docs(objectstack-ui): standardize the inline-vs-dataset chart rule (#2502)#3237
Merged
Merged
Conversation
…2502) Encode the chart-data expressibility rule into the objectstack-ui skill, pinned to what the analytics/dataset engine actually supports rather than the draft prose in the issue. - SKILL.md (Dataset-Bound Widgets): reframe around the real boundary. Every persisted chart is dataset-backed (ADR-0021 single-form cutover), so the decision is not "inline vs dataset" but "does the need fit the dataset envelope". Adds a Level A ceiling table (fits -> dataset; beyond -> Cube / stored rollup field / app code), an iron-rule callout, standardized answers for the recurring ambiguous cases (parent->child rollup, computed column, lookup filter, dashboard filter -> #2501), and a Level B note that naming a dataset is governance, not expressibility. Also corrects the Dashboards intro that still described the removed inline widget shape. - evals/analytics-inline-vs-dataset.json: first working evals for this skill, encoding the key decisions in the proven must_contain/must_not_contain format. - dashboard.zod.ts: fix the @example that still showed the removed inline widget shape (object/valueField/aggregate), which contradicted the now-required `dataset` field declared a few lines below it. Follow-ups intentionally left out of this change: service-analytics/README.md documents a retired API surface (HAVING, old IAnalyticsService methods) and needs a full rewrite; the inline-embedded-dataset schema change and the save-as-dataset promotion flow are larger, cross-repo design items tracked on the issue. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016QR9X5jcv9tEQQX5V9UZDu
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 102 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
os-zhuang
marked this pull request as ready for review
July 19, 2026 02:03
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
Standardizes the rule for how a chart's data is expressed (#2502), pinned to what the
analytics/datasetengine actually supports rather than the draft prose in the issue.The evaluation posted on #2502 found the issue's premise had drifted from shipped code: ADR-0021's single-form cutover already removed the per-widget inline query (every persisted chart is dataset-backed), and a dataset is a deliberately narrow governed layer — 5 of the issue's 7 "dataset triggers" aren't expressible in a dataset either. So the useful, checkable rule is the dataset-envelope ceiling, not "inline vs dataset".
Changes
skills/objectstack-ui/SKILL.md— Dataset-Bound Widgets: reframed around the real boundary.## Dashboardsintro that still described the removed inline widget shape.skills/objectstack-ui/evals/analytics-inline-vs-dataset.json: first working evals for this skill (provenmust_contain/must_not_containformat), encoding the key decisions.packages/spec/src/ui/dashboard.zod.ts: fixed the@examplethat still showed the removed inline widget shape (object/valueField/aggregate), which contradicted the now-requireddatasetfield declared a few lines below it.Notes / not in this PR
packages/lintvalidateWidgetBindingslinks a widget'sdataset/dimensions/valuesto itsdefineDataset, and the dataset schema forbids beyond-ceiling constructs by construction (the compiler throws on unsupported aggregates / undeclared join paths). No new heuristic lint added — it would be noise.service-analytics/README.mddocuments a retired API surface (HAVING, the oldIAnalyticsServicemethods) and needs a full rewrite; the inline-embedded-dataset schema change and the save-as-dataset promotion flow are cross-repo design items discussed on Rule: when chart data stays inline vs. requires a dataset (expressibility boundary) #2502.Test plan
@example— no runtime code paths touched.jq.dashboard.zod.tsedit is comment-only (no schema/behavior change).🤖 Generated with Claude Code
https://claude.ai/code/session_016QR9X5jcv9tEQQX5V9UZDu
Generated by Claude Code