@astryxdesign/core 0.1.0 → 0.1.1-canary.080d887

package/src/Pagination/Pagination.test.tsx

@@ -10,7 +10,7 @@
  */
 
 import {describe, it, expect, vi} from 'vitest';
-import {render, screen, within} from '@testing-library/react';
+import {render, screen, within, fireEvent, act} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Pagination, generatePageRange} from './Pagination';
 
@@ -346,6 +346,140 @@ describe('Pagination', () => {
     });
   });
 
+  // ---------------------------------------------------------------------------
+  // changeAction (interruptible, optimistic)
+  // ---------------------------------------------------------------------------
+
+  describe('changeAction', () => {
+    it('fires onChange then changeAction with the new page', async () => {
+      const user = userEvent.setup();
+      const order: string[] = [];
+      const onChange = vi.fn(() => order.push('onChange'));
+      const changeAction = vi.fn(() => {
+        order.push('changeAction');
+      });
+      render(
+        <Pagination
+          page={1}
+          onChange={onChange}
+          changeAction={changeAction}
+          totalPages={5}
+        />,
+      );
+      await user.click(screen.getByRole('button', {name: 'Go to next page'}));
+      expect(onChange).toHaveBeenCalledWith(2);
+      expect(changeAction).toHaveBeenCalledWith(2);
+      expect(order).toEqual(['onChange', 'changeAction']);
+    });
+
+    it('shows the optimistic page while changeAction is pending', async () => {
+      const user = userEvent.setup();
+      let resolveAction: (() => void) | undefined;
+      const changeAction = vi.fn(
+        async () =>
+          new Promise<void>(resolve => {
+            resolveAction = resolve;
+          }),
+      );
+      render(
+        <Pagination
+          page={1}
+          onChange={() => {}}
+          changeAction={changeAction}
+          totalPages={5}
+          variant="compact"
+        />,
+      );
+
+      // The committed `page` prop stays at 1, but the indicator optimistically
+      // reflects the page being navigated to.
+      await user.click(screen.getByRole('button', {name: 'Go to next page'}));
+      expect(changeAction).toHaveBeenCalledWith(2);
+      expect(screen.getByText('Page 2 of 5')).toBeInTheDocument();
+
+      await act(async () => {
+        resolveAction?.();
+        await Promise.resolve();
+      });
+    });
+
+    it('interrupts an in-flight action on rapid next clicks', async () => {
+      // Each click derives its target from the optimistic page, so clicking
+      // next twice before the action settles advances 1 -> 2 -> 3 instead of
+      // being dropped by a re-entry guard.
+      const resolvers: (() => void)[] = [];
+      const changeAction = vi.fn(
+        async () =>
+          new Promise<void>(resolve => {
+            resolvers.push(resolve);
+          }),
+      );
+      render(
+        <Pagination
+          page={1}
+          onChange={() => {}}
+          changeAction={changeAction}
+          totalPages={5}
+          variant="compact"
+        />,
+      );
+
+      const next = screen.getByRole('button', {name: 'Go to next page'});
+      await act(async () => {
+        fireEvent.click(next);
+      });
+      expect(screen.getByText('Page 2 of 5')).toBeInTheDocument();
+      await act(async () => {
+        fireEvent.click(next);
+      });
+      expect(screen.getByText('Page 3 of 5')).toBeInTheDocument();
+
+      expect(changeAction).toHaveBeenCalledTimes(2);
+      expect(changeAction).toHaveBeenNthCalledWith(1, 2);
+      expect(changeAction).toHaveBeenNthCalledWith(2, 3);
+
+      await act(async () => {
+        resolvers.forEach(resolve => resolve());
+        await Promise.resolve();
+      });
+    });
+
+    it('supports a synchronous changeAction', async () => {
+      const user = userEvent.setup();
+      const changeAction = vi.fn((_page: number) => {});
+      const onChange = vi.fn();
+      render(
+        <Pagination
+          page={2}
+          onChange={onChange}
+          changeAction={changeAction}
+          totalPages={5}
+        />,
+      );
+      await user.click(
+        screen.getByRole('button', {name: 'Go to previous page'}),
+      );
+      expect(onChange).toHaveBeenCalledWith(1);
+      expect(changeAction).toHaveBeenCalledWith(1);
+    });
+
+    it('does not fire changeAction when disabled', async () => {
+      const user = userEvent.setup();
+      const changeAction = vi.fn();
+      render(
+        <Pagination
+          page={1}
+          onChange={() => {}}
+          changeAction={changeAction}
+          totalPages={5}
+          isDisabled
+        />,
+      );
+      await user.click(screen.getByRole('button', {name: 'Go to next page'}));
+      expect(changeAction).not.toHaveBeenCalled();
+    });
+  });
+
   // ---------------------------------------------------------------------------
   // Boundary states
   // ---------------------------------------------------------------------------
