@dinghy-chat/widget 0.16.0 → 0.17.0

package/README.md

@@ -21,7 +21,7 @@ const dinghy = init({ url: "https://chat.example.com", key: "YOUR_PUBLIC_KEY" })
 dinghy.on("unread", (count) => console.log(count));
 ```
 
-`init` adds the tag once and returns the typed `Dinghy` object. Calls made before the script loads wait for it. It takes `url`, `key`, and `primary`, `accent`, `mascot`, `launcher`, `position`, `offsetX`, `offsetY` and `zIndex`.
+`init` adds the tag once and returns the typed `Dinghy` object. Calls made before the script loads wait for it. It takes `url`, `key`, and `primary`, `accent`, `mascot`, `branding`, `launcher`, `position`, `offsetX`, `offsetY` and `zIndex`.
 
 ## Attributes
 

package/dist/index.d.ts

@@ -3,10 +3,12 @@ export type { Appearance, DinghyApi, DinghyEvent, DinghyEvents, DinghyState, Ide
 export interface InitOptions extends Appearance {
     /** Your Dinghy server, such as `https://chat.example.com`. */
     url: string;
-    /** The workspace's public key, from Settings > Widget snippet. */
+    /** The workspace's public key, from Settings > Install. */
     key: string;
-    /** False removes the boat. Every state keeps its text. */
+    /** Hides or shows the boat in the open chat, over the saved setting. Every state keeps its text. */
     mascot?: boolean;
+    /** Hides or shows the "Powered by Dinghy" line, over the saved setting. */
+    branding?: boolean;
     /** False hides the launcher, so your own button opens the chat. */
     launcher?: boolean;
 }

package/dist/index.js

@@ -58,7 +58,8 @@ function init(options) {
     ["position", options.position],
     ["offset-x", options.offsetX],
     ["offset-y", options.offsetY],
-    ["mascot", options.mascot === false ? "false" : void 0],
+    ["mascot", options.mascot === void 0 ? void 0 : String(options.mascot)],
+    ["branding", options.branding === void 0 ? void 0 : String(options.branding)],
     ["launcher", options.launcher === false ? "hidden" : void 0]
   ];
   for (const [name, value] of attributes) {

package/dist/shared.d.ts

@@ -17,6 +17,63 @@ export interface Appearance {
     offsetY?: number;
     zIndex?: number;
 }
+/** What an owner saves in the operator app's Widget tab. Null texts and colors mean the widget's own. */
+export interface WidgetSettings {
+    title: string | null;
+    greeting: string | null;
+    away: string | null;
+    /** A full hex color, as `primary` in configure(). */
+    primary: string | null;
+    accent: string | null;
+    position: "left" | "right";
+    theme: "light" | "dark" | "auto";
+    launcher: "boat" | "bubble" | "hidden";
+    /** The boat in the open chat. */
+    mascot: boolean;
+    /** Pixels, for the chat's corners and the launcher's. */
+    radius: number;
+    emailAsk: "off" | "after_first" | "before_first";
+    /** The "Powered by Dinghy" line. */
+    branding: boolean;
+}
+/** A member the widget's header shows: a first name and a picture, never an email. */
+export interface TeamFace {
+    /** A hash of the operator's ID, the same as `authorId` on their replies. It tells two members
+     * with one first name apart. */
+    id: string;
+    name: string;
+    pictureUrl: string | null;
+}
+/** The saved settings, as the widget's appearance route answers them. */
+export interface SavedAppearance extends WidgetSettings {
+    logoUrl: string | null;
+    /** Up to 3 members, the ones who sent the latest replies. */
+    team: TeamFace[];
+}
+/** The longest title an owner can save. */
+export declare const TITLE_MAX = 40;
+/** The longest greeting or away text. */
+export declare const TEXT_MAX = 200;
+/** The roundest corners an owner can save. */
+export declare const RADIUS_MAX_PX = 24;
+/** The widget's own colors, which a null color in the settings keeps. */
+export declare const DEFAULT_COLORS: {
+    primary: string;
+    accent: string;
+};
+/** What a new workspace saves, and what the widget shows when the server cannot answer. */
+export declare const WIDGET_DEFAULTS: SavedAppearance;
+/**
+ * The first word of a name, which is all a visitor learns of an operator. It stops at an @ too, so
+ * a name typed as an email never shows one.
+ */
+export declare const firstName: (name: string) => string;
+/**
+ * Asks for the saved settings, once a page. Null means the workspace serves no widget, and
+ * undefined that the server gave no answer, so WIDGET_DEFAULTS apply. The loader has no bytes for
+ * that object, so it leaves those values to its CSS, which holds the same ones.
+ */
+export declare const loadAppearance: (base: string, publicKey: string) => Promise<SavedAppearance | null | undefined>;
 export interface DinghyState {
     /** The chat bundle has loaded. */
     ready: boolean;
@@ -71,13 +128,23 @@ interface ChatHandlers {
 export type Listeners = {
     [E in DinghyEvent]?: Set<(data: DinghyEvents[E]) => void>;
 };
+/**
+ * The shape of WidgetContext. Bump it in any change to what the loader or page.js hands the chat
+ * bundle: a tab keeps the loader it started with for days, and the chat bundle replaces a loader
+ * with another number instead of reading a context it does not know.
+ */
+export declare const CONTEXT_VERSION = 1;
 /** What the loader hands to the chat bundle. */
 export interface WidgetContext {
+    /** CONTEXT_VERSION, as the loader knew it. Loaders before it set none. */
+    version: number;
     publicKey: string;
     base: string;
     shadow: ShadowRoot;
-    /** False when the page set data-mascot="false". Every state still has its text. */
-    mascot: boolean;
+    /** The saved settings, which the loader asked for. See loadAppearance. */
+    appearance: Promise<SavedAppearance | null | undefined>;
+    /** Reads the tag's data attributes by dataset name, such as `mascot`. They win over the saved settings. */
+    attribute(name: string): string | undefined;
     /** The full-page chat that a reply email opens, on the Dinghy server's own origin. */
     page?: boolean;
     /** Set by identify() and cleared by reset(). */
@@ -100,8 +167,9 @@ export declare function writeToken(publicKey: string, token: string | null): voi
 export declare function wasOpen(publicKey: string): boolean;
 export declare function rememberOpen(publicKey: string, open: boolean): void;
 /**
- * Tells other tabs of this site to start again. A storage event fires only in other tabs. The key
- * goes at once, so nothing stays stored for a visitor who never chatted.
+ * Clears this browser's token, and tells other tabs of this site to start again. A storage event
+ * fires only in other tabs. The key goes at once, so nothing stays stored for a visitor who never
+ * chatted.
  */
-export declare function broadcastReset(publicKey: string): void;
+export declare function forgetVisitor(publicKey: string): void;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dinghy-chat/widget",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Add the Dinghy chat to your site from code, with a typed API.",
   "type": "module",
   "license": "MIT",