npm - @khester/create-dynamics-app - Versions diffs - 2.1.0 → 2.2.0 - Mend

@khester/create-dynamics-app 2.1.0 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (121) hide show

package/templates/react-custom-page/src/core/services/crudLogging.ts ADDED Viewed

@@ -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/react-custom-page/src/dev-tools/DevPanel.tsx ADDED Viewed

@@ -0,0 +1,238 @@
+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 load a specific record by GUID (sets ?id= and reloads, which useExampleData reads).
+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 → useExampleData reads ?id=
+  }, []);
+  // 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/react-custom-page/src/domain/diff.test.ts ADDED Viewed

@@ -0,0 +1,87 @@
+import { changedKeys, hasChanged, changedFields } from "./diff";
+interface Sample {
+  a: number;
+  b: string;
+  c: boolean;
+}
+const KEYS = ["a", "b", "c"] as const;
+describe("changedKeys", () => {
+  it("treats every key as changed when there is no baseline (initial = null)", () => {
+    const current: Sample = { a: 1, b: "x", c: true };
+    expect(changedKeys(current, null, KEYS)).toEqual(["a", "b", "c"]);
+  });
+  it("returns only the keys whose value differs", () => {
+    const current: Sample = { a: 1, b: "x", c: true };
+    const initial: Sample = { a: 2, b: "x", c: false };
+    expect(changedKeys(current, initial, KEYS)).toEqual(["a", "c"]);
+  });
+  it("returns [] when nothing changed", () => {
+    const value: Sample = { a: 1, b: "x", c: true };
+    expect(changedKeys(value, { ...value }, KEYS)).toEqual([]);
+  });
+  it("only inspects the keys it is given", () => {
+    const current: Sample = { a: 1, b: "changed", c: true };
+    const initial: Sample = { a: 1, b: "original", c: true };
+    expect(changedKeys(current, initial, ["a", "c"] as const)).toEqual([]);
+  });
+  it("compares by strict reference (distinct objects of equal shape count as changed)", () => {
+    interface Holder {
+      v: { n: number };
+    }
+    const shared = { n: 1 };
+    expect(changedKeys({ v: { n: 1 } }, { v: shared }, ["v"] as const)).toEqual([
+      "v",
+    ]);
+    expect(changedKeys({ v: shared }, { v: shared }, ["v"] as const)).toEqual(
+      [],
+    );
+  });
+});
+describe("hasChanged", () => {
+  it("is true when any key differs", () => {
+    expect(hasChanged({ a: 1 }, { a: 2 }, ["a"] as const)).toBe(true);
+  });
+  it("is false when all compared keys are equal", () => {
+    expect(hasChanged({ a: 1, b: 2 }, { a: 1, b: 9 }, ["a"] as const)).toBe(
+      false,
+    );
+  });
+  it("is true when there is no baseline", () => {
+    expect(hasChanged({ a: 1 }, null, ["a"] as const)).toBe(true);
+  });
+});
+describe("changedFields", () => {
+  it("returns a partial containing only the changed keys and their current values", () => {
+    const current: Sample = { a: 1, b: "new", c: true };
+    const initial: Sample = { a: 1, b: "old", c: false };
+    expect(changedFields(current, initial, KEYS)).toEqual({
+      b: "new",
+      c: true,
+    });
+  });
+  it("returns every key (with current values) when there is no baseline", () => {
+    const current: Sample = { a: 1, b: "x", c: true };
+    expect(changedFields(current, null, KEYS)).toEqual({
+      a: 1,
+      b: "x",
+      c: true,
+    });
+  });
+  it("returns {} when nothing changed", () => {
+    const value: Sample = { a: 1, b: "x", c: true };
+    expect(changedFields(value, { ...value }, KEYS)).toEqual({});
+  });
+});

package/templates/react-custom-page/src/domain/diff.ts ADDED Viewed

