@khester/create-dynamics-app 2.1.0 → 2.2.0

package/templates/react-custom-page/src/example/hooks/useExampleForm.ts

@@ -0,0 +1,99 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { IApiService } from "../../core/services/IApiService";
+import { Account, IAccount } from "../models/Account";
+import {
+  AccountForm,
+  AccountFormField,
+  ACCOUNT_FORM_FIELDS,
+  toFormFields,
+  toUpdatePayload,
+} from "../mappers/accountMapper";
+import { changedKeys, hasChanged } from "../../domain/diff";
+import { normalizeDataverseError } from "../exampleError";
+
+const EMPTY: AccountForm = {
+  name: "",
+  accountNumber: "",
+  phone: "",
+  email: "",
+  website: "",
+};
+
+export interface ExampleFormState {
+  form: AccountForm;
+  isDirty: boolean;
+  isSaving: boolean;
+  saveError: string | null;
+  saveSucceeded: boolean;
+  setField: (field: AccountFormField, value: string) => void;
+  save: () => void;
+  reset: () => void;
+}
+
+/**
+ * View-model for the account form: holds editable state + a baseline snapshot,
+ * computes dirtiness via the pure `diff` helpers, and persists only the changed
+ * fields. The component renders this state — it owns no business logic.
+ */
+export function useExampleForm(
+  api: IApiService,
+  account: IAccount | null,
+): ExampleFormState {
+  const [form, setForm] = useState<AccountForm>(EMPTY);
+  const initialRef = useRef<AccountForm | null>(null);
+  const [isSaving, setIsSaving] = useState(false);
+  const [saveError, setSaveError] = useState<string | null>(null);
+  const [saveSucceeded, setSaveSucceeded] = useState(false);
+
+  // Re-seed the form (and the baseline) whenever a freshly-loaded account arrives.
+  useEffect(() => {
+    if (!account) return;
+    const fields = toFormFields(account);
+    setForm(fields);
+    initialRef.current = fields;
+  }, [account]);
+
+  const setField = useCallback((field: AccountFormField, value: string) => {
+    setForm((prev) => ({ ...prev, [field]: value }));
+    setSaveSucceeded(false);
+  }, []);
+
+  const isDirty = hasChanged(form, initialRef.current, ACCOUNT_FORM_FIELDS);
+
+  const save = useCallback(() => {
+    if (!account) return;
+    const changed = changedKeys(form, initialRef.current, ACCOUNT_FORM_FIELDS);
+    if (changed.length === 0) return;
+
+    setIsSaving(true);
+    setSaveError(null);
+    setSaveSucceeded(false);
+    Account.update(api, account.accountId, toUpdatePayload(changed, form))
+      .then(() => {
+        initialRef.current = form;
+        setSaveSucceeded(true);
+      })
+      .catch((e) =>
+        setSaveError(normalizeDataverseError(e, "Failed to save account.")),
+      )
+      .finally(() => setIsSaving(false));
+  }, [api, account, form]);
+
+  // Revert unsaved edits back to the last loaded/saved baseline.
+  const reset = useCallback(() => {
+    if (initialRef.current) setForm(initialRef.current);
+    setSaveError(null);
+    setSaveSucceeded(false);
+  }, []);
+
+  return {
+    form,
+    isDirty,
+    isSaving,
+    saveError,
+    saveSucceeded,
+    setField,
+    save,
+    reset,
+  };
+}

package/templates/react-custom-page/src/example/mappers/accountMapper.test.ts

@@ -0,0 +1,38 @@
+import { describe, it, expect } from "vitest";
+import { toFormFields, toUpdatePayload } from "./accountMapper";
+import type { IAccount } from "../models/Account";
+
+const sample: IAccount = {
+  accountId: "acc-1",
+  name: "Contoso",
+  accountNumber: "ACC-1",
+  phone: "555-0100",
+  email: "a@contoso.example",
+  website: "https://contoso.example",
+};
+
+describe("toFormFields", () => {
+  it("projects the editable fields from an account", () => {
+    expect(toFormFields(sample)).toEqual({
+      name: "Contoso",
+      accountNumber: "ACC-1",
+      phone: "555-0100",
+      email: "a@contoso.example",
+      website: "https://contoso.example",
+    });
+  });
+});
+
+describe("toUpdatePayload", () => {
+  it("maps only the changed fields to their Dataverse attribute names", () => {
+    const form = { ...toFormFields(sample), name: "Fabrikam", phone: "999" };
+    expect(toUpdatePayload(["name", "phone"], form)).toEqual({
+      name: "Fabrikam",
+      telephone1: "999",
+    });
+  });
+
+  it("returns an empty payload when nothing changed", () => {
+    expect(toUpdatePayload([], toFormFields(sample))).toEqual({});
+  });
+});

