@getdom/studio 0.1.1 → 0.2.1

package/src/pages/charts/area-chart/DomAreaChart.vue

@@ -0,0 +1,27 @@
+<script setup>
+import { chartProps } from '../_shared/chartProps.js';
+import XYChart from '../_shared/XYChart.vue';
+
+defineOptions({
+	__doc: {
+		name: 'Area chart',
+		tag: '<DomAreaChart>',
+		description: 'Show volume over time as overlapping or stacked areas.',
+		icon: 'M4 4v16h16M7 14l4-5 4 3 5-7',
+		events: [
+			{ name: 'select', payload: '{ row, index }', description: 'Original application record selected by click or Enter.' },
+			{ name: 'retry', description: 'Requests another attempt to load application data.' },
+		],
+		keyboard: [{ keys: 'Arrow keys / Home / End', action: 'Inspect data points.' }, { keys: 'Enter', action: 'Select the inspected record.' }],
+	},
+});
+const props = defineProps({
+	...chartProps,
+	stacked: { type: Boolean, default: false, _edit: { description: 'Stack visible series on a shared baseline.' } },
+});
+defineEmits(['select', 'retry']);
+</script>
+
+<template>
+	<XYChart v-bind="props" kind="area" @select="$emit('select', $event)" @retry="$emit('retry')" />
+</template>

package/src/pages/charts/bar-chart/DomBarChart.vue

@@ -0,0 +1,29 @@
+<script setup>
+import { chartProps } from '../_shared/chartProps.js';
+import XYChart from '../_shared/XYChart.vue';
+
+defineOptions({
+	__doc: {
+		name: 'Bar chart',
+		tag: '<DomBarChart>',
+		description: 'Compare categories with vertical or horizontal bars, grouped series, and percentage stacks.',
+		icon: 'M4 4v16h16M7 14l4-5 4 3 5-7',
+		events: [
+			{ name: 'select', payload: '{ row, index }', description: 'Original application record selected by click or Enter.' },
+			{ name: 'retry', description: 'Requests another attempt to load application data.' },
+		],
+		keyboard: [{ keys: 'Arrow keys / Home / End', action: 'Inspect data points.' }, { keys: 'Enter', action: 'Select the inspected record.' }],
+	},
+});
+const props = defineProps({
+	...chartProps,
+	stacked: { type: Boolean, default: false, _edit: { description: 'Stack series within each category.' } },
+	percentage: { type: Boolean, default: false, _edit: { description: 'Normalize non-negative visible series to a 100% stack.' } },
+	horizontal: { type: Boolean, default: false, _edit: { description: 'Place category labels down the left side.' } },
+});
+defineEmits(['select', 'retry']);
+</script>
+
+<template>
+	<XYChart v-bind="props" kind="bar" @select="$emit('select', $event)" @retry="$emit('retry')" />
+</template>

package/src/pages/charts/date-range-picker/DomDateRangePicker.vue

