@livestorm/ui-vue 2.0.3 → 2.0.5

package/README.md

@@ -36,6 +36,7 @@ A modern, strongly-typed Vue 3 component library for Livestorm’s design system
   - 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.
 
 Installing the package also pulls in `@livestorm/ui-tokens` (design tokens) and `@livestorm/ui-icons` (icon utilities).
 
@@ -58,12 +59,17 @@ Components use Tailwind utility classes (including the `i-ls-*` icon classes), s
 @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 body defaults ship inside `@layer base`, so anything your app declares — layered or not — takes precedence over them.
+
 ## App setup
 
 No runtime plugin is required. Create your app, import components, done:
@@ -100,7 +106,28 @@ app.use(Responsive, {
 
 </details>
 
-## Using components
+<details>
+<summary>Optional: plugging your own translations</summary>
+
+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:
+
+```ts
+import { setTranslator } from '@livestorm/ui-vue/integrations'
+
+setTranslator((key) => myI18n.t(`ui-vue.${key}`))
+```
+
+On an SSR server, provide the translator on the app instance instead — `setTranslator` is process-wide state shared by concurrent requests, and without a translator the server falls back to English (it cannot read `<html lang>`). For a non-English SSR app this is the difference between hydrating correct labels and keeping English aria-labels:
+
+```ts
+import { UI_VUE_TRANSLATOR } from '@livestorm/ui-vue/integrations'
+
+app.provide(UI_VUE_TRANSLATOR, (key) => myI18n.t(`ui-vue.${key}`))
+```
+
+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:
 
@@ -130,8 +157,9 @@ registerComponents(app, 'Ls')    // <LsButton>, <LsTextField>, ...
 | --- | --- |
 | `@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/integrations` | Toast helpers (`openToast`, ... — call client-side only: toast state is per-process on a server) and translation wiring (`setTranslator`, `UI_VUE_TRANSLATOR`) |
 | `@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 |