@questpie/admin 2.0.0 → 3.0.1

package/dist/server/plugin.mjs

@@ -0,0 +1,385 @@
+import { generateAdminClientTemplate } from "./codegen/admin-client-template.mjs";
+import { createAdminProjectionValidator } from "./codegen/projection-validator.mjs";
+
+//#region src/server/plugin.ts
+/**
+* Admin codegen plugin.
+*
+* Discovers admin-specific file conventions:
+* - `views/*.ts` — custom view definitions (list, form, etc.)
+* - `components/*.ts` — component definitions with typed props
+* - `blocks/*.ts` — visual block editor blocks
+* - `sidebar.ts` — sidebar contribution
+* - `dashboard.ts` — dashboard contribution
+* - `branding.ts` — admin branding config
+* - `admin-locale.ts` — admin UI locale config
+*
+* Extends collection/global builders with:
+* - `.admin()` — admin config (label, icon, group, etc.)
+* - `.list()` — list view config (columns, sort, filter, etc.)
+* - `.form()` — form view config (fields, sidebar, tabs, etc.)
+* - `.preview()` — live preview config
+* - `.actions()` — custom actions config
+*/
+function adminPlugin() {
+	return {
+		name: "questpie-admin",
+		validators: [createAdminProjectionValidator()],
+		targets: {
+			server: {
+				root: ".",
+				outputFile: "index.ts",
+				categories: {
+					views: {
+						dirs: ["views"],
+						prefix: "view",
+						factoryFunctions: ["view"],
+						registryKey: true,
+						placeholder: "$VIEW_NAMES",
+						recordPlaceholder: "$VIEWS_RECORD",
+						includeInAppState: true,
+						extractFromModules: true,
+						typeEmit: "standard"
+					},
+					components: {
+						dirs: ["components"],
+						prefix: "comp",
+						factoryFunctions: ["component"],
+						registryKey: true,
+						placeholder: "$COMPONENT_NAMES",
+						recordPlaceholder: "$COMPONENTS",
+						typeRegistry: {
+							module: "@questpie/admin/server",
+							interface: "ComponentTypeRegistry"
+						},
+						includeInAppState: true,
+						extractFromModules: true,
+						typeEmit: "standard"
+					},
+					blocks: {
+						dirs: ["blocks"],
+						prefix: "bloc",
+						factoryFunctions: ["block"],
+						registryKey: true,
+						includeInAppState: true,
+						extractFromModules: true,
+						typeEmit: "standard"
+					},
+					fieldTypes: {
+						dirs: ["fields"],
+						prefix: "ftype",
+						factoryImports: [{
+							name: "adminFields",
+							from: "@questpie/admin/server"
+						}]
+					}
+				},
+				discover: { adminConfig: {
+					pattern: "config/admin.ts",
+					configKey: "admin"
+				} },
+				registries: {
+					builderFactories: { block: {
+						builderClass: "BlockBuilder",
+						import: {
+							name: "BlockBuilder",
+							from: "@questpie/admin/server"
+						},
+						createMethod: "create",
+						returnType: "import('@questpie/admin/server').BlockBuilder<{ name: TName }>"
+					} },
+					fieldExtensions: {
+						admin: {
+							stateKey: "admin",
+							configType: "unknown"
+						},
+						form: {
+							stateKey: "form",
+							configType: "(ctx: { f: Record<string, string> }) => { fields: import('@questpie/admin/server').FieldLayoutItem[] }",
+							isCallback: true,
+							callbackContextParams: ["f"]
+						}
+					},
+					collectionExtensions: {
+						admin: {
+							stateKey: "admin",
+							imports: [{
+								name: "AdminCollectionConfig",
+								from: "@questpie/admin/server"
+							}, {
+								name: "AdminConfigContext",
+								from: "@questpie/admin/server"
+							}],
+							configType: "AdminCollectionConfig | ((ctx: AdminConfigContext<$COMPONENTS>) => AdminCollectionConfig)",
+							isCallback: true,
+							callbackContextParams: ["c"]
+						},
+						list: {
+							stateKey: "adminList",
+							imports: [
+								{
+									name: "ListViewConfig",
+									from: "@questpie/admin/server"
+								},
+								{
+									name: "ListViewConfigContext",
+									from: "@questpie/admin/server"
+								},
+								{
+									name: "FilterViewsByKind",
+									from: "@questpie/admin/server"
+								}
+							],
+							configType: "(ctx: ListViewConfigContext<TState extends { fieldDefinitions: infer F extends Record<string, any> } ? F : Record<string, any>, FilterViewsByKind<$VIEWS_RECORD, \"list\">>) => ListViewConfig",
+							isCallback: true,
+							callbackContextParams: [
+								"v",
+								"f",
+								"a"
+							],
+							defaults: {
+								view: "collection-table",
+								showSearch: true,
+								showFilters: true,
+								showToolbar: true
+							}
+						},
+						form: {
+							stateKey: "adminForm",
+							imports: [
+								{
+									name: "FormViewConfig",
+									from: "@questpie/admin/server"
+								},
+								{
+									name: "FormViewConfigContext",
+									from: "@questpie/admin/server"
+								},
+								{
+									name: "FilterViewsByKind",
+									from: "@questpie/admin/server"
+								}
+							],
+							configType: "(ctx: FormViewConfigContext<TState extends { fieldDefinitions: infer F extends Record<string, any> } ? F : Record<string, any>, FilterViewsByKind<$VIEWS_RECORD, \"form\">>) => FormViewConfig",
+							isCallback: true,
+							callbackContextParams: ["v", "f"],
+							defaults: {
+								view: "collection-form",
+								showMeta: true
+							}
+						},
+						preview: {
+							stateKey: "adminPreview",
+							imports: [{
+								name: "PreviewConfig",
+								from: "@questpie/admin/server"
+							}],
+							configType: "PreviewConfig"
+						},
+						actions: {
+							stateKey: "adminActions",
+							imports: [{
+								name: "ServerActionsConfig",
+								from: "@questpie/admin/server"
+							}, {
+								name: "ActionsConfigContext",
+								from: "@questpie/admin/server"
+							}],
+							configType: "(ctx: ActionsConfigContext<Record<string, unknown>, $COMPONENTS>) => ServerActionsConfig",
+							isCallback: true,
+							callbackContextParams: [
+								"a",
+								"c",
+								"f"
+							]
+						}
+					},
+					globalExtensions: {
+						admin: {
+							stateKey: "admin",
+							imports: [{
+								name: "AdminGlobalConfig",
+								from: "@questpie/admin/server"
+							}, {
+								name: "AdminConfigContext",
+								from: "@questpie/admin/server"
+							}],
+							configType: "AdminGlobalConfig | ((ctx: AdminConfigContext<$COMPONENTS>) => AdminGlobalConfig)",
+							isCallback: true,
+							callbackContextParams: ["c"]
+						},
+						form: {
+							stateKey: "adminForm",
+							imports: [
+								{
+									name: "FormViewConfig",
+									from: "@questpie/admin/server"
+								},
+								{
+									name: "FormViewConfigContext",
+									from: "@questpie/admin/server"
+								},
+								{
+									name: "FilterViewsByKind",
+									from: "@questpie/admin/server"
+								}
+							],
+							configType: "(ctx: FormViewConfigContext<TState extends { fieldDefinitions: infer F extends Record<string, any> } ? F : Record<string, any>, FilterViewsByKind<$VIEWS_RECORD, \"form\">>) => FormViewConfig",
+							isCallback: true,
+							callbackContextParams: ["v", "f"],
+							defaults: {
+								view: "global-form",
+								showMeta: true
+							}
+						}
+					},
+					singletonFactories: { adminConfig: {
+						configType: "AdminConfigInput",
+						imports: [{
+							name: "AdminConfigInput",
+							from: "@questpie/admin/server"
+						}],
+						isCallback: true
+					} }
+				},
+				transform(_ctx) {},
+				callbackParams: {
+					v: {
+						factory: "createViewCallbackProxy",
+						from: "@questpie/admin/server"
+					},
+					c: {
+						factory: "createComponentCallbackProxy",
+						from: "@questpie/admin/server"
+					},
+					a: {
+						factory: "createActionCallbackProxy",
+						from: "@questpie/admin/server"
+					}
+				},
+				scaffolds: {
+					block: {
+						dir: "blocks",
+						description: "Server-side block definition",
+						template: ({ kebab, camel }) => `import { block } from "#questpie/factories";\n\nexport const ${camel}Block = block("${kebab}")\n\t.fields(({ f }) => ({\n\t\ttitle: f.text("Title"),\n\t}));\n`
+					},
+					view: {
+						dir: "views",
+						description: "Server-side view definition",
+						template: ({ kebab, camel }) => `import { view } from "@questpie/admin/server";\n\nexport const ${camel}View = view("${kebab}", "list", {\n\t// TODO: configure view\n});\n`
+					},
+					component: {
+						dir: "components",
+						description: "Server-side component definition",
+						template: ({ kebab, camel }) => `import { component } from "@questpie/admin/server";\n\nexport const ${camel}Component = component("${kebab}", {\n\t// TODO: configure component props\n});\n`
+					}
+				}
+			},
+			"admin-client": {
+				root: "../admin",
+				outputFile: "client.ts",
+				moduleRoot: "client",
+				categories: {
+					blocks: {
+						dirs: ["blocks"],
+						prefix: "block",
+						registryKey: false,
+						includeInAppState: false,
+						extractFromModules: false
+					},
+					views: {
+						dirs: ["views"],
+						prefix: "view",
+						registryKey: false,
+						includeInAppState: false,
+						extractFromModules: false,
+						keyFromProperty: "name"
+					},
+					components: {
+						dirs: ["components"],
+						prefix: "comp",
+						registryKey: false,
+						includeInAppState: false,
+						extractFromModules: false
+					},
+					fields: {
+						dirs: ["fields"],
+						prefix: "fld",
+						registryKey: false,
+						includeInAppState: false,
+						extractFromModules: false
+					},
+					pages: {
+						dirs: ["pages"],
+						prefix: "pg",
+						registryKey: false,
+						includeInAppState: false,
+						extractFromModules: false
+					},
+					widgets: {
+						dirs: ["widgets"],
+						prefix: "wgt",
+						registryKey: false,
+						includeInAppState: false,
+						extractFromModules: false
+					}
+				},
+				discover: {
+					modules: "modules.ts",
+					locale: "locale.ts",
+					translations: "translations.ts",
+					defaults: "defaults.ts"
+				},
+				transform(ctx) {
+					const blockFiles = ctx.categories.get("blocks");
+					if (!blockFiles || blockFiles.size === 0) return;
+					ctx.addImport("type { BlockRendererProps }", "@questpie/admin/client");
+					ctx.addImport("type { InferBlockValues, InferBlockData }", "@questpie/admin/server");
+					const entries = [];
+					for (const [key, file] of [...blockFiles.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+						const varName = `${key}Block`;
+						const kebab = file.importPath.split("/").pop();
+						ctx.addImport(`type { ${varName} }`, `../../server/blocks/${kebab}`);
+						entries.push(`${JSON.stringify(key)}: typeof ${varName}`);
+					}
+					ctx.addTypeDeclaration(`type _ServerBlocks = { ${entries.join("; ")} };`);
+					ctx.addTypeDeclaration("");
+					ctx.addTypeDeclaration("export type BlockProps<T extends keyof _ServerBlocks> = BlockRendererProps<");
+					ctx.addTypeDeclaration("	InferBlockValues<_ServerBlocks[T][\"state\"]>,");
+					ctx.addTypeDeclaration("	InferBlockData<_ServerBlocks[T]>");
+					ctx.addTypeDeclaration(">;");
+				},
+				scaffolds: {
+					block: {
+						dir: "blocks",
+						extension: ".tsx",
+						description: "Client-side block renderer",
+						template: ({ kebab, pascal }) => `import type { BlockProps } from "../.generated/client";\n\nexport default function ${pascal}Block({ values, children }: BlockProps<"${kebab}">) {\n\treturn (\n\t\t<div>\n\t\t\t<h2>${pascal} Block</h2>\n\t\t\t{/* TODO: implement block renderer */}\n\t\t</div>\n\t);\n}\n`
+					},
+					view: {
+						dir: "views",
+						extension: ".tsx",
+						description: "Client-side view component",
+						template: ({ kebab, pascal }) => `import { defineView } from "@questpie/admin";\n\nexport default defineView("${kebab}", (props) => {\n\treturn (\n\t\t<div>\n\t\t\t<h2>${pascal} View</h2>\n\t\t\t{/* TODO: implement view */}\n\t\t</div>\n\t);\n});\n`
+					},
+					field: {
+						dir: "fields",
+						extension: ".tsx",
+						description: "Client-side field component",
+						template: ({ kebab, pascal }) => `import { field } from "@questpie/admin";\n\nexport default field({\n\tname: "${kebab}",\n\tcomponent: (props) => {\n\t\treturn (\n\t\t\t<div>\n\t\t\t\t<label>${pascal}</label>\n\t\t\t\t{/* TODO: implement field */}\n\t\t\t</div>\n\t\t);\n\t},\n});\n`
+					},
+					widget: {
+						dir: "widgets",
+						extension: ".tsx",
+						description: "Client-side dashboard widget",
+						template: ({ kebab, pascal }) => `import { defineWidget } from "@questpie/admin";\n\nexport default defineWidget("${kebab}", (props) => {\n\treturn (\n\t\t<div>\n\t\t\t<h3>${pascal} Widget</h3>\n\t\t\t{/* TODO: implement widget */}\n\t\t</div>\n\t);\n});\n`
+					}
+				},
+				generate: (ctx) => generateAdminClientTemplate(ctx)
+			}
+		}
+	};
+}
+
+//#endregion
+export { adminPlugin };

package/dist/server/proxy-factories.d.mts

@@ -0,0 +1,85 @@
+import { DashboardCallbackContext, DashboardContribution, DashboardProxy } from "./augmentation/dashboard.mjs";
+import { SidebarCallbackContext, SidebarContribution, SidebarProxy } from "./augmentation/sidebar.mjs";
+import "./augmentation.mjs";
+
+//#region src/server/proxy-factories.d.ts
+
+/**
+ * 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: [...] }`.
+ */
+declare function createViewCallbackProxy(): Record<string, (config?: Record<string, unknown>) => Record<string, unknown>>;
+/**
+ * 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" } }`.
+ */
+declare function createComponentCallbackProxy(): Record<string, (...args: unknown[]) => Record<string, unknown>>;
+/**
+ * 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 }`.
+ */
+declare function createActionCallbackProxy(): Record<string, unknown>;
+/**
+ * Create a component proxy for registered component references.
+ * Used in admin config functions (`.admin()`, `.actions()`, `.dashboard()`, `.sidebar()`).
+ */
+declare function createComponentProxy(builderState: Record<string, unknown>): Record<string, (props?: unknown) => unknown>;
+/**
+ * Create a field proxy for referencing collection fields.
+ * Returns field names as strings for config objects.
+ */
+declare function createFieldProxy<TFields extends Record<string, any>>(fieldNames: string[]): TFields;
+/**
+ * Create a view proxy for defining view configurations.
+ */
+declare function createViewProxy(kind: "list" | "form", registeredViews?: string[]): Record<string, (config: Record<string, unknown>) => unknown>;
+/**
+ * Create an action proxy for referencing built-in and custom actions.
+ */
+declare function createActionProxy(): {
+  create: string;
+  save: string;
+  delete: string;
+  deleteMany: string;
+  restore: string;
+  restoreMany: string;
+  duplicate: string;
+  export: string;
+  custom: (name: string, config?: unknown) => {
+    type: string;
+    config: unknown;
+  };
+};
+/**
+ * Create a sidebar proxy for contribution callbacks.
+ */
+declare function createSidebarContributionProxy(): SidebarProxy;
+/**
+ * Create a dashboard proxy for contribution callbacks.
+ */
+declare function createDashboardContributionProxy(): DashboardProxy;
+/**
+ * Create a sidebar callback context for resolving sidebar contributions.
+ */
+declare function createSidebarCallbackContext(): SidebarCallbackContext;
+/**
+ * Create a dashboard callback context for resolving dashboard contributions.
+ */
+declare function createDashboardCallbackContext(): DashboardCallbackContext;
+/**
+ * Resolve a sidebar callback or static value into a `SidebarContribution`.
+ */
+declare function resolveSidebarCallback(value: unknown): SidebarContribution | undefined;
+/**
+ * Resolve a dashboard callback or static value into a `DashboardContribution`.
+ */
+declare function resolveDashboardCallback(value: unknown): DashboardContribution | undefined;
+//#endregion
+export { createActionCallbackProxy, createActionProxy, createComponentCallbackProxy, createComponentProxy, createDashboardCallbackContext, createDashboardContributionProxy, createFieldProxy, createSidebarCallbackContext, createSidebarContributionProxy, createViewCallbackProxy, createViewProxy, resolveDashboardCallback, resolveSidebarCallback };