@xsolla/xui-table 0.207.0 → 0.208.1

package/README.md

@@ -34,7 +34,7 @@ Designed against the [Xsolla UI Kit Table](https://www.figma.com/design/m0qqLlCv
 
 | Sub-component | Role | Notes |
 |---|---|---|
-| `Table` | `role="table"` container | Padding, radius, gap, theme |
+| `Table` | `role="table"` container | Padding, radius, gap, theme, and the layout switches below |
 | `Table.Caption` | Caption / description | Goes anywhere inside `<Table>`; muted text by default |
 | `Table.Header` | `role="rowgroup"` (sticky) | Wraps a single `<Table.Row>` containing `<Table.Head>` cells |
 | `Table.Body` | `role="rowgroup"` | Wraps body `<Table.Row>` nodes; optional `minRows` prop reserves a stable height for paginated tables (see "Stable height across pages") |
@@ -49,6 +49,20 @@ token. Figma node `22969:49282` only ships one canonical density (`56 px`
 rows, `24 px` horizontal padding, `14 px` body font); if denser variants
 are added later, this will become a `size` prop.
 
+### Layout switches on `<Table>`
+
+Four props control the responsive layout and the horizontal scroll
+viewport. They're the only non-`children` surface on `<Table>` itself.
+
+| Prop | Default | What it does |
+|---|---|---|
+| `device="desktop" \| "mobile"` | `"desktop"` | Layout variant. Pick it from the viewport, not from a user preference. |
+| `scroll` | `true` on mobile or with `floatFirstColumn`, else `false` | Wraps the header + body rowgroups in one horizontal scroll viewport. |
+| `scrollBar` | `false` | Renders a visible scrollbar for that viewport. |
+| `floatFirstColumn` | `false` | Pins the first column to the left edge while the rest scrolls. Desktop only. |
+
+See "Scrolling" and "Responsive layout" below.
+
 ## What's NOT in the toolkit (and why)
 
 | Pattern | Where it lives | Why |
@@ -285,6 +299,10 @@ the same reason at the bottom.
 filter row above is visually separated from the column-header row
 without the consumer needing to add their own divider.
 
+These blocks stay **outside** the horizontal scroll viewport when
+`scroll` is on — only `<Table.Header>` and `<Table.Body>` scroll. See
+"Scrolling" below.
+
 ### B. Outside `<Table>`, above the card
 
 Useful when the bulk-selection bar should appear *above* the rounded card
@@ -387,8 +405,9 @@ height jump.
 The cell is hidden via `opacity: 0` + `pointer-events: none` (not
 `visibility: hidden`), so keyboard Tab still focuses descendants. Focusing
 a descendant flips the row's `focus-within` state and reveals the cell.
-On touch-only devices the cell is always visible — matches Figma's
-"Right cell actions are always visible on touch" spec.
+On touch-only devices — and whenever the table is rendered with
+`device="mobile"` — the cell is always visible, matching Figma's "Right
+cell actions are always visible on touch" spec.
 
 ## Truncation + tooltip on long values
 
@@ -418,10 +437,49 @@ when real data arrives. See the `LoadingState` story.
 
 Keeps screen reader output meaningful.
 
-## Scrolling
+## Responsive layout (`device`)
+
+`device` is a layout variant, not a runtime toggle for the user. Select it
+from the viewport — render `device="mobile"` below the mobile breakpoint
+and `device="desktop"` above it:
+
+```tsx
+<Table device={isNarrowViewport ? "mobile" : "desktop"}>...</Table>
+```
 
-The table is unopinionated about scroll. Wrap it (or the part you want to
-scroll) in a sized container.
+Because the toolkit is headless, the data, filters, sort order, and
+selection all live in consumer state — so they survive the switch for
+free. A user who selects three rows on desktop and rotates to a narrow
+viewport keeps that selection.
+
+The Mobile variant keeps the **same columnar layout** — it does not
+collapse rows into stacked cards. What changes:
+
+| | `desktop` | `mobile` |
+|---|---|---|
+| Horizontal scroll | Off unless you opt in | **On by default** |
+| `revealOnHover` cells | Hidden until hover / focus | **Always visible** (no hover on touch) |
+| `floatFirstColumn` | Honored | Ignored |
+
+What adapts *around* the table is consumer-side: the title block stacks,
+and the filter panel collapses to a search field plus a filter button that
+opens the remaining filters in a `<Modal type="bottom sheet">`. Keep a
+`<Badge>` on that button so active filters are visible from the collapsed
+state.
+
+**Mobile column order matters.** The leftmost columns are the ones read
+without scrolling, so put the row's identifying field first, then the
+values users compare most often. Push rarely-read columns to the right
+rather than removing them. This — not `floatFirstColumn` — is how
+readability is handled on mobile.
+
+**Touch targets.** Hover doesn't exist on touch, so row-level actions
+can't be revealed on hover. Keep the overflow (`⋯`) button permanently
+visible in each row and size it to meet the 44 × 44 px touch target.
+
+See the `MobileDevice` story.
+
+## Scrolling
 
 ### Vertical scroll with sticky header
 
@@ -429,13 +487,47 @@ scroll) in a sized container.
 `<Table.Body>` in a fixed-height `overflow-y: auto` container and the
 header stays pinned while rows scroll. See the `Scrollable` story.
 
