@flung.dev/connect 0.1.2 → 0.3.0

package/dist/core/types.d.ts

@@ -4,21 +4,41 @@
  */
 export declare const PLATFORMS: readonly ['x', 'instagram', 'facebook', 'threads', 'linkedin', 'tiktok', 'youtube', 'pinterest', 'bluesky', 'mastodon', 'discord', 'farcaster'];
 export type Platform = (typeof PLATFORMS)[number];
+/**
+ * Another way to connect a platform, on an app of its own: LinkedIn's `pages` connects the company pages the person
+ * administers, one account per page, instead of their own profile.
+ */
+export type ConnectVariant = 'pages';
+export declare const CONNECT_VARIANTS: readonly ConnectVariant[];
 export interface PlatformInfo {
     platform: Platform;
     /** Whether this Flung has the platform's app credentials, so accounts can be connected. */
     connectable: boolean;
+    /** The connect variants set up here, such as LinkedIn's `pages`. Optional: an API older than the field leaves it out. */
+    variants?: string[] | undefined;
 }
 export type AccountStatus = 'active' | 'needs_reconnect' | 'disconnected';
+/** A connected social account, as `GET /v1/accounts` returns it. */
 export interface Account {
+    /** Flung's id for the account. */
     id: string;
+    /** The platform it is on. */
     platform: Platform;
+    /** The platform's own id for the user. */
     platformUserId: string;
+    /** The handle on the platform, without the `@`, when it has one. */
     username: string | null;
+    /** The name the person shows on the platform. Optional: an API older than the field leaves it out. */
+    displayName?: string | null;
+    /** The person's profile picture on the platform, an `https` address. Optional: an API older than the field leaves it out. */
+    avatarUrl?: string | null;
+    /** The Flung profile it belongs to, or null for the whole workspace. */
     profileId: string | null;
+    /** `active`, `needs_reconnect` or `disconnected`. */
     status: AccountStatus;
     /** When the person must reconnect by, for platforms whose connections cannot be renewed forever. */
     reconnectBy: string | null;
+    /** When it was first connected. */
     createdAt: string;
 }
 export type ConnectSessionStatus = 'pending' | 'connected' | 'failed' | 'expired';

package/dist/core/types.js

@@ -3,3 +3,4 @@
  * the API's own (`spec/openapi.json`): `PlatformInfo`, `Account` and `ConnectSession`, trimmed to what is used.
  */
 export const PLATFORMS = ['x', 'instagram', 'facebook', 'threads', 'linkedin', 'tiktok', 'youtube', 'pinterest', 'bluesky', 'mastodon', 'discord', 'farcaster'];
+export const CONNECT_VARIANTS = ['pages'];

package/dist/element/copy.d.ts

@@ -1,39 +1,3 @@
-/**
- * Every word the panel shows, in English. Pass `labels` to put it in another language; `{platform}`, `{account}`,
- * `{message}`, `{date}` and `{count}` are filled in where a label has them.
- */
-export interface ConnectLabels {
-    /** The panel's name for a screen reader. */
-    panel: string;
-    connect: string;
-    connectAnother: string;
-    reconnect: string;
-    disconnect: string;
-    confirmDisconnect: string;
-    keep: string;
-    cancel: string;
-    continue: string;
-    handleBluesky: string;
-    handleMastodon: string;
-    waiting: string;
-    blocked: string;
-    openSignIn: string;
-    connected: string;
-    failed: string;
-    expired: string;
-    disconnected: string;
-    needsReconnect: string;
-    reconnectBy: string;
-    /** Under a platform's name once it has accounts. */
-    connectedCount: string;
-    /** Under a platform's name before it has any. */
-    notConnected: string;
-    /** Before Flung's name in the panel's footer, which `branding="none"` hides. */
-    securedBy: string;
-    loading: string;
-    loadFailed: string;
-    empty: string;
-    noToken: string;
-}
-export declare const DEFAULT_LABELS: ConnectLabels;
-export declare function format(template: string, values: Readonly<Record<string, string>>): string;
+/** The panel's words live in core, so the headless controller words its status line the same way as the element. */
+export { DEFAULT_LABELS, formatLabel as format } from '../core/labels.js';
+export type { ConnectLabels } from '../core/labels.js';

