@wildo-ai/saas-frontend-lib 1.1.9 → 1.1.11

package/dist/esm/components/sections/ContentSectionContainer.js

@@ -16,23 +16,30 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  * - Expandable: accordion, expandable
  * - Guided: stepper, timeline
  */
-import { useCallback, useId, useRef, useState } from 'react';
+import React, { useCallback, useEffect, useId, useRef, useState } from 'react';
 import { SectionMode, DisplayDirection } from '@wildo-ai/zod-decorators';
 import { cn } from '../../core/ui/cn.js';
+import { focusIndicatorClasses, FocusIndicatorShape } from '../../core/ui/themes/focus-indicator.js';
 import { useUI } from '../../core/ui/useUI.js';
 import { useSurfacePolicy } from '../../core/ui/SurfacePolicyContext.js';
 import { ButtonSize, FrontendComponentType, LabellingTypes, UIBehavior, SelectableVariant, SurfaceVariant, TypographyVariant } from '@wildo-ai/presets-components-models';
 import { useI18n } from '../../core/i18n/useI18n.js';
+import { useIconRegistry } from '../../core/icons/useIconRegistry.js';
+import { IconSize, StandardIconReference } from '../../core/icons/icon-registry.frontend.schemas.js';
+import { sectionHeadingClassName } from '../../components/sections/section-legend-voice.js';
 import { Tabs, TabsList, TabsTrigger, TabsContent } from '../../components/sections/tabs.js';
 import { Timeline, TimelineBody, TimelineEntry } from '../../components/data-display/timeline.js';
 import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from '../../components/sections/accordion.js';
 import { ToggleGroupType } from '../../components/form/controls/enum/toggle-group.js';
 import { Collapsible, CollapsibleTrigger, CollapsibleContent } from '../../components/sections/collapsible.js';
+import { Stepper, StepperIndicator, StepperItem, StepperSeparator, StepperTitle } from '../../components/sections/stepper.js';
 import { Button, ButtonVariants_Variant } from '../../components/actions/button.js';
 import { Badge } from '../../components/data-display/badge.js';
 import { Surface } from '../../components/sections/surface.js';
 import { ContentSection } from '../../components/sections/content-section.js';
 import { EmptyState } from '../../components/feedback/empty-state.js';
