Programmatic API

/**
 * Initialize Styleguidist API
 * @param config - Configuration object or path to config file (optional)
 * @returns API object with build, server, and makeWebpackConfig methods
 */
function styleguidist(config?: StyleguidistConfig | string): StyleguidistAPI;

interface StyleguidistAPI {
  build(callback: BuildCallback): webpack.Compiler;
  server(callback: ServerCallback): ServerInfo;
  makeWebpackConfig(env?: WebpackEnv): webpack.Configuration;
}

const styleguidist = require('react-styleguidist');

// Initialize with inline configuration
const api = styleguidist({
  components: 'src/components/**/*.{js,jsx}',
  styleguideDir: 'dist/styleguide'
});

// Initialize with config file path
const api = styleguidist('./styleguide.config.js');

// Initialize with default config (looks for styleguide.config.js)
const api = styleguidist();

/**
 * Build static styleguide
 * @param callback - Function called when build completes or fails
 * @returns Webpack compiler instance for advanced usage
 */
build(callback: BuildCallback): webpack.Compiler;

type BuildCallback = (
  err: Error | null,
  config: SanitizedStyleguidistConfig,
  stats: webpack.Stats
) => void;

const styleguidist = require('react-styleguidist');

const api = styleguidist({
  components: 'src/components/**/*.jsx',
  styleguideDir: 'build/styleguide'
});

// Basic build
api.build((err, config, stats) => {
  if (err) {
    console.error('Build failed:', err.message);
    process.exit(1);
  }

  console.log('Styleguide built successfully!');
  console.log('Output directory:', config.styleguideDir);
  console.log('Build time:', stats.endTime - stats.startTime, 'ms');
});

// Advanced usage with compiler access
const compiler = api.build((err, config, stats) => {
  // Handle build completion
});

// Access webpack hooks for advanced customization
compiler.hooks.done.tap('CustomPlugin', (stats) => {
  console.log('Custom build processing...');
});

/**
 * Start development server
 * @param callback - Function called when server starts or fails
 * @returns Object containing WebpackDevServer app and webpack compiler
 */
server(callback: ServerCallback): ServerInfo;

type ServerCallback = (
  err: Error | undefined,
  config: SanitizedStyleguidistConfig
) => void;

interface ServerInfo {
  app: WebpackDevServer;
  compiler: webpack.Compiler;
}

const styleguidist = require('react-styleguidist');

const api = styleguidist({
  components: 'src/components/**/*.jsx',
  serverPort: 8080,
  serverHost: 'localhost'
});

// Start development server
const serverInfo = api.server((err, config) => {
  if (err) {
    console.error('Server failed to start:', err.message);
    return;
  }

  console.log(`Server running at http://${config.serverHost}:${config.serverPort}`);
});

// Access server and compiler for advanced usage
const { app, compiler } = serverInfo;

// Add custom middleware
app.app.use('/custom', (req, res) => {
  res.json({ message: 'Custom endpoint' });
});

// Hook into webpack compilation
compiler.hooks.done.tap('DevServerPlugin', (stats) => {
  if (stats.hasErrors()) {
    console.log('Compilation errors detected');
  }
});

/**
 * Generate webpack configuration
 * @param env - Target environment (defaults to 'production')
 * @returns Complete webpack configuration object
 */
makeWebpackConfig(env?: WebpackEnv): webpack.Configuration;

type WebpackEnv = 'development' | 'production' | 'none';

const styleguidist = require('react-styleguidist');

const api = styleguidist({
  components: 'src/components/**/*.jsx'
});

// Get production webpack config
const prodConfig = api.makeWebpackConfig('production');
console.log('Entry points:', prodConfig.entry);
console.log('Output path:', prodConfig.output.path);

// Get development webpack config
const devConfig = api.makeWebpackConfig('development');
console.log('Dev server config:', devConfig.devServer);

// Use config with custom webpack setup
const webpack = require('webpack');
const compiler = webpack(prodConfig);

compiler.run((err, stats) => {
  if (err || stats.hasErrors()) {
    console.error('Custom build failed');
  } else {
    console.log('Custom build completed');
  }
});

const styleguidist = require('react-styleguidist');
const fs = require('fs');
const path = require('path');

async function buildStyleguideWithAssets() {
  const api = styleguidist('./styleguide.config.js');
  
  return new Promise((resolve, reject) => {
    api.build((err, config, stats) => {
      if (err) return reject(err);
      
      // Copy additional assets
      const assetsDir = path.join(config.styleguideDir, 'assets');
      fs.mkdirSync(assetsDir, { recursive: true });
      fs.copyFileSync('logo.png', path.join(assetsDir, 'logo.png'));
      
      // Generate build manifest
      const manifest = {
        buildTime: new Date().toISOString(),
        outputPath: config.styleguideDir,
        assets: stats.toJson().assets.map(asset => asset.name)
      };
      
      fs.writeFileSync(
        path.join(config.styleguideDir, 'build-manifest.json'),
        JSON.stringify(manifest, null, 2)
      );
      
      resolve(config);
    });
  });
}

const styleguidist = require('react-styleguidist');
const express = require('express');

function startDevEnvironment() {
  const api = styleguidist({
    components: 'src/components/**/*.jsx',
    serverPort: 3001
  });

  const { app, compiler } = api.server((err, config) => {
    if (err) {
      console.error('Dev server error:', err);
      return;
    }
    console.log('Styleguidist server ready');
  });

  // Add API endpoints to the dev server
  app.app.use('/api', express.json());
  app.app.post('/api/feedback', (req, res) => {
    console.log('Component feedback:', req.body);
    res.json({ status: 'received' });
  });

  // Monitor compilation for notifications
  compiler.hooks.done.tap('NotificationPlugin', (stats) => {
    if (!stats.hasErrors()) {
      console.log('✓ Components updated successfully');
    }
  });
}

interface SanitizedStyleguidistConfig {
  components: string | string[] | (() => string[]);
  sections: ConfigSection[];
  styleguideDir: string;
  serverHost: string;
  serverPort: number;
  webpackConfig: webpack.Configuration | ((env?: string) => webpack.Configuration);
  dangerouslyUpdateWebpackConfig: (config: webpack.Configuration, env: string) => webpack.Configuration;
  updateWebpackConfig: (config: webpack.Configuration) => webpack.Configuration;
  theme: RecursivePartial<Theme>;
  styles: ((theme: Theme) => Styles) | Styles;
  template: any;
  title: string;
  verbose: boolean;
  // ... many additional configuration properties
}

interface ConfigSection {
  name?: string;
  content?: string;
  components?: string | string[] | (() => string[]);
  sections?: ConfigSection[];
  description?: string;
  exampleMode?: ExpandMode;
  usageMode?: ExpandMode;
}