@khester/create-dynamics-app 3.0.0 → 3.1.0

package/templates/host-swap/_variants/host.pcf/{{componentName}}.pcfproj

@@ -0,0 +1,67 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  MSBuild project for the PCF control. Without this file `pac pcf push` fails
+  outright, so a scaffolded control has no deploy path at all — which is exactly
+  what this template shipped before.
+
+  Two ways to deploy (see the README's Deploy section):
+    • pac pcf push --publisher-prefix <p>   — fastest dev loop; wraps the control
+      in a temporary PowerAppsToolsTemp_<p> solution and imports it.
+    • package-control.sh --source <dir>     — emits versioned managed/unmanaged
+      solution zips with no temp solution. That script DISCARDS this file and
+      generates its own, so the two never conflict.
+
+  ProjectGuid is generated per scaffold, so two controls from this template never collide
+  inside one solution.
+-->
+<Project ToolsVersion="15.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <PropertyGroup>
+    <PowerAppsTargetsPath>$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v$(VisualStudioVersion)\PowerApps</PowerAppsTargetsPath>
+  </PropertyGroup>
+
+  <Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" />
+  <Import Project="$(PowerAppsTargetsPath)\Microsoft.PowerApps.VisualStudio.Pcf.props" Condition="Exists('$(PowerAppsTargetsPath)\Microsoft.PowerApps.VisualStudio.Pcf.props')" />
+
+  <PropertyGroup>
+    <Name>{{componentName}}</Name>
+    <ProjectGuid>{{{projectGuid}}}</ProjectGuid>
+    <OutputPath>$(MSBuildThisFileDirectory)out\controls</OutputPath>
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <TargetFrameworkVersion>v4.6.2</TargetFrameworkVersion>
+    <TargetFramework>net462</TargetFramework>
+    <RestoreProjectStyle>PackageReference</RestoreProjectStyle>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.PowerApps.MSBuild.Pcf" Version="1.*" />
+    <!-- Supplies the net462 reference assemblies on macOS/Linux so this builds
+         without a Windows image (otherwise MSB3644). -->
+    <PackageReference Include="Microsoft.NETFramework.ReferenceAssemblies" Version="1.0.3" PrivateAssets="All" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ExcludeDirectories Include="$(MSBuildThisFileDirectory)\.gitignore" />
+    <!-- A scaffolded project always has a nested .git (initGit runs unless --skip-git); the
+         probe this was modelled on lives inside a repo and never had one. package-control.sh
+         rm -rf's it before building, which is the same signal. -->
+    <ExcludeDirectories Include="$(MSBuildThisFileDirectory)\.git\**" />
+    <ExcludeDirectories Include="$(MSBuildThisFileDirectory)\.vs\**" />
+    <ExcludeDirectories Include="$(MSBuildThisFileDirectory)\bin\**" />
+    <ExcludeDirectories Include="$(MSBuildThisFileDirectory)\obj\**" />
+    <ExcludeDirectories Include="$(OutputPath)\**" />
+    <ExcludeDirectories Include="$(MSBuildThisFileDirectory)\*.pcfproj" />
+    <ExcludeDirectories Include="$(MSBuildThisFileDirectory)\*.pcfproj.user" />
+    <ExcludeDirectories Include="$(MSBuildThisFileDirectory)\*.sln" />
+    <ExcludeDirectories Include="$(MSBuildThisFileDirectory)\node_modules\**" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="$(MSBuildThisFileDirectory)\**" Exclude="@(ExcludeDirectories)" />
+  </ItemGroup>
+
+  <Import Project="$(MSBuildToolsPath)\Microsoft.Common.targets" />
+  <Import Project="$(PowerAppsTargetsPath)\Microsoft.PowerApps.VisualStudio.Pcf.targets" Condition="Exists('$(PowerAppsTargetsPath)\Microsoft.PowerApps.VisualStudio.Pcf.targets')" />
+
+</Project>

package/templates/host-swap/_variants/host.web-resource/src/App.tsx

@@ -3,6 +3,7 @@ import type { IApiService } from "./core/services/IApiService";
 import { FetchApiService } from "./core/services/FetchApiService";
 import { MockApiService } from "./core/services/MockApiService";
 import { Component } from "./Component";
+import { useHostWidth } from "./useHostWidth";
 
 // A web resource is served from the org origin, so a same-origin relative
 // /api/data/v9.2 fetch is authenticated by the session cookie — no Xrm or
@@ -14,5 +15,8 @@ export const App: React.FC = () => {
     const onLocalhost = /^(localhost|127\.0\.0\.1)$/.test(window.location.hostname);
     return onLocalhost ? new MockApiService() : new FetchApiService("");
   }, []);
-  return <Component api={api} />;
+  // A web resource embedded on a form is often narrow on a phone, so measure the
+  // viewport rather than assuming desktop.
+  const width = useHostWidth();
+  return <Component api={api} width={width} />;
 };

