@ponchia/ui 0.3.5 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/CHANGELOG.md +945 -0
  2. package/README.md +31 -7
  3. package/behaviors/index.d.ts +11 -0
  4. package/behaviors/index.js +109 -0
  5. package/classes/index.d.ts +3 -0
  6. package/classes/index.js +3 -0
  7. package/classes/vscode.css-custom-data.json +4 -12
  8. package/css/dataviz.css +96 -0
  9. package/css/dots.css +70 -4
  10. package/css/skins.css +54 -0
  11. package/css/tokens.css +4 -10
  12. package/dist/bronto.css +1 -1
  13. package/dist/css/dataviz.css +1 -0
  14. package/dist/css/dots.css +1 -1
  15. package/dist/css/skins.css +1 -0
  16. package/dist/css/tokens.css +1 -1
  17. package/docs/adr/0001-color-system.md +272 -0
  18. package/docs/contrast.md +170 -51
  19. package/docs/reference.md +13 -9
  20. package/docs/theming.md +66 -1
  21. package/docs/usage.md +99 -0
  22. package/glyphs/glyphs.d.ts +115 -0
  23. package/glyphs/glyphs.js +1063 -0
  24. package/llms.txt +54 -4
  25. package/package.json +63 -5
  26. package/react/index.d.ts +36 -0
  27. package/react/index.js +67 -0
  28. package/solid/index.d.ts +36 -0
  29. package/solid/index.js +67 -0
  30. package/tokens/charts.d.ts +37 -0
  31. package/tokens/charts.js +96 -0
  32. package/tokens/charts.json +61 -0
  33. package/tokens/index.d.ts +3 -3
  34. package/tokens/index.js +4 -8
  35. package/tokens/index.json +8 -16
  36. package/tokens/resolved.json +9 -13
  37. package/tokens/skins.d.ts +27 -0
  38. package/tokens/skins.js +62 -0
  39. package/tokens/tokens.dtcg.json +4 -24
package/llms.txt CHANGED
@@ -2,8 +2,9 @@
2
2
 
3
3
  > CSS-first, framework-agnostic UI framework. Zero runtime dependencies.
4
4
  > One `@layer bronto` cascade, a typed class vocabulary, design tokens as
5
- > data, and optional SSR-safe vanilla behaviors. Nothing-inspired:
6
- > monochrome surfaces, a single rationed accent, dot-matrix display type.
5
+ > data, and optional SSR-safe vanilla behaviors. Token-driven restraint:
6
+ > monochrome by default, one rationed accent, dot-matrix display type, with
7
+ > opt-in colorways + a colourblind-safe data-viz palette layered on top.
7
8
  >
8
9
  > This file orients an LLM/agent. The authoritative, always-correct API
9
10
  > is the TypeScript declarations shipped in this package (paths below):
@@ -45,6 +46,49 @@ Optional vanilla behaviors (theme toggle, etc. — SSR-safe, tree-shakeable):
45
46
  import { applyStoredTheme } from '@ponchia/ui/behaviors';
46
47
  ```
47
48
 
49
+ For React/Solid, optional thin hook bindings over those behaviors (peer deps
50
+ `react` / `solid-js`, optional — core stays zero-dep):
51
+
52
+ ```js
53
+ import { useDialog, useToast } from '@ponchia/ui/react'; // or '@ponchia/ui/solid'
54
+ ```
55
+
56
+ Optional display glyphs — dot-matrix bitmaps on the `.ui-dotmatrix` primitive
57
+ (decorative by default; `renderGlyph` is SSR-safe, `initDotGlyph` is the DOM form):
58
+
59
+ ```js
60
+ import { renderGlyph, GLYPH_NAMES } from '@ponchia/ui/glyphs';
61
+ el.innerHTML = renderGlyph('check', { label: 'Done' });
62
+ ```
63
+
64
+ Optional display colorways — opt-in, never in the default bundle. Root-level,
65
+ like `data-theme` (the derived accent family only recomputes at `:root`):
66
+
67
+ ```html
68
+ <link rel="stylesheet" href="@ponchia/ui/css/skins.css" />
69
+ <html data-bronto-skin="amber-crt | phosphor-green | e-ink">
70
+ ```
71
+
72
+ Each re-points the one `--accent` (OKLCH, per-theme, contrast-gated); status
73
+ colours and the neutral canvas are untouched. Details in `docs/theming.md`.
74
+
75
+ Optional data-viz palette for dashboards — opt-in, charts-only (never UI
76
+ chrome), never in the default bundle:
77
+
78
+ ```html
79
+ <link rel="stylesheet" href="@ponchia/ui/css/dataviz.css" />
80
+ ```
81
+
82
+ ```js
83
+ import charts from '@ponchia/ui/charts.json' with { type: 'json' };
84
+ // charts.dark.categorical → ['#ff3b41', …] (series 0 = the resolved accent)
85
+ ```
86
+
87
+ `--chart-1..8` (categorical; series 1 = accent; colourblind-safe, gated under
88
+ simulated protan/deutan/tritan), `--chart-seq-*` (sequential), `--chart-div-*`
89
+ (diverging), and `--chart-pattern-1..8` (dot-matrix fills — pair colour N with
90
+ pattern N; colour is never the sole signal). Details in `docs/theming.md`.
91
+
48
92
  ## Authoritative offline references (shipped in this package)
49
93
 
50
94
  Read these from `node_modules/@ponchia/ui/` — no network needed:
@@ -70,6 +114,9 @@ Read these from `node_modules/@ponchia/ui/` — no network needed:
70
114
  `#rrggbb` / `rgba(...)` per theme (var() + color-mix() evaluated).
