@fluxfiles/react 1.0.0

package/dist/index.mjs

@@ -0,0 +1,276 @@
+// src/FluxFiles.tsx
+import { forwardRef, useImperativeHandle } from "react";
+
+// src/useFluxFiles.ts
+import { useCallback, useEffect, useRef, useState } from "react";
+var SOURCE = "fluxfiles";
+var VERSION = 1;
+function uid() {
+  return "ff-" + Math.random().toString(36).slice(2, 11) + Date.now().toString(36);
+}
+function useFluxFiles(options) {
+  const iframeElRef = useRef(null);
+  const [ready, setReady] = useState(false);
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const endpoint = (options.endpoint || "").replace(/\/+$/, "");
+  const iframeSrc = endpoint + "/public/index.html";
+  const post = useCallback((type, payload = {}) => {
+    const el = iframeElRef.current;
+    if (!el?.contentWindow) return;
+    el.contentWindow.postMessage(
+      { source: SOURCE, type, v: VERSION, id: uid(), payload },
+      "*"
+    );
+  }, []);
+  const sendConfig = useCallback(() => {
+    const opts = optionsRef.current;
+    post("FM_CONFIG", {
+      disk: opts.disk || "local",
+      token: opts.token || "",
+      mode: opts.mode || "picker",
+      allowedTypes: opts.allowedTypes || null,
+      maxSize: opts.maxSize || null,
+      endpoint: opts.endpoint || "",
+      locale: opts.locale || null
+    });
+  }, [post]);
+  useEffect(() => {
+    function onMessage(e) {
+      const msg = e.data;
+      if (!msg || msg.source !== SOURCE) return;
+      const opts = optionsRef.current;
+      switch (msg.type) {
+        case "FM_READY":
+          setReady(true);
+          sendConfig();
+          opts.onReady?.();
+          break;
+        case "FM_SELECT":
+          opts.onSelect?.(msg.payload);
+          break;
+        case "FM_EVENT":
+          opts.onEvent?.(msg.payload);
+          break;
+        case "FM_CLOSE":
+          opts.onClose?.();
+          break;
+      }
+    }
+    window.addEventListener("message", onMessage);
+    return () => {
+      window.removeEventListener("message", onMessage);
+    };
+  }, [sendConfig]);
+  useEffect(() => {
+    if (ready) {
+      sendConfig();
+    }
+  }, [options.token, options.disk, options.mode, options.locale, ready, sendConfig]);
+  const command = useCallback(
+    (action, data = {}) => {
+      post("FM_COMMAND", { action, ...data });
+    },
+    [post]
+  );
+  const navigate = useCallback((path) => command("navigate", { path }), [command]);
+  const setDisk = useCallback((disk) => command("setDisk", { disk }), [command]);
+  const refresh = useCallback(() => command("refresh"), [command]);
+  const search = useCallback((q) => command("search", { q }), [command]);
+  const crossCopy = useCallback((dstDisk, dstPath) => command("crossCopy", { dst_disk: dstDisk, dst_path: dstPath || "" }), [command]);
+  const crossMove = useCallback((dstDisk, dstPath) => command("crossMove", { dst_disk: dstDisk, dst_path: dstPath || "" }), [command]);
+  const crop = useCallback((x, y, width, height, savePath) => command("crop", { x, y, width, height, save_path: savePath || "" }), [command]);
+  const aiTag = useCallback(() => command("aiTag"), [command]);
+  const iframeRef = useCallback((el) => {
+    iframeElRef.current = el;
+    if (!el) {
+      setReady(false);
+    }
+  }, []);
+  return {
+    iframeRef,
+    iframeSrc,
+    ready,
+    command,
+    navigate,
+    setDisk,
+    refresh,
+    search,
+    crossCopy,
+    crossMove,
+    crop,
+    aiTag
+  };
+}
+
+// src/FluxFiles.tsx
+import { jsx } from "react/jsx-runtime";
+var FluxFiles = forwardRef(
+  function FluxFiles2(props, ref) {
+    const {
+      endpoint,
+      token,
+      disk,
+      mode,
+      allowedTypes,
+      maxSize,
+      width = "100%",
+      height = "600px",
+      className,
+      style,
+      onSelect,
+      onClose,
+      onReady,
+      onEvent
+    } = props;
+    const handle = useFluxFiles({
+      endpoint,
+      token,
+      disk,
+      mode,
+      allowedTypes,
+      maxSize,
+      onSelect,
+      onClose,
+      onReady,
+      onEvent
+    });
+    useImperativeHandle(ref, () => ({
+      command: handle.command,
+      navigate: handle.navigate,
+      setDisk: handle.setDisk,
+      refresh: handle.refresh,
+      search: handle.search,
+      crossCopy: handle.crossCopy,
+      crossMove: handle.crossMove,
+      crop: handle.crop,
+      aiTag: handle.aiTag,
+      ready: handle.ready
+    }), [handle]);
+    const containerStyle = {
+      width: typeof width === "number" ? `${width}px` : width,
+      height: typeof height === "number" ? `${height}px` : height,
+      ...style
+    };
+    return /* @__PURE__ */ jsx("div", { className, style: containerStyle, children: /* @__PURE__ */ jsx(
+      "iframe",
+      {
+        ref: handle.iframeRef,
+        src: handle.iframeSrc,
+        style: { width: "100%", height: "100%", border: "none" },
+        allow: "clipboard-write",
+        title: "FluxFiles File Manager"
+      }
+    ) });
+  }
+);
+
+// src/FluxFilesModal.tsx
+import { useCallback as useCallback2, useEffect as useEffect2 } from "react";
+import { jsx as jsx2 } from "react/jsx-runtime";
+var defaultOverlayStyle = {
+  position: "fixed",
+  inset: 0,
+  background: "rgba(0, 0, 0, 0.5)",
+  zIndex: 99999,
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "center"
+};
+var defaultModalStyle = {
+  width: "90vw",
+  maxWidth: "1200px",
+  height: "85vh",
+  background: "#fff",
+  borderRadius: "8px",
+  overflow: "hidden",
+  boxShadow: "0 25px 50px rgba(0, 0, 0, 0.25)"
+};
+function FluxFilesModal({
+  open,
+  endpoint,
+  token,
+  disk,
+  mode = "picker",
+  allowedTypes,
+  maxSize,
+  onSelect,
+  onClose,
+  onReady,
+  onEvent,
+  overlayClassName,
+  modalClassName
+}) {
+  const handle = useFluxFiles({
+    endpoint,
+    token,
+    disk,
+    mode,
+    allowedTypes,
+    maxSize,
+    onSelect,
+    onClose,
+    onReady,
+    onEvent
+  });
+  useEffect2(() => {
+    if (!open) return;
+    function onKeyDown(e) {
+      if (e.key === "Escape") {
+        onClose?.();
+      }
+    }
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, [open, onClose]);
+  useEffect2(() => {
+    if (!open) return;
+    const prev = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    return () => {
+      document.body.style.overflow = prev;
+    };
+  }, [open]);
+  const handleOverlayClick = useCallback2(
+    (e) => {
+      if (e.target === e.currentTarget) {
+        onClose?.();
+      }
+    },
+    [onClose]
+  );
+  if (!open) return null;
+  return /* @__PURE__ */ jsx2(
+    "div",
+    {
+      className: overlayClassName,
+      style: overlayClassName ? void 0 : defaultOverlayStyle,
+      onClick: handleOverlayClick,
+      role: "dialog",
+      "aria-modal": "true",
+      "aria-label": "FluxFiles File Manager",
+      children: /* @__PURE__ */ jsx2(
+        "div",
+        {
+          className: modalClassName,
+          style: modalClassName ? void 0 : defaultModalStyle,
+          children: /* @__PURE__ */ jsx2(
+            "iframe",
+            {
+              ref: handle.iframeRef,
+              src: handle.iframeSrc,
+              style: { width: "100%", height: "100%", border: "none" },
+              allow: "clipboard-write",
+              title: "FluxFiles File Manager"
+            }
+          )
+        }
+      )
+    }
+  );
+}
+export {
+  FluxFiles,
+  FluxFilesModal,
+  useFluxFiles
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@fluxfiles/react",
+  "version": "1.0.0",
+  "description": "React components and hooks for FluxFiles file manager",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "author": "thai-pc",
+  "homepage": "https://github.com/thai-pc/fluxfiles#react",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thai-pc/fluxfiles.git",
+    "directory": "adapters/react"
+  },
+  "bugs": {
+    "url": "https://github.com/thai-pc/fluxfiles/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "fluxfiles",
+    "file-manager",
+    "react",
+    "s3",
+    "r2",
+    "upload"
+  ]
+}

