specra 0.1.13 → 0.2.0

package/dist/sidebar-utils.js

@@ -0,0 +1,144 @@
+/**
+ * Unified sidebar sorting and structure building utilities
+ * This module provides consistent sidebar logic across the application
+ * to ensure ordering is handled the same way everywhere.
+ */
+/**
+ * Sort sidebar items by their position.
+ * Items with explicit sidebar_position come first (sorted numerically),
+ * followed by items without position (sorted by their original order).
+ *
+ * @param items - Array of items with optional sidebar_position
+ * @returns Sorted array of items
+ */
+export function sortSidebarItems(items) {
+    return [...items].sort((a, b) => {
+        const posA = a.sidebar_position ?? a.meta?.sidebar_position ?? a.meta?.order ?? 999;
+        const posB = b.sidebar_position ?? b.meta?.sidebar_position ?? b.meta?.order ?? 999;
+        return posA - posB;
+    });
+}
+/**
+ * Sort sidebar groups by their position.
+ * Groups with explicit position come first (sorted numerically),
+ * followed by groups without position at the end (sorted by their original order).
+ *
+ * @param groups - Record of group key to group object with position
+ * @returns Sorted array of [key, group] tuples
+ */
+export function sortSidebarGroups(groups) {
+    return Object.entries(groups).sort(([, a], [, b]) => {
+        const posA = a.position ?? 999;
+        const posB = b.position ?? 999;
+        return posA - posB;
+    });
+}
+/**
+ * Build hierarchical sidebar structure from flat list of documents
+ * This is the single source of truth for sidebar structure used by both
+ * the sidebar component and navigation (prev/next) links.
+ *
+ * @param docs - Array of documents with metadata
+ * @returns Object containing root groups and standalone items
+ */
+export function buildSidebarStructure(docs) {
+    const rootGroups = {};
+    const standalone = [];
+    // First pass: collect category metadata from all docs to build complete folder structure
+    const categoryMetadata = new Map();
+    docs.forEach((doc) => {
+        const pathParts = doc.filePath.split("/");
+        const folderPath = pathParts.length > 1 ? pathParts.slice(0, -1).join("/") : "";
+        if (folderPath && doc.categoryLabel) {
+            categoryMetadata.set(folderPath, {
+                label: doc.categoryLabel,
+                position: doc.categoryPosition,
+                icon: doc.categoryIcon,
+                collapsible: doc.categoryCollapsible,
+                collapsed: doc.categoryCollapsed
+            });
+        }
+    });
+    docs.forEach((doc) => {
+        const pathParts = doc.filePath.split("/");
+        const isIndexFile = doc.filePath.endsWith("/index") ||
+            doc.filePath === "index" ||
+            (pathParts.length > 1 && doc.slug === pathParts.slice(0, -1).join("/"));
+        const customGroup = doc.meta.sidebar || doc.meta.group;
+        if (customGroup) {
+            const groupName = customGroup.charAt(0).toUpperCase() + customGroup.slice(1);
+            if (!rootGroups[groupName]) {
+                rootGroups[groupName] = {
+                    label: groupName,
+                    path: customGroup,
+                    items: [],
+                    position: 999,
+                    collapsible: doc.categoryCollapsible ?? true,
+                    defaultCollapsed: doc.categoryCollapsed ?? false,
+                    children: {}
+                };
+            }
+            if (isIndexFile) {
+                // Use categoryPosition if available (from _category_.json), otherwise sidebar_position from frontmatter
+                rootGroups[groupName].position = doc.categoryPosition ?? doc.meta.sidebar_position ?? 999;
+                rootGroups[groupName].icon = doc.categoryIcon;
+            }
+            else {
+                rootGroups[groupName].items.push(doc);
+            }
+            return;
+        }
+        if (pathParts.length > 1) {
+            const folderParts = pathParts.slice(0, -1);
+            let currentLevel = rootGroups;
+            let currentPath = "";
+            for (let i = 0; i < folderParts.length; i++) {
+                const folder = folderParts[i];
+                currentPath = currentPath ? `${currentPath}/${folder}` : folder;
+                const folderLabel = folder.split("-").map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+                // Get metadata for this specific folder path
+                const metadata = categoryMetadata.get(currentPath);
+                if (!currentLevel[folder]) {
+                    currentLevel[folder] = {
+                        label: metadata?.label ?? folderLabel,
+                        path: currentPath,
+                        icon: metadata?.icon,
+                        items: [],
+                        position: metadata?.position ?? 999,
+                        collapsible: metadata?.collapsible ?? true,
+                        defaultCollapsed: metadata?.collapsed ?? false,
+                        children: {}
+                    };
+                }
+                if (i === folderParts.length - 1) {
+                    if (isIndexFile) {
+                        // Update position, label, and icon if this is the index file for this folder
+                        currentLevel[folder].position = doc.categoryPosition ?? doc.meta.sidebar_position ?? currentLevel[folder].position;
+                        if (doc.categoryLabel) {
+                            currentLevel[folder].label = doc.categoryLabel;
+                        }
+                        if (doc.categoryIcon) {
+                            currentLevel[folder].icon = doc.categoryIcon;
+                        }
+                        if (doc.categoryCollapsible !== undefined) {
+                            currentLevel[folder].collapsible = doc.categoryCollapsible;
+                        }
+                        if (doc.categoryCollapsed !== undefined) {
+                            currentLevel[folder].defaultCollapsed = doc.categoryCollapsed;
+                        }
+                    }
+                    else {
+                        currentLevel[folder].items.push(doc);
+                    }
+                }
+                currentLevel = currentLevel[folder].children;
+            }
+        }
+        else {
+            if (!isIndexFile) {
+                standalone.push(doc);
+            }
+        }
+    });
+    return { rootGroups, standalone };
+}

