@vamos-ui/react 0.0.0-stage → 0.2.0

package/dist/business/approval-flow.js

@@ -0,0 +1,221 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as React from "react";
+import { Check, X, RotateCcw, Minus, Clock, Forward, CornerDownRight, GitBranch } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { useLabels } from "../lib/labels.js";
+import { useLocale } from "../lib/locale.js";
+import { Avatar } from "../components/avatar.js";
+import { Badge } from "../components/badge.js";
+import { Button } from "../components/button.js";
+import { Alert } from "../components/alert.js";
+import { Textarea, Field } from "../components/input.js";
+import { Select } from "../components/select.js";
+import { Dialog, DialogBody, DialogContent, DialogFooter, DialogHeader } from "../components/dialog.js";
+export const approvalFlowLabels = {
+    label: "Approval flow",
+    waiting: "Waiting",
+    active: "In review",
+    approved: "Approved",
+    rejected: "Rejected",
+    changes_requested: "Changes requested",
+    skipped: "Skipped",
+    withdrawn: "Withdrawn",
+    modeAll: "{count, plural, one {# approver} other {All of # approvers}}",
+    modeAny: "{count, plural, one {# approver} other {Any one of # approvers}}",
+    parallel: "In parallel",
+    condition: "Only when {condition}",
+    due: "Due {relative}",
+    overdue: "Overdue · due {relative}",
+    pending: "Pending",
+    decidedApproved: "approved",
+    decidedRejected: "rejected",
+    decidedChanges: "requested changes",
+    decisionAt: "{name} {decision} on {date}",
+    delegatedFrom: "on behalf of {name}",
+    delegated: "Delegated",
+    submittedBy: "Submitted by {name}",
+    summary: "{done} of {total} approved",
+    summaryCurrent: "Now: {stage}",
+    // actions
+    approve: "Approve",
+    reject: "Reject",
+    requestChanges: "Request changes",
+    delegate: "Delegate",
+    note: "Note",
+    noteOptional: "Add a note for the requester (optional).",
+    noteRequired: "Tell the requester why.",
+    noteMissing: "A note is required.",
+    delegateTo: "Delegate to",
+    delegateHint: "They decide for you on this request.",
+    confirmApprove: "Approve request",
+    confirmReject: "Reject request",
+    confirmChanges: "Send back for changes",
+    confirmDelegate: "Delegate request",
+    cancel: "Cancel",
+    doneApprove: "Approved",
+    doneReject: "Rejected",
+    doneChanges: "Sent back for changes",
+    doneDelegate: "Delegated to {name}",
+    failed: "That didn't go through",
+    cantAct: "You can't act on this request.",
+};
+const tone = {
+    waiting: "outline",
+    active: "accent",
+    approved: "success",
+    rejected: "danger",
+    changes_requested: "warning",
+    skipped: "neutral",
+    withdrawn: "neutral",
+};
+function StageIndicator({ status, size = "md" }) {
+    const icon = status === "approved" ? _jsx(Check, { strokeWidth: 3 }) : status === "rejected" ? _jsx(X, { strokeWidth: 3 }) : status === "changes_requested" ? _jsx(RotateCcw, { strokeWidth: 2.5 }) : status === "skipped" || status === "withdrawn" ? _jsx(Minus, { strokeWidth: 2.5 }) : null;
+    return (_jsxs("span", { "aria-hidden": true, "data-slot": "approval-indicator", "data-status": status, className: cn("vui-approval-dot relative inline-flex shrink-0 items-center justify-center rounded-full", size === "sm" ? "size-2.5" : "size-7 [&_svg]:size-3.5", status === "approved" && "tone-success bg-(--tone) text-scene", status === "rejected" && "tone-danger bg-(--tone) text-scene", status === "changes_requested" && "tone-warning bg-(--tone) text-scene", status === "active" && "bg-surface shadow-[0_0_0_1.5px_var(--accent-ink),0_0_0_5px_var(--accent-soft)]", status === "waiting" && "bg-surface shadow-[inset_0_0_0_1.5px_var(--track)]", (status === "skipped" || status === "withdrawn") && "border-[1.5px] border-dashed border-field-border bg-surface text-fg-subtle", size === "sm" && status === "waiting" && "bg-track shadow-none", size === "sm" && status === "active" && "bg-accent-ink shadow-none"), children: [size === "md" ? icon : null, size === "md" && status === "active" ? _jsx("span", { className: "size-2 rounded-full bg-accent-ink" }) : null] }));
+}
+function decisionWord(t, v) {
+    return v === "approved" ? t("decidedApproved") : v === "rejected" ? t("decidedRejected") : t("decidedChanges");
+}
+function groupStages(stages) {
+    const out = [];
+    for (const s of stages) {
+        const last = out[out.length - 1];
+        if (s.parallelGroup && last?.parallel && last.key === s.parallelGroup)
+            last.stages.push(s);
+        else
+            out.push({ key: s.parallelGroup ?? s.id, parallel: !!s.parallelGroup, stages: [s] });
+    }
+    return out;
+}
+function groupStatus(g) {
+    const st = g.stages.map((s) => s.status);
+    if (st.includes("rejected"))
+        return "rejected";
+    if (st.includes("changes_requested"))
+        return "changes_requested";
+    if (st.includes("active"))
+        return "active";
+    if (st.every((s) => s === "approved" || s === "skipped"))
+        return st.every((s) => s === "skipped") ? "skipped" : "approved";
+    if (st.every((s) => s === "withdrawn"))
+        return "withdrawn";
+    return "waiting";
+}
+/**
+ * A multi-stage approval: sequential and parallel stages ("all of" / "any of"), approvers with
+ * decisions, timestamps and notes, conditions, SLA and delegation. Renders a flow the server
+ * defines; acting on it is `<ApprovalActions>`.
+ *
+ * ```tsx
+ * <ApprovalFlow requester={{ name: "Deniz Aydın", at: "2026-11-03T09:12:00Z" }} stages={stages} />
+ * ```
+ */
+export const ApprovalFlow = React.forwardRef(function ApprovalFlow({ stages, requester, orientation = "vertical", variant = "full", now, labels, className, ...props }, ref) {
+    const t = useLabels("approvalFlow", approvalFlowLabels, labels);
+    if (variant === "compact")
+        return _jsx(ApprovalSummary, { stages: stages, labels: labels, className: className });
+    const groups = groupStages(stages);
+    const horizontal = orientation === "horizontal";
+    return (_jsxs("ol", { ref: ref, "aria-label": props["aria-label"] ?? t("label"), "data-slot": "approval-flow", "data-orientation": orientation, className: cn("vui-approval m-0 list-none p-0", horizontal ? "flex gap-0 overflow-x-auto pb-1" : "flex flex-col", className), ...props, children: [requester ? _jsx(RequesterNode, { requester: requester, t: t, horizontal: horizontal }) : null, groups.map((g, gi) => {
+                const last = gi === groups.length - 1;
+                const status = groupStatus(g);
+                if (!g.parallel) {
+                    return (_jsx(ApprovalStage, { stage: g.stages[0], last: last, horizontal: horizontal, now: now, t: t }, g.key));
+                }
+                return (_jsxs("li", { "data-slot": "approval-parallel", "data-status": status, className: cn("vui-approval-node relative", horizontal ? "min-w-[22rem] flex-1 pe-6" : "grid grid-cols-[1.75rem_minmax(0,1fr)] gap-x-4 pb-7 last:pb-0"), children: [_jsx(Rail, { status: status, last: last, horizontal: horizontal, icon: _jsx(GitBranch, { className: "size-3.5" }) }), _jsxs("div", { className: "min-w-0", children: [_jsx("p", { className: "mb-2.5 flex items-center gap-2 pt-1 font-mono text-[11px] tracking-[0.06em] text-fg-subtle uppercase", children: t("parallel") }), _jsx("ol", { className: "m-0 grid list-none gap-3 p-0 sm:grid-cols-2", "aria-label": t("parallel"), children: g.stages.map((s) => (_jsx("li", { className: "min-w-0 rounded-ui-lg border border-line bg-surface-2/60 p-3.5", "data-status": s.status, children: _jsx(StageBody, { stage: s, now: now, t: t, nested: true }) }, s.id))) })] })] }, g.key));
+            })] }));
+});
+function Rail({ status, last, horizontal, icon }) {
+    const done = status === "approved" || status === "skipped";
+    return (_jsxs("div", { "aria-hidden": true, className: cn("relative flex", horizontal ? "mb-3 items-center" : "flex-col items-center"), children: [icon && status !== "approved" && status !== "rejected" && status !== "changes_requested" ? (_jsx("span", { className: "inline-flex size-7 items-center justify-center rounded-full bg-surface text-fg-muted shadow-[inset_0_0_0_1.5px_var(--track)]", children: icon })) : (_jsx(StageIndicator, { status: status })), !last ? (_jsx("span", { className: cn("vui-approval-line", horizontal ? "mx-2 h-px flex-1" : "mt-1.5 w-px flex-1", done ? "bg-[color-mix(in_srgb,var(--success)_55%,var(--line))]" : "bg-line") })) : null] }));
+}
+function RequesterNode({ requester, t, horizontal }) {
+    const { format } = useLocale();
+    return (_jsxs("li", { className: cn("vui-approval-node relative", horizontal ? "min-w-[14rem] flex-1 pe-6" : "grid grid-cols-[1.75rem_minmax(0,1fr)] gap-x-4 pb-7"), children: [_jsxs("div", { "aria-hidden": true, className: cn("relative flex", horizontal ? "mb-3 items-center" : "flex-col items-center"), children: [_jsx(Avatar, { name: requester.name, src: requester.avatarUrl, size: "sm", className: "size-7" }), _jsx("span", { className: cn(horizontal ? "mx-2 h-px flex-1" : "mt-1.5 w-px flex-1", "bg-[color-mix(in_srgb,var(--success)_55%,var(--line))]") })] }), _jsxs("div", { className: "min-w-0 pt-1", children: [_jsx("p", { className: "text-sm font-medium text-fg", children: t("submittedBy", { name: requester.name }) }), _jsx("p", { className: "mt-0.5 text-xs text-fg-subtle tabular", children: _jsx("time", { dateTime: requester.at, children: format.dateTime(requester.at, { dateStyle: "medium", timeStyle: "short" }) }) }), requester.note ? _jsx("blockquote", { className: "mt-2 border-s-2 border-line ps-3 text-sm text-fg-muted", children: requester.note }) : null] })] }));
+}
+/** One stage node (rail + body). Rendered by `ApprovalFlow`; exported for custom layouts. */
+export function ApprovalStage({ stage, last = false, horizontal = false, now, t }) {
+    return (_jsxs("li", { "data-slot": "approval-stage", "data-status": stage.status, className: cn("vui-approval-node relative", horizontal ? "min-w-[16rem] flex-1 pe-6" : "grid grid-cols-[1.75rem_minmax(0,1fr)] gap-x-4 pb-7 last:pb-0"), children: [_jsx(Rail, { status: stage.status, last: last, horizontal: horizontal }), _jsx("div", { className: "min-w-0 pt-0.5", children: _jsx(StageBody, { stage: stage, now: now, t: t }) })] }));
+}
+function StageBody({ stage, now, t, nested }) {
+    const { format } = useLocale();
+    const ref = now ?? Date.now();
+    const count = stage.approvers.length;
+    const due = stage.dueAt ? new Date(stage.dueAt).getTime() : null;
+    const overdue = due !== null && stage.status === "active" && due < new Date(ref).getTime();
+    const muted = stage.status === "skipped" || stage.status === "withdrawn" || stage.status === "waiting";
+    return (_jsxs("div", { className: cn(muted && "text-fg-muted"), children: [_jsxs("div", { className: "flex flex-wrap items-center gap-x-2 gap-y-1", children: [nested ? _jsx(StageIndicator, { status: stage.status, size: "sm" }) : null, _jsx("h3", { className: cn("text-sm font-semibold", muted ? "text-fg-muted" : "text-fg"), children: stage.title }), _jsx(Badge, { tone: tone[stage.status], size: "sm", children: t(stage.status) })] }), _jsxs("p", { className: "mt-1 flex flex-wrap items-center gap-x-2.5 gap-y-1 text-xs text-fg-muted", children: [_jsx("span", { children: t(stage.mode === "all" ? "modeAll" : "modeAny", { count }) }), stage.condition ? (_jsxs("span", { className: "inline-flex items-center gap-1 rounded-ui-sm bg-selected px-1.5 py-0.5 font-mono text-[11px] text-fg-muted", children: [_jsx(CornerDownRight, { "aria-hidden": true, className: "size-3" }), t("condition", { condition: stage.condition })] })) : null, due !== null && (stage.status === "active" || stage.status === "waiting") ? (_jsxs("span", { className: cn("inline-flex items-center gap-1 tabular", overdue && "tone-warning rounded-ui-sm px-1.5 py-0.5 tone-soft font-medium"), children: [_jsx(Clock, { "aria-hidden": true, className: "size-3" }), t(overdue ? "overdue" : "due", { relative: format.relative(stage.dueAt, { now: ref }) })] })) : null] }), count ? (_jsx("ul", { className: "m-0 mt-2.5 flex list-none flex-col gap-2 p-0", "data-slot": "approval-approvers", children: stage.approvers.map((a) => (_jsx(ApproverRow, { approver: a, t: t, stageActive: stage.status === "active" }, a.id))) })) : null] }));
+}
+function ApproverRow({ approver: a, t, stageActive }) {
+    const { format } = useLocale();
+    const d = a.decision;
+    const decisionTone = d ? (d.value === "approved" ? "text-success" : d.value === "rejected" ? "text-danger" : "text-warning") : "text-fg-subtle";
+    return (_jsxs("li", { className: "flex min-w-0 gap-2.5", "data-slot": "approval-approver", "data-decision": d?.value, children: [_jsx(Avatar, { name: a.name, src: a.avatarUrl, size: "sm" }), _jsxs("div", { className: "min-w-0 flex-1 text-[13px] leading-snug", children: [_jsxs("p", { className: "flex flex-wrap items-baseline gap-x-1.5", children: [_jsx("span", { className: "font-medium text-fg", children: a.name }), a.role ? _jsx("span", { className: "text-xs text-fg-subtle", children: a.role }) : null, d?.delegatedFrom ? (_jsxs(Badge, { tone: "info", size: "sm", children: [_jsx(Forward, {}), " ", t("delegated")] })) : null] }), d ? (_jsxs("p", { className: "mt-0.5 text-xs text-fg-muted", children: [_jsx("span", { className: cn("font-medium", decisionTone), children: decisionWord(t, d.value) }), " ", _jsx("time", { dateTime: d.at, className: "tabular", children: format.dateTime(d.at, { day: "numeric", month: "short", hour: "2-digit", minute: "2-digit" }) }), d.delegatedFrom ? _jsxs(_Fragment, { children: [" \u00B7 ", t("delegatedFrom", { name: d.delegatedFrom.name })] }) : null] })) : (_jsx("p", { className: "mt-0.5 text-xs text-fg-subtle", children: stageActive ? t("pending") : "—" })), d?.note ? (_jsx("blockquote", { className: "mt-1.5 rounded-ui-sm border-s-2 border-(--q) bg-surface-2 px-2.5 py-1.5 text-[13px] text-fg [--q:var(--line)] data-[v=rejected]:[--q:var(--danger)] data-[v=changes_requested]:[--q:var(--warning)]", "data-v": d.value, children: d.note })) : null] })] }));
+}
+/** Inline status for table rows: one dot per stage + "2 of 3 approved". */
+export const ApprovalSummary = React.forwardRef(function ApprovalSummary({ stages, showCurrent = true, labels, className, ...props }, ref) {
+    const t = useLabels("approvalFlow", approvalFlowLabels, labels);
+    const counted = stages.filter((s) => s.status !== "skipped");
+    const done = counted.filter((s) => s.status === "approved").length;
+    const final = stages.find((s) => s.status === "rejected" || s.status === "changes_requested");
+    const current = stages.find((s) => s.status === "active");
+    return (_jsxs("span", { ref: ref, "data-slot": "approval-summary", className: cn("inline-flex min-w-0 items-center gap-2 text-xs", className), ...props, children: [_jsx("span", { "aria-hidden": true, className: "inline-flex items-center gap-1", children: stages.map((s) => (_jsx(StageIndicator, { status: s.status, size: "sm" }, s.id))) }), _jsxs("span", { className: "truncate text-fg-muted tabular", children: [final ? _jsx("span", { className: final.status === "rejected" ? "text-danger" : "text-warning", children: t(final.status) }) : t("summary", { done, total: counted.length }), showCurrent && current && !final ? _jsxs("span", { className: "text-fg-subtle", children: [" \u00B7 ", t("summaryCurrent", { stage: current.title })] }) : null] })] }));
+});
+/** Approve · Request changes · Reject · Delegate, each confirmed in a dialog with a note. Results are announced. */
+export function ApprovalActions({ canAct, onApprove, onReject, onRequestChanges, onDelegate, delegates, requireNoteOn = ["reject", "changes"], cantActReason, size = "md", labels, className, ...props }) {
+    const t = useLabels("approvalFlow", approvalFlowLabels, labels);
+    const [open, setOpen] = React.useState(null);
+    const [note, setNote] = React.useState("");
+    const [to, setTo] = React.useState(null);
+    const [busy, setBusy] = React.useState(false);
+    const [error, setError] = React.useState(null);
+    const [touched, setTouched] = React.useState(false);
+    const [announce, setAnnounce] = React.useState("");
+    if (!canAct) {
+        return (_jsx("p", { "data-slot": "approval-actions", "data-readonly": "", className: cn("text-sm text-fg-subtle", className), children: cantActReason ?? t("cantAct") }));
+    }
+    const needsNote = open === "approve" ? requireNoteOn.includes("approve") : open === "reject" ? requireNoteOn.includes("reject") : open === "changes" ? requireNoteOn.includes("changes") : false;
+    const start = (k) => {
+        setOpen(k);
+        setNote("");
+        setTo(null);
+        setError(null);
+        setTouched(false);
+    };
+    const confirm = async () => {
+        setTouched(true);
+        if (needsNote && !note.trim())
+            return;
+        if (open === "delegate" && !to)
+            return;
+        setBusy(true);
+        setError(null);
+        try {
+            const n = note.trim() || undefined;
+            if (open === "approve")
+                await onApprove(n);
+            else if (open === "reject")
+                await onReject(n ?? "");
+            else if (open === "changes")
+                await onRequestChanges?.(n ?? "");
+            else if (open === "delegate") {
+                const d = delegates?.find((x) => x.id === to);
+                if (d)
+                    await onDelegate?.(d, n);
+            }
+            const d = delegates?.find((x) => x.id === to);
+            setAnnounce(open === "approve" ? t("doneApprove") : open === "reject" ? t("doneReject") : open === "changes" ? t("doneChanges") : t("doneDelegate", { name: d?.name ?? "" }));
+            setOpen(null);
+        }
+        catch (e) {
+            setError(e instanceof Error ? e.message : String(e));
+        }
+        finally {
+            setBusy(false);
+        }
+    };
+    const title = open === "approve" ? t("confirmApprove") : open === "reject" ? t("confirmReject") : open === "changes" ? t("confirmChanges") : t("confirmDelegate");
+    const btn = size === "sm" ? "sm" : "md";
+    const noteError = touched && needsNote && !note.trim() ? t("noteMissing") : undefined;
+    return (_jsxs("div", { "data-slot": "approval-actions", className: cn("flex flex-wrap items-center gap-2", className), ...props, children: [_jsxs(Button, { variant: "primary", size: btn, onClick: () => start("approve"), children: [_jsx(Check, {}), " ", t("approve")] }), onRequestChanges ? (_jsxs(Button, { variant: "secondary", size: btn, onClick: () => start("changes"), children: [_jsx(RotateCcw, {}), " ", t("requestChanges")] })) : null, _jsxs(Button, { variant: "danger-ghost", size: btn, onClick: () => start("reject"), children: [_jsx(X, {}), " ", t("reject")] }), onDelegate && delegates?.length ? (_jsxs(Button, { variant: "ghost", size: btn, onClick: () => start("delegate"), children: [_jsx(Forward, {}), " ", t("delegate")] })) : null, _jsx("span", { className: "sr-only", "aria-live": "polite", "aria-atomic": true, children: announce }), _jsx(Dialog, { open: open !== null, onOpenChange: (o) => !o && !busy && setOpen(null), children: _jsxs(DialogContent, { size: "sm", dismissible: !busy, children: [_jsx(DialogHeader, { title: title }), _jsxs(DialogBody, { className: "flex flex-col gap-4", children: [error ? (_jsx(Alert, { tone: "danger", title: t("failed"), live: "assertive", children: error })) : null, open === "delegate" ? (_jsx(Field, { label: t("delegateTo"), hint: t("delegateHint"), required: true, error: touched && !to ? t("delegateTo") : undefined, children: _jsx(Select, { value: to, onValueChange: setTo, items: (delegates ?? []).map((d) => ({ value: d.id, label: d.name })) }) })) : null, _jsx(Field, { label: t("note"), hint: needsNote ? t("noteRequired") : t("noteOptional"), required: needsNote, error: noteError, children: _jsx(Textarea, { value: note, onChange: (e) => setNote(e.target.value), rows: 3, "data-autofocus": open !== "delegate" ? "" : undefined }) })] }), _jsxs(DialogFooter, { children: [_jsx(Button, { variant: "ghost", onClick: () => setOpen(null), disabled: busy, children: t("cancel") }), _jsx(Button, { variant: open === "reject" ? "danger" : "primary", onClick: () => void confirm(), loading: busy, children: title })] })] }) })] }));
+}

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

