@vamos-ui/react 0.0.0-stage → 0.3.0

package/dist/business/multi-step-form.d.ts

@@ -0,0 +1,131 @@
+import * as React from "react";
+export declare const multiStepFormLabels: {
+    back: string;
+    next: string;
+    submit: string;
+    submitting: string;
+    saveDraft: string;
+    savingDraft: string;
+    draftSaved: string;
+    draftFailed: string;
+    step: string;
+    stepHeading: string;
+    optional: string;
+    fixErrors: string;
+    submitFailed: string;
+    edit: string;
+    review: string;
+    leave: string;
+};
+export type MultiStepFormLabels = typeof multiStepFormLabels;
+export type MultiStepStatus = "upcoming" | "current" | "complete" | "error";
+export interface StepDef<C = unknown> {
+    id: string;
+    title: string;
+    description?: string;
+    optional?: boolean;
+    /** Conditional step: hidden (and skipped) while it returns `false`. Receives `context`. */
+    when?: (ctx: C) => boolean;
+    /** Runs on Next. `true` passes; a string is the summary error shown at the top of the step. */
+    validate?: () => true | string | Promise<true | string>;
+}
+export interface MultiStepFormProps<C = unknown> extends Omit<React.FormHTMLAttributes<HTMLFormElement>, "onSubmit" | "defaultValue"> {
+    steps: StepDef<C>[];
+    /** Current step id (controlled). */
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (id: string) => void;
+    /** Passed to `when` of conditional steps (usually the form values). */
+    context?: C;
+    /** Can't jump ahead past an invalid or unvisited step. Default `true`. */
+    linear?: boolean;
+    /** Runs on Submit (the last step). Throw to show the error and stay on the step. */
+    onComplete: () => Promise<void> | void;
+    onSaveDraft?: () => Promise<void> | void;
+    /** Saves the draft every `intervalMs` (needs `onSaveDraft`). */
+    autosave?: {
+        intervalMs: number;
+    };
+    /** `"page"`: sticky footer. `"dialog"`: footer in flow (put the form inside `DialogBody`). Default `"page"`. */
+    presentation?: "page" | "dialog";
+    orientation?: "horizontal" | "vertical";
+    /** Mirror the step in the URL (`?step=contract`), so a reload or a shared link resumes there. */
+    syncUrl?: boolean | {
+        key: string;
+    };
+    /** Warn before closing the tab until the form is submitted. */
+    confirmLeave?: boolean;
+    labels?: Partial<MultiStepFormLabels>;
+    children?: React.ReactNode;
+}
+/** State and navigation of the surrounding `MultiStepForm`. */
+export declare function useMultiStepForm(): {
+    current: string;
+    index: number;
+    total: number;
+    steps: StepDef<unknown>[];
+    next: () => Promise<void>;
+    back: () => void;
+    goTo: (id: string) => void;
+    saveDraft: () => Promise<void>;
+    isFirst: boolean;
+    isLast: boolean;
+    status: Record<string, MultiStepStatus>;
+    submitting: boolean;
+};
+/**
+ * A long form split into steps: per-step validation, conditional steps, draft saving, a review
+ * step and URL resume. Form-library agnostic — each step exposes `validate()`.
+ *
+ * ```tsx
+ * <MultiStepForm steps={steps} onComplete={submit}>
+ *   <MultiStepFormStepper />
+ *   <MultiStepFormStep id="identity">…fields…</MultiStepFormStep>
+ *   <MultiStepFormStep id="review"><MultiStepFormReview>…</MultiStepFormReview></MultiStepFormStep>
+ *   <MultiStepFormFooter />
+ * </MultiStepForm>
+ * ```
+ */
+export declare const MultiStepForm: <C = unknown>(props: MultiStepFormProps<C> & {
+    ref?: React.Ref<HTMLFormElement>;
+}) => React.ReactElement;
+export interface MultiStepFormStepperProps {
+    /** Stepper look. Default `"numbered"` (switches to compact on small screens). */
+    variant?: "numbered" | "compact" | "bar" | "dots";
+    className?: string;
+}
+/** The progress display (kit `Stepper`), wired to the form: completed steps are clickable. */
+export declare function MultiStepFormStepper({ variant, className }: MultiStepFormStepperProps): React.JSX.Element;
+export interface MultiStepFormStepProps extends Omit<React.HTMLAttributes<HTMLElement>, "title"> {
+    id: string;
+    /** Hide the built-in heading (render your own `h2` with `useMultiStepForm`). */
+    hideHeading?: boolean;
+    /** Keep the step mounted while hidden (keeps uncontrolled field values). Default `true`. */
+    keepMounted?: boolean;
+}
+/** One step's content. Shows its heading ("Step 2 of 5" + title) and the error summary. */
+export declare function MultiStepFormStep({ id, hideHeading, keepMounted, className, children, ...props }: MultiStepFormStepProps): React.JSX.Element | null;
+export interface MultiStepFormReviewSection {
+    /** Step id the "Edit" link jumps to. */
+    step: string;
+    /** Rows: label → value. */
+    items: {
+        label: string;
+        value: React.ReactNode;
+    }[];
+    /** Heading. Default: the step title. */
+    title?: string;
+}
+export interface MultiStepFormReviewProps extends React.HTMLAttributes<HTMLDivElement> {
+    sections: MultiStepFormReviewSection[];
+}
+/** A summary of earlier steps with "Edit" links back to each one. */
+export declare function MultiStepFormReview({ sections, className, ...props }: MultiStepFormReviewProps): React.JSX.Element;
+export interface MultiStepFormFooterProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Submit button label on the last step. */
+    submitLabel?: string;
+    /** Extra content at the start (a "Cancel" link). */
+    start?: React.ReactNode;
+}
+/** Back · Save draft · Next / Submit. Sticky at the bottom in page presentation. */
+export declare function MultiStepFormFooter({ submitLabel, start, className, ...props }: MultiStepFormFooterProps): React.JSX.Element;

