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

package/docs/components/input.md

@@ -0,0 +1,301 @@
+# Input
+
+Enter text, add a clear button, and connect the value to your form or state.
+
+An input is a native text field for short values like a name, an email address or a search. It works inside a field and a form, and adds a clear button, text around the input, and change reasons.
+
+```tsx title="basic.tsx"
+import { Field, FieldDescription, FieldLabel } from "@ui-sdk/react/field"
+import { Input, InputClear, InputGroup } from "@ui-sdk/react/input"
+import { XIcon } from "lucide-react"
+import { useLog } from "./log"
+
+function Example() {
+  const log = useLog()
+
+  return (
+    <Field name="website">
+      <FieldLabel>Website</FieldLabel>
+      <InputGroup>
+        <span>https://</span>
+        <Input
+          placeholder="example.com"
+          defaultValue="hollisgrant.com"
+          onValueChange={(value, details) =>
+            log(`${value ? `“${value}”` : "Empty"} (${details.reason})`)
+          }
+        />
+        <InputClear aria-label="Clear website">
+          <XIcon aria-hidden="true" />
+        </InputClear>
+      </InputGroup>
+      <FieldDescription>Shown on your public profile.</FieldDescription>
+    </Field>
+  )
+}
+
+export { Example }
+```
+
+Edit the website, then press Clear website. The text clears, focus returns to the input and the console logs the reason. Pressing https:// focuses the input too.
+
+## Installation
+
+```bash
+npm install @ui-sdk/react @ui-sdk/core
+```
+
+## Composition
+
+Use the following composition to build an `Input` or an `InputGroup`:
+
+```text
+Input
+
+InputGroup
+├── Input
+└── InputClear
+```
+
+`Input` renders a native `<input>`. Pass its type, placeholder, autocomplete and other native attributes directly. `InputGroup` holds text or buttons around it, and `InputClear` empties it.
+
+## Usage
+
+Import the parts and put them together:
+
+```tsx
+import { Input, InputClear, InputGroup } from "@ui-sdk/react/input"
+
+function Example() {
+  return (
+    <InputGroup>
+      <Input type="search" aria-label="Search" />
+      <InputClear aria-label="Clear search" />
+    </InputGroup>
+  )
+}
+
+export { Example }
+```
+
+## Fields
+
+Wrap the input in a [Field](./field.md) to give it a visible label, a description and errors. The field also supplies its `name` when the input has none.
+
+```tsx
+<Field name="username">
+  <FieldLabel>Username</FieldLabel>
+  <Input autoComplete="username" />
+  <FieldDescription>
+    Choose a unique username for your account.
+  </FieldDescription>
+</Field>
+```
+
+## Disabled and Read Only
+
+Set `disabled` on the input or its field to prevent editing and leave it out of the tab order and the submitted values. A `readOnly` input can still be focused, selected and submitted.
+
+```tsx
+<Field disabled>
+  <FieldLabel>Email</FieldLabel>
+  <Input type="email" defaultValue="hollis@example.com" />
+</Field>
+
+<Field>
+  <FieldLabel>Profile URL</FieldLabel>
+  <Input readOnly value="example.com/hollis" />
+</Field>
+```
+
+## Validation
+
+Use native constraints such as `required`, `type="email"` and `pattern`. The field shows its error after a submit attempt and updates it as the value changes. Set `invalid` on the field for an error your app decides; the input gets `aria-invalid`. [Field](./field.md#validation) covers the error parts and their matches.
+
+```tsx
+<Field name="email" invalid={emailTaken ? true : undefined}>
+  <FieldLabel>Email</FieldLabel>
+  <Input type="email" required />
+  <FieldError match="valueMissing">Enter your email address.</FieldError>
+  <FieldError match>That email is already in use.</FieldError>
+</Field>
+```
+
+## Input Group
+
+Place text or buttons around an input with `InputGroup`. Pressing the group's text focuses the input. The text is display content, not part of the submitted value.
+
+```tsx
+<InputGroup>
+  <span>https://</span>
+  <Input aria-label="Website" placeholder="example" />
+  <span>.com</span>
+</InputGroup>
+```
+
+## Clear Button
+
+`InputClear` shows while the input has text it can clear. Pressing it empties the value, reports `clear-press` and returns focus to the input. Controlled state and native input listeners receive the change too.
+
+```tsx
+<InputGroup>
+  <Input type="search" aria-label="Search people" />
+  <InputClear aria-label="Clear search">
+    <XIcon aria-hidden="true" />
+  </InputClear>
+</InputGroup>
+```
+
+## Controlled
+
+Pass `value` and `onValueChange` to control the input. Native `onChange` still works.
+
+```tsx
+const [name, setName] = React.useState("Hollis Grant")
+
+<Input value={name} onValueChange={(value) => setName(value)} />
+```
+
+See [State and Events](../state-and-events.md) for the shared controlled-state conventions. Input's [reasons](#reasons) tell typing, clearing, resetting and controller changes apart.
+
+## Filtering What's Typed
+
+Call `details.cancel()` in the value-change callback to reject a change. The previous text and caret position are restored.
+
+```tsx
+<Input
+  inputMode="numeric"
+  maxLength={6}
+  onValueChange={(value, details) => {
+    if (!/^\d*$/.test(value)) details.cancel()
+  }}
+/>
+```
+
+## Controller
+
+Use `createInputController()` for actions outside the input. Its methods update the input through the same change callbacks as typing.
+
+```tsx
+const [message] = React.useState(createInputController)
+
+<Input controller={message} aria-label="Message" />
+<button onClick={() => message.setValue("On my way!")}>Quick Reply</button>
+<button onClick={() => message.clear()}>Clear</button>
+<button onClick={() => message.focus()}>Focus</button>
+```
+
+[Controllers](../controllers.md) covers creating and sharing a controller.
+
+## Passwords and Files
+
+Use [Password Input](./password-input.md) to show and hide a password. A native file input works with `type="file"`; use [File Input](./file-input.md) for dropping, previews and validation.
+
+## Styling
+
+Each part has a `data-slot`, such as `input-group`, and shows its state through the attributes listed under [Data Attributes](#data-attributes). Use `data-filled`, `data-disabled`, `data-readonly` and `data-required` on the input, and the field's validation and focus attributes inside a field. For a group's focus ring, style `:has(input:focus-visible)`, so a focused button inside it keeps its own ring.
+
+## Data Attributes
+
+### Input
+`[data-slot="input"]`
+
+- `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.
+
+### InputGroup
+`[data-slot="input-group"]`
+
+- `data-filled`: Present while the field in the group holds any text.
+- `data-disabled`: Present while the field in the group is disabled, by itself or a `<fieldset>`.
+- `data-readonly`: Present while the field in the group is read-only.
+
+### InputClear
+`[data-slot="input-clear"]`
+
+- `data-filled`: Present while the field in the group holds any text.
+- `data-disabled`: Present while the field in the group is disabled, by itself or a `<fieldset>`.
+- `data-readonly`: Present while the field in the group is read-only.
+
+## API Reference
+
+Props are the same as below, as React props, plus every native input prop.
+
+### Input
+
+- `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.
+
+- `disabled?` (`boolean`): Disables the field.
+- `readOnly?` (`boolean`): Makes the field read-only.
+- `required?` (`boolean`): Makes the field required.
+
+### InputGroup
+
+- `debug?` (`boolean`): Logs every state change with its reason to the console, in development builds.
+
+### InputClear
+
+A `<button>` that empties the input in its group and focuses it. It renders only while there's text to clear.
+
+### 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.
+
+`InputGroup` and `InputClear` receive the state of the input inside the group.
+
+- `filled` (`boolean`): Whether the field in the group holds any text.
+- `disabled` (`boolean`): Whether the field in the group is disabled, by itself or by a `<fieldset>`.
+- `readOnly` (`boolean`): Whether the field in the group is read-only.
+
+### 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
+
+Give the input a visible field label or an `aria-label`, and give the clear button an accessible name. The native input keeps standard text editing, selection, autocomplete and form behavior.
+
+- The label names the input and the description describes it.
+- Clicking the label focuses the input.
+- An invalid input is marked once the form tries to submit.
+- Data-filled follows the text.
+- An input group's clear button shows only while there's text.
+- <ui-input>'s value property writes the field quietly, and its api reports. Web components only.
+
+**Enhancements**
+
+- Changes report their reason: typing, then a reset.
+- A canceled change keeps the text as it was.
+- A canceled change keeps a controlled input's text as it was.
+- A canceled change waits for an IME to finish before the text goes back.
+- A controlled input keeps every keystroke.
+- A required input marks its label required.
+
+**Input group**
+
+- The clear button empties the field, reports why, and returns focus.
+- Pressing the group's text focuses its field.
+- The clear button hides while its field is disabled.
+
+Runs in React, Vue and web components.

package/docs/components/label.md

@@ -0,0 +1,217 @@
+# Label
+
+Name any control with a label, and let a press on the label reach it.
+
+A plain `<label>` only reaches inputs, buttons and selects. Label names any control by its `htmlFor`, including a radio group or a slider, and a press on the label moves focus into it.
+
+```tsx title="basic.tsx"
+import { Label } from "@ui-sdk/react/label"
+import { Radio, RadioGroup, RadioIndicator } from "@ui-sdk/react/radio"
+
+const speeds = [
+  { value: "standard", label: "Standard" },
+  { value: "express", label: "Express" },
+  { value: "overnight", label: "Overnight" },
+]
+
+function Example() {
+  return (
+    <div data-slot="stack">
+      <Label htmlFor="shipping-speed">Shipping speed</Label>
+      <RadioGroup id="shipping-speed" defaultValue="standard">
+        {speeds.map((speed) => (
+          <Label key={speed.value}>
+            <Radio value={speed.value}>
+              <RadioIndicator />
+            </Radio>
+            {speed.label}
+          </Label>
+        ))}
+      </RadioGroup>
+    </div>
+  )
+}
+
+export { Example }
+```
+
+Press Shipping speed. Focus moves to the checked option, and a screen reader names the group Shipping speed.
+
+## Installation
+
+```bash
+npm install @ui-sdk/react @ui-sdk/core
+```
+
+## Usage
+
+Import the label and point its `htmlFor` at the control's `id`:
+
+```tsx
+import { Label } from "@ui-sdk/react/label"
+import { Radio, RadioGroup } from "@ui-sdk/react/radio"
+
+function Plan() {
+  return (
+    <>
+      <Label htmlFor="plan">Plan</Label>
+      <RadioGroup id="plan" defaultValue="pro">
+        <Radio value="free">Free</Radio>
+        <Radio value="pro">Pro</Radio>
+      </RadioGroup>
+    </>
+  )
+}
+
+export { Plan }
+```
+
+Label renders a native `<label>`. When the browser can reach the control on its own, like an input, it does. For anything else, the control takes the label as its name, and a press on the label focuses it, checks it or clicks it, as a native label would.
+
+Inside a [Field](./field.md), use `FieldLabel`, which also ties the field's description and errors to the control.
+
+## Build Your Own
+
+`@ui-sdk/react/label` comes with a ready-made Label. If you'd like to build your own, with your own name, start from the `label` primitive in `@ui-sdk/core`:
+
+```ts title="caption.ts"
+"use client"
+
+import { label } from "@ui-sdk/core/label"
+import { createParts } from "@ui-sdk/react/primitive"
+
+const { Root: Caption } = createParts(label, { root: "label" })
+
+export { Caption }
+```
+
+```tsx
+<Caption htmlFor="plan">Plan</Caption>
+```
+
+`Caption` keeps the behavior of the ready-made Label: it names the control and reaches it on a press. See [Rendering](../rendering.md) and [Custom Parts](../custom-parts.md) for more.
+
+## Slider
+
+A label for a slider names its thumb, so the thumb reads as **Volume**, and a press on the label focuses it.
+
+```tsx title="slider.tsx"
+import { Label } from "@ui-sdk/react/label"
+import {
+  Slider,
+  SliderControl,
+  SliderIndicator,
+  SliderThumb,
+  SliderTrack,
+  SliderValue,
+} from "@ui-sdk/react/slider"
+
+function Example() {
+  return (
+    <Slider id="volume" defaultValue={75}>
+      <div data-slot="row">
+        <Label htmlFor="volume">Volume</Label>
+        <SliderValue />
+      </div>
+      <SliderControl>
+        <SliderTrack>
+          <SliderIndicator />
+          <SliderThumb />
+        </SliderTrack>
+      </SliderControl>
+    </Slider>
+  )
+}
+
+export { Example }
+```
+
+Press Volume, then use the arrow keys. The thumb moves, and a screen reader reads it as Volume.
+
+## Switch
+
+Point the label at a switch beside it. A press on the label turns the switch on and off.
+
+```tsx title="switch.tsx"
+import { Label } from "@ui-sdk/react/label"
+import { Switch, SwitchThumb } from "@ui-sdk/react/switch"
+
+function Example() {
+  return (
+    <div data-slot="row">
+      <Switch id="updates">
+        <SwitchThumb />
+      </Switch>
+      <Label htmlFor="updates">Email me product updates</Label>
+    </div>
+  )
+}
+
+export { Example }
+```
+
+Press Email me product updates. The switch turns on.
+
+## Wrapping a Control
+
+Put the control inside the label instead of pointing at it, and you need no `id`.
+
+```tsx title="wrap.tsx"
+import { Checkbox, CheckboxIndicator } from "@ui-sdk/react/checkbox"
+import { Label } from "@ui-sdk/react/label"
+import { CheckIcon } from "lucide-react"
+
+function Example() {
+  return (
+    <Label>
+      <Checkbox>
+        <CheckboxIndicator>
+          <CheckIcon aria-hidden="true" />
+        </CheckboxIndicator>
+      </Checkbox>
+      Accept terms and conditions
+    </Label>
+  )
+}
+
+export { Example }
+```
+
+Press Accept terms and conditions. The checkbox checks, and a double click doesn't select the text.
+
+## Custom Rendering
+
+Pass `render` to use a different element, such as `render={<span />}`. A label that isn't a `<label>` still names its control and reaches it on a press. See [Parts and Composition](../parts-and-composition.md) for more.
+
+## Styling
+
+The label is unstyled. It has a `data-slot` of `label`.
+
+A double click on the label doesn't select its text, so you don't need `user-select: none` for that.
+
+## API Reference
+
+Props are the same as below, as React props, along with a native label's `htmlFor`.
+
+### Label
+
+- `debug?` (`boolean`): Logs every state change with its reason to the console, in development builds.
+
+## Accessibility
+
+A native `<label>` names the element its `for` points at only when that element is labelable, like an input or a button. Label names any other control through `aria-labelledby`, unless the control has an `aria-label` or an `aria-labelledby` of its own, which win. Its press does what a native label's does: it checks a checkbox, a switch or a radio, focuses a group's checked radio, and focuses anything else. A press on a disabled control does nothing.
+
+### Tested Behavior
+
+Every line below is an automated test.
+
+- A label names a native input, and a press focuses it.
+- A label names a radio group, and a press focuses its checked radio.
+- A label for a slider names its thumb, and a press focuses it.
+- A label around a checkbox names it, and a press toggles it.
+- A press on the label of a disabled group moves no focus.
+- A control its author names keeps that name.
+- A label names a control that renders after it.
+- A double click on a label doesn't select its text.
+
+Runs in React, Vue and web components.