@cat-factory/app 0.236.1 → 0.237.0

package/README.md

@@ -111,12 +111,27 @@ When the backend declares the fields and the SPA only collects them, render them
 surfaces use it: an initiative preset's create form and a reusable operation's per-case form on a
 custom task type (`AddTaskModal`). Adding a third is a `:fields` binding, not a component.
 
+**Grouping is the descriptor's own, through `descriptorFieldSections`**, not a wrapper each surface
+builds: consecutive fields sharing a `section` render under one caption, and the reduction applies
+`showWhen` first, so a section whose every field is hidden renders no caption. Never re-group or
+re-order the fields at a call site, or a form renders in an order its author never wrote.
+
+**A captioned run is rendered FLAT, never as a per-run wrapper element** (`descriptorFormRows`
+carries each run's caption on the field that opens it). Run membership is derived state that shifts
+as `showWhen` reveals fields, while a field's identity does not: nesting the fields inside a wrapper
+re-parents them when a boundary moves, and Vue can only do that by unmounting and remounting. The
+remounted input is typically the one being TYPED INTO, because typing into the trigger is what moved
+the boundary, so it loses focus, caret and IME composition mid-keystroke. Keep every field a sibling
+keyed by `field.key` and the diff MOVES it instead. The same trap as keying any list by index, with a
+worse symptom: `descriptorFields.spec.ts` pins that a reveal preserves every field key.
+
 Four rules travel with it. **Validate with the shared `validateDescriptorFields`** so the submit
 button reflects exactly what the server will refuse, and **submit the shared
 `sanitizeDescriptorFields` result** so a stale answer on a since-hidden `showWhen` field never
-reaches the wire. **The labels are deployment-authored English rendered verbatim**: only the chrome
-around them (a path-invalid message, section captions) is i18n, so no descriptor string enters a
-locale catalog. And **the value-bag rules live in `utils/descriptorFields.ts`, not in the SFC**
+reaches the wire. **Every string a descriptor carries is deployment-authored English rendered
+verbatim**, labels, help, option captions and the `section` grouping captions alike: only the
+platform's own chrome around them (the path-invalid message) is i18n, so no descriptor string enters
+a locale catalog. And **the value-bag rules live in `utils/descriptorFields.ts`, not in the SFC**
 (`defaultDescriptorValues` for the initial values, `setDescriptorValue` / `setDescriptorCheckbox` /
 `toggleDescriptorGroupValue` for one edit): what an edit freezes on an entity is what a unit test
 must be able to reach, and a rule inside a component is only reachable by mounting one.

package/app/components/common/DescriptorFields.vue

@@ -8,16 +8,18 @@
 //
 // It extends `ProviderConnectionTab.vue`'s flat-field pattern with the shapes a declared form needs:
 // `checkbox-group` (multi-select whose value is `string[]`), `path` (a repo-relative dir with inline
-// safety validation), and single-condition `showWhen` visibility. Labels/help/option captions are
-// backend-supplied English (the `describeConfig` convention); only the chrome is i18n.
+// safety validation), single-condition `showWhen` visibility, and `section` grouping captions.
+// Labels/help/option/section captions are backend-supplied English (the `describeConfig`
+// convention); only the chrome is i18n.
 //
 // The model is the typed `DescriptorFieldValues` map (scalars stay strings, `number` a number,
 // `checkbox` a boolean, `checkbox-group` a `string[]`), so it round-trips the wire contract and the
 // shared `validateDescriptorFields` / `sanitizeDescriptorFields` rules unchanged.
 import { computed } from 'vue'
-import { isDescriptorFieldVisible, isSafeRepoDirPath } from '@cat-factory/contracts'
+import { isSafeRepoDirPath } from '@cat-factory/contracts'
 import type { DescriptorField, DescriptorFieldValue, DescriptorFieldValues } from '~/types/domain'
 import {
+  descriptorFormRows,
   descriptorGroupValue,
   setDescriptorCheckbox,
   setDescriptorValue,
@@ -39,12 +41,20 @@ const props = withDefaults(
 const model = defineModel<DescriptorFieldValues>({ required: true })
 const { t } = useI18n()
 
-// Only fields whose `showWhen` holds against the current values are shown; a hidden field's stale
-// value is kept in the model (so re-showing restores it) but the server + client both drop it at
-// sanitize/validate time, so it can never freeze an unvalidated value.
-const visibleFields = computed(() =>
-  props.fields.filter((f) => isDescriptorFieldVisible(f, model.value)),
-)
+// The fields to render, each carrying the section caption that opens its run. Only fields whose
+// `showWhen` holds against the current values are shown; a hidden field's stale value is kept in the
+// model (so re-showing restores it) but the server + client both drop it at sanitize/validate time,
+// so it can never freeze an unvalidated value.
+//
+// The grouping underneath is the shared `descriptorFieldSections`, so a caption spans exactly what
+// one function says it spans, which is the same statement the boot check refuses a declaration
+// against. A form declaring no section is one uncaptioned run, i.e. byte-for-byte the flat column
+// this component always rendered.
+//
+// The rows are FLAT, and the template keeps them siblings keyed by `field.key`, because run
+// membership shifts as `showWhen` reveals fields while a field's identity does not: see
+// `descriptorFormRows` for why a per-run wrapper would remount the input being typed into.
+const rows = computed(() => descriptorFormRows(props.fields, model.value))
 
 // The value-mutation rules live in `utils/descriptorFields.ts` as pure functions over the bag (what
 // an edit does to it, including the drop-when-empty rule that keeps an unset answer from freezing),
@@ -90,76 +100,93 @@ function selectItems(field: DescriptorField) {
 </script>
 
 <template>
-  <div v-if="visibleFields.length" class="space-y-4">
-    <UFormField
-      v-for="field in visibleFields"
-      :key="field.key"
-      :label="field.label"
-      :help="field.help"
-      :required="field.required"
-      :error="pathInvalid(field) ? t('common.pathInvalid') : undefined"
-      :data-testid="`${testidPrefix}-${field.key}`"
-    >
-      <!-- checkbox-group: a vertical list of toggles whose value is the checked option set. -->
-      <div v-if="field.type === 'checkbox-group'" class="space-y-1.5">
-        <UCheckbox
-          v-for="opt in field.options ?? []"
-          :key="opt.value"
-          :model-value="groupValue(field.key).includes(opt.value)"
-          :label="opt.label"
-          :data-testid="`${testidPrefix}-${field.key}-${opt.value}`"
-          @update:model-value="
-            (v: boolean | 'indeterminate') => toggleGroup(field.key, opt.value, v === true)
-          "
-        />
-      </div>
+  <div v-if="rows.length" class="space-y-4">
+    <!-- One keyed fragment per FIELD, never per run: a run's caption rides the field that opens it,
+         so revealing a field re-captions rows in place instead of re-parenting the inputs (which
+         Vue can only do by remounting them, destroying the one being typed into). -->
+    <template v-for="{ field, caption, startsGroup } in rows" :key="field.key">
+      <!-- The section caption, rendered verbatim above its run (deployment-authored English, like
+           the field labels themselves). Its testid is the same on every caption, because a caption
+           is arbitrary Unicode a deployment writes in its own language: a spec addresses one by the
+           TEXT it is asserting about (`getByTestId(...).filter({ hasText })`) rather than by a
+           testid that would have to be slugified to be selectable. -->
+      <p
+        v-if="caption"
+        class="-mb-1 text-[11px] font-semibold uppercase tracking-wide text-slate-400"
+        :class="{ 'pt-2': startsGroup }"
+        :data-testid="`${testidPrefix}-section`"
+      >
+        {{ caption }}
+      </p>
+      <UFormField
+        :label="field.label"
+        :help="field.help"
+        :required="field.required"
+        :error="pathInvalid(field) ? t('common.pathInvalid') : undefined"
+        :class="{ 'pt-2': startsGroup && !caption }"
+        :data-testid="`${testidPrefix}-${field.key}`"
+      >
+        <!-- checkbox-group: a vertical list of toggles whose value is the checked option set. -->
+        <div v-if="field.type === 'checkbox-group'" class="space-y-1.5">
+          <UCheckbox
+            v-for="opt in field.options ?? []"
+            :key="opt.value"
+            :model-value="groupValue(field.key).includes(opt.value)"
+            :label="opt.label"
+            :data-testid="`${testidPrefix}-${field.key}-${opt.value}`"
+            @update:model-value="
+              (v: boolean | 'indeterminate') => toggleGroup(field.key, opt.value, v === true)
+            "
+          />
+        </div>
 
-      <USelect
-        v-else-if="field.type === 'select'"
-        :model-value="stringValue(field.key)"
-        :items="selectItems(field)"
-        class="w-full"
-        :placeholder="field.placeholder"
-        @update:model-value="(v: string) => set(field.key, v)"
-      />
+        <USelect
+          v-else-if="field.type === 'select'"
+          :model-value="stringValue(field.key)"
+          :items="selectItems(field)"
+          class="w-full"
+          :placeholder="field.placeholder"
+          @update:model-value="(v: string) => set(field.key, v)"
+        />
 
-      <USwitch
-        v-else-if="field.type === 'checkbox'"
-        :model-value="boolValue(field.key)"
-        @update:model-value="(v: boolean) => setCheckbox(field, v)"
-      />
+        <USwitch
+          v-else-if="field.type === 'checkbox'"
+          :model-value="boolValue(field.key)"
+          @update:model-value="(v: boolean) => setCheckbox(field, v)"
+        />
 
-      <UTextarea
-        v-else-if="field.type === 'textarea'"
-        :model-value="stringValue(field.key)"
-        :rows="3"
-        autoresize
-        class="w-full"
-        :maxlength="field.maxLength"
-        :placeholder="field.placeholder"
-        @update:model-value="(v: string) => set(field.key, v)"
-      />
+        <UTextarea
+          v-else-if="field.type === 'textarea'"
+          :model-value="stringValue(field.key)"
+          :rows="3"
+          autoresize
+          class="w-full"
+          :maxlength="field.maxLength"
+          :placeholder="field.placeholder"
+          @update:model-value="(v: string) => set(field.key, v)"
+        />
 
-      <UInput
-        v-else-if="field.type === 'number'"
-        :model-value="numberStr(field.key)"
-        type="number"
-        class="w-full font-mono"
-        :placeholder="field.placeholder"
-        @update:model-value="(v: string) => set(field.key, v === '' ? undefined : Number(v))"
-      />
+        <UInput
+          v-else-if="field.type === 'number'"
+          :model-value="numberStr(field.key)"
+          type="number"
+          class="w-full font-mono"
+          :placeholder="field.placeholder"
+          @update:model-value="(v: string) => set(field.key, v === '' ? undefined : Number(v))"
+        />
 
-      <!-- path + text/password (the untyped default): a single-line input. `path`s stay mono. -->
-      <UInput
-        v-else
-        :model-value="stringValue(field.key)"
-        :type="field.type === 'password' ? 'password' : 'text'"
-        class="w-full"
-        :class="{ 'font-mono': field.type === 'path' }"
-        :maxlength="field.maxLength"
-        :placeholder="field.placeholder"
-        @update:model-value="(v: string) => set(field.key, v)"
-      />
-    </UFormField>
+        <!-- path + text/password (the untyped default): a single-line input. `path`s stay mono. -->
+        <UInput
+          v-else
+          :model-value="stringValue(field.key)"
+          :type="field.type === 'password' ? 'password' : 'text'"
+          class="w-full"
+          :class="{ 'font-mono': field.type === 'path' }"
+          :maxlength="field.maxLength"
+          :placeholder="field.placeholder"
+          @update:model-value="(v: string) => set(field.key, v)"
+        />
+      </UFormField>
+    </template>
   </div>
 </template>

package/app/docs/consumer-extensions.md

@@ -185,11 +185,15 @@ module). The SPA merges it into the create-task picker and the card-badge catalo
   `category` groups the picker (below).
 - **`fields`** are descriptor-driven create-form inputs over the shared descriptor-form vocabulary
   (`text` / `textarea` / `number` / `select` / `checkbox` / `checkbox-group` / `path`, with
-  defaults and `showWhen` visibility; `password` is excluded by construction because a task field
-  value reaches prompts and telemetry). Their values land in the task's sparse
-  `taskTypeFields.custom` bag (no migration). A BACKEND-registered descriptor is enforced
-  server-side on create as well (required answers, option lists, lengths); a code-shipped one is
-  known only to the SPA, so the create form is its only check (see the Validation note below).
+  defaults, `showWhen` visibility and a `section` grouping caption; `password` is excluded by
+  construction because a task field value reaches prompts and telemetry). Their values land in the
+  task's sparse `taskTypeFields.custom` bag (no migration). A BACKEND-registered descriptor is
+  enforced server-side on create as well (required answers, option lists, lengths); a code-shipped
+  one is known only to the SPA, so the create form is its only check (see the Validation note below).
+  A `section` groups a long form into captioned runs and changes nothing else; declare a section's
+  fields consecutively, since a backend registration whose form could caption one twice fails boot
+  and a code-shipped one would simply render the caption twice. Interleaving a section with a
+  mutually exclusive `showWhen` branch is not that fault: only one half is ever on screen.
 - **`formPanel`** optionally names a bespoke create-form section component you contribute to the
   `taskTypeFormPanels` slot (paired by that id, like `resultViews`); shown INSTEAD of `fields`. An
   unpaired id degrades to the descriptor fields.

package/app/utils/descriptorFields.spec.ts

@@ -2,6 +2,7 @@ import { describe, it, expect } from 'vitest'
 import type { DescriptorField } from '~/types/domain'
 import {
   defaultDescriptorValues,
+  descriptorFormRows,
   descriptorGroupValue,
   setDescriptorCheckbox,
   setDescriptorValue,
@@ -124,3 +125,70 @@ describe('toggleDescriptorGroupValue', () => {
     })
   })
 })
