From 704cbd65a62469d12a7f567eb037adf835fbb652 Mon Sep 17 00:00:00 2001 From: "Timo K." Date: Tue, 10 Nov 2026 14:31:03 +0100 Subject: [PATCH] Shorten component readme - At the end there were not that many unique facts in there. It now only lists the relevant bits without much text around it. --- README.md | 154 +++++++++++++++++------------------------------------- 1 file changed, 48 insertions(+), 106 deletions(-) diff --git a/README.md b/README.md index ebc26f936..c806c45ce 100644 --- a/README.md +++ b/README.md @@ -221,126 +221,68 @@ See also: - [Developing with linked packages](./docs/linking.md) -#### Element Call as a component (experimental) +#### Element Call as a component -Element Call can also be embedded directly into another React application -rather than being loaded in an iframe as a widget. `pnpm build:component` -builds it as a library into `component/dist` (the bundle, its stylesheet and -type declarations), and +Element Call can be rendered inside another React app instead of an iframe. +The host supplies its own Matrix client, and the call stays inside the element +it is mounted in. -```sh -pnpm dev:component -``` - -serves a harness on port 3001 that stands in for such an application: it signs -in twice against the development backend and shows two calls side by side, in -resizable boxes, with page furniture of its own around them. Use it to see how -Element Call behaves when it does not own the page — the size it is given, -whether it stays inside its container, and what it says to its host, which is -logged along the bottom. The harness is served with the same development -certificate as the app, so unless the development CA is trusted, the browser -needs a certificate exception for `https://localhost:3001` as well (see the -note under [Backend](#backend)). It reads the same `public/config.json` as -`pnpm dev` if one exists, and runs with Element Call's defaults otherwise. - -The call lays itself out for the size of the element it is mounted in, not the -window: a host that shrinks the container to a corner of its page gets the -picture-in-picture layout, just as a host that shrank the whole iframe used to. -The breakpoints in the stylesheets the component uses are -`@container element-call` queries against its root element for the same reason; -for the standalone app the root is the page, so they mean what the media queries -they replaced did. (The standalone-only views, such as the home and login pages, -still use plain media queries, since the component never shows them.) - -The component's stylesheet is confined to the element it is mounted in: the -build rewrites every selector so that it matches only Element Call's root or -what is inside it, with `html`, `body` and `:root` standing for that root (see -`component/build/scopeStylesToRoot.ts`). A host's own page keeps its styles, -and Element Call brings its own fonts and design tokens along. - -The component speaks every language the app does. English is bundled in; the -other locales are split into chunks the host's bundler loads the first time -they are needed. It starts in the browser's language, and follows the host's -own language setting through the `language` prop (`supportedLanguages` lists -the tags it accepts, and anything else falls back to its base language or to -English). The `theme` prop works the same way and takes the same values as the -widget's `theme` URL parameter: `light`, `dark`, `light-high-contrast` or -`dark-high-contrast`. Both can change while a call is running without -disturbing it. - -The component's sounds, pictures and the MediaPipe runtime behind background -effects are files beside the module rather than data URLs inside it, each -referenced relative to the module (`new URL("./assets/…", import.meta.url)`), -so a host's bundler copies them as assets of its own — webpack 5, Vite and -Rollup all do — and the browser fetches the MediaPipe runtime, the largest of -them by far, only when an effect is first switched on. - -A host must call and await `initializeElementCall(config)` once before -rendering the component: it loads the `Intl` polyfills, applies the -deployment-wide `config.json`-style configuration and sets up translations. -The component itself takes the host's `client` and the `roomId` to call in, an -`intent` saying what the user asked for (which decides whether to show the -lobby, ring, and so on), an optional `config` overriding what the intent -implies, and an optional `hostBridge` through which Element Call tells the host -that the user has joined or hung up, that it wants to stay on screen, and so -on. The host makes its own requests (`join`, `hangUp`, `setDeviceMute`) through -the handle exposed on `ref`. The full API is documented in the type declarations -(`component/index.tsx` and `component/host.ts`). - -A few things differ from the widget on purpose: the component draws a solid -background rather than a gradient unless told otherwise, never offers to edit -the user's profile (the account is the host's), scopes its keyboard shortcuts to -its own root element so that several instances can share a page, and only shows -its own post-call and error screens when the host has not supplied a `close()` -callback; with one, it asks the host to unmount it instead. The -[global JS controls](./docs/controls.md) on `window` are unchanged and remain -page-wide, so with several instances on one page they apply to all of them. - -Each release publishes the package to npm, with the same version as the release: +##### Install ```sh npm install @element-hq/element-call-component ``` -To use an unreleased commit, a host can instead install it as a git dependency -on the `component` directory of this repository, +Releases publish the package with the same version as Element Call. For an +unreleased commit, depend on this repository directly: ```json "@element-hq/element-call-component": "github:element-hq/element-call#main&path:/component" ``` -whose `prepare` script runs the build on install. That build needs pnpm (via -Corepack) on the host's machine, runs a full `pnpm install` of this repository, -since it inherits the `--max-old-space-size` setting of -the app build; the host's pnpm also has to allow it to run at all -(`allowBuilds` in its `pnpm-workspace.yaml`). Note that `component/` is a pnpm -project of its own for this reason, so pnpm commands run from inside that -directory target it rather than the repository; run them from the repository -root. The host imports the component from -`@element-hq/element-call-component` and the stylesheet from -`@element-hq/element-call-component/style.css`, and has to provide `react`, -`react-dom`, `matrix-js-sdk`, `@vector-im/compound-web` and -`@vector-im/compound-design-tokens` itself, since the bundle leaves them -external. -Compound's stylesheet are the host's to load too: the component shares -the host's copy of Compound, (required for example for tooltips) +This builds on install, so the host needs pnpm (via Corepack) and must allow +the build (`allowBuilds` in its `pnpm-workspace.yaml`). -The component is large, and a host will usually load it lazily, only once a -call is shown. Everything a host needs in order to talk about a call before -then is also exported -from `@element-hq/element-call-component/api` (a small entry point that does not -load the component). +##### Use -- props and the types they are made of -- the handle -- the host bridge -- `UserIntent` -- `HeaderStyle` -- `BackgroundStyle` enums -- `configurationForIntent`, the defaults each intent implies - Import from it wherever a value such as - `BackgroundStyle.Solid` is needed on a path that must stay light; the main - entry point re-exports all of it too. +1. Provide the externals yourself: `react`, `react-dom`, `matrix-js-sdk`, + `@vector-im/compound-web`, `@vector-im/compound-design-tokens`, and + Compound's stylesheet. +2. Import `@element-hq/element-call-component/style.css`. +3. Await `initializeElementCall(config)` once before rendering. +4. Render the component with `client`, `roomId` and an `intent`; optionally + pass `config`, `hostBridge`, `language` and `theme` (both can change + mid-call). Control it through the `ref` handle (`join`, `hangUp`, + `setDeviceMute`). + +Load the component lazily. Types, enums and `configurationForIntent` are +available without it from `@element-hq/element-call-component/api`. The full +API is in `component/index.tsx`, `component/api.ts` and `component/host.ts`. + +##### How it differs from the widget + +- It lays out for its container, not the window: a small container gets the + picture-in-picture layout. +- Its styles and keyboard shortcuts are scoped to its root, so the host page is + untouched and several instances can share a page. The + [global JS controls](./docs/controls.md) stay page-wide. +- It draws a solid background by default and never offers profile editing. +- If the host bridge implements `close()`, it asks to be unmounted instead of + showing its own post-call and error screens. +- Sounds, images and the MediaPipe runtime are separate files the host's + bundler copies (webpack 5, Vite, Rollup); MediaPipe is fetched only when a + background effect is first used. + +##### Develop + +- `pnpm build:component` builds the library into `component/dist`. +- `pnpm dev:component` serves a test host on `https://localhost:3001`: two + calls side by side in resizable boxes, with host messages logged at the + bottom. It uses the development backend, `public/config.json` if present, + and needs the same certificate exception as `pnpm dev` (see + [Backend](#backend)). +- Run pnpm commands from the repository root; `component/` is its own pnpm + project. ### Backend