@juwel-development/design-system 4.1.0 → 4.2.0

package/src/Layout/Dialog/Dialog.tsx

@@ -15,14 +15,25 @@ import {
 import type { Subject } from 'rxjs';
 import { DialogCompositionError } from './DialogCompositionError';
 import { DialogNamingError } from './DialogNamingError';
+import { useDialogAllocation } from './useDialogAllocation';
+import { useModalScrollLock } from './useModalScrollLock';
 
 // The layout classes ride the open: variant - a bare `flex` would defeat the UA's
 // dialog:not([open]) hiding. Tailwind's preflight zeroes the UA's centering margins (m-auto
 // restores them) and strips ::backdrop, so the Scrim colour and blur are declared here.
-// overflow-hidden overrides the UA's `dialog { overflow: auto }` - Content or its delegated child owns scrolling.
+// Content or its delegated child owns scrolling while usable; insufficient height releases the whole task.
 const dialogRoot = cva(
   [
     'open:flex open:flex-col m-auto p-0 overflow-hidden',
+    '[&[data-dialog-unusable]]:overflow-auto [&[data-dialog-unusable]]:[--_scroll-released:1]',
+    '[&[data-dialog-unusable]]:scroll-p-[calc(var(--focus-ring-width)+var(--focus-ring-offset))]',
+    '[&[data-dialog-unusable]>*]:shrink-0',
+    '[&[data-dialog-unusable]>[data-dialog-member=content]]:flex-none',
+    '[&[data-dialog-unusable]>[data-dialog-member=content]]:overflow-visible',
+    '[&[data-dialog-unusable]>[data-dialog-member=content]>*]:h-auto',
+    '[&[data-dialog-unusable]_div:has(>table)]:max-h-none',
+    '[&[data-dialog-unusable]_div:has(>table)]:overflow-visible',
+    '[&[data-dialog-unusable]_thead]:static',
     'bg-surface text-foreground',
     'rounded-[var(--radius-dialog)] shadow-[var(--elevation-floating)]',
     'backdrop:bg-scrim backdrop:[backdrop-filter:blur(var(--scrim-blur))]',
@@ -50,14 +61,14 @@ const dialogRoot = cva(
 // followed by a Description hands the region's bottom padding to it.
 const dialogTitle = cva(
   [
-    'px-[var(--space-region)] pt-[var(--space-region)] pb-[var(--space-region)]',
+    'shrink-0 px-[var(--space-region)] pt-[var(--space-region)] pb-[var(--space-region)]',
     '[&:has(+[data-dialog-member=description])]:pb-0',
   ].join(' '),
 );
 
 const dialogDescription = cva(
   [
-    'px-[var(--space-region)] pt-[var(--space-region)] pb-[var(--space-region)]',
+    'shrink-0 px-[var(--space-region)] pt-[var(--space-region)] pb-[var(--space-region)]',
     '[[data-dialog-member=title]+&]:mt-[var(--space-stack)] [[data-dialog-member=title]+&]:pt-0',
   ].join(' '),
 );
@@ -202,6 +213,8 @@ const DialogRoot: FunctionComponent<IDialogRootProps> = ({
 }) => {
   const baseId = useId();
   const dialogRef = useRef<HTMLDialogElement | undefined>(undefined);
+  const isUnusable = useDialogAllocation(dialogRef);
+  useModalScrollLock(dialogRef);
   // What the component believes about its own presentation. The close handler reads it to tell a
   // platform-initiated close (form method="dialog") - which must synchronize the Subject - from a
   // close the component performed itself, which must not re-emit.
@@ -318,6 +331,7 @@ const DialogRoot: FunctionComponent<IDialogRootProps> = ({
       <dialog
         ref={attachDialog}
         className={dialogRoot({ extent })}
+        data-dialog-unusable={isUnusable || undefined}
         aria-label={ariaLabel}
         aria-labelledby={
           ariaLabel === undefined && nameParts.title
@@ -451,9 +465,14 @@ const DialogActions: FunctionComponent<IDialogActionsProps> = ({
  * - `extent="screen"` (the default) fills the viewport minus the `--gutter` inline and
  *   `--space-region` block insets, header and Actions fixed, only `Content` scrolling.
  *   `extent="content"` holds a fixed 32rem capped to the viewport with content-driven height;
- *   Default `Content` scrolls as the fallback when its content exceeds available space.
+ *   Default `Content` owns overflow while a usable viewport fits.
  * - `Content scrollOwner="child"` passes available height to one bounded child without scrolling.
- *   A bounded Table then owns both axes and pins its header; title, description and actions stay fixed.
+ *   A bounded Table, directly or through Pane's child-owned Body, owns both axes and pins its header;
+ *   title, description, Pane.Foot summary and actions stay fixed while they and a complete row fit.
+ * - When fixed regions plus a complete row/control or text line and focus room cannot fit, the
+ *   whole task scrolls in Dialog. Content and Table contribute no separate scroll region and the
+ *   Table header is released. Bounds restore on resize or content changes without remounting.
+ *   The background document is locked while presented; its prior overflow is restored on close.
  * - Regions take `--space-region` padding with `--space-stack` between Title and Description and
  *   between Actions controls; hairlines separate header from `Content` and `Content` from
  *   `Actions` only where both neighbours exist. The surface reads `--radius-dialog`,
@@ -462,8 +481,10 @@ const DialogActions: FunctionComponent<IDialogActionsProps> = ({
  *
  * @CallerMustEnsure — the component cannot see these and does not check them
  * - In child-scroll mode provide one child that accepts the height allocation and owns overflow.
- *   Intermediate wrappers must preserve that allocation. Fixed regions must fit the viewport and
- *   leave usable room for the child; a Table needs room for its header and readable rows.
+ *   Intermediate consumer wrappers must preserve that allocation. Pane.Root with child-owned
+ *   Pane.Body and a fixed Pane.Foot is supported. The fallback measures the composed table and
+ *   surrounding fixed content at their current width; arbitrary height-consuming wrappers need
+ *   their own allocation contract.
  * - Direct children in the order `Title`, `Description`, `Content`, `Actions`, at most one of
  *   each; `Actions` is present and holds at least one explicit dismissal control, wired to the
  *   same dismissal and visibility transitions. Cancel-before-Confirm order puts initial focus on

package/src/Layout/Dialog/useDialogAllocation.ts

@@ -0,0 +1,131 @@
+import { type RefObject, useLayoutEffect, useState } from 'react';
+
+const length = (value: string): number => Number.parseFloat(value) || 0;
+const edges = (style: CSSStyleDeclaration): number =>
+  length(style.paddingTop) +
+  length(style.paddingBottom) +
+  length(style.borderTopWidth) +
+  length(style.borderBottomWidth);
+const margins = (element: Element): number => {
+  const style = getComputedStyle(element);
+  return length(style.marginTop) + length(style.marginBottom);
+};
+
+// Measure semantic content at its current width, never by temporarily rebounding fallback content.
+// A table needs its caption, header and one complete row; surrounding fixed siblings keep their height.
+const minimumHeight = (element: Element): number => {
+  const style = getComputedStyle(element);
+  if (style.display === 'none' || style.position === 'absolute') return 0;
+  if (element.matches('table')) {
+    const fixed = Array.from(element.children)
+      .filter((child) => child.matches('caption, thead'))
+      .reduce(
+        (height, child) => height + child.getBoundingClientRect().height,
+        0,
+      );
+    const row = Math.max(
+      0,
+      ...Array.from(element.querySelectorAll('tbody>tr')).map(
+        (child) => child.getBoundingClientRect().height,
+      ),
+    );
+    return fixed + row;
+  }
+  if (element.querySelector('table')) {
+    const children = Array.from(element.children);
+    return (
+      edges(style) +
+      Math.max(0, children.length - 1) * length(style.rowGap) +
+      children.reduce(
+        (height, child) =>
+          height +
+          margins(child) +
+          (child.matches('table') || child.querySelector('table')
+            ? minimumHeight(child)
+            : child.getBoundingClientRect().height),
+        0,
+      )
+    );
+  }
+  const item = Math.max(
+    length(style.lineHeight) || length(style.fontSize),
+    ...Array.from(
+      element.querySelectorAll(
+        'button, input, select, textarea, [role="button"]',
+      ),
+    ).map((child) => child.getBoundingClientRect().height),
+  );
+  const ring =
+    length(style.getPropertyValue('--focus-ring-width')) +
+    length(style.getPropertyValue('--focus-ring-offset'));
+  return edges(style) + item + 2 * ring;
+};
+
+export const useDialogAllocation = (
+  root: RefObject<HTMLDialogElement | undefined>,
+): boolean => {
+  const [isUnusable, setIsUnusable] = useState(false);
+  useLayoutEffect(() => {
+    const dialog = root.current;
+    if (!dialog) return;
+    const measure = () => {
+      if (!dialog.open) return;
+      const style = getComputedStyle(dialog);
+      const available =
+        style.maxHeight === 'none'
+          ? length(style.height)
+          : length(style.maxHeight);
+      const required = Array.from(dialog.children).reduce(
+        (height, child) =>
+          height +
+          margins(child) +
+          (child.getAttribute('data-dialog-member') === 'content'
+            ? minimumHeight(child)
+            : child.getBoundingClientRect().height),
+        edges(style),
+      );
+      setIsUnusable(available < required);
+    };
+    const observer =
+      typeof ResizeObserver === 'undefined'
+        ? undefined
+        : new ResizeObserver(measure);
+    const observe = () => {
+      observer?.disconnect();
+      observer?.observe(dialog);
+      for (const child of dialog.querySelectorAll('*'))
+        observer?.observe(child);
+      measure();
+    };
+    observe();
+    const mutations = new MutationObserver(observe);
+    mutations.observe(dialog, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+      attributes: true,
+      attributeFilter: ['open'],
+    });
+    window.addEventListener('resize', measure);
+    return () => {
+      observer?.disconnect();
+      mutations.disconnect();
+      window.removeEventListener('resize', measure);
+    };
+  }, [root]);
+  // Releasing or restoring the allocation can move the focused control outside the scrollport.
+  // Reveal it after that layout commit, retaining the same element and native keyboard behavior.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: the allocation transition is the trigger
+  useLayoutEffect(() => {
+    const dialog = root.current;
+    const focused = dialog?.ownerDocument.activeElement;
+    if (
+      dialog?.open &&
+      focused instanceof HTMLElement &&
+      dialog.contains(focused)
+    ) {
+      focused.scrollIntoView?.({ block: 'nearest', inline: 'nearest' });
+    }
+  }, [root, isUnusable]);
+  return isUnusable;
+};

package/src/Layout/Dialog/useModalScrollLock.ts

@@ -0,0 +1,59 @@
+import { type RefObject, useLayoutEffect } from 'react';
+
+type PageScrollLock = {
+  overflow: string;
+  priority: string;
+  dialogs: Set<HTMLDialogElement>;
+};
+
+const PAGE_SCROLL_LOCKS = new WeakMap<HTMLElement, PageScrollLock>();
+
+// Mutation observers can report the replacement opening before the previous dialog closing,
+// even when the consumer closes first. Share the snapshot until both observers have settled.
+const acquireScrollLock = (dialog: HTMLDialogElement): (() => void) => {
+  const page = dialog.ownerDocument.documentElement;
+  let lock = PAGE_SCROLL_LOCKS.get(page);
+  if (lock === undefined) {
+    lock = {
+      overflow: page.style.getPropertyValue('overflow'),
+      priority: page.style.getPropertyPriority('overflow'),
+      dialogs: new Set<HTMLDialogElement>(),
+    };
+    PAGE_SCROLL_LOCKS.set(page, lock);
+    page.style.setProperty('overflow', 'hidden');
+  }
+  const acquired = lock;
+  acquired.dialogs.add(dialog);
+  return () => {
+    acquired.dialogs.delete(dialog);
+    if (acquired.dialogs.size === 0) {
+      page.style.setProperty('overflow', acquired.overflow, acquired.priority);
+      PAGE_SCROLL_LOCKS.delete(page);
+    }
+  };
+};
+
+export const useModalScrollLock = (
+  root: RefObject<HTMLDialogElement | undefined>,
+): void => {
+  useLayoutEffect(() => {
+    const dialog = root.current;
+    if (!dialog) return;
+    let release: (() => void) | undefined;
+    const synchronize = () => {
+      if (dialog.open && release === undefined) {
+        release = acquireScrollLock(dialog);
+      } else if (!dialog.open && release !== undefined) {
+        release();
+        release = undefined;
+      }
+    };
+    synchronize();
+    const observer = new MutationObserver(synchronize);
+    observer.observe(dialog, { attributes: true, attributeFilter: ['open'] });
+    return () => {
+      observer.disconnect();
+      release?.();
+    };
+  }, [root]);
+};

package/src/Layout/Pane/Pane.tsx

@@ -17,7 +17,7 @@ const paneBody = cva('min-h-0 min-w-0 flex-[0_1_auto]', {
   variants: {
     scrollOwner: {
       body: '[&>div]:flow-root [&>div]:w-fit [&>div]:min-w-full [&>div]:p-[calc(var(--focus-ring-width)+var(--focus-ring-offset))] overflow-auto overscroll-contain outline-focus-ring outline-offset-[var(--focus-ring-offset)] focus-visible:outline focus-visible:outline-[length:var(--focus-ring-width)]',
-      child: '',
+      child: 'flex flex-col',
     },
   },
   defaultVariants: { scrollOwner: 'body' },
@@ -145,8 +145,15 @@ const useScreenFallback = (root: {
       const gaps =
         Math.max(0, sections.length - 1) *
         parseLength(getComputedStyle(element).rowGap);
+      // A height-passing holder may keep a row of its own above the pane (Tabs.Root fill); the
+      // pane is offered the remainder less that row, bounded or released alike (#153).
+      const allocation = frame.getBoundingClientRect();
+      const above = Math.max(
+        0,
+        element.getBoundingClientRect().top - allocation.top,
+      );
       setIsUnusable(
-        frame.getBoundingClientRect().height <
+        allocation.height - above <
           fixed +
             gaps +
             blockEdges(element) +
@@ -254,7 +261,8 @@ const Body: FunctionComponent<IPaneBodyProps> = ({
  *   overflowing, retained while focused. It reserves the shared focus ring's room and leaves
  *   native focus reveal, scrolling and child keyboard interactions intact.
  * - Body scrollOwner="child" passes its allocated height directly to its child, without an
- *   inner wrapper, overflow, group or keyboard stop. The child owns scroll semantics and naming.
+ *   inner wrapper, overflow, group or keyboard stop. Its flex allocation permits a bounded Table
+ *   to shrink even in a content-height Dialog. The child owns scroll semantics and naming.
  *   Use this for a bounded Table: its wrapper must own both axes so its header stays in view.
  *
  * @CallerMustEnsure
@@ -265,7 +273,9 @@ const Body: FunctionComponent<IPaneBodyProps> = ({
  * - In child mode supply one child that accepts its parent's allocated height and handles its
  *   own overflow and focus ring. Intermediate wrappers must preserve that allocation.
  * - Inside Screen, fixed regions and the usable body minimum participate in whole-content
- *   fallback and restoration. Outside Screen the parent remains responsible for that policy.
+ *   fallback and restoration, measured against what Screen's remainder leaves below anything
+ *   above the pane - a filling Tabs row. Dialog owns the corresponding whole-task fallback for
+ *   a Pane with child-owned Body and bounded Table. Other parents own their fallback policy.
  * - Filled ColumnLayout columns and active Stepper panels can pass the bound to Root. Keep
  *   those holders and Pane directly composed so no intermediate wrapper loses the allocation.
  */

package/src/Layout/Screen/Screen.tsx

@@ -33,8 +33,8 @@ export interface IScreenProps {
  * - Use Shell's console body, optionally Sidebar.Root fill / Sidebar.Content, to allocate height
  *   and own fallback scrolling. Every intermediate wrapper must pass that allocation through.
  * - Compose filling ColumnLayout with direct Pane children; retain Pane's Head/Body/Foot order.
- *   Body can delegate to one bounded Table. Additional height-consuming wrappers need their own
- *   allocation contract and are not measured as panel fixed regions by Screen.
+ *   Body can delegate to one bounded Table. A filling Tabs row above a Pane counts against that
+ *   Pane's room; other height-consuming wrappers need their own allocation contract.
  * - Keep the Shell bar short enough to leave a usable enclosing scrollport. This is representative
  *   panel fit, not a guarantee that arbitrary content fits any particular viewport.
  */

package/src/Layout/Sidebar/Sidebar.tsx

@@ -119,8 +119,8 @@ export interface ISidebarRootProps extends VariantProps<typeof sidebarRoot> {
   active: string;
   /** The nav landmark's accessible name. */
   label: string;
-  /** Emits the selected entry's key when a usable inactive entry is activated. The active and inert
-   *  entries emit nothing, and neither does any render. */
+  /** Emits a navigation request once per non-inert entry activation, including the current entry.
+   *  Rendering, focus and active-key changes emit nothing. The caller owns the Subject's lifetime. */
   onSelect$: Subject<string>;
   /** Direct `Sidebar.Item` children in display order, then one `Sidebar.Content`. */
   children?: ReactNode;
@@ -152,7 +152,7 @@ const SidebarItem: FunctionComponent<ISidebarItemProps> = ({
   const selection = useContext(SidebarSelectionContext);
   const isActive = selection !== undefined && selection.active === entryKey;
   const selectEntry = () => {
-    if (!isActive) selection?.onSelect$.next(entryKey);
+    selection?.onSelect$.next(entryKey);
   };
   return (
     <li>
@@ -203,16 +203,17 @@ const SidebarRoot: FunctionComponent<ISidebarRootProps> = ({
 /**
  * The standing application navigation beside the active section's content: a `nav` landmark named by
  * `label`, listing text entries as plain buttons, and a `Content` track for the section the
- * application shows. Selection is a request - activating a usable inactive entry emits its key through
- * `onSelect$` - and the application answers by rerendering with a new `active`. Composed from `Root`,
+ * application shows. Every non-inert activation requests that section through `onSelect$`, including
+ * the current section; the application decides whether to change content or `active`. Composed from `Root`,
  * `Item` and `Content`; Root assembles its direct Items into the list, in order, and places Content
  * beside them at 64rem or below them under it.
  *
  * @Guarantees — enforced on every render
  * - For valid caller input, the active entry alone carries `aria-current="true"`. Sidebar owns no
  *   selection, URL, history or fallback: it renders the key it is given; a missing key marks nothing.
- * - Activating the active entry or an inert one emits nothing; no render emits anything. Entries are
- *   non-submitting `type="button"` buttons with native Tab/Enter/Space behaviour - no tabs/menu model.
+ * - Each non-inert mouse/Enter/Space activation emits its key exactly once, including the current
+ *   entry. This supersedes #101's current-entry silence. Inert entries, render, focus and active-key
+ *   changes emit nothing. Entries are non-submitting native buttons, with no tabs/menu model.
  * - An inert entry stays visible but muted and disabled, so Tab skips it and activation is inert too.
  * - A label is rendered in full inside its entry, in either arrangement: a phrase wraps at its spaces
  *   and a word wider than the track breaks within itself. Nothing is truncated, renamed or hidden
@@ -238,6 +239,8 @@ const SidebarRoot: FunctionComponent<ISidebarRootProps> = ({
  *   and an Item rendered outside a Root has no selection to derive its treatment from.
  * - Focus after the content changes belongs to the application; Sidebar leaves it on the activated
  *   entry.
+ * - Navigation requests carry no routing, history, draft disposal, payment or content state policy.
+ *   Ordinary content may ignore a current-section request; subordinate content may return through it.
  *
  * @UXGuidelines
  * - Entries are section labels: short, parallel, text-only. A destination that is a URL belongs to