@fungi.computer/caps 0.0.0-stage → 0.0.1

package/docs/api/components/combobox.md

@@ -0,0 +1,303 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/caps**](../README.md)
+
+---
+
+[@fungi.computer/caps](../README.md) / components/combobox
+
+# components/combobox
+
+## Type Aliases
+
+### ComboboxItemState
+
+```ts
+type ComboboxItemState = object;
+```
+
+Intrinsic focus and selection state supplied when rendering a Combobox item.
+
+#### Properties
+
+##### active
+
+```ts
+active: boolean;
+```
+
+##### disabled
+
+```ts
+disabled: boolean;
+```
+
+##### selected
+
+```ts
+selected: boolean;
+```
+
+---
+
+### ComboboxProps
+
+```ts
+type ComboboxProps<T> = ComboboxBaseProps<T> &
+  | ComboboxInlineProps
+| ComboboxPopupProps & ComboboxValueProps<T>;
+```
+
+Props accepted by Combobox.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+---
+
+### ComboboxBaseProps
+
+```ts
+type ComboboxBaseProps<T> = object &
+  Omit<React.HTMLAttributes<HTMLDivElement>, "defaultValue" | "value">;
+```
+
+Props shared by every Combobox mode: item shape, rendering, and field wiring.
+
+#### Type Declaration
+
+| Name                | Type                                                                                       | Description                                                                     |
+| ------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
+| `activeTone?`       | `"neutral"` \| `"primary"`                                                                 | Color intent for the locally active option.                                     |
+| `container?`        | `BasePopover.Portal.Props`\[`"container"`\]                                                | Native portal destination. Use an unclipped themed container for nested themes. |
+| `contentClassName?` | `string`                                                                                   | -                                                                               |
+| `emptyMessage?`     | `ReactNode`                                                                                | -                                                                               |
+| `getKey()`          | (`item`) => `string`                                                                       | Returns the stable identity used to track and compare items.                    |
+| `getLabel()`        | (`item`) => `string`                                                                       | Returns the text shown for an item in the trigger and the list.                 |
+| `getSearchText()?`  | (`item`) => `string`                                                                       | Returns the text matched against caller input; defaults to the item's label.    |
+| `groupBy()?`        | (`item`) => `string`                                                                       | Returns the heading an item is grouped under in the list.                       |
+| `id?`               | `string`                                                                                   | Identifies the popup trigger or inline input for native label association.      |
+| `inputProps?`       | `Omit`\<`React.InputHTMLAttributes`\<`HTMLInputElement`\>, `"defaultValue"` \| `"value"`\> | -                                                                               |
+| `inputRef?`         | `React.Ref`\<`HTMLInputElement`\>                                                          | -                                                                               |
+| `rootRef?`          | `React.Ref`\<`HTMLDivElement`\>                                                            | Receives the selection control's root div.                                      |
+| `isDisabled()?`     | (`item`) => `boolean`                                                                      | Returns whether an item is unselectable.                                        |
+| `items`             | readonly `T`[]                                                                             | -                                                                               |
+| `placeholder?`      | `string`                                                                                   | -                                                                               |
+| `renderItem()?`     | (`item`, `active`, `state`) => `ReactNode`                                                 | Renders one item's content; defaults to its label.                              |
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+---
+
+### ComboboxInlineProps
+
+```ts
+type ComboboxInlineProps = object;
+```
+
+Combobox mode flags for the inline (always-expanded, no popup trigger) layout.
+
+#### Properties
+
+##### defaultOpen?
+
+```ts
+optional defaultOpen?: never;
+```
+
+##### onOpenChange?
+
+```ts
+optional onOpenChange?: never;
+```
+
+Popup visibility callbacks do not apply to inline choices.
+
+##### open?
+
+```ts
+optional open?: never;
+```
+
+##### trigger?
+
+```ts
+optional trigger?: never;
+```
+
+##### triggerRef?
+
+```ts
+optional triggerRef?: never;
+```
+
+---
+
+### ComboboxPopupProps
+
+```ts
+type ComboboxPopupProps =
+  | {
+      defaultOpen?: boolean;
+      onOpenChange?: (open) => void;
+      open?: never;
+      trigger: ReactElement<ButtonHTMLAttributes<HTMLButtonElement>>;
+      triggerRef?: React.Ref<HTMLButtonElement>;
+    }
+  | {
+      defaultOpen?: never;
+      onOpenChange?: (open) => void;
+      open: boolean;
+      trigger: ReactElement<ButtonHTMLAttributes<HTMLButtonElement>>;
+      triggerRef?: React.Ref<HTMLButtonElement>;
+    };
+```
+
+Combobox mode flags for the popup layout, either caller-controlled or
+uncontrolled open state.
+
+#### Union Members
+
+##### Type Literal
+
+```ts
+{
+  defaultOpen?: boolean;
+  onOpenChange?: (open) => void;
+  open?: never;
+  trigger: ReactElement<ButtonHTMLAttributes<HTMLButtonElement>>;
+  triggerRef?: React.Ref<HTMLButtonElement>;
+}
+```
+
+| Name              | Type                                                            | Description                                  |
+| ----------------- | --------------------------------------------------------------- | -------------------------------------------- |
+| `defaultOpen?`    | `boolean`                                                       | -                                            |
+| `onOpenChange()?` | (`open`) => `void`                                              | Called after the popup's open state changes. |
+| `open?`           | `never`                                                         | -                                            |
+| `trigger`         | `ReactElement`\<`ButtonHTMLAttributes`\<`HTMLButtonElement`\>\> | -                                            |
+| `triggerRef?`     | `React.Ref`\<`HTMLButtonElement`\>                              | -                                            |
+
+---
+
+##### Type Literal
+
+```ts
+{
+  defaultOpen?: never;
+  onOpenChange?: (open) => void;
+  open: boolean;
+  trigger: ReactElement<ButtonHTMLAttributes<HTMLButtonElement>>;
+  triggerRef?: React.Ref<HTMLButtonElement>;
+}
+```
+
+| Name              | Type                                                            | Description                                  |
+| ----------------- | --------------------------------------------------------------- | -------------------------------------------- |
+| `defaultOpen?`    | `never`                                                         | -                                            |
+| `onOpenChange()?` | (`open`) => `void`                                              | Called after the popup's open state changes. |
+| `open`            | `boolean`                                                       | -                                            |
+| `trigger`         | `ReactElement`\<`ButtonHTMLAttributes`\<`HTMLButtonElement`\>\> | -                                            |
+| `triggerRef?`     | `React.Ref`\<`HTMLButtonElement`\>                              | -                                            |
+
+---
+
+### ComboboxValueProps
+
+```ts
+type ComboboxValueProps<T> =
+  |
+  | {
+  defaultValue?: never;
+  value: null | string;
+}
+  | {
+  defaultValue?: null | string;
+  value?: never;
+} & object
+  | {
+  multiple: true;
+  value: readonly string[];
+  defaultValue?: never;
+  onValueChange?: (value, items) => void;
+};
+```
+
+Combobox selection shape: single or multiple, controlled or uncontrolled.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+#### Union Members
+
+\| \{ `defaultValue?`: `never`; `value`: `null` \| `string`; \} \| \{
+`defaultValue?`: `null` \| `string`; `value?`: `never`; \} & `object`
+
+---
+
+##### Type Literal
+
+```ts
+{
+  multiple: true;
+  value: readonly string[];
+  defaultValue?: never;
+  onValueChange?: (value, items) => void;
+}
+```
+
+| Name               | Type                         | Description                                    |
+| ------------------ | ---------------------------- | ---------------------------------------------- |
+| `multiple`         | `true`                       | -                                              |
+| `value`            | readonly `string`[]          | -                                              |
+| `defaultValue?`    | `never`                      | -                                              |
+| `onValueChange()?` | (`value`, `items`) => `void` | Called with the newly selected keys and items. |
+
+## Variables
+
+### ComboboxTrigger
+
+```ts
+const ComboboxTrigger: ForwardRefExoticComponent<
+  ButtonHTMLAttributes<HTMLButtonElement> & RefAttributes<HTMLButtonElement>
+>;
+```
+
+The same molded field face as Select, for caller-owned selection summaries.
+
+## Functions
+
+### Combobox()
+
+```ts
+function Combobox<T>(props): Element;
+```
+
+A searchable selection primitive with caller-owned values and intrinsic keyboard
+navigation.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+#### Parameters
+
+| Parameter | Type                                     |
+| --------- | ---------------------------------------- |
+| `props`   | [`ComboboxProps`](#comboboxprops)\<`T`\> |
+
+#### Returns
+
+`Element`

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

@@ -0,0 +1,58 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/caps**](../README.md)
+
+---
+
+[@fungi.computer/caps](../README.md) / components/confirm-action
+
+# components/confirm-action
+
+## Type Aliases
+
+### ConfirmActionProps
+
+```ts
+type ConfirmActionProps = object &
+  | {
+  mode: "hold";
+  phrase?: never;
+}
+  | {
+  mode: "type";
+  phrase: string;
+};
+```
+
+A deliberate hold, or an exact phrase before a destructive action.
+
+#### Type Declaration
+
+| Name           | Type                      | Description                                                                        |
+| -------------- | ------------------------- | ---------------------------------------------------------------------------------- |
+| `label`        | `string`                  | The action's trigger label and dialog title.                                       |
+| `confirmLabel` | `string`                  | The destructive key's label (and the hold gesture's instruction).                  |
+| `onConfirm()`  | () => `Promise`\<`void`\> | Resolve on success; reject on failure. The component prevents concurrent calls.    |
+| `error?`       | `string`                  | Caller-owned, safe-to-display failure copy; rejection details are never displayed. |
+
+## Functions
+
+### ConfirmAction()
+
+```ts
+function ConfirmAction(__namedParameters): Element;
+```
+
+Confirms once per gesture, owns pending/result feedback, and keeps failed
+confirmations available for retry. Type mode closes on success and restores
+focus through Dialog. A pending action cannot be dismissed or cancelled.
+
+#### Parameters
+
+| Parameter           | Type                                        |
+| ------------------- | ------------------------------------------- |
+| `__namedParameters` | [`ConfirmActionProps`](#confirmactionprops) |
+
+#### Returns
+
+`Element`

package/docs/api/components/copy-field.md

@@ -0,0 +1,106 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/caps**](../README.md)
+
+---
+
+[@fungi.computer/caps](../README.md) / components/copy-field
+
+# components/copy-field
+
+## Type Aliases
+
+### CopyFieldTokenKind
+
+```ts
+type CopyFieldTokenKind = "text" | "tag" | "attribute" | "string";
+```
+
+The colour role of one run of text in a block's code.
+
+---
+
+### CopyFieldToken
+
+```ts
+type CopyFieldToken = object;
+```
+
+One run of a block's code; the runs, joined, are the copied value.
+
+#### Properties
+
+##### kind
+
+```ts
+kind: CopyFieldTokenKind;
+```
+
+##### text
+
+```ts
+text: string;
+```
+
+---
+
+### CopyFieldProps
+
+```ts
+type CopyFieldProps = object &
+  | {
+  value: string;
+  fieldLabel?: undefined;
+  displayValue?: undefined;
+  layout?: "inline";
+  title?: undefined;
+  tokens?: undefined;
+}
+  | {
+  value: string;
+  fieldLabel: string;
+  displayValue?: string;
+  layout?: "inline";
+  title?: undefined;
+  tokens?: undefined;
+}
+  | object &
+  | {
+  value: string;
+  tokens?: undefined;
+}
+  | {
+  tokens: readonly CopyFieldToken[];
+  value?: undefined;
+} & Omit<HTMLAttributes<HTMLElement>, "children" | "title">;
+```
+
+Props accepted by CopyField.
+
+#### Type Declaration
+
+| Name     | Type     | Description                                                 |
+| -------- | -------- | ----------------------------------------------------------- |
+| `label?` | `string` | Copy action text; the code presentations default to "Copy". |
+
+## Functions
+
+### CopyField()
+
+```ts
+function CopyField(__namedParameters): Element;
+```
+
+A value with an explicit copy action and visible outcome: wrapped code by
+default, a labelled read-only input when `fieldLabel` is given, or a titled code
+panel with `layout="block"`.
+
+#### Parameters
+
+| Parameter           | Type                                |
+| ------------------- | ----------------------------------- |
+| `__namedParameters` | [`CopyFieldProps`](#copyfieldprops) |
+
+#### Returns
+
+`Element`

package/docs/api/components/count-badge.md

@@ -0,0 +1,39 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/caps**](../README.md)
+
+---
+
+[@fungi.computer/caps](../README.md) / components/count-badge
+
+# components/count-badge
+
+## Type Aliases
+
+### CountBadgeProps
+
+```ts
+type CountBadgeProps = object & HTMLAttributes<HTMLSpanElement>;
+```
+
+Props accepted by CountBadge.
+
+#### Type Declaration
+
+| Name     | Type                       | Description                                                               |
+| -------- | -------------------------- | ------------------------------------------------------------------------- |
+| `count`  | `ReactNode`                | -                                                                         |
+| `tone?`  | `"neutral"` \| `"warning"` | Semantic count emphasis; warnings call attention to items needing action. |
+| `label?` | `ReactNode`                | -                                                                         |
+
+## Variables
+
+### CountBadge
+
+```ts
+const CountBadge: ForwardRefExoticComponent<
+  object & HTMLAttributes<HTMLSpanElement> & RefAttributes<HTMLSpanElement>
+>;
+```
+
+A badge displaying a caller-provided count and label.

