@slotted/angular 0.0.0-stage → 0.1.0-beta.1

package/docs/image.md

@@ -0,0 +1,254 @@
+<!-- index: ./index.md -->
+# image
+
+`data-ui="image"` · Image with loading, error and fit states.
+
+## Import
+
+```ts
+import { SlImage, SlImageMedia, SlImageFallback, SlImagePlaceholder, provideImageDefaults } from '@slotted/angular/image';
+```
+
+Selector: `[slImage]` · exportAs: `slImage`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div slImage alt="The fjord lookout at site 12" ratio="landscape" [src]="site.photo"></div>
+```
+
+## 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 | What the picture shows, or "" for a picture that is decoration beside its own text. Written on the component’s own img; a projected img carries its own |
+| `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 |
+| `[slImagePlaceholder]` | `projected content` | — | Image | Content over the placeholder’s ground while the picture is on its way — an slSkeleton |
+| `fallbackSrc` | `string` | — | Image | A second URL to try when src fails, on the component’s own img; error is reached only if it fails too |
+| `[slImageFallback]` | `projected content` | — | 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 |
+| `[slImage]` | `attribute selector` | — | your element | The component attaches to the element you wrote — a div, an a, a button, a figure — and it stays yours |
+| `img[slImageMedia]` | `directive on your img` | — | a projected img | The picture in the consumer’s own element — the one ngSrc and NgOptimizedImage belong on — while the family keeps reading the load |
+| `exportAs slImage, slImageMedia` | `template reference` | — | SlImage, SlImageMedia | Reaches the instance from a template |
+| `class, style` | `attributes` | — | your element | Stay on the host, which is the root; the component writes only data attributes and one custom property beside them |
+| `--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 |
+| `provideImageDefaults` | `ImageDefaults` | — | Application | Sets layout, fit, position, radius, bordered, placeholder, loading and decoding once for an injector; an input still wins |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `(statusChange)` | `'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. |
+| `(load), (error) on img[slImageMedia]` | `Event` | The element’s own events, on the img the consumer projected; the family listens beside the consumer and replaces nothing. |
+
+## 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 writing the alt on its own img and leaving a projected img’s alone: 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. The component attaches to 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 host that is 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
+
+```html
+<div slImage alt="The fjord lookout at site 12" width="800" height="600" [src]="site.photo"></div>
+<div slImage alt="The fjord lookout at site 12" layout="fill" [src]="site.photo"></div>
+```
+
+### 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
+
+```html
+<div slImage alt="…" ratio="landscape" [src]="site.photo"></div>
+<div slImage alt="…" ratio="portrait" [src]="site.photo"></div>
+<div slImage alt="…" [ratio]="[2, 1]" [src]="site.photo"></div>
+```
+
+### 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
+
+```html
+<div slImage alt="…" fit="cover" ratio="square" [src]="site.photo"></div>
+<div slImage alt="…" fit="contain" ratio="square" [src]="site.photo"></div>
+```
+
+### 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
+
+```html
+<div slImage alt="…" position="start" ratio="square" [src]="site.wide"></div>
+<div slImage alt="…" position="top" ratio="video" [src]="site.portrait"></div>
+<div slImage alt="…" position="30% 20%" ratio="video" [src]="site.portrait"></div>
+```
+
+### 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
+
+```html
+<div slImage alt="…" bordered radius="md" ratio="landscape" [src]="site.photo"></div>
+```
+
+### 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
+
+```html
+<div
+  slImage
+  alt="…"
+  placeholder="blur"
+  ratio="landscape"
+  [placeholderSrc]="site.preview"
+  [src]="site.photo"
+></div>
+<div slImage alt="…" ratio="landscape" [src]="site.photo">
+  <span slImagePlaceholder slSkeleton shape="block"></span>
+</div>
+```
+
+### 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
+
+```html
+<div slImage alt="…" ratio="landscape" [fallbackSrc]="site.archivedPhoto" [src]="site.photo">
+  <button slImageFallback slButton type="button" (click)="retry()">Retry</button>
+</div>
+```
+
+### 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
+
+```html
+<div slImage alt="…" ratio="landscape" [sources]="sources" [src]="site.photo"></div>
+```
+
+### 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
+
+```html
+<div
+  slImage
+  alt="…"
+  ratio="landscape"
+  [src]="site.photo"
+  (statusChange)="log(site.id, $event)"
+></div>
+```
+
+### 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
+
+```html
+<button
+  slImage
+  type="button"
+  alt="Open the photo of site 12"
+  ratio="square"
+  [src]="site.photo"
+  (click)="open()"
+></button>
+```
+
+### 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
+
+```html
+<article slCard>
+  <div slCardMedia>
+    <div slImage alt="" bordered ratio="landscape" [src]="site.photo"></div>
+  </div>
+  <div slCardHeader>{{ site.name }}</div>
+</article>
+```
+
+### 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
+
+```html
+<div slImage alt="Rockfall debris below the red escarpment" [src]="finding.photo"></div>
+<div slImage alt="" ratio="landscape" [src]="site.photo"></div>
+<button slImage type="button" alt="Open the full-size photo of site 12" [src]="site.photo"></button>
+```