@logicplanes/kaeso-ui 0.4.1 → 0.4.3

package/NOTICE.md

@@ -1,5 +1,5 @@
 # Notices
 
-Fonts: Inter (SIL Open Font License 1.1) and Geist Mono (SIL Open Font License 1.1), self-hosted as unmodified subsets of their Fontsource builds and shipped in `dist/fonts/` with `LICENSE-Inter.txt` and `LICENSE-GeistMono.txt`. Icons: Hugeicons free, Stroke Rounded (MIT). Provider marks: the trademarks of the providers they name, shown only to identify each provider, from each provider's own vector in one colour. The repository's `NOTICE.md` lists the source of each.
+Fonts: Inter (SIL Open Font License 1.1) and Geist Mono (SIL Open Font License 1.1), self-hosted as unmodified subsets of their Fontsource builds and shipped in `dist/fonts/` with `LICENSE-Inter.txt` and `LICENSE-GeistMono.txt`. Icons: Hugeicons free, Stroke Rounded (MIT). Provider marks: the trademarks of the providers they name, shown only to identify each provider, from each provider's own vector in one colour. Client marks: the trademarks of the agent clients they name, from Simple Icons (CC0 1.0), in one colour. The repository's `NOTICE.md` lists the source of each.
 
 The runtime dependencies are listed in `package.json`; each is MIT, ISC, BSD-2-Clause, BSD-3-Clause, Apache-2.0 or 0BSD licensed.

package/ai/component-guides.md

@@ -1,6 +1,85 @@
 # @logicplanes/kaeso-ui component guides
 
-Version 0.4.1. Generated from the showcase's demo modules (apps/showcase/src/demos); do not edit. For each component: what it is for, its import, keyboard, accessibility, do and don't, and every example's code. Props and variants: `component-registry.md`.
+Version 0.4.3. Generated from the showcase's demo modules (apps/showcase/src/demos); do not edit. For each component: what it is for, its import, keyboard, accessibility, do and don't, and every example's code. Props and variants: `component-registry.md`.
+
+## AgentAttribution
+
+A person's avatar with the agent that acted for them as a badge on its corner, for audit rows and activity.
+
+`import { AgentAttribution } from "@logicplanes/kaeso-ui";`
+
+### Accessibility
+
+- One role=img named after both, such as “Ada Okafor via Release helper (Claude)”, in the page's language.
+
+### Examples
+
+#### Activity
+
+```tsx
+<div className="flex flex-col gap-16">
+  {activity.map((a) => (
+    <div key={a.person} className="flex items-center gap-12">
+      <AgentAttribution name={a.person} agent={a.agent} />
+      <Text>{a.action}</Text>
+    </div>
+  ))}
+</div>
+```
+
+#### Sizes
+
+```tsx
+<div className="flex flex-wrap items-end gap-16">
+  {([20, 24, 28, 32, 40] as const).map((s) => (
+    <AgentAttribution key={s} name="Ada Okafor" agent={{ name: "Release helper", model: "claude" }} size={s} />
+  ))}
+</div>
+```
+
+## AgentAvatar
+
+An agent acting for a person: one bot face on an ink square, the same for every agent.
+
+`import { AgentAvatar, useModelName } from "@logicplanes/kaeso-ui";`
+
+### Accessibility
+
+- role=img named after the agent; pass decorative when the name is written next to it.
+- Every agent looks the same; write its model family with useModelName where it matters.
+
+### Examples
+
+#### Agents
+
+```tsx
+function Agents() {
+  const modelName = useModelName();
+  return (
+    <div className="flex flex-col gap-12">
+      {agents.map((a) => (
+        <div key={a.model} className="flex items-center gap-8">
+          <AgentAvatar name={a.name} decorative />
+          <Text>{a.name}</Text>
+          <Text variant="small" tone="secondary">
+            {modelName(a.model)}
+          </Text>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+#### Sizes
+
+```tsx
+<div className="flex flex-wrap items-end gap-12">
+  {([20, 24, 28, 32, 40] as const).map((s) => (
+    <AgentAvatar key={s} name="Release helper" size={s} />
+  ))}
+</div>
+```
 
 ## AlertDialog
 
@@ -595,6 +674,28 @@ An 18px box: raised and ringed, ink when checked, with a check that draws itself
 </CheckboxGroup>
 ```
 
