Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
25.9 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */

export const docs = {
  name: 'NumberInput',
  displayName: 'Number Input',
  category: 'Form Controls',
  keywords: [
    'numberinput',
    'numberfield',
    'stepper',
    'spinner',
    'counter',
    'increment',
    'decrement',
    'quantity',
    'numberpicker',
  ],
  props: [
    {
      name: 'label',
      type: 'string',
      description:
        'Label text for the input (always rendered for accessibility).',
      required: true,
    },
    {
      name: 'value',
      type: 'number | null | undefined',
      description: 'Current value of the input.',
      required: true,
    },
    {
      name: 'onChange',
      type: '(value: number) => void',
      description:
        'Callback fired when a valid text edit commits on blur or Enter, or when a step or clear control changes the value.',
      required: true,
    },
    {
      name: 'size',
      type: "'sm' | 'md' | 'lg'",
      description: 'Size variant.',
      default: "'md'",
    },
    {
      name: 'isLabelHidden',
      type: 'boolean',
      description:
        'Visually hide the label (still accessible to screen readers).',
    },
    {
      name: 'description',
      type: 'string',
      description: 'Description text displayed between the label and input.',
    },
    {
      name: 'isOptional',
      type: 'boolean',
      description:
        'Whether the field is optional (mutually exclusive with isRequired).',
    },
    {
      name: 'onKeyDown',
      type: '(e: KeyboardEvent<HTMLInputElement>) => void',
      description: 'Callback fired on keydown events on the input.',
    },
    {
      name: 'isRequired',
      type: 'boolean',
      description:
        'Whether the field is required (mutually exclusive with isOptional).',
    },
    {
      name: 'isDisabled',
      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 keeps its form value. 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',
      description:
        'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (the field becomes read-only). Use this instead of wrapping a disabled NumberInput in Tooltip.',
    },
    {
      name: 'placeholder',
      type: 'string',
      description: 'Placeholder text.',
    },
    {
      name: 'labelTooltip',
      type: 'string',
      description:
        'Tooltip text to display in an info icon at the end of the label.',
    },
    {
      name: 'startIcon',
      type: 'IconType',
      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.',
    },
    {
      name: 'status',
      type: "{type: 'error' | 'warning' | 'success', message?: string}",
      description: 'Validation status with optional message.',
    },
    {
      name: 'statusVariant',
      type: "'attached' | 'detached' | 'tooltip'",
      description:
        'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing; tooltip hides the message box and surfaces it in a tooltip on the status icon.',
      default: "'attached'",
    },
    {
      name: 'min',
      type: 'number | null',
      description:
        'Minimum value allowed. A smaller entry commits at this value on blur or Enter.',
    },
    {
      name: 'max',
      type: 'number | null',
      description:
        'Maximum value allowed. A larger entry commits at this value on blur or Enter.',
    },
    {
      name: 'step',
      type: 'number | null',
      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 on fine pointers. Hidden on coarse pointers (such as touch screens); text entry and keyboard stepping remain available. Holding a button with a mouse or a pen repeats the step and commits once, when the hold ends.',
      default: 'false',
    },
    {
      name: 'units',
      type: 'string | null',
      description:
        'Units text to display at the end of the input (e.g., "%" or "GB").',
    },
    {
      name: 'isIntegerOnly',
      type: 'boolean',
      description: 'Only allow integer values (no floating point).',
    },
    {
      name: 'hasClear',
      type: 'boolean',
      description:
        'Shows a clear (\u00d7) button when the input has a value. When true, the onChange callback also accepts null to signal the user cleared the input.',
      default: 'false',
    },
    {
      name: 'htmlName',
      type: 'string',
      description: 'HTML name attribute for form submissions.',
    },
    {
      name: 'autoComplete',
      type: 'string',
      description: 'HTML autocomplete attribute.',
    },
    {
      name: 'width',
      type: 'SizeValue',
      description:
        'Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.',
    },
    {
      name: 'hasAutoFocus',
      type: 'boolean',
      description: 'Whether to focus the input on mount.',
    },
    {
      name: 'onFocus',
      type: '(e: FocusEvent<HTMLInputElement>) => void',
      description: 'Callback fired when the input receives focus.',
    },
    {
      name: 'onBlur',
      type: '(e: FocusEvent<HTMLInputElement>) => void',
      description: 'Callback fired when the input loses focus.',
    },
    {
      name: 'onEnter',
      type: '() => void',
      description: 'Callback fired when the user presses the Enter key.',
    },
    {
      name: 'containerXstyle',
      type: 'StyleXStyles',
      description:
        'StyleX styles for the field container (label, control, and status together). No effect inside InputGroup (style the InputGroup instead) or in a `horizontal-labels` FormLayout. Root `xstyle`, `className`, and `style` are not accepted.',
    },
    {
      name: 'containerClassName',
      type: 'string',
      description:
        'Class name for the field container. Same targeting as `containerXstyle`.',
    },
    {
      name: 'containerStyle',
      type: 'CSSProperties',
      description:
        'Inline styles for the field container. Same targeting as `containerXstyle`.',
    },
    {
      name: 'controlXstyle',
      type: 'StyleXStyles',
      description:
        'StyleX styles for the visual control box: the element that paints the border and background and holds icons and end controls. Never the native input.',
    },
    {
      name: 'controlClassName',
      type: 'string',
      description: 'Class name for the visual control box.',
    },
    {
      name: 'controlStyle',
      type: 'CSSProperties',
      description: 'Inline styles for the visual control box.',
    },
  ],
  theming: {
    targets: [
      {
        className: 'astryx-number-input',
        visualProps: ['size', 'status'],
        states: ['disabled', 'readonly'],
      },
    ],
    derived: [
      // `padding` in any spelling — the shorthand, `paddingBlock`, or a lone
      // `paddingBlockStart` — is parsed by the shared container expansion and
      // emitted as normalized per-side `--astryx-number-input-padding-*`
      // tokens. The wrapper and the number-stepper column both read those, so
      // the column stays flush with the field edges under a themed padding.
      {property: 'padding', expand: 'container'},
      // Scoped to this component's own subtree: the stepper column's outer
      // corners follow the field radius, so a themed `number-input`
      // borderRadius has to reach the var the column reads, not just the
      // wrapper's own `border-radius`.
      {property: 'borderRadius', vars: ['--_field-radius']},
    ],
  },
  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:
          "Let people paste formatted numbers: a pasted 1,234,234,234 is read under the field's locale and commits as 1234234234 on blur. Typing is never intercepted.",
      },
      {
        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. Use the disabledMessage prop, which attaches the reason to the field itself.",
      },
    ],
    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: 'Number steppers',
        required: false,
        description:
          'Optional buttons that increment or decrement by the configured step.',
      },
    ],
  },
};

