@khester/create-dynamics-app 2.10.0 → 3.0.0

package/templates/power-pages-island/src/App.tsx

@@ -0,0 +1,25 @@
+import * as React from "react";
+import type { IApiService } from "./core/services/IApiService";
+import { MockApiService } from "./core/services/MockApiService";
+import { PortalSeamService } from "@dataverse-kit/portal-api-service";
+import { Component } from "./Component";
+
+// A Power Pages island is served from the portal origin, so a same-origin `/_api`
+// fetch is authenticated by the portal session cookie + anti-forgery token —
+// PortalSeamService handles both (token fetch/cache, 403-retry, idempotency-aware
+// retry). On localhost (the webpack dev server) fall back to the in-memory mock so
+// it renders with no portal.
+//
+// PortalSeamService implements the create-app 6-method `dataverse-seam`, so it is
+// structurally assignable to IApiService with NO cast — and THIS assignment is the
+// load-bearing compile-time drift guard: if the seam shapes ever diverge, this line
+// fails `tsc`. (See core/services/portalSeam.assert.ts for the explicit fixture.)
+export const App: React.FC<{ island?: string }> = () => {
+  // `island` is the `data-dvkit-island` value — a hook for routing multiple widgets
+  // on a page. The starter renders the accounts widget for any island.
+  const api = React.useMemo<IApiService>(() => {
+    const onLocalhost = /^(localhost|127\.0\.0\.1)$/.test(window.location.hostname);
+    return onLocalhost ? new MockApiService() : new PortalSeamService();
+  }, []);
+  return <Component api={api} />;
+};

package/templates/power-pages-island/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/power-pages-island/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/power-pages-island/src/core/services/portalSeam.assert.ts

@@ -0,0 +1,14 @@
+// Compile-time drift guard (typechecked by `npm run build` → `tsc --noEmit`, and by
+// the create-dynamics-app power-pages-island template build e2e). `PortalSeamService`
+// — the create-app 6-method `dataverse-seam` adapter shipped in
+// `@dataverse-kit/portal-api-service` — MUST stay structurally assignable to THIS
+// template's local seam `IApiService`, so `App.tsx` can inject it with no cast. That
+// package can't import the create-app template interface, so the assertion lives here,
+// where both types resolve. Type-only — no runtime, tree-shaken from the bundle.
+import type { IApiService } from "./IApiService";
+import type { PortalSeamService } from "@dataverse-kit/portal-api-service";
+
+// If PortalSeamService drifts from the seam shape, `true` is no longer assignable to
+// `never` and this fails to compile.
+type PortalSeamSatisfiesSeam = PortalSeamService extends IApiService ? true : never;
+export const _portalSeamDriftGuard: PortalSeamSatisfiesSeam = true;

package/templates/power-pages-island/src/island-env.d.ts

@@ -0,0 +1,12 @@
+// Webpack/ts-loader 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. This Power Pages
+// island does NOT use ServiceFactory (App.tsx builds MockApiService / PortalSeamService
+// directly), so it is tree-shaken from the bundle — but `tsc` / ts-loader still
+// typecheck it. This minimal ambient declaration lets that unused file compile here.
+//
+// NOTE: this file MUST live under src/ — the tsconfig is `include: ["src"]`, so a
+// project-root *.d.ts would be excluded and the shim would be missed.
+interface ImportMeta {
+  readonly env: Record<string, unknown>;
+}

package/templates/power-pages-island/src/islands.tsx

@@ -0,0 +1,38 @@
+import * as 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 portal.
+initLogging();
+
+// A traditional Power Pages portal is server-rendered (Liquid). This bundle is an
+// ISLAND: it hydrates React ONLY into the nodes a maker tags in Liquid, leaving the
+// rest of the page untouched — the delta the MS code-site scaffolder (whole-page SPA)
+// can't do. Tag a mount point with `data-dvkit-island="<name>"` (the name is a hook
+// for future per-widget routing) and reference this web file:
+//
+//   <div data-dvkit-island="accounts"></div>
+//   <script src="/{{projectName}}.js"></script>
+//
+const SELECTOR = "[data-dvkit-island]";
+
+function mountIslands(): void {
+  document.querySelectorAll<HTMLElement>(SELECTOR).forEach((node) => {
+    // Idempotent — a partial-page refresh or a duplicated include must not double-mount.
+    if (node.dataset.dvkitMounted === "true") return;
+    node.dataset.dvkitMounted = "true";
+    createRoot(node).render(
+      <React.StrictMode>
+        <App island={node.dataset.dvkitIsland} />
+      </React.StrictMode>,
+    );
+  });
+}
+
+if (document.readyState === "loading") {
+  document.addEventListener("DOMContentLoaded", mountIslands);
+} else {
+  mountIslands();
+}

