# Advanced Chat Components A framework-neutral chat web component and typed Vue 3 component library: rooms, messages, files, audio, reactions, replies, edits, typing indicators, themes, localization, and composables. Backend-agnostic — you own the data layer. This repository contains the release-candidate line of Advanced Chat Components: - **V3 release candidate** — published as `@advanced-chat/components@3.0.0-rc.3` on the npm `next` tag. It contains 28 typed Vue 3 SFCs plus an official light-DOM web-component entrypoint. The package is ESM-only; a browser-only UMD artifact remains available through the CDN metadata. - **Legacy v2** — published as `vue-advanced-chat@2.1.2`. Existing v2 applications can continue using that stable package; its source is retained on the [`v2`](https://github.com/advanced-chat/advanced-chat-components/tree/v2) branch. V3 is not a drop-in replacement. ## V3 documentation The V3 docs site is built from Storybook and deployed from the default branch: > **** It carries the per-component prop / event / slot tables, the prose guides, the cookbook, and the public API reference. New users on V3 should start with the **Quick Start** page on the docs site. ## Install (V3) ```bash npm install @advanced-chat/components@next ``` Vue 3.5+ is a peer dependency. ## Quick example (V3) ```ts // main.ts import { createApp } from 'vue' import App from './App.vue' import { AdvancedChatPlugin } from '@advanced-chat/components' import '@advanced-chat/components/styles' createApp(App).use(AdvancedChatPlugin()).mount('#app') ``` ```vue ``` ## Web component (V3) The framework-independent entrypoint bundles its Vue runtime and registers `` in light DOM on import. Load its matching stylesheet, then assign objects and arrays as DOM properties rather than JSON attributes: ```html ``` Importing `@advanced-chat/components/web-component` auto-registers the default tag with automatic localization. The entrypoint exports `AdvancedChatHTMLElement`, `AdvancedChatEventMap`, and `AdvancedChatElementConstructor` so DOM properties and event details are typed. Event payloads are exposed directly as `CustomEvent.detail`, not wrapped in a Vue argument array. Public events bubble and cross shadow boundaries, so hosts can use event delegation. For applications that control registration or render on the server, import the side-effect-free core entrypoint: ```ts import { registerAdvancedChat, type AdvancedChatHTMLElement, } from '@advanced-chat/components/web-component/core' import '@advanced-chat/components/web-component/styles' if (typeof window !== 'undefined') { registerAdvancedChat({ tagName: 'acme-chat' }) } ``` The package includes a standards-based `custom-elements.json` manifest for IDE completion and custom-element-aware tooling. Vanilla JavaScript, React, Angular, Svelte, and other framework examples are in the **Web Components** page on the documentation site. `registerAdvancedChat({ tagName, strings, localization })` can register an alternate tag. Calling it for the default managed tag after auto-registration updates options for elements mounted after that call; already-mounted elements keep the localization they were created with. Options are never silently applied to a tag registered by an unrelated constructor. Mention selections are serialized into stable `<@id>` tokens in `content` and the corresponding full users are included in `mentionedUsers` on both `send-message` and `edit-message`. Pending attachment object URLs are owned and cleaned up by the library until send/edit; ownership of emitted `localUrl` values then transfers to the host, which must revoke them when they are no longer needed. Transport, persistence, authorization, upload, realtime, and retry policy remain the host application's responsibility. For a full working example, the **Quick Start** page on the docs site walks through the wiring end-to-end. To run a real backend behind it, see **Cookbook → Backend Integration**. ## Install (v2) To stay on the stable v2 `2.1.2` line: ```bash npm install vue-advanced-chat ``` Use the `v2` branch for v2 source and documentation. The v2-specific issues listed in [`rewrite/issue-triage.md`](./rewrite/issue-triage.md) provide a rough map of what V3 resolves. ## Development ```bash npm ci npm run storybook # local docs + component playground npm run verify # format + types + lint + tests + build + pack + storybook ``` Use Node `22.14.0` or newer (`.nvmrc`). Key `npm run` scripts include `format`, `format:check`, `lint`, `type-check`, `test`, `test:unit`, `test:storybook`, `test:coverage`, `build`, `build-storybook`, `verify`, `verify:pack`, and `verify:web-component`. `verify` chains the release gates that CI also runs. ## Contributing Contributions are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, branch, testing, and pull-request expectations. Usage questions belong in [GitHub Discussions](https://github.com/advanced-chat/advanced-chat-components/discussions/categories/q-a), and vulnerabilities must follow [SECURITY.md](./SECURITY.md). For the V3 release process, see [RELEASING.md](./RELEASING.md). The architecture rationale and parity status live in [`rewrite/`](./rewrite/README.md). Notable changes are tracked in [`CHANGELOG.md`](./CHANGELOG.md). ## License MIT. Bundled dependency notices are listed in [THIRD_PARTY_LICENSES.md](./THIRD_PARTY_LICENSES.md).