+## ClientButton
+
+An agent client's mark on a raised tile, such as Claude, Cursor or GitHub Copilot, that opens how to connect it.
+
+`import { ClientButton } from "@logicplanes/kaeso-ui";`
+
+### Accessibility
+
+- A button named by `aria-label`, which is also its tooltip; the mark is decorative.
+
+### Examples
+
+#### Clients
+
+```tsx
+<div className="flex gap-8">
+  <ClientButton client="claude" aria-label="Add to Claude Code" />
+  <ClientButton client="cursor" aria-label="Add to Cursor" />
+  <ClientButton client="github-copilot" aria-label="Add to GitHub Copilot" />
+</div>
+```
+
 ## ClipboardText
 
 Copy a value: a read-only pill field, a copy circle, or inline text that copies itself.
@@ -622,7 +723,7 @@ A read-only pill with the value in mono and a copy circle inside.
 
 ```tsx
 <div className="w-400">
-  <ClipboardText value="https://gateway.northwind.example/v1" label="Copy base URL" />
+  <ClipboardText value="https://kaeso.example.com/v1" label="Copy base URL" />
 </div>
 ```
 
@@ -679,7 +780,7 @@ Highlighted code on a well in Kaeso's monochrome theme: copy on hover, tabs, lin
 
 ```tsx
 <div className="w-full">
-  <CodeBlock tabs={sdkSnippets({ baseUrl: "https://gateway.northwind.example" })} />
+  <CodeBlock tabs={sdkSnippets({ baseUrl: "https://kaeso.example.com" })} />
 </div>
 ```
 
@@ -1456,7 +1557,7 @@ function WithResult() {
                 title: "Key created",
                 description: "Copy the key now: it's shown once, and Kaeso keeps only a hash of it.",
                 size: "lg",
-                content: <SecretReveal secret={SECRET} name={name.trim()} baseUrl="https://gateway.northwind.example" model="gpt-5-mini" />,
+                content: <SecretReveal secret={SECRET} name={name.trim()} baseUrl="https://kaeso.example.com" model="gpt-5-mini" />,
                 footer: <Button onClick={close}>Done</Button>,
               }
             : undefined
@@ -1735,6 +1836,27 @@ A label, a control and its help, wired together; an error shows under the contro
 </div>
 ```
 
+## Figure
+
+A diagram or image set apart from the text: centred on a well, with a caption, scrolling sideways only when it can't shrink to fit.
+
+`import { Figure } from "@logicplanes/kaeso-ui";`
+
+### Accessibility
+
+- The caption names the figure; the label names the region that scrolls, so keyboard users know what they scroll.
+- Put a diagram's longer description in a visually hidden element and point the image's aria-describedby at it.
+
+### Examples
+
+#### A diagram with its caption
+
+```tsx
+<Figure label="Diagram: route of a request" caption="Route of a request" className="w-full">
+  <ThemeImage light="/demos/route.light.svg" dark="/demos/route.dark.svg" alt="Route of a request: app, Kaeso, provider" width={364} height={49} />
+</Figure>
+```
+
 ## FilterChip
 
 A filter as one pill, “Status is 2xx”: property, operator and value, each opening a menu.
@@ -1903,6 +2025,29 @@ A semicircle for “budget used”; thresholds as ticks.
 <Gauge aria-label="Monthly budget used" value={0.64} label="of $500.00 budget" valueLabel="$320.00" />
 ```
 
