@declarion/react 0.1.65 → 0.1.68

package/README.md

@@ -12,6 +12,38 @@ pnpm add @declarion/react
 pnpm add react react-dom
 ```
 
+## Subpath exports
+
+| Import | Purpose |
+|---|---|
+| `@declarion/react` | Main React entry — components, hooks, types |
+| `@declarion/react/styles.css` | Pre-compiled Tailwind output; import once at the SPA root |
+| `@declarion/react/vite` | Node-only Vite plugin — opt into client staleness handling at build time |
+
+## Vite plugin: build identity for client staleness handling
+
+The SDK ships with a tiny Vite plugin that emits `bundle-fingerprint.txt` next to `index.html` after every production build. The Declarion server reads it at boot and folds it into the build identity stamped on every `/api/*` response (`X-Declarion-Version`). The SDK's built-in version watcher detects drift on every API response, on focus/online/60s probe, and either silently invalidates the schema query (schema-only changes) or prompts the user to reload (asset/binary changes). Cross-tab coordination via `BroadcastChannel`.
+
+Add the plugin to your consumer app's `vite.config.ts`:
+
+```ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { declarionFingerprintPlugin } from "@declarion/react/vite";
+
+export default defineConfig({
+  plugins: [react(), declarionFingerprintPlugin()],
+});
+```
+
+That's it — there is no client API to wire by hand. The version watcher mounts itself inside `<App>`, the response-header observer is built into `apiFetch`, and the toast slot reuses the existing Sonner `<Toaster/>`. The plugin works in every Declarion deployment mode (local SDK link, npm-pinned, prebuilt prod image) since it runs at consumer build time regardless of where the SDK itself comes from.
+
+Consumers that haven't adopted the plugin yet degrade gracefully: the server logs once at boot, falls back to binary-only drift detection, and the rest of the system continues working — drift still gets detected, just classified more conservatively as "asset/binary" so the user gets a reload prompt rather than a silent invalidation.
+
+Browser support requires `BroadcastChannel` for cross-tab coordination — Chrome 54+, Firefox 38+, Safari 15.4+. In environments without it, in-tab detection still works; cross-tab fan-out is silently skipped.
+
+See [`docs/architecture.md`](https://github.com/disciplinedware/declarion/blob/main/docs/architecture.md) (section "Build identity & client staleness handling") for the full design rationale, fingerprint composition, RFC 7232 details (auth-variant ETag, weak-ETag handling), and the no-persistence invariant that prevents reload loops.
+
 ## License
 
 MIT. See `LICENSE`.

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

@@ -10,6 +10,7 @@ export type AgentContentBlock = {
 } | {
     type: "tool_result";
     id: string;
+    name?: string;
     output: unknown;
     is_error?: boolean;
 } | {
@@ -38,6 +39,14 @@ export type AgentContentBlock = {
 } | {
     type: "system";
     reason: string;
+} | {
+    type: "decision";
+    tool_use_id?: string;
+    tool_code: string;
+    decision: "approved" | "rejected";
+    decided_by?: string;
+    decided_at?: string;
+    note?: string;
 };
 export interface AgentMessage {
     id: string;
@@ -46,6 +55,7 @@ export interface AgentMessage {
     role: AgentRole;
     content: AgentContentBlock[];
     created_at: string;
+    streaming?: boolean;
 }
 export type AgentInvocationStatus = "proposed" | "pending_approval" | "approved" | "rejected" | "running" | "succeeded" | "failed" | "canceled" | "interrupted";
 export interface AgentToolInvocation {
@@ -62,7 +72,9 @@ export interface AgentToolInvocation {
         edits?: Record<string, unknown>;
     };
     result?: unknown;
-    audit_ref?: string;
+    audit_operation_id?: string;
+    reason?: string;
+    confidence?: number;
 }
 export type AgentConversationStatus = "active" | "canceling" | "interrupted" | "closed";
 export interface AgentConversation {
@@ -85,12 +97,15 @@ export interface AgentConversation {
     active_instance?: string;
 }
 export declare function createConversation(input: {
-    agent_code: string;
+    agent_code?: string;
     context?: Record<string, unknown>;
 }): Promise<AgentConversation>;
-export declare function sendMessage(text: string, conversationId: string, seq: number): Promise<AgentMessage>;
+export declare function sendMessage(text: string, conversationId: string, _seq?: number): Promise<AgentMessage>;
+export declare function sendElicitResponse(conversationId: string, _seq: number | undefined, toolUseId: string, data: Record<string, unknown>): Promise<AgentMessage>;
 export declare function approveInvocation(id: string, edits?: Record<string, unknown>): Promise<void>;
 export declare function rejectInvocation(id: string, note?: string): Promise<void>;
 export declare function cancelConversation(id: string): Promise<void>;
 export declare function listConversations(): Promise<AgentConversation[]>;
+export declare function rerunMessageTurn(conversationId: string): Promise<void>;
+export declare function listPendingInvocations(conversationId: string): Promise<AgentToolInvocation[]>;
 export declare function loadHistory(conversationId: string): Promise<AgentMessage[]>;

package/dist-lib/api/auth-redirect.d.ts

@@ -0,0 +1,3 @@
+export declare function sanitizeRedirectPath(value: string | null | undefined): string;
+export declare function loginPathForRedirectPath(value: string | null | undefined): string;
+export declare function loginPathForCurrentLocation(): string;

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

@@ -9,3 +9,17 @@ export declare function createTenant(code: string, name: string): Promise<Tenant
 export declare function logout(): Promise<void>;
 export declare function listSSOProviders(tenantCode?: string): Promise<SSOProvider[]>;
 export declare function ssoAuthorizeUrl(slug: string, tenantCode?: string, redirect?: string): string;
+/**
+ * Impersonation client surface. Each call dispatches through
+ * POST /api/actions/{code} like every other auth handler. The server
+ * sets / clears the impersonation cookies via the LoginResult
+ * HTTPCustomizer; the client receives the public response shape
+ * (user / tenant / expires_at) and reloads the auth context.
+ */
+export interface ImpersonationStartResponse extends LoginResponse {
+    impersonation_session_id: string;
+    session_expires_at: string;
+}
+export declare function impersonationStart(targetUserId: string, reason: string, durationMinutes?: number): Promise<ImpersonationStartResponse>;
+export declare function impersonationStop(): Promise<LoginResponse>;
+export declare function impersonationRevoke(sessionId: string): Promise<void>;

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

