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

package/dist/docs/split-button.json

@@ -0,0 +1,352 @@
+{
+  "family": "split-button",
+  "ui": "split-button",
+  "binding": "react",
+  "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  SplitButton,\n  SplitButtonChoices,\n  SplitButtonMenu,\n  SplitButtonMenuTrigger,\n  SplitButtonPrimary,\n} from '@slotted/react';\nimport { MenuContent, MenuItem, MenuRadioItem } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div, or the element render returns",
+          "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": "button — button’s Button, carrying this family’s part",
+          "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": "button — button’s IconButton, rendered as menu’s trigger",
+          "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": "SplitButton",
+          "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": "SplitButton",
+          "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": "SplitButton",
+          "description": "The control step. The trigger is square from the same height"
+        },
+        {
+          "name": "fullWidth",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "SplitButton",
+          "description": "Whether the action takes the whole line. The trigger stays square either way"
+        },
+        {
+          "name": "remember",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "SplitButton",
+          "description": "Whether the choice in the menu becomes the action. On, the items inside SplitButtonChoices are radio items bound to value and the page renders the primary’s label from it; off, the items are actions"
+        },
+        {
+          "name": "value",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "SplitButton",
+          "description": "The remembered value. Present means the consumer owns it, for the life of the component; absent, the family owns it and starts from defaultValue"
+        },
+        {
+          "name": "defaultValue",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "SplitButton",
+          "description": "What an uncontrolled split button remembers first, read once"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "SplitButton",
+          "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": "SplitButton",
+          "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": "SplitButtonMenu",
+          "description": "menu’s own controlled value, forwarded unchanged. Present means the consumer owns whether the menu shows"
+        },
+        {
+          "name": "defaultOpen",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "SplitButtonMenu",
+          "description": "menu’s own uncontrolled start, forwarded unchanged"
+        },
+        {
+          "name": "side, align, size, closeOnSelect, mount, and the rest, on SplitButtonMenu",
+          "type": "MenuProps",
+          "defaultValue": "menu’s",
+          "appliesTo": "SplitButtonMenu",
+          "description": "Every prop of Menu reaches the menu unchanged: the surface is menu’s and nothing of it is re-declared here"
+        },
+        {
+          "name": "start, end, type, loadingDelay, messages, focusableWhenDisabled, on SplitButtonPrimary",
+          "type": "ButtonProps",
+          "defaultValue": "Button’s",
+          "appliesTo": "SplitButtonPrimary",
+          "description": "Button’s own props reach the action unchanged; only the three appearance axes are the root’s"
+        },
+        {
+          "name": "aria-label or aria-labelledby, on SplitButtonMenuTrigger",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "SplitButtonMenuTrigger",
+          "description": "The menu button’s own name, distinct from the action’s, and mandatory at the type level: “More save options” beside “Save”"
+        }
+      ],
+      "composition": [
+        {
+          "name": "render",
+          "type": "(props) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "SplitButton, SplitButtonPrimary, SplitButtonMenuTrigger",
+          "description": "Substitutes the root or either half and hands it every attribute the family was going to write, the part name included. The trigger’s render is composed with menu’s, so the anchor the positioner measures is kept"
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement> | Ref<HTMLButtonElement> | Ref<MenuHandle>",
+          "defaultValue": "—",
+          "appliesTo": "SplitButton, SplitButtonPrimary, SplitButtonMenuTrigger, SplitButtonMenu",
+          "description": "Reaches each element, and on SplitButtonMenu reaches menu’s handle: open(), close() and focus()"
+        },
+        {
+          "name": "SplitButtonChoices",
+          "type": "MenuRadioGroupProps minus value",
+          "defaultValue": "—",
+          "appliesTo": "inside MenuContent, under remember",
+          "description": "menu’s radio group bound to the family’s value. Its children are MenuRadioItems, and it throws outside remember rather than holding a value nobody reads"
+        },
+        {
+          "name": "SplitButtonDefaultsProvider",
+          "type": "{ tone, variant, size }",
+          "defaultValue": "—",
+          "appliesTo": "a subtree",
+          "description": "The three decisions an application takes once. A split button that states an axis itself still wins, and button’s own provider is consulted after this one"
+        },
+        {
+          "name": "useSplitButton()",
+          "type": "() => SplitButtonContextValue",
+          "defaultValue": "—",
+          "appliesTo": "inside a SplitButton",
+          "description": "What a half reads: disabled, loading, remember, the value and select(). It throws outside a root"
+        },
+        {
+          "name": "MenuContent, MenuItem, MenuRadioItem, MenuGroup, MenuSeparator, …",
+          "type": "menu’s parts",
+          "defaultValue": "—",
+          "appliesTo": "inside SplitButtonMenu",
+          "description": "Imported from menu as they are. Nothing of the surface is re-exported under this family’s name"
+        }
+      ],
+      "events": [
+        {
+          "name": "onOpenChange, on SplitButtonMenu",
+          "payload": "(open: boolean, request: MenuChangeRequest)",
+          "when": "Before the menu opens or closes. It is menu’s own request — the same reasons in the same order: pointer, keyboard, escape, outsidePress, select, dismiss, programmatic — so a handler moved from a menu changes nothing."
+        },
+        {
+          "name": "onValueChange, on SplitButton",
+          "payload": "(value: string, request: 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": "onClick, on SplitButtonPrimary and SplitButtonMenuTrigger",
+          "payload": "the element’s own events",
+          "when": "Whenever that button fires them. The consumer’s handler runs first, and always runs; preventDefault() in the primary’s refuses the activation, and in the trigger’s it is menu’s composition rule that holds."
+        }
+      ],
+      "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 menu; its accessible name is the consumer’s and the type refuses a trigger without one. 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": "tsx",
+      "source": "<SplitButton>\n  <SplitButtonPrimary onClick={save}>Salvar</SplitButtonPrimary>\n  <SplitButtonMenu>\n    <SplitButtonMenuTrigger aria-label=\"Mais opções de salvar\" />\n    <MenuContent>\n      <MenuItem onSelect={saveDraft}>Salvar como rascunho</MenuItem>\n      <MenuItem onSelect={saveAndClose}>Salvar e fechar</MenuItem>\n    </MenuContent>\n  </SplitButtonMenu>\n</SplitButton>;\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": "tsx",
+      "source": "<SplitButton tone=\"danger\" variant=\"outline\">\n  <SplitButtonPrimary onClick={remove}>Excluir</SplitButtonPrimary>\n  <SplitButtonMenu>\n    <SplitButtonMenuTrigger aria-label=\"Mais opções de exclusão\" />\n    <MenuContent>\n      <MenuItem onSelect={archive}>Arquivar em vez disso</MenuItem>\n    </MenuContent>\n  </SplitButtonMenu>\n</SplitButton>;\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": "tsx",
+      "source": "<SplitButton size=\"sm\">\n  <SplitButtonPrimary onClick={save}>Salvar</SplitButtonPrimary>\n  <SplitButtonMenu>\n    <SplitButtonMenuTrigger aria-label=\"Mais opções de salvar\" />\n    <MenuContent>\n      <MenuItem onSelect={saveDraft}>Salvar como rascunho</MenuItem>\n    </MenuContent>\n  </SplitButtonMenu>\n</SplitButton>;\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": "tsx",
+      "source": "const [strategy, setStrategy] = useState('squash');\n\n<SplitButton onValueChange={setStrategy} remember value={strategy}>\n  <SplitButtonPrimary onClick={() => merge(strategy)}>{labels[strategy]}</SplitButtonPrimary>\n  <SplitButtonMenu>\n    <SplitButtonMenuTrigger aria-label=\"Mais estratégias de merge\" />\n    <MenuContent>\n      <SplitButtonChoices>\n        <MenuRadioItem value=\"merge\">Criar um commit de merge</MenuRadioItem>\n        <MenuRadioItem value=\"squash\">Squash e merge</MenuRadioItem>\n        <MenuRadioItem value=\"rebase\">Rebase e merge</MenuRadioItem>\n      </SplitButtonChoices>\n    </MenuContent>\n  </SplitButtonMenu>\n</SplitButton>;\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": "tsx",
+      "source": "<SplitButton loading={saving}>\n  <SplitButtonPrimary onClick={save}>Salvar</SplitButtonPrimary>\n  <SplitButtonMenu>\n    <SplitButtonMenuTrigger aria-label=\"Mais opções de salvar\" />\n    <MenuContent>\n      <MenuItem onSelect={saveDraft}>Salvar como rascunho</MenuItem>\n    </MenuContent>\n  </SplitButtonMenu>\n</SplitButton>;\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": "tsx",
+      "source": "<SplitButton>\n  <SplitButtonPrimary disabled>Mesclar</SplitButtonPrimary>\n  <SplitButtonMenu>\n    <SplitButtonMenuTrigger aria-label=\"Mais opções de merge\" />\n    <MenuContent>\n      <MenuItem onSelect={closeRequest}>Fechar sem mesclar</MenuItem>\n    </MenuContent>\n  </SplitButtonMenu>\n</SplitButton>;\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": "tsx",
+      "source": "<SplitButton fullWidth>\n  <SplitButtonPrimary onClick={order}>Fazer pedido</SplitButtonPrimary>\n  <SplitButtonMenu>\n    <SplitButtonMenuTrigger aria-label=\"Mais opções de pedido\" />\n    <MenuContent>\n      <MenuItem onSelect={schedule}>Agendar entrega</MenuItem>\n    </MenuContent>\n  </SplitButtonMenu>\n</SplitButton>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the family did not choose",
+      "note": "An icon before the label is Button’s start 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": "tsx",
+      "source": "<SplitButtonPrimary onClick={save} start={<Save size={16} />}>\n  Salvar\n</SplitButtonPrimary>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Defaults once, the consumer’s own elements, and the handle",
+      "note": "The provider sets tone, variant and size for every split button under it, and button’s own provider is consulted after it. render substitutes the root and either half and keeps the part; the ref on SplitButtonMenu is menu’s handle — open(), close(), focus().",
+      "language": "tsx",
+      "source": "<SplitButtonDefaultsProvider size=\"sm\" variant=\"outline\">\n  <SplitButton render={(props) => <section {...props} />}>\n    <SplitButtonPrimary render={(props) => <button {...props} data-track=\"save\" />}>\n      Salvar\n    </SplitButtonPrimary>\n    <SplitButtonMenu ref={menu}>\n      <SplitButtonMenuTrigger aria-label=\"Mais opções de salvar\" />\n      <MenuContent>\n        <MenuItem onSelect={saveDraft}>Salvar como rascunho</MenuItem>\n      </MenuContent>\n    </SplitButtonMenu>\n  </SplitButton>\n</SplitButtonDefaultsProvider>;\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.",
+      "language": "tsx",
+      "source": "<SplitButtonMenu onOpenChange={(open, request) => log(request.reason)}>\n  <SplitButtonMenuTrigger aria-label=\"Mais opções de salvar\" />\n  <MenuContent>\n    <MenuItem onSelect={saveDraft}>Salvar como rascunho</MenuItem>\n  </MenuContent>\n</SplitButtonMenu>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/dist/docs/split-button.md

