@object-ui/core 17.3.0 → 17.6.0

package/dist/utils/column-identity.d.ts

@@ -108,3 +108,46 @@ export declare function normalizeColumnIdentity<T>(entry: T): T;
  * every consumer already special-cases it.
  */
 export declare function normalizeColumnIdentities<T>(columns: T): T;
+/**
+ * The spec's canonical key for "what this column is CALLED on screen".
+ *
+ * `ListColumnSchema` (`@objectstack/spec/view`) spells a column's display text
+ * `label`, next to its `field`. It is metadata vocabulary, exactly like
+ * {@link CANONICAL_COLUMN_IDENTITY_KEY} — not an objectui legacy spelling, and
+ * not something to amputate.
+ */
+export declare const CANONICAL_COLUMN_LABEL_KEY = "label";
+/**
+ * NOT metadata — the display half of the same boundary
+ * {@link TABLE_ADAPTER_COLUMN_KEY} draws for identity.
+ *
+ * `header` is `TableColumn.header` (`packages/types/src/data-display.ts`), the
+ * data-table ADAPTER's own key for a column's rendered title. The adapter
+ * declares `header` and does not declare `label`; the spec declares `label` and
+ * does not declare `header`. Those are two vocabularies, and the translation
+ * between them belongs at the producer — one translation, one place
+ * (objectui#5068) — never as a tolerated `col.header || col.label` alias inside
+ * the adapter (objectui#5351).
+ */
+export declare const TABLE_ADAPTER_HEADER_KEY = "header";
+/**
+ * Read a column entry's display text on its way INTO the data-table adapter —
+ * the header counterpart of {@link columnIdentity} (objectui#5351).
+ *
+ * Adapter-first, which is the opposite order from {@link columnIdentity} and is
+ * deliberate. `columnIdentity` folds several METADATA spellings of one metadata
+ * concept, so the canonical metadata key wins. This reader crosses a boundary
+ * between two vocabularies instead: an author who wrote the adapter's own
+ * `header` addressed the table directly, and a producer must not overwrite that
+ * — the same rule `RelatedList` and `ObjectDataTable` already state for an
+ * author-supplied `accessorKey` (objectui#5022).
+ *
+ * Returns `undefined` — not `''` — when neither key carries text, so a caller
+ * can tell "no header authored" from "the header is deliberately blank" and
+ * stamp nothing rather than stamping an empty string.
+ *
+ * A bare-string column entry has no display text of its own; producers derive
+ * one from the field key (`humanizeFieldKey`) or the object schema's label, and
+ * that derivation is theirs, not this reader's.
+ */
+export declare function columnHeader(entry: unknown): string | undefined;

package/dist/utils/column-identity.js

@@ -125,7 +125,6 @@ function warnOnConflictingIdentity(entry, identity, losing) {
         if (warnedConflicts.has(memo))
             continue;
         warnedConflicts.add(memo);
-        // eslint-disable-next-line no-console
         console.warn(`[ObjectUI] Column carries two identities: \`${CANONICAL_COLUMN_IDENTITY_KEY}: ` +
             `'${identity}'\` and \`${key}: '${String(entry[key])}'\`. ` +
             `\`${CANONICAL_COLUMN_IDENTITY_KEY}\` wins — it is the only key ` +
@@ -208,3 +207,50 @@ export function normalizeColumnIdentities(columns) {
     });
     return (changed ? next : columns);
 }
