@consilioweb/admin-nav 0.4.3

package/dist/index.d.cts

@@ -0,0 +1,164 @@
+import { Plugin, Config, CollectionConfig, PayloadHandler } from 'payload';
+
+/** Localizable string — plain string or per-language record */
+type LocalizedString = string | Record<string, string>;
+/** A single navigation item */
+interface NavItemConfig {
+    /** Unique item ID (e.g. 'pages', 'posts', 'seo-dashboard') */
+    id: string;
+    /** Admin URL path (e.g. '/admin/collections/pages') */
+    href: string;
+    /** Display label (string or { fr: '...', en: '...' }) */
+    label: LocalizedString;
+    /** Icon name from the built-in icon registry */
+    icon: string;
+    /** If true, pathname.startsWith(href) activates the item */
+    matchPrefix?: boolean;
+    /** Nested child items (e.g. ticket status filters) */
+    children?: NavItemConfig[];
+    /** Whether this item is visible (default: true) */
+    visible?: boolean;
+}
+/** A navigation group (section with a title) */
+interface NavGroupConfig {
+    /** Unique group ID */
+    id: string;
+    /** Group title displayed as section header (string or { fr: '...', en: '...' }) */
+    title: LocalizedString;
+    /** Items in this group */
+    items: NavItemConfig[];
+    /** Whether this group is visible (default: true) */
+    visible?: boolean;
+    /** Whether this group starts collapsed (default: false) */
+    defaultCollapsed?: boolean;
+}
+/** Full navigation layout stored per-user in the database */
+interface NavLayout {
+    /** Ordered list of navigation groups */
+    groups: NavGroupConfig[];
+    /** Schema version for future migrations */
+    version: number;
+}
+/** Plugin configuration options */
+interface AdminNavPluginConfig {
+    /**
+     * Default navigation layout — the initial sidebar structure.
+     * If not provided, the plugin auto-discovers collections, globals, and views
+     * from the Payload config and generates a navigation layout automatically.
+     */
+    defaultNav?: NavGroupConfig[];
+    /** Components to render after the nav (e.g. NotificationCenter paths) */
+    afterNav?: string[];
+    /** Collection slug for preferences storage (default: 'admin-nav-preferences') */
+    collectionSlug?: string;
+    /** User collection slug to create the relationship (default: 'users') */
+    userCollectionSlug?: string;
+    /** Base path for API endpoints (default: '/admin-nav') */
+    endpointBasePath?: string;
+    /** Whether to add the /admin/nav-customizer view (default: true) */
+    addCustomizerView?: boolean;
+    /**
+     * Override the AdminNav component path for beforeNavLinks.
+     * Use this when the package is installed via file: or link: protocol
+     * to avoid webpack RSC resolution issues. Point to a local wrapper
+     * that re-exports AdminNav from the package.
+     * Example: '@/components/admin/AdminNavWrapper#AdminNav'
+     * Default: '@consilioweb/admin-nav/client#AdminNav'
+     */
+    navComponentPath?: string;
+}
+
+/**
+ * Payload CMS Admin Nav Plugin.
+ *
+ * Adds a fully customizable sidebar navigation to the Payload admin UI:
+ * - Per-user navigation preferences stored in the database
+ * - Drag & drop reordering (groups + items) via @dnd-kit
+ * - Show/hide items, create custom groups, edit labels/icons
+ * - API endpoints for preferences CRUD
+ * - Admin view at /admin/nav-customizer
+ * - i18n support (FR/EN, extensible)
+ * - Auto-discovery: generates nav from collections/globals/views if no defaultNav
+ *
+ * Usage:
+ *   import { adminNavPlugin } from '@consilioweb/admin-nav'
+ *
+ *   // Minimal — auto-discovers nav from Payload config
+ *   export default buildConfig({
+ *     plugins: [adminNavPlugin()],
+ *   })
+ *
+ *   // Custom — provide your own nav layout
+ *   export default buildConfig({
+ *     plugins: [
+ *       adminNavPlugin({
+ *         defaultNav: [
+ *           { id: 'content', title: 'Content', items: [...] },
+ *         ],
+ *       }),
+ *     ],
+ *   })
+ */
+
+declare const adminNavPlugin: (pluginConfig?: AdminNavPluginConfig) => Plugin;
+
+/**
+ * Auto-discover navigation structure from Payload config.
+ *
+ * When no `defaultNav` is provided, the plugin reads collections, globals,
+ * and custom admin views from the Payload config and generates a reasonable
+ * navigation layout automatically.
+ */
+
+/**
+ * Auto-discover navigation groups from a Payload config.
+ *
+ * Groups collections by their `admin.group` property.
+ * Creates items for globals and custom admin views.
+ * Assigns icons based on slug matching.
+ */
+declare function autoDiscoverNav(config: Config): NavGroupConfig[];
+
+/**
+ * Creates the AdminNavPreferences collection.
+ * Stores per-user navigation layout customizations.
+ */
+declare function createAdminNavPreferencesCollection(slug?: string, userCollectionSlug?: string): CollectionConfig;
+
+/**
+ * GET handler — retrieve current user's nav preferences.
+ * Returns the navLayout or null if no custom layout is saved.
+ */
+declare function createGetPreferencesHandler(collectionSlug: string): PayloadHandler;
+/**
+ * PATCH handler — save/update current user's nav preferences.
+ * Expects JSON body: { navLayout: NavLayout }
+ */
+declare function createSavePreferencesHandler(collectionSlug: string): PayloadHandler;
+/**
+ * DELETE handler — reset current user's nav preferences (back to default).
+ */
+declare function createResetPreferencesHandler(collectionSlug: string): PayloadHandler;
+
+/**
+ * Built-in SVG icon registry.
+ * Inline SVG paths — no external dependency (Lucide-compatible viewBox 0 0 24 24).
+ * Each icon is a <path d="..."/> string for a 24x24 viewBox.
+ */
+declare const iconPaths: Record<string, string>;
+/** Get all available icon names */
+declare function getIconNames(): string[];
+/** Get the SVG path data for a given icon name */
+declare function getIconPath(name: string): string | undefined;
+
+/**
+ * Check if a label is a multi-language record.
+ */
+declare function isMultiLang(label: string | Record<string, string>): label is Record<string, string>;
+/**
+ * Resolve a potentially multi-language label to a string.
+ * Falls back to: lang → fallback → first available value → empty string.
+ */
+declare function resolveLabel(label: string | Record<string, string>, lang: string, fallback?: string): string;
+
+export { type AdminNavPluginConfig, type LocalizedString, type NavGroupConfig, type NavItemConfig, type NavLayout, adminNavPlugin, autoDiscoverNav, createAdminNavPreferencesCollection, createGetPreferencesHandler, createResetPreferencesHandler, createSavePreferencesHandler, getIconNames, getIconPath, iconPaths, isMultiLang, resolveLabel };

