@khester/create-dynamics-app 3.0.0 → 3.2.0

package/templates/pcf-dataset/dev/main.tsx

@@ -0,0 +1,194 @@
+import * as React from 'react';
+// ReactDOM.render, NOT createRoot — this control is pinned to React 16.14.0 to match the
+// `Reactv16` platform global it externalises, and `react-dom/client` does not exist there.
+import * as ReactDOM from 'react-dom';
+import {
+  HarnessShell,
+  usePersistedState,
+  type ThemeChoice,
+  type DataSource,
+  type HarnessField,
+} from '@dataverse-kit/pcf-dev-harness/shell';
+import type { ColumnDef } from '@dataverse-kit/grid-kit';
+import { {{componentName}}App, type Row } from '../{{componentName}}/{{componentName}}App';
+import { fetchRecords, type HttpError } from './harness/dataverse';
+
+/**
+ * Dev harness — renders the control's host-agnostic <{{componentName}}App> inside the shared
+ * shell, with two data sources:
+ *   - Mock — the hard-coded recordset below. Default; works with no org.
+ *   - Live — real rows from a Dataverse org via the /api/data proxy. Enabled only when
+ *            VITE_DYNAMICS_URL is set in `.env.local`.
+ *
+ * This is the working local loop for this artifact — see the note in vite.config.ts about
+ * `pcf-scripts start` being unable to host a React-18 virtual control.
+ */
+
+/** Live-org binding for a DATASET control: entity set + columns + page size. */
+interface RecordsetBinding {
+  entitySetName: string;
+  select: string;
+  top: string;
+}
+
+const MOCK_COLUMNS: ColumnDef<Row>[] = [
+  { key: 'name', fieldName: 'name', name: 'Name', rendererType: 'text', minWidth: 200, maxWidth: 320, isResizable: true, isSortable: true, isFilterable: true },
+  { key: 'city', fieldName: 'city', name: 'City', rendererType: 'text', minWidth: 120, maxWidth: 240, isResizable: true, isSortable: true, isFilterable: true },
+  { key: 'revenue', fieldName: 'revenue', name: 'Revenue', rendererType: 'text', minWidth: 120, maxWidth: 240, isResizable: true, isSortable: true, isFilterable: true },
+];
+
+const MOCK_ITEMS: Row[] = [
+  { key: '0', name: 'Contoso Ltd', city: 'Seattle', revenue: '$5,200,000.00' },
+  { key: '1', name: 'Fabrikam Inc', city: 'Redmond', revenue: '$1,800,000.00' },
+  { key: '2', name: 'Adventure Works', city: 'Portland', revenue: '$920,000.00' },
+  { key: '3', name: 'Northwind Traders', city: 'Vancouver', revenue: '$3,400,000.00' },
+  { key: '4', name: 'Tailspin Toys', city: 'Boise', revenue: '$640,000.00' },
+];
+
+// VITE_-prefixed vars reach client code; this one only GATES Live mode. The token is
+// deliberately not read here — it would be inlined into the bundle. The proxy injects it.
+const LIVE_ENABLED = !!import.meta.env.VITE_DYNAMICS_URL;
+
+/** Turn a failed live fetch into a red status line, calling out auth failures specifically. */
+function describeLoadError(e: unknown): React.ReactNode {
+  const err = e as HttpError;
+  // The dev server refreshes the token in the background, so a 401/403 that survives the
+  // client retry means the `az login` session itself lapsed — not just the short-lived token.
+  const msg =
+    err.status === 401 || err.status === 403
+      ? 'Not authorized — your `az login` session has expired. Run `az login`, then Load again.'
+      : `Failed to load: ${err.message}`;
+  return <span style={{ color: '#a4262c' }}>{msg}</span>;
+}
+
+const Harness: React.FC = () => {
+  // Panel CONFIG persists across reloads (localStorage); fetched DATA does not.
+  const [width, setWidth] = usePersistedState('width', 0); // 0 => fill the canvas
+  const [height, setHeight] = usePersistedState('height', 0); // 0 => auto
+  const [theme, setTheme] = usePersistedState<ThemeChoice>('theme', 'light');
+  const [dataSource, setDataSource] = usePersistedState<DataSource>('dataSource', 'mock');
+  const [binding, setBinding] = usePersistedState<RecordsetBinding>('binding', {
+    entitySetName: 'accounts',
+    select: 'name,address1_city,revenue',
+    top: '25',
+  });
+
+  const [items, setItems] = React.useState<Row[]>(MOCK_ITEMS);
+  const [columns, setColumns] = React.useState<ColumnDef<Row>[]>(MOCK_COLUMNS);
+  const [liveStatus, setLiveStatus] = React.useState<React.ReactNode>(null);
+
+  // On reload with a restored Live selection: clear and prompt for Load — or fall back to
+  // Mock when this session has no org configured. Runs once on mount.
+  React.useEffect(() => {
+    if (dataSource !== 'live') return;
+    if (!LIVE_ENABLED) {
+      setDataSource('mock');
+      return;
+    }
+    setItems([]);
+    setColumns([]);
+    setLiveStatus(<span style={{ color: '#605e5c' }}>Binding restored — click Load.</span>);
+    // Mount-only by design: `[]` deliberately omits dataSource/LIVE_ENABLED, because this
+    // reconciles the RESTORED selection once and must not re-run when it later changes.
+    // (No eslint-disable here: this template's .eslintrc loads no plugins — a devDependency
+    // is not enough — so a `react-hooks/exhaustive-deps` disable names an unresolvable rule,
+    // which `pcf-scripts build` treats as an ESLint ERROR. Gated by gridCustomizer.test.ts.)
+  }, []);
+
+  const onDataSourceChange = (next: DataSource): void => {
+    setDataSource(next);
+    if (next === 'mock') {
+      setItems(MOCK_ITEMS);
+      setColumns(MOCK_COLUMNS);
+      setLiveStatus(null);
+    } else {
+      setItems([]);
+      setColumns([]);
+      setLiveStatus(<span style={{ color: '#605e5c' }}>Enter a binding and click Load.</span>);
+    }
+  };
+
+  const onLoadLive = (): void => {
+    void (async () => {
+      if (!binding.entitySetName || !binding.select) {
+        setLiveStatus(<span style={{ color: '#a4262c' }}>Enter an entity set + columns.</span>);
+        return;
+      }
+      setLiveStatus(<span style={{ color: '#605e5c' }}>Loading…</span>);
+      try {
+        const result = await fetchRecords(binding.entitySetName, binding.select, binding.top);
+        setItems(result.items);
+        setColumns(result.columns);
+        setLiveStatus(
+          <span style={{ color: '#107c10' }}>
+            Loaded {result.items.length} row{result.items.length === 1 ? '' : 's'}.
+          </span>,
+        );
+      } catch (e) {
+        setLiveStatus(describeLoadError(e));
+      }
+    })();
+  };
+
+  const bindingFields: HarnessField[] = [
+    {
+      kind: 'text',
+      label: 'Entity set (plural)',
+      placeholder: 'accounts',
+      value: binding.entitySetName,
+      onChange: (v) => setBinding((b) => ({ ...b, entitySetName: v })),
+    },
+    {
+      kind: 'text',
+      label: 'Columns ($select, comma-separated)',
+      placeholder: 'name,address1_city,revenue',
+      value: binding.select,
+      onChange: (v) => setBinding((b) => ({ ...b, select: v })),
+    },
+    {
+      kind: 'text',
+      label: 'Top (max rows)',
+      placeholder: '25',
+      value: binding.top,
+      onChange: (v) => setBinding((b) => ({ ...b, top: v })),
+    },
+  ];
+
+  return (
+    <HarnessShell
+      title="{{componentName}} — dev harness"
+      subtitle="Dataset grid (grid-kit ReadOnlyGrid)"
+      width={width}
+      onWidthChange={setWidth}
+      height={height}
+      onHeightChange={setHeight}
+      theme={theme}
+      onThemeChange={setTheme}
+      dataSource={dataSource}
+      onDataSourceChange={onDataSourceChange}
+      liveEnabled={LIVE_ENABLED}
+      bindingFields={bindingFields}
+      onLoadLive={onLoadLive}
+      liveStatus={liveStatus}
+      // Control-specific inputs panel. This grid takes no configuration properties beyond its
+      // bound dataset, so it is empty — add entries here as you add manifest properties.
+      fields={[]}
+    >
+      {/* Guard the empty-columns state (Live selected, not yet loaded): a PCF dataset always
+          has columns, so the control isn't built to render with none. Fluent v8's
+          ScrollablePane is absolutely positioned, so it needs a sized, position:relative
+          ancestor — the PCF host provides one; mirror it here. */}
+      {columns.length > 0 ? (
+        <div style={{ position: 'relative', height: height || 420 }}>
+          <{{componentName}}App items={items} columns={columns} />
+        </div>
+      ) : (
+        <div style={{ color: '#605e5c', fontSize: 13, padding: 8 }}>
+          No records — enter a binding and click Load.
+        </div>
+      )}
+    </HarnessShell>
+  );
+};
+
+ReactDOM.render(<Harness />, document.getElementById('root'));

