storybook-addon-design-system-docs 1.0.0

package/dist/preset.cjs

@@ -0,0 +1,208 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+console.log('[PRESET.CJS] Loading actual preset...');
+
+const logger = {
+    info: (msg, data) => console.log(`[PRESET] INFO: ${msg}`, data),
+    error: (msg, error) => console.error(`[PRESET] ERROR: ${msg}`, error)
+};
+
+/**
+ * Create AddonOptions from preset options.
+ */
+function createAddonOptions(options) {
+    if (!options.tailwindConfig) {
+        logger.error("tailwindConfig missing from options:", options);
+        throw new Error(
+            "tailwindConfig option is required. Please specify the path to your Tailwind config file. " +
+                'Example: { tailwindConfig: "../tailwind.config.js" }',
+        );
+    }
+    return options;
+}
+
+/**
+ * Create AssetAddonOptions from preset options if assets are configured.
+ */
+function createAssetOptions(options) {
+    if (!options.assets) {
+        return undefined;
+    }
+
+    return {
+        groups: options.assets,
+        assetsSidebarGroup: options.assetsSidebarGroup,
+        configDir: options.configDir,
+    };
+}
+
+/**
+ * Storybook indexer hook.
+ * Creates virtual entries for asset documentation pages.
+ *
+ * @param existingIndexers - The list of existing indexers
+ * @param options - Addon options
+ * @returns The updated indexers
+ */
+async function experimental_indexers(existingIndexers = [], options) {
+    console.log('[PRESET.CJS] experimental_indexers called');
+
+    if (!options.assets || !Array.isArray(options.assets)) {
+        return existingIndexers;
+    }
+
+    console.log('[PRESET.CJS] Creating indexers for', options.assets.length, 'asset groups');
+
+    // Create an indexer for virtual asset stories
+    const assetIndexer = {
+        test: /virtual:design-system-docs\/assets\.stories\.js$/,
+        createIndex: async (fileName, opts) => {
+            console.log('[PRESET.CJS] Asset indexer createIndex called for:', fileName);
+
+            const entries = [];
+
+            // Create an entry for each asset group
+            if (options.assets && Array.isArray(options.assets)) {
+                options.assets.forEach((asset) => {
+                    const assetName = asset.name;
+                    const title = `Assets/${assetName}`;
+
+                    entries.push({
+                        type: 'story',
+                        importPath: fileName,
+                        exportName: assetName,
+                        name: assetName,
+                        title: title,
+                        meta: {
+                            title: title,
+                            component: null,
+                            parameters: {
+                                docs: {
+                                    page: () => {
+                                        const React = require('react');
+                                        return React.createElement('div', {}, `${assetName} Documentation Page`);
+                                    }
+                                }
+                            }
+                        }
+                    });
+                });
+            }
+
+            return entries;
+        }
+    };
+
+    return [...existingIndexers, assetIndexer];
+}
+
+/**
+ * Vite config hook.
+ * Injects the unplugin into the Storybook Vite config.
+ *
+ * @param config - The Vite config object
+ * @param options - Addon options
+ * @returns The modified Vite config
+ */
+const viteFinal = async (config, options) => {
+    console.log('[PRESET.CJS] viteFinal called');
+
+    const { plugins = [] } = config;
+
+    // Create the unplugin instance with options
+    const unpluginInstance = {
+        name: 'design-system-docs-unplugin',
+        configResolved() {
+            console.log('[UNPLUGIN] Config resolved');
+        },
+        resolveId(id) {
+            console.log('[UNPLUGIN] Resolving ID:', id);
+            if (id === 'virtual:design-system-docs/assets.stories.js') {
+                console.log('[UNPLUGIN] Matched assets stories');
+                return '\0design-system-docs:assets.stories.js';
+            }
+        },
+        load(id) {
+            console.log('[UNPLUGIN] Loading ID:', id);
+            if (id === '\0design-system-docs:assets.stories.js') {
+                console.log('[UNPLUGIN] Loading virtual assets stories module');
+
+                // Generate CSF stories for all asset groups
+                const stories = [];
+                if (options.assets && Array.isArray(options.assets)) {
+                    options.assets.forEach((asset) => {
+                        const assetName = asset.name;
+                        const storyName = assetName.charAt(0).toUpperCase() + assetName.slice(1);
+
+                        stories.push(`
+export const ${storyName} = {
+    name: '${storyName}',
+    parameters: {
+        docs: {
+            page: () => {
+                const React = require('react');
+                return React.createElement('div', {}, '${assetName} Documentation Page');
+            }
+        }
+    }
+};
+                        `);
+                    });
+                }
+
+                return stories.join('\n');
+            }
+        }
+    };
+
+    // The unplugin returns a Vite plugin object
+    plugins.push(unpluginInstance);
+
+    config.plugins = plugins;
+    return config;
+};
+
+/**
+ * Registers asset directories as static directories for Storybook to serve.
+ * No copying is performed - assets are served directly from their source locations.
+ * We map them to specific URLs (staticPath) to ensure browser compatibility.
+ */
+const staticDirs = async (existingStaticDirs, options) => {
+    console.log('[PRESET.CJS] staticDirs called');
+    try {
+        if (!options.assets || !Array.isArray(options.assets)) {
+            return existingStaticDirs;
+        }
+
+        console.log('[PRESET.CJS] Found assets configuration:', options.assets.length, 'groups');
+
+        // For now, just return existing static dirs
+        return existingStaticDirs;
+    } catch (error) {
+        logger.error("Failed to configure static directories", error);
+        return existingStaticDirs;
+    }
+};
+
+/**
+ * Add the tailwind config file to the stories list so that experimental_indexers
+ * matches it and generates the documentation pages.
+ */
+const stories = async (entry = [], options) => {
+    console.log('[PRESET.CJS] stories called');
+    try {
+        // Stories are now generated by experimental_indexers
+        return entry;
+    } catch (error) {
+        logger.error("Failed to inject config into stories", error);
+        return entry;
+    }
+};
+
+exports.experimental_indexers = experimental_indexers;
+exports.staticDirs = staticDirs;
+exports.stories = stories;
+exports.viteFinal = viteFinal;

