@lumiose/ui 0.0.0-stage → 0.1.1

package/docs/field.md

@@ -0,0 +1,295 @@
+# Field
+
+> A form field: a label, a native control, a description and its errors, wired with `for`, `aria-describedby` and `aria-invalid`, after Base UI's Field. Validation is the browser's constraint validation (`required`, `type`, `pattern`, `minlength`…); a 1.7 kB script shows it in the field's Error parts at the right time, instead of the browser's bubble, and focuses the first invalid field on submit. A Form's server errors render in the HTML, so they work without JavaScript. In an island, `validate` adds checks of your own, async ones included, and `Field.Validity` renders from the field's validity.
+
+```ts
+import { Field } from "@lumiose/ui"; // or "@lumiose/ui/field"
+import "@lumiose/ui/field.css"; // makes <lu-field> a block, keeps hidden errors hidden
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<Field.Root>
+  <Field.Label />
+  <Field.Control />
+  <Field.Description />
+  <Field.Error />
+  <Field.Validity />
+</Field.Root>
+```
+
+| Part          | Renders                                                                                                                                      |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Root`        | `<lu-field>`, a block around the other parts, with `validation-mode`.                                                                        |
+| `Label`       | `<label for="…">`, pointing at the control.                                                                                                  |
+| `Control`     | `<input>`: [Input](input.md), with the field's `id`, `name`, `aria-describedby` and `aria-invalid`.                                          |
+| `Description` | `<p>` that describes the control; several get ids of their own, and the control is described by each.                                        |
+| `Error`       | `<output hidden>`: without children, the field's message (`for` the control); with children, your message. Shown while the field is invalid. |
+| `Validity`    | No element: what its function child returns for the field's validity, in an island.                                                          |
+
+Instead of `Field.Control`, a field can hold a [Checkbox](checkbox.md), a [Switch](switch.md), a
+[Select](select.md), a [Radio Group](radio-group.md), a [Checkbox Group](checkbox-group.md), a
+[Combobox](combobox.md), an [Autocomplete](autocomplete.md), a [Number Field](number-field.md) or a
+[Slider](slider.md): they take the field's wiring the same way (a Combobox and an Autocomplete
+through their input). A Radio Group or Checkbox Group takes it as a group: `Field.Label` names the
+group (`aria-labelledby`, as there is no single radio or checkbox for its `for`), and the group,
+not each control, gets `aria-describedby` and `aria-invalid`.
+
+## API
+
+### Field.Root
+
+| Prop                     | Type                                           | Default      |                                                                                                                                                                |
+| ------------------------ | ---------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`                   | `string`                                       |              | The control's `name` (unless it has its own), and the key of the field's errors in the Form's `errors`.                                                        |
+| `disabled`               | `boolean`                                      | `false`      | Disables the control.                                                                                                                                          |
+| `invalid`                | `boolean`                                      | `false`      | Marks the field invalid, as a server error does: its Error shows and the control gets `aria-invalid`, until the value changes.                                 |
+| `validationMode`         | `"onSubmit" \| "onBlur" \| "onChange"`         | `"onSubmit"` | When errors show: after a submit attempt, also when the control loses focus, or as soon as it is edited. Once shown, they follow the value.                    |
+| `validate`               | `(value: string \| boolean) => string \| null` |              | Your own check, run on every edit in an island: return a message when the value is invalid. It becomes the control's custom validity. It may return a promise. |
+| `validationDebounceTime` | `number`                                       | `0`          | How long typing must pause before `validate` runs, in ms: fewer server checks while the user types.                                                            |
+
+`Root` passes `class`, `style` and other element props to `<lu-field>`. A Form's `validationMode`
+applies to the fields that set none.
+
+### Field.Error
+
+| Prop       | Type                          | Default |                                                                                                        |
+| ---------- | ----------------------------- | ------- | ------------------------------------------------------------------------------------------------------ |
+| `match`    | `keyof ValidityState \| true` |         | Shows only for that problem (`"valueMissing"`, `"typeMismatch"`, `"tooShort"`, …), or always (`true`). |
+| `children` | `JSX.Element`                 |         | Your message. Without children, the Error shows the server's message or the browser's.                 |
+
+### Async validate
+
+`validate` may return a promise of the message: a check on the server, such as whether a username
+is taken.
+
+- **The latest edit wins.** Each edit starts a new check; an older check that settles later is
+  dropped, so a slow answer never overwrites a newer one.
+- **While it runs**, the control has no custom error (the last verdict was about another value),
+  `<lu-field>` has `data-validating`, and `Field.Validity` reports `validating: true`. When it
+  settles, its message becomes the control's custom validity, and the field shows it if it shows
+  its errors by then (with `validationMode="onChange"`, at once).
+- **A submit that comes first is not blocked**, as in Base UI: validate on the server too (a
+  Form action's `fail()`). A check that rejects (the network) counts as no error.
+- **One check per value.** The `change` a blur fires after an edit does not check the same value
+  again; `validationDebounceTime` waits for a pause in typing before it checks. A submit attempt
+  inside that pause runs the waiting check first: a synchronous `validate` that fails stops the
+  submission and shows its message (an async one, as above, does not block it).
+- The check runs once, quietly, when the island starts and after a form reset (`Field.Validity`
+  stays unchecked).
+
+### Field.Validity
+
+| Prop       | Type                                         |                                                    |
+| ---------- | -------------------------------------------- | -------------------------------------------------- |
+| `children` | `(state: FieldValidityState) => JSX.Element` | Renders from the state, again whenever it changes. |
+
+`FieldValidityState` holds `validity` (the control's `ValidityState` keys, with `valid` `null`
+until the first check, or `false` from a server error), `error` (the first problem's message, or
+`""`), `errors` (every message: the server's, or `error`), `value` (the control's value, or
+`checked`) and `validating` (an async `validate` is running). It updates on every edit, blur and
+submit attempt, whatever the `validationMode`, and when a `validate` result or a server error
+arrives; a form reset makes it unchecked again. On the server, and without JavaScript, it renders
+the unchecked state (or the server's error) once.
+
+### Field.Control
+
+[Input](input.md)'s props: every native `<input>` prop, plus `value`, `defaultValue`,
+`onValueChange` and `bind:value`.
+
+### The other parts
+
+`Label` and `Description` take the props of the element they render (`class`, `style`, `aria-*`)
+and pass them through; their `id` and `for` stay the field's.
+
+**Differences from Base UI's Field.** The control is native and so is validation: `validate`
+returns one message (not a list) and gets no other form values, and there is no `dirty`, `touched`,
+`actionsRef` or `Field.Item`. State is exposed the platform's way, `aria-invalid` on the control
+and `:user-invalid`, `:invalid`, `:focus-within` in CSS, rather than Base UI's `data-dirty`,
+`data-touched` and friends. `Field.Error` renders an `<output>`, not a `<div>`.
+
+## Example
+
+An email field in a server-rendered page, with no island:
+
+```tsx check
+import { Field } from "@lumiose/ui";
+
+export function EmailField() {
+  return (
+    <form method="post">
+      <Field.Root name="email" validationMode="onBlur" class="lu-field">
+        <Field.Label>Email</Field.Label>
+        <Field.Control type="email" required autocomplete="email" class="lu-input" />
+        <Field.Description>We never share it.</Field.Description>
+        <Field.Error match="valueMissing">Enter your email.</Field.Error>
+        <Field.Error match="typeMismatch">Enter an email like ada@example.com.</Field.Error>
+      </Field.Root>
+      <button class="lu-button">Subscribe</button>
+    </form>
+  );
+}
+```
+
+With a form action, a [Form](form.md)'s `errors` (the data the action passes to `fail()`) show in
+the field of the same `name`, in the page the server renders back:
+
+```tsx check
+import { Field, Form } from "@lumiose/ui";
+
+export function UsernameField(props: { errors?: { username?: string } }) {
+  return (
+    <Form method="post" errors={props.errors}>
+      <Field.Root name="username" class="lu-field">
+        <Field.Label>Username</Field.Label>
+        <Field.Control required minlength={3} class="lu-input" />
+        <Field.Error />
+      </Field.Root>
+      <button class="lu-button">Sign up</button>
+    </Form>
+  );
+}
+```
+
+In an island, an async `validate` asks the server while the user types, and `Field.Validity`
+shows its state:
+
+```tsx check
+import { Field } from "@lumiose/ui";
+
+const TAKEN = ["admin", "lumiose"];
+
+/** A server check, here a delay and a list: a `fetch` in a real form. */
+async function available(value: string | boolean) {
+  await new Promise((resolve) => setTimeout(resolve, 300));
+  return TAKEN.includes(String(value)) ? "That handle is taken." : null;
+}
+
+export function HandleField() {
+  return (
+    <Field.Root
+      name="handle"
+      validationMode="onChange"
+      validationDebounceTime={300}
+      validate={available}
+      class="lu-field"
+    >
+      <Field.Label>Handle</Field.Label>
+      <Field.Control required class="lu-input" />
+      <Field.Error />
+      <Field.Validity>
+        {(state) => (
+          <p>
+            {state.validating ? "Checking…" : state.validity.valid ? `${state.value} is free.` : ""}
+          </p>
+        )}
+      </Field.Validity>
+    </Field.Root>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-field` on `Root` and `lu-input` on the control: the parts
+stack with a small gap, the label is medium weight, the description muted, the errors red (a
+lighter red in dark, to keep 4.5:1), and an invalid control gets a red border.
+
+**With your own CSS**, style the parts through `class` and state:
+
+- the control: `[aria-invalid="true"]` while an error shows, `:user-invalid` (invalid after the
+  user interacted), `:invalid`, `:focus-visible`, `:disabled`;
+- the field: `lu-field:has([aria-invalid="true"])`, `lu-field:focus-within`, and
+  `lu-field[data-validating]` while an async `validate` runs;
+- the errors: `output` in the field (`[hidden]` while they do not apply).
+
+```css
+.field {
+  display: grid;
+  gap: 0.25rem;
+}
+.field [aria-invalid="true"] {
+  border-color: #dc2626;
+}
+.field output {
+  color: #b91c1c;
+  font-size: 0.875rem;
+}
+```
+
+`@lumiose/ui/field.css` holds what Field needs to work, in the `lu.core` layer: `lu-field` is a
+block, and the errors the script hides stay hidden whatever `display` your CSS gives them.
+
+## Keyboard and focus
+
+The control's own keyboard. Field adds focus on a submit attempt: the first invalid control of the
+form, in DOM order, takes focus, and its error is part of its accessible description, so a screen
+reader reads it there.
+
+- **On a submit attempt**, every invalid field shows its errors; the browser's bubble does not
+  appear for a field with an Error part that shows the problem. A problem none of its Errors
+  match (a missing value where the only Error has `match="tooShort"`) still gets the bubble.
+- **`validationMode="onBlur"`** shows a field's error when focus leaves it, except a missing value
+  in a field the user has not edited yet (Base UI's rule). **`"onChange"`** shows it as the user
+  types.
+- **Once shown**, an error follows the value: it updates as the problem changes and goes away when
+  the value is valid. A server error goes away as soon as the value changes, and shows again
+  each time an action fails with it, the same message included.
+- **A form reset** hides every error.
+
+## Without JavaScript, and the field's script
+
+The control, its `for` label and its constraints are native: the browser validates on submit and
+reports the first problem in its own bubble, and the form submits when everything is valid. Server
+errors from a Form render in the HTML, visible and linked with `aria-describedby` and
+`aria-invalid`.
+
+Two limits of the server HTML, which the script corrects once it runs (decision-62): the server
+writes the control's attributes before it renders the parts after it, so a Description below the
+control is linked only by the script, and an invalid field's control points `aria-describedby` at
+the message Error's id (`Field.Error` without children or `match`) even when the field only has
+Errors with children or a `match`. Give a field that must read well without JavaScript a message
+Error, and its Descriptions before the control.
+
+A page that renders a `Field` loads a 1.7 kB (brotli) script once, without the Lumiose runtime;
+islands bundle it. On a submit attempt (a submit button, Enter in a field, `requestSubmit()` or
+the form's `reportValidity()`; a silent `checkValidity()` changes nothing) it cancels the browser's
+`invalid` bubble for fields that have an Error part for the problem and shows it there instead (the
+browser's message, or one your `validate` set), with the timing above, and focuses the first
+invalid control, with no bubble on a later control outside a field. A form action's errors move
+focus to the first field that shows one, when the page renders back (unless an `autofocus` element
+has it) and when an island's errors arrive. It also keeps `aria-invalid` and
+`aria-describedby` current (a description rendered after the control is linked once the script
+runs), and hides server errors once the value changes. When an async `validate` settles, Field.Root
+fires `validitychange` (not bubbling) on the control, and the script shows the new verdict. When a
+form action's errors arrive in an island, Field.Root fires it on `<lu-field>` with the messages
+(`detail.errors`), and the script shows them as the server's, even when they repeat.
+
+**`requestSubmit()` and `reportValidity()`.** The browser fires the same `invalid` events for a
+silent `checkValidity()` as for a submit attempt, and only a submit attempt should show errors and
+move focus. A submit button's click and Enter are seen as they happen; the two methods are not, so
+the script wraps `HTMLFormElement.prototype.requestSubmit` and `reportValidity` once, when it
+loads. The wrappers only mark the form as attempting a submit for the duration of the call, and
+then call the browser's own method with the same `this`, arguments and return value, throwing what
+it throws (decision-62).
+
+## Browser support
+
+- **Constraint validation**, `:user-invalid` (Chrome 119, Firefox 88, Safari 16.5) and the
+  `invalid` event: in every supported browser.
+- **`<output for>`**: in every browser; Chromium and screen readers include an output's text in
+  the control's description. Playwright's own `toHaveAccessibleDescription` leaves it out; the
+  @lumiose/ui tests read Chromium's computation instead.
+
+## Related
+
+- [Form](form.md): server errors for the fields, by name.
+- [Input](input.md): `Field.Control`.
+- [Fieldset](fieldset.md): a group of fields with a legend.
+- [Checkbox](checkbox.md), [Switch](switch.md), [Radio Group](radio-group.md),
+  [Select](select.md), [Combobox](combobox.md), [Autocomplete](autocomplete.md),
+  [Number Field](number-field.md), [Slider](slider.md): controls that take a field's wiring.
+- [Data and actions](https://itsjavi.com/lumiose/docs/concepts/data-and-actions/): form actions,
+  `fail()` and `actionData()`.

package/docs/fieldset.md

@@ -0,0 +1,92 @@
+# Fieldset
+
+> A group of related fields with a caption: a native `<fieldset>` and `<legend>`, after Base UI's Fieldset. The browser names the group by its legend and disables every control inside a disabled fieldset, with no JavaScript and no CSS of its own. The legend also names a Checkbox Group or a Radio Group.
+
+```ts
+import { Fieldset } from "@lumiose/ui"; // or "@lumiose/ui/fieldset"
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<Fieldset.Root>
+  <Fieldset.Legend />
+</Fieldset.Root>
+```
+
+| Part     | Renders                                             |
+| -------- | --------------------------------------------------- |
+| `Root`   | `<fieldset>`, a group (`role="group"`).             |
+| `Legend` | `<legend>`, which names the group; the first child. |
+
+## API
+
+### Fieldset.Root
+
+| Prop       | Type      | Default |                                                                               |
+| ---------- | --------- | ------- | ----------------------------------------------------------------------------- |
+| `disabled` | `boolean` | `false` | Disables every control inside, except those in its legend; none is submitted. |
+
+Every other `<fieldset>` prop (`form`, `name`, `class`, `aria-*`) passes through.
+
+### Fieldset.Legend
+
+The `<legend>`'s props pass through. Put it first in the fieldset, or first in a
+[CheckboxGroup](checkbox-group.md) or [RadioGroup](radio-group.md), which render a fieldset too.
+
+**Differences from Base UI's Fieldset.** `Legend` is a native `<legend>` (Base UI renders a
+`<div>` labelling the fieldset), so the group is named without ARIA.
+
+## Example
+
+```tsx check
+import { Field, Fieldset } from "@lumiose/ui";
+
+export function AddressFields() {
+  return (
+    <Fieldset.Root class="lu-fieldset">
+      <Fieldset.Legend>Shipping address</Fieldset.Legend>
+      <Field.Root name="street" class="lu-field">
+        <Field.Label>Street</Field.Label>
+        <Field.Control autocomplete="street-address" class="lu-input" />
+      </Field.Root>
+      <Field.Root name="city" class="lu-field">
+        <Field.Label>City</Field.Label>
+        <Field.Control autocomplete="address-level2" class="lu-input" />
+      </Field.Root>
+    </Fieldset.Root>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-fieldset` on `Root`: no border or padding, the legend
+semi-bold, the fields in a column.
+
+**With your own CSS**, style the `fieldset` and `legend`, and `:disabled` (`fieldset:disabled`
+matches a disabled fieldset; its controls match `:disabled`). A fieldset's minimum width defaults
+to its content's: set `min-inline-size: 0` to let it shrink.
+
+Fieldset ships no stylesheet: it needs none to work.
+
+## Keyboard and focus
+
+The controls' own. A fieldset is not focusable; a disabled fieldset takes its controls out of the
+tab order. Screen readers announce the legend when focus enters the group.
+
+## Without JavaScript
+
+Everything is native: the group, its name, and `disabled`, in server HTML. No script.
+
+## Browser support
+
+`<fieldset>`, `<legend>` and `fieldset[disabled]`: every browser.
+
+## Related
+
+- [Field](field.md): the fields inside.
+- [Checkbox Group](checkbox-group.md) and [Radio Group](radio-group.md): groups of choices, named
+  by a `Fieldset.Legend`.
+- [Form](form.md).

package/docs/form.md

@@ -0,0 +1,131 @@
+# Form
+
+> A native `<form>` that hands its fields the server's errors, after Base UI's Form. Pass the data a form action gives `fail()` as `errors`, and each [Field](field.md) shows the message for its `name`, in the HTML the server renders back (no JavaScript needed) or, with `submit()`, in an island. Submission, validation and the first invalid field's focus are the platform's and Field's.
+
+```ts
+import { Form } from "@lumiose/ui"; // or "@lumiose/ui/form"
+```
+
+## Anatomy
+
+```tsx
+<Form>
+  <Field.Root />
+</Form>
+```
+
+| Part   | Renders                               |
+| ------ | ------------------------------------- |
+| `Form` | `<form>`, with the props it is given. |
+
+## API
+
+### Form
+
+| Prop             | Type                                                              | Default      |                                                                                                                                            |
+| ---------------- | ----------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `errors`         | `object`                                                          |              | The server's errors by field name: a message or several for each `Field.Root` `name`, such as `actionData()` after a `fail()`.             |
+| `validationMode` | `"onSubmit" \| "onBlur" \| "onChange"`                            | `"onSubmit"` | When the fields show their errors, unless a field sets its own.                                                                            |
+| `values`         | `FormData`, `URLSearchParams` or `{ [name]: string \| string[] }` |              | The values to fill the controls with after a failed submission, by name, such as the record of fields an action passes back with `fail()`. |
+
+Every other `<form>` prop passes through: `method`, `action`, `onSubmit` (Lumiose's `submit`),
+`novalidate`, `class`.
+
+**`values`** replace the controls' defaults, by `name` (the control's, or its Field's): the text of
+an Input (Field.Control), an Autocomplete, a Select, a Number Field or a Slider, the checked state of
+a Checkbox or Switch (a name the submission left out means unchecked), and a Checkbox Group's,
+Radio Group's or Combobox's selection. Controls with a `value` (or `bind:`) keep theirs, and
+passwords, files, hidden inputs (whatever the case of their `type`), OTP Fields and disabled
+controls (also in a disabled `Fieldset.Root`) are never filled. So after a failed action the page
+renders the form as the user left it, with JavaScript or without (WCAG 3.3.7, redundant entry).
+Values match by name only: give a password and a text field different names, or the text field gets
+the password. A native `<fieldset disabled>` is not seen while rendering, so its controls are
+filled; use `Fieldset.Root disabled` instead.
+
+**Differences from Base UI's Form.** No `onFormSubmit` or `actionsRef`: the form is native and
+Lumiose's form actions post it (`action="?/name"`, `onSubmit={submit}`). Base UI sets
+`noValidate`; here the browser's validation stays on, so it still works without JavaScript, and
+Field's script shows the problems in the fields instead of the browser's bubble.
+
+## Example
+
+A sign-up page whose action checks the username on the server:
+
+```tsx check
+import { Field, Form } from "@lumiose/ui";
+import { actionData, fail, type ActionContext } from "lumiose";
+
+export const actions = {
+  async signup(ctx: ActionContext) {
+    const form = await ctx.formData();
+    const username = String(form.get("username") ?? "");
+    if (username === "admin") {
+      // The errors, and the fields to fill in again (never a password): the form renders back
+      // filled in.
+      return fail(400, { errors: { username: "That username is taken." }, values: { username } });
+    }
+    return { welcome: username };
+  },
+};
+
+export function SignupForm() {
+  const result = actionData<typeof actions>();
+  const failed = result && "errors" in result ? result : undefined;
+  return (
+    <Form method="post" action="?/signup" errors={failed?.errors} values={failed?.values}>
+      <Field.Root name="username" class="lu-field">
+        <Field.Label>Username</Field.Label>
+        <Field.Control required minlength={3} autocomplete="username" class="lu-input" />
+        <Field.Error />
+      </Field.Root>
+      <button class="lu-button" data-variant="primary">
+        Sign up
+      </button>
+    </Form>
+  );
+}
+```
+
+Only the keys of `errors` that name a field and hold a string or an array of strings become
+errors, so `errors={result}` also works for an action that fails with the errors alone. The
+`values` reach the browser with the page, so send back the fields to fill in by name, as above. The
+submitted `FormData` works too (its text entries; files are left out), but it carries every field,
+a password included: Form never fills a password field, yet the password would sit in the page's
+HTML. In development, Lumiose warns when a `FormData` it serializes carries a name that looks
+secret. In an island, add `onSubmit={submit}` and the errors arrive without a page load; the
+controls keep what the user typed anyway.
+
+## Styling
+
+Form adds nothing to style: style the `form` and its state, `form:invalid` (a field is invalid)
+and `form:has(:user-invalid)` (one the user touched is), and its fields
+([Field](field.md#styling)). Form ships no stylesheet.
+
+**A form reset** (a `type="reset"` button, `form.reset()`) puts every control back to its default
+and reports it: `onValueChange` / `onCheckedChange` get the reset value a moment later, when it
+differs, so `bind:` signals in an island follow the form (the platform fires no `input` or
+`change` for a reset).
+
+## Keyboard and focus
+
+The platform's: Enter in a text field submits the form. On a submit attempt with invalid fields,
+nothing is sent, the fields show their errors, and the first invalid control takes focus (Field's
+script; without it, the browser focuses it and shows its bubble).
+
+## Without JavaScript
+
+A native form posts to its action and the page renders back with `actionData()`, so the server's
+errors show in their fields with no script, and with `values` the controls show what was
+submitted. The browser validates the fields before it posts.
+
+## Browser support
+
+Every browser. Field's script needs the `invalid` event and constraint validation, which every
+supported browser has.
+
+## Related
+
+- [Field](field.md): the fields and their errors.
+- [Fieldset](fieldset.md): groups of fields.
+- [Data and actions](https://itsjavi.com/lumiose/docs/concepts/data-and-actions/): form actions,
+  `fail()`, `actionData()` and `submit()`.

package/docs/input.md

@@ -0,0 +1,87 @@
+# Input
+
+> A native `<input>`, after Base UI's Input: every type, constraint and autofill the browser has, plus `onValueChange` and `bind:value`. Inside a [Field](field.md) (as `Field.Control`) it takes the field's id, name and ARIA references. No script, no CSS of its own.
+
+```ts
+import { Input } from "@lumiose/ui"; // or "@lumiose/ui/input"
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<Input />
+```
+
+| Part    | Renders                                |
+| ------- | -------------------------------------- |
+| `Input` | `<input>`, with the props it is given. |
+
+## API
+
+### Input
+
+| Prop            | Type                      | Default |                                                                             |
+| --------------- | ------------------------- | ------- | --------------------------------------------------------------------------- |
+| `value`         | `string`                  |         | Sets the value when it changes. Pair it with `onValueChange`.               |
+| `defaultValue`  | `string`                  |         | The value at first, when `value` is left out; a form reset goes back to it. |
+| `onValueChange` | `(value: string) => void` |         | Called with the new value on every edit.                                    |
+| `bind:value`    | `Signal<string>`          |         | Stands in for `value` and `onValueChange`.                                  |
+
+Every native `<input>` prop passes through: `type`, `name`, `required`, `pattern`, `minlength`,
+`placeholder`, `autocomplete`, `readonly`, `disabled`, `class`, `aria-*`, events. Inside a Field,
+its own `id`, `name`, `aria-describedby` and `aria-invalid` win over the field's.
+
+**Differences from Base UI's Input.** The same element and props; `bind:value` stands in for the
+pair.
+
+## Example
+
+A search box in an island, bound to a signal:
+
+```tsx check
+import { Input } from "@lumiose/ui";
+import { signal } from "lumiose";
+
+const BOOKS = ["Dune", "Emma", "Ulysses", "Middlemarch"];
+
+export function BookSearch() {
+  const query = signal("");
+  const found = () => BOOKS.filter((book) => book.toLowerCase().includes(query().toLowerCase()));
+  return (
+    <search>
+      <Input type="search" aria-label="Search books" bind:value={query} class="lu-input" />
+      <p>{found().join(", ") || "No books."}</p>
+    </search>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-input` on it: a bordered field, a muted placeholder, a focus
+ring, a red border with `aria-invalid="true"`.
+
+**With your own CSS**, style the `input` and its state: `:focus-visible`, `:disabled`,
+`:read-only`, `:placeholder-shown`, `:user-invalid`, `[aria-invalid="true"]`.
+
+Input ships no stylesheet: it needs none to work.
+
+## Keyboard and focus
+
+The browser's text-field keyboard. One tab stop.
+
+## Without JavaScript
+
+A native input: typing, autofill, validation and submission work with no script. `value`,
+`onValueChange` and `bind:value` need the component to run in an island.
+
+## Browser support
+
+Every browser; input types and constraints as the browser supports them.
+
+## Related
+
+- [Field](field.md): label, description and errors for an Input (`Field.Control`).
+- [Combobox](combobox.md): an input that filters options.
+- [JSX](https://itsjavi.com/lumiose/docs/concepts/jsx/): `bind:value`.

package/docs/installation.md

@@ -0,0 +1,65 @@
+# Installation
+
+> Add `@lumiose/ui` to a Lumiose app and import its stylesheets, and the default theme if you want its look. The components then render in server HTML, without an island, and a page loads only the small scripts of the components it renders.
+
+**Status:** `@lumiose/ui` is not on npm yet. In this repository's workspace, an app adds it as
+`"@lumiose/ui": "workspace:*"` in its `dependencies`.
+
+## Add the package
+
+`@lumiose/ui` needs a Lumiose app: it ships its components as TSX, which the app's build compiles
+with the app's own code, and `lumiose` is its peer dependency. Once it is on npm:
+
+```sh
+pnpm add @lumiose/ui
+```
+
+A new app can start with it: `create-lumiose --ui` adds the dependency, imports the stylesheets in
+the root layout and adds the UI agent files (the `lumiose-ui` skill and a UI part in `AGENTS.md`).
+In an app that already depends on it, `lumiose agents init` adds those agent files.
+
+## Import the stylesheets
+
+Import them once, in the root layout (`src/routes/layout.stsx`), so every page has them:
+
+```ts
+import "@lumiose/ui/styles.css"; // what every component needs (or "@lumiose/ui/dialog.css", …)
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+They sit in cascade layers, so your own CSS overrides them without specificity games
+([Theming](theming.md#cascade-layers)).
+
+## Use a component
+
+Import a component from `@lumiose/ui` (or its own entry, `@lumiose/ui/popover`) and compose its
+parts. In a page or a server component it renders as server HTML that works before any script
+loads; with the default theme, the `lu-` classes give it its look:
+
+```tsx check
+import { Popover } from "@lumiose/ui";
+
+export function Help() {
+  return (
+    <Popover.Root>
+      <Popover.Trigger class="lu-button">Help</Popover.Trigger>
+      <Popover.Popup class="lu-popover">
+        <Popover.Title>Help</Popover.Title>
+        <Popover.Description>
+          Server HTML: this popover opens without JavaScript.
+        </Popover.Description>
+      </Popover.Popup>
+    </Popover.Root>
+  );
+}
+```
+
+To keep a component's state in a signal (`bind:open`, `bind:value`), render it inside an
+[island](https://itsjavi.com/lumiose/docs/concepts/islands/). Each component's page lists its parts,
+props, keyboard contract and what works without JavaScript.
+
+## Related
+
+- [UI components](README.md): the approach and the components.
+- [Theming](theming.md): the default theme's classes and `--lu-` properties, and your own CSS.
+- [Getting started](https://itsjavi.com/lumiose/docs/getting-started/): a new Lumiose app.