chore(css-modules): 🤖 support local visual regression testing via docker

.changeset/eight-colts-accept.md

@@ -0,0 +1,13 @@
+---
+'@clickhouse/click-ui': minor
+---
+
+This library will now use CSS Modules for styling and because it's distributed unbundled, gives the consumer application full control over bundling and optimisations. You'll only include what you actually use, resulting in smaller bundle sizes and better performance!
+
+**Migration:**
+
+Your bundler must be configured to handle `.module.css` imports from `node_modules`. Most popular bundlers (Vite, webpack, Parcel, Rollup with appropriate plugins) support CSS Modules by default or with minimal configuration.
+
+NOTE: We're currently migrating from Styled-Components to CSS Modules. Some components may still use Styled-Components during the transition period.
+
+To learn more about CSS modules support, check our documentation [here](https://github.com/ClickHouse/click-ui?tab=readme-ov-file#css-modules)

.dockerignore

@@ -0,0 +1,23 @@
+node_modules
+
+dist
+.storybook/out
+storybook-static
+
+playwright-report
+test-results
+
+.git
+.gitignore
+
+.idea
+.vscode
+*.swp
+*.swo
+
+.DS_Store
+Thumbs.db
+
+*.log
+*.md
+!README.md

.gitignore

@@ -14,10 +14,11 @@ tmp/*
 !.yarn/releases
 !.yarn/plugins
 
-**.ts-snapshots
 tests/**/*-actual.png
 tests/**/*-diff.png
+tests/**/*-darwin.png
 test-results
+playwright-report
 
 .install
 .vscode

.llm/CONVENTIONS.md

@@ -27,6 +27,26 @@ export interface ComponentProps extends React.HTMLAttributes<HTMLElement> {
 - Use transient props (prefixed with `$`) for styled-component internal state
 - Use `data-*` attributes for styling hooks instead of generated class names
 
+### CSS Modules (BEM Naming)
+
+When using CSS Modules (migration in progress from styled-components):
+
+- **Follow BEM naming convention**:
+  - `.button` - Block (component root)
+  - `.button__icon` - Element (child of block, use double underscore)
+  - `.button--primary` - Modifier (variant/state, use double dash)
+  - `.button--primary:hover` - State pseudo-classes
+
+- **Example structure**:
+  ```css
+  .button { /* base styles */ }
+  .button__icon { /* icon element */ }
+  .button--primary { /* primary variant */ }
+  .button--primary:focus-visible { /* keyboard focus state */ }
+  ```
+- Use CSS custom properties from theme tokens: `var(--click-button-basic-color-primary-background-default)`
+- Always include `:focus-visible` styles for keyboard accessibility, never use `outline: none` without replacement
+
 ### Accessibility (Mandatory)
 
 - Interactive elements need `role`, `aria-label`, `aria-describedby`

.scripts/bash/playwright-docker

@@ -0,0 +1,36 @@
+#!/bin/bash
+
+COMMAND="${1:-test}"
+
+PORT="8282"
+
+if [[ "$COMMAND" = "update" ]]; then
+  docker compose \
+    -f docker-compose.playwright.yml \
+    run \
+    --rm update-snapshots
+elif [[ "$COMMAND" = "ui" ]]; then
+  docker rm -f playwright-ui 2>/dev/null
+
+  echo "🎭 Starting Playwright UI at http://localhost:$PORT..."
+
+  (sleep 3 &&
+    open "http://localhost:$PORT" 2>/dev/null ||
+    xdg-open "http://localhost:$PORT" 2>/dev/null) &
+
+  docker compose \
+      -f docker-compose.playwright.yml \
+      run \
+      --rm \
+      --service-ports \
+      --name playwright-ui \
+      ui
+elif [[ "$COMMAND" = "report" ]]; then
+  npx playwright show-report
+else
+  docker compose \
+    -f docker-compose.playwright.yml \
+    run \
+    --rm \
+    test
+fi

.scripts/js/generate-tokens.js

@@ -1,7 +1,9 @@
 import { register } from '@tokens-studio/sd-transforms';
 import StyleDictionary from 'style-dictionary';
+import config from '../../src/theme/theme.config.json' with { type: 'json' };
 
 const themes = ['dark', 'light'];
+const THEME_DATA_ATTRIBUTE = `data-${config.storageKey}`;
 
 await register(StyleDictionary);
 
@@ -17,6 +19,38 @@ StyleDictionary.registerTransform({
   },
 });
 
+StyleDictionary.registerTransform({
+  type: 'name',
+  name: 'name/cti/kebab',
+  transform: (token, options) => {
+    if (options.prefix && options.prefix.length) {
+      return [options.prefix].concat(token.path).join('-');
+    } else {
+      return token.path.join('-');
+    }
+  },
+});
+
+StyleDictionary.registerFormat({
+  name: 'css/themed-variables',
+  format: function ({ dictionary, file }) {
+    const themeName = file.destination.replace('tokens-', '').replace('.css', '');
+    const tokens = dictionary.allTokens
+      .map(token => {
+        const varName = token.path.join('-');
+        const cleanValue = String(token.value).replace(/;+$/, '');
+        return `  --${varName}: ${cleanValue};`;
+      })
+      .join('\n');
+
+    if (themeName === 'light') {
+      return `:root,\n[${THEME_DATA_ATTRIBUTE}="light"] {\n${tokens}\n}`;
+    } else {
+      return `[${THEME_DATA_ATTRIBUTE}="dark"] {\n${tokens}\n}`;
+    }
+  },
+});
+
 StyleDictionary.registerFormat({
   name: 'typescript/es6-theme',
   format: function ({ dictionary, file }) {
@@ -46,10 +80,7 @@ StyleDictionary.registerFormat({
 
 for (const theme of themes) {
   const sd = new StyleDictionary({
-    source: [
-      `./tokens/**/!(${themes.join('|')}).json`,
-      `./tokens/**/${theme}.json`,
-    ],
+    source: [`./tokens/**/!(${themes.join('|')}).json`, `./tokens/**/${theme}.json`],
     preprocessors: ['tokens-studio'],
     platforms: {
       ts: {
@@ -63,6 +94,17 @@ for (const theme of themes) {
           },
         ],
       },
+      css: {
+        transformGroup: 'tokens-studio',
+        transforms: ['name/cti/kebab'],
+        buildPath: 'src/theme/styles/',
+        files: [
+          {
+            destination: `tokens-${theme}.css`,
+            format: 'css/themed-variables',
+          },
+        ],
+      },
     },
   });
 

.storybook/main.ts

@@ -32,9 +32,10 @@ const config: StorybookConfig = {
   },
 
   async viteFinal(config, { configType }) {
-    // Workaround for Storybook 10.0.7 bug where MDX files generate file:// imports
-    // See: https://github.com/storybookjs/storybook/issues (mdx-react-shim resolution)
-    config.plugins = config.plugins || [];
+    config.plugins = (config.plugins || []).filter((plugin) => {
+      const pluginName = plugin && typeof plugin === 'object' && 'name' in plugin ? plugin.name : null;
+      return pluginName !== 'css-external';
+    });
     config.plugins.push({
       name: 'fix-storybook-mdx-shim',
       resolveId(source) {

.storybook/preview.tsx

@@ -1,15 +1,15 @@
-import { useState, useEffect, ReactNode } from 'react';
-import type { Preview } from '@storybook/react-vite';
-import { Decorator } from '@storybook/react-vite';
-import { styled } from 'styled-components';
-import { themes } from 'storybook/theming';
-import { ClickUIProvider } from '@/providers';
+import { useState, useEffect, ReactNode } from "react";
+import type { Preview } from "@storybook/react-vite";
+import { Decorator } from "@storybook/react-vite";
+import { styled } from "styled-components";
+import { themes } from "storybook/theming";
+import { ClickUIProvider } from "../src/providers";
 
 const ThemeBlock = styled.div<{ $left?: boolean; $bfill?: boolean }>(
   ({ $left, $bfill: fill, theme }) => `
       position: absolute;
       top: 0.5rem;
-      left: ${$left || fill ? 0 : '50vw'};
+      left: ${$left || fill ? 0 : "50vw"};
       right: 0;
       height: fit-content;
       bottom: 0;
@@ -22,26 +22,28 @@ const ThemeBlock = styled.div<{ $left?: boolean; $bfill?: boolean }>(
 
 export const globalTypes = {
   theme: {
-    name: 'Theme',
-    description: 'Global theme for components',
-    defaultValue: 'system',
+    name: "Theme",
+    description: "Global theme for components",
+    defaultValue: "system",
     toolbar: {
-      icon: 'circlehollow',
+      icon: "circlehollow",
       items: [
-        { value: 'system', icon: 'browser', title: 'system' },
-        { value: 'dark', icon: 'moon', title: 'dark' },
-        { value: 'light', icon: 'sun', title: 'light' },
+        { value: "system", icon: "browser", title: "system" },
+        { value: "dark", icon: "moon", title: "dark" },
+        { value: "light", icon: "sun", title: "light" },
       ],
       showName: true,
     },
   },
 };
 
-const getSystemTheme = (): 'dark' | 'light' => {
-  if (typeof window !== 'undefined' && window.matchMedia) {
-    return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+const getSystemTheme = (): "dark" | "light" => {
+  if (typeof window !== "undefined" && window.matchMedia) {
+    return window.matchMedia("(prefers-color-scheme: dark)").matches
+      ? "dark"
+      : "light";
   }
-  return 'dark';
+  return "dark";
 };
 
 interface ThemeWrapperProps {
@@ -50,27 +52,24 @@ interface ThemeWrapperProps {
 }
 
 const ThemeWrapper = ({ themeSelection, children }: ThemeWrapperProps) => {
-  const [systemTheme, setSystemTheme] = useState<'dark' | 'light'>(getSystemTheme);
+  const [systemTheme, setSystemTheme] = useState<"dark" | "light">(getSystemTheme);
 
   // Listen for system theme changes
   useEffect(() => {
-    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+    const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
     const handleChange = () => {
-      setSystemTheme(mediaQuery.matches ? 'dark' : 'light');
+      setSystemTheme(mediaQuery.matches ? "dark" : "light");
     };
-    mediaQuery.addEventListener('change', handleChange);
-    return () => mediaQuery.removeEventListener('change', handleChange);
+    mediaQuery.addEventListener("change", handleChange);
+    return () => mediaQuery.removeEventListener("change", handleChange);
   }, []);
 
   // Resolve the actual theme: handle "system" and fallback for undefined/null
   const theme =
-    themeSelection === 'system' || !themeSelection ? systemTheme : themeSelection;
+    themeSelection === "system" || !themeSelection ? systemTheme : themeSelection;
 
   return (
-    <ClickUIProvider
-      theme={theme}
-      config={{ tooltip: { delayDuration: 0 } }}
-    >
+    <ClickUIProvider theme={theme} config={{ tooltip: { delayDuration: 0 } }}>
       <ThemeBlock $left>{children}</ThemeBlock>
     </ClickUIProvider>
   );
@@ -91,22 +90,22 @@ const preview: Preview = {
   parameters: {
     options: {
       storySort: {
-        method: 'alphabetical',
+        method: "alphabetical",
         order: [
-          'Introduction',
-          'Buttons',
-          'Cards',
-          'Layout',
-          'Forms',
-          'Display',
-          'Sidebar',
-          'Typography',
-          'Colors',
-          ['Title', 'Text', 'Link'],
+          "Introduction",
+          "Buttons",
+          "Cards",
+          "Layout",
+          "Forms",
+          "Display",
+          "Sidebar",
+          "Typography",
+          "Colors",
+          ["Title", "Text", "Link"],
         ],
       },
     },
-    actions: { argTypesRegex: '^on[A-Z].*' },
+    actions: { argTypesRegex: "^on[A-Z].*" },
     controls: {
       matchers: {
         color: /(background|color)$/i,

Dockerfile.playwright

@@ -0,0 +1,13 @@
+FROM mcr.microsoft.com/playwright:v1.58.2-noble
+
+WORKDIR /app
+
+RUN corepack enable && corepack prepare yarn@4.5.3 --activate
+
+COPY package.json yarn.lock .yarnrc.yml ./
+
+RUN yarn install
+
+COPY . .
+
+CMD ["yarn", "test:visual"]