@junoput01/junoui 0.2.0 → 0.4.0

package/docs/components/README.md

@@ -0,0 +1,71 @@
+# Components
+
+Framework-agnostic elements built from tokens. On the web they're CSS classes in
+`@junoput01/junoui/css`; on other platforms, build the same anatomy from
+[tokens-reference.md](../tokens-reference.md).
+
+## The role mechanism (web)
+
+A component reads a single custom property, `--juno-role`. A role class sets it, so
+**one class re-colors any component**:
+
+```html
+<span class="juno-badge juno--warning">…</span>
+<!-- role = warning -->
+<button class="juno-btn juno--nominal">…</button>
+<!-- role = nominal -->
+```
+
+Role classes: `.juno--nominal` `.juno--active` `.juno--target` `.juno--caution`
+`.juno--warning` `.juno--muted`.
+
+## 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)           |
+| 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/accordion.md

@@ -0,0 +1,49 @@
+# Accordion / disclosure
+
+Stacked, expandable sections built on the native `<details>` / `<summary>` — keyboard and
+screen-reader native, **zero JS**. A chevron rotates on open. Use a lone `<details>` for a
+single disclosure, or group them in `.juno-accordion` for a bordered set.
+
+## Web
+
+```html
+<div class="juno-accordion">
+  <details class="juno-accordion__item" open>
+    <summary class="juno-accordion__summary">Region · us-east-1</summary>
+    <div class="juno-accordion__body">Primary region. 3 replicas, auto-scaling on.</div>
+  </details>
+  <details class="juno-accordion__item">
+    <summary class="juno-accordion__summary">Region · eu-west-1</summary>
+    <div class="juno-accordion__body">Failover armed. 1 of 3 replicas reporting.</div>
+  </details>
+</div>
+
+<!-- lone disclosure (frames itself) -->
+<details class="juno-accordion__item">
+  <summary class="juno-accordion__summary">Advanced options</summary>
+  <div class="juno-accordion__body">…</div>
+</details>
+```
+
+| Class                      | Effect                                                         |
+| -------------------------- | -------------------------------------------------------------- |
+| `.juno-accordion`          | Bordered group; clips its items' corners.                      |
+| `.juno-accordion__item`    | A `<details>`; row rule between items. `[open]` to start open. |
+| `.juno-accordion__summary` | The `<summary>` header; native marker hidden, chevron added.   |
+| `.juno-accordion__body`    | The revealed content (`s0`, `label` text).                     |
+
+## Anatomy (any platform)
+
+- Summary: `s1` row, `data` label, control-padding; hover → `s2`. A chevron (a rotated
+  corner) flips from ▸ to ▾ via `[open]`, `motion.duration.quick`.
+- Body: `s0` panel under a 1px rule. Native open/close (no height animation by default).
+- A lone `details.juno-accordion__item:only-child` draws its own border + radius.
+
+## Usage
+
+- **Zero JS** — `<details>` toggles itself; `<summary>` is focusable and Enter/Space work.
+  For "only one open at a time", give the `<details>` a shared `name` attribute (native
+  exclusive accordion) — no script needed.
+- Keep the summary a short label; put detail in the body.
+- To animate open/close, progressively enhance with `::details-content` +
+  `interpolate-size` where supported; the component stays correct without it.

package/docs/components/alert.md

