@questpie/admin 1.1.1 → 3.0.0

package/dist/augmentation.d.mts

@@ -0,0 +1,414 @@
+import { ReactiveConfig } from "questpie";
+
+//#region src/augmentation.d.ts
+
+/**
+ * Common admin options shared by all fields.
+ * Each field-specific admin meta extends this.
+ *
+ * Supports reactive configurations for dynamic field states:
+ * - `hidden`, `readOnly`, `disabled` can be boolean or reactive function
+ * - `compute` can auto-generate field values based on other fields
+ */
+interface BaseAdminMeta {
+  /**
+   * Field width in form (CSS value or number for pixels).
+   * @example "100%" | 400 | "50%"
+   */
+  width?: string | number;
+  /**
+   * Column span in grid layout (1-12).
+   * @default 12
+   */
+  colspan?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+  /**
+   * Field group for form organization.
+   */
+  group?: string;
+  /**
+   * Display order within group.
+   */
+  order?: number;
+  /**
+   * Hide the field conditionally.
+   * - `true`: Always hidden
+   * - Function/config: Evaluated on server based on form data
+   *
+   * @example Static
+   * ```ts
+   * hidden: true
+   * ```
+   *
+   * @example Reactive (short syntax)
+   * ```ts
+   * hidden: ({ data }) => !data.showAdvanced
+   * ```
+   *
+   * @example Reactive (full syntax with deps)
+   * ```ts
+   * hidden: {
+   *   handler: ({ data }) => !data.showAdvanced,
+   *   deps: ['showAdvanced'],
+   * }
+   * ```
+   */
+  hidden?: boolean | ReactiveConfig<boolean>;
+  /**
+   * Make field read-only conditionally.
+   * - `true`: Always read-only
+   * - Function/config: Evaluated on server based on form data
+   *
+   * @example Reactive
+   * ```ts
+   * readOnly: ({ data }) => data.status === 'published'
+   * ```
+   */
+  readOnly?: boolean | ReactiveConfig<boolean>;
+  /**
+   * Disable the field conditionally.
+   * - `true`: Always disabled
+   * - Function/config: Evaluated on server based on form data
+   *
+   * @example Reactive
+   * ```ts
+   * disabled: ({ data }) => data.isLocked
+   * ```
+   */
+  disabled?: boolean | ReactiveConfig<boolean>;
+  /**
+   * Compute field value automatically based on other fields.
+   * Handler should return the computed value or undefined to keep current.
+   * Return null to reset field to null/default.
+   *
+   * @example Auto-generate slug from title
+   * ```ts
+   * compute: ({ data }) => slugify(data.title)
+   * ```
+   *
+   * @example With debounce and explicit deps
+   * ```ts
+   * compute: {
+   *   handler: ({ data }) => slugify(data.title),
+   *   deps: ['title'],
+   *   debounce: 300,
+   * }
+   * ```
+   *
+   * @example Reset on parent change
+   * ```ts
+   * compute: ({ data, prev }) => {
+   *   if (data.category !== prev.data.category) {
+   *     return null; // Reset when category changes
+   *   }
+   * }
+   * ```
+   */
+  compute?: ReactiveConfig<any>;
+  /**
+   * Show this field in list view columns.
+   */
+  showInList?: boolean;
+  /**
+   * Column width in list view.
+   */
+  listWidth?: string | number;
+  /**
+   * Enable sorting by this field.
+   */
+  sortable?: boolean;
+  /**
+   * Enable filtering by this field.
+   */
+  filterable?: boolean;
+}
+/**
+ * Text field admin options
+ */
+interface TextFieldAdminMeta extends BaseAdminMeta {
+  placeholder?: string;
+  showCounter?: boolean;
+  prefix?: string;
+  suffix?: string;
+  inputType?: "text" | "email" | "url" | "tel" | "search" | "password";
+}
+/**
+ * Email field admin options
+ */
+interface EmailFieldAdminMeta extends BaseAdminMeta {
+  placeholder?: string;
+  /** Show domain hint (e.g., "@company.com") */
+  domainHint?: string;
+}
+/**
+ * URL field admin options
+ */
+interface UrlFieldAdminMeta extends BaseAdminMeta {
+  placeholder?: string;
+  /** Show protocol dropdown (http/https) */
+  showProtocolDropdown?: boolean;
+  /** Default protocol if not provided */
+  defaultProtocol?: "http" | "https";
+}
+/**
+ * Textarea field admin options
+ */
+interface TextareaFieldAdminMeta extends BaseAdminMeta {
+  placeholder?: string;
+  rows?: number;
+  autoResize?: boolean;
+  richText?: boolean;
+  showCounter?: boolean;
+}
+/**
+ * Number field admin options
+ */
+interface NumberFieldAdminMeta extends BaseAdminMeta {
+  placeholder?: string;
+  showButtons?: boolean;
+  step?: number;
+}
+/**
+ * Boolean field admin options
+ */
+interface BooleanFieldAdminMeta extends BaseAdminMeta {
+  displayAs?: "checkbox" | "switch";
+}
+/**
+ * Date field admin options
+ */
+interface DateFieldAdminMeta extends BaseAdminMeta {
+  placeholder?: string;
+}
+/**
+ * Time field admin options
+ */
+interface TimeFieldAdminMeta extends BaseAdminMeta {
+  placeholder?: string;
+}
+/**
+ * Select field admin options
+ */
+interface SelectFieldAdminMeta extends BaseAdminMeta {
+  displayAs?: "dropdown" | "radio" | "checkbox" | "buttons";
+  searchable?: boolean;
+  creatable?: boolean;
+  clearable?: boolean;
+}
+/**
+ * Relation field admin options
+ */
+interface RelationFieldAdminMeta extends BaseAdminMeta {
+  displayAs?: "select" | "table" | "cards" | "list";
+  displayFields?: string[];
+  titleField?: string;
+  allowCreate?: boolean;
+  allowEdit?: boolean;
+  preload?: boolean;
+  maxItems?: number;
+  /**
+   * List table cell rendering for relation values.
+   * - "chip": default text chip
+   * - "avatarChip": chip with avatar image + label
+   */
+  listCell?: {
+    display?: "chip" | "avatarChip";
+    /** Dot-path on related record (e.g. "image" or "avatar.url") */
+    avatarField?: string;
+    /** Dot-path for display label override (e.g. "fullName") */
+    labelField?: string;
+  };
+}
+/**
+ * Object field admin options
+ */
+interface ObjectFieldAdminMeta extends BaseAdminMeta {
+  /** Visual wrapper mode */
+  wrapper?: "flat" | "collapsible";
+  /** Field arrangement mode */
+  layout?: "stack" | "inline" | "grid";
+  /** Number of columns (for grid layout) */
+  columns?: number;
+  /** Default collapsed state (for collapsible wrapper) */
+  defaultCollapsed?: boolean;
+}
+/**
+ * Array field admin options
+ */
+interface ArrayFieldAdminMeta extends BaseAdminMeta {
+  /** Enable drag-and-drop reordering */
+  orderable?: boolean;
+  /** Minimum number of items */
+  minItems?: number;
+  /** Maximum number of items */
+  maxItems?: number;
+  /** Item editing mode */
+  mode?: "inline" | "modal" | "drawer";
+  /** Field arrangement mode for items */
+  layout?: "stack" | "inline" | "grid";
+  /** Number of columns (for grid layout) */
+  columns?: number;
+  /** Label for array items */
+  itemLabel?: string;
+}
+/**
+ * JSON field admin options
+ */
+interface JsonFieldAdminMeta extends BaseAdminMeta {
+  /** Show as code editor */
+  codeEditor?: boolean;
+}
+/**
+ * Upload field admin options
+ */
+interface UploadFieldAdminMeta extends BaseAdminMeta {
+  /** Accepted file types */
+  accept?: string | string[];
+  /** Dropzone placeholder text */
+  dropzoneText?: string;
+  /** Show file preview */
+  showPreview?: boolean;
+  /** Allow editing uploaded files */
+  editable?: boolean;
+  /** Preview display variant */
+  previewVariant?: "card" | "compact" | "thumbnail";
+  /** Allow multiple file uploads */
+  multiple?: boolean;
+  /** Maximum number of files */
+  maxItems?: number;
+  /** Enable drag-and-drop reordering */
+  orderable?: boolean;
+  /** Layout for multiple files */
+  layout?: "grid" | "list";
+}
+/**
+ * Rich text field admin options
+ */
+interface RichTextFieldAdminMeta extends BaseAdminMeta {
+  /** Placeholder text when editor is empty */
+  placeholder?: string;
+  /** Show character count */
+  showCharacterCount?: boolean;
+  /** Maximum characters allowed */
+  maxCharacters?: number;
+  /** Minimum characters required */
+  minCharacters?: number;
+  /** Enable image uploads within editor */
+  enableImages?: boolean;
+  /** Collection to use for image uploads */
+  imageCollection?: string;
+  /** Enable media library integration */
+  enableMediaLibrary?: boolean;
+}
+/**
+ * Blocks field admin options
+ */
+interface BlocksFieldAdminMeta extends BaseAdminMeta {
+  /** Label for add block button */
+  addLabel?: string;
+  /** Message shown when no blocks present */
+  emptyMessage?: string;
+  /** Maximum number of blocks allowed */
+  maxBlocks?: number;
+  /** Minimum number of blocks required */
+  minBlocks?: number;
+  /** Enable drag & drop reordering */
+  sortable?: boolean;
+  /** Show block type selector as dropdown or grid */
+  selectorDisplayAs?: "dropdown" | "grid";
+  /** Default collapsed state for blocks */
+  defaultCollapsed?: boolean;
+}
+type AnyAdminMeta = TextFieldAdminMeta | TextareaFieldAdminMeta | EmailFieldAdminMeta | UrlFieldAdminMeta | NumberFieldAdminMeta | BooleanFieldAdminMeta | DateFieldAdminMeta | TimeFieldAdminMeta | SelectFieldAdminMeta | RelationFieldAdminMeta | ObjectFieldAdminMeta | ArrayFieldAdminMeta | JsonFieldAdminMeta | UploadFieldAdminMeta | RichTextFieldAdminMeta | BlocksFieldAdminMeta;
+/**
+ * Base widget admin meta (common options for all widgets)
+ */
+interface BaseWidgetAdminMeta {
+  /** Default grid span */
+  span?: number;
+  /** Default refresh interval */
+  refreshInterval?: number;
+}
+/**
+ * Registry interface for widget types.
+ * Users can augment this to add custom widget type configs.
+ *
+ * @example
+ * ```ts
+ * declare module "@questpie/admin" {
+ *   interface WidgetTypeRegistry {
+ *     myCustomWidget: { loader: (client: any) => Promise<MyData> };
+ *   }
+ * }
+ * ```
+ */
+interface WidgetTypeRegistry {
+  stats: {};
+  chart: {};
+  recentItems: {};
+  quickActions: {};
+  value: {};
+  table: {};
+  timeline: {};
+  progress: {};
+}
+declare global {
+  namespace Questpie {
+    interface TextFieldMeta {
+      admin?: TextFieldAdminMeta;
+    }
+    interface EmailFieldMeta {
+      admin?: EmailFieldAdminMeta;
+    }
+    interface UrlFieldMeta {
+      admin?: UrlFieldAdminMeta;
+    }
+    interface TextareaFieldMeta {
+      admin?: TextareaFieldAdminMeta;
+    }
+    interface NumberFieldMeta {
+      admin?: NumberFieldAdminMeta;
+    }
+    interface BooleanFieldMeta {
+      admin?: BooleanFieldAdminMeta;
+    }
+    interface DateFieldMeta {
+      admin?: DateFieldAdminMeta;
+    }
+    interface DatetimeFieldMeta {
+      admin?: DateFieldAdminMeta;
+    }
+    interface TimeFieldMeta {
+      admin?: TimeFieldAdminMeta;
+    }
+    interface SelectFieldMeta {
+      admin?: SelectFieldAdminMeta;
+    }
+    interface RelationFieldMeta {
+      admin?: RelationFieldAdminMeta;
+    }
+    interface ObjectFieldMeta {
+      admin?: ObjectFieldAdminMeta;
+    }
+    interface ArrayFieldMeta {
+      admin?: ArrayFieldAdminMeta;
+    }
+    interface JsonFieldMeta {
+      admin?: JsonFieldAdminMeta;
+    }
+    interface UploadFieldMeta {
+      admin?: UploadFieldAdminMeta;
+    }
+  }
+}
+declare module "./server/fields/rich-text.js" {
+  interface RichTextFieldMeta {
+    admin?: RichTextFieldAdminMeta;
+  }
+}
+declare module "./server/fields/blocks.js" {
+  interface BlocksFieldMeta {
+    admin?: BlocksFieldAdminMeta;
+  }
+}
+//#endregion
+export { AnyAdminMeta, ArrayFieldAdminMeta, BaseAdminMeta, BaseWidgetAdminMeta, BooleanFieldAdminMeta, DateFieldAdminMeta, JsonFieldAdminMeta, NumberFieldAdminMeta, ObjectFieldAdminMeta, RelationFieldAdminMeta, SelectFieldAdminMeta, TextFieldAdminMeta, TextareaFieldAdminMeta, TimeFieldAdminMeta, UploadFieldAdminMeta, WidgetTypeRegistry };

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