71
115
  Use this for non-CSS render targets: MapLibre/canvas/WebGL/SVG.
72
116
  - `behaviors/index.d.ts` — typed signatures for the optional behaviors.
117
+ - `glyphs/glyphs.d.ts` — the `GlyphName` literal union plus `renderGlyph` /
118
+ `glyphCells` signatures for the display glyphs. (The DOM form,
119
+ `initDotGlyph`, is declared in `behaviors/index.d.ts`.)
73
120
  - `classes/vscode.css-custom-data.json` — editor autocomplete for tokens.
74
121
 
75
122
  ## Human-browsable references (not shipped in the npm tarball, by design)
@@ -86,6 +133,9 @@ Read these from `node_modules/@ponchia/ui/` — no network needed:
86
133
  - Prefer the `ui.*()` recipes over hand-concatenating modifier strings.
87
134
  - Override framework styles by writing your own rules outside
88
135
  `@layer bronto` — not with higher specificity or `!important`.
89
- - The accent color is deliberately rationed (monochrome + one accent).
90
- Do not introduce new hues; theme via the documented tokens only.
136
+ - Color is tiered (ADR-0001): neutral canvas · one rationed accent · locked
137
+ status · display expression · opt-in data-viz. Theme via the documented
138
+ tokens — re-point `--accent` (or a `data-bronto-skin` colorway), use status
139
+ tokens for status, and `--chart-*` (from `css/dataviz.css`) for charts only.
140
+ Don't add raw hues to components; `check:color-policy` enforces this.
91
141
  - Pre-1.0 SemVer: breaking changes ship in the *minor*. Pin `~0.x`.
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "@ponchia/ui",
3
- "version": "0.3.5",
3
+ "version": "0.4.0",
4
4
  "type": "module",
5
- "description": "Nothing-inspired, CSS-first UI framework — monochrome design tokens, one rationed accent, dot-matrix motifs, zero runtime dependencies, framework-agnostic.",
5
+ "description": "CSS-first, framework-agnostic UI framework — token-driven restraint (monochrome by default, one rationed accent), OKLCH colorways, a dot-matrix icon set, a colourblind-safe data-viz palette, dot-matrix motifs, zero runtime dependencies.",
6
6
  "keywords": [
7
7
  "css",
8
8
  "ui",
@@ -13,12 +13,18 @@
13
13
  "css-layers",
14
14
  "nothing",
15
15
  "monochrome",
16
+ "oklch",
17
+ "colorways",
18
+ "icons",
19
+ "data-visualization",
20
+ "wcag",
16
21
  "framework-agnostic",
17
22
  "zero-dependencies",
18
23
  "dark-mode",
19
24
  "accessibility"
20
25
  ],
21
26
  "license": "MIT",
27
+ "author": "Ponchia (https://github.com/Ponchia)",
22
28
  "repository": {
23
29
  "type": "git",
24
30
  "url": "git+https://github.com/Ponchia/bronto-ui.git"
@@ -39,12 +45,17 @@
39
45
  "tokens",
40
46
  "classes",
41
47
  "behaviors",
48
+ "glyphs",
49
+ "react",
50
+ "solid",
42
51
  "shiki",
43
52
  "llms.txt",
53
+ "CHANGELOG.md",
44
54
  "docs/reference.md",
45
55
  "docs/theming.md",
46
56
  "docs/contrast.md",
47
- "docs/usage.md"
57
+ "docs/usage.md",
58
+ "docs/adr/0001-color-system.md"
48
59
  ],
49
60
  "style": "./dist/bronto.css",
