@clickhouse/click-ui 0.0.234-sc-deprecation.3 → 0.0.234-sc-deprecation.5

package/README.md

@@ -6,35 +6,198 @@ 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
+
+1. **Install Click UI**
+   ```bash
+   npm install @clickhouse/click-ui
+   ```
+
+2. **Wrap your app with ClickUIProvider**
+
+   ```typescript
+   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>
+     )
+   }
+
+   export default App
+   ```
+
+### Customizing Your Theme
+
+To customize the theme with your own colors, spacing, and styles:
+
+1. **Initialize configuration**
+   ```bash
+   npx @clickhouse/click-ui init
+   ```
+
+   This creates a `click-ui.config.ts` file in your project root.
+
+2. **Setup Vite alias** to enable auto-discovery
+
+   In your `vite.config.ts`:
+   ```ts
+   import { defineConfig } from 'vite';
+   import path from 'path';
+
+   export default defineConfig({
+     resolve: {
+       alias: {
+         'click-ui-config': path.resolve(__dirname, './click-ui.config.ts'),
+       },
+     },
+   });
+   ```
+
+3. **Customize the generated config file**
+
+   ```typescript
+   import type { ThemeConfig } from '@clickhouse/click-ui/theme';
+
+   const config: ThemeConfig = {
+     theme: {
+       global: {
+         color: {
+           brand: '#FFCC00',
+           background: {
+             default: '#FFFFFF'
+           }
+         }
+       },
+       button: {
+         primary: {
+           background: {
+             default: '#FFCC00',
+             hover: '#FFD700'
+           }
+         }
+       }
+     }
+   };
+
+   export default config;
+   ```
+
+4. **That's it!** Your custom theme will be automatically loaded by ClickUIProvider.
+
+#### CLI Options
+
+```bash
+# Create TypeScript config (default)
+npx @clickhouse/click-ui init
+
+# Create JavaScript config
+npx @clickhouse/click-ui init -f js
+
+# Overwrite existing config
+npx @clickhouse/click-ui init --force
+```
+
+### Advanced Configuration Options
+
+The generated config file supports extensive customization:
+
+#### System Mode Overrides
+
+Define different styles for light and dark modes:
 
 ```typescript
-import { ClickUIProvider, Text, ThemeName, Title, Switch } from '@clickhouse/click-ui'
+const config: ThemeConfig = {
+  systemModeOverrides: {
+    light: {
+      global: {
+        color: {
+          background: { default: '#FFFFFF' }
+        }
+      }
+    },
+    dark: {
+      global: {
+        color: {
+          background: { default: '#0D1117' },
+          text: { default: '#F0F6FC' }
+        }
+      }
+    }
+  }
+};
+```
 
