@supertype.ai/foundations 0.1.28 → 0.1.30

package/dist/blocks/card.js

@@ -1,6 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { cn } from "../cn.js";
-import { Link } from "next-view-transitions";
+import { FOCUS_RING } from "./focus.js";
+import { inkOnSurface, toneClass } from "../tone.js";
+import { resolveLink } from "../href.js";
 /** Two columns from `sm` up: a pair reads as a set rather than two panels. */
 export function Cards({ className, children, ...props }) {
     return (_jsx("div", { className: cn("my-6 grid gap-4 sm:grid-cols-2", className), ...props, children: children }));
@@ -10,9 +12,20 @@ export function Cards({ className, children, ...props }) {
  * grid and `overflow-hidden` clips a bleed image cleanly. Padding is vertical
  * only — the horizontal inset belongs to the slots, so bands can run edge to edge.
  */
-const CARD_CLASS = "flex flex-col gap-4 overflow-hidden rounded-xl bg-card py-4 text-sm text-card-foreground ring-1 ring-border " +
+const CARD_CLASS = `flex flex-col gap-4 overflow-hidden rounded-xl bg-card py-4 text-sm text-card-foreground ring-1 ring-border ${inkOnSurface("--card-foreground")} ` +
     "has-[>img:first-child]:pt-0 " +
     "*:[img:first-child]:rounded-t-xl *:[img:last-child]:rounded-b-xl";
+/**
+ * What a card does when it is a link, which is the only time it does anything: two pixels
+ * up, a shadow under it, the ring firming from `--border` to a cut of the page's own ink.
+ * Following a link is not a colour, so nothing here is one — `--elevation-raised` is the
+ * token for a layer leaving the page plane, and that is the whole gesture. The lift is
+ * `motion-safe:` and the shadow is not, so reduced motion keeps the affordance.
+ *
+ * `toneClass` is declared here so the icon below can take `--tone-hue` rather than naming
+ * a token, the way every other tinted role in the package reads it.
+ */
+const CARD_LINK_CLASS = cn(toneClass("primary"), FOCUS_RING, "group/card no-underline transition duration-200 ease-out", "hover:shadow-raised hover:ring-foreground/15 motion-safe:hover:-translate-y-0.5");
 export function CardHeader({ className, ...props }) {
     return (_jsx("div", { "data-slot": "card-header", className: cn("grid auto-rows-min items-start gap-1 px-4 [.border-b]:pb-4", className), ...props }));
 }
@@ -36,21 +49,24 @@ export function CardContent({ className, ...props }) {
 /**
  * Takes either shape: `title`/`href` fills the header, or compose the slots
  * directly. Unrecognised props pass through — MDX authors reach for the whole
- * HTML surface. An href with a scheme leaves the app; the rest route through
- * the router's Link.
+ * HTML surface. Where the href goes is ../href.ts's call, the same one Button
+ * and TypographyLink make.
  */
-export function Card({ href, className, external, title, description, icon, children, ...rest }) {
-    const header = title || description || icon ? (_jsxs(CardHeader, { children: [icon ? _jsx("div", { className: "mb-1 text-muted-foreground", children: icon }) : null, title ? _jsx(CardTitle, { children: title }) : null, description ? _jsx(CardDescription, { children: description }) : null] })) : null;
+export function Card({ href, className, external, newTab, title, description, icon, children, ...rest }) {
+    const header = title || description || icon ? (_jsxs(CardHeader, { children: [icon || title ? (
+            // The icon sits on the title's line and is its mark; stacked, it read as a
+            // decoration the title happened to follow. `gap-2` is a gap between two
+            // objects, not the header's `gap-1` between two lines.
+            _jsxs("div", { className: "flex items-center gap-2", children: [icon ? (
+                    // Sized here, not at the call site, so two cards cannot disagree about how
+                    // big an icon is. On a link card it takes the tone as the card lifts.
+                    _jsx("span", { className: "shrink-0 text-muted-foreground transition-colors group-hover/card:text-(color:--tone-hue) [&_svg]:size-4 [&_svg]:shrink-0", children: icon })) : null, title ? _jsx(CardTitle, { children: title }) : null] })) : null, description ? _jsx(CardDescription, { children: description }) : null] })) : null;
     // Bare children compose; children under a shorthand header are body copy.
     const body = header ? (_jsxs(_Fragment, { children: [header, children ? _jsx(CardContent, { children: children }) : null] })) : (children);
     const shared = { "data-slot": "card" };
     if (!href) {
         return (_jsx("div", { className: cn(CARD_CLASS, className), ...shared, ...rest, children: body }));
     }
-    const leavesApp = external ?? /^[a-z][a-z0-9+.-]*:/i.test(href);
-    const classes = cn(CARD_CLASS, "no-underline transition-colors hover:bg-accent", className);
-    if (leavesApp) {
-        return (_jsx("a", { href: href, className: classes, target: "_blank", rel: "noopener noreferrer", ...shared, ...rest, children: body }));
-    }
-    return (_jsx(Link, { href: href, className: classes, ...shared, ...rest, children: body }));
+    const { Component, props: link } = resolveLink(href, { external, newTab });
+    return (_jsx(Component, { className: cn(CARD_CLASS, CARD_LINK_CLASS, className), ...link, ...shared, ...rest, children: body }));
 }

package/dist/blocks/focus.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The focus ring, stated once.
+ *
+ * It was five copies — Button, Badge, Accordion, `SEGMENT.item`, and Card, which
+ * added the fifth while its own comment observed that the other four existed.
+ * Retuning the width or the ink was a find-and-replace across five files with no
+ * compiler help if one was missed.
+ */
+export declare const FOCUS_RING = "outline-none focus-visible:ring-3 focus-visible:ring-ring/50";

package/dist/blocks/focus.js

@@ -0,0 +1,9 @@
+/**
+ * The focus ring, stated once.
+ *
+ * It was five copies — Button, Badge, Accordion, `SEGMENT.item`, and Card, which
+ * added the fifth while its own comment observed that the other four existed.
+ * Retuning the width or the ink was a find-and-replace across five files with no
+ * compiler help if one was missed.
+ */
+export const FOCUS_RING = "outline-none focus-visible:ring-3 focus-visible:ring-ring/50";

package/dist/blocks/index.d.ts

@@ -2,6 +2,8 @@ export { Cards, Card, CardHeader, CardTitle, CardDescription, CardContent, } fro
 export { Disclosure, DisclosureGroup } from "./accordion.js";
 export { Accordion, AccordionItem, AccordionTrigger, AccordionContent, } from "./interactive-accordion.js";
 export { Callout } from "./callout.js";
-export { Tabs, TabsList, TabsTrigger, TabsContent, TabGroup, Tab, } from "./tabs.js";
+export { Button, buttonVariants, type ButtonLook } from "./button.js";
+export { Badge, badgeVariants, type BadgeLook } from "./badge.js";
+export { Tabs, TabsList, TabsTrigger, TabsContent, TabGroup, type TabItem, } from "./tabs.js";
 export { SEGMENT } from "./segment.js";
 export { Steps, Step } from "./steps.js";

package/dist/blocks/index.js

@@ -2,6 +2,8 @@ export { Cards, Card, CardHeader, CardTitle, CardDescription, CardContent, } fro
 export { Disclosure, DisclosureGroup } from "./accordion.js";
 export { Accordion, AccordionItem, AccordionTrigger, AccordionContent, } from "./interactive-accordion.js";
 export { Callout } from "./callout.js";
-export { Tabs, TabsList, TabsTrigger, TabsContent, TabGroup, Tab, } from "./tabs.js";
+export { Button, buttonVariants } from "./button.js";
+export { Badge, badgeVariants } from "./badge.js";
+export { Tabs, TabsList, TabsTrigger, TabsContent, TabGroup, } from "./tabs.js";
 export { SEGMENT } from "./segment.js";
 export { Steps, Step } from "./steps.js";

package/dist/blocks/interactive-accordion.js

@@ -8,6 +8,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  */
 import { Accordion as AccordionPrimitive } from "@base-ui/react/accordion";
 import { cn } from "../cn.js";
+import { FOCUS_RING } from "./focus.js";
 function Accordion({ className, ...props }) {
     return (_jsx(AccordionPrimitive.Root, { "data-slot": "accordion", className: cn("flex w-full flex-col", className), ...props }));
 }
@@ -15,7 +16,7 @@ function AccordionItem({ className, ...props }) {
     return (_jsx(AccordionPrimitive.Item, { "data-slot": "accordion-item", className: cn("not-last:border-b", className), ...props }));
 }
 function AccordionTrigger({ className, children, ...props }) {
-    return (_jsx(AccordionPrimitive.Header, { className: "flex", children: _jsxs(AccordionPrimitive.Trigger, { "data-slot": "accordion-trigger", className: cn("group/accordion-trigger relative flex flex-1 items-start justify-between rounded-lg border border-transparent py-2.5 text-left text-sm font-medium transition outline-none hover:underline focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 focus-visible:after:border-ring aria-disabled:pointer-events-none aria-disabled:opacity-50 **:data-[slot=accordion-trigger-icon]:ml-auto **:data-[slot=accordion-trigger-icon]:size-4 **:data-[slot=accordion-trigger-icon]:text-muted-foreground", className), ...props, children: [children, _jsx(Chevron, { className: "group-aria-expanded/accordion-trigger:hidden" }), _jsx(Chevron, { up: true, className: "hidden group-aria-expanded/accordion-trigger:inline" })] }) }));
+    return (_jsx(AccordionPrimitive.Header, { className: "flex", children: _jsxs(AccordionPrimitive.Trigger, { "data-slot": "accordion-trigger", className: cn(FOCUS_RING, "group/accordion-trigger relative flex flex-1 items-start justify-between rounded-lg border border-transparent py-2.5 text-left text-sm font-medium transition hover:underline focus-visible:border-ring focus-visible:after:border-ring aria-disabled:pointer-events-none aria-disabled:opacity-50 **:data-[slot=accordion-trigger-icon]:ml-auto **:data-[slot=accordion-trigger-icon]:size-4 **:data-[slot=accordion-trigger-icon]:text-muted-foreground", className), ...props, children: [children, _jsx(Chevron, { className: "group-aria-expanded/accordion-trigger:hidden" }), _jsx(Chevron, { up: true, className: "hidden group-aria-expanded/accordion-trigger:inline" })] }) }));
 }
 function AccordionContent({ className, children, ...props }) {
     return (_jsx(AccordionPrimitive.Panel, { "data-slot": "accordion-content", className: "overflow-hidden text-sm data-open:animate-accordion-down data-closed:animate-accordion-up", ...props, children: _jsx("div", { className: cn("h-(--accordion-panel-height) pt-0 pb-2.5 data-ending-style:h-0 data-starting-style:h-0 [&_a]:underline [&_a]:underline-offset-3 [&_a]:hover:text-foreground [&_p:not(:last-child)]:mb-4", className), children: children }) }));

package/dist/blocks/render-as.d.ts

@@ -0,0 +1,11 @@
+import { type ReactElement } from "react";
+/**
+ * `render={<a href="…" />}` — the component's classes and data marks put onto an element
+ * the caller supplies, so a badge or a button can BE a link rather than wrap one. A
+ * screen reader announces the element, and the element is the anchor.
+ *
+ * Shared because Button and Badge both do it, identically, for the same reason; both
+ * files' comments used to say so while carrying their own copy. Returns `null` when
+ * `render` is not an element, which is the caller's signal to render its own tag.
+ */
+export declare function renderAs(render: unknown, classes: string, props: Record<string, unknown>): ReactElement | null;

package/dist/blocks/render-as.js

@@ -0,0 +1,22 @@
+import { cloneElement, isValidElement } from "react";
+import { cn } from "../cn.js";
+/**
+ * `render={<a href="…" />}` — the component's classes and data marks put onto an element
+ * the caller supplies, so a badge or a button can BE a link rather than wrap one. A
+ * screen reader announces the element, and the element is the anchor.
+ *
+ * Shared because Button and Badge both do it, identically, for the same reason; both
+ * files' comments used to say so while carrying their own copy. Returns `null` when
+ * `render` is not an element, which is the caller's signal to render its own tag.
+ */
+export function renderAs(render, classes, props) {
+    // `unknown`, because Base UI's `render` is an element OR a render function; only the
+    // element half is ours to clone, and `isValidElement` is the narrowing.
+    if (!isValidElement(render))
+        return null;
+    const { className } = render.props;
+    return cloneElement(render, {
+        ...props,
+        className: cn(classes, className),
+    });
+}

package/dist/blocks/segment.d.ts

@@ -9,29 +9,37 @@
  * class strings, which is exactly the kind of duplication that drifts the first time
  * someone retunes the palette.
  *
- * Some entries appear twice, once bare and once `data-active:`-prefixed. That is not
- * laziness: Tailwind generates a utility only if it appears literally in scanned source, so
- * prefixing at runtime would compile to classes that never got built. Writing both forms
- * side by side is the honest version, and it keeps the pair impossible to change by half.
- *
  * The active segment is deliberately flat — a card surface and a hairline, no shadow.
  * Elevation in this system means "this layer left the page plane" (see --elevation-* in
  * theme.css), and a segment sitting inside its own track has not.
+ *
+ * The other half of that: the segment stays on the page plane because the RAIL drops below
+ * it. The well is the shadow and the hairline, not a fill — the track is `bg-background`
+ * pressed in. A `--muted` rail cannot work, because `--muted` sits below `--card` in light
+ * and above it in dark, so a muted fill reads correct in one theme and inverted in the
+ * other, and `dark:` is what the package's own ESLint rule exists to stop.
  */
 export declare const SEGMENT: {
-    /** The rail a set of segments sits in. Surface only; each component owns its layout. */
-    readonly track: "rounded-lg border border-border bg-muted/40 p-0.5";
+    /**
+     * The rail a set of segments sits in. Surface only; each component owns its layout.
+     *
+     * `rounded-md` over `activeSurface`'s `rounded-sm` is the 2px of `p-0.5`: concentric
+     * radii, so the segment's corner runs parallel to the rail's rather than across it.
+     */
+    readonly track: "rounded-md border border-border bg-background p-0.5 shadow-recessed";
     /** Affordances every segment shares, whatever its shape or engine. */
-    readonly item: "relative inline-flex items-center gap-1.5 font-medium outline-none transition-colors focus-visible:ring-3 focus-visible:ring-ring/50";
+    readonly item: "relative inline-flex items-center gap-1.5 font-medium transition-colors outline-none focus-visible:ring-3 focus-visible:ring-ring/50";
     /** Selected: the ink lifts to full strength. */
     readonly active: "text-foreground";
     /**
      * Unselected: quiet, but lighting its own surface on hover so the whole strip reads as
-     * reachable rather than only the segment already chosen.
+     * reachable rather than only the segment already chosen. It moves toward `activeSurface`
+     * and not toward the rail, so a hover previews being picked.
+     */
+    readonly idle: "text-muted-foreground hover:bg-card/60 hover:text-foreground";
+    /**
+     * The flat surface marking the selection. One string, worn by both engines: the marketing
+     * picker slides it with `motion`, `Tabs` hands it to the element Base UI positions.
      */
-    readonly idle: "text-muted-foreground hover:bg-muted/60 hover:text-foreground";
-    /** The flat surface marking the selection. */
-    readonly activeSurface: "bg-card ring-1 ring-border";
-    /** `activeSurface`, for an engine that marks its own trigger with `data-active`. */
-    readonly dataActiveSurface: "data-active:bg-card data-active:text-foreground data-active:ring-1 data-active:ring-border";
+    readonly activeSurface: "rounded-sm bg-card ring-1 ring-border";
 };

package/dist/blocks/segment.js

@@ -1,3 +1,4 @@
+import { FOCUS_RING } from "./focus.js";
 /**
  * The segmented picker, as one set of surfaces.
  *
@@ -9,29 +10,37 @@
  * class strings, which is exactly the kind of duplication that drifts the first time
  * someone retunes the palette.
  *
- * Some entries appear twice, once bare and once `data-active:`-prefixed. That is not
- * laziness: Tailwind generates a utility only if it appears literally in scanned source, so
- * prefixing at runtime would compile to classes that never got built. Writing both forms
- * side by side is the honest version, and it keeps the pair impossible to change by half.
- *
  * The active segment is deliberately flat — a card surface and a hairline, no shadow.
  * Elevation in this system means "this layer left the page plane" (see --elevation-* in
  * theme.css), and a segment sitting inside its own track has not.
+ *
+ * The other half of that: the segment stays on the page plane because the RAIL drops below
+ * it. The well is the shadow and the hairline, not a fill — the track is `bg-background`
+ * pressed in. A `--muted` rail cannot work, because `--muted` sits below `--card` in light
+ * and above it in dark, so a muted fill reads correct in one theme and inverted in the
+ * other, and `dark:` is what the package's own ESLint rule exists to stop.
  */
 export const SEGMENT = {
-    /** The rail a set of segments sits in. Surface only; each component owns its layout. */
-    track: "rounded-lg border border-border bg-muted/40 p-0.5",
+    /**
+     * The rail a set of segments sits in. Surface only; each component owns its layout.
+     *
+     * `rounded-md` over `activeSurface`'s `rounded-sm` is the 2px of `p-0.5`: concentric
+     * radii, so the segment's corner runs parallel to the rail's rather than across it.
+     */
+    track: "rounded-md border border-border bg-background p-0.5 shadow-recessed",
     /** Affordances every segment shares, whatever its shape or engine. */
-    item: "relative inline-flex items-center gap-1.5 font-medium outline-none transition-colors focus-visible:ring-3 focus-visible:ring-ring/50",
+    item: `relative inline-flex items-center gap-1.5 font-medium transition-colors ${FOCUS_RING}`,
     /** Selected: the ink lifts to full strength. */
     active: "text-foreground",
     /**
      * Unselected: quiet, but lighting its own surface on hover so the whole strip reads as
-     * reachable rather than only the segment already chosen.
+     * reachable rather than only the segment already chosen. It moves toward `activeSurface`
+     * and not toward the rail, so a hover previews being picked.
+     */
+    idle: "text-muted-foreground hover:bg-card/60 hover:text-foreground",
+    /**
+     * The flat surface marking the selection. One string, worn by both engines: the marketing
+     * picker slides it with `motion`, `Tabs` hands it to the element Base UI positions.
      */
-    idle: "text-muted-foreground hover:bg-muted/60 hover:text-foreground",
-    /** The flat surface marking the selection. */
-    activeSurface: "bg-card ring-1 ring-border",
-    /** `activeSurface`, for an engine that marks its own trigger with `data-active`. */
-    dataActiveSurface: "data-active:bg-card data-active:text-foreground data-active:ring-1 data-active:ring-border",
+    activeSurface: "rounded-sm bg-card ring-1 ring-border",
 };

package/dist/blocks/tabs.d.ts

@@ -1,32 +1,67 @@
 import { Tabs as TabsPrimitive } from "@base-ui/react/tabs";
 import type { ReactNode } from "react";
 import { type VariantProps } from "class-variance-authority";
+import { type Tone } from "../tone.js";
 declare function Tabs({ className, orientation, ...props }: TabsPrimitive.Root.Props): import("react").JSX.Element;
+/**
+ * Surfaces come from SEGMENT, so this and marketing/segmented-control cannot drift: a
+ * reader who meets the picker on a docs page and again on the usage dashboard should not
+ * have to learn it twice. Layout stays local, since only this one has orientation to serve.
+ *
+ * Each variant states its own box, rather than sharing a base tuned for the boxed track
+ * that `line` then had to undo at the call site.
+ */
 declare const tabsListVariants: (props?: ({
     variant?: "line" | "default" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
-declare function TabsList({ className, variant, ...props }: TabsPrimitive.List.Props & VariantProps<typeof tabsListVariants>): import("react").JSX.Element;
+/**
+ * `tone` inks the marker, and only the marker. On `line` that is the underline and the
+ * active tab's icon; the boxed track's marker is a card surface and a hairline, which
+ * SEGMENT keeps deliberately flat, so a tone there would be a colour with nothing to
+ * paint. The label stays `--foreground` in both: it is read, not signalled.
+ */
+declare function TabsList({ className, variant, tone, children, ...props }: TabsPrimitive.List.Props & VariantProps<typeof tabsListVariants> & {
+    tone?: Tone;
+}): import("react").JSX.Element;
 declare function TabsTrigger({ className, ...props }: TabsPrimitive.Tab.Props): import("react").JSX.Element;
 declare function TabsContent({ className, ...props }: TabsPrimitive.Panel.Props): import("react").JSX.Element;
+/** One tab, whole: what it is called, what marks it, and what it shows. */
+export type TabItem = {
+    /** Stable across a relabel — it is what `defaultValue` and `onValueChange` speak. */
+    value: string;
+    label: ReactNode;
+    /**
+     * An element — `<Icons.Mic />`, `<PriceChip />` — sized and inked by the trigger.
+     *
+     * An element and not a component, which this briefly also took. `TabGroup` is a client
+     * component, so a component reference handed to it from a server page is a function
+     * crossing the RSC boundary, which React refuses at render; an element is already
+     * rendered and crosses fine. One accepted shape also spares the slot a branch, and
+     * matches what `Card`'s `icon` has always taken.
+     */
+    icon?: ReactNode;
+    content: ReactNode;
+};
 /**
-* The declarative shorthand: `items` plus a `<Tab>` per panel. `TabGroup` is to
- * `Tabs` what `DisclosureGroup` is to `Accordion` — the shape you reach for when
- * the tabs are data, and what an MDX author writes as `<Tabs>`.
+ * The declarative shorthand: the tabs as data. `TabGroup` is to `Tabs` what
+ * `DisclosureGroup` is to `Accordion`: the shape to reach for. An app that rebuilds it
+ * over the primitives ends up re-adding the icon, the change handler and the stable value
+ * by hand.
  *
- * A caller passing data has no value to bind, so children pair with `items`
- * **by position** — `value` on a `<Tab>` is for readability and is not matched,
- * since matching would silently drop a panel on an edited label. Everything
- * below the adapter is the same component the product surfaces use, so a tab
- * strip in the docs and one on a dashboard behave identically.
+ * Everything below the adapter is the same component the product surfaces use, so a tab
+ * strip in the docs and one on a dashboard behave identically. The positional
+ * `items`-plus-children shape lives in the MDX map, the only thing that speaks it.
  */
-export declare function TabGroup({ items, children, className, }: {
-    items: string[];
-    children: ReactNode;
-    className?: string;
-}): import("react").JSX.Element;
-/** `value` names the panel at the call site; it is not used for matching. */
-export declare function Tab({ children }: {
+export declare function TabGroup({ tabs, defaultValue, value, onValueChange, variant, tone, iconPosition, className, }: {
+    tabs: readonly TabItem[];
+    /** Defaults to the first tab, since a picker with nothing picked is not a state. */
+    defaultValue?: string;
+    /** Pass with `onValueChange` to drive it from outside. */
     value?: string;
-    children: ReactNode;
+    onValueChange?: (value: string) => void;
+    variant?: VariantProps<typeof tabsListVariants>["variant"];
+    tone?: Tone;
+    iconPosition?: "inline-start" | "inline-end";
+    className?: string;
 }): import("react").JSX.Element;
 export { Tabs, TabsList, TabsTrigger, TabsContent };

package/dist/blocks/tabs.js

@@ -1,8 +1,9 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Tabs as TabsPrimitive } from "@base-ui/react/tabs";
 import { cva } from "class-variance-authority";
 import { cn } from "../cn.js";
+import { toneClass } from "../tone.js";
 import { SEGMENT } from "./segment.js";
 function Tabs({ className, orientation = "horizontal", ...props }) {
     return (_jsx(TabsPrimitive.Root, { "data-slot": "tabs", "data-orientation": orientation, className: cn(
@@ -12,58 +13,106 @@ function Tabs({ className, orientation = "horizontal", ...props }) {
         // flex container and laid its panels out beside the tab strip.
         "group/tabs flex gap-2 data-[orientation=horizontal]:flex-col", className), ...props }));
 }
-// Surfaces come from SEGMENT, so this and marketing/segmented-control cannot drift: a
-// reader who meets the picker on a docs page and again on the usage dashboard should not
-// have to learn it twice. Layout stays local, since only this one has orientation to serve.
-const tabsListVariants = cva("group/tabs-list inline-flex h-8 w-fit items-center justify-center text-muted-foreground data-[variant=line]:rounded-none", {
+/**
+ * Surfaces come from SEGMENT, so this and marketing/segmented-control cannot drift: a
+ * reader who meets the picker on a docs page and again on the usage dashboard should not
+ * have to learn it twice. Layout stays local, since only this one has orientation to serve.
+ *
+ * Each variant states its own box, rather than sharing a base tuned for the boxed track
+ * that `line` then had to undo at the call site.
+ */
+const tabsListVariants = cva("group/tabs-list inline-flex w-fit items-center text-muted-foreground", {
     variants: {
         variant: {
-            default: SEGMENT.track,
-            line: "gap-1 border-0 bg-transparent",
+            /** The boxed track: one fixed-height rail, segments splitting it evenly. */
+            default: cn(SEGMENT.track, "h-8 justify-center"),
+            /**
+             * A strip of labels over a rule. Free to wrap, so no fixed height — and `pb-2` is
+             * the marker's own room (6px offset plus its 2px), so the list's box contains
+             * everything the list draws and the gaps below measure from the right edge. The
+             * row gap clears the same 8px, or a wrapped row wears the rule above it.
+             */
+            line: "flex-wrap justify-start gap-x-1 gap-y-3 rounded-none border-0 bg-transparent pb-2",
         },
     },
     defaultVariants: {
         variant: "default",
     },
 });
-function TabsList({ className, variant = "default", ...props }) {
-    return (_jsx(TabsPrimitive.List, { "data-slot": "tabs-list", "data-variant": variant, className: cn(tabsListVariants({ variant }), className), ...props }));
+/**
+ * The marker: one element, positioned by Base UI from `--active-tab-left/top/width/height`
+ * on the list, dressed by the variant it is in. It outlives the selection, so it carries
+ * the answer from the old tab to the new instead of being destroyed and rebuilt.
+ *
+ * `data-activation-direction` is `none` before anything is picked, and that is the one case
+ * that must not animate — without the guard every strip on the page slides in from its left
+ * edge on hydration.
+ */
+const tabsIndicatorVariants = cva("pointer-events-none absolute left-0 top-0 w-(--active-tab-width) transition-[translate,width] duration-200 ease-out data-[activation-direction=none]:transition-none motion-reduce:transition-none", {
+    variants: {
+        variant: {
+            /** The pill, on the page plane. The rail below it is what carries the depth. */
+            default: cn(SEGMENT.activeSurface, "h-(--active-tab-height) translate-x-(--active-tab-left) translate-y-(--active-tab-top)"),
+            /**
+             * A rule under the label, clear of the descenders, in the list's tone. The 6px
+             * offset plus its own 2px is the `pb-2` the line list reserves — the two are one
+             * measurement, and changing either alone puts the rule back outside its box.
+             */
+            line: "h-0.5 translate-x-(--active-tab-left) translate-y-[calc(var(--active-tab-top)+var(--active-tab-height)+6px)] rounded-full bg-(--tone-hue)",
+        },
+    },
+    defaultVariants: { variant: "default" },
+});
+/**
+ * `tone` inks the marker, and only the marker. On `line` that is the underline and the
+ * active tab's icon; the boxed track's marker is a card surface and a hairline, which
+ * SEGMENT keeps deliberately flat, so a tone there would be a colour with nothing to
+ * paint. The label stays `--foreground` in both: it is read, not signalled.
+ */
+function TabsList({ className, variant = "default", tone = "primary", children, ...props }) {
+    return (_jsxs(TabsPrimitive.List, { "data-slot": "tabs-list", "data-variant": variant, className: cn("relative", toneClass(tone), tabsListVariants({ variant }), className), ...props, children: [_jsx(TabsPrimitive.Indicator, { renderBeforeHydration: true, className: tabsIndicatorVariants({ variant }) }), children] }));
 }
 function TabsTrigger({ className, ...props }) {
-    return (_jsx(TabsPrimitive.Tab, { "data-slot": "tabs-trigger", className: cn(SEGMENT.item, SEGMENT.dataActiveSurface, "rounded-md text-muted-foreground hover:text-foreground", 
-        // A trigger fills its share of the track and may carry an icon, neither of which a
-        // standalone picker button has to do.
-        "h-[calc(100%-1px)] flex-1 justify-center px-1.5 py-0.5 text-sm whitespace-nowrap disabled:pointer-events-none disabled:opacity-50 has-data-[icon=inline-end]:pr-1 has-data-[icon=inline-start]:pl-1 aria-disabled:pointer-events-none aria-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4", 
-        // The idle hover, scoped to the boxed variant. Spelled out rather than
-        // interpolated: an interpolated class is invisible to Tailwind's scanner and would
-        // compile to nothing at all.
-        "group-data-[variant=default]/tabs-list:not-data-active:hover:bg-muted/60", 
-        // The line variant wears no surface at all; the underline below is its whole signal.
-        "group-data-[variant=line]/tabs-list:bg-transparent group-data-[variant=line]/tabs-list:data-active:bg-transparent group-data-[variant=line]/tabs-list:data-active:ring-0", 
-        // That underline carries the accent rather than plain ink, so it reads as the
-        // brand's marker and not as a bold rule.
-        "after:absolute after:inset-x-0 after:bottom-[-5px] after:h-0.5 after:bg-primary after:opacity-0 after:transition-opacity group-data-[variant=line]/tabs-list:data-active:after:opacity-100", className), ...props }));
+    return (_jsx(TabsPrimitive.Tab, { "data-slot": "tabs-trigger", className: cn(SEGMENT.item, 
+        // Ink only — the surface and the underline belong to the indicator. The radius is
+        // for the hover wash, and matches the marker that wash previews.
+        "rounded-sm text-muted-foreground hover:text-foreground data-active:text-foreground", "px-1.5 py-0.5 text-sm whitespace-nowrap disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4", 
+        // An icon sits inside the label's gap, so the padding on that side comes off.
+        // `TabGroup` writes the `data-icon` these two read.
+        "has-data-[icon=inline-start]:pl-1 has-data-[icon=inline-end]:pr-1", 
+        // Filling the track is the boxed variant's business; a line tab is as wide as its
+        // label. The variant is read off the list's `data-variant` rather than taken as a
+        // prop, so a caller states it once on `TabsList` and not on every trigger.
+        // Selectors are spelled out, never interpolated: Tailwind's scanner cannot see an
+        // interpolated class and would compile nothing.
+        "group-data-[variant=default]/tabs-list:h-full group-data-[variant=default]/tabs-list:flex-1 group-data-[variant=default]/tabs-list:justify-center", 
+        // Hover moves toward the marker's surface, so it previews the selection.
+        "group-data-[variant=default]/tabs-list:not-data-active:hover:bg-card/60", 
+        // The active icon takes the ink the marker is drawn in.
+        "group-data-[variant=line]/tabs-list:data-active:[&_[data-icon]]:text-(color:--tone-hue)", className), ...props }));
 }
 function TabsContent({ className, ...props }) {
     return (_jsx(TabsPrimitive.Panel, { "data-slot": "tabs-content", className: cn("flex-1 text-sm outline-none", className), ...props }));
 }
+/** `data-icon` is the hook the trigger's padding and tone selectors read. */
+function TabIconSlot({ icon, position, }) {
+    return (_jsx("span", { "data-icon": position, className: "flex items-center transition-colors [&_svg]:size-4 [&_svg]:shrink-0", children: icon }));
+}
 /**
-* The declarative shorthand: `items` plus a `<Tab>` per panel. `TabGroup` is to
- * `Tabs` what `DisclosureGroup` is to `Accordion` — the shape you reach for when
- * the tabs are data, and what an MDX author writes as `<Tabs>`.
+ * The declarative shorthand: the tabs as data. `TabGroup` is to `Tabs` what
+ * `DisclosureGroup` is to `Accordion`: the shape to reach for. An app that rebuilds it
+ * over the primitives ends up re-adding the icon, the change handler and the stable value
+ * by hand.
  *
- * A caller passing data has no value to bind, so children pair with `items`
- * **by position** — `value` on a `<Tab>` is for readability and is not matched,
- * since matching would silently drop a panel on an edited label. Everything
- * below the adapter is the same component the product surfaces use, so a tab
- * strip in the docs and one on a dashboard behave identically.
+ * Everything below the adapter is the same component the product surfaces use, so a tab
+ * strip in the docs and one on a dashboard behave identically. The positional
+ * `items`-plus-children shape lives in the MDX map, the only thing that speaks it.
  */
-export function TabGroup({ items, children, className, }) {
-    const panels = Array.isArray(children) ? children : [children];
-    return (_jsxs(Tabs, { defaultValue: 0, className: cn("my-6", className), children: [_jsx(TabsList, { children: items.map((label, i) => (_jsx(TabsTrigger, { value: i, children: label }, label))) }), panels.map((panel, i) => (_jsx(TabsContent, { value: i, className: "pt-2 text-muted-foreground", children: panel }, i)))] }));
-}
-/** `value` names the panel at the call site; it is not used for matching. */
-export function Tab({ children }) {
-    return _jsx(_Fragment, { children: children });
+export function TabGroup({ tabs, defaultValue, value, onValueChange, variant, tone, iconPosition = "inline-start", className, }) {
+    return (
+    // The handler is adapted rather than wrapped when absent: an arrow declared
+    // unconditionally is a function crossing the server boundary on every page that
+    // renders tabs without one.
+    _jsxs(Tabs, { defaultValue: defaultValue ?? tabs[0]?.value, value: value, onValueChange: onValueChange && ((next) => onValueChange(String(next))), className: cn("my-6", className), children: [_jsx(TabsList, { variant: variant, tone: tone, children: tabs.map(({ value: tabValue, label, icon }) => (_jsxs(TabsTrigger, { value: tabValue, children: [icon && iconPosition === "inline-start" && (_jsx(TabIconSlot, { icon: icon, position: "inline-start" })), label, icon && iconPosition === "inline-end" && (_jsx(TabIconSlot, { icon: icon, position: "inline-end" }))] }, tabValue))) }), tabs.map(({ value: tabValue, content }) => (_jsx(TabsContent, { value: tabValue, className: "pt-2 text-muted-foreground", children: content }, tabValue)))] }));
 }
 export { Tabs, TabsList, TabsTrigger, TabsContent };