@qoretechnologies/reqraft 0.10.46-pr.95.ge595a13 → 0.10.46

package/src/components/form/engine/FormEngine.stories.tsx

@@ -2,7 +2,7 @@ import { ReqoreInput } from '@qoretechnologies/reqore';
 import { TSizes } from '@qoretechnologies/reqore/dist/constants/sizes';
 import { IQorusFormSchema } from '@qoretechnologies/ts-toolkit';
 import { Meta, StoryObj } from '@storybook/react-vite';
-import { ChangeEvent, useState } from 'react';
+import { ChangeEvent, useEffect, useState } from 'react';
 import { expect, fireEvent, fn, userEvent, waitFor, within } from 'storybook/test';
 import { validateField } from '../../../helpers/validations';
 import { defaultQorusTypes } from '../../../hooks/useQorusTypes';
@@ -786,6 +786,27 @@ const CodeEditorStandin = ({
 // (rendered by a host-injected code-editor) inherits `language` from
 // a sibling `lang` picker, so flipping the picker live-changes the
 // editor's syntax highlighting with no refetch.
+/**
+ * The same stand-in without the "syntax: <language>" tag.
+ *
+ * That tag exists to prove an inherited `language` prop reaches the renderer,
+ * and the stories that assert it keep it. Where the row already shows a Language
+ * control directly above the editor, it is the same fact stated twice — which is
+ * what the review flagged on `CompactRowAbsorbsLanguage`.
+ */
+const CodeEditorStandinNoSyntax = (props: Parameters<typeof CodeEditorStandin>[0]) => (
+  <div data-testid='code-editor-mock'>
+    <ReqoreInput
+      fluid
+      size={props.size}
+      icon='CodeLine'
+      placeholder='Source code (stand-in code-editor)'
+      value={typeof props.value === 'string' ? props.value : ''}
+      onChange={(event: ChangeEvent<HTMLInputElement>) => props.onChange?.(event.target.value)}
+    />
+  </div>
+);
+
 export const OptionInheritsRenderPropFromSibling: Story = {
   parameters: {
     docs: {
@@ -994,7 +1015,7 @@ export const CompactRowAbsorbsLanguage: Story = {
   args: {
     compact: true,
     minColumnWidth: '360px',
-    componentOverrides: { 'code-editor': CodeEditorStandin },
+    componentOverrides: { 'code-editor': CodeEditorStandinNoSyntax },
     value: {
       language: { type: 'string', value: 'qore' },
       source: { type: 'string', value: '%new-style\nclass Example {\n}\n' },
@@ -1080,14 +1101,14 @@ export const CompactRowCodeEditorPreview: Story = {
     docs: {
       description: {
         story:
-          'Renders a compact-mode code-editor row over a multi-line Qore source value — the value cell replaces the truncated string with a lines/chars summary tag and a collapsible monospace preview mounts under the row.',
+          'Renders a compact-mode code-editor row over a multi-line Qore source value — the value cell replaces the truncated string with a monospaced size note under the field name and a collapsible monospace preview mounts under the row. The stand-in prints no "syntax:" line: this row carries a Language control directly above the editor, so it would be the same fact stated twice.',
       },
     },
   },
   args: {
     compact: true,
     minColumnWidth: '360px',
-    componentOverrides: { 'code-editor': CodeEditorStandin },
+    componentOverrides: { 'code-editor': CodeEditorStandinNoSyntax },
     value: {
       language: { type: 'string', value: 'qore' },
       source: {
@@ -1143,6 +1164,132 @@ export const CompactRowCodeEditorPreview: Story = {
   },
 };
 
+export const CompactRowCodeEditorMessage: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "A schema `messages` entry on a code-editor field. Every other field surfaces its messages on the collapsed row; a code field draws a preview in the same cell, and the message has to survive beside it — a diagnostic the reader only finds by opening the field is not reported. Qorus puts source-validation results here, so an invalid service is called out on the row rather than at save time.",
+      },
+    },
+  },
+  args: {
+    ...CompactRowCodeEditorPreview.args,
+    options: {
+      ...(CompactRowCodeEditorPreview.args as any).options,
+      source: {
+        ...(CompactRowCodeEditorPreview.args as any).options.source,
+        // The field ABSORBS its language sibling, which is how Qorus ships it:
+        // the language control renders inside the Source Code container. That
+        // is the shape the message has to survive.
+        absorb_fields: ['language'],
+        // Qorus groups its fields (INFO / SCALING), so the row renders inside a
+        // group rather than in a flat list.
+        group: 'info',
+        messages: [
+          {
+            intent: 'danger',
+            title: 'Line 4',
+            content: "syntax error, unexpected '}'",
+          },
+        ],
+      },
+    },
+  },
+  play: async ({ canvasElement }) => {
+    // The message renders on the collapsed row, beside the code preview rather
+    // than instead of it.
+    await waitFor(
+      () => {
+        const row = canvasElement.querySelector('[data-field="source"]');
+        expect(row?.textContent ?? '').toContain('Line 4');
+        expect(row?.textContent ?? '').toContain("syntax error, unexpected '}'");
+      },
+      { timeout: 5000 }
+    );
+
+    const row = canvasElement.querySelector('[data-field="source"]');
+    // ... and the preview it sits beside is still there.
+    expect(row?.textContent ?? '').toContain('class ExampleJob inherits QorusJob');
+  },
+};
+
+/**
+ * Adds a schema message to a field a moment AFTER the form has mounted, the way
+ * a host that validates asynchronously does.
+ */
+const LateMessageHarness = (args: any) => {
+  const [options, setOptions] = useState(args.options);
+
+  useEffect(() => {
+    const timer = setTimeout(
+      () =>
+        setOptions((current: any) => ({
+          ...current,
+          source: {
+            ...current.source,
+            messages: [
+              { intent: 'danger', title: 'Line 4', content: "syntax error, unexpected '}'" },
+            ],
+          },
+        })),
+      100
+    );
+    return () => clearTimeout(timer);
+  }, []);
+
+  return <FormEngine {...args} options={options} />;
+};
+
+export const CompactRowCodeEditorLateMessage: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'The same message, but added to the schema after the form has mounted — which is how a host that validates asynchronously delivers one. A message that only renders when it was present at mount is no use to a validator: the answer always arrives later than the field did.',
+      },
+    },
+  },
+  args: { ...CompactRowCodeEditorPreview.args },
+  render: (args) => <LateMessageHarness {...args} />,
+  play: async ({ canvasElement }) => {
+    await waitFor(
+      () => {
+        const row = canvasElement.querySelector('[data-field="source"]');
+        expect(row?.textContent ?? '').toContain('Line 4');
+      },
+      { timeout: 10000 }
+    );
+  },
+};
+
+export const CompactRowMessageWhileEditing: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "The same message, with the row OPEN. A schema message is guidance about the value, so the moment it matters most is while the value is being edited — and a validation diagnostic is useless anywhere else: it names a line the author can only fix with the editor in front of them. Qorus opens the Source Code row on arrival, so a message that only survives on the collapsed row was never seen at all.",
+      },
+    },
+  },
+  args: { ...CompactRowCodeEditorMessage.args },
+  play: async ({ canvasElement }) => {
+    // Open the row, the way an author does before fixing what the message says.
+    await waitFor(() => {
+      expect(canvasElement.querySelector('[data-field="source"]')).toBeTruthy();
+    });
+    await fireEvent.click(canvasElement.querySelector('[data-field="source"]') as HTMLElement);
+
+    await waitFor(() => {
+      expect(canvasElement.querySelector('.readfirst-row-editing')).toBeTruthy();
+    });
+
+    const editingRow = canvasElement.querySelector('.readfirst-row-editing') as HTMLElement;
+    expect(editingRow?.textContent ?? '').toContain('Line 4');
+    expect(editingRow?.textContent ?? '').toContain("syntax error, unexpected '}'");
+  },
+};
+
 export const CompactRowMarkdownPreview: Story = {
   parameters: {
     docs: {
@@ -3031,9 +3178,10 @@ export const CompactMultiSelectEditing: Story = {
   },
   play: async () => {
     await _testsWaitForText('Audiences');
-    // Read row joins the selected items.
-    await _testsWaitForText('orders');
-    await _testsClickText('orders');
+    // Read row joins the selected items, labelled the way the picker labels
+    // them (`Orders`) rather than the way they are stored (`orders`).
+    await _testsWaitForText('Orders');
+    await _testsClickText('Orders');
     await waitFor(() => expect(document.querySelector('.options-readfirst-card')).toBeTruthy(), {
       timeout: 10000,
     });
@@ -3817,8 +3965,16 @@ export const CompactExpressions: Story = {
   play: async () => {
     const stop = startDpqlMockLsp();
     try {
-      // Read-first: the offline DPQL summary of the AST.
-      await _testsWaitForText('"$local:name" == "John"');
+      // Read-first: the offline DPQL summary of the AST — the literals read as
+      // the text they are, and the template reference reads as a chip rather
+      // than as its raw `$local:name` token inside the string.
+      await waitFor(() => {
+        const chip = Array.from(document.querySelectorAll('.reqore-tag')).find((tag) =>
+          tag.textContent?.includes('$local:name')
+        );
+        expect(chip, 'the reference in the summary renders as a chip').toBeTruthy();
+      });
+      await _testsWaitForText('" == "John"');
 
       // Drill in → the card hosts the ExpressionField (Visual builder).
       await fireEvent.click(
@@ -4614,7 +4770,8 @@ export const CompactFieldTypes: Story = {
     await _testsWaitForText('0 0 * * *'); // cron
     await _testsWaitForText('Python'); // select → allowed_value display label
     await _testsWaitForText('Medium'); // enum → allowed_value display label
-    await _testsWaitForText('orders, batch'); // multi-select joined
+    // multi-select joined, labelled the way the picker labels them
+    await _testsWaitForText('Orders, Batch');
     await _testsWaitForText('a, b'); // list joined
     await _testsWaitForText('x, y, z'); // YAML-serialized list summarised
     await _testsWaitForText('#0000FF'); // colour → uppercase hex
@@ -4644,8 +4801,15 @@ export const CompactFieldTypes: Story = {
     // than a raw hash key-count.
     await _testsWaitForText('512MiB');
     await _testsWaitForText(/example_customer_addresses/);
-    // Expression field → read-first shows the offline DPQL summary of the AST.
-    await _testsWaitForText('"$local:name" == "John"');
+    // Expression field → read-first shows the offline DPQL summary of the AST,
+    // with the template reference inside it chipped rather than printed raw.
+    await waitFor(() => {
+      const chip = Array.from(document.querySelectorAll('.reqore-tag')).find((tag) =>
+        tag.textContent?.includes('$local:name')
+      );
+      expect(chip, 'the reference in the summary renders as a chip').toBeTruthy();
+    });
+    await _testsWaitForText('" == "John"');
     await expect(document.querySelectorAll('.options-readfirst-card')).toHaveLength(0);
 
     // A hash renders its read-first preview (the structured tree by default)
@@ -6107,6 +6271,173 @@ export const CompactReadFirstRichtextTemplateBaseline: Story = {
   },
 };
 
+/**
+ * The same summary, built from the value the server actually sends.
+ *
+ * `CompactReadFirstRichtextTemplateBaseline` above separates its chips with
+ * SPACES, and that is why it kept passing while the row stayed broken: an alert
+ * rule's Gmail message body is five `\n`-separated lines, and the newline is the
+ * whole difference. The richtext branch is the only read-first value that opts
+ * into `white-space: pre` — it has to, or the space between a word and the chip
+ * beside it is dropped — and `pre` honours the newlines too. Every prose segment
+ * after the first then rendered a blank first line, measured 30px against the
+ * chips' 14px, and the wrapper's `align-items: center` put each word 12px below
+ * the chip next to it. The row read as a staircase (supah, 2026-08-28).
+ *
+ * The row is a single line by construction; every other value type reaches that
+ * through `nowrap`, which eats newlines for free. So the fix is to collapse them
+ * here as well, and this story holds the two things that prove it: the prose
+ * boxes are one line tall, not two, and they still share a centre with the chips.
+ */
+const RichtextMultilineTemplateValue: IOptions = {
+  body: {
+    type: 'richtext',
+    value: [
+      {
+        type: 'paragraph',
+        children: [
+          { text: 'Alert: ' },
+          { type: 'tag', value: '$fsminput:alert_code', label: 'alert_code', children: [{ text: '' }] },
+          { text: '\nSeverity: ' },
+          { type: 'tag', value: '$fsminput:severity', label: 'severity', children: [{ text: '' }] },
+          { text: '\nRule: ' },
+          { type: 'tag', value: '$fsminput:rule_name', label: 'rule_name', children: [{ text: '' }] },
+        ],
+      },
+    ],
+  },
+} as unknown as IOptions;
+
+export const CompactReadFirstRichtextMultilineTemplate: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "A multi-line richtext value in the read-first row. The row is one line, so the value's newlines must collapse rather than break — and the row must not also hover the raw template source, which is what the chips are there to replace.",
+      },
+    },
+  },
+  args: {
+    compact: true,
+    minColumnWidth: '300px',
+    options: RichtextTemplateSchema,
+    value: RichtextMultilineTemplateValue,
+  },
+  play: async ({ canvasElement }) => {
+    await _testsWaitForText('alert_code');
+
+    const proseSpans = Array.from(canvasElement.querySelectorAll('span')).filter(
+      // the collapsed newline leaves the segment with a leading space
+      (element) =>
+        element.children.length === 0 && /^\s*(Alert|Severity|Rule):/.test(element.textContent || '')
+    ) as HTMLElement[];
+    await expect(proseSpans.length).toBe(3);
+
+    // No hard break survives into the summary: a segment that still carried its
+    // newline would render a blank first line and measure two lines tall.
+    for (const span of proseSpans) {
+      await expect(span.textContent).not.toContain('\n');
+    }
+
+    const chipEl = Array.from(canvasElement.querySelectorAll('span')).find(
+      (element) => element.children.length === 0 && element.textContent?.trim() === 'alert_code'
+    ) as HTMLElement;
+    const chipHeight = chipEl.getBoundingClientRect().height;
+
+    // One line tall, like the chip beside it -- this is the assertion that fails
+    // on the unfixed code, where the blank line doubled it.
+    for (const span of proseSpans) {
+      await expect(span.getBoundingClientRect().height).toBeLessThan(chipHeight * 1.6);
+    }
+
+    // ...and they still sit on the chips' centre line, which is what the earlier
+    // baseline fix bought and this must not give back.
+    const chipRect = chipEl.getBoundingClientRect();
+    for (const span of proseSpans) {
+      const rect = span.getBoundingClientRect();
+      const offset = Math.abs(rect.top + rect.height / 2 - (chipRect.top + chipRect.height / 2));
+      await expect(offset).toBeLessThanOrEqual(1.5);
+    }
+
+    // The row draws the value in full as chips, so it must not ALSO carry a
+    // native tooltip of the raw source: hovering a chip fired that and the chip's
+    // own popover together, and only the popover is visible in a screenshot.
+    const valueCell = chipEl.closest('[title]');
+    await expect(valueCell).toBeNull();
+  },
+};
+
+/**
+ * A list of template-capable STRINGS, which is what an email `To` field is.
+ *
+ * Gmail's `to` is `type: "list"`, `element_type: "string"`,
+ * `supports_templates: true`, so each element is edited with a rich-text editor
+ * and its value arrives wrapped: `{type: "richtext", value: [{type:
+ * "paragraph", …}]}`. The hash-list test unwrapped `item.value`, found the Slate
+ * document — an object — and classed a list of addresses as a list of hashes, so
+ * the row drew an expandable `type / children / text` tree instead of the
+ * address (supah, 2026-08-29).
+ *
+ * A rich-text envelope is a string in a coat. The row reads it as one.
+ */
+const RichtextListSchema: IOptionsSchema = {
+  to: {
+    type: 'list',
+    element_type: 'string',
+    supports_templates: true,
+    display_name: 'To',
+    required: true,
+  } as never,
+};
+
+const RichtextListValue: IOptions = {
+  to: {
+    type: 'list',
+    value: [
+      { type: 'richtext', value: [{ type: 'paragraph', children: [{ text: 'ops@example.com' }] }] },
+      { type: 'richtext', value: [{ type: 'paragraph', children: [{ text: 'sre@example.com' }] }] },
+    ],
+  },
+} as unknown as IOptions;
+
+export const CompactReadFirstRichtextStringList: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'A list of template-capable string elements reads as its strings, not as a structured-data tree: the rich-text envelope each element arrives in is a string in a coat.',
+      },
+    },
+  },
+  args: {
+    compact: true,
+    minColumnWidth: '300px',
+    options: RichtextListSchema,
+    value: RichtextListValue,
+  },
+  play: async ({ canvasElement }) => {
+    // The row itself, not a global text search: the addresses have to be IN the
+    // `to` row, which is the whole point.
+    await waitFor(
+      () => {
+        const row = canvasElement.querySelector('[data-field="to"]');
+        expect(row).toBeTruthy();
+        // The addresses themselves, not a bare "2 items" count.
+        expect(row?.textContent ?? '').toContain('ops@example.com');
+      },
+      { timeout: 10000 }
+    );
+
+    const text = canvasElement.querySelector('[data-field="to"]')?.textContent ?? '';
+    await expect(text).toContain('sre@example.com');
+
+    // ...and none of the document's internals leak into the row. These are the
+    // labels the structured-data tree prints, and they are what the operator saw.
+    await expect(text).not.toContain('paragraph');
+    await expect(text).not.toContain('children');
+  },
+};
+
 /**
  * The other half of the markdown contract: with NO host renderer there is no
  * inset at all. The row is not left empty though — its one line still carries
@@ -6388,3 +6719,655 @@ export const CompactListOfHashReadsInSchemaWordsMobile: Story = {
     }
   },
 };
+
+/**
+ * The read-first summary of an EXPRESSION: it renders to one line of text, and
+ * a template reference inside it used to print as its own raw token — the same
+ * reference the editor shows as a named chip. This is the Save Reply row of the
+ * Discord assistant template, whose value is
+ * `trim($data:{dc_ai_reply.choices[0].message.content})`.
+ */
+export const CompactExpressionTemplateChips: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders a compact read-first row whose value is an expression wrapping a template reference — the reference renders as a named chip inside the summary text (trim("Choices[0].message.content")) rather than as its raw $data token.',
+      },
+    },
+    chromatic: { disable: true },
+  },
+  render: () => (
+    <FormEngine
+      compact
+      name='exprChips'
+      stringTemplates={
+        {
+          items: [
+            {
+              label: 'Generate AI Reply',
+              items: [
+                {
+                  label: 'Choices',
+                  value: '$data:{3.choices}',
+                  metadata: { aliasValues: ['$data:{dc_ai_reply.choices}'] },
+                },
+              ],
+            },
+          ],
+        } as any
+      }
+      options={
+        {
+          reply: {
+            type: 'string',
+            display_name: 'Value',
+            desc: 'The new value for the variable',
+            supports_expressions: true,
+            required: true,
+          },
+        } as unknown as IQorusFormSchema
+      }
+      value={
+        {
+          reply: {
+            type: 'string',
+            is_expression: true,
+            value: {
+              exp: 'trim',
+              args: [{ type: 'string', value: '$data:{dc_ai_reply.choices[0].message.content}' }],
+            },
+          },
+        } as any
+      }
+      onChange={fn()}
+    />
+  ),
+  play: async () => {
+    // The summary keeps its literal text…
+    await _testsWaitForText('trim("', undefined, 1);
+    // …and the reference inside it is a named chip, not the raw token.
+    await waitFor(() => {
+      const chip = Array.from(document.querySelectorAll('.reqore-tag')).find((tag) =>
+        tag.textContent?.includes('Choices[0].message.content')
+      );
+      expect(chip, 'the reference renders as a named chip in the summary').toBeTruthy();
+    });
+    const raw = Array.from(document.querySelectorAll('.readfirst-row')).filter((row) =>
+      row.textContent?.includes('$data:{')
+    );
+    expect(raw, 'the row prints no raw token').toHaveLength(0);
+  },
+};
+
+/**
+ * The same row on a surface with NO template catalogue — the Automation Hub
+ * template preview, which never fetches one. There is no name to resolve the
+ * reference to, so the chip carries the reference's own path: the wrapper still
+ * reads as `trim("…")` text, and the reference stops reading as code.
+ */
+export const CompactExpressionWithoutCatalogue: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders a compact read-first row whose value is an expression wrapping a template reference, with no templates supplied — the reference still renders as a chip carrying its own path (dc_ai_reply.choices[0].message.content) rather than the raw $data token.',
+      },
+    },
+    chromatic: { disable: true },
+  },
+  render: () => (
+    <FormEngine
+      compact
+      name='exprNoCatalogue'
+      options={
+        {
+          reply: {
+            type: 'string',
+            display_name: 'Value',
+            desc: 'The new value for the variable',
+            supports_expressions: true,
+            required: true,
+          },
+        } as unknown as IQorusFormSchema
+      }
+      value={
+        {
+          reply: {
+            type: 'string',
+            is_expression: true,
+            value: {
+              exp: 'trim',
+              args: [{ type: 'string', value: '$data:{dc_ai_reply.choices[0].message.content}' }],
+            },
+          },
+        } as any
+      }
+      onChange={fn()}
+    />
+  ),
+  play: async () => {
+    await _testsWaitForText('trim("', undefined, 1);
+    await waitFor(() => {
+      const chip = Array.from(document.querySelectorAll('.reqore-tag')).find((tag) =>
+        tag.textContent?.includes('dc_ai_reply.choices[0].message.content')
+      );
+      expect(chip, 'the reference chips even with no catalogue').toBeTruthy();
+    });
+    const raw = Array.from(document.querySelectorAll('.readfirst-row')).filter((row) =>
+      row.textContent?.includes('$data:{')
+    );
+    expect(raw, 'the row prints no raw token').toHaveLength(0);
+  },
+};
+
+// --- PR #99: compactCollapsedGroups + compactToolbar --------------------------
+
+/** Find a status box (`Needs attention` / `Set` / `Optional`) by its title.
+ *  A collapsed ReqorePanel unmounts its content, so "has no
+ *  `.reqore-panel-content`" IS the collapsed assertion. */
+const findStatusBox = (title: string) =>
+  Array.from(document.querySelectorAll('.options-readfirst-group')).find((panel) =>
+    panel.querySelector('.reqore-panel-title')?.textContent?.includes(title)
+  );
+
+const expectBoxCollapsed = async (title: string) => {
+  await waitFor(
+    () => {
+      const box = findStatusBox(title);
+      expect(box, `the "${title}" box renders`).toBeTruthy();
+      expect(
+        box!.querySelector('.reqore-panel-content'),
+        `the "${title}" box is collapsed (content unmounted)`
+      ).toBeFalsy();
+    },
+    { timeout: 10000 }
+  );
+};
+
+const expectBoxOpen = async (title: string) => {
+  await waitFor(
+    () => {
+      const box = findStatusBox(title);
+      expect(box, `the "${title}" box renders`).toBeTruthy();
+      expect(
+        box!.querySelector('.reqore-panel-content'),
+        `the "${title}" box is open (content mounted)`
+      ).toBeTruthy();
+    },
+    { timeout: 10000 }
+  );
+};
+
+/**
+ * The template drawer's combination: a form that is one item in a longer list,
+ * where the reader chooses WHICH form to open rather than reading this one.
+ */
+export const CompactChosenCollapsedBoxes: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders a compact form with `compactCollapsedGroups={[\'set\', \'optional\']}` — the Set and Optional boxes start collapsed while Needs attention stays open, and typing a search query forces every box open (a collapsed panel unmounts its content, so a match inside one would be unreachable); clearing the query collapses them again.',
+      },
+    },
+  },
+  args: {
+    compact: true,
+    minColumnWidth: '300px',
+    options: CompactFieldsMenuSchema,
+    value: CompactValue,
+    groups: CompactGroups,
+    compactCollapsedGroups: ['set', 'optional'],
+  },
+  play: async () => {
+    // Needs attention is not in the collapse list — its row is on screen.
+    await expectBoxOpen('Needs attention');
+    await _testsWaitForText('Description');
+
+    // Set and Optional start collapsed: headers present, rows unmounted.
+    await expectBoxCollapsed('Set');
+    await expectBoxCollapsed('Optional');
+    await _testsWaitForTextToNotExist('order-fulfilment');
+
+    // A search overrides the collapse list — the matching Set row surfaces…
+    await _testsChangeStringField({
+      selector: 'input[placeholder="Filter fields..."]',
+      value: 'name',
+    });
+    await expectBoxOpen('Set');
+    await _testsWaitForText('order-fulfilment');
+
+    // …and clearing the query hands control back to the collapse list.
+    await _testsChangeStringField({
+      selector: 'input[placeholder="Filter fields..."]',
+      value: '',
+    });
+    await expectBoxCollapsed('Set');
+    await _testsWaitForTextToNotExist('order-fulfilment');
+  },
+};
+
+export const CompactToolbarHidden: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Renders a compact form with `compactToolbar={false}` — the completion meter, search, field picker and help button are all gone, and the header carries only the consumer's own `compactPanelProps.actions`; the rows themselves are untouched.",
+      },
+    },
+  },
+  args: {
+    ...Compact.args,
+    compactToolbar: false,
+    compactPanelProps: {
+      label: 'Save Reply',
+      actions: [{ label: 'Apply', icon: 'CheckLine', responsive: false }],
+    },
+  },
+  play: async () => {
+    // The rows and the consumer's own header action render…
+    await _testsWaitForText('order-fulfilment');
+    await _testsWaitForText('Apply');
+
+    // …and none of the engine's toolbar does.
+    await waitFor(() => {
+      expect(document.querySelector('.options-readfirst-completion')).toBeFalsy();
+      expect(document.querySelector('input[placeholder="Filter fields..."]')).toBeFalsy();
+      expect(document.querySelector('.options-readfirst-fields')).toBeFalsy();
+      expect(document.querySelector('.options-readfirst-descriptions')).toBeFalsy();
+    });
+  },
+};
+
+export const CompactToolbarTrimmed: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders a compact form with `compactToolbar={{ completion: false, help: false }}` — the keys listed turn their parts off (no meter, no help button) while the unlisted ones keep their defaults (search and the field picker still render), proving the object form merges over all-on rather than replacing it.',
+      },
+    },
+  },
+  args: {
+    ...Compact.args,
+    options: CompactFieldsMenuSchema,
+    compactToolbar: { completion: false, help: false },
+  },
+  play: async () => {
+    await _testsWaitForText('order-fulfilment');
+
+    // Listed parts are off…
+    await waitFor(() => {
+      expect(document.querySelector('.options-readfirst-completion')).toBeFalsy();
+      expect(document.querySelector('.options-readfirst-descriptions')).toBeFalsy();
+    });
+
+    // …unlisted parts keep rendering.
+    await waitFor(() => {
+      expect(document.querySelector('input[placeholder="Filter fields..."]')).toBeTruthy();
+      expect(document.querySelector('.options-readfirst-fields')).toBeTruthy();
+    });
+  },
+};
+
+export const CompactCollapseListLeavesLoneOptionalOpen: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Renders an all-optional compact form with an explicit `compactCollapsedGroups={['optional']}` — the Optional box stays open anyway, because it is the whole form and collapsing it would render a titled card containing one collapsed strip and nothing else. The invariant outranks the consumer's collapse list.",
+      },
+    },
+  },
+  args: {
+    compact: true,
+    minColumnWidth: '300px',
+    options: {
+      alpha: { type: 'string', ui_type: 'string', display_name: 'Alpha' },
+      beta: { type: 'string', ui_type: 'string', display_name: 'Beta' },
+    } as unknown as IOptionsSchema,
+    value: {} as IOptions,
+    compactCollapsedGroups: ['optional'],
+  },
+  play: async () => {
+    // The lone Optional box is open — its rows are on screen with no click.
+    await expectBoxOpen('Optional');
+    await _testsWaitForText('Alpha');
+    await _testsWaitForText('Beta');
+  },
+};
+
+export const CompactNoSearchCollapseIsFinal: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Renders a compact form with `compactToolbar={{ search: false }}` and `compactCollapsedGroups={['set']}` — with the search gone there is no query to force a box open, so the collapse list fully determines what is open: Set stays collapsed, and Optional (not listed — the list replaces the default rather than adding to it) renders open.",
+      },
+    },
+  },
+  args: {
+    compact: true,
+    minColumnWidth: '300px',
+    options: CompactFieldsMenuSchema,
+    value: CompactValue,
+    groups: CompactGroups,
+    compactCollapsedGroups: ['set'],
+    compactToolbar: { search: false },
+  },
+  play: async () => {
+    await _testsWaitForText('Description');
+
+    // No search input — nothing can override the collapse list.
+    await waitFor(() =>
+      expect(document.querySelector('input[placeholder="Filter fields..."]')).toBeFalsy()
+    );
+
+    // Set is collapsed for good; Optional is NOT in the list, so it is open —
+    // the list replaces the `['optional']` default rather than extending it.
+    await expectBoxCollapsed('Set');
+    await expectBoxOpen('Optional');
+    await _testsWaitForTextToNotExist('order-fulfilment');
+  },
+};
+
+/**
+ * A field that opens as a CARD can be cancelled.
+ *
+ * Which shape an open field takes is decided by its type: `COMPACT_COMPLEX_TYPES`
+ * includes `any`, so an `any`-typed option — a test assertion's Expected Value, a
+ * Qog action state option — never edits inline and always opens the card below.
+ *
+ * The card's action strip had no Cancel and no Revert, and the Escape handler
+ * lives on the inline row's editor, so a card ignored it. Every way out of a
+ * card therefore COMMITTED: Done, clicking away, and Escape. There was no way to
+ * abandon an edit and get the original value back.
+ */
+export const CompactCardCancelDiscardsTheEdit: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Opens an `any`-typed option (which always opens as a card), edits it, then cancels — the original value comes back. Cancel appears only once there is something to discard.',
+      },
+    },
+  },
+  args: {
+    compact: true,
+    minColumnWidth: '300px',
+    options: {
+      expected_value: {
+        type: 'any',
+        display_name: 'Expected Value',
+        short_desc: 'What the checked value should be',
+      },
+    } as never,
+    value: {
+      expected_value: { type: 'string', value: 'original' },
+    } as never,
+  },
+  play: async ({ canvasElement }) => {
+    await _testsClickText('Expected Value');
+    // the card, not the inline row - this is the shape the bug lived in
+    await waitFor(() =>
+      expect(canvasElement.querySelector('.options-readfirst-card')).toBeTruthy()
+    );
+
+    // Nothing typed yet: Cancel would do exactly what Done does, so it is not
+    // offered. Two buttons differing in name but not in effect are worse than one.
+    expect(canvasElement.querySelector('.options-readfirst-cancel')).toBeNull();
+
+    await _testsChangeStringField({
+      selector: '.options-readfirst-card .reqore-textarea',
+      value: 'edited',
+    });
+    await waitFor(() =>
+      expect(canvasElement.querySelector('.options-readfirst-cancel')).toBeTruthy()
+    );
+
+    await _testsClickButton({ selector: '.options-readfirst-cancel' });
+    await _testsWaitForText('original');
+    await _testsWaitForTextToNotExist('edited');
+  },
+};
+
+/**
+ * Escape discards from a card, exactly as it does from the inline row.
+ *
+ * Escape is the one keystroke every editor treats as "get me out of this without
+ * saving". The card ignored it entirely, which made the keystroke a silent
+ * commit — the quietest possible way to keep something the author was trying to
+ * throw away.
+ */
+export const CompactCardEscapeDiscardsTheEdit: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Edits an `any`-typed option in its card and presses Escape — the edit is discarded rather than kept, matching the inline row.',
+      },
+    },
+  },
+  args: {
+    compact: true,
+    minColumnWidth: '300px',
+    options: {
+      expected_value: {
+        type: 'any',
+        display_name: 'Expected Value',
+        short_desc: 'What the checked value should be',
+      },
+    } as never,
+    value: {
+      expected_value: { type: 'string', value: 'original' },
+    } as never,
+  },
+  play: async ({ canvasElement }) => {
+    await _testsClickText('Expected Value');
+    await waitFor(() =>
+      expect(canvasElement.querySelector('.options-readfirst-card')).toBeTruthy()
+    );
+
+    await _testsChangeStringField({
+      selector: '.options-readfirst-card .reqore-textarea',
+      value: 'edited',
+    });
+    await _testsWaitForText('edited');
+
+    // Fired on the editor itself, which is where the key actually lands: the
+    // handler sits on a wrapper around the editor, and events bubble UP.
+    const editor = canvasElement.querySelector(
+      '.options-readfirst-card .reqore-textarea'
+    ) as HTMLElement;
+    fireEvent.keyDown(editor, { key: 'Escape' });
+
+    await _testsWaitForText('original');
+    await _testsWaitForTextToNotExist('edited');
+  },
+};
+
+/**
+ * An unset field shows the default the server will use, not an em-dash.
+ *
+ * A field with no value of its own but a declared `default_value` is not
+ * unanswered — the default is what the server will apply if the field is left
+ * alone. The row used to say the opposite, rendering the same em-dash as a
+ * field with no default at all, so the only place a default surfaced was a
+ * `Default: …` line behind the info toggle, and only when the schema also
+ * supplied `default_value_desc`.
+ *
+ * Both halves have to hold together, which is why they share one frame here:
+ * the default is VISIBLE, and the field is still NOT SET. Author keeps the
+ * dimmed italic treatment of an unanswered row and stays in the Optional box —
+ * if it ever moved to Set, the change would have achieved nothing.
+ *
+ * The motivating case is Qorus's `author` field, which every create form
+ * carries. It was served the current username as its VALUE, so Author occupied
+ * a row in the Set box of every create form to say only what the server was
+ * going to do anyway. Serving it as a default fixes the bucketing; without this
+ * change it would have made the information disappear instead.
+ */
+export const CompactUnsetFieldShowsItsDefault: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders a compact form holding the three value treatments side by side: Author and Mode are unset but declare a default, so each row shows the default it will contribute; Notes has no default and keeps the em-dash; Name carries a real value. The defaulted rows stay dimmed and stay in the Optional box — showing a default does not make a field count as answered.',
+      },
+    },
+  },
+  args: {
+    compact: true,
+    minColumnWidth: '300px',
+    // This story is about what a rendered row SAYS, so every box is open.
+    // `compactCollapsedGroups` is a default parameter, so passing a value
+    // REPLACES the ['optional'] default rather than adding to it.
+    compactCollapsedGroups: [],
+    options: {
+      name: { type: 'string', display_name: 'Name', required: true },
+      // the shape the server sends: `default_value` UI-wrapped as {type, value}
+      author: {
+        type: 'string',
+        display_name: 'Author',
+        short_desc: 'Who the object will be attributed to',
+        default_value: { type: 'string', value: 'dnichols' },
+      },
+      // a bare default, with no envelope, is equally valid
+      mode: {
+        type: 'string',
+        display_name: 'Mode',
+        short_desc: 'How the run treats side effects',
+        default_value: 'simulate',
+      },
+      // no default at all — the em-dash is the honest answer for this one
+      notes: { type: 'string', display_name: 'Notes' },
+    } as never,
+    value: {
+      name: { type: 'string', value: 'my-test' },
+    } as never,
+  },
+  play: async ({ canvasElement }) => {
+    const rowText = (field: string) =>
+      canvasElement
+        .querySelector(`[data-field="${field}"] .options-readfirst-valuetext`)
+        ?.textContent?.trim();
+
+    await waitFor(() => expect(canvasElement.querySelector('[data-field="author"]')).toBeTruthy());
+
+    // The default is what the row shows, through the same formatter a real
+    // value goes through
+    await waitFor(() => expect(rowText('author')).toBe('dnichols'));
+    expect(rowText('mode')).toBe('simulate');
+
+    // …and a field with nothing to fall back on still says so
+    expect(rowText('notes')).toBe('—');
+
+    // The other half of the fix: visible, but still NOT answered. Author must
+    // stay in Optional — landing in Set is the regression this guards.
+    const authorBox = canvasElement
+      .querySelector('[data-field="author"]')
+      ?.closest('.options-readfirst-group');
+    expect(authorBox?.textContent).toContain('Optional');
+  },
+};
+
+/**
+ * A capped box folds its remainder behind a row, not a scrap of text.
+ *
+ * `maxFieldsShown` caps how many rows any status box shows — Needs attention,
+ * Set and Optional alike — so a long form stays scannable instead of making the
+ * reader page past one box to reach the next.
+ *
+ * The control that reveals the rest IS a field row: same grid, same padding,
+ * same hover, so it lines up with the rows above rather than floating in the
+ * box's corner. A dashed edge and a chevron are what say it is not itself a
+ * field — nothing on it can be set.
+ */
+export const CompactMaxFieldsShown: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders a compact form with `maxFieldsShown: 3`, so each status box shows three rows and folds the rest behind a dashed "N more fields" row. Clicking that row reveals the remainder and the label becomes "Show fewer".',
+      },
+    },
+  },
+  args: {
+    compact: true,
+    minColumnWidth: '300px',
+    compactCollapsedGroups: [],
+    maxFieldsShown: 3,
+    options: {
+      alpha: { type: 'string', display_name: 'Alpha' },
+      bravo: { type: 'string', display_name: 'Bravo' },
+      charlie: { type: 'string', display_name: 'Charlie' },
+      delta: { type: 'string', display_name: 'Delta' },
+      echo: { type: 'string', display_name: 'Echo' },
+      foxtrot: { type: 'string', display_name: 'Foxtrot' },
+    } as never,
+    value: {} as never,
+  },
+  play: async ({ canvasElement }) => {
+    // Three shown, three folded — the control counts what is not on screen
+    await _testsWaitForText('3 more optional fields');
+    await _testsWaitForText('Alpha');
+    await _testsWaitForTextToNotExist('Foxtrot');
+
+    // It is a ROW, not a bare line of text: it carries the row class, so it
+    // inherits the grid and padding the fields above it use
+    const more = canvasElement.querySelector('.readfirst-more-row') as HTMLElement;
+    expect(more).toBeTruthy();
+    expect(more.classList.contains('readfirst-row')).toBe(true);
+    expect(more.getAttribute('aria-expanded')).toBe('false');
+
+    // The dashed edge is the thing that says "not a field". Asserting the
+    // COMPUTED style, because the first cut of this took its colour from the
+    // inter-row divider tint (~8% of the text colour) and rendered an invisible
+    // border — the rule was there, the affordance was not.
+    const edge = getComputedStyle(more);
+    expect(edge.borderStyle).toBe('dashed');
+    expect(edge.borderTopWidth).toBe('1px');
+    // …and it inherits the rows' geometry rather than inventing its own
+    expect(edge.paddingLeft).toBe(getComputedStyle(
+      canvasElement.querySelector('.readfirst-row:not(.readfirst-more-row)') as HTMLElement
+    ).paddingLeft);
+
+    fireEvent.click(more);
+
+    await _testsWaitForText('Foxtrot');
+    await _testsWaitForText('Show fewer');
+    expect(
+      (canvasElement.querySelector('.readfirst-more-row') as HTMLElement).getAttribute(
+        'aria-expanded'
+      )
+    ).toBe('true');
+  },
+};
+
+/**
+ * An uncapped form is unchanged.
+ *
+ * `maxFieldsShown` is opt-in: without it every box shows every row it holds and
+ * no control renders at all. The story exists so that stays true — a default
+ * that quietly started folding rows would hide fields from every consumer that
+ * never asked for it.
+ */
+export const CompactNoMaxFieldsShown: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the same form with no `maxFieldsShown` — every row shows and no "more fields" control appears.',
+      },
+    },
+  },
+  args: {
+    ...CompactMaxFieldsShown.args,
+    maxFieldsShown: undefined,
+  },
+  play: async ({ canvasElement }) => {
+    await _testsWaitForText('Foxtrot');
+    expect(canvasElement.querySelector('.readfirst-more-row')).toBeNull();
+  },
+};