@ponchia/ui 0.3.4 → 0.3.6

package/docs/reference.md

@@ -9,7 +9,7 @@ rendering of every class is the kitchen-sink demo:
 **<https://ponchia.github.io/bronto-ui/>**. Theming knobs and the token
 contract: [docs/theming.md](theming.md).
 
-- 230 classes across 101 component groups
+- 262 classes across 109 component groups
 - Import the typed registry: `import { cls, ui, cx } from '@ponchia/ui/classes'`
 - Tokens as data: `import { cssVars, tokens, themeColor } from '@ponchia/ui/tokens'`
 
@@ -206,6 +206,20 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.caret` | `ui-caret` | base |
 
+### `.ui-carousel`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.carousel` | `ui-carousel` | base |
+| `cls.carouselNext` | `ui-carousel__next` | part |
+| `cls.carouselPrev` | `ui-carousel__prev` | part |
+| `cls.carouselSlide` | `ui-carousel__slide` | part |
+| `cls.carouselStage` | `ui-carousel__stage` | part |
+| `cls.carouselStatus` | `ui-carousel__status` | part |
+| `cls.carouselThumb` | `ui-carousel__thumb` | part |
+| `cls.carouselThumbs` | `ui-carousel__thumbs` | part |
+| `cls.carouselViewport` | `ui-carousel__viewport` | part |
+
 ### `.ui-center`
 
 | Registry key | Class | Kind |
@@ -315,6 +329,8 @@ each one matches a real selector in the stylesheet.
 | `cls.dotmatrixCell` | `ui-dotmatrix__cell` | part |
 | `cls.dotmatrixCellAccent` | `ui-dotmatrix__cell--accent` | modifier |
 | `cls.dotmatrixCellHot` | `ui-dotmatrix__cell--hot` | modifier |
+| `cls.dotmatrixPulse` | `ui-dotmatrix--pulse` | modifier |
+| `cls.dotmatrixReveal` | `ui-dotmatrix--reveal` | modifier |
 
 ### `.ui-dotrule`
 
@@ -390,6 +406,20 @@ each one matches a real selector in the stylesheet.
 | `cls.inputGroup` | `ui-input-group` | base |
 | `cls.inputGroupAddon` | `ui-input-group__addon` | part |
 
+### `.ui-input-icon`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.inputIcon` | `ui-input-icon` | base |
+| `cls.inputIconSlot` | `ui-input-icon__icon` | part |
+| `cls.inputIconEnd` | `ui-input-icon--end` | modifier |
+
+### `.ui-kbd`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.kbd` | `ui-kbd` | base |
+
 ### `.ui-key-value`
 
 | Registry key | Class | Kind |
@@ -402,6 +432,13 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.label` | `ui-label` | base |
 
+### `.ui-lightbox`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.lightbox` | `ui-lightbox` | base |
+| `cls.lightboxClose` | `ui-lightbox__close` | part |
+
 ### `.ui-link`
 
 | Registry key | Class | Kind |
@@ -438,6 +475,17 @@ each one matches a real selector in the stylesheet.
 | `cls.meta` | `ui-meta` | base |
 | `cls.metaItem` | `ui-meta__item` | part |
 
+### `.ui-meter`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.meter` | `ui-meter` | base |
+| `cls.meterFill` | `ui-meter__fill` | part |
+| `cls.meterAccent` | `ui-meter--accent` | modifier |
+| `cls.meterDanger` | `ui-meter--danger` | modifier |
+| `cls.meterSuccess` | `ui-meter--success` | modifier |
+| `cls.meterWarning` | `ui-meter--warning` | modifier |
+
 ### `.ui-modal`
 
 | Registry key | Class | Kind |
@@ -471,6 +519,14 @@ each one matches a real selector in the stylesheet.
 | `cls.numNeg` | `ui-num--neg` | modifier |
 | `cls.numPos` | `ui-num--pos` | modifier |
 
+### `.ui-pagehead`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.pagehead` | `ui-pagehead` | base |
+| `cls.pageheadActions` | `ui-pagehead__actions` | part |
+| `cls.pageheadTitle` | `ui-pagehead__title` | part |
+
 ### `.ui-pagination`
 
 | Registry key | Class | Kind |
@@ -637,6 +693,14 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.status` | `ui-status` | base |
 
+### `.ui-steps`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.steps` | `ui-steps` | base |
+| `cls.stepsItem` | `ui-steps__item` | part |
+| `cls.stepsItemDone` | `ui-steps__item--done` | modifier |
+
 ### `.ui-surface`
 
 | Registry key | Class | Kind |
@@ -721,6 +785,14 @@ each one matches a real selector in the stylesheet.
 | `cls.themetoggleThumb` | `ui-themetoggle__thumb` | part |
 | `cls.themetoggleTrack` | `ui-themetoggle__track` | part |
 
+### `.ui-timeline`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.timeline` | `ui-timeline` | base |
+| `cls.timelineItem` | `ui-timeline__item` | part |
+| `cls.timelineTime` | `ui-timeline__time` | part |
+
 ### `.ui-toast`
 
 | Registry key | Class | Kind |

