@cfast/ui 0.0.1 → 0.2.0

package/dist/index.d.ts

@@ -1,9 +1,8 @@
-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 { 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 './client-CIx8_tmv.js';
+export { h as ActionButton, i as ActionButtonProps, j as AlertSlotProps, k as AppShellSlotProps, l as AvatarWithInitials, m as AvatarWithInitialsProps, n as BaseFieldProps, o as BreadcrumbSlotProps, p as BulkAction, q as BulkActionBar, r as ButtonSlotProps, C as ChipSlotProps, s as ColumnDef, t as ColumnShorthand, u as ConfirmDialogSlotProps, v as ConfirmOptions, w as ConfirmProvider, x as DataTable, y as DataTableProps, z as DetailView, G as DetailViewProps, H as DropZone, K as DropZoneProps, L as DropZoneSlotProps, M as FileList, O as FileListFile, P as FileListProps, Q as FilterBar, S as FilterBarProps, V as FilterDef, W as FilterOption, X as FilterType, Y as FormStatus, Z as FormStatusData, _ as FormStatusProps, $ as ImagePreview, a0 as ImagePreviewProps, a1 as ImpersonationBanner, a2 as ImpersonationBannerProps, a3 as ListView, a4 as ListViewProps, a5 as PageContainerSlotProps, a6 as PermissionGate, a7 as PermissionGateProps, a8 as RoleBadge, a9 as RoleBadgeProps, aa as SidebarSlotProps, ab as TableCellSlotProps, ac as TableRowSlotProps, ad as TableSectionSlotProps, ae as TableSlotProps, af as ToastApi, ag as ToastContext, ah as ToastOptions, ai as ToastSlotProps, aj as ToastType, ak as TooltipSlotProps, al as UIPlugin, am as UIPluginComponents, an as UIPluginProvider, ao as UserMenuLink, ap as WhenForbidden, 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 * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-import '@cfast/actions/client';
+import { ClientDescriptor, ActionHookResult } from '@cfast/actions/client';
 
 /**
  * Read-only display component that formats date values.
@@ -412,4 +411,52 @@ declare function AppShellHeader({ children, userMenu, }: {
  */
 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 };
+/**
+ * Safely retrieves a property from an unknown record-like value by string key.
+ *
+ * Isolates the single unavoidable `Record<string, unknown>` assertion needed
+ * when accessing dynamic keys on generic row/record objects (e.g., in DataTable
+ * and DetailView). Using this helper keeps the rest of the codebase cast-free.
+ *
+ * Returns `undefined` for non-object or null values.
+ *
+ * @param obj - A value expected to be a record-like object.
+ * @param key - The property name to look up.
+ * @returns The property value, or `undefined` if the key does not exist or obj is not an object.
+ *
+ * @internal
+ */
+declare function getField(obj: unknown, key: string): unknown;
+/**
+ * Extracts a string or number `id` from an unknown value.
+ *
+ * Returns the `id` property when it is a `string` or `number`, otherwise
+ * falls back to `0`. Isolates the dynamic-key access so callers avoid casts.
+ *
+ * @param obj - A value expected to be a record-like object with an `id` property.
+ * @returns The `id` value as a `string | number`, or `0` if missing/wrong type.
+ *
+ * @internal
+ */
+declare function getRecordId(obj: unknown): string | number;
+
+/**
+ * Returns the permission status and submit function for the first action in a descriptor.
+ *
+ * Convenience wrapper around `useActions()` for single-action descriptors
+ * (e.g. a create action passed to EmptyState or a navigation item guard).
+ *
+ * @param descriptor - Client-side action descriptor from `@cfast/actions`
+ * @returns The ActionHookResult with `permitted`, `invisible`, `pending`, and `submit`
+ *
+ * @example
+ * ```ts
+ * const status = useActionStatus(createPost.client);
+ * if (status.permitted) {
+ *   status.submit({ title: "New Post" });
+ * }
+ * ```
+ */
+declare function useActionStatus(descriptor: ClientDescriptor): ActionHookResult;
+
+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, getField, getRecordId, useActionStatus };

package/dist/index.js

