@object-ui/core 17.5.0 → 17.7.0

package/dist/utils/filter-tokens.d.ts

@@ -16,7 +16,7 @@ import { CONTEXT_TOKENS } from '@objectstack/spec/data';
  *
  *     { owner_id: '{current_user_id}' }
  *
- * ## Why this module exists (framework #3574)
+ * ## Why this module exists (objectstack-ai/objectstack#3574)
  *
  * There used to be no shared resolver. Three ad-hoc implementations had grown
  * up independently — one in `ObjectView` for list views, one in
@@ -40,6 +40,25 @@ import { CONTEXT_TOKENS } from '@objectstack/spec/data';
  * Dropping a `{current_user_id}` filter widens a view; it must never widen
  * access. Never use a context token as an access control.
  *
+ * ## `{record_id}` — the record in view, not the session (objectui#7297)
+ *
+ * `@objectstack/spec` declares one sibling of the two session tokens:
+ * `RECORD_CONTEXT_TOKENS` = `{record_id}`, the id of the record a
+ * `type: 'record'` page is showing (objectstack-ai/objectstack#20003). It is a
+ * separate list, not a member of `CONTEXT_TOKENS`, because it resolves against
+ * the SURFACE rather than the session, and only here: the server never knows
+ * which record a page shows, so it refuses a filter still carrying the token
+ * by name (`FILTER_TOKEN_UNRESOLVED`).
+ *
+ * Its value is `FilterTokenScope.recordId`, which `useFilterScope()` in
+ * `@object-ui/react` fills from the mounted `RecordContextProvider` and from
+ * nothing else — never a URL parameter, never a page variable. With no record
+ * in scope the token is refused by name through `onUnresolved`, in the voice
+ * an unresolved session token gets, and left as written: it never becomes
+ * `null` (a count about nobody) and its condition is never dropped (a count
+ * about everybody). Like the session tokens it scopes what a record page
+ * SHOWS; which of those rows the caller may read is still RLS's decision.
+ *
  * ## Contract source
  *
  * The canonical vocabulary is published as part of the platform contract at
@@ -53,6 +72,20 @@ import { CONTEXT_TOKENS } from '@objectstack/spec/data';
  * copy was byte-identical, so every value comparison and every behavioural
  * test passed while it sat here. Reference identity is the one check that
  * distinguishes a re-export from a fork (objectui#3003).
+ *
+ * The same argument retired the two module-local copies that sat beside it
+ * until objectui#7265 — the near-miss suggestion map and the membership
+ * predicate are imported from `@objectstack/spec/data` now, so neither can
+ * drift either. Both were re-measured against the RESOLVED pin (17.4.0; the
+ * card had measured 17.2.0) before the swap, because "byte-identical" is a
+ * statement about a version, not a property: the map matched on nine keys, in
+ * the same order, with the same values, and the two predicates agreed on every
+ * one of 61 real vocabulary members — the token tuple, both suggestion key
+ * sets, the date-macro tokens and their aliases, plus casing, whitespace and
+ * prototype-key spellings. Each comparison ran a lit control of the same kind
+ * through the same comparator (the spec's own token-description map, and its
+ * date-macro predicate), so "no difference" came from an instrument shown able
+ * to report one.
  */
 /** The complete set of session-scoped filter tokens (spec-owned, re-exported). */
 export { CONTEXT_TOKENS };
@@ -63,15 +96,26 @@ export interface FilterTokenScope {
     currentUserId?: string | null;
     /** The active organization id. */
     currentOrgId?: string | null;
+    /**
+     * The id of the record the surface is bound to, which resolves
+     * `{record_id}` (objectui#7297): the mounted record context of a
+     * `type: 'record'` page. `useFilterScope()` in `@object-ui/react` fills it
+     * from the nearest `RecordContextProvider`, and a host that renders no
+     * record leaves it unset, so the token is refused there. ⛔ Never fill it
+     * from a URL parameter or a page variable.
+     */
+    recordId?: string | null;
     /**
      * Called when a placeholder cannot be resolved — either a recognised token
-     * with no value in scope (signed out), or a near-miss spelling that resolves
-     * in no vocabulary. Defaults to a `console.warn`; pass `null` to silence.
+     * with no value in scope (signed out, or no record in context), or a
+     * near-miss spelling that resolves in no vocabulary. Defaults to a
+     * `console.warn`; pass `null` to silence.
      */
     onUnresolved?: ((message: string) => void) | null;
 }
 /**
- * Expand `{current_user_id}` / `{current_org_id}` inside a filter.
+ * Expand `{current_user_id}` / `{current_org_id}`, and `{record_id}` where a
+ * record is in scope, inside a filter.
  *
  * Walks arrays and plain objects recursively, which is what makes one
  * resolver cover both platform filter shapes: the MongoDB-style object a
@@ -98,7 +142,7 @@ export declare function resolveContextTokens<T = any>(filter: T, scope?: FilterT
  * macros and context tokens — in one call.
  *
  * This is the function surfaces should call. Calling only one of the two
- * resolvers is the defect behind framework #3574: dashboard widgets called
+ * resolvers is the defect behind objectstack-ai/objectstack#3574: dashboard widgets called
  * `resolveDateMacros` alone, so `{today}` worked and `{current_user_id}`
  * silently did not.
  *

package/dist/utils/filter-tokens.js

@@ -5,7 +5,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { CONTEXT_TOKENS } from '@objectstack/spec/data';
+import { CONTEXT_TOKENS, CONTEXT_TOKEN_SUGGESTIONS, isContextToken, isRecordContextToken, } from '@objectstack/spec/data';
 import { resolveDateMacros } from './date-macros.js';
 /**
  * Session-scoped filter placeholders — the sibling vocabulary to
@@ -17,7 +17,7 @@ import { resolveDateMacros } from './date-macros.js';
  *
  *     { owner_id: '{current_user_id}' }
  *
- * ## Why this module exists (framework #3574)
+ * ## Why this module exists (objectstack-ai/objectstack#3574)
  *
  * There used to be no shared resolver. Three ad-hoc implementations had grown
  * up independently — one in `ObjectView` for list views, one in
@@ -41,6 +41,25 @@ import { resolveDateMacros } from './date-macros.js';
  * Dropping a `{current_user_id}` filter widens a view; it must never widen
  * access. Never use a context token as an access control.
  *
+ * ## `{record_id}` — the record in view, not the session (objectui#7297)
+ *
+ * `@objectstack/spec` declares one sibling of the two session tokens:
+ * `RECORD_CONTEXT_TOKENS` = `{record_id}`, the id of the record a
+ * `type: 'record'` page is showing (objectstack-ai/objectstack#20003). It is a
+ * separate list, not a member of `CONTEXT_TOKENS`, because it resolves against
+ * the SURFACE rather than the session, and only here: the server never knows
+ * which record a page shows, so it refuses a filter still carrying the token
+ * by name (`FILTER_TOKEN_UNRESOLVED`).
+ *
+ * Its value is `FilterTokenScope.recordId`, which `useFilterScope()` in
+ * `@object-ui/react` fills from the mounted `RecordContextProvider` and from
+ * nothing else — never a URL parameter, never a page variable. With no record
+ * in scope the token is refused by name through `onUnresolved`, in the voice
+ * an unresolved session token gets, and left as written: it never becomes
+ * `null` (a count about nobody) and its condition is never dropped (a count
+ * about everybody). Like the session tokens it scopes what a record page
+ * SHOWS; which of those rows the caller may read is still RLS's decision.
+ *
  * ## Contract source
  *
  * The canonical vocabulary is published as part of the platform contract at
@@ -54,40 +73,47 @@ import { resolveDateMacros } from './date-macros.js';
  * copy was byte-identical, so every value comparison and every behavioural
  * test passed while it sat here. Reference identity is the one check that
  * distinguishes a re-export from a fork (objectui#3003).
+ *
+ * The same argument retired the two module-local copies that sat beside it
+ * until objectui#7265 — the near-miss suggestion map and the membership
+ * predicate are imported from `@objectstack/spec/data` now, so neither can
+ * drift either. Both were re-measured against the RESOLVED pin (17.4.0; the
+ * card had measured 17.2.0) before the swap, because "byte-identical" is a
+ * statement about a version, not a property: the map matched on nine keys, in
+ * the same order, with the same values, and the two predicates agreed on every
+ * one of 61 real vocabulary members — the token tuple, both suggestion key
+ * sets, the date-macro tokens and their aliases, plus casing, whitespace and
+ * prototype-key spellings. Each comparison ran a lit control of the same kind
+ * through the same comparator (the spec's own token-description map, and its
+ * date-macro predicate), so "no difference" came from an instrument shown able
+ * to report one.
  */
 /** The complete set of session-scoped filter tokens (spec-owned, re-exported). */
 export { CONTEXT_TOKENS };
-/**
- * Near-miss spellings → the token the author meant.
- *
- * Every entry is a real authoring mistake, and each is a correct spelling
- * *somewhere else* in the platform, which is exactly why authors reach for it:
- * `current_user` is the RLS expression root, `{user_id}` is valid
- * `titleFormat` field interpolation, `organization_id` is a real column name.
- *
- * Mirrors `CONTEXT_TOKEN_SUGGESTIONS` in `@objectstack/spec`. Used only to
- * make the runtime warning actionable; the authoring-time gate
- * (`validateFilterTokens` in `@objectstack/lint`) is what actually prevents
- * these from shipping.
- */
-const CONTEXT_TOKEN_SUGGESTIONS = {
-    current_user: 'current_user_id',
-    current_user_email: 'current_user_id',
-    user_id: 'current_user_id',
-    userid: 'current_user_id',
-    me: 'current_user_id',
-    current_organization_id: 'current_org_id',
-    org_id: 'current_org_id',
-    organization_id: 'current_org_id',
-    current_tenant_id: 'current_org_id',
-};
 /** Whole-string placeholder: `{token}` or `${token}`, anchored. */
 const WHOLE_TOKEN_RE = /^\$?\{([a-zA-Z0-9_]+)\}$/;
-function isContextToken(token) {
-    return CONTEXT_TOKENS.includes(token);
-}
 /**
- * Expand `{current_user_id}` / `{current_org_id}` inside a filter.
+ * A null-prototype copy of the spec's near-miss suggestion map (objectui#9129).
+ *
+ * `CONTEXT_TOKEN_SUGGESTIONS` is a plain object, so indexing it with an
+ * author-controlled, lower-cased string reaches `Object.prototype` for any
+ * spelling that happens to be an inherited member name — `constructor` and
+ * `__proto__` today, and, silently, whichever future member is added in
+ * lower case (see the lookup below). This is a read-only console hint, never
+ * an assignment, so no filter value is ever widened, narrowed or mismatched
+ * by it; the only externally visible effect of the underlying bug is a
+ * confusing suggestion string in a `warn()` call.
+ *
+ * Copying into an `Object.create(null)` base closes the whole class rather
+ * than special-casing the two spellings measured today: this object has no
+ * prototype at all, so *no* key — known or future — can resolve through it.
+ * `@objectstack/spec`'s own map is left untouched (out of scope here; the
+ * identical shape in its `classifyFilterToken` is the one objectstack `4342c9923` closed).
+ */
+const NEAR_MISS_SUGGESTIONS = Object.assign(Object.create(null), CONTEXT_TOKEN_SUGGESTIONS);
+/**
+ * Expand `{current_user_id}` / `{current_org_id}`, and `{record_id}` where a
+ * record is in scope, inside a filter.
  *
  * Walks arrays and plain objects recursively, which is what makes one
  * resolver cover both platform filter shapes: the MongoDB-style object a
@@ -111,18 +137,30 @@ function isContextToken(token) {
 export function resolveContextTokens(filter, scope = {}) {
     if (filter == null)
         return filter;
-    const { currentUserId, currentOrgId } = scope;
+    const { currentUserId, currentOrgId, recordId } = scope;
     const warn = scope.onUnresolved === null
         ? () => { }
         : scope.onUnresolved ??
             ((message) => {
-                // eslint-disable-next-line no-console
                 console.warn(`[object-ui] ${message}`);
             });
+    // Annotated `Record<string, …>` because the spec's predicate returns a plain
+    // `boolean`, not the narrowing `token is ContextTokenName` the deleted local
+    // copy declared, so the narrowed branch below hands this lookup a `string`.
+    // The `satisfies` clause keeps the one thing that narrowing bought: a third
+    // context token in the spec reds this literal at compile time instead of
+    // resolving to `undefined` at runtime.
     const values = {
         current_user_id: currentUserId,
         current_org_id: currentOrgId,
     };
+    // The record-context sibling, kept apart for the reason the spec keeps the
+    // two lists apart: it is filled from the record in view, never from the
+    // session. The same `satisfies` ratchet: a second record-context token in
+    // the spec reds this literal at compile time.
+    const recordValues = {
+        record_id: recordId,
+    };
     const walk = (value) => {
         if (value == null)
             return value;
@@ -138,10 +176,36 @@ export function resolveContextTokens(filter, scope = {}) {
                 warn(`Filter placeholder "{${token}}" could not be resolved — no ${token === 'current_user_id' ? 'signed-in user' : 'active organization'} in scope. The filter will match no records.`);
                 return value;
             }
+            // `{record_id}` (objectui#7297). Resolved only from the record in scope.
+            // With none, it is refused BY NAME, in the voice of the unresolved
+            // session token above, and left as written: never `null` (a count about
+            // nobody), never dropped (a count about everybody), and never reported as
+            // an unknown spelling, because the spelling is right and the surface is
+            // not. The ObjectStack server then refuses the same filter by name
+            // (`FILTER_TOKEN_UNRESOLVED`), since no server path has a record in view.
+            if (isRecordContextToken(token)) {
+                const resolved = recordValues[token];
+                if (resolved != null && resolved !== '')
+                    return resolved;
+                warn(`Filter placeholder "{${token}}" could not be resolved — no record in context ` +
+                    `on this surface. It resolves only on a component of a \`type: 'record'\` page, ` +
+                    `to the id of the record that page shows. It is left as written, so the filter ` +
+                    `never widens: the server refuses it by name, and a backend with no resolver ` +
+                    `matches no records.`);
+                return value;
+            }
             // Not ours. Warn only for near-misses, which resolve in no vocabulary
             // at all and would otherwise fail silently; genuine date macros and
             // nav context-selector ids must pass through quietly.
-            const suggestion = CONTEXT_TOKEN_SUGGESTIONS[token.toLowerCase()];
+            //
+            // Every spelling in the imported map is a real authoring mistake, and
+            // each is a correct spelling *somewhere else* in the platform, which is
+            // exactly why authors reach for it: `current_user` is the RLS expression
+            // root, `{user_id}` is valid `titleFormat` field interpolation,
+            // `organization_id` is a real column name. The map only makes the runtime
+            // warning actionable; the authoring-time gate (`validateFilterTokens` in
+            // `@objectstack/lint`) is what actually prevents these from shipping.
+            const suggestion = NEAR_MISS_SUGGESTIONS[token.toLowerCase()];
             if (suggestion) {
                 warn(`Filter placeholder "{${token}}" is not a recognised token — did you mean ` +
                     `"{${suggestion}}"? It is sent to the server as a literal string and will ` +
@@ -151,7 +215,14 @@ export function resolveContextTokens(filter, scope = {}) {
         }
         if (Array.isArray(value))
             return value.map(walk);
+        // Only a PLAIN object (prototype `Object.prototype` or `null`) is a bag to
+        // walk. Anything else is a leaf, returned as the same instance: rebuilding
+        // a `Date` from its own keys — it has none — turned a comparand the spec
+        // admits (`ACCEPTED_FILTER_COMPARAND_TYPES`) into `{}` (objectui#10506).
         if (typeof value === 'object') {
+            const proto = Object.getPrototypeOf(value);
+            if (proto !== Object.prototype && proto !== null)
+                return value;
             const out = {};
             for (const k of Object.keys(value))
                 out[k] = walk(value[k]);
@@ -166,7 +237,7 @@ export function resolveContextTokens(filter, scope = {}) {
  * macros and context tokens — in one call.
  *
  * This is the function surfaces should call. Calling only one of the two
- * resolvers is the defect behind framework #3574: dashboard widgets called
+ * resolvers is the defect behind objectstack-ai/objectstack#3574: dashboard widgets called
  * `resolveDateMacros` alone, so `{today}` worked and `{current_user_id}`
  * silently did not.
  *

package/dist/utils/freeze-schema.d.ts

@@ -36,6 +36,33 @@ export declare const SYSTEM_VIEW_MARKER: unique symbol;
 export type DeepReadonly<T> = T extends (...args: any[]) => any ? T : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepReadonly<U>> : T extends object ? {
     readonly [K in keyof T]: DeepReadonly<T[K]>;
 } : T;
+/**
+ * The inverse of `DeepReadonly<T>`: recursively strip `readonly` at every depth.
+ *
+ * Named `DeepMutable` rather than `Mutable` for the same reason the type above
+ * is not called `Readonly` — TS' built-in `Readonly<T>` is SHALLOW, so a bare
+ * `Mutable` would understate what this does by exactly the depth gap that made
+ * `cloneAsOverride` wrong in the first place. A type whose name misreports its
+ * own reach is the defect this pair exists to close, not a naming preference.
+ *
+ * Symmetric with `DeepReadonly` arm for arm, deliberately including its two
+ * limits: a tuple widens to an array (`DeepReadonly` widens it the same way, so
+ * an inverse that preserved tuples would not be an inverse), and `Date`,
+ * `RegExp`, `Map` and `Set` are mapped as plain objects even though
+ * `isFreezableObject` skips them at runtime.
+ *
+ * One thing it deliberately does NOT do: drop the `SYSTEM_VIEW_MARKER` key.
+ * `cloneAsOverride` never copies the symbol, so a clone's marker is always
+ * absent — but the key is declared optional (`?: true`), and carrying it
+ * therefore states "may be absent", which is true. Excluding it needs
+ * `Exclude<keyof T, typeof SYSTEM_VIEW_MARKER>`, a NON-homomorphic mapped type
+ * that drops the `?` modifier from every other property and turns optional keys
+ * required — a strictly worse type, and a real break for callers, traded for
+ * removing a key that already reads as optional.
+ */
+export type DeepMutable<T> = T extends (...args: any[]) => any ? T : T extends ReadonlyArray<infer U> ? DeepMutable<U>[] : T extends object ? {
+    -readonly [K in keyof T]: DeepMutable<T[K]>;
+} : T;
 /**
  * A schema that has been frozen by `defineSystemView()`. The marker symbol is
  * non-enumerable and therefore invisible to consumers, but its presence
@@ -87,8 +114,18 @@ export declare function isSystemView(value: unknown): boolean;
  * Produce a deep, mutable clone of a System View so callers can apply
  * Tenant/User overrides without touching the source schema.
  *
+ * Returns `DeepMutable<T>`, not `T`. The declaration used to hand back the
+ * input type unchanged, which meant cloning a `SystemView<S>` returned
+ * something still typed deep-readonly even though the implementation had always
+ * produced a plain mutable object — so the override flow this function exists
+ * for, `draft.columns.push(...)`, did not type-check (TS2339). The return type
+ * now relaxes TOWARD what the runtime already does, never away from it, which
+ * is why the change adds capability to a caller's type rather than removing it.
+ *
  * Implementation note: uses `structuredClone` when available (Node 17+, all
  * evergreen browsers) and falls back to a JSON round-trip. The marker
  * symbol is intentionally NOT copied — the clone is no longer a System View.
+ * Neither path can copy it by accident: `structuredClone` ignores symbol keys,
+ * and `JSON.stringify` never sees them.
  */
-export declare function cloneAsOverride<T>(view: T): T;
+export declare function cloneAsOverride<T>(view: T): DeepMutable<T>;

package/dist/utils/freeze-schema.js

@@ -140,9 +140,19 @@ export function isSystemView(value) {
  * Produce a deep, mutable clone of a System View so callers can apply
  * Tenant/User overrides without touching the source schema.
  *
+ * Returns `DeepMutable<T>`, not `T`. The declaration used to hand back the
+ * input type unchanged, which meant cloning a `SystemView<S>` returned
+ * something still typed deep-readonly even though the implementation had always
+ * produced a plain mutable object — so the override flow this function exists
+ * for, `draft.columns.push(...)`, did not type-check (TS2339). The return type
+ * now relaxes TOWARD what the runtime already does, never away from it, which
+ * is why the change adds capability to a caller's type rather than removing it.
+ *
  * Implementation note: uses `structuredClone` when available (Node 17+, all
  * evergreen browsers) and falls back to a JSON round-trip. The marker
  * symbol is intentionally NOT copied — the clone is no longer a System View.
+ * Neither path can copy it by accident: `structuredClone` ignores symbol keys,
+ * and `JSON.stringify` never sees them.
  */
 export function cloneAsOverride(view) {
     if (view == null || typeof view !== 'object')

package/dist/utils/grouping-fields.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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.
+ */
+/**
+ * The THIRD half of a view's field appetite (objectui#7179).
+ *
+ * A list view projects what it DISPLAYS — `$select` is built from `columns`.
+ * `predicate-fields.ts` covers the fields a view's PREDICATES read. This covers
+ * the fields it GROUPS BY, which is a third, independent source of demand: the
+ * spec's `grouping` block is a sibling of `columns`, not a subset of it, so a
+ * view may legitimately group by a field it never shows.
+ *
+ * ## Why it needed a fix rather than a gate
+ *
+ * `GroupingConfigSchema` accepts `grouping` with no matching column, and the
+ * neighbouring view kinds (kanban / gantt / timeline) already union their
+ * `groupByField` into the projection with no column required. Grouping by a
+ * field you do not want on screen is an ordinary thing to want. Refusing it at
+ * author time would make the grid the odd one out and reject working intent.
+ *
+ * ## The failure this closes
+ *
+ * With the grouping field absent from `$select` the server never returns it,
+ * so `useGroupedData` reads `undefined` on every row and `buildSegmentLabel`
+ * answers `(empty)` for all of them: ONE group holding every record, with no
+ * error, no warning and no empty state. It reads as "these records have no
+ * value for this field" — a plausible, wrong, actionable conclusion about the
+ * data rather than a visible bug in the view.
+ *
+ * ## ⛔ THE RESULT IS CANDIDATES, NOT VERIFIED FIELDS — the caller MUST gate it
+ *
+ * `GroupingFieldSchema.field` is a string that refuses a padded name
+ * (objectui#7347 — `grouping-field-padded-refused-7347.test.ts` in
+ * `@object-ui/types` pins it on every face declaring `grouping`; the trim below
+ * stays as defence for blocks that skipped that parse). Nothing in the schema
+ * requires it to name a field the object declares, and the whole premise of
+ * this harvest is that it has NOT been through column validation. Some backends
+ * answer an unknown `$select` key with an EMPTY RESULT SET rather than ignoring
+ * it — the cloud multi-tenant runtime does exactly that — so a single unknown
+ * grouping field put in the projection unguarded silently zeroes the whole
+ * list. That would convert this card's bug (one `(empty)` group holding every
+ * row) into a strictly worse one (no rows at all, still silent).
+ *
+ * So every caller intersects this result with the object's declared fields —
+ * {@link isProjectableField}, or the caller's equivalent known-field set —
+ * exactly as {@link collectPredicateFieldRefs}'s callers do, and for the same
+ * measured reason. Callers additionally FLS-gate it: a grouping field names a
+ * field just as capable of being denied as a column is, and the projection is
+ * what goes on the wire (objectui#6898).
+ *
+ * @param grouping - The view's `grouping` block in any authored state
+ *   (`undefined`, malformed, or the spec shape). Anything that is not an entry
+ *   carrying a non-empty string `field` contributes nothing, so a malformed
+ *   block yields an empty harvest instead of a plausible wrong name.
+ * @returns Grouping field names in first-seen order, deduplicated.
+ */
+export declare function collectGroupingFieldRefs(grouping: unknown): string[];

package/dist/utils/grouping-fields.js

@@ -0,0 +1,84 @@
+/**
+ * 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.
+ */
+/**
+ * The THIRD half of a view's field appetite (objectui#7179).
+ *
+ * A list view projects what it DISPLAYS — `$select` is built from `columns`.
+ * `predicate-fields.ts` covers the fields a view's PREDICATES read. This covers
+ * the fields it GROUPS BY, which is a third, independent source of demand: the
+ * spec's `grouping` block is a sibling of `columns`, not a subset of it, so a
+ * view may legitimately group by a field it never shows.
+ *
+ * ## Why it needed a fix rather than a gate
+ *
+ * `GroupingConfigSchema` accepts `grouping` with no matching column, and the
+ * neighbouring view kinds (kanban / gantt / timeline) already union their
+ * `groupByField` into the projection with no column required. Grouping by a
+ * field you do not want on screen is an ordinary thing to want. Refusing it at
+ * author time would make the grid the odd one out and reject working intent.
+ *
+ * ## The failure this closes
+ *
+ * With the grouping field absent from `$select` the server never returns it,
+ * so `useGroupedData` reads `undefined` on every row and `buildSegmentLabel`
+ * answers `(empty)` for all of them: ONE group holding every record, with no
+ * error, no warning and no empty state. It reads as "these records have no
+ * value for this field" — a plausible, wrong, actionable conclusion about the
+ * data rather than a visible bug in the view.
+ *
+ * ## ⛔ THE RESULT IS CANDIDATES, NOT VERIFIED FIELDS — the caller MUST gate it
+ *
+ * `GroupingFieldSchema.field` is a string that refuses a padded name
+ * (objectui#7347 — `grouping-field-padded-refused-7347.test.ts` in
+ * `@object-ui/types` pins it on every face declaring `grouping`; the trim below
+ * stays as defence for blocks that skipped that parse). Nothing in the schema
+ * requires it to name a field the object declares, and the whole premise of
+ * this harvest is that it has NOT been through column validation. Some backends
+ * answer an unknown `$select` key with an EMPTY RESULT SET rather than ignoring
+ * it — the cloud multi-tenant runtime does exactly that — so a single unknown
+ * grouping field put in the projection unguarded silently zeroes the whole
+ * list. That would convert this card's bug (one `(empty)` group holding every
+ * row) into a strictly worse one (no rows at all, still silent).
+ *
+ * So every caller intersects this result with the object's declared fields —
+ * {@link isProjectableField}, or the caller's equivalent known-field set —
+ * exactly as {@link collectPredicateFieldRefs}'s callers do, and for the same
+ * measured reason. Callers additionally FLS-gate it: a grouping field names a
+ * field just as capable of being denied as a column is, and the projection is
+ * what goes on the wire (objectui#6898).
+ *
+ * @param grouping - The view's `grouping` block in any authored state
+ *   (`undefined`, malformed, or the spec shape). Anything that is not an entry
+ *   carrying a non-empty string `field` contributes nothing, so a malformed
+ *   block yields an empty harvest instead of a plausible wrong name.
+ * @returns Grouping field names in first-seen order, deduplicated.
+ */
+export function collectGroupingFieldRefs(grouping) {
+    const fields = grouping?.fields;
+    if (!Array.isArray(fields))
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const entry of fields) {
+        // The spec shape is `{ field, order, collapsed }`. A bare string is NOT
+        // accepted here even though it would be a natural shorthand: `grouping` is
+        // a `$strict` object schema in `@objectstack/spec`, so a bare string is
+        // off-spec metadata, and reading it anyway would be exactly the lenient
+        // renderer-side alias AGENTS.md #0.1 forbids — it fossilizes a second
+        // de-facto contract instead of having the producer rejected at publish.
+        const name = entry?.field;
+        if (typeof name !== 'string')
+            continue;
+        const trimmed = name.trim();
+        if (!trimmed || seen.has(trimmed))
+            continue;
+        seen.add(trimmed);
+        out.push(trimmed);
+    }
+    return out;
+}

package/dist/utils/humanize-label.d.ts

@@ -0,0 +1,60 @@
+/**
+ * ObjectUI — value-fallback label prettifier
+ * 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.
+ */
+/**
+ * humanize-label — the ONE home for the VALUE fallback: a stored value becomes
+ * a display string when nothing else resolves it (objectui#5444).
+ *
+ * Two byte-identical copies preceded this module: `@object-ui/fields` (read by
+ * `plugin-grid`, `plugin-gantt`, `plugin-detail`, and by the field renderers in
+ * that package itself) and a deliberate local copy in `plugin-charts`'
+ * `ObjectChart.tsx`, whose comment said it existed "to avoid a dependency on
+ * `@object-ui/fields`". `@object-ui/core` is the shared ancestor both packages
+ * already depend on, so the convention gets a single home without a new
+ * dependency edge and without React reaching core — objectui#4389's ruling for
+ * this family: core-canonical logic, plugins consume; never core importing
+ * react. Both former sites now re-export THIS function, so there is one
+ * implementation and two doorways.
+ *
+ * ## Why this is NOT `humanizeFieldKey`, and why the two are kept apart
+ *
+ * The renderer carries a second prettifier — `humanizeFieldKey` in
+ * `@object-ui/plugin-dashboard`, the single home for the KEY fallback (a field
+ * key becomes a column header). It is a DIFFERENT convention, not a stale copy
+ * of this one: it additionally splits camelCase.
+ *
+ *   input                humanizeFieldKey     humanizeLabel (here)
+ *   ──────────────────   ──────────────────   ──────────────────
+ *   needs_analysis       Needs Analysis       Needs Analysis
+ *   NeedsAnalysis        Needs Analysis       NeedsAnalysis        <- differ
+ *   unitPrice            Unit Price           UnitPrice            <- differ
+ *   BestCase             Best Case            BestCase             <- differ
+ *   lost-to-competitor   Lost-To-Competitor   Lost To Competitor   <- differ
+ *
+ * They are fed different inputs, which is why their outputs may differ. A field
+ * KEY is authored in the codebase and is expected to carry a machine spelling,
+ * so splitting camelCase recovers words its author meant. A stored VALUE is
+ * arbitrary tenant data — a picklist member, an object name, a code from
+ * another system — where a mid-token capital is not reliably a word boundary,
+ * and splitting it rewrites what the tenant wrote (`McDonald` -> `Mc Donald`).
+ * Note also that the two conventions do not nest: on the last row above each
+ * leaves alone the separator the other rewrites, so "converge" would have to
+ * pick a winner per input class rather than adopt one side wholesale.
+ *
+ * Kept distinct DELIBERATELY, and this paragraph is the write-down whose
+ * absence made the split read as drift. Converging them is a decision, not a
+ * refactor: this function is read by grid, gantt, detail and charts, so any
+ * change to what it RETURNS moves rendered output in four packages at once.
+ * That change is explicitly out of scope for the convergence that created this
+ * module; it needs its own card.
+ *
+ * Examples:
+ *   "in_progress"   -> "In Progress"
+ *   "high-priority" -> "High Priority"
+ *   "active"        -> "Active"
+ */
+export declare function humanizeLabel(value: string): string;

package/dist/utils/humanize-label.js

@@ -0,0 +1,62 @@
+/**
+ * ObjectUI — value-fallback label prettifier
+ * 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.
+ */
+/**
+ * humanize-label — the ONE home for the VALUE fallback: a stored value becomes
+ * a display string when nothing else resolves it (objectui#5444).
+ *
+ * Two byte-identical copies preceded this module: `@object-ui/fields` (read by
+ * `plugin-grid`, `plugin-gantt`, `plugin-detail`, and by the field renderers in
+ * that package itself) and a deliberate local copy in `plugin-charts`'
+ * `ObjectChart.tsx`, whose comment said it existed "to avoid a dependency on
+ * `@object-ui/fields`". `@object-ui/core` is the shared ancestor both packages
+ * already depend on, so the convention gets a single home without a new
+ * dependency edge and without React reaching core — objectui#4389's ruling for
+ * this family: core-canonical logic, plugins consume; never core importing
+ * react. Both former sites now re-export THIS function, so there is one
+ * implementation and two doorways.
+ *
+ * ## Why this is NOT `humanizeFieldKey`, and why the two are kept apart
+ *
+ * The renderer carries a second prettifier — `humanizeFieldKey` in
+ * `@object-ui/plugin-dashboard`, the single home for the KEY fallback (a field
+ * key becomes a column header). It is a DIFFERENT convention, not a stale copy
+ * of this one: it additionally splits camelCase.
+ *
+ *   input                humanizeFieldKey     humanizeLabel (here)
+ *   ──────────────────   ──────────────────   ──────────────────
+ *   needs_analysis       Needs Analysis       Needs Analysis
+ *   NeedsAnalysis        Needs Analysis       NeedsAnalysis        <- differ
+ *   unitPrice            Unit Price           UnitPrice            <- differ
+ *   BestCase             Best Case            BestCase             <- differ
+ *   lost-to-competitor   Lost-To-Competitor   Lost To Competitor   <- differ
+ *
+ * They are fed different inputs, which is why their outputs may differ. A field
+ * KEY is authored in the codebase and is expected to carry a machine spelling,
+ * so splitting camelCase recovers words its author meant. A stored VALUE is
+ * arbitrary tenant data — a picklist member, an object name, a code from
+ * another system — where a mid-token capital is not reliably a word boundary,
+ * and splitting it rewrites what the tenant wrote (`McDonald` -> `Mc Donald`).
+ * Note also that the two conventions do not nest: on the last row above each
+ * leaves alone the separator the other rewrites, so "converge" would have to
+ * pick a winner per input class rather than adopt one side wholesale.
+ *
+ * Kept distinct DELIBERATELY, and this paragraph is the write-down whose
+ * absence made the split read as drift. Converging them is a decision, not a
+ * refactor: this function is read by grid, gantt, detail and charts, so any
+ * change to what it RETURNS moves rendered output in four packages at once.
+ * That change is explicitly out of scope for the convergence that created this
+ * module; it needs its own card.
+ *
+ * Examples:
+ *   "in_progress"   -> "In Progress"
+ *   "high-priority" -> "High Priority"
+ *   "active"        -> "Active"
+ */
+export function humanizeLabel(value) {
+    return value.replace(/[_-]/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+}