@@ -0,0 +1,46 @@
+# Alert / inline notification
+
+A role-tinted banner for in-context messages — validation summaries, system status,
+callouts. Soft-fill with a role accent rail; icon + title + text + optional actions and
+dismiss. Color comes from `var(--juno-role)` (set by a `.juno--<role>` class).
+
+## Web
+
+```html
+<div class="juno-alert juno--warning" role="alert">
+  <span class="juno-alert__icon" aria-hidden="true">⚠</span>
+  <div class="juno-alert__body">
+    <span class="juno-alert__title">Deploy blocked</span>
+    <span class="juno-alert__text">Two required checks are still failing.</span>
+    <div class="juno-alert__actions">
+      <button class="juno-btn juno--warning">RE-RUN</button>
+      <button class="juno-btn juno-btn--ghost">VIEW LOG</button>
+    </div>
+  </div>
+  <button class="juno-alert__close" aria-label="Dismiss">✕</button>
+</div>
+```
+
+| Class                  | Effect                                                                      |
+| ---------------------- | --------------------------------------------------------------------------- |
+| `.juno-alert`          | Soft role wash + role border + start accent rail. Default `active`.         |
+| `.juno-alert__icon`    | Leading glyph, role-colored. Mark it `aria-hidden`.                         |
+| `.juno-alert__body`    | `__title` (data, semibold) + `__text` (label) column.                       |
+| `.juno-alert__actions` | Row of buttons under the text.                                              |
+| `.juno-alert__close`   | Ghost dismiss button (app removes the alert).                               |
+| `.juno-alert--solid`   | High-emphasis: full role fill, text on `s0`.                                |
+| `.juno--<role>`        | Sets the color (`active` info · `nominal` success · `caution` · `warning`). |
+
+## Anatomy (any platform)
+
+- Surface: `color-mix(role 10%)` wash, `color-mix(role 30%)` border, `border.width.3`
+  role rail on the inline-start edge, `radius.5`, surface padding.
+- Icon + title (`data`, semibold) + text (`label`); `--solid` swaps to a full role fill.
+
+## Usage
+
+- **Inline, not floating** — alerts sit in the layout. For transient confirmations use a
+  [toast](./toast.md).
+- `role="alert"` for urgent (assertive announce); `role="status"` for passive.
+- Pair the role color with the icon **and** a word — never color alone.
+- Dismiss is the app's job: remove the node (`showcase/app.js` wires `.juno-alert__close`).

package/docs/components/avatar.md

@@ -0,0 +1,45 @@
+# Avatar
+
+A round (or squared) portrait holding an `<img>`, **initials**, or an
+[icon](./icon.md) fallback. One custom property drives the size; an optional role ring
+marks status. Zero JS. Pairs with a [`.juno-skeleton--circle`](./skeleton.md) while the
+image loads.
+
+## Web
+
+```html
+<!-- image -->
+<span class="juno-avatar"><img src="ada.jpg" alt="Ada Lovelace" /></span>
+
+<!-- initials -->
+<span class="juno-avatar juno-avatar--lg">AL</span>
+
+<!-- icon fallback + status ring -->
+<span class="juno-avatar juno-avatar--ring juno--nominal" title="Online">
+  <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-user" /></svg>
+</span>
+
+<!-- overlapping cluster -->
+<span class="juno-avatar-group">
+  <span class="juno-avatar"><img src="a.jpg" alt="Ada" /></span>
+  <span class="juno-avatar"><img src="g.jpg" alt="Grace" /></span>
+  <span class="juno-avatar">+3</span>
+</span>
+```
+
+| Class                    | Effect                                                      |
+| ------------------------ | ----------------------------------------------------------- |
+| `.juno-avatar`           | Circle portrait; `--juno-avatar-size` (default `space.32`). |
+| `.juno-avatar--sm/lg/xl` | `space.24` / `space.40` / `space.56`.                       |
+| `.juno-avatar--square`   | Rounded-rect instead of circle.                             |
+| `.juno-avatar--ring`     | Status ring in `var(--juno-role)` (+ soft halo).            |
+| `.juno-avatar-group`     | Overlapping row; each tucks under the previous.             |
+| `--juno-avatar-size`     | Override the size (initials scale to ~40% of it).           |
+
+## Usage
+
+- An `<img>` fills the box (`object-fit: cover`); always set a meaningful `alt`.
+- Initials / `+N` overflow are plain text content — center-aligned, uppercase.
+- The **ring is decorative**: pair it with a `title` / visible label so status isn't
+  color-only.
+- In a group, set `alt` per avatar; the trailing `+N` chip is just another avatar.

package/docs/components/badge.md