package/dist/stores/config.d.ts

@@ -0,0 +1,20 @@
+import { type SpecraConfig } from '../config.types';
+/**
+ * Create and set the config store in a component's context.
+ * Call this in your root layout component.
+ */
+export declare function setConfigContext(config: SpecraConfig): import("svelte/store").Writable<SpecraConfig>;
+/**
+ * Get the config store from context.
+ * Must be called within a component that has a parent with setConfigContext.
+ */
+export declare function getConfigContext(): import("svelte/store").Writable<SpecraConfig>;
+/**
+ * Standalone writable config store for cases where context is not available.
+ * Prefer using context-based stores (setConfigContext/getConfigContext) in components.
+ */
+export declare const configStore: import("svelte/store").Writable<SpecraConfig>;
+/**
+ * Get a specific configuration value by dot-separated path
+ */
+export declare function getConfigValue<T = unknown>(config: SpecraConfig, path: string): T | undefined;

package/dist/stores/config.js

@@ -0,0 +1,45 @@
+import { writable, get } from 'svelte/store';
+import { getContext, setContext } from 'svelte';
+import { defaultConfig } from '../config.types';
+const CONFIG_KEY = Symbol('specra-config');
+/**
+ * Create and set the config store in a component's context.
+ * Call this in your root layout component.
+ */
+export function setConfigContext(config) {
+    const store = writable(config);
+    setContext(CONFIG_KEY, store);
+    return store;
+}
+/**
+ * Get the config store from context.
+ * Must be called within a component that has a parent with setConfigContext.
+ */
+export function getConfigContext() {
+    const store = getContext(CONFIG_KEY);
+    if (!store) {
+        throw new Error('getConfigContext must be used within a component with setConfigContext');
+    }
+    return store;
+}
+/**
+ * Standalone writable config store for cases where context is not available.
+ * Prefer using context-based stores (setConfigContext/getConfigContext) in components.
+ */
+export const configStore = writable(defaultConfig);
+/**
+ * Get a specific configuration value by dot-separated path
+ */
+export function getConfigValue(config, path) {
+    const keys = path.split('.');
+    let value = config;
+    for (const key of keys) {
+        if (value && typeof value === 'object' && key in value) {
+            value = value[key];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return value;
+}

package/dist/stores/index.d.ts

@@ -0,0 +1,4 @@
+export { configStore, setConfigContext, getConfigContext, getConfigValue } from './config';
+export { themeStore, type Theme } from './theme';
+export { tabStore } from './tabs';
+export { sidebarStore } from './sidebar';

package/dist/stores/index.js

@@ -0,0 +1,4 @@
+export { configStore, setConfigContext, getConfigContext, getConfigValue } from './config';
+export { themeStore } from './theme';
+export { tabStore } from './tabs';
+export { sidebarStore } from './sidebar';

package/dist/stores/sidebar.d.ts

@@ -0,0 +1,7 @@
+export declare const sidebarStore: {
+    subscribe: (this: void, run: import("svelte/store").Subscriber<boolean>, invalidate?: () => void) => import("svelte/store").Unsubscriber;
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+    set: (this: void, value: boolean) => void;
+};

package/dist/stores/sidebar.js

@@ -0,0 +1,12 @@
+import { writable } from 'svelte/store';
+function createSidebarStore() {
+    const { subscribe, set, update } = writable(false);
+    return {
+        subscribe,
+        open: () => set(true),
+        close: () => set(false),
+        toggle: () => update((v) => !v),
+        set
+    };
+}
+export const sidebarStore = createSidebarStore();

package/dist/stores/tabs.d.ts

@@ -0,0 +1,6 @@
+export declare const tabStore: {
+    subscribe: (this: void, run: import("svelte/store").Subscriber<string>, invalidate?: () => void) => import("svelte/store").Unsubscriber;
+    set: (tabId: string) => void;
+    initialize: (defaultTab: string) => void;
+    get: () => string;
+};

package/dist/stores/tabs.js

@@ -0,0 +1,41 @@
+import { writable, get } from 'svelte/store';
+import { browser } from '$app/environment';
+const TAB_STORAGE_KEY = 'specra-active-tab-group';
+function getInitialTab(defaultTab) {
+    if (!browser)
+        return defaultTab;
+    try {
+        const stored = localStorage.getItem(TAB_STORAGE_KEY);
+        if (stored)
+            return stored;
+    }
+    catch {
+        // Ignore localStorage errors
+    }
+    return defaultTab;
+}
+function createTabStore() {
+    const { subscribe, set, update } = writable('');
+    function initialize(defaultTab) {
+        const initial = getInitialTab(defaultTab);
+        set(initial);
+    }
+    function setActiveTab(tabId) {
+        set(tabId);
+        if (browser) {
+            try {
+                localStorage.setItem(TAB_STORAGE_KEY, tabId);
+            }
+            catch {
+                // Ignore localStorage errors
+            }
+        }
+    }
+    return {
+        subscribe,
+        set: setActiveTab,
+        initialize,
+        get: () => get({ subscribe })
+    };
+}
+export const tabStore = createTabStore();

package/dist/stores/theme.d.ts

@@ -0,0 +1,7 @@
+export type Theme = 'light' | 'dark' | 'system';
+export declare const themeStore: {
+    subscribe: (this: void, run: import("svelte/store").Subscriber<Theme>, invalidate?: () => void) => import("svelte/store").Unsubscriber;
+    set: (theme: Theme) => void;
+    toggle: () => void;
+    getResolved: () => "light" | "dark";
+};

package/dist/stores/theme.js

@@ -0,0 +1,75 @@
+import { writable } from 'svelte/store';
+import { browser } from '$app/environment';
+const THEME_STORAGE_KEY = 'specra-theme';
+function getInitialTheme() {
+    if (!browser)
+        return 'system';
+    try {
+        const stored = localStorage.getItem(THEME_STORAGE_KEY);
+        if (stored === 'light' || stored === 'dark' || stored === 'system') {
+            return stored;
+        }
+    }
+    catch {
+        // Ignore localStorage errors
+    }
+    return 'system';
+}
+function getResolvedTheme(theme) {
+    if (theme !== 'system')
+        return theme;
+    if (!browser)
+        return 'light';
+    return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+}
+function createThemeStore() {
+    const initial = getInitialTheme();
+    const { subscribe, set, update } = writable(initial);
+    function setTheme(theme) {
+        set(theme);
+        if (browser) {
+            try {
+                localStorage.setItem(THEME_STORAGE_KEY, theme);
+            }
+            catch {
+                // Ignore localStorage errors
+            }
+            applyTheme(theme);
+        }
+    }
+    function applyTheme(theme) {
+        if (!browser)
+            return;
+        const resolved = getResolvedTheme(theme);
+        const root = document.documentElement;
+        root.classList.remove('light', 'dark');
+        root.classList.add(resolved);
+    }
+    function toggle() {
+        update((current) => {
+            const resolved = getResolvedTheme(current);
+            const next = resolved === 'dark' ? 'light' : 'dark';
+            setTheme(next);
+            return next;
+        });
+    }
+    // Apply initial theme on creation
+    if (browser) {
+        applyTheme(initial);
+        // Listen for system preference changes
+        const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+        mediaQuery.addEventListener('change', () => {
+            const currentTheme = getInitialTheme();
+            if (currentTheme === 'system') {
+                applyTheme('system');
+            }
+        });
+    }
+    return {
+        subscribe,
+        set: setTheme,
+        toggle,
+        getResolved: () => getResolvedTheme(getInitialTheme())
+    };
+}
+export const themeStore = createThemeStore();