@questpie/admin 1.1.1 → 3.0.0

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

@@ -0,0 +1,110 @@
+import { ViewKind } from "./view/view.mjs";
+import { AdminState } from "./admin-types.mjs";
+import { RegisteredAdmin } from "./registry.mjs";
+
+//#region src/client/builder/admin.d.ts
+
+/**
+ * Input type for Admin - accepts Admin instance or plain state.
+ *
+ * The plain state form is used by generated admin client configs from codegen.
+ */
+type AdminInput<TState$1 extends AdminState = AdminState> = Admin<TState$1> | TState$1;
+/**
+ * Admin runtime instance
+ *
+ * Provides methods to access admin configuration at runtime.
+ *
+ * @example
+ * ```ts
+ * // Generated by `questpie generate`:
+ * // import admin from "#questpie/admin/.generated/client";
+ * import { Admin } from "@questpie/admin/builder";
+ *
+ * <AdminLayoutProvider admin={admin} ... />
+ * ```
+ */
+declare class Admin<TState$1 extends AdminState = AdminState> {
+  readonly state: TState$1;
+  constructor(state: TState$1);
+  /**
+   * Normalize input to Admin instance.
+   *
+   * Accepts two input forms:
+   * - `Admin` instance — returned as-is
+   * - Plain `AdminState` object — wraps directly (from codegen)
+   */
+  static normalize<TState$1 extends AdminState>(input: AdminInput<TState$1>): Admin<TState$1>;
+  /**
+   * Get all custom page configurations.
+   */
+  getPages(): TState$1["pages"];
+  /**
+   * Get configuration for a specific page.
+   */
+  getPageConfig(name: string): TState$1["pages"][string] | undefined;
+  /**
+   * Get all registered component implementations.
+   */
+  getComponents(): TState$1["components"];
+  /**
+   * Get a specific component implementation by name.
+   */
+  getComponent(name: string): TState$1["components"][string] | undefined;
+  /**
+   * Get all registered view definitions (flat map with kind discriminant)
+   */
+  getViews(): TState$1["views"];
+  /**
+   * Get a specific view definition by name
+   */
+  getView(name: string): TState$1["views"][string] | undefined;
+  /**
+   * Get all views of a specific kind
+   */
+  getViewsByKind(kind: ViewKind): Record<string, any>;
+  /**
+   * Get locale configuration
+   */
+  getLocale(): TState$1["locale"];
+  /**
+   * Get available locales
+   */
+  getAvailableLocales(): string[];
+  /**
+   * Get default locale
+   */
+  getDefaultLocale(): string;
+  /**
+   * Get human-readable label for a locale
+   */
+  getLocaleLabel(locale: string): string;
+  /**
+   * Get translations map from state
+   */
+  getTranslations(): TState$1["translations"];
+  /**
+   * Get all registered field definitions
+   */
+  getFields(): TState$1["fields"];
+  /**
+   * Get a specific field definition
+   */
+  getField(name: string): TState$1["fields"][string] | undefined;
+  /**
+   * Get all registered widget definitions
+   */
+  getWidgets(): TState$1["widgets"];
+}
+/**
+ * Infer the app type from an Admin instance
+ */
+type InferAdminCMS<TAdmin> = TAdmin extends Admin<infer TState> ? TState extends {
+  "~app": infer TApp;
+} ? TApp : unknown : unknown;
+/**
+ * Get the registered Admin type (from module augmentation)
+ */
+type AppAdmin = RegisteredAdmin extends Admin<infer TState> ? Admin<TState> : Admin<AdminState>;
+//#endregion
+export { Admin, AdminInput, AppAdmin, InferAdminCMS };

package/dist/client/builder/admin.mjs

