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

package/docs/split-button.json

@@ -0,0 +1,361 @@
+{
+  "family": "split-button",
+  "ui": "split-button",
+  "binding": "angular",
+  "catalog": {
+    "group": "Actions",
+    "summary": "Main action with a menu of alternatives."
+  },
+  "axes": {
+    "tone": [
+      "accent",
+      "secondary",
+      "success",
+      "warning",
+      "danger"
+    ],
+    "variant": [
+      "solid",
+      "outline",
+      "ghost"
+    ],
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ]
+  },
+  "members": {
+    "splitButton": {
+      "nativeElement": "div",
+      "defaults": {
+        "tone": "accent",
+        "variant": "solid",
+        "size": "md",
+        "fullWidth": false,
+        "remember": false,
+        "disabled": false,
+        "loading": false
+      },
+      "capabilities": [
+        "open",
+        "selection",
+        "appearance",
+        "size",
+        "fullWidth",
+        "disabled",
+        "loading",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "open",
+        "disabled",
+        "loading"
+      ],
+      "parts": [
+        "root",
+        "primary",
+        "menu-trigger"
+      ]
+    }
+  },
+  "docs": {
+    "splitButton": {
+      "imports": {
+        "source": "import {\n  provideSplitButtonDefaults,\n  SlSplitButton,\n  SlSplitButtonChoices,\n  SlSplitButtonMenuTrigger,\n  SlSplitButtonPrimary,\n} from '@slotted/angular/split-button';\nimport { SlMenu, SlMenuItem, SlMenuRadioGroup } from '@slotted/angular/menu';",
+        "selector": "[slSplitButton]",
+        "exportAs": "slSplitButton"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "the consumer’s own element, with slSplitButton on it",
+          "required": true,
+          "purpose": "The group. It carries role=\"group\", data-ui=\"split-button\", the three appearance axes it hands to both halves, and data-disabled, data-loading and data-full-width. It paints the join; the chevron is the chevron-down Glyph element inside the menu trigger."
+        },
+        {
+          "part": "primary",
+          "element": "the consumer’s own button, with slSplitButtonPrimary on it — SlButton, extended",
+          "required": true,
+          "purpose": "The action. Everything about it is Button’s: start and end, type, loading with the width held, focusableWhenDisabled, the native attributes. The family adds the part name and folds the root’s disabled and loading into its own."
+        },
+        {
+          "part": "menu-trigger",
+          "element": "the consumer’s own button, with slSplitButtonMenuTrigger and [slMenuTriggerFor] on it — SlIconButton, extended, hosting slMenuTriggerFor",
+          "required": true,
+          "purpose": "The menu button. It carries aria-haspopup=\"menu\", aria-expanded and aria-controls from menu, the chevron from this family — content the consumer passes replaces it — and an accessible name the type makes mandatory. Square from the control height; it never shrinks."
+        }
+      ],
+      "api": [
+        {
+          "name": "tone",
+          "type": "'accent' | 'secondary' | 'success' | 'warning' | 'danger'",
+          "defaultValue": "accent",
+          "appliesTo": "slSplitButton",
+          "description": "The tone both halves are painted in. Resolved from the prop, then SplitButtonDefaultsProvider, then button’s own provider, then the contract"
+        },
+        {
+          "name": "variant",
+          "type": "'solid' | 'outline' | 'ghost'",
+          "defaultValue": "solid",
+          "appliesTo": "slSplitButton",
+          "description": "How the tone is painted on both halves. Between two solid halves the family paints the seam; outline and ghost share the edge the join leaves"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "slSplitButton",
+          "description": "The control step. The trigger is square from the same height"
+        },
+        {
+          "name": "fullWidth",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slSplitButton",
+          "description": "Whether the action takes the whole line. The trigger stays square either way"
+        },
+        {
+          "name": "remember",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slSplitButton",
+          "description": "Whether the choice in the menu becomes the action. On, the items inside the radio group carrying slSplitButtonChoices are bound to value and the page renders the primary’s label from it; off, the items are actions"
+        },
+        {
+          "name": "value",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slSplitButton",
+          "description": "The remembered value. Bound, the consumer owns it for the life of the component; unbound, the family owns it and starts from defaultValue"
+        },
+        {
+          "name": "defaultValue",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slSplitButton",
+          "description": "What an uncontrolled split button remembers first, read once"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slSplitButton",
+          "description": "Takes both halves out natively. Each half also accepts its own, which adds to the root’s"
+        },
+        {
+          "name": "loading",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slSplitButton",
+          "description": "The action is in flight: the primary shows button’s indicator with its width and name held, and the trigger is aria-disabled for the duration, still in the tab sequence and still painted"
+        },
+        {
+          "name": "open",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "sl-menu",
+          "description": "sl-menu’s own two-way model, untouched by the family. Bound, the consumer owns whether the menu shows"
+        },
+        {
+          "name": "defaultOpen",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "sl-menu",
+          "description": "sl-menu’s own uncontrolled start, untouched by the family"
+        },
+        {
+          "name": "side, align, size, closeOnSelect, mount, and the rest, on sl-menu",
+          "type": "sl-menu’s inputs",
+          "defaultValue": "menu’s",
+          "appliesTo": "sl-menu",
+          "description": "Every input of sl-menu is written on the consumer’s own sl-menu: the surface is menu’s and nothing of it is re-declared here"
+        },
+        {
+          "name": "type, loadingDelay, messages, focusableWhenDisabled, slButtonStart, slButtonEnd, on slSplitButtonPrimary",
+          "type": "SlButton’s inputs and slots",
+          "defaultValue": "SlButton’s",
+          "appliesTo": "slSplitButtonPrimary",
+          "description": "SlButton’s own inputs and content slots reach the action unchanged; only the three appearance axes are the root’s"
+        },
+        {
+          "name": "slMenuTriggerFor, on slSplitButtonMenuTrigger",
+          "type": "SlMenu",
+          "defaultValue": "—",
+          "appliesTo": "slSplitButtonMenuTrigger",
+          "description": "The menu this trigger opens, as on any menu trigger. Hosted by the component, so the consumer writes one attribute and the part name survives"
+        },
+        {
+          "name": "aria-label or aria-labelledby, on slSplitButtonMenuTrigger",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slSplitButtonMenuTrigger",
+          "description": "The menu button’s own name, distinct from the action’s. SlIconButton refuses to render without one in development: “More save options” beside “Save”"
+        }
+      ],
+      "composition": [
+        {
+          "name": "slSplitButton, slSplitButtonPrimary, slSplitButtonMenuTrigger",
+          "type": "directives on the consumer’s own elements",
+          "defaultValue": "—",
+          "appliesTo": "the consumer’s elements",
+          "description": "Each part is a directive on the element the consumer wrote — a div or a section, two buttons — so every attribute, listener and structural directive around them stays as written, and the part names survive the host bindings"
+        },
+        {
+          "name": "slSplitButtonChoices",
+          "type": "directive on sl-menu-radio-group",
+          "defaultValue": "—",
+          "appliesTo": "inside sl-menu, under remember",
+          "description": "Binds the consumer’s own radio group to the root’s value both ways. The group never owns the value: its request is forwarded and cancelled, and what it shows checked is written back from the root. It throws outside remember"
+        },
+        {
+          "name": "exportAs",
+          "type": "'slSplitButton' | 'slSplitButtonPrimary' | 'slSplitButtonMenuTrigger' | 'slSplitButtonChoices'",
+          "defaultValue": "—",
+          "appliesTo": "a template reference",
+          "description": "Reaches each instance; sl-menu’s own exportAs reaches its instance — toggle(open, reason) — as it does for any menu"
+        },
+        {
+          "name": "provideSplitButtonDefaults()",
+          "type": "(defaults: SplitButtonDefaults) => Provider",
+          "defaultValue": "—",
+          "appliesTo": "an injector",
+          "description": "The three decisions an application takes once, at the root or on one route. A split button that states an axis itself still wins, and provideButtonDefaults() is consulted after this one"
+        },
+        {
+          "name": "role",
+          "type": "string",
+          "defaultValue": "group",
+          "appliesTo": "slSplitButton",
+          "description": "Read from the host with HostAttributeToken before the host binding writes, so a consumer’s own survives; role=\"\" gives the group up inside a named one"
+        },
+        {
+          "name": "slMenuItem, slMenuRadioItem, slMenuGroup, slMenuSeparator, …",
+          "type": "menu’s directives",
+          "defaultValue": "—",
+          "appliesTo": "inside sl-menu",
+          "description": "Imported from menu as they are. Nothing of the surface is re-exported under this family’s name"
+        }
+      ],
+      "events": [
+        {
+          "name": "(openChangeRequest) and [(open)], on sl-menu",
+          "payload": "ChangeRequest<boolean>",
+          "when": "Before the menu opens or closes. The state is sl-menu’s own and the family adds no second owner — the same reasons in the same order: pointer, keyboard, escape, outsidePress, select, dismiss, programmatic."
+        },
+        {
+          "name": "(valueChange), on slSplitButton",
+          "payload": "ChangeRequest<string>",
+          "when": "Under remember, before the remembered value moves. The request carries the new value, the one it replaces, the reason — pointer or keyboard — the originating event, and cancel(). Nothing is emitted for a value equal to the one held."
+        },
+        {
+          "name": "(click), on the primary and the trigger",
+          "payload": "the element’s own events",
+          "when": "Whenever that button fires them. A busy or unavailable half refuses the activation in the capture phase, before the consumer’s listener; otherwise the consumer’s runs as written."
+        }
+      ],
+      "accessibility": [
+        "There is no APG split-button pattern. The action is the Button pattern’s button and the menu button is the Menu Button pattern’s (w3.org/WAI/ARIA/apg/patterns/menu-button/), each with its own tab stop — which is what every surveyed implementation does.",
+        "The trigger carries aria-haspopup=\"menu\", aria-expanded and, while open, aria-controls, all written by slMenuTriggerFor, which the component hosts; its accessible name is the consumer’s and SlIconButton refuses to render without one in development. A default string was declined: “More options” beside “Save” names the menu for no reader.",
+        "Enter and Space open the menu on the first item, ArrowDown on the first and ArrowUp on the last, from menu; Escape closes and returns focus to the trigger. ArrowDown on the action does nothing — a key that opens a surface from a button whose name says the action is a surprise.",
+        "disabled is the native attribute on both halves. loading keeps the trigger reachable and announces aria-disabled, so a reader who lands on it hears why nothing opens, while the primary announces its progress bar.",
+        "Under remember the alternatives are menuitemradio items with aria-checked, so a reader hears which strategy is the action and that choosing another persists — the honest semantics of a choice that changes what the next click does."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-control-border-color",
+    "--slotted-control-border-width",
+    "--slotted-control-radius",
+    "--slotted-disabled-border",
+    "--slotted-split-button-radius",
+    "--slotted-tone-accent-solid-active",
+    "--slotted-tone-danger-solid-active",
+    "--slotted-tone-secondary-solid-active",
+    "--slotted-tone-success-solid-active",
+    "--slotted-tone-warning-solid-active"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One split button with every axis on it, driven by the controls below the canvas. Tab reaches the action, then the menu button: two controls, two stops, one shape.",
+      "language": "html",
+      "source": "<div slSplitButton>\n  <button slSplitButtonPrimary (click)=\"save()\">Salvar</button>\n  <button\n    slSplitButtonMenuTrigger\n    [slMenuTriggerFor]=\"more\"\n    aria-label=\"Mais opções de salvar\"\n  ></button>\n  <sl-menu #more>\n    <button slMenuItem (select)=\"saveDraft()\">Salvar como rascunho</button>\n    <button slMenuItem (select)=\"saveAndClose()\">Salvar e fechar</button>\n  </sl-menu>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "variants",
+      "title": "Five tones, three variants, one seam",
+      "note": "Every tone and variant is button’s, handed to both halves at once. Between two solid halves the seam is the tone’s darkest step, painted on the trigger’s leading edge — the one edge the join leaves in the shared column.",
+      "language": "html",
+      "source": "<div slSplitButton tone=\"danger\" variant=\"outline\">\n  <button slSplitButtonPrimary (click)=\"remove()\">Excluir</button>\n  <button\n    slSplitButtonMenuTrigger\n    [slMenuTriggerFor]=\"more\"\n    aria-label=\"Mais opções de exclusão\"\n  ></button>\n  <sl-menu #more>\n    <button slMenuItem (select)=\"archive()\">Arquivar em vez disso</button>\n  </sl-menu>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sizes",
+      "title": "Three steps, one control tall",
+      "note": "Both halves read the control scale, so the bar is exactly as tall as the field beside it and the trigger stays square at every step. Switch the density in the toolbar: the pair moves together.",
+      "language": "html",
+      "source": "<div slSplitButton size=\"sm\">\n  <button slSplitButtonPrimary (click)=\"save()\">Salvar</button>\n  <button\n    slSplitButtonMenuTrigger\n    [slMenuTriggerFor]=\"more\"\n    aria-label=\"Mais opções de salvar\"\n  ></button>\n  <sl-menu #more>\n    <button slMenuItem (select)=\"saveDraft()\">Salvar como rascunho</button>\n  </sl-menu>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "remember",
+      "title": "The choice becomes the action",
+      "note": "Under remember the alternatives are radio items bound to the family’s value, and the page renders the action’s label from it — the merge button whose strategy a repository remembers. Choose one, then read the primary. Without remember the items are actions.",
+      "language": "html",
+      "source": "<div slSplitButton remember [value]=\"strategy()\" (valueChange)=\"strategy.set($event.value)\">\n  <button slSplitButtonPrimary (click)=\"merge(strategy())\">{{ labels[strategy()] }}</button>\n  <button\n    slSplitButtonMenuTrigger\n    [slMenuTriggerFor]=\"more\"\n    aria-label=\"Mais estratégias de merge\"\n  ></button>\n  <sl-menu #more>\n    <sl-menu-radio-group slSplitButtonChoices>\n      <button slMenuRadioItem value=\"merge\">Criar um commit de merge</button>\n      <button slMenuRadioItem value=\"squash\">Squash e merge</button>\n      <button slMenuRadioItem value=\"rebase\">Rebase e merge</button>\n    </sl-menu-radio-group>\n  </sl-menu>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "loading",
+      "title": "The action in flight",
+      "note": "Press Salvar: the primary shows button’s indicator with its width and name held, and the menu button waits with it — aria-disabled, still focusable, still painted in the tone, refusing the click and the arrow keys. The bar is one control that is busy.",
+      "language": "html",
+      "source": "<div slSplitButton [loading]=\"saving()\">\n  <button slSplitButtonPrimary (click)=\"save()\">Salvar</button>\n  <button\n    slSplitButtonMenuTrigger\n    [slMenuTriggerFor]=\"more\"\n    aria-label=\"Mais opções de salvar\"\n  ></button>\n  <sl-menu #more>\n    <button slMenuItem (select)=\"saveDraft()\">Salvar como rascunho</button>\n  </sl-menu>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "Every state the contract declares",
+      "note": "disabled on the root takes both halves out natively; disabled on one half leaves the other an action. Hover, press and focus are button’s, and only focus is raised above the seam, because a hover repaints a fill and never an edge.",
+      "language": "html",
+      "source": "<div slSplitButton>\n  <button slSplitButtonPrimary disabled>Mesclar</button>\n  <button\n    slSplitButtonMenuTrigger\n    [slMenuTriggerFor]=\"more\"\n    aria-label=\"Mais opções de merge\"\n  ></button>\n  <sl-menu #more>\n    <button slMenuItem (select)=\"closeRequest()\">Fechar sem mesclar</button>\n  </sl-menu>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "width",
+      "title": "The line, and a narrow room",
+      "note": "fullWidth gives the line to the action alone and the trigger stays square. In a narrow column the label wraps inside its own control, which is button’s rule, and the bar never pushes past the container.",
+      "language": "html",
+      "source": "<div slSplitButton fullWidth>\n  <button slSplitButtonPrimary (click)=\"order()\">Fazer pedido</button>\n  <button\n    slSplitButtonMenuTrigger\n    [slMenuTriggerFor]=\"more\"\n    aria-label=\"Mais opções de pedido\"\n  ></button>\n  <sl-menu #more>\n    <button slMenuItem (select)=\"schedule()\">Agendar entrega</button>\n  </sl-menu>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the family did not choose",
+      "note": "An icon before the label is SlButton’s slButtonStart slot and reaches the primary unchanged; a long translated action wraps rather than growing the bar; a right-to-left document puts the trigger at the other end of the action. Switch the direction in the toolbar.",
+      "language": "html",
+      "source": "<button slSplitButtonPrimary (click)=\"save()\">\n  <ng-icon slButtonStart name=\"lucideSave\" />\n  Salvar\n</button>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Defaults once, the consumer’s own elements, and the handle",
+      "note": "provideSplitButtonDefaults() sets tone, variant and size for every split button under an injector, and provideButtonDefaults() is consulted after it. The root is a section here and the action carries an analytics attribute, because each part is a directive on the consumer’s own element; the second button opens the menu through sl-menu’s own instance, carrying the programmatic reason.",
+      "language": "html",
+      "source": "<!-- providers: [provideSplitButtonDefaults({ size: 'sm', variant: 'outline' })] -->\n<section slSplitButton>\n  <button slSplitButtonPrimary data-track=\"save\" (click)=\"save()\">Salvar</button>\n  <button\n    slSplitButtonMenuTrigger\n    [slMenuTriggerFor]=\"more\"\n    aria-label=\"Mais opções de salvar\"\n  ></button>\n  <sl-menu #more=\"slMenu\">\n    <button slMenuItem (select)=\"saveDraft()\">Salvar como rascunho</button>\n  </sl-menu>\n</section>\n<button slButton variant=\"ghost\" (click)=\"more.toggle(true, 'programmatic')\">\n  Abrir pelo handle\n</button>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "The keyboard, key by key",
+      "note": "Tab reaches the action, then the menu button. Space and Enter run the action from the first and open the menu from the second; ArrowDown opens on the first item, ArrowUp on the last; Escape closes and returns to the trigger. ArrowDown on the action does nothing, and the line below says what the family saw.",
+      "language": "html",
+      "source": "<sl-menu #more (openChangeRequest)=\"log($event.reason)\">\n  <button slMenuItem (select)=\"saveDraft()\">Salvar como rascunho</button>\n</sl-menu>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/docs/split-button.md

@@ -0,0 +1,275 @@
+<!-- index: ./index.md -->
+# split-button
+
+`data-ui="split-button"` · Main action with a menu of alternatives.
+
+## Import
+
+```ts
+import {
+  provideSplitButtonDefaults,
+  SlSplitButton,
+  SlSplitButtonChoices,
+  SlSplitButtonMenuTrigger,
+  SlSplitButtonPrimary,
+} from '@slotted/angular/split-button';
+import { SlMenu, SlMenuItem, SlMenuRadioGroup } from '@slotted/angular/menu';
+```
+
+Selector: `[slSplitButton]` · exportAs: `slSplitButton`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div slSplitButton>
+  <button slSplitButtonPrimary (click)="save()">Salvar</button>
+  <button
+    slSplitButtonMenuTrigger
+    [slMenuTriggerFor]="more"
+    aria-label="Mais opções de salvar"
+  ></button>
+  <sl-menu #more>
+    <button slMenuItem (select)="saveDraft()">Salvar como rascunho</button>
+    <button slMenuItem (select)="saveAndClose()">Salvar e fechar</button>
+  </sl-menu>
+</div>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the consumer’s own element, with slSplitButton on it | yes |
+| `primary` | the consumer’s own button, with slSplitButtonPrimary on it — SlButton, extended | yes |
+| `menu-trigger` | the consumer’s own button, with slSplitButtonMenuTrigger and [slMenuTriggerFor] on it — SlIconButton, extended, hosting slMenuTriggerFor | yes |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `tone` | `'accent' \| 'secondary' \| 'success' \| 'warning' \| 'danger'` | accent | slSplitButton | The tone both halves are painted in. Resolved from the prop, then SplitButtonDefaultsProvider, then button’s own provider, then the contract |
+| `variant` | `'solid' \| 'outline' \| 'ghost'` | solid | slSplitButton | How the tone is painted on both halves. Between two solid halves the family paints the seam; outline and ghost share the edge the join leaves |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | slSplitButton | The control step. The trigger is square from the same height |
+| `fullWidth` | `boolean` | false | slSplitButton | Whether the action takes the whole line. The trigger stays square either way |
+| `remember` | `boolean` | false | slSplitButton | Whether the choice in the menu becomes the action. On, the items inside the radio group carrying slSplitButtonChoices are bound to value and the page renders the primary’s label from it; off, the items are actions |
+| `value` | `string` | — | slSplitButton | The remembered value. Bound, the consumer owns it for the life of the component; unbound, the family owns it and starts from defaultValue |
+| `defaultValue` | `string` | — | slSplitButton | What an uncontrolled split button remembers first, read once |
+| `disabled` | `boolean` | false | slSplitButton | Takes both halves out natively. Each half also accepts its own, which adds to the root’s |
+| `loading` | `boolean` | false | slSplitButton | The action is in flight: the primary shows button’s indicator with its width and name held, and the trigger is aria-disabled for the duration, still in the tab sequence and still painted |
+| `open` | `boolean` | — | sl-menu | sl-menu’s own two-way model, untouched by the family. Bound, the consumer owns whether the menu shows |
+| `defaultOpen` | `boolean` | false | sl-menu | sl-menu’s own uncontrolled start, untouched by the family |
+| `side, align, size, closeOnSelect, mount, and the rest, on sl-menu` | `sl-menu’s inputs` | menu’s | sl-menu | Every input of sl-menu is written on the consumer’s own sl-menu: the surface is menu’s and nothing of it is re-declared here |
+| `type, loadingDelay, messages, focusableWhenDisabled, slButtonStart, slButtonEnd, on slSplitButtonPrimary` | `SlButton’s inputs and slots` | SlButton’s | slSplitButtonPrimary | SlButton’s own inputs and content slots reach the action unchanged; only the three appearance axes are the root’s |
+| `slMenuTriggerFor, on slSplitButtonMenuTrigger` | `SlMenu` | — | slSplitButtonMenuTrigger | The menu this trigger opens, as on any menu trigger. Hosted by the component, so the consumer writes one attribute and the part name survives |
+| `aria-label or aria-labelledby, on slSplitButtonMenuTrigger` | `string` | — | slSplitButtonMenuTrigger | The menu button’s own name, distinct from the action’s. SlIconButton refuses to render without one in development: “More save options” beside “Save” |
+| `slSplitButton, slSplitButtonPrimary, slSplitButtonMenuTrigger` | `directives on the consumer’s own elements` | — | the consumer’s elements | Each part is a directive on the element the consumer wrote — a div or a section, two buttons — so every attribute, listener and structural directive around them stays as written, and the part names survive the host bindings |
+| `slSplitButtonChoices` | `directive on sl-menu-radio-group` | — | inside sl-menu, under remember | Binds the consumer’s own radio group to the root’s value both ways. The group never owns the value: its request is forwarded and cancelled, and what it shows checked is written back from the root. It throws outside remember |
+| `exportAs` | `'slSplitButton' \| 'slSplitButtonPrimary' \| 'slSplitButtonMenuTrigger' \| 'slSplitButtonChoices'` | — | a template reference | Reaches each instance; sl-menu’s own exportAs reaches its instance — toggle(open, reason) — as it does for any menu |
+| `provideSplitButtonDefaults()` | `(defaults: SplitButtonDefaults) => Provider` | — | an injector | The three decisions an application takes once, at the root or on one route. A split button that states an axis itself still wins, and provideButtonDefaults() is consulted after this one |
+| `role` | `string` | group | slSplitButton | Read from the host with HostAttributeToken before the host binding writes, so a consumer’s own survives; role="" gives the group up inside a named one |
+| `slMenuItem, slMenuRadioItem, slMenuGroup, slMenuSeparator, …` | `menu’s directives` | — | inside sl-menu | Imported from menu as they are. Nothing of the surface is re-exported under this family’s name |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `(openChangeRequest) and [(open)], on sl-menu` | `ChangeRequest<boolean>` | Before the menu opens or closes. The state is sl-menu’s own and the family adds no second owner — the same reasons in the same order: pointer, keyboard, escape, outsidePress, select, dismiss, programmatic. |
+| `(valueChange), on slSplitButton` | `ChangeRequest<string>` | Under remember, before the remembered value moves. The request carries the new value, the one it replaces, the reason — pointer or keyboard — the originating event, and cancel(). Nothing is emitted for a value equal to the one held. |
+| `(click), on the primary and the trigger` | `the element’s own events` | Whenever that button fires them. A busy or unavailable half refuses the activation in the capture phase, before the consumer’s listener; otherwise the consumer’s runs as written. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `tone` | `accent`, `secondary`, `success`, `warning`, `danger` | `accent` |
+| `variant` | `solid`, `outline`, `ghost` | `solid` |
+| `size` | `sm`, `md`, `lg` | `md` |
+
+## Rules
+
+- There is no APG split-button pattern. The action is the Button pattern’s button and the menu button is the Menu Button pattern’s (w3.org/WAI/ARIA/apg/patterns/menu-button/), each with its own tab stop — which is what every surveyed implementation does.
+- The trigger carries aria-haspopup="menu", aria-expanded and, while open, aria-controls, all written by slMenuTriggerFor, which the component hosts; its accessible name is the consumer’s and SlIconButton refuses to render without one in development. A default string was declined: “More options” beside “Save” names the menu for no reader.
+- Enter and Space open the menu on the first item, ArrowDown on the first and ArrowUp on the last, from menu; Escape closes and returns focus to the trigger. ArrowDown on the action does nothing — a key that opens a surface from a button whose name says the action is a surprise.
+- disabled is the native attribute on both halves. loading keeps the trigger reachable and announces aria-disabled, so a reader who lands on it hears why nothing opens, while the primary announces its progress bar.
+- Under remember the alternatives are menuitemradio items with aria-checked, so a reader hears which strategy is the action and that choosing another persists — the honest semantics of a choice that changes what the next click does.
+
+## Tokens
+
+`--slotted-control-border-color`, `--slotted-control-border-width`, `--slotted-control-radius`, `--slotted-disabled-border`, `--slotted-split-button-radius`, `--slotted-tone-accent-solid-active`, `--slotted-tone-danger-solid-active`, `--slotted-tone-secondary-solid-active`, `--slotted-tone-success-solid-active`, `--slotted-tone-warning-solid-active`
+
+## Examples
+
+### Five tones, three variants, one seam
+
+Every tone and variant is button’s, handed to both halves at once. Between two solid halves the seam is the tone’s darkest step, painted on the trigger’s leading edge — the one edge the join leaves in the shared column.
+
+Excerpt — not a complete module
+
+```html
+<div slSplitButton tone="danger" variant="outline">
+  <button slSplitButtonPrimary (click)="remove()">Excluir</button>
+  <button
+    slSplitButtonMenuTrigger
+    [slMenuTriggerFor]="more"
+    aria-label="Mais opções de exclusão"
+  ></button>
+  <sl-menu #more>
+    <button slMenuItem (select)="archive()">Arquivar em vez disso</button>
+  </sl-menu>
+</div>
+```
+
+### Three steps, one control tall
+
+Both halves read the control scale, so the bar is exactly as tall as the field beside it and the trigger stays square at every step. Switch the density in the toolbar: the pair moves together.
+
+Excerpt — not a complete module
+
+```html
+<div slSplitButton size="sm">
+  <button slSplitButtonPrimary (click)="save()">Salvar</button>
+  <button
+    slSplitButtonMenuTrigger
+    [slMenuTriggerFor]="more"
+    aria-label="Mais opções de salvar"
+  ></button>
+  <sl-menu #more>
+    <button slMenuItem (select)="saveDraft()">Salvar como rascunho</button>
+  </sl-menu>
+</div>
+```
+
+### The choice becomes the action
+
+Under remember the alternatives are radio items bound to the family’s value, and the page renders the action’s label from it — the merge button whose strategy a repository remembers. Choose one, then read the primary. Without remember the items are actions.
+
+Excerpt — not a complete module
+
+```html
+<div slSplitButton remember [value]="strategy()" (valueChange)="strategy.set($event.value)">
+  <button slSplitButtonPrimary (click)="merge(strategy())">{{ labels[strategy()] }}</button>
+  <button
+    slSplitButtonMenuTrigger
+    [slMenuTriggerFor]="more"
+    aria-label="Mais estratégias de merge"
+  ></button>
+  <sl-menu #more>
+    <sl-menu-radio-group slSplitButtonChoices>
+      <button slMenuRadioItem value="merge">Criar um commit de merge</button>
+      <button slMenuRadioItem value="squash">Squash e merge</button>
+      <button slMenuRadioItem value="rebase">Rebase e merge</button>
+    </sl-menu-radio-group>
+  </sl-menu>
+</div>
+```
+
+### The action in flight
+
+Press Salvar: the primary shows button’s indicator with its width and name held, and the menu button waits with it — aria-disabled, still focusable, still painted in the tone, refusing the click and the arrow keys. The bar is one control that is busy.
+
+Excerpt — not a complete module
+
+```html
+<div slSplitButton [loading]="saving()">
+  <button slSplitButtonPrimary (click)="save()">Salvar</button>
+  <button
+    slSplitButtonMenuTrigger
+    [slMenuTriggerFor]="more"
+    aria-label="Mais opções de salvar"
+  ></button>
+  <sl-menu #more>
+    <button slMenuItem (select)="saveDraft()">Salvar como rascunho</button>
+  </sl-menu>
+</div>
+```
+
+### Every state the contract declares
+
+disabled on the root takes both halves out natively; disabled on one half leaves the other an action. Hover, press and focus are button’s, and only focus is raised above the seam, because a hover repaints a fill and never an edge.
+
+Excerpt — not a complete module
+
+```html
+<div slSplitButton>
+  <button slSplitButtonPrimary disabled>Mesclar</button>
+  <button
+    slSplitButtonMenuTrigger
+    [slMenuTriggerFor]="more"
+    aria-label="Mais opções de merge"
+  ></button>
+  <sl-menu #more>
+    <button slMenuItem (select)="closeRequest()">Fechar sem mesclar</button>
+  </sl-menu>
+</div>
+```
+
+### The line, and a narrow room
+
+fullWidth gives the line to the action alone and the trigger stays square. In a narrow column the label wraps inside its own control, which is button’s rule, and the bar never pushes past the container.
+
+Excerpt — not a complete module
+
+```html
+<div slSplitButton fullWidth>
+  <button slSplitButtonPrimary (click)="order()">Fazer pedido</button>
+  <button
+    slSplitButtonMenuTrigger
+    [slMenuTriggerFor]="more"
+    aria-label="Mais opções de pedido"
+  ></button>
+  <sl-menu #more>
+    <button slMenuItem (select)="schedule()">Agendar entrega</button>
+  </sl-menu>
+</div>
+```
+
+### Content the family did not choose
+
+An icon before the label is SlButton’s slButtonStart slot and reaches the primary unchanged; a long translated action wraps rather than growing the bar; a right-to-left document puts the trigger at the other end of the action. Switch the direction in the toolbar.
+
+Excerpt — not a complete module
+
+```html
+<button slSplitButtonPrimary (click)="save()">
+  <ng-icon slButtonStart name="lucideSave" />
+  Salvar
+</button>
+```
+
+### Defaults once, the consumer’s own elements, and the handle
+
+provideSplitButtonDefaults() sets tone, variant and size for every split button under an injector, and provideButtonDefaults() is consulted after it. The root is a section here and the action carries an analytics attribute, because each part is a directive on the consumer’s own element; the second button opens the menu through sl-menu’s own instance, carrying the programmatic reason.
+
+Excerpt — not a complete module
+
+```html
+<!-- providers: [provideSplitButtonDefaults({ size: 'sm', variant: 'outline' })] -->
+<section slSplitButton>
+  <button slSplitButtonPrimary data-track="save" (click)="save()">Salvar</button>
+  <button
+    slSplitButtonMenuTrigger
+    [slMenuTriggerFor]="more"
+    aria-label="Mais opções de salvar"
+  ></button>
+  <sl-menu #more="slMenu">
+    <button slMenuItem (select)="saveDraft()">Salvar como rascunho</button>
+  </sl-menu>
+</section>
+<button slButton variant="ghost" (click)="more.toggle(true, 'programmatic')">
+  Abrir pelo handle
+</button>
+```
+
+### The keyboard, key by key
+
+Tab reaches the action, then the menu button. Space and Enter run the action from the first and open the menu from the second; ArrowDown opens on the first item, ArrowUp on the last; Escape closes and returns to the trigger. ArrowDown on the action does nothing, and the line below says what the family saw.
+
+Excerpt — not a complete module
+
+```html
+<sl-menu #more (openChangeRequest)="log($event.reason)">
+  <button slMenuItem (select)="saveDraft()">Salvar como rascunho</button>
+</sl-menu>
+```