@dxos/react-ui 0.8.4-main.3eb6e50203 → 0.8.4-main.3fbcb4aa9b

package/src/exemplars/slot.stories.tsx

@@ -2,85 +2,64 @@
 // Copyright 2023 DXOS.org
 //
 
+import { Primitive } from '@radix-ui/react-primitive';
 import { Slot } from '@radix-ui/react-slot';
 import { type Meta, type StoryObj } from '@storybook/react-vite';
-import React, { type PropsWithChildren, forwardRef } from 'react';
+import React, { PropsWithChildren } from 'react';
 
-import { mx } from '@dxos/ui-theme';
-import { type SlottableClassName, type SlottableProps, type ThemedClassName } from '@dxos/ui-types';
+import { composable, composableProps, mx, slottable } from '@dxos/ui-theme';
 
 import { withTheme } from '../testing';
+import { ThemedClassName } from '../util';
 
 /**
- * Composition
- *
+ * Radix-style composition.
  * All Radix primitive parts that render a DOM element accept an asChild prop.
- * When asChild is set to true, Radix will not render a default DOM element, instead cloning the part's child and passing it the props and behavior required to make it functional.
+ * When asChild is set to true, Radix will not render a default DOM element,
+ * instead cloning the part's child and passing it the props and behavior required to make it functional.
  * https://www.radix-ui.com/primitives/docs/guides/composition
  */
 
