@getdom/studio 0.1.0

package/src/pages/components/toast/useToasts.js

@@ -0,0 +1,237 @@
+import { markRaw, ref, toRaw } from 'vue';
+import DomToastItem from './DomToastItem.vue';
+
+/**
+ * @typedef {import('vue').Component} ToastComponent
+ * @typedef {Record<string, unknown>} ToastProps
+ *
+ * @typedef {Object} ToastOptions
+ * @property {string} [id] Stable toast id. Generated automatically when omitted.
+ * @property {'default'|'success'|'danger'|'warning'|string} [tone] Visual tone used by the default toast item.
+ * @property {number} [duration] Auto-dismiss delay in milliseconds. Use 0 for manual dismissal.
+ * @property {boolean} [dismissible] Set false to hide the default dismiss button.
+ * @property {string} [title] Default toast title.
+ * @property {string} [description] Default toast description.
+ * @property {ToastComponent|string} [component] Component used for a custom toast template.
+ * @property {ToastProps} [props] Props passed to a custom toast template.
+ *
+ * @typedef {Object} ToastApi
+ * @property {import('vue').Ref<ToastOptions[]>} toasts Reactive toast array for <DomToastStack>.
+ * @property {(input?: string|ToastOptions|ToastComponent, propsOrOverrides?: ToastProps|ToastOptions, options?: ToastOptions) => string} show Show a toast and return its id.
+ * @property {(input?: string|ToastOptions|ToastComponent, propsOrOverrides?: ToastProps|ToastOptions, options?: ToastOptions) => string} normal Show a default-tone toast and return its id.
+ * @property {(input?: string|ToastOptions|ToastComponent, propsOrOverrides?: ToastProps|ToastOptions, options?: ToastOptions) => string} success Show a success-tone toast and return its id.
+ * @property {(input?: string|ToastOptions|ToastComponent, propsOrOverrides?: ToastProps|ToastOptions, options?: ToastOptions) => string} danger Show a danger-tone toast and return its id.
+ * @property {(id: string) => void} dismiss Remove a toast by id.
+ * @property {() => void} clear Remove all toasts.
+ */
+
+/**
+ * Creates a small controlled toast store for <DomToastStack>.
+ *
+ * @param {ToastOptions} [defaults] Options applied to every toast shown by this store.
+ * @returns {ToastApi}
+ */
+export function useToasts(defaults = {}) {
+	const toasts = ref([]);
+
+	/**
+	 * Show a toast and return its generated id.
+	 *
+	 * Plain strings and toast objects render with the default ToastItem:
+	 * `show('Saved', { description: 'Changes stored.' })`.
+	 *
+	 * Vue components render as template toasts:
+	 * `show(AvatarToast, { name: 'Maya' }, { duration: 0 })`.
+	 *
+	 * @param {string|ToastOptions|ToastComponent} [input] Toast text, full toast object, or Vue component.
+	 * @param {ToastProps|ToastOptions} [propsOrOverrides] Props for component toasts, or option overrides for default toasts.
+	 * @param {ToastOptions} [options] Options for component toasts.
+	 * @returns {string}
+	 */
+	function show(input = {}, propsOrOverrides = {}, options = {}) {
+		const toast = normalizeToast(input, propsOrOverrides, options, defaults);
+		toasts.value = [...toasts.value, toast];
+		return toast.id;
+	}
+
+	/**
+	 * Show a default-tone toast. Supports the same arguments as show().
+	 *
+	 * @param {string|ToastOptions|ToastComponent} [input]
+	 * @param {ToastProps|ToastOptions} [propsOrOverrides]
+	 * @param {ToastOptions} [options]
+	 * @returns {string}
+	 */
+	function normal(input, propsOrOverrides, options) {
+		return showWithTone('default', input, propsOrOverrides, options);
+	}
+
+	/**
+	 * Show a success-tone toast. Supports the same arguments as show().
+	 *
+	 * @param {string|ToastOptions|ToastComponent} [input]
+	 * @param {ToastProps|ToastOptions} [propsOrOverrides]
+	 * @param {ToastOptions} [options]
+	 * @returns {string}
+	 */
+	function success(input, propsOrOverrides, options) {
+		return showWithTone('success', input, propsOrOverrides, options);
+	}
+
+	/**
+	 * Show a danger-tone toast. Supports the same arguments as show().
+	 *
+	 * @param {string|ToastOptions|ToastComponent} [input]
+	 * @param {ToastProps|ToastOptions} [propsOrOverrides]
+	 * @param {ToastOptions} [options]
+	 * @returns {string}
+	 */
+	function danger(input, propsOrOverrides, options) {
+		return showWithTone('danger', input, propsOrOverrides, options);
+	}
+
+	/**
+	 * Remove a toast by id.
+	 *
+	 * @param {string} id
+	 * @returns {void}
+	 */
+	function dismiss(id) {
+		toasts.value = toasts.value.filter((toast) => toast.id !== id);
+	}
+
+	/**
+	 * Remove all visible toasts.
+	 *
+	 * @returns {void}
+	 */
+	function clear() {
+		toasts.value = [];
+	}
+
+	return {
+		toasts,
+		show,
+		normal,
+		success,
+		danger,
+		dismiss,
+		clear,
+	};
+
+	/**
+	 * Show a toast while forcing a specific tone into the supported argument shapes.
+	 *
+	 * @param {string} tone Tone to apply to the toast.
+	 * @param {string|ToastOptions|ToastComponent} [input] Toast text, full toast object, or Vue component.
+	 * @param {ToastProps|ToastOptions} [propsOrOverrides] Props for component toasts, or option overrides for default toasts.
+	 * @param {ToastOptions} [options] Options for component toasts.
+	 * @returns {string}
+	 */
+	function showWithTone(tone, input, propsOrOverrides = {}, options = {}) {
+		const toastOptions = tone === 'default'
+			? { tone, ...options }
+			: { ...options, tone };
+		const toastOverrides = tone === 'default'
+			? { tone, ...propsOrOverrides }
+			: { ...propsOrOverrides, tone };
+		if (isToastComponent(input)) return show(input, propsOrOverrides, toastOptions);
+		return show(input, toastOverrides);
+	}
+}
+
+/**
+ * Normalizes supported show() inputs into the controlled toast record shape.
+ *
+ * @param {string|ToastOptions|ToastComponent} input Toast text, full toast object, or Vue component.
+ * @param {ToastProps|ToastOptions} propsOrOverrides Props for component toasts, or option overrides for default toasts.
+ * @param {ToastOptions} options Options for component toasts.
+ * @param {ToastOptions} defaults Options applied to every toast shown by this store.
+ * @returns {ToastOptions & { id: string }}
+ */
+function normalizeToast(input, propsOrOverrides, options, defaults) {
+	if (isToastComponent(input)) {
+		return {
+			id: createToastId(),
+			tone: 'default',
+			...defaults,
+			...options,
+			component: rawToastComponent(input),
+			props: propsOrOverrides || {},
+		};
+	}
+
+	const base = typeof input === 'string' ? { title: input } : { ...input };
+	const toast = {
+		id: createToastId(),
+		tone: 'default',
+		...defaults,
+		...base,
+		...propsOrOverrides,
+	};
+
+	return withDefaultComponent(toast);
+}
+
+/**
+ * Ensures component references stay out of Vue's reactive proxy conversion.
+ *
+ * @param {ToastOptions} toast Toast record to normalize.
+ * @returns {ToastOptions}
+ */
+function withDefaultComponent(toast) {
+	if (toast.component) {
+		return {
+			...toast,
+			component: rawToastComponent(toast.component),
+			props: toast.props || {},
+		};
+	}
+	return {
+		...toast,
+		component: rawToastComponent(DomToastItem),
+		props: {
+			title: toast.title,
+			description: toast.description,
+			tone: toast.tone,
+			dismissible: toast.dismissible !== false,
+			...(toast.props || {}),
+		},
+	};
+}
+
+/**
+ * Reports whether a value looks like a Vue component that can render a toast.
+ *
+ * @param {unknown} value Value to inspect.
+ * @returns {boolean}
+ */
+function isToastComponent(value) {
+	return Boolean(
+		value
+		&& (typeof value === 'function'
+			|| (typeof value === 'object'
+				&& (value.setup || value.render || value.template || value.__name || value.__file))),
+	);
+}
+
+/**
+ * Marks a Vue component reference as raw before storing it in the reactive toast array.
+ *
+ * @param {ToastComponent|string} component Component reference to store.
+ * @returns {ToastComponent|string}
+ */
+function rawToastComponent(component) {
+	if (!isToastComponent(component)) return component;
+	return markRaw(toRaw(component));
+}
+
+/**
+ * Creates a stable id for a toast that did not provide one.
+ *
+ * @returns {string}
+ */
+function createToastId() {
+	if (typeof crypto !== 'undefined' && crypto.randomUUID) return crypto.randomUUID();
+	return `toast-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}

package/src/pages/components/toolbar/DomToolbar.vue

@@ -0,0 +1,158 @@
+<script setup>
+import { computed } from 'vue';
+
+const toolbarControlHeights = {
+	xs: '1.75rem',
+	sm: '2rem',
+	md: '2.5rem',
+	lg: '3rem',
+};
+const toolbarControlRadiusValues = {
+	none: '0',
+	sm: '0.125rem',
+	md: '0.375rem',
+	lg: '0.5rem',
+	xl: '0.75rem',
+	'2xl': '1rem',
+	full: '9999px',
+};
+const toolbarSkinClasses = {
+	control: 'skin-control rounded-2xl p-1',
+	card: 'skin-card rounded-2xl p-1',
+	flat: 'bg-transparent',
+	none: '',
+};
+
+defineOptions({
+	__doc: {
+		name: 'Toolbar',
+		tag: '<DomToolbar>',
+		description: 'A compact action surface for icon buttons, segmented controls, filters, and overflow menus.',
+		slots: [
+			{ name: '(default)', description: 'Toolbar controls.' },
+		],
+	},
+});
+
+const props = defineProps({
+	as: {
+		type: String,
+		default: 'div',
+		_edit: { description: 'Element to render.' },
+	},
+	label: {
+		type: String,
+		default: 'Toolbar',
+		_edit: { description: 'Accessible toolbar label.' },
+	},
+	orientation: {
+		type: String,
+		default: 'horizontal',
+		_edit: { options: ['horizontal', 'vertical'], description: 'Toolbar direction.' },
+	},
+	align: {
+		type: String,
+		default: 'start',
+		_edit: { options: ['start', 'center', 'end', 'between'], description: 'Control alignment.' },
+	},
+	wrap: {
+		type: Boolean,
+		default: true,
+		_edit: { description: 'Allow controls to wrap on narrow screens.' },
+	},
+	skin: {
+		type: [String, Boolean],
+		default: null,
+		_edit: { options: ['control', 'card', 'flat', 'none', false], description: 'Toolbar surface skin. Use flat when the parent supplies border, padding, or background chrome.' },
+	},
+	inset: {
+		type: Boolean,
+		default: false,
+		_edit: { description: 'Use card skin instead of control skin. Prefer skin="card" for new usage.' },
+	},
+	controlSize: {
+		type: String,
+		default: 'md',
+		_edit: { options: ['xs', 'sm', 'md', 'lg'], description: 'Shared toolbar control height for buttons, dropdowns, and select triggers.' },
+	},
+	controlHeight: {
+		type: String,
+		default: '',
+		_edit: { description: 'Explicit CSS height for toolbar controls. Overrides controlSize when provided.' },
+	},
+	controlRadius: {
+		type: String,
+		default: 'full',
+		_edit: { options: ['none', 'sm', 'md', 'lg', 'xl', '2xl', 'full'], description: 'Shared corner radius for toolbar buttons, dropdowns, and select triggers.' },
+	},
+});
+
+/**
+ * Resolves the toolbar skin while preserving the older inset prop contract.
+ *
+ * @returns {'control'|'card'|'flat'|'none'} Resolved toolbar skin.
+ */
+function resolveToolbarSkin() {
+	if (props.skin === false || props.skin === 'none') return 'none';
+	if (props.skin) return props.skin;
+	return props.inset ? 'card' : 'control';
+}
+
+/**
+ * Resolves the CSS height used to normalize controls inside the toolbar.
+ *
+ * @returns {string} CSS length for toolbar controls.
+ */
+function resolveToolbarControlHeight() {
+	return props.controlHeight || toolbarControlHeights[props.controlSize] || toolbarControlHeights.md;
+}
+
+/**
+ * Resolves the CSS border radius used to normalize controls inside the toolbar.
+ *
+ * @returns {string} CSS radius for toolbar controls.
+ */
+function resolveToolbarControlRadius() {
+	return toolbarControlRadiusValues[props.controlRadius] || toolbarControlRadiusValues.full;
+}
+
+const resolvedSkin = computed(resolveToolbarSkin);
+const classes = computed(() => [
+	'dom-toolbar inline-flex gap-1',
+	toolbarSkinClasses[resolvedSkin.value] ?? toolbarSkinClasses.control,
+	props.orientation === 'vertical' ? 'flex-col' : 'flex-row items-center',
+	props.wrap && props.orientation !== 'vertical' && 'flex-wrap',
+	{
+		start: 'justify-start',
+		center: 'justify-center',
+		end: 'justify-end',
+		between: 'justify-between',
+	}[props.align] || 'justify-start',
+]);
+const styles = computed(() => ({
+	'--dom-toolbar-control-height': resolveToolbarControlHeight(),
+	'--dom-toolbar-control-radius': resolveToolbarControlRadius(),
+}));
+</script>
+
+<template>
+	<component :is="as" role="toolbar" :aria-label="label" :aria-orientation="orientation" :class="classes" :style="styles">
+		<slot />
+	</component>
+</template>
+
+<style scoped>
+.dom-toolbar {
+	--dom-toolbar-control-height: 2.5rem;
+	--dom-toolbar-control-radius: 9999px;
+}
+
+.dom-toolbar :deep(button),
+.dom-toolbar :deep([role="button"]),
+.dom-toolbar :deep([slot="trigger"]),
+.dom-toolbar :deep(.dom-toolbar-control) {
+	border-radius: var(--dom-toolbar-control-radius);
+	height: var(--dom-toolbar-control-height);
+	min-height: var(--dom-toolbar-control-height);
+}
+</style>

package/src/pages/components/tooltip/DomTooltip.vue

@@ -0,0 +1,69 @@
+<script setup>
+import { onMounted } from 'vue';
+
+const props = defineProps({
+	for: {
+		type: String,
+		default: '',
+		_edit: { description: 'ID of an existing trigger element. Leave empty to wrap the trigger in the default slot.' },
+	},
+	text: {
+		type: String,
+		required: true,
+		_edit: { description: 'Tooltip body. Keep it short — one line works best.' },
+	},
+	placement: {
+		type: String,
+		default: 'top',
+		_edit: {
+			options: ['top', 'bottom', 'left', 'right'],
+			description: 'Position of the bubble relative to the trigger.',
+		},
+	},
+	delay: {
+		type: Number,
+		default: 120,
+		_edit: { description: 'Open delay in milliseconds — stops flicker when sweeping the cursor across.' },
+	},
+	offset: {
+		type: Number,
+		default: 6,
+		_edit: { description: 'Gap in pixels between the trigger and tooltip.' },
+	},
+	collisionPadding: {
+		type: Number,
+		default: 8,
+		_edit: { description: 'Viewport padding used when the tooltip flips or shifts.' },
+	},
+	floatingMode: {
+		type: String,
+		default: 'viewport',
+		_edit: { options: ['viewport', 'anchor'], description: 'viewport keeps the tooltip inside the browser; anchor keeps it attached while scrolling.' },
+	},
+});
+
+/**
+ * Register the headless tooltip element after Vue mounts its target markup.
+ *
+ * @returns {Promise<void>}
+ */
+async function registerTooltipElement() {
+	await import('../../lib/headless/tooltip.js');
+}
+
+onMounted(registerTooltipElement);
+</script>
+
+<template>
+	<dom-tooltip
+		:for="props.for || undefined"
+		:text="text"
+		:placement="placement"
+		:delay="delay"
+		:offset="offset"
+		:collision-padding="collisionPadding"
+		:floating-mode="floatingMode"
+	>
+		<slot />
+	</dom-tooltip>
+</template>

package/src/pages/components/tooltip/vDomTooltip.js

@@ -0,0 +1,106 @@
+import { attachTooltip } from '../../lib/headless/tooltip-controller.js';
+
+const controllers = new WeakMap();
+const placementModifiers = ['top', 'right', 'bottom', 'left'];
+
+/**
+ * Resolve the first supported placement modifier from a Vue directive binding.
+ *
+ * @param {Record<string, boolean>} modifiers Vue directive modifiers.
+ * @returns {'top' | 'right' | 'bottom' | 'left' | undefined} Requested placement.
+ */
+function placementFromModifiers(modifiers) {
+	return placementModifiers.find((placement) => modifiers[placement]);
+}
+
+/**
+ * Normalize a Vue directive binding into the shared tooltip controller shape.
+ *
+ * String bindings are shorthand for tooltip text. Object bindings may use
+ * either `label` or `text`, and falsey or disabled bindings remove behaviour
+ * without unmounting the target element.
+ *
+ * @param {unknown} value Vue directive binding value.
+ * @param {Record<string, boolean>} modifiers Vue directive modifiers.
+ * @returns {Record<string, unknown> | null} Controller options or null when disabled.
+ */
+function normalizeDirectiveValue(value, modifiers = {}) {
+	const placement = placementFromModifiers(modifiers);
+
+	if (typeof value === 'string') {
+		if (!value.trim()) return null;
+		return {
+			text: value,
+			...(placement ? { placement } : {}),
+		};
+	}
+	if (!value || typeof value !== 'object' || value.disabled) return null;
+	const text = String(value.text ?? value.label ?? '');
+	if (!text.trim()) return null;
+	return {
+		...value,
+		text,
+		...(placement ? { placement } : {}),
+	};
+}
+
+/**
+ * Attach, update, or remove tooltip behaviour for one directive target.
+ *
+ * @param {HTMLElement} element Vue directive target element.
+ * @param {unknown} value Current directive binding value.
+ * @param {Record<string, boolean>} modifiers Vue directive modifiers.
+ * @returns {void}
+ */
+function syncDirectiveTooltip(element, value, modifiers = {}) {
+	const options = normalizeDirectiveValue(value, modifiers);
+	const controller = controllers.get(element);
+
+	if (!options) {
+		controller?.destroy();
+		controllers.delete(element);
+		return;
+	}
+
+	if (controller) {
+		controller.update(options);
+		return;
+	}
+
+	controllers.set(element, attachTooltip(element, options, element));
+}
+
+export const vDomTooltip = {
+	/**
+	 * Register tooltip behaviour directly on the mounted element.
+	 *
+	 * @param {HTMLElement} element Vue directive target element.
+	 * @param {{ value: unknown, modifiers: Record<string, boolean> }} binding Vue directive binding.
+	 * @returns {void}
+	 */
+	mounted(element, binding) {
+		syncDirectiveTooltip(element, binding.value, binding.modifiers);
+	},
+
+	/**
+	 * Synchronize content, placement, and enabled state after Vue updates.
+	 *
+	 * @param {HTMLElement} element Vue directive target element.
+	 * @param {{ value: unknown, modifiers: Record<string, boolean> }} binding Vue directive binding.
+	 * @returns {void}
+	 */
+	updated(element, binding) {
+		syncDirectiveTooltip(element, binding.value, binding.modifiers);
+	},
+
+	/**
+	 * Release listeners, ARIA wiring, and the bubble before unmount.
+	 *
+	 * @param {HTMLElement} element Vue directive target element.
+	 * @returns {void}
+	 */
+	beforeUnmount(element) {
+		controllers.get(element)?.destroy();
+		controllers.delete(element);
+	},
+};