@livestorm/ui-vue 2.0.2 → 2.0.4

package/README.md

@@ -11,37 +11,44 @@
 A modern, strongly-typed Vue 3 component library for Livestorm’s design system.
 </p>
 
+<p align="center">
+<a href="https://main--65bcc25b1bd5ef5d8b1a8505.chromatic.com/"><strong>Browse the components →</strong></a>
+</p>
 
 ## Table of Contents
 
-- [Introduction](#introduction)
-- [Usage](#usage)
-- [Importing Components](#importing-components)
-- [Storybook](#storybook)
-- [Testing](#testing)
-- [CI/CD](#cicd)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Tailwind CSS setup](#tailwind-css-setup)
+- [App setup](#app-setup)
+- [Using components](#using-components)
+- [Entry points](#entry-points)
 - [Contributing](#contributing)
-- [License](#license)
 
 ---
 
-## Introduction
-
-`ui-vue` provides a suite of reusable, accessible, and well-tested Vue 3 components, following Livestorm’s design system. It is built with Vue.js, TypeScript, Vitest, and Storybook.
+## Requirements
 
-## Usage
+- **Vue 3.5+**, a peer dependency provided by your app.
+- **vue-router 5+**, an optional peer dependency. Everything works without it — install it only if you use one of these router-aware features:
+  - the `to` prop on `UiButton`, `UiListItem`, `UiActionBarItem` and `UiSideMenu` items, which renders a `<router-link>` (each also accepts a plain `href` link instead);
+  - the `confirmTo` action of toasts (`confirmHref` is the plain-link alternative);
+  - the logo link of `UiPageHeader` when `showLogo` is enabled;
+  - the `@livestorm/ui-vue/utils` entry point: its `useRouteQueryModel` helper is built on the router, so importing this entry requires vue-router to be installed.
+- **Tailwind CSS 4**, since components are styled with Tailwind utility classes.
+- **The Inter font**, which components are designed for. The package never loads it for you: self-host it, or import the optional Google Fonts shortcut once (`import '@livestorm/ui-vue/fonts'`). Without Inter, components fall back to the system font stack.
 
-This package is used as a workspace dependency inside the `@livestorm/entropy` monorepo, and is also published to npm as [`@livestorm/ui-vue`](https://www.npmjs.com/package/@livestorm/ui-vue) for other Livestorm projects.
+Installing the package also pulls in `@livestorm/ui-tokens` (design tokens) and `@livestorm/ui-icons` (icon utilities).
 
-### Installation (outside the monorepo)
+## Installation
 
 ```bash
 pnpm add @livestorm/ui-vue
 ```
 
-This pulls in `@livestorm/ui-tokens` (design tokens) and `@livestorm/ui-icons` (icon utilities) as dependencies. `vue` (and `vue-router`, if you use router-aware components) are peer dependencies you provide.
+## Tailwind CSS setup
 
-The library is Tailwind CSS 4 based: components use Tailwind utility classes (including `i-ls-*` icon classes), so your app must run Tailwind and scan the library for classes. In your Tailwind entry CSS:
+Components use Tailwind utility classes (including the `i-ls-*` icon classes), so your app needs to run Tailwind and scan the library. In your Tailwind entry CSS:
 
 ```css
 @import "tailwindcss";
@@ -52,58 +59,20 @@ The library is Tailwind CSS 4 based: components use Tailwind utility classes (in
 @source "../node_modules/@livestorm/ui-vue/dist";
 ```
 
+> [!WARNING]
+> Components rely on the design-token utilities these two imports produce (`bg-actions-primary-idle`, `i-ls-*`, ...). Those class names live in the component code, not in the shipped stylesheet, so if your own theme resets the token namespace (for example `--color-*: initial` in an `@theme`), Tailwind silently stops generating them and components render unstyled — no error, no warning. Keep the Livestorm token imports alongside your palette instead of resetting all colors.
+
 Then import the library base styles once (body defaults, transitions, animations):
 
 ```ts
 import '@livestorm/ui-vue/style'
 ```
 
-The published package ships prebuilt ES modules (`dist/`), so no special bundler configuration is needed. The source is also included under `src/` if your Vite setup prefers compiling the components itself.
-
-### Local Import
-
-```ts
-import { UiButton } from '@livestorm/ui-vue'
-
-export default {
-  components: { UiButton }
-}
-```
-
-### Example
-
-```vue
-<template>
-  <UiButton variant="primary">Click me</UiButton>
-</template>
-```
-
-### Importing Components
-
-All components are available as named exports. Example:
-
-```ts
-import { UiInput, UiInputSelect } from '@livestorm/ui-vue'
-```
-
-Or import a specific component directly:
+The body defaults ship inside `@layer base`, so anything your app declares — layered or not — takes precedence over them.
 
-```ts
-import UiDialog from '@livestorm/ui-vue/src/components/UiDialog'
-```
+## App setup
 
-To register every component globally under its own name (`<UiButton>`, `<UiTag>`, …):
-
-```ts
-import { registerComponents } from '@livestorm/ui-vue/components-vite'
-
-registerComponents(app)          // registers UiButton, UiTag, ...
-registerComponents(app, 'Ls')    // optional custom prefix: LsButton, LsTag, ...
-```
-
-### App setup
-
-No runtime plugin is required: beyond the Tailwind CSS setup above, create the app and use components.
+No runtime plugin is required. Create your app, import components, done:
 
 ```ts
 import { createApp } from 'vue'
@@ -118,9 +87,12 @@ registerComponents(app)    // optional: register all Ui* components globally
 app.mount('#app')
 ```
 
-Layout components (`UiPage`, the toast layout) read the viewport from a shared responsive singleton that initializes itself on first use. Installing the `@livestorm/ui-vue/responsive` plugin is optional: do it only to customize the breakpoint flags (`mobile`, `tablet`, ...) or to expose `$responsive` to your own templates.
+Server-side rendering works out of the box: pages render with a desktop layout on the server, then adapt to the real screen size as soon as they load in the browser. No configuration and no hydration warnings. Overlay components (dialogs, dropdowns, menus, popovers, tooltips) render through client-only teleports and hydrate with no extra setup.
 
-Server-side rendering works out of the box: pages render with a desktop layout on the server, then adapt to the real screen size as soon as they load in the browser. No configuration and no hydration warnings.
+<details>
+<summary>Optional: customizing the responsive breakpoints</summary>
+
+Layout components read the viewport from a shared helper with sensible defaults. Install the responsive plugin only if you want to override the breakpoint flags, or read `$responsive` in your own templates:
 
 ```ts
 import Responsive from '@livestorm/ui-vue/responsive'
@@ -132,54 +104,68 @@ app.use(Responsive, {
 })
 ```
 
-The overlay components (dialogs, dropdowns, menus, popovers, tooltips) render through client-only teleports; under SSR they hydrate on the client with no extra setup.
+</details>
 
-### Storybook
+<details>
+<summary>Optional: plugging your own translations</summary>
 
-Interactive documentation and playground for all components.
+Components render a few built-in labels themselves (the dialog and banner close buttons, the "Copied!" tooltip, the side menu's "More"). Out of the box they come in English or French, picked from `<html lang>`. An app running [i18next](https://www.i18next.com/) with Livestorm's keys keeps control automatically; any other i18n stack can take over with a translator function:
 
-```bash
-# From the ui-vue package directory
-pnpm dev:storybook
+```ts
+import { setTranslator } from '@livestorm/ui-vue/integrations'
 
+setTranslator((key) => myI18n.t(`ui-vue.${key}`))
 ```
 
-Visit http://localhost:6006 after starting.
+On an SSR server rendering a locale per request, provide the translator on the app instance instead — `setTranslator` is process-wide state shared by concurrent requests:
 
-## Testing
+```ts
+import { UI_VUE_TRANSLATOR } from '@livestorm/ui-vue/integrations'
 
-We use Vitest for unit/component tests.
+app.provide(UI_VUE_TRANSLATOR, (key) => myI18n.t(`ui-vue.${key}`))
+```
 
-```bash
-# Run all tests just one time
-pnpm test:vitest
-# or watch mode (preferred for debugging)
-pnpm test:vitest:watch
-# regenerate snapshots
-pnpm test:vitest:updateSnapshots
+Return the key itself (or `null`) to fall back to the built-in labels. The keys used: `general_close`, `general_dialog_title`, `general_misc_copied-text`, `room_bottom-bar_controls-label_more`.
 
+</details>
+
+Every component is a named export:
+
+```ts
+import { UiButton, UiTextField, UiInputSelect } from '@livestorm/ui-vue'
 ```
 
-> Minimum 95% coverage required.
-> See CONTRIBUTING.md for writing good tests.
+```vue
+<template>
+  <UiButton variant="cta" color="primary" icon="i-ls-check">
+    Click me
+  </UiButton>
+</template>
+```
+
+Props, variants and events for each component are documented in the [hosted Storybook](https://main--65bcc25b1bd5ef5d8b1a8505.chromatic.com/), where every story is interactive. TypeScript definitions ship with the package, so editors autocomplete props and catch mistakes.
+
+If you registered components globally with `registerComponents(app)`, you can use `<UiButton>` in any template without importing it. A custom prefix is supported too:
 
-## CI/CD
+```ts
+registerComponents(app, 'Ls')    // <LsButton>, <LsTextField>, ...
+```
 
-#### Testing (ui-vue-test.yml):
-- Runs automatically on every pull request that modifies packages/ui-vue.
-- Installs dependencies, builds required packages, and runs all Vitest tests with coverage.
-- Posts test results as a GitHub Check, including whether tests passed or failed.
-- Ensures code quality before any code is merged.
+## Entry points
 
-#### Deployment (ui-vue-deploy.yml):
-- Triggers on pushes to main or when a pull request affecting ui-vue has the deploy-storybook label.
-- For PRs, checks if the label `deploy-storybook` is present. If not, deployment is skipped.
-- Verifies that all tests have passed before proceeding with deployment.
-- If conditions are met, builds and deploys the Storybook for ui-vue (typically to Chromatic or a static host).
-- Ensures only tested and reviewed code is deployed and that Storybook previews are available for review.
+| Import | Contents |
+| --- | --- |
+| `@livestorm/ui-vue` | All components and utilities |
+| `@livestorm/ui-vue/style` | Base stylesheet (import once) |
+| `@livestorm/ui-vue/fonts` | Optional: loads Inter from Google Fonts (skip it if you self-host) |
+| `@livestorm/ui-vue/components-vite` | `registerComponents` for global registration |
+| `@livestorm/ui-vue/integrations` | Toast helpers (`openToast`, ...) |
+| `@livestorm/ui-vue/layouts` | Layout components such as the toast container |
+| `@livestorm/ui-vue/utils` | Helpers (`useCopyToClipboard`, `useRouteQueryModel`, ...) — the one entry that requires `vue-router` |
+| `@livestorm/ui-vue/responsive` | Optional responsive plugin |
 
-Every code change is tested automatically. Storybook deployments for review are gated by a label and require passing tests, ensuring high confidence in merged and released code.
+The package ships prebuilt ES modules, so no special bundler configuration is needed. The original sources are included as well, if your setup prefers to compile the components itself.
 
 ## Contributing
 
-See CONTRIBUTING.md for guidelines, architecture, and best practices.
+This package lives in Livestorm's [entropy](https://github.com/livestorm/entropy) monorepo, under `packages/ui-vue`. See that directory's `CONTRIBUTING.md` for architecture, conventions and the release process.