Listbox and select: the markup is the collection, and the focus lands where the reader can see

@monowind/ui gains a listbox and a select, each a Zag.js machine wired
to the grid, with hooks in the React, Vue and Svelte packages. The
items a component needs are the ones the markup marks: their values,
their text and their disabled state make the collection where the
props name none, so a list of static items is markup alone. A select
is the anchored one — the same items and keyboard under a trigger, its
value on that trigger and in a hidden native control a form posts —
and both take one value or several.

A list's focus is its highlight, since a composite's own cells stay
plain and the grid draws no focus ring to fall back on: taking focus
highlights the selection, or the first item where nothing is selected,
and brings that row into view. The scroll targets the content box
rather than the scrollport, the engine reserving a box's border cells
as padding, and skips a focus the pointer caused.

Three engine fixes came out of building them. A sized box inside a
line of text now counts its own width toward a container sized to its
content, where it counted the text inside it. A scroller inside an
out-of-flow box is collected after the positioning pass that sizes it,
so a menu's, a dialog's or a select's content mirrors its scroll to
the grid at last. And a container new to a pass keeps its last offset
rather than reading a position the measuring mask makes unreliable.

pnpm check now refuses a package whose publishConfig exports point
outside its files, which would publish an entry the tarball does not
carry.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: benface

.agents/architecture/core-architecture.md

@@ -196,9 +196,9 @@ All three share one core. Concretely, the planned packages:
   Tailwind palettes, period fonts (int10h pack, CC BY-SA), ANSI tokens,
   and border glyph sets via the core theming contract (specs/theming.md).
 - **`@monowind/ui`** (`packages/ui`) — accessible components (menu,
-  dialog, popover, tooltip) as Zag.js machines placed and layered by the
-  engine (specs/ui.md), one entry per component, a vanilla mount, and a
-  CDN bundle; **`@monowind/ui-react`**, **`@monowind/ui-vue`**,
+  listbox, select, dialog, popover, tooltip) as Zag.js machines placed
+  and layered by the engine (specs/ui.md), one entry per component, a
+  vanilla mount, and a CDN bundle; **`@monowind/ui-react`**, **`@monowind/ui-vue`**,
   **`@monowind/ui-svelte`** fold each framework's Zag adapter in, one
   function per component.
 - **CDN mode is a build output of core, not a package** — an extra IIFE bundle

.agents/plans/2026-09-19-ui-components.md

@@ -64,8 +64,9 @@ The elements also serve any framework as plain markup.
   `onSelect`) with the argument as `detail` and `preventDefault`
   relayed, `api` and `destroy()` exposed, `attributeChangedCallback`
   into `updateProps`, `disconnectedCallback` destroying.
-- `menu.ts`, `submenu.ts`, `dialog.ts`, `popover.ts`, `tooltip.ts`:
-  one subclass each with its table and callbacks; the menu mount takes
+- `menu.ts`, `submenu.ts`, `listbox.ts`, `select.ts`, `dialog.ts`,
+  `popover.ts`, `tooltip.ts`: one subclass each with its table and
+  callbacks; the menu mount takes
   `<mono-submenu>` roots as it takes `[data-part=submenu]` today,
   reading their attributes for the submenu's positioning and
   reflecting their `open`.

.agents/specs/cell-model.md

