@questpie/admin 3.0.3 → 3.0.5

package/README.md

@@ -8,7 +8,7 @@ QUESTPIE follows a **server-first** architecture. All schema, layout, and behavi
 
 | Layer      | Package                               | Defines                                                           |
 | ---------- | ------------------------------------- | ----------------------------------------------------------------- |
-| **Server** | `questpie` + `@questpie/admin/server` | Schema, fields, access, hooks, sidebar, dashboard, branding       |
+| **Server** | `questpie` + `@questpie/admin/server` | Schema, fields, access, hooks, sidebar, dashboard, branding name  |
 | **Client** | `@questpie/admin/client`              | Field renderers, view renderers, component registry, UI overrides |
 
 ## Installation
@@ -39,7 +39,7 @@ import { adminModule } from "@questpie/admin/server";
 export default [adminModule] as const;
 ```
 
-Branding, sidebar, dashboard, and admin locale are configured via `config/admin.ts`:
+Branding name, sidebar, dashboard, and admin locale are configured via `config/admin.ts`:
 
 ```ts
 // config/admin.ts
@@ -255,15 +255,44 @@ export default function AdminRoute() {
 
 ### 4. Tailwind CSS
 
-Import admin styles and scan the admin package:
+Import the admin base stylesheet and scan the admin package:
 
 ```css
 @import "tailwindcss";
-@import "@questpie/admin/styles/index.css";
+@import "@questpie/admin/client/styles/index.css";
 
 @source "../node_modules/@questpie/admin/dist";
 ```
 
+`index.css` is an alias for `base.css`; import `base.css` directly when you want explicit control.
+
+## Chrome Overrides (File-First)
+
+Place component files in `questpie/admin/components/` to override specific UI chrome without changing your app shell:
+
+| File                         | What it overrides                      |
+| ---------------------------- | -------------------------------------- |
+| `admin-sidebar-brand.tsx`    | Sidebar logo + name area               |
+| `admin-sidebar-nav-item.tsx` | Each navigation item row               |
+| `admin-auth-layout.tsx`      | Auth page wrapper (login, reset, etc.) |
+
+```tsx title="questpie/admin/components/admin-sidebar-brand.tsx"
+import type { AdminSidebarBrandProps } from "@questpie/admin/client";
+
+export default function MyBrand({ name, collapsed }: AdminSidebarBrandProps) {
+	return (
+		<div className="flex items-center gap-2">
+			<img src="/logo.svg" alt={name} className="size-6 shrink-0" />
+			{!collapsed && <span className="font-bold">{name}</span>}
+		</div>
+	);
+}
+```
+
+These files are discovered by codegen exactly like any other component file — no factory call needed, just a default export.
+
+For these reserved override files, default-export a React component (sync or `React.lazy(...)`). Do **not** default-export a raw `() => import("...")` loader function.
+
 ## Block Editor
 
 The admin includes a full drag-and-drop block editor. Blocks are defined server-side:
@@ -353,7 +382,7 @@ import {
 import { adminModule, auditModule } from "@questpie/admin/server";
 
 // Styles
-import "@questpie/admin/styles/index.css";
+import "@questpie/admin/client/styles/index.css";
 ```
 
 ## Component Stack

package/dist/client/blocks/block-renderer.d.mts

@@ -1,6 +1,6 @@
 import { BlockContent } from "./types.mjs";
 import * as React from "react";
-import * as react_jsx_runtime17 from "react/jsx-runtime";
+import * as react_jsx_runtime19 from "react/jsx-runtime";
 
 //#region src/client/blocks/block-renderer.d.ts
 
@@ -40,6 +40,6 @@ declare function BlockRenderer({
   selectedBlockId,
   onBlockClick,
   className
-}: BlockRendererProps): react_jsx_runtime17.JSX.Element | null;
+}: BlockRendererProps): react_jsx_runtime19.JSX.Element | null;
 //#endregion
 export { BlockRenderer, BlockRendererProps };

package/dist/client/blocks/block-renderer.mjs

@@ -22,7 +22,7 @@ function BlockRenderer(t0) {
 		t3 = Symbol.for("react.early_return_sentinel");
 		bb0: {
 			function renderBlock(node) {
-				const renderFn = renderers[node.type];
+				const renderFn = renderers[node.type] ?? renderers[kebabToCamelCase(node.type)];
 				if (!renderFn) {
 					if (process.env.NODE_ENV !== "production") console.warn(`[BlockRenderer] No renderer found for block type "${node.type}"`);
 					return null;
@@ -100,6 +100,9 @@ function BlockRenderer(t0) {
 	} else t4 = $[10];
 	return t4;
 }
+function kebabToCamelCase(value) {
+	return value.replace(/-([a-z])/g, (_, char) => char.toUpperCase());
+}
 
 //#endregion
 export { BlockRenderer };

package/dist/client/builder/types/action-types.d.mts

@@ -1,6 +1,6 @@
 import { I18nText } from "../../i18n/types.mjs";
 import { IconComponent, MaybeLazyComponent } from "./common.mjs";
-import { FieldDefinition } from "../field/field.mjs";
+import { FieldInstance } from "../field/field.mjs";
 import { ComponentReference } from "../../../server/augmentation/common.mjs";
 import "../../../server/augmentation.mjs";
 
@@ -127,7 +127,7 @@ interface ActionFormConfig<TItem = any> {
   /** Dialog description */
   description?: I18nText;
   /** Form fields using FieldDefinition */
-  fields: Record<string, FieldDefinition>;
+  fields: Record<string, FieldInstance>;
   /** Default values */
   defaultValues?: Record<string, any>;
   /** Submit handler */
@@ -222,5 +222,33 @@ interface ActionDefinition<TItem = any> {
   /** Confirmation dialog before executing */
   confirmation?: ConfirmationConfig;
 }
+/**
+ * Header actions configuration with primary/secondary split
+ *
+ * @example
+ * ```ts
+ * header: {
+ *   primary: [a.create()],           // Shown as buttons
+ *   secondary: [a.action({...})],    // Shown in dropdown menu
+ * }
+ * ```
+ */
+interface HeaderActionsConfig<TItem = any> {
+  /** Actions shown as buttons */
+  primary?: ActionDefinition<TItem>[];
+  /** Actions shown in dropdown menu */
+  secondary?: ActionDefinition<TItem>[];
+}
+/**
+ * Collection actions configuration for list views
+ */
+interface ActionsConfig<TItem = any> {
+  /** Actions displayed in the header area (create, import, etc.) */
+  header?: HeaderActionsConfig<TItem>;
+  /** Actions displayed per row in list/table views */
+  row?: ActionDefinition<TItem>[];
+  /** Actions for bulk operations on selected items (deleteMany, duplicate, etc.) */
+  bulk?: ActionDefinition<TItem>[];
+}
 //#endregion
-export { ActionDefinition };
+export { ActionDefinition, ActionsConfig };

package/dist/client/builder/types/collection-types.d.mts

@@ -0,0 +1,140 @@
+import "../../i18n/types.mjs";
+import { MaybeLazyComponent } from "./common.mjs";
+import "../field/field.mjs";
+import "../../../server/augmentation.mjs";
+import "../admin.mjs";
+import { ActionsConfig } from "./action-types.mjs";
+
+//#region src/client/builder/types/collection-types.d.ts
+
+/**
+ * Column configuration for list views
+ * Can be a simple field name or detailed config object
+ */
+type ColumnConfig<TFieldNames extends string = string> = TFieldNames | ColumnConfigObject<TFieldNames>;
+/**
+ * Detailed column configuration object
+ */
+interface ColumnConfigObject<TFieldNames extends string = string> {
+  /**
+   * Field name to display
+   */
+  field: TFieldNames;
+  /**
+   * Custom header label (defaults to field label)
+   */
+  header?: string;
+  /**
+   * Column width (CSS value like "200px", "20%", etc.)
+   */
+  width?: string | number;
+  /**
+   * Minimum column width
+   */
+  minWidth?: string | number;
+  /**
+   * Maximum column width
+   */
+  maxWidth?: string | number;
+  /**
+   * Enable sorting for this column
+   * @default true
+   */
+  sortable?: boolean;
+  /**
+   * Custom cell renderer component
+   * Overrides the field's default cell component
+   */
+  cell?: MaybeLazyComponent;
+  /**
+   * Column visibility
+   * Can be a boolean or function for conditional visibility
+   */
+  visible?: boolean | ((row: any) => boolean);
+  /**
+   * Custom CSS class for column cells
+   */
+  className?: string;
+  /**
+   * Text alignment
+   */
+  align?: "left" | "center" | "right";
+}
+/**
+ * List view configuration
+ */
+interface ListViewConfig<TFieldNames extends string = string> {
+  /**
+   * Columns to display (field names or column configs)
+   */
+  columns?: ColumnConfig<TFieldNames>[];
+  /**
+   * Relations to include in query
+   */
+  with?: string[];
+  /**
+   * Default sort
+   */
+  defaultSort?: {
+    field: TFieldNames;
+    direction: "asc" | "desc";
+  };
+  /**
+   * Enables reorder mode for this list.
+   * Requires a numeric field named `order` on the collection.
+   */
+  orderable?: boolean | {
+    direction?: "asc" | "desc";
+    step?: number;
+  };
+  /**
+   * Enable search
+   * @default true
+   */
+  searchable?: boolean;
+  /**
+   * Searchable fields (defaults to all text-like fields)
+   */
+  searchFields?: TFieldNames[];
+  /**
+   * Enable row selection
+   * @default false
+   */
+  selectable?: boolean;
+  /**
+   * Enable pagination
+   * @default true
+   */
+  paginated?: boolean;
+  /**
+   * Enable realtime invalidation for list queries.
+   * Falls back to AdminProvider realtime config when undefined.
+   */
+  realtime?: boolean;
+  /**
+   * Default page size
+   * @default 25
+   */
+  pageSize?: number;
+  /**
+   * Available page size options
+   * @default [10, 25, 50, 100]
+   */
+  pageSizeOptions?: number[];
+  /**
+   * Client-side grouping options for the current fetched page.
+   * Counts are page-local until a server aggregate API exists.
+   */
+  grouping?: {
+    fields: TFieldNames[];
+    defaultField?: TFieldNames;
+    defaultCollapsed?: boolean;
+    showCounts?: boolean;
+  };
+  /**
+   * Actions configuration for list view
+   */
+  actions?: ActionsConfig;
+}
+//#endregion
+export { ListViewConfig };

package/dist/client/builder/types/ui-config.d.mts

@@ -49,6 +49,8 @@ type DashboardLayoutItem = WidgetConfig | DashboardSection | DashboardTabs;
  */
 interface DashboardSection {
   type: "section";
+  /** Stable section ID */
+  id?: string;
   /** Section label */
   label?: DynamicI18nText;
   /** Section description */
@@ -63,6 +65,8 @@ interface DashboardSection {
   layout?: "grid" | "stack";
   /** Grid columns (for grid layout) */
   columns?: number;
+  /** Fixed row height for widgets in this section */
+  rowHeight?: number | string;
   /** Gap between items */
   gap?: number;
   /** Section items */
@@ -94,12 +98,14 @@ interface DashboardSection {
  */
 interface DashboardTabs {
   type: "tabs";
+  /** Stable tabs group ID */
+  id?: string;
   /** Tab configurations */
   tabs: DashboardTabConfig[];
   /** Default active tab ID */
   defaultTab?: string;
-  /** Tabs visual variant */
-  variant?: "default" | "line" | "pills";
+  /** Custom CSS class */
+  className?: string;
 }
 /**
  * Single tab configuration
@@ -113,6 +119,12 @@ interface DashboardTabConfig {
   icon?: IconComponent | ComponentReference;
   /** Tab items (widgets or sections) */
   items: DashboardLayoutItem[];
+  /** Grid columns for this tab */
+  columns?: number;
+  /** Fixed row height for widgets in this tab */
+  rowHeight?: number | string;
+  /** Gap between tab items */
+  gap?: number;
   /** Badge text (e.g., count) */
   badge?: string | number;
 }
@@ -128,6 +140,8 @@ interface DashboardConfig {
   description?: DynamicI18nText;
   /** Grid columns (default: 4) */
   columns?: number;
+  /** Fixed row height for dashboard widgets */
+  rowHeight?: number | string;
   /** Gap between widgets */
   gap?: number;
   /** Dashboard items - widgets, sections, or tabs */

package/dist/client/builder/types/views.d.mts

@@ -0,0 +1,57 @@
+import { ComponentRegistry, FormViewConfig } from "./field-types.mjs";
+import { ListViewConfig } from "./collection-types.mjs";
+import * as React from "react";
+
+//#region src/client/builder/types/views.d.ts
+type ViewBaseProps = {
+  navigate: (path: string) => void;
+  basePath?: string;
+  config?: Record<string, any>;
+  viewConfig?: ListViewConfig | FormViewConfig;
+  registry?: ComponentRegistry;
+};
+interface CollectionListViewProps {
+  collection: string;
+  baseFindOptions?: any;
+  realtime?: boolean;
+  headerActions?: React.ReactNode;
+  onRowClick?: (item: any) => void;
+  config?: ViewBaseProps["config"];
+  viewConfig?: ListViewConfig;
+  navigate: ViewBaseProps["navigate"];
+  basePath?: ViewBaseProps["basePath"];
+}
+interface CollectionFormViewProps {
+  collection: string;
+  id?: string;
+  title?: string;
+  headerActions?: React.ReactNode;
+  onSuccess?: (data?: any) => void;
+  onCancel?: () => void;
+  onError?: (error: Error) => void;
+  defaultValues?: Record<string, any>;
+  allCollectionsConfig?: Record<string, any>;
+  config?: ViewBaseProps["config"];
+  viewConfig?: FormViewConfig;
+  navigate: ViewBaseProps["navigate"];
+  basePath?: ViewBaseProps["basePath"];
+  registry?: ViewBaseProps["registry"];
+  children?: React.ReactNode;
+}
+interface GlobalFormViewProps {
+  global: string;
+  title?: string;
+  description?: string;
+  headerActions?: React.ReactNode;
+  onSuccess?: (data?: any) => void;
+  onError?: (error: Error) => void;
+  allGlobalsConfig?: Record<string, any>;
+  config?: ViewBaseProps["config"];
+  viewConfig?: FormViewConfig;
+  navigate: ViewBaseProps["navigate"];
+  basePath?: ViewBaseProps["basePath"];
+  registry?: ViewBaseProps["registry"];
+  children?: React.ReactNode;
+}
+//#endregion
+export { CollectionFormViewProps, CollectionListViewProps, GlobalFormViewProps };

package/dist/client/builder/types/widget-types.d.mts

@@ -42,6 +42,11 @@ interface BaseWidgetConfig {
    * Column span (1-12)
    */
   span?: number;
+  /**
+   * Row span in the dashboard tile grid.
+   * A widget with span=2 and rowSpan=2 renders as a 2x2 tile.
+   */
+  rowSpan?: number;
   /**
    * Grid position (for dashboard layouts)
    */