@zenithbuild/plugins 0.3.2

package/content/hooks/useZenOrder.ts

@@ -0,0 +1,292 @@
+/**
+ * useZenOrder Hook
+ * 
+ * A plugin-provided hook for organizing and navigating documentation.
+ * Provides dynamic folder ordering, slug generation, and navigation helpers.
+ * 
+ * Features:
+ * - Dynamic folder ordering (meta.order → intro tag → alphabetical)
+ * - Slug generation for sections and docs
+ * - State management for selected section/doc
+ * - Navigation helpers (next/prev) with cross-section support
+ */
+
+import type { ContentItem } from '../types';
+
+export interface DocItem extends ContentItem {
+    slug: string;
+    sectionSlug: string;
+    isIntro?: boolean;
+}
+
+export interface Section {
+    id: string;
+    title: string;
+    slug: string;
+    order?: number;
+    hasIntro: boolean;
+    items: DocItem[];
+}
+
+export interface ZenOrderState {
+    sections: Section[];
+    selectedSection: Section | null;
+    selectedDoc: DocItem | null;
+}
+
+export interface ZenOrderActions {
+    selectSection: (section: Section) => void;
+    selectDoc: (doc: DocItem) => void;
+    getNextDoc: (currentDoc: DocItem) => DocItem | null;
+    getPrevDoc: (currentDoc: DocItem) => DocItem | null;
+    getDocBySlug: (sectionSlug: string, docSlug: string) => DocItem | null;
+    getSectionBySlug: (sectionSlug: string) => Section | null;
+}
+
+export type ZenOrderReturn = ZenOrderState & ZenOrderActions;
+
+/**
+ * Generate a URL-safe slug from a string
+ */
+function slugify(text: string): string {
+    return text
+        .toLowerCase()
+        .replace(/[^\w\s-]/g, '') // Remove special characters
+        .replace(/\s+/g, '-')     // Replace spaces with hyphens
+        .replace(/-+/g, '-')      // Replace multiple hyphens with single
+        .trim();
+}
+
+/**
+ * Extract slug from file path or title
+ */
+function getDocSlug(doc: ContentItem): string {
+    // Try to use the filename from the slug/id
+    const slugOrId = String(doc.slug || doc.id || '');
+    const parts = slugOrId.split('/');
+    const filename = parts[parts.length - 1];
+
+    // If filename exists and isn't empty, use it
+    if (filename && filename.length > 0) {
+        return slugify(filename);
+    }
+
+    // Fallback to title
+    return slugify(doc.title || 'untitled');
+}
+
+/**
+ * Sort sections dynamically based on:
+ * 1. meta.order (absolute priority if defined)
+ * 2. Presence of intro doc (soft priority)
+ * 3. Alphabetical fallback
+ */
+function sortSections(sections: Section[]): Section[] {
+    return [...sections].sort((a, b) => {
+        // 1. Order priority (lower is first)
+        if (a.order !== undefined && b.order !== undefined) {
+            return a.order - b.order;
+        }
+        if (a.order !== undefined) return -1;
+        if (b.order !== undefined) return 1;
+
+        // 2. Intro priority (sections with intro come first)
+        if (a.hasIntro && !b.hasIntro) return -1;
+        if (!a.hasIntro && b.hasIntro) return 1;
+
+        // 3. Alphabetical fallback
+        return a.title.localeCompare(b.title);
+    });
+}
+
+/**
+ * Sort docs within a section
+ * - Intro docs come first
+ * - Then by order if defined
+ * - Then alphabetical
+ */
+function sortDocs(docs: DocItem[]): DocItem[] {
+    return [...docs].sort((a, b) => {
+        // Intro docs first
+        if (a.isIntro && !b.isIntro) return -1;
+        if (!a.isIntro && b.isIntro) return 1;
+
+        // Order priority
+        const orderA = (a as any).order;
+        const orderB = (b as any).order;
+        if (orderA !== undefined && orderB !== undefined) {
+            return orderA - orderB;
+        }
+        if (orderA !== undefined) return -1;
+        if (orderB !== undefined) return 1;
+
+        // Alphabetical
+        return (a.title || '').localeCompare(b.title || '');
+    });
+}
+
+/**
+ * Process raw sections from zenCollection into structured sections with slugs
+ */
+export function processRawSections(rawSections: any[]): Section[] {
+    const sections: Section[] = rawSections.map(rawSection => {
+        const sectionSlug = slugify(rawSection.title || rawSection.id || 'section');
+
+        // Process items with slugs and section reference
+        const items: DocItem[] = (rawSection.items || []).map((item: ContentItem) => ({
+            ...item,
+            slug: getDocSlug(item),
+            sectionSlug,
+            isIntro: (item as any).intro === true || (item as any).tags?.includes('intro')
+        }));
+
+        // Sort items within section
+        const sortedItems = sortDocs(items);
+
+        // Check if section has intro doc
+        const hasIntro = sortedItems.some(item => item.isIntro);
+
+        // Get section order from first item's folder meta or undefined
+        const order = (rawSection as any).order ?? (rawSection as any).meta?.order;
+
+        return {
+            id: rawSection.id || sectionSlug,
+            title: rawSection.title || 'Untitled Section',
+            slug: sectionSlug,
+            order,
+            hasIntro,
+            items: sortedItems
+        };
+    });
+
+    return sortSections(sections);
+}
+
+/**
+ * Create the useZenOrder hook
+ * 
+ * This function creates the hook state and actions.
+ * In the Zenith runtime, this would be called during component initialization.
+ */
+export function createZenOrder(rawSections: any[]): ZenOrderReturn {
+    // Process and sort sections
+    const sections = processRawSections(rawSections);
+
+    // Initialize state
+    let state: ZenOrderState = {
+        sections,
+        selectedSection: sections[0] || null,
+        selectedDoc: sections[0]?.items[0] || null
+    };
+
+    // Actions
+    const selectSection = (section: Section): void => {
+        state.selectedSection = section;
+        state.selectedDoc = section.items[0] || null;
+    };
+
+    const selectDoc = (doc: DocItem): void => {
+        state.selectedDoc = doc;
+        // Also update selected section if doc is from a different section
+        const docSection = sections.find(s => s.slug === doc.sectionSlug);
+        if (docSection && state.selectedSection?.slug !== doc.sectionSlug) {
+            state.selectedSection = docSection;
+        }
+    };
+
+    const getSectionBySlug = (sectionSlug: string): Section | null => {
+        return sections.find(s => s.slug === sectionSlug) || null;
+    };
+
+    const getDocBySlug = (sectionSlug: string, docSlug: string): DocItem | null => {
+        const section = getSectionBySlug(sectionSlug);
+        if (!section) return null;
+        return section.items.find(d => d.slug === docSlug) || null;
+    };
+
+    const getNextDoc = (currentDoc: DocItem): DocItem | null => {
+        const currentSection = sections.find(s => s.slug === currentDoc.sectionSlug);
+        if (!currentSection) return null;
+
+        const currentIndex = currentSection.items.findIndex(d => d.slug === currentDoc.slug);
+
+        // Try next doc in same section
+        if (currentIndex < currentSection.items.length - 1) {
+            return currentSection.items[currentIndex + 1];
+        }
+
+        // Try first doc of next section
+        const sectionIndex = sections.findIndex(s => s.slug === currentSection.slug);
+        if (sectionIndex < sections.length - 1) {
+            const nextSection = sections[sectionIndex + 1];
+            return nextSection.items[0] || null;
+        }
+
+        return null;
+    };
+
+    const getPrevDoc = (currentDoc: DocItem): DocItem | null => {
+        const currentSection = sections.find(s => s.slug === currentDoc.sectionSlug);
+        if (!currentSection) return null;
+
+        const currentIndex = currentSection.items.findIndex(d => d.slug === currentDoc.slug);
+
+        // Try previous doc in same section
+        if (currentIndex > 0) {
+            return currentSection.items[currentIndex - 1];
+        }
+
+        // Try last doc of previous section
+        const sectionIndex = sections.findIndex(s => s.slug === currentSection.slug);
+        if (sectionIndex > 0) {
+            const prevSection = sections[sectionIndex - 1];
+            return prevSection.items[prevSection.items.length - 1] || null;
+        }
+
+        return null;
+    };
+
+    return {
+        ...state,
+        sections,
+        selectSection,
+        selectDoc,
+        getNextDoc,
+        getPrevDoc,
+        getDocBySlug,
+        getSectionBySlug
+    };
+}
+
+/**
+ * Build a documentation URL from section and doc slugs
+ */
+export function buildDocUrl(sectionSlug: string, docSlug?: string): string {
+    if (!docSlug || docSlug === 'index') {
+        return `/documentation/${sectionSlug}`;
+    }
+    return `/documentation/${sectionSlug}/${docSlug}`;
+}
+
+/**
+ * Parse slugs from a URL path
+ */
+export function parseDocUrl(path: string): { sectionSlug: string | null; docSlug: string | null } {
+    const match = path.match(/^\/documentation\/([^/]+)(?:\/([^/]+))?$/);
+    if (!match) {
+        return { sectionSlug: null, docSlug: null };
+    }
+    return {
+        sectionSlug: match[1] || null,
+        docSlug: match[2] || null
+    };
+}
+
+// Default export for easy importing
+export default {
+    createZenOrder,
+    processRawSections,
+    buildDocUrl,
+    parseDocUrl,
+    slugify
+};

