@clickhouse/click-ui 0.0.235 → 0.0.237-sc-deprecation.1

package/README.md

@@ -6,35 +6,176 @@ The home of the ClickHouse design system and component library. Click UI is in v
 
 Click UI has been tested in NextJS, Gatsby, and Vite. If you run into problems using it in your app, please create an issue and our team will try to answer.
 
-1. Navigate to your app's route and run
-   `npm i @clickhouse/click-ui`
-   or
-   `yarn add @clickhouse/click-ui`
-2. Make sure to wrap your application in the Click UI `ClickUIProvider`, without doing this, you may run into issues with styled-components. Once thats done, you'll be able to import the individual components that you want to use on each page. Here's an example an `App.tsx` in NextJS.
+### Quick Start
 
-```typescript
-import { ClickUIProvider, Text, ThemeName, Title, Switch } from '@clickhouse/click-ui'
+1. **Install Click UI**
+   ```bash
+   npm install @clickhouse/click-ui
+   ```
+
+2. **Import the required styles**
+
+   Add these imports at the top of your main application file (before other styles):
+
+   **Option A: Simple (Recommended for most projects)**
+   ```typescript
+   // All-in-one: Includes both component styles and default theme
+   import '@clickhouse/click-ui/cui.css';
+   ```
+
+   **Option B: Granular (For custom theming)**
+   ```typescript
+   // Component styles only
+   import '@clickhouse/click-ui/cui-components.css';
+
+   // Default theme (light + dark with automatic switching)
+   import '@clickhouse/click-ui/cui-default-theme.css';
+
+   // OR import your custom theme instead:
+   // import './my-custom-theme.css';
+   ```
+
+   **Where to import:**
+   - **Next.js App Router**: Add to your root `layout.tsx`
+   - **Next.js Pages Router**: Add to `pages/_app.tsx`
+   - **Gatsby**: Add to `gatsby-browser.js`
+   - **Vite/React**: Add to `main.tsx` or `App.tsx`
+
+3. **Wrap your app with ClickUIProvider**
+
+   ```typescript
+   import '@clickhouse/click-ui/cui.css';
+   import { ClickUIProvider, Text, Title } from '@clickhouse/click-ui'
+
+   function App() {
+     return (
+       <ClickUIProvider>
+         <Title type='h1'>Click UI Example</Title>
+         <Text>Welcome to Click UI!</Text>
+       </ClickUIProvider>
+     )
+   }
 
