@ponchia/ui 0.3.5 → 0.4.0

package/docs/usage.md

@@ -146,6 +146,105 @@ carousel crops (`cover`); the lightbox shows the whole image (`contain`).
 This is deliberately *not* an auto-playing marketing slider (no timers, no
 infinite-clone track). It's a gallery: the user drives it.
 
+## Display glyphs: when (and when not)
+
+`@ponchia/ui/glyphs` is a 43-glyph dot-matrix icon set — navigation
+(`arrow-*`, `chevron-*`), actions (`check`, `close`, `plus`, `minus`,
+`search`, `menu`, `gear`), status (`info`, `warning`, `bell`, `lock`) and
+common marks (`home`, `user`, `heart`, `star`, `spark`) — rendered on the
+`.ui-dotmatrix` primitive, so they re-skin with the same `--field-dot*`
+tokens as every other dot surface (no SVG, no icon font).
+
+**Two rendering modes — pick by size.** The dots need physical room to
+read, so the default _dot_ look is for **display** sizes (~40px up: hero
+marks, empty states, status bursts, section headers, large buttons). For
+small/inline use pass **`solid: true`** (or `data-bronto-glyph-solid`):
+that fuses the cells into a square, gapless pixel glyph that stays crisp and
+legible down to **~16px** — so the same set doubles as real inline UI icons,
+not just decoration. (Below the dot fragments into dot-soup; solid does not.)
+
+`renderGlyph(name, { label })` returns an SSR-safe string: decorative
+(`aria-hidden`) by default, or `role="img"` + `aria-label` when you pass a
+`label` — which is how it conveys meaning to assistive tech. Prefer the
+`data-bronto-glyph` placeholder + `initDotGlyph()` when the markup is
+easier dropped than inlined. Size with `--dotmatrix-dot` (and a tight
+`--dotmatrix-gap`) for an intrinsic dot, or let it stretch to its container.
+It is still a pixel-grid aesthetic, not a hairline vector set — but it now
+spans both inline-icon and display use from one source.
+
+**Animation** is opt-in via `anim` (`renderGlyph(name, { anim: 'reveal' })`)
+or `data-bronto-glyph-anim`: `reveal` powers the cells on in a scan (a
+dot-matrix booting up), `pulse` makes the glyph breathe for a live/attention
+state. It's **decorative only** — disabled under `prefers-reduced-motion`,
+and the meaning still lives in the static frame + `label`, never in the
+motion. Don't animate to convey information a reduced-motion user would miss.
+Tune the scan speed with `--dotmatrix-reveal-step` (delay per cell, default
+`3ms`). Use `pulse` sparingly — one attention target per view: it loops
+indefinitely, and animation that runs in parallel with other content is the
+consumer's WCAG 2.2.2 (Pause/Stop/Hide) responsibility (reduced-motion is not
+a substitute).
+
+A few sharp edges to know:
+
+- **Inline icon recipe.** `renderGlyph` returns a `<span>`, so it's valid
+  inline and inside a `<button>`. For an inline UI icon, render `solid` and
+  size the dot, e.g. inside a button:
+  `` `<button class="ui-button">${renderGlyph('search', { solid: true, dot: '1.2px', label: 'Search' })}<span>Search</span></button>` `` —
+  the button's `display: inline-flex; gap` aligns icon + text. For icon-in-prose,
+  set `--dotmatrix-dot` to ~`0.08em` and `vertical-align: -0.15em` on the span.
+- **`solid` wins.** `solid: true` implies glyph-only and forces
+  `--dotmatrix-gap: 0` / square cells, so a `grid: true` or `gap` passed
+  alongside it is ignored.
+- **Directional glyphs are physical, not logical.** `arrow-left/right`,
+  `chevron-left/right` are fixed bitmaps; in an RTL context flip them yourself
+  (e.g. swap the name, or `transform: scaleX(-1)`), the framework won't.
+- **Cost / icon-at-scale.** The default (cell) render is a 16×16 grid = 256
+  cells (DOM nodes), regardless of `solid`/`grid`; `anim: 'reveal'` adds a
+  per-cell `--i`. That's the dot-matrix display look — but for **many** icons
+  (one in every row of a long table) use **`renderGlyph(name, { render: 'mask' })`**:
+  it returns a **single** `.ui-icon` element masked by the bitmap (one node, not
+  256), sizes to `size` / `--icon-size` (default `1em`) and inherits
+  `currentColor` — a normal inline icon. Pick `render: 'mask'` for icons,
+  the cell render for display marks/animation.
+
+## Colorways: when to reach for a skin
+
+`@ponchia/ui/css/skins.css` adds `data-bronto-skin="amber-crt |
+phosphor-green | e-ink"` — a **root-level** colorway (apply on `<html>`, like
+`data-theme`) that re-points the one accent to a different single hue.
+
+- **Use a skin** when you want a distinct, on-brand _look_ (a phosphor/CRT or
+  e-ink feel) for the whole page or app — it's the supported, contrast-gated
+  way to recolour without leaving the design system.
+- **Use a raw `--accent` override** when you just need _your_ brand hue: it's
+  one declaration (see "Re-brand obligations" below) — but then contrast is
+  yours, whereas the shipped skins are pre-gated.
+- **Don't** put `data-bronto-skin` on a subtree — it's root-level by design
+  (the derived accent family only recomputes at `:root`); a subtree skin
+  no-ops. For a one-section recolour, scope a raw `--accent` override instead.
+- It's **opt-in**: a separate stylesheet, never in `dist/bronto.css`. No skin
+  imported → zero cost. Full detail in [theming.md](theming.md) → "Display
+  colorways".
+
+## Data-viz colours: charts, not chrome
+
+`@ponchia/ui/css/dataviz.css` (opt-in) adds a Tier-4 chart palette for
+dashboards: `--chart-1..8` (categorical), `--chart-seq-*` (sequential),
+`--chart-div-*` (diverging), and `--chart-pattern-1..8` (dot-matrix fills).
+
+- **Use it for charts only.** These are not UI tokens — a build gate fails if
+  `var(--chart-*)` appears in component CSS. Style buttons/badges with the
+  accent/status tiers, not chart colours.
+- **Series 1 is the accent**, so your brand leads the palette; series 2–8 are a
+  colourblind-safe set (gated for distinctness under protan/deutan/tritan).
+- **Always pair colour with pattern** (`--chart-pattern-N`) and/or a direct
+  label — never colour alone (WCAG 1.4.1):
+  `background: var(--chart-3); background-image: var(--chart-pattern-3); background-size: var(--chart-pattern-size);`
+- **In JS** (Chart.js, canvas, SVG): import resolved hex from
+  `@ponchia/ui/charts.json` (`{ light, dark }`, series 1 = the resolved accent).
+  Cap a chart at ~8 series. Full detail in [theming.md](theming.md) →
+  "Data-viz palette".
+
 ## When to add a behavior
 
 The CSS is the framework; `@ponchia/ui/behaviors` is the *sanctioned*