@@ -0,0 +1,151 @@
+import { DEFAULT_LOCALE, DEFAULT_LOCALE_CONFIG } from "questpie/shared";
+
+//#region src/client/builder/admin.ts
+/**
+* Admin Runtime Class
+*
+* Wraps AdminState with runtime methods for accessing configuration.
+* This is what gets passed to AdminProvider and used throughout the admin UI.
+*/
+/**
+* Admin runtime instance
+*
+* Provides methods to access admin configuration at runtime.
+*
+* @example
+* ```ts
+* // Generated by `questpie generate`:
+* // import admin from "#questpie/admin/.generated/client";
+* import { Admin } from "@questpie/admin/builder";
+*
+* <AdminLayoutProvider admin={admin} ... />
+* ```
+*/
+var Admin = class Admin {
+	constructor(state) {
+		this.state = state;
+	}
+	/**
+	* Normalize input to Admin instance.
+	*
+	* Accepts two input forms:
+	* - `Admin` instance — returned as-is
+	* - Plain `AdminState` object — wraps directly (from codegen)
+	*/
+	static normalize(input) {
+		if (input instanceof Admin) return input;
+		return new Admin(input);
+	}
+	/**
+	* Get all custom page configurations.
+	*/
+	getPages() {
+		return this.state.pages ?? {};
+	}
+	/**
+	* Get configuration for a specific page.
+	*/
+	getPageConfig(name) {
+		return this.state.pages?.[name];
+	}
+	/**
+	* Get all registered component implementations.
+	*/
+	getComponents() {
+		return this.state.components ?? {};
+	}
+	/**
+	* Get a specific component implementation by name.
+	*/
+	getComponent(name) {
+		return this.state.components?.[name];
+	}
+	/**
+	* Get all registered view definitions (flat map with kind discriminant)
+	*/
+	getViews() {
+		return this.state.views ?? {};
+	}
+	/**
+	* Get a specific view definition by name
+	*/
+	getView(name) {
+		return this.state.views?.[name];
+	}
+	/**
+	* Get all views of a specific kind
+	*/
+	getViewsByKind(kind) {
+		const views = this.state.views ?? {};
+		const result = {};
+		for (const [name, view] of Object.entries(views)) if (view?.kind === kind) result[name] = view;
+		return result;
+	}
+	/**
+	* Get locale configuration
+	*/
+	getLocale() {
+		return this.state.locale ?? DEFAULT_LOCALE_CONFIG;
+	}
+	/**
+	* Get available locales
+	*/
+	getAvailableLocales() {
+		return this.getLocale().supported ?? [DEFAULT_LOCALE];
+	}
+	/**
+	* Get default locale
+	*/
+	getDefaultLocale() {
+		return this.getLocale().default ?? DEFAULT_LOCALE;
+	}
+	/**
+	* Get human-readable label for a locale
+	*/
+	getLocaleLabel(locale) {
+		return {
+			en: "English",
+			sk: "Slovencina",
+			cs: "Cestina",
+			de: "Deutsch",
+			fr: "Francais",
+			es: "Espanol",
+			it: "Italiano",
+			pt: "Portugues",
+			pl: "Polski",
+			nl: "Nederlands",
+			ru: "Russkij",
+			uk: "Ukrainska",
+			ja: "Nihongo",
+			ko: "Hangugeo",
+			zh: "Zhongwen"
+		}[locale] ?? locale.toUpperCase();
+	}
+	/**
+	* Get translations map from state
+	*/
+	getTranslations() {
+		return this.state.translations ?? {};
+	}
+	/**
+	* Get all registered field definitions
+	*/
+	getFields() {
+		return this.state.fields ?? {};
+	}
+	/**
+	* Get a specific field definition
+	*/
+	getField(name) {
+		return this.state.fields?.[name];
+	}
+	/**
+	* Get all registered widget definitions
+	*/
+	getWidgets() {
+		return this.state.widgets ?? {};
+	}
+};
+
+//#endregion
+export { Admin };

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