@@ -0,0 +1,104 @@
+<script setup>
+import { computed, onMounted, ref, watch } from 'vue';
+import DomPopover from '../../components/popover/DomPopover.vue';
+import DomButton from '../../components/button/DomButton.vue';
+import DomDatePicker from '../../forms/date-picker/DomDatePicker.vue';
+import DomNativeSelect from '../../forms/native-select/DomNativeSelect.vue';
+import { comparisonRange, dateRangePresets, rangeError } from './dateRange.js';
+
+defineOptions({
+	__doc: {
+		name: 'Date range picker', tag: '<DomDateRangePicker>',
+		description: 'Inclusive reporting dates with useful presets, explicit Apply and Cancel actions, and optional period comparisons.',
+		icon: 'M5 4v3M19 4v3M4 9h16M4 6h16v14H4zM8 13h8M8 16h5',
+		events: [
+			{ name: 'update:modelValue', payload: '{ start, end }', description: 'Committed inclusive YYYY-MM-DD dates.' },
+			{ name: 'update:comparison', payload: 'string', description: 'Committed comparison mode.' },
+			{ name: 'change', payload: '{ range, comparison, comparisonRange }', description: 'Atomic reporting query change; fetching remains application-owned.' },
+		],
+	},
+});
+const props = defineProps({
+	modelValue: { type: Object, default: () => ({ start: '', end: '' }), _edit: { description: 'Controlled inclusive { start, end } dates in YYYY-MM-DD format.' } },
+	comparison: { type: String, default: 'none', _edit: { options: ['none', 'previous-period', 'previous-year'] } },
+	showComparison: { type: Boolean, default: true },
+	label: { type: String, default: 'Reporting period' },
+	disabled: { type: Boolean, default: false },
+	min: { type: String, default: '' },
+	max: { type: String, default: '' },
+	anchorDate: { type: String, default: '', _edit: { description: 'Preset reference date. Defaults to browser-local today after mount; supply a reporting-timezone date for deterministic presets.' } },
+	locale: { type: String, default: 'en-GB' },
+});
+const draft = ref({ ...props.modelValue });
+const draftComparison = ref(props.comparison);
+const invalidStart = ref(false);
+const invalidEnd = ref(false);
+const draftVersion = ref(0);
+const today = ref('');
+const presets = computed(() => dateRangePresets(props.anchorDate || today.value));
+const error = computed(() => invalidStart.value || invalidEnd.value ? 'Correct the invalid date before applying this range.' : rangeError(draft.value, props.min, props.max));
+const compared = computed(() => comparisonRange(draft.value, draftComparison.value));
+const triggerLabel = computed(() => rangeError(props.modelValue) ? props.label : `${formatDate(props.modelValue.start)} – ${formatDate(props.modelValue.end)}`);
+const emit = defineEmits(['update:modelValue', 'update:comparison', 'change']);
+const comparisonOptions = [{ value: 'none', label: 'No comparison' }, { value: 'previous-period', label: 'Previous period' }, { value: 'previous-year', label: 'Previous year' }];
+onMounted(setToday);
+watch(() => [props.modelValue, props.comparison], resetDraft, { deep: true });
+
+/** @returns {void} Establishes local today only after hydration. */
+function setToday() {
+	const date = new Date();
+	today.value = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+}
+/** @returns {void} Restores controlled values when reopening or cancelling. */
+function resetDraft() {
+	draft.value = { ...props.modelValue };
+	draftComparison.value = props.comparison;
+	invalidStart.value = false;
+	invalidEnd.value = false;
+	draftVersion.value += 1;
+}
+/** @param {string} value Canonical date. @returns {string} Localized date label. */
+function formatDate(value) { return new Intl.DateTimeFormat(props.locale, { day: 'numeric', month: 'short', year: 'numeric', timeZone: 'UTC' }).format(new Date(`${value}T00:00:00Z`)); }
+/** @param {object} preset Inclusive dates. @returns {void} Updates only the editable draft. */
+function choosePreset(preset) {
+	draft.value = { start: preset.start, end: preset.end };
+	invalidStart.value = false;
+	invalidEnd.value = false;
+	draftVersion.value += 1;
+}
+/** @param {Function} close Popover close helper. @returns {void} Commits the complete reporting choice. */
+function apply(close) {
+	if (props.disabled || error.value) return;
+	const range = { ...draft.value };
+	const comparison = props.showComparison ? draftComparison.value : 'none';
+	emit('update:modelValue', range);
+	emit('update:comparison', comparison);
+	emit('change', { range, comparison, comparisonRange: comparisonRange(range, comparison) });
+	close();
+}
+</script>
+
+<template>
+	<DomPopover width="w-[min(26rem,calc(100vw-2rem))]" :arrow="false" padding="p-4" @open="resetDraft">
+		<template #trigger><DomButton variant="secondary" :disabled="disabled" :aria-label="`${label}: ${triggerLabel}`">{{ triggerLabel }}</DomButton></template>
+		<template #default="{ close }">
+			<div class="space-y-4">
+				<p class="font-semibold">{{ label }}</p>
+				<div class="grid grid-cols-2 gap-2">
+					<DomButton v-for="preset in presets" :key="preset.label" size="sm" variant="secondary" :disabled="!!rangeError(preset, min, max)" @click="choosePreset(preset)">{{ preset.label }}</DomButton>
+				</div>
+				<div class="grid gap-3 sm:grid-cols-2">
+					<DomDatePicker :key="`start-${draftVersion}`" v-model="draft.start" label="Start date" :calendar-props="{ min, max }" :register-field="false" @invalid-date="invalidStart = true" @update:model-value="invalidStart = false" />
+					<DomDatePicker :key="`end-${draftVersion}`" v-model="draft.end" label="End date" :calendar-props="{ min, max }" :register-field="false" @invalid-date="invalidEnd = true" @update:model-value="invalidEnd = false" />
+				</div>
+				<DomNativeSelect v-if="showComparison" v-model="draftComparison" label="Compare with" :options="comparisonOptions" :register-field="false" />
+				<p v-if="compared && showComparison" class="text-xs leading-5 text-muted-fg">Comparison: {{ formatDate(compared.start) }} – {{ formatDate(compared.end) }}</p>
+				<p v-if="error" role="status" class="text-xs text-destructive">{{ error }}</p>
+				<div class="flex justify-end gap-2 border-t border-border pt-3">
+					<DomButton size="sm" variant="ghost" @click="resetDraft(); close()">Cancel</DomButton>
+					<DomButton size="sm" :disabled="!!error || disabled" @click="apply(close)">Apply</DomButton>
+				</div>
+			</div>
+		</template>
+	</DomPopover>
+</template>