@@ -0,0 +1,38 @@
+// Generic, framework-free change detection. Pure — unit-testable without React.
+// The form layer uses this to send ONLY the modified fields to Dataverse.
+/**
+ * Returns the subset of `keys` whose value differs between `current` and
+ * `initial`. When `initial` is null (no snapshot yet) every key is considered
+ * changed — matching "treat as dirty until initialized" behavior.
+ */
+export function changedKeys<T>(
+  current: T,
+  initial: T | null,
+  keys: ReadonlyArray<keyof T>,
+): Array<keyof T> {
+  if (!initial) return [...keys];
+  return keys.filter((key) => current[key] !== initial[key]);
+}
+/** True when any of `keys` differ between `current` and `initial`. */
+export function hasChanged<T>(
+  current: T,
+  initial: T | null,
+  keys: ReadonlyArray<keyof T>,
+): boolean {
+  return changedKeys(current, initial, keys).length > 0;
+}
+/** A partial object containing only the changed keys (and their current values). */
+export function changedFields<T>(
+  current: T,
+  initial: T | null,
+  keys: ReadonlyArray<keyof T>,
+): Partial<T> {
+  const result: Partial<T> = {};
+  for (const key of changedKeys(current, initial, keys)) {
+    result[key] = current[key];
+  }
+  return result;
+}

package/templates/react-custom-page/src/example/ExamplePage.tsx ADDED Viewed

@@ -0,0 +1,140 @@
+import React from "react";
+import { Spinner, MessageBarType, CommandBarButton } from "@fluentui/react";
+import {
+  Form,
+  Avatar,
+  ReusableCard,
+  FieldRow,
+  CustomTextfield,
+  ButtonDefaultComponent,
+  MessageBarComponent,
+} from "@khester/reusable-components";
+import type { IApiService } from "../core/services/IApiService";
+import { useExampleData } from "./hooks/useExampleData";
+import { useExampleForm } from "./hooks/useExampleForm";
+import type { AccountFormField } from "./mappers/accountMapper";
+export interface ExamplePageProps {
+  api: IApiService;
+  /** Record id resolved from the page context (URL / hosting form). */
+  recordId?: string;
+}
+type Field = {
+  key: AccountFormField;
+  label: string;
+  required?: boolean;
+  icon?: string;
+};
+// Two sections laid out in the Form's 12-column grid (span 6 each).
+const ACCOUNT_FIELDS: Field[] = [
+  { key: "name", label: "Account name", required: true },
+  { key: "accountNumber", label: "Account number" },
+  { key: "phone", label: "Phone", icon: "Phone" },
+];
+const CONTACT_FIELDS: Field[] = [
+  { key: "email", label: "Email", icon: "Mail" },
+  { key: "website", label: "Website", icon: "Globe" },
+];
+/**
+ * Thin form: hooks + JSX, no CRUD. A page-variant <Form> renders a Dynamics-style
+ * top command bar + record header; two section cards (ReusableCard, span 6) sit in
+ * the responsive grid body. Swap out example/ to build your own page.
+ */
+export const ExamplePage: React.FC<ExamplePageProps> = ({ api, recordId }) => {
+  const { account, isLoading, error, reload } = useExampleData(api, recordId);
+  const { form, isDirty, isSaving, saveError, saveSucceeded, setField, save, reset } =
+    useExampleForm(api, account);
+  if (isLoading) {
+    return <Spinner label="Loading account…" />;
+  }
+  if (error) {
+    return (
+      <div style={{ padding: 16 }}>
+        <MessageBarComponent messageBarType={MessageBarType.error} subtext={error} />
+        <div style={{ marginTop: 12 }}>
+          <ButtonDefaultComponent text="Retry" onClick={reload} />
+        </div>
+      </div>
+    );
+  }
+  if (!account) {
+    return (
+      <div style={{ padding: 16 }}>
+        <MessageBarComponent
+          messageBarType={MessageBarType.warning}
+          subtext="No account to display."
+        />
+      </div>
+    );
+  }
+  const renderField = (f: Field) => (
+    <FieldRow key={f.key} label={f.label} required={f.required}>
+      <CustomTextfield
+        value={form[f.key]}
+        onChange={(_, v) => setField(f.key, v ?? "")}
+        iconProps={f.icon ? { iconName: f.icon } : undefined}
+      />
+    </FieldRow>
+  );
+  // Form-level save result, shown above the sections.
+  const notification = saveError ? (
+    <MessageBarComponent messageBarType={MessageBarType.error} subtext={saveError} />
+  ) : saveSucceeded ? (
+    <MessageBarComponent messageBarType={MessageBarType.success} subtext="Account saved." />
+  ) : undefined;
+  // Top command bar (page variant) — flat Dynamics-style commands.
+  const commands = (
+    <>
+      <CommandBarButton
+        iconProps={{ iconName: "Save" }}
+        text="Save"
+        onClick={save}
+        disabled={!isDirty || isSaving}
+      />
+      <CommandBarButton
+        iconProps={{ iconName: "Undo" }}
+        text="Reset"
+        onClick={reset}
+        disabled={!isDirty || isSaving}
+      />
+      <CommandBarButton
+        iconProps={{ iconName: "Refresh" }}
+        text="Refresh"
+        onClick={reload}
+        disabled={isSaving}
+      />
+    </>
+  );
+  return (
+    <div style={{ maxWidth: 1100, margin: "16px auto" }}>
+      <Form
+        variant="page"
+        title={account.name || "Account"}
+        avatar={<Avatar name={account.name || "Account"} />}
+        status={isDirty ? "Unsaved" : "Saved"}
+        subtitle="Account · Account"
+        actions={commands}
+        notification={notification}
+      >
+        <ReusableCard title="Account" columnSpan={6}>
+          {ACCOUNT_FIELDS.map(renderField)}
+        </ReusableCard>
+        <ReusableCard title="Contact" columnSpan={6}>
+          {CONTACT_FIELDS.map(renderField)}
+        </ReusableCard>
+      </Form>
+    </div>
+  );
+};
+export default ExamplePage;

