Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

3.1 KB
Raw Blame
import { useId, Children, cloneElement, isValidElement } from 'react';

/**
 * Accessible config-form field wrapper.
 *
 * Generates a stable id via `useId()` and wires the `<label htmlFor>` to the
 * first child input/select/textarea's `id`, so clicking the label focuses the
 * field and screen readers announce the association (the repo's
 * "form labels need htmlFor/id pairing" convention).
 *
 * Styling is caller-owned so migrating an existing field is a lossless swap:
 * pass `className` for the wrapper and `labelClassName` to match the field's
 * current label classes. If the first child already has an `id`, that id wins
 * and the label points at it; otherwise the generated id is injected — either
 * way the label/control association holds.
 *
 * @param {string} label - Visible label text.
 * @param {import('react').ReactNode} [hint] - Optional hint rendered between label and field.
 * @param {import('react').ReactNode} children - The field control(s); the first element is bound to the label.
 * @param {string} [className] - Wrapper div className.
 * @param {string} [labelClassName] - Label className (defaults to the common config-form label style).
 */
export function FormField({
  label,
  hint,
 children,
 className = '',
  labelClassName = 'block text-sm text-gray-400 mb-1',
  compact = false,
}) {
  const generatedId = useId();
  // A hint only earns an id when it will actually render; otherwise
  // aria-describedby would point at an element that is never in the DOM.
  const hasHint = hint != null && hint !== '' && hint !== false;
  const hintId = hasHint ? `${generatedId}-hint` : null;

  // The label must point at whatever id the first control actually has: reuse
  // the child's own id when present, otherwise inject the generated one.
  //
  // Keep the `cloneElement(child, { id: controlId, ... })` literal intact: the
  // tree-wide scanner in a11yConventions.test.js proves this wrapper names its
  // child by matching that exact shape, and a props object built in a variable
  // is invisible to it (#7525).
  let controlId = generatedId;
  const augmented = Children.map(children, (child, i) => {
    if (i !== 0 || !isValidElement(child)) return child;
    // Preserve any description the caller already declared and append ours.
    const existingDescribedBy = child.props['aria-describedby'];
    const describedBy = hintId
      ? [existingDescribedBy?.trim(), hintId].filter(Boolean).join(' ')
      : existingDescribedBy;
    if (child.props.id) {
      controlId = child.props.id;
      if (describedBy === existingDescribedBy) return child;
      return cloneElement(child, { 'aria-describedby': describedBy });
    }
    return cloneElement(child, { id: controlId, 'aria-describedby': describedBy });
  });

  return (
    <div className={className}>
      {label != null && <label htmlFor={controlId} className={compact ? 'block text-xs uppercase tracking-wider text-gray-500 mb-1' : labelClassName}>{label}</label>}
      {hasHint && <p id={hintId} className={compact ? 'block text-[11px] text-gray-500 mt-1' : 'text-xs text-gray-500 mb-1'}>{hint}</p>}
      {augmented}
    </div>
  );
}

export default FormField;