@khester/create-dynamics-app 2.1.0 → 2.2.0

package/templates/starter-page/README.md

@@ -0,0 +1,38 @@
+# {{projectName}}
+
+A Dynamics 365 **starter page** — a React web resource built on a single
+[`@dataverse-kit/surface-kit`](https://www.npmjs.com/package/@dataverse-kit/surface-kit)
+surface (Fluent UI v8), hosted as a custom page / web resource.
+
+The surface was chosen at scaffold time (`--surface <form|panel|dashboard|master-detail>`)
+and lives in `src/App.tsx`:
+
+| Surface | Renders | Extra dep |
+|---------|---------|-----------|
+| `form` | `FormSurface` + `Section`s + `FieldRow`s (a record edit page) | — |
+| `panel` | A list with a slide-in `PanelSurface` editor | — |
+| `dashboard` | `DashboardSurface` tile grid hosting a `<DataGrid>` | `@dataverse-kit/grid-kit` |
+| `master-detail` | `MasterDetailSurface` (list + detail split) hosting a `<DataGrid>` | `@dataverse-kit/grid-kit` |
+
+## Develop
+
+```bash
+npm install
+npm run dev        # webpack dev server on http://localhost:8080
+npm run build      # production bundle → dist/{{projectName}}.js
+npm run typecheck  # tsc --noEmit
+```
+
+Data access goes through `src/services/dataverse.ts` (`Xrm.WebApi`). Outside a
+model-driven host, stub `Xrm` with the `serve` dev-tool's `tools/dev/mock-xrm.js`.
+
+## Dev-tools
+
+```bash
+npm run auth:token -- --url https://YOUR_ORG.crm.dynamics.com   # token → .env
+```
+
+## Deploy
+
+Upload `dist/{{projectName}}.js` as a web resource and host it on a custom page or
+open it from a form / ribbon command.

package/templates/starter-page/_variants/App.dashboard.v8.tsx

@@ -0,0 +1,46 @@
+import * as React from 'react';
+import { ThemeProvider } from '@fluentui/react/lib/Theme';
+import { DashboardSurface, Section } from '@dataverse-kit/surface-kit';
+import { DataGrid, type ColumnDef } from '@dataverse-kit/grid-kit';
+
+/**
+ * Starter page — `dashboard` surface. A surface-kit `DashboardSurface` tile grid
+ * (2 cols, reflows to 1 on narrow widths) whose tiles host grid-kit `<DataGrid>`s.
+ * Swap the sample rows for `retrieveMultiple(...)` from `./services/dataverse`.
+ */
+interface AccountRow extends Record<string, unknown> {
+  key: string;
+  name: string;
+  revenue: number;
+  status: string;
+}
+
+const COLUMNS: ColumnDef<AccountRow>[] = [
+  { key: 'name', fieldName: 'name', name: 'Account', rendererType: 'text' },
+  { key: 'revenue', fieldName: 'revenue', name: 'Revenue', rendererType: 'currency' },
+  { key: 'status', fieldName: 'status', name: 'Status', rendererType: 'text' },
+];
+
+const ROWS: AccountRow[] = [
+  { key: '1', name: 'Contoso', revenue: 5_000_000, status: 'Active' },
+  { key: '2', name: 'Fabrikam', revenue: 2_400_000, status: 'Active' },
+  { key: '3', name: 'Adventure Works', revenue: 980_000, status: 'On hold' },
+];
+
+export const App: React.FC = () => {
+  return (
+    <ThemeProvider>
+      <DashboardSurface
+        columns={2}
+        tiles={[
+          <Section key="accounts" title="Top accounts" variant="card">
+            <DataGrid<AccountRow> items={ROWS} columns={COLUMNS} />
+          </Section>,
+          <Section key="pipeline" title="Pipeline" variant="card">
+            <DataGrid<AccountRow> items={ROWS} columns={COLUMNS} />
+          </Section>,
+        ]}
+      />
+    </ThemeProvider>
+  );
+};

package/templates/starter-page/_variants/App.form.v8.tsx

@@ -0,0 +1,59 @@
+import * as React from 'react';
+import { ThemeProvider } from '@fluentui/react/lib/Theme';
+import { Stack } from '@fluentui/react/lib/Stack';
+import { TextField } from '@fluentui/react/lib/TextField';
+import { PrimaryButton, DefaultButton } from '@fluentui/react/lib/Button';
+import { FormSurface, Section, FieldRow } from '@dataverse-kit/surface-kit';
+import { createRecord } from './services/dataverse';
+
+/**
+ * Starter page — `form` surface. A surface-kit `FormSurface` hosts a `Section` of
+ * `FieldRow`s; the layout stacks to one column on narrow widths (surface-kit owns
+ * the responsive breakpoints). Saves a contact via `Xrm.WebApi`.
+ */
+export const App: React.FC = () => {
+  const [name, setName] = React.useState('');
+  const [email, setEmail] = React.useState('');
+  const [phone, setPhone] = React.useState('');
+  const [saving, setSaving] = React.useState(false);
+
+  const onSave = async () => {
+    setSaving(true);
+    try {
+      await createRecord('contact', {
+        fullname: name,
+        emailaddress1: email,
+        telephone1: phone,
+      });
+      alert('Saved.');
+    } catch (e) {
+      alert(`Save failed (Xrm not available here?): ${String(e)}`);
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return (
+    <ThemeProvider>
+      <FormSurface maxWidth={960}>
+        <Section title="{{projectName}}" columnSpan={12}>
+          <FieldRow label="Full name" required>
+            <TextField value={name} onChange={(_, v) => setName(v ?? '')} />
+          </FieldRow>
+          <FieldRow label="Email">
+            <TextField value={email} onChange={(_, v) => setEmail(v ?? '')} />
+          </FieldRow>
+          <FieldRow label="Phone">
+            <TextField value={phone} onChange={(_, v) => setPhone(v ?? '')} />
+          </FieldRow>
+          <FieldRow>
+            <Stack horizontal tokens={{ childrenGap: 8 }}>
+              <PrimaryButton text="Save" onClick={onSave} disabled={saving} />
+              <DefaultButton text="Cancel" onClick={() => window.history.back()} />
+            </Stack>
+          </FieldRow>
+        </Section>
+      </FormSurface>
+    </ThemeProvider>
+  );
+};

package/templates/starter-page/_variants/App.master-detail.v8.tsx

@@ -0,0 +1,61 @@
+import * as React from 'react';
+import { ThemeProvider } from '@fluentui/react/lib/Theme';
+import { Text } from '@fluentui/react/lib/Text';
+import { MasterDetailSurface, Section, FieldRow } from '@dataverse-kit/surface-kit';
+import { DataGrid, type ColumnDef } from '@dataverse-kit/grid-kit';
+
+/**
+ * Starter page — `master-detail` surface. A surface-kit `MasterDetailSurface`
+ * (list + detail split that stacks below the `md` breakpoint) with a grid-kit
+ * `<DataGrid>` master and a `Section` detail driven by the selected row. Swap the
+ * sample rows for `retrieveMultiple(...)` from `./services/dataverse`.
+ */
+interface AccountRow extends Record<string, unknown> {
+  key: string;
+  name: string;
+  city: string;
+  owner: string;
+}
+
+const COLUMNS: ColumnDef<AccountRow>[] = [
+  { key: 'name', fieldName: 'name', name: 'Account', rendererType: 'text' },
+  { key: 'city', fieldName: 'city', name: 'City', rendererType: 'text' },
+];
+
+const ROWS: AccountRow[] = [
+  { key: '1', name: 'Contoso', city: 'Seattle', owner: 'Dana' },
+  { key: '2', name: 'Fabrikam', city: 'Austin', owner: 'Lee' },
+  { key: '3', name: 'Adventure Works', city: 'Denver', owner: 'Sam' },
+];
+
+export const App: React.FC = () => {
+  const [selected, setSelected] = React.useState<AccountRow | undefined>(ROWS[0]);
+
+  return (
+    <ThemeProvider>
+      <MasterDetailSurface
+        master={
+          <DataGrid<AccountRow>
+            items={ROWS}
+            columns={COLUMNS}
+            selectionMode="single"
+            onSelectionChanged={(rows) => setSelected(rows[0])}
+          />
+        }
+        detail={
+          selected ? (
+            <Section title={selected.name} variant="flat">
+              <FieldRow label="City">
+                <Text>{selected.city}</Text>
+              </FieldRow>
+              <FieldRow label="Owner">
+                <Text>{selected.owner}</Text>
+              </FieldRow>
+            </Section>
+          ) : null
+        }
+        detailFallback={<Text>Select an account to see its details.</Text>}
+      />
+    </ThemeProvider>
+  );
+};

package/templates/starter-page/_variants/App.panel.v8.tsx

@@ -0,0 +1,99 @@
+import * as React from 'react';
+import { ThemeProvider } from '@fluentui/react/lib/Theme';
+import { Stack } from '@fluentui/react/lib/Stack';
+import { TextField } from '@fluentui/react/lib/TextField';
+import { PrimaryButton, DefaultButton } from '@fluentui/react/lib/Button';
+import { DetailsList, SelectionMode, type IColumn } from '@fluentui/react/lib/DetailsList';
+import { FormSurface, Section, FieldRow, PanelSurface } from '@dataverse-kit/surface-kit';
+import { createRecord } from './services/dataverse';
+
+/**
+ * Starter page — `panel` surface. A list with a slide-in surface-kit `PanelSurface`
+ * editor (Fluent v8 Panel, width-derived PanelType, sticky footer): the Section's
+ * command bar opens the panel to create a record, which is saved via `Xrm.WebApi`.
+ * The list is a plain Fluent `DetailsList` (no grid-kit) — swap the sample rows for
+ * `retrieveMultiple(...)` from `./services/dataverse`.
+ */
+interface ContactRow {
+  key: string;
+  name: string;
+  email: string;
+}
+
+const COLUMNS: IColumn[] = [
+  { key: 'name', name: 'Name', fieldName: 'name', minWidth: 120, maxWidth: 240, isResizable: true },
+  { key: 'email', name: 'Email', fieldName: 'email', minWidth: 160, isResizable: true },
+];
+
+const SAMPLE: ContactRow[] = [
+  { key: '1', name: 'Dana Reed', email: 'dana@contoso.com' },
+  { key: '2', name: 'Lee Park', email: 'lee@fabrikam.com' },
+];
+
+export const App: React.FC = () => {
+  const [open, setOpen] = React.useState(false);
+  const [name, setName] = React.useState('');
+  const [email, setEmail] = React.useState('');
+  const [saving, setSaving] = React.useState(false);
+
+  const onSave = async () => {
+    setSaving(true);
+    try {
+      await createRecord('contact', { fullname: name, emailaddress1: email });
+      setOpen(false);
+      setName('');
+      setEmail('');
+    } catch (e) {
+      alert(`Save failed (Xrm not available here?): ${String(e)}`);
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return (
+    <ThemeProvider>
+      <FormSurface maxWidth={960}>
+        <Section
+          title="{{projectName}}"
+          columnSpan={12}
+          showCommandBar
+          commandBarItems={[
+            {
+              key: 'new',
+              text: 'New record',
+              iconProps: { iconName: 'Add' },
+              onClick: () => setOpen(true),
+            },
+          ]}
+        >
+          <DetailsList
+            items={SAMPLE}
+            columns={COLUMNS}
+            selectionMode={SelectionMode.none}
+            setKey="contacts"
+          />
+        </Section>
+      </FormSurface>
+
+      <PanelSurface
+        isOpen={open}
+        onDismiss={() => setOpen(false)}
+        title="New contact"
+        width={480}
+        footer={
+          <Stack horizontal tokens={{ childrenGap: 8 }}>
+            <PrimaryButton text="Save" onClick={onSave} disabled={saving} />
+            <DefaultButton text="Cancel" onClick={() => setOpen(false)} />
+          </Stack>
+        }
+      >
+        <FieldRow label="Full name" required>
+          <TextField value={name} onChange={(_, v) => setName(v ?? '')} />
+        </FieldRow>
+        <FieldRow label="Email">
+          <TextField value={email} onChange={(_, v) => setEmail(v ?? '')} />
+        </FieldRow>
+      </PanelSurface>
+    </ThemeProvider>
+  );
+};

package/templates/starter-page/gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+.env
+.env.local
+*.log

package/templates/starter-page/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "{{projectName}}",
+  "version": "1.0.0",
+  "description": "{{projectName}} — Dynamics 365 starter page (React, @dataverse-kit/surface-kit, Fluent v8)",
+  "private": true,
+  "scripts": {
+    "dev": "webpack serve --mode development",
+    "build": "webpack --mode production",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts,.tsx"
+  },
+  "dependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "@types/xrm": "^9.0.74",
+    "html-webpack-plugin": "^5.5.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"
+  }
+}

package/templates/starter-page/public/index.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{projectName}}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

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

@@ -0,0 +1,10 @@
+import * as React from 'react';
+import { createRoot } from 'react-dom/client';
+import { App } from './App';
+
+// On localhost, `tools/dev/mock-xrm.js` (from the `serve` dev-tool) can be loaded
+// to stub the Xrm global so this resource runs outside a model-driven host.
+const container = document.getElementById('root');
+if (container) {
+  createRoot(container).render(<App />);
+}

package/templates/starter-page/src/services/dataverse.ts

@@ -0,0 +1,30 @@
+/**
+ * Thin wrapper over Xrm.WebApi for this starter page's data access. The Xrm global
+ * is typed via @types/xrm; on localhost, stub it with tools/dev/mock-xrm.js.
+ */
+
+export type DataverseRecord = Record<string, unknown>;
+
+export async function retrieveMultiple(
+  entityLogicalName: string,
+  options = ''
+): Promise<DataverseRecord[]> {
+  const result = await Xrm.WebApi.retrieveMultipleRecords(entityLogicalName, options);
+  return result.entities;
+}
+
+export async function retrieveRecord(
+  entityLogicalName: string,
+  id: string,
+  options = ''
+): Promise<DataverseRecord> {
+  return Xrm.WebApi.retrieveRecord(entityLogicalName, id, options);
+}
+
+export async function createRecord(
+  entityLogicalName: string,
+  data: Record<string, unknown>
+): Promise<string> {
+  const res = await Xrm.WebApi.createRecord(entityLogicalName, data);
+  return res.id;
+}

package/templates/starter-page/tsconfig.json

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

package/templates/starter-page/webpack.config.js

@@ -0,0 +1,17 @@
+const path = require('path');
+const HtmlWebpackPlugin = require('html-webpack-plugin');
+
+module.exports = {
+  entry: './src/index.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 },
+};