@astryxdesign/core 0.2.0 → 0.3.0-canary.041a0ef

package/src/NumberInput/NumberInput.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: 'NumberInput',
@@ -174,7 +174,7 @@ export const docs = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-number-input', visualProps: ['size', 'status']},
+      {className: 'astryx-number-input', visualProps: ['size', 'status'], states: ['disabled']},
     ],
   },
   usage: {
@@ -192,12 +192,11 @@ export const docs = {
       {name: 'Description', required: false, description: 'Additional description text below the label.'},
       {name: 'Icon', required: false, description: 'An optional icon within the input.'},
       {name: 'Placeholder', required: false, description: 'Placeholder text shown when the input is empty.'},
-      {name: 'Spinner', required: false, description: 'Increment and decrement controls for the value.'},
     ],
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'NumberInput',
   displayName: 'Number Input',
@@ -361,7 +360,7 @@ export const docsZh = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-number-input', visualProps: ['size', 'status']},
+      {className: 'astryx-number-input', visualProps: ['size', 'status'], states: ['disabled']},
     ],
   },
   usage: {
@@ -379,12 +378,11 @@ export const docsZh = {
       {name: 'Description', required: false, description: 'Additional description text below the label.'},
       {name: 'Icon', required: false, description: 'An optional icon within the input.'},
       {name: 'Placeholder', required: false, description: 'Placeholder text shown when the input is empty.'},
-      {name: 'Spinner', required: false, description: 'Increment and decrement controls for the value.'},
     ],
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'Number input component for collecting numeric user input w/ validation.',
   usage: {
@@ -402,7 +400,6 @@ export const docsDense = {
       {name: 'Description', required: false, description: 'Additional description text below the label.'},
       {name: 'Icon', required: false, description: 'An optional icon within the input.'},
       {name: 'Placeholder', required: false, description: 'Placeholder text shown when the input is empty.'},
-      {name: 'Spinner', required: false, description: 'Increment and decrement controls for the value.'},
     ],
   },
   propDescriptions: {

package/src/NumberInput/NumberInput.test.tsx

@@ -687,6 +687,61 @@ describe('NumberInput', () => {
     });
   });
 
