@ews-admin/global-design-system 1.29.0 → 1.31.0

package/src/components/PinCodeInput/PinCodeInput.tsx

@@ -0,0 +1,184 @@
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import { cn } from "../../utils";
+import type { PinCodeInputProps } from "./PinCodeInput.types";
+
+const MASK = "•";
+const onlyDigits = (text: string) => text.replace(/\D/g, "");
+
+/**
+ * Row of one-digit boxes for a PIN or a one-time code (desktop keyboards):
+ * typing moves to the next box, Backspace goes back, arrows move, pasting a
+ * code fills the boxes and `onComplete` fires once every box is filled.
+ */
+const PinCodeInput = ({
+  length = 4,
+  onComplete,
+  onChange,
+  masked = true,
+  autoComplete = "off",
+  autoFocus = true,
+  disabled = false,
+  invalid = false,
+  resetKey,
+  digitLabel,
+  groupLabel,
+  className,
+}: PinCodeInputProps) => {
+  const empty = useCallback(() => Array.from({ length }, () => ""), [length]);
+  const [digits, setDigits] = useState<string[]>(empty);
+  const digitsRef = useRef<string[]>(digits);
+  const inputs = useRef<Array<HTMLInputElement | null>>([]);
+
+  const focusBox = (index: number) => {
+    const input = inputs.current[Math.max(0, Math.min(index, length - 1))];
+    input?.focus();
+    input?.select();
+  };
+
+  const update = (next: string[]) => {
+    digitsRef.current = next;
+    setDigits(next);
+    const value = next.join("");
+    onChange?.(value);
+    if (value.length === length && next.every(Boolean)) onComplete(value);
+  };
+
+  /** Writes `chars` from box `start` on and focuses the box after them. */
+  const fill = (start: number, chars: string) => {
+    const next = [...digitsRef.current];
+    const written = chars.slice(0, length - start).split("");
+    written.forEach((char, offset) => {
+      next[start + offset] = char;
+    });
+    focusBox(start + written.length);
+    update(next);
+  };
+
+  // Clear the boxes when the caller asks for it.
+  useEffect(() => {
+    const cleared = empty();
+    digitsRef.current = cleared;
+    setDigits(cleared);
+  }, [resetKey, empty]);
+
+  // Focus the first empty box on mount, after a reset and once re-enabled.
+  useEffect(() => {
+    if (!autoFocus || disabled) return;
+    const firstEmpty = digitsRef.current.findIndex((digit) => !digit);
+    focusBox(firstEmpty === -1 ? length - 1 : firstEmpty);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [autoFocus, disabled, resetKey, length]);
+
+  const handleChange = (index: number, event: React.ChangeEvent<HTMLInputElement>) => {
+    if (disabled) return;
+    const { value, selectionStart } = event.target;
+    const typed = onlyDigits(value);
+    if (!typed) {
+      const next = [...digitsRef.current];
+      next[index] = "";
+      update(next);
+      return;
+    }
+    // A digit typed next to the one already in the box: keep the new one.
+    if (digitsRef.current[index] && value.length === 2) {
+      const inserted = value.charAt((selectionStart ?? value.length) - 1);
+      if (/\d/.test(inserted)) {
+        fill(index, inserted);
+        return;
+      }
+    }
+    // One digit, or a whole code (browser autofill of the one-time code).
+    fill(typed.length >= length ? 0 : index, typed);
+  };
+
+  const handleKeyDown = (index: number, event: React.KeyboardEvent<HTMLInputElement>) => {
+    if (disabled) return;
+    switch (event.key) {
+      case "Backspace": {
+        event.preventDefault();
+        const next = [...digitsRef.current];
+        const target = next[index] ? index : Math.max(0, index - 1);
+        next[target] = "";
+        focusBox(target);
+        update(next);
+        return;
+      }
+      case "Delete": {
+        event.preventDefault();
+        const next = [...digitsRef.current];
+        next[index] = "";
+        update(next);
+        return;
+      }
+      case "ArrowLeft":
+        event.preventDefault();
+        focusBox(index - 1);
+        return;
+      case "ArrowRight":
+        event.preventDefault();
+        focusBox(index + 1);
+        return;
+      case "Home":
+        event.preventDefault();
+        focusBox(0);
+        return;
+      case "End":
+        event.preventDefault();
+        focusBox(length - 1);
+        return;
+    }
+  };
+
+  const handlePaste = (index: number, event: React.ClipboardEvent<HTMLInputElement>) => {
+    event.preventDefault();
+    if (disabled) return;
+    const pasted = onlyDigits(event.clipboardData.getData("text"));
+    if (!pasted) return;
+    fill(pasted.length >= length ? 0 : index, pasted);
+  };
+
+  return (
+    // Codes stay left-to-right in RTL locales.
+    <div
+      dir="ltr"
+      role="group"
+      aria-label={groupLabel}
+      data-testid="pin-code-input"
+      className={cn("flex justify-center gap-3", invalid && "animate-pin-shake", className)}
+    >
+      {digits.map((digit, index) => (
+        <input
+          key={index}
+          ref={(element) => {
+            inputs.current[index] = element;
+          }}
+          type="text"
+          inputMode="numeric"
+          pattern="[0-9]*"
+          autoComplete={index === 0 ? autoComplete : "off"}
+          autoCorrect="off"
+          spellCheck={false}
+          value={digit && masked ? MASK : digit}
+          disabled={disabled}
+          aria-label={digitLabel(index + 1, length)}
+          aria-invalid={invalid || undefined}
+          data-filled={!!digit}
+          onChange={(event) => handleChange(index, event)}
+          onKeyDown={(event) => handleKeyDown(index, event)}
+          onPaste={(event) => handlePaste(index, event)}
+          onFocus={(event) => event.target.select()}
+          className={cn(
+            "h-14 w-12 rounded-lg border bg-white text-center text-2xl font-medium text-ews-gray-900 outline-none",
+            "transition-colors focus:border-ews-primary focus:ring-2 focus:ring-ews-primary",
+            "disabled:cursor-not-allowed disabled:opacity-60",
+            invalid ? "border-ews-error" : digit ? "border-ews-primary" : "border-ews-gray-300",
+            disabled && digit && "animate-pulse",
+          )}
+        />
+      ))}
+    </div>
+  );
+};
+
+export type { PinCodeInputProps } from "./PinCodeInput.types";
+export { PinCodeInput };

package/src/components/PinCodeInput/PinCodeInput.types.ts

@@ -0,0 +1,25 @@
+export interface PinCodeInputProps {
+  /** Number of boxes (digits). Default 4. */
+  length?: number;
+  /** Called once every box is filled, with the full code. */
+  onComplete: (code: string) => void;
+  /** Called on every change of the typed value. */
+  onChange?: (value: string) => void;
+  /** Shows bullets instead of the typed digits (PIN). Default true. */
+  masked?: boolean;
+  /** `autocomplete` of the boxes, e.g. "one-time-code" for an SMS code. Default "off". */
+  autoComplete?: string;
+  /** Focuses the first empty box on mount, after a reset and when re-enabled. Default true. */
+  autoFocus?: boolean;
+  /** Ignores input (e.g. while the code is being checked). */
+  disabled?: boolean;
+  /** Shows the boxes in the error color and shakes them. */
+  invalid?: boolean;
+  /** Changing this value clears the boxes (e.g. after a wrong code). */
+  resetKey?: string | number;
+  /** Accessible label of each box, e.g. (1, 4) => "Digit 1 of 4". */
+  digitLabel: (position: number, total: number) => string;
+  /** Accessible label of the group of boxes. */
+  groupLabel?: string;
+  className?: string;
+}

package/src/components/PinCodeInput/index.ts

@@ -0,0 +1,2 @@
+export { PinCodeInput } from "./PinCodeInput";
+export type { PinCodeInputProps } from "./PinCodeInput";

package/src/components/PinPad/PinPad.tsx

@@ -0,0 +1,150 @@
+import { Delete } from "lucide-react";
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import { cn } from "../../utils";
+import type { PinPadProps } from "./PinPad.types";
+
+const DIGIT_ROWS = ["1", "2", "3", "4", "5", "6", "7", "8", "9"];
+
+const keyClass =
+  "flex h-16 w-16 items-center justify-center justify-self-center rounded-full text-3xl font-light text-ews-gray-900 " +
+  "transition-colors hover:bg-ews-gray-100 active:bg-ews-gray-200 " +
+  "focus-visible:ring-2 focus-visible:ring-ews-primary disabled:cursor-not-allowed disabled:opacity-40 disabled:hover:bg-transparent";
+
+/**
+ * iOS-style PIN entry: a row of dots filled as digits are typed and a 3x4
+ * keypad. Texts are provided by the caller (already translated).
+ */
+const PinPad = ({
+  length = 4,
+  onComplete,
+  onChange,
+  disabled = false,
+  invalid = false,
+  resetKey,
+  captureKeyboard = true,
+  eraseLabel,
+  progressLabel,
+  keypadLabel,
+  className,
+}: PinPadProps) => {
+  const [value, setValue] = useState("");
+  const valueRef = useRef("");
+
+  const update = useCallback(
+    (next: string) => {
+      valueRef.current = next;
+      setValue(next);
+      onChange?.(next);
+      if (next.length === length) onComplete(next);
+    },
+    [length, onChange, onComplete],
+  );
+
+  // Clear the typed digits when the caller asks for it.
+  useEffect(() => {
+    valueRef.current = "";
+    setValue("");
+  }, [resetKey]);
+
+  const press = useCallback(
+    (digit: string) => {
+      if (disabled || valueRef.current.length >= length) return;
+      update(valueRef.current + digit);
+    },
+    [disabled, length, update],
+  );
+
+  const erase = useCallback(() => {
+    if (disabled || valueRef.current.length === 0) return;
+    update(valueRef.current.slice(0, -1));
+  }, [disabled, update]);
+
+  useEffect(() => {
+    if (!captureKeyboard) return;
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.ctrlKey || event.metaKey || event.altKey) return;
+      const target = event.target as HTMLElement | null;
+      if (target && (target.tagName === "INPUT" || target.tagName === "TEXTAREA")) return;
+      if (/^[0-9]$/.test(event.key)) {
+        event.preventDefault();
+        press(event.key);
+      } else if (event.key === "Backspace") {
+        event.preventDefault();
+        erase();
+      }
+    };
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, [captureKeyboard, press, erase]);
+
+  return (
+    <div className={cn("flex flex-col items-center gap-10", className)}>
+      {/* Keypads stay left-to-right in RTL locales, like phone keypads. */}
+      <div
+        dir="ltr"
+        aria-hidden="true"
+        data-testid="pin-dots"
+        className={cn("flex gap-5", invalid && "animate-pin-shake")}
+      >
+        {Array.from({ length }, (_, index) => (
+          <span
+            key={index}
+            data-filled={index < value.length}
+            className={cn(
+              "h-3.5 w-3.5 rounded-full transition-colors",
+              invalid
+                ? "bg-ews-error"
+                : index < value.length
+                  ? "bg-ews-primary"
+                  : "bg-ews-primary-light",
+              disabled && index < value.length && "animate-pulse",
+            )}
+          />
+        ))}
+      </div>
+      <p className="sr-only" aria-live="polite" aria-atomic="true">
+        {progressLabel(value.length, length)}
+      </p>
+
+      <div
+        dir="ltr"
+        role="group"
+        aria-label={keypadLabel}
+        className="grid grid-cols-3 gap-x-8 gap-y-4"
+      >
+        {DIGIT_ROWS.map((digit) => (
+          <button
+            key={digit}
+            type="button"
+            className={keyClass}
+            disabled={disabled}
+            onClick={() => press(digit)}
+          >
+            {digit}
+          </button>
+        ))}
+        <span aria-hidden="true" />
+        <button
+          type="button"
+          className={keyClass}
+          disabled={disabled}
+          onClick={() => press("0")}
+        >
+          0
+        </button>
+        <button
+          type="button"
+          className={cn(keyClass, "text-ews-gray-700")}
+          disabled={disabled || value.length === 0}
+          aria-label={eraseLabel}
+          onClick={erase}
+        >
+          <Delete className="h-7 w-7" strokeWidth={1.5} aria-hidden="true" />
+        </button>
+      </div>
+    </div>
+  );
+};
+
+export type { PinPadProps } from "./PinPad.types";
+export { PinPad };