package/templates/react-custom-page/src/example/mappers/accountMapper.ts

@@ -0,0 +1,55 @@
+import { IAccount } from "../models/Account";
+
+// Pure translation between the Dataverse-shaped IAccount and the form's editable
+// fields. Keeping it pure makes it the cheapest layer to unit-test (see the
+// adjacent .test.ts) and keeps the component free of any field-mapping logic.
+
+export interface AccountForm {
+  name: string;
+  accountNumber: string;
+  phone: string;
+  email: string;
+  website: string;
+}
+
+export type AccountFormField = keyof AccountForm;
+
+export const ACCOUNT_FORM_FIELDS: ReadonlyArray<AccountFormField> = [
+  "name",
+  "accountNumber",
+  "phone",
+  "email",
+  "website",
+];
+
+// Form field → Dataverse logical attribute name (for the update payload).
+const FIELD_TO_ATTR: Record<AccountFormField, string> = {
+  name: "name",
+  accountNumber: "accountnumber",
+  phone: "telephone1",
+  email: "emailaddress1",
+  website: "websiteurl",
+};
+
+/** Project an account into the flat, editable form shape. */
+export function toFormFields(account: IAccount): AccountForm {
+  return {
+    name: account.name,
+    accountNumber: account.accountNumber,
+    phone: account.phone,
+    email: account.email,
+    website: account.website,
+  };
+}
+
+/** Build a Dataverse update payload from only the changed form fields. */
+export function toUpdatePayload(
+  changed: ReadonlyArray<AccountFormField>,
+  form: AccountForm,
+): Record<string, string> {
+  const payload: Record<string, string> = {};
+  for (const field of changed) {
+    payload[FIELD_TO_ATTR[field]] = form[field];
+  }
+  return payload;
+}

package/templates/react-custom-page/src/example/models/Account.ts

@@ -0,0 +1,74 @@
+import { IApiService } from "../../core/services/IApiService";
+import { logger } from "@khester/reusable-components";
+
+// Dataverse `account` attribute logical names. Inlined here (no separate
+// constants file) so this model is the single source of truth for the fields
+// the page reads and writes. CRUD lives in the model — never in the component.
+const ATTR = {
+  id: "accountid",
+  name: "name",
+  accountNumber: "accountnumber",
+  phone: "telephone1",
+  email: "emailaddress1",
+  website: "websiteurl",
+} as const;
+
+const ENTITY_SET = "accounts";
+
+export interface IAccount {
+  accountId: string;
+  name: string;
+  accountNumber: string;
+  phone: string;
+  email: string;
+  website: string;
+}
+
+function attributes(): string {
+  return Object.values(ATTR)
+    .map((a) => `<attribute name="${a}" />`)
+    .join("");
+}
+
+function fromDataverse(record: any): IAccount {
+  return {
+    accountId: record[ATTR.id] ?? "",
+    name: record[ATTR.name] ?? "",
+    accountNumber: record[ATTR.accountNumber] ?? "",
+    phone: record[ATTR.phone] ?? "",
+    email: record[ATTR.email] ?? "",
+    website: record[ATTR.website] ?? "",
+  };
+}
+
+export const Account = {
+  /**
+   * Load a single account. When `id` is provided (production / token mode, e.g.
+   * from the custom-page `?id=` parameter) it fetches that record; otherwise it
+   * returns the first account (mock mode seeds exactly one).
+   */
+  async retrieveOne(api: IApiService, id?: string): Promise<IAccount | null> {
+    const filter = id
+      ? `<filter><condition attribute="${ATTR.id}" operator="eq" value="${id}" /></filter>`
+      : "";
+    const fetchXml = `<fetch top="1"><entity name="account">${attributes()}${filter}</entity></fetch>`;
+    const { entities } = await api.retrieveMultipleRecords(ENTITY_SET, fetchXml);
+    if (!entities.length) {
+      logger.warn("No account found", {
+        source: "Account.retrieveOne",
+        data: { id },
+      });
+      return null;
+    }
+    return fromDataverse(entities[0]);
+  },
+
+  /** Persist only the changed attributes (already mapped to logical names). */
+  update(
+    api: IApiService,
+    id: string,
+    changed: Record<string, unknown>,
+  ): Promise<any> {
+    return api.updateRecord(ENTITY_SET, id, changed);
+  },
+};

