Skip to content

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

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

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

export const docs = {
  name: 'Popover',
  displayName: 'Popover',
  group: 'Popover',
  category: 'Overlay',
  keywords: [
    'popover',
    'popup',
    'dropdown',
    'tooltip',
    'overlay',
    'flyout',
    'callout',
    'popper',
    'anchor',
    'floating',
    'bubble',
  ],
  components: [
    {
      name: 'Popover',
      displayName: 'Popover',
      description:
        'A click-triggered popover for displaying interactive content anchored to a trigger element.',
      props: [
        {
          name: 'children',
          type: 'ReactNode',
          description:
            'Trigger element. Must contain a <button> or [role="button"] element.',
        },
        {
          name: 'anchorRef',
          type: 'React.RefObject<HTMLElement>',
          description:
            'External ref to use as the popover anchor in sibling mode.',
        },
        {
          name: 'content',
          type: 'ReactNode',
          description: 'Content to display inside the popover.',
          required: true,
          slotElements: [
            {
              __element: 'Text',
              props: {type: 'body'},
              children: 'Content text',
            },
          ],
        },
        {
          name: 'placement',
          type: "'above' | 'below' | 'start' | 'end'",
          description:
            "Position placement relative to the trigger. Logical: start/end resolve against the popover's own inherited direction, so RTL contexts mirror automatically in pure CSS.",
          default: "'below'",
        },
        {
          name: 'alignment',
          type: "'start' | 'center' | 'end'",
          description:
            "Alignment along the placement axis. Logical: start/end follow the popover's own inherited direction (RTL mirrors).",
          default: "'start'",
        },
        {
          name: 'isOpen',
          type: 'boolean',
          description: 'Whether the popover is shown in controlled mode.',
        },
        {
          name: 'onOpenChange',
          type: '(isOpen: boolean) => void',
          description: 'Callback fired when the popover visibility changes.',
        },
        {
          name: 'isEnabled',
          type: 'boolean',
          description: 'When false, trigger interactions are ignored.',
          default: 'true',
        },
        {
          name: 'width',
          type: 'number | string',
          description:
            'Width of the popover container. The layer still caps to the viewport with alignment-aware safe-area gutters before scrolling long content.',
          default: "'auto'",
        },
        {
          name: 'padding',
          type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
          description:
            'Inner padding of the popover surface on the spacing scale (0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10), matching the padding prop on Card and Stack. Pass 0 for a flush surface when the content owns its own edges, such as a list of rows or a header with a rule, and pad the content itself. The padding sits on the painted popover target, so a theme padding on that target replaces it.',
          default: '3',
        },
        {
          name: 'label',
          type: 'string',
          description:
            'Accessible label for the popover dialog. A sheet without one is named by the trigger\u2019s text.',
        },
        {
          name: 'role',
          type: "'dialog' | 'none'",
          description:
            'ARIA role for the popover wrapper. Use dialog for dialog-style popovers; use none when content provides its own role, like menu or listbox.',
          default: "'dialog'",
        },
        {
          name: 'isModal',
          type: 'boolean',
          description:
            'Whether a dialog-style popover sets aria-modal. Only applies when role is dialog.',
          default: 'true',
        },
        {
          name: 'hasCloseButton',
          type: 'boolean',
          description:
            'Whether to include a hidden close button for accessibility.',
          default: 'true',
        },
        {
          name: 'closeButtonLabel',
          type: 'string',
          description: 'Label for the hidden close button.',
          default: "'Close popover'",
        },
        {
          name: 'hasAutoFocus',
          type: 'boolean',
          description:
            'Whether to move focus into the popover when it opens. Focus enters the first genuine content control; dialogs with none fall back to the labeled surface. The generated fallback close control stays hidden until reached through keyboard navigation. Set to false for input-owned focus, inline showcases, or documentation previews.',
          default: 'true',
        },
        {
          name: 'hasLightDismiss',
          type: 'boolean',
          description:
            'Whether clicking outside dismisses the popover. Set to false for surfaces that stay open until explicitly dismissed, like onboarding coachmarks.',
          default: 'true',
        },
        {
          name: 'hasEscapeDismiss',
          type: 'boolean',
          description:
            'Whether pressing Escape dismisses the popover. Only takes full effect together with hasLightDismiss={false}, since native light dismiss also closes on Escape.',
          default: 'true',
        },
        {
          name: 'presentation',
          type: "'popover' | 'bottom-sheet' | 'adaptive'",
          description:
            "The surface that holds the content. 'popover' anchors it to the trigger, 'bottom-sheet' presents it in a modal BottomSheet labeled by label, and 'adaptive' uses the BottomSheet on a compact touch screen (a coarse pointer on a screen the theme counts as compact: narrower than its md width point or shorter than 500 px, so a phone in either orientation) and the anchored popover elsewhere. In a sheet, placement, alignment, width, role, isModal and hasAutoFocus do not apply, and xstyle, className and style style the sheet's panel; the sheet always light-dismisses (a tap outside it or a swipe down closes it, whatever hasLightDismiss says), Escape follows hasEscapeDismiss, and the fallback close stays hidden. The surface is chosen as it opens and kept until it closes.",
          default: "'popover'",
        },
        {
          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={{}}.',
        },
      ],
    },
  ],
  examples: [
    {
      label: 'Flush surface for a list of rows',
      code: `<Popover
  label="Recent files"
  padding={0}
  content={
    <List>
      <ListItem label="Quarterly report.pdf" />
      <ListItem label="Roadmap.key" />
    </List>
  }>
  <Button label="Recent" variant="secondary" />
</Popover>`,
    },
    {
      label: 'Roomier surface for a form',
      code: `<Popover
  label="Save search"
  padding={4}
  content={<SaveSearchForm />}>
  <Button label="Save search" variant="secondary" />
</Popover>`,
    },
  ],
  playground: {
    defaults: {
      content: {
        __element: 'Text',
        props: {type: 'body'},
        children: 'Popover content goes here.',
      },
      children: {
        __element: 'Button',
        props: {label: 'Open popover', variant: 'secondary'},
      },
    },
  },
  theming: {
    targets: [
      // Canonical broad target for the painted Popover surface.
      {className: 'astryx-popover'},
    ],
    vars: [
      {
        name: '--_popover-radius',
        description: 'Border radius of the popover surface',
        default: 'var(--radius-container)',
        private: true,
      },
    ],
    derived: [{property: 'borderRadius', vars: ['--_popover-radius']}],
  },
  usage: {
    description:
      'A click-triggered overlay anchored to a button or trigger element. Use it for secondary actions, inline confirmations, or supplementary information that does not warrant a full dialog. For hover previews use HoverCard, for brief helper text use Tooltip. Under a finger (a coarse primary pointer), it is presented like a native popover: it grows out of its trigger and shrinks back into it on the theme\u2019s motion tokens; with reduced motion it cross-fades, opacity only, in 200 ms or less.',
    bestPractices: [
      {
        guidance: true,
        description:
          'Keep popover content focused on a single task or piece of information.',
      },
      {
        guidance: true,
        description:
          'Provide a clear way to close: either by clicking outside or with an explicit close button.',
      },
      {
        guidance: true,
        description:
          'Theme the painted surface through the canonical popover target.',
      },
      {
        guidance: false,
        description:
          'Nest popovers inside other popovers; it creates confusing focus and navigation.',
      },
      {
        guidance: false,
        description:
          "Assume input complexity alone determines the presentation; evaluate the task's focus, space, and interaction requirements.",
      },
      {
        guidance: false,
        description:
          'Assume scrolling alone means Popover is the wrong component; a bounded Popover may scroll while a focused anchored interaction remains appropriate.',
      },
    ],
    anatomy: [
      {
        name: 'Trigger element',
        required: true,
        description:
          'Caller-supplied or externally referenced control that anchors and toggles the popover.',
      },
      {
        name: 'Popover surface',
        required: true,
        description:
          'Painted surface owned and themed by Popover through the canonical popover target.',
      },
      {
        name: 'Touch sheet',
        required: false,
        description:
          'BottomSheet surface that holds the same content in place of the popover surface for presentation="bottom-sheet", or "adaptive" on a compact touch screen; themed through the bottom-sheet target.',
      },
      {
        name: 'Popover content',
        required: true,
        description: 'Caller-supplied content rendered inside the surface.',
      },
      {
        name: 'Fallback close control',
        required: false,
        description:
          'Keyboard-reachable close affordance appended by usePopover when enabled.',
      },
    ],
  },
};

