@btst/stack 2.8.1 → 2.9.1

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

@@ -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.js';
+
+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.mjs

@@ -0,0 +1,2 @@
+export { mediaClientPlugin } from '../../../packages/stack/src/plugins/media/client/plugin.mjs';
+export { uploadAsset } from '../../../packages/stack/src/plugins/media/client/upload.mjs';

package/dist/plugins/media/client.css

@@ -0,0 +1 @@
+/* Media plugin client styles — included in consumer CSS via @import "@btst/stack/plugins/media/css" */

package/dist/plugins/media/query-keys.cjs

@@ -0,0 +1,72 @@
+'use strict';
+
+const queryKeyFactory = require('@lukemorales/query-key-factory');
+const queryKeyDefs = require('../../packages/stack/src/plugins/media/api/query-key-defs.cjs');
+
+function isErrorResponse(response) {
+  return typeof response === "object" && response !== null && "error" in response && response.error !== null && response.error !== void 0;
+}
+function toError(error) {
+  if (error instanceof Error) return error;
+  if (typeof error === "object" && error !== null) {
+    const errorObj = error;
+    const message = (typeof errorObj.message === "string" ? errorObj.message : null) || JSON.stringify(error);
+    const err = new Error(message);
+    Object.assign(err, error);
+    return err;
+  }
+  return new Error(String(error));
+}
+function createMediaQueryKeys(client, headers) {
+  return queryKeyFactory.mergeQueryKeys(
+    queryKeyFactory.createQueryKeys("mediaAssets", {
+      list: (params) => ({
+        queryKey: [queryKeyDefs.assetListDiscriminator(params)],
+        queryFn: async ({ pageParam }) => {
+          const response = await client("/media/assets", {
+            method: "GET",
+            query: {
+              folderId: params?.folderId,
+              mimeType: params?.mimeType,
+              query: params?.query,
+              offset: pageParam ?? params?.offset ?? 0,
+              limit: params?.limit ?? 20
+            },
+            headers
+          });
+          if (isErrorResponse(response)) throw toError(response.error);
+          const data = response.data;
+          return data;
+        }
+      }),
+      detail: (id) => ({
+        queryKey: [id],
+        queryFn: async () => {
+          const response = await client("/media/assets", {
+            method: "GET",
+            query: { id },
+            headers
+          });
+          if (isErrorResponse(response)) throw toError(response.error);
+          return response.data;
+        }
+      })
+    }),
+    queryKeyFactory.createQueryKeys("mediaFolders", {
+      list: (parentId) => ({
+        queryKey: [parentId ?? "root"],
+        queryFn: async () => {
+          const response = await client("/media/folders", {
+            method: "GET",
+            query: parentId !== void 0 ? { parentId: parentId ?? void 0 } : {},
+            headers
+          });
+          if (isErrorResponse(response)) throw toError(response.error);
+          return response.data;
+        }
+      })
+    })
+  );
+}
+
+exports.createMediaQueryKeys = createMediaQueryKeys;

package/dist/plugins/media/query-keys.d.cts

@@ -0,0 +1,49 @@
+import * as _tanstack_react_query from '@tanstack/react-query';
+import { M as MediaApiRouter, A as AssetListDiscriminator } from '../../shared/stack.CI8iRKKi.cjs';
+import { createApiClient } from '@btst/stack/plugins/client';
+import { S as SerializedAsset, a as SerializedFolder } from '../../shared/stack.CLcnSF_b.cjs';
+import { A as AssetListParams } from '../../shared/stack.CAni8dnD.cjs';
+import '@btst/stack/plugins/api';
+import '../../shared/stack.BttDsJJn.cjs';
+import 'better-call';
+import 'zod';
+import '@btst/db';
+
+declare function createMediaQueryKeys(client: ReturnType<typeof createApiClient<MediaApiRouter>>, headers?: HeadersInit): {
+    mediaAssets: {
+        _def: readonly ["mediaAssets"];
+    } & {
+        list: ((params?: AssetListParams | undefined) => Omit<Omit<{
+            queryKey: readonly ["mediaAssets", "list", AssetListDiscriminator];
+            queryFn: _tanstack_react_query.QueryFunction<unknown, readonly ["mediaAssets", "list", AssetListDiscriminator]>;
+        }, "queryFn"> & {
+            _def: readonly ["mediaAssets", "list"];
+        }, "_def">) & {
+            _def: readonly ["mediaAssets", "list"];
+        };
+        detail: ((id: string) => Omit<{
+            queryKey: readonly ["mediaAssets", "detail", string];
+            queryFn: _tanstack_react_query.QueryFunction<SerializedAsset | null, readonly ["mediaAssets", "detail", string]>;
+        } & {
+            _def: readonly ["mediaAssets", "detail"];
+        }, "_def">) & {
+            _def: readonly ["mediaAssets", "detail"];
+        };
+    };
+    mediaFolders: {
+        _def: readonly ["mediaFolders"];
+    } & {
+        list: ((parentId?: string | null | undefined) => Omit<{
+            queryKey: readonly ["mediaFolders", "list", string];
+            queryFn: _tanstack_react_query.QueryFunction<SerializedFolder[], readonly ["mediaFolders", "list", string]>;
+        } & {
+            _def: readonly ["mediaFolders", "list"];
+        }, "_def">) & {
+            _def: readonly ["mediaFolders", "list"];
+        };
+    };
+};
+type MediaQueryKeys = ReturnType<typeof createMediaQueryKeys>;
+
+export { createMediaQueryKeys };
+export type { MediaQueryKeys };