@@ -317,7 +317,10 @@ text run iff its computed display is exactly `inline` (or `contents`).
 ride the run as SINGLE UNBREAKABLE UNITS, per CSS: the run holds an
 object-replacement marker (U+FFFC) whose advance is the box's laid-out
 width (shrink-to-fit against the leaf's content box), with break
-opportunities on both sides like browsers give replaced elements. The
+opportunities on both sides like browsers give replaced elements. Where
+the container sizes itself to its content, the marker's advance is the
+box's width contribution, as it is for any child: a width of its own,
+clamped by its min and max, else its content's. The
 box stays IN FLOW — the engine sizes it to exactly those cells and the
 browser's own line layout places it, so the two agree by construction;
 its interior is a normal layout subtree on the grid (`inline-flex`

.agents/specs/scrolling.md

@@ -25,6 +25,11 @@ truth.
   instead of chaining. Rounding can still put the native ceiling a
   pixel either side of the multiple, so "at the native ceiling" reads
   as "at max" and the settle parks the max cell ON the ceiling.
+- **A container is known once its box is.** The offsets the paint
+  mirrors are collected from the laid-out tree, and an out-of-flow box
+  takes its size in the positioning pass, so the collection runs again
+  after it: a scroller inside a popover, a menu, or a select's content
+  is a container like any other, and the grid follows its scroll.
 - **The browser owns scroll physics; the engine mirrors on the grid.**
   Authored `overflow(-x|-y): auto | scroll` stays LIVE on the light
   element (not normalized away like `clip`/`hidden` are), so the
@@ -46,7 +51,10 @@ truth.
   descendants by the cell-quantized scroll and CULLS ink at the
   PADDING box per CSS (reserved gutter cells excluded — the bar owns
   them): padding sits blank at the scroll extremes and content flows
-  through it mid-scroll. The same rect covers `overflow: clip`. During a live grid-mode drag,
+  through it mid-scroll, under the border's own cells where the box has
+  one — a native `scrollIntoView` aligns to the scrollport, so a
+  component bringing an item into view aims at the content box instead
+  (specs/ui.md). The same rect covers `overflow: clip`. During a live grid-mode drag,
   scroll repaints are HELD like any structural repaint
   (`holdStructural`) and apply on release.
 - **Offsets are cell-quantized for ink; the native position settles to

.agents/specs/ui.md

@@ -1,14 +1,17 @@
 # Spec: `@monowind/ui` — accessible components on the grid
 
 Status: **implemented** (2026-09-13, the framework packages and
-examples 2026-09-18; `packages/ui`, one entry per component, plan
-`2026-09-13-ui.md`). The engine features it needs are
-`top-layer.md` and `anchor-positioning.md`; motion is `animations.md`.
+examples 2026-09-18, the listbox and the select 2026-09-21;
+`packages/ui`, one entry per component, plan `2026-09-13-ui.md`). The
+engine features it needs are `top-layer.md` and
+`anchor-positioning.md`; motion is `animations.md`, and a list's scroll
+is `scrolling.md`.
 
 ## Motivation
 
-A menu, a dialog, a popover, a tooltip: every application needs them,
-and doing them accessibly — roles and states, roving focus, typeahead,
+A menu, a list to choose from, a dialog, a popover, a tooltip: every
+application needs them, and doing them accessibly — roles and states,
+roving focus, typeahead,
 focus trapping and restore, dismissal, nested menus — is where most
 hand-rolled components fail. monowind is a custom element that renders
 whatever DOM it holds, so its components must be framework-agnostic
@@ -21,9 +24,10 @@ the engine places and layers the parts, Zag runs them.
 ## Shape
 
 - **One package, a subpath per component**: `@monowind/ui/menu`,
-  `@monowind/ui/dialog`, `@monowind/ui/popover`, `@monowind/ui/tooltip`
-  first; `select`, `combobox`, `tabs` and the rest follow the same
-  shape. Versioned in lockstep with `monowind`.
+  `@monowind/ui/listbox`, `@monowind/ui/select`, `@monowind/ui/dialog`,
+  `@monowind/ui/popover`, and `@monowind/ui/tooltip`, in that order
+  wherever they are listed; `combobox`, `tabs` and the rest follow the
+  same shape. Versioned in lockstep with `monowind`.
 - **A core that touches no DOM**: per component, `props(p)`, the
   machine's props with Zag's own positioning off, Zag's `machine`
   re-exported, `connect(service, normalizeProps, p)` — Zag's connect
@@ -77,6 +81,53 @@ props)` is the core plus `VanillaMachine` and `spreadProps`: parts
   highlight, and ids are its own. It returns the API and a `destroy`
   that stops the machine and takes its handlers off the parts, after
   which a mount on the same markup wires it again.
+- **A component with no floating part stands in the flow.** A listbox
+  is roles, selection, and keyboard alone, so the engine lays its parts
+  out as it lays out any box and the entry adds no props to Zag's. It
+  takes the mount the anchored components build on, without the
+  trigger, positioner, and content that one spreads, and the framework
+  packages return its API alone. Its scroll is the engine's
+  (scrolling.md): `overflow-y-auto` with a `max-h-*` on the content
+  scrolls natively, a select's list the same, and Zag scrolling the
+  highlighted item into view repaints the grid on the cells it moved
+  to. That scroll targets the content box, not the scrollport
+  (`scrollToIndexFn` in the machine's props, an author's own over it):
+  the engine reserves a box's border cells as padding, so a scroll into
+  the scrollport would stop with the item under the border.
+- **A list's focus starts at its selection.** The content taking focus
+  highlights the selected item, or the first where nothing is selected,
+  as ARIA's listbox pattern has it, and brings that row into view. A
+  composite's own cells stay plain and the grid draws no focus ring to
+  fall back on (cell-model.md), so the highlight is the whole of the
+  indication and a stale one misplaces it: Zag leaves the highlight
+  empty on focus wherever a value is selected, and a pointer passing
+  over an unfocused list leaves its own, which nothing shows until the
+  next focus. The scroll skips a focus the pointer caused, as the
+  machine's own does, so a press on a visible item never jumps the list
+  out from under it.
+- **The markup is a listbox's collection.** Zag takes its items as a
+  `collection` the author builds; for markup that names none, the
+  marked items make one — the `data-value` each carries, the words of
+  its `item-text`, and `data-disabled` — so a list of static items is
+  markup alone, and an item the author's own collection leaves out
+  stays plain markup. The mount's own element is the `root`, its id the
+  markup's so the page still finds it, and `data-highlight-on-hover` on
+  it passes Zag's `highlightOnHover` for every item: it moves the
+  highlight, Zag keeping `data-highlighted` for the keyboard's focus
+  and leaving the pointer's feedback to `hover:`.
+- **A select is a listbox on a trigger.** Zag's select is the anchored
+  one — the same collection, items, and keyboard, its content in the
+  top layer — so it takes the anchored mount and the placement mapping
+  unchanged, and shares the items and the scroll with the listbox. Two
+  parts are the mount's to fill, a markup author having nothing else to
+  render them with: the `value-text`, whose markup text is its
+  placeholder and whose content the mount writes from the API; and an
+  optional `hidden-select`, the native control a form posts under the
+  machine's `name`, filled with an option per item and set to
+  `display: none`, which the layout skips while a form still submits
+  it; where the select takes several values, the options carry the
+  selection, the adapter's one assignment of `value` being a single
+  control's.
 - **States are attributes**: `data-state`, `data-highlighted`,
   `data-disabled`, `data-placement`, as Zag sets them, so an author
   styles them with Tailwind's data variants
@@ -157,7 +208,8 @@ the functions; the functions change only where the elements need them
 to, and additively.
 
 - **Elements for markup**: `<mono-menu>`, `<mono-submenu>`,
-  `<mono-dialog>`, `<mono-popover>`, `<mono-tooltip>`, from
+  `<mono-listbox>`, `<mono-select>`, `<mono-dialog>`,
+  `<mono-popover>`, `<mono-tooltip>`, from
   `@monowind/ui/elements`, registered by `defineMonoUi()` as core's
   are by `defineMonoWind()` — the entry registers nothing on import,
   so the package's `sideEffects: false` holds; the CDN bundle calls it.
@@ -223,11 +275,15 @@ to, and additively.
 false`), one namespace per component with Ark UI's anatomy —
   `Menu.Root`, `Menu.Trigger`, `Menu.Positioner`, `Menu.Content`,
   `Menu.Item`, `Menu.ItemGroup`, `Menu.ItemGroupLabel`,
