# ark-plastic A headless, accessible UI component library for the [Plastic](https://github.com/plastic-js/plastic) JSX runtime. Built on [Zag.js](https://zagjs.com/) — state-machine-driven, framework-agnostic UI primitives. ## Philosophy - **Headless** — zero styles, full control over markup and design - **Accessible** — WAI-ARIA compliant by default via Zag.js machines - **Reactive** — state lives in Zag machines, exposed as Plastic signals and computed values that update the DOM automatically - **Framework-native** — built for Plastic, not adapted or wrapped from another framework - **API-compatible** — component props, part names, and callback signatures mirror the official [Ark UI](https://ark-ui.com/) API so knowledge transfers directly - **Browser-only** — no SSR support; all rendering targets a live `document` ## How it works Each component is backed by a Zag.js finite-state machine that manages all interactive state: open/closed, selected values, focus, keyboard navigation, and ARIA attributes. `@plastic-js/ark` connects those machines to the Plastic reactive runtime through two thin layers: 1. **`useMachine`** — creates a Plastic-managed service instance and starts the machine lifecycle. 2. **`createComputed`** — wraps `connect(service, normalizeProps)` so that any JSX expression reading machine state is tracked as a reactive dependency and re-renders automatically. The result is that `api().open`, `api().getTriggerProps()`, etc. behave like ordinary Plastic signals — no manual subscriptions, no reconciliation, no imperative DOM updates. ## Install ```bash npm install @plastic-js/ark ``` ## Requirements - **Plastic JSX runtime** — the peer runtime that `@plastic-js/ark` targets. In your JSX transform configuration, point the runtime at `@plastic-js/plastic/jsx-runtime`. - Node 22+ / a modern bundler that supports ES modules (`"type": "module"`). ## Usage ### Compound components Every component exposes its parts as nested sub-components under a shared namespace: ```jsx import { Dialog } from "@plastic-js/ark" function MyDialog() { return ( Open Hello World Close ) } ``` You can also import parts by their full flat name: ```jsx import { DialogRoot, DialogTrigger, DialogContent } from "@plastic-js/ark" ``` Or use the deep-import path for more precise tree-shaking: ```jsx import { Root, Trigger, Content } from "@plastic-js/ark/dialog" ``` ### Controlled usage Pass a signal-based value to keep state under your control. The component's internal machine only fires the `onXxx` callback — it does not update its own state unless you push a new value back in: ```jsx import { createSignal } from "@plastic-js/plastic" import { Dialog } from "@plastic-js/ark" function App() { const [open, setOpen] = createSignal(false) return ( setOpen(next)}> Open Close ) } ``` ### Uncontrolled usage with a default value Use `defaultValue` / `defaultOpen` / `defaultChecked` to set an initial state while letting the machine own all subsequent transitions: ```jsx … ``` ### Headless hook usage For full control, call the `useXxx` hook directly and wire machine props onto your own markup: ```jsx import { useDialog } from "@plastic-js/ark/dialog" import { ark } from "@plastic-js/ark/factory" function CustomDialog(props) { const api = useDialog(props) return ( Open {props.children} ) } ``` Each `useXxx` hook accepts the same props as the corresponding `Root` component and returns a reactive accessor (`api`) whose value is the full Zag `connect(...)` API. ## The `asChild` pattern Every part component accepts an `asChild` render prop. Pass it a function that receives a props accessor and returns a single custom element. The machine-provided ARIA attributes, event handlers, and `data-*` attributes are merged onto your element — no extra wrappers: ```jsx import { Dialog } from "@plastic-js/ark" function MyButton(props) { return {(toast) => ( {toast.title} {toast.description} ✕ )} ) } ``` `createToaster` accepts the same options as the Zag toast machine context. The `toaster` object is plain — no Plastic reactivity required to hold a reference to it. ## Providers Wrap your app (or a subtree) with these providers to configure library-wide behaviour. ### EnvironmentProvider Controls which `document` and `window` the components read from. Required for Shadow DOM, iframes, and multi-document setups. Providers can be nested — each level inherits any getter the inner provider does not override: ```jsx import { EnvironmentProvider } from "@plastic-js/ark/environment" // Pass a custom document directly // Or provide a getter function shadowRoot.ownerDocument }}> ``` When mounted without an explicit `value`, `EnvironmentProvider` still renders a hidden `` sentinel so `getRootNode()` reflects the actual DOM root of the subtree — critical for Shadow DOM usage. ### LocaleProvider Sets the locale (`BCP 47` language tag) and text direction (`ltr` / `rtl`) for all components in the subtree. When no locale is provided, the library tracks the browser's locale reactively — no re-mount required when the user changes the OS language: ```jsx import { LocaleProvider } from "@plastic-js/ark/locale" {/* components render RTL automatically */} ``` The `useLocaleContext` hook, plus three utility hooks, are also available for component authors: ```js import { useCollator, useFilter, useDateFormatter } from "@plastic-js/ark/locale" // Returns a reactive Intl.Collator for the active locale const collator = useCollator() // Returns a reactive locale-aware string filter (startsWith / contains / endsWith) const filter = useFilter({ sensitivity: "base" }) // Returns a reactive Intl.DateTimeFormat const fmt = useDateFormatter({ dateStyle: "medium" }) ``` ### InteractionProvider Configures pointer interaction behaviour (touch vs. mouse heuristics) for the component tree. Wrap the root of your app once; components beneath it adapt accordingly: ```jsx import { InteractionProvider } from "@plastic-js/ark/interaction" ``` ## Components | Category | Components | |---|---| | **Navigation** | Accordion, Tabs, Pagination, Tree View, Tour, Steps | | **Overlays** | Dialog, Drawer, Popover, Hover Card, Tooltip, Menu, Toast | | **Forms** | Checkbox, Radio Group, Switch, Select, Combobox, Listbox, Tags Input, Number Input, Slider, Rating Group, Date Input, Date Picker, Color Picker, Signature Pad, File Upload, Field, Fieldset, Toggle, Toggle Group | | **Layout** | Splitter, Collapsible, Carousel | | **Utilities** | Portal, Presence, Focus Trap, Progress, Avatar, Clipboard | | **Providers** | Environment, Locale, Interaction | ## Stale event handler pitfall Machine `connect(...)` calls return a **snapshot** object. If you destructure an event handler once and bind it to a long-lived DOM node, it can go stale after the machine transitions to a new state. ```js // ✗ stale — onClick captured from a single snapshot const { onClick } = api().getTriggerProps()