@declarion/react 0.56.0 → 0.59.0

package/dist-lib/hooks/useEntityData.d.ts

@@ -10,7 +10,7 @@ export declare function entityDataQueryKey(entity: string | undefined, params: L
 /**
  * useEntityData fetches one page-window of entity rows.
  *
- * Decoupled-count contract (docs/plans/2026-05-18-declarative-row-count.md):
+ * Decoupled-count contract:
  * this hook issues the WINDOW request only - `count: "window"`, so the
  * server returns the page of rows and never blocks on a COUNT(*). The total
  * is fetched separately by `useEntityCount`; the table renders rows the

package/dist-lib/hooks/useFilters.d.ts

@@ -1,12 +1,14 @@
 import { type FilterNode } from "../lib/filters.d.ts";
-/**
- * useFilters reads/writes the JSON `filters` URL param.
- * URL is the source of truth.
- */
-export declare function useFilters(): {
+interface FiltersInput {
+    defaults?: FilterNode[];
+}
+/** `filters=[]` and an absent parameter are different states: the first says
+ *  the caller removed every condition, the second says `defaults` apply. */
+export declare function useFilters({ defaults }?: FiltersInput): {
     filters: FilterNode[];
     filterError: string | null;
     activeCount: number;
     setFilters: (newFilters: FilterNode[]) => void;
     clearFilters: () => void;
 };
+export {};

package/dist-lib/hooks/useLanguage.d.ts

@@ -0,0 +1,4 @@
+import type { QueryClient } from "@tanstack/react-query";
+export declare function useLanguage(): string;
+export declare function useDeploymentLanguage(): string;
+export declare function reresolveLanguage(queryClient: QueryClient): Promise<void>;

package/dist-lib/hooks/useParams.d.ts

@@ -2,17 +2,8 @@ import type { ParamLookup, ParamOverride, ResolvedParam } from "../types/api.d.t
 /** `$params` subresource key on a carrier's PK-detail / write payload. */
 export declare const PARAMS_KEY = "$params";
 /**
- * useCarrierParamOverrides owns the ONE dangerous `$params` write path shared
- * by every parameter-editing surface (the tenant Parameters screen, the
- * generic ParamsBlock). `$params` is a FULL-SET write, so the rules live here,
- * once, and cannot drift between surfaces:
- *   - the current override set is ALWAYS sourced from the carrier's PK-detail
- *     response (`$params`);
- *   - a missing `$params` key on a loaded detail is a HARD ERROR
- *     (`missingParams`), never an empty set - treating it as empty would
- *     delete every override on the next save;
- *   - every save/reset composes the complete new set client-side and writes it
- *     through `<carrier>.__update`.
+ * `$params` is a FULL-SET write: a loaded detail without the key is an error
+ * (`missingParams`), never an empty set, which would delete every override.
  */
 export declare function useCarrierParamOverrides({ carrierEntityCode, rowId, enabled, onWritten, }: {
     /** Carrier entity code (the write target, e.g. "profile", "my_tenant"). */
@@ -35,20 +26,9 @@ export declare function useCarrierParamOverrides({ carrierEntityCode, rowId, ena
     save: (param: ResolvedParam, value: unknown) => Promise<void>;
     reset: (param: ResolvedParam) => Promise<void>;
 };
-/**
- * Bulk effective-value view for the admin surfaces (catalog attachment,
- * ParamsBlock, tenant Parameters screen). `resolution: "tenant"` requests the
- * tenant baseline (yaml/env/tenant only); omit for the caller's full personal
- * resolution. Disclosure-tiered server-side. Short staleTime: params are
- * push-invalidated on the server, and edits invalidate this key directly.
- */
+/** `resolution: "tenant"` reads the tenant baseline, without role and user overrides. */
 export declare function useAllParams(resolution?: "tenant"): import("@tanstack/react-query").UseQueryResult<ResolvedParam[], Error>;
 export declare function usePublicParams(): import("@tanstack/react-query").UseQueryResult<import("../types/api.d.ts").PublicParamsResponse, Error>;
-/**
- * Looks up the platform's record for a parameter without a default.
- * Returns the full ParamLookup envelope (`found`, `value`, `source`).
- * Prefer `useParam` for typical reads where the call site has a default.
- */
 export declare function useResolvedParam(code: string, options?: {
     enabled?: boolean;
 }): import("@tanstack/react-query").UseQueryResult<ParamLookup, Error>;
@@ -59,34 +39,7 @@ export declare function useEffectiveParam<T = unknown>(code: string): {
     loading: boolean;
     error: Error | null;
 };
-/**
- * Reads a parameter and substitutes a caller-supplied default when the
- * platform has no value for it. The default never crosses the wire; the
- * server only answers "do you have a value for code X?".
- *
- * Behaviour:
- *   - Platform has a value     -> `value` is the resolved value.
- *   - Platform reports no value -> `value` is `defaultValue`. Not an error.
- *   - Network / auth failure    -> `error` is set; `value` is `defaultValue`
- *     so the UI has something to render during a partial outage.
- *
- * Important: this React hook intentionally diverges from the Go-side
- * contract. In Go (`params.Get[T]`), a transport error propagates and
- * the default is NEVER used for broken infrastructure. In React, the
- * hook returns the default AND surfaces the error so a component can
- * still mount during a brownout. Callers whose parameter controls
- * security-sensitive behaviour (a feature gate that hides admin UI,
- * a permission flag, etc.) MUST check `error` and refuse to render
- * the protected branch when set - do not rely on `value` alone.
- *
- * Devs may call useParam with a code that is not yet declared in YAML;
- * the platform reports not-found and the default applies. That is by
- * design: knobs become declarable later as ops asks for tunability.
- *
- * Type T is enforced by the caller. The hook does not coerce - if the
- * stored value's shape is incompatible with T, that is a programming
- * bug at the call site to be fixed.
- */
+/** A failed read returns the default AND `error`; a gate on anything sensitive checks `error`. */
 export declare function useParam<T>(code: string, defaultValue: T): {
     value: T;
     found: boolean;

package/dist-lib/hooks/useRegisterScreenTab.d.ts

@@ -5,7 +5,7 @@ import { type Entity, type Screen } from "../types/schema.d.ts";
  * so the "open a tab for this screen" logic - and its embed guard - lives in one
  * place. Registers `route` as a tab once; `search` is captured at first
  * registration (the mirror syncs later changes), so it is excluded from the
- * effect deps. No-op when `route` is absent or embed mode is on (Invariant 8).
+ * effect deps. No-op when `route` is absent or embed mode is on.
  */
 export declare function useScreenTabRegistration(route: string | undefined, title: string, icon: string | undefined, search: string): void;
 export declare function useRegisterScreenTab(screen: Screen | undefined, entity: Entity | undefined, search: string): void;

package/dist-lib/hooks/useSSE.d.ts

@@ -11,13 +11,13 @@ export interface EntityChangedEvent {
 /**
  * Applies one coalescing window of change frames, resolving once every query it
  * touched claims no freshness it lacks - which is what lets the caller advance
- * its resume position. docs/realtime.md "Frontend Invalidation".
+ * its resume position.
  */
 export declare function applyEntityChanges(queryClient: QueryClient, events: EntityChangedEvent[], signal?: AbortSignal): Promise<void>;
 /**
  * What a write of one's OWN settles: the rows it NAMED are re-read through the
  * path a change frame takes, and `fallback` covers everything it does not
- * identify. docs/realtime.md "Frontend Invalidation".
+ * identify.
  */
 export declare function settleOwnWrite(queryClient: QueryClient, isAuthenticated: boolean, entity: string, rows: Array<Record<string, string>>, fallback: () => void): void;
 export declare function evictEntityBackedQueries(queryClient: QueryClient): void;
@@ -25,7 +25,7 @@ export declare function liveEntityChanges(queryClient: QueryClient, isAuthentica
 /**
  * What a returning tab still has to ask for, once the replay covers the rest:
  * the entities that are not `realtime: true` and the ones the relay degraded,
- * which between them are the majority of screens. docs/realtime.md.
+ * which between them are the majority of screens.
  */
 export declare function refetchQueriesReplayDoesNotCover(queryClient: QueryClient, isAuthenticated: boolean): void;
 export declare function useSSE(): void;

package/dist-lib/hooks/useTabTitle.d.ts

@@ -0,0 +1,2 @@
+import type { TabItem } from "../stores/tabs.d.ts";
+export declare function useTabTitle(): (tab: Pick<TabItem, "pathname" | "title" | "derivedTitle">) => string;

package/dist-lib/hooks/useText.d.ts

@@ -1,3 +1,3 @@
-/** Resolves a declared message by code, with the English fallback the caller states. */
-export type TextFn = (code: string, fallback: string, vars?: Record<string, string | number>) => string;
-export declare function useText(): TextFn;
+import { type TextFn } from "../lib/language.d.ts";
+export type { TextFn } from "../lib/language.d.ts";
+export declare function useText(catalog?: "messages" | "errors"): TextFn;

package/dist-lib/hooks/useVersionWatcher.d.ts

@@ -20,7 +20,7 @@
  *
  * On drift the tracker classifies the delta:
  *   • schema-only      → silent React Query invalidation of ["schema"]
- *   • asset-or-binary  → persistent toast: "Reload now" / "Later"
+ *   • asset-or-binary  → persistent toast with a "Reload now" action
  *   • unknown          → same as asset/binary (conservative reload)
  *
  * Safe to call exactly once at the App root. Subsequent calls are

package/dist-lib/hooks/useViews.d.ts

@@ -1,6 +1,26 @@
 import type { ViewItem } from "../components/list/ViewSwitcher.d.ts";
+import type { RowData } from "../types/api.d.ts";
+/** One saved-view row as the switcher and the resolver read it. */
+export declare function viewItemFromRow(row: RowData, userId?: string): ViewItem;
+/** One view by identifier. The switcher's window is bounded, so a link to an
+ *  older view resolves here instead of reading as deleted. */
+export declare function useViewById(id: string | null, userId?: string): {
+    view: ViewItem | undefined;
+    isSettled: boolean;
+};
+/** The screen's views and whether the saved half of them has arrived. */
+export interface ViewsQuery {
+    views: ViewItem[];
+    /** A failed request is settled, and so is one the browser has PAUSED for
+     *  being offline: in both the list is what it is, and a view the URL names
+     *  is not found rather than still coming. */
+    isSettled: boolean;
+    isFetching: boolean;
+    refetch: () => void;
+}
 /**
  * useViews fetches DB views for a screen and merges with system views (presets) from DSL.
  * Returns a unified list with source tagging.
  */
 export declare function useViews(screenCode: string, userId?: string): ViewItem[];
+export declare function useViewsQuery(screenCode: string, userId?: string): ViewsQuery;

package/dist-lib/index.d.ts

@@ -2,9 +2,9 @@ import "./globals.css";
 export { App } from "./app";
 export { App as Declarion } from "./app";
 export type { LocalizedString, LanguageDef, Schema, Entity, EntityField, Screen, NavNode, Action, ChildRelation, StatusDef, StatusGroupDef, PropertyDef, EnumDef, ParameterDef, StructureDef, PkValues, } from "./types/schema";
-export { OrderedMap, loc, fieldDisplayName, getPrimaryKeyFields, extractPkValues, pkValuePartsToId, pkValuesToId, pkValuesToDetailId, pkValuesFromId, resolveDetailRoute, buildDetailHrefFromId, buildEntityDetailHref, buildRowDetailHref, } from "./types/schema";
+export { OrderedMap, fieldDisplayName, getPrimaryKeyFields, extractPkValues, pkValuePartsToId, pkValuesToId, pkValuesToDetailId, pkValuesFromId, resolveDetailRoute, buildDetailHrefFromId, buildEntityDetailHref, buildRowDetailHref, } from "./types/schema";
 export type { ListResponse, DataResponse, ListMeta, ApiError, AuthUser, LoginResponse, CheckSetupResponse, ListParams, Tenant, StatusInfo, PropertyValue, PublicParam, V2Meta, Refs, V2StatusInstance, V2PropertyInstance, V2ParamInstance, V2ListResponse, V2ListParams, EnrichedRow, } from "./types/api";
-export { CURSOR_SEMANTICS_MISMATCH, CURSOR_LOCALE_CHANGED, isCursorStaleError } from "./types/api";
+export { CURSOR_SEMANTICS_MISMATCH, CURSOR_LANGUAGE_CHANGED, isCursorStaleError } from "./types/api";
 export { coerceDisplayString } from "./lib/display-value";
 export { EntityClient, RefCache, entityClient } from "./api/entities";
 export type { RowHelpers } from "./api/entities";
@@ -43,7 +43,11 @@ export type { CustomScreenProps } from "./stores/screen-registry";
 export { setIconRegistry, getIcon } from "./stores/icon-registry";
 export type { IconDef } from "./stores/icon-registry";
 export { registerLayoutWidget, getLayoutWidget, hasLayoutWidget, type LayoutWidget, type LayoutWidgetProps, } from "./components/detail-layout/widgets/registry";
-export { useUserLocale } from "./hooks/useUserLocale";
+export { useLanguage, useDeploymentLanguage, reresolveLanguage } from "./hooks/useLanguage";
+export { useText } from "./hooks/useText";
+export { pickLocalized, pluralText, textWithNodes, makeTextFn, MANDATORY_LANGUAGE } from "./lib/language";
+export type { TextFn, TextVars } from "./lib/language";
+export { failureTitle } from "./lib/failure";
 export { useTabStore, type TabItem, type ReturnTarget } from "./stores/tabs";
 export { useTabNavigate } from "./hooks/useTabNavigate";
 export { useScreenBack } from "./hooks/useScreenBack";
@@ -91,16 +95,13 @@ export { AuthShell } from "./components/pages/auth/AuthShell";
 export type { AuthShellProps } from "./components/pages/auth/AuthShell";
 export { Profile } from "./components/pages/profile/Profile";
 export { Preferences } from "./components/pages/profile/Preferences";
-export { HomeStub } from "./components/pages/home/HomeStub";
-export type { HomeStubProps } from "./components/pages/home/HomeStub";
-export { PipelineStub } from "./components/pages/pipeline/Pipeline";
-export { JobsStub } from "./components/pages/jobs/Jobs";
 export { ChangePasswordDialog } from "./components/shared/ChangePasswordDialog";
 export type { ChangePasswordDialogProps } from "./components/shared/ChangePasswordDialog";
 export { Icon, Btn, IconBtn, Pill, Kbd, Avatar, BrandGlyph, Dropdown, HoverCard, Tooltip, InfoTooltip, Chip, SectionCard, RecordIdBadge, RowField, BoolToggle, MenuItem, Check, Spinner, FieldLabel, TextInput, TextArea, Select, MultiSelect, DateInput, PasswordInput, TagsInput, JsonField, RefField, ViewField, QuickEditCell, } from "./components/primitives";
 export type { IconProps, IconName, BtnProps, BtnKind, BtnSize, IconBtnProps, PillProps, PillTone, PillSize, AvatarProps, BrandGlyphProps, DropdownProps, HoverCardProps, HoverCardAlign, TooltipProps, InfoTooltipProps, ChipProps, SectionCardProps, SectionBadge, SectionEmphasis, RecordIdBadgeProps, RowFieldProps, BoolToggleProps, MenuItemProps, CheckProps, FieldLabelProps, TextInputProps, TextAreaProps, SelectProps, MultiSelectProps, SelectOption, DateInputProps, PasswordInputProps, TagsInputProps, JsonFieldProps, RefFieldProps, RefFieldItem, ViewFieldProps, QuickEditCellProps, } from "./components/primitives";
 export { SquareImage, CircleImage, WideBanner, registerFileWidget, getFileWidget, hasFileWidget, uploadFile, discardFile, validateClientSide, formatBytes, UploadError, setImageCropper, getImageCropper, FileDraftScope, useFileDraftScope, useDraftRegistration, } from "./components/file-widgets";
 export type { FileFieldDef, FileFieldDisplay, FileFieldMode, FileWidget, FileWidgetProps, HydratedFile, UploadProgress, UploadedFile, ImageCropper, CropperOptions, CropperResult, FileDraftScopeApi, DraftEntry, } from "./components/file-widgets";
+export type { UploadCheck } from "./components/file-widgets/upload";
 export { Rail } from "./components/layout/Rail";
 export type { RailProps, RailAreaItem } from "./components/layout/Rail";
 export { Sidebar, buildSections } from "./components/layout/Sidebar";