@pienter/ui 0.10.0 → 0.13.0

package/CHANGELOG.md

@@ -2,6 +2,75 @@
 
 ## Unreleased
 
+## 0.13.0 - 2026-09-15
+
+### Added
+
+- View mode for `BlockEditor`: `readonly` renders the block list as content.
+  The drag handle, move, remove and add controls and the reorder hint go, every
+  mutation returns early, and `#block` receives `readonly` beside `disabled` so
+  the fields render read-only. The collapse toggles stay — they are the escape
+  hatch for a long list — and blocks start expanded. Each block title now sits
+  in a heading element around its collapse button, so heading navigation works
+  in both modes; `level` (2–6, default 3) picks it. A read-only editor carries
+  `data-readonly="true"`, and `Panel` keeps its border, background and padding
+  around one instead of dropping them as it does for an editable editor.
+- `image` field type on `RecordFormField`: a URL `type="url"` TextInput while
+  editing, the image itself when read-only, capped so a full-size asset cannot
+  push the layout, with the same em dash as `RecordDetails` when the value is
+  empty. `altName` points at a sibling field in the same list for the
+  alternative text, so it works for nested and indexed paths.
+
+### Fixed
+
+- A read-only `Textarea` grows with its value instead of clipping it inside a
+  box nobody can type in; `rows` becomes its minimum height.
+
+## 0.12.0 - 2026-09-15
+
+### Added
+
+- View mode: `readonly` on `RecordForm` renders the same form read-only. The
+  flag fans out to `RecordFields` (and its `field:<name>` slot props) and to
+  every form primitive — `TextInput`, `Textarea`, `NumberField`, `DateInput`,
+  `Select`, `Combobox`, `Checkbox`, `Switch`, `RadioGroup` and `TagsInput`
+  gain a `readonly` prop. Native inputs get the `readonly` attribute; a
+  `select`, checkbox, switch or radio group gets `aria-readonly="true"` and
+  ignores changes; `NumberField` drops its steppers, `TagsInput` its remove
+  buttons, `Combobox` keeps its listbox closed. A read-only field is never
+  disabled: it stays in the tab order with its border, text colour and focus
+  ring, on the muted `--bg-clr-surface-2` surface, without a placeholder.
+  `.pui-field` carries `data-readonly="true"` for styling. `Form` also takes
+  `readonly`: it renders no actions row and never emits `submit`, Enter
+  included. Everything is off by default, so existing consumers are
+  unaffected.
+
+- `RecordLayout` and `Panel`: the sidebar-plus-panels shape a record page is
+  built from. `RecordLayout` places a `sidebar` slot (an `aside` named through
+  `sidebar-labelledby`) beside a main column and stacks them below 56em.
+  `Panel` is one bordered section with its heading inside it (`title`,
+  `description`, `level`, `title-id`); it honours `hidden`, so it serves as a
+  tab panel as-is, and drops its border, background and padding when its
+  direct child is a `BlockEditor`. Both set `--pui-record-fields-columns` for
+  the RecordFields inside them — one column in the sidebar, two in a panel
+  from 48em with textarea fields spanning the row — and the sidebar stacks
+  RecordDetails labels over their values, so a consumer page no longer
+  carries any of that CSS.
+
+### Fixed
+
+- `Tabs` wraps its buttons inside a narrow container instead of pushing the
+  tablist past the container's edge.
+
+## 0.11.0 - 2026-09-15
+
+### Added
+
+- The Vue CMS playground defines its contacts collection once and mounts it as
+  both the `/contacts` module index and the related index on a company's
+  Contacts tab, demonstrating `Index` placement and prefixed query syncing with
+  realistic consumer-owned columns, loaders, cells and navigation.
+
 ## 0.10.0 - 2026-09-15
 
 ### Changed
@@ -13,9 +82,31 @@
   style that targeted them moves to `pui-page-header` and its
   `__heading`, `__title`, `__description` and `__actions` elements. Markup,
   spacing and type are unchanged in both placements.