package/docs/api/components/cover-pattern.md

@@ -0,0 +1,43 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/caps**](../README.md)
+
+---
+
+[@fungi.computer/caps](../README.md) / components/cover-pattern
+
+# components/cover-pattern
+
+## Type Aliases
+
+### CoverPatternProps
+
+```ts
+type CoverPatternProps = object &
+  Omit<SVGAttributes<SVGSVGElement>, "children" | "role" | "aria-label">;
+```
+
+Props accepted by CoverPattern.
+
+#### Type Declaration
+
+| Name     | Type     | Description                                                                       |
+| -------- | -------- | --------------------------------------------------------------------------------- |
+| `seed`   | `string` | Stable identity that picks the garden; the same seed draws the same one.          |
+| `label?` | `string` | Names the pattern for assistive technology; without it the pattern is decorative. |
+
+## Variables
+
+### CoverPattern
+
+```ts
+const CoverPattern: ForwardRefExoticComponent<
+  object &
+    Omit<SVGAttributes<SVGSVGElement>, "role" | "aria-label" | "children"> &
+    RefAttributes<SVGSVGElement>
+>;
+```
+
+A garden of mushrooms over a thread of mycelium: the stand-in for a cover that
+has no picture yet. It fills its box, holds no text, and takes every color from
+the theme.

