@pienter/ui 0.11.0 → 0.14.0

package/CHANGELOG.md

@@ -2,6 +2,102 @@
 
 ## Unreleased
 
+## 0.14.0 - 2026-09-15
+
+### Changed
+
+- `AppLayout`'s main region is now the scrollport. The shell is one viewport
+  tall (`100dvh`), `.pui-app-layout__main` takes the height left under the
+  header and scrolls with `overflow: auto`, and the document never scrolls.
+  The header and navigation rail lose their `position: sticky`; they simply
+  stay put. This gives a page a definite height to work against: a sticky
+  pagination or action band pins to the region's bottom edge, a `1fr` row
+  takes the real leftover space, and a short page no longer grows a scrollbar
+  to fit a sticky aside. `overscroll-behavior-block: contain` on the region
+  keeps an iOS rubber-band from dragging the whole shell, and a print rule
+  (`block-size: auto`, `overflow: visible`) prints the whole page rather than
+  one screenful.
+
+    Consumer-visible: anything that scrolled the window must now scroll the
+    region. Vue Router's `scrollBehavior` only scrolls the window, so return
+    `false` from it and set `main.scrollTop` yourself on route change (and on
+    back, if you restore); move a `scroll-padding-block-end` for sticky bands
+    from `html` to `<main>`, and drop any `scroll-padding-block-start` for the
+    header, which is now outside the scrollport. A sticky band pins at the
+    region's content edge, inside its padding, so a page that ends in one
+    sets `--pui-app-layout-main-padding` with a `0` block-end instead of
+    pulling the band down with a negative margin. Fragment links to targets
+    inside the region keep working natively. Escape hatch, one line:
+    `.pui-app-layout { block-size: auto; min-block-size: 100dvh }` makes the
+    document the scrollport again (pin the header yourself if you want it
+    fixed).
+### Added
+
+- `sidebar-left` and `sidebar-right` icons: a panel outline with the divider on
+  the left or the right, for toggling a side column. `sidebar-left` is
+  Feather's `sidebar`; `sidebar-right` is its mirror on the same 24px grid.
+
+
+## 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

package/CONVENTIONS.md

