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

Commit cecd6a0

Browse files
fix(app-shell): the report and dashboard-widget pickers show a dataset member's label and the dataset's description (objectui#11161) (#11171)
Fixes #11161 Clause-②: no ## What an author now sees The report inspector and the dashboard-widget inspector show the text a dataset declares, beside the machine names. This is the objectui sub-issue of objectstack-ai/objectstack#20282, as the triage ruled it (comment 5903169797). - **Measure and dimension options show the member's `label`.** The add-member lists in both inspectors read `Revenue · sum` with `revenue` in the code chip beside it, and `Stage` beside `stage`. The report's chart-axis selects read `Stage (stage)` and `Revenue (revenue) · sum`. The dashboard's filter-binding field picker shows `stage`, then `Stage`. - **Dataset options show the dataset's `description`.** The report's dataset select reads `Sales pipeline (sales_pipeline) — Open deals by stage`. The dashboard's searchable dataset picker shows the description as the option's muted hint. - **Nothing declared, nothing changes.** A member with no label reads `deal_count · count` or `region`, and a dataset with no description reads `Bare metrics (bare_metrics)`, exactly as before. - **A map-valued label resolves in the designer's language.** `{ en, zh-CN }` labels and descriptions read their `en` entry under English and their `zh-CN` entry under Chinese. A language switch re-reads them without refetching the catalog. - **What a pick stores is unchanged.** Every option's value is the machine name. The label never reaches `report.values`, `rows`, `columns`, the chart axes, `dataset`, or the widget's `dimensions`, `values` and `dataset`. - **No `/analytics/meta` reader, no authored cubes**, per the triage. ## Where it landed All in `packages/app-shell/src/views/metadata-admin/`, the claimed surface. `_shared.tsx` is untouched: its select renders each option's `label` as given, so the report's dataset options carry the description in their label text. - `previews/useDatasetCatalog.ts` - `toCatalogEntry(doc, locale)` keeps each member's `label`, the dataset's `description` and the dataset `label`. It resolves all four through the spec's `resolveI18nLabel` in `locale`. A blank or non-text value reads as undeclared. There is no `String()` of a label. - The hand-rolled `resolveLabel` is gone. It read a string or a `{ default }` object only. The spec resolver reads the untagged `default` entry itself, so that spelling still resolves (pinned). - `useDatasetCatalog` and `useDatasetSemantics` keep the documents as served. They resolve where they return, in `useMetadataLocale()`. - The entry's new fields are `description?` on the dataset and `label?` on each member. All of them are optional strings, so the `datasetCatalogOverride` contract is unchanged. - `inspectors/ReportDefaultInspector.tsx` - `datasetMeasureOptions`, `datasetDimensionOptions` and `datasetPickerOptions` live next to `DatasetNamesEditor`, which the widget inspector already imports from here. They are the one form both inspectors build their options from. - The chart-axis options use the same `LABEL (name)` text the dataset picker has always used. - `inspectors/DashboardWidgetInspector.tsx`: its dataset, dimension, measure and filter-field options come from those builders. ## The mechanism readings the order asked for 1. **What the old reader did with a map label.** Measured, not read: the base `useDatasetCatalog.ts` was put under the new pin. For `label: { en: 'Sales pipeline', zh-CN: '销售管道' }` it answered `sales_pipeline`, the machine name. So a map-valued dataset label never reached the picker. That case is folded into the spec resolver, and no second resolver remains. 2. **Where the locale enters: as a required `toCatalogEntry` parameter.** The hooks supply `useMetadataLocale()`. Four reasons: - A catalog entry leaves the one seam as display-ready strings. No consumer can render a raw locale map, which reads `[object Object]` in a template literal and throws as a React child. - The `datasetCatalogOverride` type stays string-typed. - The pure function stays unit-pinnable in both languages. - A language switch re-reads the text without a refetch. That is the pattern `useDatasetSemantics` already follows for its not-found sentence (objectui#10862). Both hosts pass `useMetadataLocale()` as the inspectors' `locale` prop (`ResourceEditPage`, `ReportConfigPanel`), so the options and the rest of the inspector read in one language. 3. **Does `useDatasetSemantics` read the same entry?** - When the list carried the members, it reads the same catalog entry. - When the list carried a summary, it hydrates once with `get('dataset', name)`. - Both paths now go through `toCatalogEntry` in the designer locale. The new pins cover both: the report's list answers full documents, and the dashboard's list answers summaries, so its members come through `get`. 4. **Existing pins.** `git grep` for `useDatasetCatalog`, `toCatalogEntry` and `DatasetMeasureInfo` over test sources finds: - three report test files that type their override fixtures as `DatasetCatalogEntry`; - `DashboardWidgetInspector.test.tsx`, which mocks the module's two hooks. No expected option text moved, because none of those fixtures declares a member label or a description: `deal_count · count` and `Sales metrics (sales_metrics)` read as before. `ReportDefaultInspector.joinedClearsBinding-10746.test.tsx`, which PR objectui#11086 edits, is untouched. ## Verification (all at `d5dc4a99d`, the head of this branch) - **New pins** (`useDatasetCatalog.authorText-11161.test.ts`, `datasetPickers.authorText-11161.test.tsx`): `Test Files 2 passed (2)`, `Tests 24 passed (24)`. - **The order's test gate**: `pnpm exec vitest run` over `inspectors/` and `previews/`, plus `ReportConfigPanel.panelTitle.test.tsx` and `ResourceEditPage.servedDraftTakenAsIs-10765.test.tsx`, the two other suites that mount these inspectors. Result: `Test Files 201 passed (201)`, `Tests 2733 passed | 1 skipped (2734)`. - **Type-check**: `pnpm --filter @object-ui/app-shell type-check` exits 0. The script echoes `tsc --noEmit && tsc -p tsconfig.test.json`. It ran after `turbo run build --filter='@object-ui/app-shell^...' --concurrency=2`, which reported `28 successful, 28 total`. `tsc -p tsconfig.test.json --listFilesOnly` lists both new test files among its 4782 program files. - **ESLint** on the five changed source and test files: 0 errors. The warnings delta against the base, per file: - `ReportDefaultInspector.tsx`: +3 `react-refresh/only-export-components`, one per exported builder. They are warn level, and exported helpers beside components are the tree's existing pattern (`FlowReferenceField.tsx`, `DatasetDefaultInspector.tsx`). - `useDatasetCatalog.ts` and `DashboardWidgetInspector.tsx`: unchanged. - **Other gates, each exit 0**: - `node scripts/check-changeset-presence.mjs`: 1 released package, 1 changeset. - `check:control-bytes`. - `check:new-line-citations`: `0 new citation(s)`. - `check:vi-mock-specifiers`, `check:vi-mock-inherit`, `check:vi-mock-override-shape`, `check:test-path-roots`. - `check:changeset-claims`, `check:pending-changeset-literals`. - `check:phantom-deps`, `check:self-import`, and `check:esm-specifiers` (its specifiers-only leg). **Ablations.** Both ran from the committed head. Each restore was proven by `blob == HEAD` and an empty `git diff HEAD`. - **The base catalog file restored in place.** The on-disk blob equalled the base blob. Result: `Tests 20 failed | 4 passed (24)`. The four green cases are the ones the base already satisfied: the names and type keys, the dataset-label fallback, the `{ default }` spelling, and a nameless document. - **The measure option's stored `name` set to its label** (through `ablation-replace.mjs`, anchor hit x1 to x0). Result: `Tests 6 failed | 18 passed (24)`. Both "a pick stores the machine name" pins went red, with `values` receiving `Revenue` instead of `revenue`, and so did the four measure-option pins whose name chip read the label. **Not measured here, left to CI:** the full `pnpm test` and lint farm, and a browser pass. No live console was driven. ## Acceptance notes These are observations and are not filed. - **Picked rows still show the stored name.** `DatasetNamesEditor`'s rows (the values and rows already bound) show the machine name, not the label. The triage scoped this card to the options, so the rows are left as they were. - **The report's dataset select shows the description in its trigger too.** A Radix select mirrors the chosen item's text into its trigger, so the trigger reads `LABEL (name) — description`, clamped to one line by the trigger's own style. Avoiding that needs a secondary-text slot in `InspectorSelectField` (`_shared.tsx`), which this card did not need. - **Long descriptions wrap on the right in the dashboard picker.** `InspectorComboField`'s `hint` suffix has no truncation, so a long description wraps there. - **A measure's `format` is still dropped by `toCatalogEntry`.** The card named it, and the triage's direction did not ask for it. - **`plugin-dashboard`'s `WidgetConfigPanel` is untouched.** It keeps its own catalog type, which already has an optional member `label`, and no in-repo host passes it a catalog. --- _Generated by [Claude Code](https://claude.ai/code/session_011p7ikEivgXefNDaE5S5Uec)_ Co-authored-by: Claude <noreply@anthropic.com>
1 parent 33da643 commit cecd6a0

6 files changed

Lines changed: 667 additions & 60 deletions

File tree

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
'@object-ui/app-shell': patch
3+
---
4+
5+
fix(app-shell): the report and dashboard-widget pickers show a dataset member's label and the dataset's description
6+
7+
The report inspector and the dashboard-widget inspector now show the text a
8+
dataset declares for its author, beside the machine names. Each measure and
9+
dimension option shows the member's `label`, and each dataset option shows the
10+
dataset's `description`. Before, every measure and dimension option showed the
11+
bare name, and no picker showed a description.
12+
13+
The form is the same in both inspectors: the author's label, then the machine
14+
name. The add-member lists show the label with the name in a code chip beside
15+
it (`Revenue · sum` beside `revenue`). The report's chart-axis selects write
16+
`Revenue (revenue) · sum`, the form the dataset picker already used. The
17+
dashboard's filter-field picker shows the name, then the label. A measure keeps
18+
its ` · aggregate` hint where it showed before. A dataset option adds its
19+
description after ` — ` in the report's select, and as the muted hint in the
20+
dashboard's searchable picker. Where the dataset declares no label or
21+
description, each option reads as it did before.
22+
23+
The label, the description and the dataset label are `I18nLabel`. They resolve
24+
through the spec's `resolveI18nLabel` in the designer's language, so an inline
25+
per-locale map shows its entry for that language. Before, a map-valued dataset
26+
label showed the machine name instead. A language switch re-reads the text
27+
without refetching the catalog. The text is display only. What a pick stores
28+
(`report.values`, `rows`, `columns`, `chart` axes, `dataset`, and the widget's
29+
`dimensions`, `values` and `dataset`) is still the machine name.

‎packages/app-shell/src/views/metadata-admin/inspectors/DashboardWidgetInspector.tsx‎

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,12 @@ import { resolveI18nLabel as resolveInlineI18nLabel } from '@objectstack/spec/ui
4040
import { setLocalized } from '@object-ui/i18n';
4141
import { InspectorCheckboxField, InspectorReorderButtons, moveArray } from './_shared.js';
4242
import { InspectorComboField, type InspectorComboOption } from './InspectorComboField.js';
43-
import { DatasetNamesEditor } from './ReportDefaultInspector.js';
43+
import {
44+
DatasetNamesEditor,
45+
datasetDimensionOptions,
46+
datasetMeasureOptions,
47+
datasetPickerOptions,
48+
} from './ReportDefaultInspector.js';
4449
import { useDatasetCatalog, useDatasetSemantics } from '../previews/useDatasetCatalog.js';
4550
import type { ObjectFieldInfo } from '../previews/useObjectFields.js';
4651

@@ -130,29 +135,31 @@ export function DashboardWidgetInspector({
130135
const catalog = useDatasetCatalog();
131136
const semantics = useDatasetSemantics(datasetName || undefined, catalog);
132137

138+
// objectui#11161 — the options read the author's text in the one form the
139+
// Report inspector's pickers share (see `datasetPickerOptions` and its
140+
// siblings): a dataset's declared `description` rides as the combo's muted
141+
// `hint`, a member's `label` beside its name. The stored value is the name.
133142
const datasetComboOptions: InspectorComboOption[] = React.useMemo(() => {
134-
const opts = catalog.datasets.map((d) => ({
135-
value: d.name,
136-
label: d.label && d.label !== d.name ? `${d.label} (${d.name})` : d.name,
137-
}));
143+
const opts: InspectorComboOption[] = datasetPickerOptions(catalog.datasets);
138144
if (datasetName && !opts.some((o) => o.value === datasetName)) {
139145
opts.push({ value: datasetName, label: datasetName });
140146
}
141147
return opts;
142148
}, [catalog.datasets, datasetName]);
143149
const measureOptions: ObjectFieldInfo[] = React.useMemo(
144-
() => semantics.measures.map((m) => ({ name: m.name, label: m.aggregate ? `${m.name} · ${m.aggregate}` : m.name, type: 'number', hidden: false })),
150+
() => datasetMeasureOptions(semantics.measures),
145151
[semantics.measures],
146152
);
147153
const dimensionOptions: ObjectFieldInfo[] = React.useMemo(
148-
() => semantics.dimensions.map((d) => ({ name: d.name, label: d.name, type: d.type ?? 'text', hidden: false })),
154+
() => datasetDimensionOptions(semantics.dimensions),
149155
[semantics.dimensions],
150156
);
151157
// Filter-binding field picker options come from the bound dataset's
152158
// dimensions (the fields a widget filter can target), replacing the removed
153-
// object-field source.
159+
// object-field source. The combo prints the value (the dimension name)
160+
// itself, so the label is the author's text alone.
154161
const fieldComboOptions: InspectorComboOption[] = React.useMemo(
155-
() => semantics.dimensions.map((d) => ({ value: d.name, label: d.name, hint: d.type })),
162+
() => semantics.dimensions.map((d) => ({ value: d.name, label: d.label ?? d.name, hint: d.type })),
156163
[semantics.dimensions],
157164
);
158165

‎packages/app-shell/src/views/metadata-admin/inspectors/ReportDefaultInspector.tsx‎

Lines changed: 85 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,8 @@ import {
4848
useDatasetCatalog,
4949
useDatasetSemantics,
5050
type DatasetCatalogEntry,
51+
type DatasetDimensionInfo,
52+
type DatasetMeasureInfo,
5153
} from '../previews/useDatasetCatalog.js';
5254
import { getReportForm, getReportSchema } from '../report-schema.js';
5355
import { mergeServerFields } from '../mergeServerFields.js';
@@ -150,6 +152,71 @@ function readNames(value: unknown): string[] {
150152
return Array.isArray(value) ? value.filter((v): v is string => typeof v === 'string') : [];
151153
}
152154

155+
/*
156+
* ── The author's text in the dataset pickers (objectui#11161) ─────────────────
157+
*
158+
* The catalog carries each member's `label` and the dataset's `description`,
159+
* already resolved in the designer locale (`useDatasetCatalog`). Every option
160+
* list both dataset inspectors render reads them in ONE form: the author's
161+
* label beside the machine name, the name alone when no label is declared, and
162+
* a measure's ` · aggregate` hint where it has always shown. Each primitive
163+
* places the name its own way:
164+
*
165+
* • the add-member list (`AddFieldPopover`) prints an option's `name` in a
166+
* code chip beside its `label` whenever the two differ, so the label there
167+
* is the author's text alone — `Revenue · sum` beside `revenue`;
168+
* • a slot that renders text only (a select item) writes `LABEL (name)`, the
169+
* form the dataset picker has always used — `Revenue (revenue) · sum`;
170+
* • `InspectorComboField` prints each option's value itself, so a member
171+
* option there carries the author's text alone.
172+
*
173+
* The dataset's `description` rides as the option's `hint`, the slot name
174+
* `InspectorComboField` renders as a muted suffix; a text-only item appends it
175+
* after ` — ` (the objectui#11028 form). An option's VALUE is always the
176+
* machine name — the label never reaches what a binding stores.
177+
*/
178+
179+
/** `LABEL (name)`, or the bare name when no label is declared or it repeats the name. */
180+
function labelBesideName(name: string, label: string | undefined): string {
181+
return label && label !== name ? `${label} (${name})` : name;
182+
}
183+
184+
/** A measure's aggregate hint, appended where the options have always shown it. */
185+
function withAggregate(text: string, aggregate: string | undefined): string {
186+
return aggregate ? `${text} · ${aggregate}` : text;
187+
}
188+
189+
/** The bound dataset's measures as add-member options (the name rides in `name`). */
190+
export function datasetMeasureOptions(measures: DatasetMeasureInfo[]): ObjectFieldInfo[] {
191+
return measures.map((m) => ({
192+
name: m.name,
193+
label: withAggregate(m.label ?? m.name, m.aggregate),
194+
type: 'number',
195+
hidden: false,
196+
}));
197+
}
198+
199+
/** The bound dataset's dimensions as add-member options (the name rides in `name`). */
200+
export function datasetDimensionOptions(dimensions: DatasetDimensionInfo[]): ObjectFieldInfo[] {
201+
return dimensions.map((d) => ({
202+
name: d.name,
203+
label: d.label ?? d.name,
204+
type: d.type ?? 'text',
205+
hidden: false,
206+
}));
207+
}
208+
209+
/** The catalog as dataset-picker options: `LABEL (name)`, the description as `hint`. */
210+
export function datasetPickerOptions(
211+
datasets: DatasetCatalogEntry[],
212+
): Array<{ value: string; label: string; hint?: string }> {
213+
return datasets.map((d) => ({
214+
value: d.name,
215+
label: labelBesideName(d.name, d.label),
216+
...(d.description ? { hint: d.description } : {}),
217+
}));
218+
}
219+
153220
/**
154221
* A reorderable list of dataset member names (the report's `values` or
155222
* `rows`) with an add-popover fed by the bound dataset's catalog. Exported so
@@ -291,33 +358,24 @@ export function ReportDefaultInspector({
291358
// "stored" and "offered" indistinguishable on screen, trading a display
292359
// defect for a semantic one. `InspectorSelectField` now synthesises the row
293360
// AND flags it; the catalog is all this list owes.
361+
//
362+
// objectui#11161 — a select item renders text only, so a declared
363+
// description follows the label after ` — `.
294364
const datasetOptions = React.useMemo(
295365
() =>
296-
catalog.datasets.map((d) => ({
297-
value: d.name,
298-
label: d.label && d.label !== d.name ? `${d.label} (${d.name})` : d.name,
366+
datasetPickerOptions(catalog.datasets).map((o) => ({
367+
value: o.value,
368+
label: o.hint ? `${o.label} — ${o.hint}` : o.label,
299369
})),
300370
[catalog.datasets],
301371
);
302372

303373
const measureOptions: ObjectFieldInfo[] = React.useMemo(
304-
() =>
305-
semantics.measures.map((m) => ({
306-
name: m.name,
307-
label: m.aggregate ? `${m.name} · ${m.aggregate}` : m.name,
308-
type: 'number',
309-
hidden: false,
310-
})),
374+
() => datasetMeasureOptions(semantics.measures),
311375
[semantics.measures],
312376
);
313377
const dimensionOptions: ObjectFieldInfo[] = React.useMemo(
314-
() =>
315-
semantics.dimensions.map((d) => ({
316-
name: d.name,
317-
label: d.name,
318-
type: d.type ?? 'text',
319-
hidden: false,
320-
})),
378+
() => datasetDimensionOptions(semantics.dimensions),
321379
[semantics.dimensions],
322380
);
323381

@@ -341,13 +399,19 @@ export function ReportDefaultInspector({
341399
// Both axis rosters used to append an out-of-catalog axis unflagged
342400
// (objectui#8488): visible, but indistinguishable from a dimension the
343401
// dataset actually offers. The flag is `InspectorSelectField`'s job now.
402+
// objectui#11161 — a select item renders text only, so each axis reads
403+
// `LABEL (name)`; the stored axis is the name.
344404
const chartXOptions = React.useMemo(
345-
() => dimensionOptions.map((d) => ({ value: d.name, label: d.label || d.name })),
346-
[dimensionOptions],
405+
() => semantics.dimensions.map((d) => ({ value: d.name, label: labelBesideName(d.name, d.label) })),
406+
[semantics.dimensions],
347407
);
348408
const chartYOptions = React.useMemo(
349-
() => measureOptions.map((m) => ({ value: m.name, label: m.label || m.name })),
350-
[measureOptions],
409+
() =>
410+
semantics.measures.map((m) => ({
411+
value: m.name,
412+
label: withAggregate(labelBesideName(m.name, m.label), m.aggregate),
413+
})),
414+
[semantics.measures],
351415
);
352416

353417
// A `joined` report carries its data on dataset-bound `blocks` (edited via

0 commit comments

Comments
 (0)