@junoput01/junoui 0.3.0 → 0.4.0

package/docs/components/README.md

@@ -21,48 +21,51 @@ Role classes: `.juno--nominal` `.juno--active` `.juno--target` `.juno--caution`
 
 ## Catalogue
 
-| Component                      | Class                                  | Spec                                   |
-| ------------------------------ | -------------------------------------- | -------------------------------------- |
-| Badge / status indicator       | `.juno-badge`                          | [badge.md](./badge.md)                 |
-| Button                         | `.juno-btn`                            | [button.md](./button.md)               |
-| Card / panel                   | `.juno-card`                           | [card.md](./card.md)                   |
-| Data readout                   | `.juno-readout`                        | [readout.md](./readout.md)             |
-| Status dot                     | `.juno-status`                         | [status.md](./status.md)               |
-| Loaders (arc · beacon · bar)   | `.juno-arc` `.juno-beacon` `.juno-bar` | [loader.md](./loader.md)               |
-| Gauge (metric ring)            | `.juno-gauge`                          | [gauge.md](./gauge.md)                 |
-| Spark (sparkline contract)     | `.juno-spark`                          | [spark.md](./spark.md)                 |
-| Field wrapper                  | `.juno-field`                          | [field.md](./field.md)                 |
-| Input / textarea               | `.juno-input`                          | [input.md](./input.md)                 |
-| Select                         | `.juno-select`                         | [select.md](./select.md)               |
-| Checkbox / radio               | `.juno-checkbox` `.juno-radio`         | [checkbox.md](./checkbox.md)           |
-| Switch                         | `.juno-switch`                         | [switch.md](./switch.md)               |
-| Segmented control              | `.juno-seg`                            | [segmented.md](./segmented.md)         |
-| Toggle button                  | `.juno-toggle-btn`                     | [toggle-button.md](./toggle-button.md) |
-| Slider                         | `.juno-slider`                         | [slider.md](./slider.md)               |
-| Modal / dialog                 | `.juno-modal`                          | [modal.md](./modal.md)                 |
-| Drawer                         | `.juno-drawer`                         | [drawer.md](./drawer.md)               |
-| Tooltip                        | `.juno-tooltip`                        | [tooltip.md](./tooltip.md)             |
-| Popover                        | `.juno-popover`                        | [popover.md](./popover.md)             |
-| Menu / dropdown                | `.juno-menu`                           | [menu.md](./menu.md)                   |
-| Table / data grid              | `.juno-table`                          | [table.md](./table.md)                 |
-| Alert / inline notification    | `.juno-alert`                          | [alert.md](./alert.md)                 |
-| Toast / snackbar               | `.juno-toast`                          | [toast.md](./toast.md)                 |
-| Tabs                           | `.juno-tabs`                           | [tabs.md](./tabs.md)                   |
-| Accordion / disclosure         | `.juno-accordion`                      | [accordion.md](./accordion.md)         |
-| Icon                           | `.juno-icon`                           | [icon.md](./icon.md)                   |
-| Skeleton / loading placeholder | `.juno-skeleton`                       | [skeleton.md](./skeleton.md)           |
-| Thumb / media placeholder      | `.juno-thumb`                          | [thumb.md](./thumb.md)                 |
-| Avatar                         | `.juno-avatar`                         | [avatar.md](./avatar.md)               |
-| Divider / separator            | `.juno-divider`                        | [divider.md](./divider.md)             |
-| Chip / tag                     | `.juno-chip`                           | [chip.md](./chip.md)                   |
-| Breadcrumb                     | `.juno-breadcrumb`                     | [breadcrumb.md](./breadcrumb.md)       |
-| Pagination                     | `.juno-pagination`                     | [pagination.md](./pagination.md)       |
-| Stepper                        | `.juno-stepper`                        | [stepper.md](./stepper.md)             |
-| Rail (app-shell nav)           | `.juno-rail`                           | [rail.md](./rail.md)                   |
-| Dock (bottom nav, narrow)      | `.juno-dock`                           | [dock.md](./dock.md)                   |
-| Pillbar (floating pill bar)    | `.juno-pillbar`                        | [pillbar.md](./pillbar.md)             |
-| Icon loader (nav loading ring) | `.juno-icon-loader`                    | [icon-loader.md](./icon-loader.md)     |
-| Navbar (stack top bar)         | `.juno-navbar`                         | [navbar.md](./navbar.md)               |
-| List (grouped rows)            | `.juno-list`                           | [list.md](./list.md)                   |
+| Component                        | Class                                       | Spec                                   |
+| -------------------------------- | ------------------------------------------- | -------------------------------------- |
+| Badge / status indicator         | `.juno-badge`                               | [badge.md](./badge.md)                 |
+| Button                           | `.juno-btn`                                 | [button.md](./button.md)               |
+| Card / panel                     | `.juno-card`                                | [card.md](./card.md)                   |
+| Data readout                     | `.juno-readout`                             | [readout.md](./readout.md)             |
+| Status dot                       | `.juno-status`                              | [status.md](./status.md)               |
+| Loaders (arc · beacon · bar)     | `.juno-arc` `.juno-beacon` `.juno-bar`      | [loader.md](./loader.md)               |
+| Gauge (metric ring)              | `.juno-gauge`                               | [gauge.md](./gauge.md)                 |
+| Spark (sparkline contract)       | `.juno-spark`                               | [spark.md](./spark.md)                 |
+| Field wrapper                    | `.juno-field`                               | [field.md](./field.md)                 |
+| Input / textarea                 | `.juno-input`                               | [input.md](./input.md)                 |
+| Select                           | `.juno-select`                              | [select.md](./select.md)               |
+| Checkbox / radio                 | `.juno-checkbox` `.juno-radio`              | [checkbox.md](./checkbox.md)           |
+| Switch                           | `.juno-switch`                              | [switch.md](./switch.md)               |
+| Segmented control                | `.juno-seg`                                 | [segmented.md](./segmented.md)         |
+| Toggle button                    | `.juno-toggle-btn`                          | [toggle-button.md](./toggle-button.md) |
+| Slider                           | `.juno-slider`                              | [slider.md](./slider.md)               |
+| Modal / dialog                   | `.juno-modal`                               | [modal.md](./modal.md)                 |
+| Drawer                           | `.juno-drawer`                              | [drawer.md](./drawer.md)               |
+| Tooltip                          | `.juno-tooltip`                             | [tooltip.md](./tooltip.md)             |
+| Popover                          | `.juno-popover`                             | [popover.md](./popover.md)             |
+| Menu / dropdown                  | `.juno-menu`                                | [menu.md](./menu.md)                   |
+| Table / data grid                | `.juno-table`                               | [table.md](./table.md)                 |
+| Alert / inline notification      | `.juno-alert`                               | [alert.md](./alert.md)                 |
+| Toast / snackbar                 | `.juno-toast`                               | [toast.md](./toast.md)                 |
+| Tabs                             | `.juno-tabs`                                | [tabs.md](./tabs.md)                   |
+| Accordion / disclosure           | `.juno-accordion`                           | [accordion.md](./accordion.md)         |
+| Icon                             | `.juno-icon`                                | [icon.md](./icon.md)                   |
+| Skeleton / loading placeholder   | `.juno-skeleton`                            | [skeleton.md](./skeleton.md)           |
+| Load state (shimmer/fault/empty) | `.juno-shimmer` `.juno-fault` `.juno-empty` | [load-state.md](./load-state.md)       |
+| Reload (refetch-in-place)        | `.juno-reload`                              | [reload.md](./reload.md)               |
+| Thumb / media placeholder        | `.juno-thumb`                               | [thumb.md](./thumb.md)                 |
+| Avatar                           | `.juno-avatar`                              | [avatar.md](./avatar.md)               |
+| Divider / separator              | `.juno-divider`                             | [divider.md](./divider.md)             |
+| Chip / tag                       | `.juno-chip`                                | [chip.md](./chip.md)                   |
+| Breadcrumb                       | `.juno-breadcrumb`                          | [breadcrumb.md](./breadcrumb.md)       |
+| Pagination                       | `.juno-pagination`                          | [pagination.md](./pagination.md)       |
+| Stepper                          | `.juno-stepper`                             | [stepper.md](./stepper.md)             |
+| Rail (app-shell nav)             | `.juno-rail`                                | [rail.md](./rail.md)                   |
+| Dock (bottom nav, narrow)        | `.juno-dock`                                | [dock.md](./dock.md)                   |
+| Pillbar (floating pill bar)      | `.juno-pillbar`                             | [pillbar.md](./pillbar.md)             |
+| Fold slot (animated presence)    | `.juno-fold`                                | [fold-slot.md](./fold-slot.md)         |
+| Icon loader (rings any control)  | `.juno-icon-loader`                         | [icon-loader.md](./icon-loader.md)     |
+| Navbar (stack top bar)           | `.juno-navbar`                              | [navbar.md](./navbar.md)               |
+| List (grouped rows)              | `.juno-list`                                | [list.md](./list.md)                   |
 
 Always pair a status color with a text label — color is never the only signal.

