@hidemikimura/chit-ui 0.1.0

package/src/styles/panel.css.js

@@ -0,0 +1,126 @@
+// @ts-check
+import { css } from 'lit';
+
+export const panelStyles = css`
+  [part~='panel'] {
+    position: absolute;
+    display: flex;
+    flex-direction: column;
+    width: var(--chit-panel-width);
+    height: var(--chit-panel-height);
+    max-width: calc(100vw - var(--chit-panel-offset-x) * 2);
+    max-height: calc(100vh - var(--chit-panel-offset-y) * 2);
+    overflow: hidden;
+    border-radius: var(--chit-panel-radius);
+    background-color: var(--chit-color-bg);
+    background-image: var(--chit-panel-bg-image);
+    background-size: cover;
+    background-position: center;
+    box-shadow: var(--chit-panel-shadow);
+  }
+
+  /* --- placement -------------------------------------------------------- */
+
+  :host([data-panel-position='bottom-right']) [part~='panel'] {
+    right: var(--chit-panel-offset-x);
+    bottom: var(--chit-panel-offset-y);
+    transform-origin: bottom right;
+  }
+  :host([data-panel-position='bottom-left']) [part~='panel'] {
+    left: var(--chit-panel-offset-x);
+    bottom: var(--chit-panel-offset-y);
+    transform-origin: bottom left;
+  }
+  :host([data-panel-position='top-right']) [part~='panel'] {
+    right: var(--chit-panel-offset-x);
+    top: var(--chit-panel-offset-y);
+    transform-origin: top right;
+  }
+  :host([data-panel-position='top-left']) [part~='panel'] {
+    left: var(--chit-panel-offset-x);
+    top: var(--chit-panel-offset-y);
+    transform-origin: top left;
+  }
+
+  [part~='panel']:focus {
+    outline: none;
+  }
+
+  /*
+   * A phone gets the whole screen. dvh rather than vh so the browser chrome
+   * collapsing does not leave a gap, and the safe-area insets keep the header
+   * clear of the notch.
+   */
+  :host([data-device='mobile']) [part~='panel'],
+  :host([data-device='mobile'][data-panel-position]) [part~='panel'] {
+    inset: 0;
+    width: 100vw;
+    height: 100dvh;
+    max-width: none;
+    max-height: none;
+    border-radius: 0;
+    padding-top: env(safe-area-inset-top);
+    padding-bottom: env(safe-area-inset-bottom);
+    overscroll-behavior: contain;
+  }
+
+  [part~='header'] {
+    display: flex;
+    flex: none;
+    align-items: center;
+    justify-content: space-between;
+    gap: 0.5em;
+    padding: 0.875em 1em;
+    border-bottom: 1px solid var(--chit-color-border);
+    background: var(--chit-color-header-bg);
+    color: var(--chit-color-header-text);
+  }
+
+  [part~='header-heading'] {
+    font-size: 1.05em;
+    font-weight: 600;
+  }
+
+  [part~='header-logo'] {
+    width: 1.75em;
+    height: 1.75em;
+    margin-inline-end: 0.5em;
+    border-radius: 50%;
+    object-fit: cover;
+    vertical-align: middle;
+  }
+
+  [part~='header-actions'] {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.25em;
+  }
+
+  [part~='close-button'] {
+    display: grid;
+    place-items: center;
+    width: 2em;
+    height: 2em;
+    padding: 0;
+    border: 0;
+    border-radius: 50%;
+    background: transparent;
+    color: inherit;
+    cursor: pointer;
+  }
+
+  [part~='close-button']:hover {
+    background: color-mix(in srgb, currentColor 10%, transparent);
+  }
+
+  [part~='close-button']:focus-visible {
+    outline: 2px solid var(--chit-color-accent);
+    outline-offset: 1px;
+  }
+
+  [part~='close-button'] svg {
+    width: 1.1em;
+    height: 1.1em;
+  }
+
+`;

package/src/theme/default-theme.js

