Skip to content

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

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

'use client';

/**
 * @file DrawerHeader.tsx
 * @input Uses React, StyleX, LayoutHeader, Button, Icon, Heading, Text, i18n, BaseProps, isRenderable, mergeProps, themeProps
 * @output Exports DrawerHeader component and DrawerHeaderProps
 * @position Drawer header; composed in a Layout header slot inside Drawer, tested by DrawerHeader.test.tsx
 *
 * Mirrors DialogHeader's API: a title, an optional subtitle, start/end content
 * slots, and a close button that renders only when `onOpenChange` is passed.
 * Two differences follow from Drawer's contract:
 * - It does not move focus on mount. Drawer owns focus entry through
 *   `data-autofocus` once its native host is presented.
 * - It does not name the drawer. Drawer's required `label` does.
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/Drawer/DrawerHeader.doc.mjs (props, anatomy, theming)
 * - /packages/core/src/Drawer/DrawerHeader.test.tsx (tests for new/changed behavior)
 * - /packages/core/src/Drawer/index.ts (exports if types change)
 * - /packages/cli/assets/templates/blocks/components/Drawer/ (showcase blocks)
 * - /packages/cli/assets/templates/blocks/components/DrawerHeader/ (showcase blocks)
 * - /apps/storybook/stories/Drawer.stories.tsx (examples and visual coverage)
 * - /apps/storybook/stories/DrawerHeader.stories.tsx (component audit fixture)
 */

