@livestorm/ui-vue 2.0.1 → 2.0.3

package/README.md

@@ -11,37 +11,43 @@
 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.
 
-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";
@@ -58,116 +64,80 @@ Then import the library base styles once (body defaults, transitions, animations
 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
+## App setup
 
-All components are available as named exports. Example:
-
-```ts
-import { UiInput, UiInputSelect } from '@livestorm/ui-vue'
-```
-
-Or import a specific component directly:
-
-```ts
-import UiDialog from '@livestorm/ui-vue/src/components/UiDialog'
-```
-
-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
-
-Beyond the Tailwind CSS setup above, one runtime plugin must be registered when you create the app. `@livestorm/ui-vue/responsive` installs the `$responsive` global that layout components (`UiPage`, the toast layout) read; without it those components won't render correctly.
+No runtime plugin is required. Create your app, import components, done:
 
 ```ts
 import { createApp } from 'vue'
-import Responsive from '@livestorm/ui-vue/responsive'
 import { registerComponents } from '@livestorm/ui-vue/components-vite'
 import '@livestorm/ui-vue/style'
 import App from './App.vue'
 
 const app = createApp(App)
 
-app.use(Responsive)        // provides $responsive (required by UiPage, toasts)
 registerComponents(app)    // optional: register all Ui* components globally
 
 app.mount('#app')
 ```
 
-The overlay components (dialogs, dropdowns, menus, popovers, tooltips) render through client-only teleports; under SSR they hydrate on the client 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. Overlay components (dialogs, dropdowns, menus, popovers, tooltips) render through client-only teleports and hydrate with no extra setup.
 
-### Storybook
+<details>
+<summary>Optional: customizing the responsive breakpoints</summary>
 
-Interactive documentation and playground for all components.
+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:
 
-```bash
-# From the ui-vue package directory
-pnpm dev:storybook
+```ts
+import Responsive from '@livestorm/ui-vue/responsive'
 
+app.use(Responsive, {
+  computed: {
+    mobile: state => state.width < 900, // override the built-in flag
+  },
+})
 ```
 
-Visit http://localhost:6006 after starting.
+</details>
 
-## Testing
+## Using components
 
-We use Vitest for unit/component tests.
+Every component is a named export:
 
-```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
+```ts
+import { UiButton, UiTextField, UiInputSelect } from '@livestorm/ui-vue'
+```
 
+```vue
+<template>
+  <UiButton variant="cta" color="primary" icon="i-ls-check">
+    Click me
+  </UiButton>
+</template>
 ```
 
-> Minimum 95% coverage required.
-> See CONTRIBUTING.md for writing good tests.
+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/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.