@declarion/react 0.60.0 → 0.63.0

package/dist-lib/lib/screen-back.d.ts

@@ -1,70 +0,0 @@
-import { type ReturnTarget, type TabItem } from "../stores/tabs.d.ts";
-/** Drop a leading `?` so a search string matches the canonical `TabItem.search`
- *  / `ReturnTarget.search` form (stored WITHOUT `?`). Empty in -> empty out. */
-export declare function stripLeadingQuestion(search: string | undefined | null): string;
-/** Re-attach the leading `?` for the router/`navigate` form, or `undefined`
- *  when there is no query. The inverse of `stripLeadingQuestion`. */
-export declare function toRouterSearch(search: string | undefined): string | undefined;
-/** The current location at navigate time (canonical: `search` may carry `?`,
- *  `hash` carries `#`). Sourced from `window.location` at the click. */
-export interface CaptureLocation {
-    pathname: string;
-    search?: string;
-    hash?: string;
-}
-/**
- * Build the return target to stamp on the DESTINATION tab when navigating from
- * `current` to `destinationPathname`. Returns `undefined` (no capture) when:
- *   - the current path is not a same-origin in-app route,
- *   - the current path is an excluded (auth) route,
- *   - the destination shares the current PATHNAME (self guard) -
- *     a same-screen, different-query link must not self-stamp a Back.
- *
- * `originTab` supplies metadata (id/title/icon/screen) for switching to or
- * reopening the origin; only the current location drives pathname/search/hash.
- */
-export declare function captureReturnTarget(current: CaptureLocation, destinationPathname: string, originTab?: Pick<TabItem, "id" | "title" | "icon" | "screen">): ReturnTarget | undefined;
-/** The Back visibility intent, derived from a tab's `returnTo` alone (no tab
- *  list needed). `hasOriginBack` drives an origin Back affordance;
- *  `allowFallbackBack` permits a screen's static/parent fallback (false ONLY
- *  for a menu-cleared `null`). */
-export interface BackVisibility {
-    hasOriginBack: boolean;
-    allowFallbackBack: boolean;
-}
-/**
- * Interpret the tri-state `returnTo` for Back VISIBILITY:
- *   - embed enabled -> never an origin Back; fallback allowed (embed has no tabs),
- *   - `null` (menu-cleared) -> no origin Back AND no fallback (a menu-opened
- *     screen has nowhere to return),
- *   - a valid origin object -> origin Back,
- *   - `undefined` / invalid object (deep-link) -> no origin Back, fallback allowed.
- */
-export declare function resolveBackVisibility(returnTo: ReturnTarget | null | undefined, embedEnabled: boolean): BackVisibility;
-/** The resolved Back destination. `live` = the origin tab is still open (switch
- *  to it); `reopen` = the origin tab was closed (reopen it). Both navigate to
- *  the CAPTURED snapshot (pathname+search+hash). */
-export interface ResolvedBack {
-    kind: "live" | "reopen";
-    tabId?: string;
-    pathname: string;
-    search?: string;
-    hash?: string;
-    title?: string;
-    icon?: string;
-    screen?: string;
-}
-/**
- * Resolve the Back DESTINATION from a tab's `returnTo` and the live tab list.
- * Returns `null` when there is no valid origin (the caller then uses its
- * fallback). The origin tab (live by `tabId`, else by `pathname`) decides only
- * SWITCH vs REOPEN; the destination URL is always the CAPTURED snapshot. Embed
- * yields `null` (Back is fallback-only in embed; no tab ops).
- *
- * The captured `returnTo` wins over the live tab's CURRENT search. Custom
- * screens (Compare, dashboards) do not mirror their URL into the tab store, so
- * the live search would lose URL-encoded state. The captured `returnTo` is
- * exact at drill time ("where I came from"), so it is the single source of
- * truth for the destination URL - no per-screen search mirror needed.
- */
-export declare function resolveBackTarget(returnTo: ReturnTarget | null | undefined, tabs: TabItem[], embedEnabled: boolean): ResolvedBack | null;

package/dist-lib/lib/scroll-restoration.d.ts

