@slotted/react 0.0.0-stage → 0.1.0-beta.0

package/dist/docs/image.md

@@ -0,0 +1,263 @@
+<!-- index: ./index.md -->
+# image
+
+`data-ui="image"` · Image with loading, error and fit states.
+
+## Import
+
+```tsx
+import { Image, ImageDefaultsProvider } from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<Image alt="The fjord lookout at site 12" ratio="landscape" src={site.photo} />;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div | yes |
+| `picture` | picture | no |
+| `image` | img | yes |
+| `placeholder` | span | yes |
+| `fallback` | span | yes |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `src` | `string` | — | Image | The picture. Absent, nothing is requested and the status is idle |
+| `alt` | `string` | — | Image | Required. What the picture shows, or "" for a picture that is decoration beside its own text |
+| `srcSet` | `string` | — | Image | The platform’s candidates by width or density |
+| `sizes` | `string` | — | Image | The platform’s sizes, beside srcSet |
+| `width` | `number` | — | Image | The intrinsic width; with height, reserves the ratio before the picture loads |
+| `height` | `number` | — | Image | The intrinsic height, beside width |
+| `ratio` | `'square' \| 'landscape' \| 'portrait' \| 'video' \| 'wide' \| number \| [number, number]` | — | Image | Renders an AspectRatio inside the root and lays the picture out framed |
+| `layout` | `'intrinsic' \| 'fill' \| 'framed'` | intrinsic | Image | The picture’s own size, the parent’s box, or the frame’s. A ratio implies framed unless one is stated |
+| `fit` | `'cover' \| 'contain' \| 'fill' \| 'none' \| 'scale-down'` | cover | Image | What the picture does about a box that is not its shape: object-fit |
+| `position` | `'center' \| 'top' \| 'bottom' \| 'start' \| 'end' \| string` | center | Image | The focal point a crop keeps. start and end mirror in RTL; any other value is written on the instance |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg'` | none | Image | The corner, on the radius scale |
+| `bordered` | `boolean` | false | Image | A subtle inset edge, for a photograph of a white wall on a white page |
+| `placeholder` | `'none' \| 'surface' \| 'blur'` | surface | Image | What stands under the picture before it arrives: nothing, the sunken ground, or placeholderSrc blurred |
+| `placeholderSrc` | `string` | — | Image | The small picture placeholder="blur" scales and blurs; a data URI, usually |
+| `placeholderContent` | `ReactNode` | — | Image | Content over the placeholder’s ground while the picture is on its way — a Skeleton |
+| `fallbackSrc` | `string` | — | Image | A second URL to try when src fails; error is reached only if it fails too |
+| `fallback` | `ReactNode` | — | Image | Content of the fallback in place of the glyph, once the picture has failed |
+| `sources` | `{ srcSet, media?, type?, sizes? }[]` | — | Image | The sources of a picture element, in order; the img is written last |
+| `loading` | `'lazy' \| 'eager'` | lazy | Image | The platform’s loading. priority makes it eager unless it is stated |
+| `decoding` | `'async' \| 'sync' \| 'auto'` | async | Image | The platform’s decoding |
+| `priority` | `boolean` | false | Image | The picture the page is waiting for: eager, with fetchPriority high, unless either is stated |
+| `status` | `'idle' \| 'loading' \| 'loaded' \| 'error'` | — | Image | Where the picture is. Supplied, it wins over what the family derives from the element |
+| `render` | `(props) => ReactNode` | — | Image | Substitutes the root element — an a, a button, a figure — and hands it every data attribute and the layers |
+| `renderImage` | `(props) => ReactNode` | — | Image | Renders the picture into the consumer’s own element — a Next.js Image — while the family keeps reporting the load |
+| `ref` | `Ref<HTMLImageElement>` | — | Image | Reaches the img; composed with the one the family reads the load with, never replaced |
+| `className, style` | `string, CSSProperties` | — | Image | Reach the root, because the root is what a consumer sees and sizes; every other native prop reaches the img |
+| `--slotted-image-position` | `custom property` | — | an instance | What a custom focal point writes on the root; --slotted-aspect-ratio is what a custom ratio writes on the frame |
+| `ImageDefaultsProvider` | `ImageDefaults` | — | Application | Sets layout, fit, position, radius, bordered, placeholder, loading and decoding once for everything below it; a prop still wins |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onStatusChange` | `'idle' \| 'loading' \| 'loaded' \| 'error'` | The derived status changed: loaded when the picture reported, error after the second URL failed too. Never for a status passed in. |
+| `onLoad, onError` | `SyntheticEvent<HTMLImageElement>` | The element’s own events, composed with the family’s: the consumer’s handler runs first, on every attempt. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `layout` | `intrinsic`, `fill`, `framed` | `intrinsic` |
+| `fit` | `cover`, `contain`, `fill`, `none`, `scale-down` | `cover` |
+| `position` | `center`, `top`, `bottom`, `start`, `end`, `custom` | `center` |
+| `radius` | `none`, `sm`, `md`, `lg` | `none` |
+| `placeholder` | `none`, `surface`, `blur` | `surface` |
+| `status` | `idle`, `loading`, `loaded`, `error` | — |
+
+## Rules
+
+- There is no image pattern in the WAI-ARIA Authoring Practices; the applicable guidance is the W3C WAI alt decision tree, and the family follows it by making alt required in the type: an informative picture says what it shows, a decorative one says "" and is skipped, a functional one (a link, a button) says what it does.
+- The img is never taken out of the DOM. While the picture loads it is transparent over the ground; after it fails it takes no box and the fallback takes its place — but its alt is still the name a reader hears, so a broken thumbnail is announced as what it was meant to show.
+- The placeholder is aria-hidden and the blurred preview inside it has an empty alt: neither is content. The fallback is not hidden, because a consumer may put a retry button in it, and it is out of the flow until the picture fails so that button is neither focusable nor announced before then.
+- A picture is not a control and paints nothing at rest. render can make the root an a or a button, and for exactly that case the family paints the focus ring outside the box and a 2px strong edge on hover — colour and geometry, not the photograph — and holds the hover back on a disabled button.
+- The picture crosses over the ground on --slotted-duration-short, which prefers-reduced-motion collapses to 1ms in the theme; nothing loops. Under forced colours the ground becomes Canvas, the edge ButtonBorder, and the glyph keeps currentColor; the photograph is left alone by the user agent’s own rule.
+- A caption belongs in a figcaption after the frame, and is not repeated in the alt; zoom and preview belong to Dialog, opened from a root render made a button.
+
+## Tokens
+
+`--slotted-border-strong`, `--slotted-border-subtle`, `--slotted-border-width-thick`, `--slotted-border-width-thin`, `--slotted-duration-short`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-image-background`, `--slotted-image-border-width`, `--slotted-image-fallback-min-size`, `--slotted-image-glyph-size`, `--slotted-image-placeholder-background`, `--slotted-image-placeholder-blur`, `--slotted-image-position`, `--slotted-image-radius`, `--slotted-radius-lg`, `--slotted-radius-md`, `--slotted-radius-none`, `--slotted-radius-sm`, `--slotted-space-12`, `--slotted-space-9`, `--slotted-surface-sunken`, `--slotted-text-muted`
+
+## Examples
+
+### Nothing is reserved without a decision
+
+width and height on the element reserve the ratio before the first byte, the platform’s own way; fill takes the parent’s box in both axes; a picture with neither and no ratio has no height until it reports, which is the honest answer rather than a guess.
+
+Excerpt — not a complete module
+
+```tsx
+<Image alt="The fjord lookout at site 12" height={600} src={site.photo} width={800} />;
+<Image alt="The fjord lookout at site 12" layout="fill" src={site.photo} />;
+```
+
+### A ratio decided on the image renders an AspectRatio inside its root
+
+landscape, portrait and wide frames at the column’s width, each holding its shape before the picture arrives and cropping it with fit once it has. The frame is the other family’s, composed rather than restated.
+
+Excerpt — not a complete module
+
+```tsx
+<Image alt="…" ratio="landscape" src={site.photo} />;
+<Image alt="…" ratio="portrait" src={site.photo} />;
+<Image alt="…" ratio={[2, 1]} src={site.photo} />;
+```
+
+### The five fits, in one square frame
+
+cover crops to fill; contain shows the picture whole with the ground either side; fill stretches it; none draws it at its natural size; scale-down is none unless the picture is larger than the frame.
+
+Excerpt — not a complete module
+
+```tsx
+<Image alt="…" fit="cover" ratio="square" src={site.photo} />;
+<Image alt="…" fit="contain" ratio="square" src={site.photo} />;
+```
+
+### The focal point a crop keeps
+
+A wide picture in a square frame keeps its start, its centre or its end; a portrait in a 16:9 frame keeps its top or its bottom; a CMS focal point is any object-position value. Switch the toolbar to rtl and start and end swap sides, which object-position alone does not do.
+
+Excerpt — not a complete module
+
+```tsx
+<Image alt="…" position="start" ratio="square" src={site.wide} />;
+<Image alt="…" position="top" ratio="video" src={site.portrait} />;
+<Image alt="…" position="30% 20%" ratio="video" src={site.portrait} />;
+```
+
+### Four corners and an edge
+
+radius takes the steps of the radius scale, and every layer is cut to the same corner. bordered draws border-subtle inside the box for a photograph of a white wall on a white page — and it moves nothing, because the edge is inset.
+
+Excerpt — not a complete module
+
+```tsx
+<Image alt="…" bordered radius="md" ratio="landscape" src={site.photo} />;
+```
+
+### Before the picture
+
+The sunken ground, a blurred preview from a forty-pixel version of the same picture, nothing at all, and a Skeleton the consumer put over the ground. All four are held at loading with the status prop, which wins over what the element reports.
+
+Excerpt — not a complete module
+
+```tsx
+<Image
+  alt="…"
+  placeholder="blur"
+  placeholderSrc={site.preview}
+  ratio="landscape"
+  src={site.photo}
+/>;
+<Image
+  alt="…"
+  placeholderContent={<Skeleton shape="block" />}
+  ratio="landscape"
+  src={site.photo}
+/>;
+```
+
+### After the picture failed
+
+A request to a picture that is not there: the image-off glyph on the ground in a decided frame; the same with nothing reserved, where the fallback’s own minimum is the box; and a consumer’s message and retry in place of the glyph. The fourth tile tried a second URL first and shows it.
+
+Excerpt — not a complete module
+
+```tsx
+<Image
+  alt="…"
+  fallback={<Button onClick={retry}>Retry</Button>}
+  fallbackSrc={site.archivedPhoto}
+  ratio="landscape"
+  src={site.photo}
+/>;
+```
+
+### Art direction and formats, with the platform’s picture element
+
+One source per entry, in order, and the img last: a WebP for browsers that take it, and a portrait crop when the column is narrower than 480 pixels. Resize the window past that width and the picture changes.
+
+Excerpt — not a complete module
+
+```tsx
+<Image
+  alt="…"
+  ratio="landscape"
+  sources={[
+    { srcSet: site.webp, type: 'image/webp' },
+    { media: '(max-width: 480px)', srcSet: site.portrait },
+  ]}
+  src={site.photo}
+/>;
+```
+
+### Four statuses, reported as facts
+
+idle when nothing was asked for, loading while the request is out, loaded once it answered, error after the second URL failed too. The status is derived from the element and reported through onStatusChange; a status passed in wins and is never reported.
+
+Excerpt — not a complete module
+
+```tsx
+<Image
+  alt="…"
+  onStatusChange={(status) => log(site.id, status)}
+  ratio="landscape"
+  src={site.photo}
+/>;
+```
+
+### A thumbnail that is a link, and one that is a button
+
+render puts the root on an a or a button; the family paints the focus ring outside the box and a strong edge on hover, and touches the photograph itself for neither. A picture that opens a dialog is a button, and the dialog is where the zoom lives.
+
+Excerpt — not a complete module
+
+```tsx
+<Image
+  alt="Open the photo of site 12"
+  ratio="square"
+  render={(props) => <button {...props} onClick={open} type="button" />}
+  src={site.photo}
+/>;
+```
+
+### A grid of survey sites
+
+Six cards, each with a bordered landscape thumbnail as its media: three arrived, one is still on its way, one failed, one is a portrait cropped to its top. The captions sit under the pictures because a framed image is exactly the frame’s height.
+
+Excerpt — not a complete module
+
+```tsx
+<Card>
+  <CardMedia>
+    <Image alt="" bordered ratio="landscape" src={site.photo} />
+  </CardMedia>
+  <CardHeader>{site.name}</CardHeader>
+</Card>;
+```
+
+### The alt decides what a reader hears
+
+An informative picture says what it shows; a decorative one beside its own text has alt=""; a picture that is a link says what the link does. The img is never removed, so the name holds in every status, and a caption is a figcaption rather than a repeat of the alt.
+
+Excerpt — not a complete module
+
+```tsx
+<Image alt="Rockfall debris below the red escarpment" src={finding.photo} />;
+<Image alt="" ratio="landscape" src={site.photo} />;
+<Image alt="Open the full-size photo of site 12" render={asButton} src={site.photo} />;
+```