package/templates/pcf-dataset/dev/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/templates/pcf-dataset/env.local.example

@@ -0,0 +1,24 @@
+# Live-org dev harness config. Copy to `.env.local` (gitignored) and fill in your org.
+#
+#   cp env.local.example .env.local
+#   az login
+#   npm run dev          # http://localhost:8182
+#
+# `az login` alone is enough: the Vite dev server acquires the bearer token in-process and
+# refreshes it before expiry. DYNAMICS_TOKEN below is only an optional static fallback.
+
+# The ONLY var exposed to the browser bundle. Setting it enables the harness "Live" toggle;
+# leave it blank to run against mock data only.
+VITE_DYNAMICS_URL=
+
+# Optional. Set for a CDX / cross-tenant org — passed to `az --tenant`.
+DYNAMICS_TENANT=
+
+# Optional static token fallback, used only if the in-process `az` acquisition fails.
+# ★ NO `VITE_` PREFIX, deliberately: a VITE_-prefixed var is inlined into the client bundle,
+# which would ship your bearer token to the browser. Server-side only.
+#
+# ★ Do NOT populate this with the workspace's `msft/04-dynamics/scripts/get-token.sh` — its
+# detect_env_prefix writes REACT_APP_/VITE_-prefixed names, and this harness looks up a bare
+# `DYNAMICS_TOKEN`. Use `npm run auth:token` (the pcf-dev-token bin) instead.
+DYNAMICS_TOKEN=