@@ -1,90 +0,0 @@
-/** The default deep-state bag key under which a screen's scroll anchor is
- *  stored. A screen with one scroll container uses this; a screen with several
- *  passes distinct keys. */
-export declare const SCROLL_STATE_KEY = "scroll";
-/**
- * A saved scroll position. `key` is the stable key of the row at the top of the
- * viewport (empty when the container had no rows / is non-virtualized); `delta`
- * is the sub-row pixel offset; `offset` is the raw scroll offset kept as a
- * last-resort fallback when the anchor row is gone.
- */
-export interface ScrollAnchor {
-    key: string;
-    delta: number;
-    offset: number;
-}
-/** The minimal virtualizer surface the seam needs. A
- *  `Virtualizer<HTMLElement, Element>` is structurally assignable; a test can
- *  pass a fake. */
-export interface ScrollableVirtualizer {
-    scrollOffset: number | null;
-    getVirtualItemForOffset: (offset: number) => {
-        index: number;
-        start: number;
-    } | undefined;
-    getOffsetForIndex: (index: number, align?: "start") => readonly [number, unknown] | undefined;
-    getTotalSize: () => number;
-    scrollToOffset: (offset: number, opts?: {
-        align?: "start";
-        behavior?: "auto";
-    }) => void;
-}
-/**
- * Capture the scroll anchor at `scrollOffset`. `topItem` is the virtual item at
- * the top of the viewport (`getVirtualItemForOffset(scrollOffset)`); `rowKeys`
- * maps its index to a stable row key. Returns an anchor with an empty `key`
- * (raw-offset-only) when there is no top item or no key for it. Pure.
- */
-export declare function captureScrollAnchor(scrollOffset: number, topItem: {
-    index: number;
-    start: number;
-} | undefined, rowKeys: string[]): ScrollAnchor;
-/**
- * Resolve the scroll offset to restore to, from a saved `anchor`, the CURRENT
- * `rowKeys`, an `offsetForIndex` accessor (the virtualizer's measured start of a
- * row), and the current `totalSize` (for clamping). Pure and testable.
- *
- * Fallback chain (Decision #17): anchor row found -> its measured start + delta;
- * anchor row gone (deleted / filtered out) -> clamped raw offset; unusable
- * offset -> top (0). Returns null when there is nothing saved.
- */
-export declare function resolveScrollOffset(anchor: ScrollAnchor | undefined, rowKeys: string[], offsetForIndex: (index: number) => number | undefined, totalSize: number): number | null;
-/** Read the saved raw scroll offset for the current page ONCE, for seeding a
- *  virtualizer's `initialOffset` (read-once at init). Returns 0 when none /
- *  retention off. The full anchor re-restore happens after rows measure. */
-export declare function useSavedScrollOffset(stateKey?: string): number;
-/**
- * Bind scroll save + anchor-row restore for a VIRTUALIZED list to the retained
- * page keyed by the live canonical URL.
- *
- * - Restore: once per pageKey, after `rowKeys` first become non-empty, scrolls
- *   to `resolveScrollOffset(...)` (anchor row -> clamped raw -> top).
- * - Save: a throttled scroll listener captures the top-of-viewport anchor and
- *   writes it imperatively (no re-render); the final position flushes on
- *   unmount / pageKey change to the DEPARTING view's own URL (tracked via a
- *   per-render ref).
- *
- * `enabled` (default true) lets a caller gate the seam; when false it is inert.
- */
-export declare function useVirtualScrollRestoration(opts: {
-    virtualizer: ScrollableVirtualizer | null;
-    scrollElementRef: {
-        current: HTMLElement | null;
-    };
-    rowKeys: string[];
-    stateKey?: string;
-    enabled?: boolean;
-}): void;
-/**
- * Scroll save + restore for a PLAIN (non-virtualized) scroll container - the
- * detail page. Stores the raw `scrollTop` (no anchor rows to key by) under the
- * live canonical URL; restores after first layout; saves throttled-on-scroll +
- * on unmount flush.
- */
-export declare function usePlainScrollRestoration(opts: {
-    scrollElementRef: {
-        current: HTMLElement | null;
-    };
-    stateKey?: string;
-    enabled?: boolean;
-}): void;

