Skip to content

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

TypeScript
8.7 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
 * @file DialogHeroHeader.doc.mjs
 * @input DialogHeroHeader props and Dialog composition
 * @output Consumer documentation for the canary-only hero header
 * @position Lab component documentation consumed by the CLI and docsite
 */

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

export const docs = {
  name: 'DialogHeroHeader',
  displayName: 'Dialog Hero Header',
  import: '@astryxdesign/lab',
  group: 'DialogHeroHeader',
  category: 'Overlay',
  keywords: [
    'dialog',
    'modal',
    'header',
    'hero',
    'media',
    'image',
    'illustration',
    'onboarding',
    'marketing',
    'featured',
    'close button',
    'title',
  ],
  description:
    'Experimental hero-style header for Dialog, available from @astryxdesign/lab@canary: a full-bleed media slot above the title with the close button overlaid on the media. The high-emphasis sibling of DialogHeader for featured, marketing, or onboarding dialogs.',
  props: [
    {
      name: 'title',
      type: 'string | ReactElement',
      description:
        'Dialog title. A string is wrapped in a level 2 Heading (matching DialogHeader); pass a pre-styled Heading element to customize the treatment. Provides the accessible label for the parent Dialog via aria-labelledby unless the Dialog has an explicit label. The visible title is the default initial focus target; another eligible descendant autofocus request takes priority. A custom Heading receives the label and focus on its own element; if it sets its own id, name the Dialog with aria-labelledby.',
      required: true,
    },
    {
      name: 'media',
      type: 'ReactNode',
      description:
        "Full-bleed visual rendered above the title (image, illustration, or icon). Stretches to the dialog's padded edges; the close button overlays its top-trailing corner. Size the media itself (e.g. width 100%) to fill the slot.",
      required: true,
    },
    {
      name: 'mediaMode',
      type: "'light' | 'dark'",
      description:
        "Luminance of the media surface. Composes MediaTheme under the hood so content overlaid on the media (the close button) picks up contrast-safe inverted tokens: 'dark' media gets light overlay content, 'light' media gets dark. Omit to keep ambient theme tokens.",
    },
    {
      name: 'isTitleHidden',
      type: 'boolean',
      description:
        'Visually hides the title row while keeping it available to screen readers, so the dialog stays named by the title.',
      default: 'false',
    },
    {
      name: 'startContent',
      type: 'ReactNode',
      description:
        'Content placed before the title (e.g. an icon), inline with the heading.',
    },
    {
      name: 'maxLines',
      type: 'number',
      description:
        'Max lines before the title truncates with an ellipsis. Only applies when title is a string (auto-wrapped in a Heading).',
    },
    {
      name: 'onOpenChange',
      type: '(isOpen: boolean) => unknown',
      description:
        'Close button callback, called with false when the close button is clicked. If not provided, no close button is rendered. Same contract as DialogHeader.',
    },
    {
      name: 'hasDivider',
      type: 'boolean',
      description:
        "Adds a themed border at the bottom edge. Defaults to the parent Layout's defaultHasDividers context value.",
    },
  ],
  usage: {
    description:
      "Drop into Layout's header slot inside a Dialog, exactly like DialogHeader. Use when the dialog opens onto a featured, marketing, or onboarding moment where the compact DialogHeader is too understated. The media bleeds to the dialog's edges automatically and the close button floats over its top-trailing corner. The visible title is the default initial focus target; inline previews do not move focus. Install @astryxdesign/lab@canary with @astryxdesign/core@canary and import both packages’ CSS. Lab APIs can change between canary versions.",
    bestPractices: [
      {
        guidance: true,
        description:
          'Set mediaMode to match the media\'s luminance so the overlaid close button stays legible: dark imagery needs mediaMode="dark".',
      },
      {
        guidance: true,
        description:
          'Size the media content to fill the slot (width 100% for images); the slot itself only positions and bleeds.',
      },
      {
        guidance: true,
        description:
          'Keep actions (CTAs) in LayoutFooter; the hero header takes no actions slot.',
      },
      {
        guidance: true,
        description:
          'Use isTitleHidden when the media already communicates the message visually; the title still names the dialog for screen readers.',
      },
      {
        guidance: false,
        description:
          'Use for routine confirmations or forms; use the compact DialogHeader instead.',
      },
      {
        guidance: false,
        description:
          'Pass decorative media without an empty alt: use alt="" on purely decorative images so screen readers skip them.',
      },
    ],
  },
  examples: [
    {
      label: 'Onboarding dialog',
      code: `import {DialogHeroHeader} from '@astryxdesign/lab';
import '@astryxdesign/core/astryx.css';
import '@astryxdesign/lab/lab.css';

const [isOpen, setIsOpen] = useState(true);
<Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
  <Layout
    header={
      <DialogHeroHeader
        title="Welcome aboard"
        media={<img src={heroImage} alt="" width="100%" />}
        mediaMode="dark"
        onOpenChange={setIsOpen}
      />
    }
    content={<LayoutContent>Get started in three steps.</LayoutContent>}
    footer={
      <LayoutFooter hasDivider>
        <Button label="Get started" variant="primary" />
      </LayoutFooter>
    }
  />
</Dialog>`,
    },
    {
      label: 'Hidden title (media carries the message)',
      code: `<DialogHeroHeader
  title="Product tour"
  media={<AnnouncementIllustration />}
  isTitleHidden
  onOpenChange={setIsOpen}
/>`,
    },
  ],
};