package/templates/pcf-dataset/eslintrc.json

@@ -0,0 +1,11 @@
+{
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": 2021,
+    "sourceType": "module",
+    "ecmaFeatures": { "jsx": true }
+  },
+  "env": { "browser": true, "es2021": true },
+  "ignorePatterns": ["out/**", "node_modules/**", "**/generated/**"]
+}

package/templates/pcf-dataset/gitignore

@@ -3,3 +3,7 @@ out/
 generated/
 *.log
 .env
+.env.local
+.env.local.backup
+dev/dist/
+obj/

package/templates/pcf-dataset/package.json

@@ -2,31 +2,41 @@
   "name": "{{projectName}}",
   "version": "1.0.0",
   "description": "{{componentName}} PCF control built with Dynamics UI Kit",
+  "_comment_versions": "react/react-dom are pinned EXACTLY to 16.14.0 and @fluentui/react to 8.121.1 because this is a control-type=\"virtual\" control: both are externalised to the platform globals Reactv16 / FluentUIReactv81211, so the compiled-against version MUST equal the served version. Measured live 2026-08-01: the model-driven host serves React 17.0.2 under the Reactv16 alias and defines NO Reactv18 \u2014 declaring React 18.3.1 built green and failed to instantiate in the org. Pinning the 16.x types also makes any React-17+-only API a compile error instead of a runtime crash. Requires @dataverse-kit/grid-kit >= 0.16.0, whose react peer was widened to >=16.14.0 <19 for exactly this reason.",
   "scripts": {
     "build": "pcf-scripts build",
     "clean": "pcf-scripts clean",
     "rebuild": "pcf-scripts rebuild",
     "start": "pcf-scripts start",
-    "refreshTypes": "pcf-scripts refreshTypes"
+    "refreshTypes": "pcf-scripts refreshTypes",
+    "dev": "vite --config vite.config.ts",
+    "dev:token": "npm run auth:token && npm run dev",
+    "auth:token": "pcf-dev-token",
+    "typecheck:dev": "tsc -p tsconfig.dev.json --noEmit",
+    "harness:check": "npm run typecheck:dev && vite build --config vite.config.ts"
   },
   "dependencies": {
-    "@dataverse-kit/grid-kit": "^0.6.0",
-    "@fluentui/react": "^8.120.0",
+    "@dataverse-kit/grid-kit": "^0.16.0",
+    "@fluentui/react": "8.121.1",
     "@khester/dynamics-cell-renderers": "^1.1.0",
     "@khester/dynamics-utils": "^1.2.0",
     "@types/powerapps-component-framework": "^1.3.18",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0"
+    "react": "16.14.0",
+    "react-dom": "16.14.0"
   },
   "devDependencies": {
+    "@dataverse-kit/pcf-dev-harness": "^0.2.0",
     "@microsoft/eslint-config-spfx": "^1.18.2",
+    "@vitejs/plugin-react": "^4.3.4",
     "@types/node": "^18.16.9",
-    "@types/react": "^18.2.0",
-    "@types/react-dom": "^18.2.0",
+    "@types/react": "^16.14.34",
+    "@types/react-dom": "^16.9.17",
+    "@typescript-eslint/parser": "^6.21.0",
     "eslint-plugin-react-hooks": "^4.6.0",
     "pcf-scripts": "^1",
     "pcf-start": "^1",
-    "typescript": "^5.3.0"
+    "typescript": "^5.3.0",
+    "vite": "^5.4.0"
   },
   "browserslist": [
     "last 2 versions"

package/templates/pcf-dataset/pcfconfig.json

@@ -0,0 +1,3 @@
+{
+  "outDir": "./out/controls"
+}

package/templates/pcf-dataset/tsconfig.dev.json

@@ -0,0 +1,15 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "skipLibCheck": true
+  },
+  "//": [
+    "★ `exclude` is INHERITED through `extends`, so it MUST be overridden here — otherwise",
+    "dev/ stays excluded from its own project, `include` resolves to nothing, and",
+    "`npm run typecheck:dev` passes while checking zero files: a green gate gating nothing.",
+    "dev/main.tsx imports the control's App, which pulls the shared component in too."
+  ],
+  "exclude": ["node_modules", "out"],
+  "include": ["dev", "vite.config.ts"]
+}

