@xemahq/ui-kernel 0.1.6 → 0.1.8

package/src/session-kit/approvals/obligation-display.ts

@@ -0,0 +1,100 @@
+/**
+ * Obligation → display metadata map (HANDOFF §6).
+ *
+ * Covers ALL NINE obligation kinds in the kernel closed taxonomy —
+ * `audit`, `redact-secrets`, `require-runner-kind`,
+ * `require-human-approval`, `max-duration-seconds`, `max-cost-usd`,
+ * `restrict-output-classification`, `data-residency`, `egress-allowlist`.
+ *
+ * The map is typed `Record<PolicyObligationKind, …>` so it is EXHAUSTIVE
+ * over the installed kernel enum: adding a new `PolicyObligationKind`
+ * member is a COMPILE ERROR here until it gets a label + icon key. The
+ * published `@xemahq/kernel-contracts` enum now ships all nine members
+ * (incl. `egress-allowlist`), so every kind is keyed directly by its enum
+ * value — no literal-wire fallback is needed.
+ *
+ * The kit is icon-agnostic: this module names a stable `iconKey`
+ * (`ObligationIcon`) and the host translates it into a concrete icon node
+ * via the `Obligation`/`renderIcon` prop. No icon dependency leaks into
+ * the kernel package.
+ */
+import { PolicyObligationKind } from '@xemahq/kernel-contracts/policy';
+
+/**
+ * Stable, icon-set-agnostic glyph keys for obligation chips. The host
+ * maps each onto a concrete icon (lucide, etc.); the kit never imports an
+ * icon set. Closed set — one key per obligation family.
+ */
+export enum ObligationIcon {
+  Dollar = 'dollar',
+  ShieldCheck = 'shield-check',
+  Scroll = 'scroll',
+  Eye = 'eye',
+  Clock = 'clock',
+  Layers = 'layers',
+  Globe = 'globe',
+  Lock = 'lock',
+  Network = 'network',
+}
+
+export interface ObligationDisplayMeta {
+  readonly iconKey: ObligationIcon;
+  readonly label: string;
+}
+
+/**
+ * Chip metadata for every member of the kernel `PolicyObligationKind`
+ * enum. Typed as `Record<PolicyObligationKind, …>` so adding a new kernel
+ * enum member is a COMPILE ERROR here until it gets a label + icon key —
+ * the exhaustiveness guarantee.
+ */
+const ENUM_OBLIGATION_DISPLAY: Record<
+  PolicyObligationKind,
+  ObligationDisplayMeta
+> = {
+  [PolicyObligationKind.MaxCostUsd]: {
+    iconKey: ObligationIcon.Dollar,
+    label: 'Spend cap',
+  },
+  [PolicyObligationKind.RequireHumanApproval]: {
+    iconKey: ObligationIcon.ShieldCheck,
+    label: 'Human approval',
+  },
+  [PolicyObligationKind.Audit]: {
+    iconKey: ObligationIcon.Scroll,
+    label: 'Audited',
+  },
+  [PolicyObligationKind.RestrictOutputClassification]: {
+    iconKey: ObligationIcon.Eye,
+    label: 'Output limited',
+  },
+  [PolicyObligationKind.MaxDurationSeconds]: {
+    iconKey: ObligationIcon.Clock,
+    label: 'Time cap',
+  },
+  [PolicyObligationKind.RequireRunnerKind]: {
+    iconKey: ObligationIcon.Layers,
+    label: 'Runner',
+  },
+  [PolicyObligationKind.DataResidency]: {
+    iconKey: ObligationIcon.Globe,
+    label: 'Residency',
+  },
+  [PolicyObligationKind.RedactSecrets]: {
+    iconKey: ObligationIcon.Lock,
+    label: 'Redacted',
+  },
+  [PolicyObligationKind.EgressAllowlist]: {
+    iconKey: ObligationIcon.Network,
+    label: 'Egress',
+  },
+};
+
+/**
+ * The authoritative obligation-kind → chip metadata map, keyed by the
+ * obligation wire-string. Exhaustive over the installed kernel enum via
+ * `ENUM_OBLIGATION_DISPLAY` (compile-checked).
+ */
+export const OBLIGATION_DISPLAY: Record<string, ObligationDisplayMeta> = {
+  ...ENUM_OBLIGATION_DISPLAY,
+};

package/src/session-kit/approvals/risk-accent.ts