/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docsZh = {
  name: 'Popover',
  displayName: 'Popover',
  components: [
    {
      name: 'Popover',
      displayName: 'Popover',
      description: '一个点击触发的弹出框,用于显示锚定到触发元素的交互式内容。',
      props: [
        {
          name: 'children',
          type: 'ReactNode',
          description:
            '触发元素。必须包含一个 <button> 或 [role="button"] 元素。',
        },
        {
          name: 'anchorRef',
          type: 'React.RefObject<HTMLElement>',
          description: '在兄弟模式下用作弹出框锚点的外部 ref。',
        },
        {
          name: 'content',
          type: 'ReactNode',
          description: '在弹出框内显示的内容。',
          required: true,
        },
        {
          name: 'placement',
          type: "'above' | 'below' | 'start' | 'end'",
          description:
            '相对于触发器的位置放置方式。逻辑值:start/end 根据弹出层自身继承的方向解析,RTL 环境通过纯 CSS 自动镜像。',
          default: "'below'",
        },
        {
          name: 'alignment',
          type: "'start' | 'center' | 'end'",
          description:
            '沿放置轴的对齐方式。逻辑值:start/end 跟随弹出层自身继承的方向(RTL 镜像)。',
          default: "'start'",
        },
        {
          name: 'isOpen',
          type: 'boolean',
          description: '在受控模式下弹出框是否显示。',
        },
        {
          name: 'onOpenChange',
          type: '(isOpen: boolean) => void',
          description: '弹出框可见性变化时触发的回调。',
        },
        {
          name: 'isEnabled',
          type: 'boolean',
          description: '设为 false 时,忽略触发器交互。',
          default: 'true',
        },
        {
          name: 'width',
          type: 'number | string',
          description:
            '弹出框容器的宽度。弹出层仍会限制在视口和安全区域留白内,长内容再滚动。',
          default: "'auto'",
        },
        {
          name: 'padding',
          type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
          description:
            '弹出框表面的内边距,使用间距刻度(0、0.5、1、1.5、2、3、4、5、6、8、10),与 Card 和 Stack 的 padding 属性一致。当内容自行管理边缘(如行列表或带分隔线的标题)时传入 0 使表面无内边距,并由内容自行设置内边距。',
          default: '3',
        },
        {
          name: 'label',
          type: 'string',
          description:
            '弹出框对话框的无障碍标签。没有标签的底部面板以触发器的文本命名。',
        },
        {
          name: 'role',
          type: "'dialog' | 'none'",
          description:
            '弹出框包装器的 ARIA 角色。对话框式弹出框使用 dialog;当内容提供自己的角色(如 menu 或 listbox)时使用 none。',
          default: "'dialog'",
        },
        {
          name: 'isModal',
          type: 'boolean',
          description:
            '对话框式弹出框是否设置 aria-modal。仅在 role 为 dialog 时适用。',
          default: 'true',
        },
        {
          name: 'hasCloseButton',
          type: 'boolean',
          description: '是否包含用于无障碍访问的隐藏关闭按钮。',
          default: 'true',
        },
        {
          name: 'closeButtonLabel',
          type: 'string',
          description: '隐藏关闭按钮的标签。',
          default: "'Close popover'",
        },
        {
          name: 'hasAutoFocus',
          type: 'boolean',
          description:
            '弹出框打开时是否将焦点移入其中。优先聚焦调用方内容中的第一个控件;若对话框没有此类控件,则聚焦带标签的表面。生成的关闭按钮仅在键盘导航到达时显示。',
          default: 'true',
        },
        {
          name: 'hasLightDismiss',
          type: 'boolean',
          description:
            '点击外部是否关闭弹出框。需要显式关闭的界面(如新手引导提示)设为 false。',
          default: 'true',
        },
        {
          name: 'hasEscapeDismiss',
          type: 'boolean',
          description:
            '按 Escape 是否关闭弹出框。仅在 hasLightDismiss={false} 时生效,因为原生 light dismiss 行为同样响应 Escape。',
          default: 'true',
        },
        {
          name: 'presentation',
          type: "'popover' | 'bottom-sheet' | 'adaptive'",
          description:
            "承载内容的界面。'popover' 锚定在触发器上,'bottom-sheet' 以模态 BottomSheet 呈现(由 label 命名),'adaptive' 在紧凑触屏(粗指针,且屏幕按主题定义为紧凑:宽度小于其 md 断点或高度小于 500 px,即任意方向的手机)上使用 BottomSheet,在其他设备上使用锚定的弹出框。在底部面板中,placement、alignment、width、role、isModal 和 hasAutoFocus 不生效,xstyle、className 和 style 作用于面板;底部面板始终支持轻触关闭(点按面板外部或向下轻扫即可关闭,不受 hasLightDismiss 影响),Escape 遵循 hasEscapeDismiss,后备关闭按钮保持隐藏。界面在打开时选定,并保持到关闭。",
          default: "'popover'",
        },
      ],
    },
  ],
  theming: {
    targets: [
      // Canonical broad target for the painted Popover surface.
      {className: 'astryx-popover'},
    ],
    vars: [
      {
        name: '--_popover-radius',
        description: 'Border radius of the popover surface',
        default: 'var(--radius-container)',
        private: true,
      },
    ],
    derived: [{property: 'borderRadius', vars: ['--_popover-radius']}],
  },
  usage: {
    description:
      'A click-triggered overlay anchored to a button or trigger element. Use it for secondary actions, inline confirmations, or supplementary information that does not warrant a full dialog. For hover previews use HoverCard, for brief helper text use Tooltip. Under a finger (a coarse primary pointer), it is presented like a native popover: it grows out of its trigger and shrinks back into it on the theme\u2019s motion tokens; with reduced motion it cross-fades, opacity only, in 200 ms or less.',
    bestPractices: [
      {
        guidance: true,
        description:
          'Keep popover content focused on a single task or piece of information.',
      },
      {
        guidance: true,
        description:
          'Provide a clear way to close: either by clicking outside or with an explicit close button.',
      },
      {
        guidance: true,
        description:
          'Theme the painted surface through the canonical popover target.',
      },
      {
        guidance: false,
        description:
          'Nest popovers inside other popovers; it creates confusing focus and navigation.',
      },
      {
        guidance: false,
        description:
          "Assume input complexity alone determines the presentation; evaluate the task's focus, space, and interaction requirements.",
      },
      {
        guidance: false,
        description:
          'Assume scrolling alone means Popover is the wrong component; a bounded Popover may scroll while a focused anchored interaction remains appropriate.',
      },
    ],
    anatomy: [
      {
        name: 'Trigger element',
        required: true,
        description:
          'Caller-supplied or externally referenced control that anchors and toggles the popover.',
      },
      {
        name: 'Popover surface',
        required: true,
        description:
          'Painted surface owned and themed by Popover through the canonical popover target.',
      },
      {
        name: 'Touch sheet',
        required: false,
        description:
          'BottomSheet surface that holds the same content in place of the popover surface for presentation="bottom-sheet", or "adaptive" on a compact touch screen; themed through the bottom-sheet target.',
      },
      {
        name: 'Popover content',
        required: true,
        description: 'Caller-supplied content rendered inside the surface.',
      },
      {
        name: 'Fallback close control',
        required: false,
        description:
          'Keyboard-reachable close affordance appended by usePopover when enabled.',
      },
    ],
  },
};

