@object-ui/fields 17.6.0 → 18.0.0

package/dist/widgets/uploadingScope.d.ts

@@ -0,0 +1,142 @@
+import * as React from 'react';
+/**
+ * An ambient "is any upload still in flight?" scope for a whole form subtree.
+ *
+ * ## Why this exists beside `onUploadingChange`, and why it is not a second contract
+ *
+ * `onUploadingChange` (ADR-0059) is a PER-WIDGET prop: a host that renders one
+ * upload control and knows its name can pass a callback and keep the answer
+ * itself. That is `ActionParamDialog`, which holds a `Record<paramName, boolean>`
+ * because it lays out its own params one by one.
+ *
+ * A record form cannot do that. Its fields are rendered by the `form` node
+ * renderer from a `fields` array — the host hands over a list of field configs
+ * and never touches the widget — and its upload widgets may sit an arbitrary
+ * number of levels down (a section, a tab, a line-items subform). There is no
+ * place in that chain where the form host can attach a per-widget callback, so
+ * a record form was left with no notion of upload state at all and could submit
+ * mid-upload: the record was written WITHOUT the attachment and reported
+ * success (objectui#10166).
+ *
+ * The scope is the aggregation, not a second producer. `useUploadingSignal` is
+ * still the ONE place a widget's in-flight state is published; it drives the
+ * host prop and this scope from that same call, so the two can never disagree.
+ * A widget reports nothing extra and knows nothing about the scope, and a host
+ * that mounts no provider (every host on `main` today) is unaffected — the
+ * context read answers `null` and the reporting hook is inert.
+ *
+ * ## The one thing a mount-bound report cannot see (objectui#10180)
+ *
+ * A widget's in-flight state is React state, so it ends when the widget
+ * unmounts — and an upload does not. `FileField` does not abort its upload
+ * when it unmounts; the promise settles later and hands the value to the
+ * `onChange` it captured, which the form still accepts. So "the widget
+ * unmounted" is not "the upload ended". A wizard step the user leaves is the
+ * everyday case: leaving the step drops the widget's report, the wizard's final
+ * gate reads `false` while the upload is still running, and a Create pressed in
+ * that window writes the record WITHOUT the attachment and reports success.
+ *
+ * The in-repo upload widgets therefore also hold the scope for the lifetime of
+ * the upload ITSELF, through {@link useUploadingScopeHold}: taken when the
+ * upload starts, released when its promise settles, whether or not the widget
+ * is still mounted by then. While the widget is mounted the two entries start
+ * and stop together, so they cannot disagree; after it unmounts the hold is the
+ * only entry left, and it is the true one. The hold is internal to this package
+ * — it is not exported from the package entry.
+ */
+/**
+ * The write half of a scope. Kept separate from the boolean so a widget that
+ * only REPORTS does not re-render when some other widget's upload flips —
+ * reporters read this context, the host owns the boolean.
+ */
+interface UploadingScopeSink {
+    /**
+     * Record whether the widget registered under `id` is currently uploading.
+     * Reporting `false` for an unknown id is a no-op, which is what makes the
+     * unmount release below safe to call unconditionally.
+     */
+    report: (id: string, uploading: boolean) => void;
+}
+/** What {@link useUploadingScope} hands a host. */
+export interface UploadingScope {
+    /** True while at least one upload widget inside the scope is in flight. */
+    anyUploading: boolean;
+    /**
+     * Passed to {@link UploadingScopeProvider}. Opaque to the host: it is the
+     * channel the widgets report on, not state the host is meant to read.
+     */
+    sink: UploadingScopeSink;
+}
+/**
+ * Own an uploading scope. The host reads `anyUploading` to gate its own submit
+ * and to say WHY that control is disabled, and renders its form subtree inside
+ * {@link UploadingScopeProvider}.
+ *
+ * The host owns the state rather than reading it back out of the context on
+ * purpose: a provider cannot consume its own value, and splitting it would give
+ * "is anything uploading" two authors.
+ */
+export declare function useUploadingScope(): UploadingScope;
+/**
+ * Publish a host's {@link useUploadingScope} to every upload widget rendered
+ * below it. Nesting is legal and CHAINS: an inner scope gates its own Save on
+ * its own uploads AND reports itself to the scope above, so an outer Save whose
+ * write encompasses the inner content is never blind to it. See
+ * {@link useUploadingScope} for why the direction is not a preference.
+ */
+export declare function UploadingScopeProvider({ scope, children, }: {
+    scope: UploadingScope;
+    children: React.ReactNode;
+}): React.ReactElement;
+/**
+ * Report this widget's in-flight state to the enclosing scope, if there is one.
+ * Called by `useUploadingSignal` so every widget that already publishes to a
+ * host prop publishes here too, from the same state.
+ *
+ * ⚠️ The unmount release is load-bearing, not tidiness. A widget removed while
+ * its upload is in flight — a section collapsing, a tab switching, a subform
+ * row deleted — would otherwise leave its id in the set with nothing left to
+ * ever clear it, and the form's Save would stay disabled for the rest of the
+ * session. That failure mode is worse than the defect this scope fixes,
+ * because it has no user-visible cause at all.
+ *
+ * This report covers the widget's MOUNTED lifetime only. The upload's own
+ * lifetime, which can outlast the widget, is covered by
+ * {@link useUploadingScopeHold} — that is what keeps the release above from
+ * also releasing an upload that is still running (objectui#10180).
+ */
+export declare function useUploadingScopeReport(uploading: boolean): void;
+/**
+ * Hold the enclosing scope "uploading" for the lifetime of ONE upload
+ * (objectui#10180). The returned `hold()` is called when an upload starts and
+ * answers that upload's `release()`, to be called once its promise settles —
+ * in a `finally`, so a failed upload releases too.
+ *
+ * ## Why this is separate from the mount-bound report
+ *
+ * {@link useUploadingScopeReport} has to release on unmount (see there), and
+ * an upload keeps running after the widget that started it has unmounted —
+ * `FileField` does not abort it, and its settle still reaches the form's
+ * `onChange`. Leaving a wizard step mid-upload is exactly that: the step's
+ * widgets unmount, their reports are released, and without this hold the
+ * wizard's final gate read `false` while the file was still on its way, so a
+ * Create pressed in that window wrote the record without it.
+ *
+ * ## Why this cannot wedge the form
+ *
+ * The entry is released by the upload's own settle, not by a render, so it is
+ * cleared exactly when the upload ends, mounted widget or not. It can stay
+ * held only as long as the upload itself stays unsettled — the same bound a
+ * mounted widget's report already has — and while it is held the host shows
+ * the reason it gives for any upload in flight.
+ *
+ * The sink is captured when the upload STARTS: the scope the user picked the
+ * file under is the one whose save the file belongs to. A release that reaches
+ * a scope whose host has since unmounted is a no-op, and that host already
+ * released itself from any scope above it on the way out.
+ *
+ * Inert without a provider, like the report. Not exported from the package
+ * entry: it is how this package's own upload widgets report, not a contract.
+ */
+export declare function useUploadingScopeHold(): () => () => void;
+export {};

