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

package/docs/hover-card.md

@@ -0,0 +1,213 @@
+<!-- index: ./index.md -->
+# hover-card
+
+`data-ui="hover-card"` · Preview card that opens on hover or focus.
+
+## Import
+
+```ts
+import { SlHoverCard, SlHoverCardTrigger, provideHoverCardDefaults } from '@slotted/angular/hover-card';
+import { SlPopoverLayer, SlPopoverContent, SlPopoverBody } from '@slotted/angular/popover';
+```
+
+Selector: `[slHoverCard], [slHoverCardTrigger]` · exportAs: `slHoverCard`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<ng-container slHoverCard>
+  <a slHoverCardTrigger href="/people/ana">&#64;ana.souza</a>
+  <ng-template slPopoverLayer>
+    <div slPopoverContent>
+      <div slPopoverBody>…</div>
+      <div slPopoverArrow></div>
+    </div>
+  </ng-template>
+</ng-container>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | a[slHoverCardTrigger], the consumer’s own anchor | yes |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `open` | `model<boolean>` | false | slHoverCard | Whether the card shows. Two-way: [(open)] on the container; a bound [open] alone makes the card controlled. |
+| `openDelay` | `number` | 600 | slHoverCard | Milliseconds the pointer rests on the trigger before the card opens. Focus never waits. |
+| `closeDelay` | `number` | 300 | slHoverCard | Milliseconds after the pointer has left trigger and card before it closes; a pointer on its way to the card is not counted as gone. |
+| `navigable` | `boolean` | false | slHoverCard | Whether the card holds controls a keyboard reader can reach. On, the panel is a dialog, the link announces it and Tab enters it; off, the panel is presentation. |
+| `disabled` | `boolean` | false | slHoverCard | The card never opens. The link keeps working, and carries no disabled state. |
+| `sideOffset` | `number` | 4 | slHoverCard | The popover’s own input, with the family’s default: the halo the open mark draws plus the same again of air, so the arrow’s tip stands off the word. |
+| `side, align, size, width, arrow, mount, …` | `SlPopover inputs` | — | slHoverCard | Every input of slPopover except autoFocus, which the family forces off: slHoverCard extends SlPopover and provides itself as one. |
+| `provideHoverCardDefaults()` | `provider` | — | Application | Sets openDelay, closeDelay and navigable once for an injector. A card that states one itself still wins; the panel reads providePopoverDefaults(). |
+| `slPopoverLayer, slPopoverContent, slPopoverBody, slPopoverClose, …` | `directives` | — | Inside slHoverCard | The card is the popover family unchanged, and nothing is re-exported: slHoverCard provides itself as SlPopover, so every popover part inside it reaches the card. The panel’s role follows navigable. |
+| `exportAs` | `template reference` | — | slHoverCard | A template reaches the card — #card="slHoverCard" — for show(), hide() and the resolved delays; the trigger as #mention="slHoverCardTrigger". |
+| `many triggers` | `composition` | — | slHoverCard | Several a[slHoverCardTrigger] inside one container share one card; the one that starts an opening registers itself as the anchor. |
+| `host attributes` | `attributes` | — | slHoverCardTrigger | The trigger is the consumer’s own anchor: href, rel and target are theirs, and a data-part they wrote is kept beside the identity. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `openChangeRequest` | `ChangeRequest<boolean>` | Before the card opens or closes. The request carries pointer (hover in, hover out, a tap), keyboard (focus arriving, a focus guard), escape, outsidePress, blur (focus leaving the trigger), dismiss (the Close part) or programmatic, the originating event, and cancel(). |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `navigable` | `true`, `false` | `false` |
+| `disabled` | `true`, `false` | `false` |
+
+## Rules
+
+- The platform supplies the link: it is a native anchor, so Enter follows it, a middle click opens it in a tab and a screen reader hears a link. The card never takes focus when it opens — autoFocus is forced off on the popover it holds — so the reader’s focus stays on the word under the pointer.
+- The family answers WCAG 2.2 SC 1.4.13 item by item: the card is dismissible with Escape and no pointer movement, hoverable because the pointer may move onto it and the grace area keeps it open on the way, and persistent because it stays until hover and focus have left both link and card.
+- A card the keyboard cannot enter is role="presentation" and the link says nothing about it, because a popup the announced means cannot reach would be a lie a screen reader repeats. A navigable card is the APG’s non-modal dialog, named by its title, with aria-haspopup="dialog", aria-expanded and aria-controls on the link, and Tab from the link enters it.
+- Focus the family itself puts back on the link — after Escape inside the card, after a focus guard — does not reopen the card; the link holds the reopening back until focus has left it once. Without that rule a guard would close the card, focus the link, and open the card again.
+
+## Tokens
+
+`--slotted-border-width-thick`, `--slotted-duration-short`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-highlight-tint-opacity`, `--slotted-hover-card-color`, `--slotted-hover-card-halo`, `--slotted-hover-card-radius`, `--slotted-hover-card-tint`, `--slotted-hover-card-underline-color`, `--slotted-radius-xs`, `--slotted-space-1`, `--slotted-tone-accent-text`
+
+## Examples
+
+### A person
+
+The card a review thread shows for a handle: avatar, name, team and what they own, under the word it is about. While it shows, the word carries a tint and a halo that grow the inline box without moving the line — the sentence under it has not shifted.
+
+Excerpt — not a complete module
+
+```html
+<ng-container slHoverCard [open]="true">
+  <a slHoverCardTrigger href="/people/ana">&#64;ana.souza</a>
+  <ng-template slPopoverLayer>
+    <div slPopoverContent>
+      <div slPopoverBody>
+        <span slAvatar name="Ana Souza"></span>
+        …
+      </div>
+    </div>
+  </ng-template>
+</ng-container>
+```
+
+### A document
+
+The card a link to a spec shows: its title, who touched it last and its first lines. The trigger stays a link — Enter follows it, a middle click opens it in a tab — and the card adds nothing the destination does not have.
+
+Excerpt — not a complete module
+
+```html
+<ng-container slHoverCard>
+  <a slHoverCardTrigger href="/specs/checkout-pricing">Checkout redesign — pricing table</a>
+  <ng-template slPopoverLayer>
+    <div slPopoverContent>
+      <div slPopoverHeader>
+        <div slPopoverTitle>Checkout redesign — pricing table</div>
+        <p slPopoverDescription>Product spec · updated 2 hours ago</p>
+      </div>
+      <div slPopoverBody>…</div>
+    </div>
+  </ng-template>
+</ng-container>
+```
+
+### Navigable
+
+The card holds a control, so the page says so with navigable: the panel becomes a dialog named by its title, the link announces the popup, and Tab from the open link enters the card. Past its last control a focus guard closes it and puts focus back on the link, which does not reopen.
+
+Excerpt — not a complete module
+
+```html
+<ng-container slHoverCard navigable>
+  <a slHoverCardTrigger href="/people/ana">&#64;ana.souza</a>
+  <ng-template slPopoverLayer>
+    <div slPopoverContent>
+      <div slPopoverHeader><div slPopoverTitle>Ana Souza</div></div>
+      <div slPopoverBody>…</div>
+      <div slPopoverFooter><button slButton size="sm">Follow</button></div>
+    </div>
+  </ng-template>
+</ng-container>
+```
+
+### The delays
+
+Two of the same card: the left opens after the default 600 ms and closes 300 ms after the pointer has left; the right answers at once and holds for a second, for a page where the preview is the point. Focus never waits on either.
+
+Excerpt — not a complete module
+
+```html
+<ng-container slHoverCard [openDelay]="0" [closeDelay]="1000">…</ng-container>
+```
+
+### One card, many mentions
+
+A thread with four handles and one slHoverCard around all of them. The mention the pointer rests on registers itself as the anchor, and the request carries the event whose currentTarget names the person, so the card fills from one state instead of mounting four.
+
+Excerpt — not a complete module
+
+```html
+<ng-container slHoverCard (openChangeRequest)="remember($event)">
+  <p>
+    <a slHoverCardTrigger data-handle="ana.souza" href="/people/ana">&#64;ana.souza</a>
+    and
+    <a slHoverCardTrigger data-handle="marcus.lee" href="/people/marcus">&#64;marcus.lee</a>
+  </p>
+  <ng-template slPopoverLayer>
+    <div slPopoverContent>{{ people[handle()] }}</div>
+  </ng-template>
+</ng-container>
+```
+
+### On touch
+
+There is no hover on a touch screen: the first tap on the mention opens the card instead of following the link, and a tap on the open mention follows it. The cost is one extra tap to navigate; the alternative is a preview no touch reader ever sees.
+
+Excerpt — not a complete module
+
+```html
+<ng-container slHoverCard>
+  <a slHoverCardTrigger href="/people/ana">&#64;ana.souza</a>
+  <ng-template slPopoverLayer><div slPopoverContent>…</div></ng-template>
+</ng-container>
+```
+
+### On the consumer’s own link
+
+The trigger is a component on the consumer’s anchor, and two components do not share one element: a[slLink] cannot also carry it, so the family paints the link itself and a data-part the consumer wrote is kept. The Close part inside the card is the popover’s, and it is what a touch reader has in place of Escape.
+
+Excerpt — not a complete module
+
+```html
+<ng-container slHoverCard>
+  <a slHoverCardTrigger href="/people/ana" data-part="mention">Ana Souza</a>
+  <ng-template slPopoverLayer>
+    <div slPopoverContent>
+      <div slPopoverHeader>
+        <div slPopoverTitle>Ana Souza</div>
+        <button slPopoverClose></button>
+      </div>
+    </div>
+  </ng-template>
+</ng-container>
+```
+
+### From the keyboard
+
+Tab onto the mention: the card opens in the same task, without the pointer's delay. Escape closes it and leaves focus where it is, and the mention does not reopen until focus has left it once. Tab on moves focus down the page and closes the card with the reason blur.
+
+Excerpt — not a complete module
+
+```html
+<ng-container slHoverCard (openChangeRequest)="log($event.reason)">
+  <a slHoverCardTrigger href="/people/ana">&#64;ana.souza</a>
+  <ng-template slPopoverLayer><div slPopoverContent>…</div></ng-template>
+</ng-container>
+```

package/docs/icon.json

@@ -0,0 +1,173 @@
+{
+  "family": "icon",
+  "ui": "icon",
+  "binding": "angular",
+  "catalog": {
+    "group": "Data display",
+    "summary": "Sized glyph with an optional tone."
+  },
+  "axes": {
+    "size": [
+      "text",
+      "sm",
+      "md",
+      "lg"
+    ],
+    "tone": [
+      "inherit",
+      "default",
+      "muted",
+      "accent",
+      "success",
+      "warning",
+      "danger",
+      "inverse"
+    ]
+  },
+  "members": {
+    "icon": {
+      "nativeElement": "span",
+      "defaults": {
+        "size": "md",
+        "tone": "inherit",
+        "directional": false
+      },
+      "capabilities": [
+        "size"
+      ],
+      "states": [
+        "default"
+      ],
+      "parts": [
+        "root",
+        "glyph"
+      ]
+    }
+  },
+  "docs": {
+    "icon": {
+      "imports": null,
+      "anatomy": [],
+      "api": [
+        {
+          "name": "size",
+          "type": "'text' | 'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "slIcon",
+          "description": "Box size; sm, md and lg read the control icon scale, text follows the type"
+        },
+        {
+          "name": "tone",
+          "type": "'inherit' | 'default' | 'muted' | 'accent' | 'success' | 'warning' | 'danger' | 'inverse'",
+          "defaultValue": "inherit",
+          "appliesTo": "slIcon",
+          "description": "Colour; inherit takes the colour of the text beside it"
+        },
+        {
+          "name": "directional",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slIcon",
+          "description": "The artwork points somewhere, so it mirrors in a right-to-left document"
+        },
+        {
+          "name": "label",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slIcon",
+          "description": "The name the icon carries; absent, the icon leaves the accessibility tree"
+        },
+        {
+          "name": "content",
+          "type": "projected",
+          "defaultValue": "—",
+          "appliesTo": "slIcon",
+          "description": "The glyph — an ng-icon, an svg, any artwork the consumer projects"
+        },
+        {
+          "name": "name",
+          "type": "GlyphName",
+          "defaultValue": "—",
+          "appliesTo": "slGlyph",
+          "description": "One of the library’s own icons, drawn as an svg inside the box; families draw theirs with it"
+        }
+      ],
+      "composition": [],
+      "events": [],
+      "accessibility": [
+        "A glyph is drawn aria-hidden and focusable=false: it is artwork, and the Icon around it is what carries a name. A family’s close button is named by its own aria-label, never by the cross it draws.",
+        "There is no decorative input. An icon with no name is hidden with aria-hidden, and an icon with one takes role=\"img\" and carries it, so named and hidden cannot both be true.",
+        "WAI-ARIA requires a label on role=\"img\" (§5.2.8 lists img among the roles for which a name is required), which is why the role appears only once a name exists.",
+        "An aria-label or aria-labelledby written on the element is read as a name, so the icon a consumer labelled directly keeps its label and stays in the tree.",
+        "The name says what the icon means, not what it draws: “Payment failed”, not “red triangle”. An icon that repeats adjacent text is decorative and stays out of the tree.",
+        "Colour is inherited, so an icon works in forced colours without a rule of its own. Colour alone never carries the state: the icon accompanies text, or it carries a name.",
+        "size=\"text\" is 1em, so it follows the type it sits in under page zoom and under a text-only resize alike. The sm, md and lg steps read the theme’s control geometry, which page zoom scales and a text-only resize does not; an application that needs the icon to follow text alone uses text, or retunes the density scale in rem.",
+        "The optical shift is computed from the cap height of the surrounding font and the size of the box, so an icon stays on the text’s optical line at every combination of the two rather than at the one ratio a constant would fit."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-control-icon-size-lg",
+    "--slotted-control-icon-size-md",
+    "--slotted-control-icon-size-sm",
+    "--slotted-icon-baseline-shift",
+    "--slotted-icon-size",
+    "--slotted-text",
+    "--slotted-text-inverse",
+    "--slotted-text-muted",
+    "--slotted-tone-accent-text",
+    "--slotted-tone-danger-text",
+    "--slotted-tone-success-text",
+    "--slotted-tone-warning-text"
+  ],
+  "examples": [
+    {
+      "id": "icon-angular-library-glyph",
+      "title": "The library’s own icons are real svg elements",
+      "note": null,
+      "language": "html",
+      "source": "<button slButton aria-label=\"Close\">\n  <span slIcon size=\"sm\"><svg slGlyph name=\"x\"></svg></span>\n</button>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "icon-angular-decorative",
+      "title": "Beside a label, the icon is decorative",
+      "note": null,
+      "language": "html",
+      "source": "<span slIcon><ng-icon name=\"lucideDownload\" /></span>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "icon-angular-named",
+      "title": "Alone, the icon carries the name",
+      "note": null,
+      "language": "html",
+      "source": "<span slIcon label=\"Payment failed\" tone=\"danger\"><ng-icon name=\"lucideTriangleAlert\" /></span>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "icon-angular-directional",
+      "title": "Artwork that points somewhere mirrors",
+      "note": null,
+      "language": "html",
+      "source": "<span slIcon directional><ng-icon name=\"lucideArrowRight\" /></span>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "icon-angular-container-size",
+      "title": "A container sizes every icon inside it, once",
+      "note": null,
+      "language": "html",
+      "source": "<div style=\"--slotted-icon-size: var(--slotted-control-icon-size-sm)\">\n  <ng-content />\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "icon-application-defaults",
+      "title": "Defaults for the whole application, set once",
+      "note": null,
+      "language": "css",
+      "source": "/* The family has no provider and no injection token: data-ui is public\n   contract, so the cascade sets the defaults and any subtree overrides\n   them. An instance that states its own size or tone still wins. */\n:root {\n  --slotted-icon-size: var(--slotted-control-icon-size-sm);\n}\n\n[data-ui='icon'] svg {\n  /* The stroke weight belongs to the icon set, not to the icon. */\n  stroke-width: 2.25;\n}\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/docs/icon.md

@@ -0,0 +1,101 @@
+<!-- index: ./index.md -->
+# icon
+
+`data-ui="icon"` · Sized glyph with an optional tone.
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<button slButton aria-label="Close">
+  <span slIcon size="sm"><svg slGlyph name="x"></svg></span>
+</button>
+```
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `size` | `'text' \| 'sm' \| 'md' \| 'lg'` | md | slIcon | Box size; sm, md and lg read the control icon scale, text follows the type |
+| `tone` | `'inherit' \| 'default' \| 'muted' \| 'accent' \| 'success' \| 'warning' \| 'danger' \| 'inverse'` | inherit | slIcon | Colour; inherit takes the colour of the text beside it |
+| `directional` | `boolean` | false | slIcon | The artwork points somewhere, so it mirrors in a right-to-left document |
+| `label` | `string` | — | slIcon | The name the icon carries; absent, the icon leaves the accessibility tree |
+| `content` | `projected` | — | slIcon | The glyph — an ng-icon, an svg, any artwork the consumer projects |
+| `name` | `GlyphName` | — | slGlyph | One of the library’s own icons, drawn as an svg inside the box; families draw theirs with it |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `text`, `sm`, `md`, `lg` | `md` |
+| `tone` | `inherit`, `default`, `muted`, `accent`, `success`, `warning`, `danger`, `inverse` | `inherit` |
+
+## Rules
+
+- A glyph is drawn aria-hidden and focusable=false: it is artwork, and the Icon around it is what carries a name. A family’s close button is named by its own aria-label, never by the cross it draws.
+- There is no decorative input. An icon with no name is hidden with aria-hidden, and an icon with one takes role="img" and carries it, so named and hidden cannot both be true.
+- WAI-ARIA requires a label on role="img" (§5.2.8 lists img among the roles for which a name is required), which is why the role appears only once a name exists.
+- An aria-label or aria-labelledby written on the element is read as a name, so the icon a consumer labelled directly keeps its label and stays in the tree.
+- The name says what the icon means, not what it draws: “Payment failed”, not “red triangle”. An icon that repeats adjacent text is decorative and stays out of the tree.
+- Colour is inherited, so an icon works in forced colours without a rule of its own. Colour alone never carries the state: the icon accompanies text, or it carries a name.
+- size="text" is 1em, so it follows the type it sits in under page zoom and under a text-only resize alike. The sm, md and lg steps read the theme’s control geometry, which page zoom scales and a text-only resize does not; an application that needs the icon to follow text alone uses text, or retunes the density scale in rem.
+- The optical shift is computed from the cap height of the surrounding font and the size of the box, so an icon stays on the text’s optical line at every combination of the two rather than at the one ratio a constant would fit.
+
+## Tokens
+
+`--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-icon-baseline-shift`, `--slotted-icon-size`, `--slotted-text`, `--slotted-text-inverse`, `--slotted-text-muted`, `--slotted-tone-accent-text`, `--slotted-tone-danger-text`, `--slotted-tone-success-text`, `--slotted-tone-warning-text`
+
+## Examples
+
+### Beside a label, the icon is decorative
+
+Excerpt — not a complete module
+
+```html
+<span slIcon><ng-icon name="lucideDownload" /></span>
+```
+
+### Alone, the icon carries the name
+
+Excerpt — not a complete module
+
+```html
+<span slIcon label="Payment failed" tone="danger"><ng-icon name="lucideTriangleAlert" /></span>
+```
+
+### Artwork that points somewhere mirrors
+
+Excerpt — not a complete module
+
+```html
+<span slIcon directional><ng-icon name="lucideArrowRight" /></span>
+```
+
+### A container sizes every icon inside it, once
+
+Excerpt — not a complete module
+
+```html
+<div style="--slotted-icon-size: var(--slotted-control-icon-size-sm)">
+  <ng-content />
+</div>
+```
+
+### Defaults for the whole application, set once
+
+Excerpt — not a complete module
+
+```css
+/* The family has no provider and no injection token: data-ui is public
+   contract, so the cascade sets the defaults and any subtree overrides
+   them. An instance that states its own size or tone still wins. */
+:root {
+  --slotted-icon-size: var(--slotted-control-icon-size-sm);
+}
+
+[data-ui='icon'] svg {
+  /* The stroke weight belongs to the icon set, not to the icon. */
+  stroke-width: 2.25;
+}
+```