@pienter/ui 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 ## Unreleased
 
+## 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
+
+- Index renders its title, description and actions through the new
+  `PageHeader`, so the `pui-index__header`, `pui-index__heading`,
+  `pui-index__title`, `pui-index__description` and `pui-index__actions`
+  classes are gone. They were never documented as public API; a consumer
+  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
+  header. `title` and `description` are plain strings, `level` (`1` | `2` |
+  `3`, default `1`) picks the heading element and sizes levels 2 and 3 as
+  section headings, `title-id` sets the title's `id` for `aria-labelledby`,
+  and `#actions` fills the trailing row. It renders nothing when it has no
+  title, description or actions. Index uses it at level 1 in module placement
+  and level 2 in related placement.
+
 ## 0.9.0 - 2026-09-15
 
 ### Added

package/CONVENTIONS.md

@@ -96,18 +96,18 @@ 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`                                                         |
 
 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 +272,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

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/checkbox/checkbox.css

@@ -51,6 +51,12 @@
         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);

package/components/form/combobox/Combobox.vue

@@ -1,5 +1,10 @@
 <template>
-    <div ref="fieldRef" class="pui-field" :data-status="computedStatus">
+    <div
+        ref="fieldRef"
+        class="pui-field"
+        :data-layout="layout === 'inline' ? 'inline' : undefined"
+        :data-status="computedStatus"
+    >
         <label v-if="label" class="pui-field__label" :for="inputId"
             >{{ label
             }}<span
@@ -174,6 +179,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,
@@ -191,6 +198,7 @@ const props = withDefaults(
         emptyMessage: 'No results',
         placement: 'bottom-start',
         offset: 4,
+        layout: 'stacked',
     },
 );
 

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

@@ -1,5 +1,9 @@
 <template>
-    <div class="pui-field" :data-status="computedStatus">
+    <div
+        class="pui-field"
+        :data-layout="layout === 'inline' ? 'inline' : undefined"
+        :data-status="computedStatus"
+    >
         <label class="pui-field__label" :for="inputId"
             >{{ label
             }}<span
@@ -83,6 +87,8 @@ const props = withDefaults(
         hint?: string;
         errors?: string[];
         status?: 'error' | 'success';
+        /** `inline` puts the label beside the control; hint and errors wrap below. */
+        layout?: 'stacked' | 'inline';
     }>(),
     {
         id: undefined,
@@ -96,6 +102,7 @@ const props = withDefaults(
         hint: undefined,
         errors: () => [],
         status: undefined,
+        layout: 'stacked',
     },
 );
 

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

@@ -1,5 +1,9 @@
 <template>
-    <div class="pui-field" :data-status="computedStatus">
+    <div
+        class="pui-field"
+        :data-layout="layout === 'inline' ? 'inline' : undefined"
+        :data-status="computedStatus"
+    >
         <label class="pui-field__label" :for="inputId"
             >{{ label
             }}<span
@@ -90,6 +94,8 @@ const props = withDefaults(
         hint?: string;
         errors?: string[];
         status?: 'error' | 'success';
+        /** `inline` puts the label beside the control; hint and errors wrap below. */
+        layout?: 'stacked' | 'inline';
     }>(),
     {
         id: undefined,
@@ -104,6 +110,7 @@ const props = withDefaults(
         hint: undefined,
         errors: () => [],
         status: undefined,
+        layout: 'stacked',
     },
 );
 

package/components/form/select/Select.vue

@@ -1,5 +1,9 @@
 <template>
-    <div class="pui-field" :data-status="computedStatus">
+    <div
+        class="pui-field"
+        :data-layout="layout === 'inline' ? 'inline' : undefined"
+        :data-status="computedStatus"
+    >
         <label v-if="label" class="pui-field__label" :for="inputId"
             >{{ label
             }}<span
@@ -74,6 +78,8 @@ const props = withDefaults(
         hint?: string;
         errors?: string[];
         status?: 'error' | 'success';
+        /** `inline` puts the label beside the control; hint and errors wrap below. */
+        layout?: 'stacked' | 'inline';
     }>(),
     {
         id: undefined,
@@ -86,6 +92,7 @@ const props = withDefaults(
         hint: undefined,
         errors: () => [],
         status: undefined,
+        layout: 'stacked',
     },
 );
 

package/components/form/switch/switch.css

@@ -56,6 +56,12 @@
         background: var(--bg-clr-success, var(--bg-clr-brand));
     }
 
+    /* The label is the click target for the switch, so it reads as one. */
+    .pui-field:has(.pui-switch) .pui-field__label {
+        cursor: pointer;
+        user-select: none;
+    }
+
     /* Disable the cursor + label colour when the input is disabled. */
     .pui-field:has(.pui-switch:disabled) .pui-field__label {
         color: var(--text-clr-muted);

package/components/form/tags-input/TagsInput.vue

@@ -1,5 +1,9 @@
 <template>
-    <div class="pui-field" :data-status="computedStatus">
+    <div
+        class="pui-field"
+        :data-layout="layout === 'inline' ? 'inline' : undefined"
+        :data-status="computedStatus"
+    >
         <label class="pui-field__label" :for="inputId"
             >{{ label
             }}<span
@@ -100,6 +104,8 @@ const props = withDefaults(
          * `[',', 'Enter']`.
          */
         separators?: string[];
+        /** `inline` puts the label beside the control; hint and errors wrap below. */
+        layout?: 'stacked' | 'inline';
     }>(),
     {
         id: undefined,
@@ -112,6 +118,7 @@ const props = withDefaults(
         status: undefined,
         maxTags: undefined,
         separators: () => [',', 'Enter'],
+        layout: 'stacked',
     },
 );
 

package/components/form/text-input/TextInput.vue

@@ -1,5 +1,9 @@
 <template>
-    <div class="pui-field" :data-status="computedStatus">
+    <div
+        class="pui-field"
+        :data-layout="layout === 'inline' ? 'inline' : undefined"
+        :data-status="computedStatus"
+    >
         <label class="pui-field__label" :for="inputId"
             >{{ label
             }}<span
@@ -62,6 +66,8 @@ const props = withDefaults(
         hint?: string;
         errors?: string[];
         status?: 'error' | 'success';
+        /** `inline` puts the label beside the control; hint and errors wrap below. */
+        layout?: 'stacked' | 'inline';
     }>(),
     {
         id: undefined,
@@ -74,6 +80,7 @@ const props = withDefaults(
         hint: undefined,
         errors: () => [],
         status: undefined,
+        layout: 'stacked',
     },
 );
 

package/components/form/textarea/Textarea.vue

@@ -1,5 +1,9 @@
 <template>
-    <div class="pui-field" :data-status="computedStatus">
+    <div
+        class="pui-field"
+        :data-layout="layout === 'inline' ? 'inline' : undefined"
+        :data-status="computedStatus"
+    >
         <label class="pui-field__label" :for="inputId"
             >{{ label
             }}<span
@@ -64,6 +68,8 @@ const props = withDefaults(
         errors?: string[];
         status?: 'error' | 'success';
         autoResize?: boolean;
+        /** `inline` puts the label beside the control; hint and errors wrap below. */
+        layout?: 'stacked' | 'inline';
     }>(),
     {
         id: undefined,
@@ -77,6 +83,7 @@ const props = withDefaults(
         errors: () => [],
         status: undefined,
         autoResize: false,
+        layout: 'stacked',
     },
 );
 

package/components/layout/index/Index.vue

@@ -4,26 +4,16 @@
         :data-placement="placement"
         :data-state="loading ? 'loading' : undefined"
     >
-        <header
-            v-if="title || description || $slots.actions"
-            class="pui-index__header"
+        <PageHeader
+            :title="title"
+            :description="description"
+            :level="placement === 'related' ? 2 : 1"
+            :title-id="titleId"
         >
-            <div v-if="title || description" class="pui-index__heading">
-                <component
-                    :is="placement === 'related' ? 'h2' : 'h1'"
-                    v-if="title"
-                    :id="titleId"
-                    class="pui-index__title"
-                    >{{ title }}</component
-                >
-                <p v-if="description" class="pui-index__description">
-                    {{ description }}
-                </p>
-            </div>
-            <div v-if="$slots.actions" class="pui-index__actions">
+            <template v-if="$slots.actions" #actions>
                 <slot name="actions" :reload="reload" :loading="loading" />
-            </div>
-        </header>
+            </template>
+        </PageHeader>
 
         <div class="pui-index__body">
             <div
@@ -150,6 +140,7 @@
                     <Select
                         :label="pageSizeLabel"
                         :aria-label="pageSizeLabel"
+                        layout="inline"
                         :model-value="String(query.page_size)"
                         :options="pageSizeOptions"
                         @update:model-value="
@@ -172,6 +163,7 @@
 <script setup lang="ts" generic="T extends object">
 import { computed, watch } from 'vue';
 import DataTable from '../table/DataTable.vue';
+import PageHeader from '../page-header/PageHeader.vue';
 import type { Column } from '../table/types.js';
 import TextInput from '../../form/text-input/TextInput.vue';
 import Select from '../../form/select/Select.vue';

package/components/layout/index/index.css

@@ -6,37 +6,6 @@
         color: var(--text-clr-base);
     }
 
-    .pui-index__header {
-        display: grid;
-        grid-template-columns: minmax(0, 1fr) auto;
-        align-items: center;
-        justify-content: space-between;
-        gap: var(--space-s);
-        padding-block-end: var(--space-s);
-        border-block-end: var(--stroke-sm) solid var(--border-clr-subtle);
-    }
-
-    .pui-index__heading {
-        display: grid;
-        gap: var(--space-3xs);
-        min-inline-size: 0;
-    }
-
-    .pui-index__title {
-        margin: 0;
-        font-family: var(--ff-display);
-        font-size: var(--step-2);
-        font-weight: var(--fw-display);
-        letter-spacing: var(--ls-display);
-    }
-
-    .pui-index__description {
-        margin: 0;
-        font-size: var(--step--1);
-        color: var(--text-clr-muted);
-    }
-
-    .pui-index__actions,
     .pui-index__selection {
         display: flex;
         flex-wrap: wrap;
@@ -78,14 +47,15 @@
         --pui-table-cell-padding-block: var(--space-2xs);
     }
 
-    .pui-index__page-size > .pui-field {
-        display: flex;
-        align-items: center;
-        gap: var(--space-xs);
+    /* Two-line primary cell: title (usually a link) over a muted subline. */
+    .pui-index__primary {
+        display: grid;
+        gap: var(--space-3xs);
+    }
 
-        & > .pui-field__label {
-            white-space: nowrap;
-        }
+    .pui-index__subline {
+        color: var(--text-clr-muted);
+        font-size: var(--step--2);
     }
 
     .pui-index__pagination {
@@ -123,16 +93,10 @@
         border: var(--stroke-sm) solid var(--border-clr-subtle);
         border-radius: var(--radius-md);
 
-        & > .pui-index__header {
+        & > .pui-page-header {
             padding: var(--space-s);
         }
 
-        & .pui-index__title {
-            font-size: var(--step-1);
-            font-weight: var(--fw-semibold);
-            letter-spacing: normal;
-        }
-
         & .pui-index__toolbar {
             padding: var(--space-s);
             border-block-end: var(--stroke-sm) solid var(--border-clr-subtle);

package/components/layout/page-header/PageHeader.vue

@@ -0,0 +1,49 @@
+<template>
+    <header
+        v-if="title || description || $slots.actions"
+        class="pui-page-header"
+    >
+        <div v-if="title || description" class="pui-page-header__heading">
+            <component
+                :is="`h${level}`"
+                v-if="title"
+                :id="titleId"
+                class="pui-page-header__title"
+                >{{ title }}</component
+            >
+            <p v-if="description" class="pui-page-header__description">
+                {{ description }}
+            </p>
+        </div>
+        <div v-if="$slots.actions" class="pui-page-header__actions">
+            <slot name="actions" />
+        </div>
+    </header>
+</template>
+
+<script setup lang="ts">
+withDefaults(
+    defineProps<{
+        title?: string;
+        description?: string;
+        /** Heading level of the title: `1` for a page, `2` or `3` for a band inside one. */
+        level?: 1 | 2 | 3;
+        /** `id` for the title element, so a region can reference it through `aria-labelledby`. */
+        titleId?: string;
+    }>(),
+    {
+        title: undefined,
+        description: undefined,
+        level: 1,
+        titleId: undefined,
+    },
+);
+
+defineSlots<{
+    actions?: () => unknown;
+}>();
+</script>
+
+<style>
+@import './page-header.css';
+</style>

package/components/layout/page-header/page-header.css

@@ -0,0 +1,44 @@
+@layer components {
+    .pui-page-header {
+        display: grid;
+        grid-template-columns: minmax(0, 1fr) auto;
+        align-items: center;
+        justify-content: space-between;
+        gap: var(--space-s);
+        padding-block-end: var(--space-s);
+        border-block-end: var(--stroke-sm) solid var(--border-clr-subtle);
+    }
+
+    .pui-page-header__heading {
+        display: grid;
+        gap: var(--space-3xs);
+        min-inline-size: 0;
+    }
+
+    .pui-page-header__title {
+        margin: 0;
+        font-family: var(--ff-display);
+        font-size: var(--step-2);
+        font-weight: var(--fw-display);
+        letter-spacing: var(--ls-display);
+
+        &:is(h2, h3) {
+            font-size: var(--step-1);
+            font-weight: var(--fw-semibold);
+            letter-spacing: normal;
+        }
+    }
+
+    .pui-page-header__description {
+        margin: 0;
+        font-size: var(--step--1);
+        color: var(--text-clr-muted);
+    }
+
+    .pui-page-header__actions {
+        display: flex;
+        flex-wrap: wrap;
+        align-items: center;
+        gap: var(--space-xs);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pienter/ui",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Shared Pienter UI components, styles, icons, and browser utilities.",
   "type": "module",
   "license": "MIT",
@@ -63,6 +63,7 @@
     "./components/Card.vue": "./components/layout/card/Card.vue",
     "./components/Collapsible.vue": "./components/layout/collapsible/Collapsible.vue",
     "./components/AppLayout.vue": "./components/layout/app-layout/AppLayout.vue",
+    "./components/PageHeader.vue": "./components/layout/page-header/PageHeader.vue",
     "./components/Separator.vue": "./components/layout/separator/Separator.vue",
     "./components/Table.vue": "./components/layout/table/Table.vue",
     "./components/TableRow.vue": "./components/layout/table/TableRow.vue",

package/styles/2-base/base.css

@@ -33,10 +33,15 @@
 
     a {
         color: var(--text-clr-brand);
-        text-underline-offset: 0.14em;
+        text-underline-offset: var(--space-3xs);
     }
 
     a:hover {
         color: var(--text-clr-brand-hover);
     }
+
+    a:focus-visible {
+        outline: var(--outline-width) solid var(--outline-clr-base);
+        outline-offset: var(--outline-offset);
+    }
 }

package/styles/4-components/form-field.css

@@ -27,19 +27,15 @@
         float: none;
     }
 
-    /* `data-layout="inline"`: control first in DOM order, label beside it,
-     * hint and errors below spanning both columns. */
+    /* `data-layout="inline"`: label and control share a row in DOM order
+     * (control first for Checkbox/Switch, label first elsewhere); hint and
+     * errors drop below spanning both columns. */
     .pui-field[data-layout='inline'] {
         grid-template-columns: max-content 1fr;
         column-gap: var(--space-xs);
         align-items: center;
     }
 
-    .pui-field[data-layout='inline'] .pui-field__label {
-        cursor: pointer;
-        user-select: none;
-    }
-
     .pui-field[data-layout='inline'] .pui-field__hint {
         grid-column: 1 / -1;
     }