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

'use client';

/**
 * @file CheckboxListItem.tsx
 * @input Uses React, CheckboxInput, ListItem, CheckboxListContext
 * @output Exports CheckboxListItem component, CheckboxListItemProps
 * @position Core implementation; consumed by index.ts, tested by CheckboxList.test.tsx
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/CheckboxList/CheckboxList.doc.mjs
 * - /packages/core/src/CheckboxList/CheckboxList.test.tsx
 * - /packages/core/src/CheckboxList/index.ts
 * - /apps/storybook/stories/CheckboxList.stories.tsx
 * - /packages/cli/assets/templates/blocks/components/CheckboxList/ (showcase blocks)
 */
import { use, useId, useRef, type ReactNode } from 'react';
import * as stylex from "../style-runtime.js";
import type { StyleXStyles } from "../style-runtime.js";
import "../theme/tokens.stylex.js";
import { colorVars } from "../theme/tokens.stylex.js";
import type { BaseProps } from "../BaseProps.js";
import { CheckboxInput } from "../CheckboxInput/CheckboxInput.js";
import type { CheckboxInputProps } from "../CheckboxInput/CheckboxInput.js";
import { ListItem } from "../List/ListItem.js";
import { ListContext } from "../List/ListContext.js";
import { CheckboxListContext } from "./CheckboxListContext.js";
import { useTranslator } from "../i18n/index.js";
import { ItemDescriptionContext } from "../Item/ItemDescriptionContext.js";

// =============================================================================
// Styles
// =============================================================================

const styles = {
  selected: {
    kWkggS: "xgcxg3y",
    $$css: true as const
  }
};

// =============================================================================
// Types
// =============================================================================

export interface CheckboxListItemProps extends BaseProps<HTMLLIElement> {
  /**
   * Primary text label for the item.
   *
   * Accepts a plain string (single-line truncation applied automatically)
   * or a ReactNode for rich content (no truncation constraints —
   * child components control their own text behavior). Links and buttons in
   * the label keep their own behavior; only non-interactive row clicks
   * delegate to the checkbox.
   *
   * A string names the checkbox directly. A ReactNode names it from its
   * visible text through `aria-labelledby`; if that text is absent, pass
   * `aria-label`. When visible text is present, an override must retain every
   * visible word so speech-input users can say what they see.
   */
  label: ReactNode;
  /**
   * Plain-text accessible name for the checkbox, replacing the one derived
   * from `label`.
   *
   * A string `label` names the checkbox directly, and a rich (ReactNode)
   * `label` names it from its visible text through `aria-labelledby`. Pass
   * `aria-label` when that text is absent. When visible text is present, the
   * override must retain every visible word so speech-input users can say what
   * they see. It replaces the derived name and applies to the checkbox control,
   * not the row.
   *
   * @example
   * ```
   * <CheckboxListItem
   *   label={<span>Pro plan <Badge label="Recommended" /></span>}
   *   aria-label="Pro plan Recommended option"
   *   value="pro"
   * />
   * ```
   */
  'aria-label'?: string;
  /**
   * Identity key for collection mode (REQUIRED inside CheckboxList).
   * Throws a runtime error if missing when used inside CheckboxList.
   */
  value?: string;
  /**
   * Secondary content below the label. Accepts a plain string or a ReactNode.
   * Exposed as the checkbox's accessible description through
   * `aria-describedby`, so assistive technology can tell it is the explanation
   * for this choice rather than unrelated row text.
   */
  description?: ReactNode;
  /**
   * Content rendered after the label area.
   */
  endContent?: ReactNode;
  /**
   * Whether this individual item is disabled.
   * @default false
   */
  isDisabled?: boolean;
  /**
   * Whether this item is in a loading state. Renders a spinner inside the
   * checkbox and blocks interaction on this item only.
   *
   * In collection mode, this is also driven automatically: when the parent
   * `CheckboxList` has a `changeAction`, the toggled item shows its
   * spinner while that promise is pending.
   * @default false
   */
  isLoading?: boolean;
  /**
   * Direct checked state (standalone mode only).
   * Ignored when inside CheckboxList.
   */
  isChecked?: boolean | 'indeterminate';
  /**
   * Direct check handler (standalone mode only).
   * Ignored when inside CheckboxList.
   */
  onCheck?: (checked: boolean) => void;
  /** Ref forwarded to the root element */
  ref?: React.Ref<HTMLLIElement>;
}

// =============================================================================
// Component
// =============================================================================

/**
 * The row's visible description is the checkbox's accessible description. Item
 * renders that element and owns its id, and publishes the id through
 * ItemDescriptionContext; this reads it from inside the slot Item renders. The
 * row cannot wrap the description in an id'd element instead — that turns a
 * plain string into a ReactNode and drops the single-line truncation ListItem
 * documents — and a public `descriptionId` prop would fail
 * `spec:AST-002/DEC-1`, since the caller decides nothing Item cannot derive.
 *
 * This component owns `aria-describedby`, so the prop is omitted rather than
 * accepted and overwritten: a caller passing one would otherwise lose the id
 * silently.
 */
function DescribedCheckboxInput(props: Omit<CheckboxInputProps, 'aria-describedby'>) {
  const describedBy = use(ItemDescriptionContext);
  return <CheckboxInput {...props} aria-describedby={describedBy ?? undefined} />;
}

