@pienter/ui 0.2.0

package/components/layout/collapsible/collapsible.css

@@ -0,0 +1,76 @@
+@layer components {
+    /* ============================================================
+   * Block — the native <details> element. The browser handles
+   * expand/collapse via the [open] attribute; we layer styling.
+   * ============================================================ */
+    .pui-collapsible {
+        border: var(--stroke-sm) solid var(--border-clr-base);
+        border-radius: var(--radius-md);
+        background: var(--bg-clr-surface);
+    }
+
+    /* ============================================================
+   * Summary — the focusable / clickable trigger. Native <summary>
+   * carries activation semantics for free; we style it to look
+   * like a clickable row with a chevron affordance.
+   * ============================================================ */
+    .pui-collapsible__trigger {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        gap: var(--space-s);
+        padding: var(--space-2xs) var(--space-s);
+        cursor: pointer;
+        font: inherit;
+        font-weight: var(--fw-semibold);
+        color: var(--text-clr-base);
+        list-style: none; /* hide default disclosure triangle (Firefox) */
+    }
+
+    /* Chrome / Safari hide the default marker with this pseudo. */
+    .pui-collapsible__trigger::-webkit-details-marker {
+        display: none;
+    }
+
+    .pui-collapsible__trigger:hover {
+        background: var(--bg-clr-surface-2);
+    }
+
+    .pui-collapsible__trigger:focus-visible {
+        outline: 3px solid var(--outline-clr-base);
+        outline-offset: 2px;
+    }
+
+    .pui-collapsible__label {
+        flex: 1 1 auto;
+        min-width: 0;
+    }
+
+    /* ============================================================
+   * Chevron — rotates to indicate open state via [open] attribute
+   * on the parent <details>. Matches Sidebar group toggle and the
+   * locked CSS-tokens-only rule.
+   * ============================================================ */
+    .pui-collapsible__chevron {
+        flex: 0 0 auto;
+        color: var(--text-clr-muted);
+        transition: transform 180ms ease;
+    }
+
+    .pui-collapsible[open]
+        > .pui-collapsible__trigger
+        > .pui-collapsible__chevron {
+        transform: rotate(180deg);
+    }
+
+    /* ============================================================
+   * Content — the disclosure panel. Border separates it visually
+   * from the summary; padding matches the trigger's inline padding
+   * for vertical alignment.
+   * ============================================================ */
+    .pui-collapsible__content {
+        padding: var(--space-s);
+        border-block-start: var(--stroke-sm) solid var(--border-clr-base);
+        color: var(--text-clr-base);
+    }
+}

package/components/layout/separator/Separator.astro

@@ -0,0 +1,31 @@
+---
+import './separator.css';
+
+interface Props {
+  orientation?: 'horizontal' | 'vertical';
+  decorative?: boolean;
+}
+
+const { orientation = 'horizontal', decorative = false, ...rest } = Astro.props;
+---
+
+{
+  decorative ? (
+    <div
+      class="pui-separator"
+      data-orientation={orientation}
+      role="none"
+      {...rest}
+    />
+  ) : orientation === 'vertical' ? (
+    <div
+      class="pui-separator"
+      data-orientation="vertical"
+      role="separator"
+      aria-orientation="vertical"
+      {...rest}
+    />
+  ) : (
+    <hr class="pui-separator" data-orientation="horizontal" {...rest} />
+  )
+}

package/components/layout/separator/Separator.vue

@@ -0,0 +1,33 @@
+<template>
+    <div
+        v-if="decorative"
+        class="pui-separator"
+        :data-orientation="orientation"
+        role="none"
+    />
+    <div
+        v-else-if="orientation === 'vertical'"
+        class="pui-separator"
+        data-orientation="vertical"
+        role="separator"
+        aria-orientation="vertical"
+    />
+    <hr v-else class="pui-separator" data-orientation="horizontal" />
+</template>
+
+<script setup lang="ts">
+withDefaults(
+    defineProps<{
+        orientation?: 'horizontal' | 'vertical';
+        decorative?: boolean;
+    }>(),
+    {
+        orientation: 'horizontal',
+        decorative: false,
+    },
+);
+</script>
+
+<style>
+@import './separator.css';
+</style>

