@logicplanes/kaeso-ui 0.2.1 → 0.3.0

package/AGENTS.md

@@ -29,6 +29,7 @@ The design system behind the components, in `node_modules/@logicplanes/kaeso-ui/
 | `foundations/typography.md`    | Setting text, numbers, ids or code                |
 | `foundations/shape.md`         | Choosing a radius, nesting surfaces               |
 | `foundations/elevation.md`     | Drawing a line, a ring or a raised surface        |
+| `foundations/layout.md`        | Placing anything on a page: one gutter, one edge  |
 | `foundations/motion.md`        | Animating anything, showing loading               |
 | `foundations/icons.md`         | Placing an icon                                   |
 | `foundations/writing.md`       | Writing any label, message, empty state or error  |
@@ -83,6 +84,7 @@ export function Providers({ children }: { children: React.ReactNode }) {
 9. **Use the icon vocabulary**: `icons.key`, `icons.model`, never an icon picked by look.
 10. **Copy follows the voice**: sentence case, a verb first on buttons, no exclamation points or emoji, errors that say what to do next.
 11. **Leave room.** Let the panel breathe: the components bring their own spacing, so don't pack screens with extra wrappers, borders or headings. Fewer elements, each one clear.
+12. **One edge per page.** Every box, from a button to a row's hover fill, starts on the 24px gutter, and the text inside a box 12px further in. Never pull a component into the gutter with a negative margin.
 
 ## Which component for which job
 

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).
+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.
 
 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,6 @@
 # @logicplanes/kaeso-ui component guides
 
-Version 0.2.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.3.0. 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`.
 
 ## AlertDialog
 
