@grampro/kit 0.0.0-stage → 2.4.0

package/source/components/input/react/Input.tsx

@@ -0,0 +1,219 @@
+"use client";
+
+import {
+  useId,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+  type ChangeEvent,
+  type InputHTMLAttributes,
+  type ReactNode,
+  type Ref,
+} from "react";
+import { useControllableState } from "../../shared/react/useControllableState";
+import { describeField } from "../../shared/core/field";
+import { countCharacters } from "../core/count";
+import type { FieldSize, InputLocaleText } from "../core/types";
+import { setNativeValue } from "./dom";
+import { EyeIcon, EyeOffIcon, XIcon } from "./icons";
+import { defaultInputText } from "./locale";
+import { cx, type InputSlot } from "./props";
+
+export interface InputProps
+  extends Omit<InputHTMLAttributes<HTMLInputElement>, "size" | "prefix" | "value" | "defaultValue"> {
+  value?: string;
+  defaultValue?: string;
+  /** The new text on every change. The native `onChange` fires as well. */
+  onValueChange?(value: string): void;
+  label?: ReactNode;
+  description?: ReactNode;
+  /** Message below the field; also marks it invalid. */
+  error?: ReactNode;
+  size?: FieldSize;
+  /** Content before the text, e.g. an icon or "https://". */
+  leading?: ReactNode;
+  /** Content after the text, e.g. a unit such as "kg". */
+  trailing?: ReactNode;
+  /** A button that empties the field. Default false. */
+  clearable?: boolean;
+  /** For `type="password"`, a button that shows the text. Default true. */
+  revealPassword?: boolean;
+  /** A character counter under the field; shows `count / maxLength` when `maxLength` is set. */
+  showCount?: boolean;
+  classNames?: Partial<Record<InputSlot, string>>;
+  localeText?: Partial<InputLocaleText>;
+  /** The `<input>` element. */
+  ref?: Ref<HTMLInputElement>;
+}
+
+/**
+ * A text field with label, hint, error, adornments, clear and password-reveal
+ * buttons and a character counter. Every other prop goes to the `<input>`, so
+ * it works with native forms and form libraries unchanged.
+ */
+export function Input(props: InputProps) {
+  const {
+    ref,
+    value: valueProp,
+    defaultValue,
+    onChange,
+    onValueChange,
+    label,
+    description,
+    error,
+    size = "md",
+    leading,
+    trailing,
+    clearable = false,
+    revealPassword = true,
+    showCount = false,
+    className,
+    classNames,
+    style,
+    localeText,
+    id: idProp,
+    type = "text",
+    disabled,
+    readOnly,
+    required,
+    maxLength,
+    "aria-describedby": describedByProp,
+    ...inputProps
+  } = props;
+
+  const reactId = useId();
+  const id = idProp ?? reactId;
+  const text = useMemo(() => ({ ...defaultInputText, ...localeText }), [localeText]);
+  const inputRef = useRef<HTMLInputElement>(null);
+  useImperativeHandle(ref, () => inputRef.current as HTMLInputElement, []);
+
+  // Mirrors the text even when uncontrolled, for the counter and the clear button.
+  const [current, setCurrent] = useControllableState(valueProp, defaultValue ?? "");
+  const [revealed, setRevealed] = useState(false);
+
+  const handleChange = (event: ChangeEvent<HTMLInputElement>) => {
+    setCurrent(event.target.value);
+    onChange?.(event);
+    onValueChange?.(event.target.value);
+  };
+
+  const clear = () => {
+    const input = inputRef.current;
+    if (!input) return;
+    // A real input event, so onChange and form libraries see the change too.
+    setNativeValue(input, "");
+    input.focus();
+  };
+
+  const invalid = Boolean(error);
+  const isPassword = type === "password";
+  const count = countCharacters(current);
+  const describedBy = describeField(id, { extra: describedByProp, description, error });
+
+  return (
+    <div
+      className={cx("in-root", classNames?.root, className)}
+      style={style}
+      data-size={size}
+      data-disabled={disabled || undefined}
+      data-invalid={invalid ? "" : undefined}
+    >
+      {label && (
+        <label htmlFor={id} className={cx("in-label", classNames?.label)} data-required={required || undefined}>
+          {label}
+        </label>
+      )}
+
+      <div
+        className={cx("in-control", classNames?.control)}
+        data-disabled={disabled || undefined}
+        data-readonly={readOnly || undefined}
+        data-invalid={invalid ? "" : undefined}
+        // A press on the padding or an adornment focuses the text, like a native field.
+        onMouseDown={(event) => {
+          const target = event.target as Element;
+          if (target === inputRef.current || target.closest("button") || disabled) return;
+          event.preventDefault();
+          inputRef.current?.focus();
+        }}
+      >
+        {leading && (
+          <span className="in-adornment" data-side="leading">
+            {leading}
+          </span>
+        )}
+        <input
+          {...inputProps}
+          ref={inputRef}
+          id={id}
+          type={isPassword && revealed ? "text" : type}
+          className={cx("in-input", classNames?.input)}
+          value={valueProp}
+          defaultValue={valueProp === undefined ? defaultValue : undefined}
+          disabled={disabled}
+          readOnly={readOnly}
+          required={required}
+          maxLength={maxLength}
+          aria-invalid={invalid || undefined}
+          aria-describedby={describedBy}
+          onChange={handleChange}
+        />
+        {clearable && current !== "" && !disabled && !readOnly && (
+          <button
+            type="button"
+            tabIndex={-1}
+            className="in-icon-button"
+            aria-label={text.clear}
+            title={text.clear}
+            onClick={clear}
+          >
+            <XIcon />
+          </button>
+        )}
+        {isPassword && revealPassword && (
+          <button
+            type="button"
+            className="in-icon-button"
+            aria-label={revealed ? text.hidePassword : text.showPassword}
+            title={revealed ? text.hidePassword : text.showPassword}
+            aria-pressed={revealed}
+            aria-controls={id}
+            disabled={disabled}
+            onClick={() => setRevealed((shown) => !shown)}
+          >
+            {revealed ? <EyeOffIcon /> : <EyeIcon />}
+          </button>
+        )}
+        {trailing && (
+          <span className="in-adornment" data-side="trailing">
+            {trailing}
+          </span>
+        )}
+      </div>
+
+      {(description || showCount) && (
+        <div className="in-footer">
+          {description && (
+            <span id={`${id}-description`} className={cx("in-description", classNames?.description)}>
+              {description}
+            </span>
+          )}
+          {showCount && (
+            <span
+              className={cx("in-count", classNames?.count)}
+              data-over={maxLength !== undefined && count > maxLength ? "" : undefined}
+            >
+              {text.characterCount(String(count), maxLength !== undefined ? String(maxLength) : undefined)}
+            </span>
+          )}
+        </div>
+      )}
+      {error && (
+        <span id={`${id}-error`} className={cx("in-error", classNames?.error)} role="alert">
+          {error}
+        </span>
+      )}
+    </div>
+  );
+}

