@declarion/react 0.60.0 → 0.63.0

package/dist-lib/safe-url-oSJw5pzO.js

@@ -1,34 +0,0 @@
-//#region src/lib/safe-url.ts
-var e = [
-	"http:",
-	"https:",
-	"mailto:"
-], t = /[\u0000-\u001f\u007f]/g;
-function n(n) {
-	if (!n) return;
-	let r = n.trim();
-	if (!r) return;
-	let i = r.replace(t, "");
-	if (!i || i.startsWith("//")) return;
-	let a = i.match(/^([a-zA-Z][a-zA-Z0-9+.-]*):/);
-	if (a) {
-		let t = a[1].toLowerCase() + ":";
-		if (!e.includes(t)) return;
-	}
-	return i;
-}
-function r(e) {
-	if (!e) return !1;
-	if (e.startsWith("//")) return !0;
-	let t = typeof window < "u" ? window.location.href : "http://localhost/", n;
-	try {
-		n = new URL(e, t);
-	} catch {
-		return !1;
-	}
-	if (n.protocol !== "http:" && n.protocol !== "https:") return !0;
-	let r = typeof window < "u" ? window.location.origin : "http://localhost";
-	return n.origin !== r;
-}
-//#endregion
-export { n, r as t };

package/dist-lib/stores/auth.d.ts

@@ -1,16 +0,0 @@
-import type { AuthUser, Tenant } from "../types/api.d.ts";
-interface AuthState {
-    user: AuthUser | null;
-    isAuthenticated: boolean;
-    isLoading: boolean;
-    activeTenant: Tenant | null;
-    tenants: Tenant[];
-    initialize: () => Promise<void>;
-    refreshMe: () => Promise<void>;
-    setUser: (user: AuthUser, tenant?: Tenant) => void;
-    setTenants: (tenants: Tenant[]) => void;
-    setActiveTenant: (tenant: Tenant) => void;
-    logout: () => Promise<void>;
-}
-export declare const useAuthStore: import("zustand").UseBoundStore<import("zustand").StoreApi<AuthState>>;
-export {};

package/dist-lib/stores/list-layout.d.ts

