feat(ButtonSplit): add component

Author: tenphi

.changeset/button-pressed-icon-mod.md

@@ -0,0 +1,5 @@
+---
+"@cube-dev/ui-kit": patch
+---
+
+**Button:** The dynamic `icon` callback now receives `pressed` in its mods argument. Use it to change the icon when the button is pressed (e.g., arrow up when menu is open, arrow down when closed).

.changeset/button-split.md

@@ -0,0 +1,5 @@
+---
+"@cube-dev/ui-kit": minor
+---
+
+**Button.Split:** New compound component for split-button patterns. Supports two modes: **custom** (arbitrary `<Button>` children with joined radius) and **strict** (declarative `actions` array with built-in dropdown menu, controlled/uncontrolled selection). `type`, `theme`, `size`, and `isDisabled` are inherited by child buttons via context.

package.json

@@ -111,7 +111,7 @@
     "@storybook/addon-docs": "^10.2.3",
     "@storybook/addon-links": "^10.2.3",
     "@storybook/react-vite": "^10.2.3",
-    "@tenphi/eslint-plugin-tasty": "^0.3.0",
+    "@tenphi/eslint-plugin-tasty": "^0.3.1",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.7.0",
     "@testing-library/react": "^16.3.0",

pnpm-lock.yaml

@@ -66,6 +66,7 @@ import { DisplayTransition } from '../../helpers/DisplayTransition';
 import { IconSwitch } from '../../helpers/IconSwitch/IconSwitch';
 import { CubeTooltipProviderProps } from '../../overlays/Tooltip/TooltipProvider';
 import { CubeActionProps } from '../Action/Action';