package/src/pages/charts/date-range-picker/dateRange.js

@@ -0,0 +1,69 @@
+const DAY = 86_400_000;
+
+/** @param {string} value Canonical date. @returns {number|null} UTC timestamp for a real calendar date. */
+export function dateStamp(value) {
+	if (!/^\d{4}-\d{2}-\d{2}$/.test(value || '')) return null;
+	const stamp = Date.parse(`${value}T00:00:00Z`);
+	return Number.isFinite(stamp) && new Date(stamp).toISOString().slice(0, 10) === value ? stamp : null;
+}
+
+/** @param {number} stamp UTC timestamp. @returns {string} Canonical date without a timezone conversion. */
+function dateString(stamp) { return new Date(stamp).toISOString().slice(0, 10); }
+
+/**
+ * Validates inclusive date ranges against optional application bounds.
+ * @param {{start?: string, end?: string}} range Proposed range.
+ * @param {string} [min] Earliest available date.
+ * @param {string} [max] Latest available date.
+ * @returns {string} Validation message, or an empty string.
+ */
+export function rangeError(range, min = '', max = '') {
+	if (dateStamp(range?.start) === null || dateStamp(range?.end) === null) return 'Choose a valid start and end date.';
+	if (range.start > range.end) return 'End date must be on or after start date.';
+	if (min && range.start < min) return `Choose dates on or after ${min}.`;
+	if (max && range.end > max) return `Choose dates on or before ${max}.`;
+	return '';
+}
+
+/**
+ * Calculates reporting presets using calendar arithmetic independent of DST.
+ * @param {string} anchor Canonical date treated as today.
+ * @returns {Array<object>} Inclusive preset ranges.
+ */
+export function dateRangePresets(anchor) {
+	const end = dateStamp(anchor);
+	if (end === null) return [];
+	const date = new Date(end);
+	const monthStart = Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), 1);
+	return [
+		{ label: 'Last 7 days', start: dateString(end - 6 * DAY), end: anchor },
+		{ label: 'Last 30 days', start: dateString(end - 29 * DAY), end: anchor },
+		{ label: 'This month', start: dateString(monthStart), end: anchor },
+		{ label: 'Last month', start: dateString(Date.UTC(date.getUTCFullYear(), date.getUTCMonth() - 1, 1)), end: dateString(monthStart - DAY) },
+	];
+}
+
+/**
+ * Derives an equal-length previous period or the matching dates a year earlier.
+ * Leap-day comparisons clamp to the final valid day of the earlier February.
+ * @param {{start: string, end: string}} range Inclusive reporting range.
+ * @param {'none'|'previous-period'|'previous-year'} comparison Comparison mode.
+ * @returns {{start: string, end: string}|null} Derived comparison dates.
+ */
+export function comparisonRange(range, comparison) {
+	if (rangeError(range) || comparison === 'none') return null;
+	const start = dateStamp(range.start);
+	const end = dateStamp(range.end);
+	if (comparison === 'previous-period') return { start: dateString(start - (end - start + DAY)), end: dateString(start - DAY) };
+	if (comparison !== 'previous-year') return null;
+	return { start: previousYear(start), end: previousYear(end) };
+}
+
+/** @param {number} stamp Valid UTC date. @returns {string} Date in the preceding year, clamped at month end. */
+function previousYear(stamp) {
+	const date = new Date(stamp);
+	const year = date.getUTCFullYear() - 1;
+	const month = date.getUTCMonth();
+	const lastDay = new Date(Date.UTC(year, month + 1, 0)).getUTCDate();
+	return dateString(Date.UTC(year, month, Math.min(date.getUTCDate(), lastDay)));
+}

