@khester/create-dynamics-app 3.0.0 → 3.2.0

package/templates/grid-customizer/README.md

@@ -1,28 +1,118 @@
-# {{componentName}} (grid customizer)
+# {{componentName}} — Power Apps grid customizer
 
-A Dynamics 365 **editable-grid customizer** — maps column data types / logical names to custom Fluent
-UI v9 cell renderers (status badge, currency, date, progress).
+A **PCF virtual control** that overrides how Microsoft's editable grid (PowerAppsOneGrid)
+paints its cells: option sets become coloured badges, currency is right-aligned and coloured
+by sign, yes/no becomes a tick or cross, and nominated numeric columns become progress bars.
 
-## Develop
+It is **not a grid**. It renders nothing of its own — it hands the platform's grid a map of
+cell renderers and the grid does the drawing.
+
+```
+OneGrid ──(bound EventName)──▶ {{componentName}}.init
+                              └─ factory.fireEvent(eventName, { cellRendererOverrides, cellEditorOverrides })
+OneGrid ◀─────────────────────┘  then calls those overrides while painting each cell
+```
+
+## Quick start
 
 ```bash
 npm install
-npm run build      # webpack → dist/{{projectName}}.js (UMD)
-npm run typecheck  # tsc --noEmit
+
+npm run dev      # ★ the working local loop — http://localhost:8182
+npm run build    # pcf-scripts build → out/controls/{{componentName}}/
 ```
 
-## Customize
+`npm start` (the stock `pcf-scripts` harness) will load the control and show a **blank
+canvas**. That is correct, not a bug: the harness has no OneGrid, so nothing ever calls the
+overrides. `npm run dev` runs a stand-in grid that calls them exactly as the platform does.
+
+## Local development
+
+`npm run dev` serves the harness in `dev/`:
 
-Edit `src/GridCustomizer.ts` to map columns to renderers, and add renderers in
-`src/cell-renderers.tsx`:
+| Data source | What it gives you |
+|---|---|
+| **Mock** (default) | One column per overridden data type, including an unmapped status label so you can see the derived-colour fallback. No org needed. |
+| **Live** | Real rows **and real column data types** from your org, read from entity metadata. |
 