@@ -1,9 +1,39 @@
+/** Signals that auth.refresh failed terminally (refresh cookie missing, token
+ *  expired/reused, session revoked). Callers MUST stop retrying and route the
+ *  user back to /login — retrying produces an infinite 401/4xx storm against
+ *  the rate-limited refresh endpoint. Distinct from generic network errors so
+ *  useSSE can branch on it. */
+export declare class RefreshDeadError extends Error {
+    status: number;
+    constructor(status: number);
+}
 export declare function ensureRefresh(): Promise<void>;
 type PersistentAuthFailureHandler = () => void;
 /** Replace the handler invoked on persistent 401. Intended for tests
  *  and non-browser consumers. Returns the previous handler so callers
  *  can restore it if needed. */
 export declare function setPersistentAuthFailureHandler(h: PersistentAuthFailureHandler): PersistentAuthFailureHandler;
+/** Returns the currently registered persistent-auth-failure handler. useSSE
+ *  reads this lazily so a setPersistentAuthFailureHandler() call from a test
+ *  is observed by the SSE retry loop without re-importing the module. */
+export declare function getPersistentAuthFailureHandler(): PersistentAuthFailureHandler;
+export type ApiErrorReport = {
+    status: number;
+    code: string;
+    message: string;
+};
+type ApiErrorReporter = (report: ApiErrorReport) => void;
+/** Replace the reporter invoked for every non-2xx response. Returns the
+ *  previous reporter so callers can restore it. Tests should install a
+ *  spy or no-op via this hook instead of stubbing `console.error`. */
+export declare function setApiErrorReporter(r: ApiErrorReporter): ApiErrorReporter;
 export declare function apiFetch<T>(path: string, options?: RequestInit): Promise<T>;
+export interface BlobResponse {
+    blob: Blob;
+    filename: string;
+    headers: Headers;
+}
+export declare function apiFetchBlob(path: string, options?: RequestInit): Promise<BlobResponse>;
+export declare function parseContentDispositionFilename(headers: Headers): string;
 export declare function callHandler<R = unknown>(code: string, args?: unknown): Promise<R>;
 export {};

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