package/dist/element/copy.js

@@ -1,32 +1,2 @@
-export const DEFAULT_LABELS = {
-    panel: 'Connected accounts',
-    connect: 'Connect',
-    connectAnother: 'Add another',
-    reconnect: 'Reconnect',
-    disconnect: 'Disconnect',
-    confirmDisconnect: 'Disconnect {account}? Posts to it will stop.',
-    keep: 'Keep it',
-    cancel: 'Cancel',
-    continue: 'Continue',
-    handleBluesky: 'Your Bluesky handle, such as alice.bsky.social (optional)',
-    handleMastodon: 'Your Mastodon server, such as mastodon.social',
-    waiting: 'Finish signing in to {platform} in the window that opened.',
-    blocked: 'Your browser did not open the {platform} window.',
-    openSignIn: 'Open {platform} sign-in',
-    connected: '{platform} is connected.',
-    failed: '{platform} was not connected: {message}',
-    expired: 'Signing in to {platform} took too long. Try again.',
-    disconnected: '{account} is disconnected.',
-    needsReconnect: 'Needs reconnecting',
-    reconnectBy: 'Reconnect by {date}',
-    connectedCount: '{count} connected',
-    notConnected: 'Not connected',
-    securedBy: 'Secured by',
-    loading: 'Loading accounts…',
-    loadFailed: 'Could not load accounts: {message}',
-    empty: 'There is nothing to connect here.',
-    noToken: 'This panel has no connect token yet.',
-};
-export function format(template, values) {
-    return template.replace(/\{(\w+)\}/g, (whole, name) => values[name] ?? whole);
-}
+/** The panel's words live in core, so the headless controller words its status line the same way as the element. */
+export { DEFAULT_LABELS, formatLabel as format } from '../core/labels.js';

package/dist/element/dom.d.ts

@@ -3,21 +3,37 @@
  * supplies (an account name, an error message) can become markup. Attributes go through `setAttribute`, text through
  * `textContent`.
  */
+import type { AccountItem } from '../core/controller.js';
 import type { Account } from '../core/types.js';
 type Attributes = Readonly<Record<string, string | number | boolean | undefined>>;
 /** An HTML element of the element's own. `true` sets an empty attribute; `false` and `undefined` set none. */
 export declare function html<K extends keyof HTMLElementTagNameMap>(tag: K, attributes?: Attributes, ...children: (Node | string | null)[]): HTMLElementTagNameMap[K];
-/** How an account is named in the panel: its username, or its platform id when it has none. */
+/** How an account is named in the panel's messages: its username, or its platform id when it has none. */
 export declare function displayName(account: Account): string;