/**
 * A checkbox item for use within CheckboxList (collection mode)
 * or List (standalone mode).
 *
 * In collection mode, checked state is derived from the parent's value array.
 * In standalone mode, uses isChecked/onCheck props directly.
 *
 * Composes ListItem internally — gets density, dividers, hover/press,
 * focus, and container alignment for free.
 *
 * @example
 * ```
 * <CheckboxListItem label="Email" value="email" />
 * <CheckboxListItem
 *   label="Accept terms"
 *   isChecked={accepted}
 *   onCheck={setAccepted}
 * />
 * ```
 */
export function CheckboxListItem({
  label,
  'aria-label': ariaLabel,
  value,
  description,
  endContent,
  isDisabled: isItemDisabled = false,
  isLoading: isItemLoading = false,
  isChecked,
  onCheck,
  ref,
  xstyle,
  className,
  style,
  onClick: onClickProp,
  ...restProps
}: CheckboxListItemProps) {
  const t = useTranslator();
  const ctx = use(CheckboxListContext);
  if (ctx && ctx.value !== undefined && value === undefined) {
    throw new Error('CheckboxListItem requires a `value` prop when used inside CheckboxList with a value array.');
  }

  // Accessible name for the checkbox. A string `label` (or an explicit
  // `aria-label`) becomes the text of CheckboxInput's visually hidden
  // `<label>`, which only accepts a string. A rich label instead names the
  // checkbox from the visible label element through `aria-labelledby`, as
  // RadioListItem does; the hidden label then carries only the generic word,
  // which `aria-labelledby` outranks. Strings are left unwrapped on purpose:
  // Item single-line-truncates a raw string label but not a node.
  const isRichLabel = typeof label !== 'string';
  const labelID = useId();
  const namesFromVisibleLabel = isRichLabel && ariaLabel == null;
  const checkboxLabel = ariaLabel ?? (isRichLabel ? t('@astryx.checkboxList.item.checkbox') : label);

  // Density from list context for checkbox sizing
  const listCtx = use(ListContext);
  const density = listCtx?.density ?? 'balanced';
  const checkboxSize = density === 'compact' ? 'sm' : 'md';

  // Disabled: parent-level OR item-level
  const effectiveDisabled = (ctx?.isDisabled ?? false) || isItemDisabled;
  const effectiveReadOnly = ctx?.isReadOnly ?? false;
  // Loading is per-item: explicit item prop OR (collection mode) the item
  // whose `changeAction` is currently pending in the parent.
  const isBusy = isItemLoading || (ctx?.loadingValue != null && value !== undefined ? ctx.loadingValue === value : false);

  // Resolve checked state:
  // 1. Collection mode (inside CheckboxList with value[])
  // 2. Standalone mode (isChecked prop)
  // 3. Neither → unchecked
  let resolvedChecked: boolean | 'indeterminate' = false;
  if (ctx && ctx.value !== undefined && value !== undefined) {
    resolvedChecked = ctx.value.includes(value);
  } else if (isChecked !== undefined) {
    resolvedChecked = isChecked;
  }

  // Whether this item is interactive (has a toggle handler)
  const isInteractive = !effectiveReadOnly && (ctx != null || onCheck != null);

  // The checkbox is the row's single keyboard control and action. The row is
  // an enlarged click/tap target that delegates surface clicks to it via
  // ListItem's `interactiveRef` (useClickableContainer), so each option is
  // exactly one tab stop. Delegate whenever the row should respond to clicks:
  // a toggleable item, or one carrying a consumer `onClick`.
  const checkboxRef = useRef<HTMLInputElement | null>(null);
  const hasRowInteraction = isInteractive || onClickProp != null;
  const handleToggle = () => {
    if (effectiveDisabled || effectiveReadOnly || isBusy) {
      return;
    }
    if (ctx && ctx.value !== undefined && value !== undefined) {
      // Collection mode — pass the toggled value up so the list can show a
      // spinner on this item while a changeAction is pending.
      const currentlyChecked = ctx.value.includes(value);
      if (currentlyChecked) {
        ctx.onChange?.(ctx.value.filter(v => v !== value), value);
      } else {
        ctx.onChange?.([...ctx.value, value], value);
      }
    } else {
      // Standalone mode
      const shouldCheck = resolvedChecked === true ? false : true;
      onCheck?.(shouldCheck);
    }
  };
  return <ListItem {...restProps} ref={ref} label={namesFromVisibleLabel ? <span id={labelID}>{label}</span> : label} description={description} endContent={endContent} isDisabled={effectiveDisabled}
  // Delegate row clicks to the checkbox instead of wiring onClick (which
  // would add an invisible row button = a second tab stop). The checkbox
  // stays the option's sole focusable control (WCAG 4.1.2 / APG checkbox
  // pattern). A consumer onClick rides on the checkbox itself (below), so
  // it still fires for both direct and delegated (row-surface) clicks.
  interactiveRef={hasRowInteraction ? checkboxRef : undefined} aria-busy={isBusy || undefined} xstyle={[resolvedChecked === true && !effectiveDisabled && !effectiveReadOnly && styles.selected, xstyle] as StyleXStyles} className={className} style={style} startContent={<DescribedCheckboxInput ref={checkboxRef} label={checkboxLabel} aria-labelledby={namesFromVisibleLabel ? labelID : undefined} isLabelHidden value={resolvedChecked} onChange={() => handleToggle()} onClick={onClickProp} isDisabled={effectiveDisabled} isReadOnly={effectiveReadOnly} isLoading={isBusy} size={checkboxSize} />} />;
}
CheckboxListItem.displayName = 'CheckboxListItem';