@astryxdesign/core 0.2.0 → 0.3.0

package/src/Pagination/Pagination.tsx

@@ -5,7 +5,9 @@
 /**
  * @file Pagination.tsx
  * @input Uses React, StyleX, Button, Icon, Selector, Text; page number buttons delegate to Button.
- *   Reads i18n direction via useDirection() to flip the prev/next chevrons under RTL.
+ *   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.
  * @output Exports Pagination component, PaginationProps, PaginationVariant, PaginationSize types
  * @position Core implementation; consumed by index.ts, tested by Pagination.test.tsx
  *
@@ -13,11 +15,11 @@
  * - /packages/core/src/Pagination/Pagination.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/Pagination/index.ts (exports if types change)
  * - /apps/storybook/stories/Pagination.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/Pagination/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Pagination/ (showcase blocks)
  *
  * Last synced props: page, onChange, changeAction, totalItems, totalPages, hasMore,
- *   pageSize, pageSizeOptions, onPageSizeChange, variant, siblingCount, size, isDisabled,
- *   label, data-testid, xstyle
+ *   pageSize, pageSizeOptions, onPageSizeChange, variant, pageLabel,
+ *   hasFirstLast, step, siblingCount, size, isDisabled, label, data-testid, xstyle
  */
 
 import {useOptimistic, useTransition} from 'react';
@@ -33,41 +35,21 @@ import {
 } from '../theme/tokens.stylex';
 import {Button} from '../Button';
 import {Icon} from '../Icon';
+import {NumberInput} from '../NumberInput';
 import {Selector} from '../Selector';
 import {Text} from '../Text';
 import {useAnnounce} from '../hooks/useAnnounce';
 import {useListFocus} from '../hooks/useListFocus';
-import {mergeProps} from '../utils';
+import {mergeProps, rtlStyles} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n/useTranslator';
-import {useDirection} from '../i18n/useDirection';
+import type {PaginationVariantMap} from './index';
 
 // =============================================================================
 // Types
 // =============================================================================
 
-/**
- * Extensible variant map for Pagination.
- *
- * Theme packages can add custom variants via TypeScript module augmentation:
- * @example
- * ```
- * declare module '@astryxdesign/core/Pagination' {
- *   interface PaginationVariantMap {
- *     'progress': true;
- *   }
- * }
- * ```
- */
-export interface PaginationVariantMap {
-  pages: true;
-  count: true;
-  compact: true;
-  dots: true;
-  none: true;
-}
-
 /** Visual variant controlling what appears between prev/next buttons.
  * Extensible via module augmentation of PaginationVariantMap.
  */
@@ -124,10 +106,34 @@ export interface PaginationProps extends Omit<
    * - count: "X–Y of Z" text
    * - compact: "Page X of Y" text
    * - dots: Dot indicators
+   * - input: An editable number box rendering "Page [ n ] / N". The leading
+   *   noun is controlled by `pageLabel`. First/last double-chevron buttons
+   *   flank prev/next by default (see hasFirstLast).
    * - none: Just prev/next buttons
    * @default 'pages'
    */
   variant?: PaginationVariant;