package/src/pages/charts/donut-chart/DomDonutChart.vue

@@ -0,0 +1,117 @@
+<script setup>
+import { computed, onBeforeUnmount, onMounted, ref, shallowRef, watch } from 'vue';
+import { chartProps } from '../_shared/chartProps.js';
+import { chartColor, chartNumber, formatChartValue } from '../_shared/chartUtils.js';
+import ChartContainer from '../_shared/ChartContainer.vue';
+import ChartLegend from '../_shared/ChartLegend.vue';
+import ChartTooltip from '../_shared/ChartTooltip.vue';
+
+defineOptions({
+	__doc: {
+		name: 'Donut chart', tag: '<DomDonutChart>',
+		description: 'Compare non-negative category shares with a centre total, selectable legend, and accessible data table.',
+		icon: 'M12 3v9h9A9 9 0 1 1 12 3ZM15 3.5A9 9 0 0 1 20.5 9H15z',
+		slots: [{ name: 'center', payload: '{ total, formattedTotal }', description: 'Replaces the centre labels with custom content, such as an audit score out of 100. Keep content small enough to fit inside the ring.' }],
+		events: [{ name: 'select', payload: '{ row, index }', description: 'Original record for the selected category.' }, { name: 'retry', description: 'Requests application data recovery.' }],
+	},
+});
+const props = defineProps({
+	rows: chartProps.rows,
+	title: chartProps.title,
+	description: chartProps.description,
+	height: chartProps.height,
+	format: chartProps.format,
+	currency: chartProps.currency,
+	locale: chartProps.locale,
+	valueFormatter: chartProps.valueFormatter,
+	loading: chartProps.loading,
+	error: chartProps.error,
+	emptyLabel: chartProps.emptyLabel,
+	legend: chartProps.legend,
+	showTable: chartProps.showTable,
+	labelKey: { type: String, default: 'label', _edit: { description: 'Unique category label field; supply one row per category.' } },
+	valueKey: { type: String, default: 'value', _edit: { description: 'Non-negative measurement field.' } },
+	colorKey: { type: String, default: 'color', _edit: { description: 'Optional field containing a semantic token or CSS colour.' } },
+	totalLabel: { type: String, default: 'Total', _edit: { description: 'Caption beneath the sum of visible categories.' } },
+	arcWidth: { type: Number, default: 36, _edit: { description: 'Ring thickness in pixels.' } },
+});
+const emit = defineEmits(['select', 'retry']);
+const renderer = shallowRef(null);
+const loadError = ref('');
+const hiddenKeys = ref([]);
+const active = ref(null);
+let disposed = false;
+const items = computed(getItems);
+const visibleItems = computed(() => items.value.filter((item) => !hiddenKeys.value.includes(item.key)));
+const total = computed(() => visibleItems.value.some((item) => item.value !== undefined) ? visibleItems.value.reduce((sum, item) => sum + (item.value || 0), 0) : null);
+const validationError = computed(getValidationError);
+const tooltipItems = computed(() => active.value ? [{ ...active.value, value: formatValue(active.value.value) }] : []);
+onMounted(loadRenderer);
+onBeforeUnmount(() => { disposed = true; });
+watch(items, () => { active.value = null; });
+
+/** @returns {Array<object>} Categories preserving source records and missing values. */
+function getItems() {
+	return props.rows.flatMap((row, index) => {
+		if (!row || typeof row !== 'object') return [];
+		const key = String(row[props.labelKey] ?? index);
+		return [{ key, label: String(row[props.labelKey] ?? 'Unlabelled'), value: chartNumber(row[props.valueKey]), color: chartColor(key, row[props.colorKey]), row, index }];
+	});
+}
+
+/** @returns {string} Invalid data explanation, avoiding misleading category shares. */
+function getValidationError() {
+	if (items.value.some((item) => item.value < 0)) return 'Donut charts require non-negative measurements.';
+	if (new Set(items.value.map((item) => item.key)).size !== items.value.length) return 'Provide one row per category; category labels must be unique.';
+	return '';
+}
+
+/** @returns {Promise<void>} Loads the browser-only rendering component. */
+async function loadRenderer() {
+	loadError.value = '';
+	try {
+		const module = await import('../_shared/DonutRenderer.vue');
+		if (!disposed) renderer.value = module.default;
+	} catch {
+		if (!disposed) loadError.value = 'The chart could not be loaded.';
+	}
+}
+
+/** @returns {void} Retries the engine or delegates data recovery. */
+function retry() { if (loadError.value) loadRenderer(); else emit('retry'); }
+/** @param {unknown} value Measurement. @returns {string} Consistent formatted value. */
+function formatValue(value) { return formatChartValue(value, props); }
+/** @param {object} item Category. @returns {void} Emits the original selected record. */
+function select(item) { if (item) emit('select', { row: item.row, index: item.index }); }
+/** @param {string} key Category key. @returns {void} Toggles visibility while preserving one category. */
+function toggle(key) {
+	if (hiddenKeys.value.includes(key)) hiddenKeys.value = hiddenKeys.value.filter((item) => item !== key);
+	else if (visibleItems.value.length > 1) hiddenKeys.value = [...hiddenKeys.value, key];
+	active.value = null;
+}
+</script>
+
+<template>
+	<ChartContainer :title="title" :description="description" :height="height" :loading="loading" :error="error || validationError || loadError" :empty="total === null" :empty-label="emptyLabel" @retry="retry">
+		<div class="relative" :style="{ height: `${Math.max(120, height)}px` }">
+			<component :is="renderer" v-if="renderer" aria-hidden="true" :items="visibleItems.filter(item => item.value > 0)" :height="Math.max(120, height)" :total="$slots.center ? '' : formatValue(total)" :label="$slots.center ? '' : totalLabel" :arc-width="arcWidth" @inspect="active = $event" @select="select" />
+			<div v-if="$slots.center" class="pointer-events-none absolute inset-0 flex items-center justify-center text-center">
+				<slot name="center" :total="total" :formatted-total="formatValue(total)" />
+			</div>
+			<ChartTooltip v-if="active" class="absolute right-2 top-2 z-10" :label="active.label" :items="tooltipItems" />
+			<p v-if="total === 0" class="absolute inset-x-0 bottom-1 text-center text-xs text-muted-fg">No positive values for this period</p>
+		</div>
+		<template #legend><ChartLegend v-if="legend && !loading && !error" :items="items" :hidden-keys="hiddenKeys" @toggle="toggle" /></template>
+		<template #table>
+			<details v-if="showTable && items.length && !loading && !error" class="mt-3 text-xs text-muted-fg">
+				<summary class="w-fit cursor-pointer rounded py-2 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring">View data for {{ title }}</summary>
+				<div class="mt-3 overflow-auto rounded-lg border border-border">
+					<table class="w-full text-left tabular-nums"><caption class="sr-only">{{ title }}. Missing values are shown as a dash.</caption>
+						<thead class="bg-secondary text-canvas-fg"><tr><th scope="col" class="px-3 py-2">Category</th><th scope="col" class="px-3 py-2 text-right">Value</th></tr></thead>
+						<tbody><tr v-for="item in items" :key="item.key" class="border-t border-border"><th scope="row" class="px-3 py-2"><button type="button" class="rounded text-left font-medium underline underline-offset-4 focus-visible:ring-2 focus-visible:ring-ring" @focus="active = item" @blur="active = null" @click="select(item)">{{ item.label }}</button></th><td class="px-3 py-2 text-right">{{ formatValue(item.value) }}</td></tr></tbody>
+					</table>
+				</div>
+			</details>
+		</template>
+	</ChartContainer>
+</template>