@@ -0,0 +1,35 @@
+# Badge / status indicator
+
+A compact, uppercase status label.
+
+## Web
+
+```html
+<span class="juno-badge juno--nominal">NOMINAL</span>
+<span class="juno-badge juno-badge--outline juno--caution">CAUTION</span>
+```
+
+| Class                  | Effect                                         |
+| ---------------------- | ---------------------------------------------- |
+| `.juno-badge`          | Base. Filled: background = role, text = `s0`.  |
+| `.juno-badge--outline` | Transparent fill, text + border = role.        |
+| `.juno-badge--soft`    | Low-fill chip: role text on a 13% role wash.   |
+| `.juno-badge--micro`   | Data-UI atom: mono 10px, hairline role border. |
+| `.juno--<role>`        | Sets the color (required).                     |
+
+## Anatomy (any platform)
+
+- Font: B612, 700 weight, size `font.size.11`, uppercase, tracking `font.tracking.caps` (0.15em).
+- Padding: `space.4` vertical, `space.10` horizontal. Radius: `radius.3`.
+- **Filled:** fill = role color, text = `s0` (base surface).
+- **Outline:** transparent fill, text + 1px border = role color.
+
+## Usage
+
+- Use the semantic roles for status; `muted` for inactive/disabled.
+- Keep the text the literal status word — color reinforces, never replaces it.
+- `--micro` is for provenance/kind tags (`device`, `TRANSCODE`, model names) and
+  threshold values that repeat dozens of times per screen. Threshold coloring is app
+  policy — map value → role class yourself, e.g.
+  `juno-badge--micro juno--nominal` for a ≥ 90% confidence. Same recipe as the
+  [gauge](./gauge.md) thresholds.

package/docs/components/breadcrumb.md

