@vamos-ui/react 0.0.0-stage → 0.3.0

package/dist/business/permission-matrix.d.ts

@@ -0,0 +1,158 @@
+import * as React from "react";
+import { type LabelFn } from "../lib/labels.js";
+import { type PermissionChange, type PermissionDependency, type PermissionLevel, type PermissionScope, type PermissionValue } from "./permission-core.js";
+export declare const permissionMatrixLabels: {
+    label: string;
+    resource: string;
+    none: string;
+    own: string;
+    team: string;
+    all: string;
+    granted: string;
+    denied: string;
+    notApplicable: string;
+    cell: string;
+    inheritedFrom: string;
+    inheritedState: string;
+    override: string;
+    reset: string;
+    grantRow: string;
+    revokeRow: string;
+    grantColumn: string;
+    revokeColumn: string;
+    grantGroup: string;
+    revokeGroup: string;
+    collapse: string;
+    expand: string;
+    scopeMenu: string;
+    dependencyRaised: string;
+    dependencyLowered: string;
+    changes: string;
+    review: string;
+    discard: string;
+    save: string;
+    close: string;
+    reviewTitle: string;
+    reviewDescription: string;
+    change: string;
+    dangerous: string;
+    noChanges: string;
+    readOnly: string;
+    differs: string;
+    permission: string;
+    keyboard: string;
+};
+export type PermissionMatrixLabels = typeof permissionMatrixLabels;
+export interface PermissionResource {
+    id: string;
+    label: string;
+    /** Rows with the same group are shown under a collapsible heading. */
+    group?: string;
+    description?: string;
+    /** Actions that apply to this resource. Default: all. */
+    actions?: string[];
+}
+export interface PermissionAction {
+    id: string;
+    label: string;
+    /** Scope cells (None / Own / Team / All) instead of a checkbox. */
+    scoped?: boolean;
+    /** Highlight grants ("Delete: All"). */
+    danger?: boolean;
+}
+export interface PermissionMatrixProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "defaultValue" | "onChange"> {
+    resources: PermissionResource[];
+    actions: PermissionAction[];
+    /** Scope names. Default None / Own / Team / All from the dictionary. */
+    scopes?: {
+        id: PermissionScope;
+        label: string;
+    }[];
+    value?: PermissionValue;
+    defaultValue?: PermissionValue;
+    onValueChange?: (value: PermissionValue) => void;
+    /** From the parent role: shown locked until overridden. */
+    inherited?: PermissionValue;
+    /** Parent role name ("Manager"). */
+    inheritedFrom?: string;
+    /** Saved value: changed cells get a dot and a save bar appears. */
+    baseline?: PermissionValue;
+    onSave?: (value: PermissionValue, changes: PermissionChange[]) => Promise<void> | void;
+    /** Role / plan being edited, for the review dialog ("Sales rep"). */
+    subject?: string;
+    readOnly?: boolean;
+    /** "edit" requires "view": kept consistent automatically. */
+    dependencies?: PermissionDependency[];
+    /** Called with a message when a dependency changed another cell (show a toast). */
+    onDependencyApplied?: (message: string) => void;
+    /** Max height of the scroll area (sticky headers). Default none. */
+    maxHeight?: string;
+    labels?: Partial<PermissionMatrixLabels>;
+}
+/**
+ * Who may do what: resources × actions with checkbox or scope cells (None / Own / Team / All),
+ * inheritance from a parent role, row / column / group bulk toggles, dependencies ("Edit needs
+ * View"), sticky headers, and a review-before-save diff. A WAI-ARIA grid.
+ *
+ * ```tsx
+ * <PermissionMatrix resources={resources} actions={actions} value={value} onValueChange={setValue}
+ *   inherited={manager} inheritedFrom="Manager" baseline={saved} onSave={save} dependencies={[{ action: "edit", requires: "view" }]} />
+ * ```
+ */
+export declare const PermissionMatrix: React.ForwardRefExoticComponent<PermissionMatrixProps & React.RefAttributes<HTMLDivElement>>;
+export interface PermissionMatrixCellProps {
+    resource: PermissionResource;
+    action: PermissionAction;
+    applicable: boolean;
+    own: PermissionLevel | undefined;
+    inherited: PermissionLevel | undefined;
+    inheritedFrom: string;
+    changed: boolean;
+    readOnly?: boolean;
+    scopeNames?: Record<string, string>;
+    pos: string;
+    tabIndex: number;
+    onFocus: () => void;
+    onNav: (e: React.KeyboardEvent) => boolean;
+    onToggle: () => void;
+    onSet: (level: PermissionLevel | undefined) => void;
+    onReset: () => void;
+    t: LabelFn<PermissionMatrixLabels>;
+}
+/** One grid cell: a checkbox (boolean actions) or a scope menu (scoped actions). */
+export declare function PermissionMatrixCell({ resource: r, action: a, applicable, own, inherited, inheritedFrom, changed, readOnly, scopeNames, pos, tabIndex, onFocus, onNav, onToggle, onSet, onReset, t, }: PermissionMatrixCellProps): React.JSX.Element;
+export interface PermissionDiffProps extends React.HTMLAttributes<HTMLUListElement> {
+    changes: PermissionChange[];
+    resources: PermissionResource[];
+    actions: PermissionAction[];
+    scopes?: {
+        id: PermissionScope;
+        label: string;
+    }[];
+    labels?: Partial<PermissionMatrixLabels>;
+}
+/** The review list before saving: "Quotes · Delete: None → Team", sensitive grants flagged. */
+export declare function PermissionDiff({ changes, resources, actions, scopes, labels, className, ...props }: PermissionDiffProps): React.JSX.Element;
+export interface PermissionCompareProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Roles or plans as columns. */
+    subjects: {
+        id: string;
+        label: string;
+        value: PermissionValue;
+        description?: string;
+    }[];
+    resources: PermissionResource[];
+    actions: PermissionAction[];
+    scopes?: {
+        id: PermissionScope;
+        label: string;
+    }[];
+    /** Only rows where subjects differ. */
+    onlyDifferences?: boolean;
+    /** Highlight rows where subjects differ. Default `true`. */
+    highlightDifferences?: boolean;
+    maxHeight?: string;
+    labels?: Partial<PermissionMatrixLabels>;
+}
+/** Subjects side by side: one row per permission, one column per role or plan. Read-only. */
+export declare function PermissionCompare({ subjects, resources, actions, scopes, onlyDifferences, highlightDifferences, maxHeight, labels, className, ...props }: PermissionCompareProps): React.JSX.Element;

