Skip to content

Commit df86293

Browse files
committed
Merge origin/main into claude/project-thread-mvhzud
Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WGufziGaNnGcwiYSC9Qzck
2 parents 2e1e09d + b322b5d commit df86293

67 files changed

Lines changed: 2922 additions & 200 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.changeset/26602-delta-polarity.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
'@object-ui/plugin-dashboard': minor
3+
---
4+
5+
Clause-②: yes (widening)
6+
Metadata-protocol: added
7+
8+
A dataset-bound KPI tile and a cross-tab cell colour their period-over-period delta by the measure's declared `polarity` (`fields[].polarity` on the dataset answer, objectstack#26602). `'lower'` draws a rise red and a fall green, so a slower approval turnaround no longer reads as good news. `'neutral'` draws the delta in the muted text colour, with no green and no red. `'higher'`, and an undeclared polarity, keep the colours every delta had before: a rise green, a fall red. The arrow still shows which way the number moved under every polarity.
Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
'@objectstack/spec': minor
3+
'@objectstack/service-analytics': minor
4+
'@objectstack/platform-objects': minor
5+
---
6+
7+
feat(spec): a dataset measure declares its `polarity`, so a lower-is-better KPI draws a rising delta as bad news
8+
9+
Clause-②: yes (widening)
10+
Metadata-protocol: added
11+
12+
`DatasetMeasureSchema` declares one optional key, `polarity`, with three values (`DatasetMeasurePolarity`): `'higher'` (a rise is good), `'lower'` (a fall is good: turnaround days, overdue counts, cost) and `'neutral'` (neither direction is good or bad). It is declared on the measure, the semantic layer, so every widget over the measure agrees, and not on a widget's `compareTo`, which is the executor's closed comparison directive. An undeclared polarity keeps today's colours: a rise green, a fall red. Nothing infers a polarity from the measure's name. The near-miss keys `betterWhen`, `direction`, `goodDirection` and `trendDirection` are pointed at `polarity`, and the boolean spellings `higherIsBetter` / `lowerIsBetter` are answered with the three values.
13+
14+
The dataset answer's column descriptor declares the same vocabulary as `fields[].polarity` (`AnalyticsResult` and `AnalyticsResultResponseSchema`), and the analytics service relays the measure's declared value onto it, on the live query and the draft-data preview alike, the measure's `__compare` column included. An undeclared measure and every dimension column carry no `polarity` key, so an answer over a dataset that declares none is unchanged.
15+
16+
The dataset form's measures repeater offers `polarity`, labelled in every shipped locale (`@objectstack/platform-objects` metadata-form catalogs).
Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
'@objectstack/formula': minor
3+
---
4+
5+
feat(formula): the mail hole grammar admits `currency:@path`, which reads the ISO 4217 code from the send's data; the in-app template dialect refuses that form by name
6+
7+
Clause-②: yes
8+
Metadata-protocol: added
9+
10+
A mail template can now format each record's amount in that record's own currency: `{{ planned_amount | currency:@currency_code }}`. The rule, exported as `CURRENCY_ARGUMENT_RULE`: a `currency` argument is either a literal ISO 4217 code in three capital letters (`currency:EUR`) or, in a mail template only, `@` followed by a path into the send's data whose value is such a code (`currency:@currency_code`).
11+
12+
- **Widened:** `parseMailHole` and `judgeMailHoleGrammar` admit `currency:@path` when the path is a dotted path of word characters with no empty segment, written right after the `@` and not in quotes. The parsed hole carries the path as `codePath`.
13+
- **Unchanged refusals:** a bare argument is still never read as a path, so `currency:currency_code`, `currency:record.currency_code`, a lowercase or empty code and a double-quoted code stay refused (`currency-code-literal`); so do `currency:@`, `currency:@ x`, `currency:'@x'` and `currency:@a..b`. In the mail dialect that refusal now names the marked form as the way to read a code from the data.
14+
- **Declared variables:** `judgeMailHoleGrammar(face, { variables })` refuses a marked path that none of the template's declared variables names, itself or as a root it lies under (`currency-code-path-undeclared`), when the template declares any.
15+
- **In-app dialect:** `templateEngine` (flow text slots, action and bulk-action copy, `titleFormat`, `promptTemplate`) refuses `currency:@path` at compile and evaluate with its own rule, `currency-code-path-mail-only`: the doors that judge that text check a hole's path against the roots a slot binds and never read an argument. It was refused there before too, as `currency-code-literal`.
16+
- **The value:** `currencyCodeValueRefusal(hole, path, value)` names a resolved value that is not an ISO 4217 code in three capital letters exactly as stored (missing, `null`, `eur`, `' EUR'`, a number). `formatValue('currency', …)` still never reads a path and still throws for a non-code argument; no argument still formats in US dollars.
17+
18+
New exports: `CURRENCY_ARGUMENT_RULE`, `currencyCodePath`, `currencyCodeValueRefusal`, and the types `TemplateHoleDialect` and `MailHoleGrammarOptions`. `judgeHoleFormatter` takes an optional fifth argument, the dialect (`'in-app'` by default, `'mail'`), and `TemplateHoleGrammarRule` gains `currency-code-path-mail-only` and `currency-code-path-undeclared`.
Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
'@objectstack/lint': minor
3+
---
4+
5+
feat(lint): `email-template-hole-grammar` accepts `currency:@path` and refuses a marked path the template's declared variables do not declare
6+
7+
Clause-②: yes
8+
Metadata-protocol: added
9+
10+
`os validate`, `os build`, `os lint` and the `email_template` publish door accept a mail template hole such as `{{ planned_amount | currency:@currency_code }}`, which reads the ISO 4217 code from the send's data, when its path is well-formed. When the template declares `variables`, a marked path that none of them declares, itself or as a root it lies under (`contract` declares `contract.currency_code`), is refused at `error` (a `422 INVALID_METADATA` at the publish door), naming the hole and the path. A template that declares no variables has the path judged at render.
11+
12+
Everything the rule refused before stays refused: a bare path (`currency:currency_code`), a lowercase or empty code, a quoted or empty marked path, and a second formatter. The finding's hint now quotes the argument rule, `CURRENCY_ARGUMENT_RULE` from `@objectstack/formula`.
Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
'@objectstack/plugin-email': minor
3+
---
4+
5+
feat(plugin-email): a mail template formats an amount in the record's own currency with `currency:@path`
6+
7+
Clause-②: yes
8+
Metadata-protocol: added
9+
10+
`{{ planned_amount | currency:@currency_code }}` formats the amount in the currency whose ISO 4217 code the send's `data` holds at `currency_code`, so one template, in every locale row of its bundle, serves records in many currencies. With `currency_code: 'EUR'` it renders `€1,234.50` in `en-US`; with `'CNY'` it renders `CN¥1,234.50` in `en-US` and `¥1,234.50` in `zh-CN`. The path is resolved like a hole's own path, in all three faces, double- or triple-braced.
11+
12+
The value at the path must be the code in three capital letters, as stored. A missing or `null` value, a lowercase code (`eur`) or any other value makes `renderTemplate` and `sendTemplate` throw `TEMPLATE_INVALID: email template NAME (locale=L): …`, naming the hole, the path and the value, and send nothing. The amount is never formatted in a default currency in its place.
13+
14+
Unchanged: a literal code (`currency:EUR`) formats in that code, no argument formats in US dollars, and a bare path (`currency:currency_code`) is still refused with `TEMPLATE_INVALID`.
Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
'@objectstack/spec': minor
3+
---
4+
5+
docs(spec): the `email_template` faces state the mail hole grammar, including `currency:@path`, which reads the ISO 4217 code from the send's data
6+
7+
Clause-②: yes
8+
Metadata-protocol: added
9+
10+
`EmailTemplateDefinitionSchema`'s `subject`, `bodyHtml` and `bodyText` descriptions now state the hole grammar a mail template is rendered and judged with: holes are `{{ path }}` or `{{ path | formatter[:arg] }}` over the send's `data`, with one formatter per hole, and a `currency` argument is either a literal ISO 4217 code in three capital letters (`currency:EUR`) or, in a mail template only, `@` followed by a path into the send's data whose value is such a code (`currency:@currency_code`). The `variables[].name` description adds that, when a template declares any variable, the path of a `currency:@path` argument must be one of them or lie under one.
11+
12+
Only descriptions change; no key, type or default does. The form itself is judged by `@objectstack/formula`, refused or accepted at authoring by `@objectstack/lint` and rendered by `@objectstack/plugin-email`.
Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
'@objectstack/service-analytics': patch
3+
'@objectstack/spec': patch
4+
---
5+
6+
fix(service-analytics): a windowed dataset answer reports its window in `drillRanges`, so a drill list stays inside the picked period
7+
8+
Clause-②: yes (widening)
9+
Metadata-protocol: none
10+
11+
A dataset query whose selection carries `timeDimensions[].dateRange` (a report's picked period) counts only that period's records, but its answer's `drillRanges` covered only the date dimensions it groups by. So a report run on "this quarter" and grouped by stage drilled to a list of every period's deals, and a month bucket cut by `last_30_days` drilled the whole month.
12+
13+
- **The window rides `drillRanges`.** A windowed dimension that is not grouped gets an entry on every row: the `[gte, lt)` the query filtered by. A windowed field that a bucket already bounds narrows that bucket's entry to the part inside the window, and adds no entry of its own, so an edge bucket drills only its in-window records. Drill hosts already filter by every `drillRanges` entry, by its `field`, so they need no change.
14+
- **One window, not a second resolver.** The bounds come from the query's own steps: the preset resolved in the reference time zone, an explicit `[a, b]` as written, the shared whole-day lowering (a bare-day end runs to the start of the next day), and the engine's temporal storage form: ISO instants for a `datetime` field, `YYYY-MM-DD` days for a `date` field.
15+
- **No entry when there is no exact spelling.** An explicit window whose end is an instant (compared with `<=`), or whose end is the last supported day (no upper bound), gets no entry, and the drill stays as wide as before. So does a field whose type is unknown under a non-UTC time zone, as for buckets.
16+
- **Spec.** The `drillRanges` docblock on `AnalyticsResult` and its `.describe` text on the dataset answer schema say what the key now carries. No key is added.
Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
'@objectstack/spec': patch
3+
---
4+
5+
fix(spec): a retired filter operator's refusal names every replacement before the 500-character client cap
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
`POST /api/v1/data/OBJECT/query` with `{ "title": { "$regex": "acme" } }` answers `400 INVALID_FILTER`, and a client reads at most 500 characters of the message. The five refusal sites print `RETIRED_FILTER_OPERATORS[op].why` after their own lead-in, and `$regex`'s prescription opened with the history of the retirement, so `$contains` (the case-sensitive alternative) and "match in application code" (for a pattern that really needs a regex) were cut off. Both prescriptions now lead with what to write and put the history after it: `$regex` names `$icontains`, `$contains` and the application-code route first, and `$options` now says to delete it and write `$icontains`. The table, the operators it names, the cap and the error envelope are unchanged; only the order and wording of the two `why` strings change.

‎content/docs/api/data-api.mdx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -474,7 +474,8 @@ is executed. `POST /analytics/sql` refuses the same keys. To order by a member,
474474
<Callout type="info">
475475
**`fields[]` is the resolved presentation surface — read it first.** Each entry carries
476476
`name` and `type` and, when the producer declares them, `label`, `format`, `currency`,
477-
`percentScale`, `builtinAggregate`, `aggregate` and `nullLabel`: the optional members
477+
`percentScale`, `builtinAggregate`, `aggregate`, `nullLabel` and `polarity` (which direction
478+
of a measure's change is good news, relayed from the dataset measure): the optional members
478479
`AnalyticsResultResponseSchema` declares (`packages/spec/src/api/analytics.zod.ts`),
479480
mirrored member for member by `IAnalyticsService.query`'s `AnalyticsResult` and bound to
480481
it at compile time. Optional means a given column may omit them — read them defensively,

‎content/docs/automation/email-templates.mdx‎

Lines changed: 31 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -88,14 +88,37 @@ never needs triple braces.
8888
chaining. Decide the value in the caller that supplies the data — a default, a
8989
second format — and pass the finished value as its own variable.
9090

91-
**The `currency` argument is a literal code.** `currency:EUR` formats in euros,
92-
and `currency` with no argument formats in US dollars. The argument is an ISO
93-
4217 code in three capital letters, never a path: `currency:currency_code` does
94-
not read the record's `currency_code`. `os validate`, `os build`, `os lint` and
95-
the metadata publish door refuse any other argument (`email-template-hole-grammar`,
96-
a `422 INVALID_METADATA` at the publish door), naming the hole and the rule. To
97-
show an amount in each record's own currency, format it in the caller that
98-
supplies the data and pass the formatted text as its own variable.
91+
**The `currency` argument is a literal code or a marked path.** A `currency`
92+
argument is either a literal ISO 4217 code in three capital letters
93+
(`currency:EUR`) or, in a mail template only, `@` followed by a path into the
94+
send's data whose value is such a code (`currency:@currency_code`). `currency`
95+
with no argument formats in US dollars.
96+
97+
The marked path is how one template shows each record's amount in that record's
98+
own currency:
99+
100+
```ts
101+
subject: 'Instalment overdue: {{ planned_amount | currency:@currency_code }}',
102+
```
103+
104+
With `data` holding `planned_amount: 1234.5` and `currency_code: 'EUR'` it renders
105+
`€1,234.50` in `en-US`; with `currency_code: 'CNY'` it renders `CN¥1,234.50`. The
106+
value at the path must be the code in capitals, as stored: a missing or `null`
107+
value, a lowercase code (`eur`) or anything else makes the render fail with
108+
`TEMPLATE_INVALID`, naming the template, its locale, the hole and the value. The
109+
amount is never formatted in a default currency in its place.
110+
111+
A bare argument is never read as a path: `currency:currency_code` is refused,
112+
and so are a lowercase or empty code, a quoted path and an `@` with no path
113+
after it. `os validate`, `os build`, `os lint` and the metadata publish door
114+
refuse these (`email-template-hole-grammar`, a `422 INVALID_METADATA` at the
115+
publish door), naming the hole and the rule. When the template declares
116+
`variables`, the same doors also refuse a marked path that none of them
117+
declares (a variable `contract` declares `contract.currency_code`).
118+
119+
The `@` form belongs to mail templates. In-app template text (flow
120+
notifications, action and bulk-action copy) takes a literal code only and
121+
refuses `currency:@path` by name.
99122

100123
**Where a hole may sit in `bodyHtml`.** The renderer's escaping is right for
101124
element text and for a quoted attribute value that holds plain text, so those

0 commit comments

Comments
 (0)