package/src/pages/charts/line-chart/DomLineChart.vue

@@ -0,0 +1,26 @@
+<script setup>
+import { chartProps } from '../_shared/chartProps.js';
+import XYChart from '../_shared/XYChart.vue';
+
+defineOptions({
+	__doc: {
+		name: 'Line chart',
+		tag: '<DomLineChart>',
+		description: 'Compare trends, reporting periods, and targets with proportional time or ordered category axes.',
+		icon: 'M4 4v16h16M7 14l4-5 4 3 5-7',
+		events: [
+			{ name: 'select', payload: '{ row, index }', description: 'Original application record selected by click or Enter.' },
+			{ name: 'retry', description: 'Requests another attempt to load application data.' },
+		],
+		keyboard: [{ keys: 'Arrow keys / Home / End', action: 'Inspect data points.' }, { keys: 'Enter', action: 'Select the inspected record.' }],
+	},
+});
+const props = defineProps({
+	...chartProps,
+});
+defineEmits(['select', 'retry']);
+</script>
+
+<template>
+	<XYChart v-bind="props" kind="line" @select="$emit('select', $event)" @retry="$emit('retry')" />
+</template>

package/src/pages/charts/metric-card/DomMetricCard.vue

@@ -0,0 +1,49 @@
+<script setup>
+import { computed } from 'vue';
+import DomCard from '../../visual/card/DomCard.vue';
+import DomSparkline from '../sparkline/DomSparkline.vue';
+import { chartNumber, formatChartValue } from '../_shared/chartUtils.js';
+
+defineOptions({
+	__doc: { name: 'Metric card', tag: '<DomMetricCard>', description: 'A formatted measurement, explicit comparison, and optional sparkline for reporting dashboards.', icon: 'M4 5h16v14H4zM7 15l3-3 3 1 4-5' },
+});
+const props = defineProps({
+	label: { type: String, default: 'Revenue', _edit: { description: 'Metric name.' } },
+	value: { type: Number, default: null, _edit: { description: 'Current value. Null is unavailable; zero remains zero.' } },
+	format: { type: String, default: 'number', _edit: { options: ['number', 'compact', 'currency', 'percent'] } },
+	currency: { type: String, default: 'GBP' },
+	locale: { type: String, default: 'en-GB' },
+	change: { type: Number, default: null, _edit: { description: 'Relative change as a fraction, e.g. 0.12 for +12%. Calculated by the application.' } },
+	comparisonLabel: { type: String, default: 'vs previous period' },
+	trend: { type: String, default: 'up-good', _edit: { options: ['up-good', 'down-good', 'neutral'], description: 'Whether an increase or decrease represents improvement.' } },
+	loading: { type: Boolean, default: false },
+	rows: { type: Array, default: () => [], _edit: { description: 'Optional sparkline records.' } },
+	xKey: { type: String, default: 'date' },
+	valueKey: { type: String, default: 'value' },
+	color: { type: String, default: 'primary' },
+});
+const formatted = computed(() => formatChartValue(props.value, props));
+const changeLabel = computed(getChangeLabel);
+const tone = computed(getTone);
+
+/** @returns {string} Signed percentage change without inventing a comparison. */
+function getChangeLabel() {
+	if (chartNumber(props.change) === undefined) return '';
+	return new Intl.NumberFormat(props.locale, { style: 'percent', maximumFractionDigits: 1, signDisplay: 'exceptZero' }).format(props.change);
+}
+/** @returns {string} Semantic performance colour based on metric direction. */
+function getTone() {
+	if (props.trend === 'neutral' || !props.change) return 'text-muted-fg';
+	return (props.change > 0) === (props.trend === 'up-good') ? 'text-success' : 'text-destructive';
+}
+</script>
+
+<template>
+	<DomCard padding="sm" :aria-busy="loading || undefined">
+		<p class="text-sm text-muted-fg">{{ label }}</p>
+		<p class="mt-2 text-3xl font-semibold tracking-tight tabular-nums text-canvas-fg" :class="loading && 'motion-safe:animate-pulse'">{{ loading ? '…' : formatted }}</p>
+		<p v-if="changeLabel && !loading" class="mt-2 flex flex-wrap items-center gap-x-2 text-xs"><span class="font-medium tabular-nums" :class="tone">{{ changeLabel }}</span><span class="text-muted-fg">{{ comparisonLabel }}</span></p>
+		<DomSparkline v-if="rows.length" class="mt-5" :title="`${label} trend`" :rows="rows" :x-key="xKey" :series="[{ key: valueKey, label, color }]" :format="format" :currency="currency" :locale="locale" :loading="loading" />
+		<slot />
+	</DomCard>
+</template>