@@ -0,0 +1,55 @@
+/**
+ * Export helpers — React-free. CSV goes through the kit's CSV writer (RFC 4180 quoting, BOM,
+ * locale delimiter, formula-injection guard). XLSX loads `write-excel-file` only when used.
+ */
+import { type CsvCell } from "../data-table/csv.js";
+export type ExportFormat = "csv" | "xlsx" | "json";
+export interface ExportColumn {
+    id: string;
+    label: string;
+    /** Personal data (KVKK / GDPR): flagged in the dialog, can be masked, can require a reason. */
+    personalData?: boolean;
+    /** Masked unless the user turns masking off. */
+    maskByDefault?: boolean;
+    /** Ticked when the dialog opens. Default `true`. */
+    defaultSelected?: boolean;
+    /** Cell value. Default `row[id]`. */
+    accessor?: (row: Record<string, unknown>) => unknown;
+    /** `"number"` cells stay numeric in CSV / XLSX. */
+    type?: "text" | "number" | "date" | "boolean";
+}
+export interface CsvExportOptions {
+    /** Default: from the locale (`;` where the decimal separator is a comma). */
+    delimiter?: "," | ";" | "\t";
+    /** UTF-8 byte order mark so Excel reads accents. Default `true`. */
+    bom?: boolean;
+    /** `"locale"`: decimal comma in tr-TR. `"."`: always a point. Default `"locale"`. */
+    decimal?: "locale" | ".";
+}
+export interface ExportToBlobOptions {
+    rows: Record<string, unknown>[];
+    columns: ExportColumn[];
+    format: ExportFormat;
+    /** Column ids written masked. */
+    masked?: string[];
+    locale?: string;
+    csv?: CsvExportOptions;
+    /** XLSX sheet name. Default "Export". */
+    sheetName?: string;
+}
+/** "ayse.yilmaz@northwind.com" → "a••••@northwind.com"; "+90 532 111 22 33" → "••••••••33". */
+export declare function maskValue(value: unknown): string;
+/** Two-dimensional data with a header row — what CSV and XLSX writers take. */
+export declare function toExportMatrix(rows: Record<string, unknown>[], columns: ExportColumn[], masked?: string[]): CsvCell[][];
+/**
+ * Rows → a file Blob in the chosen format.
+ *
+ * ```ts
+ * const blob = await exportToBlob({ rows, columns, format: "csv", locale: "tr-TR" }); // ; + decimal comma + BOM
+ * ```
+ */
+export declare function exportToBlob({ rows, columns, format, masked, locale, csv, sheetName }: ExportToBlobOptions): Promise<Blob>;
+/** A dated file name: `exportFilename("contacts", "csv", "2026-11-10")` → "contacts-2026-11-10.csv". */
+export declare function exportFilename(base: string, format: ExportFormat, date?: string): string;
+/** Saves a Blob as a file in the browser. */
+export declare function downloadBlob(blob: Blob, filename: string): void;

