@hussmartinez/ui 0.1.1 → 0.3.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.
package/README.md CHANGED
@@ -130,6 +130,14 @@ Every component renders on the server and hydrates without warnings; end-to-end
130
130
 
131
131
  No styles are evaluated as JavaScript, and nothing needs `unsafe-eval`.
132
132
 
133
+ ## Files from users
134
+
135
+ `FileDropZone` hands you `File` objects. Treat each one as untrusted:
136
+
137
+ - **`accept` is a hint, not a check.** A file's name and type are whatever its sender chose, so the zone's checks only spare people an obvious mistake. Check the contents, and the size, before using a file, as each SDK's file policy does.
138
+ - **Show names as text.** Render `file.name` as a React text child, never through `dangerouslySetInnerHTML` or `innerHTML`. The zone itself never shows a name.
139
+ - **Read in your own code.** The zone never reads a file, so reading, and its limits, stay under your control.
140
+
133
141
  ## Components
134
142
 
135
143
  Every component follows one contract ([ADR 0003](https://github.com/ie-huss-martinez/ui/blob/main/docs/adr/0003-component-contract.md)):
@@ -141,26 +149,59 @@ Every component follows one contract ([ADR 0003](https://github.com/ie-huss-mart
141
149
 
142
150
  | Component | Use it for |
143
151
  |---|---|
144
- | `Button` | Actions. `variant` is `primary`, `secondary` (default), `quiet` or `danger`; `size` is `medium` or `small`; `pressed` makes a toggle button; `startIcon` and `endIcon` take icons |
152
+ | `Button` | Actions. `variant` is `primary`, `secondary` (default), `quiet` or `danger`; `size` is `medium` or `small`; `pressed` shows a toggle state you control, as `ToggleButton` does; `startIcon` and `endIcon` take icons |
145
153
  | `IconButton` | Icon-only actions. `label` is required: it's the accessible name |
154
+ | `ToggleButton` | Turning something on or off, such as loop or the active tool, exposed as `aria-pressed`. `variant` is `secondary` (default) or `quiet`. Controlled with `pressed` and `onPressedChange`, or uncontrolled from `defaultPressed`. Text children, or `icon` with a required `label`. The label stays the same in both states, so a button whose label changes, such as play and pause, is an `IconButton` that swaps its `label` |
146
155
  | `VisuallyHidden` | Text for assistive technology only |
147
156
  | `Toolbar`, `ToolbarGroup`, `ToolbarSeparator` | A row or column of controls with one Tab stop: arrow keys move between items, Home and End jump to the ends. `label` is required on the toolbar and its groups |
148
157
  | `SegmentedControl` | A few mutually exclusive choices side by side. A radio group: arrow keys move and select. Inside a `Toolbar`, it joins the toolbar's arrow keys, and Space or Enter selects |
158
+ | `FileDropZone` | Choosing or dropping files, such as a document to open. Its button opens the system's file picker and is the keyboard and screen reader path; the zone around it takes drops from a pointer, with `data-hm-dragging` while files are over it. `accept` and `multiple` are checked by name, type and count, and folders are turned away; `onFiles` gets the rest, and `onFilesRejected` the others, with a reason. It never reads a file or shows its name, and while it's on the page, a file dropped beside it doesn't open in place of the page; `preventStrayDrops={false}` leaves that to you |
149
159
  | `Dialog` | A modal dialog on the native `<dialog>`: focus moves in and is trapped, the page behind is inert, Escape asks to close through `onOpenChange(false)`, and focus returns to the opener. Controlled by `open`; labelled by `title`. Long content scrolls in the body, which becomes keyboard-scrollable when it overflows |
150
160
  | `Spinner` | Loading for an unknown time. An indeterminate progress bar to assistive technology, named by `label`; its size follows `--hm-spinner-size` |
151
161
  | `ProgressBar` | Progress for a known amount, on the native `<progress>`: `value`, `max`, `label`, `valueText`. Indeterminate without `value`. It needs no inline styles, so it works under a strict Content Security Policy |
162
+ | `Field` | A visible `label`, an optional `description` and an optional `error`, wired to one control: the label names it, the description and error describe it, and an error marks it `aria-invalid`. `Slider` and `NumberField` connect themselves; for a native `<input>` or `<select>`, pass a function and spread the props it receives |
163
+ | `NumberField` | A number typed as text, exposed as a spin button. Typing is committed on blur or Enter and kept within `min` and `max`; text that isn't a number goes back to the last value, so `onValueChange` never receives `NaN`. Arrow Up and Down step by `step`, Page Up and Down by `largeStep`, and Escape throws the typing away. `parse` and `format` default to the `locale`, or `UiMessagesProvider`'s, digits and separators included; replace them for units or a timecode. With `name`, forms receive the number |
164
+ | `Slider` | A value in a range, such as volume or zoom, on the native `<input type="range">`: `value` or `defaultValue`, `onValueChange`, `min`, `max`, `step` and `largeStep`. `formatValue` gives screen readers the value as text, such as "−6 dB". Arrow keys, Page Up and Down, Home and End work the same in every browser, mirrored in right-to-left text. In a `Toolbar`, it keeps the arrow keys, so put it last |
152
165
  | `AnnouncerProvider`, `useAnnounce` | Announcements for screen readers, such as "Saved 1.3 MB": `announce(message, { politeness })`. The provider renders the live regions once, on the server too |
153
166
 
154
167
  ```tsx
155
- import { Button, IconButton } from "@hussmartinez/ui/react";
168
+ import { Button, DownloadIcon, IconButton, RotateLeftIcon } from "@hussmartinez/ui/react";
156
169
 
157
170
  <Button variant="primary" startIcon={<DownloadIcon />} onClick={save}>
158
171
  {messages.t("toolbar.download")}
159
172
  </Button>
160
- <IconButton label={messages.t("toolbar.rotate")} icon={<RotateIcon />} onClick={rotate} />
173
+ <IconButton label={messages.t("toolbar.rotate")} icon={<RotateLeftIcon />} onClick={rotate} />
161
174
  ```
162
175
 
163
- Icons are yours: pass any element that draws with `currentColor`. Each component costs a few hundred bytes minified and compressed, and a bundler drops the ones you don't import.
176
+ Pass ui's icons, below, or any element that draws with `currentColor`. Each component costs a few hundred bytes minified and compressed, and a bundler drops the ones you don't import.
177
+
178
+ ### Icons
179
+
180
+ ui has its own icon set, generated from [Lucide](https://lucide.dev) ([ADR 0005](https://github.com/ie-huss-martinez/ui/blob/main/docs/adr/0005-icon-set.md)). Each icon is a component named after its use in the SDK family, such as `UndoIcon`, `RotateLeftIcon`, `PlayIcon` or `PageGridIcon`; the catalogue shows them all.
181
+
182
+ ```tsx
183
+ import { IconButton, RotateLeftIcon } from "@hussmartinez/ui/react";
184
+
185
+ <IconButton label={messages.t("toolbar.rotateLeft")} icon={<RotateLeftIcon />} />;
186
+ ```
187
+
188
+ - **Size and colour:** icons draw with `currentColor` and size to `--hm-icon-size`; in a button's icon slot, the slot sets the size.
189
+ - **Accessibility:** icons are decorative and hidden from assistive technology, as they should be inside a labelled button. For an icon that means something on its own, pass `label`, from your message catalogue, and it becomes a named image.
190
+ - **Right to left:** icons that point along the reading direction, such as undo and redo, mirror in right-to-left text.
191
+ - **Only what you import ships:** each icon is its own export, about 140 bytes compressed.
192
+ - **Icons by name:** tools refer to icons by their `IconName`, such as `"rotate-left"` (sdk-core ADR 0030). ui has no name-to-component registry, which would ship every icon, so map the names your tools use:
193
+
194
+ ```tsx
195
+ import type { IconComponent, IconName } from "@hussmartinez/ui/react";
196
+ import { RotateLeftIcon, UndoIcon } from "@hussmartinez/ui/react";
197
+
198
+ const toolIcons: Partial<Record<IconName, IconComponent>> = {
199
+ undo: UndoIcon,
200
+ "rotate-left": RotateLeftIcon,
201
+ };
202
+ ```
203
+
204
+ - **Licence:** Lucide's ISC licence, and the MIT licence of its icons derived from Feather, are in `THIRD_PARTY_NOTICES.md` in the package.
164
205
 
165
206
  ### Text
166
207
 
@@ -174,6 +215,17 @@ const messages = createMessages({ ...sdkCoreMessages, ...uiMessages, ...yourMess
174
215
  </UiMessagesProvider>
175
216
  ```
176
217
 
218
+ ## Using ui from an SDK
219
+
220
+ The `@hussmartinez` SDKs build their editors from ui's components, so an application using an SDK already has ui ([ADR 0036](https://github.com/ie-huss-martinez/sdk-core/blob/main/docs/adr/0036-ui-as-a-dependency-of-the-sdks.md)).
221
+
222
+ - **One stylesheet, required.** Import `@hussmartinez/ui/styles.css` once, before the SDKs' stylesheets. The SDKs' stylesheets never include it, so it loads once however many SDKs you use. Don't leave it out: the focus rings and target sizes of the components inside an SDK live there.
223
+ - **One copy of ui.** Each `ui` copy has its own providers, so `UiMessagesProvider`, `ThemeProvider` and `AnnouncerProvider` from one copy don't reach components from another: their text falls back to English, and announcements are lost. If your application uses ui itself, depend on the same minor version as your SDKs; `npm ls @hussmartinez/ui` should list one version. In development, ui warns when a second copy is in use, and names the versions it found.
224
+ - **Providers once, at the root.** One `UiMessagesProvider`, `ThemeProvider` and `AnnouncerProvider` around your application reach ui's components inside every SDK too.
225
+ - **Headless use.** An SDK's `.` entry never loads ui or React. ui is still installed with the SDK, but its `react` and `react-dom` peers are optional, so there are no peer warnings.
226
+
227
+ **For SDK authors:** list ui in `dependencies` with a caret range on the current minor, such as `^0.2.0`, and import it only from `features/`, `react/` and `element/`. `sdk-config`'s dependency-cruiser preset fails the build when the core, an adapter, a worker or anything the `.` entry reaches imports it.
228
+
177
229
  ## Errors and messages
178
230
 
179
231
  Errors are `UiError`s, subclasses of sdk-core's `SdkError`, with a stable `code` and `details`. `uiMessages` has English text for each code; spread it into your catalogue next to `sdkCoreMessages`:
@@ -0,0 +1,53 @@
1
+ # Third-party notices
2
+
3
+ `@hussmartinez/ui` includes the following third-party material.
4
+
5
+ ## Lucide
6
+
7
+ The icons in `dist/react.js`, such as `UndoIcon`, are generated from [Lucide](https://lucide.dev) (`lucide-static` 1.72.0). Their shapes are Lucide's; ui adds its own names and markup. Lucide's licence follows, as published in `lucide-static`, including the MIT licence of the icons derived from Feather.
8
+
9
+ ```text
10
+ ISC License
11
+
12
+ Copyright (c) 2026 Lucide Icons and Contributors
13
+
14
+ Permission to use, copy, modify, and/or distribute this software for any
15
+ purpose with or without fee is hereby granted, provided that the above
16
+ copyright notice and this permission notice appear in all copies.
17
+
18
+ THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
19
+ WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
20
+ MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
21
+ ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
22
+ WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
23
+ ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
24
+ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
25
+
26
+ ---
27
+
28
+ The following Lucide icons are derived from the Feather project:
29
+
30
+ airplay, alert-circle, alert-octagon, alert-triangle, aperture, arrow-down-circle, arrow-down-left, arrow-down-right, arrow-down, arrow-left-circle, arrow-left, arrow-right-circle, arrow-right, arrow-up-circle, arrow-up-left, arrow-up-right, arrow-up, at-sign, calendar, cast, check, chevron-down, chevron-left, chevron-right, chevron-up, chevrons-down, chevrons-left, chevrons-right, chevrons-up, circle, clipboard, clock, code, columns, command, compass, corner-down-left, corner-down-right, corner-left-down, corner-left-up, corner-right-down, corner-right-up, corner-up-left, corner-up-right, crosshair, database, divide-circle, divide-square, dollar-sign, download, external-link, feather, frown, hash, headphones, help-circle, info, italic, key, layout, life-buoy, link-2, link, loader, lock, log-in, log-out, maximize, meh, minimize, minimize-2, minus-circle, minus-square, minus, monitor, moon, more-horizontal, more-vertical, move, music, navigation-2, navigation, octagon, pause-circle, percent, plus-circle, plus-square, plus, power, radio, rss, search, server, share, shopping-bag, sidebar, smartphone, smile, square, table-2, tablet, target, terminal, trash-2, trash, triangle, tv, type, upload, x-circle, x-octagon, x-square, x, zoom-in, zoom-out
31
+
32
+ The MIT License (MIT) (for the icons listed above)
33
+
34
+ Copyright (c) 2013-present Cole Bemis
35
+
36
+ Permission is hereby granted, free of charge, to any person obtaining a copy
37
+ of this software and associated documentation files (the "Software"), to deal
38
+ in the Software without restriction, including without limitation the rights
39
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
40
+ copies of the Software, and to permit persons to whom the Software is
41
+ furnished to do so, subject to the following conditions:
42
+
43
+ The above copyright notice and this permission notice shall be included in all
44
+ copies or substantial portions of the Software.
45
+
46
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
47
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
48
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
49
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
50
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
51
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
52
+ SOFTWARE.
53
+ ```
@@ -0,0 +1,448 @@
1
+ /**
2
+ * Design tokens, themes and theme helpers for the `@hussmartinez` SDK family.
3
+ *
4
+ * @remarks
5
+ * This entry is server-safe: it has no React and touches no DOM on import, so
6
+ * Server Components and build scripts can import it (ADR 0004, ADR 0007).
7
+ *
8
+ * @packageDocumentation
9
+ */
10
+
11
+ import { SdkError } from '@hussmartinez/sdk-core';
12
+
13
+ /**
14
+ * The names of the base tokens: the raw colour, space, radius, border, type
15
+ * and motion scales.
16
+ *
17
+ * @public
18
+ */
19
+ export declare type BaseTokenName = `${"gray" | "blue" | "red" | "green" | "amber"}-${50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950}` | "white" | "black" | `space-${1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12}` | "radius-none" | "radius-sm" | "radius-md" | "radius-lg" | "radius-full" | "border-width-1" | "border-width-2" | "font-sans" | "font-mono" | `font-size-${1 | 2 | 3 | 4 | 5 | 6 | 7}` | "font-weight-400" | "font-weight-500" | "font-weight-600" | "font-weight-700" | "leading-tight" | "leading-normal" | "leading-relaxed" | "duration-fast" | "duration-normal" | "duration-slow" | "easing-standard" | "easing-decelerate" | "easing-accelerate";
20
+
21
+ /**
22
+ * Checks a theme's text, boundary and focus colours against WCAG 2.2 AA
23
+ * contrast. References to base tokens the theme doesn't set resolve to the
24
+ * built-in values, as they do on the page.
25
+ *
26
+ * @public
27
+ */
28
+ export declare function checkContrast(theme: Theme): ContrastReport;
29
+
30
+ /**
31
+ * How a subtree picks between light and dark: one of them, or whichever the
32
+ * operating system prefers (`prefers-color-scheme`).
33
+ *
34
+ * @public
35
+ */
36
+ export declare type ColorMode = "light" | "dark" | "system";
37
+
38
+ /**
39
+ * A theme from scratch: every semantic token is needed. Base tokens are
40
+ * optional, and fall back to the built-in ones on the page.
41
+ *
42
+ * @public
43
+ */
44
+ export declare interface CompleteThemeInput extends ThemeInputBase {
45
+ readonly extends?: undefined;
46
+ readonly tokens: CompleteThemeTokens;
47
+ }
48
+
49
+ /**
50
+ * Every semantic token, which a theme that doesn't extend another must set.
51
+ *
52
+ * @public
53
+ */
54
+ export declare type CompleteThemeTokens = ThemeTokens & {
55
+ readonly [Name in Exclude<SemanticTokenName, "color-scheme">]: string;
56
+ };
57
+
58
+ /**
59
+ * The names of `ui`'s component tokens: fine-grained overrides for one
60
+ * component, each falling back to a semantic token.
61
+ *
62
+ * @public
63
+ */
64
+ export declare type ComponentTokenName = "button-height" | "button-small-height" | "button-padding-x" | "button-gap" | "button-icon-size" | "button-radius" | "button-font-weight" | "button-bg" | "button-bg-hover" | "button-bg-active" | "button-fg" | "button-border-color" | "button-primary-bg" | "button-primary-bg-hover" | "button-primary-bg-active" | "button-primary-fg" | "button-quiet-bg-hover" | "button-quiet-bg-active" | "button-danger-bg" | "button-danger-bg-hover" | "button-danger-fg" | "button-pressed-bg" | "button-pressed-border-color" | "button-pressed-fg" | "toolbar-bg" | "toolbar-border-color" | "toolbar-radius" | "toolbar-padding" | "toolbar-gap" | "toolbar-group-gap" | "toolbar-separator-color" | "segmented-control-height" | "segmented-control-small-height" | "segmented-control-padding" | "segmented-control-gap" | "segmented-control-radius" | "segmented-control-bg" | "segmented-control-border-color" | "segmented-control-option-padding-x" | "segmented-control-option-fg" | "segmented-control-option-bg-hover" | "segmented-control-option-checked-bg" | "segmented-control-option-checked-fg" | "segmented-control-option-checked-border-color" | "dialog-bg" | "dialog-fg" | "dialog-border-color" | "dialog-radius" | "dialog-shadow" | "dialog-padding" | "dialog-gap" | "dialog-backdrop" | "dialog-title-font-size" | "dialog-small-width" | "dialog-width" | "dialog-large-width" | "spinner-size" | "spinner-thickness" | "spinner-color" | "spinner-track-color" | "spinner-duration" | "progress-height" | "progress-radius" | "progress-track-color" | "progress-fill-color" | "progress-duration" | "slider-track-size" | "slider-track-color" | "slider-radius" | "slider-thumb-size" | "slider-thumb-color" | "slider-thumb-color-hover" | "slider-thumb-color-active" | "field-gap" | "field-label-fg" | "field-label-font-weight" | "field-description-fg" | "field-error-fg" | "field-message-font-size" | "number-field-height" | "number-field-padding-x" | "number-field-radius" | "number-field-bg" | "number-field-fg" | "number-field-border-color" | "number-field-invalid-border-color" | "file-drop-zone-gap" | "file-drop-zone-padding" | "file-drop-zone-radius" | "file-drop-zone-border-color" | "file-drop-zone-dragging-border-color" | "file-drop-zone-dragging-bg" | "file-drop-zone-hint-fg";
65
+
66
+ /**
67
+ * Component tokens from SDKs, such as `pdf-thumb-radius`. `ui`'s own
68
+ * component tokens are typed already ({@link ComponentTokenName}); SDKs add
69
+ * theirs through declaration merging, so their themes are typed too:
70
+ *
71
+ * ```ts
72
+ * declare module "@hussmartinez/ui" {
73
+ * interface ComponentTokens {
74
+ * "pdf-thumb-radius": string;
75
+ * }
76
+ * }
77
+ * ```
78
+ *
79
+ * @public
80
+ */
81
+ export declare interface ComponentTokens {
82
+ }
83
+
84
+ /**
85
+ * A foreground token that must contrast with a background token, and the
86
+ * smallest WCAG 2.2 ratio it needs.
87
+ *
88
+ * @public
89
+ */
90
+ export declare interface ContrastPair {
91
+ readonly foreground: SemanticTokenName;
92
+ readonly background: SemanticTokenName;
93
+ /** 4.5 for text (WCAG 1.4.3), 3 for boundaries and focus indicators (WCAG 1.4.11). */
94
+ readonly minimum: 4.5 | 3;
95
+ }
96
+
97
+ /**
98
+ * The colour pairs every theme must meet, as checked by `createTheme` in
99
+ * development and by the tests for the built-in themes.
100
+ *
101
+ * @public
102
+ */
103
+ export declare const contrastPairs: readonly ContrastPair[];
104
+
105
+ /**
106
+ * Result of checking a theme's colour pairs against WCAG 2.2 AA.
107
+ *
108
+ * @public
109
+ */
110
+ export declare interface ContrastReport {
111
+ /** Pairs below their minimum ratio, with the ratio they have. */
112
+ readonly failures: readonly {
113
+ readonly foreground: string;
114
+ readonly background: string;
115
+ readonly ratio: number;
116
+ readonly minimum: number;
117
+ }[];
118
+ /**
119
+ * Pairs that couldn't be checked, because a colour can't be computed
120
+ * without a browser, such as `color-mix()`, or its background is translucent.
121
+ */
122
+ readonly unchecked: readonly {
123
+ readonly foreground: string;
124
+ readonly background: string;
125
+ }[];
126
+ }
127
+
128
+ /**
129
+ * Creates a theme: a validated, frozen set of token values that
130
+ * {@link themeToCss} and `ThemeProvider` apply.
131
+ *
132
+ * - With `extends`, only the tokens that change are needed.
133
+ * - Without it, every semantic token is needed, so a theme can replace the
134
+ * whole look.
135
+ *
136
+ * Every value is checked against its token's type and an allowlist grammar,
137
+ * so a value can't break out of its CSS declaration, even when it comes from
138
+ * a user. Invalid input throws a {@link UiError} with the code
139
+ * `INVALID_THEME_TOKEN`. In development, it also warns when text, boundary or
140
+ * focus colours fall below WCAG 2.2 AA contrast.
141
+ *
142
+ * @example
143
+ * ```ts
144
+ * const brand = createTheme({
145
+ * extends: "light",
146
+ * tokens: { "color-accent": "#6d28d9", "radius-control": "0" },
147
+ * });
148
+ * ```
149
+ *
150
+ * @public
151
+ */
152
+ export declare function createTheme(input: ThemeInput): Theme;
153
+
154
+ /**
155
+ * The built-in dark theme.
156
+ *
157
+ * @public
158
+ */
159
+ export declare const darkTheme: Theme;
160
+
161
+ /**
162
+ * How tightly controls are packed. Set it with `data-hm-density` or the
163
+ * `density` prop.
164
+ *
165
+ * @public
166
+ */
167
+ export declare type Density = "comfortable" | "compact";
168
+
169
+ /**
170
+ * The semantic tokens that density changes: control sizes, gaps and insets.
171
+ *
172
+ * @public
173
+ */
174
+ export declare type DensityTokenName = "control-height" | "control-height-small" | "control-padding-x" | "control-gap" | "icon-size" | "target-size" | "gap-tight" | "gap-normal" | "gap-loose" | "inset-tight" | "inset-normal" | "inset-loose";
175
+
176
+ /**
177
+ * Values for the density tokens.
178
+ *
179
+ * @public
180
+ */
181
+ export declare type DensityTokens = {
182
+ readonly [Name in DensityTokenName]?: string;
183
+ };
184
+
185
+ /**
186
+ * A theme built on another: only the tokens it changes are needed.
187
+ *
188
+ * @public
189
+ */
190
+ export declare interface ExtendingThemeInput extends ThemeInputBase {
191
+ /** The theme to start from: a built-in one by name, or one from `createTheme`. */
192
+ readonly extends: Theme | "light" | "dark";
193
+ readonly tokens?: ThemeTokens;
194
+ }
195
+
196
+ /**
197
+ * The name of an icon in ui's set, such as `rotate-left`. Tools refer to
198
+ * icons by name (sdk-core ADR 0030), and the SDK maps the names it uses to
199
+ * their components.
200
+ *
201
+ * @public
202
+ */
203
+ export declare type IconName = "add" | "check" | "chevron-down" | "chevron-left" | "chevron-right" | "close" | "delete" | "download" | "highlighter" | "info" | "loop" | "menu" | "more" | "muted" | "open" | "page-grid" | "page-single" | "pan" | "pause" | "pen" | "play" | "redo" | "remove" | "rotate-left" | "rotate-right" | "search" | "select" | "skip-back" | "skip-forward" | "split" | "stop" | "undo" | "upload" | "volume" | "warning" | "zoom-in" | "zoom-out";
204
+
205
+ /**
206
+ * The built-in light theme.
207
+ *
208
+ * @public
209
+ */
210
+ export declare const lightTheme: Theme;
211
+
212
+ /**
213
+ * The names of the semantic tokens, which components use.
214
+ *
215
+ * @public
216
+ */
217
+ export declare type SemanticTokenName = "color-scheme" | "color-bg" | "color-surface" | "color-surface-raised" | "color-surface-sunken" | "color-overlay" | "color-text" | "color-text-muted" | "color-text-disabled" | "color-border" | "color-border-strong" | "color-control" | "color-control-hover" | "color-control-active" | "color-accent" | "color-accent-hover" | "color-accent-active" | "color-on-accent" | "color-accent-subtle" | "color-accent-text" | "color-danger" | "color-danger-hover" | "color-on-danger" | "color-danger-subtle" | "color-danger-text" | "color-warning" | "color-on-warning" | "color-warning-subtle" | "color-warning-text" | "color-success" | "color-on-success" | "color-success-subtle" | "color-success-text" | "focus-ring-color" | "focus-ring-width" | "focus-ring-offset" | "focus-ring" | "font-family" | "font-family-mono" | "font-size-small" | "font-size-body" | "font-size-title" | "font-weight-regular" | "font-weight-strong" | "line-height-body" | "line-height-tight" | "letter-spacing" | "control-height" | "control-height-small" | "control-padding-x" | "control-gap" | "icon-size" | "target-size" | "gap-tight" | "gap-normal" | "gap-loose" | "inset-tight" | "inset-normal" | "inset-loose" | "surface-width-small" | "surface-width-medium" | "surface-width-large" | "track-size" | "radius-control" | "radius-surface" | "radius-round" | "border-width" | "shadow-raised" | "shadow-overlay" | "motion-duration-feedback" | "motion-duration-enter" | "motion-duration-exit" | "motion-easing-standard" | "motion-easing-enter" | "motion-easing-exit" | "motion-duration-loop" | "motion-easing-loop" | "z-raised" | "z-sticky" | "z-overlay" | "opacity-disabled";
218
+
219
+ /**
220
+ * A validated theme. Create it with `createTheme`; its values are
221
+ * frozen and safe to write into CSS.
222
+ *
223
+ * @public
224
+ */
225
+ export declare interface Theme {
226
+ readonly colorScheme: "light" | "dark";
227
+ /** Every token value, by name without the `--hm-` prefix. Density tokens hold comfortable values. */
228
+ readonly tokens: Readonly<Record<string, string>>;
229
+ /** Density token values for compact density. */
230
+ readonly compact: Readonly<Record<string, string>>;
231
+ /** Density token values for coarse pointers. */
232
+ readonly coarsePointer: Readonly<Record<string, string>>;
233
+ }
234
+
235
+ /**
236
+ * What `createTheme` accepts.
237
+ *
238
+ * @public
239
+ */
240
+ export declare type ThemeInput = ExtendingThemeInput | CompleteThemeInput;
241
+
242
+ /**
243
+ * Options of `createTheme` shared by both forms.
244
+ *
245
+ * @public
246
+ */
247
+ export declare interface ThemeInputBase {
248
+ /** Whether the theme is light or dark. Defaults to the extended theme's, or `"light"`. */
249
+ readonly colorScheme?: "light" | "dark";
250
+ /** Values for compact density. Comfortable values are the density tokens in `tokens`. */
251
+ readonly density?: {
252
+ readonly compact?: DensityTokens;
253
+ };
254
+ /** Values for coarse pointers, such as touch screens. Default to 44 px targets (ADR 0014). */
255
+ readonly coarsePointer?: DensityTokens;
256
+ }
257
+
258
+ /**
259
+ * A light and a dark theme used together, so `system` mode can follow the
260
+ * operating system. Density values come from `light`.
261
+ *
262
+ * @public
263
+ */
264
+ export declare interface ThemePair {
265
+ readonly light: Theme;
266
+ readonly dark: Theme;
267
+ }
268
+
269
+ /**
270
+ * Writes a theme, or a light and dark pair, as a static stylesheet: for
271
+ * build-time theming, server rendering without JavaScript, and strict
272
+ * Content Security Policies.
273
+ *
274
+ * - **A single theme** applies to the elements `selector` matches, and
275
+ * everything inside them.
276
+ * - **A pair** follows `prefers-color-scheme` in pure CSS, and descendants can
277
+ * force a mode with `data-hm-theme="light|dark|system"`.
278
+ * - **Density** follows `data-hm-density`, and coarse pointers get 44 px
279
+ * targets.
280
+ *
281
+ * The rules sit in the `hm.tokens.theme` cascade layer, so they beat the
282
+ * built-in themes whatever order stylesheets load in, and a host's unlayered
283
+ * CSS still beats them. They're wrapped in `@scope`, so when themes are
284
+ * nested, the closest one wins.
285
+ *
286
+ * Themes that didn't come from {@link createTheme} are validated again, and
287
+ * the selector must be a plain selector list. Invalid input throws a
288
+ * {@link UiError}. The output never contains `<`, so it's safe inside a
289
+ * `<style>` element.
290
+ *
291
+ * @param theme - A theme from `createTheme`, or a `{ light, dark }` pair.
292
+ * @param selector - Where the theme applies. Defaults to `:root`.
293
+ *
294
+ * @example
295
+ * ```ts
296
+ * // brand.css.ts, run at build time
297
+ * export default themeToCss({ light: brandLight, dark: brandDark });
298
+ * ```
299
+ *
300
+ * @public
301
+ */
302
+ export declare function themeToCss(theme: Theme | ThemePair, selector?: string): string;
303
+
304
+ /**
305
+ * Token values a theme sets, by token name without the `--hm-` prefix. The
306
+ * colour scheme isn't a token here; it's `colorScheme`.
307
+ *
308
+ * @public
309
+ */
310
+ export declare type ThemeTokens = {
311
+ readonly [Name in Exclude<TokenName, "color-scheme">]?: string;
312
+ } & {
313
+ readonly [Name in keyof ComponentTokens]?: ComponentTokens[Name];
314
+ };
315
+
316
+ /**
317
+ * What a token is for, used to group the token reference.
318
+ *
319
+ * @public
320
+ */
321
+ export declare type TokenCategory = "color" | "typography" | "space" | "size" | "shape" | "shadow" | "motion" | "z-index" | "opacity" | "focus";
322
+
323
+ /**
324
+ * What a token is, for tooling: its name, level, category and value type.
325
+ * What each token is for is documented in the token reference,
326
+ * `docs/tokens.md`, rather than shipped to applications (docs/adr/0001).
327
+ *
328
+ * @public
329
+ */
330
+ export declare interface TokenDefinition {
331
+ /** The name without the `--hm-` prefix, such as `color-accent`. */
332
+ readonly name: string;
333
+ /** Base, semantic or component (ADR 0006). */
334
+ readonly level: TokenLevel;
335
+ /** What the token styles, used to group the token reference. */
336
+ readonly category: TokenCategory;
337
+ /** The grammar its values must follow. */
338
+ readonly type: TokenType;
339
+ /**
340
+ * Whether density changes the token. Density tokens are set by
341
+ * `data-hm-density`, not by the colour mode.
342
+ */
343
+ readonly density: boolean;
344
+ /**
345
+ * For component tokens, the semantic token they fall back to. `ui` never
346
+ * declares component tokens; components read them as
347
+ * `var(--hm-<name>, var(--hm-<fallback>))`, so a theme or host can set them
348
+ * on any ancestor (docs/adr/0001).
349
+ */
350
+ readonly fallback?: SemanticTokenName;
351
+ }
352
+
353
+ /**
354
+ * Base tokens are raw scales that only other tokens use. Semantic tokens name
355
+ * a purpose, and are what components use (ADR 0006).
356
+ *
357
+ * @public
358
+ */
359
+ export declare type TokenLevel = "base" | "semantic" | "component";
360
+
361
+ /**
362
+ * The name of any token `@hussmartinez/ui` defines.
363
+ *
364
+ * @public
365
+ */
366
+ export declare type TokenName = BaseTokenName | SemanticTokenName | ComponentTokenName;
367
+
368
+ /**
369
+ * Every token `@hussmartinez/ui` defines, base tokens first, in a stable
370
+ * order. Use it to build token documentation or tooling.
371
+ *
372
+ * @public
373
+ */
374
+ export declare const tokens: readonly TokenDefinition[];
375
+
376
+ /**
377
+ * The token definitions: every token's name, level, category, value type and
378
+ * purpose. This is the single source the CSS, the types and the token
379
+ * reference are generated from (ADR 0006).
380
+ */
381
+ /**
382
+ * The value types a token can have. Each type has its own grammar, which
383
+ * {@link createTheme} checks values against.
384
+ *
385
+ * @public
386
+ */
387
+ export declare type TokenType = "color" | "length" | "duration" | "easing" | "number" | "integer" | "font-family" | "font-weight" | "shadow" | "outline" | "color-scheme";
388
+
389
+ /**
390
+ * The error `@hussmartinez/ui` throws, with a stable `code` and structured
391
+ * `details`. Show users the text for its code from {@link uiMessages}, never
392
+ * its `message`.
393
+ *
394
+ * @example
395
+ * ```ts
396
+ * try {
397
+ * createTheme({ extends: "light", tokens: { "color-accent": brandColour } });
398
+ * } catch (error) {
399
+ * if (isSdkError(error, "INVALID_THEME_TOKEN")) {
400
+ * // Ask for another colour.
401
+ * }
402
+ * }
403
+ * ```
404
+ *
405
+ * @public
406
+ */
407
+ export declare class UiError extends SdkError<UiErrorCode> {
408
+ readonly name = "UiError";
409
+ }
410
+
411
+ /**
412
+ * Error codes of `@hussmartinez/ui`. They never change once released.
413
+ *
414
+ * - `INVALID_THEME_TOKEN`: a theme token has an unknown name, or a value that
415
+ * isn't allowed for its type. `details` has `token`, `value` and `reason`.
416
+ * - `INVALID_THEME_SELECTOR`: the selector passed to `themeToCss` isn't a
417
+ * plain CSS selector. `details` has `selector` and `reason`.
418
+ *
419
+ * @public
420
+ */
421
+ export declare type UiErrorCode = "INVALID_THEME_TOKEN" | "INVALID_THEME_SELECTOR";
422
+
423
+ /**
424
+ * English text for `@hussmartinez/ui`'s error codes. Applications and SDKs
425
+ * spread it into their catalogue, next to `sdkCoreMessages`, so
426
+ * `messages.error()` can describe a `UiError`. Components add their
427
+ * text here as they arrive.
428
+ *
429
+ * @example
430
+ * ```ts
431
+ * export const en = defineMessages({ ...sdkCoreMessages, ...uiMessages });
432
+ * ```
433
+ *
434
+ * @public
435
+ */
436
+ export declare const uiMessages: {
437
+ readonly "dialog.close": "Close";
438
+ readonly "fileDropZone.choose": "Choose a file";
439
+ readonly "fileDropZone.chooseMultiple": "Choose files";
440
+ readonly "fileDropZone.hint": "or drop it here";
441
+ readonly "fileDropZone.hintMultiple": "or drop them here";
442
+ readonly "progress.label": "Progress";
443
+ readonly "spinner.label": "Loading";
444
+ readonly "errors.INVALID_THEME_TOKEN": "The theme setting {token} has a value that can't be used.";
445
+ readonly "errors.INVALID_THEME_SELECTOR": "The theme can't be applied to the selector {selector}.";
446
+ };
447
+
448
+ export { }