-  `Menu.Separator`, `Menu.TriggerItem`; `Dialog.Root`, `.Trigger`,
+  `Menu.Separator`, `Menu.TriggerItem`; `Listbox.Root`, `.Label`,
+  `.Content`, `.Item`, `.ItemText`, `.ItemIndicator`, `.ItemGroup`,
+  `.ItemGroupLabel`; `Select` the same with `.Control`, `.Trigger`,
+  `.ValueText`, `.Indicator`, `.ClearTrigger`, `.Positioner`, and
+  `.HiddenSelect` around them; `Dialog.Root`, `.Trigger`,
   `.Positioner`, `.Content`, `.Title`, `.Description`,
   `.CloseTrigger`; `Popover` the same; `Tooltip.Root`, `.Trigger`,
-  `.Positioner`, `.Content` — Ark's other parts (arrows, indicators,
-  a backdrop, checkbox and radio items) left for a later need. `Root`
+  `.Positioner`, `.Content` — Ark's other parts (arrows, a backdrop,
+  checkbox and radio items) left for a later need. `Root`
   takes the machine's props, `id` optional and generated (`useId`,
   Vue's `useId`, Svelte's `$props.id()`), renders nothing of its own,
   and hands the API down through context; `RootProvider` takes an
@@ -255,12 +311,20 @@ false`), one namespace per component with Ark UI's anatomy —
 ## Testing
 
 - Node: the placement mapping to `position-area`; the vanilla path's
-  parts found and wired; the show and hide of the positioner around
-  the exit's transitions; the React hooks and Vue composables rendered
-  through their frameworks (`hooks.test.tsx`, `composables.test.ts`).
-- Storybook, per component, in every engine: open and close by
-  pointer and keyboard; the floating part's cells directly under (or
-  beside, above) the trigger and the light element's box on them, over
+  parts found and wired, a list's collection read from its markup and a
+  select's hidden control among them; the show and hide of the
+  positioner around the exit's transitions; the React hooks and Vue
+  composables rendered through their frameworks (`hooks.test.tsx`,
+  `composables.test.ts`), a component with no floating part included.
+- Storybook, per component, in every engine: the listbox's roles, its
+  value selected by press and by Enter with the indicator following it
+  on the grid, the pointer highlight its root asks for, and the list
+  scrolled to the item the keyboard highlights; the select's list
+  anchored under its trigger, the value it puts on the trigger and in
+  its form control, and that control left out of the layout; per
+  anchored component, open and close by pointer and keyboard; the
+  floating part's cells directly under (or beside, above) the trigger
+  and the light element's box on them, over
   the page's later text; Escape and focus restore (an outside press
   dismisses through Zag's document listener on a deferred animation
   frame, which WebKit suspends in a backgrounded window, so the
@@ -297,7 +361,10 @@ false`), one namespace per component with Ark UI's anatomy —
 - `packages/ui`: `anchor.ts` (the placement table, the anchor name,
   the props and their merge, `anchoredApi`), `top-layer.ts`
   (`syncTopLayer`, its own `./top-layer` subpath for the framework
-  packages), `vanilla.ts` (the parts, the mount), and `menu.ts`,
+  packages), `vanilla.ts` (the parts, the mount, and the anchored mount
+  over it), `items.ts` (the markup's collection and the item parts a
+  listbox and a select share), `scroll.ts` (the highlight scrolled into
+  the content box), and `menu.ts`, `listbox.ts`, `select.ts`,
   `dialog.ts`, `popover.ts`, `tooltip.ts` (each `props`, `api`, the
   mount); `@zag-js/vanilla` and the machines as dependencies;
   `dist/cdn.js` for classic scripts, `monowind.ui`.