package/dist/preset.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Storybook indexer hook.
+ * We no longer use a custom indexer for assets, as we generate physical MDX files
+ * that are picked up by the standard Storybook indexers.
+ *
+ * @param existingIndexers - The list of existing indexers
+ * @param options - Addon options
+ * @returns The (unmodified) indexers
+ */
+export declare function experimental_indexers(existingIndexers: any[], _options: any): Promise<any[]>;
+/**
+ * Vite config hook.
+ * Injects the unplugin into the Storybook Vite config.
+ *
+ * @param config - The Vite config object
+ * @param options - Addon options
+ * @returns The modified Vite config
+ */
+export declare const viteFinal: (config: any, options: any) => Promise<any>;
+/**
+ * Registers asset directories as static directories for Storybook to serve.
+ * No copying is performed - assets are served directly from their source locations.
+ * We map them to specific URLs (staticPath) to ensure browser compatibility.
+ */
+export declare const staticDirs: (existingStaticDirs: any[], options: any) => Promise<any[]>;
+/**
+ * Add the tailwind config file to the stories list so that experimental_indexers
+ * matches it and generates the documentation pages.
+ */
+export declare const stories: (entry: StorybookConfigRaw, options: any) => Promise<any>;

package/dist/preset.js

@@ -0,0 +1,13 @@
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+
+const preset = require('./dist/preset.cjs');
+
+export const managerEntries = (entry = []) => {
+    return [...entry, require.resolve('./dist/manager.js')];
+};
+
+export const experimental_indexers = preset.experimental_indexers;
+export const viteFinal = preset.viteFinal;
+export const stories = preset.stories;
+export const staticDirs = preset.staticDirs;