@@ -0,0 +1,45 @@
+import { BlockContent } from "./types.mjs";
+import * as React from "react";
+import * as react_jsx_runtime23 from "react/jsx-runtime";
+
+//#region src/client/blocks/block-renderer.d.ts
+
+/**
+ * Block renderer function type.
+ * Consumers provide their own renderers mapped by block type.
+ */
+type BlockRendererFn = (props: any) => React.ReactNode;
+/**
+ * Props for BlockRenderer component.
+ */
+type BlockRendererProps = {
+  /** Block content from API (tree + values) */
+  content: BlockContent;
+  /** Block renderers mapped by type */
+  renderers: Record<string, BlockRendererFn>;
+  /** Prefetched data by block ID (optional, for SSR) */
+  data?: Record<string, unknown>;
+  /** Currently selected block ID (for editor mode) */
+  selectedBlockId?: string | null;
+  /** Block click handler (for editor mode) */
+  onBlockClick?: (blockId: string) => void;
+  /** Custom class name for the container */
+  className?: string;
+};
+/**
+ * Renders a tree of blocks.
+ *
+ * Iterates through the block tree and renders each block using its
+ * registered renderer component. Layout blocks receive their rendered
+ * children as the `children` prop.
+ */
+declare function BlockRenderer({
+  content,
+  renderers,
+  data,
+  selectedBlockId,
+  onBlockClick,
+  className
+}: BlockRendererProps): react_jsx_runtime23.JSX.Element | null;
+//#endregion
+export { BlockRenderer, BlockRendererProps };

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