package/source/components/input/react/OtpInput.tsx

@@ -0,0 +1,256 @@
+"use client";
+
+import {
+  Fragment,
+  useId,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+  type ChangeEvent,
+  type InputHTMLAttributes,
+  type KeyboardEvent,
+  type ReactNode,
+  type Ref,
+} from "react";
+import { describeField } from "../../shared/core/field";
+import {
+  activeCell,
+  cellAt,
+  otpInputMode,
+  otpPattern,
+  sanitizeOtp,
+  separatorsAfter,
+} from "../core/otp";
+import type { FieldSize, InputLocaleText, OtpMode } from "../core/types";
+import { defaultInputText } from "./locale";
+import { cx, type OtpSlot } from "./props";
+
+export interface OtpInputProps
+  extends Omit<
+    InputHTMLAttributes<HTMLInputElement>,
+    "size" | "prefix" | "value" | "defaultValue" | "type" | "maxLength" | "minLength" | "pattern" | "inputMode"
+  > {
+  /** Number of characters. Default 6. */
+  length?: number;
+  /** Default `numeric`. */
+  mode?: OtpMode;
+  /** Turn letters into capitals as they are typed. */
+  uppercase?: boolean;
+  value?: string;
+  defaultValue?: string;
+  onValueChange?(value: string): void;
+  /** Every cell is filled. */
+  onComplete?(value: string): void;
+  /** Group sizes with a separator between them, e.g. `[3, 3]`. */
+  groups?: number[];
+  /** Show dots instead of the characters. */
+  mask?: boolean;
+  label?: ReactNode;
+  description?: ReactNode;
+  error?: ReactNode;
+  size?: FieldSize;
+  classNames?: Partial<Record<OtpSlot, string>>;
+  localeText?: Partial<InputLocaleText>;
+  /** The `<input>` element. */
+  ref?: Ref<HTMLInputElement>;
+}
+
+/**
+ * A one-time-code field. It is a single real `<input>` drawn as separate cells,
+ * so SMS autofill, paste, password managers and screen readers treat it as one
+ * field, the way they expect.
+ */
+export function OtpInput(props: OtpInputProps) {
+  const {
+    ref,
+    length = 6,
+    mode = "numeric",
+    uppercase = false,
+    value: valueProp,
+    defaultValue = "",
+    onValueChange,
+    onComplete,
+    groups,
+    mask = false,
+    label,
+    description,
+    error,
+    size = "md",
+    className,
+    classNames,
+    style,
+    localeText,
+    id: idProp,
+    disabled,
+    readOnly,
+    required,
+    autoComplete = "one-time-code",
+    onChange,
+    onFocus,
+    onBlur,
+    onKeyDown,
+    onSelect,
+    onClick,
+    "aria-describedby": describedByProp,
+    "aria-label": ariaLabel,
+    ...inputProps
+  } = props;
+
+  const reactId = useId();
+  const id = idProp ?? reactId;
+  const text = useMemo(() => ({ ...defaultInputText, ...localeText }), [localeText]);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const cellsRef = useRef<HTMLDivElement>(null);
+  useImperativeHandle(ref, () => inputRef.current as HTMLInputElement, []);
+
+  const [internal, setInternal] = useState(() => sanitizeOtp(defaultValue, length, mode, uppercase));
+  const value = valueProp !== undefined ? sanitizeOtp(valueProp, length, mode, uppercase) : internal;
+  const [focused, setFocused] = useState(false);
+  const [caret, setCaret] = useState(0);
+
+  /** Once the code is full, the caret selects one character so typing replaces it. */
+  const selectAt = (input: HTMLInputElement, index: number) => {
+    if (input.value.length >= length) {
+      const at = Math.max(0, Math.min(index, length - 1));
+      input.setSelectionRange(at, at + 1);
+    } else {
+      const at = Math.max(0, Math.min(index, input.value.length));
+      input.setSelectionRange(at, at);
+    }
+  };
+
+  const handleChange = (event: ChangeEvent<HTMLInputElement>) => {
+    const next = sanitizeOtp(event.target.value, length, mode, uppercase);
+    if (valueProp === undefined) setInternal(next);
+    onChange?.(event);
+    onValueChange?.(next);
+    if (next.length === length && next !== value) onComplete?.(next);
+  };
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
+    onKeyDown?.(event);
+    const input = event.currentTarget;
+    // Before the code is full the caret is collapsed, and native movement works.
+    if (event.defaultPrevented || event.shiftKey || input.value.length < length) return;
+    const start = input.selectionStart ?? 0;
+    const target: Record<string, number> = {
+      ArrowLeft: start - 1,
+      ArrowRight: start + 1,
+      Home: 0,
+      End: length - 1,
+    };
+    if (!(event.key in target)) return;
+    event.preventDefault();
+    selectAt(input, target[event.key]);
+  };
+
+  const invalid = Boolean(error);
+  const separators = separatorsAfter(groups, length);
+  const active = focused ? activeCell(value.length, length, caret) : -1;
+  const describedBy = describeField(id, { extra: describedByProp, description, error });
+
+  return (
+    <div
+      className={cx("in-root", "in-otp-root", classNames?.root, className)}
+      style={style}
+      data-size={size}
+      data-disabled={disabled || undefined}
+      data-invalid={invalid ? "" : undefined}
+    >
+      {label && (
+        <label htmlFor={id} className={cx("in-label", classNames?.label)} data-required={required || undefined}>
+          {label}
+        </label>
+      )}
+
+      <div
+        ref={cellsRef}
+        className={cx("in-otp", classNames?.cells)}
+        dir="ltr"
+        data-focused={focused || undefined}
+        data-disabled={disabled || undefined}
+        data-invalid={invalid ? "" : undefined}
+      >
+        <input
+          {...inputProps}
+          ref={inputRef}
+          id={id}
+          className="in-otp-input"
+          type={mask ? "password" : "text"}
+          value={value}
+          inputMode={otpInputMode(mode)}
+          pattern={otpPattern(mode, length)}
+          autoComplete={autoComplete}
+          autoCorrect="off"
+          autoCapitalize={uppercase ? "characters" : "off"}
+          spellCheck={false}
+          disabled={disabled}
+          readOnly={readOnly}
+          required={required}
+          aria-label={ariaLabel ?? (label ? undefined : text.otpLabel)}
+          aria-invalid={invalid || undefined}
+          aria-describedby={describedBy}
+          onChange={handleChange}
+          onKeyDown={handleKeyDown}
+          onFocus={(event) => {
+            setFocused(true);
+            selectAt(event.currentTarget, event.currentTarget.value.length);
+            onFocus?.(event);
+          }}
+          onBlur={(event) => {
+            setFocused(false);
+            onBlur?.(event);
+          }}
+          onSelect={(event) => {
+            const input = event.currentTarget;
+            const start = input.selectionStart ?? input.value.length;
+            const end = input.selectionEnd ?? start;
+            if (input.value.length >= length && start === end) selectAt(input, start);
+            else setCaret(start);
+            onSelect?.(event);
+          }}
+          // The text is invisible, so place the caret by the cell that was clicked.
+          onClick={(event) => {
+            const cells = cellsRef.current?.querySelectorAll<HTMLElement>("[data-cell]");
+            if (cells) {
+              const index = cellAt(Array.from(cells, (cell) => cell.getBoundingClientRect()), event.clientX);
+              selectAt(event.currentTarget, index);
+            }
+            onClick?.(event);
+          }}
+        />
+        {Array.from({ length }, (_, index) => {
+          const char = value[index];
+          return (
+            <Fragment key={index}>
+              <span
+                data-cell=""
+                className={cx("in-otp-cell", classNames?.cell)}
+                data-active={index === active || undefined}
+                data-filled={char ? "" : undefined}
+                aria-hidden="true"
+              >
+                {char ? (mask ? "•" : char) : index === active ? <span className="in-otp-caret" /> : null}
+              </span>
+              {separators.has(index) && (
+                <span className={cx("in-otp-separator", classNames?.separator)} aria-hidden="true" />
+              )}
+            </Fragment>
+          );
+        })}
+      </div>
+
+      {description && (
+        <span id={`${id}-description`} className={cx("in-description", classNames?.description)}>
+          {description}
+        </span>
+      )}
+      {error && (
+        <span id={`${id}-error`} className={cx("in-error", classNames?.error)} role="alert">
+          {error}
+        </span>
+      )}
+    </div>
+  );
+}

