@qoretechnologies/reqraft 0.10.16 → 0.10.18

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

@@ -11,6 +11,7 @@
 import { StoryObj } from '@storybook/react-vite';
 import { expect, fn, userEvent, waitFor, within } from 'storybook/test';
 import { useState } from 'react';
+import { _testsClickButton, sleep } from '../../../stories/Tests/utils';
 import { StoryMeta } from '../../../types';
 import { FormEngine } from './FormEngine';
 
@@ -307,6 +308,334 @@ export const InjectedOptionActions: Story = {
   },
 };
 
+/**
+ * The same injected actions seam must also work in compact/read-first mode. The
+ * IDE uses this path for option-based forms and relies on the action slot for
+ * small per-field Qonsole controls.
+ */
+export const InjectedCompactOptionActions: Story = {
+  args: {
+    name: 'compactOptionActionsSeam',
+    compact: true,
+    options: BASIC_SCHEMA as any,
+    optionActions: ({ name }) => [
+      {
+        icon: 'MagicLine',
+        className: 'option-compact-ai-assist',
+        tooltip: `AI assistance for ${name}`,
+        // The shape the IDE passes on the classic path — hover-gated here too.
+        show: 'hover',
+        size: 'tiny',
+        fixed: true,
+      },
+      {
+        icon: 'InformationLine',
+        className: 'option-compact-always',
+        tooltip: `Details for ${name}`,
+        size: 'tiny',
+        fixed: true,
+      },
+    ],
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders compact FormEngine rows with two injected per-option actions: one always visible, one declared `show: "hover"` that stays transparent until its row is hovered or focused. Hover-gating applies only where the pointer can hover — on touch both collapse into the row\'s overflow menu instead, so neither is ever hover-only.',
+      },
+    },
+  },
+  async play() {
+    await waitFor(
+      () => expect(document.querySelectorAll('.readfirst-row').length).toBeGreaterThan(0),
+      { timeout: 10000 }
+    );
+
+    const rowCount = document.querySelectorAll('.readfirst-row').length;
+
+    await waitFor(() => {
+      expect(document.querySelectorAll('.option-compact-always').length).toBe(rowCount);
+      expect(document.querySelectorAll('.option-compact-ai-assist').length).toBe(rowCount);
+    });
+
+    // The hover-only action carries the CSS gate; the always-on one does not.
+    const hoverAction = document.querySelector(
+      '.option-compact-ai-assist.options-injected-action-hover'
+    ) as HTMLElement;
+    expect(hoverAction).toBeTruthy();
+    expect(
+      document.querySelectorAll('.option-compact-always.options-injected-action-hover').length
+    ).toBe(0);
+
+    // Actually exercise the reveal condition rather than just asserting the
+    // class is present: gated the action is transparent and not hit-testable.
+    expect(getComputedStyle(hoverAction).opacity).toBe('0');
+    expect(getComputedStyle(hoverAction).pointerEvents).toBe('none');
+
+    // Focus is the reveal path a test can drive: the gate keys on
+    // `:hover, :focus-within`, and a synthetic mouse event does NOT put a real
+    // browser into `:hover`. Focusing the action is also the keyboard route a
+    // user takes, so this covers the accessibility path at the same time.
+    hoverAction.focus();
+    await waitFor(() => {
+      expect(getComputedStyle(hoverAction).opacity).toBe('1');
+      expect(getComputedStyle(hoverAction).pointerEvents).toBe('auto');
+    });
+
+    // Left revealed so the captured frame shows the action rather than an
+    // empty slot — the whole point of the story.
+    await sleep(200);
+  },
+};
+
+/**
+ * The no-hover case. A touch device never fires `:hover`, so a hover-gated
+ * action would be permanently unreachable; instead every injected action moves
+ * into the row's own overflow menu. `optionActionsCollapse='always'` forces the
+ * branch that `(hover: none)`/`(pointer: coarse)` picks on a real phone, which a
+ * desktop browser cannot emulate.
+ */
+export const InjectedCompactOptionActionsMobile: Story = {
+  args: {
+    name: 'compactOptionActionsMobile',
+    compact: true,
+    options: BASIC_SCHEMA as any,
+    optionActionsCollapse: 'always',
+    optionActions: ({ name }) => [
+      {
+        icon: 'MagicLine',
+        className: 'option-compact-ai-assist',
+        tooltip: `AI assistance for ${name}`,
+        show: 'hover',
+        size: 'tiny',
+        fixed: true,
+      },
+      {
+        icon: 'InformationLine',
+        className: 'option-compact-always',
+        tooltip: `Details for ${name}`,
+        size: 'tiny',
+        fixed: true,
+      },
+    ],
+  },
+  parameters: {
+    qlip: { viewport: { width: 420, height: 900 } },
+    docs: {
+      description: {
+        story:
+          'Renders the compact rows at phone width with injected actions collapsed into each row\'s overflow menu — the no-hover path, where a hover-gated button would otherwise be unreachable. The menu is opened so the actions are visible.',
+      },
+    },
+  },
+  async play() {
+    await waitFor(
+      () => expect(document.querySelectorAll('.readfirst-row').length).toBeGreaterThan(0),
+      { timeout: 10000 }
+    );
+
+    // Collapsed: no inline injected buttons at all, one overflow menu per row.
+    const rowCount = document.querySelectorAll('.readfirst-row').length;
+    await waitFor(() => {
+      expect(document.querySelectorAll('.options-injected-actions-menu').length).toBe(rowCount);
+    });
+    expect(document.querySelectorAll('.option-compact-ai-assist').length).toBe(0);
+    expect(document.querySelectorAll('.option-compact-always').length).toBe(0);
+
+    // Both actions are reachable from the menu — the reason the collapse exists.
+    await _testsClickButton({ selector: '.options-injected-actions-menu', nth: 0 });
+    await waitFor(
+      () => {
+        const labels = Array.from(document.querySelectorAll('.reqore-menu-item')).map(
+          (item) => item.textContent ?? ''
+        );
+        expect(labels.some((label) => label.includes('AI assistance for'))).toBe(true);
+        expect(labels.some((label) => label.includes('Details for'))).toBe(true);
+      },
+      { timeout: 10000 }
+    );
+  },
+};
+
+/**
+ * Many injected actions. Beyond the inline cap the extras overflow into the
+ * row's menu instead of squeezing the value out of the row, so a consumer can
+ * inject any number without breaking the layout.
+ */
+export const InjectedCompactOptionActionsMany: Story = {
+  args: {
+    name: 'compactOptionActionsMany',
+    compact: true,
+    options: BASIC_SCHEMA as any,
+    optionActions: ({ name }) =>
+      ['MagicLine', 'InformationLine', 'FileCopyLine', 'DeleteBinLine', 'ShareLine'].map(
+        (icon, index) => ({
+          icon: icon as any,
+          className: `option-compact-many-${index}`,
+          tooltip: `${icon} for ${name}`,
+          size: 'tiny',
+          fixed: true,
+        })
+      ),
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the compact rows with five injected actions per option — the first two stay inline and the remaining three collapse into the row\'s overflow menu, which is opened here to show them.',
+      },
+    },
+  },
+  async play() {
+    await waitFor(
+      () => expect(document.querySelectorAll('.readfirst-row').length).toBeGreaterThan(0),
+      { timeout: 10000 }
+    );
+
+    const rowCount = document.querySelectorAll('.readfirst-row').length;
+
+    // Only the first two render inline; the rest are in the menu.
+    await waitFor(() => {
+      expect(document.querySelectorAll('.option-compact-many-0').length).toBe(rowCount);
+      expect(document.querySelectorAll('.option-compact-many-1').length).toBe(rowCount);
+    });
+    expect(document.querySelectorAll('.option-compact-many-2').length).toBe(0);
+    expect(document.querySelectorAll('.option-compact-many-4').length).toBe(0);
+    expect(document.querySelectorAll('.options-injected-actions-menu').length).toBe(rowCount);
+
+    await _testsClickButton({ selector: '.options-injected-actions-menu', nth: 0 });
+    await waitFor(
+      () => {
+        const labels = Array.from(document.querySelectorAll('.reqore-menu-item')).map(
+          (item) => item.textContent ?? ''
+        );
+        expect(labels.some((label) => label.includes('DeleteBinLine for'))).toBe(true);
+        expect(labels.some((label) => label.includes('ShareLine for'))).toBe(true);
+      },
+      { timeout: 10000 }
+    );
+  },
+};
+
+// A compact row renders the SAME logical state three ways — the read row, the
+// inline editor, and the edit card (complex types get the card). An injected
+// action has to survive all three, and per the affordance-parity rule each
+// branch needs its own story: the branch without one is where a dead action
+// hides, because the branch under test is the branch that works.
+const BRANCH_SCHEMA = {
+  host: {
+    type: 'string',
+    display_name: 'Host',
+    short_desc: 'Edits inline inside the row',
+    preselected: true,
+    default_value: 'localhost',
+  },
+  notes: {
+    type: 'string',
+    ui_type: 'long-string',
+    display_name: 'Notes',
+    short_desc: 'A complex type — edits in the card branch',
+    preselected: true,
+    // Needs a value: an empty optional field sits in the collapsed "Optional"
+    // group, where `initialExpandedOptions` has nothing to open.
+    default_value: 'Notes that are long enough to want the card editor.',
+  },
+};
+
+const branchAction = ({ name }: { name: string }) => [
+  {
+    icon: 'MagicLine' as const,
+    className: 'option-branch-action',
+    tooltip: `AI assistance for ${name}`,
+    size: 'tiny' as const,
+    fixed: true,
+  },
+];
+
+/**
+ * Branch 1 of 3: the INLINE editor. A simple type opens inside the row itself,
+ * and the injected action has to be reachable there, not just on the read row.
+ */
+export const InjectedOptionActionsInlineEditing: Story = {
+  args: {
+    name: 'compactOptionActionsInline',
+    compact: true,
+    options: BRANCH_SCHEMA as any,
+    initialExpandedOptions: ['host'],
+    optionActions: branchAction,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the compact form with the simple `host` field already open, so it edits inline inside the row — the injected per-option action is asserted inside that inline branch.',
+      },
+    },
+  },
+  async play() {
+    await waitFor(
+      () => expect(document.querySelector('.readfirst-row-editing')).toBeTruthy(),
+      { timeout: 10000 }
+    );
+
+    // Scoped to the branch on purpose: a global query would pass on the read
+    // row's copy and prove nothing about the inline editor.
+    const injected = await waitFor(() => {
+      const el = document.querySelector(
+        '.readfirst-row-editing .option-branch-action'
+      ) as HTMLElement;
+      expect(el).toBeTruthy();
+      return el;
+    });
+
+    // The injected action must match the size of the row's own actions. The
+    // fixture deliberately asks for `size: 'tiny'` — the row overrides it,
+    // because a consumer-sized button rendered visibly smaller than the revert
+    // and More buttons beside it (qlip build #57 rejection).
+    const neighbour = document.querySelector(
+      '.readfirst-row-editing .options-readfirst-more'
+    ) as HTMLElement;
+    expect(neighbour).toBeTruthy();
+    expect(injected.getBoundingClientRect().height).toBe(
+      neighbour.getBoundingClientRect().height
+    );
+  },
+};
+
+/**
+ * Branch 2 of 3: the EDIT CARD. A complex type (`long-string`) is too tall to
+ * edit in-row, so it opens as a card — a different subtree, and historically
+ * where an action wired only in the other branch went missing.
+ */
+export const InjectedOptionActionsEditCard: Story = {
+  args: {
+    name: 'compactOptionActionsCard',
+    compact: true,
+    options: BRANCH_SCHEMA as any,
+    initialExpandedOptions: ['notes'],
+    optionActions: branchAction,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the compact form with the complex `notes` field already open, so it edits in the card branch rather than in-row — the injected per-option action is asserted inside that card.',
+      },
+    },
+  },
+  async play() {
+    await waitFor(() => expect(document.querySelector('.options-readfirst-card')).toBeTruthy(), {
+      timeout: 10000,
+    });
+
+    await waitFor(() => {
+      expect(
+        document.querySelector('.options-readfirst-card .option-branch-action')
+      ).toBeTruthy();
+    });
+  },
+};
+
 /**
  * Opt-in template fetching: `interfaceContext` makes `useTemplates` fetch
  * `system/getContextData` (the IDE's behavior); without it, no request is

package/src/components/form/engine/compactRowContext.ts

@@ -9,6 +9,7 @@ import {
 import { MutableRefObject } from 'react';
 import { createContext } from 'use-context-selector';
 import { IOperatorsSchema } from './FormEngine';
+import { TOptionActions } from './optionActions';
 
 /**
  * The complete closure surface of the (former) `renderCompactRow` function,
@@ -74,6 +75,13 @@ export interface ICompactRowContext {
 
   // Function passed through as a value (stays defined in FormEngine because the
   // classic non-compact path uses it too).
+  optionActions?: TOptionActions;
+  /**
+   * Injected actions render inside the row's overflow menu instead of as inline
+   * buttons. True on touch (where a hover-gated button is unreachable) and on
+   * narrow viewports. Resolved once by FormEngine so rows share one subscription.
+   */
+  collapseOptionActions?: boolean;
   renderOption: (
     optionName: string,
     field: IQorusFormField,

package/src/components/form/engine/compactRowStyles.ts

@@ -73,6 +73,36 @@ export const StyledCompactPanel = styled(ReqorePanel)<{
     flex: 1 1 auto;
     min-width: 0;
   }
+
+  /* An injected option action declared \`show: 'hover'\` — the shape ReqorePanel
+     honours on the classic path — is revealed only while its row or card is
+     hovered or holds focus. The compact slots render plain buttons, so the gate
+     has to be CSS here. Kept focus-visible too, so the action stays reachable by
+     keyboard. Opacity rather than display keeps the slot's width stable, so rows
+     don't reflow on hover. */
+  .options-injected-action-hover {
+    opacity: 0;
+    /* Not hit-testable while invisible — an opacity:0 button still takes taps
+       and clicks, which reads as a mystery control firing out of nowhere. */
+    pointer-events: none;
+    transition: opacity 0.15s ease;
+  }
+  .readfirst-row:hover .options-injected-action-hover,
+  .readfirst-row:focus-within .options-injected-action-hover,
+  .options-readfirst-card:hover .options-injected-action-hover,
+  .options-readfirst-card:focus-within .options-injected-action-hover {
+    opacity: 1;
+    pointer-events: auto;
+  }
+  /* Touch and other hover-less pointers never fire :hover, so a hover-gated
+     action would be permanently unreachable there. Show it unconditionally
+     instead — losing the tidiness beats losing the functionality. */
+  @media (hover: none), (pointer: coarse) {
+    .options-injected-action-hover {
+      opacity: 1;
+      pointer-events: auto;
+    }
+  }
 `;
 
 // Compact group header laid out as the panel's `label`: the group name, a

package/src/components/form/engine/optionActions.ts

@@ -0,0 +1,40 @@
+import { IReqorePanelAction } from '@qoretechnologies/reqore/dist/components/Panel';
+import { IQorusFormField, IQorusFormSchema } from '@qoretechnologies/ts-toolkit';
+
+/**
+ * The context an `optionActions` factory receives for a single option — the
+ * option's name, its schema entry, and its current field value. This is the
+ * IDE's `AiAssistanceAction` context (it injects its `allowAi` button here).
+ */
+export interface IOptionActionsContext {
+  name: string;
+  schema: IQorusFormSchema[string];
+  value?: IQorusFormField;
+}
+
+/**
+ * SEAM (reqraft): per-option injected actions. Either a static list applied to
+ * every option, or a factory invoked once per option with that option's context.
+ */
+export type TOptionActions =
+  | IReqorePanelAction[]
+  | ((context: IOptionActionsContext) => IReqorePanelAction[]);
+
+/**
+ * Resolve the `optionActions` seam for one option.
+ *
+ * Both render paths go through this so a consumer's factory is called with the
+ * same context and its result shaped the same way: the classic path feeds the
+ * result to `ReqorePanel`'s `actions`, the compact path renders the buttons
+ * itself. Falsy entries are dropped so a factory can return conditional actions
+ * inline (`cond && {...}`) without each caller re-filtering.
+ */
+export const resolveOptionActions = (
+  optionActions: TOptionActions | undefined,
+  context: IOptionActionsContext
+): IReqorePanelAction[] => {
+  const actions =
+    typeof optionActions === 'function' ? optionActions(context) : (optionActions ?? []);
+
+  return (actions ?? []).filter((action): action is IReqorePanelAction => !!action);
+};

package/src/components/form/engine/readFirst.ts

@@ -1,4 +1,9 @@
-import { IQorusFormField, TQorusFormFieldSchema } from '@qoretechnologies/ts-toolkit';
+import {
+  IQorusFormField,
+  TQorusFormFieldSchema,
+  TQorusType,
+} from '@qoretechnologies/ts-toolkit';
+import { isRendererOnlyUiType } from './rendererTypes';
 import { isUiEncodedValue } from './_structuredData/structuredData';
 import { renderExpressionToText } from '../expressions/renderExpressionToText';
 import { IExpressionValue } from '../expressions/types';
@@ -223,15 +228,29 @@ export const getFileSize = (value: unknown): number | undefined => {
   return typeof size === 'number' && Number.isFinite(size) && size >= 0 ? size : undefined;
 };
 
-/** Effective UI type for display: the stored `type` wins (any/auto picks),
- * then schema `ui_type`, then `type`. */
+/**
+ * Effective UI type for DISPLAY — which preview/summary a value renders as.
+ *
+ * A renderer-only `ui_type` wins outright: the field's stored `type` holds the
+ * STORAGE type for those (a `code-editor` stores a string), so consulting the
+ * stored type here would render the bespoke editor's value as a plain string and
+ * silently drop its preview. Every other case keeps the stored type first, so an
+ * `any`/`auto` field still displays as whatever concrete type the user picked.
+ */
 export const getValueType = (
   option?: IQorusFormField,
   schema?: TQorusFormFieldSchema
-): string | undefined =>
-  (option?.type ||
-    (schema as { ui_type?: string; type?: string } | undefined)?.ui_type ||
+): string | undefined => {
+  const uiType = (schema as { ui_type?: string } | undefined)?.ui_type;
+
+  if (isRendererOnlyUiType(uiType as TQorusType)) {
+    return uiType;
+  }
+
+  return (option?.type ||
+    uiType ||
     (schema as { type?: string } | undefined)?.type) as string | undefined;
+};
 
 /** Human-readable byte count (e.g. `1.2 KB`). */
 export const formatBytes = (bytes: number): string => {

package/src/components/form/engine/rendererTypes.ts

@@ -0,0 +1,55 @@
+import { TQorusType } from '@qoretechnologies/ts-toolkit';
+
+/**
+ * A schema entry carries two type-ish keys with different jobs:
+ *
+ * - `type` names how the value is STORED and validated (`string`, `hash`, `list`…).
+ * - `ui_type` names which EDITOR renders it.
+ *
+ * For most fields `ui_type` is a storage-compatible refinement (`long-string`,
+ * `enum`, `url`) and it is safe to let it win for both jobs. But some `ui_type`s
+ * name a bespoke editor whose value is still stored as the plainer `type` — a
+ * `cron` editor stores a string, `processor-mappings` stores a hash. Writing
+ * those renderer names into the field's `type` breaks validation and round-trips
+ * the value through the wrong branch, which is what `RENDERER_ONLY_UI_TYPES`
+ * exists to prevent.
+ *
+ * There is deliberately no derivation here: a renderer-only `ui_type` is not
+ * distinguishable from a storage-compatible one by inspecting the value or the
+ * `TQorusType` union (`code-editor` and `tool-catalog` are members of it, and
+ * the validator has cases for `cron` and `schema-definition`). It is a fact
+ * about which editor a name selects, so it has to be declared.
+ */
+export const BUILT_IN_RENDERER_ONLY_UI_TYPES: readonly string[] = [
+  'active-windows',
+  'alert-threshold',
+  'code-editor',
+  'cron',
+  'dpql',
+  'processor-mappings',
+  'schema-definition',
+  'test-cases',
+  'test-value-contract',
+  'tool-catalog',
+];
+
+/**
+ * Build the renderer-only predicate for one FormEngine instance.
+ *
+ * Consumers inject their own editors through `componentOverrides`, so the set of
+ * renderer-only names is open-ended — the IDE ships editors reqraft has never
+ * heard of. `extraTypes` (the `rendererOnlyUiTypes` prop) lets a consumer declare
+ * its own without waiting on a reqraft release, which is what previously made
+ * every new IDE editor a silent value-corruption bug until this list caught up.
+ */
+export const createRendererOnlyUiTypeCheck = (
+  extraTypes?: readonly string[]
+): ((type?: TQorusType | TQorusType[]) => boolean) => {
+  const known = new Set<string>([...BUILT_IN_RENDERER_ONLY_UI_TYPES, ...(extraTypes ?? [])]);
+
+  return (type?: TQorusType | TQorusType[]): boolean =>
+    typeof type === 'string' && known.has(type);
+};
+
+/** The default predicate — built-ins only, for module-scope callers with no props. */
+export const isRendererOnlyUiType = createRendererOnlyUiTypeCheck();

package/src/components/form/fields/auto/AutoFormField.tsx

@@ -356,7 +356,12 @@ function AutoField<T = any>({
         {...rest}
         name={name}
         value={value}
-        onChange={(val: any) => handleChange(name, val)}
+        onChange={(val: any, emittedType?: IQorusType, emittedIsFunction?: boolean) => {
+          const returnType = emittedType || currentType;
+          if (onChange && returnType) {
+            onChange(name, val, returnType, emittedIsFunction);
+          }
+        }}
       />
     );
   }

package/src/components/form/index.tsx

@@ -22,6 +22,8 @@ export * from './fields/select/SelectCollection';
 export * from './fields/string/String';
 export * from './fields/template/TemplateField';
 export * from './engine/FormEngine';
+export * from './engine/optionActions';
+export * from './engine/rendererTypes';
 export * from './expressions/types';
 export * from './expressions/useExpressions';
 // Named (not wildcard) so the `_resetRenderExpressionTransportForTests`