+  /**
+   * The noun rendered before the editable box in the `input` variant, e.g.
+   * "Page" or "Row". Navigation is always page-based (via `onChange`); this
+   * only relabels the box. @default the localized "Page"
+   */
+  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
+   */
+  hasFirstLast?: boolean;
+  /**
+   * Number of pages the previous/next («‹ ›») buttons advance per click.
+   * Clamped to the valid page range, so a step that would overshoot lands on
+   * the first/last page. When greater than 1, the buttons' accessible names
+   * reflect the stride (e.g. "Go forward 5 pages"). Non-integer or values < 1
+   * fall back to 1. @default 1
+   */
+  step?: number;
   /**
    * Number of page buttons to show on each side of the current page.
    * Only applies when variant='pages'. @default 1
@@ -232,6 +238,28 @@ const styles = stylex.create({
     backgroundColor: colorVars['--color-neutral'],
     fontWeight: fontWeightVars['--font-weight-medium'],
   },
+  inputGroup: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-1'],
+    whiteSpace: 'nowrap',
+  },
+  inputLabel: {
+    color: colorVars['--color-text-secondary'],
+    fontSize: typeScaleVars['--text-label-size'],
+    userSelect: 'none',
+  },
+  inputLabelSm: {
+    fontSize: typeScaleVars['--text-supporting-size'],
+  },
+  inputTotal: {
+    color: colorVars['--color-text-secondary'],
+    fontSize: typeScaleVars['--text-label-size'],
+    userSelect: 'none',
+  },
+  inputTotalSm: {
+    fontSize: typeScaleVars['--text-supporting-size'],
+  },
   pageSizeSelector: {
     display: 'flex',
     alignItems: 'center',
@@ -344,6 +372,9 @@ export function Pagination({
   pageSizeOptions,
   onPageSizeChange,
   variant = 'pages',
+  pageLabel,
+  hasFirstLast = true,
+  step: stepProp = 1,
   siblingCount = 1,
   size = 'md',
   isDisabled = false,
@@ -360,16 +391,13 @@ export function Pagination({
   // Resolve system strings once per render. Prop overrides win.
   const t = useTranslator();
   const label = labelFromProps ?? t('@astryx.pagination.label');
-  const previousLabel = t('@astryx.pagination.previous');
-  const nextLabel = t('@astryx.pagination.next');
-
-  // Directional icons: under RTL, the "previous" control points right and the
-  // "next" control points left. aria-labels stay semantic (unchanged).
-  const direction = useDirection();
-  const previousIcon = direction === 'rtl' ? 'chevronRight' : 'chevronLeft';
-  const nextIcon = direction === 'rtl' ? 'chevronLeft' : 'chevronRight';
+  const firstLabel = t('@astryx.pagination.first');
+  const lastLabel = t('@astryx.pagination.last');
+
   const pageIndicatorsLabel = t('@astryx.pagination.pageIndicators');
   const itemsPerPageLabel = t('@astryx.pagination.itemsPerPage');
+  const goToPageLabel = t('@astryx.pagination.goToPageInput');
+  const inputLabelText = pageLabel ?? t('@astryx.pagination.pageLabel');
 
   // pageSize is typed as number, so 0, NaN, and negatives are valid at the
   // type level but yield Infinity/NaN page counts, and
@@ -379,6 +407,23 @@ export function Pagination({
     ? Math.max(1, Math.floor(pageSizeProp))
     : 10;
 
+  // Prev/next stride. Same guard as pageSize: non-integer or < 1 falls back to
+  // a single-page step so a bad value never freezes or reverses navigation.
+  const step = Number.isInteger(stepProp) && stepProp >= 1 ? stepProp : 1;
+
+  // The prev/next buttons advance `step` pages, so their accessible names must
+  // reflect the stride: a plain "previous/next page" for the default single
+  // step, or an explicit "back/forward N pages" so a screen reader never
+  // announces a single-page move for a multi-page jump.
+  const previousLabel =
+    step > 1
+      ? t('@astryx.pagination.previousBy', {step})
+      : t('@astryx.pagination.previous');
+  const nextLabel =
+    step > 1
+      ? t('@astryx.pagination.nextBy', {step})
+      : t('@astryx.pagination.next');
+
   // Announce page changes politely (navigation-10). The controls carry no
   // live region, so page transitions were previously silent to screen readers.
   // Only user-driven changes go through handlePageChange, so initial mount is
@@ -404,7 +449,6 @@ export function Pagination({
     orientation: 'horizontal',
   });
 
-  // Compute pagination state
   const computedTotalPages =
     totalPagesProp ??
     (totalItems != null ? Math.ceil(totalItems / pageSize) : undefined);
@@ -415,7 +459,6 @@ export function Pagination({
       ? optimisticPage < computedTotalPages
       : (hasMore ?? false);
 
-  // Return null for empty state
   if (totalItems != null && totalItems <= 0) {
     return null;
   }
@@ -469,15 +512,37 @@ export function Pagination({
     }
   };
 
+  // Clamp a target page into the valid range. The lower bound is always 1; the
+  // upper bound only exists when the page count is known (cursor/hasMore mode
+  // leaves it open-ended).
+  const clampPage = (target: number): number => {
+    const lower = Math.max(target, 1);
+    return computedTotalPages != null
+      ? Math.min(lower, computedTotalPages)
+      : lower;
+  };
+
   const handlePrevious = () => {
     if (hasPrevious) {
-      handlePageChange(optimisticPage - 1);
+      handlePageChange(clampPage(optimisticPage - step));
     }
   };
 
   const handleNext = () => {
     if (hasNext) {
-      handlePageChange(optimisticPage + 1);
+      handlePageChange(clampPage(optimisticPage + step));
+    }
+  };
+
+  const handleFirst = () => {
+    if (hasPrevious) {
+      handlePageChange(1);
+    }
+  };
+
+  const handleLast = () => {
+    if (hasNext && computedTotalPages != null) {
+      handlePageChange(computedTotalPages);
     }
   };
 
@@ -488,6 +553,19 @@ export function Pagination({
     handlePageChange(1);
   };
 
+  // The value currently shown in the input box is the committed page number.
+  const inputCommittedValue = optimisticPage;
+
+  // NumberInput owns the typing/pending state and clamps to [min, max] with
+  // integer-only semantics, so it only ever hands back a valid page here.
+  // Navigation is page-based via onChange.
+  const handleInputCommit = (nextPage: number) => {
+    if (isDisabled || nextPage === optimisticPage) {
+      return;
+    }
+    handlePageChange(nextPage);
+  };
+
   // Item range for count display
   const rangeStart = (optimisticPage - 1) * pageSize + 1;
   const rangeEnd =
@@ -498,6 +576,11 @@ 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;
+
   const renderIndicator = () => {
     switch (variant) {
       case 'pages': {
@@ -633,6 +716,61 @@ export function Pagination({
         );
       }
 
+      case 'input': {
+        // The editable box needs a known page count to clamp against; in
+        // cursor/hasMore mode (no total) there is no valid range, so the box is
+        // disabled rather than accepting entries it can't resolve — matching the
+        // convention that a typeable page box requires a known total.
+        const isInputDisabled = isDisabled || computedTotalPages == null;
+
+        const inputNode = (
+          <NumberInput
+            label={goToPageLabel}
+            isLabelHidden
+            value={inputCommittedValue}
+            onChange={handleInputCommit}
+            min={1}
+            max={computedTotalPages ?? undefined}
+            isIntegerOnly
+            size={size}
+            width={
+              isSm
+                ? sizeVars['--size-element-sm']
+                : sizeVars['--size-element-md']
+            }
+            isDisabled={isInputDisabled}
+            data-testid={testId != null ? `${testId}-input` : undefined}
+          />
+        );
+
+        // Label wording: "Page [ n ] / N". The leading noun comes from
+        // `pageLabel`; the trailing "/ N" total is omitted when unknown.
+        return (
+          <span {...stylex.props(styles.inputGroup)}>
+            <span
+              aria-hidden="true"
+              {...mergeProps(
+                themeProps('pagination-input-label', {size}),
+                stylex.props(styles.inputLabel, isSm && styles.inputLabelSm),
+              )}>
+              {inputLabelText}
+            </span>
+            {inputNode}
+            {computedTotalPages != null && (
+              <span
+                {...mergeProps(
+                  themeProps('pagination-input-total', {size}),
+                  stylex.props(styles.inputTotal, isSm && styles.inputTotalSm),
+                )}>
+                {t('@astryx.pagination.ofTotalPages', {
+                  total: computedTotalPages,
+                })}
+              </span>
+            )}
+          </span>
+        );
+      }
+
       case 'none':
       default:
         return null;
@@ -667,11 +805,33 @@ export function Pagination({
         </div>
       )}
       <div {...stylex.props(styles.controls)}>
+        {showFirstLast && (
+          <Button
+            label={firstLabel}
+            tooltip={isDisabled || !hasPrevious ? undefined : firstLabel}
+            variant="ghost"
+            size={buttonSize}
+            icon={
+              <span {...stylex.props(rtlStyles.mirror)}>
+                <Icon icon="chevronsLeft" size={isSm ? 'sm' : 'md'} />
+              </span>
+            }
+            onClick={handleFirst}
+            isDisabled={isDisabled || !hasPrevious}
+            isIconOnly
+          />
+        )}
+
         <Button
           label={previousLabel}
+          tooltip={isDisabled || !hasPrevious ? undefined : previousLabel}
           variant="ghost"
           size={buttonSize}
-          icon={<Icon icon={previousIcon} size={isSm ? 'sm' : 'md'} />}
+          icon={
+            <span {...stylex.props(rtlStyles.mirror)}>
+              <Icon icon="chevronLeft" size={isSm ? 'sm' : 'md'} />
+            </span>
+          }
           onClick={handlePrevious}
           isDisabled={isDisabled || !hasPrevious}
           isIconOnly
@@ -681,13 +841,35 @@ export function Pagination({
 
         <Button
           label={nextLabel}
+          tooltip={isDisabled || !hasNext ? undefined : nextLabel}
           variant="ghost"
           size={buttonSize}
-          icon={<Icon icon={nextIcon} size={isSm ? 'sm' : 'md'} />}
+          icon={
+            <span {...stylex.props(rtlStyles.mirror)}>
+              <Icon icon="chevronRight" size={isSm ? 'sm' : 'md'} />
+            </span>
+          }
           onClick={handleNext}
           isDisabled={isDisabled || !hasNext}
           isIconOnly
         />
+
+        {showFirstLast && (
+          <Button
+            label={lastLabel}
+            tooltip={isDisabled || !hasNext ? undefined : lastLabel}
+            variant="ghost"
+            size={buttonSize}
+            icon={
+              <span {...stylex.props(rtlStyles.mirror)}>
+                <Icon icon="chevronsRight" size={isSm ? 'sm' : 'md'} />
+              </span>
+            }
+            onClick={handleLast}
+            isDisabled={isDisabled || !hasNext}
+            isIconOnly
+          />
+        )}
       </div>
     </nav>
   );

package/src/Pagination/index.ts

@@ -9,10 +9,31 @@
  * @position Barrel export; consumed by packages/core/src/index.ts
  */
 