package/src/FluxFiles.tsx

@@ -0,0 +1,91 @@
+import React, { forwardRef, useImperativeHandle } from 'react';
+import type { FluxFilesProps, FluxFilesHandle } from './types';
+import { useFluxFiles } from './useFluxFiles';
+
+/**
+ * Embedded FluxFiles file manager component.
+ *
+ * Renders an iframe inside a container div. Use `ref` to access command methods.
+ *
+ * @example
+ * ```tsx
+ * const ref = useRef<FluxFilesHandle>(null);
+ *
+ * <FluxFiles
+ *   ref={ref}
+ *   endpoint="https://files.example.com"
+ *   token={jwt}
+ *   disk="local"
+ *   onSelect={(file) => console.log(file)}
+ *   height="600px"
+ * />
+ *
+ * // Programmatic control:
+ * ref.current?.navigate('/uploads');
+ * ref.current?.refresh();
+ * ```
+ */
+export const FluxFiles = forwardRef<FluxFilesHandle, FluxFilesProps>(
+  function FluxFiles(props, ref) {
+    const {
+      endpoint,
+      token,
+      disk,
+      mode,
+      allowedTypes,
+      maxSize,
+      width = '100%',
+      height = '600px',
+      className,
+      style,
+      onSelect,
+      onClose,
+      onReady,
+      onEvent,
+    } = props;
+
+    const handle = useFluxFiles({
+      endpoint,
+      token,
+      disk,
+      mode,
+      allowedTypes,
+      maxSize,
+      onSelect,
+      onClose,
+      onReady,
+      onEvent,
+    });
+
+    useImperativeHandle(ref, () => ({
+      command: handle.command,
+      navigate: handle.navigate,
+      setDisk: handle.setDisk,
+      refresh: handle.refresh,
+      search: handle.search,
+      crossCopy: handle.crossCopy,
+      crossMove: handle.crossMove,
+      crop: handle.crop,
+      aiTag: handle.aiTag,
+      ready: handle.ready,
+    }), [handle]);
+
+    const containerStyle: React.CSSProperties = {
+      width: typeof width === 'number' ? `${width}px` : width,
+      height: typeof height === 'number' ? `${height}px` : height,
+      ...style,
+    };
+
+    return (
+      <div className={className} style={containerStyle}>
+        <iframe
+          ref={handle.iframeRef}
+          src={handle.iframeSrc}
+          style={{ width: '100%', height: '100%', border: 'none' }}
+          allow="clipboard-write"
+          title="FluxFiles File Manager"
+        />
+      </div>
+    );
+  }
+);

