@qoretechnologies/reqraft 0.10.10 → 0.10.12

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

@@ -123,6 +123,14 @@ export const SchemaFromUrl: Story = {
     name: 'remoteBasic',
     url: 'sb-remote/basic',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders FormEngine with a url — the options schema is fetched from options/{url}, three fields mount with the preselected localhost default seeded and onOptionsLoaded fires with the fetched schema.',
+      },
+    },
+  },
   async beforeEach() {
     return mockFetchRoutes({ 'options/sb-remote/basic': { body: BASIC_SCHEMA } });
   },
@@ -153,6 +161,14 @@ export const OperatorsFromUrl: Story = {
       hostname: { type: 'string', value: 'qore', op: ['like'] },
     } as any,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders FormEngine with both url and operatorsUrl — the operator select resolves the "like" op against the fetched operator schema and the WHERE/IS summary tags appear alongside the option.',
+      },
+    },
+  },
   async beforeEach() {
     return mockFetchRoutes({
       'options/sb-remote/search': { body: SEARCH_SCHEMA },
@@ -181,6 +197,14 @@ export const FetchFailure: Story = {
     name: 'remoteFail',
     url: 'sb-remote/fail',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders FormEngine when the schema fetch returns 500 — the skeleton resolves into the "No options available" empty state instead of crashing.',
+      },
+    },
+  },
   async beforeEach() {
     return mockFetchRoutes({
       'options/sb-remote/fail': { status: 500, body: { err: 'boom' } },
@@ -202,6 +226,14 @@ export const UrlChangeResetsValue: Story = {
     name: 'remoteSwitch',
     url: 'sb-remote/first',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders FormEngine wired to url="first". Clicking the switch button re-points the engine to a different schema — the previous value (localhost) is dropped and the new Token field mounts.',
+      },
+    },
+  },
   render(args) {
     const [url, setUrl] = useState(args.url);
     return (
@@ -256,6 +288,14 @@ export const InjectedOptionActions: Story = {
       },
     ],
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders FormEngine with an optionActions factory that injects a per-option AI-assist button. Hovering an option reveals the injected action next to it.',
+      },
+    },
+  },
   async play() {
     await waitFor(() => expect(optionCount()).toBe(3), { timeout: 10000 });
 
@@ -278,6 +318,14 @@ export const TemplatesFromContext: Story = {
     options: BASIC_SCHEMA as any,
     interfaceContext: 'sb-ctx',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders FormEngine with an interfaceContext — useTemplates hits system/getContextData so template values are available in the schema fields.',
+      },
+    },
+  },
   async beforeEach() {
     return mockFetchRoutes({
       'system/getContextData': {

package/src/components/form/engine/_structuredData/StructuredDataView.stories.tsx

@@ -57,6 +57,14 @@ export const WorkflowOrderData: Story = {
     // Expand deep enough that the parsed-YAML sub-tree is visible.
     defaultExpandDepth: 3,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders StructuredDataView over a workflow-order payload — UI-encoded envelopes unwrap to scalars, embedded YAML strings parse into sub-trees and Qorus timestamps format to YYYY-MM-DD HH:mm:ss.SSS in the viewer\'s zone.',
+      },
+    },
+  },
   play: async () => {
     await _testsWaitForText('ORD-1002');
     await _testsWaitForText('order-process');

package/src/components/form/engine/variants/FormEngineVariants.stories.tsx

@@ -59,6 +59,14 @@ type Story = StoryObj<typeof meta>;
 
 export const V1CalmTable: Story = {
   name: '1 · Calm Table',
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the "Calm Table" compact-form variant over the shared basic schema — one of four visual candidates for the read-first FormEngine view.',
+      },
+    },
+  },
   render: () => (
     <Frame>
       <VariantCalmTable options={options} values={values} />
@@ -68,6 +76,14 @@ export const V1CalmTable: Story = {
 
 export const V2Cards: Story = {
   name: '2 · Cards',
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the "Cards" compact-form variant over the shared basic schema — each field group is a card so the presentation reads as chunked panels.',
+      },
+    },
+  },
   render: () => (
     <Frame>
       <VariantCards options={options} values={values} />
@@ -77,6 +93,14 @@ export const V2Cards: Story = {
 
 export const V3Focus: Story = {
   name: '3 · Focus',
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the "Focus" compact-form variant over the richer focus-demo schema (named groups, required-group choices) so the variant is compared under full engine parity.',
+      },
+    },
+  },
   render: () => (
     <Frame>
       <VariantFocus options={focusOptions} values={focusValues} config={focusConfig} />
@@ -86,6 +110,14 @@ export const V3Focus: Story = {
 
 export const V4Minimal: Story = {
   name: '4 · Minimal',
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the "Minimal" compact-form variant over the shared basic schema — the sparest of the four candidates, only labels and values.',
+      },
+    },
+  },
   render: () => (
     <Frame>
       <VariantMinimal options={options} values={values} />
@@ -96,6 +128,14 @@ export const V4Minimal: Story = {
 /** All four stacked, labelled — for a quick scroll-through comparison. */
 export const CompareAll: Story = {
   name: '★ Compare all',
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders all four compact-form variants stacked in a single scroll — the Calm Table, Cards, Focus and Minimal layouts sit under labelled panels so they can be compared side by side.',
+      },
+    },
+  },
   render: () => {
     const items: [string, React.ReactNode][] = [
       ['1 · Calm Table', <VariantCalmTable key='v1' options={options} values={values} />],

package/src/components/form/expressions/ExpressionField.stories.tsx

@@ -50,6 +50,14 @@ export const Default: Story = {
   args: {
     value: SAMPLE,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders ExpressionField holding a "$local:name == John" expression — the Visual builder shows the Logical Equals operator with its two operands and the Visual/Text mode toggle.',
+      },
+    },
+  },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
 
@@ -73,6 +81,14 @@ export const Empty: Story = {
     value: { is_expression: true, value: { args: [] } },
     defaultMode: 'text',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders ExpressionField in Text mode with an empty expression AST — the "Parsed" preview shows the "(empty)" placeholder for an empty expression.',
+      },
+    },
+  },
   async beforeEach() {
     const stop = startDpqlMockLsp();
     return () => stop();
@@ -102,6 +118,14 @@ export const Empty: Story = {
  * builder, and the Visual/Text toggle is present.
  */
 export const ViaFormEngine: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders a FormEngine schema with a bool option that carries supports_expressions and a stored expression value — the engine routes through TemplateField and mounts the ExpressionField shell with the Visual builder and the Visual/Text toggle.',
+      },
+    },
+  },
   render: () => {
     const [value, setValue] = useState<any>({
       condition: { type: 'bool', value: SAMPLE.value, is_expression: true },
@@ -150,6 +174,14 @@ export const ViaFormEngine: Story = {
  * renders the same AST.
  */
 export const ViaFormEngineTextMode: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the FormEngine expression field, then switches to Text mode — the DPQL editor seeds from the stored AST via the mock LSP\'s dpql/serialize call and the "Parsed" preview mirrors it.',
+      },
+    },
+  },
   render: ViaFormEngine.render,
   async beforeEach() {
     const stop = startDpqlMockLsp();
@@ -200,6 +232,14 @@ export const ViaFormEngineTextMode: Story = {
  * the seeded direction is covered by `ViaFormEngineTextMode` above.)
  */
 export const ViaFormEngineTextTyping: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the FormEngine expression field with an empty AST in Text mode. Typing DPQL text triggers the mock LSP\'s dpql/parse and the parsed expression lands in the form value with is_expression set.',
+      },
+    },
+  },
   render: (args) => {
     const [value, setValue] = useState<any>({
       condition: { type: 'bool', value: { args: [] }, is_expression: true },
@@ -277,6 +317,14 @@ export const TextMode: Story = {
     value: { is_expression: true, value: { args: [] } },
     defaultMode: 'text',
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders ExpressionField in Text (DPQL) mode over a mock-socket LSP. Typing DPQL text triggers dpql/parse and the "Parsed" preview reflects the resulting AST.',
+      },
+    },
+  },
   async beforeEach() {
     const stop = startDpqlMockLsp();
     return () => stop();
@@ -309,6 +357,14 @@ export const TextMode: Story = {
  * Driven live for the toggle interaction.
  */
 export const ToggleInFormEngine: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders a FormEngine schema with a plain bool option (supports_expressions, no value). Clicking More then "Use Expression" flips the field to expression mode and the ExpressionField shell with the Visual builder mounts in place of the checkbox.',
+      },
+    },
+  },
   render: () => {
     const [value, setValue] = useState<any>({});
     return (
@@ -380,7 +436,15 @@ export const Live: Story = {
   // (network/auth), still snapshotted by Chromatic. Mirrors the DpqlEditor
   // live stories.
   tags: ['!test'],
-  parameters: { live: true },
+  parameters: {
+    live: true,
+    docs: {
+      description: {
+        story:
+          'Renders ExpressionField against a live Qorus instance — the picker fetches the real ~121-function catalogue rather than the mock, and the seeded "contains" expression exercises the schema-driven operators and operands.',
+      },
+    },
+  },
   args: {
     type: 'bool',
     value: {
@@ -423,7 +487,15 @@ export const Live: Story = {
  */
 export const LiveExplain: Story = {
   tags: ['!test'],
-  parameters: { live: true },
+  parameters: {
+    live: true,
+    docs: {
+      description: {
+        story:
+          'Renders ExpressionField in Text mode against a live Qorus instance — the "Parsed" preview uses the server-rendered form via dpql/renderExpression rather than the client-side approximation.',
+      },
+    },
+  },
   args: {
     value: {
       is_expression: true,

package/src/components/form/expressions/builder/ExpressionBuilder.stories.tsx

@@ -113,6 +113,14 @@ export const Default: Story = {
   args: {
     returnType: ['string', 'int'],
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the ExpressionBuilder with no value and a string-or-int return type — a single empty expression card is shown so the operator can pick an operation.',
+      },
+    },
+  },
   play: async () => {
     await waitFor(() => expect(expressionCount()).toBe(1), { timeout: 10000 });
   },
@@ -122,6 +130,14 @@ export const DefaultBoolean: Story = {
   args: {
     returnType: ['boolean'],
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the ExpressionBuilder with no value and a boolean return type — a single empty expression card is shown so the operator can pick a boolean-returning operation.',
+      },
+    },
+  },
   play: async () => {
     await waitFor(() => expect(expressionCount()).toBe(1), { timeout: 10000 });
   },
@@ -142,6 +158,14 @@ export const WithSimpleValue: Story = {
       },
     },
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the ExpressionBuilder holding a single "contains" expression with three arguments — the card shows the operation and each operand slot.',
+      },
+    },
+  },
   play: async () => {
     await waitFor(() => expect(expressionCount()).toBe(1), { timeout: 10000 });
   },
@@ -234,6 +258,14 @@ export const WithComplexValue: Story = {
       },
     },
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the ExpressionBuilder holding a nested &&/|| expression with six leaf expressions — the builder shows the full expression tree with the AND/OR group cards and their operand cards.',
+      },
+    },
+  },
   play: async () => {
     await waitFor(() => expect(expressionCount()).toBe(6), { timeout: 10000 });
   },
