@fungi.computer/caps 0.0.0-stage → 0.0.1

package/docs/api/components/activity-line.md

@@ -0,0 +1,103 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/caps**](../README.md)
+
+---
+
+[@fungi.computer/caps](../README.md) / components/activity-line
+
+# components/activity-line
+
+## Type Aliases
+
+### ActivityState
+
+```ts
+type ActivityState = "running" | "done" | "failed";
+```
+
+Where a piece of agent work stands.
+
+---
+
+### ActivityLineProps
+
+```ts
+type ActivityLineProps = Readonly<{
+  state: ActivityState;
+  startedAt: number;
+  finishedAt?: number;
+  label: string;
+  doneLabel: string;
+  failedLabel?: string;
+  children?: ReactNode;
+  className?: string;
+}>;
+```
+
+Props accepted by ActivityLine.
+
+## Functions
+
+### formatElapsed()
+
+```ts
+function formatElapsed(milliseconds): string;
+```
+
+Short elapsed time: `0.4s`, `4.2s`, `42s`, `3m 05s`.
+
+#### Parameters
+
+| Parameter      | Type     |
+| -------------- | -------- |
+| `milliseconds` | `number` |
+
+#### Returns
+
+`string`
+
+---
+
+### useElapsed()
+
+```ts
+function useElapsed(startedAt, finishedAt, running): number;
+```
+
+A clock that ticks while `running` and holds still otherwise. Times are epoch
+milliseconds (`Date.now()`), owned by the caller.
+
+#### Parameters
+
+| Parameter    | Type                    |
+| ------------ | ----------------------- |
+| `startedAt`  | `number`                |
+| `finishedAt` | `number` \| `undefined` |
+| `running`    | `boolean`               |
+
+#### Returns
+
+`number`
+
+---
+
+### ActivityLine()
+
+```ts
+function ActivityLine(__namedParameters): Element;
+```
+
+One line of agent activity. While running it says what is happening with a live
+clock and shows its trace; when done it settles into "Thought for 4.2s" and
+folds the trace away, one click from reopening.
+
+#### Parameters
+
+| Parameter           | Type                                      |
+| ------------------- | ----------------------------------------- |
+| `__namedParameters` | [`ActivityLineProps`](#activitylineprops) |
+
+#### Returns
+
+`Element`

package/docs/api/components/alert.md

@@ -0,0 +1,60 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/caps**](../README.md)
+
+---
+
+[@fungi.computer/caps](../README.md) / components/alert
+
+# components/alert
+
+## Type Aliases
+
+### AlertTone
+
+```ts
+type AlertTone =
+  | "neutral"
+  | "primary"
+  | "secondary"
+  | "accent"
+  | "success"
+  | "info"
+  | "warning"
+  | "error";
+```
+
+Supported AlertTone values.
+
+---
+
+### AlertProps
+
+```ts
+type AlertProps = object & Omit<HTMLAttributes<HTMLDivElement>, "title">;
+```
+
+Props accepted by Alert.
+
+#### Type Declaration
+
+| Name           | Type                      |
+| -------------- | ------------------------- |
+| `action?`      | `ReactNode`               |
+| `description?` | `ReactNode`               |
+| `title?`       | `ReactNode`               |
+| `tone?`        | [`AlertTone`](#alerttone) |
+
+## Variables
+
+### Alert
+
+```ts
+const Alert: ForwardRefExoticComponent<
+  object &
+    Omit<HTMLAttributes<HTMLDivElement>, "title"> &
+    RefAttributes<HTMLDivElement>
+>;
+```
+
+A caller-labelled alert presentation.

package/docs/api/components/badge.md

@@ -0,0 +1,77 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/caps**](../README.md)
+
+---
+
+[@fungi.computer/caps](../README.md) / components/badge
+
+# components/badge
+
+## Type Aliases
+
+### BadgeTone
+
+```ts
+type BadgeTone =
+  | "neutral"
+  | "primary"
+  | "secondary"
+  | "accent"
+  | "success"
+  | "info"
+  | "warning"
+  | "error";
+```
+
+Supported BadgeTone values.
+
+---
+
+### BadgeSize
+
+```ts
+type BadgeSize = "sm" | "default" | "lg";
+```
+
+Supported BadgeSize values.
+
+---
+
+### BadgeVariant
+
+```ts
+type BadgeVariant = "solid" | "quiet";
+```
+
+`quiet` is a soft tint with no outline, for labels that sit beside keys.
+
+---
+
+### BadgeProps
+
+```ts
+type BadgeProps = object & HTMLAttributes<HTMLSpanElement>;
+```
+
+Props accepted by Badge.
+
+#### Type Declaration
+
+| Name       | Type                            |
+| ---------- | ------------------------------- |
+| `size?`    | [`BadgeSize`](#badgesize)       |
+| `variant?` | [`BadgeVariant`](#badgevariant) |
+| `tone?`    | [`BadgeTone`](#badgetone)       |
+
+## Variables
+
+### Badge
+
+```ts
+const Badge: ForwardRefExoticComponent<
+  object & HTMLAttributes<HTMLSpanElement> & RefAttributes<HTMLSpanElement>
+>;
+```
+
+A compact status or category label.

package/docs/api/components/button.md

@@ -0,0 +1,94 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/caps**](../README.md)
+
+---
+
+[@fungi.computer/caps](../README.md) / components/button
+
+# components/button
+
+## Type Aliases
+
+### ButtonVariant
+
+```ts
+type ButtonVariant =
+  | "primary"
+  | "secondary"
+  | "accent"
+  | "destructive"
+  | "outline"
+  | "ghost"
+  | "ghost-destructive"
+  | "link";
+```
+
+Supported Button visual variants.
+
+---
+
+### ButtonSize
+
+```ts
+type ButtonSize = "xs" | "sm" | "default" | "lg" | "icon" | "menubar";
+```
+
+Supported ButtonSize values.
+
+---
+
+### ButtonResult
+
+```ts
+type ButtonResult = "done" | "failed";
+```
+
+The outcome of a Button's last action.
+
+---
+
+### ButtonProps
+
+```ts
+type ButtonProps = object & ButtonHTMLAttributes<HTMLButtonElement>;
+```
+
+Props accepted by Button.
+
+#### Type Declaration
+
+| Name             | Type                              | Description                                                                                                                                                                                                                                                                 |
+| ---------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `asChild?`       | `boolean`                         | -                                                                                                                                                                                                                                                                           |
+| `loading?`       | `boolean`                         | -                                                                                                                                                                                                                                                                           |
+| `result?`        | [`ButtonResult`](#buttonresult)   | The outcome of the last action. Becoming `done` plays a short beat: a check (and `resultLabel`) springs in, holds, then settles back to the label. Becoming `failed` shakes the label by the theme's `--stipe-motion-shake`. Say what failed elsewhere, next to the action. |
+| `resultLabel?`   | `ReactNode`                       | What the done beat says, such as "Installed". The button keeps the wider of its two labels, so nothing shifts.                                                                                                                                                              |
+| `onResultEnd()?` | () => `void`                      | Called when the done beat has held long enough to read, just before it would settle back to the label. Replace the button here to hand off to what comes next (an "Installed" mark, an "Open" action).                                                                      |
+| `size?`          | [`ButtonSize`](#buttonsize)       | -                                                                                                                                                                                                                                                                           |
+| `variant?`       | [`ButtonVariant`](#buttonvariant) | -                                                                                                                                                                                                                                                                           |
+
+---
+
+### ButtonElement
+
+```ts
+type ButtonElement = ElementRef<"button">;
+```
+
+The native element type used by Button.
+
+## Variables
+
+### Button
+
+```ts
+const Button: ForwardRefExoticComponent<
+  object &
+    ButtonHTMLAttributes<HTMLButtonElement> &
+    RefAttributes<HTMLButtonElement>
+>;
+```
+
+A reusable button with caller-controlled native behavior and intrinsic loading
+presentation.

package/docs/api/components/card.md

@@ -0,0 +1,165 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/caps**](../README.md)
+
+---
+
+[@fungi.computer/caps](../README.md) / components/card
+
+# components/card
+
+## Type Aliases
+
+### CardProps
+
+```ts
+type CardProps = object & HTMLAttributes<HTMLDivElement>;
+```
+
+Props accepted by Card.
+
+#### Type Declaration
+
+| Name        | Type                                                                 | Description                                                            |
+| ----------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `variant?`  | `"surface"` \| `"outline"` \| `"interactive"` \| `"game"` \| `"fit"` | -                                                                      |
+| `featured?` | `boolean`                                                            | Emphasize a featured item without changing its interaction.            |
+| `state?`    | `"empty"`                                                            | Present the absence of content within the same card shell.             |
+| `density?`  | `"regular"` \| `"compact"`                                           | Reduce card section padding when several related details share a page. |
+
+---
+
+### CenteredCardProps
+
+```ts
+type CenteredCardProps = CardProps & object;
+```
+
+Props accepted by CenteredCard.
+
+#### Type Declaration
+
+| Name     | Type                    |
+| -------- | ----------------------- |
+| `width?` | `"default"` \| `"wide"` |
+
+---
+
+### CardHeaderProps
+
+```ts
+type CardHeaderProps = object & HTMLAttributes<HTMLDivElement>;
+```
+
+A card header layout with optional centered alignment.
+
+#### Type Declaration
+
+| Name         | Type                    |
+| ------------ | ----------------------- |
+| `alignment?` | `"start"` \| `"center"` |
+
+---
+
+### CardTitleProps
+
+```ts
+type CardTitleProps = HTMLAttributes<HTMLHeadingElement> & object;
+```
+
+Props accepted by CardTitle.
+
+#### Type Declaration
+
+| Name     | Type       | Description                                                        |
+| -------- | ---------- | ------------------------------------------------------------------ |
+| `level?` | `2` \| `3` | Heading level; the host keeps its document outline. Defaults to 3. |
+
+## Variables
+
+### Card
+
+```ts
+const Card: ForwardRefExoticComponent<
+  object & HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement>
+>;
+```
+
+A presentational card shell.
+
+---
+
+### CenteredCard
+
+```ts
+const CenteredCard: ForwardRefExoticComponent<
+  object &
+    HTMLAttributes<HTMLDivElement> &
+    object &
+    RefAttributes<HTMLDivElement>
+>;
+```
+
+Center one primary card in a welcoming, viewport-filling page stage.
+
+---
+
+### CardHeader
+
+```ts
+const CardHeader: ForwardRefExoticComponent<
+  object & HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement>
+>;
+```
+
+Render a Caps card header with the requested alignment.
+
+---
+
+### CardTitle
+
+```ts
+const CardTitle: ForwardRefExoticComponent<
+  HTMLAttributes<HTMLHeadingElement> &
+    object &
+    RefAttributes<HTMLHeadingElement>
+>;
+```
+
+A card title element.
+
+---
+
+### CardDescription
+
+```ts
+const CardDescription: ForwardRefExoticComponent<
+  HTMLAttributes<HTMLParagraphElement> & RefAttributes<HTMLParagraphElement>
+>;
+```
+
+A card supporting-description element.
+
+---
+
+### CardContent
+
+```ts
+const CardContent: ForwardRefExoticComponent<
+  HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement>
+>;
+```
+
+A card body layout.
+
+---
+
+### CardFooter
+
+```ts
+const CardFooter: ForwardRefExoticComponent<
+  HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement>
+>;
+```
+
+A card footer layout.

package/docs/api/components/chat-bubble.md

@@ -0,0 +1,66 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/caps**](../README.md)
+
+---
+
+[@fungi.computer/caps](../README.md) / components/chat-bubble
+
+# components/chat-bubble
+
+## Type Aliases
+
+### ChatBubbleSide
+
+```ts
+type ChatBubbleSide = "agent" | "user";
+```
+
+Which side of the conversation a bubble sits on.
+
+---
+
+### ChatBubbleState
+
+```ts
+type ChatBubbleState = "settled" | "pending" | "error";
+```
+
+`pending` is still being written; `error` is a turn that did not finish.
+
+---
+
+### ChatBubbleProps
+
+```ts
+type ChatBubbleProps = object &
+  Omit<HTMLAttributes<HTMLDivElement>, "children">;
+```
+
+Props accepted by ChatBubble.
+
+#### Type Declaration
+
+| Name        | Type                                  | Description                                                             |
+| ----------- | ------------------------------------- | ----------------------------------------------------------------------- |
+| `side`      | [`ChatBubbleSide`](#chatbubbleside)   | An agent speaks from the left with its mark; the person from the right. |
+| `avatar?`   | `ReactNode`                           | A mark for an agent, drawn beside its bubble.                           |
+| `name?`     | `ReactNode`                           | Who is speaking, on the line above the bubble.                          |
+| `time?`     | `ReactNode`                           | When it was said, or what the speaker is doing instead.                 |
+| `state?`    | [`ChatBubbleState`](#chatbubblestate) | -                                                                       |
+| `children?` | `ReactNode`                           | -                                                                       |
+
+## Variables
+
+### ChatBubble
+
+```ts
+const ChatBubble: ForwardRefExoticComponent<
+  object &
+    Omit<HTMLAttributes<HTMLDivElement>, "children"> &
+    RefAttributes<HTMLDivElement>
+>;
+```
+
+One turn of a conversation: who said it, when, and what. It owns the sides, the
+bubble and the still-writing dots; the caller owns the content.

package/docs/api/components/checkbox-bead.md

@@ -0,0 +1,20 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/caps**](../README.md)
+
+---
+
+[@fungi.computer/caps](../README.md) / components/checkbox-bead
+
+# components/checkbox-bead
+
+## Type Aliases
+
+### CheckboxState
+
+```ts
+type CheckboxState = "unchecked" | "checked" | "mixed";
+```
+
+Visual state of a checkbox's mark: unchecked, checked, or indeterminate
+("mixed").

package/docs/api/components/checkbox.md

@@ -0,0 +1,42 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/caps**](../README.md)
+
+---
+
+[@fungi.computer/caps](../README.md) / components/checkbox
+
+# components/checkbox
+
+## Type Aliases
+
+### CheckboxProps
+
+```ts
+type CheckboxProps = object & InputHTMLAttributes<HTMLInputElement>;
+```
+
+Props accepted by Checkbox.
+
+#### Type Declaration
+
+| Name             | Type                       | Description                                                                  |
+| ---------------- | -------------------------- | ---------------------------------------------------------------------------- |
+| `appearance?`    | `"default"` \| `"compact"` | Compact instruments keep the wrapper's focus ring and disabled ink readable. |
+| `indicator?`     | `ReactNode`                | Replaces the bead while the native input continues to own selection.         |
+| `invalid?`       | `boolean`                  | -                                                                            |
+| `indeterminate?` | `boolean`                  | Shows a mixed selection while checked still controls native form submission. |
+
+## Variables
+
+### Checkbox
+
+```ts
+const Checkbox: ForwardRefExoticComponent<
+  object &
+    InputHTMLAttributes<HTMLInputElement> &
+    RefAttributes<HTMLInputElement>
+>;
+```
+
+A native checkbox with styled invalid-state presentation.

package/docs/api/components/code-input.md

@@ -0,0 +1,61 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/caps**](../README.md)
+
+---
+
+[@fungi.computer/caps](../README.md) / components/code-input
+
+# components/code-input
+
+## Type Aliases
+
+### CodeInputStatus
+
+```ts
+type CodeInputStatus = "idle" | "invalid" | "accepted";
+```
+
+What the caller has learned about the entered code.
+
+---
+
+### CodeInputProps
+
+```ts
+type CodeInputProps = object &
+  Omit<
+    InputHTMLAttributes<HTMLInputElement>,
+    "value" | "defaultValue" | "onChange" | "maxLength" | "size"
+  >;
+```
+
+Props accepted by CodeInput.
+
+#### Type Declaration
+
+| Name              | Type                                  | Description                                                                                                                                       |
+| ----------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `length?`         | `number`                              | How many characters the code has.                                                                                                                 |
+| `value`           | `string`                              | The current code.                                                                                                                                 |
+| `onValueChange()` | (`value`) => `void`                   | Receives the code after a native edit or a normalized paste.                                                                                      |
+| `status?`         | [`CodeInputStatus`](#codeinputstatus) | `invalid` shakes the slots in a cascade and marks them; `accepted` lifts them in a wave. Say what was wrong next to the field, as with any error. |
+
+## Variables
+
+### CodeInput
+
+```ts
+const CodeInput: ForwardRefExoticComponent<
+  object &
+    Omit<
+      InputHTMLAttributes<HTMLInputElement>,
+      "defaultValue" | "onChange" | "size" | "value" | "maxLength"
+    > &
+    RefAttributes<HTMLInputElement>
+>;
+```
+
+A short code (a sign-in or pairing code) shown as one slot per character. It is
+a single native input underneath, so typing, pasting, one-time-code autofill and
+screen readers behave as they do on any text field.