@questpie/admin 2.0.0 → 3.0.0

package/dist/server/augmentation/form-layout.d.mts

@@ -0,0 +1,303 @@
+import { ActionReference, ComponentReference } from "./common.mjs";
+import { I18nText } from "questpie/shared";
+
+//#region src/server/augmentation/form-layout.d.ts
+
+/**
+ * Admin metadata for a collection.
+ * Defines how the collection appears in the admin sidebar and UI.
+ */
+interface AdminCollectionConfig {
+  /** Display label for the collection */
+  label?: I18nText;
+  /** Description shown in tooltips/help text */
+  description?: I18nText;
+  /** Icon reference (resolved by client's icon component) */
+  icon?: ComponentReference;
+  /** Hide from admin sidebar */
+  hidden?: boolean;
+  /** Group in sidebar */
+  group?: string;
+  /** Order within group */
+  order?: number;
+  /**
+   * Whether this collection should be included in audit logging.
+   * Requires the audit module to be registered via `runtimeConfig({ modules: [auditModule] })`.
+   *
+   * - `true` or `undefined` (default): audited when audit module is active
+   * - `false`: never audited, even when audit module is active
+   */
+  audit?: boolean;
+}
+/**
+ * Block category configuration.
+ * Defines how blocks are grouped in the block picker.
+ */
+interface BlockCategoryConfig {
+  /** Display label for the category */
+  label: I18nText;
+  /** Icon for the category */
+  icon?: ComponentReference;
+  /** Order in block picker (lower = first) */
+  order?: number;
+}
+/**
+ * Admin metadata for a block.
+ * Defines how the block appears in the block picker and editor.
+ *
+ * @example
+ * ```ts
+ * block("hero")
+ *   .admin(({ c }) => ({
+ *     label: { en: "Hero Section", sk: "Hero sekcia" },
+ *     icon: c.icon("ph:image"),
+ *     category: {
+ *       label: { en: "Sections", sk: "Sekcie" },
+ *       icon: c.icon("ph:layout"),
+ *     },
+ *   }))
+ * ```
+ */
+interface AdminBlockConfig {
+  /** Display label for the block */
+  label?: I18nText;
+  /** Description shown in tooltips/help text */
+  description?: I18nText;
+  /** Icon reference (resolved by client's icon component) */
+  icon?: ComponentReference;
+  /** Category for grouping in block picker */
+  category?: BlockCategoryConfig;
+  /** Order within category in block picker (lower = first) */
+  order?: number;
+  /** Hide from block picker (useful for deprecated blocks) */
+  hidden?: boolean;
+}
+/**
+ * List view configuration for a collection.
+ * Defines columns, sorting, filtering, and actions.
+ */
+interface ListViewConfig {
+  /** View type to use (e.g., "table", "cards") */
+  view?: string;
+  /** Columns to display */
+  columns?: string[];
+  /** Default sort configuration */
+  defaultSort?: {
+    field: string;
+    direction: "asc" | "desc";
+  };
+  /** Searchable fields */
+  searchable?: string[];
+  /** Filterable fields */
+  filterable?: string[];
+  /** Actions configuration */
+  actions?: {
+    header?: {
+      primary?: ActionReference[];
+      secondary?: ActionReference[];
+    };
+    row?: ActionReference[];
+    bulk?: ActionReference[];
+  };
+}
+/**
+ * Context passed to form reactive handlers.
+ */
+interface FormReactiveContext<TData = Record<string, unknown>> {
+  data: TData;
+  sibling: Record<string, unknown>;
+  ctx: {
+    db: any;
+    user?: any;
+    locale?: string;
+  };
+  prev?: {
+    data: TData;
+    sibling: Record<string, unknown>;
+  };
+}
+/**
+ * Reactive config for field-level form behavior.
+ */
+type FormReactiveConfig<TData = any, TReturn = any> = ((ctx: FormReactiveContext<TData>) => TReturn | Promise<TReturn>) | {
+  handler: (ctx: FormReactiveContext<TData>) => TReturn | Promise<TReturn>;
+  deps?: string[] | ((ctx: FormReactiveContext<TData>) => any[]);
+  debounce?: number;
+} | {
+  deps: string[];
+  debounce?: number;
+};
+/**
+ * Section layout for form views.
+ * Groups fields with optional visual wrapper and layout mode.
+ *
+ * @example
+ * ```ts
+ * {
+ *   type: "section",
+ *   label: { en: "Contact Information" },
+ *   layout: "grid",
+ *   columns: 2,
+ *   fields: [f.name, f.email, f.phone],
+ * }
+ * ```
+ */
+interface FormSectionLayout {
+  type: "section";
+  /** Section label */
+  label?: I18nText;
+  /** Section description */
+  description?: I18nText;
+  /** Visual wrapper mode */
+  wrapper?: "flat" | "collapsible";
+  /** Default collapsed state (for collapsible wrapper) */
+  defaultCollapsed?: boolean;
+  /** Field arrangement mode */
+  layout?: "stack" | "inline" | "grid";
+  /** Number of columns (for grid layout) */
+  columns?: number;
+  /** Custom gap (in quarter rems) */
+  gap?: number;
+  /** Fields in this section */
+  fields: FieldLayoutItem[];
+  /** Conditional visibility */
+  hidden?: boolean;
+  /** Custom CSS class */
+  className?: string;
+}
+/**
+ * Tab configuration for tabbed form views.
+ */
+interface FormTabConfig {
+  /** Unique tab identifier */
+  id: string;
+  /** Tab label */
+  label: I18nText;
+  /** Tab icon */
+  icon?: ComponentReference;
+  /** Fields in this tab */
+  fields: FieldLayoutItem[];
+  /** Conditional visibility */
+  hidden?: boolean;
+}
+/**
+ * Tabs layout for form views.
+ *
+ * @example
+ * ```ts
+ * {
+ *   type: "tabs",
+ *   tabs: [
+ *     { id: "basic", label: { en: "Basic" }, fields: [f.name, f.email] },
+ *     { id: "advanced", label: { en: "Advanced" }, fields: [f.settings] },
+ *   ],
+ * }
+ * ```
+ */
+interface FormTabsLayout {
+  type: "tabs";
+  tabs: FormTabConfig[];
+}
+/**
+ * Field entry with optional reactive form behavior.
+ */
+interface FormFieldLayoutItem<TData = any> {
+  field: string;
+  className?: string;
+  hidden?: boolean | FormReactiveConfig<TData, boolean>;
+  readOnly?: boolean | FormReactiveConfig<TData, boolean>;
+  disabled?: boolean | FormReactiveConfig<TData, boolean>;
+  compute?: FormReactiveConfig<TData, any>;
+}
+/**
+ * Field layout item - union of field reference or layout container.
+ *
+ * Can be:
+ * - Field name string: `f.name`
+ * - Field with className: `{ field: "name", className: "col-span-2" }`
+ * - Section layout: `{ type: "section", ... }`
+ * - Tabs layout: `{ type: "tabs", ... }`
+ */
+type FieldLayoutItem = string | FormFieldLayoutItem | FormSectionLayout | FormTabsLayout;
+/**
+ * Form sidebar configuration.
+ * Places fields in a fixed sidebar alongside the main content.
+ *
+ * @example
+ * ```ts
+ * sidebar: {
+ *   position: "right",
+ *   fields: [f.isActive, f.avatar],
+ * }
+ * ```
+ */
+interface FormSidebarConfig {
+  /** Sidebar position (default: "right") */
+  position?: "left" | "right";
+  /** Fields in the sidebar */
+  fields: FieldLayoutItem[];
+}
+/**
+ * Form view configuration for a collection.
+ * Defines field layout with sections, tabs, and optional sidebar.
+ *
+ * @example
+ * ```ts
+ * v.collectionForm({
+ *   sidebar: { position: "right", fields: [f.status] },
+ *   fields: [
+ *     { type: "section", label: { en: "Details" }, layout: "grid", columns: 2, fields: [f.name, f.email] },
+ *     { type: "section", label: { en: "Content" }, fields: [f.body] },
+ *   ],
+ * })
+ * ```
+ */
+interface FormViewConfig {
+  /** View type to use (e.g., "form", "wizard") */
+  view?: string;
+  /** Main content fields */
+  fields: FieldLayoutItem[];
+  /** Sidebar configuration */
+  sidebar?: FormSidebarConfig;
+}
+/**
+ * Preview configuration for a collection.
+ * Enables live preview of content.
+ */
+interface PreviewConfig {
+  /** Enable preview panel */
+  enabled?: boolean;
+  /** Preview URL builder (runs on server) */
+  url?: (ctx: {
+    record: Record<string, unknown>;
+    locale?: string;
+  }) => string;
+  /** Preview panel position */
+  position?: "left" | "right" | "bottom";
+  /** Default panel width (percentage) */
+  defaultWidth?: number;
+}
+/**
+ * Admin metadata for a global.
+ */
+interface AdminGlobalConfig {
+  /** Display label */
+  label?: I18nText;
+  /** Description */
+  description?: I18nText;
+  /** Icon reference */
+  icon?: ComponentReference;
+  /** Hide from admin */
+  hidden?: boolean;
+  /** Group in sidebar */
+  group?: string;
+  /** Order within group */
+  order?: number;
+  /**
+   * Whether this global should be included in audit logging.
+   * @see AdminCollectionConfig.audit
+   */
+  audit?: boolean;
+}
+//#endregion
+export { AdminBlockConfig, AdminCollectionConfig, AdminGlobalConfig, BlockCategoryConfig, FieldLayoutItem, FormFieldLayoutItem, FormReactiveConfig, FormReactiveContext, FormSectionLayout, FormSidebarConfig, FormTabConfig, FormTabsLayout, FormViewConfig, ListViewConfig, PreviewConfig };

