@object-ui/core 17.6.0 → 17.7.0

package/dist/utils/date-display.js

@@ -0,0 +1,463 @@
+/**
+ * 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 date-only ISO spelling — `2026-08-01`, and nothing else.
+ *
+ * Spelled exactly as `dataset-format.ts`'s `ISO_DATE_ONLY_RE`, which sniffs
+ * the same shape one file over to decide which arm a measure takes. Two
+ * spellings of one convention is what this module exists to prevent, so the
+ * two regexes are kept identical on purpose.
+ */
+const ISO_DATE_ONLY_RE = /^\d{4}-\d{2}-\d{2}$/;
+/**
+ * An ISO date carrying a time part — `2026-08-01T09:30:00Z`, the same with a
+ * space separator, with or without seconds or an offset. Matched only as far
+ * as `HH:mm`, so its first ten characters are the `YYYY-MM-DD` the value was
+ * written on.
+ *
+ * Spelled exactly as `dataset-format.ts`'s `ISO_DATETIME_RE`, which sniffs the
+ * same shape to route a measure to its datetime arm, for the same reason as
+ * {@link ISO_DATE_ONLY_RE} above: one convention, one spelling.
+ */
+const ISO_DATETIME_RE = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/;
+/**
+ * A date that exists — the pattern alone would accept `2024-02-31`.
+ *
+ * `true` only for a date-only ISO string (`YYYY-MM-DD`, the shape
+ * {@link ISO_DATE_ONLY_RE} names) whose year, month and day read back
+ * unchanged from the calendar. Anything else — another shape, a time part, an
+ * out-of-range month, or a day its month does not have — is `false`.
+ *
+ * ## Why this lives here (objectui#10026)
+ *
+ * It used to be module-private in `@object-ui/components`' filter builder,
+ * which refused `2026-02-30` at the AUTHORING boundary, while this module — a
+ * package below it, unable to import it — ROLLED the same value into March 2nd
+ * on every display face. One concept, two answers. It moved down, exactly as
+ * `formatDate` itself moved into this package (see the header), so the filter
+ * builder and {@link toDisplayDate} now ask the one function. ⛔ A move, not a
+ * copy: `@object-ui/components` imports it from here.
+ *
+ * ## Why the engine cannot answer this on its own
+ *
+ * ECMAScript's date-string parse accepts a DAY of `01`-`31` for every month
+ * and rolls the surplus forward: `Date.parse('2026-02-30')` is March 2nd, not
+ * `NaN`. It rejects an out-of-range MONTH (`2026-13-01`), which is why a
+ * bad month was always a dash on the display path and a bad day never was.
+ * So the day is read back instead: build the date in UTC (no zone, so no DST
+ * gap can move it) and require all three parts to survive.
+ *
+ * `setUTCFullYear` rather than `Date.UTC(year, …)`: the latter maps years
+ * 0-99 onto 1900+y, so it answered `false` for `0026-08-01` — a real day,
+ * and one {@link toDisplayDate} renders (it undoes the same legacy mapping for
+ * the same reason). The move had to fix that, or refusing through this
+ * function would have dashed every year below 100.
+ */
+export function isRealCalendarDate(dateOnly) {
+    if (!ISO_DATE_ONLY_RE.test(dateOnly))
+        return false;
+    const [year, month, day] = dateOnly.split('-').map(Number);
+    const probe = new Date(0);
+    probe.setUTCFullYear(year, month - 1, day);
+    return (probe.getUTCFullYear() === year &&
+        probe.getUTCMonth() === month - 1 &&
+        probe.getUTCDate() === day);
+}
+/**
+ * The ONE `value -> Date` step behind every function below.
+ *
+ * ## The defect (objectui#10110)
+ *
+ * ECMAScript parses the two ISO shapes into two different zones: a DATE-ONLY
+ * form is UTC, while a date-TIME form without an offset is local. So
+ * `new Date('2026-08-01')` is UTC midnight, and every getter this module then
+ * uses — `getFullYear`, `getMonth`, `getDate`, and `toLocaleDateString`'s own
+ * internal ones — reads it back in the VIEWER's zone. West of UTC that lands
+ * on the previous calendar day: `2026-08-01` rendered `Jul 31` for a UTC-7
+ * viewer while the stored value, the API response and a UTC+8 viewer all said
+ * August 1st. The relative branch shifted with it, one day per day
+ * (`2026-08-31` read `4 days ago` on the 3rd instead of `3 days ago`),
+ * because it compares two LOCAL start-of-days.
+ *
+ * ## The repair, and why it is not an offset
+ *
+ * A date-only value names a CALENDAR DAY and carries no instant, so there is
+ * no conversion to perform: this rebuilds it at LOCAL midnight of the day it
+ * names, and every local getter downstream then reports that same day in
+ * every zone. ⛔ Nothing here adds or subtracts hours. An offset that
+ * cancels the shift would be wrong again at the next DST boundary and wrong
+ * in the opposite direction for a viewer EAST of UTC, where the UTC-midnight
+ * parse already lands on the right day — the co-located suite drives both.
+ * `GridField`'s sub-grid cell already parsed its own date-only values this
+ * way before reaching `formatDate`; this is that treatment, moved to the one
+ * place every caller passes through (the sub-grid reads it from here since
+ * objectui#10301).
+ *
+ * A value with a time part is not rebuilt, in both spellings: it HAS an
+ * instant, and rendering an instant in the viewer's zone is the whole point
+ * of a `datetime`. The regex is what separates them, so the split is the
+ * VALUE's shape and never the field's declared type, which this module (pure,
+ * no schema) cannot see.
+ *
+ * ## What it refuses (objectui#10026)
+ *
+ * The engine's own parse still decides what is a date at all (`2026-13-01`
+ * is an Invalid Date, and so every face below renders `—`), with ONE
+ * addition: a date-only value naming a day its month does not have. The
+ * engine accepts `2026-02-30` and rolls it into March 2nd, so before this
+ * card every date face showed a real day nobody wrote, with nothing to say
+ * so. This step hands back an Invalid Date for it instead — the same answer
+ * the engine gives a bad month — so every caller renders the face it already
+ * renders for an unparsable value: `—` from the functions below, `EmptyValue`
+ * from the field carriers that read validity here, the raw stored string from
+ * a caller whose unparsable face is the raw string. ⛔ No new marker.
+ *
+ * The maintainer's ruling on objectui#10026 (option A) placed the refusal on
+ * the SHARED path, in this step and not in any one consumer: refusing in a
+ * single face would re-create the list-cell-versus-measure split
+ * objectui#4576 recorded. {@link isRealCalendarDate} is the one judgement,
+ * shared with the filter builder's authoring boundary.
+ *
+ * A value that carries a TIME is refused the same way when the day it is
+ * written on does not exist (objectui#10301): `2026-02-30T10:00:00Z` parses
+ * too, and rendered `Mar 2, 2026, 10:00 AM` on every datetime face. Triage
+ * graded that an inherited branch of the same ruling. The judgement reads the
+ * value's leading `YYYY-MM-DD` AS WRITTEN, never the day its instant lands on
+ * in some zone: a parsed `Date` always names a real day, so a check made after
+ * any conversion could only miss the refusal, and a real day written with an
+ * offset (`2026-02-28T23:30:00-05:00`, March 1st in UTC) is kept. A real
+ * date-time is otherwise untouched — no rebuild, the engine's instant.
+ *
+ * ## Why it is exported (objectui#10183)
+ *
+ * A caller that formats with its own `Intl` options — a face none of the
+ * functions below produce, such as the record summary chip's
+ * `dateStyle: 'medium'` — or that compares a value against "today" needs the
+ * `Date` itself, not a string. Such callers used to parse the value on their
+ * own (`new Date(value)`, or `Date.parse` and then a `Date` handed to
+ * `formatDate`, which this step then leaves alone), so the objectui#10110
+ * repair never reached them and each still read a date-only value one day
+ * early west of UTC. They take the `Date` from here instead.
+ *
+ * ⛔ Read the result with LOCAL getters or local-zone `Intl` formatting only.
+ * For a date-only value it is local midnight of the named day, so its
+ * `toISOString()` / UTC getters name the previous day east of UTC — hand
+ * those the stored value, never this.
+ */
+export function toDisplayDate(value) {
+    const parsed = value instanceof Date ? value : new Date(value);
+    // The engine rolls a date-time written on a nonexistent day forward too;
+    // judge the day as written and refuse it (objectui#10301).
+    if (typeof value === 'string' && ISO_DATETIME_RE.test(value) && !isRealCalendarDate(value.slice(0, 10))) {
+        return new Date(NaN);
+    }
+    if (typeof value !== 'string' || !ISO_DATE_ONLY_RE.test(value) || isNaN(parsed.getTime())) {
+        return parsed;
+    }
+    // The engine rolled a nonexistent day forward; refuse it (objectui#10026).
+    if (!isRealCalendarDate(value))
+        return new Date(NaN);
+    const [year, month, day] = value.split('-').map(Number);
+    const local = new Date(year, month - 1, day);
+    // Years 0-99 only: the multi-argument constructor maps them onto 1900+y, so
+    // `0026-08-01` would render as 1926 where the string parse read year 26.
+    // Setting the year back is co-extensive with that legacy mapping and a
+    // no-op on every other year.
+    local.setFullYear(year);
+    return local;
+}
+/**
+ * THE ONE READ of a stored END, where a bar or span is drawn to
+ * (objectui#11141): {@link toDisplayDate}'s read, and then, for a date-only
+ * value only, the next day's local midnight.
+ *
+ * ## The rule (objectui#11112's ruling, one home since objectui#11141)
+ *
+ * A date-only end is INCLUSIVE: `2024-01-01` to `2024-01-15` runs through
+ * January 15th, so the span is drawn to the start of the 16th, and a
+ * successor starting `2024-01-16` begins exactly where it ends. A span whose
+ * date-only start and end name the same day is one day long, across a DST
+ * change too: the step is a calendar day (`setDate`), never 24 hours, so it
+ * lands on the next local midnight, or on that day's first hour where its
+ * midnight does not exist. That is how a project plan and the schema
+ * catalog's gantt plans author an end.
+ *
+ * The result is the EXCLUSIVE end instant of a half-open span `[start, end)`,
+ * the form every gantt surface draws and schedules with. Date-only is decided
+ * by the value's own shape, with {@link isRealCalendarDate}, exactly as
+ * {@link toDisplayDate} decides it, so an end reads its day as a start does and
+ * then runs to that day's end. A value with a time part, a number or a `Date`
+ * is an instant: the span ends at it, and it is handed back as
+ * {@link toDisplayDate} hands it back.
+ *
+ * {@link toInclusiveEndDay} is the exact inverse: it names the day a span
+ * ending here runs through, so a read and a write of a date-only end agree.
+ *
+ * ⛔ One rule, one place: `plugin-timeline`'s gantt variant and
+ * `plugin-gantt` both read their ends here. A second copy of the step in a
+ * consumer is how the two gantt surfaces came to draw one plan a day apart.
+ * ⛔ Read the result with LOCAL getters only, as {@link toDisplayDate}'s is.
+ */
+export function toDisplayEndDate(value) {
+    const end = toDisplayDate(value);
+    if (typeof value !== 'string' || !isRealCalendarDate(value))
+        return end;
+    end.setDate(end.getDate() + 1);
+    // Back to the start of that day. A day whose own midnight does not exist is
+    // read at its first hour, and the step keeps the hour, so without this the
+    // day after it would start an hour late and name itself back.
+    end.setHours(0, 0, 0, 0);
+    return end;
+}
+/**
+ * The day a span ending at `end` runs through: local midnight of the day that
+ * holds the last instant before `end` (objectui#11141).
+ *
+ * This is the exact inverse of {@link toDisplayEndDate} on a date-only end:
+ * the instant it reads `2024-01-15` as, local midnight of the 16th, names the
+ * 15th here, so a read, a drag and a write of a stored date-only end leave it
+ * the day it was, and a bar dragged to end at a day's local midnight names the
+ * day BEFORE it. An end inside a day (a `datetime` end, or a shift band's
+ * edge) names that day, the last one the span reaches into.
+ *
+ * It names a day for display and for a date-only write. ⛔ It is not a read of
+ * a stored value, and a `datetime` end still keeps its own instant: hand this
+ * only to a face that names a day, or to a field that stores one. Read the
+ * result with LOCAL getters only; an Invalid Date stays invalid.
+ */
+export function toInclusiveEndDay(end) {
+    const day = new Date(end.getTime() - 1);
+    day.setHours(0, 0, 0, 0);
+    return day;
+}
+/**
+ * Localized day-granularity relative phrase ("Tomorrow", "3 days ago", "明天",
+ * "3天前"), sentence-cased for locales whose `Intl` output starts lowercase.
+ */
+function formatRelativeDays(diffDays, locale) {
+    try {
+        const phrase = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' }).format(diffDays, 'day');
+        return phrase.charAt(0).toUpperCase() + phrase.slice(1);
+    }
+    catch {
+        // Invalid locale tag — degrade to English rather than crash the cell.
+        if (diffDays === 0)
+            return 'Today';
+        if (diffDays === 1)
+            return 'Tomorrow';
+        if (diffDays === -1)
+            return 'Yesterday';
+        return diffDays > 0 ? `In ${diffDays} days` : `${Math.abs(diffDays)} days ago`;
+    }
+}
+/**
+ * The options bag {@link formatRelativeDate} hands to {@link formatDate} for
+ * its out-of-window ABSOLUTE fallback, with `style` neutralised.
+ *
+ * Two reasons, both load-bearing since objectui#7745 made `formatDate` read
+ * `options.style`:
+ *
+ *   1. **Behaviour preservation.** `formatRelativeDate` does not read
+ *      `options.style`, and #7745 does not change that. Without the strip it
+ *      would start reading it THROUGH this delegation for dates outside the
+ *      ±7-day window only — a face change on a live path (grid cell, gantt
+ *      tooltip) that no card authorises.
+ *   2. **Termination.** `formatDate` resolves `'relative'` by calling
+ *      `formatRelativeDate`, which lands back here. With the style still in
+ *      the bag, `formatRelativeDate(v, { style: 'relative' })` on an
+ *      out-of-window date would recurse until the stack ran out.
+ *
+ * The bag is returned UNCHANGED when there is nothing to strip, so the common
+ * path allocates nothing.
+ */
+function absoluteFallbackOptions(options) {
+    if (options === undefined || options.style === undefined)
+        return options;
+    return { ...options, style: undefined };
+}
+/**
+ * Format date as relative time (e.g., "3 days ago", "Today", "Overdue 3d"),
+ * localized via `Intl.RelativeTimeFormat` (objectstack-ai/objectstack#3040).
+ *
+ * `dueLike` gates the "Overdue" wording — a past `start_date`/`created_at`
+ * isn't overdue, only a past due/deadline-semantic field is. Non-due-like
+ * past dates render as plain "N days ago" instead. The overdue phrase has no
+ * `Intl` equivalent, so it resolves through `options.t` (key
+ * `fields.relativeDate.overdue`) with an English fallback.
+ */
+export function formatRelativeDate(value, options) {
+    if (value === null || value === undefined || value === '')
+        return '—';
+    const date = toDisplayDate(value);
+    if (!(date instanceof Date) || isNaN(date.getTime()))
+        return '—';
+    const now = new Date();
+    const startOfToday = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+    const startOfDate = new Date(date.getFullYear(), date.getMonth(), date.getDate());
+    const diffMs = startOfDate.getTime() - startOfToday.getTime();
+    const diffDays = Math.round(diffMs / (1000 * 60 * 60 * 24));
+    // Beyond the ±7-day window, fall back to the absolute (already localized) form.
+    if (diffDays < -7 || diffDays > 7)
+        return formatDate(date, undefined, absoluteFallbackOptions(options));
+    if (diffDays < -1 && options?.dueLike) {
+        const absDays = Math.abs(diffDays);
+        const key = 'fields.relativeDate.overdue';
+        const translated = options.t?.(key, { count: absDays });
+        return translated && translated !== key ? translated : `Overdue ${absDays}d`;
+    }
+    return formatRelativeDays(diffDays, options?.locale);
+}
+/**
+ * Format date value.
+ *
+ * The named face comes from EITHER spelling — the positional `style`
+ * parameter or `options.style` — and the precedence between them is pinned
+ * (objectui#7745):
+ *
+ * > **The positional argument wins. `options.style` is consulted only when the
+ * > positional slot is `undefined`.**
+ *
+ * Before #7745 only the positional spelling was read here, while
+ * {@link formatDateTime} read only the `options` one — one shared bag, two
+ * spellings for one concept, and on THIS function the options spelling did
+ * nothing at all: `formatDate(v, undefined, { style: 'short' })` silently
+ * rendered the default face with no diagnostic. Reading the key is the
+ * additive half of the maintainer's long-run ruling on objectui#7443.
+ *
+ * Why the positional wins, and not the newer key:
+ *
+ *   - It is the ONLY direction that is purely additive. It fires exactly on
+ *     the input that is a silent no-op today (positional absent, key present);
+ *     every call that renders a face today renders the same face after.
+ *   - The bag is SHARED across three functions, so it can legitimately carry a
+ *     key meant for a sibling — that is this module's convention (`dueLike`
+ *     and `t` are read by `formatRelativeDate` alone). A caller that built
+ *     `{ style: 'compact', locale }` for `formatDateTime` and reused the bag
+ *     for `formatDate(v, 'short', bag)` must keep its short face. A key aimed
+ *     at a sibling function must not outrank an argument written for THIS
+ *     call — that is objectui#7694's shape (an alias overwriting the canonical
+ *     key), and the silent-override half of objectui#4272.
+ *
+ * `??`, not `||`, is what "absent" means here: `formatDate(v, '', bag)`
+ * renders the default face today and must keep doing so, so an empty string
+ * counts as GIVEN and does not fall through to the key.
+ */
+export function formatDate(value, style, options) {
+    if (value === null || value === undefined || value === '')
+        return '—';
+    const date = toDisplayDate(value);
+    if (!(date instanceof Date) || isNaN(date.getTime()))
+        return '—';
+    const effectiveStyle = style ?? options?.style;
+    if (effectiveStyle === 'short') {
+        // Compact format for mobile: "Jan 15, '24" / "1月 15, '24".
+        // Only the MONTH token is localized: the surrounding compact shape (day,
+        // apostrophe + 2-digit year) is a deliberate fixed layout for narrow
+        // cards, not a locale-derived one. The tag comes from `options.locale`
+        // like the default branch below — hardcoding `'en-US'` here made this the
+        // one branch that ignored a locale its caller had threaded (objectui#4272).
+        const month = date.toLocaleDateString(options?.locale, { month: 'short' });
+        const day = date.getDate();
+        const year = String(date.getFullYear()).slice(-2);
+        return `${month} ${day}, '${year}`;
+    }
+    if (effectiveStyle === 'relative') {
+        return formatRelativeDate(date, options);
+    }
+    // Default format: locale-aware human-readable. Drop the year when it
+    // matches the current year — Salesforce / HubSpot / Linear all do this
+    // because the year is rarely useful for in-progress records and the
+    // verbose "2026年7月21日" form crowds cards and table cells. Past- /
+    // future-year dates keep the year so users can disambiguate.
+    const isCurrentYear = date.getFullYear() === new Date().getFullYear();
+    return date.toLocaleDateString(options?.locale, {
+        year: isCurrentYear ? undefined : 'numeric',
+        month: 'short',
+        day: 'numeric',
+    });
+}
+/**
+ * The `'compact'` datetime face as the two halves a grid cell paints
+ * separately — `7/4/2024` and `7:00 am` for `2024-07-04T07:00:00Z` in `en-US`.
+ *
+ * `formatDateTime(value, { style: 'compact', ...options })` is exactly
+ * `date + ' ' + time` of what this returns, so a caller that wants the face
+ * as ONE string and a caller that wants to style the halves differently
+ * cannot drift apart. That drift is what objectui#7443 recorded:
+ * `DateTimeCellRenderer` inlined these two option bags and never called this
+ * module, so `datetime` had two display conventions while `date` had one —
+ * the same shape as objectui#4576, which this repo has already paid for once.
+ *
+ * `null` for a value this module renders as `'—'`; the cell renders its own
+ * empty state for those, so it never sees the dash.
+ */
+export function formatDateTimeCompactParts(value, options) {
+    if (value === null || value === undefined || value === '')
+        return null;
+    const date = toDisplayDate(value);
+    if (!(date instanceof Date) || isNaN(date.getTime()))
+        return null;
+    return {
+        date: date.toLocaleDateString(options?.locale, {
+            month: 'numeric',
+            day: 'numeric',
+            year: 'numeric',
+        }),
+        // `hour12` stays declared: this is the compact Airtable-style cell, and
+        // the 12-hour face is its design, not a locale artefact. Locales that
+        // write no am/pm marker simply ignore it.
+        time: date.toLocaleTimeString(options?.locale, {
+            hour: 'numeric',
+            minute: '2-digit',
+            hour12: true,
+        }).toLowerCase(),
+    };
+}
+/**
+ * Format datetime value.
+ *
+ * `options.style` selects a named face:
+ *
+ *   - `'compact'` — the dense grid face, `7/4/2024 7:00 am` in `en-US`. It is
+ *     what every `datetime` CELL renders, and what `DateTimeCellRenderer`
+ *     used to build from its own inlined `Intl` bags (objectui#7443).
+ *   - anything else, including absent — the verbose default,
+ *     `Jul 4, 2024, 07:00 AM` in `en-US`. Unchanged, and still what a
+ *     non-cell caller (dataset measure, gantt tooltip, data-table) gets.
+ *
+ * The signature is `(value, options?)`, unchanged: `style` is a key of
+ * `options`, not a positional parameter, so every existing call —
+ * `formatDateTime(v, { locale })` included — keeps meaning exactly what it
+ * meant (see the note on `DateDisplayOptions.style` for why the positional
+ * shape `formatDate` uses was refused here).
+ *
+ * `options` is optional, so a caller that passes nothing keeps the exact
+ * runtime-default behavior it had. Before objectui#4272 the parameter did not
+ * exist at all, which meant no caller could localize this function however
+ * hard it tried — it always handed `Intl` an `undefined` tag, i.e. the
+ * MACHINE's locale, which is neither of the repo's two locale channels.
+ * Callers should pass the tag from `useDisplayLocale()`.
+ */
+export function formatDateTime(value, options) {
+    if (value === null || value === undefined || value === '')
+        return '—';
+    const date = toDisplayDate(value);
+    if (!(date instanceof Date) || isNaN(date.getTime()))
+        return '—';
+    if (options?.style === 'compact') {
+        const parts = formatDateTimeCompactParts(date, options);
+        return parts ? `${parts.date} ${parts.time}` : '—';
+    }
+    return date.toLocaleDateString(options?.locale, {
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric',
+        hour: '2-digit',
+        minute: '2-digit',
+    });
+}

