gentiq 0.8.1 → 0.8.3

package/README.md

@@ -105,6 +105,105 @@ const components: GentiqComponents = {
 };
 ```
 
+### References for Text, Tools, and Custom Cards
+
+Gentiq includes a built-in reference UX similar to modern AI chat apps. Users can select text in previous messages, click the reference action, and Gentiq will add a compact quote chip to the composer. When the message is sent, the referenced context is sent to the backend/model and shown as a clickable badge in the chat.
+
+For normal text messages, this works automatically. For custom cards, use `Referenceable` or `useChatReferences` so Gentiq knows exactly what should be referenced and how it should appear to the user.
+
+#### Reference a custom card
+
+Use `Referenceable` when your component has a clear card-like boundary. Gentiq will add a hover reference action, register the source for click-to-highlight, and send the structured reference with the next user message.
+
+```tsx
+import { Referenceable } from 'gentiq';
+
+function CarCard({ car }) {
+  return (
+    <Referenceable
+      reference={{
+        kind: 'car',
+        sourceId: `car-${car.id}`,
+        label: 'Car',
+        excerpt: `${car.year} ${car.make} ${car.model} · ${car.price}`,
+        data: {
+          carId: car.id,
+          make: car.make,
+          model: car.model,
+          year: car.year,
+          price: car.price,
+        },
+      }}
+    >
+      <div className="car-card">
+        <CarImageCarousel images={car.images} />
+        <h3>{car.year} {car.make} {car.model}</h3>
+        <p>{car.price}</p>
+      </div>
+    </Referenceable>
+  );
+}
+```
+
+`excerpt` is the human-readable text shown in the composer chip and reference badge. `data` is optional structured context, useful for IDs or machine-readable values like `{ carId }`.
+
+#### Use your own reference button
+
+If you do not want the built-in hover action, call `addReference` yourself. Keep the `sourceId` on the element you want highlighted later.
+
+```tsx
+import { useChatReferences } from 'gentiq';
+
+function CarCard({ car }) {
+  const { addReference } = useChatReferences();
+
+  const reference = {
+    kind: 'car',
+    sourceId: `car-${car.id}`,
+    label: 'Car',
+    excerpt: `${car.year} ${car.make} ${car.model} · ${car.price}`,
+    data: { carId: car.id },
+  };
+
+  return (
+    <div data-gentiq-reference-source-id={reference.sourceId}>
+      <CarImageCarousel images={car.images} />
+      <h3>{car.year} {car.make} {car.model}</h3>
+
+      <button type="button" onClick={() => addReference(reference)}>
+        Reference this car
+      </button>
+    </div>
+  );
+}
+```
+
+#### Customize tool/card reference text
+
+For tool-rendered cards, use `referenceAdapters` to control what appears in the composer and sent reference context. This avoids showing raw JSON to users.
+
+```tsx
+const components: GentiqComponents = {
+  toolComponents: {
+    get_weather: WeatherCard,
+  },
+  referenceAdapters: {
+    get_weather: ({ part }) => ({
+      label: 'Weather',
+      excerpt: `Weather: ${part.output.city}: ${part.output.condition}`,
+      data: {
+        city: part.output.city,
+        condition: part.output.condition,
+      },
+    }),
+  },
+};
+
+<ChatUI components={components} />
+```
+
+For markdown patterns like `[CarCard](car_id)`, render your `CarCard` from the markdown override, fetch the car data as usual, and wrap the rendered card with `Referenceable` as shown above.
+
 ---
 
 ## ⚓ Headless Mode