package/templates/react-custom-page/src/example/exampleError.ts ADDED Viewed

@@ -0,0 +1,36 @@
+// Normalizes the error shapes thrown by the IApiService implementations into a
+// single human-readable string for the UI. (The service layer's own logging
+// parser lives in core/services/crudLogging.ts; this one is for user messages.)
+/**
+ * Extracts the most meaningful message from an error thrown by an IApiService,
+ * falling back to `fallback` when nothing useful is found. Handles plain
+ * `json.error` objects (XrmApiService) and Error instances whose message embeds
+ * a Dataverse error JSON blob (FetchApiService).
+ */
+export function normalizeDataverseError(err: unknown, fallback: string): string {
+  if (err && typeof err === "object" && !(err instanceof Error)) {
+    const obj = err as Record<string, unknown>;
+    const innerMsg = obj["@Microsoft.PowerApps.CDS.InnerError.Message"];
+    if (typeof innerMsg === "string" && innerMsg) return innerMsg;
+    if (typeof obj.message === "string" && obj.message) return obj.message;
+  }
+  if (err instanceof Error) {
+    try {
+      const jsonStart = err.message.indexOf("{");
+      if (jsonStart !== -1) {
+        const parsed = JSON.parse(err.message.substring(jsonStart));
+        const innerMsg =
+          parsed?.error?.["@Microsoft.PowerApps.CDS.InnerError.Message"];
+        if (innerMsg) return innerMsg;
+        if (parsed?.error?.message) return parsed.error.message;
+      }
+    } catch {
+      // JSON parse failed — fall through to the raw message
+    }
+    return err.message || fallback;
+  }
+  return fallback;
+}

package/templates/react-custom-page/src/example/hooks/useExampleData.ts ADDED Viewed

@@ -0,0 +1,40 @@
+import { useCallback, useEffect, useState } from "react";
+import type { IApiService } from "../../core/services/IApiService";
+import { Account, IAccount } from "../models/Account";
+import { normalizeDataverseError } from "../exampleError";
+export interface ExampleData {
+  account: IAccount | null;
+  isLoading: boolean;
+  error: string | null;
+  reload: () => void;
+}
+/**
+ * Loads the single account this page edits (data layer only — no form state).
+ * `recordId` is resolved by the shell from the page context (URL / hosting form);
+ * in mock mode it's ignored and the seeded record is returned.
+ */
+export function useExampleData(
+  api: IApiService,
+  recordId?: string,
+): ExampleData {
+  const [account, setAccount] = useState<IAccount | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const load = useCallback(() => {
+    setIsLoading(true);
+    setError(null);
+    Account.retrieveOne(api, recordId)
+      .then(setAccount)
+      .catch((e) =>
+        setError(normalizeDataverseError(e, "Failed to load account.")),
+      )
+      .finally(() => setIsLoading(false));
+  }, [api, recordId]);
+  useEffect(load, [load]);
+  return { account, isLoading, error, reload: load };
+}