@saasicat/ui-vue 0.19.0 → 0.22.0

package/src/components/MfaPromptDialog.vue

@@ -1,8 +1,8 @@
 <template>
     <q-dialog
         :model-value="modelValue"
-        @update:model-value="emit('update:modelValue', $event)"
         persistent
+        @update:model-value="emit('update:modelValue', $event)"
     >
         <q-card class="mfa-card">
             <q-card-section class="header">
@@ -23,15 +23,21 @@
                     :error-message="error"
                 />
                 <slot name="hint">
+                    <!-- `setupHint` is markup the hosting app authored in its
+                         own source (typically a link to its MFA setup docs). It
+                         never carries request data, and an app that wants full
+                         control over the node uses the `hint` slot instead. -->
+                    <!-- eslint-disable vue/no-v-html -->
                     <div
                         v-if="setupHint"
                         class="text-caption text-grey-7 q-mt-xs"
                         v-html="setupHint"
                     />
+                    <!-- eslint-enable vue/no-v-html -->
                 </slot>
             </q-card-section>
             <q-card-actions align="right">
-                <q-btn flat :label="common.cancel" v-close-popup />
+                <q-btn v-close-popup flat :label="common.cancel" />
                 <q-btn
                     unelevated
                     color="amber-9"

package/src/components/TenantActionConfirmDialog.vue

@@ -1,8 +1,8 @@
 <template>
     <q-dialog
         :model-value="modelValue"
-        @update:model-value="emit('update:modelValue', $event)"
         persistent
+        @update:model-value="emit('update:modelValue', $event)"
     >
         <q-card class="tenant-action-confirm">
             <q-card-section class="header">
