@khester/create-dynamics-app 2.0.0 → 2.2.0

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

@@ -0,0 +1,58 @@
+import { IApiService } from "./IApiService";
+import { MockApiService } from "./MockApiService";
+import { XrmApiService } from "./XrmApiService";
+import { FetchApiService } from "./FetchApiService";
+import { logger } from "@khester/reusable-components";
+
+/**
+ * Single decision point for which IApiService the page talks to.
+ *
+ * Priority:
+ *   1. localhost + VITE_USE_PROXY → FetchApiService (real Dataverse via the Vite proxy)
+ *   2. localhost (no proxy)       → injected mock, or MockApiService by default
+ *   3. deployed + Xrm context     → XrmApiService
+ */
+export class ServiceFactory {
+  public static isMockEnvironment: boolean =
+    window.location.hostname === "localhost" ||
+    window.location.hostname === "127.0.0.1";
+
+  /**
+   * Token-proxy dev mode. `vite.config.ts` sets `import.meta.env.VITE_USE_PROXY`
+   * to a boolean — true when DYNAMICS_URL is configured — and proxies
+   * /api/data/* to Dataverse with a server-side bearer token. Truthiness check
+   * (NOT `=== 'true'`): the `define` value is a real boolean, not a string.
+   */
+  public static isTokenMode = !!import.meta.env.VITE_USE_PROXY;
+
+  /**
+   * @param Xrm        The Xrm context (required when deployed). Resolve it from
+   *                   `window.parent?.Xrm ?? window.Xrm` in App.tsx.
+   * @param createMock Optional factory for a domain-specific mock. Used ONLY in
+   *                   mock mode (after the token-mode check), so a token session
+   *                   still talks to the real org. Defaults to MockApiService.
+   */
+  public static createApiService(
+    Xrm?: any,
+    createMock?: () => IApiService,
+  ): IApiService {
+    if (ServiceFactory.isMockEnvironment && ServiceFactory.isTokenMode) {
+      logger.info("Token mode — using FetchApiService via proxy", {
+        source: "ServiceFactory",
+      });
+      return new FetchApiService();
+    }
+
+    if (ServiceFactory.isMockEnvironment) {
+      logger.info("Mock mode — using MockApiService", {
+        source: "ServiceFactory",
+      });
+      return (createMock ?? (() => new MockApiService()))();
+    }
+
+    if (!Xrm) {
+      throw new Error("Xrm object is required in a non-mock environment.");
+    }
+    return new XrmApiService(Xrm);
+  }
+}

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

@@ -0,0 +1,135 @@
+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 "";
+  }
+}

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

@@ -0,0 +1,52 @@
+// Binds the generic `withCrudLog` wrapper (from @khester/reusable-components) to
+// the Dataverse error shapes thrown by the IApiService implementations, so each
+// service method can be instrumented with a single `logCrud(meta, fn)` call.
+//
+// `parseServiceError` lives here (app/template code), not in the library — the
+// library's logger stays backend-agnostic and the app injects this parser.
+
+import { withCrudLog, type CrudMeta } from "@khester/reusable-components";
+
+/**
+ * Extract a numeric status + human message from the error shapes the services
+ * throw: an `Error("… 400: <body>")` whose body may embed a Dataverse error
+ * JSON blob, or a plain `json.error` object with a CDS InnerError message.
+ */
+function parseServiceError(err: unknown): { status?: number; message?: string } {
+  if (err && typeof err === "object" && !(err instanceof Error)) {
+    const obj = err as Record<string, unknown>;
+    const inner = obj["@Microsoft.PowerApps.CDS.InnerError.Message"];
+    const message =
+      (typeof inner === "string" && inner) ||
+      (typeof obj.message === "string" && obj.message) ||
+      undefined;
+    const status = typeof obj.status === "number" ? obj.status : undefined;
+    return { status, message: message || undefined };
+  }
+
+  if (err instanceof Error) {
+    const statusMatch = err.message.match(/\b(\d{3})\b/);
+    const status = statusMatch ? Number(statusMatch[1]) : undefined;
+
+    const jsonStart = err.message.indexOf("{");
+    if (jsonStart !== -1) {
+      try {
+        const parsed = JSON.parse(err.message.substring(jsonStart));
+        const inner =
+          parsed?.error?.["@Microsoft.PowerApps.CDS.InnerError.Message"];
+        const message = inner || parsed?.error?.message || err.message;
+        return { status, message };
+      } catch {
+        // not JSON — fall through to the raw message
+      }
+    }
+    return { status, message: err.message };
+  }
+
+  return { message: String(err) };
+}
+
+/** Run a CRUD operation, emitting one structured `[CRUD] …` log line for it. */
+export function logCrud<T>(meta: CrudMeta, fn: () => Promise<T>): Promise<T> {
+  return withCrudLog(meta, fn, { parseError: parseServiceError });
+}