package/templates/pcf-dataset/tsconfig.json

@@ -4,6 +4,15 @@
     "typeRoots": ["node_modules/@types"],
     "jsx": "react",
     "esModuleInterop": true,
-    "experimentalDecorators": true
-  }
+    "experimentalDecorators": true,
+    "skipLibCheck": true
+  },
+  "//": [
+    "★ `exclude` REPLACES the base's [\"./node_modules\"] — node_modules MUST be re-listed here.",
+    "pcf-scripts runs ts-loader in full (non-transpileOnly) mode, and ts-loader seeds its file",
+    "list from EVERY file the tsconfig resolves — not just what webpack reaches from the entry.",
+    "So without this exclude the Vite harness under dev/ would be typechecked as part of the",
+    "control build and could fail it. dev/ has its own project: tsconfig.dev.json."
+  ],
+  "exclude": ["node_modules", "out", "dev", "vite.config.ts"]
 }

package/templates/pcf-dataset/vite.config.ts

@@ -0,0 +1,63 @@
+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:
+ * `pcf-start` hard-codes React 16 in its harness page and never loads its own
+ * `lib/react_18_3_1.js`, so a control-type="virtual" control declaring React 18.3.1 — which
+ * this one is — externalises a `Reactv18` global that the harness never defines, and shows
+ * "Error loading control". Verified against pcf-start 1.51.1 (latest) on 2026-08-01.
+ * So for THIS artifact the Vite harness is the working local loop, not a convenience.
+ *
+ * Two data sources (see `dev/main.tsx`):
+ *   - Mock — a hard-coded recordset. Default; needs no org.
+ *   - Live — real rows from Dataverse through the same-origin `/api/data` proxy. Enabled
+ *            only when VITE_DYNAMICS_URL is set in `.env.local`.
+ *
+ * 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/pcf-dataset/{{componentName}}/ControlManifest.Input.xml