-```ts
-cellRendererOverrides = {
-  OptionSet: StatusBadgeRenderer,   // by data type
-  prioritycode: StatusBadgeRenderer // by column logical name
-};
+Live mode needs one line of config plus an Azure login:
+
+```bash
+cp env.local.example .env.local     # set VITE_DYNAMICS_URL=https://<org>.crm.dynamics.com
+az login
+npm run dev
 ```
 
+The dev server acquires and refreshes the bearer token **in-process, server-side** — it is
+never exposed to the browser bundle. See `env.local.example` for the full contract.
+
+> **Why Live mode reads metadata.** A customizer is dispatched purely by `ColumnDataType`.
+> Currency and Decimal are both `number` on the wire; Picklist and Integer are too. Guessing
+> the type from a sample value would exercise the wrong handler, so the harness reads the
+> real `AttributeType` — the same classification the platform uses.
+
+## Customizing it
+
+| File | What it is for |
+|---|---|
+| `{{componentName}}/customizers/config.ts` | **Start here.** Status colours, which columns get progress bars, currency colours. |
+| `{{componentName}}/customizers/cells.tsx` | What each custom cell looks like. |
+| `{{componentName}}/customizers/CellRendererOverrides.tsx` | Which data type maps to which cell, and how to scope one to a single column. |
+| `{{componentName}}/customizers/CellEditorOverrides.tsx` | Edit-mode overrides. Empty by default — the built-in editors are good. |
+| `{{componentName}}/types.ts` | The platform contract. Vendored: Microsoft ships no package for it. |
+
+Three rules the compiler cannot enforce for you:
+
+1. **Override keys are column DATA TYPES, never logical names.** `{ statuscode: … }` never
+   fires. Register under `OptionSet` and narrow with
+   `params.colDefs[params.columnIndex].name`.
+2. **Return `undefined` to fall through** to the grid's own renderer. Returning an empty
+   element blanks the cell instead.
+3. **Render `props.formattedValue`, not `props.value`.** `formattedValue` is already
+   localized, currency-symbolled and resolved to option labels; `value` is raw.
+
+### There is no maker-facing configuration
+
+A grid customizer **cannot receive `usage="input"` properties**. The grid's *Customizer
+control* field references this control by name only, with nowhere to put a value, so any
+input property is `undefined` at runtime — and reading `.raw` off it throws inside `init()`,
+which the host silently swallows. Configure in `config.ts` and redeploy.
+
+If you need rules that change without a redeploy, read them from a Dataverse **environment
+variable** in `init()`. That requires `<uses-feature name="WebAPI" required="true" />` in the
+manifest — without it `context.webAPI` exists but throws. (If you have the `claude-workspace`
+checkout, `shared/pcf-gallery/controls/color-grid` is a complete worked example, including
+throttled re-reads so an already-open grid picks up a change.)
+
 ## Deploy
 
-Bundle and register `dist/{{projectName}}.js` on the grid control's customizer property.
+A customizer is a **PCF control**, so it ships in a solution — not as a web resource.
+
+```bash
+# 1. package (from the workspace root)
+msft/04-dynamics/scripts/deploy/package-control.sh \
+  --source ./{{projectName}} --version 1.0.0 --output ./dist
+
+# 2. import
+pac solution import --path ./dist/{{componentName}}_1.0.0.zip --publish-changes
+```
+
+Then bind it to a table's grid by setting `GridCustomizerControlFullName` on that table's
+PowerAppsOneGrid configuration (a `customcontroldefaultconfigs` record) to
+`<prefix>_{{namespace}}.{{componentName}}` — `org-bootstrap.sh`'s `controls` + `bindings`
+steps do this, or set **Customizer control** in the table's grid properties in the maker
+portal.
+
+★ **Bump `version=` in `ControlManifest.Input.xml` on every change.** The platform caches by
+`(namespace.constructor, version)`; without a bump it keeps serving the previous build and
+you will debug a fix that was never deployed.
+
+## Platform versions
+
+`React 16.14.0` + `Fluent 8.121.1`, both declared as `<platform-library>` and pinned exactly
+in `package.json`. A virtual control returns a ReactElement that the **platform** renders, so
+compiled-against must equal served. Measured live 2026-08-02: the model-driven host serves
+React 17.0.2 under the `Reactv16` alias, defines no `Reactv18`, and serves Fluent 8.121.1
+**and** 9.68.0. v8 is used here because the cells render inside OneGrid's own v8 React tree —
+a v9 cell would need its own `FluentProvider` and would be themed independently of the grid
+around it. The manifest carries the full measurement.

package/templates/grid-customizer/dev/harness/MockGrid.tsx

@@ -0,0 +1,165 @@
+import * as React from 'react';
+import type {
+  CellRendererOverrides,
+  CellRendererProps,
+  ColumnDataType,
+  ColumnDefinition,
+  GetRendererParams,
+} from '../../{{componentName}}/types';
+
+/**
+ * A stand-in for Microsoft's PowerAppsOneGrid, present only so the customizer has something
+ * to customize during local development.
+ *
+ * ★ Its whole value is that it calls the overrides EXACTLY the way the real grid does:
+ *   - looks the handler up by the column's `ColumnDataType`, never by its logical name;
+ *   - passes `(CellRendererProps, GetRendererParams)`, with `colDefs` + `columnIndex` so a
+ *     handler can narrow to one column;
+ *   - treats a `null`/`undefined` return as "use the default renderer" rather than as an
+ *     empty cell.
+ *
+ * If a renderer works here and not in the org, the difference is the platform (versions,
+ * bindings, publish state) — not the contract. It deliberately does NOT reimplement sorting,
+ * filtering, selection, paging or inline editing: the real grid owns all of those, and a
+ * fake one that drifted from them would be worse than none.
+ */
+
+/** One column of the fake grid: the platform's `ColumnDefinition` plus a display width. */
+export interface HarnessColumn {
+  name: string;
+  displayName: string;
+  dataType: ColumnDataType;
+  width?: number;
+}
+
+/** One cell: the raw value the platform would pass, and the text it would have painted. */
+export interface HarnessCell {
+  raw: unknown;
+  formatted: string;
+}
+
+/** One row, keyed by column logical name. */
+export type HarnessRow = Record<string, HarnessCell>;
+
+export interface MockGridProps {
+  columns: HarnessColumn[];
+  rows: HarnessRow[];
+  overrides: CellRendererOverrides;
+  /** Row height in px — the real grid gives cells a fixed height, so mirror that. */
+  rowHeight?: number;
+}
+
+const ROW_HEIGHT = 42;
+const BORDER = '#edebe9';
+
+const headerCell: React.CSSProperties = {
+  textAlign: 'left',
+  fontSize: 12,
+  fontWeight: 600,
+  color: '#323130',
+  padding: '0 8px',
+  height: 36,
+  borderBottom: `1px solid ${BORDER}`,
+  whiteSpace: 'nowrap',
+};
+
+export const MockGrid: React.FC<MockGridProps> = ({
+  columns,
+  rows,
+  overrides,
+  rowHeight = ROW_HEIGHT,
+}) => {
+  // Built once per render and shared by every cell, exactly as the grid does — a handler
+  // that inspects sibling columns sees the same array the platform would give it.
+  const colDefs: ColumnDefinition[] = columns.map((c, i) => ({
+    name: c.name,
+    displayName: c.displayName,
+    dataType: c.dataType,
+    isPrimary: i === 0,
+  }));
+
+  if (columns.length === 0) {
+    return (
+      <div style={{ color: '#605e5c', fontSize: 13, padding: 8 }}>
+        No columns — pick a data source and load.
+      </div>
+    );
+  }
+
+  return (
+    <div style={{ border: `1px solid ${BORDER}`, background: '#fff', overflowX: 'auto' }}>
+      <table style={{ borderCollapse: 'collapse', width: '100%', tableLayout: 'fixed' }}>
+        <colgroup>
+          {columns.map((c) => (
+            <col key={c.name} style={{ width: c.width ? `${c.width}px` : 'auto' }} />
+          ))}
+        </colgroup>
+        <thead>
+          <tr>
+            {columns.map((c) => (
+              <th key={c.name} style={headerCell} title={`${c.name} — ${c.dataType}`}>
+                {c.displayName}
+                <span style={{ color: '#a19f9d', fontWeight: 400 }}> · {c.dataType}</span>
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {rows.map((row, rowIndex) => (
+            <tr key={rowIndex}>
+              {columns.map((col, columnIndex) => {
+                const cell = row[col.name] ?? { raw: undefined, formatted: '' };
+
+                const props: CellRendererProps = {
+                  value: cell.raw,
+                  formattedValue: cell.formatted,
+                  columnDataType: col.dataType,
+                  rowHeight,
+                  columnEditable: false,
+                  isRightAligned:
+                    col.dataType === 'Currency' ||
+                    col.dataType === 'Decimal' ||
+                    col.dataType === 'Integer' ||
+                    col.dataType === 'FloatingPoint',
+                  // Part of the contract, unused by a read-only harness. A renderer that
+                  // calls it in the org would still compile against the same signature.
+                  onValueChange: () => undefined,
+                };
+
+                const params: GetRendererParams = {
+                  colDefs,
+                  columnIndex,
+                  rowData: { __rec_id: String(rowIndex) },
+                };
+
+                const handler = overrides[col.dataType];
+                const custom = handler ? handler(props, params) : undefined;
+
+                return (
+                  <td
+                    key={col.name}
+                    style={{
+                      height: rowHeight,
+                      padding: '0 8px',
+                      borderBottom: `1px solid ${BORDER}`,
+                      fontSize: 13,
+                      overflow: 'hidden',
+                      textOverflow: 'ellipsis',
+                      whiteSpace: 'nowrap',
+                      // The real grid right-aligns numerics itself; a custom renderer that
+                      // returns undefined must therefore still land in the default layout.
+                      textAlign: props.isRightAligned && !custom ? 'right' : 'left',
+                    }}
+                  >
+                    {/* ★ null/undefined => the grid's own rendering, not an empty cell. */}
+                    {custom ?? cell.formatted}
+                  </td>
+                );
+              })}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+};

package/templates/grid-customizer/dev/harness/dataverse.ts

@@ -0,0 +1,168 @@
+import { apiFetch, toHttpError } from '@dataverse-kit/pcf-dev-harness/shell';
+import type { ColumnDataType } from '../../{{componentName}}/types';
+import type { HarnessColumn, HarnessRow } from './MockGrid';
+
+/**
+ * TIER 2 of the dev harness — the {{componentName}}-specific live-org read.
+ *
+ * The reusable parts (shell, proxy, token refresh, `apiFetch`'s one-shot 401/403 retry) come
+ * from `@dataverse-kit/pcf-dev-harness`. This file supplies what only THIS control needs,
+ * and it is not the rows: it is the **column data types**.
+ *
+ * ★ A customizer is dispatched entirely by `ColumnDataType`. Guessing the type from a sample
+ * value cannot work — a Currency and a Decimal are both `number` over the wire, a Picklist
+ * and an Integer are both `number`, a DateOnly and a DateAndTime are both strings — so the
+ * harness would exercise the wrong handler (or none) and tell you nothing. It therefore
+ * reads the real `AttributeType` from entity metadata, the same classification the platform
+ * uses when it decides which override to call.
+ *
+ * All calls go through the same-origin `/api/data` proxy in `vite.config.ts`, which injects
+ * the bearer token server-side — no token ever reaches the browser. READ-ONLY: the harness
+ * never writes, so there is no save counterpart.
+ */
+
+export type { HttpError } from '@dataverse-kit/pcf-dev-harness/shell';
+
+/** What the grid contract calls a column, keyed by Dataverse's `AttributeTypeCode`. */
+const ATTRIBUTE_TYPE_TO_COLUMN_TYPE: Readonly<Record<string, ColumnDataType>> = {
+  // The three that actually drive this template's overrides.
+  Picklist: 'OptionSet',
+  State: 'OptionSet',
+  Status: 'OptionSet',
+  Boolean: 'TwoOptions',
+  Money: 'Currency',
+  Decimal: 'Decimal',
+  Double: 'FloatingPoint',
+  // Everything below is mapped for completeness, so a column you add an override for later
+  // is dispatched correctly without touching this file.
+  Integer: 'Integer',
+  BigInt: 'Integer',
+  String: 'Text',
+  Memo: 'TextArea',
+  DateTime: 'DateAndTime',
+  Lookup: 'Lookup',
+  Customer: 'Customer',
+  Owner: 'Owner',
+  Virtual: 'Text',
+  Uniqueidentifier: 'Text',
+  EntityName: 'Text',
+};
+
+/**
+ * ★ Lookup-typed columns are mapped above but cannot be LOADED by this harness. Dataverse
+ * requires the `_<name>_value` form in `$select` for a lookup, while the metadata call wants
+ * the plain logical name — so a binding that lists one gets a clean metadata read and then a
+ * 400 on the row fetch. Drop lookups from the Columns box; the mapping is here so that a
+ * lookup override you add later dispatches correctly in the org, where the platform supplies
+ * the columns rather than you typing them.
+ */
+
+interface AttributeMetadata {
+  LogicalName: string;
+  AttributeType: string;
+  DisplayName?: { UserLocalizedLabel?: { Label?: string } | null } | null;
+}
+
+/** OData annotation carrying the text the platform itself would paint in the cell. */
+const FORMATTED = '@OData.Community.Display.V1.FormattedValue';
+
+/** Resolve an entity SET name (`accounts`) to its logical name (`account`) for metadata. */
+async function resolveLogicalName(entitySetName: string): Promise<string> {
+  const params = new URLSearchParams({
+    $select: 'LogicalName',
+    $filter: `EntitySetName eq '${entitySetName.replace(/'/g, "''")}'`,
+  });
+  const res = await apiFetch(`/api/data/v9.2/EntityDefinitions?${params}`);
+  if (!res.ok) throw await toHttpError(res);
+  const body = (await res.json()) as { value?: { LogicalName: string }[] };
+  const logicalName = body.value?.[0]?.LogicalName;
+  if (!logicalName) {
+    throw new Error(`No table has entity set name "${entitySetName}".`);
+  }
+  return logicalName;
+}
+
+/**
+ * Read `AttributeType` + display label for every requested column, in the order given.
+ *
+ * Fetches the table's WHOLE attribute set (~200 rows for `account`) rather than filtering to
+ * the requested columns. Deliberate: an `or`-chain built from user-typed field names is the
+ * one place in this file where input would reach an OData filter expression, and the saving
+ * is a few hundred KB on a dev-only call made once per Load.
+ */
+async function fetchColumnTypes(
+  logicalName: string,
+  fields: string[],
+): Promise<HarnessColumn[]> {
+  const params = new URLSearchParams({ $select: 'LogicalName,AttributeType,DisplayName' });
+  const res = await apiFetch(
+    `/api/data/v9.2/EntityDefinitions(LogicalName='${logicalName}')/Attributes?${params}`,
+  );
+  if (!res.ok) throw await toHttpError(res);
+  const body = (await res.json()) as { value?: AttributeMetadata[] };
+
+  const byName = new Map((body.value ?? []).map((a) => [a.LogicalName, a]));
+  return fields.map((f, i) => {
+    const meta = byName.get(f);
+    return {
+      name: f,
+      displayName: meta?.DisplayName?.UserLocalizedLabel?.Label ?? f,
+      // An unknown or missing attribute falls back to Text — it then renders through the
+      // default path, which is the honest outcome for a column we cannot classify.
+      dataType: (meta && ATTRIBUTE_TYPE_TO_COLUMN_TYPE[meta.AttributeType]) ?? 'Text',
+      width: i === 0 ? 220 : 160,
+    };
+  });
+}
+
+/**
+ * Fetch `top` rows of `select` columns, with each column's real data type attached.
+ *
+ * @param entitySetName plural set name, e.g. `accounts`
+ * @param select        comma-separated logical names, e.g. `name,revenue,statuscode`
+ * @param top           max rows
+ */
+export async function fetchGridData(
+  entitySetName: string,
+  select: string,
+  top: string,
+): Promise<{ columns: HarnessColumn[]; rows: HarnessRow[] }> {
+  const fields = select
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+  if (fields.length === 0) throw new Error('Enter at least one column.');
+
+  const logicalName = await resolveLogicalName(entitySetName);
+  const columns = await fetchColumnTypes(logicalName, fields);
+
+  const params = new URLSearchParams({ $select: fields.join(','), $top: top || '25' });
+  const res = await apiFetch(`/api/data/v9.2/${entitySetName}?${params}`, {
+    // Ask for the formatted-value annotations the deployed control renders.
+    headers: { Prefer: 'odata.include-annotations="OData.Community.Display.V1.FormattedValue"' },
+  });
+  if (!res.ok) throw await toHttpError(res);
+  const body = (await res.json()) as { value?: Record<string, unknown>[] };
+
+  const rows: HarnessRow[] = (body.value ?? []).map((record) => {
+    const row: HarnessRow = {};
+    for (const f of fields) {
+      const raw = record[f];
+      const formatted = record[`${f}${FORMATTED}`];
+      row[f] = {
+        raw: raw ?? undefined,
+        // No annotation means the value needs no formatting (plain text, a number the
+        // platform shows as-is) — stringify the raw value, as the grid would.
+        formatted:
+          formatted !== undefined && formatted !== null
+            ? String(formatted)
+            : raw === undefined || raw === null
+              ? ''
+              : String(raw),
+      };
+    }
+    return row;
+  });
+
+  return { columns, rows };
+}

package/templates/grid-customizer/dev/index.html

@@ -0,0 +1,20 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{componentName}} – Dev Harness</title>
+    <style>
+      html, body, #root {
+        margin: 0;
+        padding: 0;
+        height: 100%;
+        font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./main.tsx"></script>
+  </body>
+</html>