// @design-system: primitives/LabelWithTooltip
// Registered at /design-system#labelwithtooltip-primitive

'use client';

/**
 * LabelWithTooltip — a label text + focusable info-icon button that reveals
 * a Radix tooltip explaining the field.
 *
 * Usage pattern:
 *   <LabelWithTooltip label={t('limit')} tooltip={t('help_limit')} htmlFor="limit-input" />
 *
 * Hard rules:
 *  - Token-only classes. Zero hardcoded values.
 *  - RTL-first: icon sits at inline-end of label (ms-1).
 *  - Keyboard reachable: Tab → info button, Enter/Space → tooltip already visible on focus.
 *  - Screen readers: info button has aria-label from common.more_info; tooltip role="tooltip".
 *  - Focus ring always visible.
 *  - prefers-reduced-motion: Radix tooltip & animation respect motion-reduce via TooltipContent.
 */

import { useT } from '@/lib/i18n/react';
import { Icon } from '@/components/ui/icons/Icon';
import {
  TooltipProvider,
  Tooltip,
  TooltipTrigger,
  TooltipContent,
} from '@/components/ui/overlays/Tooltip';

export interface LabelWithTooltipProps {
  /** The visible label text. */
  label: string;
  /** Tooltip explanation text. */
  tooltip: string;
  /** The `for` attribute linking this label to a form control. */
  htmlFor?: string;
  /** Shows a required asterisk after the label text. */
  required?: boolean;
  /** Additional class names for the wrapper. */
  className?: string;
}

/**
 * Inline label + info-icon tooltip.
 *
 * Renders as a `<label>` (when `htmlFor` provided) or a `<span>`, followed by
 * a small `<button>` that shows a tooltip on hover/focus.
 *
 * @example
 * ```tsx
 * <LabelWithTooltip
 *   label={t('limit')}
 *   tooltip={t('help_limit')}
 *   htmlFor="limit-input"
 * />
 * ```
 */
export function LabelWithTooltip({
  label,
  tooltip,
  htmlFor,
  required,
  className,
}: LabelWithTooltipProps) {
  const tCommon = useT('common');

  const asterisk = required ? (
    <span aria-hidden="true" className="text-danger-600 ms-0.5">
      {' '}
      *
    </span>
  ) : null;

  const labelEl = htmlFor ? (
    <label htmlFor={htmlFor} className="text-text-primary text-sm leading-none font-medium">
      {label}
      {asterisk}
    </label>
  ) : (
    <span className="text-text-primary text-sm leading-none font-medium">
      {label}
      {asterisk}
    </span>
  );

  return (
    <TooltipProvider delayDuration={200}>
      <span className={`inline-flex items-center gap-1 ${className ?? ''}`}>
        {labelEl}
        <Tooltip>
          <TooltipTrigger asChild>
            <button
              type="button"
              aria-label={tCommon('more_info')}
              className={[
                'inline-flex items-center justify-center rounded-full',
                'hover:text-text-muted text-neutral-400',
                'focus-visible:outline-brand-primary-600 focus-visible:outline-2 focus-visible:outline-offset-1',
                'transition-colors duration-[var(--duration-fast)]',
              ].join(' ')}
            >
              <Icon name="Info" size="xs" aria-hidden />
            </button>
          </TooltipTrigger>
          <TooltipContent side="top" className="max-w-xs text-wrap">
            {tooltip}
          </TooltipContent>
        </Tooltip>
      </span>
    </TooltipProvider>
  );
}