+import { DEFAULT_EXPANDABLE_INITIAL_VISIBLE_COUNT } from '../../components/sections/section-grouping.shared.js';
+import { fieldRevealPanelAttributes, useFieldRevealRequests, useKeepsHiddenPanelsMounted } from '../../components/form/validation-errors/field-reveal.js';
 function resolveSectionWrapMode(value) {
     switch (value) {
         case 'grouped':
@@ -45,22 +52,16 @@ function resolveSectionWrapMode(value) {
 }
 /**
  * Maps the surface-policy `autoSectionWrap` to a {@link ContentSection}
- * `appearance` (+ optional className). Every container panel now renders through
- * the registry-resolved `ContentSection` primitive (P3 consolidation), so panels
- * inherit the native `<fieldset disabled>` cascade and the truthful `when-orphan`
- * frame de-duplication that solo sections already have — instead of the old
- * always-on `<Surface variant=BASE><div border rounded-lg>` chrome that could not
- * de-dup its frame when nested:
- * - `card-each`      → CARD     (framed fieldset; frame self-suppresses when nested)
+ * `appearance` (+ optional className). Every container panel renders through
+ * the registry-resolved `ContentSection` primitive, so panels inherit the native
+ * `<fieldset disabled>` cascade solo sections have:
+ * - `card-each`      → CARD     (a framed fieldset; an authored card paints its frame in every context, nested or not)
  * - `flat`           → DEFAULT  (bare fieldset, no frame)
  * - `separator-only` → DEFAULT  + a bottom-divider className
  *
- * Note (plan P3, §7 Decision 2 — heading-chrome redesign): container panels render
- * through ContentSection's PANEL mode, which PRESERVES the titled-card-with-header
- * look (an `<h3>` band with icon over a `border-b` divider, content in a `p-card`
- * area) while gaining the `<fieldset>` disabled cascade + when-orphan frame de-dup.
- * The visible chrome is unchanged from the former bespoke `<Surface><div border
- * rounded-lg>`; only the element (div → fieldset) and the frame-dedup behavior change.
+ * Container panels render through ContentSection's PANEL mode: a titled card with a
+ * header band (an `<h3>` with icon over a `border-b` divider, content in a `p-card`
+ * area) for CARD, a flat group otherwise.
  */
 function wrapModeToAppearance(wrapMode) {
     switch (wrapMode) {
@@ -104,7 +105,8 @@ const GroupedSectionsCard = ({ sections, className }) => {
  * the heading renders as an `<h3>`/`<h4>` band (icon + title, level per `titleTag`,
  * default `h3`) with a `border-b` divider above the `p-card` content area (the
  * titled-card-with-header look), framed per `wrapMode` via a `<fieldset>` that
- * carries the disabled cascade + when-orphan frame-dedup. Used by the panel-heading
+ * carries the disabled cascade (a `card-each` panel always paints its card, a flat
+ * one never frames). Used by the panel-heading
  * modes (single / inline / grid / columns / collapsible / expandable). Collapsible
  * panels pass `titleTag: 'h4'` since they nest under the collapsible-all `<h3>`.
  * The explicit `section.disabled` flows to the panel `<fieldset disabled>` for the
@@ -127,6 +129,18 @@ function renderSectionContentChrome(section, content = section.content, wrapMode
     const { appearance, className } = wrapModeToAppearance(wrapMode);
     return (_jsx(ContentSection, { panel: true, appearance: appearance, className: className, children: content }, section.id));
 }
+/**
+ * A section's content, introduced by its description. The modes whose heading lives OUTSIDE the panel (a tab, a
+ * pill, a step, an accordion row) render the panel content-only, so the description had nowhere to go and was
+ * dropped: TABS, VERTICAL_TABS, PILLS and STEPPER showed a section without the sentence that says what it is for,
+ * which every other mode shows. It leads the panel, in the theme's description voice.
+ */
+function SectionPanelContent({ section }) {
+    const { getRecipe } = useUI();
+    if (section.description == null)
+        return section.content;
+    return (_jsxs(_Fragment, { children: [_jsx("p", { className: cn('mb-field', getRecipe(UIBehavior.TYPOGRAPHY, TypographyVariant.DESCRIPTION).base), children: section.description }), section.content] }));
+}
 // =============================================================================
 // MAIN COMPONENT
 // =============================================================================
@@ -186,6 +200,14 @@ const GAP_CLASSES = {
     md: 'gap-field',
     lg: 'gap-section',
 };
+/** The length each gap class stands for, for a column computation that has to subtract the gaps. */
+const GAP_LENGTHS = {
+    sm: 'var(--spacing-element)',
+    md: 'var(--spacing-field)',
+    lg: 'var(--spacing-section)',
+};
+/** The narrowest a COLUMNS column gets before the columns become fewer (the GRID default minimum, for one look). */
+const COLUMNS_MIN_WIDTH = '300px';
 const CONTENT_SECTION_CONTAINER_COMPONENT = FrontendComponentType.LOW_LEVEL_CONTENT_SECTION_CONTAINER;
 function useContentSectionContainerLabel() {
     const { tComponent } = useI18n({
@@ -205,41 +227,80 @@ const InlineMode = ({ sections, config, className, sectionWrapMode }) => {
     if (sectionWrapMode === 'grouped') {
         return _jsx(GroupedSectionsCard, { sections: sections, className: className });
     }
-    return (_jsx("div", { className: cn(`space-y-field ${gapClass}`, className), role: "region", "aria-label": config.ariaLabel ?? getLabel('contentSectionsRegion'), children: sections.map((section) => renderPanelSection(section, { wrapMode: sectionWrapMode })) }));
+    return (_jsx("div", { 
+        // A column with the configured gap. `space-y-field` beside a `gap-*` class gave every gap the field spacing:
+        // `gap` does nothing on a block container, so the `gap` option was a no-op.
+        className: cn('flex flex-col', gapClass, className), role: "region", "aria-label": config.ariaLabel ?? getLabel('contentSectionsRegion'), children: sections.map((section) => renderPanelSection(section, { wrapMode: sectionWrapMode })) }));
 };
 const GridMode = ({ sections, config, className, sectionWrapMode }) => {
-    const columnCount = config.columnCount === 'auto' ? undefined : config.columnCount ?? 2;
+    // `'auto'` is the documented default (`SectionConfig_Grid.columnCount`); the code defaulted to 2.
+    const columnCount = config.columnCount === 'auto' || config.columnCount === undefined ? undefined : config.columnCount;
     const gap = config.gap ?? 'md';
     const minColumnWidth = config.minColumnWidth ?? '300px';
     const gapClass = GAP_CLASSES[gap];
     const getLabel = useContentSectionContainerLabel();
-    const style = columnCount
-        ? { gridTemplateColumns: `repeat(${columnCount}, 1fr)` }
-        : { gridTemplateColumns: `repeat(auto-fit, minmax(${minColumnWidth}, 1fr))` };
+    /*
+     * Responsive in both shapes. `auto` fits as many columns of `minColumnWidth` as the container holds. A column
+     * COUNT is a ceiling, not a constant: each column is at least its share of the row (so a wide container shows
+     * exactly N) and at least `minColumnWidth` (so a narrow one shows fewer, down to one). A fixed `repeat(N, 1fr)`
+     * squeezed two columns into a phone. `min(100%, …)` keeps a single column from overflowing a container narrower
+     * than the minimum.
+     *
+     * The two shapes differ when there are fewer sections than columns. A COUNT keeps its columns (`auto-fill`): two
+     * sections in a three-column grid take two of three columns, as `grid-cols-3` does, so they line up with a
+     * three-column grid beside them. `auto` lets the sections fill the row (`auto-fit` collapses the empty columns).
+     */
+    const columnWidth = columnCount
+        ? `max(${minColumnWidth}, calc((100% - ${columnCount - 1} * ${GAP_LENGTHS[gap]}) / ${columnCount}))`
+        : minColumnWidth;
+    const repeatMode = columnCount ? 'auto-fill' : 'auto-fit';
+    const style = { gridTemplateColumns: `repeat(${repeatMode}, minmax(min(100%, ${columnWidth}), 1fr))` };
     return (_jsx("div", { className: cn('grid', gapClass, className), style: style, role: "region", "aria-label": config.ariaLabel ?? getLabel('contentGridRegion'), children: sections.map((section) => renderPanelSection(section, { wrapMode: sectionWrapMode })) }));
 };
 const ColumnsMode = ({ sections, config, className, sectionWrapMode }) => {
-    const columnCount = config.columnCount === 'auto' ? 2 : config.columnCount ?? 2;
     const gap = config.gap ?? 'md';
     const gapClass = GAP_CLASSES[gap];
     const getLabel = useContentSectionContainerLabel();
-    return (_jsx("div", { className: cn('columns-2', gapClass, className), style: { columnCount }, role: "region", "aria-label": config.ariaLabel ?? getLabel('contentColumnsRegion'), children: sections.map((section) => (_jsx("div", { className: cn('break-inside-avoid mb-field', sectionWrapMode === 'separator-only' && 'border-b pb-field last:border-b-0 last:pb-0'), children: renderPanelSection(section, { wrapMode: sectionWrapMode === 'separator-only' ? 'flat' : sectionWrapMode }) }, section.id))) }));
+    /*
+     * CSS multi-column with a minimum width: `columns: <count> <width>` is "at most <count> columns, none narrower
+     * than <width>", so a narrow container flows into fewer. `'auto'`, the documented default, sets the width alone
+     * and lets the container decide the count. The code used a fixed two columns whatever the width.
+     */
+    const columns = config.columnCount === 'auto' || config.columnCount === undefined
+        ? COLUMNS_MIN_WIDTH
+        : `${config.columnCount} ${COLUMNS_MIN_WIDTH}`;
+    return (_jsx("div", { className: cn(gapClass, className), style: { columns }, role: "region", "aria-label": config.ariaLabel ?? getLabel('contentColumnsRegion'), children: sections.map((section) => (_jsx("div", { className: cn('break-inside-avoid mb-field', sectionWrapMode === 'separator-only' && 'border-b pb-field last:border-b-0 last:pb-0'), children: renderPanelSection(section, { wrapMode: sectionWrapMode === 'separator-only' ? 'flat' : sectionWrapMode }) }, section.id))) }));
 };
+/**
+ * The tab a tab set shows, with the controlled/uncontrolled contract an OWNER can drive it through (deep links,
+ * cross-pane navigation): with `config.activeSection` present the owner's value renders and a selection is only
+ * REPORTED through `onSectionChange` (an owner that sets it and ignores the callback has frozen its tabs); without it
+ * the set keeps its own. Held here rather than inside Radix so the set can answer a reveal request.
+ */
+function useActiveTab(config, sections, onSectionChange) {
+    const [localActive, setLocalActive] = useState(config.defaultActive ?? sections[0]?.id);
+    const active = config.activeSection ?? localActive;
+    const select = (id) => {
+        setLocalActive(id);
+        onSectionChange?.(id);
+    };
+    const revealContainerId = useFieldRevealRequests((id) => {
+        if (id === active)
+            return false;
+        select(id);
+        return true;
+    });
+    return { active, select, revealContainerId };
+}
 const TabsMode = ({ sections, config, className, sectionWrapMode, onSectionChange }) => {
-    const defaultValue = config.defaultActive ?? sections[0]?.id;
     const getLabel = useContentSectionContainerLabel();
-    return (_jsxs(Tabs
-    /*
-     * Controlled when `config.activeSection` is present, uncontrolled otherwise — the standard
-     * Radix contract, exposed so an OWNER can drive the tab (deep links, cross-pane navigation).
-     * In the controlled shape every user click is only REPORTED through `onSectionChange`; an
-     * owner that sets `activeSection` and ignores the callback has frozen its tabs.
-     */
-    , { ...(config.activeSection !== undefined ? { value: config.activeSection } : { defaultValue }), className: className, onValueChange: (value) => onSectionChange?.(value), children: [_jsx(TabsList, { role: "tablist", "aria-label": config.ariaLabel ?? getLabel('sectionTabsNav'), children: sections.map((section) => (_jsxs(TabsTrigger, { value: section.id, disabled: section.disabled, role: "tab", "aria-controls": `panel-${section.id}`, ...(section.count !== undefined ? { count: section.count } : {}), ...(section.countTone !== undefined ? { countTone: section.countTone } : {}), children: [section.icon && _jsx("span", { className: "me-element", children: section.icon }), section.title] }, section.id))) }), sections.map((section) => (_jsx(TabsContent, { value: section.id, role: "tabpanel", id: `panel-${section.id}`, "aria-labelledby": section.id, 
-                // Radix unmounts inactive panels, so the active one mounts fresh on each
-                // switch — `animate-in fade-in-0` runs once per activation (a subtle
-                // cross-fade instead of an instant pop).
-                className: "animate-in fade-in-0 duration-[var(--motion-duration-fast)]", children: renderSectionContentChrome(section, section.content, sectionWrapMode) }, section.id)))] }));
+    const keepPanelsMounted = useKeepsHiddenPanelsMounted();
+    const { active, select, revealContainerId } = useActiveTab(config, sections, onSectionChange);
+    return (_jsxs(Tabs, { value: active, className: className, onValueChange: select, children: [_jsx(TabsList, { "aria-label": config.ariaLabel ?? getLabel('sectionTabsNav'), children: sections.map((section) => (_jsxs(TabsTrigger, { value: section.id, disabled: section.disabled, ...(section.count !== undefined ? { count: section.count } : {}), ...(section.countTone !== undefined ? { countTone: section.countTone } : {}), children: [section.icon && _jsx("span", { className: "me-element", children: section.icon }), section.title] }, section.id))) }), sections.map((section) => (_jsx(TabsContent, { value: section.id, ...(keepPanelsMounted ? { forceMount: true, hidden: section.id !== active } : {}), ...fieldRevealPanelAttributes(revealContainerId, section.id), 
+                // The active panel appears fresh on each switch (mounted outside a form, un-hidden inside one, and a CSS
+                // animation restarts when an element stops being `display: none`), so `animate-in fade-in-0` runs once per
+                // activation: a subtle cross-fade instead of an instant pop.
+                className: "animate-in fade-in-0 duration-[var(--motion-duration-fast)]", children: renderSectionContentChrome(section, _jsx(SectionPanelContent, { section: section }), sectionWrapMode) }, section.id)))] }));
 };
 /**
  * VERTICAL_TABS — side nav rail + content pane.
@@ -254,21 +315,53 @@ const TabsMode = ({ sections, config, className, sectionWrapMode, onSectionChang
  * Arrow-key navigation. The Tabs preset already styles `data-[orientation=vertical]`
  * as a left-aligned nav rail, so the look is preserved.
  */
+/**
+ * Below this width the rail sits ABOVE its panel instead of beside it: the default 12rem rail plus the 24rem a
+ * label-and-value row needs. Measured on the SSO policy in the Settings Hub at phone width (#2329): a 390px screen
+ * left the rail half the pane and its fields about 80px, wrapping "Require SSO" a word per line. Nothing collapsed
+ * the rail at any width. It is the CONTAINER that decides, not the viewport: the same section is narrow in a
+ * settings pane on a wide screen.
+ */
+const VERTICAL_TABS_STACKING_THRESHOLD_REM = 36;
+/** Whether the element is narrower than `thresholdRem`, re-measured as it resizes. False until measured, and where nothing can measure. */
+function useNarrowerThan(thresholdRem) {
+    const [element, setElement] = useState(null);
+    const [narrow, setNarrow] = useState(false);
+    useEffect(() => {
+        if (!element || typeof ResizeObserver === 'undefined')
+            return undefined;
+        const rootFontSize = Number.parseFloat(getComputedStyle(document.documentElement).fontSize) || 16;
+        const measure = (width) => setNarrow(width > 0 && width < thresholdRem * rootFontSize);
+        measure(element.getBoundingClientRect().width);
+        const observer = new ResizeObserver(([entry]) => { if (entry)
+            measure(entry.contentRect.width); });
+        observer.observe(element);
+        return () => observer.disconnect();
+    }, [element, thresholdRem]);
+    return [setElement, narrow];
+}
 const VerticalTabsMode = ({ sections, config, className, sectionWrapMode, onSectionChange }) => {
-    const defaultValue = config.defaultActive ?? sections[0]?.id;
     const getLabel = useContentSectionContainerLabel();
+    const keepPanelsMounted = useKeepsHiddenPanelsMounted();
+    const { active, select, revealContainerId } = useActiveTab(config, sections, onSectionChange);
     const navWidth = config.navWidth ?? 'w-48';
-    return (_jsxs(Tabs
-    /* Controlled/uncontrolled split — same contract as TabsMode above (the seam's home). */
-    , { ...(config.activeSection !== undefined ? { value: config.activeSection } : { defaultValue }), orientation: DisplayDirection.VERTICAL, 
-        /*
-         * `mt-field` — the rail and its panel start BELOW whatever introduces them. A vertical tab
-         * set is a navigation surface, not a paragraph: butted against the preceding content its
-         * first rail item read as one more line of that content rather than as the top of a
-         * different control. The horizontal set gets its separation for free from the strip's own
-         * bottom rule; this one has no such edge, so the space has to be declared.
-         */
-        className: cn('mt-field', className), onValueChange: (value) => onSectionChange?.(value), children: [_jsx(TabsList, { className: cn(navWidth, 'shrink-0 self-start border-e pe-card'), "aria-label": config.ariaLabel ?? getLabel('verticalTabsRegion'), children: sections.map((section) => (_jsxs(TabsTrigger, { value: section.id, disabled: section.disabled, ...(section.count !== undefined ? { count: section.count } : {}), ...(section.countTone !== undefined ? { countTone: section.countTone } : {}), children: [section.icon && _jsx("span", { className: "inline-flex items-center shrink-0", children: section.icon }), section.title] }, section.id))) }), sections.map((section) => (_jsx(TabsContent, { value: section.id, className: "min-w-0 flex-1 animate-in fade-in-0 duration-[var(--motion-duration-fast)]", children: renderSectionContentChrome(section, section.content, sectionWrapMode) }, section.id)))] }));
+    // In a narrow container the rail becomes the horizontal strip, which already scrolls and fades at its edges. The
+    // same `Tabs` instance changes orientation, so the open tab is kept, and Radix announces the orientation (and
+    // takes the arrow keys) that is actually on screen.
+    const [measureRef, stacked] = useNarrowerThan(VERTICAL_TABS_STACKING_THRESHOLD_REM);
+    return (_jsx("div", { ref: measureRef, className: "min-w-0", "data-vertical-tabs-stacked": stacked || undefined, children: _jsxs(Tabs
+        /* Controlled/uncontrolled split — same contract as TabsMode above (`useActiveTab`). */
+        , { 
+            /* Controlled/uncontrolled split — same contract as TabsMode above (`useActiveTab`). */
+            value: active, orientation: stacked ? DisplayDirection.HORIZONTAL : DisplayDirection.VERTICAL, 
+            /*
+             * `mt-field` — the rail and its panel start BELOW whatever introduces them. A vertical tab
+             * set is a navigation surface, not a paragraph: butted against the preceding content its
+             * first rail item read as one more line of that content rather than as the top of a
+             * different control. The horizontal set gets its separation for free from the strip's own
+             * bottom rule; this one has no such edge, so the space has to be declared.
+             */
+            className: cn('mt-field', className), onValueChange: select, children: [_jsx(TabsList, { className: stacked ? undefined : cn(navWidth, 'shrink-0 self-start border-e pe-card'), "aria-label": config.ariaLabel ?? getLabel('verticalTabsRegion'), children: sections.map((section) => (_jsxs(TabsTrigger, { value: section.id, disabled: section.disabled, ...(section.count !== undefined ? { count: section.count } : {}), ...(section.countTone !== undefined ? { countTone: section.countTone } : {}), children: [section.icon && _jsx("span", { className: "inline-flex items-center shrink-0", children: section.icon }), section.title] }, section.id))) }), sections.map((section) => (_jsx(TabsContent, { value: section.id, ...(keepPanelsMounted ? { forceMount: true, hidden: section.id !== active } : {}), ...fieldRevealPanelAttributes(revealContainerId, section.id), className: "min-w-0 flex-1 animate-in fade-in-0 duration-[var(--motion-duration-fast)]", children: renderSectionContentChrome(section, _jsx(SectionPanelContent, { section: section }), sectionWrapMode) }, section.id)))] }) }));
 };
 /**
  * PILLS — a horizontal nav tablist over a single content pane.
@@ -305,12 +398,19 @@ const PillsMode = ({ sections, config, className, sectionWrapMode, onSectionChan
     const tablistRef = useRef(null);
     // FILLED — the SAME recipe the vertical-tabs rail uses, so the two are coherent.
     const selectableRecipe = getRecipe(UIBehavior.SELECTABLE, SelectableVariant.FILLED);
+    const keepPanelsMounted = useKeepsHiddenPanelsMounted();
     const tabId = (id) => `${baseId}-tab-${id}`;
-    const panelId = `${baseId}-panel`;
+    const panelId = (id) => `${baseId}-panel-${id}`;
     const handleSectionChange = (id) => {
         setActiveSection(id);
         onSectionChange?.(id);
     };
+    const revealContainerId = useFieldRevealRequests((id) => {
+        if (id === activeSection)
+            return false;
+        handleSectionChange(id);
+        return true;
+    });
     // WAI-ARIA tabs keyboard model: Arrow keys move (and activate) among ENABLED
     // pills, wrapping at the ends; Home/End jump to first/last. Focus follows the
     // selection so the roving tabindex stays coherent.
@@ -337,15 +437,21 @@ const PillsMode = ({ sections, config, className, sectionWrapMode, onSectionChan
         tablistRef.current?.querySelector(`#${CSS.escape(tabId(nextId))}`)?.focus();
     };
     const activeContentSection = sections.find(s => s.id === activeSection);
+    /*
+     * One panel per pill, each labelled by its own pill. Outside a form only the active one renders (keyed by its id,
+     * so it mounts fresh and cross-fades on each switch); inside one every panel stays mounted and the others are hidden
+     * (`useKeepsHiddenPanelsMounted`).
+     */
+    const renderPanel = (section) => (_jsx("div", { role: "tabpanel", id: panelId(section.id), "aria-labelledby": tabId(section.id), tabIndex: 0, hidden: section.id !== activeSection, ...fieldRevealPanelAttributes(revealContainerId, section.id), className: cn("animate-in fade-in-0 duration-[var(--motion-duration-fast)]", focusIndicatorClasses(FocusIndicatorShape.INSET)), children: renderSectionContentChrome(section, _jsx(SectionPanelContent, { section: section }), sectionWrapMode) }, section.id));
     return (_jsxs("div", { className: cn('space-y-field', className), role: "region", "aria-label": config.ariaLabel ?? getLabel('pillNavigationRegion'), children: [_jsx("div", { ref: tablistRef, className: "flex flex-wrap items-center gap-item", role: "tablist", "aria-label": config.ariaLabel ?? getLabel('sectionTabsNav'), onKeyDown: handleKeyDown, children: sections.map((section) => {
                     const isActive = activeSection === section.id;
-                    return (_jsxs("button", { id: tabId(section.id), type: "button", role: "tab", "aria-selected": isActive, "aria-controls": panelId, "data-state": isActive ? 'active' : 'inactive', tabIndex: isActive ? 0 : -1, disabled: section.disabled, className: cn(
+                    return (_jsxs("button", { id: tabId(section.id), type: "button", role: "tab", "aria-selected": isActive, "aria-controls": panelId(section.id), "data-state": isActive ? 'active' : 'inactive', tabIndex: isActive ? 0 : -1, disabled: section.disabled, className: cn(
                         // Mirror the vertical rail item: FILLED recipe + rounded-md.
                         'inline-flex items-center gap-element rounded-md px-card-sm py-item font-medium', selectableRecipe.base, selectableRecipe.motion?.transition, selectableRecipe.states.focus, 
                         // Hover only when NOT active, so the hover tint can't override the
                         // selected fill on the active item.
                         !isActive && selectableRecipe.states.hover, isActive && selectableRecipe.states.selected, section.disabled && 'opacity-[var(--opacity-disabled)] cursor-not-allowed'), onClick: () => handleSectionChange(section.id), children: [section.icon && _jsx("span", { className: "inline-flex items-center shrink-0", children: section.icon }), section.title] }, section.id));
-                }) }), _jsx("div", { role: "tabpanel", id: panelId, "aria-labelledby": tabId(activeSection), tabIndex: 0, className: "animate-in fade-in-0 duration-[var(--motion-duration-fast)]", children: activeContentSection && renderSectionContentChrome(activeContentSection, activeContentSection.content, sectionWrapMode) }, activeSection)] }));
+                }) }), keepPanelsMounted ? sections.map(renderPanel) : activeContentSection && renderPanel(activeContentSection)] }));
 };
 const AccordionMode = ({ sections, config, className, sectionWrapMode, onSectionChange }) => {
     const defaultValue = config.defaultExpanded ?? [sections[0]?.id];
@@ -354,50 +460,90 @@ const AccordionMode = ({ sections, config, className, sectionWrapMode, onSection
     // stack of independent EXPANDABLE toggles — the two modes lost their semantic
     // distinction. Multi-open stays available via explicit `allowMultiple: true`.
     const allowMultiple = config.allowMultiple ?? false;
-    const accordionItems = sections.map((section) => (_jsxs(AccordionItem, { value: section.id, disabled: section.disabled, children: [_jsx(AccordionTrigger, { className: cn(section.disabled && 'opacity-[var(--opacity-disabled)] cursor-not-allowed'), children: _jsxs("span", { className: "flex items-center gap-item-xs", children: [section.icon && _jsx("span", { className: "inline-flex items-center shrink-0", children: section.icon }), section.title] }) }), _jsx(AccordionContent, { children: renderSectionContentChrome(section, _jsxs(_Fragment, { children: [section.description && (_jsx("p", { className: "text-sm text-muted-foreground mb-field", children: section.description })), section.content] }), sectionWrapMode) })] }, section.id)));
+    const keepPanelsMounted = useKeepsHiddenPanelsMounted();
+    const { getRecipe } = useUI();
+    const sectionTitleClassName = sectionHeadingClassName(getRecipe);
+    // The open rows, held here rather than inside Radix so a reveal request can open the row holding a field.
+    const [openItems, setOpenItems] = useState(allowMultiple ? defaultValue : defaultValue.slice(0, 1));
+    const changeOpenItems = (next) => {
+        setOpenItems(next);
+        onSectionChange?.(allowMultiple ? next : (next[0] ?? ''));
+    };
+    const revealContainerId = useFieldRevealRequests((id) => {
+        if (openItems.includes(id))
+            return false;
+        changeOpenItems(allowMultiple ? [...openItems, id] : [id]);
+        return true;
+    });
+    const accordionItems = sections.map((section) => (_jsxs(AccordionItem, { value: section.id, disabled: section.disabled, children: [_jsx(AccordionTrigger, { className: cn(section.disabled && 'opacity-[var(--opacity-disabled)] cursor-not-allowed'), children: _jsxs("span", { className: cn('flex items-center gap-element', sectionTitleClassName), children: [section.icon && _jsx("span", { className: "inline-flex items-center shrink-0", children: section.icon }), section.title] }) }), _jsx(AccordionContent, { ...(keepPanelsMounted ? { forceMount: true, hidden: !openItems.includes(section.id) } : {}), ...fieldRevealPanelAttributes(revealContainerId, section.id), children: renderSectionContentChrome(section, _jsx(SectionPanelContent, { section: section }), 'flat') })] }, section.id)));
     if (allowMultiple) {
-        return (_jsx(Accordion, { type: ToggleGroupType.MULTIPLE, defaultValue: defaultValue, className: className, onValueChange: (value) => onSectionChange?.(value), children: accordionItems }));
+        return (_jsx(Accordion, { type: ToggleGroupType.MULTIPLE, value: openItems, className: className, onValueChange: (value) => changeOpenItems(value), children: accordionItems }));
     }
-    return (_jsx(Accordion, { type: ToggleGroupType.SINGLE, defaultValue: defaultValue[0], className: className, collapsible: true, onValueChange: (value) => onSectionChange?.(value), children: accordionItems }));
+    return (_jsx(Accordion, { type: ToggleGroupType.SINGLE, value: openItems[0] ?? '', className: className, collapsible: true, onValueChange: (value) => changeOpenItems(value ? [value] : []), children: accordionItems }));
 };
+/** COLLAPSIBLE folds every section at once, so it has a single panel. */
+const COLLAPSIBLE_PANEL_ID = 'all';
 const CollapsibleMode = ({ sections, config, className, sectionWrapMode }) => {
     const [isOpen, setIsOpen] = useState(true);
     const getLabel = useContentSectionContainerLabel();
     const openLabel = config.triggerLabel?.open ?? getLabel('accordionCollapseAll');
     const closedLabel = config.triggerLabel?.closed ?? getLabel('accordionExpandAll');
     const sectionCountLabel = getLabel('accordionSectionCount', { count: sections.length });
-    return (_jsxs(Collapsible, { open: isOpen, onOpenChange: setIsOpen, className: className, children: [_jsxs("div", { className: "flex items-center justify-between", children: [_jsx("h3", { className: "font-semibold", children: sectionCountLabel }), _jsx(CollapsibleTrigger, { asChild: true, children: _jsx(Button, { variant: ButtonVariants_Variant.GHOST, size: ButtonSize.SM, "aria-expanded": isOpen, children: isOpen ? openLabel : closedLabel }) })] }), _jsx(CollapsibleContent, { className: "space-y-field mt-field", children: sections.map((section) => renderPanelSection(section, { titleTag: 'h4', wrapMode: sectionWrapMode })) })] }));
+    const keepPanelsMounted = useKeepsHiddenPanelsMounted();
+    const revealContainerId = useFieldRevealRequests(() => {
+        if (isOpen)
+            return false;
+        setIsOpen(true);
+        return true;
+    });
+    return (_jsxs(Collapsible, { open: isOpen, onOpenChange: setIsOpen, className: className, children: [_jsxs("div", { className: "flex items-center justify-between", children: [_jsx("h3", { className: "font-semibold", children: sectionCountLabel }), _jsx(CollapsibleTrigger, { asChild: true, children: _jsx(Button, { type: "button", variant: ButtonVariants_Variant.GHOST, size: ButtonSize.SM, "aria-expanded": isOpen, children: isOpen ? openLabel : closedLabel }) })] }), _jsx(CollapsibleContent, { className: "space-y-field mt-field", ...(keepPanelsMounted ? { forceMount: true, hidden: !isOpen } : {}), ...fieldRevealPanelAttributes(revealContainerId, COLLAPSIBLE_PANEL_ID), children: sections.map((section) => renderPanelSection(section, { titleTag: 'h4', wrapMode: sectionWrapMode })) })] }));
 };
+/** The panel EXPANDABLE folds behind "show more": every section past the first `initialVisibleCount`. */
+const EXPANDABLE_FOLDED_PANEL_ID = 'folded';
 const ExpandableMode = ({ sections, config, className, sectionWrapMode }) => {
-    const initialCount = config.initialVisibleCount ?? 3;
+    const initialCount = config.initialVisibleCount ?? DEFAULT_EXPANDABLE_INITIAL_VISIBLE_COUNT;
     const [showAll, setShowAll] = useState(false);
     const getLabel = useContentSectionContainerLabel();
     const visibleSections = showAll ? sections : sections.slice(0, initialCount);
     const hiddenCount = sections.length - initialCount;
     const showMoreLabel = config.showMoreLabel ?? getLabel('expandableShowMore', { count: hiddenCount });
     const showLessLabel = config.showLessLabel ?? getLabel('expandableShowLess');
-    return (_jsxs("div", { className: cn('space-y-field', className), children: [visibleSections.map((section) => renderPanelSection(section, { wrapMode: sectionWrapMode })), hiddenCount > 0 && (_jsx(Button, { variant: ButtonVariants_Variant.OUTLINE, className: "w-full", onClick: () => setShowAll(!showAll), "aria-expanded": showAll, children: showAll ? showLessLabel : showMoreLabel }))] }));
+    const keepPanelsMounted = useKeepsHiddenPanelsMounted();
+    const { renderIcon } = useIconRegistry();
+    const revealContainerId = useFieldRevealRequests(() => {
+        if (showAll)
+            return false;
+        setShowAll(true);
+        return true;
+    });
+    return (_jsxs("div", { className: cn('flex flex-col gap-field', className), children: [keepPanelsMounted ? (_jsxs(_Fragment, { children: [sections.slice(0, initialCount).map((section) => renderPanelSection(section, { wrapMode: sectionWrapMode })), hiddenCount > 0 && (_jsx("div", { className: "flex flex-col gap-field", hidden: !showAll, ...fieldRevealPanelAttributes(revealContainerId, EXPANDABLE_FOLDED_PANEL_ID), children: sections.slice(initialCount).map((section) => renderPanelSection(section, { wrapMode: sectionWrapMode })) }))] })) : (visibleSections.map((section) => renderPanelSection(section, { wrapMode: sectionWrapMode }))), hiddenCount > 0 && (
+            /*
+             * A quiet disclosure control under the last visible section, sized to its words: the full-width outline bar it
+             * was read as the heaviest thing in the group. The chevron says which way it goes.
+             */
+            _jsxs(Button, { type: "button", variant: ButtonVariants_Variant.GHOST, size: ButtonSize.SM, className: "self-start", onClick: () => setShowAll(!showAll), "aria-expanded": showAll, children: [showAll ? showLessLabel : showMoreLabel, renderIcon(showAll ? StandardIconReference.CHEVRON_UP : StandardIconReference.CHEVRON_DOWN, { size: IconSize.SM })] }))] }));
 };
+/**
+ * STEPPER — a guided sequence, one section at a time.
+ *
+ * Drawn with the framework's `Stepper`, the same one a form wizard uses, so a section stepper and a wizard look and
+ * behave as one thing (a hand-drawn second stepper diverged in glyph, state and focus). A step a person may go to
+ * is a button; a step holding nothing selectable yet is not. There is no "Complete" on the last step: a section
+ * stepper completes nothing (a form's own submit does that), and the button it showed was always disabled.
+ */
 const StepperMode = ({ sections, config, className, sectionWrapMode, onSectionChange }) => {
     const [currentStep, setCurrentStep] = useState(0);
     const getLabel = useContentSectionContainerLabel();
     const progressNavId = useId();
-    const orientation = config.orientation ?? 'horizontal';
-    // The numbered step indicators (filled circles + connectors) ALREADY communicate
-    // progress, so the separate linear progress bar is redundant by default — a
-    // double indicator for the same state. Opt in via `config.showProgress` only.
+    const orientation = config.orientation ?? DisplayDirection.HORIZONTAL;
+    // The numbered step indicators ALREADY communicate progress, so the separate linear progress bar is redundant
+    // by default — a double indicator for the same state. Opt in via `config.showProgress` only.
     const showProgress = config.showProgress ?? false;
     const allowSkip = config.allowSkip ?? false;
-    const completedIcon = config.completedIcon ?? '✓';
     const nextLabel = config.nextLabel ?? getLabel('stepperNext');
     const previousLabel = config.previousLabel ?? getLabel('stepperPrevious');
-    const completeLabel = config.completeLabel ?? getLabel('stepperComplete');
-    // Single source of truth for "can the user jump to this step?" — used for BOTH
-    // the disabled state AND the click handler. Previously the two disagreed: a step
-    // could render ENABLED (`index <= currentStep + 1`) yet the handler silently
-    // rejected the click (it only accepted STRICTLY adjacent steps), so e.g. jumping
-    // back to step 1 from step 3 was a dead control. Users may revisit any completed
-    // step and advance one step ahead; `allowSkip` unlocks arbitrary jumps.
+    // Single source of truth for "can the user go to this step?": any visited step and the next one; `allowSkip`
+    // unlocks every step.
     const canNavigate = (index) => allowSkip || index <= currentStep + 1;
     const handleStepChange = (index) => {
         if (index < 0 || index >= sections.length)
@@ -407,13 +553,19 @@ const StepperMode = ({ sections, config, className, sectionWrapMode, onSectionCh
         setCurrentStep(index);
         onSectionChange?.(sections[index].id);
     };
+    const keepPanelsMounted = useKeepsHiddenPanelsMounted();
+    // A field that must be shown takes the stepper to its step, whatever `canNavigate` says: it is where the repair is.
+    const revealContainerId = useFieldRevealRequests((id) => {
+        const index = sections.findIndex((section) => section.id === id);
+        if (index < 0 || index === currentStep)
+            return false;
+        setCurrentStep(index);
+        onSectionChange?.(id);
+        return true;
+    });
     const currentSection = sections[currentStep];
-    return (_jsxs("div", { className: cn('space-y-section', className), children: [_jsx("nav", { id: progressNavId, className: cn('flex', orientation === 'horizontal' ? 'flex-row gap-field' : 'flex-col gap-element'), "aria-label": config.ariaLabel ?? getLabel('stepperProgressNav'), children: sections.map((section, index) => {
-                    const isCompleted = index < currentStep;
-                    const isCurrent = index === currentStep;
-                    const isClickable = canNavigate(index);
-                    return (_jsxs("button", { type: "button", onClick: () => handleStepChange(index), disabled: !isClickable, className: cn('flex items-center gap-element', orientation === 'horizontal' ? 'flex-1' : '', !isClickable && 'cursor-not-allowed opacity-[var(--opacity-disabled)]'), "aria-current": isCurrent ? 'step' : undefined, children: [_jsx("div", { className: cn('w-8 h-8 rounded-full flex items-center justify-center text-sm font-medium border-2', isCompleted && 'bg-primary text-primary-foreground border-primary', isCurrent && 'border-primary text-primary', !isCompleted && !isCurrent && 'border-muted-foreground/30'), children: isCompleted ? completedIcon : index + 1 }), _jsx("span", { className: cn('text-sm', isCurrent && 'font-medium', !isCurrent && !isCompleted && 'text-muted-foreground'), children: section.title }), orientation === 'horizontal' && index < sections.length - 1 && (_jsx("div", { className: cn('flex-1 h-0.5', isCompleted ? 'bg-primary' : 'bg-muted-foreground/30') }))] }, section.id));
-                }) }), showProgress && (_jsx("div", { className: "w-full bg-muted rounded-full h-2", children: _jsx("div", { className: "bg-primary h-2 rounded-full transition-[width]", style: { width: `${((currentStep + 1) / sections.length) * 100}%` }, role: "progressbar", "aria-labelledby": progressNavId, "aria-valuenow": currentStep + 1, "aria-valuemin": 1, "aria-valuemax": sections.length }) })), currentSection && (_jsx("div", { className: "animate-in fade-in-0 duration-[var(--motion-duration-fast)]", children: renderSectionContentChrome(currentSection, currentSection.content, sectionWrapMode) }, currentSection.id)), _jsxs("div", { className: "flex justify-between", children: [_jsx(Button, { variant: ButtonVariants_Variant.OUTLINE, onClick: () => handleStepChange(currentStep - 1), disabled: currentStep === 0, children: previousLabel }), _jsx(Button, { onClick: () => handleStepChange(currentStep + 1), disabled: currentStep === sections.length - 1, children: currentStep === sections.length - 1 ? completeLabel : nextLabel })] })] }));
+    const renderStepPanel = (section, index) => (_jsx("div", { hidden: index !== currentStep, ...fieldRevealPanelAttributes(revealContainerId, section.id), className: "animate-in fade-in-0 duration-[var(--motion-duration-fast)]", children: renderSectionContentChrome(section, _jsx(SectionPanelContent, { section: section }), sectionWrapMode) }, section.id));
+    return (_jsxs("div", { className: cn('flex flex-col gap-section', className), children: [_jsx("nav", { id: progressNavId, "aria-label": config.ariaLabel ?? getLabel('stepperProgressNav'), children: _jsx(Stepper, { currentStep: currentStep, totalSteps: sections.length, orientation: orientation, onStepSelect: handleStepChange, isStepSelectable: (index) => index !== currentStep && canNavigate(index), ...(config.completedIcon !== undefined ? { completedIcon: config.completedIcon } : {}), role: "list", children: sections.map((section, index) => (_jsxs(React.Fragment, { children: [_jsxs(StepperItem, { step: index, role: "listitem", "aria-current": index === currentStep ? 'step' : undefined, children: [_jsx(StepperIndicator, { step: index, "aria-hidden": "true" }), _jsx(StepperTitle, { step: index, children: section.title })] }), index < sections.length - 1 && _jsx(StepperSeparator, { step: index, "aria-hidden": "true" })] }, section.id))) }) }), showProgress && (_jsx("div", { className: "w-full bg-muted rounded-full h-2", children: _jsx("div", { className: "bg-primary h-2 rounded-full transition-[width]", style: { width: `${((currentStep + 1) / sections.length) * 100}%` }, role: "progressbar", "aria-labelledby": progressNavId, "aria-valuenow": currentStep + 1, "aria-valuemin": 1, "aria-valuemax": sections.length }) })), _jsxs("div", { className: "flex flex-col gap-field", children: [keepPanelsMounted ? sections.map(renderStepPanel) : currentSection && renderStepPanel(currentSection, currentStep), _jsxs("div", { className: "flex justify-between", children: [_jsx(Button, { type: "button", variant: ButtonVariants_Variant.OUTLINE, onClick: () => handleStepChange(currentStep - 1), disabled: currentStep === 0, children: previousLabel }), currentStep < sections.length - 1 && (_jsx(Button, { type: "button", onClick: () => handleStepChange(currentStep + 1), children: nextLabel }))] })] })] }));
 };
 const TimelineMode = ({ sections, config, className, sectionWrapMode }) => {
     const getLabel = useContentSectionContainerLabel();