Skip to content

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

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

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

export const docs = {
  name: 'FormLayout',
  displayName: 'Form Layout',
  group: 'Layout',
  category: 'Layout',
  keywords: [
    'formlayout',
    'form',
    'fieldset',
    'formgroup',
    'formcontainer',
    'fields',
    'vertical',
    'horizontal',
  ],
  props: [
    {
      name: 'direction',
      type: "'vertical' | 'horizontal' | 'horizontal-labels'",
      description:
        'Controls field arrangement. Vertical stacks top-to-bottom, horizontal uses one fractional grid track per field in logical inline order, and horizontal-labels uses CSS Grid with labels beside inputs on the inline-start side (collapsing to vertical when the viewport is <=480px).',
      default: "'vertical'",
    },
    {
      name: 'defaultOptionality',
      type: "'optional' | 'required'",
      description:
        'The state the form treats as its default, so only the exception shows an optional/required indicator. With "optional", only fields marked isRequired show an indicator; with "required", only fields marked isOptional do. A field that restates the default shows nothing. Under "required" the unmarked fields also expose aria-required so screen readers match the visual default; aria-required only, never the native required attribute. CheckboxInput, Switch and CheckboxList are the exception: an unchecked box, an off switch or an empty group is an answer, so they take no required state from the default. A CheckboxInput or Switch is required only through its own isRequired. Leave unset for today\'s per-field behavior.',
    },
    {
      name: 'children',
      type: 'ReactNode',
      description:
        'Form fields to arrange. Accepts Astryx inputs (TextInput, Selector, etc.) and Field-wrapped custom controls.',
    },
    {
      name: 'xstyle',
      type: 'StyleXStyles',
      description:
        'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.',
    },
  ],
  theming: {
    targets: [{className: 'astryx-form-layout', visualProps: ['direction']}],
  },
  usage: {
    description:
      'A layout container that arranges form fields with consistent spacing and direction. FormLayout handles where fields go, not state or submission. Wrap it in a native <form> for that; <form> has no Astryx replacement, so it stays a plain element. Supports vertical (default), horizontal, and horizontal-labels directions, and can be nested to mix them.',
    bestPractices: [
      {
        guidance: true,
        description:
          "Stack fields vertically for most forms. It's the easiest to scan top to bottom.",
      },
      {
        guidance: true,
        description:
          'Nest a horizontal FormLayout inside a vertical one when fields naturally pair up, like First Name + Last Name or City + State + ZIP.',
      },
      {
        guidance: true,
        description:
          'Use horizontal-labels for settings pages where labels sit beside their inputs.',
      },
      {
        guidance: false,
        description:
          "Use FormLayout for form state or submission. It's just layout. Wrap it in a native <form> for that.",
      },
      {
        guidance: false,
        description:
          'Put unrelated fields side by side in a horizontal layout. Save it for fields that belong together.',
      },
      {
        guidance: false,
        description:
          'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.',
      },
    ],
    anatomy: [
      {
        name: 'Layout container',
        required: true,
        description:
          'Owns field arrangement, spacing, direction, and form-level optionality.',
      },
      {
        name: 'Form title',
        required: false,
        description: 'Heading that describes the purpose of the form.',
      },
      {
        name: 'Fields',
        required: true,
        description: 'Input components with labels for collecting user data.',
      },
      {
        name: 'Footer',
        required: false,
        description: 'Contains confirmation buttons such as Submit or Cancel.',
      },
    ],
  },
};

