@astryxdesign/core 0.1.0 → 0.1.1-canary.129bf0e

package/src/Pagination/Pagination.tsx

@@ -19,7 +19,7 @@
  *   label, data-testid, xstyle
  */
 
-import {useTransition} from 'react';
+import {useOptimistic, useTransition} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {
   colorVars,
@@ -349,16 +349,22 @@ export function Pagination({
   style,
   ref,
 }: PaginationProps) {
-  const [isPending, startTransition] = useTransition();
+  const [, startTransition] = useTransition();
+
+  // Track the page optimistically so rapid prev/next clicks advance from the
+  // in-flight target instead of stalling on the last committed page.
+  const [optimisticPage, setOptimisticPage] = useOptimistic(page);
 
   // Compute pagination state
   const computedTotalPages =
     totalPagesProp ??
     (totalItems != null ? Math.ceil(totalItems / pageSize) : undefined);
 
-  const hasPrevious = page > 1;
+  const hasPrevious = optimisticPage > 1;
   const hasNext =
-    computedTotalPages != null ? page < computedTotalPages : (hasMore ?? false);
+    computedTotalPages != null
+      ? optimisticPage < computedTotalPages
+      : (hasMore ?? false);
 
   // Return null for empty state
   if (totalItems != null && totalItems <= 0) {
@@ -368,48 +374,47 @@ export function Pagination({
     return null;
   }
 
+  // Interruptible: re-clicking before the transition settles starts a fresh one
+  // with the next optimistic page rather than being dropped, so there is no
+  // re-entry guard.
   const handlePageChange = (newPage: number) => {
-    if (isDisabled || isPending) {
+    if (isDisabled) {
       return;
     }
+    // Keep onChange urgent so controlled page state updates in the same commit
+    // as the click; only the optimistic indicator and changeAction defer.
     onChange(newPage);
-    if (changeAction) {
-      startTransition(async () => {
-        await changeAction(newPage);
-      });
-    }
+    startTransition(async () => {
+      setOptimisticPage(newPage);
+      await changeAction?.(newPage);
+    });
   };
 
   const handlePrevious = () => {
     if (hasPrevious) {
-      handlePageChange(page - 1);
+      handlePageChange(optimisticPage - 1);
     }
   };
 
   const handleNext = () => {
     if (hasNext) {
-      handlePageChange(page + 1);
+      handlePageChange(optimisticPage + 1);
     }
   };
 
   const handlePageSizeChange = (value: string) => {
     const newSize = Number(value);
     onPageSizeChange?.(newSize);
-    // Reset to page 1 when page size changes
-    onChange(1);
-    if (changeAction) {
-      startTransition(async () => {
-        await changeAction(1);
-      });
-    }
+    // Reset to page 1 when page size changes.
+    handlePageChange(1);
   };
 
   // Item range for count display
-  const rangeStart = (page - 1) * pageSize + 1;
+  const rangeStart = (optimisticPage - 1) * pageSize + 1;
   const rangeEnd =
     totalItems != null
-      ? Math.min(page * pageSize, totalItems)
-      : page * pageSize;
+      ? Math.min(optimisticPage * pageSize, totalItems)
+      : optimisticPage * pageSize;
 
   const buttonSize = size === 'sm' ? 'sm' : 'md';
   const isSm = size === 'sm';
@@ -421,7 +426,7 @@ export function Pagination({
           return null;
         }
         const pageRange = generatePageRange(
-          page,
+          optimisticPage,
           computedTotalPages,
           siblingCount,
         );
@@ -443,7 +448,7 @@ export function Pagination({
                   </span>
                 );
               }
-              const isActive = item === page;
+              const isActive = item === optimisticPage;
               return (
                 <Button
                   key={item}
@@ -483,7 +488,7 @@ export function Pagination({
         return (
           <span {...stylex.props(styles.infoText)}>
             <Text type="body" size="sm" color="secondary">
-              {`Page ${page} of ${computedTotalPages}`}
+              {`Page ${optimisticPage} of ${computedTotalPages}`}
             </Text>
           </span>
         );
@@ -503,18 +508,18 @@ export function Pagination({
                 key={i + 1}
                 type="button"
                 aria-label={`Go to page ${i + 1}`}
-                aria-current={i + 1 === page ? 'page' : undefined}
+                aria-current={i + 1 === optimisticPage ? 'page' : undefined}
                 onClick={() => handlePageChange(i + 1)}
                 disabled={isDisabled}
                 {...mergeProps(
                   themeProps('pagination-dot', {
-                    active: i + 1 === page ? 'active' : null,
+                    active: i + 1 === optimisticPage ? 'active' : null,
                     size,
                   }),
                   stylex.props(
                     styles.dot,
                     isSm && styles.dotSm,
-                    i + 1 === page && styles.dotActive,
+                    i + 1 === optimisticPage && styles.dotActive,
                     isDisabled && styles.dotDisabled,
                   ),
                 )}

package/src/Resizable/Resizable.doc.mjs

@@ -27,7 +27,7 @@ export const docs = {
       {
         guidance: true,
         description:
-          'Use useResizable() with existing XDS layout components. ' +
+          'Use useResizable() with existing Astryx layout components. ' +
           'Pass the returned props to the resizable prop on LayoutPanel or SideNav.',
       },
       {
@@ -147,7 +147,7 @@ export const docs = {
           type: 'boolean',
           description:
             'Show the pill grip at rest instead of only on hover. Use when discoverability is important.',
-          default: 'false',
+          default: 'true',
         },
         {
           name: 'pillPlacement',
@@ -195,7 +195,7 @@ export const docsDense = {
     description:
       'Hook-based resizable panel system. useResizable() manages size state; ResizeHandle provides interactive pill-grip separator. Pass resize props to existing layout components via their resizable prop.',
     bestPractices: [
-      {guidance: true, description: 'Use useResizable() w/ existing XDS layout components. Pass returned props to resizable prop on LayoutPanel or SideNav.'},
+      {guidance: true, description: 'Use useResizable() w/ existing Astryx layout components. Pass returned props to resizable prop on LayoutPanel or SideNav.'},
       {guidance: true, description: 'Provide accessible label on each ResizeHandle when multiple handles exist (e.g. "Resize sidebar", "Resize terminal").'},
       {guidance: false, description: 'Wrap panels in extra container components for resize. Hook-first architecture avoids extra DOM; use it directly on existing components.'},
     ],

package/src/Resizable/useResizable.ts

@@ -107,10 +107,6 @@ export interface ResizableProps {
 const DEFAULT_MIN = 50;
 const DEFAULT_COLLAPSED_SIZE = 40;
 const STORAGE_PREFIX = 'astryx-resizable:';
-// Legacy key prefix read during the compat window so persisted panel sizes
-// survive the xds -> astryx rename. Read-only fallback; we always write the
-// new prefix. Removed at final cutover.
-const LEGACY_STORAGE_PREFIX = 'xds-resizable:';
 
 // =============================================================================
 // Helpers
@@ -147,9 +143,7 @@ function loadPersistedSize(key: string): number | null {
     return null;
   }
   try {
-    const raw =
-      localStorage.getItem(STORAGE_PREFIX + key) ??
-      localStorage.getItem(LEGACY_STORAGE_PREFIX + key);
+    const raw = localStorage.getItem(STORAGE_PREFIX + key);
     if (raw != null) {
       const parsed = JSON.parse(raw);
       if (typeof parsed === 'number') {

package/src/Selector/Selector.doc.mjs

@@ -84,11 +84,13 @@ export const docs = {
       name: 'isDisabled',
       type: 'boolean',
       description: 'Disables the selector.',
+      default: 'false',
     },
     {
       name: 'isLabelHidden',
       type: 'boolean',
       description: 'Visually hides the label while keeping it accessible.',
+      default: 'false',
     },
     {
       name: 'description',
@@ -99,11 +101,13 @@ export const docs = {
       name: 'isOptional',
       type: 'boolean',
       description: 'Marks the field as optional.',
+      default: 'false',
     },
     {
       name: 'isRequired',
       type: 'boolean',
       description: 'Marks the field as required.',
+      default: 'false',
     },
     {
       name: 'status',

package/src/Selector/Selector.tsx

@@ -107,12 +107,11 @@ const styles = stylex.create({
     lineHeight: 'inherit',
     color: 'inherit',
     cursor: 'pointer',
-    outline: {
-      default: 'none',
-      ':focus-visible': `${borderVars['--border-width']} solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: '0',
-    borderRadius: radiusVars['--radius-element'],
+    // The wrapper (inputWrapperStyles.base) renders the focus ring via
+    // :focus-within when this button is focused, matching TextInput/NumberInput.
+    // The button must not draw its own :focus-visible outline or the two stack
+    // into a doubled ring over the trigger.
+    outline: 'none',
   },
   triggerPlaceholder: {
     color: colorVars['--color-text-secondary'],

package/src/Skeleton/Skeleton.doc.mjs

@@ -33,7 +33,17 @@ export const docs = {
         'Index for staggered animation timing. For element at index n, animation starts at DELAY_TIME + (STAGGER_TIME × n).',
       default: '0',
     },
-  ],  theming: {
+  ],
+  playground: {
+    // Skeleton width/height default to '100%', which collapses to a zero-size
+    // (invisible) element in the properties-tab preview. Give the example
+    // explicit pixel dimensions so the shimmer placeholder is visible.
+    defaults: {
+      width: 320,
+      height: 80,
+    },
+  },
+  theming: {
     targets: [
       {className: 'astryx-skeleton'},
     ],

package/src/Table/BaseTable.tsx

@@ -26,6 +26,7 @@ import type {
   HeaderCellRenderProps,
   BodyRowRenderProps,
   BodyCellRenderProps,
+  ScrollWrapperRenderProps,
   TableRowComponentProps,
   TableCellComponentProps,
   TableHeaderCellComponentProps,
@@ -152,22 +153,27 @@ function TableRowInner<T extends Record<string, unknown>>({
   CellComponent,
 }: TableRowProps<T>): ReactElement {
   // Build cells first
-  const cells = columns.map(col => {
+  const cells = columns.map((col, columnIndex) => {
     // Apply column alignment to body cells
     const initialCellHtmlProps: Record<string, unknown> = {};
     if (col.align) {
       initialCellHtmlProps.style = {textAlign: col.align};
     }
 
+    const initialBodyCellRenderProps: BodyCellRenderProps = {
+      htmlProps: initialCellHtmlProps,
+      styles: [],
+      columnIndex,
+      columns: columns as ReadonlyArray<TableColumn<Record<string, unknown>>>,
+    };
     const cellRenderProps = applyPlugins(
       plugins,
       p => p.transformBodyCell,
-      {
-        htmlProps: initialCellHtmlProps,
-        styles: [],
-      } satisfies BodyCellRenderProps,
+      initialBodyCellRenderProps,
       col,
       item,
+      columnIndex,
+      columns,
     );
 
     const isDefaultRenderer = !col.renderCell;
@@ -313,8 +319,7 @@ function BaseTableInner<T extends Record<string, unknown>>({
   // Use stable empty array when no plugins provided
   const plugins = pluginsProp ?? (EMPTY_PLUGINS as TablePlugin<T>[]);
 
-  const RowComponent =
-    TableRow as React.ComponentType<TableRowComponentProps>;
+  const RowComponent = TableRow as React.ComponentType<TableRowComponentProps>;
   const CellComponent =
     TableCell as React.ComponentType<TableCellComponentProps>;
   const HeaderCellComponent =
@@ -354,7 +359,7 @@ function BaseTableInner<T extends Record<string, unknown>>({
   } satisfies TableRenderProps);
 
   // --- Plugin pipeline: header cells ---
-  const headerCells = resolvedColumns.map(col => {
+  const headerCells = resolvedColumns.map((col, columnIndex) => {
     const headerContent = col.header ?? col.key;
 
     // Build initial htmlProps with column alignment if specified
@@ -365,15 +370,22 @@ function BaseTableInner<T extends Record<string, unknown>>({
       initialHeaderHtmlProps.style = {textAlign: col.align};
     }
 
+    const initialHeaderRenderProps: HeaderCellRenderProps = {
+      htmlProps: initialHeaderHtmlProps,
+      styles: [],
+      content: headerContent,
+      columnIndex,
+      columns: resolvedColumns as ReadonlyArray<
+        TableColumn<Record<string, unknown>>
+      >,
+    };
     const cellRenderProps = applyPlugins(
       plugins,
       p => p.transformHeaderCell,
-      {
-        htmlProps: initialHeaderHtmlProps,
-        styles: [],
-        content: headerContent,
-      } satisfies HeaderCellRenderProps,
+      initialHeaderRenderProps,
       col,
+      columnIndex,
+      resolvedColumns,
     );
 
     // Apply pre-computed column width styles on the <th>.
@@ -497,9 +509,7 @@ function BaseTableInner<T extends Record<string, unknown>>({
                 emptyState !== false && (
                   <tr>
                     <td colSpan={resolvedColumns.length}>
-                      {emptyState ?? (
-                        <EmptyState title="No data" isCompact />
-                      )}
+                      {emptyState ?? <EmptyState title="No data" isCompact />}
                     </td>
                   </tr>
                 )}
@@ -513,8 +523,29 @@ function BaseTableInner<T extends Record<string, unknown>>({
   // when columns exceed the container width. This wrapper sits between
   // the <table> and transformTableContext, so plugin chrome (pagination,
   // toolbars) renders outside the scroll area.
+  //
+  // Before rendering the wrapper, run the plugin `transformScrollWrapper`
+  // pipeline so plugins can attach a ref to the scroll container (scroll-aware
+  // sticky shadows, virtualization) and inject before/after chrome.
   if (ScrollWrapper) {
-    tableElement = <ScrollWrapper>{tableElement}</ScrollWrapper>;
+    const scrollWrapperRenderProps = applyPlugins(
+      plugins,
+      p => p.transformScrollWrapper,
+      {
+        htmlProps: {},
+        styles: [],
+      } satisfies ScrollWrapperRenderProps,
+    );
+
+    tableElement = (
+      <ScrollWrapper
+        htmlProps={scrollWrapperRenderProps.htmlProps}
+        styles={scrollWrapperRenderProps.styles}
+        beforeTable={scrollWrapperRenderProps.beforeTable}
+        afterTable={scrollWrapperRenderProps.afterTable}>
+        {tableElement}
+      </ScrollWrapper>
+    );
   }
 
   // Apply transformTableContext from each plugin.
@@ -527,10 +558,7 @@ function BaseTableInner<T extends Record<string, unknown>>({
       try {
         tableElement = plugin.transformTableContext(tableElement);
       } catch (error) {
-        console.error(
-          '[Table] Plugin threw in transformTableContext:',
-          error,
-        );
+        console.error('[Table] Plugin threw in transformTableContext:', error);
       }
     }
   }
@@ -556,9 +584,7 @@ function BaseTableInner<T extends Record<string, unknown>>({
  * />
  * ```
  */
-export const BaseTable = BaseTableInner as <
-  T extends Record<string, unknown>,
->(
+export const BaseTable = BaseTableInner as <T extends Record<string, unknown>>(
   props: BaseTableProps<T> & {ref?: Ref<HTMLTableElement>},
 ) => ReactElement;
 

package/src/Table/Table.doc.mjs

@@ -104,7 +104,7 @@ export const docs = {
       'Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.',
     bestPractices: [
       { guidance: true, description: 'Use density and divider variants to match the information density and scanning needs of your data.' },
-      { guidance: true, description: 'Compose rich cell content with XDS components like Badge, StatusDot, and Avatar via renderCell.' },
+      { guidance: true, description: 'Compose rich cell content with Astryx components like Badge, StatusDot, and Avatar via renderCell.' },
       { guidance: true, description: 'Set explicit width on every column using proportional() or pixel(). proportional(1) gives equal flex distribution with a 120px minimum that prevents columns from collapsing on narrow viewports. Omitting width skips the minimum.' },
       { guidance: false, description: 'Use a table for data without consistent columns. Use a list or card layout for heterogeneous content.' },
       { guidance: false, description: 'Enable every plugin at once. Add only the features your use case requires to keep the interface focused.' },
@@ -128,7 +128,7 @@ export const docsZh = {
       'Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.',
     bestPractices: [
       { guidance: true, description: 'Use density and divider variants to match the information density and scanning needs of your data.' },
-      { guidance: true, description: 'Compose rich cell content with XDS components like Badge, StatusDot, and Avatar via renderCell.' },
+      { guidance: true, description: 'Compose rich cell content with Astryx components like Badge, StatusDot, and Avatar via renderCell.' },
       { guidance: false, description: 'Use a table for data without consistent columns. Use a list or card layout for heterogeneous content.' },
       { guidance: false, description: 'Enable every plugin at once. Add only the features your use case requires to keep the interface focused.' },
     ],
@@ -151,7 +151,7 @@ export const docsDense = {
       'Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.',
     bestPractices: [
       { guidance: true, description: 'Use density and divider variants to match the information density and scanning needs of your data.' },
-      { guidance: true, description: 'Compose rich cell content with XDS components like Badge, StatusDot, and Avatar via renderCell.' },
+      { guidance: true, description: 'Compose rich cell content with Astryx components like Badge, StatusDot, and Avatar via renderCell.' },
       { guidance: true, description: 'Set explicit width on every column via proportional() or pixel(). proportional(1) = equal flex w/ 120px min preventing collapse on narrow viewports. Omitting width skips the minimum.' },
       { guidance: false, description: 'Use a table for data without consistent columns. Use a list or card layout for heterogeneous content.' },
       { guidance: false, description: 'Enable every plugin at once. Add only the features your use case requires to keep the interface focused.' },

package/src/Table/Table.tsx

@@ -30,6 +30,7 @@ import type {
   TablePlugin,
   TableRenderProps,
 } from './types';
+import type {StyleXStyles} from '../theme/types';
 
 // =============================================================================
 // Table Types
@@ -131,17 +132,37 @@ const scrollWrapperStyles = stylex.create({
   },
 });
 
-function TableScrollWrapper({children}: {children: React.ReactNode}) {
+function TableScrollWrapper({
+  children,
+  htmlProps,
+  styles: pluginStyles,
+  beforeTable,
+  afterTable,
+}: {
+  children: React.ReactNode;
+  htmlProps?: React.HTMLAttributes<HTMLDivElement> & {
+    ref?: React.Ref<HTMLDivElement>;
+  };
+  styles?: StyleXStyles[];
+  beforeTable?: React.ReactNode;
+  afterTable?: React.ReactNode;
+}) {
+  const {ref, ...restHtmlProps} = htmlProps ?? {};
   return (
     <div
+      ref={ref}
+      {...restHtmlProps}
       {...mergeProps(
         themeProps('table-scroll-wrapper'),
         stylex.props(
           scrollWrapperStyles.base,
           scrollWrapperStyles.containerBleed,
+          ...(pluginStyles ?? []),
         ),
       )}>
+      {beforeTable}
       {children}
+      {afterTable}
     </div>
   );
 }

package/src/Table/index.ts

@@ -27,6 +27,7 @@ export {useTablePagination, paginateData} from './plugins/pagination';
 export {useTableColumnSettings} from './plugins/columnSettings';
 export {useTableColumnSettingsState} from './plugins/columnSettings';
 export {useTableColumnResize} from './plugins/columnResize';
+export {useTableStickyColumns} from './plugins/stickyColumns';
 export {
   useTableFiltering,
   useTableFilterState,
@@ -53,6 +54,7 @@ export type {
   HeaderCellRenderProps,
   BodyRowRenderProps,
   BodyCellRenderProps,
+  ScrollWrapperRenderProps,
   BaseTableProps,
 } from './types';
 export type {
@@ -93,6 +95,7 @@ export type {
   UseTableColumnSettingsStateReturn,
 } from './plugins/columnSettings';
 export type {UseTableColumnResizeConfig} from './plugins/columnResize';
+export type {UseTableStickyColumnsConfig} from './plugins/stickyColumns';
 export type {
   UseTableFilteringConfig,
   TableFilterState,

package/src/Table/plugins/stickyColumns/index.ts

@@ -0,0 +1,4 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+export {useTableStickyColumns} from './useTableStickyColumns';
+export type {UseTableStickyColumnsConfig} from './useTableStickyColumns';