50
61
  "scripts": {
@@ -56,6 +67,9 @@
56
67
  "dtcg:build": "node scripts/gen-dtcg.mjs",
57
68
  "resolved:build": "node scripts/gen-resolved.mjs",
58
69
  "dts:build": "node scripts/gen-dts.mjs",
70
+ "glyphs:build": "node scripts/gen-glyphs.mjs",
71
+ "skins:build": "node scripts/gen-skins.mjs",
72
+ "charts:build": "node scripts/gen-charts.mjs",
59
73
  "reference:build": "node scripts/gen-reference.mjs",
60
74
  "contrast:build": "node scripts/gen-contrast.mjs",
61
75
  "vscode:build": "node scripts/gen-vscode-data.mjs",
@@ -64,6 +78,12 @@
64
78
  "check:tokens": "node scripts/check-tokens.mjs",
65
79
  "check:classes": "node scripts/check-classes.mjs",
66
80
  "check:dts": "node scripts/check-dts.mjs",
81
+ "check:behaviors": "node scripts/check-behaviors.mjs",
82
+ "check:bindings": "node scripts/check-bindings.mjs",
83
+ "check:glyphs": "node scripts/check-glyphs.mjs",
84
+ "check:color-policy": "node scripts/check-color-policy.mjs",
85
+ "check:skins": "node scripts/check-skins.mjs",
86
+ "check:charts": "node scripts/check-charts.mjs",
67
87
  "check:types": "tsc -p tsconfig.json",
68
88
  "check:dtcg": "node scripts/check-dtcg.mjs",
69
89
  "check:resolved": "node scripts/check-resolved.mjs",
@@ -74,9 +94,9 @@
74
94
  "check:reference": "node scripts/check-reference.mjs",
75
95
  "check:contrast": "node scripts/check-contrast.mjs",
76
96
  "check:vscode": "node scripts/check-vscode-data.mjs",
77
- "check": "npm run lint && npm run check:format && npm run check:exports && npm run check:tokens && npm run check:classes && npm run check:dts && npm run check:types && npm run check:dtcg && npm run check:resolved && npm run check:shiki && npm run check:dist && npm run check:pack && npm run check:release && npm run check:reference && npm run check:contrast && npm run check:vscode",
97
+ "check": "npm run lint && npm run check:format && npm run check:exports && npm run check:tokens && npm run check:classes && npm run check:dts && npm run check:types && npm run check:dtcg && npm run check:resolved && npm run check:shiki && npm run check:dist && npm run check:pack && npm run check:release && npm run check:reference && npm run check:contrast && npm run check:vscode && npm run check:behaviors && npm run check:bindings && npm run check:glyphs && npm run check:color-policy && npm run check:skins && npm run check:charts",
78
98
  "test": "node --test \"test/*.test.mjs\"",
79
- "prepack": "npm run tokens:build && npm run dtcg:build && npm run resolved:build && npm run dts:build && npm run reference:build && npm run contrast:build && npm run vscode:build && npm run dist:build",
99
+ "prepack": "npm run tokens:build && npm run dtcg:build && npm run resolved:build && npm run dts:build && npm run reference:build && npm run contrast:build && npm run vscode:build && npm run skins:build && npm run charts:build && npm run dist:build && npm run glyphs:build",
80
100
  "prepublishOnly": "npm run check && npm test"
81
101
  },
82
102
  "devDependencies": {
@@ -89,6 +109,18 @@
89
109
  "stylelint-use-logical": "^2.1.3",
90
110
  "typescript": "^6.0.3"
91
111
  },
