@khester/create-dynamics-app 3.1.0 → 3.2.0

package/templates/grid-customizer/vite.config.ts

@@ -0,0 +1,64 @@
+import { defineConfig, loadEnv } from 'vite';
+import react from '@vitejs/plugin-react';
+import * as path from 'path';
+import { dataverseProxy } from '@dataverse-kit/pcf-dev-harness/node';
+
+/**
+ * Live-org dev harness for {{componentName}} — `npm run dev` → http://localhost:8182
+ *
+ * WHY THIS EXISTS, given `npm start` already runs the Microsoft PCF harness:
+ * a grid customizer renders NOTHING of its own. `pcf-scripts start` will load this control
+ * happily and show an empty canvas, because the thing being customized — Microsoft's
+ * PowerAppsOneGrid — is not present in that harness and never calls the overrides. So the
+ * stock harness can tell you the control instantiates, and nothing else.
+ *
+ * `dev/harness/MockGrid.tsx` fills that gap: a minimal grid that calls the SAME
+ * `cellRendererOverrides` map, with the same `(props, params)` arguments and the same
+ * fall-through-on-undefined rule as OneGrid. Two data sources (see `dev/main.tsx`):
+ *   - Mock — a hard-coded recordset covering each overridden data type. Needs no org.
+ *   - Live — real rows AND real column data types from Dataverse metadata, through the
+ *            same-origin `/api/data` proxy. Enabled when VITE_DYNAMICS_URL is set.
+ *
+ * The proxy and its in-process Azure-CLI token refresh come from
+ * `@dataverse-kit/pcf-dev-harness/node`: the bearer token is injected SERVER-SIDE and never
+ * reaches the browser. `az login` + `npm run dev` is enough — `npm run auth:token` only
+ * writes an optional static fallback.
+ */
+export default defineConfig(({ mode }) => {
+  // Read .env* from the PROJECT root (__dirname), not `root: 'dev'`. The empty prefix loads
+  // every var server-side (URL + tenant + any static token); `envPrefix` below still limits
+  // what can reach the client bundle.
+  const env = loadEnv(mode, __dirname, '');
+  const live = dataverseProxy({
+    dynamicsUrl: env.VITE_DYNAMICS_URL || '',
+    tenant: env.DYNAMICS_TENANT,
+    // Array: `.env.local` is the documented file, `.env` is tolerated as a fallback so a
+    // token written by a different tool still works. First file defining DYNAMICS_TOKEN wins.
+    envFile: [path.resolve(__dirname, '.env.local'), path.resolve(__dirname, '.env')],
+    pluginName: '{{componentName}}-live-token',
+  });
+
+  return {
+    root: 'dev',
+    // .env* live at the project root, not the `dev` root, so client code still sees
+    // import.meta.env.VITE_DYNAMICS_URL (which gates Live mode).
+    envDir: __dirname,
+    // SECURITY: the bearer token is acquired server-side by dataverseProxy and is never put
+    // in a VITE_-prefixed var, so Vite cannot inline it into the client bundle. envPrefix
+    // narrows client exposure to VITE_DYNAMICS_URL alone; the static fallback DYNAMICS_TOKEN
+    // is deliberately unprefixed for the same reason.
+    envPrefix: 'VITE_DYNAMICS_URL',
+    // jsxRuntime: 'classic' — the automatic runtime emits `react/jsx-runtime`, which does not
+    // exist in React 16. This control is pinned to 16.14.0 to match the platform's Reactv16
+    // global, and tsconfig sets `"jsx": "react"` (classic) for the same reason.
+    plugins: [react({ jsxRuntime: 'classic' }), live.plugin],
+    server: {
+      // 8182, because `pcf-scripts start` owns 8181 — the two harnesses can run side by side.
+      // strictPort so a clash fails loudly instead of silently moving to another port.
+      port: 8182,
+      strictPort: true,
+      open: true,
+      proxy: live.proxy,
+    },
+  };
+});

package/templates/grid-customizer/{{componentName}}/ControlManifest.Input.xml