+/**
+ * Extensible variant map for Pagination.
+ *
+ * Theme packages can add custom variants via TypeScript module augmentation:
+ * @example
+ * ```
+ * declare module '@astryxdesign/core/Pagination' {
+ *   interface PaginationVariantMap {
+ *     'progress': true;
+ *   }
+ * }
+ * ```
+ */
+export interface PaginationVariantMap {
+  pages: true;
+  count: true;
+  compact: true;
+  dots: true;
+  input: true;
+  none: true;
+}
+
 export {Pagination, generatePageRange} from './Pagination';
 export type {
   PaginationProps,
   PaginationVariant,
-  PaginationVariantMap,
   PaginationSize,
 } from './Pagination';

package/src/Popover/Popover.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Popover',
@@ -72,6 +72,20 @@ export const docs = {
           type: 'string',
           description: 'Accessible label for the popover dialog.',
         },
+        {
+          name: 'role',
+          type: "'dialog' | 'none'",
+          description:
+            'ARIA role for the popover wrapper. Use dialog for dialog-style popovers; use none when content provides its own role, like menu or listbox.',
+          default: "'dialog'",
+        },
+        {
+          name: 'isModal',
+          type: 'boolean',
+          description:
+            'Whether a dialog-style popover sets aria-modal. Only applies when role is dialog.',
+          default: 'true',
+        },
         {
           name: 'hasCloseButton',
           type: 'boolean',
@@ -145,7 +159,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'Popover',
   displayName: 'Popover',
@@ -213,6 +227,20 @@ export const docsZh = {
           type: 'string',
           description: '弹出框对话框的无障碍标签。',
         },
+        {
+          name: 'role',
+          type: "'dialog' | 'none'",
+          description:
+            '弹出框包装器的 ARIA 角色。对话框式弹出框使用 dialog；当内容提供自己的角色（如 menu 或 listbox）时使用 none。',
+          default: "'dialog'",
+        },
+        {
+          name: 'isModal',
+          type: 'boolean',
+          description:
+            '对话框式弹出框是否设置 aria-modal。仅在 role 为 dialog 时适用。',
+          default: 'true',
+        },
         {
           name: 'hasCloseButton',
           type: 'boolean',
@@ -275,7 +303,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Click-triggered popover displaying interactive content anchored to trigger element; implements button+dialog ARIA pattern.',

package/src/Popover/Popover.test.tsx

@@ -107,6 +107,47 @@ describe('Popover', () => {
     expect(dialog).toHaveAttribute('aria-label', 'Greeting');
   });
 
+  it('can render a neutral wrapper when content owns its role', () => {
+    render(
+      <Popover
+        role="none"
+        content={
+          <div role="menu" aria-label="Actions">
+            Menu content
+          </div>
+        }
+        label="Actions">
+        <button type="button">Open</button>
+      </Popover>,
+    );
+
+    const trigger = screen.getByRole('button', {name: 'Open'});
+    expect(trigger).toHaveAttribute('aria-haspopup', 'true');
+    expect(
+      screen.queryByRole('dialog', {hidden: true}),
+    ).not.toBeInTheDocument();
+    expect(screen.getByRole('menu', {hidden: true})).toHaveAttribute(
+      'aria-label',
+      'Actions',
+    );
+  });
+
+  it('can render a non-modal dialog wrapper', () => {
+    render(
+      <Popover
+        role="dialog"
+        isModal={false}
+        content={<span>Hello</span>}
+        label="Greeting">
+        <button type="button">Open</button>
+      </Popover>,
+    );
+
+    const dialog = screen.getByRole('dialog', {hidden: true});
+    expect(dialog).toBeInTheDocument();
+    expect(dialog).not.toHaveAttribute('aria-modal');
+  });
+
   it('calls onOpenChange when opened', () => {
     const onOpenChange = vi.fn();
     render(

package/src/Popover/Popover.tsx

@@ -14,7 +14,7 @@
  * - /packages/core/src/Popover/Popover.test.tsx
  * - /packages/core/src/Popover/index.ts
  * - /apps/storybook/stories/Popover.stories.tsx
- * - /packages/cli/templates/blocks/components/Popover/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Popover/ (showcase blocks)
  */
 
 import React, {
@@ -163,10 +163,29 @@ export interface PopoverProps extends Pick<
 
   /**
    * Accessible label for the popover dialog.
-   * Recommended for accessibility (used as aria-label on the dialog).
+   * Recommended for accessibility when `role` is `'dialog'`.
    */
   label?: string;
 
+  /**
+   * ARIA role stamped on the popover content wrapper.
+   *
+   * Use `'dialog'` for dialog-style popovers. Use `'none'` when the popup
+   * content owns its own role, such as a child `role="menu"` or
+   * `role="listbox"`.
+   *
+   * @default 'dialog'
+   */
+  role?: 'dialog' | 'none';
+
+  /**
+   * Whether a dialog-style popover is modal (`aria-modal`). Only applies when
+   * `role` is `'dialog'`.
+   *
+   * @default true
+   */
+  isModal?: boolean;
+
   /**
    * Whether to include a hidden close button for accessibility.
    * The button appears when keyboard users tab past the last element.
@@ -293,6 +312,8 @@ export function Popover({
   isEnabled = true,
   width,
   label,
+  role = 'dialog',
+  isModal,
   hasCloseButton,
   closeButtonLabel,
   hasAutoFocus,
@@ -320,6 +341,8 @@ export function Popover({
 
   const popover = usePopover({
     dialogLabel: label,
+    role,
+    isModal,
     hasLightDismiss,
     hasEscapeDismiss,
     hasCloseButton,

package/src/Popover/usePopover.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'usePopover',
   displayName: 'usePopover',
@@ -46,7 +46,7 @@ export const docs = {
   category: 'interaction',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description: 'Headless click-triggered popovers w/ focus trap, auto-focus, light dismiss, Escape, optional hidden close button. Use for custom interactive floating content needing keyboard nav.',
   paramDescriptions: {

package/src/Popover/usePopover.tsx

@@ -27,6 +27,7 @@ import {
   shadowVars,
 } from '../theme/tokens.stylex';
 import {Button} from '../Button';
+import {rtlStyles} from '../utils';
 import {useTranslator} from '../i18n';
 import {useDevWarning} from '../hooks/useDevWarning';
 
@@ -43,12 +44,13 @@ const styles = stylex.create({
   contentWrapper: {
     position: 'relative',
   },
-  // Hidden close button wrapper - sr-only until focused, then positioned below popover
+  // Hidden close button wrapper - sr-only until focused, then positioned below
+  // popover. Inline-axis centering (+ the translateY(100%) that drops it below
+  // the surface) comes from rtlStyles.centerInline('100%') at the call site —
+  // it centers correctly in both LTR and RTL.
   closeButtonWrapper: {
     position: 'absolute',
     bottom: 0,
-    left: '50%',
-    transform: 'translate(-50%, 100%)',
     zIndex: 1,
     // sr-only by default
     width: {
@@ -417,7 +419,11 @@ export function usePopover(options: UsePopoverOptions = {}): UsePopoverReturn {
           )}>
           {children}
           {hasCloseButton && (
-            <div {...stylex.props(styles.closeButtonWrapper)}>
+            <div
+              {...stylex.props(
+                styles.closeButtonWrapper,
+                rtlStyles.centerInline('100%'),
+              )}>
               <Button
                 variant="secondary"
                 label={closeButtonLabel}