@khester/create-dynamics-app 3.0.0 → 3.2.0

package/templates/pcf-field/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-field/dev/main.tsx

@@ -0,0 +1,212 @@
+import * as React from 'react';
+// ReactDOM.render, NOT createRoot — this control is pinned to React 16.14.0 (the floor the
+// canvas runtime serves), 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 { {{componentName}}Component } from '../{{componentName}}/{{componentName}}Component';
+import { readField, saveField, type HttpError } from './harness/dataverse';
+
+/**
+ * Dev harness — renders the control against either a local value or a REAL Dataverse column.
+ *
+ *   - Mock — the local value below. Default; works with no org.
+ *   - Live — read a column off a record via the /api/data proxy, edit it in the control, and
+ *            Save it back. Enabled only when VITE_DYNAMICS_URL is set in `.env.local`.
+ *
+ * The read/edit/save round-trip is the point: `npm start` (pcf-scripts, :8181) can only feed
+ * this control hand-typed values, so it never proves the control round-trips real org data.
+ */
+
+interface FieldBinding {
+  entitySetName: string;
+  recordId: string;
+  column: string;
+}
+
+// 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;
+
+/**
+ * Minimal stand-in for the PCF context. Only the OptionSet variant reads it, for the bound
+ * column's choice metadata — note the UPPERCASE `Options`/`Value`/`Label`, which is the live
+ * PCF API shape, not the form-builder's design-time config. Harmless for the other variants,
+ * which ignore `context` entirely.
+ */
+const MOCK_CONTEXT = {
+  parameters: {
+    value: {
+      attributes: {
+        Options: [
+          { Value: 1, Label: 'Option A' },
+          { Value: 2, Label: 'Option B' },
+          { Value: 3, Label: 'Option C' },
+        ],
+      },
+    },
+  },
+} as unknown as ComponentFramework.Context<any>;
+
+/** Turn a failed live call into a red status line, calling out auth failures specifically. */
+function describeError(e: unknown, verb: string): 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 try again.'
+      : `Failed to ${verb}: ${err.message}`;
+  return <span style={{ color: '#a4262c' }}>{msg}</span>;
+}
+
+const Harness: React.FC = () => {
+  // Panel CONFIG persists across reloads (localStorage); the fetched VALUE does not.
+  const [width, setWidth] = usePersistedState('width', 320);
+  const [height, setHeight] = usePersistedState('height', 0);
+  const [theme, setTheme] = usePersistedState<ThemeChoice>('theme', 'light');
+  const [dataSource, setDataSource] = usePersistedState<DataSource>('dataSource', 'mock');
+  const [placeholder, setPlaceholder] = usePersistedState('placeholder', 'Enter a value');
+  const [disabled, setDisabled] = usePersistedState('disabled', false);
+  const [binding, setBinding] = usePersistedState<FieldBinding>('binding', {
+    entitySetName: 'accounts',
+    recordId: '',
+    column: 'accountcategorycode',
+  });
+
+  const [value, setValue] = React.useState<{{tsType}}>({{valueDefault}});
+  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;
+    }
+    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);
+    setValue({{valueDefault}});
+    setLiveStatus(
+      next === 'mock' ? null : <span style={{ color: '#605e5c' }}>Enter a binding and click Load.</span>,
+    );
+  };
+
+  const onLoadLive = (): void => {
+    void (async () => {
+      if (!binding.entitySetName || !binding.recordId || !binding.column) {
+        setLiveStatus(<span style={{ color: '#a4262c' }}>Enter entity set, record id and column.</span>);
+        return;
+      }
+      setLiveStatus(<span style={{ color: '#605e5c' }}>Loading…</span>);
+      try {
+        const { raw, formatted } = await readField(binding.entitySetName, binding.recordId, binding.column);
+        // The control owns its own typing; the harness hands the raw platform value straight
+        // through, exactly as the PCF host does via `context.parameters.value.raw`.
+        setValue(raw as {{tsType}});
+        setLiveStatus(
+          <span style={{ color: '#107c10' }}>
+            Loaded{formatted ? ` — "${formatted}"` : ''}.
+          </span>,
+        );
+      } catch (e) {
+        setLiveStatus(describeError(e, 'load'));
+      }
+    })();
+  };
+
+  const onSave = (): void => {
+    void (async () => {
+      setLiveStatus(<span style={{ color: '#605e5c' }}>Saving…</span>);
+      try {
+        await saveField(binding.entitySetName, binding.recordId, binding.column, value);
+        setLiveStatus(<span style={{ color: '#107c10' }}>Saved to the org.</span>);
+      } catch (e) {
+        setLiveStatus(describeError(e, 'save'));
+      }
+    })();
+  };
+
+  const bindingFields: HarnessField[] = [
+    {
+      kind: 'text',
+      label: 'Entity set (plural)',
+      placeholder: 'accounts',
+      value: binding.entitySetName,
+      onChange: (v) => setBinding((b) => ({ ...b, entitySetName: v })),
+    },
+    {
+      kind: 'text',
+      label: 'Record id (GUID)',
+      placeholder: '00000000-0000-0000-0000-000000000000',
+      value: binding.recordId,
+      onChange: (v) => setBinding((b) => ({ ...b, recordId: v })),
+    },
+    {
+      kind: 'text',
+      label: 'Column (logical name)',
+      placeholder: 'accountcategorycode',
+      value: binding.column,
+      onChange: (v) => setBinding((b) => ({ ...b, column: v })),
+    },
+  ];
+
+  return (
+    <HarnessShell
+      title="{{componentName}} — dev harness"
+      subtitle="Field control ({{propertyType}})"
+      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}
+      fields={[
+        { kind: 'text', label: 'placeholder', value: placeholder, onChange: setPlaceholder },
+        { kind: 'boolean', label: 'disabled', value: disabled, onChange: setDisabled },
+      ]}
+    >
+      <div style={{ width: width || 320 }}>
+        <{{componentName}}Component
+          value={value}
+          placeholder={placeholder}
+          disabled={disabled}
+          onChange={setValue}
+          onBlur={() => undefined}
+          context={MOCK_CONTEXT}
+        />
+        {dataSource === 'live' && (
+          <button
+            type="button"
+            onClick={onSave}
+            style={{ marginTop: 12, padding: '6px 14px', cursor: 'pointer' }}
+          >
+            Save to org
+          </button>
+        )}
+      </div>
+    </HarnessShell>
+  );
+};
+
+ReactDOM.render(<Harness />, document.getElementById('root'));

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

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

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

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

