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

package/docs/badge.json

@@ -0,0 +1,334 @@
+{
+  "family": "badge",
+  "ui": "badge",
+  "binding": "angular",
+  "catalog": {
+    "group": "Data display",
+    "summary": "Short label or count attached to an element."
+  },
+  "axes": {
+    "tone": [
+      "accent",
+      "secondary",
+      "success",
+      "warning",
+      "danger"
+    ],
+    "variant": [
+      "solid",
+      "soft",
+      "outline"
+    ],
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "shape": [
+      "pill",
+      "square",
+      "dot"
+    ],
+    "live": [
+      "off",
+      "polite",
+      "assertive"
+    ],
+    "placement": [
+      "top-end",
+      "top-start",
+      "bottom-end",
+      "bottom-start"
+    ],
+    "overlap": [
+      "rectangle",
+      "circle"
+    ]
+  },
+  "members": {
+    "badge": {
+      "nativeElement": "span",
+      "defaults": {
+        "tone": "secondary",
+        "variant": "soft",
+        "size": "md",
+        "shape": "pill",
+        "live": "off",
+        "placement": "top-end",
+        "overlap": "rectangle",
+        "offset": "{ x: 0, y: 0 }",
+        "max": 99,
+        "showZero": false
+      },
+      "capabilities": [
+        "appearance",
+        "size",
+        "shape",
+        "content",
+        "live",
+        "placement"
+      ],
+      "states": [
+        "default",
+        "focus-visible"
+      ],
+      "parts": [
+        "root",
+        "start",
+        "label",
+        "end",
+        "anchor"
+      ]
+    }
+  },
+  "docs": {
+    "badge": {
+      "imports": null,
+      "anatomy": [],
+      "api": [
+        {
+          "name": "tone",
+          "type": "'accent' | 'secondary' | 'success' | 'warning' | 'danger'",
+          "defaultValue": "secondary",
+          "appliesTo": "slBadge",
+          "description": "Which of the five semantic colours the badge speaks in"
+        },
+        {
+          "name": "variant",
+          "type": "'solid' | 'soft' | 'outline'",
+          "defaultValue": "soft",
+          "appliesTo": "slBadge",
+          "description": "How that colour is painted: filled, tinted, or an edge alone. All three draw the same tone edge"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "slBadge",
+          "description": "Type and glyph come from the control scale, so a badge shrinks with density beside the controls it sits with"
+        },
+        {
+          "name": "shape",
+          "type": "'pill' | 'square' | 'dot'",
+          "defaultValue": "pill",
+          "appliesTo": "slBadge",
+          "description": "A dot is the same badge, tone and hidden text, drawn without a value"
+        },
+        {
+          "name": "count",
+          "type": "number",
+          "defaultValue": "—",
+          "appliesTo": "slBadge",
+          "description": "The number the badge shows, written before any projected content and formatted for the locale"
+        },
+        {
+          "name": "max",
+          "type": "number | false",
+          "defaultValue": "99",
+          "appliesTo": "slBadge",
+          "description": "The largest count written in full; above it the badge shows the ceiling and a plus. false removes the ceiling"
+        },
+        {
+          "name": "showZero",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slBadge",
+          "description": "Whether a count of nought is a value worth showing or an absence that takes the badge out of the page"
+        },
+        {
+          "name": "locale",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slBadge",
+          "description": "BCP 47, for the digits of count. Falls back to the injected default, then to the runtime"
+        },
+        {
+          "name": "start",
+          "type": "slBadgeStart",
+          "defaultValue": "—",
+          "appliesTo": "a projected element",
+          "description": "A glyph before the words; the directive gives the consumer’s own element the start part"
+        },
+        {
+          "name": "end",
+          "type": "slBadgeEnd",
+          "defaultValue": "—",
+          "appliesTo": "a projected element",
+          "description": "A glyph after the words"
+        },
+        {
+          "name": "live",
+          "type": "'off' | 'polite' | 'assertive'",
+          "defaultValue": "off",
+          "appliesTo": "slBadge",
+          "description": "Whether a change to this badge is announced, and how urgently"
+        },
+        {
+          "name": "placement",
+          "type": "'top-end' | 'top-start' | 'bottom-end' | 'bottom-start'",
+          "defaultValue": "top-end",
+          "appliesTo": "slBadgeAnchor",
+          "description": "Which corner of the host the badge sits on. Mirrors in a right-to-left document"
+        },
+        {
+          "name": "overlap",
+          "type": "'rectangle' | 'circle'",
+          "defaultValue": "rectangle",
+          "appliesTo": "slBadgeAnchor",
+          "description": "The host's shape, which decides how far in from the corner the badge starts"
+        },
+        {
+          "name": "offset",
+          "type": "{ x?: number; y?: number }",
+          "defaultValue": "{ x: 0, y: 0 }",
+          "appliesTo": "slBadgeAnchor",
+          "description": "Moves the badge off the computed corner, in pixels. x runs along the inline axis and mirrors with the document"
+        },
+        {
+          "name": "exportAs",
+          "type": "slBadge | slBadgeStart | slBadgeEnd | slBadgeAnchor",
+          "defaultValue": "—",
+          "appliesTo": "every directive",
+          "description": "Reaches the instance from the template"
+        },
+        {
+          "name": "provideBadgeDefaults",
+          "type": "{ tone, variant, size, shape, max, locale }",
+          "defaultValue": "—",
+          "appliesTo": "an injector",
+          "description": "Sets the defaults once for every badge under it; an explicit input still wins"
+        }
+      ],
+      "composition": [],
+      "events": [],
+      "accessibility": [
+        "There is no badge pattern in the WAI-ARIA Authoring Practices — the pattern index carries no entry — and there is no badge role. The applicable guidance is the status role in WAI-ARIA 1.2, and WCAG 2.2 1.4.1 Use of Color, 1.4.11 Non-text Contrast and 4.1.3 Status Messages.",
+        "The directive adds no role. It is written on the element the page chose — a span in a sentence, a dd in a description list, an a that navigates — and what a badge means comes from where it sits.",
+        "live is the announcement policy for a badge whose value changes: polite writes role=\"status\", assertive writes role=\"alert\". A role the consumer wrote on the host is read with HostAttributeToken first and never replaced.",
+        "A dot says nothing a screen reader can read. Project the words beside it — a span slVisuallyHidden inside the badge — because colour alone is not a signal. Inside a badge that element is out of flow, so it costs no space.",
+        "The dot is the only badge whose whole meaning is a graphic, so its rim is --slotted-border-strong: the one border token the theme holds to 3:1 against the surface.",
+        "slBadgeAnchor is written on the element already around the host and does not rewrite the host. The badge is read after it in document order. When the host is interactive and its name must carry the count, wire aria-describedby from the host to the badge’s id, or name the count in the host’s aria-label.",
+        "A badge is not focusable and is never a command: it answers no hover and gives no press feedback. Written on an anchor it is focusable, and the family paints the ring for exactly that case.",
+        "A count of nought takes the badge out of the page with display: none — no box, no layout, nothing in the accessibility tree. React returns nothing instead; a directive written on an element the consumer owns cannot un-write it.",
+        "A badge is one line. A string too long for its container is clipped with an ellipsis rather than reflowed, and the clipping is visual only: text-overflow shortens nothing, so the whole value stays in the DOM, stays in the accessibility tree, and a page search still finds it. A value that routinely needs more room is a Tag, not a Badge.",
+        "The count is formatted with Intl.NumberFormat, so a total reads 1.234 in de-DE and ١٬٢٣٤ in ar-EG. Provide locale through provideBadgeDefaults when the application server-renders counts above its grouping threshold."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-badge-anchor-offset-x",
+    "--slotted-badge-anchor-offset-y",
+    "--slotted-badge-border-width",
+    "--slotted-badge-dot-border-color",
+    "--slotted-badge-font-family",
+    "--slotted-badge-font-weight",
+    "--slotted-badge-radius",
+    "--slotted-badge-ring-color",
+    "--slotted-badge-ring-width",
+    "--slotted-border-strong",
+    "--slotted-border-width-thick",
+    "--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-icon-size-md",
+    "--slotted-control-icon-size-sm",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width",
+    "--slotted-font-weight-medium",
+    "--slotted-line-height-xs",
+    "--slotted-radius-full",
+    "--slotted-radius-sm",
+    "--slotted-space-1",
+    "--slotted-space-2",
+    "--slotted-space-3",
+    "--slotted-space-4",
+    "--slotted-space-5",
+    "--slotted-surface",
+    "--slotted-tone-accent-border",
+    "--slotted-tone-accent-on-solid",
+    "--slotted-tone-accent-solid",
+    "--slotted-tone-accent-surface",
+    "--slotted-tone-accent-text",
+    "--slotted-tone-danger-border",
+    "--slotted-tone-danger-on-solid",
+    "--slotted-tone-danger-solid",
+    "--slotted-tone-danger-surface",
+    "--slotted-tone-danger-text",
+    "--slotted-tone-secondary-border",
+    "--slotted-tone-secondary-on-solid",
+    "--slotted-tone-secondary-solid-hover",
+    "--slotted-tone-secondary-surface",
+    "--slotted-tone-secondary-text",
+    "--slotted-tone-success-border",
+    "--slotted-tone-success-on-solid",
+    "--slotted-tone-success-solid",
+    "--slotted-tone-success-surface",
+    "--slotted-tone-success-text",
+    "--slotted-tone-warning-border",
+    "--slotted-tone-warning-on-solid",
+    "--slotted-tone-warning-solid",
+    "--slotted-tone-warning-surface",
+    "--slotted-tone-warning-text"
+  ],
+  "examples": [
+    {
+      "id": "badge-angular-status",
+      "title": "A status beside the thing it describes",
+      "note": null,
+      "language": "html",
+      "source": "<h3 slHeading [level]=\"3\">Invoice #4821 <span slBadge tone=\"warning\">Pending</span></h3>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "badge-angular-count",
+      "title": "A count on the corner of a control",
+      "note": null,
+      "language": "html",
+      "source": "<span slBadgeAnchor>\n  <button slIconButton type=\"button\" aria-label=\"Notifications\">\n    <ng-icon name=\"bell\" />\n  </button>\n  <span slBadge tone=\"danger\" variant=\"solid\" size=\"sm\" live=\"polite\" [count]=\"unread()\">\n    <span slVisuallyHidden>unread notifications</span>\n  </span>\n</span>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "badge-angular-described",
+      "title": "The count inside the host’s own description",
+      "note": null,
+      "language": "html",
+      "source": "<span slBadgeAnchor>\n  <button type=\"button\" aria-describedby=\"inbox-count\">Inbox</button>\n  <span id=\"inbox-count\" slBadge size=\"sm\" tone=\"danger\" variant=\"solid\" [count]=\"4\">\n    <span slVisuallyHidden>unread messages</span>\n  </span>\n</span>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "badge-angular-dot",
+      "title": "A dot, and the words it cannot say",
+      "note": null,
+      "language": "html",
+      "source": "<div slInline align=\"center\" [gap]=\"3\">\n  <span slBadge shape=\"dot\" tone=\"success\" variant=\"solid\">\n    <span slVisuallyHidden>Online</span>\n  </span>\n  <span slText>Deployed</span>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "badge-angular-presence",
+      "title": "Presence on a round host",
+      "note": null,
+      "language": "html",
+      "source": "<span slBadgeAnchor placement=\"bottom-end\" overlap=\"circle\">\n  <img class=\"avatar\" alt=\"\" [src]=\"member.photo\" />\n  <span slBadge shape=\"dot\" size=\"sm\" tone=\"success\" variant=\"solid\">\n    <span slVisuallyHidden>Online</span>\n  </span>\n</span>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "badge-angular-link",
+      "title": "A badge that navigates",
+      "note": null,
+      "language": "html",
+      "source": "<a slBadge tone=\"accent\" variant=\"outline\" href=\"/releases/4.2.0\">v4.2.0</a>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "badge-angular-defaults",
+      "title": "One decision for every badge in the application",
+      "note": null,
+      "language": "ts",
+      "source": "import { provideBadgeDefaults } from '@slotted/angular/badge';\n\nbootstrapApplication(App, {\n  providers: [provideBadgeDefaults({ locale: 'pt-BR', max: 999, size: 'sm' })],\n});\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/docs/badge.md

@@ -0,0 +1,138 @@
+<!-- index: ./index.md -->
+# badge
+
+`data-ui="badge"` · Short label or count attached to an element.
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<h3 slHeading [level]="3">Invoice #4821 <span slBadge tone="warning">Pending</span></h3>
+```
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `tone` | `'accent' \| 'secondary' \| 'success' \| 'warning' \| 'danger'` | secondary | slBadge | Which of the five semantic colours the badge speaks in |
+| `variant` | `'solid' \| 'soft' \| 'outline'` | soft | slBadge | How that colour is painted: filled, tinted, or an edge alone. All three draw the same tone edge |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | slBadge | Type and glyph come from the control scale, so a badge shrinks with density beside the controls it sits with |
+| `shape` | `'pill' \| 'square' \| 'dot'` | pill | slBadge | A dot is the same badge, tone and hidden text, drawn without a value |
+| `count` | `number` | — | slBadge | The number the badge shows, written before any projected content and formatted for the locale |
+| `max` | `number \| false` | 99 | slBadge | The largest count written in full; above it the badge shows the ceiling and a plus. false removes the ceiling |
+| `showZero` | `boolean` | false | slBadge | Whether a count of nought is a value worth showing or an absence that takes the badge out of the page |
+| `locale` | `string` | — | slBadge | BCP 47, for the digits of count. Falls back to the injected default, then to the runtime |
+| `start` | `slBadgeStart` | — | a projected element | A glyph before the words; the directive gives the consumer’s own element the start part |
+| `end` | `slBadgeEnd` | — | a projected element | A glyph after the words |
+| `live` | `'off' \| 'polite' \| 'assertive'` | off | slBadge | Whether a change to this badge is announced, and how urgently |
+| `placement` | `'top-end' \| 'top-start' \| 'bottom-end' \| 'bottom-start'` | top-end | slBadgeAnchor | Which corner of the host the badge sits on. Mirrors in a right-to-left document |
+| `overlap` | `'rectangle' \| 'circle'` | rectangle | slBadgeAnchor | The host's shape, which decides how far in from the corner the badge starts |
+| `offset` | `{ x?: number; y?: number }` | { x: 0, y: 0 } | slBadgeAnchor | Moves the badge off the computed corner, in pixels. x runs along the inline axis and mirrors with the document |
+| `exportAs` | `slBadge \| slBadgeStart \| slBadgeEnd \| slBadgeAnchor` | — | every directive | Reaches the instance from the template |
+| `provideBadgeDefaults` | `{ tone, variant, size, shape, max, locale }` | — | an injector | Sets the defaults once for every badge under it; an explicit input still wins |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `tone` | `accent`, `secondary`, `success`, `warning`, `danger` | `secondary` |
+| `variant` | `solid`, `soft`, `outline` | `soft` |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `shape` | `pill`, `square`, `dot` | `pill` |
+| `live` | `off`, `polite`, `assertive` | `off` |
+| `placement` | `top-end`, `top-start`, `bottom-end`, `bottom-start` | `top-end` |
+| `overlap` | `rectangle`, `circle` | `rectangle` |
+
+## Rules
+
+- There is no badge pattern in the WAI-ARIA Authoring Practices — the pattern index carries no entry — and there is no badge role. The applicable guidance is the status role in WAI-ARIA 1.2, and WCAG 2.2 1.4.1 Use of Color, 1.4.11 Non-text Contrast and 4.1.3 Status Messages.
+- The directive adds no role. It is written on the element the page chose — a span in a sentence, a dd in a description list, an a that navigates — and what a badge means comes from where it sits.
+- live is the announcement policy for a badge whose value changes: polite writes role="status", assertive writes role="alert". A role the consumer wrote on the host is read with HostAttributeToken first and never replaced.
+- A dot says nothing a screen reader can read. Project the words beside it — a span slVisuallyHidden inside the badge — because colour alone is not a signal. Inside a badge that element is out of flow, so it costs no space.
+- The dot is the only badge whose whole meaning is a graphic, so its rim is --slotted-border-strong: the one border token the theme holds to 3:1 against the surface.
+- slBadgeAnchor is written on the element already around the host and does not rewrite the host. The badge is read after it in document order. When the host is interactive and its name must carry the count, wire aria-describedby from the host to the badge’s id, or name the count in the host’s aria-label.
+- A badge is not focusable and is never a command: it answers no hover and gives no press feedback. Written on an anchor it is focusable, and the family paints the ring for exactly that case.
+- A count of nought takes the badge out of the page with display: none — no box, no layout, nothing in the accessibility tree. React returns nothing instead; a directive written on an element the consumer owns cannot un-write it.
+- A badge is one line. A string too long for its container is clipped with an ellipsis rather than reflowed, and the clipping is visual only: text-overflow shortens nothing, so the whole value stays in the DOM, stays in the accessibility tree, and a page search still finds it. A value that routinely needs more room is a Tag, not a Badge.
+- The count is formatted with Intl.NumberFormat, so a total reads 1.234 in de-DE and ١٬٢٣٤ in ar-EG. Provide locale through provideBadgeDefaults when the application server-renders counts above its grouping threshold.
+
+## Tokens
+
+`--slotted-badge-anchor-offset-x`, `--slotted-badge-anchor-offset-y`, `--slotted-badge-border-width`, `--slotted-badge-dot-border-color`, `--slotted-badge-font-family`, `--slotted-badge-font-weight`, `--slotted-badge-radius`, `--slotted-badge-ring-color`, `--slotted-badge-ring-width`, `--slotted-border-strong`, `--slotted-border-width-thick`, `--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-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-weight-medium`, `--slotted-line-height-xs`, `--slotted-radius-full`, `--slotted-radius-sm`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-surface`, `--slotted-tone-accent-border`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-danger-on-solid`, `--slotted-tone-danger-solid`, `--slotted-tone-danger-surface`, `--slotted-tone-danger-text`, `--slotted-tone-secondary-border`, `--slotted-tone-secondary-on-solid`, `--slotted-tone-secondary-solid-hover`, `--slotted-tone-secondary-surface`, `--slotted-tone-secondary-text`, `--slotted-tone-success-border`, `--slotted-tone-success-on-solid`, `--slotted-tone-success-solid`, `--slotted-tone-success-surface`, `--slotted-tone-success-text`, `--slotted-tone-warning-border`, `--slotted-tone-warning-on-solid`, `--slotted-tone-warning-solid`, `--slotted-tone-warning-surface`, `--slotted-tone-warning-text`
+
+## Examples
+
+### A count on the corner of a control
+
+Excerpt — not a complete module
+
+```html
+<span slBadgeAnchor>
+  <button slIconButton type="button" aria-label="Notifications">
+    <ng-icon name="bell" />
+  </button>
+  <span slBadge tone="danger" variant="solid" size="sm" live="polite" [count]="unread()">
+    <span slVisuallyHidden>unread notifications</span>
+  </span>
+</span>
+```
+
+### The count inside the host’s own description
+
+Excerpt — not a complete module
+
+```html
+<span slBadgeAnchor>
+  <button type="button" aria-describedby="inbox-count">Inbox</button>
+  <span id="inbox-count" slBadge size="sm" tone="danger" variant="solid" [count]="4">
+    <span slVisuallyHidden>unread messages</span>
+  </span>
+</span>
+```
+
+### A dot, and the words it cannot say
+
+Excerpt — not a complete module
+
+```html
+<div slInline align="center" [gap]="3">
+  <span slBadge shape="dot" tone="success" variant="solid">
+    <span slVisuallyHidden>Online</span>
+  </span>
+  <span slText>Deployed</span>
+</div>
+```
+
+### Presence on a round host
+
+Excerpt — not a complete module
+
+```html
+<span slBadgeAnchor placement="bottom-end" overlap="circle">
+  <img class="avatar" alt="" [src]="member.photo" />
+  <span slBadge shape="dot" size="sm" tone="success" variant="solid">
+    <span slVisuallyHidden>Online</span>
+  </span>
+</span>
+```
+
+### A badge that navigates
+
+Excerpt — not a complete module
+
+```html
+<a slBadge tone="accent" variant="outline" href="/releases/4.2.0">v4.2.0</a>
+```
+
+### One decision for every badge in the application
+
+Excerpt — not a complete module
+
+```ts
+import { provideBadgeDefaults } from '@slotted/angular/badge';
+
+bootstrapApplication(App, {
+  providers: [provideBadgeDefaults({ locale: 'pt-BR', max: 999, size: 'sm' })],
+});
+```