@slotted/react 0.0.0-stage → 0.1.0-beta.1

package/dist/docs/upload.md

@@ -0,0 +1,168 @@
+<!-- index: ./index.md -->
+# upload
+
+`data-ui="upload"` · Picks or drops files and shows their progress.
+
+## Import
+
+```tsx
+import { Upload, UploadDefaultsProvider } from '@slotted/react';
+import { createXhrUpload } from '@slotted/core/upload';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<Upload
+  accept="application/pdf,image/*"
+  description="PDF, JPEG or PNG, up to 10 MB each."
+  label="Supporting documents"
+  multiple
+/>;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div | yes |
+| `label` | span | no |
+| `description` | p | no |
+| `dropzone` | div | no |
+| `trigger` | label | yes |
+| `input` | input | yes |
+| `summary` | div | no |
+| `clear` | button | no |
+| `list` | ul | no |
+| `item` | li | no |
+| `body` | div | no |
+| `detail` | div | no |
+| `preview` | span | no |
+| `filename` | button or span | no |
+| `name` | span | no |
+| `extension` | span | no |
+| `meta` | span | no |
+| `status` | span | no |
+| `progress` | div | no |
+| `actions` | span | no |
+| `start` | button | no |
+| `pause` | button | no |
+| `retry` | button | no |
+| `cancel` | button | no |
+| `remove` | button | no |
+| `message` | p | no |
+| `viewer` | div | no |
+| `viewerHeader` | div | no |
+| `viewerTitle` | h2 | no |
+| `viewerMeta` | span | no |
+| `viewerActions` | span | no |
+| `viewerExternal` | button | no |
+| `viewerClose` | button | no |
+| `viewerPrevious` | button | no |
+| `viewerNext` | button | no |
+| `viewerStage` | div | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `files` | `readonly UploadFile[]` | — | Upload | The selection, when the consumer owns it. Each entry carries the file, its kind, its status, the bytes moved and the reason it was refused. |
+| `defaultFiles` | `readonly UploadFile[]` | [] | Upload | The selection an uncontrolled upload starts from, read once |
+| `viewing` | `string \| null` | — | Upload | The key of the file the viewer is open on, when the consumer owns it |
+| `defaultViewing` | `string \| null` | null | Upload | The file the viewer starts open on, read once |
+| `variant` | `'dropzone' \| 'button' \| 'field'` | dropzone | Upload | Which of the three shapes the consolidation names is drawn |
+| `layout` | `'list' \| 'grid'` | list | Upload | A column of rows, or a wall of pictures |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | Upload | The step every control measure in the family reads. A Field above outranks it. |
+| `preview` | `'auto' \| 'none'` | auto | Upload | Whether an image gets a thumbnail from an object URL the family revokes |
+| `view` | `'auto' \| 'none'` | auto | Upload | Whether a file the browser can render opens in the viewer from its own name |
+| `duplicates` | `'reject' \| 'allow' \| 'replace'` | reject | Upload | What happens to a second copy of a file the list already holds |
+| `accept` | `string` | — | Upload | The same syntax the attribute takes, applied to a drop as well as to the dialog |
+| `multiple` | `boolean` | false | Upload | Whether more than one file may be held. Multiple appends; single replaces. |
+| `directory` | `boolean` | false | Upload | Whether the picker chooses folders. Each file keeps its webkitRelativePath. |
+| `capture` | `'user' \| 'environment'` | — | Upload | Which camera the picker opens on a device that has one |
+| `maxFiles` | `number` | — | Upload | How many files may be kept. The extras are reported, never truncated in silence. |
+| `minFiles` | `number` | — | Upload | How many the form needs before it may be submitted |
+| `maxSize` | `number` | — | Upload | The largest a single file may be, in bytes |
+| `minSize` | `number` | — | Upload | The smallest, in bytes. A zero-byte file is the common case it catches. |
+| `maxTotalSize` | `number` | — | Upload | The largest the whole selection may be, in bytes |
+| `validate` | `(file) => reason \| null` | — | Upload | The consumer’s own rule, run after the family’s and before anything is kept |
+| `transform` | `(files) => files \| Promise<files>` | — | Upload | Rewrites the selection before it is judged: compression, renaming, cropping |
+| `fileKey` | `(file) => string` | name, size and lastModified | Upload | What makes two files the same file |
+| `adapter` | `UploadAdapter \| send` | — | Upload | What moves the bytes. Without one the family selects and holds. |
+| `autoUpload` | `boolean` | true | Upload | Whether an accepted file is sent at once, or waits for the reader |
+| `concurrency` | `number` | 3 | Upload | How many transfers run at the same time |
+| `retries` | `number` | 0 | Upload | How many times a failure is sent again before the reader is told. Off, because a POST retried is a second record. |
+| `retryDelay` | `number` | 1000 | Upload | The first backoff, doubled for each further attempt |
+| `stallAfter` | `number` | 10000 | Upload | How long without a progress report before a running transfer is called stalled |
+| `maxRows` | `number` | 6 | Upload | How many rows the list shows before the platform scrolls the rest. 0 is no bound. |
+| `clickToBrowse` | `boolean` | true | Upload | Whether pressing the region opens the picker |
+| `allowDrop` | `boolean` | true | Upload | Whether the region takes a drop |
+| `allowPaste` | `boolean` | true | Upload | Whether a file on the clipboard may be pasted into the region |
+| `preventDocumentDrop` | `boolean` | true | Upload | Whether a file dropped beside the region is stopped from navigating the browser away |
+| `pendingBlocksSubmit` | `boolean` | true | Upload | Whether a transfer still running makes the control invalid |
+| `locale` | `string` | the language in force | Upload | BCP 47, for the size and the time left |
+| `label` | `ReactNode` | — | Upload | The family’s own label, drawn only outside a Field |
+| `description` | `ReactNode` | — | Upload | The guidance, and the input’s aria-describedby |
+| `disabled` | `boolean` | unstated | Upload | Refuses the picker and the drop alike, because a drag is not routed through the input at all. Unstated rather than false, so the control defers to the Field around it. |
+| `readOnly` | `boolean` | unstated | Upload | Keeps the list readable and takes every control away. Distinct from disabled, which the reader cannot operate at all. |
+| `invalid` | `boolean` | unstated | Upload | Retargets the focus ring to the danger colour and marks the region. Unstated, it defers to the Field. |
+| `required` | `boolean` | unstated | Upload | Reaches the native input, so an empty selection is valueMissing before any of the family’s own rules run |
+| `name` | `string` | — | Upload | What the native input submits under |
+| `messages` | `Partial<UploadMessages>` | — | Upload | Words laid over the language in force, key by key: every control, the word for each status and each kind, the sentences about the queue (summary, selection, added, finished), and the sentence a refused file carries (rejection.*) |
+| `render` | `(props) => ReactNode` | — | Upload | Substitutes the root element, keeping the identity, the axes and every state |
+| `handleRef` | `Ref<UploadHandle>` | — | Upload | browse, upload, retryAll, cancelAll, clear and view — the six a consumer cannot write declaratively |
+| `UploadDefaultsProvider` | `component` | — | anywhere above | Sets the adapter, the limits and the behaviour once for the application; the words come from SlottedProvider |
+| `useUploadDefaults` | `() => UploadDefaults` | — | inside a provider | What an upload here would do, for a page that wants to say so |
+| `createXhrUpload` | `(options) => UploadAdapter` | — | @slotted/core/upload | The sender this library ships: url, method, headers, field name, credentials, and a parse of your own |
+| `selectFiles, uploadSummary, fileKind` | `functions` | — | @slotted/core/upload | The rules, the counts and the kind, framework-free, for a page that holds the list itself |
+| `children` | `ReactNode` | — | Upload | Appended inside the root, which is where an application puts its own note or its own control |
+| `Field` | `component` | — | around Upload | Owns the label row, the necessity mark, the description and the error slot; the upload then draws none of its own |
+| `ProgressBar` | `component` | — | composed by the row | The bar on a row’s bottom edge. The family says where it stands and nothing about how it is drawn. |
+| `Dialog` | `component` | — | composed by the viewer | The layer, the scrim, the focus containment, the scroll lock and Escape |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onFilesChange` | `(files, request)` | Whenever the selection would move: a pick, a drop, a paste, a removal, a clear, or the transfer reporting on a row. The request carries the new value, the value it replaces, the reason — select, pointer, keyboard, remove, clear or programmatic — the originating event and cancel(). |
+| `onViewingChange` | `(key, request)` | When the reader opens a file, moves to another, or closes the viewer. The reason says which: pointer, keyboard, escape, outsidePress, dismiss or programmatic. |
+| `onReject` | `(files)` | Once per selection that refused something, with the refused rows and their reasons. It fires before any message is written about them, because what to say is the consumer’s. |
+| `onDrop, onDragEnter, onDragLeave, onDragOver, onPaste, onChange` | `(event)` | The native events, on the element that owns them. The consumer’s handler runs first and the family composes with it rather than replacing it. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `variant` | `dropzone`, `button`, `field` | `dropzone` |
+| `layout` | `list`, `grid` | `list` |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `preview` | `auto`, `none` | `auto` |
+| `duplicates` | `reject`, `allow`, `replace` | `reject` |
+| `clickToBrowse` | `true`, `false` | `true` |
+| `allowDrop` | `true`, `false` | `true` |
+| `allowPaste` | `true`, `false` | `true` |
+| `preventDocumentDrop` | `true`, `false` | `true` |
+| `autoUpload` | `true`, `false` | `true` |
+| `pendingBlocksSubmit` | `true`, `false` | `true` |
+| `view` | `auto`, `none` | `auto` |
+
+## Rules
+
+- There is no upload, dropzone or drag-and-drop pattern in the WAI-ARIA Authoring Practices — the index at w3.org/WAI/ARIA/apg/patterns/ lists none of the three. The platform supplies the control and four sources settle the rest: the HTML file input, the APG Button Pattern for every per-row control, WCAG 2.2 SC 2.5.7 for the drag, and SC 4.1.3 for what is announced.
+- The accessible name comes from a <label> around the trigger rather than around the whole region, so it is three words instead of every word in the box, and the guidance reaches the input as aria-describedby. The input itself is clipped rather than hidden: display:none and visibility:hidden take it out of the tab order and out of the accessibility tree, which is the whole reason the label pairing exists.
+- Drag and drop is pointer-only and cannot be made otherwise. WCAG 2.2 SC 2.5.7 asks for a single-pointer alternative to every dragging action, and the trigger inside the region is it — a real control, in the tab order, that opens the picker with Enter or Space.
+- A file arriving, being refused, failing or finishing is announced through packages/core/src/live-announcer, politely, without moving focus — WCAG 2.2 SC 4.1.3. Progress is never announced: a bar that speaks every event says nothing, and the number is on the row inside a progressbar a reader can inspect on demand.
+- A status is a word before it is a colour. Refused, Failed and Stopped are three different words for three different failures, because a reader looking at one red row cannot tell whether to try again, choose another file, or do nothing — and under forced colours the tint goes and only the word is left.
+- Focus is never lost. When the row holding it is removed, focus goes to the same control on the next row, then on the previous one, then to the trigger when the list empties — so a reader clearing four failed rows presses the same key four times.
+- The viewer is a modal Dialog: focus is contained inside it, the page behind it does not scroll, Escape closes it, and focus goes back to the name that opened it. A text frame carries sandbox with neither allow-scripts nor allow-same-origin, because an object URL inherits this document’s origin and a text/html file the reader dropped would otherwise run its own script against it. A PDF frame carries none: Chrome’s PDF viewer is blocked in a sandboxed frame, and the type is what makes the exception safe — an HTML document served as application/pdf runs no script there.
+- A form submitted while the bytes are still moving is refused on the control the reader can see. None of the nine surveyed implementations answers this, and the result is a record saved with an attachment that never arrived.
+
+## Tokens
+
+`--slotted-border-strong`, `--slotted-border-subtle`, `--slotted-border-width-medium`, `--slotted-border-width-thin`, `--slotted-control-border-color`, `--slotted-control-border-width`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-font-weight`, `--slotted-control-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-inner-size-lg`, `--slotted-control-inner-size-md`, `--slotted-control-inner-size-sm`, `--slotted-control-invalid-edge-width`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-radius`, `--slotted-control-shadow`, `--slotted-control-surface`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-duration-instant`, `--slotted-duration-medium`, `--slotted-easing-enter`, `--slotted-focus-ring-color`, `--slotted-focus-ring-color-invalid`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-size-md`, `--slotted-font-size-sm`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-font-weight-semibold`, `--slotted-line-height-md`, `--slotted-radius-full`, `--slotted-radius-md`, `--slotted-radius-sm`, `--slotted-shadow-sm`, `--slotted-shadow-xs`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-space-9`, `--slotted-surface`, `--slotted-surface-sunken`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-surface`, `--slotted-tone-danger-border`, `--slotted-tone-danger-surface`, `--slotted-tone-danger-text`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-tone-success-text`, `--slotted-tone-warning-text`, `--slotted-upload-action-radius`, `--slotted-upload-action-size`, `--slotted-upload-border-width`, `--slotted-upload-card-actions-opacity`, `--slotted-upload-card-measure`, `--slotted-upload-field-section-gap`, `--slotted-upload-font-family`, `--slotted-upload-icon-size-min`, `--slotted-upload-item-background`, `--slotted-upload-item-border-color`, `--slotted-upload-item-gap`, `--slotted-upload-item-padding-block`, `--slotted-upload-item-padding-inline`, `--slotted-upload-item-radius`, `--slotted-upload-kind-archive`, `--slotted-upload-kind-audio`, `--slotted-upload-kind-document`, `--slotted-upload-kind-foreground`, `--slotted-upload-kind-image`, `--slotted-upload-kind-other`, `--slotted-upload-kind-pdf`, `--slotted-upload-kind-presentation`, `--slotted-upload-kind-spreadsheet`, `--slotted-upload-kind-video`, `--slotted-upload-label-font-weight`, `--slotted-upload-line-gap`, `--slotted-upload-name-font-weight`, `--slotted-upload-preview-radius`, `--slotted-upload-preview-size`, `--slotted-upload-radius`, `--slotted-upload-section-gap`, `--slotted-upload-state-layer-active`, `--slotted-upload-state-layer-hover`, `--slotted-upload-status-font-weight`, `--slotted-upload-trigger-background`, `--slotted-upload-viewer-control-opacity`, `--slotted-upload-viewer-control-size`, `--slotted-upload-viewer-tile-size`, `--slotted-upload-zone-background`, `--slotted-upload-zone-border-color`, `--slotted-upload-zone-border-width`, `--slotted-upload-zone-icon-size`, `--slotted-upload-zone-padding-block`, `--slotted-upload-zone-padding-inline`, `--slotted-upload-zone-state-layer-active`, `--slotted-upload-zone-state-layer-hover`
+
+## Examples
+
+See [upload.examples.md](./upload.examples.md).