+- Bare anchors get the standard `:focus-visible` ring from the base layer,
+  and their underline offset is the `--space-3xs` token instead of a `0.14em`
+  literal, so content links inside a consumer page need no app rule for
+  colour, offset or focus. Components that style their own anchors (Button,
+  Breadcrumb, Sidebar) are unaffected: their rules sit in the components
+  layer, which outranks base.
+- Index's page-size Select renders through the new inline field layout
+  instead of an Index-owned flex override; no visual change.
 
 ### Added
 
+- Inline field layout: `layout="inline"` on TextInput, Textarea, Select,
+  NumberField, DateInput, Combobox and TagsInput puts the label beside the
+  control on one row, with hint and errors wrapping below across both
+  columns. It sets `data-layout="inline"` on `.pui-field`, the attribute
+  Checkbox and Switch already carry, so one scaffold rule serves both DOM
+  orders; label association, `aria-describedby` and status recolour are
+  identical to the stacked layout. Checkbox and Switch stay inline-only and
+  RadioGroup stacked-only, so neither takes the prop.
+- `pui-index__primary` and `pui-index__subline`: a two-line primary cell for
+  an Index `cell:<key>` slot, the title (usually the record link) over a
+  muted, smaller subline such as a slug.
+- `pui-badge-list`: put it on any element wrapping several badges and they
+  wrap with a small gap. Loaded with Badge.
+
 - `PageHeader` at `@pienter/ui/components/PageHeader.vue`: the title,
   description and actions band above a module index or a record page,
   extracted from Index so detail and form pages no longer hand-roll the same

package/CONVENTIONS.md

@@ -96,18 +96,19 @@ list, add a token to `0-settings/` rather than hardcoding.
 
 Variants and runtime states live on `data-*` attributes on the block element, never on class names.
 
-| Attribute          | Purpose                                                                                                                                                    | Example values                                                                        |
-| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| `data-variant`     | Visual variant (mutually exclusive within a component)                                                                                                     | `primary`, `secondary`, `ghost`, `danger`, `link`                                     |
-| `data-size`        | Sizing scale (mutually exclusive)                                                                                                                          | `sm`, `md` (Button/IconButton); `sm`/`md`/`lg` (Icon); other components add their own |
-| `data-animation`   | Continuous decorative animation on the block                                                                                                               | `spin` (Icon)                                                                         |
-| `data-tone`        | Semantic tone for non-variant components (Alert, Badge, Toast)                                                                                             | `brand`, `success`, `warning`, `danger`                                               |
-| `data-block`       | Block-level layout flag (boolean)                                                                                                                          | `'true'` or absent                                                                    |
-| `data-state`       | Runtime state controlled by code or a behavior composable                                                                                                  | `loading`, `open`, `closed`, `checked`, `indeterminate`                               |
-| `data-status`      | Derived semantic status for form primitives (validation outcome)                                                                                           | `error`, `success`                                                                    |
-| `data-layout`      | Form-primitive scaffold layout selector — lives on `.pui-field`; flips between stacked label-above (default) and compact inline control-left + label-right | `stacked` (default; attribute may be omitted), `inline`                               |
-| `data-orientation` | Layout direction for grouped controls (RadioGroup items, future SegmentedControl, etc.) — lives on the group container                                     | `vertical` (default for RadioGroup), `horizontal`                                     |
-| `data-placement`   | Where a CMS surface is mounted, which decides its chrome and heading level — lives on `.pui-index`                                                         | `module` (default), `related`                                                         |
+| Attribute          | Purpose                                                                                                                                                         | Example values                                                                        |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `data-variant`     | Visual variant (mutually exclusive within a component)                                                                                                          | `primary`, `secondary`, `ghost`, `danger`, `link`                                     |
+| `data-size`        | Sizing scale (mutually exclusive)                                                                                                                               | `sm`, `md` (Button/IconButton); `sm`/`md`/`lg` (Icon); other components add their own |
+| `data-animation`   | Continuous decorative animation on the block                                                                                                                    | `spin` (Icon)                                                                         |
+| `data-tone`        | Semantic tone for non-variant components (Alert, Badge, Toast)                                                                                                  | `brand`, `success`, `warning`, `danger`                                               |
+| `data-block`       | Block-level layout flag (boolean)                                                                                                                               | `'true'` or absent                                                                    |
+| `data-state`       | Runtime state controlled by code or a behavior composable                                                                                                       | `loading`, `open`, `closed`, `checked`, `indeterminate`                               |
+| `data-status`      | Derived semantic status for form primitives (validation outcome)                                                                                                | `error`, `success`                                                                    |
+| `data-layout`      | Form-primitive scaffold layout selector — lives on `.pui-field`; `inline` puts label and control on one row in DOM order, hint and errors below (see checklist) | `stacked` (default; attribute may be omitted), `inline`                               |
+| `data-orientation` | Layout direction for grouped controls (RadioGroup items, future SegmentedControl, etc.) — lives on the group container                                          | `vertical` (default for RadioGroup), `horizontal`                                     |
+| `data-placement`   | Where a CMS surface is mounted, which decides its chrome and heading level — lives on `.pui-index`                                                              | `module` (default), `related`                                                         |
+| `data-readonly`    | Read-only form primitive (boolean) — lives on `.pui-field` beside the control's native `readonly` / `aria-readonly`, so one selector styles every primitive     | `'true'` or absent                                                                    |
 
 The example values listed for each attribute are non-exhaustive — components add states as needed (e.g. `expanded`, `selected`, `active` for upcoming Disclosure, Tabs, Sidebar). New values follow the same kebab-case rule and live on the same attribute family.
 
