@fungi.computer/caps 0.0.0-stage → 0.0.1

package/docs/api/blocks/spec-sheet.md

@@ -0,0 +1,400 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/caps**](../README.md)
+
+---
+
+[@fungi.computer/caps](../README.md) / blocks/spec-sheet
+
+# blocks/spec-sheet
+
+## Type Aliases
+
+### SpecRulerProps
+
+```ts
+type SpecRulerProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & object;
+```
+
+Props accepted by SpecRuler.
+
+#### Type Declaration
+
+| Name    | Type        | Description                                  |
+| ------- | ----------- | -------------------------------------------- |
+| `label` | `ReactNode` | A short section label, such as `01 · Plans`. |
+
+---
+
+### SpecFrameProps
+
+```ts
+type SpecFrameProps = Omit<HTMLAttributes<HTMLElement>, "children"> & object;
+```
+
+Props accepted by SpecFrame.
+
+#### Type Declaration
+
+| Name       | Type                       | Description                                                           |
+| ---------- | -------------------------- | --------------------------------------------------------------------- |
+| `children` | `ReactNode`                | Caller-owned media, such as an `img` with its own alt text.           |
+| `caption?` | `ReactNode`                | A short printed caption under the frame.                              |
+| `surface?` | `"default"` \| `"inverse"` | `inverse` seats dark media, such as a terminal readout, in the frame. |
+
+---
+
+### SpecFact
+
+```ts
+type SpecFact = object;
+```
+
+One fact in a SpecFacts strip.
+
+#### Properties
+
+##### id
+
+```ts
+id: string;
+```
+
+##### value
+
+```ts
+value: ReactNode;
+```
+
+##### label
+
+```ts
+label: ReactNode;
+```
+
+---
+
+### SpecFactsProps
+
+```ts
+type SpecFactsProps = Omit<HTMLAttributes<HTMLDListElement>, "children"> &
+  object;
+```
+
+Props accepted by SpecFacts.
+
+#### Type Declaration
+
+| Name    | Type                               |
+| ------- | ---------------------------------- |
+| `facts` | readonly [`SpecFact`](#specfact)[] |
+
+---
+
+### SpecStep
+
+```ts
+type SpecStep = object;
+```
+
+One step in a SpecSteps list.
+
+#### Properties
+
+##### id
+
+```ts
+id: string;
+```
+
+##### title
+
+```ts
+title: ReactNode;
+```
+
+##### body
+
+```ts
+body: ReactNode;
+```
+
+---
+
+### SpecStepsProps
+
+```ts
+type SpecStepsProps = Omit<HTMLAttributes<HTMLOListElement>, "children"> &
+  object;
+```
+
+Props accepted by SpecSteps.
+
+#### Type Declaration
+
+| Name    | Type                               |
+| ------- | ---------------------------------- |
+| `steps` | readonly [`SpecStep`](#specstep)[] |
+
+---
+
+### SpecFaqItem
+
+```ts
+type SpecFaqItem = object;
+```
+
+One question in a SpecFaq list.
+
+#### Properties
+
+##### id
+
+```ts
+id: string;
+```
+
+##### question
+
+```ts
+question: ReactNode;
+```
+
+##### answer
+
+```ts
+answer: ReactNode;
+```
+
+Caller-reviewed answer content.
+
+---
+
+### SpecFaqProps
+
+```ts
+type SpecFaqProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & object;
+```
+
+Props accepted by SpecFaq.
+
+#### Type Declaration
+
+| Name           | Type                                     | Description                       |
+| -------------- | ---------------------------------------- | --------------------------------- |
+| `items`        | readonly [`SpecFaqItem`](#specfaqitem)[] | -                                 |
+| `defaultOpen?` | readonly `string`[]                      | Ids of the items that start open. |
+
+---
+
+### SpecDiagramMarker
+
+```ts
+type SpecDiagramMarker = object;
+```
+
+One labelled part of a SpecDiagram, placed in percent of the art.
+
+#### Properties
+
+##### id
+
+```ts
+id: string;
+```
+
+##### tag
+
+```ts
+tag: string;
+```
+
+A short tag drawn on the art, such as `A`.
+
+##### x
+
+```ts
+x: number;
+```
+
+Distance from the art's left edge, 0 to 100.
+
+##### y
+
+```ts
+y: number;
+```
+
+Distance from the art's top edge, 0 to 100.
+
+##### label
+
+```ts
+label: ReactNode;
+```
+
+##### note?
+
+```ts
+optional note?: ReactNode;
+```
+
+---
+
+### SpecDiagramProps
+
+```ts
+type SpecDiagramProps = Omit<HTMLAttributes<HTMLElement>, "children"> & object;
+```
+
+Props accepted by SpecDiagram.
+
+#### Type Declaration
+
+| Name      | Type                                                 | Description                                               |
+| --------- | ---------------------------------------------------- | --------------------------------------------------------- |
+| `art`     | `ReactNode`                                          | Caller-owned art, such as an `img` with its own alt text. |
+| `markers` | readonly [`SpecDiagramMarker`](#specdiagrammarker)[] | -                                                         |
+
+---
+
+### SpecPrintFilterProps
+
+```ts
+type SpecPrintFilterProps = object;
+```
+
+Props accepted by SpecPrintFilter.
+
+#### Properties
+
+##### offset?
+
+```ts
+optional offset?: object;
+```
+
+Misregistration of the second ink, in CSS pixels. Defaults to 2, 1.
+
+###### x
+
+```ts
+x: number;
+```
+
+###### y
+
+```ts
+y: number;
+```
+
+## Variables
+
+### SpecRuler
+
+```ts
+const SpecRuler: ForwardRefExoticComponent<
+  Omit<HTMLAttributes<HTMLDivElement>, "children"> &
+    object &
+    RefAttributes<HTMLDivElement>
+>;
+```
+
+A tick-marked rule that separates sections, with crosshairs at both ends. It is
+decorative: the section heading carries the accessible name.
+
+---
+
+### SpecFrame
+
+```ts
+const SpecFrame: ForwardRefExoticComponent<
+  Omit<HTMLAttributes<HTMLElement>, "children"> &
+    object &
+    RefAttributes<HTMLElement>
+>;
+```
+
+A figure seated in a hatched band, like a plate in a printed manual.
+
+---
+
+### SpecFacts
+
+```ts
+const SpecFacts: ForwardRefExoticComponent<
+  Omit<HTMLAttributes<HTMLDListElement>, "children"> &
+    object &
+    RefAttributes<HTMLDListElement>
+>;
+```
+
+A ruled strip of short facts: a big value over a small label.
+
+---
+
+### SpecSteps
+
+```ts
+const SpecSteps: ForwardRefExoticComponent<
+  Omit<HTMLAttributes<HTMLOListElement>, "children"> &
+    object &
+    RefAttributes<HTMLOListElement>
+>;
+```
+
+A numbered row of steps in ruled cells, numbered 01, 02 and on.
+
+---
+
+### SpecFaq
+
+```ts
+const SpecFaq: ForwardRefExoticComponent<
+  Omit<HTMLAttributes<HTMLDivElement>, "children"> &
+    object &
+    RefAttributes<HTMLDivElement>
+>;
+```
+
+Questions and answers as native disclosures. It works without JavaScript, and
+every answer stays in the document for search and find-in-page.
+
+---
+
+### SpecDiagram
+
+```ts
+const SpecDiagram: ForwardRefExoticComponent<
+  Omit<HTMLAttributes<HTMLElement>, "children"> &
+    object &
+    RefAttributes<HTMLElement>
+>;
+```
+
+A manual-style parts diagram: tags drawn on the art and a legend that names each
+part. The legend is the accessible text; tags are decorative.
+
+## Functions
+
+### SpecPrintFilter()
+
+```ts
+function SpecPrintFilter(__namedParameters): Element;
+```
+
+The `#caps-print` SVG filter, rendered once per page. It turns 1-bit art (dark
+ink on light paper) into the theme's ink on a transparent ground, with a second
+ink printed slightly off register underneath, like a two-drum risograph. Art
+opts in through the theme's `--caps-print-filter`; the inks come from
+`--caps-print-ink` and `--caps-print-offset`.
+
+#### Parameters
+
+| Parameter           | Type                                            |
+| ------------------- | ----------------------------------------------- |
+| `__namedParameters` | [`SpecPrintFilterProps`](#specprintfilterprops) |
+
+#### Returns
+
+`Element`

package/docs/api/blocks/status-tray.md

@@ -0,0 +1,141 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/caps**](../README.md)
+
+---
+
+[@fungi.computer/caps](../README.md) / blocks/status-tray
+
+# blocks/status-tray
+
+## Type Aliases
+
+### StatusTrayItem
+
+```ts
+type StatusTrayItem = Readonly<{
+  id: string;
+  label: ReactNode;
+  count?: number;
+  tone?: StatusTone;
+  glyph?: StatusGlyph;
+  motion?: StatusMotion;
+  accessibleLabel?: string;
+  title?: ReactNode;
+  actions?: ReactNode;
+  content: ReactNode;
+  disabled?: boolean;
+  after?: ReactNode;
+}>;
+```
+
+One footer readout and the small tray it opens. Semantic data only: the chip's
+finish, the tray's material and the seam between them come from theme tokens
+(`--caps-status-tray-*`), never from a prop.
+
+---
+
+### StatusTrayProps
+
+```ts
+type StatusTrayProps = Omit<HTMLAttributes<HTMLDivElement>, "title"> & object;
+```
+
+Controlled selection and structural slots for a row of footer trays.
+
+#### Type Declaration
+
+| Name             | Type                                           | Description                                                                                                                                                                                                                                                                              |
+| ---------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `items`          | readonly [`StatusTrayItem`](#statustrayitem)[] | Readouts and their tray contents in display order.                                                                                                                                                                                                                                       |
+| `openId`         | `string` \| `null`                             | Which tray is open. The host owns this state.                                                                                                                                                                                                                                            |
+| `onOpenChange()` | (`id`) => `void`                               | Requests a selection change or dismissal.                                                                                                                                                                                                                                                |
+| `leading?`       | `ReactNode`                                    | Leading readouts that never open a tray (connection state, etc.).                                                                                                                                                                                                                        |
+| `trailing?`      | `ReactNode`                                    | Trailing controls after the chips (Send, Expand, …).                                                                                                                                                                                                                                     |
+| `placement?`     | `"housing"` \| `"screen"` \| `"host"`          | Structural seat. `housing` sits on the plastic below a screen; `screen` sits inside a Display as flat, screen-native text (the wiki's screen material rule); `host` means a host's own chrome draws the chips, so only the open tray renders here. The look of each seat is theme-owned. |
+| `align?`         | `"start"` \| `"end"`                           | Which edge the tray aligns to.                                                                                                                                                                                                                                                           |
+| `hostInset?`     | `number`                                       | For `host` placement: where the host's trigger starts, in CSS pixels from this tray's inline start, so the open tray sits above it.                                                                                                                                                      |
+
+## Functions
+
+### StatusTray()
+
+```ts
+function StatusTray(__namedParameters): Element;
+```
+
+A footer row of readout chips; one opens its tray above the row at a time.
+
+#### Parameters
+
+| Parameter           | Type                                  |
+| ------------------- | ------------------------------------- |
+| `__namedParameters` | [`StatusTrayProps`](#statustrayprops) |
+
+#### Returns
+
+`Element`
+
+---
+
+### StatusTrayList()
+
+```ts
+function StatusTrayList(__namedParameters): Element;
+```
+
+A group of tray rows. Precede it with a DataListHeading to label it.
+
+#### Parameters
+
+| Parameter           | Type                                 |
+| ------------------- | ------------------------------------ |
+| `__namedParameters` | `HTMLAttributes`\<`HTMLDivElement`\> |
+
+#### Returns
+
+`Element`
+
+---
+
+### StatusTrayRow()
+
+```ts
+function StatusTrayRow(__namedParameters): Element;
+```
+
+One line: the host's icon, a title, a muted detail that truncates, and a quiet
+text action (a ghost Button) at the end.
+
+#### Parameters
+
+| Parameter           | Type                                                                    |
+| ------------------- | ----------------------------------------------------------------------- |
+| `__namedParameters` | `Omit`\<`HTMLAttributes`\<`HTMLDivElement`\>, `"children"`\> & `object` |
+
+#### Returns
+
+`Element`
+
+---
+
+### StatusTrayNote()
+
+```ts
+function StatusTrayNote(__namedParameters): Element;
+```
+
+A quiet sentence for an empty or unavailable feed. Empty reads "All caught up."
+unless the host says otherwise; unavailable takes a `title`.
+
+#### Parameters
+
+| Parameter                     | Type                                                |
+| ----------------------------- | --------------------------------------------------- |
+| `__namedParameters`           | \{ `children?`: `ReactNode`; `title?`: `string`; \} |
+| `__namedParameters.children?` | `ReactNode`                                         |
+| `__namedParameters.title?`    | `string`                                            |
+
+#### Returns
+
+`Element`

package/docs/api/blocks/upload-queue.md

@@ -0,0 +1,110 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/caps**](../README.md)
+
+---
+
+[@fungi.computer/caps](../README.md) / blocks/upload-queue
+
+# blocks/upload-queue
+
+## Type Aliases
+
+### UploadQueueAction
+
+```ts
+type UploadQueueAction = Readonly<{
+  accessibleLabel: string;
+  label: string;
+}>;
+```
+
+LAW — queue thumbnails are decorative. The adjacent filename is the row's
+accessible file fact; lifecycle status, progress, and actions remain named.
+
+---
+
+### UploadQueueActions
+
+```ts
+type UploadQueueActions = Readonly<{
+  cancel?: UploadQueueAction;
+  remove?: UploadQueueAction;
+  retry?: UploadQueueAction;
+}>;
+```
+
+Caller-owned labels for the row actions that may be shown.
+
+---
+
+### UploadQueueItem
+
+```ts
+type UploadQueueItem = Readonly<{
+  actions: UploadQueueActions;
+  alert?: string;
+  id: string;
+  name: string;
+  preview: UploadQueuePreview;
+  progress: number | null;
+  progressLabel: string;
+  statusLabel: string;
+}>;
+```
+
+Caller-provided upload queue item data.
+
+---
+
+### UploadQueuePreview
+
+```ts
+type UploadQueuePreview =
+  | Readonly<{
+      kind: "file";
+    }>
+  | Readonly<{
+      kind: "image";
+      url: string;
+    }>;
+```
+
+A caller-provided file or image preview for one upload row.
+
+---
+
+### UploadQueueProps
+
+```ts
+type UploadQueueProps = Readonly<{
+  className?: string;
+  items: readonly UploadQueueItem[];
+  onCancel: (id) => Promise<void> | void;
+  onRemove: (id) => void;
+  onRetry: (id) => Promise<void> | void;
+  rowClassName?: string;
+}>;
+```
+
+Props accepted by UploadQueue.
+
+## Functions
+
+### UploadQueue()
+
+```ts
+function UploadQueue(__namedParameters): Element | null;
+```
+
+Product-neutral upload facts and affordances; lifecycle stays with the host.
+
+#### Parameters
+
+| Parameter           | Type                                    |
+| ------------------- | --------------------------------------- |
+| `__namedParameters` | [`UploadQueueProps`](#uploadqueueprops) |
+
+#### Returns
+
+`Element` \| `null`

package/docs/api/components/action-row.md

@@ -0,0 +1,51 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/caps**](../README.md)
+
+---
+
+[@fungi.computer/caps](../README.md) / components/action-row
+
+# components/action-row
+
+## Type Aliases
+
+### ActionRowProps
+
+```ts
+type ActionRowProps = Omit<ButtonProps, "children"> & object;
+```
+
+A full-width, structured action for a data list.
+
+#### Type Declaration
+
+| Name           | Type                       | Description                                                               |
+| -------------- | -------------------------- | ------------------------------------------------------------------------- |
+| `icon?`        | `ReactNode`                | -                                                                         |
+| `label`        | `ReactNode`                | -                                                                         |
+| `description?` | `ReactNode`                | -                                                                         |
+| `trailing?`    | `ReactNode`                | -                                                                         |
+| `density?`     | `"regular"` \| `"compact"` | -                                                                         |
+| `iconSize?`    | `"default"` \| `"lg"`      | `lg` gives a character-sized mark (a sprite head) more room than an icon. |
+| `appearance?`  | `"plain"` \| `"card"`      | `card` molds the row into its own raised plastic card.                    |
+
+## Functions
+
+### ActionRow()
+
+```ts
+function ActionRow(__namedParameters): Element;
+```
+
+Render a clear label, supporting detail, and optional trailing status.
+
+#### Parameters
+
+| Parameter           | Type                                |
+| ------------------- | ----------------------------------- |
+| `__namedParameters` | [`ActionRowProps`](#actionrowprops) |
+
+#### Returns
+
+`Element`