@qoretechnologies/reqraft 0.10.45-pr.95.gc02205d → 0.10.45

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

@@ -49,7 +49,12 @@ import React, { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useSta
 import { useMeasure, useMount, useUpdateEffect } from 'react-use';
 import styled from 'styled-components';
 import { createContext } from 'use-context-selector';
-import { getDefaultValue, insertAtIndex, richtextToString } from '../../../helpers/common';
+import {
+  fixOperatorValue,
+  getDefaultValue,
+  insertAtIndex,
+  richtextToString,
+} from '../../../helpers/common';
 import { getRequiredOptionMessage } from '../../../helpers/options';
 import {
   IValidationResult,
@@ -70,11 +75,7 @@ import {
   isValueTemplate,
 } from '../fields/template/TemplateField';
 import { CompactRow } from './CompactRow';
-import {
-  CompactRowContext,
-  ICompactRowContext,
-  TCodePreviewRenderer,
-} from './compactRowContext';
+import { CompactRowContext, ICompactRowContext, TCodePreviewRenderer } from './compactRowContext';
 import {
   GROUP_INDENT,
   LABEL_AFFORDANCE_WIDTH,
@@ -117,9 +118,25 @@ import {
   isOptionValueEmpty,
   isFixedCompactAllowedValueOption,
   shouldAutoCollapseCompactOption,
+  isUnsetSchemaHash,
 } from './readFirst';
 
 // Re-export types for consumers
+/** The compact form's three status boxes. */
+export type TFormEngineBoxKey = 'attention' | 'set' | 'optional';
+
+/** Which parts of the compact toolbar to render — see `compactToolbar`. */
+export interface IFormEngineToolbarParts {
+  /** The "Ready / 4 of 6 set / 67%" line and its meter. */
+  completion?: boolean;
+  /** The "Filter fields…" input. */
+  search?: boolean;
+  /** The field-picker dropdown (add optional fields, reset, revert). */
+  fields?: boolean;
+  /** The help button that opens the options dialog. */
+  help?: boolean;
+}
+
 export type IOptions = TQorusForm;
 export type TFlatOptions = TQorusFlatForm;
 export type TOption = IQorusFormField;
@@ -133,8 +150,7 @@ export type TOperatorValue = TQorusFormOperatorValue;
  * consumer gets.
  */
 export interface IOptionFieldMessage
-  extends IQorusFormFieldMessage,
-    Pick<IConditionalFieldMessage, 'when' | 'unless'> {}
+  extends IQorusFormFieldMessage, Pick<IConditionalFieldMessage, 'when' | 'unless'> {}
 export type IOptionsSchemaArg = TQorusFormFieldSchema;
 export interface IOptionsSchema extends IQorusFormSchema {}
 export interface IOperator extends IQorusFormOperator {}
@@ -292,9 +308,10 @@ const getTypeFromOperator = (
   return (operators[last(operatorData) as string]?.type as TQorusType) || null;
 };
 
-export const fixOperatorValue = (operator: TOperatorValue): (string | null | undefined)[] => {
-  return isArray(operator) ? operator : [operator];
-};
+/** Re-exported from `helpers/common` so existing importers keep working; it
+ *  lives there because `helpers/validations` needs it and cannot import this
+ *  module (this module imports the validators). */
+export { fixOperatorValue } from '../../../helpers/common';
 
 /**
  * The renderer-only predicate. Defaults to reqraft's built-ins; a FormEngine
@@ -307,11 +324,9 @@ const getOptionSchemaStorageType = (
   option?: TQorusFormFieldSchema,
   isRendererOnly: TRendererOnlyCheck = isRendererOnlyUiType
 ): TQorusType =>
-  ((isFixedCompactAllowedValueOption(option)
-    ? option?.type || option?.ui_type
-    : isRendererOnly(option?.ui_type)
-    ? option?.type || option?.ui_type
-    : option?.ui_type || option?.type) || 'any') as TQorusType;
+  ((isFixedCompactAllowedValueOption(option) ? option?.type || option?.ui_type
+  : isRendererOnly(option?.ui_type) ? option?.type || option?.ui_type
+  : option?.ui_type || option?.type) || 'any') as TQorusType;
 
 const getOptionFieldStorageType = (
   optionName: string,
@@ -323,9 +338,9 @@ const getOptionFieldStorageType = (
 ): TQorusType => {
   const schemaOption = schema?.[optionName];
   const storedType =
-    fieldType && !(fieldType === schemaOption?.ui_type && isRendererOnly(fieldType))
-      ? fieldType
-      : getOptionSchemaStorageType(schemaOption, isRendererOnly);
+    fieldType && !(fieldType === schemaOption?.ui_type && isRendererOnly(fieldType)) ?
+      fieldType
+    : getOptionSchemaStorageType(schemaOption, isRendererOnly);
 
   return getType(storedType as TQorusType, operators, operatorData);
 };
@@ -373,6 +388,23 @@ export const fixOptions = (
         (fixedValue[name] as IQorusFormField)?.value === undefined
       ) {
         obj = option.default_value as IQorusFormField;
+      } else if (
+        option.default_view === 'expression' &&
+        (fixedValue[name] as IQorusFormField)?.value === undefined
+      ) {
+        // A field the schema declares as opening in expression mode starts as an
+        // EMPTY expression, not as its raw default. `isDefaultFunction` already
+        // makes the renderer open that way, so without this the data disagreed
+        // with what the operator was looking at: an expression editor whose
+        // value was still the plain default, and no `is_expression` on the field
+        // until the first edit.
+        obj = {
+          type,
+          value: {
+            args: [],
+          },
+          is_expression: true,
+        };
       } else {
         obj = {
           type,
@@ -438,9 +470,19 @@ export const fixOptions = (
       // every value declared the bare way: the collapsed row still showed its
       // display name while the editor showed "—" and the value never reached
       // the submitted data.
+      // `allowed_values: []` is NOT "no value is permitted" — it is the server
+      // saying it has no reference values to offer right now (the app-action
+      // catalogue ships exactly that, with an
+      // `option_reference_values_unavailable` message attached). An empty array
+      // is truthy, so testing the array itself made every such option erase the
+      // operator's stored value on the first render, before the
+      // connection-refreshed schema arrived to say otherwise — and the emptied
+      // form then autosaved over the draft, so the value was gone for good.
+      // Only an option that actually declares choices can have a value that is
+      // not one of them.
       if (
         newOption.value !== undefined &&
-        options?.[optionName]?.allowed_values &&
+        options?.[optionName]?.allowed_values?.length &&
         !findAllowedValueOption(newOption.value, options?.[optionName]) &&
         !isValueTemplate(newOption.value) &&
         !options?.[optionName]?.multiselect &&
@@ -626,6 +668,37 @@ export interface IFormEngineProps extends Omit<IReqoreCollectionProps, 'onChange
    * No-op in classic (non-compact) mode.
    */
   compactPanelProps?: IReqorePanelProps;
+  /**
+   * Compact mode only: which status boxes start collapsed. Defaults to
+   * `['optional']` — a form opens on what is in use.
+   *
+   * Pass `['set', 'optional']` where the form is one item in a longer list and
+   * the reader is choosing WHICH to open rather than reading this one, e.g. a
+   * template's per-action option forms stacked in a drawer.
+   *
+   * Two escapes override this and are not negotiable: a box always opens while
+   * a search query is running (`ReqorePanel` unmounts collapsed content, so a
+   * match inside a closed box would be unreachable), and the Optional box stays
+   * open when every row is optional, because collapsing it would render a card
+   * that looks empty and broken.
+   */
+  compactCollapsedGroups?: TFormEngineBoxKey[];
+  /**
+   * Compact mode only: which parts of the form's toolbar to show. `true`
+   * (default) shows all of it; `false` hides the whole thing.
+   *
+   * The parts already hide themselves when they have nothing to say — the
+   * completion meter needs at least one counted option, and the search and
+   * field-picker need more than one option to pick between — so reach for this
+   * only to hide something that WOULD have rendered. A per-action form asking
+   * for one value, say, has a meter reading 0/1 that tells the reader nothing
+   * they cannot see in the row below it.
+   *
+   * Hiding `search` removes the only way to run a query, which is what forces
+   * a collapsed box open; `compactCollapsedGroups` then fully determines what
+   * is open.
+   */
+  compactToolbar?: boolean | IFormEngineToolbarParts;
   /** Compact mode only: per-group display metadata (label / icon / subtitle /
    * order) — the server only sends the bare group key. */
   groups?: Record<string, IFormEngineGroup>;
@@ -792,6 +865,8 @@ const FormEngineImpl = ({
   compactFlush = false,
   compactNested = false,
   compactPanelProps,
+  compactCollapsedGroups = ['optional'],
+  compactToolbar = true,
   commitMode = 'immediate',
   expandMode = 'single',
   onCommit,
@@ -1129,7 +1204,10 @@ const FormEngineImpl = ({
           setOptions({});
           return;
         }
-        setLocalValue({ fields: fixOptions(value, data.data, undefined, isRendererOnly), meta: undefined });
+        setLocalValue({
+          fields: fixOptions(value, data.data, undefined, isRendererOnly),
+          meta: undefined,
+        });
         if (!operatorsUrl) {
           setLoading(false);
         }
@@ -1174,7 +1252,10 @@ const FormEngineImpl = ({
         }
         setOptions(data.data);
         onOptionsLoaded?.(data.data);
-        setLocalValue({ fields: fixOptions({}, data.data, undefined, isRendererOnly), meta: undefined });
+        setLocalValue({
+          fields: fixOptions({}, data.data, undefined, isRendererOnly),
+          meta: undefined,
+        });
       })();
     }
   }, [url, customUrl]);
@@ -1231,12 +1312,14 @@ const FormEngineImpl = ({
         const isAnyLike = schemaType === 'any' || schemaType === 'auto';
         // For any/auto schema types, preserve the user's chosen type stored in the field
         const resolvedSchemaType =
-          isAnyLike && (fields[optionName] as IQorusFormField)?.type
-            ? ((fields[optionName] as IQorusFormField).type as TQorusType)
-            : (fields[optionName] as IQorusFormField)?.type === options?.[optionName]?.ui_type &&
-                isRendererOnly((fields[optionName] as IQorusFormField)?.type)
-              ? schemaType
-              : schemaType || ((fields[optionName] as IQorusFormField)?.type as TQorusType);
+          isAnyLike && (fields[optionName] as IQorusFormField)?.type ?
+            ((fields[optionName] as IQorusFormField).type as TQorusType)
+          : (
+            (fields[optionName] as IQorusFormField)?.type === options?.[optionName]?.ui_type &&
+            isRendererOnly((fields[optionName] as IQorusFormField)?.type)
+          ) ?
+            schemaType
+          : schemaType || ((fields[optionName] as IQorusFormField)?.type as TQorusType);
         const type =
           _type ||
           getTypeAndCanBeNull(resolvedSchemaType, options?.[optionName]?.allowed_values).type;
@@ -1310,11 +1393,7 @@ const FormEngineImpl = ({
 
         onSingleOptionsChange?.(optionName, updatedValue[optionName]);
 
-        if (
-          compact &&
-          !readOnly &&
-          shouldAutoCollapseCompactOption(options?.[optionName], val)
-        ) {
+        if (compact && !readOnly && shouldAutoCollapseCompactOption(options?.[optionName], val)) {
           setExpandedOptions((prev) => prev.filter((name) => name !== optionName));
         }
 
@@ -1757,7 +1836,11 @@ const FormEngineImpl = ({
         isRendererOnly
       );
       const value = (availableOptions as TQorusForm)?.[name]?.value;
-      const empty = isOptionValueEmpty(value);
+      // A schema-declared hash whose every entry is a materialised-but-unset
+      // field holds nothing, so it is not "set" — without this the row showed a
+      // green set-dot and counted toward the completion meter while the
+      // sub-form it summarises said 0/3 set.
+      const empty = isOptionValueEmpty(value) || isUnsetSchemaHash(value, schema);
       const reqGroups = (schema?.required_groups as string[] | undefined) || [];
       const required = !!(schema?.required || reqGroups.length);
       const covered =
@@ -2060,7 +2143,10 @@ const FormEngineImpl = ({
           next[optionName] = value as IQorusFormField;
         }
       });
-      return { fields: fixOptions(next, options || {}, operators, isRendererOnly), meta: undefined };
+      return {
+        fields: fixOptions(next, options || {}, operators, isRendererOnly),
+        meta: undefined,
+      };
     });
     setRequiredOnly(false);
   }, [JSON.stringify(options), JSON.stringify(operators), isRendererOnly]);
@@ -2108,11 +2194,10 @@ const FormEngineImpl = ({
       const schemaUiType = optionSchema?.ui_type as TQorusType;
       const uiTypeIsAnyLike = schemaUiType === 'any' || schemaUiType === 'auto';
       const resolvedType =
-        (isFixedCompactAllowedValueOption(optionSchema)
-          ? getOptionSchemaStorageType(optionSchema, isRendererOnly)
-          : schemaUiType && !uiTypeIsAnyLike
-            ? schemaUiType
-            : undefined) ||
+        (isFixedCompactAllowedValueOption(optionSchema) ?
+          getOptionSchemaStorageType(optionSchema, isRendererOnly)
+        : schemaUiType && !uiTypeIsAnyLike ? schemaUiType
+        : undefined) ||
         type ||
         schemaUiType ||
         (optionSchema?.type as TQorusType) ||
@@ -2307,6 +2392,11 @@ const FormEngineImpl = ({
             allowed_values_creatable={options?.[optionName]?.allowed_values_creatable}
             disabled={
               options?.[optionName]?.disabled ||
+              // a system-owned field states that as `readonly`; only the older
+              // compat projection also sent `disabled`, so honouring only
+              // `disabled` rendered an editable control for a value the user
+              // cannot change (see CompactRow's `fieldReadonly`)
+              (options?.[optionName] as { readonly?: boolean } | undefined)?.readonly ||
               readOnly ||
               !hasAllDependenciesFullfilled(
                 options?.[optionName]?.depends_on,
@@ -2503,6 +2593,14 @@ const FormEngineImpl = ({
     ]
   );
 
+  // `compactToolbar` resolved to a full object, so neither the context type nor
+  // the toolbar itself has to re-default anything. `null` means no toolbar.
+  const compactToolbarParts = useMemo(() => {
+    if (compactToolbar === false) return null;
+    const all = { completion: true, search: true, fields: true, help: true };
+    return compactToolbar === true ? all : { ...all, ...compactToolbar };
+  }, [JSON.stringify(compactToolbar)]);
+
   const compactToolbarContextValue = useMemo<ICompactToolbarContext>(
     () => ({
       readOnly,
@@ -2511,6 +2609,12 @@ const FormEngineImpl = ({
       completion: readFirstCompletion,
       showInvalidOnly: showInvalidOptionsOnly,
       onToggleInvalidOnly: handleToggleInvalidOnly,
+      parts: compactToolbarParts ?? {
+        completion: false,
+        search: false,
+        fields: false,
+        help: false,
+      },
       hasMultipleOptions: size(availableOptions) > 1,
       compactQuery,
       setCompactQuery,
@@ -2561,10 +2665,14 @@ const FormEngineImpl = ({
 
   // The engine's own toolbar action, plus whatever the consumer added through
   // `compactPanelProps.actions` — appended, so an outside action can never
-  // knock the form's toolbar out of the header.
+  // knock the form's toolbar out of the header. Only `compactToolbar={false}`
+  // removes it, and then the header carries just the consumer's own actions.
   const compactHeaderActions = useMemo(
-    () => [{ as: CompactToolbar, responsive: false }, ...(compactPanelProps?.actions || [])],
-    [compactPanelProps?.actions]
+    () => [
+      ...(compactToolbarParts ? [{ as: CompactToolbar, responsive: false }] : []),
+      ...(compactPanelProps?.actions || []),
+    ],
+    [compactPanelProps?.actions, compactToolbarParts]
   );
   const renderCompact = () => {
     const headerBg = `${changeDarkness(getMainBackgroundColor(theme), 0.02)}${percentToHexAlpha(88)}`;
@@ -2577,9 +2685,40 @@ const FormEngineImpl = ({
       if (requiredOnly && !(schema?.required || schema?.required_groups)) {
         return false;
       }
-      return matchesQuery(optionName);
+      // A field that absorbs a sibling also answers for it: searching
+      // "language" has to surface the row that now holds the language control,
+      // or the field becomes unreachable through the filter.
+      if (matchesQuery(optionName)) return true;
+      const absorb = (schema as { absorb_fields?: string[] } | undefined)?.absorb_fields;
+      return !!absorb?.some((absorbedName) => matchesQuery(absorbedName));
     };
 
+    // Fields a sibling absorbs into its own container.
+    //
+    // A field declaring `absorb_fields: ['language']` renders that sibling's
+    // control inside its own row instead of letting it have a row of its own.
+    // The pair this exists for is a code editor and its language: they are one
+    // decision — "what is this code, and in what language" — and reading them
+    // as two unrelated rows one above the other is what the layout used to say.
+    //
+    // Absorbed fields stay in `grouped`, and therefore in the Set / Optional /
+    // Needs-attention counts and in the completion meter. Only the ROW is
+    // skipped. Dropping them from the buckets instead would leave the meter
+    // ("13/18 set", computed from `availableOptions`) disagreeing with the box
+    // badge beside it, which counts row entries.
+    const absorbedBy: Record<string, string> = {};
+    forEach(options, (option, optionName) => {
+      const absorb = (option as { absorb_fields?: string[] } | undefined)?.absorb_fields;
+      if (!absorb?.length) return;
+      absorb.forEach((absorbedName) => {
+        // Only absorb a sibling that exists and is not already spoken for; a
+        // schema naming a missing field must not make the field disappear.
+        if (options?.[absorbedName] && !absorbedBy[absorbedName]) {
+          absorbedBy[absorbedName] = optionName;
+        }
+      });
+    });
+
     // Group the options by their raw `group` key, remembering the order groups
     // first appear in the schema. Each row carries a `hidden` flag.
     const groupOrder: string[] = [];
@@ -2668,17 +2807,20 @@ const FormEngineImpl = ({
     // schema-group order (thin sub-labels) and the required-group clustering: an
     // unmet one-of group's members all land in attention and still rail up.
     type TRowEntry = { name: string; hidden: boolean };
-    type TBucketKey = 'attention' | 'set' | 'optional';
-    const buckets: Record<TBucketKey, Record<string, TRowEntry[]>> = {
+    const buckets: Record<TFormEngineBoxKey, Record<string, TRowEntry[]>> = {
       attention: {},
       set: {},
       optional: {},
     };
-    const bucketGroups: Record<TBucketKey, string[]> = { attention: [], set: [], optional: [] };
+    const bucketGroups: Record<TFormEngineBoxKey, string[]> = {
+      attention: [],
+      set: [],
+      optional: [],
+    };
     // Freeze the box of any field currently being edited (or whose one-of group
     // has an edited member) to its last settled box — so finishing an edit that
     // flips its status doesn't remount it in another box and steal focus.
-    const stableBucketOf = (entry: TRowEntry): TBucketKey => {
+    const stableBucketOf = (entry: TRowEntry): TFormEngineBoxKey => {
       const fresh = getOptionBucket(entry.name, entry.hidden);
       const groupBeingEdited =
         !entry.hidden &&
@@ -2702,7 +2844,7 @@ const FormEngineImpl = ({
         buckets[b][groupName].push(entry);
       });
     });
-    const bucketCount = (b: TBucketKey) =>
+    const bucketCount = (b: TFormEngineBoxKey) =>
       bucketGroups[b].reduce((n, g) => n + buckets[b][g].length, 0);
 
     // "Is the Optional box the whole form?" — when nothing needs attention and
@@ -2718,7 +2860,7 @@ const FormEngineImpl = ({
     const showGroupSubLabel = (groupName: string) =>
       (groupName !== 'general' && groupName !== 'optional') || !!groups?.[groupName];
     const STATUS_BOXES: Array<{
-      key: TBucketKey;
+      key: TFormEngineBoxKey;
       label: string;
       intent?: 'warning' | 'success';
       icon: IReqoreIconName;
@@ -2732,6 +2874,11 @@ const FormEngineImpl = ({
     // together at the first member's slot and rendered as a connected rail (flat
     // rows — no wrapper — so the value surface applies normally; the rail + nodes
     // are drawn per member). Narrow stacks fall back to flat rows.
+    // The absorbed siblings a host row must render, in schema order. Empty for
+    // every row that absorbs nothing, which is all of them by default.
+    const absorbedNamesFor = (hostName: string): string[] =>
+      Object.keys(absorbedBy).filter((absorbedName) => absorbedBy[absorbedName] === hostName);
+
     const renderGroupRows = (names: Array<{ name: string; hidden: boolean }>) => {
       const renderRow = (
         entry: { name: string; hidden?: boolean },
@@ -2754,6 +2901,9 @@ const FormEngineImpl = ({
           clustered={clustered}
           clusterFirst={clusterFirst}
           clusterLast={clusterLast}
+          // The siblings this row renders inside itself instead of leaving
+          // them a row of their own — see `absorbedBy`.
+          absorbedFields={absorbedNamesFor(entry.name)}
         />
       );
       // (Clustering runs in narrow mode too now — the "One of the below is
@@ -2762,6 +2912,10 @@ const FormEngineImpl = ({
       const emitted = new Set<string>();
       const groupOf = (name: string) =>
         (options?.[name]?.required_groups as string[] | undefined)?.[0];
+      // An absorbed field keeps its place in the buckets — so the Set /
+      // Optional counts and the completion meter still see it — but its host
+      // renders its control, so it gets no row of its own here.
+      names = names.filter((entry) => !absorbedBy[entry.name]);
       return names.map((entry) => {
         const grp = groupOf(entry.name);
         if (!grp) return renderRow(entry, false);
@@ -2812,6 +2966,10 @@ const FormEngineImpl = ({
                 $flush={compactFlush || compactNested}
               >
                 <StyledCompactPanel
+                  // Mirrors the toolbar's own search-row gate: when no search
+                  // row renders, the header is a thin strip and sits tight to
+                  // the first status box (see StyledCompactPanel).
+                  $tightHeader={!(compactToolbarParts?.search && size(availableOptions) > 1)}
                   // The top-level form scrolls, so its toolbar STICKS and carries a
                   // dark blurred backdrop so content ghosts cleanly beneath it. A
                   // nested (arg_schema) sub-form owns no scroll context — drop the
@@ -2878,24 +3036,29 @@ const FormEngineImpl = ({
                         minimal
                         collapseButtonProps={{ flat: true, minimal: true, size: 'small' }}
                         collapsible
-                        // The Optional box now holds every not-yet-added field, so
-                        // it starts COLLAPSED to keep the form focused on what's in
-                        // use. But a SEARCH must surface matching addable fields —
-                        // and ReqorePanel unmounts collapsed content — so force it
-                        // open whenever a query is active. (isCollapsed is the
-                        // panel's controllable state; manual toggling still works
-                        // when no query is set.)
-                        // The Optional box starts collapsed so a form opens on what
-                        // is in use — but only when there IS something else to
-                        // open on. When every field is optional it is the whole
-                        // form, and collapsing it renders a card that looks empty
-                        // and broken: an auth profile's Authorization block, whose
-                        // nine requirement fields are all optional, showed as a
-                        // titled card containing one collapsed "Optional 9" strip
-                        // and nothing else. A search still forces it open
-                        // (ReqorePanel unmounts collapsed content, so a match
-                        // inside it would be unreachable otherwise).
-                        isCollapsed={box.key === 'optional' && !query && !onlyOptionalRows}
+                        // Which boxes start closed is the consumer's call
+                        // (`compactCollapsedGroups`, default `['optional']`: the
+                        // Optional box holds every not-yet-added field, so a form
+                        // opens on what is in use). Two rules override it:
+                        //
+                        // A SEARCH forces every box open — ReqorePanel unmounts
+                        // collapsed content, so a match inside a closed box would
+                        // be unreachable. (isCollapsed is the panel's controllable
+                        // state; manual toggling still works with no query set.)
+                        //
+                        // The Optional box stays open when it is the ONLY box,
+                        // because collapsing it renders a card that looks empty and
+                        // broken: an auth profile's Authorization block, whose nine
+                        // requirement fields are all optional, showed as a titled
+                        // card containing one collapsed "Optional 9" strip and
+                        // nothing else. This does not generalise to the other two —
+                        // a lone Set box collapsed is a deliberate ask, and its
+                        // header still reports what is in there.
+                        isCollapsed={
+                          compactCollapsedGroups.includes(box.key) &&
+                          !query &&
+                          !(box.key === 'optional' && onlyOptionalRows)
+                        }
                         label={
                           <StyledGroupHeader>
                             <ReqoreP effect={{ weight: 'bold' }} size='normal'>

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

@@ -55,6 +55,78 @@ const methodValue = [
   { type: 'hash', value: { name: 'onConnect', desc: 'connection lifecycle hook' } },
 ];
 
+/**
+ * A schema whose hash values hold hash values of their own — three levels, not
+ * one.
+ *
+ * Every other fixture here is a flat record, and a flat record cannot show what
+ * this view does with depth: whether a nested level is legible, whether the
+ * rules stack sensibly, whether a heading two levels down still reads as a
+ * heading. Judging the treatment on a single `key: value` pair is what the
+ * review said was impossible, and it was right.
+ */
+const NestedSchema = {
+  name: { type: 'string', display_name: 'Endpoint' },
+  auth: {
+    type: 'hash',
+    display_name: 'Authentication',
+    arg_schema: {
+      scheme: {
+        type: 'string',
+        display_name: 'Scheme',
+        allowed_values: [
+          { value: 'oauth2', display_name: 'OAuth2' },
+          { value: 'basic', display_name: 'Basic' },
+        ],
+      },
+      token: {
+        type: 'hash',
+        display_name: 'Token',
+        arg_schema: {
+          url: { type: 'string', display_name: 'Token URL' },
+          ttl: { type: 'int', display_name: 'Lifetime (s)' },
+          rotate: { type: 'bool', display_name: 'Rotate Automatically' },
+        },
+      },
+    },
+  },
+  retry: {
+    type: 'hash',
+    display_name: 'Retry Policy',
+    arg_schema: {
+      attempts: { type: 'int', display_name: 'Attempts' },
+      backoff: { type: 'string', display_name: 'Backoff' },
+    },
+  },
+} as never;
+
+const nestedValue = [
+  {
+    type: 'hash',
+    value: {
+      name: 'POST /orders',
+      auth: {
+        scheme: 'oauth2',
+        token: {
+          url: 'https://auth.example.com/oauth2/token',
+          ttl: 3600,
+          rotate: true,
+        },
+      },
+      retry: { attempts: 3, backoff: 'exponential' },
+    },
+  },
+  {
+    // A second record that fills only part of the tree: the nested level is
+    // present but shallow, which is where "no data under the label" shows up.
+    type: 'hash',
+    value: {
+      name: 'GET /orders/{id}',
+      auth: { scheme: 'basic' },
+    },
+  },
+];
+
 const colors = { key: '#f1f0ee', muted: '#a0a0a0', border: '#a0a0a066', accent: '#3b8eea' };
 
 export const Schemes: Story = {
@@ -127,3 +199,35 @@ export const Undescribed: Story = {
     await expect(label!.offsetHeight).toBeLessThan(lineHeight * 1.6);
   },
 };
+
+/**
+ * The deeper case: hash values holding hash values.
+ *
+ * Asked for in review because the flat fixtures could not answer whether the
+ * treatment survives nesting — three levels here (endpoint → authentication →
+ * token), plus a second record that stops after one, so a nested level with
+ * nothing under it renders beside one that is full.
+ */
+export const NestedSchemas: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'A described list whose records nest two levels deeper: an endpoint carrying an Authentication hash, which itself carries a Token hash of URL, lifetime and a bool. The second record fills only the first nested level, so a shallow branch sits next to a full one.',
+      },
+    },
+  },
+  args: { value: nestedValue, schema: NestedSchema, colors },
+  play: async ({ canvasElement }) => {
+    const titles = [...canvasElement.querySelectorAll('.schema-view-item-title')].map((element) =>
+      (element.textContent ?? '').trim()
+    );
+
+    await expect(titles).toEqual(['POST /orders', 'GET /orders/{id}']);
+    // The deepest level actually rendered: a label from the third tier, and the
+    // bool beneath it resolved to a word rather than printed as `true`.
+    await expect(canvasElement.textContent).toContain('Token URL');
+    await expect(canvasElement.textContent).toContain('Lifetime (s)');
+    await expect(canvasElement.textContent).not.toContain('[object Object]');
+  },
+};