@livestorm/ui-vue 1.1.2 → 2.0.0

package/README.md

@@ -1,51 +1,183 @@
-# Livestorm Vue Components Library
+<p align="center">
+<a href="https://livestorm.co">
+<img src="https://cdn.prod.website-files.com/60ad0f9314e628baa6971a76/60ec0b72995cde84f69dbd43_Logo-Livestorm-Primary.svg" height="60">
+</a>
+</p>
 
-## Install
+<h1 align="center">
+@livestorm/ui-vue
+</h1>
+<p align="center">
+A modern, strongly-typed Vue 3 component library for Livestorm’s design system.
+</p>
+
+
+## Table of Contents
+
+- [Introduction](#introduction)
+- [Usage](#usage)
+- [Importing Components](#importing-components)
+- [Storybook](#storybook)
+- [Testing](#testing)
+- [CI/CD](#cicd)
+- [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.
+
+## Usage
+
+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.
+
+### Installation (outside the monorepo)
 
 ```bash
-npm install @livestorm/ui-vue
+pnpm add @livestorm/ui-vue
 ```
 
-## Storybook
+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.
 
-All the components are described in our Storybook: <https://storybook.livestorm.co>
+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:
 
-## Usage
+```css
+@import "tailwindcss";
+@import "@livestorm/ui-tokens/output/supernova/index.css";
+@import "@livestorm/ui-icons/icons-tailwind-utilities.css";
+
+/* Generate the utility classes used by ui-vue components */
+@source "../node_modules/@livestorm/ui-vue/dist";
+```
+
+Then import the library base styles once (body defaults, transitions, animations):
 
-Import style:
+```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'
 
-```javascript
-import "@livestorm/ui-vue/dist/style.css";
+export default {
+  components: { UiButton }
+}
 ```
 
-Use components in your Vue files:
+### Example
 
-```html
+```vue
 <template>
-  <div>
-    <LsButton class="base-button-primary"> Hello World </LsButton>
-
-    <LsCheckbox
-      :value="true"
-      label="My label"
-      for-id="my-id"
-      tooltip="My tooltip"
-    />
-  </div>
+  <UiButton variant="primary">Click me</UiButton>
 </template>
+```
+
+### Importing Components
+
+All components are available as named exports. Example:
 
-<script>
-  import { LsButton, LsCheckbox } from "@livestorm/ui-vue";
+```ts
+import { UiInput, UiInputSelect } from '@livestorm/ui-vue'
+```
+
+Or import a specific component directly:
 
-  export default {
-    components: {
-      LsButton,
-      LsCheckbox,
-    },
-  };
-</script>
+```ts
+import UiDialog from '@livestorm/ui-vue/src/components/UiDialog'
 ```
 
-## Compatibility
+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, two runtime plugins 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.
+- **`floating-vue`** backs the tooltips on `UiButton`, `UiLabel`, `UiFieldWrapper` and `UiInputCheckbox` (the `v-tooltip` directive). Install it alongside the library and import its stylesheet:
+
+  ```bash
+  pnpm add floating-vue
+  ```
+
+```ts
+import { createApp } from 'vue'
+import FloatingVue from 'floating-vue'
+import 'floating-vue/dist/style.css'
+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)
+app.use(FloatingVue)       // enables v-tooltip on UiButton, UiLabel, UiFieldWrapper, UiInputCheckbox
+registerComponents(app)    // optional: register all Ui* components globally
+
+app.mount('#app')
+```
+
+The overlay components (dialogs, dropdowns, menus, popovers) render through client-only teleports; under SSR they hydrate on the client with no extra setup.
+
+### Storybook
+
+Interactive documentation and playground for all components.
+
+```bash
+# From the ui-vue package directory
+pnpm dev:storybook
+
+```
+
+Visit http://localhost:6006 after starting.
+
+## Testing
+
+We use Vitest for unit/component tests.
+
+```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
+
+```
+
+> Minimum 95% coverage required.
+> See CONTRIBUTING.md for writing good tests.
+
+## CI/CD
+
+#### 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.
+
+#### 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.
+
+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.
+
+## Contributing
 
-Compatible with Vue 2 only for now. Support for Vue 3 is coming.
+See CONTRIBUTING.md for guidelines, architecture, and best practices.

package/components-vite.js

@@ -1,11 +1,11 @@
 import { RenderSlot } from './src/utils/slot'
 
-const NAME_REG = /Base([a-z0-9]+)\./i
+const NAME_REG = /Ui([a-z0-9]+)\./i
 
-export function registerComponents (app, prefix = 'Ls') {
+export function registerComponents (app, prefix = 'Ui') {
   app.component('RenderSlot', RenderSlot)
 
-  const componentsLib = import.meta.globEager('./src/components/**/Base+([a-zA-Z0-9]).{js,jsx,vue}')
+  const componentsLib = import.meta.glob('./src/components/**/Ui+([a-zA-Z0-9]).{js,jsx,vue,ts}', { eager: true })
   for (const key in componentsLib) {
     const component = componentsLib[key]
     const name = key.match(NAME_REG)[1]
@@ -13,12 +13,12 @@ export function registerComponents (app, prefix = 'Ls') {
   }
 }
 
-export function getComponents (prefix = 'Ls') {
+export function getComponents (prefix = 'Ui') {
   const componentsMap = {}
 
   componentsMap.RenderSlot = RenderSlot
 
-  const componentsLib = import.meta.globEager('./src/components/**/Base+([a-zA-Z0-9]).{js,jsx,vue}')
+  const componentsLib = import.meta.glob('./src/components/**/Ui+([a-zA-Z0-9]).{js,jsx,vue,ts}', { eager: true })
   for (const key in componentsLib) {
     const component = componentsLib[key]
     const name = key.match(NAME_REG)[1]

package/components.d.ts

@@ -1,4 +1,4 @@
-// @TODO remove when ui-vue is migrated to TS
+import type { App, Component } from 'vue'
 
-export function registerComponents (app: any, prefix = 'Ls'): void
-export function getComponents (prefix = 'Ls'): Record<string, any>
+export declare function registerComponents (app: App, prefix?: string): void
+export declare function getComponents (prefix?: string): Record<string, Component>