+  describe('form participation', () => {
+    it('submits the value under htmlName', () => {
+      const {container} = render(
+        <form>
+          <NumberInput
+            label="Quantity"
+            htmlName="quantity"
+            value={42}
+            onChange={() => {}}
+          />
+        </form>,
+      );
+      const data = new FormData(container.querySelector('form')!);
+      expect(data.get('quantity')).toBe('42');
+    });
+
+    it('is excluded from form data when disabled', () => {
+      const {container} = render(
+        <form>
+          <NumberInput
+            label="Quantity"
+            htmlName="quantity"
+            value={42}
+            onChange={() => {}}
+            isDisabled
+          />
+        </form>,
+      );
+      expect([
+        ...new FormData(container.querySelector('form')!).keys(),
+      ]).toEqual([]);
+    });
+
+    // Regression: a disabledMessage swaps the native `disabled` attribute for
+    // aria-disabled + readOnly so the reason stays focus-discoverable, but
+    // read-only fields still submit — the name has to be withheld too.
+    it('is excluded from form data when disabled, even with a disabledMessage', () => {
+      const {container} = render(
+        <form>
+          <NumberInput
+            label="Quantity"
+            htmlName="quantity"
+            value={42}
+            onChange={() => {}}
+            isDisabled
+            disabledMessage="Quantity is fixed by the contract"
+          />
+        </form>,
+      );
+      expect([
+        ...new FormData(container.querySelector('form')!).keys(),
+      ]).toEqual([]);
+    });
+  });
+
   describe('autoComplete prop', () => {
     it('sets autocomplete attribute when autoComplete is provided', () => {
       render(
@@ -965,11 +1020,15 @@ describe('keyboard clearing with hasClear (#3599)', () => {
   });
 });
 
-
 describe('NumberInput statusVariant forwarding', () => {
   it('defaults to attached (status renders with data-variant="attached")', () => {
     const {container} = render(
-      <NumberInput label="Amount" value={null} onChange={() => {}} status={{type: 'error', message: 'Must be positive'}} />,
+      <NumberInput
+        label="Amount"
+        value={null}
+        onChange={() => {}}
+        status={{type: 'error', message: 'Must be positive'}}
+      />,
     );
     expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
       'data-variant',
@@ -979,11 +1038,66 @@ describe('NumberInput statusVariant forwarding', () => {
 
   it('forwards statusVariant="detached" to the underlying Field status', () => {
     const {container} = render(
-      <NumberInput label="Amount" value={null} onChange={() => {}} status={{type: 'error', message: 'Must be positive'}} statusVariant="detached" />,
+      <NumberInput
+        label="Amount"
+        value={null}
+        onChange={() => {}}
+        status={{type: 'error', message: 'Must be positive'}}
+        statusVariant="detached"
+      />,
     );
     expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
       'data-variant',
       'detached',
     );
   });
+
+  it('stops wheel propagation while focused so ancestor containers do not scroll', () => {
+    const onScrollableWheel = vi.fn();
+    render(
+      <div onWheel={onScrollableWheel}>
+        <NumberInput label="Amount" value={5} onChange={() => {}} />
+      </div>,
+    );
+    const input = screen.getByRole('spinbutton');
+    input.focus();
+    fireEvent.wheel(input, {deltaY: 100});
+    expect(onScrollableWheel).not.toHaveBeenCalled();
+  });
+
+  it('does not stop wheel propagation when the input is not focused', () => {
+    const onScrollableWheel = vi.fn();
+    render(
+      <div onWheel={onScrollableWheel}>
+        <NumberInput label="Amount" value={5} onChange={() => {}} />
+      </div>,
+    );
+    const input = screen.getByRole('spinbutton');
+    fireEvent.wheel(input, {deltaY: 100});
+    expect(onScrollableWheel).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('NumberInput disabled theme state', () => {
+  it('reflects disabled on the root target so themes can gate paint on it', () => {
+    const {container} = render(
+      <NumberInput
+        label="Quantity"
+        value={null}
+        onChange={() => {}}
+        isDisabled
+      />,
+    );
+    const root = container.querySelector('.astryx-number-input');
+    expect(root).toHaveAttribute('data-disabled', 'disabled');
+    expect(root).toHaveClass('disabled');
+  });
+
+  it('omits data-disabled when enabled, like status does', () => {
+    const {container} = render(
+      <NumberInput label="Quantity" value={null} onChange={() => {}} />,
+    );
+    const root = container.querySelector('.astryx-number-input');
+    expect(root).not.toHaveAttribute('data-disabled');
+  });
 });

package/src/NumberInput/NumberInput.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/NumberInput/NumberInput.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/NumberInput/index.ts (exports if types change)
  * - /apps/storybook/stories/NumberInput.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/NumberInput/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/NumberInput/ (showcase blocks)
  */
 
 import {
@@ -81,6 +81,18 @@ const styles = stylex.create({
     borderWidth: 0,
     borderStyle: 'none',
     padding: 0,
+    // Hide the browser's native number spinners; the component provides its own
+    // affordances (keyboard entry, optional clear button) and the spinners
+    // clash with the input's visual treatment and sizing.
+    MozAppearance: 'textfield',
+    '::-webkit-inner-spin-button': {
+      WebkitAppearance: 'none',
+      margin: 0,
+    },
+    '::-webkit-outer-spin-button': {
+      WebkitAppearance: 'none',
+      margin: 0,
+    },
     fontFamily: typographyVars['--font-family-body'],
     fontSize: {
       default: typeScaleVars['--text-body-size'],
@@ -579,6 +591,16 @@ export function NumberInput({
     ],
   );
 
+  // While focused, a wheel gesture steps the value — keep that gesture from
+  // also bubbling up and scrolling an ancestor container (page, Dialog,
+  // ScrollArea). When the input isn't focused the wheel isn't stepping the
+  // value, so normal scrolling is left alone.
+  const handleWheel = useCallback((e: React.WheelEvent<HTMLInputElement>) => {
+    if (document.activeElement === e.currentTarget) {
+      e.stopPropagation();
+    }
+  }, []);
+
   // Handle clear button click
   const handleClear = useCallback(() => {
     if (hasClear) {
@@ -608,7 +630,11 @@ export function NumberInput({
       onClick={handleWrapperClick}
       onMouseUp={handleWrapperMouseUp}
       {...mergeProps(
-        themeProps('number-input', {size, status: status?.type ?? null}),
+        themeProps('number-input', {
+          size,
+          status: status?.type ?? null,
+          disabled: isDisabled ? 'disabled' : null,
+        }),
         stylex.props(
           inputWrapperStyles.base,
           styles.wrapper,
@@ -629,7 +655,7 @@ export function NumberInput({
         {...rest}
         ref={mergeRefs(ref, inputRef)}
         id={id}
-        name={htmlName}
+        name={isDisabled ? undefined : htmlName}
         type="number"
         autoComplete={autoComplete}
         value={displayValue}
@@ -637,6 +663,7 @@ export function NumberInput({
         onFocus={handleFocus}
         onBlur={handleBlur}
         onKeyDown={handleKeyDown}
+        onWheel={handleWheel}
         placeholder={placeholder}
         // With a disabledMessage the input keeps focusability via aria-disabled
         // so the reason is focus-discoverable; readOnly + the handler guards

package/src/Outline/Outline.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: 'Outline',
@@ -236,7 +236,7 @@ function FlashOnArrival() {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'Outline',
   displayName: 'Outline',
@@ -334,7 +334,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Document outline/table-of-contents nav with sliding indicator track. Flat items array {id,label,level}; anchor links; density variant (default/compact); uncontrolled scroll-spy by scroll position (last heading past its resting line = offset + its own scroll-margin-top; first item at top, last at bottom); controlled with activeId; smooth-scroll on click that pins the active item until the next manual scroll. Single tab stop (roving tabindex): Arrow keys move, Home/End jump, Enter/Space activate. onNavigateStart/onNavigateEnd fire around the scroll. Scroll scoping via offset / scrollContainerRef / hasScrollOnClick.',

package/src/Outline/Outline.tsx

@@ -20,7 +20,7 @@
  * - /packages/core/src/Outline/Outline.doc.mjs
  * - /packages/core/src/Outline/index.ts
  * - /apps/storybook/stories/Outline.stories.tsx
- * - /packages/cli/templates/blocks/components/Outline/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Outline/ (showcase blocks)
  */
 
 import {useRef} from 'react';
@@ -42,6 +42,7 @@ import type {BaseProps} from '../BaseProps';
 import {useScrollSpy} from './useScrollSpy';
 import type {OutlineItem} from './types';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useTranslator} from '../i18n';
 
 export type {OutlineItem} from './types';
@@ -211,10 +212,6 @@ const styles = stylex.create({
     ':active': {
       backgroundColor: colorVars['--color-overlay-pressed'],
     },
-    ':focus-visible': {
-      outline: `2px solid ${colorVars['--color-accent']}`,
-      outlineOffset: 2,
-    },
   },
   activeLink: {
     color: colorVars['--color-text-primary'],
@@ -473,7 +470,7 @@ export function Outline({
                     active: isActive ? 'active' : null,
                     level: item.level,
                   }),
-                  stylex.props(
+                  focusOutlineProps.focusVisible(
                     styles.link,
                     densityStyles[density],
                     getIndentStyle(item.level),

package/src/OverflowList/OverflowList.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: 'OverflowList',
@@ -112,7 +112,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'OverflowList',
   displayName: 'Overflow List',
@@ -188,7 +188,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'horizontal list w/ overflow indicator: hides items beyond container width',
   usage: {

package/src/OverflowList/OverflowList.tsx

@@ -15,7 +15,7 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/OverflowList/index.ts (exports if types change)
- * - /packages/cli/templates/blocks/components/OverflowList/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/OverflowList/ (showcase blocks)
  */
 
 import {type ReactNode, type ReactElement, Children} from 'react';

package/src/Overlay/Overlay.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: 'Overlay',
@@ -188,7 +188,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'layered content over media/card surfaces with scrim + hover/focus/controlled reveal',
   usage: {

package/src/Pagination/Pagination.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: 'Pagination',
@@ -64,11 +64,31 @@ export const docs = {
     },
     {
       name: 'variant',
-      type: "'pages' | 'count' | 'compact' | 'dots' | 'none'",
+      type: "'pages' | 'count' | 'compact' | 'dots' | 'input' | 'none'",
       description:
-        "Visual variant controlling what appears between prev/next buttons. 'pages' shows page number buttons with ellipsis, 'count' shows 'X-Y of Z' text, 'compact' shows 'Page X of Y', 'dots' shows dot indicators, 'none' shows just prev/next buttons.",
+        "Visual variant controlling what appears between prev/next buttons. 'pages' shows page number buttons with ellipsis, 'count' shows 'X-Y of Z' text, 'compact' shows 'Page X of Y', 'dots' shows dot indicators, 'input' shows an editable page-number box with a leading label ('Page [ n ] / N') flanked by first/last buttons by default (the box needs a known total to clamp against, so it is disabled in cursor/hasMore mode), 'none' shows just prev/next buttons.",
       default: "'pages'",
     },
+    {
+      name: 'pageLabel',
+      type: 'string',
+      description:
+        "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. Defaults to the localized 'Page'.",
+    },
+    {
+      name: 'hasFirstLast',
+      type: 'boolean',
+      description:
+        "Whether to show first/last («/») double-chevron buttons flanking prev/next. Only applies to the 'input' variant; omitted when the page count is unknown (cursor/hasMore pagination).",
+      default: 'true',
+    },
+    {
+      name: 'step',
+      type: 'number',
+      description:
+        '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. Non-integer or values < 1 fall back to 1.',
+      default: '1',
+    },
     {
       name: 'siblingCount',
       type: 'number',
@@ -105,6 +125,8 @@ export const docs = {
     targets: [
       {className: 'astryx-pagination', visualProps: ['size', 'variant']},
       {className: 'astryx-pagination-dot', visualProps: ['size'], states: ['active']},
+      {className: 'astryx-pagination-input-label', visualProps: ['size']},
+      {className: 'astryx-pagination-input-total', visualProps: ['size']},
     ],
   },
   playground: {
@@ -131,7 +153,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'Pagination',
   displayName: 'Pagination',
@@ -192,11 +214,31 @@ export const docsZh = {
     },
     {
       name: 'variant',
-      type: "'pages' | 'count' | 'compact' | 'dots' | 'none'",
+      type: "'pages' | 'count' | 'compact' | 'dots' | 'input' | 'none'",
       description:
-        "控制上一页/下一页按钮之间显示内容的视觉变体。'pages' 显示带省略号的页码按钮，'count' 显示 'X-Y of Z' 文本，'compact' 显示 'Page X of Y'，'dots' 显示点指示器，'none' 仅显示上一页/下一页按钮。",
+        "控制上一页/下一页按钮之间显示内容的视觉变体。'pages' 显示带省略号的页码按钮，'count' 显示 'X-Y of Z' 文本，'compact' 显示 'Page X of Y'，'dots' 显示点指示器，'input' 显示带前置标签的可编辑页码框——'Page [ n ] / N'——默认两侧带首页/末页按钮，'none' 仅显示上一页/下一页按钮。",
       default: "'pages'",
     },
+    {
+      name: 'pageLabel',
+      type: 'string',
+      description:
+        "'input' 变体中可编辑框前显示的名词，如 'Page' 或 'Row'。导航始终基于页码（通过 onChange）；此项仅用于重新标注。默认为本地化的 'Page'。",
+    },
+    {
+      name: 'hasFirstLast',
+      type: 'boolean',
+      description:
+        "是否显示首页/末页（«/»）双箭头按钮，位于上一页/下一页两侧。仅适用于 'input' 变体；当页数未知（游标/hasMore 分页）时省略。",
+      default: 'true',
+    },
+    {
+      name: 'step',
+      type: 'number',
+      description:
+        '上一页/下一页按钮每次点击前进的页数。会被限制在有效页码范围内，因此超出范围的步进会落在首页/末页。大于 1 时，按钮的无障碍名称会反映跨步页数。非整数或小于 1 的值回退为 1。',
+      default: '1',
+    },
     {
       name: 'siblingCount',
       type: 'number',
@@ -233,6 +275,8 @@ export const docsZh = {
     targets: [
       {className: 'astryx-pagination', visualProps: ['size', 'variant']},
       {className: 'astryx-pagination-dot', visualProps: ['size'], states: ['active']},
+      {className: 'astryx-pagination-input-label', visualProps: ['size']},
+      {className: 'astryx-pagination-input-total', visualProps: ['size']},
     ],
   },
   usage: {
@@ -251,7 +295,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Standalone pagination controls for navigating content pages. Supports multiple display variants + works w/ known totals or cursor-based pagination.',
@@ -280,7 +324,10 @@ export const docsDense = {
     pageSize: 'Items per page; coerced to positive integer, non-finite falls back to default',
     pageSizeOptions: 'Page size options. Shows selector dropdown when provided.',
     onPageSizeChange: 'Called on page size change. Auto resets to page 1.',
-    variant: 'Display between prev/next buttons.',
+    variant: "Display between prev/next. 'input' = 'Page [n] / N' + first/last.",
+    pageLabel: "Noun before the 'input' box (e.g. 'Page' or 'Row'). Navigation stays page-based. Default localized 'Page'.",
+    hasFirstLast: "Show first/last («/») buttons in the 'input' variant. Omitted when total unknown.",
+    step: 'Pages the prev/next buttons advance per click. Clamped to range; < 1 or non-integer falls back to 1.',
     siblingCount: "Page buttons each side of current; only variant='pages'.",
     size: 'Control size.',
     isDisabled: 'Component disabled.',