aplance-ui 1.0.1

package/registry/components/ui/input-fields/media-input/useMediaUpload.tsx

@@ -0,0 +1,302 @@
+import {
+  type ChangeEvent,
+  type DragEvent,
+  type HTMLAttributes,
+  type InputHTMLAttributes,
+  type RefObject,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import type { MediaFile, MediaRejection } from "./types";
+import {
+  revokePreviewUrl,
+  validateIncomingFiles,
+  wrapAsMediaFile,
+} from "./utils";
+
+export type UseMediaUploadOptions = {
+  /** Controlled value. Must be the array previously returned by the hook. */
+  value?: MediaFile[];
+  /** Initial value for uncontrolled usage. Plain `File`s are wrapped automatically. */
+  defaultValue?: MediaFile[] | File[];
+  onChange?: (files: MediaFile[]) => void;
+  onAccepted?: (files: MediaFile[]) => void;
+  onRejected?: (rejections: MediaRejection[]) => void;
+  onRemove?: (file: MediaFile) => void;
+
+  accept?: string;
+  multiple?: boolean;
+  maxFiles?: number;
+  maxSize?: number;
+
+  disabled?: boolean;
+  readOnly?: boolean;
+};
+
+export type UseMediaUploadReturn = {
+  files: MediaFile[];
+  rejections: MediaRejection[];
+  isDragging: boolean;
+
+  /** Imperatively open the native file picker. */
+  open: () => void;
+  /** Programmatic add - used by the host component and consumers alike. */
+  add: (incoming: File[] | FileList | null | undefined) => void;
+  remove: (id: string) => void;
+  clear: () => void;
+
+  /** Spread on the dropzone container to enable drag-and-drop + click-to-open. */
+  getRootProps: <E extends HTMLElement = HTMLDivElement>(
+    overrides?: HTMLAttributes<E>,
+  ) => HTMLAttributes<E>;
+  /** Spread on the hidden `<input type="file">`. The hook owns this element. */
+  getInputProps: (
+    overrides?: InputHTMLAttributes<HTMLInputElement>,
+  ) => InputHTMLAttributes<HTMLInputElement> & {
+    ref: RefObject<HTMLInputElement | null>;
+  };
+};
+
+/**
+ * Headless file upload behavior. Owns dedupe, validation, drag state, and
+ * preview URL lifecycle. The host component decides what to render - see
+ * `MediaInput` for the full UI, or wire `getRootProps`/`getInputProps`
+ * yourself for a custom layout.
+ */
+export function useMediaUpload({
+  value,
+  defaultValue,
+  onChange,
+  onAccepted,
+  onRejected,
+  onRemove,
+  accept,
+  multiple = false,
+  maxFiles,
+  maxSize,
+  disabled = false,
+  readOnly = false,
+}: UseMediaUploadOptions): UseMediaUploadReturn {
+  const isControlled = value !== undefined;
+
+  const [internal, setInternal] = useState<MediaFile[]>(() =>
+    defaultValue ? defaultValue.map(wrapAsMediaFile) : [],
+  );
+  const [rejections, setRejections] = useState<MediaRejection[]>([]);
+  const [isDragging, setIsDragging] = useState(false);
+  const dragCounter = useRef(0);
+
+  const inputRef = useRef<HTMLInputElement>(null);
+  const filesRef = useRef<MediaFile[]>(isControlled ? value! : internal);
+
+  useEffect(() => {
+    filesRef.current = isControlled ? value! : internal;
+  }, [isControlled, value, internal]);
+
+  // Revoke any preview URLs the hook created on unmount so blob memory is
+  // freed even if the consumer forgets to clear state.
+  useEffect(
+    () => () => {
+      filesRef.current.forEach(revokePreviewUrl);
+    },
+    [],
+  );
+
+  const commit = useCallback(
+    (next: MediaFile[]) => {
+      if (!isControlled) setInternal(next);
+      onChange?.(next);
+    },
+    [isControlled, onChange],
+  );
+
+  const add = useCallback(
+    (incoming: File[] | FileList | null | undefined) => {
+      if (!incoming || disabled || readOnly) return;
+      const list = Array.from(incoming as ArrayLike<File>);
+      if (list.length === 0) return;
+
+      const existing = filesRef.current;
+      const baseExisting = multiple ? existing : [];
+
+      const { accepted, rejected } = validateIncomingFiles(list, {
+        accept,
+        maxSize,
+        maxFiles,
+        multiple,
+        existing: baseExisting,
+      });
+
+      // Single-mode replacement frees the previous preview blob immediately.
+      if (!multiple && existing.length > 0) existing.forEach(revokePreviewUrl);
+
+      const next = multiple ? [...existing, ...accepted] : accepted;
+      if (accepted.length > 0) {
+        commit(next);
+        onAccepted?.(accepted);
+      }
+      setRejections(rejected);
+      if (rejected.length > 0) onRejected?.(rejected);
+    },
+    [
+      accept,
+      commit,
+      disabled,
+      maxFiles,
+      maxSize,
+      multiple,
+      onAccepted,
+      onRejected,
+      readOnly,
+    ],
+  );
+
+  const remove = useCallback(
+    (id: string) => {
+      if (disabled || readOnly) return;
+      const target = filesRef.current.find((f) => f.id === id);
+      if (!target) return;
+      revokePreviewUrl(target);
+      const next = filesRef.current.filter((f) => f.id !== id);
+      commit(next);
+      onRemove?.(target);
+    },
+    [commit, disabled, onRemove, readOnly],
+  );
+
+  const clear = useCallback(() => {
+    if (disabled || readOnly) return;
+    filesRef.current.forEach(revokePreviewUrl);
+    commit([]);
+    setRejections([]);
+  }, [commit, disabled, readOnly]);
+
+  const open = useCallback(() => {
+    if (disabled || readOnly) return;
+    inputRef.current?.click();
+  }, [disabled, readOnly]);
+
+  const handleInputChange = useCallback(
+    (e: ChangeEvent<HTMLInputElement>) => {
+      add(e.target.files);
+      // Reset so re-selecting the same file fires `change` again.
+      e.target.value = "";
+    },
+    [add],
+  );
+
+  const handleDragEnter = useCallback(
+    (e: DragEvent) => {
+      if (disabled || readOnly) return;
+      e.preventDefault();
+      e.stopPropagation();
+      dragCounter.current += 1;
+      if (e.dataTransfer?.types?.includes("Files")) setIsDragging(true);
+    },
+    [disabled, readOnly],
+  );
+
+  const handleDragLeave = useCallback((e: DragEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
+    dragCounter.current = Math.max(0, dragCounter.current - 1);
+    if (dragCounter.current === 0) setIsDragging(false);
+  }, []);
+
+  const handleDragOver = useCallback(
+    (e: DragEvent) => {
+      if (disabled || readOnly) return;
+      e.preventDefault();
+      e.stopPropagation();
+      if (e.dataTransfer) e.dataTransfer.dropEffect = "copy";
+    },
+    [disabled, readOnly],
+  );
+
+  const handleDrop = useCallback(
+    (e: DragEvent) => {
+      if (disabled || readOnly) return;
+      e.preventDefault();
+      e.stopPropagation();
+      dragCounter.current = 0;
+      setIsDragging(false);
+      add(e.dataTransfer?.files);
+    },
+    [add, disabled, readOnly],
+  );
+
+  const getRootProps = useCallback(
+    <E extends HTMLElement = HTMLDivElement>(
+      overrides: HTMLAttributes<E> = {},
+    ): HTMLAttributes<E> => ({
+      ...overrides,
+      onClick: (e) => {
+        overrides.onClick?.(e);
+        if (!e.defaultPrevented) open();
+      },
+      onKeyDown: (e) => {
+        overrides.onKeyDown?.(e);
+        if (e.defaultPrevented) return;
+        if (e.key === "Enter" || e.key === " ") {
+          e.preventDefault();
+          open();
+        }
+      },
+      onDragEnter: (e) => {
+        overrides.onDragEnter?.(e);
+        handleDragEnter(e);
+      },
+      onDragLeave: (e) => {
+        overrides.onDragLeave?.(e);
+        handleDragLeave(e);
+      },
+      onDragOver: (e) => {
+        overrides.onDragOver?.(e);
+        handleDragOver(e);
+      },
+      onDrop: (e) => {
+        overrides.onDrop?.(e);
+        handleDrop(e);
+      },
+    }),
+    [handleDragEnter, handleDragLeave, handleDragOver, handleDrop, open],
+  );
+
+  const getInputProps = useCallback(
+    (overrides: InputHTMLAttributes<HTMLInputElement> = {}) => ({
+      type: "file" as const,
+      hidden: true,
+      tabIndex: -1,
+      accept,
+      multiple,
+      disabled: disabled || readOnly,
+      ...overrides,
+      ref: inputRef,
+      onChange: (e: ChangeEvent<HTMLInputElement>) => {
+        overrides.onChange?.(e);
+        handleInputChange(e);
+      },
+    }),
+    [accept, disabled, handleInputChange, multiple, readOnly],
+  );
+
+  const files = isControlled ? value! : internal;
+
+  return useMemo(
+    () => ({
+      files,
+      rejections,
+      isDragging,
+      open,
+      add,
+      remove,
+      clear,
+      getRootProps,
+      getInputProps,
+    }),
+    [add, clear, files, getInputProps, getRootProps, isDragging, open, rejections, remove],
+  );
+}

package/registry/components/ui/input-fields/media-input/utils.ts

@@ -0,0 +1,325 @@
+import type { MediaFile, MediaKind, MediaRejection, MediaRejectionCode } from "./types";
+
+const SIZE_UNITS = ["B", "KB", "MB", "GB", "TB"] as const;
+
+export const formatBytes = (bytes: number): string => {
+  if (!Number.isFinite(bytes) || bytes < 0) return "0 B";
+  if (bytes === 0) return "0 B";
+  const exp = Math.min(
+    SIZE_UNITS.length - 1,
+    Math.floor(Math.log(bytes) / Math.log(1024)),
+  );
+  const value = bytes / 1024 ** exp;
+  const formatted = value >= 100 || exp === 0 ? value.toFixed(0) : value.toFixed(1);
+  return `${formatted} ${SIZE_UNITS[exp]}`;
+};
+
+export const isImageFile = (file: File): boolean =>
+  file.type.startsWith("image/");
+
+export const isVideoFile = (file: File): boolean =>
+  file.type.startsWith("video/");
+
+export const isAudioFile = (file: File): boolean =>
+  file.type.startsWith("audio/");
+
+/**
+ * Match a file against an HTML `accept` string. Supports MIME globs
+ * (image-slash-star), exact MIME types (`application/pdf`), extension globs
+ * (`.png`), and bare wildcards (`*` or any-MIME). Empty/undefined accept
+ * matches every file.
+ */
+export const matchesAccept = (file: File, accept?: string): boolean => {
+  if (!accept) return true;
+  const normalized = accept
+    .split(",")
+    .map((token) => token.trim().toLowerCase())
+    .filter(Boolean);
+  if (normalized.length === 0) return true;
+
+  const mime = (file.type || "").toLowerCase();
+  const name = file.name.toLowerCase();
+
+  return normalized.some((token) => {
+    if (token === "*" || token === "*/*") return true;
+    if (token.startsWith(".")) return name.endsWith(token);
+    if (token.endsWith("/*")) {
+      const prefix = token.slice(0, -1);
+      return mime.startsWith(prefix);
+    }
+    return mime === token;
+  });
+};
+
+const fileFingerprint = (file: File): string =>
+  `${file.name}::${file.size}::${file.lastModified}`;
+
+const generateId = (): string =>
+  typeof crypto !== "undefined" && "randomUUID" in crypto
+    ? crypto.randomUUID()
+    : `media-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 9)}`;
+
+export const buildMediaFile = (file: File): MediaFile => {
+  const previewUrl =
+    typeof URL !== "undefined" && (isImageFile(file) || isVideoFile(file))
+      ? URL.createObjectURL(file)
+      : undefined;
+  return {
+    id: generateId(),
+    file,
+    previewUrl,
+    status: "ready",
+  };
+};
+
+/**
+ * Only revoke `blob:` URLs that the hook itself created. Consumers may pass
+ * pre-existing `https://...` URLs (server-rendered media, signed thumbnails,
+ * etc.) and we must not touch those.
+ */
+export const revokePreviewUrl = (file: MediaFile): void => {
+  if (
+    typeof URL !== "undefined" &&
+    typeof file.previewUrl === "string" &&
+    file.previewUrl.startsWith("blob:")
+  ) {
+    URL.revokeObjectURL(file.previewUrl);
+  }
+};
+
+export const wrapAsMediaFile = (input: File | MediaFile): MediaFile =>
+  input instanceof File ? buildMediaFile(input) : input;
+
+export const rejectionMessage = (
+  code: MediaRejectionCode,
+  meta: { maxSize?: number; maxFiles?: number; accept?: string } = {},
+): string => {
+  switch (code) {
+    case "file-too-large":
+      return meta.maxSize
+        ? `File exceeds the ${formatBytes(meta.maxSize)} size limit.`
+        : "File is too large.";
+    case "file-invalid-type":
+      return meta.accept
+        ? `File type is not allowed. Accepted: ${meta.accept}.`
+        : "File type is not allowed.";
+    case "too-many-files":
+      return meta.maxFiles
+        ? `Only ${meta.maxFiles} file${meta.maxFiles === 1 ? "" : "s"} can be added.`
+        : "Too many files selected.";
+    case "duplicate-file":
+      return "File has already been added.";
+  }
+};
+
+export type ValidateOptions = {
+  accept?: string;
+  maxSize?: number;
+  maxFiles?: number;
+  multiple: boolean;
+  existing: MediaFile[];
+};
+
+export type ValidateResult = {
+  accepted: MediaFile[];
+  rejected: MediaRejection[];
+};
+
+/**
+ * Apply accept/size/dedupe/limit rules and convert raw `File`s into
+ * `MediaFile`s. Stops adding once `maxFiles` is reached and reports the
+ * remainder as `too-many-files` so consumers can display the issue.
+ */
+export const validateIncomingFiles = (
+  incoming: File[],
+  options: ValidateOptions,
+): ValidateResult => {
+  const accepted: MediaFile[] = [];
+  const rejected: MediaRejection[] = [];
+
+  const seen = new Set(options.existing.map((f) => fileFingerprint(f.file)));
+  const remainingCapacity = options.multiple
+    ? options.maxFiles
+      ? Math.max(0, options.maxFiles - options.existing.length)
+      : Number.POSITIVE_INFINITY
+    : 1;
+
+  for (const file of incoming) {
+    if (!matchesAccept(file, options.accept)) {
+      rejected.push({
+        file,
+        code: "file-invalid-type",
+        message: rejectionMessage("file-invalid-type", { accept: options.accept }),
+      });
+      continue;
+    }
+    if (options.maxSize && file.size > options.maxSize) {
+      rejected.push({
+        file,
+        code: "file-too-large",
+        message: rejectionMessage("file-too-large", { maxSize: options.maxSize }),
+      });
+      continue;
+    }
+    const fingerprint = fileFingerprint(file);
+    if (seen.has(fingerprint)) {
+      rejected.push({
+        file,
+        code: "duplicate-file",
+        message: rejectionMessage("duplicate-file"),
+      });
+      continue;
+    }
+    if (accepted.length >= remainingCapacity) {
+      rejected.push({
+        file,
+        code: "too-many-files",
+        message: rejectionMessage("too-many-files", { maxFiles: options.maxFiles }),
+      });
+      continue;
+    }
+    seen.add(fingerprint);
+    accepted.push(buildMediaFile(file));
+  }
+
+  return { accepted, rejected };
+};
+
+// ─── File kind detection ─────────────────────────────────────────────────────
+
+const EXTENSION_KIND_MAP: Record<string, MediaKind> = {
+  // documents
+  doc: "document",
+  docx: "document",
+  rtf: "document",
+  odt: "document",
+  pages: "document",
+  // spreadsheets
+  xls: "spreadsheet",
+  xlsx: "spreadsheet",
+  csv: "spreadsheet",
+  tsv: "spreadsheet",
+  ods: "spreadsheet",
+  numbers: "spreadsheet",
+  // presentations
+  ppt: "presentation",
+  pptx: "presentation",
+  odp: "presentation",
+  key: "presentation",
+  // archives
+  zip: "archive",
+  rar: "archive",
+  "7z": "archive",
+  tar: "archive",
+  gz: "archive",
+  bz2: "archive",
+  xz: "archive",
+  // code
+  js: "code",
+  jsx: "code",
+  ts: "code",
+  tsx: "code",
+  mjs: "code",
+  cjs: "code",
+  json: "code",
+  html: "code",
+  htm: "code",
+  css: "code",
+  scss: "code",
+  less: "code",
+  vue: "code",
+  svelte: "code",
+  py: "code",
+  rb: "code",
+  go: "code",
+  rs: "code",
+  java: "code",
+  c: "code",
+  cpp: "code",
+  h: "code",
+  cs: "code",
+  php: "code",
+  sh: "code",
+  yaml: "code",
+  yml: "code",
+  toml: "code",
+  xml: "code",
+  sql: "code",
+  // text
+  txt: "text",
+  md: "text",
+  markdown: "text",
+  log: "text",
+  // font
+  ttf: "font",
+  otf: "font",
+  woff: "font",
+  woff2: "font",
+  eot: "font",
+};
+
+const MIME_KIND_MAP: Record<string, MediaKind> = {
+  "application/pdf": "pdf",
+  "application/msword": "document",
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document": "document",
+  "application/vnd.oasis.opendocument.text": "document",
+  "application/rtf": "document",
+  "application/vnd.ms-excel": "spreadsheet",
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": "spreadsheet",
+  "application/vnd.oasis.opendocument.spreadsheet": "spreadsheet",
+  "text/csv": "spreadsheet",
+  "text/tab-separated-values": "spreadsheet",
+  "application/vnd.ms-powerpoint": "presentation",
+  "application/vnd.openxmlformats-officedocument.presentationml.presentation": "presentation",
+  "application/vnd.oasis.opendocument.presentation": "presentation",
+  "application/zip": "archive",
+  "application/x-zip-compressed": "archive",
+  "application/x-rar-compressed": "archive",
+  "application/vnd.rar": "archive",
+  "application/x-7z-compressed": "archive",
+  "application/x-tar": "archive",
+  "application/gzip": "archive",
+  "application/x-gzip": "archive",
+  "application/x-bzip2": "archive",
+  "application/json": "code",
+  "application/xml": "code",
+  "application/sql": "code",
+  "application/x-yaml": "code",
+  "text/yaml": "code",
+  "text/html": "code",
+  "text/css": "code",
+  "text/javascript": "code",
+  "application/javascript": "code",
+  "application/typescript": "code",
+  "text/x-python": "code",
+  "text/markdown": "text",
+};
+
+const fileExtension = (file: File): string => {
+  const dot = file.name.lastIndexOf(".");
+  if (dot === -1 || dot === file.name.length - 1) return "";
+  return file.name.slice(dot + 1).toLowerCase();
+};
+
+/**
+ * Resolve a {@link MediaKind} from MIME type first (authoritative), then
+ * fall back to extension lookup. Always returns a value - `"other"` when
+ * nothing matches - so callers never need to handle `undefined`.
+ */
+export const previewKindOf = (file: File): MediaKind => {
+  if (isImageFile(file)) return "image";
+  if (isVideoFile(file)) return "video";
+  if (isAudioFile(file)) return "audio";
+  const mime = (file.type || "").toLowerCase();
+  if (mime.startsWith("font/")) return "font";
+  if (mime.startsWith("text/")) {
+    if (MIME_KIND_MAP[mime]) return MIME_KIND_MAP[mime];
+    return "text";
+  }
+  if (MIME_KIND_MAP[mime]) return MIME_KIND_MAP[mime];
+
+  const ext = fileExtension(file);
+  if (ext && EXTENSION_KIND_MAP[ext]) return EXTENSION_KIND_MAP[ext];
+
+  return "other";
+};

package/registry/components/ui/input-fields/otp-input/otp-input.module.css

@@ -0,0 +1,24 @@
+/* OTP Input - N-cell variant of input-fields family.
+   Each cell reuses sCommon.field_default for border/focus/disabled tokens
+   so theme variants flow through unchanged. This module only sizes the
+   cell into a square and centers its single character. */
+
+.cells {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--spacing-4);
+  width: fit-content;
+}
+
+.cell {
+  --otp-cell-size: var(--spacing-12);
+
+  width: var(--otp-cell-size);
+  min-width: var(--otp-cell-size);
+  height: var(--otp-cell-size);
+  min-height: var(--otp-cell-size);
+  padding: 0;
+  text-align: center;
+  font-size: var(--font-size-lg);
+  font-variant-numeric: tabular-nums;
+}