@happyvertical/smrt-fields 0.40.61 → 0.40.62

package/README.md

@@ -1,140 +1,153 @@
 # @happyvertical/smrt-fields
 
-Layered field policy for SMRT objects: personalize per-field defaults,
-visibility tiers (basic/advanced/hidden), help text, labels, ordering, and
-org locks at app, tenant, and user scope — over the code-authored
-`@field({ ui })` seed.
+`@happyvertical/smrt-fields` lets an application adjust an object's form
+defaults, labels, help, order, visibility, and locks without changing the
+object's source. Policies layer organization and personal choices over the
+code-authored field definition.
 
-```typescript
-import {
-  FieldPolicy,
-  FieldPolicyCollection,
-  resolveFieldPolicy,
-  resolveFieldPolicyExplained,
-} from '@happyvertical/smrt-fields';
-
-// An org (tenant) demotes an optional field and sets a default
-const policies = await FieldPolicyCollection.create({ db });
-await policies.create({
-  objectRef: '@happyvertical/smrt-content:Article',
-  fieldName: 'summary',
-  scopeType: 'tenant',
-  tenantId,
-  visibility: 'advanced',
-  defaultValue: JSON.stringify('TBD'),
-});
-
-// Resolve the effective policy for a user in that tenant
-const resolved = await resolveFieldPolicy(
-  '@happyvertical/smrt-content:Article',
-  { tenantId, userId, db },
-);
-resolved.fields.summary.visibility; // 'advanced'
+For the complete application and operator guide, see the
+[field policy guide](https://happyvertical.github.io/smrt/field-policies).
 
-// Explain variant: per-layer contributions for admin/gear UIs
-const explained = await resolveFieldPolicyExplained(
-  '@happyvertical/smrt-content:Article',
-  { tenantId, userId, db },
-);
+## Install
+
+```bash
+pnpm add @happyvertical/smrt-fields
 ```
 
-Resolution layers (low → high): code seed → app rows → tenant rows
-(hierarchy walk via the users tenant loader, or a flat fallback when an
-injected hierarchy provider cannot resolve the tenant) → user rows. A NULL column inherits
-from the lower layer; resetting a customization is a row delete.
+The package includes `@happyvertical/smrt-users` because policy writes and
+operator actions use its permission and tenant context services.
 
-`@happyvertical/smrt-users` is a required runtime dependency: Field Policy
-uses its permission catalog and operation guard for every write and gear
-action. The hierarchy fallback concerns tenant ancestry only; it is not a
-users-authorization fallback.
+## Define a safe code seed
 
-Writes are validated against the live `ObjectRegistry`: unknown
-objects/fields are rejected, defaults are type-checked, and defaults on
-`transient`/`sensitive`/`readPermission`-gated fields are refused. Required
-fields can only be demoted from `basic` when a usable default resolves —
-and the resolver re-enforces that invariant at read time.
+The decorated model remains the definition of a field. Use its description
+and `ui` hints to supply a useful first form before any policy row exists.
 
-See `AGENTS.md` for the full architecture notes.
+```typescript
+import { field, SmrtObject, smrt } from '@happyvertical/smrt-core';
+
+@smrt({ packageName: '@acme/billing' })
+export class Invoice extends SmrtObject {
+  @field({
+    required: true,
+    description: 'Shown on the customer invoice.',
+    ui: { basic: true, group: 'billing', order: 1 },
+  })
+  title = '';
+
+  @field({ ui: { basic: false, group: 'billing', order: 2 } })
+  internalNotes = '';
+}
+```
 
-## Svelte ObjectForm
+If no field has `ui.basic: true`, fields start in the basic view. Once at
+least one field is marked basic, unmarked fields start advanced. `group` and
+`order` are code-owned hints; `locked: true` seeds a lock that can prevent a
+personal override.
 
-`@happyvertical/smrt-fields/svelte` provides provider-free generated forms.
-Pass only the generated browser field definitions and the matching resolved
-policy; `ObjectForm` renders their safe intersection, honors policy visibility
-and ordering, and keeps form state transport-neutral.
+## Resolve on the server
 
-```svelte
-<script lang="ts">
-  import { ObjectForm, createFieldInputRegistry } from '@happyvertical/smrt-fields/svelte';
+Use the resolver in trusted server code when rendering SSR or applying a
+server-owned workflow. It merges code → app → tenant ancestry → user.
 