@@ -795,6 +795,89 @@ function Create() {
 }
 ```
 
+## CommandList
+
+A search field over a long list that stays fast with thousands of rows, grouped under sticky captions.
+
+`import { CommandList } from "@logicplanes/kaeso-ui";`
+
+### Keyboard
+
+| Key | Action |
+|---|---|
+| Up Down | Moves through rows, skipping disabled ones |
+| Home End | Goes to the first or last row |
+| PageUp PageDown | Moves a page at a time |
+| Enter | Chooses the active row |
+| Escape | Clears the search, then closes |
+
+### Accessibility
+
+- The search field is a combobox that points at the active row; the list is a listbox with one group per caption.
+- Each row says its position in the whole list, so a screen reader counts every row, not just those drawn.
+
+### Examples
+
+#### In a dialog step
+
+```tsx
+function Inline() {
+  const [value, setValue] = useState("gpt-5");
+  return (
+    <div className="w-400 max-w-full">
+      <CommandList height="inline" aria-label="Models" groups={groups} value={value} onSelect={setValue} placeholder="Search models" />
+    </div>
+  );
+}
+```
+
+#### In a picker
+
+```tsx
+function Picker() {
+  const [open, setOpen] = useState(false);
+  const [value, setValue] = useState<string | null>(null);
+  const chosen = models.find((m) => m.model === value);
+  return (
+    <PickerPopover
+      title="Model"
+      open={open}
+      onOpenChange={setOpen}
+      trigger={
+        <PickerTrigger aria-label="Model" placeholder="Choose a model">
+          {chosen?.name}
+        </PickerTrigger>
+      }
+    >
+      <CommandList
+        aria-label="Models"
+        groups={groups}
+        value={value}
+        autoFocus
+        placeholder="Search models"
+        onSelect={(v) => {
+          setValue(v);
+          setOpen(false);
+        }}
+      />
+    </PickerPopover>
+  );
+}
+```
+
+#### Ten thousand rows
+
+```tsx
+function Thousands() {
+  const [value, setValue] = useState<string | null>(null);
+  return (
+    <div className="w-400 max-w-full">
+      <CommandList height="inline" aria-label="Models" groups={thousands} value={value} onSelect={setValue} placeholder="Search 10,000 models" />
+    </div>
+  );
+}
+```
+
 ## CommandPalette
 
 ⌘K: every page and action, grouped; nested pages; async groups with a quiet progress line.
@@ -1012,15 +1095,20 @@ The console's table: a 36px header, 40px rows without lines, numbers right, sort
 
 | Key | Action |
 |---|---|
-| Tab | Moves to the next row |
+| Tab | Moves into the table, to the row last in focus, and out again |
+| Up Down | Move between rows |
+| Home End | First and last row |
+| Page Up Page Down | A screen of rows up or down |
 | Enter | Opens the row |
+| Space | Selects the row, in a selectable table |
+| Left Right | Resize a column, on its handle |
 | shift F10 | Opens the row menu |
 
 ### Accessibility
 
 - role=table with column headers; sorted columns carry aria-sort.
 - Columns declare a priority; low-priority columns hide first when space is short. A growing column then shrinks to its readable minimum (minWidth, 136px by default) and truncates. On a screen narrower still, the other priority 1 columns give way from the row's end backwards, keeping its last column (the actions) and the selection boxes; only a row with nothing left to give way scrolls sideways, its last column pinned at the end.
-- Over 100 rows render virtually; the row count is in aria-rowcount.
+- Over 100 rows render virtually; the row count is in aria-rowcount and each row's place in aria-rowindex.
 
 ### Examples
 
@@ -1132,6 +1220,7 @@ A pill showing the date; a calendar with circles, today ringed, and a typed ISO
 | Arrows | Move between days |
 | Page Up Page Down | Previous and next month |
 | Enter | Chooses the day |
+| Up Down | Move between the range's presets |
 
 ### Accessibility
 
@@ -1184,7 +1273,7 @@ The destructive flow: the object and the consequence, typed confirmation, a dang
 
 ## Dialog
 
-A modal dialog: 440, 560 or 720 wide, radius 20; title, description, body, actions. ⌘Enter submits. Longer forms use StepDialog: one question per step.
+A modal dialog: 440, 560 or 720 wide, radius 20; title, description, body, actions. Enter in a field and ⌘Enter submit. Longer forms use StepDialog: one question per step.
 
 `import { Dialog } from "@logicplanes/kaeso-ui";`
 
@@ -1194,7 +1283,8 @@ A modal dialog: 440, 560 or 720 wide, radius 20; title, description, body, actio
 |---|---|
 | Escape | Closes and returns focus to the trigger |
 | Tab | Moves within the dialog |
-| mod Enter | Submits |
+| Enter | Submits from a single-line field |
+| mod Enter | Submits from anywhere in the dialog |
 
 ### Accessibility
 
@@ -1600,14 +1690,14 @@ What is absent and the next step: an icon circle, a title, one sentence, one or
 
 ## Field
 
-A label, a control and its help, wired together; errors are toasts, never text under the field.
+A label, a control and its help, wired together; an error shows under the control.
 
 `import { Field, Fieldset } from "@logicplanes/kaeso-ui";`
 
 ### Accessibility
 
 - The label points at the control; help is in aria-describedby.
-- invalid sets aria-invalid and the danger ring; say what is wrong in a toast. A deprecated error stays the control's description for a screen reader but isn't drawn.
+- invalid sets aria-invalid and the danger ring; error shows what is wrong under the control and is its description for a screen reader.
 - Optional fields are marked, not required ones.
 
 ### Examples
@@ -1988,7 +2078,7 @@ A pill text field with the secondary material and a soft focus halo.
 
 ### Accessibility
 
-- Pass label and description and the input wraps itself in Field, wiring aria-describedby; invalid sets aria-invalid. Errors are toasts, never text under the field.
+- Pass label and description and the input wraps itself in Field, wiring aria-describedby; invalid sets aria-invalid, and an error shows under the input.
 - Placeholders are hints, never labels.
 - Read-only fields stay selectable and focusable.
 
@@ -2138,7 +2228,7 @@ Kaeso's identities: a redacted key with its state, a model with its provider and
 
 ### Accessibility
 
-- Providers show their mark in the text color, so it follows the theme; others a letter. The name is always next to it or its accessible label.
+- Providers show their mark in its owner's one-colour version for the theme; others a letter. The name is always next to it or its accessible label.
 - Capability icons have tooltips and are summarized in an accessible label.
 - Status codes carry their phrase for screen readers.
 
@@ -2160,11 +2250,11 @@ Kaeso's identities: a redacted key with its state, a model with its provider and
 ```tsx
 <div className="flex flex-col gap-12">
   {models.map((m) => (
-    <ModelLabel key={m.id} provider={m.provider} model={m.model} name={m.name} capabilities={m.capabilities} />
+    <ModelLabel key={m.id} provider={m.provider} providerName={providerNames[m.provider]} model={m.model} name={m.name} capabilities={m.capabilities} />
   ))}
   <div className="flex gap-12">
