@grampro/kit 0.0.0-stage → 2.4.0

package/source/components/shared/react/GramproAIProvider.tsx

@@ -0,0 +1,50 @@
+"use client";
+
+import { createContext, useContext, useMemo, type ReactNode } from "react";
+import type { AgentAdapter } from "../core/agent/adapter";
+
+/*
+ * Where an application plugs its own language model in.
+ *
+ * Nothing below this provider knows which one it is. A component asks the
+ * context for an adapter; if there is none, the component renders exactly as
+ * it does today and its natural-language affordance is simply absent. That is
+ * the whole opt-in: no provider, no AI, no bytes, no network.
+ */
+
+interface AIContextValue {
+  adapter: AgentAdapter | null;
+  /** Shown above the input, e.g. "Ask about these customers". */
+  placeholder?: string;
+  /** Example utterances offered as one-click suggestions. */
+  suggestions?: readonly string[];
+}
+
+const AIContext = createContext<AIContextValue>({ adapter: null });
+
+export interface GramproAIProviderProps extends AIContextValue {
+  children: ReactNode;
+}
+
+export function GramproAIProvider({
+  adapter,
+  placeholder,
+  suggestions,
+  children,
+}: GramproAIProviderProps) {
+  const value = useMemo(
+    () => ({ adapter, placeholder, suggestions }),
+    [adapter, placeholder, suggestions],
+  );
+  return <AIContext.Provider value={value}>{children}</AIContext.Provider>;
+}
+
+/**
+ * The adapter in scope, or null.
+ *
+ * Null is an ordinary case, not an error: a component asks, gets nothing, and
+ * renders without the affordance.
+ */
+export function useAgentAdapter(): AIContextValue {
+  return useContext(AIContext);
+}

package/source/components/shared/react/Popover.tsx