@@ -1,43 +1,43 @@
 import {
   ActionButton,
+  AvatarWithInitials,
+  BooleanField,
   BulkActionBar,
   ConfirmProvider,
   DataTable,
+  DateField,
   DetailView,
   DropZone,
+  EmailField,
   EmptyState,
   FileList,
   FilterBar,
   FormStatus,
   ImagePreview,
   ImpersonationBanner,
-  ListView,
-  PageContainer,
-  RoleBadge,
-  useActionToast,
-  useColumnInference,
-  useConfirm
-} from "./chunk-JEGEIQ3R.js";
-import {
-  AvatarWithInitials,
-  BooleanField,
-  DateField,
-  EmailField,
   JsonField,
+  ListView,
   NumberField,
+  PageContainer,
   PermissionGate,
+  RoleBadge,
   TextField,
+  ToastContext,
   UIPluginProvider,
   createUIPlugin,
   fieldForColumn,
   fieldsForTable,
   getField,
   getInitials,
+  getRecordId,
   useActionStatus,
+  useActionToast,
+  useColumnInference,
   useComponent,
+  useConfirm,
   useToast,
   useUIPlugin
-} from "./chunk-RDTUEOLK.js";
+} from "./chunk-PWBG6CGF.js";
 
 // src/fields/url-field.tsx
 import { jsx, jsxs } from "react/jsx-runtime";
