@qoretechnologies/reqraft 0.10.2 → 0.10.5

package/src/components/form/engine/variants/variantModel.ts

@@ -0,0 +1,216 @@
+/**
+ * Shared row model for the FormEngine compact VARIANTS playground.
+ *
+ * This is a prototyping harness: every variant renders the SAME normalized rows
+ * (derived from a real options schema + values via the real `readFirst`
+ * formatters) and differs only in layout / chrome / UX. That keeps the
+ * comparison about presentation, not data. Editing is intentionally stubbed
+ * (expand shows a placeholder) — the point is to compare the read-first view
+ * that currently feels crowded, then graft the winner onto the real engine.
+ */
+import { IQorusFormField, IQorusFormSchema } from '@qoretechnologies/ts-toolkit';
+import {
+  colorToCss,
+  formatBytes,
+  formatOptionValue,
+  getFileSize,
+  getOptionGroup,
+  getOptionGroupLabel,
+  getValueType,
+  isOptionValueEmpty,
+} from '../readFirst';
+import { isValueTemplate } from '../../../../helpers/templates';
+
+export type TVariantStatus =
+  | 'set' // has a valid value
+  | 'unset' // empty, not required — calm, no alarm
+  | 'todo' // required (or required-group) but unset — gentle amber
+  | 'invalid'; // user-entered value fails validation — red (only when surfaced)
+
+export type TVariantValueKind =
+  | 'text'
+  | 'number'
+  | 'bool'
+  | 'color'
+  | 'file'
+  | 'template'
+  | 'richtext'
+  | 'hash'
+  | 'empty';
+
+export interface IVariantValue {
+  kind: TVariantValueKind;
+  /** Human-readable summary (already formatted by readFirst). */
+  display: string;
+  /** color: css color; file: size label; hash: field count; template: label */
+  extra?: string;
+}
+
+export interface IVariantRow {
+  name: string;
+  label: string;
+  shortDesc?: string;
+  longDesc?: string;
+  required: boolean;
+  readOnly: boolean;
+  status: TVariantStatus;
+  /** Short reason for todo/invalid, e.g. "Text value is empty". */
+  reason?: string;
+  value: IVariantValue;
+  typeLabel: string;
+  /** required_groups this field belongs to (one-of constraints). */
+  requiredGroups: string[];
+  /** True when this field is a member of an unsatisfied one-of group. */
+  inUnmetGroup: boolean;
+  /** Raw schema + value object — passed to AutoFormField for REAL editing. */
+  schema: any;
+  field: any;
+}
+
+export interface IVariantGroup {
+  name: string;
+  label: string;
+  rows: IVariantRow[];
+}
+
+/** One-of required group: members + whether any is filled. */
+export interface IRequiredGroupInfo {
+  key: string;
+  members: string[];
+  memberLabels: string[];
+  satisfied: boolean;
+}
+
+export interface IVariantConfig {
+  groupLabels?: Record<string, string>;
+  /** name → reason; in the engine this comes from the validity pass. */
+  invalidReasons?: Record<string, string>;
+}
+
+// Default (basic-fixture) invalid set — overridable via config.
+const DEFAULT_INVALID: Record<string, string> = {
+  optionWithInvalidValue: 'Text value is empty',
+  schemaOption: 'Hash arguments are invalid',
+};
+
+function buildValue(field: IQorusFormField | undefined, schema: any): IVariantValue {
+  if (!field || isOptionValueEmpty(field.value)) return { kind: 'empty', display: '' };
+
+  const valueType = getValueType(field, schema);
+  const formatted = formatOptionValue(field, schema);
+
+  if (valueType === 'rgbcolor') {
+    return { kind: 'color', display: formatted, extra: colorToCss(field.value) };
+  }
+  if (valueType === 'file') {
+    const size = getFileSize(field.value);
+    return {
+      kind: 'file',
+      display: formatted,
+      extra: size !== undefined ? formatBytes(size) : undefined,
+    };
+  }
+  if (valueType === 'bool' || valueType === 'boolean') {
+    return { kind: 'bool', display: formatted };
+  }
+  if (valueType === 'hash' || valueType === 'free-hash') {
+    return { kind: 'hash', display: formatted };
+  }
+  if (typeof field.value === 'string' && isValueTemplate(field.value)) {
+    // The real chip resolves the template's display name from the templates
+    // list; the prototype shows a friendly label of the key.
+    const label =
+      field.value.replace(/^\$[a-z]+:/i, '').replace(/[-_]/g, ' ') || field.value;
+    return { kind: 'template', display: label.replace(/\b\w/g, (c) => c.toUpperCase()), extra: 'local' };
+  }
+  if (valueType === 'richtext' && Array.isArray(field.value)) {
+    return { kind: 'richtext', display: formatted };
+  }
+  return { kind: 'text', display: formatted };
+}
+
+export function buildVariantGroups(
+  options: IQorusFormSchema,
+  values: Record<string, IQorusFormField>,
+  config: IVariantConfig = {}
+): { groups: IVariantGroup[]; requiredGroups: Record<string, IRequiredGroupInfo> } {
+  const invalidReasons = config.invalidReasons ?? DEFAULT_INVALID;
+  const groupMap = new Map<string, IVariantGroup>();
+
+  // Pass 1: collect one-of required-group membership + satisfaction.
+  const reqGroups: Record<string, IRequiredGroupInfo> = {};
+  Object.entries(options).forEach(([name, schema]: [string, any]) => {
+    (schema?.required_groups || []).forEach((key: string) => {
+      if (!reqGroups[key]) reqGroups[key] = { key, members: [], memberLabels: [], satisfied: false };
+      reqGroups[key].members.push(name);
+      reqGroups[key].memberLabels.push((schema?.display_name as string) || name);
+      if (!isOptionValueEmpty(values[name]?.value)) reqGroups[key].satisfied = true;
+    });
+  });
+
+  Object.entries(options).forEach(([name, schema]: [string, any]) => {
+    const field = values[name];
+    const empty = isOptionValueEmpty(field?.value);
+    const ownGroups: string[] = schema?.required_groups || [];
+    // Member of a one-of group that nobody has satisfied yet.
+    const inUnmetGroup = ownGroups.some((k) => reqGroups[k] && !reqGroups[k].satisfied);
+    const required = !!schema?.required;
+
+    let status: TVariantStatus;
+    let reason: string | undefined;
+    if (invalidReasons[name]) {
+      status = 'invalid';
+      reason = invalidReasons[name];
+    } else if (empty && required) {
+      status = 'todo';
+      reason = 'Needs a value';
+    } else if (empty && inUnmetGroup) {
+      status = 'todo';
+      reason = `One of ${reqGroups[ownGroups[0]].memberLabels.join(' / ')}`;
+    } else if (empty) {
+      status = 'unset';
+    } else {
+      status = 'set';
+    }
+
+    const groupName = getOptionGroup(schema);
+    const groupLabel = config.groupLabels?.[groupName] ?? getOptionGroupLabel(groupName, undefined);
+    if (!groupMap.has(groupName)) {
+      groupMap.set(groupName, { name: groupName, label: groupLabel, rows: [] });
+    }
+    groupMap.get(groupName)!.rows.push({
+      name,
+      label: (schema?.display_name as string) || name,
+      shortDesc: schema?.short_desc,
+      longDesc: schema?.desc,
+      required: required || ownGroups.length > 0,
+      readOnly: !!schema?.readonly,
+      status,
+      reason,
+      value: buildValue(field, schema),
+      typeLabel: `${(schema?.ui_type as string) || (schema?.type as string) || 'auto'}`,
+      requiredGroups: ownGroups,
+      inUnmetGroup,
+      schema,
+      field,
+    });
+  });
+
+  // Stable group order: 'general' first, then the rest, 'optional' last.
+  const groups = Array.from(groupMap.values()).sort((a, b) => {
+    const rank = (g: string) => (g === 'general' ? 0 : g === 'optional' ? 2 : 1);
+    return rank(a.name) - rank(b.name);
+  });
+  return { groups, requiredGroups: reqGroups };
+}
+
+export function summarize(groups: IVariantGroup[]) {
+  const rows = groups.flatMap((g) => g.rows);
+  const total = rows.length;
+  const set = rows.filter((r) => r.status === 'set').length;
+  const todo = rows.filter((r) => r.status === 'todo').length;
+  const invalid = rows.filter((r) => r.status === 'invalid').length;
+  const attention = todo + invalid;
+  const pct = total ? Math.round((set / total) * 100) : 0;
+  return { total, set, todo, invalid, attention, pct };
+}

