@vamos-ui/react 0.0.0-stage → 0.3.0

package/dist/components/toast.js

@@ -0,0 +1,142 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { Toaster as Sonner, toast as sonner } from "sonner";
+import { CircleAlert, CircleCheck, Info, TriangleAlert, X } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { useLabels } from "../lib/labels.js";
+import { useLocale } from "../lib/locale.js";
+import { useMediaQuery } from "../lib/use-media-query.js";
+import { buttonVariants } from "./button.js";
+import { Spinner } from "./spinner.js";
+const DURATION = { neutral: 4000, success: 4000, info: 4000, warning: 6000, danger: 8000, loading: Infinity };
+const ENGINE = {
+    neutral: sonner,
+    success: sonner.success,
+    info: sonner.info,
+    warning: sonner.warning,
+    danger: sonner.error,
+    loading: sonner.loading,
+};
+let seq = 0;
+function show(tone, title, o = {}) {
+    const assertive = tone === "danger" || o.important;
+    const duration = o.duration ?? (o.action && tone !== "loading" ? Math.max(6000, DURATION[tone]) : DURATION[tone]);
+    // Own string ids, so the id we return is exactly the one that updates the toast later.
+    const id = o.id ?? `toast-${++seq}`;
+    ENGINE[tone](assertive ? _jsx("span", { role: "alert", children: title }) : title, {
+        id,
+        description: o.description,
+        duration,
+        closeButton: o.closeButton,
+        action: o.action ? { label: o.action.label, onClick: () => o.action.onClick() } : undefined,
+        cancel: o.cancel ? { label: o.cancel.label, onClick: () => o.cancel.onClick?.() } : undefined,
+        onDismiss: o.onDismiss ? () => o.onDismiss() : undefined,
+        onAutoClose: o.onAutoClose ? () => o.onAutoClose() : undefined,
+    });
+    return id;
+}
+/**
+ * Report the result of an action without interrupting. Import it from the kit only — never
+ * from the engine underneath — so it can be swapped later.
+ *
+ * ```ts
+ * toast.success("Post published", { action: { label: "View", onClick: open } });
+ * toast("Contact moved to trash", { action: { label: "Undo", onClick: restore } });
+ * const id = toast.loading("Preparing export…");
+ * toast.success("Export ready", { id });
+ * ```
+ *
+ * Needs one `<Toaster />` in the tree (App shell includes it).
+ */
+export const toast = Object.assign((title, o) => show("neutral", title, o), {
+    success: (title, o) => show("success", title, o),
+    warning: (title, o) => show("warning", title, o),
+    danger: (title, o) => show("danger", title, o),
+    info: (title, o) => show("info", title, o),
+    loading: (title, o) => show("loading", title, o),
+    promise(promise, m) {
+        const p = typeof promise === "function" ? promise() : promise;
+        const id = show("loading", m.loading, { id: m.id, description: m.description });
+        p.then((data) => show("success", typeof m.success === "function" ? m.success(data) : m.success, { id }), (err) => show("danger", typeof m.error === "function" ? m.error(err) : m.error, { id }));
+        return p;
+    },
+    dismiss(id) {
+        sonner.dismiss(id);
+    },
+});
+const toasterLabels = { region: "Notifications", close: "Close" };
+// Only the first mounted <Toaster/> renders, so a second one (a page plus the app shell) never doubles toasts.
+const mounted = [];
+const listeners = new Set();
+const emit = () => listeners.forEach((l) => l());
+const subscribe = (l) => {
+    listeners.add(l);
+    return () => listeners.delete(l);
+};
+function useIsPrimary() {
+    const [id] = React.useState(() => Symbol("toaster"));
+    React.useEffect(() => {
+        mounted.push(id);
+        emit();
+        return () => {
+            mounted.splice(mounted.indexOf(id), 1);
+            emit();
+        };
+    }, [id]);
+    return React.useSyncExternalStore(subscribe, () => mounted[0] === id, () => false);
+}
+function physical(pos, dir) {
+    const [y, x] = pos.split("-");
+    const side = x === "center" ? "center" : (x === "end") === (dir === "ltr") ? "right" : "left";
+    return `${y}-${side}`;
+}
+const toneClass = {
+    default: "tone-neutral",
+    success: "tone-success",
+    info: "tone-info",
+    warning: "tone-warning",
+    error: "tone-danger",
+    loading: "tone-accent",
+};
+/**
+ * Where toasts appear. Mount once near the app root (App shell already does). Styled with
+ * tokens: popover surface, a thin edge in the status colour, the front toast alone blurs.
+ */
+export function Toaster({ position = "bottom-end", mobilePosition = "top-center", max = 3, expand, closeButton, hotkey, offset, className, labels }) {
+    const primary = useIsPrimary();
+    const { dir } = useLocale();
+    const t = useLabels("toast", toasterLabels, labels);
+    const mobile = useMediaQuery("(max-width: 639px)");
+    if (!primary)
+        return null;
+    return (_jsx(Sonner, { position: physical(mobile ? mobilePosition : position, dir), dir: dir, visibleToasts: max, expand: expand, closeButton: closeButton, hotkey: hotkey, offset: offset, gap: 10, containerAriaLabel: t("region"), className: cn("vui-toaster", className), icons: {
+            success: _jsx(CircleCheck, { "aria-hidden": true }),
+            info: _jsx(Info, { "aria-hidden": true }),
+            warning: _jsx(TriangleAlert, { "aria-hidden": true }),
+            error: _jsx(CircleAlert, { "aria-hidden": true }),
+            loading: _jsx(Spinner, { size: "sm" }),
+            close: _jsx(X, { "aria-hidden": true, className: "size-3.5" }),
+        }, toastOptions: {
+            unstyled: true,
+            closeButtonAriaLabel: t("close"),
+            classNames: {
+                toast: cn("vui-toast surface-popover relative flex w-full items-start gap-3 overflow-hidden rounded-ui py-3 ps-4 pe-3 text-sm text-fg [&:has([data-close-button])]:pe-9", 
+                // thin status edge (never the accent colour)
+                "before:absolute before:inset-y-2.5 before:start-0 before:w-[3px] before:rounded-e-full before:bg-(--tone)"),
+                default: toneClass.default,
+                success: toneClass.success,
+                info: toneClass.info,
+                warning: toneClass.warning,
+                error: toneClass.error,
+                loading: cn(toneClass.loading, "before:bg-transparent"),
+                icon: "relative mt-px flex size-[1.15rem] flex-none items-center justify-center text-(--tone)",
+                content: "flex min-w-0 flex-1 flex-col gap-0.5 py-px",
+                title: "leading-[1.35] font-medium text-pretty",
+                description: "text-[13px] leading-[1.4] text-pretty text-fg-muted",
+                actionButton: cn(buttonVariants({ variant: "secondary", size: "xs" }), "self-center"),
+                cancelButton: cn(buttonVariants({ variant: "ghost", size: "xs" }), "self-center text-fg-muted"),
+                closeButton: cn(buttonVariants({ variant: "ghost", size: "icon-xs" }), "absolute end-1.5 top-1.5 size-6! text-fg-subtle hover:text-fg"),
+            },
+        } }));
+}

