Skip to content

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

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

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

export const docs = {
  name: 'Chart',
  displayName: 'Chart',
  group: 'Charts',
  category: 'Data Visualization',
  keywords: [
    'chart',
    'graph',
    'plot',
    'visualization',
    'bar chart',
    'line chart',
    'data',
  ],

  usage: {
    description:
      'Chart lays out one or more mark definitions against shared responsive x and y scales. Use it for data visualizations that combine Astryx chart marks, axes, grids, legends, tooltips, and custom interaction layers.',
    bestPractices: [
      {
        guidance: true,
        description:
          'Give the chart a concise title that states what is measured, and use subtitle for the comparison, time range, or other context needed to interpret it.',
      },
      {
        guidance: true,
        description:
          'Use the same series array for Chart and any directly composed ChartTooltip so labels, colors, and resolved points stay aligned.',
      },
      {
        guidance: false,
        description:
          'Use color as the only way to distinguish series or communicate status. Pair color with labels, mark shapes, direct annotations, or another visible cue.',
      },
      {
        guidance: false,
        description:
          'Reuse one mark definition object across multiple Chart instances. Mark definitions currently carry per-chart layout metadata and are single-use.',
      },
    ],
    accessibility: [
      {
        name: 'Accessible chart name',
        category: 'Semantics',
        criterion: '1.1.1 Non-text Content',
        requirement: 'Required',
        states: ['All'],
        description:
          'Provide title when a product-specific name is available. Without it, Chart derives a localized name from the primary series labels and xKey.',
      },
      {
        name: 'Small-data table',
        category: 'Content',
        criterion: '1.1.1 Non-text Content',
        requirement: 'Required for supported small datasets',
        states: ['1–100 row × series cells'],
        description:
          'Chart mirrors small datasets into a visually hidden table. For larger datasets, provide an equivalent nearby summary or data view because the built-in table is intentionally omitted.',
      },
      {
        name: 'Meaningful chart graphics',
        category: 'Color contrast',
        criterion: '1.4.11 Non-text Contrast',
        requirement: '3:1 when the graphic carries information',
        states: ['Light', 'Dark', 'Supported themes'],
        description:
          'Measure meaningful marks and state indicators against their rendered backdrop. Decorative grid lines are not required to meet the non-text threshold.',
      },
      {
        name: 'Tooltip information',
        category: 'Keyboard',
        criterion: '2.1.1 Keyboard and 2.5.1 Pointer Gestures',
        requirement: 'Supplemental only',
        states: ['Tooltip enabled'],
        description:
          'Do not make hover-only tooltip content the only way to obtain important values. Keep the hidden table or another equivalent data view available.',
      },
    ],
    anatomy: [
      {
        name: 'Header',
        required: false,
        description:
          'Optional visible title and supporting subtitle above the plot.',
      },
      {
        name: 'Plot',
        required: true,
        description:
          'Responsive SVG coordinate space containing the clipped series marks.',
      },
      {
        name: 'Grid and axes',
        required: false,
        description:
          'Caller-supplied ChartGrid and ChartAxis elements that share the plot scales.',
      },
      {
        name: 'Legend',
        required: false,
        description:
          'Derived or caller-supplied series labels and swatches placed above, below, at the start, or at the end of the plot.',
      },
      {
        name: 'Tooltip and interactions',
        required: false,
        description:
          'Pointer-driven overlays that consume the chart interaction stream.',
      },
      {
        name: 'Data table',
        required: false,
        description:
          'Visually hidden tabular alternative rendered for small datasets.',
      },
    ],
  },

  props: [
    {
      name: 'data',
      type: 'Record<string, unknown>[]',
      description:
        'Rows to visualize. Each row may contain the x field and one or more series fields.',
      required: true,
    },
    {
      name: 'xKey',
      type: 'string',
      description: 'Field name read from each data row for the shared x scale.',
      required: true,
    },
    {
      name: 'series',
      type: 'SeriesDef[]',
      description:
        'Mark definitions created by helpers such as bar(), line(), area(), or dot(). Build a fresh array for each Chart.',
      required: true,
    },
    {
      name: 'height',
      type: 'number',
      description: 'Chart height in CSS pixels.',
      default: '300',
    },
    {
      name: 'margin',
      type: 'Partial<ChartMargin>',
      description:
        'Plot inset overrides in CSS pixels for top, right, bottom, and left.',
      default: '{top: 24, right: 24, bottom: 32, left: 48}',
    },
    {
      name: 'yBaseline',
      type: "'auto' | 'zero' | 'data'",
      description:
        'How Chart derives the y-domain when yDomain is omitted: mark-aware zero/headroom, symmetric around zero, or tight to the data extent.',
      default: "'auto'",
    },
    {
      name: 'yDomain',
      type: '[number, number]',
      description:
        'Explicit y-domain. When set, it takes precedence over yBaseline, automatic headroom, and scale nicening.',
    },
    {
      name: 'xDomain',
      type: '[number, number]',
      description:
        'Explicit x-domain for numeric scales, including an empty streaming window. Categorical scales ignore it.',
    },
    {
      name: 'grid',
      type: 'ReactNode',
      description:
        'Grid content rendered behind the series, normally ChartGrid.',
      slotElements: [{__element: 'ChartGrid', props: {horizontal: true}}],
    },
    {
      name: 'axes',
      type: 'ReactNode',
      description:
        'Axis content rendered after the series, normally one or more ChartAxis elements.',
      slotElements: [
        {__element: 'ChartAxis', props: {position: 'bottom'}},
        {__element: 'ChartAxis', props: {position: 'left'}},
      ],
    },
    {
      name: 'legend',
      type: 'boolean | ChartLegendProps',
      description:
        'Set true for a derived bottom legend, or pass items, position, and alignment.',
      default: 'false',
    },
    {
      name: 'tooltip',
      type: "boolean | Omit<ChartTooltipProps, 'series'>",
      description:
        'Set true for the grouped pointer tooltip, or pass render and presentation options.',
      default: 'false',
    },
    {
      name: 'interactions',
      type: 'ReactNode',
      description:
        'Interaction overlays rendered above the pointer-capture layer.',
    },
    {
      name: 'children',
      type: 'ReactNode',
      description:
        'Additional SVG content rendered after the built-in tooltip for advanced composition.',
    },
    {
      name: 'title',
      type: 'string',
      description:
        'Visible heading and accessible name for the chart image. A localized fallback is derived when omitted.',
    },
    {
      name: 'subtitle',
      type: 'string',
      description:
        'Visible supporting text that also describes the chart image.',
    },
    {
      name: 'ref',
      type: 'Ref<HTMLDivElement>',
      description: 'Ref forwarded to the root chart container.',
    },
    {
      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={{}}.',
    },
    {
      name: 'className',
      type: 'string',
      description: 'CSS class name appended to the root chart container.',
    },
    {
      name: 'style',
      type: 'CSSProperties',
      description:
        'Inline styles merged onto the root chart container after the component styles.',
    },
  ],

  examples: [
    {
      label: 'Bar and trend line',
      code: `import {Chart, ChartAxis, ChartGrid, bar, line} from '@astryxdesign/charts';

const series = [
  bar('revenue', {label: 'Revenue'}),
  line('trend', {label: 'Trend'}),
];

<Chart
  data={monthlyRevenue}
  xKey="month"
  series={series}
  title="Monthly revenue"
  grid={<ChartGrid horizontal />}
  axes={
    <>
      <ChartAxis position="bottom" />
      <ChartAxis position="left" />
    </>
  }
  legend
  tooltip
/>;`,
    },
    {
      label: 'Stable numeric window',
      code: `<Chart
  data={streamedValues}
  xKey="timestamp"
  series={[line('value')]}
  xDomain={[windowStart, windowEnd]}
  yDomain={[0, 100]}
  title="Live utilization"
/>;`,
    },
  ],
};