@vamos-ui/react 0.0.0-stage → 0.2.0

package/dist/components/alert-dialog.d.ts

@@ -0,0 +1,99 @@
+import * as React from "react";
+import { AlertDialog as AlertDialogPrimitive } from "radix-ui";
+import { type ButtonProps } from "./button.js";
+import { type LayerHeaderProps } from "./dialog.js";
+type Tone = "default" | "danger";
+/**
+ * Confirms an irreversible or high-stakes action. `role="alertdialog"`; the overlay never closes it.
+ *
+ * ```tsx
+ * <AlertDialog>
+ *   <AlertDialogTrigger asChild><Button variant="danger-ghost">Delete post</Button></AlertDialogTrigger>
+ *   <AlertDialogContent tone="danger">
+ *     <AlertDialogHeader title="Delete this post permanently?" description="It can't be restored from the trash." />
+ *     <AlertDialogFooter>
+ *       <AlertDialogCancel />
+ *       <AlertDialogAction onClick={remove}>Delete post</AlertDialogAction>
+ *     </AlertDialogFooter>
+ *   </AlertDialogContent>
+ * </AlertDialog>
+ * ```
+ *
+ * For a one-line `await confirm({...})` use `useConfirm()` under a `ConfirmProvider`.
+ */
+export declare const AlertDialog: React.FC<AlertDialogPrimitive.AlertDialogProps>;
+export declare const AlertDialogTrigger: React.ForwardRefExoticComponent<AlertDialogPrimitive.AlertDialogTriggerProps & React.RefAttributes<HTMLButtonElement>>;
+export interface AlertDialogContentProps extends React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Content> {
+    /** `"danger"` → warning icon, danger action, initial focus on Cancel. `"default"` focuses the action. */
+    tone?: Tone;
+    /** Lock Esc (e.g. while the action runs). */
+    dismissible?: boolean;
+    /** Portal target. Defaults to the nearest `PortalContainer` / `ThemeScope`. */
+    container?: HTMLElement | null;
+}
+/** Fixed 420px panel. Below 640px it anchors to the bottom and stacks the buttons, action on top. */
+export declare const AlertDialogContent: React.ForwardRefExoticComponent<AlertDialogContentProps & React.RefAttributes<HTMLDivElement>>;
+/** Icon well in the danger tone. */
+export declare function AlertDialogIcon({ className, children }: {
+    className?: string;
+    children?: React.ReactNode;
+}): React.JSX.Element;
+export interface AlertDialogHeaderProps extends LayerHeaderProps {
+}
+/** `LayerHeader` that adds the warning icon well when the content is `tone="danger"` (pass `icon={null}` to drop it). */
+export declare const AlertDialogHeader: React.ForwardRefExoticComponent<AlertDialogHeaderProps & React.RefAttributes<HTMLDivElement>>;
+export declare const AlertDialogBody: React.ForwardRefExoticComponent<import("./dialog.js").LayerBodyProps & React.RefAttributes<HTMLDivElement>>;
+/** Footer without the hairline; buttons at the end, stacked on mobile. */
+export declare const AlertDialogFooter: React.ForwardRefExoticComponent<Omit<import("./dialog.js").LayerFooterProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare const confirmLabels: {
+    cancel: string;
+    confirm: string;
+    typeToConfirm: string;
+    error: string;
+};
+export interface AlertDialogCancelProps extends ButtonProps {
+    labels?: Partial<typeof confirmLabels>;
+}
+/** Closes without acting. Receives initial focus in a danger dialog. Default label "Cancel". */
+export declare const AlertDialogCancel: React.ForwardRefExoticComponent<AlertDialogCancelProps & React.RefAttributes<HTMLButtonElement>>;
+export interface AlertDialogActionProps extends ButtonProps {
+    /** Keep the dialog open after click (you close it when async work finishes). */
+    keepOpen?: boolean;
+    labels?: Partial<typeof confirmLabels>;
+}
+/** Runs the action and closes. `variant` follows the content tone (`danger` or `primary`). */
+export declare const AlertDialogAction: React.ForwardRefExoticComponent<AlertDialogActionProps & React.RefAttributes<HTMLButtonElement>>;
+export interface ConfirmOptions {
+    title: React.ReactNode;
+    description?: React.ReactNode;
+    tone?: Tone;
+    confirmLabel?: string;
+    cancelLabel?: string;
+    /** Text the user must type before confirming (e.g. the record name). Compared case-insensitively for the current locale. */
+    requireText?: string;
+    /** Async work: the button shows loading; if it throws, the dialog stays open and shows the error. */
+    onConfirm?: () => Promise<void> | void;
+}
+export interface ConfirmDialogProps extends ConfirmOptions {
+    open: boolean;
+    /** Called once with the outcome; the dialog closes itself. */
+    onResult: (confirmed: boolean) => void;
+    labels?: Partial<typeof confirmLabels>;
+}
+/** A ready-made confirmation (controlled). `useConfirm()` renders one of these for you. */
+export declare function ConfirmDialog({ open, onResult, title, description, tone, confirmLabel, cancelLabel, requireText, onConfirm, labels }: ConfirmDialogProps): React.JSX.Element;
+type ConfirmFn = (options: ConfirmOptions) => Promise<boolean>;
+/**
+ * Provides `useConfirm()` to its subtree and renders the one shared confirmation dialog.
+ * App shell includes it; mount it yourself at the app root otherwise.
+ */
+export declare function ConfirmProvider({ children, labels }: {
+    children: React.ReactNode;
+    labels?: Partial<typeof confirmLabels>;
+}): React.JSX.Element;
+/**
+ * Imperative confirmation: `if (await confirm({ title: "Delete 3 posts?", tone: "danger" })) …`.
+ * Resolves `true` on confirm, `false` on cancel / Esc. Needs a `ConfirmProvider` above.
+ */
+export declare function useConfirm(): ConfirmFn;
+export {};

