@marianmeres/collection-types 1.19.0 → 1.21.0

package/dist/custom-pages.d.ts

@@ -1,29 +1,35 @@
 /**
- * Custom Pages Configuration Types
+ * Custom Pages Configuration Types (v2 - 3-Level Hierarchy)
  *
  * These types define the structure of the `__joy_custom_pages__` config record
- * stored in the project's config collection. They establish a contract for
- * defining project-specific custom UI pages with lazy loading support.
+ * stored in the project's config collection.
+ *
+ * Hierarchy:
+ * - Level 1: Group (shown in sidebar with expand/collapse)
+ * - Level 2: Page (shown as items within expanded group)
+ * - Level 3: Tab (shown as tabs within a page)
+ *
+ * URL Pattern: #/p/{projectId}/custom/{groupId}/{pageId}?/{tabPath}?
  *
  * @module custom-pages/types
  */
 import type { MaybeLocalized } from "./utils.js";
 /**
- * Nested route definition within a custom page.
- * Supports tabs, wizard steps, or multi-step flows.
+ * Tab definition within a page (Level 3).
+ * Tabs are rendered as secondary navigation within a page.
  */
-export interface CustomPageNestedRoute {
+export interface CustomPageTab {
     /**
-     * Unique path segment (e.g., "overview", "settings", "step-1").
-     * Used in URL: #/p/{projectId}/custom/{pageId}/{path}
+     * Unique path segment for this tab.
+     * Used in URL: #/p/{projectId}/custom/{groupId}/{pageId}/{path}
      */
     path: string;
     /**
-     * Display label for navigation (tabs, breadcrumbs).
+     * Display label for the tab.
      */
     label: MaybeLocalized<string>;
     /**
-     * Icon identifier for the tab/step.
+     * Icon identifier for the tab.
      */
     icon?: string;
     /**
@@ -32,85 +38,119 @@ export interface CustomPageNestedRoute {
      */
     order?: number;
     /**
-     * Whether this is the default route when parent page is accessed.
-     * If no default is specified, the first route by order is used.
+     * Whether this is the default tab when page is accessed without tab path.
+     * If no default is specified, the first tab by order is used.
      */
     default?: boolean;
     /**
-     * Component file name within _routes/ directory.
-     * Defaults to path if not specified.
-     * @example "Overview" for "_routes/Overview.svelte"
+     * Component file name within _tabs/ directory.
+     * Defaults to capitalized path if not specified.
+     * @example "Overview" for "_tabs/Overview.svelte"
      */
     component?: string;
 }
 /**
- * Navigation metadata for a custom page.
+ * Page definition within a group (Level 2).
+ * Pages are shown as items within an expanded group in the sidebar.
  */
-export interface CustomPageNavMeta {
+export interface CustomPageDef {
     /**
-     * Display label in navigation.
+     * Unique identifier for this page within the group.
+     * Used in URL: #/p/{projectId}/custom/{groupId}/{id}
+     * Must match directory name: src/custom-pages/pages/{groupId}/{id}/
+     */
+    id: string;
+    /**
+     * Display label for the page in navigation.
      */
     label: MaybeLocalized<string>;
     /**
-     * Icon identifier (matches ICON_MAP in LeftSidebarNav).
+     * Human-readable description of what this page does.
+     */
+    description?: string;
+    /**
+     * Icon identifier for the page.
      */
     icon?: string;
     /**
-     * Display order in the custom pages section (lower = first).
+     * Display order within the group (lower = first).
      * @default 0
      */
     order?: number;
     /**
-     * Optional grouping label for organizing multiple custom pages.
+     * Whether this is the default page when group is accessed without page ID.
+     * If no default is specified, the first page by order is used.
      */
-    group?: MaybeLocalized<string>;
+    default?: boolean;
+    /**
+     * Whether this page is enabled.
+     * @default true
+     */
+    enabled?: boolean;
     /**
-     * Icon for the group header.
+     * Component file name (defaults to "Page" for Page.svelte).
      */
-    groupIcon?: string;
+    component?: string;
+    /**
+     * Tabs within this page (Level 3).
+     * If specified and non-empty, the page will show tab navigation.
+     * If empty or undefined, page content is rendered directly.
+     */
+    tabs?: CustomPageTab[];
 }
 /**
- * A single custom page definition.
+ * Navigation metadata for a group.
  */
-export interface CustomPageDef {
+export interface CustomPageNavMeta {
     /**
-     * Unique identifier for this page.
-     * Used in URL: #/p/{projectId}/custom/{id}
-     * Must match directory name in src/custom-pages/pages/{id}/
+     * Display label in navigation.
      */
-    id: string;
+    label: MaybeLocalized<string>;
     /**
-     * Human-readable description of what this page does.
+     * Icon identifier (matches ICON_MAP in LeftSidebarNav).
      */
-    description?: string;
+    icon?: string;
     /**
-     * Route pattern for this page.
-     * Supports parameters: /reports/[reportType]
-     * Defaults to "/{id}" if not specified.
+     * Display order in the custom pages section (lower = first).
+     * @default 0
      */
-    route?: string;
+    order?: number;
+}
+/**
+ * Group definition (Level 1).
+ * Groups are shown in the sidebar with expand/collapse functionality.
+ */
+export interface CustomPageGroupDef {
     /**
-     * Navigation metadata.
+     * Unique identifier for this group.
+     * Used in URL: #/p/{projectId}/custom/{id}
+     * Must match directory name: src/custom-pages/pages/{id}/
      */
-    nav: CustomPageNavMeta;
+    id: string;
     /**
-     * Nested routes (tabs, wizard steps, etc.)
-     * If specified, the page component receives an `activeNestedRoute` prop.
+     * Human-readable description of this group.
      */
-    nestedRoutes?: CustomPageNestedRoute[];
+    description?: string;
     /**
-     * Whether this page is enabled.
+     * Whether this group is enabled.
      * @default true
      */
     enabled?: boolean;
+    /**
+     * Navigation metadata for the group.
+     */
+    nav: CustomPageNavMeta;
+    /**
+     * Pages within this group (Level 2).
+     */
+    pages: CustomPageDef[];
     /**
      * Priority for route matching (higher = checked first).
-     * Prevents conflicts with more generic routes.
      * @default 0
      */
     priority?: number;
     /**
-     * Required permissions to access this page.
+     * Required permissions to access this group.
      * If specified, user must have at least one of these permissions.
      */
     permissions?: string[];
@@ -133,19 +173,18 @@ export interface CustomPagesNavSection {
     divider?: boolean;
 }
 /**
- * The complete custom pages configuration structure.
+ * The complete custom pages configuration structure (v2).
  * Stored as the `value` of the `__joy_custom_pages__` config record.
  */
 export interface CustomPagesConfig {
     /**
-     * Schema version for future migrations.
-     * @default 1
+     * Schema version. Must be 2 for 3-level hierarchy.
      */
     version: number;
     /**
-     * Array of custom page definitions.
+     * Array of group definitions (Level 1).
      */
-    pages: CustomPageDef[];
+    groups: CustomPageGroupDef[];
     /**
      * Section configuration for the navigation.
      */

package/dist/custom-pages.js

@@ -1,9 +1,15 @@
 /**
- * Custom Pages Configuration Types
+ * Custom Pages Configuration Types (v2 - 3-Level Hierarchy)
  *
  * These types define the structure of the `__joy_custom_pages__` config record
- * stored in the project's config collection. They establish a contract for
- * defining project-specific custom UI pages with lazy loading support.
+ * stored in the project's config collection.
+ *
+ * Hierarchy:
+ * - Level 1: Group (shown in sidebar with expand/collapse)
+ * - Level 2: Page (shown as items within expanded group)
+ * - Level 3: Tab (shown as tabs within a page)
+ *
+ * URL Pattern: #/p/{projectId}/custom/{groupId}/{pageId}?/{tabPath}?
  *
  * @module custom-pages/types
  */

package/dist/joy-config.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Base configuration interface for Joy admin UI.
+ * Extensible via index signature - consumers can add custom fields.
+ *
+ * @example
+ * ```ts
+ * // Extend with custom fields
+ * interface MyJoyConfig extends JoyConfig {
+ *   myCustomField: string;
+ *   stuic: {
+ *     DismissibleMessage: {
+ *       theme: "red" | "blue"; // Stricter typing
+ *     };
+ *   };
+ * }
+ * ```
+ */
+export interface JoyConfig {
+    /** Project/app title */
+    title?: string;
+    /** Stuic component configuration overrides */
+    stuic?: {
+        DismissibleMessage?: {
+            /** Theme color for dismissible messages */
+            theme?: string;
+        };
+        [component: string]: Record<string, unknown> | undefined;
+    };
+    /** Index signature for custom extensions */
+    [key: string]: unknown;
+}

package/dist/joy-config.js

@@ -0,0 +1 @@
+export {};

package/dist/mod.d.ts

@@ -50,3 +50,4 @@ export * from "./schema-builder.js";
 export * from "./navigation.js";
 export * from "./form-routes.js";
 export * from "./custom-pages.js";
+export * from "./joy-config.js";

package/dist/mod.js

@@ -69,3 +69,5 @@ export * from "./navigation.js";
 export * from "./form-routes.js";
 // Custom Pages Configuration Types (admin UI)
 export * from "./custom-pages.js";
+// Joy Config Types (admin UI)
+export * from "./joy-config.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/collection-types",
-	"version": "1.19.0",
+	"version": "1.21.0",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",