@spaethtech/svelte-ui 0.10.0 → 0.11.0

package/.claude/skills/svelte-ui/SKILL.md

@@ -153,7 +153,13 @@ All from `@spaethtech/svelte-ui` (see the shipped `docs/components.md` + `docs/u
 examples):
 
 - **Form:** `Button` `ButtonDropdown` `Input` `Select` `List` `TextArea` `Checkbox` `Toggle` `Radio`
-  `Rating` · **`FieldGroup`** (fieldset wrapper for radio/checkbox/toggle sets)
+  `Rating` · **`FieldGroup`** (fieldset wrapper for radio/checkbox/toggle sets) · **`ButtonGroup`**
+  (joined row/`col` of `<Button>`s as one unit — an action toolbar or a **controlled** segmented
+  selector; `items` of `ButtonGroupItem` {`value`,`text`,`icon`,`variant`,`disabled`,`menu`,`onclick`}
+  or a presentational default slot; `select` `'none'|'single'|'multi'` with `bind:value`/`bind:values`;
+  selected = variant-swap to filled, unselected = `ghost`; the group owns the frame; an item `menu`
+  (`MenuItem[]`) makes a split-button. Not a form field — for legend/`name`/submit use `FieldGroup`;
+  for view switching use `TabStrip`.)
 - **Specialized inputs:** `PasswordInput` `EmailInput` `SearchInput` `NumberInput` (formatting +
   `percent`/`stepper`/`clamp`/`liveFormat`) `PhoneInput` (stores E.164; dep-free, inject
   `parse`/`format` for per-country)
@@ -180,8 +186,8 @@ examples):
   `bind:value`; children are `<Disclosure value="…">`, no per-item `bind:open`)
 - **Display / theme:** `NotesEditor` · `ThemeSelector` (Auto/Light/Dark Select) · `ThemeToggle`
   (compact ☀/☾ icon button, same persisted state)
-- **Types / utils:** `Variant` `Size` `TabDefinition` (types), `responsiveClasses` / `resolveScalar`,
-  `BREAKPOINT_PX`.
+- **Types / utils:** `Variant` `Size` `TabDefinition` `MenuItem` `ButtonGroupItem` `ButtonGroupSelect`
+  (types), `responsiveClasses` / `resolveScalar`, `BREAKPOINT_PX`.
 
 ## Adopting updates
 

package/dist/components/ButtonGroup/ButtonGroup.svelte

@@ -0,0 +1,236 @@
+<!--
+/**
+ * ButtonGroup — a joined row/column of buttons rendered as one unit: an action toolbar, or a
+ * CONTROLLED segmented single/multi selector. Composes `<Button>` (never a raw `<button>`); the
+ * group owns the frame (border + radius + internal seams) so ends round automatically.
+ *
+ * Two authoring modes:
+ *  - `items` (data-driven, default): the managed path — selection, the selected variant-swap, ARIA,
+ *    and keyboard live here. Required for `select` modes.
+ *  - default slot: a presentational escape hatch — hand-authored `<Button>`s get the frame; YOU own
+ *    their behaviour (selection is `items`-only).
+ *
+ * See `ButtonGroup.spec.md` for the full contract.
+ */
+-->
+<script lang="ts" module>
+  import type { Snippet } from "svelte";
+  import type { Variant } from "../../types/variants.js";
+  import type { MenuItem } from "../../data/table/types.js";
+
+  export type ButtonGroupSelect = "none" | "single" | "multi";
+
+  /** A managed item — rendered internally as a `<Button>`; fields mirror the relevant Button props. */
+  export type ButtonGroupItem = {
+    /** Identity for `select` modes. */
+    value?: string;
+    text?: string;
+    /** Icon slot — a consumer-rendered component (e.g. `~icons/mdi/*`), like `Button`'s `icon`. */
+    icon?: Snippet;
+    disabled?: boolean;
+    /** Per-item colour override; otherwise the group `variant`. */
+    variant?: Variant;
+    /** Split-button dropdown: a trailing caret opens a `Menu` with these items. */
+    menu?: MenuItem[];
+    /** Action-mode click. Fires in `select="none"`; in selection modes it runs after the select. */
+    onclick?: (e: MouseEvent) => void;
+  };
+</script>
+
+<script lang="ts">
+  import Button from "../Button.svelte";
+  import Menu from "../Menu.svelte";
+  import type { Size } from "../../types/sizes.js";
+  import type { Responsive } from "../../types/responsive.js";
+  import IconChevronDown from "~icons/mdi/chevron-down";
+  import { DEV } from "esm-env";
+
+  let {
+    items,
+    select = "none",
+    value = $bindable(),
+    values = $bindable([]),
+    orientation = "row",
+    variant = "primary",
+    size = "md",
+    disabled = false,
+    class: cls = "",
+    children,
+  }: {
+    /** Managed items. Omit to use the default slot instead. */
+    items?: ButtonGroupItem[];
+    /** Selection behaviour (items mode only; the slot is always presentational). */
+    select?: ButtonGroupSelect;
+    /** Selected value in `select="single"` (bindable). */
+    value?: string;
+    /** Selected values in `select="multi"` (bindable). */
+    values?: string[];
+    orientation?: "row" | "col";
+    /** Group accent — the selected item fills with it; per-item `variant` overrides. */
+    variant?: Variant;
+    size?: Responsive<Size>;
+    /** Disable the whole group (per-item `disabled` also honoured). */
+    disabled?: boolean;
+    class?: string;
+    children?: Snippet;
+  } = $props();
+
+  if (DEV && items && children) {
+    console.warn("ButtonGroup: both `items` and children provided — using `items`, ignoring children.");
+  }
+  if (DEV && items && select !== "none") {
+    for (const it of items) {
+      if (it.value == null) {
+        console.warn(`ButtonGroup: item "${it.text ?? "?"}" has no \`value\` — it can never be selected in select="${select}".`);
+      }
+    }
+  }
+
+  const isRow = $derived(orientation === "row");
+
+  // ── Selection ───────────────────────────────────────────────────
+  const isSelected = (v?: string): boolean => {
+    if (v == null || select === "none") return false;
+    return select === "single" ? value === v : values.includes(v);
+  };
+  function activate(item: ButtonGroupItem, e: MouseEvent) {
+    if (disabled || item.disabled) return;
+    const v = item.value;
+    if (v != null) {
+      if (select === "single") value = v;
+      else if (select === "multi") values = values.includes(v) ? values.filter((x) => x !== v) : [...values, v];
+    }
+    item.onclick?.(e);
+  }
+  // Selected → filled (group/item variant); unselected in a select mode → ghost. `none` → always filled.
+  const variantFor = (item: ButtonGroupItem): Variant => {
+    const base = item.variant ?? variant;
+    return select === "none" || isSelected(item.value) ? base : "ghost";
+  };
+  // Per-item ARIA for the selection semantics.
+  const selectAttrs = (item: ButtonGroupItem) =>
+    select === "single"
+      ? { role: "radio", "aria-checked": isSelected(item.value) }
+      : select === "multi"
+        ? { "aria-pressed": isSelected(item.value) }
+        : {};
+
+  const groupRole = $derived(
+    select === "single" ? "radiogroup" : select === "multi" ? "group" : "toolbar",
+  );
+
+  // ── Split-button menus ──────────────────────────────────────────
+  // Per-item open flag (bound to each `Menu`, which closes itself on select / outside-click).
+  // Seed to `false` synchronously (before first render) so `bind:open` never sees `undefined` —
+  // binding `undefined` to Menu's `open` (which has a fallback) is a fatal error.
+  let menuOpen = $state<Record<number, boolean>>({});
+  for (let i = 0; i < (items?.length ?? 0); i++) menuOpen[i] = false;
+  let caretRefs = $state<Record<number, HTMLButtonElement | HTMLAnchorElement | undefined>>({});
+
+  // ── Roving focus / arrow-keys (single mode = radiogroup) ────────
+  let mainRefs = $state<Record<number, HTMLButtonElement | HTMLAnchorElement | undefined>>({});
+  const enabledIdx = $derived(
+    (items ?? []).map((it, i) => (disabled || it.disabled ? -1 : i)).filter((i) => i >= 0),
+  );
+  function onKeydown(e: KeyboardEvent) {
+    if (select !== "single" || !items) return;
+    const fwd = isRow ? "ArrowRight" : "ArrowDown";
+    const back = isRow ? "ArrowLeft" : "ArrowUp";
+    if (e.key !== fwd && e.key !== back) return;
+    e.preventDefault();
+    if (enabledIdx.length === 0) return;
+    const cur = items.findIndex((it) => it.value != null && it.value === value);
+    const pos = enabledIdx.indexOf(cur);
+    const nextPos =
+      e.key === fwd
+        ? (pos + 1 + enabledIdx.length) % enabledIdx.length
+        : (pos - 1 + enabledIdx.length) % enabledIdx.length;
+    const nextIdx = enabledIdx[pos === -1 ? 0 : nextPos];
+    const item = items[nextIdx];
+    if (item?.value != null) {
+      value = item.value;
+      mainRefs[nextIdx]?.focus();
+    }
+  }
+  // Roving tabindex: only the selected (or first enabled) item is tab-focusable in single mode.
+  const tabIdxFor = (i: number, item: ButtonGroupItem): 0 | -1 => {
+    if (select !== "single") return 0;
+    const selectedIdx = items?.findIndex((it) => it.value != null && it.value === value) ?? -1;
+    const anchor = selectedIdx >= 0 ? selectedIdx : (enabledIdx[0] ?? 0);
+    return i === anchor ? 0 : -1;
+  };
+
+  // Frame: the group owns border + radius + seams; inner buttons are squared via a descendant
+  // selector (`[&_button]`), which beats Button's own radius by specificity (reliable).
+  const frameClass = $derived(
+    [
+      "inline-flex",
+      isRow ? "flex-row" : "flex-col",
+      isRow ? "divide-x" : "divide-y",
+      "divide-[var(--ui-border-color)]",
+      "overflow-hidden border [border-color:var(--ui-border-color)] [border-radius:var(--ui-border-radius)]",
+      "[&_button]:rounded-none [&_a]:rounded-none",
+      cls,
+    ].join(" "),
+  );
+</script>
+
+<!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+<div role={groupRole} class={frameClass} onkeydown={onKeydown}>
+  {#if items}
+    {#each items as item, i (item.value ?? item.text ?? i)}
+      {#if item.menu}
+        <!-- Split button: main (action/select) + caret (opens the Menu). One cell in the group. -->
+        <span class="inline-flex {isRow ? '[&>button+button]:border-l' : '[&>button+button]:border-t'} [&>button+button]:[border-color:var(--ui-border-color)]">
+          <Button
+            icon={item.icon}
+            text={item.text}
+            variant={variantFor(item)}
+            {size}
+            disabled={disabled || item.disabled}
+            bind:element={mainRefs[i]}
+            tabindex={tabIdxFor(i, item)}
+            {...selectAttrs(item)}
+            onclick={(e) => activate(item, e)}
+          />
+          <Button
+            variant={variantFor(item)}
+            {size}
+            disabled={disabled || item.disabled}
+            aria-haspopup="menu"
+            aria-expanded={!!menuOpen[i]}
+            aria-label="More"
+            bind:element={caretRefs[i]}
+            onclick={() => (menuOpen[i] = !menuOpen[i])}
+          >
+            {#snippet icon()}<IconChevronDown />{/snippet}
+          </Button>
+        </span>
+      {:else}
+        <Button
+          icon={item.icon}
+          text={item.text}
+          variant={variantFor(item)}
+          {size}
+          disabled={disabled || item.disabled}
+          bind:element={mainRefs[i]}
+          tabindex={tabIdxFor(i, item)}
+          {...selectAttrs(item)}
+          onclick={(e) => activate(item, e)}
+        />
+      {/if}
+    {/each}
+  {:else}
+    {@render children?.()}
+  {/if}
+</div>
+
+<!-- Split-button dropdowns — top-layer, anchored to each caret. Kept OUTSIDE the frame so the frame's
+     `overflow-hidden` never clips them and they don't count as extra `divide-x` cells. -->
+{#if items}
+  {#each items as item, i (item.value ?? item.text ?? i)}
+    {#if item.menu}
+      <Menu anchor={caretRefs[i]} bind:open={menuOpen[i]} items={item.menu} {size} />
+    {/if}
+  {/each}
+{/if}

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

@@ -0,0 +1,42 @@
+import type { Snippet } from "svelte";
+import type { Variant } from "../../types/variants.js";
+import type { MenuItem } from "../../data/table/types.js";
+export type ButtonGroupSelect = "none" | "single" | "multi";
+/** A managed item — rendered internally as a `<Button>`; fields mirror the relevant Button props. */
+export type ButtonGroupItem = {
+    /** Identity for `select` modes. */
+    value?: string;
+    text?: string;
+    /** Icon slot — a consumer-rendered component (e.g. `~icons/mdi/*`), like `Button`'s `icon`. */
+    icon?: Snippet;
+    disabled?: boolean;
+    /** Per-item colour override; otherwise the group `variant`. */
+    variant?: Variant;
+    /** Split-button dropdown: a trailing caret opens a `Menu` with these items. */
+    menu?: MenuItem[];
+    /** Action-mode click. Fires in `select="none"`; in selection modes it runs after the select. */
+    onclick?: (e: MouseEvent) => void;
+};
+import type { Size } from "../../types/sizes.js";
+import type { Responsive } from "../../types/responsive.js";
+type $$ComponentProps = {
+    /** Managed items. Omit to use the default slot instead. */
+    items?: ButtonGroupItem[];
+    /** Selection behaviour (items mode only; the slot is always presentational). */
+    select?: ButtonGroupSelect;
+    /** Selected value in `select="single"` (bindable). */
+    value?: string;
+    /** Selected values in `select="multi"` (bindable). */
+    values?: string[];
+    orientation?: "row" | "col";
+    /** Group accent — the selected item fills with it; per-item `variant` overrides. */
+    variant?: Variant;
+    size?: Responsive<Size>;
+    /** Disable the whole group (per-item `disabled` also honoured). */
+    disabled?: boolean;
+    class?: string;
+    children?: Snippet;
+};
+declare const ButtonGroup: import("svelte").Component<$$ComponentProps, {}, "value" | "values">;
+type ButtonGroup = ReturnType<typeof ButtonGroup>;
+export default ButtonGroup;

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

@@ -0,0 +1,2 @@
+export { default as ButtonGroup } from "./ButtonGroup.svelte";
+export type { ButtonGroupItem, ButtonGroupSelect } from "./ButtonGroup.svelte";

package/dist/components/ButtonGroup/index.js

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

package/dist/index.d.ts

@@ -32,6 +32,9 @@ export { default as ThemeSelector } from "./components/ThemeSelector.svelte";
 export { default as ThemeToggle } from "./components/ThemeToggle.svelte";
 export { default as Popup } from "./components/Popup.svelte";
 export { default as Menu } from "./components/Menu.svelte";
+export type { MenuItem } from "./data/table/types.js";
+export { ButtonGroup } from "./components/ButtonGroup/index.js";
+export type { ButtonGroupItem, ButtonGroupSelect } from "./components/ButtonGroup/index.js";
 export { default as Checkbox } from "./components/Checkbox.svelte";
 export { default as Toggle } from "./components/Toggle.svelte";
 export { default as Radio } from "./components/Radio.svelte";

package/dist/index.js

@@ -37,6 +37,7 @@ export { default as ThemeToggle } from "./components/ThemeToggle.svelte";
 // Utility Components
 export { default as Popup } from "./components/Popup.svelte";
 export { default as Menu } from "./components/Menu.svelte";
+export { ButtonGroup } from "./components/ButtonGroup/index.js";
 export { default as Checkbox } from "./components/Checkbox.svelte";
 export { default as Toggle } from "./components/Toggle.svelte";
 export { default as Radio } from "./components/Radio.svelte";

package/docs/components.md

@@ -135,6 +135,27 @@ One wrapper for a set of Radios, Checkboxes, or Toggles under a shared legend (a
   `variant`, `disabled` (propagate to children), and for radio groups `value` (bindable) + `name`.
   Children render their label inline; radios auto-share the group value/name via context.
 
+### ButtonGroup
+
+A **joined** row (or column) of buttons rendered as one visual unit — an action toolbar and/or a
+**controlled** segmented single/multi selector. Composes `<Button>` (never a raw `<button>`); the
+**group owns the frame** (border, radius, internal `divide-*` seams) so the outer ends round and the
+middles sit flush. The selected/"down" state is a **variant-swap** — unselected buttons are `ghost`,
+the selected one fills with the group `variant`. Not a form field (controlled via `bind:value`, no
+`name`/submit — for those use `FieldGroup`); not navigation (for view switching use `TabStrip`).
+
+- **Location**: `src/lib/components/ButtonGroup/ButtonGroup.svelte`
+- **Axes**: `variant` (the selected fill; per-item `variant` overrides), `size`
+- **Props**: `items` (`ButtonGroupItem[]` — the managed, recommended path), `select`
+  (`'none' | 'single' | 'multi'`, default `'none'`), `value` (bindable, single), `values` (bindable
+  `string[]`, multi), `orientation` (`'row' | 'col'`, default `'row'`), `disabled` (whole group),
+  `class`, `children` (a **presentational** default slot — hand-authored `<Button>`s get the frame but
+  you own their behaviour; mutually exclusive with `items`, which wins + DEV-warns).
+- **`ButtonGroupItem`**: `{ value?, text?, icon? (Snippet), disabled?, variant?, menu? (MenuItem[] —
+  renders a split-button caret opening a `Menu`), onclick? }`.
+- **Selection / a11y**: `'single'` → `role="radiogroup"` + `aria-checked`, arrow-key roving;
+  `'multi'` → `aria-pressed`; `'none'` → `role="toolbar"`, `item.onclick` fires (no swap).
+
 ### Grid
 
 Minimal auto-placed CSS-grid layout primitive — every direct child flows into an equal cell (no

package/docs/usage.md

@@ -220,6 +220,85 @@ A `Disclosure` is one expand/collapse section (`bind:open`); an `Accordion` coor
 </Button>
 ```
 
+### ButtonGroup
+
+A joined row/column of buttons — an action toolbar or a controlled segmented selector. Composes
+`<Button>`; the group owns the frame and the selected state is a variant-swap (`ghost` → filled).
+
+```svelte
+<script>
+  import { ButtonGroup, Button, toast } from "@spaethtech/svelte-ui";
+  import IconAlignLeft from "~icons/mdi/format-align-left";
+  import IconAlignCenter from "~icons/mdi/format-align-center";
+  import IconAlignRight from "~icons/mdi/format-align-right";
+  import IconContentSave from "~icons/mdi/content-save";
+  import IconExport from "~icons/mdi/export-variant";
+  import IconList from "~icons/mdi/view-sequential";
+  import IconGrid from "~icons/mdi/view-grid";
+
+  // Single-select (segmented): exactly one value, bound.
+  let align = $state("left");
+  const alignItems = [
+    { value: "left", text: "Left", icon: iLeft },
+    { value: "center", text: "Center", icon: iCenter },
+    { value: "right", text: "Right", icon: iRight },
+  ];
+
+  // Multi-select: a set of values, bound.
+  let marks = $state(["bold"]);
+
+  // Action toolbar (select="none"): each item runs its onclick; `menu` → split-button.
+  const actions = [
+    { text: "Save", icon: iSave, onclick: () => toast.success("Saved") },
+    {
+      text: "Export",
+      icon: iExport,
+      onclick: () => toast.success("Exported"),
+      menu: [
+        { label: "Export as CSV", onclick: () => toast.success("CSV") },
+        { label: "Export as JSON", onclick: () => toast.success("JSON") },
+      ],
+    },
+  ];
+
+  // Slot mode wires its own selection.
+  let view = $state("list");
+</script>
+
+{#snippet iLeft()}<IconAlignLeft />{/snippet}
+{#snippet iCenter()}<IconAlignCenter />{/snippet}
+{#snippet iRight()}<IconAlignRight />{/snippet}
+{#snippet iSave()}<IconContentSave />{/snippet}
+{#snippet iExport()}<IconExport />{/snippet}
+
+<!-- Segmented single-select (arrow keys move the selection) -->
+<ButtonGroup items={alignItems} select="single" bind:value={align} variant="primary" />
+
+<!-- Multi-select toggle -->
+<ButtonGroup select="multi" bind:values={marks} variant="secondary"
+  items={[
+    { value: "bold", text: "Bold" },
+    { value: "italic", text: "Italic" },
+    { value: "underline", text: "Underline" },
+  ]} />
+
+<!-- Action toolbar with a split-button (Export has a `menu`) -->
+<ButtonGroup items={actions} variant="secondary" />
+
+<!-- Vertical -->
+<ButtonGroup items={alignItems} select="single" bind:value={align} orientation="col" />
+
+<!-- Slot (presentational): hand-authored Buttons get the frame; you own behaviour + selected look -->
+<ButtonGroup>
+  <Button text="List" variant={view === "list" ? "primary" : "ghost"} onclick={() => (view = "list")}>
+    {#snippet icon()}<IconList />{/snippet}
+  </Button>
+  <Button text="Grid" variant={view === "grid" ? "primary" : "ghost"} onclick={() => (view = "grid")}>
+    {#snippet icon()}<IconGrid />{/snippet}
+  </Button>
+</ButtonGroup>
+```
+
 ### Input
 
 ```svelte

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaethtech/svelte-ui",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/spaethtech/svelte-ui.git"