/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docsZh = {
  name: 'NumberInput',
  displayName: 'Number Input',
  props: [
    {
      name: 'label',
      type: 'string',
      description: '输入框的标签文本(始终渲染以确保无障碍访问)。',
      required: true,
    },
    {
      name: 'value',
      type: 'number | null | undefined',
      description: '输入框的当前值。',
      required: true,
    },
    {
      name: 'onChange',
      type: '(value: number) => void',
      description:
        '有效文本编辑在失焦或按 Enter 时提交;步进或清除控件更改值时也会触发回调。',
      required: true,
    },
    {
      name: 'size',
      type: "'sm' | 'md' | 'lg'",
      description: '尺寸变体。',
      default: "'md'",
    },
    {
      name: 'isLabelHidden',
      type: 'boolean',
      description: '视觉隐藏标签(屏幕阅读器仍可访问)。',
    },
    {
      name: 'description',
      type: 'string',
      description: '显示在标签和输入框之间的描述文本。',
    },
    {
      name: 'isOptional',
      type: 'boolean',
      description: '字段是否可选(与 isRequired 互斥)。',
    },
    {
      name: 'isRequired',
      type: 'boolean',
      description: '字段是否必填(与 isOptional 互斥)。',
    },
    {
      name: 'isDisabled',
      type: 'boolean',
      description: '输入框是否禁用。',
    },
    {
      name: 'isReadOnly',
      type: 'boolean',
      description:
        '将输入框设为只读:值以完整不透明度显示并仍随表单提交,但无法编辑。与 isDisabled 不同,只读输入框不会变暗,并保留其表单值。只读时所有步进方式均被禁用:方向键、滚轮和步进按钮。同时设置时 isDisabled 优先。',
      default: 'false',
    },
    {
      name: 'disabledMessage',
      type: 'string',
      description:
        '说明输入框被禁用的原因。与 isDisabled 一起使用时,在悬停/键盘聚焦时显示工具提示,并通过 aria-disabled 保持输入框可聚焦(字段变为只读)。请使用此属性,而不是用 Tooltip 包裹已禁用的 NumberInput。',
    },
    {
      name: 'placeholder',
      type: 'string',
      description: '占位符文本。',
    },
    {
      name: 'labelTooltip',
      type: 'string',
      description: '在标签末尾的信息图标中显示的工具提示文本。',
    },
    {
      name: 'startIcon',
      type: 'IconType',
      description: '显示在输入框起始位置的图标。',
    },
    {
      name: 'labelIcon',
      type: 'IconType',
      description: '显示在标签文本前的图标。',
    },
    {
      name: 'status',
      type: "{type: 'error' | 'warning' | 'success', message?: string}",
      description: '带可选消息的验证状态。',
    },
    {
      name: 'statusVariant',
      type: "'attached' | 'detached' | 'tooltip'",
      description:
        '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方(带边框处理);detached 作为独立元素浮于下方并留有间距;tooltip 隐藏消息框,并在状态图标上以提示气泡形式显示。',
      default: "'attached'",
    },
    {
      name: 'min',
      type: 'number | null',
      description: '允许的最小值。更小的输入会在失焦或按 Enter 时提交为该值。',
    },
    {
      name: 'max',
      type: 'number | null',
      description: '允许的最大值。更大的输入会在失焦或按 Enter 时提交为该值。',
    },
    {
      name: 'step',
      type: 'number | null',
      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")。',
    },
    {
      name: 'isIntegerOnly',
      type: 'boolean',
      description: '仅允许整数值(不允许浮点数)。',
    },
    {
      name: 'hasClear',
      type: 'boolean',
      description:
        '输入有值时显示清除 (×) 按鈕。启用后, onChange 回调还接受 null 表示用户已清空输入。',
      default: 'false',
    },
    {
      name: 'htmlName',
      type: 'string',
      description: '用于表单提交的 HTML name 属性。',
    },
    {
      name: 'autoComplete',
      type: 'string',
      description: 'HTML autocomplete 属性。',
    },
    {
      name: 'hasAutoFocus',
      type: 'boolean',
      description: '是否在挂载时聚焦输入框。',
    },
    {
      name: 'onFocus',
      type: '(e: FocusEvent<HTMLInputElement>) => void',
      description: '输入框获得焦点时触发的回调。',
    },
    {
      name: 'onBlur',
      type: '(e: FocusEvent<HTMLInputElement>) => void',
      description: '输入框失去焦点时触发的回调。',
    },
    {
      name: 'onEnter',
      type: '() => void',
      description: '用户按下 Enter 键时触发的回调。',
    },
    {
      name: 'containerXstyle',
      type: 'StyleXStyles',
      description:
        '字段容器(标签、控件和状态整体)的 StyleX 样式。在 InputGroup 内(请改为设置 InputGroup 的样式)或 `horizontal-labels` FormLayout 中无效。不接受根级 `xstyle`、`className` 和 `style`。',
    },
    {
      name: 'containerClassName',
      type: 'string',
      description: '字段容器的类名,作用目标同 `containerXstyle`。',
    },
    {
      name: 'containerStyle',
      type: 'CSSProperties',
      description: '字段容器的内联样式,作用目标同 `containerXstyle`。',
    },
    {
      name: 'controlXstyle',
      type: 'StyleXStyles',
      description:
        '可视控件框的 StyleX 样式:绘制边框和背景并包含图标与尾部控件的元素,而非原生输入元素。',
    },
    {
      name: 'controlClassName',
      type: 'string',
      description: '可视控件框的类名。',
    },
    {
      name: 'controlStyle',
      type: 'CSSProperties',
      description: '可视控件框的内联样式。',
    },
  ],
  theming: {
    targets: [
      {
        className: 'astryx-number-input',
        visualProps: ['size', 'status'],
        states: ['disabled', 'readonly'],
      },
    ],
    derived: [
      // 任何写法的 `padding`(简写、`paddingBlock`,或单独的
      // `paddingBlockStart`)都由共享的 container 展开解析,并输出为规范化的
      // 每侧 `--astryx-number-input-padding-*` 令牌。容器与数字步进器列都读取
      // 这些令牌,因此在主题化内边距下步进器仍与字段边缘齐平。
      {property: 'padding', expand: 'container'},
      // 作用域限于该组件自身的子树:步进器列的外角跟随字段圆角,因此主题化的
      // `number-input` borderRadius 必须传到步进器读取的变量,而不只是容器
      // 自身的 `border-radius`。
      {property: 'borderRadius', vars: ['--_field-radius']},
    ],
  },
  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:
          '可以直接粘贴带格式的数字:粘贴 1,234,234,234 会按字段所在区域设置解析,失去焦点时提交为 1234234234。输入过程中不会拦截按键。',
      },
      {
        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. Use the disabledMessage prop, which attaches the reason to the field itself.",
      },
    ],
    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: '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.',
  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:
          "Pasted formatted numbers parse: 1,234,234,234 commits as 1234234234 under the field's locale. Typing is never intercepted.",
      },
      {
        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. Use the disabledMessage prop, which attaches the reason to the field itself.",
      },
    ],
    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: 'Number steppers',
        required: false,
        description:
          'Optional buttons that increment or decrement by the configured step.',
      },
    ],
  },
  propDescriptions: {
    containerXstyle:
      'StyleX styles for the field container; no effect in InputGroup or horizontal-labels FormLayout. No root xstyle/className/style.',
    containerClassName: 'Class name for the field container.',
    containerStyle: 'Inline styles for the field container.',
    controlXstyle:
      'StyleX styles for the visual control box (border, background, icons); not the native input.',
    controlClassName: 'Class name for the visual control box.',
    controlStyle: 'Inline styles for the visual control box.',
    label: 'Label text (always rendered for accessibility).',
    value: 'Current input value.',
    onChange:
      'Callback when a valid text edit commits on blur/Enter, or a step/clear control changes the value.',
    size: 'Size variant.',
    isLabelHidden: 'Visually hide label (still accessible to screen readers).',
    description: 'Text between label + input.',
    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.',
    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.',
    labelTooltip: 'Tooltip text in info icon at label end.',
    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.',
    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 on fine pointers; hidden on coarse pointers. 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.',
    htmlName: 'HTML name for form submissions.',
    autoComplete: 'HTML autocomplete attribute.',
    hasAutoFocus: 'Focus input on mount.',
    onFocus: 'Callback on focus.',
    onBlur: 'Callback on blur.',
    onEnter: 'Callback on Enter key.',
  },
};