@@ -0,0 +1,111 @@
+// @ts-check
+
+/** @import { ResolvedClosed } from '../types.js' */
+
+/**
+ * Neutral light palette. Every text/background pair here clears WCAG AA
+ * (4.5:1); `test/theme.test.js` re-checks the ratios so a future tweak cannot
+ * quietly drop below it.
+ */
+const PALETTE = {
+  accent: '#2563eb',
+  ink: '#1f2328',
+  muted: '#5c6370',
+  surface: '#ffffff',
+  raised: '#f1f3f5',
+  line: '#e4e4e7',
+  onAccent: '#ffffff',
+};
+
+/** @type {ResolvedClosed} */
+const CLOSED_PC = {
+  size: 60,
+  position: 'bottom-right',
+  offset: { x: 24, y: 24 },
+  radius: 30,
+  image: null,
+  label: null,
+  component: null,
+  props: {},
+  colors: {
+    background: PALETTE.accent,
+    text: PALETTE.onAccent,
+    shadow: '0 4px 12px rgba(0, 0, 0, 0.2)',
+  },
+  animation: { enter: 'scale', exit: 'scale', duration: 200, idle: 'none' },
+};
+
+/**
+ * What a phone gets when the theme does not say. Only the measurements differ:
+ * a thumb needs a slightly smaller target closer to the screen edge.
+ *
+ * @type {Partial<ResolvedClosed>}
+ */
+const CLOSED_MOBILE_DIFF = {
+  size: 56,
+  offset: { x: 16, y: 16 },
+  radius: 28,
+};
+
+/**
+ * The library's own theme. A user theme is merged over this, so everything
+ * here is what you get when the user says nothing at all.
+ *
+ * `closed` carries both device buckets; `mergeTheme` narrows it to one.
+ */
+export const defaultTheme = {
+  breakpoint: 768,
+  zIndex: 2147483000,
+  font: {
+    family:
+      "system-ui, -apple-system, 'Segoe UI', 'Hiragino Sans', 'Noto Sans JP', sans-serif",
+    size: 14,
+  },
+  closed: {
+    pc: CLOSED_PC,
+    mobile: /** @type {ResolvedClosed} */ ({ ...CLOSED_PC, ...CLOSED_MOBILE_DIFF }),
+  },
+  open: {
+    width: 380,
+    height: 600,
+    position: /** @type {const} */ ('bottom-right'),
+    offset: { x: 24, y: 24 },
+    radius: 16,
+    launcher: /** @type {const} */ ('hidden'),
+    header: { title: null, logo: null, avatar: null },
+    background: { image: null },
+    colors: {
+      background: PALETTE.surface,
+      text: PALETTE.ink,
+      accent: PALETTE.accent,
+      border: PALETTE.line,
+      shadow: '0 8px 32px rgba(0, 0, 0, 0.24)',
+      headerBackground: PALETTE.surface,
+      headerText: PALETTE.ink,
+      userBubble: PALETTE.accent,
+      userText: PALETTE.onAccent,
+      assistantBubble: PALETTE.raised,
+      assistantText: PALETTE.ink,
+      systemText: PALETTE.muted,
+      inputBackground: PALETTE.surface,
+      inputText: PALETTE.ink,
+      inputPlaceholder: PALETTE.muted,
+    },
+    animation: {
+      enter: /** @type {const} */ ('scale'),
+      exit: /** @type {const} */ ('fade'),
+      duration: 150,
+      // How the conversation follows a new message. Growth within a message
+      // (a streamed reply, an image loading) is always instant; see
+      // ScrollController for why.
+      scroll: /** @type {const} */ ('smooth'),
+    },
+    input: { maxRows: 5, placeholder: null },
+  },
+  hidden: {
+    animation: { exit: /** @type {const} */ ('fade'), duration: 150 },
+  },
+};
+
+/** The measurements a phone falls back to when only `closed.pc` was given. */
+export const mobileClosedDefaults = CLOSED_MOBILE_DIFF;

package/src/theme/merge-theme.js