package/dist/plugins/media/query-keys.d.mts

@@ -0,0 +1,49 @@
+import * as _tanstack_react_query from '@tanstack/react-query';
+import { M as MediaApiRouter, A as AssetListDiscriminator } from '../../shared/stack.FgBVDSPi.mjs';
+import { createApiClient } from '@btst/stack/plugins/client';
+import { S as SerializedAsset, a as SerializedFolder } from '../../shared/stack.CLcnSF_b.mjs';
+import { A as AssetListParams } from '../../shared/stack.C7vfOBmO.mjs';
+import '@btst/stack/plugins/api';
+import '../../shared/stack.BttDsJJn.mjs';
+import 'better-call';
+import 'zod';
+import '@btst/db';
+
+declare function createMediaQueryKeys(client: ReturnType<typeof createApiClient<MediaApiRouter>>, headers?: HeadersInit): {
+    mediaAssets: {
+        _def: readonly ["mediaAssets"];
+    } & {
+        list: ((params?: AssetListParams | undefined) => Omit<Omit<{
+            queryKey: readonly ["mediaAssets", "list", AssetListDiscriminator];
+            queryFn: _tanstack_react_query.QueryFunction<unknown, readonly ["mediaAssets", "list", AssetListDiscriminator]>;
+        }, "queryFn"> & {
+            _def: readonly ["mediaAssets", "list"];
+        }, "_def">) & {
+            _def: readonly ["mediaAssets", "list"];
+        };
+        detail: ((id: string) => Omit<{
+            queryKey: readonly ["mediaAssets", "detail", string];
+            queryFn: _tanstack_react_query.QueryFunction<SerializedAsset | null, readonly ["mediaAssets", "detail", string]>;
+        } & {
+            _def: readonly ["mediaAssets", "detail"];
+        }, "_def">) & {
+            _def: readonly ["mediaAssets", "detail"];
+        };
+    };
+    mediaFolders: {
+        _def: readonly ["mediaFolders"];
+    } & {
+        list: ((parentId?: string | null | undefined) => Omit<{
+            queryKey: readonly ["mediaFolders", "list", string];
+            queryFn: _tanstack_react_query.QueryFunction<SerializedFolder[], readonly ["mediaFolders", "list", string]>;
+        } & {
+            _def: readonly ["mediaFolders", "list"];
+        }, "_def">) & {
+            _def: readonly ["mediaFolders", "list"];
+        };
+    };
+};
+type MediaQueryKeys = ReturnType<typeof createMediaQueryKeys>;
+
+export { createMediaQueryKeys };
+export type { MediaQueryKeys };

package/dist/plugins/media/query-keys.d.ts

@@ -0,0 +1,49 @@
+import * as _tanstack_react_query from '@tanstack/react-query';
+import { M as MediaApiRouter, A as AssetListDiscriminator } from '../../shared/stack.DJDjdG64.js';
+import { createApiClient } from '@btst/stack/plugins/client';
+import { S as SerializedAsset, a as SerializedFolder } from '../../shared/stack.CLcnSF_b.js';
+import { A as AssetListParams } from '../../shared/stack.CYSwntXC.js';
+import '@btst/stack/plugins/api';
+import '../../shared/stack.BttDsJJn.js';
+import 'better-call';
+import 'zod';
+import '@btst/db';
+
+declare function createMediaQueryKeys(client: ReturnType<typeof createApiClient<MediaApiRouter>>, headers?: HeadersInit): {
+    mediaAssets: {
+        _def: readonly ["mediaAssets"];
+    } & {
+        list: ((params?: AssetListParams | undefined) => Omit<Omit<{
+            queryKey: readonly ["mediaAssets", "list", AssetListDiscriminator];
+            queryFn: _tanstack_react_query.QueryFunction<unknown, readonly ["mediaAssets", "list", AssetListDiscriminator]>;
+        }, "queryFn"> & {
+            _def: readonly ["mediaAssets", "list"];
+        }, "_def">) & {
+            _def: readonly ["mediaAssets", "list"];
+        };
+        detail: ((id: string) => Omit<{
+            queryKey: readonly ["mediaAssets", "detail", string];
+            queryFn: _tanstack_react_query.QueryFunction<SerializedAsset | null, readonly ["mediaAssets", "detail", string]>;
+        } & {
+            _def: readonly ["mediaAssets", "detail"];
+        }, "_def">) & {
+            _def: readonly ["mediaAssets", "detail"];
+        };
+    };
+    mediaFolders: {
+        _def: readonly ["mediaFolders"];
+    } & {
+        list: ((parentId?: string | null | undefined) => Omit<{
+            queryKey: readonly ["mediaFolders", "list", string];
+            queryFn: _tanstack_react_query.QueryFunction<SerializedFolder[], readonly ["mediaFolders", "list", string]>;
+        } & {
+            _def: readonly ["mediaFolders", "list"];
+        }, "_def">) & {
+            _def: readonly ["mediaFolders", "list"];
+        };
+    };
+};
+type MediaQueryKeys = ReturnType<typeof createMediaQueryKeys>;
+
+export { createMediaQueryKeys };
+export type { MediaQueryKeys };

