Skip to content

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

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

/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
const anatomy = [
  {
    name: 'Progress bar',
    required: true,
    description: 'Container arranging the label row and progress track.',
  },
  {
    name: 'Label',
    required: true,
    description:
      'Text naming the operation, optionally hidden visually while remaining accessible.',
  },
  {
    name: 'Value text',
    required: false,
    description:
      'Formatted determinate value shown beside the label when requested.',
  },
  {
    name: 'Track',
    required: true,
    description:
      'Remaining-progress rail that carries the progressbar semantics.',
  },
  {
    name: 'Fill',
    required: true,
    description:
      'Painted segment showing completed progress or indeterminate movement.',
  },
  {
    name: 'Mark',
    required: false,
    description: 'Labeled target tick positioned on a determinate track.',
  },
];

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

export const docs = {
  name: 'ProgressBar',
  displayName: 'Progress Bar',
  category: 'Feedback & Status',
  keywords: [
    'progressbar',
    'progress',
    'loader',
    'loading',
    'linear',
    'determinate',
    'indeterminate',
    'meter',
    'linearprogress',
  ],
  props: [
    {
      name: 'label',
      type: 'string',
      description: 'accessible label',
      required: true,
    },
    {
      name: 'value',
      type: 'number',
      description: 'Current value (ignored when indeterminate).',
      default: '0',
    },
    {
      name: 'max',
      type: 'number',
      description: 'Maximum value.',
      default: '100',
    },
    {
      name: 'isLabelHidden',
      type: 'boolean',
      description: 'Visually hide the label (remains accessible).',
      default: 'false',
    },
    {
      name: 'hasValueLabel',
      type: 'boolean',
      description: 'Show formatted value text (ignored when indeterminate).',
      default: 'false',
    },
    {
      name: 'formatValueLabel',
      type: '(value: number, max: number) => string',
      description:
        'Custom value label formatter; defaults to a percentage string.',
    },
    {
      name: 'variant',
      type: "'accent' | 'success' | 'warning' | 'error' | 'neutral'",
      description: 'Semantic color variant.',
      default: "'accent'",
    },
    {
      name: 'isIndeterminate',
      type: 'boolean',
      description:
        'Animated loading indicator for unknown progress. Under reduced motion it pulses in place instead of sliding.',
      default: 'false',
    },
    {
      name: 'marks',
      type: 'ReadonlyArray<{value: number; label: string}>',
      description:
        "Fixed target marks drawn on the track at values in the same 0..max scale as value (e.g. a goal line). They stay visible whether progress is below or past them, and take their color from what they sit on: a mark inside the filled area uses the fill variant's on-color (on-accent, on-warning, on-error, and so on), a mark still out on the bare track uses the primary text color (the secondary one on a disabled bar, which dims everything it draws). Each mark requires a label: it is the mark's accessible name and the text revealed via a tooltip on hover/focus. Ignored when indeterminate.",
    },
    {
      name: 'isDisabled',
      type: 'boolean',
      description:
        'Visually disabled state: grays out the fill and text. Use for canceled or inactive operations.',
      default: 'false',
    },
    {
      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-progress-bar', visualProps: ['variant']},
      {className: 'astryx-progress-bar-fill', visualProps: ['variant']},
      {className: 'astryx-progress-bar-track'},
      {
        className: 'astryx-progress-bar-mark',
        visualProps: ['variant', 'placement'],
      },
    ],
    vars: [
      {
        name: '--_progressbar-mark-width',
        description: 'Target mark tick width',
        default: '2px',
        private: true,
      },
      {
        name: '--_progressbar-mark-height',
        description: 'Target mark tick height',
        default: '8px',
        private: true,
      },
    ],
    derived: [
      {property: 'width', vars: ['--_progressbar-mark-width'], replaces: true},
      {
        property: 'height',
        vars: ['--_progressbar-mark-height'],
        replaces: true,
      },
    ],
  },
  usage: {
    anatomy,
    description:
      "A horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can't be calculated. Supports semantic color variants, value labels, and custom formatting. Under a finger a new value animates as on iOS: linearly, in proportion to how far it moves (a full track takes one second at the theme's default tempo), and the fill keeps a minimum visible length above zero.",
    bestPractices: [
      {
        guidance: true,
        description:
          "Use a determinate bar when the total amount of work is known, and indeterminate when it's not.",
      },
      {
        guidance: true,
        description:
          'Choose a color variant that matches the context: accent for general progress, success for completion, warning or error for alerts.',
      },
      {
        guidance: true,
        description:
          "Always provide a label, even if hidden; screen readers need it to announce what's loading.",
      },
      {
        guidance: false,
        description:
          'Place icons or labels inside the bar; compose them alongside it using layout components.',
      },
      {
        guidance: false,
        description:
          "Use a progress bar for instant actions; it's meant for operations that take noticeable time.",
      },
      {
        guidance: false,
        description:
          'Use multiple progress bars stacked together for the same operation; use one bar with a value label instead.',
      },
    ],
  },
};

