@juwel-development/design-system 3.10.0 → 4.0.0

package/src/Interaction/Tabs/Tabs.tsx

@@ -1,4 +1,4 @@
-import { cva } from 'class-variance-authority';
+import { cva, type VariantProps } from 'class-variance-authority';
 import {
   createContext,
   type FocusEvent,
@@ -11,6 +11,16 @@ import {
 import type { Subject } from 'rxjs';
 import { TabsCompositionError } from './TabsCompositionError';
 
+const tabsRoot = cva('', {
+  variants: {
+    fill: {
+      true: 'flex h-full min-h-0 min-w-0 flex-col',
+      false: '',
+    },
+  },
+  defaultVariants: { fill: false },
+});
+
 // The row is one scrolling line of controls, never a second row. The ring room is written from the
 // two focus-ring tokens so it cannot drift from the ring it exists for: padding holds the scroll
 // clip off the outline, the negative margin hands the room back to the page, and scroll-padding
@@ -22,6 +32,7 @@ const tabsList = cva(
     'm-[calc(-1*(var(--focus-ring-width)+var(--focus-ring-offset)))]',
     'scroll-p-[calc(var(--focus-ring-width)+var(--focus-ring-offset))]',
   ].join(' '),
+  { variants: { fill: { true: 'shrink-0', false: '' } } },
 );
 
 // Navigation typography - the tracked grotesk label, muted at rest, foreground when current -
@@ -45,6 +56,7 @@ const tabsTab = cva(
 // the ring follows focusability, not control-ness.
 const tabsPanel = cva(
   'outline-focus-ring outline-offset-[var(--focus-ring-offset)] focus-visible:outline focus-visible:outline-[length:var(--focus-ring-width)]',
+  { variants: { fill: { true: 'min-h-0 min-w-0 flex-auto', false: '' } } },
 );
 
 type TabsContract = {
@@ -52,6 +64,7 @@ type TabsContract = {
   onSelect$: Subject<string>;
   label: string;
   baseId: string;
+  fill: boolean;
 };
 
 const TabsContext = createContext<TabsContract | undefined>(undefined);
@@ -99,7 +112,11 @@ const neighbourTab = (
   return tabs[(index + step + tabs.length) % tabs.length];
 };
 
-export interface ITabsRootProps {
+export interface ITabsRootProps extends VariantProps<typeof tabsRoot> {
+  /** Fill the allocated parent height, keeping List at content height and giving Panel the rest.
+   * In an unsized parent, panels retain content height. Compose List and Panels directly in Root;
+   * an unsized spacing wrapper does not pass the bound. No spacing is added. */
+  fill?: VariantProps<typeof tabsRoot>['fill'];
   /** The key of the active tab. Must name a declared tab/panel pair; the consumer owns it. */
   active: string;
   /** Emits the selected key on click and on arrow navigation. Tabs never selects on its own. */
@@ -141,24 +158,29 @@ const TabsRoot: FunctionComponent<ITabsRootProps> = ({
   active,
   onSelect$,
   label,
+  fill,
   children,
   testId,
 }) => {
   const baseId = useId();
   return (
-    <TabsContext.Provider value={{ active, onSelect$, label, baseId }}>
-      <div data-testid={testId}>{children}</div>
+    <TabsContext.Provider
+      value={{ active, onSelect$, label, baseId, fill: fill === true }}
+    >
+      <div className={tabsRoot({ fill })} data-testid={testId}>
+        {children}
+      </div>
     </TabsContext.Provider>
   );
 };
 
 const TabsList: FunctionComponent<ITabsListProps> = ({ children, testId }) => {
-  const { label } = useTabsContract('List');
+  const { label, fill } = useTabsContract('List');
   return (
     <div
       role="tablist"
       aria-label={label}
-      className={tabsList()}
+      className={tabsList({ fill })}
       data-testid={testId}
     >
       {children}
@@ -221,7 +243,7 @@ const TabsPanel: FunctionComponent<ITabsPanelProps> = ({
   children,
   testId,
 }) => {
-  const { active, baseId } = useTabsContract('Panel');
+  const { active, baseId, fill } = useTabsContract('Panel');
   const isActive = active === value;
   return (
     <div
@@ -230,7 +252,7 @@ const TabsPanel: FunctionComponent<ITabsPanelProps> = ({
       aria-labelledby={tabId(baseId, value)}
       hidden={!isActive}
       tabIndex={isActive ? 0 : undefined}
-      className={tabsPanel()}
+      className={tabsPanel({ fill })}
       data-testid={testId}
     >
       {isActive ? children : undefined}
@@ -271,11 +293,23 @@ const TabsPanel: FunctionComponent<ITabsPanelProps> = ({
  *   `foreground`, constant thickness in both states, so switching shifts no widths and no weights.
  *   Keyboard focus is the separate shared focus ring. Colour moves on the one motion token.
  *
+ * - With `fill`, Root takes the allocated parent height; List keeps its content height and the
+ *   active Panel takes the remainder. Its definite height bounds a direct Pane or bounded Table.
+ *   Switching views changes neither Root height nor List position. No scrolling or spacing is added.
+ *   In an unsized parent the panel retains content height; no bound is invented.
+ * - Without `fill` (including false or null), the existing content-height composition is unchanged.
+ *
  * @CallerMustEnsure — the component cannot see these and does not check them
  * - One List with Tab elements as direct DOM children (arrays and fragments are supported),
  *   and the Panels under the same Root - as siblings of the List, or with it inside one
  *   arrangement such as a `Stack` (see the separation guidance below). Do not wrap tabs in host
  *   elements.
+ * - For `fill`, List and Panels must be direct DOM children of Root (fragments are fine), with
+ *   one height-accepting child directly inside the active Panel. Supply a definite parent height
+ *   and enough room for List and the child's fixed content. An unsized Stack between Root and
+ *   members, or between Panel and its child, breaks that height chain. Compose content spacing
+ *   inside the Pane's slots instead; Tabs adds no gap. In an unsized parent the enclosing page
+ *   owns overflow. A bounded Table requires the separate #142 API.
  * - A label is a meaningful visible text name, with non-interactive decoration at most: no link,
  *   button, input or other focusable descendant, since the tab is the one control and a nested
  *   control inside a `button` is invalid. Decorative parts - an icon that repeats the text - carry
@@ -295,8 +329,8 @@ const TabsPanel: FunctionComponent<ITabsPanelProps> = ({
  *   do not fit, so a label is never the reason to shorten a name.
  * - This is not a router: no location, no history, no deep links. Wire `onSelect$` to whatever
  *   owns the active key and pass that key back in.
- * - Tabs sets no spacing between the row and the panel; the separation is a `Stack` between Root
- *   and its members - `<Tabs.Root><Stack gap="region"><Tabs.List/>…<Tabs.Panel/>…</Stack>
+ * - In the default content-height mode, Tabs sets no spacing between the row and the panel;
+ *   the separation is a `Stack` between Root and its members - `<Tabs.Root><Stack gap="region"><Tabs.List/>…<Tabs.Panel/>…</Stack>
  *   </Tabs.Root>`. `gap="stack"` holds the row and its view together as one block; `gap="region"`
  *   sets the view apart as a region of its own. Inactive panels are hidden, so the gap is exactly
  *   one whichever panel is active, from the token the consumer's other groups already use.

package/src/Layout/Dialog/Dialog.tsx

@@ -19,7 +19,7 @@ import { DialogNamingError } from './DialogNamingError';
 // 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 }` - only Content may scroll.
+// overflow-hidden overrides the UA's `dialog { overflow: auto }` - Content or its delegated child owns scrolling.
 const dialogRoot = cva(
   [
     'open:flex open:flex-col m-auto p-0 overflow-hidden',
@@ -67,10 +67,16 @@ const dialogDescription = cva(
 // this scrolls. Its hairline exists only when a header region stands before it.
 const dialogContent = cva(
   [
-    'grow shrink min-h-0 overflow-y-auto',
+    'grow shrink min-h-0 min-w-0',
     'px-[var(--space-region)] py-[var(--space-region)]',
     '[&:not(:first-child)]:border-t [&:not(:first-child)]:border-border',
   ].join(' '),
+  {
+    variants: {
+      scrollOwner: { body: 'overflow-y-auto', child: 'flex flex-col' },
+    },
+    defaultVariants: { scrollOwner: 'body' },
+  },
 );
 
 // An end-aligned row in consumer DOM order, wrapping on narrow screens without reversing. Its
@@ -173,7 +179,8 @@ export interface IDialogDescriptionProps {
   testId?: string;
 }
 
-export interface IDialogContentProps {
+export interface IDialogContentProps
+  extends VariantProps<typeof dialogContent> {
   /** Arbitrary task content, composed and owned by the consumer. */
   children: ReactNode;
   testId?: string;
@@ -385,13 +392,14 @@ const DialogDescription: FunctionComponent<IDialogDescriptionProps> = ({
 
 const DialogContent: FunctionComponent<IDialogContentProps> = ({
   children,
+  scrollOwner,
   testId,
 }) => {
   useDialogContract('Content');
   return (
     <div
       data-dialog-member={'content'}
-      className={dialogContent()}
+      className={dialogContent({ scrollOwner })}
       data-testid={testId}
     >
       {children}
@@ -420,7 +428,7 @@ const DialogActions: FunctionComponent<IDialogActionsProps> = ({
  * the platform `<dialog>` and `showModal()`: the browser owns the top layer, background inertness
  * and the modal keyboard boundary; the consumer owns all wording, controls, outcomes and
  * replacement. Composed from five members: `Root` carries the contract, `Title` the visible name,
- * `Description` one connected line, `Content` the only scrollable region, `Actions` the controls.
+ * `Description` one connected line, `Content` the scrolling region or holder of one bounded child, `Actions` the controls.
  *
  * @Guarantees — enforced on every render
  * - Presents through `showModal()`/`close()` - no portal, focus trap or polyfill - so background
@@ -443,7 +451,9 @@ 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;
- *   `Content` scrolls only as the emergency fallback when fitting is physically impossible.
+ *   Default `Content` scrolls as the fallback when its content exceeds available space.
+ * - `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.
  * - 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`,
@@ -451,6 +461,9 @@ const DialogActions: FunctionComponent<IDialogActionsProps> = ({
  *   with the theme's optional `--scrim-blur`.
  *
  * @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.
  * - 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/Form/Form.tsx

@@ -1,5 +1,6 @@
 import { cva } from 'class-variance-authority';
 import type { FunctionComponent, ReactNode } from 'react';
+import { FormConfigurationError } from './FormConfigurationError';
 
 /** Which of the four states the page has put the form in. Owned by the page, never by Form: the
  *  component renders the state it is given and never decides which one it is in. */
@@ -78,7 +79,7 @@ export const Form: FunctionComponent<IFormProps> = ({
     note !== undefined && note !== null && typeof note !== 'boolean';
 
   if (state === 'sent' && !hasNote) {
-    throw new Error(
+    throw new FormConfigurationError(
       'Form in the `sent` state must be given a `note` - it is the outcome message.',
     );
   }

package/src/Layout/Form/FormConfigurationError.ts

@@ -0,0 +1,6 @@
+export class FormConfigurationError extends Error {
+  constructor(reason: string) {
+    super(`Form configuration is invalid: ${reason}`);
+    this.name = 'FormConfigurationError';
+  }
+}

package/src/Layout/Pane/Pane.tsx

@@ -0,0 +1,159 @@
+import { cva, type VariantProps } from 'class-variance-authority';
+import {
+  type FunctionComponent,
+  type ReactNode,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from 'react';
+
+const pane = cva(
+  'box-border flex h-full min-h-0 min-w-0 flex-col gap-[var(--space-stack)] border border-solid border-border bg-surface text-foreground p-[var(--space-box-inset)] [overflow-wrap:anywhere]',
+);
+const paneSection = cva('min-w-0 shrink-0');
+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: '',
+    },
+  },
+  defaultVariants: { scrollOwner: 'body' },
+});
+
+const useOverflow = (
+  container: { current: HTMLDivElement | null },
+  content: { current: HTMLDivElement | null },
+  ownsScroll: boolean,
+): boolean => {
+  const [isScrollable, setIsScrollable] = useState(true);
+  useLayoutEffect(() => {
+    const element = container.current;
+    if (!element || !ownsScroll) return;
+    const measure = () =>
+      setIsScrollable(
+        element.scrollHeight > element.clientHeight ||
+          element.scrollWidth > element.clientWidth ||
+          element === element.ownerDocument.activeElement,
+      );
+    measure();
+    const observer =
+      typeof ResizeObserver === 'undefined'
+        ? undefined
+        : new ResizeObserver(measure);
+    observer?.observe(element);
+    if (content.current) observer?.observe(content.current);
+    const mutations = new MutationObserver(measure);
+    mutations.observe(element, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+    });
+    window.addEventListener('resize', measure);
+    element.addEventListener('blur', measure);
+    return () => {
+      observer?.disconnect();
+      mutations.disconnect();
+      window.removeEventListener('resize', measure);
+      element.removeEventListener('blur', measure);
+    };
+  }, [container, content, ownsScroll]);
+  return isScrollable;
+};
+
+export interface IPaneRootProps {
+  children?: ReactNode;
+  /** A non-empty name makes the enclosure an accessible group, as with Box. */
+  name?: string;
+  testId?: string;
+}
+export interface IPaneSectionProps {
+  children?: ReactNode;
+  testId?: string;
+}
+export interface IPaneBodyProps extends VariantProps<typeof paneBody> {
+  children?: ReactNode;
+  /** Names the body while overflowing. Unused when the child owns scrolling. */
+  ariaLabel: string;
+  testId?: string;
+}
+
+const Root: FunctionComponent<IPaneRootProps> = ({
+  children,
+  name,
+  testId,
+}) => (
+  // biome-ignore lint/a11y/useAriaPropsSupportedByRole: the name and group role are assigned together
+  <div
+    className={pane()}
+    role={name ? 'group' : undefined}
+    aria-label={name || undefined}
+    data-testid={testId}
+  >
+    {children}
+  </div>
+);
+const Head: FunctionComponent<IPaneSectionProps> = ({ children, testId }) => (
+  <div className={paneSection()} data-testid={testId}>
+    {children}
+  </div>
+);
+const Foot: FunctionComponent<IPaneSectionProps> = ({ children, testId }) => (
+  <div className={paneSection()} data-testid={testId}>
+    {children}
+  </div>
+);
+const Body: FunctionComponent<IPaneBodyProps> = ({
+  children,
+  ariaLabel,
+  scrollOwner,
+  testId,
+}) => {
+  const container = useRef<HTMLDivElement>(null);
+  const content = useRef<HTMLDivElement>(null);
+  const ownsScroll = scrollOwner !== 'child';
+  const isScrollable =
+    useOverflow(container, content, ownsScroll) && ownsScroll;
+  return (
+    // biome-ignore lint/a11y/useAriaPropsSupportedByRole: the name and group role are assigned together
+    <div
+      ref={container}
+      className={paneBody({ scrollOwner: scrollOwner ?? 'body' })}
+      role={isScrollable ? 'group' : undefined}
+      aria-label={isScrollable ? ariaLabel : undefined}
+      tabIndex={isScrollable ? 0 : undefined}
+      data-testid={testId}
+    >
+      {ownsScroll ? <div ref={content}>{children}</div> : children}
+    </div>
+  );
+};
+
+/**
+ * A parent-bounded enclosure with optional content-height Head and Foot around a shrinking Body.
+ *
+ * @Guarantees
+ * - Root fills the allocated height, including its border and box inset. Without a definite
+ *   parent height it grows with content; a stacked parent or enclosing body owns scrolling.
+ * - Head and Foot never shrink. Body scrolls both axes as needed and short content does not
+ *   stretch: Foot follows it, with any unused height left in Root rather than inside Body.
+ * - Root paints surface, foreground, border and box inset, square and without elevation.
+ *   The stack space role separates slots; a non-empty name exposes a group, never a landmark.
+ * - Default Body is the sole scroll region: a named group and keyboard stop only while
+ *   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.
+ *   Use this for a bounded Table: its wrapper must own both axes so its header stays in view.
+ *
+ * @CallerMustEnsure
+ * - Compose at most one Head, Body and Foot, in that order, directly inside Root; all are optional.
+ *   Do not nest panes. The consumer owns all wording, facts, actions and internal arrangement.
+ * - Supply a finite parent height to bound a pane, and enough room for Head, Foot, inset and gaps.
+ *   At smaller sizes use an unsized stacked arrangement in a scrolling page or Shell body.
+ * - 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.
+ * - 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.
+ */
+export const Pane = { Root, Head, Body, Foot } as const;

package/src/Layout/Shell/Shell.tsx

@@ -0,0 +1,124 @@
+import { cva, type VariantProps } from 'class-variance-authority';
+import {
+  type FunctionComponent,
+  type ReactNode,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from 'react';
+
+const shell = cva(
+  'h-dvh min-w-0 overflow-clip grid grid-rows-[auto_minmax(0,1fr)]',
+);
+const shellBody = cva(
+  'min-h-0 min-w-0 overflow-auto overscroll-contain p-[calc(var(--focus-ring-width)+var(--focus-ring-offset))] scroll-p-[calc(var(--focus-ring-width)+var(--focus-ring-offset))] outline-focus-ring focus-visible:outline focus-visible:outline-[length:var(--focus-ring-width)] focus-visible:outline-offset-[calc(-1*var(--focus-ring-width))]',
+  {
+    variants: {
+      mode: { console: '[&>div]:h-full', page: '[&>div]:min-h-full' },
+    },
+    defaultVariants: { mode: 'console' },
+  },
+);
+
+// Geometry is read only to expose a keyboard stop; CSS alone allocates the height.
+const useScrollableBody = (body: {
+  current: HTMLDivElement | null;
+}): boolean => {
+  const [isScrollable, setIsScrollable] = useState(true);
+  useLayoutEffect(() => {
+    const element = body.current;
+    if (!element) return;
+    const measure = () =>
+      setIsScrollable(
+        element.scrollHeight > element.clientHeight ||
+          element.scrollWidth > element.clientWidth ||
+          element === element.ownerDocument.activeElement,
+      );
+    measure();
+    const resize =
+      typeof ResizeObserver === 'undefined'
+        ? undefined
+        : new ResizeObserver(measure);
+    const observeContent = () => {
+      resize?.disconnect();
+      resize?.observe(element);
+      for (const child of element.querySelectorAll('*')) resize?.observe(child);
+      measure();
+    };
+    observeContent();
+    const mutations = new MutationObserver(observeContent);
+    mutations.observe(element, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+    });
+    window.addEventListener('resize', measure);
+    element.addEventListener('blur', measure);
+    return () => {
+      resize?.disconnect();
+      mutations.disconnect();
+      window.removeEventListener('resize', measure);
+      element.removeEventListener('blur', measure);
+    };
+  }, [body]);
+  return isScrollable;
+};
+
+export interface IShellProps extends VariantProps<typeof shellBody> {
+  /** Consumer-owned top bar; its content determines its height. */
+  bar: ReactNode;
+  /** Body content; receives the remaining height in console mode. */
+  children: ReactNode;
+  /** The body scroll group's name, exposed only while overflowing or focused. */
+  ariaLabel: string;
+  testId?: string;
+}
+
+/**
+ * A viewport-owning frame with a content-height bar and the remaining height for its body.
+ *
+ * @Guarantees
+ * - CSS allocates both tracks, including when bar content wraps. Header is unchanged.
+ * - Console (default) passes a finite height to its child; page lets body content grow.
+ *   Both keep overflow inside the body, with the bar visible and document still.
+ * - Console body scrolling is a reachability fallback for content that cannot fit; bounded
+ *   panels normally own their scrolling. Page deliberately scrolls the body as a whole.
+ * - Overflow makes the body a named, keyboard-reachable group, never a landmark. Removing
+ *   overflow does not relocate focus. Native focus reveal and scroll keys remain intact.
+ * - Body padding reserves the shared focus ring's room, with an inset ring on the body itself.
+ *
+ * @CallerMustEnsure
+ * - Place one Shell at the viewport origin, with no outside margins, padding or siblings that
+ *   add document extent. This is the application frame, not a nested fullscreen section.
+ * - The bar must leave usable body space. An arbitrarily tall bar cannot fit every viewport.
+ * - Supply the main landmark inside the body (inside Sidebar.Content when using Sidebar).
+ * - Intermediate consumer wrappers must preserve the allocated height for bounded panels;
+ *   wrappers with height: 100% and min-height: 0, or display: contents, can pass it through.
+ * - Use Sidebar.Root fill in a console; below 64rem its list stacks and the body scrolls.
+ * - Name the body in the viewer's language. Content and its panel arrangements remain yours.
+ */
+export const Shell: FunctionComponent<IShellProps> = ({
+  bar,
+  children,
+  ariaLabel,
+  mode,
+  testId,
+}) => {
+  const body = useRef<HTMLDivElement>(null);
+  const isScrollable = useScrollableBody(body);
+  return (
+    <div className={shell()} data-testid={testId}>
+      <div>{bar}</div>
+      {/* biome-ignore lint/a11y/useAriaPropsSupportedByRole: the group and its name are conditional together */}
+      <div
+        ref={body}
+        className={shellBody({ mode })}
+        role={isScrollable ? 'group' : undefined}
+        aria-label={isScrollable ? ariaLabel : undefined}
+        tabIndex={isScrollable ? 0 : undefined}
+      >
+        <div>{children}</div>
+      </div>
+    </div>
+  );
+};

package/src/Layout/Sidebar/Sidebar.tsx

@@ -1,4 +1,4 @@
-import { cva } from 'class-variance-authority';
+import { cva, type VariantProps } from 'class-variance-authority';
 import type { FunctionComponent, ReactNode, RefCallback } from 'react';
 import { Children, createContext, isValidElement, useContext } from 'react';
 import type { Subject } from 'rxjs';
@@ -12,10 +12,20 @@ const sidebarRoot = cva(
     'grid gap-[var(--space-region)] lg:grid-cols-[12rem_minmax(0,1fr)]',
     '[&>div:first-child]:border-solid [&>div:first-child]:border-border [&>div:first-child]:border-b [&>div:first-child]:pb-[var(--space-stack)]',
     'lg:[&>div:first-child]:border-b-0 lg:[&>div:first-child]:border-r lg:[&>div:first-child]:pb-0 lg:[&>div:first-child]:pr-[var(--space-stack)]',
-    'lg:[&>div:first-child>nav]:sticky lg:[&>div:first-child>nav]:top-0 lg:[&>div:first-child>nav]:max-h-[min(100dvh,var(--sidebar-scrollport-height,100dvh))] lg:[&>div:first-child>nav]:overflow-y-auto',
+    'lg:[&>div:first-child>nav]:sticky lg:[&>div:first-child>nav]:top-0 lg:[&>div:first-child>nav]:overflow-y-auto',
     '[&>div:first-child>nav]:p-[calc(var(--focus-ring-width)+var(--focus-ring-offset))] lg:[&>div:first-child>nav]:scroll-p-[calc(var(--focus-ring-width)+var(--focus-ring-offset))]',
     '[&>div:first-child>nav>ul]:flex [&>div:first-child>nav>ul]:flex-col [&>div:first-child>nav>ul]:gap-[var(--space-stack)]',
   ].join(' '),
+  {
+    variants: {
+      fill: {
+        false:
+          'lg:[&>div:first-child>nav]:max-h-[min(100dvh,var(--sidebar-scrollport-height,100dvh))]',
+        true: 'min-h-full lg:h-full lg:min-h-0 lg:grid-rows-[minmax(0,1fr)] lg:[&>div]:min-h-0 lg:[&>div]:h-full lg:[&>div:first-child>nav]:max-h-full',
+      },
+    },
+    defaultVariants: { fill: false },
+  },
 );
 
 // A percentage max-height resolves against the content-driven grid cell, not its scrollport;
@@ -38,9 +48,13 @@ const observeScrollport: RefCallback<HTMLElement> = (navigation) => {
       ),
     );
     if (scrollport) {
+      const scrollportStyle = getComputedStyle(scrollport);
+      const padding =
+        (Number.parseFloat(scrollportStyle.paddingTop) || 0) +
+        (Number.parseFloat(scrollportStyle.paddingBottom) || 0);
       navigation.style.setProperty(
         '--sidebar-scrollport-height',
-        `${scrollport.clientHeight}px`,
+        `${Math.max(0, scrollport.clientHeight - padding)}px`,
       );
     } else {
       navigation.style.removeProperty('--sidebar-scrollport-height');
@@ -96,7 +110,10 @@ const SidebarSelectionContext = createContext<SidebarSelection | undefined>(
   undefined,
 );
 
-export interface ISidebarRootProps {
+export interface ISidebarRootProps extends VariantProps<typeof sidebarRoot> {
+  /** Pass a finite parent height through to Content at 64rem and above, using CSS alone.
+   * Below 64rem the enclosing scrollable body owns the stacked list and content. */
+  fill?: VariantProps<typeof sidebarRoot>['fill'];
   /** The key of the active entry. The caller supplies a key identifying one non-inert entry;
    *  Sidebar renders what it is given and never selects a fallback for an invalid key. */
   active: string;
@@ -166,12 +183,13 @@ const SidebarRoot: FunctionComponent<ISidebarRootProps> = ({
   onSelect$,
   children,
   testId,
+  fill,
 }) => {
   const parts = Children.toArray(children).filter(isValidElement);
   return (
-    <div className={sidebarRoot()} data-testid={testId}>
+    <div className={sidebarRoot({ fill })} data-testid={testId}>
       <div>
-        <nav ref={observeScrollport} aria-label={label}>
+        <nav ref={fill ? undefined : observeScrollport} aria-label={label}>
           <SidebarSelectionContext value={{ active, onSelect$ }}>
             <ul>{parts.filter((part) => part.type === SidebarItem)}</ul>
           </SidebarSelectionContext>
@@ -204,11 +222,17 @@ const SidebarRoot: FunctionComponent<ISidebarRootProps> = ({
  *   assumed top-bar offset, capped to the screen/scrolling-area height with independent entry scrolling.
  *   Content sits beside it in `minmax(0,1fr)`, so wide content cannot displace the track.
  * - Below 64rem the whole list lies above the content in normal flow - no stickiness, no cap, no
- *   drawer. Sidebar sets no viewport-height minimum and grows with its content.
+ *   drawer. Without fill, Sidebar grows with its content.
+ * - With fill, a finite parent height passes through Root and Content at 64rem and above;
+ *   navigation is capped to that allocated height by CSS, with no scrollport measurement.
+ *   Below 64rem the list stacks and the enclosing body scrolls. The DOM never switches.
  * - It separates the tracks itself (the region space role and a `border` hairline) but gives the
  *   content track no padding and no landmark - the consumer owns everything inside `Content`.
  *
  * @CallerMustEnsure — the component cannot see these and does not check them
+ * - Fill requires a parent with a finite height and a scrollable enclosing body for narrow
+ *   viewports or oversized fixed content. Consumer wrappers inside Content preserve that bound.
+ *   It works with any bounded parent; no Shell identity, context or offset is required.
  * - Entry keys are unique and `active` names one non-inert entry. Sidebar corrects nothing.
  * - Items and the one Content are direct children of `Root` - Root assembles only what it can see,
  *   and an Item rendered outside a Root has no selection to derive its treatment from.