package/dist-lib/lib/size-value.d.ts

@@ -1,16 +0,0 @@
-import type { SizeValue } from "../types/schema.d.ts";
-export type ParsedSizeValue = {
-    kind: "weight";
-    value: number;
-} | {
-    kind: "px";
-    value: number;
-} | {
-    kind: "auto";
-} | {
-    kind: "fill";
-};
-export declare function parseSizeValue(raw: SizeValue | undefined): ParsedSizeValue | null;
-export declare function isValidSizeValue(raw: SizeValue | undefined): boolean;
-export declare function sizeValueToCSS(parsed: ParsedSizeValue): string;
-export declare function normalizeSizeValue(raw: SizeValue | undefined, defaultValue: ParsedSizeValue): ParsedSizeValue;

package/dist-lib/lib/sort.d.ts

@@ -1,72 +0,0 @@
-export type SortDir = "asc" | "desc";
-export type SortNulls = "first" | "last";
-export interface SortCol {
-    field: string;
-    dir: SortDir;
-    nulls?: SortNulls;
-}
-/**
- * Parse a sort expression string into a list of SortCol entries.
- *
- * Tolerant:
- *   - empty/null/undefined → []
- *   - missing direction defaults to "asc"
- *   - missing nulls segment is left undefined (system default applies server-side)
- *   - unknown nulls literal is dropped (server is the strict authority)
- *   - empty fields between commas are skipped
- */
-export declare function parseSort(s: string | null | undefined): SortCol[];
-/**
- * Filter a raw sort URL string so $property.* segments (not yet sortable)
- * don't reach the backend's strict parser. EVERY OTHER token passes through
- * unchanged - including malformed grammar like `:nulls_middle` or extra
- * colons - so the backend can return a typed ValidationError and the SDK
- * surfaces the error to the user. Grammar violations are NOT silently
- * rewritten on the client.
- */
-export declare function stripUnsupportedSortSegments(s: string | null | undefined): string | undefined;
-/**
- * Serialize a list of SortCol entries back to the canonical string form.
- * Round-trips losslessly with parseSort for any valid input.
- */
-export declare function serializeSort(cols: SortCol[]): string;
-/**
- * Server-enforced cap. Mirrored on the client so
- * we never POST a sort the server will reject with HTTP 400.
- */
-export declare const MAX_SORT_COLS = 5;
-/**
- * Shift-click on a column header.
- *
- *   - field already in `prev`  → remove it (toggle off).
- *   - field not in `prev`      → append { field, dir: "asc" } to the tail.
- *
- * When the list is already at the {@link MAX_SORT_COLS} cap AND `field` is
- * not already in it, the helper refuses and returns `prev` unchanged. The
- * UI surfaces this implicitly: the "Add to multi-sort" menu item is hidden
- * once the cap is reached, and a shift-click on a brand-new column at the
- * cap is a no-op (consistent UX, matches the brief's "refuse" call).
- *
- * Nulls placement of every retained column is preserved verbatim - shift-
- * click never silently rewrites another column's NULL setting.
- *
- * Returned arrays are always new references; never mutates `prev`.
- */
-export declare function applyShiftClickSort(prev: SortCol[], field: string): SortCol[];
-/**
- * "Add to multi-sort" menu action. Adds `col` to the sort tail
- * with the caller-chosen `dir` + `nulls`. Dedupes: if `col.field` is already
- * present in `prev`, the earlier occurrence is removed and the new one
- * appended at the tail (server rejects duplicate fields).
- *
- * Refuses to grow past {@link MAX_SORT_COLS}: when appending would exceed
- * the cap AND the field is not already present, returns `prev` unchanged.
- * The menu item that drives this is hidden at the cap, so this guard exists
- * to keep the helper safe under any caller.
- */
-export declare function applyAppendSort(prev: SortCol[], col: SortCol): SortCol[];
-/**
- * "Clear sort on this column" menu action. Removes the one
- * entry matching `field` from `prev`; returns `prev` unchanged if absent.
- */
-export declare function removeSortField(prev: SortCol[], field: string): SortCol[];

