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

package/docs/link.json

@@ -0,0 +1,264 @@
+{
+  "family": "link",
+  "ui": "link",
+  "binding": "angular",
+  "catalog": {
+    "group": "Navigation",
+    "summary": "Text link to another page or resource."
+  },
+  "axes": {
+    "underline": [
+      "always",
+      "hover",
+      "none"
+    ],
+    "variant": [
+      "accent",
+      "neutral",
+      "inverse"
+    ]
+  },
+  "members": {
+    "link": {
+      "nativeElement": "a",
+      "defaults": {
+        "underline": "always",
+        "variant": "accent",
+        "visited": false,
+        "external": false,
+        "disabled": false
+      },
+      "capabilities": [
+        "appearance",
+        "underline",
+        "external",
+        "disabled"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "disabled"
+      ],
+      "parts": [
+        "root",
+        "external-icon",
+        "external-hint"
+      ]
+    }
+  },
+  "docs": {
+    "link": {
+      "imports": {
+        "source": "import { SlLink, provideLinkDefaults } from '@slotted/angular/link';",
+        "selector": "a[slLink]",
+        "exportAs": "slLink"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "a",
+          "required": true,
+          "purpose": "The consumer’s own anchor, which is why routerLink, href and every native attribute sit on the same element. Carries data-ui=\"link\" and the axes as data attributes."
+        },
+        {
+          "part": "external-icon",
+          "element": "span",
+          "required": false,
+          "purpose": "The marker a new tab earns: the external Glyph inside a directional icon box, sized to the text and hidden from assistive technology. Rendered only when the link opens a new browsing context."
+        },
+        {
+          "part": "external-hint",
+          "element": "span",
+          "required": false,
+          "purpose": "The same warning in words, clipped from view and appended to the accessible name. Rendered with the visually-hidden family."
+        }
+      ],
+      "api": [
+        {
+          "name": "underline",
+          "type": "'always' | 'hover' | 'none'",
+          "defaultValue": "always",
+          "appliesTo": "slLink",
+          "description": "When the underline is drawn"
+        },
+        {
+          "name": "variant",
+          "type": "'accent' | 'neutral' | 'inverse'",
+          "defaultValue": "accent",
+          "appliesTo": "slLink",
+          "description": "Accent, the colour of the surrounding text, or a solid surface"
+        },
+        {
+          "name": "external",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slLink",
+          "description": "Opens a new tab and warns that it does"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<LinkMessages>",
+          "defaultValue": "—",
+          "appliesTo": "slLink",
+          "description": "Words laid over the language in force: the wording of that warning (externalHint)"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slLink",
+          "description": "Withholds the destination, keeps the role, the state and the tab stop"
+        },
+        {
+          "name": "visited",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slLink",
+          "description": "Paints a destination the reader already followed"
+        }
+      ],
+      "composition": [
+        {
+          "name": "href, target, rel, download",
+          "type": "attribute",
+          "defaultValue": "—",
+          "appliesTo": "The anchor",
+          "description": "The consumer’s own attributes. rel and target are added only when the anchor carries neither, and never rewritten."
+        },
+        {
+          "name": "routerLink, routerLinkActive",
+          "type": "directive",
+          "defaultValue": "—",
+          "appliesTo": "The same element",
+          "description": "The directive claims no destination of its own, so the router writes href and aria-current on the anchor it already owns"
+        },
+        {
+          "name": "exportAs=\"slLink\"",
+          "type": "template reference",
+          "defaultValue": "—",
+          "appliesTo": "Template",
+          "description": "Reaches the instance, for a template that needs to read the resolved axes"
+        },
+        {
+          "name": "provideLinkDefaults",
+          "type": "underline | variant | visited",
+          "defaultValue": "—",
+          "appliesTo": "Application",
+          "description": "Sets those three once for the whole injector; an input on the link still wins"
+        }
+      ],
+      "events": [],
+      "accessibility": [
+        "The directive sits on the consumer’s own anchor, so the link role, Enter, the context menu and every modified click come from the platform — and routerLink composes on the same element. Space does not activate a link, and nothing here makes it.",
+        "underline=\"always\" is the default because colour alone does not distinguish a link: the accent text colour clears 4.5:1 against the surface and not 3:1 against the body text beside it.",
+        "variant=\"neutral\" takes the colour of the text around it, so it belongs where nothing on the line could be mistaken for it — a cell, a title, a row — and never inside a sentence.",
+        "Whatever the underline axis says, the underline returns under forced-colors, where the palette flattens the colour contrast a bare link relies on.",
+        "A new browsing context is announced in the accessible name and marked with a glyph. external states it, and so does a static target=\"_blank\" the consumer wrote.",
+        "rel and target are added only when the anchor carries neither, so an attribute the consumer wrote is never rewritten or removed.",
+        "A disabled link keeps no href, which is what stops a middle click as well as a left one, and keeps role=\"link\", aria-disabled and its place in the tab sequence so the state can be discovered.",
+        "The current page is painted from aria-current, which routerLinkActive writes through ariaCurrentWhenActive; the family invents no input for it."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-control-radius",
+    "--slotted-disabled-foreground",
+    "--slotted-duration-short",
+    "--slotted-easing-standard",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-width",
+    "--slotted-link-color",
+    "--slotted-link-color-active",
+    "--slotted-link-color-current",
+    "--slotted-link-color-disabled",
+    "--slotted-link-color-hover",
+    "--slotted-link-color-visited",
+    "--slotted-link-external-icon-gap",
+    "--slotted-link-external-icon-size",
+    "--slotted-link-focus-ring-offset",
+    "--slotted-link-radius",
+    "--slotted-link-underline-color",
+    "--slotted-link-underline-offset",
+    "--slotted-link-underline-thickness",
+    "--slotted-text",
+    "--slotted-text-inverse",
+    "--slotted-text-muted",
+    "--slotted-tone-accent-text"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "Every input on one link inside a sentence, driven by the controls below the canvas. Change underline and watch what a reader has left to recognize the link by.",
+      "language": "html",
+      "source": "<p>Read the <a slLink href=\"/terms\">terms of service</a> before continuing.</p>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "underline",
+      "title": "When the underline is drawn",
+      "note": "always is the default and the only value safe inside a sentence: the accent text colour clears 4.5:1 against the surface but not 3:1 against the body text beside it.",
+      "language": "html",
+      "source": "<a slLink href=\"/invoices\">Underlined always</a>\n<a slLink href=\"/invoices\" underline=\"hover\">Underlined on hover</a>\n<a slLink href=\"/invoices\" underline=\"none\">Never underlined</a>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "variants",
+      "title": "How the link is painted",
+      "note": "accent invites, neutral takes the colour of the text around it for a cell or a title, and inverse is the link on a solid surface. Hover moves each one toward the strongest text colour its context has.",
+      "language": "html",
+      "source": "<a slLink href=\"/history\">payment history</a>\n<a slLink href=\"/invoices/0041\" underline=\"hover\" variant=\"neutral\">INV-2026-08-0041</a>\n<a slLink href=\"/plans\" variant=\"inverse\">Choose a plan</a>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "external",
+      "title": "Leaving the application",
+      "note": "One fact told three ways: the safe rel, the marker for the eye, the warning in the accessible name. A static target=\"_blank\" the consumer wrote states the same fact and earns the same three.",
+      "language": "html",
+      "source": "<a slLink external href=\"https://example.com/docs\">Documentation</a>\n<a slLink href=\"https://example.com/docs\" target=\"_blank\">Documentation</a>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "States",
+      "note": "Hover darkens the text and fills the underline, press goes one step further, and an unavailable link keeps its underline so it still reads as a link rather than as plain text.",
+      "language": "html",
+      "source": "<a slLink href=\"/invoices\">At rest</a>\n<a slLink href=\"/invoices\" visited>Followed before</a>\n<a slLink disabled href=\"/invoices/0042\">Unavailable until the invoice is issued</a>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "current",
+      "title": "The page you are on",
+      "note": "routerLinkActive writes aria-current through ariaCurrentWhenActive, and the stylesheet paints that attribute. The family declares no input for it and nothing to keep in sync.",
+      "language": "html",
+      "source": "<nav aria-label=\"Workspace\">\n  <a slLink routerLink=\"/invoices\" routerLinkActive ariaCurrentWhenActive=\"page\" underline=\"hover\"\n    >Invoices</a\n  >\n  <a slLink routerLink=\"/members\" routerLinkActive ariaCurrentWhenActive=\"page\" underline=\"hover\"\n    >Members</a\n  >\n</nav>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the link did not choose",
+      "note": "A pasted URL with no spaces, a long German compound, and an Arabic sentence. The first two break inside the column instead of widening it; the third mirrors the marker without mirroring the Latin island beside it.",
+      "language": "html",
+      "source": "<a slLink href=\"/reconciliation\"\n  >https://billing.example.com/accounts/8412/invoices/2026-08/reconciliation-report</a\n>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Composition",
+      "note": "The directive sits on the anchor the consumer wrote, so routerLink, a static href and a dense table cell all compose with it. provideLinkDefaults decides for a whole application what a link looks like.",
+      "language": "ts",
+      "source": "bootstrapApplication(App, {\n  providers: [provideLinkDefaults({ underline: 'hover' })],\n});\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "accessibility",
+      "title": "Keyboard and announcement",
+      "note": "Tab reaches every link including the unavailable one, Enter follows the one that has a destination, and Space does nothing because Space does not activate a link.",
+      "language": "html",
+      "source": "<a slLink href=\"/invoices\">A link with a destination</a>\n<a slLink external href=\"https://example.com/status\">A link that leaves the application</a>\n<a slLink disabled href=\"/invoices/0042\">A link that is unavailable</a>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/docs/link.md

@@ -0,0 +1,167 @@
+<!-- index: ./index.md -->
+# link
+
+`data-ui="link"` · Text link to another page or resource.
+
+## Import
+
+```ts
+import { SlLink, provideLinkDefaults } from '@slotted/angular/link';
+```
+
+Selector: `a[slLink]` · exportAs: `slLink`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<p>Read the <a slLink href="/terms">terms of service</a> before continuing.</p>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | a | yes |
+| `external-icon` | span | no |
+| `external-hint` | span | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `underline` | `'always' \| 'hover' \| 'none'` | always | slLink | When the underline is drawn |
+| `variant` | `'accent' \| 'neutral' \| 'inverse'` | accent | slLink | Accent, the colour of the surrounding text, or a solid surface |
+| `external` | `boolean` | false | slLink | Opens a new tab and warns that it does |
+| `messages` | `Partial<LinkMessages>` | — | slLink | Words laid over the language in force: the wording of that warning (externalHint) |
+| `disabled` | `boolean` | false | slLink | Withholds the destination, keeps the role, the state and the tab stop |
+| `visited` | `boolean` | false | slLink | Paints a destination the reader already followed |
+| `href, target, rel, download` | `attribute` | — | The anchor | The consumer’s own attributes. rel and target are added only when the anchor carries neither, and never rewritten. |
+| `routerLink, routerLinkActive` | `directive` | — | The same element | The directive claims no destination of its own, so the router writes href and aria-current on the anchor it already owns |
+| `exportAs="slLink"` | `template reference` | — | Template | Reaches the instance, for a template that needs to read the resolved axes |
+| `provideLinkDefaults` | `underline \| variant \| visited` | — | Application | Sets those three once for the whole injector; an input on the link still wins |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `underline` | `always`, `hover`, `none` | `always` |
+| `variant` | `accent`, `neutral`, `inverse` | `accent` |
+
+## Rules
+
+- The directive sits on the consumer’s own anchor, so the link role, Enter, the context menu and every modified click come from the platform — and routerLink composes on the same element. Space does not activate a link, and nothing here makes it.
+- underline="always" is the default because colour alone does not distinguish a link: the accent text colour clears 4.5:1 against the surface and not 3:1 against the body text beside it.
+- variant="neutral" takes the colour of the text around it, so it belongs where nothing on the line could be mistaken for it — a cell, a title, a row — and never inside a sentence.
+- Whatever the underline axis says, the underline returns under forced-colors, where the palette flattens the colour contrast a bare link relies on.
+- A new browsing context is announced in the accessible name and marked with a glyph. external states it, and so does a static target="_blank" the consumer wrote.
+- rel and target are added only when the anchor carries neither, so an attribute the consumer wrote is never rewritten or removed.
+- A disabled link keeps no href, which is what stops a middle click as well as a left one, and keeps role="link", aria-disabled and its place in the tab sequence so the state can be discovered.
+- The current page is painted from aria-current, which routerLinkActive writes through ariaCurrentWhenActive; the family invents no input for it.
+
+## Tokens
+
+`--slotted-control-radius`, `--slotted-disabled-foreground`, `--slotted-duration-short`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-width`, `--slotted-link-color`, `--slotted-link-color-active`, `--slotted-link-color-current`, `--slotted-link-color-disabled`, `--slotted-link-color-hover`, `--slotted-link-color-visited`, `--slotted-link-external-icon-gap`, `--slotted-link-external-icon-size`, `--slotted-link-focus-ring-offset`, `--slotted-link-radius`, `--slotted-link-underline-color`, `--slotted-link-underline-offset`, `--slotted-link-underline-thickness`, `--slotted-text`, `--slotted-text-inverse`, `--slotted-text-muted`, `--slotted-tone-accent-text`
+
+## Examples
+
+### When the underline is drawn
+
+always is the default and the only value safe inside a sentence: the accent text colour clears 4.5:1 against the surface but not 3:1 against the body text beside it.
+
+Excerpt — not a complete module
+
+```html
+<a slLink href="/invoices">Underlined always</a>
+<a slLink href="/invoices" underline="hover">Underlined on hover</a>
+<a slLink href="/invoices" underline="none">Never underlined</a>
+```
+
+### How the link is painted
+
+accent invites, neutral takes the colour of the text around it for a cell or a title, and inverse is the link on a solid surface. Hover moves each one toward the strongest text colour its context has.
+
+Excerpt — not a complete module
+
+```html
+<a slLink href="/history">payment history</a>
+<a slLink href="/invoices/0041" underline="hover" variant="neutral">INV-2026-08-0041</a>
+<a slLink href="/plans" variant="inverse">Choose a plan</a>
+```
+
+### Leaving the application
+
+One fact told three ways: the safe rel, the marker for the eye, the warning in the accessible name. A static target="_blank" the consumer wrote states the same fact and earns the same three.
+
+Excerpt — not a complete module
+
+```html
+<a slLink external href="https://example.com/docs">Documentation</a>
+<a slLink href="https://example.com/docs" target="_blank">Documentation</a>
+```
+
+### States
+
+Hover darkens the text and fills the underline, press goes one step further, and an unavailable link keeps its underline so it still reads as a link rather than as plain text.
+
+Excerpt — not a complete module
+
+```html
+<a slLink href="/invoices">At rest</a>
+<a slLink href="/invoices" visited>Followed before</a>
+<a slLink disabled href="/invoices/0042">Unavailable until the invoice is issued</a>
+```
+
+### The page you are on
+
+routerLinkActive writes aria-current through ariaCurrentWhenActive, and the stylesheet paints that attribute. The family declares no input for it and nothing to keep in sync.
+
+Excerpt — not a complete module
+
+```html
+<nav aria-label="Workspace">
+  <a slLink routerLink="/invoices" routerLinkActive ariaCurrentWhenActive="page" underline="hover"
+    >Invoices</a
+  >
+  <a slLink routerLink="/members" routerLinkActive ariaCurrentWhenActive="page" underline="hover"
+    >Members</a
+  >
+</nav>
+```
+
+### Content the link did not choose
+
+A pasted URL with no spaces, a long German compound, and an Arabic sentence. The first two break inside the column instead of widening it; the third mirrors the marker without mirroring the Latin island beside it.
+
+Excerpt — not a complete module
+
+```html
+<a slLink href="/reconciliation"
+  >https://billing.example.com/accounts/8412/invoices/2026-08/reconciliation-report</a
+>
+```
+
+### Composition
+
+The directive sits on the anchor the consumer wrote, so routerLink, a static href and a dense table cell all compose with it. provideLinkDefaults decides for a whole application what a link looks like.
+
+Excerpt — not a complete module
+
+```ts
+bootstrapApplication(App, {
+  providers: [provideLinkDefaults({ underline: 'hover' })],
+});
+```
+
+### Keyboard and announcement
+
+Tab reaches every link including the unavailable one, Enter follows the one that has a destination, and Space does nothing because Space does not activate a link.
+
+Excerpt — not a complete module
+
+```html
+<a slLink href="/invoices">A link with a destination</a>
+<a slLink external href="https://example.com/status">A link that leaves the application</a>
+<a slLink disabled href="/invoices/0042">A link that is unavailable</a>
+```