@burojs/react 0.2.0 → 0.5.0

package/dist/types-DH3beUOO.d.cts

@@ -0,0 +1,488 @@
+
+import { AnyBlockHandle, ApplicationSnapshot, BlockLookup, Check, CheckOutcome, CheckSurface, CompiledScreen, DraftOption, EntityRef, ErasedResourceHandle, FieldIssue, FilterExpression, FixedFilterInput, FlowRun, FormBody, MessageReference, NodeState, ResourceFieldDefinition, ResourceFieldMap, ResourceHandle, ScreenEntry, ScreenFailure, ScreenPlan, ScreenSources, SourceState, StandardSchemaV1, TypeOfferState, ValidationContext, ValidationIssue, ValidationIssueSeverity, ValidationIssues } from "@burojs/core";
+//#region src/flows/inline-holder.d.ts
+/**
+ * What an inline flow placement keeps beyond the lifetime of its node (P6 3.12): the run, so that
+ * switching a tab away and back, or a re-render of the tree, neither loses what was typed nor
+ * starts a second attempt. `useFlowRun` fills `run` and `deps` through its `lease` option.
+ * @internal
+ */
+interface InlineLease {
+  /** The placement's key on its screen. */
+  readonly key: string;
+  readonly flowId: string;
+  readonly record: string;
+  /** The run the lease holds; created by the first `useFlowRun` that takes the lease. */
+  run: FlowRun | null;
+  /** What the run was built for; a change builds a new run in the lease. */
+  deps: string | null;
+  /** Whether the run was opened (its gate asked) already. */
+  opened: boolean;
+  /** The run's values when it opened, as JSON: what "dirty" is measured against. */
+  initial?: string;
+  /** The flow's label, for the guard's text when the node is not on screen. */
+  label: string;
+  /** Unsaved input, or an unresolved attempt: set by the host from the run's snapshots. */
+  dirty: boolean;
+  /** A write is in flight. */
+  locked: boolean;
+  /** How many nodes currently show this lease. */
+  mounted: number;
+}
+/**
+ * The screen-held state of inline flows (P6 3.12): one lease per placement key, and the registry of
+ * which flow-and-record slot a mounted screen holds, so a second screen showing the same record
+ * (a quick sheet over the page) draws the flow's button instead of a second form. A slot is the
+ * attempt slot of P4: `(user, flow, record)`.
+ * @internal
+ */
+interface InlineFlowHolder {
+  /**
+   * The placement's lease, created on the first call and kept; or `'held-elsewhere'` when another
+   * mounted holder already holds the slot. `user` is the signed-in user's id (`''` without one).
+   */
+  acquire(key: string, flowId: string, record: string, user?: string): InlineLease | 'held-elsewhere';
+  /** Whether the screen places `flowId` inline: the flow's own button is not drawn on it. */
+  suppressed(flowId: string): boolean;
+  /** The lease of `key` if the screen holds one (no acquisition). */
+  get(key: string): InlineLease | undefined;
+  /** Replaces the set of flows the screen places inline (by flow name). */
+  declare(flowNames: Iterable<string>): void;
+  /** Frees the lease of `key`; a run with a write in flight is disposed once that write settles (the attempt store adopts it). */
+  release(key: string): void;
+  /**
+   * Marks the holder mounted. The returned function marks it unmounted: the leases are released
+   * after the commit, unless the holder was attached again (StrictMode's simulated unmount).
+   */
+  attach(): () => void;
+  /** Tells the screen's blockers that a lease changed (dirty, locked, mounted). */
+  touch(): void;
+  subscribe(listener: () => void): () => void;
+  /** Counts every change `touch` announced: the external store's version. */
+  version(): number;
+  /**
+   * What the screen must guard for the leases whose node is not on screen: the labels of those
+   * holding unsaved input, and whether any write is in flight.
+   */
+  guarded(): {
+    readonly labels: readonly string[];
+    readonly locked: boolean;
+  };
+}
+//#endregion
+//#region src/forms/controller/placements.d.ts
+/** What the resolver knows of one placement at mount (spec 8.1, decision 35). */
+interface PlacementRuntime {
+  readonly key: string;
+  readonly block: EntityRef;
+  /** Over props, validation and `data` entries: absent > pending > failed > ready. */
+  readonly state: NodeState;
+  /**
+   * `'access'`: absent because a required prop reads a field its user may not view (P5 spec
+   * 3.6.3) — no view mounts, no block `data` is read, and the plan's reason is `access`.
+   */
+  readonly reason?: 'access';
+  readonly error?: unknown;
+  /** Whether Retry can help: a failed read, never a refused prop or a missing definition. */
+  readonly retryable: boolean;
+  /** The validated props (each schema's output), once ready. */
+  readonly props?: Readonly<Record<string, unknown>>;
+  /** The ready `data` entry values. */
+  readonly data: Readonly<Record<string, unknown>>;
+  /** A development error to report once (`block.prop-invalid`, `block.data-order`). */
+  readonly problem?: {
+    readonly code: string;
+    readonly message: string;
+  };
+  /** The block handle (the view's `t` and a test read its definition). */
+  readonly definition?: AnyBlockHandle;
+}
+//#endregion
+//#region src/checks/use-check-gate.d.ts
+interface CheckGateRequest {
+  readonly surface: CheckSurface;
+  readonly values?: Record<string, unknown>;
+  readonly saved?: Record<string, unknown>;
+  readonly record?: Record<string, unknown>;
+  readonly actionName?: string;
+  /** The screen's `with` sources the checks read, by name (P2 4.10). */
+  readonly sources?: Readonly<Record<string, SourceState>>;
+  /** An existing `action.confirm` message; becomes the dialog header. */
+  readonly header?: string | null;
+}
+interface CheckGateState {
+  /**
+   * The resource whose checks this gate evaluates. Carried in the state so the
+   * dialog rendering it can bind its translations to the same resource the
+   * rules came from: a check message's i18n key is `checks.<id>`, which only
+   * reaches the per-resource entry `resources.<name>.checks.<id>` when a
+   * resource is bound.
+   *
+   * It must travel WITH the state rather than being passed to the dialog
+   * separately — the ambient `ResourceContext` is not a substitute. Only
+   * `<RecordScreen>` and `<DeclarativeForm>` mount one, so an action gated from a
+   * LIST ROW has no ambient resource at all, and the same check would render
+   * translated on a show page and untranslated in the list. (Exactly the bug
+   * `useResolvedLabel` in `action-button.tsx` carries a comment about.)
+   *
+   * Optional because a resource-less host — `<DeclarativeForm>` builds this
+   * shape by hand — genuinely has no resource to name.
+   */
+  readonly resource?: string;
+  readonly open: boolean;
+  readonly busy: boolean;
+  readonly header: string | null;
+  readonly blockers: ValidationIssues;
+  readonly confirmable: ValidationIssues;
+  readonly proceed: () => void;
+  readonly cancel: () => void;
+}
+interface UseCheckGateResult {
+  readonly run: (request: CheckGateRequest) => Promise<'proceed' | 'cancel'>;
+  readonly state: CheckGateState;
+}
+/**
+ * Imperative pre-flight gate. `run()` evaluates the resource's checks for the
+ * surface, and resolves immediately with 'proceed' when there is nothing to say.
+ * Otherwise it opens (the host renders the dialog off `state`) and resolves once
+ * the user decides. One dialog: an existing `action.confirm` becomes its header
+ * rather than a second prompt.
+ */
+declare function useCheckGate(resource: string): UseCheckGateResult;
+//#endregion
+//#region src/forms/types.d.ts
+/** The live values map a declarative form reads from and writes to. */
+type FormValues = Record<string, unknown>;
+/**
+ * A friendly validator return, resolved through `normalizeFieldIssues` at
+ * the boundary. Reused for both per-field validators (`ResourceFieldDefinition.
+ * validators`, from `@burojs/core`) and the form-level `validate` below.
+ */
+type FormLevelValidationResult = FieldIssue | readonly FieldIssue[] | null | undefined;
+/**
+ * Cross-field / whole-form validator. Receives the full values map plus the
+ * same `{ values, field? }` context shape core's per-field `FieldValidator`
+ * uses — deliberately NOT the richer visibility/permission `FieldCtx` from
+ * the design doc's §4, since predicates and conditional visibility are
+ * Task 4. Keeping this context-free is what lets `renderHook` run this
+ * controller with no provider wrapper.
+ */
+type FormValidate = (values: FormValues, ctx: ValidationContext) => FormLevelValidationResult | Promise<FormLevelValidationResult>;
+/** A validation issue projected for display: one field, one message. */
+interface ResolvedIssue {
+  readonly field: string;
+  /** The issue's code (`required`, `string.minLength`, …): `resolveValidationMessage` keys on it. */
+  readonly code?: string;
+  readonly severity: ValidationIssueSeverity;
+  readonly message: MessageReference;
+  /**
+   * Interpolation params for a bundle-translated `message.key` (e.g. a
+   * check's `{ checkId, show, trigger }` — `evaluateChecks`, `@burojs/core`).
+   * Forwarded from the source `ValidationIssue.params` so a renderer's
+   * `t(message.key, { params })` call can fill in a `{{placeholder}}` in a
+   * registered bundle entry, mirroring `resolveValidationMessage`
+   * and `<CheckConfirmDialog>`'s own `issueText`.
+   */
+  readonly params?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Minimal event shape `handleSubmit`'s returned handler needs. Structurally
+ * compatible with a real DOM `FormEvent`, but the controller itself never
+ * imports React's DOM event types — it stays usable outside a `<form>`.
+ */
+interface SubmitEventLike {
+  readonly preventDefault?: () => void;
+}
+/**
+ * The prop bag `<Field {...form.field(name)} />` spreads, and the raw escape
+ * hatch for a hand-rolled input. Carries `resource` (derived from
+ * `i18nPrefix` via `i18nPrefixToRef`) but deliberately NOT a UI `fallback`
+ * node — `@burojs/react` has no shadcn/DOM dependency; the `<Field>` brick
+ * in `@burojs/ui-shadcn` supplies its own default fallback.
+ *
+ * `required`/`disabled`/`hidden` are RESOLVED (Task 4): `hidden` is
+ * `!evaluateVisible(field.visible, ctx, values)` (`@burojs/core`'s existing
+ * `visible` convention, reused as-is); `required`/`disabled` are each
+ * either a static boolean or a predicate `(ctx, values) => boolean`
+ * evaluated the same way — see `packages/react/src/forms/conditional.ts`.
+ */
+interface FieldBinding {
+  readonly name: string;
+  readonly value: unknown;
+  readonly onChange: (value: unknown) => void;
+  readonly onBlur: () => void;
+  readonly error?: ResolvedIssue;
+  readonly warnings: readonly ResolvedIssue[];
+  readonly required: boolean;
+  readonly disabled: boolean;
+  readonly hidden: boolean;
+  readonly resource: EntityRef;
+  readonly field: ResourceFieldDefinition;
+  /**
+   * A relation field's `filter` function, RESOLVED against the current `values` snapshot (design
+   * doc §5). `undefined` when the field declared none (or it threw / returned a non-array — the
+   * "broken predicate behaves as if never declared" convention `resolvePredicate` uses for
+   * `required`/`disabled`, see `./conditional.js`). `@burojs/ui-shadcn`'s `<Field>` hands it to
+   * the select as a prop, applied on top of the field's `candidates` (data in `meta`), so a plain
+   * `{...binding}` spread onto `<Field>` (what `<DeclarativeForm>` does) needs no extra wiring.
+   *
+   * Typed as `FixedFilterInput` (not the bare AST) so it widens together
+   * with `RelationPickerProps.fixedFilters` and
+   * `RelationPickerDialogProps.fixedFilters` downstream.
+   */
+  readonly fixedFilters?: readonly FixedFilterInput[];
+  /**
+   * A relation field's create seeds (P6-31): the top-level `eq` literals of the field's
+   * `meta.candidates`, read from the code registry's definition only, and none for a field whose
+   * candidates a granted layer chose. Never derived from `fixedFilters` or the compiled
+   * declaration, which a component or a granted layer can write.
+   */
+  readonly relationSeeds?: Readonly<Record<string, unknown>>;
+}
+/**
+ * A relation field's `filter` (design doc §5): code that returns extra filters from the form's
+ * current values, applied on top of the field's `candidates` (data, in `meta`). A static array is
+ * not a `filter` — that is `candidates`. See `readFieldFilterOpt` in `./conditional.js`.
+ */
+type RelationFilterOpt = (values: FormValues) => readonly FilterExpression<ErasedResourceHandle>[];
+/** The members every form controller exposes (values, bindings, submit). */
+interface FormControllerMembers {
+  /** Spread into `<Field/>`, or read raw for a hand-rolled input. */
+  field(name: string): FieldBinding;
+  /** The fields the plan does not make inactive, in declaration order. */
+  readonly fields: readonly FieldBinding[];
+  readonly values: FormValues;
+  /** severity 'error' issues, form-level plus per-field, from the last validation pass. */
+  readonly errors: readonly ResolvedIssue[];
+  /** severity 'warning' | 'info' issues — never block `canSubmit`. */
+  readonly warnings: readonly ResolvedIssue[];
+  /** `errors.length === 0 && !isSubmitting`. */
+  readonly canSubmit: boolean;
+  /** Current `values` vs. the baseline captured once at mount. */
+  readonly isDirty: boolean;
+  readonly isSubmitting: boolean;
+  /** The last check pass, for a host that mounts its own confirm gate. */
+  readonly checkOutcome: CheckOutcome | null;
+  handleSubmit(cb?: (values: FormValues) => unknown | Promise<unknown>): (e?: SubmitEventLike) => Promise<void>;
+  setValue(name: string, value: unknown): void;
+  reset(next?: FormValues): void;
+  /**
+   * Re-run every field's + the form's validation against the current
+   * `values` and update `errors`/`warnings`. A live seam for a renderer or
+   * adopter to call on value change (e.g. debounced) — this controller does
+   * NOT call it itself; deciding when to revalidate outside of blur/submit
+   * is the caller's job.
+   */
+  revalidate(): Promise<void>;
+}
+//#endregion
+//#region src/forms/controller/types.d.ts
+type AnyResourceHandle = ResourceHandle<any, any, any, any>;
+/** A record form: its screen comes from `compiledScreenFor`, its record from the `SourceResolver`. */
+interface UseFormControllerRecordOptions {
+  /** A canonical name, or a handle reduced to its canonical ref (never read). */
+  readonly resource: string | AnyResourceHandle;
+  readonly mode: 'create' | 'edit' | 'show';
+  /** The record's id (edit, show). */
+  readonly recordId?: string;
+  /** The accepted type of a typed create (from the route's `?type=` or the type offer). */
+  readonly type?: string;
+  /** A caller-supplied row: nothing is read. */
+  readonly record?: Record<string, unknown>;
+  /** The caller's seed tier of a create, above the field defaults and the type's defaults. */
+  readonly defaults?: Record<string, unknown>;
+  /** Default: the resource's `draft`. */
+  readonly draft?: DraftOption;
+  /** Replaces the built-in create / update mutation; receives the payload. */
+  readonly onSubmit?: (payload: Record<string, unknown>) => Promise<unknown>;
+  /**
+   * The entry the screen is compiled for (P6 3.8): `'route'` by default; a quick host passes
+   * `'quick'` so a declared quick screen plans its own body. Typed in P6-A; read from P6-B.
+   */
+  readonly entry?: ScreenEntry;
+}
+/**
+ * A resource-less form: its screen is compiled from `fields` and `body`
+ * (`compileFormScreen`), and only `onSubmit` writes.
+ */
+interface UseFormControllerFormOptions<F extends ResourceFieldMap = ResourceFieldMap> {
+  readonly fields: F;
+  /** The tree; absent, the generic one-column tree in declaration order. */
+  readonly body?: FormBody<F>;
+  /** The draft identity; `draft` without it is a development error. */
+  readonly formId?: string;
+  /** Default `'create'`; `'show'` is display only. */
+  readonly mode?: 'create' | 'edit' | 'show';
+  /** The check surface; default `'edit'` in edit mode, `'create'` otherwise. */
+  readonly surface?: CheckSurface;
+  /** Text slots key as `resources.<i18nPrefix>.…`; default `'form'`. */
+  readonly i18nPrefix?: string;
+  readonly defaults?: FormValues;
+  /** Controlled values; the form follows them and reports edits through `onChange`. */
+  readonly value?: FormValues;
+  readonly onChange?: (values: FormValues) => void;
+  readonly schema?: StandardSchemaV1;
+  readonly validate?: FormValidate;
+  readonly checks?: readonly Check[];
+  readonly onConfirmChecks?: (outcome: CheckOutcome) => Promise<'proceed' | 'cancel'>;
+  readonly draft?: DraftOption;
+  /**
+   * @internal A flow's form (P4 spec 4.4): the run `useFlowRun` created. With it — a claim the
+   * controller verifies, never a bare flag (Known finding 24) — the controller emits no
+   * `form.submit` (the run emits `flow.submit`) and keys its draft in mode `flow`.
+   */
+  readonly flowRun?: FlowRun;
+  /**
+   * @internal A flow's form: the issues its run decided (honoured only with the run's claim).
+   */
+  readonly flowIssues?: readonly ValidationIssue[];
+  /**
+   * @internal The owner's own source states a field's `meta` refs read beside the form's `values`,
+   * `scope` and `user` (P7 3.2): a flow's `record` and `args`. Honoured only with the run's claim
+   * (`flowRun`), like the flow issues: a bare option cannot put a source in front of a field.
+   */
+  readonly metaSources?: ScreenSources;
+  /** @internal The flow draft key's segments: the record, the args and selection hashes. */
+  readonly flowDraft?: {
+    readonly recordId?: string;
+    readonly argsHash?: string;
+    readonly selectionHash?: string;
+    /** The run's attempt key: a forced sign-out keeps the draft while it is unresolved. */
+    readonly attempt?: string;
+  };
+  /**
+   * @internal The trusted block catalogue the tree may place from (P4-D): a flow's form and
+   * review pass the app's (`snapshotBlockLookup` over the committed snapshot), so
+   * `l.place(appBlock)` resolves. Without it only the built-in blocks do.
+   */
+  readonly blocks?: BlockLookup;
+  /** Receives the active declared values (the payload). */
+  readonly onSubmit?: (values: FormValues) => unknown | Promise<unknown>;
+  /**
+   * The field access of a resource's fields (P5 decision 41): a form field whose name is a
+   * declared field of `resource` takes that field's `requires` and `field/*` rules, planned and
+   * projected exactly as on a record form (in edit and show the form's values are the record the
+   * rules see); any other field has none.
+   */
+  readonly access?: {
+    readonly resource: string;
+  };
+}
+/** Why a controller plans nothing and refuses to submit. */
+type FormControllerFailure = {
+  readonly kind: 'screen';
+  readonly failure: ScreenFailure;
+} | {
+  readonly kind: 'type-required';
+};
+type FormSubmitResult = {
+  readonly status: 'submitted';
+  readonly result: unknown;
+} |
+/** The write threw: `error` is what it threw; the values and the draft stay. */
+{
+  readonly status: 'failed';
+  readonly error: unknown;
+} | {
+  readonly status: 'invalid' | 'blocked' | 'cancelled' | 'refused';
+};
+/** A stored draft offered for restore. */
+interface FormDraftState {
+  readonly pending: {
+    readonly savedAt: string;
+  } | null;
+  /**
+   * Edit only: the record changed since the draft was made. The draft is
+   * still offered (the host shows `draft.recordChanged`), `restore()` is
+   * refused and `discard()` stays.
+   */
+  readonly recordChanged: boolean;
+  restore(): void;
+  discard(): void;
+}
+/**
+ * A create's `steps` wizard (P1b+P1c decision 11). Step ids are the step
+ * panels' keys (else their node ids), in order; the current step is the
+ * steps node's open panel.
+ */
+interface FormSteps {
+  readonly ids: readonly string[];
+  readonly current: string | undefined;
+  /** The steps left with Next, in the order they were completed. */
+  readonly completed: readonly string[];
+  /**
+   * Validates the current step's active fields and, when they pass, opens the
+   * next step that has an active field; whether it advanced.
+   */
+  next(): Promise<boolean>;
+  /** Opens the previous step that has an active field. */
+  back(): void;
+  /** Opens a completed step (or the current one); any other id is ignored. */
+  goTo(id: string): void;
+}
+interface FormController extends FormControllerMembers {
+  /**
+   * The compiled screen this controller plans (the accessor's object); `null`
+   * on a failure or an unknown resource. Hosts render the tree from it.
+   */
+  readonly screen: CompiledScreen | null;
+  /** `null` on a failure. */
+  readonly plan: ScreenPlan | null;
+  readonly failure: FormControllerFailure | null;
+  submit(): Promise<FormSubmitResult>;
+  readonly draft: FormDraftState;
+  /**
+   * The record the form shows or edits once it is ready (a caller's `record`,
+   * or the one the `SourceResolver` read); `undefined` in create and while
+   * the read is pending.
+   */
+  readonly record: Readonly<Record<string, unknown>> | undefined;
+  /**
+   * The sources the plan was made from, as view code reads them (P5 spec 3.6.1): `record` and
+   * `values` projected by field view, `scope`, `user`, and the screen's `with` sources. A field's
+   * `meta` refs read these, so a field P5 withholds stays pending there too.
+   */
+  readonly sources: ScreenSources;
+  /** Refetches the failed requests under these source names (a failed node's Retry). */
+  retry(sources: readonly string[]): void;
+  /**
+   * A placement at mount, by its key (a nested one by its derived key): its props validated, its
+   * `data` entries resolved; `undefined` for a key the screen does not place. `usePlacement`
+   * reads it.
+   */
+  placement(key: string): PlacementRuntime | undefined;
+  /**
+   * The number of error issues (not fields) on the `active` field leaves under
+   * the keyed node `containerKey`: a tab's, a step's or a panel's badge.
+   */
+  errorsIn(containerKey: string): number;
+  /**
+   * Registers what brings a node into view: a submit refused by validation
+   * calls, outermost first, the reveal of every container holding the first
+   * failing field, then that field leaf's own reveal (which focuses its input).
+   * `nodeId` is the compiled node's id. Returns the unregister function.
+   */
+  registerReveal(nodeId: string, reveal: () => void): () => void;
+  /**
+   * The resource's check gate (a record form): the confirm dialog a host
+   * renders while a submit waits for the user's decision; `null` for a
+   * resource-less form, whose host passes `onConfirmChecks`.
+   */
+  readonly checkGate: CheckGateState | null;
+  /**
+   * A background run of the resource's form-level `validate` is in flight (the
+   * debounced run as the user types; a submit's own run is `isSubmitting`).
+   */
+  readonly isValidating: boolean;
+  /** A create whose body holds a `steps` node: the wizard; `null` otherwise. */
+  readonly steps: FormSteps | null;
+  /**
+   * A typed create's type offer (P1b+P1c decision 24): `pending` while the
+   * offer's `scope` is, else the types on offer; `null` for any other form.
+   * A host shows it while `failure` is `type-required`.
+   */
+  readonly typeOffer: TypeOfferState | null;
+}
+//#endregion
+export { InlineFlowHolder as _, FormSubmitResult as a, FieldBinding as c, ResolvedIssue as d, CheckGateRequest as f, PlacementRuntime as g, useCheckGate as h, FormSteps as i, FormValues as l, UseCheckGateResult as m, FormControllerFailure as n, UseFormControllerFormOptions as o, CheckGateState as p, FormDraftState as r, UseFormControllerRecordOptions as s, FormController as t, RelationFilterOpt as u, InlineLease as v };
+//# sourceMappingURL=types-DH3beUOO.d.cts.map