/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docsZh = {
  name: 'ProgressBar',
  displayName: 'Progress Bar',
  props: [
    {
      name: 'label',
      type: 'string',
      description: '无障碍标签(必填)。',
      required: true,
    },
    {
      name: 'value',
      type: 'number',
      description: '当前值(不确定模式下忽略)。',
      default: '0',
    },
    {
      name: 'max',
      type: 'number',
      description: '最大值。',
      default: '100',
    },
    {
      name: 'isLabelHidden',
      type: 'boolean',
      description: '视觉上隐藏标签(仍保持无障碍可访问性)。',
      default: 'false',
    },
    {
      name: 'hasValueLabel',
      type: 'boolean',
      description: '显示格式化的值文本(不确定模式下忽略)。',
      default: 'false',
    },
    {
      name: 'formatValueLabel',
      type: '(value: number, max: number) => string',
      description: '自定义值标签格式化器;默认为百分比字符串。',
    },
    {
      name: 'variant',
      type: "'accent' | 'success' | 'warning' | 'error' | 'neutral'",
      description: '语义颜色变体。',
      default: "'accent'",
    },
    {
      name: 'isIndeterminate',
      type: 'boolean',
      description: '用于未知进度的动画加载指示器。',
      default: 'false',
    },
    {
      name: 'marks',
      type: 'ReadonlyArray<{value: number; label: string}>',
      description:
        '在轨道上按与 value 相同的 0..max 刻度绘制的固定目标标记(例如目标线)。无论进度低于还是超过它们都保持可见,并根据所处位置取色:位于已填充区域内的标记使用与填充变体配对的前景色(on-accent、on-warning、on-error 等),仍位于空轨道上的标记使用主文本颜色(禁用状态下会降为次要文本颜色,与其整体弱化的呈现保持一致)。每个标记都必须提供 label——它既是标记的无障碍名称,也是悬停/聚焦时通过工具提示显示的文本。不确定模式下忽略。',
    },
    {
      name: 'isDisabled',
      type: 'boolean',
      description:
        '视觉禁用状态——使填充条和文本变灰。用于已取消或不活跃的操作。',
      default: 'false',
    },
    {
      name: 'xstyle',
      type: 'StyleXStyles',
      description:
        '用于布局自定义的 StyleX 样式(边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。',
    },
  ],
  theming: {
    targets: [
      {className: 'astryx-progress-bar', visualProps: ['variant']},
      {className: 'astryx-progress-bar-fill', visualProps: ['variant']},
      {className: 'astryx-progress-bar-track'},
      {
        className: 'astryx-progress-bar-mark',
        visualProps: ['variant', 'placement'],
      },
    ],
    vars: [
      {
        name: '--_progressbar-mark-width',
        description: '目标标记刻度宽度',
        default: '2px',
        private: true,
      },
      {
        name: '--_progressbar-mark-height',
        description: '目标标记刻度高度',
        default: '8px',
        private: true,
      },
    ],
    derived: [
      {property: 'width', vars: ['--_progressbar-mark-width'], replaces: true},
      {
        property: 'height',
        vars: ['--_progressbar-mark-height'],
        replaces: true,
      },
    ],
  },
  usage: {
    anatomy,
    description:
      "A horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can't be calculated. Supports semantic color variants, value labels, and custom formatting. Under a finger a new value animates as on iOS: linearly, in proportion to how far it moves (a full track takes one second at the theme's default tempo), and the fill keeps a minimum visible length above zero.",
    bestPractices: [
      {
        guidance: true,
        description:
          "Use a determinate bar when the total amount of work is known, and indeterminate when it's not.",
      },
      {
        guidance: true,
        description:
          'Choose a color variant that matches the context: accent for general progress, success for completion, warning or error for alerts.',
      },
      {
        guidance: true,
        description:
          "Always provide a label, even if hidden; screen readers need it to announce what's loading.",
      },
      {
        guidance: false,
        description:
          'Place icons or labels inside the bar; compose them alongside it using layout components.',
      },
      {
        guidance: false,
        description:
          "Use a progress bar for instant actions; it's meant for operations that take noticeable time.",
      },
      {
        guidance: false,
        description:
          'Use multiple progress bars stacked together for the same operation; use one bar with a value label instead.',
      },
    ],
  },
};

/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
export const docsDense = {
  description:
    'Progress bar for displaying determinate or indeterminate progress.',
  usage: {
    anatomy,
    description:
      "A horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can't be calculated. Supports semantic color variants, value labels, and custom formatting. Under a finger a new value animates as on iOS: linearly, in proportion to how far it moves (a full track takes one second at the theme's default tempo), and the fill keeps a minimum visible length above zero.",
    bestPractices: [
      {
        guidance: true,
        description:
          "Use a determinate bar when the total amount of work is known, and indeterminate when it's not.",
      },
      {
        guidance: true,
        description:
          'Choose a color variant that matches the context: accent for general progress, success for completion, warning or error for alerts.',
      },
      {
        guidance: true,
        description:
          "Always provide a label, even if hidden; screen readers need it to announce what's loading.",
      },
      {
        guidance: false,
        description:
          'Place icons or labels inside the bar; compose them alongside it using layout components.',
      },
      {
        guidance: false,
        description:
          "Use a progress bar for instant actions; it's meant for operations that take noticeable time.",
      },
      {
        guidance: false,
        description:
          'Use multiple progress bars stacked together for the same operation; use one bar with a value label instead.',
      },
    ],
  },
  propDescriptions: {
    label: 'accessible label',
    value: 'Current value (ignored when indeterminate).',
    max: 'Maximum value.',
    isLabelHidden: 'Visually hide label (remains accessible).',
    hasValueLabel: 'Show formatted value text (ignored when indeterminate).',
    formatValueLabel:
      'Custom value label formatter; defaults to percentage string.',
    variant: 'Semantic color variant.',
    isIndeterminate:
      'Animated loading indicator for unknown progress. Under reduced motion it pulses in place instead of sliding.',
    marks:
      'Fixed target marks ({value, label?}) drawn on the track in the 0..max scale; stay visible past the fill. Marks inside the fill take the variant on-color; marks on the bare track take the primary text color (secondary when disabled). A label reveals a tooltip on hover/focus. Ignored when indeterminate.',
    isDisabled: 'Visually disabled: grays out fill and text.',
    xstyle:
      'StyleX styles for layout customization. Must be stylex.create() value.',
  },
};