-/** A button that calls `onClick`, with a `data-key` so focus can be put back on it after the panel is drawn again. */
-export declare function button(text: string, key: string, onClick: () => void, options?: {
-    primary?: boolean;
-    danger?: boolean;
-    warning?: boolean;
-    quiet?: boolean;
+/** A button's look: `primary` for the first Connect, `secondary` for the rest, `quiet` for Disconnect, `danger` to confirm one. */
+export type ButtonVariant = 'primary' | 'secondary' | 'quiet' | 'danger';
+/**
+ * A button that calls `onClick`, with a `data-key` so focus can be put back on it after the panel is drawn again. Its
+ * `part` is `button`, `button-<variant>` and `button-<role>`, so a page can style every button, a kind, or one of them.
+ */
+export declare function button(text: string, key: string, role: string, onClick: () => void, options?: {
+    variant?: ButtonVariant;
     disabled?: boolean;
     label?: string;
+    expanded?: boolean;
+    controls?: string;
 }): HTMLButtonElement;
 /** An icon drawn from one path, for the platform marks and Flung's own. Hidden from screen readers: the name beside it says what it is. */
-export declare function mark(path: string, viewBox?: string, className?: string): SVGSVGElement;
+export declare function mark(path: string, options?: {
+    viewBox?: string;
+    className?: string;
+    part?: string;
+    size?: number;
+}): SVGSVGElement;
+/**
+ * An account's picture: an `<img>` that sends no referrer, loads lazily and has an empty `alt` (the name is beside it),
+ * or a circle with the account's initial when there is no picture or it does not load. `avatarUrl` is only ever an
+ * `https` address (the controller drops anything else).
+ */
+export declare function avatar(item: AccountItem): HTMLElement;
 export {};

package/dist/element/dom.js

@@ -16,22 +16,40 @@ export function html(tag, attributes = {}, ...children) {
             element.append(child);
     return element;
 }
-/** How an account is named in the panel: its username, or its platform id when it has none. */
+/** How an account is named in the panel's messages: its username, or its platform id when it has none. */
 export function displayName(account) {
     return account.username ?? account.platformUserId;
 }
-/** A button that calls `onClick`, with a `data-key` so focus can be put back on it after the panel is drawn again. */
-export function button(text, key, onClick, options = {}) {
-    const className = [options.primary === true && 'primary', options.danger === true && 'danger', options.warning === true && 'warning', options.quiet === true && 'quiet'].filter(Boolean).join(' ') || undefined;
-    const element = html('button', { type: 'button', class: className, 'data-key': key, disabled: options.disabled === true, 'aria-label': options.label }, text);
+/**
+ * A button that calls `onClick`, with a `data-key` so focus can be put back on it after the panel is drawn again. Its
+ * `part` is `button`, `button-<variant>` and `button-<role>`, so a page can style every button, a kind, or one of them.
+ */
+export function button(text, key, role, onClick, options = {}) {
+    const variant = options.variant ?? 'secondary';
+    const element = html('button', {
+        type: 'button',
+        class: variant,
+        part: `button button-${variant} button-${role}`,
+        'data-key': key,
+        disabled: options.disabled === true,
+        'aria-label': options.label,
+        // A button that opens a question inside the panel says whether it is open, and which question.
+        'aria-expanded': options.expanded === undefined ? undefined : String(options.expanded),
+        'aria-controls': options.controls,
+    }, text);
     element.addEventListener('click', onClick);
     return element;
 }
 /** An icon drawn from one path, for the platform marks and Flung's own. Hidden from screen readers: the name beside it says what it is. */
-export function mark(path, viewBox = '0 0 24 24', className = 'mark') {
+export function mark(path, options = {}) {
     const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
-    svg.setAttribute('viewBox', viewBox);
-    svg.setAttribute('class', className);
+    svg.setAttribute('viewBox', options.viewBox ?? '0 0 24 24');
+    svg.setAttribute('class', options.className ?? 'mark');
+    svg.setAttribute('part', options.part ?? 'mark');
+    // Presentation attributes: any stylesheet overrides them, and an unstyled panel still draws a sensible size.
+    svg.setAttribute('width', String(options.size ?? 20));
+    svg.setAttribute('height', String(options.size ?? 20));
+    svg.setAttribute('fill', 'currentColor');
     svg.setAttribute('aria-hidden', 'true');
     svg.setAttribute('focusable', 'false');
     const shape = document.createElementNS('http://www.w3.org/2000/svg', 'path');
@@ -39,3 +57,17 @@ export function mark(path, viewBox = '0 0 24 24', className = 'mark') {
     svg.append(shape);
     return svg;
 }
+/**
+ * An account's picture: an `<img>` that sends no referrer, loads lazily and has an empty `alt` (the name is beside it),
+ * or a circle with the account's initial when there is no picture or it does not load. `avatarUrl` is only ever an
+ * `https` address (the controller drops anything else).
+ */
+export function avatar(item) {
+    const initial = html('span', { class: 'avatar initial', part: 'avatar avatar-initial', 'aria-hidden': 'true' }, item.initial);
+    if (item.avatarUrl === null)
+        return initial;
+    const image = html('img', { class: 'avatar', part: 'avatar avatar-image', alt: '', referrerpolicy: 'no-referrer', loading: 'lazy', decoding: 'async', width: 32, height: 32 });
+    image.addEventListener('error', () => image.replaceWith(initial), { once: true });
+    image.src = item.avatarUrl;
+    return image;
+}

package/dist/element/events.d.ts

@@ -1,31 +1,21 @@
-import type { Account, ConnectSession } from '../core/types.js';
-/** `flung-load`: the accounts were read, on first show and after every change. */
-export interface LoadDetail {
-    /** The connected accounts the panel shows, newest first. */
-    accounts: Account[];
-}
-/** `flung-connect`: a connect or reconnect finished. `accounts` are the ones stored; Facebook stores one per page. */
-export interface ConnectDetail {
-    /** The connect session, or null when the person came back from a redirect. */
-    session: ConnectSession | null;
-    /** The accounts stored. */
-    accounts: Account[];
-}
-/** `flung-disconnect`: an account was disconnected. */
-export interface DisconnectDetail {
-    /** The account, now `disconnected`. */
-    account: Account;
-}
-/** `flung-error`: a call or a connect failed. `code` is the API's stable code, such as `forbidden` or `access_denied`. */
-export interface ErrorDetail {
-    /** The API's stable code, or the platform's, such as `access_denied`. */
-    code: string;
-    /** What went wrong, for a person. */
-    message: string;
+import type { ConnectState } from '../core/controller.js';
+import type { ConnectDetail, DisconnectDetail, ErrorDetail, LoadDetail } from '../core/events.js';
+export type { ConnectDetail, DisconnectDetail, ErrorDetail, LoadDetail } from '../core/events.js';
+/** `flung-change`: the panel's state changed. Does not bubble; for a page that draws parts of the panel itself. */
+export interface ChangeDetail {
+    /** The new snapshot. */
+    state: ConnectState;
 }
+/** The element's events, for `addEventListener` types. */
 export interface FlungConnectEventMap {
+    /** The accounts were read. */
     'flung-load': CustomEvent<LoadDetail>;
+    /** A connect or reconnect finished. */
     'flung-connect': CustomEvent<ConnectDetail>;
+    /** An account was disconnected. */
     'flung-disconnect': CustomEvent<DisconnectDetail>;
+    /** A call or a connect failed. */
     'flung-error': CustomEvent<ErrorDetail>;
+    /** The state changed. */
+    'flung-change': CustomEvent<ChangeDetail>;
 }

package/dist/element/flung-connect.d.ts

@@ -1,11 +1,31 @@
 import type { TokenSource } from '../core/client.js';
-import type { ConnectLabels } from './copy.js';
+import type { ConnectController, ConnectOptions, ConnectState } from '../core/controller.js';
+import type { ConnectLabels } from '../core/labels.js';
+import type { Platform } from '../core/types.js';
+/** How the platforms are laid out: `list` (the default) one under another, `grid` as cards side by side, `compact` tighter. */
+export type FlungConnectLayout = 'list' | 'grid' | 'compact';
+/**
+ * How a platform with a connect variant (LinkedIn: a personal profile or company pages) is offered: `choose` (the
+ * default) asks which after Connect, inside the panel; `tiles` shows each as its own platform, such as LinkedIn and
+ * LinkedIn Page.
+ */
+export type FlungConnectVariants = 'choose' | 'tiles';
 /** `<flung-connect>` as a page sees it. */
 export interface FlungConnectElement extends HTMLElement {
     /** A connect token, or a function that fetches a fresh one from your server. The `token` attribute sets a string. */
     token: TokenSource | null;
+    /** Every word the panel shows. Setting it fills in the defaults for any left out. */
     get labels(): ConnectLabels;
     set labels(value: Partial<ConnectLabels> | undefined);
+    /** The panel's current state, the same snapshot `flung-change` carries. */
+    readonly state: ConnectState;
+    /** The headless controller behind the panel, for a page that draws parts of it itself; null until the element is on a page. A new token makes a new one. */
+    readonly controller: ConnectController | null;
+    /**
+     * Starts a connect, as the platform's Connect button does. Call it straight from a click: a browser opens a window only
+     * during one. `{ variant: 'pages' }` connects LinkedIn company pages without asking, `{ variant: null }` the profile.
+     */
+    connect(platform: Platform, options?: ConnectOptions): void;
     /** Reads the accounts again, as after a connect. */
     refresh(): Promise<void>;
 }