@@ -0,0 +1,51 @@
+import { MaybeLazyComponent } from "../types/common.mjs";
+
+//#region src/client/builder/field/field.d.ts
+
+/**
+ * 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> {
+  readonly name: TName;
+  readonly component: MaybeLazyComponent;
+  readonly cell?: MaybeLazyComponent;
+}
+/**
+ * A field instance with runtime options from server introspection.
+ * Created by `configureField()` when mapping server metadata to field rendering.
+ */
+interface FieldInstance {
+  readonly name: string;
+  readonly component: MaybeLazyComponent;
+  readonly cell?: MaybeLazyComponent;
+  readonly "~options": Record<string, unknown>;
+}
+/**
+ * Create a field definition as a plain frozen object.
+ *
+ * @param name - Field type name (e.g. "text", "relation")
+ * @param config - Component and optional cell component
+ *
+ * @example
+ * ```ts
+ * export default field("text", {
+ *   component: () => import("./text-field.js"),
+ *   cell: () => import("./cells/primitive-cells.js"),
+ * });
+ * ```
+ */
+declare function field<TName extends string>(name: TName, config: {
+  component: MaybeLazyComponent;
+  cell?: MaybeLazyComponent;
+}): FieldDefinition<TName>;
+/**
+ * Create a configured field instance (field + server-provided options).
+ * Used when mapping server introspection metadata to field rendering.
+ */
+declare function configureField(base: FieldDefinition, options: Record<string, unknown>): FieldInstance;
+//#endregion
+export { FieldDefinition, FieldInstance, configureField, field };

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

@@ -0,0 +1,37 @@
+//#region src/client/builder/field/field.ts
+/**
+* Create a field definition as a plain frozen object.
+*
+* @param name - Field type name (e.g. "text", "relation")
+* @param config - Component and optional cell component
+*
+* @example
+* ```ts
+* export default field("text", {
+*   component: () => import("./text-field.js"),
+*   cell: () => import("./cells/primitive-cells.js"),
+* });
+* ```
+*/
+function field(name, config) {
+	return Object.freeze({
+		name,
+		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 { configureField, field };

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

@@ -0,0 +1,31 @@
+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
+
+/**
+ * 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 AnyQuestpieClient = QuestpieClient<any>;
+/**
+ * Extract collection names from a QuestpieApp config
+ */
+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 { AnyQuestpieClient, CollectionNames, GlobalNames };

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

@@ -0,0 +1,24 @@
+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: 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;
+}
+//#endregion
+export { PageDefinition };

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

@@ -0,0 +1,31 @@
+//#region src/client/builder/page/page.ts
+/**
+* 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 Object.freeze({
+		name,
+		component: config.component,
+		path: config.path,
+		showInNav: config.showInNav,
+		label: config.label,
+		icon: config.icon,
+		group: config.group,
+		order: config.order
+	});
+}
+
+//#endregion
+export { page };

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

@@ -0,0 +1,50 @@
+import { Admin } from "./admin.mjs";
+import { Questpie } from "questpie";
+
+//#region src/client/builder/registry.d.ts
+
+/**
+ * Admin Type Registry for module augmentation.
+ *
+ * @deprecated Use `createTypedHooks<App>()` instead for new projects.
+ *
+ * @example
+ * ```ts
+ * // Generated by `questpie generate`:
+ * // import admin from "#questpie/admin/.generated/client";
+ *
+ * import type { App } from "./server/app";
+ * import { createTypedHooks } from '@questpie/admin/client';
+ *
+ * export const {
+ *   useCollectionList,
+ *   useCollectionItem,
+ *   useGlobal,
+ * } = createTypedHooks<App>();
+ * ```
+ */
+interface AdminTypeRegistry {}
+/**
+ * Extract the app type from AdminTypeRegistry if augmented, otherwise unknown.
+ */
+type RegisteredCMS = AdminTypeRegistry extends {
+  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 Admin<any> ? T : unknown : unknown;
+/**
+ * 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 app.
+ * Falls back to string if app is not registered.
+ */
+type RegisteredGlobalNames = RegisteredCMS extends Questpie<infer TConfig> ? keyof TConfig["globals"] & string : string;
+//#endregion
+export { RegisteredAdmin, RegisteredCMS, RegisteredCollectionNames, RegisteredGlobalNames };