@signalcore/ui 0.1.0 → 1.0.0-beta.1

package/src/widget/element.tsx

@@ -0,0 +1,535 @@
+/// <reference path="./css.d.ts" />
+import { ChatCircleDotsIcon, XIcon } from "@phosphor-icons/react";
+import { useMemo, useState } from "react";
+import { createRoot, type Root } from "react-dom/client";
+
+import type { ChatSteps } from "../AgentChat";
+import { AgentSpace, SPACE_MESSAGES } from "../AgentSpace";
+import { createClient } from "../client";
+import type { Credentials } from "../credentials";
+import { SPACE_MESSAGES_ES } from "../es";
+import { es } from "../locale";
+import styles from "../styles.css?inline";
+import type { WidgetConfig, WidgetLook } from "../types";
+import own from "./widget.css?inline";
+
+/** The tag the widget registers. */
+export const TAG = "signalcore-chat";
+
+/** What the page says on the element; a change to any of them draws it again. */
+const ATTRIBUTES = [
+  "base-url",
+  "agent",
+  "publishable-key",
+  "token",
+  "theme",
+  "locale",
+  "mode",
+  "header",
+  "steps",
+  "stylesheet",
+  "unstyled",
+  "shadow",
+  "contained",
+] as const;
+
+type Attribute = (typeof ATTRIBUTES)[number];
+
+/** The two languages the widget speaks. */
+type Language = "es" | "en";
+
+/** What the widget is drawn from, as its attributes say it. */
+export interface WidgetSettings {
+  /** The public API: its origin and `/v1`. */
+  baseUrl: string;
+  /** The agent; null: the web channel its publishable key belongs to names it. */
+  agent: string | null;
+  /**
+   * Who the page speaks for: a person, by the token the host minted; a visitor of the site; or,
+   * with neither, the page's own sign-in (SignalCore's app, previewing the widget).
+   */
+  credential: Credentials;
+  language: Language;
+  /** A button at the page's corner that opens a panel; or the panel in the page's flow. */
+  mode: "floating" | "inline";
+  /** The agent's face over the space (`header`); off unless the page asks. */
+  header: boolean;
+  /** Whether the agent's steps show (`steps`); as the page speaks (hidden for its people) unless said. */
+  steps: ChatSteps | undefined;
+  /** Floating within the element's own box (`contained`), not at the page's corner: a preview. */
+  contained: boolean;
+}
+
+/** The launcher's words, by language. */
+const LAUNCHER: Readonly<Record<Language, { open: string; close: string; chat: string }>> = {
+  en: { open: "Open the chat", close: "Close the chat", chat: "Chat" },
+  es: { open: "Abrir el chat", close: "Cerrar el chat", chat: "Chat" },
+};
+
+/**
+ * The language asked for (`locale`), else the page's own (`<html lang>`), else the browser's:
+ * Spanish for any `es`, English otherwise.
+ */
+export function languageOf(locale: string | null): Language {
+  const asked = locale || document.documentElement.lang || navigator.language;
+  return asked.toLowerCase().startsWith("es") ? "es" : "en";
+}
+
+/** Whether a boolean attribute is on: present, and not `"false"`. */
+const on = (element: Element, name: Attribute): boolean =>
+  element.hasAttribute(name) && element.getAttribute(name) !== "false";
+
+/**
+ * The settings an element's attributes give, or null while one it needs is missing: the API, and
+ * the agent, which only a publishable key may leave to its web channel.
+ */
+export function settingsOf(element: Element): WidgetSettings | null {
+  const read = (name: Attribute) => element.getAttribute(name) || null;
+  const baseUrl = read("base-url");
+  const agent = read("agent");
+  const token = read("token");
+  const publishableKey = read("publishable-key");
+  const credential: Credentials =
+    token !== null
+      ? { token }
+      : publishableKey !== null
+        ? { publishableKey }
+        : { credentials: "cookie" };
+  if (baseUrl === null || (agent === null && publishableKey === null)) return null;
+  const steps = read("steps");
+  return {
+    baseUrl,
+    agent,
+    credential,
+    language: languageOf(read("locale")),
+    mode: read("mode") === "inline" ? "inline" : "floating",
+    header: on(element, "header"),
+    steps: steps === "shown" || steps === "hidden" ? steps : undefined,
+    contained: on(element, "contained"),
+  };
+}
+
+/**
+ * A look as the widget's own stylesheet: its tokens on the host (`:host` in its shadow root, the
+ * element itself when drawn into the page), where the page's own rules for the element still
+ * win, then its CSS. The font is the face's name; `loadFont` brings the face.
+ */
+export function lookCss(look: WidgetLook, host: string): string {
+  const px = (value: number | null | undefined) => (value == null ? null : `${String(value)}px`);
+  const tokens: [string, string | null | undefined][] = [
+    ["--sc-accent", look.accent],
+    ["--sc-accent-fg", look.accent_fg],
+    ["--sc-font", look.font && `"${look.font}", ui-sans-serif, system-ui, sans-serif`],
+    ["--sc-radius", px(look.radius)],
+    ["--sc-launcher-size", px(look.launcher_size)],
+    ["--sc-panel-width", px(look.panel_width)],
+    ["--sc-panel-height", px(look.panel_height)],
+    ["color-scheme", look.theme === "light" || look.theme === "dark" ? look.theme : null],
+  ];
+  const said = tokens.flatMap(([name, value]) => (value ? [`${name}: ${value};`] : []));
+  const rule = said.length > 0 ? `${host} { ${said.join(" ")} }` : "";
+  return [rule, look.css ?? ""].filter(Boolean).join("\n");
+}
+
+/** The face from Google Fonts, in the page's head (where a shadow root's text finds it), once. */
+export function loadFont(font: string) {
+  if (document.querySelector(`link[data-signalcore-font="${font}"]`) !== null) return;
+  const family = encodeURIComponent(font).replace(/%20/g, "+");
+  const link = linkTo(
+    `https://fonts.googleapis.com/css2?family=${family}:wght@400;500;600&display=swap`,
+  );
+  link.setAttribute("data-signalcore-font", font);
+  document.head.append(link);
+}
+
+/**
+ * How light a CSS colour is, from 0 (black) to 1 (white), as a browser gives a computed one:
+ * `rgb()`, `rgba()`, `color(srgb …)`, `oklab()`, `oklch()`, `lab()`, `lch()`; null for any other.
+ */
+export function lightnessOf(color: string): number | null {
+  const open = color.indexOf("(");
+  if (open < 0) return null;
+  const space = color.slice(0, open).trim().toLowerCase();
+  const inside = color.slice(open + 1);
+  // `color()` names its space first: only sRGB's channels are read as they are.
+  if (space === "color" && !/^\s*srgb\s/i.test(inside)) return null;
+  const values = inside
+    .replace(/^\s*srgb\s/i, "")
+    .match(/-?\d*\.?\d+(?:e-?\d+)?%?/gi)
+    ?.map((value) => (value.endsWith("%") ? Number.parseFloat(value) / 100 : Number(value)));
+  if (values === undefined) return null;
+  const [a, b, c] = values;
+  const luminance = (red: number, green: number, blue: number) =>
+    0.2126 * red + 0.7152 * green + 0.0722 * blue;
+  if (a === undefined) return null;
+  switch (space) {
+    case "rgb":
+    case "rgba":
+      return b === undefined || c === undefined ? null : luminance(a, b, c) / 255;
+    case "color":
+      return b === undefined || c === undefined ? null : luminance(a, b, c);
+    case "oklab":
+    case "oklch":
+      return a;
+    case "lab":
+    case "lch":
+      return a / 100;
+    default:
+      return null;
+  }
+}
+
+/**
+ * Whether the widget wears its dark palette by the page's text: only where the page names no
+ * `color-scheme` (`normal`) and its text is light, as on a page made dark by its own classes.
+ */
+export function darkByInk(colorScheme: string, color: string): boolean {
+  if (colorScheme !== "" && colorScheme !== "normal") return false;
+  const lightness = lightnessOf(color);
+  return lightness !== null && lightness > 0.6;
+}
+
+/** Whether the page's stylesheet for the widget is CSS itself, or the address of one. */
+const isCss = (stylesheet: string): boolean => stylesheet.includes("{");
+
+/** A stylesheet of this CSS. */
+function cssOf(text: string): HTMLStyleElement {
+  const style = document.createElement("style");
+  style.textContent = text;
+  return style;
+}
+
+/** The stylesheet at this address. */
+function linkTo(address: string): HTMLLinkElement {
+  const link = document.createElement("link");
+  link.rel = "stylesheet";
+  link.href = address;
+  return link;
+}
+
+/** Where the page keeps the visitor's conversation with an agent, so a visit goes on with it. */
+const conversationKey = (agent: string): string => `signalcore.conversation.${agent}`;
+
+function keptConversation(agent: string): string | undefined {
+  try {
+    return localStorage.getItem(conversationKey(agent)) ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function keepConversation(agent: string, id: string) {
+  try {
+    localStorage.setItem(conversationKey(agent), id);
+  } catch {
+    // A page that can't keep anything starts a new conversation each visit.
+  }
+}
+
+/** Our stylesheet in the page itself, once, first in its head so the page's own CSS wins. */
+function stylePage() {
+  if (document.querySelector("style[data-signalcore-ui]") !== null) return;
+  const style = document.createElement("style");
+  style.setAttribute("data-signalcore-ui", "");
+  style.textContent = `${styles}\n${own}`;
+  document.head.prepend(style);
+}
+
+/** What the widget draws: its settings with the agent known, and its look, if it has one. */
+export interface WidgetProps {
+  settings: WidgetSettings & { agent: string };
+  look?: WidgetLook | null | undefined;
+}
+
+/**
+ * The widget: the agent's space (`AgentSpace`) in a panel, opened from a round button at the
+ * page's corner (the left one if its look says so), or (`inline`) in the page's flow at the
+ * element's size. The conversation it opens is kept in the page's storage for the next visit.
+ */
+export function Widget({ settings, look = null }: WidgetProps) {
+  const { baseUrl, agent, credential, language, mode, steps, contained } = settings;
+  const signedAs = credential.token ?? credential.publishableKey ?? "cookie";
+  // One client while the page says the same; a new token (the host's, renewed) makes another.
+  const client = useMemo(() => createClient({ baseUrl, ...credential }), [baseUrl, signedAs]);
+  const [open, setOpen] = useState(false);
+  const words = LAUNCHER[language];
+  const floating = mode === "floating";
+  const header = settings.header || look?.header === true;
+
+  const space = (
+    <div part="panel" role="dialog" aria-label={words.chat} className="sc-widget__panel">
+      <AgentSpace
+        key={agent}
+        client={client}
+        agentId={agent}
+        conversationId={keptConversation(agent)}
+        onConversation={(id) => {
+          keepConversation(agent, id);
+        }}
+        layout={floating ? "compact" : "full"}
+        header={header}
+        steps={steps}
+        messages={language === "es" ? SPACE_MESSAGES_ES : SPACE_MESSAGES}
+        locale={language === "es" ? es : undefined}
+        onClose={
+          floating
+            ? () => {
+                setOpen(false);
+              }
+            : undefined
+        }
+      />
+    </div>
+  );
+
+  if (!floating) return <div className="sc sc-widget sc-widget--inline">{space}</div>;
+  const classes = [
+    "sc sc-widget sc-widget--floating",
+    open && "sc-widget--open",
+    look?.position === "left" && "sc-widget--left",
+    contained && "sc-widget--contained",
+  ];
+  return (
+    <div className={classes.filter(Boolean).join(" ")}>
+      {open && space}
+      <button
+        type="button"
+        part="launcher"
+        aria-label={open ? words.close : words.open}
+        aria-expanded={open}
+        onClick={() => {
+          setOpen(!open);
+        }}
+        className="sc-widget__launcher"
+      >
+        {open ? (
+          <XIcon aria-hidden weight="bold" />
+        ) : (
+          <ChatCircleDotsIcon aria-hidden weight="fill" />
+        )}
+      </button>
+    </div>
+  );
+}
+
+/**
+ * `<signalcore-chat>`: the widget as a web component, for a page built without React. It draws
+ * into a shadow root holding the package's stylesheet (or, `shadow="none"`, into the page, the
+ * stylesheet first in its head), takes the page's type and ink, and lets in its `--sc-*` tokens,
+ * `::part()` and its own stylesheet (`stylesheet`: CSS, or its address). Its attributes say where
+ * the API is (`base-url`), the agent, who the page speaks for (`publishable-key`, or `token`),
+ * `theme` (`light`, `dark`; the page's by default), `locale` (`es`, `en`), `mode` (`inline`;
+ * floating by default), `header` (the agent's face), `steps` (`shown`, `hidden`), `unstyled`
+ * (our look's defaults dropped, the layout kept) and `contained` (floating in its own box).
+ *
+ * With a publishable key and no `agent`, it is a web channel's widget: it reads its agent and
+ * its look by the key as it loads (`GET /channels/web/widget`), so a change the business makes
+ * reaches every site. A look set on it (`look`) stands over its channel's: SignalCore's preview.
+ */
+export class SignalCoreChat extends HTMLElement {
+  static observedAttributes = [...ATTRIBUTES];
+
+  #mount: HTMLElement | null = null;
+  #root: Root | null = null;
+  /** The page's own stylesheet for the widget, and what it was made from. */
+  #sheet: { from: string; element: HTMLStyleElement | HTMLLinkElement } | null = null;
+  /** The look as a stylesheet, before the page's own. */
+  #lookSheet: HTMLStyleElement | null = null;
+  /** The look set on the element, over its channel's. */
+  #look: WidgetLook | null = null;
+  /** The web channel its publishable key belongs to, as read for that key (null while read). */
+  #channel: { key: string; config: WidgetConfig | null } | null = null;
+  /** The page's type and ink as last given to the widget. */
+  #adopted = "";
+  #unwatch: (() => void) | null = null;
+
+  /** The page's own stylesheet for the widget: CSS, or the address of one (`stylesheet`). */
+  get stylesheet(): string | null {
+    return this.getAttribute("stylesheet");
+  }
+
+  set stylesheet(value: string | null) {
+    if (value === null) this.removeAttribute("stylesheet");
+    else this.setAttribute("stylesheet", value);
+  }
+
+  /** A look over its channel's (or the only one, with an `agent`); null: its channel's. */
+  get look(): WidgetLook | null {
+    return this.#look;
+  }
+
+  set look(value: WidgetLook | null) {
+    this.#look = value;
+    this.#draw();
+  }
+
+  connectedCallback() {
+    this.#mount ??= this.#build();
+    this.#root = createRoot(this.#mount);
+    this.#unwatch = this.#watch();
+    this.#draw();
+  }
+
+  disconnectedCallback() {
+    this.#unwatch?.();
+    this.#unwatch = null;
+    this.#root?.unmount();
+    this.#root = null;
+  }
+
+  attributeChangedCallback() {
+    this.#draw();
+  }
+
+  /**
+   * Where the widget draws (and the kit's panels go): in a shadow root after the package's styles,
+   * or (`shadow="none"`, read once, as the element first connects) in the element itself.
+   */
+  #build(): HTMLElement {
+    const mount = document.createElement("div");
+    mount.setAttribute("data-sc-portal", "");
+    mount.setAttribute("data-sc-widget", "");
+    if (this.getAttribute("shadow") === "none") {
+      stylePage();
+      this.append(mount);
+      return mount;
+    }
+    const shadow = this.attachShadow({ mode: "open" });
+    const style = document.createElement("style");
+    style.textContent = `${styles}\n${own}`;
+    shadow.append(style, mount);
+    return mount;
+  }
+
+  /**
+   * Follows the page: its type and ink again whenever `<html>` or `<body>` change (a class that
+   * makes it dark, say) and when the system's scheme does.
+   */
+  #watch(): () => void {
+    const adopt = () => {
+      this.#adopt();
+    };
+    const observer = new MutationObserver(adopt);
+    for (const node of [document.documentElement, document.body]) {
+      if (node) observer.observe(node, { attributes: true });
+    }
+    const scheme =
+      typeof window.matchMedia === "function"
+        ? window.matchMedia("(prefers-color-scheme: dark)")
+        : null;
+    scheme?.addEventListener("change", adopt);
+    return () => {
+      observer.disconnect();
+      scheme?.removeEventListener("change", adopt);
+    };
+  }
+
+  /** The look it wears: the one set on it, else its channel's, else none. */
+  get #worn(): WidgetLook | null {
+    return this.#look ?? this.#channel?.config?.appearance ?? null;
+  }
+
+  /**
+   * The page's type and ink, as the element inherits them, given to the widget for its defaults
+   * (`--_host-font`, `--_host-font-size`, `--_host-fg`); and its dark palette where the page
+   * names no scheme but its text is light. A theme named (`theme`, or the look's) wears its own
+   * ink, not the page's.
+   */
+  #adopt() {
+    const mount = this.#mount;
+    if (mount === null) return;
+    const page = getComputedStyle(this);
+    const themed = this.hasAttribute("theme") || (this.#worn?.theme ?? "auto") !== "auto";
+    const dark = !themed && darkByInk(page.colorScheme, page.color);
+    const adopted = [page.fontFamily, page.fontSize, page.color, dark, themed].join("|");
+    if (adopted === this.#adopted) return;
+    this.#adopted = adopted;
+    mount.style.setProperty("--_host-font", page.fontFamily);
+    mount.style.setProperty("--_host-font-size", page.fontSize);
+    if (themed) mount.style.removeProperty("--_host-fg");
+    else mount.style.setProperty("--_host-fg", page.color);
+    if (dark) mount.setAttribute("data-scheme", "dark");
+    else mount.removeAttribute("data-scheme");
+  }
+
+  /**
+   * Its look as a stylesheet (and its face loaded), then the page's own stylesheet beside ours
+   * (`stylesheet`), and ours bare (`unstyled`).
+   */
+  #dress() {
+    const mount = this.#mount;
+    if (mount === null) return;
+    mount.toggleAttribute("data-sc-unstyled", on(this, "unstyled"));
+    this.#wear(mount, this.#worn);
+    const from = this.getAttribute("stylesheet")?.trim() || null;
+    if (from === (this.#sheet?.from ?? null)) return;
+    this.#sheet?.element.remove();
+    this.#sheet = null;
+    if (from === null) return;
+    const element = isCss(from) ? cssOf(from) : linkTo(from);
+    // After ours, so it wins where it says the same as loudly.
+    mount.before(element);
+    this.#sheet = { from, element };
+  }
+
+  #wear(mount: HTMLElement, look: WidgetLook | null) {
+    if (look?.font) loadFont(look.font);
+    const css = look === null ? "" : lookCss(look, this.shadowRoot === null ? TAG : ":host");
+    if (css === "") {
+      this.#lookSheet?.remove();
+      this.#lookSheet = null;
+      return;
+    }
+    this.#lookSheet ??= document.createElement("style");
+    if (this.#lookSheet.textContent !== css) this.#lookSheet.textContent = css;
+    // After ours and before the page's own, which wins over it.
+    if (!this.#lookSheet.isConnected) (this.#sheet?.element ?? mount).before(this.#lookSheet);
+  }
+
+  /**
+   * Its web channel's agent and look, read once for its key: null while read, and when it has
+   * an `agent` of its own (it needs no channel then).
+   */
+  #channelOf(settings: WidgetSettings): WidgetConfig | null {
+    const key = settings.credential.publishableKey;
+    if (settings.agent !== null || key === undefined) return null;
+    if (this.#channel?.key === key) return this.#channel.config;
+    this.#channel = { key, config: null };
+    createClient({ baseUrl: settings.baseUrl, publishableKey: key })
+      .widget()
+      .then(
+        (config) => {
+          if (this.#channel?.key !== key) return;
+          this.#channel = { key, config };
+          this.#draw();
+        },
+        (error: unknown) => {
+          console.warn(`<${TAG}> could not read its web channel`, error);
+        },
+      );
+    return null;
+  }
+
+  #draw() {
+    if (this.#root === null) return;
+    const settings = settingsOf(this);
+    const config = settings && this.#channelOf(settings);
+    this.#adopt();
+    this.#dress();
+    if (settings === null) {
+      console.warn(`<${TAG}> needs base-url, and an agent or a publishable key`);
+    }
+    const agent = settings?.agent ?? config?.agent_id ?? null;
+    this.#root.render(
+      settings && agent && <Widget settings={{ ...settings, agent }} look={this.#worn} />,
+    );
+  }
+}
+
+/** Registers `<signalcore-chat>`, once however often it is asked. */
+export function defineSignalCoreChat(): CustomElementConstructor {
+  const known = customElements.get(TAG);
+  if (known) return known;
+  customElements.define(TAG, SignalCoreChat);
+  return SignalCoreChat;
+}

package/src/widget/index.ts

@@ -0,0 +1,10 @@
+/**
+ * The widget's script (`dist/widget.js`): React and the package in one file, which registers
+ * `<signalcore-chat>` as it loads. A page puts the element where it wants it, or, with the one
+ * line a web channel gives, lets the script put it (`mountFromScript`).
+ */
+import { defineSignalCoreChat } from "./element";
+import { mountFromScript } from "./mount";
+
+defineSignalCoreChat();
+mountFromScript(document.currentScript);

package/src/widget/mount.ts

@@ -0,0 +1,27 @@
+import { TAG } from "./element";
+
+/**
+ * The web channel's one line, `<script src="https://signalcore.ai/v1/widget.js" data-key="pk_…"
+ * async>`: the script puts the widget on the page itself, speaking to the API it was loaded from
+ * with that key, which names the agent and the look. `data-locale` and `data-theme` say what
+ * the element's `locale` and `theme` would. Once per key, however often the line is pasted.
+ */
+export function mountFromScript(script: HTMLOrSVGScriptElement | null): HTMLElement | null {
+  if (!(script instanceof HTMLScriptElement)) return null;
+  const key = script.dataset.key;
+  if (!key || !script.src) return null;
+  if (document.querySelector(`${TAG}[publishable-key="${CSS.escape(key)}"]`) !== null) return null;
+  const element = document.createElement(TAG);
+  element.setAttribute("base-url", `${new URL(script.src).origin}/v1`);
+  element.setAttribute("publishable-key", key);
+  for (const name of ["locale", "theme"] as const) {
+    const value = script.dataset[name];
+    if (value) element.setAttribute(name, value);
+  }
+  const place = () => {
+    document.body.append(element);
+  };
+  if (document.body === null) document.addEventListener("DOMContentLoaded", place, { once: true });
+  else place();
+  return element;
+}