package/dist/widgets/useCascadingOptions.d.ts

@@ -9,8 +9,9 @@ import { CascadingOptions, OptionLike, DependsOnInput } from '@object-ui/core';
  * empty the list is *gated* — callers surface a "select the parent first" hint
  * rather than an unfiltered set, mirroring the dependent-lookup UX.
  *
- * This is the React wrapper that sources `record` (the live form values) and the
- * predicate scope from context; the actual resolution is the pure
+ * This is the React wrapper: `record` (the live form values) arrives on the
+ * `dependentValues` argument its HOST passes, the predicate scope comes from
+ * context, and the actual resolution is the pure
  * {@link resolveCascadingOptions} in `@object-ui/core`, shared with the form
  * renderer so gating/filtering can never drift between them (#2715).
  */

package/dist/widgets/useRecordQuery.d.ts

@@ -12,7 +12,9 @@ import { DataSource } from '@object-ui/types';
  *   (`{ data, total }`, tolerating a bare array),
  * - owns `records`/`loading`/`error`/`total` plus the `page`/`search`/`sort`
  *   controls, with a debounced search path,
- * - clears itself when `enabled` goes false (e.g. a dialog closing).
+ * - clears itself when it can no longer query — `enabled` false (e.g. a dialog
+ *   closing), or no data source or object name — superseding any read still in
+ *   flight, so that read's answer commits nothing (objectui#10712).
  *
  * The caller keeps ownership of *selection* state and of record→option mapping;
  * this hook only answers "what records match the current query". It is the
@@ -43,7 +45,7 @@ export interface UseRecordQueryOptions {
      */
     paginate?: boolean;
     /**
-     * `$filter` — already merged by the caller (base `lookup_filters`, dependent
+     * `$filter` — already merged by the caller (base `lookupFilters`, dependent
      * lookup chain, candidate hygiene like `banned != true`, …). Compared by
      * value, so a referentially-new-but-equal object each render will not loop.
      *
@@ -76,6 +78,19 @@ export interface UseRecordQueryResult {
     totalPages: number;
     page: number;
     search: string;
+    /**
+     * The search term `records` answer: the term of the query that committed
+     * them, `''` before the first answer and after a reset. It is set in the same
+     * commit as `records`, so the two never disagree.
+     *
+     * `search` moves on every keystroke, and the query for it runs after the
+     * debounce, so for that window `records` still answer an earlier term. A
+     * consumer that acts on "the rows for what the user typed" compares this
+     * with `search` (objectui#13162): equal means the rows on screen answer the
+     * term in the box. A late answer to a superseded query commits nothing
+     * (objectui#10712), so it cannot set this either.
+     */
+    answeredSearch: string;
     sort: RecordQuerySort | null;
     /** Jump to a page (1-indexed). No-op unless `paginate` is set. */
     setPage: (page: number) => void;

package/dist/widgets/useUploadingSignal.d.ts

@@ -5,5 +5,13 @@
  * submitted mid-upload (the value only becomes the fileId once the upload
  * settles). Fires with the latest callback and only when `uploading` actually
  * changes, so an inline arrow prop doesn't thrash the parent every render.
+ *
+ * It ALSO reports into the ambient `UploadingScope` when one is mounted above
+ * the widget (objectui#10166). The prop suits a host that renders one named
+ * control; a record form hands its fields to the `form` node renderer and never
+ * touches the widget, so it has no place to attach a callback — the scope is how
+ * that host learns an upload is in flight. Both sinks are driven from this one
+ * call so they cannot disagree, and a host that mounts no provider is
+ * unaffected: `useUploadingScopeReport` is inert without one.
  */
 export declare function useUploadingSignal(uploading: boolean, onUploadingChange?: (uploading: boolean) => void): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/fields",
-  "version": "17.6.0",
+  "version": "18.0.0",
   "description": "Field renderers and registry for Object UI",
   "license": "MIT",
   "type": "module",
@@ -23,19 +23,18 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@objectstack/spec": "^17.0.0",
-    "clsx": "^2.1.1",
-    "lucide-react": "^1.31.0",
+    "@objectstack/spec": "^18.0.0",
+    "lucide-react": "^1.43.0",
     "react-markdown": "^10.1.0",
     "rehype-sanitize": "^6.0.0",
     "remark-gfm": "^4.0.1",
-    "tailwind-merge": "^3.6.0",
-    "@object-ui/components": "17.6.0",
-    "@object-ui/core": "17.6.0",
-    "@object-ui/i18n": "17.6.0",
-    "@object-ui/providers": "17.6.0",
-    "@object-ui/react": "17.6.0",
-    "@object-ui/types": "17.6.0"
+    "@object-ui/components": "18.0.0",
+    "@object-ui/core": "18.0.0",
+    "@object-ui/i18n": "18.0.0",
+    "@object-ui/permissions": "18.0.0",
+    "@object-ui/providers": "18.0.0",
+    "@object-ui/react": "18.0.0",
+    "@object-ui/types": "18.0.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
@@ -83,7 +82,7 @@
     "build": "tsc && vite build && node scripts/build-css.mjs",
     "clean": "rm -rf dist",
     "type-check": "tsc --noEmit && tsc -p tsconfig.test.json",
-    "test": "vitest run",
+    "test": "vitest run --root ../.. packages/fields/",
     "lint": "eslint ."
   }
 }