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

package/docs/custom-parts.md

@@ -0,0 +1,120 @@
+# Custom Parts
+
+Write a part with its own React logic and connect it to a primitive.
+
+The parts from [Rendering Primitives](./rendering.md) are enough until one needs its own logic. You can replace just that part and keep the same `rating.ts` definition from [Compose Behaviors](./core.md#complete-primitive).
+
+## Write a Root Part
+
+Here's a replacement for the generated `RatingRoot`. `usePrimitive` creates its instance, and `usePart` connects the `root` slot:
+
+```tsx title="rating-root.tsx"
+"use client"
+
+import type { StateOf } from "@ui-sdk/core"
+import { usePart, usePrimitive, type PartProps } from "@ui-sdk/react/primitive"
+import { rating, type RatingOptions } from "./rating"
+
+function RatingRoot({
+  value,
+  defaultValue,
+  onValueChange,
+  ...props
+}: RatingOptions &
+  Omit<PartProps<"div", StateOf<typeof rating, "root">>, "defaultValue">) {
+  const handle = usePrimitive(rating, { value, defaultValue, onValueChange })
+  return usePart(handle, "root", {}, props, "div")
+}
+
+export { RatingRoot }
+```
+
+Pass primitive options to `usePrimitive` and element props to `usePart`. The empty `{}` is for slot props; this root doesn't need any. `usePart` shares the instance with child parts and renders nothing when the slot isn't present.
+
+The adapter keeps options current and manages the instance's lifetime. Call `handle.api` from event handlers or effects. To render changing state, use a part's `children` or `render` function; reading `handle.state` alone doesn't subscribe to changes.
+
+## Connect a Child Part
+
+A child can pass the primitive itself to `usePart`. It finds the instance shared by the root above it.
+
+This `RatingStar` works inside the manual root above or the generated `RatingRoot`. It adds a default accessible label:
+
+```tsx
+"use client"
+
+import { usePart, type PartProps } from "@ui-sdk/react/primitive"
+import { rating } from "./rating"
+
+function RatingStar({
+  value,
+  ...props
+}: { value: string } & Omit<PartProps<"button">, "value">) {
+  const label = `${value} ${value === "1" ? "star" : "stars"}`
+  return usePart(
+    rating,
+    "star",
+    { value },
+    { "aria-label": label, ...props },
+    "button"
+  )
+}
+
+export { RatingStar }
+```
+
+`{ value }` identifies the star. The remaining props go to its button. A caller can override the label with `aria-label`.
+
+Use it in place of the generated star in [Render the Rating](./rendering.md#render-the-rating). Keep it inside `RatingRoot` so it can find the instance.
+
+## Merge Props
+
+Use `mergeProps` when your part adds props that need to combine with the caller's. For example, an input can select its text on focus while still accepting an `onFocus` handler:
+
+```tsx
+"use client"
+
+import {
+  mergeProps,
+  renderElement,
+  type PartProps,
+} from "@ui-sdk/react/primitive"
+import type { FocusEvent } from "react"
+
+function SelectOnFocusInput({ render, ...props }: PartProps<"input">) {
+  const own = {
+    onFocus: (event: FocusEvent<HTMLInputElement>) =>
+      event.currentTarget.select(),
+  }
+  return renderElement("input", mergeProps(own, props), render)
+}
+
+export { SelectOnFocusInput }
+```
+
+The caller's handler runs first and can call `preventDefault()` to skip yours. Class names join, styles merge, and refs combine. Other values from later arguments win; `undefined` doesn't replace an existing value.
+
+For native `pointerenter` and `pointerleave` slot listeners, canceling React's handler doesn't cancel the slot's listener.
+
+## An Element Without a Primitive
+
+`renderElement` also works for a plain wrapper. It gives the wrapper the same `render` prop as the other parts:
+
+```tsx
+"use client"
+
+import { renderElement, type PartProps } from "@ui-sdk/react/primitive"
+
+function Card({ render, ...props }: PartProps<"div">) {
+  return renderElement("div", props, render)
+}
+
+export { Card }
+```
+
+`PartProps` supplies the element props and `render`. Add its second type argument when `className`, `style`, or `children` should receive your part's state.
+
+`renderElement` uses no hooks, so a wrapper like `Card` also works in a Server Component. Anything built on `usePrimitive`, `usePart` or `createParts` still needs a client component, since those use hooks. [Server Rendering](./server-rendering.md#wrappers-in-a-server-component) shows one.
+
+## Compose a Popup
+
+A custom part can render an existing Popover or Dialog and connect its open state. [Compose Ours](./core.md#compose-ours) shows that connection with an emoji picker.

package/docs/first-component.md

@@ -0,0 +1,83 @@
+# First Component
+
+Add a component to your app and style its state.
+
+Let's add a Bookmark toggle. Press it once to turn it on, then again to turn it off.
+
+If you haven't installed the packages yet, start with [Installation](./installation.md).
+
+## Create the Component
+
+Create `bookmark-button.tsx` next to your app component and render a `Toggle`:
+
+```tsx title="bookmark-button.tsx"
+import { Toggle } from "@ui-sdk/react/toggle"
+
+function BookmarkButton() {
+  return <Toggle>Bookmark</Toggle>
+}
+
+export { BookmarkButton }
+```
+
+`Toggle` renders a button. It keeps track of its pressed state, handles Enter and Space, and sets `aria-pressed` for screen readers.
+
+## Use It in Your App
+
+In your app component (`app.tsx` here), import and render `BookmarkButton`:
+
+```tsx title="app.tsx"
+import { BookmarkButton } from "./bookmark-button"
+
+function App() {
+  return <BookmarkButton />
+}
+
+export { App }
+```
+
+Open your app. You should see a button labeled Bookmark. Next, add styles so you can tell when it is pressed.
+
+## Add Styles
+
+When the toggle is pressed, it has a `data-pressed` attribute. Use that attribute to change its appearance.
+
+With Tailwind CSS configured in your app, add utility classes to `className`. The `data-pressed:` variant applies while the toggle is pressed:
+
+```tsx title="bookmark-button.tsx"
+import { Toggle } from "@ui-sdk/react/toggle"
+
+function BookmarkButton() {
+  return (
+    <Toggle className="inline-flex h-8 items-center rounded-md border border-neutral-300 px-3 text-sm font-medium hover:bg-neutral-100 focus-visible:outline-2 focus-visible:outline-offset-2 data-pressed:bg-neutral-900 data-pressed:text-white">
+      Bookmark
+    </Toggle>
+  )
+}
+
+export { BookmarkButton }
+```
+
+Try the styled toggle:
+
+```tsx title="first-component.tsx"
+import { Toggle } from "@ui-sdk/react/toggle"
+
+function Example() {
+  return <Toggle data-variant="outline">Bookmark</Toggle>
+}
+
+export { Example }
+```
+
+Click Bookmark to turn it on or off. A filled background means it is on. You can also focus the button with Tab and press Enter or Space.
+
+Keep the label the same in both states. `aria-pressed` tells a screen reader whether the toggle is on.
+
+## Keep Going
+
+- [Toggle](./components/toggle.md) covers disabled states, controlled state, and groups of toggles.
+- [Components](./README.md) lists the other components you can add with the same install.
+- [Parts and Composition](./parts-and-composition.md) shows how to put a component with several parts together.
+- [State and Events](./state-and-events.md) shows how to read changes and control state from your app.
+- [Styling and Animation](./styling-and-animation.md) covers state attributes, CSS variables, and transitions.

package/docs/forms.md

@@ -0,0 +1,148 @@
+# Forms
+
+Submit component values, label controls, and show validation errors.
+
+Give a control a `name` to include its value in a form. This works for Select and Combobox as well as inputs and checkboxes.
+
+## Submit a Value
+
+```tsx
+import { Checkbox } from "@ui-sdk/react/checkbox"
+
+function Example() {
+  return (
+    <form action="/preferences" method="post">
+      <label>
+        <Checkbox name="updates" value="yes" defaultChecked />
+        Email me updates
+      </label>
+      <button type="submit">Save</button>
+      <button type="reset">Reset</button>
+    </form>
+  )
+}
+
+export { Example }
+```
+
+The checkbox submits `updates=yes` when checked. Reset restores its default value.
+
+## Reset a Controlled Value
+
+A reset also goes through `onCheckedChange`. Update your React state there, just as you would after a click:
+
+```tsx
+"use client"
+
+import { Checkbox, type CheckedState } from "@ui-sdk/react/checkbox"
+import { useState } from "react"
+
+function Example() {
+  const [checked, setChecked] = useState<CheckedState>(true)
+  const [reason, setReason] = useState("No change yet")
+
+  return (
+    <form>
+      <label>
+        <Checkbox
+          name="updates"
+          defaultChecked
+          checked={checked}
+          onCheckedChange={(next, details) => {
+            setChecked(next)
+            setReason(details.reason)
+          }}
+        />
+        Email me updates
+      </label>
+      <button type="reset">Reset</button>
+      <output>{reason}</output>
+    </form>
+  )
+}
+
+export { Example }
+```
+
+Uncheck the box, then press Reset. `defaultChecked` supplies the reset value, and the callback receives `true` with reason `"reset"`. The callback runs when reset requests a different value; it does not run if the checkbox is already at its default.
+
+## Label and Validate a Field
+
+`Field` connects a control to its label, description, and error message:
+
+```tsx
+import {
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldLabel,
+} from "@ui-sdk/react/field"
+import { Input } from "@ui-sdk/react/input"
+
+function Example() {
+  return (
+    <Field name="email">
+      <FieldLabel>Email</FieldLabel>
+      <Input type="email" required />
+      <FieldDescription>We'll only use it for receipts.</FieldDescription>
+      <FieldError />
+    </Field>
+  )
+}
+
+export { Example }
+```
+
+You can use a Textarea, Checkbox, Switch, Radio Group, or Select in place of the Input. [Field](./components/field.md) shows how they connect.
+
+These props follow native form conventions on controls that support them:
+
+| Prop       | What It Does                                                                |
+| ---------- | --------------------------------------------------------------------------- |
+| `name`     | Sets the submitted field name. Without one, no value is submitted.          |
+| `required` | Requires a value before the form can submit.                                |
+| `disabled` | Prevents interaction and leaves the control out of the submission.          |
+| `readOnly` | Prevents edits while keeping the control focusable and its value submitted. |
+| `form`     | Connects a control to a form by ID when it's outside that form.             |
+
+## Handle a Submission
+
+On a normal submit, the browser checks constraints such as `required` and `type="email"` before running your handler.
+
+Your server may still reject a valid-looking value. Pass `invalid` to the field and show the server’s message. When the user edits the field, clear the message and return `invalid` to `undefined` so the field uses native validation again. This example expects a `/api/preferences` endpoint:
+
+```tsx
+"use client"
+
+import { Field, FieldError, FieldLabel } from "@ui-sdk/react/field"
+import { Input } from "@ui-sdk/react/input"
+import * as React from "react"
+
+function Example() {
+  const [error, setError] = React.useState("")
+
+  async function save(event: React.FormEvent<HTMLFormElement>) {
+    event.preventDefault()
+    const response = await fetch("/api/preferences", {
+      method: "POST",
+      body: new FormData(event.currentTarget),
+    })
+    setError(response.ok ? "" : "That email is already taken.")
+  }
+
+  return (
+    <form onSubmit={save}>
+      <Field name="email" invalid={error ? true : undefined}>
+        <FieldLabel>Email</FieldLabel>
+        <Input type="email" required onValueChange={() => setError("")} />
+        <FieldError>{(state) => error || state.message}</FieldError>
+      </Field>
+      <button type="submit">Save</button>
+    </form>
+  )
+}
+
+export { Example }
+```
+
+Without a handler, the form submits through its `action`, including a React server action.