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

package/docs/components/textarea.md

@@ -0,0 +1,331 @@
+# 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.
+
+```ts title="basic.ts"
+import "@ui-sdk/web/field"
+import "@ui-sdk/web/textarea"
+
+function mount(root: HTMLElement) {
+  root.innerHTML = `
+    <ui-field name="message">
+      <ui-field-label>Message</ui-field-label>
+      <ui-textarea>
+        <textarea placeholder="Type your message here…"></textarea>
+      </ui-textarea>
+    </ui-field>
+  `
+}
+
+export { mount }
+```
+
+Click Message to focus the textarea, then type. Press Enter to start a new line.
+
+## Installation
+
+```bash
+npm install @ui-sdk/web @ui-sdk/core
+```
+
+Importing the component defines its element. Import the field too if you use it. On the server the import does nothing.
+
+```ts
+import "@ui-sdk/web/textarea"
+import "@ui-sdk/web/field"
+```
+
+## Usage
+
+`ui-textarea` wraps your own `<textarea>`. Put `rows`, `placeholder`, `maxlength` and other native attributes on the `<textarea>`.
+
+```html
+<script type="module">
+  import "@ui-sdk/web/textarea"
+</script>
+
+<ui-textarea>
+  <textarea
+    aria-label="Message"
+    placeholder="Type your message here…"
+  ></textarea>
+</ui-textarea>
+```
+
+## 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.
+
+```ts title="field.ts"
+import "@ui-sdk/web/field"
+import "@ui-sdk/web/textarea"
+
+function mount(root: HTMLElement) {
+  root.innerHTML = `
+    <ui-field name="feedback">
+      <ui-field-label>Feedback</ui-field-label>
+      <ui-textarea>
+        <textarea placeholder="What could we do better?"></textarea>
+      </ui-textarea>
+      <ui-field-description>Only the product team can see this.</ui-field-description>
+    </ui-field>
+  `
+}
+
+export { mount }
+```
+
+Click Feedback to focus the textarea. A screen reader reads the description with the field.
+
+## Auto Resize
+
+Set `auto-resize` 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.
+
+```ts title="auto-resize.ts"
+import "@ui-sdk/web/field"
+import "@ui-sdk/web/textarea"
+
+function mount(root: HTMLElement) {
+  root.innerHTML = `
+    <ui-field name="notes">
+      <ui-field-label>Notes</ui-field-label>
+      <ui-textarea auto-resize>
+        <textarea placeholder="Add notes for the delivery driver…"></textarea>
+      </ui-textarea>
+      <ui-field-description>Your driver sees these notes.</ui-field-description>
+    </ui-field>
+  `
+}
+
+export { mount }
+```
+
+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
+
+Listen for `valuechange` to read the value, and set the element's `value` property to change it from your app. Here the character count is derived from that value, and the native `maxlength` caps the text.
+
+```ts title="controlled.ts"
+import "@ui-sdk/web/field"
+import "@ui-sdk/web/textarea"
+
+function mount(root: HTMLElement) {
+  root.innerHTML = `
+    <ui-field name="bio">
+      <ui-field-label>Bio</ui-field-label>
+      <ui-textarea>
+        <textarea maxlength="160">Product designer in Lisbon. I write about type and interfaces.</textarea>
+      </ui-textarea>
+      <ui-field-description>62 / 160 characters</ui-field-description>
+    </ui-field>
+  `
+  const count = root.querySelector("ui-field-description")!
+  root
+    .querySelector("ui-textarea")!
+    .addEventListener("valuechange", (event) => {
+      count.textContent = `${event.detail.value.length} / 160 characters`
+    })
+}
+
+export { mount }
+```
+
+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`. Use the element's `api` to change it from outside, here to empty it after sending. The native `required` constraint blocks an empty message.
+
+```ts title="button.ts"
+import "@ui-sdk/web/field"
+import "@ui-sdk/web/textarea"
+import { log } from "./log"
+
+function mount(root: HTMLElement) {
+  root.innerHTML = `
+    <form data-slot="stack">
+      <ui-field name="message">
+        <ui-field-label>Message</ui-field-label>
+        <ui-textarea>
+          <textarea required placeholder="Write a reply to Hollis Grant…"></textarea>
+        </ui-textarea>
+      </ui-field>
+      <div data-slot="row">
+        <button type="submit" data-variant="solid">Send Message</button>
+      </div>
+    </form>
+  `
+  const form = root.querySelector("form")!
+  const message = root.querySelector("ui-textarea")!
+  form.addEventListener("submit", (event) => {
+    event.preventDefault()
+    log(root, `Sent “${new FormData(form).get("message")}”`)
+    message.api.clear()
+  })
+}
+
+export { mount }
+```
+
+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 native textarea or its field to prevent editing and leave it out of the tab order and the submitted values.
+
+```ts title="disabled.ts"
+import "@ui-sdk/web/field"
+import "@ui-sdk/web/textarea"
+
+function mount(root: HTMLElement) {
+  root.innerHTML = `
+    <ui-field disabled>
+      <ui-field-label>Reply</ui-field-label>
+      <ui-textarea>
+        <textarea>Replies are closed for this thread.</textarea>
+      </ui-textarea>
+    </ui-field>
+  `
+}
+
+export { mount }
+```
+
+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.
+
+```ts title="invalid.ts"
+import "@ui-sdk/web/field"
+import "@ui-sdk/web/textarea"
+
+function mount(root: HTMLElement) {
+  root.innerHTML = `
+    <ui-field invalid>
+      <ui-field-label>Review</ui-field-label>
+      <ui-textarea>
+        <textarea>Great.</textarea>
+      </ui-textarea>
+      <ui-field-error match>Write at least 20 characters.</ui-field-error>
+    </ui-field>
+  `
+}
+
+export { mount }
+```
+
+Focus Review. The textarea is marked invalid, and the error below says how long the review should be.
+
+## Submit Shortcut
+
+Set `submit-shortcut` 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.
+
+```html
+<script type="module">
+  import "@ui-sdk/web/textarea"
+</script>
+
+<form action="/messages" method="post">
+  <ui-textarea submit-shortcut="mod+enter">
+    <textarea name="message" aria-label="Message" required></textarea>
+  </ui-textarea>
+  <button type="submit">Send</button>
+</form>
+```
+
+The shortcut submits the form like the Send button, so `required` and the form's `submit` event still apply.
+
+## 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 `auto-resize`, 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
+
+### `<ui-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 attributes in kebab case, like `auto-resize` and `default-value`. `disabled`, `readonly`, `required` and other native attributes are read from the `<textarea>`. Callbacks are DOM events: `valuechange` fires on `ui-textarea` with `{ value, reason, event, source }` in `event.detail`.
+
+### Textarea
+
+- `value?` (`string`): The value, for a controlled field.
+- `defaultValue?` (`string`): The value it starts with. A form reset returns here.
+- `valuechange event`: 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.
+- `submit event`: 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
+
+The element's `api` property has these methods, and its `value` property reads and sets the text. Writes fire `valuechange` like typing.
+
+- `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,235 @@
+# 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.
+
+```ts title="time.ts"
+import "@ui-sdk/web/field"
+import "@ui-sdk/web/time-input"
+
+function mount(root: HTMLElement) {
+  root.innerHTML = `
+    <ui-field>
+      <ui-field-label>Meeting time</ui-field-label>
+      <ui-time-input default-value="09:30"></ui-time-input>
+    </ui-field>
+  `
+}
+
+export { mount }
+```
+
+Click the hour and type 230, then P. Press ArrowUp or ArrowDown on a part to step it.
+
+## Installation
+
+```bash
+npm install @ui-sdk/web @ui-sdk/core
+```
+
+Importing the component defines its elements. Import the field too if you use it. On the server the import does nothing.
+
+```ts
+import "@ui-sdk/web/time-input"
+import "@ui-sdk/web/field"
+```
+
+## Composition
+
+Use the following composition to build a `ui-time-input`:
+
+```text
+ui-time-input
+├── ui-time-input-segment
+│   └── input
+└── ui-time-input-segment
+```
+
+`<ui-time-input>` renders a group with one `<ui-time-input-segment>` 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:
+
+```html
+<script type="module">
+  import "@ui-sdk/web/time-input"
+  import "@ui-sdk/web/field"
+</script>
+
+<ui-field>
+  <ui-field-label>Meeting time</ui-field-label>
+  <ui-time-input default-value="09:30"></ui-time-input>
+</ui-field>
+```
+
+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 `hour-cycle` to `12` or `24` to choose one, and `granularity` to `"second"` to add seconds, or `"hour"` to show the hour alone.
+
+```ts title="hour-cycle.ts"
+import "@ui-sdk/web/field"
+import "@ui-sdk/web/time-input"
+
+function mount(root: HTMLElement) {
+  root.innerHTML = `
+    <div data-slot="stack">
+      <ui-field>
+        <ui-field-label>12-hour clock</ui-field-label>
+        <ui-time-input hour-cycle="12" default-value="18:45"></ui-time-input>
+      </ui-field>
+      <ui-field>
+        <ui-field-label>24-hour clock</ui-field-label>
+        <ui-time-input hour-cycle="24" default-value="18:45"></ui-time-input>
+      </ui-field>
+      <ui-field>
+        <ui-field-label>With seconds</ui-field-label>
+        <ui-time-input granularity="second" hour-cycle="24" default-value="18:45:30"></ui-time-input>
+      </ui-field>
+    </div>
+  `
+}
+
+export { mount }
+```
+
+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
+
+The element is form-associated and submits the time under `name`, with no hidden input. 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
+
+Listen for `valuechange` and set the `value` property, or drive the input with its `api`, 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
+
+### `<ui-time-input>`
+`[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.
+
+### `<ui-time-input-segment>`
+`[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 are attributes in kebab case, like `default-value`, `hour-cycle` and `read-only`. `value` is also a property, and `controller` is a property. Callbacks are DOM events.
+
+### 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.
+- `valuechange event`: 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
+
+Events fire on their own element and don't bubble, with the value in `event.detail.value` and the `reason` and `event` beside it. Calling `preventDefault()` on `valuechange` cancels the change.
+
+| Member              | On                | Description                                                             |
+| ------------------- | ----------------- | ----------------------------------------------------------------------- |
+| `value` property    | `<ui-time-input>` | The time, or null while empty or partly typed                           |
+| `api` property      | `<ui-time-input>` | The [controller](#controller)                                           |
+| `valuechange` event | `<ui-time-input>` | `detail: { value, reason, event }`, as a whole value forms or is erased |
+
+## 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.