@hussmartinez/ui 0.2.0 → 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.
- package/README.md +43 -4
- package/THIRD_PARTY_NOTICES.md +53 -0
- package/dist/index.d.ts +448 -0
- package/dist/index.js +1609 -0
- package/dist/index.js.map +1 -0
- package/dist/react.d.ts +1410 -0
- package/dist/react.js +1353 -0
- package/dist/react.js.map +1 -0
- package/dist/shared/pair-DLVFV6vU.js +43 -0
- package/dist/shared/pair-DLVFV6vU.js.map +1 -0
- package/dist/styles.css +1342 -0
- package/dist/ui.d.ts +1410 -0
- package/package.json +10 -7
package/README.md
CHANGED
|
@@ -155,7 +155,7 @@ Every component follows one contract ([ADR 0003](https://github.com/ie-huss-mart
|
|
|
155
155
|
| `VisuallyHidden` | Text for assistive technology only |
|
|
156
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 |
|
|
157
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 |
|
|
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 |
|
|
159
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 |
|
|
160
160
|
| `Spinner` | Loading for an unknown time. An indeterminate progress bar to assistive technology, named by `label`; its size follows `--hm-spinner-size` |
|
|
161
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 |
|
|
@@ -165,15 +165,43 @@ Every component follows one contract ([ADR 0003](https://github.com/ie-huss-mart
|
|
|
165
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 |
|
|
166
166
|
|
|
167
167
|
```tsx
|
|
168
|
-
import { Button, IconButton } from "@hussmartinez/ui/react";
|
|
168
|
+
import { Button, DownloadIcon, IconButton, RotateLeftIcon } from "@hussmartinez/ui/react";
|
|
169
169
|
|
|
170
170
|
<Button variant="primary" startIcon={<DownloadIcon />} onClick={save}>
|
|
171
171
|
{messages.t("toolbar.download")}
|
|
172
172
|
</Button>
|
|
173
|
-
<IconButton label={messages.t("toolbar.rotate")} icon={<
|
|
173
|
+
<IconButton label={messages.t("toolbar.rotate")} icon={<RotateLeftIcon />} onClick={rotate} />
|
|
174
174
|
```
|
|
175
175
|
|
|
176
|
-
|
|
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.
|
|
177
205
|
|
|
178
206
|
### Text
|
|
179
207
|
|
|
@@ -187,6 +215,17 @@ const messages = createMessages({ ...sdkCoreMessages, ...uiMessages, ...yourMess
|
|
|
187
215
|
</UiMessagesProvider>
|
|
188
216
|
```
|
|
189
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
|
+
|
|
190
229
|
## Errors and messages
|
|
191
230
|
|
|
192
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
|
+
```
|
package/dist/index.d.ts
ADDED
|
@@ -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" | "crop" | "delete" | "download" | "fade-in" | "fade-out" | "fit" | "flip-horizontal" | "flip-vertical" | "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" | "snap" | "split" | "stop" | "trim-end" | "trim-start" | "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 { }
|