@khester/create-dynamics-app 2.6.2 → 2.6.4

package/templates/host-swap/_variants/host.custom-page/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{projectName}}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/index.tsx"></script>
+  </body>
+</html>

package/templates/host-swap/_variants/host.custom-page/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.1.0",
+  "private": true,
+  "description": "{{projectName}} — host-swap component hosted as a Dynamics custom page (Vite)",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "dev": "vite",
+    "dev:token": "npm run auth:token && npm run dev",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist"
+  },
+  "dependencies": {
+    "@fluentui/react": "^8.110.10",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "@vitejs/plugin-react": "^4.2.1",
+    "rimraf": "^5.0.5",
+    "typescript": "^5.3.3",
+    "vite": "^5.4.21"
+  }
+}

package/templates/host-swap/_variants/host.custom-page/src/App.tsx

@@ -0,0 +1,14 @@
+import * as React from "react";
+import { ServiceFactory } from "./core/services/ServiceFactory";
+import { Component } from "./Component";
+
+// Resolve the Xrm context when hosted as a Dynamics custom page (the app runs in
+// an iframe → window.parent.Xrm, or window.Xrm). ServiceFactory then picks the
+// IApiService per environment: Mock on localhost, the token-proxy in dev, or the
+// production XrmApiService when deployed.
+const Xrm = (window.parent as any)?.Xrm ?? (window as any).Xrm;
+
+export const App: React.FC = () => {
+  const api = React.useMemo(() => ServiceFactory.createApiService(Xrm), []);
+  return <Component api={api} />;
+};

package/templates/host-swap/_variants/host.custom-page/src/index.tsx

@@ -0,0 +1,17 @@
+import React from "react";
+import { createRoot } from "react-dom/client";
+import { initLogging } from "@khester/reusable-components";
+import { App } from "./App";
+
+// Wire up the localhost-only troubleshooting hooks (window.dumpAppLogs()); no-op
+// in a live org.
+initLogging();
+
+const container = document.getElementById("root");
+if (!container) throw new Error('Root element "#root" not found');
+
+createRoot(container).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+);

package/templates/host-swap/_variants/host.custom-page/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "types": ["vite/client"]
+  },
+  "include": ["src"]
+}

package/templates/host-swap/_variants/host.custom-page/vite.config.ts

@@ -0,0 +1,63 @@
+import { defineConfig, loadEnv } from "vite";
+import react from "@vitejs/plugin-react";
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Read a single key from .env / .env.local at request time, so a refreshed
+ * `npm run auth:token` takes effect without restarting the dev server.
+ */
+function readEnvValue(key: string): string | undefined {
+  for (const file of [".env.local", ".env"]) {
+    const p = path.resolve(process.cwd(), file);
+    if (!fs.existsSync(p)) continue;
+    for (const line of fs.readFileSync(p, "utf8").split(/\r?\n/)) {
+      const m = line.match(/^([A-Z0-9_]+)=(.*)$/);
+      if (m && m[1] === key) return m[2];
+    }
+  }
+  return undefined;
+}
+
+export default defineConfig(({ mode }) => {
+  // DYNAMICS_URL / DYNAMICS_TOKEN are written to .env by `npm run auth:token`.
+  const env = loadEnv(mode, process.cwd(), "");
+  const dynamicsUrl = env.DYNAMICS_URL;
+
+  return {
+    // Relative base — the built bundle is served from the Dataverse web-resource
+    // CDN under a long prefixed path, where absolute /assets URLs would 404.
+    base: "./",
+    plugins: [react()],
+    server: {
+      port: 3000,
+      // Token-proxy mode: forward /api/data/* to Dataverse and inject the bearer
+      // SERVER-SIDE, so the token is never read by or bundled into the client.
+      proxy: dynamicsUrl
+        ? {
+            "/api/data": {
+              target: dynamicsUrl,
+              changeOrigin: true,
+              secure: true,
+              configure: (proxy) => {
+                proxy.on("proxyReq", (proxyReq) => {
+                  const token = readEnvValue("DYNAMICS_TOKEN");
+                  if (token) proxyReq.setHeader("Authorization", `Bearer ${token}`);
+                  proxyReq.setHeader("OData-Version", "4.0");
+                  proxyReq.setHeader("OData-MaxVersion", "4.0");
+                });
+              },
+            },
+          }
+        : undefined,
+    },
+    define: {
+      // Client flag for ServiceFactory — a real boolean (Vite stringifies it).
+      // True only when a Dataverse URL is configured (token-proxy dev mode).
+      "import.meta.env.VITE_USE_PROXY": Boolean(dynamicsUrl),
+    },
+    build: {
+      outDir: "dist",
+    },
+  };
+});

