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

package/docs/upload.md

@@ -0,0 +1,166 @@
+<!-- index: ./index.md -->
+# upload
+
+`data-ui="upload"` · Picks or drops files and shows their progress.
+
+## Import
+
+```ts
+import { provideUploadDefaults, SlUpload } from '@slotted/angular/upload';
+import { createXhrUpload } from '@slotted/core/upload';
+```
+
+Selector: `div[slUpload]` · exportAs: `slUpload`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div
+  accept="application/pdf,image/*"
+  description="PDF, JPEG or PNG, up to 10 MB each."
+  label="Supporting documents"
+  multiple
+  slUpload
+></div>
+```
+
+## 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` | `model<readonly UploadFile[]>` | [] | div[slUpload] | The selection, as a two-way binding. Each entry carries the file, its kind, its status, the bytes moved and the reason it was refused; `filesRequest` carries the reason a movement happened. |
+| `viewing` | `model<string \| null>` | null | div[slUpload] | The key of the file the viewer is open on, as a two-way binding |
+| `variant` | `'dropzone' \| 'button' \| 'field'` | dropzone | div[slUpload] | Which of the three shapes the consolidation names is drawn |
+| `layout` | `'list' \| 'grid'` | list | div[slUpload] | A column of rows, or a wall of pictures |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | div[slUpload] | The step every control measure in the family reads |
+| `preview` | `'auto' \| 'none'` | auto | div[slUpload] | Whether an image gets a thumbnail from an object URL the family revokes |
+| `view` | `'auto' \| 'none'` | auto | div[slUpload] | Whether a file the browser can render opens in the viewer from its own name |
+| `duplicates` | `'reject' \| 'allow' \| 'replace'` | reject | div[slUpload] | What happens to a second copy of a file the list already holds |
+| `accept` | `string` | — | div[slUpload] | The same syntax the attribute takes, applied to a drop as well as to the dialog |
+| `multiple` | `boolean` | false | div[slUpload] | Whether more than one file may be held. Multiple appends; single replaces. |
+| `directory` | `boolean` | false | div[slUpload] | Whether the picker chooses folders. Each file keeps its webkitRelativePath. |
+| `capture` | `'user' \| 'environment'` | — | div[slUpload] | Which camera the picker opens on a device that has one |
+| `maxFiles` | `number` | — | div[slUpload] | How many files may be kept. The extras are reported, never truncated in silence. |
+| `minFiles` | `number` | — | div[slUpload] | How many the form needs. Reported to Reactive Forms as minFiles. |
+| `maxSize` | `number` | — | div[slUpload] | The largest a single file may be, in bytes |
+| `minSize` | `number` | — | div[slUpload] | The smallest, in bytes. A zero-byte file is the common case it catches. |
+| `maxTotalSize` | `number` | — | div[slUpload] | The largest the whole selection may be, in bytes |
+| `validate` | `(file) => reason \| null` | — | div[slUpload] | The consumer’s own rule, run after the family’s. It is fileValidator in the class, because Validator.validate is a method this directive already has. |
+| `transform` | `(files) => files \| Promise<files>` | — | div[slUpload] | Rewrites the selection before it is judged: compression, renaming, cropping |
+| `fileKey` | `(file) => string` | name, size and lastModified | div[slUpload] | What makes two files the same file |
+| `adapter` | `UploadAdapter \| send` | — | div[slUpload] | What moves the bytes. Without one the family selects and holds. |
+| `autoUpload` | `boolean` | true | div[slUpload] | Whether an accepted file is sent at once, or waits for the reader |
+| `concurrency` | `number` | 3 | div[slUpload] | How many transfers run at the same time |
+| `retries` | `number` | 0 | div[slUpload] | How many times a failure is sent again. Off, because a POST retried is a second record. |
+| `retryDelay` | `number` | 1000 | div[slUpload] | The first backoff, doubled for each further attempt |
+| `stallAfter` | `number` | 10000 | div[slUpload] | How long without a progress report before a running transfer is called stalled |
+| `maxRows` | `number` | 6 | div[slUpload] | How many rows the list shows before the platform scrolls the rest. 0 is no bound. |
+| `clickToBrowse` | `boolean` | true | div[slUpload] | Whether pressing the region opens the picker |
+| `allowDrop` | `boolean` | true | div[slUpload] | Whether the region takes a drop |
+| `allowPaste` | `boolean` | true | div[slUpload] | Whether a file on the clipboard may be pasted into the region |
+| `preventDocumentDrop` | `boolean` | true | div[slUpload] | Whether a file dropped beside the region is stopped from navigating the browser away |
+| `pendingBlocksSubmit` | `boolean` | true | div[slUpload] | Whether a transfer still running makes the control invalid |
+| `locale` | `string` | the language in force | div[slUpload] | BCP 47, for the size and the time left |
+| `label` | `string` | — | div[slUpload] | The family’s own label, drawn only outside a field |
+| `description` | `string` | — | div[slUpload] | The guidance, and the input’s aria-describedby |
+| `disabled` | `boolean` | false | div[slUpload] | Refuses the picker and the drop alike, because a drag is not routed through the input at all |
+| `readOnly` | `boolean` | false | div[slUpload] | Keeps the list readable and takes every control away |
+| `invalid` | `boolean` | false | div[slUpload] | Retargets the focus ring to the danger colour and marks the region |
+| `required` | `boolean` | false | div[slUpload] | Reaches the native input, so an empty selection is valueMissing before any of the family’s own rules run |
+| `name` | `string` | — | div[slUpload] | What the native input submits under |
+| `messages` | `Partial<UploadMessages>` | — | div[slUpload] | 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.*) |
+| `provideUploadDefaults` | `provider` | — | any injector | Sets the adapter, the limits and the behaviour once for the application; the words come from provideSlotted |
+| `UPLOAD_DEFAULTS` | `InjectionToken` | — | any injector | What the provider fills, for a page that wants to read what an upload here would do |
+| `exportAs="slUpload"` | `template reference` | — | div[slUpload] | browse(), upload(), retryAll(), cancelAll() and setViewing() — what a template cannot write |
+| `ControlValueAccessor` | `implemented` | — | div[slUpload] | formControl and ngModel hold the selection. writeValue accepts UploadFile[] or File[] and normalises. |
+| `Validator` | `implemented` | — | div[slUpload] | required, minFiles, maxFiles and uploadPending reach the form as errors, so a Reactive Form agrees with the DOM |
+| `ng-content` | `projection` | — | div[slUpload] | Projected into the root, which is where an application puts its own note or its own control |
+| `createXhrUpload` | `(options) => UploadAdapter` | — | @slotted/core/upload | The sender this library ships: url, method, headers, field name, credentials, and a parse of your own |
+| `SlProgressBar` | `directive` | — | 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. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `filesChange` | `readonly UploadFile[]` | The two-way binding’s own output, so [(files)] holds the selection. It fires after every movement: a pick, a drop, a paste, a removal, a clear, or the transfer reporting on a row. |
+| `filesRequest` | `ChangeRequest<readonly UploadFile[]>` | Before the selection moves, carrying the new value, the value it replaces, the reason — select, pointer, keyboard, remove, clear or programmatic — the originating event and cancel(). A two-way binding has one slot and can carry none of those. |
+| `viewingChange, viewingRequest` | `string \| null, ChangeRequest<string \| null>` | When the reader opens a file, moves to another, or closes the viewer. The reason says which: pointer, keyboard, escape, outsidePress, dismiss or programmatic. |
+| `reject` | `readonly UploadFile[]` | 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. |
+
+## 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.
+- The viewer is modal: focus is contained inside it, 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 twice over: setCustomValidity on the control the reader can see, and { uploadPending: true } from Validator so a Reactive Form agrees with it. None of the nine surveyed implementations answers this at all.
+
+## 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/docs/visually-hidden.json

