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

package/docs/attachment.json

@@ -0,0 +1,486 @@
+{
+  "family": "attachment",
+  "ui": "attachment",
+  "binding": "angular",
+  "catalog": {
+    "group": "Data display",
+    "summary": "File that belongs to a message or record."
+  },
+  "axes": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "orientation": [
+      "horizontal",
+      "vertical"
+    ],
+    "layout": [
+      "list",
+      "grid",
+      "strip"
+    ]
+  },
+  "members": {
+    "attachment": {
+      "nativeElement": "li",
+      "defaults": {
+        "size": "md",
+        "orientation": "horizontal",
+        "layout": "list",
+        "invalid": false,
+        "loading": false,
+        "disabled": false
+      },
+      "capabilities": [
+        "appearance",
+        "arrangement",
+        "size",
+        "orientation",
+        "content",
+        "invalid",
+        "loading",
+        "disabled",
+        "removable",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "invalid",
+        "loading",
+        "disabled"
+      ],
+      "parts": [
+        "root",
+        "group",
+        "preview",
+        "body",
+        "trigger",
+        "filename",
+        "name",
+        "extension",
+        "detail",
+        "message",
+        "progress",
+        "actions",
+        "action",
+        "remove"
+      ]
+    }
+  },
+  "docs": {
+    "attachment": {
+      "imports": {
+        "source": "import { provideAttachmentDefaults, SlAttachment, SlAttachmentAction, SlAttachmentActions, SlAttachmentBody, SlAttachmentDetail, SlAttachmentFilename, SlAttachmentGroup, SlAttachmentMessage, SlAttachmentPreview, SlAttachmentProgress, SlAttachmentRemove, SlAttachmentTrigger } from '@slotted/angular/attachment';",
+        "selector": "[slAttachment], [slAttachmentGroup], [slAttachmentPreview], [slAttachmentBody], a[slAttachmentTrigger], button[slAttachmentTrigger], [slAttachmentFilename], [slAttachmentDetail], [slAttachmentMessage], [slAttachmentProgress], [slAttachmentActions], button[slAttachmentAction], a[slAttachmentAction], button[slAttachmentRemove]",
+        "exportAs": "slAttachment, slAttachmentGroup, slAttachmentPreview, slAttachmentBody, slAttachmentTrigger, slAttachmentFilename, slAttachmentDetail, slAttachmentMessage, slAttachmentProgress, slAttachmentActions, slAttachmentAction, slAttachmentRemove"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "li, or div alone",
+          "required": true,
+          "purpose": "The attachment. Carries data-ui=\"attachment\", data-kind, data-size, data-orientation, data-invalid, data-loading, data-disabled and aria-busy, and handles Backspace and Delete when it is removable."
+        },
+        {
+          "part": "group",
+          "element": "ul",
+          "required": false,
+          "purpose": "The set, as a native list with tabindex -1: a column, a wrapping grid or one scrolling line. It hands its size and orientation down and keeps focus when an attachment leaves."
+        },
+        {
+          "part": "preview",
+          "element": "span",
+          "required": false,
+          "purpose": "The kind’s tile with the kind’s mark knocked out of it, or the thumbnail [src] names. A thumbnail that fails to load returns to the tile."
+        },
+        {
+          "part": "body",
+          "element": "div",
+          "required": true,
+          "purpose": "The text column, and the one box that shrinks so a long name truncates."
+        },
+        {
+          "part": "trigger",
+          "element": "a or button",
+          "required": false,
+          "purpose": "The file’s target. Named by the file, described by the detail and the message, and stretched over the whole attachment by a transparent ::after."
+        },
+        {
+          "part": "filename",
+          "element": "span",
+          "required": true,
+          "purpose": "The name as one run in its own direction: the trigger’s fallback content, or written on its own for a file that cannot be opened."
+        },
+        {
+          "part": "name",
+          "element": "span",
+          "required": true,
+          "purpose": "The stem, which shrinks to an ellipsis."
+        },
+        {
+          "part": "extension",
+          "element": "span",
+          "required": false,
+          "purpose": "The extension, which never shrinks, so the part that says what the file is stays."
+        },
+        {
+          "part": "detail",
+          "element": "p",
+          "required": false,
+          "purpose": "One line under the name. With nothing projected it writes the size with formatBytes in the language in force."
+        },
+        {
+          "part": "message",
+          "element": "p",
+          "required": false,
+          "purpose": "Why the file failed, under the name; it wraps rather than truncating a reason."
+        },
+        {
+          "part": "progress",
+          "element": "div",
+          "required": false,
+          "purpose": "The transfer, as the attachment’s bottom edge. Named by the file; indeterminate without a value."
+        },
+        {
+          "part": "actions",
+          "element": "div",
+          "required": false,
+          "purpose": "The application’s controls, beside the trigger and above its stretched target. On a card they stand on a plate over the picture."
+        },
+        {
+          "part": "action",
+          "element": "button or a",
+          "required": false,
+          "purpose": "One icon control of the application’s own: download, share, reply with."
+        },
+        {
+          "part": "remove",
+          "element": "button",
+          "required": false,
+          "purpose": "Asks to take the attachment out of its list. Hidden unless the attachment is removable; named Remove and the file name."
+        }
+      ],
+      "api": [
+        {
+          "name": "[file]",
+          "type": "{ name: string; type?: string; size?: number }",
+          "defaultValue": "—",
+          "appliesTo": "slAttachment",
+          "description": "Required. A File already is one; a server record needs only the name"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "slAttachment, slAttachmentGroup",
+          "description": "The room the attachment gets. Falls back to the group, then the token"
+        },
+        {
+          "name": "orientation",
+          "type": "'horizontal' | 'vertical'",
+          "defaultValue": "horizontal",
+          "appliesTo": "slAttachment, slAttachmentGroup",
+          "description": "A row, or a card stood on end. Falls back to the group, then the token"
+        },
+        {
+          "name": "layout",
+          "type": "'list' | 'grid' | 'strip'",
+          "defaultValue": "list",
+          "appliesTo": "slAttachmentGroup",
+          "description": "A column, a wrapping grid, or one line that scrolls"
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slAttachment",
+          "description": "The file failed: tinted ground, doubled edge, and the message named as the trigger description"
+        },
+        {
+          "name": "loading",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slAttachment",
+          "description": "aria-busy on the root and the trigger refused; remove stays operable"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slAttachment",
+          "description": "The trigger, every action and remove are refused"
+        },
+        {
+          "name": "removable",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slAttachment",
+          "description": "Shows slAttachmentRemove and lets Backspace and Delete ask for removal"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<AttachmentMessages>",
+          "defaultValue": "—",
+          "appliesTo": "slAttachment",
+          "description": "Words laid over the language in force, key by key: the remove control name (remove, with the file name) and the tile word for a file without an extension (noExtension)"
+        },
+        {
+          "name": "src",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slAttachmentPreview",
+          "description": "A thumbnail. Absent or failing, the kind tile is drawn"
+        },
+        {
+          "name": "value",
+          "type": "number | null",
+          "defaultValue": "null",
+          "appliesTo": "slAttachmentProgress",
+          "description": "Per cent, 0 to 100; null draws the indeterminate bar"
+        },
+        {
+          "name": "href / download",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "a[slAttachmentTrigger], a[slAttachmentAction]",
+          "description": "The anchor own attributes, untouched"
+        }
+      ],
+      "composition": [
+        {
+          "name": "provideAttachmentDefaults",
+          "type": "{ size, orientation, layout }",
+          "defaultValue": "—",
+          "appliesTo": "an injector",
+          "description": "Sets the three once; the group and the attachment still win"
+        },
+        {
+          "name": "exportAs",
+          "type": "slAttachment and every part",
+          "defaultValue": "—",
+          "appliesTo": "template reference",
+          "description": "#attachment=\"slAttachment\" reaches kind(), blocked() and request()"
+        },
+        {
+          "name": "projected content",
+          "type": "ng-content",
+          "defaultValue": "—",
+          "appliesTo": "trigger, filename, detail, remove",
+          "description": "Replaces the name, the size or the cross the family draws by default"
+        },
+        {
+          "name": "static attributes",
+          "type": "id, title, dir, type, aria-label, aria-describedby",
+          "defaultValue": "—",
+          "appliesTo": "every part",
+          "description": "Read with HostAttributeToken and kept; aria-describedby is joined, not replaced"
+        }
+      ],
+      "events": [
+        {
+          "name": "(remove)",
+          "payload": "{ reason: 'remove' | 'keyboard', file: AttachmentFile, source: Event }",
+          "when": "The remove control was pressed, or Backspace or Delete arrived inside a removable attachment. A request: the list is the page’s, and nothing leaves until the page removes it. Not emitted while disabled, nor for a repeated key."
+        }
+      ],
+      "accessibility": [
+        "The set is a native ul and each attachment an li, so a reader hears the count of files; an attachment alone goes on a div, because a list item outside a list is an error.",
+        "The trigger is a real a or button whose accessible name is the file name and whose description is the detail and the message, so a failed file is heard as its name and then its reason.",
+        "The trigger is stretched over the attachment by a transparent pseudo-element rather than wrapping it, because interactive content may not nest inside a or button; the actions are its siblings and sit above it.",
+        "ARIA 1.2 deprecates aria-invalid and aria-disabled on listitem, so the three states are painted from data attributes on the root and carried by the controls: disabled on a button, aria-disabled on a link that keeps its destination.",
+        "A refused link is refused by slAttachment in the capture phase, so the page’s own (click) on the trigger never runs while the file is loading or unavailable.",
+        "Backspace and Delete ask to remove a removable attachment from wherever focus is inside it; a held key does not repeat the request, and a field inside the attachment keeps its editing keys.",
+        "When an attachment leaves, focus goes to the control that took its place, then to the last one, then to the list, which holds tabindex -1 for that purpose.",
+        "The progress bar is named by the file, so a reader hears the file and the percentage together, and without a value it is announced as indeterminate."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-attachment-action-radius",
+    "--slotted-attachment-action-size",
+    "--slotted-attachment-action-state-layer-active",
+    "--slotted-attachment-action-state-layer-hover",
+    "--slotted-attachment-background",
+    "--slotted-attachment-border-color",
+    "--slotted-attachment-border-width",
+    "--slotted-attachment-card-actions-opacity",
+    "--slotted-attachment-card-preview-radius",
+    "--slotted-attachment-card-size",
+    "--slotted-attachment-font-family",
+    "--slotted-attachment-grid-min",
+    "--slotted-attachment-group-gap",
+    "--slotted-attachment-icon-size-min",
+    "--slotted-attachment-line-gap",
+    "--slotted-attachment-name-font-weight",
+    "--slotted-attachment-padding-lg",
+    "--slotted-attachment-padding-md",
+    "--slotted-attachment-padding-sm",
+    "--slotted-attachment-preview-radius",
+    "--slotted-attachment-preview-size",
+    "--slotted-attachment-radius",
+    "--slotted-attachment-state-layer-active",
+    "--slotted-attachment-state-layer-hover",
+    "--slotted-attachment-strip-item-size",
+    "--slotted-border-strong",
+    "--slotted-border-subtle",
+    "--slotted-border-width-thin",
+    "--slotted-control-font-family",
+    "--slotted-control-font-size-lg",
+    "--slotted-control-font-size-md",
+    "--slotted-control-font-size-sm",
+    "--slotted-control-gap-lg",
+    "--slotted-control-gap-md",
+    "--slotted-control-gap-sm",
+    "--slotted-control-icon-size-lg",
+    "--slotted-control-icon-size-md",
+    "--slotted-control-icon-size-sm",
+    "--slotted-control-invalid-edge-width",
+    "--slotted-control-radius",
+    "--slotted-control-transition-duration",
+    "--slotted-control-transition-easing",
+    "--slotted-disabled-background",
+    "--slotted-disabled-foreground",
+    "--slotted-duration-instant",
+    "--slotted-duration-medium",
+    "--slotted-duration-short",
+    "--slotted-easing-enter",
+    "--slotted-easing-exit",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width",
+    "--slotted-font-size-xs",
+    "--slotted-font-weight-medium",
+    "--slotted-font-weight-semibold",
+    "--slotted-line-height-md",
+    "--slotted-radius-lg",
+    "--slotted-radius-md",
+    "--slotted-radius-sm",
+    "--slotted-shadow-xs",
+    "--slotted-space-1",
+    "--slotted-space-2",
+    "--slotted-space-3",
+    "--slotted-space-4",
+    "--slotted-space-5",
+    "--slotted-surface",
+    "--slotted-target-comfortable",
+    "--slotted-target-min",
+    "--slotted-text",
+    "--slotted-text-muted",
+    "--slotted-tone-danger-border",
+    "--slotted-tone-danger-surface",
+    "--slotted-tone-danger-text",
+    "--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"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One attachment with every input on the controls below the canvas. Point at it: the whole attachment answers, and the remove control answers on its own.",
+      "language": "html",
+      "source": "<li slAttachment [file]=\"file\" removable (remove)=\"drop($event.file)\">\n  <span slAttachmentPreview></span>\n  <div slAttachmentBody>\n    <a slAttachmentTrigger [href]=\"file.url\"></a>\n    <p slAttachmentDetail></p>\n  </div>\n  <div slAttachmentActions><button slAttachmentRemove></button></div>\n</li>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "anatomy",
+      "title": "Every part, and a file with almost none",
+      "note": "An absent part leaves no column behind: without a tile or actions the name takes the width they held. A file that cannot be opened writes its name without a trigger.",
+      "language": "html",
+      "source": "<div slAttachment [file]=\"{ name: 'telematics-export' }\">\n  <div slAttachmentBody>\n    <span slAttachmentFilename></span>\n    <p slAttachmentDetail>No preview available</p>\n  </div>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sizes",
+      "title": "Three sizes, one tile rule",
+      "note": "The tile is the height of the two lines beside it — 40 pixels at md — so its edges meet the name’s cap and the detail’s foot. Density shrinks all three with the fields around them.",
+      "language": "html",
+      "source": "<div slAttachment [file]=\"file\" size=\"sm\"></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "orientation",
+      "title": "A row, or a card stood on end",
+      "note": "A card is three tiles wide — 120 pixels at md — with the picture square inside it. The actions move onto the picture on a plate of their own, and a card with no picture writes its extension under the mark.",
+      "language": "html",
+      "source": "<li slAttachment [file]=\"photo\" orientation=\"vertical\" removable (remove)=\"drop(photo)\">\n  <span slAttachmentPreview [src]=\"photo.thumbnail\"></span>\n  <div slAttachmentBody>\n    <button slAttachmentTrigger (click)=\"openViewer(photo)\"></button>\n    <p slAttachmentDetail></p>\n  </div>\n  <div slAttachmentActions><button slAttachmentRemove></button></div>\n</li>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "layout",
+      "title": "A column, a grid, a scrolling tray",
+      "note": "The group is a native list. Grid rows share the width and never go narrower than a name; cards keep their own width so each is a whole pixel. The strip scrolls on one line and snaps to each attachment, and its ring never meets the clip.",
+      "language": "html",
+      "source": "<ul slAttachmentGroup aria-label=\"Attached to your reply\" layout=\"strip\" size=\"sm\">\n  @for (file of files(); track file.name) {\n    <li slAttachment [file]=\"file\" removable (remove)=\"drop(file)\">\n      <span slAttachmentPreview></span>\n      <div slAttachmentBody>\n        <span slAttachmentFilename></span>\n        <p slAttachmentDetail></p>\n      </div>\n      <div slAttachmentActions><button slAttachmentRemove></button></div>\n    </li>\n  }\n</ul>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "kinds",
+      "title": "Nine kinds, read before the name",
+      "note": "The kind comes from the media type first and the extension second, and paints the tile from the scale upload uses, so a PDF is the same red in a reply as in the upload it came from. A thumbnail replaces the tile, and falls back to it if it fails.",
+      "language": "html",
+      "source": "<div slAttachment [file]=\"{ name: 'repair-estimate.xlsx', size: 86000 }\">\n  <span slAttachmentPreview></span>\n  <div slAttachmentBody>\n    <span slAttachmentFilename></span>\n    <p slAttachmentDetail></p>\n  </div>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "trigger",
+      "title": "A link, or a button that opens a viewer",
+      "note": "On an a the trigger is a real anchor, so href, download and a modified click are the browser’s; on a button it is a real button for a viewer the page opens. Either one is the whole attachment’s target, and the ring goes round the attachment.",
+      "language": "html",
+      "source": "<a slAttachmentTrigger [href]=\"file.url\"></a>\n<button slAttachmentTrigger (click)=\"openViewer(file)\"></button>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "actions",
+      "title": "Actions beside the file, never inside it",
+      "note": "slAttachmentAction is an inner control on the button or the a the page wrote: no frame at rest, a state layer on hover and a deeper one on press. The remove control is hidden unless the attachment is removable.",
+      "language": "html",
+      "source": "<div slAttachmentActions>\n  <a slAttachmentAction [href]=\"file.url\" download [attr.aria-label]=\"'Download ' + file.name\">\n    <span slIcon><svg slGlyph name=\"external\"></svg></span>\n  </a>\n  <button slAttachmentRemove></button>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "Failed, sending, waiting, unavailable",
+      "note": "A failed file tints its ground, doubles its edge and says why in a sentence the trigger names as its description; its tile keeps the kind. A sending file carries its bar as its bottom edge and refuses its trigger but not remove.",
+      "language": "html",
+      "source": "<li slAttachment [file]=\"file\" [loading]=\"percent() < 100\" removable (remove)=\"cancel()\">\n  <span slAttachmentPreview></span>\n  <div slAttachmentBody>\n    <button slAttachmentTrigger></button>\n    <p slAttachmentDetail>Uploading · {{ percent() }}%</p>\n  </div>\n  <div slAttachmentProgress [value]=\"percent()\"></div>\n  <div slAttachmentActions><button slAttachmentRemove></button></div>\n</li>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Names the family did not choose",
+      "note": "The stem shrinks and the extension stays, so a sixty-character report still ends in .pdf; the whole name stays in the title. A name in Arabic keeps its own direction, and a name with no dot is one run.",
+      "language": "html",
+      "source": "<div slAttachment [file]=\"report\"></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "In a claim thread",
+      "note": "A message carries its files the way the product would: the group under the text, links that download, one file still sending. provideAttachmentDefaults sets the size once for the application; the words and the locale come from provideSlotted.",
+      "language": "ts",
+      "source": "bootstrapApplication(App, {\n  providers: [provideAttachmentDefaults({ size: 'sm' })],\n});\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "Tab reaches every control; Delete asks",
+      "note": "Tab reaches the trigger, each action and remove. Backspace or Delete anywhere in a removable attachment asks to remove it, a held key is ignored, and focus moves to the attachment that took its place, then the last one, then the list.",
+      "language": "html",
+      "source": "<li slAttachment [file]=\"file\" removable (remove)=\"drop($event.file, $event.reason)\"></li>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}