@astryxdesign/core 0.7.1 → 0.7.2-canary.c68f5e8

package/src/Pagination/Pagination.test.tsx

@@ -20,6 +20,7 @@ import {
 } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Pagination, generatePageRange} from './Pagination';
+import {InternationalizationProvider} from '../i18n';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 
 afterEach(() => {
@@ -119,6 +120,28 @@ describe('Pagination', () => {
       ).toBeInTheDocument();
     });
 
+    it('does not introduce Stack theme targets around navigation controls', () => {
+      const {rerender} = render(
+        <Pagination page={3} onChange={() => {}} totalPages={5} />,
+      );
+      expect(
+        screen.getByRole('navigation').querySelector('.astryx-stack'),
+      ).toBeNull();
+
+      rerender(
+        <Pagination
+          page={3}
+          onChange={() => {}}
+          totalPages={5}
+          variant="compact"
+          hasFirstLast
+        />,
+      );
+      expect(
+        screen.getByRole('navigation').querySelector('.astryx-stack'),
+      ).toBeNull();
+    });
+
     it('gives the prev/next carets a hover tooltip matching their accessible name', () => {
       // The carets are icon-only, so sighted users need a visible label on
       // hover, not just the accessible name. The tooltip reuses the same
@@ -291,6 +314,225 @@ describe('Pagination', () => {
       );
       expect(screen.getByText('Page 3 of 10')).toBeInTheDocument();
     });
+
+    describe('first/last buttons', () => {
+      function navButtonNames(): string[] {
+        return within(screen.getByRole('navigation'))
+          .getAllByRole('button')
+          .map(button => button.getAttribute('aria-label') ?? '');
+      }
+
+      it('omits first/last when hasFirstLast is unset', () => {
+        render(
+          <Pagination
+            page={5}
+            onChange={() => {}}
+            totalPages={10}
+            variant="compact"
+          />,
+        );
+        expect(navButtonNames()).toEqual([
+          'Go to previous page',
+          'Go to next page',
+        ]);
+      });
+
+      it('omits first/last when hasFirstLast is false', () => {
+        render(
+          <Pagination
+            page={5}
+            onChange={() => {}}
+            totalPages={10}
+            variant="compact"
+            hasFirstLast={false}
+          />,
+        );
+        expect(navButtonNames()).toEqual([
+          'Go to previous page',
+          'Go to next page',
+        ]);
+      });
+
+      it('flanks prev/next with first/last when hasFirstLast is true', () => {
+        render(
+          <Pagination
+            page={5}
+            onChange={() => {}}
+            totalPages={10}
+            variant="compact"
+            hasFirstLast
+          />,
+        );
+        expect(navButtonNames()).toEqual([
+          'Go to first page',
+          'Go to previous page',
+          'Go to next page',
+          'Go to last page',
+        ]);
+        // The readout stays between prev and next.
+        const readout = within(screen.getByRole('navigation')).getByText(
+          'Page 5 of 10',
+        );
+        const prev = screen.getByRole('button', {name: 'Go to previous page'});
+        const next = screen.getByRole('button', {name: 'Go to next page'});
+        expect(
+          prev.compareDocumentPosition(readout) &
+            Node.DOCUMENT_POSITION_FOLLOWING,
+        ).toBeTruthy();
+        expect(
+          next.compareDocumentPosition(readout) &
+            Node.DOCUMENT_POSITION_PRECEDING,
+        ).toBeTruthy();
+        // Compact never gains an editable box.
+        expect(screen.queryByRole('spinbutton')).not.toBeInTheDocument();
+      });
+
+      it('jumps to the first and last page through onChange and changeAction', async () => {
+        const user = userEvent.setup();
+        const onChange = vi.fn();
+        const changeAction = vi.fn();
+        render(
+          <Pagination
+            page={5}
+            onChange={onChange}
+            changeAction={changeAction}
+            totalItems={95}
+            pageSize={10}
+            variant="compact"
+            hasFirstLast
+          />,
+        );
+        await user.click(
+          screen.getByRole('button', {name: 'Go to first page'}),
+        );
+        expect(onChange).toHaveBeenLastCalledWith(1);
+        expect(changeAction).toHaveBeenLastCalledWith(1);
+        await waitFor(() => {
+          expect(politeRegion()).toHaveTextContent('Page 1 of 10');
+        });
+
+        await user.click(screen.getByRole('button', {name: 'Go to last page'}));
+        // 95 items at 10 per page is 10 pages.
+        expect(onChange).toHaveBeenLastCalledWith(10);
+        expect(changeAction).toHaveBeenLastCalledWith(10);
+        await waitFor(() => {
+          expect(politeRegion()).toHaveTextContent('Page 10 of 10');
+        });
+      });
+
+      it('disables first on the first page and last on the last page', () => {
+        const {rerender} = render(
+          <Pagination
+            page={1}
+            onChange={() => {}}
+            totalPages={10}
+            variant="compact"
+            hasFirstLast
+          />,
+        );
+        expect(
+          screen.getByRole('button', {name: 'Go to first page'}),
+        ).toBeDisabled();
+        expect(
+          screen.getByRole('button', {name: 'Go to last page'}),
+        ).not.toBeDisabled();
+
+        rerender(
+          <Pagination
+            page={10}
+            onChange={() => {}}
+            totalPages={10}
+            variant="compact"
+            hasFirstLast
+          />,
+        );
+        expect(
+          screen.getByRole('button', {name: 'Go to first page'}),
+        ).not.toBeDisabled();
+        expect(
+          screen.getByRole('button', {name: 'Go to last page'}),
+        ).toBeDisabled();
+      });
+
+      it('omits first/last when the total page count is unknown', async () => {
+        const user = userEvent.setup();
+        const onChange = vi.fn();
+        render(
+          <Pagination
+            page={2}
+            onChange={onChange}
+            hasMore
+            variant="compact"
+            hasFirstLast
+          />,
+        );
+        expect(navButtonNames()).toEqual([
+          'Go to previous page',
+          'Go to next page',
+        ]);
+        await user.click(screen.getByRole('button', {name: 'Go to next page'}));
+        expect(onChange).toHaveBeenLastCalledWith(3);
+      });
+
+      it('mirrors the first/last chevrons under RTL like prev/next', () => {
+        render(
+          <InternationalizationProvider locale="en" dir="rtl">
+            <div dir="rtl">
+              <Pagination
+                page={5}
+                onChange={() => {}}
+                totalPages={10}
+                variant="compact"
+                hasFirstLast
+              />
+            </div>
+          </InternationalizationProvider>,
+        );
+        // jsdom applies no CSS transforms, so assert the first/last icons carry
+        // every class the mirrored prev/next icons share (the mirror included).
+        const iconClasses = (name: string) =>
+          new Set(
+            screen
+              .getByRole('button', {name})
+              .querySelector('.astryx-icon')
+              ?.getAttribute('class')
+              ?.split(/\s+/) ?? [],
+          );
+        const prev = iconClasses('Go to previous page');
+        const shared = [...iconClasses('Go to next page')].filter(name =>
+          prev.has(name),
+        );
+        expect(shared.length).toBeGreaterThan(0);
+        for (const name of ['Go to first page', 'Go to last page']) {
+          const classes = iconClasses(name);
+          expect(shared.filter(c => !classes.has(c))).toEqual([]);
+        }
+      });
+    });
+  });
+
+  describe('hasFirstLast on other variants', () => {
+    it.each(['pages', 'count', 'dots', 'none'] as const)(
+      'does not add first/last to the %s variant',
+      variant => {
+        render(
+          <Pagination
+            page={3}
+            onChange={() => {}}
+            totalItems={50}
+            pageSize={10}
+            variant={variant}
+            hasFirstLast
+          />,
+        );
+        expect(
+          screen.queryByRole('button', {name: 'Go to first page'}),
+        ).not.toBeInTheDocument();
+        expect(
+          screen.queryByRole('button', {name: 'Go to last page'}),
+        ).not.toBeInTheDocument();
+      },
+    );
   });
 
   // ---------------------------------------------------------------------------

