@xemahq/ui-kernel 0.1.5 → 0.1.7

package/src/session-kit/display/ToolStrip.tsx

@@ -0,0 +1,278 @@
+/**
+ * Tool-call strip — a collapsed summary chip that expands into a row of
+ * per-tool chips. Tool icons and the summary stat icons are
+ * host-supplied; the dot/stat colours come from the authoritative
+ * status-dot map so every surface agrees on "amber pending / green done
+ * / red error".
+ */
+import { useState, type ReactElement, type ReactNode } from 'react';
+
+import { SessionSkin, ToolStatus } from '../lib/enums';
+import { toolStatusColor } from '../lib/status-dot';
+
+export interface ToolCall {
+  /** Tool label (e.g. "Read", "Shell"). */
+  readonly label: string;
+  /** Optional host-supplied tool icon. */
+  readonly icon?: ReactNode;
+  /** Primary argument shown in mono after the label. */
+  readonly arg?: string;
+  readonly status: ToolStatus;
+  /** Expandable raw detail; chip is only clickable when present. */
+  readonly detail?: string;
+  /** Repeat count badge (e.g. ×3) when the same call ran multiple times. */
+  readonly count?: number;
+}
+
+/** Host-supplied icons used by the collapsed-summary and per-chip UI. */
+export interface ToolStripIcons {
+  /** Leading glyph on the collapsed summary (e.g. a zap). */
+  readonly summary?: ReactNode;
+  /** Chevron on the collapsed summary. */
+  readonly chevron?: ReactNode;
+  /** Done stat icon. */
+  readonly done?: ReactNode;
+  /** Pending stat icon (rendered spinning via `xk-spin`). */
+  readonly pending?: ReactNode;
+  /** Error stat icon. */
+  readonly error?: ReactNode;
+  /** Per-chip pending spinner. */
+  readonly chipSpinner?: ReactNode;
+}
+
+export interface ToolStripProps {
+  readonly tools: ReadonlyArray<ToolCall>;
+  readonly skin?: SessionSkin;
+  readonly icons?: ToolStripIcons;
+  /** Collapse threshold; above this the strip starts collapsed. */
+  readonly collapseAbove?: number;
+}
+
+function Stat({
+  icon,
+  n,
+  color,
+  spin,
+}: {
+  readonly icon: ReactNode;
+  readonly n: number;
+  readonly color: string;
+  readonly spin?: boolean;
+}): ReactElement {
+  return (
+    <span
+      className="mono"
+      style={{
+        display: 'inline-flex',
+        alignItems: 'center',
+        gap: 3,
+        fontSize: 11,
+        color,
+      }}
+    >
+      <span className={spin ? 'xk-spin' : ''} style={{ display: 'inline-flex' }}>
+        {icon}
+      </span>
+      {n}
+    </span>
+  );
+}
+
+export function ToolChip({
+  tool,
+  skin = SessionSkin.Minimal,
+  spinnerIcon,
+}: {
+  readonly tool: ToolCall;
+  readonly skin?: SessionSkin;
+  readonly spinnerIcon?: ReactNode;
+}): ReactElement {
+  const [expanded, setExpanded] = useState(false);
+  const dotColor = toolStatusColor(tool.status);
+  const tint = skin === SessionSkin.Functional;
+  const isError = tool.status === ToolStatus.Error;
+  return (
+    <div style={{ display: 'inline-flex', flexDirection: 'column' }}>
+      <button
+        type="button"
+        onClick={() => tool.detail && setExpanded((v) => !v)}
+        style={{
+          display: 'inline-flex',
+          alignItems: 'center',
+          gap: 7,
+          padding: '5px 10px',
+          borderRadius: 8,
+          border: `1px solid ${tint && isError ? 'hsl(var(--destructive, var(--danger)) / 0.3)' : 'hsl(var(--rule))'}`,
+          background:
+            tint && isError
+              ? 'hsl(var(--destructive, var(--danger)) / 0.05)'
+              : 'hsl(var(--paper-elev))',
+          cursor: tool.detail ? 'pointer' : 'default',
+          maxWidth: 320,
+        }}
+      >
+        <span
+          style={{
+            width: 6,
+            height: 6,
+            borderRadius: '50%',
+            background: dotColor,
+            flexShrink: 0,
+          }}
+        />
+        {tool.icon && (
+          <span style={{ display: 'inline-flex', color: 'hsl(var(--ink-3))' }}>
+            {tool.icon}
+          </span>
+        )}
+        <span style={{ fontSize: 12.5, fontWeight: 500, color: 'hsl(var(--ink-2))' }}>
+          {tool.label}
+        </span>
+        {tool.arg && (
+          <span
+            className="mono"
+            style={{
+              fontSize: 11,
+              color: 'hsl(var(--ink-3))',
+              overflow: 'hidden',
+              textOverflow: 'ellipsis',
+              whiteSpace: 'nowrap',
+              maxWidth: 180,
+            }}
+          >
+            {tool.arg}
+          </span>
+        )}
+        {tool.status === ToolStatus.Pending && spinnerIcon && (
+          <span className="xk-spin" style={{ display: 'inline-flex', color: 'hsl(var(--warning))' }}>
+            {spinnerIcon}
+          </span>
+        )}
+        {tool.count !== undefined && tool.count > 1 && (
+          <span
+            className="mono"
+            style={{
+              fontSize: 10,
+              color: 'hsl(var(--ink-3))',
+              padding: '0 5px',
+              background: 'hsl(var(--muted))',
+              borderRadius: 6,
+            }}
+          >
+            ×{tool.count}
+          </span>
+        )}
+      </button>
+      {expanded && tool.detail && (
+        <pre
+          className="mono"
+          style={{
+            margin: '5px 0 0',
+            padding: '9px 11px',
+            background: 'hsl(var(--paper-sunk))',
+            border: '1px solid hsl(var(--rule))',
+            borderRadius: 8,
+            fontSize: 11,
+            lineHeight: 1.55,
+            color: 'hsl(var(--ink-2))',
+            maxWidth: 460,
+            overflowX: 'auto',
+            whiteSpace: 'pre-wrap',
+          }}
+        >
+          {tool.detail}
+        </pre>
+      )}
+    </div>
+  );
+}
+
+export function ToolStrip({
+  tools,
+  skin = SessionSkin.Minimal,
+  icons,
+  collapseAbove = 4,
+}: ToolStripProps): ReactElement {
+  const [open, setOpen] = useState(false);
+  const many = tools.length > collapseAbove;
+  const done = tools.filter((t) => t.status === ToolStatus.Done).length;
+  const error = tools.filter((t) => t.status === ToolStatus.Error).length;
+  const pending = tools.filter((t) => t.status === ToolStatus.Pending).length;
+
+  if (!many || open) {
+    return (
+      <div style={{ display: 'flex', flexWrap: 'wrap', gap: 6, marginTop: 9 }}>
+        {many && (
+          <button
+            type="button"
+            onClick={() => setOpen(false)}
+            style={{
+              fontSize: 11,
+              color: 'hsl(var(--ink-3))',
+              padding: '4px 8px',
+              borderRadius: 7,
+              border: '1px solid hsl(var(--rule))',
+              background: 'hsl(var(--paper-elev))',
+            }}
+          >
+            ‹ collapse
+          </button>
+        )}
+        {tools.map((tool, index) => (
+          <ToolChip
+            key={index}
+            tool={tool}
+            skin={skin}
+            spinnerIcon={icons?.chipSpinner}
+          />
+        ))}
+      </div>
+    );
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={() => setOpen(true)}
+      style={{
+        marginTop: 9,
+        display: 'flex',
+        alignItems: 'center',
+        gap: 9,
+        width: '100%',
+        padding: '7px 11px',
+        borderRadius: 9,
+        border: '1px solid hsl(var(--rule))',
+        background:
+          skin === SessionSkin.Functional
+            ? 'hsl(var(--muted))'
+            : 'hsl(var(--paper-elev))',
+        textAlign: 'left',
+      }}
+    >
+      {icons?.summary && (
+        <span style={{ display: 'inline-flex', color: 'hsl(var(--primary))' }}>
+          {icons.summary}
+        </span>
+      )}
+      <span style={{ fontSize: 12.5, fontWeight: 500, color: 'hsl(var(--ink-2))' }}>
+        {tools.length} tool calls
+      </span>
+      <span style={{ flex: 1 }} />
+      {done > 0 && icons?.done && (
+        <Stat icon={icons.done} n={done} color={toolStatusColor(ToolStatus.Done)} />
+      )}
+      {pending > 0 && icons?.pending && (
+        <Stat icon={icons.pending} n={pending} color={toolStatusColor(ToolStatus.Pending)} spin />
+      )}
+      {error > 0 && icons?.error && (
+        <Stat icon={icons.error} n={error} color={toolStatusColor(ToolStatus.Error)} />
+      )}
+      {icons?.chevron && (
+        <span style={{ display: 'inline-flex', color: 'hsl(var(--ink-4))' }}>
+          {icons.chevron}
+        </span>
+      )}
+    </button>
+  );
+}