-function App() {
-  const [theme, setTheme] = useState<ThemeName>('dark')
+   export default App
+   ```
 
-  const toggleTheme = () => {
-    theme === 'dark' ? setTheme('light') : setTheme('dark')
-  }
+### Customizing Your Theme
 
-  return (
-    <ClickUIProvider theme={theme} config={{tooltip:{ delayDuration: 0 }}}>
-      <Switch checked={theme === 'dark'} onClick={() => toggleTheme() } />
+Click UI supports extensive theming through a CLI-based approach:
 
-      <Title type='h1'>Click UI Example</Title>
-      <Text>Welcome to Click UI. Get started here.</Text>
-    </ClickUIProvider>
-  )
+#### Step 1: Create a config file
+
+```bash
+npx click-ui init
+```
+
+This creates a `click-ui.config.ts` file in your project root.
+
+#### Step 2: Customize your theme
+
+```typescript
+// click-ui.config.ts
+export default {
+  // Light mode theme tokens
+  theme: {
+    button: {
+      color: {
+        primary: {
+          'background-default': '#FF6B00',
+          'background-hover': '#FF8533',
+        }
+      }
+    }
+  },
+
+  // Dark mode overrides
+  dark: {
+    button: {
+      color: {
+        primary: {
+          'background-default': '#FF8533',
+          'background-hover': '#FFA366',
+        }
+      }
+    }
+  },
+
+  // Runtime configuration (optional)
+  storageKey: 'my-app-theme',
+  tooltipConfig: { delayDuration: 200 }
 }
+```
+
+#### Step 3: Generate your custom theme CSS
 
-export default App
+```bash
+npx click-ui generate
 ```
 
+This creates `cui-custom-theme.css` in your `public/` folder.
+
+#### Step 4: Import your custom theme instead of the default
+
+```typescript
+import '@clickhouse/click-ui/cui-components.css'; // Component styles only
+import './public/cui-custom-theme.css'; // Your custom theme
+import { ClickUIProvider } from '@clickhouse/click-ui'
+```
+
+**Resources:**
+- **[CLI Theme Generation](CLI_THEME_GENERATION.md)** - Complete CLI documentation
+- **[Theme System](src/theme/index.md)** - Runtime theming, hooks, and theme switching
+- **[Build-Time Configuration](BUILD_TIME_CONFIG_CLICK_UI.md)** - Theme config API reference
+
+---
+
+## How It Works
+
+Click UI uses a **pre-built CSS approach** for optimal performance:
+
+1. **CSS Files Generated at Build Time**
+   - Default theme included in the library (~10 KB)
+   - Custom themes generated via CLI
+   - Uses CSS `light-dark()` function for automatic theme switching
+
+2. **Minimal Runtime JavaScript**
+   - Provider only sets `data-theme` attribute (~600 bytes)
+   - Zero runtime CSS generation
+   - Instant theme switching via CSS attributes
+
+3. **Perfect Tree-Shaking**
+   - Import only the components you use
+   - Unused CSS automatically eliminated by your bundler
+   - Optimal bundle size
+
+### Theme Switching
+
+Themes are controlled via HTML attributes and CSS custom properties:
+
+```html
+<!-- Light mode -->
+<html data-theme="light">
+
+<!-- Dark mode -->
+<html data-theme="dark">
+
+<!-- System preference mode (automatic) -->
+<html data-theme="system">
+```
+
+All theme tokens are available as CSS variables with the `--click` prefix:
+
+```css
+.my-component {
+  background: var(--click-global-color-background-default);
+  color: var(--click-global-color-text-default);
+}
+```
+
+The provider automatically sets the theme attribute based on user preference and system settings.
+
+---
+
 ## To develop this library locally 🚀
 
 1. Clone this repo, cd into the `click-ui` directory

package/bin/README.md

@@ -0,0 +1,178 @@
+# Click UI CLI
+
+This directory contains the Click UI command-line interface for theme customization.
+
+## Quick Start
+
+```bash
+# Initialize a config file
+npx click-ui init
+
+# Generate custom theme CSS
+npx click-ui generate
+
+# Get help
+npx click-ui --help
+```
+
+## Commands
+
+### `click-ui init`
+
+Creates a `click-ui.config.ts` file in your project root with default configuration.
+
+**Options:**
+- `-f, --format <format>` - Config format: `js` or `ts` (default: `ts`)
+- `--force` - Overwrite existing config file
+- `-h, --help` - Display help
+
+**Example:**
+```bash
+npx click-ui init
+npx click-ui init --format js
+npx click-ui init --force
+```
+
+### `click-ui generate`
+
+Generates custom theme CSS from your `click-ui.config.ts` file.
+
+**Options:**
+- `-o, --output <path>` - Output file path (default: `public/cui-custom-theme.css`)
+- `-v, --verbose` - Show detailed output
+- `-w, --watch` - Watch for config changes and regenerate
+- `-h, --help` - Display help
+
+**Example:**
+```bash
+npx click-ui generate
+npx click-ui generate --output src/theme.css
+npx click-ui generate --watch
+```
+
+## Configuration
+
+See [click-ui.config.example.ts](./click-ui.config.example.ts) for a complete example configuration.
+
+### Basic Structure
+
+```typescript
+import type { ThemeConfig } from '@clickhouse/click-ui/theme';
+
+const config: ThemeConfig = {
+  // Light mode theme
+  theme: {
+    global: {
+      color: {
+        brand: '#FF6B6B',
+      }
+    }
+  },
+
+  // Dark mode overrides
+  dark: {
+    global: {
+      color: {
+        brand: '#FF8A80',
+      }
+    }
+  },
+
+  // Runtime configuration
+  storageKey: 'my-app-theme',
+};
+
+export default config;
+```
+
+## Workflow
+
+1. **Create config:**
+   ```bash
+   npx click-ui init
+   ```
+
+2. **Customize theme** in `click-ui.config.ts`:
+   ```typescript
+   theme: {
+     button: {
+       primary: {
+         background: { default: '#FF6B6B' }
+       }
+     }
+   }
+   ```
+
+3. **Generate CSS:**
+   ```bash
+   npx click-ui generate
+   ```
+
+4. **Import in your app:**
+   ```typescript
+   import '@clickhouse/click-ui/cui.css';
+   import './public/cui-custom-theme.css'; // Your custom theme
+   import { ClickUIProvider } from '@clickhouse/click-ui';
+   // OR for simple setup without custom theme:
+   // import '@clickhouse/click-ui/cui.css';
+
+   function App() {
+     return (
+       <ClickUIProvider>
+         {/* Your app */}
+       </ClickUIProvider>
+     );
+   }
+   ```
+
+## File Structure
+
+```
+bin/
+├── click-ui.js                    # CLI entry point
+├── click-ui.config.example.ts     # Example configuration
+├── commands/
+│   ├── init.js                    # Creates config file
+│   ├── generate.js                # Generates theme CSS
+│   └── build-default-theme.ts     # Internal: builds library's default theme
+└── utils/
+    └── css-generator.js           # CSS generation utilities
+```
+
+## TypeScript Support
+
+Full TypeScript support with autocomplete for theme configuration:
+
+```typescript
+import type { ThemeConfig } from '@clickhouse/click-ui/theme';
+
+const config: ThemeConfig = {
+  theme: {
+    // TypeScript autocomplete works here! ✨
+  }
+};
+```
+
+## CSS Output
+
+The CLI generates CSS using `light-dark()` functions for automatic theme switching:
+
+```css
+:root {
+  color-scheme: light dark;
+  --click-button-color-primary-background-default: light-dark(#FF6B6B, #FF8A80);
+}
+```
+
+This allows the browser to automatically switch between light and dark values based on the user's system preference or your theme setting.
+
+## Documentation
+
+For more information:
+- [Main README](../README.md) - Getting started
+- [Theme Documentation](../src/theme/index.md) - Theme configuration guide
+- [GitHub Repository](https://github.com/ClickHouse/click-ui)
+
+## License
+
+Apache-2.0

package/bin/click-ui.config.example.ts

@@ -0,0 +1,70 @@
+import type { ThemeConfig } from "@clickhouse/click-ui/theme";
+
+const config: ThemeConfig = {
+  storageKey: "click-ui-theme",
+
+  // Light mode theme (default)
+  theme: {
+    global: {
+      color: {
+        brand: "#FF6B6B",
+        background: {
+          default: "#FFFFFF",
+        },
+      },
+    },
+    button: {
+      space: {
+        x: "1.5rem",
+        y: "0.75rem",
+      },
+      radii: {
+        all: "0.5rem",
+      },
+      primary: {
+        background: {
+          default: "#FF6B6B",
+          hover: "#FF5252",
+        },
+      },
+    },
+  },
+
+  // Dark mode overrides - if not defined, theme values are used for dark mode too
+  dark: {
+    global: {
+      color: {
+        background: {
+          default: "#0D1117",
+        },
+        text: {
+          default: "#F0F6FC",
+        },
+      },
+    },
+    button: {
+      primary: {
+        background: {
+          default: "#FF8A80",
+          hover: "#FF7043",
+        },
+      },
+    },
+  },
+
+  // Tooltip configuration (optional)
+  // tooltipConfig: {
+  //   delayDuration: 100,
+  //   skipDelayDuration: 300,
+  //   disableHoverableContent: false,
+  // },
+
+  // Toast configuration (optional)
+  // toastConfig: {
+  //   duration: 4000,
+  //   swipeDirection: "right",
+  //   swipeThreshold: 50,
+  // },
+};
+
+export default config;

package/bin/click-ui.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+
+import { initCommand } from './commands/init.js';
+import { generateCommand } from './commands/generate.js';
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (command === 'init') {
+  const options = {
+    format: 'ts',
+    force: false
+  };
+
+  // Parse options
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === '-f' || args[i] === '--format') {
+      options.format = args[i + 1];
+      i++;
+    } else if (args[i] === '--force') {
+      options.force = true;
+    } else if (args[i] === '-h' || args[i] === '--help') {
+      console.log(`
+Usage: @clickhouse/click-ui init [options]
+
+Initialize Click UI configuration file
+
+Options:
+  -f, --format <format>  Config format (js or ts) (default: "ts")
+  --force                Overwrite existing config file
+  -h, --help             Display help for command
+      `);
+      process.exit(0);
+    }
+  }
+
+  initCommand(options);
+} else if (command === 'generate') {
+  const options = {
+    output: null,
+    verbose: false,
+    watch: false
+  };
+
+  // Parse options
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === '-o' || args[i] === '--output') {
+      options.output = args[i + 1];
+      i++;
+    } else if (args[i] === '-v' || args[i] === '--verbose') {
+      options.verbose = true;
+    } else if (args[i] === '-w' || args[i] === '--watch') {
+      options.watch = true;
+    } else if (args[i] === '-h' || args[i] === '--help') {
+      console.log(`
+Usage: @clickhouse/click-ui generate [options]
+
+Generate custom theme CSS from click-ui.config.ts/js
+
+Options:
+  -o, --output <path>  Output file path (default: "public/cui-custom-theme.css")
+  -v, --verbose        Show detailed output
+  -w, --watch          Watch for config changes and regenerate
+  -h, --help           Display help for command
+
+Example:
+  click-ui generate
+  click-ui generate --output src/theme.css
+  click-ui generate --watch
+      `);
+      process.exit(0);
+    }
+  }
+
+  generateCommand(options);
+} else if (command === '--version' || command === '-V') {
+  console.log('0.0.234');
+} else if (command === '--help' || command === '-h' || !command) {
+  console.log(`
+Usage: @clickhouse/click-ui [options] [command]
+
+CLI for ClickHouse Click UI
+
+Options:
+  -V, --version   Output the version number
+  -h, --help      Display help for command
+
+Commands:
+  init [options]      Initialize Click UI configuration file
+  generate [options]  Generate custom theme CSS from config
+  help [command]      Display help for command
+  `);
+} else {
+  console.error(`Unknown command: ${command}`);
+  console.log('Run "@clickhouse/click-ui --help" for usage information.');
+  process.exit(1);
+}

package/bin/commands/build-default-theme.ts

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+/**
+ * Generate theme-default.css with light-dark() functions
+ * This runs during library build to create pre-compiled CSS
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { getBaseTheme } from "../../src/theme/utils";
+import { generateLightDarkVariables, generateThemeOverrides } from "../../src/theme/utils/css-generator";
+import { buildCSSOutput } from "../../src/theme/utils/css-builder";
+
+// Load light and dark base themes from tokens
+const lightTheme = getBaseTheme("light");
+const darkTheme = getBaseTheme("dark");
+
+// Debug: Check if themes loaded correctly
+console.log("\n🔍 Debug Info:");
+console.log(`Light theme loaded: ${Object.keys(lightTheme).length} keys`);
+console.log(`Dark theme loaded: ${Object.keys(darkTheme).length} keys`);
+console.log(`Light accordion color: ${lightTheme?.click?.accordion?.color?.default?.label?.default}`);
+console.log(`Dark accordion color: ${darkTheme?.click?.accordion?.color?.default?.label?.default}`);
+
+// Generate CSS using the same logic as injectThemeStyles()
+const lightDarkVars = generateLightDarkVariables(lightTheme, darkTheme);
+const themeOverrides = generateThemeOverrides(lightTheme, darkTheme);
+
+// Build CSS using shared builder
+const css = buildCSSOutput(lightDarkVars, themeOverrides, {
+  headerComment: '/* Click UI Default Theme */\n/* Generated during library build - DO NOT EDIT MANUALLY */\n/* Uses light-dark() CSS function for automatic theme switching */\n'
+});
+
+// Ensure output directory exists
+const outputDir = path.join(process.cwd(), "src", "styles");
+if (!fs.existsSync(outputDir)) {
+  fs.mkdirSync(outputDir, { recursive: true });
+}
+
+// Write the CSS file
+const outputPath = path.join(outputDir, "cui-default-theme.css");
+fs.writeFileSync(outputPath, css, "utf-8");
+
+console.log(`✅ Generated cui-default-theme.css (${css.length} bytes)`);
+console.log(`   Location: ${outputPath}`);
+console.log(`   Light vars: ${Object.keys(lightDarkVars).length}`);
+console.log(`   Light overrides: ${Object.keys(themeOverrides.light).length}`);
+console.log(`   Dark overrides: ${Object.keys(themeOverrides.dark).length}`);

package/bin/commands/generate.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { pathToFileURL } from 'url';
+import { findConfigFile } from '../../src/theme/utils/find-config.js';
+import { loadConfig, validateConfig } from '../utils/config-loader.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Generate custom theme CSS from click-ui.config.ts/js
+ */
+export async function generateCommand(options = {}) {
+  const cwd = process.cwd();
+  const outputPath = options.output || path.join(cwd, 'public', 'cui-custom-theme.css');
+  const verbose = options.verbose || false;
+
+  console.log('🎨 Click UI Theme Generator\n');
+
+  try {
+    // Find config file
+    const configFile = findConfigFile(cwd);
+
+    if (!configFile) {
+      console.log('ℹ️  No click-ui.config.ts/js found');
+      console.log('   Run "click-ui init" to create a config file');
+      process.exit(0);
+    }
+
+    if (verbose) {
+      console.log(`📄 Found config: ${path.relative(cwd, configFile)}`);
+    }
+
+    // Load config
+    const config = await loadConfig(configFile);
+
+    if (!validateConfig(config)) {
+      console.log('⚠️  Config file exists but has no theme configuration');
+      console.log('   Add "theme" or "dark" properties to customize your theme');
+      process.exit(0);
+    }
+
+    // Generate CSS
+    const css = await generateCSS(config);
+
+    // Ensure output directory exists
+    const outputDir = path.dirname(outputPath);
+    if (!fs.existsSync(outputDir)) {
+      fs.mkdirSync(outputDir, { recursive: true });
+      if (verbose) {
+        console.log(`📁 Created directory: ${path.relative(cwd, outputDir)}`);
+      }
+    }
+
+    // Write CSS file
+    fs.writeFileSync(outputPath, css, 'utf-8');
+
+    console.log('✅ Generated custom theme CSS');
+    console.log(`   Location: ${path.relative(cwd, outputPath)}`);
+    console.log(`   Size: ${(css.length / 1024).toFixed(2)} KB\n`);
+
+    console.log('📝 Next steps:');
+    console.log('   1. Import the CSS in your app:');
+    console.log(`      import '${path.relative(cwd, outputPath).replace(/\\/g, '/')}';`);
+    console.log('   2. Or add to your HTML:');
+    console.log(`      <link rel="stylesheet" href="/${path.basename(outputPath)}">`);
+
+  } catch (error) {
+    console.error('❌ Failed to generate theme CSS:', error.message);
+    if (verbose) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+/**
+ * Generate CSS from config
+ */
+async function generateCSS(config) {
+  // Import the CSS generation function from bin/utils
+  const cssGeneratorPath = path.join(__dirname, '../utils/css-generator.js');
+
+  if (!fs.existsSync(cssGeneratorPath)) {
+    throw new Error('CSS generator module not found at ' + cssGeneratorPath);
+  }
+
+  const { generateThemeCSS } = await import(pathToFileURL(cssGeneratorPath).href);
+
+  // Get full config and generate CSS
+  const fullConfig = config.default || config;
+  const css = generateThemeCSS(fullConfig);
+
+  if (!css || css.length === 0) {
+    throw new Error('No CSS generated. Please check your theme configuration.');
+  }
+
+  return css;
+}
+
+/**
+ * Split config into build-time and runtime
+ */
+function splitConfig(fullConfig) {
+  const { theme, dark, ...runtimeConfig } = fullConfig;
+
+  return {
+    buildTimeConfig: {
+      ...(theme && { theme }),
+      ...(dark && { dark }),
+    },
+    runtimeConfig,
+  };
+}