@datama/studio 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,299 @@
-# Temporary Holding Version
+# DataMa Studio v2
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Standalone npm workspace (`@datama/studio`).
+
+## Layout
+
+```text
+studio/
+  src/            # App.ts, core/, components, dialogs, solutions, assets, dev/, docs/, types/
+  tests/          # Vitest, Playwright, perf
+  dist/
+    studio/       # datama-studio.* + index.html demo
+    plotter/      # plotter CDN bundle
+    tableau/      # Tableau viz: public/ | licence/
+    powerbi/      # Power BI visual: certified/ | pro/ | pro-manual/ (npm projects)
+```
+
+| Topic | Location |
+|-------|----------|
+| Architecture (canonical) | [`archi.md`](archi.md) |
+| Architecture (agents — one section) | [`.cursor/skills/studio-architecture/reference/README.md`](.cursor/skills/studio-architecture/reference/README.md) |
+| TypeScript | `src/core/**` + rest of `src/**` as `.ts` — **`src/core/ui/**` remains `.js`** |
+| Plotter CDN | `npm run build:plotter` → `dist/plotter/plotter.{es,iife}.js` |
+
+## Commands (from repo root)
+
+> **Shell** — this repo lives on a WSL path. The IDE shell is PowerShell on a UNC path where `&&`
+> and inline `VAR=value` are invalid. Run every command below from a **WSL (Ubuntu) terminal**, or
+> wrap it: `wsl -d Ubuntu-20.04 -e bash -lc '<cmd>'`. Node is pinned to 24 — `nvm use 24` first.
+
+```bash
+nvm use 24
+npm ci              # install exact dependencies (first checkout)
+npm run serve       # Vite :8095 + Sass watch (dev)
+npm run typecheck   # tsc -p tsconfig.json
+npm run lint        # ESLint (security invariants)
+```
+
+Interim chrome CSS lives under [`src/assets/css/legacy-chrome/`](src/assets/css/legacy-chrome/README.md) until native Studio styles replace it.
+
+## Build commands (production, turn-key)
+
+Four independent build targets, each emitting into `dist/`:
+
+| Target | Script | Output | Deploy |
+|--------|--------|--------|--------|
+| Web bundle (embed/CDN) | `npm run build:prod` | `dist/studio/` + `dist/plotter/` | `npm run deploy:prod` (GCS) or `npm:publish` (npm) |
+| Tableau Viz extension | `npm run build:tableau` | `dist/tableau/{public,licence}/` | `--bucket/--folder` (GCS) |
+| Power BI custom visual | `npm run build:powerbi` | `dist/powerbi/{certified,pro,pro-manual}/` | local only (manual submit) |
+| Looker Studio Community Viz | `npm run build:lookerstudio` | `dist/lookerstudio/` | `--bucket/--folder` (GCS) |
+
+`TAG_NAME` (four-part `X.X.X.X`) stamps the version into Tableau/Power BI artifacts; defaults to `local`.
+
+### 1. Web bundle (Studio core)
+
+```bash
+# Full production build (all registered solutions + plotter CDN bundle)
+npm run build:prod                     # → dist/studio/datama-studio.{js,es.js,css} + dist/plotter/
+
+# Staging context
+npm run build:staging
+
+# Subset of solutions (smaller bundle) — inline env + forward flags after --
+STUDIO_CONTEXT=prod npm run build:all -- --solutions compare,detect
+
+# Deploy the web bundle to GCS (requires gsutil auth)
+npm run deploy:prod                    # or deploy:staging
+
+# Publish the same web bundle to npm (from generated/npm/, never the private root)
+export TAG_NAME=1.0.0.0
+npm run npm:publish:build -- --package-name @datama/studio --npm-access public
+# Dry-run (packs a .tgz under generated/npm/ without publishing):
+npm run npm:publish:dry-run -- --package-name @datama/studio --build
+```
+
+`build` = JS + CSS only · `build:all` = adds the plotter bundle · `build:prod`/`build:staging` set `STUDIO_CONTEXT`.
+Flags: `--solutions <a,b,…>` (bundle subset, default all), `--clear`/`-c` (readable/non-minified output).
+Public npm access uses Vite prod minify; restricted sets `STUDIO_CLEAR=1` (no Light-style `javascript-obfuscator` yet).
+
+### 2. Tableau Viz extension
+
+Mode is implicit: **licence** when `--api` is passed, otherwise **public**.
+
+```bash
+# Public (no backend license check)
+TAG_NAME=1.4.0.0 npm run build:tableau -- \
+  --host https://cdn.datama.io/tableau            # → dist/tableau/public/
+
+# Licence (backend license + monitoring)
+TAG_NAME=1.4.0.0 npm run build:tableau -- \
+  --api https://api.datama.io \
+  --host https://cdn.datama.io/tableau            # → dist/tableau/licence/
+
+# Build + deploy to GCS in one shot
+TAG_NAME=1.4.0.0 npm run build:tableau -- \
+  --api https://api.datama.io \
+  --host https://cdn.datama.io/tableau \
+  --bucket datama-cdn --folder tableau/licence
+```
+
+Flags: `--api/-l`, `--host`, `--bucket/-b` + `--folder/-f` (GCS deploy), `--solution/-s <a,b,…>` (default `compare,detect,explore,pivot`), `--dev/-d`, `--clear/-c`. See [`npm run build:tableau -- --help`].
+
+### 3. Power BI custom visual
+
+Emits a **complete, non-minified npm project** (reviewable by Microsoft certification) under
+`dist/powerbi/<mode>/`. The `.pbiviz` is **not** produced here — it is built inside that project.
+
+The visual version comes from `--version/-v` (or the `TAG_NAME` env var); it **must** be four-part
+`X.X.X.X` for `pbiviz package` to accept it (otherwise the build warns and defaults to `local`).
+
+```bash
+# Certified (AppSource, zero external network) — all solutions
+npm run build:powerbi -- \
+  --mode certified -s compare,detect,explore,pivot -v 1.4.0.0   # → dist/powerbi/certified/
+
+# Pro (listed on AppSource, backend license check) — --api required
+npm run build:powerbi -- \
+  --mode pro --api https://api.datama.io -v 1.4.0.0             # → dist/powerbi/pro/
+
+# Pro Manual Update (distributed from the Datama web app) — --api required
+npm run build:powerbi -- \
+  --mode pro-manual --api https://api.datama.io -v 1.4.0.0      # → dist/powerbi/pro-manual/
+
+# Equivalent: version via env instead of the flag
+TAG_NAME=1.4.0.0 npm run build:powerbi -- --mode certified
+```
+
+Then package / lint / audit **inside the generated project** (scripts live only there, never at the Studio root):
+
+```bash
+cd dist/powerbi/certified
+npm ci                 # first run writes package-lock.json (commit it in the cert repo)
+npm run lint           # ESLint + eslint-plugin-powerbi-visuals (src/ only)
+npm run audit          # pbiviz package --certification-audit → must report 0 external requests
+npm run package        # → dist/datama_powerbi.pbiviz
+```
+
+Flags: `--mode/-m <certified|pro|pro-manual>` (default `certified`), `--api/-l` (required for pro/pro-manual), `--solution/-s <a,b,…|all>`, `--version/-v <X.X.X.X>` (or `TAG_NAME`), `--guid <baseGuid>` (default reuses the Light GUID for in-place upgrade), `--dev/-d`, `--clear/-c`. See [`npm run build:powerbi -- --help`]. Full flow: [`src/platforms/powerbi/docs/README.md`](src/platforms/powerbi/docs/README.md).
+
+### 4. Looker Studio Community Viz
+
+Single **Datama Studio** package (all bundled solutions). Register in Looker with `gs://{bucket}/{folder}` after deploy.
+
+```bash
+npm run build:lookerstudio -- --help
+npm run build:lookerstudio -- --version 1.4.0.0 -s compare,detect,explore,pivot
+TAG_NAME=1.4.0.0 npm run build:lookerstudio -- --bucket app2.datama.io --folder looker-datama-studio-local
+```
+
+Flags: `--solution/-s`, `--bucket/-b` + `--folder/-f` (GCS deploy when both set), `--app`, `--version/-v` (overrides `TAG_NAME`), `--dev/-d` (no minify), `--clear/-c`, `--lite`. Full flow: [`src/platforms/lookerstudio/docs/README.md`](src/platforms/lookerstudio/docs/README.md).
+
+**Note:** Some migrated modules still use `// @ts-nocheck` while legacy types are tightened; remove incrementally after enriching `types/legacy-shim.d.ts`.
+
+## Client usage (post-build)
+
+Build the distributable bundle from the repo root:
+
+```bash
+npm run build:css      # if CSS is not already in src/assets/css/dist/
+npm run build:prod     # or build:staging
+```
+
+Artifacts (under `studio/dist/studio/`):
+
+| File | Role |
+|------|------|
+| `datama-studio.js` | IIFE bundle — global `DatamaStudio` |
+| `datama-studio.es.js` | ES module — `import DatamaStudio from "./datama-studio.es.js"` |
+| `datama-studio.css` | Required styles for the shell and chrome |
+| `index.html` | Minimal post-build demo (inline sample data + Compare story) |
+| `dist/tableau/public/` / `dist/tableau/licence/` | Tableau Viz extension bundle (`npm run build:tableau`) |
+
+Plotter CDN: `studio/dist/plotter/plotter.{es,iife}.js` + `plotter.css`.
+
+Quick local check after build:
+
+```bash
+npm run build          # from studio/
+npx --yes serve dist/studio
+# open index.html — or npm run preview (serves dist/studio)
+```
+
+Serve the host page over HTTP(S) (local static server or CDN).
+
+### Constructor parameters
+
+`new DatamaStudio(params)` runs the full mount pipeline synchronously in the constructor (configuration → DOM → infra → stories → header chrome → first `refresh()`).
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `container` | `string` \| `HTMLElement` | `"datama-studio"` | Host root element **or** id of an existing element. If omitted, a div with the default id is created on `document.body`. The element id becomes the instance `baseID`. |
+| `configuration` | `object` \| `string` | `{}` | Story / workbook bag. Passed through `DataMaStory.unpack` (plain object, JSON string, or legacy packed `{ __datamaStory__, z }`). |
+| `callbacks` | `Record<string, Function>` | `{}` | Host listeners registered on the instance event bus (`DatamaEvents`). Built-in wiring: `onLoad`, `onCreate`, and `onDelete` trigger `refresh()`. `refresh()` emits `onSuccess` or `onError`. `onFilterOnThis` fires when the user picks **Filter on this** on a Compare/Pivot segment (after the filters pin is updated). |
+| `debug` | `boolean` | `false` | Enables `DatamaLog` and `DatamaI18n` debug output. |
+| `infos` | `object` | — | Host metadata. `infos.debug === true` enables debug when `debug` is omitted. `infos.context` overrides the header host context (falls back to `context`). |
+| `context` | `string` | `"dev"` | Host context string passed to header chrome (e.g. embed environment label). |
+| `host` | `object` | — | `{ configurable?: … }` — host flags for header behavior. |
+| `header` | `object` | — | Header configuration bag (forwarded to `DatamaHeader`). |
+| `license` | `string` \| `object` | — | **v2** token (`DL2.…`), **legacy v1** LZW token, or resolved bag (`valid`, `user`, `expiration`, `solutions`, …). String tokens decode asynchronously in the constructor; prefer `DatamaStudio.create()` for a ready license before first paint. See [`src/core/license/docs/README.md`](src/core/license/docs/README.md). |
+| `isDemo` | `boolean` | — | Demo mode flag for header chrome. |
+| `allowSettingsExportWithoutLicense` | `boolean` | — | Allows settings export without a license when true. |
+
+#### `configuration` shape (minimal)
+
+Phase-1 Studio expects a **multi-story** bag compatible with `DataMaStory.hydrate`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `stories` | `object[]` \| `Record<string, object>` | Story list or id→story dictionary. Each story typically includes `id`, `title`, optional `emoji`, `preset`, `displayMode` (`"scroll"` \| `"slide"`; default `"scroll"`), optional `appearance` (default Flat; omit or pass official Default tokens), and `activeModules` (`{ instance, module }[]`). Use `displayMode: "slide"` for the carousel. |
+| `activeStory` | `string` | Id of the story selected on load. |
+| `preset` | `string` | Optional top-level preset when migrating empty workbooks (default `"compare"`). |
+| `inputs` | `object` | Optional root inputs; `inputs.language` (string or `{ value: string }`) sets UI locale (`en-US`, `fr-FR`, …). |
+
+Packed or legacy Light workbooks are accepted as long as `unpack` / `hydrate` can normalize them. Deeper story schema: [`src/resources/story/README.md`](../src/resources/story/README.md).
+
+#### Instance surface (after construction)
+
+| Member | Description |
+|--------|-------------|
+| `baseID` | Container element id for this instance. |
+| `events` | `DatamaEvents` — `listen(event, fn)`, `emit(event, …)`. |
+| `timer` | `DatamaTimer` — mount/refresh timings. |
+| `nodeManager` | `DatamaNode` scoped to the studio frame. |
+| `refresh()` | `Promise<void>` — re-applies active story appearance/display and re-renders story chrome. |
+| `debug()` | Logs instance id and timer records (requires debug logging enabled for full detail). |
+
+### Example — host embed
+
+Host page co-located with the Studio bundle (e.g. inside `dist/studio/`, or adjust paths if you deploy elsewhere):
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8">
+		<meta name="viewport" content="width=device-width, initial-scale=1.0">
+		<title>Datama Studio embed</title>
+		<link rel="stylesheet" href="./datama-studio.css">
+		<style>
+			html, body { margin: 0; height: 100%; }
+			#datama-studio { height: 100%; }
+		</style>
+	</head>
+	<body>
+		<div id="datama-studio"></div>
+		<script src="./datama-studio.js"></script>
+		<script>
+			// With an encoded license string, prefer create() so decode finishes before chrome:
+			// DatamaStudio.create({ license: "DL2....", container: "datama-studio", ... }).then(function (studio) { ... });
+
+			var studio = new DatamaStudio({
+				container: "datama-studio",
+				configuration: {
+					inputs: { language: "fr-FR" },
+					stories: [
+						{
+							id: "story-revenue",
+							title: "Revenue drop",
+							emoji: "📉",
+							preset: "compare",
+							displayMode: "scroll",
+							activeModules: [
+								{ instance: "compare.waterfall", module: "compare.waterfall" },
+							],
+						},
+					],
+					activeStory: "story-revenue",
+				},
+				debug: false,
+				callbacks: {
+					onSuccess: function () {
+						/* first refresh completed */
+					},
+					onError: function (err) {
+						console.error(err);
+					},
+				},
+			});
+		</script>
+	</body>
+</html>
+```
+
+ES module variant (`datama-studio.es.js`):
+
+```html
+<script type="module">
+	import DatamaStudio from "./datama-studio.es.js";
+
+	const studio = await DatamaStudio.create({
+		container: "datama-studio",
+		configuration: {},
+	});
+</script>
+```
+
+With an empty `configuration`, Studio bootstraps **one default story per registered solution** (Compare, Detect, Pivot when all are in the bundle).
+
+Further orchestrator notes: [`src/docs/resources/DatamaStudio.md`](src/docs/resources/DatamaStudio.md) and [`archi.md`](archi.md).