@@ -241,6 +273,15 @@ export const WithComplexValue: Story = {
 
 export const ShowsExplanation: Story = {
   ...WithComplexValue,
+  parameters: {
+    ...WithComplexValue.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders the nested expression tree and clicks Explain — the plain-language explanation of the whole expression is shown alongside the builder.',
+      },
+    },
+  },
   play: async (args) => {
     await WithComplexValue.play!(args);
     await clickButtonByLabel('Explain');
@@ -260,6 +301,15 @@ export const Readonly: Story = {
     ...WithComplexValue.args,
     readOnly: true,
   },
+  parameters: {
+    ...WithComplexValue.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders the nested expression tree with readOnly enabled — the tree is visible but the AND/OR add-group controls are hidden so the operator cannot mutate it.',
+      },
+    },
+  },
   play: async (args) => {
     await WithComplexValue.play!(args);
     expect(document.querySelector('.expression-and')).toBeNull();
@@ -268,6 +318,15 @@ export const Readonly: Story = {
 
 export const FocusedEditing: Story = {
   ...WithComplexValue,
+  parameters: {
+    ...WithComplexValue.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders the nested expression tree, hovers a card and clicks its fullscreen action — the focused-editing modal opens over that subtree.',
+      },
+    },
+  },
   play: async (args) => {
     await WithComplexValue.play!(args);
     await userEvent.hover(document.querySelectorAll('.expression')[0]);
@@ -288,6 +347,14 @@ export const WithArgWithAllowedValues: Story = {
   args: {
     returnType: ['bool'],
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders an empty ExpressionBuilder and selects "Matches Regular Expression" — the third operand ("Regex Options") carries element_allowed_values and renders the "Select one or more" picker.',
+      },
+    },
+  },
   play: async (args) => {
     await Default.play!(args);
 
@@ -311,6 +378,14 @@ export const WithIntType: Story = {
       },
     },
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the ExpressionBuilder with an int-typed >= expression comparing $local:input to 20 — the operands render as Number fields inside the expression card.',
+      },
+    },
+  },
   play: async () => {
     await waitFor(() => expect(expressionCount()).toBe(1), { timeout: 10000 });
   },