package/dist/components/alert-dialog.js

@@ -0,0 +1,192 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as React from "react";
+import { AlertDialog as AlertDialogPrimitive } from "radix-ui";
+import { TriangleAlert } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { useLabels } from "../lib/labels.js";
+import { useLocale } from "../lib/locale.js";
+import { Layer, useLayerDepth } from "../lib/layer.js";
+import { usePortalContainer } from "../lib/theme-scope.js";
+import { Button } from "./button.js";
+import { Field, Input } from "./input.js";
+import { Alert } from "./alert.js";
+import { LayerBody, LayerFooter, LayerHeader, LayerPartsProvider } from "./dialog.js";
+const AlertDialogContentContext = React.createContext({ tone: "default", actionRef: { current: null } });
+/**
+ * Confirms an irreversible or high-stakes action. `role="alertdialog"`; the overlay never closes it.
+ *
+ * ```tsx
+ * <AlertDialog>
+ *   <AlertDialogTrigger asChild><Button variant="danger-ghost">Delete post</Button></AlertDialogTrigger>
+ *   <AlertDialogContent tone="danger">
+ *     <AlertDialogHeader title="Delete this post permanently?" description="It can't be restored from the trash." />
+ *     <AlertDialogFooter>
+ *       <AlertDialogCancel />
+ *       <AlertDialogAction onClick={remove}>Delete post</AlertDialogAction>
+ *     </AlertDialogFooter>
+ *   </AlertDialogContent>
+ * </AlertDialog>
+ * ```
+ *
+ * For a one-line `await confirm({...})` use `useConfirm()` under a `ConfirmProvider`.
+ */
+export const AlertDialog = AlertDialogPrimitive.Root;
+export const AlertDialogTrigger = AlertDialogPrimitive.Trigger;
+/** Fixed 420px panel. Below 640px it anchors to the bottom and stacks the buttons, action on top. */
+export const AlertDialogContent = React.forwardRef(function AlertDialogContent({ tone = "default", dismissible = true, container, className, children, onEscapeKeyDown, onOpenAutoFocus, onCloseAutoFocus, ...props }, ref) {
+    const scope = usePortalContainer();
+    const depth = useLayerDepth() + 1;
+    const actionRef = React.useRef(null);
+    const returnTo = React.useRef(null);
+    const [descriptions, setDescriptions] = React.useState(0);
+    const parts = React.useMemo(() => ({
+        Title: AlertDialogPrimitive.Title,
+        Description: AlertDialogPrimitive.Description,
+        registerDescription: () => {
+            setDescriptions((n) => n + 1);
+            return () => setDescriptions((n) => n - 1);
+        },
+    }), []);
+    const ctx = React.useMemo(() => ({ tone, actionRef }), [tone]);
+    const described = descriptions > 0 || "aria-describedby" in props;
+    return (_jsxs(AlertDialogPrimitive.Portal, { container: container ?? scope, children: [_jsx(AlertDialogPrimitive.Overlay, { "data-slot": "alert-dialog-overlay", "data-overlay-blurred": depth === 1 ? "" : undefined, className: "vui-overlay ui-fade" }), _jsx(Layer, { asChild: true, children: _jsx(AlertDialogPrimitive.Content, { ref: ref, "data-slot": "alert-dialog-content", "data-mobile": "sheet", "data-tone": tone, ...(described ? {} : { "aria-describedby": undefined }), className: cn("vui-layer-panel vui-dialog ui-dialog surface-popover [--dialog-w:26.25rem]", className), onEscapeKeyDown: (e) => {
+                        onEscapeKeyDown?.(e);
+                        if (!dismissible)
+                            e.preventDefault();
+                    }, onOpenAutoFocus: (e) => {
+                        // Fires before focus moves in: remember the opener. Radix returns focus only to an
+                        // AlertDialog.Trigger, so a controlled confirm (useConfirm, ConfirmDialog) lost focus.
+                        returnTo.current = document.activeElement;
+                        onOpenAutoFocus?.(e);
+                        if (e.defaultPrevented)
+                            return;
+                        // Radix focuses Cancel. For a non-destructive confirm the action is the safe default.
+                        if (tone === "default" && actionRef.current) {
+                            e.preventDefault();
+                            actionRef.current.focus();
+                        }
+                    }, onCloseAutoFocus: (e) => {
+                        onCloseAutoFocus?.(e);
+                        if (e.defaultPrevented)
+                            return;
+                        const el = returnTo.current;
+                        if (el && el.isConnected && el !== document.body) {
+                            e.preventDefault();
+                            el.focus();
+                        }
+                    }, ...props, children: _jsx(AlertDialogContentContext.Provider, { value: ctx, children: _jsx(LayerPartsProvider, { value: parts, children: children }) }) }) })] }));
+});
+/** Icon well in the danger tone. */
+export function AlertDialogIcon({ className, children }) {
+    return (_jsx("span", { "aria-hidden": true, className: cn("flex size-10 items-center justify-center rounded-ui tone-danger bg-[color-mix(in_srgb,var(--danger)_12%,transparent)] text-danger [&_svg]:size-5", className), children: children ?? _jsx(TriangleAlert, {}) }));
+}
+/** `LayerHeader` that adds the warning icon well when the content is `tone="danger"` (pass `icon={null}` to drop it). */
+export const AlertDialogHeader = React.forwardRef(function AlertDialogHeader({ icon, className, ...props }, ref) {
+    const { tone } = React.useContext(AlertDialogContentContext);
+    const resolvedIcon = icon === undefined ? (tone === "danger" ? _jsx(AlertDialogIcon, {}) : undefined) : icon;
+    return _jsx(LayerHeader, { ref: ref, icon: resolvedIcon, className: cn("pt-6", className), ...props });
+});
+export const AlertDialogBody = LayerBody;
+/** Footer without the hairline; buttons at the end, stacked on mobile. */
+export const AlertDialogFooter = React.forwardRef(function AlertDialogFooter({ className, ...props }, ref) {
+    return _jsx(LayerFooter, { ref: ref, className: cn("border-t-0 pt-1 pb-5", className), ...props });
+});
+const confirmLabels = { cancel: "Cancel", confirm: "Confirm", typeToConfirm: "Type {text} to confirm", error: "That didn't work. Try again." };
+/** Closes without acting. Receives initial focus in a danger dialog. Default label "Cancel". */
+export const AlertDialogCancel = React.forwardRef(function AlertDialogCancel({ children, labels, variant = "secondary", ...props }, ref) {
+    const t = useLabels("confirm", confirmLabels, labels);
+    return (_jsx(AlertDialogPrimitive.Cancel, { asChild: true, children: _jsx(Button, { ref: ref, variant: variant, ...props, children: children ?? t("cancel") }) }));
+});
+/** Runs the action and closes. `variant` follows the content tone (`danger` or `primary`). */
+export const AlertDialogAction = React.forwardRef(function AlertDialogAction({ children, labels, variant, keepOpen, onClick, ...props }, ref) {
+    const { tone, actionRef } = React.useContext(AlertDialogContentContext);
+    const t = useLabels("confirm", confirmLabels, labels);
+    const setRefs = React.useCallback((node) => {
+        actionRef.current = node;
+        if (typeof ref === "function")
+            ref(node);
+        else if (ref)
+            ref.current = node;
+    }, [ref, actionRef]);
+    const button = (_jsx(Button, { ref: setRefs, variant: variant ?? (tone === "danger" ? "danger" : "primary"), onClick: onClick, "data-slot": "alert-dialog-action", ...props, children: children ?? t("confirm") }));
+    return keepOpen ? button : _jsx(AlertDialogPrimitive.Action, { asChild: true, children: button });
+});
+const SPLIT = "\u2063";
+/** A ready-made confirmation (controlled). `useConfirm()` renders one of these for you. */
+export function ConfirmDialog({ open, onResult, title, description, tone = "default", confirmLabel, cancelLabel, requireText, onConfirm, labels }) {
+    const t = useLabels("confirm", confirmLabels, labels);
+    const { locale } = useLocale();
+    const [typed, setTyped] = React.useState("");
+    const [busy, setBusy] = React.useState(false);
+    const [error, setError] = React.useState(null);
+    const inputId = React.useId();
+    React.useEffect(() => {
+        if (open) {
+            setTyped("");
+            setError(null);
+            setBusy(false);
+        }
+    }, [open]);
+    // Split the translated prompt around {text} so the required text can be styled as code.
+    const promptParts = t("typeToConfirm", { text: SPLIT }).split(SPLIT);
+    const matches = !requireText || typed.trim().toLocaleLowerCase(locale) === requireText.trim().toLocaleLowerCase(locale);
+    const run = async () => {
+        if (!matches || busy)
+            return;
+        if (!onConfirm)
+            return onResult(true);
+        setBusy(true);
+        setError(null);
+        try {
+            await onConfirm();
+            setBusy(false);
+            onResult(true);
+        }
+        catch (e) {
+            setBusy(false);
+            setError(e instanceof Error && e.message ? e.message : t("error"));
+        }
+    };
+    return (_jsx(AlertDialog, { open: open, onOpenChange: (next) => !next && !busy && onResult(false), children: _jsxs(AlertDialogContent, { tone: tone, dismissible: !busy, children: [_jsx(AlertDialogHeader, { title: title, description: description }), requireText || error ? (_jsxs(AlertDialogBody, { className: "grid gap-3 pb-3", children: [error ? (_jsx(Alert, { tone: "danger", size: "sm", live: "assertive", children: error })) : null, requireText ? (_jsx(Field, { id: inputId, label: _jsxs(_Fragment, { children: [promptParts[0], _jsx("code", { className: "rounded-ui-sm bg-selected px-1.5 py-0.5 font-mono text-[12.5px] text-fg", children: requireText }), promptParts[1]] }), children: _jsx(Input, { value: typed, onChange: (e) => setTyped(e.target.value), autoComplete: "off", autoCapitalize: "off", spellCheck: false, disabled: busy, onKeyDown: (e) => {
+                                    if (e.key === "Enter") {
+                                        e.preventDefault();
+                                        void run();
+                                    }
+                                } }) })) : null] })) : null, _jsxs(AlertDialogFooter, { children: [_jsx(AlertDialogCancel, { disabled: busy, children: cancelLabel ?? t("cancel") }), _jsx(AlertDialogAction, { keepOpen: true, disabled: !matches, loading: busy, onClick: () => void run(), children: confirmLabel ?? t("confirm") })] })] }) }));
+}
+const ConfirmContext = React.createContext(null);
+/**
+ * Provides `useConfirm()` to its subtree and renders the one shared confirmation dialog.
+ * App shell includes it; mount it yourself at the app root otherwise.
+ */
+export function ConfirmProvider({ children, labels }) {
+    const [state, setState] = React.useState(null);
+    const [open, setOpen] = React.useState(false);
+    const stateRef = React.useRef(state);
+    stateRef.current = state;
+    const confirm = React.useCallback((options) => {
+        // A second confirm while one is open resolves the first as cancelled.
+        stateRef.current?.resolve(false);
+        return new Promise((resolve) => {
+            setState({ options, resolve });
+            setOpen(true);
+        });
+    }, []);
+    const onResult = React.useCallback((ok) => {
+        stateRef.current?.resolve(ok);
+        stateRef.current = null;
+        setOpen(false);
+    }, []);
+    return (_jsxs(ConfirmContext.Provider, { value: confirm, children: [children, state ? _jsx(ConfirmDialog, { ...state.options, open: open, onResult: onResult, labels: labels }) : null] }));
+}
+/**
+ * Imperative confirmation: `if (await confirm({ title: "Delete 3 posts?", tone: "danger" })) …`.
+ * Resolves `true` on confirm, `false` on cancel / Esc. Needs a `ConfirmProvider` above.
+ */
+export function useConfirm() {
+    const ctx = React.useContext(ConfirmContext);
+    if (!ctx)
+        throw new Error("useConfirm() needs a <ConfirmProvider> above it (AppShell includes one).");
+    return ctx;
+}