112
+ "peerDependencies": {
113
+ "react": ">=18",
114
+ "solid-js": ">=1.6"
115
+ },
116
+ "peerDependenciesMeta": {
117
+ "react": {
118
+ "optional": true
119
+ },
120
+ "solid-js": {
121
+ "optional": true
122
+ }
123
+ },
92
124
  "exports": {
93
125
  ".": {
94
126
  "style": "./dist/bronto.css",
@@ -112,6 +144,8 @@
112
144
  "./css/disclosure.css": "./dist/css/disclosure.css",
113
145
  "./css/table.css": "./dist/css/table.css",
114
146
  "./css/app.css": "./dist/css/app.css",
147
+ "./css/skins.css": "./dist/css/skins.css",
148
+ "./css/dataviz.css": "./dist/css/dataviz.css",
115
149
  "./css/unlayered/tokens.css": "./css/tokens.css",
116
150
  "./css/unlayered/fonts.css": "./css/fonts.css",
117
151
  "./css/unlayered/base.css": "./css/base.css",
@@ -127,6 +161,8 @@
127
161
  "./css/unlayered/disclosure.css": "./css/disclosure.css",
128
162
  "./css/unlayered/table.css": "./css/table.css",
129
163
  "./css/unlayered/app.css": "./css/app.css",
164
+ "./css/unlayered/skins.css": "./css/skins.css",
165
+ "./css/unlayered/dataviz.css": "./css/dataviz.css",
130
166
  "./tokens": {
131
167
  "types": "./tokens/index.d.ts",
132
168
  "default": "./tokens/index.js"
@@ -141,6 +177,7 @@
141
177
  "./docs/theming.md": "./docs/theming.md",
142
178
  "./docs/contrast.md": "./docs/contrast.md",
143
179
  "./docs/usage.md": "./docs/usage.md",
180
+ "./docs/adr/0001-color-system.md": "./docs/adr/0001-color-system.md",
144
181
  "./classes": {
145
182
  "types": "./classes/index.d.ts",
146
183
  "default": "./classes/index.js"
@@ -149,6 +186,27 @@
149
186
  "types": "./behaviors/index.d.ts",
150
187
  "default": "./behaviors/index.js"
151
188
  },
189
+ "./glyphs": {
190
+ "types": "./glyphs/glyphs.d.ts",
191
+ "default": "./glyphs/glyphs.js"
192
+ },
193
+ "./react": {
194
+ "types": "./react/index.d.ts",
195
+ "default": "./react/index.js"
196
+ },
197
+ "./solid": {
198
+ "types": "./solid/index.d.ts",
199
+ "default": "./solid/index.js"
200
+ },
201
+ "./skins": {
202
+ "types": "./tokens/skins.d.ts",
203
+ "default": "./tokens/skins.js"
204
+ },
205
+ "./charts": {
206
+ "types": "./tokens/charts.d.ts",
207
+ "default": "./tokens/charts.js"
208
+ },
209
+ "./charts.json": "./tokens/charts.json",
152
210
  "./fonts/*": "./fonts/*"
153
211
  }
154
212
  }
package/react/index.d.ts ADDED
@@ -0,0 +1,36 @@
1
+ /** @ponchia/ui/react — thin React bindings over the SSR-safe behaviors.
2
+ * Optional peer dep `react`. Hooks run a delegated behavior for the
3
+ * component's lifetime; they take the same options as the behavior and
4
+ * return void (the cleanup is wired to unmount). See behaviors/index.d.ts. */
5
+ import type {
6
+ Cleanup,
7
+ DelegateOpts,
8
+ ThemeStorageOpts,
9
+ ToastOpts,
10
+ } from '../behaviors/index.js';
11
+
12
+ /** Run any delegated behavior for the component's lifetime (init on mount,
13
+ * its returned cleanup on unmount). The behavior is run once. */
14
+ export declare function useBrontoBehavior(
15
+ init: (opts?: DelegateOpts) => Cleanup | void,
16
+ opts?: DelegateOpts,
17
+ ): void;
18
+
19
+ export declare function useThemeToggle(opts?: ThemeStorageOpts & DelegateOpts): void;
20
+ export declare function useDismissible(opts?: DelegateOpts): void;
21
+ export declare function useDisclosure(opts?: DelegateOpts): void;
22
+ export declare function useMenu(opts?: DelegateOpts): void;
23
+ export declare function useFormValidation(opts?: DelegateOpts): void;
24
+ export declare function useCombobox(opts?: DelegateOpts): void;
25
+ export declare function usePopover(opts?: DelegateOpts): void;
26
+ export declare function useTableSort(opts?: DelegateOpts): void;
27
+ export declare function useTabs(opts?: DelegateOpts): void;
28
+ export declare function useDialog(opts?: DelegateOpts): void;
29
+ export declare function useCarousel(opts?: DelegateOpts): void;
30
+ export declare function useDotGlyph(opts?: DelegateOpts): void;
31
+
32
+ /** The `toast()` imperative (no lifecycle of its own). */
33
+ export declare function useToast(): (message: string, opts?: ToastOpts) => Cleanup;
34
+
35
+ export { applyStoredTheme } from '../behaviors/index.js';
36
+ export { cls, ui, cx } from '../classes/index.js';
package/react/index.js ADDED
@@ -0,0 +1,67 @@
1
+ /**
2
+ * @ponchia/ui/react — thin React bindings over @ponchia/ui/behaviors.
3
+ *
4
+ * The CSS is the framework; these are *optional* hooks that wrap the SSR-safe
5
+ * vanilla `init*` behaviors in a component lifecycle (run on mount, clean up on
6
+ * unmount). They are deliberately thin adapters — not a component library — per
7
+ * the architecture ADR. `react` is an optional peer dependency.
8
+ *
9
+ * The behaviors delegate from a root (default `document`), so call a hook once
10
+ * near the relevant subtree; pass `{ root: ref.current }` to scope it. The root
11
+ * is captured on mount — keep it stable (a ref), like any effect dependency.
12
+ *
13
+ * import { useDialog, useToast } from '@ponchia/ui/react';
14
+ * function App() {
15
+ * useDialog(); // wires every .ui-modal under document
16
+ * const toast = useToast();
17
+ * return <button onClick={() => toast('Saved', { tone: 'success' })}>Save</button>;
18
+ * }
19
+ */
20
+ import { useEffect } from 'react';
21
+ import {
22
+ applyStoredTheme,
23
+ initThemeToggle,
24
+ dismissible,
25
+ initDisclosure,
26
+ initMenu,
27
+ initFormValidation,
28
+ initCombobox,
29
+ initPopover,
30
+ initTableSort,
31
+ initTabs,
32
+ initDialog,
33
+ initCarousel,
34
+ initDotGlyph,
35
+ toast,
36
+ } from '../behaviors/index.js';
37
+
38
+ /** Run a delegated behavior for the component's lifetime (init on mount, its
39
+ * returned cleanup on unmount). The behavior is run once; `opts` is captured
40
+ * on mount — pass a stable root (a ref) if you scope it. */
41
+ export function useBrontoBehavior(init, opts) {
42
+ useEffect(() => init(opts), []); // eslint-disable-line react-hooks/exhaustive-deps -- delegated once on mount
43
+ }
44
+
45
+ export const useThemeToggle = (opts) => useBrontoBehavior(initThemeToggle, opts);
46
+ export const useDismissible = (opts) => useBrontoBehavior(dismissible, opts);
47
+ export const useDisclosure = (opts) => useBrontoBehavior(initDisclosure, opts);
48
+ export const useMenu = (opts) => useBrontoBehavior(initMenu, opts);
49
+ export const useFormValidation = (opts) => useBrontoBehavior(initFormValidation, opts);
50
+ export const useCombobox = (opts) => useBrontoBehavior(initCombobox, opts);
51
+ export const usePopover = (opts) => useBrontoBehavior(initPopover, opts);
52
+ export const useTableSort = (opts) => useBrontoBehavior(initTableSort, opts);
53
+ export const useTabs = (opts) => useBrontoBehavior(initTabs, opts);
54
+ export const useDialog = (opts) => useBrontoBehavior(initDialog, opts);
55
+ export const useCarousel = (opts) => useBrontoBehavior(initCarousel, opts);
56
+ export const useDotGlyph = (opts) => useBrontoBehavior(initDotGlyph, opts);
57
+
58
+ /** The `toast()` imperative (no lifecycle of its own). */
59
+ export const useToast = () => toast;
60
+
61
+ // No-flash theme application has to run before paint; do it in an inline head
62
+ // script, not an effect. Re-exported for manual/SSR-bootstrap use.
63
+ export { applyStoredTheme };
64
+
65
+ // Convenience: the framework-agnostic class contract, re-exported so a React
66
+ // consumer needs one import.
67
+ export { cls, ui, cx } from '../classes/index.js';
package/solid/index.d.ts ADDED
@@ -0,0 +1,36 @@
1
+ /** @ponchia/ui/solid — thin Solid bindings over the SSR-safe behaviors.
2
+ * Optional peer dep `solid-js`. Primitives run a delegated behavior for the
3
+ * component's lifetime; they take the same options as the behavior and return
4
+ * void (the cleanup is wired to dispose). See behaviors/index.d.ts. */
5
+ import type {
6
+ Cleanup,
7
+ DelegateOpts,
8
+ ThemeStorageOpts,
9
+ ToastOpts,
10
+ } from '../behaviors/index.js';
11
+
12
+ /** Run any delegated behavior for the component's lifetime (init on mount,
13
+ * its returned cleanup on dispose). */
14
+ export declare function useBrontoBehavior(
15
+ init: (opts?: DelegateOpts) => Cleanup | void,
16
+ opts?: DelegateOpts,
17
+ ): void;
18
+
19
+ export declare function useThemeToggle(opts?: ThemeStorageOpts & DelegateOpts): void;
20
+ export declare function useDismissible(opts?: DelegateOpts): void;
21
+ export declare function useDisclosure(opts?: DelegateOpts): void;
22
+ export declare function useMenu(opts?: DelegateOpts): void;
23
+ export declare function useFormValidation(opts?: DelegateOpts): void;
24
+ export declare function useCombobox(opts?: DelegateOpts): void;
25
+ export declare function usePopover(opts?: DelegateOpts): void;
26
+ export declare function useTableSort(opts?: DelegateOpts): void;
27
+ export declare function useTabs(opts?: DelegateOpts): void;
28
+ export declare function useDialog(opts?: DelegateOpts): void;
29
+ export declare function useCarousel(opts?: DelegateOpts): void;
30
+ export declare function useDotGlyph(opts?: DelegateOpts): void;
31
+
32
+ /** The `toast()` imperative (no lifecycle of its own). */
33
+ export declare function useToast(): (message: string, opts?: ToastOpts) => Cleanup;
34
+
35
+ export { applyStoredTheme } from '../behaviors/index.js';
36
+ export { cls, ui, cx } from '../classes/index.js';
package/solid/index.js ADDED
@@ -0,0 +1,67 @@
1
+ /**
2
+ * @ponchia/ui/solid — thin Solid bindings over @ponchia/ui/behaviors.
3
+ *
4
+ * The CSS is the framework; these are *optional* primitives that wrap the
5
+ * SSR-safe vanilla `init*` behaviors in Solid's lifecycle (run on mount, clean
6
+ * up on dispose). Thin adapters, not a component library (architecture ADR).
7
+ * `solid-js` is an optional peer dependency.
8
+ *
9
+ * Behaviors delegate from a root (default `document`); call a primitive once in
10
+ * a component that owns the relevant subtree, `{ root: el }` to scope it.
11
+ *
12
+ * import { useDialog, useToast } from '@ponchia/ui/solid';
13
+ * function App() {
14
+ * useDialog(); // wires every .ui-modal under document
15
+ * const toast = useToast();
16
+ * return <button onClick={() => toast('Saved', { tone: 'success' })}>Save</button>;
17
+ * }
18
+ */
19
+ import { onMount, onCleanup } from 'solid-js';
20
+ import {
21
+ applyStoredTheme,
22
+ initThemeToggle,
23
+ dismissible,
24
+ initDisclosure,
25
+ initMenu,
26
+ initFormValidation,
27
+ initCombobox,
28
+ initPopover,
29
+ initTableSort,
30
+ initTabs,
31
+ initDialog,
32
+ initCarousel,
33
+ initDotGlyph,
34
+ toast,
35
+ } from '../behaviors/index.js';
36
+
37
+ /** Run a delegated behavior for the component's lifetime (init on mount, its
38
+ * returned cleanup on dispose). */
39
+ export function useBrontoBehavior(init, opts) {
40
+ onMount(() => {
41
+ const cleanup = init(opts);
42
+ if (typeof cleanup === 'function') onCleanup(cleanup);
43
+ });
44
+ }
45
+
46
+ export const useThemeToggle = (opts) => useBrontoBehavior(initThemeToggle, opts);
47
+ export const useDismissible = (opts) => useBrontoBehavior(dismissible, opts);
48
+ export const useDisclosure = (opts) => useBrontoBehavior(initDisclosure, opts);
49
+ export const useMenu = (opts) => useBrontoBehavior(initMenu, opts);
50
+ export const useFormValidation = (opts) => useBrontoBehavior(initFormValidation, opts);
51
+ export const useCombobox = (opts) => useBrontoBehavior(initCombobox, opts);
52
+ export const usePopover = (opts) => useBrontoBehavior(initPopover, opts);
53
+ export const useTableSort = (opts) => useBrontoBehavior(initTableSort, opts);
54
+ export const useTabs = (opts) => useBrontoBehavior(initTabs, opts);
55
+ export const useDialog = (opts) => useBrontoBehavior(initDialog, opts);
56
+ export const useCarousel = (opts) => useBrontoBehavior(initCarousel, opts);
57
+ export const useDotGlyph = (opts) => useBrontoBehavior(initDotGlyph, opts);
58
+
59
+ /** The `toast()` imperative (no lifecycle of its own). */
60
+ export const useToast = () => toast;
61
+
62
+ // No-flash theme application must run before paint — do it in an inline head
63
+ // script, not on mount. Re-exported for manual/SSR-bootstrap use.
64
+ export { applyStoredTheme };
65
+
66
+ // Convenience: the framework-agnostic class contract, re-exported.
67
+ export { cls, ui, cx } from '../classes/index.js';
package/tokens/charts.d.ts ADDED
@@ -0,0 +1,37 @@
1
+ /** @ponchia/ui — GENERATED from tokens/charts.js by scripts/gen-charts.mjs.
2
+ * Do not edit by hand; run `npm run charts:build`. Drift-checked in CI. */
3
+
4
+ /** A theme's data-viz palette. Values are CSS colour strings (OKLCH for the
5
+ * authored series; `var(--accent)` for series 1). For resolved sRGB **hex**
6
+ * (canvas/SVG/charting libs), import `@ponchia/ui/charts.json` instead. */
7
+ export interface ChartTheme {
8
+ /** 8 distinct series colours (index 0 = `var(--accent)`, the brand). */
9
+ categorical: string[];
10
+ /** Single-hue sequential ramp (light→dark), for heatmaps/intensity. */
11
+ sequential: string[];
12
+ /** Diverging ramp (− … neutral … +), for gains/losses. */
13
+ diverging: string[];
14
+ }
15
+
16
+ /** The categorical CSS custom-property names (1-based; `--chart-1` = the accent). */
17
+ export type ChartTokenName =
18
+ | '--chart-1'
19
+ | '--chart-2'
20
+ | '--chart-3'
21
+ | '--chart-4'
22
+ | '--chart-5'
23
+ | '--chart-6'
24
+ | '--chart-7'
25
+ | '--chart-8';
26
+
27
+ /** The opt-in data-viz palette source, per theme (CSS colour strings). */
28
+ export declare const charts: { light: ChartTheme; dark: ChartTheme };
29
+
30
+ /** Series 1 sentinel — the live brand accent. */
31
+ export declare const ACCENT: 'var(--accent)';
32
+
33
+ export declare const CHART_CATEGORICAL: 8;
34
+ export declare const CHART_PATTERN_COUNT: 8;
35
+
36
+ declare const _default: { light: ChartTheme; dark: ChartTheme };
37
+ export default _default;
package/tokens/charts.js ADDED
@@ -0,0 +1,96 @@
1
+ /**
2
+ * @ponchia/ui — Tier-4 data-viz colour module (ADR-0001 step 7).
3
+ *
4
+ * The single source for the opt-in chart palette (`@ponchia/ui/css/dataviz.css`
5
+ * + `tokens/charts.json`). **Charts only, never UI chrome** — `check-color-policy`
6
+ * forbids `var(--chart-*)` in core component CSS. Opt-in: a separate entrypoint,
7
+ * never in the default bundle.
8
+ *
9
+ * Hybrid accent-led: **series 1 is the live `var(--accent)`** (the brand stays
10
+ * series 1, so it re-themes/-skins for free); series 2–8 are an Okabe-Ito-derived
11
+ * colourblind-safe set, authored in OKLCH per-theme (darker in light, brighter
12
+ * in dark) and **gated for pairwise distinguishability under normal + simulated
13
+ * protan/deutan/tritan vision** (scripts/check-charts.mjs). Series 8 is a neutral
14
+ * grey (on-brand, and a useful "other"/baseline series).
15
+ *
16
+ * Colour is never the sole signal: `--chart-pattern-1..8` ship a matching
17
+ * dot-matrix pattern per series (WCAG 1.4.1). Use colour N WITH pattern N.
18
+ *
19
+ * Generated → drift-checked: css/dataviz.css, tokens/charts.json (resolved hex
20
+ * for JS/canvas/SVG/charting libs), tokens/charts.d.ts.
21
+ */
22
+
23
+ /** Series 1 is the live accent (a CSS var, not a fixed hue). Resolved to the
24
+ * theme accent for the JSON/gate. */
25
+ export const ACCENT = 'var(--accent)';
26
+
27
+ /** Series 2–8 — the Okabe-Ito colourblind-safe set, used **verbatim** (the same
28
+ * hues both themes). Authored as sRGB hex on purpose: Okabe-Ito is a published,
29
+ * CVD-proven *set*, and round-tripping through OKLCH (or re-spacing per theme)
30
+ * breaks the careful lightness relationships that make it colourblind-safe —
31
+ * which the CVD gate caught. Series 1 (the accent, per-theme) replaces
32
+ * Okabe-Ito's vermillion; a dark slate-grey is the 8th (a CVD-distinct "other"
33
+ * / baseline, far enough in lightness from the reddish-purple to clear deutan).
34
+ * The sequential/diverging ramps below ARE authored in OKLCH (new work). */
35
+ const FILLS = [
36
+ '#e69f00', // 2 orange
37
+ '#56b4e9', // 3 sky blue
38
+ '#009e73', // 4 bluish green
39
+ '#f0e442', // 5 yellow
40
+ '#0072b2', // 6 blue
41
+ '#cc79a7', // 7 reddish purple
42
+ '#4d5358', // 8 dark slate (CVD-distinct neutral)
43
+ ];
44
+
45
+ export const charts = {
46
+ light: {
47
+ categorical: [ACCENT, ...FILLS],
48
+ sequential: [
49
+ 'oklch(94% 0.03 25deg)',
50
+ 'oklch(85% 0.07 25deg)',
51
+ 'oklch(74% 0.12 25deg)',
52
+ 'oklch(62% 0.16 25deg)',
53
+ 'oklch(50% 0.16 25deg)',
54
+ 'oklch(38% 0.13 25deg)',
55
+ ],
56
+ diverging: [
57
+ 'oklch(45% 0.14 255deg)', // − strong blue
58
+ 'oklch(62% 0.1 250deg)',
59
+ 'oklch(82% 0.05 245deg)',
60
+ 'oklch(90% 0.01 250deg)', // mid neutral
61
+ 'oklch(80% 0.07 60deg)',
62
+ 'oklch(66% 0.13 55deg)',
63
+ 'oklch(56% 0.15 45deg)', // + strong orange
64
+ ],
65
+ },
66
+ dark: {
67
+ categorical: [ACCENT, ...FILLS],
68
+ sequential: [
69
+ 'oklch(30% 0.1 25deg)',
70
+ 'oklch(42% 0.15 25deg)',
71
+ 'oklch(55% 0.17 25deg)',
72
+ 'oklch(68% 0.15 25deg)',
73
+ 'oklch(80% 0.1 25deg)',
74
+ 'oklch(90% 0.05 25deg)',
75
+ ],
76
+ diverging: [
77
+ 'oklch(70% 0.13 250deg)', // − blue
78
+ 'oklch(60% 0.12 252deg)',
79
+ 'oklch(48% 0.08 255deg)',
80
+ 'oklch(40% 0.01 250deg)', // mid neutral
81
+ 'oklch(58% 0.1 60deg)',
82
+ 'oklch(72% 0.13 58deg)',
83
+ 'oklch(80% 0.12 55deg)', // + orange
84
+ ],
85
+ },
86
+ };
87
+
88
+ /** Pattern fills — dot-matrix CSS background-images, the second (non-colour)
89
+ * channel per series. Each uses `--chart-pattern-ink` (set it to the series
90
+ * colour). Index matches the categorical series. */
91
+ export const CHART_PATTERN_COUNT = 8;
92
+
93
+ /** Number of categorical series. */
94
+ export const CHART_CATEGORICAL = 8;
95
+
96
+ export default charts;
package/tokens/charts.json ADDED
@@ -0,0 +1,61 @@
1
+ {
2
+ "$comment": "@ponchia/ui data-viz palette resolved to static hex per theme, for non-CSS render targets (canvas/SVG/charting libs). Series 1 = the resolved brand accent. Generated from tokens/charts.js — do not edit by hand; run `npm run charts:build`. Drift-checked in CI.",
3
+ "light": {
4
+ "categorical": [
5
+ "#d71921",
6
+ "#e69f00",
7
+ "#56b4e9",
8
+ "#009e73",
9
+ "#f0e442",
10
+ "#0072b2",
11
+ "#cc79a7",
12
+ "#4d5358"
13
+ ],
14
+ "sequential": [
15
+ "#ffe4e1",
16
+ "#f9bdb7",
17
+ "#ed8c84",
18
+ "#d55753",
19
+ "#ac3031",
20
+ "#79191b"
21
+ ],
22
+ "diverging": [
23
+ "#0c54a0",
24
+ "#558ac0",
25
+ "#aac8e3",
26
+ "#d9dfe5",
27
+ "#e0b491",
28
+ "#ce7a3b",
29
+ "#b95115"
30
+ ]
31
+ },
32
+ "dark": {
33
+ "categorical": [
34
+ "#ff3b41",
35
+ "#e69f00",
36
+ "#56b4e9",
37
+ "#009e73",
38
+ "#f0e442",
39
+ "#0072b2",
40
+ "#cc79a7",
41
+ "#4d5358"
42
+ ],
43
+ "sequential": [
44
+ "#551112",
45
+ "#8d1a1e",
46
+ "#c13c3b",
47
+ "#e66e68",
48
+ "#f8a49d",
49
+ "#fed2cd"
50
+ ],
51
+ "diverging": [
52
+ "#5aa3ec",
53
+ "#4683c5",
54
+ "#3e5f8a",
55
+ "#44484d",
56
+ "#a56b38",
57
+ "#e18e4b",
58
+ "#f9a870"
59
+ ]
60
+ }
61
+ }