@kitn.ai/ui 0.17.0 → 0.18.0

package/src/components/composer-dom.ts

@@ -0,0 +1,159 @@
+import type { EntityRef, ComposerDoc } from '../primitives/composer-model';
+import { normalizeValue } from '../primitives/composer-model';
+
+export const ZWSP = '​';
+export const ENTITY_ATTR = 'data-kai-entity';
+export const entityStore = new WeakMap<HTMLElement, EntityRef>();
+
+export function isEntityEl(node: Node | null): node is HTMLElement {
+  return !!node && node.nodeType === 1 && (node as HTMLElement).hasAttribute(ENTITY_ATTR);
+}
+
+/**
+ * A TreeWalker over the editable's text nodes that SKIPS text inside entity
+ * pills. Pills are atomic and contribute nothing to the text model — their inner
+ * label text must not pollute caret offsets, trigger detection, or highlight
+ * ranges. (Without this, the text seen at a caret right after a pill is the
+ * pill's label, so `/` reads as glued to the label instead of starting a token.)
+ */
+export function createTextWalker(root: HTMLElement): TreeWalker {
+  return root.ownerDocument.createTreeWalker(root, NodeFilter.SHOW_TEXT, {
+    acceptNode(node) {
+      let p = node.parentElement;
+      while (p && p !== root) {
+        if (p.hasAttribute(ENTITY_ATTR)) return NodeFilter.FILTER_REJECT;
+        p = p.parentElement;
+      }
+      return NodeFilter.FILTER_ACCEPT;
+    },
+  });
+}
+
+/**
+ * The leading sigil shown on a "light" pill, by kind: skills `/`, agents `@`.
+ * Skills and agents render as decorated inline text led by their sigil; this is
+ * what makes them read like `/my-skill` / `@my-agent` rather than a chip.
+ * Returns '' for kinds rendered as a richer CHIP (plugins, and any other/unknown
+ * kind) — those carry an icon instead of a sigil. The sigil is visual only: it
+ * never enters the text model (the entity is read from `entityStore`, and the
+ * text walker skips pill-internal nodes).
+ */
+export function kindSigil(kind: string): string {
+  switch (kind) {
+    case 'skill':
+      return '/';
+    case 'agent':
+      return '@';
+    default:
+      return '';
+  }
+}
+
+/**
+ * Default monochrome (currentColor) glyph per entity kind, for the richer CHIP
+ * kinds shown in the trigger menu / on plugin pills: plugin = plug. (Skills and
+ * agents are light sigil-text pills — see `kindSigil` — so they take no glyph on
+ * the pill, though the menu may still show one.) Returns inline SVG markup
+ * (trusted — no user input), or '' for kinds without a default. An item's own
+ * `icon` always takes precedence over this.
+ */
+export function kindGlyph(kind: string): string {
+  const svg = (inner: string) =>
+    `<svg viewBox="0 0 24 24" width="1em" height="1em" aria-hidden="true" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">${inner}</svg>`;
+  switch (kind) {
+    case 'agent':
+      return svg('<rect x="4" y="8" width="16" height="12" rx="3"/><path d="M12 4.5V8M9.5 13.5v1.5M14.5 13.5v1.5"/><circle cx="12" cy="3" r="1.2"/>');
+    case 'plugin':
+      return svg('<path d="M9 2v4M15 2v4M6 6h12v5a6 6 0 0 1-12 0zM12 17v5"/>');
+    default:
+      return ''; // skills + unknown kinds: no default glyph
+  }
+}
+
+export function createEntityEl(
+  doc: Document,
+  entity: EntityRef,
+  kindIcons?: Record<string, string>,
+): HTMLElement {
+  const el = doc.createElement('span');
+  el.setAttribute(ENTITY_ATTR, '');
+  el.setAttribute('contenteditable', 'false');
+  el.dataset.kind = entity.kind;
+  el.dataset.id = entity.id;
+  el.className = 'kai-composer-pill';
+
+  const sigil = kindSigil(entity.kind);
+  if (sigil) {
+    // Skills/agents: LIGHT pill — decorated inline text led by the sigil, no
+    // icon. (`/my-skill`, `@my-agent`.)
+    const s = doc.createElement('span');
+    s.className = 'kai-composer-pill-sigil';
+    s.setAttribute('aria-hidden', 'true');
+    s.textContent = sigil;
+    el.appendChild(s);
+  } else {
+    // Plugins (and other composite/unknown kinds): the richer CHIP, with an
+    // icon so a bundle reads differently from a skill/agent at a glance. Icon
+    // resolution: the item's own icon → per-kind default (kindIcons) → a
+    // built-in kind glyph (plugin) → nothing.
+    const iconSrc = entity.icon ?? kindIcons?.[entity.kind];
+    if (iconSrc) {
+      const img = doc.createElement('img');
+      img.src = iconSrc;
+      img.alt = '';
+      img.className = 'kai-composer-pill-icon';
+      el.appendChild(img);
+    } else {
+      const glyph = kindGlyph(entity.kind);
+      if (glyph) {
+        const span = doc.createElement('span');
+        span.className = 'kai-composer-pill-icon kai-composer-pill-glyph';
+        span.setAttribute('aria-hidden', 'true');
+        span.innerHTML = glyph; // trusted SVG markup (not user input)
+        el.appendChild(span);
+      }
+    }
+  }
+  el.appendChild(doc.createTextNode(entity.label));
+  entityStore.set(el, entity);
+  return el;
+}
+
+export function parseDom(root: HTMLElement): ComposerDoc {
+  const segs: ComposerDoc = [];
+  const nodes = root.childNodes;
+  nodes.forEach((node, i) => {
+    if (isEntityEl(node)) {
+      const stored = entityStore.get(node as HTMLElement);
+      const el = node as HTMLElement;
+      segs.push({ type: 'entity', entity: stored ?? { kind: el.dataset.kind ?? '', id: el.dataset.id ?? '', label: el.textContent ?? '' } });
+    } else if (node.nodeType === 1 && (node as HTMLElement).tagName === 'BR') {
+      // Drop the browser's trailing filler <br> — contenteditable inserts one when
+      // the field is cleared (or after a newline) to keep the line visible. Treating
+      // it as content would leave the field "non-empty" (placeholder stuck hidden)
+      // and serialize a phantom trailing "\n". A <br> BETWEEN content is a real
+      // newline and is preserved.
+      if (i === nodes.length - 1) return;
+      segs.push({ type: 'text', text: '\n' });
+    } else if (node.nodeType === 3) {
+      segs.push({ type: 'text', text: (node.textContent ?? '').split(ZWSP).join('') });
+    }
+  });
+  return normalizeValue(segs);
+}
+
+export function renderDoc(
+  root: HTMLElement,
+  doc: ComposerDoc,
+  ownerDoc: Document = document,
+  kindIcons?: Record<string, string>,
+): void {
+  root.textContent = '';
+  for (const seg of doc) {
+    if (seg.type === 'text') root.appendChild(ownerDoc.createTextNode(seg.text));
+    else {
+      root.appendChild(createEntityEl(ownerDoc, seg.entity, kindIcons));
+      root.appendChild(ownerDoc.createTextNode(ZWSP));
+    }
+  }
+}