@@ -236,16 +236,16 @@ function onCancel(): void {
 }
 .tenant-action-confirm__lead {
     margin: 0 0 12px;
-    color: #475569;
+    color: var(--sa-muted-dark);
     line-height: 1.5;
 }
 .tenant-action-confirm__hint {
     margin: 0 0 8px;
-    color: #475569;
+    color: var(--sa-muted-dark);
     font-size: 13px;
 }
 .tenant-action-confirm__hint code {
-    background: #f1f5f9;
+    background: var(--sa-border-soft);
     padding: 1px 6px;
     border-radius: 4px;
     font-family: ui-monospace, SFMono-Regular, monospace;

package/src/components/VersionDiffPreview.vue

@@ -109,10 +109,10 @@ function formatValue(value: unknown): string {
 
 <style scoped>
 .sa-diff-preview__empty {
-    color: #64748b;
+    color: var(--sa-muted);
     font-style: italic;
     padding: 12px;
-    background: #f8fafc;
+    background: var(--sa-bg-surface-2);
     border-radius: 8px;
     border: 1px dashed #cbd5e1;
 }
@@ -142,9 +142,9 @@ function formatValue(value: unknown): string {
     color: #991b1b;
 }
 .sa-diff-preview__row--neutral {
-    background: #f8fafc;
-    border-color: #e2e8f0;
-    color: #475569;
+    background: var(--sa-bg-surface-2);
+    border-color: var(--sa-border);
+    color: var(--sa-muted-dark);
 }
 .sa-diff-preview__direction {
     display: flex;
@@ -156,7 +156,7 @@ function formatValue(value: unknown): string {
     letter-spacing: 0.04em;
 }
 .sa-diff-preview__field {
-    color: #0f172a;
+    color: var(--sa-heading);
     font-weight: 500;
 }
 .sa-diff-preview__values {
@@ -165,7 +165,7 @@ function formatValue(value: unknown): string {
     gap: 8px;
 }
 .sa-diff-preview__values .old {
-    color: #94a3b8;
+    color: var(--sa-muted-light);
     text-decoration: line-through;
     font-family: ui-monospace, 'SF Mono', Menlo, monospace;
     font-size: 12px;

package/src/components/admin-page/AdminBody.vue

@@ -0,0 +1,40 @@
+<template>
+    <div class="sa-page-body">
+        <div v-if="loading" class="sa-page-body__state">
+            <slot name="loading">
+                <q-spinner size="32px" />
+                <span>{{ loadingText ?? common.loadingData }}</span>
+            </slot>
+        </div>
+
+        <div v-else-if="empty" class="sa-page-body__state sa-page-body__state--empty">
+            <slot name="empty">{{ emptyText ?? common.noData }}</slot>
+        </div>
+
+        <slot v-else />
+    </div>
+</template>
+
+<script setup lang="ts">
+import { useSaMessages } from '../../vue/use-super-admin-i18n.js';
+
+// The page body: everything below the hero, plus the two states that body is
+// almost always in before it has content.
+//
+// Ten of the fifteen standard pages used to spell out their own spinner and
+// their own empty text, each with a private class for the same centred,
+// muted block. The states live here so a page describes *when* it is empty
+// rather than *what* empty looks like.
+//
+// Like AdminPage, this is deliberately not <main>: the landmark belongs to
+// AdminLayout and must appear once per document.
+defineProps<{
+    loading?: boolean;
+    /** Shown when not loading. The page decides what counts as empty. */
+    empty?: boolean;
+    loadingText?: string;
+    emptyText?: string;
+}>();
+
+const common = useSaMessages('common');
+</script>

package/src/components/admin-page/AdminFilters.vue

@@ -0,0 +1,12 @@
+<template>
+    <section class="sa-filters">
+        <div class="sa-filters__body">
+            <slot />
+        </div>
+    </section>
+</template>
+
+<script setup lang="ts">
+// Layout-only: the filter row is a flex container around whatever the page
+// puts in it. No script state — the inputs are the page's, not ours.
+</script>

package/src/components/admin-page/AdminHero.vue

@@ -0,0 +1,49 @@
+<template>
+    <header class="sa-page-head">
+        <div>
+            <slot name="before-title" />
+            <component :is="`h${level}`" class="sa-page-head__title">
+                <slot name="title">{{ title }}</slot>
+            </component>
+            <p v-if="subtitle || $slots.subtitle" class="sa-page-head__sub">
+                <slot name="subtitle">{{ subtitle }}</slot>
+            </p>
+        </div>
+        <div v-if="$slots.actions" class="sa-page-head__actions">
+            <slot name="actions" />
+        </div>
+    </header>
+</template>
+
+<script setup lang="ts">
+// The page hero: the one <h1> a page is allowed to have.
+//
+// `title` is required on purpose. It is the part of the contract that the
+// previous class-name convention could not enforce — a page can forget to add
+// `.sa-page-head`, but it cannot instantiate this component without a title,
+// because vue-tsc rejects it.
+//
+// `subtitle` covers the plain-text case; the matching slot is for the detail
+// pages whose subtitle carries markup (a status badge, a <code> slug).
+// `before-title` holds the back link on detail pages, which sits above the
+// heading rather than beside it.
+//
+// The `title` slot fills the heading with markup rather than text — a rename
+// affordance, say. The hero still owns the element and its level; the page only
+// says what goes inside it. `title` stays required either way, so the heading
+// has an accessible name even while the slot renders a control.
+//
+// `level` is what lets the same title block appear twice on a page: `1` at the
+// top, `2` for a titled group inside AdminBody. The markup is identical, so a
+// second component would only have duplicated it — and the heading level is
+// the one thing that actually differs.
+withDefaults(
+    defineProps<{
+        title: string;
+        subtitle?: string;
+        /** Heading level. `1` for the page hero, `2` for a block inside the body. */
+        level?: 1 | 2;
+    }>(),
+    { level: 1 },
+);
+</script>

package/src/components/admin-page/AdminKpi.vue

@@ -0,0 +1,84 @@
+<template>
+    <component
+        :is="action ? 'button' : 'div'"
+        :type="action ? 'button' : undefined"
+        :aria-pressed="action ? selected : undefined"
+        :class="[
+            'sa-kpi',
+            `sa-kpi--${layout}`,
+            tone !== 'neutral' && `sa-kpi--${tone}`,
+            emphasis === 'surface' && 'sa-kpi--surface',
+            action && 'sa-kpi--action',
+            action && selected && 'sa-kpi--selected',
+        ]"
+        @click="action?.()"
+    >
+        <span v-if="icon" class="sa-kpi__icon">
+            <q-icon :name="icon" size="18px" />
+        </span>
+        <span class="sa-kpi__text">
+            <span class="sa-kpi__label">{{ label }}</span>
+            <span class="sa-kpi__value">
+                <slot name="value">{{ formattedValue }}</slot>
+            </span>
+            <span v-if="sub || $slots.sub" class="sa-kpi__sub">
+                <slot name="sub">{{ sub }}</slot>
+            </span>
+        </span>
+    </component>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useSuperAdminI18n } from '../../vue/use-super-admin-i18n.js';
+
+// One statistic tile. Seven near-copies of this existed across the admin
+// pages, two of them byte identical; the differences that were real are the
+// props below.
+//
+// `action` decides everything about interactivity: with one the tile is a
+// <button> carrying `aria-pressed`, without one it is a <div>. Making that an
+// explicit prop rather than inferring it from an attached listener keeps the
+// rendered tag, the role and the focus behaviour visible at the call site.
+//
+// `layout` is the second: `stacked` leads with the number, which is what a
+// count-at-a-glance row wants; `inline` puts the icon in a tinted square beside
+// a label-first column, for rows where the icon carries the identity of the
+// figure. It is a prop rather than a page-level style so both arrangements stay
+// in this file and a page can only pick one, not invent a third.
+//
+// `emphasis` is the one genuine fork between the two families that came
+// before: the filter pills recolour only the number, while the discovery and
+// draft tiles tint the whole tile because there the colour IS the statement.
+const props = withDefaults(
+    defineProps<{
+        label: string;
+        /** Numbers are localised here so every tile formats alike. */
+        value?: string | number | null;
+        sub?: string;
+        tone?: 'neutral' | 'positive' | 'info' | 'warn' | 'danger' | 'muted' | 'purple';
+        /** `value` colours the number only, `surface` tints the whole tile. */
+        emphasis?: 'value' | 'surface';
+        icon?: string;
+        /**
+         * `stacked` leads with the number, `inline` sets the icon beside a
+         * label-first column. One arrangement per tile row, never per page.
+         */
+        layout?: 'stacked' | 'inline';
+        /** Supply to make the tile a button; omit for an informational tile. */
+        action?: () => void;
+        selected?: boolean;
+    }>(),
+    { tone: 'neutral', emphasis: 'value', selected: false, layout: 'stacked' },
+);
+
+const EMPTY = '—';
+
+const { intlLocale } = useSuperAdminI18n();
+
+const formattedValue = computed(() => {
+    const value = props.value;
+    if (value === null || value === undefined || value === '') return EMPTY;
+    return typeof value === 'number' ? value.toLocaleString(intlLocale.value) : value;
+});
+</script>

package/src/components/admin-page/AdminPage.vue

@@ -0,0 +1,16 @@
+<template>
+    <div class="sa-page">
+        <slot />
+    </div>
+</template>
+
+<script setup lang="ts">
+// Root of every SuperAdmin content page.
+//
+// It owns the page frame — canvas background, min-height and page padding —
+// which eleven pages used to declare verbatim in their own scoped styles.
+//
+// It deliberately does NOT render <main>. The landmark belongs to the layout
+// and must appear exactly once per document; AdminLayout provides it. Quasar's
+// QPage also renders <main>, which is why pages must not use QPage either.
+</script>

package/src/components/admin-page/AdminPaginator.vue

@@ -0,0 +1,195 @@
+<template>
+    <nav class="sa-paginator" :aria-label="msg.paginator.label">
+        <span class="sa-paginator__size-label">{{ msg.paginator.rowsPerPage }}</span>
+        <q-select
+            class="sa-paginator__select"
+            :model-value="rowsPerPage"
+            :options="sizeOptions"
+            :aria-label="msg.paginator.rowsPerPage"
+            dense
+            outlined
+            emit-value
+            map-options
+            @update:model-value="onSizeChange"
+        />
+
+        <button
+            class="sa-paginator__step"
+            type="button"
+            :disabled="page <= 1"
+            :aria-label="msg.paginator.previous"
+            @click="goTo(page - 1)"
+        >
+            <q-icon name="chevron_left" size="18px" />
+        </button>
+
+        <input
+            v-if="editing"
+            ref="pageInput"
+            v-model="draft"
+            class="sa-paginator__input"
+            type="number"
+            inputmode="numeric"
+            :min="1"
+            :max="pageCount"
+            :aria-label="pageInputLabel"
+            @keydown.enter="commit"
+            @keydown.escape="cancel"
+            @blur="commit"
+        />
+        <button
+            v-else
+            class="sa-paginator__page"
+            type="button"
+            :disabled="pageCount <= 1"
+            @click="startEdit"
+        >
+            {{ pageLabel }}
+        </button>
+
+        <button
+            class="sa-paginator__step"
+            type="button"
+            :disabled="page >= pageCount"
+            :aria-label="msg.paginator.next"
+            @click="goTo(page + 1)"
+        >
+            <q-icon name="chevron_right" size="18px" />
+        </button>
+    </nav>
+</template>
+
+<script setup lang="ts">
+import { computed, nextTick, onMounted, ref } from 'vue';
+import { formatMessage } from '../../client/i18n/format.js';
+import { useSaMessages } from '../../vue/use-super-admin-i18n.js';
+// Imported, not redeclared: `withDefaults` hoists its defaults out of setup(),
+// so a local const cannot be referenced there — and the sizes belong with the
+// composable that slices by them anyway.
+import { ALL_ROWS, PAGE_SIZE_OPTIONS } from '../../vue/use-pagination.js';
+
+// The pager below a list. One control for every list in the admin, so a page
+// contributes how many rows it has and which page it is on — never how paging
+// looks or where it sits.
+//
+// The page indicator doubles as its own input: clicking it turns "Page 3/9"
+// into a number field. That keeps a long list reachable without a row of page
+// buttons whose width depends on the number of pages.
+//
+// `rowsPerPage` follows Quasar's convention where 0 means "all", so a page can
+// hand this straight to a QTable's pagination object.
+
+const STORAGE_PREFIX = 'saasicat.rowsPerPage.';
+
+const props = withDefaults(
+    defineProps<{
+        page: number;
+        rowsPerPage: number;
+        /** Total rows across all pages, not the rows on this one. */
+        total: number;
+        /** Ordered page sizes; 0 renders as "all". */
+        pageSizes?: readonly number[];
+        /**
+         * Remembers the chosen size under this key. One key per list, not per
+         * page: a detail page with two tables would otherwise have them
+         * overwrite each other. Omit to keep the size for the visit only.
+         */
+        storageKey?: string;
+    }>(),
+    { pageSizes: () => [...PAGE_SIZE_OPTIONS] },
+);
+
+const emit = defineEmits<{
+    (e: 'update:page', page: number): void;
+    (e: 'update:rowsPerPage', rows: number): void;
+}>();
+
+const msg = useSaMessages('common');
+
+// A page may start on a size that is not in the list (its own default); it is
+// merged in rather than silently snapped to the nearest offered one.
+const sizeOptions = computed(() => {
+    const sizes = props.pageSizes.includes(props.rowsPerPage)
+        ? [...props.pageSizes]
+        : [...props.pageSizes, props.rowsPerPage].sort((a, b) => a - b);
+    return sizes.map((size) => ({
+        value: size,
+        label: size === ALL_ROWS ? msg.value.paginator.all : String(size),
+    }));
+});
+
+const pageCount = computed(() => {
+    if (props.rowsPerPage === ALL_ROWS) return 1;
+    return Math.max(1, Math.ceil(props.total / props.rowsPerPage));
+});
+
+const pageLabel = computed(() =>
+    formatMessage(msg.value.paginator.page, { page: props.page, pages: pageCount.value }),
+);
+const pageInputLabel = computed(() =>
+    formatMessage(msg.value.paginator.pageInput, { pages: pageCount.value }),
+);
+
+function goTo(page: number): void {
+    const clamped = Math.min(Math.max(1, page), pageCount.value);
+    if (clamped !== props.page) emit('update:page', clamped);
+}
+
+function onSizeChange(value: number): void {
+    emit('update:rowsPerPage', value);
+    // A smaller page can put the current one past the end.
+    emit('update:page', 1);
+    writeStoredSize(value);
+}
+
+// Persistence lives here rather than in each list's state, so a page that
+// paginates on the server gets it on the same terms as one that slices
+// locally. Storage can throw — Safari's private mode, a blocked third-party
+// context — and a pager that cannot remember a number is not a reason to take
+// the page down with it.
+function readStoredSize(): number | null {
+    if (!props.storageKey) return null;
+    try {
+        const raw = window.localStorage.getItem(STORAGE_PREFIX + props.storageKey);
+        const parsed = raw === null ? Number.NaN : Number.parseInt(raw, 10);
+        return Number.isFinite(parsed) && parsed >= 0 ? parsed : null;
+    } catch {
+        return null;
+    }
+}
+
+function writeStoredSize(value: number): void {
+    if (!props.storageKey) return;
+    try {
+        window.localStorage.setItem(STORAGE_PREFIX + props.storageKey, String(value));
+    } catch {
+        // Nothing to recover: the size simply lasts for this visit.
+    }
+}
+
+onMounted(() => {
+    const stored = readStoredSize();
+    if (stored !== null && stored !== props.rowsPerPage) emit('update:rowsPerPage', stored);
+});
+
+const editing = ref(false);
+const draft = ref('');
+const pageInput = ref<HTMLInputElement | null>(null);
+
+function startEdit(): void {
+    draft.value = String(props.page);
+    editing.value = true;
+    void nextTick(() => pageInput.value?.select());
+}
+
+function commit(): void {
+    if (!editing.value) return;
+    editing.value = false;
+    const parsed = Number.parseInt(draft.value, 10);
+    if (Number.isFinite(parsed)) goTo(parsed);
+}
+
+function cancel(): void {
+    editing.value = false;
+}
+</script>

package/src/components/admin-page/AdminRefreshBtn.vue

@@ -0,0 +1,39 @@
+<template>
+    <button
+        class="sa-btn sa-btn--icon"
+        type="button"
+        :disabled="loading"
+        :aria-label="label ?? common.reload"
+        @click="emit('refresh')"
+    >
+        <q-spinner v-if="loading" size="16px" />
+        <q-icon v-else name="refresh" size="16px" />
+    </button>
+</template>
+
+<script setup lang="ts">
+import { useSaMessages } from '../../vue/use-super-admin-i18n.js';
+
+// The reload control in a hero or a section head. Icon only, always the last
+// action in its row.
+//
+// Seven pages wrote it by hand and no two agreed: three showed no progress at
+// all, one disabled itself without a spinner so the page looked stuck, one had
+// no accessible name whatsoever — an icon-only button that a screen reader
+// announced as nothing — and the label came from three different message keys
+// for the same word.
+//
+// `loading` drives both the spinner and the disabled state, so a page cannot
+// have one without the other.
+defineProps<{
+    loading?: boolean;
+    /** Accessible name. Defaults to the shared "reload" string. */
+    label?: string;
+}>();
+
+const emit = defineEmits<{
+    (e: 'refresh'): void;
+}>();
+
+const common = useSaMessages('common');
+</script>

package/src/components/admin-page/AdminSection.vue

@@ -0,0 +1,53 @@
+<template>
+    <section class="sa-section" :aria-labelledby="hasTitle ? headingId : undefined">
+        <header v-if="hasTitle" class="sa-section__head">
+            <div>
+                <h2 :id="headingId" class="sa-section__title">
+                    <slot name="title">{{ title }}</slot>
+                </h2>
+                <p v-if="subtitle || $slots.subtitle" class="sa-section__sub">
+                    <slot name="subtitle">{{ subtitle }}</slot>
+                </p>
+            </div>
+            <div v-if="$slots.actions" class="sa-section__actions">
+                <slot name="actions" />
+            </div>
+        </header>
+        <div class="sa-section__body">
+            <slot />
+        </div>
+    </section>
+</template>
+
+<script setup lang="ts">
+import { computed, useId, useSlots } from 'vue';
+
+// A block of a page. Every child of AdminBody is one of these or an
+// AdminStatistics — nothing else, so the page structure can be explained once
+// instead of page by page.
+//
+// The title is optional. A filter row and a data table are blocks without a
+// natural name, and inventing one per page is exactly how a design line
+// splinters. When a title IS given, the head repeats the hero's treatment one
+// level down: same block, `h2` instead of `h1`.
+//
+// The `title` slot is for the cases where the heading carries more than text —
+// a count, a badge — so a page never has to rebuild the head to add one.
+//
+// `aria-labelledby` is why this is a component rather than a bare `<section>`:
+// an unnamed section is not a landmark, and naming one by hand needs an id
+// unique per instance. Without a title there is nothing to point at, so the
+// attribute is left off rather than pointed at an element that is not there.
+//
+// The content sits in its own wrapper so a page can lay it out — a filter row
+// as flex, a grid of cards — without the head being dragged into that layout.
+// That wrapper is the only thing a page styles; the surface is not its business.
+const props = defineProps<{
+    title?: string;
+    subtitle?: string;
+}>();
+
+const slots = useSlots();
+const headingId = useId();
+const hasTitle = computed(() => Boolean(props.title || slots.title));
+</script>

package/src/components/admin-page/AdminStatistics.vue

@@ -0,0 +1,40 @@
+<template>
+    <div class="sa-stats" :style="columns ? gridStyle : undefined" :aria-label="label">
+        <slot />
+    </div>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+
+// A row of AdminKpi tiles. One arrangement, everywhere: tiles share a track
+// width and their sub-lines land on one baseline.
+//
+// There is deliberately no layout variant. An earlier version offered a
+// content-sized "strip" alongside the grid, and the result was two different
+// looking KPI rows in the same admin — which is the kind of divergence a
+// prescribed design element exists to prevent.
+//
+// `columns` caps the track count without a media query: the tiles collapse to
+// fewer columns on their own once the minimum width no longer fits.
+const props = defineProps<{
+    /** Upper bound on tracks; fewer are used when they no longer fit. */
+    columns?: number;
+    /** Accessible name — worth setting when the tiles are interactive. */
+    label?: string;
+}>();
+
+const TILE_MIN_WIDTH = '150px';
+const GAP_PX = 10;
+
+const gridStyle = computed(() => {
+    const n = props.columns!;
+    // The gap total is computed here rather than left as `(n - 1) * 10px` in
+    // the declaration: a plain calc() sum is the conservative form, and one
+    // rejected expression would drop the whole track list back to an uncapped
+    // auto-fit — the cap would fail open, invisibly.
+    const gaps = `${(n - 1) * GAP_PX}px`;
+    const track = `max(${TILE_MIN_WIDTH}, calc((100% - ${gaps}) / ${n}))`;
+    return { gridTemplateColumns: `repeat(auto-fit, minmax(${track}, 1fr))` };
+});
+</script>