@khester/create-dynamics-app 2.0.0 → 2.2.0

package/templates/grid-starter/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/grid-starter/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", "vitest/globals"]
+  },
+  "include": ["src"]
+}

package/templates/grid-starter/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"],
+    },
+  };
+});

package/templates/pcf-field/_variants/ValueInput.boolean.tsx

@@ -7,6 +7,8 @@ export interface ValueInputProps {
     disabled?: boolean;
     onChange: (value: boolean) => void;
     onBlur: () => void;
+    /** Optional PCF context (forwarded uniformly; only the optionset variant reads it). */
+    context?: ComponentFramework.Context<any>;
 }
 
 export const ValueInput: React.FC<ValueInputProps> = ({

package/templates/pcf-field/_variants/ValueInput.date.tsx

@@ -7,6 +7,8 @@ export interface ValueInputProps {
     disabled?: boolean;
     onChange: (value: Date | null) => void;
     onBlur: () => void;
+    /** Optional PCF context (forwarded uniformly; only the optionset variant reads it). */
+    context?: ComponentFramework.Context<any>;
 }
 
 export const ValueInput: React.FC<ValueInputProps> = ({

package/templates/pcf-field/_variants/ValueInput.number.tsx

@@ -7,6 +7,8 @@ export interface ValueInputProps {
     disabled?: boolean;
     onChange: (value: number | null) => void;
     onBlur: () => void;
+    /** Optional PCF context (forwarded uniformly; only the optionset variant reads it). */
+    context?: ComponentFramework.Context<any>;
 }
 
 export const ValueInput: React.FC<ValueInputProps> = ({

package/templates/pcf-field/_variants/ValueInput.optionset.tsx

@@ -0,0 +1,77 @@
+import * as React from 'react';
+import { Dropdown, IDropdownOption } from '@fluentui/react/lib/Dropdown';
+import { TextField } from '@fluentui/react/lib/TextField';
+
+export interface ValueInputProps {
+    value: number | null;
+    placeholder?: string;
+    disabled?: boolean;
+    onChange: (value: number | null) => void;
+    onBlur: () => void;
+    /**
+     * The bound PCF context. OptionSet choices are read at runtime from the bound
+     * column's metadata: `context.parameters.value.attributes.Options` is the
+     * platform-supplied `Array<{ Value: number; Label: string }>` (note the
+     * UPPERCASE field names — this is the live PCF API, not the form-builder's
+     * design-time config). `context` is typed `<any>`, so this access is
+     * unchecked: keep `Options` / `Value` / `Label` spelled exactly.
+     */
+    context?: ComponentFramework.Context<any>;
+}
+
+export const ValueInput: React.FC<ValueInputProps> = ({
+    value,
+    placeholder,
+    disabled,
+    onChange,
+    onBlur,
+    context,
+}) => {
+    const rawOptions = context?.parameters?.value?.attributes?.Options as
+        | Array<{ Value: number; Label: string }>
+        | undefined;
+    const options: IDropdownOption[] = (rawOptions ?? []).map(
+        (o: { Value: number; Label: string }) => ({ key: o.Value, text: o.Label })
+    );
+
+    // Degrade to a numeric input when no choice metadata is available — e.g. an
+    // unbound control or a test harness. An empty dropdown is unusable, so we fall
+    // back to a raw option-value number entry (mirrors the form-builder's
+    // optionset → number convention). NOTE: an empty `Options` is ambiguous — it
+    // means either "genuinely no choices" or "wrong metadata path"; the unit test
+    // pins the path so only the legitimate case reaches here.
+    if (options.length === 0) {
+        return (
+            <TextField
+                type="number"
+                value={value === null ? '' : String(value)}
+                placeholder={placeholder}
+                disabled={disabled}
+                onChange={(_, v) => {
+                    if (!v) {
+                        onChange(null);
+                        return;
+                    }
+                    const n = Number(v);
+                    onChange(Number.isNaN(n) ? null : n);
+                }}
+                onBlur={onBlur}
+                styles={{ root: { width: '100%' } }}
+            />
+        );
+    }
+
+    return (
+        <Dropdown
+            selectedKey={value ?? undefined}
+            placeholder={placeholder}
+            disabled={disabled}
+            options={options}
+            onChange={(_, option) =>
+                onChange(typeof option?.key === 'number' ? option.key : null)
+            }
+            onBlur={onBlur}
+            styles={{ root: { width: '100%' } }}
+        />
+    );
+};

package/templates/pcf-field/_variants/ValueInput.text.tsx

@@ -7,6 +7,8 @@ export interface ValueInputProps {
     disabled?: boolean;
     onChange: (value: string) => void;
     onBlur: () => void;
+    /** Optional PCF context (forwarded uniformly; only the optionset variant reads it). */
+    context?: ComponentFramework.Context<any>;
 }
 
 export const ValueInput: React.FC<ValueInputProps> = ({

package/templates/pcf-field/index.ts

@@ -51,7 +51,7 @@ export class {{componentName}} implements ComponentFramework.StandardControl<IIn
 
     public getOutputs(): IOutputs {
         return {
-            value: this._value
+            value: this._value ?? undefined
         };
     }
 

package/templates/pcf-field/package.json

@@ -11,7 +11,9 @@
   },
   "dependencies": {
     "@fluentui/react": "^8.110.10",
-    "@types/powerapps-component-framework": "^1.3.4"
+    "@types/powerapps-component-framework": "^1.3.4",
+    "react": "^16.14.0",
+    "react-dom": "^16.14.0"
   },
   "devDependencies": {
     "@microsoft/eslint-config-spfx": "^1.18.2",

package/templates/pcf-field/{{componentName}}Component.tsx

@@ -20,6 +20,7 @@ export const {{componentName}}Component: React.FC<I{{componentName}}ComponentPro
     disabled,
     onChange,
     onBlur,
+    context,
 }) => {
     return (
         <div style={{ width: '100%', height: '100%' }}>
@@ -29,6 +30,7 @@ export const {{componentName}}Component: React.FC<I{{componentName}}ComponentPro
                 disabled={disabled}
                 onChange={onChange}
                 onBlur={onBlur}
+                context={context}
             />
         </div>
     );

package/templates/react-custom-page/ARCHITECTURE.md

@@ -0,0 +1,75 @@
+# Architecture
+
+A small, layered custom page. The goal is that **business logic lives in pure,
+testable functions** and the React component stays thin.
+
+## Layers
+
+```
+@khester/reusable-components      UI primitives + theme + logging (npm dependency)
+        │  (imported)
+        ▼
+src/example/   ExamplePage.tsx      view — JSX only, no CRUD
+               hooks/               view-models — state, handlers, dirty tracking
+               mappers/             PURE entity <-> form translation  (unit-tested)
+               models/Account.ts    where CRUD lives (calls IApiService)
+        │
+        ▼
+src/domain/    diff.ts              PURE change detection             (unit-tested)
+        │
+        ▼
+src/core/services/  IApiService     the data-access contract
+                    ServiceFactory  picks one impl per environment (the seam)
+                    Mock / Fetch / Xrm   three implementations
+```
+
+**Dependency rule (one direction):** view → hook → pure domain/mapper → model →
+`IApiService`. Nothing below imports from `example/`; `core/` imports nothing app-
+specific. UI/theme/logging are consumed from the package, never reached into.
+
+## The thin-form pattern
+
+| Concern | Lives in | Why |
+|---------|----------|-----|
+| Rendering | `ExamplePage.tsx` | swap freely; no logic to retest |
+| State + handlers | `hooks/useExampleForm` | view-model, not the view |
+| Load | `hooks/useExampleData` | data fetching isolated from form state |
+| Field ↔ attribute mapping | `mappers/accountMapper` | pure → cheap to unit-test |
+| Change detection | `domain/diff` | pure; sends only changed fields to Dataverse |
+| CRUD | `models/Account` | one place that talks to `IApiService` |
+
+The component calls two hooks and renders. It never builds a Dataverse payload or
+calls a service directly.
+
+## The ServiceFactory seam
+
+`ServiceFactory.createApiService(Xrm)` is the single decision point:
+
+- **Mock** (`localhost`, no `DYNAMICS_URL`) → `MockApiService`, in-memory.
+- **Token** (`localhost` + `DYNAMICS_URL`) → `FetchApiService`. `vite.config.ts`
+  sets `import.meta.env.VITE_USE_PROXY` (a boolean via `define`) and proxies
+  `/api/data/*` to the org, injecting the bearer **server-side**. The token never
+  reaches the client bundle — an intentional improvement over inlining it.
+- **Production** (deployed) → `XrmApiService`, hitting the Web API on the same
+  origin (session auth). `Xrm` is resolved from `window.parent` in `App.tsx`.
+
+All three implement the same `IApiService` and address entities by their Web API
+**set name** (e.g. `accounts`), so reads and writes use one consistent identifier.
+
+## Logging
+
+`logger` / `withCrudLog` / `initLogging` come from the component library.
+`core/services/crudLogging.ts` binds `withCrudLog` to the Dataverse error shapes
+so every service method emits one structured `[CRUD] …` line. Console output is
+**localhost-gated** (errors always surface); on localhost the buffer is exposed as
+`window.__APP_LOGS__` + `window.dumpAppLogs(filter?)`.
+
+## Testing
+
+Unit-test the **pure layers** — they hold the rules and need no DOM:
+
+- `src/domain/diff.test.ts`
+- `src/example/mappers/accountMapper.test.ts`
+
+The view and the `IApiService` implementations are best covered by running the app
+against the mock seam (`npm run dev`). Run `npm run test` (Vitest).