package/dist/business/multi-step-form.js

@@ -0,0 +1,337 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as React from "react";
+import { ArrowLeft, ArrowRight, Check, CloudUpload, Pencil } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { useLabels } from "../lib/labels.js";
+import { useLocale } from "../lib/locale.js";
+import { useLatest } from "../lib/use-controllable-state.js";
+import { focusFirstInvalid } from "../lib/field-context.js";
+import { Button } from "../components/button.js";
+import { Alert } from "../components/alert.js";
+import { Stepper } from "../components/stepper.js";
+export const multiStepFormLabels = {
+    back: "Back",
+    next: "Next",
+    submit: "Submit",
+    submitting: "Submitting…",
+    saveDraft: "Save draft",
+    savingDraft: "Saving…",
+    draftSaved: "Draft saved {time}",
+    draftFailed: "Draft not saved",
+    step: "Step {current} of {total}",
+    stepHeading: "Step {current} of {total}: {title}",
+    optional: "Optional",
+    fixErrors: "Check this step",
+    submitFailed: "Couldn't submit",
+    edit: "Edit {title}",
+    review: "Review",
+    leave: "You have unsaved changes. Leave anyway?",
+};
+const MultiStepFormContext = React.createContext(null);
+function useCtx(part) {
+    const ctx = React.useContext(MultiStepFormContext);
+    if (!ctx)
+        throw new Error(`<${part}> must be used inside <MultiStepForm>.`);
+    return ctx;
+}
+/** State and navigation of the surrounding `MultiStepForm`. */
+export function useMultiStepForm() {
+    const c = useCtx("useMultiStepForm");
+    return {
+        current: c.current.id,
+        index: c.index,
+        total: c.visible.length,
+        steps: c.visible,
+        next: c.next,
+        back: c.back,
+        goTo: c.goTo,
+        saveDraft: c.saveDraft,
+        isFirst: c.isFirst,
+        isLast: c.isLast,
+        status: c.status,
+        submitting: c.submitting,
+    };
+}
+function urlKey(syncUrl) {
+    if (!syncUrl)
+        return null;
+    return typeof syncUrl === "object" ? syncUrl.key : "step";
+}
+function MultiStepFormInner(props, ref) {
+    const { steps, value, defaultValue, onValueChange, context, linear = true, onComplete, onSaveDraft, autosave, presentation = "page", orientation = "horizontal", syncUrl, confirmLeave, labels, className, children, ...formProps } = props;
+    const t = useLabels("multiStepForm", multiStepFormLabels, labels);
+    const visible = React.useMemo(() => steps.filter((s) => !s.when || s.when(context)), [steps, context]);
+    const key = urlKey(syncUrl);
+    const [inner, setInner] = React.useState(() => defaultValue ?? steps[0]?.id ?? "");
+    // Resume from the URL after mount (keeps server and client markup identical).
+    React.useEffect(() => {
+        if (!key)
+            return;
+        const fromUrl = new URLSearchParams(window.location.search).get(key);
+        if (fromUrl && steps.some((s) => s.id === fromUrl)) {
+            if (value === undefined)
+                setInner(fromUrl);
+            onValueChange?.(fromUrl);
+        }
+    }, [key]); // eslint-disable-line react-hooks/exhaustive-deps
+    const currentId = value ?? inner;
+    const index = Math.max(0, visible.findIndex((s) => s.id === currentId));
+    const current = visible[index] ?? visible[0];
+    const [completed, setCompleted] = React.useState(() => new Set());
+    const [errors, setErrors] = React.useState({});
+    const [validating, setValidating] = React.useState(false);
+    const [submitting, setSubmitting] = React.useState(false);
+    const [submitError, setSubmitError] = React.useState(null);
+    const [draft, setDraft] = React.useState({ state: "idle" });
+    const [done, setDone] = React.useState(false);
+    const headingRef = React.useRef(null);
+    const formRef = React.useRef(null);
+    const moved = React.useRef(false);
+    const setStep = React.useCallback((id) => {
+        moved.current = true;
+        if (value === undefined)
+            setInner(id);
+        onValueChange?.(id);
+        setSubmitError(null);
+        if (key && typeof window !== "undefined") {
+            const url = new URL(window.location.href);
+            url.searchParams.set(key, id);
+            window.history.replaceState(window.history.state, "", url);
+        }
+    }, [value, onValueChange, key]);
+    // Focus the step heading after a step change (announced as "Step 3 of 6: Contract").
+    React.useEffect(() => {
+        if (!moved.current)
+            return;
+        moved.current = false;
+        headingRef.current?.focus({ preventScroll: false });
+    }, [current?.id]);
+    const runValidate = async (step) => {
+        if (!step.validate)
+            return true;
+        setValidating(true);
+        try {
+            const r = await step.validate();
+            setErrors((e) => ({ ...e, [step.id]: r === true ? undefined : r }));
+            if (r !== true) {
+                requestAnimationFrame(() => {
+                    const panel = formRef.current?.querySelector(`[data-step-panel="${step.id}"]`);
+                    if (!focusFirstInvalid(panel))
+                        panel?.querySelector("[data-msf-error]")?.focus();
+                });
+            }
+            return r === true;
+        }
+        finally {
+            setValidating(false);
+        }
+    };
+    const isLast = index === visible.length - 1;
+    const next = async () => {
+        if (submitting || validating)
+            return;
+        const ok = await runValidate(current);
+        if (!ok)
+            return;
+        setCompleted((s) => new Set(s).add(current.id));
+        if (!isLast) {
+            setStep(visible[index + 1].id);
+            return;
+        }
+        setSubmitting(true);
+        setSubmitError(null);
+        try {
+            await onComplete();
+            setDone(true);
+        }
+        catch (e) {
+            setSubmitError(e instanceof Error ? e.message : String(e));
+        }
+        finally {
+            setSubmitting(false);
+        }
+    };
+    const back = () => {
+        if (index > 0 && !submitting)
+            setStep(visible[index - 1].id);
+    };
+    const canGoTo = (id) => {
+        if (submitting)
+            return false;
+        const target = visible.findIndex((s) => s.id === id);
+        if (target < 0)
+            return false;
+        if (!linear || target <= index)
+            return true;
+        // Linear: every step before the target must be complete.
+        return visible.slice(0, target).every((s) => completed.has(s.id) && !errors[s.id]);
+    };
+    const goTo = (id) => {
+        if (canGoTo(id))
+            setStep(id);
+    };
+    const saveRef = useLatest(onSaveDraft);
+    const saveDraft = React.useCallback(async () => {
+        if (!saveRef.current)
+            return;
+        setDraft((d) => ({ ...d, state: "saving" }));
+        try {
+            await saveRef.current();
+            setDraft({ state: "saved", at: Date.now() });
+        }
+        catch {
+            setDraft({ state: "error" });
+        }
+    }, [saveRef]);
+    React.useEffect(() => {
+        if (!autosave || !onSaveDraft || done)
+            return;
+        const id = setInterval(() => void saveDraft(), Math.max(2000, autosave.intervalMs));
+        return () => clearInterval(id);
+    }, [autosave?.intervalMs, onSaveDraft, saveDraft, done]); // eslint-disable-line react-hooks/exhaustive-deps
+    React.useEffect(() => {
+        if (!confirmLeave || done)
+            return;
+        const onBeforeUnload = (e) => {
+            e.preventDefault();
+            e.returnValue = t("leave");
+        };
+        window.addEventListener("beforeunload", onBeforeUnload);
+        return () => window.removeEventListener("beforeunload", onBeforeUnload);
+    }, [confirmLeave, done, t]);
+    const status = {};
+    visible.forEach((s, i) => {
+        status[s.id] = errors[s.id] ? "error" : i === index ? "current" : completed.has(s.id) ? "complete" : "upcoming";
+    });
+    const ctx = {
+        steps: steps,
+        visible: visible,
+        current: current,
+        index,
+        status,
+        errors,
+        isFirst: index === 0,
+        isLast,
+        submitting,
+        validating,
+        submitError,
+        draft,
+        canSaveDraft: !!onSaveDraft,
+        linear,
+        presentation,
+        orientation,
+        next,
+        back,
+        goTo,
+        saveDraft,
+        canGoTo,
+        t,
+        headingRef,
+    };
+    return (_jsx(MultiStepFormContext.Provider, { value: ctx, children: _jsx("form", { ref: (node) => {
+                formRef.current = node;
+                if (typeof ref === "function")
+                    ref(node);
+                else if (ref)
+                    ref.current = node;
+            }, noValidate: true, "data-slot": "multi-step-form", "data-presentation": presentation, "data-orientation": orientation, "aria-busy": submitting || undefined, className: cn("vui-msf flex min-w-0 flex-col gap-6", orientation === "vertical" && "md:grid md:grid-cols-[14rem_minmax(0,1fr)] md:gap-x-10", className), onSubmit: (e) => {
+                e.preventDefault();
+                void next();
+            }, onKeyDown: (e) => {
+                // Enter in a single-line field moves to the next step instead of submitting everything.
+                const el = e.target;
+                if (e.key !== "Enter" || e.shiftKey || e.altKey || e.nativeEvent.isComposing)
+                    return;
+                if (el.tagName === "INPUT" && !["checkbox", "radio", "button", "submit", "file"].includes(el.type)) {
+                    e.preventDefault();
+                    void next();
+                }
+            }, ...formProps, children: children }) }));
+}
+/**
+ * A long form split into steps: per-step validation, conditional steps, draft saving, a review
+ * step and URL resume. Form-library agnostic — each step exposes `validate()`.
+ *
+ * ```tsx
+ * <MultiStepForm steps={steps} onComplete={submit}>
+ *   <MultiStepFormStepper />
+ *   <MultiStepFormStep id="identity">…fields…</MultiStepFormStep>
+ *   <MultiStepFormStep id="review"><MultiStepFormReview>…</MultiStepFormReview></MultiStepFormStep>
+ *   <MultiStepFormFooter />
+ * </MultiStepForm>
+ * ```
+ */
+export const MultiStepForm = React.forwardRef(MultiStepFormInner);
+/** The progress display (kit `Stepper`), wired to the form: completed steps are clickable. */
+export function MultiStepFormStepper({ variant = "numbered", className }) {
+    const c = useCtx("MultiStepFormStepper");
+    const items = c.visible.map((s) => ({
+        id: s.id,
+        title: s.title,
+        description: c.orientation === "vertical" ? s.description : undefined,
+        optional: s.optional,
+        status: c.status[s.id] === "error" ? "error" : undefined,
+        disabled: !c.canGoTo(s.id),
+    }));
+    return (_jsx(Stepper, { "data-slot": "multi-step-form-stepper", value: c.index, steps: items, orientation: c.orientation, variant: variant, loading: c.validating || c.submitting, navigable: (i) => i !== c.index && c.canGoTo(c.visible[i].id), onValueChange: (i) => c.goTo(c.visible[i].id), className: cn(c.orientation === "vertical" && "md:row-span-3 md:sticky md:top-4 md:self-start", className) }));
+}
+/** One step's content. Shows its heading ("Step 2 of 5" + title) and the error summary. */
+export function MultiStepFormStep({ id, hideHeading, keepMounted = true, className, children, ...props }) {
+    const c = useCtx("MultiStepFormStep");
+    const step = c.visible.find((s) => s.id === id);
+    if (!step)
+        return null;
+    const active = c.current.id === id;
+    if (!active && !keepMounted)
+        return null;
+    const position = c.visible.indexOf(step) + 1;
+    const error = c.errors[id];
+    const headingId = `msf-${id}-heading`;
+    return (_jsx("section", { "data-slot": "multi-step-form-step", "data-step-panel": id, hidden: !active, "aria-labelledby": headingId, className: cn("min-w-0", active && "vui-msf-step-in", className), ...props, children: _jsxs("fieldset", { disabled: c.submitting, className: "m-0 min-w-0 border-0 p-0", children: [hideHeading ? (_jsx("h2", { id: headingId, className: "sr-only", tabIndex: -1, ref: active ? c.headingRef : undefined, children: c.t("stepHeading", { current: position, total: c.visible.length, title: step.title }) })) : (_jsxs("header", { className: "mb-5", children: [_jsxs("p", { className: "font-mono text-[11px] tracking-[0.06em] text-fg-subtle uppercase", "aria-hidden": true, children: [c.t("step", { current: position, total: c.visible.length }), step.optional ? ` · ${c.t("optional")}` : ""] }), _jsxs("h2", { id: headingId, tabIndex: -1, ref: active ? c.headingRef : undefined, className: "mt-1 text-[22px] font-semibold tracking-[-0.016em] text-fg outline-none", children: [_jsxs("span", { className: "sr-only", children: [c.t("step", { current: position, total: c.visible.length }), ":"] }), " ", step.title] }), step.description ? _jsx("p", { className: "mt-1 max-w-prose text-sm text-fg-muted", children: step.description }) : null] })), error ? (_jsx(Alert, { tone: "danger", title: c.t("fixErrors"), className: "mb-5", "data-msf-error": "", tabIndex: -1, live: "assertive", children: error })) : null, active && c.isLast && c.submitError ? (_jsx(Alert, { tone: "danger", title: c.t("submitFailed"), className: "mb-5", live: "assertive", children: c.submitError })) : null, children] }) }));
+}
+/** A summary of earlier steps with "Edit" links back to each one. */
+export function MultiStepFormReview({ sections, className, ...props }) {
+    const c = useCtx("MultiStepFormReview");
+    return (_jsx("div", { "data-slot": "multi-step-form-review", className: cn("flex flex-col divide-y divide-line rounded-ui-lg border border-line", className), ...props, children: sections
+            .filter((s) => c.visible.some((v) => v.id === s.step))
+            .map((s) => {
+            const title = s.title ?? c.visible.find((v) => v.id === s.step)?.title ?? s.step;
+            return (_jsxs("section", { className: "px-4 py-3.5", "aria-label": title, children: [_jsxs("div", { className: "mb-2 flex items-center justify-between gap-3", children: [_jsx("h3", { className: "text-[13px] font-semibold text-fg", children: title }), _jsxs(Button, { size: "xs", variant: "ghost", onClick: () => c.goTo(s.step), "aria-label": c.t("edit", { title }), children: [_jsx(Pencil, {}), " ", _jsx("span", { "aria-hidden": true, children: c.t("edit", { title: "" }).trim() })] })] }), _jsx("dl", { className: "grid grid-cols-1 gap-x-6 gap-y-1.5 text-sm sm:grid-cols-[minmax(8rem,12rem)_1fr]", children: s.items.map((it) => (_jsxs("div", { className: "contents", children: [_jsx("dt", { className: "text-fg-muted", children: it.label }), _jsx("dd", { className: "min-w-0 text-fg [overflow-wrap:anywhere]", children: it.value || _jsx("span", { className: "text-fg-subtle", children: "\u2014" }) })] }, it.label))) })] }, s.step));
+        }) }));
+}
+/** Back · Save draft · Next / Submit. Sticky at the bottom in page presentation. */
+export function MultiStepFormFooter({ submitLabel, start, className, ...props }) {
+    const c = useCtx("MultiStepFormFooter");
+    // The opaque backing only appears while the footer is actually stuck over scrolling content;
+    // at rest it sits flush on whatever surface holds the form.
+    const footerRef = React.useRef(null);
+    const [stuck, setStuck] = React.useState(false);
+    React.useEffect(() => {
+        const el = footerRef.current;
+        if (c.presentation !== "page" || !el || typeof IntersectionObserver === "undefined")
+            return;
+        const io = new IntersectionObserver(([e]) => setStuck(!!e && e.intersectionRatio < 1 && e.boundingClientRect.top > 0), {
+            rootMargin: "0px 0px -1px 0px",
+            threshold: [1],
+        });
+        io.observe(el);
+        return () => io.disconnect();
+    }, [c.presentation]);
+    const { format } = useLocale();
+    const [, tick] = React.useReducer((n) => n + 1, 0);
+    React.useEffect(() => {
+        if (c.draft.state !== "saved")
+            return;
+        const id = setInterval(tick, 30_000);
+        return () => clearInterval(id);
+    }, [c.draft.state]);
+    const draftText = c.draft.state === "saving"
+        ? c.t("savingDraft")
+        : c.draft.state === "saved" && c.draft.at
+            ? c.t("draftSaved", { time: format.relative(c.draft.at) })
+            : c.draft.state === "error"
+                ? c.t("draftFailed")
+                : "";
+    return (_jsxs("div", { ref: footerRef, "data-slot": "multi-step-form-footer", "data-stuck": stuck ? "" : undefined, className: cn("vui-msf-footer flex flex-wrap items-center gap-2 border-t border-line pt-4", c.presentation === "page" && "sticky bottom-0 z-10 -mx-1 px-1 pb-1", c.orientation === "vertical" && "md:col-start-2", className), ...props, children: [start, !c.isFirst ? (_jsxs(Button, { variant: "ghost", onClick: c.back, disabled: c.submitting, children: [_jsx(ArrowLeft, { className: "rtl:rotate-180" }), " ", c.t("back")] })) : null, _jsx("span", { className: "flex-1" }), _jsx("span", { className: cn("text-xs text-fg-subtle", c.draft.state === "error" && "text-danger"), "aria-live": "polite", children: draftText }), c.canSaveDraft ? (_jsxs(Button, { variant: "secondary", onClick: () => void c.saveDraft(), loading: c.draft.state === "saving", disabled: c.submitting, children: [_jsx(CloudUpload, {}), " ", c.t("saveDraft")] })) : null, _jsx(Button, { type: "submit", variant: "primary", loading: c.submitting || c.validating, loadingText: c.submitting ? c.t("submitting") : undefined, children: c.isLast ? (_jsxs(_Fragment, { children: [_jsx(Check, {}), " ", submitLabel ?? c.t("submit")] })) : (_jsxs(_Fragment, { children: [c.t("next"), " ", _jsx(ArrowRight, { className: "rtl:rotate-180" })] })) })] }));
+}

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