package/docs/components/dock.md

@@ -19,14 +19,173 @@ destinations as icon-over-label tap targets. The phone-width counterpart of the
 </nav>
 ```
 
-| Class / prop        | Effect                                                                                        |
-| ------------------- | --------------------------------------------------------------------------------------------- |
-| `.juno-dock`        | Sticky bottom `s1` bar, 1px `border` seam on top, safe-area pad.                              |
-| `.juno-dock__item`  | Equal-width icon-over-label target, ≥ `size.tap.comfortable` tall.                            |
-| `.juno-dock__label` | The text — truncates with an ellipsis, never wraps.                                           |
-| `[aria-current]`    | Active item: `s2` fill + 2px role edge on top. Attribute, not class.                          |
-| `.juno-dock--fixed` | Pin to the viewport foot (`position: fixed`) — for page-scroll shells where sticky won't pin. |
-| `.juno--<role>`     | Active-edge color (default `active`).                                                         |
+| Class / prop              | Effect                                                                                                                                                                                     |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `.juno-dock`              | Sticky bottom `s1` bar, 1px `border` seam on top, safe-area pad.                                                                                                                           |
+| `.juno-dock__item`        | Equal-width icon-over-label target, ≥ `size.tap.comfortable` tall.                                                                                                                         |
+| `.juno-dock__label`       | The text — truncates with an ellipsis, never wraps.                                                                                                                                        |
+| `[aria-current]`          | Active item: `s2` fill + 2px role edge on top. Attribute, not class.                                                                                                                       |
+| `.juno-dock--fixed`       | Pin to the viewport foot (`position: fixed`) — for page-scroll shells where sticky won't pin.                                                                                              |
+| `.juno-dock--pill`        | Floating rounded pill: big glyphs in circular bubbles, labels hidden, active = bubble fill.                                                                                                |
+| `.juno-dock--float`       | Pillbar-style floating capsule chrome (fixed, rounded, blurred, shadowed) — keeps icon+label items and the full-item active fill. Combine with `--icon` for the `--pill` look, decomposed. |
+| `.juno-dock--icon`        | Labels hidden, glyphs grow, active = bubble fill — standalone (no floating chrome required).                                                                                               |
+| `.juno-dock__bubble`      | Circular icon holder (`--pill`/`--icon`); pair with `.juno-icon-loader` to host the loading ring.                                                                                          |
+| `.juno-dock--collapsible` | Fold-to-a-circle variant driven by `--juno-dock-fold` — see [Collapsible](#collapsible-fold-driven).                                                                                       |
+| `.juno-dock__tray`        | The collapsible bar's item row — fades out as the fold closes.                                                                                                                             |
+| `.juno-dock__knob`        | The collapsed circle's face (a button); shown only under `data-juno-collapsed`.                                                                                                            |
+| `.juno--<role>`           | Active-edge color (default `active`).                                                                                                                                                      |
+| `--juno-dock-scale`       | Consumer-set scale factor (default `1`) applied to the whole bar — e.g. shrink on scroll.                                                                                                  |
+
+## Pill variant
+
+`.juno-dock--pill` turns the full-width bar into a floating rounded pill: big
+glyphs sit in circular `.juno-dock__bubble`s, the labels drop, and only the
+active tab's bubble fills. It floats out of flow (fixed), so the page scrolls
+_under_ it — reserve room on the scroller with
+`padding-block-end: var(--juno-dock-clearance)` (a published token that folds
+in the pill height + safe area, so it stays correct if the geometry changes).
+
+```html
+<nav class="juno-dock juno-dock--pill juno-hide-from-md" aria-label="Primary">
+  <a class="juno-dock__item" href="/library" aria-current="page" aria-label="Library">
+    <span class="juno-dock__bubble juno-icon-loader">
+      <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-squares-four" /></svg>
+    </span>
+  </a>
+  <button class="juno-dock__item" aria-label="Nodes">
+    <span class="juno-dock__bubble juno-icon-loader">
+      <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-hexagon" /></svg>
+    </span>
+  </button>
+</nav>
+```
+
+- **Labels are hidden — every item MUST carry an `aria-label`** (on the
+  `<a>`/`<button>`). The glyph alone is not an accessible name.
+- Focus lands on the bubble, so the ring hugs the round target.
+- Pair every bubble with [`.juno-icon-loader`](./icon-loader.md) — it's the
+  concentric-stack contract, and having it on from the start means a loading
+  arc can appear later without touching the class list.
+
+### Section-loading ring
+
+The bubble doesn't invent its own ring: it is an
+[icon-loader](./icon-loader.md) host that overrides the ring's two dimensions
+(`--juno-icon-loader-ring` = the bubble diameter, `--juno-icon-loader-ring-width`
+= 2px), so the arc rings the bubble's **edge** rather than the glyph. Drop an
+indeterminate [arc](./loader.md) inside while the section loads; it eats no
+clicks, so the item still activates, and because the bubble's box is definite
+the arc appearing never resizes it. The app owns the state — add/remove
+`.juno-arc--indeterminate`; give the arc `role="status"` + `aria-label`.
+
+```html
+<span class="juno-dock__bubble juno-icon-loader">
+  <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-gear" /></svg>
+  <span class="juno-arc juno-arc--indeterminate" role="status" aria-label="Loading"></span>
+</span>
+```
+
+## Float variant
+
+`.juno-dock--float` lifts the pillbar's floating capsule chrome (fixed
+position, rounded shell, blur, shadow, off-edge margin) onto the dock's own
+item model — icon+label items stay, and the active item still fills (`s2` +
+role edge), just clipped to the capsule's rounded corners. It's `--pill`'s
+exterior without `--pill`'s interior; combine with `--icon` below to
+reproduce the original `--pill` look from two composable pieces. Out of flow
+(fixed), so reserve room on the scroller with
+`padding-block-end: var(--juno-dock-clearance)`.
+
+```html
+<nav class="juno-dock juno-dock--float juno-hide-from-md" aria-label="Primary">
+  <a class="juno-dock__item" href="/library" aria-current="page">
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-squares-four" /></svg>
+    <span class="juno-dock__label">Library</span>
+  </a>
+  <a class="juno-dock__item" href="/nodes">
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-hexagon" /></svg>
+    <span class="juno-dock__label">Nodes</span>
+  </a>
+</nav>
+```
+
+## Icon variant
+
+`.juno-dock--icon` hides labels, grows the glyph, and moves the active state
+onto a circular `.juno-dock__bubble` — usable standalone on a plain
+sticky/`--fixed` bar for a compact, icon-only dock that stays in flow. Follows
+the same bubble contract as `--pill` (pair with
+[`.juno-icon-loader`](./icon-loader.md); see the pill section above for the
+section-loading ring).
+
+```html
+<nav class="juno-dock juno-dock--icon" aria-label="Primary">
+  <a class="juno-dock__item" href="/library" aria-current="page" aria-label="Library">
+    <span class="juno-dock__bubble juno-icon-loader">
+      <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-squares-four" /></svg>
+    </span>
+  </a>
+  <button class="juno-dock__item" aria-label="Nodes">
+    <span class="juno-dock__bubble juno-icon-loader">
+      <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-hexagon" /></svg>
+    </span>
+  </button>
+</nav>
+```
+
+- **Labels are hidden — every item MUST carry an `aria-label`.**
+- Combine with `.juno-dock--float` for a floating icon-only capsule (the
+  original `--pill` treatment, built from the two composable variants).
+
+## Shrink on scroll
+
+`--juno-dock-scale` (default `1`) drives a `transform: scale()` on the whole
+bar, anchored `bottom center`, so a consumer can compact the dock as the page
+scrolls without junoui shipping any scroll-listener JS:
+
+```js
+dockEl.style.setProperty('--juno-dock-scale', shrink ? '0.92' : '1');
+```
+
+The transition duration is authored through the motion scale, so
+`prefers-reduced-motion` collapses it to an instant snap with no
+component-specific media query.
+
+## Collapsible (fold-driven)
+
+`.juno-dock--collapsible` folds the whole bar into a single circular
+`.juno-dock__knob` at the inline-end edge, driven by one inherited custom prop
+the app writes — `--juno-dock-fold` (`0` open … `1` the circle). Write it per
+scroll frame for a gesture-tracked fold, or flip it `0`/`1` for a toggle.
+Compose with a fixed placement (`--pill`, `--float`, or `--fixed`).
+
+```html
+<nav class="juno-dock juno-dock--pill juno-dock--collapsible" aria-label="Primary">
+  <div class="juno-dock__tray">…the usual __item children…</div>
+  <button class="juno-dock__knob" aria-label="Show navigation">
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-dots-three" /></svg>
+  </button>
+</nav>
+```
+
+Two phases, split at `--juno-dock-fold-split` (default `0.35`): first the bar
+**shrinks** in place to `--juno-dock-fold-scale` (default `0.78`, transform
+only — no relayout), then it **slides** shut to `--juno-dock-collapsed-size`.
+The width interpolates between two definite lengths (a transition cannot run
+to an intrinsic size); `--juno-dock-fold-smoothing` (default `90ms`) smooths
+over scroll-event discretization — anything longer visibly lags the finger.
+
+- `data-juno-collapsed` is the **end state**, set by the app only at fold = 1:
+  it hides the tray (`visibility` — the items leave the tab order) and reveals
+  the knob. Remove it the moment the fold reopens.
+- The knob **must** carry an `aria-label`. Collapsing while focus is inside
+  the tray is the app's edge — move focus to the knob first.
+- The fold's scale **replaces** the base `--juno-dock-scale` hook (one
+  transform slot). Transform-origin is the physical bottom right; RTL
+  consumers flip the origin and inset overrides together.
+- Knobs: `--juno-dock-collapsed-size` (default: one tap-comfortable bubble
+  plus the pill's padding and border), `--juno-dock-edge-gap` (what the
+  floating margins take from `100%` — default `2 × space.12`).
 
 ## Anatomy (any platform)
 

package/docs/components/drawer.md

@@ -15,11 +15,11 @@ surface; `.juno-drawer` re-pins and re-slides it.
 <dialog class="juno-modal juno-drawer juno-drawer--bottom">…</dialog>
 ```
 