@@ -0,0 +1,63 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<manifest>
+  <control namespace="{{namespace}}" constructor="{{componentName}}" version="1.0.0" display-name-key="{{namespace}}_{{componentName}}" description-key="{{namespace}}_{{componentName}}_Desc" control-type="virtual">
+    <!--
+      ★ A GRID CUSTOMIZER IS NOT A GRID. It renders nothing of its own.
+
+      It is bound to Microsoft's PowerAppsOneGrid via that grid's
+      `GridCustomizerControlFullName` parameter. On init the platform hands it an event
+      name through the BOUND `EventName` property below; the control answers by calling
+      `context.factory.fireEvent(eventName, customizer)` with an object of cell renderer /
+      editor overrides. OneGrid then calls those overrides while painting its own cells.
+
+      Consequences that shape this whole template:
+        • `EventName` is the ONLY property. It must be `usage="bound"` and `required="true"`.
+        • `updateView` returns an empty Fragment — see index.ts.
+        • ★ A customizer CANNOT receive maker-set `usage="input"` properties. The grid's
+          "Customizer control" field references this control by NAME only, with nowhere to
+          pass a value, so any input property is `undefined` at runtime — and reading `.raw`
+          off it throws inside init, which the host SWALLOWS (you get a silently missing
+          customizer, not an error). Configure via customizers/config.ts, or read a Dataverse
+          environment variable at runtime (see README).
+    -->
+    <property name="EventName" display-name-key="EventName" description-key="EventName_Desc" of-type="SingleLine.Text" usage="bound" required="true" />
+    <resources>
+      <code path="index.ts" order="1"/>
+      <!--
+        ★ These versions must EQUAL a version the PLATFORM ACTUALLY SERVES — not merely one
+        pcf-scripts accepts. pcf-scripts matches a {minVersion, maxVersion} row in its
+        PlatformLibraryVersions.json and remaps the bundle to that row's global alias, but it
+        never checks the runtime. Trusting the tool produces a green build and a dead control.
+
+        Measured on live model-driven pages (orge2e285aa, 2026-08-02):
+
+            Reactv16            = React 17.0.2   ← the alias says 16; the served React is 17.0.2
+            Reactv17            = undefined
+            Reactv18            = undefined      ← pcf-scripts HAS an 18.3.1 row; no org serves it
+            ReactDOMv16         = present
+            ReactDOMv18         = undefined
+            FluentUIReactv81211 = present        ← Fluent 8.121.1, loaded on every page
+            FluentUIReactv940   = present        ← Fluent 9.68.0 IS served (see below)
+            FluentUIReactv8290  = loaded ON DEMAND — appears only on a page hosting a control
+                                  that declares Fluent 8.29.0, which is how the injection works
+
+        16.14.0, not 17.0.2, is deliberate: the model-driven host serves 17.0.2 but the canvas
+        host serves 16.14.0, so 16.14.0 is the floor both satisfy.
+
+        ★ WHY v8 AND NOT v9, given the platform serves both. A customizer's elements are
+        rendered by OneGrid INSIDE OneGrid's own React tree, and OneGrid is Fluent v8. A v8
+        cell inherits the host's theme for free. A v9 cell would need its own <FluentProvider>
+        wrapper per cell to get Griffel styles + tokens, and would then be themed
+        independently of the grid it sits in. v8 is the contract here.
+
+        A virtual control CANNOT bundle its own React: it returns a ReactElement that the
+        PLATFORM renders with the PLATFORM's React, so a second React instance breaks it.
+        That is why react/react-dom and @fluentui/react are pinned EXACTLY in package.json to
+        the versions declared here — compiled-against must equal served.
+      -->
+      <platform-library name="React" version="16.14.0" />
+      <platform-library name="Fluent" version="8.121.1" />
+      <resx path="strings/{{componentName}}.1033.resx" version="1.0.0" />
+    </resources>
+  </control>
+</manifest>

package/templates/grid-customizer/{{componentName}}/customizers/CellEditorOverrides.tsx

