Skip to content

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

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

/**
 * @file FieldStatus.tsx
 * @input Uses React, stylex, theme tokens, useFieldStatusAnnouncement, Icon
 * @output Exports FieldStatus component, FieldStatusProps
 * @position Core implementation; consumed by Field, Switch, CheckboxInput, and the FieldStatus entrypoint
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/FieldStatus/FieldStatus.doc.mjs (props table, features, implementation notes)
 * - /packages/core/src/Field/Field.doc.mjs (compat docs when public API changes)
 * - /packages/core/src/FieldStatus/index.ts (exports if types change)
 * - /packages/core/src/FieldStatus/useFieldStatusAnnouncement.ts (announcement timing shared with Field)
 * - /packages/core/src/Field/index.ts (compat re-export if public API changes)
 * - /packages/cli/assets/templates/blocks/components/FieldStatus/ (showcase blocks)
 */

'use client';

import React from 'react';
import * as stylex from '@stylexjs/stylex';
import type {BaseProps} from '../BaseProps';
import {mergeProps} from '../utils/mergeProps';
import {
  colorVars,
  radiusVars,
  spacingVars,
  typographyVars,
  typeScaleVars,
} from '../theme/tokens.stylex';
import type {InputStatusType} from '../Field/types';
import {useEntryAnimation} from '../hooks/useEntryAnimation';
import {themeProps} from '../utils/themeProps';
import {Icon} from '../Icon/Icon';
import type {IconName} from '../Icon';
import type {FieldStatusVariantMap} from './index';
import {useFieldStatusAnnouncement} from './useFieldStatusAnnouncement';

/**
 * Maps each status type to its status glyph. Mirrors the mapping the input
 * controls already use for the on-field status affordance, so the detached
 * message shows the same icon a consumer sees elsewhere for that status.
 */
const statusIconMap: Record<InputStatusType, IconName> = {
  warning: 'warning',
  error: 'error',
  success: 'success',
};

const ATTACHED_OVERLAP = `var(--_field-status-overlap, ${spacingVars['--spacing-1-5']})`;

const styles = stylex.create({
  base: {
    // Forced colors replace status fills with Canvas; this boundary keeps the
    // fill's shape visible (architecture:theme-tokens INV11).
    outlineWidth: {default: null, '@media (forced-colors: active)': '1px'},
    outlineStyle: {default: null, '@media (forced-colors: active)': 'solid'},
    outlineColor: {
      default: null,
      '@media (forced-colors: active)': 'CanvasText',
    },
    outlineOffset: {default: null, '@media (forced-colors: active)': '-1px'},
    fontFamily: typographyVars['--font-family-body'],
    fontSize: typeScaleVars['--text-supporting-size'],
    lineHeight: typeScaleVars['--text-supporting-leading'],
    // A validation message often echoes the value that failed (an address, a
    // URL). Let such an unbroken token wrap inside the field instead of
    // painting past its edges (WCAG 2.2 SC 1.4.10 Reflow).
    overflowWrap: 'anywhere',
    // Text inside keeps `anywhere` too (Text FR3).
    '--_astryx-text-overflow-wrap': 'anywhere',
  },
  attached: {
    marginTop: `calc(-1 * ${ATTACHED_OVERLAP})`,
    paddingBlockStart: `calc(${ATTACHED_OVERLAP} + ${spacingVars['--spacing-2']})`,
    paddingBlockEnd: spacingVars['--spacing-2'],
    paddingInline: spacingVars['--spacing-2'],
    borderEndStartRadius: radiusVars['--radius-element'],
    borderEndEndRadius: radiusVars['--radius-element'],
    // The overlap is visual only. Let pointer input reach the control beneath
    // it instead of allowing the later-painted status box to steal the click.
    pointerEvents: 'none',
  },
  detached: {
    marginTop: spacingVars['--spacing-1'],
    paddingBlock: spacingVars['--spacing-2'],
    paddingInline: spacingVars['--spacing-2'],
    borderRadius: radiusVars['--radius-element'],
  },
  detachedContent: {
    display: 'flex',
    alignItems: 'flex-start',
    gap: spacingVars['--spacing-1'],
  },
  detachedIcon: {
    // Center the glyph within the first text-line box so it aligns to the
    // first line of the message (rather than the top of the flex row) when the
    // message wraps to multiple lines.
    display: 'inline-flex',
    alignItems: 'center',
    height: `calc(${typeScaleVars['--text-supporting-size']} * ${typeScaleVars['--text-supporting-leading']})`,
    flexShrink: 0,
  },
});