-| Class                  | Effect                                                 |
-| ---------------------- | ------------------------------------------------------ |
-| `.juno-drawer`         | 380px, full height, pinned to the **inline-end** edge. |
-| `.juno-drawer--start`  | Pins to the inline-start edge.                         |
-| `.juno-drawer--bottom` | Full width, 60dvh, pinned to the bottom edge.          |
+| Class                  | Effect                                                                                                                                     |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `.juno-drawer`         | 380px, full height, pinned to the **inline-end** edge.                                                                                     |
+| `.juno-drawer--start`  | Pins to the inline-start edge.                                                                                                             |
+| `.juno-drawer--bottom` | Full width, real bottom sheet: height via `--juno-sheet-h` (default `60dvh`), grab handle, rounded top corners, pinned to the bottom edge. |
 
 ## Anatomy (any platform)
 
@@ -27,6 +27,45 @@ surface; `.juno-drawer` re-pins and re-slides it.
   (`opacity.scrim`) and shadow (`shadow.3`) as the modal.
 - Edge anchoring is logical (`margin-inline`), so start/end mirror under RTL.
 
+## Bottom sheet (`.juno-drawer--bottom`)
+
+```html
+<dialog class="juno-modal juno-drawer juno-drawer--bottom" aria-labelledby="sheet-tag">
+  <div class="juno-sheet__handle" aria-hidden="true"></div>
+  <div class="juno-modal__stripe"></div>
+  <div class="juno-modal__head">
+    <span class="juno-modal__tag" id="sheet-tag">FILTERS</span>
+    <button class="juno-modal__close" autofocus aria-label="Close">✕</button>
+  </div>
+  <div class="juno-modal__body"><!-- scrolls on its own, pads past the home indicator --></div>
+</dialog>
+```
+
+- **Height knob:** `--juno-sheet-h` (default `60dvh`) sets the sheet's block-size;
+  `--juno-sheet-max` (default `92dvh`) caps it. Both are plain custom properties an
+  app can swap per open (or per breakpoint) for peek/half/full snap points — this is
+  CSS only. junoui does **not** ship the drag gesture that would let a user pull
+  between those points; that's stateful interaction and belongs to the app (or a
+  sibling `junoui-<framework>` package).
+- **Grab handle:** `.juno-sheet__handle` is a decorative bar the app renders as the
+  first child. Mark it `aria-hidden="true"` — the dialog's own `aria-labelledby`
+  (pointing at the title) remains the accessible name. It is not a button and has no
+  built-in drag behavior.
+- **Safe area lives on the body, not the sheet.** `.juno-drawer--bottom` itself has
+  `padding-block-end: 0`; `.juno-modal__body` carries
+  `calc(var(--juno-pad-surface-inline) + env(safe-area-inset-bottom, 0px))` so a
+  scrolling sheet never hides its last row under the home indicator (a sheet that
+  doesn't scroll still gets the clearance, since the padding sits on the body box
+  either way).
+- **`<dialog>` is the only supported sheet root.** `showModal()` gives you the
+  top-layer stacking, `::backdrop` scrim, ESC handling, scroll lock, and — critically —
+  focus trap **and** `inert` background for free: the rest of the page becomes
+  unfocusable and unclickable the moment the sheet opens, with no extra markup.
+  Hand-rolling a bottom sheet from a positioned `<div>` + a manual scrim `<button>`
+  reproduces the visual but silently drops all of that: no focus trap, no `inert`,
+  ESC and outside-dismiss have to be wired by hand and are easy to get wrong. Don't
+  do it — use `<dialog class="juno-modal juno-drawer juno-drawer--bottom">`.
+
 ## The slide-over pattern
 
 The full production composition — scrim, end-anchored panel on `s1`, header row,