-  const inputRegistry = createFieldInputRegistry();
-  // inputRegistry.registerField(objectRef, 'body', RichTextInput);
-</script>
+```typescript
+import { resolveFieldPolicy } from '@happyvertical/smrt-fields';
 
-<ObjectForm {objectRef} fields={collectionDefinition.fields} {policy}
-  bind:value={record} {inputRegistry} />
+const policy = await resolveFieldPolicy(
+  '@acme/billing:Invoice',
+  { tenantId: requestTenant.id, userId: session.user.id, db },
+);
+
+const title = policy.fields.title;
 ```
 
-Pass an `actions` snippet to place host controls inside the owned native form.
-The snippet renders after ObjectForm's policy-ordered fields, so a regular
-submit button keeps native Enter/click submission and ObjectForm's validation
-and `onsubmit` handling without querying the DOM.
+The client-facing generated `resolveBatch` action derives the tenant and user
+from the authenticated request context. Do not accept those identifiers from a
+browser request. It returns only fields that are safe to expose; sensitive,
+transient, and read-permission-gated fields are omitted.
 
-```svelte
-<ObjectForm {objectRef} fields={collectionDefinition.fields} {policy}
-  bind:value={record} onsubmit={save}>
-  {#snippet actions()}
-    <button type="submit">Save</button>
-  {/snippet}
-</ObjectForm>
-```
+## Use policy-aware Svelte forms
 
-An app can register all of its generated collection definitions once and put
-the `resolveBatch` custom-action client behind an `ObjectFormSourceProvider`.
-Then forms need only their canonical object reference; the registry validates
-the generated definition and the untyped custom-action response before it is
-rendered, failing closed with an accessible error state on a missing or
-mismatched response.
+For a custom form, provide a resolved policy with `FieldPolicyProvider` and
+wrap each input in `PolicyField`. The wrapper applies visibility, labels, help,
+and new-record defaults while preserving your markup and input component.
 
 ```svelte
 <script lang="ts">
   import {
-    ObjectForm,
-    ObjectFormSourceProvider,
-    ObjectFormSourceRegistry,
+    FieldPolicyProvider,
+    PolicyField,
   } from '@happyvertical/smrt-fields/svelte';
 
-  const source = new ObjectFormSourceRegistry(fieldPoliciesClient);
-  for (const definition of Object.values(collectionDefinitions)) source.register(definition);
+  let { policy, invoice = $bindable({}) } = $props();
 </script>
 
-<ObjectFormSourceProvider {source}>
-  <ObjectForm objectRef="@happyvertical/smrt-products:Product" bind:value={record} />
-</ObjectFormSourceProvider>
+<FieldPolicyProvider {policy}>
+  <PolicyField name="title">
+    <input id="title" bind:value={invoice.title} />
+  </PolicyField>
+</FieldPolicyProvider>
 ```
 