package/dist-lib/lib/timestamp.d.ts

@@ -1,53 +0,0 @@
-/**
- * Wire format for outgoing datetime payloads: local wall-clock with offset,
- * e.g. "2026-04-22T15:18:00-05:00" (or "...Z" when local == UTC).
- *
- * Every API call that sends a timestamp value must go through this helper:
- * ui-actions `${now}`, TimestampField submit, quick-add defaults, status
- * history `set_at`. The offset makes the instant unambiguous for passthrough
- * fields and is stripped by the backend for fields with configured timezone.
- */
-export declare function formatWireDateTime(date?: Date): string;
-/**
- * Format an offset-aware timestamp string (e.g. "2026-03-27T14:30:00+03:00")
- * for display WITHOUT browser-local timezone conversion, applying the given
- * Intl options. The server returns timestamps already converted to the target
- * timezone - we display the wall-clock as-is:
- *  - "...Z"            -> rendered in the UTC zone.
- *  - whole-hour offset -> rendered in the matching `Etc/GMT±h` zone.
- *  - fractional offset (e.g. +05:30) -> the instant is shifted by the offset
- *    and rendered in UTC (no IANA zone exists for a bare fractional offset).
- *  - bare datetime     -> browser-local.
- *  - unparseable input -> the raw string, unchanged.
- *
- * Single source of the offset-resolution algorithm; callers (`formatOffsetTimestamp`
- * here, `TimestampField`'s display formatter) differ ONLY in the Intl options.
- */
-export declare function formatInOffsetZone(raw: string, options: Intl.DateTimeFormatOptions, language?: string): string;
-/**
- * Format an offset-aware timestamp for display WITHOUT browser-local
- * conversion.
- *
- * `DD-MM-YYYY HH:mm`, the same in every language. Deliberately NOT
- * `dateStyle: "medium"`: that renders "Aug 15, 2026" for one reader and
- * "15 авг. 2026 г." for another, so two people reading the same screen cannot
- * quote the same date to each other.
- */
-export declare function formatOffsetTimestamp(raw: string): string;
-/**
- * Relative-or-absolute timestamp formatting for the time_ago cell renderer.
- *
- * Returns a short relative phrase in `language` ("5 minutes ago", "hace 2 días")
- * when the timestamp is within 30 days of `now`, and an ISO date ("2026-01-15") when
- * older. Linear / Stripe / Datadog convention — avoids the "1y 4mo 12d ago"
- * eyesore for stable historical data.
- *
- * `absolute` is the offset-aware long form intended for the cell's hover
- * tooltip; the user always has access to the precise timestamp.
- *
- * Bare or unparseable input falls back to the raw string for both fields.
- */
-export declare function formatRelativeOrAbsolute(language: string, raw: string | Date | null | undefined, now?: Date): {
-    text: string;
-    absolute: string;
-};

package/dist-lib/lib/toast.d.ts

