@getdom/studio 0.1.1 → 0.2.0

package/src/pages/_layout/componentLoaders.js

@@ -0,0 +1,41 @@
+const lazyComponentModules = import.meta.glob([
+	'../components/*/Dom*.vue',
+	'../data/*/Dom*.vue',
+	'../charts/*/Dom*.vue',
+	'../dev/*/Dom*.vue',
+	'../forms/*/Dom*.vue',
+	'../mobile/*/Dom*.vue',
+	'../visual/*/Dom*.vue',
+	'../designer/*/Dom*.vue',
+	'!../components/playground/DomRenderer.vue',
+	'!../components/toast/DomToastItem.vue',
+	'!../forms/_shared/Dom*.vue',
+], { import: 'default' });
+const lazyComponentSourceModules = import.meta.glob([
+	'../components/*/Dom*.vue',
+	'../data/*/Dom*.vue',
+	'../charts/*/Dom*.vue',
+	'../dev/*/Dom*.vue',
+	'../forms/*/Dom*.vue',
+	'../mobile/*/Dom*.vue',
+	'../visual/*/Dom*.vue',
+	'../designer/*/Dom*.vue',
+	'!../components/playground/DomRenderer.vue',
+	'!../components/toast/DomToastItem.vue',
+	'!../forms/_shared/Dom*.vue',
+], { import: 'default', query: '?raw' });
+
+/**
+ * Resolves a component implementation or source only when documentation needs it.
+ * Keeping these import maps in a separate chunk avoids shipping every component's
+ * preload dependency list with the homepage router.
+ *
+ * @param {string} path Catalogued component path.
+ * @param {boolean} source Whether to load raw SFC source instead of the component.
+ * @returns {Promise<object|string>} Component or source module content.
+ */
+export function loadComponent(path, source = false) {
+	const loader = (source ? lazyComponentSourceModules : lazyComponentModules)[path];
+	if (!loader) throw new Error(`Unknown component path: ${path}`);
+	return loader();
+}

package/src/pages/_layout/componentManager.js

@@ -1,29 +1,19 @@
 import { componentCatalog } from './componentCatalog.generated.js';
 
-const lazyComponentModules = import.meta.glob([
-	'../components/*/Dom*.vue',
-	'../data/*/Dom*.vue',
-	'../dev/*/Dom*.vue',
-	'../forms/*/Dom*.vue',
-	'../mobile/*/Dom*.vue',
-	'../visual/*/Dom*.vue',
-	'!../components/playground/DomRenderer.vue',
-	'!../components/toast/DomToastItem.vue',
-	'!../forms/_shared/Dom*.vue',
-], { import: 'default' });
-const lazyComponentSourceModules = import.meta.glob([
-	'../components/*/Dom*.vue',
-	'../data/*/Dom*.vue',
-	'../dev/*/Dom*.vue',
-	'../forms/*/Dom*.vue',
-	'../mobile/*/Dom*.vue',
-	'../visual/*/Dom*.vue',
-	'!../components/playground/DomRenderer.vue',
-	'!../components/toast/DomToastItem.vue',
-	'!../forms/_shared/Dom*.vue',
-], { import: 'default', query: '?raw' });
+export const componentSections = ['components', 'data', 'charts', 'dev', 'forms', 'mobile', 'visual', 'designer'];
+export const componentNavigationSections = ['ai', ...componentSections];
 