package/docs/usage.md

@@ -86,6 +86,39 @@ destructive action).
 | toast    | transient, out-of-flow, system-initiated. Danger toasts route to an assertive live region; everything else polite. |
 | tooltip  | supplemental, hover/focus, never essential info (it's not announced reliably; don't hide required content in it). |
 
+## Meter vs progress
+
+Both are a thin horizontal bar; they mean different things.
+
+- **`ui-progress`** — *task* progress: how far an operation has run. Can be
+  indeterminate (`ui-progress--indeterminate`). The fill is always accent.
+- **`ui-meter`** — a *measured static value*: coverage, disk, capacity, a
+  KPI against a target. Never indeterminate. Tone the fill by threshold
+  (`ui.meter({ tone })` → accent/success/warning/danger); the unset
+  default is neutral. Drive the width with the shared `--value` knob
+  (`style="--value: 72"`, 0–100) and author `role="meter"` +
+  `aria-valuenow/min/max` for AT.
+
+Rule of thumb: *something is happening* → progress; *something measures
+this much* → meter.
+
+## Steps, timeline, kbd, input icons
+
+- **`ui-steps`** — a stepper for a multi-step flow. Use an `<ol>`. State is
+  ARIA-driven (the framework rule): the active step is `aria-current="step"`
+  (no class); completed steps take `ui-steps__item--done`. Markers are
+  auto-numbered by CSS counter.
+- **`ui-timeline`** — a vertical event list on a hairline spine (`<ol>` of
+  `ui-timeline__item`, optional `ui-timeline__time`). `aria-current` on an
+  item marks the live/most-recent event.
+- **`ui-kbd`** — an inline keyboard-key glyph. Wrap a `<kbd>`; for a
+  shortcut, use one per key (`<kbd>⌘</kbd> <kbd>K</kbd>`).
+- **`ui-input-icon`** — a leading (or `--end` trailing) icon *inside* one
+  control. This is distinct from `ui-input-group`, whose addon sits
+  *adjacent* to the control. Wrap the input; the icon is decorative
+  (`aria-hidden`) and the input keeps its full width. Don't hand-roll an
+  absolute overlay.
+
 ## Modal: native `<dialog>` vs `is-open`
 
 Prefer the **native `<dialog>`** path — you get top-layer, backdrop and
@@ -94,6 +127,83 @@ when a portal/React modal genuinely can't be a `<dialog>`; then the
 backdrop and focus-trap are **yours** to provide. A drawer is a modal
 that enters from an edge — same rule.
 
+## Carousel & lightbox: one primitive, two skins
+
+`ui-carousel` is a scroll-snap track of `__slide`s wired by `initCarousel`
+(prev/next, keyboard, a `__thumb` strip, the `__status` counter, ARIA).
+Because the track is **native horizontal scroll**, touch and trackpad
+swipe — with momentum — are the browser's; the behavior only keeps the JS
+index in sync with the scroll both ways. Add `data-bronto-carousel-loop`
+to wrap at the ends.
+
+A **lightbox is the same carousel inside a native
+`<dialog class="ui-lightbox">`**, opened with `data-bronto-open` (wired by
+`initDialog`). Do **not** hand-roll an overlay: the `<dialog>` gives the
+top layer, the backdrop, the focus-trap, Escape, and focus-return for
+free — exactly the parts a from-scratch lightbox gets wrong. The inline
+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.** Each glyph is a 16×16 grid = 256 cells (DOM nodes / spans),
+  regardless of mode; `anim: 'reveal'` adds a per-cell `--i` (≈doubles the
+  string size). Fine for display marks and the odd inline icon — but don't
+  render hundreds at once (e.g. one in every row of a long table) without
+  measuring.
+
 ## When to add a behavior
 
 The CSS is the framework; `@ponchia/ui/behaviors` is the *sanctioned*

package/fonts/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2024 The Doto Project Authors (https://github.com/oliverlalan/Doto)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/glyphs/glyphs.d.ts

@@ -0,0 +1,102 @@
+/** @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'
+  | 'chevron-down'
+  | 'chevron-left'
+  | 'chevron-right'
+  | 'chevron-up'
+  | 'clock'
+  | 'close'
+  | 'download'
+  | 'edit'
+  | 'eye'
+  | 'eye-off'
+  | 'file'
+  | 'folder'
+  | 'gear'
+  | 'grid'
+  | 'heart'
+  | 'home'
+  | 'info'
+  | 'link'
+  | 'lock'
+  | 'mail'
+  | 'menu'
+  | 'minus'
+  | 'moon'
+  | 'more-horizontal'
+  | 'more-vertical'
+  | 'pause'
+  | 'play'
+  | 'plus'
+  | 'refresh'
+  | 'search'
+  | 'spark'
+  | 'star'
+  | 'sun'
+  | 'trash'
+  | 'upload'
+  | 'user'
+  | 'warning';
+
+/** 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;
+}
+
+/** 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;