@@ -1,85 +0,0 @@
-/**
- * Per-device list-table WIDTH store. Holds ONE thing: column pixel widths,
- * device-local in localStorage, per (tenant, user, SCREEN) by column id. Screen-keyed, so
- * widening a column once holds across EVERY view of that screen on this device.
- * Absent entry = the YAML default (`field.display.width ?? 150`), resolved by
- * TanStack when `header.getSize()` reads `columnSizing[id] ?? columnDef.size`.
- *
- * Why widths are the ONLY thing here: order/visibility/sort/filters already
- * live in the URL and are persisted per device per tab by the `tabs` store -
- * that is the single source of truth for the logical layout (a second store
- * mirroring them caused a cold-open seed to clobber `?sort`; removed in rev 2).
- * Width is the one column setting that must NOT ride a shareable URL: it is
- * physical fit (a width tuned for a 27"/4K monitor would corrupt the same view
- * for a teammate on a laptop), so it is device-local and never in a saved view.
- *
- * This does NOT violate the "browser stores nothing" appearance-preferences
- * rule (`preferences.ts`): that governs deployment BRANDING
- * (theme/accent/density). Widths are device state of the same class as the
- * `tabs` store, which already uses localStorage. Keying + persistence mirror
- * `stores/tabs.ts`: a module-level (tenant,user) scope set via `setScope`, the
- * whole snapshot under one key `declarion::${tenantId}::${userId}::listlayout`,
- * hydrated on tenant switch. `childKey` callers pass a composite screenKey
- * `${screenCode}::child::${childKey}`; the store is agnostic to it.
- */
-/** Minimum resizable column width in px. Exported so the resize handler and
- *  the store's defensive clamp share ONE floor (no magic number). */
-export declare const MIN_COL_WIDTH = 60;
-/** Maximum resizable column width in px (a sane cap so a column can never
- *  become absurdly wide). Shared by the TanStack per-column `maxSize` and the
- *  store's defensive clamp. */
-export declare const MAX_COL_WIDTH = 1200;
-/** Snapshot schema version. A snapshot with a different `v` is discarded on
- *  read (future migrations plug in here). */
-export declare const LIST_LAYOUT_VERSION = 2;
-/** A screen's width overrides: colId -> pixel width. */
-export type WidthMap = Record<string, number>;
-interface LayoutSnapshot {
-    v: number;
-    /** screenKey -> (colId -> width). */
-    widths: Record<string, WidthMap>;
-    /** True once this user has resized any column on this device - gates the
-     *  one-time "widths are personal per device" education toast. */
-    resizeEduShown?: boolean;
-}
-interface LayoutState extends LayoutSnapshot {
-    setScope: (tenantId: string | null, userId: string | null) => void;
-    hydrate: () => void;
-    /** Set one column's width (clamped). */
-    setWidth: (screenKey: string, colId: string, width: number) => void;
-    /** Merge a batch of column widths (clamped). */
-    setWidths: (screenKey: string, widths: WidthMap) => void;
-    /** Drop all width overrides for a screen (back to YAML defaults). Stored as
-     *  an empty map, not a deleted key, so the reset propagates across tabs. */
-    resetWidths: (screenKey: string) => void;
-    /** Drop width entries for colIds no longer in the screen schema. */
-    prune: (screenKey: string, validColIds: string[]) => void;
-    /** Record that the one-time resize-education toast has been shown. */
-    markResizeEduShown: () => void;
-}
-/** Narrow an untrusted persisted snapshot (localStorage is hostile) to
- *  LayoutSnapshot, discarding anything malformed or of a foreign version. */
-export declare function parseLayoutSnapshot(raw: string): LayoutSnapshot | null;
-/**
- * Merge an incoming cross-tab snapshot into the local one, last-writer-wins per
- * screenKey (a screenKey present in `incoming` replaces the local value
- * wholesale, so a prune / reset-to-`{}` / edit all propagate; screenKeys only
- * the local tab touched survive).
- */
-export declare function mergeSnapshot(local: LayoutSnapshot, incoming: LayoutSnapshot): LayoutSnapshot;
-export declare const useListLayoutStore: import("zustand").UseBoundStore<import("zustand").StoreApi<LayoutState>>;
-/** Subscribe to the window `storage` event for the layout key and merge an
- *  incoming snapshot (last-writer-wins per screenKey). Idempotent. */
-export declare function startListLayoutCrossTabSync(): void;
-export interface ScopedListLayout {
-    widths: WidthMap;
-    /** Whether the one-time resize-education toast has already been shown. */
-    resizeEduShown: boolean;
-    setWidth: (colId: string, width: number) => void;
-    setWidths: (widths: WidthMap) => void;
-    resetWidths: () => void;
-    prune: (validColIds: string[]) => void;
-    markResizeEduShown: () => void;
-}
-export declare function useListLayout(screenKey: string | null | undefined): ScopedListLayout;
-export {};

package/dist-lib/stores/page-state.d.ts