-The built-ins support text, integer, decimal, boolean, datetime, JSON, and
-reference identifiers. `FieldInputRegistry` is per app: a field-specific
-renderer takes precedence over a wire-type renderer. SMRT has no `select` wire
-type: keep the persisted wire type (normally `text`) and register a
-field-specific select-like renderer with `registerField(objectRef, fieldName,
-component)`. Reference fields deliberately remain provider-free identifier
-inputs unless an app registers its own chooser. `policyToVisibleColumnIds`
-adapts the same resolved policy to `DataTable` without hiding unmapped action or
-computed columns; static `column.hidden` remains authoritative.
-
-When a mounted create form starts another record, replace the bound record with
-an empty object or change `createSessionKey`; both begin a new default-prefill
-session without reapplying defaults after an in-form user clear.
-
-## Policy settings gear
-
-`FieldPolicyGearProvider` makes the context-derived `editor-state` action
-available to any policy-aware form without choosing a client transport. Pass an
-adapter around the generated collection client's `getEditorState`, `create`,
-`update`, and `delete` calls; it must not accept tenant or user identifiers.
-Use `FieldPolicyGearButton` where the form wants its affordance, or set
-`showPolicyGear` on `ObjectForm`. `registerFieldPolicyFocusTool(shell,
-objectRef, tool)` is a structural AdminShell seam: it registers the required
-`{ type: 'object-form', id: objectRef }` subject and returns the shell's
-disposer without making Fields depend on `smrt-svelte`.
+For generated forms, register the application's generated collection
+definitions once in an `ObjectFormSourceRegistry`, place it in an
+`ObjectFormSourceProvider`, then render an `ObjectForm` by canonical
+`objectRef`. The registry validates both the generated field definition and
+the `resolveBatch` response before rendering. See the guide for the complete
+setup, including field-specific input renderers and policy-aware tables.
+
+## Administration and personal settings
+
+Use `FieldPolicyGearProvider` with an adapter to the generated
+`getEditorState`, create, update, and delete actions. It derives identity on
+the server; adapter methods intentionally do not accept tenant or user ids.
+Use `FieldPolicyGearButton` or `showPolicyGear` on `ObjectForm` to expose
+the editor.
+
+For a settings destination, the server builds data with
+`buildFieldPolicySettingsCatalog()` and the browser renders it through
+`FieldPolicyControlPanel`. Hosts supply route, transport, confirmation, and
+AdminShell adapters. `fieldPolicyControlPanelNavItem()` and
+`registerFieldPolicyFocusTool()` are structural seams, so Fields does not
+take a dependency on a particular application shell.
+
+`fields.policy.manage` permits app and tenant administration.
+`fields.policy.personalize` permits only the current user's personal choices.
+The host must still establish a trusted authenticated principal context and
+enforce the route permission before rendering an operator destination.
+
+## Important behavior
+
+- A policy row is sparse: `null` means inherit the lower layer. Delete a row
+  to reset that scope completely.
+- `defaultValue` is the JSON-encoded wire channel. Server code with a plain
+  value should use `defaultValueRaw` or `setDefaultValue()`.
+- Required fields cannot be hidden or moved to advanced without a usable
+  resolved default. Resolution forces a required, default-less field back to
+  basic as a safety net.
+- App and tenant rows may lock a field. While the resolved organization policy
+  is locked, personal writes are rejected and old personal rows do not apply.
+- Defaults are rejected for sensitive, transient, and read-permission-gated
+  fields. Reference defaults must use a valid UUID unless that reference
+  declares a text id type.
+
+## Usage learning
+
+Optional usage capture records bounded, aggregated submissions from
+authenticated tenant members and turns qualified patterns into
+administrator-reviewed tenant-policy suggestions. It never auto-applies a
+suggestion. `ObjectForm` reports only after its host confirms persistence;
+browser values transit only for low-cardinality boolean and reference fields,
+and telemetry failures never affect the saved submit.
+
+Operators enable the dormant maintenance and suggestion schedules explicitly
+with `ensureFieldUsageLearningSchedules({ db })`. The learning loop retains
+aggregates and uses conservative thresholds; its accepted/dismissed suggestion
+queue is restricted to `fields.policy.manage`. See the
+[field policy guide](https://happyvertical.github.io/smrt/field-policies#usage-learning-and-suggestions)
+for the capture, privacy, retention, and schedule contract.
+
+## Example application
+
+The [SMRT SaaS starter field-policy walkthrough](https://github.com/happyvertical/smrt-saas-starter/pull/51)
+uses SMRT `0.40.61` and shows the owner/admin controls and the member-facing
+personal form flow in a working application.