package/templates/pcf-field/package.json

@@ -7,7 +7,12 @@
     "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": {
     "@fluentui/react": "^8.120.0",
@@ -16,14 +21,18 @@
     "react-dom": "^16.14.0"
   },
   "devDependencies": {
+    "@dataverse-kit/pcf-dev-harness": "^0.2.0",
     "@microsoft/eslint-config-spfx": "^1.18.2",
     "@types/node": "^18.16.9",
     "@types/react": "^16.14.34",
     "@types/react-dom": "^16.9.17",
+    "@typescript-eslint/parser": "^6.21.0",
+    "@vitejs/plugin-react": "^4.3.4",
     "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-field/pcfconfig.json

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

package/templates/pcf-field/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-field/tsconfig.json

@@ -1,8 +1,24 @@
 {
   "extends": "./node_modules/pcf-scripts/tsconfig_base.json",
   "compilerOptions": {
-    "typeRoots": ["node_modules/@types"],
+    "typeRoots": [
+      "node_modules/@types"
+    ],
     "jsx": "react",
-    "experimentalDecorators": true
-  }
-}
+    "experimentalDecorators": true,
+    "skipLibCheck": true
+  },
+  "//": [
+    "\u2605 `exclude` REPLACES the base's [\"./node_modules\"] \u2014 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 \u2014 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-field/vite.config.ts

@@ -0,0 +1,60 @@
+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
+ *
+ * Complements `npm start` (the pcf-scripts harness on :8181) rather than replacing it: this
+ * control is control-type="standard" on React 16 and bundles its own React, so it loads fine
+ * in the stock harness. What the stock harness cannot do is show you REAL org data — it only
+ * takes hand-typed values. This one reads and writes an actual Dataverse column.
+ *
+ * Two data sources (see `dev/main.tsx`):
+ *   - Mock — a local value. Default; needs no org.
+ *   - Live — read a column off a real record through the same-origin `/api/data` proxy, edit
+ *            it, and save it back. 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; `envPrefix` below still limits what reaches 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 another 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 pins 16.14.0 (the floor the canvas runtime serves), and
+    // tsconfig sets `"jsx": "react"` (classic) for the same reason.
+    plugins: [react({ jsxRuntime: 'classic' }), live.plugin],
+    server: {
+      // 8182, because `pcf-scripts start` owns 8181 — both 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-field/{{componentName}}/ControlManifest.Input.xml

@@ -0,0 +1,42 @@
+<?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="standard">
+    <property name="value" display-name-key="Value" description-key="Value_Desc" of-type="{{propertyType}}" usage="bound" required="true" />
+    <property name="placeholder" display-name-key="Placeholder" description-key="Placeholder_Desc" of-type="SingleLine.Text" usage="input" required="false" />
+    <property name="disabled" display-name-key="Disabled" description-key="Disabled_Desc" of-type="TwoOptions" usage="input" required="false" default-value="false" />
+    <resources>
+      <code path="index.ts" order="1"/>
+      <!--
+        ★ DELIBERATELY NO <platform-library> HERE. This is a control-type="standard" control.
+
+        Microsoft scopes <platform-library> to "React controls & platform libraries", and
+        defines that feature as control-type="virtual" PLUS the platform-library children —
+        one feature, not two. Declaring them on a standard control is a half-state that
+        builds green and dies at runtime:
+
+          - With pcfReactPlatformLibraries at its shipped default ("off"),
+            platformLibrariesHandler externalises `react` but NOT `react-dom`. So the bundle
+            ships ReactDOM 16.14 wired to a platform React the model-driven host actually
+            loads as 17.0.2 — a cross-major ReactSharedInternals/event-system mismatch.
+          - Turning the flag ON instead externalises react-dom to the `ReactDOMv16` global,
+            which the platform only contracts to supply for VIRTUAL controls. Strictly worse.
+
+        So: bundle our own React 16.14 + Fluent 8. Nothing is externalised, therefore
+        installed == compiled == runtime and no version skew is possible. The bundle grows
+        (~1-1.5 MB minified); the 5 MB cap is enforced in production mode only.
+
+        If this control is ever converted to control-type="virtual", the versions declared
+        must EQUAL a served platform version, not merely fall inside pcf-scripts' matched
+        range — an in-range-but-unequal version builds green and cannot be resolved at
+        runtime ("Error loading control" in every host). Live-diagnosed 2026-07-26 on
+        host-swap: React 18.2.0 + Fluent 8.115.6, 15/15 build gates green, loaded nowhere.
+        Supported then: React 16.14.0 | 18.3.1; @fluentui/react 8.29.0 | 8.121.1;
+        @fluentui/react-components >=9.4.0 <=9.46.2. See src/__tests__/registry.test.ts.
+      -->
+      <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-field/{{{componentName}}Component.tsx → {{componentName}}/{{componentName}}Component.tsx}

@@ -11,7 +11,12 @@ export interface I{{componentName}}ComponentProps {
     disabled?: boolean;
     onChange: (value: {{tsType}}) => void;
     onBlur: () => void;
-    context: ComponentFramework.Context<any>;
+    /**
+     * The bound PCF context. OPTIONAL so the dev harness can render this component
+     * without a platform context (only the optionset variant reads it, for the
+     * bound column's choice metadata). The PCF host always supplies it.
+     */
+    context?: ComponentFramework.Context<any>;
 }
 
 export const {{componentName}}Component: React.FC<I{{componentName}}ComponentProps> = ({

package/templates/power-pages-island/README.md

@@ -79,3 +79,15 @@ This starter is **build-verified** (`tsc` + webpack bundle) and **localhost-mock
 (`npm run dev`). Live behavior against a real traditional portal (the web-file upload, the Liquid
 snippet, and `PortalSeamService` against live `/_api/`) is the deploy step above — verify it on your
 own portal.
+
+> **The artifact is live-verified (2026-07-26).** This template was deployed to a real traditional
+> (Liquid) Power Pages portal on the **enhanced data model** (`mspp_*` / `powerpagecomponent`): the
+> bundle mounted into a Liquid-placed `[data-dvkit-island]` node and `PortalSeamService` returned
+> **200** from `GET /_api/accounts?fetchXml=…` (the FetchXML read path the MS code-site scaffolder
+> generates none of), rendering live accounts in the DetailsList.
+>
+> **Deploy tip for enhanced-data-model portals:** after uploading the web file + placing the snippet,
+> run **⟳ Purge Cache** (Power Platform admin center → *Resources → Power Pages sites*) — traditional
+> portals serve a precompiled snapshot, so a freshly-added web file **404s** until the cache is purged.
+> The site is private until the signed-in user is a portal contact (first Entra sign-in auto-registers
+> one + attaches the Authenticated Users role).

package/templates/power-pages-island/src/App.tsx

@@ -3,6 +3,7 @@ import type { IApiService } from "./core/services/IApiService";
 import { MockApiService } from "./core/services/MockApiService";
 import { PortalSeamService } from "@dataverse-kit/portal-api-service";
 import { Component } from "./Component";
+import { useHostWidth } from "./useHostWidth";
 
 // A Power Pages island is served from the portal origin, so a same-origin `/_api`
 // fetch is authenticated by the portal session cookie + anti-forgery token —
@@ -21,5 +22,16 @@ export const App: React.FC<{ island?: string }> = () => {
     const onLocalhost = /^(localhost|127\.0\.0\.1)$/.test(window.location.hostname);
     return onLocalhost ? new MockApiService() : new PortalSeamService();
   }, []);
-  return <Component api={api} />;
+
+  // An island is mounted into a slot on a portal page, NOT a full-page iframe, so the
+  // viewport is the whole portal and would overstate the space available. Measure the
+  // island's own box instead — portals are heavily mobile, so this matters here most.
+  const hostRef = React.useRef<HTMLDivElement>(null);
+  const width = useHostWidth(hostRef);
+
+  return (
+    <div ref={hostRef}>
+      <Component api={api} width={width} />
+    </div>
+  );
 };

package/templates/power-pages-island/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>
   );
 };