@@ -1,61 +0,0 @@
-import type { QueryClient, QueryKey } from "@tanstack/react-query";
-/** Default retention window before the `ui_page_state_ttl_ms` parameter
- *  resolves (and the fallback when it is absent). 30 minutes - long enough to
- *  switch among tabs all day instantly, bounded enough to keep memory sane.
- *  Mirrors the YAML default in core_parameters.yaml; both must agree. */
-export declare const DEFAULT_PAGE_STATE_TTL_MS: number;
-/** Hard upper bound on retained-page entries. Bounds total memory and is the
- *  ONLY bound in embed mode, which has no tab-close signal at all. Generous
- *  relative to `preferences.tabs_max_open` (a user rarely revisits more than this many
- *  distinct URLs within one TTL window); the least-recently-active entry is
- *  evicted first when the cap is exceeded. */
-export declare const PAGE_STATE_MAX_ENTRIES = 64;
-/** One retained page's deep state. `bag` holds small JSON-serializable deep
- *  values; `queryKeys` references the screen's PRIMARY React Query reads so an
- *  eviction can release the cached data alongside the deep state. */
-export interface PageStateEntry {
-    bag: Record<string, unknown>;
-    lastActiveAt: number;
-    queryKeys: QueryKey[];
-}
-interface PageStateStore {
-    /** pageKey (canonical URL) -> retained-page deep state. */
-    entries: Record<string, PageStateEntry>;
-    /** Active retention window. `<= 0` disables retention. Set by the runtime
-     *  from the resolved `ui_page_state_ttl_ms`; defaults to the 30-min fallback
-     *  so retention works before the parameter loads. */
-    ttlMs: number;
-    /** Set the retention window. `<= 0` disables retention and immediately clears
-     *  every entry (with linked `removeQueries`), so a runtime toggle to "off"
-     *  frees memory at once. */
-    setTtl: (ttlMs: number) => void;
-    /** Write a deep value under `pageKey`, refreshing `lastActiveAt` and
-     *  enforcing the LRU cap. No-op when retention is disabled. */
-    set: (pageKey: string, key: string, value: unknown) => void;
-    /** Read a deep value, or `undefined` when absent / reaped / retention off. */
-    read: (pageKey: string, key: string) => unknown;
-    /** Refresh `lastActiveAt` for a still-mounted view so it is not reaped while
-     *  active. No-op when the entry is absent or retention is disabled. */
-    touch: (pageKey: string) => void;
-    /** Track one of the screen's PRIMARY React Query keys so eviction releases
-     *  the cached data. Deduplicated. No-op when retention is disabled. */
-    registerQueryKey: (pageKey: string, queryKey: QueryKey) => void;
-    /** Explicitly evict one retained page NOW: drop its deep state AND
-     *  `removeQueries` its tracked keys. Idempotent; works even when retention is
-     *  disabled (used by per-screen kill policies, e.g. a deleted detail record). */
-    kill: (pageKey: string) => void;
-    /** Reap every entry stale past the active TTL (`now - lastActiveAt > ttlMs`),
-     *  releasing data + deep state together. When retention is disabled, evicts
-     *  all. `now` is injected for testability. */
-    sweep: (now: number) => void;
-    /** Drop EVERY retained page NOW (releasing all tracked queries) without
-     *  changing the TTL - the auth-scope reset. Called on logout so a different
-     *  user signing in within the same JS session cannot restore the prior user's
-     *  deep state (selection, scroll, custom-screen values). */
-    clear: () => void;
-}
-/** Register the app's QueryClient so retained-page eviction can release the
- *  tracked entity-read queries. Called once at app mount. */
-export declare function setPageStateQueryClient(client: QueryClient | null): void;
-export declare const usePageStateStore: import("zustand").UseBoundStore<import("zustand").StoreApi<PageStateStore>>;
-export {};

package/dist-lib/stores/preferences.d.ts

@@ -1,37 +0,0 @@
-import type { BrandingPreferences } from "../types/api.d.ts";
-export type ColorScheme = "light" | "dark";
-export type AccentId = "violet" | "blue" | "teal" | "amber" | "rose";
-export type Density = "compact" | "comfortable" | "cozy";
-export type SidebarMode = "wide" | "collapsed";
-export type TabsPosition = "top" | "bottom";
-export type AiSurface = "command" | "panel" | "both" | "off";
-export type ToastPosition = "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right";
-export interface Preferences {
-    colorScheme: ColorScheme;
-    accent: AccentId;
-    density: Density;
-    sidebar: SidebarMode;
-    tabsPosition: TabsPosition;
-    tabsMaxOpen: number;
-    /** When false, tabs are not persisted across reloads. */
-    tabsPersist: boolean;
-    radius: number;
-    zebra: boolean;
-    aiSurface: AiSurface;
-    /** Where toasts appear. Read by <Toaster> in app.tsx. */
-    toastPosition: ToastPosition;
-}
-export declare function applyPreferences(p: Preferences): void;
-interface PreferencesState extends Preferences {
-    set: <K extends keyof Preferences>(key: K, value: Preferences[K]) => void;
-    setMany: (patch: Partial<Preferences>) => void;
-    /** Apply the deployment's defaults from `branding.preferences`. ONLY fills
-     *  keys the user has not already changed this session, so a branding
-     *  refetch never clobbers a toggle the user just clicked. */
-    hydrateFromBranding: (preferences: BrandingPreferences | undefined) => void;
-    /** Forget every session choice and return to the deployment's defaults —
-     *  the same state a fresh page load resolves, reproduced on demand. */
-    resetToDefaults: (preferences: BrandingPreferences | undefined) => void;
-}
-export declare const usePreferencesStore: import("zustand").UseBoundStore<import("zustand").StoreApi<PreferencesState>>;
-export {};

package/dist-lib/stores/realtime.d.ts

