@object-ui/react 17.5.0 → 17.7.0

package/dist/utils/visibilityDiagnostic.d.ts

@@ -0,0 +1,371 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Diagnostic: a node-gate predicate could not be evaluated (objectui#5454,
+ * leg 3 of the 2026-08-21 ruling; production coverage added by objectui#6038,
+ * maintainer ruling 2026-08-25 option B; the `disabled` / `disabledOn` gate
+ * added by objectui#6445).
+ *
+ * ## The defect this names
+ *
+ * `SchemaRenderer`'s visibility chain is FAIL-SOFT: `evaluateCondition` answers
+ * an unevaluable predicate with `true`. On the four negated legs (`visible` /
+ * `visibleWhen` / `visibleOn` / `visibility`) that `true` means SHOWN — so "this
+ * predicate is broken" and "this predicate said yes" reach the screen as the
+ * same pixel. An author who mistyped a root, or who wrote a `record.*` gate
+ * before objectui#5454 bound the row, saw their block render and had no signal
+ * at all that the gate had not been consulted.
+ *
+ * One of the three evaluation paths was already loud — a `{ dialect: 'cel' }`
+ * envelope routes to `evalFieldPredicate`, which warns (objectstack#5149). The
+ * bare-expression and `${…}` template paths were mute. So whether an author
+ * heard about their own typo depended on which dialect they happened to write
+ * it in, which is the arbitrariness this module removes.
+ *
+ * ## What it deliberately does NOT do
+ *
+ * It changes NO verdict. `evaluateCondition` already returned `true` for every
+ * unevaluable predicate on every one of its paths, and the caller reproduces
+ * exactly that from its catch — including on the two NON-negated legs
+ * (`hidden` / `hiddenOn`), where the same `true` means HIDE — and, since
+ * objectui#6445, on the `disabled` / `disabledOn` gate, where it means GREYED
+ * OUT. Flipping fail-soft to fail-closed is a shipped-behaviour change tracked
+ * separately upstream (objectstack#5149, appeal 1, undecided); this module is
+ * the diagnostic half only, on every gate wired to it.
+ *
+ * ## Why a separate module
+ *
+ * Same reason as `unevaluatedExpression.ts` next door: exporting non-components
+ * from the module that exports `SchemaRenderer` breaks Fast Refresh
+ * (`react-refresh/only-export-components`), and a format/emit split lets the
+ * pins assert the words a developer will actually read rather than that a spy
+ * was called — a diagnostic whose only test is the latter goes green the moment
+ * someone no-ops it.
+ */
+/**
+ * Prefix every diagnostic line starts with. Exported so tests can match on it
+ * and so an app can filter it out of its console transport if it must.
+ */
+export declare const UNRESOLVABLE_VISIBILITY_PREFIX = "[ObjectUI] A visibility predicate could not be evaluated";
+/**
+ * The same opening line for the ENABLEMENT gate (`disabled` / `disabledOn`,
+ * objectui#6445). A sibling constant rather than a widened one: the six
+ * visibility legs keep the bytes they ship today (objectui#6487 pinned them),
+ * and calling a `disabled` predicate a "visibility predicate" would send an
+ * author to the wrong gate on the first line - the one line a console filter
+ * and a `grep` both read.
+ *
+ * Same posture as its sibling in every other respect: same reporter, same
+ * severity, same dedupe `Set`, same key shape, same test-only reset. Only the
+ * words that would be FALSE on this gate differ.
+ */
+export declare const UNRESOLVABLE_ENABLEMENT_PREFIX = "[ObjectUI] An enablement predicate could not be evaluated";
+/**
+ * Which SCOPE the faulting predicate was evaluated against (objectui#6487).
+ *
+ * ## Why the reporter needs to be told, rather than deducing it
+ *
+ * The closing paragraph of the message names the ROOTS an author can bind. That
+ * is the half of the report an author acts on: a fault is usually a mistyped or
+ * unbound root, and "which roots exist here" is the answer. It is therefore the
+ * one part of the copy that is NOT true on every surface — the callers below
+ * build genuinely different bags — and it was printed unconditionally in the
+ * node tier's spelling, so an app-shell author was sent to check `record` and
+ * `page.<var>`, which nothing at that tier binds.
+ *
+ * The alternative fix — generalising the copy to "whatever this surface binds"
+ * plus a docs link — was refused deliberately: the concrete root names are the
+ * whole value of the paragraph, and advice that names no roots is correct
+ * everywhere and useful nowhere.
+ *
+ * Deducing the tier from the `type` slot was refused too. `type` carries the
+ * SCHEMA NODE TYPE at the node tier and a surface label at the other two
+ * (`page:tabs`, `app-shell:visible`), and `page:tabs` is a real registry key —
+ * so a `page:tabs` NODE faulting its own `visibleWhen` inside `SchemaRenderer`
+ * is indistinguishable, by `type` alone, from one of its ITEM predicates. An
+ * explicit argument cannot collide that way.
+ *
+ * ## The tiers, each derived from the code that builds the bag
+ *
+ * `'page-component'` — the node gate. `SchemaRenderer.tsx` builds
+ * `new ExpressionEvaluator({ ...predicateScope, current_user, [record], data,
+ * page })`, so the roots the SPEC declares for the tier (`ui/page.zod.ts`:
+ * *"Binds `record`, `current_user`, `page.<var>`"*) are the roots it binds.
+ * `page:tabs` ITEM predicates (`containers.tsx`) are this tier as well: they
+ * build the same three roots (plus the row spread flat, and `data` aliased to
+ * the row rather than to the adapter — both undeclared breadth that the spec
+ * does not promise and this paragraph therefore does not advertise).
+ *
+ * `'app-shell'` — the chrome gate. `ExpressionProvider.tsx` builds
+ * `{ current_user, user, ctx: { user }, os: { user }, features }`.
+ * There is no `record` and no `page` in it at all, which is the defect this
+ * type exists to fix. The four identity spellings are the ADR-0068 aliases and
+ * all four resolve; `features` is the deployment-flag root that provider's own
+ * docblock documents for exactly this kind of predicate.
+ *
+ * ⛔ No `app`. It was in that bag and in the paragraph below until
+ * objectui#8155 (ruled 2026-09-07): neither ADR-0068 nor
+ * `@objectstack/formula`'s `SCOPE_ROOTS` declares such a root, so
+ * `buildExpressionScope` stopped binding it. Naming it here would be worse
+ * than stale — this paragraph is printed at the exact moment a saved `app.*`
+ * predicate faults, so it would answer "why did my predicate not resolve?"
+ * with the root that is the reason.
+ *
+ * ⛔ No `data` either, since objectui#8166 (ruled 2026-09-10). It WAS bound at
+ * the app-shell tier and was already withheld from the paragraph below, on the
+ * grounds that every `ExpressionProvider` mount passes `data={{}}` — but
+ * `AppContent`'s own field-list evaluator passed the record under edit, so on
+ * that one leg an authored `data.*` resolved silently against the host's record
+ * instead of faulting. `buildExpressionScope` stopped binding it; a `data.*`
+ * predicate at this tier now reaches this reporter with the engine's
+ * `Unknown variable: data`, the same verdict the server gives it.
+ */
+export type PredicateScopeTier = 'page-component' | 'app-shell';
+/**
+ * WHICH GATE the faulting predicate was authored on (objectui#6445).
+ *
+ * ## Why the reporter has to be told, when it already prints the key
+ *
+ * `evaluateCondition` answers an unevaluable predicate with `true` on every one
+ * of its paths, and every caller reproduces that answer. What that `true` DOES
+ * to the node is not a property of the predicate - it is a property of the gate
+ * it was authored on, and the consequence paragraph has to say which:
+ *
+ * `'visibility'` - the visibility chain. Its `true` means SHOWN on the four
+ * negated legs, so the safe default does NOT bite: a predicate that could not be
+ * evaluated reads on screen exactly like one that said yes, which is why the
+ * console line is the only signal an author gets.
+ *
+ * `'enablement'` - `disabled` / `disabledOn`. The SAME `true` GREYS THE CONTROL
+ * OUT, so here the safe default is the one that BITES. The author is looking at
+ * a control they can see and cannot use; telling them the gate did not bite
+ * would be the opposite of what is on their screen, and would send them looking
+ * for a rendering bug rather than at their own predicate.
+ *
+ * ## Why a parameter, and not deduced from `key`
+ *
+ * Same reason {@link PredicateScopeTier} is a parameter (read its docblock): the
+ * caller knows, and a deduction is a table that goes quietly wrong the moment a
+ * spelling arrives that it has not heard of - a new alias, or a caller outside
+ * this repo - which would inherit a consequence sentence written about some
+ * other gate. That is the exact defect class this card and objectui#6487 both
+ * exist to remove, so it is not worth re-introducing to save an argument.
+ *
+ * `'concealment'` - `hidden` / `hiddenOn` (objectui#6503). These are visibility
+ * legs, but the only two whose verdict `SchemaRenderer` does NOT negate, so the
+ * SAME `true` that SHOWS a node on the four negated legs REMOVES it here. They
+ * resolved to `'visibility'` until objectui#6503 and were therefore handed the
+ * one sentence that is false about them: the gate did not merely bite, it bit
+ * hardest of the three, and the node is not on screen to be inspected at all.
+ * This is the third member objectui#6445's docblock predicted, in the shape it
+ * predicted - a table entry and a routing decision, no signature change.
+ *
+ * ## Why a third MEMBER, and not `'visibility'` plus a `negated` flag
+ *
+ * What varies is the consequence sentence, and it varies per GATE - not along
+ * an independent axis a caller could set to contradict the gate it passed
+ * alongside. Three flat members cannot be spelled inconsistently; a
+ * `(kind, negated)` pair can, and `('enablement', negated: true)` would name a
+ * combination no renderer in this repo produces. The table stays the one place
+ * that decides what a fail-soft default DID.
+ *
+ * ## What widening this union costs, stated because it is a published surface
+ *
+ * `PredicateGateKind` is re-exported from `packages/react/src/index.ts` - the
+ * package entry, and the chain stops there (no sibling package re-exports it,
+ * and no file outside `packages/react` names it). A consumer switching
+ * EXHAUSTIVELY over the union, or holding a `Record<PredicateGateKind, ...>`,
+ * gains a third case to answer. That is a type-level change only: no runtime
+ * signature moved, and every value that was accepted before still is.
+ */
+export type PredicateGateKind = 'visibility' | 'enablement' | 'concealment';
+/**
+ * Build the message. Separate from the emit so a test can assert the words,
+ * not merely that something was logged.
+ *
+ * `tier` defaults to `'page-component'` and `gate` to `'visibility'` so the
+ * historical five-argument call keeps printing the exact bytes it printed
+ * before (objectui#6487, objectui#6445) — the defaults are a compatibility
+ * shim for callers outside this repo, not something this repo leans on: every
+ * in-repo call site passes both explicitly, which is what makes each one a
+ * stated decision rather than an inherited one.
+ */
+export declare function formatUnresolvableVisibilityMessage(type: unknown, id: unknown, key: string, raw: unknown, reason: string, tier?: PredicateScopeTier, gate?: PredicateGateKind): string;
+/**
+ * Reports a NODE-GATE predicate that could not be evaluated — in DEVELOPMENT
+ * AND IN PRODUCTION since objectui#6038 (maintainer ruling 2026-08-25, option
+ * B: "the silence is no longer an accepted property").
+ *
+ * The visibility chain was the first gate wired to it and is still the default
+ * {@link PredicateGateKind}; `disabled` / `disabledOn` joined it in
+ * objectui#6445, which is why the name is now narrower than the function. It is
+ * kept anyway: this symbol is exported from the package entry and called from
+ * `@object-ui/app-shell` and `@object-ui/components`, so renaming it would be a
+ * cross-package edit that changes no behaviour, on a card scoped to one file's
+ * wiring. What has to stay true is the posture the name once described — ONE
+ * reporter, ONE dedupe `Set`, ONE severity, ONE reset — and a second reporter
+ * for the second gate is exactly what that rules out.
+ *
+ * `console.warn`, not `error`: the verdict is unchanged and the page still
+ * renders, so this is a diagnostic about a predicate — not the refusal
+ * `reportUnevaluatedExpressions` emits once raw source has reached the DOM.
+ *
+ * ## `err` takes a reason, not only an `Error`
+ *
+ * The dev caller catches a throw and passes the `Error`; the production caller
+ * is handed the evaluator's own reason STRING through `EvaluationOptions.onFault`
+ * (no throw is raised there, because raising one would cost a second
+ * evaluation). `String(err)` already covered that shape, so both callers reach
+ * the same `Reason:` text and the same dedupe entry — which is what makes "dev
+ * and production print the identical line" true rather than approximately true.
+ *
+ * ## `tier` is NOT in the dedupe key, and that is not an oversight
+ *
+ * The key stays `(type, key, predicate source)` — the rate limit objectui#6038
+ * pinned in both directions. Adding `tier` could only ever LOOSEN it, and it
+ * would take a `type` shared across two tiers to loosen anything: the app-shell
+ * site's `type` is the constant `'app-shell:visible'`, which no node tier can
+ * produce, and the two `'page-component'` callers are the same tier by
+ * definition. So the tier is free of the key by measurement, not by assumption.
+ *
+ * ## Neither is `gate`, and for a stronger reason (objectui#6445)
+ *
+ * `gate` is a FUNCTION of `key`, which is already in the dedupe key: the
+ * enablement gate is exactly `disabled` / `disabledOn` and the visibility gate
+ * is exactly the six legs of the visibility chain, two disjoint sets. So adding
+ * it could not separate two entries that `key` does not already separate, and
+ * the cross-gate direction is pinned rather than argued: the SAME predicate
+ * source authored on `disabled` and on `visibleWhen` produces TWO lines, not
+ * one - the new reporting site cannot be swallowed by a visibility entry, and
+ * cannot swallow one.
+ */
+export declare function reportUnresolvableVisibilityPredicate(type: unknown, id: unknown, key: string, raw: unknown, err: unknown, tier?: PredicateScopeTier, gate?: PredicateGateKind): void;
+/**
+ * Test-only reset for the dedupe above — for BOTH legs, which is the point of
+ * their sharing one `Set`. The `Set` is module state: without this, the second
+ * test to assert the same warning reads the first test's dedupe entry and sees
+ * silence — a green run that checked nothing.
+ */
+export declare function __resetVisibilityPredicateWarnings(): void;
+/**
+ * Prefix for the objectui#5687 leg. A SIBLING of the constant above, not a
+ * reuse of it, and the difference is deliberate.
+ *
+ * The maintainer ruling (2026-08-22, option A) says this path "emits the
+ * dev-only unresolvable-predicate report". What is load-bearing there — and
+ * what the dispatch restated — is the reporter's POSTURE: same module, same
+ * severity (`console.warn`), same dedupe key shape, same dedupe Set, same
+ * gate at the same call site, same test-only reset. All of that is shared
+ * below.
+ *
+ * ⚠️ The two legs stopped sharing that gate's VALUE in objectui#6038, and only
+ * that. The unresolvable leg now reports in production as well, because the
+ * 2026-08-25 ruling retired its silence; THIS leg stays dev-only under its own
+ * 2026-08-22 ruling, and the difference is not an oversight. A fault is a
+ * predicate that could not be evaluated, and shipping a live gate that has
+ * stopped biting is the class-1 defect production has to be able to see. This
+ * leg reports something else: a predicate that evaluated perfectly, against the
+ * wrong object. Its trigger is a LEXICAL scan of the predicate source with a
+ * stated false-positive residue (the deliberate-absence idioms below), which is
+ * a cost worth paying for an author at their keyboard and not for every user of
+ * every production page. The first LINE is not reused, because on this path it would
+ * state something false: the predicate did not fail to evaluate. It evaluated
+ * perfectly, against the wrong object, and produced a constant. Telling an
+ * author "could not be evaluated" would send them hunting for a syntax error
+ * that is not there.
+ */
+export declare const ADAPTER_ONLY_DATA_PREDICATE_PREFIX = "[ObjectUI] A visibility predicate read `data.*` that the bound `data` does not answer";
+/**
+ * The `disabled` / `disabledOn` sibling of the prefix above (objectui#6504,
+ * maintainer ruling 2026-08-27 option A). Same reason
+ * {@link UNRESOLVABLE_ENABLEMENT_PREFIX} is a sibling of
+ * {@link UNRESOLVABLE_VISIBILITY_PREFIX} rather than a reuse: calling a
+ * `disabled` predicate "a visibility predicate" would send an author to the
+ * wrong gate on the first line — the one line a console filter and a `grep`
+ * both read.
+ */
+export declare const ADAPTER_ONLY_ENABLEMENT_PREDICATE_PREFIX = "[ObjectUI] An enablement predicate read `data.*` that the bound `data` does not answer";
+/**
+ * Which gates the objectui#5687 constant-predicate diagnostic is wired to
+ * (objectui#6504, maintainer ruling 2026-08-27 option A: extend to the
+ * enablement gate, dev-only; option C — always-on — was excluded, outside
+ * the #5687 precedent).
+ *
+ * A NARROWER union than {@link PredicateGateKind} deliberately, not an
+ * oversight: `'concealment'` (`hidden` / `hiddenOn`) is not one of them. Both
+ * of this diagnostic's call sites are unchanged by this card — the visibility
+ * one (`SchemaRenderer.tsx`'s `evaluateVisibilityPredicate`) still calls
+ * {@link reportAdapterOnlyDataPredicate} with no `gate` argument at all, for
+ * the six-leg chain exactly as objectui#5687 shipped it, so `'concealment'`
+ * was never a value this table had to answer for. Giving it an entry nobody
+ * can reach would be a decision this ruling did not make; widening this type
+ * later is a decision for whichever card makes that call, not a `??` for this
+ * table to paper over now.
+ */
+export type AdapterOnlyPredicateGateKind = Extract<PredicateGateKind, 'visibility' | 'enablement'>;
+/**
+ * Built separately from the emit, for the same reason as the message above.
+ *
+ * `gate` defaults to `'visibility'` so the historical four-argument call
+ * (objectui#5687) keeps printing the exact bytes it printed before —
+ * objectui#6504's own call site in `evaluateVisibilityPredicate`
+ * (`SchemaRenderer.tsx`) is one of those unchanged callers, passing no `gate`
+ * at all. `evaluateEnablementPredicate` is the one caller that states
+ * `'enablement'` explicitly, matching {@link formatUnresolvableVisibilityMessage}'s
+ * own compatibility-default pattern.
+ */
+export declare function formatAdapterOnlyDataMessage(type: unknown, id: unknown, key: string, raw: unknown, unresolved: string[], gate?: AdapterOnlyPredicateGateKind): string;
+/**
+ * Dev-build diagnostic for a node-gate predicate that reads `data.*` and gets
+ * `undefined` back from the adapter (objectui#5687, maintainer ruling
+ * 2026-08-22 option A).
+ *
+ * ## It changes NO verdict, and it is not allowed to
+ *
+ * The ruling is explicit that the node tier keeps its documented
+ * `data` = adapter semantics: no verdict change, no interpolation change. This
+ * function returns `void`, is called for its console output only, and the
+ * caller passes the evaluator's answer through untouched. The constant-false
+ * still hides the block; the author now hears about it.
+ *
+ * ## Why it lives beside `reportUnresolvableVisibilityPredicate`
+ *
+ * They are two halves of ONE silence. objectui#5454 made the THROWING paths
+ * loud; measured on this base, a `{ dialect: 'cel' }` envelope reading
+ * `data.status` already throws and is already reported by that function. The
+ * bare-string and `${…}` template dialects do not throw for the same
+ * predicate — they resolve `undefined == 'draft'` to a clean `false` — so the
+ * author heard about the identical authoring mistake only if they happened to
+ * write it in the CEL dialect. That is the same dialect-dependent arbitrariness
+ * objectui#5454 existed to remove, one path further along.
+ *
+ * Sharing the module means sharing the LIFECYCLE, which is the part that has to
+ * match: one dedupe Set, one reset, one severity. (One gate, too, until
+ * objectui#6038 — see the prefix constant above for why only the sibling leg
+ * crossed into production.) The dedupe
+ * key is tagged with this leg's name so the two diagnostics cannot silence each
+ * other for the same (type, key, source) triple — they are different faults,
+ * and a node that faults one way is not evidence about the other.
+ *
+ * ## `gate` (objectui#6504) — NOT in the dedupe key, for the reason
+ * {@link reportUnresolvableVisibilityPredicate}'s own docblock gives for the
+ * same omission
+ *
+ * `gate` is a FUNCTION of `key`: the enablement gate is exactly `disabled` /
+ * `disabledOn` and the visibility gate this leg is called for is the six-leg
+ * chain, two disjoint sets. Adding it to the dedupe key could not separate two
+ * entries `key` does not already separate — and the cross-gate direction is
+ * the one that would matter if it could: the SAME predicate source authored on
+ * `disabled` and on (say) `visibleWhen` must produce TWO lines, which it does
+ * today because `key` differs, with or without `gate` in the tuple.
+ *
+ * Defaults to `'visibility'` — the objectui#5687 call site
+ * (`evaluateVisibilityPredicate`) is unchanged by this card and still calls
+ * this function with five arguments.
+ */
+export declare function reportAdapterOnlyDataPredicate(type: unknown, id: unknown, key: string, raw: unknown, boundData: unknown, gate?: AdapterOnlyPredicateGateKind): void;