@marianmeres/stuic 3.148.0 → 3.149.0

package/dist/actions/tooltip/README.md

@@ -115,7 +115,7 @@ if (isTooltipSupported()) {
 - Requires CSS Anchor Positioning support (no fallback)
 - Shows on hover or focus with 200ms delay
 - Tooltip persists when hovering over it
-- ARIA attributes are automatically managed (`aria-describedby`, `aria-expanded`)
+- ARIA attributes are automatically managed (`aria-describedby`)
 - Maximum width is 16rem (256px) by default
 
 ## CSS Variables

package/dist/actions/tooltip/tooltip.svelte.js

@@ -157,8 +157,11 @@ export function tooltip(anchorEl, fn) {
     // node once init
     // Use addAnchorName to support multiple anchor names on same element (e.g., popover + tooltip)
     addAnchorName(anchorEl, anchorName);
+    // NOTE: aria-describedby is the only ARIA wiring a tooltip anchor should get
+    // (per the WAI-ARIA tooltip pattern). Do NOT manage aria-expanded here — it
+    // belongs to disclosure widgets (menu/combobox triggers), and writing it would
+    // clobber legitimate values set by consumers (e.g. DropdownMenu trigger props).
     anchorEl.setAttribute("aria-describedby", id);
-    anchorEl.setAttribute("aria-expanded", "false");
     const debug = (...args) => {
         if (do_debug)
             console.debug("[tooltip]", rnd, ...args);
@@ -222,7 +225,6 @@ export function tooltip(anchorEl, fn) {
             if (!hide_timer) {
                 debug("show...");
                 clear_show();
-                anchorEl.setAttribute("aria-expanded", "true");
                 //
                 tooltipEl.classList.add("tt-block");
                 // Backstop: the CSS @position-try fallbacks handle most edge cases,
@@ -245,7 +247,6 @@ export function tooltip(anchorEl, fn) {
         hide_timer = setTimeout(() => {
             debug("hide...");
             clear_hide();
-            anchorEl.setAttribute("aria-expanded", "false");
             tooltipEl.classList.remove("tt-visible");
             setTimeout(() => {
                 tooltipEl.classList.remove("tt-block");

package/dist/components/SplitButton/README.md

@@ -0,0 +1,163 @@
+# SplitButton
+
+A primary action button fused with an adjacent secondary trigger on a shared pill
+surface — the pattern seen in meeting toolbars (mic / camera controls) and classic
+"Save ▾" split buttons. The secondary trigger opens a built-in [DropdownMenu](../DropdownMenu/README.md)
+(`items`) or fires a custom callback (`onSecondaryClick`). Both segments support
+tooltips out of the box.
+
+Two visual modes:
+
+- **Raised** (default) — a distinct primary button sitting on a shared pill surface,
+  with a neutral ghost icon trigger beside it (the "meeting toolbar" look).
+- **Divided** (`divided`) — classic split button: both segments flush on one surface,
+  separated by a hairline divider, secondary inheriting the primary intent/variant.
+
+## Props
+
+| Prop                | Type                          | Default               | Description                                                                                                   |
+| ------------------- | ----------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `children`          | `Snippet<[{ checked? }]>`     | -                     | Primary button content (label and/or custom markup)                                                           |
+| `icon`              | `string \| Snippet`           | -                     | Convenience primary icon (SVG string or snippet), rendered before `children`. Icon-only → implies icon button |
+| `onclick`           | `(e: MouseEvent) => void`     | -                     | Primary click handler                                                                                         |
+| `intent`            | `IntentColorKey`              | -                     | Color intent forwarded to the primary button                                                                  |
+| `variant`           | `ButtonVariant`               | `"solid"`             | Visual variant forwarded to the primary button                                                                |
+| `size`              | `ButtonSize`                  | `"md"`                | Size preset forwarded to both segments                                                                        |
+| `iconButton`        | `boolean`                     | auto                  | Icon-only primary. Auto-enabled when `icon` is set without `children`                                         |
+| `checked`           | `boolean`                     | `false`               | Toggle state forwarded to the primary button (bindable, pairs with `iconSwap`)                                |
+| `roleSwitch`        | `boolean`                     | `false`               | Switch/toggle behavior on the primary button                                                                  |
+| `iconSwap`          | `[icon, icon]`                | -                     | Two icon states for the primary swap animation                                                                |
+| `disabled`          | `boolean`                     | -                     | Disable the primary button only                                                                               |
+| `tooltip`           | `string \| TooltipConfig`     | -                     | Tooltip for the primary button                                                                                |
+| `primaryProps`      | `Partial<ButtonProps>`        | -                     | Escape hatch — any extra `ButtonProps` for the primary (wins over conveniences)                               |
+| `classPrimary`      | `string`                      | -                     | Classes for the primary button                                                                                |
+| `primaryEl`         | `HTMLElement`                 | -                     | Primary element reference (bindable)                                                                          |
+| `placement`         | `"start" \| "end"`            | `"start"`             | Which side the secondary trigger sits on (logical, RTL-aware)                                                 |
+| `secondaryIcon`     | `string \| Snippet`           | chevron               | Secondary trigger icon. The default chevron rotates while the menu is open                                    |
+| `secondaryLabel`    | `string`                      | `"More options"`      | Accessible label for the (icon-only) secondary trigger                                                        |
+| `secondaryTooltip`  | `string \| TooltipConfig`     | -                     | Tooltip for the secondary trigger                                                                             |
+| `secondaryDisabled` | `boolean`                     | -                     | Disable the secondary trigger only                                                                            |
+| `onSecondaryClick`  | `(e: MouseEvent) => void`     | -                     | Custom secondary handler — used instead of the dropdown. Ignored when `items` set                             |
+| `secondaryProps`    | `Partial<ButtonProps>`        | -                     | Escape hatch — any extra `ButtonProps` for the secondary trigger                                              |
+| `classSecondary`    | `string`                      | -                     | Classes for the secondary trigger                                                                             |
+| `secondaryEl`       | `HTMLElement`                 | -                     | Secondary element reference (bindable)                                                                        |
+| `items`             | `DropdownMenuItem[]`          | -                     | Menu items — when provided, the secondary trigger opens a `DropdownMenu`                                      |
+| `menuOpen`          | `boolean`                     | `false`               | Menu open state (bindable)                                                                                    |
+| `position`          | `DropdownMenuPosition`        | `"bottom-span-right"` | Menu position relative to the secondary trigger                                                               |
+| `offset`            | `string`                      | `"0.25rem"`           | Menu offset from the secondary trigger (CSS value)                                                            |
+| `menuProps`         | `Partial<DropdownMenuProps>`¹ | -                     | Escape hatch — any extra `DropdownMenuProps` (wins over `position`/`offset`)                                  |
+| `divided`           | `boolean`                     | `false`               | Classic split-button look: flush segments + hairline divider                                                  |
+| `roundedFull`       | `boolean`                     | `true`                | Fully-rounded pill. Set `false` to use the button radius                                                      |
+| `unstyled`          | `boolean`                     | `false`               | Skip all default styling                                                                                      |
+| `class`             | `string`                      | -                     | Additional CSS classes for the wrapper                                                                        |
+| `el`                | `HTMLDivElement`              | -                     | Wrapper element reference (bindable)                                                                          |
+
+¹ `menuProps` excludes the keys the component reserves for its own wiring:
+`items`, `trigger`, `isOpen`, `triggerEl`, `class`.
+
+Remaining props are spread onto the wrapper `<div role="group">` (e.g. `aria-label`, `data-testid`).
+
+## Usage
+
+### Meeting-toolbar pill (raised, icon swap, menu)
+
+```svelte
+<script lang="ts">
+	import { SplitButton, type DropdownMenuItem } from "@marianmeres/stuic";
+	import { iconLucideMic } from "@marianmeres/icons-fns/lucide/iconLucideMic.js";
+	import { iconLucideMicOff } from "@marianmeres/icons-fns/lucide/iconLucideMicOff.js";
+	import { iconLucideEllipsisVertical } from "@marianmeres/icons-fns/lucide/iconLucideEllipsisVertical.js";
+
+	let muted = $state(false);
+	const items: DropdownMenuItem[] = [
+		{ type: "action", id: "a", label: "Audio settings", onSelect: () => {} },
+	];
+</script>
+
+<SplitButton
+	bind:checked={muted}
+	roleSwitch
+	iconSwap={[iconLucideMic({ size: 24 }), iconLucideMicOff({ size: 24 })]}
+	intent={muted ? "destructive" : undefined}
+	tooltip={muted ? "Turn on microphone" : "Turn off microphone"}
+	secondaryIcon={iconLucideEllipsisVertical({ size: 20 })}
+	secondaryLabel="Audio options"
+	secondaryTooltip="Audio options"
+	position="top-span-right"
+	{items}
+	primaryProps={{ "aria-label": "Toggle microphone" }}
+/>
+```
+
+### Classic split button (divided, label, chevron at end)
+
+```svelte
+<SplitButton
+	divided
+	placement="end"
+	intent="primary"
+	roundedFull={false}
+	onclick={() => save()}
+	{items}
+	tooltip="Save"
+	secondaryTooltip="More save options"
+>
+	Save
+</SplitButton>
+```
+
+### Callback instead of the built-in dropdown
+
+```svelte
+<script lang="ts">
+	import { SplitButton, iconSettings } from "@marianmeres/stuic";
+</script>
+
+<SplitButton icon={iconSettings()} onSecondaryClick={() => openCustomPanel()} />
+```
+
+When `items` is provided, `onSecondaryClick` is ignored — the built-in dropdown wins.
+
+## Accessibility
+
+- Wrapper is a `role="group"` — pass `aria-label` to name the group.
+- Two tab stops (primary, secondary). The secondary trigger carries
+  `aria-haspopup="menu"` / `aria-expanded` / `aria-controls` wiring only when the
+  built-in dropdown is active.
+- The secondary trigger is icon-only; `secondaryLabel` provides its accessible
+  name (and doubles as tooltip fallback content).
+- Menu keyboard handling (arrows, Escape, focus return) comes from `DropdownMenu`.
+
+## State attributes
+
+| Attribute           | On      | Meaning                                    |
+| ------------------- | ------- | ------------------------------------------ |
+| `data-placement`    | wrapper | `start` / `end`                            |
+| `data-divided`      | wrapper | Divided (classic) mode                     |
+| `data-rounded-full` | wrapper | Fully-rounded pill                         |
+| `data-size`         | wrapper | Size preset                                |
+| `data-open`         | wrapper | Menu currently open (also when `unstyled`) |
+
+## CSS Variables
+
+```css
+:root {
+	/* Raised (default) mode: shared pill surface behind both segments */
+	--stuic-split-button-bg: var(--stuic-color-surface);
+	--stuic-split-button-padding: calc(var(--spacing) * 1);
+	--stuic-split-button-gap: calc(var(--spacing) * 0.5);
+
+	/* Divider (divided mode only) */
+	--stuic-split-button-divider-bg: var(--stuic-color-border);
+	--stuic-split-button-divider-width: 1px;
+	--stuic-split-button-divider-inset: calc(var(--spacing) * 1.5);
+}
+
+/* structural (resolved at element level with global fallbacks) */
+/* --stuic-split-button-radius: var(--stuic-radius-button) */
+/* --stuic-split-button-transition: var(--stuic-transition) */
+```
+
+In `divided` mode with bordered variants (`outline`), the segment borders plus the
+divider can read as a thicker seam — set `--stuic-split-button-divider-width: 0`
+to rely on the borders alone.

package/dist/components/SplitButton/SplitButton.svelte

@@ -0,0 +1,294 @@
+<script lang="ts" module>
+	import type { HTMLAttributes } from "svelte/elements";
+	import type { Snippet } from "svelte";
+	import type { IntentColorKey } from "../../utils/design-tokens.js";
+	import type {
+		Props as ButtonProps,
+		ButtonVariant,
+		ButtonSize,
+	} from "../Button/Button.svelte";
+	import type {
+		Props as DropdownMenuProps,
+		DropdownMenuItem,
+		DropdownMenuPosition,
+	} from "../DropdownMenu/DropdownMenu.svelte";
+	import type { TooltipConfig } from "../../actions/tooltip/tooltip.svelte.js";
+
+	/** Which side of the primary button the secondary (menu) trigger sits on. Logical (RTL-aware). */
+	export type SplitButtonPlacement = "start" | "end";
+
+	/** Args passed by DropdownMenu's `trigger` snippet (internal). */
+	interface SecondaryTriggerArgs {
+		isOpen: boolean;
+		toggle: () => void;
+		triggerProps: {
+			id: string;
+			"aria-haspopup": "menu";
+			"aria-expanded": boolean;
+			"aria-controls": string;
+		};
+	}
+
+	export interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+		// ----- primary segment -----
+		/** Primary button content (label and/or custom markup). */
+		children?: Snippet<[{ checked?: boolean }]>;
+		/**
+		 * Convenience primary icon (SVG string or snippet). Rendered before `children`.
+		 * When provided without `children`, the primary implicitly becomes an icon button.
+		 */
+		icon?: string | Snippet;
+		/** Primary click handler. */
+		onclick?: (e: MouseEvent) => void;
+		/** Color intent forwarded to the primary button. */
+		intent?: IntentColorKey;
+		/** Visual variant forwarded to the primary button. */
+		variant?: ButtonVariant | string;
+		/** Size preset forwarded to both segments. */
+		size?: ButtonSize | string;
+		/** Icon-only primary (forwarded to Button). Auto-enabled when `icon` is set without `children`. */
+		iconButton?: boolean;
+		/** Toggle state forwarded to the primary button (pairs with `iconSwap`/`roleSwitch`). Bindable. */
+		checked?: boolean;
+		/** Enable switch/toggle behavior on the primary button. */
+		roleSwitch?: boolean;
+		/** Two icon states for swap animation on the primary button (implies icon button). */
+		iconSwap?: ButtonProps["iconSwap"];
+		/** Disable the primary button only (see `secondaryDisabled` for the trigger). */
+		disabled?: boolean;
+		/** Tooltip for the primary button (content string or config). */
+		tooltip?: string | TooltipConfig;
+		/**
+		 * Escape hatch: any extra `ButtonProps` forwarded to the primary button.
+		 * Wins over the top-level conveniences above.
+		 */
+		primaryProps?: Partial<ButtonProps>;
+		/** Classes for the primary button. */
+		classPrimary?: string;
+		/** Bindable primary button element reference. */
+		primaryEl?: HTMLElement;
+
+		// ----- secondary (menu trigger) segment -----
+		/** Which side the secondary trigger sits on (default `"start"` — the raised/pill look). */
+		placement?: SplitButtonPlacement;
+		/** Secondary trigger icon (SVG string or snippet). Defaults to a chevron that rotates when open. */
+		secondaryIcon?: string | Snippet;
+		/** Accessible label for the secondary trigger (default `"More options"`). */
+		secondaryLabel?: string;
+		/** Tooltip for the secondary trigger (content string or config). */
+		secondaryTooltip?: string | TooltipConfig;
+		/** Disable the secondary trigger only. */
+		secondaryDisabled?: boolean;
+		/**
+		 * Custom secondary click handler — used INSTEAD of the built-in dropdown.
+		 * Only relevant when `items` is not provided (`items` takes precedence).
+		 */
+		onSecondaryClick?: (e: MouseEvent) => void;
+		/** Escape hatch: any extra `ButtonProps` forwarded to the secondary trigger button. */
+		secondaryProps?: Partial<ButtonProps>;
+		/** Classes for the secondary trigger button. */
+		classSecondary?: string;
+		/** Bindable secondary trigger element reference. */
+		secondaryEl?: HTMLElement;
+
+		// ----- dropdown menu -----
+		/** Menu items — when provided, the secondary trigger opens a `DropdownMenu`. */
+		items?: DropdownMenuItem[];
+		/** Bindable menu open state. */
+		menuOpen?: boolean;
+		/** Menu position relative to the secondary trigger. */
+		position?: DropdownMenuPosition;
+		/** Menu offset from the secondary trigger (CSS value). */
+		offset?: string;
+		/**
+		 * Escape hatch: any extra `DropdownMenuProps` forwarded to the `DropdownMenu`.
+		 * Wins over the top-level `position`/`offset` conveniences.
+		 */
+		menuProps?: Partial<
+			Omit<DropdownMenuProps, "items" | "trigger" | "isOpen" | "triggerEl" | "class">
+		>;
+
+		// ----- surface -----
+		/**
+		 * Classic split-button look: flush segments + hairline divider — instead of the
+		 * default "raised" look (a distinct primary button on a shared pill surface).
+		 */
+		divided?: boolean;
+		/** Fully-rounded pill (default `true`). Set `false` to use the button radius. */
+		roundedFull?: boolean;
+
+		// ----- universal -----
+		/** Skip all default styling, use only custom classes */
+		unstyled?: boolean;
+		/** Additional CSS classes for the wrapper. */
+		class?: string;
+		/** Bindable wrapper element reference. */
+		el?: HTMLDivElement;
+	}
+</script>
+
+<script lang="ts">
+	import { twMerge } from "../../utils/tw-merge.js";
+	import Button from "../Button/Button.svelte";
+	import DropdownMenu from "../DropdownMenu/DropdownMenu.svelte";
+	import { iconChevronDown } from "../../icons/index.js";
+
+	let {
+		children,
+		icon,
+		onclick,
+		intent,
+		variant = "solid",
+		size = "md",
+		iconButton,
+		checked = $bindable(false),
+		roleSwitch = false,
+		iconSwap,
+		disabled,
+		tooltip,
+		primaryProps,
+		classPrimary,
+		primaryEl = $bindable(),
+		placement = "start",
+		secondaryIcon,
+		secondaryLabel = "More options",
+		secondaryTooltip,
+		secondaryDisabled,
+		onSecondaryClick,
+		secondaryProps,
+		classSecondary,
+		secondaryEl = $bindable(),
+		items,
+		menuOpen = $bindable(false),
+		position,
+		offset,
+		menuProps,
+		divided = false,
+		roundedFull = true,
+		unstyled = false,
+		class: classProp,
+		el = $bindable(),
+		...rest
+	}: Props = $props();
+
+	let _class = $derived(unstyled ? classProp : twMerge("stuic-split-button", classProp));
+
+	// icon-only primary → icon button (explicit `iconButton` always wins)
+	let _iconButton = $derived(iconButton ?? (!!icon && !children));
+
+	// Secondary defaults are mode-aware: neutral ghost circle on the raised pill
+	// surface, primary-matching flush segment in divided mode.
+	let _secondaryVariant = $derived(divided ? variant : "ghost");
+	let _secondaryIntent = $derived(divided ? intent : undefined);
+
+	// In divided mode segment corners are managed by CSS (flush inner, rounded outer)
+	let _segmentRoundedFull = $derived(!divided && roundedFull);
+</script>
+
+{#snippet primaryContent({ checked }: { checked?: boolean })}
+	{#if typeof icon === "string"}
+		<span class="stuic-split-button-icon" aria-hidden="true">{@html icon}</span>
+	{:else if icon}
+		{@render icon()}
+	{/if}
+	{@render children?.({ checked })}
+{/snippet}
+
+{#snippet primary()}
+	<Button
+		bind:el={primaryEl}
+		bind:checked
+		class={twMerge("stuic-split-button-primary", classPrimary)}
+		{intent}
+		{variant}
+		{size}
+		iconButton={_iconButton}
+		{roleSwitch}
+		{iconSwap}
+		{disabled}
+		{tooltip}
+		{unstyled}
+		roundedFull={_segmentRoundedFull}
+		type="button"
+		{onclick}
+		children={icon || children ? primaryContent : undefined}
+		{...primaryProps}
+	/>
+{/snippet}
+
+{#snippet secondary(args?: SecondaryTriggerArgs)}
+	<Button
+		bind:el={secondaryEl}
+		class={twMerge("stuic-split-button-secondary", classSecondary)}
+		intent={_secondaryIntent}
+		variant={_secondaryVariant}
+		{size}
+		iconButton
+		{unstyled}
+		roundedFull={_segmentRoundedFull}
+		disabled={secondaryDisabled}
+		tooltip={secondaryTooltip}
+		aria-label={secondaryLabel}
+		type="button"
+		onclick={(e: MouseEvent) => (args ? args.toggle() : onSecondaryClick?.(e))}
+		{...args?.triggerProps}
+		{...secondaryProps}
+	>
+		{#if typeof secondaryIcon === "string"}
+			<span class="stuic-split-button-icon" aria-hidden="true">{@html secondaryIcon}</span
+			>
+		{:else if secondaryIcon}
+			{@render secondaryIcon()}
+		{:else}
+			<span class="stuic-split-button-caret" aria-hidden="true">
+				{@html iconChevronDown({ size: 20 })}
+			</span>
+		{/if}
+	</Button>
+{/snippet}
+
+{#snippet dropdownTrigger(args: SecondaryTriggerArgs)}
+	{@render secondary(args)}
+{/snippet}
+
+{#snippet secondaryRegion()}
+	{#if items}
+		<DropdownMenu
+			{items}
+			bind:isOpen={menuOpen}
+			bind:triggerEl={
+				() => secondaryEl as HTMLButtonElement | undefined, (v) => (secondaryEl = v)
+			}
+			{position}
+			{offset}
+			{unstyled}
+			class="stuic-split-button-menu"
+			trigger={dropdownTrigger}
+			{...menuProps}
+		/>
+	{:else}
+		{@render secondary()}
+	{/if}
+{/snippet}
+
+<div
+	bind:this={el}
+	class={_class}
+	role="group"
+	data-placement={!unstyled ? placement : undefined}
+	data-divided={!unstyled && divided ? "true" : undefined}
+	data-rounded-full={!unstyled && roundedFull ? "true" : undefined}
+	data-size={!unstyled ? size : undefined}
+	data-open={menuOpen ? "true" : undefined}
+	{...rest}
+>
+	{#if placement === "start"}
+		{@render secondaryRegion()}
+		{#if divided}<span class="stuic-split-button-divider" aria-hidden="true"></span>{/if}
+		{@render primary()}
+	{:else}
+		{@render primary()}
+		{#if divided}<span class="stuic-split-button-divider" aria-hidden="true"></span>{/if}
+		{@render secondaryRegion()}
+	{/if}
+</div>

package/dist/components/SplitButton/SplitButton.svelte.d.ts

@@ -0,0 +1,98 @@
+import type { HTMLAttributes } from "svelte/elements";
+import type { Snippet } from "svelte";
+import type { IntentColorKey } from "../../utils/design-tokens.js";
+import type { Props as ButtonProps, ButtonVariant, ButtonSize } from "../Button/Button.svelte";
+import type { Props as DropdownMenuProps, DropdownMenuItem, DropdownMenuPosition } from "../DropdownMenu/DropdownMenu.svelte";
+import type { TooltipConfig } from "../../actions/tooltip/tooltip.svelte.js";
+/** Which side of the primary button the secondary (menu) trigger sits on. Logical (RTL-aware). */
+export type SplitButtonPlacement = "start" | "end";
+export interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    /** Primary button content (label and/or custom markup). */
+    children?: Snippet<[{
+        checked?: boolean;
+    }]>;
+    /**
+     * Convenience primary icon (SVG string or snippet). Rendered before `children`.
+     * When provided without `children`, the primary implicitly becomes an icon button.
+     */
+    icon?: string | Snippet;
+    /** Primary click handler. */
+    onclick?: (e: MouseEvent) => void;
+    /** Color intent forwarded to the primary button. */
+    intent?: IntentColorKey;
+    /** Visual variant forwarded to the primary button. */
+    variant?: ButtonVariant | string;
+    /** Size preset forwarded to both segments. */
+    size?: ButtonSize | string;
+    /** Icon-only primary (forwarded to Button). Auto-enabled when `icon` is set without `children`. */
+    iconButton?: boolean;
+    /** Toggle state forwarded to the primary button (pairs with `iconSwap`/`roleSwitch`). Bindable. */
+    checked?: boolean;
+    /** Enable switch/toggle behavior on the primary button. */
+    roleSwitch?: boolean;
+    /** Two icon states for swap animation on the primary button (implies icon button). */
+    iconSwap?: ButtonProps["iconSwap"];
+    /** Disable the primary button only (see `secondaryDisabled` for the trigger). */
+    disabled?: boolean;
+    /** Tooltip for the primary button (content string or config). */
+    tooltip?: string | TooltipConfig;
+    /**
+     * Escape hatch: any extra `ButtonProps` forwarded to the primary button.
+     * Wins over the top-level conveniences above.
+     */
+    primaryProps?: Partial<ButtonProps>;
+    /** Classes for the primary button. */
+    classPrimary?: string;
+    /** Bindable primary button element reference. */
+    primaryEl?: HTMLElement;
+    /** Which side the secondary trigger sits on (default `"start"` — the raised/pill look). */
+    placement?: SplitButtonPlacement;
+    /** Secondary trigger icon (SVG string or snippet). Defaults to a chevron that rotates when open. */
+    secondaryIcon?: string | Snippet;
+    /** Accessible label for the secondary trigger (default `"More options"`). */
+    secondaryLabel?: string;
+    /** Tooltip for the secondary trigger (content string or config). */
+    secondaryTooltip?: string | TooltipConfig;
+    /** Disable the secondary trigger only. */
+    secondaryDisabled?: boolean;
+    /**
+     * Custom secondary click handler — used INSTEAD of the built-in dropdown.
+     * Only relevant when `items` is not provided (`items` takes precedence).
+     */
+    onSecondaryClick?: (e: MouseEvent) => void;
+    /** Escape hatch: any extra `ButtonProps` forwarded to the secondary trigger button. */
+    secondaryProps?: Partial<ButtonProps>;
+    /** Classes for the secondary trigger button. */
+    classSecondary?: string;
+    /** Bindable secondary trigger element reference. */
+    secondaryEl?: HTMLElement;
+    /** Menu items — when provided, the secondary trigger opens a `DropdownMenu`. */
+    items?: DropdownMenuItem[];
+    /** Bindable menu open state. */
+    menuOpen?: boolean;
+    /** Menu position relative to the secondary trigger. */
+    position?: DropdownMenuPosition;
+    /** Menu offset from the secondary trigger (CSS value). */
+    offset?: string;
+    /**
+     * Escape hatch: any extra `DropdownMenuProps` forwarded to the `DropdownMenu`.
+     * Wins over the top-level `position`/`offset` conveniences.
+     */
+    menuProps?: Partial<Omit<DropdownMenuProps, "items" | "trigger" | "isOpen" | "triggerEl" | "class">>;
+    /**
+     * Classic split-button look: flush segments + hairline divider — instead of the
+     * default "raised" look (a distinct primary button on a shared pill surface).
+     */
+    divided?: boolean;
+    /** Fully-rounded pill (default `true`). Set `false` to use the button radius. */
+    roundedFull?: boolean;
+    /** Skip all default styling, use only custom classes */
+    unstyled?: boolean;
+    /** Additional CSS classes for the wrapper. */
+    class?: string;
+    /** Bindable wrapper element reference. */
+    el?: HTMLDivElement;
+}
+declare const SplitButton: import("svelte").Component<Props, {}, "el" | "checked" | "primaryEl" | "secondaryEl" | "menuOpen">;
+type SplitButton = ReturnType<typeof SplitButton>;
+export default SplitButton;

package/dist/components/SplitButton/index.css

@@ -0,0 +1,95 @@
+/* =============================================================================
+   SPLIT BUTTON COMPONENT TOKENS
+   Override globally: :root { --stuic-split-button-bg: red; }
+   Override locally:  <SplitButton style="--stuic-split-button-bg: red;">
+   ============================================================================= */
+
+:root {
+	/* Raised (default) mode: shared pill surface behind both segments */
+	--stuic-split-button-bg: var(--stuic-color-surface);
+	--stuic-split-button-padding: calc(var(--spacing) * 0); /* mm: no padding by default */
+	--stuic-split-button-gap: calc(var(--spacing) * 0); /* mm: no gap by default */
+
+	/* Divider (divided mode only) */
+	--stuic-split-button-divider-bg: var(--stuic-color-border);
+	--stuic-split-button-divider-width: 1px;
+	--stuic-split-button-divider-inset: calc(var(--spacing) * 1.5);
+}
+
+@layer components {
+	/* ============================================================================
+	   BASE (raised mode: distinct primary button on a shared pill surface)
+	   ============================================================================ */
+
+	.stuic-split-button {
+		/* structural token resolved at element level (scoped overrides work) */
+		--_sb-radius: var(--stuic-split-button-radius, var(--stuic-radius-button));
+
+		position: relative;
+		display: inline-flex;
+		align-items: center;
+		gap: var(--stuic-split-button-gap);
+		padding: var(--stuic-split-button-padding);
+		background: var(--stuic-split-button-bg);
+		border-radius: var(--_sb-radius);
+	}
+
+	.stuic-split-button[data-rounded-full] {
+		--_sb-radius: 9999px;
+	}
+
+	/* DropdownMenu wrapper participates in the flex row */
+	.stuic-split-button > .stuic-split-button-menu {
+		display: inline-flex;
+	}
+
+	/* Icon wrappers center their svg content */
+	.stuic-split-button-icon,
+	.stuic-split-button-caret {
+		display: inline-flex;
+	}
+
+	/* Default caret rotates when the menu is open */
+	.stuic-split-button-caret {
+		transition: rotate var(--stuic-split-button-transition, var(--stuic-transition));
+	}
+	.stuic-split-button[data-open] .stuic-split-button-caret {
+		rotate: 180deg;
+	}
+
+	/* ============================================================================
+	   DIVIDED MODE (classic split button: flush segments + hairline divider)
+	   ============================================================================ */
+
+	.stuic-split-button[data-divided] {
+		gap: 0;
+		padding: 0;
+		background: transparent;
+	}
+
+	.stuic-split-button[data-divided] .stuic-split-button-divider {
+		align-self: stretch;
+		width: var(--stuic-split-button-divider-width);
+		margin-block: var(--stuic-split-button-divider-inset);
+		background: var(--stuic-split-button-divider-bg);
+	}
+
+	/* Flush inner corners, keep outer corners (placement-aware, logical = RTL-safe) */
+	.stuic-split-button[data-divided] .stuic-split-button-primary,
+	.stuic-split-button[data-divided] .stuic-split-button-secondary {
+		border-radius: 0;
+	}
+
+	.stuic-split-button[data-divided][data-placement="end"] .stuic-split-button-primary,
+	.stuic-split-button[data-divided][data-placement="start"]
+		.stuic-split-button-secondary {
+		border-start-start-radius: var(--_sb-radius);
+		border-end-start-radius: var(--_sb-radius);
+	}
+
+	.stuic-split-button[data-divided][data-placement="end"] .stuic-split-button-secondary,
+	.stuic-split-button[data-divided][data-placement="start"] .stuic-split-button-primary {
+		border-start-end-radius: var(--_sb-radius);
+		border-end-end-radius: var(--_sb-radius);
+	}
+}

package/dist/components/SplitButton/index.d.ts

@@ -0,0 +1 @@
+export { default as SplitButton, type Props as SplitButtonProps, type SplitButtonPlacement, } from "./SplitButton.svelte";

package/dist/components/SplitButton/index.js

@@ -0,0 +1 @@
+export { default as SplitButton, } from "./SplitButton.svelte";

package/dist/index.css

@@ -100,6 +100,7 @@ In practice:
 @import "./components/Skeleton/index.css";
 @import "./components/Slider/index.css";
 @import "./components/Spinner/index.css";
+@import "./components/SplitButton/index.css";
 @import "./components/Switch/index.css";
 @import "./components/TabbedMenu/index.css";
 @import "./components/ThemePreview/index.css";

package/dist/index.d.ts

@@ -70,6 +70,7 @@ export * from "./components/Skeleton/index.js";
 export * from "./components/Slider/index.js";
 export * from "./components/SlidingPanels/index.js";
 export * from "./components/Spinner/index.js";
+export * from "./components/SplitButton/index.js";
 export * from "./components/Switch/index.js";
 export * from "./components/TabbedMenu/index.js";
 export * from "./components/Thc/index.js";

package/dist/index.js

@@ -76,6 +76,7 @@ export * from "./components/Skeleton/index.js";
 export * from "./components/Slider/index.js";
 export * from "./components/SlidingPanels/index.js";
 export * from "./components/Spinner/index.js";
+export * from "./components/SplitButton/index.js";
 export * from "./components/Switch/index.js";
 export * from "./components/TabbedMenu/index.js";
 export * from "./components/Thc/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/stuic",
-	"version": "3.148.0",
+	"version": "3.149.0",
 	"packageManager": "pnpm@11.5.0",
 	"scripts": {
 		"dev": "vite dev",
@@ -129,61 +129,61 @@
 	},
 	"devDependencies": {
 		"@codemirror/commands": "^6.10.4",
-		"@codemirror/lang-markdown": "^6.5.0",
+		"@codemirror/lang-markdown": "^6.5.2",
 		"@codemirror/language": "^6.12.4",
 		"@codemirror/language-data": "^6.5.2",
-		"@codemirror/state": "^6.7.0",
-		"@codemirror/view": "^6.43.4",
-		"@eslint/js": "^9.39.4",
+		"@codemirror/state": "^6.7.1",
+		"@codemirror/view": "^6.43.8",
+		"@eslint/js": "^9.39.5",
 		"@marianmeres/random-human-readable": "^1.10.2",
-		"@milkdown/core": "^7.21.2",
-		"@milkdown/ctx": "^7.21.2",
-		"@milkdown/plugin-history": "^7.21.2",
-		"@milkdown/plugin-listener": "^7.21.2",
-		"@milkdown/preset-commonmark": "^7.21.2",
-		"@milkdown/preset-gfm": "^7.21.2",
-		"@milkdown/prose": "^7.21.2",
-		"@milkdown/transformer": "^7.21.2",
-		"@milkdown/utils": "^7.21.2",
+		"@milkdown/core": "^7.22.0",
+		"@milkdown/ctx": "^7.22.0",
+		"@milkdown/plugin-history": "^7.22.0",
+		"@milkdown/plugin-listener": "^7.22.0",
+		"@milkdown/preset-commonmark": "^7.22.0",
+		"@milkdown/preset-gfm": "^7.22.0",
+		"@milkdown/prose": "^7.22.0",
+		"@milkdown/transformer": "^7.22.0",
+		"@milkdown/utils": "^7.22.0",
 		"@sveltejs/adapter-auto": "^4.0.0",
-		"@sveltejs/kit": "^2.68.0",
+		"@sveltejs/kit": "^2.70.2",
 		"@sveltejs/package": "^2.5.8",
 		"@sveltejs/vite-plugin-svelte": "^6.2.4",
-		"@tailwindcss/cli": "^4.3.1",
+		"@tailwindcss/cli": "^4.3.3",
 		"@tailwindcss/forms": "^0.5.11",
 		"@tailwindcss/typography": "^0.5.20",
-		"@tailwindcss/vite": "^4.3.1",
-		"@types/node": "^25.9.4",
-		"@vitest/browser-playwright": "^4.1.9",
+		"@tailwindcss/vite": "^4.3.3",
+		"@types/node": "^25.9.5",
+		"@vitest/browser-playwright": "^4.1.10",
 		"dotenv": "^16.6.1",
-		"eslint": "^9.39.4",
+		"eslint": "^9.39.5",
 		"globals": "^16.5.0",
-		"playwright": "^1.61.1",
-		"prettier": "^3.9.0",
+		"playwright": "^1.62.1",
+		"prettier": "^3.9.6",
 		"prettier-plugin-svelte": "^3.5.2",
-		"publint": "^0.3.21",
-		"svelte": "^5.56.4",
-		"svelte-check": "^4.7.1",
-		"tailwindcss": "^4.3.1",
-		"tsx": "^4.22.4",
+		"publint": "^0.3.23",
+		"svelte": "^5.56.8",
+		"svelte-check": "^4.7.5",
+		"tailwindcss": "^4.3.3",
+		"tsx": "^4.23.12",
 		"typescript": "^5.9.3",
-		"typescript-eslint": "^8.62.0",
+		"typescript-eslint": "^8.67.0",
 		"vite": "^7.3.6",
-		"vitest": "^4.1.9",
-		"vitest-browser-svelte": "^2.1.1"
+		"vitest": "^4.1.10",
+		"vitest-browser-svelte": "^2.2.1"
 	},
 	"dependencies": {
 		"@marianmeres/clog": "^3.21.0",
-		"@marianmeres/countries": "^1.0.1",
+		"@marianmeres/countries": "^1.1.0",
 		"@marianmeres/cron-parser": "^1.0.1",
-		"@marianmeres/design-tokens": "^1.12.0",
+		"@marianmeres/design-tokens": "^1.17.0",
 		"@marianmeres/icons-fns": "^5.0.0",
 		"@marianmeres/item-collection": "^1.4.2",
 		"@marianmeres/paging-store": "^2.1.1",
 		"@marianmeres/parse-boolean": "^2.1.0",
 		"@marianmeres/ticker": "^1.17.1",
 		"@marianmeres/tree": "^2.3.0",
-		"libphonenumber-js": "^1.13.7",
+		"libphonenumber-js": "^1.13.10",
 		"runed": "^0.23.4",
 		"tailwind-merge": "^3.6.0"
 	}