@@ -0,0 +1,38 @@
+import type { CellEditorOverrides } from '../types';
+
+/**
+ * Cell EDITOR overrides — what a cell becomes when the user starts editing it.
+ *
+ * Empty by default: OneGrid's built-in editors already handle every column type correctly,
+ * including the lookup search and option-set pickers that are genuinely hard to reimplement.
+ * Override only where the default is wrong for your data.
+ *
+ * The keys and the fall-through rule are identical to `CellRendererOverrides`: key by
+ * `ColumnDataType`, narrow to a column with `editorParams.colDefs[editorParams.columnIndex]`,
+ * and return `undefined` to keep the platform editor.
+ *
+ * A worked example — clamp a percentage column to 0–100:
+ *
+ * ```tsx
+ * import * as React from 'react';
+ * import { SpinButton } from '@fluentui/react';
+ *
+ * export const cellEditorOverrides: CellEditorOverrides = {
+ *   Decimal: (defaultProps, editorParams) => {
+ *     const name = editorParams.colDefs[editorParams.columnIndex]?.name;
+ *     if (name !== 'dvk_percentcomplete') return undefined;
+ *     return (
+ *       <SpinButton
+ *         min={0}
+ *         max={100}
+ *         step={5}
+ *         defaultValue={String(defaultProps.value ?? 0)}
+ *         // Commit through onChange; the grid writes the value back to the record.
+ *         onChange={(_e, v) => defaultProps.onChange(Number(v ?? 0))}
+ *       />
+ *     );
+ *   },
+ * };
+ * ```
+ */
+export const cellEditorOverrides: CellEditorOverrides = {};

package/templates/grid-customizer/{{componentName}}/customizers/CellRendererOverrides.tsx

@@ -0,0 +1,109 @@
+import * as React from 'react';
+import type { CellRendererOverrides, CellRendererProps, GetRendererParams } from '../types';
+import { BooleanCell, CurrencyCell, ProgressCell, StatusBadgeCell } from './cells';
+import { PROGRESS_COLUMNS, toNumber } from './config';
+
+/**
+ * The renderer map handed to OneGrid.
+ *
+ * ★ Three contract rules, each of which silently produces "my customizer does nothing" when
+ * broken:
+ *
+ *  1. **Keys are COLUMN DATA TYPES, never column logical names.** A `{ statuscode: … }`
+ *     entry type-errors against `CellRendererOverrides` — and would simply never fire if it
+ *     were cast away. Scope to a single column INSIDE the handler, as `Decimal` does below.
+ *  2. **Return `undefined` to fall through** to the grid's own renderer. That is the opt-out
+ *     for a row or column this customizer has no opinion about — returning an empty element
+ *     instead blanks the cell.
+ *  3. **Render `props.formattedValue`, not `props.value`.** `value` is raw: an option-set
+ *     integer, an unrounded decimal, a UTC timestamp. `formattedValue` is what the platform
+ *     itself would have painted — already localized, already currency-symbolled, already
+ *     resolved to an option label.
+ */
+
+/** Per-instance knobs. Everything else is compile-time config in `./config`. */
+export interface RendererOptions {
+  /**
+   * Columns rendered as a progress bar. Defaults to `config.PROGRESS_COLUMNS`.
+   *
+   * Overridable so the dev harness can retarget the SAME override map at whatever columns
+   * you loaded, instead of shipping a second near-copy of the renderers that could drift
+   * from the one the org actually runs.
+   */
+  progressColumns?: readonly string[];
+}
+
+/** The column logical name for the cell currently being rendered. */
+function columnName(params: GetRendererParams): string | undefined {
+  return params.colDefs[params.columnIndex]?.name;
+}
+
+/** Text the grid would have shown, falling back to the raw value when there is no format. */
+function displayText(props: CellRendererProps): string {
+  if (props.formattedValue !== undefined && props.formattedValue !== null) {
+    return props.formattedValue;
+  }
+  return props.value === undefined || props.value === null ? '' : String(props.value);
+}
+
+/**
+ * True when the cell holds no value.
+ *
+ * ★ Every handler must check this FIRST and fall through. Dataverse columns are nullable —
+ * a Boolean added to a table with existing rows is `null` on all of them — and a renderer
+ * that coerces null (`value === true` → false) paints a definite answer for missing data.
+ * "No" and "not set" are different facts; the grid's own renderer draws the second correctly.
+ */
+function isEmpty(props: CellRendererProps): boolean {
+  return props.value === undefined || props.value === null;
+}
+
+/** Build the override map. `cellRendererOverrides` below is the configured singleton. */
+export function createCellRendererOverrides(
+  options: RendererOptions = {},
+): CellRendererOverrides {
+  const progressColumns = options.progressColumns ?? PROGRESS_COLUMNS;
+
+  return {
+    // Option sets and status/state columns → a coloured pill keyed off the option LABEL.
+    // An unset option set falls through: a badge with no text is just a coloured smudge.
+    OptionSet: (props) => {
+      if (isEmpty(props)) return undefined;
+      const label = displayText(props);
+      return label ? <StatusBadgeCell label={label} /> : undefined;
+    },
+
+    // Yes/no → tick or cross plus the platform's own label ("Yes"/"No", or the custom pair).
+    // ★ Falls through on null — otherwise a nullable Boolean renders the same grey cross as a
+    // genuine "No", which silently misrepresents the data.
+    TwoOptions: (props) => {
+      if (isEmpty(props)) return undefined;
+      return (
+        <BooleanCell on={props.value === true || props.value === 1} label={displayText(props)} />
+      );
+    },
+
+    // Money → right-aligned, red when negative. Falls through when the cell is empty so a
+    // blank amount stays blank rather than rendering a coloured "0".
+    Currency: (props) => {
+      const amount = toNumber(props.value);
+      if (amount === undefined) return undefined;
+      return <CurrencyCell amount={amount} formatted={displayText(props)} />;
+    },
+
+    // ★ The per-column pattern. Decimal is registered for the whole grid, but only the
+    // columns in `progressColumns` get a progress bar — everything else falls through to the
+    // default renderer. Without this narrowing, every decimal column in every grid this
+    // customizer is bound to would become a progress bar.
+    Decimal: (props, params) => {
+      const name = columnName(params);
+      if (!name || !progressColumns.includes(name)) return undefined;
+      const value = toNumber(props.value);
+      if (value === undefined) return undefined;
+      return <ProgressCell value={value} />;
+    },
+  };
+}
+
+/** What the control registers with the grid — see `index.ts`. */
+export const cellRendererOverrides: CellRendererOverrides = createCellRendererOverrides();