package/src/components/PinPad/PinPad.types.ts

@@ -0,0 +1,23 @@
+export interface PinPadProps {
+  /** Number of digits of the PIN. Default 4. */
+  length?: number;
+  /** Called once the last digit is typed, with the full PIN. */
+  onComplete: (pin: string) => void;
+  /** Called on every change of the typed value. */
+  onChange?: (value: string) => void;
+  /** Ignores taps and key presses (e.g. while the PIN is being checked). */
+  disabled?: boolean;
+  /** Shows the dots in the error color and shakes them. */
+  invalid?: boolean;
+  /** Changing this value clears the typed digits (e.g. after a wrong PIN). */
+  resetKey?: string | number;
+  /** Listens to the physical keyboard (digits and Backspace). Default true. */
+  captureKeyboard?: boolean;
+  /** Accessible label of the erase key. */
+  eraseLabel: string;
+  /** Text announced to screen readers when the number of typed digits changes. */
+  progressLabel: (filled: number, total: number) => string;
+  /** Accessible label of the keypad group. */
+  keypadLabel?: string;
+  className?: string;
+}

package/src/components/PinPad/index.ts

@@ -0,0 +1,2 @@
+export { PinPad } from "./PinPad";
+export type { PinPadProps } from "./PinPad";

package/src/hooks/index.ts