-function App() {
-  const [theme, setTheme] = useState<ThemeName>('dark')
+#### Component-Specific Styling
+
+Customize individual components:
 
-  const toggleTheme = () => {
-    theme === 'dark' ? setTheme('light') : setTheme('dark')
+```typescript
+const config: ThemeConfig = {
+  theme: {
+    button: {
+      space: { x: '1rem', y: '0.5rem' },
+      radii: { all: '0.375rem' },
+      primary: {
+        background: {
+          default: '#FFCC00',
+          hover: '#FFD700'
+        }
+      }
+    }
   }
+};
+```
+
+### Manual Theme Control
+
+You can manually control the theme at runtime:
+
+```typescript
+import { ClickUIProvider, useCUITheme, Switch } from '@clickhouse/click-ui'
+
+function ThemeToggle() {
+  const { themeName, toggleTheme } = useCUITheme();
 
   return (
-    <ClickUIProvider theme={theme} config={{tooltip:{ delayDuration: 0 }}}>
-      <Switch checked={theme === 'dark'} onClick={() => toggleTheme() } />
+    <Switch
+      checked={themeName === 'dark'}
+      onClick={toggleTheme}
+    />
+  );
+}
 
+function App() {
+  return (
+    <ClickUIProvider theme="dark">
+      <ThemeToggle />
       <Title type='h1'>Click UI Example</Title>
-      <Text>Welcome to Click UI. Get started here.</Text>
     </ClickUIProvider>
   )
 }
-
-export default App
 ```
 
+### How It Works
+
+1. **Config File**: Create `click-ui.config.ts` in your project root
+2. **Vite Alias**: The alias makes the config discoverable via `'click-ui-config'` import
+3. **Auto-Load**: `ClickUIProvider` automatically imports and applies your config
+4. **Runtime Override**: Props passed to `ClickUIProvider` can override the config
+
+### Troubleshooting
+
+**Config not loading?**
+- Verify the Vite alias is correctly set up in `vite.config.ts`
+- Ensure `click-ui.config.ts` is in your project root
+- Restart your dev server after adding the alias
+
+**TypeScript errors?**
+- Import types from: `import type { ThemeConfig } from '@clickhouse/click-ui/theme';`
+- Your IDE will provide autocomplete for all config options
+
 ## To develop this library locally 🚀
 
 1. Clone this repo, cd into the `click-ui` directory

package/bin/click-ui.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+
+import { initCommand } from './commands/init.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 === '--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
+  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/init.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const CONFIG_TEMPLATES = {
+  ts: `import type { ThemeConfig } from '@clickhouse/click-ui/theme';
+
+const config: ThemeConfig = {
+  cssPrefix: '--click',
+  storageKey: 'click-ui-theme',
+
+  theme: {
+    global: {
+      color: {
+        brand: '#FFCC00',
+        background: {
+          default: '#FFFFFF'
+        }
+      }
+    },
+    button: {
+      space: {
+        x: '1rem',
+        y: '0.5rem'
+      },
+      radii: {
+        all: '0.375rem'
+      }
+    }
+  },
+
+  systemModeOverrides: {
+    light: {
+      global: {
+        color: {
+          background: {
+            default: '#FFFFFF'
+          }
+        }
+      }
+    },
+    dark: {
+      global: {
+        color: {
+          background: {
+            default: '#0D1117'
+          },
+          text: {
+            default: '#F0F6FC'
+          }
+        }
+      }
+    }
+  }
+};
+
+export default config;
+`,
+  js: `/** @type {import('@clickhouse/click-ui/theme').ThemeConfig} */
+const config = {
+  cssPrefix: '--click',
+  storageKey: 'click-ui-theme',
+
+  theme: {
+    global: {
+      color: {
+        brand: '#FFCC00',
+        background: {
+          default: '#FFFFFF'
+        }
+      }
+    },
+    button: {
+      space: {
+        x: '1rem',
+        y: '0.5rem'
+      },
+      radii: {
+        all: '0.375rem'
+      }
+    }
+  },
+
+  systemModeOverrides: {
+    light: {
+      global: {
+        color: {
+          background: {
+            default: '#FFFFFF'
+          }
+        }
+      }
+    },
+    dark: {
+      global: {
+        color: {
+          background: {
+            default: '#0D1117'
+          },
+          text: {
+            default: '#F0F6FC'
+          }
+        }
+      }
+    }
+  }
+};
+
+export default config;
+`
+};
+
+export const initCommand = (options) => {
+  const format = options.format === 'js' ? 'js' : 'ts';
+  const filename = `click-ui.config.${format}`;
+  const targetPath = path.join(process.cwd(), filename);
+
+  // Check if config already exists
+  if (fs.existsSync(targetPath) && !options.force) {
+    console.error(`❌ ${filename} already exists. Use --force to overwrite.`);
+    process.exit(1);
+  }
+
+  // Write config file
+  try {
+    fs.writeFileSync(targetPath, CONFIG_TEMPLATES[format], 'utf-8');
+    console.log(`✅ Created ${filename}`);
+    console.log(`\n📝 Next steps:`);
+    console.log(`   1. Customize your theme in ${filename}`);
+    console.log(`   2. Add Vite alias to make config discoverable (vite.config.ts):`);
+    console.log(`\n      resolve: {`);
+    console.log(`        alias: {`);
+    console.log(`          'click-ui-config': path.resolve(__dirname, './${filename}'),`);
+    console.log(`        },`);
+    console.log(`      },`);
+    console.log(`\n   3. Use ClickUIProvider (config loads automatically):`);
+    console.log(`\n      import { ClickUIProvider } from '@clickhouse/click-ui';`);
+    console.log(`\n      <ClickUIProvider>`);
+    console.log(`        {/* Your app */}`);
+    console.log(`      </ClickUIProvider>`);
+    console.log(`\n   The config will be automatically discovered and applied! 🎨`);
+  } catch (error) {
+    console.error(`❌ Failed to create config file: ${error.message}`);
+    process.exit(1);
+  }
+};