package/templates/grid-customizer/{{componentName}}/customizers/cells.tsx

@@ -0,0 +1,137 @@
+import * as React from 'react';
+// ★ Root import, not a deep one (`@fluentui/react/lib/Label`). pcf-scripts externalises the
+// module specifier `@fluentui/react` to the platform global; a deep path is a DIFFERENT
+// specifier and gets bundled instead — which reintroduces exactly the compiled-version ≠
+// served-version skew the exact pin in package.json exists to prevent.
+import { ProgressIndicator } from '@fluentui/react';
+import {
+  CURRENCY_NEGATIVE,
+  CURRENCY_POSITIVE,
+  PROGRESS_MAX,
+  getStatusColor,
+} from './config';
+
+/**
+ * The visual half of the customizer: presentational cells with no knowledge of the grid
+ * contract. `CellRendererOverrides.tsx` decides WHICH cell renders WHERE; this file decides
+ * what each one looks like. Split that way so a renderer can be unit-tested and reused from
+ * the dev harness without a PCF context.
+ *
+ * All of these are Fluent v8 / inline styles, matching the host grid — see the manifest
+ * comment on why a customizer is v8 even though the platform also serves Fluent v9.
+ */
+
+/** Cells sit inside a grid row of fixed height; fill it rather than adding vertical padding. */
+const fill: React.CSSProperties = {
+  display: 'flex',
+  alignItems: 'center',
+  height: '100%',
+  width: '100%',
+  overflow: 'hidden',
+};
+
+/**
+ * An option-set / status value as a coloured pill.
+ *
+ * Assumes a non-empty label — the caller falls through to the grid's own renderer for an
+ * unset value rather than asking this component to draw "nothing", which would blank the
+ * cell instead of leaving it to the platform.
+ */
+export const StatusBadgeCell: React.FC<{ label: string }> = ({ label }) => {
+  return (
+    <div style={fill}>
+      <span
+        title={label}
+        style={{
+          backgroundColor: getStatusColor(label),
+          color: '#ffffff',
+          borderRadius: 10,
+          padding: '2px 10px',
+          fontSize: 12,
+          fontWeight: 600,
+          lineHeight: '16px',
+          maxWidth: '100%',
+          overflow: 'hidden',
+          textOverflow: 'ellipsis',
+          whiteSpace: 'nowrap',
+        }}
+      >
+        {label}
+      </span>
+    </div>
+  );
+};
+
+/**
+ * A currency amount, right-aligned and coloured by sign.
+ *
+ * Renders the platform's `formattedValue` — it already carries the record's currency symbol
+ * and the user's locale separators, which a client-side `Intl.NumberFormat` would guess at
+ * (and get wrong for any transaction currency other than the user's own).
+ */
+export const CurrencyCell: React.FC<{ amount: number; formatted: string }> = ({
+  amount,
+  formatted,
+}) => (
+  <div style={{ ...fill, justifyContent: 'flex-end' }}>
+    <span
+      style={{
+        color: amount < 0 ? CURRENCY_NEGATIVE : CURRENCY_POSITIVE,
+        fontWeight: 600,
+        fontVariantNumeric: 'tabular-nums',
+      }}
+    >
+      {formatted}
+    </span>
+  </div>
+);
+
+/** A 0–PROGRESS_MAX number as a labelled bar. */
+export const ProgressCell: React.FC<{ value: number }> = ({ value }) => {
+  const clamped = Math.max(0, Math.min(PROGRESS_MAX, value));
+  return (
+    <div style={{ ...fill, gap: 8 }}>
+      <div style={{ flex: '1 1 auto', minWidth: 40 }}>
+        <ProgressIndicator
+          percentComplete={clamped / PROGRESS_MAX}
+          barHeight={6}
+          // The grid row supplies the label; a second one here would double the row height.
+          styles={{ root: { margin: 0 }, itemProgress: { padding: 0 } }}
+        />
+      </div>
+      <span style={{ flex: '0 0 auto', fontSize: 12, fontVariantNumeric: 'tabular-nums' }}>
+        {Math.round(clamped)}%
+      </span>
+    </div>
+  );
+};
+
+/**
+ * A yes/no value as a tick or cross, so the column scans at a glance.
+ *
+ * ★ Inline SVG, NOT Fluent's `<Icon iconName="CheckMark">`. Fluent v8 icons are FONT icons
+ * that must be registered by `initializeIcons()` before use; an unregistered name renders as
+ * nothing and only warns ("The icon 'checkmark' was used but not registered"). A customizer
+ * does not own the page, so whether registration has happened against the platform's shared
+ * Fluent instance by the time a cell paints is not ours to guarantee — and the failure is a
+ * silently blank cell, not an error. An SVG has no such dependency and looks the same in the
+ * dev harness and in the org.
+ */
+export const BooleanCell: React.FC<{ on: boolean; label: string }> = ({ on, label }) => (
+  <div style={{ ...fill, gap: 6 }}>
+    <svg
+      width="14"
+      height="14"
+      viewBox="0 0 16 16"
+      aria-hidden="true"
+      focusable="false"
+      style={{ flex: '0 0 auto' }}
+    >
+      <path
+        d={on ? 'M6.2 12.4 2 8.2l1.3-1.3 2.9 2.9 6.5-6.5L14 4.6z' : 'M12.7 4.3 11.3 2.9 8 6.2 4.7 2.9 3.3 4.3 6.6 7.6 3.3 10.9l1.4 1.4L8 9l3.3 3.3 1.4-1.4-3.3-3.3z'}
+        fill={on ? '#107c10' : '#a19f9d'}
+      />
+    </svg>
+    <span>{label}</span>
+  </div>
+);