@@ -1,49 +0,0 @@
-import { type ToastType } from "../components/shared/toast/DeclarionToast.d.ts";
-export type { ToastType, ToastAction } from "../components/shared/toast/DeclarionToast.d.ts";
-/** Per-call toast options. Severity sets the defaults; these override them. */
-export interface ToastOptions {
-    /** Auto-dismiss after this many ms. 0 = sticky. Defaults to the variant's. */
-    duration?: number;
-    /** Force sticky (never auto-dismiss) regardless of duration. */
-    sticky?: boolean;
-    /** Trailing action button - e.g. View / Retry / Undo / Reload. */
-    action?: {
-        label: string;
-        onClick: () => void;
-    };
-    /** Correlation id, shown top-right in mono, included when the user copies. */
-    requestId?: string;
-    /** Expandable detail block (stack trace, server payload). */
-    details?: string;
-    /** Repeats sharing a `group` roll up into one toast with a ×N badge. */
-    group?: string;
-    /** Explicit id - reuse to replace an existing toast in place (idempotent). */
-    id?: string;
-}
-/** Fields a loading toast can morph into when its async work resolves. */
-export interface ToastUpdate {
-    type?: ToastType;
-    title?: string;
-    message?: string;
-    duration?: number;
-    sticky?: boolean;
-    action?: {
-        label: string;
-        onClick: () => void;
-    };
-    requestId?: string;
-    details?: string;
-}
-/** Morph an existing toast in place - the loading -> success/error path. */
-declare function update(id: string, patch: ToastUpdate): void;
-/** The app-wide toast API. Import this - not `sonner` - everywhere. */
-export declare const toast: {
-    success: (title: string, message?: string, opts?: ToastOptions) => string;
-    info: (title: string, message?: string, opts?: ToastOptions) => string;
-    warning: (title: string, message?: string, opts?: ToastOptions) => string;
-    error: (title: string, message?: string, opts?: ToastOptions) => string;
-    loading: (title: string, message?: string, opts?: ToastOptions) => string;
-    update: typeof update;
-    dismiss: (id: string) => string | number;
-    dismissAll: () => string | number;
-};

package/dist-lib/lib/ui-actions.d.ts

@@ -1,12 +0,0 @@
-import type { TextFn } from "./language.d.ts";
-import type { UIStep } from "../types/schema.d.ts";
-export interface UIActionContext {
-    row?: Record<string, unknown>;
-    params?: Record<string, unknown>;
-}
-export declare function interpolate(template: string, ctx: UIActionContext): unknown;
-export declare function executeUISteps(errorTitle: TextFn, steps: UIStep[], ctx: UIActionContext): Promise<void>;
-export declare function isUIAction(action: {
-    ui_steps?: UIStep[];
-    handler?: string;
-}): boolean;

package/dist-lib/lib/utils.d.ts

@@ -1,9 +0,0 @@
-import { type ClassValue } from "clsx";
-export declare function cn(...inputs: ClassValue[]): string;
-export declare function isModifiedClick(e: {
-    metaKey: boolean;
-    ctrlKey: boolean;
-    shiftKey: boolean;
-    altKey: boolean;
-    button: number;
-}): boolean;

package/dist-lib/lib/variants.d.ts

@@ -1,7 +0,0 @@
-import { type FilterRecord } from "./filter-evaluator";
-import type { Entity, Screen } from "../types/schema.d.ts";
-export declare function resolveEntityVariantCode(entity: Entity, record: FilterRecord): string | undefined;
-export declare function variantActionCodesForRecord(entity: Entity | undefined, record: FilterRecord): ReadonlySet<string> | undefined;
-export declare function commonVariantActionCodes(entity: Entity | undefined, records: readonly FilterRecord[]): ReadonlySet<string> | undefined;
-export declare function resolveScreenVariantCode(entity: Entity, screen: Screen, record: FilterRecord): string | undefined;
-export declare function effectiveScreenForRecord(entity: Entity | undefined, screen: Screen | undefined, record: FilterRecord): Screen | undefined;

package/dist-lib/lib/versionTracker.d.ts