package/components/layout/separator/separator.css

@@ -0,0 +1,27 @@
+@layer components {
+    .pui-separator {
+        /* Reset native <hr> defaults so the component fully owns sizing.
+     * Browsers paint <hr> with a 1px inset border and default block
+     * margins; both are zeroed and replaced with token-driven values. */
+        flex-shrink: 0;
+        border: 0;
+        margin: 0;
+        background-color: var(--border-clr-base);
+    }
+
+    .pui-separator[data-orientation='horizontal'] {
+        display: block;
+        width: 100%;
+        height: var(--stroke-sm);
+    }
+
+    .pui-separator[data-orientation='vertical'] {
+        display: inline-block;
+        width: var(--stroke-sm);
+        height: 100%;
+        /* Allow the consumer's flex/grid context to size the height; falls
+     * back to 1em when the parent does not constrain block-size. */
+        min-height: 1em;
+        align-self: stretch;
+    }
+}

package/components/layout/table/DataTable.vue

@@ -0,0 +1,127 @@
+<!--
+    DataTable — the data-driven wrapper over `Table` (ADR 0003), generic over the row type T.
+    Cells render from `row[column.key]` unless overridden by a `#cell:<key>="{ row, value }"` slot.
+-->
+<template>
+    <Table
+        :sort="sort"
+        :loading="loading"
+        :columns="columns"
+        :selectable="selectable"
+        :clickable="clickable"
+        :all-selected="allSelected"
+        @toggle-all="toggleAll"
+        @sort="(key) => emit('sort', key)"
+    >
+        <tr
+            v-for="row in rows"
+            :key="String(keyOf(row))"
+            class="pui-table__row"
+            :data-selected="isSelected(keyOf(row)) || undefined"
+            :data-clickable="clickable || undefined"
+            @click="onRowClick($event, row)"
+        >
+            <td v-if="selectable" class="pui-table__cell" data-select>
+                <input
+                    class="pui-table__check"
+                    type="checkbox"
+                    :checked="isSelected(keyOf(row))"
+                    aria-label="Select row"
+                    @click.stop
+                    @change="toggle(keyOf(row))"
+                />
+            </td>
+            <td
+                v-for="col in columns"
+                :key="col.key"
+                class="pui-table__cell"
+                :data-align="col.align"
+            >
+                <slot
+                    :name="`cell:${col.key}`"
+                    :row="row"
+                    :value="cellValue(row, col.key)"
+                >
+                    {{ cellValue(row, col.key) }}
+                </slot>
+            </td>
+        </tr>
+        <!-- Suppressed while loading: an empty `rows` mid-fetch means "not yet", not "nothing". -->
+        <tr v-if="!rows.length && !loading" class="pui-table__row">
+            <td class="pui-table__empty">
+                <slot name="empty">No results.</slot>
+            </td>
+        </tr>
+    </Table>
+</template>
+
+<script setup lang="ts" generic="T extends object">
+import { computed } from 'vue';
+import Table from './Table.vue';
+import type { Column, SortState } from './types.js';
+
+const props = withDefaults(
+    defineProps<{
+        /** Column layout. */
+        columns: Column[];
+        /** Row data. */
+        rows: T[];
+        /** Property on each row that uniquely identifies it. */
+        rowKey?: string;
+        /** Selected row keys — use with `v-model:selected`. */
+        selected?: (string | number)[];
+        /** Render a selection gutter (checkbox column). */
+        selectable?: boolean;
+        /** Show a pointer cursor on rows. */
+        clickable?: boolean;
+        /** Which column is sorted, and how. `rows` is passed through untouched — ordering them is the consumer's job (ADR 0005). */
+        sort?: SortState;
+        /** Frosts and disables the body while the rows are stale, and suppresses the empty state. */
+        loading?: boolean;
+    }>(),
+    {
+        rowKey: 'id',
+        selected: () => [],
+        selectable: false,
+        clickable: false,
+        sort: null,
+        loading: false,
+    },
+);
+
+const emit = defineEmits<{
+    'update:selected': [keys: (string | number)[]];
+    'row-click': [row: T];
+    /** A sortable header was activated, carrying that column's `key`. */
+    sort: [key: string];
+}>();
+
+/** Read a field off a row by key; interface row types lack an index signature, hence the cast. */
+function cellValue(row: T, key: string): unknown {
+    return (row as Record<string, unknown>)[key];
+}
+function keyOf(row: T): string | number {
+    return cellValue(row, props.rowKey) as string | number;
+}
+function isSelected(key: string | number): boolean {
+    return props.selected.includes(key);
+}
+function toggle(key: string | number) {
+    const next = isSelected(key)
+        ? props.selected.filter((k) => k !== key)
+        : [...props.selected, key];
+    emit('update:selected', next);
+}
+const allSelected = computed(
+    () =>
+        props.rows.length > 0 && props.rows.every((r) => isSelected(keyOf(r))),
+);
+function toggleAll() {
+    emit('update:selected', allSelected.value ? [] : props.rows.map(keyOf));
+}
+
+function onRowClick(event: MouseEvent, row: T) {
+    if ((event.target as HTMLElement).closest('button, a')) return;
+    emit('row-click', row);
+}
+</script>