package/templates/grid-customizer/{{componentName}}/customizers/config.ts

@@ -0,0 +1,84 @@
+/**
+ * ★ THE ONE FILE YOU EDIT to retarget this customizer at your own columns.
+ *
+ * It is plain data, deliberately: a grid customizer cannot be configured by a maker at
+ * bind time. The grid's "Customizer control" field references this control by NAME only,
+ * so any `usage="input"` manifest property arrives `undefined` at runtime. Changing
+ * behaviour means editing this file and redeploying with a bumped manifest version.
+ *
+ * If you need runtime-changeable rules instead, read them from a Dataverse environment
+ * variable in `index.ts` — see the README. (If you have the `claude-workspace` checkout,
+ * `shared/pcf-gallery/controls/color-grid` is a full worked implementation, including the
+ * `<uses-feature name="WebAPI">` declaration that read requires.)
+ */
+
+/**
+ * Columns rendered as a progress bar instead of a plain number. Empty by default: without
+ * an explicit list, EVERY numeric column in every grid this customizer touches would turn
+ * into a progress bar, which is almost never what you want.
+ *
+ * Use column LOGICAL names, e.g. `['dvk_percentcomplete']`.
+ */
+export const PROGRESS_COLUMNS: readonly string[] = [];
+
+/** Values a progress column is scaled against. A value of `PROGRESS_MAX` fills the bar. */
+export const PROGRESS_MAX = 100;
+
+/**
+ * Colour for a status / option-set label, matched case-insensitively against the
+ * platform-formatted TEXT of the cell (not the numeric option value) — so the same map
+ * works across tables whose option values differ but whose labels agree.
+ *
+ * Anything not listed falls back to a stable colour derived from the label itself, so a
+ * new option is still visually distinct without a code change.
+ */
+export const STATUS_COLORS: Readonly<Record<string, string>> = {
+  active: '#107c10',
+  inactive: '#605e5c',
+  draft: '#0078d4',
+  new: '#0078d4',
+  pending: '#c19c00',
+  inprogress: '#0078d4',
+  approved: '#107c10',
+  completed: '#107c10',
+  done: '#107c10',
+  rejected: '#a4262c',
+  failed: '#a4262c',
+  cancelled: '#605e5c',
+  canceled: '#605e5c',
+  blocked: '#a4262c',
+};
+
+/** Colour for a positive currency amount. */
+export const CURRENCY_POSITIVE = '#107c10';
+/** Colour for a negative currency amount — the reason Currency is overridden at all. */
+export const CURRENCY_NEGATIVE = '#a4262c';
+
+/**
+ * Deterministic fallback colour for an unmapped status label. Same input → same colour for
+ * the life of the label, so the grid does not reshuffle between renders.
+ */
+export function stringToColor(str: string): string {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    hash = str.charCodeAt(i) + ((hash << 5) - hash);
+    hash |= 0; // keep it a 32-bit int so long labels don't drift into float imprecision
+  }
+  return `hsl(${Math.abs(hash) % 360}, 55%, 35%)`;
+}
+
+/** Resolve the badge colour for a formatted status label. */
+export function getStatusColor(label: string): string {
+  const normalized = label.toLowerCase().replace(/[\s_-]+/g, '');
+  return STATUS_COLORS[normalized] ?? stringToColor(normalized || 'unknown');
+}
+
+/** Coerce a raw grid cell value to a number, or `undefined` when it isn't one. */
+export function toNumber(value: unknown): number | undefined {
+  if (typeof value === 'number') return Number.isFinite(value) ? value : undefined;
+  if (typeof value === 'string' && value.trim() !== '') {
+    const n = Number(value);
+    return Number.isFinite(n) ? n : undefined;
+  }
+  return undefined;
+}

