# README.md · versecafe/quoin

[View on GitCafe](https://git.cafe/versecafe/quoin/blob/7b37bf7a5dd8b90ae1238b85abf170ead38cb0e9/README.md)

Repository: [versecafe/quoin](https://git.cafe/versecafe/quoin)

Visibility: public

Requested revision: 7b37bf7a5dd8b90ae1238b85abf170ead38cb0e9

Requested commit: 7b37bf7a5dd8b90ae1238b85abf170ead38cb0e9

Commit: 7b37bf7a5dd8b90ae1238b85abf170ead38cb0e9

Blob: 4cb03def206fd5fe16b2e5ea870466bcaed4739f

Size: 10125 bytes

[Immutable source](https://git.cafe/versecafe/quoin/blob/7b37bf7a5dd8b90ae1238b85abf170ead38cb0e9/README.md?format=markdown)

````
# quoin

An unstyled, accessible UI component library for [SolidJS](https://www.solidjs.com) — a faithful port of [Base UI](https://base-ui.com), built on Solid 2.0's fine-grained reactivity.

You bring the styles and the markup; quoin brings the behavior, accessibility, and positioning. Every component is a set of composable parts you assemble yourself, so you keep full control over the DOM.

> [!WARNING]
> quoin is pre-release software (`0.1.x`). The API is still settling and breaking changes should be expected. It targets the `solid-js@2.0.0-beta` line and currently relies on a few patches to that beta (see `patches/`); until those fixes land upstream, consuming apps may need to apply the same patches.

## Installation

```bash
pnpm install quoin-ui
# or
bun add quoin-ui
```

quoin targets **Solid 2.0** and expects the following peers:

```bash
bun install solid-js@2.0.0-beta.14 @solidjs/web@2.0.0-beta.14 @solidjs/signals@2.0.0-beta.14
```

### Required patches (Solid beta)

quoin relies on three small fixes to the Solid 2.0 beta — Portal `mount`
defaulting to `document.body`, suspense/error flushing in `@solidjs/signals`,
and a context `untrack` fix. These land upstream in a later beta; until then,
**bun** consumers must apply them to their own install (npm/pnpm/yarn users
need an equivalent such as `patch-package`).

The patch files ship inside the package. Copy them into your project and
register them in your `package.json`:

```bash
mkdir -p patches
cp node_modules/quoin/patches/* patches/
```

```jsonc
// package.json
{
  "patchedDependencies": {
    "solid-js@2.0.0-beta.14": "patches/solid-js@2.0.0-beta.14.patch",
    "@solidjs/web@2.0.0-beta.14": "patches/@solidjs%2Fweb@2.0.0-beta.14.patch",
    "@solidjs/signals@2.0.0-beta.14": "patches/@solidjs%2Fsignals@2.0.0-beta.14.patch"
  }
}
```

```bash
bun install   # applies the patches
```

Without the patches quoin still installs and imports cleanly, but a few
components (portals, suspense-driven state) won't behave correctly.

## Two ways to build

quoin exposes every component at two layers. Reach for whichever fits the job — they share the same underlying state machine, so you can mix them.

### Compound components

The **Base UI / React-style** API: a namespace of composable parts you nest to build the markup. Batteries included — portal, focus trap, scroll lock, positioning, and transitions are wired up for you. This is what you want most of the time.

```tsx
import { createSignal } from "solid-js";
import { Dialog } from "quoin-ui/dialog";

function Example() {
  const [open, setOpen] = createSignal(false);

  return (
    <Dialog.Root open={open()} onOpenChange={setOpen}>
      <Dialog.Trigger>View notifications</Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Backdrop />
        <Dialog.Popup>
          <Dialog.Title>Notifications</Dialog.Title>
          <Dialog.Description>
            You are all caught up. Good job!
          </Dialog.Description>
          <Dialog.Close>Close</Dialog.Close>
        </Dialog.Popup>
      </Dialog.Portal>
    </Dialog.Root>
  );
}
```

Every component family is also a subpath export (`quoin/dialog`, `quoin/select`, …) so you only ship what you import. Components are unstyled — bring your own CSS, CSS modules, or Tailwind. Every part forwards `class`, `style`, and the standard data attributes (`data-open`, `data-disabled`, …) for styling state.

### Headless primitives

The **`createX` API**: a Solid-idiomatic primitive that owns the state, modality, and dismissal logic but renders nothing. You provide the markup and read the state from any descendant with `useX()`. The compound `<Dialog.Root>` is itself a thin wrapper over `createDialog` — drop to this layer when you need full control of the rendered tree.

```tsx
import { createSignal, Show } from "solid-js";
import { createDialog, useDialog } from "quoin-ui/dialog";

function Example() {
  const [open, setOpen] = createSignal(false);
  // Controlled — `setOpen`/`toggle` emit through `onOpenChange`; you own the signal.
  const dialog = createDialog({ open, onOpenChange: setOpen });

  return (
    <dialog.Provider>
      <button onClick={() => dialog.toggle()}>View notifications</button>
      <Show when={dialog.open()}>
        <div role="dialog" aria-modal={dialog.modal() === true}>
          <h2>Notifications</h2>
          <p>You are all caught up. Good job!</p>
          <CloseButton />
        </div>
      </Show>
    </dialog.Provider>
  );
}

function CloseButton() {
  const dialog = useDialog(); // reads the nearest <dialog.Provider>
  return <button onClick={() => dialog.setOpen(false)}>Close</button>;
}
```

> Note: the primitive manages state and behavior only — DOM machinery like the portal, focus trap, and scroll lock lives in the compound parts. With `createDialog` alone you render (and wire up) the surface yourself.

For state that lives outside your JSX — opened from an event handler or another component — the `Dialog` namespace also exposes an imperative `Dialog.createHandle()` you connect via `<Dialog.Root handle={…}>` and drive with `handle.open(triggerId)` / `handle.close()` / `handle.openWithPayload({ … })`.

## Components

|                |                    |                 |                |
| -------------- | ------------------ | --------------- | -------------- |
| **Overlays**   | Dialog             | Alert Dialog    | Popover        |
|                | Tooltip            | Preview Card    | Drawer         |
| **Menus**      | Menu               | Submenu         | Context Menu   |
|                | Menubar            | Navigation Menu | Toolbar        |
| **Selection**  | Select             | Combobox        | Autocomplete   |
| **Form**       | Field              | Fieldset        | Form           |
|                | Input              | Number Field    | OTP Field      |
| **Controls**   | Button             | Checkbox        | Checkbox Group |
|                | Radio              | Radio Group     | Switch         |
|                | Toggle             | Toggle Group    | Slider         |
| **Disclosure** | Accordion          | Collapsible     | Tabs           |
| **Display**    | Avatar             | Progress        | Meter          |
|                | Scroll Area        | Separator       |                |
| **Providers**  | Direction Provider | CSP Provider    |                |

## How it works

Quoin heavily references Base UI's component model in idiomatic Solid:

- **Composable parts.** Each component is a namespace of parts (`Dialog.Root`, `Dialog.Trigger`, `Dialog.Popup`, …) that you nest to build the markup you want.
- **Controlled by default.** Root components take controlled props (`open`/`onOpenChange`, `value`/`onValueChange`) — pass a signal and wire the callback.
- **Floating UI positioning.** Popovers, menus, selects, and tooltips position with [`@floating-ui/dom`](https://floating-ui.com).
- **SSR & hydration ready.** Ships a dual build — a DOM-compiled bundle (`import`/`default`) plus a JSX-preserved bundle (the `solid` condition) so Solid-aware bundlers can recompile for your target.

## Project status

This is an experimental Solid 2.0 port and is not affiliated with the Base UI team. It tracks Base UI's behavior and test suite where practical, with adjustments for Solid's reactivity model.

## Acknowledgements

Built on the work of the [Base UI](https://base-ui.com) team (from the creators of Radix, Floating UI, and Material UI) and the [SolidJS](https://www.solidjs.com) project.

## Required Solid patches

> [!IMPORTANT]
> quoin depends on three small fixes to Solid 2.0 beta.14 that have not yet landed upstream. **You must apply them in your own project** — package-manager patch settings are an install-time mechanism that does *not* transfer from a published dependency to its consumers. Without them, parts of quoin will not work; most severely, **every portalled component (dialog, popover, tooltip, menu, select, drawer, …) crashes in Chromium** with `TypeError: parameter 1 is not of type 'Node'`.

The three patches (against `solid-js`, `@solidjs/web`, and `@solidjs/signals` at `2.0.0-beta.14`) fix:

- **`@solidjs/web` — `Portal` passes a `Proxy` to `Node.contains`.** Chromium throws on every portalled surface; happy-dom/WebKit mask it, so it only shows in a real Chromium browser. *(The critical one.)*
- **`@solidjs/signals` — `action()` rejection routing.** A rejected `action()` recurses forever instead of settling; `await action(...)()` hangs.
- **`@solidjs/signals` — async-memo rejection wake-up.** A rejecting async memo never wakes its dependents; `await resolve(...)` hangs.
- **`solid-js` — `createContext` provider tracks its value.** The provider re-runs its whole subtree on unrelated upstream changes.

### Applying them

quoin ships the patch files in [`patches/`](./patches). Copy them into your project and register them with your package manager.

**bun** — copy `patches/` to your project root and add to `package.json`:

```jsonc
{
  "patchedDependencies": {
    "solid-js@2.0.0-beta.14": "patches/solid-js@2.0.0-beta.14.patch",
    "@solidjs/web@2.0.0-beta.14": "patches/@solidjs%2Fweb@2.0.0-beta.14.patch",
    "@solidjs/signals@2.0.0-beta.14": "patches/@solidjs%2Fsignals@2.0.0-beta.14.patch"
  }
}
```

**pnpm** — same, under the `pnpm.patchedDependencies` key. **npm / yarn** — these have no native equivalent; use [`patch-package`](https://www.npmjs.com/package/patch-package) with the same diffs.

After installing, verify the fix actually applied — patches can *silently mis-apply* on a version drift (see below). The quickest check is to open any dialog/popover in **Chromium**; if it renders instead of throwing, `@solidjs/web` is patched.

> [!NOTE]
> These patches are pinned to `2.0.0-beta.14`. If you bump Solid, the minified identifiers shift and the patches will not carry forward cleanly — re-derive (or drop any that upstream has since fixed). Full rationale, per-patch detail, and re-derivation steps live in [`solid/patches.md`](./solid/patches.md).

````