package/src/Pagination/Pagination.tsx

@@ -5,9 +5,10 @@
 /**
  * @file Pagination.tsx
  * @input Uses React, StyleX, Button, Icon, Selector, Text; page number buttons delegate to Button.
+ *   Compact first/last buttons cancel the inside control gap with logical token margins.
  *   Prev/next and first/last chevrons mirror under RTL via the shared rtlStyles.mirror
- *   (CSS scaleX), not a JS direction read. The input variant uses the chevronsLeft/chevronsRight
- *   (first/last) icons.
+ *   (CSS scaleX), not a JS direction read. The input and compact variants use the
+ *   chevronsLeft/chevronsRight (first/last) icons.
  * @output Exports Pagination component, PaginationProps, PaginationVariant, PaginationSize types
  * @position Core implementation; consumed by index.ts, tested by Pagination.test.tsx
  *
@@ -105,7 +106,8 @@ export interface PaginationProps extends Omit<
    * Visual variant controlling what appears between prev/next buttons.
    * - pages: Page number buttons with ellipsis (default)
    * - count: "X–Y of Z" text
-   * - compact: "Page X of Y" text
+   * - compact: "Page X of Y" text. First/last buttons are opt-in (see
+   *   hasFirstLast).
    * - dots: Dot indicators
    * - input: An editable number box rendering "Page [ n ] / N". The leading
    *   noun is controlled by `pageLabel`. First/last double-chevron buttons
@@ -122,9 +124,11 @@ export interface PaginationProps extends Omit<
   pageLabel?: string;
   /**
    * Whether to show first/last («/») double-chevron buttons flanking
-   * prev/next. Only applies to the `input` variant; other variants ignore it.
-   * The last button needs a known total — it is omitted when the page count is
-   * unknown (cursor/hasMore pagination). @default true
+   * prev/next. Applies to the `input` variant (shown unless false) and the
+   * `compact` variant (shown only when true); other variants ignore it.
+   * The last button needs a known total — both are omitted when the page count
+   * is unknown (cursor/hasMore pagination).
+   * @default true for `input`, false for `compact`
    */
   hasFirstLast?: boolean;
   /**
@@ -181,6 +185,12 @@ const styles = stylex.create({
     alignItems: 'center',
     gap: spacingVars['--spacing-1'],
   },
+  compactFirst: {
+    marginInlineEnd: `calc(-1 * ${spacingVars['--spacing-1']})`,
+  },
+  compactLast: {
+    marginInlineStart: `calc(-1 * ${spacingVars['--spacing-1']})`,
+  },
   ellipsis: {
     display: 'inline-flex',
     alignItems: 'center',
@@ -369,7 +379,7 @@ export function Pagination({
   onPageSizeChange,
   variant = 'pages',
   pageLabel,
-  hasFirstLast = true,
+  hasFirstLast: hasFirstLastProp,
   step: stepProp = 1,
   siblingCount = 1,
   size = 'md',
@@ -572,10 +582,14 @@ export function Pagination({
   const buttonSize = size === 'sm' ? 'sm' : 'md';
   const isSm = size === 'sm';
 
-  // First/last buttons only exist in the input variant, and only when the page
-  // count is known (they'd have no target otherwise).
-  const showFirstLast =
-    hasFirstLast && variant === 'input' && computedTotalPages != null;
+  // First/last buttons are on by default in the input variant and opt-in for
+  // compact; other variants never render them. They also need a known page
+  // count (the last button would have no target otherwise).
+  const hasFirstLast =
+    variant === 'input'
+      ? (hasFirstLastProp ?? true)
+      : variant === 'compact' && hasFirstLastProp === true;
+  const showFirstLast = hasFirstLast && computedTotalPages != null;
 
   const renderIndicator = () => {
     switch (variant) {
@@ -819,6 +833,7 @@ export function Pagination({
             onClick={handleFirst}
             isDisabled={isDisabled || !hasPrevious}
             isIconOnly
+            xstyle={variant === 'compact' && styles.compactFirst}
           />
         )}
 
@@ -874,6 +889,7 @@ export function Pagination({
             onClick={handleLast}
             isDisabled={isDisabled || !hasNext}
             isIconOnly
+            xstyle={variant === 'compact' && styles.compactLast}
           />
         )}
       </div>

package/src/Switch/Switch.test.tsx

@@ -834,6 +834,34 @@ describe('Switch', () => {
       expect(root).toHaveAttribute('id', 'switch-1');
       expect(root).toHaveAttribute('aria-label', 'Toggle notifications');
     });
+
+    it('composes a caller aria-describedby onto the switch control', () => {
+      const {container} = render(
+        <>
+          <p id="external-hint">Applies to every repository</p>
+          <Switch
+            label="Notifications"
+            description="Sends a daily digest"
+            value={false}
+            onChange={() => {}}
+            data-testid="my-switch"
+            aria-describedby="external-hint"
+          />
+        </>,
+      );
+      const control = screen.getByRole('switch');
+      const description = screen.getByText('Sends a daily digest');
+      expect(control.getAttribute('aria-describedby')?.split(' ')).toEqual([
+        'external-hint',
+        description.id,
+      ]);
+      expect(control).toHaveAccessibleDescription(
+        'Applies to every repository Sends a daily digest',
+      );
+      // The id reference lives on the control only, not on the field wrapper.
+      const root = container.querySelector('[data-testid="my-switch"]');
+      expect(root).not.toHaveAttribute('aria-describedby');
+    });
   });
 
   describe('pressed state', () => {

package/src/Switch/Switch.tsx

@@ -566,6 +566,7 @@ export function Switch({
   className,
   style,
   ref,
+  'aria-describedby': ariaDescribedByProp,
   ...rest
 }: SwitchProps) {
   const t = useTranslator();
@@ -610,7 +611,12 @@ export function Switch({
   // Only include descriptionID when the element actually renders.
   // FieldLabel renders the description (with descriptionID) even when the
   // label is visually hidden — it's sr-only, so keep it linked.
+  // A consumer's own `aria-describedby` describes the control, so it comes
+  // first here rather than landing on the field wrapper via `...rest`.
   const describedByParts: string[] = [];
+  if (ariaDescribedByProp) {
+    describedByParts.push(ariaDescribedByProp);
+  }
   if (description) {
     describedByParts.push(descriptionID);
   }

package/src/i18n/InternationalizationProvider.doc.mjs

@@ -21,6 +21,14 @@ export const docs = {
   usage: {
     description:
       'Wraps your app to set the active locale and (optionally) merge additional translation catalogs + per-locale overrides. Astryx components inside the subtree resolve their strings against this context. If no provider is present, components fall back to the shipped English defaults.',
+    anatomy: [
+      {
+        name: 'Provider boundary',
+        required: true,
+        description:
+          'A nonvisual context boundary that supplies locale, message catalogs, overrides, and direction to descendant Astryx components. It renders no DOM element.',
+      },
+    ],
     bestPractices: [
       {
         guidance: true,