@@ -0,0 +1,105 @@
+import { BlockScopeProvider } from "../preview/block-scope-context.mjs";
+import { c } from "react/compiler-runtime";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/client/blocks/block-renderer.tsx
+const EMPTY_DATA = {};
+/**
+* Renders a tree of blocks.
+*
+* Iterates through the block tree and renders each block using its
+* registered renderer component. Layout blocks receive their rendered
+* children as the `children` prop.
+*/
+function BlockRenderer(t0) {
+	const $ = c(11);
+	const { content, renderers, data, onBlockClick, className } = t0;
+	const resolvedData = data ?? EMPTY_DATA;
+	let t1;
+	let t2;
+	let t3;
+	if ($[0] !== className || $[1] !== content || $[2] !== onBlockClick || $[3] !== renderers || $[4] !== resolvedData) {
+		t3 = Symbol.for("react.early_return_sentinel");
+		bb0: {
+			function renderBlock(node) {
+				const renderFn = renderers[node.type];
+				if (!renderFn) {
+					if (process.env.NODE_ENV !== "production") console.warn(`[BlockRenderer] No renderer found for block type "${node.type}"`);
+					return null;
+				}
+				const values = content._values[node.id] || {};
+				const blockData = resolvedData[node.id];
+				const renderedChildren = node.children.length > 0 ? node.children.map(renderBlock) : void 0;
+				const handleClick = onBlockClick ? (e) => {
+					e.stopPropagation();
+					onBlockClick(node.id);
+				} : void 0;
+				const BlockComponent = renderFn;
+				const blockElement = /* @__PURE__ */ jsx(BlockScopeProvider, {
+					blockId: node.id,
+					basePath: "content._values",
+					children: /* @__PURE__ */ jsx(BlockComponent, {
+						id: node.id,
+						type: node.type,
+						values,
+						data: blockData,
+						children: renderedChildren
+					})
+				});
+				if (handleClick) return /* @__PURE__ */ jsx("div", {
+					"data-block-id": node.id,
+					"data-block-type": node.type,
+					onClick: handleClick,
+					onKeyDown: (e_0) => {
+						if (e_0.key === "Enter" || e_0.key === " ") {
+							e_0.preventDefault();
+							onBlockClick?.(node.id);
+						}
+					},
+					role: "button",
+					tabIndex: 0,
+					className: "cursor-pointer",
+					children: blockElement
+				}, node.id);
+				return /* @__PURE__ */ jsx("div", {
+					"data-block-id": node.id,
+					"data-block-type": node.type,
+					children: blockElement
+				}, node.id);
+			}
+			if (!content?._tree?.length) {
+				t3 = null;
+				break bb0;
+			}
+			t1 = className;
+			t2 = content._tree.map(renderBlock);
+		}
+		$[0] = className;
+		$[1] = content;
+		$[2] = onBlockClick;
+		$[3] = renderers;
+		$[4] = resolvedData;
+		$[5] = t1;
+		$[6] = t2;
+		$[7] = t3;
+	} else {
+		t1 = $[5];
+		t2 = $[6];
+		t3 = $[7];
+	}
+	if (t3 !== Symbol.for("react.early_return_sentinel")) return t3;
+	let t4;
+	if ($[8] !== t1 || $[9] !== t2) {
+		t4 = /* @__PURE__ */ jsx("div", {
+			className: t1,
+			children: t2
+		});
+		$[8] = t1;
+		$[9] = t2;
+		$[10] = t4;
+	} else t4 = $[10];
+	return t4;
+}
+
+//#endregion
+export { BlockRenderer };

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