package/templates/grid-starter/src/dev-tools/DevPanel.tsx

@@ -0,0 +1,239 @@
+import React, { useCallback, useMemo, useState } from "react";
+import {
+  Panel,
+  PanelType,
+  TextField,
+  PrimaryButton,
+  DefaultButton,
+  Stack,
+  Text,
+  Separator,
+  MessageBar,
+  MessageBarType,
+  Link,
+  Icon,
+} from "@fluentui/react";
+import { logger } from "@khester/reusable-components";
+
+// Floating dev-tools panel for local development — a 🔧 FAB (bottom-right) that
+// opens a Fluent Panel. Localhost-gated: it renders nothing once deployed, so a
+// live custom page never shows it. Modeled on the original import_weights dev tool,
+// adapted to Vite + this minimal Account example.
+//
+// It does NOT authenticate — "live data" is still the token-proxy env
+// (npm run auth:token + DYNAMICS_URL). The panel surfaces the active mode and lets
+// you set a record GUID in the URL (?id= + reload). The grid starter loads the full
+// list and ignores ?id=; wire it into GridPage if you add a record-detail view.
+
+const GUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const RECENT_KEY = "cda-dev-panel-recent";
+
+const stripBraces = (s: string) => s.replace(/[{}]/g, "").trim();
+
+function isLocalhost(): boolean {
+  return (
+    typeof window !== "undefined" &&
+    (window.location.hostname === "localhost" ||
+      window.location.hostname === "127.0.0.1")
+  );
+}
+
+function getRecent(): string[] {
+  try {
+    return JSON.parse(localStorage.getItem(RECENT_KEY) || "[]");
+  } catch {
+    return [];
+  }
+}
+
+function addRecent(id: string): string[] {
+  const next = [id, ...getRecent().filter((x) => x !== id)].slice(0, 5);
+  try {
+    localStorage.setItem(RECENT_KEY, JSON.stringify(next));
+  } catch {
+    /* ignore */
+  }
+  return next;
+}
+
+const fabStyle: React.CSSProperties = {
+  position: "fixed",
+  bottom: 20,
+  right: 20,
+  zIndex: 2147483000,
+  width: 48,
+  height: 48,
+  borderRadius: "50%",
+  backgroundColor: "#0078d4",
+  color: "#ffffff",
+  boxShadow: "0 2px 8px rgba(0, 0, 0, 0.26)",
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "center",
+  border: "none",
+  cursor: "pointer",
+  fontSize: 20,
+  padding: 0,
+};
+
+const EnvRow: React.FC<{ label: string; value: string }> = ({ label, value }) => (
+  <div
+    style={{
+      display: "flex",
+      justifyContent: "space-between",
+      gap: 12,
+      padding: "2px 0",
+      fontSize: 12,
+    }}
+  >
+    <span style={{ color: "#605e5c", fontWeight: 600 }}>{label}</span>
+    <span
+      title={value}
+      style={{
+        color: "#323130",
+        maxWidth: 210,
+        overflow: "hidden",
+        textOverflow: "ellipsis",
+        whiteSpace: "nowrap",
+      }}
+    >
+      {value}
+    </span>
+  </div>
+);
+
+export const DevPanel: React.FC = () => {
+  const [open, setOpen] = useState(false);
+  const [recordId, setRecordId] = useState(
+    () => new URLSearchParams(window.location.search).get("id") || "",
+  );
+  const [guidError, setGuidError] = useState<string | null>(null);
+  const [recent, setRecent] = useState<string[]>(getRecent);
+  const [logs, setLogs] = useState<string | null>(null);
+
+  const mode = useMemo(
+    () =>
+      import.meta.env.VITE_USE_PROXY
+        ? "Token-proxy (live Dataverse)"
+        : "Mock (in-memory)",
+    [],
+  );
+  const targetUrl = import.meta.env.VITE_DYNAMICS_URL || "";
+
+  const openRecord = useCallback((id: string) => {
+    const clean = stripBraces(id);
+    if (!GUID_RE.test(clean)) {
+      setGuidError("Invalid GUID (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).");
+      return;
+    }
+    setRecent(addRecent(clean));
+    const url = new URL(window.location.href);
+    url.searchParams.set("id", clean);
+    window.location.href = url.toString(); // reload with ?id= (consume it in GridPage if needed)
+  }, []);
+
+  // Localhost-only. (Hooks run unconditionally above this guard.)
+  if (!isLocalhost()) return null;
+
+  return (
+    <>
+      <button
+        style={fabStyle}
+        title="Dev Tools"
+        aria-label="Open dev tools panel"
+        onClick={() => setOpen(true)}
+      >
+        🔧
+      </button>
+      <Panel
+        isOpen={open}
+        onDismiss={() => setOpen(false)}
+        type={PanelType.smallFixedFar}
+        headerText="Dev Tools"
+        isLightDismiss
+        styles={{ main: { maxWidth: 360 } }}
+      >
+        <Stack tokens={{ childrenGap: 16 }} styles={{ root: { paddingTop: 12 } }}>
+          <Stack tokens={{ childrenGap: 8 }}>
+            <Text variant="smallPlus" styles={{ root: { fontWeight: 600, color: "#605e5c" } }}>
+              Open record
+            </Text>
+            <TextField
+              label="Record ID (GUID)"
+              placeholder="00000000-0000-0000-0000-000000000000"
+              value={recordId}
+              onChange={(_, v) => {
+                setRecordId(v || "");
+                setGuidError(null);
+              }}
+              errorMessage={guidError || undefined}
+            />
+            <PrimaryButton
+              text="Open"
+              disabled={!recordId.trim()}
+              onClick={() => openRecord(recordId)}
+            />
+            <Text variant="tiny" styles={{ root: { color: "#a19f9d" } }}>
+              Adds ?id= and reloads. In mock mode the seeded record is always returned.
+            </Text>
+          </Stack>
+
+          {recent.length > 0 && (
+            <>
+              <Separator />
+              <Stack tokens={{ childrenGap: 4 }}>
+                <Text variant="smallPlus" styles={{ root: { fontWeight: 600, color: "#605e5c" } }}>
+                  Recent
+                </Text>
+                {recent.map((id) => (
+                  <Link key={id} title={id} onClick={() => openRecord(id)}>
+                    <Icon iconName="OpenFile" styles={{ root: { fontSize: 12, marginRight: 6 } }} />
+                    {id.substring(0, 8)}…
+                  </Link>
+                ))}
+              </Stack>
+            </>
+          )}
+
+          <Separator />
+          <Stack tokens={{ childrenGap: 2 }}>
+            <Text variant="smallPlus" styles={{ root: { fontWeight: 600, color: "#605e5c" } }}>
+              Environment
+            </Text>
+            <EnvRow label="Mode" value={mode} />
+            {targetUrl && <EnvRow label="Target" value={targetUrl} />}
+            <EnvRow
+              label="Token"
+              value={import.meta.env.VITE_USE_PROXY ? "Configured (server-side)" : "Not set"}
+            />
+            <MessageBar messageBarType={MessageBarType.info} isMultiline styles={{ root: { marginTop: 8 } }}>
+              For live data: run <strong>npm run auth:token -- --url https://your-org.crm.dynamics.com</strong>, then restart <strong>npm run dev</strong>.
+            </MessageBar>
+          </Stack>
+
+          <Separator />
+          <Stack tokens={{ childrenGap: 6 }}>
+            <Text variant="smallPlus" styles={{ root: { fontWeight: 600, color: "#605e5c" } }}>
+              Logs
+            </Text>
+            <Stack horizontal tokens={{ childrenGap: 8 }}>
+              <DefaultButton text="Refresh" onClick={() => setLogs(logger.dump())} />
+              <DefaultButton
+                text="Clear"
+                onClick={() => {
+                  logger.clear();
+                  setLogs("");
+                }}
+              />
+            </Stack>
+            {logs !== null && (
+              <TextField multiline rows={6} readOnly value={logs || "(no entries)"} />
+            )}
+          </Stack>
+        </Stack>
+      </Panel>
+    </>
+  );
+};
+
+export default DevPanel;