package/src/pages/charts/sparkline/DomSparkline.vue

@@ -0,0 +1,30 @@
+<script setup>
+import { chartProps } from '../_shared/chartProps.js';
+import XYChart from '../_shared/XYChart.vue';
+
+defineOptions({
+	__doc: {
+		name: 'Sparkline',
+		tag: '<DomSparkline>',
+		description: 'Compact trends for metric cards, table cells, and resource lists.',
+		icon: 'M4 4v16h16M7 14l4-5 4 3 5-7',
+		events: [
+			{ name: 'select', payload: '{ row, index }', description: 'Original application record selected by click or Enter.' },
+			{ name: 'retry', description: 'Requests another attempt to load application data.' },
+		],
+		keyboard: [{ keys: 'Arrow keys / Home / End', action: 'Inspect data points.' }, { keys: 'Enter', action: 'Select the inspected record.' }],
+	},
+});
+const props = defineProps({
+	...chartProps,
+	title: { type: String, default: 'Trend' },
+	height: { type: Number, default: 48 },
+	legend: { type: Boolean, default: false },
+	showTable: { type: Boolean, default: false },
+});
+defineEmits(['select', 'retry']);
+</script>
+
+<template>
+	<XYChart v-bind="props" kind="line" compact @select="$emit('select', $event)" @retry="$emit('retry')" />
+</template>