package/content/index.ts

@@ -0,0 +1,209 @@
+/**
+ * Zenith Content Plugin
+ * 
+ * A data provider plugin for loading content from markdown and JSON files.
+ * 
+ * Usage in zenith.config.ts:
+ * ```typescript
+ * import { defineConfig } from 'zenith/config';
+ * import content from 'zenith-content';
+ * 
+ * export default defineConfig({
+ *   plugins: [
+ *     content({
+ *       sources: {
+ *         docs: {
+ *           root: '../zenith-docs',
+ *           include: ['documentation']
+ *         }
+ *       }
+ *     })
+ *   ]
+ * });
+ * ```
+ */
+
+import type { ContentItem, ContentPluginOptions, ContentSourceConfig } from "./types";
+import { loadContent, loadFromSources } from "./loader";
+import { ZenCollection } from "./query";
+import { defineSchema } from "./schema";
+import path from "node:path";
+
+// Re-exports for convenience
+export { defineSchema } from "./schema";
+export { ZenCollection } from "./query";
+export type { ContentItem, ContentPluginOptions, ContentSourceConfig } from "./types";
+
+// Export useZenOrder hook and utilities
+export {
+  createZenOrder,
+  processRawSections,
+  buildDocUrl,
+  parseDocUrl
+} from "./hooks/useZenOrder";
+export type {
+  DocItem,
+  Section,
+  ZenOrderState,
+  ZenOrderActions,
+  ZenOrderReturn
+} from "./hooks/useZenOrder";
+
+// Store for loaded content (used by legacy zenQuery)
+let allContent: ContentItem[] = [];
+
+/**
+ * Legacy query function - use zenCollection in templates instead
+ */
+export const zenQuery = (collection: string) => {
+  const items = allContent.filter(item => item.collection === collection);
+  return new ZenCollection(items);
+};
+
+/**
+ * Plugin interface expected by core
+ */
+export interface ZenithPlugin {
+  name: string;
+  setup: (ctx: PluginContext) => void | Promise<void>;
+  config?: unknown;
+  registerCLI?: (api: CLIBridgeAPI) => void;
+}
+
+/**
+ * Context provided to plugins during setup (matches core generic signature)
+ */
+export interface PluginContext {
+  projectRoot: string;
+  setPluginData: (namespace: string, data: unknown[]) => void;
+  options?: Record<string, unknown>;
+}
+
+/**
+ * CLI Bridge API for hook registration
+ * Matches core's CLIBridgeAPI interface
+ */
+export interface CLIBridgeAPI {
+  on(hook: string, handler: (ctx: HookContext) => unknown | void): void;
+}
+
+/**
+ * Hook context passed to CLI hooks
+ */
+export interface HookContext {
+  projectRoot: string;
+  getPluginData: (namespace: string) => unknown;
+  [key: string]: unknown;
+}
+
+/**
+ * Content plugin factory function
+ * 
+ * @param options - Plugin configuration with sources
+ * @returns A ZenithPlugin that loads content from configured sources
+ */
+export default function content(options: ContentPluginOptions = {}): ZenithPlugin {
+  return {
+    name: 'zenith-content',
+    config: options,
+    setup(ctx: PluginContext) {
+      let collections: Record<string, ContentItem[]> = {};
+
+      if (options.sources && Object.keys(options.sources).length > 0) {
+        // Use new sources configuration
+        collections = loadFromSources(options.sources, ctx.projectRoot);
+      } else if (options.contentDir) {
+        // Legacy: single content directory
+        const contentPath = path.resolve(ctx.projectRoot, options.contentDir);
+        const items = loadContent(contentPath);
+
+        // Group by collection
+        for (const item of items) {
+          const collection = item.collection || 'default';
+          if (!collections[collection]) {
+            collections[collection] = [];
+          }
+          collections[collection].push(item);
+        }
+
+        console.log(`[zenith:content] Loaded ${items.length} items from ${options.contentDir}`);
+      }
+
+      // Pass to runtime using generic namespaced data store
+      const allItems = Object.values(collections).flat();
+      ctx.setPluginData('content', allItems);
+
+      // Update legacy storage
+      allContent = allItems;
+    },
+
+    /**
+     * CLI Registration - Plugin owns its CLI behavior
+     * 
+     * Registers namespaced hooks for CLI lifecycle events.
+     * The CLI never calls plugin logic directly - it dispatches hooks.
+     */
+    registerCLI(api: CLIBridgeAPI) {
+      // Register for runtime data collection
+      // CLI collects payloads and serializes to window.__ZENITH_PLUGIN_DATA__
+      api.on('cli:runtime:collect', (ctx: HookContext) => {
+        const data = ctx.getPluginData('content');
+        if (!data) return;
+
+        return {
+          namespace: 'content',
+          payload: data
+        };
+      });
+
+      // Register for file change events (plugin decides what to do)
+      api.on('cli:dev:file-change', (ctx: HookContext) => {
+        const filename = ctx.filename as string | undefined;
+        if (!filename) return;
+
+        // Plugin owns knowledge of what files it cares about
+        if (filename.startsWith('content') || filename.endsWith('.md') || filename.endsWith('.mdx')) {
+          // Signal that content should be reloaded
+          // The actual reload happens via plugin re-initialization
+          console.log('[zenith:content] Content file changed:', filename);
+        }
+      });
+    }
+  };
+}
+
+/**
+ * Legacy plugin export for backward compatibility
+ * @deprecated Use the default export factory function instead
+ */
+export const plugin: ZenithPlugin = {
+  name: "zenith-content",
+  setup(ctx: PluginContext) {
+    const contentDir = path.resolve(ctx.projectRoot, "content");
+    const items = loadContent(contentDir);
+
+    // Group by collection
+    const collections: Record<string, ContentItem[]> = {};
+    for (const item of items) {
+      const collection = item.collection || 'default';
+      if (!collections[collection]) {
+        collections[collection] = [];
+      }
+      collections[collection].push(item);
+    }
+
+    allContent = items;
+    ctx.setPluginData('content', items);
+
+    console.log(`[zenith:content] Loaded ${items.length} items from ${contentDir}`);
+  },
+
+  registerCLI(api: CLIBridgeAPI) {
+    api.on('cli:runtime:collect', (ctx: HookContext) => {
+      const data = ctx.getPluginData('content');
+      if (!data) return;
+      return { namespace: 'content', payload: data };
+    });
+  }
+};
+

