@enonic/ui 1.1.1 → 1.2.0

package/README.md

@@ -1,16 +1,22 @@
 # @enonic/ui
 
-A modern UI component library built with Preact/React, TypeScript, and Tailwind CSS.
+[![npm](https://img.shields.io/npm/v/@enonic/ui.svg)](https://www.npmjs.com/package/@enonic/ui)
+[![CI](https://github.com/enonic/npm-enonic-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/enonic/npm-enonic-ui/actions/workflows/ci.yml)
+[![License](https://img.shields.io/npm/l/@enonic/ui.svg)](LICENSE)
 
-## Installation
+UI components for Preact and React, styled with Tailwind CSS v4. Components ship with keyboard navigation, focus management, and ARIA wiring; theming runs on CSS custom properties with a light and a dark palette.
 
-#### With React
+**[Browse the components →](https://enonic.github.io/npm-enonic-ui/)** Every component and variant, live, with props tables and accessibility checks.
+
+## Quick start
+
+**1. Install** — with React:
 
 ```bash
 pnpm add @enonic/ui react react-dom @radix-ui/react-slot
 ```
 
-#### With Preact
+…or with Preact:
 
 ```bash
 pnpm add @enonic/ui preact @radix-ui/react-slot
@@ -19,39 +25,51 @@ pnpm add @enonic/ui preact @radix-ui/react-slot
 <details>
 <summary><b>npm</b></summary>
 
-#### With React
-
 ```bash
-npm install @enonic/ui react react-dom @radix-ui/react-slot
+npm install @enonic/ui react react-dom @radix-ui/react-slot  # React
+npm install @enonic/ui preact @radix-ui/react-slot            # Preact
 ```
 
-#### With Preact
+</details>
 
-```bash
-npm install @enonic/ui preact @radix-ui/react-slot
+**2. Load the styles.** Components use Tailwind utility classes and render unstyled until a stylesheet is present. The prebuilt one needs no configuration:
+
+```css
+/* your app's entry CSS */
+@import '@enonic/ui/style.css';
 ```
 
-</details>
+Already running Tailwind v4? Use the [Tailwind setup](#tailwind-v4-setup) instead — it shares one utility build with your app and lets your theme overrides through.
 
-> Some components and styling paths need extra packages — `focus-trap-react` (dialogs and overlays), `react-virtuoso` (virtualized lists), and `tw-animate-css` (the Tailwind styling path). See [Peer Dependencies](#peer-dependencies).
+**3. Render something.**
 
-## Usage
+```tsx
+import { Button, Input } from '@enonic/ui';
 
-### Styles
+function App() {
+  return (
+    <>
+      <Input label='Project' placeholder='Search projects' />
+      <Button variant='filled' size='md'>
+        Search
+      </Button>
+    </>
+  );
+}
+```
 
-> **Important**: Components are styled with Tailwind CSS utility classes and render unstyled until you load the CSS. Pick one of the two paths below.
+## Styles
 
-#### Option A — No Tailwind (prebuilt stylesheet)
+Two paths. Pick by whether your app already runs Tailwind:
 
-Import the fully compiled stylesheet. It bundles Tailwind's output, the design tokens, and component animations — nothing else to configure:
+| Your app                      | Import                  | Trade-off                                                         |
+| ----------------------------- | ----------------------- | ----------------------------------------------------------------- |
+| No Tailwind                   | `@enonic/ui/style.css`  | Zero config, ships Tailwind's output for the components           |
+| Tailwind CSS v4 (recommended) | `@enonic/ui/preset.css` | One shared utility build, your theme overrides apply, smaller CSS |
 
-```css
-@import '@enonic/ui/style.css';
-```
+### Tailwind v4 setup
 
-#### Option B — Your own Tailwind CSS (recommended)
-
-If your project already runs **Tailwind CSS v4**, integrate the design tokens through `preset.css` so components share your Tailwind build — one set of utilities, your theme overrides apply, and a smaller bundle. A working setup needs all of the following:
+Import the tokens through `preset.css` and point Tailwind at the package. All four pieces are needed:
 
 ```css
 /* Declare layer order first so your own overrides win over component styles */
@@ -60,19 +78,19 @@ If your project already runs **Tailwind CSS v4**, integrate the design tokens th
 @import 'tailwindcss/theme.css' layer(theme);
 @import 'tailwindcss/preflight.css' layer(base);
 @import '@enonic/ui/preset.css'; /* design tokens, dark variant, base + custom utilities */
-@import 'tw-animate-css'; /* component enter/exit animations (required — see below) */
+@import 'tw-animate-css'; /* component enter/exit animations */
 @import 'tailwindcss/utilities.css' layer(utilities);
 
-/* Let Tailwind scan @enonic/ui's compiled files for the classes its components use.
-   The path is relative to THIS file — adjust the number of ../ to reach node_modules. */
+/* Relative to THIS file — adjust the ../ depth to reach node_modules */
 @source '../node_modules/@enonic/ui';
 ```
 
-> **`@source` is mandatory.** Tailwind v4 only generates the utilities it finds in scanned sources, and it ignores `node_modules` by default. The classes used inside `@enonic/ui` components live in its compiled output, so without `@source` pointing at the package those utilities are never generated and components render unstyled.
+> [!IMPORTANT]
+> `@source` is mandatory. Tailwind v4 generates only the utilities it finds in scanned sources, and it skips `node_modules` by default. Without this line the component classes are never generated and everything renders unstyled.
 
-> **`tw-animate-css` is required on this path.** Components such as `Dialog`, `Toast`, and `Tooltip` emit `animate-in` / `fade-*` / `zoom-*` classes from [`tw-animate-css`](https://www.npmjs.com/package/tw-animate-css), which `preset.css` does not include. Install it (`pnpm add tw-animate-css`) and import it as shown. The prebuilt `style.css` already inlines these, so Option A doesn't need it.
+`tw-animate-css` is also required on this path: `Dialog`, `Toast`, and `Tooltip` emit `animate-in` / `fade-*` / `zoom-*` classes that `preset.css` does not include. Install it with `pnpm add tw-animate-css`. The prebuilt `style.css` already inlines them.
 
-If you don't need explicit layer control, the shorthand also works:
+Without explicit layer control, the shorthand works too:
 
 ```css
 @import 'tailwindcss';
@@ -81,36 +99,19 @@ If you don't need explicit layer control, the shorthand also works:
 @source '../node_modules/@enonic/ui';
 ```
 
-#### CSS exports
+### CSS exports
 
-| Export                     | Contents                                                              | Use when                          |
-| -------------------------- | --------------------------------------------------------------------- | --------------------------------- |
-| `@enonic/ui/style.css`     | Fully compiled — Tailwind output + tokens + animations                | You don't run Tailwind (Option A) |
-| `@enonic/ui/preset.css`    | Design tokens (`@theme`), dark variant, base styles, custom utilities | You run Tailwind (Option B)       |
-| `@enonic/ui/tokens.css`    | Design tokens + dark variant only                                     | Tokens without base/utilities     |
-| `@enonic/ui/base.css`      | Root font size + base text color                                      | Granular composition              |
-| `@enonic/ui/utilities.css` | Custom `@utility` definitions (shimmer, `scrollbar-none`, …)          | Granular composition              |
+| Export                     | Contents                                                              | Use when                      |
+| -------------------------- | --------------------------------------------------------------------- | ----------------------------- |
+| `@enonic/ui/style.css`     | Fully compiled — Tailwind output + tokens + animations                | You don't run Tailwind        |
+| `@enonic/ui/preset.css`    | Design tokens (`@theme`), dark variant, base styles, custom utilities | You run Tailwind v4           |
+| `@enonic/ui/tokens.css`    | Design tokens + dark variant only                                     | Tokens without base/utilities |
+| `@enonic/ui/base.css`      | Root font size + base text color                                      | Granular composition          |
+| `@enonic/ui/utilities.css` | Custom `@utility` definitions (shimmer, `scrollbar-none`, …)          | Granular composition          |
 
-### Import Components
+## Dark mode
 
-```tsx
-import { Button, Input } from '@enonic/ui';
-
-function App() {
-  return (
-    <div>
-      <Button variant='primary' size='md'>
-        Click Me
-      </Button>
-      <Input placeholder='Enter text...' />
-    </div>
-  );
-}
-```
-
-### Dark Mode
-
-The library ships light and dark themes as CSS variables, switched by a class. Add `dark` to a root element (or a shadow-DOM host) and every token updates:
+Both themes ship as CSS variables, switched by a class. Add `dark` to a root element and every token updates:
 
 ```html
 <html class="dark">
@@ -119,48 +120,62 @@ The library ships light and dark themes as CSS variables, switched by a class. A
 ```
 
 ```ts
-// Toggle at runtime
 document.documentElement.classList.toggle('dark', isDark);
 ```
 
-The variant is defined as `@custom-variant dark (&:where(.dark, .dark *))` and also matches `:host(.dark)` for web-component hosts. Use the `dark:` variant in your own markup as usual.
+The variant is `@custom-variant dark (&:where(.dark, .dark *))`, so `dark:` matches `.dark` and anything inside it. Use it in your own markup as usual.
+
+Inside a shadow root the document's theme does not reach in, even though custom properties cross the boundary: the adopted sheet declares the light tokens on `:host`, and a declaration on the host beats a value inherited into it. Mount through `AppRoot` and let it switch — `<AppRoot theme='dark' stylesheets={sheets}>`. `theme='light'` emits nothing, being the state a root is already in. A `dark` class on the host works too, since `:host(.dark)` outranks `:host`, but it leaves your own `dark:` utilities unmatched because `.dark *` cannot see an ancestor in the outer tree; the class `AppRoot` places sits inside the root, and it mirrors it onto the portal layer so overlays follow. `stylesheets` expects constructed sheets: on Tailwind v4 your own compiled CSS, which already carries the package's tokens and utilities via `preset.css` and `@source`; without Tailwind the prebuilt sheet from `@enonic/ui/style` (`getStyleSheet()`, or `styleText` for the raw text). Not both, and never `tokens.css`/`utilities.css`, which are Tailwind source entries.
 
-### Icons
+## Icons
 
-Icons used internally by components are bundled — no icon library install is required for components to render.
+Icons used inside components are bundled — no icon package is needed for components to render.
 
-You only need a Lucide package when you pass a custom icon to a component that accepts one (e.g. `Tab`, `Link`, and `VirtualizedTreeList` expose an `icon` prop):
+A Lucide package is needed only when you pass your own icon to a component that takes one, such as the `icon` prop on `Tab`, `Link`, or `VirtualizedTreeList`:
 
 ```tsx
 import { Tab } from '@enonic/ui';
-import { Star } from 'lucide-react'; // React
-// import { Star } from 'lucide-preact'; // Preact
+import { Star } from 'lucide-react'; // lucide-preact in Preact projects
 
 <Tab icon={Star} label='Favorites' />;
 ```
 
-Use `lucide-react` in React projects and `lucide-preact` in Preact projects — the `icon` prop accepts either.
+The `icon` prop accepts either package.
 
-## Peer Dependencies
+## Requirements
 
-Installing `@enonic/ui` surfaces any unmet peers with the exact ranges it needs (defined in `package.json` — the source of truth).
+`package.json` holds the exact ranges — installing surfaces any unmet peer.
 
-**Required**
+| Requirement                                     | Notes                               |
+| ----------------------------------------------- | ----------------------------------- |
+| `@radix-ui/react-slot`                          | Required — backs the `asChild` prop |
+| `react` + `react-dom` v19, **or** `preact` v10+ | Pick one framework                  |
+| Tailwind CSS v4                                 | Only for the `preset.css` path      |
 
-- `@radix-ui/react-slot` — backs the `asChild` prop used across components
+Optional peers, needed per feature:
 
-…plus one framework:
+| Package            | Needed for                                        |
+| ------------------ | ------------------------------------------------- |
+| `focus-trap-react` | Focus management in `Dialog` and other overlays   |
+| `react-virtuoso`   | `VirtualizedTreeList` and other virtualized lists |
+| `tw-animate-css`   | Component animations on the `preset.css` path     |
 
-| React                       | Preact          |
-| --------------------------- | --------------- |
-| `react` + `react-dom` (v19) | `preact` (v10+) |
+## What's exported
 
-**Optional** — add only if you use the related feature:
+Beyond the components, the package entry re-exports the hooks that drive them (roving tabindex, type-ahead, floating position, scroll lock, and more), the bundled icon set, context providers, shared types, and the `cn` class-merge helper.
 
-- `focus-trap-react` — focus management for `Dialog` and other overlay components
-- `react-virtuoso` — required by `VirtualizedTreeList` and other virtualized lists
-- `tw-animate-css` — component animations when integrating through `preset.css` (see [Styles](#styles))
+```tsx
+import { Button, cn, useControlledState } from '@enonic/ui';
+```
+
+## Development
+
+```bash
+pnpm dev         # Storybook on :6006
+pnpm check:fix   # format + lint, then typecheck
+pnpm build       # library + CSS into dist/
+```
 
 ## License
 
-MIT
+Apache-2.0 — see [LICENSE](LICENSE).