@spaethtech/svelte-ui 0.1.10 → 0.3.1-dev.3.e16df24

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

@@ -1,13 +1,33 @@
-import type { IconDefinition } from "@fortawesome/free-solid-svg-icons";
-import type { Variant } from "../../types/variants.js";
+import type { Snippet } from "svelte";
 import type { Size } from "../../types/sizes.js";
+import { type Responsive } from "../../types/responsive.js";
+/**
+ * A compact status chip — themed via the semantic colour tokens like
+ * Alert. Honours the shared {@link Variant} + {@link Size} axes;
+ * chips scale in lockstep with the surrounding text.
+ *
+ * Variant → semantic token. `default` uses `--ui-color-secondary`
+ * (the neutral in every theme). The chip fills with a soft tint
+ * of the token and borders with the token at full strength; the
+ * text stays high-contrast against the background.
+ */
+type BadgeVariant = "neutral" | "default" | "primary" | "secondary" | "success" | "info" | "warning" | "danger" | "ghost";
 interface Props {
-    icon?: IconDefinition;
     text?: string;
-    variant?: Variant;
-    size?: Size;
-    iconPosition?: "left" | "right";
+    variant?: BadgeVariant;
+    size?: Responsive<Size>;
+    dismissible?: boolean;
     rounded?: boolean;
+    /** Hide the border WITHOUT changing the box: the border stays 1px (so height/width are
+     *  identical to a bordered chip) but its colour is set to the chip's own background, so the
+     *  visible ring disappears. Set `borderless={false}` for the classic ringed chip — the ring is
+     *  `--ui-tint-border` (30%) over the `--ui-tint-soft` (12%) fill. Defaults `true` (fill only). */
+    borderless?: boolean;
+    /** When set, the badge renders as an `<a href>` (clickable, `cursor-pointer`) instead of a
+     *  static `<span>`. Mirrors Button's `href`. */
+    href?: string;
+    ondismiss?: () => void;
+    children?: Snippet;
 }
 declare const Badge: import("svelte").Component<Props, {}, "">;
 type Badge = ReturnType<typeof Badge>;

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

@@ -1 +1 @@
-export { default } from './Badge.svelte';
+export { default } from "./Badge.svelte";

package/dist/components/Badge/index.js

@@ -1 +1 @@
-export { default } from './Badge.svelte';
+export { default } from "./Badge.svelte";

package/dist/components/Banner.svelte

