@flung.dev/connect 0.1.1 → 0.3.0

package/README.md

@@ -42,7 +42,7 @@ app.post('/connect-token', async (_request, response) => {
   const panel = document.querySelector('flung-connect')
   // A function: the panel asks again when a token expires.
   panel.token = async () => (await (await fetch('/connect-token', { method: 'POST' })).json()).token
-  panel.addEventListener('flung-connect', (event) => console.log('Connected', event.detail.accounts))
+  panel.addEventListener('flung-connect', (event) => showConnected(event.detail.accounts))
 </script>
 
 <flung-connect platforms="x,linkedin,bluesky,mastodon"></flung-connect>
@@ -54,7 +54,7 @@ app.post('/connect-token', async (_request, response) => {
 import { FlungConnect } from '@flung.dev/connect/react'
 
 export function Accounts() {
-  return <FlungConnect token={fetchConnectToken} platforms={['x', 'linkedin']} onConnect={({ accounts }) => console.log(accounts)} />
+  return <FlungConnect token={fetchConnectToken} platforms={['x', 'linkedin']} onConnect={({ accounts }) => showConnected(accounts)} />
 }
 ```
 
@@ -69,7 +69,14 @@ export function Accounts() {
 | `platforms` | | Offer only these, comma-separated. A token made with `platforms` is narrowed to those as well. |
 | `mode` | | `popup` (the default) opens a small window. `redirect` sends the whole page to the platform and back, for pages that cannot open windows; Flung returns to the same address, and the panel reports the result and tidies the address. |
 | `theme` | | `light` or `dark`. Follows the page's scheme when left out. |
+| `layout` | | `list` (the default), `grid` or `compact`. See [Make it yours](#make-it-yours). |
+| `variants` | | How LinkedIn offers company pages, when your Flung has them set up: `choose` (the default) asks after **Connect**; `tiles` shows **LinkedIn** and **LinkedIn Page** as two platforms. See [LinkedIn company pages](#linkedin-company-pages). |
+| `unstyled` | | Drops Flung's stylesheet, so every part is yours to style. |
+| `branding` | | `none` hides the small "Secured by Flung" line under the list. |
 | | `labels` | Every word the panel shows, to put it in another language. See `DEFAULT_LABELS`. |
+| | `state` | The panel's current state (`ConnectState`), read only. |
+| | `controller` | The headless controller behind the panel (`ConnectController`), for rows a page draws itself. A new token makes a new one. |
+| | `connect(platform, options)` | Starts a connect as the platform's button does; `{ variant: 'pages' }` connects LinkedIn company pages without asking, `{ variant: null }` the person's profile. Call it from a click. |
 | | `refresh()` | Reads the accounts again. |
 
 ## Events
@@ -80,30 +87,233 @@ export function Accounts() {
 | `flung-connect` | `{ session, accounts }` | A connect or reconnect finished. Facebook stores one account per page. `session` is null after a redirect. |
 | `flung-disconnect` | `{ account }` | An account was disconnected. Its past posts keep their results. |
 | `flung-error` | `{ code, message }` | A call or a connect failed: `access_denied`, `wrong_account`, `forbidden`, `network_error` and so on. |
+| `flung-change` | `{ state }` | Anything the panel shows changed. Does not bubble. |
 
-Events bubble and cross the shadow root.
+The first four bubble and cross the shadow root.
 
-## Looks
+## LinkedIn company pages
 
-The panel draws in a shadow root. Set any of `--flung-font`, `--flung-text`, `--flung-muted`, `--flung-surface`, `--flung-raised`, `--flung-border`, `--flung-accent`, `--flung-accent-text`, `--flung-danger`, `--flung-warning` and `--flung-radius` on the element, or style its parts with `::part()`: `panel`, `list`, `platform`, `badge`, `name`, `account`, `status`, `form`, `note`, `confirm`, `message`.
+LinkedIn connects a person's own profile and the company pages they administer through two separate apps. When your Flung has the pages app set up, `GET /v1/platforms` lists `variants: ["pages"]` for LinkedIn and the panel offers both. A person does not need to connect their profile first.
+
+| `variants` | What the person sees |
+|---|---|
+| `choose` (the default) | One LinkedIn row. **Connect** opens a small question under it: **Personal profile** (post as yourself) or **Company page** (post as a page you admin). Arrow keys move between the two, Escape or **Cancel** closes it, and focus goes back to **Connect**. |
+| `tiles` | Two rows, **LinkedIn** and **LinkedIn Page**, each with its own Connect and its own accounts. |
+
+A pages connect stores one account per page the person administers. Each shows under LinkedIn with the page's name and a small **Page** tag (`AccountItem.page` is true). Without the pages app, LinkedIn works as before; with only the pages app, the LinkedIn row connects pages straight away and is named **LinkedIn Page**.
+
+```html
+<flung-connect variants="tiles"></flung-connect>
+<button id="pages">Connect your company page</button>
+<script type="module">
+  // From your own button: a click opens the sign-in window.
+  document.getElementById('pages').onclick = () => document.querySelector('flung-connect').connect('linkedin', { variant: 'pages' })
+</script>
+```
+
+In React, `<FlungConnect variants="tiles" />`; with the hook or the controller, `connect('linkedin', { variant: 'pages' })`. The chooser's words are labels like the rest: `chooseVariant`, `variantPersonal`, `variantPersonalDescription`, `variantPages`, `variantPagesDescription`, `pagesName` and `pageTag`.
+
+## Make it yours
+
+Six levels of control, from least to most. Each keeps the same behaviour: the popup and its blocked-window link, the Mastodon and Bluesky questions, the wait with Cancel, the confirm before a disconnect, redirects and errors.
+
+### 1. Custom properties
+
+Set any of these on the element. Each has a default for light and dark.
+
+| Property | Default | What |
+|---|---|---|
+| `--flung-font` | `system-ui, ...` | The typeface. |
+| `--flung-font-size` | `15px` | Body text; most other sizes are worked out from it. |
+| `--flung-font-size-small` | `13px` | Counts, handles, labels and the footer. |
+| `--flung-line-height` | `1.45` | Body line height. |
+| `--flung-font-weight-medium` | `500` | Buttons and account names. |
+| `--flung-font-weight-strong` | `600` | Platform names and initials. |
+| `--flung-text` | `#18181b` | Text. |
+| `--flung-muted` | `#71717a` | Secondary text. |
+| `--flung-surface` | `#ffffff` | The panel's background. |
+| `--flung-raised` | `#f4f4f5` | Questions, the message line, button hover. |
+| `--flung-border` | `#e4e4e7` | Every border. |
+| `--flung-accent` | `#18181b` | Primary buttons. |
+| `--flung-accent-text` | `#ffffff` | Text on primary buttons. |
+| `--flung-danger` | `#dc2626` | Errors, Disconnect on hover, the confirm button. |
+| `--flung-warning` | `#b45309` | The reconnect status. |
+| `--flung-success` | `#15803d` | The connected dot. |
+| `--flung-radius` | `12px` | The panel's corners. |
+| `--flung-radius-inner` | radius less 4px | Tiles, cards, questions and fields. |
+| `--flung-button-radius` | `--flung-radius-inner` | Buttons. |
+| `--flung-border-width` | `1px` | Every border. `0` for none. |
+| `--flung-shadow` | `none` | The panel's shadow. |
+| `--flung-card-shadow` | `none` | Each card in the `grid` layout. |
+| `--flung-padding` | `16px` | Space at the panel's edges. |
+| `--flung-gap` | `12px` | Space between pieces and rows. |
+| `--flung-badge-size` | `40px` | The platform tile. |
+| `--flung-mark-size` | `20px` | The platform mark inside it. |
+| `--flung-mark-strength` | `100%` | How much of each platform's brand colour its mark keeps. |
+| `--flung-tint-strength` | `8%` | How much of it the tile and the initial circle take. |
+| `--flung-avatar-size` | `32px` | Account pictures. |
+| `--flung-button-height` | `36px` | Every button and the handle field. |
+| `--flung-button-padding` | `0 14px` | Inside buttons. |
+| `--flung-focus-color` | `--flung-accent` | The focus ring. |
+| `--flung-focus-width` | `2px` | Its width. |
+| `--flung-focus-offset` | `2px` | Its gap from the control. |
+| `--flung-grid-min` | `16rem` | The narrowest card in the `grid` layout. |
+| `--flung-tooltip-background` | `--flung-text` | The tooltip that shows an account name cut short. |
+| `--flung-tooltip-text` | `--flung-surface` | Its words. |
+| `--flung-tooltip-radius` | `--flung-radius-inner` | Its corners. |
+| `--flung-tooltip-shadow` | a soft shadow | Its shadow. |
+
+```css
+flung-connect {
+  --flung-font: "Inter", sans-serif;
+  --flung-accent: #0f766e;
+  --flung-radius: 6px;
+  --flung-shadow: 0 1px 2px rgb(0 0 0 / .06);
+}
+```
+
+### 2. Parts
+
+Every piece the panel draws has a `part` name for `::part()`. Pieces with a kind carry a second name, so a page can style all of them or one kind.
+
+| Part | What |
+|---|---|
+| `panel` | The whole panel. Has `data-layout`. |
+| `list` | The list of platforms. |
+| `platform`, `platform-<id>` | One platform, such as `platform-linkedin`. |
+| `row` | Its tile, name and Connect button. |
+| `badge`, `mark` | The tile and the mark inside it. |
+| `title`, `name`, `count`, `count-connected` | The name and the line under it. |
+| `accounts`, `account` | The platform's accounts, and one of them. |
+| `avatar`, `avatar-image`, `avatar-initial` | The account's picture, or the circle with its initial when there is none or it does not load. |
+| `account-details`, `account-names`, `account-name`, `account-username` | The display name and the `@handle` under it. |
+| `status` | Needs reconnecting, or the date to reconnect by. |
+| `actions` | The account's buttons. |
+| `button` | Every button. Also `button-primary`, `button-secondary`, `button-quiet` or `button-danger`, and one of `button-connect`, `button-reconnect`, `button-disconnect`, `button-continue`, `button-cancel`, `button-confirm`, `button-keep`, `button-option`. |
+| `platform-linkedin-pages` | With `variants="tiles"`, the LinkedIn Page row, besides `platform` and `platform-linkedin`. Its slot is `platform-linkedin-pages`. |
+| `choose`, `choose-title`, `choose-options` | The question between a LinkedIn profile and a company page. |
+| `button-option`, `button-option-personal`, `button-option-pages` | Its two choices. Each holds `option-icon` (with `option-mark`), `option-text`, `option-name` and `option-description`. |
+| `tag`, `tag-page` | The **Page** tag beside a company page. |
+| `form`, `label`, `input` | The Mastodon server or Bluesky handle question. |
+| `note`, `spinner`, `note-text`, `link` | The wait, and the sign-in link when the browser blocked the window. |
+| `confirm`, `confirm-text` | The question before a disconnect. |
+| `message`, `message-error` | The status line under the list. It has `hidden` when empty. |
+| `footer`, `footer-link`, `footer-mark` | "Secured by Flung". |
+| `tooltip` | The full account name or `@handle`, when the panel is too narrow for it, on hover or a held finger. In the top layer where the browser has popovers. |
 
 ```css
-flung-connect { --flung-accent: #0f766e; --flung-radius: 12px; }
 flung-connect::part(panel) { border: 0; }
+flung-connect::part(button-primary) { border-radius: 999px; }
+flung-connect::part(platform-x) { background: #fafafa; }
+```
+
+### 3. Layouts
+
+`layout="list"` (the default) puts platforms one under another, `grid` makes them cards side by side, and `compact` tightens every size for a sidebar.
+
+```html
+<flung-connect layout="grid" style="--flung-grid-min: 14rem"></flung-connect>
+```
+
+### 4. Unstyled
+
+`unstyled` drops Flung's stylesheet. The element stays a block and keeps its `part` names, so the whole look is your CSS. Marks and avatars carry `width` and `height` attributes so they stay small until you size them.
+
+```css
+flung-connect::part(list) { display: flex; flex-direction: column; gap: 1rem; }
+flung-connect::part(platform) { padding: 1rem; border: 1px solid var(--your-border); }
+flung-connect::part(button) { font: inherit; }
+```
+
+### 5. Render props
+
+`<FlungConnect>` takes `renderPlatform` and `renderAccount`, to draw a platform's row (mark, name and Connect) or an account's row with your own components. They render in your page's DOM, through the element's named slots (`platform-<id>`, `account-<id>`), so your own CSS reaches them; the panel keeps the questions, the wait, the confirm and the messages around them.
+
+```tsx
+<FlungConnect
+  token={fetchConnectToken}
+  renderAccount={({ account, actions, labels }) => (
+    <UserChip name={account.displayName} picture={account.avatarUrl} handle={account.username}>
+      <Button variant="ghost" onClick={() => actions.requestDisconnect(account.account.id)}>{labels.disconnect}</Button>
+    </UserChip>
+  )}
+/>
 ```
 
+Without React, put an element with `slot="account-<id>"` inside `<flung-connect>` and call `panel.controller` from it; `flung-change` says when to draw again.
+
+### 6. Headless: `useFlungConnect` and `createConnectController`
+
+`useFlungConnect` (from `@flung.dev/connect/react`) gives the state and the actions and draws nothing: every element and class is yours. Call `connect`, `submitHandle` and `reconnect` straight from a click or submit handler, since a browser opens a window only during one.
+
+```tsx
+import { useFlungConnect } from '@flung.dev/connect/react'
+
+export function Accounts() {
+  const panel = useFlungConnect({ token: fetchConnectToken, platforms: ['x', 'linkedin', 'mastodon'] })
+  return (
+    <ul className="accounts">
+      {panel.platforms.map((item) => (
+        <li key={item.platform}>
+          <h3>{item.name}</h3>
+          {item.accounts.map((account) => <p key={account.account.id}>{account.displayName}</p>)}
+          {item.step.kind === 'handle' && (
+            <form onSubmit={(event) => { event.preventDefault(); panel.submitHandle(item.platform, new FormData(event.currentTarget).get('handle') as string) }}>
+              <input name="handle" required={item.step.required} />
+            </form>
+          )}
+          {item.step.kind === 'waiting' && item.step.blockedUrl !== null && <a href={item.step.blockedUrl} target="_blank" rel="noopener">Open sign-in</a>}
+          {item.step.kind === 'confirm' && <button onClick={() => panel.confirmDisconnect(item.platform)}>Yes, disconnect</button>}
+          <button disabled={item.busy} onClick={() => panel.connect(item.platform)}>Connect</button>
+        </li>
+      ))}
+      <p role="status">{panel.message.text}</p>
+    </ul>
+  )
+}
+```
+
+`createConnectController` (from `@flung.dev/connect/core`) is the same with no framework: `getState()` and `subscribe()` fit `useSyncExternalStore`, Svelte stores, Vue's `shallowRef` and plain DOM alike. `<flung-connect>` and `useFlungConnect` are both drawn from it.
+
+```ts
+import { createConnectController } from '@flung.dev/connect/core'
+
+const panel = createConnectController({ token: fetchConnectToken, onConnect: ({ accounts }) => showConnected(accounts) })
+panel.subscribe(() => draw(panel.getState()))
+// later: panel.destroy()
+```
+
+| Member | What |
+|---|---|
+| `getState()` | The current `ConnectState`, frozen; the same object until something changes. |
+| `subscribe(listener)` | Calls `listener` after every change; returns the function that stops it. |
+| `connect(platform, { variant })` | Starts a connect, or sets the step to `handle` for Mastodon and Bluesky, or to `choose` when LinkedIn offers pages and `variant` is left out. `variant: 'pages'` or `null` (the profile) connects without asking. |
+| `submitHandle(platform, handle)` | Answers the `handle` step and starts the connect. |
+| `reconnect(accountId)` | Reconnects an account. |
+| `requestDisconnect(accountId)` | Sets the step to `confirm`. Nothing is sent. |
+| `confirmDisconnect(platform)` | Disconnects the account the `confirm` step asks about. |
+| `cancel(platform)` | Stops waiting, or closes the question. |
+| `dismissNotice()` | Clears the last notice. |
+| `refresh()` | Reads everything again. |
+| `configure({ platforms, mode, labels })` | Changes those options while shown. |
+| `destroy()` | Stops every wait and listener. |
+
+`ConnectState` has `hasToken`, `loading`, `loaded`, `platforms` (each with `name`, `accounts`, `step`, `busy`, `handlePrompt`, `connectable` and `variants`), `accounts`, `notice` (the last thing that happened, as data), `message` (that notice, or the loading, empty or no-token line, in the labels' words) and `labels`. Each account item has `displayName`, `username` (the handle when it differs), `avatarUrl` (only ever `https`), `initial`, `page` (a LinkedIn company page) and `reconnect`. A step is `idle`, `handle` (with `required`), `choose` (with `variants`), `waiting` (with `blockedUrl` and `variant`) or `confirm` (with `account`).
+
 ## Behaviour worth knowing
 
 - **Popups.** Browsers open a window only straight from a click, so the panel opens it first and fills it in once Flung answers. When a browser blocks it anyway, the panel shows a link to the consent page instead.
 - **Waiting.** The panel waits on the connect session, not the window: some platforms' sign-in pages cut the link back to the page that opened them. Sessions last ten minutes. **Cancel** stops waiting.
 - **Mastodon and Bluesky** ask first: the person's Mastodon server (required), or their Bluesky handle (optional; without it they sign in through bsky.social).
+- **LinkedIn** asks whether to connect a personal profile or a company page when your Flung offers pages. A reconnect of a page goes through the pages app by itself.
 - **Reconnect** appears beside an account that needs it, or whose platform only lets Flung renew it for a limited time and that time ends within two weeks.
 - **Disconnect** asks to confirm. The account then drops from the panel; it stays in the API as `disconnected`.
-- **Safety.** Every name and message is set as text; nothing the API returns becomes markup. The panel sends the token to the API address only, and no cookie.
+- **Accounts** show their picture, display name and `@handle`. A picture is loaded only from an `https` address, sends no referrer, and falls back to the account's initial when it is missing or does not load.
+- **Safety.** Every name and message is set as text; nothing the API returns becomes markup. A sign-in link is only ever an `http` or `https` address. The panel sends the token to the API address only, and no cookie. The headless controller and hook keep the same rules; what your own markup does with the state is yours.
 
 ## Without the element
 
-`@flung.dev/connect/core` has the calls (`ConnectClient`) and the flows (`connectInPopup`, `readRedirectResult`) for a page that draws its own panel.
+`@flung.dev/connect/core` has the headless controller (above), and underneath it the calls (`ConnectClient`) and the flows (`connectInPopup`, `readRedirectResult`).
 
 ```ts
 import { ConnectClient, connectInPopup } from '@flung.dev/connect/core'
@@ -119,8 +329,8 @@ button.onclick = async () => {
 
 | Path | Purpose |
 |---|---|
-| `src/core/` | `ConnectClient`, the popup and redirect flows, platform names, and the API shapes it reads. No DOM needed except `window.open` in the popup flow. |
-| `src/element/` | `<flung-connect>`: the element, its styles, words, events and node helpers. |
-| `src/react/` | `<FlungConnect>`, the element for React. |
+| `src/core/` | `createConnectController` (the panel's behaviour with no markup), `ConnectClient`, the popup and redirect flows, the panel's words, platform names, and the API shapes it reads. No DOM needed except `window.open` in the popup flow. |
+| `src/element/` | `<flung-connect>`: the element drawn from the controller, its styles, events and node helpers. `marks.ts` is the platforms' marks (Simple Icons; Boxicons for LinkedIn), the profile-or-page choice's icons (Boxicons) and Flung's, written by `pnpm sync:icons`. |
+| `src/react/` | `<FlungConnect>`, the element for React, and `useFlungConnect`, the headless hook. |
 | `src/register.ts` | The side-effect entry that registers the element. |
-| `src/__tests__/` | The client, flows, element and React component against a fake of the seven calls (`fake-api.ts`), in jsdom. |
+| `src/__tests__/` | The client, flows, controller, element and React component and hook against a fake of the seven calls (`fake-api.ts`), in jsdom. |

package/dist/core/client.d.ts

@@ -1,4 +1,4 @@
-import type { Account, ConnectSession, Platform, PlatformInfo } from './types.js';
+import type { Account, ConnectSession, ConnectVariant, Platform, PlatformInfo } from './types.js';
 export declare const DEFAULT_BASE_URL = "https://api.flung.dev";
 /** A connect token (`flung_ct_...`), or a function that fetches a fresh one from your server. */
 export type TokenSource = string | (() => Promise<string>);
@@ -24,12 +24,18 @@ export declare class FlungConnectError extends Error {
 export declare class ConnectClient {
     #private;
     constructor(options: ConnectClientOptions);
+    /** Every platform, and whether this Flung can connect it. */
     platforms(): Promise<PlatformInfo[]>;
+    /** The connected accounts the token may see: its profile's, or the whole workspace's. */
     accounts(): Promise<Account[]>;
-    /** Starts connecting a new account. `handle` is the Bluesky handle, or the Mastodon instance (required there). */
+    /**
+     * Starts connecting a new account. `handle` is the Bluesky handle, or the Mastodon instance (required there). `variant`
+     * picks another way to connect the platform: `pages` on LinkedIn connects the company pages the person administers.
+     */
     connect(platform: Platform, options?: {
         handle?: string | undefined;
         redirectUrl?: string | undefined;
+        variant?: ConnectVariant | undefined;
     }): Promise<ConnectSession>;
     /** Starts reconnecting an account that needs it; the person must sign in as the same platform user. */
     reconnect(accountId: string, options?: {
@@ -37,6 +43,7 @@ export declare class ConnectClient {
     }): Promise<ConnectSession>;
     /** Deletes the account's stored tokens. It stays listed as `disconnected`. */
     disconnect(accountId: string): Promise<Account>;
+    /** A connect session's state: pending, connected, failed or expired. */
     session(id: string): Promise<ConnectSession>;
     /** Resolves once the session is no longer `pending`. Rejects with an `AbortError` when `signal` aborts. */
     waitForSession(id: string, options?: {

package/dist/core/client.js

@@ -22,21 +22,28 @@ export class ConnectClient {
     #fetch;
     #source;
     #token;
+    /** The token being fetched, shared by every call that needs one meanwhile, so calls side by side ask the source once. */
+    #pending = null;
     constructor(options) {
         this.#baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
         this.#fetch = options.fetch ?? ((input, init) => fetch(input, init));
         this.#source = options.token;
         this.#token = typeof options.token === 'string' ? options.token : null;
     }
+    /** Every platform, and whether this Flung can connect it. */
     async platforms() {
         return (await this.#call('GET', '/v1/platforms')).data;
     }
+    /** The connected accounts the token may see: its profile's, or the whole workspace's. */
     async accounts() {
         return (await this.#call('GET', '/v1/accounts')).data;
     }
-    /** Starts connecting a new account. `handle` is the Bluesky handle, or the Mastodon instance (required there). */
+    /**
+     * Starts connecting a new account. `handle` is the Bluesky handle, or the Mastodon instance (required there). `variant`
+     * picks another way to connect the platform: `pages` on LinkedIn connects the company pages the person administers.
+     */
     async connect(platform, options = {}) {
-        return this.#call('POST', `/v1/connect/${encodeURIComponent(platform)}`, compact({ handle: options.handle, redirectUrl: options.redirectUrl }));
+        return this.#call('POST', `/v1/connect/${encodeURIComponent(platform)}`, compact({ handle: options.handle, redirectUrl: options.redirectUrl, variant: options.variant }));
     }
     /** Starts reconnecting an account that needs it; the person must sign in as the same platform user. */
     async reconnect(accountId, options = {}) {
@@ -46,6 +53,7 @@ export class ConnectClient {
     async disconnect(accountId) {
         return this.#call('DELETE', `/v1/accounts/${encodeURIComponent(accountId)}`);
     }
+    /** A connect session's state: pending, connected, failed or expired. */
     async session(id) {
         return this.#call('GET', `/v1/connect-sessions/${encodeURIComponent(id)}`);
     }
@@ -60,9 +68,10 @@ export class ConnectClient {
         }
     }
     async #call(method, path, body) {
-        let response = await this.#send(method, path, body, await this.#currentToken(false));
+        const used = await this.#currentToken();
+        let response = await this.#send(method, path, body, used);
         if (response.status === 401 && typeof this.#source === 'function')
-            response = await this.#send(method, path, body, await this.#currentToken(true));
+            response = await this.#send(method, path, body, await this.#currentToken(used));
         const text = await response.text();
         const parsed = parse(text);
         if (!response.ok) {
@@ -79,12 +88,22 @@ export class ConnectClient {
             throw new FlungConnectError(0, 'network_error', `Could not reach Flung: ${String(error)}`);
         });
     }
-    async #currentToken(fresh) {
-        if (typeof this.#source === 'string')
-            return this.#source;
-        if (this.#token === null || fresh)
-            this.#token = await this.#source();
-        return this.#token;
+    /**
+     * The token to send. `expired` is one the API refused: a new one is asked for unless another call already replaced it. One
+     * request to the source at a time, shared by every call waiting on it.
+     */
+    async #currentToken(expired) {
+        const source = this.#source;
+        if (typeof source === 'string')
+            return source;
+        if (this.#token !== null && this.#token !== expired)
+            return this.#token;
+        this.#pending ??= source()
+            .then((token) => (this.#token = token))
+            .finally(() => {
+            this.#pending = null;
+        });
+        return this.#pending;
     }
 }
 function compact(values) {

package/dist/core/controller.d.ts

@@ -0,0 +1,214 @@
+import type { TokenSource } from './client.js';
+import type { ConnectDetail, DisconnectDetail, ErrorDetail, LoadDetail } from './events.js';
+import type { ConnectLabels } from './labels.js';
+import type { Account, ConnectSession, ConnectVariant, Platform } from './types.js';
+/** What one connected account looks like to a panel: the API's account and what to show for it. */
+export interface AccountItem {
+    /** The account as the API returned it. */
+    readonly account: Account;
+    /** How messages name it: its username, or its platform id when it has none. */
+    readonly name: string;
+    /** The name to show first: the display name, else the username, else the platform id. */
+    readonly displayName: string;
+    /** The handle to show under the display name, without the `@`; null when it would repeat the display name. */
+    readonly username: string | null;
+    /** The profile picture, only when the API gave an `https` address; otherwise null, so a panel shows `initial`. */
+    readonly avatarUrl: string | null;
+    /** One letter for a picture that is missing or does not load. */
+    readonly initial: string;
+    /** True for a company page (a LinkedIn page connected with the `pages` variant), false for a person's own account. */
+    readonly page: boolean;
+    /** Why a reconnect is offered, or null when none is. `deadline` gives the ISO time it must happen by, within two weeks. */
+    readonly reconnect: {
+        readonly reason: 'needs_reconnect';
+    } | {
+        readonly reason: 'deadline';
+        readonly by: string;
+    } | null;
+}
+/** What a platform is doing besides listing its accounts. */
+export type PlatformStep = 
+/** Nothing: its Connect button is ready. */
+{
+    readonly kind: 'idle';
+}
+/** Asking for the Mastodon server (required) or Bluesky handle (optional) before a connect: call `submitHandle`. */
+ | {
+    readonly kind: 'handle';
+    readonly required: boolean;
+}
+/**
+ * Asking what to connect, when the platform offers its own connect and a variant (LinkedIn: a personal profile or a
+ * company page): call `connect(platform, { variant })` with the answer, `null` for the profile, or `cancel`.
+ */
+ | {
+    readonly kind: 'choose';
+    readonly variants: readonly ConnectVariant[];
+}
+/**
+ * Waiting on the person to finish signing in. `blockedUrl` is set when the browser refused to open the window: offer it
+ * as a link. `variant` is the variant being connected, or null.
+ */
+ | {
+    readonly kind: 'waiting';
+    readonly blockedUrl: string | null;
+    readonly accountId: string | null;
+    readonly variant: ConnectVariant | null;
+}
+/** Asking whether to disconnect `account`: call `confirmDisconnect` or `cancel`. */
+ | {
+    readonly kind: 'confirm';
+    readonly account: AccountItem;
+};
+/** One platform the panel offers. */
+export interface PlatformItem {
+    /** The platform's id. */
+    readonly platform: Platform;
+    /** Its name for people, such as `LinkedIn`. */
+    readonly name: string;
+    /** Its connected accounts, newest first. */
+    readonly accounts: readonly AccountItem[];
+    /** What it is doing now. */
+    readonly step: PlatformStep;
+    /** True while a connect is under way: its other buttons should be disabled. */
+    readonly busy: boolean;
+    /** Whether a connect asks first for a handle (Bluesky, optional) or a server (Mastodon, required); null when it does not. */
+    readonly handlePrompt: {
+        readonly required: boolean;
+    } | null;
+    /**
+     * Whether the platform's own connect is set up (on LinkedIn, the person's profile). False when only a variant is, and
+     * the platform is offered for that alone.
+     */
+    readonly connectable: boolean;
+    /** The other ways it can connect here, such as LinkedIn's `pages`; empty for most platforms. */
+    readonly variants: readonly ConnectVariant[];
+}
+/** The last thing that happened, as data. `message` in the state words it. */
+export type ConnectNotice = 
+/** A connect or reconnect finished. `platform` is null when a redirect came back with no account the panel can see. */
+{
+    readonly kind: 'connected';
+    readonly platform: Platform | null;
+    readonly accounts: readonly Account[];
+    readonly session: ConnectSession | null;
+}
+/** An account was disconnected. */
+ | {
+    readonly kind: 'disconnected';
+    readonly account: Account;
+}
+/** The person took too long to sign in. */
+ | {
+    readonly kind: 'expired';
+    readonly platform: Platform;
+}
+/** A call or a connect failed. `during` says what was being done. */
+ | {
+    readonly kind: 'error';
+    readonly during: 'load' | 'connect' | 'disconnect' | 'redirect';
+    readonly platform: Platform | null;
+    readonly code: string;
+    readonly message: string;
+};
+/** Everything a panel draws, as one immutable snapshot. A new object every time anything changes. */
+export interface ConnectState {
+    /** False until there is a connect token; no call is made without one. */
+    readonly hasToken: boolean;
+    /** True while the platforms and accounts are being read. */
+    readonly loading: boolean;
+    /** True once they have been read at least once. */
+    readonly loaded: boolean;
+    /** The platforms to offer, in the API's order. */
+    readonly platforms: readonly PlatformItem[];
+    /** Every connected account shown, newest first. */
+    readonly accounts: readonly Account[];
+    /** The last thing that happened, or null. */
+    readonly notice: ConnectNotice | null;
+    /** The panel's status line in the labels' words: the notice, or loading, empty and no-token text. `text` is empty when there is nothing to say. */
+    readonly message: {
+        readonly text: string;
+        readonly error: boolean;
+    };
+    /** The words in use, defaults filled in. */
+    readonly labels: ConnectLabels;
+}
+/** What `connect` takes. */
+export interface ConnectOptions {
+    /**
+     * Which way to connect, without asking: `pages` for LinkedIn company pages, or `null` for the platform's own connect (a
+     * LinkedIn personal profile). Left out, a platform that offers both asks first (the step becomes `choose`), and one
+     * that offers only a variant connects that.
+     */
+    variant?: ConnectVariant | null | undefined;
+}
+/** What a panel can do. Start a connect straight from a click or submit handler: a browser opens a window only during one. */
+export interface ConnectActions {
+    /**
+     * Connects a new account on `platform`. It asks first when it must: for a handle (the step becomes `handle`), or, when
+     * the platform offers a variant and `options.variant` is left out, what to connect (the step becomes `choose`).
+     */
+    connect(platform: Platform, options?: ConnectOptions): void;
+    /** Sends the Mastodon server or Bluesky handle the step asked for and starts the connect. Blank means none. */
+    submitHandle(platform: Platform, handle: string): void;
+    /** Reconnects an account that needs it. */
+    reconnect(accountId: string): void;
+    /** Asks to disconnect an account: the step becomes `confirm`. Nothing is sent yet. */
+    requestDisconnect(accountId: string): void;
+    /** Disconnects the account the platform's `confirm` step is asking about. */
+    confirmDisconnect(platform: Platform): Promise<void>;
+    /** Stops waiting on a connect, or closes the handle or confirm question. */
+    cancel(platform: Platform): void;
+    /** Clears the notice. */
+    dismissNotice(): void;
+    /** Reads the platforms and accounts again. */
+    refresh(): Promise<void>;
+}
+/** The headless panel: state, a way to hear it change, the actions, and the means to change options or stop. */
+export interface ConnectController extends ConnectActions {
+    /** The current snapshot. The same object until something changes, as `useSyncExternalStore` needs. */
+    getState(): ConnectState;
+    /** Calls `listener` after every change. Returns the function that stops it. */
+    subscribe(listener: () => void): () => void;
+    /** Changes the options a panel may change while it is shown. A new platform list reads the accounts again. */
+    configure(options: {
+        platforms?: readonly Platform[] | null | undefined;
+        mode?: 'popup' | 'redirect' | undefined;
+        labels?: Partial<ConnectLabels> | undefined;
+    }): void;
+    /** Stops every wait, drops every listener, and ignores answers still on their way. */
+    destroy(): void;
+}
+/** What `createConnectController` takes. */
+export interface ConnectControllerOptions {
+    /** A connect token from your server, or a function that fetches a fresh one. Null makes no call. */
+    token: TokenSource | null;
+    /** Where the API lives; production when left out. The token is sent there and nowhere else. */
+    baseUrl?: string | undefined;
+    /** Offer only these platforms. */
+    platforms?: readonly Platform[] | null | undefined;
+    /** `popup` (the default) opens a small window; `redirect` sends the whole page to the platform and back. */
+    mode?: 'popup' | 'redirect' | undefined;
+    /** A `fetch` to use instead of the global one. */
+    fetch?: typeof fetch | undefined;
+    /** Any of the words, for `message` and the notices. */
+    labels?: Partial<ConnectLabels> | undefined;
+    /** Reads, reports and removes the result Flung put on the address after a redirect. True when left out. */
+    readRedirect?: boolean | undefined;
+    /** The accounts were read. */
+    onLoad?: ((detail: LoadDetail) => void) | undefined;
+    /** A connect or reconnect finished. */
+    onConnect?: ((detail: ConnectDetail) => void) | undefined;
+    /** An account was disconnected. */
+    onDisconnect?: ((detail: DisconnectDetail) => void) | undefined;
+    /** A call or a connect failed. */
+    onError?: ((detail: ErrorDetail) => void) | undefined;
+}
+/**
+ * The connect panel with no markup: it reads the platforms and accounts, runs connects, reconnects and disconnects, and
+ * keeps one immutable snapshot of it all. `<flung-connect>` and `useFlungConnect` are drawn from it; a page can draw its
+ * own panel from it too. It starts reading as soon as it has a token.
+ */
+export declare function createConnectController(options: ConnectControllerOptions): ConnectController;
+/** The snapshot a panel with no controller yet shows, the same object every time for each `hasToken`. */
+export declare function initialConnectState(hasToken: boolean): ConnectState;