package/components/layout/table/Table.astro

@@ -0,0 +1,116 @@
+---
+// Table (Astro) — the static primitive; the consumer authors the body in the default slot with
+// the BEM classes. Sortable headers are <a>s, not events: sorting a static table is a navigation.
+import './table.css';
+import Icon from '../../display/icon/Icon.astro';
+import Spinner from '../../feedback/spinner/Spinner.astro';
+import type { IconName } from '../../../icons/index.js';
+import {
+  formatSort,
+  toggleSort,
+  type SortDirection,
+  type SortState,
+} from '../../../utils/sort/index.js';
+import type { Column } from './types.js';
+
+interface Props {
+  columns: Column[];
+  /** Which column is sorted, and how. Rendered here; the page orders the rows itself (ADR 0005). */
+  sort?: SortState;
+  /** Query parameter the header links read and write. */
+  sortParam?: string;
+  /** Frosts and disables the body while the rows are stale, leaving the header usable. */
+  loading?: boolean;
+}
+
+const {
+  columns,
+  sort = null,
+  sortParam = 'sort',
+  loading = false,
+  ...rest
+} = Astro.props;
+const cols = columns.map((c) => c.width ?? 'auto').join(' ');
+
+/** Header glyph per sort state — the shape carries the direction. */
+const SORT_ICONS: Record<SortDirection | 'none', IconName> = {
+  asc: 'chevron-up',
+  desc: 'chevron-down',
+  none: 'chevron-up-down',
+};
+
+function sortState(key: string): SortDirection | 'none' {
+  return sort?.key === key ? sort.direction : 'none';
+}
+
+/** `aria-sort` token for the header cell; only the sorted column carries one. */
+function ariaSort(key: string): 'ascending' | 'descending' | undefined {
+  if (sort?.key !== key) return undefined;
+  return sort.direction === 'asc' ? 'ascending' : 'descending';
+}
+
+/** Where this column's header links: the asc → desc → unsorted cycle, other query params preserved. */
+function sortHref(key: string): string {
+  const url = new URL(Astro.url);
+  const value = formatSort(toggleSort(sort, key));
+  if (value) url.searchParams.set(sortParam, value);
+  else url.searchParams.delete(sortParam);
+  return url.pathname + url.search;
+}
+---
+
+<div class="pui-table-wrap" {...rest}>
+  <table
+    class="pui-table"
+    style={`--pui-table-cols: ${cols}`}
+    aria-busy={loading ? 'true' : undefined}
+  >
+    <thead class="pui-table__head">
+      <tr class="pui-table__row" data-head>
+        {
+          columns.map((col) => (
+            <th
+              scope="col"
+              class="pui-table__cell"
+              data-head
+              data-align={col.align}
+              aria-sort={col.sortable ? ariaSort(col.key) : undefined}
+            >
+              {col.sortable ? (
+                <a class="pui-table__sort" href={sortHref(col.key)}>
+                  {col.label}
+                  <span
+                    class="pui-table__sort-arrow"
+                    data-sort={sortState(col.key)}
+                  >
+                    <Icon name={SORT_ICONS[sortState(col.key)]} size="sm" />
+                  </span>
+                </a>
+              ) : (
+                col.label
+              )}
+            </th>
+          ))
+        }
+      </tr>
+    </thead>
+    {
+      /* `inert`, not CSS: `pointer-events` only stops the mouse and leaves the stale rows tabbable. */
+    }
+    <tbody class="pui-table__body" inert={loading ? true : undefined}>
+      <slot />
+      {
+        /* Must be a real <tr>/<td> inside the body, or the HTML parser hoists it out — see AUDIT.md. */
+      }
+      {
+        loading && (
+          <tr class="pui-table__loading" aria-hidden="true">
+            <td>
+              <Spinner size="xl" />
+            </td>
+          </tr>
+        )
+      }
+    </tbody>
+  </table>
+</div>