@@ -1,3 +1,6 @@
 export { useDebounce, useDebouncedCallback } from "./useDebounce";
+export { useMediaQuery } from "./useMediaQuery";
+export { useIdleLock } from "./useIdleLock";
+export type { UseIdleLockOptions, UseIdleLockResult } from "./useIdleLock";
 export { useSelectField } from "./useSelectField";
 export type { UseSelectFieldProps } from "./useSelectField";

package/src/hooks/useIdleLock.ts

@@ -0,0 +1,181 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+export interface UseIdleLockOptions {
+  /** Inactivity delay before locking. Default 3 minutes. */
+  timeoutMs?: number;
+  /** Called each time the screen becomes locked (idle, `lock()` or another tab). */
+  onLock?: () => void;
+  /** localStorage key of the locked flag, also the BroadcastChannel name. */
+  storageKey?: string;
+  /** Turns the inactivity timer off (e.g. until the session is loaded). Default true. */
+  enabled?: boolean;
+}
+
+export interface UseIdleLockResult {
+  locked: boolean;
+  lock: () => void;
+  unlock: () => void;
+}
+
+const DEFAULT_TIMEOUT_MS = 180_000;
+const DEFAULT_STORAGE_KEY = "ews-idle-lock";
+const ACTIVITY_WRITE_INTERVAL_MS = 5_000;
+const ACTIVITY_EVENTS = [
+  "pointerdown",
+  "pointermove",
+  "keydown",
+  "wheel",
+  "scroll",
+  "touchstart",
+] as const;
+
+const readStorage = (key: string): string | null => {
+  try {
+    return typeof window === "undefined" ? null : window.localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+};
+
+const writeStorage = (key: string, value: string | null) => {
+  try {
+    if (typeof window === "undefined") return;
+    if (value === null) window.localStorage.removeItem(key);
+    else window.localStorage.setItem(key, value);
+  } catch {
+    // Storage unavailable (private mode, quota): the lock still works in this tab.
+  }
+};
+
+/**
+ * Locks the screen after `timeoutMs` without user activity. The locked flag is
+ * kept in localStorage (it survives a reload) and shared between tabs through
+ * a BroadcastChannel, or the `storage` event where BroadcastChannel is missing:
+ * locking or unlocking one tab does the same in every tab. Activity in any tab
+ * keeps every tab unlocked.
+ */
+export function useIdleLock({
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  onLock,
+  storageKey = DEFAULT_STORAGE_KEY,
+  enabled = true,
+}: UseIdleLockOptions = {}): UseIdleLockResult {
+  const activityKey = `${storageKey}:activity`;
+  const [locked, setLocked] = useState(() => readStorage(storageKey) === "1");
+  const lockedRef = useRef(locked);
+  const onLockRef = useRef(onLock);
+  const lastActivity = useRef(Date.now());
+  const lastActivityWrite = useRef(0);
+  const channelRef = useRef<{ postMessage: (message: string) => void } | null>(
+    null,
+  );
+
+  useEffect(() => {
+    onLockRef.current = onLock;
+  }, [onLock]);
+
+  const markActivity = useCallback(
+    (now: number) => {
+      lastActivity.current = now;
+      if (now - lastActivityWrite.current >= ACTIVITY_WRITE_INTERVAL_MS) {
+        lastActivityWrite.current = now;
+        writeStorage(activityKey, String(now));
+      }
+    },
+    [activityKey],
+  );
+
+  const applyLocked = useCallback((next: boolean) => {
+    if (lockedRef.current === next) return;
+    lockedRef.current = next;
+    setLocked(next);
+    if (next) onLockRef.current?.();
+  }, []);
+
+  const lock = useCallback(() => {
+    if (lockedRef.current) return;
+    writeStorage(storageKey, "1");
+    channelRef.current?.postMessage("lock");
+    applyLocked(true);
+  }, [storageKey, applyLocked]);
+
+  const unlock = useCallback(() => {
+    lastActivityWrite.current = 0;
+    markActivity(Date.now());
+    writeStorage(storageKey, null);
+    channelRef.current?.postMessage("unlock");
+    applyLocked(false);
+  }, [storageKey, applyLocked, markActivity]);
+
+  // Cross-tab sync.
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const onRemote = (nextLocked: boolean) => {
+      if (!nextLocked) lastActivity.current = Date.now();
+      applyLocked(nextLocked);
+    };
+
+    if (typeof window.BroadcastChannel === "function") {
+      const channel = new window.BroadcastChannel(storageKey);
+      channelRef.current = channel;
+      channel.onmessage = (event: MessageEvent) => {
+        if (event.data === "lock") onRemote(true);
+        else if (event.data === "unlock") onRemote(false);
+      };
+      return () => {
+        channelRef.current = null;
+        channel.close();
+      };
+    }
+
+    const onStorage = (event: StorageEvent) => {
+      if (event.key !== storageKey) return;
+      onRemote(event.newValue === "1");
+    };
+    window.addEventListener("storage", onStorage);
+    return () => window.removeEventListener("storage", onStorage);
+  }, [storageKey, applyLocked]);
+
+  // Inactivity timer.
+  useEffect(() => {
+    if (!enabled || locked || typeof window === "undefined") return;
+    lastActivity.current = Date.now();
+    let timer: ReturnType<typeof setTimeout>;
+
+    const idleFor = () => {
+      const shared = Number(readStorage(activityKey)) || 0;
+      return Date.now() - Math.max(lastActivity.current, shared);
+    };
+
+    const check = () => {
+      const idle = idleFor();
+      if (idle >= timeoutMs) lock();
+      else timer = setTimeout(check, timeoutMs - idle);
+    };
+
+    const onActivity = () => markActivity(Date.now());
+
+    // Timers are throttled in background tabs: check the delay on return.
+    const onVisibility = () => {
+      if (document.visibilityState !== "visible") return;
+      if (idleFor() >= timeoutMs) lock();
+      else onActivity();
+    };
+
+    timer = setTimeout(check, timeoutMs);
+    ACTIVITY_EVENTS.forEach((name) =>
+      document.addEventListener(name, onActivity, { capture: true, passive: true }),
+    );
+    document.addEventListener("visibilitychange", onVisibility);
+
+    return () => {
+      clearTimeout(timer);
+      ACTIVITY_EVENTS.forEach((name) =>
+        document.removeEventListener(name, onActivity, { capture: true }),
+      );
+      document.removeEventListener("visibilitychange", onVisibility);
+    };
+  }, [enabled, locked, timeoutMs, activityKey, lock, markActivity]);
+
+  return { locked, lock, unlock };
+}