@@ -0,0 +1,189 @@
+"use client";
+
+import { useLayoutEffect, useRef, type ReactNode, type ToggleEvent } from "react";
+import { cx } from "../core/cx";
+import { placePopover, type Align, type Side } from "../core/position";
+
+/** Space kept between the popover and the edge of the viewport. */
+const EDGE = 8;
+
+export interface AnchoredPopoverProps {
+  /** The element the popover is positioned against. */
+  anchor: HTMLElement;
+  /** Called when the browser light-dismisses it, or Escape closes it. */
+  onClose(): void;
+  children: ReactNode;
+  id?: string;
+  className?: string;
+  /**
+   * Gives the popover `role="dialog"` and this accessible name. Leave it and
+   * `labelledBy` out for content that carries its own role, such as a listbox.
+   */
+  label?: string;
+  /** Names the popover from an element inside it, such as its heading. */
+  labelledBy?: string;
+  /** Points at a description inside the popover. */
+  describedBy?: string;
+  /** `menu` for a list of commands, `tooltip` for a label; otherwise a dialog. */
+  role?: "dialog" | "menu" | "tooltip";
+  /** The side of the anchor to open on, before flipping. Default `bottom`. */
+  side?: Side;
+  /** Which edge of the anchor to align to, in reading order. Default `start`. */
+  align?: Align;
+  /** Distance between the anchor and the popover. Default 4. */
+  gap?: number;
+  /** Make the popover at least as wide as its anchor. */
+  matchAnchorWidth?: boolean;
+  /**
+   * Cap the height to the free space on the chosen side, and prefer the side
+   * with more room. For scrolling content such as a long list; panels that
+   * cannot scroll should leave it off so they only flip when they fully fit.
+   */
+  fitHeight?: boolean;
+  /** Floor for `fitHeight`, so a cramped viewport still shows something. Default 140. */
+  minHeight?: number;
+  /**
+   * Where focus goes when it opens: a selector, `true` for the first
+   * `[data-autofocus]` and otherwise the popover itself, or `false` to leave
+   * focus where it is. A popover focused this way needs `tabIndex={-1}`.
+   */
+  autoFocus?: string | boolean;
+  /** Reposition when the popover resizes (`self`) or the anchor does too (`both`). */
+  observeResize?: "self" | "both" | false;
+  /** Put focus back on the anchor when the popover closes. */
+  returnFocus?: boolean;
+  /**
+   * `auto` (the default) gets the browser's light dismiss and Escape, and is
+   * right for anything opened deliberately. `manual` opts out of both, for
+   * content that appears beside something else and must not close it: opening
+   * an `auto` popover closes every other one, so a tooltip or a submenu over an
+   * open menu would take the menu down with it. Manual popovers handle their
+   * own dismissal.
+   */
+  mode?: "auto" | "manual";
+}
+
+/**
+ * Anchored popover on the native Popover API: rendered in the top layer, so it
+ * is never clipped by a scrolling parent or an `overflow: hidden` ancestor, and
+ * the browser provides light dismiss and Escape. Mount it to open, unmount it
+ * to close.
+ *
+ * Positioning is deliberately plain — align, clamp to the viewport, flip when
+ * there is no room below — because that is all any of the components need, and
+ * it keeps the library free of a positioning dependency.
+ */
+export function AnchoredPopover({
+  anchor,
+  onClose,
+  children,
+  id,
+  className,
+  label,
+  labelledBy,
+  describedBy,
+  role,
+  side = "bottom",
+  align = "start",
+  gap = 4,
+  matchAnchorWidth = false,
+  fitHeight = false,
+  minHeight = 140,
+  autoFocus = "[data-autofocus]",
+  observeResize = false,
+  returnFocus = false,
+  mode = "auto",
+}: AnchoredPopoverProps) {
+  const ref = useRef<HTMLDivElement>(null);
+
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+
+    const position = () => {
+      const rect = anchor.getBoundingClientRect();
+      if (matchAnchorWidth) el.style.minWidth = `${rect.width}px`;
+
+      const placement = placePopover(
+        rect,
+        { width: el.offsetWidth, height: el.offsetHeight },
+        { width: window.innerWidth, height: window.innerHeight },
+        {
+          side,
+          align,
+          gap,
+          edge: EDGE,
+          rtl: getComputedStyle(anchor).direction === "rtl",
+          fitHeight,
+          minHeight,
+        },
+      );
+
+      el.style.left = `${placement.left}px`;
+      el.style.top = `${placement.top}px`;
+      if (placement.maxHeight !== undefined) el.style.maxHeight = `${placement.maxHeight}px`;
+      // Lets a stylesheet point an arrow, or slide the panel in from the right
+      // direction, without measuring anything itself.
+      el.dataset.side = placement.side;
+    };
+
+    el.showPopover();
+    position();
+    // A popover is display:none until it is shown, so focus only lands after
+    // showPopover().
+    if (autoFocus) {
+      const selector = typeof autoFocus === "string" ? autoFocus : "[data-autofocus]";
+      const target = el.querySelector<HTMLElement>(selector) ?? (autoFocus === true ? el : null);
+      target?.focus({ preventScroll: true });
+    }
+
+    const observer = observeResize ? new ResizeObserver(position) : null;
+    observer?.observe(el);
+    if (observeResize === "both") observer?.observe(anchor);
+    window.addEventListener("resize", position);
+    // Capture: a scroll in any ancestor moves the anchor, not just the page.
+    window.addEventListener("scroll", position, true);
+
+    return () => {
+      observer?.disconnect();
+      window.removeEventListener("resize", position);
+      window.removeEventListener("scroll", position, true);
+      const hadFocus = el.contains(document.activeElement);
+      if (el.matches(":popover-open")) el.hidePopover();
+      if (returnFocus && (hadFocus || document.activeElement === document.body) && anchor.isConnected) {
+        anchor.focus({ preventScroll: true });
+      }
+    };
+  }, [
+    anchor,
+    side,
+    align,
+    gap,
+    matchAnchorWidth,
+    fitHeight,
+    minHeight,
+    autoFocus,
+    observeResize,
+    returnFocus,
+  ]);
+
+  return (
+    <div
+      ref={ref}
+      id={id}
+      popover={mode}
+      // Focusable only from script, so `autoFocus` can land on the panel itself.
+      tabIndex={-1}
+      role={role ?? (label || labelledBy ? "dialog" : undefined)}
+      aria-label={label}
+      aria-labelledby={labelledBy}
+      aria-describedby={describedBy}
+      className={cx(className)}
+      onToggle={(event: ToggleEvent<HTMLDivElement>) => {
+        if (event.newState === "closed") onClose();
+      }}
+    >
+      {children}
+    </div>
+  );
+}

