@object-ui/core 17.6.0 → 18.0.0

package/dist/utils/column-sortability.js

@@ -0,0 +1,217 @@
+/**
+ * ObjectUI — served per-column sortability projection (consumer side)
+ * 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 consumer half of objectstack#10235 (maintainer ruling A, 2026-08-23):
+ * the platform serves an explicit per-column sortability signal, and a grid
+ * reads THAT to decide whether a header offers a sort click — it never
+ * re-derives "virtual ⇒ unsortable" from the field's `type`.
+ *
+ * ## What the platform serves
+ *
+ * `GET /api/v1/meta/object/:name` answers `GetMetaItemResponseSchema`, whose
+ * ENVELOPE (never the document under `item` — `FieldSchema` is a
+ * `strictObject`, so the key must stay un-authorable) carries an optional
+ * `sortability` key when the served type is `object`, on every serving branch
+ * including the cached one:
+ *
+ * ```jsonc
+ * { "type": "object", "name": "crm_opportunity", "item": { … },
+ *   "sortability": { "fields": {
+ *     "amount":           { "sortable": true },
+ *     "expected_revenue": { "sortable": false, "reason": "virtual-type" },
+ *     "remote_anchor":    { "sortable": true,  "caveat": "unprovisioned-anchor" }
+ *   } } }
+ * ```
+ *
+ * Shape verified against the MERGED upstream change, not against a description
+ * of it: `@objectstack/spec`'s `ObjectSortabilitySchema` /
+ * `FieldSortabilitySchema` and `GetMetaItemResponseSchema.sortability`.
+ *
+ * ## The contract, and the asymmetry that makes it easy to get backwards
+ *
+ * Offer a sort affordance on a column **iff the projection has an entry for
+ * the column's field name AND that entry says `sortable: true`**.
+ *
+ * ABSENCE OF AN ENTRY MEANS "no platform sort behind this name" — never
+ * "assume sortable". The projection's domain is exactly the served field map
+ * plus the always-provisioned `id`, so an unknown name, a dotted path
+ * (`account.name`) and an unprovisioned audit column all arrive as absence,
+ * and all three are refused by the runtime doors. A `!== false` test — the
+ * spelling every other optional flag in this repo uses — answers `true` for
+ * absence and so gets exactly that family backwards. {@link isPlatformSortableField}
+ * is the only spelling of this test; do not inline a comparison at a call site.
+ *
+ * ## Present-vs-absent PROJECTION is a different question
+ *
+ * `readObjectSortability` returns `undefined` when the served metadata carried
+ * no `sortability` key at all — a backend older than the upstream change, an
+ * inline/mock data source, a fixture. That is NOT "every column is unsortable":
+ * it is "no signal was served", and the caller decides what it did before the
+ * signal existed. The two are deliberately different types (`undefined` vs an
+ * empty `fields` map) so a caller cannot conflate them by accident.
+ *
+ * ## `caveat: 'unprovisioned-anchor'` is NOT a refusal
+ *
+ * Platform-injected anchors on ADR-0015 `external` objects come back
+ * `sortable: true, caveat: 'unprovisioned-anchor'`: the runtime ACCEPTS the
+ * sort, but silently drops it (`asc` === `desc` under a `200`) when the remote
+ * table carries no such column — a degradation the platform cannot prove
+ * either way at serve time. This module treats the caveat as advisory and the
+ * `sortable` verdict as the enforcement fact, so a caveated column keeps its
+ * click. Refusing what the platform does not refuse would recreate
+ * declared-≠-enforced drift in mirror image; whether to badge or withhold on
+ * the caveat is an open affordance question, not something to settle here.
+ */
+/**
+ * The served shape is the SPEC's, re-exported rather than restated.
+ *
+ * `FIELD_UNSORTABLE_VIRTUAL_TYPE` / `FIELD_SORTABLE_UNPROVISIONED_ANCHOR` are
+ * the two string literals the projection can carry, and `FieldSortability` /
+ * `ObjectSortability` are the wire types themselves (`z.input` of the
+ * schemas the REST layer answers with). Re-exporting is the point of a
+ * contract-first consumer: a local declaration under a spec export's name is
+ * read by the next agent as the spec's own definition, and then drifts from
+ * it — which is what `check:spec-symbols` guards, and what it caught here.
+ */
+export { FIELD_UNSORTABLE_VIRTUAL_TYPE, FIELD_SORTABLE_UNPROVISIONED_ANCHOR, } from '@objectstack/spec/api';
+/**
+ * Where the projection rides on the client-side object schema.
+ *
+ * A GLOBAL-REGISTRY SYMBOL, deliberately — the same carrier shape
+ * `INFLIGHT_GET_REGISTRY_KEY` uses in `@object-ui/types`. Three properties
+ * this signal needs and a string key would not give it:
+ *
+ *  - `JSON.stringify` drops symbol-keyed properties, so a schema object that
+ *    is ever round-tripped back at a metadata WRITE endpoint cannot carry the
+ *    projection into a document the server parses `strict` and rejects by
+ *    name. The upstream change kept the key off `item` for exactly that
+ *    reason; stamping a string key here would undo it one repo away.
+ *  - `Object.keys` / spread / `for…in` do not see it, so every existing reader
+ *    that enumerates the schema (column generators, diffing, form builders)
+ *    is unchanged by its presence.
+ *  - `Symbol.for` is the cross-realm registry, so two copies of this module
+ *    (a workspace build and a published one in the same graph) agree on the
+ *    key rather than silently reading past each other.
+ */
+export const OBJECT_SORTABILITY_KEY = Symbol.for('objectui.objectSortability');
+/** Narrow one served entry, tolerating an unparsed / hand-built record. */
+function asFieldSortability(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const sortable = value.sortable;
+    if (typeof sortable !== 'boolean')
+        return undefined;
+    const reason = value.reason;
+    const caveat = value.caveat;
+    // `reason` / `caveat` are typed as closed literal unions by the spec, and
+    // this is unparsed input off the wire. Preserve whatever string arrived
+    // rather than dropping an annotation a NEWER platform added — the verdict
+    // this module acts on is `sortable`, and an unrecognised advisory string is
+    // strictly better carried than silently erased. The assertion is the
+    // boundary cast that admission implies, and it is confined to this function.
+    return {
+        sortable,
+        ...(typeof reason === 'string' ? { reason } : {}),
+        ...(typeof caveat === 'string' ? { caveat } : {}),
+    };
+}
+/**
+ * Normalize a served `sortability` envelope value into the projection, or
+ * `undefined` when the envelope carried nothing usable.
+ *
+ * Tolerant on purpose (the same contract the upstream resolver carries): the
+ * adapter hands this whatever came back over the wire, unparsed.
+ */
+export function normalizeObjectSortability(served) {
+    if (!served || typeof served !== 'object' || Array.isArray(served))
+        return undefined;
+    const rawFields = served.fields;
+    if (!rawFields || typeof rawFields !== 'object' || Array.isArray(rawFields))
+        return undefined;
+    const fields = {};
+    for (const [name, entry] of Object.entries(rawFields)) {
+        const verdict = asFieldSortability(entry);
+        if (verdict)
+            fields[name] = verdict;
+    }
+    return { fields };
+}
+/**
+ * Stamp the served projection onto the client-side object schema, under
+ * {@link OBJECT_SORTABILITY_KEY}.
+ *
+ * Non-enumerable and non-writable-by-accident: the property is defined rather
+ * than assigned so it never shows up in a spread of the schema and cannot be
+ * clobbered by one. Returns the same object it was handed (the adapter caches
+ * that instance), and is a no-op when there is nothing usable to attach — so
+ * an older backend leaves the schema exactly as it found it rather than
+ * stamping an empty projection that would read as "nothing is sortable".
+ */
+export function attachObjectSortability(schema, served) {
+    const projection = normalizeObjectSortability(served);
+    if (!projection || !schema || typeof schema !== 'object')
+        return schema;
+    Object.defineProperty(schema, OBJECT_SORTABILITY_KEY, {
+        value: projection,
+        enumerable: false,
+        configurable: true,
+        writable: true,
+    });
+    return schema;
+}
+/**
+ * Read the served projection off a client-side object schema.
+ *
+ * `undefined` means NO SIGNAL WAS SERVED — not "nothing is sortable". See the
+ * module docblock: callers must branch on this before applying the contract.
+ */
+export function readObjectSortability(schema) {
+    if (!schema || typeof schema !== 'object')
+        return undefined;
+    const carried = schema[OBJECT_SORTABILITY_KEY];
+    if (!carried || typeof carried !== 'object')
+        return undefined;
+    const fields = carried.fields;
+    if (!fields || typeof fields !== 'object' || Array.isArray(fields))
+        return undefined;
+    return carried;
+}
+/**
+ * THE contract test: does the platform offer a sort over this field name?
+ *
+ * `true` iff the projection has an entry for `fieldName` and that entry says
+ * `sortable: true`. Every other case — no entry, `sortable: false`, a
+ * malformed entry — answers `false`, because absence means "no platform sort
+ * behind this name".
+ *
+ * `sortability` is REQUIRED and non-optional on purpose: a caller holding
+ * `undefined` (no signal served) has a different question to answer and must
+ * not reach this function with it. See {@link readObjectSortability}.
+ */
+export function isPlatformSortableField(sortability, fieldName) {
+    if (typeof fieldName !== 'string' || fieldName.length === 0)
+        return false;
+    const entry = sortability.fields?.[fieldName];
+    return asFieldSortability(entry)?.sortable === true;
+}
+/**
+ * Drop from a sort list every entry the platform will not order by.
+ *
+ * The RESTORE leg of the same contract: withholding the header click stops a
+ * fresh unsortable sort from being created, but a sort persisted BEFORE the
+ * signal existed is already in stored view state, and replaying it would keep
+ * a refused `$orderby` alive and re-persist it on the next unrelated edit.
+ * Filtering the list at the seam the grid both renders from and emits through
+ * means an already-stored entry is inert and is dropped the first time
+ * anything writes the sort back.
+ */
+export function filterPlatformSortableSort(sort, sortability) {
+    if (!Array.isArray(sort))
+        return [];
+    return sort.filter((item) => isPlatformSortableField(sortability, item?.field));
+}