+import { useButtonSplitContext } from '../ButtonSplit/context';
 import { useAction } from '../use-action';
 
 const BUTTON_SIZE_VALUES = [
@@ -79,6 +80,7 @@ const BUTTON_SIZE_VALUES = [
 
 /** Known modifiers for Button component */
 export type ButtonMods = Mods<{
+  pressed?: boolean;
   loading?: boolean;
   selected?: boolean;
   'has-icons'?: boolean;
@@ -222,6 +224,18 @@ export const DEFAULT_BUTTON_STYLES: Styles = {
   radius: {
     '': true,
     'type=link & !focused': 0,
+    '@parent(button-split, >) & !:last-child': '1r left',
+    '@parent(button-split, >) & !:first-child': '1r right',
+    '@parent(button-split, >) & !:first-child & !:last-child': 0,
+  },
+  margin: {
+    '': 0,
+    '@parent(button-split, >) & !:first-child & (type=secondary | type=outline | type=primary)':
+      '-1bw left',
+  },
+  zIndex: {
+    '@parent(button-split, >) & :hover': 1,
+    '@parent(button-split, >) & :focus-visible': 2,
   },
   transition: 'theme, grid-template, padding',
   verticalAlign: 'bottom',
@@ -364,12 +378,14 @@ export const Button = forwardRef(function Button(
   allProps: CubeButtonProps,
   ref: FocusableRef<HTMLElement>,
 ) {
+  const splitContext = useButtonSplitContext();
+
   let {
     type,
     size: sizeProp,
     label,
     children,
-    theme = 'default',
+    theme = splitContext?.theme ?? 'default',
     icon: iconProp,
     rightIcon: rightIconProp,
     mods,
@@ -379,20 +395,34 @@ export const Button = forwardRef(function Button(
     ...props
   } = allProps;
 
-  const size = sizeProp ?? (type === 'link' ? 'inline' : 'medium');
+  type = type ?? splitContext?.type;
+  const size =
+    sizeProp ?? splitContext?.size ?? (type === 'link' ? 'inline' : 'medium');
 
-  const isDisabled = props.isDisabled ?? props.isLoading;
+  const isDisabled =
+    props.isDisabled ?? props.isLoading ?? splitContext?.isDisabled;
   const isLoading = props.isLoading;
   const isSelected = props.isSelected;
 
+  const { actionProps, isPressed } = useAction(
+    { ...allProps, isDisabled, ...(label ? { label } : {}) },
+    ref,
+  );
+
+  const styles = extractStyles(props, STYLE_PROPS);
+  const isDisabledElement = actionProps.isDisabled;
+
+  delete actionProps.isDisabled;
+
   // Base mods for icon resolution (without icon-dependent mods)
   const baseMods = useMemo<ButtonMods>(
     () => ({
+      pressed: isPressed && !isDisabled,
       loading: isLoading,
       selected: isSelected,
       ...mods,
     }),
-    [isLoading, isSelected, mods],
+    [isPressed, isDisabled, isLoading, isSelected, mods],
   );
 
   // Resolve dynamic icon props
@@ -499,16 +529,6 @@ export const Button = forwardRef(function Button(
     ],
   );
 
-  const { actionProps } = useAction(
-    { ...allProps, isDisabled, mods: modifiers, ...(label ? { label } : {}) },
-    ref,
-  );
-
-  const styles = extractStyles(props, STYLE_PROPS);
-  const isDisabledElement = actionProps.isDisabled;
-
-  delete actionProps.isDisabled;
-
   const {
     labelProps: finalLabelProps,
     labelRef,
@@ -552,6 +572,7 @@ export const Button = forwardRef(function Button(
         download={download}
         {...mergeProps(actionProps, tooltipTriggerProps || {})}
         ref={handleRef}
+        mods={{ ...actionProps.mods, ...modifiers }}
         disabled={isDisabledElement}
         variant={`${theme}.${type ?? 'outline'}` as ButtonVariant}
         data-theme={theme}

src/components/actions/Button/Button.tsx

@@ -0,0 +1,201 @@
+import { Meta, Story, Controls } from '@storybook/addon-docs/blocks';
+import * as ButtonSplitStories from './ButtonSplit.stories';
+
+<Meta of={ButtonSplitStories} />
+
+# Button.Split
+
+A split button that groups a primary action with a dropdown trigger for secondary actions. Supports two modes: **custom** (arbitrary button children) and **strict** (declarative action list with built-in menu).
+
+## When to Use
+
+- Present a default action alongside alternative actions in a compact control
+- Allow users to switch between related operations (e.g., deploy targets, save modes)
+- Group two or more buttons visually as a single connected unit
+
+## Component
+
+<Story of={ButtonSplitStories.Default} />
+
+---
+
+## Properties
+
+<Controls />
+
+### Base Properties
+
+Supports [Base properties](https://github.com/tenphi/tasty/blob/main/docs/tasty.md)
+
+### Styling Properties
+
+#### styles
+
+Customises the root wrapper element of the split button.
+
+### Style Properties
+
+These properties allow direct styling without using the `styles` prop: `width`, `height`.
+
+## Modes
+
+### Strict Mode
+
+Pass an `actions` array to automatically render an action button and a trigger button with a dropdown menu. The trigger displays a `DirectionIcon` pointing down.
+
+```jsx
+import { Button } from '@cube-dev/ui-kit';
+
+const actions = [
+  { key: 'deploy', label: 'Deploy', icon: <IconSend /> },
+  { key: 'deploy-staging', label: 'Deploy to Staging', icon: <IconSend /> },
+  { key: 'deploy-preview', label: 'Deploy Preview', icon: <IconPlayerPlay /> },
+];
+
+<Button.Split
+  actions={actions}
+  defaultActionKey="deploy"
+  type="primary"
+  onAction={(key) => console.log('Executed:', key)}
+  onActionChange={(key) => console.log('Switched to:', key)}
+/>
+```
+
+<Story of={ButtonSplitStories.StrictUncontrolled} />
+
+#### Controlled
+
+Use `actionKey` and `onActionChange` for controlled state.
+
+```jsx
+const [currentKey, setCurrentKey] = useState('deploy');
+
+<Button.Split
+  actions={actions}
+  actionKey={currentKey}
+  type="primary"
+  onAction={(key) => console.log('Executed:', key)}
+  onActionChange={setCurrentKey}
+/>
+```
+
+<Story of={ButtonSplitStories.StrictControlled} />
+
+### Custom Mode
+
+Pass `children` to render arbitrary buttons with split-group styling (joined radius, collapsed borders). Use `Menu.Trigger` and `Menu` for dropdown behavior.
+
+```jsx
+import { Button, Menu } from '@cube-dev/ui-kit';
+
+<Button.Split>
+  <Button type="primary" onPress={() => console.log('Save')}>
+    Save
+  </Button>
+  <Menu.Trigger placement="bottom end">
+    <Button type="primary" aria-label="More save options" icon={true} />
+    <Menu onAction={(key) => console.log(key)}>
+      <Menu.Item key="save-draft">Save as Draft</Menu.Item>
+      <Menu.Item key="save-publish">Save & Publish</Menu.Item>
+    </Menu>
+  </Menu.Trigger>
+</Button.Split>
+```
+
+<Story of={ButtonSplitStories.Custom} />
+
+### Multiple Buttons
+
+More than two buttons are supported. Middle buttons have no border radius.
+
+```jsx
+<Button.Split>
+  <Button type="outline" icon={<IconPlus />}>Add</Button>
+  <Button type="outline" icon={<IconCopy />}>Copy</Button>
+  <Button type="outline" icon={<IconDownload />}>Export</Button>
+</Button.Split>
+```
+
+<Story of={ButtonSplitStories.ThreeButtons} />
+
+## Examples
+
+### Variants
+
+Different types and themes can be applied in strict mode.
+
+<Story of={ButtonSplitStories.Variants} />
+
+```jsx
+<Button.Split actions={actions} defaultActionKey="copy" type="primary" />
+<Button.Split actions={actions} defaultActionKey="copy" type="secondary" />
+<Button.Split actions={actions} defaultActionKey="copy" type="outline" />
+<Button.Split actions={actions} defaultActionKey="copy" type="primary" theme="danger" />
+<Button.Split actions={actions} defaultActionKey="copy" type="primary" isDisabled />
+```
+
+### Customizing Sub-Components
+
+Use `actionProps`, `triggerProps`, and `menuProps` to customise individual parts.
+
+```jsx
+<Button.Split
+  actions={actions}
+  defaultActionKey="deploy"
+  type="primary"
+  actionProps={{ size: 'large' }}
+  triggerProps={{ 'aria-label': 'Select deploy target' }}
+  menuProps={{ placement: 'bottom start' }}
+/>
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Tab` -- Moves focus between the action button and the trigger button.
+- `Space` / `Enter` -- Activates the focused button. On the trigger, opens the dropdown menu.
+- `Arrow Down` -- When the menu is open, navigates menu items.
+- `Escape` -- Closes the dropdown menu and returns focus to the trigger.
+
+### Screen Reader Support
+
+- The action button announces its label.
+- The trigger button has `aria-label="More options"` by default (override via `triggerProps`).
+- The dropdown menu announces selection changes.
+
+### ARIA Properties
+
+- `aria-label` -- Provide on the trigger for context (e.g., "Select deploy target").
+- Menu items support `aria-disabled` via the `isDisabled` property on actions.
+
+## Best Practices
+
+1. **Do**: Use strict mode for standard action+trigger patterns.
+   ```jsx
+   <Button.Split actions={actions} defaultActionKey="deploy" type="primary" />
+   ```
+
+2. **Do**: Use custom mode when you need full control over button content and behavior.
+   ```jsx
+   <Button.Split>
+     <Button>Primary</Button>
+     <Button icon={<DirectionIcon to="down" />} aria-label="Options" />
+   </Button.Split>
+   ```
+
+3. **Don't**: Mix `actions` prop with `children`. Use one mode or the other.
+
+4. **Accessibility**: Always provide `aria-label` on icon-only trigger buttons.
+
+## Suggested Improvements
+
+- Add `size` variants demo for strict mode across all sizes.
+- Support `isLoading` on the action button in strict mode.
+- Add keyboard shortcut display in menu items via `hotkeys` prop.
+
+## Related Components
+
+- [Button](/docs/actions-button--docs) -- Standalone action button.
+- [Menu](/docs/actions-menu--docs) -- Dropdown menu for action lists.
+- [Button.Group](/docs/actions-buttongroup--docs) -- Layout wrapper for spacing multiple buttons.