-// Outer primitive (like Tooltip.Trigger or Focus.Group).
-const Outer = forwardRef<HTMLDivElement, SlottableProps<HTMLDivElement>>(
-  ({ children, className, classNames, asChild, ...props }, forwardedRef) => {
-    const Root = asChild ? Slot : 'div';
+const Outer = slottable<HTMLDivElement, { priority?: number }>(
+  ({ children, asChild, priority, ...props }, forwardedRef) => {
+    const Comp = asChild ? Slot : Primitive.div;
     return (
-      <Root {...props} className={mx(className, classNames)} data-outer='true' ref={forwardedRef}>
+      <Comp
+        {...composableProps<HTMLDivElement>(props, { classNames: 'p-2 border border-red-500 rounded' })}
+        ref={forwardedRef}
+      >
         {children}
-      </Root>
+      </Comp>
     );
   },
 );
 
-// Middle primitive (like Dialog.Trigger or Mosaic.Cell).
-const Middle = forwardRef<HTMLDivElement, SlottableProps<HTMLDivElement>>(
-  ({ children, className, classNames, asChild, ...props }, forwardedRef) => {
-    const Root = asChild ? Slot : 'div';
-    return (
-      <Root {...props} className={mx(className, classNames)} data-middle='true' ref={forwardedRef}>
-        {children}
-      </Root>
-    );
-  },
-);
-
-// Leaf component (like Card.Root).
-const Leaf = forwardRef<HTMLButtonElement, SlottableClassName<PropsWithChildren>>(
-  ({ className, classNames, children, ...props }, forwardedRef) => {
-    return (
-      <button {...props} className={mx('p-2 outline-none border rounded', className, classNames)} ref={forwardedRef}>
-        {children}
-      </button>
-    );
-  },
-);
-
-// Test 1: Single asChild.
-const TestSingle = ({ classNames, ...props }: ThemedClassName<{ role?: string }>) => (
-  <Outer asChild {...props} className={mx('p-2', classNames)}>
-    <Leaf>Single asChild</Leaf>
-  </Outer>
-);
+const Middle = slottable<HTMLDivElement>(({ children, asChild, ...props }, forwardedRef) => {
+  const Comp = asChild ? Slot : Primitive.div;
+  return (
+    <Comp
+      {...composableProps<HTMLDivElement>(props, { classNames: 'p-2 border border-red-500 rounded' })}
+      ref={forwardedRef}
+    >
+      {children}
+    </Comp>
+  );
+});
 
-// Test 2: Nested asChild.
-const TestNested = ({ classNames, ...props }: ThemedClassName<{ role?: string }>) => {
+const Leaf = composable<HTMLButtonElement>(({ children, ...props }, forwardedRef) => {
   return (
-    <Outer asChild {...props} className={mx('p-2', classNames)}>
-      <Middle asChild>
-        <Leaf>Nested asChild</Leaf>
-      </Middle>
-    </Outer>
+    <button
+      {...composableProps<HTMLButtonElement>(props, { classNames: 'p-2 border border-red-500 rounded' })}
+      ref={forwardedRef}
+    >
+      {children}
+    </button>
   );
-};
+});
 
-// Test 3: Complex.
-const TestInner = ({ classNames, ...props }: ThemedClassName<{ role?: string }>) => (
-  <Outer asChild {...props} className={mx('p-2', classNames)}>
-    <Middle asChild>
-      <Leaf>
-        <div role='none'>Leaf</div>
-      </Leaf>
-    </Middle>
-  </Outer>
+/** This isn't a valid child for a `slottable` component. */
+const Simple = ({ children, classNames }: ThemedClassName<PropsWithChildren>) => (
+  <div className={mx(classNames)}>{children}</div>
 );
 
 const meta = {
@@ -96,13 +75,41 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const Single: Story = {
-  render: () => <TestSingle role='listitem' classNames='border-red-500' />,
+  render: () => (
+    <Outer asChild role='article' classNames='border-green-500' priority={1}>
+      <Leaf>Single asChild (non-compliant — see console)</Leaf>
+    </Outer>
+  ),
 };
 
 export const Nested: Story = {
-  render: () => <TestNested role='listitem' classNames='border-green-500' />,
+  render: () => (
+    <Outer asChild role='article' classNames='border-blue-500'>
+      <Middle asChild>
+        <Leaf>Nested asChild</Leaf>
+      </Middle>
+    </Outer>
+  ),
 };
 
 export const Inner: Story = {
-  render: () => <TestInner role='listitem' classNames='border-blue-500' />,
+  render: () => (
+    <Outer asChild role='article' classNames='border-orange-500'>
+      <Middle asChild>
+        <Leaf>
+          <div>Leaf</div>
+        </Leaf>
+      </Middle>
+    </Outer>
+  ),
+};
+
+export const Error: Story = {
+  render: () => (
+    <Outer asChild role='none' classNames='p-2 border border-green-500 rounded'>
+      <Middle asChild>
+        <Simple>Simple</Simple>
+      </Middle>
+    </Outer>
+  ),
 };

package/src/exemplars/tabster.stories.tsx

@@ -21,14 +21,14 @@ import { mx } from '@dxos/ui-theme';
 // TODO(burdon): Prevent tab out of app.
 
 const border =
-  'rounded-sm outline-none border border-subduedSeparator focus:border-primary-500 focus-within:border-rose-500';
+  'rounded-xs outline-hidden border border-subdued-separator focus:border-primary-500 focus-within:border-rose-500';
 
 const Board = forwardRef<HTMLDivElement, { columns: string[][] }>(({ columns }, ref) => {
   const arrowNavigationAttrs = useArrowNavigationGroup({ axis: 'horizontal', memorizeCurrent: true, tabbable: true });
 
   return (
-    <div ref={ref} tabIndex={0} {...arrowNavigationAttrs} className='flex bs-full is-full overflow-hidden'>
-      <div className={mx('flex bs-full overflow-x-auto p-4 gap-4')}>
+    <div ref={ref} tabIndex={0} {...arrowNavigationAttrs} className='flex h-full w-full overflow-hidden'>
+      <div className={mx('flex h-full overflow-x-auto p-4 gap-4')}>
         {columns.map((column) => (
           <Column key={column[0]} items={column} />
         ))}
@@ -43,7 +43,7 @@ const Column = forwardRef<HTMLDivElement, { items: string[] }>(({ items }, ref)
   const tabsterAttrs = useMergedTabsterAttributes_unstable(focusableGroupAttrs, arrowNavigationAttrs);
 
   return (
-    <ScrollArea.Root tabIndex={0} orientation='vertical' classNames={mx('shrink-0 bs-full is-[25rem]', border)}>
+    <ScrollArea.Root orientation='vertical' classNames={mx('w-[25rem]', border)}>
       <ScrollArea.Viewport {...tabsterAttrs} classNames='p-4 gap-4' ref={ref}>
         {items.map((item) => (
           <Item key={item} value={item} />
@@ -61,7 +61,7 @@ const Item = forwardRef<HTMLDivElement, { value: string }>(({ value }, ref) => {
       ref={ref}
       tabIndex={0}
       {...focusableGroupAttrs}
-      className={mx('flex shrink-0 is-full gap-4 p-4 items-center', border)}
+      className={mx('flex shrink-0 w-full gap-4 p-4 items-center', border)}
     >
       <Input.Root>
         <Input.Checkbox />

package/src/exemplars/virtualizer.stories.tsx

@@ -0,0 +1,136 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type Meta } from '@storybook/react-vite';
+import { useVirtualizer } from '@tanstack/react-virtual';
+import React, { useEffect, useMemo, useRef, useState } from 'react';
+
+import { random } from '@dxos/random';
+import { Panel, ScrollArea, Toolbar } from '@dxos/react-ui';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+random.seed(999);
+
+type TestItem = {
+  name: string;
+};
+
+const meta: Meta = {
+  title: 'ui/react-ui-core/exemplars/virtualizer',
+  decorators: [withLayout({ layout: 'column' }), withTheme()],
+  parameters: {
+    layout: 'fullscreen',
+  },
+};
+
+export default meta;
+
+const NUM_ITEMS = 500;
+
+/**
+ * https://tanstack.com/virtual/latest/docs/introduction
+ */
+export const Default = {
+  render: () => {
+    const [index, setIndex] = useState(0);
+    const items = useMemo<TestItem[]>(
+      () =>
+        Array.from({ length: NUM_ITEMS }, () => ({
+          name: random.lorem.paragraph(),
+        })),
+      [],
+    );
+
+    const parentRef = useRef(null);
+    const [viewport, setViewport] = useState<HTMLElement | null>(null);
+    const virtualizer = useVirtualizer({
+      getScrollElement: () => viewport,
+      estimateSize: () => 40,
+      count: items.length,
+      gap: 8,
+    });
+
+    useEffect(() => {
+      virtualizer.scrollToIndex(index, { align: 'start' });
+    }, [virtualizer, index]);
+
+    const virtualItems = virtualizer.getVirtualItems();
+
+    return (
+      <Panel.Root>
+        <Panel.Toolbar asChild>
+          <ScrollToolbar items={items} index={index} setIndex={setIndex} />
+        </Panel.Toolbar>
+        <Panel.Content asChild>
+          <ScrollArea.Root orientation='vertical' centered>
+            <ScrollArea.Viewport classNames='p-2' ref={setViewport}>
+              <div
+                style={{
+                  position: 'relative',
+                  height: virtualizer.getTotalSize(),
+                  width: '100%',
+                }}
+                ref={parentRef}
+              >
+                {virtualItems.map((virtualItem) => (
+                  <div
+                    key={virtualItem.key}
+                    role='list'
+                    className='grid grid-cols-[3rem_1fr] overflow-hidden border border-separator rounded-xs'
+                    style={{
+                      position: 'absolute',
+                      top: 0,
+                      left: 0,
+                      width: '100%',
+                      transform: `translateY(${virtualItem.start}px)`,
+                    }}
+                    data-index={virtualItem.index}
+                    ref={virtualizer.measureElement}
+                  >
+                    <div className='p-1'>{virtualItem.index + 1}</div>
+                    <div className='p-1'>{items[virtualItem.index].name}</div>
+                  </div>
+                ))}
+              </div>
+            </ScrollArea.Viewport>
+          </ScrollArea.Root>
+        </Panel.Content>
+      </Panel.Root>
+    );
+  },
+};
+
+const ScrollToolbar = ({
+  items,
+  index,
+  setIndex,
+}: {
+  items: any[];
+  index: number;
+  setIndex: (index: number) => void;
+}) => {
+  return (
+    <Toolbar.Root classNames='grid grid-cols-3'>
+      <div />
+      <div className='flex justify-center gap-1'>
+        <Toolbar.IconButton icon='ph--arrow-line-left--regular' iconOnly label='start' onClick={() => setIndex(0)} />
+        <Toolbar.IconButton
+          icon='ph--arrows-out-line-horizontal--regular'
+          iconOnly
+          label='random'
+          onClick={() => setIndex(Math.floor(Math.random() * items.length))}
+        />
+        <Toolbar.IconButton
+          icon='ph--arrow-line-right--regular'
+          iconOnly
+          label='end'
+          onClick={() => setIndex(items.length - 1)}
+        />
+      </div>
+      <div className='p-1 text-right'>
+        {index + 1}/{items.length}
+      </div>
+    </Toolbar.Root>
+  );
+};

package/src/hooks/index.ts

@@ -6,6 +6,7 @@ export * from './useDensityContext';
 export * from './useElevationContext';
 export * from './useIconHref';
 export * from './useSafeArea';
+export * from './useSafeCollisionPadding';
 export * from './useTranslationsContext';
 export * from './useThemeContext';
 export * from './useVisualViewport';

package/src/hooks/useDensityContext.ts

@@ -8,7 +8,7 @@ import { type Density } from '@dxos/ui-types';
 
 import { DensityContext } from '../components';
 
-export const useDensityContext = (propsDensity?: Density) => {
+export const useDensityContext = (densityProp?: Density): Density | undefined => {
   const { density } = useContext(DensityContext);
-  return propsDensity ?? density;
+  return densityProp ?? density;
 };

package/src/playground/Controls.stories.tsx

@@ -31,9 +31,6 @@ const DefaultStory = () => {
             </Select.Content>
           </Select.Portal>
         </Select.Root>
-        {/* TODO(burdon): Highlight is cyan. */}
-        {/* TODO(burdon): Show vertical divider by default. */}
-        {/* TODO(burdon): Icon sizes should adapt to density. */}
         <Toolbar.ToggleGroup type='multiple'>
           <Toolbar.ToggleGroupItem value='a'>
             <Icon icon='ph--text-b--regular' />
@@ -45,7 +42,6 @@ const DefaultStory = () => {
             <Icon icon='ph--text-underline--regular' />
           </Toolbar.ToggleGroupItem>
         </Toolbar.ToggleGroup>
-        {/* TODO(burdon): Highlight isn't shown. */}
         <Toolbar.ToggleGroup type='single' defaultValue='a'>
           <Toolbar.ToggleGroupItem value='a'>
             <Icon icon='ph--file-ts--regular' />
@@ -59,11 +55,9 @@ const DefaultStory = () => {
             <Icon icon='ph--bug--regular' />
           </Toggle>
         </Toolbar.Button>
-        {/* TODO(burdon): Should not be 'is-full' by default. */}
         <Input.Root>
           <Input.TextInput placeholder='Enter text...' />
         </Input.Root>
-        {/* TODO(burdon): Checkbox collapsed. */}
         <Input.Root>
           <Input.Checkbox checked={checked} onCheckedChange={(value) => setChecked(!!value)} />
           <Input.Label>Checkbox</Input.Label>

package/src/playground/Custom.stories.tsx

@@ -20,17 +20,16 @@ const DefaultStory = ({ children, ...args }: Omit<ButtonProps, 'ref'>) => {
             </Button>
           </div>
           <div className='flex justify-center'>
-            <IconButton {...args} label='Test' icon='ph--atom--regular' size={7} density='coarse' />
+            <IconButton {...args} label='Test' icon='ph--circle--regular' density='coarse' />
           </div>
           <div className='flex justify-center'>
             <IconButton
               {...args}
               label='Test'
-              icon='ph--atom--regular'
+              icon='ph--circle--regular'
               iconOnly
-              size={7}
               density='coarse'
-              classNames='pli-1.5'
+              classNames='px-1.5'
             />
           </div>
         </div>
@@ -43,16 +42,16 @@ const DefaultStory = ({ children, ...args }: Omit<ButtonProps, 'ref'>) => {
             </Button>
           </div>
           <div className='flex justify-center'>
-            <IconButton {...args} label='Test' icon='ph--atom--regular' density='fine' classNames='pli-2' />
+            <IconButton {...args} label='Test' icon='ph--circle--regular' density='fine' classNames='px-2' />
           </div>
           <div className='flex justify-center'>
             <IconButton
               {...args}
               label='Test'
-              icon='ph--atom--regular'
+              icon='ph--circle--regular'
               iconOnly
               density='fine'
-              classNames='plb-1 pli-1.5'
+              classNames='py-1 px-1.5'
             />
           </div>
         </div>
@@ -60,7 +59,7 @@ const DefaultStory = ({ children, ...args }: Omit<ButtonProps, 'ref'>) => {
         {/* Small */}
         <div className='grid grid-cols-3 gap-4'>
           <div className='flex justify-center'>
-            <Button {...args} density='fine' classNames={'!h-[24px] !text-[14px] p-0 pli-1.5 min-bs-0'}>
+            <Button {...args} density='fine' classNames={'!h-[24px] !text-[14px] p-0 px-1.5 min-h-0'}>
               {children}
             </Button>
           </div>
@@ -68,35 +67,33 @@ const DefaultStory = ({ children, ...args }: Omit<ButtonProps, 'ref'>) => {
             <IconButton
               {...args}
               label='Test'
-              icon='ph--atom--regular'
+              icon='ph--circle--regular'
               density='fine'
-              size={4}
-              classNames={'!h-[24px] !text-[14px] p-1 min-bs-0 gap-0.5'}
+              classNames={'!h-[24px] !text-[14px] p-1 min-h-0 gap-0.5'}
             />
           </div>
           <div className='flex justify-center'>
             <IconButton
               {...args}
               label='Test'
-              icon='ph--atom--regular'
+              icon='ph--circle--regular'
               iconOnly
               density='fine'
-              size={4}
-              classNames={'!h-[24px] !text-[14px] p-1 min-bs-0'}
+              classNames={'!h-[24px] !text-[14px] p-1 min-h-0'}
             />
           </div>
         </div>
 
         {/* TODO(burdon): Full variant with max width. */}
         <div className='flex justify-center'>
-          <Button classNames='is-full max-is-[15rem] rounded' variant='default'>
+          <Button classNames='w-full max-w-[15rem] rounded-sm' variant='default'>
             Test
           </Button>
         </div>
         <div className='flex justify-center'>
           {/* TODO(burdon): Option to have button on RHS. Default size for icon should be 5 for this (medium) density. */}
           <IconButton
-            classNames='is-full max-is-[15rem] rounded'
+            classNames='w-full max-w-[15rem] rounded-sm'
             variant='primary'
             icon='ph--arrows-clockwise--regular'
             label='Test'

package/src/playground/Typography.stories.tsx

@@ -9,7 +9,7 @@ import { withTheme } from '../testing';
 
 const DefaultStory = () => {
   return (
-    <div className='mli-auto p-8 max-is-[60rem] space-b-4'>
+    <div className='mx-auto p-8 max-w-[60rem] space-b-4'>
       <h1 className='text-4xl font-medium'>
         Việc <span className='italic'>thừa</span> nhận{' '}
         <span className='font-mono bg-neutral-500/10'>

package/src/primitives/Column/AUDIT.md

@@ -0,0 +1,148 @@
+# Column architecture reference
+
+## Background
+
+`Column` establishes a 3-column CSS grid with left/right gutter columns and a center content
+channel. Two CSS custom properties drive the system:
+
+- `--gutter` — the gutter track width (e.g. `var(--dx-gutter-md)`); consumed by `ScrollArea.Viewport` for padding.
+- `--dx-col` — the grid-column placement token; set by `Column.Root` and consumed by `withColumn` utilities.
+
+## Column primitives
+
+### Column.Root
+
+```css
+/* column.ts — columnRoot */
+dx-column grid
+/* inline style */
+--gutter: <gutterSize>
+--dx-col: 2 / span 1
+grid-template-columns: <gutter> minmax(0,1fr) <gutter>
+```
+
+Sets the 3-column grid and both CSS variables. All `withColumn` utilities are no-ops outside this context.
+
+### Column.Center
+
+```css
+/* column.ts — columnCenter */
+[grid-column:var(--dx-col,auto)] min-h-0
+```
+
+Places a single element in col 2 (the center track). Does not use subgrid — placement is explicit
+on this element only, so arbitrary compound components (including `display: contents` wrappers) can
+be nested safely.
+
+### Column.Bleed
+
+```css
+/* column.ts — columnBleed */
+col-span-full grid grid-cols-subgrid min-h-0
+```
+
+Spans all 3 columns and propagates the subgrid. Use for `ScrollArea`, full-width dividers, and
+any content that should ignore the gutters.
+
+### Column.Row
+
+```css
+/* column.ts — columnRow */
+col-span-3 grid grid-cols-subgrid
+```
+
+Three-slot icon row. Children map to: `[col-1: icon/slot] [col-2: content] [col-3: icon/action]`.
+Must be a direct child of `Column.Root`.
+
+## withColumn theme utilities
+
+Exported from `@dxos/ui-theme`. Components import and call these in their theme functions to
+participate in the Column grid without importing Column React components.
+
+```ts
+withColumn.center();
+// → '[grid-column:var(--dx-col,auto)]'
+
+withColumn.propagate();
+// → '[.dx-column_&]:col-span-full [.dx-column_&]:grid [.dx-column_&]:grid-cols-subgrid'
+
+withColumn.consumed();
+// → '[--dx-col:auto]'
+```
+
+| Utility       | Purpose                                                                           | Where used                                                                    |
+| :------------ | :-------------------------------------------------------------------------------- | :---------------------------------------------------------------------------- |
+| `center()`    | Place element in col 2 via `--dx-col`. No-op outside Column or inside ScrollArea. | Dialog.Header, Dialog.ActionBar, Form.Content, Form.Actions, SearchList.Input |
+| `propagate()` | Extend Column subgrid to children. No-op outside Column.                          | Dialog.Body, SearchList.Content                                               |
+| `consumed()`  | Reset `--dx-col` after `--gutter` is consumed.                                    | ScrollArea.Viewport                                                           |
+
+## CSS custom property cascade
+
+```text
+Column.Root
+  sets --gutter = var(--dx-gutter-<size>)
+  sets --dx-col = 2 / span 1
+    │
+    ├─ Column.Center        → grid-column: var(--dx-col)   ← consumes --dx-col
+    ├─ Column.Bleed         → col-span-full, subgrid
+    ├─ Column.Row           → col-span-3, subgrid
+    │
+    └─ withColumn.center()  → grid-column: var(--dx-col)   ← consumes --dx-col
+       withColumn.propagate() → col-span-full, grid, subgrid (inside .dx-column only)
+         │
+         └─ ScrollArea.Root → col-span-full (inside .dx-column only)
+              ScrollArea.Viewport
+                applies pl/pr using --gutter
+                withColumn.consumed() → sets --dx-col: auto
+                  │
+                  └─ (nested components no longer auto-position)
+```
+
+## Component integration
+
+### Dialog
+
+| Sub-component      | withColumn applied            | Effect                        |
+| :----------------- | :---------------------------- | :---------------------------- |
+| `Dialog.Content`   | `Column.Root` (gutter `'sm'`) | Establishes the 3-col grid.   |
+| `Dialog.Header`    | `withColumn.center()`         | Placed in col 2.              |
+| `Dialog.Body`      | `withColumn.propagate()`      | Children inherit the subgrid. |
+| `Dialog.ActionBar` | `withColumn.center()`         | Placed in col 2.              |
+
+### Form
+
+| Sub-component  | withColumn applied    | Effect                              |
+| :------------- | :-------------------- | :---------------------------------- |
+| `Form.Content` | `withColumn.center()` | Placed in col 2 when inside Column. |
+| `Form.Actions` | `withColumn.center()` | Placed in col 2 when inside Column. |
+
+### SearchList
+
+| Sub-component              | withColumn applied       | Effect                                          |
+| :------------------------- | :----------------------- | :---------------------------------------------- |
+| `SearchList.Content`       | `withColumn.propagate()` | Extends subgrid to children when inside Column. |
+| `SearchList.Input` wrapper | `withColumn.center()`    | Input row placed in col 2.                      |
+
+### Card
+
+`Card.Row` uses its own inline subgrid CSS (`col-span-3 grid grid-cols-subgrid`) and does not
+participate in an outer Column grid. `Card.Root` establishes a separate 3-column grid for its
+own icon-slot layout.
+
+## Subgrid chain integrity
+
+Every intermediate container between `Column.Root` and a `ScrollArea.Root` must propagate the
+subgrid, otherwise `ScrollArea.Root`'s `[.dx-column_&]:col-span-full` selector will not match
+and the scrollbar will not extend to the gutter.
+
+Required chain:
+
+```
+Column.Root (.dx-column)
+  → withColumn.propagate() container   (col-span-full, grid, grid-cols-subgrid)
+    → ScrollArea.Root                  (.dx-container, [.dx-column_&]:col-span-full)
+      → ScrollArea.Viewport            (applies --gutter padding, resets --dx-col)
+```
+
+If any intermediate element wraps the ScrollArea without propagating, use `Column.Bleed` or
+apply `withColumn.propagate()` to that wrapper.