@@ -280,13 +280,17 @@ export {
   RelationField,
   RoleBadge,
   TextField,
+  ToastContext,
   UIPluginProvider,
   UrlField,
   UserMenu,
   createUIPlugin,
   fieldForColumn,
   fieldsForTable,
+  getField,
   getInitials,
+  getRecordId,
+  useActionStatus,
   useActionToast,
   useColumnInference,
   useComponent,

package/llms.txt

@@ -0,0 +1,159 @@
+# @cfast/ui
+
+> Permission-aware UI components for cfast apps: data tables, page shells, typed fields, file uploads, and action feedback -- all wired to the framework.
+
+## When to use
+
+Use `@cfast/ui` when building data-driven pages in a cfast app. It sits between your primitive component library (MUI Joy UI) and your application code, providing "smart" components that integrate with `@cfast/db`, `@cfast/actions`, `@cfast/permissions`, `@cfast/pagination`, `@cfast/auth`, and `@cfast/storage`.
+
+Import styled components from `@cfast/joy`. Import headless components and hooks from `@cfast/ui`.
+
+## Key concepts
+
+- **Headless core + UI plugins**: `@cfast/ui` exports hooks and logic. `@cfast/joy` exports Joy UI styled implementations. Custom plugins can provide other UI libraries via `createUIPlugin()`.
+- **Permission-aware**: Components like `ActionButton`, `PermissionGate`, `EmptyState`, sidebar nav items, and `BulkActionBar` automatically hide/disable based on `@cfast/actions` permission status.
+- **Schema-driven**: Pass a Drizzle `table` to `DataTable`, `FilterBar`, `DetailView`, or `useColumnInference()` and columns/fields/filters are inferred from column types.
+- **URL-synced**: `FilterBar` serializes filter state to URL search params. `DataTable` sorting syncs to URL params. Both work with `@cfast/pagination`'s `parseParams()` in loaders.
+
+## API Reference
+
+### Hooks (from `@cfast/ui`)
+
+```typescript
+useActionStatus(descriptor: ClientDescriptor): ActionHookResult
+// Returns { permitted, invisible, pending, submit } for a single action.
+
+useToast(): ToastApi
+// Returns { show, success, error, info, warning } methods. Requires <ToastProvider>.
+
+useActionToast(descriptor: ClientDescriptor, config: Record<string, { success?: string; error?: string }>): void
+// Auto-shows toasts when action results arrive.
+
+useConfirm(): ConfirmFn
+// Returns async (options: ConfirmOptions) => Promise<boolean>. Requires <ConfirmProvider>.
+
+useColumnInference(table: Record<string, unknown> | undefined, columns?: string[]): InferredColumn[]
+// Maps Drizzle table columns to TypedField components. Memoized.
+```
+
+### Components (from `@cfast/joy`)
+
+**Data display:**
+- `DataTable` -- table with sorting, selection, row actions, skeleton loading. Accepts `data` (pagination result), `table` (Drizzle), `columns`, `actions`, `selectable`.
+- `FilterBar` -- URL-synced filters. Accepts `table`, `filters` (array of FilterDef), `searchable`.
+- `ListView` -- full page: title + filters + data table + pagination + empty state + bulk actions.
+- `DetailView` -- read-only detail page for a single record. Auto-lays out TypedFields.
+
+**Layout:**
+- `AppShell` -- sidebar + header + content. Sub-components: `AppShellSidebar`, `AppShellHeader`.
+- `PageContainer` -- title + breadcrumb + tabs + action toolbar.
+- `UserMenu` -- header dropdown with avatar, role badge, auth actions.
+- `NavigationProgress` -- thin progress bar during React Router navigation.
+
+**Actions & feedback:**
+- `ActionButton` -- permission-aware button wrapping a `@cfast/actions` action. Props: `action`, `input`, `whenForbidden: "hide" | "disable" | "show"`, `confirmation`.
+- `PermissionGate` -- conditional render based on action permissions. Props: `action`, `input`, `fallback`.
+- `ConfirmDialog` -- standalone confirmation dialog.
+- `ToastProvider` -- mount once in root layout for toast notifications.
+- `FormStatus` -- renders success/error/validation from action results.
+- `BulkActionBar` -- toolbar for selected rows with bulk actions.
+
+**Files:**
+- `DropZone` -- drag-and-drop upload. Integrates with `@cfast/storage`'s `useUpload()`.
+- `ImagePreview` -- displays image from storage with signed URL handling.
+- `FileList` -- list of uploaded files with download/delete.
+
+**Utilities:**
+- `AvatarWithInitials` -- avatar with automatic initials fallback.
+- `RoleBadge` -- colored chip for user role.
+- `ImpersonationBanner` -- persistent banner when impersonating.
+- `EmptyState` -- permission-aware empty state with optional create CTA.
+
+### TypedField components (from `@cfast/ui`)
+
+```typescript
+DateField, BooleanField, NumberField, TextField,
+EmailField, UrlField, ImageField, FileField,
+RelationField, JsonField
+fieldForColumn(columnMeta): ComponentType  // maps Drizzle column type to field
+fieldsForTable(table): Record<string, ComponentType>  // field map for whole table
+```
+
+### Plugin API
+
+```typescript
+createUIPlugin({ components: { button, tooltip, table, ... } }): UIPlugin
+UIPluginProvider  // React provider for custom UI plugins
+useUIPlugin(): UIPlugin
+useComponent(slotName: string): ComponentType
+```
+
+## Usage Examples
+
+### Full list page
+
+```typescript
+import { ListView } from "@cfast/joy";
+import { usePagination } from "@cfast/pagination";
+import { posts } from "~/db/schema";
+
+function PostsPage() {
+  const pagination = usePagination<Post>();
+  return (
+    <ListView
+      title="Blog Posts"
+      data={pagination}
+      table={posts}
+      columns={["title", "author", "published", "createdAt"]}
+      actions={composed.client}
+      filters={[{ column: "published", type: "select", options: publishedOptions }]}
+      searchable={["title", "content"]}
+      createAction={createPost.client}
+      selectable
+    />
+  );
+}
+```
+
+### Permission-aware button with confirmation
+
+```typescript
+import { ActionButton } from "@cfast/joy";
+
+<ActionButton
+  action={deletePost}
+  input={{ postId }}
+  whenForbidden="disable"
+  confirmation="Delete this post?"
+>
+  Delete
+</ActionButton>
+```
+
+### Auto-toast on action results
+
+```typescript
+import { useActionToast } from "@cfast/ui";
+
+useActionToast(composed.client, {
+  deletePost: { success: "Post deleted", error: "Failed to delete" },
+  publishPost: { success: "Post published" },
+});
+```
+
+## Integration
+
+- **@cfast/actions** -- `ActionButton`, `PermissionGate`, `BulkActionBar`, `useActionToast` consume action descriptors.
+- **@cfast/pagination** -- `DataTable` and `ListView` accept pagination hook results. `FilterBar` serializes to URL params that `parseParams()` reads.
+- **@cfast/db** -- Drizzle schema drives column inference, filter type inference, and field type inference.
+- **@cfast/auth** -- `UserMenu` reads `useCurrentUser()`. `ImpersonationBanner` reads impersonation state.
+- **@cfast/storage** -- `DropZone` integrates with `useUpload()`. `ImagePreview`/`FileList` use storage URLs.
+- **@cfast/admin** -- Admin uses `ListView`, `DetailView`, `DataTable`, `FilterBar`, `AppShell`, etc. Admin generates config; UI renders pixels.
+
+## Common Mistakes
+
+- Importing from `@cfast/joy` on the server -- Joy components are client-only. Use headless exports from `@cfast/ui` for server-safe code.
+- Forgetting `<ToastProvider>` in root layout -- `useToast()` and `useActionToast()` throw without it.
+- Forgetting `<ConfirmProvider>` -- `useConfirm()` and `ActionButton` with `confirmation` need it.
+- Passing raw data arrays to `DataTable` instead of a pagination result from `usePagination()`.
+- Using `whenForbidden="show"` on `ActionButton` when you mean `"disable"` -- `"show"` renders even when forbidden with no visual indicator.

package/package.json

@@ -1,7 +1,14 @@
 {
   "name": "@cfast/ui",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "description": "Permission-aware React components with UI library plugins",
+  "keywords": [
+    "cfast",
+    "cloudflare-workers",
+    "react",
+    "ui",
+    "permissions"
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -16,52 +23,40 @@
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
     },
-    "./joy": {
-      "import": "./dist/joy.js",
-      "types": "./dist/joy.d.ts"
-    },
     "./client": {
       "import": "./dist/client.js",
       "types": "./dist/client.d.ts"
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "llms.txt"
   ],
   "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "build": "tsup src/index.ts src/client.ts --format esm --dts",
+    "dev": "tsup src/index.ts src/client.ts --format esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "test": "vitest run"
+  },
   "peerDependencies": {
-    "@mui/joy": ">=5.0.0-beta.0",
     "react": ">=19",
     "react-dom": ">=19",
-    "react-router": ">=7",
-    "sonner": ">=2"
-  },
-  "peerDependenciesMeta": {
-    "@mui/joy": {
-      "optional": true
-    },
-    "sonner": {
-      "optional": true
-    }
+    "react-router": ">=7"
   },
   "dependencies": {
-    "@cfast/actions": "0.0.1",
-    "@cfast/db": "0.0.1",
-    "@cfast/permissions": "0.0.1",
-    "@cfast/auth": "0.0.1",
-    "@cfast/storage": "0.0.1",
-    "@cfast/pagination": "0.0.1"
+    "@cfast/actions": "workspace:*",
+    "@cfast/auth": "workspace:*",
+    "@cfast/db": "workspace:*",
+    "@cfast/pagination": "workspace:*",
+    "@cfast/permissions": "workspace:*",
+    "@cfast/storage": "workspace:*"
   },
   "devDependencies": {
-    "@emotion/react": "^11.14.0",
-    "@emotion/styled": "^11.14.1",
-    "@mui/joy": "^5.0.0-beta.52",
-    "@mui/material": "^6.5.0",
-    "@storybook/react": "^8.6.14",
-    "@storybook/react-vite": "^8.6.14",
     "@testing-library/react": "^16.3.0",
     "@types/react": "^19.1.6",
     "@types/react-dom": "^19.1.6",
@@ -70,19 +65,8 @@
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "react-router": "^7.12.0",
-    "sonner": "^2.0.3",
-    "storybook": "^8.6.14",
     "tsup": "^8",
     "typescript": "^5.7",
     "vitest": "^4.1.0"
-  },
-  "scripts": {
-    "build": "tsup src/index.ts src/joy.ts src/client.ts --format esm --dts",
-    "dev": "tsup src/index.ts src/joy.ts src/client.ts --format esm --dts --watch",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src/",
-    "test": "vitest run",
-    "storybook": "storybook dev -p 6006",
-    "build-storybook": "storybook build"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Daniel Schmidt
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.