@frontlit/media-uploader 0.1.0-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 FrontLit
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,141 @@
1
+ # @frontlit/media-uploader
2
+
3
+ A reusable media and file upload dialog with library and Unsplash tabs for React. Framework-agnostic: it depends only on `react` and `react-dom`.
4
+
5
+ Hosts provide their own storage adapters (or backend endpoints) via `MediaUploaderProvider`, and can invoke `MediaUploadDialog` or `ImageUploadDialog` anywhere in their UI.
6
+
7
+ ## Installation
8
+
9
+ ```sh
10
+ npm i @frontlit/media-uploader
11
+ # or
12
+ pnpm add @frontlit/media-uploader
13
+ # or
14
+ bun add @frontlit/media-uploader
15
+ ```
16
+
17
+ Peer dependencies: `react` and `react-dom` (^18 or ^19).
18
+
19
+ ### CSS
20
+
21
+ Import the compiled stylesheet. It includes the required layout, dialog, tab, and responsive utilities:
22
+
23
+ ```ts
24
+ import "@frontlit/media-uploader/styles.css";
25
+ ```
26
+
27
+ If you already run Tailwind CSS v4 in your host application, you can scan the package instead:
28
+
29
+ ```css
30
+ @source "./node_modules/@frontlit/media-uploader";
31
+ ```
32
+
33
+ ## Usage
34
+
35
+ ### 1. Setup Providers with Adapters
36
+
37
+ Wrap your application (or a subtree) with `MediaUploaderProvider` to wire up file uploading, library browsing, and Unsplash search:
38
+
39
+ ```tsx
40
+ import { MediaUploaderProvider } from "@frontlit/media-uploader";
41
+
42
+ function App({ children }: { children: React.ReactNode }) {
43
+ return (
44
+ <MediaUploaderProvider
45
+ uploadMedia={async (file, meta) => {
46
+ const formData = new FormData();
47
+ formData.append("file", file);
48
+ if (meta.alt) formData.append("alt", meta.alt);
49
+ if (meta.title) formData.append("title", meta.title);
50
+
51
+ const res = await fetch("/api/media/upload", {
52
+ method: "POST",
53
+ body: formData,
54
+ });
55
+ return res.json();
56
+ }}
57
+ listMedia={async (query) => {
58
+ const res = await fetch(`/api/media?q=${encodeURIComponent(query)}`);
59
+ return res.json();
60
+ }}
61
+ searchUnsplash={async (query) => {
62
+ const res = await fetch(`/api/unsplash?q=${encodeURIComponent(query ?? "")}`);
63
+ return res.json();
64
+ }}
65
+ >
66
+ {children}
67
+ </MediaUploaderProvider>
68
+ );
69
+ }
70
+ ```
71
+
72
+ ### 2. General Media Dialog (`MediaUploadDialog`)
73
+
74
+ Use `MediaUploadDialog` to select any file type (images, videos, documents, archives, etc.):
75
+
76
+ ```tsx
77
+ import { useState } from "react";
78
+ import { MediaUploadDialog, type SelectedMedia } from "@frontlit/media-uploader";
79
+ import "@frontlit/media-uploader/styles.css";
80
+
81
+ function MediaPicker() {
82
+ const [open, setOpen] = useState(false);
83
+
84
+ function handleSelect(media: SelectedMedia) {
85
+ console.log("Selected file:", media.src, media.fileName, media.mimeType);
86
+ setOpen(false);
87
+ }
88
+
89
+ return (
90
+ <MediaUploadDialog
91
+ open={open}
92
+ onOpenChange={setOpen}
93
+ title="Upload documents"
94
+ acceptedTypes={["application/pdf", "image/*"]}
95
+ maxUploadBytes={50 * 1024 * 1024} // 50MB
96
+ onSelect={handleSelect}
97
+ >
98
+ <button onClick={() => setOpen(true)}>Choose File</button>
99
+ </MediaUploadDialog>
100
+ );
101
+ }
102
+ ```
103
+
104
+ ### 3. Image-Specific Dialog (`ImageUploadDialog`)
105
+
106
+ `ImageUploadDialog` is a pre-configured convenience component for image selection with alt text metadata support:
107
+
108
+ ```tsx
109
+ import { useState } from "react";
110
+ import { ImageUploadDialog, type SelectedImage } from "@frontlit/media-uploader";
111
+
112
+ function AvatarPicker() {
113
+ const [open, setOpen] = useState(false);
114
+
115
+ return (
116
+ <ImageUploadDialog
117
+ open={open}
118
+ onOpenChange={setOpen}
119
+ title="Select avatar"
120
+ onSelect={(img: SelectedImage) => {
121
+ console.log("Image selected:", img.src, img.alt);
122
+ }}
123
+ >
124
+ <button onClick={() => setOpen(true)}>Change Avatar</button>
125
+ </ImageUploadDialog>
126
+ );
127
+ }
128
+ ```
129
+
130
+ ## What's inside
131
+
132
+ - `MediaUploadDialog` — General-purpose file & media dialog with drag-and-drop upload, library browser, and Unsplash tabs.
133
+ - `ImageUploadDialog` — Specialized dialog pre-configured for images and alt-text editing.
134
+ - `MediaUploaderProvider` / `ImageUploaderProvider` — React Context providers for storage and search adapters.
135
+ - `useMediaUploaderAdapters` / `useImageUploaderAdapters` — Hook to access configured adapters within dialogs.
136
+ - `formatFileSize` — Formats byte count into human-readable strings (`KB`, `MB`, `GB`).
137
+ - `matchesMime`, `allowsImages`, `getMimeCategory` — MIME type matching, categorizing, and filtering utilities.
138
+
139
+ ## License
140
+
141
+ MIT
@@ -0,0 +1,99 @@
1
+ import * as react from 'react';
2
+ import { ReactNode } from 'react';
3
+
4
+ type LibraryMedia = {
5
+ id: string;
6
+ url: string;
7
+ thumbnailUrl?: string | null;
8
+ alt?: string | null;
9
+ fileName?: string | null;
10
+ mimeType?: string | null;
11
+ byteSize?: number | null;
12
+ title?: string | null;
13
+ };
14
+ /** Backward-compatible alias for LibraryMedia. */
15
+ type LibraryImage = LibraryMedia;
16
+ type SelectedMedia<TMedia extends LibraryMedia = LibraryMedia> = {
17
+ src: string;
18
+ alt?: string;
19
+ fileName?: string;
20
+ mimeType?: string;
21
+ byteSize?: number;
22
+ media?: TMedia;
23
+ };
24
+ /** Backward-compatible alias for SelectedMedia. */
25
+ type SelectedImage<TMedia extends LibraryImage = LibraryImage> = SelectedMedia<TMedia>;
26
+ type UnsplashPhoto = {
27
+ id: string;
28
+ url: string;
29
+ thumbUrl: string;
30
+ alt?: string;
31
+ photographer?: string;
32
+ };
33
+ type UnsplashSearchResult = {
34
+ configured: boolean;
35
+ items: UnsplashPhoto[];
36
+ };
37
+ type MediaUploadMeta = {
38
+ alt?: string;
39
+ fileName?: string;
40
+ title?: string;
41
+ mimeType?: string;
42
+ };
43
+ type UploadMediaFn<TMedia extends LibraryMedia = LibraryMedia> = (file: File, meta: MediaUploadMeta) => Promise<TMedia>;
44
+ type ListMediaFn<TMedia extends LibraryMedia = LibraryMedia> = (query: string) => Promise<TMedia[]>;
45
+ type SearchUnsplashFn = (query?: string) => Promise<UnsplashSearchResult>;
46
+ type MediaUploaderAdapters<TMedia extends LibraryMedia = LibraryMedia> = {
47
+ uploadMedia?: UploadMediaFn<TMedia>;
48
+ listMedia?: ListMediaFn<TMedia>;
49
+ searchUnsplash?: SearchUnsplashFn;
50
+ isUploading?: boolean;
51
+ uploadProgress?: number;
52
+ cancelUpload?: () => void;
53
+ };
54
+ /** Backward-compatible alias for MediaUploaderAdapters. */
55
+ type ImageUploaderAdapters<TMedia extends LibraryImage = LibraryImage> = MediaUploaderAdapters<TMedia>;
56
+
57
+ type MediaUploadDialogProps<TMedia extends LibraryMedia = LibraryMedia> = Partial<MediaUploaderAdapters<TMedia>> & {
58
+ open?: boolean;
59
+ onOpenChange?: (open: boolean) => void;
60
+ onSelect: (media: SelectedMedia<TMedia>) => void;
61
+ title?: string;
62
+ description?: string;
63
+ children?: ReactNode;
64
+ disabled?: boolean;
65
+ allowUnsplash?: boolean;
66
+ allowExistingMedia?: boolean;
67
+ acceptedTypes?: string[];
68
+ maxUploadBytes?: number;
69
+ validateFile?: (file: File) => string | null | Promise<string | null>;
70
+ defaultTab?: "upload" | "media" | "unsplash";
71
+ metadataMode?: "auto" | "alt" | "title" | "none";
72
+ };
73
+ declare function MediaUploadDialog<TMedia extends LibraryMedia = LibraryMedia>({ open, onOpenChange, onSelect, title, description, children, disabled, allowUnsplash, allowExistingMedia, acceptedTypes, maxUploadBytes, validateFile: customValidateFile, defaultTab, metadataMode, uploadMedia: uploadMediaProp, listMedia: listMediaProp, searchUnsplash: searchUnsplashProp, isUploading: isUploadingProp, uploadProgress: uploadProgressProp, cancelUpload: cancelUploadProp, }: MediaUploadDialogProps<TMedia>): react.JSX.Element;
74
+
75
+ type ImageUploadDialogProps<TMedia extends LibraryImage = LibraryImage> = MediaUploadDialogProps<TMedia>;
76
+ /**
77
+ * Specialized image uploader dialog.
78
+ * Pre-configured with image-only MIME filters, image alt-text metadata mode, and image descriptions.
79
+ * Drop-in backward-compatible component.
80
+ */
81
+ declare function ImageUploadDialog<TMedia extends LibraryImage = LibraryImage>({ acceptedTypes, maxUploadBytes, title, metadataMode, onSelect, ...props }: ImageUploadDialogProps<TMedia>): react.JSX.Element;
82
+
83
+ declare function MediaUploaderProvider<TMedia extends LibraryMedia = LibraryMedia>({ children, ...adapters }: MediaUploaderAdapters<TMedia> & {
84
+ children: ReactNode;
85
+ }): react.JSX.Element;
86
+ /** Backward-compatible alias for MediaUploaderProvider. */
87
+ declare const ImageUploaderProvider: typeof MediaUploaderProvider;
88
+ declare function useMediaUploaderAdapters<TMedia extends LibraryMedia = LibraryMedia>(overrides?: Partial<MediaUploaderAdapters<TMedia>>): Required<Pick<MediaUploaderAdapters<TMedia>, "uploadMedia">> & Omit<MediaUploaderAdapters<TMedia>, "uploadMedia">;
89
+ /** Backward-compatible alias for useMediaUploaderAdapters. */
90
+ declare const useImageUploaderAdapters: typeof useMediaUploaderAdapters;
91
+
92
+ declare function formatFileSize(bytes: number): string;
93
+
94
+ type MimeCategory = "image" | "video" | "audio" | "pdf" | "archive" | "document" | "other";
95
+ declare function getMimeCategory(mimeType?: string | null, fileName?: string | null): MimeCategory;
96
+ declare function matchesMime(fileType: string, fileName?: string, acceptedTypes?: string[]): boolean;
97
+ declare function allowsImages(acceptedTypes?: string[]): boolean;
98
+
99
+ export { ImageUploadDialog, type ImageUploadDialogProps, type ImageUploaderAdapters, ImageUploaderProvider, type LibraryImage, type LibraryMedia, type ListMediaFn, MediaUploadDialog, type MediaUploadDialogProps, type MediaUploadMeta, type MediaUploaderAdapters, MediaUploaderProvider, type MimeCategory, type SearchUnsplashFn, type SelectedImage, type SelectedMedia, type UnsplashPhoto, type UnsplashSearchResult, type UploadMediaFn, allowsImages, formatFileSize, getMimeCategory, matchesMime, useImageUploaderAdapters, useMediaUploaderAdapters };