package/templates/host-swap/_variants/host.pcf/ControlManifest.Input.xml

@@ -0,0 +1,17 @@
+<?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 bound property so the control can be placed on a form field. The
+         component ignores it — it fetches its own data via the Web API. -->
+    <property name="value" display-name-key="value_Display_Key" description-key="value_Desc_Key" of-type="SingleLine.Text" usage="bound" required="false" />
+    <resources>
+      <code path="index.ts" order="1"/>
+      <platform-library name="React" version="18.2.0" />
+      <platform-library name="Fluent" version="8.115.6" />
+      <resx path="strings/{{componentName}}.1033.resx" version="1.0.0" />
+    </resources>
+    <feature-usage>
+      <uses-feature name="WebAPI" required="true" />
+    </feature-usage>
+  </control>
+</manifest>

package/templates/host-swap/_variants/host.pcf/featureconfig.json

@@ -0,0 +1,3 @@
+{
+  "pcfReactPlatformLibraries": "on"
+}

package/templates/host-swap/_variants/host.pcf/gitignore

@@ -0,0 +1,5 @@
+node_modules/
+out/
+generated/
+*.log
+.env

package/templates/host-swap/_variants/host.pcf/index.ts

@@ -0,0 +1,44 @@
+import { IInputs, IOutputs } from "./generated/ManifestTypes";
+import * as React from "react";
+import { Component } from "./src/Component";
+import type { IApiService } from "./src/core/services/IApiService";
+import { FetchApiService } from "./src/core/services/FetchApiService";
+import { MockApiService } from "./src/core/services/MockApiService";
+
+/**
+ * PCF host wrapper for the shared Component. A React (virtual) control: the
+ * platform owns the React root, so updateView returns the element.
+ *
+ * It builds the IApiService DIRECTLY rather than via the Vite-coupled
+ * ServiceFactory: in a model-driven host the control 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 clientUrl needed. On localhost (the pcf-scripts
+ * test harness) it falls back to the in-memory mock so the control renders with
+ * no org.
+ */
+export class {{componentName}} implements ComponentFramework.ReactControl<IInputs, IOutputs> {
+  private api!: IApiService;
+
+  public init(
+    _context: ComponentFramework.Context<IInputs>,
+    _notifyOutputChanged: () => void,
+    _state: ComponentFramework.Dictionary,
+  ): void {
+    const onLocalhost =
+      typeof window !== "undefined" &&
+      /^(localhost|127\.0\.0\.1)$/.test(window.location.hostname);
+    this.api = onLocalhost ? new MockApiService() : new FetchApiService("");
+  }
+
+  public updateView(_context: ComponentFramework.Context<IInputs>): React.ReactElement {
+    return React.createElement(Component, { api: this.api });
+  }
+
+  public getOutputs(): IOutputs {
+    return {};
+  }
+
+  public destroy(): void {
+    // React root teardown is handled by the platform for virtual controls.
+  }
+}

package/templates/host-swap/_variants/host.pcf/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "{{projectName}}",
+  "version": "1.0.0",
+  "description": "{{componentName}} — host-swap component hosted as a PCF control",
+  "scripts": {
+    "build": "pcf-scripts build",
+    "clean": "pcf-scripts clean",
+    "rebuild": "pcf-scripts rebuild",
+    "start": "pcf-scripts start",
+    "refreshTypes": "pcf-scripts refreshTypes"
+  },
+  "dependencies": {
+    "@fluentui/react": "^8.120.0",
+    "@types/powerapps-component-framework": "^1.3.18",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@microsoft/eslint-config-spfx": "^1.18.2",
+    "@types/node": "^18.16.9",
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "eslint-plugin-react-hooks": "^4.6.0",
+    "pcf-scripts": "^1",
+    "pcf-start": "^1",
+    "typescript": "^5.3.0"
+  },
+  "browserslist": [
+    "last 2 versions"
+  ]
+}