package/components/layout/table/Table.vue

@@ -0,0 +1,146 @@
+<!--
+    Table — the primitive shell (ADR 0003): header from `columns`, default slot for the body,
+    which takes `TableRow`s or plain `<tr>`s. Column layout is provided to child `TableRow`s.
+-->
+<template>
+    <div class="pui-table-wrap">
+        <table
+            class="pui-table"
+            :style="{ '--pui-table-cols': cols }"
+            :aria-busy="loading || undefined"
+        >
+            <thead class="pui-table__head">
+                <tr class="pui-table__row" data-head>
+                    <th
+                        v-if="selectable"
+                        class="pui-table__cell"
+                        data-head
+                        data-select
+                    >
+                        <input
+                            class="pui-table__check"
+                            type="checkbox"
+                            :checked="allSelected"
+                            aria-label="Select all rows"
+                            @change="emit('toggle-all')"
+                        />
+                    </th>
+                    <th
+                        v-for="col in columns"
+                        :key="col.key"
+                        class="pui-table__cell"
+                        data-head
+                        :data-align="col.align"
+                        :aria-sort="
+                            col.sortable ? ariaSort(col.key) : undefined
+                        "
+                        scope="col"
+                    >
+                        <button
+                            v-if="col.sortable"
+                            type="button"
+                            class="pui-table__sort"
+                            @click="emit('sort', col.key)"
+                        >
+                            {{ col.label }}
+                            <span
+                                class="pui-table__sort-arrow"
+                                :data-sort="state(col.key)"
+                            >
+                                <Icon
+                                    :name="SORT_ICONS[state(col.key)]"
+                                    size="sm"
+                                />
+                            </span>
+                        </button>
+                        <template v-else>{{ col.label }}</template>
+                    </th>
+                </tr>
+            </thead>
+            <!-- `inert`, not CSS: `pointer-events` only stops the mouse and leaves the stale rows tabbable. -->
+            <tbody class="pui-table__body" :inert="loading || undefined">
+                <slot />
+                <!-- Inside the body so it covers the rows and not the header; must be a real
+                     <tr>/<td> or the HTML parser hoists it out of the table — see AUDIT.md. -->
+                <tr
+                    v-if="loading"
+                    class="pui-table__loading"
+                    aria-hidden="true"
+                >
+                    <td><Spinner size="xl" /></td>
+                </tr>
+            </tbody>
+        </table>
+    </div>
+</template>
+
+<script setup lang="ts">
+import { computed, provide } from 'vue';
+import Icon from '../../display/icon/Icon.vue';
+import Spinner from '../../feedback/spinner/Spinner.vue';
+import type { IconName } from '../../../icons/index.js';
+import type { SortDirection, SortState } from '../../../utils/sort/index.js';
+import { TABLE_COLUMNS, type Column } from './types.js';
+import { gridColumns } from './useTable.js';
+
+/** Header glyph per sort state — the shape carries the direction. */
+const SORT_ICONS: Record<SortDirection | 'none', IconName> = {
+    asc: 'chevron-up',
+    desc: 'chevron-down',
+    none: 'chevron-up-down',
+};
+
+const props = withDefaults(
+    defineProps<{
+        /** Column layout. */
+        columns: Column[];
+        /** Render a leading selection gutter (checkbox column). */
+        selectable?: boolean;
+        /** Show a pointer cursor on rows (for clickable/selectable rows). */
+        clickable?: boolean;
+        /** Checked state of the header select-all checkbox. */
+        allSelected?: boolean;
+        /** Which column is sorted, and how. Rendered, never changed here; `null` is unsorted (ADR 0005). */
+        sort?: SortState;
+        /** Frosts and disables the body while the rows are stale, leaving the header usable. */
+        loading?: boolean;
+    }>(),
+    {
+        selectable: false,
+        clickable: false,
+        allSelected: false,
+        sort: null,
+        loading: false,
+    },
+);
+
+const emit = defineEmits<{
+    'toggle-all': [];
+    /** A sortable header was activated, carrying that column's `key` — the intent, not the next state (ADR 0005). */
+    sort: [key: string];
+}>();
+
+// TableRow reads layout from here instead of taking `columns` again.
+provide(TABLE_COLUMNS, {
+    columns: computed(() => props.columns),
+    selectable: computed(() => props.selectable),
+    clickable: computed(() => props.clickable),
+});
+
+const cols = computed(() => gridColumns(props.columns, props.selectable));
+
+/** Sort state of one column, driving the header glyph. */
+function state(key: string): SortDirection | 'none' {
+    return props.sort?.key === key ? props.sort.direction : 'none';
+}
+
+/** `aria-sort` token for the header cell; only the sorted column carries one. */
+function ariaSort(key: string): 'ascending' | 'descending' | undefined {
+    if (props.sort?.key !== key) return undefined;
+    return props.sort.direction === 'asc' ? 'ascending' : 'descending';
+}
+</script>
+
+<style>
+@import './table.css';
+</style>

