chore: 🤖 initial css modules setup

.changeset/eight-colts-accept.md

@@ -0,0 +1,9 @@
+---
+'@clickhouse/click-ui': minor
+---
+
+This library will now use CSS Modules for styling and is distributed unbundled, giving your application full control over bundling and optimisations. This means you only include what you actually use, resulting in smaller bundle sizes and better performance!
+
+NOTE: We're currently migrating from Styled-Components to CSS Modules. Some components may still use Styled-Components during this 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)

README.md

@@ -31,6 +31,7 @@ You can find the official docs for the Click UI design system and component libr
 * [Distribution](#distribution)
   - [Build](#build)
   - [Use Click UI](#use-click-ui)
+  - [CSS Modules](#css-modules)
   - [Deep imports support](#deep-imports-support)
   - [Examples](#examples)
 * [Themes](#themes)
@@ -316,6 +317,39 @@ export default () => {
 
 To learn more about individual components, visit [Click UI components](https://clickhouse.design/click-ui).
 
+### CSS Modules
+
+This library uses [CSS Modules](https://github.com/css-modules/css-modules) for styling and is distributed unbundled, giving your application full control over bundling and optimizations. This means you only include what you actually use, resulting in smaller bundle sizes and better performance!
+
+Most modern React frameworks support CSS Modules out of the box, including Next.js, Vite, Create React App, and TanStack Start, with no configuration required.
+
+> [!NOTE]
+> We're currently migrating from Styled-Components to CSS Modules. Some components may still use Styled-Components during this transition period.
+#### Benefits
+
+CSS Modules align naturally with component-level imports. When you import a component like `Button`, its `Button.module.css` is automatically included. If you don't use the component, neither the JavaScript, or CSS will be bundled in your application's output. Only the necessary stylesheets will be included in the output bundle.
+
+#### Custom Build Configurations
+
+Although most modern React setups have CSS Modules built-in, if your build tool doesn't support it by default, you'll need to configure it.
+
+Let's assume you have an old Webpack setup. Here's an example of how that'd look like:
+
+```js
+{
+  test: /\.module\.css$/,
+  use: [
+    'style-loader',
+    {
+      loader: 'css-loader',
+      options: { modules: true }
+    }
+  ]
+}
+```
+
+For other bundlers, refer to their documentation on CSS Modules configuration.
+
 ### Deep imports support
 
 Deep imports are supported, you can import directly from path.

package.json

@@ -146,6 +146,7 @@
     "vite": "^7.3.0",
     "vite-plugin-dts": "^4.3.0",
     "vite-plugin-externalize-deps": "^0.10.0",
+    "vite-plugin-static-copy": "^3.2.0",
     "vite-tsconfig-paths": "^6.0.5",
     "vitest": "^2.1.8",
     "watch": "^1.0.2"

src/components/Button/Button.module.css

@@ -0,0 +1 @@
+.demoCSSModuleSetupOnlyDeleteAfter {}

src/components/Button/Button.tsx

@@ -5,6 +5,8 @@ import { styled, keyframes } from 'styled-components';
 import { BaseButton } from '../commonElement';
 import React from 'react';
 
+import styles from './Button.module.css';
+
 export type ButtonType = 'primary' | 'secondary' | 'empty' | 'danger';
 type Alignment = 'center' | 'left';
 
@@ -42,6 +44,7 @@ export const Button = ({
   ...delegated
 }: ButtonProps) => (
   <StyledButton
+    className={styles.demoCSSModuleSetupOnlyDeleteAfter}
     $styleType={type}
     $align={align}
     $fillWidth={fillWidth}

src/components/DateDetails/DateDetails.test.tsx

@@ -1,18 +1,16 @@
 import { DateDetails } from '@/components/DateDetails/DateDetails';
 import { renderCUI } from '@/utils/test-utils';
-import { fireEvent } from '@testing-library/dom';
+import { fireEvent } from '@testing-library/react';
 
 describe('DateDetails', () => {
   const actualTZ = process.env.TZ;
 
   beforeAll(() => {
-    global.ResizeObserver = vi.fn(() => {
-      return {
-        observe: vi.fn(),
-        unobserve: vi.fn(),
-        disconnect: vi.fn(),
-      };
-    });
+    global.ResizeObserver = vi.fn(() => ({
+      observe: vi.fn(),
+      unobserve: vi.fn(),
+      disconnect: vi.fn(),
+    }));
 
     process.env.TZ = 'America/New_York';
   });
@@ -22,11 +20,11 @@ describe('DateDetails', () => {
   });
 
   it('renders the DateDetails component with relevant timezone information', () => {
-    const baseDate = new Date('2024-12-24 11:45:00 AM');
+    const baseDate = new Date('2024-12-24T11:45:00');
     const systemTimeZone = 'America/Los_Angeles';
     vi.setSystemTime(baseDate);
 
-    const fiveMinutesAgo = new Date('2024-12-24 11:40:00 AM');
+    const fiveMinutesAgo = new Date('2024-12-24T11:40:00');
 
     const { getByText } = renderCUI(
       <DateDetails
@@ -39,52 +37,36 @@ describe('DateDetails', () => {
     expect(trigger).toBeInTheDocument();
 
     fireEvent.click(trigger);
-    expect(
-      getByText(content => {
-        return content.includes('EST');
-      })
-    ).toBeInTheDocument();
-    expect(
-      getByText(content => {
-        return content.includes('PST');
-      })
-    ).toBeInTheDocument();
+
+    expect(getByText(/Dec 24, 11:40 a\.m\..*(EST|GMT-5)/)).toBeInTheDocument();
+    expect(getByText(/Dec 24, 8:40 a\.m\..*(PST|GMT-8)/)).toBeInTheDocument();
     expect(getByText('Dec 24, 4:40 p.m.')).toBeInTheDocument();
-    expect(getByText('Dec 24, 11:40 a.m. (EST)')).toBeInTheDocument();
-    expect(getByText('Dec 24, 8:40 a.m. (PST)')).toBeInTheDocument();
-    expect(getByText(fiveMinutesAgo.getTime() / 1000)).toBeInTheDocument();
+    expect(getByText(String(fiveMinutesAgo.getTime() / 1000))).toBeInTheDocument();
   });
 
   it('allows for not passing in a system timezone', () => {
-    const baseDate = new Date('2024-12-24 11:45:00 AM');
+    const baseDate = new Date('2024-12-24T11:45:00');
     vi.setSystemTime(baseDate);
 
-    const fiveMinutesAgo = new Date('2024-12-24 11:40:00 AM');
+    const fiveMinutesAgo = new Date('2024-12-24T11:40:00');
 
     const { getByText, queryByText } = renderCUI(<DateDetails date={fiveMinutesAgo} />);
 
     const trigger = getByText('5 minutes ago');
-    expect(trigger).toBeInTheDocument();
-
     fireEvent.click(trigger);
-    expect(
-      getByText(content => {
-        return content.includes('EST');
-      })
-    ).toBeInTheDocument();
 
+    expect(getByText(/Dec 24, 11:40 a\.m\..*(EST|GMT-5)/)).toBeInTheDocument();
     expect(getByText('Dec 24, 4:40 p.m.')).toBeInTheDocument();
-    expect(getByText('Dec 24, 11:40 a.m. (EST)')).toBeInTheDocument();
     expect(queryByText('System')).not.toBeInTheDocument();
-    expect(getByText(fiveMinutesAgo.getTime() / 1000)).toBeInTheDocument();
+    expect(getByText(String(fiveMinutesAgo.getTime() / 1000))).toBeInTheDocument();
   });
 
   it("only shows the date if the previous date isn't in this year", () => {
-    const baseDate = new Date('2025-02-07 11:45:00 AM');
+    const baseDate = new Date('2025-02-07T11:45:00');
     const systemTimeZone = 'America/Los_Angeles';
     vi.setSystemTime(baseDate);
 
-    const oneYearAgo = new Date('2024-02-07 11:45:00 AM');
+    const oneYearAgo = new Date('2024-02-07T11:45:00');
 
     const { getByText } = renderCUI(
       <DateDetails
@@ -94,21 +76,20 @@ describe('DateDetails', () => {
     );
 
     const trigger = getByText('1 year ago');
-    expect(trigger).toBeInTheDocument();
-
     fireEvent.click(trigger);
+
     expect(getByText('Feb 7, 2024, 4:45 p.m.')).toBeInTheDocument();
-    expect(getByText('Feb 7, 2024, 11:45 a.m. (EST)')).toBeInTheDocument();
-    expect(getByText('Feb 7, 2024, 8:45 a.m. (PST)')).toBeInTheDocument();
-    expect(getByText(oneYearAgo.getTime() / 1000)).toBeInTheDocument();
+    expect(getByText(/Feb 7, 2024, 11:45 a\.m\..*(EST|GMT-5)/)).toBeInTheDocument();
+    expect(getByText(/Feb 7, 2024, 8:45 a\.m\..*(PST|GMT-8)/)).toBeInTheDocument();
+    expect(getByText(String(oneYearAgo.getTime() / 1000))).toBeInTheDocument();
   });
 
   it('handles Daylight Savings Time', () => {
-    const baseDate = new Date('2024-07-04 11:45:00 AM');
+    const baseDate = new Date('2024-07-04T11:45:00');
     const systemTimeZone = 'America/Los_Angeles';
     vi.setSystemTime(baseDate);
 
-    const fiveMinutesAgo = new Date('2024-07-04 11:40:00 AM');
+    const fiveMinutesAgo = new Date('2024-07-04T11:40:00');
 
     const { getByText } = renderCUI(
       <DateDetails
@@ -118,22 +99,11 @@ describe('DateDetails', () => {
     );
 
     const trigger = getByText('5 minutes ago');
-    expect(trigger).toBeInTheDocument();
-
     fireEvent.click(trigger);
-    expect(
-      getByText(content => {
-        return content.includes('EDT');
-      })
-    ).toBeInTheDocument();
-    expect(
-      getByText(content => {
-        return content.includes('PDT');
-      })
-    ).toBeInTheDocument();
+
+    expect(getByText(/Jul 4, 11:40 a\.m\..*(EDT|GMT-4)/)).toBeInTheDocument();
+    expect(getByText(/Jul 4, 8:40 a\.m\..*(PDT|GMT-7)/)).toBeInTheDocument();
     expect(getByText('Jul 4, 3:40 p.m.')).toBeInTheDocument();
-    expect(getByText('Jul 4, 11:40 a.m. (EDT)')).toBeInTheDocument();
-    expect(getByText('Jul 4, 8:40 a.m. (PDT)')).toBeInTheDocument();
-    expect(getByText(fiveMinutesAgo.getTime() / 1000)).toBeInTheDocument();
+    expect(getByText(String(fiveMinutesAgo.getTime() / 1000))).toBeInTheDocument();
   });
 });

vite.config.ts

@@ -6,9 +6,17 @@ import dts from 'vite-plugin-dts';
 import { externalizeDeps } from 'vite-plugin-externalize-deps';
 import tsconfigPaths from 'vite-tsconfig-paths';
 import { visualizer } from 'rollup-plugin-visualizer';
+import { viteStaticCopy } from 'vite-plugin-static-copy';
 
 const srcDir = path.resolve(__dirname, 'src').replace(/\\/g, '/');
 
+// TODO: Find a solution for static files based on conf extensions
+const cssExternalPlugin = () => ({
+  name: 'css-external',
+  enforce: 'pre' as const,
+  resolveId: (id: string) => (id.endsWith('.module.css') ? { id, external: true } : null),
+});
+
 const buildOptions: BuildOptions = {
   target: 'esnext',
   emptyOutDir: true,
@@ -51,6 +59,7 @@ const buildOptions: BuildOptions = {
 const viteConfig = defineConfig({
   publicDir: false,
   plugins: [
+    cssExternalPlugin(),
     react({
       babel: {
         plugins: [['babel-plugin-styled-components', { displayName: false }]],
@@ -85,6 +94,37 @@ const viteConfig = defineConfig({
       useFile: path.join(process.cwd(), 'package.json'),
     }),
     tsconfigPaths(),
+    // TODO: Copying CSS Module files to both esm and cjs dist directories should have the target names, e.g. esm, cjs shared with bundled target, so that they're automatically sync.
+    viteStaticCopy({
+      targets: [
+        {
+          src: 'src/**/*.module.css',
+          dest: 'esm',
+          rename: (fileName: string, fileExt: string, srcPath: string) => {
+            const srcIndex = srcPath.indexOf('/src/');
+            const ext = fileExt.startsWith('.') ? fileExt : `.${fileExt}`;
+            if (srcIndex !== -1) {
+              const relativePath = srcPath.slice(srcIndex + 5, srcPath.lastIndexOf('/'));
+              return `${relativePath}/${fileName}${ext}`;
+            }
+            return `${fileName}${ext}`;
+          },
+        },
+        {
+          src: 'src/**/*.module.css',
+          dest: 'cjs',
+          rename: (fileName: string, fileExt: string, srcPath: string) => {
+            const srcIndex = srcPath.indexOf('/src/');
+            const ext = fileExt.startsWith('.') ? fileExt : `.${fileExt}`;
+            if (srcIndex !== -1) {
+              const relativePath = srcPath.slice(srcIndex + 5, srcPath.lastIndexOf('/'));
+              return `${relativePath}/${fileName}${ext}`;
+            }
+            return `${fileName}${ext}`;
+          },
+        },
+      ],
+    }),
     // WARNING: Keep the visualizer last
     ...(process.env.ANALYZE === 'true'
       ? [