@@ -272,15 +273,17 @@ role="status">` with one `<li>` per error message, only when errors are
     typed prop through. Order matters: bind `$attrs` first, then explicit
     props — explicit bindings win, which is what we want.
 
-- [ ] Compact form primitives (Switch, Checkbox, individual Radio items) use
-      `data-layout="inline"` on the `pui-field` wrapper to flip the layout to
-      control-left + label-right. Everything else (label association via
-      `for`/`id`, hint/error rendering, ARIA wiring, `aria-describedby`
-      joining, status-driven recolour) stays unchanged. The DOM source order
-      under `data-layout="inline"` is **control first, label second** so the
-      `<label for>` association is read in left-to-right order, and the
-      `pui-field__hint` elements remain after the label so a single CSS rule
-      (`grid-column: 1 / -1`) drops them onto a row below the control + label.
+- [ ] `data-layout="inline"` on the `pui-field` wrapper puts label and
+      control on one row in DOM order; the `pui-field__hint` elements stay
+      after them so a single CSS rule (`grid-column: 1 / -1`) drops them onto
+      the row below. Compact primitives (Switch, Checkbox) always render it,
+      with the control **first** in DOM order so the `<label for>`
+      association is read left-to-right. Label-first primitives (TextInput,
+      Textarea, Select, NumberField, DateInput, Combobox, TagsInput) expose
+      it as `layout?: 'stacked' | 'inline'` (default `stacked`, attribute
+      omitted). Everything else (label association via `for`/`id`,
+      hint/error rendering, ARIA wiring, `aria-describedby` joining,
+      status-driven recolour) stays unchanged in both layouts.
 
 **Worked example — TextInput**: see `packages/ui/components/form/text-input/`. The
 wrapper is `<div class="pui-field" data-status>`, the label is
@@ -1278,9 +1281,11 @@ follow the shape of an existing one.
 | Navbar       | [`components/navigation/navbar/AUDIT.md`](./components/navigation/navbar/AUDIT.md)         |
 | NumberField  | [`components/form/number-field/AUDIT.md`](./components/form/number-field/AUDIT.md)         |
 | Pagination   | [`components/navigation/pagination/AUDIT.md`](./components/navigation/pagination/AUDIT.md) |
+| Panel        | [`components/layout/record-layout/AUDIT.md`](./components/layout/record-layout/AUDIT.md)   |
 | Popover      | [`components/overlay/popover/AUDIT.md`](./components/overlay/popover/AUDIT.md)             |
 | Progress     | [`components/feedback/progress/AUDIT.md`](./components/feedback/progress/AUDIT.md)         |
 | RadioGroup   | [`components/form/radio-group/AUDIT.md`](./components/form/radio-group/AUDIT.md)           |
+| RecordLayout | [`components/layout/record-layout/AUDIT.md`](./components/layout/record-layout/AUDIT.md)   |
 | Segmented    | [`components/form/select/AUDIT.md`](./components/form/select/AUDIT.md)                     |
 | Select       | [`components/form/select/AUDIT.md`](./components/form/select/AUDIT.md)                     |
 | Separator    | [`components/layout/separator/AUDIT.md`](./components/layout/separator/AUDIT.md)           |
@@ -1463,6 +1468,13 @@ custom sidebar/tab layouts. RecordFields takes the same draft and renders a
 subset, with `--pui-record-fields-columns` as its grid seam. It never renders a
 form element. Callers expose the relevant tab when backend issues arrive.
 
+RecordLayout and Panel give a record page its shape (`CONTEXT.md`): a sidebar
+`aside` named through `sidebar-labelledby` beside a main column that stacks
+below 56em, and one bordered section per field group or tab with its heading
+inside it. Panel honours `hidden`, so a consumer toggles tab panels with the
+attribute, and drops its chrome around a direct `BlockEditor` child. Both set
+`--pui-record-fields-columns` for the RecordFields inside them.
+
 BlockEditor owns an ordered array of stable `id`/`type` blocks and emits updates
 for edits, addition, removal and reordering. Creation factories and slot content
 stay caller-owned. Optional `v-model:collapsed` lets pages reveal invalid blocks.

package/components/display/badge/badge.css

@@ -53,4 +53,11 @@
             border-color: transparent;
         }
     }
+
+    /* A wrapped group of badges (tags, labels). */
+    .pui-badge-list {
+        display: flex;
+        flex-wrap: wrap;
+        gap: var(--space-2xs);
+    }
 }

package/components/form/block-editor/BlockEditor.vue

@@ -18,13 +18,19 @@ const props = withDefaults(
         /** Optional controlled list of collapsed block ids. */
         collapsed?: readonly string[];
         disabled?: boolean;
+        /** View mode: the editing affordances go, the collapse toggles stay and the slot renders read-only. */
+        readonly?: boolean;
         label?: string;
+        /** Heading level of each block title: `3` sits under a level-2 `Panel` title. */
+        level?: 2 | 3 | 4 | 5 | 6;
         blockLabel?: (block: T, index: number) => string;
     }>(),
     {
         disabled: false,
+        readonly: false,
         collapsed: undefined,
         label: 'Content blocks',
+        level: 3,
         blockLabel: undefined,
     },
 );
@@ -39,12 +45,14 @@ defineSlots<{
         index: number;
         update: (patch: BlockPatch<T>) => void;
         disabled: boolean;
+        readonly: boolean;
     }) => unknown;
     summary?: (scope: { block: T; index: number }) => unknown;
     empty?: () => unknown;
 }>();
 
 const id = generateId('blocks');
+const locked = computed(() => props.disabled || props.readonly);
 const localCollapsed = ref<string[]>([]);
 const collapsed = computed(
     () => new Set(props.collapsed ?? localCollapsed.value),
@@ -95,7 +103,7 @@ function focusBlock(key: string) {
 }
 
 function add(type: BlockType<T>) {
-    if (props.disabled) return;
+    if (locked.value) return;
     const block = type.create();
     if (
         !block.id ||
@@ -112,7 +120,7 @@ function add(type: BlockType<T>) {
 }
 
 function update(key: string, patch: BlockPatch<T>) {
-    if (props.disabled) return;
+    if (locked.value) return;
     emit(
         'update:modelValue',
         props.modelValue.map((block) =>
@@ -124,7 +132,7 @@ function update(key: string, patch: BlockPatch<T>) {
 }
 
 function remove(key: string) {
-    if (props.disabled) return;
+    if (locked.value) return;
     const index = props.modelValue.findIndex((block) => block.id === key);
     const block = props.modelValue[index];
     if (!block) return;
@@ -144,7 +152,7 @@ function remove(key: string) {
 }
 
 function move(key: string, target: number) {
-    if (props.disabled) return;
+    if (locked.value) return;
     const source = props.modelValue.findIndex((block) => block.id === key);
     if (
         source < 0 ||
@@ -220,7 +228,7 @@ function stopDrag() {
 }
 
 function startDrag(event: PointerEvent, key: string) {
-    if (props.disabled || event.button !== 0 || props.modelValue.length < 2)
+    if (locked.value || event.button !== 0 || props.modelValue.length < 2)
         return;
     stopDrag();
     const handle = event.currentTarget as HTMLButtonElement;
@@ -295,12 +303,9 @@ function cancelWithEscape(event: KeyboardEvent) {
     }
 }
 
-watch(
-    () => props.disabled,
-    (disabled) => {
-        if (disabled) stopDrag();
-    },
-);
+watch(locked, (value) => {
+    if (value) stopDrag();
+});
 watch(() => props.modelValue.map((block) => block.id).join('\u0000'), stopDrag);
 onBeforeUnmount(stopDrag);
 </script>
@@ -309,15 +314,16 @@ onBeforeUnmount(stopDrag);
     <div
         class="pui-block-editor"
         :data-disabled="disabled ? 'true' : undefined"
+        :data-readonly="readonly ? 'true' : undefined"
     >
-        <p :id="`${id}-hint`" class="pui-block-editor__hint">
+        <p v-if="!readonly" :id="`${id}-hint`" class="pui-block-editor__hint">
             Use the move buttons to reorder, or drag with a pointer.
         </p>
         <ol
             v-if="modelValue.length"
             class="pui-block-editor__list"
             :aria-label="label"
-            :aria-describedby="`${id}-hint`"
+            :aria-describedby="readonly ? undefined : `${id}-hint`"
         >
             <li
                 v-for="(block, index) in modelValue"
@@ -333,6 +339,7 @@ onBeforeUnmount(stopDrag);
             >
                 <div class="pui-block-editor__header">
                     <button
+                        v-if="!readonly"
                         class="pui-block-editor__drag"
                         type="button"
                         tabindex="-1"
@@ -344,35 +351,42 @@ onBeforeUnmount(stopDrag);
                         <Icon name="arrow-up-down" size="sm" />
                     </button>
                     <div class="pui-block-editor__heading">
-                        <button
-                            type="button"
-                            class="pui-block-editor__toggle"
-                            data-block-toggle
-                            :disabled="disabled"
-                            :aria-label="`${collapsed.has(block.id) ? 'Expand' : 'Collapse'} ${title(block, index)}`"
-                            :aria-expanded="
-                                collapsed.has(block.id) ? 'false' : 'true'
-                            "
-                            :aria-controls="bodyId(block)"
-                            @click="toggle(block.id)"
+                        <component
+                            :is="`h${level}`"
+                            class="pui-block-editor__heading-text"
                         >
-                            <Icon
-                                :name="
-                                    collapsed.has(block.id)
-                                        ? 'chevron-right'
-                                        : 'chevron-down'
+                            <button
+                                type="button"
+                                class="pui-block-editor__toggle"
+                                data-block-toggle
+                                :disabled="disabled"
+                                :aria-label="`${collapsed.has(block.id) ? 'Expand' : 'Collapse'} ${title(block, index)}`"
+                                :aria-expanded="
+                                    collapsed.has(block.id) ? 'false' : 'true'
                                 "
-                                size="sm"
-                            />
-                            <span class="pui-block-editor__title">{{
-                                title(block, index)
-                            }}</span>
-                            <span
-                                v-if="title(block, index) !== typeLabel(block)"
-                                class="pui-block-editor__type"
-                                >{{ typeLabel(block) }}</span
+                                :aria-controls="bodyId(block)"
+                                @click="toggle(block.id)"
                             >
-                        </button>
+                                <Icon
+                                    :name="
+                                        collapsed.has(block.id)
+                                            ? 'chevron-right'
+                                            : 'chevron-down'
+                                    "
+                                    size="sm"
+                                />
+                                <span class="pui-block-editor__title">{{
+                                    title(block, index)
+                                }}</span>
+                                <span
+                                    v-if="
+                                        title(block, index) !== typeLabel(block)
+                                    "
+                                    class="pui-block-editor__type"
+                                    >{{ typeLabel(block) }}</span
+                                >
+                            </button>
+                        </component>
                         <div
                             v-if="$slots.summary"
                             class="pui-block-editor__summary"
@@ -384,7 +398,7 @@ onBeforeUnmount(stopDrag);
                             />
                         </div>
                     </div>
-                    <div class="pui-block-editor__actions">
+                    <div v-if="!readonly" class="pui-block-editor__actions">
                         <IconButton
                             name="arrow-up"
                             variant="ghost"
@@ -427,16 +441,19 @@ onBeforeUnmount(stopDrag);
                             (patch: BlockPatch<T>) => update(block.id, patch)
                         "
                         :disabled="disabled"
+                        :readonly="readonly"
                     />
                 </div>
             </li>
         </ol>
         <div v-else class="pui-block-editor__empty">
-            <slot name="empty"
-                >No blocks yet. Add a block to start writing.</slot
-            >
+            <slot name="empty">{{
+                readonly
+                    ? 'No content blocks.'
+                    : 'No blocks yet. Add a block to start writing.'
+            }}</slot>
         </div>
-        <div :id="`${id}-add`" class="pui-block-editor__add">
+        <div v-if="!readonly" :id="`${id}-add`" class="pui-block-editor__add">
             <Button
                 v-for="type in blockTypes"
                 :key="type.type"

package/components/form/block-editor/block-editor.css

@@ -62,6 +62,13 @@
         min-inline-size: 0;
     }
 
+    /* A heading element so the toggle is reachable by heading navigation; it
+     * carries no type scale of its own. */
+    .pui-block-editor__heading-text {
+        margin: 0;
+        font: inherit;
+    }
+
     .pui-block-editor__drag,
     .pui-block-editor__toggle {
         display: inline-flex;
@@ -124,6 +131,10 @@
     }
 
     .pui-block-editor__body {
+        /* A block body is a narrow box inside a panel; it keeps one column
+         * whatever the panel around it asks for. */
+        --pui-record-fields-columns: minmax(0, 1fr);
+
         display: grid;
         gap: var(--space-s);
         padding: var(--space-s);

package/components/form/checkbox/Checkbox.vue

@@ -1,5 +1,10 @@
 <template>
-    <div class="pui-field" data-layout="inline" :data-status="computedStatus">
+    <div
+        class="pui-field"
+        data-layout="inline"
+        :data-readonly="readonly ? 'true' : undefined"
+        :data-status="computedStatus"
+    >
         <input
             v-bind="$attrs"
             :id="inputId"
@@ -10,14 +15,11 @@
             :required="required"
             :disabled="disabled"
             :aria-checked="ariaCheckedValue"
+            :aria-readonly="readonly ? 'true' : undefined"
             :aria-invalid="hasErrors ? 'true' : undefined"
             :aria-describedby="describedBy"
-            @change="
-                emit(
-                    'update:modelValue',
-                    ($event.target as HTMLInputElement).checked,
-                )
-            "
+            @click="onClick"
+            @change="onChange"
         />
         <label class="pui-field__label" :for="inputId"
             >{{ label
@@ -54,6 +56,8 @@ const props = withDefaults(
         name?: string;
         required?: boolean;
         disabled?: boolean;
+        /** Read-only: `aria-readonly`, still focusable, but toggling is ignored. */
+        readonly?: boolean;
         hint?: string;
         errors?: string[];
         status?: 'error' | 'success';
@@ -64,6 +68,7 @@ const props = withDefaults(
         name: undefined,
         required: false,
         disabled: false,
+        readonly: false,
         hint: undefined,
         errors: () => [],
         status: undefined,
@@ -96,6 +101,17 @@ const describedBy = computed(() => {
 const ariaCheckedValue = computed<'true' | 'false'>(() =>
     props.modelValue ? 'true' : 'false',
 );
+
+// Cancelling `click` keeps the native checked state and fires no `change`;
+// the label's forwarded click and the Space key arrive here too.
+function onClick(event: MouseEvent): void {
+    if (props.readonly) event.preventDefault();
+}
+
+function onChange(event: Event): void {
+    if (props.readonly) return;
+    emit('update:modelValue', (event.target as HTMLInputElement).checked);
+}
 </script>
 
 <style>

package/components/form/checkbox/checkbox.css

@@ -41,6 +41,14 @@
         cursor: not-allowed;
     }
 
+    .pui-field[data-readonly='true'] .pui-checkbox {
+        cursor: default;
+    }
+
+    .pui-field[data-readonly='true'] .pui-checkbox:not(:checked) {
+        background: var(--bg-clr-surface-2);
+    }
+
     /* Status-driven recolour from the parent pui-field wrapper. */
     .pui-field[data-status='error'] .pui-checkbox {
         border-color: var(--border-clr-danger);
@@ -51,9 +59,19 @@
         border-color: var(--bg-clr-success, var(--border-clr-brand));
     }
 
+    /* The label is the click target for the box, so it reads as one. */
+    .pui-field:has(.pui-checkbox) .pui-field__label {
+        cursor: pointer;
+        user-select: none;
+    }
+
     /* Mute the label + cursor when the input is disabled. */
     .pui-field:has(.pui-checkbox:disabled) .pui-field__label {
         color: var(--text-clr-muted);
         cursor: not-allowed;
     }
+
+    .pui-field[data-readonly='true']:has(.pui-checkbox) .pui-field__label {
+        cursor: default;
+    }
 }

package/components/form/combobox/Combobox.vue

@@ -1,5 +1,11 @@
 <template>
-    <div ref="fieldRef" class="pui-field" :data-status="computedStatus">
+    <div
+        ref="fieldRef"
+        class="pui-field"
+        :data-layout="layout === 'inline' ? 'inline' : undefined"
+        :data-readonly="readonly ? 'true' : undefined"
+        :data-status="computedStatus"
+    >
         <label v-if="label" class="pui-field__label" :for="inputId"
             >{{ label
             }}<span
@@ -18,8 +24,9 @@
             role="combobox"
             :name="name"
             :value="displayValue"
-            :placeholder="placeholder"
+            :placeholder="readonly ? undefined : placeholder"
             :disabled="disabled"
+            :readonly="readonly"
             :required="required"
             :autocomplete="autocomplete"
             :popovertarget="listboxId"
@@ -142,6 +149,8 @@ const props = withDefaults(
         placeholder?: string;
         /** Disables the input (and thus the popover). */
         disabled?: boolean;
+        /** Read-only: native `readonly` on the input, still focusable, the listbox never opens. */
+        readonly?: boolean;
         /** Marks the input as required for form submission. */
         required?: boolean;
         /** Native autocomplete value forwarded to the input. */
@@ -174,6 +183,8 @@ const props = withDefaults(
         placement?: Placement;
         /** Pixel offset between input and listbox; default `4`. */
         offset?: number;
+        /** `inline` puts the label beside the control; hint and errors wrap below. */
+        layout?: 'stacked' | 'inline';
     }>(),
     {
         id: undefined,
@@ -182,6 +193,7 @@ const props = withDefaults(
         name: undefined,
         placeholder: undefined,
         disabled: false,
+        readonly: false,
         required: false,
         autocomplete: undefined,
         hint: undefined,
@@ -191,6 +203,7 @@ const props = withDefaults(
         emptyMessage: 'No results',
         placement: 'bottom-start',
         offset: 4,
+        layout: 'stacked',
     },
 );
 
@@ -302,7 +315,7 @@ const activeOptionDomId = computed(() => {
 });
 
 function open(): void {
-    if (props.disabled) return;
+    if (props.disabled || props.readonly) return;
     control.show();
 }
 
@@ -356,6 +369,7 @@ function selectOption(opt: ComboboxOption): void {
 }
 
 function onInput(event: Event): void {
+    if (props.readonly) return;
     const target = event.target as HTMLInputElement;
     query.value = target.value;
     isTyping.value = true;
@@ -398,6 +412,7 @@ function onOptionMouseEnter(idx: number): void {
 }
 
 function onKeydown(event: KeyboardEvent): void {
+    if (props.readonly) return;
     switch (event.key) {
         case 'ArrowDown':
             event.preventDefault();