package/dist/business/permission-matrix.js

@@ -0,0 +1,341 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as React from "react";
+import { Check, ChevronRight, Lock, Minus, ShieldCheck, Eye } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { useLabels } from "../lib/labels.js";
+import { useControllableState } from "../lib/use-controllable-state.js";
+import { Button } from "../components/button.js";
+import { Badge } from "../components/badge.js";
+import { DropdownMenu, DropdownMenuContent, DropdownMenuLabel, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuItem, DropdownMenuTrigger } from "../components/dropdown-menu.js";
+import { Dialog, DialogBody, DialogContent, DialogFooter, DialogHeader } from "../components/dialog.js";
+import { applyDependencies, diffPermissions, effectiveLevel, isGranted, scopeRank, setMany, setPermission, SCOPE_ORDER, } from "./permission-core.js";
+export const permissionMatrixLabels = {
+    label: "Permissions",
+    resource: "Resource",
+    none: "None",
+    own: "Own",
+    team: "Team",
+    all: "All",
+    granted: "Allowed",
+    denied: "Not allowed",
+    notApplicable: "Not applicable",
+    cell: "{resource}, {action}: {level}",
+    inheritedFrom: "From {role}",
+    inheritedState: "{level}, inherited from {role}",
+    override: "Changed from {role}",
+    reset: "Reset to inherited",
+    grantRow: "Grant all actions on {resource}",
+    revokeRow: "Revoke all actions on {resource}",
+    grantColumn: "Grant {action} on all resources",
+    revokeColumn: "Revoke {action} on all resources",
+    grantGroup: "Grant everything in {group}",
+    revokeGroup: "Revoke everything in {group}",
+    collapse: "Collapse {group}",
+    expand: "Expand {group}",
+    scopeMenu: "Scope for {resource}, {action}",
+    dependencyRaised: "{requires} enabled because {action} requires it",
+    dependencyLowered: "{action} lowered because it requires {requires}",
+    changes: "{count, plural, one {# change} other {# changes}}",
+    review: "Review",
+    discard: "Discard",
+    save: "Save",
+    close: "Close",
+    reviewTitle: "Review permission changes",
+    reviewDescription: "{count, plural, one {# change} other {# changes}} for {subject}.",
+    change: "{resource} · {action}: {from} → {to}",
+    dangerous: "Sensitive",
+    noChanges: "No changes",
+    readOnly: "System role · read only",
+    differs: "Differs",
+    permission: "Permission",
+    keyboard: "Arrow keys move. Space toggles, Enter opens scopes, 1–4 pick a scope, Delete resets to inherited.",
+};
+const levelLabel = (t, v, scoped, scopeNames) => {
+    if (!scoped)
+        return isGranted(v) ? t("granted") : t("denied");
+    const s = v === true ? "all" : v === false || v === undefined ? "none" : v;
+    return scopeNames?.[s] ?? t(s);
+};
+/**
+ * Who may do what: resources × actions with checkbox or scope cells (None / Own / Team / All),
+ * inheritance from a parent role, row / column / group bulk toggles, dependencies ("Edit needs
+ * View"), sticky headers, and a review-before-save diff. A WAI-ARIA grid.
+ *
+ * ```tsx
+ * <PermissionMatrix resources={resources} actions={actions} value={value} onValueChange={setValue}
+ *   inherited={manager} inheritedFrom="Manager" baseline={saved} onSave={save} dependencies={[{ action: "edit", requires: "view" }]} />
+ * ```
+ */
+export const PermissionMatrix = React.forwardRef(function PermissionMatrix({ resources, actions, scopes, value: valueProp, defaultValue, onValueChange, inherited, inheritedFrom = "parent role", baseline, onSave, subject = "this role", readOnly, dependencies, onDependencyApplied, maxHeight, labels, className, ...props }, ref) {
+    const t = useLabels("permissionMatrix", permissionMatrixLabels, labels);
+    const [value, setValueState] = useControllableState({ value: valueProp, defaultValue: defaultValue ?? {} });
+    const [collapsed, setCollapsed] = React.useState(() => new Set());
+    const [focus, setFocus] = React.useState({ r: 0, c: 0 });
+    const [live, setLive] = React.useState("");
+    const [reviewOpen, setReviewOpen] = React.useState(false);
+    const [saving, setSaving] = React.useState(false);
+    const gridRef = React.useRef(null);
+    const scopeNames = React.useMemo(() => (scopes ? Object.fromEntries(scopes.map((s) => [s.id, s.label])) : undefined), [scopes]);
+    // Groups in first-seen order.
+    const groups = React.useMemo(() => {
+        const out = [];
+        for (const r of resources) {
+            const key = r.group ?? "";
+            let g = out.find((x) => x.key === key);
+            if (!g)
+                out.push((g = { key, label: r.group, resources: [] }));
+            g.resources.push(r);
+        }
+        return out;
+    }, [resources]);
+    const visibleRows = groups.flatMap((g) => (collapsed.has(g.key) ? [] : g.resources));
+    const actionById = React.useMemo(() => new Map(actions.map((a) => [a.id, a])), [actions]);
+    const applies = (r, a) => !r.actions || r.actions.includes(a.id);
+    const commit = (next, changed) => {
+        let v = next;
+        if (dependencies?.length) {
+            const res = applyDependencies(next, dependencies, { changed, scoped: (id) => !!actionById.get(id)?.scoped, resources: resources.map((r) => r.id) });
+            v = res.value;
+            const first = res.adjusted[0];
+            if (first) {
+                const raised = first.action === first.reason.requires;
+                const msg = t(raised ? "dependencyRaised" : "dependencyLowered", {
+                    action: actionById.get(first.reason.action)?.label ?? first.reason.action,
+                    requires: actionById.get(first.reason.requires)?.label ?? first.reason.requires,
+                });
+                setLive(msg);
+                onDependencyApplied?.(msg);
+            }
+        }
+        setValueState(v);
+        onValueChange?.(v);
+    };
+    const setCell = (r, a, level) => {
+        if (readOnly || !applies(r, a))
+            return;
+        commit(setPermission(value, r.id, a.id, level), { resource: r.id, action: a.id });
+    };
+    const toggleCell = (r, a) => {
+        const cur = effectiveLevel(value, inherited, r.id, a.id);
+        if (a.scoped)
+            setCell(r, a, isGranted(cur) ? "none" : "all");
+        else
+            setCell(r, a, !isGranted(cur));
+    };
+    const resetCell = (r, a) => {
+        if (readOnly)
+            return;
+        commit(setPermission(value, r.id, a.id, undefined), { resource: r.id, action: a.id });
+    };
+    const bulk = (cells) => {
+        const list = cells.filter((x) => applies(x.r, x.a));
+        if (readOnly || !list.length)
+            return;
+        const allOn = list.every((x) => scopeRank(effectiveLevel(value, inherited, x.r.id, x.a.id)) === 3);
+        const next = setMany(value, list.map((x) => ({ resource: x.r.id, action: x.a.id })), (c) => (actionById.get(c.action)?.scoped ? (allOn ? "none" : "all") : !allOn));
+        commit(next);
+    };
+    const allGranted = (cells) => {
+        const list = cells.filter((x) => applies(x.r, x.a));
+        return list.length > 0 && list.every((x) => scopeRank(effectiveLevel(value, inherited, x.r.id, x.a.id)) === 3);
+    };
+    const changes = React.useMemo(() => (baseline ? diffPermissions(baseline, value) : []), [baseline, value]);
+    const changedKey = React.useMemo(() => new Set(changes.map((c) => `${c.resource}\u0000${c.action}`)), [changes]);
+    // Roving focus. r = -1 → header row (column toggles); c = -1 → row header (row toggle).
+    const clamp = (cell) => ({
+        r: Math.max(-1, Math.min(visibleRows.length - 1, cell.r)),
+        c: Math.max(-1, Math.min(actions.length - 1, cell.c)),
+    });
+    const cur = clamp(focus);
+    const focusAt = (cell) => {
+        const next = clamp(cell);
+        if (next.r === -1 && next.c === -1)
+            next.c = 0;
+        setFocus(next);
+        requestAnimationFrame(() => gridRef.current?.querySelector(`[data-pm-pos="${next.r}:${next.c}"]`)?.focus());
+    };
+    const onKeyNav = (e, cell) => {
+        const mod = e.ctrlKey || e.metaKey;
+        let target = null;
+        if (e.key === "ArrowRight")
+            target = { r: cell.r, c: cell.c + 1 };
+        else if (e.key === "ArrowLeft")
+            target = { r: cell.r, c: cell.c - 1 };
+        else if (e.key === "ArrowDown")
+            target = { r: cell.r + 1, c: cell.c };
+        else if (e.key === "ArrowUp")
+            target = { r: cell.r - 1, c: cell.c };
+        else if (e.key === "Home")
+            target = mod ? { r: 0, c: 0 } : { r: cell.r, c: -1 };
+        else if (e.key === "End")
+            target = mod ? { r: visibleRows.length - 1, c: actions.length - 1 } : { r: cell.r, c: actions.length - 1 };
+        else if (e.key === "PageDown")
+            target = { r: cell.r + 5, c: cell.c };
+        else if (e.key === "PageUp")
+            target = { r: cell.r - 5, c: cell.c };
+        if (target) {
+            // RTL: left/right swap visually.
+            const rtl = gridRef.current?.closest("[dir=rtl]");
+            if (rtl && (e.key === "ArrowRight" || e.key === "ArrowLeft"))
+                target = { r: cell.r, c: cell.c + (e.key === "ArrowRight" ? -1 : 1) };
+            e.preventDefault();
+            focusAt(target);
+            return true;
+        }
+        return false;
+    };
+    const tab = (cell) => (cur.r === cell.r && cur.c === cell.c ? 0 : -1);
+    const colCount = actions.length + 1;
+    return (_jsxs("div", { ref: ref, "data-slot": "permission-matrix", "data-readonly": readOnly ? "" : undefined, className: cn("vui-pm flex min-w-0 flex-col", className), ...props, children: [_jsx("div", { className: "vui-pm-scroll overflow-auto rounded-ui-lg border border-line bg-surface", style: maxHeight ? { maxHeight } : undefined, children: _jsxs("table", { ref: gridRef, role: "grid", "aria-label": props["aria-label"] ?? t("label"), "aria-readonly": readOnly || undefined, className: "w-full border-separate border-spacing-0 text-sm", children: [_jsx("caption", { className: "sr-only", children: t("keyboard") }), _jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", className: "vui-pm-sticky vui-pm-corner sticky start-0 top-0 z-30 border-b border-line px-3 py-2.5 text-start text-[11px] font-medium tracking-[0.04em] text-fg-subtle uppercase", children: readOnly ? (_jsxs("span", { className: "inline-flex items-center gap-1.5 normal-case tracking-normal", children: [_jsx(Lock, { "aria-hidden": true, className: "size-3" }), " ", t("readOnly")] })) : (t("resource")) }), actions.map((a, ci) => {
+                                        const cells = visibleRows.map((r) => ({ r, a }));
+                                        const on = allGranted(cells);
+                                        return (_jsx("th", { scope: "col", className: "vui-pm-sticky sticky top-0 z-20 min-w-[6.5rem] border-b border-line px-1.5 py-1.5 text-center font-medium", children: readOnly ? (_jsx("span", { className: "block px-1.5 py-1 text-[13px] text-fg", children: a.label })) : (_jsxs("button", { type: "button", "data-pm-pos": `-1:${ci}`, tabIndex: tab({ r: -1, c: ci }), "aria-label": t(on ? "revokeColumn" : "grantColumn", { action: a.label }), title: t(on ? "revokeColumn" : "grantColumn", { action: a.label }), onFocus: () => setFocus({ r: -1, c: ci }), onKeyDown: (e) => onKeyNav(e, { r: -1, c: ci }), onClick: () => bulk(cells), className: "focus-ring inline-flex w-full items-center justify-center gap-1 rounded-ui-sm px-1.5 py-1 text-[13px] text-fg hover:bg-hover", children: [a.label, a.danger ? _jsx("span", { "aria-hidden": true, className: "size-1.5 rounded-full bg-danger" }) : null] })) }, a.id));
+                                    })] }) }), groups.map((g) => {
+                            const isCollapsed = collapsed.has(g.key);
+                            const groupCells = g.resources.flatMap((r) => actions.map((a) => ({ r, a })));
+                            const groupOn = allGranted(groupCells);
+                            return (_jsxs("tbody", { "data-slot": "permission-matrix-group", children: [g.label ? (_jsx("tr", { className: "vui-pm-group-row", children: _jsx("th", { scope: "colgroup", colSpan: colCount, className: "vui-pm-sticky-group sticky start-0 border-b border-line px-1.5 py-1 text-start", children: _jsxs("div", { className: "flex items-center gap-1", children: [_jsxs("button", { type: "button", "aria-expanded": !isCollapsed, 
+                                                        // The visible group name is the accessible name (WCAG 2.5.3); aria-expanded carries the state.
+                                                        title: t(isCollapsed ? "expand" : "collapse", { group: g.label }), onClick: () => setCollapsed((s) => {
+                                                            const n = new Set(s);
+                                                            if (n.has(g.key))
+                                                                n.delete(g.key);
+                                                            else
+                                                                n.add(g.key);
+                                                            return n;
+                                                        }), className: "focus-ring inline-flex items-center gap-1.5 rounded-ui-sm px-1.5 py-1 font-mono text-[11px] font-medium tracking-[0.06em] text-fg-muted uppercase hover:bg-hover", children: [_jsx(ChevronRight, { "aria-hidden": true, className: cn("size-3.5 transition-transform duration-150 rtl:rotate-180", !isCollapsed && "rotate-90 rtl:rotate-90") }), g.label, _jsxs("span", { className: "font-sans tracking-normal text-fg-subtle normal-case tabular", children: ["\u00B7 ", g.resources.length] })] }), !readOnly ? (_jsx(Button, { size: "xs", variant: "ghost", className: "ms-auto text-fg-muted", onClick: () => bulk(groupCells), children: t(groupOn ? "revokeGroup" : "grantGroup", { group: g.label }) })) : null] }) }) })) : null, isCollapsed
+                                        ? null
+                                        : g.resources.map((r) => {
+                                            const ri = visibleRows.indexOf(r);
+                                            const rowCells = actions.map((a) => ({ r, a }));
+                                            const rowOn = allGranted(rowCells);
+                                            return (_jsxs("tr", { "data-slot": "permission-matrix-row", className: "vui-pm-row", children: [_jsx("th", { scope: "row", className: "vui-pm-sticky-col sticky start-0 z-10 border-b border-line px-1.5 py-1 text-start font-normal", children: readOnly ? (_jsxs("span", { className: "block px-1.5 py-1", children: [_jsx("span", { className: "block text-[13px] font-medium text-fg", children: r.label }), r.description ? _jsx("span", { className: "block text-xs text-fg-subtle", children: r.description }) : null] })) : (_jsxs("button", { type: "button", "data-pm-pos": `${ri}:-1`, tabIndex: tab({ r: ri, c: -1 }), onFocus: () => setFocus({ r: ri, c: -1 }), onKeyDown: (e) => onKeyNav(e, { r: ri, c: -1 }), onClick: () => bulk(rowCells), className: "focus-ring group/rt flex w-full min-w-[11rem] items-center gap-2 rounded-ui-sm px-1.5 py-1 text-start hover:bg-hover", children: [_jsxs("span", { className: "min-w-0 flex-1", children: [_jsx("span", { className: "block text-[13px] font-medium text-fg", children: r.label }), r.description ? _jsx("span", { className: "block text-xs text-fg-subtle", children: r.description }) : null] }), _jsxs("span", { className: "sr-only", children: [", ", t(rowOn ? "revokeRow" : "grantRow", { resource: r.label })] }), _jsx(ShieldCheck, { "aria-hidden": true, className: cn("size-3.5 shrink-0 text-fg-subtle opacity-0 transition-opacity group-hover/rt:opacity-100 group-focus-visible/rt:opacity-100", rowOn && "text-accent-ink opacity-100") })] })) }), actions.map((a, ci) => (_jsx("td", { role: "gridcell", className: "border-b border-line px-1 py-1 text-center", children: _jsx(PermissionMatrixCell, { resource: r, action: a, applicable: applies(r, a), own: value[r.id]?.[a.id], inherited: inherited?.[r.id]?.[a.id], inheritedFrom: inheritedFrom, changed: changedKey.has(`${r.id}\u0000${a.id}`), readOnly: readOnly, scopeNames: scopeNames, pos: `${ri}:${ci}`, tabIndex: tab({ r: ri, c: ci }), onFocus: () => setFocus({ r: ri, c: ci }), onNav: (e) => onKeyNav(e, { r: ri, c: ci }), onToggle: () => toggleCell(r, a), onSet: (l) => setCell(r, a, l), onReset: () => resetCell(r, a), t: t }) }, a.id)))] }, r.id));
+                                        })] }, g.key || "_"));
+                        })] }) }), _jsx("span", { className: "sr-only", "aria-live": "polite", "aria-atomic": true, children: live }), baseline && changes.length && !readOnly ? (_jsxs("div", { "data-slot": "permission-matrix-savebar", className: "vui-pm-savebar sticky bottom-3 z-30 mx-auto mt-3 flex w-fit max-w-full items-center gap-2 rounded-full surface-popover py-1.5 ps-4 pe-1.5 text-sm", children: [_jsxs("span", { className: "inline-flex items-center gap-2 text-fg tabular", "aria-live": "polite", children: [_jsx("span", { "aria-hidden": true, className: "size-1.5 rounded-full bg-accent-ink" }), t("changes", { count: changes.length })] }), _jsxs(Button, { size: "sm", variant: "ghost", onClick: () => setReviewOpen(true), children: [_jsx(Eye, {}), " ", t("review")] }), _jsx(Button, { size: "sm", variant: "ghost", onClick: () => commit(baseline), children: t("discard") }), onSave ? (_jsx(Button, { size: "sm", variant: "primary", pill: true, loading: saving, onClick: async () => {
+                            setSaving(true);
+                            try {
+                                await onSave(value, changes);
+                            }
+                            finally {
+                                setSaving(false);
+                            }
+                        }, children: t("save") })) : null] })) : null, baseline ? (_jsx(Dialog, { open: reviewOpen, onOpenChange: setReviewOpen, children: _jsxs(DialogContent, { size: "md", children: [_jsx(DialogHeader, { title: t("reviewTitle"), description: t("reviewDescription", { count: changes.length, subject }) }), _jsx(DialogBody, { children: _jsx(PermissionDiff, { changes: changes, resources: resources, actions: actions, scopes: scopes, labels: labels }) }), _jsxs(DialogFooter, { children: [_jsx(Button, { variant: "ghost", onClick: () => setReviewOpen(false), children: t("close") }), onSave ? (_jsx(Button, { variant: "primary", loading: saving, onClick: async () => {
+                                        setSaving(true);
+                                        try {
+                                            await onSave(value, changes);
+                                            setReviewOpen(false);
+                                        }
+                                        finally {
+                                            setSaving(false);
+                                        }
+                                    }, children: t("save") })) : null] })] }) })) : null] }));
+});
+/** One grid cell: a checkbox (boolean actions) or a scope menu (scoped actions). */
+export function PermissionMatrixCell({ resource: r, action: a, applicable, own, inherited, inheritedFrom, changed, readOnly, scopeNames, pos, tabIndex, onFocus, onNav, onToggle, onSet, onReset, t, }) {
+    const level = own !== undefined ? own : inherited;
+    const isInherited = own === undefined && inherited !== undefined;
+    const isOverride = own !== undefined && inherited !== undefined && scopeRank(own) !== scopeRank(inherited);
+    const rank = scopeRank(level);
+    const text = levelLabel(t, level, !!a.scoped, scopeNames);
+    const state = isInherited ? t("inheritedState", { level: text, role: inheritedFrom }) : text;
+    const name = t("cell", { resource: r.label, action: a.label, level: state });
+    const danger = !!a.danger && rank === 3;
+    const [menuOpen, setMenuOpen] = React.useState(false);
+    const common = {
+        "data-pm-pos": pos,
+        tabIndex,
+        onFocus,
+        "data-level": a.scoped ? SCOPE_ORDER[rank] : rank ? "on" : "off",
+        "data-inherited": isInherited ? "" : undefined,
+        "data-override": isOverride ? "" : undefined,
+        "data-changed": changed ? "" : undefined,
+        "data-danger": danger ? "" : undefined,
+        title: isInherited ? t("inheritedFrom", { role: inheritedFrom }) : isOverride ? t("override", { role: inheritedFrom }) : undefined,
+    };
+    const base = "vui-pm-cell focus-ring relative inline-flex h-8 w-full min-w-[5.5rem] items-center justify-center gap-1 rounded-ui-sm text-xs font-medium transition-[background-color,box-shadow,color] duration-150";
+    if (!applicable) {
+        return (_jsx("span", { ...common, role: "img", "aria-label": t("cell", { resource: r.label, action: a.label, level: t("notApplicable") }), className: cn(base, "text-fg-subtle/60"), onKeyDown: (e) => void onNav(e), children: _jsx(Minus, { "aria-hidden": true, className: "size-3" }) }));
+    }
+    const marks = (_jsxs(_Fragment, { children: [isInherited ? _jsx(Lock, { "aria-hidden": true, className: "size-3 text-fg-subtle" }) : null, changed ? _jsx("span", { "aria-hidden": true, className: "vui-pm-dot absolute end-1 top-1 size-1.5 rounded-full bg-accent-ink" }) : null] }));
+    const scopeKeys = (e) => {
+        if (readOnly)
+            return false;
+        if (["1", "2", "3", "4"].includes(e.key) && a.scoped) {
+            e.preventDefault();
+            onSet(SCOPE_ORDER[Number(e.key) - 1]);
+            return true;
+        }
+        if ((e.key === "Delete" || e.key === "Backspace") && own !== undefined && inherited !== undefined) {
+            e.preventDefault();
+            onReset();
+            return true;
+        }
+        return false;
+    };
+    if (!a.scoped) {
+        return (_jsxs("button", { type: "button", role: "checkbox", "aria-checked": rank > 0, "aria-label": name, "aria-readonly": readOnly || undefined, ...common, onClick: () => !readOnly && onToggle(), onKeyDown: (e) => {
+                if (onNav(e) || scopeKeys(e))
+                    return;
+                if (e.key === "Enter") {
+                    e.preventDefault();
+                    if (!readOnly)
+                        onToggle();
+                }
+            }, className: cn(base, !readOnly && "hover:bg-hover", isInherited && "opacity-75"), children: [_jsx("span", { "aria-hidden": true, className: cn("vui-pm-check inline-flex size-[18px] items-center justify-center rounded-[5px] border transition-colors", rank ? "border-transparent bg-accent text-accent-fg" : "border-field-border bg-field", danger && "tone-danger border-transparent bg-(--tone) text-scene", isInherited && rank && "border-dashed border-accent-ink bg-accent-soft text-accent-ink"), children: rank ? _jsx(Check, { strokeWidth: 3, className: "size-3" }) : null }), marks] }));
+    }
+    const content = (_jsxs(_Fragment, { children: [_jsx("span", { className: "vui-pm-level-text", children: rank === 0 ? _jsx("span", { className: "text-fg-subtle", children: "\u2014" }) : text }), rank === 3 ? _jsx(ShieldCheck, { "aria-hidden": true, className: "size-3" }) : null, marks] }));
+    if (readOnly) {
+        return (_jsx("span", { ...common, role: "img", "aria-label": name, className: cn(base, "vui-pm-scope"), onKeyDown: (e) => void onNav(e), children: content }));
+    }
+    return (_jsxs(DropdownMenu, { open: menuOpen, onOpenChange: setMenuOpen, children: [_jsx(DropdownMenuTrigger, { asChild: true, children: _jsx("button", { type: "button", "aria-label": name, ...common, onKeyDown: (e) => {
+                        if (onNav(e) || scopeKeys(e)) {
+                            e.preventDefault();
+                            return;
+                        }
+                        if (e.key === " ") {
+                            // Space toggles None ↔ All; Enter opens the menu.
+                            e.preventDefault();
+                            onToggle();
+                        }
+                    }, onPointerDown: (e) => {
+                        // Keep Radix from opening on pointerdown so a click opens like Enter does.
+                        if (e.button === 0 && !e.ctrlKey) {
+                            e.preventDefault();
+                            setMenuOpen((o) => !o);
+                        }
+                    }, className: cn(base, "vui-pm-scope hover:brightness-[0.97]", isInherited && "opacity-75"), children: content }) }), _jsxs(DropdownMenuContent, { align: "center", className: "min-w-44", children: [_jsx(DropdownMenuLabel, { children: t("scopeMenu", { resource: r.label, action: a.label }) }), _jsx(DropdownMenuRadioGroup, { value: SCOPE_ORDER[rank], onValueChange: (v) => onSet(v), children: SCOPE_ORDER.map((s, i) => (_jsxs(DropdownMenuRadioItem, { value: s, children: [_jsx("span", { className: "flex-1", children: scopeNames?.[s] ?? t(s) }), _jsx("span", { className: "ms-4 font-mono text-[11px] text-fg-subtle", children: i + 1 })] }, s))) }), own !== undefined && inherited !== undefined ? (_jsxs(_Fragment, { children: [_jsx(DropdownMenuSeparator, {}), _jsx(DropdownMenuItem, { onSelect: onReset, children: t("reset") })] })) : null] })] }));
+}
+/** The review list before saving: "Quotes · Delete: None → Team", sensitive grants flagged. */
+export function PermissionDiff({ changes, resources, actions, scopes, labels, className, ...props }) {
+    const t = useLabels("permissionMatrix", permissionMatrixLabels, labels);
+    const scopeNames = scopes ? Object.fromEntries(scopes.map((s) => [s.id, s.label])) : undefined;
+    if (!changes.length)
+        return _jsx("p", { className: "text-sm text-fg-subtle", children: t("noChanges") });
+    return (_jsx("ul", { "data-slot": "permission-diff", className: cn("m-0 flex list-none flex-col divide-y divide-line rounded-ui-lg border border-line p-0", className), ...props, children: changes.map((c) => {
+            const r = resources.find((x) => x.id === c.resource);
+            const a = actions.find((x) => x.id === c.action);
+            const scoped = !!a?.scoped;
+            const from = levelLabel(t, c.from, scoped, scopeNames);
+            const to = levelLabel(t, c.to, scoped, scopeNames);
+            const up = scopeRank(c.to) > scopeRank(c.from);
+            return (_jsxs("li", { className: "flex flex-wrap items-center gap-x-3 gap-y-1 px-3.5 py-2.5 text-sm", children: [_jsxs("span", { className: "min-w-0 flex-1 text-fg", children: [_jsx("span", { className: "font-medium", children: r?.label ?? c.resource }), _jsx("span", { className: "text-fg-subtle", children: " \u00B7 " }), a?.label ?? c.action] }), _jsxs("span", { className: "inline-flex items-center gap-1.5 text-[13px] tabular", children: [_jsx("span", { className: "text-fg-muted line-through decoration-fg-subtle/50", children: from }), _jsx("span", { "aria-hidden": true, className: "text-fg-subtle", children: "\u2192" }), _jsx("span", { className: cn("font-medium", up ? "text-fg" : "text-fg-muted"), children: to }), _jsx("span", { className: "sr-only", children: t("change", { resource: r?.label ?? c.resource, action: a?.label ?? c.action, from, to }) })] }), a?.danger && up ? (_jsx(Badge, { tone: "danger", size: "sm", children: t("dangerous") })) : null] }, `${c.resource}:${c.action}`));
+        }) }));
+}
+/** Subjects side by side: one row per permission, one column per role or plan. Read-only. */
+export function PermissionCompare({ subjects, resources, actions, scopes, onlyDifferences, highlightDifferences = true, maxHeight, labels, className, ...props }) {
+    const t = useLabels("permissionMatrix", permissionMatrixLabels, labels);
+    const scopeNames = scopes ? Object.fromEntries(scopes.map((s) => [s.id, s.label])) : undefined;
+    const rows = resources.flatMap((r) => actions
+        .filter((a) => !r.actions || r.actions.includes(a.id))
+        .map((a) => {
+        const levels = subjects.map((s) => s.value[r.id]?.[a.id]);
+        const differs = new Set(levels.map((l) => scopeRank(l))).size > 1;
+        return { r, a, levels, differs };
+    }));
+    const shown = onlyDifferences ? rows.filter((x) => x.differs) : rows;
+    return (_jsx("div", { "data-slot": "permission-compare", className: cn("vui-pm overflow-auto rounded-ui-lg border border-line bg-surface", className), style: maxHeight ? { maxHeight } : undefined, ...props, children: _jsxs("table", { className: "w-full border-separate border-spacing-0 text-sm", children: [_jsx("caption", { className: "sr-only", children: props["aria-label"] ?? t("label") }), _jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", className: "vui-pm-sticky vui-pm-corner sticky start-0 top-0 z-30 border-b border-line px-3 py-2.5 text-start text-[11px] font-medium tracking-[0.04em] text-fg-subtle uppercase", children: t("permission") }), subjects.map((s) => (_jsxs("th", { scope: "col", className: "vui-pm-sticky sticky top-0 z-20 min-w-[8rem] border-b border-line px-3 py-2 text-center align-bottom", children: [_jsx("span", { className: "block text-[13px] font-semibold text-fg", children: s.label }), s.description ? _jsx("span", { className: "block text-[11px] font-normal text-fg-subtle", children: s.description }) : null] }, s.id)))] }) }), _jsx("tbody", { children: shown.map(({ r, a, levels, differs }) => (_jsxs("tr", { "data-differs": differs ? "" : undefined, className: cn(highlightDifferences && differs && "vui-pm-differs"), children: [_jsxs("th", { scope: "row", className: "vui-pm-sticky-col sticky start-0 z-10 border-b border-line px-3 py-2 text-start font-normal", children: [_jsx("span", { className: "text-[13px] font-medium text-fg", children: r.label }), _jsx("span", { className: "text-fg-subtle", children: " \u00B7 " }), _jsx("span", { className: "text-[13px] text-fg-muted", children: a.label }), highlightDifferences && differs ? _jsxs("span", { className: "sr-only", children: [" (", t("differs"), ")"] }) : null] }), levels.map((l, i) => {
+                                const rank = scopeRank(l);
+                                return (_jsx("td", { className: "border-b border-line px-2 py-1.5 text-center", children: _jsx("span", { className: cn("vui-pm-cell inline-flex h-7 min-w-[5rem] items-center justify-center gap-1 rounded-ui-sm px-2 text-xs font-medium", a.scoped && "vui-pm-scope"), "data-level": a.scoped ? SCOPE_ORDER[rank] : rank ? "on" : "off", "data-danger": a.danger && rank === 3 ? "" : undefined, children: a.scoped ? (rank ? levelLabel(t, l, true, scopeNames) : _jsx("span", { className: "text-fg-subtle", children: "\u2014" })) : rank ? (_jsxs(_Fragment, { children: [_jsx(Check, { "aria-hidden": true, className: "size-3.5 text-accent-ink" }), _jsx("span", { className: "sr-only", children: t("granted") })] })) : (_jsxs(_Fragment, { children: [_jsx(Minus, { "aria-hidden": true, className: "size-3.5 text-fg-subtle" }), _jsx("span", { className: "sr-only", children: t("denied") })] })) }) }, subjects[i].id));
+                            })] }, `${r.id}:${a.id}`))) })] }) }));
+}

