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

package/docs/avatar.json

@@ -0,0 +1,342 @@
+{
+  "family": "avatar",
+  "ui": "avatar",
+  "binding": "angular",
+  "catalog": {
+    "group": "Data display",
+    "summary": "Image or initials that stand for a person."
+  },
+  "axes": {
+    "size": [
+      "xs",
+      "sm",
+      "md",
+      "lg",
+      "xl"
+    ],
+    "shape": [
+      "circle",
+      "square"
+    ],
+    "tone": [
+      "auto",
+      "accent",
+      "secondary",
+      "success",
+      "warning",
+      "danger"
+    ],
+    "variant": [
+      "soft",
+      "solid"
+    ],
+    "status": [
+      "idle",
+      "loading",
+      "loaded",
+      "error"
+    ]
+  },
+  "members": {
+    "avatar": {
+      "nativeElement": "span",
+      "defaults": {
+        "size": "md",
+        "shape": "circle",
+        "tone": "auto",
+        "variant": "soft",
+        "decorative": false,
+        "disabled": false
+      },
+      "capabilities": [
+        "appearance",
+        "size",
+        "shape",
+        "status",
+        "disabled",
+        "decorative"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "focus-visible",
+        "disabled"
+      ],
+      "parts": [
+        "root",
+        "image",
+        "fallback"
+      ]
+    }
+  },
+  "docs": {
+    "avatar": {
+      "imports": null,
+      "anatomy": [],
+      "api": [
+        {
+          "name": "name",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slAvatar",
+          "description": "The person or entity. It is the accessible name in every status, the source of the initials, and the seed of the colour"
+        },
+        {
+          "name": "src",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slAvatar",
+          "description": "The picture the component renders itself. Project an img slAvatarImage instead when the element must be yours"
+        },
+        {
+          "name": "initials",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slAvatar",
+          "description": "The letters to draw, in place of the ones derived from the name"
+        },
+        {
+          "name": "tone",
+          "type": "'auto' | 'accent' | 'secondary' | 'success' | 'warning' | 'danger'",
+          "defaultValue": "auto",
+          "appliesTo": "slAvatar",
+          "description": "Which of the five semantic colours the fallback is painted in. auto derives it from the name"
+        },
+        {
+          "name": "idFor",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slAvatar",
+          "description": "A stable identifier to derive the colour from, when the name is not stable or two people share one"
+        },
+        {
+          "name": "variant",
+          "type": "'soft' | 'solid'",
+          "defaultValue": "soft",
+          "appliesTo": "slAvatar",
+          "description": "How that colour is painted: tinted, or filled"
+        },
+        {
+          "name": "size",
+          "type": "'xs' | 'sm' | 'md' | 'lg' | 'xl'",
+          "defaultValue": "md",
+          "appliesTo": "slAvatar",
+          "description": "Five steps, each of which answers density. --slotted-avatar-size states a size no step holds"
+        },
+        {
+          "name": "shape",
+          "type": "'circle' | 'square'",
+          "defaultValue": "circle",
+          "appliesTo": "slAvatar",
+          "description": "A circle is a person; a square is a team, an organisation or a bot"
+        },
+        {
+          "name": "status",
+          "type": "'idle' | 'loading' | 'loaded' | 'error'",
+          "defaultValue": "—",
+          "appliesTo": "slAvatar",
+          "description": "Where the picture is. Supplied, it wins over what the component derives from the element"
+        },
+        {
+          "name": "statusChange",
+          "type": "output<AvatarStatus>",
+          "defaultValue": "—",
+          "appliesTo": "slAvatar",
+          "description": "Reports the derived status. Never emits for a status passed in"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slAvatar",
+          "description": "A deactivated account, or an avatar inside a control the page has turned off"
+        },
+        {
+          "name": "decorative",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slAvatar",
+          "description": "Takes the avatar out of the accessibility tree, for one beside the name it belongs to"
+        },
+        {
+          "name": "locale",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slAvatar",
+          "description": "BCP 47, for the case of the initials. Falls back to the injected defaults, then to the runtime"
+        },
+        {
+          "name": "slAvatarImage",
+          "type": "directive",
+          "defaultValue": "—",
+          "appliesTo": "img",
+          "description": "The consumer’s own img, so ngSrc and NgOptimizedImage reach it. Reports its own load and error"
+        },
+        {
+          "name": "slAvatarFallback",
+          "type": "directive",
+          "defaultValue": "—",
+          "appliesTo": "projected content",
+          "description": "Content that stands in for the picture, in place of the initials and the glyph"
+        },
+        {
+          "name": "provideAvatarDefaults",
+          "type": "{ size, shape, tone, variant, locale }",
+          "defaultValue": "—",
+          "appliesTo": "an injector",
+          "description": "Sets the defaults once for every avatar under it; an explicit input still wins"
+        },
+        {
+          "name": "exportAs",
+          "type": "'slAvatar'",
+          "defaultValue": "—",
+          "appliesTo": "slAvatar",
+          "description": "Reaches the component instance from the template"
+        }
+      ],
+      "composition": [],
+      "events": [],
+      "accessibility": [
+        "There is no avatar pattern in the WAI-ARIA Authoring Practices — the pattern index carries no entry, and the string does not occur on the page. The applicable guidance is the platform’s own: the img element and the img role in WAI-ARIA 1.2, the W3C WAI alt decision tree, and WCAG 2.2 1.1.1 Non-text Content, 1.4.11 Non-text Contrast and 2.5.8 Target Size (Minimum).",
+        "The name is on the root, as aria-label with role=\"img\", and the picture takes an empty alt. The avatar therefore announces the same thing in all four statuses. An alt the consumer wrote on a projected img is read with HostAttributeToken and kept.",
+        "An avatar with no name is aria-hidden, which is the rule Icon already takes. decorative is the third case — a name written beside the avatar, where announcing it would read the person twice.",
+        "A role the consumer wrote on the host element is read before the host binding writes one, so an avatar that is also a menu trigger keeps the role its page chose.",
+        "The colour derived from a name is an aid to scanning a list, never the identifier: five tones mean collisions are certain, and colour alone is not a signal.",
+        "The component is written on the element the page chose, so an a or a button is an avatar with the platform’s own keyboard behaviour. The family paints the focus ring and the hover edge only on an element the browser treats as interactive, and holds both back when it is disabled.",
+        "An interactive avatar smaller than 24 by 24 CSS pixels grows a centred overlay to --slotted-target-min, so WCAG 2.2 2.5.8 is met at the two tighter densities without changing any layout.",
+        "The fallback glyph is the person slGlyph in an aria-hidden slIcon, not a character. Under forced colours the family draws its edge in currentColor and leaves the photograph alone.",
+        "The picture crosses over the initials on --slotted-duration-short, which prefers-reduced-motion collapses to 1ms in the theme. Nothing here loops."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-avatar-border-width",
+    "--slotted-avatar-disabled-image-filter",
+    "--slotted-avatar-elevation",
+    "--slotted-avatar-font-family",
+    "--slotted-avatar-font-weight",
+    "--slotted-avatar-glyph-size",
+    "--slotted-avatar-initials-size",
+    "--slotted-avatar-radius",
+    "--slotted-avatar-ring-color",
+    "--slotted-avatar-ring-width",
+    "--slotted-avatar-size",
+    "--slotted-avatar-size-lg",
+    "--slotted-avatar-size-md",
+    "--slotted-avatar-size-sm",
+    "--slotted-avatar-size-xl",
+    "--slotted-avatar-size-xs",
+    "--slotted-avatar-state-layer-active",
+    "--slotted-avatar-state-layer-hover",
+    "--slotted-border-strong",
+    "--slotted-border-subtle",
+    "--slotted-border-width-thick",
+    "--slotted-border-width-thin",
+    "--slotted-control-font-family",
+    "--slotted-disabled-background",
+    "--slotted-disabled-border",
+    "--slotted-disabled-foreground",
+    "--slotted-duration-short",
+    "--slotted-easing-enter",
+    "--slotted-easing-exit",
+    "--slotted-easing-standard",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width",
+    "--slotted-font-weight-medium",
+    "--slotted-radius-full",
+    "--slotted-surface",
+    "--slotted-target-min",
+    "--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": "avatar-angular-name",
+      "title": "A name is enough",
+      "note": null,
+      "language": "html",
+      "source": "<span slAvatar name=\"Ada Lovelace\"></span>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "avatar-angular-picture",
+      "title": "A picture, and the initials until it arrives",
+      "note": null,
+      "language": "html",
+      "source": "<span slAvatar [name]=\"person.name\" [src]=\"person.photograph\"></span>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "avatar-angular-optimized-image",
+      "title": "The consumer’s own img, so NgOptimizedImage can reach it",
+      "note": null,
+      "language": "html",
+      "source": "<span slAvatar [name]=\"person.name\">\n  <img slAvatarImage [ngSrc]=\"person.photograph\" width=\"64\" height=\"64\" />\n</span>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "avatar-angular-decorative",
+      "title": "Beside the name it belongs to",
+      "note": null,
+      "language": "html",
+      "source": "<div slInline align=\"center\" [gap]=\"3\">\n  <span slAvatar decorative [name]=\"person.name\" [src]=\"person.photograph\"></span>\n  <div slStack [gap]=\"1\">\n    <span slText weight=\"medium\">{{ person.name }}</span>\n    <span slText tone=\"muted\">{{ person.role }}</span>\n  </div>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "avatar-angular-presence",
+      "title": "Presence, composed with Badge",
+      "note": null,
+      "language": "html",
+      "source": "<span slBadgeAnchor overlap=\"circle\" placement=\"bottom-end\">\n  <span slAvatar [name]=\"person.name\" [src]=\"person.photograph\"></span>\n  <span slBadge shape=\"dot\" size=\"sm\" tone=\"success\" variant=\"solid\">\n    <span slVisuallyHidden>Online</span>\n  </span>\n</span>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "avatar-angular-link",
+      "title": "An avatar that opens a profile",
+      "note": null,
+      "language": "html",
+      "source": "<a\n  slAvatar\n  [name]=\"person.name\"\n  [src]=\"person.photograph\"\n  [routerLink]=\"['/people', person.id]\"\n></a>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "avatar-angular-organisation",
+      "title": "A square avatar, and a mark of its own",
+      "note": null,
+      "language": "html",
+      "source": "<span slAvatar name=\"Acme Inc\" shape=\"square\" tone=\"accent\" variant=\"solid\">\n  <span slIcon slAvatarFallback>\n    <svg viewBox=\"0 0 24 24\"><path d=\"M4 20 12 4l8 16Z\" /></svg>\n  </span>\n</span>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "avatar-angular-defaults",
+      "title": "One decision for every avatar in the application",
+      "note": null,
+      "language": "ts",
+      "source": "bootstrapApplication(App, {\n  providers: [provideAvatarDefaults({ locale: 'pt-BR', size: 'sm' })],\n});\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/docs/avatar.md

@@ -0,0 +1,142 @@
+<!-- index: ./index.md -->
+# avatar
+
+`data-ui="avatar"` · Image or initials that stand for a person.
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<span slAvatar name="Ada Lovelace"></span>
+```
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `string` | — | slAvatar | The person or entity. It is the accessible name in every status, the source of the initials, and the seed of the colour |
+| `src` | `string` | — | slAvatar | The picture the component renders itself. Project an img slAvatarImage instead when the element must be yours |
+| `initials` | `string` | — | slAvatar | The letters to draw, in place of the ones derived from the name |
+| `tone` | `'auto' \| 'accent' \| 'secondary' \| 'success' \| 'warning' \| 'danger'` | auto | slAvatar | Which of the five semantic colours the fallback is painted in. auto derives it from the name |
+| `idFor` | `string` | — | slAvatar | A stable identifier to derive the colour from, when the name is not stable or two people share one |
+| `variant` | `'soft' \| 'solid'` | soft | slAvatar | How that colour is painted: tinted, or filled |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | md | slAvatar | Five steps, each of which answers density. --slotted-avatar-size states a size no step holds |
+| `shape` | `'circle' \| 'square'` | circle | slAvatar | A circle is a person; a square is a team, an organisation or a bot |
+| `status` | `'idle' \| 'loading' \| 'loaded' \| 'error'` | — | slAvatar | Where the picture is. Supplied, it wins over what the component derives from the element |
+| `statusChange` | `output<AvatarStatus>` | — | slAvatar | Reports the derived status. Never emits for a status passed in |
+| `disabled` | `boolean` | false | slAvatar | A deactivated account, or an avatar inside a control the page has turned off |
+| `decorative` | `boolean` | false | slAvatar | Takes the avatar out of the accessibility tree, for one beside the name it belongs to |
+| `locale` | `string` | — | slAvatar | BCP 47, for the case of the initials. Falls back to the injected defaults, then to the runtime |
+| `slAvatarImage` | `directive` | — | img | The consumer’s own img, so ngSrc and NgOptimizedImage reach it. Reports its own load and error |
+| `slAvatarFallback` | `directive` | — | projected content | Content that stands in for the picture, in place of the initials and the glyph |
+| `provideAvatarDefaults` | `{ size, shape, tone, variant, locale }` | — | an injector | Sets the defaults once for every avatar under it; an explicit input still wins |
+| `exportAs` | `'slAvatar'` | — | slAvatar | Reaches the component instance from the template |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `xs`, `sm`, `md`, `lg`, `xl` | `md` |
+| `shape` | `circle`, `square` | `circle` |
+| `tone` | `auto`, `accent`, `secondary`, `success`, `warning`, `danger` | `auto` |
+| `variant` | `soft`, `solid` | `soft` |
+| `status` | `idle`, `loading`, `loaded`, `error` | — |
+
+## Rules
+
+- There is no avatar pattern in the WAI-ARIA Authoring Practices — the pattern index carries no entry, and the string does not occur on the page. The applicable guidance is the platform’s own: the img element and the img role in WAI-ARIA 1.2, the W3C WAI alt decision tree, and WCAG 2.2 1.1.1 Non-text Content, 1.4.11 Non-text Contrast and 2.5.8 Target Size (Minimum).
+- The name is on the root, as aria-label with role="img", and the picture takes an empty alt. The avatar therefore announces the same thing in all four statuses. An alt the consumer wrote on a projected img is read with HostAttributeToken and kept.
+- An avatar with no name is aria-hidden, which is the rule Icon already takes. decorative is the third case — a name written beside the avatar, where announcing it would read the person twice.
+- A role the consumer wrote on the host element is read before the host binding writes one, so an avatar that is also a menu trigger keeps the role its page chose.
+- The colour derived from a name is an aid to scanning a list, never the identifier: five tones mean collisions are certain, and colour alone is not a signal.
+- The component is written on the element the page chose, so an a or a button is an avatar with the platform’s own keyboard behaviour. The family paints the focus ring and the hover edge only on an element the browser treats as interactive, and holds both back when it is disabled.
+- An interactive avatar smaller than 24 by 24 CSS pixels grows a centred overlay to --slotted-target-min, so WCAG 2.2 2.5.8 is met at the two tighter densities without changing any layout.
+- The fallback glyph is the person slGlyph in an aria-hidden slIcon, not a character. Under forced colours the family draws its edge in currentColor and leaves the photograph alone.
+- The picture crosses over the initials on --slotted-duration-short, which prefers-reduced-motion collapses to 1ms in the theme. Nothing here loops.
+
+## Tokens
+
+`--slotted-avatar-border-width`, `--slotted-avatar-disabled-image-filter`, `--slotted-avatar-elevation`, `--slotted-avatar-font-family`, `--slotted-avatar-font-weight`, `--slotted-avatar-glyph-size`, `--slotted-avatar-initials-size`, `--slotted-avatar-radius`, `--slotted-avatar-ring-color`, `--slotted-avatar-ring-width`, `--slotted-avatar-size`, `--slotted-avatar-size-lg`, `--slotted-avatar-size-md`, `--slotted-avatar-size-sm`, `--slotted-avatar-size-xl`, `--slotted-avatar-size-xs`, `--slotted-avatar-state-layer-active`, `--slotted-avatar-state-layer-hover`, `--slotted-border-strong`, `--slotted-border-subtle`, `--slotted-border-width-thick`, `--slotted-border-width-thin`, `--slotted-control-font-family`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-duration-short`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-weight-medium`, `--slotted-radius-full`, `--slotted-surface`, `--slotted-target-min`, `--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 picture, and the initials until it arrives
+
+Excerpt — not a complete module
+
+```html
+<span slAvatar [name]="person.name" [src]="person.photograph"></span>
+```
+
+### The consumer’s own img, so NgOptimizedImage can reach it
+
+Excerpt — not a complete module
+
+```html
+<span slAvatar [name]="person.name">
+  <img slAvatarImage [ngSrc]="person.photograph" width="64" height="64" />
+</span>
+```
+
+### Beside the name it belongs to
+
+Excerpt — not a complete module
+
+```html
+<div slInline align="center" [gap]="3">
+  <span slAvatar decorative [name]="person.name" [src]="person.photograph"></span>
+  <div slStack [gap]="1">
+    <span slText weight="medium">{{ person.name }}</span>
+    <span slText tone="muted">{{ person.role }}</span>
+  </div>
+</div>
+```
+
+### Presence, composed with Badge
+
+Excerpt — not a complete module
+
+```html
+<span slBadgeAnchor overlap="circle" placement="bottom-end">
+  <span slAvatar [name]="person.name" [src]="person.photograph"></span>
+  <span slBadge shape="dot" size="sm" tone="success" variant="solid">
+    <span slVisuallyHidden>Online</span>
+  </span>
+</span>
+```
+
+### An avatar that opens a profile
+
+Excerpt — not a complete module
+
+```html
+<a
+  slAvatar
+  [name]="person.name"
+  [src]="person.photograph"
+  [routerLink]="['/people', person.id]"
+></a>
+```
+
+### A square avatar, and a mark of its own
+
+Excerpt — not a complete module
+
+```html
+<span slAvatar name="Acme Inc" shape="square" tone="accent" variant="solid">
+  <span slIcon slAvatarFallback>
+    <svg viewBox="0 0 24 24"><path d="M4 20 12 4l8 16Z" /></svg>
+  </span>
+</span>
+```
+
+### One decision for every avatar in the application
+
+Excerpt — not a complete module
+
+```ts
+bootstrapApplication(App, {
+  providers: [provideAvatarDefaults({ locale: 'pt-BR', size: 'sm' })],
+});
+```