package/templates/react-custom-page/src/index.tsx

@@ -1,128 +1,18 @@
-import React, { useState, useCallback } from 'react';
-import { createRoot } from 'react-dom/client';
-import { Pivot, DynamicsPivotItemProps } from '@khester/dynamics-ui-components';
-import { ContactManagement } from './components/ContactManagement';
-import { AccountManagement } from './components/AccountManagement';
-import { DynamicsProvider } from './providers/DynamicsProvider';
-import { LoggingProvider } from './components/Logging/LoggingProvider';
-import { LoggingDebugPanel } from './components/Logging/LoggingDebugPanel';
-import { Logger } from './components/Logging/logger';
-import './styles/index.css';
-
-const App: React.FC = () => {
-  const [selectedTab, setSelectedTab] = useState<'contacts' | 'accounts'>(
-    'contacts'
-  );
-  const [showDebugPanel, setShowDebugPanel] = useState(false);
-
-  const handleTabChange = useCallback(
-    (item: DynamicsPivotItemProps) => {
-      const newTab = item.itemKey as 'contacts' | 'accounts';
-      Logger.userAction(
-        'Tab changed in main application',
-        { from: selectedTab, to: newTab },
-        'App.handleTabChange'
-      );
-      setSelectedTab(newTab);
-    },
-    [selectedTab]
-  );
-
-  const toggleDebugPanel = useCallback(() => {
-    setShowDebugPanel((prev) => !prev);
-    Logger.userAction(
-      showDebugPanel ? 'Debug panel closed' : 'Debug panel opened',
-      {},
-      'App.toggleDebugPanel'
-    );
-  }, [showDebugPanel]);
-
-  const renderContent = () => {
-    switch (selectedTab) {
-      case 'contacts':
-        return <ContactManagement />;
-      case 'accounts':
-        return <AccountManagement />;
-      default:
-        return <ContactManagement />;
-    }
-  };
-
-  return (
-    <LoggingProvider>
-      <DynamicsProvider>
-        <div className="app">
-          <header className="app-header">
-            <div className="app-header__content">
-              <div className="app-header__title">
-                <h1>Dynamics 365 Management Console</h1>
-                <p>Built with Dynamics UI Kit - Enhanced Template</p>
-              </div>
-              <div className="app-header__actions">
-                <button
-                  className="debug-toggle-btn"
-                  onClick={toggleDebugPanel}
-                  title="Toggle Debug Panel"
-                >
-                  🐛 Debug
-                </button>
-              </div>
-            </div>
-          </header>
-
-          <nav className="app-navigation">
-            <Pivot
-              items={[
-                {
-                  headerText: 'Contacts',
-                  itemKey: 'contacts',
-                  itemIcon: 'Contact',
-                },
-                {
-                  headerText: 'Accounts',
-                  itemKey: 'accounts',
-                  itemIcon: 'Building',
-                },
-              ]}
-              selectedKey={selectedTab}
-              onItemClick={handleTabChange}
-              linkFormat="tabs"
-            />
-          </nav>
-
-          <main className="app-main">{renderContent()}</main>
-
-          <footer className="app-footer">
-            <p>
-              &copy; 2024 Your Organization. Powered by Dynamics UI Kit v1.0
-            </p>
-          </footer>
-
-          {/* Debug Panel */}
-          {showDebugPanel && (
-            <div className="debug-panel-overlay">
-              <LoggingDebugPanel onClose={() => setShowDebugPanel(false)} />
-            </div>
-          )}
-        </div>
-      </DynamicsProvider>
-    </LoggingProvider>
-  );
-};
-
-// For development/testing
-if (typeof document !== 'undefined') {
-  const container = document.getElementById('root');
-  if (container) {
-    const root = createRoot(container);
-    root.render(<App />);
-  }
-}
-
-// Export for PCF integration
-export { App, ContactManagement, AccountManagement };
-export * from './components/ContactManagement';
-export * from './components/AccountManagement';
-export * from './providers/DynamicsProvider';
-export * from './pcf/ContactControlWrapper';
-export * from './pcf/MultiEntityControlWrapper';
+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. Fluent's initializeIcons() is called inside the component
+// library (via MessageBarComponent) — do NOT call it again here.
+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/react-custom-page/src/vite-env.d.ts

