Skip to content
This repository was archived by the owner on Nov 4, 2026. It is now read-only.

Commit 7f2a5f4

Browse files
committed
fix(plugin-grid): header arrows read the ONE declared sort spelling (objectui#8961)
Executes the maintainer ruling of 2026-09-15, director batch #135 item 5, letter A. Not a decision; execution. ## What a user saw A view authored `sort: "name desc"` lit a descending arrow on the `name` header before anyone clicked anything, while the query that fetched those rows carried no ordering at all. The arrow stated something about the list that was not true of the rows beside it, and the first click on that column then asked for `asc` on a list that was in no declared order. The only signal was a `console.error` no end user reads. ## Why the two halves disagreed objectui#8221 retired the legacy string clause — one spelling, the array, everywhere — and objectui#8767 (route C) made this block's fetch path REFUSE a string `sort` and send no `$orderby`. That ruling deliberately left the other reader of the same key alone: `parseSchemaSort`, which feeds the header indicators, went on parsing `"name desc"` and `["name desc", ...]`. One key, two readers, opposite answers. ## What this does `parseSchemaSort` admits only `[{ field, order }, ...]` — the spelling `@objectstack/spec` declares for `ObjectGridPropsSchema.sort` and the only one the fetch path still lowers. A retired string yields nothing, so it lights no arrow. The refusal is per entry: a mixed array still lights the arrows for the keys spelled in the declared form. No second diagnostic is added. The author is already told once per spelling by PR #8758's reporter at the fetch path, which quotes the offending value and prescribes the array form; a second voice here would only restore the arrow the wire cannot honour. ## What is deliberately unchanged The wire shape. The array arm still lowers to this block's own `"field order"` join string; routing the key through the shared sink's `{field: direction}` map is route B on objectui#8767, which stays declined until the protocol declares that shape. Measured while here: the server-side export path reads `schema.sort` itself rather than through `parseSchemaSort`, so it was already array-only and does not move — the retired docblock claim that narrowing this reader "takes the export path with it" was not borne out. ## Pins, both directions `serverSorting.test.tsx`: the declared array lights the arrow (the case that already existed); a retired string lights NEITHER direction while the query carries no `$orderby` and the one diagnostic still fires once. That case previously pinned the divergence — the arrow drawn beside an empty query — so the arrow half is what flips. Its non-vacuity control is the neutral sort indicator, still rendered, so "no arrow" cannot pass by the column having quietly stopped offering sorting. The unit block re-judges every spelling it used to admit, each refusal paired with a declared-array control. `gridArrayArmOrderby-8973.test.tsx`'s docblock cited this card by a label that had already moved; it now names the ruling, which does not move. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VCpmqvacV4BypY48QdoxcE
1 parent f0f4d6c commit 7f2a5f4

4 files changed

Lines changed: 179 additions & 74 deletions

File tree

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
'@object-ui/plugin-grid': patch
3+
---
4+
5+
`object-grid`'s header arrows read the ONE declared `sort` spelling — a retired
6+
string no longer paints a pre-click arrow (objectui#8961, maintainer ruling
7+
2026-09-15, letter A).
8+
9+
**What a user saw.** A view authored `sort: "name desc"` lit a descending arrow
10+
on the `name` header *before anyone clicked anything*, while the query that
11+
fetched those rows carried no ordering at all. The arrow stated something about
12+
the list that was not true of the rows beside it, and the first click on that
13+
column then asked for `asc` on a list that was in no declared order. The only
14+
signal was a `console.error` no end user reads.
15+
16+
**Why the two halves disagreed.** objectui#8221 retired the legacy string
17+
clause — one spelling, the array, everywhere — and objectui#8767 made this
18+
block's fetch path REFUSE a string `sort` and send no `$orderby`. That ruling
19+
deliberately left the other reader of the same key alone: `parseSchemaSort`,
20+
which feeds the header indicators, went on parsing `"name desc"` and
21+
`["name desc", …]`. One key, two readers, opposite answers.
22+
23+
**What changes.** `parseSchemaSort` admits only `[{ field, order }, …]` — the
24+
spelling `@objectstack/spec` declares for `ObjectGridPropsSchema.sort` and the
25+
only one the fetch path still lowers. A retired string yields nothing, so it
26+
lights no arrow, matching the query it produces. The refusal is per entry: a
27+
mixed array still shows the arrows for the keys spelled in the declared form.
28+
29+
**No second diagnostic.** The author is already told once per spelling by the
30+
shared reporter at the fetch path, which quotes the offending value and
31+
prescribes the array form. Narrowing the header reader adds no new message.
32+
33+
**Migration.** Write the array: `sort: [{ field: 'name', order: 'desc' }]` —
34+
the same edit the fetch path has required since objectui#8767. A declared entry
35+
with no `order` still reads ascending; that behaviour is unchanged.
36+
37+
**What is deliberately unchanged.** The wire shape. This block still lowers its
38+
array arm to its own `"field order"` join string; routing the key through the
39+
shared sink's `{field: direction}` map is route B on objectui#8767, which stays
40+
declined until the protocol declares that shape (`$orderby` is declared
41+
`string | string[]`). The server-side export path reads `schema.sort` itself
42+
rather than through `parseSchemaSort`, so it was already array-only and does
43+
not move.

‎packages/plugin-grid/src/ObjectGrid.tsx‎

Lines changed: 53 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -78,27 +78,6 @@ import { BulkActionDialog } from './components/BulkActionDialog';
7878
import type { BulkResult } from './hooks/useBulkExecutor';
7979
import type { BulkActionDef } from '@object-ui/types';
8080

81-
/**
82-
* A view's declared `sort` → the shape the table's header indicators read.
83-
*
84-
* `[{ field, order }, …]` is the ONE spelling `@objectstack/spec` still
85-
* declares (objectui#8221 retired the string clauses). The headers have to
86-
* agree with the fetch path on it: a view that arrives sorted by
87-
* `created_at desc` should show that arrow before anyone clicks anything —
88-
* otherwise the first click on that column produces `asc` while the list was
89-
* already `desc`, and the arrow tells the truth only from the second click on.
90-
*
91-
* ⚠️ This reader is WIDER than the fetch path as of objectui#8767, and the
92-
* sentence this docblock used to carry — that the fetch path reads all three
93-
* spellings — is no longer true. The fetch path now REFUSES a string and sends
94-
* no `$orderby` at all, while this reader still parses `"name desc"` and
95-
* `["name desc", …]`, so a grid authored with a retired spelling shows an
96-
* arrow for an ordering its query does not carry. Narrowing this reader moves
97-
* the wire shape and takes the export path with it — the route the #8767
98-
* ruling deliberately did not take. It is NOT fixed here.
99-
*
100-
* Exported for the test that pins it against the fetch path's own reading.
101-
*/
10281
/**
10382
* A declared `sort` → the `"field order"` join string THIS block sends as
10483
* `$orderby` (objectui#8973).
@@ -131,14 +110,44 @@ function toOrderByClause(sort: QuerySortEntry[] | undefined | null): string | un
131110
return ordered.map((s) => `${s.field} ${s.order}`).join(', ');
132111
}
133112

113+
/**
114+
* A view's declared `sort` → the shape the table's header indicators read.
115+
*
116+
* `[{ field, order }, …]` is the ONE spelling `@objectstack/spec` still
117+
* declares for `ObjectGridPropsSchema.sort` (objectui#8221 retired the string
118+
* clauses), and since objectui#8961 it is the only spelling this reader
119+
* admits. The headers agree with the fetch path on it: a view that arrives
120+
* sorted by `created_at desc` shows that arrow before anyone clicks anything —
121+
* otherwise the first click on that column produces `asc` while the list was
122+
* already `desc`, and the arrow tells the truth only from the second click on.
123+
*
124+
* ⭐ A retired string spelling (`"name desc"`, `["name desc", …]`) yields
125+
* NOTHING here, so it lights no arrow. That is the agreement, not an omission:
126+
* the fetch path REFUSES the same spelling and sends no `$orderby`
127+
* (objectui#8767). Between #8767 and objectui#8961 this reader was WIDER than
128+
* that path — it parsed the string and drew a confident arrow for an ordering
129+
* the query did not carry, a UI element stating something untrue about the rows
130+
* beside it, with nothing but a console line to say so.
131+
*
132+
* ⛔ Do not re-widen it for a stored `sys_metadata` row still carrying the old
133+
* spelling. The author is already told, once per spelling, by PR #8758's own
134+
* diagnostic at the fetch path — it quotes the offending value and prescribes
135+
* the array form. A second reading here would restore exactly the arrow the
136+
* wire cannot honour.
137+
*
138+
* The wire shape is NOT what moved: this block still sends its own
139+
* `"field order"` join string (see {@link toOrderByClause}), the shared sink's
140+
* `{field: direction}` map stays declined, and the server-side export path
141+
* reads `schema.sort` itself rather than through this function, so it was
142+
* already array-only and is untouched.
143+
*
144+
* Exported for the test that pins it against the fetch path's own reading.
145+
*/
134146
export function parseSchemaSort(sort: unknown): TableSortItem[] {
135-
const entries = typeof sort === 'string' ? [sort] : Array.isArray(sort) ? sort : [];
147+
const entries = Array.isArray(sort) ? sort : [];
136148
const items: TableSortItem[] = [];
137149
for (const entry of entries) {
138-
if (typeof entry === 'string') {
139-
const [field, order] = entry.trim().split(/\s+/);
140-
if (field) items.push({ field, order: order?.toLowerCase() === 'desc' ? 'desc' : 'asc' });
141-
} else if (entry && typeof entry === 'object' && typeof (entry as any).field === 'string') {
150+
if (entry && typeof entry === 'object' && typeof (entry as any).field === 'string') {
142151
const { field, order } = entry as { field: string; order?: string };
143152
items.push({ field, order: String(order).toLowerCase() === 'desc' ? 'desc' : 'asc' });
144153
}
@@ -2008,10 +2017,13 @@ export const ObjectGrid: React.FC<ObjectGridComponentProps> = ({
20082017
// spelling and answers `undefined`, so the query carries no
20092018
// `$orderby`. Its return value is deliberately unused — the wire
20102019
// shape stays this block's, and the array arm below is untouched
2011-
// (with it the export path and `parseSchemaSort`). Routing the
2012-
// whole key through the sink is a different card: it would send
2013-
// the sink's `{field: direction}` map where every grid today
2014-
// sends a `"field order"` string.
2020+
// (with it the export path). The header-arrow reader
2021+
// `parseSchemaSort` was left parsing the string HERE, and read
2022+
// this same key more widely than this refusal until objectui#8961
2023+
// narrowed it to the declared array; the two now agree. Routing
2024+
// the whole key through the sink is still a different card: it
2025+
// would send the sink's `{field: direction}` map where every grid
2026+
// today sends a `"field order"` string.
20152027
//
20162028
// Read through `unknown`, exactly as the sink does: types are
20172029
// erased, so the array-only `ObjectGridSchema.sort` declaration
@@ -4263,10 +4275,17 @@ export const ObjectGrid: React.FC<ObjectGridComponentProps> = ({
42634275
// arrow, and the first click on that column would ask for `asc` on a list
42644276
// that was already `desc`.
42654277
//
4266-
// ⚠️ One spelling now escapes that agreement: since objectui#8767 the fetch
4267-
// path REFUSES a string `sort` and sends no `$orderby`, while
4268-
// {@link parseSchemaSort} still parses one. Closing that gap narrows this
4269-
// reader and moves the wire shape with it — the route #8767 did not take.
4278+
// ⭐ That agreement now covers the SPELLING too (objectui#8961). One used to
4279+
// escape it: since objectui#8767 the fetch path REFUSES a string `sort` and
4280+
// sends no `$orderby`, while {@link parseSchemaSort} went on parsing one, so
4281+
// a grid authored `sort: 'name desc'` painted a descending arrow over rows
4282+
// the server returned in no declared order. That reader now admits only the
4283+
// declared `[{ field, order }]` array — the one spelling the fetch path
4284+
// still lowers — so the arrow on screen and the `$orderby` on the wire read
4285+
// the same key the same way, and a retired spelling lights nothing on either
4286+
// side. What did NOT move is the wire shape: the array arm still lowers to
4287+
// this block's own `"field order"` join string, and the shared sink's
4288+
// `{field: direction}` map stays declined (see {@link toOrderByClause}).
42704289
//
42714290
// A plain expression, not a `useMemo`: this sits below the component's early
42724291
// returns, where a hook would be skipped on some renders and change the hook

‎packages/plugin-grid/src/__tests__/gridArrayArmOrderby-8973.test.tsx‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -46,10 +46,20 @@
4646
*
4747
* ## Deliberately untouched
4848
*
49-
* The header-arrow reader `parseSchemaSort` (objectui#8961, `pm:blocked`) and
50-
* the export path's `{field, direction}` projection. The `headerSort` arm also
51-
* keeps sending `SortNode[]` objects rather than a join string — a documented,
52-
* deliberate difference, not a defect.
49+
* The export path's `{field, direction}` projection, and the header-arrow
50+
* reader `parseSchemaSort` — untouched BY THIS CARD. ⛔ Do not read the latter
51+
* as a standing description of that reader: objectui#8961 has since narrowed it
52+
* to the declared `[{ field, order }]` array (ruled letter A, director batch
53+
* #135 item 5), so a retired string spelling now lights no arrow either and the
54+
* two readers of this key agree. Nothing below reads the header indicators, so
55+
* this file's pins are unaffected. The `headerSort` arm also keeps sending
56+
* `SortNode[]` objects rather than a join string — a documented, deliberate
57+
* difference, not a defect.
58+
*
59+
* ⚠️ The sentence this replaces cited objectui#8961 by its LABEL
60+
* (`pm:blocked`), which had moved before anyone read the line again. A card's
61+
* label is state nothing in this file re-derives; its RULING does not move, so
62+
* that is what is named here.
5363
*
5464
* ⭐ The CONTROL rows are what make the rest a measurement rather than a block
5565
* that mangles everything: if the fix had broken lowering outright, the

‎packages/plugin-grid/src/__tests__/serverSorting.test.tsx‎

Lines changed: 69 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -178,39 +178,48 @@ describe('ObjectGrid — column-header sorting is server-side (#3106)', () => {
178178
});
179179
});
180180

181-
it('DIVERGENCE, pinned not tolerated (objectui#8961): a retired STRING sort still draws the arrow while the wire carries NO ordering', async () => {
182-
// objectui#8767 made the fetch path REFUSE a string `sort`. The header
183-
// indicators are fed by `parseSchemaSort`, a second private reader that
184-
// the ruling deliberately left alone — and it still parses a string. So
185-
// the two readers of one key now disagree, and this asserts BOTH halves of
186-
// that disagreement.
181+
it('a retired STRING sort lights NO arrow — the header reads the key exactly as the fetch path does (objectui#8961)', async () => {
182+
// Both readers of one key, in agreement. objectui#8767 made the fetch path
183+
// REFUSE a string `sort`; the header indicators are fed by
184+
// `parseSchemaSort`, a second private reader that went on parsing one, so
185+
// this very schema drew a confident `status desc` arrow over rows the
186+
// server had returned in NO declared order — and the first click on that
187+
// column then asked for `asc` on a list that was in no order at all.
187188
//
188-
// Asserting only the arrow (which is what this file did before) leaves a
189-
// green test that reads as "string sort ⇒ arrow, as intended". A green
190-
// test does not make a divergence visible; it certifies it. Naming both
191-
// halves is what makes the state a recorded defect instead of an expected
192-
// one, and makes THIS the case that has to change when objectui#8961
193-
// closes the gap — narrowing the reader moves the wire shape and takes the
194-
// export path with it, the route objectui#8767 did not take.
189+
// This case used to pin that divergence rather than tolerate it: it
190+
// asserted the arrow WAS drawn beside the empty query, so the state read
191+
// as a recorded defect instead of an expected one. The ruling on
192+
// objectui#8961 (director batch #135 item 5, letter A) closed it by
193+
// narrowing the reader to the declared array, so the ARROW half flips
194+
// here. The wire half is unchanged and stays asserted: "no arrow" is the
195+
// right answer only while the query really does carry no ordering.
195196
resetRetiredSortSpellingReports();
196197
const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
197198
try {
198199
const ds = makeDataSource();
199200
const { container } = renderGrid(ds, { sort: 'status desc' });
200201
await waitFor(() => expect(screen.getByText('Row 0')).toBeInTheDocument());
201202

202-
// Half one — the header still tells the user this list is `status desc`.
203-
expect(
204-
headerCell(container, 'Status').querySelector('[class*="chevron-down"]'),
205-
).not.toBeNull();
203+
// Half one — the header states nothing about an ordering this list does
204+
// not have. NEITHER direction, not merely "not descending".
205+
const status = headerCell(container, 'Status');
206+
expect(status.querySelector('[class*="chevron-down"]')).toBeNull();
207+
expect(status.querySelector('[class*="chevron-up"]')).toBeNull();
208+
// CONTROL, non-vacuity — the column is still sortable and still renders
209+
// its header chrome, so the two nulls above mean "no ACTIVE sort" rather
210+
// than "no icons here at all", which is how they would also pass if the
211+
// harness or the column had silently stopped offering sorting.
212+
expect(status.querySelector('[class*="chevrons-up-down"]')).not.toBeNull();
206213

207214
// Half two — and the query it was fetched with carries no ordering at
208215
// all. `hasOwnProperty`, not `toBeUndefined`: the key is absent, which is
209216
// a different claim from "present and undefined".
210217
const params = lastFindParams(ds);
211218
expect(Object.prototype.hasOwnProperty.call(params, '$orderby')).toBe(false);
212219

213-
// …and the disagreement is announced once, by PR #8758's own reporter.
220+
// …and the author is told once, by PR #8758's own reporter on the fetch
221+
// path. STILL once: narrowing the header reader deliberately did not add
222+
// a second diagnostic for the same spelling — one refusal, one voice.
214223
const retired = errorSpy.mock.calls.filter((c) =>
215224
String(c[0]).includes('objectui#8221'),
216225
);
@@ -237,34 +246,58 @@ describe('ObjectGrid — column-header sorting is server-side (#3106)', () => {
237246
});
238247

239248
/**
240-
* ⚠️ This block pins the header reader's OWN contract, which since
241-
* objectui#8767 is WIDER than the fetch path's — hence the renamed title. The
242-
* cases below still admit the retired string spellings because this reader
243-
* still admits them; the fetch path refuses them (see the divergence pin
244-
* above). Re-judging these inputs belongs to objectui#8961, which narrows this
245-
* reader and moves the wire shape with it. Until then they are read as "what
246-
* `parseSchemaSort` accepts", never as "what the grid queries with".
249+
* ⚠️ This block pins the header reader's OWN contract. Since objectui#8961
250+
* that contract is exactly as wide as the fetch path's: the declared
251+
* `[{ field, order }]` array and nothing else (objectui#8221 retired the string
252+
* clauses, objectui#8767 made the fetch path refuse them). The cases below used
253+
* to admit the retired spellings because this reader still did, and re-judging
254+
* them was named as this card's work; that is what has happened.
255+
*
256+
* These refusals are the unit-level half of the rendered pin above — the `[]`
257+
* here is what the "no arrow" there is made of.
258+
*
259+
* Non-vacuity: every refusal is paired with a CONTROL in the same shape — the
260+
* declared array must still parse, single- and multi-key. A reader that had
261+
* simply stopped returning anything would fail those controls, so `[]` is a
262+
* verdict here and not silence.
247263
*/
248-
describe('parseSchemaSort — the header reader\'s own contract, wider than the fetch path (objectui#8961)', () => {
249-
it('reads the bare-string form', () => {
250-
expect(parseSchemaSort('name desc')).toEqual([{ field: 'name', order: 'desc' }]);
264+
describe('parseSchemaSort — the header reader reads the ONE declared spelling (objectui#8961)', () => {
265+
it('REFUSES the bare-string form — no arrow, matching the `$orderby` the fetch path does not send', () => {
266+
expect(parseSchemaSort('name desc')).toEqual([]);
267+
// The one-word spelling too, not just the two-word one.
268+
expect(parseSchemaSort('name')).toEqual([]);
251269
});
252270

253-
it('defaults an omitted direction to ascending', () => {
254-
expect(parseSchemaSort('name')).toEqual([{ field: 'name', order: 'asc' }]);
255-
});
256-
257-
it('reads the array-of-strings form', () => {
258-
expect(parseSchemaSort(['status asc', 'name desc'])).toEqual([
259-
{ field: 'status', order: 'asc' },
271+
it('REFUSES string entries INSIDE an array, entry by entry', () => {
272+
expect(parseSchemaSort(['status asc', 'name desc'])).toEqual([]);
273+
// Per entry, not a whole-value veto: one retired entry cannot blank the
274+
// keys the author did spell in the declared form.
275+
expect(parseSchemaSort(['status asc', { field: 'name', order: 'desc' }])).toEqual([
260276
{ field: 'name', order: 'desc' },
261277
]);
262278
});
263279

264-
it('reads the SortNode[] form', () => {
280+
it('CONTROL — reads the declared `SortConfig[]` form, single- and multi-key', () => {
265281
expect(parseSchemaSort([{ field: 'name', order: 'desc' }])).toEqual([
266282
{ field: 'name', order: 'desc' },
267283
]);
284+
expect(
285+
parseSchemaSort([
286+
{ field: 'status', order: 'asc' },
287+
{ field: 'name', order: 'desc' },
288+
]),
289+
).toEqual([
290+
{ field: 'status', order: 'asc' },
291+
{ field: 'name', order: 'desc' },
292+
]);
293+
});
294+
295+
it('CONTROL — a declared entry with no `order` still reads ascending', () => {
296+
// Untouched by objectui#8961, and named here so the narrowing is not read
297+
// as a second, stricter judgement of the ENTRY: what moved is which
298+
// SPELLING of the key is admitted, not how a declared entry is read. This
299+
// is also the shape `defaultSort` arrives in, wrapped by the read site.
300+
expect(parseSchemaSort([{ field: 'name' }])).toEqual([{ field: 'name', order: 'asc' }]);
268301
});
269302

270303
it('yields nothing for an absent or unreadable sort', () => {

0 commit comments

Comments
 (0)