@khester/create-dynamics-app 2.1.0 → 2.2.0

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).