package/source/components/shared/react/icons.tsx

@@ -0,0 +1,74 @@
+import type { SVGProps } from "react";
+
+export type IconProps = SVGProps<SVGSVGElement>;
+
+/**
+ * The base every icon draws on: a 24-unit grid, stroked in `currentColor`, and
+ * hidden from assistive technology because the control around it carries the
+ * name. Size it by passing `width` and `height`.
+ */
+export function Svg(props: IconProps) {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      focusable="false"
+      {...props}
+    />
+  );
+}
+
+/*
+ * Glyphs more than one component draws. A component keeps its own icons file
+ * for anything only it uses, and re-exports from here for the rest, so a fix to
+ * a shape lands everywhere at once.
+ */
+
+export const XIcon = (p: IconProps) => <Svg {...p}><path d="M18 6 6 18M6 6l12 12" /></Svg>;
+export const CheckIcon = (p: IconProps) => <Svg {...p}><path d="M20 6 9 17l-5-5" /></Svg>;
+export const ChevronDownIcon = (p: IconProps) => <Svg {...p}><path d="m6 9 6 6 6-6" /></Svg>;
+export const ChevronLeftIcon = (p: IconProps) => <Svg {...p}><path d="m15 18-6-6 6-6" /></Svg>;
+export const ChevronRightIcon = (p: IconProps) => <Svg {...p}><path d="m9 18 6-6-6-6" /></Svg>;
+
+export const SearchIcon = (p: IconProps) => (
+  <Svg {...p}><circle cx="11" cy="11" r="7" /><path d="m20 20-3.5-3.5" /></Svg>
+);
+
+export const SuccessIcon = (p: IconProps) => (
+  <Svg {...p}>
+    <circle cx="12" cy="12" r="9" />
+    <path d="m8 12.5 2.5 2.5L16 9.5" />
+  </Svg>
+);
+
+/** The circled exclamation used for errors, danger and alerts alike. */
+export const AlertCircleIcon = (p: IconProps) => (
+  <Svg {...p}>
+    <circle cx="12" cy="12" r="9" />
+    <path d="M12 7.5v5.5M12 16.5h.01" />
+  </Svg>
+);
+
+export const WarningIcon = (p: IconProps) => (
+  <Svg {...p}>
+    <path d="M10.3 3.9 2.4 18a2 2 0 0 0 1.7 3h15.8a2 2 0 0 0 1.7-3L13.7 3.9a2 2 0 0 0-3.4 0Z" />
+    <path d="M12 9v4M12 17h.01" />
+  </Svg>
+);
+
+export const InfoIcon = (p: IconProps) => (
+  <Svg {...p}>
+    <circle cx="12" cy="12" r="9" />
+    <path d="M12 11v5M12 7.5h.01" />
+  </Svg>
+);
+
+/** The arc only; the spin comes from each component's own stylesheet. */
+export const SpinnerIcon = (p: IconProps) => <Svg {...p}><path d="M12 3a9 9 0 1 0 9 9" /></Svg>;

package/source/components/shared/react/useAskAgent.ts