package/components/layout/table/TableRow.vue

@@ -0,0 +1,59 @@
+<!--
+    TableRow — one row of the composed primitive. One named slot per column key (`#<key>`).
+    Reads column layout from the parent `Table` via inject. Emits `row-click`, auto-suppressed
+    when the click lands on a button or link inside the row, so action controls coexist with a
+    clickable/selectable row. Selection is externalized: the caller owns the set and passes `selected`.
+-->
+<template>
+    <tr
+        class="pui-table__row"
+        :data-selected="selected || undefined"
+        :data-clickable="ctx.clickable.value || undefined"
+        @click="onClick"
+    >
+        <td v-if="ctx.selectable.value" class="pui-table__cell" data-select>
+            <input
+                class="pui-table__check"
+                type="checkbox"
+                :checked="selected"
+                tabindex="-1"
+                aria-hidden="true"
+                @click.prevent
+            />
+        </td>
+        <td
+            v-for="col in ctx.columns.value"
+            :key="col.key"
+            class="pui-table__cell"
+            :data-align="col.align"
+        >
+            <slot :name="col.key" />
+        </td>
+    </tr>
+</template>
+
+<script setup lang="ts">
+import { inject } from 'vue';
+import { TABLE_COLUMNS } from './types.js';
+
+withDefaults(
+    defineProps<{
+        /** Selected styling. Selection state is owned by the caller. */
+        selected?: boolean;
+    }>(),
+    { selected: false },
+);
+
+const emit = defineEmits<{ 'row-click': [event: MouseEvent] }>();
+
+const ctx = inject(TABLE_COLUMNS);
+if (!ctx) {
+    throw new Error('[pui] TableRow must be used inside a Table.');
+}
+
+function onClick(event: MouseEvent) {
+    // Don't hijack clicks on interactive controls inside the row.
+    if ((event.target as HTMLElement).closest('button, a')) return;
+    emit('row-click', event);
+}
+</script>