package/dist/business/setup-checklist.d.ts

@@ -0,0 +1,80 @@
+import * as React from "react";
+export declare const setupChecklistLabels: {
+    title: string;
+    progress: string;
+    progressShort: string;
+    dismiss: string;
+    reopen: string;
+    skip: string;
+    undoSkip: string;
+    optional: string;
+    todo: string;
+    in_progress: string;
+    done: string;
+    skipped: string;
+    locked: string;
+    itemName: string;
+    allDone: string;
+    allDoneBody: string;
+    hide: string;
+    details: string;
+};
+export type SetupChecklistLabels = typeof setupChecklistLabels;
+export type SetupItemStatus = "todo" | "in_progress" | "done" | "skipped";
+export interface SetupItem {
+    id: string;
+    title: string;
+    description?: string;
+    status: SetupItemStatus;
+    /** The deep link or action that completes this step. */
+    action?: {
+        label: string;
+        href?: string;
+        onSelect?: () => void;
+    };
+    optional?: boolean;
+    /** Depends on another step. */
+    locked?: {
+        reason: string;
+    };
+    /** "2 min". */
+    estimate?: string;
+}
+export interface SetupChecklistProps extends Omit<React.HTMLAttributes<HTMLElement>, "title"> {
+    title?: string;
+    description?: string;
+    items: SetupItem[];
+    onSkip?: (id: string) => void;
+    onUndoSkip?: (id: string) => void;
+    /** Controlled dismissal. Show `<SetupChecklistLauncher>` while dismissed. */
+    dismissed?: boolean;
+    onDismissedChange?: (dismissed: boolean) => void;
+    /** `card` (dashboard), `sidebar` (app shell), `popover` (opened from the launcher). Default `"card"`. */
+    variant?: "card" | "sidebar" | "popover";
+    /** Open the first unfinished step's details. Default `true`. */
+    expandFirstIncomplete?: boolean;
+    /** Called once when the last required step becomes done. */
+    onAllDone?: () => void;
+    loading?: boolean;
+    labels?: Partial<SetupChecklistLabels>;
+}
+/**
+ * A "Get started" panel: ordered setup steps with progress, deep-link actions, skip, lock and
+ * dismiss. Completion comes from the app (pass the new `status`); focus never jumps when a
+ * step completes on its own.
+ *
+ * ```tsx
+ * <SetupChecklist items={steps} onSkip={skip} dismissed={hidden} onDismissedChange={setHidden} />
+ * {hidden ? <SetupChecklistLauncher items={steps} onOpen={() => setHidden(false)} /> : null}
+ * ```
+ */
+export declare const SetupChecklist: React.ForwardRefExoticComponent<SetupChecklistProps & React.RefAttributes<HTMLElement>>;
+export interface SetupChecklistLauncherProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> {
+    items: SetupItem[];
+    onOpen: () => void;
+    /** Fixed to the bottom end of the viewport. Default `false` (in flow). */
+    floating?: boolean;
+    labels?: Partial<SetupChecklistLabels>;
+}
+/** A pill that reopens a dismissed checklist: "Setup guide · 3 of 6". */
+export declare const SetupChecklistLauncher: React.ForwardRefExoticComponent<SetupChecklistLauncherProps & React.RefAttributes<HTMLButtonElement>>;