package/templates/power-pages-island/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "lib": ["DOM", "DOM.Iterable", "ES2020"],
+    "types": []
+  },
+  "include": ["src"]
+}

package/templates/power-pages-island/webpack.config.js

@@ -0,0 +1,22 @@
+const path = require('path');
+const HtmlWebpackPlugin = require('html-webpack-plugin');
+
+// A Power Pages ISLAND: one self-contained bundle, uploaded as a portal WEB FILE and
+// referenced from a Liquid page (see README). The output filename is STABLE (no
+// contenthash) so the Liquid `<script src>` URL stays fixed across rebuilds.
+// HtmlWebpackPlugin exists only for the local `webpack serve` preview — on a real
+// portal the Liquid page is the host, so the emitted index.html is never uploaded.
+module.exports = {
+  entry: './src/islands.tsx',
+  output: {
+    path: path.resolve(__dirname, 'dist'),
+    filename: '{{projectName}}.js',
+    clean: true,
+  },
+  resolve: { extensions: ['.ts', '.tsx', '.js'] },
+  module: {
+    rules: [{ test: /\.tsx?$/, use: 'ts-loader', exclude: /node_modules/ }],
+  },
+  plugins: [new HtmlWebpackPlugin({ template: './public/index.html' })],
+  devServer: { static: './dist', port: 8080, hot: true },
+};

package/templates/power-pages-starter/.env.example

@@ -1,6 +0,0 @@
-# Power Pages Configuration
-PORTAL_URL=https://your-portal.powerappsportals.com
-
-# Optional: API Configuration
-API_VERSION=v9.0
-ENABLE_LOGGING=false

package/templates/power-pages-starter/README.md