@@ -1,11 +1,23 @@
 import type { ListParams, ListResponse, DataResponse } from "../types/api";
 import type { PkValues } from "../types/schema";
+import type { ExportRequest } from "../components/pages/exportRequest";
 export declare function listEntities(entity: string, params?: ListParams): Promise<ListResponse>;
 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 restoreEntity(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
+ *  filename* preferred). Triggering the actual download (anchor click)
+ *  is the caller's job — separation lets ExportMenu show the bytes in a
+ *  toast when the browser blocks the download. */
+export interface ExportResponse {
+    blob: Blob;
+    filename: string;
+}
+export declare function exportEntities(entity: string, body: ExportRequest): Promise<ExportResponse>;
 /**
  * Action request body is flat: top-level keys are handler params. The only
  * reserved control key is `_ids` (array of object IDs for single/batch

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

@@ -2,8 +2,25 @@ export type SSEEvent = {
     type: "entity_changed";
     entity: string;
     ids: string[];
+    objects?: Array<{
+        object_id?: string;
+        pk?: Record<string, string>;
+    }>;
     action: "created" | "updated" | "deleted" | "restored";
 } | {
     type: "session_refresh";
 };
+export declare const agentBus: EventTarget;
+export declare const AGENT_FRAME_EVENT = "agent-frame";
+export declare const AGENT_MESSAGE_CHANGED_EVENT = "agent-message-changed";
+export interface AgentFrameDetail {
+    convId: string;
+    kind: string;
+    turnId?: string;
+    payload?: Record<string, unknown>;
+}
+export declare function emitAgentFrame(detail: AgentFrameDetail): void;
+export declare class SSEAuthError extends Error {
+    constructor();
+}
 export declare function streamEvents(signal?: AbortSignal): AsyncGenerator<SSEEvent>;

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

@@ -1,11 +1,17 @@
-import type { PublicParamsResponse, ResolvedParam } from "../types/api";
+import type { ParamLookup, PublicParamsResponse } from "../types/api";
 /**
  * Fetches the full pre-login envelope from /api/params/public:
- * {parameters, accents, branding}. Used by AuthShell to theme
+ * {parameters, accents, branding, meta}. Used by AuthShell to theme
  * unauthenticated screens before any user context exists.
  */
 export declare function fetchPublicParams(): Promise<PublicParamsResponse>;
-export declare function fetchParam(code: string): Promise<ResolvedParam>;
+/**
+ * Looks up a single parameter from the platform. Always returns a
+ * `ParamLookup`; `found:false` signals "no value, use your default".
+ * Network/auth failures still throw - "missing" is normal, "broken"
+ * is an error.
+ */
+export declare function fetchParam(code: string): Promise<ParamLookup>;
 /**
  * Persist a parameter override at user scope. Writes via the existing
  * subresource $params channel on the user entity (PATCH /api/data/user).

package/dist-lib/components/agents/AgentChatPanel.d.ts

@@ -2,5 +2,6 @@ export interface AgentChatPanelProps {
     open: boolean;
     onClose: () => void;
     context?: string;
+    title?: string;
 }
-export declare function AgentChatPanel({ open, onClose, context }: AgentChatPanelProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function AgentChatPanel({ open, onClose, context, title }: AgentChatPanelProps): import("react/jsx-runtime").JSX.Element | null;

package/dist-lib/components/fields/EmailField.d.ts

@@ -1,2 +1,2 @@
 import type { FieldRendererProps } from "./index";
-export declare function EmailField({ value, mode, onChange }: FieldRendererProps): import("react/jsx-runtime").JSX.Element;
+export declare function EmailField({ value, onChange }: FieldRendererProps): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/fields/PhoneField.d.ts

@@ -0,0 +1,2 @@
+import type { FieldRendererProps } from "./index";
+export declare function PhoneField({ value, onChange }: FieldRendererProps): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/fields/RichTextField.d.ts

@@ -0,0 +1,2 @@
+import type { FieldRendererProps } from "./index";
+export declare function RichTextField(props: FieldRendererProps): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/fields/UrlField.d.ts

@@ -1,2 +1,2 @@
 import type { FieldRendererProps } from "./index";
-export declare function UrlField({ field, value, mode, onChange }: FieldRendererProps): import("react/jsx-runtime").JSX.Element;
+export declare function UrlField({ value, onChange }: FieldRendererProps): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/fields/cells/factories/badge.d.ts

@@ -0,0 +1,2 @@
+import type { CellFactory } from "../registry";
+export declare const badgeFactory: CellFactory;

package/dist-lib/components/fields/cells/factories/boolPill.d.ts

@@ -0,0 +1,2 @@
+import type { CellFactory } from "../registry";
+export declare const boolPillFactory: CellFactory;

package/dist-lib/components/fields/cells/factories/code.d.ts

@@ -0,0 +1,2 @@
+import type { CellFactory } from "../registry";
+export declare const codeFactory: CellFactory;

package/dist-lib/components/fields/cells/factories/email.d.ts

@@ -0,0 +1,2 @@
+import type { CellFactory } from "../registry";
+export declare const emailFactory: CellFactory;

package/dist-lib/components/fields/cells/factories/host-icons.d.ts

@@ -0,0 +1,9 @@
+import { type FC, type SVGProps } from "react";
+type IconFC = FC<SVGProps<SVGSVGElement>>;
+export interface HostIconProps {
+    /** Canonical (after-www) hostname; pass null/empty to render the globe. */
+    domain: string | null | undefined;
+}
+export declare function HostIcon({ domain }: HostIconProps): React.ReactElement;
+export declare const GENERIC_GLOBE: IconFC;
+export {};