package/src/FluxFilesModal.tsx

@@ -0,0 +1,134 @@
+import React, { useCallback, useEffect } from 'react';
+import type { FluxFilesModalProps } from './types';
+import { useFluxFiles } from './useFluxFiles';
+
+const defaultOverlayStyle: React.CSSProperties = {
+  position: 'fixed',
+  inset: 0,
+  background: 'rgba(0, 0, 0, 0.5)',
+  zIndex: 99999,
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+};
+
+const defaultModalStyle: React.CSSProperties = {
+  width: '90vw',
+  maxWidth: '1200px',
+  height: '85vh',
+  background: '#fff',
+  borderRadius: '8px',
+  overflow: 'hidden',
+  boxShadow: '0 25px 50px rgba(0, 0, 0, 0.25)',
+};
+
+/**
+ * Modal wrapper for FluxFiles.
+ *
+ * Renders a fullscreen overlay with the file manager when `open` is true.
+ *
+ * @example
+ * ```tsx
+ * const [open, setOpen] = useState(false);
+ *
+ * <button onClick={() => setOpen(true)}>Pick file</button>
+ *
+ * <FluxFilesModal
+ *   open={open}
+ *   endpoint="https://files.example.com"
+ *   token={jwt}
+ *   onSelect={(file) => {
+ *     console.log(file);
+ *     setOpen(false);
+ *   }}
+ *   onClose={() => setOpen(false)}
+ * />
+ * ```
+ */
+export function FluxFilesModal({
+  open,
+  endpoint,
+  token,
+  disk,
+  mode = 'picker',
+  allowedTypes,
+  maxSize,
+  onSelect,
+  onClose,
+  onReady,
+  onEvent,
+  overlayClassName,
+  modalClassName,
+}: FluxFilesModalProps) {
+  const handle = useFluxFiles({
+    endpoint,
+    token,
+    disk,
+    mode,
+    allowedTypes,
+    maxSize,
+    onSelect,
+    onClose,
+    onReady,
+    onEvent,
+  });
+
+  // Close on escape
+  useEffect(() => {
+    if (!open) return;
+
+    function onKeyDown(e: KeyboardEvent) {
+      if (e.key === 'Escape') {
+        onClose?.();
+      }
+    }
+
+    document.addEventListener('keydown', onKeyDown);
+    return () => document.removeEventListener('keydown', onKeyDown);
+  }, [open, onClose]);
+
+  // Prevent body scroll when open
+  useEffect(() => {
+    if (!open) return;
+    const prev = document.body.style.overflow;
+    document.body.style.overflow = 'hidden';
+    return () => {
+      document.body.style.overflow = prev;
+    };
+  }, [open]);
+
+  const handleOverlayClick = useCallback(
+    (e: React.MouseEvent) => {
+      if (e.target === e.currentTarget) {
+        onClose?.();
+      }
+    },
+    [onClose]
+  );
+
+  if (!open) return null;
+
+  return (
+    <div
+      className={overlayClassName}
+      style={overlayClassName ? undefined : defaultOverlayStyle}
+      onClick={handleOverlayClick}
+      role="dialog"
+      aria-modal="true"
+      aria-label="FluxFiles File Manager"
+    >
+      <div
+        className={modalClassName}
+        style={modalClassName ? undefined : defaultModalStyle}
+      >
+        <iframe
+          ref={handle.iframeRef}
+          src={handle.iframeSrc}
+          style={{ width: '100%', height: '100%', border: 'none' }}
+          allow="clipboard-write"
+          title="FluxFiles File Manager"
+        />
+      </div>
+    </div>
+  );
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+// Components
+export { FluxFiles } from './FluxFiles';
+export { FluxFilesModal } from './FluxFilesModal';
+
+// Hook
+export { useFluxFiles } from './useFluxFiles';
+
+// Types
+export type {
+  FluxFile,
+  FluxEvent,
+  FluxFilesConfig,
+  FluxFilesProps,
+  FluxFilesModalProps,
+  FluxFilesHandle,
+  FluxCommand,
+} from './types';

package/src/types.ts

@@ -0,0 +1,124 @@
+/** A file or directory entry returned by FluxFiles. */
+export interface FluxFile {
+  path: string;
+  basename: string;
+  type: 'file' | 'dir';
+  size?: number;
+  mime?: string;
+  modified?: number;
+  url?: string;
+  title?: string;
+  alt_text?: string;
+  caption?: string;
+  hash?: string;
+  variants?: Record<string, string>;
+}
+
+/** Event payload dispatched by the file manager iframe. */
+export interface FluxEvent {
+  action: string;
+  disk?: string;
+  path?: string;
+  file?: FluxFile;
+  [key: string]: unknown;
+}
+
+/** Configuration for the FluxFiles component. */
+export interface FluxFilesConfig {
+  /** Base URL of the FluxFiles API. */
+  endpoint: string;
+  /** JWT token for authentication. */
+  token: string;
+  /** Storage disk to use. */
+  disk?: string;
+  /** Display mode: "picker" selects a file, "browser" is free-browse. */
+  mode?: 'picker' | 'browser';
+  /** Filter displayed file types (e.g. ["image/*", ".pdf"]). */
+  allowedTypes?: string[] | null;
+  /** Max file size filter in bytes. */
+  maxSize?: number | null;
+  /** Locale code (e.g. "en", "vi", "ar"). */
+  locale?: string | null;
+}
+
+/** Props for the <FluxFiles /> embedded component. */
+export interface FluxFilesProps extends FluxFilesConfig {
+  /** Container width. */
+  width?: string | number;
+  /** Container height. */
+  height?: string | number;
+  /** CSS class for the wrapper div. */
+  className?: string;
+  /** Inline styles for the wrapper div. */
+  style?: React.CSSProperties;
+  /** Fired when a file is selected (picker mode). */
+  onSelect?: (file: FluxFile) => void;
+  /** Fired when the file manager signals a close. */
+  onClose?: () => void;
+  /** Fired when the iframe is ready. */
+  onReady?: () => void;
+  /** Fired on file operations (upload, delete, move, etc.). */
+  onEvent?: (event: FluxEvent) => void;
+}
+
+/** Props for the <FluxFilesModal /> component. */
+export interface FluxFilesModalProps extends FluxFilesConfig {
+  /** Whether the modal is open. */
+  open: boolean;
+  /** Fired when a file is selected. */
+  onSelect?: (file: FluxFile) => void;
+  /** Fired when the modal should close (overlay click, escape, or FM_CLOSE). */
+  onClose?: () => void;
+  /** Fired when the iframe is ready. */
+  onReady?: () => void;
+  /** Fired on file operations. */
+  onEvent?: (event: FluxEvent) => void;
+  /** CSS class for the overlay. */
+  overlayClassName?: string;
+  /** CSS class for the modal content. */
+  modalClassName?: string;
+}
+
+/** Commands that can be sent to the file manager. */
+export type FluxCommand =
+  | { action: 'navigate'; path: string }
+  | { action: 'setDisk'; disk: string }
+  | { action: 'refresh' }
+  | { action: 'search'; q: string }
+  | { action: 'crossCopy'; dst_disk: string; dst_path?: string }
+  | { action: 'crossMove'; dst_disk: string; dst_path?: string }
+  | { action: 'crop'; x: number; y: number; width: number; height: number; save_path?: string }
+  | { action: 'aiTag' };
+
+/** Return type of useFluxFiles hook. */
+export interface FluxFilesHandle {
+  /** Send a command to the iframe. */
+  command: (action: string, data?: Record<string, unknown>) => void;
+  /** Navigate to a path. */
+  navigate: (path: string) => void;
+  /** Switch disk. */
+  setDisk: (disk: string) => void;
+  /** Refresh the file list. */
+  refresh: () => void;
+  /** Search files. */
+  search: (q: string) => void;
+  /** Copy selected files to another disk. */
+  crossCopy: (dstDisk: string, dstPath?: string) => void;
+  /** Move selected files to another disk. */
+  crossMove: (dstDisk: string, dstPath?: string) => void;
+  /** Crop the currently selected image. */
+  crop: (x: number, y: number, width: number, height: number, savePath?: string) => void;
+  /** Trigger AI tagging on the currently selected image. */
+  aiTag: () => void;
+  /** Whether the iframe has reported ready. */
+  ready: boolean;
+}
+
+/** Internal postMessage protocol types. */
+export interface FluxMessage {
+  source: 'fluxfiles';
+  type: 'FM_READY' | 'FM_SELECT' | 'FM_EVENT' | 'FM_CLOSE' | 'FM_CONFIG' | 'FM_COMMAND';
+  v: number;
+  id: string;
+  payload: Record<string, unknown>;
+}