@@ -0,0 +1,52 @@
+<?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">
+    <data-set name="dataset" display-name-key="Dataset_Display_Key">
+    </data-set>
+    <resources>
+      <code path="index.ts" order="1"/>
+      <!--
+        ★ These versions must EQUAL a version the PLATFORM ACTUALLY SERVES — not merely one
+        pcf-scripts accepts. The two are NOT the same list, and that gap is what kills controls:
+        pcf-scripts matches a {minVersion, maxVersion} row and remaps the bundle to that row's
+        alias, but never rewrites this file and never checks the runtime.
+
+        Measured on a live model-driven page (orge2e285aa, 2026-08-01) — these are the globals
+        the host defines:
+
+            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; the org has no React 18
+            ReactDOMv16         = present
+            ReactDOMv18         = undefined
+            FluentUIReactv81211 = present        ← Fluent 8.121.1
+            FluentUIReactv940   = present        ← Fluent 9.68.0 IS served (re-measured 2026-08-02)
+
+        ★ Correction, 2026-08-02: an earlier revision of this comment claimed "8.29.0 is NOT
+        served", from probing `FluentUIReactv829`. The real alias is `FluentUIReactv8290`, and
+        8.29.0 IS served. Platform libraries are injected ON DEMAND from manifest declarations,
+        so a global is absent simply because nothing on that page declared it — "undefined here"
+        is not evidence that a version is unavailable. React 18 is the genuine exception:
+        `Reactv18` is undefined even on pages actively loading controls.
+
+        This control previously declared React 18.3.1 (because pcf-scripts allows it). It built
+        green and then failed with "An error has occurred." in the org, because it externalised
+        a `Reactv18` global that does not exist. Now 16.14.0 — matching Microsoft's published
+        table ("allowed 16.14.0; version loaded: 17.0.2 (Model), 16.14.0 (Canvas)") and the
+        only React alias the runtime supplies. It is also what the canvas runtime serves, so
+        this control now works in a model-driven custom page too.
+
+        A virtual control CANNOT bundle its own React as a workaround: it returns a ReactElement
+        that the platform renders with the platform's React, so two React instances would break.
+        That is why grid-kit's peer was widened to >=16.14.0 <19 rather than pinning React 18
+        here. See src/__tests__/registry.test.ts.
+      -->
+      <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>
+    <feature-usage>
+      <uses-feature name="Utility" required="true" />
+    </feature-usage>
+  </control>
+</manifest>

package/templates/pcf-dataset/{{componentName}}/{{componentName}}App.tsx

