chore: 🤖 distribution unbundled

.changeset/chatty-chairs-drop.md

@@ -0,0 +1,13 @@
+---
+"@clickhouse/click-ui": minor
+---
+
+Makes the distributed files "unbundled", effectively moving optimisation to a consumer app concern, e.g. obfuscation, compression, bundling MUST be consumer concerns, the library SHOULD NOT make the consumer bundling process more difficult, it MUST facilitate it! It resolves cyclic imports or circular dependencies, enhances linting to prevent imports from barrel files, making the barrel files more of a public API than an internal API to help prevent circular dependencies.
+
+From now on, bundling preserves the file tree, externalises packages based on the package.json dependency declaration automatically, instead of managing them manually as the current version does. It allows deep imports, e.g. @clickhouse/click-ui/components/Button.
+
+Exports files are placed by target resolution, e.g. dist/esm|cjs. It has removed UMD until further notice (why is the original version providing UMD, what's the use-case?). As a component library, in principle, it should be ESM and CJS (due to NodeJS SSR) compatible in the worse case scenarios.
+
+It reduces build times from > 1 minute to < 22 seconds.
+
+More importantly, this initial revision provides tree-shaking support, helping reduce file size. Which can now be assessed with an optional builder feature to analyse and visualise the package dependency graph, file sizes, etc.

.gitignore

@@ -8,6 +8,7 @@ storybook-static
 **/.DS_Store
 vite.config.ts.timestamp*
 .storybook/out
+tmp/*
 
 .yarn/*
 !.yarn/releases

README.md

@@ -28,6 +28,11 @@ You can find the official docs for the Click UI design system and component libr
 * [Storybook](#storybook)
   - [Stories development server](#stories-development-server)
   - [Public static site](#public-static-site)
+* [Distribution](#distribution)
+  - [Build](#build)
+  - [Use Click UI](#use-click-ui)
+  - [Deep imports support](#deep-imports-support)
+  - [Examples](#examples)
 * [Assets Management](#assets-management)
   - [Add a new SVG logo or icon](#add-new-svg-logo-or-icon)
 * [Releases and Versions](#releases-and-versions)
@@ -96,6 +101,7 @@ You can start the Storybook development server by:
 yarn dev
 ```
 
+
 We do NOT maintain a separate development environment; our Storybook stories serve as the source of truth for component implementation.
 
 > [!IMPORTANT]
@@ -142,7 +148,6 @@ Once ready, you can run tests by:
 ```sh
 yarn test:chromatic
 ```
-
 > [!NOTE]
 > Chromatic does NOT generate a report in the terminal due to its cloud nature, which only outputs:
 > - Build status, e.g. uploading or testing
@@ -179,50 +184,12 @@ Once built, you can serve the static files by:
 yarn storybook:serve
 ```
 
-### Public static site
+### Public Static Site
 
 The latest static version's built and deployed automatically when contributing to `main` of [Click UI](https://github.com/ClickHouse/click-ui).
 
 Once deployed it's available publicly at [clickhouse.design/click-ui](https://clickhouse.design/click-ui).
 
-## How-to use
-
-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 that's done, you'll be able to import the individual components that you want to use on each page. Here's an example of an `App.tsx` in NextJS.
-
-```typescript
-import { ClickUIProvider, Text, ThemeName, Title, Switch } from '@clickhouse/click-ui'
-import { useState } from 'react'
-
-function App() {
-  const [theme, setTheme] = useState<ThemeName>('dark')
-
-  const toggleTheme = () => {
-    theme === 'dark' ? setTheme('light') : setTheme('dark')
-  }
-
-  return (
-    <ClickUIProvider theme={theme} config={{tooltip:{ delayDuration: 0 }}}>
-      <Switch 
-        checked={theme === 'dark'} 
-        onCheckedChange={() => toggleTheme()} 
-        label="Dark mode"
-      />
-
-      <Title type='h1'>Click UI Example</Title>
-      <Text>Welcome to Click UI. Get started here.</Text>
-    </ClickUIProvider>
-  )
-}
-
-export default App
-```
-
 ## Changeset
 
 Learn to manage the versioning of changelog entries.
@@ -269,6 +236,107 @@ To consume all changesets, and update to the most appropriate semver version and
 yarn changeset:version
 ```
 
+## Distribution
+
+The package is distributed as ESM.
+
+### Build
+
+To build the distribution version of the package run:
+
+```sh
+yarn build
+```
+
+> [!NOTE]
+> Optimizations are responsability of consumer or host apps, e.g. they can't remove unused code if already minified it! We ship unminified code so their build tools can: analyse and remove what they don't need or dead code, debug more easily, compress everything together in one go instead of handling conflicting compression algorithms, etc.
+
+### Use Click UI
+
+Navigate to your app's work directory and add the package.
+
+Here, we use `yarn` but you can use your favorite package manager, e.g. pnpm.
+
+```sh
+yarn add @clickhouse/click-ui
+```
+> [!NOTE]
+> Click UI should be supported by react frameworks.
+> If you run into any issues consuming it in your react app, report it [here](https://github.com/ClickHouse/click-ui/issues/new). Provide all important details, including information on how to replicate the issue!
+
+Once installed, wrap the application with Click UI provider:
+
+```js
+import { ClickUIProvider } from '@clickhouse/click-ui'
+
+export default () => {
+  return (
+    <ClickUIProvider theme='light'>
+      <p>Hello world!</p>
+    </ClickUIProvider>
+  );
+}
+```
+
+After, you are able to import your favorite [Click UI components](https://clickhouse.design/click-ui).
+
+```js
+import { ClickUIProvider, Title } from '@clickhouse/click-ui'
+
+export default () => {
+  return (
+    <ClickUIProvider theme='light'>
+      <Title type='h1'>Click UI Example</Title>
+    </ClickUIProvider>
+  );
+}
+```
+
+To learn more about individual components, visit [Click UI components](https://clickhouse.design/click-ui).
+
+### Deep imports support
+
+Deep imports are supported, you can import directly from path.
+
+> [!WARNING]
+> At time of writing, there are components that consume from theme provider, which means that these will fail when unwrapped. This will change in future versions.
+
+```ts
+import { Button } from '@clickhouse/click-ui/Button';
+```
+
+### Examples
+
+Here's a quick copy and paste NextJS example with interactive components you can play:
+
+```ts
+import { ClickUIProvider, Text, ThemeName, Title, Switch } from '@clickhouse/click-ui'
+import { useState } from 'react'
+
+function App() {
+  const [theme, setTheme] = useState<ThemeName>('dark')
+
+  const toggleTheme = () => {
+    theme === 'dark' ? setTheme('light') : setTheme('dark')
+  }
+
+  return (
+    <ClickUIProvider theme={theme} config={{tooltip:{ delayDuration: 0 }}}>
+      <Switch 
+        checked={theme === 'dark'} 
+        onCheckedChange={() => toggleTheme()} 
+        label="Dark mode"
+      />
+
+      <Title type='h1'>Click UI Example</Title>
+      <Text>Welcome to Click UI. Get started here.</Text>
+    </ClickUIProvider>
+  )
+}
+
+export default App
+```
+
 ## Assets management
 
 The Click UI has image asset files, such as icons or logos.

eslint.config.js

@@ -77,6 +77,23 @@ export default tseslint.config(
           tsx: 'never',
         },
       ],
+      'no-restricted-imports': [
+        'error',
+        {
+          paths: [
+            {
+              name: '@/components',
+              message:
+                'Do not import from the components barrel inside the library. Import from leaf modules (e.g., ../Icon/Icon) to avoid cycles.',
+            },
+            {
+              name: '@/index',
+              message:
+                'Do not import from the package entry internally. Import from leaf modules instead.',
+            },
+          ],
+        },
+      ],
       '@typescript-eslint/no-deprecated': 'warn',
     },
   },

package.json

@@ -7,35 +7,36 @@
   "files": [
     "dist"
   ],
+  "main": "./dist/cjs/index.cjs",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "sideEffects": false,
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/click-ui.es.js",
-      "require": "./dist/click-ui.umd.js"
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.cjs"
     },
-    "./bundled": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/click-ui.bundled.es.js",
-      "require": "./dist/click-ui.bundled.umd.js"
+    "./*": {
+      "types": "./dist/types/*.d.ts",
+      "import": "./dist/esm/*.js",
+      "require": "./dist/cjs/*.cjs"
     }
   },
-  "main": "./dist/click-ui.umd.js",
-  "module": "./dist/click-ui.es.js",
-  "types": "./dist/index.d.ts",
   "keywords": [
     "click-ui",
     "clickhouse",
     "design system"
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/ClickHouse/click-ui.git"
+    "url": "git+https://github.com/ClickHouse/click-ui.git"
   },
   "homepage": "https://clickhouse.com",
   "scripts": {
-    "build": "tsc && vite build && yarn build:bundled",
+    "build": "yarn typecheck && vite build",
+    "build:analyze": "ANALYZE=true vite build",
     "build-storybook": "storybook build",
-    "build:bundled": "vite build -- bundled",
     "build:watch": "watch 'yarn build' ./src",
     "changeset:add": "yarn changeset",
     "changeset:status": "yarn changeset status",
@@ -81,7 +82,8 @@
     "@radix-ui/react-tabs": "1.1.1",
     "@radix-ui/react-toast": "1.2.2",
     "@radix-ui/react-tooltip": "1.1.2",
-    "lodash": "^4.17.21",
+    "dayjs": "1.11.19",
+    "lodash-es": "^4.17.23",
     "react-sortablejs": "^6.1.4",
     "react-syntax-highlighter": "^16.1.0",
     "react-virtualized-auto-sizer": "^1.0.20",
@@ -102,7 +104,7 @@
     "@testing-library/user-event": "^14.5.2",
     "@tokens-studio/sd-transforms": "^1.2.0",
     "@types/eslint-plugin-react-refresh": "^0.4.0",
-    "@types/lodash-es": "^4.17.7",
+    "@types/lodash-es": "^4.17.12",
     "@types/node": "^24.10.1",
     "@types/react": "18.3.1",
     "@types/react-dom": "18.3.1",
@@ -115,7 +117,6 @@
     "babel-plugin-styled-components": "^2.1.4",
     "chromatic": "^13.3.4",
     "date-fns": "4.1.0",
-    "dayjs": "1.11.13",
     "eslint": "^9",
     "eslint-import-resolver-typescript": "^4.4.4",
     "eslint-plugin-import": "^2.32.0",
@@ -130,6 +131,7 @@
     "prop-types": "^15.8.1",
     "react": "18.3.1",
     "react-dom": "18.3.1",
+    "rollup-plugin-visualizer": "^6.0.5",
     "storybook": "^10.1.10",
     "storybook-addon-pseudo-states": "^10.1.10",
     "style-dictionary": "^5.0.0",
@@ -139,6 +141,8 @@
     "typescript-eslint": "^8",
     "vite": "^7.3.0",
     "vite-plugin-dts": "^4.3.0",
+    "vite-plugin-externalize-deps": "^0.10.0",
+    "vite-tsconfig-paths": "^6.0.5",
     "vitest": "^2.1.8",
     "watch": "^1.0.2"
   },

src/components/Accordion/Accordion.tsx

@@ -1,7 +1,10 @@
 import * as RadixAccordion from '@radix-ui/react-accordion';
 import { styled } from 'styled-components';
 import { IconSize } from '@/components/Icon/types';
-import { Icon, IconName, Spacer, Text } from '@/components';
+import { Icon } from '@/components/Icon/Icon';
+import { IconName } from '@/components/Icon/types';
+import { Spacer } from '@/components/Spacer/Spacer';
+import { Text } from '@/components/Typography/Text/Text';
 import { ReactNode } from 'react';
 
 type Size = 'sm' | 'md' | 'lg';

src/components/Alert/Alert.stories.tsx

@@ -1,6 +1,8 @@
 import { Meta, StoryObj } from '@storybook/react-vite';
 
-import { Alert, Container, Link } from '@/components';
+import { Alert } from '@/components/Alert/Alert';
+import { Container } from '@/components/Container/Container';
+import { Link } from '@/components/Link/Link';
 import { ICON_NAMES } from '@/components/Icon/IconCommon';
 
 const meta: Meta<typeof Alert> = {

src/components/Alert/Alert.tsx

@@ -1,4 +1,4 @@
-import { Icon } from '@/components';
+import { Icon } from '@/components/Icon/Icon';
 import { IconName } from '@/components/Icon/types';
 import { useState, ReactNode, useCallback } from 'react';
 import { styled } from 'styled-components';

src/components/AutoComplete/AutoComplete.test.tsx

@@ -1,5 +1,6 @@
 import { act, fireEvent } from '@testing-library/react';
-import { AutoComplete, AutoCompleteProps } from '@/components';
+import { AutoComplete } from '@/components/AutoComplete/AutoComplete';
+import type { AutoCompleteProps } from '@/components/AutoComplete/AutoComplete';
 import { renderCUI } from '@/utils/test-utils';
 import { selectOptions } from '../Select/selectOptions';
 describe('AutoComplete', () => {