@cdx-ui/components 0.2.3 → 0.2.5

package/docs/components/textarea/content.md

@@ -0,0 +1,222 @@
+# Textarea (https://design.candescent.com/docs/components/textarea)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=7078-1235), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/inputs-textarea--default)
+
+A multi-line text input for notes, messages, descriptions, and other longer content.
+
+```tsx
+import { Textarea } from '@cdx-ui/components';
+```
+
+## Basic
+
+`Textarea` enables `multiline` and top-aligns its text by default.
+
+```tsx
+import { Textarea } from '@cdx-ui/components';
+
+export default function TextareaBasicDemo() {
+  return <Textarea accessibilityLabel="Notes" placeholder="Add details…" numberOfLines={4} />;
+}
+```
+
+## Sizes
+
+Use `size="small"` for denser forms. Padding, font size, and line height scale together.
+
+```tsx
+import { Box, Text, Textarea, type TextareaProps } from '@cdx-ui/components';
+
+const sizes = ['default', 'small'] as const satisfies readonly NonNullable<TextareaProps['size']>[];
+
+export default function TextareaSizesDemo() {
+  return (
+    <Box className="w-full gap-4">
+      {sizes.map((size) => (
+        <Box key={size} className="gap-2">
+          <Text size="sm" color="secondary">
+            {size}
+          </Text>
+          <Textarea
+            accessibilityLabel={`${size} notes`}
+            defaultValue="Multi-line content"
+            numberOfLines={3}
+            size={size}
+          />
+        </Box>
+      ))}
+    </Box>
+  );
+}
+```
+
+## Auto-grow
+
+Set `autoGrow` to expand the field as content is entered. Add `maxRows` to cap its height and enable internal scrolling after the limit.
+
+```tsx
+import { Textarea } from '@cdx-ui/components';
+
+export default function TextareaAutoGrowDemo() {
+  return (
+    <Textarea
+      accessibilityLabel="Message"
+      autoGrow
+      maxRows={6}
+      numberOfLines={2}
+      placeholder="Type a message…"
+    />
+  );
+}
+```
+
+## Resizable
+
+On web, `resize="vertical"` displays the browser resize handle. It has no effect on native platforms.
+
+```tsx
+import { Textarea } from '@cdx-ui/components';
+
+export default function TextareaResizableDemo() {
+  return (
+    <Textarea
+      accessibilityLabel="Resizable notes"
+      defaultValue="Drag the bottom-right handle to resize this field."
+      numberOfLines={3}
+      resize="vertical"
+    />
+  );
+}
+```
+
+## States
+
+The component supports disabled, read-only, required, and invalid states.
+
+```tsx
+import { Box, Text, Textarea } from '@cdx-ui/components';
+
+export default function TextareaStatesDemo() {
+  return (
+    <Box className="w-full gap-4">
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          Disabled
+        </Text>
+        <Textarea
+          accessibilityLabel="Disabled notes"
+          defaultValue="This content cannot be edited."
+          isDisabled
+          numberOfLines={3}
+        />
+      </Box>
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          Read-only
+        </Text>
+        <Textarea
+          accessibilityLabel="Read-only notes"
+          defaultValue="This content is available for reference."
+          isReadOnly
+          numberOfLines={3}
+        />
+      </Box>
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          Invalid
+        </Text>
+        <Textarea
+          accessibilityLabel="Invalid notes"
+          defaultValue="Too short"
+          isInvalid
+          numberOfLines={3}
+        />
+      </Box>
+    </Box>
+  );
+}
+```
+
+## With field
+
+Compose with `Field` to provide a visible label, helper text, and required state.
+
+```tsx
+import { Field, Textarea } from '@cdx-ui/components';
+
+export default function TextareaWithFieldDemo() {
+  return (
+    <Field className="w-full" isRequired>
+      <Field.Label>Transfer notes</Field.Label>
+      <Textarea isRequired numberOfLines={4} placeholder="Add details for the recipient…" />
+      <Field.Helper>Do not include account numbers or other sensitive information.</Field.Helper>
+    </Field>
+  );
+}
+```
+
+## With field and validation
+
+Set invalid state on both `Field` and `Textarea` so the error message and textarea styling stay in sync.
+
+```tsx
+import { Field, Textarea } from '@cdx-ui/components';
+
+export default function TextareaWithFieldInvalidDemo() {
+  return (
+    <Field className="w-full" isInvalid isRequired>
+      <Field.Label>Transfer notes</Field.Label>
+      <Textarea defaultValue="Gift" isInvalid isRequired numberOfLines={4} />
+      <Field.Error>Enter at least 10 characters.</Field.Error>
+    </Field>
+  );
+}
+```
+
+## API
+
+### Textarea
+
+A flat, single-element multi-line input. Form-control state, sizing, and standard text input props are applied directly to the component.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Additional Tailwind classes, applied to the root shell rather than the inner field. |
+| `numberOfLines?` | `number` | — | Initial / minimum visible rows. Defaults to 2 on web and 8 on native. |
+| `placeholderTextColorClassName?` | `string` | — | — |
+| `style?` | `StyleProp<ViewStyle>` | — | — |
+| `variant?` | `'outline' \| null` | — | — |
+| `size?` | `'default' \| 'small' \| null` | — | — |
+| `autoGrow?` | `boolean` | — | Grow the field height to fit its content. Defaults to `false`. Web uses `field-sizing: content`; native grows intrinsically (`scrollEnabled` off), using `onContentSizeChange` only to enable scrolling past `maxRows`. |
+| `maxRows?` | `number` | — | Caps `autoGrow` at this many rows, after which the field scrolls. |
+| `resize?` | `'none' \| 'vertical'` | — | Web-only user resize affordance. Defaults to `'none'`. `'vertical'` exposes the browser resize handle and takes precedence over `autoGrow` (they are mutually exclusive). No-op on native. |
+| `isInvalid?` | `boolean` | — | If true, the input will indicate an error. |
+| `isDisabled?` | `boolean` | — | If true, the input will be disabled. |
+| `isRequired?` | `boolean` | — | Sets `aria-required="true"` on web when passed in form control. |
+| `isReadOnly?` | `boolean` | — | If true, prevents the value of the input from being edited. |
+| `isFullWidth?` | `boolean` | — | If true, the input element will span the full width of its parent. |
+
+Inherits all [`TextInputProps`](https://reactnative.dev/docs/textinput#props) except `children` and `multiline`. Multi-line mode is always enabled. `style` and `className` apply to the root container, and the forwarded ref targets the underlying `TextInput`.
+
+### Sizing behavior
+
+`numberOfLines` sets the initial or minimum visible rows and defaults to 2 on web and 8 on native. With `autoGrow`, the textarea expands to fit its content until it reaches `maxRows`, then scrolls internally.
+
+On web viewports below 600px, field text renders at 16px (`text-base`) for both sizes so iOS Safari
+does not auto-zoom the page when the textarea is focused. At 600px and above, web matches native
+sizes (14px default, 12px small).
+
+On web, `resize="vertical"` takes precedence over `autoGrow`. Passing both logs a development warning and disables auto-grow. `resize` is a no-op on native.
+
+| Attribute   | Values     | Description    |
+| ----------- | ---------- | -------------- |
+| `data-slot` | `textarea` | Root container |
+
+## Accessibility
+
+| Item                   | Behavior                                                                             |
+| ---------------------- | ------------------------------------------------------------------------------------ |
+| Accessible name        | Compose with `Field.Label` (recommended) or pass `accessibilityLabel` directly.      |
+| Validation             | Pair `isInvalid` with `Field.Error` so the error is not communicated by color alone. |
+| Required               | `isRequired` exposes the required state to assistive technology.                     |
+| Disabled and read-only | `isDisabled` and `isReadOnly` prevent editing and expose the corresponding state.    |