package/src/components/composer-highlight.ts

@@ -0,0 +1,242 @@
+import type { HighlightRule } from './composer';
+import { createTextWalker } from './composer-dom';
+
+export interface HighlightMatch {
+  start: number;
+  end: number;
+  class: string | undefined;
+}
+
+/** Escape special regex metacharacters in a literal string. */
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Find all non-overlapping highlight ranges in `text` for the given rules.
+ *
+ * - A string rule is matched as a case-insensitive literal (regex metachars are escaped).
+ * - An object rule uses `new RegExp(pattern, flags ?? 'gi')`.
+ * - Overlapping ranges are resolved in earliest-start order; later ranges that
+ *   overlap an already-claimed span are dropped.
+ * - Zero-width matches are skipped to avoid infinite loops.
+ * - Returns `[]` when nothing matches.
+ */
+export function findHighlightMatches(text: string, rules: HighlightRule[]): HighlightMatch[] {
+  const candidates: HighlightMatch[] = [];
+
+  for (const rule of rules) {
+    let regex: RegExp;
+    let cls: string | undefined;
+
+    if (typeof rule === 'string') {
+      regex = new RegExp(escapeRegex(rule), 'gi');
+      cls = undefined;
+    } else {
+      regex = new RegExp(rule.pattern, rule.flags ?? 'gi');
+      cls = rule.class;
+    }
+
+    // Reset lastIndex so we scan from the beginning regardless of flag state.
+    regex.lastIndex = 0;
+
+    let match: RegExpExecArray | null;
+    while ((match = regex.exec(text)) !== null) {
+      const start = match.index;
+      const end = start + match[0].length;
+
+      // Guard against zero-width matches to avoid infinite loops.
+      if (end === start) {
+        regex.lastIndex = start + 1;
+        continue;
+      }
+
+      candidates.push({ start, end, class: cls });
+    }
+  }
+
+  // Sort by start position (tie-break: earlier rule wins, which preserves insertion order).
+  candidates.sort((a, b) => a.start - b.start);
+
+  // Remove overlapping ranges (greedy earliest-start wins).
+  const result: HighlightMatch[] = [];
+  let frontier = -1; // end of the last accepted range
+  for (const c of candidates) {
+    if (c.start >= frontier) {
+      result.push(c);
+      frontier = c.end;
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// CSS Custom Highlight API — ambient type declarations
+// (jsdom does not ship these; they are defined here rather than in a lib to
+// keep the footprint minimal and avoid tsconfig changes.)
+// ---------------------------------------------------------------------------
+
+declare global {
+  // CSS.highlights is defined on the CSS namespace object.
+  interface CSSNamespace {
+    highlights?: HighlightRegistry;
+  }
+  interface HighlightRegistry {
+    set(name: string, highlight: CSSHighlight): void;
+    delete(name: string): boolean;
+    has(name: string): boolean;
+  }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  class CSSHighlight {
+    constructor(...ranges: Range[]);
+  }
+}
+
+/**
+ * Feature-detect whether the CSS Custom Highlight API is available in the
+ * current environment.  Returns false in jsdom (decoration no-op).
+ */
+export function supportsHighlightAPI(): boolean {
+  try {
+    return (
+      typeof CSS !== 'undefined' &&
+      typeof CSS.highlights !== 'undefined' &&
+      typeof Highlight !== 'undefined'
+    );
+  } catch {
+    return false;
+  }
+}
+
+const HIGHLIGHT_NAME = 'kai-composer-highlight';
+
+/**
+ * Apply highlight matches to a contenteditable element using the CSS Custom
+ * Highlight API.  Maps text offsets (ZWSP-stripped concatenated text) to DOM
+ * Ranges spanning across text nodes, builds a `Highlight`, and registers it.
+ *
+ * If the API is unavailable (jsdom, older browsers), this is a strict no-op.
+ *
+ * @param root     The contenteditable element.
+ * @param matches  Pre-computed non-overlapping `{start, end}` ranges.
+ * @param zwsp     The ZWSP character used in the editable (passed to avoid
+ *                 a circular import; callers pass ZWSP from composer-dom).
+ */
+export function applyHighlights(
+  root: HTMLElement,
+  matches: HighlightMatch[],
+  zwsp: string,
+  name = HIGHLIGHT_NAME,
+): void {
+  if (!supportsHighlightAPI()) return;
+
+  const registry = CSS.highlights as HighlightRegistry;
+
+  if (matches.length === 0) {
+    registry.delete(name);
+    return;
+  }
+
+  // Build a flat list of {node, rawStart, rawEnd} segments mirroring
+  // how getFullText works, but retaining the raw (pre-stripped) offsets so
+  // we can set Range.setStart/setEnd correctly.
+  //
+  // Each entry records:
+  //   textNode   - the DOM Text node
+  //   stripped   - the node's textContent with ZWSP removed
+  //   rawOffset  - raw index in textContent where the stripped content starts
+  //                at the node level (always 0 — we need per-char mapping when
+  //                ZWSP chars are interspersed, so we build a per-node map)
+  //   strippedStart - cumulative stripped-text offset at the start of this node
+  //
+  interface NodeEntry {
+    node: Text;
+    strippedStart: number; // cumulative stripped offset before this node
+    // Maps stripped-relative index i → raw textContent index
+    strippedToRaw: Int32Array;
+  }
+
+  const entries: NodeEntry[] = [];
+  let cursor = 0; // cumulative stripped offset
+
+  const ownerDoc = root.ownerDocument;
+  const walker = createTextWalker(root); // skip text inside entity pills
+  let node = walker.nextNode() as Text | null;
+  while (node) {
+    const raw = node.textContent ?? '';
+    // Build stripped→raw index map for this node.
+    const strippedIndices: number[] = [];
+    for (let ri = 0; ri < raw.length; ri++) {
+      if (raw[ri] !== zwsp) {
+        strippedIndices.push(ri);
+      }
+    }
+    if (strippedIndices.length > 0) {
+      const map = new Int32Array(strippedIndices.length);
+      for (let i = 0; i < strippedIndices.length; i++) map[i] = strippedIndices[i];
+      entries.push({ node, strippedStart: cursor, strippedToRaw: map });
+      cursor += strippedIndices.length;
+    }
+    node = walker.nextNode() as Text | null;
+  }
+
+  /**
+   * Convert a stripped-text offset to a {node, rawOffset} pair for Range API.
+   * Returns null if out of range.
+   */
+  function resolve(
+    strippedOffset: number,
+  ): { node: Text; rawOffset: number } | null {
+    // Binary-search for the entry that contains strippedOffset.
+    let lo = 0;
+    let hi = entries.length - 1;
+    while (lo <= hi) {
+      const mid = (lo + hi) >> 1;
+      const e = entries[mid];
+      const eEnd = e.strippedStart + e.strippedToRaw.length;
+      if (strippedOffset < e.strippedStart) {
+        hi = mid - 1;
+      } else if (strippedOffset >= eEnd) {
+        lo = mid + 1;
+      } else {
+        const localIdx = strippedOffset - e.strippedStart;
+        return { node: e.node, rawOffset: e.strippedToRaw[localIdx] };
+      }
+    }
+    // strippedOffset is exactly at the end of the last entry — point after
+    // the last raw character of the last node.
+    if (entries.length > 0) {
+      const last = entries[entries.length - 1];
+      const localIdx = strippedOffset - last.strippedStart;
+      if (localIdx === last.strippedToRaw.length) {
+        // End position: raw offset is one past the last stripped char's raw index.
+        return {
+          node: last.node,
+          rawOffset: last.strippedToRaw[last.strippedToRaw.length - 1] + 1,
+        };
+      }
+    }
+    return null;
+  }
+
+  const ranges: Range[] = [];
+  for (const m of matches) {
+    const startPos = resolve(m.start);
+    const endPos = resolve(m.end);
+    if (!startPos || !endPos) continue;
+
+    const r = ownerDoc.createRange();
+    r.setStart(startPos.node, startPos.rawOffset);
+    r.setEnd(endPos.node, endPos.rawOffset);
+    ranges.push(r);
+  }
+
+  if (ranges.length === 0) {
+    registry.delete(name);
+    return;
+  }
+
+  const hl = new Highlight(...ranges);
+  registry.set(name, hl);
+}

package/src/components/composer-history.ts

@@ -0,0 +1,82 @@
+import type { ComposerDoc } from '../primitives/composer-model';
+
+/**
+ * Undo/redo history for the composer.
+ *
+ * The browser's native contenteditable undo stack can't track our programmatic
+ * pill insertion/deletion — it leaves pills stuck and replays text edits against
+ * a DOM we changed underneath it, corrupting the content. So we own the history:
+ * a stack of document-model snapshots. Restoring a snapshot re-renders the doc
+ * (pills included, since each snapshot holds full EntityRefs) and the caret.
+ *
+ * Pure module — no DOM. The caller computes `coalesce` (true to merge a run of
+ * consecutive typing into one undo step; false for a structural edit like a pill
+ * insert/delete, which gets its own step).
+ */
+
+export interface Snapshot {
+  doc: ComposerDoc;
+  caret: number;
+}
+
+export interface ComposerHistory {
+  /** Record a new state. `coalesce` merges it into the current entry instead of
+   *  pushing a new one (used for consecutive typing). */
+  record(snap: Snapshot, coalesce: boolean): void;
+  /** Step back; returns the snapshot to restore, or null if nothing to undo. */
+  undo(): Snapshot | null;
+  /** Step forward; returns the snapshot to restore, or null if nothing to redo. */
+  redo(): Snapshot | null;
+  /** Replace all history with a single baseline entry (e.g. external value set). */
+  reset(snap: Snapshot): void;
+  canUndo(): boolean;
+  canRedo(): boolean;
+  /** Current entry count (for tests/debugging). */
+  size(): number;
+}
+
+export function createHistory(initial: Snapshot, limit = 200): ComposerHistory {
+  let entries: Snapshot[] = [initial];
+  let index = 0;
+
+  return {
+    record(snap, coalesce) {
+      if (coalesce && index === entries.length - 1) {
+        // Merge into the current entry (a continuing run of typing).
+        entries[index] = snap;
+        return;
+      }
+      // Drop any redo branch, then push a fresh entry.
+      entries = entries.slice(0, index + 1);
+      entries.push(snap);
+      if (entries.length > limit) {
+        entries.shift();
+      } else {
+        index++;
+      }
+    },
+    undo() {
+      if (index === 0) return null;
+      index--;
+      return entries[index];
+    },
+    redo() {
+      if (index >= entries.length - 1) return null;
+      index++;
+      return entries[index];
+    },
+    reset(snap) {
+      entries = [snap];
+      index = 0;
+    },
+    canUndo() {
+      return index > 0;
+    },
+    canRedo() {
+      return index < entries.length - 1;
+    },
+    size() {
+      return entries.length;
+    },
+  };
+}