@astryxdesign/core 0.1.1 → 0.1.2-canary.3893cd5

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/ProgressBar/ProgressBar.test.tsx

@@ -79,9 +79,7 @@ describe('ProgressBar', () => {
   });
 
   it('passes data-testid', () => {
-    render(
-      <ProgressBar value={50} label="Test" data-testid="my-progress" />,
-    );
+    render(<ProgressBar value={50} label="Test" data-testid="my-progress" />);
     expect(screen.getByTestId('my-progress')).toBeInTheDocument();
   });
 
@@ -115,6 +113,18 @@ describe('ProgressBar', () => {
     expect(screen.getByText('Hidden')).toBeInTheDocument();
   });
 
+  it('renders no visible value label when isLabelHidden without hasValueLabel', () => {
+    // Mirrors the intended "accessible label only" composition: the text
+    // label is kept for assistive tech (visually hidden) while no extra
+    // visible value label is surfaced.
+    render(<ProgressBar value={42} label="Context usage" isLabelHidden />);
+    expect(screen.queryByText('42%')).not.toBeInTheDocument();
+    const label = screen.getByText('Context usage');
+    expect(label).toBeInTheDocument();
+    const meter = screen.getByRole('meter');
+    expect(meter).toHaveAttribute('aria-labelledby', label.id);
+  });
+
   it('handles zero max gracefully', () => {
     render(<ProgressBar value={0} max={0} label="Empty" />);
     const meter = screen.getByRole('meter');

package/src/Resizable/Resizable.doc.mjs

@@ -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',

package/src/Section/Section.doc.mjs

@@ -53,6 +53,11 @@ export const docs = {
       description: 'Internal padding using the spacing scale (0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10). Use padding={0} for edge-to-edge content.',
       default: '4',
     },
+    {
+      name: 'paddingBlock',
+      type: 'SpacingStep',
+      description: 'Block (vertical) padding override. Overrides only the block-axis padding while preserving inline padding from `padding` or the container theme default. Accepts the spacing scale (0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10).',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -130,6 +135,11 @@ export const docsZh = {
       description: '使用间距比例的内部内边距（0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10）。使用 padding={0} 实现全宽内容。',
       default: '4',
     },
+    {
+      name: 'paddingBlock',
+      type: 'SpacingStep',
+      description: '块（垂直）方向内边距覆盖。仅覆盖块轴内边距，同时保留来自 padding 或容器主题默认值的行内内边距。使用间距比例（0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10）。',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -182,6 +192,7 @@ export const docsDense = {
     children: 'Content rendered inside section.',
     dividers: 'Which sides of section have divider borders.',
     padding: 'Internal padding via spacing scale; 0 for edge-to-edge content.',
+    paddingBlock: 'Block-axis padding override; preserves inline padding from padding/theme.',
     xstyle: 'StyleX styles for layout customization; must be stylex.create() value.',
   },
 };

package/src/SelectableCard/SelectableCard.doc.mjs

@@ -36,6 +36,21 @@ export const docs = {
     container: true,
     targets: [{className: 'astryx-selectable-card', visualProps: ['selected']}],
   },
+  playground: {
+    defaults: {
+      label: 'Pro plan',
+      isSelected: true,
+      padding: 4,
+      children: {
+        __element: 'XDSVStack',
+        props: {gap: 1},
+        children: [
+          {__element: 'XDSHeading', props: {level: 3}, children: 'Pro plan'},
+          {__element: 'XDSText', props: {type: 'body'}, children: '$29/month — unlimited projects and priority support.'},
+        ],
+      },
+    },
+  },
 };
 
 /** @type {import('../docs-types').TranslationDoc} */

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

@@ -43,6 +43,12 @@ export const docs = {
       description: 'Size variant applied to all child tabs.',
       default: "'md'",
     },
+    {
+      name: 'layout',
+      type: "'hug' | 'fill'",
+      description: "Layout mode for tab sizing. 'hug': each tab hugs its content width. 'fill': tabs stretch equally to fill the container width.",
+      default: "'hug'",
+    },
     {
       name: 'hasDivider',
       type: 'boolean',