-    <ProviderBadge provider="openai" withName />
-    <ProviderBadge provider="anthropic" withName />
+    <ProviderBadge provider="openai" name="OpenAI" withName />
+    <ProviderBadge provider="anthropic" name="Anthropic" withName />
   </div>
 </div>
 ```
@@ -2188,6 +2278,7 @@ Kaeso's identities: a redacted key with its state, a model with its provider and
 <div className="grid w-full grid-cols-1 gap-16 md:grid-cols-2">
   <ProviderCard
     provider="openai"
+    name="OpenAI"
     connected
     status="The organization's key"
     keyLabel="Production …4f2a"
@@ -2196,6 +2287,7 @@ Kaeso's identities: a redacted key with its state, a model with its provider and
   />
   <ProviderCard
     provider="anthropic"
+    name="Anthropic"
     connected={false}
     status="No key yet: requests to Anthropic fail"
     actions={
@@ -2323,7 +2415,11 @@ function Wizard() {
         <List
           aria-label="Models on models.dev"
           density="compact"
-          items={models.map((x) => ({ id: x.model, textValue: x.model, title: <ModelLabel provider={x.provider} model={x.model} name={x.name} /> }))}
+          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} />,
+          }))}
           onOpen={(item) => {
             setModel(item.id);
             setView("review");
@@ -2344,7 +2440,7 @@ function Wizard() {
       description: "Prices come from models.dev; you can override them.",
       content: m && (
         <div className="flex flex-col gap-16">
-          <ModelLabel provider={m.provider} model={m.model} name={m.name} capabilities={m.capabilities} />
+          <ModelLabel provider={m.provider} providerName={providerNames[m.provider]} model={m.model} name={m.name} capabilities={m.capabilities} />
           <KeyValue
             items={[
               { label: "Input", value: `$${m.input} / M` },
@@ -2867,7 +2963,7 @@ A limit or quota: label and value, a 6px pill track, threshold ticks and a capti
 
 ## ModelPicker
 
-A model from the project's catalogue: provider mark, name and id, grouped by provider. The start of a comparison column's header.
+A model from a catalogue of any size: searchable, grouped by provider, recent models on top. The start of a comparison column's header.
 
 `import { ModelPicker } from "@logicplanes/kaeso-ui/playground";`
 
@@ -2875,13 +2971,17 @@ A model from the project's catalogue: provider mark, name and id, grouped by pro
 
 | Key | Action |
 |---|---|
-| Enter Space | Opens the list |
+| Enter Space | Opens the list with its search focused |
+| A–Z | Searches by name, id or provider |
 | Up Down | Moves through models |
-| A–Z | Jumps to a model by name |
+| Enter | Chooses the active model |
+| Escape | Clears the search, then closes |
 
 ### Accessibility
 
-- A select named “Model” by default; each option reads the model's name.
+- A button named “Model” by default opens a search field over a listbox, one group per provider.
+- Above the list, a Provider select narrows it to one provider; it offers only the providers whose models match the search.
+- On phones the list opens as a full-screen sheet with the search on top.
 
 ### Examples
 
@@ -2892,7 +2992,7 @@ function Basic() {
   const [model, setModel] = useState("claude-sonnet-4-5");
   return (
     <div className="flex h-52 w-full max-w-360 items-center pl-8 hairline-b">
-      <ModelPicker value={model} onValueChange={setModel} options={playgroundModels} />
+      <ModelPicker value={model} onValueChange={setModel} options={playgroundModels} providers={providers} />
     </div>
   );
 }
@@ -2901,7 +3001,26 @@ function Basic() {
 #### Raised
 
 ```tsx
-<ModelPicker appearance="default" size="md" defaultValue="gpt-5" options={playgroundModels} />
+<ModelPicker appearance="default" size="md" defaultValue="gpt-5" options={playgroundModels} providers={providers} />
+```
+
+#### With details and recent models
+
+```tsx
+function Catalogue() {
+  const [model, setModel] = useState<string | null>(null);
+  return (
+    <ModelPicker
+      appearance="default"
+      size="md"
+      options={catalogue}
+      providers={providers.map((p) => ({ ...p, connected: p.id === "anthropic" }))}
+      recent={["claude-sonnet-4-5"]}
+      value={model}
+      onValueChange={setModel}
+    />
+  );
+}
 ```
 
 ## NumberInput
@@ -3213,7 +3332,7 @@ A floating panel next to its trigger; HoverCard previews on hover, never as the
   </HoverCard.Trigger>
   <HoverCard.Content>
     <div className="flex flex-col gap-12">
-      <ModelLabel provider="anthropic" model="claude-sonnet-4-5" capabilities={["tools", "reasoning", "vision", "pdf"]} />
+      <ModelLabel provider="anthropic" providerName="Anthropic" model="claude-sonnet-4-5" capabilities={["tools", "reasoning", "vision", "pdf"]} />
       <KeyValue
         items={[
           { label: "Input", value: "$3.00 / M" },
@@ -3252,6 +3371,58 @@ function Basic() {
 }
 ```
 
