// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file Field.tsx
 * @input Uses React, HTMLAttributes, ReactNode, FieldLabel, IconType
 * @output Exports Field component, FieldProps
 * @position Core implementation; consumed by index.ts, tested by Field.test.tsx
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/Field/Field.doc.mjs (props table, features, implementation notes)
 * - /packages/core/src/Field/Field.test.tsx (tests for new/changed behavior)
 * - /packages/core/src/Field/index.ts (exports if types change)
 * - /apps/storybook/stories/Field.stories.tsx (storybook stories)
 * - /packages/cli/assets/templates/blocks/components/Field/ (showcase blocks)
 */
import { type ReactNode, use } from 'react';
import * as stylex from "../style-runtime.js";
import type { BaseProps } from "../BaseProps.js";
import type { SizeValue } from "../utils/types.js";
import { FieldLabel } from "./FieldLabel.js";
import { FieldStatus } from "../FieldStatus/FieldStatus.js";
import type { FieldStatusVariant } from "../FieldStatus/FieldStatus.js";
import "../theme/tokens.stylex.js";
import { spacingVars, borderVars, sizeVars } from "../theme/tokens.stylex.js";
import type { IconType } from "../Icon/index.js";
import { mergeProps } from "../utils/index.js";
import { useDevWarning } from "../hooks/useDevWarning.js";
import { FormLayoutContext } from "../FormLayout/FormLayoutContext.js";
import { Text } from "../Text/index.js";
import { themeProps } from "../utils/themeProps.js";
const styles = {
  container: {
    k1xSpc: "x78zum5",
    kXwgrk: "xdt5ytf",
    kHBbk8: "xc8icb0",
    $$css: true as const
  },
  containerGap: {
    kOIVth: "xzye2dw",
    $$css: true as const
  },
  horizontalLabels: {
    k1xSpc: "xjp7ctv",
    $$css: true as const
  },
  attachedStatusLayer: {
    kVAEAm: "x1n2onr6",
    kY2c9j: "x8knxv4",
    $$css: true as const
  }
};

// Dynamic style for the consumer-controlled field width. Numbers are treated
// as pixels by StyleX; strings (e.g. '100%') are used as-is.
const dynamicStyles = {
  width: (width: SizeValue | null) => [{
    kzqmXN: width != null ? "x5lhr3w" : width,
    $$css: true as const
  }, {
    "--x-width": (val => typeof val === "number" ? val + "px" : val != null ? val : undefined)(width)
  }]
};
export type { SizeValue } from "../utils/types.js";
export type FieldStatusType = 'warning' | 'error' | 'success';
export interface FieldStatusInput {
  /**
   * The type of status to display.
   */
  type: FieldStatusType;
  /**
   * Optional message to display below the input.
   */
  message?: string;
  /**
   * ID for the status message element (use for aria-describedby on the input).
   */
  messageID?: string;
}
export interface FieldProps extends Omit<BaseProps<HTMLDivElement>, 'children'> {
  /** Ref forwarded to the root element */
  ref?: React.Ref<HTMLDivElement>;
  /**
   * Label text for the field (always rendered for accessibility).
   */
  label: string;
  /**
   * Whether to visually hide the label and description (still accessible to screen readers).
   * @default false
   */
  isLabelHidden?: boolean;
  /**
   * Description text displayed between the label and input.
   * Hidden when isLabelHidden is true.
   */
  description?: string;
  /**
   * ID of the input element this label points AT (used as the label's
   * `htmlFor`). This is the id of the *control*, not of the label element —
   * see `labelID` for the latter.
   */
  inputID: string;
  /**
   * The `id` applied TO the label element itself (distinct from `inputID`,
   * which is the control the label points at). A grouping control
   * (radiogroup, checkbox group) references this via `aria-labelledby` to take
   * the label as its accessible name. Pair with `isGroupLabel`.
   */
  labelID?: string;
  /**
   * When the field wraps a group of controls rather than a single input, set
   * this so the label renders as a non-`<label>` element (a `<span>`): a
   * `<label>` semantically names one control and can't be associated with a
   * group. Pair with `labelID` + `aria-labelledby` on the group.
   * @default false
   */
  isGroupLabel?: boolean;
  /**
   * ID for the description element (use for aria-describedby on the input).
   */
  descriptionID?: string;
  /**
   * Whether the field is optional. Mutually exclusive with isRequired.
   * @default false
   */
  isOptional?: boolean;
  /**
   * Whether the field is required. Mutually exclusive with isOptional.
   * @default false
   */
  isRequired?: boolean;
  /**
   * Whether the associated input is disabled.
   * @default false
   */
  isDisabled?: boolean;
  /**
   * Icon to display before the label text.
   */
  labelIcon?: ReactNode | IconType;
  /**
   * Status indicator for the field.
   * When set with a message, displays a colored message box below the input.
   */
  status?: FieldStatusInput;
  /**
   * Tooltip text to display in an info icon at the end of the label.
   */
  labelTooltip?: string;
  /**
   * How the status message is rendered relative to the input.
   * - 'attached': Status sits directly below the input (default, for bordered inputs)
   * - 'detached': Status is a separate element below the field (for checkboxes, switches, sliders)
   * - 'tooltip': No message box; the input surfaces status through a tooltip on its on-field icon
   * @default 'attached'
   */
  statusVariant?: FieldStatusVariant;
  /**
   * Width of the field. Numbers are treated as pixels, strings are used as-is
   * (e.g. `'100%'`). Sizes the whole field — label, control, and status — so
   * the control and its surrounding chrome stay aligned. Prefer this over
   * setting `width` via `xstyle`/`className`/`style`, which only size the inner
   * control box and leave the label and status at their natural width.
   */
  width?: SizeValue;
  /**
   * The input or control to render inside the field.
   */
  children: ReactNode;
}