@@ -108,6 +108,7 @@ Variants and runtime states live on `data-*` attributes on the block element, ne
 | `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.
 
@@ -1280,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)           |
@@ -1421,6 +1424,13 @@ Pinned upstream SHAs used across the table:
 `Index`, `RecordForm`, and `RecordDetails` compose existing primitives. Consumers
 register routes and supply endpoint-specific data functions, rendering and actions.
 
+They render inside `AppLayout`, whose main region is the scrollport: the shell
+is `100dvh` tall, `<main>` scrolls, the document does not. Page-level bands
+(`position: sticky`) and leftover-height rows (`1fr`) inside a page therefore
+resolve against a definite height. Scroll-to-top on navigation,
+`scroll-padding` for sticky bands and scroll restoration target that region,
+not the window; the AppLayout audit lists what a consumer wires.
+
 Index accepts `load(query, { signal })`, `columns` and `queryOptions`. It owns
 query state, rows, metadata, loading, failures and retry. Search is debounced;
 search/filter/sort/page-size changes reset page to 1. New requests and unmount
@@ -1465,6 +1475,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/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);
@@ -62,4 +70,8 @@
         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

@@ -3,6 +3,7 @@
         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"
@@ -23,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"
@@ -147,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. */
@@ -189,6 +193,7 @@ const props = withDefaults(
         name: undefined,
         placeholder: undefined,
         disabled: false,
+        readonly: false,
         required: false,
         autocomplete: undefined,
         hint: undefined,
@@ -310,7 +315,7 @@ const activeOptionDomId = computed(() => {
 });
 
 function open(): void {
-    if (props.disabled) return;
+    if (props.disabled || props.readonly) return;
     control.show();
 }
 
@@ -364,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;
@@ -406,6 +412,7 @@ function onOptionMouseEnter(idx: number): void {
 }
 
 function onKeydown(event: KeyboardEvent): void {
+    if (props.readonly) return;
     switch (event.key) {
         case 'ArrowDown':
             event.preventDefault();

package/components/form/date-input/DateInput.vue

@@ -2,6 +2,7 @@
     <div
         class="pui-field"
         :data-layout="layout === 'inline' ? 'inline' : undefined"
+        :data-readonly="readonly ? 'true' : undefined"
         :data-status="computedStatus"
     >
         <label class="pui-field__label" :for="inputId"
@@ -25,6 +26,7 @@
             :step="step"
             :required="required"
             :disabled="disabled"
+            :readonly="readonly"
             :aria-invalid="hasErrors ? 'true' : undefined"
             :aria-describedby="describedBy"
             @input="
@@ -84,6 +86,8 @@ const props = withDefaults(
         step?: number | string;
         required?: boolean;
         disabled?: boolean;
+        /** Read-only: the value shows in the field chrome, stays focusable and cannot be edited. */
+        readonly?: boolean;
         hint?: string;
         errors?: string[];
         status?: 'error' | 'success';
@@ -99,6 +103,7 @@ const props = withDefaults(
         step: undefined,
         required: false,
         disabled: false,
+        readonly: false,
         hint: undefined,
         errors: () => [],
         status: undefined,

package/components/form/form/Form.vue

@@ -22,7 +22,7 @@
             {{ statusMessage }}
         </div>
 
-        <div class="pui-form__actions">
+        <div v-if="!readonly" class="pui-form__actions">
             <slot name="actions">
                 <button
                     class="pui-btn"
@@ -52,6 +52,8 @@ const props = withDefaults(
     defineProps<{
         submitLabel?: string;
         busy?: boolean;
+        /** Read-only presentation: renders no actions row and ignores every submit, Enter included. */
+        readonly?: boolean;
         /** Top-level errors not tied to a specific field. */
         errors?: string[];
         /** Server-side per-field errors. Consumers SHALL replace the object reference rather than mutate in place. */
@@ -64,6 +66,7 @@ const props = withDefaults(
     {
         submitLabel: 'Submit',
         busy: false,
+        readonly: false,
         errors: () => [],
         fieldErrors: () => ({}),
         statusMessage: undefined,
@@ -105,7 +108,7 @@ const allFieldErrors = computed<Record<string, string[]>>(() => {
 
 function handleSubmit(): void {
     const formEl = formRef.value;
-    if (!formEl) return;
+    if (!formEl || props.readonly) return;
 
     const formData = new FormData(formEl);
 

package/components/form/number-field/NumberField.vue

@@ -2,6 +2,7 @@
     <div
         class="pui-field"
         :data-layout="layout === 'inline' ? 'inline' : undefined"
+        :data-readonly="readonly ? 'true' : undefined"
         :data-status="computedStatus"
     >
         <label class="pui-field__label" :for="inputId"
@@ -24,16 +25,17 @@
                 :min="min"
                 :max="max"
                 :step="step"
-                :placeholder="placeholder"
+                :placeholder="readonly ? undefined : placeholder"
                 :required="required"
                 :disabled="disabled"
+                :readonly="readonly"
                 :value="modelValue"
                 :aria-invalid="hasErrors ? 'true' : undefined"
                 :aria-describedby="describedBy"
                 @input="onInput"
                 @blur="emit('blur')"
             />
-            <div class="pui-number-field__steppers">
+            <div v-if="!readonly" class="pui-number-field__steppers">
                 <button
                     type="button"
                     class="pui-number-field__step"
@@ -91,6 +93,8 @@ const props = withDefaults(
         placeholder?: string;
         required?: boolean;
         disabled?: boolean;
+        /** Read-only: the value shows in the field chrome without steppers, stays focusable and cannot be edited. */
+        readonly?: boolean;
         hint?: string;
         errors?: string[];
         status?: 'error' | 'success';
@@ -107,6 +111,7 @@ const props = withDefaults(
         placeholder: undefined,
         required: false,
         disabled: false,
+        readonly: false,
         hint: undefined,
         errors: () => [],
         status: undefined,
@@ -149,7 +154,7 @@ function onInput(event: Event): void {
 }
 
 function handleStep(direction: 'decrement' | 'increment'): void {
-    if (props.disabled) return;
+    if (props.disabled || props.readonly) return;
     const input = inputRef.value;
     if (!input) return;
     if (direction === 'increment') {