import type {ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import type {BaseProps} from '../BaseProps';
import {sizeVars, spacingVars, typeScaleVars} from '../theme/tokens.stylex';
import {Button} from '../Button';
import {Heading} from '../Heading';
import {Icon} from '../Icon';
import {LayoutHeader} from '../Layout';
import {Text} from '../Text';
import {isRenderable, mergeProps, themeProps} from '../utils';
import {
  registerEnglishFallback,
  useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/Drawer/DrawerHeader.generated';

registerEnglishFallback(english);

const styles = stylex.create({
  container: {
    display: 'flex',
    alignItems: 'flex-start',
    justifyContent: 'space-between',
    gap: spacingVars['--spacing-3'],
  },
  // Compensate for the medium icon button's visual padding on the end slot.
  endBlockEdgeCompensation: {
    marginBlock: `calc(-1 * ${spacingVars['--spacing-2']})`,
  },
  endInlineEdgeCompensation: {
    marginInlineEnd: `calc(-1 * ${spacingVars['--spacing-2']})`,
  },
  titleWrapper: {
    display: 'flex',
    flexDirection: 'column',
    gap: spacingVars['--spacing-0'],
    flex: 1,
    minWidth: 0,
    // Align the title's center with the close button's center, as
    // DialogHeader does.
    marginBlock: `calc(${sizeVars['--size-element-md']} / 2 - ${spacingVars['--spacing-2']} - ${typeScaleVars['--text-heading-2-size']} * ${typeScaleVars['--text-heading-2-leading']} / 2)`,
  },
  actions: {
    display: 'flex',
    alignItems: 'center',
    gap: spacingVars['--spacing-2'],
    flexShrink: 0,
  },
});

export interface DrawerHeaderProps extends BaseProps<HTMLDivElement> {
  /** Ref forwarded to the root element */
  ref?: React.Ref<HTMLDivElement>;

  /**
   * The title of the drawer, rendered as an h2. Keep it inline and
   * non-interactive. It does not name the drawer; Drawer's `label` does.
   */
  title: ReactNode;

  /**
   * Optional subtitle displayed below the title in smaller, secondary text.
   * Accepts inline content such as a Link; it renders inside a span, so
   * avoid block elements. Nothing renders for `null`, `undefined`, booleans,
   * or an empty string.
   */
  subtitle?: ReactNode;

  /**
   * Called with `false` when the close button is clicked. Pass the Drawer's
   * own `onOpenChange`. If not provided, no close button is rendered.
   */
  onOpenChange?: (isOpen: boolean) => unknown;

  /**
   * Content to render before the title (e.g., a back button).
   */
  startContent?: ReactNode;

  /**
   * Content to render after the title, before the close button (e.g., action
   * buttons).
   */
  endContent?: ReactNode;

  /**
   * Overrides automatic end-slot compensation. When omitted, rendering the
   * close action applies block and logical inline-end compensation. Use
   * `inline`, `block`, or `all` to select the axes explicitly.
   */
  endContentEdgeCompensation?: 'inline' | 'block' | 'all';

  /**
   * Adds a themed border at the bottom edge.
   * When false, spacing collapse is applied automatically for seamless visual flow.
   * Defaults to the parent Layout's `defaultHasDividers` context value.
   */
  hasDivider?: boolean;
}

/**
 * Header for a Drawer: a title, optional subtitle and start/end content, and a
 * close button when `onOpenChange` is passed. Same API as DialogHeader.
 *
 * Uses LayoutHeader internally for consistent styling with other layout headers.
 *
 * @example
 * ```
 * <Drawer isOpen={isOpen} onOpenChange={setIsOpen} label="Details">
 *   <DrawerHeader title="Details" onOpenChange={setIsOpen} />
 *   <Section padding={4}>Content</Section>
 * </Drawer>
 * ```
 */
export function DrawerHeader({
  title,
  subtitle,
  onOpenChange,
  startContent,
  endContent,
  endContentEdgeCompensation,
  hasDivider,
  xstyle,
  className,
  style,
  ref,
  ...rest
}: DrawerHeaderProps) {
  const t = useComponentTranslator();
  const hasSubtitle = isRenderable(subtitle);
  const hasStartContent = isRenderable(startContent);
  const hasEndContent = isRenderable(endContent);
  const shouldCompensateEndBlock =
    endContentEdgeCompensation == null
      ? onOpenChange != null
      : endContentEdgeCompensation === 'block' ||
        endContentEdgeCompensation === 'all';
  const shouldCompensateEndInline =
    endContentEdgeCompensation == null
      ? onOpenChange != null
      : endContentEdgeCompensation === 'inline' ||
        endContentEdgeCompensation === 'all';

  return (
    <LayoutHeader
      ref={ref}
      hasDivider={hasDivider}
      xstyle={xstyle}
      className={className}
      style={style}
      {...rest}>
      <div
        {...mergeProps(
          themeProps('drawer-header'),
          stylex.props(styles.container),
        )}>
        {hasStartContent && (
          <div
            {...mergeProps(
              themeProps('drawer-header-start-content'),
              stylex.props(styles.actions),
            )}>
            {startContent}
          </div>
        )}
        <div
          {...mergeProps(
            themeProps('drawer-header-title-block'),
            stylex.props(styles.titleWrapper),
          )}>
          <Heading level={2}>{title}</Heading>
          {hasSubtitle && (
            <Text type="body" size="sm" color="secondary">
              {subtitle}
            </Text>
          )}
        </div>
        {(hasEndContent || onOpenChange != null) && (
          <div
            {...mergeProps(
              themeProps('drawer-header-end-content'),
              stylex.props(
                styles.actions,
                shouldCompensateEndBlock && styles.endBlockEdgeCompensation,
                shouldCompensateEndInline && styles.endInlineEdgeCompensation,
              ),
            )}>
            {endContent}
            {onOpenChange && (
              <Button
                variant="ghost"
                label={t('@astryx.dialog.close')}
                tooltip={t('@astryx.dialog.close')}
                icon={
                  <Icon
                    icon="close"
                    color="inherit"
                    {...themeProps('drawer-header-close-icon')}
                  />
                }
                onClick={() => {
                  onOpenChange(false);
                }}
                isIconOnly
              />
            )}
          </div>
        )}
      </div>
    </LayoutHeader>
  );
}

DrawerHeader.displayName = 'DrawerHeader';