package/templates/host-swap/src/Component.tsx

@@ -17,14 +17,33 @@ initializeIcons();
 
 /**
  * The ONE host-agnostic component. It depends on nothing but an injected
- * `IApiService` — no PCF `context`, no Xrm, no lifecycle, no bundler globals — so
- * the SAME source renders unchanged inside a PCF control and a Dynamics custom
- * page. Each host's thin wrapper builds the right `IApiService` and mounts this.
+ * `IApiService` and a plain number for its width — no PCF `context`, no Xrm, no
+ * lifecycle, no bundler globals — so the SAME source renders unchanged inside a
+ * PCF control, a web resource, and a model-driven custom page. Each host's thin
+ * wrapper builds the right `IApiService` and supplies the width.
  */
 export interface ComponentProps {
   api: IApiService;
+  /**
+   * Width available to the control, in px. Hosts that can measure it should pass it
+   * (the PCF wrapper passes `context.mode.allocatedWidth`); when omitted the layout
+   * falls back to the roomy variant.
+   *
+   * ★ Deliberately a NUMBER, not a form factor. Do NOT branch on
+   * `context.client.getFormFactor()` / `getClient()`: verified live 2026-07-25 on a
+   * physical iPhone in the native Power Apps app, a custom page reports
+   * client "Web" and formFactor 1 (Desktop). Branching on those silently gives every
+   * phone the desktop layout, and passes every test not run on a real device.
+   */
+  width?: number;
 }
 
