@modern-admin/react 0.1.0

package/dist/use-dashboard-charts.d.ts

@@ -0,0 +1,93 @@
+import { type ChartDef, type ChartDefInput, type ChartGroup, type DashboardBlob, type IDashboardStore, type TimeRange } from '@modern-admin/core';
+import type { AdminClient, TimeSeriesMetric, TimeSeriesStep } from './client.js';
+/**
+ * localStorage-backed `IDashboardStore`. Persists one blob per user under
+ * `modern-admin:dashboard:v1:<userId>` so multiple admins on the same
+ * browser do not see each other's charts.
+ *
+ * SSR-safe: `typeof window` checks gate every access; on the server load()
+ * returns `EMPTY_DASHBOARD` and save() is a no-op.
+ */
+export declare class LocalStorageDashboardStore implements IDashboardStore {
+    load(userId: string): DashboardBlob;
+    save(userId: string, blob: DashboardBlob): void;
+}
+/**
+ * Server-backed `IDashboardStore` that persists per-user dashboard layouts
+ * via `GET/PUT /admin/api/dashboard`. Requires `configStore` to be wired in
+ * `ModernAdminModule.forRoot()`. Falls back gracefully when the endpoint
+ * returns an empty dashboard (e.g. first load or missing configStore).
+ */
+export declare class ServerDashboardStore implements IDashboardStore {
+    private readonly client;
+    constructor(client: AdminClient);
+    load(_userId: string): Promise<DashboardBlob>;
+    save(_userId: string, blob: DashboardBlob): Promise<void>;
+}
+/**
+ * Resolve a `TimeRange` (preset or explicit custom) into concrete
+ * inclusive `from`/`to` `YYYY-MM-DD` strings. Presets are anchored to
+ * `now` so cards always reflect "the last N days" without re-saving.
+ *
+ * `'all'` resolves to a 10-year window ending at `now`, which is wide
+ * enough for any realistic admin dataset while keeping the server's
+ * date-range constraint satisfied.
+ */
+export declare function resolveRange(range: TimeRange, now?: Date): {
+    from: string;
+    to: string;
+};
+/**
+ * Equal-length window immediately preceding `[from, to]`.
+ */
+export declare function previousRangeOf(range: {
+    from: string;
+    to: string;
+}): {
+    from: string;
+    to: string;
+} | null;
+/** Signal every mounted `useDashboardCharts` hook to reload from its store. */
+export declare function emitDashboardReload(): void;
+export interface UseDashboardChartsOptions {
+    /** Used to scope the storage key. `null`/`undefined` defers loading. */
+    userId: string | null | undefined;
+    /** Override the default localStorage store (e.g. server-backed in future). */
+    store?: IDashboardStore;
+}
+export interface UseDashboardChartsResult {
+    charts: ChartDef[];
+    /** Groups defined on the dashboard, sorted by `order` ascending. */
+    groups: ChartGroup[];
+    /** True until the initial load has resolved (relevant for async stores). */
+    isLoading: boolean;
+    /** Append a new chart. Auto-assigns to the first group when groups exist and no `groupId` is provided. */
+    addChart(input: ChartDefInput): void;
+    updateChart(id: string, input: ChartDefInput): void;
+    removeChart(id: string): void;
+    /**
+     * Create a new group. When this is the very first group, every existing
+     * (ungrouped) chart is moved into it so the user keeps the same view.
+     * Returns the new group id so callers can switch to it.
+     */
+    addGroup(input: {
+        name: string;
+        order?: number;
+    }): string;
+    updateGroup(id: string, patch: {
+        name?: string;
+        order?: number;
+    }): void;
+    /** Remove a group AND every chart assigned to it. */
+    removeGroup(id: string): void;
+}
+/**
+ * Per-user dashboard chart registry backed by `IDashboardStore` (default:
+ * `LocalStorageDashboardStore`). When `userId` is null/undefined the hook
+ * returns an empty list and ignores writes — used while
+ * `useCurrentUser()` is still loading.
+ */
+export declare function useDashboardCharts(options: UseDashboardChartsOptions): UseDashboardChartsResult;
+export type { TimeSeriesMetric, TimeSeriesStep };
+export type { ChartDef, ChartDefInput, ChartGroup } from '@modern-admin/core';
+//# sourceMappingURL=use-dashboard-charts.d.ts.map