@@ -0,0 +1,59 @@
+/**
+ * Permission matrix maths — React-free. A value is `resource → action → Scope | boolean`;
+ * missing entries mean "not granted here" (and fall back to `inherited` when given).
+ */
+export type PermissionScope = "none" | "own" | "team" | "all";
+export type PermissionLevel = PermissionScope | boolean;
+export type PermissionValue = Record<string, Record<string, PermissionLevel | undefined>>;
+export interface PermissionDependency {
+    /** "edit" … */
+    action: string;
+    /** … requires "view". */
+    requires: string;
+}
+export interface PermissionChange {
+    resource: string;
+    action: string;
+    from: PermissionLevel | undefined;
+    to: PermissionLevel | undefined;
+}
+export declare const SCOPE_ORDER: PermissionScope[];
+/** 0 none · 1 own · 2 team · 3 all; booleans map to 0 / 3. */
+export declare function scopeRank(v: PermissionLevel | undefined): number;
+export declare function isGranted(v: PermissionLevel | undefined): boolean;
+/** The value in effect: own entry, else the inherited one. */
+export declare function effectiveLevel(value: PermissionValue, inherited: PermissionValue | undefined, resource: string, action: string): PermissionLevel | undefined;
+/** Every changed cell between two values, in resource / action order of `b`, then `a`. */
+export declare function diffPermissions(a: PermissionValue, b: PermissionValue): PermissionChange[];
+declare function setLevel(v: PermissionValue, resource: string, action: string, level: PermissionLevel | undefined): PermissionValue;
+/**
+ * Makes a value consistent with dependencies: a granted action raises what it requires to at
+ * least its scope ("edit: team" → "view: team"); a revoked requirement lowers its dependents.
+ * `changed` (the cell the user just set) decides the direction. Returns the new value and the
+ * cells that were adjusted.
+ */
+export declare function applyDependencies(value: PermissionValue, deps: PermissionDependency[], options?: {
+    changed?: {
+        resource: string;
+        action: string;
+    };
+    scoped?: (action: string) => boolean;
+    resources?: string[];
+}): {
+    value: PermissionValue;
+    adjusted: {
+        resource: string;
+        action: string;
+        reason: PermissionDependency;
+        level: PermissionLevel;
+    }[];
+};
+/** Grants (or revokes) one action on many resources, or many actions on one resource. */
+export declare function setMany(value: PermissionValue, cells: {
+    resource: string;
+    action: string;
+}[], level: (cell: {
+    resource: string;
+    action: string;
+}) => PermissionLevel | undefined): PermissionValue;
+export { setLevel as setPermission };

