@astryxdesign/core 0.3.0 → 0.4.0

package/src/NumberInput/NumberInput.doc.mjs

@@ -6,7 +6,17 @@ export const docs = {
   name: 'NumberInput',
   displayName: 'Number Input',
   category: 'Data Input',
-  keywords: ["numberinput","numberfield","stepper","spinner","counter","increment","decrement","quantity","numberpicker"],
+  keywords: [
+    'numberinput',
+    'numberfield',
+    'stepper',
+    'spinner',
+    'counter',
+    'increment',
+    'decrement',
+    'quantity',
+    'numberpicker',
+  ],
   props: [
     {
       name: 'label',
@@ -62,6 +72,13 @@ export const docs = {
       type: 'boolean',
       description: 'Whether the input is disabled.',
     },
+    {
+      name: 'isReadOnly',
+      type: 'boolean',
+      description:
+        'Makes the input read-only: the value is shown at full opacity and still submits with the form, but cannot be edited. Unlike isDisabled, a read-only input is not dimmed and stays in the tab order. Stepping is off in every form while read-only: arrow keys, the wheel, and the number steppers. isDisabled takes precedence when both are set.',
+      default: 'false',
+    },
     {
       name: 'disabledMessage',
       type: 'string',
@@ -82,12 +99,14 @@ export const docs = {
     {
       name: 'startIcon',
       type: 'IconType',
-      description: 'Icon to display at the start of the input. See `astryx docs icons` for valid semantic names.',
+      description:
+        'Icon to display at the start of the input. See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'labelIcon',
       type: 'IconType',
-      description: 'Icon to display before the label text. See `astryx docs icons` for valid semantic names.',
+      description:
+        'Icon to display before the label text. See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'status',
@@ -117,6 +136,26 @@ export const docs = {
       description: 'Step increment for the input.',
       default: '1',
     },
+    {
+      name: 'formatValue',
+      type: '(value: number) => string',
+      description:
+        'Formats the committed value while the input is not focused. The raw numeric value is shown on focus for editing and the formatted value is exposed through aria-valuetext.',
+    },
+    {
+      name: 'isWheelEnabled',
+      type: 'boolean',
+      description:
+        'Whether scrolling the wheel over the focused input steps the value. Disable this when page scrolling should always take priority.',
+      default: 'true',
+    },
+    {
+      name: 'hasNumberSteppers',
+      type: 'boolean',
+      description:
+        'Shows increment and decrement buttons at the end of the input.',
+      default: 'false',
+    },
     {
       name: 'units',
       type: 'string | null',
@@ -174,24 +213,74 @@ export const docs = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-number-input', visualProps: ['size', 'status']},
+      {
+        className: 'astryx-number-input',
+        visualProps: ['size', 'status'],
+        states: ['disabled', 'readonly'],
+      },
     ],
   },
   usage: {
     description:
       'A form input for numeric values with built-in validation, min/max constraints, and step controls. Use NumberInput for quantities, measurements, percentages, and similar inputs.',
     bestPractices: [
-      { guidance: true, description: 'Set min, max, and step to guide users toward valid values.' },
-      { guidance: true, description: 'Show units (e.g. "%" or "GB") so users know what the number represents.' },
-      { guidance: false, description: 'Use NumberInput for free-form text that happens to contain numbers; use TextInput instead.' },
-      { guidance: false, description: 'Set both isOptional and isRequired on the same field.' },
-      { guidance: false, description: "Wrap a disabled NumberInput in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead." },
+      {
+        guidance: true,
+        description:
+          'Set min, max, and step to guide users toward valid values.',
+      },
+      {
+        guidance: true,
+        description:
+          'Show units (e.g. "%" or "GB") so users know what the number represents.',
+      },
+      {
+        guidance: true,
+        description:
+          'Set isWheelEnabled={false} when the input appears in a scrolling surface where wheel gestures should always scroll the page.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use NumberInput for free-form text that happens to contain numbers; use TextInput instead.',
+      },
+      {
+        guidance: false,
+        description: 'Set both isOptional and isRequired on the same field.',
+      },
+      {
+        guidance: false,
+        description:
+          "Wrap a disabled NumberInput in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.",
+      },
     ],
     anatomy: [
-      {name: 'Label', required: true, description: 'The label for the number input.'},
-      {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: 'Label',
+        required: true,
+        description: 'The label for the number input.',
+      },
+      {
+        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: 'Number steppers',
+        required: false,
+        description:
+          'Optional buttons that increment or decrement by the configured step.',
+      },
     ],
   },
 };
@@ -204,8 +293,7 @@ export const docsZh = {
     {
       name: 'label',
       type: 'string',
-      description:
-        '输入框的标签文本（始终渲染以确保无障碍访问）。',
+      description: '输入框的标签文本（始终渲染以确保无障碍访问）。',
       required: true,
     },
     {
@@ -217,8 +305,7 @@ export const docsZh = {
     {
       name: 'onChange',
       type: '(value: number) => void',
-      description:
-        '输入值变化时触发的回调（仅在输入有效时触发）。',
+      description: '输入值变化时触发的回调（仅在输入有效时触发）。',
       required: true,
     },
     {
@@ -230,8 +317,7 @@ export const docsZh = {
     {
       name: 'isLabelHidden',
       type: 'boolean',
-      description:
-        '视觉隐藏标签（屏幕阅读器仍可访问）。',
+      description: '视觉隐藏标签（屏幕阅读器仍可访问）。',
     },
     {
       name: 'description',
@@ -241,20 +327,25 @@ export const docsZh = {
     {
       name: 'isOptional',
       type: 'boolean',
-      description:
-        '字段是否可选（与 isRequired 互斥）。',
+      description: '字段是否可选（与 isRequired 互斥）。',
     },
     {
       name: 'isRequired',
       type: 'boolean',
-      description:
-        '字段是否必填（与 isOptional 互斥）。',
+      description: '字段是否必填（与 isOptional 互斥）。',
     },
     {
       name: 'isDisabled',
       type: 'boolean',
       description: '输入框是否禁用。',
     },
+    {
+      name: 'isReadOnly',
+      type: 'boolean',
+      description:
+        '将输入框设为只读：值以完整不透明度显示并仍随表单提交，但无法编辑。与 isDisabled 不同，只读输入框不会变暗，并保留在 Tab 顺序中。只读时所有步进方式均被禁用：方向键、滚轮和步进按钮。同时设置时 isDisabled 优先。',
+      default: 'false',
+    },
     {
       name: 'disabledMessage',
       type: 'string',
@@ -269,8 +360,7 @@ export const docsZh = {
     {
       name: 'labelTooltip',
       type: 'string',
-      description:
-        '在标签末尾的信息图标中显示的工具提示文本。',
+      description: '在标签末尾的信息图标中显示的工具提示文本。',
     },
     {
       name: 'startIcon',
@@ -310,11 +400,29 @@ export const docsZh = {
       description: '输入框的步进增量。',
       default: '1',
     },
+    {
+      name: 'formatValue',
+      type: '(value: number) => string',
+      description:
+        '输入框未聚焦时格式化已提交的值。聚焦编辑时显示原始数值，并通过 aria-valuetext 提供格式化值。',
+    },
+    {
+      name: 'isWheelEnabled',
+      type: 'boolean',
+      description:
+        '是否允许在已聚焦的输入框上滚动滚轮来步进数值。当页面滚动应始终优先时请禁用。',
+      default: 'true',
+    },
+    {
+      name: 'hasNumberSteppers',
+      type: 'boolean',
+      description: '是否在输入框末尾显示递增和递减按钮。',
+      default: 'false',
+    },
     {
       name: 'units',
       type: 'string | null',
-      description:
-        '在输入框末尾显示的单位文本（例如"%"或"GB"）。',
+      description: '在输入框末尾显示的单位文本（例如"%"或"GB"）。',
     },
     {
       name: 'isIntegerOnly',
@@ -324,7 +432,8 @@ export const docsZh = {
     {
       name: 'hasClear',
       type: 'boolean',
-      description: '输入有值时显示清除 (×) 按鈕。启用后， onChange 回调还接受 null 表示用户已清空输入。',
+      description:
+        '输入有值时显示清除 (×) 按鈕。启用后， onChange 回调还接受 null 表示用户已清空输入。',
       default: 'false',
     },
     {
@@ -360,46 +469,143 @@ export const docsZh = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-number-input', visualProps: ['size', 'status']},
+      {
+        className: 'astryx-number-input',
+        visualProps: ['size', 'status'],
+        states: ['disabled', 'readonly'],
+      },
     ],
   },
   usage: {
     description:
       'A form input for numeric values with built-in validation, min/max constraints, and step controls. Use NumberInput for quantities, measurements, percentages, and similar inputs.',
     bestPractices: [
-      { guidance: true, description: 'Set min, max, and step to guide users toward valid values.' },
-      { guidance: true, description: 'Show units (e.g. "%" or "GB") so users know what the number represents.' },
-      { guidance: false, description: 'Use NumberInput for free-form text that happens to contain numbers; use TextInput instead.' },
-      { guidance: false, description: 'Set both isOptional and isRequired on the same field.' },
-      { guidance: false, description: "Wrap a disabled NumberInput in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead." },
+      {
+        guidance: true,
+        description:
+          'Set min, max, and step to guide users toward valid values.',
+      },
+      {
+        guidance: true,
+        description:
+          'Show units (e.g. "%" or "GB") so users know what the number represents.',
+      },
+      {
+        guidance: true,
+        description:
+          'Set isWheelEnabled={false} when the input appears in a scrolling surface where wheel gestures should always scroll the page.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use NumberInput for free-form text that happens to contain numbers; use TextInput instead.',
+      },
+      {
+        guidance: false,
+        description: 'Set both isOptional and isRequired on the same field.',
+      },
+      {
+        guidance: false,
+        description:
+          "Wrap a disabled NumberInput in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.",
+      },
     ],
     anatomy: [
-      {name: 'Label', required: true, description: 'The label for the number input.'},
-      {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: 'Label',
+        required: true,
+        description: 'The label for the number input.',
+      },
+      {
+        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: 'Number steppers',
+        required: false,
+        description:
+          'Optional buttons that increment or decrement by the configured step.',
+      },
     ],
   },
 };
 
 /** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
-  description: 'Number input component for collecting numeric user input w/ validation.',
+  description:
+    'Number input component for collecting numeric user input w/ validation.',
   usage: {
     description:
       'A form input for numeric values with built-in validation, min/max constraints, and step controls. Use NumberInput for quantities, measurements, percentages, and similar inputs.',
     bestPractices: [
-      { guidance: true, description: 'Set min, max, and step to guide users toward valid values.' },
-      { guidance: true, description: 'Show units (e.g. "%" or "GB") so users know what the number represents.' },
-      { guidance: false, description: 'Use NumberInput for free-form text that happens to contain numbers; use TextInput instead.' },
-      { guidance: false, description: 'Set both isOptional and isRequired on the same field.' },
-      { guidance: false, description: "Wrap a disabled NumberInput in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead." },
+      {
+        guidance: true,
+        description:
+          'Set min, max, and step to guide users toward valid values.',
+      },
+      {
+        guidance: true,
+        description:
+          'Show units (e.g. "%" or "GB") so users know what the number represents.',
+      },
+      {
+        guidance: true,
+        description:
+          'Set isWheelEnabled={false} when the input appears in a scrolling surface where wheel gestures should always scroll the page.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use NumberInput for free-form text that happens to contain numbers; use TextInput instead.',
+      },
+      {
+        guidance: false,
+        description: 'Set both isOptional and isRequired on the same field.',
+      },
+      {
+        guidance: false,
+        description:
+          "Wrap a disabled NumberInput in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.",
+      },
     ],
     anatomy: [
-      {name: 'Label', required: true, description: 'The label for the number input.'},
-      {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: 'Label',
+        required: true,
+        description: 'The label for the number input.',
+      },
+      {
+        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: 'Number steppers',
+        required: false,
+        description:
+          'Optional buttons that increment or decrement by the configured step.',
+      },
     ],
   },
   propDescriptions: {
@@ -412,6 +618,8 @@ export const docsDense = {
     isOptional: 'Field optional (mutually exclusive w/ isRequired).',
     isRequired: 'Field required (mutually exclusive w/ isOptional).',
     isDisabled: 'Input disabled.',
+    isReadOnly:
+      'Read-only: value visible + still submits, but not editable. Unlike isDisabled: not dimmed, stays in tab order.',
     disabledMessage:
       'Explains why input is disabled. With isDisabled, shows tooltip on hover/focus + keeps input focusable via aria-disabled (field becomes read-only). Use instead of wrapping a disabled NumberInput in Tooltip.',
     placeholder: 'Placeholder text.',
@@ -419,13 +627,20 @@ export const docsDense = {
     startIcon: 'Icon at input start.',
     labelIcon: 'Icon before label text.',
     status: 'Validation status w/ optional message.',
-    statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon.',
+    statusVariant:
+      'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon.',
     min: 'Minimum value allowed.',
     max: 'Maximum value allowed.',
     step: 'Step increment.',
+    formatValue:
+      'Formats committed value at rest; raw number is shown while editing.',
+    isWheelEnabled:
+      'Allow focused wheel gestures to step value. Defaults to true.',
+    hasNumberSteppers: 'Show increment + decrement buttons. Defaults to false.',
     units: 'Units suffix (e.g. "%" or "GB").',
     isIntegerOnly: 'Only allow integer values.',
-    hasClear: 'Shows clear button when input has value. onChange also accepts null on clear.',
+    hasClear:
+      'Shows clear button when input has value. onChange also accepts null on clear.',
     htmlName: 'HTML name for form submissions.',
     autoComplete: 'HTML autocomplete attribute.',
     hasAutoFocus: 'Focus input on mount.',