@qoretechnologies/reqraft 0.10.41-pr.95.g294e5aa → 0.10.41

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: {
@@ -912,19 +933,182 @@ export const OptionInheritsRenderPropFromSiblingCompact: Story = {
 // cell couldn't provide on its own. Locks the compact preview so a future
 // CompactRow refactor can't silently reduce a Qorus source-code field to an
 // ellipsised one-liner again.
+// An open field used to have exactly one way out — the green Done check — so
+// every exit committed, Escape included. This locks the Cancel affordance in
+// place: it appears only once there is something to discard, and it puts the
+// value back to what the field was opened with.
+export const CompactRowCancelEdit: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders a compact row opened for editing with a changed value — the Cancel action appears beside Done, and clicking it puts the field back to the value it was opened with and closes it.',
+      },
+    },
+  },
+  args: {
+    compact: true,
+    minColumnWidth: '360px',
+    value: { cookie_name: { type: 'string', value: 'my-cookie' } },
+    options: {
+      cookie_name: {
+        type: 'string',
+        ui_type: 'string',
+        display_name: 'Cookie Name',
+        short_desc: 'Cookie name for cookie authentication',
+      },
+    },
+  },
+  play: async ({ canvasElement }) => {
+    // Open the field.
+    const row = canvasElement.querySelector<HTMLElement>('[data-field="cookie_name"]');
+    expect(row).toBeTruthy();
+    fireEvent.click(row!);
+    await waitFor(() =>
+      expect(canvasElement.querySelector('.readfirst-row-editing')).toBeTruthy()
+    );
+
+    // An untouched field offers no Cancel — it would do exactly what Done does.
+    expect(canvasElement.querySelector('.options-readfirst-cancel')).toBeNull();
+
+    const input = canvasElement.querySelector<HTMLInputElement>(
+      '[data-field="cookie_name"] input, [data-field="cookie_name"] textarea'
+    );
+    expect(input).toBeTruthy();
+    fireEvent.change(input!, { target: { value: 'changed-cookie' } });
+
+    // Cancel appears the moment the value differs from what was opened.
+    await waitFor(
+      () => expect(canvasElement.querySelector('.options-readfirst-cancel')).toBeTruthy(),
+      { timeout: 5000 }
+    );
+
+    fireEvent.click(canvasElement.querySelector<HTMLElement>('.options-readfirst-cancel')!);
+
+    // The row closes and the opened-with value is back.
+    await waitFor(() => expect(canvasElement.querySelector('.readfirst-row-editing')).toBeNull(), {
+      timeout: 5000,
+    });
+    await waitFor(
+      () =>
+        expect(
+          canvasElement.querySelector('[data-field="cookie_name"]')?.textContent ?? ''
+        ).toContain('my-cookie'),
+      { timeout: 5000 }
+    );
+  },
+};
+
+// Language and Source code are one decision — "what is this code, and in what
+// language" — and the form used to ask it as two unrelated rows one above the
+// other. `absorb_fields` lets the editor take the language into its own
+// container so the pair reads as the single element it is.
+export const CompactRowAbsorbsLanguage: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders a code-editor row that absorbs its Language sibling — the language control sits inside the Source Code container above the editor instead of on a row of its own, and the collapsed row summarises it as a chip beside the code size.',
+      },
+    },
+  },
+  args: {
+    compact: true,
+    minColumnWidth: '360px',
+    componentOverrides: { 'code-editor': CodeEditorStandinNoSyntax },
+    value: {
+      language: { type: 'string', value: 'qore' },
+      source: { type: 'string', value: '%new-style\nclass Example {\n}\n' },
+    },
+    options: {
+      language: {
+        type: 'string',
+        ui_type: 'string',
+        display_name: 'Language',
+        allowed_values: [
+          { display_name: 'Qore', value: { type: 'string', value: 'qore' } },
+          { display_name: 'Python', value: { type: 'string', value: 'python' } },
+        ],
+      },
+      source: {
+        type: 'string',
+        ui_type: 'code-editor',
+        display_name: 'Source Code',
+        inherit_props: { language: 'language' },
+        absorb_fields: ['language'],
+      },
+    },
+  },
+  play: async ({ canvasElement }) => {
+    // The absorbed field has no row of its own.
+    await waitFor(() => expect(canvasElement.querySelector('[data-field="source"]')).toBeTruthy());
+    expect(canvasElement.querySelector('[data-field="language"]')).toBeNull();
+
+    // Collapsed, the host still reports the absorbed value — otherwise the
+    // language would vanish from the form whenever the editor is closed.
+    const sourceRow = canvasElement.querySelector('[data-field="source"]');
+    expect(sourceRow?.textContent ?? '').toContain('qore');
+
+    // Opening the host renders the language control inside its container.
+    fireEvent.click(sourceRow as HTMLElement);
+    await waitFor(() =>
+      expect(canvasElement.querySelector('.readfirst-row-editing')).toBeTruthy()
+    );
+    await waitFor(() =>
+      expect(canvasElement.querySelector('.options-readfirst-absorbed')).toBeTruthy()
+    );
+    // It is still identifiable as its own field, not a property of the editor.
+    expect(canvasElement.querySelector('.options-readfirst-absorbed')?.textContent ?? '').toContain(
+      'Language'
+    );
+  },
+};
+
+export const CompactRowCancelEditAffordance: Story = {
+  ...CompactRowCancelEdit,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders a compact row open for editing with a changed value, stopping while it is open — Cancel edit sits beside the green Done check, which is what an open field used to offer on its own.',
+      },
+    },
+  },
+  play: async ({ canvasElement }) => {
+    const row = canvasElement.querySelector<HTMLElement>('[data-field="cookie_name"]');
+    expect(row).toBeTruthy();
+    fireEvent.click(row!);
+    await waitFor(() =>
+      expect(canvasElement.querySelector('.readfirst-row-editing')).toBeTruthy()
+    );
+
+    const input = canvasElement.querySelector<HTMLInputElement>(
+      '[data-field="cookie_name"] input, [data-field="cookie_name"] textarea'
+    );
+    fireEvent.change(input!, { target: { value: 'changed-cookie' } });
+
+    await waitFor(
+      () => expect(canvasElement.querySelector('.options-readfirst-cancel')).toBeTruthy(),
+      { timeout: 5000 }
+    );
+    // Both ways out are on screen together, which is the point of the story.
+    expect(canvasElement.querySelector('.options-readfirst-done')).toBeTruthy();
+  },
+};
+
 export const CompactRowCodeEditorPreview: Story = {
   parameters: {
     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: {
@@ -980,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: {
@@ -2868,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,
     });
@@ -3654,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(
@@ -4451,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
@@ -4481,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)
@@ -4643,7 +4970,12 @@ export const CompactFieldTypesEditing: Story = {
     await userEvent.click(within(confirmationModal!).getByRole('button', { name: 'Clear value' }));
     await waitFor(() => {
       expect(editRow('enabled').querySelector('.options-readfirst-clear')).not.toBeInTheDocument();
-      expect(editRow('enabled').querySelector('.options-readfirst-revert')).toBeInTheDocument();
+      // Clear swaps for the undo affordance. In an OPEN field that is
+      // "Cancel edit" — the field was opened holding its form-load value, so
+      // undoing this edit and reverting the field are the same thing and only
+      // one button is offered. The form-load revert reappears here only when
+      // the field was already modified before it was opened.
+      expect(editRow('enabled').querySelector('.options-readfirst-cancel')).toBeInTheDocument();
     });
   },
 };
@@ -5939,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
@@ -6220,3 +6719,355 @@ 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');
+  },
+};