/**
 * A form field wrapper that provides label and description.
 *
 * @example
 * ```
 * const id = useId();
 * const descID = useId();
 * <Field label="Email" description="We'll never share your email" inputID={id} descriptionID={descID}>
 *   <input id={id} aria-describedby={descID} />
 * </Field>
 * ```
 */
export function Field({
  label,
  isLabelHidden = false,
  description,
  inputID,
  labelID,
  isGroupLabel = false,
  descriptionID,
  isOptional = false,
  isRequired = false,
  isDisabled = false,
  labelIcon,
  status,
  labelTooltip,
  statusVariant = 'attached',
  width,
  xstyle,
  children,
  className,
  style,
  ref,
  ...props
}: FieldProps) {
  const {
    direction
  } = use(FormLayoutContext);
  const isHorizontalLabels = direction === 'horizontal-labels';
  const resolvedDescriptionID = descriptionID ?? (description ? `${inputID}-desc` : undefined);
  const resolvedMessageID = status?.messageID ?? (status?.message ? `${inputID}-status` : undefined);
  useDevWarning('Field', 'isOptional and isRequired are mutually exclusive. isOptional takes precedence.', isOptional && isRequired);
  const labelNode = <FieldLabel label={label} inputID={inputID} labelID={labelID} isGroupLabel={isGroupLabel} isLabelHidden={isLabelHidden} isDisabled={isDisabled} isOptional={isOptional} isRequired={isRequired} labelIcon={labelIcon} labelTooltip={labelTooltip} description={isHorizontalLabels ? undefined : description} descriptionID={isHorizontalLabels ? undefined : resolvedDescriptionID} />;

  // The 'tooltip' variant surfaces status through the input's on-field icon
  // tooltip, so Field renders no message box for it.
  const statusNode = status?.message && statusVariant !== 'tooltip' ? <FieldStatus type={status.type} message={status.message} id={resolvedMessageID} variant={statusVariant} xstyle={statusVariant === 'attached' ? styles.attachedStatusLayer : undefined} /> : null;

  // ─── Horizontal-labels mode ───────────────────────────────────────────
  // Use display:contents so the parent grid's `auto 1fr` columns place
  // the label in column 1 and the input group in column 2. Description
  // and status are grouped with the input in column 2.
  // The label wrapper gets top padding to align label text with input text.
  if (isHorizontalLabels) {
    return <div ref={ref} {...mergeProps(themeProps('field', {
      layout: 'horizontal-labels'
    }), stylex.props(styles.horizontalLabels, xstyle), className, style)} {...props}>
        <div className="x1enrzb7">{labelNode}</div>
        <div className="x78zum5 xdt5ytf xc8icb0 x19nvjgn xlumz0n x1qs65gq">
          {description && <Text type="supporting" display="block" id={resolvedDescriptionID}>
              {description}
            </Text>}
          {children}
          {statusNode}
        </div>
      </div>;
  }

  // ─── Default mode (vertical / horizontal) ─────────────────────────────
  return <div ref={ref} {...mergeProps(themeProps('field'), stylex.props(styles.container, !isLabelHidden && styles.containerGap, width != null && dynamicStyles.width(width), xstyle), className, style)} {...props}>
      {labelNode}
      {statusVariant === 'attached' ? <div className="x78zum5 xdt5ytf xc8icb0 x19nvjgn xlumz0n x1qs65gq">
          {children}
          {statusNode}
        </div> : <>
          {children}
          {statusNode}
        </>}
    </div>;
}
Field.displayName = 'Field';