/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docsZh = {
  name: 'FormLayout',
  displayName: 'Form Layout',
  props: [
    {
      name: 'direction',
      type: "'vertical' | 'horizontal' | 'horizontal-labels'",
      description:
        '控制字段排列方式。vertical 从上到下堆叠;horizontal 为每个字段使用一个 1fr 网格轨道,并按逻辑行内方向排列;horizontal-labels 使用 CSS Grid,将标签放在输入框的行内起始侧(当视口宽度 <=480px 时折叠为垂直布局)。',
      default: "'vertical'",
    },
    {
      name: 'defaultOptionality',
      type: "'optional' | 'required'",
      description:
        '表单视为默认的状态,因此仅例外字段显示可选/必填指示器。设为 "optional" 时,仅标记 isRequired 的字段显示指示器;设为 "required" 时,仅标记 isOptional 的字段显示。与默认一致的字段不显示任何内容。设为 "required" 时,未标记的字段仍会暴露 aria-required,使屏幕阅读器与视觉默认一致——仅作用于 aria-required,不改变原生 required 属性。CheckboxInput、Switch 和 CheckboxList 例外:未勾选的复选框、关闭的开关或空的复选框组本身就是一个回答,因此默认值不会赋予它们必填状态。CheckboxInput 或 Switch 只有通过自身的 isRequired 才会成为必填。不设置则保持当前逐字段行为。',
    },
    {
      name: 'children',
      type: 'ReactNode',
      description:
        '要排列的表单字段。接受 Astryx 输入组件(TextInput、Selector 等)和 Field 包装的自定义控件。',
    },
    {
      name: 'xstyle',
      type: 'StyleXStyles',
      description:
        '用于布局自定义(外边距、定位、尺寸)的 StyleX 样式。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。',
    },
  ],
  theming: {
    targets: [{className: 'astryx-form-layout', visualProps: ['direction']}],
  },
  usage: {
    description:
      'A layout container that arranges form fields with consistent spacing and direction. FormLayout handles where fields go, not state or submission. Wrap it in a native <form> for that; <form> has no Astryx replacement, so it stays a plain element. Supports vertical (default), horizontal, and horizontal-labels directions, and can be nested to mix them.',
    bestPractices: [
      {
        guidance: true,
        description:
          "Stack fields vertically for most forms. It's the easiest to scan top to bottom.",
      },
      {
        guidance: true,
        description:
          'Nest a horizontal FormLayout inside a vertical one when fields naturally pair up, like First Name + Last Name or City + State + ZIP.',
      },
      {
        guidance: true,
        description:
          'Use horizontal-labels for settings pages where labels sit beside their inputs.',
      },
      {
        guidance: false,
        description:
          "Use FormLayout for form state or submission. It's just layout. Wrap it in a native <form> for that.",
      },
      {
        guidance: false,
        description:
          'Put unrelated fields side by side in a horizontal layout. Save it for fields that belong together.',
      },
      {
        guidance: false,
        description:
          'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.',
      },
    ],
    anatomy: [
      {
        name: 'Layout container',
        required: true,
        description:
          'Owns field arrangement, spacing, direction, and form-level optionality.',
      },
      {
        name: 'Form title',
        required: false,
        description: 'Heading that describes the purpose of the form.',
      },
      {
        name: 'Fields',
        required: true,
        description: 'Input components with labels for collecting user data.',
      },
      {
        name: 'Footer',
        required: false,
        description: 'Contains confirmation buttons such as Submit or Cancel.',
      },
    ],
  },
};

/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
export const docsDense = {
  description:
    'Layout container for form fields w/ consistent spacing + direction.',
  usage: {
    description:
      'A layout container that arranges form fields with consistent spacing and direction. FormLayout handles where fields go, not state or submission. Wrap it in a native <form> for that; <form> has no Astryx replacement, so it stays a plain element. Supports vertical (default), horizontal, and horizontal-labels directions, and can be nested to mix them.',
    bestPractices: [
      {
        guidance: true,
        description:
          "Stack fields vertically for most forms. It's the easiest to scan top to bottom.",
      },
      {
        guidance: true,
        description:
          'Nest a horizontal FormLayout inside a vertical one when fields naturally pair up, like First Name + Last Name or City + State + ZIP.',
      },
      {
        guidance: true,
        description:
          'Use horizontal-labels for settings pages where labels sit beside their inputs.',
      },
      {
        guidance: false,
        description:
          "Use FormLayout for form state or submission. It's just layout. Wrap it in a native <form> for that.",
      },
      {
        guidance: false,
        description:
          'Put unrelated fields side by side in a horizontal layout. Save it for fields that belong together.',
      },
      {
        guidance: false,
        description:
          'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.',
      },
    ],
    anatomy: [
      {
        name: 'Layout container',
        required: true,
        description:
          'Owns field arrangement, spacing, direction, and form-level optionality.',
      },
      {
        name: 'Form title',
        required: false,
        description: 'Heading that describes the purpose of the form.',
      },
      {
        name: 'Fields',
        required: true,
        description: 'Input components with labels for collecting user data.',
      },
      {
        name: 'Footer',
        required: false,
        description: 'Contains confirmation buttons such as Submit or Cancel.',
      },
    ],
  },
  propDescriptions: {
    direction:
      'Field arrangement. Vertical stacks top-to-bottom; horizontal uses one fractional grid track per field in logical inline order; horizontal-labels places labels on the inline-start side and collapses when the viewport is <=480px.',
    defaultOptionality:
      'State the form treats as default, so only the exception is marked. "optional" → only isRequired fields show an indicator; "required" → only isOptional fields do. Under "required" unmarked fields also expose aria-required (aria only, not native required), except CheckboxInput, Switch and CheckboxList, which take no required state from it (CheckboxInput and Switch are required only through their own isRequired). Unset = per-field behavior.',
    children:
      'Form fields to arrange. Accepts Astryx inputs + Field-wrapped custom controls.',
    xstyle:
      'StyleX styles for layout customization. Must be stylex.create() value.',
  },
};