@@ -0,0 +1,47 @@
+/**
+ * Risk-tier → colour expressions for the approval frame's accent rail and
+ * the sticky bar (HANDOFF §6). RiskPill owns the PILL styling; this map is
+ * the matching surface accent (foreground / soft background / border) the
+ * frame and bar paint with. Both read the SAME kernel `CapabilityRiskTier`
+ * enum so the pill and the rail can never disagree on a tier's colour.
+ *
+ *   low      → ink / muted   (quiet)
+ *   medium   → --info
+ *   high     → --warning
+ *   critical → --destructive / --danger
+ */
+import { CapabilityRiskTier } from '@xemahq/kernel-contracts/capability';
+
+export interface RiskAccent {
+  /** Solid accent (rail, icon, critical button). */
+  readonly fg: string;
+  /** Soft tinted background (sticky bar surface). */
+  readonly bg: string;
+  /** Border (sticky bar, critical card outline). */
+  readonly bd: string;
+}
+
+const DANGER = 'var(--destructive, var(--danger))';
+
+export const RISK_ACCENT: Record<CapabilityRiskTier, RiskAccent> = {
+  [CapabilityRiskTier.Low]: {
+    fg: 'hsl(var(--ink-3))',
+    bg: 'hsl(var(--muted))',
+    bd: 'hsl(var(--rule))',
+  },
+  [CapabilityRiskTier.Medium]: {
+    fg: 'hsl(var(--info))',
+    bg: 'hsl(var(--info) / 0.07)',
+    bd: 'hsl(var(--info) / 0.28)',
+  },
+  [CapabilityRiskTier.High]: {
+    fg: 'hsl(var(--warning))',
+    bg: 'hsl(var(--warning) / 0.08)',
+    bd: 'hsl(var(--warning) / 0.3)',
+  },
+  [CapabilityRiskTier.Critical]: {
+    fg: `hsl(${DANGER})`,
+    bg: `hsl(${DANGER} / 0.07)`,
+    bd: `hsl(${DANGER} / 0.32)`,
+  },
+};

package/src/session-kit/approvals/scope-icons.ts

@@ -0,0 +1,19 @@
+/**
+ * Stable, icon-set-agnostic glyph keys used by the scoped approval bodies
+ * (`ScopedBody`). Kept in its own module (not alongside the body
+ * components) so the icon bundle and the bodies can both import it without
+ * a component file also exporting a non-component value.
+ */
+import type { ReactNode } from 'react';
+
+export enum ScopeIcon {
+  Database = 'database',
+  Layers = 'layers',
+  Alert = 'alert',
+  Send = 'send',
+  Globe = 'globe',
+  ArrowRight = 'arrow-right',
+  FileEdit = 'file-edit',
+}
+
+export type ScopeIconRenderer = (key: ScopeIcon, size: number) => ReactNode;

package/src/session-kit/combobox/Combobox.tsx