package/dist/utils/date-macros.js

@@ -182,7 +182,14 @@ export function resolveDateMacros(filter, now = new Date()) {
         }
         if (Array.isArray(value))
             return value.map(walk);
+        // Only a PLAIN object (prototype `Object.prototype` or `null`) is walked;
+        // any other object — a `Date` comparand above all — is returned as the
+        // same instance rather than rebuilt from its own keys 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]);

package/dist/utils/drill-down.d.ts

@@ -89,3 +89,81 @@ export declare function computeDrillFilter(config: DrillDownConfig | undefined,
 export declare function resolveDrillTitle(config: DrillDownConfig | undefined, event: DrillEvent, fallback?: string): string;
 /** Whether drill-down is enabled on a config (treats `{}` as enabled too). */
 export declare function isDrillEnabled(config: DrillDownConfig | undefined): boolean;
+/**
+ * Compose a widget's OWN filter with the filter a drill click derived, into the
+ * one filter the drilled list is scoped by.
+ *
+ * ## The rule: `widget.filter ∧ drill.filter`
+ *
+ * The two are independent filter SOURCES and a drill must satisfy BOTH. The
+ * widget's filter is what scopes the chart; the click context only says WHICH
+ * bucket of that scope the user asked to see. So a drill may narrow the widget's
+ * scope and may never widen it — which makes the composition a conjunction, not
+ * a merge and emphatically not a spread.
+ *
+ * ⛔ The rule is NOT invented here. It is the contract {@link mergeFilterNodes}
+ * already states — "combine filter sources under a single `and`, each as its OWN
+ * child" — the sink every other multi-source filter in this repo goes through
+ * (`ObjectView`, `RelatedList`, `LineItemsPanel`, `RecordPickerDialog`,
+ * `ElementDataSourceGate`, `buildEffectiveFilter`). This function only applies
+ * it at the drill seam and names it, so the answer is in one place rather than
+ * re-derived per widget.
+ *
+ * ## Why the two arms needed a sink at all (objectui#8944)
+ *
+ * `ObjectChartSchema.filter` admits BOTH a spec `FilterArray`
+ * (`[['stage','=','won']]`) and the ObjectQL `$filter` object
+ * (`{ close_date: { $gte } }`), because both are read — both are forwarded
+ * verbatim to `ds.aggregate` / `ds.find`. The drill seam used to compose them by
+ * SPREADING the widget's filter into an object literal, which is correct for the
+ * object arm and silent nonsense for the array arm: spreading `[['stage','=',
+ * 'won']]` yields the index key `{ '0': ['stage','=','won'] }`, so the widget's
+ * own conditions were replaced by a key the query layer ignores and the drilled
+ * list showed rows the chart itself was scoped to exclude. `toFilterNode` (via
+ * `mergeFilterNodes`) already lowers all three shapes in circulation, so routing
+ * the pair through it is what makes the array arm survive.
+ *
+ * ## Why the result is lowered back to the object dialect
+ *
+ * {@link mergeFilterNodes} answers in the ObjectQL AST
+ * (`['and', <widget>, <drill>]`). Both drill sinks take the `FilterCondition`
+ * OBJECT dialect instead — the drawer hands the value to `object-data-table`'s
+ * `filter` (which becomes `$filter`), and `DrillNavigationContext.openRecordList`
+ * declares `Record<string, unknown>` and serializes it to `filter[...]` URL
+ * params. `parseFilterAST` is the spec's single lowering sink between the two
+ * dialects, so it is what converts, rather than a second local translation.
+ *
+ * ⭐ A lone surviving source lowers back to exactly the flat object the spread
+ * produced (`{ stage: 'won' }`), so a chart with no filter of its own drills
+ * identically to before; only a genuinely composed pair gains the `$and`.
+ *
+ * Returns `undefined` when neither source carries anything, so callers can omit
+ * the key rather than send an empty filter.
+ *
+ * ⚠️ Refusals are the sink's, not this seam's: `mergeFilterNodes` rejects a
+ * comparand the wire would also reject (a bare array on `=`, a `RegExp`) with
+ * the `INVALID_FILTER` / 400 envelope. Such a filter already fails the widget's
+ * OWN query for the same reason, so the drill and the chart now agree instead of
+ * the drill quietly sending something the chart could not.
+ *
+ * ## One refusal type out of this seam (objectui#10789)
+ *
+ * The seam has TWO refusing steps, and they used to throw two different
+ * things. `mergeFilterNodes` throws a {@link FilterOperatorError}. The spec's
+ * `parseFilterAST`, which judges comparand shapes the converter passes
+ * through, throws a plain `Error` that carries the same envelope as own
+ * properties: `code: 'INVALID_FILTER'` and `status: 400`. An array-dialect
+ * widget filter holds no rule objects, so the converter never judges it, and
+ * `[['stage', 'in', 'won']]` (a scalar on a list operator) is refused only
+ * there. So is the object spelling `{ stage: { $in: 'won' } }`.
+ *
+ * Every caller catches the refusal as a `FilterOperatorError`: the chart,
+ * pivot and dataset drills report it and open nothing (never a filter-less
+ * drill). So the spec's refusal is re-raised here AS one, with its message
+ * verbatim and the same `INVALID_FILTER` / 400 envelope, rather than taught to
+ * each caller as a second shape. Only an error whose `code` is
+ * `INVALID_FILTER` is re-raised; anything else from `parseFilterAST` is a
+ * defect rather than a statement about the author's filter, and passes
+ * through untouched.
+ */
+export declare function composeDrillFilter(widgetFilter: unknown, drillFilter: Record<string, unknown> | undefined): Record<string, unknown> | undefined;

package/dist/utils/drill-down.js

@@ -21,6 +21,8 @@
  * The helpers are intentionally protocol-agnostic — any caller can
  * synthesize an `event` object and rely on the same defaults / templating.
  */
+import { parseFilterAST } from '@objectstack/spec/data';
+import { FilterOperatorError, mergeFilterNodes } from './filter-converter.js';
 const TEMPLATE = /\$\{event\.([a-zA-Z0-9_]+)\}/g;
 /**
  * Substitute `${event.x}` placeholders in a string with values from the
@@ -137,3 +139,94 @@ export function isDrillEnabled(config) {
         return false;
     return config.enabled !== false;
 }
+/**
+ * Compose a widget's OWN filter with the filter a drill click derived, into the
+ * one filter the drilled list is scoped by.
+ *
+ * ## The rule: `widget.filter ∧ drill.filter`
+ *
+ * The two are independent filter SOURCES and a drill must satisfy BOTH. The
+ * widget's filter is what scopes the chart; the click context only says WHICH
+ * bucket of that scope the user asked to see. So a drill may narrow the widget's
+ * scope and may never widen it — which makes the composition a conjunction, not
+ * a merge and emphatically not a spread.
+ *
+ * ⛔ The rule is NOT invented here. It is the contract {@link mergeFilterNodes}
+ * already states — "combine filter sources under a single `and`, each as its OWN
+ * child" — the sink every other multi-source filter in this repo goes through
+ * (`ObjectView`, `RelatedList`, `LineItemsPanel`, `RecordPickerDialog`,
+ * `ElementDataSourceGate`, `buildEffectiveFilter`). This function only applies
+ * it at the drill seam and names it, so the answer is in one place rather than
+ * re-derived per widget.
+ *
+ * ## Why the two arms needed a sink at all (objectui#8944)
+ *
+ * `ObjectChartSchema.filter` admits BOTH a spec `FilterArray`
+ * (`[['stage','=','won']]`) and the ObjectQL `$filter` object
+ * (`{ close_date: { $gte } }`), because both are read — both are forwarded
+ * verbatim to `ds.aggregate` / `ds.find`. The drill seam used to compose them by
+ * SPREADING the widget's filter into an object literal, which is correct for the
+ * object arm and silent nonsense for the array arm: spreading `[['stage','=',
+ * 'won']]` yields the index key `{ '0': ['stage','=','won'] }`, so the widget's
+ * own conditions were replaced by a key the query layer ignores and the drilled
+ * list showed rows the chart itself was scoped to exclude. `toFilterNode` (via
+ * `mergeFilterNodes`) already lowers all three shapes in circulation, so routing
+ * the pair through it is what makes the array arm survive.
+ *
+ * ## Why the result is lowered back to the object dialect
+ *
+ * {@link mergeFilterNodes} answers in the ObjectQL AST
+ * (`['and', <widget>, <drill>]`). Both drill sinks take the `FilterCondition`
+ * OBJECT dialect instead — the drawer hands the value to `object-data-table`'s
+ * `filter` (which becomes `$filter`), and `DrillNavigationContext.openRecordList`
+ * declares `Record<string, unknown>` and serializes it to `filter[...]` URL
+ * params. `parseFilterAST` is the spec's single lowering sink between the two
+ * dialects, so it is what converts, rather than a second local translation.
+ *
+ * ⭐ A lone surviving source lowers back to exactly the flat object the spread
+ * produced (`{ stage: 'won' }`), so a chart with no filter of its own drills
+ * identically to before; only a genuinely composed pair gains the `$and`.
+ *
+ * Returns `undefined` when neither source carries anything, so callers can omit
+ * the key rather than send an empty filter.
+ *
+ * ⚠️ Refusals are the sink's, not this seam's: `mergeFilterNodes` rejects a
+ * comparand the wire would also reject (a bare array on `=`, a `RegExp`) with
+ * the `INVALID_FILTER` / 400 envelope. Such a filter already fails the widget's
+ * OWN query for the same reason, so the drill and the chart now agree instead of
+ * the drill quietly sending something the chart could not.
+ *
+ * ## One refusal type out of this seam (objectui#10789)
+ *
+ * The seam has TWO refusing steps, and they used to throw two different
+ * things. `mergeFilterNodes` throws a {@link FilterOperatorError}. The spec's
+ * `parseFilterAST`, which judges comparand shapes the converter passes
+ * through, throws a plain `Error` that carries the same envelope as own
+ * properties: `code: 'INVALID_FILTER'` and `status: 400`. An array-dialect
+ * widget filter holds no rule objects, so the converter never judges it, and
+ * `[['stage', 'in', 'won']]` (a scalar on a list operator) is refused only
+ * there. So is the object spelling `{ stage: { $in: 'won' } }`.
+ *
+ * Every caller catches the refusal as a `FilterOperatorError`: the chart,
+ * pivot and dataset drills report it and open nothing (never a filter-less
+ * drill). So the spec's refusal is re-raised here AS one, with its message
+ * verbatim and the same `INVALID_FILTER` / 400 envelope, rather than taught to
+ * each caller as a second shape. Only an error whose `code` is
+ * `INVALID_FILTER` is re-raised; anything else from `parseFilterAST` is a
+ * defect rather than a statement about the author's filter, and passes
+ * through untouched.
+ */
+export function composeDrillFilter(widgetFilter, drillFilter) {
+    const merged = mergeFilterNodes(widgetFilter, drillFilter);
+    try {
+        // `FilterCondition` is the spec's object-dialect filter; the drill sinks
+        // type the same value as `Record<string, unknown>`, and this is the one
+        // seam where the two names meet.
+        return parseFilterAST(merged);
+    }
+    catch (error) {
+        if (error?.code !== 'INVALID_FILTER')
+            throw error;
+        throw new FilterOperatorError(error.message);
+    }
+}