@xpert-ai/plugin-live-dashboard 0.3.0 → 0.4.0

package/skills/live-dashboard/examples/superstore/profitability.queries.json

@@ -0,0 +1,334 @@
+{
+  "controls": [
+    {
+      "controlId": "year",
+      "label": "年份",
+      "type": "string",
+      "defaultValue": "",
+      "allowedValues": [
+        "",
+        "2021",
+        "2022",
+        "2023",
+        "2024"
+      ]
+    },
+    {
+      "controlId": "region",
+      "label": "区域",
+      "type": "string",
+      "defaultValue": "",
+      "allowedValues": [
+        "",
+        "Central",
+        "East",
+        "South",
+        "West"
+      ]
+    },
+    {
+      "controlId": "category",
+      "label": "品类",
+      "type": "string",
+      "defaultValue": "",
+      "allowedValues": [
+        "",
+        "Furniture",
+        "Office Supplies",
+        "Technology"
+      ]
+    }
+  ],
+  "bindings": [
+    {
+      "id": "summary",
+      "providerId": "data-xpert.ontology",
+      "operation": "action",
+      "contractVersion": 1,
+      "payload": {
+        "resourceId": "<discovered-resource-id>",
+        "actionTypeCode": "sql.query_cube_slice",
+        "target": {
+          "entityTypeCode": "semantic_cube",
+          "entityRef": "<published-model-id>::SuperstoreOrders"
+        },
+        "params": {
+          "dimensions": [],
+          "measures": [
+            "Sales",
+            "Profit",
+            "Orders",
+            "Customers"
+          ],
+          "filters": [
+            {
+              "field": "OrderYear",
+              "op": "contains",
+              "value": ""
+            },
+            {
+              "field": "Region",
+              "op": "contains",
+              "value": ""
+            },
+            {
+              "field": "Category",
+              "op": "contains",
+              "value": ""
+            }
+          ],
+          "limit": 100
+        },
+        "parameterPaths": {
+          "year": [
+            "filters",
+            "0",
+            "value"
+          ],
+          "region": [
+            "filters",
+            "1",
+            "value"
+          ],
+          "category": [
+            "filters",
+            "2",
+            "value"
+          ]
+        }
+      },
+      "parameters": [
+        {
+          "name": "year",
+          "controlId": "year",
+          "type": "string",
+          "required": true,
+          "defaultValue": "",
+          "allowedValues": [
+            "",
+            "2021",
+            "2022",
+            "2023",
+            "2024"
+          ]
+        },
+        {
+          "name": "region",
+          "controlId": "region",
+          "type": "string",
+          "required": true,
+          "defaultValue": "",
+          "allowedValues": [
+            "",
+            "Central",
+            "East",
+            "South",
+            "West"
+          ]
+        },
+        {
+          "name": "category",
+          "controlId": "category",
+          "type": "string",
+          "required": true,
+          "defaultValue": "",
+          "allowedValues": [
+            "",
+            "Furniture",
+            "Office Supplies",
+            "Technology"
+          ]
+        }
+      ],
+      "output": {
+        "datasetId": "summary",
+        "fields": [
+          {
+            "id": "Sales",
+            "sourceField": "Sales",
+            "label": "Sales",
+            "logicalType": "decimal",
+            "role": "measure",
+            "nullable": true
+          },
+          {
+            "id": "Profit",
+            "sourceField": "Profit",
+            "label": "Profit",
+            "logicalType": "decimal",
+            "role": "measure",
+            "nullable": true
+          },
+          {
+            "id": "Orders",
+            "sourceField": "Orders",
+            "label": "Orders",
+            "logicalType": "int64",
+            "role": "measure",
+            "nullable": false
+          },
+          {
+            "id": "Customers",
+            "sourceField": "Customers",
+            "label": "Customers",
+            "logicalType": "int64",
+            "role": "measure",
+            "nullable": false
+          }
+        ],
+        "grain": []
+      }
+    },
+    {
+      "id": "subcategories",
+      "providerId": "data-xpert.ontology",
+      "operation": "action",
+      "contractVersion": 1,
+      "payload": {
+        "resourceId": "<discovered-resource-id>",
+        "actionTypeCode": "sql.query_cube_slice",
+        "target": {
+          "entityTypeCode": "semantic_cube",
+          "entityRef": "<published-model-id>::SuperstoreOrders"
+        },
+        "params": {
+          "dimensions": [
+            "SubCategory"
+          ],
+          "measures": [
+            "Sales",
+            "Profit",
+            "Orders",
+            "Customers"
+          ],
+          "filters": [
+            {
+              "field": "OrderYear",
+              "op": "contains",
+              "value": ""
+            },
+            {
+              "field": "Region",
+              "op": "contains",
+              "value": ""
+            },
+            {
+              "field": "Category",
+              "op": "contains",
+              "value": ""
+            }
+          ],
+          "limit": 100
+        },
+        "parameterPaths": {
+          "year": [
+            "filters",
+            "0",
+            "value"
+          ],
+          "region": [
+            "filters",
+            "1",
+            "value"
+          ],
+          "category": [
+            "filters",
+            "2",
+            "value"
+          ]
+        }
+      },
+      "parameters": [
+        {
+          "name": "year",
+          "controlId": "year",
+          "type": "string",
+          "required": true,
+          "defaultValue": "",
+          "allowedValues": [
+            "",
+            "2021",
+            "2022",
+            "2023",
+            "2024"
+          ]
+        },
+        {
+          "name": "region",
+          "controlId": "region",
+          "type": "string",
+          "required": true,
+          "defaultValue": "",
+          "allowedValues": [
+            "",
+            "Central",
+            "East",
+            "South",
+            "West"
+          ]
+        },
+        {
+          "name": "category",
+          "controlId": "category",
+          "type": "string",
+          "required": true,
+          "defaultValue": "",
+          "allowedValues": [
+            "",
+            "Furniture",
+            "Office Supplies",
+            "Technology"
+          ]
+        }
+      ],
+      "output": {
+        "datasetId": "subcategories",
+        "fields": [
+          {
+            "id": "SubCategory",
+            "sourceField": "SubCategory",
+            "label": "SubCategory",
+            "logicalType": "string",
+            "role": "dimension",
+            "nullable": false
+          },
+          {
+            "id": "Sales",
+            "sourceField": "Sales",
+            "label": "Sales",
+            "logicalType": "decimal",
+            "role": "measure",
+            "nullable": true
+          },
+          {
+            "id": "Profit",
+            "sourceField": "Profit",
+            "label": "Profit",
+            "logicalType": "decimal",
+            "role": "measure",
+            "nullable": true
+          },
+          {
+            "id": "Orders",
+            "sourceField": "Orders",
+            "label": "Orders",
+            "logicalType": "int64",
+            "role": "measure",
+            "nullable": false
+          },
+          {
+            "id": "Customers",
+            "sourceField": "Customers",
+            "label": "Customers",
+            "logicalType": "int64",
+            "role": "measure",
+            "nullable": false
+          }
+        ],
+        "grain": [
+          "SubCategory"
+        ]
+      }
+    }
+  ]
+}

