@hussmartinez/ui 0.1.0 → 0.2.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 +44 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,8 +1,37 @@
|
|
|
1
1
|
# @hussmartinez/ui
|
|
2
2
|
|
|
3
|
+
[](https://www.npmjs.com/package/@hussmartinez/ui) [](https://github.com/ie-huss-martinez/ui/actions/workflows/verify.yml?query=branch%3Amain) [](https://github.com/ie-huss-martinez/ui/blob/main/LICENSE)
|
|
4
|
+
|
|
3
5
|
The design system of the `@hussmartinez` SDK family: design tokens, themes, base styles and accessible React components. Every SDK's editor uses it, and standalone applications can too.
|
|
4
6
|
|
|
5
|
-
> Status:
|
|
7
|
+
> Status: `0.x`, so the API may still change between minor versions. Tokens, theming and the first components are available; more components are on the way.
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
npm install @hussmartinez/ui
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
For the React components, your application also needs `react` and `react-dom` 18.3 or later. They're optional peer dependencies, so the tokens and theme helpers work without them.
|
|
16
|
+
|
|
17
|
+
## Quick start
|
|
18
|
+
|
|
19
|
+
Import the stylesheet once, at the root of your application, and use the components:
|
|
20
|
+
|
|
21
|
+
```tsx
|
|
22
|
+
import "@hussmartinez/ui/styles.css";
|
|
23
|
+
import { Button, ThemeProvider } from "@hussmartinez/ui/react";
|
|
24
|
+
|
|
25
|
+
export function App() {
|
|
26
|
+
return (
|
|
27
|
+
<ThemeProvider mode="system">
|
|
28
|
+
<Button variant="primary">Save</Button>
|
|
29
|
+
</ThemeProvider>
|
|
30
|
+
);
|
|
31
|
+
}
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
`mode="system"` follows the operating system's light or dark preference, in CSS, so nothing flashes on load. Without `ThemeProvider`, the page follows the system preference too; the provider is for a forced mode, a density or a custom theme.
|
|
6
35
|
|
|
7
36
|
## Entry points
|
|
8
37
|
|
|
@@ -101,6 +130,14 @@ Every component renders on the server and hydrates without warnings; end-to-end
|
|
|
101
130
|
|
|
102
131
|
No styles are evaluated as JavaScript, and nothing needs `unsafe-eval`.
|
|
103
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
|
+
|
|
104
141
|
## Components
|
|
105
142
|
|
|
106
143
|
Every component follows one contract ([ADR 0003](https://github.com/ie-huss-martinez/ui/blob/main/docs/adr/0003-component-contract.md)):
|
|
@@ -112,14 +149,19 @@ Every component follows one contract ([ADR 0003](https://github.com/ie-huss-mart
|
|
|
112
149
|
|
|
113
150
|
| Component | Use it for |
|
|
114
151
|
|---|---|
|
|
115
|
-
| `Button` | Actions. `variant` is `primary`, `secondary` (default), `quiet` or `danger`; `size` is `medium` or `small`; `pressed`
|
|
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 |
|
|
116
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` |
|
|
117
155
|
| `VisuallyHidden` | Text for assistive technology only |
|
|
118
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 |
|
|
119
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 |
|
|
120
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 |
|
|
121
160
|
| `Spinner` | Loading for an unknown time. An indeterminate progress bar to assistive technology, named by `label`; its size follows `--hm-spinner-size` |
|
|
122
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 |
|
|
123
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 |
|
|
124
166
|
|
|
125
167
|
```tsx
|
package/package.json
CHANGED