@logicplanes/kaeso-ui 0.1.0 → 0.2.0

package/AGENTS.md

@@ -97,6 +97,7 @@ export function Providers({ children }: { children: React.ReactNode }) {
 | One of many options                      | `Select`; searchable: `Combobox`                                |
 | A confirmation of an irreversible action | `AlertDialog`; deletion: the `DeleteResource` block             |
 | A task in several steps                  | `StepDialog`                                                    |
+| A dialog that opens fresh every time     | `DialogScope` around the component that keeps its state         |
 | Feedback after an action                 | `toast()`, with Undo for reversible actions                     |
 | A secret shown once                      | `SecretReveal`                                                  |
 | Numbers at a glance                      | `MetricRow` with `Stat`; over time: `TimeseriesChart`           |

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Devin Oldenburg
+Copyright (c) 2026 Devin Oldenburg (Logicplanes)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/ai/component-guides.md

@@ -1,6 +1,6 @@
 # @logicplanes/kaeso-ui component guides
 
-Version 0.1.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`.
+Version 0.2.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
 
@@ -1202,7 +1202,7 @@ A modal dialog: 440, 560 or 720 wide, radius 20; title, description, body, actio
 - The title names the dialog; the description is its accessible description.
 - The footer line appears only while content scrolls under it.
 - In steps, Continue and Back move focus to the new step's first field, or by the same rule to its primary or safe action when it has none, and the step's number and question are announced.
-- In steps, the dialog takes each step's height and keeps its top; with reduced motion the step and the height change at once.
+- The dialog stays centered while its content changes: it grows or shrinks to the new height from the size it has, and the body scrolls between the header and the footer when the content is taller than the screen. With reduced motion the size and the step change at once.
 
 ### Examples
 
@@ -1261,7 +1261,7 @@ function Steps() {
   const [name, setName] = useState("");
   return (
     <>
-      <Button variant="primary" onClick={() => setOpen(true)}>
+      <Button variant="primary" onClick={() => (setName(""), setOpen(true))}>
         Create key
       </Button>
       <StepDialog
@@ -1302,7 +1302,7 @@ function StepHeights() {
   const [level, setLevel] = useState("project");
   return (
     <>
-      <Button variant="primary" onClick={() => setOpen(true)}>
+      <Button variant="primary" onClick={() => (setLevel("project"), setOpen(true))}>
         Add limit
       </Button>
       <StepDialog
@@ -1322,6 +1322,125 @@ function StepHeights() {
 }
 ```
 
+#### The key, shown once after the last step
+
+```tsx
+function WithResult() {
+  const [open, setOpen] = useState(false);
+  const [name, setName] = useState("");
+  const [created, setCreated] = useState(false);
+  const close = () => setOpen(false);
+  const start = () => {
+    setName("");
+    setCreated(false);
+    setOpen(true);
+  };
+  return (
+    <>
+      <Button variant="primary" onClick={start}>
+        Create key
+      </Button>
+      <StepDialog
+        open={open}
+        onOpenChange={(o) => !o && close()}
+        title="Create key"
+        submitLabel="Create key"
+        onSubmit={() => setCreated(true)}
+        steps={[
+          {
+            id: "name",
+            title: "What is it for?",
+            description: "Shown in request logs and alerts.",
+            blockedReason: name.trim() ? undefined : "Enter a name",
+            content: <Input aria-label="Name" placeholder="checkout-web" value={name} onChange={(e) => setName(e.target.value)} autoFocus />,
+          },
+          {
+            id: "expiry",
+            title: "When does it expire?",
+            content: <Select aria-label="Expires" options={expiry} defaultValue="90" fullWidth />,
+          },
+        ]}
+        result={
+          created
+            ? {
+                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" />,
+                footer: <Button onClick={close}>Done</Button>,
+              }
+            : undefined
+        }
+      />
+    </>
+  );
+}
+```
+
+#### Content that grows and shrinks
+
+```tsx
+function Changing() {
+  const [open, setOpen] = useState(false);
+  const [email, setEmail] = useState("");
+  const [tried, setTried] = useState(false);
+  const [toProjects, setToProjects] = useState(false);
+  const invalid = tried && !/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email);
+  const send = () => {
+    setTried(true);
+    if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)) return;
+    setOpen(false);
+    toast.success(`Invitation sent to ${email}`);
+  };
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(o) => {
+        if (o) {
+          setEmail("");
+          setTried(false);
+          setToProjects(false);
+        }
+        setOpen(o);
+      }}
+      trigger={<Button variant="primary">Invite member</Button>}
+      title="Invite member"
+      description="The link works for 21 days."
+      onSubmit={send}
+      footer={
+        <>
+          <Dialog.Close>
+            <Button>Cancel</Button>
+          </Dialog.Close>
+          <Button variant="primary" onClick={send}>
+            Send invitation
+          </Button>
+        </>
+      }
+    >
+      <div className="flex flex-col gap-20">
+        <Input
+          label="Email address"
+          placeholder="ana@northwind.example"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          error={invalid ? "Enter a full address, like ana@northwind.example" : undefined}
+          autoFocus
+        />
+        <Checkbox label="Add them to projects now" checked={toProjects} onCheckedChange={setToProjects} />
+        {toProjects && (
+          <CheckboxGroup aria-label="Projects" defaultValue={projects.slice(0, 1).map((p) => p.id)} className="flex flex-col">
+            {projects.map((p) => (
+              <Checkbox key={p.id} value={p.id} label={p.name} />
+            ))}
+          </CheckboxGroup>
+        )}
+      </div>
+    </Dialog>
+  );
+}
+```
+
 #### Sizes
 
 ```tsx
@@ -1343,6 +1462,39 @@ function StepHeights() {
 </div>
 ```
 
+## DialogScope
+
+Opens a dialog's flow fresh every time: the first step, empty fields, no earlier result or secret. The content stays as it was while the dialog closes.
+
+`import { DialogScope } from "@logicplanes/kaeso-ui";`
+
+### Accessibility
+
+- Each open starts on the first step with the focus on its first field, as a new dialog does.
+- A secret shown once leaves the page and the component's state when the dialog has closed.
+
+### Examples
+
+#### Create a key, then another
+
+The key is shown once; closing the dialog forgets it, so the next key starts on the first step.
+
+```tsx
+function CreateKey() {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button variant="primary" onClick={() => setOpen(true)}>
+        Create key
+      </Button>
+      <DialogScope open={open}>
+        <CreateKeyFlow open={open} onClose={() => setOpen(false)} />
+      </DialogScope>
+    </>
+  );
+}
+```
+
 ## DisplayOptions
 
 View, grouping and ordering, toggles, and the properties to show, behind one circle at the end of a toolbar.
@@ -2151,11 +2303,13 @@ function Wizard() {
   const [model, setModel] = useState("");
   const [custom, setCustom] = useState("");
   const m = models.find((x) => x.model === model);
-  const close = () => {
-    setOpen(false);
+  const start = () => {
     setView("pick");
+    setModel("");
     setCustom("");
+    setOpen(true);
   };
+  const close = () => setOpen(false);
   const add = (id: string) => {
     close();
     toast.success(`Added ${id}`);
@@ -2219,7 +2373,7 @@ function Wizard() {
   };
   return (
     <>
-      <Button variant="primary" onClick={() => setOpen(true)}>
+      <Button variant="primary" onClick={start}>
         Add model
       </Button>
       <LayerDialog
@@ -2282,6 +2436,35 @@ Links look like links: text color with a quiet underline that turns solid on hov
 </div>
 ```
 
+#### Heading
+
+```tsx
+<h2 id="create-a-key" className="text-title font-semibold text-fg">
+  <Link href="#create-a-key" variant="heading">
+    Create a key
+  </Link>
+</h2>
+```
+
+#### Next pages
+
+```tsx
+<ul className="grid max-w-640 gap-12 sm:grid-cols-2">
+  <li className="flex">
+    <Link href="#" variant="card" className="w-full">
+      <span className="text-body font-medium">Calling models</span>
+      <span className="text-small text-fg-secondary">Call models from your app with the OpenAI and Anthropic SDKs.</span>
+    </Link>
+  </li>
+  <li className="flex">
+    <Link href="#" variant="card" className="w-full">
+      <span className="text-body font-medium">API keys</span>
+      <span className="text-small text-fg-secondary">Limit a key to the models and rates an app needs.</span>
+    </Link>
+  </li>
+</ul>
+```
+
 ## List
 
 44px rows on the panel, no lines, metadata on the right, group headers, keyboard first.
@@ -4484,6 +4667,85 @@ Multi-line text at radius 14: grows to eight lines, then scrolls.
 </div>
 ```
 
+## ThemeImage
+
+An image drawn twice, once for each theme, such as a diagram: it follows the theme setting, not only the system's, and prints the light one.
+
+`import { ThemeImage } from "@logicplanes/kaeso-ui";`
+
+### Accessibility
+
+- Both images carry the same text alternative; only the one for the current theme is shown, so a screen reader reads it once.
+- Pass aria-describedby with the id of a longer description when the image is a diagram.
+
+### Examples
+
+#### A diagram in both themes
+
+```tsx
+<ThemeImage light="/demos/route.light.svg" dark="/demos/route.dark.svg" alt="Route of a request: app, Kaeso, provider" width={364} height={49} />
+```
+
+## ThemeSelect
+
+A select for system, light or dark, stored as `kaeso:theme`, with its label in the provider's language.
+
+`import { ThemeSelect } from "@logicplanes/kaeso-ui";`
+
+### Keyboard
+
+| Key | Action |
+|---|---|
+| Enter Space | Opens |
+| Up Down | Moves |
+| Type | Jumps to an option |
+| Escape | Closes and returns focus |
+
+### Accessibility
+
+- Named Theme in the provider's language, and shows the choice in words, so it needs no aria-label and no icon.
+- Reads and sets the choice of the nearest ThemeProvider; every provider on the page follows it.
+
+### Examples
+
+#### Basic
+
+```tsx
+<ThemeProvider>
+  <ThemeSelect />
+</ThemeProvider>
+```
+
+#### In a sidebar's footer, beside the language
+
+```tsx
+<ThemeProvider>
+  <div className="grid w-240 grid-cols-2 gap-4">
+    <Select
+      aria-label="Language"
+      size="sm"
+      appearance="ghost"
+      fullWidth
+      defaultValue="en"
+      options={[
+        { value: "en", label: "English" },
+        { value: "de", label: "Deutsch" },
+        { value: "zh-CN", label: "简体中文" },
+      ]}
+    />
+    <ThemeSelect fullWidth />
+  </div>
+</ThemeProvider>
+```
+
+#### Raised
+
+```tsx
+<ThemeProvider>
+  <ThemeSelect appearance="default" size="md" />
+</ThemeProvider>
+```
+
 ## Timeline
 
 Events down a 1px line: the audit log.