@declarion/react 0.31.1 → 0.32.0

package/dist-lib/api/data.d.ts

@@ -7,9 +7,9 @@ export declare function listEntities(entity: string, params?: ListParams, option
 export declare function getEntity(entity: string, pkValues: PkValues | string): Promise<DataResponse>;
 export declare function createEntity(entity: string, data: Record<string, unknown>): Promise<DataResponse>;
 export declare function updateEntity(entity: string, pkValues: PkValues | string, data: Record<string, unknown>): Promise<DataResponse>;
-export declare function deleteEntity(entity: string, pkValues: PkValues | string): Promise<void>;
+export declare function deleteObject(entity: string, pkValues: PkValues | string): Promise<void>;
 export declare function encodeObjectId(pkValues: PkValues): string;
-export declare function restoreEntity(entity: string, pkValues: PkValues | string): Promise<void>;
+export declare function restoreObject(entity: string, pkValues: PkValues | string): Promise<void>;
 /** Result of POST /api/data/{entity}/export. The server streams a CSV
  *  blob; the client gets the bytes plus the server-resolved filename
  *  (parsed from Content-Disposition by apiFetchBlob, with RFC 5987
@@ -85,7 +85,7 @@ export declare function buildActionBody(params: Record<string, unknown> | undefi
 export type ActionExecutor = (code: string, body: ActionExecuteRequest) => Promise<ActionExecuteResponse>;
 /**
  * Install a test-time override for executeAction - and therefore for
- * createEntity / updateEntity / deleteEntity / restoreEntity, which all
+ * createEntity / updateEntity / deleteObject / restoreObject, which all
  * dispatch through executeAction. The @declarion/react/testing harness uses
  * this (mirroring setApiErrorReporter) to resolve actions from a fixture map
  * instead of the network. Returns the previous executor so a test can restore
@@ -100,7 +100,7 @@ export declare function setActionExecutor(fn: ActionExecutor | null): ActionExec
  * per_page / sort / filters, which a cache seed cannot know ahead of render).
  */
 export type ListEntitiesResolver = (entity: string, params: ListParams) => ListResponse | undefined;
-/** Test-time override for the single-record read seam (useEntityItem -> getEntity). */
+/** Test-time override for the single-record read seam (useObject -> getEntity). */
 export type GetEntityResolver = (entity: string, pkValues: PkValues | string) => DataResponse | undefined;
 /** Install/clear the list read seam. Returns the previous resolver. */
 export declare function setListEntitiesResolver(fn: ListEntitiesResolver | null): ListEntitiesResolver | null;

package/dist-lib/api/params.d.ts

@@ -1,7 +1,7 @@
 import type { ParamLookup, PublicParamsResponse } from "../types/api";
 /**
  * Fetches the full pre-login envelope from /api/params/public:
- * {parameters, accents, branding, meta}. Used by AuthShell to theme
+ * {parameters, accents, meta}. Used by AuthShell to theme
  * unauthenticated screens before any user context exists.
  */
 export declare function fetchPublicParams(): Promise<PublicParamsResponse>;

package/dist-lib/components/layout/Rail.d.ts

@@ -1,5 +1,5 @@
 import type { AreaDef } from "../../types/schema";
-import type { PublicBranding } from "../../types/api";
+import type { BrandingIdentity } from "../../types/api";
 export interface RailAreaItem {
     id: string;
     icon: string | undefined;
@@ -13,10 +13,10 @@ export interface RailProps {
     onCmdK: () => void;
     areas?: AreaDef[];
     /**
-     * Consumer branding from /api/params/public. When `app_logo` is present
-     * the rail's brand tile renders the consumer image; otherwise it falls
-     * back to the Declarion wordmark SVG. `app_name` drives the tooltip.
+     * Consumer branding identity. When `app_logo` is present
+     * the rail's brand tile renders the consumer image. Otherwise `app_name`
+     * supplies an initial and tooltip; with neither value the tile is empty.
      */
-    branding?: PublicBranding;
+    branding?: BrandingIdentity;
 }
 export declare function Rail({ activeArea, onPick, onToggleAI, aiOpen, onCmdK, areas, branding }: RailProps): import("react").JSX.Element;

package/dist-lib/components/layout/TopBar.d.ts

@@ -15,5 +15,7 @@ export interface TopBarProps {
     aiOpen?: boolean;
     onOpenProfile?: () => void;
     onOpenPrefs?: () => void;
+    showTenantSwitcher?: boolean;
+    showBreadcrumbs?: boolean;
 }
-export declare function TopBar({ breadcrumbs, onCrumbClick, onOpenNav, navButtonRef, showNavButton, onOpenTabs, tabsButtonRef, showTabsButton, mobileTabCount, onCmdK, onToggleAI, aiOpen, onOpenProfile, onOpenPrefs, }?: TopBarProps): import("react").JSX.Element;
+export declare function TopBar({ breadcrumbs, onCrumbClick, onOpenNav, navButtonRef, showNavButton, onOpenTabs, tabsButtonRef, showTabsButton, mobileTabCount, onCmdK, onToggleAI, aiOpen, onOpenProfile, onOpenPrefs, showTenantSwitcher, showBreadcrumbs, }?: TopBarProps): import("react").JSX.Element;

package/dist-lib/components/pages/auth/AuthShell.d.ts

@@ -4,7 +4,7 @@ export type AuthShellProps = {
     children: ReactNode;
     /**
      * Tenant slug used to compose the workspace pill. The pill renders
-     * `<tenantSlug>.<branding.workspace_domain>` only when both pieces
+     * `<tenantSlug>.<branding.identity.workspace_domain>` only when both pieces
      * are set; otherwise it is hidden. Callers are not required to
      * provide a slug — the auth shell fails closed (no pill) rather
      * than display a placeholder host.

package/dist-lib/components/pages/list/ListHeader.d.ts

@@ -33,4 +33,4 @@ export interface ListHeaderProps {
     /** Dispatch surface threaded into ResponsiveActionBar (plan §8 Task 10). */
     widgetContext: WidgetContext;
 }
-export declare function ListHeader({ title, description, total, countMode, countPending, loaded, toolbarActions, screenActionLayout, entityActionLayout, selectedIds, data, rowKey, onActionSuccess, widgetContext, }: ListHeaderProps): import("react").JSX.Element;
+export declare function ListHeader({ title, description, total, countMode, countPending, loaded, toolbarActions, screenActionLayout, entityActionLayout, selectedIds, data, rowKey, onActionSuccess, widgetContext, }: ListHeaderProps): import("react").JSX.Element | null;

package/dist-lib/components/primitives/BrandLogo.d.ts

@@ -1,6 +1,6 @@
 import type { ReactNode } from "react";
 export interface BrandLogoProps {
-    /** URL from branding.app_logo in consumer YAML. */
+    /** URL from branding.identity.app_logo. */
     appLogo?: string;
     /** Pixel edge of the rendered image. */
     size: number;

package/dist-lib/components/shared/ActionRunner.d.ts

@@ -38,6 +38,7 @@ interface ActionRunnerContextValue {
      * resolves immediately - the dialog owns its own pending UI.
      */
     run: (opts: RunActionOptions) => Promise<void>;
+    isRunning: boolean;
 }
 export declare function useActionRunner(): ActionRunnerContextValue;
 export declare function ActionRunnerProvider({ children }: {

package/dist-lib/components/shared/ObjectActionBar.d.ts

@@ -0,0 +1,29 @@
+import { type ReactNode } from "react";
+import { type ResolvedActionLayoutNode } from "../../lib/actions";
+import { type Action } from "../../types/schema";
+import { type WidgetContext } from "../../components/shared/ResponsiveActionBar";
+export type ObjectActionBarSlot = "detail" | "detail_toolbar" | "list_row" | "quick_peek";
+export type ObjectActionSelection = {
+    include: string[];
+    exclude?: never;
+} | {
+    exclude: string[];
+    include?: never;
+};
+export interface ObjectActionBarProps {
+    entity: string;
+    object: Record<string, unknown> | undefined;
+    slot: ObjectActionBarSlot;
+    screen?: string;
+    select?: ObjectActionSelection;
+    extraActions?: ReactNode;
+    onAfterRun?: (code: string, result: unknown) => void;
+}
+export interface UseObjectActionsResult {
+    nodes: ResolvedActionLayoutNode[];
+    run: (code: string, action: Action) => void | Promise<void>;
+    isBusy: boolean;
+    widgetContext?: WidgetContext;
+}
+export declare function useObjectActions({ entity: entityCode, object, slot, screen: screenCode, select, onAfterRun, }: Omit<ObjectActionBarProps, "extraActions">): UseObjectActionsResult;
+export declare function ObjectActionBar({ entity, object, slot, screen, select, extraActions, onAfterRun, }: ObjectActionBarProps): import("react").JSX.Element | null;

package/dist-lib/components/shared/PageHeader.d.ts

@@ -4,5 +4,5 @@ interface PageHeaderProps {
     backTo?: string;
     actions?: ReactNode;
 }
-export declare function PageHeader({ title, backTo, actions }: PageHeaderProps): import("react").JSX.Element;
+export declare function PageHeader({ title, backTo, actions }: PageHeaderProps): import("react").JSX.Element | null;
 export {};

package/dist-lib/components/shared/RecordHeader.d.ts

@@ -10,6 +10,7 @@ interface RecordHeaderProps {
     showBack?: boolean;
     onBack?: () => void;
     right?: ReactNode;
+    showTitle?: boolean;
 }
-export declare function RecordHeader({ icon, avatarName, title, recordId, highlights, mode, dirty, showBack, onBack, right, }: RecordHeaderProps): import("react").JSX.Element;
+export declare function RecordHeader({ icon, avatarName, title, recordId, highlights, mode, dirty, showBack, onBack, right, showTitle, }: RecordHeaderProps): import("react").JSX.Element;
 export {};

package/dist-lib/components/shared/RefreshControl.d.ts

@@ -0,0 +1,6 @@
+import type { LiveObjectResult } from "../../hooks/useLiveObject";
+export interface RefreshControlProps<T extends Record<string, unknown> = Record<string, unknown>> {
+    liveObject: Pick<LiveObjectResult<T>, "refetch" | "isFetching" | "isLoading" | "isLive">;
+    realtime?: boolean;
+}
+export declare function RefreshControl<T extends Record<string, unknown> = Record<string, unknown>>({ liveObject, realtime, }: RefreshControlProps<T>): import("react").JSX.Element;

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

@@ -0,0 +1,8 @@
+import type { PublicBranding } from "../types/api";
+export declare function useBranding(): {
+    branding: PublicBranding | undefined;
+    isLoading: boolean;
+};
+export declare function useBrandingIdentity(): import("../types/api").BrandingIdentity | undefined;
+export declare function useBrandingTheme(): import("../types/api").BrandingTheme | undefined;
+export declare function useBrandingChromeValue(): import("../types/api").BrandingChrome | undefined;

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

@@ -0,0 +1,6 @@
+import type { BrandingSurfaceFlags } from "../types/api";
+export type BrandingChromeSurface = "list" | "detail" | "record_list" | "custom";
+export interface ResolvedBrandingChrome extends BrandingSurfaceFlags {
+    isVisible: (key: keyof BrandingSurfaceFlags) => boolean;
+}
+export declare function useBrandingChrome(surface?: BrandingChromeSurface): ResolvedBrandingChrome;

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

@@ -0,0 +1,9 @@
+import type { UseQueryResult } from "@tanstack/react-query";
+import { type DataResponse, type EnrichedRow } from "../types/api";
+import type { PkValues } from "../types/schema";
+export type LiveObjectResult<T extends Record<string, unknown> = EnrichedRow> = UseQueryResult<DataResponse<T>, Error> & {
+    object: T | undefined;
+    isLive: boolean;
+    isNotFound: boolean;
+};
+export declare function useLiveObject<T extends Record<string, unknown> = EnrichedRow>(entity: string | undefined, pkValues: PkValues | string | undefined): LiveObjectResult<T>;

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

@@ -1,11 +1,11 @@
 import type { PkValues } from "../types/schema";
 import type { ActionExecuteRequest } from "../api/data";
-export declare function useCreateEntity(entityCode: string): import("@tanstack/react-query").UseMutationResult<import("..").DataResponse<Record<string, unknown>>, Error, Record<string, unknown>, unknown>;
-export declare function useUpdateEntity(entityCode: string): import("@tanstack/react-query").UseMutationResult<import("..").DataResponse<Record<string, unknown>>, Error, {
+export declare function useCreateObject(entityCode: string): import("@tanstack/react-query").UseMutationResult<import("..").DataResponse<Record<string, unknown>>, Error, Record<string, unknown>, unknown>;
+export declare function useUpdateObject(entityCode: string): import("@tanstack/react-query").UseMutationResult<import("..").DataResponse<Record<string, unknown>>, Error, {
     pkValues: PkValues | string;
     data: Record<string, unknown>;
 }, unknown>;
-export declare function useDeleteEntity(entityCode: string): import("@tanstack/react-query").UseMutationResult<void, Error, string | PkValues, unknown>;
+export declare function useDeleteObject(entityCode: string): import("@tanstack/react-query").UseMutationResult<void, Error, string | PkValues, unknown>;
 export declare function useRestoreEntity(entityCode: string): import("@tanstack/react-query").UseMutationResult<void, Error, string | PkValues, unknown>;
 export declare function useExecuteAction(entityCode?: string): import("@tanstack/react-query").UseMutationResult<import("../api/data").ActionExecuteResponse, Error, {
     actionCode: string;

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

@@ -0,0 +1,10 @@
+import { type QueryKey } from "@tanstack/react-query";
+import type { PkValues } from "../types/schema";
+/**
+ * The React Query key for a single-record read. Single source of truth for both
+ * `useObject` and a detail screen registering its PRIMARY read with its
+ * retained page (`useRegisterRetainedQuery`). For a string PK uses it directly;
+ * for a composite PK sorts the parts so key order does not fork the cache.
+ */
+export declare function objectQueryKey(entity: string | undefined, pkValues: PkValues | string | undefined): QueryKey;
+export declare function useObject(entity: string | undefined, pkValues: PkValues | string | undefined): import("@tanstack/react-query").UseQueryResult<NoInfer<import("..").DataResponse<Record<string, unknown>>>, Error>;

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

@@ -17,7 +17,7 @@ export declare function usePageStateRuntime(): void;
  * current retained page, so a kill/sweep `removeQueries` releases the cached
  * data alongside the deep state. Call from the standard pages (and custom
  * screens) with the key from the matching key-builder (`entityDataQueryKey` /
- * `cursorEntityDataQueryKey` / `entityItemQueryKey`).
+ * `cursorEntityDataQueryKey` / `objectQueryKey`).
  *
  * Pass ONLY primary heavy reads - never a shared ref/lookup query, or a
  * sibling screen that shares its key would lose it on this page's eviction.

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

@@ -5,7 +5,16 @@ export declare function usePublicParams(): import("@tanstack/react-query").UseQu
  * 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): import("@tanstack/react-query").UseQueryResult<NoInfer<ParamLookup>, Error>;
+export declare function useResolvedParam(code: string, options?: {
+    enabled?: boolean;
+}): import("@tanstack/react-query").UseQueryResult<NoInfer<ParamLookup>, Error>;
+export declare function useEffectiveParam<T = unknown>(code: string): {
+    value: T | undefined;
+    found: boolean;
+    source: ParamLookup["source"] | "public" | undefined;
+    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

package/dist-lib/index.d.ts

@@ -2,13 +2,13 @@ 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 { loc, fieldDisplayName, getPrimaryKeyFields, extractPkValues, pkValuePartsToId, pkValuesToId, pkValuesToDetailId, pkValuesFromId, resolveDetailRoute, buildDetailHrefFromId, buildEntityDetailHref, buildRowDetailHref, } from "./types/schema";
+export { OrderedMap, loc, 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 { coerceDisplayString } from "./lib/display-value";
 export { EntityClient, RefCache, entityClient } from "./api/entities";
 export type { RowHelpers } from "./api/entities";
-export { executeAction, buildActionBody, ActionBatchError, deleteEntity, restoreEntity } from "./api/data";
+export { executeAction, buildActionBody, ActionBatchError, deleteObject, restoreObject } from "./api/data";
 export type { ActionExecuteRequest, ActionExecuteResponse, ActionItemError, ActionItemSkip, } from "./api/data";
 export { Batch } from "./api/batch";
 export type { BatchOp, BatchOpResult, BatchResponse } from "./api/batch";
@@ -20,14 +20,16 @@ export { useEntityData, useEntityCount, entityDataQueryKey } from "./hooks/useEn
 export { useCursorEntityData, cursorEntityDataQueryKey, cursorEntityStableKey, } from "./hooks/useCursorEntityData";
 export type { CursorEntityDataParams, CursorEntityDataResult, } from "./hooks/useCursorEntityData";
 export { useAllEntityData } from "./hooks/useAllEntityData";
-export { useEntityItem, entityItemQueryKey } from "./hooks/useEntityItem";
+export { useObject, objectQueryKey } from "./hooks/useObject";
+export { useLiveObject } from "./hooks/useLiveObject";
+export type { LiveObjectResult } from "./hooks/useLiveObject";
 export { useActionData, useCursorActionData, actionDataQueryKey, cursorActionDataQueryKey, ACTION_DATA_KEY, ACTION_DATA_CURSOR_KEY, } from "./hooks/useActionData";
 export type { ActionListPage, CursorActionDataResult } from "./hooks/useActionData";
-export { useCreateEntity, useUpdateEntity, useDeleteEntity } from "./hooks/useMutations";
+export { useCreateObject, useUpdateObject, useDeleteObject } from "./hooks/useMutations";
 export { useDebounce } from "./hooks/useDebounce";
 export { ResponsiveModeProvider, useResponsiveMode, resolveViewportCategory, DEFAULT_RESPONSIVE_BREAKPOINTS, } from "./hooks/useResponsiveMode";
 export type { ResponsiveBreakpoints, ResponsiveMode, ResponsiveViewport, ViewportCategory, } from "./hooks/useResponsiveMode";
-export { usePublicParams, useResolvedParam, useParam } from "./hooks/useParams";
+export { usePublicParams, useResolvedParam, useEffectiveParam, useParam } from "./hooks/useParams";
 export { useSetStatus } from "./hooks/useObjectStatus";
 export { useSetProperty, useDeleteProperty } from "./hooks/useProperties";
 export { useFilters } from "./hooks/useFilters";
@@ -66,6 +68,10 @@ export { ColumnPicker } from "./components/columns/ColumnPicker";
 export { ViewSwitcher } from "./components/views/ViewSwitcher";
 export { ActionRunnerProvider, useActionRunner } from "./components/shared/ActionRunner";
 export type { RunActionOptions } from "./components/shared/ActionRunner";
+export { ObjectActionBar, useObjectActions } from "./components/shared/ObjectActionBar";
+export type { ObjectActionBarProps, ObjectActionBarSlot, ObjectActionSelection, UseObjectActionsResult, } from "./components/shared/ObjectActionBar";
+export { RefreshControl } from "./components/shared/RefreshControl";
+export type { RefreshControlProps } from "./components/shared/RefreshControl";
 export { RowMenu } from "./components/list/RowMenu";
 export type { RowMenuProps, RowMenuEntry } from "./components/list/RowMenu";
 export { QuickPeek, QEField } from "./components/list/QuickPeek";