gbs-add-block 2.1.0 → 2.3.0

package/source/beta-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/beta-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/beta-components/shared/version.json

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

package/source/beta-components/shared/version.ts

@@ -1,6 +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.1.0";
+/**
+ * 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";

package/source/beta-components/skeleton/passport.json

@@ -0,0 +1,251 @@
+{
+  "passportVersion": "1.0.0",
+  "identity": {
+    "component": "Skeleton",
+    "folder": "skeleton",
+    "exports": [
+      "Empty",
+      "Skeleton"
+    ]
+  },
+  "source": {
+    "libraryVersion": "2.3.0",
+    "files": [
+      "core/index.ts",
+      "core/lines.ts",
+      "core/types.ts",
+      "index.ts",
+      "react/Empty.tsx",
+      "react/Skeleton.tsx",
+      "react/props.ts"
+    ],
+    "sourceHash": "sha256:f94d1d6763336652599c4423a1ddfc11d8b67e31670e0b019003eed8c71eec2b"
+  },
+  "props": [
+    {
+      "name": "actions",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "The way out — usually one button, occasionally two.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "animation",
+      "type": "enum",
+      "values": [
+        "none",
+        "pulse",
+        "wave"
+      ],
+      "typeText": "SkeletonAnimation | undefined",
+      "required": false,
+      "default": "pulse",
+      "origin": "derived",
+      "description": "Default `pulse`. Reduced-motion settings turn any of them off.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "classNames",
+      "type": "other",
+      "typeText": "Partial<Record<SkeletonSlot, string>> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "description",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "Why it is empty, and what to do about it.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "height",
+      "type": "other",
+      "typeText": "string | number | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "icon",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "Decorative: an illustration or icon above the title.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Announced while the placeholder is up. Leave it out inside a region that\nalready says it is busy — two announcements are worse than one.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "lastLineWidth",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "default": 60,
+      "origin": "derived",
+      "description": "Width of the last line as a percentage, for `text`. Default 60.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "lines",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "default": 1,
+      "origin": "derived",
+      "description": "Number of bars, for `text`. Default 1.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "radius",
+      "type": "other",
+      "typeText": "string | number | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Corner radius for `rect`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "ref",
+      "type": "other",
+      "typeText": "Ref<HTMLDivElement> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "size",
+      "type": "enum",
+      "values": [
+        "lg",
+        "md",
+        "sm"
+      ],
+      "typeText": "'sm' | 'md' | 'lg' | undefined",
+      "required": false,
+      "default": "md",
+      "origin": "derived",
+      "description": "Default `md`. `sm` suits an empty panel inside a page.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "style",
+      "type": "other",
+      "typeText": "CSSProperties | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "title",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": true,
+      "origin": "derived",
+      "description": "What is missing, in a few words.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "variant",
+      "type": "enum",
+      "values": [
+        "circle",
+        "rect",
+        "text"
+      ],
+      "typeText": "SkeletonVariant | undefined",
+      "required": false,
+      "default": "text",
+      "origin": "derived",
+      "description": "Default `text`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "width",
+      "type": "other",
+      "typeText": "string | number | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "A number is pixels; a string is used as given.",
+      "descriptionOrigin": "jsdoc"
+    }
+  ],
+  "events": [],
+  "slots": [
+    "root",
+    "line",
+    "icon",
+    "title",
+    "description",
+    "actions"
+  ],
+  "states": [
+    {
+      "attr": "data-animation",
+      "values": [
+        "animation",
+        "pulse",
+        "wave"
+      ]
+    },
+    {
+      "attr": "data-lines"
+    },
+    {
+      "attr": "data-size",
+      "values": [
+        "lg",
+        "sm"
+      ]
+    },
+    {
+      "attr": "data-theme",
+      "values": [
+        "dark",
+        "light"
+      ]
+    },
+    {
+      "attr": "data-variant",
+      "values": [
+        "circle",
+        "rect",
+        "text",
+        "variant"
+      ]
+    }
+  ],
+  "accessibility": {
+    "supplied": [],
+    "required": []
+  },
+  "composition": {},
+  "operations": {},
+  "intentDomains": [],
+  "safeMutations": {},
+  "examples": [],
+  "coverage": {
+    "propsTotal": 17,
+    "propsDescribed": 12,
+    "describedPct": 71,
+    "authoredSections": [
+      "accessibility"
+    ]
+  }
+}