package/dist/components/toggle.d.ts

@@ -0,0 +1,77 @@
+import * as React from "react";
+import { Toggle as TogglePrimitive, ToggleGroup as ToggleGroupPrimitive } from "radix-ui";
+export declare const toggleVariants: (props?: ({
+    variant?: "outline" | "ghost" | "segmented" | null | undefined;
+    size?: "sm" | "md" | "lg" | "xs" | null | undefined;
+    iconOnly?: boolean | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+type ToggleVariant = "ghost" | "outline" | "segmented";
+type ToggleSize = "xs" | "sm" | "md" | "lg";
+export interface ToggleProps extends Omit<React.ComponentPropsWithoutRef<typeof TogglePrimitive.Root>, "aria-label"> {
+    variant?: Exclude<ToggleVariant, "segmented">;
+    size?: ToggleSize;
+    /** Accessible name — required when the toggle shows only an icon. */
+    label?: string;
+    "aria-label"?: string;
+}
+/**
+ * A two-state button (`aria-pressed`): Bold in an editor toolbar, "Show archived", pin.
+ *
+ * ```tsx
+ * <Toggle label="Bold" size="sm"><Bold /></Toggle>
+ * <Toggle variant="outline" defaultPressed>Show archived</Toggle>
+ * ```
+ */
+export declare const Toggle: React.ForwardRefExoticComponent<ToggleProps & React.RefAttributes<HTMLButtonElement>>;
+interface ToggleGroupBaseProps {
+    /**
+     * `"segmented"` (default): an inset track with a raised thumb — view switches (List / Board).
+     * `"outline"`: attached bordered buttons — text alignment, formatting.
+     * `"ghost"`: loose toolbar buttons.
+     */
+    variant?: ToggleVariant;
+    size?: ToggleSize;
+    orientation?: "horizontal" | "vertical";
+    /** Stretch to the container width; items share the space. */
+    block?: boolean;
+    disabled?: boolean;
+    className?: string;
+    children?: React.ReactNode;
+}
+export interface ToggleGroupSingleProps extends ToggleGroupBaseProps, Omit<React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Root>, "type" | "value" | "defaultValue" | "onValueChange" | "orientation" | "dir"> {
+    type?: "single";
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (value: string) => void;
+    /** Allow pressing the active item again to clear the selection. Default `false` — a view switch always has a view. */
+    allowEmpty?: boolean;
+}
+export interface ToggleGroupMultipleProps extends ToggleGroupBaseProps, Omit<React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Root>, "type" | "value" | "defaultValue" | "onValueChange" | "orientation" | "dir"> {
+    type: "multiple";
+    value?: string[];
+    defaultValue?: string[];
+    onValueChange?: (value: string[]) => void;
+    allowEmpty?: never;
+}
+export type ToggleGroupProps = ToggleGroupSingleProps | ToggleGroupMultipleProps;
+/**
+ * A set of toggles with roving focus (one tab stop, arrow keys move): view switches, alignment,
+ * filters. `type="single"` (default) keeps exactly one item on; `type="multiple"` for B / I / U.
+ * Use RadioGroup `variant="segmented"` instead when the choice is a form value.
+ *
+ * ```tsx
+ * <ToggleGroup aria-label="View" defaultValue="board">
+ *   <ToggleGroupItem value="list"><List /> List</ToggleGroupItem>
+ *   <ToggleGroupItem value="board"><Kanban /> Board</ToggleGroupItem>
+ * </ToggleGroup>
+ * ```
+ */
+export declare const ToggleGroup: React.ForwardRefExoticComponent<ToggleGroupProps & React.RefAttributes<HTMLDivElement>>;
+export interface ToggleGroupItemProps extends Omit<React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Item>, "aria-label"> {
+    /** Accessible name — required when the item shows only an icon. */
+    label?: string;
+    "aria-label"?: string;
+}
+/** One toggle inside a `ToggleGroup`. */
+export declare const ToggleGroupItem: React.ForwardRefExoticComponent<ToggleGroupItemProps & React.RefAttributes<HTMLButtonElement>>;
+export {};

package/dist/components/toggle.js

@@ -0,0 +1,109 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { Toggle as TogglePrimitive, ToggleGroup as ToggleGroupPrimitive } from "radix-ui";
+import { cva } from "class-variance-authority";
+import { cn } from "../lib/cn.js";
+export const toggleVariants = cva([
+    "relative inline-flex shrink-0 select-none items-center justify-center gap-1.5 whitespace-nowrap font-medium outline-none",
+    "transition-[background-color,color,box-shadow,border-color] duration-150 focus-ring [&_svg]:shrink-0",
+    "disabled:pointer-events-none disabled:opacity-45",
+], {
+    variants: {
+        variant: {
+            /** Toolbar look: transparent until hovered; pressed = tinted. */
+            ghost: "text-fg-muted hover:bg-hover hover:text-fg data-[state=on]:bg-selected data-[state=on]:text-fg",
+            /** Bordered, like a secondary button; pressed = tinted + stronger edge. */
+            outline: "border border-field-border bg-field text-fg-muted hover:border-field-border-hover hover:text-fg glass:border-field-border-hover data-[state=on]:border-field-border-hover data-[state=on]:bg-selected data-[state=on]:text-fg",
+            /** Moving-thumb look used inside a segmented ToggleGroup. */
+            segmented: "text-fg-muted hover:text-fg data-[state=on]:bg-(--segment-thumb) data-[state=on]:text-fg data-[state=on]:shadow-(--segment-thumb-shadow) focus-visible:outline-offset-0",
+        },
+        size: {
+            xs: "h-7 rounded-ui-sm px-2 text-xs [&_svg]:size-3.5",
+            sm: "h-8 rounded-ui-sm px-2.5 text-[13px] [&_svg]:size-4",
+            md: "h-(--control-h) rounded-ui px-3 text-sm [&_svg]:size-4",
+            lg: "h-12 rounded-ui px-4 text-[15px] [&_svg]:size-[18px]",
+        },
+        iconOnly: { true: "aspect-square px-0" },
+    },
+    defaultVariants: { variant: "ghost", size: "md" },
+});
+/**
+ * A two-state button (`aria-pressed`): Bold in an editor toolbar, "Show archived", pin.
+ *
+ * ```tsx
+ * <Toggle label="Bold" size="sm"><Bold /></Toggle>
+ * <Toggle variant="outline" defaultPressed>Show archived</Toggle>
+ * ```
+ */
+export const Toggle = React.forwardRef(function Toggle({ variant = "ghost", size = "md", label, className, children, title, ...props }, ref) {
+    const iconOnly = Boolean(label) && !hasText(children);
+    return (_jsx(TogglePrimitive.Root, { ref: ref, "data-slot": "toggle", "aria-label": props["aria-label"] ?? (iconOnly ? label : undefined), title: title ?? (iconOnly ? label : undefined), className: cn(toggleVariants({ variant, size, iconOnly }), className), ...props, children: children }));
+});
+function hasText(node) {
+    let found = false;
+    React.Children.forEach(node, (c) => {
+        if (typeof c === "string" ? c.trim() !== "" : typeof c === "number")
+            found = true;
+        else if (React.isValidElement(c) && c.props.children && (typeof c.type === "string" || c.type === React.Fragment))
+            found ||= hasText(c.props.children);
+    });
+    return found;
+}
+const ToggleGroupContext = React.createContext({ variant: "outline", size: "md" });
+const trackClass = (orientation) => cn("gap-0.5 rounded-ui border border-line bg-selected p-[3px]", orientation === "vertical" ? "flex-col" : "");
+/**
+ * A set of toggles with roving focus (one tab stop, arrow keys move): view switches, alignment,
+ * filters. `type="single"` (default) keeps exactly one item on; `type="multiple"` for B / I / U.
+ * Use RadioGroup `variant="segmented"` instead when the choice is a form value.
+ *
+ * ```tsx
+ * <ToggleGroup aria-label="View" defaultValue="board">
+ *   <ToggleGroupItem value="list"><List /> List</ToggleGroupItem>
+ *   <ToggleGroupItem value="board"><Kanban /> Board</ToggleGroupItem>
+ * </ToggleGroup>
+ * ```
+ */
+export const ToggleGroup = React.forwardRef(function ToggleGroup(props, ref) {
+    const { variant = "segmented", size = "md", orientation = "horizontal", block, className, children, ...rest } = props;
+    const ctx = React.useMemo(() => ({ variant, size }), [variant, size]);
+    const layout = cn("relative isolate items-stretch", block ? "flex w-full [&>*]:flex-1" : "inline-flex w-fit max-w-full", orientation === "vertical" && "flex-col", variant === "segmented" && trackClass(orientation), 
+    // A segmented track wider than its column (long labels on a phone) scrolls inside itself
+    // instead of pushing the page sideways; its padding keeps the items' focus ring visible.
+    variant === "segmented" && orientation === "horizontal" && !block && "scrollbar-none overflow-x-auto overscroll-x-contain", variant === "ghost" && "gap-0.5", variant === "outline" &&
+        (orientation === "vertical"
+            ? "[&>*:not(:first-child)]:-mt-px [&>*:not(:first-child)]:rounded-t-none [&>*:not(:last-child)]:rounded-b-none"
+            : "[&>*:not(:first-child)]:-ms-px [&>*:not(:first-child)]:rounded-s-none [&>*:not(:last-child)]:rounded-e-none"), variant === "outline" && "[&>*:focus-visible]:z-10 [&>[data-state=on]]:z-[1]", className);
+    const common = { ref, "data-slot": "toggle-group", "data-variant": variant, orientation, className: layout };
+    if (rest.type === "multiple") {
+        const { type: _t, allowEmpty: _a, ...multi } = rest;
+        return (_jsx(ToggleGroupPrimitive.Root, { type: "multiple", ...multi, ...common, children: _jsx(ToggleGroupContext.Provider, { value: ctx, children: children }) }));
+    }
+    return (_jsx(SingleToggleGroup, { ...rest, common: common, children: _jsx(ToggleGroupContext.Provider, { value: ctx, children: children }) }));
+});
+function SingleToggleGroup({ value, defaultValue, onValueChange, allowEmpty = false, type: _type, common, children, ...props }) {
+    const [inner, setInner] = React.useState(defaultValue ?? "");
+    const current = value !== undefined ? value : inner;
+    return (_jsx(ToggleGroupPrimitive.Root, { type: "single", ...props, ...common, value: current, onValueChange: (next) => {
+            if (!next && !allowEmpty)
+                return;
+            if (value === undefined)
+                setInner(next);
+            onValueChange?.(next);
+        }, children: children }));
+}
+/** One toggle inside a `ToggleGroup`. */
+export const ToggleGroupItem = React.forwardRef(function ToggleGroupItem({ label, className, children, title, ...props }, ref) {
+    const { variant, size } = React.useContext(ToggleGroupContext);
+    const iconOnly = Boolean(label) && !hasText(children);
+    const segmentSize = variant === "segmented"
+        ? size === "xs"
+            ? "h-[calc(1.75rem-8px)] rounded-[4px]"
+            : size === "sm"
+                ? "h-[calc(2rem-8px)] rounded-[5px]"
+                : size === "lg"
+                    ? "h-[calc(3rem-8px)] rounded-[calc(var(--radius)-5px)]"
+                    : "h-[calc(var(--control-h)-8px)] rounded-[calc(var(--radius)-5px)]"
+        : undefined;
+    return (_jsx(ToggleGroupPrimitive.Item, { ref: ref, "data-slot": "toggle-group-item", "aria-label": props["aria-label"] ?? (iconOnly ? label : undefined), title: title ?? (iconOnly ? label : undefined), className: cn(toggleVariants({ variant, size, iconOnly }), segmentSize, className), ...props, children: children }));
+});

package/dist/components/tooltip.d.ts

@@ -0,0 +1,69 @@
+import * as React from "react";
+import { Tooltip as TooltipPrimitive } from "radix-ui";
+import { type VariantProps } from "class-variance-authority";
+/** `true` when a `TooltipProvider` is above this point (IconButton switches from `title` to Tooltip). */
+export declare function useHasTooltipProvider(): boolean;
+export interface TooltipProviderProps extends React.ComponentProps<typeof TooltipPrimitive.Provider> {
+}
+/**
+ * Shares open/skip timing between every tooltip below it: once one tooltip has opened, moving
+ * to the next opens it instantly. Put one at the app root (App shell ships it).
+ * Inside a provider, `IconButton` shows its `label` as a Tooltip instead of the native `title`.
+ */
+export declare function TooltipProvider({ delayDuration, skipDelayDuration, ...props }: TooltipProviderProps): React.JSX.Element;
+export interface TooltipRootProps extends React.ComponentProps<typeof TooltipPrimitive.Root> {
+}
+/** Compound root. Works with or without a surrounding `TooltipProvider`. */
+export declare function TooltipRoot(props: TooltipRootProps): React.JSX.Element;
+export declare const TooltipTrigger: React.ForwardRefExoticComponent<TooltipPrimitive.TooltipTriggerProps & React.RefAttributes<HTMLButtonElement>>;
+export declare const tooltipContentVariants: (props?: ({
+    tone?: "default" | "inverted" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export interface TooltipContentProps extends React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content>, VariantProps<typeof tooltipContentVariants> {
+    /** Show the pointer arrow. Default `false`. */
+    arrow?: boolean;
+    /** Shortcut hint after the text, e.g. `"mod+e"` or `["mod", "e"]` (rendered with Kbd). */
+    shortcut?: string | string[];
+}
+export declare const TooltipContent: React.ForwardRefExoticComponent<TooltipContentProps & React.RefAttributes<HTMLDivElement>>;
+export interface TooltipProps extends Omit<TooltipContentProps, "content" | "children"> {
+    /** Tooltip text. Empty / `null` renders the trigger without a tooltip. */
+    content: React.ReactNode;
+    /** The trigger. Rendered with `asChild`, so it must accept a ref (Button, IconButton, `<a>`…). */
+    children: React.ReactElement;
+    /** Open delay in ms (overrides the provider's 400 ms). */
+    delay?: number;
+    /** Render the trigger without a tooltip. */
+    disabled?: boolean;
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+}
+/**
+ * A short label for an icon button or abbreviation. Opens on hover and focus, closes on Esc.
+ * Never shown on touch screens, so it can't be the only place a piece of information lives.
+ *
+ * ```tsx
+ * <Tooltip content="Edit post" shortcut="mod+e">
+ *   <IconButton label="Edit post"><Pencil /></IconButton>
+ * </Tooltip>
+ * ```
+ *
+ * A disabled button fires no pointer events, so a disabled child is wrapped in a focusable
+ * `<span>` automatically — use it to explain *why* the action is unavailable.
+ */
+export declare function Tooltip({ content, children, delay, disabled, open, defaultOpen, onOpenChange, ...contentProps }: TooltipProps): React.JSX.Element;
+export interface IconButtonTooltipProps {
+    /** Text shown in the tooltip (or the `title` fallback). */
+    label: string;
+    /** `"auto"`: Tooltip inside a `TooltipProvider`, native `title` otherwise. `true`: always a Tooltip. */
+    mode?: "auto" | "always";
+    side?: TooltipContentProps["side"];
+    shortcut?: TooltipContentProps["shortcut"];
+    children: React.ReactElement;
+}
+/**
+ * Used by `IconButton`: shows `label` as a Tooltip when a `TooltipProvider` is present,
+ * and falls back to the native `title` attribute when it isn't (so code without a provider keeps working).
+ */
+export declare function IconButtonTooltip({ label, mode, side, shortcut, children }: IconButtonTooltipProps): React.JSX.Element;

package/dist/components/tooltip.js

@@ -0,0 +1,105 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Slot, Tooltip as TooltipPrimitive } from "radix-ui";
+import { cva } from "class-variance-authority";
+import { cn } from "../lib/cn.js";
+import { usePortalContainer } from "../lib/theme-scope.js";
+import { FloatingArrow } from "../lib/floating-arrow.js";
+import { KbdGroup } from "./kbd.js";
+/* ------------------------------------------------------------------ */
+/* Provider                                                            */
+/* ------------------------------------------------------------------ */
+const TooltipProviderContext = React.createContext(false);
+/** `true` when a `TooltipProvider` is above this point (IconButton switches from `title` to Tooltip). */
+export function useHasTooltipProvider() {
+    return React.useContext(TooltipProviderContext);
+}
+/**
+ * Shares open/skip timing between every tooltip below it: once one tooltip has opened, moving
+ * to the next opens it instantly. Put one at the app root (App shell ships it).
+ * Inside a provider, `IconButton` shows its `label` as a Tooltip instead of the native `title`.
+ */
+export function TooltipProvider({ delayDuration = 400, skipDelayDuration = 300, ...props }) {
+    return (_jsx(TooltipProviderContext.Provider, { value: true, children: _jsx(TooltipPrimitive.Provider, { delayDuration: delayDuration, skipDelayDuration: skipDelayDuration, ...props }) }));
+}
+/** Wraps in a provider only when none is present (Radix requires one). */
+function EnsureProvider({ children }) {
+    return useHasTooltipProvider() ? _jsx(_Fragment, { children: children }) : _jsx(TooltipProvider, { children: children });
+}
+/** Compound root. Works with or without a surrounding `TooltipProvider`. */
+export function TooltipRoot(props) {
+    return (_jsx(EnsureProvider, { children: _jsx(TooltipPrimitive.Root, { ...props }) }));
+}
+export const TooltipTrigger = TooltipPrimitive.Trigger;
+export const tooltipContentVariants = cva([
+    "ui-pop z-(--z-tooltip) max-w-[min(18rem,calc(100vw-1.5rem))] select-none rounded-ui-sm px-2 py-1 text-[12.5px] leading-snug font-medium",
+    // tooltips never blur — they open and close too often to spend the glass budget on
+    "[--blur:0px] backdrop-filter-none",
+    // Close instantly: while a tooltip animates out it stays the top dismissable layer, so an Esc
+    // pressed just after tabbing past an IconButton closed the tooltip instead of the dialog.
+    "data-[state=closed]:animate-none",
+    "flex items-center gap-2 text-balance",
+], {
+    variants: {
+        tone: {
+            /** Opaque, high-contrast chip. Stays readable on glass. */
+            inverted: "bg-fg text-scene shadow-[0_4px_14px_-4px_rgb(0_0_0/0.35)]",
+            /** Floating-layer look, for longer hints. */
+            default: "border border-popover-border bg-popover-nested text-fg shadow-(--popover-shadow)",
+        },
+    },
+    defaultVariants: { tone: "inverted" },
+});
+export const TooltipContent = React.forwardRef(function TooltipContent({ className, tone, arrow = false, shortcut, sideOffset = 6, collisionPadding = 8, children, ...props }, ref) {
+    const container = usePortalContainer();
+    const inverted = (tone ?? "inverted") === "inverted";
+    return (_jsx(TooltipPrimitive.Portal, { container: container, children: _jsxs(TooltipPrimitive.Content, { ref: ref, "data-slot": "tooltip-content", "data-tone": tone ?? "inverted", sideOffset: sideOffset, collisionPadding: collisionPadding, className: cn(tooltipContentVariants({ tone }), className), ...props, children: [_jsx("span", { className: "min-w-0", children: children }), shortcut ? (_jsx(KbdGroup, { keys: shortcut, size: "sm", variant: "ghost", className: cn("-me-0.5", inverted && "[&_kbd_kbd]:border-[color-mix(in_srgb,var(--scene)_28%,transparent)] [&_kbd_kbd]:text-[color-mix(in_srgb,var(--scene)_78%,transparent)]") })) : null, arrow ? (_jsx(TooltipPrimitive.Arrow, { asChild: true, width: 10, height: 5, children: _jsx(FloatingArrow, { width: 10, height: 5, fill: inverted ? "var(--fg)" : "var(--popover-nested)", stroke: inverted ? "none" : "var(--popover-border)" }) })) : null] }) }));
+});
+function isDisabledElement(el) {
+    // A child rendered by a server component reaches this client component as a lazy reference
+    // without `props` in production (RSC), so this can only be a hint; see the DOM check below.
+    const p = el?.props;
+    return p?.disabled === true;
+}
+/**
+ * A short label for an icon button or abbreviation. Opens on hover and focus, closes on Esc.
+ * Never shown on touch screens, so it can't be the only place a piece of information lives.
+ *
+ * ```tsx
+ * <Tooltip content="Edit post" shortcut="mod+e">
+ *   <IconButton label="Edit post"><Pencil /></IconButton>
+ * </Tooltip>
+ * ```
+ *
+ * A disabled button fires no pointer events, so a disabled child is wrapped in a focusable
+ * `<span>` automatically — use it to explain *why* the action is unavailable.
+ */
+export function Tooltip({ content, children, delay, disabled, open, defaultOpen, onOpenChange, ...contentProps }) {
+    // When the child's props are not readable (server-rendered child), detect a disabled trigger
+    // from the DOM after mount and switch to the focusable wrapper.
+    const triggerRef = React.useRef(null);
+    const [domDisabled, setDomDisabled] = React.useState(false);
+    const off = disabled || content == null || content === false || content === "";
+    React.useEffect(() => {
+        const el = triggerRef.current;
+        if (!off && el && el.dataset.slot !== "tooltip-disabled-trigger" && el.matches(":disabled"))
+            setDomDisabled(true);
+    }, [off]);
+    if (off)
+        return children;
+    const trigger = isDisabledElement(children) || domDisabled ? (
+    // tabIndex keeps the explanation reachable from the keyboard
+    _jsx("span", { "data-slot": "tooltip-disabled-trigger", tabIndex: 0, className: "inline-flex cursor-not-allowed rounded-ui focus-ring", children: children })) : (children);
+    return (_jsxs(TooltipRoot, { delayDuration: delay, open: open, defaultOpen: defaultOpen, onOpenChange: onOpenChange, children: [_jsx(TooltipPrimitive.Trigger, { ref: triggerRef, asChild: true, children: trigger }), _jsx(TooltipContent, { ...contentProps, children: content })] }));
+}
+/**
+ * Used by `IconButton`: shows `label` as a Tooltip when a `TooltipProvider` is present,
+ * and falls back to the native `title` attribute when it isn't (so code without a provider keeps working).
+ */
+export function IconButtonTooltip({ label, mode = "auto", side, shortcut, children }) {
+    const hasProvider = useHasTooltipProvider();
+    if (mode === "auto" && !hasProvider)
+        return _jsx(Slot.Root, { title: label, children: children });
+    return (_jsx(Tooltip, { content: label, side: side, shortcut: shortcut, children: children }));
+}

package/dist/components/top-bar.d.ts

@@ -0,0 +1,87 @@
+import * as React from "react";
+import type { MenuEntry } from "../lib/variants.js";
+declare const topBarLabels: {
+    search: string;
+    searchShort: string;
+    menu: string;
+    account: string;
+};
+export type TopBarLabels = typeof topBarLabels;
+/**
+ * Bridge between the top bar and the App shell (mobile nav button). App shell provides it; outside
+ * a shell the menu button needs its own `onClick`.
+ */
+export declare const TopBarShellContext: React.Context<{
+    openMobileNav: () => void;
+    mobileNavOpen: boolean;
+} | null>;
+export interface TopBarProps extends React.HTMLAttributes<HTMLElement> {
+    /** Sticks to the top of the scrolling area. Default `true`. */
+    sticky?: boolean;
+    /** `bar`: translucent bar with a hairline. `transparent`: blends in until the page scrolls (`data-scrolled`). */
+    variant?: "bar" | "transparent";
+    /** Element whose scroll sets `data-scrolled`. Default `window`. */
+    scrollTarget?: React.RefObject<HTMLElement | null>;
+}
+/**
+ * The sticky bar above the content: mobile menu button, ⌘K search, contextual actions,
+ * notifications and the user menu. The same in every app.
+ *
+ * ```tsx
+ * <TopBar>
+ *   <TopBarStart><TopBarMenuButton /></TopBarStart>
+ *   <TopBarSearch />
+ *   <TopBarSpacer />
+ *   <TopBarActions><NotificationCenter adapter={inbox} /><UserMenu name="Ada Lovelace" items={account} /></TopBarActions>
+ * </TopBar>
+ * ```
+ */
+export declare const TopBar: React.ForwardRefExoticComponent<TopBarProps & React.RefAttributes<HTMLElement>>;
+/** Leading slot: menu button, breadcrumb. */
+export declare function TopBarStart({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
+/** Pushes the following slots to the end. */
+export declare function TopBarSpacer({ className }: {
+    className?: string;
+}): React.JSX.Element;
+/** Trailing slot: theme switch, notifications, "New", user menu. */
+export declare function TopBarActions({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
+/** A short vertical rule between action groups. */
+export declare function TopBarSeparator({ className }: {
+    className?: string;
+}): React.JSX.Element;
+export interface TopBarMenuButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> {
+    labels?: Partial<TopBarLabels>;
+}
+/** Opens the App shell's mobile navigation. Visible only below 768px. */
+export declare const TopBarMenuButton: React.ForwardRefExoticComponent<TopBarMenuButtonProps & React.RefAttributes<HTMLButtonElement>>;
+export interface TopBarSearchProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> {
+    /** Default "Search or run a command…" (`topBar.search`). */
+    placeholder?: string;
+    /** Shortcut hint. Default `"mod+k"`; `false` hides it. */
+    shortcut?: string | false;
+    /** Default: opens the command palette of the nearest `CommandProvider`. */
+    onOpen?: () => void;
+    labels?: Partial<TopBarLabels>;
+}
+/**
+ * The ⌘K trigger: a real button that looks like a field. Collapses to an icon button when the bar is
+ * narrower than 560px.
+ */
+export declare const TopBarSearch: React.ForwardRefExoticComponent<TopBarSearchProps & React.RefAttributes<HTMLButtonElement>>;
+export interface UserMenuProps {
+    name: string;
+    email?: string;
+    avatar?: string | null;
+    /** Account entries: profile, settings, theme, sign out. Same model as Dropdown Menu. */
+    items: MenuEntry[];
+    /** Show the name next to the avatar (wide bars). Default `false`. */
+    showName?: boolean;
+    /** Extra content under the header (a plan badge, a workspace line). */
+    children?: React.ReactNode;
+    align?: "start" | "center" | "end";
+    className?: string;
+    labels?: Partial<TopBarLabels>;
+}
+/** The avatar button with the account menu. */
+export declare function UserMenu({ name, email, avatar, items, showName, children, align, className, labels }: UserMenuProps): React.JSX.Element;
+export {};