@@ -326,6 +401,15 @@ export const WithIntType: Story = {
  */
 export const ArgsChangeWhenOperatorChanges: Story = {
   ...WithSimpleValue,
+  parameters: {
+    ...WithSimpleValue.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders the seeded "String Contains" expression, then switches the operation to "Matches Regular Expression" — the string operands carry over and the new "Regex Options" allowed-values operand appears.',
+      },
+    },
+  },
   play: async () => {
     // Both string operands of the seeded `contains` render as textareas.
     await waitFor(
@@ -344,6 +428,14 @@ export const NewGroupsCanBeCreated: Story = {
     ...WithSimpleValue.args,
     returnType: ['bool'],
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the seeded "String Contains" expression, then clicks the AND and OR add-group actions — the tree grows from 1 to 3 expression cards as new grouping levels are added.',
+      },
+    },
+  },
   play: async () => {
     await waitFor(() => expect(expressionCount()).toBe(1), { timeout: 10000 });
 
@@ -357,6 +449,15 @@ export const NewGroupsCanBeCreated: Story = {
 
 export const GroupsCanBeDeleted: Story = {
   ...WithComplexValue,
+  parameters: {
+    ...WithComplexValue.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders the nested expression tree (6 cards) and removes one group — the tree shrinks to 5 cards after the delete.',
+      },
+    },
+  },
   play: async () => {
     await waitFor(() => expect(expressionCount()).toBe(6), { timeout: 10000 });
 
@@ -377,6 +478,14 @@ export const GroupsCanBeDeleted: Story = {
  * inline `AiAssistanceAction({ context: selectedExpression })` captured.
  */
 export const WithInjectedExtraActions: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the nested expression tree with an extraActions factory that injects an AI-assist button per card. Hovering an expression reveals the injected action alongside the built-in ones.',
+      },
+    },
+  },
   args: {
     ...WithComplexValue.args,
     extraActions: ({ selectedExpression }) => [
@@ -428,6 +537,14 @@ export const ExpressionWithIntReturnType: Story = {
       is_expression: true,
     },
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the ExpressionBuilder with a "+" (Addition) varargs expression holding four int operands — the three "rest" args each expose a remove-argument button.',
+      },
+    },
+  },
   play: async () => {
     await waitFor(() => expect(expressionCount()).toBe(1), { timeout: 10000 });
     // Three "rest" args → three remove-argument buttons.
@@ -438,6 +555,15 @@ export const ExpressionWithIntReturnType: Story = {
 /** Remove one variable argument — the remove-arg count drops from 3 to 2. */
 export const VariableArgumentsCanBeRemoved: Story = {
   ...ExpressionWithIntReturnType,
+  parameters: {
+    ...ExpressionWithIntReturnType.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders the "+" varargs expression and clicks one remove-argument button — one operand disappears and the remove-arg count drops from 3 to 2.',
+      },
+    },
+  },
   play: async (args) => {
     await ExpressionWithIntReturnType.play!(args);
 
@@ -450,6 +576,15 @@ export const VariableArgumentsCanBeRemoved: Story = {
 /** Remove one then add one back — the count returns to 3. */
 export const VariableArgumentsCanBeAdded: Story = {
   ...ExpressionWithIntReturnType,
+  parameters: {
+    ...ExpressionWithIntReturnType.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders the "+" varargs expression, removes one operand and then adds one back — the remove-arg count moves 3 → 2 → 3.',
+      },
+    },
+  },
   play: async (args) => {
     await ExpressionWithIntReturnType.play!(args);
 
@@ -487,6 +622,14 @@ export const ExpressionCanBeWrapped: Story = {
     returnType: ['string', 'int'],
     value: seededConvert,
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders a seeded "Convert to Boolean" expression, hovers the card and picks "Join List Elements" from the Wrap picker — the outer op mounts and the original expression becomes its first operand.',
+      },
+    },
+  },
   play: async () => {
     // Seeded base op + its operand render.
     await waitFor(() => expect(expressionCount()).toBe(1), { timeout: 10000 });
@@ -506,6 +649,15 @@ export const ExpressionCanBeWrapped: Story = {
 /** Wrap, then unwrap — back to a single expression card. */
 export const ExpressionCanBeUnwrapped: Story = {
   ...ExpressionCanBeWrapped,
+  parameters: {
+    ...ExpressionCanBeWrapped.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders the wrapped expression from ExpressionCanBeWrapped, then hovers and unwraps the outer op — the inner "Convert to Boolean" survives and the outer wrapper is removed.',
+      },
+    },
+  },
   play: async (args) => {
     await ExpressionCanBeWrapped.play!(args);
 
@@ -579,6 +731,14 @@ const SeededMismatchBase: Story = {
  * exact, so the builder flags it and the confirmation modal mounts.
  */
 export const FunctionArgsArePassedToNewFunctionAndNeedConfirmation: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders a valued "Format Date" expression and switches the operation to "Matches Regular Expression" — the carried date arg is accepted-but-not-exact for the new richtext operand and the mismatched-arguments confirmation modal mounts.',
+      },
+    },
+  },
   args: {
     returnType: 'string',
     value: {
@@ -616,6 +776,15 @@ export const FunctionArgsArePassedToNewFunctionAndNeedConfirmation: Story = {
 /** "Confirm selection" keeps the (still-selected) mismatched arg, transformed. */
 export const AcceptIncompatibleFunctionArgsSelection: Story = {
   ...SeededMismatchBase,
+  parameters: {
+    ...SeededMismatchBase.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders the seeded mismatch-flagged expression, then clicks "Confirm selection" on the mismatched-arguments modal — the (still-selected) argument is kept and transformed to the new expected type.',
+      },
+    },
+  },
   play: async (args) => {
     await SeededMismatchBase.play!(args);
 
@@ -636,6 +805,15 @@ export const AcceptIncompatibleFunctionArgsSelection: Story = {
 /** "Accept all" — every mismatched arg is transformed and kept. */
 export const AcceptAllIncompatibleFunctionArgs: Story = {
   ...SeededMismatchBase,
+  parameters: {
+    ...SeededMismatchBase.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders the seeded mismatch-flagged expression, then clicks "Accept all" on the mismatched-arguments modal — every flagged argument is transformed and kept.',
+      },
+    },
+  },
   play: async (args) => {
     await SeededMismatchBase.play!(args);
 
@@ -655,6 +833,15 @@ export const AcceptAllIncompatibleFunctionArgs: Story = {
 /** "Discard all" — every mismatched arg is cleared. */
 export const DiscardAllIncompatibleFunctionArgs: Story = {
   ...SeededMismatchBase,
+  parameters: {
+    ...SeededMismatchBase.parameters,
+    docs: {
+      description: {
+        story:
+          'Renders the seeded mismatch-flagged expression, then clicks "Discard all" on the mismatched-arguments modal — every flagged argument is cleared.',
+      },
+    },
+  },
   play: async (args) => {
     await SeededMismatchBase.play!(args);