@xemahq/ui-kernel 0.1.5 → 0.1.7

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>
+  );
+}

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

@@ -0,0 +1,140 @@
+/**
+ * Collapsible file-diff card — path + add/del counts in the header, an
+ * optional expandable unified-diff body. Disclosure + file icons are
+ * host-supplied.
+ */
+import { useState, type ReactElement, type ReactNode } from 'react';
+
+import { SessionSkin } from '../lib/enums';
+
+/**
+ * A single diff line: first character is the marker (`+` add, `-` del,
+ * ` ` context), the remainder is the line text.
+ */
+export type DiffLine = string;
+
+export interface DiffFile {
+  readonly path: string;
+  readonly add: number;
+  readonly del: number;
+  readonly hunks?: ReadonlyArray<DiffLine>;
+}
+
+export interface FileDiffCardProps {
+  readonly file: DiffFile;
+  readonly skin?: SessionSkin;
+  readonly collapsedIcon?: ReactNode;
+  readonly expandedIcon?: ReactNode;
+  readonly fileIcon?: ReactNode;
+}
+
+const DANGER_VAR = 'var(--destructive, var(--danger))';
+const DANGER = `hsl(${DANGER_VAR})`;
+const DANGER_SOFT = `hsl(${DANGER_VAR} / 0.06)`;
+
+export function FileDiffCard({
+  file,
+  skin = SessionSkin.Minimal,
+  collapsedIcon,
+  expandedIcon,
+  fileIcon,
+}: FileDiffCardProps): ReactElement {
+  const [open, setOpen] = useState(false);
+  const hasHunks = Boolean(file.hunks && file.hunks.length > 0);
+  return (
+    <div
+      style={{
+        marginTop: 9,
+        border: '1px solid hsl(var(--rule))',
+        borderRadius: 9,
+        overflow: 'hidden',
+        background: 'hsl(var(--paper-elev))',
+      }}
+    >
+      <button
+        type="button"
+        onClick={() => hasHunks && setOpen((v) => !v)}
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: 9,
+          width: '100%',
+          padding: '8px 11px',
+          textAlign: 'left',
+          cursor: hasHunks ? 'pointer' : 'default',
+          background:
+            skin === SessionSkin.Functional ? 'hsl(var(--muted))' : 'transparent',
+        }}
+      >
+        {hasHunks && (open ? expandedIcon : collapsedIcon)}
+        {fileIcon && (
+          <span style={{ display: 'inline-flex', color: 'hsl(var(--warning))' }}>
+            {fileIcon}
+          </span>
+        )}
+        <span
+          className="mono"
+          style={{
+            fontSize: 12,
+            color: 'hsl(var(--ink))',
+            overflow: 'hidden',
+            textOverflow: 'ellipsis',
+            whiteSpace: 'nowrap',
+          }}
+        >
+          {file.path}
+        </span>
+        <span style={{ flex: 1 }} />
+        <span className="mono" style={{ fontSize: 11, color: 'hsl(var(--success))' }}>
+          +{file.add}
+        </span>
+        <span className="mono" style={{ fontSize: 11, color: DANGER }}>
+          −{file.del}
+        </span>
+      </button>
+      {open && file.hunks && (
+        <div
+          className="mono"
+          style={{
+            borderTop: '1px solid hsl(var(--rule))',
+            fontSize: 11.5,
+            lineHeight: 1.6,
+            overflowX: 'auto',
+          }}
+        >
+          {file.hunks.map((line, index) => {
+            const marker = line[0];
+            const text = line.slice(1);
+            const bg =
+              marker === '+'
+                ? 'hsl(var(--success) / 0.07)'
+                : marker === '-'
+                  ? DANGER_SOFT
+                  : 'transparent';
+            const color =
+              marker === '+'
+                ? 'hsl(var(--success))'
+                : marker === '-'
+                  ? DANGER
+                  : 'hsl(var(--ink-3))';
+            return (
+              <div key={index} style={{ display: 'flex', background: bg, padding: '0 11px' }}>
+                <span style={{ width: 14, color, flexShrink: 0 }}>
+                  {marker === ' ' ? '' : marker}
+                </span>
+                <span
+                  style={{
+                    color: marker === ' ' ? 'hsl(var(--ink-3))' : 'hsl(var(--ink-2))',
+                    whiteSpace: 'pre',
+                  }}
+                >
+                  {text}
+                </span>
+              </div>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+}