@ponchia/ui 0.2.2 → 0.3.1

package/README.md

@@ -1,9 +1,33 @@
 # @ponchia/ui
 
+[![npm](https://img.shields.io/npm/v/@ponchia/ui?logo=npm)](https://www.npmjs.com/package/@ponchia/ui)
+[![npm provenance](https://img.shields.io/badge/npm-provenance-blue?logo=npm)](https://www.npmjs.com/package/@ponchia/ui#provenance)
+[![runtime deps](https://img.shields.io/badge/runtime%20deps-0-brightgreen)](package.json)
+[![bundle](https://img.shields.io/badge/dist-~54kB%20%2F%20~10kB%20gzip-informational)](scripts/check-dist.mjs)
+[![CI](https://github.com/Ponchia/bronto-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/Ponchia/bronto-ui/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
 Shared UI framework for Bronto personal projects. Nothing-inspired:
 monochrome surfaces, a single red accent, dot-matrix display type (Doto),
 flat hairline borders, restrained motion. CSS-first and framework-agnostic.
 
+**New here?** → [Getting started](#getting-started) ·
+[Reference](docs/reference.md) · [Theming](docs/theming.md) ·
+[Roadmap](ROADMAP.md) · [Contributing](CONTRIBUTING.md)
+
+> **Editor IntelliSense.** The package ships a VS Code CSS Custom Data
+> file so every design token autocompletes inside `var(--…)`. Add to
+> your `.vscode/settings.json`:
+>
+> ```json
+> {
+>   "css.customData": ["node_modules/@ponchia/ui/classes/vscode.css-custom-data.json"]
+> }
+> ```
+
+**[Live demo →](https://ponchia.github.io/bronto-ui/)** — the kitchen
+sink (every component, light/dark, RTL, theming) deployed from `demo/`.
+
 ## Use
 
 Install from npm (public, no registry config):
@@ -18,30 +42,33 @@ npm i @ponchia/ui
 > deliberately distinct from the package name. See
 > [`docs/architecture.md`](docs/architecture.md).
 
-Import the full theme (includes responsive breakpoints):
-
-```css
-@import '@ponchia/ui/css';
-```
-
-Or the core bundle if the app manages its own responsive layer:
+Import the theme (one bundle — `ui-*` components carry their own
+breakpoints, so there is no separate core/full split as of 0.3.0):
 
 ```css
-@import '@ponchia/ui/css/core.css';
+@import '@ponchia/ui/css';        /* === @ponchia/ui/css/core.css */
 ```
 
 **Prebuilt single file (recommended for apps without a CSS bundler).**
-`@ponchia/ui/css` is a 17-deep `@import` graph — fine through a bundler,
-a load waterfall over plain HTTP. The package also ships flattened,
-minified bundles with no `@import` chain:
+`@ponchia/ui/css` is a wide `@import` fan-out (~14 leaves, one level
+deep) — fine through a bundler, a load waterfall over plain HTTP. The
+package also ships one flattened, minified bundle with no `@import`
+chain:
 
 ```css
-@import '@ponchia/ui';               /* → dist/bronto.css, full   */
-@import '@ponchia/ui/dist/bronto-core.css';   /* core, no responsive */
+@import '@ponchia/ui';   /* → dist/bronto.css, the whole framework */
 ```
 
-~62 kB raw / ~11 kB gzip, one request, same `@layer bronto`. Source CSS,
-tokens/classes/behaviors entrypoints are unchanged — use whichever fits.
+~54 kB raw / ~10 kB gzip, one request, same `@layer bronto`. (The
+enforced ceiling lives in `scripts/check-dist.mjs`, not this prose —
+treat these figures as indicative.) Source CSS, tokens/classes/behaviors
+entrypoints are unchanged — use whichever fits.
+
+> **The package root is CSS-only.** `@ponchia/ui` (the `.` export)
+> resolves to a stylesheet — `@import '@ponchia/ui'` in CSS, never
+> `import '@ponchia/ui'` in JS. There is no JS module at the root; the
+> JS entrypoints are the explicit subpaths `@ponchia/ui/tokens`,
+> `/classes`, and `/behaviors` (see [Entrypoints](#entrypoints)).
 
 ### Browser support
 
@@ -59,10 +86,14 @@ font instead, import everything except `fonts.css` and override `--display` /
 
 Everything ships inside a single `@layer bronto`, so any un-layered CSS in
 your app overrides the framework without a specificity fight or `!important`.
-The layer is applied by the `css` and `css/core.css` bundles only —
-importing an individual leaf such as `@ponchia/ui/css/primitives.css`
-directly is **unlayered** (full specificity), which is an intentional
-escape hatch, not the default path.
+
+> **Leaf imports are layer-safe by default.** Every per-leaf export —
+> `@ponchia/ui/css/primitives.css`, etc. — is self-wrapped in
+> `@layer bronto`, so mixing the bundle with individual leaves (e.g.
+> per-route CSS splitting in SvelteKit/Astro) is safe: no silent
+> cascade inversion. The deliberate full-specificity escape hatch is
+> the explicit `@ponchia/ui/css/unlayered/<leaf>.css` path — use it
+> only when you *want* an unlayered override, never by accident.
 
 Set `data-theme="light"` or `data-theme="dark"` on `<html>`; defaults follow
 `prefers-color-scheme`.
@@ -90,7 +121,9 @@ themeColor('dark').accent; // → "#ff3b41"
 ```
 
 `behaviors` wires `[data-bronto-theme-toggle]`, `[data-bronto-dismiss]` /
-`[data-bronto-dismissible]`, `[data-bronto-disclosure]`, and native
+`[data-bronto-dismissible]`, `[data-bronto-disclosure]`,
+`[data-bronto-menu]` (`initMenu`: Escape / outside-click /
+close-on-activate for a `<details>` `.ui-menu` dropdown), and native
 `<dialog>` glue (`initDialog`: `[data-bronto-open]` / `[data-bronto-close]`
 / `[data-bronto-dialog-light]`). `toast(message, { tone, title, duration })`
 pushes into a shared, body-anchored stack. Each initializer is SSR-safe and
@@ -112,74 +145,70 @@ modules, so it is also a live integration test.
 | `overlay.css`    | modal + drawer (native `<dialog>`), dropdown menu             |
 | `disclosure.css` | tabs, accordion (`<details>`), segmented, breadcrumb, pagination, avatar |
 | `table.css`      | `ui-table` dense / comfortable                                |
-| `app.css`        | admin shell: rail, topbar, toolbar, panel, metrics            |
-| `navigation.css` | site nav, menu, theme toggle (dot indicator)                  |
-| `typography.css` | display headings, eyebrows, legacy `.button`                  |
-| `content.css`    | `.ui-prose` — Markdown/raw-HTML long-form, zero per-element classes |
-| `cards.css`      | semantic content cards (token-driven)                         |
-| `layout.css`     | site shell, hero, grids                                       |
-| `responsive.css` | breakpoint overrides                                          |
+| `app.css`        | admin shell: `ui-app-shell`/`-rail`/`-topbar`/`-toolbar`/`-panel`/`-nav`/`-metrics` |
+| `navigation.css` | `ui-themetoggle` (dot-thumb switch)                           |
+| `site.css`       | content-site shell: `ui-container`, `ui-siteheader`/`ui-sitenav` (aria-current), `ui-sitemenu`, `ui-sitefooter`, `ui-skiplink`, `ui-tags`, `ui-meta` |
+| `content.css`    | `.ui-prose` Markdown/raw-HTML long-form (zero classes) + `ui-quote` pull-quote |
 
-## Demo
+## Getting started
 
-`demo/index.html` is a kitchen sink covering every primitive in both themes.
-Serve the package root and open `/demo/`:
+| Consumer                | Guide                                                              |
+| ----------------------- | ------------------------------------------------------------------ |
+| Astro                   | [`docs/getting-started/astro.md`](docs/getting-started/astro.md)   |
+| SvelteKit               | [`docs/getting-started/sveltekit.md`](docs/getting-started/sveltekit.md) |
+| Vanilla / Vite / plain  | [`docs/getting-started/vanilla.md`](docs/getting-started/vanilla.md) |
+| React / Solid (snippet) | [`docs/getting-started/react-solid.md`](docs/getting-started/react-solid.md) |
+| Tailwind / cascade-layer interop | [`docs/interop/tailwind.md`](docs/interop/tailwind.md)    |
 
-```bash
-python3 -m http.server -d . 8080   # then open http://localhost:8080/demo/
-```
+Each covers the CSS import location, the **no-flash** `applyStoredTheme`
+head-script pattern, behavior init/cleanup in that framework's lifecycle,
+and SSR caveats. Index: [`docs/integration.md`](docs/integration.md).
 
-## Develop
-
-```bash
-npm install        # stylelint + jsdom (test only)
-npm run check      # lint + 5 integrity checks (exports, tokens, classes, dist, pack)
-npm test           # node:test — pure modules + jsdom behavior tests
-npm run lint:fix   # auto-fix the safe stylistic rules + logical properties
-npm run tokens:build  # regenerate tokens/index.json from tokens/index.js
-npm run dist:build    # rebuild the flattened dist/ bundles
-```
-
-`npm run check` enforces that the data mirrors cannot drift from the CSS:
-exports/import-graph integrity, `tokens.css` ⇄ `tokens/index.{js,json}`, the
-`classes` registry ⇄ the `.ui-*` selectors, `dist/` ⇄ `css/` (fresh + in
-budget), and that the published tarball ships only the intended files.
-
-Visual + a11y regression is a separate suite (real browser, so not in the
-zero-dep core check):
-
-```bash
-npx playwright test   # demo screenshots (light/dark/RTL) + axe-core WCAG
-```
-
-It is pinned to a Playwright container so baselines are byte-stable; the
-committed baselines under `test/e2e/__screenshots__` were authored in that
-same image. CI (`.github/workflows/ci.yml`) runs both the `check` job and a
-containerised `visual` job on every branch push and PR. It never publishes —
-a push to `main` ships nothing.
-
-## Release
+## Demo
 
-Releases publish to npm and are tag-driven:
+`demo/index.html` is a kitchen sink covering every primitive in both
+themes — it drives itself with the real behavior modules, so it is also a
+live integration test. Serve the package root and open `/demo/`:
 
 ```bash
-# 1. bump "version" in package.json, land on main, let CI go green
-git tag vX.Y.Z && git push origin vX.Y.Z
+python3 -m http.server -d . 8080   # then open http://localhost:8080/demo/
 ```
 
-The tag triggers `.github/workflows/release.yml`: `validate` (read-only
-checks + tag↔version match) → `publish-npm` (only if validate passes) +
-`release-notes`. **The npm publish is the gate** — a failing check means
-the version never reaches npm, so consumers never resolve it. GitHub also
-serves the raw tag tarball ungated, but that is a legacy/fallback path, not
-the documented install. See [`docs/architecture.md`](docs/architecture.md).
-
-Published: `@ponchia/ui` is live on npm (latest `0.2.1`), released by CI
-with provenance. The `@ponchia` scope and the `NPM_TOKEN` repo secret are
-in place, so a pushed `vX.Y.Z` tag is all a release needs.
+## Develop & release
+
+Contributor setup, the 14 `check` gates, the e2e suite, the visual-
+baseline workflow, the deprecation policy and the tag-driven release
+flow all live in **[CONTRIBUTING.md](CONTRIBUTING.md)**. Direction and
+scope: **[ROADMAP.md](ROADMAP.md)**.
+
+## Versioning
+
+Pre-1.0 and deliberately so. **Until `1.0.0`, breaking changes ship in
+the _minor_** (`0.x.0`); patches (`0.x.y`) are non-breaking. This is the
+standard 0.x reading of SemVer, stated explicitly because this framework
+dresses several apps:
+
+- Because breaking changes bump the **minor**, the protective range is
+  the patch range. At `0.x` npm resolves **both** `^0.3.0` and `~0.3.0`
+  to `>=0.3.0 <0.4.0` — they are equivalent here, and either gives you
+  only non-breaking `0.3.x` patches while holding back the next
+  (breaking) `0.4.0`. Pin either; pin an **exact** version if you want
+  zero surprise and to adopt each minor deliberately.
+- Every breaking change is called out in [`CHANGELOG.md`](CHANGELOG.md)
+  under a **BREAKING** heading with a migration note.
+
+**What is contractual** (changes are breaking): the `--accent`
+derivation and token **names** (incl. `--accent-text`, `--focus-ring`);
+the `.ui-*` class names and `cls`/recipe names; the `data-bronto-*`
+behavior attributes; each behavior's return-cleanup contract. **What is
+not** (may change in any release): token _values_ (visual tuning), the
+internal leaf-file boundaries and `@layer` internals, and anything
+explicitly marked legacy/deprecated. Full token contract:
+[`docs/theming.md`](docs/theming.md).
 
 ## Consumers
 
-Built for two shapes of app: a content/marketing site (imports
-`@ponchia/ui/css/core.css`) and an admin dashboard (imports the full
-`@ponchia/ui/css`). Consuming apps depend on it via `@ponchia/ui`.
+Built for two shapes of app: a content/marketing site (`ui-site*`,
+`ui-prose`) and an admin dashboard (`ui-app-*` shell). Both import the
+one bundle `@ponchia/ui` (or `@ponchia/ui/css`); consuming apps depend
+on it via `@ponchia/ui`.

package/behaviors/index.d.ts

@@ -39,6 +39,59 @@ export declare function dismissible(opts?: DelegateOpts): Cleanup;
 /** Wire `[data-bronto-disclosure]` triggers. Returns a cleanup function. */
 export declare function initDisclosure(opts?: DelegateOpts): Cleanup;
 
+/**
+ * Close affordances (Escape, outside-click, close-on-activate) for a
+ * native `<details data-bronto-menu>` dropdown holding a `.ui-menu`.
+ * Not a full ARIA menu by design. Returns a cleanup function.
+ */
+export declare function initMenu(opts?: DelegateOpts): Cleanup;
+
+/**
+ * Accessible validation glue for `<form data-bronto-validate>`:
+ * progressive enhancement over the Constraint Validation API. Sets
+ * `aria-invalid`, writes `validationMessage` into the field's
+ * `[data-bronto-error]` / `.ui-hint` slot (linked via
+ * `aria-describedby`), and on invalid submit fills the form's
+ * `[data-bronto-error-summary]` with focusable links and blocks submit.
+ * Works without JS (native validation). Returns a cleanup function.
+ */
+export declare function initFormValidation(opts?: DelegateOpts): Cleanup;
+
+/**
+ * Editable combobox with a filtered listbox popup (WAI-ARIA APG
+ * pattern), dependency-free and CSS-anchored. Wires
+ * `[data-bronto-combobox]` (input `role=combobox` +
+ * `.ui-combobox__list` of `role=option`): ids, `aria-expanded` /
+ * `aria-controls` / `aria-activedescendant`, type-to-filter, full
+ * keyboard, pointer select, outside-click close. Emits `bronto:change`
+ * ({ detail: { value } }) on selection. SSR-safe, idempotent per
+ * instance. Returns a cleanup function.
+ */
+export declare function initCombobox(opts?: DelegateOpts): Cleanup;
+
+/**
+ * Collision-aware popover, dependency-free. A `[data-bronto-popover]`
+ * trigger toggles the `.ui-popover` panel it names; the panel flips
+ * above when it would overflow the viewport and its inline edge is
+ * clamped on-screen. Uses the native top layer when the panel has
+ * `popover` and the Popover API exists, else an `.is-open` class.
+ * Manages `aria-expanded`/`aria-controls`, Escape + outside-click
+ * close, scroll/resize reposition. Returns a cleanup function.
+ */
+export declare function initPopover(opts?: DelegateOpts): Cleanup;
+
+/**
+ * Client-side sortable + selectable data table for
+ * `[data-bronto-sortable]`. Header `.ui-table__sort` / `th[data-sort]`
+ * cycles `aria-sort` and reorders the tbody (numeric- or
+ * locale-string-aware); `[data-bronto-select-all]` toggles
+ * `[data-bronto-select]` rows + `aria-selected` with synced
+ * checked/indeterminate state. Emits `bronto:selectionchange`
+ * ({ detail: { count } }). SSR-safe, idempotent per table. Returns a
+ * cleanup function.
+ */
+export declare function initTableSort(opts?: DelegateOpts): Cleanup;
+
 /**
  * Wire `[data-bronto-tabs]` groups with the WAI-ARIA Tabs keyboard
  * pattern (roving tabindex, Arrow/Home/End, aria-selected, panel sync).