package/skills/live-dashboard/examples/superstore/provenance.json

@@ -0,0 +1,24 @@
+{
+  "version": 1,
+  "dataClassification": "fictional teaching data, not actual customer operations",
+  "publisher": "Tableau / Salesforce",
+  "sourcePage": "https://tableau.github.io/extensions-api/docs/dataapps/trex_dataapp_examples/",
+  "repositoryPath": "Samples/DataApp/Tableau Superstore Data App/Data/Datasources/Sample - Superstore.xls",
+  "blobUrl": "https://api.github.com/repos/tableau/extensions-api/git/blobs/7f294f45f39c3e82b4dc738ffa5f8692c3c000d8",
+  "sourceSha256": "add4e193479cae8e9f22bfa734dd8bb706355dce38353967668f4e2b6643d19c",
+  "csvSha256": "7939076bc3b0c5841a9514da2dc2fbce91df97a05f36a586952ca95d64fcb37b",
+  "license": "Apache-2.0",
+  "licenseUrl": "https://github.com/tableau/extensions-api/blob/main/LICENSE.txt",
+  "transformations": [
+    "Normalize Excel date serials to ISO dates; decimal values to six places",
+    "Deduplicate 800 Returns rows to 296 unique Order IDs before enrichment",
+    "Preserve 10194 order-line rows; enrich with one manager per region",
+    "Derive order_year, order_month, returned, nullable returned_order_id and returned_sales",
+    "Postal codes remain text; blank returned_order_id is SQL NULL on CSV import"
+  ],
+  "visualReference": {
+    "author": "Luke Stanke / phData",
+    "url": "https://www.phdata.io/blog/building-an-executive-dashboard-in-tableau/",
+    "usage": "Information hierarchy reference only; original page implementation; no copied screenshot or brand assets"
+  }
+}