const colorStyles = stylex.create({
  warning: {
    backgroundColor: colorVars['--color-warning-muted'],
    color: colorVars['--color-on-warning-muted'],
  },
  error: {
    backgroundColor: colorVars['--color-error-muted'],
    color: colorVars['--color-on-error-muted'],
  },
  success: {
    backgroundColor: colorVars['--color-success-muted'],
    color: colorVars['--color-on-success-muted'],
  },
});

/**
 * FieldStatus variant type. Extensible via module augmentation of FieldStatusVariantMap.
 */
export type FieldStatusVariant = keyof FieldStatusVariantMap;

export interface FieldStatusProps extends BaseProps<HTMLDivElement> {
  /**
   * Ref to the rendered message box.
   */
  ref?: React.Ref<HTMLDivElement>;
  /**
   * The type of status to display.
   */
  type: InputStatusType;
  /**
   * The status message to display.
   */
  message: string;
  /**
   * Visual variant of the status message.
   * - 'attached': Overlaps with input above (used in Field)
   * - 'detached': Floats below with spacing (used in Switch, CheckboxInput)
   * @default 'attached'
   */
  variant?: FieldStatusVariant;
}

// A direct `tooltip` resolves to the deprecated signature first; every other
// call, a `FieldStatusVariant`-typed value included, resolves to the second,
// which `ComponentProps<typeof FieldStatus>` reads.
/**
 * @deprecated FieldStatus has no `tooltip` presentation
 * (`component:FieldStatus` FR7): it draws a plain message box with no tooltip.
 * Set `statusVariant="tooltip"` on the field control instead, which shows the
 * message from its on-field status icon. Removed in the next minor release.
 */
export function FieldStatus(
  props: FieldStatusProps & {variant: 'tooltip'},
): React.JSX.Element;
/**
 * A status message component for form fields: an `attached` message under a
 * field, or a `detached` one with its own status icon.
 *
 * @example
 * ```
 * <FieldStatus type="error" message="This field is required" />
 * ```
 */
export function FieldStatus(props: FieldStatusProps): React.JSX.Element;
/**
 * A status message component for form fields.
 *
 * The `detached` variant renders a leading status icon before the message so
 * status is not conveyed by color or position alone (WCAG 1.4.1). The icon is
 * decorative for assistive tech (`aria-hidden`): the message text already names
 * the status in words and is announced through the live region. The `attached`
 * variant keeps its status affordance on the bordered input, so it renders no
 * icon here to avoid a duplicate. FieldStatus has no `tooltip` presentation:
 * a field control given `statusVariant="tooltip"` surfaces the status through
 * a tooltip on its on-field icon and renders no FieldStatus for it
 * (`component:FieldStatus` FR7).
 *
 * Screen-reader announcements go through the persistent `useAnnounce` live
 * regions (assertive for errors, polite otherwise) rather than `role`/
 * `aria-live` on the rendered element. Live regions that mount together with
 * their content are not reliably announced by assistive technology, and
 * FieldStatus is almost always conditionally rendered by its callers. The
 * message is announced whenever it appears — including on first mount — and
 * whenever it changes.
 *
 * @example
 * ```
 * <FieldStatus
 *   type="error"
 *   message="This field is required"
 * />
 * <FieldStatus
 *   type="warning"
 *   message="This will be visible to others"
 *   variant="detached"
 * />
 * ```
 */
export function FieldStatus({
  ref,
  type,
  message,
  id,
  variant = 'attached',
  xstyle,
  className,
  style,
  ...rest
}: FieldStatusProps) {
  const entryStyle = useEntryAnimation('slideDown');
  // Announce-on-mount is intentional: callers conditionally mount FieldStatus
  // when a status appears (and whole forms can mount with a server-side
  // validation error already present), and both cases must be heard.
  useFieldStatusAnnouncement(message, type);

  return (
    <div
      ref={ref}
      id={id}
      {...rest}
      {...mergeProps(
        themeProps('field-status', {type, variant}),
        stylex.props(
          styles.base,
          entryStyle,
          variant === 'attached' ? styles.attached : styles.detached,
          colorStyles[type],
          xstyle,
        ),
        className,
        style,
      )}>
      {variant === 'detached' ? (
        <span {...stylex.props(styles.detachedContent)}>
          <span {...stylex.props(styles.detachedIcon)}>
            <Icon
              icon={statusIconMap[type]}
              size="sm"
              color="inherit"
              // Stable theme target on the detached message box's leading glyph
              // itself, so a theme can restyle just this icon (color, size) —
              // and each status — via `defineTheme`. Same-element rules in
              // @layer astryx-theme win over the icon's own base
              // width/height/fontSize, which a field-level target could not
              // reach.
              {...themeProps('field-status-icon', {type})}
            />
          </span>
          <span>{message}</span>
        </span>
      ) : (
        message
      )}
    </div>
  );
}

FieldStatus.displayName = 'FieldStatus';