@@ -1,72 +0,0 @@
-/**
- * versionTracker — central staleness-detection state for the SPA.
- *
- * Every API response carries `X-Declarion-Version: <combined-fingerprint>`
- * (set by the server's version_header middleware). The FIRST arrival
- * in a bundle's lifetime is captured as the baseline; any later
- * response with a different value triggers drift detection — the SPA
- * either silently invalidates the schema query (if only schema differs)
- * or prompts the user to reload (if assets/binary changed).
- *
- * **State is in-memory only — no sessionStorage / localStorage.** Each
- * bundle load captures its own baseline from its first response. The
- * bundle IS its own version contract; the live server's first answer
- * defines what version the bundle should consider itself. Persisting
- * across reloads is actively harmful: a stale baseline from a previous
- * bundle could override the live answer, producing a "click Reload →
- * page reloads → toast pops again" infinite loop. This is the same
- * lesson behind why `index.html` is `Cache-Control: no-cache` — the
- * bootstrap manifest must always be live, never replayed.
- *
- * Defense in depth runs three sources into the same comparator:
- *   1. observe() — header read on every API response (apiFetch hook).
- *   2. fetchProbe() — explicit GET /api/version (focus / online / 60s).
- *   3. (optional) SSE `version-changed` event from useSSE.
- *
- * Cross-tab coordination via BroadcastChannel('declarion-version') —
- * runtime IPC only, not persistence. When one tab detects drift it
- * fans the decision out so all tabs reload together (avoids the
- * half-old / half-new tab anti-pattern). Each tab still bootstraps
- * its own baseline independently.
- */
-export interface VersionDelta {
-    /** Reason the delta was emitted. Lets subscribers decide UX. */
-    kind: "schema-only" | "asset-or-binary" | "unknown";
-    /** Latest combined fingerprint observed. Drives the next baseline. */
-    observed: string;
-    /** Per-component breakdown when /api/version was reached. */
-    components?: VersionComponents;
-}
-export interface VersionComponents {
-    schema: string;
-    asset: string;
-    binary: string;
-}
-export type VersionDeltaListener = (delta: VersionDelta) => void;
-/**
- * Observe an API response. Captures the first-seen fingerprint and
- * compares subsequent ones. Idempotent — safe to call from every
- * apiFetch round-trip; backward-compatible — no-op when the header
- * is absent (older server).
- */
-export declare function observe(headers: Headers | undefined | null): void;
-/**
- * Hit /api/version with If-None-Match (cheap when nothing changed —
- * 304 with no body). On any change, emit a typed delta.
- */
-export declare function fetchProbe(): Promise<void>;
-/**
- * The reload-requiring delta observed earlier, or null. useVersionWatcher
- * re-shows the reload prompt from this on every tab focus: a dismissed
- * prompt must not leave a long-lived tab silently stale.
- */
-export declare function pendingReload(): VersionDelta | null;
-/**
- * Subscribe to drift events. Called once from useVersionWatcher; the
- * subscriber renders the UpdatePrompt (toast or silent invalidation).
- */
-export declare function subscribe(cb: VersionDeltaListener): () => void;
-/**
- * Test-only: reset internal state. Not exposed via package exports.
- */
-export declare function __resetForTests(): void;

package/dist-lib/lib/viewport-category.d.ts

@@ -1,44 +0,0 @@
-export type ViewportCategory = "phone" | "tablet" | "desktop";
-export interface ResponsiveBreakpoints {
-    phoneMax: number;
-    tabletMax: number;
-    /**
-     * The height at or below which a viewport no wider than `tabletMax` is a
-     * phone held sideways. Required, never optional: a missing bound would
-     * silently restore the width-only rule, which is the defect it exists to
-     * remove.
-     */
-    landscapePhoneMaxHeight: number;
-}
-export interface ResponsiveViewport {
-    width: number;
-    height: number;
-    touch?: boolean;
-}
-export interface ResponsiveMode {
-    category: ViewportCategory;
-    width: number;
-    height: number;
-    isPhone: boolean;
-    isTablet: boolean;
-    isDesktop: boolean;
-    touch: boolean;
-}
-export declare const DEFAULT_RESPONSIVE_BREAKPOINTS: ResponsiveBreakpoints;
-/**
- * The device class, from BOTH viewport axes.
- *
- * A phone is a device, not a width. Read from width alone, the same phone is a
- * phone upright and a tablet on its side - so rotating it swapped cards for a
- * table, sections for tabs, and the compact header for the desktop one, all at
- * once. The second clause is that device: no wider than a tablet AND short.
- *
- * Height is admitted only UNDER the tablet width ceiling, because a wide short
- * window (a 1600x480 browser, a wide embed strip) is a desktop, and a height
- * clause without the ceiling would reclassify it.
- */
-export declare function resolveViewportCategory(viewport: {
-    width: number;
-    height: number;
-    touch?: boolean;
-}, breakpoints?: ResponsiveBreakpoints): ViewportCategory;

package/dist-lib/main.d.ts

@@ -1 +0,0 @@
-import "./globals.css";