package/templates/grid-starter/src/grid/GridPage.tsx

@@ -0,0 +1,119 @@
+import React, { useCallback, useEffect, useMemo, useState } from "react";
+import {
+  initializeIcons,
+  MessageBar,
+  MessageBarType,
+  Spinner,
+  Text,
+} from "@fluentui/react";
+import { DataGrid, createCellRegistry } from "@dataverse-kit/grid-kit";
+import type { ColumnDef } from "@dataverse-kit/grid-kit";
+import type { IApiService } from "../core/services/IApiService";
+
+initializeIcons();
+
+/** Display row shape — map your Dataverse attributes to this in `mapAccount`. */
+interface AccountRow extends Record<string, unknown> {
+  key: string;
+  name: string;
+  accountnumber: string;
+  telephone1: string;
+  revenue: number;
+  statuscode: string;
+  rating: number;
+}
+
+const STATUS_COLORS: Record<string, string> = {
+  Active: "#107c10",
+  "On hold": "#f7e600",
+  Inactive: "#d13438",
+};
+
+// grid-kit columns. Swap `rendererType` / `rendererConfig` to change a cell's
+// look; add `editorType` to make a column inline-editable.
+const columns: ColumnDef<AccountRow>[] = [
+  { key: "name", fieldName: "name", name: "Account", rendererType: "text", editorType: "text", minWidth: 180, isSortable: true },
+  { key: "accountnumber", fieldName: "accountnumber", name: "Number", rendererType: "text", minWidth: 110 },
+  { key: "telephone1", fieldName: "telephone1", name: "Phone", rendererType: "text", minWidth: 150 },
+  { key: "revenue", fieldName: "revenue", name: "Revenue", rendererType: "currency", minWidth: 130, isSortable: true, rendererConfig: { currencyCode: "USD" } },
+  { key: "statuscode", fieldName: "statuscode", name: "Status", rendererType: "coloredCell", minWidth: 110, rendererConfig: { colorMap: STATUS_COLORS } },
+  { key: "rating", fieldName: "rating", name: "Rating", rendererType: "rating", minWidth: 120, rendererConfig: { max: 5 } },
+];
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+function mapAccount(e: any): AccountRow {
+  return {
+    key: e.accountid,
+    name: e.name ?? "",
+    accountnumber: e.accountnumber ?? "",
+    telephone1: e.telephone1 ?? "",
+    revenue: Number(e.revenue ?? 0),
+    // NOTE: the mock seeds a display string. Real Dataverse `statuscode` is an
+    // int optionset — its label is in the `statuscode@OData.Community.Display.V1.FormattedValue`
+    // sibling key. In production prefer that label (or switch this column to
+    // rendererType 'optionset' with options) so STATUS_COLORS resolves.
+    statuscode: e["statuscode@OData.Community.Display.V1.FormattedValue"] ?? e.statuscode ?? "Active",
+    rating: Number(e.rating ?? 0),
+  };
+}
+/* eslint-enable @typescript-eslint/no-explicit-any */
+
+export const GridPage: React.FC<{ api: IApiService }> = ({ api }) => {
+  const [rows, setRows] = useState<AccountRow[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [search, setSearch] = useState("");
+  const registry = useMemo(() => createCellRegistry(), []);
+
+  const filteredRows = useMemo(() => {
+    const q = search.trim().toLowerCase();
+    if (!q) return rows;
+    return rows.filter((r) =>
+      [r.name, r.accountnumber, r.telephone1, r.statuscode].some((v) =>
+        String(v).toLowerCase().includes(q),
+      ),
+    );
+  }, [rows, search]);
+
+  const load = useCallback(() => {
+    setIsLoading(true);
+    setError(null);
+    api
+      .retrieveMultipleRecords("accounts", "")
+      .then((res) => setRows(res.entities.map(mapAccount)))
+      .catch((e) => setError(e?.message ?? String(e)))
+      .finally(() => setIsLoading(false));
+  }, [api]);
+
+  useEffect(load, [load]);
+
+  if (isLoading) return <Spinner label="Loading accounts…" />;
+
+  return (
+    <div style={{ maxWidth: 1100, margin: "16px auto" }}>
+      <Text variant="xLarge" block styles={{ root: { marginBottom: 12 } }}>
+        Accounts
+      </Text>
+      {error && (
+        <MessageBar messageBarType={MessageBarType.error} styles={{ root: { marginBottom: 12 } }}>
+          {error}
+        </MessageBar>
+      )}
+      <DataGrid<AccountRow>
+        items={filteredRows}
+        columns={columns}
+        registry={registry}
+        selectionMode="multiple"
+        getKey={(r) => r.key}
+        toolbar={{
+          showSearch: true,
+          searchPlaceholder: "Search accounts",
+          onSearch: setSearch,
+          commands: [{ key: "refresh", text: "Refresh", iconName: "Refresh", onClick: load }],
+        }}
+      />
+    </div>
+  );
+};
+
+export default GridPage;

package/templates/grid-starter/src/index.tsx

@@ -0,0 +1,18 @@
+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/grid-starter/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;
+}