@@ -0,0 +1,217 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { AgentAdapter, AskOutcome } from "../core/agent/adapter";
+import type { JsonSchema } from "../core/agent/types";
+
+/*
+ * One request, end to end: what a person typed goes to the adapter, the
+ * adapter's answer goes to the validator, and only a validated command runs.
+ *
+ * The order is the point. This hook never looks at the answer's contents to
+ * decide anything — it hands the envelope to `respond()` and reports what came
+ * back. A producer that returns nonsense, a stale schema, or an operation the
+ * component does not have is refused by the same five layers a form faces, and
+ * the person sees the validator's own words rather than a guess.
+ */
+
+/** The part of a component's agent this hook uses. */
+export interface AskableAgent {
+  contract(): unknown;
+  responseSchema(): JsonSchema;
+  /** Validates a whole envelope. Does not change anything. */
+  respond(response: unknown): AskExecution;
+  execute(intent: unknown, options?: { confirm?: boolean }): Promise<AskExecution>;
+}
+
+/** The statuses a component's validator and executor answer with. */
+export type AskExecution =
+  | {
+      status: "done";
+      commands: readonly { explain: { summary: string } }[];
+      warnings: readonly { code: string; message: string }[];
+    }
+  | {
+      status: "needs-confirmation";
+      commands: readonly { explain: { summary: string } }[];
+      confirm: { code: string; message: string };
+    }
+  | { status: "rejected"; reason: string; code: string; layer: string; suggestion?: string }
+  | { status: "clarify"; question: string; options?: readonly string[] }
+  | { status: "declined"; reason: string };
+
+const IDLE: AskOutcome = { phase: "idle", message: "" };
+
+export interface UseAskAgent {
+  ask(utterance: string): Promise<void>;
+  /** Run a `needs-confirmation` request the person has now agreed to. */
+  confirm(): Promise<void>;
+  reset(): void;
+  outcome: AskOutcome;
+  busy: boolean;
+  /** Set when the last answer stopped to ask; `confirm()` applies it. */
+  pending: unknown;
+}
+
+export function useAskAgent(
+  agent: AskableAgent | null,
+  adapter: AgentAdapter | null,
+): UseAskAgent {
+  const [outcome, setOutcome] = useState<AskOutcome>(IDLE);
+  const [busy, setBusy] = useState(false);
+  const [pending, setPending] = useState<unknown>(null);
+
+  // One request at a time: typing again abandons the one in flight rather
+  // than racing it to the grid.
+  const inFlight = useRef<AbortController | null>(null);
+  const alive = useRef(true);
+  useEffect(() => {
+    alive.current = true;
+    return () => {
+      alive.current = false;
+      inFlight.current?.abort();
+    };
+  }, []);
+
+  const report = useCallback((next: AskOutcome) => {
+    if (alive.current) setOutcome(next);
+  }, []);
+
+  /** Turn a validator answer into something to show, and run it when allowed. */
+  const settle = useCallback(
+    async (verdict: AskExecution, intents: unknown, raw: unknown) => {
+      if (verdict.status === "rejected") {
+        report({
+          phase: "refused",
+          message: verdict.reason,
+          code: verdict.code,
+          layer: verdict.layer,
+          suggestion: verdict.suggestion,
+          raw,
+        });
+        return;
+      }
+      if (verdict.status === "clarify") {
+        report({ phase: "clarify", message: verdict.question, raw });
+        return;
+      }
+      if (verdict.status === "declined") {
+        report({ phase: "refused", message: verdict.reason, raw });
+        return;
+      }
+      if (verdict.status === "needs-confirmation") {
+        setPending(intents);
+        report({
+          phase: "clarify",
+          message: verdict.confirm.message,
+          code: verdict.confirm.code,
+          raw,
+        });
+        return;
+      }
+
+      const run = await agent!.execute(intents);
+      if (run.status !== "done") {
+        report({
+          phase: "refused",
+          message: "reason" in run ? run.reason : run.status,
+          raw,
+        });
+        return;
+      }
+      report({
+        phase: "done",
+        message: run.commands.map((command) => command.explain.summary).join("; "),
+        warnings: run.warnings.map((warning) => `${warning.code}: ${warning.message}`),
+        raw,
+      });
+    },
+    [agent, report],
+  );
+
+  const ask = useCallback(
+    async (utterance: string) => {
+      const text = utterance.trim();
+      if (!agent || !adapter || text === "") return;
+
+      inFlight.current?.abort();
+      const controller = new AbortController();
+      inFlight.current = controller;
+
+      setPending(null);
+      setBusy(true);
+      report({ phase: "thinking", message: "" });
+
+      let raw: unknown;
+      try {
+        raw = await adapter({
+          utterance: text,
+          contract: agent.contract(),
+          responseSchema: agent.responseSchema(),
+          signal: controller.signal,
+        });
+      } catch (error) {
+        if (!controller.signal.aborted) {
+          // Reaching the producer failed. That is not the producer refusing,
+          // and saying so avoids blaming the person's wording.
+          report({
+            phase: "error",
+            message: error instanceof Error ? error.message : String(error),
+          });
+        }
+        if (alive.current && inFlight.current === controller) setBusy(false);
+        return;
+      }
+
+      if (controller.signal.aborted) return;
+
+      try {
+        const intents =
+          raw && typeof raw === "object" && "intents" in raw
+            ? (raw as { intents: unknown }).intents
+            : raw;
+        await settle(agent.respond(raw), intents, raw);
+      } catch (error) {
+        report({
+          phase: "error",
+          message: error instanceof Error ? error.message : String(error),
+          raw,
+        });
+      } finally {
+        if (alive.current && inFlight.current === controller) setBusy(false);
+      }
+    },
+    [adapter, agent, report, settle],
+  );
+
+  const confirm = useCallback(async () => {
+    if (!agent || pending === null) return;
+    setBusy(true);
+    try {
+      // Without the flag the executor stops and asks again, forever.
+      const run = await agent.execute(pending, { confirm: true });
+      report(
+        run.status === "done"
+          ? {
+              phase: "done",
+              message: run.commands.map((command) => command.explain.summary).join("; "),
+            }
+          : {
+              phase: "refused",
+              message: "reason" in run ? run.reason : run.status,
+            },
+      );
+      setPending(null);
+    } finally {
+      if (alive.current) setBusy(false);
+    }
+  }, [agent, pending, report]);
+
+  const reset = useCallback(() => {
+    inFlight.current?.abort();
+    setPending(null);
+    report(IDLE);
+  }, [report]);
+
+  return { ask, confirm, reset, outcome, busy, pending };
+}

