Skip to content

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

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

'use client';

/**
 * @file InputGroup.tsx
 * @input Uses React, StyleX, theme tokens, InputGroupContext, Field
 * @output Exports InputGroup component with group label/description ARIA wiring
 * @position Groups input with prefix/suffix addons; consumed by index.ts
 *
 * Compatible input children consume InputGroup context to remove competing
 * border/radius geometry. Button addons consume it to join the same outer shape.
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/InputGroup/InputGroup.doc.mjs
 * - /packages/core/src/InputGroup/InputGroup.test.tsx
 * - /packages/core/src/InputGroup/index.ts
 * - /apps/storybook/stories/InputGroup.stories.tsx
 * - /packages/cli/assets/templates/blocks/components/InputGroup/
 */

import {use, useId, useMemo, type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import {sizeVars} from '../theme/tokens.stylex';
import {Field, type InputStatus} from '../Field';
import {SizeProvider, useSize} from '../SizeContext/SizeContext';
import {mergeProps} from '../utils';
import type {BaseProps} from '../BaseProps';
import {InputGroupContext} from './InputGroupContext';
import {InputGroupInternalContext} from './InputGroupInternalContext';
import {themeProps} from '../utils/themeProps';

export type InputGroupSize = 'sm' | 'md' | 'lg';

const styles = stylex.create({
  group: {
    display: 'inline-flex',
    alignItems: 'stretch',
    backgroundColor: 'transparent',
  },
  disabled: {
    cursor: 'default',
    opacity: 0.5,
  },
});

const sizeStyles = stylex.create({
  sm: {
    height: sizeVars['--size-element-sm'],
  },
  md: {
    height: sizeVars['--size-element-md'],
  },
  lg: {
    height: sizeVars['--size-element-lg'],
  },
});

export interface InputGroupProps extends Omit<
  BaseProps<HTMLDivElement>,
  'children'
> {
  /** Ref forwarded to the group container element */
  ref?: React.Ref<HTMLDivElement>;

  /**
   * Input and addon children.
   */
  children: ReactNode;

  /**
   * Label text for the group (required for accessibility).
   */
  label: string;

  /**
   * Whether to visually hide the label.
   * @default false
   */
  isLabelHidden?: boolean;

  /**
   * Description text displayed between the label and input group.
   */
  description?: string;

  /**
   * Whether the group is disabled.
   * @default false
   */
  isDisabled?: boolean;

  /**
   * Whether the field is optional.
   * @default false
   */
  isOptional?: boolean;

  /**
   * Whether the field is required.
   * @default false
   */
  isRequired?: boolean;

  /**
   * Default size for inputs in the group.
   * @default 'md'
   */
  size?: InputGroupSize;

  /**
   * Validation status. Its message shows below the group. The group border
   * does not change; a theme can style the row from `data-status`.
   */
  status?: InputStatus;

  /**
   * Tooltip text at the end of the label.
   */
  labelTooltip?: string;

  /**
   * Test ID for testing frameworks.
   */
  'data-testid'?: string;
}

/**
 * Groups an input with prefix and suffix addons in one connected row. A
 * focused member stays above its neighbours, so its focus ring shows in full.
 *
 * @example
 * ```
 * <InputGroup label="Price">
 *   <InputGroupText>$</InputGroupText>
 *   <TextInput label="Price" isLabelHidden value={price} onChange={setPrice} />
 * </InputGroup>
 * ```
 */
export function InputGroup({
  children,
  label,
  isLabelHidden = false,
  description,
  isDisabled: isDisabledProp = false,
  isOptional = false,
  isRequired = false,
  size: sizeProp,
  status,
  labelTooltip,
  xstyle,
  className,
  style,
  ref,
  'data-testid': testId,
  ...rest
}: InputGroupProps) {
  const parentGroup = use(InputGroupInternalContext);
  const isDisabled = isDisabledProp || parentGroup.isDisabled;
  const size = useSize(sizeProp, 'md');
  const inputId = useId();
  const labelID = useId();
  const descriptionID = useId();
  const statusMessageId = useId();

  const describedByIDs =
    [
      description ? descriptionID : null,
      status?.message ? statusMessageId : null,
    ]
      .filter(Boolean)
      .join(' ') || undefined;

  const contextValue = useMemo(
    () => ({isInGroup: true as const, labelID, describedByIDs}),
    [labelID, describedByIDs],
  );
  const internalContextValue = useMemo(() => ({isDisabled}), [isDisabled]);

  return (
    <InputGroupInternalContext value={internalContextValue}>
      <InputGroupContext value={contextValue}>
        <SizeProvider value={size}>
          <Field
            label={label}
            isLabelHidden={isLabelHidden}
            description={description}
            inputID={inputId}
            labelID={labelID}
            descriptionID={description ? descriptionID : undefined}
            isGroupLabel
            isOptional={isOptional}
            isRequired={isRequired}
            isDisabled={isDisabled}
            status={
              status
                ? {
                    type: status.type,
                    message: status.message,
                    messageID: status.message ? statusMessageId : undefined,
                  }
                : undefined
            }
            statusVariant="detached"
            labelTooltip={labelTooltip}>
            <div
              ref={ref}
              data-testid={testId}
              {...rest}
              role="group"
              aria-disabled={isDisabled || undefined}
              aria-labelledby={labelID}
              aria-describedby={describedByIDs}
              {...mergeProps(
                themeProps('input-group', {
                  size,
                  status: status?.type ?? null,
                }),
                stylex.props(
                  styles.group,
                  sizeStyles[size],
                  isDisabled && styles.disabled,
                  xstyle,
                ),
                className,
                style,
              )}>
              {children}
            </div>
          </Field>
        </SizeProvider>
      </InputGroupContext>
    </InputGroupInternalContext>
  );
}

InputGroup.displayName = 'InputGroup';