package/dist/use-dashboard-charts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-dashboard-charts.d.ts","sourceRoot":"","sources":["../src/use-dashboard-charts.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,SAAS,EACf,MAAM,oBAAoB,CAAA;AAC3B,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAKhF;;;;;;;GAOG;AACH,qBAAa,0BAA2B,YAAW,eAAe;IAChE,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa;IAenC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI;CAWhD;AAID;;;;;GAKG;AACH,qBAAa,oBAAqB,YAAW,eAAe;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,WAAW;IAE1C,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAS7C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;CAOhE;AAID;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,SAAS,EAChB,GAAG,GAAE,IAAiB,GACrB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAY9B;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAQrC;AAaD,+EAA+E;AAC/E,wBAAgB,mBAAmB,IAAI,IAAI,CAQ1C;AAID,MAAM,WAAW,yBAAyB;IACxC,wEAAwE;IACxE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;IACjC,8EAA8E;IAC9E,KAAK,CAAC,EAAE,eAAe,CAAA;CACxB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,QAAQ,EAAE,CAAA;IAClB,oEAAoE;IACpE,MAAM,EAAE,UAAU,EAAE,CAAA;IACpB,4EAA4E;IAC5E,SAAS,EAAE,OAAO,CAAA;IAClB,0GAA0G;IAC1G,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAA;IACpC,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI,CAAA;IACnD,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAA;IACzD,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;IACvE,qDAAqD;IACrD,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,yBAAyB,GACjC,wBAAwB,CAqK1B;AASD,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,CAAA;AAChD,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/use-dashboard-charts.js

