@getdom/studio 0.1.0

package/src/pages/components/splitter-panel/DomSplitterPanel.vue

@@ -0,0 +1,283 @@
+<script setup>
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, useSlots, watch } from 'vue';
+
+defineOptions({
+	__doc: {
+		name: 'Splitter panel',
+		tag: '<DomSplitterPanel>',
+		description: 'A resizable multi-pane shell for editors, inspectors, file browsers, and app-builder workspaces.',
+		icon: 'M5 4v16M19 4v16M8 6h8M8 12h8M8 18h8',
+		slots: [
+			{ name: 'start', description: 'The leading resizable pane.' },
+			{ name: 'default', description: 'The flexible central pane.' },
+			{ name: 'end', description: 'Optional trailing resizable pane.' },
+			{ name: 'start-handle', description: 'Optional content inside the leading resize handle.' },
+			{ name: 'end-handle', description: 'Optional content inside the trailing resize handle.' },
+		],
+		events: [
+			{ name: 'update:startSize', payload: '(pixels)', description: 'Emitted when the leading pane is resized.' },
+			{ name: 'update:endSize', payload: '(pixels)', description: 'Emitted when the trailing pane is resized.' },
+			{ name: 'resize', payload: '({ startSize, endSize })', description: 'Emitted after either splitter handle moves.' },
+		],
+	},
+});
+
+const props = defineProps({
+	orientation: {
+		type: String,
+		default: 'horizontal',
+		validator: (value) => ['horizontal', 'vertical'].includes(value),
+		_edit: {
+			description: 'Resize direction. Horizontal creates columns; vertical creates rows.',
+			options: ['horizontal', 'vertical'],
+		},
+	},
+	startSize: {
+		type: Number,
+		default: 280,
+		_edit: { description: 'Initial width or height of the leading pane in pixels.' },
+	},
+	endSize: {
+		type: Number,
+		default: 360,
+		_edit: { description: 'Initial width or height of the trailing pane in pixels.' },
+	},
+	minStart: {
+		type: Number,
+		default: 180,
+		_edit: { description: 'Minimum leading pane width or height.' },
+	},
+	minMain: {
+		type: Number,
+		default: 320,
+		_edit: { description: 'Minimum central pane width or height.' },
+	},
+	minEnd: {
+		type: Number,
+		default: 220,
+		_edit: { description: 'Minimum trailing pane width or height.' },
+	},
+	handleSize: {
+		type: Number,
+		default: 8,
+		_edit: { description: 'Splitter handle hit area in pixels.' },
+	},
+	handleClass: {
+		type: [String, Array, Object],
+		default: 'transition hover:bg-ring/25 focus-visible:bg-ring/35 data-[dragging=true]:bg-ring/35',
+		_edit: { description: 'Classes applied to each resize button. Use this to make handles transparent, bordered, or prominent.' },
+	},
+	activeHandleClass: {
+		type: [String, Array, Object],
+		default: '',
+		_edit: { description: 'Additional classes applied to the active resize button while dragging.' },
+	},
+	handleIndicatorClass: {
+		type: [String, Array, Object],
+		default: '',
+		_edit: { description: 'Classes applied to the small visual indicator inside each resize button.' },
+	},
+});
+
+const emit = defineEmits(['update:startSize', 'update:endSize', 'resize']);
+const slots = useSlots();
+const root = ref(null);
+const startPx = ref(props.startSize);
+const endPx = ref(props.endSize);
+const dragging = ref(null);
+let resizeObserver = null;
+
+const hasEnd = computed(() => Boolean(slots.end));
+const isVertical = computed(() => props.orientation === 'vertical');
+const resizeCursor = computed(() => isVertical.value ? 'row-resize' : 'col-resize');
+const rootClass = computed(() => [
+	'grid min-h-0',
+	isVertical.value ? 'overflow-y-auto' : 'overflow-x-auto',
+]);
+const handleBaseClass = computed(() => [
+	'group flex outline-none',
+	isVertical.value
+		? 'min-w-0 cursor-row-resize items-center justify-center'
+		: 'min-h-0 cursor-col-resize items-stretch justify-center',
+]);
+const defaultIndicatorClass = computed(() => [
+	'rounded-full bg-muted-fg/35 opacity-0 transition group-hover:opacity-100 group-data-[dragging=true]:opacity-100 group-data-[dragging=true]:bg-canvas-fg/50',
+	isVertical.value ? 'mx-auto h-0.5 w-10' : 'my-auto h-10 w-0.5',
+]);
+const gridStyle = computed(() => {
+	const tracks = hasEnd.value
+		? `${startPx.value}px ${props.handleSize}px minmax(${props.minMain}px, 1fr) ${props.handleSize}px ${endPx.value}px`
+		: `${startPx.value}px ${props.handleSize}px minmax(${props.minMain}px, 1fr)`;
+	const minSize = hasEnd.value
+		? `${props.minStart + props.minMain + props.minEnd + props.handleSize * 2}px`
+		: `${props.minStart + props.minMain + props.handleSize}px`;
+
+	if (isVertical.value) return {
+		gridTemplateRows: tracks,
+		minHeight: minSize,
+	};
+
+	return {
+		gridTemplateColumns: tracks,
+		minWidth: minSize,
+	};
+});
+
+watch(() => props.startSize, (value) => {
+	startPx.value = clamp(value, props.minStart, maxStartSize());
+	syncSizesToBounds();
+});
+
+watch(() => props.endSize, (value) => {
+	endPx.value = clamp(value, props.minEnd, maxEndSize());
+	syncSizesToBounds();
+});
+
+watch(() => props.orientation, () => {
+	nextTick(syncSizesToBounds);
+});
+
+onMounted(() => {
+	nextTick(syncSizesToBounds);
+
+	if (typeof ResizeObserver === 'undefined') return;
+	resizeObserver = new ResizeObserver(syncSizesToBounds);
+	if (root.value) resizeObserver.observe(root.value);
+});
+
+onBeforeUnmount(() => {
+	resizeObserver?.disconnect();
+	endResize();
+});
+
+function beginResize(pane, event) {
+	event.preventDefault();
+	dragging.value = {
+		pane,
+		position: pointerPosition(event),
+		start: startPx.value,
+		end: endPx.value,
+	};
+	window.addEventListener('pointermove', resizeFromPointer);
+	window.addEventListener('pointerup', endResize, { once: true });
+	document.body.style.cursor = resizeCursor.value;
+	document.body.style.userSelect = 'none';
+}
+
+function resizeFromPointer(event) {
+	if (!dragging.value) return;
+	const delta = pointerPosition(event) - dragging.value.position;
+
+	if (dragging.value.pane === 'start') {
+		updateStartSize(clamp(dragging.value.start + delta, props.minStart, maxStartSize()));
+	} else {
+		updateEndSize(clamp(dragging.value.end - delta, props.minEnd, maxEndSize()));
+	}
+}
+
+function endResize() {
+	window.removeEventListener('pointermove', resizeFromPointer);
+	document.body.style.cursor = '';
+	document.body.style.userSelect = '';
+	dragging.value = null;
+}
+
+function updateStartSize(value) {
+	startPx.value = value;
+	emit('update:startSize', value);
+	emit('resize', { startSize: startPx.value, endSize: endPx.value });
+}
+
+function updateEndSize(value) {
+	endPx.value = value;
+	emit('update:endSize', value);
+	emit('resize', { startSize: startPx.value, endSize: endPx.value });
+}
+
+function syncSizesToBounds() {
+	if (!root.value) return;
+
+	const nextStart = clamp(startPx.value, props.minStart, maxStartSize());
+	startPx.value = nextStart;
+
+	if (!hasEnd.value) return;
+	endPx.value = clamp(endPx.value, props.minEnd, maxEndSize());
+}
+
+function maxStartSize() {
+	const width = panelWidth();
+	const reserved = props.minMain + (hasEnd.value ? endPx.value + props.handleSize * 2 : props.handleSize);
+	return Math.max(props.minStart, width - reserved);
+}
+
+function maxEndSize() {
+	const width = panelWidth();
+	const reserved = props.minMain + startPx.value + props.handleSize * 2;
+	return Math.max(props.minEnd, width - reserved);
+}
+
+function panelWidth() {
+	if (isVertical.value) return root.value?.clientHeight || globalThis.innerHeight || 800;
+	return root.value?.clientWidth || globalThis.innerWidth || 1200;
+}
+
+function pointerPosition(event) {
+	return isVertical.value ? event.clientY : event.clientX;
+}
+
+function isDragging(pane) {
+	return dragging.value?.pane === pane;
+}
+
+function handleLabel(pane) {
+	if (!isVertical.value) return pane === 'start' ? 'Resize leading panel' : 'Resize trailing panel';
+	return pane === 'start' ? 'Resize upper panel' : 'Resize lower panel';
+}
+
+function clamp(value, min, max) {
+	return Math.min(Math.max(value, min), max);
+}
+</script>
+
+<template>
+	<div ref="root" :class="rootClass" :style="gridStyle">
+		<section class="min-h-0 min-w-0 overflow-hidden">
+			<slot name="start" />
+		</section>
+
+		<button
+			type="button"
+			:class="[handleBaseClass, handleClass, isDragging('start') && activeHandleClass]"
+			:aria-label="handleLabel('start')"
+			:aria-orientation="isVertical ? 'horizontal' : 'vertical'"
+			:data-dragging="isDragging('start')"
+			@pointerdown="beginResize('start', $event)"
+		>
+			<slot name="start-handle" :active="isDragging('start')" :orientation="orientation">
+				<span :class="[defaultIndicatorClass, handleIndicatorClass]"></span>
+			</slot>
+		</button>
+
+		<section class="min-h-0 min-w-0 overflow-hidden">
+			<slot />
+		</section>
+
+		<button
+			v-if="hasEnd"
+			type="button"
+			:class="[handleBaseClass, handleClass, isDragging('end') && activeHandleClass]"
+			:aria-label="handleLabel('end')"
+			:aria-orientation="isVertical ? 'horizontal' : 'vertical'"
+			:data-dragging="isDragging('end')"
+			@pointerdown="beginResize('end', $event)"
+		>
+			<slot name="end-handle" :active="isDragging('end')" :orientation="orientation">
+				<span :class="[defaultIndicatorClass, handleIndicatorClass]"></span>
+			</slot>
+		</button>
+
+		<section v-if="hasEnd" class="min-h-0 min-w-0 overflow-hidden">
+			<slot name="end" />
+		</section>
+	</div>
+</template>