@@ -0,0 +1,2 @@
+import { BlockCategory, BlockContent, BlockNode, BlockRendererProps, EMPTY_BLOCK_CONTENT, isBlockContent } from "./types.mjs";
+import { BlockRenderer, BlockRendererProps as BlockRendererProps$1 } from "./block-renderer.mjs";

package/dist/client/blocks/types.d.mts

@@ -0,0 +1,68 @@
+import * as React from "react";
+
+//#region src/client/blocks/types.d.ts
+
+/**
+ * Block node in the tree structure.
+ * Represents a single block instance with its position and children.
+ */
+type BlockNode = {
+  /** Unique block instance ID (UUID) */
+  id: string;
+  /** Block type name (e.g., "hero", "columns", "text") */
+  type: string;
+  /** Child blocks (for layout blocks that accept children) */
+  children: BlockNode[];
+};
+/**
+ * Block content structure stored in JSONB.
+ * This is the shape of data stored in the database and passed to BlockRenderer.
+ *
+ * After server-side prefetch (afterRead hook), `_data` is populated with:
+ * - Auto-expanded relation/upload fields
+ * - Manual prefetch data from `.blocks()` registration
+ */
+type BlockContent = {
+  /** Block tree with hierarchy and order */
+  _tree: BlockNode[];
+  /** Block values indexed by block ID */
+  _values: Record<string, Record<string, unknown>>;
+  /** Prefetched data from server (populated by afterRead hook) */
+  _data?: Record<string, Record<string, unknown>>;
+};
+/**
+ * Block category for organization in the block picker.
+ * Categories help users find blocks quickly when adding new content.
+ */
+type BlockCategory = "layout" | "content" | "media" | "sections" | "interactive" | (string & {});
+/**
+ * Props passed to block renderer components.
+ * Each block receives these props when being rendered.
+ *
+ * @template TValues - Block field values type (inferred from `.fields()`)
+ * @template TData - Prefetch data type (inferred from `.prefetch()`)
+ */
+type BlockRendererProps<TValues = Record<string, unknown>, TData = Record<string, unknown>> = {
+  /** Block instance ID */
+  id: string;
+  /** Block field values (merged with i18n for current locale) */
+  values: TValues;
+  /** Data from server prefetch (populated via afterRead hook into _data[blockId]) */
+  data?: TData;
+  /** Rendered child blocks (for layout blocks) */
+  children?: React.ReactNode;
+  /** Whether this block is currently selected in the editor */
+  isSelected?: boolean;
+  /** Whether rendering in preview mode */
+  isPreview?: boolean;
+};
+/**
+ * Empty block content for initialization.
+ */
+declare const EMPTY_BLOCK_CONTENT: BlockContent;
+/**
+ * Check if a value is a valid BlockContent structure.
+ */
+declare function isBlockContent(value: unknown): value is BlockContent;
+//#endregion
+export { BlockCategory, BlockContent, BlockNode, BlockRendererProps, EMPTY_BLOCK_CONTENT, isBlockContent };

