@cfast/ui 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,415 @@
+export { ActionButton, AvatarWithInitials, BulkActionBar, ConfirmProvider, DataTable, DetailView, DropZone, FileList, FilterBar, FormStatus, ImagePreview, ImpersonationBanner, ListView, RoleBadge, UIPluginProvider, createUIPlugin, getInitials, useActionToast, useColumnInference, useComponent, useConfirm, useToast, useUIPlugin } from './client.js';
+import { D as DateFieldProps, B as BooleanFieldProps, N as NumberFieldProps, T as TextFieldProps, E as EmailFieldProps, U as UrlFieldProps, I as ImageFieldProps, F as FileFieldProps, R as RelationFieldProps, J as JsonFieldProps, a as FieldComponent, b as EmptyStateProps, c as NavigationProgressProps, d as BreadcrumbItem, e as TabItem, A as AppShellProps, f as NavigationItem, g as UserMenuProps } from './permission-gate-DVmY42oz.js';
+export { h as ActionButtonProps, i as AlertSlotProps, j as AppShellSlotProps, k as AvatarWithInitialsProps, l as BaseFieldProps, m as BreadcrumbSlotProps, n as BulkAction, o as ButtonSlotProps, C as ChipSlotProps, p as ColumnDef, q as ColumnShorthand, r as ConfirmDialogSlotProps, s as ConfirmOptions, t as DataTableProps, u as DetailViewProps, v as DropZoneProps, w as DropZoneSlotProps, x as FileListFile, y as FileListProps, z as FilterBarProps, G as FilterDef, H as FilterOption, K as FilterType, L as FormStatusData, M as FormStatusProps, O as ImagePreviewProps, P as ImpersonationBannerProps, Q as ListViewProps, S as PageContainerSlotProps, V as PermissionGate, W as PermissionGateProps, X as RoleBadgeProps, Y as SidebarSlotProps, Z as TableCellSlotProps, _ as TableRowSlotProps, $ as TableSectionSlotProps, a0 as TableSlotProps, a1 as ToastApi, a2 as ToastOptions, a3 as ToastSlotProps, a4 as ToastType, a5 as TooltipSlotProps, a6 as UIPlugin, a7 as UIPluginComponents, a8 as UserMenuLink, a9 as WhenForbidden } from './permission-gate-DVmY42oz.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import '@cfast/actions/client';
+
+/**
+ * Read-only display component that formats date values.
+ *
+ * Accepts `Date` objects, ISO strings, or Unix timestamps. Renders a `<time>`
+ * element with the formatted date and a machine-readable `datetime` attribute.
+ * Returns an em-dash for null/undefined values and "Invalid date" for unparseable input.
+ *
+ * @param props - See {@link DateFieldProps}.
+ * @returns A `<time>` element with the formatted date, or a placeholder `<span>`.
+ *
+ * @example
+ * ```tsx
+ * <DateField value={post.createdAt} format="relative" />
+ * // -> "3 days ago"
+ *
+ * <DateField value="2026-03-11" format="short" locale="en" />
+ * // -> "Mar 11, 2026"
+ * ```
+ */
+declare function DateField({ value, format, locale, }: DateFieldProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Read-only display component that renders a boolean value as a colored chip.
+ *
+ * Uses the plugin's `chip` slot (via {@link useComponent}) for styling.
+ * Displays customizable labels and colors for `true` and `false` states.
+ * Returns an em-dash for null/undefined values.
+ *
+ * @param props - See {@link BooleanFieldProps}.
+ * @returns A styled chip element, or a placeholder `<span>` for null values.
+ *
+ * @example
+ * ```tsx
+ * <BooleanField value={post.published} trueLabel="Published" falseLabel="Draft" />
+ * // -> Green chip: "Published" or neutral chip: "Draft"
+ * ```
+ */
+declare function BooleanField({ value, trueLabel, falseLabel, trueColor, falseColor, }: BooleanFieldProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Read-only display component that formats numeric values.
+ *
+ * Uses `Intl.NumberFormat` for locale-aware formatting. Supports currency
+ * display and decimal precision control. Returns an em-dash for null/undefined values.
+ *
+ * @param props - See {@link NumberFieldProps}.
+ * @returns A `<span>` with the formatted number, or a placeholder for null values.
+ *
+ * @example
+ * ```tsx
+ * <NumberField value={1234.5} locale="en" />
+ * // -> "1,234.5"
+ *
+ * <NumberField value={29.99} currency="USD" />
+ * // -> "$29.99"
+ * ```
+ */
+declare function NumberField({ value, locale, currency, decimals, }: NumberFieldProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Read-only display component for plain text values.
+ *
+ * Optionally truncates long strings at `maxLength` characters with an ellipsis
+ * and shows the full text in a `title` tooltip on hover. Returns an em-dash
+ * for null/undefined values.
+ *
+ * @param props - See {@link TextFieldProps}.
+ * @returns A `<span>` with the text content, or a placeholder for null values.
+ *
+ * @example
+ * ```tsx
+ * <TextField value={post.title} maxLength={50} />
+ * // -> Truncated with tooltip if longer than 50 characters
+ * ```
+ */
+declare function TextField({ value, maxLength, }: TextFieldProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Read-only display component that renders an email address as a clickable `mailto:` link.
+ *
+ * Returns an em-dash for null/undefined values.
+ *
+ * @param props - See {@link EmailFieldProps}.
+ * @returns An `<a>` element with a `mailto:` href, or a placeholder `<span>` for null values.
+ *
+ * @example
+ * ```tsx
+ * <EmailField value={user.email} />
+ * // -> <a href="mailto:user@example.com">user@example.com</a>
+ * ```
+ */
+declare function EmailField({ value }: EmailFieldProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Read-only display component that renders a URL as an external link.
+ *
+ * Opens in a new tab with `rel="noopener noreferrer"` and appends an arrow
+ * indicator. When `truncate` is enabled, displays only the hostname and path
+ * instead of the full URL. Returns an em-dash for null/undefined values.
+ *
+ * @param props - See {@link UrlFieldProps}.
+ * @returns An `<a>` element with `target="_blank"`, or a placeholder `<span>` for null values.
+ *
+ * @example
+ * ```tsx
+ * <UrlField value="https://example.com/blog/post-1" truncate />
+ * // -> "example.com/blog/post-1 (arrow icon)"
+ * ```
+ */
+declare function UrlField({ value, truncate }: UrlFieldProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Read-only display component that renders an image thumbnail.
+ *
+ * Displays the image at the specified dimensions with `object-fit: cover` and
+ * rounded corners. Returns an em-dash for null/undefined values.
+ *
+ * @param props - See {@link ImageFieldProps}.
+ * @returns An `<img>` element, or a placeholder `<span>` for null values.
+ *
+ * @example
+ * ```tsx
+ * <ImageField value={post.coverImageUrl} width={120} height={80} alt="Cover" />
+ * ```
+ */
+declare function ImageField({ value, width, height, alt, }: ImageFieldProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Read-only display component that renders a file reference with an icon,
+ * display name, and optional formatted file size.
+ *
+ * Uses `fileName` if provided, otherwise falls back to the raw `value` string.
+ * File sizes are formatted as B/KB/MB. Returns an em-dash for null/undefined values.
+ *
+ * @param props - See {@link FileFieldProps}.
+ * @returns A `<span>` with a file icon, name, and size, or a placeholder for null values.
+ *
+ * @example
+ * ```tsx
+ * <FileField value="report.pdf" fileName="Q4 Report.pdf" fileSize={2048576} />
+ * // -> "Q4 Report.pdf (2.0 MB)"
+ * ```
+ */
+declare function FileField({ value, fileName, fileSize, }: FileFieldProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Read-only display component for related record references.
+ *
+ * Extracts the display property (defaults to `"name"`) from the related record
+ * object and renders it as plain text or a link. When `linkTo` is provided,
+ * the `:id` placeholder is replaced with the record's `id` to form the href.
+ * Returns an em-dash for null/undefined values.
+ *
+ * @param props - See {@link RelationFieldProps}.
+ * @returns An `<a>` element if `linkTo` is set and the record has an `id`,
+ *   a plain `<span>` otherwise, or a placeholder for null values.
+ *
+ * @example
+ * ```tsx
+ * <RelationField value={post.author} display="name" linkTo="/users/:id" />
+ * // -> <a href="/users/abc123">Jane Doe</a>
+ * ```
+ */
+declare function RelationField({ value, display, linkTo, }: RelationFieldProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Read-only display component that renders a JSON value as formatted code.
+ *
+ * When `collapsed` is true, shows a single-line preview (truncated at 60 chars)
+ * with an "expand" button. When expanded, displays the full pretty-printed JSON
+ * in a `<pre>` block. Returns an em-dash for null/undefined values.
+ *
+ * @param props - See {@link JsonFieldProps}.
+ * @returns A `<pre>` with formatted JSON, a collapsed preview, or a
+ *   placeholder `<span>` for null values.
+ *
+ * @example
+ * ```tsx
+ * <JsonField value={{ tags: ["react", "typescript"] }} collapsed />
+ * // -> '{"tags":["react","typescript"]}' with expand button
+ * ```
+ */
+declare function JsonField({ value, collapsed, }: JsonFieldProps): react_jsx_runtime.JSX.Element;
+
+type ColumnMeta = {
+    dataType: string;
+    name: string;
+};
+/**
+ * Maps a Drizzle column's metadata to the appropriate TypedField component.
+ *
+ * Inspects the column's `dataType` and `name` to determine the best display
+ * component. The mapping follows these rules:
+ *
+ * - `boolean` or integer columns named `is*` -> {@link BooleanField}
+ * - Columns containing `timestamp`, `date`, or `datetime` -> {@link DateField}
+ * - Numeric types (`integer`, `real`, `float`, etc.) -> {@link NumberField}
+ * - Columns named `email` or `*Email` -> {@link EmailField}
+ * - `json`, `jsonb`, or `blob` -> {@link JsonField}
+ * - Everything else -> {@link TextField}
+ *
+ * @param column - Drizzle column metadata with `dataType` and `name` properties.
+ * @returns A React component suitable for displaying the column's values.
+ *
+ * @example
+ * ```ts
+ * import { fieldForColumn } from "@cfast/ui";
+ *
+ * const Field = fieldForColumn({ dataType: "timestamp", name: "createdAt" });
+ * // Field === DateField
+ * ```
+ */
+declare function fieldForColumn(column: ColumnMeta): FieldComponent;
+/**
+ * Given a Drizzle table, returns a map of column names to their inferred
+ * TypedField components.
+ *
+ * Iterates over the table's entries, identifies columns by duck-typing
+ * (`dataType` and `name` properties), and delegates to {@link fieldForColumn}
+ * for each one.
+ *
+ * @param table - A Drizzle table object whose entries expose column metadata.
+ * @returns A record mapping column key names to field component types. Each
+ *   component accepts {@link BaseFieldProps} and a `value` prop.
+ *
+ * @example
+ * ```ts
+ * import { fieldsForTable } from "@cfast/ui";
+ * import { posts } from "~/db/schema";
+ *
+ * const fields = fieldsForTable(posts);
+ * // fields.title === TextField
+ * // fields.createdAt === DateField
+ * // fields.published === BooleanField
+ *
+ * const TitleField = fields.title;
+ * <TitleField value={post.title} />;
+ * ```
+ */
+declare function fieldsForTable(table: {
+    [Symbol.iterator]?: never;
+} & Record<string, unknown>): Record<string, FieldComponent>;
+
+/**
+ * Permission-aware empty state placeholder.
+ *
+ * Adapts its content based on the user's permissions for the create action:
+ *
+ * - **Permitted**: shows title, description, and a CTA button
+ * - **Forbidden**: shows title and description without the CTA
+ * - **Invisible**: shows a generic "Nothing here yet" message
+ * - **No createAction**: shows title and description only
+ *
+ * @param props - See {@link EmptyStateProps}.
+ *
+ * @example
+ * ```tsx
+ * <EmptyState
+ *   title="No posts yet"
+ *   description="Create your first blog post to get started."
+ *   createAction={createPost.client}
+ *   createLabel="New Post"
+ *   icon={DocumentIcon}
+ * />
+ * ```
+ */
+declare function EmptyState({ title, description, createAction, createLabel, icon: Icon, }: EmptyStateProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Thin progress bar fixed to the top of the viewport during React Router navigation.
+ *
+ * Uses `useNavigation().state` from React Router to detect loading transitions.
+ * Visible when `state === "loading"`, hidden when `state === "idle"`. No
+ * configuration is required beyond dropping it into your root layout.
+ *
+ * @param props - See {@link NavigationProgressProps}.
+ *
+ * @example
+ * ```tsx
+ * // In your root layout:
+ * <NavigationProgress />
+ *
+ * // With custom color:
+ * <NavigationProgress color="#e91e63" />
+ * ```
+ */
+declare function NavigationProgress({ color, }: NavigationProgressProps): react_jsx_runtime.JSX.Element | null;
+
+type PageContainerProps = {
+    title?: string;
+    breadcrumb?: BreadcrumbItem[];
+    actions?: ReactNode;
+    tabs?: TabItem[];
+    children: ReactNode;
+};
+/**
+ * Page wrapper providing a title, breadcrumb trail, tab navigation, and an action toolbar.
+ *
+ * Renders via the UI plugin's `pageContainer` and `breadcrumb` slots. Used internally
+ * by {@link ListView} and {@link DetailView}, but also useful as a standalone page shell
+ * for custom pages.
+ *
+ * @param props - See {@link PageContainerProps}.
+ *
+ * @example
+ * ```tsx
+ * <PageContainer
+ *   title="Edit Post"
+ *   breadcrumb={[
+ *     { label: "Posts", to: "/posts" },
+ *     { label: post.title },
+ *   ]}
+ *   actions={<ActionButton action={deletePost} input={{ postId }} />}
+ * >
+ *   ...
+ * </PageContainer>
+ * ```
+ */
+declare function PageContainer({ title, breadcrumb, actions, tabs: _tabs, children, }: PageContainerProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Base application layout with sidebar navigation, header, and content area.
+ *
+ * Delegates rendering to the UI plugin's `appShell` slot. Compose with
+ * {@link AppShellSidebar} (`AppShell.Sidebar`) and {@link AppShellHeader}
+ * (`AppShell.Header`) for a complete layout.
+ *
+ * @param props - See {@link AppShellProps}.
+ *
+ * @example
+ * ```tsx
+ * <AppShell
+ *   sidebar={<AppShell.Sidebar items={navigationItems} />}
+ *   header={<AppShell.Header userMenu={<UserMenu />} />}
+ * >
+ *   {children}
+ * </AppShell>
+ * ```
+ */
+declare function AppShell({ children, sidebar, header }: AppShellProps): react_jsx_runtime.JSX.Element;
+declare namespace AppShell {
+    var Sidebar: typeof AppShellSidebar;
+    var Header: typeof AppShellHeader;
+}
+/**
+ * Sidebar navigation for {@link AppShell} that automatically filters items by permission.
+ *
+ * Each {@link NavigationItem} can optionally carry an `action` descriptor. Items whose
+ * action is invisible or forbidden are hidden from the sidebar automatically.
+ *
+ * @param props.items - Navigation items to render.
+ *
+ * @example
+ * ```tsx
+ * <AppShell.Sidebar items={[
+ *   { label: "Posts", to: "/posts", icon: DocumentIcon },
+ *   { label: "Users", to: "/users", icon: UsersIcon, action: manageUsers.client },
+ * ]} />
+ * ```
+ */
+declare function AppShellSidebar({ items }: {
+    items: NavigationItem[];
+}): react_jsx_runtime.JSX.Element;
+/**
+ * Header bar for {@link AppShell} with flexible content and an optional user menu.
+ *
+ * Renders a horizontal bar at the top of the shell. Pass a {@link UserMenu}
+ * element via the `userMenu` prop for authenticated user controls.
+ *
+ * @param props.children - Custom header content (logo, search, etc.).
+ * @param props.userMenu - User menu element rendered at the far right.
+ *
+ * @example
+ * ```tsx
+ * <AppShell.Header userMenu={<UserMenu links={[{ label: "Profile", to: "/profile" }]} />}>
+ *   <Logo />
+ * </AppShell.Header>
+ * ```
+ */
+declare function AppShellHeader({ children, userMenu, }: {
+    children?: ReactNode;
+    userMenu?: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+/**
+ * Header dropdown showing the current user's avatar, name, email, role badges, and navigation links.
+ *
+ * Reads the authenticated user via `useCurrentUser()` from `@cfast/auth`. Renders
+ * an {@link AvatarWithInitials} trigger and a dropdown with user info, {@link RoleBadge}
+ * chips, permission-filtered navigation links, and an optional sign-out button.
+ * Returns `null` when no user is authenticated.
+ *
+ * @param props - See {@link UserMenuProps}.
+ *
+ * @example
+ * ```tsx
+ * <UserMenu
+ *   links={[
+ *     { label: "Profile", to: "/profile" },
+ *     { label: "Admin", to: "/admin", action: adminAccess.client },
+ *   ]}
+ *   onSignOut={() => signOut()}
+ * />
+ * ```
+ */
+declare function UserMenu({ links, onSignOut, }: UserMenuProps): react_jsx_runtime.JSX.Element | null;
+
+export { AppShell, AppShellHeader, AppShellProps, AppShellSidebar, BooleanField, BooleanFieldProps, BreadcrumbItem, DateField, DateFieldProps, EmailField, EmailFieldProps, EmptyState, EmptyStateProps, FileField, FileFieldProps, ImageField, ImageFieldProps, JsonField, JsonFieldProps, NavigationItem, NavigationProgress, NavigationProgressProps, NumberField, NumberFieldProps, PageContainer, RelationField, RelationFieldProps, TabItem, TextField, TextFieldProps, UrlField, UrlFieldProps, UserMenu, UserMenuProps, fieldForColumn, fieldsForTable };