package/templates/grid-customizer/{{componentName}}/index.ts

@@ -0,0 +1,81 @@
+import type { IInputs, IOutputs } from './generated/ManifestTypes';
+import * as React from 'react';
+import { cellRendererOverrides } from './customizers/CellRendererOverrides';
+import { cellEditorOverrides } from './customizers/CellEditorOverrides';
+import type { PAOneGridCustomizer } from './types';
+
+/**
+ * `context.factory` carries the grid's event channel but is absent from the typed
+ * `ComponentFramework.Context`, so it is declared structurally here rather than cast to
+ * `any` — the cast would also silence a genuine typo in the call.
+ */
+interface CustomizerFactory {
+  fireEvent(eventName: string, payload: PAOneGridCustomizer): void;
+}
+
+export class {{componentName}} implements ComponentFramework.ReactControl<IInputs, IOutputs> {
+  // No constructor: the platform instantiates the control with no arguments and there is
+  // nothing to set up before init(). An explicit empty one would need an
+  // `@typescript-eslint/no-empty-function` disable, and that rule is not defined by the
+  // parser-only .eslintrc this template ships — `pcf-scripts build` fails on an unknown
+  // rule in a disable comment, not just on a rule violation.
+
+  /**
+   * Register the customizer with the host grid.
+   *
+   * This is the whole control. The grid passes an event name through the bound `EventName`
+   * property and then waits; firing that event with the override maps is what makes the
+   * grid paint custom cells. A customizer is initialised ONCE per grid, and the grid latches
+   * the FIRST payload it receives — later fires are ignored — so everything the customizer
+   * needs must be ready by the time this returns.
+   */
+  public init(
+    context: ComponentFramework.Context<IInputs>,
+    notifyOutputChanged: () => void,
+    state: ComponentFramework.Dictionary,
+  ): void {
+    // ★ The host SWALLOWS a throw from init: it tears the customizer down through a
+    // telemetry path that itself errors, which masks the original stack. The symptom is a
+    // grid that renders perfectly with default cells and no console error at all. Catch and
+    // log here or you will debug this blind.
+    try {
+      // ★ `?.` is load-bearing. A grid customizer receives ONLY the bound EventName; any
+      // other manifest property is undefined at runtime, and so is this one on a host that
+      // instantiates the control outside a grid. Reading `.raw` off undefined throws — see
+      // above for why that throw is invisible.
+      const eventName = context.parameters.EventName?.raw;
+      if (!eventName) return;
+
+      const customizer: PAOneGridCustomizer = {
+        cellRendererOverrides,
+        cellEditorOverrides,
+      };
+
+      (context as unknown as { factory: CustomizerFactory }).factory.fireEvent(
+        eventName,
+        customizer,
+      );
+    } catch (e) {
+      // eslint-disable-next-line no-console
+      console.error('[{{componentName}}] init failed', e);
+    }
+  }
+
+  /**
+   * A customizer has no surface of its own — the grid it decorates owns the DOM. Returning
+   * an empty Fragment satisfies the virtual-control contract without adding a wrapper
+   * element to the grid's layout.
+   */
+  public updateView(context: ComponentFramework.Context<IInputs>): React.ReactElement {
+    return React.createElement(React.Fragment);
+  }
+
+  public getOutputs(): IOutputs {
+    return {};
+  }
+
+  public destroy(): void {
+    // Nothing to release: no timers, no listeners, no subscriptions. If you add a runtime
+    // config read (see README), cancel it here.
+  }
+}

