@jetbrains/ring-ui 7.0.121 → 7.0.122

package/components/collapse/collapse-content.d.ts

@@ -1,5 +1,12 @@
 import React, { type PropsWithChildren } from 'react';
 interface Props {
+    /**
+     * Height of the always-visible preview of the collapsed content.
+     * The collapsed subtree is inert until expanded, matching `aria-expanded`.
+     * The preview is only a visual clip of that subtree, so it is inert too and
+     * assistive technology will not perceive it — if the preview carries essential
+     * information, expose an accessible summary outside the collapsed content.
+     */
     minHeight?: number;
     className?: string;
     'data-test'?: string | null | undefined;

package/components/collapse/collapse-content.js

@@ -10,11 +10,21 @@ const DURATION_FACTOR = 0.5;
 const DEFAULT_HEIGHT = 0;
 const VISIBLE = 1;
 const HIDDEN = 0;
+// margin for the hide fallback timer, so it fires only if transitionend never did
+const HIDE_FALLBACK_EXTRA_DELAY = 100;
+// React 18 renders unknown attributes from strings only, while React 19 treats `inert`
+// as a real boolean and removes the attribute when it gets ''
+// TODO drop the React 18 branch in develop-8.0 — Ring UI 8.0 supports React 19 only
+const REACT_MAJOR_WITH_INERT_SUPPORT = 19;
+const getInertAttributeValue = (reactMajor) => reactMajor >= REACT_MAJOR_WITH_INERT_SUPPORT ? true : '';
+// the cast is confined to the JSX assignment: React 18 actually receives the string form
+const INERT = getInertAttributeValue(Number(React.version.split('.')[0]));
+const isFullyCollapsed = (collapsed, initialContentHeight) => collapsed && initialContentHeight <= DEFAULT_HEIGHT;
 /**
  * @name CollapseContent
  */
 export const CollapseContent = ({ children, minHeight = DEFAULT_HEIGHT, 'data-test': dataTest, }) => {
-    const { collapsed, duration, id, disableAnimation } = useContext(CollapseContext);
+    const { collapsed, duration, id, disableAnimation, keepMounted } = useContext(CollapseContext);
     const containerRef = useRef(null);
     const contentRef = useRef(null);
     const [initialContentHeight] = useState(minHeight);
@@ -23,20 +33,42 @@ export const CollapseContent = ({ children, minHeight = DEFAULT_HEIGHT, 'data-te
     const height = toPx(nextHeight);
     const [shouldHideContent, setShouldHideContent] = useState(collapsed && minHeight <= DEFAULT_HEIGHT);
     useEffect(() => {
-        function onTransitionEnd() {
+        const container = containerRef.current;
+        function finalizeCollapse() {
             if (initialContentHeight <= DEFAULT_HEIGHT) {
                 setShouldHideContent(collapsed);
             }
         }
-        const container = containerRef.current;
+        function onTransitionEnd(event) {
+            // transitionend bubbles: only the container's own height transition finalizes the collapse
+            if (event.target === container && event.propertyName === 'height') {
+                finalizeCollapse();
+            }
+        }
         container?.addEventListener('transitionend', onTransitionEnd);
+        // fallback for suppressed or cancelled transitions (e.g. `transition: none` overrides),
+        // which emit no transitionend and would otherwise leave the content interactive forever.
+        // Armed once per collapse toggle from the --duration committed to the DOM — the value
+        // the running transition actually uses — so it can neither undercut a transition started
+        // from a stale height nor be restarted by content resizes or duration changes mid-collapse
+        // TODO merge with global/parse-css-duration when this lands in develop-8.0
+        const cssDuration = parseFloat(container?.style.getPropertyValue('--duration') || '') || 0;
+        const fallbackTimeout = window.setTimeout(finalizeCollapse, cssDuration + HIDE_FALLBACK_EXTRA_DELAY);
         return () => {
             container?.removeEventListener('transitionend', onTransitionEnd);
+            window.clearTimeout(fallbackTimeout);
         };
     }, [collapsed, initialContentHeight]);
+    // render-phase state adjustments (not effects): the React Compiler lint forbids
+    // setState-in-effect, and https://react.dev/learn/you-might-not-need-an-effect
+    // documents this pattern for resetting state when props change
     if (!collapsed && shouldHideContent) {
         setShouldHideContent(false);
     }
+    // without a transition there is no transitionend to wait for, so hide immediately
+    if (disableAnimation && !shouldHideContent && isFullyCollapsed(collapsed, initialContentHeight)) {
+        setShouldHideContent(true);
+    }
     useEffect(() => {
         if (contentRef.current) {
             const observer = new ResizeObserver(() => {
@@ -52,10 +84,20 @@ export const CollapseContent = ({ children, minHeight = DEFAULT_HEIGHT, 'data-te
         opacity: collapsed && !minHeight ? HIDDEN : VISIBLE,
     };
     const fadeShouldBeVisible = Boolean(minHeight && collapsed);
-    const shouldRenderContent = disableAnimation ? !collapsed : !shouldHideContent;
+    const contentVisible = !shouldHideContent;
+    const contentHidden = Boolean(keepMounted) && !contentVisible;
+    // interaction is blocked as soon as the panel collapses (matching aria-expanded), while
+    // visibility waits for the animation to finish so the content stays painted meanwhile.
+    // This includes a minHeight preview: content clipped below it must not take focus,
+    // and inert cannot be applied any more granularly than to the whole subtree
+    const contentInert = collapsed;
     return (<div ref={containerRef} id={`collapse-content-${id}`} data-test={dataTests(COLLAPSE_CONTENT_CONTAINER_TEST_ID)} className={classNames(styles.container, { [styles.transition]: !disableAnimation })} style={style}>
-      <div ref={contentRef} data-test={dataTests(COLLAPSE_CONTENT_TEST_ID, dataTest)}>
-        {shouldRenderContent ? children : null}
+      <div ref={contentRef} data-test={dataTests(COLLAPSE_CONTENT_TEST_ID, dataTest)} 
+    // visibility: hidden removes the fully collapsed content from the tab order and accessibility
+    // tree, but descendants can override it with visibility: visible — inert cannot be escaped.
+    // Both are rendered in JSX so server-rendered collapsed markup is protected before hydration.
+    style={contentHidden ? { visibility: 'hidden' } : undefined} inert={contentInert ? INERT : undefined}>
+        {keepMounted || contentVisible ? children : null}
       </div>
       {fadeShouldBeVisible && <div className={styles.fade}/>}
     </div>);

package/components/collapse/collapse-context.d.ts

@@ -2,6 +2,7 @@ interface CollapseContextInterface {
     collapsed: boolean;
     duration: number;
     disableAnimation: boolean;
+    keepMounted?: boolean;
     setCollapsed: () => void;
     id: string;
 }

package/components/collapse/collapse-context.js

@@ -4,6 +4,7 @@ export const CollapseContext = createContext({
     collapsed: true,
     duration: BASE_ANIMATION_DURATION,
     disableAnimation: false,
+    keepMounted: false,
     setCollapsed: () => { },
     id: '',
 });

package/components/collapse/collapse.d.ts

@@ -4,6 +4,15 @@ interface Props {
     onChange?: (collapsed: boolean) => void;
     duration?: number;
     disableAnimation?: boolean;
+    /**
+     * Keep children mounted while collapsed (hidden via `visibility: hidden`
+     * and the `inert` attribute) instead of unmounting them, preserving their state.
+     * Note: hidden form controls still participate in form validation
+     * and submission — disable them while collapsed if needed.
+     * Content rendered through portals (e.g. Popup) escapes the hidden
+     * wrapper and is not hidden — close overlays on collapse.
+     */
+    keepMounted?: boolean;
     className?: string;
     defaultCollapsed?: boolean;
     collapsed?: boolean | null;

package/components/collapse/collapse.js

@@ -5,7 +5,7 @@ import { BASE_ANIMATION_DURATION } from './consts';
 /**
  * @name Collapse
  */
-export const Collapse = ({ children, duration = BASE_ANIMATION_DURATION, disableAnimation = false, className = '', onChange = () => { }, defaultCollapsed = true, collapsed = null, }) => {
+export const Collapse = ({ children, duration = BASE_ANIMATION_DURATION, disableAnimation = false, keepMounted = false, className = '', onChange = () => { }, defaultCollapsed = true, collapsed = null, }) => {
     const [innerCollapsed, setInnerCollapsed] = useState(defaultCollapsed);
     const id = useId();
     const finalCollapsedValue = collapsed ?? innerCollapsed;
@@ -19,6 +19,7 @@ export const Collapse = ({ children, duration = BASE_ANIMATION_DURATION, disable
             setCollapsed,
             duration,
             disableAnimation,
+            keepMounted,
             id,
         }}>
         {children}

package/components/collapsible-group/collapsible-group.css

@@ -37,6 +37,12 @@
   height: 28px;
 }
 
+.heading {
+  margin: 0;
+
+  font: inherit;
+}
+
 .headerButton {
   display: block;
 

package/components/collapsible-group/collapsible-group.d.ts

@@ -10,6 +10,19 @@ export interface CollapsibleGroupProps {
     onChange?: (expanded: boolean) => void;
     disableAnimation?: boolean;
     interactive?: boolean;
+    /**
+     * Keep children mounted while collapsed (hidden via `visibility: hidden`
+     * and the `inert` attribute) instead of unmounting them, preserving their state.
+     * Note: hidden form controls still participate in form validation
+     * and submission — disable them while collapsed if needed.
+     * Content rendered through portals (e.g. Popup) escapes the hidden
+     * wrapper and is not hidden — close overlays on collapse.
+     */
+    keepMounted?: boolean;
+    /**
+     * Wraps the header in an <h2>–<h6> to keep the document outline.
+     */
+    headingLevel?: 2 | 3 | 4 | 5 | 6;
     'data-test'?: string | null | undefined;
 }
 declare const CollapsibleGroup: React.ForwardRefExoticComponent<CollapsibleGroupProps & React.RefAttributes<HTMLDivElement>>;

package/components/collapsible-group/collapsible-group.js

@@ -36,7 +36,7 @@ function CollapsibleGroupHeaderStatic({ avatar, titleContent, subtitle }) {
       <CollapsibleGroupHeaderContent avatar={avatar} titleContent={titleContent} subtitle={subtitle}/>
     </span>);
 }
-const CollapsibleGroup = forwardRef(({ avatar, title, subtitle, children, className, defaultExpanded = false, expanded = null, onChange = () => { }, disableAnimation = false, interactive = true, 'data-test': dataTest, }, ref) => {
+const CollapsibleGroup = forwardRef(({ avatar, title, subtitle, children, className, defaultExpanded = false, expanded = null, onChange = () => { }, disableAnimation = false, interactive = true, keepMounted = false, headingLevel, 'data-test': dataTest, }, ref) => {
     const [innerExpanded, setInnerExpanded] = useState(defaultExpanded);
     const [hovered, setHovered] = useState(false);
     const [focused, setFocused] = useState(false);
@@ -60,9 +60,10 @@ const CollapsibleGroup = forwardRef(({ avatar, title, subtitle, children, classN
         [styles.expanded]: isExpanded,
         [styles.focused]: focused,
     });
+    const header = interactive ? (<CollapsibleGroupHeader avatar={avatar} titleContent={title} subtitle={subtitle} onMouseEnter={() => setHovered(true)} onMouseLeave={() => setHovered(false)} onFocus={() => setFocused(true)} onBlur={onBlur}/>) : (<CollapsibleGroupHeaderStatic avatar={avatar} titleContent={title} subtitle={subtitle}/>);
     return (<div ref={ref} className={classes} data-test={dataTest}>
-        <Collapse defaultCollapsed={!defaultExpanded} collapsed={expanded == null ? null : !expanded} onChange={handleChange} disableAnimation={disableAnimation} className={styles.collapseRoot}>
-          {interactive ? (<CollapsibleGroupHeader avatar={avatar} titleContent={title} subtitle={subtitle} onMouseEnter={() => setHovered(true)} onMouseLeave={() => setHovered(false)} onFocus={() => setFocused(true)} onBlur={onBlur}/>) : (<CollapsibleGroupHeaderStatic avatar={avatar} titleContent={title} subtitle={subtitle}/>)}
+        <Collapse defaultCollapsed={!defaultExpanded} collapsed={expanded == null ? null : !expanded} onChange={handleChange} disableAnimation={disableAnimation} keepMounted={keepMounted} className={styles.collapseRoot}>
+          {headingLevel != null ? React.createElement(`h${headingLevel}`, { className: styles.heading }, header) : header}
           <CollapseContent>
             <div className={styles.body}>{children}</div>
           </CollapseContent>

package/components/expand/collapsible-group.css

@@ -27,6 +27,10 @@
   composes: header from '../collapsible-group/collapsible-group.css';
 }
 
+.heading {
+  composes: heading from '../collapsible-group/collapsible-group.css';
+}
+
 .headerButton {
   composes: headerButton from '../collapsible-group/collapsible-group.css';
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jetbrains/ring-ui",
-  "version": "7.0.121",
+  "version": "7.0.122",
   "description": "JetBrains UI library",
   "author": {
     "name": "JetBrains"