/* page-module.figure — image/SVG with optional heading + description.

   Asset-reality style flags (describe properties of the image itself):
     - white-on-white → image has light/white baked-in background
     - dark-background → image has dark baked-in background
     - transparent-background → image has transparency
     - needs-padding → image needs breathing room (temp; resolve by re-export)

   How the figure is housed (the frame) lives on `frame` (window /
   app / browser / null), not in style. See browser-frame.css.

   $todo: themeable SVGs (--ink-primary etc.) and canvas / live HTML /
   GSAP interactive figures.
*/

page-module.figure {
	border: var(--dev-border-width) solid rgb(0 0 0 / 0.1);
	padding-inline: 0;

	.warning {
		color: var(--ink-error);
	}

	.section-heading + .figure-placeholder {
		margin-top: var(--above-block);
	}

	.figure-placeholder {
		aspect-ratio: 16 / 9;
		max-width: 1040px;
		background: var(--viz-canvas-background);
		border: 1px dashed var(--stroke-secondary);
		display: grid;
		place-items: center;
	}

	.figure-placeholder.needs-image {
		border-color: var(--ink-error);

		.quiet-voice {
			color: var(--ink-error);
		}
	}

	.section-heading + figure {
		margin-top: var(--above-block);
	}

	figure {
		display: block;
		max-width: var(--figure-max-width, 1040px);

		/* Video-clip figure: gif-replacement pattern. Autoplay-muted-loop
		   short mp4/webm hosted in the media library. Sizing mirrors the
		   image path (100% width, natural aspect); aspect-ratio reserves
		   the box before metadata loads to avoid layout shift. */
		.video-clip {
			display: block;
			width: 100%;
			aspect-ratio: 16 / 9;
			background: var(--viz-canvas-background);
		}

		@media (width < 500px) {
			&.white-on-white {
				/* Image and page share a background; borders clarify the edge. */
				border-top: 1px solid var(--stroke-secondary);
				border-bottom: 1px solid var(--stroke-secondary);
			}
		}

		@media (width >= 500px) {
			&.white-on-white {
				border: 1px solid var(--stroke-secondary);
			}
		}

		/* === BACKDROP FRAMES ===
		   on-backdrop and whiteboard render the figure as a canvas
		   behind the asset. Colors derive from base theme tokens
		   (--fill-*, --stroke-*, --ink-*) so palettes / dark-mode
		   re-skin for free.

		   Default behavior: image bleeds to canvas edges; author bakes
		   any breathing room into the PNG. Setting max_width on the
		   figure (via ACF) signals "present as a card" — figure.php
		   auto-applies .inset, which adds padding + image chrome.
		   See the INSET block below for that behavior. */
		&.frame-on-backdrop,
		&.frame-whiteboard {
			background-color: var(--fill-secondary);
			border: 1px solid var(--stroke-auxiliary);

			/* fit-content shrink-wraps to the image's natural width;
			   max-width caps at the parent so the image never overflows. */
			picture.image,
			> svg,
			.video-clip {
				display: block;
				width: fit-content;
				max-width: var(--backdrop-image-max-width, 100%);
				margin-inline: auto;
			}
		}

		/* Whiteboard layers a dot grid over the shared canvas. */
		/* $todo: grid-line variant for other themes. Some palettes
		   (e.g. graph-paper looks) read better as a fine grid. Could
		   be handled by an alternate background-image swapped in per
		   palette, or a new frame value like 'graph-paper'. */
		&.frame-whiteboard {
			background-image: radial-gradient(
				circle,
				color-mix(in oklch, var(--ink-auxiliary) 25%, transparent) 1px,
				transparent 1px
			);
			background-size: 16px 16px;
		}

		/* === INSET MODIFIER ===
		   Applied by figure.php when max_width is set on a backdrop
		   frame. All "present as a card" chrome lives here so the
		   modifier reads as one self-contained block.

		   Chrome on the image (border, shadow) skips transparent-bg
		   assets — they have no rectangular boundary, so chrome would
		   paint phantom edges around floating shapes. */
		&.inset:where(.frame-on-backdrop, .frame-whiteboard) {
			padding-block: clamp(2rem, 5vw, 5rem);
			padding-inline: clamp(1rem, 5vw, 5rem);

			&:not(.transparent-background) picture.image,
			&:not(.transparent-background) > svg,
			&:not(.transparent-background) .video-clip {
				border: 1px solid var(--stroke-secondary);
			}

			/* Shadow only on on-backdrop — whiteboard intentionally
			   stays flat (collab-board canvas — things sit on it,
			   they don't float above it). */
			&.frame-on-backdrop:not(.transparent-background) picture.image,
			&.frame-on-backdrop:not(.transparent-background) > svg,
			&.frame-on-backdrop:not(.transparent-background) .video-clip {
				box-shadow: var(--shadow);
			}
		}
	}

	/* figcaption styling lives in styles/page-module.css under the
	   shared "figure pattern" — used by figure + mermaid-chart. */

	text-content {
		margin-top: var(--below-block);
	}

	@media (width < 500px) {
		.section-heading, text-content {
			padding-inline: var(--gutter);
		}
	}

	@media (width >= 500px) {
		padding-inline: var(--gutter);
	}

	@media (width >= 1000px) {
		padding-inline: 0;
	}
}

/* Featured figure: image bleeds wide (section cols 2/-2),
   heading + description stay in the reading band (section cols 3/-3).
   Page-module subgrids from section so descendants can address its tracks. */
[data-prominence='featured'] page-module.figure {
	@media (width >= 1000px) {
		grid-column: 2 / -2;
		display: grid;
		grid-template-columns: subgrid;

		> inner-column {
			grid-column: 1 / -1;
			display: grid;
			grid-template-columns: subgrid;

			figure {
				grid-column: 1 / -1;   /* fills the featured bleed */
				max-width: 100%;
			}

			.section-heading,
			text-content {
				grid-column: 2 / -2;   /* of subgrid = section 3-15 = reading band */
			}
		}
	}
}

/* Full figure: image goes edge-to-edge (cols 1/-1),
   heading + description still pin to the reading band (3/-3).
   Same subgrid trick, just with the wider outer placement. */
[data-prominence='full'] page-module.figure {
	@media (width >= 1000px) {
		grid-column: 1 / -1;
		display: grid;
		grid-template-columns: subgrid;

		padding-block: calc(var(--module-block-padding) * 2);

		> inner-column {
			grid-column: 1 / -1;
			display: grid;
			grid-template-columns: subgrid;

			figure {
				grid-column: 1 / -1;   /* full bleed */
				max-width: 100%;
			}

			.section-heading,
			text-content {
				grid-column: 3 / -3;   /* reading band */
			}
		}
	}
}