+/**
+ * The spec's canonical key for "what this column is CALLED on screen".
+ *
+ * `ListColumnSchema` (`@objectstack/spec/view`) spells a column's display text
+ * `label`, next to its `field`. It is metadata vocabulary, exactly like
+ * {@link CANONICAL_COLUMN_IDENTITY_KEY} — not an objectui legacy spelling, and
+ * not something to amputate.
+ */
+export const CANONICAL_COLUMN_LABEL_KEY = 'label';
+/**
+ * NOT metadata — the display half of the same boundary
+ * {@link TABLE_ADAPTER_COLUMN_KEY} draws for identity.
+ *
+ * `header` is `TableColumn.header` (`packages/types/src/data-display.ts`), the
+ * data-table ADAPTER's own key for a column's rendered title. The adapter
+ * declares `header` and does not declare `label`; the spec declares `label` and
+ * does not declare `header`. Those are two vocabularies, and the translation
+ * between them belongs at the producer — one translation, one place
+ * (objectui#5068) — never as a tolerated `col.header || col.label` alias inside
+ * the adapter (objectui#5351).
+ */
+export const TABLE_ADAPTER_HEADER_KEY = 'header';
+/**
+ * Read a column entry's display text on its way INTO the data-table adapter —
+ * the header counterpart of {@link columnIdentity} (objectui#5351).
+ *
+ * Adapter-first, which is the opposite order from {@link columnIdentity} and is
+ * deliberate. `columnIdentity` folds several METADATA spellings of one metadata
+ * concept, so the canonical metadata key wins. This reader crosses a boundary
+ * between two vocabularies instead: an author who wrote the adapter's own
+ * `header` addressed the table directly, and a producer must not overwrite that
+ * — the same rule `RelatedList` and `ObjectDataTable` already state for an
+ * author-supplied `accessorKey` (objectui#5022).
+ *
+ * Returns `undefined` — not `''` — when neither key carries text, so a caller
+ * can tell "no header authored" from "the header is deliberately blank" and
+ * stamp nothing rather than stamping an empty string.
+ *
+ * A bare-string column entry has no display text of its own; producers derive
+ * one from the field key (`humanizeFieldKey`) or the object schema's label, and
+ * that derivation is theirs, not this reader's.
+ */
+export function columnHeader(entry) {
+    if (!isRecord(entry))
+        return undefined;
+    return (asIdentity(entry[TABLE_ADAPTER_HEADER_KEY]) ?? asIdentity(entry[CANONICAL_COLUMN_LABEL_KEY]));
+}

package/dist/utils/compare-to.d.ts

@@ -8,23 +8,50 @@
 /**
  * Period-over-period comparison config for dashboard widgets.
  *
- * - `'previousPeriod'` — substitute `current_*` / `today` date macro tokens
- *   with their `last_*` / `yesterday` counterparts (e.g. `current_quarter_start`
- *   → `last_quarter_start`). Best when the filter uses date macros.
- * - `'previousYear'` — re-resolve date macros against a `now` shifted back
- *   one calendar year (same week / month / quarter, one year earlier).
- * - `{ offset: '7d' | '4w' | '1M' | '1y' }` — re-resolve macros against a
- *   `now` shifted by the given duration. Units: `d` (day), `w` (week),
- *   `M` (month), `y` (year).
+ * Converged (objectstack#5011) onto the contract the analytics executor
+ * already implements — `DatasetSelection.compareTo`, i.e. `DatasetCompareTo`
+ * in `@objectstack/spec` (`contracts/analytics-service.ts`). This type is that
+ * contract's thin projection, so the same widget key means the same thing on
+ * the ADR-0021 dataset path and on this legacy inline object-provider path.
+ *
+ * - `kind: 'previousPeriod'` — the equal-length window immediately before the
+ *   current one. On the inline path that is done by substituting `current_*` /
+ *   `today` date macro tokens with their `last_*` / `yesterday` counterparts
+ *   (`current_quarter_start` → `last_quarter_start`), so it works best when the
+ *   filter is written with date macros.
+ * - `kind: 'previousYear'` — re-resolve the filter's date macros against a
+ *   `now` shifted back one calendar year (same week / month / quarter, one year
+ *   earlier).
+ * - `dimension` — OPTIONAL, and deliberately never read on this path. It names
+ *   the dataset time dimension whose `dateRange` the EXECUTOR shifts. That
+ *   resolution lives at the producer of the comparison so that every caller
+ *   gets the same answer or the same loud error; a renderer that guessed a
+ *   dimension would trade "loud error" for "quietly wrong window" — precisely
+ *   the failure class this convergence exists to end.
+ *
+ * **Design note — a plain strict object, NOT a union** (objectstack#5011,
+ * framework#5014). The retired shape was a three-branch union
+ * (`'previousPeriod' | 'previousYear' | { offset }`); zod collapses a failed
+ * union into a bare `Invalid input`, so the prescriptions written inside each
+ * arm never reached the author. One strict object keeps the rejection specific.
+ * It also leaves this renderer with exactly one contract to read — no second
+ * de-facto dialect to be tolerant about (AGENTS.md #0.1).
+ *
+ * The `{ offset: '7d' | '1M' | '1y' }` arm went with the union: `{ offset: '1y' }`
+ * IS `kind: 'previousYear'` (rewritten deterministically upstream), while
+ * `'7d'` / `'1M'` have no faithful target — an author restates that window on
+ * the widget's own `filter` and asks for `kind: 'previousPeriod'` (registered
+ * semantic migration `dashboard-widget-compareto-offset`).
  */