@@ -0,0 +1,31 @@
+# Breadcrumb
+
+A horizontal trail of links to ancestor pages, ending at the current page. Built on a
+real `<nav><ol>`; the separator is a CSS chevron (no glyph font). Zero JS.
+
+## Web
+
+```html
+<nav class="juno-breadcrumb" aria-label="Breadcrumb">
+  <ol>
+    <li><a href="/">Home</a></li>
+    <li><a href="/fleet">Fleet</a></li>
+    <li><a aria-current="page">api-gateway</a></li>
+  </ol>
+</nav>
+```
+
+| Part / attr             | Effect                                               |
+| ----------------------- | ---------------------------------------------------- |
+| `.juno-breadcrumb`      | `<nav>` wrapper; lay out an `<ol>` of `<li>` inside. |
+| `li + li::before`       | CSS chevron separator (rotates under RTL).           |
+| `a[href]`               | `label` link → `data` + underline on hover.          |
+| `[aria-current="page"]` | The current crumb — brightest, semibold, not a link. |
+
+## Usage
+
+- Always `aria-label="Breadcrumb"` on the `<nav>`, and `aria-current="page"` on the last
+  crumb (drop its `href` so it isn't a link).
+- Order matters: root → … → current, left to right (mirrors under `dir="rtl"`).
+- For very deep trails, collapse the middle to an ellipsis crumb the app expands — junoui
+  ships the look, the app owns the collapse.

package/docs/components/button.md

@@ -0,0 +1,32 @@
+# Button
+
+## Web
+
+```html
+<button class="juno-btn juno--nominal">CONFIRM</button>
+<button class="juno-btn juno-btn--ghost">CANCEL</button>
+<button class="juno-btn juno-btn--sm juno-btn--ghost">EDIT</button>
+<button class="juno-btn" disabled>DISABLED</button>
+```
+
+| Class              | Effect                                                                           |
+| ------------------ | -------------------------------------------------------------------------------- |
+| `.juno-btn`        | Base. Primary (filled): background = role, text = `s0`. Default role = `active`. |
+| `.juno-btn--ghost` | Transparent, `data` text, `border` outline; hover → `s2`.                        |
+| `.juno-btn--sm`    | Dense-toolbar size: `font.size.11`, `space.4` × `space.10`, `radius.3`.          |
+| `.juno--<role>`    | Sets the primary fill color.                                                     |
+| `:disabled`        | `muted` fill, `label` text, not-allowed.                                         |
+
+## Anatomy (any platform)
+
+- Font: B612, 700 weight, size `font.size.13`, uppercase, tracking `font.tracking.caps`.
+- Padding: `space.10` × `space.20`. Radius: `radius.4`. Min height: `size.tap.min` (24px; use 44px on mobile).
+- States: hover brighten ~8%, active darken ~6%, disabled = `muted`/`label`.
+
+## Usage
+
+- Primary action filled with `nominal` (confirm) or `active` (apply).
+- `warning` fill only for genuinely critical/destructive actions.
+- One primary per group; everything else is ghost.
+- `--sm` drops below the WCAG tap-minimum on purpose — it is for dense **desktop**
+  toolbars (40–46px chrome bars). Keep the default size anywhere touch is expected.

package/docs/components/card.md

@@ -0,0 +1,41 @@
+# Card / panel
+
+A surface grouping a titled header and a body.
+
+## Web
+
+```html
+<article class="juno-card juno-card--accent juno--caution">
+  <header class="juno-card__head">
+    HYD SYS B
+    <span class="juno-badge juno-badge--outline juno--caution">CAUTION</span>
+  </header>
+  <div class="juno-card__body">
+    <div class="juno-card__row">
+      <span class="juno-label">Pressure</span>
+      <span class="juno-value juno-text-caution">2,650</span>
+    </div>
+  </div>
+</article>
+```
+
+| Class                | Effect                                                 |
+| -------------------- | ------------------------------------------------------ |
+| `.juno-card`         | `s1` surface, 1px `border`, radius `radius.8`.         |
+| `.juno-card--accent` | 2px top edge in the role color (status hint).          |
+| `.juno-card--alert`  | Full border in role + tinted header — critical panels. |
+| `.juno-card__head`   | Uppercase title row; holds a status badge.             |
+| `.juno-card__body`   | Padded content column.                                 |
+| `.juno-card__row`    | Label-left / value-right baseline row.                 |
+
+## Anatomy (any platform)
+
+- Surface `s1`, border `border` 1px, radius `radius.8`.
+- Header: padding `space.12`/`space.16`, bottom 1px divider, title B612 600 uppercase tracking `wide`.
+- Body: padding `space.16`, rows gapped `space.12`.
+- Escalation: accent (2px top) → alert (full role border + `s2` header tinted in role).
+
+## Usage
+
+- One subject per card. Header carries the identifier + a status badge.
+- Match accent/alert role to the card's worst current status.

package/docs/components/checkbox.md

@@ -0,0 +1,41 @@
+# Checkbox & Radio
+
+Custom-styled native inputs (`appearance: none`) — keyboard and screen-reader support
+come for free. The checkbox is a **targeting-reticle** square whose solid core drops in
+on check; the radio is a ring with a center dot. Wrap with `.juno-choice` for a label row.
+
+## Web
+
+```html
+<label class="juno-choice"> <input class="juno-checkbox" type="checkbox" checked /> TCAS </label>
+
+<label class="juno-choice"> <input class="juno-radio" type="radio" name="mode" /> SELECTED </label>
+<label class="juno-choice">
+  <input class="juno-radio juno--target" type="radio" name="mode" checked /> MANAGED
+</label>
+
+<label class="juno-choice">
+  <input class="juno-checkbox" type="checkbox" disabled /> Restricted
+</label>
+```
+
+| Class            | Effect                                                    |
+| ---------------- | --------------------------------------------------------- |
+| `.juno-checkbox` | `space.16` reticle square; checked core + role ring-glow. |
+| `.juno-radio`    | Same as a circle with a center dot.                       |
+| `.juno-choice`   | Inline-flex label row; `gap-control`, `data` text.        |
+| `.juno--<role>`  | Recolors the core/dot (default `active`).                 |
+| `:checked`       | Border → role, 3px role glow, core scales in (spring).    |
+| `:disabled`      | `s1` + dimmed; row text → `muted`.                        |
+
+## Anatomy (any platform)
+
+- Box `space.16` on `control-surface` with a `control-edge` border; checked adds a
+  `border-width.3` ring at 22% role and a `space.8` core (spring scale-in).
+- Label row: B612 `font.size.13`, `data`, `gap-control` between box and text.
+
+## Usage
+
+- Checkbox = independent toggles; radio = one-of-many (share a `name`).
+- Keep the label inside the same `<label>` so the hit area covers both.
+- For a single on/off with an emphasized track, use the [switch](./switch.md).

package/docs/components/chip.md

@@ -0,0 +1,44 @@
+# Chip / Tag
+
+A compact pill for a discrete entity — a filter, a selected value, a removable tag.
+Where a [badge](./badge.md) is a **static** status label, a chip is **interactive**:
+selectable and/or dismissible. Reads `--juno-role` for its accent; the app owns
+selection and removal (zero JS).
+
+## Web
+
+```html
+<!-- plain tag -->
+<span class="juno-chip">us-east-1</span>
+
+<!-- role-tinted -->
+<span class="juno-chip juno--active">live</span>
+
+<!-- toggle (filter) chip -->
+<button class="juno-chip juno-chip--toggle juno--active" aria-pressed="true">Errors</button>
+
+<!-- removable -->
+<span class="juno-chip">
+  filter:prod
+  <button class="juno-chip__remove" aria-label="Remove prod filter">
+    <svg class="juno-icon juno-icon--sm" aria-hidden="true"><use href="…#juno-i-x" /></svg>
+  </button>
+</span>
+```
+
+| Class                | Effect                                                       |
+| -------------------- | ------------------------------------------------------------ |
+| `.juno-chip`         | Pill; `control-surface` fill, strong border, `data` text.    |
+| `.juno--<role>`      | Role accent (border + tinted fill + role text).              |
+| `.juno-chip--toggle` | Use on a `<button>`; `aria-pressed="true"` fills the accent. |
+| `.juno-chip__remove` | Trailing dismiss button (put an `x` icon inside; label it).  |
+| `:disabled`          | Dims + blocks pointer.                                       |
+
+## Usage
+
+- **Toggle chip:** a real `<button>`; the app flips `aria-pressed`. Use for filter sets.
+- **Removable chip:** the `__remove` button needs an `aria-label` ("Remove X"); the app
+  deletes the chip on click.
+- Chip vs badge: chip = interactive / user data; badge = read-only status. Don't make a
+  badge clickable — reach for a chip.
+- Color is never the only signal — the chip's text carries the meaning; role is accent.

package/docs/components/divider.md

@@ -0,0 +1,32 @@
+# Divider
+
+A hairline rule that separates content. Horizontal by default; vertical for a column
+separator; or labeled to break the line with a centered caption.
+
+## Web
+
+```html
+<!-- semantic horizontal break -->
+<hr class="juno-divider" />
+
+<!-- labeled -->
+<div class="juno-divider juno-divider--label">OR</div>
+
+<!-- vertical (inside a flex row) -->
+<span class="juno-divider juno-divider--vertical"></span>
+```
+
+| Class                     | Effect                                                              |
+| ------------------------- | ------------------------------------------------------------------- |
+| `.juno-divider`           | Full-width `border`-colored hairline.                               |
+| `.juno-divider--vertical` | Hairline column rule; stretches to the row (`align-self: stretch`). |
+| `.juno-divider--label`    | Caption centered between two rules (uppercase `label`).             |
+
+## Usage
+
+- Use a real `<hr>` for a **semantic** break; a `<span>` / `<div>` when it's purely
+  decorative.
+- The vertical variant needs a parent that gives it block size — a flex row works
+  (`align-self: stretch`); otherwise set a height.
+- Don't over-divide: whitespace separates most things. Reach for a rule only when groups
+  would otherwise read as one.