@@ -0,0 +1,64 @@
+import * as React from 'react';
+import { initializeIcons } from '@fluentui/react/lib/Icons';
+import { ReadOnlyGrid, createCellRegistry } from '@dataverse-kit/grid-kit';
+import type { ColumnDef, GridSortState } from '@dataverse-kit/grid-kit';
+
+// Initialize Fluent UI icons — the grid toolbar / column-chooser / filter use them.
+// Lives here (not in the PCF adapter) so BOTH hosts get it: the control and the dev harness.
+initializeIcons();
+
+/** A grid row. `key` is the record id and is always present. */
+export interface Row extends Record<string, unknown> {
+    key: string;
+}
+
+export interface I{{componentName}}AppProps {
+    items: Row[];
+    columns: ColumnDef<Row>[];
+}
+
+/**
+ * HOST-AGNOSTIC grid app — plain props, no PCF and no Xrm.
+ *
+ * That is the whole point of the split: `{{componentName}}Component.tsx` adapts the PCF
+ * dataset into `items` + `columns`, and `dev/main.tsx` supplies the same shape from mock
+ * data or a live Dataverse fetch. One component, two hosts, no duplicated grid logic.
+ */
+export const {{componentName}}App: React.FC<I{{componentName}}AppProps> = ({ items, columns }) => {
+    const registry = React.useMemo(() => createCellRegistry(), []);
+    const [search, setSearch] = React.useState('');
+    const [sort, setSort] = React.useState<GridSortState | undefined>(undefined);
+
+    // grid-kit's toolbar `onSearch` only reports the term — the host owns filtering.
+    // Substring-match across every column's formatted value.
+    const q = search.trim().toLowerCase();
+    const filtered = q
+        ? items.filter((row) =>
+              columns.some((c) => String(row[c.fieldName] ?? '').toLowerCase().includes(q)),
+          )
+        : items;
+
+    // grid-kit sort is controlled — `onSortChange` reports the header click; the host
+    // reorders nothing. Sort the (filtered) rows by the formatted string.
+    const sorted = sort
+        ? [...filtered].sort(
+              (a, b) =>
+                  String(a[sort.fieldName] ?? '').localeCompare(String(b[sort.fieldName] ?? '')) *
+                  (sort.direction === 'desc' ? -1 : 1),
+          )
+        : filtered;
+
+    return (
+        <ReadOnlyGrid<Row>
+            items={sorted}
+            columns={columns}
+            registry={registry}
+            getKey={(r) => r.key}
+            sort={sort}
+            onSortChange={(fieldName, direction) => setSort({ fieldName, direction })}
+            columnChooser
+            filterBuilder
+            toolbar={{ showSearch: true, searchPlaceholder: 'Search', onSearch: setSearch }}
+        />
+    );
+};

package/templates/pcf-dataset/{{{componentName}}Component.tsx → {{componentName}}/{{componentName}}Component.tsx}

@@ -1,24 +1,18 @@
 import * as React from 'react';
-import { initializeIcons } from '@fluentui/react/lib/Icons';
-import { ReadOnlyGrid, createCellRegistry } from '@dataverse-kit/grid-kit';
-import type { ColumnDef, GridSortState } from '@dataverse-kit/grid-kit';
-
-// Initialize Fluent UI icons — the grid toolbar / column-chooser / filter use them.
-initializeIcons();
+import type { ColumnDef } from '@dataverse-kit/grid-kit';
+import { {{componentName}}App, type Row } from './{{componentName}}App';
 
 export interface I{{componentName}}ComponentProps {
     dataset: ComponentFramework.PropertyTypes.DataSet;
 }
 
-interface Row extends Record<string, unknown> {
-    key: string;
-}
-
+/**
+ * THIN PCF ADAPTER — maps the bound dataset onto the host-agnostic `<{{componentName}}App>`.
+ *
+ * All grid behaviour (search, sort, toolbar, column chooser) lives in the App so the dev
+ * harness renders the exact same component. Keep this file to dataset→props mapping only.
+ */
 export const {{componentName}}Component: React.FC<I{{componentName}}ComponentProps> = ({ dataset }) => {
-    const registry = React.useMemo(() => createCellRegistry(), []);
-    const [search, setSearch] = React.useState('');
-    const [sort, setSort] = React.useState<GridSortState | undefined>(undefined);
-
     // Map the bound dataset's columns → grid-kit ColumnDef[]. Every column renders as
     // `text` (the formatted Dataverse value), so client sort/filter is lexical on the
     // displayed string. For type-aware cells + correct numeric/date ordering, map each
@@ -54,36 +48,5 @@ export const {{componentName}}Component: React.FC<I{{componentName}}ComponentPro
         return row;
     });
 