@@ -0,0 +1,100 @@
+// @ts-check
+import { defaultTheme, mobileClosedDefaults } from './default-theme.js';
+
+/** @import { Theme, ClosedTheme, Device, ResolvedTheme } from '../types.js' */
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Merge `override` onto `base`, recursing into plain objects.
+ *
+ * `undefined` means "say nothing" and leaves the base value alone; `null` means
+ * "clear it", so `{ image: null }` removes a default icon rather than being
+ * ignored. There are no arrays anywhere in a theme, so a plain recursive merge
+ * is enough.
+ *
+ * @template {Record<string, any>} T
+ * @param {T} base
+ * @param {Record<string, any> | undefined} override
+ * @returns {T}
+ */
+export function mergeTheme(base, override) {
+  if (!isPlainObject(override)) return base;
+
+  /** @type {Record<string, any>} */
+  const out = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    if (value === undefined) continue;
+    const current = out[key];
+    out[key] = isPlainObject(value) && isPlainObject(current) ? mergeTheme(current, value) : value;
+  }
+  return /** @type {T} */ (out);
+}
+
+/**
+ * Decide which `closed` settings this device gets.
+ *
+ * Three shapes are allowed, and this is where they collapse into one:
+ * no pc/mobile keys at all (the same settings serve both), both given, or only
+ * one given. When only `pc` is given the phone inherits it but keeps the
+ * default phone measurements, so a custom icon carries over without a
+ * desktop-sized button landing on a phone.
+ *
+ * @param {ClosedTheme | { pc?: ClosedTheme, mobile?: ClosedTheme } | undefined} closed
+ * @param {Device} device
+ * @returns {ClosedTheme}
+ */
+function resolveClosed(closed, device) {
+  const perDevice = /** @type {{ pc?: ClosedTheme, mobile?: ClosedTheme }} */ (closed ?? {});
+  const split = 'pc' in perDevice || 'mobile' in perDevice;
+
+  if (!split) {
+    const shared = /** @type {ClosedTheme} */ (closed ?? {});
+    return mergeTheme(defaultTheme.closed[device], shared);
+  }
+
+  const pc = mergeTheme(defaultTheme.closed.pc, perDevice.pc);
+  if (device === 'pc') return pc;
+
+  if (perDevice.mobile) return mergeTheme(defaultTheme.closed.mobile, perDevice.mobile);
+  return mergeTheme(pc, mobileClosedDefaults);
+}
+
+/**
+ * Fill every gap in a user theme and narrow it to one device.
+ *
+ * @param {Theme | undefined} theme
+ * @param {Device} device
+ * @returns {ResolvedTheme}
+ */
+export function resolveTheme(theme, device) {
+  const user = theme ?? {};
+  const closed = resolveClosed(user.closed, device);
+
+  return /** @type {ResolvedTheme} */ ({
+    breakpoint: user.breakpoint ?? defaultTheme.breakpoint,
+    zIndex: user.zIndex ?? defaultTheme.zIndex,
+    font: mergeTheme(defaultTheme.font, user.font),
+    closed: mergeTheme(defaultTheme.closed[device], closed),
+    open: mergeTheme(defaultTheme.open, user.open),
+    hidden: mergeTheme(defaultTheme.hidden, user.hidden),
+    device,
+  });
+}
+
+/**
+ * The breakpoint a theme asks for, readable before the full resolve (the
+ * device is not known until the breakpoint is).
+ *
+ * @param {Theme | undefined} theme
+ * @returns {number}
+ */
+export function breakpointOf(theme) {
+  return theme?.breakpoint ?? defaultTheme.breakpoint;
+}

package/src/theme/theme-to-css.js

