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

package/docs/context-menu.json

@@ -0,0 +1,231 @@
+{
+  "family": "context-menu",
+  "ui": "context-menu",
+  "binding": "angular",
+  "catalog": {
+    "group": "Overlays",
+    "summary": "Menu opened by right click on a target."
+  },
+  "axes": {
+    "longPress": [
+      true,
+      false
+    ],
+    "disabled": [
+      true,
+      false
+    ]
+  },
+  "members": {
+    "contextMenu": {
+      "nativeElement": "div",
+      "defaults": {
+        "longPress": true,
+        "longPressDelay": 500,
+        "disabled": false
+      },
+      "capabilities": [
+        "open",
+        "disabled",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "open",
+        "pressed",
+        "disabled"
+      ],
+      "parts": [
+        "root"
+      ]
+    }
+  },
+  "docs": {
+    "contextMenu": {
+      "imports": {
+        "source": "import { SlContextMenuTrigger, provideContextMenuDefaults } from '@slotted/angular/context-menu';\nimport { SlMenu, SlMenuItem, SlMenuSeparator } from '@slotted/angular/menu';",
+        "selector": "[slContextMenuTriggerFor]",
+        "exportAs": "slContextMenuTrigger"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "the consumer's own element — a div, a tr, a card",
+          "required": true,
+          "purpose": "The target: the region the menu opens on. It carries data-ui=\"context-menu\", data-open while the menu shows, data-pressed during a long press and data-disabled while the browser's menu is the one that opens. The menu is the menu family unchanged — data-ui=\"menu\"."
+        }
+      ],
+      "api": [
+        {
+          "name": "open",
+          "type": "model<boolean>",
+          "defaultValue": "false",
+          "appliesTo": "sl-menu",
+          "description": "Whether the menu shows. Two-way: [(open)] on the sl-menu the target opens. The state is the menu’s and the target only asks it to move."
+        },
+        {
+          "name": "slContextMenuTriggerFor",
+          "type": "SlMenu",
+          "defaultValue": "—",
+          "appliesTo": "target",
+          "description": "The menu this region opens, as a template reference: [slContextMenuTriggerFor]=\"actions\"."
+        },
+        {
+          "name": "longPress",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "target",
+          "description": "Whether holding the region on touch and pen opens the menu."
+        },
+        {
+          "name": "longPressDelay",
+          "type": "number",
+          "defaultValue": "500",
+          "appliesTo": "target",
+          "description": "Milliseconds the press is held before the menu opens; movement past ten pixels or lifting first cancels it."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "sl-menu",
+          "description": "The menu’s own disabled: the family never opens and the browser’s menu passes through. The target carries data-disabled."
+        },
+        {
+          "name": "size, side, align, closeOnSelect, loop, typeahead, …",
+          "type": "SlMenu inputs",
+          "defaultValue": "—",
+          "appliesTo": "sl-menu",
+          "description": "Every input of sl-menu reaches the surface unchanged; anchor and finalFocus are written by the target."
+        }
+      ],
+      "composition": [
+        {
+          "name": "provideContextMenuDefaults()",
+          "type": "provider",
+          "defaultValue": "—",
+          "appliesTo": "Application",
+          "description": "Sets longPress and longPressDelay once for an injector. A target that states one itself still wins; the surface reads provideMenuDefaults()."
+        },
+        {
+          "name": "sl-menu, slMenuItem, …",
+          "type": "directives",
+          "defaultValue": "—",
+          "appliesTo": "Beside the target",
+          "description": "The surface is the menu family unchanged: submenus, checkbox and radio items, groups, shortcuts, typeahead and tone reach the context menu without a second API. Nothing is re-exported."
+        },
+        {
+          "name": "exportAs",
+          "type": "template reference",
+          "defaultValue": "—",
+          "appliesTo": "target",
+          "description": "A template reaches the target — #target=\"slContextMenuTrigger\" — and the menu — #actions=\"slMenu\" — for show() and hide()."
+        },
+        {
+          "name": "aria-label",
+          "type": "attribute",
+          "defaultValue": "—",
+          "appliesTo": "sl-menu",
+          "description": "The surface is named after the target’s text unless given one — right for a row, wrong for a canvas."
+        },
+        {
+          "name": "host attributes",
+          "type": "attributes",
+          "defaultValue": "—",
+          "appliesTo": "target",
+          "description": "The target is the consumer’s own element with its own attributes; a data-part it already carries — a table row’s — is kept, and the identity is written beside it."
+        }
+      ],
+      "events": [
+        {
+          "name": "openChangeRequest",
+          "payload": "ChangeRequest<boolean>",
+          "when": "Before the menu opens or closes. The request carries pointer (a secondary click or a long press), keyboard (Shift+F10, the Menu key), escape, outsidePress (a press anywhere else, the target included), select, dismiss or programmatic, the originating event, and cancel(). Moving to a new point while open emits nothing, because open did not change."
+        }
+      ],
+      "accessibility": [
+        "The platform supplies the gesture: the contextmenu event is the secondary click, the Menu key and Shift+F10 on every desktop, and the family answers all three with preventDefault while it is enabled and with nothing while it is disabled, so a reader is never left with no menu at all.",
+        "The family writes no aria-haspopup on the target — it is not permitted on a generic element, and no surveyed library writes it — so a screen reader is not told the region has a menu. That is why every command in a context menu also exists by another path, and the reference page shows the path.",
+        "Focus goes to the first item on open and, on Escape or after a command, back to whatever held it when the menu opened — the checkbox in the row, the tile itself — rather than to a trigger that never had it. A press elsewhere leaves focus where the reader put it.",
+        "The family writes no tabindex: a target the page made focusable can be opened from the keyboard, and one it did not cannot. A tab stop on every wrapped region would be one a grid with roving focus cannot afford."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-strong",
+    "--slotted-border-width-thin",
+    "--slotted-context-menu-mark-color",
+    "--slotted-context-menu-mark-width",
+    "--slotted-duration-short",
+    "--slotted-easing-standard",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "The menu hangs from the tile because it opened from a bound [open]; right-click anywhere on the tile and it moves to the point. The controls under the canvas change the long press and disable the family, which hands the click to the browser.",
+      "language": "html",
+      "source": "<div class=\"tile\" [slContextMenuTriggerFor]=\"actions\">…</div>\n<sl-menu #actions aria-label=\"Document actions\">\n  <button slMenuItem>Open</button>\n  <button slMenuItem tone=\"danger\">Move to trash</button>\n</sl-menu>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "target",
+      "title": "The target",
+      "note": "The tile is the target and paints nothing at rest; while the menu shows, an inward one-pixel mark laid over the tile says which one the commands act on, following the tile’s own corner. The tile on the right was opened from a bound [open], so the menu hangs from it the way a keyboard opening places it. A target wrapped around a card would frame the card’s round corners with a square: make the card the target.",
+      "language": "html",
+      "source": "<div class=\"tile\" [slContextMenuTriggerFor]=\"actions\" tabindex=\"0\">…</div>\n<sl-menu #actions [open]=\"true\">…</sl-menu>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "rows",
+      "title": "One menu for many rows",
+      "note": "A list of files with one slContextMenuTriggerFor around all of them. Right-click any row: the request carries the event, the handler reads the row from it, and the menu names the file it acts on. Mounting a menu per row is the shape this composition exists to avoid.",
+      "language": "html",
+      "source": "<ul [slContextMenuTriggerFor]=\"actions\">\n  @for (name of files; track name) {\n    <li [attr.data-file]=\"name\">{{ name }}</li>\n  }\n</ul>\n<sl-menu\n  #actions\n  [attr.aria-label]=\"file() ?? 'File actions'\"\n  (openChangeRequest)=\"remember($event)\"\n>\n  …\n</sl-menu>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "From the keyboard",
+      "note": "Tab to the tile — it is focusable because the page said so, with tabindex — and press Shift+F10 or the Menu key. The menu hangs from the tile rather than from wherever the pointer last was, focus lands on the first item, and Escape brings it back to the tile.",
+      "language": "html",
+      "source": "<div [slContextMenuTriggerFor]=\"actions\" tabindex=\"0\" aria-label=\"Release notes 4.2\">…</div>\n<sl-menu #actions>…</sl-menu>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "touch",
+      "title": "On touch",
+      "note": "There is no secondary button on a touch screen: holding the tile for half a second opens the menu at the finger, while text selection and the platform's callout are held off for the duration of the press. Lifting or moving past ten pixels before then cancels it, so a scroll that starts on the tile is still a scroll.",
+      "language": "html",
+      "source": "<div [slContextMenuTriggerFor]=\"actions\" [longPressDelay]=\"400\">…</div>\n<sl-menu #actions>…</sl-menu>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "other-path",
+      "title": "The other path",
+      "note": "A context menu is found by convention, and a reader who never right-clicks must still reach every command in it: the same actions sit behind the Actions button on the tile, as a menu opened the ordinary way. A menu has one trigger element, so the region and the button each open their own sl-menu, and one ng-template holds the commands both render.",
+      "language": "html",
+      "source": "<ng-template #commands>\n  <button slMenuItem>Open</button>\n  <button slMenuItem>Rename</button>\n</ng-template>\n\n<div class=\"tile\" [slContextMenuTriggerFor]=\"fromRegion\">\n  <button slButton variant=\"ghost\" [slMenuTriggerFor]=\"fromButton\">Actions</button>\n</div>\n<sl-menu #fromRegion aria-label=\"Document actions\">\n  <ng-container *ngTemplateOutlet=\"commands\" />\n</sl-menu>\n<sl-menu #fromButton>\n  <ng-container *ngTemplateOutlet=\"commands\" />\n</sl-menu>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "disabled",
+      "title": "Disabled",
+      "note": "A disabled family suppresses nothing: the browser's own menu opens on the secondary click, because taking both away would leave the reader with none. The target says so with data-disabled and paints nothing, since the content it wraps still works.",
+      "language": "html",
+      "source": "<div [slContextMenuTriggerFor]=\"actions\">…</div>\n<sl-menu #actions [disabled]=\"true\">…</sl-menu>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "States",
+      "note": "Three tiles: at rest nothing is painted; open draws the inward mark in the colour that separates two surfaces; disabled paints nothing either; pressed exists only for the half second a finger is held, and turns off selection rather than painting.",
+      "language": "css",
+      "source": "[data-ui='context-menu'][data-open] {\n  --slotted-context-menu-mark-color: var(--slotted-tone-accent-border);\n}\n[data-ui='context-menu'][data-pressed] {\n  opacity: 0.9;\n}\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/docs/context-menu.md

@@ -0,0 +1,176 @@
+<!-- index: ./index.md -->
+# context-menu
+
+`data-ui="context-menu"` · Menu opened by right click on a target.
+
+## Import
+
+```ts
+import { SlContextMenuTrigger, provideContextMenuDefaults } from '@slotted/angular/context-menu';
+import { SlMenu, SlMenuItem, SlMenuSeparator } from '@slotted/angular/menu';
+```
+
+Selector: `[slContextMenuTriggerFor]` · exportAs: `slContextMenuTrigger`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div class="tile" [slContextMenuTriggerFor]="actions">…</div>
+<sl-menu #actions aria-label="Document actions">
+  <button slMenuItem>Open</button>
+  <button slMenuItem tone="danger">Move to trash</button>
+</sl-menu>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the consumer's own element — a div, a tr, a card | yes |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `open` | `model<boolean>` | false | sl-menu | Whether the menu shows. Two-way: [(open)] on the sl-menu the target opens. The state is the menu’s and the target only asks it to move. |
+| `slContextMenuTriggerFor` | `SlMenu` | — | target | The menu this region opens, as a template reference: [slContextMenuTriggerFor]="actions". |
+| `longPress` | `boolean` | true | target | Whether holding the region on touch and pen opens the menu. |
+| `longPressDelay` | `number` | 500 | target | Milliseconds the press is held before the menu opens; movement past ten pixels or lifting first cancels it. |
+| `disabled` | `boolean` | false | sl-menu | The menu’s own disabled: the family never opens and the browser’s menu passes through. The target carries data-disabled. |
+| `size, side, align, closeOnSelect, loop, typeahead, …` | `SlMenu inputs` | — | sl-menu | Every input of sl-menu reaches the surface unchanged; anchor and finalFocus are written by the target. |
+| `provideContextMenuDefaults()` | `provider` | — | Application | Sets longPress and longPressDelay once for an injector. A target that states one itself still wins; the surface reads provideMenuDefaults(). |
+| `sl-menu, slMenuItem, …` | `directives` | — | Beside the target | The surface is the menu family unchanged: submenus, checkbox and radio items, groups, shortcuts, typeahead and tone reach the context menu without a second API. Nothing is re-exported. |
+| `exportAs` | `template reference` | — | target | A template reaches the target — #target="slContextMenuTrigger" — and the menu — #actions="slMenu" — for show() and hide(). |
+| `aria-label` | `attribute` | — | sl-menu | The surface is named after the target’s text unless given one — right for a row, wrong for a canvas. |
+| `host attributes` | `attributes` | — | target | The target is the consumer’s own element with its own attributes; a data-part it already carries — a table row’s — is kept, and the identity is written beside it. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `openChangeRequest` | `ChangeRequest<boolean>` | Before the menu opens or closes. The request carries pointer (a secondary click or a long press), keyboard (Shift+F10, the Menu key), escape, outsidePress (a press anywhere else, the target included), select, dismiss or programmatic, the originating event, and cancel(). Moving to a new point while open emits nothing, because open did not change. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `longPress` | `true`, `false` | `true` |
+| `disabled` | `true`, `false` | `false` |
+
+## Rules
+
+- The platform supplies the gesture: the contextmenu event is the secondary click, the Menu key and Shift+F10 on every desktop, and the family answers all three with preventDefault while it is enabled and with nothing while it is disabled, so a reader is never left with no menu at all.
+- The family writes no aria-haspopup on the target — it is not permitted on a generic element, and no surveyed library writes it — so a screen reader is not told the region has a menu. That is why every command in a context menu also exists by another path, and the reference page shows the path.
+- Focus goes to the first item on open and, on Escape or after a command, back to whatever held it when the menu opened — the checkbox in the row, the tile itself — rather than to a trigger that never had it. A press elsewhere leaves focus where the reader put it.
+- The family writes no tabindex: a target the page made focusable can be opened from the keyboard, and one it did not cannot. A tab stop on every wrapped region would be one a grid with roving focus cannot afford.
+
+## Tokens
+
+`--slotted-border-strong`, `--slotted-border-width-thin`, `--slotted-context-menu-mark-color`, `--slotted-context-menu-mark-width`, `--slotted-duration-short`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`
+
+## Examples
+
+### The target
+
+The tile is the target and paints nothing at rest; while the menu shows, an inward one-pixel mark laid over the tile says which one the commands act on, following the tile’s own corner. The tile on the right was opened from a bound [open], so the menu hangs from it the way a keyboard opening places it. A target wrapped around a card would frame the card’s round corners with a square: make the card the target.
+
+Excerpt — not a complete module
+
+```html
+<div class="tile" [slContextMenuTriggerFor]="actions" tabindex="0">…</div>
+<sl-menu #actions [open]="true">…</sl-menu>
+```
+
+### One menu for many rows
+
+A list of files with one slContextMenuTriggerFor around all of them. Right-click any row: the request carries the event, the handler reads the row from it, and the menu names the file it acts on. Mounting a menu per row is the shape this composition exists to avoid.
+
+Excerpt — not a complete module
+
+```html
+<ul [slContextMenuTriggerFor]="actions">
+  @for (name of files; track name) {
+    <li [attr.data-file]="name">{{ name }}</li>
+  }
+</ul>
+<sl-menu
+  #actions
+  [attr.aria-label]="file() ?? 'File actions'"
+  (openChangeRequest)="remember($event)"
+>
+  …
+</sl-menu>
+```
+
+### From the keyboard
+
+Tab to the tile — it is focusable because the page said so, with tabindex — and press Shift+F10 or the Menu key. The menu hangs from the tile rather than from wherever the pointer last was, focus lands on the first item, and Escape brings it back to the tile.
+
+Excerpt — not a complete module
+
+```html
+<div [slContextMenuTriggerFor]="actions" tabindex="0" aria-label="Release notes 4.2">…</div>
+<sl-menu #actions>…</sl-menu>
+```
+
+### On touch
+
+There is no secondary button on a touch screen: holding the tile for half a second opens the menu at the finger, while text selection and the platform's callout are held off for the duration of the press. Lifting or moving past ten pixels before then cancels it, so a scroll that starts on the tile is still a scroll.
+
+Excerpt — not a complete module
+
+```html
+<div [slContextMenuTriggerFor]="actions" [longPressDelay]="400">…</div>
+<sl-menu #actions>…</sl-menu>
+```
+
+### The other path
+
+A context menu is found by convention, and a reader who never right-clicks must still reach every command in it: the same actions sit behind the Actions button on the tile, as a menu opened the ordinary way. A menu has one trigger element, so the region and the button each open their own sl-menu, and one ng-template holds the commands both render.
+
+Excerpt — not a complete module
+
+```html
+<ng-template #commands>
+  <button slMenuItem>Open</button>
+  <button slMenuItem>Rename</button>
+</ng-template>
+
+<div class="tile" [slContextMenuTriggerFor]="fromRegion">
+  <button slButton variant="ghost" [slMenuTriggerFor]="fromButton">Actions</button>
+</div>
+<sl-menu #fromRegion aria-label="Document actions">
+  <ng-container *ngTemplateOutlet="commands" />
+</sl-menu>
+<sl-menu #fromButton>
+  <ng-container *ngTemplateOutlet="commands" />
+</sl-menu>
+```
+
+### Disabled
+
+A disabled family suppresses nothing: the browser's own menu opens on the secondary click, because taking both away would leave the reader with none. The target says so with data-disabled and paints nothing, since the content it wraps still works.
+
+Excerpt — not a complete module
+
+```html
+<div [slContextMenuTriggerFor]="actions">…</div>
+<sl-menu #actions [disabled]="true">…</sl-menu>
+```
+
+### States
+
+Three tiles: at rest nothing is painted; open draws the inward mark in the colour that separates two surfaces; disabled paints nothing either; pressed exists only for the half second a finger is held, and turns off selection rather than painting.
+
+Excerpt — not a complete module
+
+```css
+[data-ui='context-menu'][data-open] {
+  --slotted-context-menu-mark-color: var(--slotted-tone-accent-border);
+}
+[data-ui='context-menu'][data-pressed] {
+  opacity: 0.9;
+}
+```