package/dist/client/blocks/types.mjs

@@ -0,0 +1,19 @@
+//#region src/client/blocks/types.ts
+/**
+* Empty block content for initialization.
+*/
+const EMPTY_BLOCK_CONTENT = {
+	_tree: [],
+	_values: {}
+};
+/**
+* Check if a value is a valid BlockContent structure.
+*/
+function isBlockContent(value) {
+	if (value == null || typeof value !== "object") return false;
+	const obj = value;
+	return Array.isArray(obj._tree) && typeof obj._values === "object" && obj._values !== null;
+}
+
+//#endregion
+export { EMPTY_BLOCK_CONTENT, isBlockContent };

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

@@ -0,0 +1,40 @@
+import { SimpleMessages } from "../i18n/simple.mjs";
+import { MaybeLazyComponent } from "./types/common.mjs";
+import { FieldDefinition } from "./field/field.mjs";
+import { PageDefinition } from "./page/page.mjs";
+import { LocaleConfig } from "./types/ui-config.mjs";
+import { ViewDefinition } from "./view/view.mjs";
+import { WidgetDefinition } from "./widget/widget.mjs";
+
+//#region src/client/builder/admin-types.d.ts
+
+/**
+ * Translations map: locale -> key -> message
+ */
+type TranslationsMap = Record<string, SimpleMessages>;
+type FieldDefinitionMap = Record<string, FieldDefinition>;
+type ViewDefinitionMap = Record<string, ViewDefinition>;
+type PageDefinitionMap = Record<string, PageDefinition>;
+type WidgetDefinitionMap = Record<string, WidgetDefinition>;
+type ComponentDefinitionMap = Record<string, MaybeLazyComponent<any>>;
+type BlockDefinitionMap = Record<string, never>;
+/**
+ * Admin state — flat map of all admin registrations.
+ *
+ * Pure data: maps names to components. All config flows from server introspection.
+ *
+ * TApp: Backend Questpie app type — provides collection/global names for autocomplete
+ */
+interface AdminState<TApp = any, TFields extends FieldDefinitionMap = FieldDefinitionMap, TComponents extends ComponentDefinitionMap = ComponentDefinitionMap, TViews extends ViewDefinitionMap = ViewDefinitionMap, TPages extends PageDefinitionMap = PageDefinitionMap, TWidgets extends WidgetDefinitionMap = WidgetDefinitionMap, TBlocks extends BlockDefinitionMap = BlockDefinitionMap, TTranslations extends TranslationsMap = TranslationsMap> {
+  "~app": TApp;
+  fields: TFields;
+  components: TComponents;
+  views: TViews;
+  pages: TPages;
+  widgets: TWidgets;
+  blocks: TBlocks;
+  translations: TTranslations;
+  locale: LocaleConfig;
+}
+//#endregion
+export { AdminState, BlockDefinitionMap, ComponentDefinitionMap, FieldDefinitionMap, PageDefinitionMap, TranslationsMap, ViewDefinitionMap, WidgetDefinitionMap };