@@ -0,0 +1,15 @@
+/// <reference types="vite/client" />
+
+// Custom env keys exposed via `define` in vite.config.ts. `tsc` trusts THIS
+// declaration (it does not evaluate `define`), so the type must match the
+// runtime value the config injects (a boolean).
+interface ImportMetaEnv {
+  /** True when DYNAMICS_URL is configured (token-proxy dev mode). */
+  readonly VITE_USE_PROXY: boolean;
+  /** The org URL (not the token) for the dev panel readout; "" in production. */
+  readonly VITE_DYNAMICS_URL: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}

package/templates/react-custom-page/tools/deploy/deploy-webresource.cjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+/**
+ * Build + deploy: upload the single-file `dist/index.html` (from `npm run
+ * build:d365`) to Dataverse as an HTML web resource, then publish it.
+ *
+ * Reads DYNAMICS_URL + DYNAMICS_TOKEN from `.env` (run `npm run auth:token`
+ * first, or use `npm run deploy`, which refreshes the token for you).
+ *
+ * The web-resource unique name MUST start with a publisher prefix that exists in
+ * your org (e.g. `cr1a2_` or `new_`). Set it via WEBRESOURCE_NAME in `.env`, or:
+ *   node tools/deploy/deploy-webresource.cjs --name cr1a2_/myapp/index.html --solution MySolution
+ */
+const fs = require("fs");
+const path = require("path");
+
+function arg(name) {
+  const i = process.argv.indexOf(name);
+  return i !== -1 ? process.argv[i + 1] : undefined;
+}
+
+function readEnv(file) {
+  if (!fs.existsSync(file)) return {};
+  const out = {};
+  for (const line of fs.readFileSync(file, "utf8").split(/\r?\n/)) {
+    const m = line.match(/^([A-Z0-9_]+)=(.*)$/);
+    if (m) out[m[1]] = m[2];
+  }
+  return out;
+}
+
+const root = process.cwd();
+const env = readEnv(path.join(root, ".env"));
+const url = (arg("--url") || process.env.DYNAMICS_URL || env.DYNAMICS_URL || "").replace(/\/+$/, "");
+const token = arg("--token") || process.env.DYNAMICS_TOKEN || env.DYNAMICS_TOKEN;
+
+let pkgName = "custompage";
+try {
+  pkgName = require(path.join(root, "package.json")).name || pkgName;
+} catch {
+  /* keep default */
+}
+const name = arg("--name") || process.env.WEBRESOURCE_NAME || env.WEBRESOURCE_NAME || `new_/${pkgName}/index.html`;
+const solution = arg("--solution") || process.env.WEBRESOURCE_SOLUTION || env.WEBRESOURCE_SOLUTION;
+
+if (!url || !token) {
+  console.error("✗ Missing DYNAMICS_URL / DYNAMICS_TOKEN. Run `npm run auth:token -- --url https://<org>.crm.dynamics.com` first.");
+  process.exit(1);
+}
+
+const file = path.join(root, "dist", "index.html");
+if (!fs.existsSync(file)) {
+  console.error("✗ dist/index.html not found. Run `npm run build:d365` first.");
+  process.exit(1);
+}
+const content = fs.readFileSync(file).toString("base64");
+
+const api = `${url}/api/data/v9.2`;
+const headers = {
+  Authorization: `Bearer ${token}`,
+  "Content-Type": "application/json; charset=utf-8",
+  Accept: "application/json",
+  "OData-Version": "4.0",
+  "OData-MaxVersion": "4.0",
+};
+if (solution) headers["MSCRM.SolutionUniqueName"] = solution;
+
+async function req(method, urlPath, body) {
+  const res = await fetch(urlPath.startsWith("http") ? urlPath : `${api}/${urlPath}`, {
+    method,
+    headers,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(`${method} ${urlPath} → ${res.status}: ${text}`);
+  }
+  return res;
+}
+
+async function main() {
+  console.log(`→ Deploying "${name}" to ${url} ...`);
+
+  // 1. Upsert the web resource (find by unique name, then PATCH or POST).
+  const findRes = await req("GET", `webresourceset?$select=webresourceid&$filter=name eq '${encodeURIComponent(name)}'`);
+  const found = (await findRes.json()).value || [];
+  let id;
+  if (found.length) {
+    id = found[0].webresourceid;
+    await req("PATCH", `webresourceset(${id})`, { content });
+    console.log(`✓ Updated existing web resource (${id}).`);
+  } else {
+    const createRes = await req("POST", "webresourceset", {
+      name,
+      displayname: name,
+      webresourcetype: 1, // HTML
+      content,
+    });
+    const loc = createRes.headers.get("OData-EntityId") || "";
+    const match = /\(([^)]+)\)/.exec(loc);
+    id = match ? match[1] : null;
+    console.log(`✓ Created web resource (${id}).`);
+  }
+
+  // 2. Publish it.
+  const paramXml =
+    "<importexportxml><webresources><webresource>{" + id + "}</webresource></webresources></importexportxml>";
+  await req("POST", "PublishXml", { ParameterXml: paramXml });
+  console.log("✓ Published.");
+
+  console.log(`\nOpen it:  ${url}/WebResources/${name}`);
+  console.log("Or host it on a model-driven custom page / open via Xrm.Navigation.navigateTo.");
+}
+
+main().catch((e) => {
+  console.error("✗ Deploy failed:", e.message);
+  process.exit(1);
+});

