@junoput01/junoui 0.3.0 → 0.4.0

package/docs/components/load-state.md

@@ -0,0 +1,131 @@
+# Load state
+
+A vocabulary for every way a load can go, so nothing spins forever. junoui already had
+"resolving" (arc/beacon/bar, both indeterminate and determinate) and "layout known, not
+loaded yet" ([skeleton](./skeleton.md)). This adds the two treatments those don't cover —
+**working with no ETA** and **failed** — plus a table-agnostic **empty** state and an
+optional CSS-only switch to show exactly one at a time. Zero JS: junoui ships the look and
+the ARIA contract per state; deciding _when_ a load becomes a fault or an empty result is
+the app's job.
+
+## The decision table
+
+| State                           | Treatment                 | Why                                                          |
+| ------------------------------- | ------------------------- | ------------------------------------------------------------ |
+| No data yet, about to fetch     | `.juno-beacon`            | "no bytes yet" — a pulse, not a promise of progress.         |
+| Fetching, will resolve          | `.juno-arc` / `.juno-bar` | Real progress or a bounded wait — see [loader](./loader.md). |
+| Layout known, content pending   | `.juno-skeleton`          | Placeholder mirrors the shape of what's coming.              |
+| Server working, **no ETA**      | `.juno-shimmer`           | Motion _without_ a completion promise.                       |
+| Failed — **terminal**           | `.juno-fault`             | Static. A spinner on a 404 spins forever.                    |
+| Legitimately nothing — terminal | `.juno-empty`             | Static. Not a failure — don't tint it like one.              |
+
+`.juno-shimmer` and `.juno-fault` are the two treatments this ticket adds; `.juno-empty` is
+the generalized, table-agnostic form of the existing `.juno-table__empty` (same anatomy,
+usable outside a table).
+
+## Web
+
+### Shimmer — work in progress, no completion promise
+
+```html
+<div class="juno-shimmer" style="block-size: 120px;" aria-busy="true" aria-live="polite"></div>
+```
+
+Shares `.juno-skeleton`'s compositor-only band (same `@keyframes juno-skeleton-shimmer`,
+defined once in `skeleton.css`) — one shimmer implementation, applied to a solid fill
+instead of a placeholder shape. Override cadence with `--juno-shimmer-dur` (default
+`1.4s`).
+
+### Fault — terminal, never animates
+
+```html
+<div class="juno-fault" role="status">
+  <span class="juno-fault__icon" aria-hidden="true">!</span>
+  <p>Couldn't load this image.</p>
+</div>
+```
+
+Role defaults to `caution`; add a `.juno--<role>` class to recolor (`.juno--warning` for a
+harder failure) — never hardcode a color. `role="status"` on the fault itself is a
+per-region, polite announcement (this fired once, doesn't need to interrupt); for a
+page-level urgent message use [`.juno-alert`](./alert.md) with `role="alert"` instead.
+
+### Empty — legitimately nothing, terminal
+
+```html
+<div class="juno-empty">
+  <span class="juno-empty__icon" aria-hidden="true">∅</span>
+  <p>Nothing here yet.</p>
+</div>
+```
+
+### The switch (optional)
+
+CSS-only, one visible child at a time. The app sets `data-juno-state` on the parent as
+its fetch/rendition state changes; junoui does no state inference.
+
+```html
+<div class="juno-state" data-juno-state="processing">
+  <div data-juno-when="loading">
+    <div class="juno-arc juno-arc--indeterminate" role="status" aria-label="Loading"></div>
+  </div>
+  <div data-juno-when="processing" aria-busy="true" aria-live="polite">
+    <div class="juno-shimmer" style="block-size: 120px;"></div>
+  </div>
+  <div data-juno-when="error">
+    <div class="juno-fault" role="status">
+      <span class="juno-fault__icon" aria-hidden="true">!</span>
+      <p>Couldn't load this.</p>
+    </div>
+  </div>
+  <div data-juno-when="empty">
+    <div class="juno-empty">
+      <span class="juno-empty__icon" aria-hidden="true">∅</span>
+      <p>Nothing here yet.</p>
+    </div>
+  </div>
+</div>
+```
+
+| Class / attribute                   | Effect                                                                                                        |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `.juno-state`                       | Switch container.                                                                                             |
+| `[data-juno-when]`                  | A wrapper hidden by default; shown when its (space-separated) token list contains the parent's current state. |
+| `.juno-state[data-juno-state='…']`  | Set by the app: `loading` \| `processing` \| `error` \| `empty`.                                              |
+| `.juno-shimmer`                     | Compositor-only shimmer band on a solid fill (shares skeleton's `@keyframes`).                                |
+| `--juno-shimmer-dur`                | Shimmer cycle length (default `1.4s`).                                                                        |
+| `.juno-fault` / `.juno-fault__icon` | Terminal failure card. Role `caution` by default.                                                             |
+| `.juno-empty` / `.juno-empty__icon` | Terminal empty-result card. Neutral (`label`/`muted`), same anatomy as `.juno-table__empty`.                  |
+
+## Anatomy (any platform)
+
+- Shimmer: solid `s2` fill, `s3` highlight band at 70% opacity sliding on `transform`
+  only, 1.4s ease-in-out loop — identical mechanism to skeleton, different semantic use.
+- Fault: column, centered, `space.8` gap, `space.24` padding, role-colored text and icon
+  outline (`radius.8` box, `border.width.1`). Never animates.
+- Empty: column, centered, `space.12` gap, `space.56`/`space.24` padding, `label`/`muted`
+  text and icon outline (`radius.8` box). Never animates.
+
+## Usage
+
+- **Shimmer vs. skeleton:** skeleton implies a known layout waiting for content (first
+  paint); shimmer implies ongoing server-side work with no bound on when it finishes
+  (transcoding, indexing, re-encoding). Don't use skeleton for the latter — the moment a
+  skeleton is on screen, the layout it promises should be about to land.
+  Reference: `web/src/media/loadview.ts` (nexora) — spinner only while nothing has
+  started, shimmer for `processing`, static fault for `error`; "a spinner on a 404 spins
+  forever."
+- **Fault vs. alert:** a fault is a _region_ replacing content that failed to load
+  (an image tile, a card). An [alert](./alert.md) is a page-level message. Don't reach for
+  `.juno-alert` inside a grid cell.
+- **Empty is not a failure:** legitimately-zero-results (an empty search, a fresh account)
+  is a distinct terminal state from an error — keep it neutral, offer a next action
+  (a button/link) rather than an apology.
+- **The switch is optional.** Nothing stops rendering `.juno-shimmer` / `.juno-fault` /
+  `.juno-empty` directly and swapping them with app-side conditional rendering; `.juno-state`
+  exists for markup that's easier to keep all-present (e.g. server-rendered) and toggle
+  by attribute.
+- **a11y, per state:** `loading`/`processing` → `aria-busy="true"` (+ `aria-live="polite"`
+  if the region isn't otherwise announced); `.juno-fault` → `role="status"` on itself;
+  `.juno-empty` → no extra role, it's static content. See
+  [accessibility.md](../accessibility.md) for the full per-component ARIA contract.

package/docs/components/loader.md

@@ -26,15 +26,23 @@ Color comes from `--juno-role` (default `active`); add a `.juno--<role>` class t
 </div>
 ```
 
-| Class / var                                         | Effect                                                           |
-| --------------------------------------------------- | ---------------------------------------------------------------- |
-| `.juno-arc`                                         | Ring; determinate sweep = progress (conic gradient + ring mask). |
-| `.juno-arc--indeterminate`                          | 12-step mechanical rotation.                                     |
-| `--juno-arc-size` (76px) · `--juno-arc-width` (4px) | Diameter / stroke.                                               |
+| Class / var                                         | Effect                                                                                                                               |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `.juno-arc`                                         | Ring; determinate sweep = progress (conic gradient + ring mask).                                                                     |
+| `.juno-arc--indeterminate`                          | 12-step mechanical rotation.                                                                                                         |
+| `.juno-arc--smooth`                                 | With `--indeterminate`: continuous (linear) rotation instead of the 12-step sweep — use under ~24px, where the steps read as jitter. |
+| `--juno-arc-size` (76px) · `--juno-arc-width` (4px) | Diameter / stroke.                                                                                                                   |
 
 > The ring uses a CSS mask, which clips children. Put `.juno-arc__label` as a
 > **sibling** over a positioned wrapper, not inside `.juno-arc`.
 
+> To ring an _arbitrary control_ (a button, a badge, an avatar) without
+> changing its own box, don't reposition `.juno-arc` by hand — compose
+> [`.juno-icon-loader`](./icon-loader.md), junoui's one ring-a-thing
+> primitive. It stacks the arc and the control on a single grid cell sized
+> off two custom props, so nothing you wrap ever resizes when the ring
+> appears.
+
 ## Beacon — radiating pulse
 
 ```html

package/docs/components/pillbar.md

@@ -23,16 +23,161 @@ optional divider. Zero JS.
 </nav>
 ```
 
-| Class / prop           | Effect                                                                                                                                             |
-| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `.juno-pillbar`        | Sticky floating pill: blurred translucent `s1`, hairline, `shadow.2`.                                                                              |
-| `.juno-pillbar__item`  | Round tap target ≥ `size.tap.comfortable`; icon with optional label.                                                                               |
-| `.juno-pillbar__label` | Inline text next to the icon — truncates at 12ch.                                                                                                  |
-| `.juno-pillbar__sep`   | Vertical hairline between item groups (e.g. destinations vs. actions).                                                                             |
-| `[aria-current]`       | Active destination: `s3` pill fill + role color. Attribute, not class.                                                                             |
-| `[aria-pressed]`       | Same active look for toggle buttons.                                                                                                               |
-| `.juno-pillbar--fixed` | Fix to the viewport (`position: fixed`), floating its usual `space.16` + safe-area above the foot — for page-scroll shells where sticky won't pin. |
-| `.juno--<role>`        | Active color (default `active`).                                                                                                                   |
+| Class / prop                                                                   | Effect                                                                                                                                             |
+| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.juno-pillbar`                                                                | Sticky floating pill: blurred translucent `s1`, hairline, `shadow.2`.                                                                              |
+| `.juno-pillbar__item`                                                          | Round tap target ≥ `size.tap.comfortable`; icon with optional label.                                                                               |
+| `.juno-pillbar__label`                                                         | Inline text next to the icon — truncates at 12ch.                                                                                                  |
+| `.juno-pillbar__sep`                                                           | Vertical hairline between item groups (e.g. destinations vs. actions).                                                                             |
+| `[aria-current]`                                                               | Active destination: `s3` pill fill + role color. Attribute, not class.                                                                             |
+| `[aria-pressed]`                                                               | Same active look for toggle buttons.                                                                                                               |
+| `.juno-pillbar--fixed`                                                         | Fix to the viewport (`position: fixed`), floating its usual `space.16` + safe-area above the foot — for page-scroll shells where sticky won't pin. |
+| `.juno-pillbar--top-right` / `--top-left` / `--bottom-right` / `--bottom-left` | Fix as a floating cluster in one viewport corner (safe-area-clamped), instead of the centered bottom bar.                                          |
+| `.juno-pillbar__input`                                                         | Borderless search field inside the pill (`min(52vw, 240px)`, 16px font floor).                                                                     |
+| `.juno-pillbar__overflow`                                                      | "More" trigger for items that don't fit — anchors a [menu](./menu.md) via `popovertarget`.                                                         |
+| `.juno-pillbar--collapsible`                                                   | The pill folds into a single circle (`__toggle`) and animates back to full width — see [Collapsible](#collapsible).                                |
+| `.juno-pillbar__toggle`                                                        | The collapsible pill's circular expand/collapse control; state on `aria-expanded`, same chrome as `__overflow`.                                    |
+| `.juno-pillbar__tray`                                                          | Wrapper whose width animates shut — holds one child wrapping the usual `__item` markup.                                                            |
+| `.juno--<role>`                                                                | Active color (default `active`).                                                                                                                   |
+
+### Geometry custom props
+
+Read from `.juno-pillbar` (or its computed style) instead of hardcoding these
+in an app-side capacity planner — they're the single source of truth for how
+many `__item` fit before the rest should route to `__overflow`.
+
+| Prop                  | Default                | Meaning                                                                                                                                               |
+| --------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--juno-pillbar-item` | `size.tap.comfortable` | Item tap-target side (square).                                                                                                                        |
+| `--juno-pillbar-gap`  | `space.2`              | Gap between items.                                                                                                                                    |
+| `--juno-pillbar-pad`  | `space.4`              | Pill's own inner padding.                                                                                                                             |
+| `--juno-pillbar-edge` | `space.16`             | Base (bottom-center) placement's offset from the viewport edge. Not used by the corner modifiers, which keep their own distinct block/inline offsets. |
+
+## Corner placement
+
+The base pillbar is a centered bottom bar. The corner modifiers pin it as a
+floating cluster in one viewport corner instead — e.g. a top-right
+search/filter cluster over a full-bleed grid. Each flips to `position: fixed`
+and clamps the corner with `env(safe-area-inset-*)` so it never lands under a
+notch or the home indicator; the base blur/border/shadow carries over. For the
+bottom corners, reserve scroll clearance with
+`padding-block-end: var(--juno-pillbar-clearance)` if the pill overlaps
+content.
+
+## Input slot
+
+`.juno-pillbar__input` is an expandable search field that lives inside the
+pill, reading as part of it rather than a boxed control.
+
+```html
+<div class="juno-pillbar juno-pillbar--top-right">
+  <input
+    class="juno-pillbar__input"
+    type="search"
+    aria-label="Search library"
+    placeholder="Search…"
+  />
+  <button class="juno-pillbar__item" aria-label="Search" aria-pressed="true">
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-magnifying-glass" /></svg>
+  </button>
+</div>
+```
+
+- The field is borderless/transparent; its font-size is held at
+  `max(16px, …)` because iOS Safari zooms the whole page onto any focused text
+  field under 16px (the same floor the base [input](./input.md) applies on
+  touch).
+- **A placeholder is not a label** — give the input an `aria-label` or a
+  visually-hidden `<label>`.
+
+## Overflow slot
+
+`.juno-pillbar__overflow` is a "more" trigger, styled like `__item`, for
+pills with variable membership (e.g. a top-right action pill whose item count
+depends on the current view). It opens a [`.juno-menu`](./menu.md) holding
+whatever didn't fit — zero JS, via the native Popover API:
+
+```html
+<div class="juno-pillbar juno-pillbar--top-right">
+  <button class="juno-pillbar__item" aria-label="Search" aria-pressed="true">
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-magnifying-glass" /></svg>
+  </button>
+  <button class="juno-pillbar__item" aria-label="Filter">
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-funnel" /></svg>
+  </button>
+  <button
+    class="juno-pillbar__overflow"
+    popovertarget="pillbar-more"
+    aria-haspopup="menu"
+    aria-expanded="false"
+    aria-label="More"
+  >
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-dots-three" /></svg>
+  </button>
+</div>
+<ul class="juno-menu" id="pillbar-more" popover role="menu">
+  <li>
+    <button
+      class="juno-menu__item"
+      role="menuitem"
+      popovertarget="pillbar-more"
+      popovertargetaction="hide"
+    >
+      <span class="juno-menu__icon">⤓</span>Export
+    </button>
+  </li>
+</ul>
+```
+
+- **junoui ships the docking point, not the collapse policy.** Deciding
+  _which_ items overflow and _when_ is the app's job — read the
+  [geometry custom props](#geometry-custom-props) to do the capacity math,
+  then conditionally render `.juno-pillbar__overflow` and move the spilled
+  `__item`s into the menu. This keeps one source of truth for the pixel
+  constants instead of an app re-declaring them in JS.
+- The invoker (`popovertarget`) is the menu's implicit anchor, so
+  `.juno-menu`'s own `position-try-fallbacks` handles flipping it clear of the
+  viewport edge — no extra positioning needed in the pill.
+- `aria-expanded` mirrors the menu's open state like `[aria-pressed]` does for
+  toggle items; toggle it from the app or a stateless enhancer (junoui itself
+  ships no JS).
+
+## Collapsible
+
+`.juno-pillbar--collapsible` lets the whole pill fold into a single circular
+button and expand back to full width on demand — for toolbars that should get
+out of the content's way (e.g. a media viewer's action bar). State lives on
+the toggle's `aria-expanded`; junoui ships no JS, the app flips the attribute.
+
+```html
+<nav class="juno-pillbar juno-pillbar--collapsible" aria-label="Tools">
+  <button class="juno-pillbar__toggle" aria-expanded="false" aria-label="Show toolbar">
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-dots-three" /></svg>
+  </button>
+  <div class="juno-pillbar__tray">
+    <div>
+      <button class="juno-pillbar__item" aria-label="Share">…</button>
+      <span class="juno-pillbar__sep"></span>
+      <button class="juno-pillbar__item" aria-label="Delete">…</button>
+    </div>
+  </div>
+</nav>
+```
+
+- **The tray needs exactly one child wrapper** (any element). The expansion is
+  a `grid-template-columns: 0fr ↔ 1fr` transition — the only widely-supported
+  way to animate to an intrinsic width (Safari 16+) — and the track needs a
+  single shrinkable child to collapse.
+- DOM order is free: toggle-first reads naturally for a left-anchored pill,
+  toggle-last for a right-anchored corner (`--bottom-right`), so the circle
+  stays put and the tray grows out of it.
+- Collapsed, the tray goes `visibility: hidden` at the end of the slide, which
+  also removes its items from the tab order. **Collapsing while focus is
+  inside the tray is the app's edge:** move focus to the toggle first.
+- The toggle's glyph rotates a quarter-turn while expanded; swap the icon from
+  the app instead if you want e.g. dots → ×.
+- `prefers-reduced-motion` is handled by the base layer (every transition
+  collapses to ~0ms) — the states still apply, just without the slide.
 
 ## Anatomy (any platform)
 
@@ -47,6 +192,8 @@ optional divider. Zero JS.
 
 - Same rules as the dock: 3–5 destinations, overflow goes behind a "More" item.
   Pick **one** bottom pattern per screen — dock _or_ pillbar, never both.
+- Variable-membership action pills (not fixed destinations) use the
+  [overflow slot](#overflow-slot) instead of hand-rolling a "more" menu.
 - Sticky, not fixed: place it last inside the scrolling column; it floats over
   content while staying in flow. Best inside the
   [`.juno-app-shell`](../layout.md#app-shell) frame, whose `__main` is the

package/docs/components/reload.md

@@ -0,0 +1,41 @@
+# Reload
+
+The non-blocking counterpart to the [skeleton](./skeleton.md). A skeleton
+stands in for content that isn't there yet (first paint); the reload indicator
+signals a refresh happening _over_ content that's already on screen — the stale
+data stays readable and interactive while fresh data lands.
+
+It's a small pulsing dot with a soft halo, centered as a fixed overlay that
+eats no pointer events, so the page underneath stays fully usable.
+
+## Web
+
+```html
+<div class="juno-reload" role="status" aria-label="Reloading">
+  <span class="juno-reload__dot"></span>
+</div>
+```
+
+| Class / prop        | Effect                                                              |
+| ------------------- | ------------------------------------------------------------------- |
+| `.juno-reload`      | Fixed, centered, `pointer-events: none` overlay.                    |
+| `.juno-reload__dot` | `space.16` role-colored dot with a soft halo, gentle opacity pulse. |
+| `.juno--<role>`     | Dot color (default `active`).                                       |
+
+## Usage
+
+- Render it while a **background refetch is in flight over existing content**;
+  drop it when the request settles. For first-paint (no content yet) use the
+  [skeleton](./skeleton.md) instead.
+- The app owns the state (zero JS in the component) — mount/unmount it, or
+  toggle a `hidden` attribute.
+- The pulse uses the shared `juno-pulse` keyframe — a soft dim, not a full
+  blink. `prefers-reduced-motion` stops the pulse (via the base layer); the
+  dot stays visible so the "refreshing" state is still conveyed.
+
+## Accessibility
+
+- `role="status"` + `aria-label` announces the refresh **politely**, without
+  stealing focus — it's a status, not an alert. Don't use `role="alert"`.
+- Keep it non-blocking: `pointer-events: none` ensures it never traps clicks on
+  the content it floats over.

package/docs/components/skeleton.md

@@ -1,8 +1,9 @@
 # Skeleton
 
 A shimmering placeholder that stands in for content not yet loaded — same shimmer as
-the [table](./table.md) row skeleton, generalized to text lines, blocks, and circles.
-Zero JS; honors `prefers-reduced-motion` (shimmer → static).
+the [table](./table.md) row skeleton, generalized to text lines, blocks, circles, and
+aspect-ratio tiles. Zero JS; honors `prefers-reduced-motion` (shimmer → static) via the
+global motion contract.
 
 ## Web
 
@@ -12,27 +13,33 @@ Zero JS; honors `prefers-reduced-motion` (shimmer → static).
   <span class="juno-skeleton juno-skeleton--text" style="inline-size: 60%"></span>
   <span class="juno-skeleton juno-skeleton--text"></span>
   <span class="juno-skeleton juno-skeleton--block"></span>
+  <span class="juno-skeleton juno-skeleton--tile"></span>
 </div>
 ```
 
-| Class                    | Effect                                                           |
-| ------------------------ | ---------------------------------------------------------------- |
-| `.juno-skeleton`         | Shimmering bar; height `--juno-skeleton-h` (default `space.16`). |
-| `.juno-skeleton--text`   | One text line (`1em` tall, soft radius).                         |
-| `.juno-skeleton--circle` | Round avatar / icon placeholder (square via the height).         |
-| `.juno-skeleton--block`  | Larger surface (card / media), `space.56` tall.                  |
-| `--juno-skeleton-h`      | Override the height (any length).                                |
+| Class                    | Effect                                                                                                                                                 |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `.juno-skeleton`         | Shimmering bar; height `--juno-skeleton-h` (default `space.16`).                                                                                       |
+| `.juno-skeleton--text`   | One text line (`1em` tall, soft radius).                                                                                                               |
+| `.juno-skeleton--circle` | Round avatar / icon placeholder (square via the height).                                                                                               |
+| `.juno-skeleton--block`  | Larger surface (card / media), `space.56` tall.                                                                                                        |
+| `.juno-skeleton--tile`   | Content-box mode: sized by `--juno-skeleton-ratio` instead of a fixed height — the media-grid case (a tile matching a real image/card's aspect ratio). |
+| `--juno-skeleton-h`      | Override the height (any length).                                                                                                                      |
+| `--juno-skeleton-ratio`  | `.juno-skeleton--tile` only — the aspect ratio (default `1`, e.g. `16 / 9`).                                                                           |
 
 ## Usage
 
 - Wrap the loading region in `aria-busy="true"` (and `aria-live="polite"`) so assistive
   tech announces the pending state; swap in the real content when it arrives.
-- Mirror the **shape** of the content it replaces — line widths, an avatar circle — so
-  the layout doesn't jump on load.
-- Width is layout-driven: set `inline-size` (e.g. `60%`) per line; height via the variant
-  or `--juno-skeleton-h`.
+- Mirror the **shape** of the content it replaces — line widths, an avatar circle, a
+  tile's aspect ratio — so the layout doesn't jump on load.
+- Width is layout-driven: set `inline-size` (e.g. `60%`) per line; height via the variant,
+  `--juno-skeleton-h`, or (for `--tile`) `--juno-skeleton-ratio`.
 
 ## Anatomy (any platform)
 
-- `s2`→`s3`→`s2` horizontal gradient, `background-size: 200%`, animated 1.2s ease-in-out
-  loop. Radius `3` (block `4`, text `2`). Static fill under reduced-motion.
+- Solid `s2` fill; the shimmer is a separate overlay layer sliding across on `transform`
+  only (never `background-position`), so it animates on the compositor instead of
+  repainting the gradient every frame — cheap even with hundreds of skeletons on screen.
+  Highlight band `s3` at 70% opacity, 1.2s ease-in-out loop. Radius `3` (block/tile `4`,
+  text `2`). Static fill under reduced motion.

package/docs/components/thumb.md

@@ -8,37 +8,54 @@ that is **missing or failed**.
 ## Web
 
 ```html
-<!-- normal: image covers the placeholder -->
-<figure class="juno-thumb" style="aspect-ratio: 1">
+<!-- normal: image covers the placeholder; aspect defaults to square -->
+<figure class="juno-thumb">
   <img src="…" alt="Sunset clip" onerror="this.remove()" />
 </figure>
 
-<!-- known-missing: ship no <img>; the placeholder just shows -->
+<!-- non-square: override the ratio, not the aspect-ratio property -->
 <figure
   class="juno-thumb juno-thumb--video"
-  style="aspect-ratio: 16/9"
+  style="--juno-thumb-ratio: 16/9"
   role="img"
   aria-label="Preview unavailable"
 >
   <figcaption class="juno-thumb__label">Unavailable</figcaption>
 </figure>
+
+<!-- selected, with corner overlays: a check top-left, a duration top-right -->
+<figure class="juno-thumb juno-thumb--selected">
+  <img src="…" alt="Sunset clip" onerror="this.remove()" />
+  <span class="juno-thumb__corner juno-thumb__corner--top-start badge badge--sm">✓</span>
+  <span class="juno-thumb__corner juno-thumb__corner--top-end badge badge--sm">0:42</span>
+</figure>
 ```
 
-| Class / attr              | Effect                                                         |
-| ------------------------- | -------------------------------------------------------------- |
-| `.juno-thumb`             | Frame: `s2` fill, hairline border, `radius.3`, centered glyph. |
-| `.juno-thumb--video`      | Play glyph instead of the image glyph.                         |
-| `.juno-thumb__label`      | Optional uppercase micro-caption under the glyph.              |
-| `> img` / `> video`       | Covers the frame (`object-fit: cover`).                        |
-| `onerror="this.remove()"` | The whole JS contract — optional, stateless, one attribute.    |
+| Class / attr                                                                          | Effect                                                                                                                                           |
+| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `.juno-thumb`                                                                         | Frame: `s2` fill, hairline border, `radius.3`, centered glyph, aspect locked to `--juno-thumb-ratio` (default `1`).                              |
+| `.juno-thumb--flush`                                                                  | Drops the border/radius — full-bleed tiles in a tight wall.                                                                                      |
+| `.juno-thumb--selected`                                                               | Inset outline (`--juno-active`) — never a border, so nothing reflows on toggle. Apps own the state; junoui never adds/removes the class.         |
+| `.juno-thumb--video`                                                                  | Play glyph instead of the image glyph.                                                                                                           |
+| `.juno-thumb__label`                                                                  | Optional uppercase micro-caption under the glyph.                                                                                                |
+| `.juno-thumb__corner`                                                                 | Absolutely-positioned slot over the media, `space.4` inset from the frame edge, above the media (`z-index: 1`). Pair with one position modifier. |
+| `.juno-thumb__corner--top-start` / `--top-right` / `--bottom-left` / `--bottom-right` | Anchors the slot to a corner using logical `inset-block-*` / `inset-inline-*` — start/end swap correctly under `dir="rtl"`.                      |
+| `> img` / `> video`                                                                   | Covers the frame (`object-fit: cover`).                                                                                                          |
+| `onerror="this.remove()"`                                                             | The whole JS contract — optional, stateless, one attribute.                                                                                      |
 
 ## Anatomy (any platform)
 
-- Frame: surface `s2`, 1px `border`, radius `3`; size from the app
-  (`aspect-ratio` inline or the [tiles grid](../layout.md)).
+- Frame: surface `s2`, 1px `border`, radius `3`; aspect locked by
+  `--juno-thumb-ratio` (default square) so a media wall's scroll height is
+  stable before anything loads — override per instance
+  (`style="--juno-thumb-ratio: 16/9"`) or via the [tiles grid](../layout.md).
 - Glyph: 28% of the frame (capped `space.32`), `muted` color — a missing thumb
   is **not** a warning state; the placeholder stays neutral.
 - Media covers the full frame, center-cropped.
+- Selection is an inset outline, not a border — the frame's box never
+  changes size, so a wall re-flowing selection doesn't jitter.
+- Corner slots are presentational anchors only; what occupies them (check
+  icon, duration chip, storage-tier badge) is app vocabulary.
 
 ## Failure contract
 
@@ -58,4 +75,7 @@ explicit:
   video poster slots, attachment previews.
 - Keep the placeholder neutral; if failure _matters_ (broken pipeline), say it
   with a [badge](./badge.md) or [alert](./alert.md) next to the thumb.
-- Retry, lazy-load, LQIP/blur-up: app or `junoui-<framework>` territory.
+- Multi-select galleries: toggle `--selected` per tile and put a check in a
+  `__corner` slot; duration/storage-tier chips are `__corner` occupants too.
+- Retry, lazy-load, LQIP/blur-up, and the selection/click behavior itself:
+  app or `junoui-<framework>` territory.

package/docs/design-guidelines.md

@@ -40,6 +40,15 @@ Neutral / structural roles carry no status meaning:
   stop value-change jitter. Use `tabular-nums`.
 - **B612** — all non-numeric UI: headings, labels, navigation, buttons.
 - Headings are uppercase with wide tracking; values are mono and bright (`data`).
+- `.juno-label` reads an optional `--juno-label-size` knob (falls back to
+  `--juno-font-size-13`) so a context can resize labels — e.g. a compact list —
+  without forking the class: set the custom property on an ancestor, never on
+  `.juno-label` itself.
+  ```html
+  <div style="--juno-label-size: var(--juno-font-size-11)">
+    <span class="juno-label">Signal strength</span>
+  </div>
+  ```
 
 ## Date & time
 
@@ -123,6 +132,23 @@ edges. Interactive controls keep their `min-height` (WCAG tap target); only padd
 shrinks. New components should use the aliases for internal padding to inherit
 density for free; add a new archetype only when one is genuinely needed.
 
+A third value, `auto`, re-densifies for small **coarse-pointer** viewports (phone,
+`pointer: coarse` and width ≤ 640px) — a data-heavy layout gets its compact-ish
+padding back on a phone without the consumer hand-tracking breakpoints:
+
+```html
+<body data-juno-density="auto">
+  <!-- comfortable everywhere else; re-densifies only on a narrow touch phone -->
+</body>
+```
+
+`auto` is **opt-in only** — existing `comfortable`/compact-pinned consumers render
+byte-identical, nothing changes silently. It never touches a control's
+`min-height`; `--juno-size-tap-min` still only grows (never shrinks) under
+`base.css`'s own `@media (pointer: coarse)` rule, so `auto` can't undo the WCAG
+tap-target work. Only `--juno-tile-min` / `--juno-gap-content` /
+`--juno-pad-surface-inline` shrink, same as `compact`.
+
 ## Accessibility
 
 Accessibility is a core design goal, held to published standards — **WCAG 2.2** and

package/docs/getting-started.md

@@ -25,6 +25,29 @@ cd vendor/junoui && npm install   # `prepare` builds dist/
 
 `npm install` runs the `prepare` script, so `dist/` is always built for you.
 
+## Required: the viewport meta
+
+Ship this on every page. It is not optional if you use anything that touches a
+phone edge — the dock, pillbar, navbar, drawer, bottom sheet, toast, or the
+app-shell:
+
+```html
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+```
+
+Two things depend on it, and both fail **silently**:
+
+- **`viewport-fit=cover` turns the safe area on.** iOS defaults `viewport-fit`
+  to `auto`, and WebKit reports every `env(safe-area-inset-*)` as `0` unless you
+  opt in with `cover` (`contain` does _not_ opt out). junoui is a stylesheet — it
+  cannot set this meta for you. Without it, every safe-area guarantee in the
+  library quietly becomes a no-op and content sits under the home indicator.
+- **`width=device-width, initial-scale=1` makes 1 CSS px equal 1 Apple point**,
+  which is what makes junoui's `44px` tap targets actually 44pt on the device.
+  Without it iOS Safari lays out at ~980px wide and every metric is off.
+
+Details and sources: [ios-conformance.md](./ios-conformance.md).
+
 ## The model
 
 - **Palette** — `standard` · `colorblind` · `soft`