Configuration

/**
 * Configuration object with all optional properties
 */
interface StyleguidistConfig {
  components?: string | string[] | (() => string[]);
  sections?: ConfigSection[];
  webpackConfig?: webpack.Configuration | ((env?: string) => webpack.Configuration);
  styleguideDir?: string;
  serverHost?: string;
  serverPort?: number;
  theme?: RecursivePartial<Theme> | string;
  styles?: Styles | string | ((theme: Theme) => Styles);
  // ... extensive additional options
}

/**
 * Load configuration from file or object
 * @param config - Config object, file path, or undefined for auto-discovery
 * @returns Processed configuration with defaults applied
 */
function getConfig(
  config?: string | StyleguidistConfig,
  update?: (conf: StyleguidistConfig) => StyleguidistConfig
): SanitizedStyleguidistConfig;

// styleguide.config.js
module.exports = {
  components: 'src/components/**/*.{js,jsx,ts,tsx}',
  styleguideDir: 'dist/styleguide',
  serverPort: 8080,
  title: 'My Component Library'
};

// With function-based components discovery
module.exports = {
  components: () => {
    const glob = require('glob');
    return glob.sync('src/components/**/[A-Z]*.{js,jsx}')
      .filter(path => !path.includes('.test.'));
  }
};

// Environment-specific configuration
const isDev = process.env.NODE_ENV === 'development';

module.exports = {
  components: 'src/components/**/*.jsx',
  styleguideDir: isDev ? 'tmp/styleguide' : 'dist/styleguide',
  serverPort: isDev ? 6060 : 8080,
  showCode: isDev
};

interface ComponentConfig {
  /** Component file patterns or function returning file paths */
  components?: string | string[] | (() => string[]);
  
  /** Files/directories to ignore during component discovery */
  ignore?: string[];
  
  /** Skip components that don't have example files */
  skipComponentsWithoutExample?: boolean;
  
  /** Default example content or file path for components without examples */
  defaultExample?: string | boolean;
  
  /** Function to generate example file path for a component */
  getExampleFilename?: (componentPath: string) => string;
}

module.exports = {
  // Single pattern
  components: 'src/components/**/*.jsx',
  
  // Multiple patterns
  components: [
    'src/components/**/*.jsx',
    'src/widgets/**/*.jsx'
  ],
  
  // Function-based discovery
  components: () => {
    const glob = require('glob');
    return glob.sync('src/**/*.jsx')
      .filter(path => !path.includes('__tests__'))
      .filter(path => path.includes('Component'));
  },
  
  // Ignore patterns
  ignore: [
    '**/__tests__/**',
    '**/node_modules/**',
    '**/*.test.{js,jsx}'
  ],
  
  // Skip components without examples
  skipComponentsWithoutExample: true,
  
  // Default example for components
  defaultExample: 'Readme.md',
  // or provide default content
  defaultExample: '## Examples\n\n```jsx\n<ComponentName />\n```',
  
  // Custom example filename generation
  getExampleFilename: (componentPath) => {
    return componentPath.replace(/\.jsx?$/, '.examples.md');
  }
};

interface ConfigSection {
  /** Section name displayed in navigation */
  name?: string;
  
  /** Markdown content for section introduction */
  content?: string;
  
  /** Component patterns specific to this section */
  components?: string | string[] | (() => string[]);
  
  /** Nested subsections */
  sections?: ConfigSection[];
  
  /** Section description */
  description?: string;
  
  /** Default expand mode for examples in this section */
  exampleMode?: ExpandMode;
  
  /** Default expand mode for usage/props in this section */
  usageMode?: ExpandMode;
}

type ExpandMode = 'expand' | 'collapse' | 'hide';

module.exports = {
  sections: [
    {
      name: 'Introduction',
      content: 'docs/introduction.md'
    },
    {
      name: 'UI Components',
      components: 'src/components/ui/**/*.jsx',
      exampleMode: 'expand',
      usageMode: 'collapse'
    },
    {
      name: 'Layout',
      sections: [
        {
          name: 'Grid System',
          components: 'src/components/layout/Grid*.jsx'
        },
        {
          name: 'Containers',
          components: 'src/components/layout/Container*.jsx'
        }
      ]
    },
    {
      name: 'Forms',
      content: 'docs/forms.md',
      components: () => {
        return [
          'src/components/forms/Input.jsx',
          'src/components/forms/Button.jsx',
          'src/components/forms/Form.jsx'
        ];
      }
    }
  ]
};

interface WebpackConfig {
  /** Base webpack configuration or function returning config */
  webpackConfig?: webpack.Configuration | ((env?: string) => webpack.Configuration);
  
  /** Function to safely update generated webpack config */
  updateWebpackConfig?: (config: webpack.Configuration) => webpack.Configuration;
  
  /** Function to modify webpack config (use with caution) */
  dangerouslyUpdateWebpackConfig?: (config: webpack.Configuration, env: string) => webpack.Configuration;
  
  /** Module aliases for webpack resolution */
  moduleAliases?: Record<string, string>;
  
  /** Additional modules to require before rendering components */
  require?: string[];
  
  /** Context object available in examples */
  context?: Record<string, any>;
  
  /** Additional context dependencies for webpack watching */
  contextDependencies?: string[];
}

const path = require('path');