package/templates/host-swap/_variants/host.pcf/pcf-env.d.ts

@@ -0,0 +1,9 @@
+// PCF builds have no `vite/client` types. The shared data-access seam
+// (templates/_shared/dataverse-seam) includes ServiceFactory, which reads
+// `import.meta.env.VITE_USE_PROXY` for the Vite custom-page host. The PCF wrapper
+// does NOT use ServiceFactory (it builds FetchApiService/MockApiService directly),
+// so the file is tree-shaken out of the bundle — but pcf-scripts still typechecks
+// it. This minimal ambient declaration lets that unused file compile here.
+interface ImportMeta {
+  readonly env: Record<string, unknown>;
+}

package/templates/host-swap/_variants/host.pcf/strings/{{componentName}}.1033.resx

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="utf-8"?>
+<root>
+  <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>
+    <comment>Name of the control</comment>
+  </data>
+  <data name="{{namespace}}_{{componentName}}_Desc" xml:space="preserve">
+    <value>{{componentName}} host-swap control built with Dynamics UI Kit</value>
+    <comment>Description of the control</comment>
+  </data>
+  <data name="value_Display_Key" xml:space="preserve">
+    <value>Value</value>
+    <comment>Display name for the bound property</comment>
+  </data>
+  <data name="value_Desc_Key" xml:space="preserve">
+    <value>Bound field (ignored — the component fetches its own data)</value>
+    <comment>Description for the bound property</comment>
+  </data>
+</root>

package/templates/host-swap/_variants/host.pcf/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./node_modules/pcf-scripts/tsconfig_base.json",
+  "compilerOptions": {
+    "typeRoots": ["node_modules/@types"],
+    "jsx": "react",
+    "esModuleInterop": true,
+    "experimentalDecorators": true
+  }
+}

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