package/dist/plugins/media/query-keys.mjs

@@ -0,0 +1,70 @@
+import { mergeQueryKeys, createQueryKeys } from '@lukemorales/query-key-factory';
+import { assetListDiscriminator } from '../../packages/stack/src/plugins/media/api/query-key-defs.mjs';
+
+function isErrorResponse(response) {
+  return typeof response === "object" && response !== null && "error" in response && response.error !== null && response.error !== void 0;
+}
+function toError(error) {
+  if (error instanceof Error) return error;
+  if (typeof error === "object" && error !== null) {
+    const errorObj = error;
+    const message = (typeof errorObj.message === "string" ? errorObj.message : null) || JSON.stringify(error);
+    const err = new Error(message);
+    Object.assign(err, error);
+    return err;
+  }
+  return new Error(String(error));
+}
+function createMediaQueryKeys(client, headers) {
+  return mergeQueryKeys(
+    createQueryKeys("mediaAssets", {
+      list: (params) => ({
+        queryKey: [assetListDiscriminator(params)],
+        queryFn: async ({ pageParam }) => {
+          const response = await client("/media/assets", {
+            method: "GET",
+            query: {
+              folderId: params?.folderId,
+              mimeType: params?.mimeType,
+              query: params?.query,
+              offset: pageParam ?? params?.offset ?? 0,
+              limit: params?.limit ?? 20
+            },
+            headers
+          });
+          if (isErrorResponse(response)) throw toError(response.error);
+          const data = response.data;
+          return data;
+        }
+      }),
+      detail: (id) => ({
+        queryKey: [id],
+        queryFn: async () => {
+          const response = await client("/media/assets", {
+            method: "GET",
+            query: { id },
+            headers
+          });
+          if (isErrorResponse(response)) throw toError(response.error);
+          return response.data;
+        }
+      })
+    }),
+    createQueryKeys("mediaFolders", {
+      list: (parentId) => ({
+        queryKey: [parentId ?? "root"],
+        queryFn: async () => {
+          const response = await client("/media/folders", {
+            method: "GET",
+            query: parentId !== void 0 ? { parentId: parentId ?? void 0 } : {},
+            headers
+          });
+          if (isErrorResponse(response)) throw toError(response.error);
+          return response.data;
+        }
+      })
+    })
+  );
+}
+
+export { createMediaQueryKeys };

package/dist/plugins/media/style.css

@@ -0,0 +1 @@
+@source "./client/**/*.{ts,tsx}";

package/dist/shared/{stack.DRpeDS6X.d.ts → stack.BMx2QYOK.d.ts}

@@ -141,6 +141,31 @@ interface KanbanPluginOverrides {
      * Optional headers to pass with API requests (e.g., for SSR auth)
      */
     headers?: HeadersInit;
+    /**
+     * Function used to upload a new image file from the task description editor
+     * and return its URL. This is separate from `imagePicker`, which selects an
+     * existing asset URL.
+     */
+    uploadImage?: (file: File) => Promise<string>;
+    /**
+     * Optional trigger component for a media picker.
+     * When provided, it appears inside the image insertion dialog of the task description editor,
+     * letting users browse and select previously uploaded assets.
+     *
+     * @example
+     * ```tsx
+     * imagePicker: ({ onSelect }) => (
+     *   <MediaPicker
+     *     trigger={<Button size="sm" variant="outline">Browse media</Button>}
+     *     accept={["image/*"]}
+     *     onSelect={(assets) => onSelect(assets[0].url)}
+     *   />
+     * )
+     * ```
+     */
+    imagePicker?: ComponentType<{
+        onSelect: (url: string) => void;
+    }>;
     /**
      * Resolve user info from an assigneeId
      * Called when rendering task cards/forms that have an assignee