package/dist/utils/dashboard-filters.d.ts

@@ -27,6 +27,31 @@ export interface DashboardFilterDef {
     name: string;
     /** Default target field when a widget declares no explicit binding. */
     field: string;
+    /**
+     * The object `field` lives on, carried through from
+     * @objectstack/spec's `GlobalFilterSchema.object` (`061f5e829`).
+     *
+     * The spec's own describe text for that key states the contract: "Object
+     * whose `fields.<object>.<field>` translation-bundle entry resolves this
+     * filter's field label and option labels". It was shipped on the spec side
+     * and never reached a consumer here, because this builder names the keys it
+     * copies and this one was not among them — so the value could not reach a
+     * renderer even in principle.
+     *
+     * ⚠️ NOT `optionsFrom.object`, which the spec separates deliberately: that
+     * one names the object dynamic OPTIONS are fetched from and may differ
+     * (filtering `opportunity` by `owner` with options sourced from `user`),
+     * while this one names the object whose translation bundle is keyed by
+     * `field`. Reading the former for label resolution resolves against the
+     * wrong object for exactly that filter.
+     *
+     * Like {@link DashboardFilterDef.label}, this module carries it through
+     * UNRESOLVED — `@object-ui/core` is locale-free by design and the bundle
+     * read belongs to the render side. Omitted entirely when the author declared
+     * none, so a dashboard that never names an object resolves to a def with the
+     * same key set it always had.
+     */
+    object?: string;
     /**
      * Display label, in @objectstack/spec's `I18nLabel` vocabulary — a plain
      * string, or an inline per-locale map (`{ en: 'Owner', 'zh-CN': '负责人' }`).
@@ -49,10 +74,11 @@ export interface DashboardFilterDef {
      * `resolveDashboardFilterDefs` — consumers always see the object form.
      *
      * The canonical authoring form is @objectstack/spec's `{ value, label }`
-     * pair, and it is the ONLY one the platform accepts at publish. A bare-string
-     * shorthand in a STORED document is still lifted here, with a deprecation
-     * warning, on the objectstack#7917 retirement schedule — see
-     * `normalizeFilterOptions`. Do not author a new one.
+     * pair, and it is the ONLY one the platform accepts at publish. The
+     * bare-string shorthand a STORED document may still carry is NOT lifted
+     * (objectui#4356, retired on the objectstack#7917 option-② schedule): such
+     * a member yields no option, and `normalizeFilterOptions` says so once. Do
+     * not author one; rewrite `"X"` as `{ "value": "X", "label": "X" }`.
      *
      * The PAIR SHAPE is normalized; the label's own vocabulary is not. `label`
      * is `I18nLabel` in `GlobalFilterSchema.options[]` too, and it reaches the
@@ -99,12 +125,18 @@ export interface DateRangeValue {
  * protect.
  *
  * What stays local is the BOUNDS table above, which is the other half of
- * #4614's design ("the two vocabularies live one import apart and neither
+ * objectstack-ai/objectstack#4614's design ("the two vocabularies live one import apart and neither
  * restates the other's grammar"): the spec owns which presets exist, this
  * module owns what each one resolves to in date-macro tokens.
  */
 export { DATE_RANGE_PRESETS };
-/** Reset the shorthand-options warn-once memo. Exported for tests. */
+/**
+ * Reset the dropped-shorthand warn-once memo. Exported for tests.
+ *
+ * Kept through the objectui#4356 retirement: the memo it clears outlived the
+ * deprecation warning, because the warning that replaced it (a member was
+ * DROPPED, not lifted) dedupes on the same key for the same render-path reason.
+ */
 export declare function resetDashboardFilterWarnings(): void;
 /**
  * Normalize a dashboard schema's filter declarations into a flat list of

package/dist/utils/dashboard-filters.js

@@ -6,12 +6,39 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { liftLegacyGlobalFilterDefault } from '@object-ui/types';
-import { DATE_RANGE_PRESETS } from '@objectstack/spec/ui';
+import { DATE_RANGE_PRESETS, DashboardSchema as SpecDashboardSchema } from '@objectstack/spec/ui';
 import { resolveDateMacros } from './date-macros.js';
 /** Reserved filter name for the dashboard's built-in date range. */
 export const DATE_RANGE_FILTER_NAME = 'dateRange';
 /** Default target field for the built-in date range filter. */
 const DATE_RANGE_DEFAULT_FIELD = 'created_at';
+/**
+ * The preset an authored `dateRange` resolves to when it omits `defaultRange`
+ * (objectui#10339) — READ FROM THE SPEC, never restated here.
+ *
+ * `@objectstack/spec` declares `DashboardSchema.dateRange.defaultRange` with a
+ * `.default(...)`, so the platform's parse of `dateRange: { field: 'created_at' }`
+ * carries that preset, and a renderer that treated the omission as "no filter"
+ * showed an UNFILTERED dashboard for a document the protocol says is filtered
+ * (#7759 ruling 5617465269, rule 1: the read site implements every arm the spec
+ * declares). The value is derived by parsing an EMPTY `dateRange` element
+ * through the spec's own schema: the only keys that come back are the ones the
+ * spec supplies by default, so this reads the spec's answer rather than a
+ * hand-copied string that could drift from it. `allowCustomRange` is the
+ * sibling default and needs no such read — it is consumed as `!== false`,
+ * which already is its spec default.
+ *
+ * Computed on first use and cached: `DashboardSchema` is a lazy schema, and
+ * forcing its construction at module load would cost every importer of
+ * `@object-ui/core` for a value only a dashboard with a bare `dateRange` needs.
+ */
+let specDateRangeDefault;
+function specDefaultDateRangePreset() {
+    if (specDateRangeDefault === undefined) {
+        specDateRangeDefault = SpecDashboardSchema.shape.dateRange.parse({})?.defaultRange;
+    }
+    return specDateRangeDefault;
+}
 /**
  * Date-range presets → date-macro token bounds. Tokens stay symbolic in the
  * generated condition; every widget renderer resolves them at query time via
@@ -72,7 +99,7 @@ function presetBounds(preset) {
  * protect.
  *
  * What stays local is the BOUNDS table above, which is the other half of
- * #4614's design ("the two vocabularies live one import apart and neither
+ * objectstack-ai/objectstack#4614's design ("the two vocabularies live one import apart and neither
  * restates the other's grammar"): the spec owns which presets exist, this
  * module owns what each one resolves to in date-macro tokens.
  */
@@ -111,13 +138,13 @@ function warnDateFilter(message) {
         console.warn(`[dashboard-filters] ${message}`);
 }
 /**
- * Dev-mode gate, matching `actions/actionKeys.ts` — a deprecation warning that
- * floods a production console is a warning that gets muted.
+ * Dev-mode gate, matching `actions/actionKeys.ts` — a warning that floods a
+ * production console is a warning that gets muted.
  */
 const isDev = () => globalThis.process?.env?.NODE_ENV !==
     'production';
 /**
- * Warn-once memo for the bare-string `options` shorthand (objectui#4356).
+ * Warn-once memo for the DROPPED bare-string `options` members (objectui#4356).
  *
  * Keyed by filter NAME **and** the offending values, deliberately — the same
  * reasoning `warnOnUnknownActionKeys` records for its own memo. Keying on the
@@ -132,7 +159,13 @@ const isDev = () => globalThis.process?.env?.NODE_ENV !==
  * flood the dedupe exists to prevent.
  */
 const warnedShorthandOptions = new Set();
-/** Reset the shorthand-options warn-once memo. Exported for tests. */
+/**
+ * Reset the dropped-shorthand warn-once memo. Exported for tests.
+ *
+ * Kept through the objectui#4356 retirement: the memo it clears outlived the
+ * deprecation warning, because the warning that replaced it (a member was
+ * DROPPED, not lifted) dedupes on the same key for the same render-path reason.
+ */
 export function resetDashboardFilterWarnings() {
     warnedShorthandOptions.clear();
 }
@@ -252,45 +285,40 @@ function normalizeDateDefault(type, defaultValue) {
 }
 /**
  * Normalize a filter's static `options` declaration to `{ value, label }`
- * pairs. The @objectstack/spec `GlobalFilterSchema.options` form is
- * `{ value, label }` objects; the bare-string shorthand (`options: ['EMEA', …]`)
- * is still lifted, but is DEPRECATED and now says so out loud. Rendering an
- * un-normalized option crashes React — this is the single place both shapes
- * converge.
+ * pairs — the @objectstack/spec `GlobalFilterSchema.options` form, and the
+ * only form this function emits. Rendering an un-normalized option crashes
+ * React, so every member that reaches a renderer passes through here.
  *
- * ## The shorthand's deprecation (objectui#4356, objectstack#7917)
+ * ## The bare-string shorthand is RETIRED (objectui#4356, objectstack#7917)
  *
  * Maintainer ruling of 2026-08-12 on objectstack#7917, verbatim 「7917 ②」:
- * option ② — **the spec stays strict; the runtime bare-string lift retires
- * behind a deprecation window sized by a stored-dashboard survey.** So a
- * document spelling `options: ['EMEA']` renders here and is refused the moment
- * it reaches the platform's validation — the "one strict contract beats N
- * dialects" divergence AGENTS.md #0.1 names, with the renderer's tolerance
- * acting as a second de-facto contract.
- *
- * This is the WARN half of that window (Phase 1). The lift itself is unchanged
- * and remains mechanically lossless (`'EMEA'` → `{ value: 'EMEA', label:
- * 'EMEA' }`), because stored dashboards carry the shorthand and dropping it
- * silently would turn a rendering filter into an empty one. Removal (Phase 2)
- * is scheduled on objectstack#7917, earliest one minor release after this ships
- * and not before the live-tenant channel has actually been queried.
- *
- * The warning is not decoration: a silent lift can never be retired, because
- * nothing would ever show that the last shorthand document is gone (ADR-0078 —
- * nothing silently inert). It is the same reasoning `liftLegacyFilterDeclaration`
- * records above, for the sibling alias.
- *
- * Phase 0 shipped in the same PR: objectui's own docs, its `plugin-dashboard`
- * README and its schema-catalog corpus stopped TEACHING the shorthand, so the
- * stored population is no longer growing while this warning asks authors to
- * migrate. Warning authors while the docs still taught the form would have been
- * a contradiction users report as a bug.
+ * option ② — **the spec stays strict; the runtime bare-string lift retires.**
+ * The window closed on the maintainer's 2026-09-02 ruling, verbatim
+ * 「objectstack#7917 不考虑现有数据」: Phase 2 proceeds on release cadence
+ * alone, with no live-tenant survey and no migration entry.
+ *
+ * So `options: ['EMEA']` — which the Phase 1 build (PR #4601) lifted to
+ * `{ value: 'EMEA', label: 'EMEA' }` under a deprecation warning — now yields
+ * NO option. A member that is not an object is skipped, exactly as a nullish
+ * member or an object with no `value` already was: a shorthand-only filter
+ * resolves with no `options`, and a mixed array keeps only its object members.
+ * The runtime reads the document the way the spec does, which is the end
+ * state option ② named — one strict contract, no renderer dialect beside it
+ * (AGENTS.md #0.1). ⛔ No lift, alias, fallback or migration returns here.
+ *
+ * The skip is not silent. `warnDroppedShorthandOptions` names the filter, the
+ * dropped members and the rewrite, once per filter per session — ADR-0078 §4:
+ * where the runtime skips an instance it emits a dev-mode diagnostic rather
+ * than swallowing it, and a STORED dashboard is the one document no author-time
+ * gate ever re-reads, so an empty select with nothing in the console would read
+ * as "no data". What that warning must NOT do is promise a lift: the Phase 1
+ * text said "still lifted here", and that sentence retired with the arm.
  *
  * ## What is normalized, and what is deliberately NOT (objectui#4032 / #4163)
  *
- * The PAIR SHAPE is normalized (`value` stringified, a bare string lifted to a
- * pair). The LABEL's authoring vocabulary is carried through untouched, because
- * `label` is `I18nLabel` — a string OR an inline per-locale map.
+ * The PAIR SHAPE is normalized (`value` stringified). The LABEL's authoring
+ * vocabulary is carried through untouched, because `label` is `I18nLabel` — a
+ * string OR an inline per-locale map.
  *
  * This line used to read:
  *
@@ -312,8 +340,8 @@ function normalizeFilterOptions(options, filterName) {
     if (!Array.isArray(options) || options.length === 0)
         return undefined;
     const normalized = [];
-    /** Every bare-string member, in authored order — one warning names them all. */
-    const shorthand = [];
+    /** Every non-object member, in authored order — one warning names them all. */
+    const dropped = [];
     for (const o of options) {
         if (o === null || o === undefined)
             continue;
@@ -329,39 +357,48 @@ function normalizeFilterOptions(options, filterName) {
             });
         }
         else {
-            shorthand.push(String(o));
-            normalized.push({ value: String(o), label: String(o) });
+            // The retired shorthand arm (objectui#4356): nothing is pushed for this
+            // member. It is recorded for the warning and yields no option.
+            dropped.push(o);
         }
     }
