@atelic-action/ui 3.7.0 → 3.8.0

package/README.md

@@ -39,7 +39,7 @@ Every export, grouped by the entry it is imported from. The gallery column links
 | `Button`, `Chip`, `Eyebrow`, `Lead`, `SectionHeading` | `@atelic-action/ui/primitives` | The small pieces a page is set in | [#primitives](https://ui.atelic.me/#primitives) |
 | `GradeChip`, `gradeLabel`, `WriteupGrade` | `@atelic-action/ui/artifact` | A section's grade, A to D, as a chip in its color, the letter alone, and the grade type | [#grade-chip](https://ui.atelic.me/#grade-chip) |
 | `SignOff`, `WriteupPerson` | `@atelic-action/ui/artifact` | The close a document ends on, and the person it names | [#sign-off](https://ui.atelic.me/#sign-off) |
-| `Shot`, `WriteupShot` | `@atelic-action/ui/artifact` | The owner's own screen, opening the full picture, over its caption | [#shot](https://ui.atelic.me/#shot) |
+| `Shot`, `WriteupShot` | `@atelic-action/ui/artifact` | The owner's own screen, opening the full picture, over its caption; a portrait crop is marked `data-portrait` and held to 200px (1.8in in print) | [#shot](https://ui.atelic.me/#shot) |
 | `Paragraph`, `Runs`, `ArtifactAnchor`, `isEmpty`, `ArtifactLink`, `ArtifactParagraph` | `@atelic-action/ui/artifact` | Plain data text a routine can write as JSON: a paragraph, its runs alone, one link, the empty test, and the two types | [#paragraph](https://ui.atelic.me/#paragraph) |
 | `ArtifactShell` | `@atelic-action/ui/artifact` | The chrome around a document page: skip link, dark header, credit band, watermark | [#site-header](https://ui.atelic.me/#site-header) (its dark bar) |
 | `AppErrorBoundary`, `ErrorFallback` | `@atelic-action/ui/artifact` | The error boundary and the page it falls back to | none |
@@ -338,7 +338,7 @@ The two pieces a reader sees are ordinary components, in `@atelic-action/ui/comp
 
 `@atelic-action/ui/artifact` is the pieces an artifact document is built from and the site around it, so a fix to a piece reaches every business's documents with one version bump. The composed documents themselves (`Writeup`, `Read`, `Report`, `Note`, and the sealed `Gate`, with their content types and their stylesheet) live in [`@atelic-action/artifact`](https://github.com/atelic-action/artifact) since 2.0.0, which depends on this package for everything below:
 
-- **The pieces:** `GradeChip` and `gradeLabel` with the `WriteupGrade` type, `SignOff` with the `WriteupPerson` type, `Shot` with the `WriteupShot` type, and the plain data text (`Paragraph`, `Runs`, `ArtifactAnchor`, and `isEmpty`, with the `ArtifactLink` and `ArtifactParagraph` types: a paragraph is a string or runs of text and `{ text, href }` links, so a routine can write a document as JSON).
+- **The pieces:** `GradeChip` and `gradeLabel` with the `WriteupGrade` type, `SignOff` with the `WriteupPerson` type, `Shot` with the `WriteupShot` type (a crop taller than it is wide is measured in the browser, marked `data-portrait`, and held to 200px wide on screen and 1.8in in print; a layout that sizes its shots itself sets `--op-shot-portrait-max: none` to opt out, on screen and in print alike), and the plain data text (`Paragraph`, `Runs`, `ArtifactAnchor`, and `isEmpty`, with the `ArtifactLink` and `ArtifactParagraph` types: a paragraph is a string or runs of text and `{ text, href }` links, so a routine can write a document as JSON).
 - **The shell:** `ArtifactShell`, the `.atelic-ui` scope with the skip link, the dark header, the credit band, and the watermark around a page.
 - **The contract and the head:** the `ArtifactConfig` types, and `buildPageHead` and `canonicalURL` with their `PageMeta` type.
 - **Who opened it:** `mintToken`, `sealReader`, `openReader`, `readerId`, `readerLink`, and `whoIsReading`. The same six are also built and exported alone as `@atelic-action/ui/artifact/readers`, because a Playwright spec and a script run under Node, which compiles nothing inside `node_modules`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atelic-action/ui",
-	"version": "3.7.0",
+	"version": "3.8.0",
 	"description": "Shared UI for the Atelic templates: site chrome, base styles, the component library, the access gate, and the app shell they install",
 	"type": "module",
 	"license": "UNLICENSED",

package/src/artifact/Shot.tsx

@@ -1,4 +1,5 @@
 import { Maximize2 } from "lucide-react";
+import { useEffect, useRef, useState } from "react";
 import { newTabProps } from "../lib/newTabProps";
 
 export interface WriteupShot {
@@ -10,6 +11,12 @@ export interface WriteupShot {
 	caption: string;
 }
 
+/** The src of a loaded image taller than it is wide; null for any other. */
+function portraitSrcOf(img: HTMLImageElement): string | null {
+	if (!img.naturalWidth || !img.naturalHeight) return null;
+	return img.naturalHeight > img.naturalWidth ? img.getAttribute("src") : null;
+}
+
 /**
  * The owner's own screen: the crop, opening the full screenshot in a new tab
  * when it has one, over its caption. The writeup, the read, and the note in
@@ -18,21 +25,50 @@ export interface WriteupShot {
  * own sheet. A linked crop says it opens: a hover title, and an expand badge
  * hidden by default that a document may turn on (the note does, on its
  * thumbnails).
+ *
+ * A crop taller than it is wide (a phone screen) marks the figure
+ * `data-portrait`, and the base sheet holds it far narrower than its column.
+ * The mark is measured in the browser, after the image has a size: on load,
+ * or in an effect when the image finished loading before hydration, so the
+ * prerendered page carries no mark and nothing reads the window at render.
  */
 export function Shot({ shot }: { shot: WriteupShot }) {
+	const img = useRef<HTMLImageElement>(null);
+	// The src the portrait mark was measured on, so a new src never wears the
+	// last image's mark while it loads or if it fails.
+	const [portraitSrc, setPortraitSrc] = useState<string | null>(null);
+	const portrait = portraitSrc !== null && portraitSrc === shot.src;
+
+	// An image that loaded before hydration fired its load event before React
+	// was listening, so read its size once on mount. A later src change fires
+	// load again, which the handler below measures.
+	useEffect(() => {
+		const current = img.current;
+		if (current?.complete) setPortraitSrc(portraitSrcOf(current));
+	}, []);
+
+	const picture = (
+		<img
+			ref={img}
+			src={shot.src}
+			alt={shot.alt}
+			loading="lazy"
+			onLoad={(event) => setPortraitSrc(portraitSrcOf(event.currentTarget))}
+			onError={() => setPortraitSrc(null)}
+		/>
+	);
+
 	return (
-		<figure className="op-shot">
+		<figure className="op-shot" data-portrait={portrait ? "" : undefined}>
 			{shot.href ? (
 				<a href={shot.href} title="Open the full picture" {...newTabProps(shot.href, true)}>
-					<img src={shot.src} alt={shot.alt} loading="lazy" />
+					{picture}
 					<span className="op-shot-open" aria-hidden="true">
 						<Maximize2 size={12} />
 					</span>
 				</a>
 			) : (
-				<span className="op-shot-frame">
-					<img src={shot.src} alt={shot.alt} loading="lazy" />
-				</span>
+				<span className="op-shot-frame">{picture}</span>
 			)}
 			<figcaption>{shot.caption}</figcaption>
 		</figure>

package/src/styles/artifact.css

@@ -109,10 +109,24 @@
 		line-height: 1.45;
 		color: var(--op-ink-faint, var(--neutral-500));
 	}
+	/* A portrait crop (a phone screen, marked by Shot once its image has a
+	   size) is held far narrower than its column, at the column's start, so
+	   it never stands as a tall wall beside its findings. The cap is on the
+	   figure, so the frame, its border, and the caption all hug the picture.
+	   A layout that sizes its shots itself (fixed frames side by side) sets
+	   --op-shot-portrait-max to none to keep them all the same size. The one
+	   property governs print as well; a document that sets a size of its own
+	   restates it under @media print for the sheet. */
+	.atelic-ui .op-shot[data-portrait] {
+		max-width: var(--op-shot-portrait-max, 200px);
+	}
 	@media print {
 		.atelic-ui .op-shot a {
 			cursor: auto;
 		}
+		.atelic-ui .op-shot[data-portrait] {
+			max-width: var(--op-shot-portrait-max, 1.8in);
+		}
 	}
 
 	/* ---- print: the shell's chrome steps aside on every artifact page ----