package/dist-lib/components/fields/cells/factories/link.d.ts

@@ -0,0 +1,2 @@
+import type { CellFactory } from "../registry";
+export declare const linkFactory: CellFactory;

package/dist-lib/components/fields/cells/factories/markdown.d.ts

@@ -0,0 +1,2 @@
+import type { CellFactory } from "../registry";
+export declare const markdownFactory: CellFactory;

package/dist-lib/components/fields/cells/factories/money.d.ts

@@ -0,0 +1,2 @@
+import type { CellFactory } from "../registry";
+export declare const moneyFactory: CellFactory;

package/dist-lib/components/fields/cells/factories/multilangInline.d.ts

@@ -0,0 +1,2 @@
+import type { CellFactory } from "../registry";
+export declare const multilangInlineFactory: CellFactory;

package/dist-lib/components/fields/cells/factories/nextRun.d.ts

@@ -0,0 +1,2 @@
+import type { CellFactory } from "../registry";
+export declare const nextRunFactory: CellFactory;

package/dist-lib/components/fields/cells/factories/number.d.ts

@@ -0,0 +1,2 @@
+import type { CellFactory } from "../registry";
+export declare const numberFactory: CellFactory;

package/dist-lib/components/fields/cells/factories/passwordMask.d.ts

@@ -0,0 +1,2 @@
+import type { CellFactory } from "../registry";
+export declare const passwordMaskFactory: CellFactory;

package/dist-lib/components/fields/cells/factories/phone.d.ts

@@ -0,0 +1,2 @@
+import type { CellFactory } from "../registry";
+export declare const phoneFactory: CellFactory;

package/dist-lib/components/fields/cells/factories/refLink.d.ts

@@ -0,0 +1,2 @@
+import type { CellFactory } from "../registry";
+export declare const refLinkFactory: CellFactory;

package/dist-lib/components/fields/cells/factories/richTextPreview.d.ts

@@ -0,0 +1,2 @@
+import type { CellFactory } from "../registry";
+export declare const richTextPreviewFactory: CellFactory;

package/dist-lib/components/fields/cells/factories/statusPill.d.ts

@@ -0,0 +1,2 @@
+import type { CellFactory } from "../registry";
+export declare const statusPillFactory: CellFactory;

package/dist-lib/components/fields/cells/factories/tagList.d.ts

@@ -0,0 +1,2 @@
+import type { CellFactory } from "../registry";
+export declare const tagListFactory: CellFactory;

package/dist-lib/components/fields/cells/factories/text.d.ts

@@ -0,0 +1,2 @@
+import type { CellFactory } from "../registry";
+export declare const textFactory: CellFactory;

package/dist-lib/components/fields/cells/factories/timestamp.d.ts

@@ -0,0 +1,3 @@
+import type { CellFactory } from "../registry";
+export declare const timeAgoFactory: CellFactory;
+export declare const timestampFullFactory: CellFactory;

package/dist-lib/components/fields/cells/factories/url-helpers.d.ts