-    if (shorthand.length > 0)
-        warnShorthandOptions(filterName, shorthand);
+    if (dropped.length > 0)
+        warnDroppedShorthandOptions(filterName, dropped);
     return normalized.length > 0 ? normalized : undefined;
 }
 /**
- * Say the deprecated shorthand out loud — once per offending filter per
- * session, naming the filter and printing the canonical replacement.
+ * Say the dropped members out loud — once per offending filter per session,
+ * naming the filter, the members that yielded no option, and the rewrite.
  *
- * Collected per FILTER rather than per option: a filter declaring
+ * Collected per FILTER rather than per member: a filter declaring
  * `['EMEA', 'APAC', 'AMER']` is one authoring mistake in one place, so it earns
  * one warning carrying all three values, not three warnings the author has to
  * reassemble. A MIXED array (`[{ value: 'won', … }, 'lost']`) names only the
- * bare members, which are the ones that need rewriting — partial migrations
- * happen and a warning that re-reports the already-canonical members is noise.
+ * dropped members — the object members rendered, and re-reporting them is noise.
+ *
+ * Dev-mode only and memoised, exactly as the Phase 1 deprecation warning was:
+ * `resolveDashboardFilterDefs` runs on every dashboard render, and a warning
+ * that floods a console is a warning that gets muted. What changed is the
+ * sentence — this one reports a member that was DROPPED and promises no lift.
  */