package/src/session-kit/display/TypingDots.tsx

@@ -0,0 +1,24 @@
+/**
+ * Three bouncing dots — the agent "typing"/streaming indicator.
+ * Animation = the namespaced `xk-dot-bounce` keyframe (host stylesheet).
+ */
+import type { ReactElement } from 'react';
+
+export function TypingDots(): ReactElement {
+  return (
+    <span style={{ display: 'inline-flex', gap: 3, alignItems: 'center' }}>
+      {[0, 1, 2].map((i) => (
+        <span
+          key={i}
+          style={{
+            width: 5,
+            height: 5,
+            borderRadius: '50%',
+            background: 'hsl(var(--primary))',
+            animation: `xk-dot-bounce 1.1s ${i * 0.15}s infinite`,
+          }}
+        />
+      ))}
+    </span>
+  );
+}

package/src/session-kit/index.ts

@@ -0,0 +1,44 @@
+/**
+ * `@xemahq/ui-kernel/session-kit` — the thin, prop-driven generic
+ * component substrate for agent-session surfaces and the Portals
+ * chrome (Pillar 1 of the Xema Portals design handoff).
+ *
+ * Everything here is presentational and icon-agnostic: components take
+ * data + host-supplied icon nodes and emit inline-styled markup against
+ * the CSS-variable design tokens. No data fetching, no registry
+ * subscriptions, no framework imports — so the same kit renders inside
+ * the host shell and inside a biome's own surfaces.
+ *
+ * Pillar 2 consumes these via `import { … } from '@xemahq/ui-kernel/session-kit'`.
+ */
+
+// Closed-set enums + the authoritative status-dot map.
+export * from './lib/enums';
+export * from './lib/status-dot';
+export * from './lib/portal-accent';
+
+// Shared display primitives.
+export * from './primitives/RiskPill';
+export * from './primitives/ScopeDot';
+export * from './primitives/PortalGlyph';
+export * from './primitives/Avatar';
+export * from './primitives/Segmented';
+
+// Session display components.
+export * from './display/MD';
+export * from './display/TypingDots';
+export * from './display/TokenMeter';
+export * from './display/ContextHeader';
+export * from './display/MessageTurn';
+export * from './display/ToolStrip';
+export * from './display/ThinkingPanel';
+export * from './display/FileDiffCard';
+export * from './display/TodoChecklist';
+
+// Generic searchable picker.
+export * from './combobox/Combobox';
+export * from './combobox/use-click-outside';
+
+// Approvals primitive (Pillar 3 — generic frame + scoped bodies + sticky
+// bar + cross-portal Approvals Center).
+export * from './approvals';

