@hussmartinez/ui 0.1.1 → 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 +14 -1
  2. package/package.json +1 -1
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,14 +149,19 @@ 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 |
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
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hussmartinez/ui",
3
- "version": "0.1.1",
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": {