package/src/pages/components/_shared/media/MediaDeviceSelect.vue

@@ -0,0 +1,28 @@
+<script setup>
+import { computed } from 'vue';
+import DomNativeSelect from '../../../forms/native-select/DomNativeSelect.vue';
+
+const props = defineProps({
+	devices: { type: Array, required: true },
+	deviceId: { type: String, default: '' },
+	label: { type: String, default: 'Microphone' },
+	disabled: { type: Boolean, default: false },
+});
+const emit = defineEmits(['select']);
+/** Keeps saved selections readable before permission reveals the device list. */
+const options = computed(() => {
+	const items = props.devices.map(toOption);
+	if (props.deviceId && !items.some(matchesSelection)) {
+		items.unshift({ value: props.deviceId, label: `Selected ${props.label.toLowerCase()}` });
+	}
+	return [{ value: '', label: 'System default' }, ...items];
+});
+/** Tests whether discovery already includes the committed or saved input. */
+function matchesSelection(option) { return option.value === props.deviceId; }
+/** Converts browser input metadata into the native select's public option shape. */
+function toOption(device) { return { value: device.deviceId, label: device.label }; }
+</script>
+
+<template>
+	<DomNativeSelect :label="label" :model-value="deviceId" :options="options" placeholder="" :disabled="disabled" @update:model-value="emit('select', $event)" />
+</template>