package/src/session-kit/lib/enums.ts

@@ -0,0 +1,66 @@
+/**
+ * Closed-set enums for the session-kit. Every variant a component
+ * branches on is a real enum value (no free-form string literals), so
+ * the kit stays type-safe and the colour/icon maps below can be
+ * exhaustive.
+ *
+ * Risk tier is NOT redefined here — it is owned by the kernel
+ * (`CapabilityRiskTier`, low/medium/high/critical) and re-exported from
+ * `../primitives/RiskPill` so consumers import one canonical enum.
+ */
+
+/** Running status of a single tool call in the transcript. */
+export enum ToolStatus {
+  Pending = 'pending',
+  Done = 'done',
+  Error = 'error',
+}
+
+/**
+ * The four authoritative transcript status-dot states (HANDOFF §3.1).
+ * `Narration` is the hollow dot used by a `say` event — it is not a
+ * tool, so it sits outside `ToolStatus`.
+ */
+export enum SessionDotState {
+  Pending = 'pending',
+  Done = 'done',
+  Error = 'error',
+  Narration = 'narration',
+}
+
+/** Visual treatment of a status dot. */
+export enum SessionDotKind {
+  /** Solid fill in the token colour. */
+  Solid = 'solid',
+  /** Hollow ring (paper fill + rule border) — narration. */
+  Hollow = 'hollow',
+}
+
+/** A todo/plan checklist item's state. */
+export enum TodoState {
+  Todo = 'todo',
+  Active = 'active',
+  Done = 'done',
+}
+
+/** Biome provenance scope (drives the ScopeDot colour). */
+export enum BiomeScope {
+  System = 'system',
+  Platform = 'platform',
+  Community = 'community',
+}
+
+/**
+ * Look-and-feel variant. The kit defaults to `Minimal` (the thin/clean
+ * look the design converged on); `Functional` adds tinted surfaces.
+ */
+export enum SessionSkin {
+  Minimal = 'minimal',
+  Functional = 'functional',
+}
+
+/** A message turn's author role. */
+export enum TurnRole {
+  User = 'user',
+  Agent = 'agent',
+}