@@ -0,0 +1,12 @@
+export declare const LONG_TLD: RegExp;
+export declare function looksLikeHostname(candidate: string): boolean;
+export declare function normalizeUrl(raw: string): string | null;
+export declare function parseDomain(href: string): string | null;
+/**
+ * LinkedIn is the only host we special-case. Recognized path prefixes
+ * `/in/<slug>`, `/company/<slug>`, `/school/<slug>` render as `<prefix>/<slug>`.
+ * Any other linkedin.com URL (feed, jobs, posts, bare host) falls through to
+ * the default hostname rendering.
+ */
+export declare function linkedinLabel(href: string, domain: string): string | null;
+export declare function isValidUrl(href: string): boolean;

package/dist-lib/components/fields/cells/factories/url.d.ts

@@ -0,0 +1,2 @@
+import type { CellFactory } from "../registry";
+export declare const urlFactory: CellFactory;

package/dist-lib/components/fields/cells/registry.d.ts

@@ -0,0 +1,18 @@
+import type { ReactNode } from "react";
+import type { EntityField, Entity, Screen } from "../../../types/schema";
+export type RowRecord = Record<string, unknown>;
+export type CellRenderer = (value: unknown, record: RowRecord) => ReactNode;
+export type RefsMap = Record<string, Record<string, Record<string, unknown>>>;
+export interface CellResolveCtx {
+    field: EntityField;
+    fieldName: string;
+    entity?: Entity;
+    entities?: Record<string, Entity>;
+    screens?: Record<string, Screen>;
+    refs?: RefsMap | (() => RefsMap | undefined);
+    locale: string;
+    navigate?: (href: string) => void;
+}
+export type CellFactory = (ctx: CellResolveCtx) => CellRenderer;
+export declare const REGISTRY_WIDGETS: readonly string[];
+export declare function resolveCellRenderer(ctx: CellResolveCtx): CellRenderer;

package/dist-lib/components/fields/index.d.ts