@@ -0,0 +1,89 @@
+import * as React from "react";
+import {
+  DetailsList,
+  SelectionMode,
+  MessageBar,
+  MessageBarType,
+  Spinner,
+  Stack,
+  Text,
+  type IColumn,
+} from "@fluentui/react";
+import { initializeIcons } from "@fluentui/react/lib/Icons";
+import type { IApiService } from "./core/services/IApiService";
+
+// Initialize Fluent UI icons once (DetailsList sort/column glyphs).
+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.
+ */
+export interface ComponentProps {
+  api: IApiService;
+}
+
+const ACCOUNTS_FETCHXML = [
+  '<fetch top="25">',
+  '  <entity name="account">',
+  '    <attribute name="accountid" />',
+  '    <attribute name="name" />',
+  '    <attribute name="telephone1" />',
+  '    <order attribute="name" />',
+  "  </entity>",
+  "</fetch>",
+].join("\n");
+
+interface AccountRow {
+  accountid: string;
+  name?: string;
+  telephone1?: string;
+}
+
+const COLUMNS: IColumn[] = [
+  { key: "name", name: "Account", fieldName: "name", minWidth: 180, maxWidth: 320, isResizable: true },
+  { key: "telephone1", name: "Phone", fieldName: "telephone1", minWidth: 140, isResizable: true },
+];
+
+export const Component: React.FC<ComponentProps> = ({ api }) => {
+  const [rows, setRows] = React.useState<AccountRow[] | null>(null);
+  const [error, setError] = React.useState<string | null>(null);
+
+  React.useEffect(() => {
+    let cancelled = false;
+    api
+      .retrieveMultipleRecords("accounts", ACCOUNTS_FETCHXML)
+      .then((res) => {
+        if (!cancelled) setRows(res.entities as AccountRow[]);
+      })
+      .catch((e) => {
+        if (!cancelled) setError(e instanceof Error ? e.message : String(e));
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [api]);
+
+  return (
+    <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.
+      </Text>
+      {error && <MessageBar messageBarType={MessageBarType.error}>{error}</MessageBar>}
+      {!rows && !error && <Spinner label="Loading accounts…" />}
+      {rows && (
+        <DetailsList
+          items={rows}
+          columns={COLUMNS}
+          setKey="accounts"
+          getKey={(item: AccountRow) => item.accountid}
+          selectionMode={SelectionMode.none}
+        />
+      )}
+    </Stack>
+  );
+};

package/templates/host-swap/src/core/services/MockApiService.ts

@@ -0,0 +1,58 @@
+import { IApiService } from "./IApiService";
+import { logCrud } from "./crudLogging";
+
+// A few seeded in-memory accounts so the control/page renders with no org or
+// token (the PCF test harness and `npm run dev` both land here). Replace this
+// seed as your component grows. The other IApiService impls (Xrm/Fetch) and the
+// shared contract are pulled from templates/_shared/dataverse-seam at scaffold.
+const SEED_ACCOUNTS = [
+  { accountid: "00000000-0000-0000-0000-000000000001", name: "Contoso Ltd", telephone1: "+1 (425) 555-0100" },
+  { accountid: "00000000-0000-0000-0000-000000000002", name: "Fabrikam Inc", telephone1: "+1 (206) 555-0140" },
+  { accountid: "00000000-0000-0000-0000-000000000003", name: "Adventure Works", telephone1: "+1 (312) 555-0190" },
+];
+
+export class MockApiService implements IApiService {
+  private accounts: Record<string, any> = Object.fromEntries(
+    SEED_ACCOUNTS.map((a) => [a.accountid, { ...a }]),
+  );
+  private nextId = SEED_ACCOUNTS.length + 1;
+
+  retrieveMultipleRecords(entity: string): Promise<{ entities: any[] }> {
+    return logCrud(
+      { op: "READ", entity, resultCount: (r) => r?.entities?.length },
+      async () => ({
+        entities: entity === "accounts" ? Object.values(this.accounts) : [],
+      }),
+    );
+  }
+
+  createRecord(entity: string, record: any): Promise<any> {
+    return logCrud({ op: "CREATE", entity, resultId: (r) => r?.id }, async () => {
+      const id = `00000000-0000-0000-0000-${String(this.nextId++).padStart(12, "0")}`;
+      if (entity === "accounts") this.accounts[id] = { accountid: id, ...record };
+      return { id };
+    });
+  }
+
+  updateRecord(entity: string, id: string, record: any): Promise<any> {
+    return logCrud({ op: "UPDATE", entity, id }, async () => {
+      const key = id.replace(/[{}]/g, "");
+      if (this.accounts[key]) this.accounts[key] = { ...this.accounts[key], ...record };
+      return { success: true };
+    });
+  }
+
+  deleteRecord(entity: string, id: string): Promise<void> {
+    return logCrud({ op: "DELETE", entity, id }, async () => {
+      delete this.accounts[id.replace(/[{}]/g, "")];
+    });
+  }
+
+  executeRequest(requestName: string): Promise<any> {
+    return logCrud({ op: "EXECUTE", entity: requestName }, async () => ({}));
+  }
+
+  associateRecord(entity: string, id: string): Promise<void> {
+    return logCrud({ op: "ASSOCIATE", entity, id }, async () => undefined);
+  }
+}

package/templates/react-custom-page/src/core/services/MockApiService.ts

@@ -60,10 +60,6 @@ export class MockApiService implements IApiService {
     return logCrud({ op: "EXECUTE", entity: requestName }, async () => ({}));
   }
 
-  async uploadFile(): Promise<string> {
-    return "";
-  }
-
   associateRecord(entityName: string, entityId: string): Promise<void> {
     return logCrud(
       { op: "ASSOCIATE", entity: entityName, id: entityId },

package/templates/grid-starter/src/core/services/XrmApiService.ts

@@ -1,135 +0,0 @@
-import { IApiService } from "./IApiService";
-import { logCrud } from "./crudLogging";
-import { logger } from "@khester/reusable-components";
-
-/**
- * Production API service for a model-driven custom page. Every call hits the
- * Dataverse Web API on the same origin (the hosting org authenticates the
- * request via its session), addressing entities by their SET name (e.g.
- * "accounts") so reads and writes use one consistent identifier.
- */
-export class XrmApiService implements IApiService {
-  private Xrm: any;
-
-  constructor(Xrm: any) {
-    if (!Xrm) throw new Error("Xrm object is required");
-    this.Xrm = Xrm;
-  }
-
-  private clientUrl(): string {
-    return this.Xrm.Page.context.getClientUrl();
-  }
-
-  private headers(): HeadersInit {
-    return {
-      "OData-MaxVersion": "4.0",
-      "OData-Version": "4.0",
-      "Content-Type": "application/json; charset=utf-8",
-      Accept: "application/json",
-      Prefer: 'odata.include-annotations="*"',
-    };
-  }
-
-  retrieveMultipleRecords(
-    entity: string,
-    fetchXml: string,
-  ): Promise<{ entities: any[] }> {
-    return logCrud(
-      { op: "READ", entity, resultCount: (r) => r?.entities?.length },
-      async () => {
-        const url = `${this.clientUrl()}/api/data/v9.2/${entity}?fetchXml=${encodeURIComponent(fetchXml)}`;
-        const response = await fetch(url, { method: "GET", headers: this.headers() });
-        if (!response.ok) throw await response.json();
-        const data = await response.json();
-        return { entities: data.value ?? [] };
-      },
-    );
-  }
-
-  createRecord(entity: string, record: any): Promise<any> {
-    return logCrud({ op: "CREATE", entity, resultId: (r) => r?.id }, async () => {
-      const url = `${this.clientUrl()}/api/data/v9.2/${entity}`;
-      const response = await fetch(url, {
-        method: "POST",
-        headers: this.headers(),
-        body: JSON.stringify(record),
-      });
-      if (!response.ok) throw await response.json();
-      const uri = response.headers.get("OData-EntityId");
-      const match = uri ? /\(([^)]+)\)/.exec(uri) : null;
-      return { id: match ? match[1] : null };
-    });
-  }
-
-  updateRecord(entity: string, id: string, record: any): Promise<any> {
-    return logCrud({ op: "UPDATE", entity, id }, async () => {
-      const cleanId = id.replace(/[{}]/g, "");
-      const url = `${this.clientUrl()}/api/data/v9.2/${entity}(${cleanId})`;
-      const response = await fetch(url, {
-        method: "PATCH",
-        headers: this.headers(),
-        body: JSON.stringify(record),
-      });
-      if (!response.ok) throw await response.json();
-      return { success: true };
-    });
-  }
-
-  deleteRecord(entity: string, id: string): Promise<void> {
-    return logCrud({ op: "DELETE", entity, id }, async () => {
-      const cleanId = id.replace(/[{}]/g, "");
-      const url = `${this.clientUrl()}/api/data/v9.2/${entity}(${cleanId})`;
-      const response = await fetch(url, { method: "DELETE", headers: this.headers() });
-      if (!response.ok) throw await response.json();
-    });
-  }
-
-  executeRequest(requestName: string, requestData: any): Promise<any> {
-    return logCrud({ op: "EXECUTE", entity: requestName }, async () => {
-      const { getMetadata: _getMetadata, ...payload } = requestData ?? {};
-      const url = `${this.clientUrl()}/api/data/v9.2/${requestName}`;
-      const response = await fetch(url, {
-        method: "POST",
-        headers: this.headers(),
-        body: JSON.stringify(payload),
-      });
-      if (!response.ok) throw await response.json();
-      const text = await response.text();
-      return text ? JSON.parse(text) : null;
-    });
-  }
-
-  async associateRecord(
-    entityName: string,
-    entityId: string,
-    relationshipName: string,
-    relatedEntityName: string,
-    relatedEntityId: string,
-  ): Promise<void> {
-    return logCrud(
-      { op: "ASSOCIATE", entity: entityName, id: entityId },
-      async () => {
-        const url = `${this.clientUrl()}/api/data/v9.2/${entityName}(${entityId})/${relationshipName}/$ref`;
-        const response = await fetch(url, {
-          method: "POST",
-          headers: this.headers(),
-          body: JSON.stringify({
-            "@odata.id": `${this.clientUrl()}/api/data/v9.2/${relatedEntityName}(${relatedEntityId})`,
-          }),
-        });
-        if (!response.ok) {
-          throw new Error(`associateRecord failed (${response.status})`);
-        }
-      },
-    );
-  }
-
-  async uploadFile(file: File): Promise<string> {
-    // Stub — wire up to your file/notes/blob strategy as needed.
-    logger.warn("uploadFile not implemented", {
-      source: "XrmApiService",
-      data: { file: file.name },
-    });
-    return "";
-  }
-}