package/dist/server/augmentation/index.d.mts

@@ -0,0 +1,44 @@
+import { ActionReference, AdminLocaleConfig, ComponentReference, ComponentType, ComponentTypeRegistry } from "./common.mjs";
+import { AdminBlockConfig, AdminCollectionConfig, AdminGlobalConfig, BlockCategoryConfig, FieldLayoutItem, FormFieldLayoutItem, FormReactiveConfig, FormReactiveContext, FormSectionLayout, FormSidebarConfig, FormTabConfig, FormTabsLayout, FormViewConfig, ListViewConfig, PreviewConfig } from "./form-layout.mjs";
+import { AdminConfigContext, ComponentDefinition, ComponentFactory, EditViewDefinition, EditViewFactory, FilterViewsByKind, FormViewConfigContext, ListViewConfigContext, ListViewDefinition, ListViewFactory, ViewDefinition, ViewKind, ViewKindRegistry } from "./views.mjs";
+import { DashboardActionFactory, DashboardActionProxy, DashboardCallback, DashboardCallbackContext, DashboardConfigContext, DashboardContribution, DashboardItemDef, DashboardProxy, DashboardSectionDef, ServerBrandingConfig, ServerChartWidget, ServerCustomWidget, ServerDashboardAction, ServerDashboardConfig, ServerDashboardItem, ServerDashboardSection, ServerDashboardTab, ServerDashboardTabs, ServerDashboardWidget, ServerProgressWidget, ServerQuickAction, ServerQuickActionsWidget, ServerRecentItemsWidget, ServerStatsWidget, ServerTableWidget, ServerTimelineWidget, ServerValueWidget, WidgetAccessRule, WidgetFetchContext } from "./dashboard.mjs";
+import { ServerSidebarCollectionItem, ServerSidebarConfig, ServerSidebarDividerItem, ServerSidebarGlobalItem, ServerSidebarItem, ServerSidebarLinkItem, ServerSidebarPageItem, ServerSidebarSection, SidebarCallback, SidebarCallbackContext, SidebarConfigContext, SidebarContribution, SidebarItemDef, SidebarProxy, SidebarSectionDef } from "./sidebar.mjs";
+import { ActionsConfigContext, BuiltinActionType, ServerActionContext, ServerActionDefinition, ServerActionDownload, ServerActionEffects, ServerActionError, ServerActionForm, ServerActionFormField, ServerActionFormFieldConfig, ServerActionFormFieldDefinition, ServerActionHandler, ServerActionRedirect, ServerActionResult, ServerActionSuccess, ServerActionsConfig } from "./actions.mjs";
+
+//#region src/server/augmentation/index.d.ts
+
+/**
+ * Input type for `config/admin.ts` — a composite config file that consolidates
+ * sidebar, dashboard, branding, and locale into a single file.
+ *
+ * Used with `adminConfig()` factory for type inference.
+ *
+ * @example
+ * ```ts
+ * // config/admin.ts
+ * import { adminConfig } from "@questpie/admin/server";
+ *
+ * export default adminConfig({
+ *   sidebar: [s.section({ ... }), s.item({ ... })],
+ *   branding: { name: "My Admin" },
+ *   locale: { defaultLocale: "en" },
+ * });
+ * ```
+ */
+interface AdminConfigInput {
+  sidebar?: SidebarContribution;
+  dashboard?: DashboardContribution;
+  branding?: ServerBrandingConfig;
+  locale?: AdminLocaleConfig;
+}
+/**
+ * Identity factory for `config/admin.ts` — provides type inference.
+ */
+declare function adminConfig<T extends AdminConfigInput>(config: T): T;
+declare module "questpie" {
+  interface AppStateConfig {
+    admin?: AdminConfigInput;
+  }
+}
+//#endregion
+export { AdminConfigInput, adminConfig };

