chati-dev 4.3.0 → 4.4.0

package/framework/scaffold/saas-dashboard/components/interaction/Field.tsx.template

@@ -0,0 +1,351 @@
+/**
+ * components/interaction/Field.tsx
+ * SaaS Dashboard Preset -- D_interaction phase
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * The Field primitive is the accessibility contract boundary for every input
+ * in the dashboard. Two failure modes plague dashboard forms:
+ *
+ *   1. Placeholder-only labels: placeholder disappears on focus, leaving
+ *      users with short-term memory limitations (or filling multiple fields
+ *      rapidly) unable to recall what a field is for. WCAG 1.3.1 requires
+ *      programmatic labels. This component makes it structurally impossible
+ *      to render an input without a <label>.
+ *
+ *   2. Error announced too late: error text that appears only near the
+ *      submit button is not announced to screen reader users focused inside
+ *      the form. The `role="alert"` on the error message here fires
+ *      immediately when error text appears, regardless of focus position.
+ *
+ * ARCHITECTURE DECISIONS
+ * ----------------------
+ * 1. Field is the composition root; it renders the <label>, hint, and error.
+ *    The <Input> sub-component handles only the input element itself.
+ *    This separation means the Field wrapper can be reused with <textarea>
+ *    or <select> by passing `as="textarea"` / `as="select"`, without
+ *    duplicating label/hint/error logic.
+ *
+ * 2. `labelHidden` prop renders the label text inside a `.sr-only` span
+ *    so visually minimal forms (e.g., inline search) still have SR labels.
+ *    The label element is NEVER removed from the DOM.
+ *
+ * 3. Icon slots use absolute positioning within a `position:relative` wrapper.
+ *    The input's padding-left / padding-right adjusts via inline style when
+ *    icons are present. This avoids flexbox-inside-input hacks and keeps
+ *    the input text baseline aligned regardless of icon presence.
+ *
+ * 4. The `required` prop adds an asterisk in the label AND sets
+ *    `aria-required="true"` on the input. Both are needed: the asterisk
+ *    is a visual convention; aria-required communicates to SR users who
+ *    may not see the asterisk.
+ *
+ * 5. Focus ring: implemented globally via `:focus-visible` in globals.css.
+ *    The input itself does NOT set outline -- it relies on the global rule,
+ *    which applies the --shadow-focus token that includes a 2px ring with
+ *    2px offset.
+ *
+ * STATE TRANSITIONS
+ * -----------------
+ * resting  -> border: var(--color-border-default)
+ * focus    -> border: var(--color-border-emphasis); transition duration-normal
+ * error    -> border: var(--color-danger); bg: var(--color-danger-subtle) tint
+ * disabled -> opacity 0.5; cursor: not-allowed
+ *
+ * TOKEN USAGE
+ * -----------
+ * All properties reference CSS custom properties from globals.css.
+ * No raw hex values, no raw pixel literals.
+ */
+
+'use client';
+
+import React, {
+  forwardRef,
+  useId,
+  type InputHTMLAttributes,
+  type TextareaHTMLAttributes,
+  type SelectHTMLAttributes,
+  type ReactNode,
+} from 'react';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type InputAs = 'input' | 'textarea' | 'select';
+
+export interface FieldProps {
+  /** Always rendered as a real <label>. Never omitted. */
+  label: string;
+  /** Hint text below the input; linked via aria-describedby. */
+  hint?: string;
+  /** Error message. Overrides hint. Sets aria-invalid and role=alert. */
+  error?: string;
+  /** Visually hides the label but keeps it in the DOM for screen readers. */
+  labelHidden?: boolean;
+  /** Lucide icon rendered inside the input on the left. */
+  iconLeft?: ReactNode;
+  /** Lucide icon or button rendered inside the input on the right. */
+  iconRight?: ReactNode;
+  /** Adds asterisk and aria-required. */
+  required?: boolean;
+  /** Element to render. Default: 'input'. */
+  as?: InputAs;
+  /** Passed to underlying input element. */
+  inputProps?: InputHTMLAttributes<HTMLInputElement>;
+  /** Passed when as='textarea'. */
+  textareaProps?: TextareaHTMLAttributes<HTMLTextAreaElement>;
+  /** Passed when as='select'. */
+  selectProps?: SelectHTMLAttributes<HTMLSelectElement>;
+  /** Children for select options when as='select'. */
+  children?: ReactNode;
+  /** Additional class on the field wrapper. */
+  className?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Shared input styles (CSS-in-JS-style object used across all variants)
+// ---------------------------------------------------------------------------
+
+function buildInputStyle({
+  hasError,
+  isDisabled,
+  iconLeftPresent,
+  iconRightPresent,
+}: {
+  hasError: boolean;
+  isDisabled: boolean;
+  iconLeftPresent: boolean;
+  iconRightPresent: boolean;
+}): React.CSSProperties {
+  return {
+    display: 'block',
+    width: '100%',
+    minHeight: '40px',
+    paddingTop: 'var(--spacing-input-pad-v)',
+    paddingBottom: 'var(--spacing-input-pad-v)',
+    paddingLeft: iconLeftPresent ? '36px' : 'var(--spacing-input-pad-h)',
+    paddingRight: iconRightPresent ? '36px' : 'var(--spacing-input-pad-h)',
+    backgroundColor: 'var(--color-bg-sunken)',
+    color: hasError ? 'var(--color-text-primary)' : 'var(--color-text-primary)',
+    fontSize: 'var(--type-body)',
+    lineHeight: 'var(--type-body-lh)',
+    fontFamily: 'var(--font-sans)',
+    borderRadius: 'var(--radius-default)',
+    border: hasError
+      ? '1px solid var(--color-danger)'
+      : '1px solid var(--color-border-default)',
+    outline: 'none',
+    opacity: isDisabled ? 0.5 : 1,
+    cursor: isDisabled ? 'not-allowed' : 'text',
+    transition: `border-color var(--duration-normal) var(--ease-in-out)`,
+    // Focus border via CSS :focus-visible in globals.css (:focus-visible + border-color)
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Icon slot helper
+// ---------------------------------------------------------------------------
+
+function IconSlot({
+  side,
+  children,
+}: {
+  side: 'left' | 'right';
+  children: ReactNode;
+}) {
+  return (
+    <span
+      aria-hidden="true"
+      style={{
+        position: 'absolute',
+        top: '50%',
+        transform: 'translateY(-50%)',
+        [side === 'left' ? 'left' : 'right']: '10px',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        color: 'var(--color-text-muted)',
+        pointerEvents: 'none',
+        zIndex: 1,
+      }}
+    >
+      {children}
+    </span>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Field component
+// ---------------------------------------------------------------------------
+
+export const Field = forwardRef<HTMLDivElement, FieldProps>(
+  function Field(
+    {
+      label,
+      hint,
+      error,
+      labelHidden = false,
+      iconLeft,
+      iconRight,
+      required = false,
+      as: As = 'input',
+      inputProps,
+      textareaProps,
+      selectProps,
+      children,
+      className,
+    },
+    ref,
+  ) {
+    const inputId = useId();
+    const hintId = useId();
+    const errorId = useId();
+
+    const hasError = Boolean(error);
+    const isDisabled =
+      As === 'input'
+        ? Boolean(inputProps?.disabled)
+        : As === 'textarea'
+        ? Boolean(textareaProps?.disabled)
+        : Boolean(selectProps?.disabled);
+
+    // aria-describedby links input to hint or error message
+    const describedBy = hasError ? errorId : hint ? hintId : undefined;
+
+    const inputStyle = buildInputStyle({
+      hasError,
+      isDisabled,
+      iconLeftPresent: Boolean(iconLeft),
+      iconRightPresent: Boolean(iconRight),
+    });
+
+    return (
+      <div
+        ref={ref}
+        className={className}
+        style={{ display: 'flex', flexDirection: 'column', gap: 'var(--space-2)' }}
+      >
+        {/* Label */}
+        <label
+          htmlFor={inputId}
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            gap: 'var(--space-1)',
+            fontSize: 'var(--type-small)',
+            lineHeight: 'var(--type-small-lh)',
+            fontWeight: 500,
+            color: 'var(--color-text-primary)',
+          }}
+        >
+          {labelHidden ? (
+            <span className="sr-only">{label}</span>
+          ) : (
+            <span>{label}</span>
+          )}
+          {required && (
+            <span
+              aria-hidden="true"
+              style={{ color: 'var(--color-danger)', marginLeft: 'var(--space-px)' }}
+            >
+              *
+            </span>
+          )}
+        </label>
+
+        {/* Input wrapper (relative for icon slots) */}
+        <div style={{ position: 'relative' }}>
+          {iconLeft && <IconSlot side="left">{iconLeft}</IconSlot>}
+
+          {As === 'textarea' ? (
+            <textarea
+              id={inputId}
+              aria-required={required || undefined}
+              aria-invalid={hasError || undefined}
+              aria-describedby={describedBy}
+              disabled={isDisabled}
+              {...textareaProps}
+              style={{
+                ...inputStyle,
+                minHeight: '80px',
+                resize: 'vertical',
+                cursor: isDisabled ? 'not-allowed' : 'auto',
+                ...textareaProps?.style,
+              }}
+            />
+          ) : As === 'select' ? (
+            <select
+              id={inputId}
+              aria-required={required || undefined}
+              aria-invalid={hasError || undefined}
+              aria-describedby={describedBy}
+              disabled={isDisabled}
+              {...selectProps}
+              style={{
+                ...inputStyle,
+                appearance: 'none',
+                cursor: isDisabled ? 'not-allowed' : 'pointer',
+                paddingRight: '36px',
+                ...selectProps?.style,
+              }}
+            >
+              {children}
+            </select>
+          ) : (
+            <input
+              id={inputId}
+              aria-required={required || undefined}
+              aria-invalid={hasError || undefined}
+              aria-describedby={describedBy}
+              disabled={isDisabled}
+              {...inputProps}
+              style={{
+                ...inputStyle,
+                ...inputProps?.style,
+              }}
+            />
+          )}
+
+          {iconRight && <IconSlot side="right">{iconRight}</IconSlot>}
+        </div>
+
+        {/* Error message (role=alert for immediate SR announcement) */}
+        {hasError && (
+          <p
+            id={errorId}
+            role="alert"
+            style={{
+              fontSize: 'var(--type-caption)',
+              lineHeight: 'var(--type-caption-lh)',
+              color: 'var(--color-danger)',
+              margin: 0,
+            }}
+          >
+            {error}
+          </p>
+        )}
+
+        {/* Hint (shown when no error) */}
+        {!hasError && hint && (
+          <p
+            id={hintId}
+            style={{
+              fontSize: 'var(--type-caption)',
+              lineHeight: 'var(--type-caption-lh)',
+              color: 'var(--color-text-muted)',
+              margin: 0,
+            }}
+          >
+            {hint}
+          </p>
+        )}
+      </div>
+    );
+  },
+);
+
+Field.displayName = 'Field';
+
+export default Field;