package/dist/components/alert.d.ts

@@ -0,0 +1,42 @@
+import * as React from "react";
+import { type VariantProps } from "class-variance-authority";
+export type AlertTone = "neutral" | "info" | "success" | "warning" | "danger" | "accent";
+export declare const alertVariants: (props?: ({
+    tone?: "accent" | "info" | "warning" | "danger" | "neutral" | "success" | null | undefined;
+    variant?: "outline" | "banner" | "soft" | null | undefined;
+    size?: "sm" | "md" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export interface AlertProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title">, VariantProps<typeof alertVariants> {
+    title?: React.ReactNode;
+    /** Custom icon, or `false` for none. Each tone has a default. */
+    icon?: React.ReactNode | false;
+    /** Buttons or links ("Restore revision", "Renew plan"). Below the text; inline at the end for banners. */
+    actions?: React.ReactNode;
+    /** Renders a close button. */
+    onDismiss?: () => void;
+    /** Accessible name of the close button. Default "Dismiss" (dictionary `alert.dismiss`). */
+    dismissLabel?: string;
+    /**
+     * For alerts inserted at runtime: `"assertive"` → `role="alert"` (errors), `"polite"` →
+     * `role="status"`. Leave unset for static messages (no role).
+     */
+    live?: "polite" | "assertive";
+}
+/**
+ * A persistent inline status message in a page, card or form. Server-compatible.
+ *
+ * ```tsx
+ * <Alert tone="warning" title="Payroll filing due in 3 days" actions={<Button size="sm">Review</Button>}>
+ *   Submit the November declaration before Dec 26 to avoid a late fee.
+ * </Alert>
+ * ```
+ *
+ * Critical information must not live only in a toast — show it here too.
+ */
+export declare const Alert: React.ForwardRefExoticComponent<AlertProps & React.RefAttributes<HTMLDivElement>>;
+/** Title line, in the tone colour (mixed toward --fg so it keeps 4.5:1 on tinted / glass scenes). */
+export declare function AlertTitle({ className, ...props }: React.HTMLAttributes<HTMLParagraphElement>): React.JSX.Element;
+/** Body text — stays in `--fg` for contrast. */
+export declare function AlertDescription({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
+/** Action row under the text. */
+export declare function AlertActions({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;

package/dist/components/alert.js

@@ -0,0 +1,82 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cva } from "class-variance-authority";
+import { CircleAlert, CircleCheck, Info, Lightbulb, TriangleAlert, X } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { useLabels } from "../lib/labels.js";
+import { IconButton } from "./button.js";
+export const alertVariants = cva([
+    "vui-alert relative grid grid-cols-[auto_minmax(0,1fr)_auto] items-start text-fg",
+    // Tinted surface + hairline in the tone colour; body text stays --fg for contrast.
+    "[--alert-tone:var(--tone)]",
+], {
+    variants: {
+        tone: {
+            neutral: "tone-neutral",
+            info: "tone-info",
+            success: "tone-success",
+            warning: "tone-warning",
+            danger: "tone-danger",
+            accent: "tone-accent",
+        },
+        variant: {
+            soft: "rounded-ui border border-[color-mix(in_srgb,var(--alert-tone)_22%,transparent)] bg-[color-mix(in_srgb,var(--alert-tone)_9%,transparent)]",
+            outline: "rounded-ui border border-[color-mix(in_srgb,var(--alert-tone)_38%,transparent)] bg-transparent",
+            /** Full width, no radius — under the top bar or above a page. */
+            banner: "w-full rounded-none border-b border-[color-mix(in_srgb,var(--alert-tone)_24%,transparent)] bg-[color-mix(in_srgb,var(--alert-tone)_11%,transparent)]",
+        },
+        size: {
+            sm: "gap-x-2.5 px-3 py-2.5 text-[13px] [&_[data-slot=alert-icon]_svg]:size-4",
+            md: "gap-x-3 px-4 py-3.5 text-sm [&_[data-slot=alert-icon]_svg]:size-[18px]",
+        },
+    },
+    compoundVariants: [
+        { variant: "banner", size: "md", class: "px-5 py-2.5" },
+        { variant: "banner", size: "sm", class: "px-4 py-2" },
+    ],
+    defaultVariants: { tone: "neutral", variant: "soft", size: "md" },
+});
+const defaultIcons = {
+    neutral: Info,
+    info: Info,
+    success: CircleCheck,
+    warning: TriangleAlert,
+    danger: CircleAlert,
+    accent: Lightbulb,
+};
+const alertLabels = { dismiss: "Dismiss" };
+/**
+ * A persistent inline status message in a page, card or form. Server-compatible.
+ *
+ * ```tsx
+ * <Alert tone="warning" title="Payroll filing due in 3 days" actions={<Button size="sm">Review</Button>}>
+ *   Submit the November declaration before Dec 26 to avoid a late fee.
+ * </Alert>
+ * ```
+ *
+ * Critical information must not live only in a toast — show it here too.
+ */
+export const Alert = React.forwardRef(function Alert({ tone, variant, size, title, icon, actions, onDismiss, dismissLabel, live, className, children, ...props }, ref) {
+    const t = tone ?? "neutral";
+    const DefaultIcon = defaultIcons[t];
+    const iconNode = icon === false ? null : (icon ?? _jsx(DefaultIcon, { "aria-hidden": true }));
+    const banner = variant === "banner";
+    return (_jsxs("div", { ref: ref, "data-slot": "alert", "data-tone": t, "data-variant": variant ?? "soft", role: live === "assertive" ? "alert" : live === "polite" ? "status" : undefined, className: cn(alertVariants({ tone, variant, size }), !iconNode && "grid-cols-[minmax(0,1fr)_auto]", className), ...props, children: [iconNode ? (_jsx("span", { "data-slot": "alert-icon", className: "flex h-[1.4em] items-center text-(--alert-tone) [&_svg]:shrink-0", children: iconNode })) : null, _jsxs("div", { className: cn("min-w-0", banner && actions && "flex flex-wrap items-center gap-x-4 gap-y-2"), children: [_jsxs("div", { className: cn("min-w-0", banner && "flex-1"), children: [title ? _jsx(AlertTitle, { children: title }) : null, children ? _jsx(AlertDescription, { className: title ? "mt-0.5" : undefined, children: children }) : null] }), actions ? _jsx(AlertActions, { className: banner ? "mt-0" : undefined, children: actions }) : null] }), onDismiss ? _jsx(AlertDismiss, { onDismiss: onDismiss, label: dismissLabel }) : _jsx("span", { "aria-hidden": true })] }));
+});
+// Only rendered when `onDismiss` exists, i.e. inside a client tree.
+function AlertDismiss({ onDismiss, label }) {
+    const t = useLabels("alert", alertLabels);
+    return (_jsx(IconButton, { label: label ?? t("dismiss"), size: "xs", variant: "ghost", onClick: onDismiss, className: "-me-1.5 -mt-0.5 text-fg-muted hover:text-fg", children: _jsx(X, {}) }));
+}
+/** Title line, in the tone colour (mixed toward --fg so it keeps 4.5:1 on tinted / glass scenes). */
+export function AlertTitle({ className, ...props }) {
+    return _jsx("p", { "data-slot": "alert-title", className: cn("leading-[1.4] font-semibold text-[color-mix(in_srgb,var(--alert-tone)_62%,var(--fg))] [[data-tone=neutral]_&]:text-fg", className), ...props });
+}
+/** Body text — stays in `--fg` for contrast. */
+export function AlertDescription({ className, ...props }) {
+    return _jsx("div", { "data-slot": "alert-description", className: cn("leading-[1.4] text-pretty text-fg [&_a]:font-medium [&_a]:underline [&_a]:underline-offset-2", className), ...props });
+}
+/** Action row under the text. */
+export function AlertActions({ className, ...props }) {
+    return _jsx("div", { "data-slot": "alert-actions", className: cn("mt-3 flex flex-wrap items-center gap-2", className), ...props });
+}

package/dist/components/app-shell.d.ts

@@ -0,0 +1,159 @@
+import * as React from "react";
+import { type VamosLinkComponent, type VamosProviderProps } from "../lib/provider.js";
+import type { MenuEntry } from "../lib/variants.js";
+import { type BadgeSpec, type NavIcon, type NavNode } from "../lib/nav.js";
+import { type CommandAction, type CommandSource } from "./command.js";
+import { type UserMenuProps } from "./top-bar.js";
+declare const appShellLabels: {
+    skip: string;
+    navigation: string;
+    appMenu: string;
+    workspace: string;
+    goTo: string;
+    apps: string;
+    switchTo: string;
+    newItem: string;
+    noApps: string;
+    noAppsDescription: string;
+    pageChanged: string;
+};
+export type AppShellLabels = typeof appShellLabels;
+export interface AppLink {
+    id: string;
+    label: string;
+    href: string;
+    icon?: NavIcon;
+    external?: boolean;
+}
+/** One app (CMS, CRM, HR, PRM…) on the shared shell. Define these in a client module (they hold components). */
+export interface AppDefinition {
+    /** `"site"` | `"crm"` | `"people"`… */
+    id: string;
+    name: string;
+    description?: string;
+    icon?: React.ComponentType<{
+        className?: string;
+        strokeWidth?: number;
+    }> | React.ReactNode;
+    /** App home. An absolute URL (separately deployed app) triggers a full navigation. */
+    href: string;
+    /** Path prefix that belongs to the app. Default: `href`. */
+    base?: string;
+    /** `data-accent` override for the whole shell while this app is active (e.g. CRM = `"ocean"`). */
+    accent?: string;
+    nav: NavNode[];
+    /** Commands for ⌘K while this app is active. */
+    commands?: CommandAction[];
+    /** Record search sources (stay registered when another app is active). */
+    sources?: CommandSource[];
+    /** Contents of the top bar's "New ▾" button. */
+    newMenu?: MenuEntry[];
+    /** Top-bar links that only make sense in this app ("View site" in the Site app). */
+    links?: AppLink[];
+    /** Hide the app entirely unless `can(permission)`. */
+    permission?: string;
+}
+export interface AppShellProviderProps extends Partial<Omit<VamosProviderProps, "children" | "Link">> {
+    apps: AppDefinition[];
+    /** Default: the app whose `base` / `href` is the longest prefix of `currentPath`, else the last one used. */
+    activeApp?: string;
+    /** A menu shared by every app (users, settings), shown at the bottom of the sidebar. */
+    sharedNav?: NavNode[];
+    /** Commands available in every app. */
+    commands?: CommandAction[];
+    /** Feature flags / module toggles for nav items with `feature`. */
+    features?: Record<string, boolean | undefined>;
+    /** Rail preference — read the `ui-sidebar` cookie on the server (`parseSidebarCookie`) to avoid a flash. `undefined` = no preference. */
+    defaultCollapsed?: boolean;
+    /** Default: writes the `ui-sidebar` cookie. */
+    onCollapsedChange?: (collapsed: boolean) => void;
+    workspaces?: {
+        id: string;
+        name: string;
+        logo?: string;
+    }[];
+    activeWorkspace?: string;
+    onWorkspaceChange?: (id: string) => void;
+    /** Global shortcuts: `mod+k` (palette) and `mod+\\` (rail). Default `true`; turn off for shells embedded in a page. */
+    shortcuts?: boolean;
+    /** Router link (Next `Link`). Also accepted as `Link`. Omit when a `VamosProvider` above already sets it. */
+    linkComponent?: VamosLinkComponent;
+    Link?: VamosLinkComponent;
+    children: React.ReactNode;
+}
+/**
+ * The app bridge for the shell: apps, shared nav, permissions, collapse preference, the ⌘K
+ * registry (with "Go to" commands derived from every accessible app's nav) and app switching.
+ * Router pieces come from the surrounding `VamosProvider`, or pass them here.
+ */
+export declare function AppShellProvider(props: AppShellProviderProps): React.JSX.Element;
+/**
+ * The shell state: active app, nav, rail, mobile nav, app switching. Throws outside `AppShellProvider`.
+ */
+export declare function useAppShell(): {
+    activeApp: AppDefinition | undefined;
+    apps: AppDefinition[];
+    nav: NavNode[];
+    sharedNav: NavNode[];
+    collapsed: boolean;
+    setCollapsed: (v: boolean) => void;
+    openMobileNav: () => void;
+    closeMobileNav: () => void;
+    mobileNavOpen: boolean;
+    trail: string[];
+    can: (permission: string) => boolean;
+    switchApp: (id: string) => void;
+};
+/** `true` inside an `AppShellProvider`. */
+export declare function useInAppShell(): boolean;
+/** Breadcrumb built from the shell's active trail (used by `PageHeader breadcrumb="auto"`). */
+export declare function AppShellBreadcrumb({ includeApp, className }: {
+    includeApp?: boolean;
+    className?: string;
+}): React.JSX.Element | null;
+export interface AppShellProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "dir"> {
+    /** Replace the default sidebar (AppSwitcher + SidebarNav + shared nav + collapse). `false` = none. */
+    sidebar?: React.ReactNode | false;
+    /** Replace the default top bar. `false` = none. */
+    topbar?: React.ReactNode | false;
+    /** Slot above the top bar (offline, trial, maintenance banner). */
+    banner?: React.ReactNode;
+    /** Notification center in the default top bar (`<NotificationCenter adapter={…} />`). */
+    notifications?: React.ReactNode;
+    /** Extra default top-bar actions (theme switch, help). */
+    actions?: React.ReactNode;
+    /** User menu in the default top bar. */
+    user?: UserMenuProps;
+    /** Live sidebar badges by nav item id. */
+    badges?: Record<string, BadgeSpec | undefined>;
+    /** Extra sidebar footer content (above the collapse button). */
+    sidebarFooter?: React.ReactNode;
+    /** Footer link in the app switcher ("Manage apps & modules…"). */
+    appSwitcherFooter?: React.ReactNode;
+    /** `sidebar` (default) or `topnav` (portal-style: top-level links in the top bar, no sidebar). */
+    layout?: "sidebar" | "topnav";
+    /** Permissions still loading: sidebar skeleton. */
+    loading?: boolean;
+    /** Move focus to `main` and announce the page title after route changes. Default `true`. */
+    announceRouteChanges?: boolean;
+    /** `screen` fills the viewport (default); `fill` fills the parent (embedded previews). */
+    height?: "screen" | "fill";
+    /** Mount the ⌘K palette, Toaster and confirm dialog. Default `true`. */
+    globals?: boolean;
+    labels?: Partial<AppShellLabels>;
+}
+/**
+ * The one shell every app runs in: sidebar, top bar, content, skip link, mobile sheet nav, ⌘K
+ * palette, toasts and confirm. Switching apps swaps the nav, commands, "New" menu, links and
+ * accent; everything else stays. Use inside `AppShellProvider`.
+ *
+ * ```tsx
+ * <AppShellProvider apps={[siteApp, crmApp]} sharedNav={shared} currentPath={pathname} linkComponent={Link} navigate={router.push}>
+ *   <AppShell user={{ name: "Ada Lovelace", email: "ada@northwind.io", items: account }} notifications={<NotificationCenter adapter={inbox} />}>
+ *     {children}
+ *   </AppShell>
+ * </AppShellProvider>
+ * ```
+ */
+export declare const AppShell: React.ForwardRefExoticComponent<AppShellProps & React.RefAttributes<HTMLDivElement>>;
+export {};