@object-ui/plugin-dashboard 14.0.0 → 15.0.0

package/CHANGELOG.md

@@ -1,5 +1,121 @@
 # @object-ui/plugin-dashboard
 
+## 15.0.0
+
+### Patch Changes
+
+- @object-ui/types@15.0.0
+- @object-ui/core@15.0.0
+- @object-ui/i18n@15.0.0
+- @object-ui/react@15.0.0
+- @object-ui/components@15.0.0
+- @object-ui/fields@15.0.0
+
+## 14.1.0
+
+### Minor Changes
+
+- 5523fc4: Dashboard-level filters — the three #2578 item-5 enhancements (framework#2501):
+
+  - **react**: nested `PageVariablesProvider`s now MERGE instead of shadowing
+    wholesale. A filtered dashboard embedded in a Page with its own `variables`
+    keeps the outer page variables readable inside widget subtrees (`page.*`);
+    an inner definition shadows only the SAME name; writes route to the scope
+    that defines the variable (writing an outer-defined name from inside the
+    nested subtree updates the outer provider); `resetVariables` stays local.
+    Names defined nowhere still write locally, exactly as before.
+  - **core**: `buildWidgetScopedFilter` accepts an optional `knownFields` set —
+    a DEFAULT binding whose target field is not on the widget's object is
+    skipped with a console warning instead of emitting a query the backend
+    empty-matches. Explicit `filterBindings` strings are always honoured (a
+    typo surfaces as a visibly empty widget, never a silently dropped filter).
+    Omitting `knownFields` preserves the previous unchecked behaviour.
+  - **plugin-dashboard**: `DashboardRenderer` feeds `knownFields` from
+    `dataSource.getObjectSchema` for inline `object` widgets (best-effort —
+    unchecked while metadata loads or when the source can't describe objects).
+    `optionsFrom` dynamic filter options now resolve DISTINCT values
+    server-side via a dataset GROUP BY (`queryDataset` with an inline draft)
+    when the data source supports it, falling back to the previous client-side
+    top-200 dedupe otherwise.
+
+- 887062c: feat(dashboard): dashboard-level filters (date / region) driving multiple charts (framework#2501)
+
+  A dashboard's `dateRange` + `globalFilters` declarations are now wired end to
+  end: the filter values live as dashboard-level variables (the page variables
+  primitive, so they're also readable as `page.<name>` in widget expressions),
+  a filter bar renders above the widgets, and at render time the dashboard
+  broadcasts the active values into every bound widget's inline query —
+  `AND`-merged with the widget's own `filter`. Charts stay inline and
+  self-contained; each widget maps a filter to **its own** field.
+
+  - **`@object-ui/types`** — `globalFilters[].name` (stable filter/variable key,
+    defaults to `field`) and `DashboardWidgetSchema.filterBindings`
+    (`Record<string, string | false>`: per-widget field override / `false`
+    opt-out). Zod mirrors included. **Pending paired `@objectstack/spec`
+    alignment (framework#2501)** — same precedent as `dataset` /
+    `categoryGranularity`.
+  - **`@object-ui/core`** — new pure `dashboard-filters` module
+    (`resolveDashboardFilterDefs`, `dashboardFilterVariableDefs`,
+    `buildFilterCondition`, `buildWidgetScopedFilter`); `mergeFilters` lifted
+    from plugin-report (re-exported there unchanged). Date presets emit
+    date-macro tokens (`{30_days_ago}` …) so widgets resolve them at query time
+    like hand-authored filters.
+  - **`@object-ui/plugin-dashboard`** — `DashboardFilterBar` (date presets +
+    custom range calendar, select with static `options` or `optionsFrom`,
+    text/number inputs, reset); `DashboardRenderer` mounts a
+    `PageVariablesProvider` when filters are declared and merges the
+    widget-scoped condition into inline widgets' `filter` and dataset widgets'
+    `runtimeFilter`. Dashboards without filters render exactly as before.
+
+  Binding precedence: explicit `filterBindings` string/`false` → legacy
+  `targetWidgets` allow-list → the filter's own `field` (dateRange defaults to
+  `created_at`). Static-data widgets are not filtered.
+
+### Patch Changes
+
+- 2ded18c: Fix: a dashboard filter declaring its static `options` in the
+  `@objectstack/spec` object form (`options: [{ value, label }]` — the shape
+  the spec validates and what framework-authored dashboards ship) crashed the
+  whole dashboard with "Objects are not valid as a React child". Caught driving
+  the showcase Revenue Pulse dashboard in a real browser.
+
+  `resolveDashboardFilterDefs` now normalizes both the spec object form and the
+  bare-string shorthand (`options: ['EMEA']`) to `{ value, label }` pairs —
+  `DashboardFilterDef.options` is typed accordingly — and the filter bar's
+  select renders labels (the trigger now shows the selected option's label, not
+  its raw value). `@object-ui/types` aligns the `GlobalFilterSchema.options`
+  shape with the spec union.
+
+- Updated dependencies [82441e4]
+- Updated dependencies [2efa9fd]
+- Updated dependencies [0890fa7]
+- Updated dependencies [2ded18c]
+- Updated dependencies [e628d1f]
+- Updated dependencies [5523fc4]
+- Updated dependencies [887062c]
+- Updated dependencies [579b24d]
+- Updated dependencies [2b30583]
+- Updated dependencies [23d65c3]
+- Updated dependencies [055e1d2]
+- Updated dependencies [9e2d58f]
+- Updated dependencies [dea65f7]
+- Updated dependencies [f30ff68]
+- Updated dependencies [073e7aa]
+- Updated dependencies [3e8bf07]
+- Updated dependencies [6c0135c]
+- Updated dependencies [5b52624]
+- Updated dependencies [4afb251]
+- Updated dependencies [d5b1bc0]
+- Updated dependencies [f94905d]
+- Updated dependencies [2712fc1]
+- Updated dependencies [f0f10f5]
+  - @object-ui/i18n@14.1.0
+  - @object-ui/fields@14.1.0
+  - @object-ui/core@14.1.0
+  - @object-ui/types@14.1.0
+  - @object-ui/react@14.1.0
+  - @object-ui/components@14.1.0
+
 ## 14.0.0
 
 ### Patch Changes

package/README.md

@@ -195,6 +195,78 @@ const schema = {
 };
 ```
 
+## Dashboard-level filters
+
+A dashboard can declare top-level filters — a date range and any number of
+select / text filters — whose values drive **every bound widget at once**.
+The filter values live as dashboard-level variables (the page/dashboard
+variables primitive), and each widget declares which of **its own** fields a
+filter binds to. At render time the dashboard merges the active filter values
+into each bound widget's inline query (`AND`-combined with the widget's own
+`filter`).
+
+```jsonc
+{
+  "type": "dashboard",
+  "dateRange": {
+    "field": "created_at",          // default binding target
+    "defaultRange": "last_30_days", // today | this_week | … | last_90_days | custom
+    "allowCustomRange": true        // offer a custom from/to calendar
+  },
+  "globalFilters": [
+    {
+      "name": "region",             // stable filter name (defaults to field)
+      "field": "region",            // default binding target
+      "label": "Region",
+      "type": "select",             // text | select | date | number | lookup
+      "options": ["EMEA", "APAC", "AMER"]
+      // or dynamic: "optionsFrom": { "object": "accounts", "valueField": "region" }
+    }
+  ],
+  "widgets": [
+    // Default binding: the filter's own `field` (dateRange → created_at).
+    { "id": "w1", "type": "bar", "object": "invoices", "aggregate": "count" },
+    // Explicit binding: map each filter to THIS widget's own field.
+    {
+      "id": "w2", "type": "line", "object": "accounts", "aggregate": "count",
+      "filterBindings": { "dateRange": "signed_at", "region": "sales_region" }
+    },
+    // Opt out of a filter with `false`.
+    {
+      "id": "w3", "type": "metric", "object": "invoices", "aggregate": "count",
+      "filterBindings": { "region": false }
+    }
+  ]
+}
+```
+
+Binding rules, in precedence order:
+
+1. `filterBindings[name]` as a string — apply the filter to that field.
+2. `filterBindings[name]: false` — opt this widget out.
+3. Legacy `targetWidgets` on the filter — when set, only listed widget ids
+   get the default binding (an explicit `filterBindings` entry still wins).
+4. Otherwise the filter applies to its own `field` (the built-in date range
+   defaults to `dateRange.field ?? 'created_at'`).
+
+Notes:
+
+- Date presets stay symbolic (`{30_days_ago}` … date-macro tokens) until
+  query time, so widgets resolve them exactly like hand-authored filters.
+- Dataset-bound widgets receive the merged filter through the dataset
+  query's `runtimeFilter`.
+- Static-data widgets (inline `data` arrays) have no query to scope and are
+  not filtered.
+- Filter values are also readable in widget expressions as `page.<name>`
+  (e.g. `page.region`), since they are hosted as dashboard variables.
+- `optionsFrom` resolves distinct option values server-side (a dataset
+  GROUP BY) when the data source supports dataset queries, falling back to
+  a client-side dedupe over the first 200 records otherwise.
+- Default bindings are metadata-aware for inline `object` widgets: a default
+  field that doesn't exist on the widget's object is skipped with a console
+  warning instead of emitting a query that matches nothing. Explicit
+  `filterBindings` strings are always honoured as written.
+
 ## TypeScript Support
 
 ```typescript

package/dist/DashboardFilterBar.d.ts

@@ -0,0 +1,12 @@
+import { default as React } from 'react';
+import { DashboardFilterDef } from '@object-ui/core';
+export interface DashboardFilterBarProps {
+    defs: DashboardFilterDef[];
+    values: Record<string, any>;
+    onChange: (name: string, value: any) => void;
+    onReset?: () => void;
+    dataSource?: any;
+    className?: string;
+}
+export declare function DashboardFilterBar({ defs, values, onChange, onReset, dataSource, className }: DashboardFilterBarProps): React.JSX.Element | null;
+//# sourceMappingURL=DashboardFilterBar.d.ts.map

package/dist/DashboardFilterBar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DashboardFilterBar.d.ts","sourceRoot":"","sources":["../src/DashboardFilterBar.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;GAQG;AAEH,OAAO,KAAuC,MAAM,OAAO,CAAC;AAiB5D,OAAO,EAEL,KAAK,kBAAkB,EAExB,MAAM,iBAAiB,CAAC;AAOzB,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,kBAAkB,EAAE,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;IAC7C,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,UAAU,CAAC,EAAE,GAAG,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA2ND,wBAAgB,kBAAkB,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,EAAE,uBAAuB,4BAyCrH"}

package/dist/DashboardRenderer.d.ts

@@ -39,5 +39,20 @@ export interface DashboardRendererProps {
     hideHeaderText?: boolean;
     [key: string]: any;
 }
+/**
+ * DashboardRenderer — the public dashboard renderer.
+ *
+ * When the schema declares dashboard-level filters (`globalFilters` /
+ * `dateRange`, framework#2501), their values are hosted as dashboard
+ * variables in a `PageVariablesProvider` (the page/dashboard variables
+ * primitive) so the filter bar can write them, the widget broadcast can read
+ * them, and widget expressions can reference them as `page.<name>`.
+ * Dashboards without filters render exactly as before — no provider mounted.
+ *
+ * When a filtered dashboard is embedded inside a Page with its own
+ * variables, the nested providers MERGE (#2578 item 5): outer page variables
+ * stay readable inside widget subtrees, and only a same-named filter shadows
+ * the outer variable.
+ */
 export declare const DashboardRenderer: import('react').ForwardRefExoticComponent<Omit<DashboardRendererProps, "ref"> & import('react').RefAttributes<HTMLDivElement>>;
 //# sourceMappingURL=DashboardRenderer.d.ts.map

package/dist/DashboardRenderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DashboardRenderer.d.ts","sourceRoot":"","sources":["../src/DashboardRenderer.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAG/E,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AA+J5F,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,eAAe,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,oCAAoC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iCAAiC;IACjC,WAAW,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACrE,kEAAkE;IAClE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,gDAAgD;IAChD,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,uDAAuD;IACvD,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAClD;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,qBAAqB,EAAE,KAAK,IAAI,CAAC;IAC9D,mGAAmG;IACnG,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,wGAAwG;IACxG,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAAC,CAAC;IACrH;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,eAAO,MAAM,iBAAiB,gIAy1B7B,CAAC"}
+{"version":3,"file":"DashboardRenderer.d.ts","sourceRoot":"","sources":["../src/DashboardRenderer.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAG/E,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAmL5F,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,eAAe,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,oCAAoC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iCAAiC;IACjC,WAAW,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACrE,kEAAkE;IAClE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,gDAAgD;IAChD,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,uDAAuD;IACvD,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAClD;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,qBAAqB,EAAE,KAAK,IAAI,CAAC;IAC9D,mGAAmG;IACnG,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,wGAAwG;IACxG,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAAC,CAAC;IACrH;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAg7BD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,gIAiB7B,CAAC"}