feat(dashboard-filters): #2578 follow-ups — catalog examples, guide tutorial, i18n entries, spec-alignment cleanup

[os-zhuang]

Summary

Follow-ups to the dashboard-level filters feature (#2576, framework#2501), tracked in #2578 — this PR covers the schema-catalog examples (item 1), the docs + i18n work (item 2), and the objectui side of the spec pairing (item 3, paired with objectstack-ai/framework#3035 on the same branch name).

Changes

Schema-catalog examples (issue item 1) — five new plugin-dashboard examples, registered in the catalog index:

• filtered-dashboard-dynamic-options — optionsFrom select filter fetching distinct values from object records, with a cross-object filterBindings re-target.
• filtered-dashboard-filter-types — text ($contains), number (equality) and lookup (optionsFrom) filters, plus a metric opted out of all three.
• filtered-dashboard-dataset-widgets — dataset-bound widgets (dataset + values, scoped via the dataset query's runtimeFilter) mixed with inline object widgets under one dateRange + region filter.
• filtered-dashboard-target-widgets — legacy targetWidgets allow-list semantics, including an explicit filterBindings entry winning over the allow-list.
• filtered-dashboard-date-presets — defaultRange + allowCustomRange, a per-widget date-field override, and a dateRange: false opt-out.

Docs (issue item 2) — new guide page content/docs/guide/dashboard-filters.md (registered in guide/meta.json, cross-linked from plugin-dashboard.mdx):

• full tutorial from zero: dateRange → globalFilters → filterBindings, with the binding precedence rules;
• filter-type → generated-condition table and the date-macro preset behaviour;
• page.<name> expression usage in widgets (value display, conditional visibility, page.dateRange object shape);
• known limitations with workarounds: nested Page variables shadowing (inner provider wins), static-data (inline data) widgets not filtered, default bindings hitting non-existent fields → filterBindings override or false opt-out.

i18n (issue item 2) — dashboard.filters.* entries for en and zh (bar label, "All time", "Custom…", "All", "Reset", and the 13 date-range preset labels). The filter bar previously always rendered the useSafeTranslate English fallbacks.

Spec pairing cleanup (issue item 3) — GlobalFilterSchema.name and DashboardWidgetSchema.filterBindings land in @objectstack/spec via framework#3035, so the "Pending alignment" JSDoc in packages/types flips to "Aligned" (no shape changes). The metadata-admin inspector (dashboard-schema.ts) derives its form from the spec schema, so the new properties appear there automatically once the @objectstack/spec dependency is bumped to a release containing them.

Not in this PR (still open in #2578)

• Interactive console/app-shell showcase with real dataSource + invoices/accounts seed data (item 1, last two bullets).
• Screenshots for the guide page (needs the interactive showcase above).
• Studio widget-inspector visual filterBindings editor (item 4).
• Low-priority enhancements (item 5): server-side distinct for optionsFrom, metadata-aware default-binding skip, nested Page variables context merging.

Testing

• pnpm --filter @object-ui/types build — clean.
• pnpm --filter @object-ui/i18n build && test — 10 files / 86 tests passing.
• pnpm --filter @object-ui/example-schema-catalog build && test — 848 tests passing (includes per-example validation of the five new JSON schemas).
• node scripts/check-doc-links.mjs — no new broken links (the one reported enhanced-actions.mdx link pre-exists on main).
• node scripts/check-changeset-fixed.mjs — clean.

Refs #2578, #2576, framework#2501

🤖 Generated with Claude Code

https://claude.ai/code/session_01HG5LQnPbQbjAAyofghzz3Z

---

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		Jul 16, 2026 8:11am

[github-actions]

✅ Console Performance Budget

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

---

📦 Bundle Size Report

Package	Size	Gzipped
app-shell (index.js)	8.17KB	2.95KB
app-shell (runtime-config.js)	7.42KB	2.32KB
app-shell (types.js)	0.01KB	0.04KB
app-shell (urlParams.js)	7.57KB	2.97KB
auth (AuthContext.js)	0.31KB	0.24KB
auth (AuthGuard.js)	1.17KB	0.53KB
auth (AuthProvider.js)	21.70KB	4.21KB
auth (AuthShell.js)	3.49KB	1.40KB
auth (ForgotPasswordForm.js)	12.12KB	3.41KB
auth (LoginForm.js)	17.12KB	5.00KB
auth (PreviewBanner.js)	0.90KB	0.50KB
auth (RegisterForm.js)	6.63KB	2.15KB
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)	30.17KB	7.28KB
auth (createAuthenticatedFetch.js)	3.93KB	1.55KB
auth (index.js)	1.83KB	0.79KB
auth (phone-identifier.js)	1.11KB	0.66KB
auth (types.js)	0.59KB	0.35KB
auth (useAuth.js)	4.86KB	0.85KB
auth (useIsWorkspaceAdmin.js)	1.61KB	0.85KB
collaboration (CommentThread.js)	18.38KB	4.49KB
collaboration (LiveCursors.js)	3.17KB	1.27KB
collaboration (PresenceAvatars.js)	3.65KB	1.42KB
collaboration (PresenceProvider.js)	2.42KB	0.96KB
collaboration (index.js)	1.25KB	0.53KB
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)	445.41KB	96.36KB
core (index.js)	1.78KB	0.61KB
create-plugin (index.js)	9.28KB	2.98KB
data-objectstack (index.js)	113.70KB	28.15KB
fields (index.js)	204.01KB	49.87KB
i18n (LocalizationContext.js)	1.76KB	0.96KB
i18n (currency.js)	1.22KB	0.64KB
i18n (i18n.js)	4.32KB	1.77KB
i18n (index.js)	2.46KB	0.96KB
i18n (pickLocalized.js)	1.70KB	0.83KB
i18n (provider.js)	5.37KB	1.72KB
i18n (useObjectLabel.js)	21.22KB	4.69KB
i18n (useSafeTranslation.js)	2.68KB	0.98KB
layout (index.js)	38.45KB	10.67KB
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)	4.42KB	1.27KB
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)	1.77KB	0.77KB
mobile (useTouchTarget.js)	1.01KB	0.54KB
permissions (MePermissionsProvider.js)	5.90KB	2.15KB
permissions (PermissionContext.js)	0.31KB	0.25KB
permissions (PermissionGuard.js)	0.89KB	0.45KB
permissions (PermissionProvider.js)	3.46KB	1.03KB
permissions (evaluator.js)	4.00KB	1.23KB
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.50KB	0.70KB
plugin-ai (index.js)	15.71KB	3.79KB
plugin-calendar (index.js)	45.12KB	12.34KB
plugin-charts (index.js)	46.31KB	13.06KB
plugin-chatbot (index.js)	176.76KB	42.28KB
plugin-dashboard (index.js)	115.53KB	28.78KB
plugin-designer (index.js)	213.89KB	43.03KB
plugin-detail (index.js)	211.36KB	51.44KB
plugin-editor (index.js)	2.46KB	1.10KB
plugin-form (index.js)	104.55KB	25.30KB
plugin-gantt (index.js)	149.17KB	37.17KB
plugin-grid (index.js)	172.00KB	45.43KB
plugin-kanban (index.js)	47.17KB	12.85KB
plugin-list (index.js)	97.92KB	23.14KB
plugin-map (index.js)	16.80KB	5.24KB
plugin-markdown (index.js)	13.65KB	4.67KB
plugin-report (index.js)	37.63KB	9.92KB
plugin-timeline (index.js)	25.37KB	7.20KB
plugin-tree (index.js)	8.36KB	2.81KB
plugin-view (index.js)	85.72KB	20.86KB
providers (DataSourceProvider.js)	0.75KB	0.39KB
providers (MetadataProvider.js)	1.37KB	0.59KB
providers (ThemeProvider.js)	1.55KB	0.67KB
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)	3.19KB	1.38KB
react (LazyPluginLoader.js)	3.77KB	1.33KB
react (SchemaRenderer.js)	18.70KB	6.09KB
react (data-invalidation.js)	5.05KB	2.08KB
react (index.js)	0.76KB	0.42KB
sdui-parser (codegen.js)	4.09KB	1.74KB
sdui-parser (index.js)	2.16KB	0.94KB
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 (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)	0.77KB	0.41KB
types (disclosure.js)	0.20KB	0.18KB
types (feedback.js)	0.20KB	0.18KB
types (field-types.js)	0.20KB	0.18KB
types (form.js)	0.20KB	0.18KB
types (index.js)	1.54KB	0.68KB
types (layout.js)	0.20KB	0.18KB
types (mobile.js)	0.20KB	0.18KB
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 (registry.js)	0.20KB	0.18KB
types (reports.js)	0.20KB	0.18KB
types (spec-report.js)	5.26KB	1.96KB
types (theme.js)	0.20KB	0.18KB
types (ui-action.js)	0.75KB	0.46KB
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