package/dist/types.d.ts

@@ -0,0 +1,204 @@
+import type { VALID_SECTIONS } from "@/constants";
+import type { NormalizedAddonOptions } from "@/core/primitives/types";
+export * from "@/core/primitives/types";
+export interface PackageJson {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+}
+/**
+ * User-facing configuration options for the Design System addon.
+ * These are the options passed to the addon in .storybook/main.ts
+ */
+export interface DesignSystemAddonOptions {
+    /**
+     * Path to your Tailwind config file (relative to .storybook/ directory).
+     * Example: '../tailwind.config.js' or '../src/styles.css' (for Tailwind v4)
+     * This is now required - backwards compatibility has been removed.
+     */
+    tailwindConfig: string;
+    /**
+     * Sidebar group name for all documentation pages. This replaces defaultPath.
+     * @default 'Design System/'
+     */
+    sidebarGroup?: string;
+    /**
+     * Which theme sections to enable.
+     * @default ['Colors', 'Typography', 'Spacing', 'Shadows', 'BorderRadius']
+     */
+    sections?: TailwindSectionInput[];
+    /**
+     * If defined, combines all sections into one story.
+     */
+    forceSingleDoc?: CustomSectionInput;
+    /**
+     * When true, hides Tailwind's built-in values and shows only custom values.
+     * @default false
+     */
+    showOnlyCustom?: boolean;
+    /**
+     * Typography configuration options.
+     */
+    typography?: {
+        example?: string;
+    };
+    /**
+     * Template configuration for custom MDX rendering.
+     */
+    templates?: TemplateConfig;
+    /**
+     * Asset group configurations for icons, illustrations, etc.
+     */
+    assets?: AssetGroupConfig[];
+}
+export interface AssetAddonOptions {
+    groups: NormalizedAssetGroup[];
+}
+export interface UnpluginOptions {
+    addonOptions: NormalizedAddonOptions;
+    assetOptions?: AssetAddonOptions;
+    configPath?: string;
+}
+export type TailwindConfigSections = (typeof VALID_SECTIONS)[number];
+export type SectionInput<NameType extends string> = NameType | {
+    name: NameType;
+    path?: string;
+};
+export type TailwindSectionInput = SectionInput<TailwindConfigSections>;
+export type CustomSectionInput = SectionInput<string>;
+export interface NormalizedSection {
+    name: string;
+    path: string;
+}
+export interface ResolvedConfig {
+    theme: {
+        colors: Record<string, any>;
+        fontSize: Record<string, any>;
+        fontFamily: Record<string, any>;
+        fontWeight: Record<string, any>;
+        spacing: Record<string, any>;
+        boxShadow: Record<string, any>;
+        borderRadius: Record<string, any>;
+    };
+}
+export interface Typography {
+    type: Record<string, string>;
+    weight: Record<string, string>;
+    size: Record<string, string>;
+}
+export interface Spacing {
+    values: Record<string, string>;
+}
+export interface Shadows {
+    values: Record<string, string>;
+}
+export interface BorderRadius {
+    values: Record<string, string>;
+}
+export type ThemeCssVariables = Record<string, Record<string, string | string[]>>;
+export type SupportedFontUnit = "rem" | "em" | "px" | "pt" | "cm" | "mm" | "in" | "pc" | "%";
+/**
+ * Configuration for the template system and source code generation.
+ */
+export interface TemplateConfig {
+    /**
+     * Path to directory containing custom templates.
+     * Templates in this directory override defaults by matching filename.
+     * @example './.storybook/theme-templates'
+     */
+    directory?: string;
+    /**
+     * Whether to enable template caching (default: true in production)
+     */
+    cache?: boolean;
+    /**
+     * Whether to use React components (true) or inline framework-agnostic templates (false).
+     * Default: false (framework-agnostic templates)
+     *
+     * When true: Templates use pre-built React components (smaller bundles, React-only)
+     * When false: Templates generate all markup/logic inline (larger bundles, framework-agnostic)
+     */
+    useReactComponents?: boolean;
+    /**
+     * Custom filters to add to the template engine.
+     * Key is the filter name, value is the filter function.
+     */
+    filters?: Record<string, (...args: any[]) => any>;
+    /**
+     * Additional context data available to all templates
+     */
+    globals?: Record<string, any>;
+}
+export interface AssetVariantConfig {
+    enabled: boolean;
+    suffixes: [string, string];
+    defaultVariant: "light" | "dark";
+}
+export interface AssetDisplayConfig {
+    layout: "grid" | "list";
+    columns: number;
+    showFilename: boolean;
+    showPath: boolean;
+    previewSize: number;
+    background: "transparent" | "light" | "dark" | "checkerboard";
+}
+export interface AssetCopyConfig {
+    import?: string;
+    component?: string;
+}
+export interface AssetFilterConfig {
+    include: string[];
+    exclude: string[];
+}
+export interface AssetGroupConfig {
+    name: string;
+    path?: string;
+    source: string;
+    /**
+     * URL path where assets are served from (e.g., '/assets/illustrations').
+     * When provided, assets are served directly from this path without copying.
+     * User must configure staticDirs in their Storybook config to serve from this path.
+     */
+    staticPath?: string;
+    title?: string;
+    description?: string;
+    variants?: Partial<AssetVariantConfig>;
+    display?: Partial<AssetDisplayConfig>;
+    copy?: AssetCopyConfig;
+    filter?: Partial<AssetFilterConfig>;
+    groupByFolder?: boolean;
+}
+export interface NormalizedAssetGroup {
+    name: string;
+    path: string;
+    source: string;
+    /** URL path where assets are served from. Either user-provided or auto-generated. */
+    staticPath: string;
+    title: string;
+    description?: string;
+    variants: AssetVariantConfig;
+    display: AssetDisplayConfig;
+    copy: AssetCopyConfig;
+    filter: AssetFilterConfig;
+    groupByFolder: boolean;
+}
+export interface Asset {
+    id: string;
+    name: string;
+    filename: string;
+    relativePath: string;
+    absolutePath: string;
+    url: string;
+    folder?: string;
+    ext: string;
+    variants?: {
+        light?: string;
+        dark?: string;
+    };
+    type: "svg" | "png" | "jpg" | "jpeg" | "gif" | "webp";
+}
+export interface AssetGroup {
+    name: string;
+    config: NormalizedAssetGroup;
+    assets: Asset[];
+    folders?: Map<string, Asset[]>;
+}