package/dist/server/augmentation/index.mjs

@@ -0,0 +1,10 @@
+//#region src/server/augmentation/index.ts
+/**
+* Identity factory for `config/admin.ts` — provides type inference.
+*/
+function adminConfig(config) {
+	return config;
+}
+
+//#endregion
+export { adminConfig };

package/dist/server/augmentation/sidebar.d.mts

@@ -0,0 +1,181 @@
+import { ComponentReference } from "./common.mjs";
+import { ComponentFactory } from "./views.mjs";
+import { I18nText } from "questpie/shared";
+
+//#region src/server/augmentation/sidebar.d.ts
+
+/**
+ * Server-side sidebar item types
+ */
+type ServerSidebarItem = ServerSidebarCollectionItem | ServerSidebarGlobalItem | ServerSidebarPageItem | ServerSidebarLinkItem | ServerSidebarDividerItem;
+/**
+ * Collection item in sidebar
+ */
+interface ServerSidebarCollectionItem {
+  type: "collection";
+  /** Collection name (validated against registered collections) */
+  collection: string;
+  /** Override display label */
+  label?: I18nText;
+  /** Override icon */
+  icon?: ComponentReference;
+}
+/**
+ * Global item in sidebar
+ */
+interface ServerSidebarGlobalItem {
+  type: "global";
+  /** Global name (validated against registered globals) */
+  global: string;
+  /** Override display label */
+  label?: I18nText;
+  /** Override icon */
+  icon?: ComponentReference;
+}
+/**
+ * Custom page item in sidebar
+ */
+interface ServerSidebarPageItem {
+  type: "page";
+  /** Page ID (resolved by client) */
+  pageId: string;
+  /** Display label */
+  label?: I18nText;
+  /** Icon */
+  icon?: ComponentReference;
+}
+/**
+ * External link item in sidebar
+ */
+interface ServerSidebarLinkItem {
+  type: "link";
+  /** Display label */
+  label: I18nText;
+  /** Link URL */
+  href: string;
+  /** Icon */
+  icon?: ComponentReference;
+  /** Open in new tab */
+  external?: boolean;
+}
+/**
+ * Divider item in sidebar
+ */
+interface ServerSidebarDividerItem {
+  type: "divider";
+}
+/**
+ * Sidebar section
+ */
+interface ServerSidebarSection {
+  /** Section ID (for targeting/extending) */
+  id: string;
+  /** Section title */
+  title?: I18nText;
+  /** Section icon */
+  icon?: ComponentReference;
+  /** Whether this section can be collapsed/expanded by the user */
+  collapsible?: boolean;
+  /** Section items */
+  items?: ServerSidebarItem[];
+  /** Nested subsections */
+  sections?: ServerSidebarSection[];
+}
+/**
+ * Server-side sidebar configuration (final merged output)
+ */
+interface ServerSidebarConfig {
+  /** Sidebar sections */
+  sections: ServerSidebarSection[];
+}
+/**
+ * Sidebar contribution — what a module or user config contributes.
+ * Multiple contributions are merged by createApp() (§5.8.3).
+ * Resolved from callback: `sidebar: ({ s, c }) => ({ sections: [...], items: [...] })`
+ */
+interface SidebarContribution {
+  /** Section definitions — merged by id across modules. Later wins for title/icon. */
+  sections?: SidebarSectionDef[];
+  /** Items — appended to sections by sectionId. Module resolution order. */
+  items?: SidebarItemDef[];
+}
+/**
+ * Sidebar section definition for contributions.
+ */
+interface SidebarSectionDef {
+  /** Unique section ID — used for targeting from other modules. */
+  id: string;
+  /** Section title. */
+  title?: I18nText;
+  /** Section icon. */
+  icon?: ComponentReference;
+  /** Whether section is collapsible. */
+  collapsible?: boolean;
+}
+/**
+ * Sidebar item definition for contributions.
+ * Each item references a sectionId to indicate which section it belongs to.
+ */
+interface SidebarItemDef extends Omit<ServerSidebarItem, "type"> {
+  /** Which section this item belongs to. */
+  sectionId: string;
+  /** 'start' to prepend, default is 'end' (append). */
+  position?: "start" | "end";
+  /** Item type. */
+  type: "collection" | "global" | "page" | "link" | "divider";
+  /** Collection slug (when type = "collection"). */
+  collection?: string;
+  /** Global slug (when type = "global"). */
+  global?: string;
+  /** Page ID (when type = "page"). */
+  pageId?: string;
+  /** Display label (for links, overrides). */
+  label?: I18nText;
+  /** URL (for links). */
+  href?: string;
+  /** Icon reference. */
+  icon?: ComponentReference;
+  /** Open in new tab (for links). */
+  external?: boolean;
+}
+/**
+ * Sidebar proxy — provided in sidebar callbacks as `s`.
+ * Creates serializable contribution objects.
+ */
+interface SidebarProxy {
+  /** Define a sidebar section. */
+  section(def: SidebarSectionDef): SidebarSectionDef;
+  /** Define a sidebar item. */
+  item(def: SidebarItemDef): SidebarItemDef;
+}
+/**
+ * Context for sidebar callbacks on module() and config().
+ */
+interface SidebarCallbackContext {
+  /** Sidebar builder proxy. */
+  s: SidebarProxy;
+  /** Component proxy (scoped to registered components). */
+  c: ComponentFactory;
+}
+/**
+ * Sidebar callback type for module() and config().
+ */
+type SidebarCallback = (ctx: SidebarCallbackContext) => SidebarContribution;
+/**
+ * Context for sidebar config function
+ */
+interface SidebarConfigContext<TComponents extends Record<string, any> | string = string> {
+  /** Sidebar builder helpers */
+  s: {
+    /** Create sidebar config */
+    sidebar: (config: ServerSidebarConfig) => ServerSidebarConfig;
+    /** Create a section */
+    section: (config: Omit<ServerSidebarSection, "items"> & {
+      items?: ServerSidebarItem[];
+    }) => ServerSidebarSection;
+  };
+  /** Component helpers (from registered component registry) */
+  c: ComponentFactory<TComponents>;
+}
+//#endregion
+export { ServerSidebarCollectionItem, ServerSidebarConfig, ServerSidebarDividerItem, ServerSidebarGlobalItem, ServerSidebarItem, ServerSidebarLinkItem, ServerSidebarPageItem, ServerSidebarSection, SidebarCallback, SidebarCallbackContext, SidebarConfigContext, SidebarContribution, SidebarItemDef, SidebarProxy, SidebarSectionDef };