@pienter/ui 0.7.1 → 0.9.0

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

@@ -1,143 +1,22 @@
 @layer components {
-    /* ===== pui-field (wrapper with label + hint) =====
-   *
-   * Default layout (`data-layout="stacked"` or unset): label above the
-   * control, hint and errors below — one column, vertical flow. Used by
-   * TextInput, Textarea, Select, NumberField, DateInput.
-   *
-   * Inline layout (`data-layout="inline"`): control left, label right
-   * (next to the control), hint and errors below the row spanning both
-   * columns. Used by compact form primitives (Switch, Checkbox,
-   * RadioGroup individual items) where the control is small enough to
-   * sit beside its label without the stacked label-above pattern. The
-   * control is the FIRST DOM child so a label-following-input source
-   * order can be styled via a grid template.
-   */
-
-    .pui-field {
-        display: grid;
-        align-content: start;
-        gap: var(--space-2xs);
-    }
-
-    /* Zero <fieldset>'s user-agent defaults so it can host the pui-field grid
-   * scaffold cleanly. Without this, browsers paint a 2px groove border, add
-   * default block padding, and apply `min-inline-size: min-content` (which
-   * forces the fieldset to never shrink below its widest child). RadioGroup
-   * is the first form-primitive built on <fieldset>; future grouped-control
-   * primitives (checkbox groups, date-range pickers) reuse this carve-out. */
-    .pui-field:where(fieldset) {
-        border: 0;
-        padding: 0;
-        margin: 0;
-        min-inline-size: 0;
-    }
-
-    /* <legend> default rendering ("float" anchor, automatic padding-inline)
-   * misaligns inside a grid <fieldset>; zero those so the legend behaves
-   * like a normal block grid item, allowing `.pui-field`'s row gap to govern
-   * the label-to-control spacing. */
-    .pui-field__label:where(legend) {
-        padding: 0;
-        float: none;
-    }
-
-    .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 {
-        /* Pointer affordance for clickable label paired with a small control. */
-        cursor: pointer;
-        user-select: none;
-    }
-
-    .pui-field[data-layout='inline'] .pui-field__hint {
-        /* Hint and errors span both columns so they sit below the row. */
-        grid-column: 1 / -1;
-    }
-
-    .pui-field__label {
-        margin-block: 0;
-        font-size: var(--step--1);
-        font-weight: var(--fw-bold);
-    }
-
-    .pui-field__hint {
-        font-size: var(--step--2);
-        color: var(--text-clr-muted);
-        margin: 0;
-    }
-
-    .pui-field[data-status='error'] .pui-field__hint {
-        color: var(--text-clr-danger);
-    }
-
-    .pui-field[data-status='success'] .pui-field__hint {
-        color: var(--text-clr-success);
-    }
-
-    /* ===== pui-input / pui-textarea (actual controls) ===== */
-
-    .pui-input,
-    .pui-textarea {
-        width: 100%;
-        padding: 0.65em 0.85em;
-        font: inherit;
-        background: var(--bg-clr-surface);
-        border: var(--stroke-sm) solid var(--border-clr-base);
-        border-radius: var(--radius-sm);
-        color: var(--text-clr-base);
-        transition:
-            border-color 0.12s ease,
-            box-shadow 0.12s ease;
-    }
-
-    .pui-textarea {
-        min-height: 6rem;
-        resize: vertical;
-    }
-
-    .pui-input:focus-visible,
-    .pui-textarea:focus-visible {
-        outline: none;
-        border-color: var(--border-clr-brand);
-        box-shadow: 0 0 0 3px hsl(from var(--outline-clr-base) h s l / 0.25);
-    }
-
-    .pui-input:disabled,
-    .pui-textarea:disabled {
-        background: var(--bg-clr-surface-2);
-        color: var(--text-clr-muted);
-        cursor: not-allowed;
-    }
-
-    /* Status states on parent .pui-field */
-
-    .pui-field[data-status='error'] .pui-input,
-    .pui-field[data-status='error'] .pui-textarea {
-        border-color: var(--border-clr-danger);
-    }
-
-    .pui-field[data-status='success'] .pui-input,
-    .pui-field[data-status='success'] .pui-textarea {
-        border-color: var(--border-clr-success);
-    }
-
-    /* ===== pui-inputgroup (prefix / suffix addons) ===== */
+    /* The `.pui-field` scaffold and the `.pui-input` surface live in
+     * `styles/4-components/form-field.css`; only the input group is TextInput's. */
 
     .pui-inputgroup {
         display: flex;
-        border: var(--stroke-sm) solid var(--border-clr-base);
+        border: var(--stroke-sm) solid var(--border-clr-input);
         border-radius: var(--radius-sm);
         overflow: hidden;
     }
 
     .pui-inputgroup:focus-within {
         border-color: var(--border-clr-brand);
-        box-shadow: 0 0 0 3px hsl(from var(--outline-clr-base) h s l / 0.25);
+    }
+
+    /* `overflow: hidden` would clip the input's own ring, so the group wears it. */
+    .pui-inputgroup:has(.pui-input:focus-visible) {
+        outline: var(--outline-width) solid var(--outline-clr-base);
+        outline-offset: var(--outline-offset);
     }
 
     .pui-inputgroup .pui-input {
@@ -146,7 +25,7 @@
     }
 
     .pui-inputgroup .pui-input:focus-visible {
-        box-shadow: none;
+        outline: none;
     }
 
     .pui-inputgroup__addon {

package/components/form/textarea/Textarea.vue

@@ -1,6 +1,14 @@
 <template>
     <div class="pui-field" :data-status="computedStatus">
-        <label class="pui-field__label" :for="inputId">{{ label }}</label>
+        <label class="pui-field__label" :for="inputId"
+            >{{ label
+            }}<span
+                v-if="required"
+                class="pui-field__required"
+                aria-hidden="true"
+                >*</span
+            ></label
+        >
         <textarea
             v-bind="$attrs"
             :id="inputId"
@@ -28,7 +36,7 @@
             v-if="errors.length"
             :id="errorsId"
             class="pui-field__hint"
-            role="alert"
+            role="status"
         >
             <li v-for="error in errors" :key="error">{{ error }}</li>
         </ul>

package/components/form/textarea/textarea.css

@@ -1,25 +1,9 @@
 @layer components {
-    /* The shared `.pui-textarea` rules (sizing, padding, border, focus,
-   * disabled, status-driven recolour) live alongside `.pui-input` in
-   * `components/form/text-input/text-input.css` because both controls share
-   * the form-primitive scaffold (per CONVENTIONS § Component archetypes
-   * → Form-primitive wrapper). When a fifth+ primitive ships, those
-   * shared rules will move into a dedicated `form-field.css` per the
-   * deferred-extraction note in CONVENTIONS.
-   *
-   * This file only carries Textarea-specific rules that don't fit the
-   * shared scaffold — currently just the `:autoResize` opt-in styling.
-   */
+    /* `.pui-textarea` itself is styled by `styles/4-components/form-field.css`. */
 
-    /* Auto-resize variant — opt-in via the `autoResize` prop, which sets
-   * `style="field-sizing: content"` inline on the <textarea>. The
-   * inline style is the only documented path, so the
-   * selector matches it directly. Browsers without `field-sizing`
-   * support fall back gracefully to the default fixed-rows/min-height
-   * box. */
+    /* `autoResize` sets `style="field-sizing: content"` inline; the box grows
+     * with content, so the manual resize handle is redundant. */
     .pui-textarea[style*='field-sizing'] {
-        /* Vertical resize handle is redundant when content sizing is on;
-     * the box grows with content on its own. */
         resize: none;
     }
 }

package/components/layout/app-layout/AppLayout.vue

@@ -0,0 +1,116 @@
+<script setup lang="ts">
+import { computed, useId, watch } from 'vue';
+import IconButton from '../../action/button/IconButton.vue';
+import Sidebar from '../../navigation/sidebar/Sidebar.vue';
+import type { SidebarItem } from '../../navigation/sidebar/types.js';
+
+const props = withDefaults(
+    defineProps<{
+        topItems: SidebarItem[];
+        bottomItems?: SidebarItem[];
+        activeHref?: string | null;
+        collapsed?: boolean;
+        collapsedSubmenu?: 'hidden' | 'panel';
+        navigationLabel?: string;
+        drawerLabel?: string;
+        skipLabel?: string;
+        mainId?: string;
+        navigationId?: string;
+    }>(),
+    {
+        bottomItems: () => [],
+        activeHref: null,
+        collapsed: false,
+        collapsedSubmenu: 'hidden',
+        navigationLabel: 'Main navigation',
+        drawerLabel: 'Open navigation',
+        skipLabel: 'Skip to content',
+        mainId: undefined,
+        navigationId: undefined,
+    },
+);
+
+const emit = defineEmits<{ navigate: [event: MouseEvent] }>();
+const drawerOpen = defineModel<boolean>('drawerOpen', { default: false });
+const expandedGroups = defineModel<string[]>('expandedGroups');
+
+const instanceId = useId();
+const resolvedMainId = computed(() => props.mainId ?? `${instanceId}-main`);
+const resolvedNavigationId = computed(
+    () => props.navigationId ?? `${instanceId}-navigation`,
+);
+
+function navigate(event: MouseEvent): void {
+    emit('navigate', event);
+    const target = event.target as Element | null;
+    if (target?.closest('a[data-sidebar-link]')) drawerOpen.value = false;
+}
+
+watch(
+    () => props.activeHref,
+    (next, previous) => {
+        if (next !== previous) drawerOpen.value = false;
+    },
+);
+</script>
+
+<template>
+    <div class="pui-app-layout">
+        <a class="pui-app-layout__skip-link" :href="`#${resolvedMainId}`">
+            {{ skipLabel }}
+        </a>
+        <header class="pui-app-layout__header">
+            <IconButton
+                class="pui-app-layout__drawer-toggle"
+                :label="drawerLabel"
+                name="menu"
+                variant="ghost"
+                size="sm"
+                :aria-expanded="drawerOpen ? 'true' : undefined"
+                :aria-controls="resolvedNavigationId"
+                @click="drawerOpen = true"
+            />
+            <div v-if="$slots.brand" class="pui-app-layout__brand">
+                <slot name="brand" />
+            </div>
+            <div v-if="$slots.tools" class="pui-app-layout__tools">
+                <slot name="tools" />
+            </div>
+        </header>
+        <div class="pui-app-layout__body">
+            <Sidebar
+                :id="resolvedNavigationId"
+                class="pui-app-layout__navigation"
+                :top-items="topItems"
+                :bottom-items="bottomItems"
+                :active-href="activeHref"
+                :collapsed="collapsed"
+                :collapsed-submenu="collapsedSubmenu"
+                :drawer-open="drawerOpen"
+                :expanded-groups="expandedGroups"
+                :aria-label="navigationLabel"
+                @click="navigate"
+                @update:drawer-open="drawerOpen = $event"
+                @update:expanded-groups="expandedGroups = $event"
+            >
+                <template v-if="$slots['navigation-brand']" #brand>
+                    <slot name="navigation-brand" />
+                </template>
+                <template v-if="$slots['navigation-bottom']" #bottom>
+                    <slot name="navigation-bottom" />
+                </template>
+            </Sidebar>
+            <main
+                :id="resolvedMainId"
+                class="pui-app-layout__main"
+                tabindex="-1"
+            >
+                <slot />
+            </main>
+        </div>
+    </div>
+</template>
+
+<style>
+@import './app-layout.css';
+</style>

package/components/layout/app-layout/app-layout.css

@@ -0,0 +1,115 @@
+@layer components {
+    .pui-app-layout {
+        display: grid;
+        grid-template-rows: auto minmax(0, 1fr);
+        min-block-size: 100vh;
+
+        & .pui-app-layout__skip-link {
+            position: fixed;
+            inset-block-start: var(--space-2xs);
+            inset-inline-start: var(--space-2xs);
+            z-index: var(--layer-top);
+            inline-size: var(--stroke-sm);
+            block-size: var(--stroke-sm);
+            padding: 0;
+            overflow: hidden;
+            clip-path: inset(50%);
+            white-space: nowrap;
+
+            &:focus {
+                inline-size: auto;
+                block-size: auto;
+                padding: var(--space-2xs) var(--space-s);
+                overflow: visible;
+                clip-path: none;
+                border-radius: var(--radius-pill);
+                color: var(--text-clr-inverse);
+                background: var(--bg-clr-brand);
+                font-weight: var(--fw-semibold);
+                text-decoration: none;
+                outline: var(--outline-width) solid var(--outline-clr-base);
+                outline-offset: var(--outline-offset);
+            }
+        }
+
+        & .pui-app-layout__header {
+            position: sticky;
+            inset-block-start: 0;
+            z-index: var(--layer-4);
+            display: flex;
+            align-items: center;
+            gap: var(--space-s);
+            min-block-size: var(--space-2xl);
+            padding-inline: var(--space-s);
+            background: var(--bg-clr-surface);
+            border-block-end: var(--stroke-sm) solid var(--border-clr-base);
+        }
+
+        & .pui-app-layout__brand {
+            min-inline-size: 0;
+        }
+
+        & .pui-app-layout__tools {
+            display: flex;
+            align-items: center;
+            gap: var(--space-2xs);
+            min-inline-size: 0;
+            margin-inline-start: auto;
+        }
+
+        & .pui-app-layout__body {
+            display: grid;
+            grid-template-columns: auto minmax(0, 1fr);
+            min-block-size: 0;
+        }
+
+        & .pui-app-layout__navigation {
+            min-block-size: 0;
+        }
+
+        & .pui-app-layout__main {
+            display: grid;
+            grid-template-rows: minmax(0, 1fr);
+            min-inline-size: 0;
+            padding: var(
+                --pui-app-layout-main-padding,
+                var(--space-m) var(--space-l) var(--space-xl)
+            );
+
+            &:focus:not(:focus-visible) {
+                outline: none;
+            }
+
+            &:focus-visible {
+                outline: var(--outline-width) solid var(--outline-clr-base);
+                outline-offset: calc(-1 * var(--outline-width));
+            }
+        }
+
+        & .pui-app-layout__drawer-toggle {
+            display: none;
+            flex-shrink: 0;
+        }
+
+        @media (min-width: 48em) {
+            & .pui-app-layout__navigation {
+                position: sticky;
+                inset-block-start: var(--space-2xl);
+                block-size: calc(100vh - var(--space-2xl));
+            }
+        }
+
+        @media (max-width: 47.999em) {
+            & .pui-app-layout__drawer-toggle {
+                display: inline-flex;
+            }
+
+            & .pui-app-layout__main {
+                padding: var(
+                    --pui-app-layout-main-padding-mobile,
+                    var(--space-s)
+                );
+            }
+        }
+    }
+}

package/components/layout/index/Index.vue

@@ -1,11 +1,21 @@
 <template>
-    <div class="pui-index" :data-state="loading ? 'loading' : undefined">
+    <div
+        class="pui-index"
+        :data-placement="placement"
+        :data-state="loading ? 'loading' : undefined"
+    >
         <header
             v-if="title || description || $slots.actions"
             class="pui-index__header"
         >
             <div v-if="title || description" class="pui-index__heading">
-                <h1 v-if="title" class="pui-index__title">{{ title }}</h1>
+                <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>
@@ -51,11 +61,9 @@
                 </div>
             </div>
 
-            <div
-                v-if="selectable && selected.length && $slots.selection"
-                class="pui-index__selection"
-            >
+            <div class="pui-index__selection" role="status">
                 <slot
+                    v-if="selectable && selected.length && $slots.selection"
                     name="selection"
                     :selected="selected"
                     :reload="reload"
@@ -107,6 +115,8 @@
                     :selectable="selectable"
                     :selected="selected"
                     :clickable="clickable"
+                    :label="title ? undefined : tableLabel"
+                    :labelledby="title ? titleId : undefined"
                     @sort="
                         updateCriteria({ sort: toggleSort(query.sort, $event) })
                     "
@@ -129,9 +139,11 @@
 
         <PaginationFooter v-if="showResults" class="pui-index__footer">
             <template #summary>
-                <slot name="summary" :total="total" :from="from" :to="to">
-                    {{ from }}–{{ to }} of {{ total }}
-                </slot>
+                <div class="pui-index__summary" role="status">
+                    <slot name="summary" :total="total" :from="from" :to="to">
+                        {{ from }}–{{ to }} of {{ total }}
+                    </slot>
+                </div>
             </template>
             <div class="pui-index__pagination">
                 <div v-if="pageSizes.length" class="pui-index__page-size">
@@ -173,6 +185,7 @@ import type {
     QueryOptions,
 } from '../../../utils/cms/index.js';
 import Button from '../../action/button/Button.vue';
+import { generateId } from '../../../utils/a11y/id.js';
 import { useIndex } from './useIndex.js';
 import {
     formatSort,
@@ -186,12 +199,16 @@ const props = withDefaults(
         load: ListLoader<T>;
         columns: Column[];
         queryOptions: QueryOptions;
-        /** Synchronize list parameters with the current Vue Router route. */
-        syncQuery?: boolean;
+        /** `module` is the page itself (flat, h1); `related` sits inside a record's detail page (one bordered region, h2). */
+        placement?: 'module' | 'related';
+        /** Synchronize list parameters with the current Vue Router route; a string prefixes every key (`contacts.page`). */
+        syncQuery?: boolean | string;
         /** Delay in milliseconds before committing typed search text. */
         searchDebounce?: number;
         title?: string;
         description?: string;
+        /** Accessible name for the table when there is no `title` to reference. */
+        tableLabel?: string;
         searchable?: boolean;
         searchLabel?: string;
         searchPlaceholder?: string;
@@ -207,10 +224,12 @@ const props = withDefaults(
         clickable?: boolean;
     }>(),
     {
+        placement: 'module',
         syncQuery: false,
         searchDebounce: 250,
         title: undefined,
         description: undefined,
+        tableLabel: undefined,
         searchable: true,
         searchLabel: 'Search',
         searchPlaceholder: undefined,
@@ -291,6 +310,7 @@ const {
     reset,
 } = useIndex<T>(props);
 defineExpose({ reload });
+const titleId = generateId('index-title');
 const total = computed(() => meta.value.total);
 const showResults = computed(
     () =>

package/components/layout/index/index.css

@@ -46,14 +46,6 @@
 
     .pui-index__body {
         min-inline-size: 0;
-        background: var(--bg-clr-surface);
-        border: var(--stroke-sm) solid var(--border-clr-subtle);
-        border-radius: var(--radius-md);
-    }
-
-    .pui-index__selection,
-    .pui-index__error {
-        padding: var(--space-s);
     }
 
     .pui-index__toolbar {
@@ -61,8 +53,6 @@
         flex-wrap: wrap;
         align-items: end;
         gap: var(--space-s);
-        padding: var(--space-s);
-        border-block-end: var(--stroke-sm) solid var(--border-clr-subtle);
     }
 
     .pui-index__search {
@@ -86,8 +76,6 @@
 
     .pui-index__table {
         --pui-table-cell-padding-block: var(--space-2xs);
-        border: 0;
-        border-radius: var(--radius-md) var(--radius-md) 0 0;
     }
 
     .pui-index__page-size > .pui-field {
@@ -111,4 +99,59 @@
             flex: 1;
         }
     }
+
+    /* ===== placements ===== */
+
+    /* Module: flat in the page; the table keeps DataTable's own border. The
+       selection region is always rendered, so it spaces itself only when filled. */
+    .pui-index[data-placement='module'] {
+        & .pui-index__toolbar,
+        & .pui-index__selection:not(:empty),
+        & .pui-index__error {
+            margin-block-end: var(--space-s);
+        }
+
+        & .pui-index__body > :last-child {
+            margin-block-end: 0;
+        }
+    }
+
+    /* Related: one bordered region; header, toolbar, table and footer are its bands. */
+    .pui-index[data-placement='related'] {
+        gap: 0;
+        background: var(--bg-clr-surface);
+        border: var(--stroke-sm) solid var(--border-clr-subtle);
+        border-radius: var(--radius-md);
+
+        & > .pui-index__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);
+        }
+
+        & .pui-index__selection:not(:empty),
+        & .pui-index__error {
+            padding: var(--space-s);
+        }
+
+        & .pui-index__table {
+            border: 0;
+            border-radius: 0;
+        }
+
+        & > .pui-index__footer {
+            border-block-start-color: var(--border-clr-subtle);
+            border-end-start-radius: inherit;
+            border-end-end-radius: inherit;
+        }
+    }
 }