@clickhouse/click-ui 0.0.251-test.72 → 0.0.252-rc.3

package/README.md

@@ -28,16 +28,6 @@ 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)
-* [Themes](#themes)
-  - [Prevent theme flash](#prevent-theme-flash)
-  - [Theme Persistence](#theme-persistence)
-* [Assets Management](#assets-management)
-  - [Add a new SVG logo or icon](#add-new-svg-logo-or-icon)
 * [Releases and Versions](#releases-and-versions)
 
 ## Requirements
@@ -89,7 +79,7 @@ It's expected to have theme tokens provided externally, e.g. Figma tokens-studio
 Once [./tokens/themes] files are updated, we must regenerate the tokens:
 
 ```sh
-yarn generate:tokens
+yarn generate-tokens
 ```
 
 Learn more about tokens-studio [here](https://documentation.tokens.studio/).
@@ -187,43 +177,23 @@ 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).
 
-## Distribution
+## How-to use
 
-The package is distributed as ESM.
+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.
 
-### Build
+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.
 
-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.
-
-### 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
+```typescript
 import { ClickUIProvider, Text, ThemeName, Title, Switch } from '@clickhouse/click-ui'
 import { useState } from 'react'
 
@@ -251,11 +221,6 @@ function App() {
 export default App
 ```
 
-> [!TIP]
-> An example of NextJS with Server Side Rendering (SSR) is available [here](/docs/examples/nextjs-app-router-with-ssr.md).
-
-To learn more about individual components, visit [Click UI components](https://clickhouse.design/click-ui).
-
 ## Changeset
 
 Learn to manage the versioning of changelog entries.
@@ -302,107 +267,6 @@ To consume all changesets, and update to the most appropriate semver version and
 yarn changeset:version
 ```
 
-## Themes
-
-Theming allows the end-user to select its preferred colour theme. You are responsible for managing your own theme state. Use your preferred state management solution (React state, Zustand, Redux, Context, etc.) and pass the current theme to the provider.
-
-> [!NOTE]
-> Currently, styling is done with css-in-js which might cause some flash since it has to compute the theme and apply it. We'll be moving from styled-components and this shall be changed and improved.
-
-### Prevent theme flash
-
-To prevent flash of incorrect theme, import the `InitCUIThemeScript` component and place it in the `<head>` of your HTML.
-
-The script reads the theme from localStorage and applies it immediately before React hydration to prevent flashing.
-
-```ts
-import { InitCUIThemeScript } from '@clickhouse/click-ui';
-```
-
-Simple usage (no props needed):
-
-```jsx
-<html>
-  <head>
-    <InitCUIThemeScript />
-  </head>
-  <body>
-    <ClickUIProvider theme={theme} persistTheme>
-      {children}
-    </ClickUIProvider>
-  </body>
-</html>
-```
-
-> [!NOTE]
-> On initial load, the component `InitCUIThemeScript` reads localStorage and applies the theme immediately before React hydration. When the theme changes the ClickUIProvider stores the new theme to localStorage (persistTheme must be enabled). Finally, when page loads/refreshes the process reads from the stored theme from localStorage.
-
-The process will check localStorage for a theme, e.g. in the key `cui-theme` and apply it immediately preventing flashing. Otherwise, if nothing's stored it'll fallback to the default value `light`.
-
-> [!IMPORTANT]
-> If you'd like to override the theme fallback when localStorage is empty, you can do it by setting a value for property `defaultTheme`, e.g. `dark`.
-
-### Theme Persistence
-
-To enable theme persistence across page reloads, enable `persistTheme` (default: `true`). The provider will automatically save theme changes to localStorage.
-
-Notice that we manage theme state in the consumer side:
-
-```tsx
-import { ClickUIProvider } from '@clickhouse/click-ui';
-import { useState } from 'react';
-
-export const App = () => {
-  const [theme, setTheme] = useState<'dark' | 'light'>('dark');
-
-  return (
-    <ClickUIProvider 
-      theme={theme}
-      persistTheme
-    >
-      <button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>
-        Switch to {theme === 'dark' ? 'Light' : 'Dark'} Mode
-      </button>
-    </ClickUIProvider>
-  );
-}
-```
-
-> [!TIP]
-> An example of NextJS with Server Side Rendering (SSR) is available [here](/docs/examples/nextjs-app-router-with-ssr.md), where you can see how the root `data-cui-theme` is handled.
-
-## Assets management
-
-The Click UI has image asset files, such as icons or logos.
-
-Files are originally curated in the context of the design system Figma project. Once exported/sourced from the Figma project file these have to be transformed into the Click UI desired format, e.g. an SVG as a React Component.
-
-### Add new SVG logo or icon
-
-Here are some steps, to help you transform the Figma asset into a React Component:
-
-1) In Figma project, select and export the target image/icon, e.g. these are generally contained in a square container (64x64)
-2) Store the file in your local file system in a memorable location
-3) Use a tool to transform SVG to React JSX, e.g. [react-svgr](https://react-svgr.com/playground/)
-4) Create a new file in `src/components/Logos`, e.g. name it by the company name
-5) Modify the `<svg>` node, it should set the size to 64x64 as the original Figma container:
-
-> [!NOTE]
-> Notice the viewBox values, it should contain the same values from the sourced file 64x64, e.g. "0 0 64 64", if it hasn't make sure you are exporting it correctly, or the original file has the correct container width and height
-```tsx
-<svg
-  width="64"
-  height="64"
-  viewBox="0 0 64 64"
-  fill="none"
-  xmlns="http://www.w3.org/2000/svg"
-  {...props}
->
-```
-
-6) Declare the new logo/icon in the Logos dark and light exporte files, e.g. `src/components/Logos/LogosDark.ts` and `src/components/Logos/LogosLight.ts`
-7) Finally, introduce the new icon/logo name in the types file located at `src/components/Logos/types.ts`
-
 ## Releases and Versions
 
 New versions and release notes are available at [GitHub Releases](https://github.com/ClickHouse/click-ui/releases).