package/dist/business/permission-core.js

@@ -0,0 +1,99 @@
+/**
+ * Permission matrix maths — React-free. A value is `resource → action → Scope | boolean`;
+ * missing entries mean "not granted here" (and fall back to `inherited` when given).
+ */
+export const SCOPE_ORDER = ["none", "own", "team", "all"];
+/** 0 none · 1 own · 2 team · 3 all; booleans map to 0 / 3. */
+export function scopeRank(v) {
+    if (v === undefined || v === false || v === "none")
+        return 0;
+    if (v === true)
+        return 3;
+    return SCOPE_ORDER.indexOf(v);
+}
+export function isGranted(v) {
+    return scopeRank(v) > 0;
+}
+/** The value in effect: own entry, else the inherited one. */
+export function effectiveLevel(value, inherited, resource, action) {
+    const own = value[resource]?.[action];
+    return own !== undefined ? own : inherited?.[resource]?.[action];
+}
+/** Every changed cell between two values, in resource / action order of `b`, then `a`. */
+export function diffPermissions(a, b) {
+    const out = [];
+    const resources = [...new Set([...Object.keys(b), ...Object.keys(a)])];
+    for (const r of resources) {
+        const actions = [...new Set([...Object.keys(b[r] ?? {}), ...Object.keys(a[r] ?? {})])];
+        for (const act of actions) {
+            const from = a[r]?.[act];
+            const to = b[r]?.[act];
+            const norm = (v) => (v === undefined || v === false || v === "none" ? undefined : v);
+            if (norm(from) !== norm(to))
+                out.push({ resource: r, action: act, from, to });
+        }
+    }
+    return out;
+}
+function setLevel(v, resource, action, level) {
+    const row = { ...(v[resource] ?? {}) };
+    if (level === undefined)
+        delete row[action];
+    else
+        row[action] = level;
+    return { ...v, [resource]: row };
+}
+/** Same kind of level (boolean or scope) at a given rank. */
+function atRank(sample, rank, scoped) {
+    if (!scoped && (typeof sample === "boolean" || sample === undefined))
+        return rank > 0;
+    return SCOPE_ORDER[rank];
+}
+/**
+ * Makes a value consistent with dependencies: a granted action raises what it requires to at
+ * least its scope ("edit: team" → "view: team"); a revoked requirement lowers its dependents.
+ * `changed` (the cell the user just set) decides the direction. Returns the new value and the
+ * cells that were adjusted.
+ */
+export function applyDependencies(value, deps, options = {}) {
+    let v = value;
+    const adjusted = [];
+    const scoped = options.scoped ?? (() => false);
+    const resources = options.resources ?? Object.keys(value);
+    for (let pass = 0; pass < 4; pass++) {
+        let touched = false;
+        for (const r of resources) {
+            for (const d of deps) {
+                const dep = v[r]?.[d.action];
+                const req = v[r]?.[d.requires];
+                const depRank = scopeRank(dep);
+                const reqRank = scopeRank(req);
+                if (depRank <= reqRank)
+                    continue;
+                const loweringRequirement = options.changed?.resource === r && options.changed.action === d.requires;
+                if (loweringRequirement) {
+                    const level = atRank(dep, reqRank, scoped(d.action));
+                    v = setLevel(v, r, d.action, reqRank === 0 ? undefined : level);
+                    adjusted.push({ resource: r, action: d.action, reason: d, level });
+                }
+                else {
+                    const level = atRank(req, depRank, scoped(d.requires));
+                    v = setLevel(v, r, d.requires, level);
+                    adjusted.push({ resource: r, action: d.requires, reason: d, level });
+                }
+                touched = true;
+            }
+        }
+        if (!touched)
+            break;
+    }
+    return { value: v, adjusted };
+}
+/** Grants (or revokes) one action on many resources, or many actions on one resource. */
+export function setMany(value, cells, level) {
+    let v = value;
+    for (const c of cells)
+        v = setLevel(v, c.resource, c.action, level(c));
+    return v;
+}
+export { setLevel as setPermission };