@@ -0,0 +1,94 @@
+// @ts-check
+
+/** @import { ResolvedTheme } from '../types.js' */
+
+/**
+ * @param {number} value
+ * @returns {string}
+ */
+const px = (value) => `${value}px`;
+
+/**
+ * A CSS `url()` for an image, or `none`. Quotes and backslashes are escaped so
+ * a filename with an apostrophe cannot break out of the declaration.
+ *
+ * @param {string | null | undefined} value
+ * @returns {string}
+ */
+function url(value) {
+  if (!value) return 'none';
+  return `url("${value.replace(/[\\"]/g, '\\$&')}")`;
+}
+
+/**
+ * Turn a resolved theme into the custom properties the stylesheets read.
+ *
+ * Only values CSS can act on are here. Positions, animation effects, text and
+ * images that belong in markup are applied as attributes or drawn by the
+ * render functions instead.
+ *
+ * Animation durations are deliberately absent: the transition code has to know
+ * when an animation ends, so the theme is the single source of truth for them
+ * and it writes the duration onto the element as it starts. A custom property
+ * here would look like a knob that does nothing.
+ *
+ * @param {ResolvedTheme} theme
+ * @returns {Record<string, string>}
+ */
+export function themeToVariables(theme) {
+  const { closed, open } = theme;
+  const c = open.colors;
+
+  return {
+    '--chit-z-index': String(theme.zIndex),
+    '--chit-font-family': theme.font.family,
+    '--chit-font-size': px(theme.font.size),
+
+    '--chit-launcher-size': closed.size === 'auto' ? 'auto' : px(closed.size),
+    '--chit-launcher-offset-x': px(closed.offset.x),
+    '--chit-launcher-offset-y': px(closed.offset.y),
+    '--chit-launcher-radius': px(closed.radius),
+    '--chit-launcher-image': url(closed.image),
+    '--chit-launcher-bg': closed.colors.background,
+    '--chit-launcher-text': closed.colors.text,
+    '--chit-launcher-shadow': closed.colors.shadow,
+
+    '--chit-panel-width': px(open.width),
+    '--chit-panel-height': px(open.height),
+    '--chit-panel-offset-x': px(open.offset.x),
+    '--chit-panel-offset-y': px(open.offset.y),
+    '--chit-panel-radius': px(open.radius),
+    '--chit-panel-bg-image': url(open.background.image),
+    '--chit-panel-shadow': c.shadow,
+
+    '--chit-color-bg': c.background,
+    '--chit-color-text': c.text,
+    '--chit-color-accent': c.accent,
+    '--chit-color-border': c.border,
+    '--chit-color-header-bg': c.headerBackground,
+    '--chit-color-header-text': c.headerText,
+    '--chit-color-user-bg': c.userBubble,
+    '--chit-color-user-text': c.userText,
+    '--chit-color-assistant-bg': c.assistantBubble,
+    '--chit-color-assistant-text': c.assistantText,
+    '--chit-color-system-text': c.systemText,
+    '--chit-color-input-bg': c.inputBackground,
+    '--chit-color-input-text': c.inputText,
+    '--chit-color-input-placeholder': c.inputPlaceholder,
+
+    '--_chit-input-max-rows': String(open.input.maxRows),
+  };
+}
+
+/**
+ * The stylesheet text for a resolved theme.
+ *
+ * @param {ResolvedTheme} theme
+ * @returns {string}
+ */
+export function themeToCss(theme) {
+  const declarations = Object.entries(themeToVariables(theme))
+    .map(([name, value]) => `  ${name}: ${value};`)
+    .join('\n');
+  return `:host {\n${declarations}\n}\n`;
+}

package/src/types.js