+## GrantSummary
+
+What an agent may do in a few short lines, each after a check mark, as on its consent page.
+
+`import { GrantSummary } from "@logicplanes/kaeso-ui";`
+
+### Accessibility
+
+- A list named by `aria-label`; the check marks are decorative.
+
+### Examples
+
+#### An agent's rights
+
+```tsx
+<GrantSummary
+  className="w-360"
+  aria-label="What it can do"
+  items={["Manages projects, keys, and models in Northwind", "Reads the rest of Northwind", "Also in organizations you join later"]}
+  footer="For 90 days; revoke it any time in your account settings."
+/>
+```
+
 ## Grid
 
 Grid, Stack and Inline: layout with gaps from the spacing scale only.
@@ -2118,7 +2263,7 @@ An invalid value gets the danger ring; what is wrong goes in a toast.
 ```tsx
 <div className="flex w-360 flex-col gap-12">
   <Input aria-label="Email" leadingIcon={icons.mail} placeholder="ada@northwind.example" />
-  <Input aria-label="Gateway URL" prefix="https://" placeholder="gateway.northwind.example" />
+  <Input aria-label="Gateway URL" prefix="https://" placeholder="kaeso.example.com" />
   <Input aria-label="Rate limit" suffix="/ min" defaultValue="600" align="end" />
 </div>
 ```
@@ -2150,7 +2295,7 @@ Addons inside the pill: text, icons, a ghost circle or a key cap, sharing one fo
 <div className="flex w-400 flex-col gap-12">
   <InputGroup>
     <InputGroup.Addon>https://</InputGroup.Addon>
-    <InputGroup.Input aria-label="Host" placeholder="gateway.northwind.example" />
+    <InputGroup.Input aria-label="Host" placeholder="kaeso.example.com" />
     <InputGroup.Addon>/v1</InputGroup.Addon>
   </InputGroup>
   <InputGroup trailingButton>