package/templates/react-custom-page/tsconfig.json

@@ -1,29 +1,19 @@
 {
   "compilerOptions": {
-    "target": "es5",
-    "lib": ["dom", "dom.iterable", "es6"],
-    "allowJs": true,
-    "skipLibCheck": true,
-    "esModuleInterop": true,
-    "allowSyntheticDefaultImports": true,
-    "strict": true,
-    "forceConsistentCasingInFileNames": true,
-    "noFallthroughCasesInSwitch": true,
-    "module": "esnext",
-    "moduleResolution": "node",
+    "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"
+    "jsx": "react-jsx",
+    "types": ["vite/client", "vitest/globals"]
   },
-  "include": ["src/**/*"],
-  "exclude": [
-    "node_modules",
-    "build",
-    "dist",
-    "tools/**/*.template.ts",
-    "tools/**/templates/**/*.ts",
-    "**/templates/**/*",
-    "**/*.template.ts"
-  ]
+  "include": ["src"]
 }

package/templates/react-custom-page/vite.config.ts

@@ -0,0 +1,76 @@
+/// <reference types="vitest/config" />
+import { defineConfig, loadEnv } from "vite";
+import react from "@vitejs/plugin-react";
+import { viteSingleFile } from "vite-plugin-singlefile";
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Read a single key from .env / .env.local at request time. Re-reading per
+ * request (rather than capturing it at config eval) means 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`.
+  // Empty prefix loads unprefixed keys; we read ONLY the two below by name and
+  // never spread `env` into `define` (that would leak the whole environment).
+  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(), ...(mode === "d365" ? [viteSingleFile()] : [])],
+    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),
+      // The org URL (NOT the token) for the dev panel's Environment readout. Empty
+      // in a production build, so nothing leaks into a deployed web resource.
+      "import.meta.env.VITE_DYNAMICS_URL": JSON.stringify(dynamicsUrl ?? ""),
+    },
+    build: {
+      outDir: "dist",
+    },
+    test: {
+      // Pure layers only (diff, mappers) — no DOM needed.
+      globals: true,
+      include: ["src/**/*.test.ts"],
+    },
+  };
+});