-### Horizontal scroll
+### Horizontal scroll (`scroll`, `scrollBar`)
+
+When the columns exceed the available width, the table body scrolls
+horizontally. Set `scroll` and `<Table>` wraps the contiguous run of
+`<Table.Header>` / `<Table.Body>` children in a single scroll viewport, so
+the header row and the body scroll **in lockstep** and column labels stay
+aligned with their values.
+
+Everything else stays fixed to the container width: `<Table.Caption>`,
+`<Table.Footer>`, and any consumer-composed filter panel or item counter
+dropped in as a direct child (position A above).
 
-`<Table>` is intentionally opaque — it doesn't accept `style` or
-Box-level layout props, so the scroll viewport lives **outside**.
-Two-Box wrapper: the outer Box scrolls horizontally and the inner uses
-`min-width: max-content` so the table card grows to the natural width of
-its widest row.
+```tsx
+<Table scroll scrollBar>
+  <Table.Caption>Stays fixed while the rows scroll</Table.Caption>
+  <Table.Header>...</Table.Header>
+  <Table.Body>...</Table.Body>
+  <Table.Footer>...</Table.Footer>  {/* also stays fixed */}
+</Table>
+```
+
+`scroll` defaults to `true` on `device="mobile"` and whenever
+`floatFirstColumn` is on, and `false` otherwise — so desktop tables that
+already supply their own outer scroll container (below) are unaffected.
+
+`scrollBar` controls whether a **visible** scrollbar is rendered for that
+viewport, and is `false` by default (matching the Figma `ScrollBar` prop).
+Because it's off by default, an overflowing table gives no persistent
+signal that content continues to the right — decide deliberately rather
+than leaving the default in place. On desktop there is no swipe
+affordance, so without a visible scrollbar the overflowing columns can go
+unnoticed entirely. The scrollbar reflects the table body only.
+
+See the `BuiltInHorizontalScroll` story.
+
+#### Composing your own scroll viewport instead
+
+`scroll` is opt-in on desktop precisely so the pre-existing two-Box
+wrapper keeps working. The outer Box scrolls horizontally and the inner
+uses `min-width: max-content` so the table card grows to the natural width
+of its widest row:
 
 ```tsx
 <Box style={{ width: "100%", overflowX: "auto" }}>
@@ -452,12 +544,55 @@ cells spilling outside the card's white background when you scroll.
 `max-content` lets the browser compute the right value so the card and
 the cells stay the same width. See the `HorizontalScroll` story.
 
-### Frozen first column (optional)
+Don't combine the two: if you supply your own viewport, leave `scroll`
+off (or pass `scroll={false}` on mobile) so you don't nest one scroll
+container inside another.
+
+### Floating first column (`floatFirstColumn`, desktop only)
+
+When the columns overflow and the body scrolls horizontally, set
+`floatFirstColumn` and the first column holds its position at the left
+edge, keeping a shadow — the only cue that content continues underneath
+it. It implies the scroll viewport, so `scroll` is optional alongside it.
+
+```tsx
+<Table floatFirstColumn scrollBar>
+  <Table.Header>
+    <Table.Row>
+      <Table.Head width={200}>Name</Table.Head>
+      <Table.Head width={120}>Status</Table.Head>
+      {/* …more columns than fit… */}
+    </Table.Row>
+  </Table.Header>
+  <Table.Body>...</Table.Body>
+</Table>
+```
+
+Use it when the table has more columns than fit the viewport and the first
+column carries the row's identity (a name, an ID, an avatar) the user
+needs as a reference while reading columns to the right. Keep the pinned
+column narrow — only the first column can be pinned, and pinning a wide
+one leaves too little room for the scrolling area.
+
+Implementation notes:
+
+- It is the **real first cell** held in place inside the scrolling
+  container, not a duplicate overlay kept in step with the real column.
+  (Figma builds it as a separate absolutely-positioned layer only because
+  Figma can't express a sticky column any other way.)
+- The row's left gutter moves onto the pinned cell so it stays flush with
+  the container edge instead of leaving a transparent strip when scrolled.
+- The pinned cell paints the row's current background — including the
+  hover and `selected` states — so scrolled-under columns can't show
+  through it.
+- Only `<Table.Cell>` and `<Table.Head>` are pinned. If the first child of
+  a row is a custom wrapper, nothing is pinned for that row.
+
+**Desktop only.** On `device="mobile"` the prop is ignored: horizontal
+scrolling is already the reading mode there, so handle readability through
+column order instead (see "Responsive layout").
 
-Wrap the first cell in `position: sticky; left: 0` with a matching
-background color and z-index. The toolkit doesn't ship a `freezeFirst`
-prop because the visual treatment (border, shadow, background) varies per
-team.
+See the `FloatingFirstColumn` story.
 
 ## Virtualization
 
@@ -488,6 +623,9 @@ For native screens, pair `FlatList` with your own row + cell components.
 | Sort indicator | Built into `Table.Head` (symmetric dual-chevron + `aria-sort` for direction) |
 | Hover-reveal cells | `revealOnHover` prop on `Table.Cell` |
 | Sticky header | Built into `Table.Header` |
+| Responsive variant | `device="desktop" \| "mobile"` on `Table` |
+| Horizontal scroll | `scroll` + `scrollBar` on `Table` (or compose your own viewport) |
+| Frozen first column | `floatFirstColumn` on `Table` (desktop only) |
 | Theming | Toolkit theme tokens (`theme.sizing.table`) |
 | Cross-platform | Web only |
 | Bundles a row data engine | No |

package/native/index.d.mts

@@ -5,6 +5,13 @@ import { ThemeOverrideProps } from '@xsolla/xui-core';
 
 type TableCellAlign = "left" | "right" | "center";
 type TableCellPosition = "default" | "left" | "right";
+/**
+ * Layout variant of the table. Not a runtime user preference — pick it
+ * from the viewport (render `"mobile"` below the mobile breakpoint,
+ * `"desktop"` above it) per the Figma spec. Data, filters, sort order,
+ * and selection are owned by the consumer, so they survive the switch.
+ */
+type TableDevice = "desktop" | "mobile";
 /**
  * Structural primitives only:
  *
@@ -33,12 +40,63 @@ type TableCellPosition = "default" | "left" | "right";
  */
 /**
  * `<Table>` is intentionally opaque: no `style`, no Box-level props. The
- * surface is `children` only (plus theme overrides). To wrap the table in
- * a horizontal-scroll viewport, compose two outer Boxes around it — see
- * the `HorizontalScroll` story or the README "Horizontal scroll" section.
+ * surface is `children` plus the layout switches below (`device`,
+ * `scroll`, `scrollBar`, `floatFirstColumn`) and theme overrides.
+ *
+ * The scroll switches wrap the contiguous run of `<Table.Header>` /
+ * `<Table.Body>` children in a horizontal scroll viewport, so the header
+ * row and the body scroll in lockstep while `<Table.Caption>`,
+ * `<Table.Footer>`, and any consumer-composed filter panel / item counter
+ * stay fixed to the container width.
  */
 interface TableProps extends ThemeOverrideProps {
     children?: ReactNode;
+    /**
+     * Layout variant. Defaults to `"desktop"`.
+     *
+     * `"mobile"` keeps the same columnar layout — it does not collapse rows
+     * into stacked cards. What changes:
+     *
+     * - horizontal scrolling is on by default (this is how a wide table is
+     *   read on a narrow screen),
+     * - `<Table.Cell revealOnHover>` cells are always visible, because hover
+     *   does not exist on touch,
+     * - `floatFirstColumn` is ignored — order columns by importance instead
+     *   and put the row's identifying field first.
+     */
+    device?: TableDevice;
+    /**
+     * Wrap the header + body rowgroups in a horizontal scroll viewport.
+     *
+     * Defaults to `true` when `device="mobile"` or `floatFirstColumn` is on,
+     * and `false` otherwise — so existing desktop tables that supply their
+     * own outer scroll container (see the `HorizontalScroll` story) are
+     * unaffected. Set it explicitly to override.
+     */
+    scroll?: boolean;
+    /**
+     * Render a visible scrollbar for the horizontal scroll viewport.
+     * Defaults to `false`, matching the Figma `ScrollBar` prop.
+     *
+     * Because it is off by default, an overflowing table gives no persistent
+     * signal that content continues to the right. On desktop there is no
+     * swipe affordance, so turn it on whenever columns are expected to
+     * overflow.
+     */
+    scrollBar?: boolean;
+    /**
+     * Pin the first column to the left edge while the rest of the row
+     * scrolls horizontally. Defaults to `false`. **Desktop only** — ignored
+     * when `device="mobile"`.
+     *
+     * This is the real first cell held in place inside the scrolling
+     * container, not a duplicate overlay. Use it when the table has more
+     * columns than fit and the first column carries the row's identity (a
+     * name, an ID, an avatar) the user needs as a reference while reading
+     * columns to the right. Keep the pinned column narrow; only the first
+     * column can be pinned.
+     */
+    floatFirstColumn?: boolean;
     testID?: string;
 }
 interface TableCaptionProps extends BoxProps, ThemeOverrideProps {
@@ -102,6 +160,20 @@ interface TableRowProps extends BoxProps, ThemeOverrideProps {
      */
     onKeyDown?: (e: React.KeyboardEvent<Element>) => void;
 }
+/**
+ * Resolved sticky-column styling handed down from `<Table.Row>` to the
+ * first cell in the row when `floatFirstColumn` is on.
+ *
+ * @internal Not part of the public API.
+ */
+interface TableFloatingCellConfig {
+    /** Row background at its current state, so scrolled cells can't show through. */
+    background: string;
+    /** Row's horizontal gutter, moved onto the pinned cell so it stays flush. */
+    paddingLeft: number;
+    /** Elevation cue that content continues underneath the pinned column. */
+    shadow: string;
+}
 interface TableCellProps extends Omit<BoxProps, "position">, ThemeOverrideProps {
     children?: ReactNode;
     /** Cell text alignment. Defaults to "left". */
@@ -113,9 +185,16 @@ interface TableCellProps extends Omit<BoxProps, "position">, ThemeOverrideProps
     /**
      * Hide the cell until the parent row is hovered or focused (via `:focus-within`).
      * Typically used for `position="right"` action cells per Figma spec.
-     * Falls back to always-visible on touch devices.
+     * Falls back to always-visible on touch devices and when the enclosing
+     * `<Table>` is rendered with `device="mobile"`.
      */
     revealOnHover?: boolean;
+    /**
+     * @internal Injected by `<Table.Row>` on the first cell when the
+     * enclosing `<Table>` has `floatFirstColumn`. Do not set this manually —
+     * it is destructured away and never reaches the DOM.
+     */
+    __floating?: TableFloatingCellConfig;
     testID?: string;
 }
 interface TableHeadProps extends TableCellProps {
@@ -136,4 +215,4 @@ declare const Table: React__default.ForwardRefExoticComponent<TableProps & React
     Cell: React__default.ForwardRefExoticComponent<TableCellProps & React__default.RefAttributes<any>>;
 };
 
-export { Table, type TableBodyProps, type TableCaptionProps, type TableCellAlign, type TableCellPosition, type TableCellProps, type TableFooterProps, type TableHeadProps, type TableHeaderProps, type TableProps, type TableRowProps };
+export { Table, type TableBodyProps, type TableCaptionProps, type TableCellAlign, type TableCellPosition, type TableCellProps, type TableDevice, type TableFloatingCellConfig, type TableFooterProps, type TableHeadProps, type TableHeaderProps, type TableProps, type TableRowProps };

package/native/index.d.ts

@@ -5,6 +5,13 @@ import { ThemeOverrideProps } from '@xsolla/xui-core';
 
 type TableCellAlign = "left" | "right" | "center";
 type TableCellPosition = "default" | "left" | "right";
+/**
+ * Layout variant of the table. Not a runtime user preference — pick it
+ * from the viewport (render `"mobile"` below the mobile breakpoint,
+ * `"desktop"` above it) per the Figma spec. Data, filters, sort order,
+ * and selection are owned by the consumer, so they survive the switch.
+ */
+type TableDevice = "desktop" | "mobile";
 /**
  * Structural primitives only:
  *
@@ -33,12 +40,63 @@ type TableCellPosition = "default" | "left" | "right";
  */
 /**
  * `<Table>` is intentionally opaque: no `style`, no Box-level props. The
- * surface is `children` only (plus theme overrides). To wrap the table in
- * a horizontal-scroll viewport, compose two outer Boxes around it — see
- * the `HorizontalScroll` story or the README "Horizontal scroll" section.
+ * surface is `children` plus the layout switches below (`device`,
+ * `scroll`, `scrollBar`, `floatFirstColumn`) and theme overrides.
+ *
+ * The scroll switches wrap the contiguous run of `<Table.Header>` /
+ * `<Table.Body>` children in a horizontal scroll viewport, so the header
+ * row and the body scroll in lockstep while `<Table.Caption>`,
+ * `<Table.Footer>`, and any consumer-composed filter panel / item counter
+ * stay fixed to the container width.
  */
 interface TableProps extends ThemeOverrideProps {
     children?: ReactNode;
+    /**
+     * Layout variant. Defaults to `"desktop"`.
+     *
+     * `"mobile"` keeps the same columnar layout — it does not collapse rows
+     * into stacked cards. What changes:
+     *
+     * - horizontal scrolling is on by default (this is how a wide table is
+     *   read on a narrow screen),
+     * - `<Table.Cell revealOnHover>` cells are always visible, because hover
+     *   does not exist on touch,
+     * - `floatFirstColumn` is ignored — order columns by importance instead
+     *   and put the row's identifying field first.
+     */
+    device?: TableDevice;
+    /**
+     * Wrap the header + body rowgroups in a horizontal scroll viewport.
+     *
+     * Defaults to `true` when `device="mobile"` or `floatFirstColumn` is on,
+     * and `false` otherwise — so existing desktop tables that supply their
+     * own outer scroll container (see the `HorizontalScroll` story) are
+     * unaffected. Set it explicitly to override.
+     */
+    scroll?: boolean;
+    /**
+     * Render a visible scrollbar for the horizontal scroll viewport.
+     * Defaults to `false`, matching the Figma `ScrollBar` prop.
+     *
+     * Because it is off by default, an overflowing table gives no persistent
+     * signal that content continues to the right. On desktop there is no
+     * swipe affordance, so turn it on whenever columns are expected to
+     * overflow.
+     */
+    scrollBar?: boolean;
+    /**
+     * Pin the first column to the left edge while the rest of the row
+     * scrolls horizontally. Defaults to `false`. **Desktop only** — ignored
+     * when `device="mobile"`.
+     *
+     * This is the real first cell held in place inside the scrolling
+     * container, not a duplicate overlay. Use it when the table has more
+     * columns than fit and the first column carries the row's identity (a
+     * name, an ID, an avatar) the user needs as a reference while reading
+     * columns to the right. Keep the pinned column narrow; only the first
+     * column can be pinned.
+     */
+    floatFirstColumn?: boolean;
     testID?: string;
 }
 interface TableCaptionProps extends BoxProps, ThemeOverrideProps {
@@ -102,6 +160,20 @@ interface TableRowProps extends BoxProps, ThemeOverrideProps {
      */
     onKeyDown?: (e: React.KeyboardEvent<Element>) => void;
 }
+/**
+ * Resolved sticky-column styling handed down from `<Table.Row>` to the
+ * first cell in the row when `floatFirstColumn` is on.
+ *
+ * @internal Not part of the public API.
+ */
+interface TableFloatingCellConfig {
+    /** Row background at its current state, so scrolled cells can't show through. */
+    background: string;
+    /** Row's horizontal gutter, moved onto the pinned cell so it stays flush. */
+    paddingLeft: number;
+    /** Elevation cue that content continues underneath the pinned column. */
+    shadow: string;
+}
 interface TableCellProps extends Omit<BoxProps, "position">, ThemeOverrideProps {
     children?: ReactNode;
     /** Cell text alignment. Defaults to "left". */
@@ -113,9 +185,16 @@ interface TableCellProps extends Omit<BoxProps, "position">, ThemeOverrideProps
     /**
      * Hide the cell until the parent row is hovered or focused (via `:focus-within`).
      * Typically used for `position="right"` action cells per Figma spec.
-     * Falls back to always-visible on touch devices.
+     * Falls back to always-visible on touch devices and when the enclosing
+     * `<Table>` is rendered with `device="mobile"`.
      */
     revealOnHover?: boolean;
+    /**
+     * @internal Injected by `<Table.Row>` on the first cell when the
+     * enclosing `<Table>` has `floatFirstColumn`. Do not set this manually —
+     * it is destructured away and never reaches the DOM.
+     */
+    __floating?: TableFloatingCellConfig;
     testID?: string;
 }
 interface TableHeadProps extends TableCellProps {
@@ -136,4 +215,4 @@ declare const Table: React__default.ForwardRefExoticComponent<TableProps & React
     Cell: React__default.ForwardRefExoticComponent<TableCellProps & React__default.RefAttributes<any>>;
 };
 
-export { Table, type TableBodyProps, type TableCaptionProps, type TableCellAlign, type TableCellPosition, type TableCellProps, type TableFooterProps, type TableHeadProps, type TableHeaderProps, type TableProps, type TableRowProps };
+export { Table, type TableBodyProps, type TableCaptionProps, type TableCellAlign, type TableCellPosition, type TableCellProps, type TableDevice, type TableFloatingCellConfig, type TableFooterProps, type TableHeadProps, type TableHeaderProps, type TableProps, type TableRowProps };

package/native/index.js

@@ -344,6 +344,10 @@ var import_xui_core = require("@xsolla/xui-core");
 var import_xui_icons_base = require("@xsolla/xui-icons-base");
 var import_jsx_runtime3 = require("react/jsx-runtime");
 var TableRowGroupContext = (0, import_react.createContext)("body");
+var TableConfigContext = (0, import_react.createContext)({
+  device: "desktop",
+  floatFirstColumn: false
+});
 var RowRevealContext = (0, import_react.createContext)({
   revealed: true
 });
@@ -369,11 +373,35 @@ var Divider = ({ color }) => /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
     style: { flexShrink: 0 }
   }
 );
+var floatingCellStyle = (floating) => ({
+  position: "sticky",
+  left: 0,
+  zIndex: 2,
+  backgroundColor: floating.background,
+  paddingLeft: floating.paddingLeft,
+  boxShadow: floating.shadow
+});
 var TableRoot = (0, import_react.forwardRef)(
-  ({ children, testID, themeMode, themeProductContext }, ref) => {
+  ({
+    children,
+    device = "desktop",
+    scroll,
+    scrollBar = false,
+    floatFirstColumn = false,
+    testID,
+    themeMode,
+    themeProductContext
+  }, ref) => {
     const { theme } = (0, import_xui_core.useResolvedTheme)({ themeMode, themeProductContext });
     const sizing = theme.sizing.table;
-    return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+    const floatEnabled = floatFirstColumn && device !== "mobile";
+    const scrollEnabled = scroll ?? (device === "mobile" || floatEnabled);
+    const config = (0, import_react.useMemo)(
+      () => ({ device, floatFirstColumn: floatEnabled }),
+      [device, floatEnabled]
+    );
+    const content = scrollEnabled ? wrapRowGroupsInScrollViewport(children, scrollBar) : children;
+    return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(TableConfigContext.Provider, { value: config, children: /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
       Box,
       {
         ref,
@@ -390,9 +418,9 @@ var TableRoot = (0, import_react.forwardRef)(
           color: theme.colors.content.primary,
           overflow: "clip"
         },
-        children
+        children: content
       }
-    );
+    ) });
   }
 );
 TableRoot.displayName = "Table";
@@ -536,13 +564,14 @@ var TableRow = (0, import_react.forwardRef)(
     const { theme } = (0, import_xui_core.useResolvedTheme)({ themeMode, themeProductContext });
     const sizing = theme.sizing.table;
     const rowGroup = (0, import_react.useContext)(TableRowGroupContext);
+    const { device, floatFirstColumn } = (0, import_react.useContext)(TableConfigContext);
     const hoverCapable = useHoverCapable();
     const isHeaderRow = rowGroup === "header";
     const hoverable = hoverableProp ?? !isHeaderRow;
     const hideDivider = hideDividerProp ?? isHeaderRow;
     const [hovered, setHovered] = (0, import_react.useState)(false);
     const [focusedWithin, setFocusedWithin] = (0, import_react.useState)(false);
-    const revealed = hoverCapable ? hovered || focusedWithin : true;
+    const revealed = device === "mobile" || !hoverCapable ? true : hovered || focusedWithin;
     const handleMouseEnter = (0, import_react.useCallback)(
       (e) => {
         setHovered(true);
@@ -590,6 +619,26 @@ var TableRow = (0, import_react.forwardRef)(
     const rowHeight = isHeaderRow ? sizing.headerRowHeight : sizing.rowHeight;
     const rowPaddingHorizontal = isHeaderRow ? sizing.headerRowPaddingHorizontal : sizing.rowPaddingHorizontal;
     const ctxValue = (0, import_react.useMemo)(() => ({ revealed }), [revealed]);
+    const resolvedBg = hoverable && hovered ? theme.colors.background.secondary : baseBg;
+    let renderedChildren = children;
+    let didFloat = false;
+    if (floatFirstColumn) {
+      const childArray = import_react.default.Children.toArray(children);
+      const firstCellIndex = childArray.findIndex(
+        (c) => import_react.default.isValidElement(c) && (c.type === TableCell || c.type === TableHead)
+      );
+      if (firstCellIndex !== -1) {
+        didFloat = true;
+        const floating = {
+          background: resolvedBg,
+          paddingLeft: rowPaddingHorizontal,
+          shadow: theme.shadow.surface
+        };
+        renderedChildren = childArray.map(
+          (child, i) => i === firstCellIndex && import_react.default.isValidElement(child) ? import_react.default.cloneElement(child, { __floating: floating }) : child
+        );
+      }
+    }
     return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(RowRevealContext.Provider, { value: ctxValue, children: [
       /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
         Box,
@@ -614,8 +663,14 @@ var TableRow = (0, import_react.forwardRef)(
           onBlur: handleBlur,
           ...props,
           onKeyDown: handleKeyDown,
-          style,
-          children
+          style: {
+            // The pinned cell takes over the row's left gutter so it stays
+            // flush with the scroll container edge — without this the row
+            // padding scrolls away and leaves a transparent strip.
+            ...didFloat && { paddingLeft: 0 },
+            ...style
+          },
+          children: renderedChildren
         }
       ),
       !hideDivider && /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(Divider, { color: theme.colors.border.secondary })
@@ -651,6 +706,7 @@ var TableCell = (0, import_react.forwardRef)(
     width,
     grow,
     revealOnHover,
+    __floating,
     testID,
     themeMode,
     themeProductContext,
@@ -679,6 +735,7 @@ var TableCell = (0, import_react.forwardRef)(
           minWidth: 0,
           ...positionStyle,
           ...revealStyle,
+          ...__floating && floatingCellStyle(__floating),
           ...style
         },
         children: typeof children === "string" || typeof children === "number" ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
@@ -721,6 +778,7 @@ var TableHead = (0, import_react.forwardRef)(
     grow,
     sort,
     onSortToggle,
+    __floating,
     testID,
     themeMode,
     themeProductContext,
@@ -751,6 +809,7 @@ var TableHead = (0, import_react.forwardRef)(
           flex: width != null ? "0 0 auto" : grow ?? 1,
           minWidth: 0,
           ...positionStyle,
+          ...__floating && floatingCellStyle(__floating),
           ...style
         },
         children: [
@@ -805,6 +864,51 @@ var TableFooter = (0, import_react.forwardRef)(
   }
 );
 TableFooter.displayName = "Table.Footer";
+function wrapRowGroupsInScrollViewport(children, scrollBar) {
+  const viewportStyle = {
+    overflowX: "auto",
+    WebkitOverflowScrolling: "touch",
+    // `false` hides the scrollbar without disabling the scrolling itself.
+    ...scrollBar ? { scrollbarWidth: "thin" } : { scrollbarWidth: "none", msOverflowStyle: "none" }
+  };
+  const out = [];
+  let run = [];
+  const flush = () => {
+    if (run.length === 0) return;
+    const group = run;
+    run = [];
+    out.push(
+      /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+        Box,
+        {
+          width: "100%",
+          style: viewportStyle,
+          children: /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+            Box,
+            {
+              flexDirection: "column",
+              alignItems: "stretch",
+              style: { minWidth: "max-content" },
+              children: group
+            }
+          )
+        },
+        `__table-scroll-${out.length}`
+      )
+    );
+  };
+  import_react.default.Children.toArray(children).forEach((child) => {
+    const isRowGroup = import_react.default.isValidElement(child) && (child.type === TableHeader || child.type === TableBody);
+    if (isRowGroup) {
+      run.push(child);
+      return;
+    }
+    flush();
+    out.push(child);
+  });
+  flush();
+  return out;
+}
 var Table = Object.assign(TableRoot, {
   Caption: TableCaption,
   Header: TableHeader,