@luquimbo/bi-superpowers 3.2.0 → 4.1.0

package/skills/report-design/scripts/create-visual.js

@@ -0,0 +1,878 @@
+#!/usr/bin/env node
+/**
+ * create-visual.js — Node-only PBIR visual creator.
+ *
+ * Replaces `pbi visual add` + `pbi visual bind` for the 28 native visualTypes
+ * that PBI Desktop (March 2026, schema 2.7.0) accepts. No dependency on the
+ * pbi-cli-tool upstream. The exact count is locked in by create-visual.test.js
+ * (the EXPECTED_TYPES array + a length assertion) — update both if the
+ * allowlist changes.
+ *
+ * Why: the CLI has 3 known regressions (see SKILL.md audit):
+ *   1. advertises only 5 types in `--type`; silently accepts ~20 more.
+ *   2. accepts type aliases that rewrite to invalid PBIR (e.g. `pie` → `donutChart`).
+ *   3. accepts `stackedBarChart` / `stackedColumnChart` which are NOT native
+ *      visualTypes — Desktop renders them as "objeto visual personalizado".
+ *
+ * This script is the single source of truth for what a native PBIR visual
+ * looks like. Shape canonical derived from:
+ *   - CLI-generated shapes (for the 23 types the CLI can create)
+ *   - examples/smoke-test/.../theme/visuals/*.json (hundredPercentStackedBarChart,
+ *     hundredPercentStackedColumnChart, pieChart, scatterChart-with-Legend-and-Size,
+ *     waterfallChart-with-Breakdown)
+ *
+ * Usage:
+ *   node create-visual.js \
+ *     --report-path ./pbip-files/Foo.Report \
+ *     --page experiment \
+ *     --type clusteredBarChart \
+ *     --name my_bar \
+ *     --x 24 --y 24 --width 600 --height 280 \
+ *     --bind category="Categorias Finanzas[Categoria]" \
+ *     --bind y="_Measures[Gastos]" \
+ *     --bind legend="Cuentas[Banco]" \
+ *     --title "Gasto por categoría"
+ *
+ * Special visual types with shortcuts:
+ *
+ *   --type textbox    use --paragraph "text" (repeatable), no --bind
+ *                     or --title/--description for title+body shortcut.
+ *
+ *   --type slicer     use --slicer-mode {basic|horizontal|dropdown|between|relative}
+ *                     + --bind values=Table[Column]
+ *                     (horizontal implies Basic mode + orientation 2)
+ *
+ * Options:
+ *   -p, --report-path  Path to the .Report folder.                [required]
+ *   --page             Page name (folder under definition/pages).  [required]
+ *   -t, --type         Native PBIR visualType. See `--list-types`. [required]
+ *   -n, --name         Visual name (also the folder name). Auto-generated if omitted.
+ *   --x, --y           Canvas position (pixels). Default 0.
+ *   --width, --height  Size. Defaults 400x300 for charts, 280x120 for cards.
+ *   --tab-order        Tab order. Auto-incremented from existing visuals if omitted.
+ *   -z                 z-index. Auto-incremented from existing visuals if omitted.
+ *   --bind role=FIELD  Bind a field to a data role. Repeatable.
+ *                      FIELD = "Table[Column]" or "Table[Measure]".
+ *                      Use 'Table Name'[Field] if the table has spaces.
+ *                      Role is case-insensitive (category = Category).
+ *   --title TEXT       Set container title text (overrides the default "" title).
+ *   --no-title         Hide the container title.
+ *   --paragraph TEXT   Textbox paragraph. Repeatable. First paragraph is styled
+ *                      bigger by default (title-ish).
+ *   --description TEXT Textbox body shortcut (used with --title).
+ *   --slicer-mode MODE basic | horizontal | dropdown | between | relative
+ *   --list-types       Print all supported visualTypes with their roles and exit.
+ *   -h, --help         Show this help.
+ *
+ * Idempotent: if a visual with the same --name already exists on --page,
+ * this script FAILS (no silent overwrite). Delete the folder manually or
+ * use a different --name. This matches the CLI's behavior and avoids
+ * accidental data loss on bindings.
+ *
+ * Exit codes: 0 success, 1 user error (bad args, unknown type), 2 I/O error.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// NATIVE_VISUAL_TYPES — the single source of truth for what PBIR accepts.
+//
+// Each entry describes one visualType:
+//   - description:  one-line human explanation.
+//   - roles:        { <RoleName>: { kind: 'measure'|'column', required, multi } }
+//                   Role name is the PBIR Pascal-case name (Category, Y, Legend,
+//                   ColumnY, LineY, Breakdown, Details, X, Size, Indicator, etc.)
+//   - defaults:     (optional) extra fields to set on visual (e.g.
+//                   sortDefinition for cardVisual).
+//   - notes:        (optional) extra guidance printed with --list-types.
+//
+// NOT in this table = NOT a supported native PBIR visualType. Do NOT add
+// `stackedBarChart`, `stackedColumnChart`, or `stackedAreaChart` — they are
+// patterns (use the non-stacked type with a Legend field), not types.
+// ---------------------------------------------------------------------------
+
+const NATIVE_VISUAL_TYPES = {
+  // ---- Single value ----
+  card: {
+    description: 'Tarjeta KPI clásica (un valor grande + label).',
+    roles: {
+      Values: { kind: 'measure', required: true, multi: false },
+    },
+  },
+  cardVisual: {
+    description: 'New card (March 2026). Multiple measures + targets inline.',
+    roles: {
+      Data: { kind: 'measure', required: true, multi: true },
+    },
+    defaults: {
+      query: { sortDefinition: { sort: [], isDefaultSort: true } },
+      visualContainerObjects: {},
+    },
+  },
+  kpi: {
+    description: 'KPI con Indicator + Goal + TrendLine.',
+    roles: {
+      Indicator: { kind: 'measure', required: true, multi: false },
+      Goal: { kind: 'measure', required: false, multi: false },
+      TrendLine: { kind: 'column', required: false, multi: false },
+    },
+  },
+  gauge: {
+    description: 'Gauge arco: Y actual vs MaxValue (+ target opcional).',
+    roles: {
+      Y: { kind: 'measure', required: true, multi: false },
+      MaxValue: { kind: 'measure', required: false, multi: false },
+      TargetValue: { kind: 'measure', required: false, multi: false },
+      MinValue: { kind: 'measure', required: false, multi: false },
+    },
+  },
+  multiRowCard: {
+    description: 'Card multi-valor (múltiples measures apiladas).',
+    roles: {
+      Values: { kind: 'measure', required: true, multi: true },
+    },
+  },
+
+  // ---- Bar / Column ----
+  barChart: {
+    description: 'Bar chart. Agrega Legend para stacked-bar (no uses stackedBarChart).',
+    roles: {
+      Category: { kind: 'column', required: true, multi: false },
+      Y: { kind: 'measure', required: true, multi: true },
+      Legend: { kind: 'column', required: false, multi: false },
+    },
+    notes: 'Para stacked: agregá --bind legend=Tabla[Col]. NO existe stackedBarChart nativo.',
+  },
+  clusteredBarChart: {
+    description: 'Bar chart agrupado (side-by-side por Series).',
+    roles: {
+      Category: { kind: 'column', required: true, multi: false },
+      Y: { kind: 'measure', required: true, multi: true },
+      Legend: { kind: 'column', required: false, multi: false },
+    },
+  },
+  columnChart: {
+    description: 'Column chart. Agrega Legend para stacked-column (no uses stackedColumnChart).',
+    roles: {
+      Category: { kind: 'column', required: true, multi: false },
+      Y: { kind: 'measure', required: true, multi: true },
+      Legend: { kind: 'column', required: false, multi: false },
+    },
+    notes: 'Para stacked: agregá --bind legend=Tabla[Col]. NO existe stackedColumnChart nativo.',
+  },
+  clusteredColumnChart: {
+    description: 'Column chart agrupado (side-by-side por Series).',
+    roles: {
+      Category: { kind: 'column', required: true, multi: false },
+      Y: { kind: 'measure', required: true, multi: true },
+      Legend: { kind: 'column', required: false, multi: false },
+    },
+  },
+  hundredPercentStackedBarChart: {
+    description: 'Bar 100% apilado (Legend obligatorio).',
+    roles: {
+      Category: { kind: 'column', required: true, multi: false },
+      Y: { kind: 'measure', required: true, multi: false },
+      Legend: { kind: 'column', required: true, multi: false },
+    },
+    notes: 'Legend es mandatorio — sin él no tiene sentido el 100%.',
+  },
+  hundredPercentStackedColumnChart: {
+    description: 'Column 100% apilado (Legend obligatorio).',
+    roles: {
+      Category: { kind: 'column', required: true, multi: false },
+      Y: { kind: 'measure', required: true, multi: false },
+      Legend: { kind: 'column', required: true, multi: false },
+    },
+    notes: 'Legend es mandatorio — sin él no tiene sentido el 100%.',
+  },
+
+  // ---- Line / Area ----
+  lineChart: {
+    description: 'Line chart para time series.',
+    roles: {
+      Category: { kind: 'column', required: true, multi: false },
+      Y: { kind: 'measure', required: true, multi: true },
+      Legend: { kind: 'column', required: false, multi: false },
+    },
+  },
+  areaChart: {
+    description: 'Area chart. Agrega Legend para stacked-area (no uses stackedAreaChart).',
+    roles: {
+      Category: { kind: 'column', required: true, multi: false },
+      Y: { kind: 'measure', required: true, multi: true },
+      Legend: { kind: 'column', required: false, multi: false },
+    },
+    notes: 'Para stacked: agregá --bind legend=Tabla[Col]. NO existe stackedAreaChart nativo.',
+  },
+  lineClusteredColumnComboChart: {
+    description: 'Combo: columnas agrupadas + líneas sobre el mismo eje X.',
+    roles: {
+      Category: { kind: 'column', required: true, multi: false },
+      ColumnY: { kind: 'measure', required: true, multi: true },
+      LineY: { kind: 'measure', required: true, multi: true },
+      Legend: { kind: 'column', required: false, multi: false },
+    },
+    notes:
+      'ÚNICA variante combo que Desktop March 2026 renderiza (la variante stacked está rota — ver KNOWN_NON_NATIVE_TYPES). Usa --bind columny= y --bind liney=.',
+  },
+  ribbonChart: {
+    description: 'Ribbon chart (muestra ranking changing over time).',
+    roles: {
+      Category: { kind: 'column', required: true, multi: false },
+      Y: { kind: 'measure', required: true, multi: false },
+      Legend: { kind: 'column', required: false, multi: false },
+    },
+    notes:
+      'Puede requerir el preview flag "Ribbon visual" en Desktop Options. Verificá en `references/visual-types.md` antes de publicar un reporte que depende de este tipo.',
+  },
+
+  // ---- Part-to-whole ----
+  pieChart: {
+    description: 'Torta (pie).',
+    roles: {
+      Category: { kind: 'column', required: true, multi: false },
+      Y: { kind: 'measure', required: true, multi: false },
+    },
+  },
+  donutChart: {
+    description: 'Dona (donut).',
+    roles: {
+      Category: { kind: 'column', required: true, multi: false },
+      Y: { kind: 'measure', required: true, multi: false },
+    },
+  },
+  treemap: {
+    description: 'Treemap (rectángulos proporcionales).',
+    roles: {
+      Category: { kind: 'column', required: true, multi: false },
+      Values: { kind: 'measure', required: true, multi: false },
+    },
+  },
+
+  // ---- Análisis ----
+  funnelChart: {
+    description: 'Embudo (stages con drop-off).',
+    roles: {
+      Category: { kind: 'column', required: true, multi: false },
+      Y: { kind: 'measure', required: true, multi: false },
+    },
+  },
+  scatterChart: {
+    description: 'Scatter / bubble (X vs Y, opcional Size → bubble).',
+    roles: {
+      Details: { kind: 'column', required: true, multi: false },
+      X: { kind: 'measure', required: true, multi: false },
+      Y: { kind: 'measure', required: true, multi: false },
+      Legend: { kind: 'column', required: false, multi: false },
+      Size: { kind: 'measure', required: false, multi: false },
+    },
+    notes: 'Si agregás --bind size=..., se convierte en bubble chart.',
+  },
+  waterfallChart: {
+    description: 'Cascada (accumulator con deltas positivos/negativos).',
+    roles: {
+      Category: { kind: 'column', required: true, multi: false },
+      Y: { kind: 'measure', required: true, multi: false },
+      Breakdown: { kind: 'column', required: false, multi: false },
+    },
+  },
+
+  // ---- Tabular ----
+  tableEx: {
+    description: 'Tabla (row-detail, muchas columnas).',
+    roles: {
+      Values: { kind: 'any', required: true, multi: true },
+    },
+  },
+  pivotTable: {
+    description: 'Matriz (rows × columns × values).',
+    roles: {
+      Rows: { kind: 'column', required: true, multi: true },
+      Columns: { kind: 'column', required: false, multi: true },
+      Values: { kind: 'measure', required: true, multi: true },
+    },
+  },
+
+  // ---- Filtros ----
+  slicer: {
+    description: 'Slicer clásico (5 modos: basic, horizontal, dropdown, between, relative).',
+    roles: {
+      Values: { kind: 'column', required: true, multi: false },
+    },
+    notes: 'Usá --slicer-mode para elegir modo. Default: basic (vertical list).',
+  },
+  advancedSlicerVisual: {
+    description: 'Advanced slicer (March 2026 new slicer).',
+    roles: {
+      Values: { kind: 'column', required: true, multi: false },
+    },
+  },
+  listSlicer: {
+    description: 'List slicer (legacy typeId, list-only).',
+    roles: {
+      Values: { kind: 'column', required: true, multi: false },
+    },
+    notes: 'Legacy typeId. Preferí `slicer` con `--slicer-mode basic` para reportes nuevos.',
+  },
+  textSlicer: {
+    description: 'Text input slicer (filtra por substring).',
+    roles: {
+      Values: { kind: 'column', required: true, multi: false },
+    },
+  },
+
+  // ---- Texto ----
+  textbox: {
+    description: 'Textbox libre (no tiene query). Usá --paragraph o --title+--description.',
+    roles: {}, // no data roles
+    notes: 'No admite --bind. Usá --paragraph (repeatable) o --title/--description.',
+  },
+};
+
+// Known non-native types we want to *block* with a clear error message.
+const KNOWN_NON_NATIVE_TYPES = {
+  stackedBarChart:
+    'stackedBarChart NO es un tipo nativo. Usá --type barChart + --bind legend=Tabla[Col] para el mismo efecto.',
+  stackedColumnChart:
+    'stackedColumnChart NO es un tipo nativo. Usá --type columnChart + --bind legend=Tabla[Col].',
+  stackedAreaChart:
+    'stackedAreaChart NO es un tipo nativo. Usá --type areaChart + --bind legend=Tabla[Col].',
+  lineStackedColumnComboChart:
+    'lineStackedColumnComboChart pasa validate pero Desktop no lo renderiza (container vacío). Usá --type lineClusteredColumnComboChart (la variante clustered, que SÍ funciona).',
+  funnel: 'funnel es un typeId legacy. Usá --type funnelChart.',
+  pie: 'pie no es un visualType. Usá --type pieChart (o --type donutChart).',
+  donut: 'donut no es un visualType. Usá --type donutChart.',
+  bar_chart: 'bar_chart es alias del CLI upstream. Este script usa nombres PBIR nativos — usá --type barChart.',
+  line_chart: 'line_chart es alias del CLI upstream. Usá --type lineChart.',
+  column_chart: 'column_chart no existe. Usá --type columnChart.',
+  area_chart: 'area_chart no existe. Usá --type areaChart.',
+};
+
+const SLICER_MODES = {
+  basic: { mode: 'Basic', orientation: 1 },
+  horizontal: { mode: 'Basic', orientation: 2 },
+  dropdown: { mode: 'Dropdown' },
+  between: { mode: 'Between' },
+  relative: { mode: 'Relative' },
+};
+
+const VISUAL_SCHEMA = 'https://developer.microsoft.com/json-schemas/fabric/item/report/definition/visualContainer/2.7.0/schema.json';
+
+// ---------------------------------------------------------------------------
+// CLI argument parsing
+// ---------------------------------------------------------------------------
+
+function fail(msg, code = 1) {
+  process.stderr.write(`create-visual: ${msg}\n`);
+  process.exit(code);
+}
+
+function parseArgs(argv) {
+  const out = {
+    bindings: {}, // { RoleName: [fieldRef, ...] } always array to handle multi
+    paragraphs: [],
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    const next = () => {
+      const v = argv[++i];
+      if (v === undefined) fail(`missing value for ${a}`);
+      return v;
+    };
+    if (a === '-p' || a === '--report-path') out.reportPath = next();
+    else if (a === '--page') out.page = next();
+    else if (a === '-t' || a === '--type') out.type = next();
+    else if (a === '-n' || a === '--name') out.name = next();
+    else if (a === '--x') out.x = Number(next());
+    else if (a === '--y') out.y = Number(next());
+    else if (a === '--width') out.width = Number(next());
+    else if (a === '--height') out.height = Number(next());
+    else if (a === '--tab-order') out.tabOrder = Number(next());
+    else if (a === '-z' || a === '--z') out.z = Number(next());
+    else if (a === '--bind' || a === '--binding') {
+      const v = next();
+      const eq = v.indexOf('=');
+      if (eq < 1) fail(`--bind expects role=Table[Field], got: ${v}`);
+      const role = v.slice(0, eq).trim();
+      const ref = v.slice(eq + 1).trim();
+      if (!role || !ref) fail(`--bind expects role=Table[Field], got: ${v}`);
+      out.bindings[role] = out.bindings[role] || [];
+      out.bindings[role].push(ref);
+    } else if (a === '--title') out.title = next();
+    else if (a === '--no-title') out.noTitle = true;
+    else if (a === '--paragraph') out.paragraphs.push(next());
+    else if (a === '--description') out.description = next();
+    else if (a === '--slicer-mode') out.slicerMode = next();
+    else if (a === '--list-types') out.listTypes = true;
+    else if (a === '-h' || a === '--help') out.help = true;
+    else fail(`unknown argument: ${a}`);
+  }
+  return out;
+}
+
+function printHelp() {
+  process.stdout.write(
+    [
+      'Usage: create-visual.js --report-path <path> --page <name> --type <visualType> [options]',
+      '',
+      'Required:',
+      '  -p, --report-path PATH   Path to .Report folder',
+      '      --page NAME          Page folder name under definition/pages/',
+      '  -t, --type TYPE          Native PBIR visualType (use --list-types to see all)',
+      '',
+      'Visual placement:',
+      '  -n, --name NAME          Visual folder name (auto-generated if omitted)',
+      '      --x N --y N          Canvas position in px (default 0,0)',
+      '      --width N            Width in px (default 400)',
+      '      --height N           Height in px (default 300)',
+      '      --tab-order N        Tab order (auto-incremented if omitted)',
+      '  -z, --z N                z-index (auto-incremented if omitted)',
+      '',
+      'Data bindings (repeatable):',
+      '      --bind ROLE=FIELD    e.g. --bind category="Cuentas[Banco]"',
+      '                                 --bind y="_Measures[Monto]"',
+      '                           Role names are case-insensitive.',
+      '',
+      'Container:',
+      '      --title TEXT         Container title text',
+      '      --no-title           Hide container title',
+      '',
+      'Textbox shortcuts (--type textbox):',
+      '      --paragraph TEXT     Repeatable paragraph',
+      '      --title TEXT         Title paragraph (28pt bold by default)',
+      '      --description TEXT   Body paragraph (14pt by default)',
+      '',
+      'Slicer shortcut (--type slicer):',
+      '      --slicer-mode MODE   basic | horizontal | dropdown | between | relative',
+      '',
+      'Other:',
+      '      --list-types         Show all supported visualTypes with roles',
+      '  -h, --help               Show this help',
+      '',
+    ].join('\n')
+  );
+}
+
+function printTypes() {
+  const names = Object.keys(NATIVE_VISUAL_TYPES).sort();
+  process.stdout.write(`Native PBIR visualTypes (${names.length}):\n\n`);
+  for (const name of names) {
+    const def = NATIVE_VISUAL_TYPES[name];
+    process.stdout.write(`  ${name}\n    ${def.description}\n`);
+    const roleLines = Object.entries(def.roles).map(([r, spec]) => {
+      const flags = [];
+      if (spec.required) flags.push('required');
+      if (spec.multi) flags.push('multi');
+      flags.push(spec.kind);
+      return `      ${r} (${flags.join(', ')})`;
+    });
+    if (roleLines.length) process.stdout.write(`    roles:\n${roleLines.join('\n')}\n`);
+    if (def.notes) process.stdout.write(`    note: ${def.notes}\n`);
+    process.stdout.write('\n');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Field ref parsing
+// ---------------------------------------------------------------------------
+
+// Parses "Table[Field]" or "'Table With Spaces'[Field]" into { table, field }.
+function parseFieldRef(ref) {
+  // Quoted: 'Some Table'[Field]
+  let m = ref.match(/^'([^']+)'\[([^\]]+)\]$/);
+  if (m) return { table: m[1], field: m[2] };
+  // Unquoted: Table[Field]  (table can have spaces too in some models)
+  m = ref.match(/^([^[]+)\[([^\]]+)\]$/);
+  if (m) return { table: m[1].trim(), field: m[2] };
+  fail(`invalid field ref: ${ref} — use Table[Field] or 'Table Name'[Field]`);
+  return null;
+}
+
+function buildProjection(fieldRef, kind) {
+  const { table, field } = parseFieldRef(fieldRef);
+  const wrapper = kind === 'measure' ? 'Measure' : 'Column';
+  return {
+    field: {
+      [wrapper]: {
+        Expression: { SourceRef: { Entity: table } },
+        Property: field,
+      },
+    },
+    queryRef: `${table}.${field}`,
+    nativeQueryRef: field,
+    // Only columns get "active: true" in the CLI-generated shapes; measures don't.
+    ...(kind === 'column' ? { active: true } : {}),
+  };
+}
+
+// Role name canonicalization: users can type 'category' and we match it to 'Category'.
+function canonicalRoleName(roles, input) {
+  const lower = input.toLowerCase();
+  for (const key of Object.keys(roles)) {
+    if (key.toLowerCase() === lower) return key;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Shape builder per visualType category
+// ---------------------------------------------------------------------------
+
+function buildQueryState(def, bindingsCanonical) {
+  const queryState = {};
+  for (const role of Object.keys(def.roles)) {
+    const spec = def.roles[role];
+    const refs = bindingsCanonical[role] || [];
+    const projections = refs.map((ref) => {
+      // 'any' kind → decide by table prefix convention: _Measures → measure.
+      let kind = spec.kind;
+      if (kind === 'any') {
+        const { table } = parseFieldRef(ref);
+        kind = table === '_Measures' || table.endsWith('_Measures') ? 'measure' : 'column';
+      }
+      return buildProjection(ref, kind);
+    });
+    queryState[role] = { projections };
+  }
+  return queryState;
+}
+
+function buildTextbox(args) {
+  const paragraphs = [];
+  // --title + --description combo shortcut
+  if (args.title) {
+    paragraphs.push({
+      textRuns: [
+        {
+          value: args.title,
+          textStyle: {
+            fontFamily: "'Segoe UI Semibold', wf_segoe-ui_semibold, helvetica, arial, sans-serif",
+            fontSize: '19pt',
+            color: '#111827',
+          },
+        },
+      ],
+    });
+  }
+  if (args.description) {
+    paragraphs.push({
+      textRuns: [
+        {
+          value: args.description,
+          textStyle: {
+            fontFamily: "'Segoe UI', wf_segoe-ui_normal, helvetica, arial, sans-serif",
+            fontSize: '10.5pt',
+            color: '#6B7280',
+          },
+        },
+      ],
+    });
+  }
+  // --paragraph is raw (no styling).
+  for (const p of args.paragraphs) {
+    paragraphs.push({ textRuns: [{ value: p }] });
+  }
+  if (paragraphs.length === 0) {
+    fail('textbox needs at least one of --title, --description, or --paragraph');
+  }
+  return {
+    objects: {
+      general: [{ properties: { paragraphs } }],
+    },
+  };
+}
+
+function buildSlicerObjects(args) {
+  const mode = args.slicerMode || 'basic';
+  const spec = SLICER_MODES[mode];
+  if (!spec) fail(`unknown --slicer-mode: ${mode}. Valid: ${Object.keys(SLICER_MODES).join(', ')}`);
+  const objects = {
+    data: [{ properties: { mode: { expr: { Literal: { Value: `'${spec.mode}'` } } } } }],
+  };
+  if (spec.orientation != null) {
+    objects.general = [
+      { properties: { orientation: { expr: { Literal: { Value: String(spec.orientation) } } } } },
+    ];
+  }
+  return { objects };
+}
+
+function buildContainerTitle(args) {
+  if (args.noTitle) {
+    return {
+      title: [{ properties: { show: { expr: { Literal: { Value: 'false' } } } } }],
+    };
+  }
+  if (args.title) {
+    return {
+      title: [
+        {
+          properties: {
+            show: { expr: { Literal: { Value: 'true' } } },
+            text: { expr: { Literal: { Value: `'${escapePbiLiteral(args.title)}'` } } },
+          },
+        },
+      ],
+    };
+  }
+  return null; // default: don't emit visualContainerObjects.title
+}
+
+function escapePbiLiteral(s) {
+  // PBI literal strings use single-quote delimiters — escape internal quotes,
+  // and collapse newlines/tabs to single spaces so the resulting literal
+  // stays on one line (PBI doesn't parse multi-line literals for these fields).
+  return String(s)
+    .replace(/[\r\n\t]+/g, ' ')
+    .replace(/'/g, "''");
+}
+
+// ---------------------------------------------------------------------------
+// File I/O — atomic write (same pattern as apply-theme.js)
+// ---------------------------------------------------------------------------
+
+function writeJsonAtomic(filePath, data) {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+  if (fs.existsSync(filePath)) fs.copyFileSync(filePath, `${filePath}.bak`);
+  const tmp = `${filePath}.tmp`;
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n');
+    fs.renameSync(tmp, filePath);
+  } catch (err) {
+    try {
+      fs.unlinkSync(tmp);
+    } catch (_) {
+      /* best-effort */
+    }
+    throw err;
+  }
+}
+
+function readExistingVisuals(pageDir) {
+  const visualsDir = path.join(pageDir, 'visuals');
+  if (!fs.existsSync(visualsDir)) return [];
+  const out = [];
+  for (const name of fs.readdirSync(visualsDir)) {
+    const vp = path.join(visualsDir, name, 'visual.json');
+    if (!fs.existsSync(vp)) continue;
+    try {
+      const data = JSON.parse(fs.readFileSync(vp, 'utf8'));
+      out.push({ name, data, path: vp });
+    } catch (_) {
+      // Skip malformed visuals; don't block creation.
+    }
+  }
+  return out;
+}
+
+function nextInt(existing, key) {
+  let max = -1;
+  for (const v of existing) {
+    const pos = v.data && v.data.position;
+    if (pos && typeof pos[key] === 'number' && pos[key] > max) max = pos[key];
+  }
+  return max + 1;
+}
+
+// ---------------------------------------------------------------------------
+// main()
+// ---------------------------------------------------------------------------
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help || process.argv.length === 2) {
+    printHelp();
+    return;
+  }
+  if (args.listTypes) {
+    printTypes();
+    return;
+  }
+
+  // ---- required args
+  if (!args.reportPath) fail('--report-path is required');
+  if (!args.page) fail('--page is required');
+  if (!args.type) fail('--type is required (use --list-types to see options)');
+
+  // ---- type validation with friendly errors for known non-native aliases
+  if (KNOWN_NON_NATIVE_TYPES[args.type]) {
+    fail(KNOWN_NON_NATIVE_TYPES[args.type]);
+  }
+  const def = NATIVE_VISUAL_TYPES[args.type];
+  if (!def) {
+    fail(`unknown visualType: ${args.type}. Run --list-types for the allowlist.`);
+  }
+
+  // ---- resolve paths
+  const reportPath = path.resolve(args.reportPath);
+  const pageDir = path.join(reportPath, 'definition', 'pages', args.page);
+  if (!fs.existsSync(pageDir)) {
+    fail(`page not found: ${pageDir}. Create the page first (e.g. via pbi report add-page or create-page.js).`);
+  }
+
+  // ---- auto-generate name if omitted
+  let name = args.name;
+  if (!name) {
+    const existing = readExistingVisuals(pageDir);
+    let n = existing.length;
+    let candidate;
+    do {
+      candidate = `${args.type}_${n}`;
+      n += 1;
+    } while (existing.some((v) => v.name === candidate));
+    name = candidate;
+  }
+
+  const visualDir = path.join(pageDir, 'visuals', name);
+  const visualJsonPath = path.join(visualDir, 'visual.json');
+  if (fs.existsSync(visualJsonPath)) {
+    fail(
+      `visual already exists: ${visualJsonPath}. Delete the folder or use a different --name (got: ${name}).`
+    );
+  }
+
+  // ---- canonicalize bindings against role names
+  const bindingsCanonical = {};
+  for (const [inputRole, refs] of Object.entries(args.bindings)) {
+    // Textbox has no roles — reject bindings early.
+    if (args.type === 'textbox') {
+      fail('textbox does not accept --bind. Use --title, --description, or --paragraph.');
+    }
+    const canonical = canonicalRoleName(def.roles, inputRole);
+    if (!canonical) {
+      const valid = Object.keys(def.roles).join(', ') || '(none)';
+      fail(`--bind role "${inputRole}" is not valid for --type ${args.type}. Valid roles: ${valid}.`);
+    }
+    const spec = def.roles[canonical];
+    if (refs.length > 1 && !spec.multi) {
+      fail(`role ${canonical} does not accept multiple bindings (got ${refs.length}).`);
+    }
+    bindingsCanonical[canonical] = refs;
+  }
+
+  // ---- check required roles (textbox/cardVisual exceptions)
+  if (args.type !== 'textbox') {
+    for (const [role, spec] of Object.entries(def.roles)) {
+      if (spec.required && !(role in bindingsCanonical)) {
+        fail(`required role missing: --bind ${role.toLowerCase()}=Table[Field]`);
+      }
+    }
+  }
+
+  // ---- build position
+  const existing = readExistingVisuals(pageDir);
+  const autoZ = nextInt(existing, 'z');
+  const autoTabOrder = nextInt(existing, 'tabOrder');
+
+  // Size defaults: cards are smaller, charts bigger.
+  const defaultSize = ['card', 'cardVisual', 'kpi', 'gauge', 'multiRowCard'].includes(args.type)
+    ? { w: 280, h: 120 }
+    : { w: 400, h: 300 };
+
+  const position = {
+    x: args.x != null ? args.x : 0,
+    y: args.y != null ? args.y : 0,
+    z: args.z != null ? args.z : autoZ,
+    height: args.height != null ? args.height : defaultSize.h,
+    width: args.width != null ? args.width : defaultSize.w,
+    tabOrder: args.tabOrder != null ? args.tabOrder : autoTabOrder,
+  };
+
+  // ---- assemble visual.json
+  const visual = { visualType: args.type };
+
+  if (args.type === 'textbox') {
+    Object.assign(visual, buildTextbox(args));
+  } else {
+    visual.query = { queryState: buildQueryState(def, bindingsCanonical) };
+    if (def.defaults && def.defaults.query) {
+      Object.assign(visual.query, def.defaults.query);
+    }
+    if (args.type === 'slicer') {
+      Object.assign(visual, buildSlicerObjects(args));
+    }
+  }
+
+  // drillFilterOtherVisuals only makes sense for data visuals; textboxes
+  // have no query so there's nothing to filter — omit the flag entirely
+  // to keep the written shape minimal.
+  if (args.type !== 'textbox') {
+    visual.drillFilterOtherVisuals = true;
+  }
+
+  // Container defaults (cardVisual spawns an empty visualContainerObjects).
+  if (def.defaults && def.defaults.visualContainerObjects !== undefined) {
+    visual.visualContainerObjects = def.defaults.visualContainerObjects;
+  }
+
+  if (args.type === 'textbox') {
+    // Textbox chrome is always hidden — the paragraphs ARE the content,
+    // and --title/--description are paragraph shortcuts (see buildTextbox),
+    // not container title overrides. Emitting container title here on top
+    // of the inner title paragraph causes a double-render in PBI Desktop.
+    visual.visualContainerObjects = {
+      title: [{ properties: { show: { expr: { Literal: { Value: 'false' } } } } }],
+      background: [{ properties: { show: { expr: { Literal: { Value: 'false' } } } } }],
+      border: [{ properties: { show: { expr: { Literal: { Value: 'false' } } } } }],
+      dropShadow: [{ properties: { show: { expr: { Literal: { Value: 'false' } } } } }],
+    };
+  } else {
+    // For data visuals, --title / --no-title control the container title.
+    const titleBlock = buildContainerTitle(args);
+    if (titleBlock) {
+      visual.visualContainerObjects = visual.visualContainerObjects || {};
+      Object.assign(visual.visualContainerObjects, titleBlock);
+    }
+  }
+
+  const visualJson = {
+    $schema: VISUAL_SCHEMA,
+    name,
+    position,
+    visual,
+  };
+
+  // ---- write
+  try {
+    writeJsonAtomic(visualJsonPath, visualJson);
+  } catch (err) {
+    fail(`failed to write ${visualJsonPath}: ${err.message}`, 2);
+  }
+
+  process.stdout.write(
+    [
+      `create-visual: ✓ created ${args.type}`,
+      `  name:    ${name}`,
+      `  page:    ${args.page}`,
+      `  file:    ${visualJsonPath}`,
+      `  pos:     x=${position.x} y=${position.y} w=${position.width} h=${position.height}`,
+      '',
+    ].join('\n')
+  );
+}
+
+// Export internals for unit tests.
+module.exports = {
+  NATIVE_VISUAL_TYPES,
+  KNOWN_NON_NATIVE_TYPES,
+  SLICER_MODES,
+  parseArgs,
+  parseFieldRef,
+  buildProjection,
+  canonicalRoleName,
+  buildQueryState,
+  buildTextbox,
+  buildSlicerObjects,
+  buildContainerTitle,
+  escapePbiLiteral,
+};
+
+// Only run main() when invoked as script (not when required from tests).
+if (require.main === module) {
+  main();
+}