@xrmforge/devkit 0.7.5 → 0.7.7

package/dist/templates/AGENT.md

@@ -65,28 +65,40 @@ export const onLoad = wrapHandler('LM.Account.onLoad', logger, (ctx) => {
   const form = typedForm<AccountLMFirmaForm>(ctx.getFormContext());
 
   // Direct field access - fully typed, IDE autocomplete works
-  const name = form.name.getValue();              // string | null (non-nullable, field is on form)
+  const name = form.name.getValue();              // string | null
   form.revenue.setValue(150000);                   // NumberAttribute
   const parent = form.parentaccountid.getValue();  // LookupValue[] | null
 
-  // Control access
-  form.$control('name').setDisabled(true);
+  // addOnChange directly on the proxy (NOT via $context.getAttribute)
+  form.name.addOnChange(() => { logger.debug('Name changed'); });
+  form.revenue.addOnChange(() => { recalculate(form); });
 
-  // Full FormContext for ui, data, tabs, addOnChange
+  // Control access via controls proxy (typed from ControlMap, no cast needed)
+  form.controls.name.setDisabled(true);
+  form.controls.customerid.setEntityTypes([EntityNames.Account]);  // LookupControl
+  form.controls.revenue.setVisible(false);                          // NumberControl
+
+  // Full FormContext for ui, data, tabs
   form.$context.ui.setFormNotification('OK', FormNotificationLevel.Info, 'id');
-  form.$context.getAttribute(Fields.Name).addOnChange(() => { ... });
 });
 ```
 
-**When to use `form.$context.getAttribute(Fields.X)` instead of `form.fieldname`:**
-- `addOnChange()`, `removeOnChange()` (event registration on the attribute)
+**Use `form.fieldname` (the typedForm proxy) for EVERYTHING on the attribute:**
+- `getValue()`, `setValue()` (reading and writing values)
+- `addOnChange()`, `removeOnChange()` (event registration)
 - `setRequiredLevel()`, `setSubmitMode()` (attribute-level settings)
-- `getControl()` with typed control access (use `form.$control(Fields.X)`)
+- Any attribute method: the proxy returns the full typed Attribute object
 
-**When to use `form.fieldname` (the typedForm proxy):**
-- `getValue()`, `setValue()` (reading and writing values)
-- `addOnChange()` (event registration directly on the attribute)
-- Any read-only access to field values
+**Use `form.controls.fieldname` for control-level operations:**
+- `setDisabled()`, `setVisible()`, `setLabel()`
+- `addPreSearch()` (on LookupControl)
+- `setNotification()`, `clearNotification()`
+
+**Use `form.$context` ONLY for FormContext-level operations:**
+- `form.$context.ui` (setFormNotification, tabs, close)
+- `form.$context.data` (save, entity, process)
+- `form.$context.ui.getFormType()`
+- NOT for getAttribute (use the proxy instead)
 
 **When to use `form.$unsafe(EntityFields.X)` (off-form fields):**
 
@@ -302,7 +314,7 @@ import { SaveMode, FormNotificationLevel, RequiredLevel, SubmitMode, DisplayStat
 if (ctx.getEventArgs().getSaveMode() === SaveMode.AutoSave) { ... }  // not === 70
 
 // Form type (const enum from @types/xrm, works at runtime):
-if (form.$context.ui.getFormType() === XrmEnum.FormType.Create) { ... }  // not === 1
+if (form.$context.ui.getFormType() === FormType.Create) { ... }  // not === 1
 
 // Display state:
 if (tab.getDisplayState() === DisplayState.Expanded) { ... }  // not === 'expanded'
@@ -345,7 +357,8 @@ Xrm.Navigation.openForm({ entityName: EntityNames.Account, entityId: id });  //
 - Never magic numbers for OptionSet values, status codes, or FetchXML `<value>` (use OptionSet Enums)
 - Never magic numbers for time calculations (use named constants like `MS_PER_DAY`)
 - Never `getSaveMode() === 70` (use `SaveMode.AutoSave` from @xrmforge/helpers)
-- Never `getFormType() === 1` (use `XrmEnum.FormType.Create`)
+- Never `getFormType() === 1` (use `FormType.Create` from `@xrmforge/helpers`)
+- Never `XrmEnum.FormType` (does NOT exist at runtime, esbuild does not resolve const enums from .d.ts. Use `FormType` from `@xrmforge/helpers`)
 - Never `'expanded'`/`'collapsed'` (use `DisplayState` from @xrmforge/helpers)
 - Never `'ERROR'`/`'INFO'`/`'WARNING'` (use `FormNotificationLevel`)
 - Never `'none'`/`'required'`/`'recommended'` (use `RequiredLevel`)
@@ -367,6 +380,7 @@ Xrm.Navigation.openForm({ entityName: EntityNames.Account, entityId: id });  //
 - Never unlokalized UI strings (use `pickLang()` from constants.ts)
 - Never build your own getValue/setFieldValue/setDisabled/addOnChange helpers (use `typedForm` + native Xrm API)
 - Never `import ... from '@xrmforge/typegen'` in browser code (use `@xrmforge/helpers`)
+- Never `as Xrm.Controls.LookupControl` or similar control casts (`form.controls.fieldname` returns the typed control from ControlMap)
 - Never `as any` without eslint-disable comment explaining why
 - Never untyped `catch (error)` (always `catch (error: unknown)`)
 
@@ -546,7 +560,7 @@ each attribute to its control. `mock.getControl(Fields.Name)` works out of the b
 | Legacy Pattern | XrmForge Replacement |
 |---|---|
 | `getAttribute("name")` | `form.name` (via typedForm) |
-| `getControl("name")` | `form.$control(Fields.Name)` |
+| `getControl("name")` | `form.controls.name` |
 | `Xrm.Page.getAttribute(...)` | `form.fieldname` (via typedForm) |
 | `var formContext` (global) | `const form = typedForm<MyForm>(ctx.getFormContext())` |
 | `function form_OnLoad(ctx)` | `export const onLoad = wrapHandler(...)` |
@@ -568,11 +582,11 @@ Never recreate them. Use the typed API directly.
 |---|---|
 | `GetValue(fieldName)` | `form.fieldname.getValue()` (typed via typedForm) |
 | `SetValue(fieldName, value)` | `form.fieldname.setValue(value)` (typed via typedForm) |
-| `SetDisabled(attributeName, disabled)` | `form.$control(Fields.X).setDisabled(disabled)` |
-| `SetVisible(attributeName, visible)` | `form.$control(Fields.X).setVisible(visible)` |
+| `SetDisabled(attributeName, disabled)` | `form.controls.fieldname.setDisabled(disabled)` |
+| `SetVisible(attributeName, visible)` | `form.controls.fieldname.setVisible(visible)` |
 | `SetRequiredLevel(attributeName, level)` | `form.$context.getAttribute(Fields.X).setRequiredLevel(RequiredLevel.Required)` |
 | `AddOnChange(attributeName, callback)` | `form.$context.getAttribute(Fields.X).addOnChange(cb)` |
-| `AddPreSearch(controlName, callback)` | `(form.$control(Fields.X) as Xrm.Controls.LookupControl).addPreSearch(cb)` |
+| `AddPreSearch(controlName, callback)` | `form.controls.fieldname.addPreSearch(cb)` (typed as LookupControl from ControlMap) |
 | `GetLookupValueId(fieldName)` | `formLookupId(form.fieldname)` |
 | `SetLookupValue(field, id, type, name)` | `form.fieldname.setValue([{ id, entityType, name }])` |
 | `GetId()` | `form.$context.data.entity.getId()` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xrmforge/devkit",
-  "version": "0.7.5",
+  "version": "0.7.7",
   "description": "Build orchestration and project tooling for Dynamics 365 WebResources",
   "keywords": [
     "dynamics-365",