README.md

@@ -124,17 +124,18 @@ attributes.
 
 ## Components
 
-`@monowind/ui` adds accessible components — a menu, a dialog, a
-popover, a tooltip — as [Zag.js](https://zagjs.com) state machines
-wired to the grid: Zag runs the roles, the keyboard, typeahead, focus,
-and dismissal; the engine places each floating part against its
-trigger in cells, in the top layer above everything, flipped where
-the host leaves no room. Headless, so a component styled through the
-theme's tokens wears whatever theme its host does. Mount one on
-markup marked with `data-part`, take `@monowind/ui-react`'s hooks,
-`@monowind/ui-vue`'s composables, or `@monowind/ui-svelte`'s functions, or
-use Zag's adapter for another framework with the package's `props()`
-and `connect()`.
+`@monowind/ui` adds accessible components — a menu, a listbox, a
+select, a dialog, a popover, a tooltip — as
+[Zag.js](https://zagjs.com) state machines wired to the grid: Zag runs
+the roles, the keyboard, typeahead, focus, and dismissal; the engine
+places each floating part against its trigger in cells, in the top
+layer above everything, flipped where the host leaves no room, and a
+listbox in the flow like any other box. Headless, so a component styled
+through the theme's tokens wears whatever theme its host does. Mount
+one on markup marked with `data-part`, take `@monowind/ui-react`'s
+hooks, `@monowind/ui-vue`'s composables, or `@monowind/ui-svelte`'s
+functions, or use Zag's adapter for another framework with the
+package's `props()` and `connect()`.
 
 ```ts
 import { menu } from "@monowind/ui/menu";

apps/example-svelte/package.json

@@ -12,7 +12,7 @@
   },
   "dependencies": {
     "@monowind/ui-svelte": "workspace:*",
-    "svelte": "^5.57.0"
+    "svelte": "^5.57.1"
   },
   "devDependencies": {
     "@monowind/vite": "workspace:*",

apps/storybook/stories/helpers.ts

@@ -120,6 +120,14 @@ export const cellSize = (host: HTMLElement): { width: number; height: number } =
 export const gridOf = (host: HTMLElement): HTMLElement => host.shadowRoot!.getElementById("grid")!;
 export const rowsOf = (host: HTMLElement): string[] => gridOf(host).textContent!.split("\n");
 
+/** Whether the grid painted a row holding `text`. */
+export const showsRow = (host: HTMLElement, text: string): boolean =>
+  rowsOf(host).some((row) => row.includes(text));
+
+/** A wait for the grid to paint a row holding `text`. */
+export const expectRow = (host: HTMLElement, text: string): Promise<void> =>
+  waitFor(() => expect(showsRow(host, text), `the grid paints "${text}"`).toBe(true));
+
 /** The first span the grid painted holding `text`. */
 export const paintedSpan = (host: HTMLElement, text: string): HTMLElement | undefined =>
   Array.from(gridOf(host).querySelectorAll("span")).find((el) => el.textContent!.includes(text));