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

package/docs/components/input.md

@@ -0,0 +1,306 @@
+# 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.
+
+```vue title="basic.vue"
+<script setup lang="ts">
+import { XIcon } from "@lucide/vue"
+import { Field, FieldDescription, FieldLabel } from "@ui-sdk/vue/field"
+import { Input, InputClear, InputGroup } from "@ui-sdk/vue/input"
+import { useLog } from "./log"
+
+const log = useLog()
+</script>
+
+<template>
+  <Field name="website">
+    <FieldLabel>Website</FieldLabel>
+    <InputGroup>
+      <span>https://</span>
+      <Input
+        placeholder="example.com"
+        default-value="hollisgrant.com"
+        @value-change="
+          (value: string, details: { reason: string }) =>
+            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>
+</template>
+```
+
+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/vue @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:
+
+```vue
+<script setup lang="ts">
+import { Input, InputClear, InputGroup } from "@ui-sdk/vue/input"
+</script>
+
+<template>
+  <InputGroup>
+    <Input type="search" aria-label="Search" />
+    <InputClear aria-label="Clear search" />
+  </InputGroup>
+</template>
+```
+
+## 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.
+
+```vue
+<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 `read-only` input can still be focused, selected and submitted.
+
+```vue
+<Field disabled>
+  <FieldLabel>Email</FieldLabel>
+  <Input type="email" default-value="hollis@example.com" />
+</Field>
+
+<Field>
+  <FieldLabel>Profile URL</FieldLabel>
+  <Input read-only 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.
+
+```vue
+<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.
+
+```vue
+<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.
+
+```vue
+<InputGroup>
+  <Input type="search" aria-label="Search people" />
+  <InputClear aria-label="Clear search">
+    <XIcon aria-hidden="true" />
+  </InputClear>
+</InputGroup>
+```
+
+## Controlled
+
+Bind the value with `v-model` to control the input. `@value-change` also receives the change details, and native `@input` still works.
+
+```vue
+<script setup lang="ts">
+const name = ref("Hollis Grant")
+</script>
+
+<template>
+  <Input v-model="name" />
+</template>
+```
+
+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 `@value-change` to reject a change. The previous text and caret position are restored.
+
+```vue
+<Input
+  inputmode="numeric"
+  :maxlength="6"
+  @value-change="
+    (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 events as typing.
+
+```vue
+<script setup lang="ts">
+const message = createInputController()
+</script>
+
+<template>
+  <Input :controller="message" aria-label="Message" />
+  <button @click="message.setValue('On my way!')">Quick Reply</button>
+  <button @click="message.clear()">Clear</button>
+  <button @click="message.focus()">Focus</button>
+</template>
+```
+
+[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, plus every native input attribute. `onValueChange` is `v-model`, or `@value-change` for the reason.
+
+### Input
+
+- `value?` (`string`): The value, for a controlled field.
+- `defaultValue?` (`string`): The value it starts with. A form reset returns here.
+- `@value-change` (`((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,203 @@
+# 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 `for`, including a radio group or a slider, and a press on the label moves focus into it.
+
+```vue title="basic.vue"
+<script setup lang="ts">
+import { Label } from "@ui-sdk/vue/label"
+import { Radio, RadioGroup, RadioIndicator } from "@ui-sdk/vue/radio"
+
+const speeds = [
+  { value: "standard", label: "Standard" },
+  { value: "express", label: "Express" },
+  { value: "overnight", label: "Overnight" },
+]
+</script>
+
+<template>
+  <div data-slot="stack">
+    <Label for="shipping-speed">Shipping speed</Label>
+    <RadioGroup id="shipping-speed" default-value="standard">
+      <Label v-for="speed in speeds" :key="speed.value">
+        <Radio :value="speed.value">
+          <RadioIndicator />
+        </Radio>
+        {{ speed.label }}
+      </Label>
+    </RadioGroup>
+  </div>
+</template>
+```
+
+Press Shipping speed. Focus moves to the checked option, and a screen reader names the group Shipping speed.
+
+## Installation
+
+```bash
+npm install @ui-sdk/vue @ui-sdk/core
+```
+
+## Usage
+
+Import the label and point its `for` at the control's `id`:
+
+```vue
+<script setup lang="ts">
+import { Label } from "@ui-sdk/vue/label"
+import { Radio, RadioGroup } from "@ui-sdk/vue/radio"
+</script>
+
+<template>
+  <Label for="plan">Plan</Label>
+  <RadioGroup id="plan" default-value="pro">
+    <Radio value="free">Free</Radio>
+    <Radio value="pro">Pro</Radio>
+  </RadioGroup>
+</template>
+```
+
+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/vue/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"
+import { label } from "@ui-sdk/core/label"
+import { createParts } from "@ui-sdk/vue/primitive"
+
+const { Root: Caption } = createParts(label, { root: "label" })
+
+export { Caption }
+```
+
+```vue
+<template>
+  <Caption for="plan">Plan</Caption>
+</template>
+```
+
+`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.
+
+```vue title="slider.vue"
+<script setup lang="ts">
+import { Label } from "@ui-sdk/vue/label"
+import {
+  Slider,
+  SliderControl,
+  SliderIndicator,
+  SliderThumb,
+  SliderTrack,
+  SliderValue,
+} from "@ui-sdk/vue/slider"
+</script>
+
+<template>
+  <Slider id="volume" :default-value="75">
+    <div data-slot="row">
+      <Label for="volume">Volume</Label>
+      <SliderValue />
+    </div>
+    <SliderControl>
+      <SliderTrack>
+        <SliderIndicator />
+        <SliderThumb />
+      </SliderTrack>
+    </SliderControl>
+  </Slider>
+</template>
+```
+
+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.
+
+```vue title="switch.vue"
+<script setup lang="ts">
+import { Label } from "@ui-sdk/vue/label"
+import { Switch, SwitchThumb } from "@ui-sdk/vue/switch"
+</script>
+
+<template>
+  <div data-slot="row">
+    <Switch id="updates">
+      <SwitchThumb />
+    </Switch>
+    <Label for="updates">Email me product updates</Label>
+  </div>
+</template>
+```
+
+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`.
+
+```vue title="wrap.vue"
+<script setup lang="ts">
+import { CheckIcon } from "@lucide/vue"
+import { Checkbox, CheckboxIndicator } from "@ui-sdk/vue/checkbox"
+import { Label } from "@ui-sdk/vue/label"
+</script>
+
+<template>
+  <Label>
+    <Checkbox>
+      <CheckboxIndicator>
+        <CheckIcon aria-hidden="true" />
+      </CheckboxIndicator>
+    </Checkbox>
+    Accept terms and conditions
+  </Label>
+</template>
+```
+
+Press Accept terms and conditions. The checkbox checks, and a double click doesn't select the text.
+
+## Custom Rendering
+
+Use the `#render` slot to use a different element, such as a `<span>`, and bind the supplied `props` to it. 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, along with a native label's `for`.
+
+### 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.