@fungi.computer/caps 0.0.0-stage → 0.0.1

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

@@ -0,0 +1,174 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/caps**](../README.md)
+
+---
+
+[@fungi.computer/caps](../README.md) / components/field-guide
+
+# components/field-guide
+
+## Type Aliases
+
+### KeycapProps
+
+```ts
+type KeycapProps = object & HTMLAttributes<HTMLElement>;
+```
+
+A visible keyboard key from a shortcut or instruction.
+
+#### Type Declaration
+
+| Name       | Type        |
+| ---------- | ----------- |
+| `children` | `ReactNode` |
+
+---
+
+### StatusLedTone
+
+```ts
+type StatusLedTone = "spore" | "mycelium" | "fruiting";
+```
+
+Semantic accent pigments for the static status light.
+
+---
+
+### StatusLedProps
+
+```ts
+type StatusLedProps = object &
+  Omit<HTMLAttributes<HTMLSpanElement>, "children">;
+```
+
+Props accepted by StatusLed.
+
+#### Type Declaration
+
+| Name     | Type                              |
+| -------- | --------------------------------- |
+| `active` | `boolean`                         |
+| `label`  | `string`                          |
+| `tone?`  | [`StatusLedTone`](#statusledtone) |
+
+---
+
+### CartridgeLabelProps
+
+```ts
+type CartridgeLabelProps = object & HTMLAttributes<HTMLElement>;
+```
+
+Props accepted by CartridgeLabel.
+
+#### Type Declaration
+
+| Name        | Type        |
+| ----------- | ----------- |
+| `title`     | `string`    |
+| `subtitle?` | `string`    |
+| `mark?`     | `ReactNode` |
+
+---
+
+### SpecimenLabelProps
+
+```ts
+type SpecimenLabelProps = object & Omit<HTMLAttributes<HTMLElement>, "title">;
+```
+
+Props accepted by SpecimenLabel.
+
+#### Type Declaration
+
+| Name       | Type        | Description                                                                                                                                    |
+| ---------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `plate`    | `string`    | -                                                                                                                                              |
+| `detail`   | `string`    | -                                                                                                                                              |
+| `kind`     | `string`    | -                                                                                                                                              |
+| `number`   | `string`    | -                                                                                                                                              |
+| `title`    | `ReactNode` | -                                                                                                                                              |
+| `summary?` | `ReactNode` | -                                                                                                                                              |
+| `sketch?`  | `boolean`   | Mark the plate number for a pencil circle and the detail for a pencil underline. The ruled CSS marks remain until `enhance/sketch` draws them. |
+
+## Functions
+
+### Keycap()
+
+```ts
+function Keycap(__namedParameters): Element;
+```
+
+The shared field-guide treatment for a keyboard key.
+
+#### Parameters
+
+| Parameter           | Type                          |
+| ------------------- | ----------------------------- |
+| `__namedParameters` | [`KeycapProps`](#keycapprops) |
+
+#### Returns
+
+`Element`
+
+---
+
+### StatusLed()
+
+```ts
+function StatusLed(__namedParameters): Element;
+```
+
+A static, labelled indicator using the current field-guide pigment tokens.
+
+#### Parameters
+
+| Parameter           | Type                                |
+| ------------------- | ----------------------------------- |
+| `__namedParameters` | [`StatusLedProps`](#statusledprops) |
+
+#### Returns
+
+`Element`
+
+---
+
+### CartridgeLabel()
+
+```ts
+function CartridgeLabel(__namedParameters): Element;
+```
+
+A ruled, token-backed printed label for a physical game cartridge.
+
+#### Parameters
+
+| Parameter           | Type                                          |
+| ------------------- | --------------------------------------------- |
+| `__namedParameters` | [`CartridgeLabelProps`](#cartridgelabelprops) |
+
+#### Returns
+
+`Element`
+
+---
+
+### SpecimenLabel()
+
+```ts
+function SpecimenLabel(__namedParameters): Element;
+```
+
+A caption, catalogue line, title, and note for a specimen illustration.
+
+#### Parameters
+
+| Parameter           | Type                                        |
+| ------------------- | ------------------------------------------- |
+| `__namedParameters` | [`SpecimenLabelProps`](#specimenlabelprops) |
+
+#### Returns
+
+`Element`

package/docs/api/components/field.md

@@ -0,0 +1,252 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/caps**](../README.md)
+
+---
+
+[@fungi.computer/caps](../README.md) / components/field
+
+# components/field
+
+## Type Aliases
+
+### FormFooterProps
+
+```ts
+type FormFooterProps = object & HTMLAttributes<HTMLElement>;
+```
+
+Props accepted by FormFooter.
+
+#### Type Declaration
+
+| Name       | Type                   | Description                                                                              |
+| ---------- | ---------------------- | ---------------------------------------------------------------------------------------- |
+| `error?`   | `ReactNode`            | The submit-time error, announced above the actions.                                      |
+| `layout?`  | `"end"` \| `"stretch"` | `end` right-aligns actions; `stretch` stacks full-width actions for single-column cards. |
+| `status?`  | `ReactNode`            | Quiet state opposite the actions (role="status"), such as a Status LED reading "Saved".  |
+| `divider?` | `boolean`              | Draws the rule above the footer; short inline forms leave it off.                        |
+
+---
+
+### FormProps
+
+```ts
+type FormProps = object & FormHTMLAttributes<HTMLFormElement>;
+```
+
+Props accepted by Form.
+
+#### Type Declaration
+
+| Name    | Type      | Description                                             |
+| ------- | --------- | ------------------------------------------------------- |
+| `busy?` | `boolean` | Disables every control while a submission is in flight. |
+
+---
+
+### FormSectionProps
+
+```ts
+type FormSectionProps = object & Omit<HTMLAttributes<HTMLElement>, "title">;
+```
+
+Props accepted by FormSection.
+
+#### Type Declaration
+
+| Name           | Type              | Description                            |
+| -------------- | ----------------- | -------------------------------------- |
+| `title`        | `ReactNode`       | -                                      |
+| `description?` | `ReactNode`       | -                                      |
+| `level?`       | `2` \| `3` \| `4` | Heading level inside the page outline. |
+| `children`     | `ReactNode`       | -                                      |
+
+---
+
+### FieldSetProps
+
+```ts
+type FieldSetProps = object & FieldsetHTMLAttributes<HTMLFieldSetElement>;
+```
+
+Props accepted by FieldSet.
+
+#### Type Declaration
+
+| Name           | Type        | Description                                                       |
+| -------------- | ----------- | ----------------------------------------------------------------- |
+| `legend`       | `ReactNode` | -                                                                 |
+| `description?` | `ReactNode` | -                                                                 |
+| `error?`       | `ReactNode` | The group's announced error, such as "Choose at least one right". |
+| `children`     | `ReactNode` | -                                                                 |
+
+---
+
+### FieldProps
+
+```ts
+type FieldProps = object & HTMLAttributes<HTMLDivElement>;
+```
+
+Props accepted by Field.
+
+#### Type Declaration
+
+| Name           | Type                                         | Description                                                                                                                                                      |
+| -------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `children`     | `ReactNode`                                  | -                                                                                                                                                                |
+| `description?` | `ReactNode`                                  | -                                                                                                                                                                |
+| `error?`       | `ReactNode`                                  | -                                                                                                                                                                |
+| `icon?`        | `ReactNode`                                  | A decorative marker, such as a Sigil or App icon, before the label. It is hidden from assistive tech; the label stays the control's name.                        |
+| `label?`       | `ReactNode`                                  | -                                                                                                                                                                |
+| `orientation?` | `"horizontal"` \| `"inline"` \| `"vertical"` | `vertical` stacks label, control and error; `horizontal` puts the control opposite its copy (settings rows); `inline` puts a checkbox or switch before its copy. |
+| `optional?`    | `boolean`                                    | Marks an optional field in a mostly required form.                                                                                                               |
+| `readout?`     | `boolean`                                    | The child is a read-only readout, such as a Status, not a control: the label names the row and nothing is wired to the child.                                    |
+| `required?`    | `boolean`                                    | -                                                                                                                                                                |
+
+---
+
+### NumberFieldProps
+
+```ts
+type NumberFieldProps = object &
+  Omit<
+    InputHTMLAttributes<HTMLInputElement>,
+    "defaultValue" | "max" | "min" | "onChange" | "step" | "type" | "value"
+  >;
+```
+
+Props accepted by NumberField.
+
+#### Type Declaration
+
+| Name               | Type                | Description                                                              |
+| ------------------ | ------------------- | ------------------------------------------------------------------------ |
+| `value?`           | `number` \| `null`  | Controlled value; `null` is empty.                                       |
+| `defaultValue?`    | `number` \| `null`  | -                                                                        |
+| `onValueChange()?` | (`value`) => `void` | Called with each committed value, already clamped to min/max.            |
+| `min?`             | `number`            | -                                                                        |
+| `max?`             | `number`            | -                                                                        |
+| `step?`            | `number`            | Arrow keys and the − / + keys move by `step`; Page Up/Down by ten steps. |
+| `unit?`            | `ReactNode`         | A short unit readout after the value, such as "min" or "GB".             |
+| `wrap?`            | `boolean`           | Cycle from max back to min (and back) instead of stopping at the ends.   |
+| `invalid?`         | `boolean`           | -                                                                        |
+| `decrementLabel?`  | `string`            | Accessible names for the − / + keys.                                     |
+| `incrementLabel?`  | `string`            | -                                                                        |
+
+## Variables
+
+### Form
+
+```ts
+const Form: ForwardRefExoticComponent<
+  object & FormHTMLAttributes<HTMLFormElement> & RefAttributes<HTMLFormElement>
+>;
+```
+
+A form with Caps' field rhythm. While `busy`, its fieldset disables every
+control and the form reports `aria-busy`; validation stays with the caller.
+
+---
+
+### FormSection
+
+```ts
+const FormSection: ForwardRefExoticComponent<
+  object &
+    Omit<HTMLAttributes<HTMLElement>, "title"> &
+    RefAttributes<HTMLElement>
+>;
+```
+
+A titled group of fields; consecutive sections share one quiet rule.
+
+---
+
+### FieldSet
+
+```ts
+const FieldSet: ForwardRefExoticComponent<
+  object &
+    FieldsetHTMLAttributes<HTMLFieldSetElement> &
+    RefAttributes<HTMLFieldSetElement>
+>;
+```
+
+A legend-named group of related choices, such as a list of inline checkbox
+Fields. `disabled` disables every control inside.
+
+---
+
+### Field
+
+```ts
+const Field: ForwardRefExoticComponent<
+  object & HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement>
+>;
+```
+
+A labelled form-field layout that renders caller-provided control and supporting
+content.
+
+---
+
+### NumberField
+
+```ts
+const NumberField: ForwardRefExoticComponent<
+  object &
+    Omit<
+      InputHTMLAttributes<HTMLInputElement>,
+      "defaultValue" | "onChange" | "type" | "value" | "max" | "min" | "step"
+    > &
+    RefAttributes<HTMLInputElement>
+>;
+```
+
+A number spinbutton: a native `input type="number"` between − and + keys, with
+the value as a mono readout. Field wires its label, description and error to the
+input. The `caps-number-field-*` parts are stable so a context such as a Screen
+can redraw them; the semantics stay here.
+
+## Functions
+
+### FieldError()
+
+```ts
+function FieldError(__namedParameters): Element;
+```
+
+An announced error that takes no space when absent and collapses smoothly.
+
+#### Parameters
+
+| Parameter           | Type                                 |
+| ------------------- | ------------------------------------ |
+| `__namedParameters` | `HTMLAttributes`\<`HTMLDivElement`\> |
+
+#### Returns
+
+`Element`
+
+---
+
+### FormFooter()
+
+```ts
+function FormFooter(__namedParameters): Element;
+```
+
+A form's stationary action area. Put exactly one primary Button last; every
+other action is `ghost` or `outline`.
+
+#### Parameters
+
+| Parameter           | Type                                  |
+| ------------------- | ------------------------------------- |
+| `__namedParameters` | [`FormFooterProps`](#formfooterprops) |
+
+#### Returns
+
+`Element`

package/docs/api/components/game-feedback.md

@@ -0,0 +1,157 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/caps**](../README.md)
+
+---
+
+[@fungi.computer/caps](../README.md) / components/game-feedback
+
+# components/game-feedback
+
+## Type Aliases
+
+### FeedbackKind
+
+```ts
+type FeedbackKind = "confirm" | "deny" | "hit" | "gain";
+```
+
+What happened: an order taken, an order refused, a hit, or something gained.
+
+---
+
+### FeedbackLayerProps
+
+```ts
+type FeedbackLayerProps = HTMLAttributes<HTMLDivElement> & object;
+```
+
+Props accepted by FeedbackLayer.
+
+#### Type Declaration
+
+| Name      | Type      | Description                                                   |
+| --------- | --------- | ------------------------------------------------------------- |
+| `paused?` | `boolean` | Freeze every mark where it is, e.g. while the game is paused. |
+
+---
+
+### FeedbackMarkProps
+
+```ts
+type FeedbackMarkProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> &
+  object;
+```
+
+Props accepted by FeedbackMark.
+
+#### Type Declaration
+
+| Name      | Type                            | Description                                                         |
+| --------- | ------------------------------- | ------------------------------------------------------------------- |
+| `kind`    | [`FeedbackKind`](#feedbackkind) | -                                                                   |
+| `x`       | `number`                        | Anchor in layer pixels.                                             |
+| `y`       | `number`                        | -                                                                   |
+| `label?`  | `ReactNode`                     | A short note, such as the host's refusal reason.                    |
+| `amount?` | `number`                        | A floating number, drawn signed in outlined pixel numerals.         |
+| `life?`   | `number`                        | Total life in milliseconds; the host removes the mark when it ends. |
+
+---
+
+### FeedbackWordTone
+
+```ts
+type FeedbackWordTone = "impact" | "gun" | "mech" | "wet" | "quiet" | "bite";
+```
+
+A generic feedback tone: game-neutral, so any cartridge can author with it.
+`bite` is for a creature's bite, not any one game's monster.
+
+---
+
+### FeedbackWordSize
+
+```ts
+type FeedbackWordSize = "s" | "m" | "l" | "xl";
+```
+
+Named display sizes for game feedback words.
+
+---
+
+### FeedbackWordAccent
+
+```ts
+type FeedbackWordAccent = "jaw";
+```
+
+A two-phase accent that plays alongside the word: `jaw` claps two wedges shut
+once, then eases back open.
+
+---
+
+### FeedbackWordMarkProps
+
+```ts
+type FeedbackWordMarkProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> &
+  object;
+```
+
+Props accepted by FeedbackWordMark.
+
+#### Type Declaration
+
+| Name      | Type                                        | Description                                                           |
+| --------- | ------------------------------------------- | --------------------------------------------------------------------- |
+| `text`    | `string`                                    | Comic lettering, at most 12 characters (e.g. "CRUNCH", "BLAM").       |
+| `x`       | `number`                                    | Anchor in layer pixels; the word sits bottom-centre above this point. |
+| `y`       | `number`                                    | -                                                                     |
+| `tone?`   | [`FeedbackWordTone`](#feedbackwordtone)     | -                                                                     |
+| `size?`   | [`FeedbackWordSize`](#feedbackwordsize)     | -                                                                     |
+| `accent?` | [`FeedbackWordAccent`](#feedbackwordaccent) | -                                                                     |
+| `life?`   | `number`                                    | Total life in milliseconds; the host removes the mark when it ends.   |
+
+## Variables
+
+### FeedbackLayer
+
+```ts
+const FeedbackLayer: ForwardRefExoticComponent<
+  HTMLAttributes<HTMLDivElement> & object & RefAttributes<HTMLDivElement>
+>;
+```
+
+A click-through overlay for game feedback, placed over the world by the host.
+Marks inside it are positioned in the layer's own pixels.
+
+---
+
+### FeedbackMark
+
+```ts
+const FeedbackMark: ForwardRefExoticComponent<
+  Omit<HTMLAttributes<HTMLDivElement>, "children"> &
+    object &
+    RefAttributes<HTMLDivElement>
+>;
+```
+
+One piece of game feedback at a point: a stepped flash ring, an optional
+floating number and an optional note. Reduced motion keeps the ring and note
+still and only fades them.
+
+---
+
+### FeedbackWordMark
+
+```ts
+const FeedbackWordMark: ForwardRefExoticComponent<
+  Omit<HTMLAttributes<HTMLDivElement>, "children"> &
+    object &
+    RefAttributes<HTMLDivElement>
+>;
+```
+
+One comic sound word at a point: punchy lettering that pops in with a little
+overshoot, drifts up, and fades. Reduced motion keeps it still at full strength
+until the host removes it.