package/dist/types.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("@/core/primitives/types"), exports);

package/dist/unplugin.d.ts

@@ -0,0 +1,2 @@
+import type { UnpluginOptions } from "./types";
+export declare const vite: (options?: UnpluginOptions) => import("vite").Plugin<any> | import("vite").Plugin<any>[];

package/dist/unplugin.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vite = void 0;
+const unplugin_1 = require("unplugin");
+const constants_1 = require("@/constants");
+const manager_1 = require("@/core/assets/manager");
+const data_1 = require("@/core/primitives/data");
+const load_1 = require("@/core/primitives/load");
+const tw_config_1 = require("@/core/primitives/loaders/tw-config");
+const tw_css_1 = require("@/core/primitives/loaders/tw-css");
+const Logger_1 = require("@/util/Logger");
+const logger = new Logger_1.Logger("unplugin");
+const unplugin = (0, unplugin_1.createUnplugin)((options) => {
+    // Asset handling
+    const assetManager = options.assetOptions?.groups && options.assetOptions.groups.length > 0
+        ? (0, manager_1.createAssetManager)(options.assetOptions.groups)
+        : undefined;
+    return {
+        name: "unplugin-design-system-docs",
+        enforce: "pre",
+        resolveId(id, _importer) {
+            // Handle design system data virtual module (design-system-docs:theme)
+            if (id === `${constants_1.VIRTUAL_MODULE_PREFIX}theme`) {
+                return constants_1.DESIGN_SYSTEM_DATA_ID;
+            }
+            // Handle asset data virtual module (design-system-docs:assets)
+            if (id === `${constants_1.VIRTUAL_MODULE_PREFIX}assets`) {
+                return constants_1.ASSET_DATA_ID;
+            }
+            // Handle group-specific asset data: design-system-docs:assets/<group-name>
+            // This is used by the generated MDX files
+            if (id.startsWith(`${constants_1.VIRTUAL_MODULE_PREFIX}assets/`)) {
+                const groupName = id.replace(`${constants_1.VIRTUAL_MODULE_PREFIX}assets/`, "");
+                return constants_1.ASSET_GROUP_ID_PREFIX + groupName;
+            }
+            return null;
+        },
+        loadInclude(id) {
+            return (id === constants_1.DESIGN_SYSTEM_DATA_ID ||
+                id === constants_1.ASSET_DATA_ID ||
+                id.startsWith(constants_1.ASSET_GROUP_ID_PREFIX));
+        },
+        async load(id) {
+            try {
+                // Handle design system data virtual module (design-system-docs:theme)
+                if (id === constants_1.DESIGN_SYSTEM_DATA_ID) {
+                    if (!options.configPath) {
+                        const errorMsg = "No Tailwind config path found. Cannot load theme data. " +
+                            "This is likely a bug in the addon setup.";
+                        logger.error(errorMsg);
+                        throw new Error(errorMsg);
+                    }
+                    // Watch the config file for changes
+                    if (this.addWatchFile && options.configPath) {
+                        this.addWatchFile(options.configPath);
+                    }
+                    // Load the Tailwind theme from the config file
+                    const fullTailwindConfig = await (0, load_1.loadTheme)(options.addonOptions);
+                    // Transform to Data Context
+                    const data = (0, data_1.createDesignSystemData)(fullTailwindConfig, options.addonOptions);
+                    // Export theme data as plain JavaScript module
+                    return `
+export const colors = ${JSON.stringify(data.colors, null, 2)};
+export const typography = ${JSON.stringify(data.typography, null, 2)};
+export const spacing = ${data.spacing ? JSON.stringify(data.spacing, null, 2) : "undefined"};
+export const shadows = ${data.shadows ? JSON.stringify(data.shadows, null, 2) : "undefined"};
+export const borderRadius = ${data.borderRadius ? JSON.stringify(data.borderRadius, null, 2) : "undefined"};
+                    `.trim();
+                }
+                // Handle asset data virtual module (design-system-docs:assets)
+                if (id === constants_1.ASSET_DATA_ID) {
+                    if (!assetManager)
+                        return "export default {}";
+                    // Get all assets from all groups
+                    const groups = await Promise.all(assetManager
+                        .getGroupNames()
+                        .map((name) => assetManager.getGroup(name)));
+                    const assets = groups
+                        .filter((g) => !!g)
+                        .flatMap((g) => g.assets);
+                    return `export default ${JSON.stringify(assets)}`;
+                }
+                // Handle per-group data module
+                // e.g., \0design-system-docs:asset-group/Icons
+                if (id.startsWith(constants_1.ASSET_GROUP_ID_PREFIX)) {
+                    const groupName = id.slice(constants_1.ASSET_GROUP_ID_PREFIX.length);
+                    logger.info(`Loading asset group data: ${groupName}`);
+                    if (!assetManager) {
+                        logger.warn(`No asset manager available for group: ${groupName}`);
+                        return "export default {}";
+                    }
+                    const group = await assetManager.getGroup(groupName);
+                    if (!group) {
+                        logger.warn(`Asset group not found: ${groupName}`);
+                        return "export default {}";
+                    }
+                    return `export default ${JSON.stringify(group)}`;
+                }
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                logger.error(`Failed to load virtual module: ${id}`, error);
+                throw new Error(`[storybook-addon-design-system-docs] ${errorMessage}`);
+            }
+        },
+        vite: {
+            handleHotUpdate({ file, server }) {
+                // Handle config/CSS file changes
+                // If the file is part of the Tailwind config (JS or CSS)
+                if ((0, tw_config_1.isTwConfigPath)(file) || (0, tw_css_1.isTwCssPath)(file)) {
+                    // Update: Only invalidate the data module, not the config module (which is no longer virtual)
+                    const n1 = server.moduleGraph.getModuleById(constants_1.DESIGN_SYSTEM_DATA_ID);
+                    n1 && server.moduleGraph.invalidateModule(n1);
+                    server.ws.send({ type: "full-reload" });
+                    return;
+                }
+                // Handle asset changes
+                async function handleAssetChange(filePath, server) {
+                    if (!assetManager)
+                        return;
+                    const matchingGroup = assetManager.findMatchingGroup(filePath);
+                    if (!matchingGroup)
+                        return;
+                    logger.info(`Asset changed in group ${matchingGroup}: ${filePath}`);
+                    assetManager.invalidateGroup(matchingGroup);
+                    // Invalidate the group module
+                    const groupModule = server.moduleGraph.getModuleById(constants_1.ASSET_GROUP_ID_PREFIX + matchingGroup);
+                    groupModule && server.moduleGraph.invalidateModule(groupModule);
+                    // Invalidate the assets data module
+                    const assetsModule = server.moduleGraph.getModuleById(constants_1.ASSET_DATA_ID);
+                    assetsModule && server.moduleGraph.invalidateModule(assetsModule);
+                    server.ws.send({ type: "full-reload", path: "*" });
+                }
+                handleAssetChange(file, server);
+            },
+        },
+    };
+});
+exports.vite = unplugin.vite;