package/source/components/input/react/dom.ts

@@ -0,0 +1,10 @@
+/**
+ * Sets an input's value the way typing does: through the prototype setter,
+ * followed by a bubbling `input` event. React's `onChange`, form libraries and
+ * native listeners all see the change, controlled or not.
+ */
+export function setNativeValue(input: HTMLInputElement, value: string) {
+  const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")?.set;
+  setter?.call(input, value);
+  input.dispatchEvent(new Event("input", { bubbles: true }));
+}

package/source/components/input/react/icons.tsx

@@ -0,0 +1,17 @@
+import { XIcon as SharedX, Svg, type IconProps } from "../../shared/react/icons";
+
+/** 14px, to sit inside the field without crowding the text. */
+export const XIcon = (p: IconProps) => <SharedX width={14} height={14} {...p} />;
+
+export const EyeIcon = (p: IconProps) => (
+  <Svg {...p}>
+    <path d="M2 12s3.5-7 10-7 10 7 10 7-3.5 7-10 7S2 12 2 12Z" />
+    <circle cx="12" cy="12" r="3" />
+  </Svg>
+);
+export const EyeOffIcon = (p: IconProps) => (
+  <Svg {...p}>
+    <path d="M10.6 5.1A10.8 10.8 0 0 1 12 5c6.5 0 10 7 10 7a17.6 17.6 0 0 1-2.2 3.2M6.6 6.6C3.9 8.3 2 12 2 12s3.5 7 10 7a9.7 9.7 0 0 0 5.4-1.6" />
+    <path d="M9.9 9.9a3 3 0 0 0 4.2 4.2M2 2l20 20" />
+  </Svg>
+);

package/source/components/input/react/locale.ts

@@ -0,0 +1,9 @@
+import type { InputLocaleText } from "../core/types";
+
+export const defaultInputText: InputLocaleText = {
+  clear: "Clear",
+  showPassword: "Show password",
+  hidePassword: "Hide password",
+  characterCount: (count, max) => (max === undefined ? count : `${count} / ${max}`),
+  otpLabel: "Verification code",
+};

package/source/components/input/react/props.ts

@@ -0,0 +1,6 @@
+export type InputSlot = "root" | "label" | "control" | "input" | "description" | "error" | "count";
+
+export type OtpSlot = "root" | "label" | "cells" | "cell" | "separator" | "description" | "error";
+
+// Shared with every other component, so class handling cannot drift.
+export { cx } from "../../shared/core/cx";