@@ -0,0 +1,260 @@
+<!-- index: ./index.md -->
+# split-button
+
+`data-ui="split-button"` · Main action with a menu of alternatives.
+
+## Import
+
+```tsx
+import {
+  SplitButton,
+  SplitButtonChoices,
+  SplitButtonMenu,
+  SplitButtonMenuTrigger,
+  SplitButtonPrimary,
+} from '@slotted/react';
+import { MenuContent, MenuItem, MenuRadioItem } from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<SplitButton>
+  <SplitButtonPrimary onClick={save}>Salvar</SplitButtonPrimary>
+  <SplitButtonMenu>
+    <SplitButtonMenuTrigger aria-label="Mais opções de salvar" />
+    <MenuContent>
+      <MenuItem onSelect={saveDraft}>Salvar como rascunho</MenuItem>
+      <MenuItem onSelect={saveAndClose}>Salvar e fechar</MenuItem>
+    </MenuContent>
+  </SplitButtonMenu>
+</SplitButton>;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div, or the element render returns | yes |
+| `primary` | button — button’s Button, carrying this family’s part | yes |
+| `menu-trigger` | button — button’s IconButton, rendered as menu’s trigger | yes |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `tone` | `'accent' \| 'secondary' \| 'success' \| 'warning' \| 'danger'` | accent | SplitButton | 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 | SplitButton | 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 | SplitButton | The control step. The trigger is square from the same height |
+| `fullWidth` | `boolean` | false | SplitButton | Whether the action takes the whole line. The trigger stays square either way |
+| `remember` | `boolean` | false | SplitButton | Whether the choice in the menu becomes the action. On, the items inside SplitButtonChoices are radio items bound to value and the page renders the primary’s label from it; off, the items are actions |
+| `value` | `string` | — | SplitButton | The remembered value. Present means the consumer owns it, for the life of the component; absent, the family owns it and starts from defaultValue |
+| `defaultValue` | `string` | — | SplitButton | What an uncontrolled split button remembers first, read once |
+| `disabled` | `boolean` | false | SplitButton | Takes both halves out natively. Each half also accepts its own, which adds to the root’s |
+| `loading` | `boolean` | false | SplitButton | 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` | — | SplitButtonMenu | menu’s own controlled value, forwarded unchanged. Present means the consumer owns whether the menu shows |
+| `defaultOpen` | `boolean` | false | SplitButtonMenu | menu’s own uncontrolled start, forwarded unchanged |
+| `side, align, size, closeOnSelect, mount, and the rest, on SplitButtonMenu` | `MenuProps` | menu’s | SplitButtonMenu | Every prop of Menu reaches the menu unchanged: the surface is menu’s and nothing of it is re-declared here |
+| `start, end, type, loadingDelay, messages, focusableWhenDisabled, on SplitButtonPrimary` | `ButtonProps` | Button’s | SplitButtonPrimary | Button’s own props reach the action unchanged; only the three appearance axes are the root’s |
+| `aria-label or aria-labelledby, on SplitButtonMenuTrigger` | `string` | — | SplitButtonMenuTrigger | The menu button’s own name, distinct from the action’s, and mandatory at the type level: “More save options” beside “Save” |
+| `render` | `(props) => ReactNode` | — | SplitButton, SplitButtonPrimary, SplitButtonMenuTrigger | Substitutes the root or either half and hands it every attribute the family was going to write, the part name included. The trigger’s render is composed with menu’s, so the anchor the positioner measures is kept |
+| `ref` | `Ref<HTMLDivElement> \| Ref<HTMLButtonElement> \| Ref<MenuHandle>` | — | SplitButton, SplitButtonPrimary, SplitButtonMenuTrigger, SplitButtonMenu | Reaches each element, and on SplitButtonMenu reaches menu’s handle: open(), close() and focus() |
+| `SplitButtonChoices` | `MenuRadioGroupProps minus value` | — | inside MenuContent, under remember | menu’s radio group bound to the family’s value. Its children are MenuRadioItems, and it throws outside remember rather than holding a value nobody reads |
+| `SplitButtonDefaultsProvider` | `{ tone, variant, size }` | — | a subtree | The three decisions an application takes once. A split button that states an axis itself still wins, and button’s own provider is consulted after this one |
+| `useSplitButton()` | `() => SplitButtonContextValue` | — | inside a SplitButton | What a half reads: disabled, loading, remember, the value and select(). It throws outside a root |
+| `MenuContent, MenuItem, MenuRadioItem, MenuGroup, MenuSeparator, …` | `menu’s parts` | — | inside SplitButtonMenu | Imported from menu as they are. Nothing of the surface is re-exported under this family’s name |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onOpenChange, on SplitButtonMenu` | `(open: boolean, request: MenuChangeRequest)` | Before the menu opens or closes. It is menu’s own request — the same reasons in the same order: pointer, keyboard, escape, outsidePress, select, dismiss, programmatic — so a handler moved from a menu changes nothing. |
+| `onValueChange, on SplitButton` | `(value: string, request: 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. |
+| `onClick, on SplitButtonPrimary and SplitButtonMenuTrigger` | `the element’s own events` | Whenever that button fires them. The consumer’s handler runs first, and always runs; preventDefault() in the primary’s refuses the activation, and in the trigger’s it is menu’s composition rule that holds. |
+
+## 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 menu; its accessible name is the consumer’s and the type refuses a trigger without one. 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
+
+```tsx
+<SplitButton tone="danger" variant="outline">
+  <SplitButtonPrimary onClick={remove}>Excluir</SplitButtonPrimary>
+  <SplitButtonMenu>
+    <SplitButtonMenuTrigger aria-label="Mais opções de exclusão" />
+    <MenuContent>
+      <MenuItem onSelect={archive}>Arquivar em vez disso</MenuItem>
+    </MenuContent>
+  </SplitButtonMenu>
+</SplitButton>;
+```
+
+### 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
+
+```tsx
+<SplitButton size="sm">
+  <SplitButtonPrimary onClick={save}>Salvar</SplitButtonPrimary>
+  <SplitButtonMenu>
+    <SplitButtonMenuTrigger aria-label="Mais opções de salvar" />
+    <MenuContent>
+      <MenuItem onSelect={saveDraft}>Salvar como rascunho</MenuItem>
+    </MenuContent>
+  </SplitButtonMenu>
+</SplitButton>;
+```
+
+### 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
+
+```tsx
+const [strategy, setStrategy] = useState('squash');
+
+<SplitButton onValueChange={setStrategy} remember value={strategy}>
+  <SplitButtonPrimary onClick={() => merge(strategy)}>{labels[strategy]}</SplitButtonPrimary>
+  <SplitButtonMenu>
+    <SplitButtonMenuTrigger aria-label="Mais estratégias de merge" />
+    <MenuContent>
+      <SplitButtonChoices>
+        <MenuRadioItem value="merge">Criar um commit de merge</MenuRadioItem>
+        <MenuRadioItem value="squash">Squash e merge</MenuRadioItem>
+        <MenuRadioItem value="rebase">Rebase e merge</MenuRadioItem>
+      </SplitButtonChoices>
+    </MenuContent>
+  </SplitButtonMenu>
+</SplitButton>;
+```
+
+### 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
+
+```tsx
+<SplitButton loading={saving}>
+  <SplitButtonPrimary onClick={save}>Salvar</SplitButtonPrimary>
+  <SplitButtonMenu>
+    <SplitButtonMenuTrigger aria-label="Mais opções de salvar" />
+    <MenuContent>
+      <MenuItem onSelect={saveDraft}>Salvar como rascunho</MenuItem>
+    </MenuContent>
+  </SplitButtonMenu>
+</SplitButton>;
+```
+
+### 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
+
+```tsx
+<SplitButton>
+  <SplitButtonPrimary disabled>Mesclar</SplitButtonPrimary>
+  <SplitButtonMenu>
+    <SplitButtonMenuTrigger aria-label="Mais opções de merge" />
+    <MenuContent>
+      <MenuItem onSelect={closeRequest}>Fechar sem mesclar</MenuItem>
+    </MenuContent>
+  </SplitButtonMenu>
+</SplitButton>;
+```
+
+### 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
+
+```tsx
+<SplitButton fullWidth>
+  <SplitButtonPrimary onClick={order}>Fazer pedido</SplitButtonPrimary>
+  <SplitButtonMenu>
+    <SplitButtonMenuTrigger aria-label="Mais opções de pedido" />
+    <MenuContent>
+      <MenuItem onSelect={schedule}>Agendar entrega</MenuItem>
+    </MenuContent>
+  </SplitButtonMenu>
+</SplitButton>;
+```
+
+### Content the family did not choose
+
+An icon before the label is Button’s start 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
+
+```tsx
+<SplitButtonPrimary onClick={save} start={<Save size={16} />}>
+  Salvar
+</SplitButtonPrimary>;
+```
+
+### Defaults once, the consumer’s own elements, and the handle
+
+The provider sets tone, variant and size for every split button under it, and button’s own provider is consulted after it. render substitutes the root and either half and keeps the part; the ref on SplitButtonMenu is menu’s handle — open(), close(), focus().
+
+Excerpt — not a complete module
+
+```tsx
+<SplitButtonDefaultsProvider size="sm" variant="outline">
+  <SplitButton render={(props) => <section {...props} />}>
+    <SplitButtonPrimary render={(props) => <button {...props} data-track="save" />}>
+      Salvar
+    </SplitButtonPrimary>
+    <SplitButtonMenu ref={menu}>
+      <SplitButtonMenuTrigger aria-label="Mais opções de salvar" />
+      <MenuContent>
+        <MenuItem onSelect={saveDraft}>Salvar como rascunho</MenuItem>
+      </MenuContent>
+    </SplitButtonMenu>
+  </SplitButton>
+</SplitButtonDefaultsProvider>;
+```
+
+### 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.
+
+Excerpt — not a complete module
+
+```tsx
+<SplitButtonMenu onOpenChange={(open, request) => log(request.reason)}>
+  <SplitButtonMenuTrigger aria-label="Mais opções de salvar" />
+  <MenuContent>
+    <MenuItem onSelect={saveDraft}>Salvar como rascunho</MenuItem>
+  </MenuContent>
+</SplitButtonMenu>;
+```