package/dist/business/export-core.js

@@ -0,0 +1,101 @@
+/**
+ * Export helpers — React-free. CSV goes through the kit's CSV writer (RFC 4180 quoting, BOM,
+ * locale delimiter, formula-injection guard). XLSX loads `write-excel-file` only when used.
+ */
+import { csvDelimiter, toCsv } from "../data-table/csv.js";
+/** "ayse.yilmaz@northwind.com" → "a••••@northwind.com"; "+90 532 111 22 33" → "••••••••33". */
+export function maskValue(value) {
+    if (value == null || value === "")
+        return "";
+    const s = String(value);
+    const at = s.indexOf("@");
+    if (at > 0)
+        return `${s[0]}••••${s.slice(at)}`;
+    if (s.length <= 2)
+        return "••";
+    return `${"•".repeat(Math.min(8, s.length - 2))}${s.slice(-2)}`;
+}
+function cellOf(col, row, masked) {
+    const raw = col.accessor ? col.accessor(row) : row[col.id];
+    if (masked.has(col.id))
+        return maskValue(raw);
+    if (raw == null)
+        return null;
+    if (typeof raw === "number" || typeof raw === "boolean" || typeof raw === "string" || raw instanceof Date)
+        return raw;
+    return String(raw);
+}
+/** Two-dimensional data with a header row — what CSV and XLSX writers take. */
+export function toExportMatrix(rows, columns, masked = []) {
+    const m = new Set(masked);
+    return [columns.map((c) => c.label), ...rows.map((r) => columns.map((c) => cellOf(c, r, m)))];
+}
+const MIME = {
+    csv: "text/csv;charset=utf-8",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    json: "application/json",
+};
+/**
+ * Rows → a file Blob in the chosen format.
+ *
+ * ```ts
+ * const blob = await exportToBlob({ rows, columns, format: "csv", locale: "tr-TR" }); // ; + decimal comma + BOM
+ * ```
+ */
+export async function exportToBlob({ rows, columns, format, masked = [], locale = "en-US", csv, sheetName = "Export" }) {
+    const matrix = toExportMatrix(rows, columns, masked);
+    if (format === "csv") {
+        const text = toCsv(matrix, {
+            locale,
+            delimiter: csv?.delimiter ?? csvDelimiter(locale),
+            bom: csv?.bom ?? true,
+            localizeNumbers: (csv?.decimal ?? "locale") === "locale",
+        });
+        return new Blob([text], { type: MIME.csv });
+    }
+    if (format === "json") {
+        const m = new Set(masked);
+        const data = rows.map((r) => Object.fromEntries(columns.map((c) => [c.id, cellOf(c, r, m) ?? null])));
+        return new Blob([JSON.stringify(data, null, 2)], { type: MIME.json });
+    }
+    const { default: writeXlsxFile } = await import("write-excel-file/browser");
+    const sheet = matrix.map((r, i) => r.map((v) => {
+        if (v == null || v === "")
+            return null;
+        if (i === 0)
+            return { value: String(v), fontWeight: "bold" };
+        if (typeof v === "number")
+            return { value: v, type: Number };
+        if (typeof v === "boolean")
+            return { value: v, type: Boolean };
+        if (v instanceof Date)
+            return { value: v, type: Date, format: "yyyy-mm-dd" };
+        return { value: String(v), type: String };
+    }));
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return writeXlsxFile(sheet, { sheet: sheetName.slice(0, 31) }).toBlob();
+}
+/** A dated file name: `exportFilename("contacts", "csv", "2026-11-10")` → "contacts-2026-11-10.csv". */
+export function exportFilename(base, format, date) {
+    const d = date ?? localIsoDate(new Date());
+    const safe = base.trim().toLowerCase().replace(/[^\p{L}\p{N}]+/gu, "-").replace(/^-+|-+$/g, "") || "export";
+    return `${safe}-${d}.${format}`;
+}
+function localIsoDate(d) {
+    const p = (n) => String(n).padStart(2, "0");
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+/** Saves a Blob as a file in the browser. */
+export function downloadBlob(blob, filename) {
+    if (typeof document === "undefined")
+        return;
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = filename;
+    a.rel = "noopener";
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+    setTimeout(() => URL.revokeObjectURL(url), 1000);
+}

package/dist/business/export.d.ts

@@ -0,0 +1,148 @@
+import * as React from "react";
+import { type LabelFn } from "../lib/labels.js";
+import { Button } from "../components/button.js";
+import type { ListState } from "../data-table/types.js";
+import { type CsvExportOptions, type ExportColumn, type ExportFormat } from "./export-core.js";
+export declare const exportLabels: {
+    title: string;
+    description: string;
+    scope: string;
+    scopeSelected: string;
+    scopeFiltered: string;
+    scopeAll: string;
+    scopeFilteredHint: string;
+    scopeFilteredHintNoQ: string;
+    rows: string;
+    noneSelected: string;
+    columns: string;
+    columnsCount: string;
+    selectAll: string;
+    searchColumns: string;
+    noColumns: string;
+    personal: string;
+    mask: string;
+    maskHint: string;
+    format: string;
+    csv: string;
+    csvHint: string;
+    comma: string;
+    semicolon: string;
+    tab: string;
+    pointDecimal: string;
+    commaDecimal: string;
+    xlsx: string;
+    xlsxHint: string;
+    json: string;
+    jsonHint: string;
+    privacyTitle: string;
+    privacyBody: string;
+    reason: string;
+    reasonHint: string;
+    reasonMissing: string;
+    reasonPlaceholder: string;
+    background: string;
+    export: string;
+    exporting: string;
+    cancel: string;
+    close: string;
+    nothing: string;
+    noColumnsSelected: string;
+    queued: string;
+    running: string;
+    done: string;
+    failed: string;
+    download: string;
+    retry: string;
+    saved: string;
+    quick: string;
+};
+export type ExportLabels = typeof exportLabels;
+export type ExportScope = "selected" | "filtered" | "all";
+export interface ExportRequest {
+    scope: ExportScope;
+    /** Column ids in the chosen order. */
+    columns: string[];
+    /** Column ids to write masked. */
+    masked: string[];
+    format: ExportFormat;
+    reason?: string;
+    csv: Required<CsvExportOptions>;
+    /** Suggested file name ("contacts-2026-11-10.csv"). */
+    filename: string;
+}
+export type ExportResult = {
+    blob: Blob;
+    filename?: string;
+} | {
+    jobId: string;
+};
+export interface ExportJobState {
+    status: "queued" | "running" | "done" | "failed";
+    /** 0–100. */
+    progress?: number;
+    url?: string;
+    error?: string;
+}
+export interface ExportDialogProps {
+    columns: ExportColumn[];
+    /** What "Current view" means: filters and search of the list. */
+    listState?: ListState;
+    selectedCount?: number;
+    /** Rows matching the current view. */
+    filteredCount?: number;
+    totalCount?: number;
+    /** Plural noun for titles ("contacts"). Default "records". */
+    resource?: string;
+    formats?: ExportFormat[];
+    csv?: CsvExportOptions;
+    /** `true` always asks for a reason; `"personal-data"` only when unmasked personal columns are included. */
+    requireReason?: boolean | "personal-data";
+    /** Rows above this are announced as a background job. Default 10,000. */
+    syncLimit?: number;
+    onExport: (request: ExportRequest) => Promise<ExportResult>;
+    /** Polled every 1.5 s for background jobs. */
+    pollJob?: (jobId: string) => Promise<ExportJobState>;
+    presentation?: "dialog" | "sheet";
+    /** The element that opens the dialog (rendered with `asChild`). */
+    trigger?: React.ReactElement;
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    defaultScope?: ExportScope;
+    defaultFormat?: ExportFormat;
+    labels?: Partial<ExportLabels>;
+}
+/**
+ * Export a collection: scope (selected / current view / all), columns (searchable, reorderable,
+ * personal data maskable), format (CSV / XLSX / JSON with locale CSV conventions), a reason for
+ * personal-data exports and background jobs with a download link.
+ *
+ * ```tsx
+ * <ExportDialog resource="contacts" columns={columns} listState={state} selectedCount={3} filteredCount={248} totalCount={1240}
+ *   trigger={<Button><Download /> Export</Button>}
+ *   onExport={async (r) => ({ blob: await exportToBlob({ rows, columns: pick(r.columns), format: r.format, masked: r.masked }) })} />
+ * ```
+ */
+export declare function ExportDialog(props: ExportDialogProps): React.JSX.Element;
+export interface ExportJobStatusProps {
+    job: ExportJobState;
+    filename: string;
+    onRetry?: () => void;
+    labels?: Partial<ExportLabels>;
+    className?: string;
+}
+/** Background export progress: queued → running (progress bar) → done (focusable download link) / failed (retry). */
+export declare function ExportJobStatus({ job, filename, onRetry, labels, className, t: tProp, downloadRef, }: ExportJobStatusProps & {
+    t?: LabelFn<ExportLabels>;
+    downloadRef?: React.Ref<HTMLAnchorElement>;
+}): React.JSX.Element;
+export interface QuickExportButtonProps extends Omit<React.ComponentProps<typeof Button>, "onClick"> {
+    /** Exports the current view with default columns. Return a Blob to download it. */
+    onExport: () => Promise<{
+        blob: Blob;
+        filename: string;
+    }>;
+    labels?: Partial<ExportLabels>;
+}
+/** One click: current view, default columns, default format. */
+export declare function QuickExportButton({ onExport, labels, children, ...props }: QuickExportButtonProps): React.JSX.Element;