@questpie/admin 2.0.0 → 3.0.1

package/dist/client/builder/field/field.d.mts

@@ -1,229 +1,51 @@
-import { BaseFieldConfigProps, BaseFieldProps, MaybeLazyComponent } from "../types/common.mjs";
-import { FieldHookContext, SelectOption } from "../types/field-types.mjs";
-import { SetProperty } from "questpie/shared";
-import React from "react";
-import { z } from "zod";
+import { MaybeLazyComponent } from "../types/common.mjs";
 
 //#region src/client/builder/field/field.d.ts
 
 /**
- * Context provided to createZod callbacks for building nested schemas
- */
-interface ZodBuildContext {
-  /**
-   * Recursively builds a Zod schema for any field definition.
-   * Use this for nested fields in object/array types.
-   */
-  buildSchema: (fieldDef: FieldDefinition) => z.ZodTypeAny;
-  /**
-   * Field registry for resolving nested fields callbacks.
-   * Used to create the `r` proxy in `fields: ({ r }) => ({...})`
-   */
-  registry: Record<string, FieldBuilder<any>>;
-}
-/**
- * Function type for creating Zod schema from field options
- */
-type CreateZodFn<TOptions = any> = (opts: TOptions, ctx: ZodBuildContext) => z.ZodTypeAny;
-/**
- * Field state options (readOnly, disabled, hidden)
- */
-interface FieldStateOptions {
-  /**
-   * Whether field is read-only (can be dynamic based on form values).
-   * Read-only fields look normal but cannot be edited.
-   * Note: Fields with `compute` are automatically read-only.
-   */
-  readOnly?: boolean | ((values: Record<string, any>) => boolean);
-  /**
-   * Whether field is disabled (can be dynamic based on form values).
-   * Disabled fields appear grayed out and cannot be edited.
-   */
-  disabled?: boolean | ((values: Record<string, any>) => boolean);
-  /**
-   * Whether field is hidden (can be dynamic based on form values).
-   * Hidden fields are not rendered. Default is false (visible).
-   *
-   * Note: undefined/false = visible, true = hidden
-   * This follows JavaScript falsy semantics for better DX.
-   */
-  hidden?: boolean | ((values: Record<string, any>) => boolean);
-}
-/**
- * Hook options for field interactivity
- */
-interface FieldHookOptions {
-  /**
-   * Compute field value from other fields (proxy-tracked dependencies).
-   * Makes the field read-only and virtual (not submitted to backend).
-   *
-   * Dependencies are automatically detected via Proxy tracking.
-   * Works in both forms (reactive) and tables (static).
-   *
-   * @example
-   * ```ts
-   * pricePerMinute: r.number({
-   *   compute: (values) => values.price / values.duration,
-   * })
-   * ```
-   */
-  compute?: (values: Record<string, any>) => any;
-  /**
-   * Called when field value changes.
-   * Use for side effects like updating other fields.
-   * Can be async for API calls.
-   *
-   * @example
-   * ```ts
-   * name: r.text({
-   *   onChange: (value, { setValue }) => {
-   *     setValue('slug', slugify(value));
-   *   },
-   * })
-   * ```
-   */
-  onChange?: (value: any, ctx: FieldHookContext) => void | Promise<void>;
-  /**
-   * Dynamic default value for new records.
-   * Can be a static value, sync function, or async function.
-   * Only evaluated when creating new records (not on edit).
-   *
-   * @example
-   * ```ts
-   * status: r.select({
-   *   defaultValue: 'draft',
-   *   // or dynamic:
-   *   defaultValue: async () => fetchDefaultStatus(),
-   * })
-   * ```
-   */
-  defaultValue?: any | ((values: Record<string, any>) => any) | ((values: Record<string, any>) => Promise<any>);
-  /**
-   * Async options loader for select-type fields.
-   * Dependencies are automatically detected via Proxy tracking.
-   *
-   * @example
-   * ```ts
-   * subcategory: r.select({
-   *   loadOptions: async (values) => {
-   *     // Automatically re-fetches when values.category changes
-   *     return fetchSubcategories(values.category);
-   *   },
-   * })
-   * ```
-   */
-  loadOptions?: (values: Record<string, any>) => Promise<SelectOption[]>;
-}
-/**
- * UI options that can be set when defining a field in a collection.
- * These are the "soft" options from BaseFieldProps that make sense in config.
- */
-type FieldUIOptions = Partial<Pick<BaseFieldConfigProps, "label" | "description" | "placeholder" | "required"> & Pick<BaseFieldProps, "localized">> & FieldStateOptions & FieldHookOptions;
-/**
- * Field definition - stored in admin registry
+ * Field definition — a registry entry mapping a field type name to its components.
+ *
+ * This is what the admin module stores per field type. All field options
+ * (label, required, validation, etc.) come from server introspection at runtime,
+ * not from the FE definition.
  */