+
+// The layout half of `section` grouping. What a caption SPANS is the shared contracts rule (tested
+// there); what these assert is the property that rule's rendering has to preserve, and the reason the
+// rows are flat at all: a field's identity survives a boundary move, so the keyed diff MOVES the
+// live input instead of remounting it.
+describe('descriptorFormRows', () => {
+  const keysOf = (rows: ReturnType<typeof descriptorFormRows>) => rows.map((r) => r.field.key)
+
+  it('carries each run caption on the field that OPENS it, once', () => {
+    const rows = descriptorFormRows(
+      [
+        field({ key: 'entity' }),
+        field({ key: 'style', section: 'Shape' }),
+        field({ key: 'verb', section: 'Shape' }),
+        field({ key: 'dir', type: 'path', section: 'Placement' }),
+      ],
+      {},
+    )
+    expect(rows.map((r) => [r.field.key, r.caption, r.startsGroup])).toEqual([
+      ['entity', undefined, false],
+      ['style', 'Shape', true],
+      ['verb', undefined, false],
+      ['dir', 'Placement', true],
+    ])
+  })
+
+  it('renders a sectionless form as the flat column, with no caption and no group gap', () => {
+    const rows = descriptorFormRows([field({ key: 'entity' }), field({ key: 'notes' })], {})
+    expect(rows.map((r) => [r.caption, r.startsGroup])).toEqual([
+      [undefined, false],
+      [undefined, false],
+    ])
+    expect(descriptorFormRows([], {})).toEqual([])
+  })
+
+  it('keeps a field key STABLE when a reveal moves it into another run', () => {
+    // The regression this shape exists for. `note` is unsectioned and gated, so revealing it splits
+    // the `Shape` run in two and re-captions `style`. Boot refuses THIS declaration (the split is
+    // reachable), and the renderer still has to be total over it, because a wire descriptor can
+    // arrive from a node whose build predates the refusal. Every field key present before is still
+    // present after, so Vue's keyed diff moves those nodes rather than unmounting them: typing into
+    // `advanced` (the trigger) cannot destroy the input being typed into.
+    const fields = [
+      field({ key: 'advanced', type: 'checkbox' }),
+      field({ key: 'verb', section: 'Shape' }),
+      field({ key: 'note', showWhen: { key: 'advanced', equals: true } }),
+      field({ key: 'style', section: 'Shape' }),
+    ]
+    expect(keysOf(descriptorFormRows(fields, {}))).toEqual(['advanced', 'verb', 'style'])
+
+    const revealed = descriptorFormRows(fields, { advanced: true })
+    expect(keysOf(revealed)).toEqual(['advanced', 'verb', 'note', 'style'])
+    // The caption moved (the second run needs its own) while the field identities did not.
+    expect(revealed.map((r) => r.caption)).toEqual([undefined, 'Shape', undefined, 'Shape'])
+  })
+
+  it('marks a later UNCAPTIONED run as opening a group too, so the gap is not caption-only', () => {
+    const rows = descriptorFormRows(
+      [field({ key: 'verb', section: 'Shape' }), field({ key: 'notes' })],
+      {},
+    )
+    expect(rows.map((r) => [r.field.key, r.startsGroup])).toEqual([
+      ['verb', false],
+      ['notes', true],
+    ])
+  })
+})