package/src/hooks/useMediaQuery.ts

@@ -0,0 +1,31 @@
+import { useEffect, useState } from "react";
+
+const matches = (query: string, fallback: boolean) =>
+  typeof window !== "undefined" && typeof window.matchMedia === "function"
+    ? window.matchMedia(query).matches
+    : fallback;
+
+/**
+ * Whether a CSS media query matches, updated when it changes. Returns
+ * `defaultValue` where `matchMedia` does not exist (server rendering, old
+ * test environments).
+ */
+export const useMediaQuery = (query: string, defaultValue = false): boolean => {
+  const [value, setValue] = useState(() => matches(query, defaultValue));
+
+  useEffect(() => {
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function") return;
+    const list = window.matchMedia(query);
+    const onChange = () => setValue(list.matches);
+    onChange();
+    // Safari < 14 only has addListener.
+    if (list.addEventListener) {
+      list.addEventListener("change", onChange);
+      return () => list.removeEventListener("change", onChange);
+    }
+    list.addListener(onChange);
+    return () => list.removeListener(onChange);
+  }, [query]);
+
+  return value;
+};

package/src/index.ts

@@ -55,6 +55,19 @@ export type { PaymentDueBannerProps } from "./components/PaymentDueBanner";
 export { SecureLoader } from "./components/SecureLoader";
 export type { SecureLoaderProps } from "./components/SecureLoader";
 