/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
export const docsZh = {
  usage: {
    description:
      '像 DialogHeader 一样放入 Dialog 内 Layout 的 header 插槽。当对话框呈现精选、营销或引导场景,紧凑的 DialogHeader 不够醒目时使用。媒体自动延伸到对话框边缘,关闭按钮浮动在媒体的尾部上角。可见标题是默认的初始焦点目标;内联预览不会移动焦点。安装 @astryxdesign/lab@canary 和 @astryxdesign/core@canary,并导入两个包的 CSS。Lab API 可能在 canary 版本之间变化。',
    bestPractices: [
      {
        guidance: true,
        description:
          '让 mediaMode 与媒体的明暗匹配,保证浮动关闭按钮清晰可读:深色图片需要 mediaMode="dark"。',
      },
      {
        guidance: true,
        description:
          '让媒体内容填满插槽(图片用 width 100%);插槽本身只负责定位和延伸。',
      },
      {
        guidance: true,
        description:
          '操作按钮(CTA)放在 LayoutFooter;hero 头部不提供操作插槽。',
      },
      {
        guidance: true,
        description:
          '当媒体已经在视觉上传达信息时使用 isTitleHidden;标题仍会为屏幕阅读器命名对话框。',
      },
      {
        guidance: false,
        description: '用于常规确认或表单;请改用紧凑的 DialogHeader。',
      },
      {
        guidance: false,
        description:
          '装饰性媒体缺少空 alt;纯装饰图片请使用 alt="" 让屏幕阅读器跳过。',
      },
    ],
  },
};

/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
export const docsDense = {
  description:
    'canary-only lab hero Dialog header: full-bleed media slot + title, close button overlaid on media (MediaTheme via mediaMode)',
  usage: {
    description:
      'High-emphasis sibling of DialogHeader for featured/marketing/onboarding dialogs. Drops into Layout header slot; media bleeds to dialog edges; title names the dialog; visible title is the default initial focus target. Import from @astryxdesign/lab and load core + lab CSS; install both packages at @canary.',
    bestPractices: [
      {
        guidance: true,
        description:
          'Match mediaMode to the media luminance for close-button contrast.',
      },
      {
        guidance: true,
        description: 'Size media to fill the slot (width 100%).',
      },
      {guidance: true, description: 'Keep CTAs in LayoutFooter.'},
      {
        guidance: true,
        description:
          'Use isTitleHidden when the media carries the message; SR name is kept.',
      },
      {
        guidance: false,
        description: 'Use for routine confirmations/forms; use DialogHeader.',
      },
    ],
  },
};