package/templates/grid-customizer/{{componentName}}/strings/{{componentName}}.1033.resx

@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="utf-8"?>
+<root>
+  <xsd:schema id="root" xmlns="" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
+    <xsd:import namespace="http://www.w3.org/XML/1998/namespace" />
+    <xsd:element name="root" msdata:IsDataSet="true">
+      <xsd:complexType>
+        <xsd:choice maxOccurs="unbounded">
+          <xsd:element name="data">
+            <xsd:complexType>
+              <xsd:sequence>
+                <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
+                <xsd:element name="comment" type="xsd:string" minOccurs="0" msdata:Ordinal="2" />
+              </xsd:sequence>
+              <xsd:attribute name="name" type="xsd:string" use="required" msdata:Ordinal="1" />
+              <xsd:attribute name="type" type="xsd:string" msdata:Ordinal="3" />
+              <xsd:attribute name="mimetype" type="xsd:string" msdata:Ordinal="4" />
+              <xsd:attribute ref="xml:space" />
+            </xsd:complexType>
+          </xsd:element>
+          <xsd:element name="resheader">
+            <xsd:complexType>
+              <xsd:sequence>
+                <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
+              </xsd:sequence>
+              <xsd:attribute name="name" type="xsd:string" use="required" />
+            </xsd:complexType>
+          </xsd:element>
+        </xsd:choice>
+      </xsd:complexType>
+    </xsd:element>
+  </xsd:schema>
+  <resheader name="resmimetype">
+    <value>text/microsoft-resx</value>
+  </resheader>
+  <resheader name="version">
+    <value>2.0</value>
+  </resheader>
+  <resheader name="reader">
+    <value>System.Resources.ResXResourceReader, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
+  </resheader>
+  <resheader name="writer">
+    <value>System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
+  </resheader>
+  <data name="{{namespace}}_{{componentName}}" xml:space="preserve">
+    <value>{{componentName}}</value>
+  </data>
+  <data name="{{namespace}}_{{componentName}}_Desc" xml:space="preserve">
+    <value>Editable-grid cell renderer overrides for Power Apps OneGrid.</value>
+  </data>
+  <data name="EventName" xml:space="preserve">
+    <value>Event Name</value>
+  </data>
+  <data name="EventName_Desc" xml:space="preserve">
+    <value>Bound by the host grid. The customizer is published back to the grid through this event.</value>
+  </data>
+</root>