package/dist/util/Logger.d.ts

@@ -0,0 +1,67 @@
+export type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
+/**
+ * Logger utility for the addon with configurable log levels and context support.
+ *
+ * Features:
+ * - Log levels (debug, info, warn, error, silent)
+ * - Context/prefix support for consistent logging
+ * - Conditional ANSI colors (respects NO_COLOR, FORCE_COLOR, TTY detection)
+ * - Structured data logging
+ */
+export declare class Logger {
+    private static defaultPrefix;
+    private static level;
+    private static useColors;
+    private prefix;
+    /**
+     * Create a logger instance with a specific context prefix.
+     * @param context - Context name to prefix log messages (e.g., 'ConfigLoader', 'unplugin')
+     */
+    constructor(context?: string);
+    /**
+     * Set the global log level. Messages below this level will be suppressed.
+     */
+    static setLevel(level: LogLevel): void;
+    /**
+     * Get the current global log level.
+     */
+    static getLevel(): LogLevel;
+    /**
+     * Enable or disable color output.
+     */
+    static setColors(enabled: boolean): void;
+    private shouldLog;
+    private colorize;
+    private formatMessage;
+    /**
+     * Log debug messages. Only shown when log level is 'debug'.
+     */
+    debug(message: string, data?: Record<string, unknown>): void;
+    /**
+     * Log informational messages.
+     */
+    info(message: string, data?: Record<string, unknown>): void;
+    /**
+     * Log warning messages.
+     */
+    warn(message: string, data?: Record<string, unknown>): void;
+    /**
+     * Log error messages.
+     */
+    error(message: string, error?: Error | unknown, data?: Record<string, unknown>): void;
+    /**
+     * Static warn method for backward compatibility.
+     * Consider using instance methods for context-aware logging.
+     */
+    static warn(message: string): void;
+    /**
+     * Static error method for backward compatibility.
+     * Consider using instance methods for context-aware logging.
+     */
+    static error(message: string): void;
+    /**
+     * Static info method for backward compatibility.
+     * Consider using instance methods for context-aware logging.
+     */
+    static info(message: string): void;
+}