@object-ui/components 17.5.0 → 17.7.0

package/dist/custom/filter-builder.d.ts

@@ -1,3 +1,4 @@
+import { FilterBuilderCondition as AuthoredFilterBuilderCondition, FilterGroup as AuthoredFilterGroup } from '@object-ui/types';
 /**
  * ObjectUI
  * Copyright (c) 2024-present ObjectStack Inc.
@@ -16,21 +17,43 @@ import * as React from "react";
  * and `operator` here is the builder's own dropdown vocabulary
  * (`FILTER_BUILDER_OPERATORS`), not the spec's `$`-tokens.
  *
- * `@object-ui/types` already renamed its identical concept to
- * `FilterBuilderCondition` (objectui#3068); this is the same thing, so it takes
- * the same name rather than inventing a second dialect. Note the same name is
- * NOT the right answer everywhere: `@object-ui/app-shell`'s `FilterCondition`
- * really was the spec's ObjectQL AST and was re-exported (objectui#3169).
+ * DERIVED from `@object-ui/types`, never declared a second time (objectui#9306,
+ * which settles objectui#6349's two parked name-authority rows). That declaration is
+ * the one name authority for the row; this one takes every member from it
+ * (`id`, required since objectui#8415, and `field`) and restates exactly two,
+ * each a named extension:
+ *
+ *   - `operator` — {@link FilterBuilderOperator}: the protocol's ids, which is
+ *     what the authority declares, plus the opt-in `exists` / `notExists` the
+ *     protocol has no member for (objectui#9559 ruling B keeps them opt-in and
+ *     unfolded). It was `string`, which let a caller hand the builder an id no
+ *     dropdown entry can hold.
+ *   - `value` — REQUIRED and narrowed to the scalar-or-list union this builder
+ *     edits, where the authority declares `value?: any`. Every exported helper
+ *     below that takes a row's value (`reshapeFilterValue`, `retypeFilterValue`,
+ *     `narrowFilterValueToOptions`, …) is typed on this member, so `any` here
+ *     would switch their checking off in silence.
  */