package/src/components/form/engine/variants/variantParts.tsx

@@ -0,0 +1,313 @@
+/**
+ * Shared rendering parts for the FormEngine compact VARIANTS playground.
+ * Value rendering is shared so every variant shows identical data; the `tone`
+ * prop lets a variant choose a calm (desaturated) or vivid chip treatment.
+ */
+import {
+  ReqoreButton,
+  ReqoreCollapsibleContent,
+  ReqoreControlGroup,
+  ReqoreIcon,
+  ReqoreInput,
+  ReqoreTag,
+} from '@qoretechnologies/reqore';
+import { useReqoreTheme } from '@qoretechnologies/reqore/dist/hooks/useTheme';
+import React from 'react';
+import { AutoFormField } from '../../fields/auto/AutoFormField';
+import { StructuredDataView } from '../_structuredData/StructuredDataView';
+import {
+  buildVariantGroups,
+  summarize,
+  IVariantGroup,
+  IVariantRow,
+  IVariantValue,
+  TVariantStatus,
+} from './variantModel';
+
+export function useVariantColors() {
+  const theme = useReqoreTheme();
+  const intents = (theme.intents || {}) as Record<string, string>;
+  return {
+    main: theme.main as string,
+    text: (theme.text?.color as string) || '#e8e8e8',
+    muted: `${(theme.text?.color as string) || '#e8e8e8'}99`,
+    faint: `${(theme.text?.color as string) || '#e8e8e8'}55`,
+    line: `${(theme.text?.color as string) || '#ffffff'}14`,
+    hover: `${(theme.text?.color as string) || '#ffffff'}0c`,
+    surface: `${(theme.text?.color as string) || '#ffffff'}08`,
+    danger: intents.danger || '#a82a2a',
+    warning: intents.warning || '#d17c29',
+    success: intents.success || '#4a7110',
+    info: intents.info || '#3b7bbf',
+    custom1: intents.custom1 || '#762f7e',
+  };
+}
+
+export const STATUS_COLOR = (
+  status: TVariantStatus,
+  c: ReturnType<typeof useVariantColors>
+) =>
+  status === 'invalid' ? c.danger
+  : status === 'todo' ? c.warning
+  : status === 'set' ? c.success
+  : c.faint;
+
+/** A single status mark — one dot, color = severity. Replaces stripe+box+icon. */
+export const StatusDot = ({
+  status,
+  size = 7,
+}: {
+  status: TVariantStatus;
+  size?: number;
+}) => {
+  const c = useVariantColors();
+  if (status === 'unset') return null;
+  return (
+    <span
+      aria-hidden
+      style={{
+        width: size,
+        height: size,
+        borderRadius: '50%',
+        flex: '0 0 auto',
+        background: STATUS_COLOR(status, c),
+        boxShadow: status !== 'set' ? `0 0 0 3px ${STATUS_COLOR(status, c)}22` : undefined,
+      }}
+    />
+  );
+};
+
+/** The value summary. `tone='calm'` desaturates template/richtext chips. */
+export const ValueView = ({
+  value,
+  tone = 'calm',
+}: {
+  value: IVariantValue;
+  tone?: 'calm' | 'vivid';
+}) => {
+  const c = useVariantColors();
+  const ellipsis: React.CSSProperties = {
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
+    minWidth: 0,
+  };
+
+  switch (value.kind) {
+    case 'empty':
+      // A quiet dash reads as "no value" without shouting "Not set" on every row.
+      return <span style={{ color: c.faint }}>—</span>;
+
+    case 'color':
+      return (
+        <span style={{ display: 'inline-flex', alignItems: 'center', gap: 7, minWidth: 0 }}>
+          <span
+            aria-hidden
+            style={{
+              width: 12,
+              height: 12,
+              borderRadius: 3,
+              flex: '0 0 auto',
+              background: value.extra,
+              border: `1px solid ${c.line}`,
+            }}
+          />
+          <span style={ellipsis}>{value.display}</span>
+        </span>
+      );
+
+    case 'file':
+      return (
+        <span style={{ display: 'inline-flex', alignItems: 'center', gap: 6, minWidth: 0 }}>
+          <ReqoreIcon icon='FileLine' size='13px' style={{ color: c.muted, flexShrink: 0 }} />
+          <span style={ellipsis}>{value.display}</span>
+          {value.extra ?
+            <span style={{ color: c.faint, fontSize: 11, flexShrink: 0 }}>{value.extra}</span>
+          : null}
+        </span>
+      );
+
+    case 'bool':
+      return <span>{value.display}</span>;
+
+    case 'hash':
+      return (
+        <span style={{ display: 'inline-flex', alignItems: 'center', gap: 6, color: c.muted }}>
+          <ReqoreIcon icon='BracesLine' size='12px' style={{ color: c.faint }} />
+          <span>{value.display}</span>
+        </span>
+      );
+
+    case 'template':
+      return tone === 'vivid' ?
+          <ReqoreTag size='small' intent='info' icon='ExchangeDollarLine' label={value.display} />
+        : <span
+            style={{
+              display: 'inline-flex',
+              alignItems: 'center',
+              gap: 5,
+              padding: '1px 7px',
+              borderRadius: 4,
+              background: c.surface,
+              border: `1px solid ${c.line}`,
+              color: c.text,
+              fontSize: 12,
+              maxWidth: '100%',
+              ...ellipsis,
+            }}
+          >
+            <ReqoreIcon icon='ExchangeDollarLine' size='11px' style={{ color: c.custom1, flexShrink: 0 }} />
+            <span style={ellipsis}>{value.display}</span>
+          </span>;
+
+    case 'richtext':
+      return <span style={ellipsis}>{value.display}</span>;
+
+    default:
+      return <span style={ellipsis}>{value.display}</span>;
+  }
+};
+
+/** A reusable description disclosure used by every variant (tap-friendly).
+ *  Unifies short_desc (inline) + long desc into ONE control. */
+export const useDisclosure = () => {
+  const [open, setOpen] = React.useState<Record<string, boolean>>({});
+  return {
+    isOpen: (id: string) => !!open[id],
+    toggle: (id: string) => setOpen((p) => ({ ...p, [id]: !p[id] })),
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Shared form state: filter (all / needs-attention), add-field, inline editing.
+// Each variant calls useVariantForm and renders <VariantToolbar> + <InlineEdit>.
+// ---------------------------------------------------------------------------
+export type TVariantFilter = 'all' | 'attention';
+
+export function useVariantForm(options: any, values: any, config?: any) {
+  const [filter, setFilter] = React.useState<TVariantFilter>('all');
+  const [query, setQuery] = React.useState('');
+  const [showDescriptions, setShowDescriptions] = React.useState(false);
+  const [editing, setEditing] = React.useState<string | null>(null);
+
+  const { groups, requiredGroups } = React.useMemo(
+    () => buildVariantGroups(options, values, config),
+    [options, values, config]
+  );
+  const summary = React.useMemo(() => summarize(groups), [groups]);
+
+  // Filtered view: text query (label match) + 'attention' (todo/invalid only).
+  const visibleGroups: IVariantGroup[] = React.useMemo(() => {
+    const q = query.trim().toLowerCase();
+    return groups
+      .map((g) => ({
+        ...g,
+        rows: g.rows.filter(
+          (r) =>
+            (filter === 'all' || r.status === 'todo' || r.status === 'invalid') &&
+            (!q || r.label.toLowerCase().includes(q) || r.name.toLowerCase().includes(q))
+        ),
+      }))
+      .filter((g) => g.rows.length);
+  }, [groups, filter, query]);
+
+  return {
+    groups,
+    visibleGroups,
+    requiredGroups,
+    summary,
+    filter,
+    setFilter,
+    toggleAttention: () => setFilter((f) => (f === 'attention' ? 'all' : 'attention')),
+    query,
+    setQuery,
+    showDescriptions,
+    toggleDescriptions: () => setShowDescriptions((v) => !v),
+    editing,
+    startEdit: (name: string) => setEditing((cur) => (cur === name ? null : name)),
+    stopEdit: () => setEditing(null),
+  };
+}
+
+export type TVariantForm = ReturnType<typeof useVariantForm>;
+
+/** Compact toolbar: just a prominent filter field. The "needs attention" control
+ *  lives in each variant's header (the count line is the link); all optional
+ *  fields render inline in the Optional group, so there's no "add field" step. */
+export const VariantToolbar = ({ form }: { form: TVariantForm }) => {
+  const c = useVariantColors();
+  const { summary, query, setQuery, showDescriptions, toggleDescriptions } = form;
+  return (
+    <ReqoreControlGroup verticalAlign='center' fluid>
+      <ReqoreInput
+        placeholder='Filter fields…'
+        icon='Search2Line'
+        iconColor='muted'
+        pill
+        fluid
+        value={query}
+        onChange={(e: any) => setQuery(e.currentTarget.value)}
+        onClearClick={() => setQuery('')}
+      />
+      {/* Show short descriptions under every field — like the compact engine's
+          "Show all descriptions" toggle. Icon-only; info-intent when active. */}
+      <ReqoreButton
+        fixed
+        flat
+        minimal
+        intent={showDescriptions ? 'info' : undefined}
+        active={showDescriptions}
+        icon={showDescriptions ? 'InformationFill' : 'InformationLine'}
+        tooltip={showDescriptions ? 'Hide field descriptions' : 'Show field descriptions'}
+        onClick={toggleDescriptions}
+      />
+      <span style={{ color: c.faint, fontSize: 12, paddingLeft: 4, whiteSpace: 'nowrap' }}>
+        {summary.set}/{summary.total} set
+      </span>
+    </ReqoreControlGroup>
+  );
+};
+
+/** Complex value preview — the SAME nested tree + "Show more" fade the compact
+ *  engine uses, so hash/list fields show their contents immediately. */
+export const ComplexPreview = ({ value, onOpen }: { value: unknown; onOpen?: () => void }) => (
+  <ReqoreCollapsibleContent maxCollapsedHeight={120}>
+    <div onClick={(e) => e.stopPropagation()}>
+      <StructuredDataView
+        value={value}
+        collapsibleRoot={false}
+        defaultExpandDepth={2}
+        onItemClick={onOpen}
+      />
+    </div>
+  </ReqoreCollapsibleContent>
+);
+
+/** Inline editor: mounts the REAL field editor (AutoFormField) for the row's
+ *  schema + value, so clicking a field edits it for real (string, number, bool,
+ *  colour, file, richtext, list, date, …). Local state only — the prototype
+ *  doesn't persist; in the engine this flows through handleValueChange. */
+export const InlineEdit = ({ row, onDone }: { row: IVariantRow; onDone: () => void }) => {
+  const [value, setValue] = React.useState(row.field?.value);
+  return (
+    <div
+      style={{ gridColumn: '1 / -1', display: 'flex', flexFlow: 'column', gap: 8, padding: '10px 0 12px' }}
+      onClick={(e) => e.stopPropagation()}
+    >
+      <AutoFormField
+        {...(row.schema || {})}
+        name={row.name}
+        value={value}
+        default_value={row.schema?.default_value}
+        onChange={(_n: string, v: any) => setValue(v)}
+        fluid
+        size='small'
+      />
+      <div style={{ display: 'flex', justifyContent: 'flex-end' }}>
+        <ReqoreButton size='small' intent='success' icon='CheckLine' fixed onClick={onDone}>
+          Done
+        </ReqoreButton>
+      </div>
+    </div>
+  );
+};

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

@@ -190,9 +190,16 @@ export const ViaFormEngine: Story = {
   },
   async play({ canvasElement }) {
     const canvas = within(canvasElement);
-    await expect(await canvas.findByText('My Auto Field')).toBeInTheDocument();
+    // Generous timeout: findByText defaults to 1s, which flakes under CI load
+    // while the engine boots the auto field's type picker (the rest of the suite
+    // waits ~10s).
+    await expect(
+      await canvas.findByText('My Auto Field', undefined, { timeout: 10000 })
+    ).toBeInTheDocument();
     // The auto field renders its type picker inside the engine-driven form.
-    await expect(await canvas.findByText('Please select data type')).toBeInTheDocument();
+    await expect(
+      await canvas.findByText('Please select data type', undefined, { timeout: 10000 })
+    ).toBeInTheDocument();
   },
 };
 

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

@@ -71,6 +71,9 @@ export interface IAutoFieldProps
   uniqueName?: string;
 
   arg_schema?: string | IOptionsSchema;
+  /** Render the arg_schema sub-form in compact (read-first) mode, matching the
+   *  parent engine. */
+  compact?: boolean;
   path?: string;
   column?: boolean;
   level?: number;
@@ -137,6 +140,7 @@ function AutoField<T = any>({
   noSoft,
   path,
   arg_schema,
+  compact,
   column,
   level = 0,
   canBeNull,
@@ -540,6 +544,10 @@ function AutoField<T = any>({
               <FormEngine
                 wrapperPadding='top'
                 flat
+                compact={compact}
+                // Embedded sub-form: no scroll context of its own, so its toolbar
+                // isn't sticky and its header stays transparent (no dark backdrop).
+                compactNested
                 name={name}
                 uniqueName={uniqueName}
                 options={finalArgSchema}