@@ -0,0 +1,263 @@
+import { useCallback, useEffect, useState } from 'react';
+import { EMPTY_DASHBOARD, dashboardBlobZ, uuidv7, } from '@modern-admin/core';
+const STORAGE_PREFIX = 'modern-admin:dashboard:v1:';
+const ANON_USER = '__anon__';
+/**
+ * localStorage-backed `IDashboardStore`. Persists one blob per user under
+ * `modern-admin:dashboard:v1:<userId>` so multiple admins on the same
+ * browser do not see each other's charts.
+ *
+ * SSR-safe: `typeof window` checks gate every access; on the server load()
+ * returns `EMPTY_DASHBOARD` and save() is a no-op.
+ */
+export class LocalStorageDashboardStore {
+    load(userId) {
+        if (typeof window === 'undefined')
+            return EMPTY_DASHBOARD;
+        try {
+            const raw = window.localStorage.getItem(STORAGE_PREFIX + (userId || ANON_USER));
+            if (!raw)
+                return EMPTY_DASHBOARD;
+            const parsed = JSON.parse(raw);
+            const result = dashboardBlobZ.safeParse(parsed);
+            // Legacy bare-array shapes and other malformed blobs reset to empty
+            // rather than crashing the dashboard.
+            return result.success ? result.data : EMPTY_DASHBOARD;
+        }
+        catch {
+            return EMPTY_DASHBOARD;
+        }
+    }
+    save(userId, blob) {
+        if (typeof window === 'undefined')
+            return;
+        try {
+            window.localStorage.setItem(STORAGE_PREFIX + (userId || ANON_USER), JSON.stringify(blob));
+        }
+        catch {
+            // Quota exceeded / private mode — silently drop.
+        }
+    }
+}
+const defaultStore = new LocalStorageDashboardStore();
+/**
+ * Server-backed `IDashboardStore` that persists per-user dashboard layouts
+ * via `GET/PUT /admin/api/dashboard`. Requires `configStore` to be wired in
+ * `ModernAdminModule.forRoot()`. Falls back gracefully when the endpoint
+ * returns an empty dashboard (e.g. first load or missing configStore).
+ */
+export class ServerDashboardStore {
+    constructor(client) {
+        this.client = client;
+    }
+    async load(_userId) {
+        try {
+            const res = await this.client.loadDashboard();
+            return res.dashboard;
+        }
+        catch {
+            return EMPTY_DASHBOARD;
+        }
+    }
+    async save(_userId, blob) {
+        try {
+            await this.client.saveDashboard(blob);
+        }
+        catch {
+            // Server unavailable — silently drop. The next save attempt will retry.
+        }
+    }
+}
+// ─── Time-range helpers ──────────────────────────────────────────────────
+/**
+ * Resolve a `TimeRange` (preset or explicit custom) into concrete
+ * inclusive `from`/`to` `YYYY-MM-DD` strings. Presets are anchored to
+ * `now` so cards always reflect "the last N days" without re-saving.
+ *
+ * `'all'` resolves to a 10-year window ending at `now`, which is wide
+ * enough for any realistic admin dataset while keeping the server's
+ * date-range constraint satisfied.
+ */
+export function resolveRange(range, now = new Date()) {
+    if (range.preset === 'custom')
+        return { from: range.from, to: range.to };
+    const days = range.preset === '7d' ? 7
+        : range.preset === '30d' ? 30
+            : range.preset === '90d' ? 90
+                : range.preset === '1y' ? 365
+                    : 3650; // 'all' → 10 years
+    const to = new Date(now);
+    const from = new Date(now);
+    from.setDate(from.getDate() - days);
+    return { from: ymd(from), to: ymd(to) };
+}
+/**
+ * Equal-length window immediately preceding `[from, to]`.
+ */
+export function previousRangeOf(range) {
+    const f = new Date(range.from).getTime();
+    const t = new Date(range.to).getTime();
+    if (isNaN(f) || isNaN(t) || t < f)
+        return null;
+    const span = t - f;
+    const prevTo = new Date(f - 86_400_000);
+    const prevFrom = new Date(prevTo.getTime() - span);
+    return { from: ymd(prevFrom), to: ymd(prevTo) };
+}
+const ymd = (d) => d.toISOString().slice(0, 10);
+// ─── Reload signal ───────────────────────────────────────────────────────
+/**
+ * Module-scoped pub/sub so external code (e.g. AI assistant widget after a
+ * chart mutation) can force the dashboard to reload its blob from the store
+ * without lifting state up. Subscribers are notified asynchronously.
+ */
+const dashboardReloadListeners = new Set();
+/** Signal every mounted `useDashboardCharts` hook to reload from its store. */
+export function emitDashboardReload() {
+    for (const listener of dashboardReloadListeners) {
+        try {
+            listener();
+        }
+        catch {
+            // Listener errors must not block sibling listeners.
+        }
+    }
+}
+/**
+ * Per-user dashboard chart registry backed by `IDashboardStore` (default:
+ * `LocalStorageDashboardStore`). When `userId` is null/undefined the hook
+ * returns an empty list and ignores writes — used while
+ * `useCurrentUser()` is still loading.
+ */
+export function useDashboardCharts(options) {
+    const { userId, store = defaultStore } = options;
+    const [charts, setCharts] = useState([]);
+    const [groups, setGroups] = useState([]);
+    const [isLoading, setIsLoading] = useState(true);
+    // Bumping this counter re-runs the load effect; used by external
+    // `emitDashboardReload()` callers (e.g. AI assistant widget) so the hook
+    // can pick up changes other actors made to the underlying store.
+    const [reloadTick, setReloadTick] = useState(0);
+    // Reload whenever `userId` flips (login / logout / switch) or an external
+    // reload is signalled.
+    useEffect(() => {
+        if (!userId) {
+            setCharts([]);
+            setIsLoading(false);
+            return;
+        }
+        let cancelled = false;
+        setIsLoading(true);
+        Promise.resolve(store.load(userId)).then((blob) => {
+            if (cancelled)
+                return;
+            setCharts(blob.charts);
+            setGroups([...blob.groups].sort(byOrderThenCreated));
+            setIsLoading(false);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [userId, store, reloadTick]);
+    // Subscribe to module-scoped reload signal.
+    useEffect(() => {
+        const listener = () => setReloadTick((tick) => tick + 1);
+        dashboardReloadListeners.add(listener);
+        return () => {
+            dashboardReloadListeners.delete(listener);
+        };
+    }, []);
+    // Single persist that writes BOTH charts and groups so a partial update
+    // never strands one in localStorage while overwriting the other.
+    const persist = useCallback((nextCharts, nextGroups) => {
+        setCharts(nextCharts);
+        setGroups([...nextGroups].sort(byOrderThenCreated));
+        if (!userId)
+            return;
+        void Promise.resolve(store.save(userId, { version: 1, charts: nextCharts, groups: nextGroups }));
+    }, [userId, store]);
+    const addChart = useCallback((input) => {
+        const now = new Date().toISOString();
+        // When groups exist and the caller didn't pick one, fall back to the
+        // first-ordered group so the new chart is visible somewhere.
+        const fallbackGroupId = input.groupId ?? groups[0]?.id;
+        const def = {
+            ...input,
+            id: uuidv7(),
+            title: input.title ?? '',
+            filters: input.filters ?? {},
+            ...(fallbackGroupId ? { groupId: fallbackGroupId } : {}),
+            createdAt: now,
+            updatedAt: now,
+        };
+        persist([...charts, def], groups);
+    }, [charts, groups, persist]);
+    const updateChart = useCallback((id, input) => {
+        persist(charts.map((c) => c.id === id
+            ? {
+                ...c,
+                ...input,
+                id,
+                title: input.title ?? '',
+                filters: input.filters ?? {},
+                createdAt: c.createdAt,
+                updatedAt: new Date().toISOString(),
+            }
+            : c), groups);
+    }, [charts, groups, persist]);
+    const removeChart = useCallback((id) => {
+        persist(charts.filter((c) => c.id !== id), groups);
+    }, [charts, groups, persist]);
+    const addGroup = useCallback((input) => {
+        const now = new Date().toISOString();
+        const id = uuidv7();
+        const next = {
+            id,
+            name: input.name,
+            order: input.order ?? groups.length,
+            createdAt: now,
+            updatedAt: now,
+        };
+        // First-group rule: existing ungrouped charts join this group so the
+        // user does not lose their current dashboard view.
+        const isFirstGroup = groups.length === 0;
+        const nextCharts = isFirstGroup
+            ? charts.map((c) => (c.groupId ? c : { ...c, groupId: id, updatedAt: now }))
+            : charts;
+        persist(nextCharts, [...groups, next]);
+        return id;
+    }, [charts, groups, persist]);
+    const updateGroup = useCallback((id, patch) => {
+        const now = new Date().toISOString();
+        persist(charts, groups.map((g) => g.id === id
+            ? {
+                ...g,
+                ...(patch.name !== undefined ? { name: patch.name } : {}),
+                ...(patch.order !== undefined ? { order: patch.order } : {}),
+                updatedAt: now,
+            }
+            : g));
+    }, [charts, groups, persist]);
+    const removeGroup = useCallback((id) => {
+        // Cascading delete: every chart assigned to the group disappears with it.
+        persist(charts.filter((c) => c.groupId !== id), groups.filter((g) => g.id !== id));
+    }, [charts, groups, persist]);
+    return {
+        charts,
+        groups,
+        isLoading,
+        addChart,
+        updateChart,
+        removeChart,
+        addGroup,
+        updateGroup,
+        removeGroup,
+    };
+}
+/** Stable sort: by `order` ascending, then by `createdAt` for tie-breaking. */
+function byOrderThenCreated(a, b) {
+    if (a.order !== b.order)
+        return a.order - b.order;
+    return a.createdAt.localeCompare(b.createdAt);
+}
+//# sourceMappingURL=use-dashboard-charts.js.map

package/dist/use-dashboard-charts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-dashboard-charts.js","sourceRoot":"","sources":["../src/use-dashboard-charts.ts"],"names":[],"mappings":"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"}

package/dist/use-hotkey.d.ts

@@ -0,0 +1,17 @@
+export interface HotkeyOptions {
+    enabled?: boolean;
+    /** Override input-suppression. `true` always fires, `false` never. */
+    allowInInput?: boolean;
+    /** Call `preventDefault()` on match. Default `true`. */
+    preventDefault?: boolean;
+    /**
+     * Human-readable label shown in <KeyboardShortcutsHelp>. When set, the
+     * hotkey registers itself with the surrounding HotkeyRegistryProvider
+     * for the duration it's mounted (and `enabled`).
+     */
+    description?: string;
+    /** Optional group label used to bucket entries in the help dialog. */
+    group?: string;
+}
+export declare function useHotkey(combo: string | string[], handler: (e: KeyboardEvent) => void, options?: HotkeyOptions): void;
+//# sourceMappingURL=use-hotkey.d.ts.map

package/dist/use-hotkey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-hotkey.d.ts","sourceRoot":"","sources":["../src/use-hotkey.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,sEAAsE;IACtE,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,wDAAwD;IACxD,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAoED,wBAAgB,SAAS,CACvB,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EACxB,OAAO,EAAE,CAAC,CAAC,EAAE,aAAa,KAAK,IAAI,EACnC,OAAO,GAAE,aAAkB,GAC1B,IAAI,CA6BN"}

package/dist/use-hotkey.js

@@ -0,0 +1,103 @@
+// Tiny keyboard-shortcut hook. Each combo is a `+`-separated string,
+// e.g. `mod+s`, `ctrl+shift+k`, `esc`. `mod` matches Ctrl on
+// Windows/Linux and Cmd on macOS so Ctrl+S / ⌘S map to the same handler.
+//
+// By default a chord with a modifier (mod / alt) fires anywhere; a
+// modifier-less chord is suppressed when focus is inside an input,
+// textarea, select, or contenteditable element so plain `n`/`r` keys
+// don't hijack typing. Override per-call with `allowInInput`.
+import * as React from 'react';
+import { useHotkeyRegister } from './hotkey-registry.js';
+const KEY_ALIASES = {
+    esc: 'escape',
+    space: ' ',
+    spacebar: ' ',
+    return: 'enter',
+    del: 'delete',
+};
+function keyToCode(key) {
+    if (/^[a-z]$/.test(key))
+        return `Key${key.toUpperCase()}`;
+    if (/^[0-9]$/.test(key))
+        return `Digit${key}`;
+    return null;
+}
+function parseCombo(s) {
+    const parts = s.toLowerCase().split('+').map((p) => p.trim()).filter(Boolean);
+    const last = parts[parts.length - 1] ?? '';
+    const key = KEY_ALIASES[last] ?? last;
+    const code = keyToCode(key);
+    const mod = parts.some((p) => p === 'mod' || p === 'ctrl' || p === 'meta' || p === 'cmd');
+    const shift = parts.includes('shift');
+    const alt = parts.includes('alt') || parts.includes('option');
+    return { key, code, mod, shift, alt, hasModifier: mod || alt };
+}
+function normalizeEventKey(e) {
+    return typeof e.key === 'string' ? e.key.toLowerCase() : null;
+}
+function normalizeEventCode(e) {
+    return typeof e.code === 'string' && e.code.length > 0 ? e.code : null;
+}
+function matches(c, e) {
+    if (c.code) {
+        const code = normalizeEventCode(e);
+        if (!code || code !== c.code)
+            return false;
+    }
+    else {
+        const k = normalizeEventKey(e);
+        if (!k || k !== c.key)
+            return false;
+    }
+    const hasMod = e.ctrlKey || e.metaKey;
+    if (c.mod !== hasMod)
+        return false;
+    if (c.alt !== e.altKey)
+        return false;
+    // Require shift only when explicitly asked. Letter keys may have shift
+    // accidentally engaged (caps lock, etc.) — allow that case.
+    if (c.shift && !e.shiftKey)
+        return false;
+    return true;
+}
+function isEditableTarget(target) {
+    if (!(target instanceof HTMLElement))
+        return false;
+    const tag = target.tagName;
+    if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT')
+        return true;
+    return target.isContentEditable;
+}
+export function useHotkey(combo, handler, options = {}) {
+    const { enabled = true, allowInInput, preventDefault = true, description, group } = options;
+    const handlerRef = React.useRef(handler);
+    React.useEffect(() => {
+        handlerRef.current = handler;
+    }, [handler]);
+    const comboKey = Array.isArray(combo) ? combo.join('|') : combo;
+    const register = useHotkeyRegister();
+    React.useEffect(() => {
+        if (!enabled)
+            return;
+        const parsed = comboKey.split('|').map(parseCombo);
+        const onKeyDown = (e) => {
+            const hit = parsed.find((c) => matches(c, e));
+            if (!hit)
+                return;
+            const allow = allowInInput ?? hit.hasModifier;
+            if (!allow && isEditableTarget(e.target))
+                return;
+            if (preventDefault)
+                e.preventDefault();
+            handlerRef.current(e);
+        };
+        document.addEventListener('keydown', onKeyDown);
+        return () => document.removeEventListener('keydown', onKeyDown);
+    }, [comboKey, enabled, allowInInput, preventDefault]);
+    React.useEffect(() => {
+        if (!enabled || !description)
+            return;
+        return register({ keys: comboKey, description, group });
+    }, [enabled, description, group, comboKey, register]);
+}
+//# sourceMappingURL=use-hotkey.js.map

package/dist/use-hotkey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-hotkey.js","sourceRoot":"","sources":["../src/use-hotkey.ts"],"names":[],"mappings":"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"}

package/dist/user-directory.d.ts

@@ -0,0 +1,18 @@
+import type { RecordJSON } from './types.js';
+/** Convention: the host app exposes panel administrators under the
+ *  `admins` resource id (backed by Better Auth's `ma_user` table). When
+ *  absent or the lookup fails we fall back to the raw id string. */
+export declare const USERS_RESOURCE_ID = "admins";
+/** Resolve admin user records by id via the conventional `users` resource.
+ *  Failed lookups (404 / no users resource) cache as `null` so we don't keep
+ *  retrying them on every re-render.
+ *
+ *  NOTE: uses the `'user-dir'` segment (not `'show'`) so the cached value
+ *  (`RecordJSON | null`) doesn't collide with `useRecord`'s cache which stores
+ *  the full `RecordResponse` shape under `['modern-admin', id, 'show', ...]`. */
+export declare function useUserDirectory(userIds: ReadonlyArray<string>): Map<string, RecordJSON | null>;
+/** Pick a human-readable label for an admin record. Checks explicit name
+ *  fields first — `record.title` may be the id fallback when the resource
+ *  has no matching TITLE_COLUMN_NAMES property. */
+export declare function userLabelOf(record: RecordJSON | null | undefined, fallback: string): string;
+//# sourceMappingURL=user-directory.d.ts.map

package/dist/user-directory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-directory.d.ts","sourceRoot":"","sources":["../src/user-directory.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C;;oEAEoE;AACpE,eAAO,MAAM,iBAAiB,WAAW,CAAA;AAEzC;;;;;;iFAMiF;AACjF,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,GAC7B,GAAG,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC,CAoBhC;AAED;;mDAEmD;AACnD,wBAAgB,WAAW,CACzB,MAAM,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,EACrC,QAAQ,EAAE,MAAM,GACf,MAAM,CASR"}

package/dist/user-directory.js

@@ -0,0 +1,51 @@
+import { useQueries } from '@tanstack/react-query';
+import { useAdminClient } from './provider.js';
+/** Convention: the host app exposes panel administrators under the
+ *  `admins` resource id (backed by Better Auth's `ma_user` table). When
+ *  absent or the lookup fails we fall back to the raw id string. */
+export const USERS_RESOURCE_ID = 'admins';
+/** Resolve admin user records by id via the conventional `users` resource.
+ *  Failed lookups (404 / no users resource) cache as `null` so we don't keep
+ *  retrying them on every re-render.
+ *
+ *  NOTE: uses the `'user-dir'` segment (not `'show'`) so the cached value
+ *  (`RecordJSON | null`) doesn't collide with `useRecord`'s cache which stores
+ *  the full `RecordResponse` shape under `['modern-admin', id, 'show', ...]`. */
+export function useUserDirectory(userIds) {
+    const client = useAdminClient();
+    const queries = useQueries({
+        queries: userIds.map((id) => ({
+            queryKey: ['modern-admin', 'user-dir', USERS_RESOURCE_ID, id],
+            queryFn: async () => {
+                try {
+                    const res = await client.show(USERS_RESOURCE_ID, id);
+                    return res.record;
+                }
+                catch {
+                    return null;
+                }
+            },
+            staleTime: 60_000,
+            retry: false,
+        })),
+    });
+    const map = new Map();
+    userIds.forEach((id, i) => map.set(id, queries[i]?.data ?? null));
+    return map;
+}
+/** Pick a human-readable label for an admin record. Checks explicit name
+ *  fields first — `record.title` may be the id fallback when the resource
+ *  has no matching TITLE_COLUMN_NAMES property. */
+export function userLabelOf(record, fallback) {
+    if (!record)
+        return fallback;
+    const params = record.params ?? {};
+    const candidates = [params.name, params.fullName, params.email, record.title];
+    for (const candidate of candidates) {
+        const s = typeof candidate === 'string' ? candidate.trim() : '';
+        if (s && s !== record.id)
+            return s;
+    }
+    return fallback;
+}
+//# sourceMappingURL=user-directory.js.map

package/dist/user-directory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-directory.js","sourceRoot":"","sources":["../src/user-directory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAG9C;;oEAEoE;AACpE,MAAM,CAAC,MAAM,iBAAiB,GAAG,QAAQ,CAAA;AAEzC;;;;;;iFAMiF;AACjF,MAAM,UAAU,gBAAgB,CAC9B,OAA8B;IAE9B,MAAM,MAAM,GAAG,cAAc,EAAE,CAAA;IAC/B,MAAM,OAAO,GAAG,UAAU,CAAC;QACzB,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;YAC5B,QAAQ,EAAE,CAAC,cAAc,EAAE,UAAU,EAAE,iBAAiB,EAAE,EAAE,CAAU;YACtE,OAAO,EAAE,KAAK,IAAgC,EAAE;gBAC9C,IAAI,CAAC;oBACH,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAA;oBACpD,OAAO,GAAG,CAAC,MAAM,CAAA;gBACnB,CAAC;gBAAC,MAAM,CAAC;oBACP,OAAO,IAAI,CAAA;gBACb,CAAC;YACH,CAAC;YACD,SAAS,EAAE,MAAM;YACjB,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;KACJ,CAAC,CAAA;IACF,MAAM,GAAG,GAAG,IAAI,GAAG,EAA6B,CAAA;IAChD,OAAO,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,IAAI,CAAC,CAAC,CAAA;IACjE,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;mDAEmD;AACnD,MAAM,UAAU,WAAW,CACzB,MAAqC,EACrC,QAAgB;IAEhB,IAAI,CAAC,MAAM;QAAE,OAAO,QAAQ,CAAA;IAC5B,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,EAAE,CAAA;IAClC,MAAM,UAAU,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;IAC7E,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,MAAM,CAAC,GAAG,OAAO,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;QAC/D,IAAI,CAAC,IAAI,CAAC,KAAK,MAAM,CAAC,EAAE;YAAE,OAAO,CAAC,CAAA;IACpC,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC"}

package/dist/validation.d.ts

@@ -0,0 +1,22 @@
+import { z, type ZodType } from 'zod';
+import type { PropertyJSON } from './types.js';
+/**
+ * Lazy form-snapshot reader. Passed by the caller (the edit page) so the
+ * schema can consult the live form values at validation time without taking
+ * a hard dependency on RHF. Returning `{}` is fine — every property defaults
+ * to "visible" then.
+ */
+export type FormValuesGetter = () => Record<string, unknown>;
+export type Translator = (key: string, params?: Record<string, unknown>) => string;
+/**
+ * Map a PropertyJSON to its Zod schema. When the property has a `showWhen`
+ * rule and a `getValues` getter is supplied, the schema short-circuits to
+ * a no-op while the rule does not match — letting hidden branches pass
+ * validation without their required/format checks tripping submission.
+ */
+export declare function buildPropertySchema(p: PropertyJSON, t: Translator, getValues?: FormValuesGetter): ZodType;
+/** Build a Zod object schema covering every editable property in a resource. */
+export declare function buildValidationSchema(properties: PropertyJSON[], t: Translator, getValues?: FormValuesGetter): z.ZodObject<Record<string, ZodType>>;
+/** Sensible empty default per type so RHF stays controlled from first render. */
+export declare function defaultValueFor(p: PropertyJSON): unknown;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,CAAC,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,CAAA;AACrC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAG9C;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAE5D,MAAM,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAA;AAwRlF;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,CAAC,EAAE,YAAY,EACf,CAAC,EAAE,UAAU,EACb,SAAS,CAAC,EAAE,gBAAgB,GAC3B,OAAO,CA0BT;AAED,gFAAgF;AAChF,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,YAAY,EAAE,EAC1B,CAAC,EAAE,UAAU,EACb,SAAS,CAAC,EAAE,gBAAgB,GAC3B,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAItC;AAED,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,CAAC,EAAE,YAAY,GAAG,OAAO,CAKxD"}