package/dist/index.d.ts

@@ -0,0 +1,164 @@
+import { Plugin, Config, CollectionConfig, PayloadHandler } from 'payload';
+
+/** Localizable string — plain string or per-language record */
+type LocalizedString = string | Record<string, string>;
+/** A single navigation item */
+interface NavItemConfig {
+    /** Unique item ID (e.g. 'pages', 'posts', 'seo-dashboard') */
+    id: string;
+    /** Admin URL path (e.g. '/admin/collections/pages') */
+    href: string;
+    /** Display label (string or { fr: '...', en: '...' }) */
+    label: LocalizedString;
+    /** Icon name from the built-in icon registry */
+    icon: string;
+    /** If true, pathname.startsWith(href) activates the item */
+    matchPrefix?: boolean;
+    /** Nested child items (e.g. ticket status filters) */
+    children?: NavItemConfig[];
+    /** Whether this item is visible (default: true) */
+    visible?: boolean;
+}
+/** A navigation group (section with a title) */
+interface NavGroupConfig {
+    /** Unique group ID */
+    id: string;
+    /** Group title displayed as section header (string or { fr: '...', en: '...' }) */
+    title: LocalizedString;
+    /** Items in this group */
+    items: NavItemConfig[];
+    /** Whether this group is visible (default: true) */
+    visible?: boolean;
+    /** Whether this group starts collapsed (default: false) */
+    defaultCollapsed?: boolean;
+}
+/** Full navigation layout stored per-user in the database */
+interface NavLayout {
+    /** Ordered list of navigation groups */
+    groups: NavGroupConfig[];
+    /** Schema version for future migrations */
+    version: number;
+}
+/** Plugin configuration options */
+interface AdminNavPluginConfig {
+    /**
+     * Default navigation layout — the initial sidebar structure.
+     * If not provided, the plugin auto-discovers collections, globals, and views
+     * from the Payload config and generates a navigation layout automatically.
+     */
+    defaultNav?: NavGroupConfig[];
+    /** Components to render after the nav (e.g. NotificationCenter paths) */
+    afterNav?: string[];
+    /** Collection slug for preferences storage (default: 'admin-nav-preferences') */
+    collectionSlug?: string;
+    /** User collection slug to create the relationship (default: 'users') */
+    userCollectionSlug?: string;
+    /** Base path for API endpoints (default: '/admin-nav') */
+    endpointBasePath?: string;
+    /** Whether to add the /admin/nav-customizer view (default: true) */
+    addCustomizerView?: boolean;
+    /**
+     * Override the AdminNav component path for beforeNavLinks.
+     * Use this when the package is installed via file: or link: protocol
+     * to avoid webpack RSC resolution issues. Point to a local wrapper
+     * that re-exports AdminNav from the package.
+     * Example: '@/components/admin/AdminNavWrapper#AdminNav'
+     * Default: '@consilioweb/admin-nav/client#AdminNav'
+     */
+    navComponentPath?: string;
+}
+
+/**
+ * Payload CMS Admin Nav Plugin.
+ *
+ * Adds a fully customizable sidebar navigation to the Payload admin UI:
+ * - Per-user navigation preferences stored in the database
+ * - Drag & drop reordering (groups + items) via @dnd-kit
+ * - Show/hide items, create custom groups, edit labels/icons
+ * - API endpoints for preferences CRUD
+ * - Admin view at /admin/nav-customizer
+ * - i18n support (FR/EN, extensible)
+ * - Auto-discovery: generates nav from collections/globals/views if no defaultNav
+ *
+ * Usage:
+ *   import { adminNavPlugin } from '@consilioweb/admin-nav'
+ *
+ *   // Minimal — auto-discovers nav from Payload config
+ *   export default buildConfig({
+ *     plugins: [adminNavPlugin()],
+ *   })
+ *
+ *   // Custom — provide your own nav layout
+ *   export default buildConfig({
+ *     plugins: [
+ *       adminNavPlugin({
+ *         defaultNav: [
+ *           { id: 'content', title: 'Content', items: [...] },
+ *         ],
+ *       }),
+ *     ],
+ *   })
+ */
+
+declare const adminNavPlugin: (pluginConfig?: AdminNavPluginConfig) => Plugin;
+
+/**
+ * Auto-discover navigation structure from Payload config.
+ *
+ * When no `defaultNav` is provided, the plugin reads collections, globals,
+ * and custom admin views from the Payload config and generates a reasonable
+ * navigation layout automatically.
+ */
+
+/**
+ * Auto-discover navigation groups from a Payload config.
+ *
+ * Groups collections by their `admin.group` property.
+ * Creates items for globals and custom admin views.
+ * Assigns icons based on slug matching.
+ */
+declare function autoDiscoverNav(config: Config): NavGroupConfig[];
+
+/**
+ * Creates the AdminNavPreferences collection.
+ * Stores per-user navigation layout customizations.
+ */
+declare function createAdminNavPreferencesCollection(slug?: string, userCollectionSlug?: string): CollectionConfig;
+
+/**
+ * GET handler — retrieve current user's nav preferences.
+ * Returns the navLayout or null if no custom layout is saved.
+ */
+declare function createGetPreferencesHandler(collectionSlug: string): PayloadHandler;
+/**
+ * PATCH handler — save/update current user's nav preferences.
+ * Expects JSON body: { navLayout: NavLayout }
+ */
+declare function createSavePreferencesHandler(collectionSlug: string): PayloadHandler;
+/**
+ * DELETE handler — reset current user's nav preferences (back to default).
+ */
+declare function createResetPreferencesHandler(collectionSlug: string): PayloadHandler;
+
+/**
+ * Built-in SVG icon registry.
+ * Inline SVG paths — no external dependency (Lucide-compatible viewBox 0 0 24 24).
+ * Each icon is a <path d="..."/> string for a 24x24 viewBox.
+ */
+declare const iconPaths: Record<string, string>;
+/** Get all available icon names */
+declare function getIconNames(): string[];
+/** Get the SVG path data for a given icon name */
+declare function getIconPath(name: string): string | undefined;
+
+/**
+ * Check if a label is a multi-language record.
+ */
+declare function isMultiLang(label: string | Record<string, string>): label is Record<string, string>;
+/**
+ * Resolve a potentially multi-language label to a string.
+ * Falls back to: lang → fallback → first available value → empty string.
+ */
+declare function resolveLabel(label: string | Record<string, string>, lang: string, fallback?: string): string;
+
+export { type AdminNavPluginConfig, type LocalizedString, type NavGroupConfig, type NavItemConfig, type NavLayout, adminNavPlugin, autoDiscoverNav, createAdminNavPreferencesCollection, createGetPreferencesHandler, createResetPreferencesHandler, createSavePreferencesHandler, getIconNames, getIconPath, iconPaths, isMultiLang, resolveLabel };