package/content/loader.ts

@@ -0,0 +1,165 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import type { ContentItem, ContentSourceConfig } from './types';
+import { compileMarkdown, vnodesToHtml } from './markdown';
+
+export function loadContent(contentDir: string): ContentItem[] {
+    if (!fs.existsSync(contentDir)) {
+        console.warn(`Content directory ${contentDir} does not exist.`);
+        return [];
+    }
+
+    const items: ContentItem[] = [];
+    const files = getAllFiles(contentDir);
+
+    for (const filePath of files) {
+        const ext = path.extname(filePath).toLowerCase();
+        const relativePath = path.relative(contentDir, filePath);
+        const collection = relativePath.split(path.sep)[0];
+        // Ensure slug is forward-slash based and has no leading/trailing slashes
+        const slug = relativePath
+            .replace(/\.(md|mdx|json)$/, '')
+            .split(path.sep)
+            .join('/')
+            .replace(/^\//, '');
+        const id = slug;
+
+        const rawContent = fs.readFileSync(filePath, 'utf-8');
+
+        if (ext === '.json') {
+            try {
+                const data = JSON.parse(rawContent);
+                items.push({
+                    id,
+                    slug,
+                    collection,
+                    content: '',
+                    ...data
+                });
+            } catch (e) {
+                console.error(`Error parsing JSON file ${filePath}:`, e);
+            }
+        } else if (ext === '.md' || ext === '.mdx') {
+            const { metadata, content: markdownBody } = parseMarkdown(rawContent);
+            // Compile markdown to VNodes then to HTML for rendering
+            const vnodes = compileMarkdown(markdownBody);
+            const compiledContent = vnodesToHtml(vnodes);
+            items.push({
+                id,
+                slug,
+                collection,
+                content: compiledContent,
+                ...metadata
+            });
+        }
+    }
+
+    return items;
+}
+
+/**
+ * Load content from configured sources
+ * Supports include/exclude filtering for folder selection
+ */
+export function loadFromSources(
+    sources: Record<string, ContentSourceConfig>,
+    projectRoot: string
+): Record<string, ContentItem[]> {
+    const collections: Record<string, ContentItem[]> = {};
+
+    for (const [collectionName, config] of Object.entries(sources)) {
+        const rootPath = path.resolve(projectRoot, config.root);
+
+        if (!fs.existsSync(rootPath)) {
+            console.warn(`[zenith:content] Source root "${rootPath}" does not exist for collection "${collectionName}"`);
+            continue;
+        }
+
+        // Get folders to scan
+        let foldersToScan: string[] = [];
+
+        if (config.include && config.include.length > 0) {
+            // Explicit include list
+            foldersToScan = config.include;
+        } else {
+            // Scan all subdirectories if no include specified
+            try {
+                foldersToScan = fs.readdirSync(rootPath)
+                    .filter(f => fs.statSync(path.join(rootPath, f)).isDirectory());
+            } catch {
+                // If root is itself the content folder
+                foldersToScan = ['.'];
+            }
+        }
+
+        // Apply excludes
+        const exclude = config.exclude || [];
+        foldersToScan = foldersToScan.filter(f => !exclude.includes(f));
+
+        // Load content from each folder
+        const items: ContentItem[] = [];
+        for (const folder of foldersToScan) {
+            const folderPath = folder === '.' ? rootPath : path.join(rootPath, folder);
+
+            if (!fs.existsSync(folderPath)) {
+                console.warn(`[zenith:content] Folder "${folderPath}" does not exist, skipping`);
+                continue;
+            }
+
+            const folderItems = loadContent(folderPath);
+
+            // Override collection name to match the configured name
+            items.push(...folderItems.map(item => ({
+                ...item,
+                collection: collectionName
+            })));
+        }
+
+        collections[collectionName] = items;
+        console.log(`[zenith:content] Loaded ${items.length} items for collection "${collectionName}"`);
+    }
+
+    return collections;
+}
+
+function getAllFiles(dir: string, fileList: string[] = []): string[] {
+    const files = fs.readdirSync(dir);
+    files.forEach((file: string) => {
+        const name = path.join(dir, file);
+        if (fs.statSync(name).isDirectory()) {
+            getAllFiles(name, fileList);
+        } else {
+            fileList.push(name);
+        }
+    });
+    return fileList;
+}
+
+function parseMarkdown(content: string): { metadata: Record<string, any>, content: string } {
+    const frontmatterRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+    const match = content.match(frontmatterRegex);
+
+    if (!match) {
+        return { metadata: {}, content: content.trim() };
+    }
+
+    const [, yamlStr, body] = match;
+    const metadata: Record<string, any> = {};
+
+    yamlStr.split('\n').forEach(line => {
+        const [key, ...values] = line.split(':');
+        if (key && values.length > 0) {
+            const value = values.join(':').trim();
+            // Basic type conversion
+            if (value === 'true') metadata[key.trim()] = true;
+            else if (value === 'false') metadata[key.trim()] = false;
+            else if (!isNaN(Number(value))) metadata[key.trim()] = Number(value);
+            else if (value.startsWith('[') && value.endsWith(']')) {
+                metadata[key.trim()] = value.slice(1, -1).split(',').map(v => v.trim().replace(/^['"]|['"]$/g, ''));
+            }
+            else metadata[key.trim()] = value.replace(/^['"]|['"]$/g, '');
+        }
+    });
+
+    return { metadata, content: body.trim() };
+}