@slotted/react 0.1.0-beta.1 → 0.1.0-beta.11

package/dist/docs/textarea.examples.md

@@ -0,0 +1,504 @@
+<!-- index: ./index.md -->
+# textarea
+
+`data-ui="textarea"` · Multi-line text input.
+
+## Examples
+
+### Playground
+
+One control with every axis on it, driven by the controls below the canvas. Turn autoSize on and type: the box grows to the ceiling and then scrolls.
+
+Excerpt — not a complete module
+
+```tsx
+<Field>
+  <FieldLabel>Observações</FieldLabel>
+  <Textarea rows={3} placeholder="Descreva o que aconteceu" />
+  <FieldDescription>Aparece no histórico do chamado.</FieldDescription>
+</Field>;
+```
+
+### The step the control sits at
+
+The block padding is derived rather than chosen — half of what is left when one line box comes out of the control height — so a one-row textarea is exactly as tall as an input of the same step, at every density.
+
+Example
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import { Stack } from '@slotted/react/stack';
+import { Textarea } from '@slotted/react/textarea';
+
+export default function TextareaSizes() {
+  return (
+    <Stack gap={5}>
+      <Field size="sm">
+        <FieldLabel>Line item note</FieldLabel>
+        <Textarea rows={2} defaultValue="Pack the glass bottles separately." />
+      </Field>
+      <Field size="md">
+        <FieldLabel>Order note</FieldLabel>
+        <Textarea rows={2} defaultValue="The customer asked for delivery before noon on Friday." />
+      </Field>
+      <Field size="lg">
+        <FieldLabel>Message to the supplier</FieldLabel>
+        <Textarea rows={2} defaultValue="Please confirm the revised quantities by Wednesday." />
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### How much frame the control shows
+
+The same three frames the single-line control paints, against the same tokens: one that takes the ground it is placed on, one that sinks into the page, and one that shows nothing until it is used.
+
+Example
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import { Stack } from '@slotted/react/stack';
+import { Textarea } from '@slotted/react/textarea';
+
+export default function TextareaVariants() {
+  return (
+    <Stack gap={5}>
+      <Field>
+        <FieldLabel>Return reason</FieldLabel>
+        <Textarea variant="outline" rows={2} defaultValue="Two jars arrived with broken seals." />
+      </Field>
+      <Field>
+        <FieldLabel>Warehouse note</FieldLabel>
+        <Textarea variant="subtle" rows={2} defaultValue="Restock on shelf B4 after inspection." />
+      </Field>
+      <Field>
+        <FieldLabel>Picker comment</FieldLabel>
+        <Textarea variant="plain" rows={2} defaultValue="Counted twice, 46 units on hand." />
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### Growing with the content
+
+Nothing is measured on the main thread: CSS field-sizing grows the box, rows is the floor and maxRows the ceiling. Type past four lines in the first example and the control scrolls rather than pushing the page.
+
+Example
+
+```tsx
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import { Textarea } from '@slotted/react/textarea';
+
+export default function TextareaAutoSize() {
+  return (
+    <Field>
+      <FieldLabel>Picking note</FieldLabel>
+      <Textarea
+        autoSize
+        rows={2}
+        maxRows={6}
+        defaultValue="Use the reinforced boxes for the olive oil."
+      />
+      <FieldDescription>Shown to the picker on the warehouse screen.</FieldDescription>
+    </Field>
+  );
+}
+```
+
+### The handle in the corner
+
+block is the default rather than the platform’s both, because a control wider than its field breaks the field’s own grid. The handle is withdrawn entirely while autoSize is on, since the two would disagree on the next keystroke.
+
+Excerpt — not a complete module
+
+```tsx
+<Textarea resize="block" />;
+<Textarea resize="none" />;
+<Textarea resize="both" />;
+
+// autoSize wins: the handle is withdrawn rather than left to fight.
+<Textarea autoSize resize="both" />;
+```
+
+### The four states the control paints
+
+Read-only keeps full-strength ink and its handle, because the commonest thing a read-only textarea holds is a value someone has to copy; disabled loses the handle as well, since a handle on a control nobody can type in is a handle that lies.
+
+Example
+
+```tsx
+import { Field, FieldDescription, FieldError, FieldLabel } from '@slotted/react/field';
+import { Stack } from '@slotted/react/stack';
+import { Textarea } from '@slotted/react/textarea';
+
+export default function TextareaStates() {
+  return (
+    <Stack gap={5}>
+      <Field invalid required>
+        <FieldLabel>Damage report</FieldLabel>
+        <Textarea rows={2} defaultValue="Box dented." />
+        <FieldError>Describe the damage in at least 20 characters.</FieldError>
+      </Field>
+      <Field readOnly>
+        <FieldLabel>Customer note</FieldLabel>
+        <Textarea
+          rows={2}
+          defaultValue="Please ring the bell twice. The office is on the second floor."
+        />
+        <FieldDescription>Written by the customer at checkout.</FieldDescription>
+      </Field>
+      <Field disabled>
+        <FieldLabel>Carrier instructions</FieldLabel>
+        <Textarea rows={2} defaultValue="Leave with the building manager." />
+        <FieldDescription>Locked once the shipment is booked.</FieldDescription>
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### Counting what has been typed
+
+The control counts and the field draws it in the spare column of the label row, so a count that appears on the first keystroke never shares a row with the error and pushes it — which is where Angular Material puts it.
+
+Example
+
+```tsx
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import { Stack } from '@slotted/react/stack';
+import { Textarea } from '@slotted/react/textarea';
+
+export default function TextareaCount() {
+  return (
+    <Stack gap={5}>
+      <Field>
+        <FieldLabel>Gift message</FieldLabel>
+        <Textarea
+          rows={2}
+          maxLength={150}
+          showCount
+          defaultValue="Happy anniversary to the whole team at Alfreds Futterkiste."
+        />
+        <FieldDescription>Printed on a card inside the box.</FieldDescription>
+      </Field>
+      <Field>
+        <FieldLabel>Product summary</FieldLabel>
+        <Textarea
+          rows={3}
+          countMax={120}
+          showCount
+          defaultValue="Hand-picked Darjeeling first flush, packed in resealable tins of 100 grams. Ships within two days."
+        />
+        <FieldDescription>Search results cut summaries after 120 characters.</FieldDescription>
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### Content the family did not choose
+
+A pasted token with no break in it — a signed URL, a certificate, a container digest — wraps instead of taking the page’s horizontal scrollbar with it, and nothing is removed from the value.
+
+Excerpt — not a complete module
+
+```tsx
+<Textarea defaultValue={jwt} rows={3} />;
+
+// overflow-wrap: anywhere in the stylesheet, so the whole string stays
+// selectable, copyable and reachable with the caret.
+<Textarea dir="rtl" defaultValue="مرحبا بالعالم" rows={3} />;
+```
+
+### Setting it once, and reaching past it
+
+The provider carries the four decisions an application takes once; render substitutes the element; ref reaches the textarea, which already has focus, select and setSelectionRange.
+
+Excerpt — not a complete module
+
+```tsx
+<TextareaDefaultsProvider resize="none" variant="subtle">
+  <Textarea autoSize />
+</TextareaDefaultsProvider>;
+
+const ref = useRef<HTMLTextAreaElement>(null);
+<Textarea ref={ref} name="notes" form="ticket" />;
+```
+
+### What the keyboard does, and what it deliberately does not
+
+Enter makes a line and never submits — the difference WAI-ARIA notes between a single-line and a multi-line control — and Tab leaves the control rather than inserting a tab, so a keyboard user is never trapped in a comment box.
+
+Excerpt — not a complete module
+
+```tsx
+<form onSubmit={onSubmit}>
+  <Textarea name="notes" rows={3} />
+  <Button type="submit">Enviar</Button>
+</form>;
+```
+
+### comment-composer.tsx
+
+Example
+
+```tsx
+import { useState, type SubmitEvent } from 'react';
+import { Button } from '@slotted/react/button';
+import { Field, FieldLabel } from '@slotted/react/field';
+import { Inline } from '@slotted/react/inline';
+import { Stack } from '@slotted/react/stack';
+import { Textarea } from '@slotted/react/textarea';
+import { Text } from '@slotted/react/typography';
+
+interface Comment {
+  id: number;
+  author: string;
+  time: string;
+  body: string;
+}
+
+const THREAD: Comment[] = [
+  {
+    id: 1,
+    author: 'Maria Anders',
+    time: '09:12',
+    body: 'The customer called: the pallet has to arrive before the store opens at 8:00.',
+  },
+  {
+    id: 2,
+    author: 'Thomas Hardy',
+    time: '10:47',
+    body: 'Booked with the early carrier. Tracking follows once the truck is loaded.',
+  },
+];
+
+export default function TextareaCommentComposer() {
+  const [comments, setComments] = useState(THREAD);
+  const [draft, setDraft] = useState('');
+
+  const submit = (event: SubmitEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const body = draft.trim();
+    if (body === '') return;
+    setComments((current) => [
+      ...current,
+      { id: current.length + 1, author: 'You', time: 'Just now', body },
+    ]);
+    setDraft('');
+  };
+
+  return (
+    <Stack gap={6}>
+      <Stack gap={4}>
+        {comments.map((comment) => (
+          <Stack key={comment.id} gap={1}>
+            <Inline gap={2} align="baseline">
+              <Text size="sm" weight="semibold">
+                {comment.author}
+              </Text>
+              <Text size="sm" tone="muted">
+                {comment.time}
+              </Text>
+            </Inline>
+            <Text size="sm">{comment.body}</Text>
+          </Stack>
+        ))}
+      </Stack>
+      <form onSubmit={submit}>
+        <Stack gap={3}>
+          <Field>
+            <FieldLabel>Comment on order 10248</FieldLabel>
+            <Textarea
+              autoSize
+              rows={2}
+              maxRows={8}
+              placeholder="Write an update for the team"
+              value={draft}
+              onValueChange={setDraft}
+            />
+          </Field>
+          <Inline justify="end">
+            <Button type="submit">Post comment</Button>
+          </Inline>
+        </Stack>
+      </form>
+    </Stack>
+  );
+}
+```
+
+### defaults.tsx
+
+Example
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import { Stack } from '@slotted/react/stack';
+import { Textarea, TextareaDefaultsProvider } from '@slotted/react/textarea';
+
+export default function TextareaDefaults() {
+  return (
+    <TextareaDefaultsProvider variant="subtle" resize="none">
+      <Stack gap={5}>
+        <Field>
+          <FieldLabel>Reply to the customer</FieldLabel>
+          <Textarea rows={2} defaultValue="Your refund was issued today." />
+        </Field>
+        <Field>
+          <FieldLabel>Internal note</FieldLabel>
+          <Textarea rows={2} defaultValue="Refund approved by finance." />
+        </Field>
+        <Field>
+          <FieldLabel>Escalation summary</FieldLabel>
+          <Textarea variant="outline" rows={2} defaultValue="Second refund request this quarter." />
+        </Field>
+      </Stack>
+    </TextareaDefaultsProvider>
+  );
+}
+```
+
+### mono.tsx
+
+Example
+
+```tsx
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import { Textarea } from '@slotted/react/textarea';
+
+const PAYLOAD = `{
+  "event": "order.shipped",
+  "orderId": 10248,
+  "carrier": "Federal Shipping",
+  "tracking": "FS-2026-0042-7731"
+}`;
+
+export default function TextareaMono() {
+  return (
+    <Field>
+      <FieldLabel>Test payload</FieldLabel>
+      <Textarea mono variant="subtle" rows={7} spellCheck={false} defaultValue={PAYLOAD} />
+      <FieldDescription>Sent to your endpoint when you press Send test event.</FieldDescription>
+    </Field>
+  );
+}
+```
+
+### read-only.tsx
+
+Example
+
+```tsx
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import { Textarea } from '@slotted/react/textarea';
+
+const TERMS = `1. Payment. Invoices are payable within 30 days of the invoice date. Late payments carry interest of 1% per month.
+
+2. Delivery. The supplier ships within five business days of a confirmed purchase order. Partial shipments are invoiced separately.
+
+3. Returns. Goods damaged in transit are reported within 48 hours of receipt, with photographs of the packaging.
+
+4. Prices. Prices are fixed for the term of this agreement and reviewed every January.
+
+5. Termination. Either party may end this agreement with 60 days' written notice.`;
+
+export default function TextareaReadOnly() {
+  return (
+    <Field>
+      <FieldLabel>Supplier terms</FieldLabel>
+      <Textarea readOnly rows={6} defaultValue={TERMS} />
+      <FieldDescription>Agreed with Exotic Liquids on 3 March 2026.</FieldDescription>
+    </Field>
+  );
+}
+```
+
+### rows.tsx
+
+Example
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import { Stack } from '@slotted/react/stack';
+import { Textarea } from '@slotted/react/textarea';
+
+export default function TextareaRows() {
+  return (
+    <Stack gap={5}>
+      <Field>
+        <FieldLabel>Gift message</FieldLabel>
+        <Textarea rows={2} resize="none" defaultValue="Happy birthday, Laura. Enjoy the tea." />
+      </Field>
+      <Field>
+        <FieldLabel>Incident report</FieldLabel>
+        <Textarea rows={5} placeholder="What happened, when, and who was involved" />
+      </Field>
+      <Field>
+        <FieldLabel>Reply draft</FieldLabel>
+        <Textarea resize="both" placeholder="Drag the corner to resize in both directions" />
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### validation.tsx
+
+Example
+
+```tsx
+import { useState, type SubmitEvent } from 'react';
+import { Button } from '@slotted/react/button';
+import { Field, FieldError, FieldLabel } from '@slotted/react/field';
+import { Inline } from '@slotted/react/inline';
+import { Stack } from '@slotted/react/stack';
+import { Textarea } from '@slotted/react/textarea';
+
+const MIN_LENGTH = 20;
+
+function detailsError(value: string): string {
+  if (value === '') return 'Describe what is wrong with the item.';
+  if (value.length < MIN_LENGTH) return `Add more detail: at least ${MIN_LENGTH} characters.`;
+  return '';
+}
+
+export default function TextareaValidation() {
+  const [details, setDetails] = useState('');
+  const [submitted, setSubmitted] = useState(false);
+  const [sent, setSent] = useState(false);
+  const error = submitted ? detailsError(details) : '';
+
+  const submit = (event: SubmitEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setSubmitted(true);
+    setSent(detailsError(details) === '');
+  };
+
+  return (
+    <form noValidate onSubmit={submit}>
+      <Stack gap={4}>
+        <Field required invalid={error !== '' ? true : undefined}>
+          <FieldLabel>What is wrong with the item?</FieldLabel>
+          <Textarea
+            value={details}
+            onValueChange={(value) => {
+              setDetails(value);
+              setSent(false);
+            }}
+          />
+          <FieldError live="polite" reserve>
+            {error}
+          </FieldError>
+        </Field>
+        <Inline gap={3} align="center">
+          <Button type="submit">Request a return</Button>
+          {sent ? <span role="status">Return requested.</span> : null}
+        </Inline>
+      </Stack>
+    </form>
+  );
+}
+```

package/dist/docs/textarea.json

@@ -235,6 +235,7 @@
     "--slotted-border-subtle",
     "--slotted-control-border-color",
     "--slotted-control-border-width",
+    "--slotted-control-focus-ring-offset",
     "--slotted-control-font-family",
     "--slotted-control-font-size-lg",
     "--slotted-control-font-size-md",