-interface FieldDefinition<TName extends string = string, TOptions = any> {
+interface FieldDefinition<TName extends string = string> {
   readonly name: TName;
-  readonly "~options": TOptions;
-  field: {
-    component: MaybeLazyComponent;
-  };
-  cell?: {
-    component: MaybeLazyComponent;
-  };
-  /**
-   * Creates a Zod schema from field options.
-   * If not provided, a generic schema based on field type will be used.
-   */
-  createZod?: CreateZodFn<TOptions>;
+  readonly component: MaybeLazyComponent;
+  readonly cell?: MaybeLazyComponent;
 }
 /**
- * Field builder state
+ * A field instance with runtime options from server introspection.
+ * Created by `configureField()` when mapping server metadata to field rendering.
  */
-interface FieldBuilderState {
+interface FieldInstance {
   readonly name: string;
-  readonly "~options": any;
   readonly component: MaybeLazyComponent;
-  readonly cellComponent?: MaybeLazyComponent;
-  readonly createZod?: CreateZodFn;
+  readonly cell?: MaybeLazyComponent;
+  readonly "~options": Record<string, unknown>;
 }
 /**
- * Field builder class
- *
- * Also implements FieldDefinition interface so it can be used directly in registries.
- */
-declare class FieldBuilder<TState extends FieldBuilderState> implements FieldDefinition<TState["name"], TState["~options"]> {
-  readonly state: TState;
-  constructor(state: TState);
-  get name(): TState["name"];
-  get "~options"(): TState["~options"];
-  get field(): {
-    component: MaybeLazyComponent;
-  };
-  get cell(): {
-    component: MaybeLazyComponent;
-  } | undefined;
-  get createZod(): CreateZodFn<TState["~options"]> | undefined;
-  /**
-   * Override options - returns new builder with updated state
-   */
-  $options<TNewOptions>(options: TNewOptions): FieldBuilder<SetProperty<TState, "~options", TNewOptions>>;
-  /**
-   * Set cell component for table views
-   */
-  withCell<TNewCellComponent extends MaybeLazyComponent>(component: TNewCellComponent): FieldBuilder<SetProperty<TState, "cellComponent", TNewCellComponent>>;
-}
-/**
- * Inferred options type for a field
- */
-type InferFieldOptions<TConfig extends Record<string, any>, TComponent extends MaybeLazyComponent> = [TConfig] extends [Record<string, never>] ? ExtractComponentOptions<TComponent> : TConfig & FieldUIOptions;
-/**
- * Create a field definition
+ * Create a field definition as a plain frozen object.
  *
  * @param name - Field type name (e.g. "text", "relation")
- * @param config - Component and optional config type
+ * @param config - Component and optional cell component
  *
  * @example
  * ```ts
- * // With explicit config type and createZod
- * const relationField = field("relation", {
- *   component: RelationField,
- *   config: {} as RelationFieldConfig,
- *   createZod: (opts, ctx) => z.string(),
- * });
- *
- * // Without config (infers from component props)
- * const textField = field("text", {
- *   component: TextField,
- *   createZod: (opts) => {
- *     let schema = z.string();
- *     if (opts.maxLength) schema = schema.max(opts.maxLength);
- *     return opts.required ? schema : schema.optional().nullable();
- *   },
+ * export default field("text", {
+ *   component: () => import("./text-field.js"),
+ *   cell: () => import("./cells/primitive-cells.js"),
  * });
  * ```
  */
-declare function field<TName extends string, TConfig extends Record<string, any> = Record<string, never>, TComponent extends MaybeLazyComponent = MaybeLazyComponent, TCellComponent extends MaybeLazyComponent | undefined = undefined>(name: TName, options: {
-  component: TComponent;
-  cell?: TCellComponent;
-  config?: TConfig;
-  /**
-   * Creates a Zod schema from field options.
-   * Called during form validation schema generation.
-   */
-  createZod?: CreateZodFn<InferFieldOptions<TConfig, TComponent>>;
-}): FieldBuilder<{
-  name: TName;
-  "~options": InferFieldOptions<TConfig, TComponent>;
-  component: TComponent;
-  cellComponent: TCellComponent;
-  createZod: typeof options.createZod;
-}>;
+declare function field<TName extends string>(name: TName, config: {
+  component: MaybeLazyComponent;
+  cell?: MaybeLazyComponent;
+}): FieldDefinition<TName>;
 /**
- * Extract field-specific options from component props.
- * Omits BaseFieldProps to get only field-specific config.
+ * Create a configured field instance (field + server-provided options).
+ * Used when mapping server introspection metadata to field rendering.
  */
-type ExtractComponentOptions<TComponent> = TComponent extends React.ComponentType<infer TProps> ? Omit<TProps, keyof BaseFieldProps> & FieldUIOptions : Record<string, never>;
+declare function configureField(base: FieldDefinition, options: Record<string, unknown>): FieldInstance;
 //#endregion
-export { CreateZodFn, FieldBuilder, FieldBuilderState, FieldDefinition, FieldHookOptions, FieldStateOptions, FieldUIOptions, ZodBuildContext, field };
-//# sourceMappingURL=field.d.mts.map
+export { FieldDefinition, FieldInstance, configureField, field };

package/dist/client/builder/field/field.mjs

@@ -1,83 +1,37 @@
 //#region src/client/builder/field/field.ts
 /**
-* Field builder class
-*
-* Also implements FieldDefinition interface so it can be used directly in registries.
-*/
-var FieldBuilder = class FieldBuilder {
-	constructor(state) {
-		this.state = state;
-	}
-	get name() {
-		return this.state.name;
-	}
-	get "~options"() {
-		return this.state["~options"];
-	}
-	get field() {
-		return { component: this.state.component };
-	}
-	get cell() {
-		return this.state.cellComponent ? { component: this.state.cellComponent } : void 0;
-	}
-	get createZod() {
-		return this.state.createZod;
-	}
-	/**
-	* Override options - returns new builder with updated state
-	*/
-	$options(options) {
-		return new FieldBuilder({
-			...this.state,
-			"~options": options
-		});
-	}
-	/**
-	* Set cell component for table views
-	*/
-	withCell(component) {
-		return new FieldBuilder({
-			...this.state,
-			cellComponent: component
-		});
-	}
-};
-/**
-* Create a field definition
+* Create a field definition as a plain frozen object.
 *
 * @param name - Field type name (e.g. "text", "relation")
-* @param config - Component and optional config type
+* @param config - Component and optional cell component
 *
 * @example
 * ```ts
-* // With explicit config type and createZod
-* const relationField = field("relation", {
-*   component: RelationField,
-*   config: {} as RelationFieldConfig,
-*   createZod: (opts, ctx) => z.string(),
-* });
-*
-* // Without config (infers from component props)
-* const textField = field("text", {
-*   component: TextField,
-*   createZod: (opts) => {
-*     let schema = z.string();
-*     if (opts.maxLength) schema = schema.max(opts.maxLength);
-*     return opts.required ? schema : schema.optional().nullable();
-*   },
+* export default field("text", {
+*   component: () => import("./text-field.js"),
+*   cell: () => import("./cells/primitive-cells.js"),
 * });
 * ```
 */
-function field(name, options) {
-	return new FieldBuilder({
+function field(name, config) {
+	return Object.freeze({
 		name,
-		"~options": {},
-		component: options.component,
-		cellComponent: options.cell,
-		createZod: options.createZod
+		component: config.component,
+		cell: config.cell
+	});
+}
+/**
+* Create a configured field instance (field + server-provided options).
+* Used when mapping server introspection metadata to field rendering.
+*/
+function configureField(base, options) {
+	return Object.freeze({
+		name: base.name,
+		component: base.component,
+		cell: base.cell,
+		"~options": options
 	});
 }
 
 //#endregion
-export { FieldBuilder, field };
-//# sourceMappingURL=field.mjs.map
+export { configureField, field };

package/dist/client/builder/index.d.mts

@@ -1,36 +1,31 @@
-import { I18nContext, I18nText } from "../i18n/types.mjs";
-import { BaseFieldProps, IconComponent, MaybeLazyComponent } from "./types/common.mjs";
-import { ActionContext, ActionDefinition, ActionDialogProps, ActionFormConfig, ActionHandler, ActionHelpers, ActionVariant, ActionsConfig, ApiHandler, ConfirmationConfig, CustomHandler, DialogHandler, FormHandler, HeaderActionsConfig, NavigateHandler } from "./types/action-types.mjs";
-import { ArrayFieldConfig, ComponentRegistry, EmbeddedFieldConfig, FieldComponentProps, FieldHookContext, FieldLayoutItem, FieldUIConfig, FieldValidationConfig, FormSidebarConfig, FormViewConfig, LayoutMode, RelationFieldConfig, RichTextConfig, SectionLayout, SelectOption, TabConfig, TabsLayout, WrapperMode } from "./types/field-types.mjs";
-import { CreateZodFn, FieldBuilder, FieldBuilderState, FieldDefinition as FieldDefinition$1, FieldHookOptions, FieldStateOptions, FieldUIOptions, ZodBuildContext, field as field$1 } from "./field/field.mjs";
-import { PageBuilder, PageBuilderState, PageDefinition, page } from "./page/page.mjs";
-import { AnyWidgetConfig, BaseWidgetConfig, ChartWidgetConfig, CustomWidgetConfig, GenericWidgetConfig, ProgressWidgetConfig, QuickActionItem, QuickActionsWidgetConfig, RecentItemsWidgetConfig, StatsWidgetConfig, TableWidgetColumn, TableWidgetColumnConfig, TableWidgetConfig, TimelineItem, TimelineWidgetConfig, ValueWidgetClassNames, ValueWidgetConfig, ValueWidgetResult, ValueWidgetTrend, WidgetAction, WidgetCardVariant, WidgetComponentProps, WidgetConfig, WidgetDataSource } from "./types/widget-types.mjs";
-import { DashboardAction, DashboardConfig, DashboardLayoutItem, DashboardSection, DashboardTabConfig, DashboardTabs, LocaleConfig } from "./types/ui-config.mjs";
-import { AutoSaveConfig, CollectionBuilderState, ColumnConfig, ColumnConfigObject, ListViewConfig, PreviewConfig } from "./types/collection-types.mjs";
-import { DefaultViewsConfig } from "./types/views.mjs";
-import { EditViewBuilder, EditViewBuilderState, EditViewDefinition, ListViewBuilder, ListViewBuilderState, ListViewDefinition, editView, listView } from "./view/view.mjs";
-import { WidgetBuilder, WidgetBuilderState, WidgetDefinition, widget } from "./widget/widget.mjs";
-import { AdminBuilderState } from "./admin-types.mjs";
-import { AdminBuilder } from "./admin-builder.mjs";
-import { AdminTypeRegistry, IsRegistered, RegisteredAdmin, RegisteredCMS, RegisteredCollectionNames, RegisteredGlobalNames } from "./registry.mjs";
-import { Admin, AdminInput, AppAdmin, InferAdminCMS } from "./admin.mjs";
-import "./types/action-registry.mjs";
-import { GlobalBuilderState } from "./types/global-types.mjs";
-import { qa } from "./qa.mjs";
-import "./validation.mjs";
-import { QuestpieClient } from "questpie/client";
-import { CollectionInfer, Questpie } from "questpie";
+import { IconComponent } from "./types/common.mjs";
+import { PageDefinition } from "./page/page.mjs";
+import { AnyWidgetConfig, WidgetAction, WidgetCardVariant, WidgetComponentProps, WidgetConfig } from "./types/widget-types.mjs";
+import { DashboardAction, DashboardConfig, DashboardLayoutItem, DashboardSection, DashboardTabConfig, DashboardTabs } from "./types/ui-config.mjs";
+import { AdminState } from "./admin-types.mjs";
+import { Admin, AppAdmin, InferAdminCMS } from "./admin.mjs";
+import { ComponentRegistry, FieldComponentProps, FieldLayoutItem, FormSidebarConfig, FormViewConfig, SectionLayout, TabConfig, TabsLayout } from "./types/field-types.mjs";
+import { QuestpieApp, QuestpieClient } from "questpie/client";
+import { CollectionInfer } from "questpie";
 
 //#region src/client/builder/index.d.ts
 
 /**
- * Extract collection names from backend Questpie app
+ * Unparameterised client type used throughout the admin library.
+ *
+ * The admin package is app-agnostic — it cannot know the concrete `TApp` at
+ * build time. This alias replaces the raw `QuestpieClient<any>` escape hatch
+ * with a single, intentional definition that documents the trade-off and
+ * provides a future narrowing point.
  */
-type CollectionNames<TApp extends Questpie<any>> = keyof TApp["config"]["collections"] & string;
+type AnyQuestpieClient = QuestpieClient<any>;
 /**
- * Extract global names from backend Questpie app
+ * Extract collection names from a QuestpieApp config
  */
-type GlobalNames<TApp extends Questpie<any>> = TApp extends Questpie<infer TConfig> ? keyof TConfig["globals"] & string : never;
+type CollectionNames<TApp extends QuestpieApp> = keyof TApp["collections"] & string;
+/**
+ * Extract global names from a QuestpieApp config
+ */
+type GlobalNames<TApp extends QuestpieApp> = keyof NonNullable<TApp["globals"]> & string;
 //#endregion
-export { CollectionNames, GlobalNames };
-//# sourceMappingURL=index.d.mts.map
+export { AnyQuestpieClient, CollectionNames, GlobalNames };

package/dist/client/builder/page/page.d.mts

@@ -1,36 +1,24 @@
-import { MaybeLazyComponent } from "../types/common.mjs";
-import { SetProperty } from "questpie/shared";
+import { I18nText } from "../../i18n/types.mjs";
+import { IconComponent, MaybeLazyComponent } from "../types/common.mjs";
 
 //#region src/client/builder/page/page.d.ts
 
+/**
+ * Page definition — a plain frozen object describing a custom admin page.
+ */
 interface PageDefinition<TName extends string = string> {
   readonly name: TName;
-  readonly component: any;
-  readonly path?: string;
-}
-interface PageBuilderState {
-  readonly name: string;
-  readonly component: any;
+  readonly component: MaybeLazyComponent;
   readonly path?: string;
   readonly showInNav?: boolean;
+  /** Display label for navigation. Falls back to formatted page name. */
+  readonly label?: I18nText;
+  /** Icon for navigation sidebar. */
+  readonly icon?: IconComponent;
+  /** Navigation group this page belongs to. */
+  readonly group?: string;
+  /** Sort order within the navigation group (default: 0). */
+  readonly order?: number;
 }
-declare class PageBuilder<TState extends PageBuilderState> {
-  readonly state: TState;
-  constructor(state: TState);
-  path(path: string): PageBuilder<SetProperty<TState, "path", string>>;
-}
-/**
- * Create a custom page
- */
-declare function page<TName extends string, TComponent extends MaybeLazyComponent>(name: TName, config: {
-  component: TComponent;
-  showInNav?: boolean;
-}): PageBuilder<{
-  name: TName;
-  component: TComponent;
-  path: undefined;
-  showInNav: boolean | undefined;
-}>;
 //#endregion
-export { PageBuilder, PageBuilderState, PageDefinition, page };
-//# sourceMappingURL=page.d.mts.map
+export { PageDefinition };

package/dist/client/builder/page/page.mjs

@@ -1,27 +1,31 @@
 //#region src/client/builder/page/page.ts
-var PageBuilder = class PageBuilder {
-	constructor(state) {
-		this.state = state;
-	}
-	path(path) {
-		return new PageBuilder({
-			...this.state,
-			path
-		});
-	}
-};
 /**
-* Create a custom page
+* Create a custom page as a plain frozen object.
+*
+* @example
+* ```ts
+* // Generated by `questpie generate`:
+* export default page("login", {
+*   component: async () => ({
+*     default: (await import("./login-page.js")).LoginPage,
+*   }),
+*   showInNav: false,
+*   path: "/login",
+* });
+* ```
 */
 function page(name, config) {
-	return new PageBuilder({
+	return Object.freeze({
 		name,
 		component: config.component,
-		path: void 0,
-		showInNav: config.showInNav
+		path: config.path,
+		showInNav: config.showInNav,
+		label: config.label,
+		icon: config.icon,
+		group: config.group,
+		order: config.order
 	});
 }
 
 //#endregion
-export { page };
-//# sourceMappingURL=page.mjs.map
+export { page };

package/dist/client/builder/registry.d.mts

@@ -1,4 +1,4 @@
-import { AdminBuilder } from "./admin-builder.mjs";
+import { Admin } from "./admin.mjs";
 import { Questpie } from "questpie";
 
 //#region src/client/builder/registry.d.ts
@@ -6,65 +6,45 @@ import { Questpie } from "questpie";
 /**
  * Admin Type Registry for module augmentation.
  *
- * @deprecated Use `createTypedHooks<AppCMS>()` instead for new projects.
- * Module augmentation is still supported for backwards compatibility.
+ * @deprecated Use `createTypedHooks<App>()` instead for new projects.
  *
- * Legacy usage (still works but not recommended):
  * @example
  * ```ts
- * // In your admin.ts after creating the admin config:
- * export const admin = qa()
- *   .use(coreAdminModule)
- *   .collections({ barbers, services })
+ * // Generated by `questpie generate`:
+ * // import admin from "#questpie/admin/.generated/client";
  *
- * declare module "@questpie/admin" {
- *   interface AdminTypeRegistry {
- *     cms: AppCMS
- *     admin: typeof admin
- *   }
- * }
- * ```
- *
- * New recommended pattern:
- * @example
- * ```ts
- * import type { AppCMS } from './server/cms';
+ * import type { App } from "./server/app";
  * import { createTypedHooks } from '@questpie/admin/client';
  *
  * export const {
  *   useCollectionList,
  *   useCollectionItem,
  *   useGlobal,
- * } = createTypedHooks<AppCMS>();
+ * } = createTypedHooks<App>();
  * ```
  */
 interface AdminTypeRegistry {}
 /**
- * Extract the CMS type from AdminTypeRegistry if augmented, otherwise unknown.
+ * Extract the app type from AdminTypeRegistry if augmented, otherwise unknown.
  */
 type RegisteredCMS = AdminTypeRegistry extends {
-  cms: infer T;
+  app: infer T;
 } ? T extends Questpie<any> ? T : unknown : unknown;
 /**
  * Extract the Admin config type from AdminTypeRegistry if augmented, otherwise unknown.
  */
 type RegisteredAdmin = AdminTypeRegistry extends {
   admin: infer T;
-} ? T extends AdminBuilder<any> ? T : unknown : unknown;
+} ? T extends Admin<any> ? T : unknown : unknown;
 /**
- * Extract collection names from registered CMS.
- * Falls back to string if CMS is not registered.
+ * Extract collection names from registered app.
+ * Falls back to string if app is not registered.
  */
 type RegisteredCollectionNames = RegisteredCMS extends Questpie<infer TConfig> ? keyof TConfig["collections"] & string : string;
 /**
- * Extract global names from registered CMS.
- * Falls back to string if CMS is not registered.
+ * Extract global names from registered app.
+ * Falls back to string if app is not registered.
  */
 type RegisteredGlobalNames = RegisteredCMS extends Questpie<infer TConfig> ? keyof TConfig["globals"] & string : string;
-/**
- * Check if the registry has been augmented with a CMS type.
- */
-type IsRegistered = RegisteredCMS extends unknown ? RegisteredCMS extends Questpie<any> ? true : false : false;
 //#endregion
-export { AdminTypeRegistry, IsRegistered, RegisteredAdmin, RegisteredCMS, RegisteredCollectionNames, RegisteredGlobalNames };
-//# sourceMappingURL=registry.d.mts.map
+export { RegisteredAdmin, RegisteredCMS, RegisteredCollectionNames, RegisteredGlobalNames };