package/src/session-kit/lib/portal-accent.ts

@@ -0,0 +1,30 @@
+/**
+ * Per-portal accent token helper. A portal stores its accent as a CSS
+ * custom-property reference (`var(--p-finance)`, …); these helpers turn
+ * that into a concrete `hsl(...)` expression, with the brand `--primary`
+ * as the no-portal fallback.
+ *
+ * The token VALUES live in the host stylesheet (`--p-finance`, …). This
+ * module only composes the colour expression — it never hard-codes a
+ * hue, so re-skinning happens entirely in CSS.
+ */
+
+/** A portal's CSS accent variable, e.g. `var(--p-finance)`. */
+export type PortalAccentVar = `var(--${string})`;
+
+const PRIMARY = '--primary';
+
+/**
+ * Resolve a portal accent to an `hsl(...)` expression.
+ *
+ * @param accentVar the portal's `var(--p-*)` reference, or undefined for
+ *   "no active portal" (falls back to the brand `--primary`).
+ * @param alpha optional 0–1 alpha applied via the HSL `/ a` syntax.
+ */
+export function portalAccent(
+  accentVar: PortalAccentVar | undefined,
+  alpha?: number,
+): string {
+  const inner = accentVar ?? `var(${PRIMARY})`;
+  return alpha !== undefined ? `hsl(${inner} / ${alpha})` : `hsl(${inner})`;
+}

package/src/session-kit/lib/status-dot.ts

@@ -0,0 +1,68 @@
+/**
+ * Authoritative transcript status-dot colour map (HANDOFF §3.1).
+ *
+ *   pending / running → amber, PULSING   (--warning)
+ *   done / success    → green            (--success)
+ *   error             → red              (--danger / --destructive)
+ *   narration (`say`) → hollow ring      (--paper-elev fill + --rule-2 border)
+ *
+ * Encoded once here so every surface (rail dot, tool chip, tool-strip
+ * summary stat) reads from a single typed source instead of scattering
+ * the colour choices across components.
+ *
+ * Note on the danger token: host-web names it `--destructive`; the
+ * design names it `--danger`. We emit `--destructive` and fall back to
+ * `--danger` so the kit renders correctly under either token set.
+ */
+import { SessionDotKind, SessionDotState, ToolStatus } from './enums';
+
+export interface SessionDotStyle {
+  /** CSS colour expression for a solid dot. */
+  readonly color: string;
+  /** Solid vs hollow. */
+  readonly kind: SessionDotKind;
+  /** Whether the dot animates with the `xk-pulse-soft` keyframe. */
+  readonly pulsing: boolean;
+}
+
+const DANGER = 'hsl(var(--destructive, var(--danger)))';
+
+export const SESSION_DOT_STYLE: Record<SessionDotState, SessionDotStyle> = {
+  [SessionDotState.Pending]: {
+    color: 'hsl(var(--warning))',
+    kind: SessionDotKind.Solid,
+    pulsing: true,
+  },
+  [SessionDotState.Done]: {
+    color: 'hsl(var(--success))',
+    kind: SessionDotKind.Solid,
+    pulsing: false,
+  },
+  [SessionDotState.Error]: {
+    color: DANGER,
+    kind: SessionDotKind.Solid,
+    pulsing: false,
+  },
+  [SessionDotState.Narration]: {
+    color: 'hsl(var(--paper-elev))',
+    kind: SessionDotKind.Hollow,
+    pulsing: false,
+  },
+};
+
+/** Map a tool's running status onto its dot state. */
+export function dotStateForTool(status: ToolStatus): SessionDotState {
+  switch (status) {
+    case ToolStatus.Pending:
+      return SessionDotState.Pending;
+    case ToolStatus.Done:
+      return SessionDotState.Done;
+    case ToolStatus.Error:
+      return SessionDotState.Error;
+  }
+}
+
+/** Resolve the solid colour for a tool status (chips, summary stats). */
+export function toolStatusColor(status: ToolStatus): string {
+  return SESSION_DOT_STYLE[dotStateForTool(status)].color;
+}

