@pgege/kaboo-react 0.1.0 → 0.2.0

package/AGENTS.md

@@ -25,11 +25,11 @@ yarn examples:typecheck    # type-check examples/ against built types
 - **Two barrels.**
   - `kaboo-react` (`src/index.ts`) — framework-agnostic contexts, hooks,
     components, utils, formatters, types.
-  - `@pgege/kaboo-react/copilotkit` (`src/copilotkit.ts`) — integrations coupled to
+  - `kaboo-react/copilotkit` (`src/copilotkit.ts`) — integrations coupled to
     CopilotKit. **Put any CopilotKit-dependent code here, never in the main
     barrel.**
 - **Stylesheet.** `src/styles.css` is copied to `dist/styles.css` by tsup and
-  exported as `@pgege/kaboo-react/styles.css`. Theming is via CSS variables only
+  exported as `kaboo-react/styles.css`. Theming is via CSS variables only
   (`--background`/`--foreground`/`--card`/`--muted`/`--border` + `--kaboo-*`
   overrides). Do not add a CSS-in-JS dependency.
 - **Peer deps.** `react`, `react-dom`, `@copilotkit/react-core`. Do not add
@@ -96,6 +96,6 @@ yarn examples:typecheck    # type-check examples/ against built types
 
 - [kaboo-workflows](https://github.com/gl-pgege/kaboo-workflows)
 - [kaboo-runtime](https://github.com/gl-pgege/kaboo-runtime)
-- [kaboo-workflows-demo](https://github.com/gl-pgege/kaboo-docs/tree/main/examples/kaboo-workflows-demo) — the
+- [kaboo-workflows-demo](https://github.com/gl-pgege/kaboo-workflows-demo) — the
   runnable, end-to-end reference that consumes this library.
 - [The kaboo stack](https://gl-pgege.github.io/kaboo-docs/) — umbrella landing.

package/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0]
+
+### Added
+
+- **References & attachments.** A pluggable `@`/`+` reference system for the chat
+  composer:
+  - `KabooReferenceInput` — a drop-in `<CopilotChat input={…}>` slot that keeps
+    CopilotKit's native input chrome but renders each reference as an interactive
+    inline chip, with a shared searchable popover for both `+` and `@`.
+  - `ReferencesProvider` / `ReferenceStateSync` / `useReferences` — register
+    providers, stage pending references, and sync object references onto
+    `agent.state`.
+  - `uploadProvider` (+ `isUploadProvider`, `buildAttachmentsConfig`,
+    `uploadFileToReference`, `UPLOAD_MARKER`) — the built-in file-attachment
+    provider, with URL or base64 upload.
+  - Serialization helpers (`mintReferenceId`, `referenceMarker`,
+    `attachmentToInputContent`, `objectToStateEntry`, `serializeReferences`,
+    `withReferenceState`, `buildUserContent`).
+  - Public types/constants: `ReferenceProvider`, `ReferenceItem`,
+    `PendingReference`, `ReferenceTransport`, `REFERENCE_METADATA_KEYS`,
+    `REFERENCES_STATE_KEY`.
+- `kaboo-react/copilotkit`: `KabooUserMessage` — renders sent references as
+  non-interactive chips (inline `@` mentions and a file/object chip row) in the
+  user bubble.
+- "References & providers" guide (`docs/references.md`) documenting the provider
+  contract, both transports, and searchable vs action-only providers.
+
+### Changed
+
+- `KabooMessageView` now wires `KabooUserMessage` so references sent with a
+  message render as chips instead of raw text.
+
 ## [0.1.0]
 
 Initial release.
@@ -20,10 +52,11 @@ Initial release.
   `MiniTable`, `GlassTabs`, `DrillDetailView`, `MarkdownContent`,
   `InterruptRenderer`), group helpers (`topLevelGroups`, `directChildren`) and
   formatters (`formatToolInput`, `formatToolResult`, `normalizeResult`).
-- `@pgege/kaboo-react/copilotkit` subpath: CopilotKit-coupled integrations
+- `kaboo-react/copilotkit` subpath: CopilotKit-coupled integrations
   (`KabooMessageView`, `KabooAssistantMessage`, `KabooInlineCards`,
   `KabooInterruptHandler`, `KabooAskUser`, `KabooToolRender`).
-- `@pgege/kaboo-react/styles.css` stylesheet with themeable `--kaboo-*` design tokens.
+- `kaboo-react/styles.css` stylesheet with themeable `--kaboo-*` design tokens.
 
-[Unreleased]: https://github.com/gl-pgege/kaboo-react/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/gl-pgege/kaboo-react/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/gl-pgege/kaboo-react/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/gl-pgege/kaboo-react/releases/tag/v0.1.0

package/README.md

@@ -23,6 +23,8 @@ endpoint to wire up: kaboo-react is a batteries-included CopilotKit plugin.
 - **Human-in-the-loop** — approval gates and forms, with N parallel interrupts
   resolved independently.
 - **Structured renderers** — plug custom UI for schema-shaped agent output.
+- **References & attachments** — files and your own objects (tables, dashboards,
+  …) as interactive inline chips, added from one shared **+** / **@** popover.
 - **Batteries included** — one `KabooProvider` renders `<CopilotKit>` and mounts
   every context and handler for you.
 - **Themeable** — styled with CSS variables and `--kaboo-*` tokens.
@@ -86,9 +88,65 @@ props via `copilotKitProps`.
 - **Theming via CSS variables.** Components read standard design-system tokens and
   accept `--kaboo-*` overrides.
 
+## References & attachments
+
+Let users attach things to a message. Everything is driven by **reference
+providers** registered on `<KabooProvider references={…}>` and rendered by the
+`KabooReferenceInput` slot. There are two transports:
+
+- **Attachment** — a file/blob. Register the built-in `uploadProvider({ onUpload })`;
+  choosing "Attach a file" (from **+** or **@**) opens the picker, uploads, and
+  drops a file chip inline. Files ride the message as parts stamped with
+  `kaboo_id` / `kaboo_kind` / `kaboo_name`.
+- **Object** — a pointer to one of *your* entities (`table`, `dashboard`, …).
+  Register a `ReferenceProvider`; selected objects sync into
+  `state.kaboo_references` for the backend to resolve, and appear inline as
+  `@name`.
+
+```tsx no-verify
+import {
+  KabooProvider,
+  KabooReferenceInput,
+  uploadProvider,
+  type ReferenceProvider,
+} from "@pgege/kaboo-react";
+
+// A custom object reference: three fields make it work.
+const tableProvider: ReferenceProvider = {
+  id: "table",
+  label: "Tables",
+  icon: <Table2 size={16} />,
+  search: (q) => TABLES.filter((t) => t.label.includes(q)),          // items under @
+  toReference: (item) => ({ transport: "object", kind: "table", id: item.id, name: item.label }),
+};
+
+<KabooProvider
+  runtimeUrl="/api/copilotkit"
+  agent={agent}
+  references={[uploadProvider({ accept: "image/*,.pdf", onUpload }), tableProvider]}
+>
+  <CopilotChat input={KabooReferenceInput} messageView={KabooMessageView} />
+</KabooProvider>;
+```
+
+`KabooReferenceInput` is a drop-in `<CopilotChat input={…}>` slot. It keeps
+CopilotKit's native input chrome (send button, disclaimer, theme) but swaps the
+plain textarea for a lightweight editor where every reference renders as an
+**interactive inline chip**: click a chip to swap it for another, or its `×` to
+remove it. The **+** button and the **@** key open the *same* searchable
+popover; it dismisses on outside-click / `Escape`. On submit the editor builds
+the multimodal message (files as attachment parts, objects on
+`state.kaboo_references`, cleared only after the run starts) and runs the agent.
+`onUpload` should return a fetchable URL (not base64) so the transport and
+persisted event log stay small. See [References & providers](./docs/references.md)
+for the full provider contract (both transports, searchable vs action-only,
+`toReference`), and kaboo-workflows' *Attachments & Multimodal* chapter for how
+references reach each agent.
+
 ## Guides
 
 - [Getting started](./docs/getting-started.md)
+- [References & providers](./docs/references.md)
 - [Theming](./docs/theming.md)
 - [Structured renderers](./docs/structured-renderers.md)
 - [Human-in-the-loop](./docs/hitl.md)

package/dist/{chunk-RXZWOBSI.js → chunk-4TDUEMK5.js}

@@ -1144,6 +1144,167 @@ function InlineCardRenderer({
   );
 }
 
+// src/references/types.ts
+var REFERENCE_METADATA_KEYS = {
+  /** Metadata key carrying the reference id. */
+  id: "kaboo_id",
+  /** Metadata key carrying the reference kind. */
+  kind: "kaboo_kind",
+  /** Metadata key carrying the reference display name. */
+  name: "kaboo_name"
+};
+var REFERENCES_STATE_KEY = "kaboo_references";
+
+// src/references/serialize.ts
+function mintReferenceId(kind) {
+  const rand = typeof crypto !== "undefined" && "randomUUID" in crypto ? crypto.randomUUID() : Math.random().toString(36).slice(2);
+  return `${kind}_${rand}`;
+}
+function referenceMarker(ref) {
+  return `[${ref.kind}:${ref.id}]`;
+}
+function modalityFor(mimeType) {
+  if (mimeType.startsWith("image/")) return "image";
+  if (mimeType.startsWith("audio/")) return "audio";
+  if (mimeType.startsWith("video/")) return "video";
+  return "document";
+}
+function attachmentToInputContent(ref) {
+  const source = "url" in ref.source ? { type: "url", value: ref.source.url, mimeType: ref.mimeType } : { type: "data", value: ref.source.data, mimeType: ref.mimeType };
+  return {
+    type: modalityFor(ref.mimeType),
+    source,
+    metadata: {
+      [REFERENCE_METADATA_KEYS.id]: ref.id,
+      [REFERENCE_METADATA_KEYS.kind]: ref.kind,
+      [REFERENCE_METADATA_KEYS.name]: ref.name,
+      filename: ref.name
+    }
+  };
+}
+function objectToStateEntry(ref) {
+  return { kind: ref.kind, id: ref.id, name: ref.name, meta: ref.meta };
+}
+function serializeReferences(refs) {
+  const attachmentParts = [];
+  const objectReferences = [];
+  for (const ref of refs) {
+    if (ref.transport === "attachment") {
+      attachmentParts.push(attachmentToInputContent(ref));
+    } else {
+      objectReferences.push(objectToStateEntry(ref));
+    }
+  }
+  return { attachmentParts, objectReferences };
+}
+function withReferenceState(state, objectReferences) {
+  const next = { ...state ?? {} };
+  if (objectReferences.length > 0) {
+    next[REFERENCES_STATE_KEY] = objectReferences;
+  } else {
+    delete next[REFERENCES_STATE_KEY];
+  }
+  return next;
+}
+function buildUserContent(text, attachmentParts) {
+  const parts = [];
+  if (text.length > 0) parts.push({ type: "text", text });
+  parts.push(...attachmentParts);
+  return parts;
+}
+
+// src/references/ReferencesProvider.tsx
+import {
+  createContext as createContext4,
+  useCallback as useCallback3,
+  useContext as useContext5,
+  useEffect as useEffect4,
+  useMemo,
+  useState as useState7
+} from "react";
+import { useAgent as useAgent2 } from "@copilotkit/react-core/v2";
+import { jsx as jsx15, jsxs as jsxs9 } from "react/jsx-runtime";
+var ReferencesContext = createContext4({
+  providers: [],
+  pending: [],
+  addReference: () => {
+  },
+  removeReference: () => {
+  },
+  clearReferences: () => {
+  },
+  messageReferences: {},
+  recordMessageReferences: () => {
+  }
+});
+function ReferencesProvider({
+  providers = [],
+  syncObjectStateTo = false,
+  children
+}) {
+  const [pending, setPending] = useState7([]);
+  const [messageReferences, setMessageReferences] = useState7({});
+  const addReference = useCallback3((ref) => {
+    setPending(
+      (prev) => prev.some((r) => r.id === ref.id) ? prev : [...prev, ref]
+    );
+  }, []);
+  const removeReference = useCallback3((id) => {
+    setPending((prev) => prev.filter((r) => r.id !== id));
+  }, []);
+  const clearReferences = useCallback3(() => setPending([]), []);
+  const recordMessageReferences = useCallback3(
+    (messageId, refs) => {
+      if (refs.length === 0) return;
+      setMessageReferences((prev) => ({ ...prev, [messageId]: refs }));
+    },
+    []
+  );
+  const value = useMemo(
+    () => ({
+      providers,
+      pending,
+      addReference,
+      removeReference,
+      clearReferences,
+      messageReferences,
+      recordMessageReferences
+    }),
+    [
+      providers,
+      pending,
+      addReference,
+      removeReference,
+      clearReferences,
+      messageReferences,
+      recordMessageReferences
+    ]
+  );
+  return /* @__PURE__ */ jsxs9(ReferencesContext.Provider, { value, children: [
+    syncObjectStateTo !== false && /* @__PURE__ */ jsx15(ReferenceStateSync, { agentId: syncObjectStateTo, pending }),
+    children
+  ] });
+}
+function ReferenceStateSync({
+  agentId,
+  pending
+}) {
+  const { agent } = useAgent2(agentId ? { agentId } : void 0);
+  const objectRefs = useMemo(
+    () => pending.filter((r) => r.transport === "object").map(objectToStateEntry),
+    [pending]
+  );
+  const key = JSON.stringify(objectRefs);
+  useEffect4(() => {
+    if (!agent || typeof agent.setState !== "function") return;
+    agent.setState(withReferenceState(agent.state, objectRefs));
+  }, [agent, key]);
+  return null;
+}
+function useReferences() {
+  return useContext5(ReferencesContext);
+}
+
 export {
   StructuredRenderersContext,
   KabooActivityProvider,
@@ -1172,6 +1333,18 @@ export {
   useDrill,
   AgentCard,
   KabooToolRender,
-  KabooInlineCards
+  KabooInlineCards,
+  REFERENCE_METADATA_KEYS,
+  REFERENCES_STATE_KEY,
+  mintReferenceId,
+  referenceMarker,
+  attachmentToInputContent,
+  objectToStateEntry,
+  serializeReferences,
+  withReferenceState,
+  buildUserContent,
+  ReferencesProvider,
+  ReferenceStateSync,
+  useReferences
 };
-//# sourceMappingURL=chunk-RXZWOBSI.js.map
+//# sourceMappingURL=chunk-4TDUEMK5.js.map