+## ProviderPicker
+
+Choosing a provider from any number of them: connected ones first with their key counts, then the rest.
+
+`import { ProviderPicker } from "@logicplanes/kaeso-ui";`
+
+### Keyboard
+
+| Key | Action |
+|---|---|
+| A–Z | Searches by name or id |
+| Up Down | Moves through providers |
+| Enter | Chooses the active provider |
+
+### Accessibility
+
+- A search field over a listbox, with Connected and Other providers as groups; each option reads the provider's name and hint.
+
+### Examples
+
+#### In a dialog step
+
+```tsx
+function List() {
+  const [provider, setProvider] = useState<string | null>("openai");
+  return (
+    <div className="w-400 max-w-full">
+      <ProviderPicker aria-label="Provider" providers={providers} value={provider} onValueChange={setProvider} />
+    </div>
+  );
+}
+```
+
+#### In a toolbar
+
+```tsx
+function Select() {
+  const [provider, setProvider] = useState<string | null>(null);
+  return (
+    <ProviderPicker
+      appearance="select"
+      size="sm"
+      aria-label="Provider"
+      allLabel="All providers"
+      providers={providers}
+      value={provider}
+      onValueChange={setProvider}
+    />
+  );
+}
+```
+
 ## QRCode
 
 A scannable code drawn as one SVG path: dark modules on white in both themes, with a quiet zone.
@@ -3310,6 +3481,60 @@ One of a few choices: an ink donut around a panel center; RadioCards for choices
 </div>
 ```
 
+## Reasoning
+
+A model's reasoning behind a quiet disclosure: “Thought for 4.2 s” when it is done, “Thinking” with its latest line while it streams.
+
+`import { Reasoning } from "@logicplanes/kaeso-ui/playground";`
+
+### Accessibility
+
+- A disclosure button: Enter or Space opens and closes it, and the reasoning follows it in reading order.
+
+### Examples
+
+#### Finished reasoning
+
+```tsx
+<Reasoning text={REASONING} duration={4200} />
+```
+
+#### In a request log
+
+```tsx
+<Reasoning title="Reasoning" hint="Redacted by the provider">
+  <Text variant="small" tone="secondary">
+    The provider redacted this reasoning; only its encrypted form was returned.
+  </Text>
+</Reasoning>
+```
+
+## ReleaseArt
+
+Flat geometric artwork for a release, from a stored spec or a seed: the same picture every time, a new one for every release.
+
+`import { ReleaseArt } from "@logicplanes/kaeso-ui";`
+
+### Accessibility
+
+- The artwork is an image with a label; the title drawn on it is part of the picture, so say it in the label too.
+
+### Examples
+
+#### What's new
+
+```tsx
+<div className="w-full max-w-640">
+  <ReleaseArt
+    seed="0.3.0"
+    art={{ version: 1, seed: 2886621037, style: "stripes", palette: 6 }}
+    label="Kaeso 0.3.0"
+    eyebrow="What's new in Kaeso"
+    title="0.3.0"
+  />
+</div>
+```
+
 ## ResourceList
 
 A searchable list with group headers, row actions and a selection bar.
@@ -3357,7 +3582,7 @@ A response's numbers on one line: time to first token, total time, tokens in and
 
 ## ResponseView
 
-A model's response as it arrives: Markdown with a quiet caret, reasoning in a Thinking disclosure, and calm stopped and failed states.
+A model's response as it arrives: Markdown with a quiet caret, reasoning in a Thinking disclosure, and calm stopped, cut-off and failed states.
 
 `import { ResponseView, UserMessage, Thread } from "@logicplanes/kaeso-ui/playground";`
 
@@ -3371,7 +3596,7 @@ A model's response as it arrives: Markdown with a quiet caret, reasoning in a Th
 
 - Each response is an article named by aria-label (“GPT-5 response” in a comparison) and is aria-busy while it streams, so its words aren't read out one by one.
 - Thinking is a disclosure button; closed, its row shows the latest line of the summary, hidden from screen readers, which read the summary when opened.
-- A failure says only “No response” in place: the error itself is a toast.
+- A failure is an alert in place of the response: “No response”, then the error.
 
 ### Examples
 
@@ -4562,7 +4787,7 @@ Removable tags in a field: Enter, comma and paste split them; Backspace removes
 ### Accessibility
 
 - Each tag's remove circle is named “Remove …”.
-- Invalid tags stay, marked with the danger ring; each says what is wrong in its tooltip, and the first problem is the field's description for a screen reader. Nothing is drawn under the field.
+- Invalid tags stay, marked with the danger ring; each says what is wrong in its tooltip, and the first problem shows under the field.
 
 ### Examples