-function warnShorthandOptions(filterName, shorthand) {
+function warnDroppedShorthandOptions(filterName, dropped) {
     if (!isDev())
         return;
-    const memo = `${filterName}:${shorthand.join(',')}`;
+    // A string is quoted so `"42"` and `42` stay distinguishable; anything else is
+    // spelled as itself — `String()` rather than `JSON.stringify()`, because a
+    // programmatic caller can hand this a value JSON cannot carry.
+    const spelled = dropped.map((v) => (typeof v === 'string' ? JSON.stringify(v) : String(v)));
+    const memo = `${filterName}:${spelled.join(',')}`;
     if (warnedShorthandOptions.has(memo))
         return;
     warnedShorthandOptions.add(memo);
-    const canonical = shorthand.map((v) => `{ value: ${JSON.stringify(v)}, label: ${JSON.stringify(v)} }`).join(', ');
-    warnDateFilter(`filter "${filterName}": \`options\` carries the bare-string shorthand ` +
-        `(${shorthand.map((v) => JSON.stringify(v)).join(', ')}), which @objectstack/spec's ` +
-        `\`GlobalFilterSchema\` REFUSES at publish — a dashboard authored this way renders here ` +
-        `and is rejected the moment it reaches the platform (objectui#4356). Rewrite the stored ` +
-        `dashboard to the canonical pair form: [${canonical}]. Still lifted here for already-` +
-        `persisted dashboards; the lift is removed on the objectstack#7917 schedule.`);
+    const canonical = dropped
+        .map((v) => `{ value: ${JSON.stringify(String(v))}, label: ${JSON.stringify(String(v))} }`)
+        .join(', ');
+    warnDateFilter(`filter "${filterName}": \`options\` members ${spelled.join(', ')} are not \`{ value, label }\` ` +
+        `objects and were DROPPED — the bare-string shorthand is no longer lifted (objectui#4356), so the ` +
+        `filter renders without them. Rewrite the stored dashboard to @objectstack/spec's pair form: ` +
+        `[${canonical}].`);
 }
 /**
  * Normalize a dashboard schema's filter declarations into a flat list of
@@ -372,7 +409,11 @@ function warnShorthandOptions(filterName, shorthand) {
 export function resolveDashboardFilterDefs(schema) {
     const byName = new Map();
     if (schema.dateRange) {
-        const preset = schema.dateRange.defaultRange;
+        // An omitted `defaultRange` takes the spec's declared default (#10339); an
+        // explicit value — `'custom'` included — is used exactly as authored.
+        const preset = schema.dateRange.defaultRange === undefined
+            ? specDefaultDateRangePreset()
+            : schema.dateRange.defaultRange;
         byName.set(DATE_RANGE_FILTER_NAME, {
             name: DATE_RANGE_FILTER_NAME,
             field: schema.dateRange.field || DATE_RANGE_DEFAULT_FIELD,
@@ -398,9 +439,14 @@ export function resolveDashboardFilterDefs(schema) {
         byName.set(name, {
             name,
             field: f.field,
+            // Spread rather than assigned (`061f5e829`): every filter authored
+            // before this key existed keeps the exact key set it resolved to, so
+            // `'object' in def` stays the discriminator the render side branches on
+            // and no consumer sees a new own-property carrying `undefined`.
+            ...(typeof f.object === 'string' && f.object ? { object: f.object } : {}),
             label: f.label,
             type,
-            // `name` is the identifying context the deprecation warning needs, and
+            // `name` is the identifying context the dropped-member warning needs, and
             // the local above already resolved it — nothing new is threaded through a
             // public signature for it. `normalizeFilterOptions` is module-private, so
             // widening ITS parameter list is not a contract move.