@@ -56,5 +95,6 @@ parts; the drawer class only re-pins and re-slides the surface.
 - Settings panels, filters, detail editors that don't warrant leaving context.
 - Same `<dialog>` + `showModal()` contract as the modal.
 - **Phone widths (< `bp.sm`) are automatic:** side drawers cap at `85vw` so a
-  sliver of scrim stays visible (and tappable) for dismissal. The bottom
-  drawer always pads past the home indicator (`safe-area-inset-bottom`).
+  sliver of scrim stays visible (and tappable) for dismissal. The bottom drawer's
+  body always pads past the home indicator (`safe-area-inset-bottom`) — see
+  [Bottom sheet](#bottom-sheet-juno-drawer--bottom) above.

package/docs/components/fold-slot.md

@@ -0,0 +1,31 @@
+# Fold slot
+
+Animated presence for a member of any flex/grid row: instead of popping in and
+out of the DOM, the slot's width folds to zero, it fades, and at the end of the
+fold it leaves the tab order (`visibility`, discretely transitioned — instant
+coming in, end-of-fade going out). Keep the element mounted; flip
+`data-juno-in`. Zero JS.
+
+## Web
+
+```html
+<div class="juno-pillbar">
+  <button class="juno-fold" data-juno-in aria-label="Scroll to top">
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-arrow-up" /></svg>
+  </button>
+  …other members…
+</div>
+```
+
+| Class / prop       | Effect                                                                                                                          |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| `.juno-fold`       | The slot: definite width (`--juno-fold-size`), folds shut when `data-juno-in` is absent.                                        |
+| `[data-juno-in]`   | Present state — app-set. Absent = folded away, invisible, out of the tab order.                                                 |
+| `--juno-fold-size` | The slot's open width (default `size.tap.comfortable`) — must be definite, transitions cannot run to an intrinsic size.         |
+| `--juno-fold-gap`  | The row's flex/grid gap (default `0px`) — the folded slot swallows one gap with a negative margin so the row closes completely. |
+
+- The row's own width follows the slot, so the whole row slides open/closed.
+- `prefers-reduced-motion`: handled by the base layer (states still apply,
+  transition durations collapse).
+- Canonical use: transient toolbar actions — a scroll-to-top arrow, a
+  contextual button — whose arrival should slide the row rather than jump it.

package/docs/components/icon-loader.md

@@ -1,11 +1,16 @@
 # Icon loader
 
-A nav destination's icon ringed by the spinning [arc](./loader.md#arc) while
-that section loads — the "this section is loading" affordance for a
-[rail](./rail.md), [dock](./dock.md), or [pillbar](./pillbar.md) item. The icon
-stays static on top; the arc sizes in `em` around it and takes no pointer
-events, so the item still clicks through. Zero JS in the CSS — the app toggles
-the arc's `--indeterminate` class to start/stop the spin.
+A control ringed by the spinning [arc](./loader.md#arc) while its section
+loads — the "this section is loading" affordance for a [rail](./rail.md),
+[dock](./dock.md), or [pillbar](./pillbar.md) item. What it wraps stays static
+on top; the arc rings it and takes no pointer events, so the item still clicks
+through. Zero JS in the CSS — the app toggles the arc's `--indeterminate` class
+to start/stop the spin.
+
+This is junoui's **only** concentric-ring mechanism. Anything that wants an arc
+around it composes `.juno-icon-loader` rather than re-rolling the geometry — the
+[dock](./dock.md#section-loading-ring)'s `__bubble` is the same wrapper with the
+ring resized to the bubble.
 
 ## Web
 
@@ -23,28 +28,90 @@ When the section finishes, remove `.juno-arc--indeterminate` (or the whole
 `.juno-arc`). For a progress ring instead of an endless spin, drop
 `--indeterminate` and set `--juno-progress` (0–100) on the `.juno-arc`.
 
-| Class / prop              | Effect                                                         |
-| ------------------------- | -------------------------------------------------------------- |
-| `.juno-icon-loader`       | Positioned wrapper; sizes to the icon, centers the ring on it. |
-| `> .juno-icon`            | The static glyph, held above the ring.                         |
-| `> .juno-arc`             | The ring — `1.9em`, thin (`0.14em`), pointer-transparent.      |
-| `--juno-icon-loader-ring` | Override the ring diameter (default `1.9em`).                  |
-| `.juno--<role>`           | Ring color (default `active`).                                 |
+| Class / prop                    | Effect                                                              |
+| ------------------------------- | ------------------------------------------------------------------- |
+| `.juno-icon-loader`             | Single-cell grid wrapper — every child is centred on the same cell. |
+| `> *`                           | The ringed content, held above the ring.                            |
+| `> .juno-arc`                   | The ring — pointer-transparent, painted under the content.          |
+| `--juno-icon-loader-ring`       | Ring diameter (default `1.9em`, i.e. relative to the glyph).        |
+| `--juno-icon-loader-ring-width` | Ring stroke (default `0.14em`).                                     |
+| `.juno--<role>`                 | Ring color (default `active`).                                      |
+
+### Ringing something bigger than a glyph
+
+Both dimensions are custom props, so the same wrapper rings a 14px glyph and a
+44px bubble. Give the host a **definite** box and set the diameter to it — then
+the ring hugs the edge and the box does not resize when the arc appears:
+
+```css
+.my-avatar-loader {
+  --juno-icon-loader-ring: var(--juno-size-tap-comfortable);
+  --juno-icon-loader-ring-width: 2px;
+
+  inline-size: var(--juno-size-tap-comfortable);
+  block-size: var(--juno-size-tap-comfortable);
+}
+```
+
+That is exactly how `.juno-dock__bubble` gets its section-loading ring.
+
+### Ringing an arbitrary control (button, badge, avatar)
+
+The wrapper doesn't care what it wraps — swap the icon for any interactive
+control and the ring still hugs it without resizing its box. Set the ring
+diameter to the control's own size (its `--juno-size-*` or `em` value) and
+the control keeps its own footprint; the wrapper is the only thing that
+grows to fit the ring:
+
+```html
+<!-- 40px circular icon button -->
+<span
+  class="juno-icon-loader"
+  style="--juno-icon-loader-ring:40px;--juno-icon-loader-ring-width:2px"
+>
+  <button class="juno-btn juno-btn--icon" aria-label="More">&#8943;</button>
+  <span class="juno-arc juno-arc--indeterminate" role="status" aria-label="Loading"></span>
+</span>
+
+<!-- 14px inline badge — small ring, use --smooth to avoid stepped jitter -->
+<span
+  class="juno-icon-loader"
+  style="--juno-icon-loader-ring:14px;--juno-icon-loader-ring-width:2px"
+>
+  <span class="juno-badge juno-badge--micro">3</span>
+  <span
+    class="juno-arc juno-arc--indeterminate juno-arc--smooth"
+    role="status"
+    aria-label="Loading"
+  ></span>
+</span>
+```
+
+The ring is `pointer-events: none` and sits under the content (`z-index: 0`
+vs. `1`), so a wrapped `<button>` stays fully clickable.
 
 ## Anatomy (any platform)
 
-- A wrapper the size of the icon; the arc is absolutely positioned and centered
-  over it, at a larger diameter so it rings the glyph.
+- A wrapper that stacks the ring and what it rings on one centred cell; with no
+  explicit size the wrapper sizes to the larger of the two (normally the ring).
 - The ring color is the semantic role; a `.juno--loading`/`.juno--active`
   ancestor tints it.
 
 ## Usage
 
-- **Concentric via a single-cell grid, never `translate(-50%, -50%)`** — the
-  icon and ring share one grid cell (`place-items: center`), so they're centered
-  on each other without any `transform`. The arc's rotation animation writes
+- **Concentric via a single-cell grid, never `translate(-50%, -50%)`** — every
+  child shares one grid cell (`place-items: center`), so they're centered on
+  each other without any `transform`. The arc's rotation animation writes
   `transform`, so a translate-based centering would be clobbered; keep the grid
   approach if you re-roll the markup.
+- **Don't hand-roll a second ring.** If a component needs an arc around it,
+  compose this class and override the two ring props — one primitive keeps the
+  centring gotcha, the pointer-events rule, and the paint order in one place.
+  That includes bespoke overlay CSS elsewhere for a "this control is loading"
+  ring — delete it and wrap the control in `.juno-icon-loader` instead.
+- Below ~24px, add `.juno-arc--smooth` next to `--indeterminate` — the
+  default 12-step sweep (see [loader](./loader.md)) reads as jitter at that
+  size; `--smooth` makes it a continuous rotation.
 - Gate the spin to first load, not every background refetch — a nav icon that
   blinks on every poll reads as broken. Add `--indeterminate` when a section
   has no data yet; remove it once loaded.

package/docs/components/icon.md

@@ -24,6 +24,27 @@ and a banner in the generated sprite; keep both when you ship.
 
 Import path: `@junoput01/junoui/icons` resolves to the sprite.
 
+## Same-document refs (Safari fix)
+
+An **external** sprite reference (`<use href="…file.svg#id">`) intermittently
+fails to render in Safari — icons randomly vanish and reappear. The reliable
+path is a **same-document** reference (`<use href="#juno-i-gear">`), which needs
+the sprite living in the current document. Rather than hand-roll that injection
+in every app, import the shipped helper once:
+
+```js
+import '@junoput01/junoui/icons/inline'; // injects the sprite into the document once
+```
+
+```html
+<svg class="juno-icon" aria-hidden="true"><use href="#juno-i-gear" /></svg>
+```
+
+The module auto-installs on import in a browser (no-op server-side / before
+hydration) and is id-guarded, so importing it from many modules injects only
+once. It also exports `installJunoIcons(doc)` (default + named) for manual or
+multi-document (iframe) control. No bundler `?raw` loader needed.
+
 | Class              | Effect                                                        |
 | ------------------ | ------------------------------------------------------------- |
 | `.juno-icon`       | 1.25em square, `fill: currentColor`, baseline-aligned inline. |