package/src/pages/components/stepper/DomStepper.vue

@@ -0,0 +1,386 @@
+<script>
+/**
+ * @typedef {object} StepperItem
+ * @property {string|number} key Stable controlled step key.
+ * @property {string} label Human-readable step label.
+ * @property {string} [description] Optional supporting copy.
+ * @property {'complete'|'current'|'upcoming'|'error'} [status] Explicit state override.
+ * @property {boolean} [optional] Mark the step as optional.
+ * @property {boolean} [disabled] Prevent navigation to this step.
+ */
+
+/**
+ * @typedef {object} StepperChangePayload
+ * @property {StepperItem} item Selected step record.
+ * @property {string|number} key Selected step key.
+ * @property {number} index Selected step index.
+ * @property {string|number|null} previousKey Previously active step key.
+ */
+
+/**
+ * @typedef {object} StepperSlotPayload
+ * @property {StepperItem} item Step record.
+ * @property {string|number} key Step key.
+ * @property {number} index Step index.
+ * @property {'complete'|'current'|'upcoming'|'error'} state Resolved display state.
+ * @property {boolean} active Whether the step matches the controlled active key.
+ * @property {boolean} disabled Whether the step cannot currently be selected.
+ */
+
+export const stepperProps = {
+	items: {
+		type: Array,
+		default: () => [],
+		_edit: { typeRef: 'Array<StepperItem>', description: 'Ordered application-owned step records.' },
+	},
+	modelValue: {
+		type: [String, Number],
+		default: '',
+		_edit: { description: 'Controlled active step key. Defaults to the first enabled item.' },
+	},
+	orientation: {
+		type: String,
+		default: 'horizontal',
+		_edit: { options: ['horizontal', 'vertical'], description: 'Arrange steps across a row or down a column.' },
+	},
+	clickable: {
+		type: Boolean,
+		default: true,
+		_edit: { description: 'Allow enabled step indicators and labels to change the active key.' },
+	},
+	linear: {
+		type: Boolean,
+		default: false,
+		_edit: { description: 'Prevent navigation beyond the next incomplete step.' },
+	},
+	showDescriptions: {
+		type: Boolean,
+		default: true,
+		_edit: { description: 'Show supporting descriptions when supplied.' },
+	},
+	size: {
+		type: String,
+		default: 'md',
+		_edit: { options: ['sm', 'md'], description: 'Indicator and label density.' },
+	},
+	ariaLabel: {
+		type: String,
+		default: 'Progress',
+		_edit: { description: 'Accessible label for the step navigation.' },
+	},
+};
+</script>
+
+<script setup>
+import { computed, ref } from 'vue';
+
+defineOptions({
+	__doc: {
+		name: 'Stepper',
+		tag: '<DomStepper>',
+		description: 'Controlled horizontal or vertical progress navigation for multi-step application workflows.',
+		icon: 'M5 12h14M6 12a2 2 0 1 0 0 .01M12 12a2 2 0 1 0 0 .01M18 12a2 2 0 1 0 0 .01',
+		events: [
+			{ name: 'update:modelValue', payload: 'string | number', description: 'Fired when an enabled step is selected.' },
+			{ name: 'change', payload: 'StepperChangePayload', typeRef: 'StepperChangePayload', description: 'Fired with the selected step, key, index, and previous key.' },
+		],
+		slots: [
+			{ name: 'step', payload: 'StepperSlotPayload', typeRef: 'StepperSlotPayload', description: 'Replace the label and description while retaining navigation and progress structure.' },
+			{ name: 'indicator', payload: 'StepperSlotPayload', typeRef: 'StepperSlotPayload', description: 'Replace the numbered, completed, or error indicator.' },
+			{ name: 'separator', payload: '{ index, previous, next }', description: 'Replace the connector between adjacent steps.' },
+		],
+		keyboard: [
+			{ keys: '← / →', action: 'Move between enabled horizontal steps.' },
+			{ keys: '↑ / ↓', action: 'Move between enabled vertical steps.' },
+			{ keys: 'Home / End', action: 'Move to the first or last enabled step.' },
+		],
+	},
+});
+
+const props = defineProps(stepperProps);
+const emit = defineEmits(['update:modelValue', 'change']);
+
+const root = ref(null);
+const normalizedItems = computed(getNormalizedItems);
+const activeIndex = computed(getActiveIndex);
+const rootClass = computed(getRootClass);
+
+/**
+ * Normalizes every supplied step and its stable key.
+ *
+ * @returns {Array<StepperItem>} Safe step records.
+ */
+function getNormalizedItems() {
+	return (Array.isArray(props.items) ? props.items : [])
+		.filter(hasStepKey)
+		.map(normalizeStep);
+}
+
+/**
+ * Reports whether a candidate step has a stable key.
+ *
+ * @param {StepperItem} item Candidate step.
+ * @returns {boolean} True when the step can be controlled.
+ */
+function hasStepKey(item) {
+	return Boolean(item && item.key !== null && item.key !== undefined && item.key !== '');
+}
+
+/**
+ * Adds safe defaults to one step record.
+ *
+ * @param {StepperItem} item Source step.
+ * @param {number} index Source step index.
+ * @returns {StepperItem} Normalized step.
+ */
+function normalizeStep(item, index) {
+	return {
+		...item,
+		label: item.label || `Step ${index + 1}`,
+		description: item.description || '',
+	};
+}
+
+/**
+ * Finds the controlled active step or the first enabled step.
+ *
+ * @returns {number} Active step index or -1.
+ */
+function getActiveIndex() {
+	const controlledIndex = normalizedItems.value.findIndex(matchesModelValue);
+	if (controlledIndex >= 0) return controlledIndex;
+	return normalizedItems.value.findIndex(isEnabledStep);
+}
+
+/**
+ * Reports whether a step matches the controlled active key.
+ *
+ * @param {StepperItem} item Candidate step.
+ * @returns {boolean} True when keys match.
+ */
+function matchesModelValue(item) {
+	return String(item.key) === String(props.modelValue);
+}
+
+/**
+ * Reports whether a step is enabled.
+ *
+ * @param {StepperItem} item Candidate step.
+ * @returns {boolean} True when navigation is allowed.
+ */
+function isEnabledStep(item) {
+	return !item.disabled;
+}
+
+/**
+ * Builds orientation-aware root classes.
+ *
+ * @returns {string} Step list classes.
+ */
+function getRootClass() {
+	return props.orientation === 'vertical'
+		? 'flex flex-col'
+		: 'flex min-w-max items-start';
+}
+
+/**
+ * Resolves derived or explicitly supplied state for one step.
+ *
+ * @param {StepperItem} item Step record.
+ * @param {number} index Step index.
+ * @returns {'complete'|'current'|'upcoming'|'error'} Display state.
+ */
+function stepState(item, index) {
+	if (['complete', 'current', 'upcoming', 'error'].includes(item.status)) return item.status;
+	if (index < activeIndex.value) return 'complete';
+	if (index === activeIndex.value) return 'current';
+	return 'upcoming';
+}
+
+/**
+ * Reports whether a step can be selected under current navigation rules.
+ *
+ * @param {StepperItem} item Step record.
+ * @param {number} index Step index.
+ * @returns {boolean} True when the step is interactive.
+ */
+function canSelect(item, index) {
+	if (!props.clickable || item.disabled) return false;
+	if (!props.linear) return true;
+	return index <= activeIndex.value + 1;
+}
+
+/**
+ * Selects an enabled step and emits controlled state.
+ *
+ * @param {StepperItem} item Step record.
+ * @param {number} index Step index.
+ * @returns {void}
+ */
+function selectStep(item, index) {
+	if (!canSelect(item, index)) return;
+	const previousKey = normalizedItems.value[activeIndex.value]?.key ?? null;
+	emit('update:modelValue', item.key);
+	emit('change', { item, key: item.key, index, previousKey });
+}
+
+/**
+ * Handles directional and boundary keyboard navigation.
+ *
+ * @param {KeyboardEvent} event Native keyboard event.
+ * @param {number} index Focused step index.
+ * @returns {void}
+ */
+function onStepKeydown(event, index) {
+	const direction = keyboardDirection(event.key);
+	if (direction === null) return;
+	event.preventDefault();
+	const nextIndex = direction === 'first'
+		? findEnabledIndex(0, 1)
+		: direction === 'last'
+			? findEnabledIndex(normalizedItems.value.length - 1, -1)
+			: findEnabledIndex(index + direction, direction);
+	if (nextIndex < 0) return;
+	focusStep(nextIndex);
+}
+
+/**
+ * Maps supported keys to a navigation direction.
+ *
+ * @param {string} key Keyboard key.
+ * @returns {number|'first'|'last'|null} Navigation direction.
+ */
+function keyboardDirection(key) {
+	if (key === 'Home') return 'first';
+	if (key === 'End') return 'last';
+	if (props.orientation === 'vertical' && key === 'ArrowUp') return -1;
+	if (props.orientation === 'vertical' && key === 'ArrowDown') return 1;
+	if (props.orientation === 'horizontal' && key === 'ArrowLeft') return -1;
+	if (props.orientation === 'horizontal' && key === 'ArrowRight') return 1;
+	return null;
+}
+
+/**
+ * Finds the next enabled and selectable step in one direction.
+ *
+ * @param {number} startIndex Initial candidate index.
+ * @param {number} direction Direction increment.
+ * @returns {number} Matching index or -1.
+ */
+function findEnabledIndex(startIndex, direction) {
+	for (let index = startIndex; index >= 0 && index < normalizedItems.value.length; index += direction) {
+		if (canSelect(normalizedItems.value[index], index)) return index;
+	}
+	return -1;
+}
+
+/**
+ * Focuses and activates one step button.
+ *
+ * @param {number} index Target step index.
+ * @returns {void}
+ */
+function focusStep(index) {
+	const button = root.value?.querySelector(`[data-step-index="${index}"]`);
+	button?.focus();
+	selectStep(normalizedItems.value[index], index);
+}
+
+/**
+ * Builds the public slot payload for one step.
+ *
+ * @param {StepperItem} item Step record.
+ * @param {number} index Step index.
+ * @returns {Record<string, unknown>} Step slot payload.
+ */
+function slotPayload(item, index) {
+	return {
+		item,
+		key: item.key,
+		index,
+		state: stepState(item, index),
+		active: index === activeIndex.value,
+		disabled: !canSelect(item, index),
+	};
+}
+
+/**
+ * Builds semantic classes for a step indicator.
+ *
+ * @param {StepperItem} item Step record.
+ * @param {number} index Step index.
+ * @returns {string} Indicator classes.
+ */
+function indicatorClass(item, index) {
+	const state = stepState(item, index);
+	if (state === 'complete') return 'border-primary bg-primary text-primary-fg';
+	if (state === 'current') return 'border-primary bg-canvas text-primary ring-4 ring-primary/10';
+	if (state === 'error') return 'border-destructive bg-destructive/10 text-destructive';
+	return 'border-border bg-secondary text-muted-fg';
+}
+
+/**
+ * Builds semantic classes for a connector after one step.
+ *
+ * @param {number} index Step index before the connector.
+ * @returns {string} Connector classes.
+ */
+function separatorClass(index) {
+	const complete = index < activeIndex.value;
+	if (props.orientation === 'vertical') {
+		return `ml-[0.9375rem] h-8 w-px ${complete ? 'bg-primary' : 'bg-border'}`;
+	}
+	return `mt-[0.9375rem] h-px min-w-6 flex-1 ${complete ? 'bg-primary' : 'bg-border'}`;
+}
+
+/**
+ * Returns the compact indicator dimension for the selected size.
+ *
+ * @returns {string} Indicator size classes.
+ */
+function indicatorSizeClass() {
+	return props.size === 'sm' ? 'size-7 text-xs' : 'size-8 text-sm';
+}
+</script>
+
+<template>
+	<nav :aria-label="ariaLabel" class="min-w-0 overflow-x-auto">
+		<ol ref="root" :class="rootClass">
+			<template v-for="(item, index) in normalizedItems" :key="item.key">
+				<li class="flex min-w-0" :class="orientation === 'vertical' ? 'flex-col' : 'min-w-[8rem] flex-1 flex-row'">
+					<div class="flex min-w-0" :class="orientation === 'vertical' ? 'items-start gap-3' : 'flex-col items-center px-1 text-center'">
+						<button
+							type="button"
+							class="group flex min-w-0 focus-visible:outline-none"
+							:class="orientation === 'vertical' ? 'items-start gap-3 text-left' : 'flex-col items-center text-center'"
+							:data-step-index="index"
+							:aria-current="index === activeIndex ? 'step' : undefined"
+							:aria-disabled="!canSelect(item, index) ? 'true' : undefined"
+							:disabled="!canSelect(item, index)"
+							@click="selectStep(item, index)"
+							@keydown="onStepKeydown($event, index)"
+						>
+							<slot name="indicator" v-bind="slotPayload(item, index)">
+								<span class="grid shrink-0 place-items-center rounded-full border font-semibold transition group-focus-visible:ring-2 group-focus-visible:ring-ring" :class="[indicatorSizeClass(), indicatorClass(item, index)]">
+									<svg v-if="stepState(item, index) === 'complete'" viewBox="0 0 24 24" class="size-4" fill="none" aria-hidden="true"><path d="m6.5 12.5 3.2 3.2 7.8-8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" /></svg>
+									<span v-else-if="stepState(item, index) === 'error'" aria-hidden="true">!</span>
+									<span v-else>{{ index + 1 }}</span>
+								</span>
+							</slot>
+							<slot name="step" v-bind="slotPayload(item, index)">
+								<span class="min-w-0" :class="orientation === 'vertical' ? 'pt-0.5' : 'mt-2'">
+									<span class="block text-sm font-semibold" :class="index === activeIndex ? 'text-canvas-fg' : 'text-muted-fg'">{{ item.label }}</span>
+									<span v-if="item.optional" class="mt-0.5 block text-[11px] text-muted-fg">Optional</span>
+									<span v-if="showDescriptions && item.description" class="mt-1 block text-xs leading-5 text-muted-fg">{{ item.description }}</span>
+								</span>
+							</slot>
+						</button>
+					</div>
+					<slot v-if="index < normalizedItems.length - 1" name="separator" :index="index" :previous="item" :next="normalizedItems[index + 1]">
+						<span aria-hidden="true" :class="separatorClass(index)"></span>
+					</slot>
+				</li>
+			</template>
+		</ol>
+	</nav>
+</template>