@@ -1,96 +0,0 @@
-import type { QueryCacheNotifyEvent, QueryKey } from "@tanstack/react-query";
-/** A query as the query cache holds it, whatever its data type. */
-export type CachedQuery = QueryCacheNotifyEvent["query"];
-/** An entity the relay is not delivering; `mark` lets a resync drop only the mark it saw. */
-export interface DegradedMark {
-    mark: number;
-    since: number;
-}
-export interface RealtimeThresholds {
-    pauseGraceMs: number;
-    silenceMs: number;
-}
-/**
- * Which query keys a resync covers. `all` and `entities` also take in matching
- * keys first observed while the resync is pending; `keys` is fixed.
- */
-export type ResyncScope = {
-    kind: "all";
-} | {
-    kind: "entities";
-    entities: ReadonlySet<string>;
-} | {
-    kind: "keys";
-};
-export interface Resync {
-    id: number;
-    /** The fetch generation when it opened; only a fetch stamped above it satisfies a key. */
-    generation: number;
-    openedAt: number;
-    /** A refused read: shown at once, never issued, closed only by a fetch someone else starts. */
-    standing: boolean;
-    issued: boolean;
-    /** Whether issuing waits a random delay, so a fleet-wide cause does not burst. */
-    jitter: boolean;
-    scope: ResyncScope;
-    /** Query hash → key. */
-    keys: ReadonlyMap<string, QueryKey>;
-    /** Query hash → the query last seen observed under it, so a removed one still blocks while observed. */
-    observed: ReadonlyMap<string, CachedQuery>;
-    /** Marks dropped on completion, each only while it still carries this number. */
-    carriedMarks: ReadonlyMap<string, number>;
-    /** Entities with an observed key not yet satisfied. */
-    blocking: ReadonlySet<string>;
-}
-interface RealtimeState {
-    degradedEntities: ReadonlyMap<string, DegradedMark>;
-    /** Mark one entity degraded. A repeated mark renumbers it and keeps its start. */
-    markDegraded: (entityCode: string) => void;
-    /** Drop each mark named, only while the entity still carries that number. */
-    unmarkDegraded: (marks: ReadonlyMap<string, number>) => void;
-    /** Self-closing: no connection has stated its snapshot, or it went silent. */
-    connectionInterruptedSince: number | null;
-    holdConnectionInterruption: () => void;
-    clearConnectionInterruption: () => void;
-    /** Self-closing: the server's last word says the relay may not be streaming. */
-    relayInterruptedSince: number | null;
-    holdRelayInterruption: () => void;
-    clearRelayInterruption: () => void;
-    /** Self-closing: a connection presented a position and its replay has not applied. */
-    replayStartedAt: number | null;
-    startReplay: () => void;
-    endReplay: () => void;
-    /**
-     * Null while the declared thresholds load. `unreadable` is itself a held
-     * connection interruption, shown at once: claiming "Live" without the means
-     * to know is the defect this model removes.
-     */
-    thresholds: RealtimeThresholds | "unreadable" | null;
-    setThresholds: (thresholds: RealtimeThresholds | "unreadable" | null) => void;
-    resyncs: readonly Resync[];
-    addResync: (resync: Omit<Resync, "id">) => number;
-    updateResync: (id: number, patch: Partial<Omit<Resync, "id">>) => void;
-    removeResync: (id: number) => void;
-}
-export declare const useRealtimeStore: import("zustand").UseBoundStore<import("zustand").StoreApi<RealtimeState>>;
-export declare function isEntityLive(realtimeFlag: boolean | undefined, degradedEntities: {
-    has(entityCode: string): boolean;
-}, entityCode: string): boolean;
-type CurrentnessInputs = Pick<RealtimeState, "degradedEntities" | "connectionInterruptedSince" | "relayInterruptedSince" | "replayStartedAt" | "thresholds" | "resyncs">;
-/**
- * Whether an entity is current at `now`, and the next instant that answer can
- * flip without any state changing - when a self-closing cause reaches the pause
- * grace. Measured from each cause's stored start, so every surface flips at the
- * same instant.
- */
-export declare function screenCurrentness(state: CurrentnessInputs, realtimeFlag: boolean | undefined, entityCode: string, now: number): {
-    live: boolean;
-    recheckAt: number | null;
-};
-/**
- * The one predicate every indicator reads: is the screen showing this entity
- * CURRENT. The rows keep rendering throughout; this says whether they may be
- * behind.
- */
-export declare function useScreenIsLive(realtimeFlag: boolean | undefined, entityCode: string): boolean;
-export {};