package/skills/live-dashboard/examples/superstore/semantic-model.json

@@ -0,0 +1,220 @@
+{
+  "cubes": [
+    {
+      "name": "SuperstoreOrders",
+      "caption": "Superstore 订单分析（演示）",
+      "fact": {
+        "type": "table",
+        "table": {
+          "name": "superstore_orders_v1",
+          "schema": "public"
+        }
+      },
+      "defaultMeasure": "Sales",
+      "measures": [
+        {
+          "name": "Sales",
+          "column": "sales",
+          "aggregator": "sum",
+          "caption": "销售额（USD）",
+          "datatype": "Numeric",
+          "visible": true
+        },
+        {
+          "name": "Profit",
+          "column": "profit",
+          "aggregator": "sum",
+          "caption": "利润（USD）",
+          "datatype": "Numeric",
+          "visible": true
+        },
+        {
+          "name": "Quantity",
+          "column": "quantity",
+          "aggregator": "sum",
+          "caption": "商品件数",
+          "datatype": "Numeric",
+          "visible": true
+        },
+        {
+          "name": "Orders",
+          "column": "order_id",
+          "aggregator": "distinct-count",
+          "caption": "订单数",
+          "datatype": "Numeric",
+          "visible": true
+        },
+        {
+          "name": "Customers",
+          "column": "customer_id",
+          "aggregator": "distinct-count",
+          "caption": "客户数",
+          "datatype": "Numeric",
+          "visible": true
+        },
+        {
+          "name": "ReturnedOrders",
+          "column": "returned_order_id",
+          "aggregator": "distinct-count",
+          "caption": "退货订单数",
+          "datatype": "Numeric",
+          "visible": true
+        },
+        {
+          "name": "ReturnedSales",
+          "column": "returned_sales",
+          "aggregator": "sum",
+          "caption": "退货关联销售额（USD，非退款）",
+          "datatype": "Numeric",
+          "visible": true
+        }
+      ],
+      "dimensions": [
+        {
+          "name": "OrderYear",
+          "caption": "年份",
+          "hierarchies": [
+            {
+              "name": "OrderYear",
+              "hasAll": true,
+              "levels": [
+                {
+                  "name": "OrderYear",
+                  "column": "order_year",
+                  "type": "String",
+                  "uniqueMembers": true
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "name": "OrderMonth",
+          "caption": "订单月份",
+          "hierarchies": [
+            {
+              "name": "OrderMonth",
+              "hasAll": true,
+              "levels": [
+                {
+                  "name": "OrderMonth",
+                  "column": "order_month",
+                  "type": "String",
+                  "uniqueMembers": true
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "name": "Region",
+          "caption": "区域",
+          "hierarchies": [
+            {
+              "name": "Region",
+              "hasAll": true,
+              "levels": [
+                {
+                  "name": "Region",
+                  "column": "region",
+                  "type": "String",
+                  "uniqueMembers": true
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "name": "Category",
+          "caption": "品类",
+          "hierarchies": [
+            {
+              "name": "Category",
+              "hasAll": true,
+              "levels": [
+                {
+                  "name": "Category",
+                  "column": "category",
+                  "type": "String",
+                  "uniqueMembers": true
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "name": "SubCategory",
+          "caption": "子品类",
+          "hierarchies": [
+            {
+              "name": "SubCategory",
+              "hasAll": true,
+              "levels": [
+                {
+                  "name": "SubCategory",
+                  "column": "sub_category",
+                  "type": "String",
+                  "uniqueMembers": true
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "name": "Segment",
+          "caption": "客户分群",
+          "hierarchies": [
+            {
+              "name": "Segment",
+              "hasAll": true,
+              "levels": [
+                {
+                  "name": "Segment",
+                  "column": "segment",
+                  "type": "String",
+                  "uniqueMembers": true
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "name": "Returned",
+          "caption": "退货标记",
+          "hierarchies": [
+            {
+              "name": "Returned",
+              "hasAll": true,
+              "levels": [
+                {
+                  "name": "Returned",
+                  "column": "returned",
+                  "type": "String",
+                  "uniqueMembers": true
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "name": "RegionalManager",
+          "caption": "区域经理",
+          "hierarchies": [
+            {
+              "name": "RegionalManager",
+              "hasAll": true,
+              "levels": [
+                {
+                  "name": "RegionalManager",
+                  "column": "regional_manager",
+                  "type": "String",
+                  "uniqueMembers": true
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/skills/live-dashboard/examples/superstore/test_data.py

@@ -0,0 +1,62 @@
+"""Independent checks of packaged CSV and aggregate baselines; no xlrd required."""
+import csv
+import hashlib
+import json
+import tempfile
+import unittest
+from decimal import Decimal
+from pathlib import Path
+from build_data import read_workbook
+
+ROOT = Path(__file__).resolve().parent
+
+
+class SuperstoreDataTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        with (ROOT / 'orders.csv').open() as source:
+            cls.rows = list(csv.DictReader(source))
+        cls.expected = json.loads((ROOT / 'expected.json').read_text())
+
+    def test_provenance_and_unique_order_lines(self):
+        provenance = json.loads((ROOT / 'provenance.json').read_text())
+        self.assertEqual(hashlib.sha256((ROOT / 'orders.csv').read_bytes()).hexdigest(), provenance['csvSha256'])
+        self.assertEqual(len(self.rows), 10194)
+        self.assertEqual(len({row['row_id'] for row in self.rows}), 10194)
+        self.assertEqual(min(row['order_date'] for row in self.rows), '2021-01-03')
+        self.assertEqual(max(row['order_date'] for row in self.rows), '2024-12-30')
+
+    def test_returns_do_not_multiply_facts(self):
+        returned = {row['order_id'] for row in self.rows if row['returned'] == 'Yes'}
+        self.assertEqual(len(returned), 296)
+        for row in self.rows:
+            self.assertEqual(row['returned_order_id'], row['order_id'] if row['returned'] == 'Yes' else '')
+            self.assertEqual(Decimal(row['returned_sales']), Decimal(row['sales']) if row['returned'] == 'Yes' else 0)
+
+    def test_all_filter_baselines_from_csv(self):
+        for name, case in self.expected['cases'].items():
+            with self.subTest(name=name):
+                rows = [r for r in self.rows if all(r[k] == v for k, v in case['filters'].items())]
+                self.assertEqual(len(rows), case['rows'])
+                for field, measure in [('sales', 'Sales'), ('profit', 'Profit'), ('returned_sales', 'ReturnedSales')]:
+                    self.assertEqual(sum((Decimal(r[field]) for r in rows), Decimal(0)), Decimal(case['totals'][measure]))
+                for field, measure in [('order_id', 'Orders'), ('customer_id', 'Customers'), ('returned_order_id', 'ReturnedOrders')]:
+                    self.assertEqual(len({r[field] for r in rows if r[field]}), case['totals'][measure])
+
+    def test_counts_must_not_be_added_across_groups(self):
+        case = self.expected['cases']['all']
+        self.assertGreater(sum(row['Customers'] for row in case['groups']['OrderMonth']), case['totals']['Customers'])
+        self.assertGreater(sum(row['Orders'] for row in case['groups']['SubCategory']), case['totals']['Orders'])
+        tables = next(row for row in case['groups']['SubCategory'] if row['SubCategory'] == 'Tables')
+        self.assertEqual(Decimal(tables['Profit']), Decimal('-17753.206100'))
+
+    def test_changed_workbook_rejected_before_parsing(self):
+        with tempfile.TemporaryDirectory() as directory:
+            workbook = Path(directory) / 'wrong.xls'
+            workbook.write_bytes(b'not the pinned workbook')
+            with self.assertRaisesRegex(ValueError, 'SHA-256'):
+                read_workbook(workbook)
+
+
+if __name__ == '__main__':
+    unittest.main()

package/skills/live-dashboard/references/html-runtime.md

@@ -3,7 +3,7 @@
 When the user requests a custom HTML/JavaScript page, free layout, or a specific visual style, use HTML mode. Before writing JavaScript, read [html-lifecycle.md](html-lifecycle.md) for the runnable lifecycle pattern. Keep its SDK initialization, subscriptions, typed filter fan-out and refresh behavior while changing the layout freely. Build the smallest complete page first; avoid extra aggregate Bindings when complete rows already support every panel:
 1. Discover and preview the real data exactly as for a standard dashboard. Reuse the returned previewId and binding.id; the latter is the identifier passed to the page SDK. No hard-coded business rows or stale snapshots in HTML.
 Prefer ONE complete Dataset per page when its rows already support the requested KPIs, trends, breakdown and details. Compute display aggregates from those complete rows in frontend JS. The standard chart renderer's separate-aggregate-binding requirement does not apply to custom HTML. If multiple datasets are truly necessary, every bindingId passed to query, subscribe or bindSelect MUST have its previewId included in dashboard_create_html. An upstream preview that is omitted from the saved previewIds is NOT available to the page and returns DOCUMENT_BINDING_DENIED. Never query an auxiliary totals binding without saving it, and propagate shared filters to every binding used in a dependent total.
-2. Write a complete single-file HTML/CSS/JavaScript document using sandbox_write_file({file_path,content}); use sandbox_edit_file or sandbox_multi_edit_file for existing files. Use inline styles/scripts, SVG, Canvas and DOM for any layout. Online scripts, stylesheets and fonts are available only from the exact HTTPS origins returned by dashboard_libraries.online. Tailwind CDN can be loaded with <script src="https://cdn.tailwindcss.com/3.4.17"></script>. Use complete pinned URLs where available. External images, fetch, XMLHttpRequest, WebSocket, iframes, forms, workers and eval remain unavailable. No credentials, API URLs or backend queries in page code. Call dashboard_libraries to discover packaged dependencies. ECharts and Three.js are supported without CDN: pass libraries:["echarts"] or ["three"] (or both) to dashboard_create_html; the host injects window.echarts/window.THREE before your page code. Use the documented bundled versions. Do not paste library source, use React/JSX or assume other globals. Use packaged ECharts/Three.js when requested in libraries; use ordinary script/link tags for allowed online resources, without listing them in libraries. CDN resources must be reachable during preflight and viewing; they are not frozen into the Artifact snapshot. ECharts can use SVG or Canvas: initialize a sized container once, setOption on each Dataset update and resize with ResizeObserver. When filters can remove a series/category, replace the old series: use chart.setOption(option, {notMerge:true}) or replaceMerge:["series"]. The default merge keeps stale series even when the new Dataset has fewer regions. Verify all → one region → another region → all against both totals and plotted series. Three.js core supports WebGLRenderer with WebGL2; catch unavailable GPU contexts, show a meaningful fallback, dispose resources, and do not request external textures/models/addons/workers. Libraries only render data: all queries still use the page SDK. Dependency bytes, versions and SHA-256 are frozen with the Artifact; preflight runs the identical snapshot.
+2. Write a complete single-file HTML/CSS/JavaScript document using sandbox_write_file({file_path,content}); use sandbox_edit_file or sandbox_multi_edit_file for existing files. Use inline styles/scripts, SVG, Canvas and DOM for any layout. Network access is temporarily unrestricted for functional acceptance, as reported by dashboard_libraries.online. Online scripts, stylesheets, fonts, images and fetch/XHR are available subject to browser CORS and mixed-content rules. Tailwind CDN can be loaded with <script src="https://cdn.tailwindcss.com/3.4.17"></script>. Use complete pinned URLs where available. Host DOM/storage access, forms and eval remain unavailable. Business data must use saved Bindings; do not embed credentials in HTML. No credentials, API URLs or backend queries in page code. Call dashboard_libraries to discover packaged dependencies. ECharts and Three.js are supported without CDN: pass libraries:["echarts"] or ["three"] (or both) to dashboard_create_html; the host injects window.echarts/window.THREE before your page code. Use the documented bundled versions. Do not paste library source, use React/JSX or assume other globals. Use packaged ECharts/Three.js when requested in libraries; use ordinary script/link tags for online resources, without listing them in libraries. CDN resources must be reachable during preflight and viewing; they are not frozen into the Artifact snapshot. ECharts can use SVG or Canvas: initialize a sized container once, setOption on each Dataset update and resize with ResizeObserver. When filters can remove a series/category, replace the old series: use chart.setOption(option, {notMerge:true}) or replaceMerge:["series"]. The default merge keeps stale series even when the new Dataset has fewer regions. Verify all → one region → another region → all against both totals and plotted series. Three.js core supports WebGLRenderer with WebGL2; catch unavailable GPU contexts, show a meaningful fallback, dispose resources, and do not request external textures/models/addons/workers. Libraries only render data: all queries still use the page SDK. Dependency bytes, versions and SHA-256 are frozen with the Artifact; preflight runs the identical snapshot.
 3. The injected SDK is window.xpertLiveArtifact. await live.ready() returns {bindingIds,defaults,theme,locale}. live.query(bindingId, {controlId:value}) returns the canonical Dataset {fields,rows,grain,completeness,freshness,provenance}. Field values use output.fields[].id; decimal/int64 stay exact strings. Use Number only for safe plotting; show exact monetary values. Treat received text as untrusted: use textContent, not innerHTML interpolation.
 4. Register live.subscribe(bindingId, dataset => render(dataset)) BEFORE the first query. Call live.query on initial load and filter changes; subscription callbacks redraw both normal results and toolbar refresh results. live.refresh(bindingId) repeats the latest controls. Catch errors and show an error state. Null means all only when the declared parameter allows it. Every control ID/type/default/allowedValues must match the preview and the controls argument to save.
 For a dimension selector controlling ONE binding (such as region), use the SDK helper before the initial query: live.bindSelect(document.getElementById('regionFilter'), {bindingId, controlId:'region', fieldId:'region', allLabel:'全部区域'}). Replace IDs with the exact preview IDs. It populates unique values from received Dataset rows, preserves options across filtering, and calls the declared query on change. Do not add another change listener or manually rewrite its options/values: its option values are JSON encoded to preserve types. Keep a visible associated label. Handle the bubbling xpert-query-error event to display an error. Its optional allValue defaults to null; pass the actual declared all sentinel if different. Do not use it for fixed query parameters such as forecast days, page size or granularity: these values are not Dataset rows.