@datalabz_/dashboard-kit 4.0.0

package/README.md

@@ -0,0 +1,156 @@
+# dashboard_kit
+
+Source for **DashboardKit**, the hosted JS+CSS bundle every LLM-generated
+dashboard loads from `https://html-ui-kit-master.888drafts.com/`.
+
+## What problem it solves
+
+An LLM authoring a dashboard re-emits the same boilerplate every time — fetch
+wrapper, tab state, section loading/error states, table styling, CSV export,
+System Info panel, currency formatting, color tokens. Two costs follow:
+
+- **Output-token cost** — most of each dashboard's output doesn't vary
+  dashboard-to-dashboard.
+- **Cross-dashboard drift** — every dashboard carries its own frozen copy of
+  the boilerplate, so a bug fix doesn't reach dashboards already generated.
+
+The kit centralizes that boilerplate behind one `DashboardKit.init(...)` call.
+The author writes only SQL, section `load()` functions, dashboard-specific
+header filters, and the layout inside each panel; the kit owns the rest
+(`postMessage` handling, tabs, render primitives, formatters, CSS tokens,
+snapshot export).
+
+The LLM-facing authoring contract — what to write vs. what the kit provides —
+is [consumer_skill/dashboard-authoring-guide.md](../consumer_skill/dashboard-authoring-guide.md).
+It must always link the **current** major (see below). This file is the
+human-facing overview and the working rules for changing the kit; it is not an
+API reference. The SQL gateway the kit calls is
+[gateway_server/](../gateway_server/README.md).
+
+## Versions
+
+Each major is a separate, self-contained `vN.js`/`vN.css` pair, **pinned by
+URL from every dashboard generated against it** — those dashboards keep
+loading it indefinitely, so a shipped `vN` is a live dependency that is only
+ever added to, never altered (see Rules).
+
+- **`v4` is the current and only live major** — what the authoring guide
+  links, what `catalog.html` demos, and the only kit that is published.
+- **`v1`, `v2` and `v3` are deprecated — treat them as gone.** They live in
+  `deprecatedVersions/` for reference only and are not published. Don't move
+  them back, don't publish them, don't cite them in docs or `catalog.html`,
+  and don't copy from them when cutting a new major — start from `v4`.
+  Because they are unpublished, nothing added to these files can reach a
+  browser — a runtime deprecation warning was tried and reverted for exactly
+  that reason. Whatever is live at their CDN URLs is frozen at its last
+  published state and will vanish if the publish step prunes what is no
+  longer published.
+
+A `vN.js`/`vN.css` pair is one served bundle; the repo's per-file line budget
+(AGENTS.md #2) does not apply to it — it cannot be split without changing the
+URLs already pinned by live dashboards.
+
+## Rules
+
+- **Where a change lands — the current `vN` or a new major — is decided by
+  one question: does it make the already-shipped kit better without breaking
+  any dashboard already generated against it?** If yes, it lands in the
+  current `vN` — unless the user asked for a new major. Everything else gets a
+  new major.
+  "Better without breaking" means: an addition (a new option, a new helper, a
+  new button in kit-owned chrome, a new optional `postMessage` a parent may
+  ignore) or an improvement whose effect on an existing dashboard is only that
+  something now works better — never that its output changes. To check, trace
+  the path an existing dashboard takes — a call that omits the new option, a
+  parent that doesn't listen for the new message — and compare with today's
+  output. Rendered content the same, nothing that used to succeed now throws
+  or behaves differently → current `vN`. Anything else — including a narrow,
+  arguably-desirable fix like turning a silent no-op into a thrown error —
+  changes what a live dashboard shows, so it is a new major, no matter how
+  small or clearly-better it looks. Every live dashboard pins its `vN` by URL
+  and cannot be regenerated on demand; the current `vN` is edited in place,
+  so this is the only thing keeping them safe.
+- **Weigh every fix from three angles: kit-side (`vN.js`/`vN.css`), doc-side
+  (the authoring guide), or both.** Don't default to whichever is cheapest to
+  touch — a doc-only patch that papers over an awkward kit API, or a kit tweak
+  that's really just a doc clarification in disguise, are both weaker than
+  fixing whatever actually owns the problem. When the right fix changes
+  behavior, a new major is the normal cost of it, not a reason to settle for
+  a kludge in the current one.
+- **Don't bump `catalog.html` to a new version proactively** — only after the
+  user has reviewed and accepted that version.
+- **Every LLM-generated dashboard that uses the kit must come out:**
+  (1) safe/reliable — never crashes or mismatches, no spam beyond what was
+  asked, one idiom per task (the guide's pattern, no alternates); (2) free in
+  content — what it shows is unconstrained, only the kit's wiring is fixed;
+  (3) as short as possible — no helpers or boilerplate the kit already
+  provides. Judge every kit change against these three: an API that invites a
+  second idiom, or makes the author repeat what the kit could own, fails.
+- **The kit has no dashboard-wide currency.** `formatCurrency` takes the
+  currency per call, rows carry their own, and nothing arrives from the
+  harness — `v1`'s one-currency-per-formatter factory is exactly what was
+  retired. Don't add a global or a default; summing across currencies is the
+  query's problem to avoid, and the guide says how.
+- **The SQL gateway is shared across every live kit major** — a wire-format
+  change can break dashboards still on older `vN`s in production, not just the
+  latest.
+- **Open questions about a feature, change, or bug go in `TODO.md`, not a
+  unilateral decision.** If work surfaces something worth doing but not asked
+  for, ask the user whether to add it to `TODO.md` rather than deciding or
+  acting on it yourself.
+
+## Cutting a new version (`v{N+1}`)
+
+1. Copy `v{N}.js`/`v{N}.css` → `v{N+1}.js`/`v{N+1}.css`.
+2. Fix the header comment to `/* DashboardKit v{N+1}.js */`.
+3. Update the hardcoded `vN.css`/`vN.js` lines in `serve.mjs`'s startup
+   `console.log` (just the printed URLs — routing itself isn't version-aware).
+4. Make the actual change in the new file only.
+5. Update `catalog.html` and the authoring guide's kit links — only once the
+   user has accepted the new `vN`.
+6. The previous `vN` stays in the root and stays published. A major moves to
+   `deprecatedVersions/` only when no dashboard loads it any more — every one
+   regenerated on a newer major or deleted — and only by the user's decision,
+   never as part of cutting the next one.
+
+## Hosting
+
+Served from `https://html-ui-kit-master.888drafts.com/vN.{css,js}` — CORS
+open, `Cache-Control: immutable`. What is published is `v4.js`, `v4.css`,
+`wrapper.js`, `wrapper.css` and `catalog.html`, as they are in this directory,
+with `v4.js`'s `__BUILD__` marker replaced by the commit hash so System Info
+can say which build is live. How that gets to the host is not decided yet:
+the old repo's Bitbucket pipeline and its build script did not survive the
+move into this monorepo, and a replacement is pending with the server team.
+
+## Dev
+
+No build step — edit `vN.js`/`vN.css` directly.
+
+```bash
+npm start       # serve.mjs — dev server on :3400, CORS open
+```
+
+| URL                                                | What it serves                                                                                                                                      |
+| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `http://localhost:3400/vN.css` / `vN.js`           | Kit stylesheet / runtime for a given major                                                                                                          |
+| `http://localhost:3400/catalog.html`               | Component catalog — demos kit features                                                                                                              |
+| `http://localhost:3400/wrapper.css` / `wrapper.js` | Local harness: hosts a dashboard in a sandboxed iframe and supplies JWT + date/timezone/hierarchy via `postMessage`, standing in for the BackOffice |
+
+To simulate the harness's boot message against a dashboard opened directly:
+
+```js
+window.postMessage(
+  {
+    type: "CUSTOM_DASHBOARDS_PARAMS",
+    token: "your_jwt",
+    filters: {
+      dateFrom: "2026-05-19T03:00:00.000Z",
+      dateTo: "2026-05-20T02:59:59.999Z",
+      timezone: "America/Sao_Paulo",
+      hierarchyId: null,
+    },
+  },
+  "*",
+);
+```

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@datalabz_/dashboard-kit",
+  "version": "4.0.0",
+  "description": "DashboardKit runtime + styles, served from jsDelivr",
+  "license": "UNLICENSED",
+  "files": [
+    "v4.js",
+    "v4.css",
+    "wrapper.js",
+    "wrapper.css"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}