@@ -0,0 +1,143 @@
+// @ts-check
+
+/**
+ * Public types for Chit UI. This module has no runtime value; it exists so that
+ * every other file can `@import` from one place and so `tsc` can emit .d.ts.
+ *
+ * @typedef {'user' | 'assistant' | 'system'} Role
+ * @typedef {'sending' | 'sent' | 'error'} MessageStatus
+ * @typedef {'closed' | 'open' | 'hidden'} ChatState
+ * @typedef {'user' | 'api'} Trigger
+ * @typedef {'pc' | 'mobile'} Device
+ * @typedef {'fade' | 'scale' | 'slide' | 'none'} Effect
+ * @typedef {'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'} Position
+ */
+
+/**
+ * @typedef {Object} MessageBase
+ * @property {string} id                       Unique within the array; used as the diffing key.
+ * @property {Role} role
+ * @property {string | Date} [time]
+ * @property {string} [name]
+ * @property {string} [avatar]
+ * @property {MessageStatus} [status]
+ * @property {boolean} [streaming]
+ * @property {unknown} [meta]                  Never touched by the library.
+ *
+ * @typedef {MessageBase & { text: string }} TextMessage
+ * @typedef {MessageBase & { html: string }} HtmlMessage
+ * @typedef {MessageBase & { template: import('lit').TemplateResult }} TemplateMessage
+ * @typedef {MessageBase & { element: HTMLElement }} ElementMessage
+ * @typedef {MessageBase & { component: (new () => HTMLElement) | string, props?: Record<string, unknown> }} ComponentMessage
+ * @typedef {TextMessage | HtmlMessage | TemplateMessage | ElementMessage | ComponentMessage} Message
+ */
+
+/**
+ * @typedef {Object} Animation
+ * @property {Effect} [enter]
+ * @property {Effect} [exit]
+ * @property {number} [duration]               ms
+ *
+ * @typedef {Object} Offset
+ * @property {number} [x]
+ * @property {number} [y]
+ */
+
+/**
+ * @typedef {Object} ClosedTheme
+ * @property {number | 'auto'} [size]          Launcher edge length in px, or 'auto' to let its content decide.
+ * @property {Position} [position]
+ * @property {Offset} [offset]
+ * @property {number} [radius]
+ * @property {string | null} [image]           Icon image URL; null clears the default.
+ * @property {string | null} [label]
+ * @property {(new () => HTMLElement) | string | null} [component]  A component that draws the whole launcher.
+ * @property {Record<string, unknown>} [props] Properties written to that component.
+ * @property {{ background?: string, text?: string, shadow?: string }} [colors]
+ * @property {Animation & { idle?: 'none' | 'pulse' | 'bounce' }} [animation]
+ */
+
+/**
+ * @typedef {Object} OpenColors
+ * @property {string} [background]
+ * @property {string} [text]
+ * @property {string} [accent]
+ * @property {string} [border]
+ * @property {string} [shadow]
+ * @property {string} [headerBackground]
+ * @property {string} [headerText]
+ * @property {string} [userBubble]
+ * @property {string} [userText]
+ * @property {string} [assistantBubble]
+ * @property {string} [assistantText]
+ * @property {string} [systemText]
+ * @property {string} [inputBackground]
+ * @property {string} [inputText]
+ * @property {string} [inputPlaceholder]
+ */
+
+/**
+ * @typedef {Object} OpenTheme
+ * @property {number} [width]                  Ignored on mobile (always full screen).
+ * @property {number} [height]                 Ignored on mobile (always full screen).
+ * @property {Position} [position]
+ * @property {Offset} [offset]
+ * @property {number} [radius]
+ * @property {'hidden' | 'visible'} [launcher] Keep the launcher visible while open.
+ * @property {{ title?: string | null, logo?: string | null, avatar?: string | null }} [header]
+ * @property {{ image?: string | null }} [background]
+ * @property {OpenColors} [colors]
+ * @property {Animation & { scroll?: 'smooth' | 'instant' }} [animation]
+ * @property {{ maxRows?: number, placeholder?: string | null }} [input]
+ */
+
+/**
+ * @typedef {Object} Theme
+ * @property {number} [breakpoint]             Widths below this are treated as mobile.
+ * @property {number} [zIndex]
+ * @property {{ family?: string, size?: number }} [font]
+ * @property {ClosedTheme | { pc?: ClosedTheme, mobile?: ClosedTheme }} [closed]
+ * @property {OpenTheme} [open]
+ * @property {{ animation?: { exit?: Effect, duration?: number } }} [hidden]
+ */
+
+/**
+ * A theme with every gap filled in and `closed` narrowed to the device in use.
+ * This is what the render functions and the CSS generator read.
+ *
+ * @typedef {Object} ResolvedClosed
+ * @property {number | 'auto'} size
+ * @property {Position} position
+ * @property {{ x: number, y: number }} offset
+ * @property {number} radius
+ * @property {string | null} image
+ * @property {string | null} label
+ * @property {(new () => HTMLElement) | string | null} component
+ * @property {Record<string, unknown>} props
+ * @property {{ background: string, text: string, shadow: string }} colors
+ * @property {{ enter: Effect, exit: Effect, duration: number, idle: 'none' | 'pulse' | 'bounce' }} animation
+ *
+ * @typedef {Object} ResolvedOpen
+ * @property {number} width
+ * @property {number} height
+ * @property {Position} position
+ * @property {{ x: number, y: number }} offset
+ * @property {number} radius
+ * @property {'hidden' | 'visible'} launcher
+ * @property {{ title: string | null, logo: string | null, avatar: string | null }} header
+ * @property {{ image: string | null }} background
+ * @property {Required<OpenColors>} colors
+ * @property {{ enter: Effect, exit: Effect, duration: number, scroll: 'smooth' | 'instant' }} animation
+ * @property {{ maxRows: number, placeholder: string | null }} input
+ *
+ * @typedef {Object} ResolvedTheme
+ * @property {number} breakpoint
+ * @property {number} zIndex
+ * @property {{ family: string, size: number }} font
+ * @property {ResolvedClosed} closed
+ * @property {ResolvedOpen} open
+ * @property {{ animation: { exit: Effect, duration: number } }} hidden
+ * @property {Device} device       Which bucket `closed` was narrowed to.
+ */
+
+export {};