`. - **`press`** for roles that activate, like `button`, `option` or `tab`. - **`keys`** for roles whose pattern moves with keys, like `listbox`, `menu` or `slider`: the keys its `on.keydown` handles, or a function of state when they depend on it. ```ts list: slot({ role: "listbox", keys: (state) => [...(state.orientation === "horizontal" ? ["ArrowLeft", "ArrowRight"] : ["ArrowUp", "ArrowDown"]), "Home", "End", "typeahead"], on: { keydown: (event, { api }) => api.navigate(event) }, }), ``` Listing keys without an `on.keydown` to handle them fails to compile too, on any slot. When another element meets a need, say which with `{ none: "why" }`, like `keys: { none: "The combobox's input handles them." }`. A role that changes with state is a function, with every role it can pick in `roles`: ```ts root: slot({ role: (state) => (state.decorative ? "none" : "separator"), roles: ["none", "separator"], }), ``` The role decides the part's ARIA too. Its `attrs` returns the states the role can't work without, like `aria-checked` on a checkbox or `aria-selected` on an option, and nothing the role doesn't take: `aria-orientation` on a group fails with "aria-orientation isn't allowed on a group". ```ts box: slot({ role: "checkbox", focus: "native", press: ({ api }) => api.toggle(), attrs: (state) => ({ "aria-checked": String(state.checked) }), }), ``` A state that `live` keeps current is `undefined` in `attrs`, so `attrs` still names it. Development builds warn about anything the types can't see, like a spread slot or JavaScript, and about a required state that renders without a value. Set `globalThis.__UI_SDK_STRICT__ = true` in your test setup to turn every warning into an error. ## Working with the Element Use `bind` for work that needs an element, such as measuring it or attaching an observer. It runs in the browser once the part is bound. Return a cleanup function: ```ts root: slot({ attrs: () => ({ rows: "1" }), bind: (el) => { const fit = () => { el.style.height = "auto" el.style.height = `${el.scrollHeight}px` } fit() el.addEventListener("input", fit) return () => el.removeEventListener("input", fit) }, }), ``` This textarea measures its content after each input and adjusts its height. Keep `attrs` and slot `state` pure: they also run on the server. Read from state and the part's props; do DOM work in `bind`. Slot `state` can return new objects and arrays on every call, since parts compare them by value, but other values, like a `Date` or a `Map`, should stay the same object until they change. `bind` also receives the part as its second argument. Its `props` stay current, and `part.store.subscribe` lets you follow state changes. Use `connect` for work that must stay active while an element remains in the page, even when it isn't present, as with a hidden custom element. ### Cleaning up the Instance Work shared by all parts belongs in `api`. Use `context.onDestroy` to clean it up when the instance is destroyed. For example, the copy button clears its reset timer: ```ts let timer: ReturnType | undefined context.onDestroy(() => clearTimeout(timer)) ``` Clear the previous timer before starting another one, too. ## Reading Parts in the Api Sometimes a method needs to find a part. `elements(context, slot)` returns the bound parts in page order, with their elements, keys and props: ```ts import { elements } from "@ui-sdk/core" api: (context) => ({ next() { const fields = elements<{ value: string }>(context, "field") const empty = fields.find((field) => (field.el as HTMLInputElement).value === "") empty?.el.focus() }, }), ``` Try leaving a field empty. The button finds it from the current page order, so there's no separate index to keep up to date. For one part, use `context.element(slot, key)`. To read its latest props, use `context.props(slot, key)`, naming them the same way: `context.props<{ title: string }>("window", key)`. The `key` is the part's `id` prop, or its `value`, as with the stars in [Compose Behaviors](/docs/core/compose-behaviors#add-a-star). ## What Agents Can Do The `agent` key tells [the agent bridge](/docs/agents/connect-an-agent/reference#custom-primitives) which api methods an agent can call, and a little about the component, like whether its value must be one of its items: ```ts agent: { actions: ["setValue", "clear"], closed: true }, ``` Put it last, after `slots`, so TypeScript has read the api by then. Without it, the bridge picks methods named like changes, such as `setValue` or `toggle`. [Your Own Components](/docs/agents/connect-an-agent/your-components) shows a rating an agent can use, and every part of the key. ## Naming A primitive's `name` prefixes each part's `data-slot`, like `tabs-list` for the tabs' `list` slot. The `root` slot gets the name alone, so `name: "copy-button"` gives its root `data-slot="copy-button"`. Warnings and devtools use this name too. Set `label` when they should show a different name; it doesn't change `data-slot`. For state attributes, `openAttrs(open)` returns `data-open` or `data-closed`. `checkedAttrs(checked)` returns `data-checked`, `data-unchecked` or `data-indeterminate`. Both are helpers from `@ui-sdk/core`. ## API Reference ### definePrimitive - `name` (`string`): Prefixes `data-slot`, and names the component in warnings and the devtools. Kebab case. Example: [Naming](#naming). - `state` (`(options: Options) => State`): The starting state, from the first options. Read `default` here. Example: [Define a Primitive](/docs/core/build-a-component#define-a-primitive). - `live?` (`(keyof State)[]`): State keys that change often and never affect rendering, like a highlighted item. Example: [Live State](/docs/core/kernel/handle-changes#live-state). - `asleep?` (`((options: object) => boolean)`): Whether an instance with these options starts asleep: its parts render and run `asleep`, while its api and each part's `bind` wait for the first event a part handles or the first read of `instance.api`. Like a closed tooltip, which costs little until its trigger is hovered or focused. - `sync?` (`(options: Options) => Partial`): Maps controlled options onto state. Runs whenever options change. Example: [State a User Controls](/docs/core/kernel/handle-changes#state-a-user-controls). - `controlled?` (`(keyof State)[]`): State keys a user can control with ``, `default` and `onChange`. Development builds warn when one starts with both `` and `default`, or was controlled and becomes undefined. Defaults to whichever of `open`, `value` and `checked` the state has. Example: [State a User Controls](/docs/core/kernel/handle-changes#state-a-user-controls). - `commits?` (`(keyof State)[]`): State keys an interaction changes in steps and then commits, through `createCommit`, like a slider's `value` while it's dragged. `observe` reports each of them once per commit rather than per step. Example: [Commits](/docs/core/kernel/handle-changes#commits). - `api` (`(context: PrimitiveContext) => Api`): Runs once per instance and returns its api, which slots, adapters and a controller call. Example: [Define a Primitive](/docs/core/build-a-component#define-a-primitive). - `slots` (`(slot: SlotFactory) => Record`): The parts, built with `slot`. `slot({ ... })` types a slot's props and the state its render functions get. Example: [Define a Primitive](/docs/core/build-a-component#define-a-primitive). - `label?` (`string`): What warnings, `debug` and the devtools call it, when that isn't `name`, which prefixes `data-slot`. Like a checkbox group's parts in `checkbox`. Example: [Naming](#naming). - `agent?` (`object: actions, closed, items, reveals, shown, secret`): What `@ui-sdk/core/agent` offers an agent. Without it, the agent takes the api's methods that change something by their names, like `setValue`. Example: [What Agents Can Do](#what-agents-can-do). - `options?` (`PropSchema`): Each option, with its kind, for renderers to read. A primitive without options leaves it out. Example: [Options](#options). ### Slots - `present?` (`((state: State, context: { id: string; key: string; props: Props; api: Api; }) => boolean)`): Whether the slot's element should exist. Adapters that cannot unmount markup, like custom elements, bind and unbind on it. Defaults to always. Keyed parts, like one panel among many, decide from their own props. May read live state: adapters check presence on every change. Example: [Parts That Come and Go](#parts-that-come-and-go). - `attrs?` (`((state: State, context: { id: string; key: string; props: Props; api: Api; }) => Attrs)`): Pure. Runs on the server and on every render. Never reads live state. Example: [Define a Primitive](/docs/core/build-a-component#define-a-primitive). - `state?` (`((state: State, context: { id: string; key: string; props: Props; api: Api; }) => Public)`): What `render` functions and state-based class names see, like { highlighted, disabled }. May read live state: adapters only re-render a part for live changes when its render function actually read them. Example: [What a Part Shows](#what-a-part-shows). - `live?` (`Live`): Attributes written straight to the element on every change, built by `live()`. Example: [Live State](/docs/core/kernel/handle-changes#live-state). - `direct?` (`{ names: readonly string[]; attach: (part: Part, el: HTMLElement) => () => void; }`): Attributes of `attrs` core keeps current on a framework's element, built by `direct()`. Example: [Live State](/docs/core/kernel/handle-changes#live-state). - `selects?` (`Selects`): Narrows which changes reach the slot's parts, built by `selects()`. Example: [Live State](/docs/core/kernel/handle-changes#live-state). - `press?` (`(context: { el, id, key, props, store, api }, event?: Event) => void`): Activation: a click, which keys and screen readers send too. `{ none: "why" }` for a role that activates when another handler does it, like the author's own click. Example: [Define a Primitive](/docs/core/build-a-component#define-a-primitive). - `on?` (`Partial void>>`): DOM events. Adapters attach these so user handlers run first and can call preventDefault() to skip them. Example: [Events](#events). - `bind?` (`((el: HTMLElement, part: Part) => (() => void) | void)`): Client only, web only. Focus, positioning, observers. Gets the part, whose `props` are its newest render's. Return a cleanup. Follow state with `part.store.subscribe`, or write attributes that change often with `direct`. Example: [Working with the Element](#working-with-the-element). - `asleep?` (`((el: HTMLElement, part: Part) => (() => void) | void)`): Client only, web only. Like `bind`, but runs at once while the instance is asleep, for what a part can't wait for, like naming its trigger. Its `part.api` is undefined until the instance wakes. - `connect?` (`((el: HTMLElement) => () => void)`): Client only. Runs while the element is in the page, present or not, for adapters that keep parts that aren't present, like custom elements. A popup's content registers here, so shortcuts inside a closed one don't run. Example: [Working with the Element](#working-with-the-element). - `props?` (`PropSchema`): Each prop the slot's parts take, with its kind, like `{ value: "string" }`. Example: [Add a Star](/docs/core/compose-behaviors#add-a-star). ### Roles - `role?` (`Role | ((state, context) => Role | undefined)`): The part's WAI-ARIA role, which core writes. A role that takes focus, activates or moves with keys makes the slot say how, with `focus`, `press` and `keys`. A function picks the role from state, with every role it can pick in `roles`. Never put `role` in `attrs`. Example: [Roles, Focus and Keys](#roles-focus-and-keys). - `roles?` (`array`): Every role a `role` function can pick. Development builds check what each one needs. Example: [Roles, Focus and Keys](#roles-focus-and-keys). - `focus?` (`Unneeded | ((state: State, context: { id: string; key: string; props: Props; api: Api; }) => Focus | Unneeded) | Focus`): How the part gets focus, for a role that takes it, like an option or a tab. `{ none: "why" }` when another element takes it instead. Example: [Roles, Focus and Keys](#roles-focus-and-keys). - `keys?` (`HandledKey[] | ((state) => HandledKey[]) | { none: string }`): The keys the part's `on.keydown` handles, for a role whose pattern moves with keys, or a function of state when they depend on it, like the arrows of an orientation. `{ none: "why" }` when another element handles them, like a combobox's input for its listbox. Example: [Roles, Focus and Keys](#roles-focus-and-keys). ## Next The copy button has everything it needs. Next, [Render a Primitive](/docs/core/kernel/render-a-primitive) puts it on the page in your framework. # Render a Primitive Turn a primitive's slots into parts in your framework, pass options, and read state. [Define a Primitive](/docs/core/kernel/define-a-primitive) gave the copy button its options, state and slots. Now let's put it on the page. Choose your framework in the page header, and the code below follows it. ## Install the Adapter An **adapter** connects a primitive to your framework. Install the one for yours: **React** ```bash npm add @ui-sdk/react ``` **Vue** ```bash npm add @ui-sdk/vue ``` **Svelte** ```bash npm add @ui-sdk/svelte ``` **Solid** ```bash npm add @ui-sdk/solid ``` **Web Components** ```bash npm add @ui-sdk/web ``` ## Create the Parts `createParts` turns each slot into a **part**. Pass it the primitive and the element each part renders: **React** ```ts title="copy-button-parts.ts" "use client" import { createParts } from "@ui-sdk/react/primitive" import { copyButton } from "./copy-button" const { Root: CopyButton } = createParts(copyButton, { root: "button" }) export { CopyButton } ``` **Vue** ```ts title="copy-button-parts.ts" import { createParts } from "@ui-sdk/vue/primitive" import { copyButton } from "./copy-button" const { Root: CopyButton } = createParts(copyButton, { root: "button" }) export { CopyButton } ``` **Svelte** ```ts title="copy-button-parts.ts" import { createParts } from "@ui-sdk/svelte/primitive" import { copyButton } from "./copy-button" const { Root: CopyButton } = createParts(copyButton, { root: "button" }) export { CopyButton } ``` **Solid** ```ts title="copy-button-parts.ts" import { createParts } from "@ui-sdk/solid/primitive" import { copyButton } from "./copy-button" const { Root: CopyButton } = createParts(copyButton, { root: "button" }) export { CopyButton } ``` **Web Components** ```ts title="copy-button-parts.ts" import { createParts, wrappedButton } from "@ui-sdk/web" import { copyButton } from "./copy-button" createParts(copyButton, { root: { tag: "copy-button", target: wrappedButton }, }) ``` `createParts` registers a custom element for each slot you map. `wrappedButton` puts the root's behavior and attributes on a native button inside the element. Import this file from your app's browser entry point. `Root` creates the primitive's instance and shares it with the parts inside. Every other slot becomes a part named in Pascal case, so a `star` slot becomes `Star`. ## Pass Options The primitive's options become the part's props, next to the element's own: **React** ```tsx console.log(text)}> Copy ``` **Vue** ```vue Copy ``` A callback option becomes an event, so `onCopy` is `@copy`. **Svelte** ```svelte console.log(text)} >Copy ``` **Solid** ```tsx console.log(text)}> Copy ``` **Web Components** ```html