@@ -0,0 +1,133 @@
+<script lang="ts">
+  import type { Snippet } from "svelte";
+  import type { Size } from "../types/sizes.js";
+  import { responsiveClasses, type Responsive } from "../types/responsive.js";
+  import IconClose from "~icons/mdi/close";
+
+  /**
+   * A page/section-level notice. Like {@link Alert} but ALWAYS solid-filled (variant background +
+   * light text), full-width, with an optional leading icon (always left) and an optional trailing
+   * close (X) button (always right). Quieter a11y than Alert — `role="status"`, not assertive. For
+   * inline field/form status, use <Alert> instead. Honours the shared Size axis (scalar OR responsive).
+   */
+  type BannerVariant =
+    "neutral" | "primary" | "secondary" | "success" | "info" | "warning" | "danger" | "ghost";
+  interface Props {
+    variant?: BannerVariant;
+    size?: Responsive<Size>;
+    text?: string;
+    /** Leading icon (always left) — a Snippet (icon-set-agnostic), like Button/Input. */
+    icon?: Snippet;
+    /** Show a trailing close (X) button (always right). */
+    dismissible?: boolean;
+    /** Border colour = the banner's solid fill (invisible, box unchanged) — the default. Set
+     *  `borderless={false}` for a contrasting 30% tint-border around the bar. */
+    borderless?: boolean;
+    /** Visibility — bindable. The close button sets it false. */
+    open?: boolean;
+    /** Fired after the close button flips `open` to false. */
+    onClose?: () => void;
+    class?: string;
+    children?: Snippet;
+  }
+  let {
+    variant = "info",
+    size = "md",
+    text = "",
+    icon,
+    dismissible = false,
+    borderless = true,
+    open = $bindable(true),
+    onClose,
+    class: cls = "",
+    children,
+  }: Props = $props();
+
+  // Variant → semantic token (danger maps to --ui-color-error).
+  const tokenFor: Record<BannerVariant, string> = {
+    neutral: "--ui-color-text",
+    primary: "--ui-color-primary",
+    secondary: "--ui-color-secondary",
+    success: "--ui-color-success",
+    info: "--ui-color-info",
+    warning: "--ui-color-warning",
+    danger: "--ui-color-error",
+    ghost: "--ui-color-text",
+  };
+  const sizeClass: Record<Size, string> = {
+    sm: "px-3 py-1.5 text-xs gap-2",
+    md: "px-4 py-2.5 text-sm gap-3",
+    lg: "px-5 py-3 text-base gap-3",
+  };
+  // Icon svg size per tier (16 / 20 / 24px) — a touch larger than Alert since a banner is louder.
+  const iconSizeClass: Record<Size, string> = {
+    sm: "[&_svg]:w-4 [&_svg]:h-4",
+    md: "[&_svg]:w-5 [&_svg]:h-5",
+    lg: "[&_svg]:w-6 [&_svg]:h-6",
+  };
+  const token = $derived(tokenFor[variant]);
+  // Accent variants: solid fill + white text (accents are dark enough for white in both themes).
+  // `neutral` is solid too — a --ui-color-text bar — but takes CONTRASTING text (--ui-color-background)
+  // so it stays legible in both modes (black bar/white text in light, white bar/black text in dark).
+  // `ghost` is the quiet exception to "always solid": a faint neutral surface with normal text.
+  const bgColor = $derived(
+    variant === "neutral"
+      ? "var(--ui-color-text)"
+      : variant === "ghost"
+        ? "color-mix(in srgb, var(--ui-color-text) 10%, transparent)"
+        : `var(${token})`,
+  );
+  const textColor = $derived(
+    variant === "neutral"
+      ? "var(--ui-color-background)"
+      : variant === "ghost"
+        ? "var(--ui-color-text)"
+        : "white",
+  );
+  // borderless (default) → border = the solid fill (invisible); else the standard 30% tint-border.
+  const standardBorder = $derived(
+    `color-mix(in srgb, var(${token}) var(--ui-tint-border), transparent)`,
+  );
+  const style = $derived(
+    `background-color: ${bgColor}; color: ${textColor};` +
+      ` border-color: ${borderless ? bgColor : standardBorder};`,
+  );
+
+  function close() {
+    open = false;
+    onClose?.();
+  }
+</script>
+
+{#if open}
+  <div
+    role="status"
+    class="flex w-full items-center border [border-radius:var(--ui-border-radius)] [&_svg]:fill-current {responsiveClasses(
+      size,
+      sizeClass,
+    )} {cls}"
+    {style}
+  >
+    {#if icon}
+      <span class="inline-flex shrink-0 {responsiveClasses(size, iconSizeClass)}"
+        >{@render icon()}</span
+      >
+    {/if}
+    <span class="min-w-0 grow"
+      >{#if children}{@render children()}{:else}{text}{/if}</span
+    >
+    {#if dismissible}
+      <button
+        type="button"
+        aria-label="Dismiss"
+        onclick={close}
+        class="inline-flex shrink-0 cursor-pointer items-center justify-center rounded p-0.5 opacity-80 transition-opacity hover:opacity-100 focus-visible:opacity-100 {responsiveClasses(
+          size,
+          iconSizeClass,
+        )}"
+      >
+        <IconClose />
+      </button>
+    {/if}
+  </div>
+{/if}

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

@@ -0,0 +1,31 @@
+import type { Snippet } from "svelte";
+import type { Size } from "../types/sizes.js";
+import { type Responsive } from "../types/responsive.js";
+/**
+ * A page/section-level notice. Like {@link Alert} but ALWAYS solid-filled (variant background +
+ * light text), full-width, with an optional leading icon (always left) and an optional trailing
+ * close (X) button (always right). Quieter a11y than Alert — `role="status"`, not assertive. For
+ * inline field/form status, use <Alert> instead. Honours the shared Size axis (scalar OR responsive).
+ */
+type BannerVariant = "neutral" | "primary" | "secondary" | "success" | "info" | "warning" | "danger" | "ghost";
+interface Props {
+    variant?: BannerVariant;
+    size?: Responsive<Size>;
+    text?: string;
+    /** Leading icon (always left) — a Snippet (icon-set-agnostic), like Button/Input. */
+    icon?: Snippet;
+    /** Show a trailing close (X) button (always right). */
+    dismissible?: boolean;
+    /** Border colour = the banner's solid fill (invisible, box unchanged) — the default. Set
+     *  `borderless={false}` for a contrasting 30% tint-border around the bar. */
+    borderless?: boolean;
+    /** Visibility — bindable. The close button sets it false. */
+    open?: boolean;
+    /** Fired after the close button flips `open` to false. */
+    onClose?: () => void;
+    class?: string;
+    children?: Snippet;
+}
+declare const Banner: import("svelte").Component<Props, {}, "open">;
+type Banner = ReturnType<typeof Banner>;
+export default Banner;

package/dist/components/Button.svelte

@@ -0,0 +1,240 @@
+<script lang="ts">
+  import type { Snippet } from "svelte";
+  import type { Variant } from "../types/variants.js";
+  import type { Size } from "../types/sizes.js";
+  import { responsiveClasses, type Responsive } from "../types/responsive.js";
+  import type { HTMLButtonAttributes, HTMLAnchorAttributes } from "svelte/elements";
+  import { tooltip } from "../positioning/tooltip.js";
+  import { DEV } from "esm-env";
+
+  // Only lib-specific props live here; standard element attributes (class, title, aria-*, onclick,
+  // disabled, target, …) come from the svelte element-attribute types below.
+  interface BaseProps {
+    /** Icon slot — consumer-rendered (e.g. an MDI `~icons/mdi/*` component). */
+    icon?: Snippet;
+    text?: string;
+    variant?: Responsive<Variant>;
+    size?: Responsive<Size>;
+    /** Border colour matches the fill (invisible ring, box unchanged) — the default. Set
+     *  `borderless={false}` for the standard contrasting tint-border; on the `ghost` variant that's
+     *  the "outline button" (transparent fill + a 30% text-tint edge), no separate variant needed. */
+    borderless?: boolean;
+    children?: Snippet;
+    // Element-agnostic so they're assignable to both <button> and <a> (and typed for consumers).
+    onclick?: (event: MouseEvent) => void;
+    onmouseenter?: (event: MouseEvent) => void;
+    onmouseleave?: (event: MouseEvent) => void;
+    element?: HTMLButtonElement | HTMLAnchorElement;
+  }
+
+  interface ButtonProps extends BaseProps, Omit<HTMLButtonAttributes, keyof BaseProps> {
+    href?: never;
+  }
+
+  interface AnchorProps extends BaseProps, Omit<HTMLAnchorAttributes, keyof BaseProps | "type"> {
+    href: string;
+    type?: never;
+    disabled?: never;
+  }
+
+  export type Props = ButtonProps | AnchorProps;
+
+  let {
+    icon,
+    text,
+    variant = "secondary",
+    size = "md",
+    borderless = true,
+    children,
+    disabled = false,
+    type = "button",
+    href,
+    class: additionalClass = "",
+    title,
+    onclick,
+    onmouseenter,
+    onmouseleave,
+    element = $bindable(),
+    ...restProps
+  }: Props = $props();
+
+  // Development warnings for prop conflicts and empty content
+  if (DEV) {
+    if ((text || icon) && children) {
+      console.warn(
+        "Button: Props (text/icon) and children provided. Using props, ignoring children.",
+      );
+    }
+    if (!text && !icon && !children) {
+      console.warn("Button: No content provided (text, icon, or children). Button will be empty.");
+    }
+  }
+
+  // Determine content mode and styling
+  const hasProps = !!(text || icon);
+  const isIconOnly = icon && !text;
+
+  // Base classes - height is always h-8 (32px), width is h-8 for icon-only
+  const baseClasses =
+    "inline-flex items-center justify-center [border-radius:var(--ui-border-radius)] font-medium transition-colors no-underline cursor-pointer border focus-visible:[outline:2px_solid_color-mix(in_srgb,var(--ui-color-text)_70%,transparent)] focus-visible:[outline-offset:0px]";
+
+  // Additional classes for disabled state (only applies to buttons)
+  const disabledClasses = href ? "" : "disabled:opacity-50 disabled:cursor-not-allowed";
+
+  // Size axis (see types/sizes.ts): height + (icon-only square | labeled padding) + text + icon.
+  // Each map is per-Size; responsiveClasses() turns a scalar OR a { base, xs, … } map into the
+  // right (breakpoint-prefixed) Tailwind classes. Icons scale 14 / 16 / 20px (sm / md / lg).
+  const boxMap: Record<Size, string> = { sm: "h-6 w-6", md: "h-8 w-8", lg: "h-10 w-10" };
+  const padMap: Record<Size, string> = { sm: "h-6 px-2.5", md: "h-8 px-4", lg: "h-10 px-6" };
+  const textMap: Record<Size, string> = { sm: "text-xs", md: "text-sm", lg: "text-base" };
+  const iconMap: Record<Size, string> = {
+    sm: "[&_svg]:w-3.5 [&_svg]:h-3.5",
+    md: "[&_svg]:w-4 [&_svg]:h-4",
+    lg: "[&_svg]:w-5 [&_svg]:h-5",
+  };
+  const sizeClasses = $derived(
+    `${responsiveClasses(size, isIconOnly ? boxMap : padMap)} ${responsiveClasses(size, textMap)}`,
+  );
+  const iconSizeClass = $derived(responsiveClasses(size, iconMap));
+
+  // FILL = background + text + hover-background (no border here — the border is a separate axis so
+  // `borderless` can swap it independently while the 1px box stays constant).
+  const fillClasses = {
+    primary:
+      "[background-color:var(--ui-color-primary)] text-white hover:[background-color:color-mix(in_srgb,var(--ui-color-primary)_90%,black)] [&_svg]:fill-current",
+    secondary:
+      "[background-color:var(--ui-color-secondary)] text-white hover:[background-color:color-mix(in_srgb,var(--ui-color-secondary)_90%,black)] [&_svg]:fill-current",
+    danger:
+      "[background-color:var(--ui-color-error)] text-white hover:[background-color:color-mix(in_srgb,var(--ui-color-error)_90%,black)] [&_svg]:fill-current",
+    info: "[background-color:var(--ui-color-info)] text-white hover:[background-color:color-mix(in_srgb,var(--ui-color-info)_90%,black)] [&_svg]:fill-current",
+    success:
+      "[background-color:var(--ui-color-success)] text-white hover:[background-color:color-mix(in_srgb,var(--ui-color-success)_90%,black)] [&_svg]:fill-current",
+    warning:
+      "[background-color:var(--ui-color-warning)] text-white hover:[background-color:color-mix(in_srgb,var(--ui-color-warning)_90%,black)] [&_svg]:fill-current",
+    // ghost: transparent fill, hover-tint only — the minimal button (table chrome, pagination).
+    ghost:
+      "bg-transparent [color:var(--ui-color-text)] hover:[background-color:var(--ui-color-hover)] [&_svg]:fill-current",
+    // neutral: SOLID, like the accent variants but coloured by --ui-color-text — solid text-colour fill
+    // with contrasting (background-colour) text. Black-on-white / white-on-black. Hover lifts to bg.
+    neutral:
+      "[background-color:var(--ui-color-text)] [color:var(--ui-color-background)] hover:[background-color:color-mix(in_srgb,var(--ui-color-text)_85%,var(--ui-color-background))] [&_svg]:fill-current",
+  };
+
+  // borderless=true (default): border tracks the fill (incl. hover) → an invisible, space-preserving ring.
+  const borderMatchClasses = {
+    primary:
+      "[border-color:var(--ui-color-primary)] hover:[border-color:color-mix(in_srgb,var(--ui-color-primary)_90%,black)]",
+    secondary:
+      "[border-color:var(--ui-color-secondary)] hover:[border-color:color-mix(in_srgb,var(--ui-color-secondary)_90%,black)]",
+    danger:
+      "[border-color:var(--ui-color-error)] hover:[border-color:color-mix(in_srgb,var(--ui-color-error)_90%,black)]",
+    info: "[border-color:var(--ui-color-info)] hover:[border-color:color-mix(in_srgb,var(--ui-color-info)_90%,black)]",
+    success:
+      "[border-color:var(--ui-color-success)] hover:[border-color:color-mix(in_srgb,var(--ui-color-success)_90%,black)]",
+    warning:
+      "[border-color:var(--ui-color-warning)] hover:[border-color:color-mix(in_srgb,var(--ui-color-warning)_90%,black)]",
+    ghost: "border-transparent hover:[border-color:var(--ui-color-hover)]",
+    neutral:
+      "[border-color:var(--ui-color-text)] hover:[border-color:color-mix(in_srgb,var(--ui-color-text)_85%,var(--ui-color-background))]",
+  };
+
+  // borderless=false: the standard contrasting tint-border — the SAME calc as Input/Card (token @
+  // --ui-tint-border at rest, @ --ui-tint-border-hover on hover). On ghost/neutral (token =
+  // --ui-color-text) this is the outline button; on solids, an accent rim that strengthens on hover.
+  const borderTintClasses = {
+    primary:
+      "[border-color:color-mix(in_srgb,var(--ui-color-primary)_var(--ui-tint-border),transparent)] hover:[border-color:color-mix(in_srgb,var(--ui-color-primary)_var(--ui-tint-border-hover),transparent)]",
+    secondary:
+      "[border-color:color-mix(in_srgb,var(--ui-color-secondary)_var(--ui-tint-border),transparent)] hover:[border-color:color-mix(in_srgb,var(--ui-color-secondary)_var(--ui-tint-border-hover),transparent)]",
+    danger:
+      "[border-color:color-mix(in_srgb,var(--ui-color-error)_var(--ui-tint-border),transparent)] hover:[border-color:color-mix(in_srgb,var(--ui-color-error)_var(--ui-tint-border-hover),transparent)]",
+    info: "[border-color:color-mix(in_srgb,var(--ui-color-info)_var(--ui-tint-border),transparent)] hover:[border-color:color-mix(in_srgb,var(--ui-color-info)_var(--ui-tint-border-hover),transparent)]",
+    success:
+      "[border-color:color-mix(in_srgb,var(--ui-color-success)_var(--ui-tint-border),transparent)] hover:[border-color:color-mix(in_srgb,var(--ui-color-success)_var(--ui-tint-border-hover),transparent)]",
+    warning:
+      "[border-color:color-mix(in_srgb,var(--ui-color-warning)_var(--ui-tint-border),transparent)] hover:[border-color:color-mix(in_srgb,var(--ui-color-warning)_var(--ui-tint-border-hover),transparent)]",
+    ghost:
+      "[border-color:color-mix(in_srgb,var(--ui-color-text)_var(--ui-tint-border),transparent)] hover:[border-color:color-mix(in_srgb,var(--ui-color-text)_var(--ui-tint-border-hover),transparent)]",
+    neutral:
+      "[border-color:color-mix(in_srgb,var(--ui-color-text)_var(--ui-tint-border),transparent)] hover:[border-color:color-mix(in_srgb,var(--ui-color-text)_var(--ui-tint-border-hover),transparent)]",
+  };
+
+  // Build final classes - reactive to variant changes
+  const buttonClasses = $derived(
+    [
+      baseClasses,
+      sizeClasses,
+      responsiveClasses(variant, fillClasses),
+      responsiveClasses(variant, borderless ? borderMatchClasses : borderTintClasses),
+      disabledClasses,
+      additionalClass,
+    ]
+      .filter(Boolean)
+      .join(" "),
+  );
+</script>
+
+<!-- Icon slot, sized by the lib; color comes from the variant's [&_svg]:fill-current. -->
+{#snippet iconSlot()}
+  <span class="inline-flex {iconSizeClass}">{@render icon?.()}</span>
+{/snippet}
+
+{#if href}
+  <a
+    bind:this={element}
+    {href}
+    use:tooltip={{ text: title ?? undefined }}
+    {onclick}
+    {onmouseenter}
+    {onmouseleave}
+    class={buttonClasses}
+    {...restProps as HTMLAnchorAttributes}
+  >
+    <div class="{text || children ? '-translate-y-px' : ''} flex items-center gap-2">
+      {#if hasProps}
+        {#if isIconOnly}
+          {@render iconSlot()}
+        {:else}
+          {#if icon}
+            {@render iconSlot()}
+          {/if}
+          {#if text}
+            <span>{text}</span>
+          {/if}
+        {/if}
+      {:else if children}
+        {@render children()}
+      {/if}
+    </div>
+  </a>
+{:else}
+  <button
+    bind:this={element}
+    {type}
+    {disabled}
+    aria-disabled={disabled}
+    use:tooltip={{ text: title ?? undefined }}
+    {onclick}
+    {onmouseenter}
+    {onmouseleave}
+    class={buttonClasses}
+    {...restProps as HTMLButtonAttributes}
+  >
+    <div class="{text || children ? '-translate-y-px' : ''} flex items-center gap-2">
+      {#if hasProps}
+        {#if isIconOnly}
+          {@render iconSlot()}
+        {:else}
+          {#if icon}
+            {@render iconSlot()}
+          {/if}
+          {#if text}
+            <span>{text}</span>
+          {/if}
+        {/if}
+      {:else if children}
+        {@render children()}
+      {/if}
+    </div>
+  </button>
+{/if}

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

@@ -0,0 +1,33 @@
+import type { Snippet } from "svelte";
+import type { Variant } from "../types/variants.js";
+import type { Size } from "../types/sizes.js";
+import { type Responsive } from "../types/responsive.js";
+import type { HTMLButtonAttributes, HTMLAnchorAttributes } from "svelte/elements";
+interface BaseProps {
+    /** Icon slot — consumer-rendered (e.g. an MDI `~icons/mdi/*` component). */
+    icon?: Snippet;
+    text?: string;
+    variant?: Responsive<Variant>;
+    size?: Responsive<Size>;
+    /** Border colour matches the fill (invisible ring, box unchanged) — the default. Set
+     *  `borderless={false}` for the standard contrasting tint-border; on the `ghost` variant that's
+     *  the "outline button" (transparent fill + a 30% text-tint edge), no separate variant needed. */
+    borderless?: boolean;
+    children?: Snippet;
+    onclick?: (event: MouseEvent) => void;
+    onmouseenter?: (event: MouseEvent) => void;
+    onmouseleave?: (event: MouseEvent) => void;
+    element?: HTMLButtonElement | HTMLAnchorElement;
+}
+interface ButtonProps extends BaseProps, Omit<HTMLButtonAttributes, keyof BaseProps> {
+    href?: never;
+}
+interface AnchorProps extends BaseProps, Omit<HTMLAnchorAttributes, keyof BaseProps | "type"> {
+    href: string;
+    type?: never;
+    disabled?: never;
+}
+export type Props = ButtonProps | AnchorProps;
+declare const Button: import("svelte").Component<Props, {}, "element">;
+type Button = ReturnType<typeof Button>;
+export default Button;

package/dist/components/ButtonDropdown.svelte

@@ -0,0 +1,145 @@
+<!--
+/**
+ * ButtonDropdown — a split-button compound built from Button + Menu.
+ *
+ * Same prop surface as Button (variant, size, icon, text, children,
+ * disabled, onclick, …); when `items` is empty/absent it renders
+ * identically to a single Button. With items, it splits into a primary
+ * half (the consumer's button) and a secondary chevron half that opens
+ * a Menu anchored to the chevron.
+ *
+ * Compound rule: nothing in this file builds primitives — it composes
+ * Button + Menu. The split visual is enforced by overriding the two
+ * halves' rounded corners + adjacent border via the {class} prop both
+ * Buttons already accept; the outer wrapper carries the shape so a
+ * consumer-applied shadow (e.g. `class="shadow-md"`) lands on the
+ * combined silhouette rather than splitting at the seam between the
+ * two halves.
+ */
+-->
+<script lang="ts">
+  import ChevronDown from "~icons/mdi/chevron-down";
+  import Button from "./Button.svelte";
+  import Menu from "./Menu.svelte";
+  import type { Variant } from "../types/variants.js";
+  import type { Size } from "../types/sizes.js";
+  import type { Responsive } from "../types/responsive.js";
+  import type { Snippet } from "svelte";
+  import type { MenuItem } from "../data/table/types.js";
+
+  // Mirrors Button's button-flavour Props (the anchor-flavour `href` is
+  // intentionally not on offer here — a split-button's two halves can't
+  // both be a single navigation target). Adds `items`.
+  interface Props {
+    /** Icon slot for the primary half — same contract as Button.icon. */
+    icon?: Snippet;
+    text?: string;
+    variant?: Variant;
+    size?: Responsive<Size>;
+    children?: Snippet;
+    disabled?: boolean;
+    type?: "button" | "submit" | "reset";
+    title?: string;
+    /** Append-extra classes — applied to the OUTER wrapper so consumer
+     *  styling (margin, shadow, alignment) targets the combined shape
+     *  rather than just one half. */
+    class?: string;
+    onclick?: (event: MouseEvent) => void;
+    /** Menu items shown when the chevron is clicked. Empty / absent →
+     *  the component degrades gracefully to a plain Button. */
+    items?: MenuItem[];
+    /** Menu placement passed through to `<Menu>`. Defaults match the
+     *  ActionBar split-button convention: opens below, right-aligned. */
+    menuSide?: "top" | "bottom" | "left" | "right";
+    menuAlign?: "start" | "center" | "end";
+  }
+
+  let {
+    icon,
+    text,
+    variant = "secondary",
+    size = "md",
+    children,
+    disabled = false,
+    type = "button",
+    title,
+    class: additionalClass = "",
+    onclick,
+    items,
+    menuSide = "bottom",
+    menuAlign = "end",
+  }: Props = $props();
+
+  // No items → degrade to a plain Button with the exact same prop
+  // surface. Keeps `<ButtonDropdown {variant} {size} text="…" />`
+  // usable as a drop-in for sites that may or may not declare items
+  // dynamically.
+  const hasItems = $derived(!!items && items.length > 0);
+
+  // Chevron-half state. `chevronEl` is what Menu anchors against; the
+  // element gets bound through Button's existing `bind:element` prop so
+  // we never poke at the DOM ourselves.
+  let menuOpen = $state(false);
+  let chevronEl = $state<HTMLButtonElement | HTMLAnchorElement | undefined>(undefined);
+
+  // Class overrides applied via Button's {class} pass-through. The
+  // outer wrapper is `inline-flex` and the two halves abut; we strip
+  // the inner corners + the primary's right border so the seam reads
+  // as a single divider rather than two stacked borders.
+  const primaryHalfClass = "rounded-r-none border-r-0";
+  const secondaryHalfClass = "rounded-l-none px-2";
+</script>
+
+{#if hasItems}
+  <span class="inline-flex {additionalClass}">
+    <Button
+      {icon}
+      {text}
+      {children}
+      {variant}
+      {size}
+      {disabled}
+      {type}
+      {title}
+      {onclick}
+      class={primaryHalfClass}
+    />
+    <Button
+      {variant}
+      {size}
+      {disabled}
+      type="button"
+      title="More actions"
+      aria-haspopup="menu"
+      aria-expanded={menuOpen}
+      onclick={() => (menuOpen = !menuOpen)}
+      bind:element={chevronEl}
+      class={secondaryHalfClass}
+      icon={chevronIcon}
+    />
+  </span>
+  <Menu
+    anchor={chevronEl as HTMLElement | undefined}
+    bind:open={menuOpen}
+    items={items!}
+    side={menuSide}
+    align={menuAlign}
+  />
+{:else}
+  <Button
+    {icon}
+    {text}
+    {children}
+    {variant}
+    {size}
+    {disabled}
+    {type}
+    {title}
+    {onclick}
+    class={additionalClass}
+  />
+{/if}
+
+{#snippet chevronIcon()}
+  <ChevronDown />
+{/snippet}

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

@@ -0,0 +1,31 @@
+import type { Variant } from "../types/variants.js";
+import type { Size } from "../types/sizes.js";
+import type { Responsive } from "../types/responsive.js";
+import type { Snippet } from "svelte";
+import type { MenuItem } from "../data/table/types.js";
+interface Props {
+    /** Icon slot for the primary half — same contract as Button.icon. */
+    icon?: Snippet;
+    text?: string;
+    variant?: Variant;
+    size?: Responsive<Size>;
+    children?: Snippet;
+    disabled?: boolean;
+    type?: "button" | "submit" | "reset";
+    title?: string;
+    /** Append-extra classes — applied to the OUTER wrapper so consumer
+     *  styling (margin, shadow, alignment) targets the combined shape
+     *  rather than just one half. */
+    class?: string;
+    onclick?: (event: MouseEvent) => void;
+    /** Menu items shown when the chevron is clicked. Empty / absent →
+     *  the component degrades gracefully to a plain Button. */
+    items?: MenuItem[];
+    /** Menu placement passed through to `<Menu>`. Defaults match the
+     *  ActionBar split-button convention: opens below, right-aligned. */
+    menuSide?: "top" | "bottom" | "left" | "right";
+    menuAlign?: "start" | "center" | "end";
+}
+declare const ButtonDropdown: import("svelte").Component<Props, {}, "">;
+type ButtonDropdown = ReturnType<typeof ButtonDropdown>;
+export default ButtonDropdown;