-    // grid-kit's toolbar `onSearch` only reports the term — the host owns filtering.
-    // Substring-match across every column's formatted value.
-    const q = search.trim().toLowerCase();
-    const filtered = q
-        ? items.filter((row) =>
-              columns.some((c) => String(row[c.fieldName] ?? '').toLowerCase().includes(q)),
-          )
-        : items;
-
-    // grid-kit sort is controlled — `onSortChange` reports the header click; the host
-    // reorders nothing. Sort the (filtered) rows by the formatted string.
-    const sorted = sort
-        ? [...filtered].sort(
-              (a, b) =>
-                  String(a[sort.fieldName] ?? '').localeCompare(String(b[sort.fieldName] ?? '')) *
-                  (sort.direction === 'desc' ? -1 : 1),
-          )
-        : filtered;
-
-    return (
-        <ReadOnlyGrid<Row>
-            items={sorted}
-            columns={columns}
-            registry={registry}
-            getKey={(r) => r.key}
-            sort={sort}
-            onSortChange={(fieldName, direction) => setSort({ fieldName, direction })}
-            columnChooser
-            filterBuilder
-            toolbar={{ showSearch: true, searchPlaceholder: 'Search', onSearch: setSearch }}
-        />
-    );
+    return <{{componentName}}App items={items} columns={columns} />;
 };

package/templates/pcf-field/dev/harness/dataverse.ts

@@ -0,0 +1,71 @@
+import { apiFetch, toHttpError } from '@dataverse-kit/pcf-dev-harness/shell';
+
+/**
+ * TIER 2 of the dev harness — the {{componentName}}-specific live-org read/write.
+ *
+ * The reusable parts (shell, proxy, token refresh, `apiFetch`'s one-shot 401/403 retry) come
+ * from `@dataverse-kit/pcf-dev-harness`. This file is what only THIS control can supply:
+ * reading and writing a SINGLE COLUMN on a single record — which is exactly what a field
+ * control does, so the harness exercises the same round-trip the deployed control performs.
+ *
+ * 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.
+ */
+
+export type { HttpError } from '@dataverse-kit/pcf-dev-harness/shell';
+
+/** The raw value plus the platform's formatted rendering, when the column has one. */
+export interface FieldRead {
+    raw: unknown;
+    formatted?: string;
+}
+
+/**
+ * Read one column off one record.
+ *
+ * @param entitySetName plural set name, e.g. `accounts`
+ * @param recordId      GUID, with or without braces
+ * @param column        logical name, e.g. `accountcategorycode`
+ */
+export async function readField(
+    entitySetName: string,
+    recordId: string,
+    column: string,
+): Promise<FieldRead> {
+    const id = recordId.replace(/[{}]/g, '').trim();
+    const res = await apiFetch(`/api/data/v9.2/${entitySetName}(${id})?$select=${column}`, {
+        // Ask for the formatted-value annotation so option-set labels / currency symbols show
+        // the same text the platform renders on a form.
+        headers: { Prefer: 'odata.include-annotations="OData.Community.Display.V1.FormattedValue"' },
+    });
+    if (!res.ok) throw await toHttpError(res);
+
+    const body = (await res.json()) as Record<string, unknown>;
+    return {
+        raw: body[column] ?? null,
+        formatted: body[`${column}@OData.Community.Display.V1.FormattedValue`] as string | undefined,
+    };
+}
+
+/**
+ * Write one column back to one record — the save half of the round-trip.
+ *
+ * PATCH with a single property, exactly as the deployed control's `getOutputs` → platform save
+ * would. Returns nothing; a non-2xx throws an HttpError the caller can surface.
+ */
+export async function saveField(
+    entitySetName: string,
+    recordId: string,
+    column: string,
+    value: unknown,
+): Promise<void> {
+    const id = recordId.replace(/[{}]/g, '').trim();
+    const res = await apiFetch(`/api/data/v9.2/${entitySetName}(${id})`, {
+        method: 'PATCH',
+        headers: { 'Content-Type': 'application/json' },
+        // `null` is meaningful here — it clears the column, which is a real thing a field
+        // control must be able to do, so it is NOT coerced away.
+        body: JSON.stringify({ [column]: value === undefined ? null : value }),
+    });
+    if (!res.ok) throw await toHttpError(res);
+}