package/glyphs/glyphs.d.ts

@@ -0,0 +1,115 @@
+/** @ponchia/ui — GENERATED from glyphs/glyphs.js by scripts/gen-glyphs.mjs.
+ *  Do not edit by hand; run `npm run glyphs:build`. Drift-checked in CI. */
+
+/** Every display-glyph name @ponchia/ui ships (literal union). Use this as a
+ *  type annotation to reject typos (`const n: GlyphName = 'arow'` is an error). */
+export type GlyphName =
+  | 'arrow-down'
+  | 'arrow-left'
+  | 'arrow-right'
+  | 'arrow-up'
+  | 'bell'
+  | 'check'
+  | 'check-circle'
+  | 'chevron-down'
+  | 'chevron-left'
+  | 'chevron-right'
+  | 'chevron-up'
+  | 'circle'
+  | 'clock'
+  | 'close'
+  | 'download'
+  | 'edit'
+  | 'eye'
+  | 'eye-off'
+  | 'file'
+  | 'folder'
+  | 'gear'
+  | 'grid'
+  | 'heart'
+  | 'home'
+  | 'info'
+  | 'link'
+  | 'lock'
+  | 'mail'
+  | 'menu'
+  | 'minus'
+  | 'minus-circle'
+  | 'moon'
+  | 'more-horizontal'
+  | 'more-vertical'
+  | 'pause'
+  | 'play'
+  | 'plus'
+  | 'plus-circle'
+  | 'refresh'
+  | 'search'
+  | 'spark'
+  | 'star'
+  | 'sun'
+  | 'trash'
+  | 'upload'
+  | 'user'
+  | 'warning'
+  | 'x-circle';
+
+/** A glyph name, or any string — for dynamic dispatch (a CMS/config value). The
+ *  known names still autocomplete; an unknown name hits the runtime fallback
+ *  (`glyph`→`undefined`, `glyphCells`→`[]`, `renderGlyph`→`''`). */
+export type GlyphNameInput = GlyphName | (string & {});
+
+/** A glyph is 16 rows of 16 chars: `.` off, `#` lit, `*` accent. */
+export type Glyph = readonly string[];
+
+/** One rendered dot. `on:false` is an unlit panel dot; tone picks the lit color. */
+export interface GlyphCell {
+  on: boolean;
+  tone?: 'hot' | 'accent';
+}
+
+export interface RenderGlyphOptions {
+  /** Show the unlit panel dots (default true). `false` → glyph-only look. */
+  grid?: boolean;
+  /** Render lit cells as square, gapless pixels (a filled silhouette) instead
+   *  of separated dots — the legible mode at small/inline sizes (~16–24px).
+   *  Implies glyph-only. Default false (the dot-matrix display look). */
+  solid?: boolean;
+  /** Opt into a decorative animation (disabled under `prefers-reduced-motion`;
+   *  meaning stays in the static frame + `label`). `'reveal'` powers the cells
+   *  on in a scan; `'pulse'` makes the glyph breathe. */
+  anim?: 'reveal' | 'pulse';
+  /** Expose as `role="img"` with this label; omit for decorative (aria-hidden). */
+  label?: string;
+  /** CSS length for one dot (sets `--dotmatrix-dot`; sanitized — a value that
+   *  is not a plain length/calc expression is dropped). */
+  dot?: string;
+  /** CSS length for the gap between dots (sets `--dotmatrix-gap`; sanitized
+   *  the same way as `dot`). */
+  gap?: string;
+  /** `'mask'` returns a single `.ui-icon` element masked by the glyph bitmap
+   *  (one DOM node, not GLYPH_SIZE²) — the icon-at-scale path. Inherits
+   *  `currentColor`; the cell-mode options above don't apply. Needs the
+   *  `.ui-icon` rule from `@ponchia/ui/css`. */
+  render?: 'mask';
+  /** With `render: 'mask'`, the icon size (sets `--icon-size`; defaults to
+   *  `1em`; sanitized to a length/calc allowlist). */
+  size?: string;
+}
+
+/** The grid edge length (rows = cols = 16). */
+export declare const GLYPH_SIZE: 16;
+
+/** The frozen name→bitmap registry. */
+export declare const GLYPHS: Readonly<Record<GlyphName, Glyph>>;
+
+/** Every glyph name, frozen and sorted. */
+export declare const GLYPH_NAMES: readonly GlyphName[];
+
+/** The raw bitmap rows for a glyph, or `undefined` if the name is unknown. */
+export declare function glyph(name: GlyphNameInput): Glyph | undefined;
+
+/** 256 cell descriptors (row-major), or `[]` if unknown. */
+export declare function glyphCells(name: GlyphNameInput): GlyphCell[];
+
+/** A full `.ui-dotmatrix` HTML string for a glyph (`''` if unknown). */
+export declare function renderGlyph(name: GlyphNameInput, options?: RenderGlyphOptions): string;