package/src/session-kit/primitives/Avatar.tsx

@@ -0,0 +1,44 @@
+/**
+ * Circular initials avatar. Mono initials on a soft accent fill.
+ */
+import type { CSSProperties, ReactElement } from 'react';
+
+export interface AvatarProps {
+  readonly initials: string;
+  readonly size?: number;
+  /** Background fill. Defaults to the soft accent tint. */
+  readonly color?: string;
+  /** Initials colour. Defaults to the accent ink. */
+  readonly ink?: string;
+  readonly style?: CSSProperties;
+}
+
+export function Avatar({
+  initials,
+  size = 26,
+  color = 'hsl(var(--accent-2, var(--accent-tint)))',
+  ink = 'hsl(var(--primary-ink, var(--accent-ink)))',
+  style,
+}: AvatarProps): ReactElement {
+  return (
+    <span
+      className="mono"
+      style={{
+        width: size,
+        height: size,
+        borderRadius: '50%',
+        flexShrink: 0,
+        display: 'grid',
+        placeItems: 'center',
+        background: color,
+        color: ink,
+        fontSize: size * 0.4,
+        fontWeight: 600,
+        letterSpacing: '-0.02em',
+        ...style,
+      }}
+    >
+      {initials}
+    </span>
+  );
+}

package/src/session-kit/primitives/PortalGlyph.tsx

@@ -0,0 +1,51 @@
+/**
+ * Portal glyph — a rounded-square badge tinted with the portal's accent
+ * token. The glyph icon itself is supplied by the host as a `ReactNode`
+ * (the kit carries no icon set), matching the icon-agnostic convention
+ * used elsewhere in ui-kernel.
+ */
+import { portalAccent, type PortalAccentVar } from '../lib/portal-accent';
+
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+
+
+export interface PortalGlyphProps {
+  /** The portal's accent token, e.g. `var(--p-finance)`. Omit for the brand accent. */
+  readonly accentVar?: PortalAccentVar;
+  /** The portal's glyph (host-supplied icon node). */
+  readonly icon: ReactNode;
+  readonly size?: number;
+  readonly radius?: number;
+  /** Emphasised border + ring when the portal is the active one. */
+  readonly active?: boolean;
+  readonly style?: CSSProperties;
+}
+
+export function PortalGlyph({
+  accentVar,
+  icon,
+  size = 34,
+  radius = 9,
+  active = false,
+  style,
+}: PortalGlyphProps): ReactElement {
+  return (
+    <span
+      style={{
+        width: size,
+        height: size,
+        borderRadius: radius,
+        flexShrink: 0,
+        display: 'grid',
+        placeItems: 'center',
+        background: portalAccent(accentVar, 0.13),
+        color: portalAccent(accentVar),
+        border: `1px solid ${portalAccent(accentVar, active ? 0.5 : 0.22)}`,
+        boxShadow: active ? `0 0 0 1px ${portalAccent(accentVar, 0.25)}` : 'none',
+        ...style,
+      }}
+    >
+      {icon}
+    </span>
+  );
+}