aplance-ui 1.0.1

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

@@ -0,0 +1,327 @@
+import { type MouseEvent, useId, useMemo } from "react";
+import clsx from "clsx";
+import { IconUpload, IconX } from "@tabler/icons-react";
+import sCommon from "../common/input-field-common.module.css";
+import sButton from "../../button/button.module.css";
+import { FieldMessage } from "../common/field-message/field-message";
+import { Icon } from "../../../primitives/icon/icon";
+import { Button, type ButtonVariant } from "../../button/button";
+import type { MediaInputProps } from "./types";
+import { useMediaUpload } from "./useMediaUpload";
+import { MediaPreview } from "./media-preview";
+import { formatBytes } from "./utils";
+import s from "./media-input.module.css";
+
+/* This file is intentionally component-only (only exports `MediaInput`)
+   so Vite Fast Refresh can preserve component state across edits. Helpers,
+   hooks, types, and constants live in their own files and are re-exported
+   from the package index - see `packages/core/src/index.ts`. */
+
+export const MediaInput = (props: MediaInputProps) => {
+  const {
+    label,
+    className,
+    style,
+    id,
+    name,
+    info,
+    errors,
+    layout = "default",
+    layoutDirection = "default",
+
+    accept,
+    multiple = false,
+    maxFiles,
+    maxSize,
+    disabled = false,
+    readOnly = false,
+    required = false,
+
+    buttonStyle = "none",
+    browseButtonVariant = "bordered",
+
+    showDropzone = true,
+    previewLayout = "grid",
+    previewSize = "md",
+    showRemove = true,
+    showClearAll = true,
+
+    dropzoneTitle,
+    dropzoneHint,
+    browseLabel,
+    dropzoneIcon,
+
+    renderPreview,
+    renderDropzone,
+
+    previewListClassName,
+    previewListStyle,
+
+    value,
+    defaultValue,
+    onChange,
+    onAccepted,
+    onRejected,
+    onRemove,
+  } = props;
+
+  const generatedId = useId();
+  const inputId = id ?? generatedId;
+  const labelId = `${inputId}-label`;
+  const hintId = `${inputId}-hint`;
+
+  const {
+    files,
+    rejections,
+    isDragging,
+    open,
+    remove,
+    clear,
+    getRootProps,
+    getInputProps,
+  } = useMediaUpload({
+    value,
+    defaultValue,
+    onChange,
+    onAccepted,
+    onRejected,
+    onRemove,
+    accept,
+    multiple,
+    maxFiles,
+    maxSize,
+    disabled,
+    readOnly,
+  });
+
+  const hasFiles = files.length > 0;
+  const interactive = !disabled && !readOnly;
+
+  // Merge rejection messages with consumer-supplied errors so the field message
+  // slot stays the single source of validation feedback.
+  const mergedErrors = useMemo(() => {
+    if (rejections.length === 0) return errors;
+    const next = errors ? [...errors] : [];
+    rejections.forEach((r) => next.push(r.message));
+    return next;
+  }, [errors, rejections]);
+
+  const resolvedTitle =
+    dropzoneTitle ??
+    (multiple ? "Drop files here or browse" : "Drop a file here or browse");
+  const resolvedHint =
+    dropzoneHint ??
+    [
+      accept ? `Accepts ${accept}` : null,
+      maxSize ? `Up to ${formatBytes(maxSize)} per file` : null,
+      multiple && maxFiles ? `Max ${maxFiles} files` : null,
+    ]
+      .filter(Boolean)
+      .join(" • ");
+
+  const inputProps = getInputProps({
+    id: inputId,
+    name,
+    required,
+  });
+
+  // Mirrors the SelectButton pattern from common/select-button:
+  // outer wrapper holds the variant CSS-variable contracts, inner element
+  // is either a default-styled drop target (when "none") or a `<Button as="div"
+  // variant=X>` whose full paint becomes the dropzone surface.
+  const hasButtonStyle = buttonStyle !== "none";
+  const buttonToneClass = hasButtonStyle
+    ? sButton[`tone_${buttonStyle}`]
+    : undefined;
+
+  const browseButton = browseButtonVariant !== "none" && interactive && (
+    <Button
+      type="button"
+      variant={browseButtonVariant as ButtonVariant}
+      size="sm"
+      onClick={(e: MouseEvent) => {
+        e.stopPropagation();
+        open();
+      }}
+      disabled={disabled}
+    >
+      {browseLabel ?? "Browse files"}
+    </Button>
+  );
+
+  const dropzoneNode = showDropzone ? (
+    renderDropzone ? (
+      renderDropzone({
+        isDragging,
+        open,
+        disabled,
+        readOnly,
+        hasFiles,
+      })
+    ) : (
+      <div className={s.dropzone_inner}>
+        <Icon size="md" className={s.dropzone_icon} aria-hidden="true">
+          {dropzoneIcon ?? <IconUpload />}
+        </Icon>
+        <div className={s.dropzone_copy}>
+          <span className={s.dropzone_title}>{resolvedTitle}</span>
+          {resolvedHint && (
+            <span id={hintId} className={s.dropzone_hint}>
+              {resolvedHint}
+            </span>
+          )}
+        </div>
+        {browseButton}
+      </div>
+    )
+  ) : null;
+
+  // Dropzone is non-selectable when a single-file picker already has its slot
+  // filled - remove the existing file first to add a different one.
+  const dropzoneSelectable = interactive && (multiple || !hasFiles);
+
+  const hasLabelAction = hasFiles && showClearAll && interactive;
+
+  const showLabelRow = Boolean(label) || hasLabelAction;
+
+  const dropzoneClassName = hasButtonStyle
+    ? clsx(
+        s.dropzone,
+        s.dropzone_button_shell,
+        sCommon.field_full_width,
+        sCommon.field_button_variant,
+        sButton.input_focus,
+        buttonToneClass,
+        isDragging && s.dropzone_active,
+        !dropzoneSelectable && s.dropzone_disabled,
+      )
+    : clsx(
+        s.dropzone,
+        s.dropzone_default,
+        isDragging && s.dropzone_active,
+        !dropzoneSelectable && s.dropzone_disabled,
+      );
+
+  const dropzoneRootProps = getRootProps<HTMLDivElement>({
+    className: dropzoneClassName,
+    role: "button",
+    tabIndex: dropzoneSelectable ? 0 : -1,
+    "aria-disabled": !dropzoneSelectable,
+    "aria-labelledby": label ? labelId : undefined,
+    "aria-describedby": resolvedHint ? hintId : undefined,
+    onClick: dropzoneSelectable ? undefined : (e) => e.preventDefault(),
+  });
+
+  return (
+    <div className={clsx(sCommon.container, className)} style={style}>
+      {showLabelRow && (
+        <div
+          className={clsx(
+            sCommon.field_container,
+            layout !== "default" && sCommon[layout],
+            layout !== "default" &&
+              layoutDirection !== "default" &&
+              sCommon[layoutDirection],
+          )}
+        >
+          <div
+            className={clsx(
+              hasLabelAction && sCommon.label_row,
+              hasLabelAction && !label && sCommon.field_justify_end,
+            )}
+          >
+            {label && (
+              <label
+                id={labelId}
+                className={sCommon.label}
+                htmlFor={inputId}
+              >
+                {label}
+              </label>
+            )}
+            {hasLabelAction && (
+              <Button
+                type="button"
+                variant="ghost"
+                size="sm"
+                onClick={(e: MouseEvent) => {
+                  e.stopPropagation();
+                  clear();
+                }}
+                className={s.clear_all}
+              >
+                <Icon size="sm" aria-hidden="true">
+                  <IconX />
+                </Icon>
+                Clear all
+              </Button>
+            )}
+          </div>
+        </div>
+      )}
+
+      <input {...inputProps} />
+
+      {showDropzone && (
+        <div
+          className={clsx(
+            s.dropzone_wrapper,
+            hasButtonStyle && sCommon.field_wrapper_variant,
+            hasButtonStyle && buttonToneClass,
+          )}
+        >
+          {hasButtonStyle ? (
+            <Button
+              as="div"
+              variant={buttonStyle as ButtonVariant}
+              isActive={isDragging}
+              disabled={disabled}
+              {...dropzoneRootProps}
+            >
+              {dropzoneNode}
+            </Button>
+          ) : (
+            <div {...dropzoneRootProps}>{dropzoneNode}</div>
+          )}
+        </div>
+      )}
+
+      <FieldMessage errors={mergedErrors} info={info} />
+
+      {hasFiles && previewLayout !== "none" && (
+        <ul
+          className={clsx(
+            s.preview_list,
+            s[`preview_list_${previewSize}`],
+            previewLayout === "list" && s.preview_list_layout_list,
+            previewListClassName,
+          )}
+          style={previewListStyle}
+        >
+          {files.map((file) => (
+            <li key={file.id} className={s.preview_item_wrap}>
+              {renderPreview ? (
+                renderPreview(file, {
+                  remove: () => remove(file.id),
+                  disabled,
+                  readOnly,
+                  size: previewSize,
+                })
+              ) : (
+                <MediaPreview
+                  file={file}
+                  layout={previewLayout}
+                  size={previewSize}
+                  showRemove={showRemove}
+                  disabled={disabled}
+                  readOnly={readOnly}
+                  onRemove={() => remove(file.id)}
+                />
+              )}
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+};

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

@@ -0,0 +1,101 @@
+import { type FC, type MouseEvent } from "react";
+import clsx from "clsx";
+import { IconX } from "@tabler/icons-react";
+import { Icon } from "../../../primitives/icon/icon";
+import { Button } from "../../button/button";
+import type {
+  MediaFile,
+  MediaPreviewLayout,
+  MediaPreviewSize,
+} from "./types";
+import { formatBytes, previewKindOf } from "./utils";
+import { KIND_LABEL, iconForKind } from "./kind-icons";
+import s from "./media-input.module.css";
+
+export type MediaPreviewProps = {
+  file: MediaFile;
+  layout: MediaPreviewLayout;
+  size: MediaPreviewSize;
+  showRemove: boolean;
+  disabled: boolean;
+  readOnly: boolean;
+  onRemove: () => void;
+};
+
+export const MediaPreview: FC<MediaPreviewProps> = ({
+  file,
+  layout,
+  size,
+  showRemove,
+  disabled,
+  readOnly,
+  onRemove,
+}) => {
+  const kind = previewKindOf(file.file);
+  const showRemoveBtn = showRemove && !disabled && !readOnly;
+
+  const thumb =
+    kind === "image" && file.previewUrl ? (
+      <img
+        src={file.previewUrl}
+        alt={file.file.name}
+        className={s.preview_image}
+        draggable={false}
+      />
+    ) : kind === "video" && file.previewUrl ? (
+      <video
+        src={file.previewUrl}
+        className={s.preview_image}
+        muted
+        playsInline
+      />
+    ) : (
+      <div className={s.preview_thumb_fallback} aria-hidden="true">
+        <Icon size={layout === "list" ? "sm" : "md"}>{iconForKind(kind)}</Icon>
+      </div>
+    );
+
+  return (
+    <div
+      className={clsx(
+        s.preview_item,
+        layout === "list" ? s.preview_item_list : s[`preview_size_${size}`],
+      )}
+      data-status={file.status}
+      data-kind={kind}
+    >
+      <div className={s.preview_thumb}>{thumb}</div>
+
+      <div className={s.preview_meta}>
+        <span className={s.preview_name} title={file.file.name}>
+          {file.file.name}
+        </span>
+        <span className={s.preview_sub}>
+          <span>{KIND_LABEL[kind]}</span>
+          <span aria-hidden="true">·</span>
+          <span>{formatBytes(file.file.size)}</span>
+        </span>
+        {file.error && <span className={s.preview_error}>{file.error}</span>}
+      </div>
+
+      {showRemoveBtn && (
+        <Button
+          type="button"
+          variant="ghost"
+          size="sm"
+          layout="box"
+          className={s.preview_remove}
+          onClick={(e: MouseEvent) => {
+            e.stopPropagation();
+            onRemove();
+          }}
+          aria-label={`Remove ${file.file.name}`}
+        >
+          <Icon size="sm" aria-hidden="true">
+            <IconX />
+          </Icon>
+        </Button>
+      )}
+    </div>
+  );
+};

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

@@ -0,0 +1,129 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { ButtonVariant } from "../../button/button";
+import type { BaseInputFieldProps } from "../common/types";
+
+/** Standardized rejection reasons surfaced to consumers and the field message slot. */
+export const mediaRejectionCodes = [
+  "file-too-large",
+  "file-invalid-type",
+  "too-many-files",
+  "duplicate-file",
+] as const;
+export type MediaRejectionCode = (typeof mediaRejectionCodes)[number];
+
+export type MediaRejection = {
+  file: File;
+  code: MediaRejectionCode;
+  message: string;
+};
+
+/**
+ * Closed-set classification used to choose preview icons and labels. Always
+ * resolves to a value (never `undefined`) so renderers can rely on it.
+ */
+export const mediaKinds = [
+  "image",
+  "video",
+  "audio",
+  "pdf",
+  "document",
+  "spreadsheet",
+  "presentation",
+  "archive",
+  "code",
+  "text",
+  "font",
+  "other",
+] as const;
+export type MediaKind = (typeof mediaKinds)[number];
+
+/**
+ * Stable wrapper around a File. The `id` is generated once when the file is
+ * accepted and stays the same across re-renders so previews and DOM keys
+ * remain consistent. `previewUrl` is an `URL.createObjectURL` blob that the
+ * hook revokes automatically when the file is removed or replaced.
+ */
+export type MediaFile = {
+  id: string;
+  file: File;
+  previewUrl?: string;
+  status: "ready" | "uploading" | "uploaded" | "error";
+  progress?: number;
+  error?: string;
+};
+
+export const mediaPreviewLayouts = ["grid", "list", "none"] as const;
+export type MediaPreviewLayout = (typeof mediaPreviewLayouts)[number];
+
+export const mediaPreviewSizes = ["sm", "md", "lg"] as const;
+export type MediaPreviewSize = (typeof mediaPreviewSizes)[number];
+
+export type MediaInputProps = Omit<
+  BaseInputFieldProps,
+  "iconStart" | "iconEnd"
+> & {
+  /** Native `accept` string (e.g. `image/*`, `image/png,application/pdf`). */
+  accept?: string;
+  /** Allow selecting multiple files. Default: `false`. */
+  multiple?: boolean;
+  /** Hard cap on accepted files (only enforced when `multiple`). */
+  maxFiles?: number;
+  /** Per-file size cap in bytes. */
+  maxSize?: number;
+
+  /**
+   * Variant for the inner Browse button. Independent from `buttonStyle`
+   * (which paints the dropzone surface). Set to `"none"` to hide the
+   * Browse button entirely. Default: `"bordered"`.
+   */
+  browseButtonVariant?: ButtonVariant | "none";
+
+  /** Show the dashed dropzone target. Default: `true`. */
+  showDropzone?: boolean;
+  /** How accepted files are rendered. `"none"` hides previews entirely. */
+  previewLayout?: MediaPreviewLayout;
+  /** Tile size for grid previews. Default: `"md"`. */
+  previewSize?: MediaPreviewSize;
+  /** Show the per-file remove (X) action on previews. Default: `true`. */
+  showRemove?: boolean;
+  /** Show a “Clear all” action when at least one file is selected. */
+  showClearAll?: boolean;
+
+  /** Copy slots - render-prop friendly so consumers can localize freely. */
+  dropzoneTitle?: ReactNode;
+  dropzoneHint?: ReactNode;
+  browseLabel?: ReactNode;
+  /** Replaces the icon shown inside the dropzone. */
+  dropzoneIcon?: ReactNode;
+
+  /** Render override for an individual preview tile. */
+  renderPreview?: (file: MediaFile, ctx: MediaPreviewContext) => ReactNode;
+  /** Render override for the entire dropzone body (keep wrapper styling). */
+  renderDropzone?: (ctx: MediaDropzoneContext) => ReactNode;
+
+  /** Pass-through styling for the inner preview list/grid. */
+  previewListClassName?: string;
+  previewListStyle?: CSSProperties;
+
+  value?: MediaFile[];
+  defaultValue?: MediaFile[] | File[];
+  onChange?: (files: MediaFile[]) => void;
+  onRemove?: (file: MediaFile) => void;
+  onAccepted?: (files: MediaFile[]) => void;
+  onRejected?: (rejections: MediaRejection[]) => void;
+};
+
+export type MediaPreviewContext = {
+  remove: () => void;
+  disabled: boolean;
+  readOnly: boolean;
+  size: MediaPreviewSize;
+};
+
+export type MediaDropzoneContext = {
+  isDragging: boolean;
+  open: () => void;
+  disabled: boolean;
+  readOnly: boolean;
+  hasFiles: boolean;
+};