@ui-sdk/react 0.0.0-stage → 0.1.0-beta.1

package/docs/components/textarea.md

@@ -0,0 +1,318 @@
+# Textarea
+
+Enter multiple lines of text, grow the field as you type, and connect it to a form.
+
+A textarea is a native multi-line text field for messages, notes and descriptions. It works inside a field and a form, can grow with its text, and reports the same change reasons as Input.
+
+```tsx title="basic.tsx"
+import { Field, FieldLabel } from "@ui-sdk/react/field"
+import { Textarea } from "@ui-sdk/react/textarea"
+
+function Example() {
+  return (
+    <Field name="message">
+      <FieldLabel>Message</FieldLabel>
+      <Textarea placeholder="Type your message here…" />
+    </Field>
+  )
+}
+
+export { Example }
+```
+
+Click Message to focus the textarea, then type. Press Enter to start a new line.
+
+## Installation
+
+```bash
+npm install @ui-sdk/react @ui-sdk/core
+```
+
+## Usage
+
+`Textarea` renders a native `<textarea>`. Pass `rows`, `placeholder`, `maxLength` and other native attributes directly.
+
+```tsx
+import { Textarea } from "@ui-sdk/react/textarea"
+
+function Example() {
+  return <Textarea aria-label="Message" placeholder="Type your message here…" />
+}
+
+export { Example }
+```
+
+## Field
+
+Wrap the textarea in a [Field](./field.md) to give it a visible label and a description. The field also supplies its `name` when the textarea has none.
+
+```tsx title="field.tsx"
+import { Field, FieldDescription, FieldLabel } from "@ui-sdk/react/field"
+import { Textarea } from "@ui-sdk/react/textarea"
+
+function Example() {
+  return (
+    <Field name="feedback">
+      <FieldLabel>Feedback</FieldLabel>
+      <Textarea placeholder="What could we do better?" />
+      <FieldDescription>Only the product team can see this.</FieldDescription>
+    </Field>
+  )
+}
+
+export { Example }
+```
+
+Click Feedback to focus the textarea. A screen reader reads the description with the field.
+
+## Auto Resize
+
+Set `autoResize` to grow and shrink the textarea with its text. CSS `min-height` and `max-height` set its limits; past the maximum, the text scrolls inside it.
+
+```tsx title="auto-resize.tsx"
+import { Field, FieldDescription, FieldLabel } from "@ui-sdk/react/field"
+import { Textarea } from "@ui-sdk/react/textarea"
+
+function Example() {
+  return (
+    <Field name="notes">
+      <FieldLabel>Notes</FieldLabel>
+      <Textarea autoResize placeholder="Add notes for the delivery driver…" />
+      <FieldDescription>Your driver sees these notes.</FieldDescription>
+    </Field>
+  )
+}
+
+export { Example }
+```
+
+Type several lines in Notes. The textarea grows with each line until it reaches its maximum height, then scrolls. Delete the lines and it shrinks back.
+
+Browsers that support `field-sizing: content` size it natively. Elsewhere, the component measures it when the value changes, the form resets or its width changes.
+
+## Controlled
+
+Keep `value` in state and update it with `onValueChange`. Here the character count is derived from that value, and the native `maxLength` caps the text.
+
+```tsx title="controlled.tsx"
+import { Field, FieldDescription, FieldLabel } from "@ui-sdk/react/field"
+import { Textarea } from "@ui-sdk/react/textarea"
+import * as React from "react"
+
+function Example() {
+  const [bio, setBio] = React.useState(
+    "Product designer in Lisbon. I write about type and interfaces."
+  )
+  return (
+    <Field name="bio">
+      <FieldLabel>Bio</FieldLabel>
+      <Textarea value={bio} onValueChange={setBio} maxLength={160} />
+      <FieldDescription>{bio.length} / 160 characters</FieldDescription>
+    </Field>
+  )
+}
+
+export { Example }
+```
+
+Edit Bio and watch the character count under it. The textarea stops accepting text at 160 characters.
+
+Textarea shares Input's [change reasons](#reasons) and cancellation behavior. See [State and Events](../state-and-events.md) for the shared conventions.
+
+## Form
+
+A textarea submits its value through a native form under its field's `name`. Pass a controller from `createInputController()` to change it from outside, here to empty it after sending. The native `required` constraint blocks an empty message.
+
+```tsx title="button.tsx"
+import { Field, FieldLabel } from "@ui-sdk/react/field"
+import { Textarea, createInputController } from "@ui-sdk/react/textarea"
+import * as React from "react"
+import { useLog } from "./log"
+
+function Example() {
+  const log = useLog()
+  const [message] = React.useState(createInputController)
+  return (
+    <form
+      data-slot="stack"
+      onSubmit={(event) => {
+        event.preventDefault()
+        const data = new FormData(event.currentTarget)
+        log(`Sent “${data.get("message")}”`)
+        message.clear()
+      }}
+    >
+      <Field name="message">
+        <FieldLabel>Message</FieldLabel>
+        <Textarea controller={message} required placeholder="Write a reply to Hollis Grant…" />
+      </Field>
+      <div data-slot="row">
+        <button type="submit" data-variant="solid">
+          Send Message
+        </button>
+      </div>
+    </form>
+  )
+}
+
+export { Example }
+```
+
+Type a message and press Send Message. The console logs it and the textarea clears. Pressing Send Message while it's empty is blocked.
+
+[Controllers](../controllers.md) covers creating and sharing a controller.
+
+## Disabled
+
+Set `disabled` on the textarea or its field to prevent editing and leave it out of the tab order and the submitted values.
+
+```tsx title="disabled.tsx"
+import { Field, FieldLabel } from "@ui-sdk/react/field"
+import { Textarea } from "@ui-sdk/react/textarea"
+
+function Example() {
+  return (
+    <Field disabled>
+      <FieldLabel>Reply</FieldLabel>
+      <Textarea defaultValue="Replies are closed for this thread." />
+    </Field>
+  )
+}
+
+export { Example }
+```
+
+Try to edit Reply or reach it with Tab. The disabled textarea keeps its value but can't be changed.
+
+## Invalid
+
+Set `invalid` on the field for an error your app decides. The field shows its error, associates it with the textarea and sets `aria-invalid`. [Field](./field.md#validation) covers native constraints and error matches.
+
+```tsx title="invalid.tsx"
+import { Field, FieldError, FieldLabel } from "@ui-sdk/react/field"
+import { Textarea } from "@ui-sdk/react/textarea"
+
+function Example() {
+  return (
+    <Field invalid>
+      <FieldLabel>Review</FieldLabel>
+      <Textarea defaultValue="Great." />
+      <FieldError match>Write at least 20 characters.</FieldError>
+    </Field>
+  )
+}
+
+export { Example }
+```
+
+Focus Review. The textarea is marked invalid, and the error below says how long the review should be.
+
+## Submit Shortcut
+
+Set `submitShortcut` to submit the textarea's form from the keyboard. With `"mod+enter"`, Enter still starts a new line and Command or Control+Enter submits. With `"enter"`, Enter submits and Shift+Enter starts a new line. Without it, Enter always starts a new line, and neither submits while an input method is composing.
+
+```tsx
+import { Textarea } from "@ui-sdk/react/textarea"
+
+function Example() {
+  return (
+    <form action="/messages" method="post">
+      <Textarea
+        name="message"
+        aria-label="Message"
+        required
+        submitShortcut="mod+enter"
+      />
+      <button type="submit">Send</button>
+    </form>
+  )
+}
+
+export { Example }
+```
+
+The shortcut submits like the Send button, so `required` and the form's `onSubmit` still apply. Pass `onSubmit` to the textarea to handle the shortcut yourself instead. It receives the value, and the form doesn't submit.
+
+## Styling
+
+Style the native textarea directly, with `data-filled`, `data-disabled`, `data-readonly` and `data-required` for its states. Inside a field it also receives the field's validation attributes, such as `data-invalid`. For `autoResize`, set `min-height` and `max-height` to bound its growth. Use logical spacing so the text follows the surrounding direction.
+
+The textarea has a `data-slot` of `textarea`, and its state attributes are listed under [Data Attributes](#data-attributes).
+
+## Data Attributes
+
+### Textarea
+`[data-slot="textarea"]`
+
+- `data-filled`: Present while the field holds any text.
+- `data-disabled`: Present when the field is disabled, by its own prop or its Field.
+- `data-readonly`: Present when the field is read-only.
+- `data-required`: Present when the field is required.
+
+## API Reference
+
+Props are the same as below, as React props, plus every native textarea prop.
+
+### Textarea
+
+- `value?` (`string`): The value, for a controlled field.
+- `defaultValue?` (`string`): The value it starts with. A form reset returns here.
+- `onValueChange?` (`((value: string, details: ChangeDetails<InputValueChangeReason>) => void)`): Called when the user changes the value: typing (`"input-change"`), a Clear part (`"clear-press"`), a form reset (`"reset"`) or a controller (`"imperative"`). `details.cancel()` keeps the value as it was.
+- `controller?` (`object`): Reads and writes the field from anywhere. Create one with `createInputController()`.
+- `debug?` (`boolean`): Logs every state change with its reason to the console, in development builds.
+- `autoResize?` (`boolean`): Grows and shrinks with the text. Bound it with CSS `min-height` and `max-height`; past the maximum, it scrolls.
+- `onSubmit?` (`((value: string, details: TextareaSubmitDetails) => void)`): Runs on the submit shortcut, unless an input method is composing. Without it, the shortcut submits the form the textarea is in. With neither, the key is left alone, so Enter adds a line.
+- `submitShortcut?` (`"enter" | "mod+enter"`): Which keys submit: `"enter"`, with Shift+Enter for a new line, or `"mod+enter"`, with Enter for a new line. Without it, Enter always starts a new line.
+
+- `disabled?` (`boolean`): Disables the field.
+- `readOnly?` (`boolean`): Makes the field read-only.
+- `required?` (`boolean`): Makes the field required.
+
+### State
+
+- `filled` (`boolean`): Whether the field holds any text.
+- `disabled` (`boolean`): Whether the field is disabled.
+- `readOnly` (`boolean`): Whether the field is read-only.
+- `required` (`boolean`): Whether the field is required.
+
+### Reasons
+
+- `input-change` (`Event`): Typing, pasting or dropping changed a text field's value; in a combobox it can also open or close it, or Enter keeps the typed text as the value.
+- `clear-press` (`MouseEvent | KeyboardEvent`): A Clear part was pressed, like on an input, a select or a combobox.
+- `reset` (`none`): A form reset.
+- `imperative` (`none`): A controller or `api` call, or a property set on a web component.
+
+### Controller
+
+Create one with `createInputController()` and pass it as `controller`.
+
+- `getValue()` (`() => string`): The current value.
+- `setValue(value, options?)` (`(value: string, options?: ChangeOptions<InputValueChangeReason> | undefined) => boolean`): Sets the value as if the user typed it, so `input` fires. Returns false when the change was canceled or nothing changed.
+- `clear(options?)` (`(options?: ChangeOptions<InputValueChangeReason> | undefined) => boolean`): Empties the field, as if the user deleted the text, so `input` fires. Returns false when the change was canceled or nothing changed.
+- `focus()` (`() => void`): Moves focus to the field.
+
+## Accessibility
+
+There's no WAI-ARIA pattern for a multi-line text field. The textarea stays a native `<textarea>`, with standard text editing, selection, spell checking and form behavior. Give it a visible field label or an `aria-label`, and keep descriptions and errors in their field parts so they're associated with it.
+
+### Tested Behavior
+
+Every line below is an automated test.
+
+- The label names the textarea and the description describes it.
+
+**Auto resize**
+
+- Grows with its text and shrinks back.
+- Stops at its max height and scrolls.
+- Shrinks back when a reset empties it.
+- Follows text written from code.
+
+**Submit shortcut**
+
+- Without a submit shortcut, Enter starts a new line and doesn't submit.
+- With enter, Enter submits the form and Shift+Enter starts a new line.
+- With mod+enter, Enter starts a new line and Cmd or Ctrl+Enter submits.
+- Enter while an input method composes doesn't submit.
+
+Runs in React, Vue and web components.

package/docs/components/time-input.md

@@ -0,0 +1,231 @@
+# Time Input
+
+Type a time one part at a time, on the clock your user's language uses.
+
+Use a Time Input for a time of day, like a meeting or an opening hour. It works like [Date Input](./date-input.md), with segments for the hour, the minute and, on a 12-hour clock, AM or PM.
+
+```tsx title="time.tsx"
+"use client"
+
+import { Field, FieldLabel } from "@ui-sdk/react/field"
+import { TimeInput } from "@ui-sdk/react/time-input"
+
+function Example() {
+  return (
+    <Field>
+      <FieldLabel>Meeting time</FieldLabel>
+      <TimeInput defaultValue="09:30" />
+    </Field>
+  )
+}
+
+export { Example }
+```
+
+Click the hour and type 230, then P. Press ArrowUp or ArrowDown on a part to step it.
+
+## Installation
+
+```bash
+npm install @ui-sdk/react @ui-sdk/core
+```
+
+## Composition
+
+Use the following composition to build a `TimeInput`:
+
+```text
+TimeInput
+├── TimeInputSegment
+└── TimeInputSegment
+```
+
+`TimeInput` renders a group with one `TimeInputSegment` for each part of the time, and the text between them.
+
+## Usage
+
+Put the input in a [Field](./field.md) and give it a label:
+
+```tsx
+import { Field, FieldLabel } from "@ui-sdk/react/field"
+import { TimeInput } from "@ui-sdk/react/time-input"
+
+function Example() {
+  return (
+    <Field>
+      <FieldLabel>Meeting time</FieldLabel>
+      <TimeInput defaultValue="09:30" />
+    </Field>
+  )
+}
+
+export { Example }
+```
+
+The value is a 24-hour time like `"14:30"`, the same as a native time input's, whatever clock the input shows. Typing, stepping and pasting work as they do in [Date Input](./date-input.md#usage).
+
+## Clock and Seconds
+
+The input shows the locale's clock. Set `hourCycle` to `12` or `24` to choose one, and `granularity` to `"second"` to add seconds, or `"hour"` to show the hour alone.
+
+```tsx title="hour-cycle.tsx"
+"use client"
+
+import { Field, FieldLabel } from "@ui-sdk/react/field"
+import { TimeInput } from "@ui-sdk/react/time-input"
+
+function Example() {
+  return (
+    <div data-slot="stack">
+      <Field>
+        <FieldLabel>12-hour clock</FieldLabel>
+        <TimeInput hourCycle={12} defaultValue="18:45" />
+      </Field>
+      <Field>
+        <FieldLabel>24-hour clock</FieldLabel>
+        <TimeInput hourCycle={24} defaultValue="18:45" />
+      </Field>
+      <Field>
+        <FieldLabel>With seconds</FieldLabel>
+        <TimeInput granularity="second" hourCycle={24} defaultValue="18:45:30" />
+      </Field>
+    </div>
+  )
+}
+
+export { Example }
+```
+
+The same evening time on a 12-hour clock, a 24-hour clock and with seconds. All three submit 24-hour values.
+
+## Min and Max
+
+`min` and `max` take times like `"09:00"`. A time outside them is invalid: the input sets `data-invalid`, and its form won't submit.
+
+## Form
+
+A hidden input submits the time under `name`. Set `required` to need a time before the form submits, and `form` to the id of a form elsewhere in the page to submit with it. The [Date Input form example](./date-input.md#form) has a time in it.
+
+## Controlled and Controller
+
+Pass `value` and update it in `onValueChange`, or drive the input with `createTimeInputController()`, as in [Date Input](./date-input.md#controlled).
+
+## Styling
+
+Style it like [Date Input](./date-input.md#styling). The AM/PM segment sets `data-type="dayPeriod"`.
+
+Each part has a `data-slot`, such as `time-input-segment`, and its state attributes are listed under [Data Attributes](#data-attributes).
+
+## Data Attributes
+
+### TimeInput
+`[data-slot="time-input"]`
+
+- `data-disabled`: Present when disabled, by its own prop or a `<fieldset>`.
+- `data-readonly`: Present when read-only.
+- `data-required`: Present when required.
+- `data-invalid`: Present while the time is before `min` or after `max`.
+- `data-empty`: Present while every segment is empty.
+
+### TimeInputSegment
+`[data-slot="time-input-segment"]`
+
+- `data-type` (`hour`, `minute`, `second`, `dayPeriod`, `literal`): The segment's unit, or `literal` for the text between segments.
+- `data-disabled`: Present when disabled, by its own prop or a `<fieldset>`.
+- `data-readonly`: Present when read-only.
+- `data-required`: Present when required.
+- `data-invalid`: Present while the time is before `min` or after `max`.
+- `data-empty`: Present while the segment is empty. It shows its placeholder.
+
+## API Reference
+
+Props and callbacks are the same as below, as React props.
+
+### TimeInput
+
+- `value?` (`string | null`): The value: a time like `"14:30"`, or `"14:30:15"` with seconds, or `null`. Pass it to control the input.
+- `defaultValue?` (`string | null`): The value it starts with, when uncontrolled, and goes back to when its form resets.
+- `onValueChange?` (`((value: string | null, details: ChangeDetails<TimeInputValueChangeReason>) => void)`): Runs when the value wants to change: once every segment holds something, and again with `null` when one is emptied. `details.cancel()` keeps the value.
+- `granularity?` (`TimeInputGranularity`): The smallest unit it shows.
+- `hourCycle?` (`HourCycle`): A 12 or 24 hour clock. Defaults to the locale's.
+- `min?` (`string`): The earliest time, like `"09:00"`. A time before it is invalid.
+- `max?` (`string`): The latest time, like `"17:30"`. A time after it is invalid.
+- `locale?` (`string`): The language whose separators and clock it shows. Defaults to the page's.
+- `disabled?` (`boolean`): Whether it can't be used.
+- `readOnly?` (`boolean`): Whether the value can be seen but not changed.
+- `required?` (`boolean`): Whether a time must be entered before its form submits.
+- `name?` (`string`): The name the value submits under.
+- `form?` (`string`): The id of the form it belongs to, when it isn't inside it.
+- `controller?` (`object`): Drives it from anywhere. Create one with `createTimeInputController()`.
+- `debug?` (`boolean`): Logs every state change with its reason to the console, in development builds.
+
+### State
+
+- `value` (`string | null`): The value, or `null` while empty or partly filled.
+- `segments` (`DateInputSegmentData[]`): The segments in the order the locale shows them, with the text between them. Render one part for each.
+- `disabled` (`boolean`): Whether it can't be used, by itself or by a `<fieldset>`.
+- `readOnly` (`boolean`): Whether the value can be seen but not changed.
+- `invalid` (`boolean`): Whether the value is before `min`, after `max` or an unavailable date.
+
+### Reasons
+
+- `input-change` (`Event`): Typing, pasting or dropping changed a text field's value; in a combobox it can also open or close it, or Enter keeps the typed text as the value.
+- `step-key` (`KeyboardEvent`): Arrow, Page Up, Page Down, Home or End stepped a slider or a number input.
+- `paste` (`ClipboardEvent`): Files were pasted, like a screenshot, or text and tokens into a token input.
+- `reset` (`none`): A form reset.
+- `restore` (`none`): The browser restored state, like after going back, or a saved value was read back from storage.
+- `imperative` (`none`): A controller or `api` call, or a property set on a web component.
+
+### Controller
+
+- `getValue()` (`() => string | null`): The value, or `null` while empty or partly filled.
+- `setValue(value, options?)` (`(value: string | null, options?: DateInputChangeOptions | undefined) => boolean`): Sets the value. Returns false when it isn't a value the input can show, or when canceled.
+- `clear(options?)` (`(options?: DateInputChangeOptions | undefined) => boolean`): Empties every segment.
+- `focus(segment?)` (`(segment?: string | undefined) => void`): Focuses a segment, like `"month"`, or the first one.
+
+### Events
+
+| Prop            | On          | Receives                                                                           |
+| --------------- | ----------- | ---------------------------------------------------------------------------------- |
+| `onValueChange` | `TimeInput` | `(value, details)`: the time, or null once it's erased, and the [reason](#reasons) |
+
+## Accessibility
+
+The root is a group, named by its Field's label or by your `aria-label`. Each segment is a spinbutton named by its unit, like "hour" or "AM/PM", with its value, range and text. The keys are the same as in [Date Input](./date-input.md#keyboard).
+
+### Tested Behavior
+
+Every line below is an automated test.
+
+- Each unit is a spinbutton in the locale's order.
+- Another locale orders the segments its own way.
+- Typing fills each segment, moves on and reports the date once.
+- A press on the box or between segments focuses the nearest segment.
+- A digit that can't start a longer number moves on at once.
+- A separator moves to the next segment.
+- Typing with separators over a filled date or time keeps every segment.
+- ArrowUp and ArrowDown step a segment and wrap around.
+- PageUp and PageDown take bigger steps.
+- Home and End go to a segment's first and last values.
+- ArrowLeft and ArrowRight move between segments.
+- Tab moves through the segments, then out.
+- Backspace empties a segment, then moves back.
+- A day past the end of a new month is moved back to its last day.
+- Pasting a date fills every segment.
+- A time takes hours, minutes and AM or PM.
+- A 24-hour clock has no AM or PM.
+- A date with a time shows its hour and minute too.
+- A controller sets and clears the date.
+- A canceled change keeps the date.
+- The form submits the ISO date and time under their names.
+- Enter submits the form with what was typed.
+- Resetting the form brings back the default date.
+- A partly filled date can't be submitted.
+- A required empty date can't be submitted.
+- A date after max is invalid.
+- An unavailable date is invalid.
+- The field's label focuses the first segment.
+- A read-only date takes focus but doesn't change.
+- A disabled date can't be focused.
+
+Runs in React, Vue and web components.