-export type CompareToConfig = 'previousPeriod' | 'previousYear' | {
-    offset: string;
-};
+export interface CompareToConfig {
+    kind: 'previousPeriod' | 'previousYear';
+    dimension?: string;
+}
 /**
- * Resolve a filter for a period-over-period comparison query.
+ * Resolve a filter for a period-over-period comparison query. Dispatches on
+ * `compareTo.kind` — the only discriminator the converged shape has:
  *
  * - `previousYear` — re-resolve date macros against a `now` shifted back by one year.
- * - `{ offset }` — re-resolve date macros against a `now` shifted by the given duration.
  * - `previousPeriod` — substitute `current_*` / `today` tokens with `last_*` / `yesterday`
  *   before resolving.
  */

package/dist/utils/compare-to.js

@@ -44,44 +44,19 @@ function substituteTokens(value, map) {
     }
     return value;
 }
-function shiftNow(now, offset) {
-    const m = offset.match(/^(\d+)([dwMy])$/);
-    if (!m)
-        return null;
-    const n = parseInt(m[1], 10);
-    const unit = m[2];
-    const x = new Date(now);
-    if (unit === 'd')
-        x.setDate(x.getDate() - n);
-    else if (unit === 'w')
-        x.setDate(x.getDate() - n * 7);
-    else if (unit === 'M')
-        x.setMonth(x.getMonth() - n);
-    else if (unit === 'y')
-        x.setFullYear(x.getFullYear() - n);
-    else
-        return null;
-    return x;
-}
 /**
- * Resolve a filter for a period-over-period comparison query.
+ * Resolve a filter for a period-over-period comparison query. Dispatches on
+ * `compareTo.kind` — the only discriminator the converged shape has:
  *
  * - `previousYear` — re-resolve date macros against a `now` shifted back by one year.
- * - `{ offset }` — re-resolve date macros against a `now` shifted by the given duration.
  * - `previousPeriod` — substitute `current_*` / `today` tokens with `last_*` / `yesterday`
  *   before resolving.
  */
 export function shiftFilterByCompareTo(filter, compareTo, now = new Date()) {
-    if (compareTo === 'previousYear') {
+    if (compareTo.kind === 'previousYear') {
         const shifted = new Date(now.getFullYear() - 1, now.getMonth(), now.getDate(), now.getHours(), now.getMinutes(), now.getSeconds());
         return resolveDateMacros(filter, shifted);
     }
-    if (typeof compareTo === 'object' && compareTo && 'offset' in compareTo) {
-        const shifted = shiftNow(now, compareTo.offset);
-        if (!shifted)
-            return resolveDateMacros(filter, now);
-        return resolveDateMacros(filter, shifted);
-    }
     // previousPeriod
     const substituted = substituteTokens(filter, CURRENT_TO_LAST_TOKENS);
     return resolveDateMacros(substituted, now);
@@ -91,11 +66,8 @@ export function shiftFilterByCompareTo(filter, compareTo, now = new Date()) {
  * comparison window. Used by metric widgets to label the trend delta.
  */
 export function compareToTrendLabelKey(compareTo, filter) {
-    if (compareTo === 'previousYear')
+    if (compareTo.kind === 'previousYear')
         return 'vsLastYear';
-    if (typeof compareTo === 'object' && compareTo && 'offset' in compareTo) {
-        return 'vsPreviousPeriod';
-    }
     // previousPeriod — sniff the dominant token in the filter
     const json = filter ? JSON.stringify(filter) : '';
     if (/current_year_|year_start|year_end/.test(json))

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

@@ -18,7 +18,8 @@
  * Everything in this module is pure and synchronous so the binding rules
  * are unit-testable in isolation from React and the data layer.
  */
-import type { DashboardComponentSchema, DashboardWidgetSchema, PageVariable } from '@object-ui/types';
+import type { DashboardComponentSchema, DashboardWidgetSchema, I18nLabel, PageVariable } from '@object-ui/types';
+import { DATE_RANGE_PRESETS } from '@objectstack/spec/ui';
 /** Reserved filter name for the dashboard's built-in date range. */
 export declare const DATE_RANGE_FILTER_NAME = "dateRange";
 export interface DashboardFilterDef {
@@ -26,17 +27,41 @@ export interface DashboardFilterDef {
     name: string;
     /** Default target field when a widget declares no explicit binding. */
     field: string;
-    label?: string;
+    /**
+     * Display label, in @objectstack/spec's `I18nLabel` vocabulary — a plain
+     * string, or an inline per-locale map (`{ en: 'Owner', 'zh-CN': '负责人' }`).
+     *
+     * Widened from `string` under the objectstack#5428 ruling of 2026-08-06
+     * (option A): `GlobalFilterSchema.label` has been `I18nLabel` on the spec
+     * side since 17.0.0-rc.6, so declaring it `string` here made this module
+     * NARROWER than the contract it implements — which is exactly why the filter
+     * bar's map reads were invisible to `tsc` (objectui#4163).
+     *
+     * This module is locale-free BY DESIGN (`@object-ui/core` is logic-only), so
+     * it carries the authored vocabulary through unresolved and the RENDER side
+     * collapses it to the active language. Resolving here would need a locale
+     * this layer has no business knowing.
+     */
+    label?: string | I18nLabel;
     type: 'text' | 'select' | 'date' | 'number' | 'lookup' | 'dateRange';
     /**
      * Static options, NORMALIZED to `{ value, label }` pairs by
-     * `resolveDashboardFilterDefs` — authors may write either the
-     * @objectstack/spec object form (`{ value, label }`) or the bare-string
-     * shorthand; consumers always see the object form.
+     * `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.
+     *
+     * The PAIR SHAPE is normalized; the label's own vocabulary is not. `label`
+     * is `I18nLabel` in `GlobalFilterSchema.options[]` too, and it reaches the
+     * renderer as authored — see `normalizeFilterOptions` for why collapsing it
+     * here was data loss rather than normalization.
      */
     options?: Array<{
         value: string;
-        label: string;
+        label: string | I18nLabel;
     }>;
     optionsFrom?: {
         object: string;
@@ -58,8 +83,29 @@ export interface DateRangeValue {
     from?: string;
     to?: string;
 }
-/** Preset keys the filter bar offers, in display order. */
-export declare const DATE_RANGE_PRESETS: string[];
+/**
+ * Preset keys the filter bar offers, in display order — the spec's list,
+ * RE-EXPORTED since objectui#4167 rather than derived from the local bounds
+ * table (objectstack#4115).
+ *
+ * `@objectstack/spec` 17.0.0-rc.6 publishes `DATE_RANGE_PRESETS`, and its own
+ * doc comment names this module as one of the three copies the extraction
+ * (objectstack#4614) existed to collapse: "it used to exist three times —
+ * inline in `dateRange.defaultRange`, as `PRESET_RANGES` in objectui's
+ * `dashboard-filters`, and as a hand-written table in
+ * `content/docs/ui/dashboards.mdx`". So the burn-down direction here is not a
+ * judgement call, it is upstream's stated intent, and the two lists were
+ * already identical in content AND display order — the copy had nothing to
+ * 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
+ * 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. */
+export declare function resetDashboardFilterWarnings(): void;
 /**
  * Normalize a dashboard schema's filter declarations into a flat list of
  * filter definitions. The built-in `dateRange` (when declared) comes first