@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.
Files changed (2) hide show
  1. package/README.md +44 -2
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,8 +1,37 @@
1
1
  # @hussmartinez/ui
2
2
 
3
+ [![npm version of @hussmartinez/ui](https://img.shields.io/npm/v/@hussmartinez/ui)](https://www.npmjs.com/package/@hussmartinez/ui) [![Verify workflow status on main](https://github.com/ie-huss-martinez/ui/actions/workflows/verify.yml/badge.svg?branch=main)](https://github.com/ie-huss-martinez/ui/actions/workflows/verify.yml?query=branch%3Amain) [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](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: not published yet. Tokens, theming and the first components are in place; more components are on the way.
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` 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 |
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hussmartinez/ui",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "Design system of the @hussmartinez SDK family: tokens, themes, base styles and accessible React components.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {