@btst/stack 2.8.0 → 2.9.0

package/dist/plugins/media/client/hooks/index.d.mts

@@ -0,0 +1,53 @@
+import * as _tanstack_react_query from '@tanstack/react-query';
+import { A as AssetListParams } from '../../../../shared/stack.C7vfOBmO.mjs';
+import { S as SerializedAsset, a as SerializedFolder } from '../../../../shared/stack.CLcnSF_b.mjs';
+import '@btst/db';
+
+/**
+ * Infinite-scroll list of assets, optionally filtered by folder / MIME type / search.
+ */
+declare function useAssets(params?: AssetListParams): _tanstack_react_query.UseInfiniteQueryResult<_tanstack_react_query.InfiniteData<{
+    items: SerializedAsset[];
+    total: number;
+    limit?: number;
+    offset?: number;
+}, unknown>, Error>;
+/**
+ * List of folders, optionally filtered by parentId.
+ * Pass `null` for root-level folders, `undefined` for all folders.
+ */
+declare function useFolders(parentId?: string | null): _tanstack_react_query.UseQueryResult<SerializedFolder[], Error>;
+/**
+ * Upload an asset — adapter-aware. Handles direct, S3, and Vercel Blob flows.
+ */
+declare function useUploadAsset(): _tanstack_react_query.UseMutationResult<SerializedAsset, Error, {
+    file: File;
+    folderId?: string;
+}, unknown>;
+/**
+ * Register an asset URL directly (for when the URL already exists).
+ */
+declare function useRegisterAsset(): _tanstack_react_query.UseMutationResult<SerializedAsset, Error, {
+    url: string;
+    filename: string;
+    mimeType?: string;
+    size?: number;
+    folderId?: string;
+}, unknown>;
+/**
+ * Delete an asset by ID.
+ */
+declare function useDeleteAsset(): _tanstack_react_query.UseMutationResult<void, Error, string, unknown>;
+/**
+ * Create a new folder.
+ */
+declare function useCreateFolder(): _tanstack_react_query.UseMutationResult<SerializedFolder, Error, {
+    name: string;
+    parentId?: string;
+}, unknown>;
+/**
+ * Delete a folder by ID.
+ */
+declare function useDeleteFolder(): _tanstack_react_query.UseMutationResult<void, Error, string, unknown>;
+
+export { useAssets, useCreateFolder, useDeleteAsset, useDeleteFolder, useFolders, useRegisterAsset, useUploadAsset };

package/dist/plugins/media/client/hooks/index.d.ts

@@ -0,0 +1,53 @@
+import * as _tanstack_react_query from '@tanstack/react-query';
+import { A as AssetListParams } from '../../../../shared/stack.CYSwntXC.js';
+import { S as SerializedAsset, a as SerializedFolder } from '../../../../shared/stack.CLcnSF_b.js';
+import '@btst/db';
+
+/**
+ * Infinite-scroll list of assets, optionally filtered by folder / MIME type / search.
+ */
+declare function useAssets(params?: AssetListParams): _tanstack_react_query.UseInfiniteQueryResult<_tanstack_react_query.InfiniteData<{
+    items: SerializedAsset[];
+    total: number;
+    limit?: number;
+    offset?: number;
+}, unknown>, Error>;
+/**
+ * List of folders, optionally filtered by parentId.
+ * Pass `null` for root-level folders, `undefined` for all folders.
+ */
+declare function useFolders(parentId?: string | null): _tanstack_react_query.UseQueryResult<SerializedFolder[], Error>;
+/**
+ * Upload an asset — adapter-aware. Handles direct, S3, and Vercel Blob flows.
+ */
+declare function useUploadAsset(): _tanstack_react_query.UseMutationResult<SerializedAsset, Error, {
+    file: File;
+    folderId?: string;
+}, unknown>;
+/**
+ * Register an asset URL directly (for when the URL already exists).
+ */
+declare function useRegisterAsset(): _tanstack_react_query.UseMutationResult<SerializedAsset, Error, {
+    url: string;
+    filename: string;
+    mimeType?: string;
+    size?: number;
+    folderId?: string;
+}, unknown>;
+/**
+ * Delete an asset by ID.
+ */
+declare function useDeleteAsset(): _tanstack_react_query.UseMutationResult<void, Error, string, unknown>;
+/**
+ * Create a new folder.
+ */
+declare function useCreateFolder(): _tanstack_react_query.UseMutationResult<SerializedFolder, Error, {
+    name: string;
+    parentId?: string;
+}, unknown>;
+/**
+ * Delete a folder by ID.
+ */
+declare function useDeleteFolder(): _tanstack_react_query.UseMutationResult<void, Error, string, unknown>;
+
+export { useAssets, useCreateFolder, useDeleteAsset, useDeleteFolder, useFolders, useRegisterAsset, useUploadAsset };

package/dist/plugins/media/client/hooks/index.mjs

@@ -0,0 +1 @@
+export { useAssets, useCreateFolder, useDeleteAsset, useDeleteFolder, useFolders, useRegisterAsset, useUploadAsset } from '../../../../packages/stack/src/plugins/media/client/hooks/use-media.mjs';

package/dist/plugins/media/client/index.cjs

@@ -0,0 +1,9 @@
+'use strict';
+
+const plugin = require('../../../packages/stack/src/plugins/media/client/plugin.cjs');
+const upload = require('../../../packages/stack/src/plugins/media/client/upload.cjs');
+
+
+
+exports.mediaClientPlugin = plugin.mediaClientPlugin;
+exports.uploadAsset = upload.uploadAsset;

package/dist/plugins/media/client/index.d.cts

@@ -0,0 +1,242 @@
+import * as _btst_stack_plugins_client from '@btst/stack/plugins/client';
+import * as _btst_yar from '@btst/yar';
+import { ComponentType } from 'react';
+import { QueryClient } from '@tanstack/react-query';
+import { S as SerializedAsset } from '../../../shared/stack.CLcnSF_b.cjs';
+
+interface MediaLoaderContext {
+    path: string;
+    isSSR: boolean;
+    apiBaseURL: string;
+    apiBasePath: string;
+    headers?: HeadersInit;
+}
+interface MediaClientHooks {
+    /** Called before the media library data is fetched during SSR. Throw to cancel. */
+    beforeLoadLibrary?: (context: MediaLoaderContext) => Promise<void> | void;
+    /** Called after the media library data is fetched during SSR. */
+    afterLoadLibrary?: (context: MediaLoaderContext) => Promise<void> | void;
+    /** Called when an error occurs during the SSR loader. */
+    onLoadError?: (error: Error, context: MediaLoaderContext) => Promise<void> | void;
+}
+interface MediaClientConfig {
+    /** Base URL for API calls (e.g., "http://localhost:3000") */
+    apiBaseURL: string;
+    /** Path where the API is mounted (e.g., "/api/data") */
+    apiBasePath: string;
+    /** Base URL of your site for SEO meta tags */
+    siteBaseURL: string;
+    /** Path where pages are mounted (e.g., "/pages") */
+    siteBasePath: string;
+    /** React Query client — used by the SSR loader to prefetch data */
+    queryClient: QueryClient;
+    /** Optional headers forwarded with SSR API requests (e.g. auth cookies) */
+    headers?: HeadersInit;
+    /** Optional lifecycle hooks for the media client plugin */
+    hooks?: MediaClientHooks;
+    /**
+     * Optional page component overrides.
+     * Replace any plugin page with a custom React component.
+     * The built-in component is used as the fallback when not provided.
+     */
+    pageComponents?: {
+        /** Replaces the media library page */
+        library?: ComponentType;
+    };
+}
+/**
+ * Media client plugin.
+ * Registers the /media library route.
+ *
+ * Configure overrides in StackProvider:
+ * ```tsx
+ * <StackProvider overrides={{ media: { apiBaseURL, apiBasePath, queryClient, uploadMode: "direct", navigate } }}>
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { mediaClientPlugin } from "@btst/stack/plugins/media/client"
+ *
+ * const clientPlugins = [
+ *   mediaClientPlugin({ apiBaseURL, apiBasePath, siteBaseURL, siteBasePath, queryClient }),
+ *   // ...other plugins
+ * ]
+ * ```
+ */
+declare const mediaClientPlugin: (config: MediaClientConfig) => _btst_stack_plugins_client.ClientPlugin<Record<string, never>, {
+    library: {
+        (inputCtx_0?: _btst_yar.InputContext<"/media", _btst_yar.RouteOptions> | undefined): {
+            PageComponent?: ComponentType<{}> | undefined;
+            LoadingComponent?: ComponentType<{}> | undefined;
+            ErrorComponent?: ComponentType<{}> | undefined;
+            loader?: (() => Promise<void>) | undefined;
+            meta?: (() => ({
+                title: string;
+                name?: undefined;
+                content?: undefined;
+                property?: undefined;
+            } | {
+                name: string;
+                content: string;
+                title?: undefined;
+                property?: undefined;
+            } | {
+                property: string;
+                content: string;
+                title?: undefined;
+                name?: undefined;
+            })[]) | undefined;
+            extra?: (() => any) | undefined;
+        };
+        options: _btst_yar.RouteOptions | undefined;
+        path: "/media";
+        meta: _btst_yar.RouteMeta | undefined;
+    };
+}>;
+
+/**
+ * Canvas-based client-side image compression.
+ *
+ * Skips SVG and GIF (vector data / animation would be lost on a canvas round-trip).
+ * All other image/* types are scaled down to fit within maxWidth × maxHeight
+ * (preserving aspect ratio) and re-encoded at the configured quality.
+ */
+interface ImageCompressionOptions {
+    /**
+     * Maximum width in pixels. Images wider than this are scaled down.
+     * @default 2048
+     */
+    maxWidth?: number;
+    /**
+     * Maximum height in pixels. Images taller than this are scaled down.
+     * @default 2048
+     */
+    maxHeight?: number;
+    /**
+     * Encoding quality (0–1). Applies to JPEG and WebP.
+     * @default 0.85
+     */
+    quality?: number;
+    /**
+     * Output MIME type. Defaults to the source image's MIME type.
+     * Set to `"image/webp"` for better compression at the cost of format change.
+     */
+    outputFormat?: string;
+}
+
+/**
+ * Upload mode — must match the storage adapter configured in mediaBackendPlugin.
+ * - `"direct"` — local filesystem adapter, files are uploaded via `POST /media/upload`
+ * - `"s3"` — AWS S3 / R2 / MinIO, the client fetches a presigned token then PUTs directly to S3
+ * - `"vercel-blob"` — Vercel Blob, uses the `@vercel/blob/client` SDK for direct upload
+ */
+type MediaUploadMode = "direct" | "s3" | "vercel-blob";
+/**
+ * Overridable components and functions for the Media plugin.
+ *
+ * External consumers provide these when registering the media client plugin
+ * via the StackProvider overrides.
+ */
+interface MediaPluginOverrides {
+    /**
+     * Base URL for API calls (e.g., "http://localhost:3000").
+     */
+    apiBaseURL: string;
+    /**
+     * Path where the API is mounted (e.g., "/api/data").
+     */
+    apiBasePath: string;
+    /**
+     * React Query client — used by the MediaPicker to cache and fetch assets.
+     */
+    queryClient: QueryClient;
+    /**
+     * Upload mode — must match the storageAdapter configured in mediaBackendPlugin.
+     * @default "direct"
+     */
+    uploadMode?: MediaUploadMode;
+    /**
+     * Optional headers to pass with API requests (e.g., for SSR auth).
+     */
+    headers?: HeadersInit;
+    /**
+     * Navigation function for programmatic navigation.
+     */
+    navigate: (path: string) => void | Promise<void>;
+    /**
+     * Link component for navigation within the media library page.
+     */
+    Link?: ComponentType<React.ComponentProps<"a"> & Record<string, any>>;
+    /**
+     * Image component for rendering asset thumbnails and previews.
+     *
+     * When provided, replaces the default `<img>` element in asset cards,
+     * the media library grid, and the ImageInputField preview. Use this
+     * to plug in Next.js `<Image>` for automatic optimisation.
+     *
+     * @example
+     * ```tsx
+     * Image: (props) => <NextImage {...props} />
+     * ```
+     */
+    Image?: ComponentType<React.ImgHTMLAttributes<HTMLImageElement> & Record<string, any>>;
+    /**
+     * Client-side image compression applied before upload via the Canvas API.
+     *
+     * Images are scaled down to fit within `maxWidth` × `maxHeight` (preserving
+     * aspect ratio) and re-encoded at `quality`. SVG and GIF files are always
+     * passed through unchanged.
+     *
+     * Set to `false` to disable compression entirely.
+     *
+     * @default { maxWidth: 2048, maxHeight: 2048, quality: 0.85 }
+     */
+    imageCompression?: ImageCompressionOptions | false;
+    /**
+     * Called when a media route is rendered.
+     */
+    onRouteRender?: (routeName: string, context: MediaRouteContext) => void | Promise<void>;
+    /**
+     * Called when a media route encounters an error.
+     */
+    onRouteError?: (routeName: string, error: Error, context: MediaRouteContext) => void | Promise<void>;
+    /**
+     * Called before the media library page is rendered.
+     * Return `false` to prevent rendering (e.g., redirect unauthenticated users).
+     *
+     * @example
+     * ```ts
+     * media: {
+     *   onBeforeLibraryPageRendered: (context) => !!currentUser?.isAdmin,
+     *   onRouteError: (routeName, error, context) => navigate("/login"),
+     * }
+     * ```
+     */
+    onBeforeLibraryPageRendered?: (context: MediaRouteContext) => boolean;
+}
+interface MediaRouteContext {
+    /** Current route path */
+    path: string;
+    /** Route parameters */
+    params?: Record<string, string>;
+    /** Whether rendering on server (true) or client (false) */
+    isSSR: boolean;
+    [key: string]: unknown;
+}
+
+type MediaUploadClientConfig = Pick<MediaPluginOverrides, "apiBaseURL" | "apiBasePath" | "headers" | "uploadMode" | "imageCompression">;
+interface UploadAssetInput {
+    file: File;
+    folderId?: string;
+}
+/**
+ * Upload an asset using the media plugin's configured storage mode.
+ *
+ * Use this in non-React contexts like editor `uploadImage` callbacks. React
+ * components should usually prefer `useUploadAsset()`, which wraps this helper
+ * and handles cache invalidation.
+ */
+declare function uploadAsset(config: MediaUploadClientConfig, input: UploadAssetInput): Promise<SerializedAsset>;
+
+export { mediaClientPlugin, uploadAsset };
+export type { MediaPluginOverrides, MediaUploadClientConfig, MediaUploadMode, UploadAssetInput };

package/dist/plugins/media/client/index.d.mts

@@ -0,0 +1,242 @@
+import * as _btst_stack_plugins_client from '@btst/stack/plugins/client';
+import * as _btst_yar from '@btst/yar';
+import { ComponentType } from 'react';
+import { QueryClient } from '@tanstack/react-query';
+import { S as SerializedAsset } from '../../../shared/stack.CLcnSF_b.mjs';
+
+interface MediaLoaderContext {
+    path: string;
+    isSSR: boolean;
+    apiBaseURL: string;
+    apiBasePath: string;
+    headers?: HeadersInit;
+}
+interface MediaClientHooks {
+    /** Called before the media library data is fetched during SSR. Throw to cancel. */
+    beforeLoadLibrary?: (context: MediaLoaderContext) => Promise<void> | void;
+    /** Called after the media library data is fetched during SSR. */
+    afterLoadLibrary?: (context: MediaLoaderContext) => Promise<void> | void;
+    /** Called when an error occurs during the SSR loader. */
+    onLoadError?: (error: Error, context: MediaLoaderContext) => Promise<void> | void;
+}
+interface MediaClientConfig {
+    /** Base URL for API calls (e.g., "http://localhost:3000") */
+    apiBaseURL: string;
+    /** Path where the API is mounted (e.g., "/api/data") */
+    apiBasePath: string;
+    /** Base URL of your site for SEO meta tags */
+    siteBaseURL: string;
+    /** Path where pages are mounted (e.g., "/pages") */
+    siteBasePath: string;
+    /** React Query client — used by the SSR loader to prefetch data */
+    queryClient: QueryClient;
+    /** Optional headers forwarded with SSR API requests (e.g. auth cookies) */
+    headers?: HeadersInit;
+    /** Optional lifecycle hooks for the media client plugin */
+    hooks?: MediaClientHooks;
+    /**
+     * Optional page component overrides.
+     * Replace any plugin page with a custom React component.
+     * The built-in component is used as the fallback when not provided.
+     */
+    pageComponents?: {
+        /** Replaces the media library page */
+        library?: ComponentType;
+    };
+}
+/**
+ * Media client plugin.
+ * Registers the /media library route.
+ *
+ * Configure overrides in StackProvider:
+ * ```tsx
+ * <StackProvider overrides={{ media: { apiBaseURL, apiBasePath, queryClient, uploadMode: "direct", navigate } }}>
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { mediaClientPlugin } from "@btst/stack/plugins/media/client"
+ *
+ * const clientPlugins = [
+ *   mediaClientPlugin({ apiBaseURL, apiBasePath, siteBaseURL, siteBasePath, queryClient }),
+ *   // ...other plugins
+ * ]
+ * ```
+ */
+declare const mediaClientPlugin: (config: MediaClientConfig) => _btst_stack_plugins_client.ClientPlugin<Record<string, never>, {
+    library: {
+        (inputCtx_0?: _btst_yar.InputContext<"/media", _btst_yar.RouteOptions> | undefined): {
+            PageComponent?: ComponentType<{}> | undefined;
+            LoadingComponent?: ComponentType<{}> | undefined;
+            ErrorComponent?: ComponentType<{}> | undefined;
+            loader?: (() => Promise<void>) | undefined;
+            meta?: (() => ({
+                title: string;
+                name?: undefined;
+                content?: undefined;
+                property?: undefined;
+            } | {
+                name: string;
+                content: string;
+                title?: undefined;
+                property?: undefined;
+            } | {
+                property: string;
+                content: string;
+                title?: undefined;
+                name?: undefined;
+            })[]) | undefined;
+            extra?: (() => any) | undefined;
+        };
+        options: _btst_yar.RouteOptions | undefined;
+        path: "/media";
+        meta: _btst_yar.RouteMeta | undefined;
+    };
+}>;
+
+/**
+ * Canvas-based client-side image compression.
+ *
+ * Skips SVG and GIF (vector data / animation would be lost on a canvas round-trip).
+ * All other image/* types are scaled down to fit within maxWidth × maxHeight
+ * (preserving aspect ratio) and re-encoded at the configured quality.
+ */
+interface ImageCompressionOptions {
+    /**
+     * Maximum width in pixels. Images wider than this are scaled down.
+     * @default 2048
+     */
+    maxWidth?: number;
+    /**
+     * Maximum height in pixels. Images taller than this are scaled down.
+     * @default 2048
+     */
+    maxHeight?: number;
+    /**
+     * Encoding quality (0–1). Applies to JPEG and WebP.
+     * @default 0.85
+     */
+    quality?: number;
+    /**
+     * Output MIME type. Defaults to the source image's MIME type.
+     * Set to `"image/webp"` for better compression at the cost of format change.
+     */
+    outputFormat?: string;
+}
+
+/**
+ * Upload mode — must match the storage adapter configured in mediaBackendPlugin.
+ * - `"direct"` — local filesystem adapter, files are uploaded via `POST /media/upload`
+ * - `"s3"` — AWS S3 / R2 / MinIO, the client fetches a presigned token then PUTs directly to S3
+ * - `"vercel-blob"` — Vercel Blob, uses the `@vercel/blob/client` SDK for direct upload
+ */
+type MediaUploadMode = "direct" | "s3" | "vercel-blob";
+/**
+ * Overridable components and functions for the Media plugin.
+ *
+ * External consumers provide these when registering the media client plugin
+ * via the StackProvider overrides.
+ */
+interface MediaPluginOverrides {
+    /**
+     * Base URL for API calls (e.g., "http://localhost:3000").
+     */
+    apiBaseURL: string;
+    /**
+     * Path where the API is mounted (e.g., "/api/data").
+     */
+    apiBasePath: string;
+    /**
+     * React Query client — used by the MediaPicker to cache and fetch assets.
+     */
+    queryClient: QueryClient;
+    /**
+     * Upload mode — must match the storageAdapter configured in mediaBackendPlugin.
+     * @default "direct"
+     */
+    uploadMode?: MediaUploadMode;
+    /**
+     * Optional headers to pass with API requests (e.g., for SSR auth).
+     */
+    headers?: HeadersInit;
+    /**
+     * Navigation function for programmatic navigation.
+     */
+    navigate: (path: string) => void | Promise<void>;
+    /**
+     * Link component for navigation within the media library page.
+     */
+    Link?: ComponentType<React.ComponentProps<"a"> & Record<string, any>>;
+    /**
+     * Image component for rendering asset thumbnails and previews.
+     *
+     * When provided, replaces the default `<img>` element in asset cards,
+     * the media library grid, and the ImageInputField preview. Use this
+     * to plug in Next.js `<Image>` for automatic optimisation.
+     *
+     * @example
+     * ```tsx
+     * Image: (props) => <NextImage {...props} />
+     * ```
+     */
+    Image?: ComponentType<React.ImgHTMLAttributes<HTMLImageElement> & Record<string, any>>;
+    /**
+     * Client-side image compression applied before upload via the Canvas API.
+     *
+     * Images are scaled down to fit within `maxWidth` × `maxHeight` (preserving
+     * aspect ratio) and re-encoded at `quality`. SVG and GIF files are always
+     * passed through unchanged.
+     *
+     * Set to `false` to disable compression entirely.
+     *
+     * @default { maxWidth: 2048, maxHeight: 2048, quality: 0.85 }
+     */
+    imageCompression?: ImageCompressionOptions | false;
+    /**
+     * Called when a media route is rendered.
+     */
+    onRouteRender?: (routeName: string, context: MediaRouteContext) => void | Promise<void>;
+    /**
+     * Called when a media route encounters an error.
+     */
+    onRouteError?: (routeName: string, error: Error, context: MediaRouteContext) => void | Promise<void>;
+    /**
+     * Called before the media library page is rendered.
+     * Return `false` to prevent rendering (e.g., redirect unauthenticated users).
+     *
+     * @example
+     * ```ts
+     * media: {
+     *   onBeforeLibraryPageRendered: (context) => !!currentUser?.isAdmin,
+     *   onRouteError: (routeName, error, context) => navigate("/login"),
+     * }
+     * ```
+     */
+    onBeforeLibraryPageRendered?: (context: MediaRouteContext) => boolean;
+}
+interface MediaRouteContext {
+    /** Current route path */
+    path: string;
+    /** Route parameters */
+    params?: Record<string, string>;
+    /** Whether rendering on server (true) or client (false) */
+    isSSR: boolean;
+    [key: string]: unknown;
+}
+
+type MediaUploadClientConfig = Pick<MediaPluginOverrides, "apiBaseURL" | "apiBasePath" | "headers" | "uploadMode" | "imageCompression">;
+interface UploadAssetInput {
+    file: File;
+    folderId?: string;
+}
+/**
+ * Upload an asset using the media plugin's configured storage mode.
+ *
+ * Use this in non-React contexts like editor `uploadImage` callbacks. React
+ * components should usually prefer `useUploadAsset()`, which wraps this helper
+ * and handles cache invalidation.
+ */
+declare function uploadAsset(config: MediaUploadClientConfig, input: UploadAssetInput): Promise<SerializedAsset>;
+
+export { mediaClientPlugin, uploadAsset };
+export type { MediaPluginOverrides, MediaUploadClientConfig, MediaUploadMode, UploadAssetInput };