-export const componentSections = ['components', 'data', 'dev', 'forms', 'mobile', 'visual'];
+/**
+ * Resolves a component's navigation category independently of its source path.
+ * Unknown overrides fall back to the source section so components stay discoverable.
+ *
+ * @param {object} record Component catalogue or inspected metadata record.
+ * @returns {string} Section used by navigation, search, and component indexes.
+ */
+export function getComponentNavigationSection(record) {
+	const section = record.doc?.nav?.section;
+	return componentNavigationSections.includes(section) ? section : record.section;
+}
 
 /**
  * Returns component records that are safe for app-shell navigation and search.
@@ -47,10 +37,28 @@ export function getLazyComponentRecords() {
 	return getComponentRecords()
 		.map((record) => ({
 			...record,
-			loader: lazyComponentModules[record.path],
-			sourceLoader: lazyComponentSourceModules[record.path],
-		}))
-		.filter((record) => record.loader);
+			loader: createComponentLoader(record.path),
+			sourceLoader: createComponentLoader(record.path, true),
+		}));
+}
+
+/**
+ * Creates a documentation loader without importing the full component import map.
+ *
+ * @param {string} path Catalogued component path.
+ * @param {boolean} source Whether to load raw SFC source.
+ * @returns {Function} Lazy Vue Router or documentation source loader.
+ */
+function createComponentLoader(path, source = false) {
+	/**
+	 * Resolves the shared import map and then the requested component resource.
+	 * @returns {Promise<object|string>} Component implementation or raw source.
+	 */
+	async function load() {
+		const { loadComponent } = await import('./componentLoaders.js');
+		return loadComponent(path, source);
+	}
+	return load;
 }
 
 /**
@@ -113,8 +121,11 @@ export function getDevRedirectRecords() {
  */
 export function labelFromSection(section) {
 	return {
+		ai: 'AI',
+		designer: 'UI designer',
 		components: 'Components',
 		data: 'Data',
+		charts: 'Data Visualisation',
 		dev: 'Dev',
 		forms: 'Forms',
 		mobile: 'Mobile',

package/src/pages/_layout/componentRuntimeRecords.js

@@ -1,10 +1,12 @@
 const eagerComponentModules = import.meta.glob([
 	'../components/*/Dom*.vue',
 	'../data/*/Dom*.vue',
+	'../charts/*/Dom*.vue',
 	'../dev/*/Dom*.vue',
 	'../forms/*/Dom*.vue',
 	'../mobile/*/Dom*.vue',
 	'../visual/*/Dom*.vue',
+	'../designer/*/Dom*.vue',
 	'!../components/playground/DomRenderer.vue',
 	'!../components/toast/DomToastItem.vue',
 	'!../forms/_shared/Dom*.vue',
@@ -33,7 +35,7 @@ export function getRuntimeComponentRecords() {
  * @returns {object|null} Component record, or null for unrecognized paths.
  */
 function recordFromPath(path, component) {
-	const match = path.match(/^\.\.\/(components|data|dev|forms|mobile|visual)\/([^/]+)\/(Dom[^/]+)\.vue$/);
+	const match = path.match(/^\.\.\/(components|data|charts|dev|forms|mobile|visual|designer)\/([^/]+)\/(Dom[^/]+)\.vue$/);
 	if (!match) return null;
 
 	const [, section, slug, exportName] = match;

package/src/pages/charts/_shared/ChartContainer.vue

@@ -0,0 +1,67 @@
+<script setup>
+import { useId } from 'vue';
+import DomButton from '../../components/button/DomButton.vue';
+import DomEmptyState from '../../visual/empty-state/DomEmptyState.vue';
+import DomSkeleton from '../../visual/skeleton/DomSkeleton.vue';
+
+defineProps({
+	title: { type: String, default: 'Chart' },
+	description: { type: String, default: '' },
+	height: { type: Number, default: 280 },
+	loading: { type: Boolean, default: false },
+	error: { type: String, default: '' },
+	empty: { type: Boolean, default: false },
+	emptyLabel: { type: String, default: 'No data for this period' },
+	compact: { type: Boolean, default: false },
+});
+defineEmits(['retry']);
+const titleId = useId();
+</script>
+
+<template>
+	<figure class="m-0 min-w-0 w-full" :aria-labelledby="titleId" :aria-busy="loading || undefined">
+		<figcaption :class="compact ? 'sr-only' : 'mb-5'">
+			<div :id="titleId" class="text-sm font-semibold text-canvas-fg">{{ title }}</div>
+			<p v-if="description" class="mt-1 text-sm leading-6 text-muted-fg">{{ description }}</p>
+		</figcaption>
+		<div class="relative min-w-0" :style="{ minHeight: `${Math.max(32, height)}px` }">
+			<div v-if="loading" role="status" class="flex h-full items-end gap-3 p-4" :style="{ height: `${Math.max(32, height)}px` }">
+				<span class="sr-only">Loading {{ title }}</span>
+				<DomSkeleton v-for="size in [45, 70, 55, 85, 65, 95, 75]" :key="size" aria-hidden="true" class="flex-1" :style="{ height: `${size}%` }" />
+			</div>
+			<div v-else-if="error" role="alert" class="grid place-content-center gap-3 text-center" :style="{ minHeight: `${Math.max(80, height)}px` }">
+				<p class="text-sm text-muted-fg">{{ error }}</p>
+				<DomButton size="sm" variant="secondary" class="justify-self-center" @click="$emit('retry')">Try again</DomButton>
+			</div>
+			<div v-else-if="empty" class="grid place-content-center" :style="{ minHeight: `${Math.max(32, height)}px` }">
+				<p v-if="compact" class="text-xs text-muted-fg">{{ emptyLabel }}</p>
+				<DomEmptyState v-else :title="emptyLabel" description="Choose another period or check back when measurements are available." size="sm" />
+			</div>
+			<slot v-else />
+		</div>
+		<slot name="legend" />
+		<slot name="table" />
+	</figure>
+</template>
+
+<style scoped>
+/* Unovis draws SVG attributes from inherited variables, including in dark themes. */
+figure {
+	--vis-font-family: inherit;
+	--vis-color-main: var(--primary);
+	--vis-axis-tick-label-color: var(--muted-fg);
+	--vis-axis-label-color: var(--muted-fg);
+	--vis-axis-grid-color: var(--border);
+	--vis-axis-domain-color: var(--border);
+	--vis-crosshair-line-stroke-color: var(--muted-fg);
+	--vis-donut-central-label-text-color: var(--canvas-fg);
+	--vis-donut-central-sub-label-text-color: var(--muted-fg);
+	--vis-donut-background-color: var(--secondary);
+}
+
+@media (prefers-reduced-motion: reduce) {
+	figure {
+		--vis-axis-tick-label-hide-transition: none;
+	}
+}
+</style>

package/src/pages/charts/_shared/ChartLegend.vue

@@ -0,0 +1,22 @@
+<script setup>
+defineProps({
+	items: { type: Array, default: () => [] },
+	hiddenKeys: { type: Array, default: () => [] },
+});
+defineEmits(['toggle']);
+</script>
+
+<template>
+	<div class="mt-4 flex flex-wrap items-center justify-center gap-x-4 gap-y-2" role="group" aria-label="Chart legend">
+		<button
+			v-for="item in items" :key="item.key" type="button"
+			class="inline-flex min-h-9 min-w-0 items-center gap-2 rounded-md px-1 text-xs text-muted-fg transition hover:text-canvas-fg focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+			:aria-pressed="!hiddenKeys.includes(item.key)"
+			:class="hiddenKeys.includes(item.key) && 'opacity-45'"
+			@click="$emit('toggle', item.key)"
+		>
+			<span class="h-0.5 w-4 shrink-0 border-t-2" :style="{ borderColor: item.color, borderStyle: item.dashed ? 'dashed' : 'solid' }" aria-hidden="true" />
+			<span :class="hiddenKeys.includes(item.key) && 'line-through'">{{ item.label }}</span>
+		</button>
+	</div>
+</template>

package/src/pages/charts/_shared/ChartTooltip.vue

@@ -0,0 +1,18 @@
+<script setup>
+defineProps({
+	label: { type: String, default: '' },
+	items: { type: Array, default: () => [] },
+});
+</script>
+
+<template>
+	<div class="pointer-events-none max-w-full rounded-lg border border-border skin-popover px-3 py-2 text-xs shadow-lg">
+		<p class="mb-2 truncate font-medium text-canvas-fg">{{ label }}</p>
+		<dl class="space-y-1.5">
+			<div v-for="item in items" :key="item.key" class="flex items-center justify-between gap-5">
+				<dt class="flex min-w-0 items-center gap-2 text-muted-fg"><span class="size-2 shrink-0 rounded-sm" :style="{ background: item.color }" /><span class="truncate">{{ item.label }}</span></dt>
+				<dd class="shrink-0 font-medium tabular-nums text-canvas-fg">{{ item.value }}</dd>
+			</div>
+		</dl>
+	</div>
+</template>

package/src/pages/charts/_shared/DonutRenderer.vue

@@ -0,0 +1,33 @@
+<script setup>
+import VisSingleContainer from '@unovis/vue/containers/single-container';
+import VisDonut, { VisDonutSelectors } from '@unovis/vue/components/donut';
+
+defineProps({
+	items: { type: Array, required: true },
+	height: { type: Number, default: 260 },
+	total: { type: String, default: '' },
+	label: { type: String, default: 'Total' },
+	arcWidth: { type: Number, default: 36 },
+});
+const emit = defineEmits(['inspect', 'select']);
+const events = { [VisDonutSelectors.segment]: { mouseover: inspect, mouseout: clear, click: select } };
+
+/** @param {object} item Chart category. @returns {number} Segment value. */
+function value(item) { return item.value; }
+/** @param {object} item Chart category. @returns {string} Stable segment colour. */
+function color(item) { return item.color; }
+/** @param {object} item Chart category. @returns {string} Stable segment identity. */
+function id(item) { return item.key; }
+/** @param {object} datum Unovis arc datum. @returns {void} Shows category detail. */
+function inspect(datum) { emit('inspect', datum.data || datum); }
+/** @returns {void} Hides category detail. */
+function clear() { emit('inspect', null); }
+/** @param {object} datum Unovis arc datum. @returns {void} Selects the category. */
+function select(datum) { emit('select', datum.data || datum); }
+</script>
+
+<template>
+	<VisSingleContainer :data="items" :height="height" :duration="0" class="block w-full">
+		<VisDonut :value="value" :color="color" :id="id" :arc-width="arcWidth" :pad-angle="0.025" :corner-radius="3" :central-label="total" :central-sub-label="label" :events="events" :duration="0" />
+	</VisSingleContainer>
+</template>

package/src/pages/charts/_shared/XYChart.vue

@@ -0,0 +1,140 @@
+<script setup>
+import { computed, onBeforeUnmount, onMounted, ref, shallowRef, watch } from 'vue';
+import { chartProps } from './chartProps.js';
+import { chartPoints, chartSeries, formatChartValue, percentagePoints } from './chartUtils.js';
+import ChartContainer from './ChartContainer.vue';
+import ChartLegend from './ChartLegend.vue';
+import ChartTooltip from './ChartTooltip.vue';
+
+const props = defineProps({
+	...chartProps,
+	kind: { type: String, default: 'line' },
+	stacked: { type: Boolean, default: false },
+	percentage: { type: Boolean, default: false },
+	horizontal: { type: Boolean, default: false },
+	compact: { type: Boolean, default: false },
+});
+const emit = defineEmits(['retry', 'select']);
+const renderer = shallowRef(null);
+const loadError = ref('');
+const hiddenKeys = ref([]);
+const inspected = ref(null);
+let disposed = false;
+const allSeries = computed(() => chartSeries(props.series));
+const visibleSeries = computed(() => allSeries.value.filter((item) => !hiddenKeys.value.includes(item.key)));
+const points = computed(() => chartPoints(props.rows, props.xKey, props.xType, allSeries.value));
+const renderPoints = computed(() => props.percentage ? percentagePoints(points.value, visibleSeries.value) : points.value);
+const hasData = computed(() => points.value.some((point) => visibleSeries.value.some((item) => Number.isFinite(point.values[item.key]))));
+const validationError = computed(() => props.percentage && points.value.some((point) => visibleSeries.value.some((item) => point.values[item.key] < 0)) ? 'Percentage stacks require non-negative measurements.' : '');
+const tooltipItems = computed(() => inspected.value ? visibleSeries.value.map((item) => ({ ...item, value: formatValue(inspected.value.values[item.key]) })) : []);
+const safeHeight = computed(() => Math.max(props.compact ? 32 : 120, props.height));
+
+onMounted(loadRenderer);
+onBeforeUnmount(() => { disposed = true; });
+watch(points, () => { inspected.value = null; });
+
+/** Loads the drawing engine only in the browser, preserving SSR-safe imports. @returns {Promise<void>} */
+async function loadRenderer() {
+	loadError.value = '';
+	try {
+		const module = await import('./XYRenderer.vue');
+		if (!disposed) renderer.value = module.default;
+	} catch {
+		if (!disposed) loadError.value = 'The chart could not be loaded.';
+	}
+}
+
+/** Retries an engine failure or delegates application data recovery. @returns {void} */
+function retry() {
+	if (loadError.value) loadRenderer();
+	else emit('retry');
+}
+
+/** @param {string} key Series key. @returns {void} Toggles a series while preserving at least one. */
+function toggleSeries(key) {
+	if (hiddenKeys.value.includes(key)) hiddenKeys.value = hiddenKeys.value.filter((entry) => entry !== key);
+	else if (visibleSeries.value.length > 1) hiddenKeys.value = [...hiddenKeys.value, key];
+}
+
+/** @param {unknown} value Measurement. @returns {string} Formatted measurement. */
+function formatValue(value) { return formatChartValue(value, props); }
+
+/** @param {number} value Numeric axis tick. @returns {string} Value-axis label. */
+function formatAxisValue(value) {
+	if (props.yFormatter) return String(props.yFormatter(value));
+	return props.percentage ? `${Math.round(value)}%` : formatValue(value);
+}
+
+/** @param {unknown} value Raw horizontal value. @returns {string} Category, date, or number label. */
+function formatLabel(value) {
+	if (props.xFormatter) return String(props.xFormatter(value));
+	if (props.xType === 'time') return new Intl.DateTimeFormat(props.locale, { month: 'short', day: 'numeric', timeZone: 'UTC' }).format(new Date(value));
+	return String(value ?? '—');
+}
+
+/** @param {number} value Numeric axis coordinate. @returns {string} Axis tick label. */
+function formatAxisLabel(value) {
+	return formatLabel(props.xType === 'category' ? props.rows[Math.round(value)]?.[props.xKey] : value);
+}
+
+/** @param {object|null} point Hovered point. @returns {void} Updates the shared tooltip. */
+function inspect(point) { inspected.value = point ? points.value.find((entry) => entry.index === point.index) || null : null; }
+
+/** @param {KeyboardEvent} event Chart navigation key. @returns {void} Inspects or selects a datum. */
+function navigate(event) {
+	if (!hasData.value) return;
+	const index = Math.max(0, points.value.findIndex((point) => point.index === inspected.value?.index));
+	let next = index;
+	if (event.key === 'ArrowRight' || event.key === 'ArrowDown') next = Math.min(points.value.length - 1, index + 1);
+	else if (event.key === 'ArrowLeft' || event.key === 'ArrowUp') next = Math.max(0, index - 1);
+	else if (event.key === 'Home') next = 0;
+	else if (event.key === 'End') next = points.value.length - 1;
+	else if (event.key === 'Escape') { inspected.value = null; return; }
+	else if (event.key === 'Enter' || event.key === ' ') { selectPoint(); event.preventDefault(); return; }
+	else return;
+	event.preventDefault();
+	inspected.value = points.value[next];
+}
+
+/** @returns {void} Emits the original application record selected by the user. */
+function selectPoint() {
+	if (inspected.value) emit('select', { row: inspected.value.row, index: inspected.value.index });
+}
+
+/** @param {Event} event Accessible scrubber input. @returns {void} Inspects a data point on touch or keyboard. */
+function scrub(event) { inspected.value = points.value[Number(event.target.value)]; }
+</script>
+
+<template>
+	<ChartContainer :title="title" :description="description" :height="safeHeight" :compact="compact" :loading="loading" :error="error || validationError || loadError" :empty="!hasData" :empty-label="emptyLabel" @retry="retry">
+		<div
+			class="relative rounded-md focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+			:style="{ height: `${safeHeight}px` }" tabindex="0" role="group"
+			:aria-label="`${title}. Use arrow keys to inspect values; Enter selects a row.`"
+			@keydown="navigate" @focus="inspect(points[0])" @blur="inspect(null)" @mouseleave="inspect(null)" @click="selectPoint"
+		>
+			<div aria-hidden="true">
+				<component :is="renderer" v-if="renderer" :key="`${kind}-${horizontal}-${stacked}-${percentage}`" :points="renderPoints" :series="visibleSeries" :kind="kind" :height="safeHeight" :curve="curve" :stacked="stacked || percentage" :percentage="percentage" :horizontal="horizontal" :compact="compact" :grid="grid" :x-type="xType" :format-x="formatAxisLabel" :format-y="formatAxisValue" @inspect="inspect" />
+				<div v-else class="h-full w-full" />
+			</div>
+			<ChartTooltip v-if="inspected && !compact" class="absolute right-2 top-2 z-10" :label="formatLabel(inspected.row[xKey])" :items="tooltipItems" />
+			<span class="sr-only" aria-live="polite">{{ inspected ? `${formatLabel(inspected.row[xKey])}: ${tooltipItems.map(item => `${item.label} ${item.value}`).join(', ')}` : '' }}</span>
+		</div>
+		<template #legend>
+			<ChartLegend v-if="legend && !loading && !error && allSeries.length" :items="allSeries" :hidden-keys="hiddenKeys" @toggle="toggleSeries" />
+		</template>
+		<template #table>
+			<details v-if="showTable && !loading && !error && points.length" 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>
+				<label v-if="points.length > 1" class="mt-3 flex items-center gap-3">Inspect data<input type="range" min="0" :max="points.length - 1" :value="Math.max(0, points.findIndex(point => point.index === inspected?.index))" class="min-w-0 flex-1 accent-primary" @input="scrub" /></label>
+				<div class="mt-3 max-h-80 overflow-auto rounded-lg border border-border" tabindex="0" :aria-label="`${title} data table`">
+					<table class="w-full text-left text-xs tabular-nums">
+						<caption class="sr-only">{{ title }}. Missing measurements are shown as a dash.{{ percentage ? ' Original measurements before percentage normalization.' : '' }}</caption>
+						<thead class="sticky top-0 bg-secondary text-canvas-fg"><tr><th scope="col" class="px-3 py-2">{{ xKey }}</th><th v-for="item in allSeries" :key="item.key" scope="col" class="px-3 py-2 text-right">{{ item.label }}</th></tr></thead>
+						<tbody><tr v-for="point in points" :key="point.index" class="border-t border-border"><th scope="row" class="whitespace-nowrap px-3 py-2 font-medium">{{ formatLabel(point.row[xKey]) }}</th><td v-for="item in allSeries" :key="item.key" class="whitespace-nowrap px-3 py-2 text-right">{{ formatValue(point.values[item.key]) }}</td></tr></tbody>
+					</table>
+				</div>
+			</details>
+		</template>
+	</ChartContainer>
+</template>

package/src/pages/charts/_shared/XYRenderer.vue

@@ -0,0 +1,90 @@
+<script setup>
+import { computed } from 'vue';
+import VisXYContainer from '@unovis/vue/containers/xy-container';
+import VisAxis from '@unovis/vue/components/axis';
+import VisLine from '@unovis/vue/components/line';
+import VisArea from '@unovis/vue/components/area';
+import VisGroupedBar, { VisGroupedBarSelectors } from '@unovis/vue/components/grouped-bar';
+import VisStackedBar, { VisStackedBarSelectors } from '@unovis/vue/components/stacked-bar';
+import VisCrosshair from '@unovis/vue/components/crosshair';
+import VisScatter from '@unovis/vue/components/scatter';
+
+const props = defineProps({
+	points: { type: Array, required: true },
+	series: { type: Array, required: true },
+	kind: { type: String, default: 'line' },
+	height: { type: Number, default: 280 },
+	curve: { type: String, default: 'linear' },
+	stacked: { type: Boolean, default: false },
+	percentage: { type: Boolean, default: false },
+	horizontal: { type: Boolean, default: false },
+	compact: { type: Boolean, default: false },
+	grid: { type: Boolean, default: true },
+	xType: { type: String, default: 'category' },
+	formatX: { type: Function, required: true },
+	formatY: { type: Function, required: true },
+});
+const emit = defineEmits(['inspect']);
+const accessors = computed(getAccessors);
+const categoryTicks = computed(getCategoryTicks);
+const valueDomain = computed(getValueDomain);
+const barEvents = computed(() => ({
+	[props.stacked ? VisStackedBarSelectors.bar : VisGroupedBarSelectors.bar]: { mouseover: inspectBar, click: inspectBar },
+}));
+
+/** @returns {Array<Function>} Measurement accessors for visible series. */
+function getAccessors() {
+	return props.series.map((item) => (point) => point.values[item.key]);
+}
+
+/** @returns {number[]|undefined} Exact categorical ticks; continuous axes choose their own. */
+function getCategoryTicks() {
+	return props.xType === 'category' ? props.points.map(getX) : undefined;
+}
+
+/** @returns {Array<number|undefined>} Value domain including zero for filled charts. */
+function getValueDomain() {
+	if (props.percentage) return [0, 100];
+	if (props.kind === 'line') return [undefined, undefined];
+	const values = props.points.flatMap((point) => props.series.map((item) => point.values[item.key])).filter(Number.isFinite);
+	return [values.some((value) => value < 0) ? undefined : 0, values.some((value) => value > 0) ? undefined : 0];
+}
+
+/** @param {object} point Projected datum. @returns {number} Category coordinate. */
+function getX(point) { return point.x; }
+
+/** @param {unknown} _datum Unovis datum. @param {number} index Series index. @returns {string} Stable colour. */
+function getColor(_datum, index) { return props.series[index]?.color || 'var(--primary)'; }
+
+/** @param {number} _x Pointer coordinate. @param {object} point Nearest datum. @returns {void} */
+function inspectPoint(_x, point) { emit('inspect', point || null); }
+
+/** @param {object} datum Bar or stack datum. @returns {void} Inspects horizontal and touch-selected bars. */
+function inspectBar(datum) { emit('inspect', datum.datum || datum); }
+</script>
+
+<template>
+	<VisXYContainer
+		:data="points" :height="height" :duration="0" class="block w-full"
+		:x-domain="horizontal ? valueDomain : undefined" :y-domain="horizontal ? undefined : valueDomain"
+		:y-direction="horizontal ? 'south' : 'north'"
+		:margin="compact ? { top: 4, bottom: 4, left: 4, right: 4 } : { top: 12, right: 12 }"
+	>
+		<template v-if="kind === 'line'">
+			<VisLine v-for="(item, index) in series" :key="item.key" :x="getX" :y="accessors[index]" :color="item.color" :curve-type="curve" :line-width="2" :line-dash-array="item.dashed ? [5, 4] : undefined" :duration="0" />
+			<VisScatter v-if="points.length === 1" :x="getX" :y="accessors" :color="getColor" :size="24" :duration="0" />
+		</template>
+		<template v-else-if="kind === 'area'">
+			<VisArea v-if="stacked" :x="getX" :y="accessors" :color="getColor" :curve-type="curve" :opacity="0.45" :duration="0" />
+			<VisArea v-for="(item, index) in stacked ? [] : series" :key="item.key" :x="getX" :y="accessors[index]" :color="item.color" :curve-type="curve" :opacity="0.15" :line="true" :line-color="item.color" :duration="0" />
+		</template>
+		<component
+			:is="stacked ? VisStackedBar : VisGroupedBar" v-else
+			:x="getX" :y="accessors" :color="getColor" :orientation="horizontal ? 'horizontal' : 'vertical'"
+			:bar-padding="stacked ? 0.3 : 0.1" :group-padding="0.3" :rounded-corners="3" :bar-min-height="0" :duration="0" :events="barEvents"
+		/>
+		<VisAxis v-if="!compact" :key="`category-${horizontal}`" :type="horizontal ? 'y' : 'x'" :tick-values="categoryTicks" :tick-format="formatX" :grid-line="false" :domain-line="false" :tick-line="false" :tick-text-width="horizontal ? 90 : 72" :tick-text-hide-overlapping="true" :tick-text-adaptive-sets="true" :duration="0" />
+		<VisAxis v-if="!compact" :key="`value-${horizontal}`" :type="horizontal ? 'x' : 'y'" :tick-format="formatY" :grid-line="grid" :domain-line="false" :tick-line="false" :tick-text-width="90" :tick-text-hide-overlapping="true" :num-ticks="4" :duration="0" />
+		<VisCrosshair v-if="!horizontal" :x="getX" :y="stacked ? [] : accessors" :y-stacked="stacked ? accessors : undefined" :color="getColor" :hide-when-far-from-pointer="false" :on-crosshair-move="inspectPoint" :duration="0" />
+	</VisXYContainer>
+</template>

package/src/pages/charts/_shared/chartProps.js

@@ -0,0 +1,23 @@
+/** Shared presentation and data contract for the Cartesian chart family. */
+export const chartProps = {
+	rows: { type: Array, default: () => [], _edit: { description: 'Application-owned records. Missing measurements remain gaps; zero is valid.' } },
+	series: { type: Array, default: () => [], _edit: { description: 'Field keys or { key, label, color, dashed } definitions. Keep keys stable when filtering.' } },
+	xKey: { type: String, default: 'date', _edit: { description: 'Record field used for category or horizontal axis values.' } },
+	xType: { type: String, default: 'category', _edit: { options: ['category', 'time', 'number'], description: 'Category preserves row order; time and number use proportional, sorted coordinates.' } },
+	title: { type: String, default: 'Chart', _edit: { description: 'Visible title and accessible chart name.' } },
+	description: { type: String, default: '', _edit: { description: 'Supporting context, units, or reporting period.' } },
+	height: { type: Number, default: 280, _edit: { description: 'Plot height in pixels; width responds to its container.' } },
+	format: { type: String, default: 'number', _edit: { options: ['number', 'compact', 'currency', 'percent'], description: 'Value format. Percent expects fractions, such as 0.25 for 25%.' } },
+	currency: { type: String, default: 'GBP', _edit: { description: 'ISO currency code for currency formatting.' } },
+	locale: { type: String, default: 'en-GB', _edit: { description: 'Locale used for number and date labels.' } },
+	valueFormatter: { type: Function, default: null, _edit: { description: 'Optional (value) => string override shared by axes, tooltips, and tables.' } },
+	xFormatter: { type: Function, default: null, _edit: { description: 'Optional (value) => string override for category/date labels.' } },
+	yFormatter: { type: Function, default: null, _edit: { description: 'Optional (value) => string for value-axis ticks only. Tooltips and tables keep the full valueFormatter output.' } },
+	loading: { type: Boolean, default: false, _edit: { description: 'Show a loading state in the reserved plot space.' } },
+	error: { type: String, default: '', _edit: { description: 'Show an application-owned error with a retry action.' } },
+	emptyLabel: { type: String, default: 'No data for this period', _edit: { description: 'Message when no finite measurements are available.' } },
+	legend: { type: Boolean, default: true, _edit: { description: 'Show buttons to toggle series without changing their colours.' } },
+	showTable: { type: Boolean, default: true, _edit: { description: 'Offer an accessible, server-rendered table of the chart data.' } },
+	grid: { type: Boolean, default: true, _edit: { description: 'Show subtle value-axis grid lines.' } },
+	curve: { type: String, default: 'linear', _edit: { options: ['linear', 'monotoneX', 'step'], description: 'Line interpolation. Linear avoids implying unobserved smooth changes.' } },
+};

package/src/pages/charts/_shared/chartUtils.js

@@ -0,0 +1,95 @@
+/**
+ * Converts a measurement without turning missing values into misleading zeros.
+ * @param {unknown} value Raw application value.
+ * @returns {number|undefined} Finite measurement, or a missing value.
+ */
+export function chartNumber(value) {
+	if (!['number', 'string'].includes(typeof value) || (typeof value === 'string' && !value.trim())) return undefined;
+	const number = Number(value);
+	return Number.isFinite(number) ? number : undefined;
+}
+
+/**
+ * Resolves a stable palette colour from a series key or an explicit CSS colour.
+ * @param {string} key Stable series or category key.
+ * @param {string} [color] Semantic token or CSS colour.
+ * @returns {string} CSS colour expression.
+ */
+export function chartColor(key, color) {
+	if (color) return /^(primary|secondary|muted-fg|success|warning|destructive|chart-[1-5])$/.test(color) ? `var(--${color})` : color;
+	let hash = 0;
+	for (const character of String(key)) hash = (hash * 31 + character.charCodeAt(0)) >>> 0;
+	return `var(--chart-${hash % 5 + 1}, var(--primary))`;
+}
+
+/**
+ * Normalizes series definitions and removes ambiguous duplicate keys.
+ * @param {Array<string|object>} series Field keys or series definitions.
+ * @returns {Array<object>} Labelled, consistently coloured series.
+ */
+export function chartSeries(series) {
+	const seen = new Set();
+	return series.flatMap((entry) => {
+		const item = typeof entry === 'string' ? { key: entry } : entry;
+		if (!item?.key || seen.has(item.key)) return [];
+		seen.add(item.key);
+		return [{ ...item, label: item.label || item.key, color: chartColor(item.key, item.color) }];
+	});
+}
+
+/**
+ * Projects records into numeric chart coordinates while retaining original rows.
+ * Continuous axes are sorted without modifying the supplied collection.
+ * @param {Array<object>} rows Application-owned records.
+ * @param {string} xKey Category, number, or date field.
+ * @param {'category'|'number'|'time'} xType Horizontal axis interpretation.
+ * @param {Array<object>} series Normalized series definitions.
+ * @returns {Array<object>} Renderable points with original row indexes.
+ */
+export function chartPoints(rows, xKey, xType, series) {
+	const points = rows.flatMap((row, index) => {
+		if (!row || typeof row !== 'object') return [];
+		const rawX = row[xKey];
+		const x = xType === 'time'
+			? (rawX == null || rawX === '' ? NaN : new Date(rawX).getTime())
+			: xType === 'number' ? chartNumber(rawX) : index;
+		if (!Number.isFinite(x)) return [];
+		return [{ row, index, x, values: Object.fromEntries(series.map((item) => [item.key, chartNumber(row[item.key])])) }];
+	});
+	return xType === 'category' ? points : points.sort((a, b) => a.x - b.x);
+}
+
+/**
+ * Formats finite values consistently across axes, tooltips, and data tables.
+ * @param {unknown} value Raw value.
+ * @param {object} options Locale, format, currency, and optional custom formatter.
+ * @returns {string} Human-readable measurement.
+ */
+export function formatChartValue(value, { locale = 'en-GB', format = 'number', currency = 'GBP', valueFormatter } = {}) {
+	const number = chartNumber(value);
+	if (number === undefined) return '—';
+	if (valueFormatter) return String(valueFormatter(number));
+	const options = format === 'currency'
+		? { style: 'currency', currency, maximumFractionDigits: 0 }
+		: format === 'percent'
+			? { style: 'percent', maximumFractionDigits: 1 }
+			: { maximumFractionDigits: 2, ...(format === 'compact' ? { notation: 'compact' } : {}) };
+	return new Intl.NumberFormat(locale, options).format(number);
+}
+
+/**
+ * Normalizes each non-negative row to percentages of its visible series total.
+ * Missing values remain missing, and an all-zero row remains zero.
+ * @param {Array<object>} points Chart points.
+ * @param {Array<object>} series Visible series.
+ * @returns {Array<object>} New points with values in the range 0–100.
+ */
+export function percentagePoints(points, series) {
+	return points.map((point) => {
+		const total = series.reduce((sum, item) => sum + (point.values[item.key] || 0), 0);
+		return { ...point, values: Object.fromEntries(series.map((item) => {
+			const value = point.values[item.key];
+			return [item.key, value === undefined ? undefined : total ? value / total * 100 : 0];
+		})) };
+	});
+}