@inspectorhub/field-ui 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,155 @@
+import { F as FieldCommand, C as CommandResult, a as CommandData, b as FieldDataSource } from './data-source-B_ogNIa3.js';
+export { A as AiAssistInput, c as AiAssistResult, d as AutoAdvanceMode, e as AutofillReason, B as BulkCreateUnitsBody, f as CollabConnector, g as CommandDataMap, h as CommandKey, i as CommentsLibraryEntry, j as CommentsLibraryQuery, k as CommentsLibraryRow, l as CommercialPresets, m as ComplianceCommand, n as CompliancePanelData, o as CostItemView, p as CostItemWrite, q as CostItemsListing, D as DateFormat, r as DefectCategory, s as DocumentReviewItemView, E as EditorData, t as EditorInspection, u as ExecuteOptions, v as FieldResources, w as FieldUrls, I as InspectionPrefs, x as InspectionUnit, M as MediaFileResult, y as MediaPoolListing, z as MediaUploader, N as NotifyOptions, G as NotifyVariant, O as OutboundCoolingWindow, P as PcaNarrative, H as PcaNarrativeData, J as PendingMediaRecord, K as PendingMediaStore, L as PhotoAnnotateMeta, Q as PhotoCropMeta, R as PhotoCropTransform, S as PhotoUploadMeta, T as PropertyMetaField, U as PsqView, V as RatingLevel, W as RelianceText, X as RepairItemOption, Y as ReportLinkTtl, Z as ReportSignoffView, _ as ResultMap, $ as ResultsDocHandle, a0 as RevisionStatus, a1 as SaveStructureTemplateCommand, a2 as SchemaItem, a3 as SchemaSection, a4 as SessionInfo, a5 as SettingsSheetData, a6 as StatutoryCoverage, a7 as StatutoryDetails, a8 as TagLibraryEntry, a9 as TemplateItemBody, aa as TemplateSchema, ab as TemplateSearchResult, ac as TemplateSnapshot, ad as TemplateSummary, ae as TimeFormat, af as UnitCommand, ag as UnitProgress, ah as VersionSnapshotContent, ai as VersionSnapshotEntry, aj as VideoFinalizeInput, ak as VideoUploadRef, al as VideoUploadTicket } from './data-source-B_ogNIa3.js';
+import * as react from 'react';
+import { ReactNode } from 'react';
+import 'yjs';
+
+/**
+ * Host-supplied UI, injected through `FieldDataSourceProvider` rather than read
+ * from the data source: the package renders the entry point, the host owns the
+ * implementation.
+ */
+interface FieldHostSlots {
+    /** The theme switch shown in the header (the web host passes `ThemeSegmentControl`). Absent hides it. */
+    renderThemeControl?: (props: {
+        className?: string;
+    }) => ReactNode;
+    /**
+     * PDF export, kept in the host (it needs the host's download machinery).
+     * `run` starts the export for the inspection; the rest is what the header
+     * reads off `usePdfExport`. Absent hides the PDF entry points.
+     */
+    pdf?: {
+        run(inspectionId: string): void;
+        busy: boolean;
+        /** The last failure's sentence, or null. */
+        error: string | null;
+        /** Button text: the host's `pdfActionLabel`, which swaps in "Generating" / "Retry in N s". */
+        actionLabel(defaultLabel: string): string;
+    };
+    /**
+     * The human check that gates an outbound send (publish). Resolves `true` when the person may go on (the
+     * check passed, or none is due) and `false` when they cancelled it. Read it through `useFieldEnsureHuman`,
+     * which hands back a stable function.
+     *
+     * FAIL-CLOSED: a host that provides neither this nor `humanCheck: 'not-required'` gets a check that refuses
+     * every send and tells the person why. A forgotten slot must never turn the gate off; the client check is the
+     * only gate on publishing, so skipping it has to be a decision the host writes down.
+     */
+    ensureHuman?: () => Promise<boolean>;
+    /**
+     * The explicit opt-out of the human check, for a host that has none by design (a native shell with its own
+     * signed-in session). Only this exact value lets sends through without `ensureHuman`; it is not a default.
+     */
+    humanCheck?: 'not-required';
+    /**
+     * The unsaved-changes guard: a component the editor mounts once, which watches `atRisk` and, while it is
+     * true, stops the person leaving the page without asking. The host owns the mechanism (a router blocker, the
+     * browser's close prompt) and renders its own confirmation. Absent means leaving is never intercepted.
+     */
+    renderUnsavedGuard?: (props: {
+        atRisk: boolean;
+    }) => ReactNode;
+    /** Told which layout band the browser really shows (after mount, and on change); a host that remembers it returns it as `EditorData.initialLayout`. */
+    onLayoutObserved?: (layout: 'phone' | 'tablet' | 'desktop') => void;
+}
+
+interface FieldDataSourceProviderProps {
+    dataSource: FieldDataSource;
+    /** Host-supplied UI (theme control, PDF export). Absent slots hide their entry points. */
+    slots?: FieldHostSlots;
+    children?: ReactNode;
+}
+declare function FieldDataSourceProvider({ dataSource, slots, children }: FieldDataSourceProviderProps): react.JSX.Element;
+/** The data source of the nearest provider. Throws outside one: a silent null would fail much later. */
+declare function useFieldDataSource(): FieldDataSource;
+/** The host-supplied UI slots; an empty object when the provider was given none. */
+declare function useFieldSlots(): FieldHostSlots;
+/**
+ * The host's human check as one stable function, FAIL-CLOSED.
+ *
+ * - `slots.ensureHuman` present: that function.
+ * - `slots.humanCheck === 'not-required'` (the host's explicit opt-out): answers `true` at once.
+ * - Neither: refuses (`false`) and shows the person why, because a host that forgot the slot must not
+ *   silently lose the check. The caller treats `false` as "do not send".
+ *
+ * The function keeps its identity across renders for as long as the slot and data source do.
+ */
+declare function useFieldEnsureHuman(): () => Promise<boolean>;
+/**
+ * What `run` answers. `ignored: true` means the call was dropped because another
+ * command of this hook was still in flight; nothing was sent and the caller must
+ * treat it as a no-op (not as a failure to report).
+ */
+type IgnoredRun = {
+    ok: false;
+    ignored: true;
+    error?: undefined;
+};
+type FieldRunResult<D> = CommandResult<D> | IgnoredRun;
+/**
+ * True when `run` dropped the call because another command of this hook was in flight. Check this FIRST:
+ * an ignored call is neither success nor failure (the first request is still running), so a consumer that
+ * toasts an error or rolls back on `!ok` would undo work that is about to succeed.
+ */
+declare function isIgnored<D>(result: FieldRunResult<D>): result is IgnoredRun;
+interface FieldCommandRunner {
+    run<C extends FieldCommand>(cmd: C): Promise<FieldRunResult<CommandData<C>>>;
+    /** True from the call until the answer settles. Render state only; the guard is synchronous and separate. */
+    busy: boolean;
+    /**
+     * The guard itself, read synchronously: true from the moment a `run` started (in the same frame, before any
+     * render) until it settles. Use it to decide, BEFORE changing UI state, whether a `run` would be dropped
+     * (an optimistic update that a dropped call must not make). It is the same ref `run` tests, not a second
+     * guard: `run` stays the only thing that can start a request.
+     */
+    isBusy(): boolean;
+}
+/**
+ * The guarded write channel: the only caller of `FieldDataSource.execute` in the
+ * package. It reproduces `useGuardedSubmit` (app/hooks/useGuardedSubmit.ts):
+ *
+ * - Same-frame guard. `inFlight` is a ref set synchronously, so two `run` calls
+ *   in one frame send ONE request; the second answers `{ ok: false, ignored: true }`.
+ * - Idempotency key. Minted on the first attempt, HELD across a retry of a failed
+ *   attempt, ROTATED after an `ok` answer. The rotation is written into the ref
+ *   before the guard is released, so no call can ever carry a spent key. Unlike the
+ *   host hook (one key per hook), the held key is tied to the request (inspection
+ *   plus the whole command): a different request mints its own, so a failed
+ *   `unit:delete` of one row cannot make the delete of another row read as its replay.
+ * - `busy` mirrors the in-flight state for rendering.
+ * - After unmount no state is set, but the pending promise still settles.
+ *
+ * A host `execute` that rejects is reported as `{ ok: false, error }` and counts as
+ * a failed attempt (the key is held). Use one hook per write surface, as with
+ * `useGuardedSubmit`.
+ */
+declare function useFieldCommand(inspectionId: string): FieldCommandRunner;
+
+/**
+ * Pin the package to one locale, explicitly.
+ *
+ * Use this from a host that has no per-request locale scope: a native shell, a
+ * test, a single-user browser app. An unknown tag falls back to the base locale
+ * rather than throwing, because a locale the catalogue does not carry is a
+ * configuration gap and must not blank the editor. Calling this also detaches
+ * any source installed with `bindFieldLocaleSource`.
+ *
+ * On a server that renders several requests at once, do NOT use this: it writes
+ * a module-level variable that every in-flight render reads. Bind a
+ * request-scoped source instead.
+ */
+declare function setFieldLocale(locale: string): void;
+/**
+ * Make the package read its locale from the host on every message call.
+ *
+ * The host passes the same function its own messages use (on the web, the app
+ * runtime's `getLocale`, which reads the request-scoped store on the server and
+ * `<html lang>` or the cookie in the browser). The package then agrees with the
+ * app by construction, with no copy to go stale and no shared mutable variable
+ * between concurrent server renders. `null` restores the package's own variable.
+ */
+declare function bindFieldLocaleSource(read: (() => string) | null): void;
+
+export { CommandData, CommandResult, FieldCommand, FieldDataSource, FieldDataSourceProvider, bindFieldLocaleSource, isIgnored, setFieldLocale, useFieldCommand, useFieldDataSource, useFieldEnsureHuman, useFieldSlots };
+export type { FieldCommandRunner, FieldDataSourceProviderProps, FieldHostSlots, FieldRunResult, IgnoredRun };