package/docs/api/components/data-list.md

@@ -0,0 +1,80 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/caps**](../README.md)
+
+---
+
+[@fungi.computer/caps](../README.md) / components/data-list
+
+# components/data-list
+
+## Type Aliases
+
+### DataListProps
+
+```ts
+type DataListProps = HTMLAttributes<HTMLUListElement> & object;
+```
+
+Props accepted by DataList.
+
+#### Type Declaration
+
+| Name       | Type                       |
+| ---------- | -------------------------- |
+| `density?` | `"regular"` \| `"compact"` |
+
+---
+
+### DataListHeadingProps
+
+```ts
+type DataListHeadingProps = HTMLAttributes<HTMLHeadingElement> & object;
+```
+
+Props accepted by DataListHeading.
+
+#### Type Declaration
+
+| Name     | Type        | Description                                         |
+| -------- | ----------- | --------------------------------------------------- |
+| `level?` | `2` \| `3`  | Heading level; the host keeps its document outline. |
+| `aside?` | `ReactNode` | Optional trailing count or status, such as a Badge. |
+
+## Variables
+
+### DataList
+
+```ts
+const DataList: ForwardRefExoticComponent<
+  HTMLAttributes<HTMLUListElement> & object & RefAttributes<HTMLUListElement>
+>;
+```
+
+A list wrapper for caller-provided rows.
+
+---
+
+### DataRow
+
+```ts
+const DataRow: ForwardRefExoticComponent<
+  LiHTMLAttributes<HTMLLIElement> & RefAttributes<HTMLLIElement>
+>;
+```
+
+A list row for a caller-provided label and value.
+
+---
+
+### DataListHeading
+
+```ts
+const DataListHeading: ForwardRefExoticComponent<
+  HTMLAttributes<HTMLHeadingElement> &
+    object &
+    RefAttributes<HTMLHeadingElement>
+>;
+```
+
+A quiet small-caps section label that groups the rows below it.