+export { PinPad } from "./components/PinPad";
+export type { PinPadProps } from "./components/PinPad";
+
+export { PinCodeInput } from "./components/PinCodeInput";
+export type { PinCodeInputProps } from "./components/PinCodeInput";
+
+export { LockScreen } from "./components/LockScreen";
+export type {
+  LockScreenMode,
+  LockScreenProps,
+  LockScreenTexts,
+} from "./components/LockScreen";
+
 // Molecules
 export { SpecialtySearchAutocomplete } from "./molecules";
 export type { Specialty, SpecialtySearchAutocompleteProps } from "./molecules";
@@ -95,8 +108,18 @@ export type {
 } from "./utils";
 
 // Hooks
-export { useDebounce, useDebouncedCallback, useSelectField } from "./hooks";
-export type { UseSelectFieldProps } from "./hooks";
+export {
+  useDebounce,
+  useDebouncedCallback,
+  useIdleLock,
+  useMediaQuery,
+  useSelectField,
+} from "./hooks";
+export type {
+  UseIdleLockOptions,
+  UseIdleLockResult,
+  UseSelectFieldProps,
+} from "./hooks";
 
 // Theme
 export { ThemeProvider, useTheme } from "./theme/ThemeProvider";

package/tailwind.preset.js

@@ -135,6 +135,17 @@ module.exports = {
         large:
           "0 10px 40px -10px rgba(0, 0, 0, 0.15), 0 2px 10px -2px rgba(0, 0, 0, 0.05)",
       },
+      // PinPad: wrong PIN feedback
+      keyframes: {
+        "pin-shake": {
+          "0%, 100%": { transform: "translateX(0)" },
+          "20%, 60%": { transform: "translateX(-8px)" },
+          "40%, 80%": { transform: "translateX(8px)" },
+        },
+      },
+      animation: {
+        "pin-shake": "pin-shake 0.4s ease-in-out",
+      },
     },
   },
   plugins: [