@questpie/admin 1.1.1 → 3.0.0

package/dist/server/proxy-factories.mjs

@@ -0,0 +1,302 @@
+//#region src/server/proxy-factories.ts
+/**
+* Resolve registry source state.
+*
+* Collection/Global builders: registry lives on `state["~questpieApp"].state`.
+*/
+function getRegistrySourceState(builderState) {
+	const questpieApp = builderState["~questpieApp"];
+	if (questpieApp?.state && typeof questpieApp.state === "object") return questpieApp.state;
+	return builderState;
+}
+/**
+* Resolve registered component names from builder state.
+*/
+function getRegisteredComponentNames(builderState) {
+	const components = getRegistrySourceState(builderState).components;
+	if (!components || typeof components !== "object") return [];
+	return Object.keys(components);
+}
+/**
+* Normalize component props into a serializable object.
+*/
+function normalizeComponentProps(componentType, props) {
+	if (componentType === "icon" && typeof props === "string") return { name: props };
+	if (props === null || props === void 0) return {};
+	if (typeof props === "object") return props;
+	return { value: props };
+}
+/**
+* Convert a view callback property name to a canonical view id.
+*
+* Examples:
+* - `collectionTable` -> `collection-table`
+* - `globalForm` -> `global-form`
+* - `kanban` -> `kanban`
+*/
+function toViewId(name) {
+	return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+/**
+* Create a simple view proxy for builder callback contexts.
+* Accessing any property returns a function that creates a view config object.
+*
+* Used as the `v` callback param:
+* `v.collectionTable({ columns: [...] })` -> `{ view: "collection-table", columns: [...] }`.
+*/
+function createViewCallbackProxy() {
+	return new Proxy({}, { get: (_, prop) => {
+		return (config = {}) => ({
+			view: toViewId(String(prop)),
+			...config
+		});
+	} });
+}
+/**
+* Create a simple component proxy for builder callback contexts.
+* Accessing any property returns a function that creates a component reference.
+*
+* Used as the `c` callback param: `c.icon("ph:article")` → `{ type: "icon", props: { name: "ph:article" } }`.
+*/
+function createComponentCallbackProxy() {
+	return new Proxy({}, { get: (_, prop) => {
+		return (...args) => ({
+			type: String(prop),
+			props: typeof args[0] === "string" ? { name: args[0] } : args[0] ?? {}
+		});
+	} });
+}
+/**
+* Create a simple action proxy for builder callback contexts.
+* Provides a `custom()` method and returns action names as strings for built-in actions.
+*
+* Used as the `a` callback param: `a.delete` → `"delete"`, `a.custom("archive", config)` → `{ id: "archive", ...config }`.
+*/
+function createActionCallbackProxy() {
+	return new Proxy({ custom: (name, config) => ({
+		id: name,
+		...config
+	}) }, { get: (target, prop) => {
+		return target[prop] ?? String(prop);
+	} });
+}
+/**
+* Create a component proxy for registered component references.
+* Used in admin config functions (`.admin()`, `.actions()`, `.dashboard()`, `.sidebar()`).
+*/
+function createComponentProxy(builderState) {
+	const componentNames = getRegisteredComponentNames(builderState);
+	const registeredComponentSet = new Set(componentNames);
+	return new Proxy({}, {
+		get: (_target, prop) => {
+			if (typeof prop !== "string") return;
+			if (prop === "then") return;
+			if (registeredComponentSet.size > 0 && !registeredComponentSet.has(prop)) throw new Error(`Unknown component "${prop}". Register it via .components(). Available components: ${[...registeredComponentSet].sort().join(", ")}`);
+			return (props) => ({
+				type: prop,
+				props: normalizeComponentProps(prop, props)
+			});
+		},
+		has: (_target, prop) => {
+			if (typeof prop !== "string") return false;
+			return registeredComponentSet.has(prop);
+		},
+		ownKeys: () => [...registeredComponentSet],
+		getOwnPropertyDescriptor: (_target, prop) => {
+			if (typeof prop !== "string") return;
+			if (!registeredComponentSet.has(prop)) return;
+			return {
+				configurable: true,
+				enumerable: true,
+				writable: false,
+				value: (props) => ({
+					type: prop,
+					props: normalizeComponentProps(prop, props)
+				})
+			};
+		}
+	});
+}
+/**
+* Create a field proxy for referencing collection fields.
+* Returns field names as strings for config objects.
+*/
+function createFieldProxy(fieldNames) {
+	return new Proxy({}, {
+		get: (_target, prop) => prop,
+		has: (_target, prop) => fieldNames.includes(prop),
+		ownKeys: () => fieldNames,
+		getOwnPropertyDescriptor: (_target, prop) => {
+			if (fieldNames.includes(prop)) return {
+				configurable: true,
+				enumerable: true,
+				value: prop
+			};
+		}
+	});
+}
+/**
+* Create a view proxy for defining view configurations.
+*/
+function createViewProxy(kind, registeredViews = []) {
+	const registeredViewSet = new Set(registeredViews);
+	const hasRegistry = registeredViewSet.size > 0;
+	return new Proxy({}, {
+		get: (_target, prop) => {
+			if (typeof prop !== "string") return;
+			if (prop === "then") return;
+			if (hasRegistry && !registeredViewSet.has(prop)) {
+				const registerMethod = kind === "list" ? "listViews" : "formViews";
+				const available = [...registeredViewSet].sort().join(", ");
+				throw new Error(`Unknown ${kind} view "${prop}". Register it via .${registerMethod}(). Available ${kind} views: ${available || "(none)"}`);
+			}
+			return (config = {}) => ({
+				view: toViewId(prop),
+				...config
+			});
+		},
+		has: (_target, prop) => {
+			if (typeof prop !== "string") return false;
+			return hasRegistry && registeredViewSet.has(prop);
+		},
+		ownKeys: () => hasRegistry ? [...registeredViewSet] : [],
+		getOwnPropertyDescriptor: (_target, prop) => {
+			if (typeof prop !== "string") return;
+			if (hasRegistry && !registeredViewSet.has(prop)) return;
+			return {
+				configurable: true,
+				enumerable: hasRegistry,
+				writable: false,
+				value: (config = {}) => ({
+					view: toViewId(prop),
+					...config
+				})
+			};
+		}
+	});
+}
+/**
+* Create an action proxy for referencing built-in and custom actions.
+*/
+function createActionProxy() {
+	return {
+		create: "create",
+		save: "save",
+		delete: "delete",
+		deleteMany: "deleteMany",
+		restore: "restore",
+		restoreMany: "restoreMany",
+		duplicate: "duplicate",
+		export: "export",
+		custom: (name, config) => ({
+			type: name,
+			config
+		})
+	};
+}
+/**
+* Create a sidebar proxy for contribution callbacks.
+*/
+function createSidebarContributionProxy() {
+	return {
+		section: (def) => def,
+		item: (def) => def
+	};
+}
+/**
+* Create a dashboard proxy for contribution callbacks.
+*/
+function createDashboardContributionProxy() {
+	return {
+		section: (def) => def,
+		stats: (def) => ({
+			...def,
+			type: "stats"
+		}),
+		value: (def) => ({
+			...def,
+			type: "value"
+		}),
+		progress: (def) => ({
+			...def,
+			type: "progress"
+		}),
+		chart: (def) => ({
+			...def,
+			type: "chart"
+		}),
+		recentItems: (def) => ({
+			...def,
+			type: "recentItems"
+		}),
+		timeline: (def) => ({
+			...def,
+			type: "timeline"
+		}),
+		table: (def) => ({
+			...def,
+			type: "table"
+		}),
+		custom: (def) => ({
+			...def,
+			type: "custom"
+		})
+	};
+}
+/**
+* Create action helpers for dashboard header actions.
+*/
+function createDashboardActionProxy() {
+	const toCollectionCreatePath = (collection) => `/admin/collections/${collection}/create`;
+	const toGlobalPath = (global) => `/admin/globals/${global}`;
+	return {
+		action: (config) => config,
+		link: (config) => config,
+		create: ({ collection, ...config }) => ({
+			...config,
+			href: toCollectionCreatePath(collection)
+		}),
+		global: ({ global, ...config }) => ({
+			...config,
+			href: toGlobalPath(global)
+		})
+	};
+}
+/**
+* Create a sidebar callback context for resolving sidebar contributions.
+*/
+function createSidebarCallbackContext() {
+	return {
+		s: createSidebarContributionProxy(),
+		c: createComponentProxy({})
+	};
+}
+/**
+* Create a dashboard callback context for resolving dashboard contributions.
+*/
+function createDashboardCallbackContext() {
+	return {
+		d: createDashboardContributionProxy(),
+		c: createComponentProxy({}),
+		a: createDashboardActionProxy()
+	};
+}
+/**
+* Resolve a sidebar callback or static value into a `SidebarContribution`.
+*/
+function resolveSidebarCallback(value) {
+	if (value == null) return void 0;
+	if (typeof value === "function") return value(createSidebarCallbackContext());
+	return value;
+}
+/**
+* Resolve a dashboard callback or static value into a `DashboardContribution`.
+*/
+function resolveDashboardCallback(value) {
+	if (value == null) return void 0;
+	if (typeof value === "function") return value(createDashboardCallbackContext());
+	return value;
+}
+
+//#endregion
+export { createActionCallbackProxy, createActionProxy, createComponentCallbackProxy, createComponentProxy, createDashboardCallbackContext, createDashboardContributionProxy, createFieldProxy, createSidebarCallbackContext, createSidebarContributionProxy, createViewCallbackProxy, createViewProxy, resolveDashboardCallback, resolveSidebarCallback };

package/dist/server/registry-helpers.d.mts

@@ -0,0 +1,83 @@
+import { ComponentDefinition, EditViewDefinition, ListViewDefinition, ViewDefinition, ViewKind } from "./augmentation/views.mjs";
+import "./augmentation.mjs";
+
+//#region src/server/registry-helpers.d.ts
+
+/**
+ * Create a view definition with a `kind` discriminant and typed config.
+ *
+ * `kind` determines which registry this view belongs to:
+ * - `"list"` → used in `.list()` callback via `v.myView()`
+ * - `"form"` → used in `.form()` callback via `v.myView()`
+ *
+ * The first generic parameter `TConfig` carries the config type that
+ * `v.myView(config)` will accept in `.list()` / `.form()` callbacks.
+ * When omitted, the view accepts `unknown` (no type checking on config).
+ *
+ * The `kind` field is plugin-extensible — plugins can register new view kinds
+ * via the `ViewKindRegistry` augmentation interface.
+ *
+ * @example
+ * ```ts
+ * // views/table.ts — built-in list view with typed config
+ * export default view<ListViewConfig>("table", { kind: "list" });
+ *
+ * // views/kanban.ts — custom list view with its own config type
+ * interface KanbanConfig { groupBy: string; swimlanes?: boolean }
+ * export default view<KanbanConfig>("kanban", { kind: "list" });
+ *
+ * // views/wizard.ts — custom edit view
+ * interface WizardConfig { steps: { title: string; fields: string[] }[] }
+ * export default view<WizardConfig>("wizard", { kind: "form" });
+ * ```
+ */
+declare function view<TConfig = unknown, TName extends string = string, TKind extends ViewKind = ViewKind>(name: TName, config: {
+  kind: TKind;
+} & Record<string, unknown>): ViewDefinition<TName, TKind, TConfig>;
+/**
+ * Create a list view definition.
+ * @deprecated Use `view(name, { kind: "list", ... })` instead.
+ */
+declare function listView<TName extends string>(name: TName, config?: Record<string, unknown>): ListViewDefinition<TName>;
+/**
+ * Create an edit view definition.
+ * @deprecated Use `view(name, { kind: "form", ... })` instead.
+ */
+declare function editView<TName extends string>(name: TName, config?: Record<string, unknown>): EditViewDefinition<TName>;
+/**
+ * Create a component definition with typed props.
+ *
+ * The first generic parameter `TProps` carries the input props type that
+ * `c.myComponent(props)` will accept in `.admin()` callbacks.
+ * When omitted, the component accepts `Record<string, unknown> | string`.
+ *
+ * @example
+ * ```ts
+ * // components/icon.ts — string shorthand for icon name
+ * export default component<string | { name: string }>("icon");
+ *
+ * // components/rating.ts — typed props
+ * interface RatingProps { value: number; max?: number }
+ * export default component<RatingProps>("rating");
+ * ```
+ */
+declare function component<TProps = unknown, TName extends string = string>(name: TName, config?: Record<string, unknown>): ComponentDefinition<TName, TProps>;
+/**
+ * Filter a views record by kind, returning only views matching the specified kind.
+ *
+ * Used by codegen to derive `listViews`/`formViews` from the unified `views` category.
+ * Each view file defines `view("name", { kind: "list"|"form" })`. This function
+ * filters at module-definition time so the module exports separate registries.
+ *
+ * @example
+ * ```ts
+ * // Generated by codegen in .generated/module.ts:
+ * listViews: filterViewsByKind({ table: _view_table, form: _view_form }, "list"),
+ * formViews: filterViewsByKind({ table: _view_table, form: _view_form }, "form"),
+ * ```
+ */
+declare function filterViewsByKind<TViews extends Record<string, ViewDefinition<string, ViewKind, any>>, TKind extends ViewKind>(views: TViews, kind: TKind): { [K in keyof TViews as TViews[K] extends {
+  kind: TKind;
+} ? K : never]: TViews[K] };
+//#endregion
+export { component, editView, filterViewsByKind, listView, view };

package/dist/server/registry-helpers.mjs

@@ -0,0 +1,104 @@
+//#region src/server/registry-helpers.ts
+/**
+* Create a view definition with a `kind` discriminant and typed config.
+*
+* `kind` determines which registry this view belongs to:
+* - `"list"` → used in `.list()` callback via `v.myView()`
+* - `"form"` → used in `.form()` callback via `v.myView()`
+*
+* The first generic parameter `TConfig` carries the config type that
+* `v.myView(config)` will accept in `.list()` / `.form()` callbacks.
+* When omitted, the view accepts `unknown` (no type checking on config).
+*
+* The `kind` field is plugin-extensible — plugins can register new view kinds
+* via the `ViewKindRegistry` augmentation interface.
+*
+* @example
+* ```ts
+* // views/table.ts — built-in list view with typed config
+* export default view<ListViewConfig>("table", { kind: "list" });
+*
+* // views/kanban.ts — custom list view with its own config type
+* interface KanbanConfig { groupBy: string; swimlanes?: boolean }
+* export default view<KanbanConfig>("kanban", { kind: "list" });
+*
+* // views/wizard.ts — custom edit view
+* interface WizardConfig { steps: { title: string; fields: string[] }[] }
+* export default view<WizardConfig>("wizard", { kind: "form" });
+* ```
+*/
+function view(name, config) {
+	return {
+		type: "view",
+		name,
+		...config
+	};
+}
+/**
+* Create a list view definition.
+* @deprecated Use `view(name, { kind: "list", ... })` instead.
+*/
+function listView(name, config = {}) {
+	return {
+		type: "listView",
+		name,
+		...config
+	};
+}
+/**
+* Create an edit view definition.
+* @deprecated Use `view(name, { kind: "form", ... })` instead.
+*/
+function editView(name, config = {}) {
+	return {
+		type: "editView",
+		name,
+		...config
+	};
+}
+/**
+* Create a component definition with typed props.
+*
+* The first generic parameter `TProps` carries the input props type that
+* `c.myComponent(props)` will accept in `.admin()` callbacks.
+* When omitted, the component accepts `Record<string, unknown> | string`.
+*
+* @example
+* ```ts
+* // components/icon.ts — string shorthand for icon name
+* export default component<string | { name: string }>("icon");
+*
+* // components/rating.ts — typed props
+* interface RatingProps { value: number; max?: number }
+* export default component<RatingProps>("rating");
+* ```
+*/
+function component(name, config = {}) {
+	return {
+		type: "component",
+		name,
+		...config
+	};
+}
+/**
+* Filter a views record by kind, returning only views matching the specified kind.
+*
+* Used by codegen to derive `listViews`/`formViews` from the unified `views` category.
+* Each view file defines `view("name", { kind: "list"|"form" })`. This function
+* filters at module-definition time so the module exports separate registries.
+*
+* @example
+* ```ts
+* // Generated by codegen in .generated/module.ts:
+* listViews: filterViewsByKind({ table: _view_table, form: _view_form }, "list"),
+* formViews: filterViewsByKind({ table: _view_table, form: _view_form }, "form"),
+* ```
+*/
+function filterViewsByKind(views, kind) {
+	const result = {};
+	for (const [key, view$1] of Object.entries(views)) if (view$1.kind === kind) result[key] = view$1;
+	return result;
+}
+
+//#endregion
+export { component, editView, filterViewsByKind, listView, view };