package/app/utils/descriptorFields.ts

@@ -1,4 +1,4 @@
-import { descriptorFieldDefaults } from '@cat-factory/contracts'
+import { descriptorFieldDefaults, descriptorFieldSections } from '@cat-factory/contracts'
 import type { DescriptorField, DescriptorFieldValue, DescriptorFieldValues } from '~/types/domain'
 
 // Form-side helpers over the shared descriptor-field vocabulary (`contracts/src/form-fields.ts`),
@@ -75,6 +75,45 @@ export function descriptorGroupValue(values: DescriptorFieldValues, key: string)
   return Array.isArray(value) ? value : []
 }
 
+/** One row of a rendered descriptor form: a field, plus the section chrome that precedes it. */
+export interface DescriptorFormRow {
+  /** The field to render. Its `key` is the row's identity in the keyed diff. */
+  field: DescriptorField
+  /** The caption to print above this field, set only on the field that OPENS a captioned run. */
+  caption?: string
+  /** Whether this field opens a run with another run before it, i.e. needs the between-runs gap. */
+  startsGroup: boolean
+}
+
+/**
+ * A descriptor form reduced to a FLAT list of rows: the shared `descriptorFieldSections` grouping,
+ * with each run's caption carried on the field that opens it rather than on a wrapper around it.
+ *
+ * Flat is the whole point, and it is a correctness rule rather than a layout preference. Run
+ * membership is DERIVED state that changes as `showWhen` reveals and hides fields, while a field's
+ * identity does not. Rendering the runs as nested `v-for`s re-parents a field the moment a boundary
+ * moves, and Vue cannot move a node between two parents: it unmounts and remounts it. The field being
+ * remounted is typically the one being TYPED INTO, because typing into a `showWhen` trigger is what
+ * moved the boundary, so the input loses focus, caret and any in-flight IME composition mid-keystroke.
+ * Keeping every field a sibling under one parent, keyed by `field.key`, makes that a MOVE, which
+ * preserves the live input: the behaviour the flat column had before sections existed.
+ *
+ * Presentation, so it lives here rather than in contracts: what a caption spans is the shared rule,
+ * and this is only how the SPA lays that out.
+ */
+export function descriptorFormRows(
+  fields: readonly DescriptorField[],
+  values: DescriptorFieldValues,
+): DescriptorFormRow[] {
+  return descriptorFieldSections(fields, values).flatMap((group, groupIndex) =>
+    group.fields.map((field, fieldIndex) => ({
+      field,
+      ...(fieldIndex === 0 && group.section !== undefined ? { caption: group.section } : {}),
+      startsGroup: fieldIndex === 0 && groupIndex > 0,
+    })),
+  )
+}
+
 /** One option toggled on/off in a `checkbox-group` field's value (deduped, order-preserving). */
 export function toggleDescriptorGroupValue(
   values: DescriptorFieldValues,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.236.1",
+  "version": "0.237.0",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",
@@ -40,7 +40,7 @@
     "valibot": "^1.4.2",
     "vue": "3.5.40",
     "wretch": "^3.0.9",
-    "@cat-factory/contracts": "0.256.0"
+    "@cat-factory/contracts": "0.257.0"
   },
   "devDependencies": {
     "@toad-contracts/testing": "0.3.2",