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

package/docs/list-item.json

@@ -0,0 +1,463 @@
+{
+  "family": "list-item",
+  "ui": "list-item",
+  "binding": "angular",
+  "catalog": {
+    "group": "Data display",
+    "summary": "Row with media, text, metadata and actions."
+  },
+  "axes": {
+    "tone": [
+      "secondary",
+      "accent",
+      "success",
+      "warning",
+      "danger"
+    ],
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "align": [
+      "center",
+      "start"
+    ]
+  },
+  "members": {
+    "listItem": {
+      "nativeElement": "li",
+      "defaults": {
+        "tone": "secondary",
+        "size": "md",
+        "align": "center",
+        "inset": false,
+        "truncate": false,
+        "selected": false,
+        "current": false,
+        "disabled": false,
+        "loading": false
+      },
+      "capabilities": [
+        "appearance",
+        "size",
+        "disabled",
+        "loading",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "selected",
+        "current",
+        "loading",
+        "disabled"
+      ],
+      "parts": [
+        "root",
+        "marker",
+        "content",
+        "start",
+        "body",
+        "label",
+        "description",
+        "end",
+        "actions"
+      ]
+    }
+  },
+  "docs": {
+    "listItem": {
+      "imports": {
+        "source": "import { SlListItem, SlListItemActions, SlListItemBody, SlListItemContent, SlListItemDescription, SlListItemEnd, SlListItemLabel, SlListItemStart } from '@slotted/angular/list-item';",
+        "selector": "li[slListItem], [slListItemContent], [slListItemStart], [slListItemBody], [slListItemLabel], [slListItemDescription], [slListItemEnd], [slListItemActions]",
+        "exportAs": "slListItem, slListItemContent, slListItemStart, slListItemBody, slListItemLabel, slListItemDescription, slListItemEnd, slListItemActions"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "li, or the element render returns",
+          "required": true,
+          "purpose": "The row. Carries data-ui=\"list-item\", every axis, data-selected, data-current, data-disabled, data-loading and aria-current. It is its own container, so the row reflows on its own inline size rather than the viewport."
+        },
+        {
+          "part": "marker",
+          "element": "span",
+          "required": false,
+          "purpose": "The bullet, rendered only when marker is bullet: the dot Glyph in the marker column, before content and hidden from assistive technology. A numbered marker is a counter the stylesheet writes, because it is text."
+        },
+        {
+          "part": "content",
+          "element": "div, button or a",
+          "required": true,
+          "purpose": "The box that is read, hovered, focused and — for two of the three — activated. Three elements rather than one as prop, because the three are three different accessibility trees."
+        },
+        {
+          "part": "start",
+          "element": "div",
+          "required": false,
+          "purpose": "The leading column: an icon, an avatar, a Checkbox. It is the slot and not the control, and the chooser here is also what announces a selection the row only paints."
+        },
+        {
+          "part": "body",
+          "element": "div",
+          "required": false,
+          "purpose": "The text column, and the one box in the row that may shrink — which is what lets an unbroken token break instead of pushing the metadata out of the row."
+        },
+        {
+          "part": "label",
+          "element": "div",
+          "required": false,
+          "purpose": "The title. It clips under truncate, isolates its own direction so another script does not reorder the row, and breaks a single unbroken token."
+        },
+        {
+          "part": "description",
+          "element": "div",
+          "required": false,
+          "purpose": "The lines under the title. They clip with it, never instead of it."
+        },
+        {
+          "part": "end",
+          "element": "div",
+          "required": false,
+          "purpose": "Trailing metadata that is part of what the row says — a timestamp, a count, a Badge. Below 22rem it leaves the inline axis and sits under the title."
+        },
+        {
+          "part": "actions",
+          "element": "div",
+          "required": false,
+          "purpose": "Independent targets, and a sibling of the box rather than its child: interactive content may not nest inside an a or a button."
+        }
+      ],
+      "api": [
+        {
+          "name": "tone",
+          "type": "'secondary' | 'accent' | 'success' | 'warning' | 'danger'",
+          "defaultValue": "secondary",
+          "appliesTo": "slListItem",
+          "description": "The row ink, the wash under the pointer and the ground of a selected row. It never fills a resting row"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "slListItem",
+          "description": "The room the row gets. Falls back to the list, then the injected default"
+        },
+        {
+          "name": "align",
+          "type": "'center' | 'start'",
+          "defaultValue": "center",
+          "appliesTo": "slListItem",
+          "description": "Where the leading visual and the metadata sit against a row of more than one line"
+        },
+        {
+          "name": "inset",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slListItem",
+          "description": "Takes the row inline padding away. Falls back to the list, then the injected default"
+        },
+        {
+          "name": "truncate",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slListItem",
+          "description": "Clips the title and the lines under it to one line each. The whole string stays in the document"
+        },
+        {
+          "name": "selected",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slListItem",
+          "description": "Mirrors a selection the page owns. The slCheckbox in slListItemStart is what announces it"
+        },
+        {
+          "name": "current",
+          "type": "boolean | 'page' | 'step' | 'location' | 'date' | 'time'",
+          "defaultValue": "false",
+          "appliesTo": "slListItem",
+          "description": "The row the reader is on, written as aria-current — the one state of this shape a listitem may announce"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slListItem",
+          "description": "The row dims and refuses the activation. The attribute goes on the box, never on the li"
+        },
+        {
+          "name": "loading",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slListItem",
+          "description": "aria-busy on the box and the activation withdrawn. The width and the accessible name are kept"
+        },
+        {
+          "name": "variant",
+          "type": "'plain' | 'ruled' | 'framed' | 'separated'",
+          "defaultValue": "—",
+          "appliesTo": "slListItem",
+          "description": "How the rows are told apart. Falls back to the list, then to plain"
+        },
+        {
+          "name": "marker",
+          "type": "'none' | 'bullet' | 'number'",
+          "defaultValue": "—",
+          "appliesTo": "slListItem",
+          "description": "What is painted in the marker column. Falls back to the list, then to none"
+        },
+        {
+          "name": "position / setSize",
+          "type": "number",
+          "defaultValue": "—",
+          "appliesTo": "slListItem",
+          "description": "aria-posinset and aria-setsize, written only when the page knows them"
+        },
+        {
+          "name": "href / routerLink",
+          "type": "string | unknown[]",
+          "defaultValue": "—",
+          "appliesTo": "the element",
+          "description": "Not an input: slListItemContent goes on the anchor the page wrote, so the router link stays the page own"
+        },
+        {
+          "name": "exportAs",
+          "type": "slListItem | slListItemContent | slListItemStart | slListItemBody | slListItemLabel | slListItemDescription | slListItemEnd | slListItemActions",
+          "defaultValue": "—",
+          "appliesTo": "every directive",
+          "description": "Reaches the instance from a template"
+        },
+        {
+          "name": "provideListItemDefaults",
+          "type": "{ tone, size, align, inset, truncate }",
+          "defaultValue": "—",
+          "appliesTo": "an injector",
+          "description": "Sets the five once for every row under it; an explicit input still wins"
+        }
+      ],
+      "composition": [],
+      "events": [],
+      "accessibility": [
+        "The row is an li, and ARIA 1.2 is unusually specific about what a listitem may carry: aria-level, aria-posinset and aria-setsize are supported, aria-current and aria-busy are inherited, and aria-disabled, aria-invalid, aria-errormessage and aria-haspopup are deprecated on the role.",
+        "disabled is therefore painted from data-disabled on the row while the attribute that means it goes on the box, and slListItemContent reads the element it is on to choose which: the native disabled on a button, aria-disabled on an anchor. No surveyed implementation makes the distinction; MUI writes aria-disabled on the row, where it is deprecated.",
+        "A disabled link keeps its destination. aria-disabled means perceivable but not operable and leaves the element focusable, so a reader can still reach the row and hear the description that says why it is unavailable.",
+        "The refusal is a capture listener on the row rather than a host listener on the box. A directive host listener and a click the page wrote sit on the same target and run in registration order, and the page own was registered first — a refusal on the box arrived after the handler it was meant to stop. A capture listener on an ancestor always runs first, and it refuses only what is inside the box.",
+        "selected is painted and never announced, because aria-selected is not valid on a listitem. The slCheckbox the page composes into slListItemStart is what carries the state for assistive technology.",
+        "current is announced, with aria-current and the token the page states. An aria-current the page wrote itself is read with HostAttributeToken and kept.",
+        "position and setSize are written only when the page states them. ARIA 1.2 says both are unnecessary while every row is in the document and necessary the moment only part of the set is.",
+        "slListItemActions is a sibling of the box and never its child, because interactive content may not nest inside an a or a button. A control inside it is the page own to disable: a disabled row refuses its own box and nothing else.",
+        "The row binds no key. Enter on a link, Enter and Space on a button, and the modified click a browser gives an anchor are the platform own behaviour.",
+        "The focus ring is drawn inside the row rather than around it, because a row runs the full width of its set: an outward ring on the first row of a framed list is drawn under the frame.",
+        "Selection is said with a fill and an edge together, because every tone surface is the page own white in the high-contrast scheme.",
+        "The title isolates its own direction and breaks a single unbroken token rather than pushing the metadata out of the row."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-subtle",
+    "--slotted-border-width-thin",
+    "--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-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-padding-inline-lg",
+    "--slotted-control-padding-inline-md",
+    "--slotted-control-padding-inline-sm",
+    "--slotted-control-transition-duration",
+    "--slotted-control-transition-easing",
+    "--slotted-disabled-border",
+    "--slotted-disabled-foreground",
+    "--slotted-duration-short",
+    "--slotted-easing-standard",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width",
+    "--slotted-font-size-xs",
+    "--slotted-font-weight-medium",
+    "--slotted-font-weight-regular",
+    "--slotted-line-height-md",
+    "--slotted-line-height-sm",
+    "--slotted-list-item-background",
+    "--slotted-list-item-background-active",
+    "--slotted-list-item-background-current",
+    "--slotted-list-item-background-hover",
+    "--slotted-list-item-background-selected",
+    "--slotted-list-item-body-gap",
+    "--slotted-list-item-border-color",
+    "--slotted-list-item-border-width",
+    "--slotted-list-item-color",
+    "--slotted-list-item-color-disabled",
+    "--slotted-list-item-color-muted",
+    "--slotted-list-item-control-size",
+    "--slotted-list-item-control-size-lg",
+    "--slotted-list-item-control-size-sm",
+    "--slotted-list-item-description-font-size",
+    "--slotted-list-item-font-size",
+    "--slotted-list-item-font-size-lg",
+    "--slotted-list-item-font-size-sm",
+    "--slotted-list-item-font-weight",
+    "--slotted-list-item-font-weight-current",
+    "--slotted-list-item-font-weight-selected",
+    "--slotted-list-item-gap",
+    "--slotted-list-item-gap-lg",
+    "--slotted-list-item-gap-sm",
+    "--slotted-list-item-icon-size",
+    "--slotted-list-item-icon-size-lg",
+    "--slotted-list-item-icon-size-sm",
+    "--slotted-list-item-min-block-size",
+    "--slotted-list-item-min-block-size-lg",
+    "--slotted-list-item-min-block-size-sm",
+    "--slotted-list-item-padding-block",
+    "--slotted-list-item-padding-block-lg",
+    "--slotted-list-item-padding-block-sm",
+    "--slotted-list-item-padding-inline",
+    "--slotted-list-item-padding-inline-lg",
+    "--slotted-list-item-padding-inline-sm",
+    "--slotted-list-item-radius",
+    "--slotted-radius-md",
+    "--slotted-selection-size-lg",
+    "--slotted-selection-size-md",
+    "--slotted-selection-size-sm",
+    "--slotted-space-1",
+    "--slotted-space-2",
+    "--slotted-surface-raised",
+    "--slotted-surface-sunken",
+    "--slotted-text",
+    "--slotted-text-muted",
+    "--slotted-tone-accent-border",
+    "--slotted-tone-accent-solid-active",
+    "--slotted-tone-accent-solid-hover",
+    "--slotted-tone-accent-subtle-active",
+    "--slotted-tone-accent-subtle-hover",
+    "--slotted-tone-accent-surface",
+    "--slotted-tone-accent-text",
+    "--slotted-tone-danger-border",
+    "--slotted-tone-danger-solid-active",
+    "--slotted-tone-danger-solid-hover",
+    "--slotted-tone-danger-subtle-active",
+    "--slotted-tone-danger-subtle-hover",
+    "--slotted-tone-danger-surface",
+    "--slotted-tone-danger-text",
+    "--slotted-tone-secondary-border",
+    "--slotted-tone-secondary-solid-active",
+    "--slotted-tone-secondary-solid-hover",
+    "--slotted-tone-secondary-subtle-active",
+    "--slotted-tone-secondary-subtle-hover",
+    "--slotted-tone-secondary-surface",
+    "--slotted-tone-success-border",
+    "--slotted-tone-success-solid-active",
+    "--slotted-tone-success-solid-hover",
+    "--slotted-tone-success-subtle-active",
+    "--slotted-tone-success-subtle-hover",
+    "--slotted-tone-success-surface",
+    "--slotted-tone-success-text",
+    "--slotted-tone-warning-border",
+    "--slotted-tone-warning-solid-active",
+    "--slotted-tone-warning-solid-hover",
+    "--slotted-tone-warning-subtle-active",
+    "--slotted-tone-warning-subtle-hover",
+    "--slotted-tone-warning-surface",
+    "--slotted-tone-warning-text"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One row with every input on it, driven by the controls below the canvas. Tab lands on the box and then on the control beside it; the family binds no key of its own.",
+      "language": "html",
+      "source": "<li slListItem>\n  <a slListItemContent href=\"/photos\">\n    <span slListItemBody><span slListItemLabel>Photos</span></span>\n    <span slListItemEnd>Yesterday</span>\n  </a>\n</li>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content-elements",
+      "title": "One directive, three trees",
+      "note": "The directive goes on the element the page wrote, so the router link, the form ownership and the modified click a browser gives an anchor all stay the page own.",
+      "language": "html",
+      "source": "<div slListItemContent></div>\n<button slListItemContent type=\"button\"></button>\n<a slListItemContent [routerLink]=\"['/photos']\"></a>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "anatomy",
+      "title": "Every part, and a row with almost none",
+      "note": "Every part but the box is optional, and an absent one leaves no column behind: each gap is a margin on the part rather than a track on the grid.",
+      "language": "html",
+      "source": "<li slListItem>\n  <div slListItemContent>\n    <span slListItemStart></span>\n    <span slListItemBody>\n      <span slListItemLabel>Photos</span>\n      <span slListItemDescription>128 files</span>\n    </span>\n    <span slListItemEnd>Yesterday</span>\n  </div>\n  <span slListItemActions></span>\n</li>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "alignment",
+      "title": "Where the leading visual sits",
+      "note": "center is right while the block is one line and wrong as soon as it is three. start returns the mark and the metadata to the title own line, so a row of three lines reads from one corner.",
+      "language": "html",
+      "source": "<li slListItem align=\"center\"></li>\n<li slListItem align=\"start\"></li>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "tone",
+      "title": "The five the theme carries",
+      "note": "A tone moves the ink, the wash under the pointer and the ground of a selected row, and never fills a resting row: forty rows each filled with a tone is a list nobody can read.",
+      "language": "html",
+      "source": "<li slListItem tone=\"danger\">\n  <button slListItemContent type=\"button\" (click)=\"destroy()\">Delete the workspace</button>\n</li>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "Every state the row paints",
+      "note": "Selection is the accent ground, the accent ink and a one-pixel edge together, because every tone surface is white in the high-contrast scheme. Current is the neutral ground with its own edge, so a row can be both at once and the selection is what shows without either of them being lost.",
+      "language": "html",
+      "source": "<li slListItem selected></li>\n<li slListItem current=\"page\"></li>\n<li slListItem loading></li>\n<li slListItem disabled></li>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "actions",
+      "title": "Independent targets",
+      "note": "The two targets are siblings, so the row hit area stops before the button. A disabled row refuses its own box and nothing else: the control beside it is the page own to disable.",
+      "language": "html",
+      "source": "<li slListItem>\n  <a slListItemContent [routerLink]=\"folder.route\">{{ folder.name }}</a>\n  <span slListItemActions>\n    <button slButton variant=\"ghost\" (click)=\"remove(folder)\">Remove</button>\n  </span>\n</li>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "reflow",
+      "title": "The row answers its own width",
+      "note": "Below 22rem the metadata sits under the title and the independent targets take a line of their own, because a target never shrinks and the box beside it would shrink instead. The container is the row and not the set.",
+      "language": "css",
+      "source": "@container slotted-list-item (max-inline-size: 22rem) {\n  /* the metadata moves under the title */\n}\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the family did not choose",
+      "note": "An unbroken token breaks inside the row; a translated title gives way and the timestamp does not; a title in another script keeps its own direction and leaves the row around it alone.",
+      "language": "html",
+      "source": "<li slListItem truncate>\n  <div slListItemContent>\n    <span slListItemBody>\n      <span slListItemLabel>{{ message.subject }}</span>\n    </span>\n  </div>\n</li>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "The families beside it",
+      "note": "slCheckbox announces the selection the row paints, slBadge carries the count, slButton is the independent target. The row draws none of the three.",
+      "language": "html",
+      "source": "<li slListItem selected>\n  <div slListItemContent>\n    <span slListItemStart>\n      <span slCheckbox [checked]=\"true\" aria-label=\"Select\"></span>\n    </span>\n    <span slListItemBody>\n      <span slListItemLabel>Quarterly report</span>\n    </span>\n    <span slListItemEnd><span slBadge tone=\"accent\">3</span></span>\n  </div>\n</li>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "What the platform already does",
+      "note": "The family binds no key. A disabled button leaves the tab sequence, while a disabled link stays in it and refuses the activation — which is what keeps its description reachable to a reader.",
+      "language": "html",
+      "source": "<li slListItem disabled>\n  <a slListItemContent href=\"/exports\">\n    <span slListItemBody>\n      <span slListItemLabel>Exports</span>\n      <span slListItemDescription>Unavailable while the index rebuilds</span>\n    </span>\n  </a>\n</li>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}