An open source design system that's fully customizable and agent ready
TypeScript
docs: Table plugin demos + search entries (+ fix: sticky-column cell backgrounds) (#3180)
Humberto Virtudesafb6240fc36f
diff --git a/.changeset/sticky-columns-background-polish.md b/.changeset/sticky-columns-background-polish.mdnew file mode 100644index 0000000000..2d06de23f1--- /dev/null+++ b/.changeset/sticky-columns-background-polish.md@@ -0,0 +1,18 @@+---+'@astryxdesign/core': patch+---++[fix] Polish `useTableStickyColumns` pinned-cell backgrounds so they match the+rest of the row:++- Pinned cells paint an opaque base via the overridable+ `--table-sticky-background` variable (defaults to `--color-background-card`),+ fixing a grey mismatch in themes/modes where `surface !== card` (e.g. neutral+ dark). Consumers on a different backdrop override the variable.+- The row's overlay (striping and/or hover) is replayed on the pinned cell via+ a background-image gradient. `TableRow` publishes its current overlay color as+ the inheritable `--table-row-overlay` variable, so pinned columns mirror the+ row exactly — striped when the table is striped, hover when enabled, nothing+ otherwise (no phantom stripes) — transitioning in lockstep with the row.+- `background-clip: padding-box` keeps the row divider visible on pinned cells.+@humbertovirtudesdiff --git a/.changeset/table-sticky-columns-demo.md b/.changeset/table-sticky-columns-demo.mdnew file mode 100644index 0000000000..99981439bb--- /dev/null+++ b/.changeset/table-sticky-columns-demo.md@@ -0,0 +1,15 @@+---+'@astryxdesign/cli': patch+---++[docs] Add rendered example blocks for the two column-axis Table plugin hooks,+shown on their own subcomponent pages:++- `useTableStickyColumns — Pinned Columns` (on /components/useTableStickyColumns)+- `useTableColumnResize — Draggable Columns` (on /components/useTableColumnResize)++Each renders a live, interactive Table in a width-constrained container so the+table's own horizontal scroll container is the scroller (required for sticky+columns to pin and for resize handles to behave). Blocks target the hook via+`exampleFor`, so they appear on the hook pages rather than the main Table page.+@humbertovirtudesdiff --git a/packages/cli/templates/blocks/components/Table/ColumnResizeHookUsage.doc.mjs b/packages/cli/templates/blocks/components/Table/ColumnResizeHookUsage.doc.mjsnew file mode 100644index 0000000000..033f0937b5--- /dev/null+++ b/packages/cli/templates/blocks/components/Table/ColumnResizeHookUsage.doc.mjs@@ -0,0 +1,14 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ exampleFor: 'useTableColumnResize',+ name: 'useTableColumnResize — Draggable Columns',+ displayName: 'useTableColumnResize — Draggable Columns',+ description:+ 'A Table using useTableColumnResize. Drag the right edge of any column header to resize; widths are committed on release. The last proportional column flexes to fill remaining space.',+ isReady: true,+ aspectRatio: 16 / 9,+ componentsUsed: ['Table'],+};diff --git a/packages/cli/templates/blocks/components/Table/ColumnResizeHookUsage.tsx b/packages/cli/templates/blocks/components/Table/ColumnResizeHookUsage.tsxnew file mode 100644index 0000000000..c248dbc803--- /dev/null+++ b/packages/cli/templates/blocks/components/Table/ColumnResizeHookUsage.tsx@@ -0,0 +1,59 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import {useState} from 'react';+import {+ Table,+ useTableColumnResize,+ proportional,+ pixel,+} from '@astryxdesign/core/Table';++interface User extends Record<string, unknown> {+ id: string;+ name: string;+ email: string;+ role: string;+}++const users: User[] = [+ {+ id: '1',+ name: 'Alice Johnson',+ email: '[email protected]',+ role: 'Engineer',+ },+ {id: '2', name: 'Bob Smith', email: '[email protected]', role: 'Designer'},+ {id: '3', name: 'Charlie Brown', email: '[email protected]', role: 'PM'},+ {id: '4', name: 'Diana Prince', email: '[email protected]', role: 'Engineer'},+ {id: '5', name: 'Eve Davis', email: '[email protected]', role: 'Analyst'},+];++const columns = [+ {key: 'name', header: 'Name'},+ {key: 'email', header: 'Email', width: proportional(2)},+ {key: 'role', header: 'Role', width: pixel(120)},+];++export default function ColumnResizeHookUsage() {+ const [columnWidths, setColumnWidths] = useState<Record<string, number>>({});++ const columnResize = useTableColumnResize({+ columnWidths,+ columns,+ onColumnResizeEnd: updates => {+ setColumnWidths(prev => ({...prev, ...updates}));+ },+ });++ return (+ <Table+ data={users}+ columns={columns}+ idKey="id"+ hasHover+ plugins={{columnResize}}+ />+ );+}diff --git a/packages/cli/templates/blocks/components/Table/StickyColumnsHookUsage.doc.mjs b/packages/cli/templates/blocks/components/Table/StickyColumnsHookUsage.doc.mjsnew file mode 100644index 0000000000..3cfb0aceb0--- /dev/null+++ b/packages/cli/templates/blocks/components/Table/StickyColumnsHookUsage.doc.mjs@@ -0,0 +1,14 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ exampleFor: 'useTableStickyColumns',+ name: 'useTableStickyColumns — Pinned Columns',+ displayName: 'useTableStickyColumns — Pinned Columns',+ description:+ 'A Table using useTableStickyColumns to pin the Name column to the start edge and Status to the end edge. Scroll horizontally — pinned columns stay in view with a soft shadow over the scrolling content.',+ isReady: true,+ aspectRatio: 16 / 9,+ componentsUsed: ['Table'],+};diff --git a/packages/cli/templates/blocks/components/Table/StickyColumnsHookUsage.tsx b/packages/cli/templates/blocks/components/Table/StickyColumnsHookUsage.tsxnew file mode 100644index 0000000000..98667534d9--- /dev/null+++ b/packages/cli/templates/blocks/components/Table/StickyColumnsHookUsage.tsx@@ -0,0 +1,104 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import {Table, useTableStickyColumns, pixel} from '@astryxdesign/core/Table';++interface Employee extends Record<string, unknown> {+ id: string;+ name: string;+ email: string;+ team: string;+ role: string;+ location: string;+ startDate: string;+ status: string;+}++const employees: Employee[] = [+ {+ id: '1',+ name: 'Alice Johnson',+ email: '[email protected]',+ team: 'Design Systems',+ role: 'Staff Engineer',+ location: 'San Francisco',+ startDate: '2019-03-12',+ status: 'Active',+ },+ {+ id: '2',+ name: 'Bob Smith',+ email: '[email protected]',+ team: 'Design Systems',+ role: 'Senior Designer',+ location: 'New York',+ startDate: '2020-07-01',+ status: 'Active',+ },+ {+ id: '3',+ name: 'Charlie Brown',+ email: '[email protected]',+ team: 'Platform',+ role: 'Engineering Manager',+ location: 'London',+ startDate: '2017-11-20',+ status: 'On leave',+ },+ {+ id: '4',+ name: 'Diana Prince',+ email: '[email protected]',+ team: 'Platform',+ role: 'Staff Engineer',+ location: 'Remote',+ startDate: '2021-01-15',+ status: 'Active',+ },+ {+ id: '5',+ name: 'Eve Davis',+ email: '[email protected]',+ team: 'Growth',+ role: 'Product Engineer',+ location: 'Berlin',+ startDate: '2022-05-30',+ status: 'Active',+ },+];++// Wide fixed-width columns so the table overflows and scrolls horizontally,+// keeping the pinned Name (start) and Status (end) columns in view.+const columns = [+ {key: 'name', header: 'Name', width: pixel(180)},+ {key: 'email', header: 'Email', width: pixel(220)},+ {key: 'team', header: 'Team', width: pixel(180)},+ {key: 'role', header: 'Role', width: pixel(200)},+ {key: 'location', header: 'Location', width: pixel(160)},+ {key: 'startDate', header: 'Start date', width: pixel(140)},+ {key: 'status', header: 'Status', width: pixel(140)},+];++export default function StickyColumnsHookUsage() {+ const stickyColumns = useTableStickyColumns<Employee>({+ startKeys: ['name'],+ endKeys: ['status'],+ });++ return (+ // Constrain the width so the Table's own horizontal scroll container is+ // narrower than its columns — that scroll container is what sticky columns+ // pin against. Without a width cap the table renders full-width and never+ // scrolls internally, so nothing sticks.+ <div style={{width: 560, maxWidth: '100%'}}>+ <Table+ data={employees}+ columns={columns}+ idKey="id"+ hasHover+ plugins={{stickyColumns}}+ />+ </div>+ );+}diff --git a/packages/core/src/Table/TableRow.tsx b/packages/core/src/Table/TableRow.tsxindex b752a845f0..f00f5cd8dd 100644--- a/packages/core/src/Table/TableRow.tsx+++ b/packages/core/src/Table/TableRow.tsx@@ -42,6 +42,13 @@ const stripedRowStyles = stylex.create({default: null,':nth-child(even)': colorVars['--color-background-muted'],},+ // Publish the row's current overlay color as an inheritable variable so+ // pinned/sticky cells (which paint an opaque background over the otherwise+ // transparent row) can replay the exact same striping. Unset on odd rows.+ '--table-row-overlay': {+ default: null,+ ':nth-child(even)': colorVars['--color-background-muted'],+ },},});@@ -53,6 +60,12 @@ const hoverRowStyles = stylex.create({'@media (hover: hover)': colorVars['--color-overlay-hover'],},},+ '--table-row-overlay': {+ default: null,+ ':hover': {+ '@media (hover: hover)': colorVars['--color-overlay-hover'],+ },+ },transitionProperty: 'background-color',transitionDuration: durationVars['--duration-fast'],transitionTimingFunction: easeVars['--ease-standard'],@@ -68,6 +81,13 @@ const stripedHoverRowStyles = stylex.create({'@media (hover: hover)': colorVars['--color-overlay-hover'],},},+ '--table-row-overlay': {+ default: null,+ ':nth-child(even)': colorVars['--color-background-muted'],+ ':hover': {+ '@media (hover: hover)': colorVars['--color-overlay-hover'],+ },+ },transitionProperty: 'background-color',transitionDuration: durationVars['--duration-fast'],transitionTimingFunction: easeVars['--ease-standard'],diff --git a/packages/core/src/Table/plugins/stickyColumns/useTableStickyColumns.tsx b/packages/core/src/Table/plugins/stickyColumns/useTableStickyColumns.tsxindex 89d3d411fb..f2d64c72f6 100644--- a/packages/core/src/Table/plugins/stickyColumns/useTableStickyColumns.tsx+++ b/packages/core/src/Table/plugins/stickyColumns/useTableStickyColumns.tsx@@ -15,7 +15,7 @@import {useCallback, useMemo, useRef, type CSSProperties} from 'react';import * as stylex from '@stylexjs/stylex';-import {colorVars} from '../../../theme/tokens.stylex';+import {colorVars, durationVars, easeVars} from '../../../theme/tokens.stylex';import type {TableColumn,TablePlugin,@@ -75,12 +75,9 @@ function getColumnWidth(col: TableColumn<Record<string, unknown>>): number {}/**- * Columns pinned to the START edge, keyed by column key → cumulative inline- * offset in pixels. The pinned block is the CONTIGUOUS run of leading columns- * from index 0 through the last column whose key is in `startKeys` (inclusive),- * INCLUDING synthetic columns (selection checkbox, row-index, …) that sit to- * the start of the user's sticky column. Returns `null` when no start-sticky- * column is present or column context is unavailable.+ * Columns pinned to the START edge → cumulative inline offset (px). The pinned+ * block is the contiguous run from column 0 through the last key in `startKeys`+ * (inclusive of any synthetic columns before it). `null` if none / no context.*/function computeStartOffsets(columns: ReadonlyArray<TableColumn<Record<string, unknown>>> | undefined,@@ -108,12 +105,9 @@ function computeStartOffsets(}/**- * Mirror image of {@link computeStartOffsets} — columns pinned to the END edge,- * keyed by column key → cumulative inline-end offset. The pinned block is the- * CONTIGUOUS run of trailing columns from the FIRST column whose key is in- * `endKeys` through the last column (inclusive). Offsets accumulate from the- * end edge — the last column gets `0`, its neighbor gets that column's width,- * etc. Returns `null` when no end-sticky column is present.+ * Mirror of {@link computeStartOffsets} for the END edge — contiguous run from+ * the first key in `endKeys` through the last column, offsets accumulating from+ * the end (last column = 0). `null` if none.*/function computeEndOffsets(columns: ReadonlyArray<TableColumn<Record<string, unknown>>> | undefined,@@ -169,31 +163,37 @@ function resolveStickySide(// Styles// =============================================================================-// CSS variables toggled on the scroll container by the layout ref. The cell-// ::after shadows read these, so each edge's shadow only shows when there is-// horizontally-scrolled content hidden behind that edge. We use CSS variables-// (not stylex.when.ancestor) because StyleX ancestor selectors support pseudo--// classes only, not attribute/className matching — a CSS variable inherited-// from the scroll container is the supported way to gate descendant styles on-// container scroll state.+// Scroll-state CSS variables set on the scroll container by the layout ref;+// the cell ::after shadows read them so each edge's shadow only shows when+// content is hidden behind it. (A variable, not stylex.when.ancestor, because+// StyleX ancestor selectors are pseudo-class only — not scroll state.)const SHADOW_VAR_START = '--table-sticky-shadow-start';const SHADOW_VAR_END = '--table-sticky-shadow-end';const stickyStyles = stylex.create({cell: {position: 'sticky',- // Pinned cells must be opaque so scrolling content doesn't show through.- backgroundColor: colorVars['--color-background-surface'],- // Clip the background to the padding box so it doesn't paint over the- // cell's (translucent, collapsed) bottom/right divider border. Sticky cells- // sit above regular cells, so without this the opaque background would hide- // the row divider on the pinned column.+ // Opaque base (overridable; defaults to the card token, the common+ // container) so scrolled content doesn't show through the pinned column.+ backgroundColor: `var(--table-sticky-background, ${colorVars['--color-background-card']})`,+ // Replay the row's overlay on a ::before layer (above the base, below text)+ // so the pinned column mirrors the row's striping/hover exactly via+ // --table-row-overlay. Transitions background-COLOR (not background-image)+ // so hover stays smooth at rest, not just when GPU-promoted while scrolled.+ '::before': {+ content: '""',+ position: 'absolute',+ inset: 0,+ zIndex: -1,+ pointerEvents: 'none',+ backgroundColor: 'var(--table-row-overlay, transparent)',+ transitionProperty: 'background-color',+ transitionDuration: durationVars['--duration-fast'],+ transitionTimingFunction: easeVars['--ease-standard'],+ },+ // padding-box keeps the base off the cell's collapsed divider border.backgroundClip: 'padding-box',- // Default table cells are `overflow: hidden` (for text truncation), which- // would clip the shadow ::after that bleeds past the pinned edge. Sticky- // cells opt back into visible overflow so the shadow can render outside.- // Text truncation on sticky columns still works because the cell width is- // fixed and the inner content wraps/ellipsizes within it.+ // Sticky cells need visible overflow so the shadow ::after can bleed out.overflow: 'visible',},headerCell: {@@ -205,19 +205,12 @@ const stickyStyles = stylex.create({},});-// A soft drop shadow over the scrolling region, matching the EPS sticky-column-// treatment. `border-collapse: collapse` tables (Astryx Table uses-// table-layout: fixed + border-collapse: collapse) do NOT paint `box-shadow`-// on the cells themselves in Chromium, so the shadow is cast by a ::after strip-// positioned just outside the pinned edge, filled with a soft gradient that-// fades from a shadow tint to transparent over the scrolled content. Sticky-// cells set `overflow: visible` (above) so this strip isn't clipped. Its-// opacity reads a CSS variable inherited from the scroll container, which the-// layout ref toggles between 0 and 1 on scroll so the shadow only shows when-// there is hidden content behind that edge.+// Soft drop shadow over the scrolling region (matches the EPS sticky treatment).+// border-collapse tables don't paint box-shadow on cells in Chromium, so it's a+// ::after gradient strip just past the pinned edge (visible thanks to the cell's+// overflow: visible). Opacity is gated by the scroll-state variable above.const SHADOW_WIDTH = '6px';-// A subtle tint that fades to transparent. --color-shadow is only ~10% alpha,-// which reads too faintly here, so use a slightly stronger but still soft tint.+// --color-shadow is only ~10% alpha (too faint here); use a slightly stronger soft tint.const SHADOW_TINT = 'light-dark(rgba(0, 0, 0, 0.12), rgba(0, 0, 0, 0.32))';const shadowStyles = stylex.create({// start-pinned: shadow falls to the right (inline-end), over scrolled contentdiff --git a/packages/core/src/Table/useTableColumnResize.doc.mjs b/packages/core/src/Table/useTableColumnResize.doc.mjsnew file mode 100644index 0000000000..54f12f53bd--- /dev/null+++ b/packages/core/src/Table/useTableColumnResize.doc.mjs@@ -0,0 +1,96 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'useTableColumnResize',+ subComponentOf: 'Table',+ displayName: 'useTableColumnResize',+ description:+ 'Hook that returns a TablePlugin adding draggable resize handles to column header borders. Supports pointer + keyboard (WAI-ARIA window splitter) resizing, RTL, per-column min/max widths, and proportional-column preservation (resizes the neighbor so the table stays full-width). Commits widths on release.',+ props: [+ {+ name: 'columnWidths',+ type: 'Record<string, number>',+ description:+ 'Controlled pixel-width overrides keyed by column key. When a key is present it overrides the column\'s declared width.',+ },+ {+ name: 'onColumnResizeEnd',+ type: '(updates: Record<string, number>) => void',+ description:+ 'Called when a resize completes (pointerup / Enter). Receives a map of every column key whose width changed — merge it into your columnWidths state.',+ },+ {+ name: 'minWidth',+ type: 'number',+ description:+ 'Global minimum column width in pixels during resize. Overrides per-column defaults when set.',+ },+ {+ name: 'maxWidth',+ type: 'number',+ description: 'Global maximum column width in pixels during resize.',+ default: 'Infinity',+ },+ {+ name: 'columns',+ type: 'TableColumn<T>[]',+ description:+ 'Column definitions — needed to derive per-column min widths and detect proportional vs pixel columns for neighbor/last-column resize behavior.',+ },+ ],+};++export const docsZh = {+ name: 'useTableColumnResize',+ displayName: 'useTableColumnResize',+ description:+ '返回 TablePlugin 的 Hook,为列表头边框添加可拖动的调整手柄。支持指针 + 键盘(WAI-ARIA 窗口分隔符)调整、RTL、每列最小/最大宽度,以及比例列保留(调整相邻列以保持表格全宽)。在释放时提交宽度。',+ props: [+ {+ name: 'columnWidths',+ type: 'Record<string, number>',+ description: '受控的像素宽度覆盖,按列键索引。存在某键时会覆盖该列声明的宽度。',+ },+ {+ name: 'onColumnResizeEnd',+ type: '(updates: Record<string, number>) => void',+ description:+ '调整完成时(pointerup / Enter)调用。接收所有宽度发生变化的列键的映射——将其合并到你的 columnWidths 状态中。',+ },+ {+ name: 'minWidth',+ type: 'number',+ description: '调整期间的全局最小列宽(像素)。设置后覆盖每列默认值。',+ },+ {+ name: 'maxWidth',+ type: 'number',+ description: '调整期间的全局最大列宽(像素)。',+ default: 'Infinity',+ },+ {+ name: 'columns',+ type: 'TableColumn<T>[]',+ description:+ '列定义——用于推导每列最小宽度,并区分比例列与像素列以确定相邻列/末列的调整行为。',+ },+ ],+};++export const docsDense = {+ name: 'useTableColumnResize',+ displayName: 'useTableColumnResize',+ description:+ 'Hook returning TablePlugin w/ draggable column resize handles. Pointer + keyboard (WAI-ARIA splitter), RTL, per-column min/max, proportional-preserving (resizes neighbor). Commits on release.',+ propDescriptions: {+ columnWidths: 'Controlled pixel-width overrides keyed by column key.',+ onColumnResizeEnd:+ 'Called on resize end; receives map of all changed column widths to merge into state.',+ minWidth: 'Global min column width (px) during resize.',+ maxWidth: 'Global max column width (px) during resize. Default Infinity.',+ columns:+ 'Column defs — derive per-column mins + proportional/pixel detection for neighbor/last-column behavior.',+ },+};diff --git a/packages/core/src/Table/useTableStickyColumns.doc.mjs b/packages/core/src/Table/useTableStickyColumns.doc.mjsnew file mode 100644index 0000000000..0a142d8acd--- /dev/null+++ b/packages/core/src/Table/useTableStickyColumns.doc.mjs@@ -0,0 +1,59 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'useTableStickyColumns',+ subComponentOf: 'Table',+ displayName: 'useTableStickyColumns',+ description:+ 'Hook that returns a TablePlugin which pins a contiguous run of columns to the start and/or end edge of the table. Pinned columns get cumulative offsets and a soft, scroll-aware shadow over the scrolling content. An empty config ({}) is a valid no-op that pins nothing.',+ props: [+ {+ name: 'startKeys',+ type: 'string[]',+ description:+ 'Column keys pinned to the start (inline-start / left in LTR) edge — the contiguous run from the first column through the last listed key.',+ },+ {+ name: 'endKeys',+ type: 'string[]',+ description:+ 'Column keys pinned to the end (inline-end / right in LTR) edge — the contiguous run from the first listed key through the last column.',+ },+ ],+};++export const docsZh = {+ name: 'useTableStickyColumns',+ displayName: 'useTableStickyColumns',+ description:+ '返回 TablePlugin 的 Hook,将一组连续的列固定到表格的起始和/或结束边缘。固定的列具有累积偏移量,并在滚动内容上方显示柔和的、随滚动感知的阴影。空配置 ({}) 是有效的空操作,不固定任何列。',+ props: [+ {+ name: 'startKeys',+ type: 'string[]',+ description:+ '固定到起始(inline-start / LTR 中为左侧)边缘的列键——从第一列到最后列出的键的连续范围。',+ },+ {+ name: 'endKeys',+ type: 'string[]',+ description:+ '固定到结束(inline-end / LTR 中为右侧)边缘的列键——从第一个列出的键到最后一列的连续范围。',+ },+ ],+};++export const docsDense = {+ name: 'useTableStickyColumns',+ displayName: 'useTableStickyColumns',+ description:+ 'Hook returning TablePlugin that pins contiguous column runs to start/end edges w/ cumulative offsets + scroll-aware shadow. Empty config = no-op.',+ propDescriptions: {+ startKeys:+ 'Column keys pinned to the start edge (contiguous run from column 0 through the last listed key).',+ endKeys:+ 'Column keys pinned to the end edge (contiguous run from the first listed key through the last column).',+ },+};diff --git a/packages/core/src/theme/derivedVarRegistry.test.ts b/packages/core/src/theme/derivedVarRegistry.test.tsindex 92771f7f53..f323bd9d86 100644--- a/packages/core/src/theme/derivedVarRegistry.test.ts+++ b/packages/core/src/theme/derivedVarRegistry.test.ts@@ -64,6 +64,10 @@ const STRUCTURAL_VARS = new Set(['--indicator-color','--indicator-width','--table-resize-height',+ // sticky-columns plugin: opaque backdrop (overridable) + the row overlay it+ // replays on pinned cells. Structural/runtime, not themeable design tokens.+ '--table-sticky-background',+ '--table-row-overlay','--separator-display','--astryx-section-padding',]);