@@ -0,0 +1,327 @@
+/**
+ * Generic searchable picker (HANDOFF §7). Use it wherever a closed set
+ * is selected (agents, models, skills/tools, …).
+ *
+ * - Shows a search field when `items.length > searchThreshold` (default
+ *   7) with a live `shown/total` count.
+ * - Scrolls a long list (max-height 240).
+ * - Single OR multi (checkbox) select via a discriminated `multi` flag.
+ * - Long labels truncate with ellipsis in the trigger; the list always
+ *   shows the full label.
+ * - Opens up/down, left/right aligned, with an optional footer slot.
+ * - Click-outside closes (and clears the query).
+ *
+ * Standalone (not built on a host Popover): the design's behaviour is a
+ * small self-contained surface (click-outside + absolute positioning),
+ * and this package is layer-agnostic ui-kernel — it must not depend on
+ * host primitives. So we ship a minimal, faithful standalone impl. The
+ * search/check/checkbox icons are host-supplied (icon-agnostic kit).
+ */
+import {
+  useEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+
+import { useClickOutside } from './use-click-outside';
+
+export interface ComboboxItem<V extends string> {
+  readonly value: V;
+  readonly label: string;
+  /** Secondary muted line under the label. */
+  readonly hint?: string;
+  /** Leading icon node (host-supplied). */
+  readonly icon?: ReactNode;
+  /** Small uppercase kind tag on the right (`.cap`). */
+  readonly kind?: string;
+  /** Render the label in the mono face. */
+  readonly mono?: boolean;
+}
+
+/**
+ * Trigger render-prop state. The consumer renders its own interactive
+ * trigger element (typically a `<button>`) and wires `toggle` to its
+ * `onClick`, so the picker never nests interactive elements.
+ */
+export interface ComboboxTriggerState<V extends string> {
+  readonly open: boolean;
+  /** The selected item (single-select only; `undefined` in multi mode). */
+  readonly selected: ComboboxItem<V> | undefined;
+  /** Toggle the dropdown open/closed. */
+  readonly toggle: () => void;
+}
+
+export type ComboboxTrigger<V extends string> = (
+  state: ComboboxTriggerState<V>,
+) => ReactNode;
+
+/** Host-supplied icons (kit carries no icon set). */
+export interface ComboboxIcons {
+  readonly search?: ReactNode;
+  /** Check mark for the selected single-select row. */
+  readonly check?: ReactNode;
+  /** Check mark rendered inside a ticked multi-select box. */
+  readonly multiCheck?: ReactNode;
+}
+
+export type ComboboxAlign = 'left' | 'right';
+
+interface ComboboxBaseProps<V extends string> {
+  readonly items: ReadonlyArray<ComboboxItem<V>>;
+  readonly trigger: ComboboxTrigger<V>;
+  readonly icons?: ComboboxIcons;
+  readonly placeholder?: string;
+  readonly searchThreshold?: number;
+  readonly align?: ComboboxAlign;
+  /** Open upward instead of downward. */
+  readonly up?: boolean;
+  readonly width?: number;
+  readonly footer?: ReactNode;
+}
+
+interface ComboboxSingleProps<V extends string> extends ComboboxBaseProps<V> {
+  readonly multi?: false;
+  readonly value: V | undefined;
+  readonly onChange: (value: V) => void;
+}
+
+interface ComboboxMultiProps<V extends string> extends ComboboxBaseProps<V> {
+  readonly multi: true;
+  readonly value: ReadonlyArray<V>;
+  readonly onChange: (value: V) => void;
+}
+
+export type ComboboxProps<V extends string> =
+  | ComboboxSingleProps<V>
+  | ComboboxMultiProps<V>;
+
+const POP_STYLE: CSSProperties = {
+  position: 'absolute',
+  zIndex: 60,
+  borderRadius: 11,
+  background: 'hsl(var(--paper-elev))',
+  border: '1px solid hsl(var(--rule-2))',
+  boxShadow: 'var(--shadow-28, var(--shadow-pop))',
+  overflow: 'hidden',
+};
+
+export function Combobox<V extends string>(props: ComboboxProps<V>): ReactElement {
+  const {
+    items,
+    trigger,
+    icons,
+    placeholder = 'Search…',
+    searchThreshold = 7,
+    align = 'left',
+    up = false,
+    width = 240,
+    footer,
+  } = props;
+
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState('');
+  const ref = useClickOutside<HTMLDivElement>(() => {
+    setOpen(false);
+    setQuery('');
+  });
+  const searchRef = useRef<HTMLInputElement>(null);
+
+  const showSearch = items.length > searchThreshold;
+
+  // Move focus to the search field when the dropdown opens (replaces the
+  // a11y-discouraged `autoFocus` attribute).
+  useEffect(() => {
+    if (open && showSearch) searchRef.current?.focus();
+  }, [open, showSearch]);
+
+  const filtered = query
+    ? items.filter((it) =>
+        `${it.label} ${it.hint ?? ''}`.toLowerCase().includes(query.toLowerCase()),
+      )
+    : items;
+
+  const isOn = (value: V): boolean =>
+    props.multi ? props.value.includes(value) : props.value === value;
+
+  const selected = props.multi
+    ? undefined
+    : items.find((it) => it.value === props.value);
+
+  function pick(value: V): void {
+    props.onChange(value);
+    if (!props.multi) {
+      setOpen(false);
+      setQuery('');
+    }
+  }
+
+  const pos: CSSProperties = up
+    ? { bottom: 'calc(100% + 6px)' }
+    : { top: 'calc(100% + 6px)' };
+
+  return (
+    <div
+      ref={ref}
+      style={{ position: 'relative', display: 'inline-flex', flexShrink: 0 }}
+    >
+      {trigger({ open, selected, toggle: () => setOpen((o) => !o) })}
+      {open && (
+        <div style={{ ...POP_STYLE, ...pos, [align]: 0, width }}>
+          {showSearch && (
+            <div
+              style={{
+                display: 'flex',
+                alignItems: 'center',
+                gap: 7,
+                padding: '9px 11px',
+                borderBottom: '1px solid hsl(var(--rule))',
+              }}
+            >
+              {icons?.search && (
+                <span style={{ display: 'inline-flex', color: 'hsl(var(--ink-3))' }}>
+                  {icons.search}
+                </span>
+              )}
+              <input
+                ref={searchRef}
+                value={query}
+                onChange={(e) => setQuery(e.target.value)}
+                placeholder={placeholder}
+                style={{
+                  flex: 1,
+                  border: 'none',
+                  outline: 'none',
+                  background: 'transparent',
+                  fontSize: 13,
+                  color: 'hsl(var(--ink))',
+                }}
+              />
+              {items.length > 0 && (
+                <span className="mono" style={{ fontSize: 10, color: 'hsl(var(--ink-4))' }}>
+                  {filtered.length}/{items.length}
+                </span>
+              )}
+            </div>
+          )}
+          <div style={{ maxHeight: 240, overflowY: 'auto', padding: 5 }}>
+            {filtered.map((it) => {
+              const on = isOn(it.value);
+              const singleSelected = on && !props.multi;
+              return (
+                <button
+                  type="button"
+                  key={it.value}
+                  onClick={() => pick(it.value)}
+                  style={{
+                    display: 'flex',
+                    alignItems: 'center',
+                    gap: 9,
+                    width: '100%',
+                    padding: '7px 9px',
+                    borderRadius: 7,
+                    textAlign: 'left',
+                    background: singleSelected ? 'hsl(var(--accent) / 0.6)' : 'transparent',
+                    transition: 'background 140ms ease',
+                  }}
+                  onMouseEnter={(e) => {
+                    if (!singleSelected) {
+                      e.currentTarget.style.background = 'hsl(var(--paper-sunk))';
+                    }
+                  }}
+                  onMouseLeave={(e) => {
+                    if (!singleSelected) {
+                      e.currentTarget.style.background = 'transparent';
+                    }
+                  }}
+                >
+                  {it.icon && (
+                    <span style={{ display: 'inline-flex', color: 'hsl(var(--ink-3))', flexShrink: 0 }}>
+                      {it.icon}
+                    </span>
+                  )}
+                  <span style={{ flex: 1, minWidth: 0 }}>
+                    <span
+                      className={it.mono ? 'mono' : ''}
+                      style={{
+                        display: 'block',
+                        fontSize: it.mono ? 12 : 12.5,
+                        color: 'hsl(var(--ink))',
+                        overflow: 'hidden',
+                        textOverflow: 'ellipsis',
+                        whiteSpace: 'nowrap',
+                      }}
+                    >
+                      {it.label}
+                    </span>
+                    {it.hint && (
+                      <span
+                        style={{
+                          display: 'block',
+                          fontSize: 10.5,
+                          color: 'hsl(var(--ink-4))',
+                          overflow: 'hidden',
+                          textOverflow: 'ellipsis',
+                          whiteSpace: 'nowrap',
+                        }}
+                      >
+                        {it.hint}
+                      </span>
+                    )}
+                  </span>
+                  {it.kind && (
+                    <span className="cap" style={{ fontSize: 8.5, flexShrink: 0 }}>
+                      {it.kind}
+                    </span>
+                  )}
+                  {props.multi ? (
+                    <span
+                      style={{
+                        width: 17,
+                        height: 17,
+                        borderRadius: 5,
+                        flexShrink: 0,
+                        display: 'grid',
+                        placeItems: 'center',
+                        background: on ? 'hsl(var(--primary))' : 'transparent',
+                        border: on ? 'none' : '1.5px solid hsl(var(--rule-2))',
+                        color: '#fff',
+                      }}
+                    >
+                      {on && icons?.multiCheck}
+                    </span>
+                  ) : (
+                    on && (
+                      <span style={{ display: 'inline-flex', color: 'hsl(var(--primary))', flexShrink: 0 }}>
+                        {icons?.check}
+                      </span>
+                    )
+                  )}
+                </button>
+              );
+            })}
+            {filtered.length === 0 && (
+              <div
+                style={{
+                  padding: '18px 0',
+                  textAlign: 'center',
+                  fontSize: 12,
+                  color: 'hsl(var(--ink-4))',
+                }}
+              >
+                No matches
+              </div>
+            )}
+          </div>
+          {footer && (
+            <div style={{ borderTop: '1px solid hsl(var(--rule))', padding: 6 }}>
+              {footer}
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/session-kit/combobox/use-click-outside.ts

@@ -0,0 +1,21 @@
+/**
+ * Close-on-outside-click hook. Returns a ref to attach to the element
+ * whose interior clicks should NOT trigger `onClose`.
+ */
+import { useEffect, useRef, type RefObject } from 'react';
+
+export function useClickOutside<T extends HTMLElement>(
+  onClose: () => void,
+): RefObject<T> {
+  const ref = useRef<T>(null);
+  useEffect(() => {
+    function handle(event: MouseEvent): void {
+      if (ref.current && !ref.current.contains(event.target as Node)) {
+        onClose();
+      }
+    }
+    document.addEventListener('mousedown', handle);
+    return () => document.removeEventListener('mousedown', handle);
+  }, [onClose]);
+  return ref;
+}

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

@@ -0,0 +1,148 @@
+/**
+ * Session context header — agent / model / environment / audience meta
+ * row with the token meter pinned to the right. Icons are host-supplied
+ * (`ReactNode`) so the kit stays icon-agnostic.
+ */
+import { TokenMeter, type TokenCounts } from './TokenMeter';
+import { SessionSkin } from '../lib/enums';
+
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+
+
+export interface ContextHeaderSession {
+  readonly agent: string;
+  readonly model: string;
+  readonly environment: string;
+  readonly audience: string;
+  readonly tokens: TokenCounts;
+  readonly cost: number;
+}
+
+/** Host-supplied icon nodes for each meta row. All optional. */
+export interface ContextHeaderIcons {
+  readonly agent?: ReactNode;
+  readonly model?: ReactNode;
+  readonly environment?: ReactNode;
+  readonly audience?: ReactNode;
+}
+
+export interface ContextHeaderProps {
+  readonly session: ContextHeaderSession;
+  readonly icons?: ContextHeaderIcons;
+  readonly skin?: SessionSkin;
+  /**
+   * Audience value treated as the default (un-flagged) audience. When the
+   * session's audience differs, the audience meta is shown with a warn tone.
+   */
+  readonly defaultAudience?: string;
+  /**
+   * Environment value treated as production (shown with a warn tone).
+   */
+  readonly productionEnvironment?: string;
+  readonly style?: CSSProperties;
+}
+
+function MetaDot(): ReactElement {
+  return (
+    <span
+      style={{
+        width: 3,
+        height: 3,
+        borderRadius: '50%',
+        background: 'hsl(var(--ink-4) / 0.6)',
+      }}
+    />
+  );
+}
+
+type MetaTone = 'default' | 'strong' | 'warn';
+
+function Meta({
+  icon,
+  label,
+  mono,
+  tone = 'default',
+}: {
+  readonly icon?: ReactNode;
+  readonly label: string;
+  readonly mono?: boolean;
+  readonly tone?: MetaTone;
+}): ReactElement {
+  const color =
+    tone === 'warn'
+      ? 'hsl(var(--warning))'
+      : tone === 'strong'
+        ? 'hsl(var(--ink))'
+        : 'hsl(var(--ink-3))';
+  return (
+    <span
+      style={{
+        display: 'inline-flex',
+        alignItems: 'center',
+        gap: 5,
+        color,
+        fontSize: 12,
+        fontWeight: tone === 'strong' ? 600 : 450,
+        whiteSpace: 'nowrap',
+      }}
+    >
+      {icon && (
+        <span style={{ display: 'inline-flex', opacity: 0.8 }}>{icon}</span>
+      )}
+      <span
+        className={mono ? 'mono' : ''}
+        style={{ fontSize: mono ? 11.5 : 12, whiteSpace: 'nowrap' }}
+      >
+        {label}
+      </span>
+    </span>
+  );
+}
+
+export function ContextHeader({
+  session,
+  icons,
+  skin = SessionSkin.Minimal,
+  defaultAudience = 'internal-org',
+  productionEnvironment = 'production',
+  style,
+}: ContextHeaderProps): ReactElement {
+  const showAudience = session.audience !== defaultAudience;
+  return (
+    <div
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: 10,
+        flexWrap: 'wrap',
+        padding: '8px 14px',
+        borderBottom: '1px solid hsl(var(--rule))',
+        background:
+          skin === SessionSkin.Functional
+            ? 'hsl(var(--paper-elev))'
+            : 'hsl(var(--paper) / 0.6)',
+        backdropFilter: 'blur(6px)',
+        ...style,
+      }}
+    >
+      <Meta icon={icons?.agent} label={session.agent} tone="strong" />
+      <MetaDot />
+      <Meta icon={icons?.model} label={session.model} mono />
+      <MetaDot />
+      <Meta
+        icon={icons?.environment}
+        label={session.environment}
+        mono
+        tone={session.environment === productionEnvironment ? 'warn' : 'default'}
+      />
+      {showAudience && (
+        <>
+          <MetaDot />
+          <Meta icon={icons?.audience} label={session.audience} mono tone="warn" />
+        </>
+      )}
+      <div style={{ flex: 1 }} />
+      <TokenMeter tokens={session.tokens} cost={session.cost} skin={skin} />
+    </div>
+  );
+}