@@ -2394,11 +2539,13 @@ function Wizard() {
   const [view, setView] = useState<"pick" | "review" | "custom">("pick");
   const [model, setModel] = useState("");
   const [custom, setCustom] = useState("");
+  const [query, setQuery] = useState("");
   const m = models.find((x) => x.model === model);
   const start = () => {
     setView("pick");
     setModel("");
     setCustom("");
+    setQuery("");
     setOpen(true);
   };
   const close = () => setOpen(false);
@@ -2410,29 +2557,31 @@ function Wizard() {
   const pick = {
     title: "Add model",
     description: "Pick a model from the models.dev catalogue.",
+    toolbar: <SearchInput aria-label="Search models" placeholder="Search" value={query} onChange={(e) => setQuery(e.target.value)} data-autofocus />,
     content: (
       <div className="flex flex-col gap-12">
         <List
           aria-label="Models on models.dev"
           density="compact"
-          items={models.map((x) => ({
-            id: x.model,
-            textValue: x.model,
-            title: <ModelLabel provider={x.provider} providerName={providerNames[x.provider]} model={x.model} name={x.name} />,
-          }))}
+          items={models
+            .filter((x) => x.model.includes(query.trim().toLowerCase()))
+            .map((x) => ({
+              id: x.model,
+              textValue: x.model,
+              title: <ModelLabel provider={x.provider} providerName={providerNames[x.provider]} model={x.model} name={x.name} />,
+            }))}
           onOpen={(item) => {
             setModel(item.id);
             setView("review");
           }}
         />
-        <Text variant="small" tone="secondary">
-          Not on models.dev?{" "}
-          <Button variant="link" size="sm" onClick={() => setView("custom")}>
-            Add a custom model
-          </Button>
-        </Text>
       </div>
     ),
+    footerStart: (
+      <Button variant="ghost" leadingIcon={icons.add} onClick={() => setView("custom")}>
+        Add a custom model
+      </Button>
+    ),
   };
   const second = {
     review: {
@@ -3388,9 +3537,23 @@ Choosing a provider from any number of them: connected ones first with their key
 ### Accessibility
 
 - A search field over a listbox, with Connected and Other providers as groups; each option reads the provider's name and hint.
+- As tiles, a radio group: arrow keys move the choice, and a press or click on a tile calls onChoose, so a dialog step can continue at once.
 
 ### Examples
 
+#### Tiles in a dialog's first step
+
+```tsx
+function Grid() {
+  const [provider, setProvider] = useState<string | null>(null);
+  return (
+    <div className="w-512 max-w-full">
+      <ProviderPicker appearance="grid" aria-label="Provider" providers={providers} value={provider} onValueChange={setProvider} />
+    </div>
+  );
+}
+```
+
 #### In a dialog step
 
 ```tsx
@@ -3903,7 +4066,7 @@ The one-time secret: calm, centered, certain. Copy it, store it, see how to use
 
 ```tsx
 <div className="w-560">
-  <SecretReveal secret={SECRET} name="checkout-web" baseUrl="https://gateway.northwind.example" model="gpt-5-mini" />
+  <SecretReveal secret={SECRET} name="checkout-web" baseUrl="https://kaeso.example.com" model="gpt-5-mini" />
 </div>
 ```
 
@@ -3911,7 +4074,7 @@ The one-time secret: calm, centered, certain. Copy it, store it, see how to use
 
 ```tsx
 <div className="w-640">
-  <EnvironmentSnippet baseUrl="https://gateway.northwind.example" />
+  <EnvironmentSnippet baseUrl="https://kaeso.example.com" />
 </div>
 ```
 
@@ -3922,12 +4085,12 @@ The one-time secret: calm, centered, certain. Copy it, store it, see how to use
   <SecretReveal
     secret={SECRET}
     name="terraform"
-    baseUrl="https://gateway.northwind.example"
+    baseUrl="https://kaeso.example.com"
     snippets={[
       {
         label: "curl",
         lang: "bash",
-        code: `curl https://gateway.northwind.example/platform/v1/orgs/org_01/projects \\\n  -H "Authorization: Bearer ${SECRET}"`,
+        code: `curl https://kaeso.example.com/platform/v1/orgs/org_01/projects \\\n  -H "Authorization: Bearer ${SECRET}"`,
       },
     ]}
   />
@@ -4524,6 +4687,59 @@ An 8px semantic dot with its word. Status is never color alone.
 </div>
 ```
 
+## SwapText
+
+Text that changes with state in a place sized for its widest version, so nothing around it moves.
+
+`import { SwapText } from "@logicplanes/kaeso-ui";`
+
+### Accessibility
+
+- Only the current text is read; the reserved versions are hidden from screen readers.
+- Buttons take reserveLabels, which wraps their label in SwapText; reach for SwapText itself for text outside a button.
+
+### Examples
+
+#### Basic
+
+```tsx
+function Basic() {
+  const [active, setActive] = useState(true);
+  return (
+    <div className="flex items-center gap-12 text-body">
+      <Switch size="sm" aria-label="Key active" checked={active} onCheckedChange={setActive} />
+      <span className="font-medium text-fg">
+        <SwapText reserve={["Active", "Paused"]} align="start">
+          {active ? "Active" : "Paused"}
+        </SwapText>
+      </span>
+      <span className="text-fg-secondary">production</span>
+    </div>
+  );
+}
+```
+
+#### Aligned at the start
+
+In a column, start-aligned labels keep the text after them on one line.
+
+```tsx
+<div className="flex flex-col gap-8 text-body">
+  {[
+    { status: "Streaming", model: "gpt-5-mini" },
+    { status: "Done", model: "claude-sonnet-4-5" },
+    { status: "Failed", model: "gpt-4.1-nano" },
+  ].map((row) => (
+    <div key={row.model} className="flex items-center gap-12">
+      <SwapText reserve={STATUSES} align="start" className="font-medium text-fg">
+        {row.status}
+      </SwapText>
+      <span className="mono text-fg-secondary">{row.model}</span>
+    </div>
+  ))}
+</div>
+```
+
 ## Switch
 
 A pill track and a round thumb that travels in 180ms.
@@ -4655,6 +4871,35 @@ Long text and links wrap like prose; the row grows and keeps its padding, and on
 </Table>
 ```
 
+#### Compact
+
+A reference table of five or more columns puts 8px between them, so it fits the column without scrolling.
+
+```tsx
+<Table density="compact" className="w-640">
+  <Table.Head>
+    <Table.Row>
+      <Table.HeaderCell>Variable</Table.HeaderCell>
+      <Table.HeaderCell>TOML key</Table.HeaderCell>
+      <Table.HeaderCell>Type</Table.HeaderCell>
+      <Table.HeaderCell>Default</Table.HeaderCell>
+      <Table.HeaderCell>What it does</Table.HeaderCell>
+    </Table.Row>
+  </Table.Head>
+  <Table.Body>
+    {settings.map((s) => (
+      <Table.Row key={s.variable}>
+        <Table.Cell className="mono text-small">{s.variable}</Table.Cell>
+        <Table.Cell className="mono text-small">{s.key}</Table.Cell>
+        <Table.Cell>{s.type}</Table.Cell>
+        <Table.Cell className="mono text-small whitespace-nowrap">{s.default}</Table.Cell>
+        <Table.Cell>{s.does}</Table.Cell>
+      </Table.Row>
+    ))}
+  </Table.Body>
+</Table>
+```
+
 ## TableOfContents
 
 “On this page”: the heading in view in text color with a 2px ink bar.
@@ -4912,6 +5157,44 @@ An image drawn twice, once for each theme, such as a diagram: it follows the the
 <ThemeImage light="/demos/route.light.svg" dark="/demos/route.dark.svg" alt="Route of a request: app, Kaeso, provider" width={364} height={49} />
 ```
 
+## ThemeMenu
+
+A circle that opens system, light or dark, stored as `kaeso:theme`; its icon shows the theme in use.
+
+`import { ThemeMenu } from "@logicplanes/kaeso-ui";`
+
+### Keyboard
+
+| Key | Action |
+|---|---|
+| Enter Space | Opens the menu |
+| Up Down | Moves between the choices |
+| Enter | Chooses and closes |
+| Escape | Closes and returns focus |
+
+### Accessibility
+
+- Named Theme in the provider's language; the menu marks the current choice as checked.
+- Reads and sets the choice of the nearest ThemeProvider; every provider on the page follows it.
+
+### Examples
+
+#### Basic
+
+```tsx
+<ThemeProvider>
+  <ThemeMenu />
+</ThemeProvider>
+```
+
+#### Raised
+
+```tsx
+<ThemeProvider>
+  <ThemeMenu variant="secondary" size="md" />
+</ThemeProvider>
+```
+
 ## ThemeSelect
 
 A select for system, light or dark, stored as `kaeso:theme`, with its label in the provider's language.
@@ -4972,6 +5255,35 @@ A select for system, light or dark, stored as `kaeso:theme`, with its label in t
 </ThemeProvider>
 ```
 
+## Thumbnail
+
+A square image someone sent, such as a photo in a request's conversation, cropped to fill a well.
+
+`import { Thumbnail } from "@logicplanes/kaeso-ui";`
+
+### Accessibility
+
+- Alt is required: say what the image shows, or the sender's own description when the request carried one.
+- When the image can't load, its text alternative takes its place, so nothing is lost.
+
+### Examples
+
+#### An image in a message
+
+```tsx
+<Thumbnail src="/demos/receipt.svg" alt="A receipt from Northwind Labs" />
+```
+
+#### Sizes
+
+```tsx
+<div className="flex flex-wrap items-end gap-12">
+  <Thumbnail src="/demos/receipt.svg" alt="A receipt, 64px" size="sm" />
+  <Thumbnail src="/demos/receipt.svg" alt="A receipt, 120px" />
+  <Thumbnail src="/demos/receipt.svg" alt="A receipt, 160px" size="lg" />
+</div>
+```
+
 ## Timeline
 
 Events down a 1px line: the audit log.