@tempoxyz/ds 0.3.10 → 0.3.13

package/dist/docs/product/components/textarea.md

@@ -0,0 +1,352 @@
+# Textarea
+
+A multi-line text field.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Textarea.tsx)
+
+## Overview
+
+A textarea is a native `<textarea>` registered as the control of its enclosing field. Set `rows` to the expected length of the answer.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Field, style, Textarea } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.grid()}>
+      <Field.Root>
+        <Field.Label>Notes</Field.Label>
+        <Textarea placeholder="Add a note" />
+      </Field.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const grid = style({
+    alignItems: 'start',
+    display: 'grid',
+    gap: '24',
+    gridTemplateColumns: 'repeat(auto-fill, minmax(min(280px, 100%), 1fr)) !custom',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Textarea/Basic.tsx)
+
+### Variant
+
+Set `variant` to `default` (default) or `outlined`, which draws a 1px line instead of the fill.
+
+```tsx
+import { Field, style, Textarea } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.grid()}>
+      <Field.Root>
+        <Field.Label>Notes</Field.Label>
+        <Textarea defaultValue="Paid in full" />
+      </Field.Root>
+      <Field.Root>
+        <Field.Label>Memo</Field.Label>
+        <Textarea defaultValue="Rent for May" variant="outlined" />
+      </Field.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const grid = style({
+    alignItems: 'start',
+    display: 'grid',
+    gap: '24',
+    gridTemplateColumns: 'repeat(auto-fill, minmax(min(280px, 100%), 1fr)) !custom',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Textarea/Variant.tsx)
+
+### Resize
+
+Set `resize` to `vertical` (default), `none`, or `auto`, which grows with the content.
+
+```tsx
+import { Field, style, Textarea } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.grid()}>
+      <Field.Root>
+        <Field.Label>Grows with content</Field.Label>
+        <Textarea resize="auto" rows={1} />
+      </Field.Root>
+      <Field.Root>
+        <Field.Label>Fixed height</Field.Label>
+        <Textarea placeholder="Add a note" resize="none" />
+      </Field.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const grid = style({
+    alignItems: 'start',
+    display: 'grid',
+    gap: '24',
+    gridTemplateColumns: 'repeat(auto-fill, minmax(min(280px, 100%), 1fr)) !custom',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Textarea/Resize.tsx)
+
+### Invalid
+
+Set `invalid` on `Field.Root` and add a `Field.Error` to show a validation message.
+
+```tsx
+import { Field, style, Textarea } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.grid()}>
+      <Field.Root invalid>
+        <Field.Label>Notes</Field.Label>
+        <Textarea defaultValue="Too short" />
+        <Field.Error match>Write at least 20 characters.</Field.Error>
+      </Field.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const grid = style({
+    alignItems: 'start',
+    display: 'grid',
+    gap: '24',
+    gridTemplateColumns: 'repeat(auto-fill, minmax(min(280px, 100%), 1fr)) !custom',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Textarea/Invalid.tsx)
+
+### Disabled
+
+Set `disabled` on `Field.Root` to disable the textarea.
+
+```tsx
+import { Field, style, Textarea } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.grid()}>
+      <Field.Root disabled>
+        <Field.Label>Disabled</Field.Label>
+        <Textarea defaultValue="Locked" />
+      </Field.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const grid = style({
+    alignItems: 'start',
+    display: 'grid',
+    gap: '24',
+    gridTemplateColumns: 'repeat(auto-fill, minmax(min(280px, 100%), 1fr)) !custom',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Textarea/Disabled.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Textarea } from '@tempoxyz/ds'
+
+<Textarea />
+```
+
+## Guidelines
+
+### When to Use
+
+* Collect free text that may run over one line, such as a support message, a refund reason, or notes on a contact.
+* Describe a new webhook, API key, or other object when a name alone isn't enough.
+
+### When Not to Use
+
+* Use [TextInput](text-input.md) for single-line values, even long ones such as a 0x address or a webhook URL.
+* Use [Snippet](snippet.md) for a command or JSON payload to copy, not edit.
+* Use [Select](select.md), [RadioGroup](radio-group.md), or [Checkbox](checkbox.md) when the answer fits a known set of options.
+
+### Set Rows to the Expected Length
+
+`rows` sets the starting height and defaults to 3. Size it to a typical answer.
+
+**Do:** Give a long answer a few rows to start.
+
+```tsx
+/**
+ * Do example for "Set Rows to the Expected Length" on the Textarea page.
+ * Give a long answer a few rows to start.
+ * @module
+ */
+import { Field, style, Textarea } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <Field.Label>Describe the issue</Field.Label>
+      <Textarea rows={4} />
+      <Field.Description>Include the transaction hash if you have one.</Field.Description>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })
+}
+```
+
+**Don't:** Use a one-row textarea for a long answer. It reads as a single-line input.
+
+```tsx
+/**
+ * Don't example for "Set Rows to the Expected Length" on the Textarea page.
+ * Don't use a one-row textarea for a long answer. It reads as a single-line input.
+ * @module
+ */
+import { Field, style, Textarea } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <Field.Label>Describe the issue</Field.Label>
+      <Textarea resize="none" rows={1} />
+      <Field.Description>Include the transaction hash if you have one.</Field.Description>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })
+}
+```
+
+### Let the Box Grow
+
+* **Drag to Resize (vertical):** The default. People drag the corner of the box down to make it taller.
+* **Grow With Content (auto):** Grows through `field-sizing`. Other browsers keep the `rows` height.
+* **Fixed Height (none):** Only when the layout can't absorb a taller box, such as a fixed-height card.
+
+### Put Requirements in the Description
+
+State what to include and any length limit in `Field.Description`, such as Up to 500 characters. There is no built-in character count.
+
+Native `maxLength` cuts off pasted text without a warning. To keep pasted text, check the length in `validate` on `Field.Root` and explain the limit in `Field.Error`.
+
+**Do:** State the limit before people start to write.
+
+```tsx
+/**
+ * Do example for "Put Requirements in the Description" on the Textarea page.
+ * State the limit before people start to write.
+ * @module
+ */
+import { Field, style, Textarea } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root {...styles.field()}>
+      <Field.Label>Reason for refund</Field.Label>
+      <Textarea defaultValue="Sent 250.00 USDC to the wrong address." rows={3} />
+      <Field.Description>Up to 500 characters.</Field.Description>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })
+}
+```
+
+**Don't:** Reveal the limit only in an error.
+
+```tsx
+/**
+ * Don't example for "Put Requirements in the Description" on the Textarea page.
+ * Don't reveal the limit only in an error.
+ * @module
+ */
+import { Field, style, Textarea } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root invalid {...styles.field()}>
+      <Field.Label>Reason for refund</Field.Label>
+      <Textarea defaultValue="Sent 250.00 USDC to the wrong address." rows={3} />
+      <Field.Error match>Your message is too long.</Field.Error>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })
+}
+```
+
+## Accessibility
+
+`Textarea` renders a native `<textarea>` registered as the control of its `Field.Root`.
+
+### Semantics
+
+* **Textarea (textbox):** A native textarea, announced by screen readers as a multi-line text box.
+* **Wiring (aria-describedby):** In a field, the label names it, and the field description and any shown error describe it.
+* **Invalid State (aria-invalid):** Marks the control invalid and draws a red border. Explain the problem in `Field.Error`.
+* **Disabled State (disabled):** Disables the native textarea, removes it from the tab order, and dims its label.
+
+### Keyboard
+
+* **Move Focus In and Out (Tab):** Moves focus to the textarea, and out of it again.
+* **Insert a New Line (Enter):** Inserts a new line. It does not submit the form.
+
+All other keys follow the native textarea.
+
+### Your Responsibilities
+
+* **Label the Textarea (Field.Label):** Give it a visible label in a field, or set `aria-label`. A placeholder isn't a label.
+* **Keep Resizing (resize):** Keep resizing enabled where the layout allows, so readers who zoom can view their whole answer.
+
+## Related
+
+[TextInput](text-input.md)
+
+Use for single-line text.
+
+[Field](field.md)
+
+Use for labels, descriptions, and errors.
+
+[Snippet](snippet.md)
+
+Use for read-only code and values.
+
+[Forms](../patterns/forms.md)
+
+Covers laying out fields and actions.