@@ -0,0 +1,71 @@
+{
+  "family": "visually-hidden",
+  "ui": "visually-hidden",
+  "binding": "angular",
+  "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": "slVisuallyHidden",
+          "description": "Stops hiding the content while focus is inside it"
+        }
+      ],
+      "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 it was written — the family paints nothing on the revealed state, so the appearance of a skip link belongs to the link.",
+        "The selector is the bare attribute, so it applies to whichever element carries the semantics: a span, an anchor, or a table cell. It adds no role and no class, and is selected in the DOM as [data-ui=\"visually-hidden\"]."
+      ]
+    }
+  },
+  "tokens": [],
+  "examples": [
+    {
+      "id": "visually-hidden-angular-icon-label",
+      "title": "An accessible name for an icon-only control",
+      "note": null,
+      "language": "html",
+      "source": "<button type=\"button\">\n  <svg aria-hidden=\"true\" viewBox=\"0 0 24 24\">\n    <path d=\"M18 6 6 18M6 6l12 12\" />\n  </svg>\n  <span slVisuallyHidden>Delete invoice</span>\n</button>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "visually-hidden-angular-skip-link",
+      "title": "A skip link that appears on focus",
+      "note": null,
+      "language": "html",
+      "source": "<a slVisuallyHidden focusable href=\"#main\">Skip to content</a>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/docs/visually-hidden.md

@@ -0,0 +1,42 @@
+<!-- index: ./index.md -->
+# visually-hidden
+
+`data-ui="visually-hidden"` · Hides content visually, keeps it for readers.
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<button type="button">
+  <svg aria-hidden="true" viewBox="0 0 24 24">
+    <path d="M18 6 6 18M6 6l12 12" />
+  </svg>
+  <span slVisuallyHidden>Delete invoice</span>
+</button>
+```
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `focusable` | `boolean` | false | slVisuallyHidden | Stops hiding the content while focus is inside it |
+
+## 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 it was written — the family paints nothing on the revealed state, so the appearance of a skip link belongs to the link.
+- The selector is the bare attribute, so it applies to whichever element carries the semantics: a span, an anchor, or a table cell. It adds no role and no class, and is selected in the DOM as [data-ui="visually-hidden"].
+
+## Examples
+
+### A skip link that appears on focus
+
+Excerpt — not a complete module
+
+```html
+<a slVisuallyHidden focusable href="#main">Skip to content</a>
+```