Skip to content

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

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

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

export const docs = {
  name: 'RadioList',
  displayName: 'Radio List',
  group: 'Radio',
  category: 'Form Controls',
  keywords: [
    'radiolist',
    'radio',
    'radiogroup',
    'radiobutton',
    'optionlist',
    'singlechoice',
    'choicelist',
  ],
  theming: {
    targets: [
      {className: 'astryx-radio-list', visualProps: ['orientation', 'size']},
      {
        className: 'astryx-radio-list-item',
        visualProps: ['size'],
        states: ['selected', 'disabled'],
      },
      {
        className: 'astryx-radio-indicator',
        visualProps: ['size'],
        states: ['checked', 'disabled'],
      },
      {className: 'astryx-radio-indicator-dot', visualProps: ['size']},
    ],
  },
  description:
    'Radio group container with field integration for label, description, and status.',
  props: [
    {
      name: 'label',
      type: 'string',
      description:
        'Label text for the radio group (always rendered for accessibility).',
      required: true,
    },
    {
      name: 'value',
      type: 'string',
      description: 'The currently selected value.',
      required: true,
    },
    {
      name: 'onChange',
      type: '(value: string) => void',
      description: 'Callback fired when the selected value changes.',
      required: true,
    },
    {
      name: 'children',
      type: 'ReactNode',
      description: 'RadioListItem elements.',
      slotElements: [
        {
          __element: 'RadioListItem',
          props: {
            label: 'Option',
            value: 'option',
          },
        },
      ],
      required: true,
    },
    {
      name: 'isLabelHidden',
      type: 'boolean',
      description: 'Whether to visually hide the label.',
      default: 'false',
    },
    {
      name: 'description',
      type: 'string',
      description: 'Description text displayed below the label.',
    },
    {
      name: 'orientation',
      type: "'vertical' | 'horizontal'",
      description: 'Layout direction of the radio items.',
      default: "'vertical'",
    },
    {
      name: 'isDisabled',
      type: 'boolean',
      description: 'Whether all radio items are disabled.',
      default: 'false',
    },
    {
      name: 'htmlName',
      type: 'string',
      description:
        'The HTML name attribute shared by the radio inputs, useful for form submissions. When omitted, a unique internal name still groups the radios.',
    },
    {
      name: 'disabledMessage',
      type: 'string',
      description:
        'Explains why the group is disabled. Applies to the whole-group disabled state (isDisabled), not per item. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the radios focusable via aria-disabled (selection stays blocked). Use this instead of wrapping a disabled RadioList in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
    },
    {
      name: 'isRequired',
      type: 'boolean',
      description: 'Whether the radio group is required.',
      default: 'false',
    },
    {
      name: 'isOptional',
      type: 'boolean',
      description:
        'Whether the field is optional (mutually exclusive with isRequired).',
      default: 'false',
    },
    {
      name: 'status',
      type: "{type: 'warning' | 'error' | 'success', message?: string}",
      description: 'Status indicator ({ type, message }).',
    },
    {
      name: 'size',
      type: "'sm' | 'md'",
      description: 'Size of the radio controls.',
      default: "'md'",
    },
    {
      name: 'labelTooltip',
      type: 'string',
      description: 'Tooltip text for an info icon next to the label.',
    },
    {
      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: '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.',
    },
  ],
  components: [{name: 'RadioListItem'}],
  usage: {
    accessibility: [
      {
        name: 'Radio circle',
        category: 'Color contrast',
        criterion: '1.4.11 Non-text Contrast',
        requirement: '3:1',
        states: ['Rest', 'Hover', 'Pointer down', 'Selected'],
        description:
          'The circle edge (unselected) and fill (selected) must have at least 3:1 contrast with the surface behind them. For Hover and Pointer down, measure the final colors after the tint and the pressed overlay are applied.',
      },
    ],
    description:
      'A group of options where only one can be selected at a time. All options are visible at once, making it easy to compare choices. Use it when users need to pick one option from a small set.',
    bestPractices: [
      {
        guidance: true,
        description:
          'Keep the number of options small: typically 2 to 7 choices.',
      },
      {
        guidance: true,
        description:
          'Use clear, concise labels that differentiate each option at a glance.',
      },
      {
        guidance: true,
        description:
          "Pre-select a default option when there's a sensible default; don't leave the group empty unless the choice is optional.",
      },
      {
        guidance: false,
        description:
          'Use when multiple selections are needed; use CheckboxList instead.',
      },
      {
        guidance: false,
        description:
          'Use for long lists; use Selector for better discoverability.',
      },
      {
        guidance: false,
        description:
          'Use horizontal layout with more than 4 options; it wraps awkwardly.',
      },
      {
        guidance: false,
        description:
          'Wrap a disabled RadioList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
      },
    ],
    anatomy: [
      {
        name: 'Header',
        required: false,
        description: 'Optional heading above the radio list.',
      },
      {
        name: 'Children',
        required: true,
        description: 'The radio list items rendered as selectable options.',
      },
      {
        name: 'Label/Value',
        required: true,
        description: 'The text label and associated value for each radio item.',
      },
    ],
  },
};

