cobrowse-agent-ui 1.6.0 → 1.7.0-rc.10

package/README.md

@@ -1,5 +1,94 @@
 # Cobrowse Agent UI
 
+## Development
+
+This project uses [Vite+](https://viteplus.dev/guide/) (`vp`) as its toolchain for the dev server, builds, formatting,
+linting and type checking.
+
+### Setup
+
+1. Install the global `vp` CLI:
+
+   ```bash
+   # macOS / Linux
+   curl -fsSL https://vite.plus | bash
+
+   # Windows (PowerShell)
+   irm https://vite.plus/ps1 | iex
+   ```
+
+   Open a new shell and run `vp help` to confirm it's on your `PATH`. `vp` manages the Node.js runtime and package manager
+   for you. The npm version is pinned through `devEngines` in `package.json` and is downloaded automatically if it's missing.
+
+2. Install dependencies:
+
+   ```bash
+   vp install
+   ```
+
+3. Install the Git hooks:
+
+   ```bash
+   vp config
+   ```
+
+   The project's `.npmrc` sets `ignore-scripts=true`, so installing dependencies doesn't run the `prepare` script and
+   the hooks need installing once per clone. `vp config` installs them in `.vite-hooks`. The pre-commit hook runs
+   `vp check --fix` on staged files.
+
+If Node.js or npm behave unexpectedly, run `vp env doctor`.
+
+### Commands
+
+| Command       | Description                                                  |
+| ------------- | ------------------------------------------------------------ |
+| `vp dev`      | Start the dev server with the kitchen sink app from `src/`   |
+| `vp build`    | Build the library into `dist/`                               |
+| `vp check`    | Format, lint and type check                                  |
+| `vp run lint` | Lint (warnings fail), plus `i18next-cli` lint. CI runs this. |
+| `vp run i18n` | Extract translation keys into the locale files               |
+
+**Note:** `vp <name>` runs a built-in Vite+ command, while `vp run <name>` runs a `package.json` script. The two can do
+different things, so use `vp run` for the scripts defined in this project.
+
+The npm equivalents (`npm install`, `npm run <script>`) still work, even without the global `vp` CLI, since the scripts
+use the project-local `vp` from the `vite-plus` package. CI uses them too. Prefer `vp` for local development, though, so
+commands run with the Node.js and npm versions Vite+ manages.
+
+For linting in your editor, install the [Oxc extension](https://marketplace.visualstudio.com/items?itemName=oxc.oxc-vscode)
+for VS Code or the equivalent for [other editors](https://viteplus.dev/guide/ide-integration).
+
+## Accounts (experimental)
+
+`AccountsProvider` lists the user's accounts and keeps one selected, stored in local storage so it survives a reload.
+While mounted it owns the SDK's license: once the list has loaded, the license is kept on the account shown, so that
+is the account requests are made against, and on unmount the SDK gets back the license it had. The selection starts
+from the stored one, else from a license set on the SDK before mounting, and resolves to the first account when the
+list doesn't contain it. The provider needs a
+`CobrowseProvider` above it, and should be mounted once the user is signed in, as an empty list, which the API returns
+to a signed-out request, resolves to no account and clears the SDK's license:
+
+```jsx
+<CobrowseProvider cobrowse={cobrowse}>
+  <AccountsProvider>
+    <App />
+  </AccountsProvider>
+</CobrowseProvider>
+```
+
+Inside it, `useActiveAccount` gives the selected account and the function to select another, `useAccountsContext` the
+list as `useListAccounts` returns it, and `useActiveAccountContext` the selection along with `isResolved`, true once
+the selection has been matched against the loaded list or the list failed to load:
+
+```jsx
+const [account, setActiveAccount] = useActiveAccount()
+const { data: accounts, refetch, unshift } = useAccountsContext()
+```
+
+`setActiveAccount` takes an SDK account, and puts one the list doesn't contain yet, e.g. one just created, first in
+the list. A bare `{ license_key }` can be selected before the list has loaded, e.g. an account forced from the URL,
+and is resolved against the list once it arrives. After that it has to be in the list, or `setActiveAccount` throws.
+
 ## Localization
 
 ### Change active locale at runtime
@@ -10,16 +99,16 @@ achieve this from an app that's also using `i18next` to handle localization.
 ```js
 // i18n.js
 
-import i18n from 'i18next';
-import { bindI18n } from 'cobrowse-agent-ui';
+import i18n from 'i18next'
+import { bindI18n } from 'cobrowse-agent-ui'
 
 i18n.init({
   // ...
-});
+})
 
-bindI18n(i18n);
+bindI18n(i18n)
 
-export default i18n;
+export default i18n
 ```
 
 ### Adding new locales
@@ -27,11 +116,11 @@ export default i18n;
 To add a new locale follow these steps:
 
 - Add a new entry to the `locales` array inside `i18next.config.ts`.
-- Run the `npm run i18n` command to generate a new locale file.
+- Run the `vp run i18n` command to generate a new locale file.
 - Import the new locale JSON file inside `lib/i18n/instance.ts` and add it to the `resources` object (in the i18n instance
   configuration) keyed by the locale key.
 - Import the relevant `date-fns` locale inside `lib/i18n/instance.ts`.
 - Add a new entry to `dateLocales` inside `lib/i18n/instance.ts`.
 
 **Note:** ensure the locale code matches the ones provided by the
-[date-fns library](https://github.com/date-fns/date-fns/tree/main/src/locale) as these are used to localize dates as well.
+[date-fns library](https://github.com/date-fns/date-fns/tree/main/pkgs/core/src/locale) as these are used to localize dates as well.