/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
export const docsDense = {
  description:
    'Click-triggered popover displaying interactive content anchored to trigger element; implements button+dialog ARIA pattern.',
  usage: {
    description:
      'A click-triggered overlay anchored to a button or trigger element. Use it for secondary actions, inline confirmations, or supplementary information that does not warrant a full dialog. For hover previews use HoverCard, for brief helper text use Tooltip. Under a finger (a coarse primary pointer), it is presented like a native popover: it grows out of its trigger and shrinks back into it on the theme\u2019s motion tokens; with reduced motion it cross-fades, opacity only, in 200 ms or less.',
    bestPractices: [
      {
        guidance: true,
        description:
          'Keep popover content focused on a single task or piece of information.',
      },
      {
        guidance: true,
        description:
          'Provide a clear way to close: either by clicking outside or with an explicit close button.',
      },
      {
        guidance: true,
        description:
          'Theme the painted surface through the canonical popover target.',
      },
      {
        guidance: false,
        description:
          'Nest popovers inside other popovers; it creates confusing focus and navigation.',
      },
      {
        guidance: false,
        description:
          "Assume input complexity alone determines the presentation; evaluate the task's focus, space, and interaction requirements.",
      },
      {
        guidance: false,
        description:
          'Assume scrolling alone means Popover is the wrong component; a bounded Popover may scroll while a focused anchored interaction remains appropriate.',
      },
    ],
    anatomy: [
      {
        name: 'Trigger element',
        required: true,
        description:
          'Caller-supplied or externally referenced control that anchors and toggles the popover.',
      },
      {
        name: 'Popover surface',
        required: true,
        description:
          'Painted surface owned and themed by Popover through the canonical popover target.',
      },
      {
        name: 'Touch sheet',
        required: false,
        description:
          'BottomSheet surface that holds the same content in place of the popover surface for presentation="bottom-sheet", or "adaptive" on a compact touch screen; themed through the bottom-sheet target.',
      },
      {
        name: 'Popover content',
        required: true,
        description: 'Caller-supplied content rendered inside the surface.',
      },
      {
        name: 'Fallback close control',
        required: false,
        description:
          'Keyboard-reachable close affordance appended by usePopover when enabled.',
      },
    ],
  },
  components: [
    {
      name: 'Popover',
      displayName: 'Popover',
      description:
        'Click-triggered popover for interactive content anchored to trigger element.',
      propDescriptions: {
        children:
          'Trigger element. Must contain <button> or [role="button"] element.',
        anchorRef: 'External ref for popover anchor in sibling mode.',
        content: 'Content displayed inside popover.',
        placement:
          "Position relative to trigger. Logical: start/end resolve against the popover's inherited direction (RTL mirrors).",
        alignment:
          "Alignment along placement axis. Logical: start/end follow the popover's inherited direction (RTL mirrors).",
        isOpen: 'Whether popover shown in controlled mode.',
        onOpenChange: 'Callback fired when popover visibility changes.',
        isEnabled: 'When false, trigger interactions ignored.',
        width:
          'Popover container width; capped to alignment-aware viewport/safe-area gutters before long content scrolls.',
        label: 'Accessible label for popover dialog.',
        hasCloseButton:
          'Whether to include hidden close button for accessibility.',
        closeButtonLabel: 'Label for hidden close button.',
        hasAutoFocus:
          'Move focus into genuine popover content on open, with a labeled-surface fallback; the generated close control stays hidden until reached by keyboard.',
        hasLightDismiss:
          'Outside click dismisses; false for explicit-dismiss surfaces (coachmarks).',
        hasEscapeDismiss:
          'Escape dismisses; full effect only with hasLightDismiss=false.',
        presentation:
          "Surface: 'popover' (anchored), 'bottom-sheet' (modal BottomSheet), or 'adaptive' (BottomSheet on a coarse pointer on a compact screen, popover elsewhere); chosen on open, kept until close.",
      },
    },
  ],
};