-export interface FilterBuilderCondition {
-    id: string;
-    field: string;
-    operator: string;
+export interface FilterBuilderCondition extends Omit<AuthoredFilterBuilderCondition, "operator" | "value"> {
+    operator: FilterBuilderOperator;
     value: string | number | boolean | (string | number | boolean)[];
 }
-export interface FilterGroup {
-    id: string;
-    logic: "and" | "or";
+/**
+ * The group the FilterBuilder edits: one `logic` over FLAT rows.
+ *
+ * DERIVED from `@object-ui/types` like the row above (objectui#9306). Only
+ * `conditions` is restated, to hold THIS package's row; `id` and `logic` are
+ * the authority's own. So `id` is OPTIONAL here, as it is there: nothing in
+ * this builder reads a group's `id`, `onChange` hands back whatever group the
+ * host passed (an id-less group comes back id-less), and only `EMPTY_GROUP`
+ * invents one. The `id: string` this package used to declare described a
+ * group the builder never guaranteed.
+ *
+ * `conditions` is flat because the builder is: it draws each entry as one row
+ * and has no control that creates a group. The authority retired nested
+ * sub-groups in the same change and its zod mirror refuses one by name.
+ */
+export interface FilterGroup extends Omit<AuthoredFilterGroup, "conditions"> {
     conditions: FilterBuilderCondition[];
 }
 export interface FilterBuilderProps {
@@ -42,7 +65,7 @@ export interface FilterBuilderProps {
             value: string;
             label: string;
         }>;
-        /** For lookup/master_detail/user/owner fields — referenced object name */
+        /** For lookup/master_detail/user fields — referenced object name */
         referenceTo?: string;
         /** Display field on the referenced object (defaults to "name") */
         displayField?: string;
@@ -53,36 +76,50 @@ export interface FilterBuilderProps {
     onChange?: (value: FilterGroup) => void;
     className?: string;
     showClearAll?: boolean;
+    /**
+     * Opt-in operator ids ({@link OPT_IN_OPERATORS}) this instance may offer, on
+     * top of the ones every FilterBuilder draws.
+     *
+     * The dropdown is shared by consumers that persist a filter into DIFFERENT
+     * dialects, and an operator one dialect can carry is not automatically
+     * storable in another — so whether an opt-in operator is offered is the
+     * consumer's answer, not this component's. See {@link OPT_IN_OPERATORS} for
+     * the measurement that made this a prop instead of one global list.
+     */
+    extraOperators?: readonly string[];
 }
 declare const defaultOperators: readonly [{
     readonly value: "equals";
     readonly label: "Equals";
 }, {
-    readonly value: "notEquals";
+    readonly value: "not_equals";
     readonly label: "Does not equal";
 }, {
     readonly value: "contains";
     readonly label: "Contains";
 }, {
-    readonly value: "notContains";
+    readonly value: "icontains";
+    readonly label: "Contains (ignore case)";
+}, {
+    readonly value: "not_contains";
     readonly label: "Does not contain";
 }, {
-    readonly value: "isEmpty";
+    readonly value: "is_empty";
     readonly label: "Is empty";
 }, {
-    readonly value: "isNotEmpty";
+    readonly value: "is_not_empty";
     readonly label: "Is not empty";
 }, {
-    readonly value: "greaterThan";
+    readonly value: "greater_than";
     readonly label: "Greater than";
 }, {
-    readonly value: "lessThan";
+    readonly value: "less_than";
     readonly label: "Less than";
 }, {
-    readonly value: "greaterOrEqual";
+    readonly value: "greater_than_or_equal";
     readonly label: "Greater than or equal";
 }, {
-    readonly value: "lessOrEqual";
+    readonly value: "less_than_or_equal";
     readonly label: "Less than or equal";
 }, {
     readonly value: "before";
@@ -97,19 +134,19 @@ declare const defaultOperators: readonly [{
     readonly value: "in";
     readonly label: "In";
 }, {
-    readonly value: "notIn";
+    readonly value: "not_in";
     readonly label: "Not in";
 }, {
-    readonly value: "startsWith";
+    readonly value: "starts_with";
     readonly label: "Starts with";
 }, {
-    readonly value: "endsWith";
+    readonly value: "ends_with";
     readonly label: "Ends with";
 }, {
-    readonly value: "isNull";
+    readonly value: "is_null";
     readonly label: "Is null";
 }, {
-    readonly value: "isNotNull";
+    readonly value: "is_not_null";
     readonly label: "Is not null";
 }, {
     readonly value: "exists";
@@ -120,19 +157,394 @@ declare const defaultOperators: readonly [{
 }];
 /**
  * The FilterBuilder's own operator vocabulary — every id its dropdown can
- * hold, derived from the operators it actually renders.
+ * hold, derived from the operators it actually renders. Includes the opt-in
+ * ids: they are drawable, just not offered unconditionally.
  *
- * Exported because several translation tables map an external vocabulary
- * (the spec's `VIEW_FILTER_OPERATORS`, Mongo `$`-tokens) *onto* this one, and
- * a value that is not in this list produces a condition row whose operator
- * select has nothing to select. Those tables assert against this export
- * rather than restating it, so adding an operator here is the only edit
- * needed to widen them.
+ * Since objectui#9306 these ARE the protocol's ids — the twenty members of the
+ * spec's `VIEW_FILTER_OPERATORS`, plus the opt-in `exists` / `notExists` the
+ * protocol has no member for — so a table that maps the spec's vocabulary onto
+ * this one is an identity over the twenty. It is still exported because those
+ * tables, and the parity pins over them, assert against this list rather than
+ * restating it: a value that is not in it produces a condition row whose
+ * operator select has nothing to select.
+ */
+export declare const FILTER_BUILDER_OPERATORS: ("in" | "starts_with" | "ends_with" | "contains" | "equals" | "not_equals" | "greater_than" | "greater_than_or_equal" | "less_than" | "less_than_or_equal" | "before" | "after" | "not_in" | "not_contains" | "icontains" | "between" | "is_null" | "is_not_null" | "is_empty" | "is_not_empty" | "exists" | "notExists")[];
+/**
+ * An operator id the FilterBuilder can render: the spec's `ViewFilterOperator`
+ * plus the two opt-in existence ids (objectui#9306). A type-level pin in
+ * `filter-builder-protocol-ids-9306.test.tsx` holds it EQUAL to that union, so
+ * a protocol member added upstream fails to compile there until the dropdown
+ * offers it.
  */
-export declare const FILTER_BUILDER_OPERATORS: ("endsWith" | "startsWith" | "in" | "after" | "equals" | "notEquals" | "contains" | "notContains" | "isEmpty" | "isNotEmpty" | "greaterThan" | "lessThan" | "greaterOrEqual" | "lessOrEqual" | "before" | "between" | "notIn" | "isNull" | "isNotNull" | "exists" | "notExists")[];
-/** An operator id the FilterBuilder can render. */
 export type FilterBuilderOperator = (typeof defaultOperators)[number]['value'];
-declare function FilterBuilder({ fields, value, onChange, className, showClearAll, }: FilterBuilderProps): React.JSX.Element;
+/**
+ * The spelling a stored operator is READ as — the protocol id for every
+ * spelling the spec or this builder ever wrote (objectui#9306).
+ *
+ * The ruling this executes: camelCase is the deprecated alias form
+ * (objectui#7993), accepted on read and rewritten on write. So a filter stored
+ * as `{ operator: 'greaterOrEqual' }` keeps loading — it is folded here, through
+ * the spec's own `normalizeFilterOperator`, onto `greater_than_or_equal` — and
+ * the builder holds and emits that canonical id from then on, so the next write
+ * the author makes stores it. A lossless conversion on the read side, ⛔ not a
+ * second vocabulary: nothing this builder EMITS is ever a camelCase id.
+ *
+ * An id nothing folds (`exists`, `notExists`, a spelling from no vocabulary)
+ * comes back unchanged, exactly as the spec's normalizer returns it: inventing
+ * a mapping for a word the protocol does not contain would be a claim, not a
+ * repair.
+ *
+ * ⚠️ One guard on the spec's answer, and only because the builder now STORES
+ * what this returns (before objectui#9306 the fold was used for comparison
+ * only). `normalizeFilterOperator` is declared to return a string, but it
+ * looks the spelling up on a plain object, so an `Object.prototype` key comes
+ * back as whatever the prototype holds — `'constructor'` returns the `Object`
+ * function, measured on `@objectstack/spec` 17.4.0. Held in a row and written
+ * back, that would drop the row's operator on serialisation. A non-string
+ * answer is therefore treated as "nothing folds" and the spelling is kept;
+ * the defect itself belongs to the spec and is reported there, not patched
+ * around here in any other way.
+ */
+export declare function normalizeFilterBuilderOperator(operator: string): string;
+/**
+ * Operator ids — this dropdown's own ids, which are the protocol's canonical
+ * spellings since objectui#9306 — for which this builder renders no value
+ * input, so "no value" is the row's FINISHED state, not an unfinished one
+ * (objectui#4744).
+ *
+ * This is the source of truth for that distinction, and it lives here because
+ * this component is the thing that decides it. But membership here is not the
+ * whole question: `needsValueInput` below asks it of the row's spelling AFTER
+ * {@link normalizeFilterBuilderOperator} (objectui#9302), so the gate answers
+ * "no value" for spellings that are NOT members — the deprecated camelCase ids
+ * a stored filter may still carry, and the alias rows the spec publishes for
+ * those same operators. A consumer holding a spelling that did not come from
+ * this dropdown must therefore fold it before asking, and fold this set's own
+ * members through the same normalizer too — the spec's `normalizeFilterOperator`
+ * is the identity on them, so that fold costs nothing and keeps the consumer
+ * correct whichever vocabulary this set is written in. How much wider the
+ * gate's preimage is is NOT restated here: the pin
+ * `filter-builder-valueless-canonical-spelling-9302.test.tsx` walks the
+ * spec's two published tables and names every row it measures, which is the
+ * only form of that answer that moves when those tables do (AGENTS.md #9).
+ *
+ * Every consumer that has to tell a complete value-less row from a half-filled
+ * one reads the membership FROM here rather than restating it:
+ *
+ *   - `plugin-list`'s `convertFilterGroupToAST` — what the live grid QUERIES;
+ *   - `app-shell`'s `foldFilterGroupToSpecRules` — what a saved view PERSISTS.
+ *
+ * Placement is forced by the dependency graph — `app-shell` depends on
+ * `plugin-list` depends on this package, so this is the only module all three
+ * can reach — and it is also where the set belongs on the merits: the fact it
+ * states is a fact about what this dropdown draws.
+ *
+ * Why it exists at all: each consumer used to keep its own copy, and the
+ * live-grid copy listed only the two empty-string operators. A fresh row is
+ * seeded `{ operator: 'equals', value: '' }` and the operator dropdown
+ * preserves `value`, so picking **Is null** as the first action left
+ * `value: ''` — the grid read that as an unfinished row, dropped it, and
+ * applied NO filter at all while the panel showed one. Silent, and every
+ * record came back.
+ *
+ * `exists` / `notExists` stay listed even though `OPT_IN_OPERATORS` withholds
+ * them from most consumers (objectui#4736): the builder still draws them
+ * value-less for `FilterConditionField`, which is exactly what this set
+ * describes. Whether a consumer can EXPRESS an operator is a separate
+ * question, answered by `OPT_IN_OPERATORS` and by each consumer's parity test.
+ */
+export declare const VALUELESS_FILTER_BUILDER_OPERATORS: ReadonlySet<string>;
+/**
+ * The SHAPE an operator's `value` must have — the question
+ * `ViewFilterRuleSchema` asks, asked here in the one place that decides what
+ * input the user is given (objectui#3958).
+ *
+ *   - `list` — membership over any arity, `[]` included (`in` / `not_in`).
+ *   - `pair` — exactly two bounds, in order (`between`).
+ *   - `scalar` — everything else, including the value-less operators above
+ *     (they draw no input at all, so their shape never reaches storage).
+ */
+export type FilterValueArity = "scalar" | "list" | "pair";
+/**
+ * Which value shape `operator` takes, whichever spelling it arrives in.
+ *
+ * The argument is folded through {@link normalizeFilterBuilderOperator} — the
+ * spec's own `normalizeFilterOperator` plus the builder's one unfolded legacy
+ * id — first, so the canonical id this dropdown emits (`not_in`) and the
+ * deprecated alias a stored filter may still carry (`notIn`) land on the same
+ * answer. That fold is the whole point: one vocabulary, declared upstream,
+ * consulted here — not a second local dialect kept in sync by hand.
+ *
+ * @internal exported for tests
+ */
+export declare function filterValueArity(operator: string): FilterValueArity;
+/**
+ * Re-shape a row's `value` for the operator it is being changed TO.
+ *
+ * Switching the operator dropdown used to update `operator` alone, so the
+ * value the previous family had produced simply survived the switch — a scalar
+ * `"acme"` (or the seed `""`) still sitting there under `in`, which is
+ * precisely the shape `ViewFilterRuleSchema` refuses. Re-shaping rather than
+ * blanking keeps what the user typed wherever it still means something:
+ *
+ *   - to `list`: a scalar becomes a one-element list (`"acme"` → `["acme"]`),
+ *     an empty scalar becomes `[]` — a real, spec-valid predicate;
+ *   - to `pair`: the first two entries become `[min, max]`, padded with `""`;
+ *     with nothing to carry it collapses to `[]`, which the write path reads
+ *     as "row not filled in yet" and drops, exactly as it drops an empty
+ *     scalar today;
+ *   - to `scalar`: the first entry of a list survives; the rest cannot, and
+ *     dropping them is the honest answer — `equals` compares against one value.
+ *
+ * @internal exported for tests
+ */
+export declare function reshapeFilterValue(value: FilterBuilderCondition["value"], nextOperator: string): FilterBuilderCondition["value"];
+/**
+ * The operator a row keeps after its FIELD is changed, given the operators the
+ * NEW field offers (objectui#4768).
+ *
+ * Each field type has its own operator bucket, and the buckets are not nested:
+ * a `select` column offers `in` / `not_in`, a `text` column does not. Changing
+ * the field used to write `{ field }` alone, so the row's operator survived
+ * into a bucket that no longer contains it — `in` on a text column. The Radix
+ * trigger then had nothing to render (its `SelectValue` matches against the
+ * `SelectItem`s actually mounted) and went BLANK, while the row went on
+ * filtering by an operator the user could no longer see or reach.
+ *
+ * So the two edits are one edit, exactly as `changeOperator` made the operator
+ * and its value shape one edit: an operator the new bucket still offers is the
+ * user's choice and is KEPT; one it does not is replaced by the bucket's first
+ * entry (`equals` for every bucket this builder draws), and the caller then
+ * re-shapes the value for that operator's family.
+ *
+ * Membership is decided CANONICALLY, through
+ * {@link normalizeFilterBuilderOperator} — the same fold `filterValueArity`
+ * uses. A caller can hand this helper a row spelled with the deprecated alias
+ * `notIn` while the dropdown lists the protocol id `not_in`; those are one
+ * operator, so a select→lookup switch must not silently rewrite the author's
+ * operator to `equals` just because the two spellings differ. The fold is safe
+ * to compare through because it is INJECTIVE over this builder's vocabulary —
+ * all 22 ids in `defaultOperators` normalize to 22 distinct canonical
+ * operators, pinned in `filter-builder-field-switch-operator.test.tsx` — so no
+ * two OFFERED operators can ever collapse onto one another.
+ *
+ * @internal exported for tests
+ */
+export declare function reconcileOperatorForField(operator: string, offeredOperators: ReadonlyArray<{
+    value: string;
+}>): string;
+/**
+ * The offered id the operator trigger COMPARES against — the last site in this
+ * component that read the operator literally instead of through the spec's
+ * fold (objectui#7561).
+ *
+ * Radix matches `SelectValue` against the `SelectItem`s actually MOUNTED, and
+ * the mounted ids are this builder's own vocabulary — the protocol's canonical
+ * ids since objectui#9306 (they were camelCase when this helper was written). A
+ * row can hold the operator under another spelling of the SAME operator and
+ * still be perfectly valid:
+ *
+ *   - a deprecated camelCase alias such as `greaterThan`, which a filter saved
+ *     before objectui#9306 still carries;
+ *   - the spec's alias table `gt` / `lt` / `eq`, which three schema-catalog
+ *     entries author today.
+ *
+ * When this helper was written the mounted id was `greaterThan` and the stored
+ * spelling `greater_than`; neither matched the other literally, so the trigger
+ * drew BLANK over a row that filtered correctly — the user's own operator,
+ * invisible and unreachable.
+ * Everywhere the operator's MEANING matters this component already folds first
+ * ({@link filterValueArity}, {@link reconcileOperatorForField}); this was the
+ * one place it did not, and that omission — not the vocabulary divergence — is
+ * what produced the blank.
+ *
+ * So the comparison is made canonically and the MOUNTED spelling is handed to
+ * the trigger. Three things this deliberately does NOT do, each of them a
+ * separate ruling (objectui#7561):
+ *
+ *   1. it does not rewrite `condition.operator` — the row keeps the spelling it
+ *      arrived with, exactly as {@link reconcileOperatorForField} keeps it, and
+ *      nothing is written back on render. (Since objectui#9306 the BUILDER
+ *      folds a row's spelling once, at its read boundary — see
+ *      {@link normalizeFilterBuilderOperator} — so the rows it renders already
+ *      hold protocol ids. This helper still folds both sides, because it is
+ *      exported and its caller's rows need not have come through that
+ *      boundary.)
+ *   2. it does not mount a new `SelectItem`, so the vocabulary the dropdown
+ *      EMITS is byte-identical — contrast the value select above, where
+ *      objectui#4874 ruling C mounts the outside-options value as its own
+ *      option. That answer is right there and wrong here: the value's domain is
+ *      the author's data, while the operator's domain is a declared vocabulary,
+ *      and mounting a foreign spelling would admit a second one;
+ *   3. it does not widen what any schema ACCEPTS.
+ *
+ * Safe to compare through because the fold is INJECTIVE over this builder's
+ * vocabulary — all 22 ids in `defaultOperators` normalize to 22 distinct
+ * canonical operators, pinned in `filter-builder-field-switch-operator.test.tsx`
+ * — so no two OFFERED operators can collapse onto one another and the match is
+ * unambiguous. An operator no offered id folds onto falls through to the row's
+ * own spelling and still draws blank: inventing a label for a word this
+ * vocabulary does not contain would be a claim, not a repair.
+ *
+ * @internal exported for tests
+ */
+export declare function mountedOperatorValue(operator: string, offeredOperators: ReadonlyArray<{
+    value: string;
+}>): string;
+/**
+ * Re-TYPE a row's `value` for the field it is being changed TO — the type
+ * question, standing beside {@link reshapeFilterValue}'s shape question
+ * (objectui#4781).
+ *
+ * Changing a row's field used to carry the value through untouched whenever the
+ * shape did not have to change, which is right about the shape and wrong about
+ * the type: the value input is re-drawn from the NEW field's type, and an
+ * `<input type="number">` renders a non-numeric value as BLANK. So a `text`
+ * row filtered `equals "acme"`, pointed at a number column, showed an empty box
+ * while the row went on carrying `"acme"` — `foldFilterGroupToSpecRules`
+ * persisted it and the live grid queried `amount equals "acme"`. The same
+ * invisible-value shape objectui#4768 closed on the operator, one column over.
+ *
+ * Carry-if-possible, exactly as `reshapeFilterValue` carries what it can across
+ * a family change: `"42"` moved to a number column becomes `42` and survives;
+ * `"acme"` cannot be read as a number by any clean reading, so it clears to the
+ * family's empty shape — scalar `""`, list `[]`, pair `[]`. What a value can
+ * become is decided in one place, {@link convertScalarToFamily}.
+ *
+ * The arity is read from the operator through the same `filterValueArity` fold
+ * the rest of this component uses, because each shape clears differently:
+ *
+ *   - `scalar` — converted, or `""`.
+ *   - `list` — converted ENTRY BY ENTRY, keeping the ones that carry:
+ *     `["42", "acme"]` → `[42]`, and `[]` when none do. Reachable today only
+ *     between the two buckets that offer `in`/`not_in` (`select` ↔ `lookup`),
+ *     which are both text-family, so the conversion is the identity there; it
+ *     is written for the family the operator lands in rather than for today's
+ *     buckets, and pinned directly on this helper.
+ *   - `pair` — both bounds converted independently, an unconvertible bound
+ *     becoming `""` so the range keeps its two slots; both empty collapses to
+ *     `[]`, the "not filled in yet" shape `reshapeFilterValue` also produces
+ *     and the write path drops.
+ *
+ * @internal exported for tests
+ */
+export declare function retypeFilterValue(value: FilterBuilderCondition["value"], fieldType: string | undefined, operator: string): FilterBuilderCondition["value"];
+/** The shape of a `fields` entry that the option-domain helpers below read. */
+type OptionBearingField = {
+    type?: string;
+    options?: ReadonlyArray<{
+        value: string;
+        label: string;
+    }>;
+};
+/**
+ * Narrow a row's `value` to the option DOMAIN of the field it is being changed
+ * TO — the value-domain question, standing beside {@link retypeFilterValue}'s
+ * type question and {@link reshapeFilterValue}'s shape question
+ * (objectui#4874).
+ *
+ * objectui#4781 settled the TYPE half and deliberately stopped there: `select`
+ * and `lookup` are text-family, so `"acme"` is a value those columns can
+ * perfectly well HOLD. What it cannot be is one of the column's options — and
+ * the control drawn for those columns is a Radix Select, whose trigger renders
+ * only what one of its mounted `SelectItem`s carries. So a text row filtered
+ * `equals "acme"`, pointed at a picklist column of `won`/`lost`, showed a BLANK
+ * trigger while the row went on carrying `"acme"`:
+ * `foldFilterGroupToSpecRules` persisted it and the live grid queried
+ * `stage equals "acme"`. The third face of the same invisible value —
+ * objectui#4768 on the operator, objectui#4781 on the value's type, this one on
+ * its domain.
+ *
+ * Ruled 2026-08-17 as **A + C combined**, and the A half is this function:
+ * clear on non-membership, but ONLY where the option set is the column's whole
+ * domain ({@link hasStaticOptionDomain}). A remote/async column's value is
+ * returned untouched — clearing it would delete a perfectly valid lookup id on
+ * the strength of a local page that never claimed to be complete, and the C
+ * half (the render path's temporary option) is what keeps it visible instead.
+ * Option B — keep the value and tolerate it being invisible — stays rejected,
+ * as it was on objectui#4781.
+ *
+ * The empty shape a cleared value falls to is objectui#4781's, unchanged and
+ * read from the same `filterValueArity` fold:
+ *
+ *   - `scalar` — `""`.
+ *   - `list` — filtered ENTRY BY ENTRY, keeping the members: `["acme", "won"]`
+ *     → `["won"]`, and `[]` when none survive. Per-entry rather than
+ *     all-or-nothing because each entry is its own filter term, and one bad
+ *     term is no reason to throw away the user's good ones.
+ *   - `pair` — untouched; `between` is not option-driven.
+ *
+ * @internal exported for tests
+ */
+export declare function narrowFilterValueToOptions(value: FilterBuilderCondition["value"], field: OptionBearingField | undefined, operator: string): FilterBuilderCondition["value"];
+/**
+ * Is this row's value FINISHED for the operator it carries — the arity-aware
+ * reading of "the user has filled this in" (objectstack#8815).
+ *
+ * Both write paths used to ask this with one shape-blind predicate:
+ *
+ * ```ts
+ * value == null || value === '' || (Array.isArray(value) && value.length === 0)
+ * ```
+ *
+ * which is right for `scalar` and `list` and WRONG for `pair`. A `between` row
+ * with one bound typed is `["2024-01-01", ""]` — an array of length 2, so it
+ * read as complete, and both consumers carried it through. The live grid then
+ * queried a range with an empty upper bound and the server refused the whole
+ * view (`400 INVALID_FILTER`), which is the "该视图的查询被拒绝" the reporter
+ * hit; the saved-view path persisted the same half-range, so the refusal came
+ * back on every later read of that view.
+ *
+ * The spec cannot catch this on the way past — measured against
+ * `ViewFilterRuleSchema` on `@objectstack/spec` 17.0.0: `["2024-01-01", ""]` is
+ * ACCEPTED (it counts the two slots, not what is in them), while a scalar or a
+ * one-element array is refused. So the empty bound sails through authoring
+ * validation and only dies at query time, one layer too late to be actionable.
+ * That makes it the PRODUCER's job to not emit it — this component is what
+ * decides when a row is finished, exactly as it already decides which operators
+ * finish with no value at all ({@link VALUELESS_FILTER_BUILDER_OPERATORS}), and
+ * for the same reason: each consumer keeping its own copy is how the two came to
+ * disagree in the first place.
+ *
+ * The arity is read through the same `filterValueArity` fold the rest of this
+ * file uses, so a stored rule spelled canonically gets the same answer as the
+ * dropdown's own id.
+ *
+ * What each shape needs:
+ *
+ *   - `pair` — BOTH bounds present. A range missing an end is not a narrower
+ *     range, it is a query the server refuses.
+ *   - `list` — at least one entry; `[]` is the "nothing chosen yet" shape.
+ *   - `scalar` — anything that is not the unfilled shape.
+ *
+ * "Present" is {@link isValueUnset}, never `!bound` (objectui#4873): `0` is a
+ * real bound on a number column and `false` is a real value, and reading either
+ * as unfilled would drop a filter the user can see on screen.
+ *
+ * This answers the VALUE question only. Whether an operator wants a value at all
+ * stays with each caller, because the two layers see different vocabularies:
+ * `app-shell` also has to recognise the canonical spellings (`is_null`) that
+ * never reach this dropdown.
+ *
+ * @internal exported for tests
+ */
+export declare function isFilterValueComplete(operator: string, value: FilterBuilderCondition["value"] | undefined | null): boolean;
+/**
+ * The operators the dropdown offers for a field of `fieldType`, given the
+ * opt-in ids this instance was granted.
+ *
+ * A pure function rather than a closure so the selection rule — and above all
+ * the {@link OPT_IN_OPERATORS} gate, whose whole job is to keep an operator OFF
+ * the surfaces that cannot store it — is assertable without driving a Radix
+ * popover open in jsdom.
+ *
+ * @internal exported for tests
+ */
+export declare function operatorsForFieldType(fieldType: string | undefined, extraOperators?: readonly string[]): ReadonlyArray<{
+    value: string;
+    label: string;
+}>;
+declare function FilterBuilder({ fields, value, onChange, className, showClearAll, extraOperators, }: FilterBuilderProps): React.JSX.Element;
 declare namespace FilterBuilder {
     var displayName: string;
 }

package/dist/custom/fullscreen-editor.d.ts

@@ -1,4 +1,29 @@
 import { default as React } from 'react';
+/**
+ * The accessibility attributes the dialog's injected editor MUST carry, handed
+ * to `children` as its required fourth argument (objectui#4824 / #4832).
+ *
+ * Shaped as a spreadable set of real DOM attributes rather than the ids behind
+ * them, on purpose: `{...aria}` is the whole integration, so a host cannot get
+ * the composition subtly wrong, cannot name a node outside the dialog, and
+ * cannot compute its own `aria-invalid` from a prop it forgot to plumb — the
+ * three ways every one of the three surfaces got this wrong before.
+ */
+export interface FullscreenEditorAria {
+    /**
+     * The dialog title's text node — the field label (#3393) reused as the
+     * control's accessible name rather than a second, string-valued author for it.
+     */
+    'aria-labelledby': string;
+    /** Mirrors `error`, so the dialog cannot disagree with the inline control. */
+    'aria-invalid': boolean;
+    /**
+     * The dialog-local message node. A SINGLE id, present only when `error` is —
+     * `aria-errormessage` is exposed only alongside `aria-invalid="true"`, and
+     * this repo's toolchain does not accept an id list here.
+     */
+    'aria-errormessage'?: string;
+}
 export interface FullscreenEditorProps {
     /**
      * The committed value. Seeds the draft each time the dialog opens — read at
@@ -39,6 +64,22 @@ export interface FullscreenEditorProps {
      * widgets and applies it on the built-in branch.
      */
     disabled?: boolean;
+    /**
+     * The field's validation message, or `undefined` when the field is valid.
+     *
+     * **Required, not optional** (objectui#4824). Every consumer already has it —
+     * the registered widgets take `error` off the widget props contract
+     * (objectui#3222), the built-in branch reads `fieldState.error?.message` — and
+     * an omitted `error` reproduces this issue exactly: a dialog that announces
+     * `aria-invalid="false"` while the same field's inline control announces
+     * `true`. A key the type system makes every call site answer cannot be
+     * forgotten by the next surface; an optional one was, three times.
+     *
+     * **Producers**: `TextAreaField`, `RichTextField`, and the form renderer's
+     * built-in `textarea` branch (which reads it off the PRE-strip props, exactly
+     * like `label` — `stripRendererOnlyProps` discards `error` for the DOM).
+     */
+    error: string | undefined;
     /**
      * The editor itself, rendered inside the dialog body against the draft. The
      * host passes the SAME editor it renders inline.
@@ -48,9 +89,14 @@ export interface FullscreenEditorProps {
      * editor's disabled state belongs on. Ignoring it is not a write-back hole —
      * `onCommit` is gated here regardless — but it does leave a control that looks
      * editable while the field is not, so every in-repo host applies it.
+     *
+     * The fourth argument is the accessibility set this component owns — name and
+     * validation state — and it is spread onto the control the host renders. See
+     * `FullscreenEditorAria` and the section above for why it is computed here
+     * rather than by each host.
      */
-    children: (draft: string, setDraft: (next: string) => void, disabled: boolean) => React.ReactNode;
+    children: (draft: string, setDraft: (next: string) => void, disabled: boolean, aria: FullscreenEditorAria) => React.ReactNode;
     /** Optional footer status for the draft (e.g. a character counter). */
     footer?: (draft: string) => React.ReactNode;
 }
-export declare function FullscreenEditor({ value, onCommit, label, testIdPrefix, readOnly, disabled, children, footer, }: FullscreenEditorProps): React.JSX.Element | null;
+export declare function FullscreenEditor({ value, onCommit, label, testIdPrefix, readOnly, disabled, error, children, footer, }: FullscreenEditorProps): React.JSX.Element | null;