refactor(core,react,dashboard,report): the analytics label net's fetch-and-memo glue is written once (#4389)

[yinlianghui]

Fixes#4389

PR #4388 (#4330) left the same React glue on two surfaces. The resolution rules were never duplicated — both call the same @object-ui/core helpers — but the wiring around them was: read the object schema through the host's authenticated apiFetch, keep the fetched metadata locale-free in state, derive the label maps in a render memo. Two copies meant two statements of the same two bug fixes. Nothing a user hits today; retired deliberately, per the card.

Hook home, and the dependency-direction evidence

The card's title said the home is @object-ui/core. That is disproven, and the card's PM RULING #2 retires it. Measured on origin/main, two independent blockers:

1. Hard cycle.SchemaRendererContext is defined at packages/react/src/context/SchemaRendererContext.tsx:19, exported via context/index.ts then src/index.ts. packages/react/package.json declares "@object-ui/core": "workspace:*" in dependencies. So core importing it back is a cycle, not a new edge. useSafeFieldLabel is the same story: it lives in packages/i18n/src/useObjectLabel.ts:601, and @object-ui/i18n is not a core dependency either.

2. Layer violation.@object-ui/core is React-free by declaration and by content — dependencies are only @object-ui/types, @objectstack/formula, @objectstack/spec, lodash, zod; peerDependencies is empty; packages/core/src has 0 files with a .tsx extension, 0 react imports and 0 exported hooks; packages/core/node_modules has no react. AGENTS.md section 3 pins it: "No UI-lib deps. Logic only." #3367 already ruled this exact direction for this exact family (core-canonical logic, react re-exports — never core importing react).

⚠️ One trap worth recording, since it would have hidden the cycle from the obvious check: react DOES resolve from packages/core, via the root devDependencies.react symlink. A resolution-based direction check therefore returns the wrong answer here; the authoritative check is the declared dependencies. Filed separately as #4394.

So the split is A+B, as ruled — each half in the layer that can actually hold it:

Half	Package	Added
B (React-free)	@object-ui/core	loadDimensionFieldMeta, deriveDimensionLabelMaps, dimensionOptionTranslator
A (React wiring)	@object-ui/react	useDatasetDimensionMeta, useDatasetDimensionLabels

@object-ui/react is the one package downstream of core (helpers reachable), downstream of @object-ui/i18n (useSafeFieldLabel reachable), owner of SchemaRendererContext (apiFetch is a local read), and upstream of both plugins. It already hosts this exact fetch-and-memo-off-apiFetch shape three times: useViewData, useElementDataSource, useDiscovery.

Consumers

• DatasetWidget consumes useDatasetDimensionMeta and layers its chart-only colour/order derivation locally — a table renders no palette, so firstDimPath stays isTable-gated exactly as before.
• plugin-report's useDatasetDimensionLabels.ts becomes a literal one-line re-export, keeping its rationale header and its import path, so DatasetReportRenderer's three call sites are untouched.

Two exports rather than one is what lets that re-export stay literal: useDatasetDimensionLabels is the labels-only signature plugin-report already had, and useDatasetDimensionMeta is the same glue stopping one step earlier, for the surface that derives more from the metadata. The fetch-and-memo wiring itself exists once.

The two properties, now singly expressed and pinned

Both were previously written out per surface — the drift this card names:

• the read rides the host's authenticated apiFetch (DatasetWidget's option-color / dimension-label probe reads the global fetch, bypassing the host's apiFetch channel (the plugin-dashboard twin of #4114) #4121) — pinned by asserting a new channel re-issues the read, i.e. that apiFetch really is in the effect's deps. "Was apiFetch called" cannot see that half.
• the fetched metadata stays locale-free (Analytics surfaces resolve select-option labels but never apply the i18n bundle — reports and dashboards show English while lists and forms show the translation #4030 / PR fix(core,plugin-dashboard,plugin-charts): run resolved select-option labels through the i18n bundle on analytics surfaces (#4030) #4324) — pinned by switching language at runtime and asserting the labels flip in place with no second metadata read.

New pins live at the shared seam (packages/react/src/hooks/__tests__/useDatasetDimensionLabels.test.tsx, packages/core/src/utils/__tests__/chart-series.labelNetGlue.test.ts) because a plugin-level pin can only observe its own copy — which is how the duplication survived long enough to be filed.

Pins-unchanged proof (the acceptance evidence)

All 39 assertions PR #4388 landed pass unchanged, and their files are byte-identical to main:

git diff --name-only origin/main -- 'packages/plugin-dashboard/src/__tests__/*' \
'packages/plugin-report/src/__tests__/*'
(no output)

Run	Result
The 6 #4388 pin files, before any edit (baseline)	6 files, 39 passed
The same 6 files, after the refactor	6 files, 39 passed
packages/core/ packages/react/ packages/plugin-dashboard/ packages/plugin-report/	169 files, 2670 passed
Repo-wide turbo run type-check --concurrency=2	78/78 successful, 0 error TS
lint on the 4 packages	0 errors (280 pre-existing no-explicit-any warnings)
check-control-bytes	OK, 4098 files

Typecheck ran both tsc projects per package (tsc --noEmit && tsc -p tsconfig.test.json) wherever a test project exists. The repo-wide pass covers every package, so it subsumes a directional consumer sweep in both directions.

Reverse verification

RV1 — revert DatasetWidget to its local glue (git checkout origin/main -- DatasetWidget.tsx), run the dashboard pins. Predicted GREEN before running, and measured GREEN: 5 files, 32 passed. Reporting the null result honestly rather than dressing it as a catch — this refactor is behaviour-preserving by construction, so the surface pins cannot distinguish shared glue from duplicated glue. That is precisely why the new hook-level pins had to be added; the #4388 pins are evidence that nothing broke, never evidence that the glue is shared.

RV2 — break the locale-free property in a scratch commit (put the locale-derived fieldOptionLabel into the fetch effect's deps, the pre-#4324 defect). Predicted RED on the read-count assertion; measured RED, and harder than predicted: all 4 hook pins go red, because that value's identity is unstable across renders, so the effect does not refetch once per language switch — it refetches unboundedly. Observed 287, 436 and 2 extra reads where 1 was expected. Restored; pins green again.

Scope

Surface: packages/core, packages/react (the new hook plus its barrel line, nothing else), packages/plugin-dashboard, packages/plugin-report, changeset. Changeset is patch across the 4 packages, never major. Merged origin/main (#4383 landed mid-task, different surface) with no conflicts, and re-ran the full suite after the merge — same 2670 passed.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectui	Ignored		Aug 12, 2026 2:51am

[github-actions]

✅ Console Performance Budget

Metric	Value	Budget
Main entry (gzip)	24.7 KB	350 KB
Entry file	index-jlTnASYb.js	—
Status	PASS	—

---

📦 Bundle Size Report

Package	Size	Gzipped
app-shell (index.js)	9.56KB	3.59KB
app-shell (runtime-config.js)	7.42KB	2.32KB
app-shell (types.js)	0.01KB	0.04KB
app-shell (urlParams.js)	8.92KB	3.41KB
auth (AuthContext.js)	0.31KB	0.24KB
auth (AuthGuard.js)	1.17KB	0.53KB
auth (AuthProvider.js)	22.10KB	4.37KB
auth (AuthShell.js)	3.49KB	1.40KB
auth (ForgotPasswordForm.js)	12.21KB	3.45KB
auth (LoginForm.js)	18.13KB	5.39KB
auth (PreviewBanner.js)	0.90KB	0.50KB
auth (RegisterForm.js)	6.64KB	2.21KB
auth (SocialSignInButtons.js)	9.60KB	3.89KB
auth (UserMenu.js)	3.40KB	1.22KB
auth (auth-gate-events.js)	1.29KB	0.66KB
auth (authStyles.js)	5.04KB	1.72KB
auth (createAuthClient.js)	35.76KB	9.11KB
auth (createAuthenticatedFetch.js)	4.37KB	1.69KB
auth (index.js)	2.35KB	1.07KB
auth (org-roles.js)	6.66KB	2.78KB
auth (phone-identifier.js)	1.11KB	0.66KB
auth (types.js)	0.59KB	0.35KB
auth (useAuth.js)	4.91KB	0.87KB
auth (useIsWorkspaceAdmin.js)	1.61KB	0.85KB
collaboration (CommentThread.js)	26.07KB	7.56KB
collaboration (LiveCursors.js)	3.17KB	1.27KB
collaboration (PresenceAvatars.js)	6.49KB	2.64KB
collaboration (PresenceProvider.js)	2.79KB	1.13KB
collaboration (index.js)	1.65KB	0.73KB
collaboration (useCollaborationTranslation.js)	6.05KB	2.52KB
collaboration (useCommentSearch.js)	1.98KB	0.88KB
collaboration (useConflictResolution.js)	7.75KB	1.86KB
collaboration (useMentionNotifications.js)	1.81KB	0.68KB
collaboration (usePresence.js)	6.33KB	1.84KB
collaboration (useRealtimeSubscription.js)	7.91KB	2.01KB
components (index.js)	489.20KB	108.43KB
core (index.js)	2.99KB	1.14KB
create-plugin (index.js)	10.08KB	3.26KB
data-objectstack (index.js)	153.42KB	41.19KB
fields (index.js)	228.36KB	56.61KB
i18n (LocalizationContext.js)	1.76KB	0.96KB
i18n (currency.js)	1.22KB	0.64KB
i18n (i18n.js)	4.32KB	1.77KB
i18n (index.js)	3.35KB	1.38KB
i18n (pickLocalized.js)	3.69KB	1.73KB
i18n (provider.js)	23.12KB	7.62KB
i18n (useDisplayLocale.js)	2.33KB	1.20KB
i18n (useObjectLabel.js)	27.59KB	6.63KB
i18n (useSafeTranslation.js)	7.77KB	3.13KB
layout (index.js)	38.98KB	10.85KB
mobile (MobileProvider.js)	0.92KB	0.49KB
mobile (ResponsiveContainer.js)	0.94KB	0.38KB
mobile (breakpoints.js)	1.51KB	0.70KB
mobile (createOfflineDataSource.js)	5.61KB	1.74KB
mobile (index.js)	1.50KB	0.62KB
mobile (offlineQueue.js)	3.91KB	1.35KB
mobile (pwa.js)	0.97KB	0.49KB
mobile (serviceWorker.js)	1.48KB	0.62KB
mobile (serviceWorkerSource.js)	3.41KB	1.48KB
mobile (useBreakpoint.js)	1.54KB	0.65KB
mobile (useGesture.js)	6.96KB	1.98KB
mobile (useOfflineSync.js)	1.99KB	0.72KB
mobile (usePullToRefresh.js)	2.53KB	0.85KB
mobile (useResponsive.js)	0.71KB	0.42KB
mobile (useResponsiveConfig.js)	1.36KB	0.63KB
mobile (useSpecGesture.js)	4.32KB	1.64KB
mobile (useTouchTarget.js)	1.01KB	0.54KB
permissions (MePermissionsProvider.js)	8.75KB	3.06KB
permissions (PermissionContext.js)	0.31KB	0.25KB
permissions (PermissionGuard.js)	0.89KB	0.45KB
permissions (PermissionProvider.js)	3.67KB	1.12KB
permissions (evaluator.js)	4.41KB	1.44KB
permissions (index.js)	0.91KB	0.41KB
permissions (store.js)	0.91KB	0.42KB
permissions (useFieldPermissions.js)	1.28KB	0.52KB
permissions (usePermissions.js)	1.55KB	0.71KB
plugin-ai (index.js)	15.71KB	3.79KB
plugin-calendar (index.js)	45.23KB	12.45KB
plugin-charts (index.js)	62.18KB	17.67KB
plugin-chatbot (index.js)	180.33KB	42.79KB
plugin-dashboard (index.js)	120.57KB	31.32KB
plugin-designer (index.js)	210.91KB	42.67KB
plugin-detail (index.js)	239.00KB	59.76KB
plugin-editor (index.js)	2.46KB	1.10KB
plugin-form (index.js)	114.58KB	27.68KB
plugin-gantt (index.js)	164.14KB	39.98KB
plugin-grid (index.js)	187.99KB	49.92KB
plugin-kanban (index.js)	48.60KB	13.41KB
plugin-list (index.js)	110.12KB	26.74KB
plugin-map (index.js)	18.05KB	5.80KB
plugin-markdown (index.js)	13.72KB	4.69KB
plugin-report (index.js)	40.99KB	10.74KB
plugin-timeline (index.js)	26.21KB	7.52KB
plugin-tree (index.js)	8.50KB	2.88KB
plugin-view (index.js)	84.03KB	20.55KB
providers (DataSourceProvider.js)	0.75KB	0.39KB
providers (MetadataProvider.js)	1.37KB	0.59KB
providers (ThemeProvider.js)	1.90KB	0.85KB
providers (UploadProvider.js)	11.71KB	3.53KB
providers (index.js)	0.44KB	0.22KB
providers (types.js)	0.01KB	0.04KB
react-runtime (index.js)	5.67KB	2.37KB
react (LazyPluginLoader.js)	3.77KB	1.33KB
react (SchemaRenderer.js)	23.71KB	7.96KB
react (data-invalidation.js)	5.05KB	2.08KB
react (index.js)	1.23KB	0.66KB
react (spec-input.js)	0.20KB	0.18KB
sdui-parser (codegen.js)	4.09KB	1.74KB
sdui-parser (index.js)	4.47KB	2.03KB
sdui-parser (parse.js)	10.04KB	2.82KB
sdui-parser (types.js)	0.29KB	0.24KB
sdui-parser (validate.js)	4.69KB	1.48KB
types (ai.js)	0.20KB	0.17KB
types (api-types.js)	0.20KB	0.18KB
types (app.js)	2.87KB	0.99KB
types (base.js)	0.20KB	0.18KB
types (blocks.js)	0.20KB	0.18KB
types (complex.js)	0.20KB	0.18KB
types (crud.js)	0.20KB	0.18KB
types (dashboard-filter-alias.js)	6.23KB	2.74KB
types (data-display.js)	0.20KB	0.18KB
types (data-protocol.js)	0.20KB	0.19KB
types (data.js)	0.20KB	0.18KB
types (designer.js)	1.87KB	0.85KB
types (disclosure.js)	0.20KB	0.18KB
types (error-code.js)	1.54KB	0.88KB
types (feedback.js)	0.20KB	0.18KB
types (field-types.js)	0.20KB	0.18KB
types (form.js)	0.20KB	0.18KB
types (http-retry.js)	4.32KB	2.02KB
types (index.js)	3.05KB	1.52KB
types (layout.js)	0.20KB	0.18KB
types (managed-by.js)	0.19KB	0.18KB
types (mobile.js)	2.59KB	1.31KB
types (navigation.js)	0.20KB	0.18KB
types (objectql.js)	0.20KB	0.18KB
types (overlay.js)	0.20KB	0.18KB
types (permissions.js)	0.20KB	0.18KB
types (plugin-scope.js)	0.20KB	0.18KB
types (record-components.js)	0.20KB	0.19KB
types (record-semantics.js)	1.28KB	0.67KB
types (registry.js)	0.20KB	0.18KB
types (reports.js)	0.20KB	0.18KB
types (spec-report.js)	5.05KB	1.93KB
types (system-fields.js)	3.33KB	1.54KB
types (theme.js)	0.20KB	0.18KB
types (ui-action.js)	3.40KB	1.71KB
types (views.js)	0.20KB	0.18KB
types (widget.js)	0.20KB	0.18KB

Size Limits

• ✅ Core packages should be < 50KB gzipped
• ✅ Component packages should be < 100KB gzipped
• ⚠️ Plugin packages should be < 150KB gzipped

[yinlianghui]

ACCEPT — PM 复核 (session session_017Qqyix2QcnpUC9XeYVDzx3), closes #4389.

• A+B as re-ruled, with the two-export design note accepted as within the ruling: the duplicated wiring exists exactly once; useDatasetDimensionMeta is a 3-line-composition stop-early variant that lets DatasetWidget keep its chart-only derivation local and plugin-report stay a literal re-export with its rationale header — both properties the ruling asked for.
• The pins-unchanged proof is the acceptance evidence done properly: 39/39 on both sides with the pin files untouched by diff, PLUS the honest RV1 null result stating what those pins can never prove (surface pins cannot see WHERE glue lives) — which is the recorded argument for the 14 new seam-level pins.
• RV2's measurement beat its prediction (unbounded refetch, not +1 — the locale-identity instability) and was recorded as measured; the two self-corrected assertions now document buildDimensionLabelMap's real pre-Analytics surfaces resolve select-option labels but never apply the i18n bundle — reports and dashboards show English while lists and forms show the translation #4030 semantics rather than forcing the helper. The qualifying-key bundle trap note is valuable method capture.
• Risks accepted as named: react's remit widening was the ruling's explicit cost on precedent evidence; the additive exports are permanent contract and the naming is flagged for reviewer attention; the effect-deps change is a strict improvement with read-count pins green.
• Analytics label net: ObjectChart is a THIRD copy of the derivation glue — it can consume the core helpers #4389 extracted #4405 (the third glue copy in ObjectChart — drift reduced 3→2, not eliminated) is triaged next.

Flipping ready + arming auto-merge.

---

Generated by Claude Code