@@ -1,95 +0,0 @@
-# Power Pages Application
-
-This is a Power Pages application built with Dynamics UI Kit components.
-
-## Getting Started
-
-1. **Environment Setup**
-
-   ```bash
-   cp .env.example .env
-   ```
-
-   Edit `.env` and set your `PORTAL_URL` to your Power Pages portal URL.
-
-2. **Install Dependencies**
-
-   ```bash
-   npm install
-   ```
-
-3. **Development**
-
-   ```bash
-   npm run dev
-   ```
-
-   This starts the development server at http://localhost:3000
-
-4. **Build for Production**
-   ```bash
-   npm run build
-   ```
-
-## Project Structure
-
-```
-src/
-├── components/          # React components
-│   ├── ContactForm.tsx  # Main contact form component
-│   └── ContactForm.css  # Component styles
-├── providers/           # Context providers
-│   └── PowerPagesProvider.tsx  # Power Pages API provider
-├── styles/             # Global styles
-│   └── index.css       # Global CSS
-└── index.tsx           # Application entry point
-```
-
-## Features
-
-- **Contact Management**: Create and manage contacts using Dynamics UI Kit components
-- **Power Pages Integration**: Seamless integration with Power Pages API
-- **Responsive Design**: Mobile-friendly responsive layout
-- **Type Safety**: Full TypeScript support
-
-## Deployment
-
-To deploy your application to Power Pages:
-
-1. Build the application:
-
-   ```bash
-   npm run build
-   ```
-
-2. Upload the `dist` folder contents to your Power Pages portal's web files
-
-3. Create a new web page in Power Pages and reference your built JavaScript and CSS files
-
-## Customization
-
-### Adding New Components
-
-1. Create your component in `src/components/`
-2. Use Dynamics UI Kit components for consistent styling
-3. Import and use the `usePowerPagesApi` hook for data operations
-
-### Styling
-
-- Global styles are in `src/styles/index.css`
-- Component-specific styles should be co-located with components
-- Follow the existing CSS naming conventions
-
-## Available Scripts
-
-- `npm run dev` - Start development server
-- `npm run build` - Build for production
-- `npm run typecheck` - Type check without building
-- `npm run clean` - Clean build directory
-- `npm run lint` - Lint code
-
-## Learn More
-
-- [Dynamics UI Kit Documentation](https://github.com/your-org/dynamics-ui-kit)
-- [Power Pages Documentation](https://docs.microsoft.com/power-pages/)
-- [React Documentation](https://reactjs.org/)

package/templates/power-pages-starter/package.json

@@ -1,43 +0,0 @@
-{
-  "name": "power-pages-app",
-  "version": "1.0.0",
-  "description": "Power Pages application built with Dynamics UI Kit",
-  "main": "dist/index.js",
-  "scripts": {
-    "build": "webpack --mode=production",
-    "dev": "webpack serve --mode=development",
-    "typecheck": "tsc --noEmit",
-    "clean": "rimraf dist",
-    "lint": "eslint src --ext .ts,.tsx"
-  },
-  "dependencies": {
-    "@khester/dynamics-ui-api-client": "^1.0.0",
-    "@khester/dynamics-ui-components": "^1.0.0",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0"
-  },
-  "devDependencies": {
-    "@types/react": "^18.2.0",
-    "@types/react-dom": "^18.2.0",
-    "css-loader": "^6.8.1",
-    "html-webpack-plugin": "^5.5.3",
-    "style-loader": "^3.3.3",
-    "ts-loader": "^9.5.1",
-    "typescript": "^5.3.3",
-    "webpack": "^5.89.0",
-    "webpack-cli": "^5.1.4",
-    "webpack-dev-server": "^4.15.1"
-  },
-  "browserslist": {
-    "production": [
-      ">0.2%",
-      "not dead",
-      "not op_mini all"
-    ],
-    "development": [
-      "last 1 chrome version",
-      "last 1 firefox version",
-      "last 1 safari version"
-    ]
-  }
-}

package/templates/power-pages-starter/public/index.html

@@ -1,15 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="utf-8" />
-    <link rel="icon" href="data:," />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <meta name="theme-color" content="#000000" />
-    <meta name="description" content="Power Pages Application built with Dynamics UI Kit" />
-    <title>Power Pages App - Dynamics UI Kit</title>
-</head>
-<body>
-    <noscript>You need to enable JavaScript to run this app.</noscript>
-    <div id="root"></div>
-</body>
-</html>

package/templates/power-pages-starter/src/components/ContactForm.css

@@ -1,84 +0,0 @@
-.contact-form {
-  max-width: 800px;
-  margin: 0 auto;
-  padding: 24px;
-  background: #ffffff;
-  border-radius: 8px;
-  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
-}
-
-.contact-form__header {
-  margin-bottom: 24px;
-}
-
-.contact-form__title {
-  margin: 0;
-  font-size: 24px;
-  font-weight: 600;
-  color: #323130;
-}
-
-.contact-form__content {
-  margin-bottom: 24px;
-}
-
-.contact-form__row {
-  display: grid;
-  grid-template-columns: 1fr 1fr;
-  gap: 16px;
-  margin-bottom: 16px;
-}
-
-.contact-form__field {
-  display: flex;
-  flex-direction: column;
-}
-
-.contact-form__actions {
-  display: flex;
-  gap: 12px;
-  justify-content: flex-start;
-  margin-top: 24px;
-}
-
-.contact-form__success {
-  padding: 12px 16px;
-  margin-bottom: 16px;
-  background-color: #dff6dd;
-  border: 1px solid #107c10;
-  border-radius: 4px;
-  color: #107c10;
-  font-weight: 500;
-}
-
-.contact-form__error {
-  padding: 12px 16px;
-  margin-bottom: 16px;
-  background-color: #fef7f1;
-  border: 1px solid #d13438;
-  border-radius: 4px;
-  color: #d13438;
-  font-weight: 500;
-}
-
-.contact-form__auth-notice {
-  margin-top: 16px;
-  padding: 12px 16px;
-  background-color: #fff4ce;
-  border: 1px solid #ffb900;
-  border-radius: 4px;
-  color: #8a6d00;
-  text-align: center;
-}
-
-@media (max-width: 768px) {
-  .contact-form {
-    padding: 16px;
-    margin: 16px;
-  }
-  
-  .contact-form__row {
-    grid-template-columns: 1fr;
-    gap: 12px;
-  }
-}