@pienter/ui 0.11.0 → 0.13.0

package/components/form/radio-group/RadioGroup.vue

@@ -3,8 +3,10 @@
         v-bind="$attrs"
         :id="fieldId"
         class="pui-field"
+        :data-readonly="readonly ? 'true' : undefined"
         :data-status="computedStatus"
         role="radiogroup"
+        :aria-readonly="readonly ? 'true' : undefined"
         :aria-describedby="describedBy"
         :aria-invalid="hasErrors ? 'true' : undefined"
     >
@@ -31,7 +33,9 @@
                     :aria-checked="
                         modelValue === option.value ? 'true' : 'false'
                     "
-                    @change="emit('update:modelValue', option.value)"
+                    @click="onClick"
+                    @keydown="onKeydown"
+                    @change="onChange(option.value)"
                 />
                 <span class="pui-radio-group__label">{{ option.label }}</span>
             </label>
@@ -62,6 +66,8 @@ const props = withDefaults(
         options: RadioOption[];
         modelValue?: string;
         disabled?: boolean;
+        /** Read-only: `aria-readonly` on the group, the checked radio stays focusable, selection is ignored. */
+        readonly?: boolean;
         orientation?: 'vertical' | 'horizontal';
         hint?: string;
         errors?: string[];
@@ -71,6 +77,7 @@ const props = withDefaults(
         id: undefined,
         modelValue: undefined,
         disabled: false,
+        readonly: false,
         orientation: 'vertical',
         hint: undefined,
         errors: () => [],
@@ -100,6 +107,21 @@ const describedBy = computed(() => {
     if (hasErrors.value) ids.push(errorsId);
     return ids.length > 0 ? ids.join(' ') : undefined;
 });
+
+// Cancelling `click` keeps the native checked state and fires no `change`;
+// arrow keys move the selection without a click, so they are cancelled too.
+function onClick(event: MouseEvent): void {
+    if (props.readonly) event.preventDefault();
+}
+
+function onKeydown(event: KeyboardEvent): void {
+    if (props.readonly && event.key.startsWith('Arrow')) event.preventDefault();
+}
+
+function onChange(value: string): void {
+    if (props.readonly) return;
+    emit('update:modelValue', value);
+}
 </script>
 
 <style>

package/components/form/radio-group/radio-group.css

@@ -102,6 +102,15 @@
         cursor: not-allowed;
     }
 
+    .pui-field[data-readonly='true'] .pui-radio-group__item,
+    .pui-field[data-readonly='true'] .pui-radio {
+        cursor: default;
+    }
+
+    .pui-field[data-readonly='true'] .pui-radio:not(:checked) {
+        background: var(--bg-clr-surface-2);
+    }
+
     /* Status-driven recolour from the parent pui-field wrapper. */
     .pui-field[data-status='error'] .pui-radio {
         border-color: var(--border-clr-danger);

package/components/form/record-form/RecordFields.vue

@@ -23,8 +23,10 @@ const props = withDefaults(
         fields: readonly RecordFormField[];
         issues?: readonly ValidationIssue[];
         busy?: boolean;
+        /** View mode: every field renders read-only and `update` is a no-op. */
+        readonly?: boolean;
     }>(),
-    { issues: () => [], busy: false },
+    { issues: () => [], busy: false, readonly: false },
 );
 const emit = defineEmits<{
     'update:modelValue': [value: T];
@@ -44,8 +46,14 @@ function textFor(field: RecordFormField): string {
     const value = valueFor(field);
     return typeof value === 'string' ? value : '';
 }
+function altFor(field: RecordFormField): string {
+    const name = field.type === 'image' ? field.altName : undefined;
+    if (!name) return '';
+    const sibling = props.fields.find((other) => other.name === name);
+    return textFor(sibling ?? { name, label: '' });
+}
 function update(field: RecordFormField, value: unknown): void {
-    if (props.busy || field.disabled) return;
+    if (props.busy || props.readonly || field.disabled) return;
     const path = pathFor(field);
     emit('update:modelValue', updatePath(props.modelValue, path, value));
     emit('field-change', path);
@@ -66,6 +74,7 @@ function update(field: RecordFormField, value: unknown): void {
                 :update="(value: unknown) => update(field, value)"
                 :errors="errors"
                 :disabled="busy || !!field.disabled"
+                :readonly="readonly"
             >
                 <PuiTextarea
                     v-if="field.type === 'textarea'"
@@ -75,6 +84,7 @@ function update(field: RecordFormField, value: unknown): void {
                     :hint="field.hint"
                     :required="field.required"
                     :disabled="busy || field.disabled"
+                    :readonly="readonly"
                     :placeholder="field.placeholder"
                     :rows="field.rows"
                     :errors="errors"
@@ -88,6 +98,7 @@ function update(field: RecordFormField, value: unknown): void {
                     :hint="field.hint"
                     :required="field.required"
                     :disabled="busy || field.disabled"
+                    :readonly="readonly"
                     :placeholder="field.placeholder"
                     :options="field.options"
                     :errors="errors"
@@ -101,9 +112,35 @@ function update(field: RecordFormField, value: unknown): void {
                     :hint="field.hint"
                     :required="field.required"
                     :disabled="busy || field.disabled"
+                    :readonly="readonly"
                     :errors="errors"
                     @update:model-value="update(field, $event)"
                 />
+                <template v-else-if="field.type === 'image'">
+                    <div v-if="readonly" class="pui-field" data-readonly="true">
+                        <span class="pui-field__label">{{ field.label }}</span>
+                        <img
+                            v-if="textFor(field)"
+                            class="pui-record-fields__image"
+                            :src="textFor(field)"
+                            :alt="altFor(field)"
+                        />
+                        <p v-else class="pui-record-fields__empty">—</p>
+                    </div>
+                    <TextInput
+                        v-else
+                        :label="field.label"
+                        :name="JSON.stringify(pathFor(field))"
+                        :model-value="textFor(field)"
+                        type="url"
+                        :hint="field.hint"
+                        :required="field.required"
+                        :disabled="busy || field.disabled"
+                        :placeholder="field.placeholder"
+                        :errors="errors"
+                        @update:model-value="update(field, $event)"
+                    />
+                </template>
                 <TextInput
                     v-else-if="field.type !== 'custom'"
                     :label="field.label"
@@ -113,6 +150,7 @@ function update(field: RecordFormField, value: unknown): void {
                     :hint="field.hint"
                     :required="field.required"
                     :disabled="busy || field.disabled"
+                    :readonly="readonly"
                     :placeholder="field.placeholder"
                     :autocomplete="field.autocomplete"
                     :errors="errors"

package/components/form/record-form/RecordForm.vue

@@ -23,6 +23,8 @@ const props = withDefaults(
         issues?: readonly ValidationIssue[];
         errors?: string[];
         busy?: boolean;
+        /** View mode: fields render read-only, the actions row is gone and `submit` never fires. */
+        readonly?: boolean;
         submitLabel?: string;
         statusMessage?: string;
     }>(),
@@ -30,6 +32,7 @@ const props = withDefaults(
         issues: () => [],
         errors: () => [],
         busy: false,
+        readonly: false,
         submitLabel: 'Save changes',
         statusMessage: undefined,
     },
@@ -64,7 +67,8 @@ const summary = computed(() => [
 ]);
 
 function submit(): void {
-    if (!props.busy) emit('submit', cloneRecord(props.modelValue));
+    if (props.busy || props.readonly) return;
+    emit('submit', cloneRecord(props.modelValue));
 }
 </script>
 
@@ -72,6 +76,7 @@ function submit(): void {
     <Form
         class="pui-record-form"
         :busy="busy"
+        :readonly="readonly"
         :errors="summary"
         :field-errors="fieldErrors"
         :status-message="statusMessage"
@@ -84,6 +89,7 @@ function submit(): void {
                 :fields="fields"
                 :issues="issues"
                 :busy="busy"
+                :readonly="readonly"
                 @update:model-value="emit('update:modelValue', $event)"
                 @field-change="emit('field-change', $event)"
             >

package/components/form/record-form/record-form.css

@@ -12,4 +12,18 @@
         gap: var(--space-s);
         min-inline-size: 0;
     }
+
+    .pui-record-fields__image {
+        justify-self: start;
+        max-inline-size: 100%;
+        max-block-size: var(--space-3xl);
+        border: var(--stroke-sm) solid var(--border-clr-subtle);
+        border-radius: var(--radius-sm);
+        background: var(--bg-clr-surface-2);
+    }
+
+    .pui-record-fields__empty {
+        margin: 0;
+        color: var(--text-clr-muted);
+    }
 }

package/components/form/record-form/types.ts

@@ -23,6 +23,12 @@ export type RecordFormField = RecordFieldBase &
               options: { value: string; label: string }[];
               placeholder?: string;
           }
+        | {
+              type: 'image';
+              placeholder?: string;
+              /** `name` of the field in this list holding the alternative text. */
+              altName?: string;
+          }
         | { type: 'checkbox' }
         | { type: 'custom' }
     );

package/components/form/select/Select.vue

@@ -2,6 +2,7 @@
     <div
         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"
@@ -22,14 +23,12 @@
                 :required="required"
                 :disabled="disabled"
                 :value="modelValue"
+                :aria-readonly="readonly ? 'true' : undefined"
                 :aria-invalid="hasErrors ? 'true' : undefined"
                 :aria-describedby="describedBy"
-                @change="
-                    emit(
-                        'update:modelValue',
-                        ($event.target as HTMLSelectElement).value,
-                    )
-                "
+                @change="onChange"
+                @mousedown="onMousedown"
+                @keydown="onKeydown"
             >
                 <option v-if="placeholder" value="" disabled hidden>
                     {{ placeholder }}
@@ -73,6 +72,8 @@ const props = withDefaults(
         name?: string;
         required?: boolean;
         disabled?: boolean;
+        /** Read-only: `aria-readonly`, still focusable, but the list does not open and changes are ignored. */
+        readonly?: boolean;
         options: { value: string; label: string }[];
         placeholder?: string;
         hint?: string;
@@ -88,6 +89,7 @@ const props = withDefaults(
         name: undefined,
         required: false,
         disabled: false,
+        readonly: false,
         placeholder: undefined,
         hint: undefined,
         errors: () => [],
@@ -118,6 +120,30 @@ const describedBy = computed(() => {
     if (hasErrors.value) ids.push(errorsId);
     return ids.length > 0 ? ids.join(' ') : undefined;
 });
+
+function onChange(event: Event): void {
+    const target = event.target as HTMLSelectElement;
+    if (props.readonly) {
+        target.value = props.modelValue ?? '';
+        return;
+    }
+    emit('update:modelValue', target.value);
+}
+
+// A `<select>` has no `readonly`: keep it focusable but stop the picker
+// from opening and the keys that change the value without opening it.
+function onMousedown(event: MouseEvent): void {
+    if (!props.readonly) return;
+    event.preventDefault();
+    (event.currentTarget as HTMLSelectElement).focus();
+}
+
+function onKeydown(event: KeyboardEvent): void {
+    if (!props.readonly) return;
+    if (event.key === 'Tab' || event.key === 'Escape') return;
+    if (event.metaKey || event.ctrlKey) return;
+    event.preventDefault();
+}
 </script>
 
 <style>

package/components/form/select/select.css

@@ -38,6 +38,11 @@
         cursor: not-allowed;
     }
 
+    .pui-field[data-readonly='true'] .pui-select__control {
+        background: var(--bg-clr-surface-2);
+        cursor: default;
+    }
+
     .pui-select__caret {
         position: absolute;
         right: 0.85em;

package/components/form/switch/Switch.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 @@
             :checked="modelValue"
             :disabled="disabled"
             :aria-checked="modelValue ? 'true' : 'false'"
+            :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 }}</label>
         <p v-if="hint" :id="hintId" class="pui-field__hint">{{ hint }}</p>
@@ -45,6 +47,8 @@ const props = withDefaults(
         modelValue?: boolean;
         name?: string;
         disabled?: boolean;
+        /** Read-only: `aria-readonly`, still focusable, but toggling is ignored. */
+        readonly?: boolean;
         hint?: string;
         errors?: string[];
         status?: 'error' | 'success';
@@ -54,6 +58,7 @@ const props = withDefaults(
         modelValue: false,
         name: undefined,
         disabled: false,
+        readonly: false,
         hint: undefined,
         errors: () => [],
         status: undefined,
@@ -82,6 +87,17 @@ const describedBy = computed(() => {
     if (hasErrors.value) ids.push(errorsId);
     return ids.length > 0 ? ids.join(' ') : undefined;
 });
+
+// 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/switch/switch.css

@@ -47,6 +47,10 @@
         cursor: not-allowed;
     }
 
+    .pui-field[data-readonly='true'] .pui-switch {
+        cursor: default;
+    }
+
     /* Status-driven recolour from the parent pui-field wrapper. */
     .pui-field[data-status='error'] .pui-switch {
         border-color: var(--border-clr-danger);
@@ -67,4 +71,8 @@
         color: var(--text-clr-muted);
         cursor: not-allowed;
     }
+
+    .pui-field[data-readonly='true']:has(.pui-switch) .pui-field__label {
+        cursor: default;
+    }
 }

package/components/form/tags-input/TagsInput.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"
@@ -35,6 +36,7 @@
             >
                 <span class="pui-tags-input__tag-label">{{ tag }}</span>
                 <button
+                    v-if="!readonly"
                     type="button"
                     class="pui-tags-input__tag-remove"
                     :aria-label="`Remove tag ${tag}`"
@@ -52,8 +54,9 @@
                 class="pui-tags-input__entry"
                 type="text"
                 :name="name"
-                :placeholder="placeholder"
-                :disabled="disabled || maxReached"
+                :placeholder="readonly ? undefined : placeholder"
+                :disabled="disabled || (!readonly && maxReached)"
+                :readonly="readonly"
                 :aria-required="required ? 'true' : undefined"
                 :aria-invalid="hasErrors ? 'true' : undefined"
                 :aria-describedby="describedBy"
@@ -91,6 +94,8 @@ const props = withDefaults(
         /** Marks the field; set as `aria-required` on the entry input since the value is the tag list, not the typed text. */
         required?: boolean;
         disabled?: boolean;
+        /** Read-only: tags show without remove buttons and the entry is a focusable native `readonly` input. */
+        readonly?: boolean;
         hint?: string;
         errors?: string[];
         status?: 'error' | 'success';
@@ -113,6 +118,7 @@ const props = withDefaults(
         placeholder: undefined,
         required: false,
         disabled: false,
+        readonly: false,
         hint: undefined,
         errors: () => [],
         status: undefined,
@@ -163,7 +169,7 @@ function isSeparator(event: KeyboardEvent): boolean {
 
 function addTag(raw: string): boolean {
     const value = raw.trim();
-    if (!value) return false;
+    if (!value || props.readonly) return false;
     if (maxReached.value) return false;
     if (props.modelValue.includes(value)) return false;
     emit('update:modelValue', [...props.modelValue, value]);
@@ -171,7 +177,7 @@ function addTag(raw: string): boolean {
 }
 
 function removeTag(index: number): void {
-    if (props.disabled) return;
+    if (props.disabled || props.readonly) return;
     if (index < 0 || index >= props.modelValue.length) return;
     const tag = props.modelValue[index];
     const next = props.modelValue.filter((_, i) => i !== index);
@@ -182,7 +188,7 @@ function removeTag(index: number): void {
 }
 
 function onKeydown(event: KeyboardEvent): void {
-    if (props.disabled) return;
+    if (props.disabled || props.readonly) return;
     if (isSeparator(event)) {
         if (entryText.value.trim().length > 0) {
             event.preventDefault();

package/components/form/tags-input/tags-input.css

@@ -47,6 +47,11 @@
         cursor: not-allowed;
     }
 
+    .pui-field[data-readonly='true'] .pui-tags-input {
+        background: var(--bg-clr-surface-2);
+        cursor: default;
+    }
+
     /* Status states inherited from .pui-field — recolour to match
    * .pui-input / .pui-textarea when the parent carries `data-status`. */
     .pui-field[data-status='error'] .pui-tags-input {

package/components/form/text-input/TextInput.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"
@@ -23,7 +24,8 @@
             :autocomplete="autocomplete"
             :required="required"
             :disabled="disabled"
-            :placeholder="placeholder"
+            :readonly="readonly"
+            :placeholder="readonly ? undefined : placeholder"
             :aria-invalid="hasErrors ? 'true' : undefined"
             :aria-describedby="describedBy"
             @input="
@@ -62,6 +64,8 @@ const props = withDefaults(
         autocomplete?: string;
         required?: boolean;
         disabled?: boolean;
+        /** Read-only: the value shows in the field chrome, stays focusable and cannot be edited. */
+        readonly?: boolean;
         placeholder?: string;
         hint?: string;
         errors?: string[];
@@ -76,6 +80,7 @@ const props = withDefaults(
         autocomplete: undefined,
         required: false,
         disabled: false,
+        readonly: false,
         placeholder: undefined,
         hint: undefined,
         errors: () => [],

package/components/form/textarea/Textarea.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"
@@ -22,7 +23,8 @@
             :autocomplete="autocomplete"
             :required="required"
             :disabled="disabled"
-            :placeholder="placeholder"
+            :readonly="readonly"
+            :placeholder="readonly ? undefined : placeholder"
             :style="autoResize ? 'field-sizing: content' : undefined"
             :aria-invalid="hasErrors ? 'true' : undefined"
             :aria-describedby="describedBy"
@@ -63,6 +65,8 @@ const props = withDefaults(
         autocomplete?: string;
         required?: boolean;
         disabled?: boolean;
+        /** Read-only: the value shows in the field chrome, stays focusable and cannot be edited. */
+        readonly?: boolean;
         placeholder?: string;
         hint?: string;
         errors?: string[];
@@ -78,6 +82,7 @@ const props = withDefaults(
         autocomplete: undefined,
         required: false,
         disabled: false,
+        readonly: false,
         placeholder: undefined,
         hint: undefined,
         errors: () => [],

package/components/form/textarea/textarea.css

@@ -6,4 +6,11 @@
     .pui-textarea[style*='field-sizing'] {
         resize: none;
     }
+
+    /* Read-only: `rows` becomes a minimum and the box grows, so a long value
+     * is read in place rather than scrolled inside a box nobody can type in. */
+    .pui-field[data-readonly='true'] .pui-textarea {
+        field-sizing: content;
+        resize: none;
+    }
 }

package/components/layout/record-layout/Panel.vue

@@ -0,0 +1,44 @@
+<template>
+    <section class="pui-panel">
+        <header v-if="title || description" class="pui-panel__header">
+            <component
+                :is="`h${level}`"
+                v-if="title"
+                :id="titleId"
+                class="pui-panel__title"
+                >{{ title }}</component
+            >
+            <p v-if="description" class="pui-panel__description">
+                {{ description }}
+            </p>
+        </header>
+        <slot />
+    </section>
+</template>
+
+<script setup lang="ts">
+withDefaults(
+    defineProps<{
+        title?: string;
+        description?: string;
+        /** Heading level of the title: `2` under a page heading, `3` under another section. */
+        level?: 2 | 3;
+        /** `id` for the title element, so the panel or a landmark can reference it through `aria-labelledby`. */
+        titleId?: string;
+    }>(),
+    {
+        title: undefined,
+        description: undefined,
+        level: 2,
+        titleId: undefined,
+    },
+);
+
+defineSlots<{
+    default?: () => unknown;
+}>();
+</script>
+
+<style>
+@import './record-layout.css';
+</style>

package/components/layout/record-layout/RecordLayout.vue

@@ -0,0 +1,35 @@
+<template>
+    <div class="pui-record-layout">
+        <aside
+            v-if="$slots.sidebar"
+            class="pui-record-layout__sidebar"
+            :aria-labelledby="sidebarLabelledby"
+        >
+            <slot name="sidebar" />
+        </aside>
+        <div class="pui-record-layout__main">
+            <slot />
+        </div>
+    </div>
+</template>
+
+<script setup lang="ts">
+withDefaults(
+    defineProps<{
+        /** `id` of the sidebar's heading; names the `<aside>` landmark through `aria-labelledby`. */
+        sidebarLabelledby?: string;
+    }>(),
+    {
+        sidebarLabelledby: undefined,
+    },
+);
+
+defineSlots<{
+    sidebar?: () => unknown;
+    default?: () => unknown;
+}>();
+</script>
+
+<style>
+@import './record-layout.css';
+</style>