package/source/components/shared/react/useControllableState.ts

@@ -0,0 +1,42 @@
+"use client";
+
+import { useCallback, useState } from "react";
+
+/**
+ * One value that may be controlled by the caller or owned by the component.
+ *
+ * Pass the `value` prop (or `undefined`) and the `defaultValue`. The returned
+ * setter writes internal state only while the component is uncontrolled, so a
+ * controlled caller stays the single source of truth and the component never
+ * renders a value its parent did not hand it.
+ *
+ * Change callbacks stay with the component: they differ too much between
+ * controls — some pass a DOM event, some skip a no-op change — and hiding them
+ * here would only move the difference somewhere less obvious.
+ *
+ * ```ts
+ * const [value, setValue] = useControllableState(valueProp, defaultValue ?? "");
+ *
+ * const handleChange = (event: ChangeEvent<HTMLInputElement>) => {
+ *   setValue(event.target.value);
+ *   onChange?.(event);
+ * };
+ * ```
+ */
+export function useControllableState<T>(
+  controlled: T | undefined,
+  defaultValue: T | (() => T),
+): readonly [T, (next: T) => void, boolean] {
+  const [internal, setInternal] = useState(defaultValue);
+  const isControlled = controlled !== undefined;
+  const value = isControlled ? controlled : internal;
+
+  const setValue = useCallback(
+    (next: T) => {
+      if (!isControlled) setInternal(next);
+    },
+    [isControlled],
+  );
+
+  return [value, setValue, isControlled] as const;
+}

