@edux-design/buttons 0.2.0 → 0.3.1

package/dist/index.mjs

@@ -35,19 +35,19 @@ var IconButton = forwardRef(
       }
     }
     const defaults = "flex justify-center items-center focus:shadow-focus focus-visible:shadow-focus outline-none transition-all duration-300 ease-in-out rounded-full cursor-pointer";
-    const sizes = {
+    const sizes2 = {
       small: "size-control-sm text-sm",
       medium: "size-control-md text-base",
       large: "size-control-lg text-lg"
     };
     const variants = {
-      primary: "border-2 border-border-primary-emphasis bg-bg-primary-base text-white hover:bg-border-focus hover:text-fg-focus hover:border-border-emphasis hover:shadow-md active:bg-border-focus active:bg-bg-focus-overlay active:text-fg-focus",
+      primary: "border-2 border-border-primary-emphasis bg-bg-primary-base text-fg-invert hover:bg-border-focus hover:text-fg-focus hover:border-border-emphasis hover:shadow-md active:bg-border-focus active:bg-bg-focus-overlay active:text-fg-focus",
       secondary: "border-2 border-border-primary-base bg-bg-base text-fg-primary-emphasis hover:shadow-md hover:bg-bg-primary-subtle active:bg-bg-primary-subtle-90",
       bare: "bg-bg-base text-fg-primary-emphasis hover:bg-bg-minimal active:bg-bg-minimal-5",
       danger: "bg-bg-danger-base border-2 border-border-danger-emphasis text-white hover:bg-bg-danger-base-5 active:bg-bg-danger-base-10",
       disabled: "border-2 border-border-subtle bg-bg-inactive text-fg-inactive hover:no-underline cursor-not-allowed"
     };
-    const STYLES = cx(defaults, sizes[size], variants[variant], className);
+    const STYLES = cx(defaults, sizes2[size], variants[variant], className);
     return /* @__PURE__ */ jsx(
       "button",
       {
@@ -105,21 +105,21 @@ var Button = forwardRef2(
     }
     const defaults = "flex justify-center items-center gap-8 focus:shadow-focus focus-visible:shadow-focus outline-none transition-all duration-300 ease-in-out cursor-pointer";
     const fonts = "text-bold tracking-normal hover:underline hover:underline-offset-(--underline-offset-btn) active:underline active:underline-offset-(--underline-offset-btn)";
-    const sizes = {
+    const sizes2 = {
       small: "h-control-sm py-8 px-16 rounded-lg text-sm",
       medium: "h-control-md py-8 px-16 rounded-lg text-base",
       large: "h-control-lg py-8 px-16 rounded-lg text-lg"
     };
     const width = isStretched ? "w-full" : "w-fit-content";
     const variants = {
-      primary: "border-2 border-border-primary-emphasis bg-bg-primary-base text-white hover:bg-border-focus hover:text-fg-focus hover:border-border-emphasis hover:shadow-md active:bg-border-focus active:bg-bg-focus-overlay active:text-fg-focus",
+      primary: "border-2 border-border-primary-emphasis bg-bg-primary-base text-fg-invert hover:bg-border-focus hover:text-fg-focus hover:border-border-emphasis hover:shadow-md active:bg-border-focus active:bg-bg-focus-overlay active:text-fg-focus",
       secondary: "border-2 border-border-primary-base bg-bg-base text-fg-primary-emphasis hover:shadow-md hover:bg-bg-primary-subtle active:bg-bg-primary-subtle-90",
       bare: "bg-bg-base text-fg-primary-emphasis hover:bg-bg-minimal active:bg-bg-minimal-5",
       dangerBare: "bg-bg-base text-fg-danger-emphasis hover:bg-bg-danger-subtle active:bg-bg-danger-subtle",
       danger: "bg-bg-danger-base border-2 border-border-danger-emphasis text-white hover:bg-bg-danger-base-5 active:bg-bg-danger-base-10",
       disabled: "border-2 border-border-subtle bg-bg-inactive text-fg-inactive hover:no-underline"
     };
-    const STYLES = cx2(defaults, sizes[size], width, fonts, variants[variant]);
+    const STYLES = cx2(defaults, sizes2[size], width, fonts, variants[variant]);
     return /* @__PURE__ */ jsxs(
       "button",
       {
@@ -575,7 +575,7 @@ var ButtonCounter = forwardRef5(function ButtonCounter2({
     (next) => {
       const clamped = Math.min(max, Math.max(min, next));
       if (!isControlled) setInternalValue(clamped);
-      onChange == null ? void 0 : onChange(clamped);
+      onChange?.(clamped);
     },
     [isControlled, max, min, onChange]
   );
@@ -608,15 +608,15 @@ var ButtonCounter = forwardRef5(function ButtonCounter2({
   const CONTROL_SIZES = {
     small: {
       button: "size-control-sm text-sm",
-      display: "h-control-sm min-w-[48px] px-12 text-sm"
+      display: "h-control-sm min-w-48 px-12 text-sm"
     },
     medium: {
       button: "size-control-md text-base",
-      display: "h-control-md min-w-[56px] px-12 text-base"
+      display: "h-control-md min-w-56 px-12 text-base"
     },
     large: {
       button: "size-control-lg text-lg",
-      display: "h-control-lg min-w-[72px] px-16 text-lg"
+      display: "h-control-lg min-w-72 px-16 text-lg"
     }
   };
   const defaultsButton = "flex justify-center items-center focus:shadow-focus focus-visible:shadow-focus outline-none transition-all duration-300 ease-in-out cursor-pointer";
@@ -624,8 +624,8 @@ var ButtonCounter = forwardRef5(function ButtonCounter2({
   const width = isStretched ? "w-full" : "w-fit-content";
   const variants = {
     primary: {
-      button: "border-2 border-border-primary-emphasis bg-bg-primary-base text-white hover:bg-border-focus hover:text-fg-focus hover:border-border-emphasis hover:shadow-md active:bg-border-focus active:bg-bg-focus-overlay active:text-fg-focus",
-      display: "border-y-2 border-x-2 border-border-primary-emphasis bg-bg-primary-base text-white"
+      button: "border-2 border-border-primary-emphasis bg-bg-primary-base text-fg-invert hover:bg-border-focus hover:text-fg-focus hover:border-border-emphasis hover:shadow-md active:bg-border-focus active:bg-bg-focus-overlay active:text-fg-focus",
+      display: "border-y-2 border-x-2 border-border-primary-emphasis bg-bg-primary-base text-fg-invert"
     },
     secondary: {
       button: "border-2 border-border-primary-base bg-bg-base text-fg-primary-emphasis hover:shadow-md hover:bg-bg-primary-subtle active:bg-bg-primary-subtle-90",
@@ -675,8 +675,8 @@ var ButtonCounter = forwardRef5(function ButtonCounter2({
   const effectiveDecrementIcon = decrementIcon ?? startIcon ?? "-";
   const effectiveIncrementIcon = incrementIcon ?? endIcon ?? "+";
   const generatedValueId = useId();
-  const valueElementId = (inputProps == null ? void 0 : inputProps.id) ?? generatedValueId;
-  const valueAriaLabel = (inputProps == null ? void 0 : inputProps["aria-label"]) ?? ariaLabel ?? "Value";
+  const valueElementId = inputProps?.id ?? generatedValueId;
+  const valueAriaLabel = inputProps?.["aria-label"] ?? ariaLabel ?? "Value";
   const [draftValue, setDraftValue] = useState2(String(clampedValue));
   const [isEditing, setIsEditing] = useState2(false);
   const inputRef = useRef2(null);
@@ -709,18 +709,17 @@ var ButtonCounter = forwardRef5(function ButtonCounter2({
           {
             ...decrementButtonProps,
             type: "button",
-            "aria-label": (decrementButtonProps == null ? void 0 : decrementButtonProps["aria-label"]) ?? "Decrease",
+            "aria-label": decrementButtonProps?.["aria-label"] ?? "Decrease",
             "aria-controls": valueElementId,
             "aria-disabled": decrementDisabled,
             disabled: decrementDisabled,
             className: cx5(
               leftButtonStyles,
               decrementDisabled && variant !== "disabled" ? variants.disabled.button : null,
-              decrementButtonProps == null ? void 0 : decrementButtonProps.className
+              decrementButtonProps?.className
             ),
             onClick: (event) => {
-              var _a;
-              (_a = decrementButtonProps == null ? void 0 : decrementButtonProps.onClick) == null ? void 0 : _a.call(decrementButtonProps, event);
+              decrementButtonProps?.onClick?.(event);
               if (event.defaultPrevented) return;
               commitValue(clampedValue - step);
             },
@@ -739,34 +738,30 @@ var ButtonCounter = forwardRef5(function ButtonCounter2({
             "aria-label": valueAriaLabel,
             className: cx5(
               displayStyles,
-              "w-[44px] text-center outline-none bg-transparent text-fg-base",
+              "w-control-md text-center outline-none bg-transparent text-fg-base",
               "[appearance:textfield] [&::-webkit-outer-spin-button]:appearance-none [&::-webkit-inner-spin-button]:appearance-none [&::-webkit-outer-spin-button]:m-0 [&::-webkit-inner-spin-button]:m-0",
               "focus:shadow-focus focus-visible:shadow-focus focus:z-15 focus-within:z-15",
-              inputProps == null ? void 0 : inputProps.className
+              inputProps?.className
             ),
             value: draftValue,
             onChange: (event) => {
-              var _a;
-              (_a = inputProps == null ? void 0 : inputProps.onChange) == null ? void 0 : _a.call(inputProps, event);
+              inputProps?.onChange?.(event);
               if (event.defaultPrevented) return;
               setDraftValue(event.target.value);
             },
             onFocus: (event) => {
-              var _a;
-              (_a = inputProps == null ? void 0 : inputProps.onFocus) == null ? void 0 : _a.call(inputProps, event);
+              inputProps?.onFocus?.(event);
               if (event.defaultPrevented) return;
               setIsEditing(true);
             },
             onBlur: (event) => {
-              var _a;
-              (_a = inputProps == null ? void 0 : inputProps.onBlur) == null ? void 0 : _a.call(inputProps, event);
+              inputProps?.onBlur?.(event);
               if (event.defaultPrevented) return;
               setIsEditing(false);
               commitDraft();
             },
             onKeyDown: (event) => {
-              var _a;
-              (_a = inputProps == null ? void 0 : inputProps.onKeyDown) == null ? void 0 : _a.call(inputProps, event);
+              inputProps?.onKeyDown?.(event);
               if (event.defaultPrevented) return;
               if (event.key === "Enter") {
                 event.currentTarget.blur();
@@ -793,18 +788,17 @@ var ButtonCounter = forwardRef5(function ButtonCounter2({
           {
             ...incrementButtonProps,
             type: "button",
-            "aria-label": (incrementButtonProps == null ? void 0 : incrementButtonProps["aria-label"]) ?? "Increase",
+            "aria-label": incrementButtonProps?.["aria-label"] ?? "Increase",
             "aria-controls": valueElementId,
             "aria-disabled": incrementDisabled,
             disabled: incrementDisabled,
             className: cx5(
               rightButtonStyles,
               incrementDisabled && variant !== "disabled" ? variants.disabled.button : null,
-              incrementButtonProps == null ? void 0 : incrementButtonProps.className
+              incrementButtonProps?.className
             ),
             onClick: (event) => {
-              var _a;
-              (_a = incrementButtonProps == null ? void 0 : incrementButtonProps.onClick) == null ? void 0 : _a.call(incrementButtonProps, event);
+              incrementButtonProps?.onClick?.(event);
               if (event.defaultPrevented) return;
               commitValue(clampedValue + step);
             },
@@ -815,11 +809,279 @@ var ButtonCounter = forwardRef5(function ButtonCounter2({
     }
   );
 });
+
+// src/elements/Toolbar.tsx
+import {
+  forwardRef as forwardRef6,
+  useEffect as useEffect3,
+  useImperativeHandle,
+  useRef as useRef3
+} from "react";
+import { cx as cx6 } from "@edux-design/utils";
+import { jsx as jsx7 } from "react/jsx-runtime";
+function toolbarButtons(root) {
+  return Array.from(
+    root.querySelectorAll("[data-edux-toolbar-button]")
+  ).filter((button) => {
+    if (button.closest("[data-edux-toolbar]") !== root) return false;
+    if (button.disabled || button.getAttribute("aria-disabled") === "true")
+      return false;
+    for (let node = button; node; node = node.parentElement) {
+      if (node.hidden || node.hasAttribute("inert") || node.getAttribute("aria-hidden") === "true")
+        return false;
+      const styles = node.ownerDocument.defaultView?.getComputedStyle(node);
+      if (styles?.display === "none" || styles?.visibility === "hidden")
+        return false;
+      if (node === root) break;
+    }
+    return true;
+  });
+}
+var Toolbar = forwardRef6(
+  function Toolbar2({
+    keyboardNavigation = "native",
+    orientation = "horizontal",
+    loop = true,
+    className,
+    children,
+    onKeyDown,
+    onFocusCapture,
+    ...props
+  }, forwardedRef) {
+    const rootRef = useRef3(null);
+    useImperativeHandle(forwardedRef, () => rootRef.current);
+    const lastFocused = useRef3(null);
+    const originalTabIndexes = useRef3(
+      /* @__PURE__ */ new Map()
+    );
+    function syncTabStops() {
+      const root = rootRef.current;
+      if (!root || keyboardNavigation !== "roving") return;
+      const buttons = toolbarButtons(root);
+      const active = buttons.includes(lastFocused.current) ? lastFocused.current : buttons[0];
+      root.querySelectorAll("[data-edux-toolbar-button]").forEach((button) => {
+        const nextTabIndex = button === active ? 0 : -1;
+        if (button.closest("[data-edux-toolbar]") !== root) return;
+        if (!originalTabIndexes.current.has(button))
+          originalTabIndexes.current.set(
+            button,
+            button.getAttribute("tabindex")
+          );
+        if (button.tabIndex !== nextTabIndex) button.tabIndex = nextTabIndex;
+      });
+      lastFocused.current = active ?? null;
+    }
+    useEffect3(() => {
+      const root = rootRef.current;
+      if (!root || keyboardNavigation !== "roving") return;
+      syncTabStops();
+      const observer = typeof MutationObserver === "undefined" ? null : new MutationObserver(syncTabStops);
+      observer?.observe(root, {
+        subtree: true,
+        childList: true,
+        attributes: true,
+        attributeFilter: [
+          "disabled",
+          "aria-disabled",
+          "hidden",
+          "inert",
+          "aria-hidden",
+          "class",
+          "style",
+          "tabindex"
+        ]
+      });
+      return () => {
+        observer?.disconnect();
+        originalTabIndexes.current.forEach((value, button) => {
+          if (value === null) button.removeAttribute("tabindex");
+          else button.setAttribute("tabindex", value);
+        });
+        originalTabIndexes.current.clear();
+      };
+    }, [keyboardNavigation]);
+    return /* @__PURE__ */ jsx7(
+      "div",
+      {
+        ...props,
+        ref: rootRef,
+        role: "toolbar",
+        "aria-orientation": orientation,
+        "data-edux-toolbar": "",
+        className: cx6(
+          "flex min-w-0 flex-wrap gap-8",
+          orientation === "vertical" ? "flex-col items-start" : "items-center",
+          className
+        ),
+        onFocusCapture: (event) => {
+          onFocusCapture?.(event);
+          const target = event.target;
+          if (target instanceof HTMLButtonElement && target.closest("[data-edux-toolbar]") === event.currentTarget) {
+            if (toolbarButtons(event.currentTarget).includes(target))
+              lastFocused.current = target;
+            syncTabStops();
+          }
+        },
+        onKeyDown: (event) => {
+          onKeyDown?.(event);
+          if (keyboardNavigation !== "roving" || event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey)
+            return;
+          const root = event.currentTarget;
+          const target = event.target;
+          if (!(target instanceof HTMLButtonElement) || target.closest("[data-edux-toolbar]") !== root)
+            return;
+          const buttons = toolbarButtons(root);
+          const index = buttons.indexOf(target);
+          if (index === -1) return;
+          let next;
+          if (event.key === "Home") next = 0;
+          else if (event.key === "End") next = buttons.length - 1;
+          else {
+            const directionValue = root.ownerDocument.defaultView?.getComputedStyle(root).direction || root.closest("[dir]")?.getAttribute("dir");
+            const rtl = directionValue === "rtl";
+            const forward = orientation === "vertical" ? "ArrowDown" : rtl ? "ArrowLeft" : "ArrowRight";
+            const backward = orientation === "vertical" ? "ArrowUp" : rtl ? "ArrowRight" : "ArrowLeft";
+            if (event.key !== forward && event.key !== backward) return;
+            const direction = event.key === forward ? 1 : -1;
+            next = loop ? (index + direction + buttons.length) % buttons.length : Math.max(0, Math.min(buttons.length - 1, index + direction));
+          }
+          event.preventDefault();
+          buttons[next]?.focus();
+        },
+        children
+      }
+    );
+  }
+);
+var ToolbarGroup = forwardRef6(
+  function ToolbarGroup2({ orientation = "horizontal", className, ...props }, ref) {
+    return /* @__PURE__ */ jsx7(
+      "div",
+      {
+        ...props,
+        ref,
+        role: "group",
+        className: cx6(
+          "inline-flex gap-4",
+          orientation === "vertical" ? "flex-col" : "flex-wrap items-center",
+          className
+        )
+      }
+    );
+  }
+);
+var ToolbarSeparator = forwardRef6(function ToolbarSeparator2({ orientation = "vertical", className, ...props }, ref) {
+  return /* @__PURE__ */ jsx7(
+    "div",
+    {
+      ...props,
+      ref,
+      role: "separator",
+      "aria-orientation": orientation,
+      className: cx6(
+        "shrink-0 border-border-subtle",
+        orientation === "vertical" ? "h-control-sm border-l" : "w-full border-t",
+        className
+      )
+    }
+  );
+});
+
+// src/elements/ToolbarButton.tsx
+import { forwardRef as forwardRef7, useState as useState3 } from "react";
+import { cx as cx7 } from "@edux-design/utils";
+import { jsx as jsx8, jsxs as jsxs6 } from "react/jsx-runtime";
+var sizes = {
+  small: "h-control-sm min-w-control-sm text-sm",
+  medium: "h-control-md min-w-control-md text-base",
+  large: "h-control-lg min-w-control-lg text-lg"
+};
+var ToolbarButton = forwardRef7(
+  function ToolbarButton2({
+    active = false,
+    size = "small",
+    variant = "neutral",
+    icon,
+    iconOnly = false,
+    children,
+    className,
+    type = "button",
+    onClick,
+    ...props
+  }, ref) {
+    const pressed = active || props["aria-pressed"] === true || props["aria-pressed"] === "true" || props["aria-pressed"] === "mixed";
+    const disabled = props.disabled || props["aria-disabled"] === true || props["aria-disabled"] === "true";
+    const colours = {
+      neutral: pressed ? "border-border-primary-base bg-bg-primary-subtle text-fg-primary-emphasis" : "border-transparent bg-transparent text-fg-base hover:bg-bg-minimal active:bg-bg-inactive",
+      primary: pressed ? "border-border-primary-emphasis bg-bg-primary-subtle text-fg-primary-emphasis" : "border-transparent bg-transparent text-fg-primary-emphasis hover:bg-bg-primary-subtle active:bg-bg-primary-subtle-90",
+      danger: pressed ? "border-border-danger-emphasis bg-bg-danger-subtle text-fg-danger-emphasis" : "border-transparent bg-transparent text-fg-danger-emphasis hover:bg-bg-danger-subtle active:bg-bg-danger-subtle"
+    };
+    return /* @__PURE__ */ jsxs6(
+      "button",
+      {
+        "aria-pressed": active ? true : void 0,
+        ...props,
+        ref,
+        type,
+        "data-edux-toolbar-button": "",
+        "data-state": pressed ? "on" : "off",
+        className: cx7(
+          "inline-flex shrink-0 items-center justify-center gap-8 whitespace-nowrap rounded-md border-2 font-semibold cursor-pointer outline-none transition-colors duration-150 motion-reduce:transition-none focus-visible:shadow-focus disabled:cursor-not-allowed disabled:opacity-50 aria-disabled:cursor-not-allowed aria-disabled:opacity-50",
+          sizes[size],
+          iconOnly ? "aspect-square p-0" : "px-8",
+          disabled ? "border-border-subtle bg-bg-inactive text-fg-inactive" : colours[variant],
+          className
+        ),
+        onClick: (event) => {
+          if (disabled) {
+            event.preventDefault();
+            return;
+          }
+          onClick?.(event);
+        },
+        children: [
+          icon && /* @__PURE__ */ jsx8(
+            "span",
+            {
+              "aria-hidden": "true",
+              className: "inline-flex shrink-0 items-center",
+              children: icon
+            }
+          ),
+          children
+        ]
+      }
+    );
+  }
+);
+var ToolbarToggleButton = forwardRef7(function ToolbarToggleButton2({ pressed, defaultPressed = false, onPressedChange, onClick, ...props }, ref) {
+  const [internalPressed, setInternalPressed] = useState3(defaultPressed);
+  const isPressed = pressed ?? internalPressed;
+  return /* @__PURE__ */ jsx8(
+    ToolbarButton,
+    {
+      ...props,
+      ref,
+      "aria-pressed": isPressed,
+      onClick: (event) => {
+        onClick?.(event);
+        if (event.defaultPrevented) return;
+        if (pressed === void 0) setInternalPressed(!isPressed);
+        onPressedChange?.(!isPressed, event);
+      }
+    }
+  );
+});
 export {
   Button,
   ButtonCounter,
   ButtonGroup,
   ButtonGroupItem,
   IconButton,
-  MenuButton
+  MenuButton,
+  Toolbar,
+  ToolbarButton,
+  ToolbarGroup,
+  ToolbarSeparator,
+  ToolbarToggleButton
 };

package/docs/button-group.md

@@ -0,0 +1,25 @@
+# ButtonGroup option types
+
+`ButtonGroupItem` is an option marker read by `ButtonGroup`. It accepts `value`
+(string or number), `disabled` (boolean), `label`, `children`, `startAdornment`,
+`endAdornment`, and the legacy `endIcon` alias. Omitted values use the option's
+index. The label falls back to children, then an automatically numbered label.
+
+The marker renders no DOM element. It does not forward a ref, native button
+attributes, or event handlers. Put selection handling on `ButtonGroup.onChange`,
+which receives the selected value and option. The group forwards a div ref and
+native div attributes. Use `Button` for a native button ref, attributes, and events.
+
+```tsx
+<ButtonGroup defaultValue="draft" onChange={(value) => setFilter(value)}>
+  <ButtonGroupItem value="draft">Draft</ButtonGroupItem>
+  <ButtonGroupItem value="published" endAdornment={<span>3</span>}>
+    Published
+  </ButtonGroupItem>
+  <ButtonGroupItem value="archived" disabled>Archived</ButtonGroupItem>
+</ButtonGroup>
+```
+
+The package-local `test/button-group-api.tsx` fixture checks the public entry point
+under strict TypeScript, including no-`any` assertions, native button refs/events,
+selection values, disabled options, and rejection of unsupported marker props.

package/docs/toolbar.md

@@ -0,0 +1,146 @@
+# Toolbar controls
+
+`ToolbarButton`, `ToolbarToggleButton`, `Toolbar`, `ToolbarGroup` and
+`ToolbarSeparator` extend the Buttons package without changing existing Button,
+IconButton or ButtonGroup APIs. Use them for compact editor, preview and page
+actions. Commands, editor selection, persistence and menu state belong to the host.
+
+```tsx
+import {
+  Toolbar,
+  ToolbarGroup,
+  ToolbarSeparator,
+  ToolbarButton,
+  ToolbarToggleButton,
+} from "@edux-design/buttons";
+
+<Toolbar aria-label="Document formatting">
+  <ToolbarGroup aria-label="Text style">
+    <ToolbarToggleButton pressed={bold} onPressedChange={setBold}>
+      Bold
+    </ToolbarToggleButton>
+    <ToolbarToggleButton defaultPressed>Italic</ToolbarToggleButton>
+  </ToolbarGroup>
+  <ToolbarSeparator />
+  <ToolbarButton onClick={save}>Save draft</ToolbarButton>
+</Toolbar>;
+```
+
+## Buttons and state
+
+All buttons render a single native `button`, forward an `HTMLButtonElement` ref,
+and accept native attributes, events, ARIA, data attributes, `className`, `style`
+and arbitrary children. Their default `type` is `button`; `type="submit"` is
+supported. Handlers receive the native React event with the actual button as
+`event.currentTarget`, suitable for menu anchors and measurement. No wrapper is
+inserted around the button. An optional `icon` slot is decorative (`aria-hidden`).
+
+| Prop            | Default   | Contract                                                    |
+| --------------- | --------- | ----------------------------------------------------------- |
+| `size`          | `small`   | `small`, `medium`, `large`: 36, 44, 56px semantic controls  |
+| `variant`       | `neutral` | `neutral`, `primary`, `danger`; existing semantic tokens    |
+| `iconOnly`      | `false`   | Square geometry; caller supplies an accessible name         |
+| `icon`          | —         | Decorative icon before children                             |
+| `active`        | `false`   | ToolbarButton compatibility visual state, no internal state |
+| `disabled`      | `false`   | Native disabled behaviour; blocks activation                |
+| `aria-disabled` | —         | Also blocks activation; roving focus skips this action      |
+
+An ordinary action has no `aria-pressed` attribute by default. Native
+`aria-pressed` true/false/mixed is forwarded and controls selected styling.
+`active` is a compatibility flag: true selects the visual and defaults
+`aria-pressed` to true. Explicit native `aria-pressed`, including false or
+undefined, takes precedence for semantics. A question selector can use
+`active={current}` and `aria-pressed={undefined}` with the host's appropriate
+`aria-current` semantics. It need not become a toggle merely to show selection.
+
+`ToolbarToggleButton` is an independent toggle with boolean `pressed`,
+`defaultPressed` (false by default), and
+`onPressedChange(nextBoolean, clickEvent)`. It always exposes true or false
+`aria-pressed`. Controlled state changes only when its host updates `pressed`.
+The native `onClick` runs first; `event.preventDefault()` cancels state changes
+and the change callback. Disabled actions cannot change state. Enter and Space
+use native button activation. Keep a toggle's accessible label stable between
+states. `active` is reserved for ToolbarButton, not the dedicated toggle.
+
+The selected border reserves its space in every state, keeping dimensions stable.
+Transitions honour reduced motion. Disabled controls keep their disabled colours
+on hover. There are no new palette or semantic tokens.
+
+## Grouping and keyboard policy
+
+`Toolbar` renders a `div` with `role="toolbar"`; supply `aria-label` or
+`aria-labelledby`. `ToolbarGroup` is a native `div` with `role="group"`, not a
+radiogroup. Give meaningful groups accessible names. Root and group support
+`orientation="horizontal"` (default) or `vertical`, refs and native div props.
+`ToolbarSeparator` renders a non-focusable separator; its `orientation` refers
+to the line, and defaults to `vertical` for a horizontal toolbar.
+
+**Native Tab order is the default.** Grouping does not change button tab stops,
+activate toggles, intercept arrows or manage menu state. Buttons and groups also
+work independently without a Toolbar. This preserves existing footer/editor
+keyboard behaviour when replacing presentation.
+
+Opt into `keyboardNavigation="roving"` deliberately to use a single tab stop
+across ToolbarButton and ToolbarToggleButton descendants. After hydration:
+
+- Horizontal Left/Right arrows move focus in the layout direction, including RTL.
+- Vertical Up/Down arrows move focus; the perpendicular axis remains available.
+- Home/End focus the first/last enabled visible action.
+- `loop` defaults to true; false stops at either end.
+- Tab/Shift+Tab leave normally; returning remembers the last enabled action.
+- Arrow navigation moves focus without activating an action or toggle.
+- Native disabled, aria-disabled, hidden/inert and CSS-hidden actions are skipped.
+- Nested toolbars keep independent focus. Inputs and other widgets retain their
+  own keys and tab order; place complex widgets in separate labelled groups when
+  a strict one-stop toolbar is required.
+- Modified keys and caller-prevented key events are left alone, including table
+  Alt+Arrow shortcuts. The host's root `onKeyDown` runs before navigation.
+
+Roving mode owns action tab stops while enabled, updates them when actions change,
+and restores the original native values when disabled/unmounted. It does not
+capture focus, auto-focus on mount, intercept Escape or handle editor commands.
+
+## Payload compact and selection adapters
+
+Existing Payload toolbars use 32px controls. The package's standard small control
+is 36px. Preserve 32px explicitly during local acceptance rather than silently
+resizing the client. This is component/host geometry, not a new global token:
+
+```tsx
+const compact = { height: 32, minWidth: 32 };
+
+<ToolbarButton
+  style={compact}
+  onMouseDown={(event) => {
+    event.preventDefault(); // Host preserves editor selection.
+    onMouseDown?.(event); // Existing handler observes defaultPrevented.
+  }}
+  onClick={runCommand}
+>
+  Insert
+</ToolbarButton>;
+```
+
+Mouse prevention is optional host behaviour. The package does not prevent pointer
+focus or focus the editor. Keyboard navigation and activation remain available.
+Table handles can retain their class/style/data hooks and specialised geometry,
+pointer handlers, currentTarget anchors and Alt+Arrow reordering in local adapters.
+
+## Tooltip, menu and theme composition
+
+Use TooltipTrigger's `asChild` API around the same button, or pass that button
+as the existing Menu's `button` prop. Provide TooltipProvider as usual.
+Tooltips describe an action; icon-only actions
+still need `aria-label`/`aria-labelledby`. Injected refs/handlers/ARIA are forwarded.
+Menus own their `aria-expanded`, popup keyboard behaviour and focus restoration;
+use ToolbarButton, not an independent toggle, for a menu trigger.
+
+Import `@edux-design/tokens/theme` once, and include installed packages in Tailwind
+source detection. Use existing `theme--light`/`theme--dark` and `brand--blue`/
+`brand--teal` classes on the same scope. The controls use existing semantic
+foreground, background, border and focus tokens. They do not own a theme provider.
+
+Storybook **Components/Toolbar** includes native actions, explicit roving focus,
+all sizes/states, light/dark × blue/teal, narrow wrapping, vertical/RTL, tooltip/menu
+composition, a measured Payload32px recipe and the editor selection adapter. The package includes interaction,
+structural accessibility, public consumer type and CJS/SSR fixtures.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edux-design/buttons",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "private": false,
   "sideEffects": [
     "**/*.css"
@@ -13,21 +13,6 @@
       "require": "./dist/index.js"
     }
   },
-  "scripts": {
-    "lint": "eslint . --max-warnings 0",
-    "build": "tsup src/index.js --format esm,cjs --dts",
-    "dev": "tsup src/index.js --watch --format esm,cjs --dts",
-    "generate:component": "turbo gen react-component",
-    "check-types": "tsc --noEmit"
-  },
-  "devDependencies": {
-    "typescript": "^5.9.2",
-    "tailwindcss": "^4.1.12",
-    "postcss": "^8.5.6",
-    "tsup": "^8.5.0",
-    "@tailwindcss/cli": "^4.1.12",
-    "@tailwindcss/postcss": "^4.1.12"
-  },
   "dependencies": {
     "@edux-design/utils": "*"
   },
@@ -35,5 +20,11 @@
     "@edux-design/tokens": ">=0.2.0 <0.3.0",
     "react": "^19.1.0",
     "react-dom": "^19.1.0"
-  }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "CHANGELOG.md"
+  ]
 }