@edux-design/buttons 0.1.4 → 0.3.0

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,44 +1,32 @@
 {
   "name": "@edux-design/buttons",
-  "version": "0.1.4",
+  "version": "0.3.0",
   "private": false,
   "sideEffects": [
     "**/*.css"
   ],
-  "files": [
-    "dist",
-    "README.md",
-    "CHANGELOG.md"
-  ],
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
-      "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "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",
-    "prepack": "npm run build",
-    "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": "*"
   },
   "peerDependencies": {
+    "@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",
+    "LICENSE",
+    "LICENSE.md"
+  ]
 }