+/**
+ * Below this the Fluent `DetailsList` stops being usable — columns collapse and
+ * horizontal scrolling takes over — so narrow hosts get a stacked card list instead.
+ */
+const NARROW_BREAKPOINT_PX = 480;
+
 const ACCOUNTS_FETCHXML = [
   '<fetch top="25">',
   '  <entity name="account">',
@@ -47,10 +66,14 @@ const COLUMNS: IColumn[] = [
   { key: "telephone1", name: "Phone", fieldName: "telephone1", minWidth: 140, isResizable: true },
 ];
 
-export const Component: React.FC<ComponentProps> = ({ api }) => {
+export const Component: React.FC<ComponentProps> = ({ api, width }) => {
   const [rows, setRows] = React.useState<AccountRow[] | null>(null);
   const [error, setError] = React.useState<string | null>(null);
 
+  // `width === undefined` means the host cannot measure itself; prefer the roomy
+  // layout rather than guessing narrow.
+  const isNarrow = width !== undefined && width < NARROW_BREAKPOINT_PX;
+
   React.useEffect(() => {
     let cancelled = false;
     api
@@ -70,12 +93,13 @@ export const Component: React.FC<ComponentProps> = ({ api }) => {
     <Stack tokens={{ childrenGap: 12 }} styles={{ root: { padding: 16 } }}>
       <Text variant="xLarge">Accounts</Text>
       <Text variant="small">
-        One host-agnostic component — the same source renders in a PCF control and a
-        Dynamics custom page; only the thin host wrapper changes.
+        One host-agnostic component — the same source renders in a PCF control, a web
+        resource and a model-driven custom page; only the thin host wrapper changes.
+        {width !== undefined && ` (${isNarrow ? "narrow" : "wide"} layout · ${width}px)`}
       </Text>
       {error && <MessageBar messageBarType={MessageBarType.error}>{error}</MessageBar>}
       {!rows && !error && <Spinner label="Loading accounts…" />}
-      {rows && (
+      {rows && !isNarrow && (
         <DetailsList
           items={rows}
           columns={COLUMNS}
@@ -84,6 +108,29 @@ export const Component: React.FC<ComponentProps> = ({ api }) => {
           selectionMode={SelectionMode.none}
         />
       )}
+      {rows && isNarrow && (
+        <Stack tokens={{ childrenGap: 8 }}>
+          {rows.map((row) => (
+            <Stack
+              key={row.accountid}
+              tokens={{ childrenGap: 2 }}
+              styles={{
+                root: {
+                  padding: 12,
+                  border: "1px solid #edebe9",
+                  borderRadius: 4,
+                  // Long account names must wrap rather than force the card wider
+                  // than the phone — the failure mode DetailsList has here.
+                  wordBreak: "break-word",
+                },
+              }}
+            >
+              <Text variant="mediumPlus">{row.name ?? "(no name)"}</Text>
+              <Text variant="small">{row.telephone1 ?? "—"}</Text>
+            </Stack>
+          ))}
+        </Stack>
+      )}
     </Stack>
   );
 };

package/templates/host-swap/src/useHostWidth.ts

@@ -0,0 +1,53 @@
+import * as React from "react";
+
+/**
+ * Width available to the component, in px, kept live as the host resizes.
+ *
+ * Two modes, because the browser hosts are not all shaped the same:
+ *
+ *  - **Pass a ref** when the component is mounted into an element on a larger page
+ *    (a Power Pages island). The viewport is then the whole portal page, which may be
+ *    far wider than the slot the island occupies, so it must measure its own box.
+ *  - **Pass nothing** when the component owns a full-page iframe (web resource /
+ *    Vite host). There the viewport *is* the control's width.
+ *
+ * The PCF host uses neither — it gets a properly scoped measurement from
+ * `context.mode.allocatedWidth` after opting in with `trackContainerResize(true)`.
+ *
+ * ★ Why measure at all rather than ask the platform what device this is: verified
+ * live 2026-07-25 on a physical iPhone in the native Power Apps app, a model-driven
+ * custom page reports `client: "Web"` and `formFactor: 1` (Desktop). Form-factor
+ * branching therefore hands every phone the desktop layout — and passes every test
+ * that is not run on a real device.
+ */
+export function useHostWidth(ref?: React.RefObject<HTMLElement | null>): number {
+  const [width, setWidth] = React.useState<number>(() =>
+    typeof window === "undefined" ? 0 : window.innerWidth,
+  );
+
+  React.useEffect(() => {
+    const el = ref?.current;
+
+    if (el && typeof ResizeObserver !== "undefined") {
+      const ro = new ResizeObserver((entries) => {
+        for (const entry of entries) setWidth(entry.contentRect.width);
+      });
+      ro.observe(el);
+      setWidth(el.getBoundingClientRect().width);
+      return () => ro.disconnect();
+    }
+
+    // Viewport fallback: no ref, or an environment without ResizeObserver.
+    const onResize = () => setWidth(window.innerWidth);
+    window.addEventListener("resize", onResize);
+    // iOS Safari does not reliably fire `resize` on rotation, so listen for both.
+    window.addEventListener("orientationchange", onResize);
+    onResize();
+    return () => {
+      window.removeEventListener("resize", onResize);
+      window.removeEventListener("orientationchange", onResize);
+    };
+  }, [ref]);
+
+  return width;
+}

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

@@ -0,0 +1,82 @@
+import { apiFetch, toHttpError } from '@dataverse-kit/pcf-dev-harness/shell';
+import type { ColumnDef } from '@dataverse-kit/grid-kit';
+import type { Row } from '../../{{componentName}}/{{componentName}}App';
+
+/**
+ * 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 is what only THIS control can supply:
+ * turning an OData recordset into the exact `items` + `columns` its App expects.
+ *
+ * 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: this is a
+ * read-only grid, so there is no save counterpart.
+ */
+
+export type { HttpError } from '@dataverse-kit/pcf-dev-harness/shell';
+
+/**
+ * Shape a raw OData recordset into the App's props.
+ *
+ * Prefers the `@OData.Community.Display.V1.FormattedValue` annotation for each field, which
+ * is what the deployed control sees via `record.getFormattedValue()` — currency symbols,
+ * option-set labels and lookup display names rather than raw ids. `fields` fixes the column
+ * set and order; the first field is treated as the primary column.
+ */
+function shapeResult(
+  rows: Array<Record<string, unknown>>,
+  fields: string[],
+): { items: Row[]; columns: ColumnDef<Row>[] } {
+  const items: Row[] = rows.map((r, i) => {
+    // The harness never navigates, so a per-render index is a stable enough record id.
+    const row: Row = { key: String(i) };
+    for (const f of fields) {
+      const formatted = r[`${f}@OData.Community.Display.V1.FormattedValue`];
+      row[f] = formatted !== undefined && formatted !== null ? String(formatted) : String(r[f] ?? '');
+    }
+    return row;
+  });
+
+  const columns: ColumnDef<Row>[] = fields.map((f, i) => ({
+    key: f,
+    fieldName: f,
+    name: f,
+    rendererType: 'text',
+    minWidth: i === 0 ? 200 : 120,
+    maxWidth: i === 0 ? 320 : 240,
+    isResizable: true,
+    isSortable: true,
+    isFilterable: true,
+  }));
+
+  return { items, columns };
+}
+
+/**
+ * Fetch `top` rows of `select` columns from an entity set.
+ *
+ * @param entitySetName plural set name, e.g. `accounts`
+ * @param select        comma-separated logical names, e.g. `name,revenue`
+ * @param top           max rows
+ */
+export async function fetchRecords(
+  entitySetName: string,
+  select: string,
+  top: string,
+): Promise<{ items: Row[]; columns: ColumnDef<Row>[] }> {
+  const fields = select
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+
+  const params = new URLSearchParams({ $select: fields.join(','), $top: top || '50' });
+  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?: Array<Record<string, unknown>> };
+  return shapeResult(body.value ?? [], fields);
+}

package/templates/pcf-dataset/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>

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

@@ -0,0 +1,190 @@
+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>);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  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"]
+}