@@ -459,12 +593,7 @@ describe('Pagination', () => {
   describe('disabled state', () => {
     it('disables all page buttons when isDisabled', () => {
       render(
-        <Pagination
-          page={3}
-          onChange={() => {}}
-          totalPages={5}
-          isDisabled
-        />,
+        <Pagination page={3} onChange={() => {}} totalPages={5} isDisabled />,
       );
       expect(
         screen.getByRole('button', {name: 'Go to previous page'}),
@@ -480,12 +609,7 @@ describe('Pagination', () => {
       const user = userEvent.setup();
       const onChange = vi.fn();
       render(
-        <Pagination
-          page={3}
-          onChange={onChange}
-          totalPages={5}
-          isDisabled
-        />,
+        <Pagination page={3} onChange={onChange} totalPages={5} isDisabled />,
       );
       // Disabled buttons can't be clicked
       await user.click(screen.getByRole('button', {name: 'Go to page 1'}));

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/Slider/Slider.doc.mjs

@@ -11,6 +11,10 @@ export const docs = {
     defaults: {
       label: 'Volume',
       value: 50,
+      // Give the properties-tab preview a defined width so the track has room
+      // to render and stays draggable/interactive (the slider track grows to
+      // fill its container, which can collapse without an explicit width).
+      width: 300,
     },
   },
   props: [

package/src/Slider/Slider.test.tsx

@@ -24,9 +24,7 @@ describe('Slider', () => {
   });
 
   it('range thumbs have correct aria-labels', () => {
-    render(
-      <Slider label="Price range" value={[20, 80] as [number, number]} />,
-    );
+    render(<Slider label="Price range" value={[20, 80] as [number, number]} />);
     const sliders = screen.getAllByRole('slider');
     expect(sliders[0]).toHaveAttribute(
       'aria-label',
@@ -172,12 +170,7 @@ describe('Slider', () => {
   it('does not fire onChange on keyboard when disabled', () => {
     const handleChange = vi.fn();
     render(
-      <Slider
-        label="Volume"
-        value={50}
-        onChange={handleChange}
-        isDisabled
-      />,
+      <Slider label="Volume" value={50} onChange={handleChange} isDisabled />,
     );
     const slider = screen.getByRole('slider');
     fireEvent.keyDown(slider, {key: 'ArrowRight'});
@@ -297,13 +290,7 @@ describe('Slider', () => {
 
   it('focuses closest thumb on track click', () => {
     render(
-      <Slider
-        label="Volume"
-        value={50}
-        min={0}
-        max={100}
-        onChange={vi.fn()}
-      />,
+      <Slider label="Volume" value={50} min={0} max={100} onChange={vi.fn()} />,
     );
     const slider = screen.getByRole('slider');
     const trackContainer = slider.parentElement!;

package/src/Slider/Slider.tsx

@@ -159,7 +159,7 @@ const styles = stylex.create({
   },
   track: {
     position: 'absolute',
-    backgroundColor: colorVars['--color-background-muted'],
+    backgroundColor: colorVars['--color-track'],
     borderRadius: radiusVars['--radius-full'],
   },
   trackHorizontal: {

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;