/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
export const docsZh = {
  usage: {
    description:
      'A group of options where only one can be selected at a time. All options are visible at once, making it easy to compare choices. Use it when users need to pick one option from a small set.',
    bestPractices: [
      {
        guidance: true,
        description:
          'Keep the number of options small: typically 2 to 7 choices.',
      },
      {
        guidance: true,
        description:
          'Use clear, concise labels that differentiate each option at a glance.',
      },
      {
        guidance: true,
        description:
          "Pre-select a default option when there's a sensible default; don't leave the group empty unless the choice is optional.",
      },
      {
        guidance: false,
        description:
          'Use when multiple selections are needed; use CheckboxList instead.',
      },
      {
        guidance: false,
        description:
          'Use for long lists; use Selector for better discoverability.',
      },
      {
        guidance: false,
        description:
          'Use horizontal layout with more than 4 options; it wraps awkwardly.',
      },
      {
        guidance: false,
        description:
          'Wrap a disabled RadioList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
      },
    ],
    anatomy: [
      {
        name: 'Header',
        required: false,
        description: 'Optional heading above the radio list.',
      },
      {
        name: 'Children',
        required: true,
        description: 'The radio list items rendered as selectable options.',
      },
      {
        name: 'Label/Value',
        required: true,
        description: 'The text label and associated value for each radio item.',
      },
    ],
  },
};

/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
export const docsDense = {
  description:
    'Radio group component for single-value selection from list of options.',
  usage: {
    description:
      'A group of options where only one can be selected at a time. All options are visible at once, making it easy to compare choices. Use it when users need to pick one option from a small set.',
    bestPractices: [
      {
        guidance: true,
        description:
          'Keep the number of options small: typically 2 to 7 choices.',
      },
      {
        guidance: true,
        description:
          'Use clear, concise labels that differentiate each option at a glance.',
      },
      {
        guidance: true,
        description:
          "Pre-select a default option when there's a sensible default; don't leave the group empty unless the choice is optional.",
      },
      {
        guidance: false,
        description:
          'Use when multiple selections are needed; use CheckboxList instead.',
      },
      {
        guidance: false,
        description:
          'Use for long lists; use Selector for better discoverability.',
      },
      {
        guidance: false,
        description:
          'Use horizontal layout with more than 4 options; it wraps awkwardly.',
      },
      {
        guidance: false,
        description:
          'Wrap a disabled RadioList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
      },
    ],
    anatomy: [
      {
        name: 'Header',
        required: false,
        description: 'Optional heading above the radio list.',
      },
      {
        name: 'Children',
        required: true,
        description: 'The radio list items rendered as selectable options.',
      },
      {
        name: 'Label/Value',
        required: true,
        description: 'The text label and associated value for each radio item.',
      },
    ],
  },
};