@@ -1,7 +1,9 @@
-import type { EntityField } from "../../types/schema";
+import type { EntityField, Entity, Screen } from "../../types/schema";
+import { type FieldType } from "../../types/fieldType";
 export type RefsMap = Record<string, Record<string, Record<string, unknown>>>;
 export interface FieldRendererProps {
     field: EntityField;
+    entityCode?: string;
     fieldName: string;
     value: unknown;
     mode: "display" | "edit";
@@ -10,9 +12,13 @@ export interface FieldRendererProps {
     refs?: RefsMap;
     fill?: boolean;
     compact?: boolean;
+    entity?: Entity;
+    entities?: Record<string, Entity>;
+    screens?: Record<string, Screen>;
+    navigate?: (href: string) => void;
+    locale: string;
 }
 type FieldRenderer = React.ComponentType<FieldRendererProps>;
+export declare const editRegistry: Record<FieldType, FieldRenderer>;
 export declare function renderField(props: FieldRendererProps): React.ReactNode;
-export declare function getFieldRenderer(type: string): FieldRenderer;
-export declare function hasFieldRenderer(key: string): boolean;
 export {};

package/dist-lib/components/file-widgets/CircleImage.d.ts

@@ -0,0 +1,2 @@
+import type { FileWidgetProps } from "./types";
+export declare function CircleImage(props: FileWidgetProps): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/file-widgets/DocumentCard.d.ts

@@ -0,0 +1,2 @@
+import type { FileWidgetProps } from "./types";
+export declare function DocumentCard(props: FileWidgetProps): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/file-widgets/FileList.d.ts

@@ -0,0 +1,2 @@
+import type { FileWidgetProps } from "./types";
+export declare function FileList(props: FileWidgetProps): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/file-widgets/Grid.d.ts

@@ -0,0 +1,2 @@
+import type { FileWidgetProps } from "./types";
+export declare function Grid(props: FileWidgetProps): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/file-widgets/ImageWidget.d.ts

@@ -0,0 +1,12 @@
+import { formatBytes } from "./upload";
+import type { FileWidgetProps } from "./types";
+export interface ImageWidgetVisualConfig {
+    shape: "square" | "circle" | "wide";
+    aspectRatio?: string;
+    width?: string;
+}
+export interface ImageWidgetInternalProps extends FileWidgetProps {
+    visual: ImageWidgetVisualConfig;
+}
+export declare function ImageWidget(props: ImageWidgetInternalProps): import("react/jsx-runtime").JSX.Element;
+export { formatBytes };

package/dist-lib/components/file-widgets/LabeledSlots.d.ts

@@ -0,0 +1,2 @@
+import type { FileWidgetProps } from "./types";
+export declare function LabeledSlots(props: FileWidgetProps): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/file-widgets/SquareImage.d.ts

@@ -0,0 +1,2 @@
+import type { FileWidgetProps } from "./types";
+export declare function SquareImage(props: FileWidgetProps): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/file-widgets/WideBanner.d.ts

@@ -0,0 +1,2 @@
+import type { FileWidgetProps } from "./types";
+export declare function WideBanner(props: FileWidgetProps): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/file-widgets/builtins.d.ts

@@ -0,0 +1 @@
+export declare function registerBuiltinFileWidgets(): void;

package/dist-lib/components/file-widgets/cropper.d.ts

@@ -0,0 +1,14 @@
+import type { ReactNode } from "react";
+export interface CropperOptions {
+    aspectRatio?: number;
+    file: File;
+}
+export interface CropperResult {
+    blob: Blob;
+    filename: string;
+}
+export type ImageCropper = (opts: CropperOptions) => Promise<CropperResult>;
+export declare function setImageCropper(c: ImageCropper | null): void;
+export declare function getImageCropper(): ImageCropper;
+export declare function setCropperRenderer(fn: ((node: ReactNode) => void) | null): void;
+export declare function getCropperRenderer(): ((node: ReactNode) => void) | null;

package/dist-lib/components/file-widgets/draft-scope.d.ts

@@ -0,0 +1,22 @@
+import type { ReactNode } from "react";
+export interface DraftEntry {
+    fileId: string;
+    discard: () => Promise<void> | void;
+}
+export interface FileDraftScopeApi {
+    registerDraft(entry: DraftEntry): void;
+    unregisterDraft(fileId: string): void;
+    hasDraft(fileId: string): boolean;
+    flushAllDrafts(): Promise<void>;
+    markCommitted(fileId: string): void;
+}
+export declare function FileDraftScope({ children }: {
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useFileDraftScope(): FileDraftScopeApi;
+export declare function useDraftRegistration(): {
+    register: (fileId: string, discard: () => Promise<void> | void) => void;
+    unregister: (fileId: string) => void;
+    markCommitted: (fileId: string) => void;
+    isDraft: (fileId: string) => boolean;
+};

package/dist-lib/components/file-widgets/helpers.d.ts

@@ -0,0 +1,12 @@
+import type { HydratedFile } from "./types";
+export interface FocalPoint {
+    x: number;
+    y: number;
+}
+export declare function resolveFileAltText(file: HydratedFile | null, alt: string | undefined, fallback: string): string;
+export declare function previewFileURL(file: HydratedFile): string | undefined;
+export declare function downloadFileURL(file: HydratedFile): string | undefined;
+export declare function preferredListThumbnailURL(file: HydratedFile | null, preferredDerivationKey?: string): string | undefined;
+export declare function readFocalPoint(file: HydratedFile | null): FocalPoint | null;
+export declare function focalPointObjectPosition(point: FocalPoint | null): string | undefined;
+export declare function withFocalPoint(file: HydratedFile, point: FocalPoint): HydratedFile;

package/dist-lib/components/file-widgets/host.d.ts

@@ -0,0 +1,23 @@
+import type { ReactNode } from "react";
+import type { Entity, Screen } from "../../types/schema";
+import type { FileFieldDef, FileFieldValue } from "../../types/files";
+import type { RefsMap } from "../../components/fields";
+export declare function getEntityFileField(entity: Pick<Entity, "files">, fieldName: string): FileFieldDef | undefined;
+export declare function getFileFieldValue(record: Record<string, unknown>, fieldName: string): FileFieldValue;
+export declare function getSchemaFieldValue(entity: Pick<Entity, "fields" | "files">, record: Record<string, unknown>, fieldName: string): unknown;
+export declare function serializeSchemaFieldValue(entity: Pick<Entity, "fields" | "files">, fieldName: string, value: unknown): unknown;
+export declare function resolveSchemaFieldLabel(entity: Pick<Entity, "fields" | "files">, fieldName: string, entities?: Record<string, Entity>): string;
+export declare function renderSchemaField(props: {
+    entity: Pick<Entity, "fields" | "files">;
+    entityCode?: string;
+    fieldName: string;
+    record: Record<string, unknown>;
+    mode: "display" | "edit";
+    onChange?: (value: unknown) => void;
+    refs?: RefsMap;
+    disabled?: boolean;
+    entities?: Record<string, Entity>;
+    screens?: Record<string, Screen>;
+    navigate?: (href: string) => void;
+    locale: string;
+}): ReactNode;

package/dist-lib/components/file-widgets/index.d.ts

@@ -0,0 +1,16 @@
+export { SquareImage } from "./SquareImage";
+export { CircleImage } from "./CircleImage";
+export { WideBanner } from "./WideBanner";
+export { Grid } from "./Grid";
+export { DocumentCard } from "./DocumentCard";
+export { FileList } from "./FileList";
+export { LabeledSlots } from "./LabeledSlots";
+export { registerFileWidget, getFileWidget, hasFileWidget, __resetFileWidgetRegistryForTests, } from "./registry";
+export { getEntityFileField, getFileFieldValue, getSchemaFieldValue, serializeSchemaFieldValue, resolveSchemaFieldLabel, renderSchemaField, } from "./host";
+export { buildFileFieldPatch, buildFilesPayload, collectCommittedFileIds, } from "./payload";
+export { uploadFile, discardFile, validateClientSide, formatBytes, UploadError, } from "./upload";
+export { setImageCropper, getImageCropper, setCropperRenderer, getCropperRenderer, } from "./cropper";
+export type { ImageCropper, CropperOptions, CropperResult, } from "./cropper";
+export { FileDraftScope, useFileDraftScope, useDraftRegistration, } from "./draft-scope";
+export type { FileDraftScopeApi, DraftEntry, } from "./draft-scope";
+export type { FileFieldDef, FileFieldDisplay, FileFieldMode, FileWidget, FileWidgetProps, HydratedFile, UploadProgress, UploadedFile, } from "./types";

package/dist-lib/components/file-widgets/payload.d.ts

@@ -0,0 +1,21 @@
+import type { Entity } from "../../types/schema";
+import type { FileFieldDef, FileFieldValue } from "../../types/files";
+export interface FileSetItem {
+    file_id: string;
+    filename?: string;
+    slot?: string;
+    position?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface FileFieldPatch {
+    clear?: true;
+    set?: FileSetItem[];
+}
+export declare function buildFileFieldPatch(field: FileFieldDef, value: FileFieldValue): FileFieldPatch;
+export declare function buildFilesPayload(opts: {
+    entity: Pick<Entity, "files"> & Partial<Pick<Entity, "fields">>;
+    formData: Record<string, unknown>;
+    record: Record<string, unknown> | undefined;
+    isNew: boolean;
+}): Record<string, FileFieldPatch>;
+export declare function collectCommittedFileIds(payload: Record<string, FileFieldPatch>): string[];

package/dist-lib/components/file-widgets/registry.d.ts

@@ -0,0 +1,5 @@
+import type { FileWidget } from "./types";
+export declare function registerFileWidget(code: string, widget: FileWidget): void;
+export declare function getFileWidget(code: string): FileWidget | undefined;
+export declare function hasFileWidget(code: string): boolean;
+export declare function __resetFileWidgetRegistryForTests(): void;

package/dist-lib/components/file-widgets/types.d.ts

@@ -0,0 +1,15 @@
+import type { FileFieldDef, FileFieldDisplay, FileFieldMode, FileFieldValue, HydratedFile, UploadProgress, UploadedFile } from "../../types/files";
+export type { FileFieldDef, FileFieldDisplay, FileFieldMode, FileFieldValue, HydratedFile, UploadProgress, UploadedFile, };
+export interface FileWidgetProps {
+    field: FileFieldDef;
+    fieldName: string;
+    entityCode?: string;
+    value: FileFieldValue;
+    mode: "display" | "edit";
+    onChange?: (next: FileFieldValue) => void;
+    disabled?: boolean;
+    alt?: string;
+    uploadFieldCode?: string;
+    uploadSlotCode?: string;
+}
+export type FileWidget = React.ComponentType<FileWidgetProps>;