package/source/components/shared/styles.css

@@ -0,0 +1,79 @@
+/*
+ * Shared defaults every component can rely on.
+ *
+ * Rules are unlayered: they beat a framework reset on specificity, and lose to
+ * anything you pass through `className`. With Tailwind v4, import this file
+ * after the framework and inside its components layer - see the README.
+ *
+ * Right now this file is scrollbars. Each component carries its own fallback
+ * values, so a component installed on its own still looks right; what lives
+ * here is the single place to theme them, and the `gbs-scroll` class for your
+ * own scrolling areas.
+ */
+
+/*
+ * Thin scrollbars, themed with the rest of the kit.
+ *
+ * `scrollbar-width` and `scrollbar-color` are the standard properties -
+ * Baseline since December 2024 - rather than the `::-webkit-scrollbar`
+ * pseudo-elements. Two reasons: the standard ones are what the other browsers
+ * implement, and mixing the two is a known way to get a scrollbar that is thin
+ * in one engine and default in another. `scrollbar-width` takes no length,
+ * only `auto | thin | none`, so `thin` is the whole control surface.
+ *
+ * Override any of these on `:root` to restyle every scrollbar at once, or on
+ * one element to restyle that one:
+ *
+ *   :root {
+ *     --gbs-scrollbar-width: auto;              bring the chunky ones back
+ *     --gbs-scrollbar-thumb: var(--gbs-accent); tint them with the brand
+ *   }
+ */
+:root {
+  /* `auto | thin | none`. `thin` is the default across the kit. */
+  --gbs-scrollbar-width: thin;
+
+  /*
+   * Derived from the accent so a themed kit themes its scrollbars too, and
+   * muted hard, because a scrollbar is furniture rather than content. The
+   * fallbacks are the same neutral the components use when untouched.
+   */
+  --gbs-scrollbar-thumb: color-mix(
+    in oklab,
+    var(--gbs-accent, light-dark(#2563eb, #60a5fa)) 28%,
+    light-dark(#a1a1aa, #52525b)
+  );
+  --gbs-scrollbar-thumb-hover: color-mix(
+    in oklab,
+    var(--gbs-accent, light-dark(#2563eb, #60a5fa)) 55%,
+    light-dark(#71717a, #71717a)
+  );
+  /* Transparent by default: a track that is a visible stripe reads as heavier
+     than the scrollbar it holds. */
+  --gbs-scrollbar-track: transparent;
+}
+
+/*
+ * Apply to your own scrolling areas to match the components:
+ *
+ *   <div class="gbs-scroll">…</div>
+ *
+ * `:where()` keeps the specificity at zero, so a single utility class of your
+ * own still wins without `!important`.
+ */
+:where(.gbs-scroll) {
+  scrollbar-width: var(--gbs-scrollbar-width, thin);
+  scrollbar-color: var(--gbs-scrollbar-thumb, light-dark(#c4c4ca, #3f3f46))
+    var(--gbs-scrollbar-track, transparent);
+}
+
+/*
+ * The hover brightening is a progressive enhancement: `scrollbar-color` does
+ * not transition, and a pointer-coarse device has no hover to speak of.
+ */
+@media (hover: hover) {
+  :where(.gbs-scroll):hover {
+    scrollbar-color: var(--gbs-scrollbar-thumb-hover, light-dark(#a1a1aa, #52525b))
+      var(--gbs-scrollbar-track, transparent);
+  }
+}

package/source/components/shared/version.json

@@ -0,0 +1,4 @@
+{
+  "name": "shared",
+  "version": "1.3.0"
+}

package/source/components/shared/version.ts

@@ -0,0 +1,6 @@
+/**
+ * Bumped whenever anything in `shared/` changes. The installer copies
+ * `version.json` next to it and compares the two, so a project is never left
+ * with components built against a newer `shared/` than the one on disk.
+ */
+export const version = "1.3.0";