module.exports = {
  // Use existing webpack config
  webpackConfig: require('./webpack.config.js'),
  
  // Function-based webpack config
  webpackConfig: (env) => {
    return {
      module: {
        rules: [
          {
            test: /\.scss$/,
            use: ['style-loader', 'css-loader', 'sass-loader']
          }
        ]
      },
      resolve: {
        alias: {
          '@': path.resolve(__dirname, 'src')
        }
      }
    };
  },
  
  // Update generated config
  updateWebpackConfig: (config) => {
    // Add source maps for development
    config.devtool = 'eval-source-map';
    
    // Add custom plugins
    config.plugins.push(
      new webpack.DefinePlugin({
        STYLEGUIDE_BUILD: true
      })
    );
    
    return config;
  },
  
  // Module aliases
  moduleAliases: {
    '@components': path.resolve(__dirname, 'src/components'),
    '@utils': path.resolve(__dirname, 'src/utils')
  },
  
  // Global requires
  require: [
    path.resolve(__dirname, 'src/styles/global.css'),
    path.resolve(__dirname, 'src/setupTests.js')
  ],
  
  // Context for examples
  context: {
    theme: require('./src/theme'),
    utils: require('./src/utils')
  }
};

interface ThemeConfig {
  /** Theme object or path to theme file */
  theme?: RecursivePartial<Theme> | string;
  
  /** JSS styles, file path, or function returning styles */
  styles?: Styles | string | ((theme: Theme) => Styles);
  
  /** Override default UI components */
  styleguideComponents?: Record<string, string>;
}

interface Theme {
  color: {
    base: string;
    light: string;
    lightest: string;
    link: string;
    linkHover: string;
    error: string;
    // ... additional color properties
  };
  fontFamily: {
    base: string;
    monospace: string;
  };
  fontSize: {
    base: number;
    text: number;
    small: number;
    h1: number;
    h2: number;
    // ... additional font sizes
  };
  // ... layout, spacing, and border properties
}

module.exports = {
  // Custom theme object
  theme: {
    color: {
      link: '#007bff',
      linkHover: '#0056b3',
      base: '#333333'
    },
    fontFamily: {
      base: '"Inter", -apple-system, BlinkMacSystemFont, sans-serif'
    }
  },
  
  // Theme from file
  theme: './src/styleguide-theme.js',
  
  // Custom styles with JSS
  styles: {
    Playground: {
      preview: {
        padding: '20px',
        border: '1px solid #e0e0e0',
        borderRadius: '4px'
      }
    },
    ReactComponent: {
      tabs: {
        backgroundColor: '#f8f9fa'
      }
    }
  },
  
  // Styles from function
  styles: (theme) => ({
    Logo: {
      logo: {
        color: theme.color.base,
        fontSize: theme.fontSize.h2
      }
    }
  }),
  
  // Custom UI components
  styleguideComponents: {
    Wrapper: path.join(__dirname, 'src/styleguide/Wrapper'),
    StyleGuideRenderer: path.join(__dirname, 'src/styleguide/StyleGuideRenderer')
  }
};

interface ServerBuildConfig {
  /** Development server host */
  serverHost?: string;
  
  /** Development server port */
  serverPort?: number;
  
  /** Output directory for built styleguide */
  styleguideDir?: string;
  
  /** Static assets directories to copy */
  assetsDir?: string | string[];
  
  /** HTML template or template function */
  template?: any;
  
  /** Styleguide title */
  title?: string;
  
  /** Enable/disable minification in production */
  minimize?: boolean;
  
  /** Enable verbose logging */
  verbose?: boolean;
}

module.exports = {
  // Server configuration
  serverHost: '0.0.0.0',
  serverPort: 8080,
  
  // Build configuration
  styleguideDir: 'dist/styleguide',
  title: 'My Component Library v2.0',
  minimize: true,
  
  // Assets
  assetsDir: ['src/assets', 'public/images'],
  
  // Custom HTML template
  template: {
    favicon: 'favicon.ico',
    head: {
      meta: [
        { name: 'description', content: 'Component documentation' }
      ],
      links: [
        { rel: 'stylesheet', href: 'https://fonts.googleapis.com/css?family=Inter' }
      ]
    }
  }
};

interface ComponentProcessingConfig {
  /** Custom props parser function */
  propsParser?: (
    filePath: string,
    code: string,
    resolver: Function,
    handlers: Handler[]
  ) => DocumentationObject;
  
  /** Component resolver for react-docgen */
  resolver?: (ast: ASTNode, parser: any) => NodePath | NodePath[];
  
  /** React-docgen handlers for component processing */
  handlers?: (componentPath: string) => Handler[];
  
  /** Modify extracted component documentation */
  updateDocs?: (docs: PropsObject, file: string) => PropsObject;
  
  /** Custom prop sorting function */
  sortProps?: (props: PropDescriptor[]) => PropDescriptor[];
  
  /** Transform example before processing */
  updateExample?: (props: any, resourcePath: string) => any;
}

const { resolver } = require('react-docgen');

module.exports = {
  // Custom props parser
  propsParser: (filePath, code, resolver, handlers) => {
    // Custom parsing logic
    return require('react-docgen').parse(code, resolver, handlers);
  },
  
  // Custom component resolver
  resolver: resolver.findAllComponentDefinitions,
  
  // Custom handlers
  handlers: (componentPath) => {
    const defaultHandlers = require('react-docgen').defaultHandlers;
    return [
      ...defaultHandlers,
      // Add custom handler
      (documentation, path) => {
        // Custom documentation extraction
      }
    ];
  },
  
  // Modify extracted docs
  updateDocs: (docs, file) => {
    // Add custom metadata
    docs.customMetadata = {
      fileName: path.basename(file),
      lastModified: fs.statSync(file).mtime
    };
    return docs;
  },
  
  // Custom prop sorting
  sortProps: (props) => {
    return props.sort((a, b) => {
      // Required props first
      if (a.required && !b.required) return -1;
      if (!a.required && b.required) return 1;
      // Then alphabetical
      return a.name.localeCompare(b.name);
    });
  }
};