package/dist/docs/visually-hidden.json

@@ -0,0 +1,92 @@
+{
+  "family": "visually-hidden",
+  "ui": "visually-hidden",
+  "binding": "react",
+  "catalog": {
+    "group": "Layout",
+    "summary": "Hides content visually, keeps it for readers."
+  },
+  "axes": {},
+  "members": {
+    "visuallyHidden": {
+      "nativeElement": "span",
+      "defaults": {
+        "focusable": false
+      },
+      "capabilities": [
+        "focusable"
+      ],
+      "states": [
+        "default"
+      ],
+      "parts": [
+        "root"
+      ]
+    }
+  },
+  "docs": {
+    "visuallyHidden": {
+      "imports": null,
+      "anatomy": [],
+      "api": [
+        {
+          "name": "focusable",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "VisuallyHidden",
+          "description": "Stops hiding the content while focus is inside it"
+        },
+        {
+          "name": "render",
+          "type": "(props) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "VisuallyHidden",
+          "description": "Renders a different element"
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "VisuallyHidden",
+          "description": "Content exposed only to assistive technology"
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "VisuallyHidden",
+          "description": "Class names, forwarded untouched"
+        }
+      ],
+      "composition": [],
+      "events": [],
+      "accessibility": [
+        "The content stays in the accessibility tree: the stylesheet clips it rather than applying display: none or visibility: hidden.",
+        "The content costs no space. The element is taken out of flow and held to one pixel, so a control that gains an accessible name this way is the size it was, and a hidden span between two flex items does not become a second gap.",
+        "A screen reader reads the content in document order, so it belongs where it would be read, not at the end of the document.",
+        "The whole string stays in the document, so a page search finds it and a selection copies it. Hidden text is content, not decoration.",
+        "focusable is for content a sighted keyboard user must be able to reach, such as a skip link. While focus is inside, the hiding rule stops matching and the element renders as the consumer wrote it — the component paints nothing on the revealed state, so the appearance of a skip link belongs to the link.",
+        "The component adds no role and no class. Wrap it in the element that carries the semantics, or hand the wiring to that element with render. Select it in the DOM as [data-ui=\"visually-hidden\"]."
+      ]
+    }
+  },
+  "tokens": [],
+  "examples": [
+    {
+      "id": "visually-hidden-react-icon-label",
+      "title": "An accessible name for an icon-only control",
+      "note": null,
+      "language": "tsx",
+      "source": "<button type=\"button\">\n  <TrashIcon aria-hidden=\"true\" />\n  <VisuallyHidden>Delete invoice</VisuallyHidden>\n</button>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "visually-hidden-react-skip-link",
+      "title": "A skip link that appears on focus",
+      "note": null,
+      "language": "tsx",
+      "source": "<VisuallyHidden focusable render={(props) => <a {...props} href=\"#main\" />}>\n  Skip to content\n</VisuallyHidden>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/dist/docs/visually-hidden.md

@@ -0,0 +1,45 @@
+<!-- index: ./index.md -->
+# visually-hidden
+
+`data-ui="visually-hidden"` · Hides content visually, keeps it for readers.
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<button type="button">
+  <TrashIcon aria-hidden="true" />
+  <VisuallyHidden>Delete invoice</VisuallyHidden>
+</button>;
+```
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `focusable` | `boolean` | false | VisuallyHidden | Stops hiding the content while focus is inside it |
+| `render` | `(props) => ReactNode` | — | VisuallyHidden | Renders a different element |
+| `children` | `ReactNode` | — | VisuallyHidden | Content exposed only to assistive technology |
+| `className` | `string` | — | VisuallyHidden | Class names, forwarded untouched |
+
+## Rules
+
+- The content stays in the accessibility tree: the stylesheet clips it rather than applying display: none or visibility: hidden.
+- The content costs no space. The element is taken out of flow and held to one pixel, so a control that gains an accessible name this way is the size it was, and a hidden span between two flex items does not become a second gap.
+- A screen reader reads the content in document order, so it belongs where it would be read, not at the end of the document.
+- The whole string stays in the document, so a page search finds it and a selection copies it. Hidden text is content, not decoration.
+- focusable is for content a sighted keyboard user must be able to reach, such as a skip link. While focus is inside, the hiding rule stops matching and the element renders as the consumer wrote it — the component paints nothing on the revealed state, so the appearance of a skip link belongs to the link.
+- The component adds no role and no class. Wrap it in the element that carries the semantics, or hand the wiring to that element with render. Select it in the DOM as [data-ui="visually-hidden"].
+
+## Examples
+
+### A skip link that appears on focus
+
+Excerpt — not a complete module
+
+```tsx
+<VisuallyHidden focusable render={(props) => <a {...props} href="#main" />}>
+  Skip to content
+</VisuallyHidden>;
+```