@cfast/ui 0.0.1 → 0.2.0

package/dist/client.d.ts

@@ -1,617 +1,4 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
-import { a6 as UIPlugin, a7 as UIPluginComponents, s as ConfirmOptions, a1 as ToastApi, h as ActionButtonProps, M as FormStatusProps, k as AvatarWithInitialsProps, X as RoleBadgeProps, P as ImpersonationBannerProps, t as DataTableProps, z as FilterBarProps, n as BulkAction, p as ColumnDef, v as DropZoneProps, O as ImagePreviewProps, y as FileListProps, Q as ListViewProps, u as DetailViewProps } from './permission-gate-DVmY42oz.js';
-export { V as PermissionGate } from './permission-gate-DVmY42oz.js';
-import { ClientDescriptor } from '@cfast/actions/client';
-import { ReactNode, ComponentType } from 'react';
-
-/**
- * Creates a {@link UIPlugin} that maps component slots to styled implementations.
- *
- * Slots not provided in the `components` map fall back to the unstyled HTML
- * defaults from the headless layer. This allows incremental adoption -- implement
- * only the slots your design system covers.
- *
- * @param config - Plugin configuration object.
- * @param config.components - Partial map of slot names to styled component implementations.
- *   See {@link UIPluginComponents} for available slots.
- * @returns A {@link UIPlugin} instance to pass to {@link UIPluginProvider}.
- *
- * @example
- * ```ts
- * import { createUIPlugin } from "@cfast/ui";
- *
- * const joyPlugin = createUIPlugin({
- *   components: {
- *     button: JoyButton,
- *     table: JoyTable,
- *     chip: JoyChip,
- *   },
- * });
- * ```
- */
-declare function createUIPlugin(config: {
-    components: Partial<UIPluginComponents>;
-}): UIPlugin;
-/**
- * React context provider that makes a {@link UIPlugin} available to all `@cfast/ui` components.
- *
- * Place this near the root of your component tree (typically in the root layout).
- * All headless components use {@link useComponent} internally to resolve their
- * styled implementations from this context.
- *
- * @param props - Component props.
- * @param props.plugin - The UI plugin created by {@link createUIPlugin}.
- * @param props.children - Child elements that can access the plugin via
- *   {@link useUIPlugin} or {@link useComponent}.
- * @returns A React element wrapping children with the UI plugin context.
- *
- * @example
- * ```tsx
- * import { UIPluginProvider, createUIPlugin } from "@cfast/ui";
- *
- * const plugin = createUIPlugin({ components: { button: MyButton } });
- *
- * function Root() {
- *   return (
- *     <UIPluginProvider plugin={plugin}>
- *       <App />
- *     </UIPluginProvider>
- *   );
- * }
- * ```
- */
-declare function UIPluginProvider({ plugin, children, }: {
-    plugin: UIPlugin;
-    children: React.ReactNode;
-}): react_jsx_runtime.JSX.Element;
-/**
- * Returns the current {@link UIPlugin} from React context.
- *
- * Returns `null` if no {@link UIPluginProvider} is present in the component tree.
- * Most consumers should use {@link useComponent} instead, which handles the
- * fallback to headless defaults automatically.
- *
- * @returns The active {@link UIPlugin}, or `null` if no provider is mounted.
- *
- * @example
- * ```ts
- * const plugin = useUIPlugin();
- * if (plugin?.components.button) {
- *   // A custom button implementation is available
- * }
- * ```
- */
-declare function useUIPlugin(): UIPlugin | null;
-/**
- * Resolves a component for a given {@link UIPluginComponents} slot.
- *
- * Looks up the slot in the current {@link UIPlugin} (via {@link useUIPlugin}).
- * If the plugin provides an implementation for the slot, that component is returned.
- * Otherwise, the headless HTML default is returned. This ensures every component
- * renders correctly even without a UI plugin installed.
- *
- * @typeParam K - The slot key from {@link UIPluginComponents}.
- * @param slot - The component slot name to resolve (e.g., `"button"`, `"table"`, `"chip"`).
- * @returns The component implementation for the given slot.
- *
- * @example
- * ```ts
- * function MyComponent() {
- *   const Button = useComponent("button");
- *   const Chip = useComponent("chip");
- *
- *   return <Button onClick={handleClick}>Click me</Button>;
- * }
- * ```
- */
-declare function useComponent<K extends keyof UIPluginComponents>(slot: K): UIPluginComponents[K];
-
-/**
- * Function signature for the imperative confirmation dialog.
- *
- * Call with {@link ConfirmOptions} to show a dialog. Resolves to `true` if
- * the user confirms, or `false` if they cancel or dismiss.
- */
-type ConfirmFn = (options: ConfirmOptions) => Promise<boolean>;
-/**
- * Returns an imperative {@link ConfirmFn} that opens a confirmation dialog
- * and resolves to `true` (confirmed) or `false` (cancelled/dismissed).
- *
- * Must be used within a `ConfirmProvider` -- typically supplied by the
- * Joy UI plugin or a custom UI plugin implementation.
- *
- * @returns A {@link ConfirmFn} that accepts {@link ConfirmOptions} and returns a `Promise<boolean>`.
- * @throws {Error} If called outside of a `ConfirmProvider`.
- *
- * @example
- * ```ts
- * function DangerZone() {
- *   const confirm = useConfirm();
- *
- *   async function handleDelete() {
- *     const ok = await confirm({
- *       title: "Delete account",
- *       description: "This action cannot be undone.",
- *       confirmLabel: "Delete",
- *       variant: "danger",
- *     });
- *     if (ok) { /* proceed *\/ }
- *   }
- *
- *   return <button onClick={handleDelete}>Delete</button>;
- * }
- * ```
- */
-declare function useConfirm(): ConfirmFn;
-
-/**
- * Returns an imperative {@link ToastApi} for showing toast notifications.
- *
- * Provides convenience methods (`success`, `error`, `info`, `warning`) as well
- * as a generic `show` method that accepts full {@link ToastOptions}.
- *
- * Must be used within a `ToastProvider` -- typically supplied by the Joy UI
- * plugin (backed by Sonner) or a custom UI plugin implementation.
- *
- * @returns A {@link ToastApi} object with methods for each notification type.
- * @throws {Error} If called outside of a `ToastProvider`.
- *
- * @example
- * ```ts
- * function PublishButton() {
- *   const toast = useToast();
- *
- *   async function handlePublish() {
- *     try {
- *       await publishPost();
- *       toast.success("Post published");
- *     } catch (err) {
- *       toast.error("Failed to publish post");
- *     }
- *   }
- *
- *   return <button onClick={handlePublish}>Publish</button>;
- * }
- * ```
- */
-declare function useToast(): ToastApi;
-
-/**
- * Maps action names to their success/error toast messages.
- *
- * Each key is an action name from a {@link ClientDescriptor}, and the value
- * specifies the toast messages to show when that action succeeds or fails.
- */
-type ActionToastConfig = Record<string, {
-    success?: string;
-    error?: string;
-}>;
-/**
- * Automatically shows toast notifications when `@cfast/actions` results arrive.
- *
- * Watches all configured actions via their {@link ClientDescriptor} and triggers
- * success or error toasts when their result data changes. Internally uses
- * {@link useToast} and `useActions` from `@cfast/actions/client`.
- *
- * Must be used within both a `ToastProvider` and an actions context
- * (i.e., inside `app.Provider`).
- *
- * @param descriptor - Client-side action descriptor from `@cfast/actions`, typically
- *   `composed.client` from a `createActions()` call.
- * @param config - Map of action names to toast messages. Only actions listed here
- *   are watched; others are ignored.
- * @returns void
- *
- * @example
- * ```ts
- * // In a route component:
- * useActionToast(composed.client, {
- *   deletePost: { success: "Post deleted", error: "Failed to delete" },
- *   publishPost: { success: "Post published" },
- * });
- * ```
- */
-declare function useActionToast(descriptor: ClientDescriptor, config: ActionToastConfig): void;
-
-/**
- * Permission-aware button that submits a `@cfast/actions` action.
- *
- * Accepts an `ActionHookResult` from `useActions()` and renders a button
- * via the UI plugin's `button` slot. The button's visibility and disabled
- * state are controlled by the action's permission status. Extra props are
- * forwarded to the underlying button component.
- *
- * - `whenForbidden="hide"` -- hidden when not permitted
- * - `whenForbidden="disable"` -- shown but disabled when not permitted (default)
- * - `whenForbidden="show"` -- shown and clickable regardless of permission
- *
- * @param props - See {@link ActionButtonProps}.
- *
- * @example
- * ```tsx
- * <ActionButton
- *   action={publishPost}
- *   whenForbidden="disable"
- *   confirmation="Publish this post?"
- * >
- *   Publish
- * </ActionButton>
- * ```
- */
-declare function ActionButton({ action, children, whenForbidden, confirmation: _confirmation, ...buttonProps }: ActionButtonProps): react_jsx_runtime.JSX.Element | null;
-
-/**
- * Provides the {@link useConfirm} context and renders the confirmation dialog.
- *
- * Wrap your application (or a subtree) with `ConfirmProvider` to enable the
- * imperative `useConfirm()` hook. The dialog is rendered using the UI plugin's
- * `confirmDialog` slot, so it matches your chosen component library.
- *
- * @param props.children - The React tree that can call `useConfirm()`.
- *
- * @example
- * ```tsx
- * // In your root layout:
- * <ConfirmProvider>
- *   <App />
- * </ConfirmProvider>
- *
- * // In any descendant component:
- * const confirm = useConfirm();
- * const ok = await confirm({ title: "Delete?", variant: "danger" });
- * ```
- */
-declare function ConfirmProvider({ children }: {
-    children: ReactNode;
-}): react_jsx_runtime.JSX.Element;
-
-/**
- * Displays action result feedback (success, error, and field-level validation messages).
- *
- * Renders alerts via the UI plugin's `alert` slot. Success messages are shown
- * in green, errors in red, and field-level validation errors as a bulleted list.
- * Returns `null` when there is no feedback to display.
- *
- * @param props - See {@link FormStatusProps}.
- *
- * @example
- * ```tsx
- * function EditForm() {
- *   const actionData = useActionData();
- *   return (
- *     <Form method="post">
- *       <FormStatus data={actionData} />
- *       ...
- *     </Form>
- *   );
- * }
- * ```
- */
-declare function FormStatus({ data }: FormStatusProps): react_jsx_runtime.JSX.Element | null;
-
-/**
- * Extracts up to two uppercase initials from a full name.
- *
- * Splits the name on spaces and takes the first character of each part.
- *
- * @param name - The full name to extract initials from.
- * @returns A string of 1-2 uppercase characters (e.g. `"DS"` for `"Daniel Schmidt"`).
- *
- * @example
- * ```ts
- * getInitials("Daniel Schmidt"); // "DS"
- * getInitials("Alice");          // "A"
- * ```
- */
-declare function getInitials(name: string): string;
-/**
- * Avatar component with automatic initials fallback.
- *
- * Renders an `<img>` when a `src` URL is provided. When `src` is absent or null,
- * displays the user's initials (derived via {@link getInitials}) inside a circular
- * badge. This is the headless implementation; styled versions are provided by UI plugins.
- *
- * @param props - See {@link AvatarWithInitialsProps}.
- *
- * @example
- * ```tsx
- * <AvatarWithInitials
- *   src={user.avatarUrl}
- *   name={user.name}
- *   size="sm"
- * />
- * ```
- */
-declare function AvatarWithInitials({ src, name, size, }: AvatarWithInitialsProps): react_jsx_runtime.JSX.Element;
-
-/**
- * Colored badge displaying a user's role name.
- *
- * Renders via the UI plugin's `chip` slot. Default color mapping:
- * admin = danger, editor = primary, author = success, reader = neutral.
- * Pass a custom `colors` map to override or extend the defaults.
- *
- * @param props - See {@link RoleBadgeProps}.
- *
- * @example
- * ```tsx
- * <RoleBadge role="admin" />
- * // Custom colors:
- * <RoleBadge role="moderator" colors={{ moderator: "warning" }} />
- * ```
- */
-declare function RoleBadge({ role, colors }: RoleBadgeProps): react_jsx_runtime.JSX.Element;
-
-/**
- * Persistent banner shown when an admin is impersonating another user.
- *
- * Reads the current user from `@cfast/auth` via `useCurrentUser()`. When the
- * user has `isImpersonating` set, renders a warning alert with the impersonated
- * user's name/email and a "Stop Impersonating" button that posts to `stopAction`.
- * Hidden when not impersonating.
- *
- * @param props - See {@link ImpersonationBannerProps}.
- *
- * @example
- * ```tsx
- * // In your root layout:
- * <ImpersonationBanner />
- *
- * // With custom stop action URL:
- * <ImpersonationBanner stopAction="/api/stop-impersonation" />
- * ```
- */
-declare function ImpersonationBanner({ stopAction, }: ImpersonationBannerProps): react_jsx_runtime.JSX.Element | null;
-
-/**
- * Data table with column sorting, row selection, and pluggable cell rendering.
- *
- * Renders via the UI plugin's table slots (`table`, `tableHead`, `tableBody`,
- * `tableRow`, `tableCell`). Accepts column definitions as strings (auto-labeled)
- * or full {@link ColumnDef} objects for custom labels, sorting, and renderers.
- *
- * Integrates with `@cfast/pagination` hook results for paginated data and with
- * `@cfast/actions` for row-level actions.
- *
- * @typeParam T - The row data type.
- * @param props - See {@link DataTableProps}.
- *
- * @example
- * ```tsx
- * const pagination = usePagination<Post>();
- *
- * <DataTable
- *   data={pagination}
- *   columns={["title", "author", { key: "createdAt", sortable: false }]}
- *   selectable
- *   onRowClick={(row) => navigate(`/posts/${row.id}`)}
- * />
- * ```
- */
-declare function DataTable<T = unknown>({ data, columns: columnsProp, selectable, selectedRows: externalSelectedRows, onSelectionChange, onRowClick, getRowId, emptyMessage, }: DataTableProps<T>): react_jsx_runtime.JSX.Element;
-
-/**
- * URL-synced filter controls for data tables and list views.
- *
- * Each filter serializes its state to URL search params (e.g., `?published=true`).
- * On filter change, React Router navigates with the updated params, resetting
- * pagination to page 1. In the loader, `@cfast/pagination`'s `parseParams()`
- * reads these params and applies them as Drizzle `where` clauses.
- *
- * Supports text, select, boolean, and other filter types via {@link FilterDef}.
- * An optional `searchable` prop adds a full-text search input across specified columns.
- *
- * @param props - See {@link FilterBarProps}.
- *
- * @example
- * ```tsx
- * <FilterBar
- *   filters={[
- *     { column: "published", type: "select", options: [
- *       { label: "Published", value: "true" },
- *       { label: "Draft", value: "false" },
- *     ]},
- *     { column: "createdAt", type: "dateRange" },
- *   ]}
- *   searchable={["title", "content"]}
- * />
- * ```
- */
-declare function FilterBar({ filters, searchable, }: FilterBarProps): react_jsx_runtime.JSX.Element;
-
-type BulkActionBarProps = {
-    selectedCount: number;
-    actions: BulkAction[];
-    onAction: (action: BulkAction) => void;
-    onClearSelection: () => void;
-};
-/**
- * Toolbar that appears when rows are selected in a {@link DataTable}.
- *
- * Displays the selected row count, action buttons for each {@link BulkAction},
- * and a "Clear" button to deselect all rows. Actions are rendered via the UI
- * plugin's `button` slot. Hidden automatically when `selectedCount` is zero.
- *
- * @param props - See {@link BulkActionBarProps}.
- *
- * @example
- * ```tsx
- * <BulkActionBar
- *   selectedCount={selectedRows.length}
- *   actions={[
- *     { label: "Delete", icon: TrashIcon },
- *     { label: "Publish" },
- *   ]}
- *   onAction={(action) => handleBulk(action, selectedRows)}
- *   onClearSelection={() => clearSelection()}
- * />
- * ```
- */
-declare function BulkActionBar({ selectedCount, actions, onAction, onClearSelection, }: BulkActionBarProps): react_jsx_runtime.JSX.Element | null;
-
-/** A column definition extended with an inferred TypedField component. */
-type InferredColumn = ColumnDef & {
-    /** The field component that renders the appropriate display for this column type. */
-    field: ComponentType<{
-        value: unknown;
-    }>;
-};
-/**
- * Inspects a Drizzle table's columns and returns inferred {@link ColumnDef} entries
- * with appropriate TypedField components attached.
- *
- * Uses {@link fieldForColumn} internally to map each Drizzle column's `dataType`
- * to a display component (e.g., `DateField`, `BooleanField`, `TextField`).
- * Labels are auto-derived from camelCase column keys.
- *
- * Memoized -- only recomputes when the `table` reference or `columns` array changes.
- *
- * @param table - A Drizzle table object whose entries expose `dataType` and `name` metadata.
- *   Pass `undefined` to return an empty array (safe for conditional rendering).
- * @param columns - Optional subset of column names to include. When provided,
- *   only matching columns are returned and their order is preserved.
- * @returns Array of {@link InferredColumn} definitions, each containing a `field`
- *   component ready for rendering.
- *
- * @example
- * ```ts
- * import { useColumnInference } from "@cfast/ui";
- * import { posts } from "~/db/schema";
- *
- * const cols = useColumnInference(posts, ["title", "createdAt", "published"]);
- * // cols[0].field === TextField
- * // cols[1].field === DateField
- * // cols[2].field === BooleanField
- * ```
- */
-declare function useColumnInference(table: Record<string, unknown> | undefined, columns?: string[]): InferredColumn[];
-
-/**
- * Drag-and-drop file upload area that integrates with `@cfast/storage`.
- *
- * Accepts an `upload` result from `useUpload()` (`@cfast/storage/client`).
- * File type restrictions and max size are inherited from the storage schema.
- * Renders via the UI plugin's `dropZone` slot and manages drag state,
- * file validation, and upload progress internally.
- *
- * @param props - See {@link DropZoneProps}.
- *
- * @example
- * ```tsx
- * const upload = useUpload("postCoverImage");
- *
- * <DropZone upload={upload} />
- *
- * // Allow multiple files:
- * <DropZone upload={upload} multiple />
- * ```
- */
-declare function DropZone({ upload, multiple, children, }: DropZoneProps): react_jsx_runtime.JSX.Element;
-
-/**
- * Displays an image from `@cfast/storage` or a direct URL.
- *
- * Resolves the display URL from either a direct `src`, or a `fileKey` + `getUrl`
- * resolver function (for signed URL generation). Shows a placeholder when no
- * image is available, or renders the `fallback` element if provided.
- *
- * @param props - See {@link ImagePreviewProps}.
- *
- * @example
- * ```tsx
- * <ImagePreview
- *   fileKey={post.coverImageKey}
- *   getUrl={(key) => storage.getSignedUrl(key)}
- *   width={200}
- *   height={150}
- *   fallback={<PlaceholderImage />}
- * />
- * ```
- */
-declare function ImagePreview({ fileKey, src, getUrl, width, height, fallback, alt, }: ImagePreviewProps): react_jsx_runtime.JSX.Element;
-
-/**
- * Displays a list of uploaded files with metadata, formatted sizes, and download links.
- *
- * Each file is rendered as a row showing the file name, size (human-readable), and
- * a download link (either via `onDownload` callback or the file's direct `url`).
- * Returns a "No files" placeholder when the list is empty.
- *
- * @param props - See {@link FileListProps}.
- *
- * @example
- * ```tsx
- * <FileList
- *   files={post.attachments}
- *   onDownload={(file) => window.open(storage.getSignedUrl(file.key))}
- * />
- * ```
- */
-declare function FileList({ files, onDownload, }: FileListProps): react_jsx_runtime.JSX.Element;
-
-/**
- * Full-page list layout composing filters, data table, pagination, and empty state.
- *
- * Combines {@link PageContainer}, {@link FilterBar}, {@link DataTable},
- * {@link EmptyState}, {@link BulkActionBar}, and pagination controls into a
- * single component. This is the primary component used by `@cfast/admin` for
- * every table view, but it is equally useful in application code.
- *
- * Supports both offset-based pagination (page numbers) and cursor-based pagination
- * (load more). The `createAction` prop controls the visibility of the "Create" button
- * via permission checks.
- *
- * @typeParam T - The row data type.
- * @param props - See {@link ListViewProps}.
- *
- * @example
- * ```tsx
- * const pagination = useOffsetPagination<Post>();
- *
- * <ListView
- *   title="Blog Posts"
- *   data={pagination}
- *   columns={["title", "author", "published", "createdAt"]}
- *   filters={[{ column: "published", type: "select", options: publishedOptions }]}
- *   searchable={["title", "content"]}
- *   createAction={createPost.client}
- *   selectable
- *   bulkActions={[
- *     { label: "Delete", handler: (rows) => bulkDelete(rows) },
- *   ]}
- * />
- * ```
- */
-declare function ListView<T = unknown>({ title, data, table: _table, columns, actions: _actions, filters, searchable, createAction, createLabel, selectable, bulkActions, breadcrumb, }: ListViewProps<T>): react_jsx_runtime.JSX.Element;
-
-/**
- * Read-only detail page for a single record, rendered in a two-column grid.
- *
- * Composes {@link PageContainer} with automatic TypedField rendering. When a Drizzle
- * `table` is provided, field types are inferred from column metadata and rendered with
- * the appropriate field component (DateField, BooleanField, etc.). Fields can also be
- * specified manually as strings or full {@link ColumnDef} objects with custom renderers.
- *
- * If no `fields` are specified, they are inferred from the record's own keys
- * (minus any keys listed in `exclude`).
- *
- * @typeParam T - The record data type.
- * @param props - See {@link DetailViewProps}.
- *
- * @example
- * ```tsx
- * <DetailView
- *   title={post.title}
- *   table={posts}
- *   record={post}
- *   fields={["title", "content", "author", "published", "createdAt"]}
- *   breadcrumb={[
- *     { label: "Posts", to: "/posts" },
- *     { label: post.title },
- *   ]}
- * />
- * ```
- */
-declare function DetailView<T = unknown>({ title, table, record, fields: fieldsProp, exclude, breadcrumb, }: DetailViewProps<T>): react_jsx_runtime.JSX.Element;
-
-export { ActionButton, AvatarWithInitials, BulkActionBar, ConfirmProvider, DataTable, DetailView, DropZone, FileList, FilterBar, FormStatus, ImagePreview, ImpersonationBanner, ListView, RoleBadge, UIPluginProvider, createUIPlugin, getInitials, useActionToast, useColumnInference, useComponent, useConfirm, useToast, useUIPlugin };
+export { h as ActionButton, l as AvatarWithInitials, q as BulkActionBar, w as ConfirmProvider, x as DataTable, z as DetailView, H as DropZone, M as FileList, Q as FilterBar, Y as FormStatus, $ as ImagePreview, a1 as ImpersonationBanner, a3 as ListView, a6 as PermissionGate, a8 as RoleBadge, an as UIPluginProvider, aq as createUIPlugin, ar as getInitials, as as useActionToast, at as useColumnInference, au as useComponent, av as useConfirm, aw as useToast, ax as useUIPlugin } from './client-CIx8_tmv.js';
+import 'react/jsx-runtime';
+import 'react';
+import '@cfast/actions/client';

package/dist/client.js

@@ -1,5 +1,6 @@
 import {
   ActionButton,
+  AvatarWithInitials,
   BulkActionBar,
   ConfirmProvider,
   DataTable,
@@ -11,21 +12,18 @@ import {
   ImagePreview,
   ImpersonationBanner,
   ListView,
-  RoleBadge,
-  useActionToast,
-  useColumnInference,
-  useConfirm
-} from "./chunk-JEGEIQ3R.js";
-import {
-  AvatarWithInitials,
   PermissionGate,
+  RoleBadge,
   UIPluginProvider,
   createUIPlugin,
   getInitials,
+  useActionToast,
+  useColumnInference,
   useComponent,
+  useConfirm,
   useToast,
   useUIPlugin
-} from "./chunk-RDTUEOLK.js";
+} from "./chunk-PWBG6CGF.js";
 export {
   ActionButton,
   AvatarWithInitials,