package/dist-lib/stores/screen-registry.d.ts

@@ -1,17 +0,0 @@
-import type { ComponentType } from "react";
-/**
- * What the platform hands a custom screen when it mounts it.
- *
- * `screenCode` is the same handle every standard page already receives, so a custom
- * screen can read its own declaration (name, description, entity, route) instead of
- * restating it in code. Prefer the `useCurrentScreen()` hook - it reaches any component
- * in the tree, not just the top one - and take this prop only when the top-level
- * component itself needs the code.
- *
- * It is optional: a screen registered before this existed keeps compiling and running.
- */
-export interface CustomScreenProps {
-    screenCode?: string;
-}
-export declare function registerScreen(code: string, component: ComponentType<CustomScreenProps>): void;
-export declare function getRegisteredScreen(code: string): ComponentType<CustomScreenProps> | undefined;

package/dist-lib/stores/tabs.d.ts

@@ -1,73 +0,0 @@
-export type TabMode = "view" | "edit" | "create";
-export type TabCloseScope = "current" | "others" | "right" | "all";
-/**
- * Origin-aware Back return target. The CANONICAL stored shape: `pathname` is an
- * in-app path (no origin, starts `/` not `//`), `search` is the query string
- * WITHOUT a leading `?` (matches `TabItem.search`), `hash` carries its leading
- * `#`. Converted to the `?`-prefixed router form only at the navigate boundary.
- *
- * `hash` lives here but NOT on `TabItem` (which has no `hash` field): a closed
- * origin tab with a hash is reopened via pathname+search, and the hash is
- * applied only in the `navigate()` call. `tabId`/`title`/`icon`/`screen` are
- * hints for switching to (or reopening) the origin tab. Never stores secrets,
- * external URLs, or row data.
- */
-export interface ReturnTarget {
-    pathname: string;
-    search?: string;
-    hash?: string;
-    tabId?: string;
-    title?: string;
-    icon?: string;
-    screen?: string;
-}
-export interface TabItem {
-    id: string;
-    pathname: string;
-    search: string;
-    title: string;
-    derivedTitle?: boolean;
-    icon?: string;
-    closable: boolean;
-    area?: string;
-    screen?: string;
-    navId?: string;
-    entity?: string;
-    record?: Record<string, unknown>;
-    mode?: TabMode;
-    dirty?: boolean;
-    returnTo?: ReturnTarget | null;
-}
-interface TabState {
-    tabs: TabItem[];
-    activeTabId: string | null;
-    openTab: (tab: Omit<TabItem, "id">) => string;
-    closeTab: (id: string) => void;
-    closeTabs: (ids: string[]) => TabItem | null;
-    switchTab: (id: string) => void;
-    reorderTabs: (activeId: string, overId: string) => void;
-    findTabByPathname: (pathname: string) => TabItem | undefined;
-    updateTabTitle: (id: string, title: string, derived?: boolean) => void;
-    updateTabSearch: (id: string, search: string) => void;
-    setReturnTarget: (id: string, rt: ReturnTarget | null) => void;
-    commitTabNavigation: (id: string, patch: {
-        search: string;
-        returnTo?: ReturnTarget | null;
-    }) => void;
-    setDirty: (id: string, dirty: boolean) => void;
-    setMode: (id: string, mode: TabMode) => void;
-    updateTab: (id: string, patch: Partial<TabItem>) => void;
-    setScope: (tenantId: string | null, userId: string | null) => void;
-    hydrate: () => void;
-}
-/** True for an auth/chrome route that must never create a tab or be captured
- *  as a Back origin. Shared by `openTab` and the origin-capture path. */
-export declare function isExcludedRoute(pathname: string): boolean;
-/** A same-origin in-app path: starts `/` but not `//` (the latter is a
- *  protocol-relative external URL). The single guard reused on capture, on
- *  snapshot load (localStorage is hostile), and in the tenant-landing peek. */
-export declare function isSameOriginPath(pathname: unknown): pathname is string;
-export declare function tabIdsForCloseScope(tabs: TabItem[], activeTabId: string | null, scope: TabCloseScope, targetId?: string): string[];
-export declare function peekTenantLandingPath(tenantId: string, userId: string): string | null;
-export declare const useTabStore: import("zustand").UseBoundStore<import("zustand").StoreApi<TabState>>;
-export {};