bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/BaseDialog.md

@@ -0,0 +1,610 @@
+# BaseDialog
+
+## Template & Script
+
+```vue
+<template>
+	<dialog
+		ref="dialog"
+		:aria-describedby="
+			hasRenderedAtLeastOnce && description ? descriptionId : undefined
+		"
+		:aria-labelledby="
+			hasRenderedAtLeastOnce && title && !hideHeader ? titleId : undefined
+		"
+		:aria-live="model ? 'polite' : 'off'"
+		class="bb-base-dialog"
+		:class="
+			[
+				{
+					'bb-base-dialog--open': model,
+					'bb-base-dialog--fullscreen': isFullscreen,
+					'bb-base-dialog--compact': compact,
+					'bb-base-dialog--deny-close': denyClose,
+				},
+				overlayClasses,
+				panelClasses,
+			].flat()
+		"
+		:inert="!model"
+		:style="{
+			'--max-width': maxWidth,
+			'--transition-duration': `${props.transitionDuration}ms`,
+		}"
+		@cancel="cancelableClose"
+		@click.self="cancelableClose"
+	>
+		<template v-if="hasRenderedAtLeastOnce">
+			<div v-if="!hideHeader" ref="header" class="bb-base-dialog__header">
+				<slot :close="close" name="header" :title="title" :title-id="titleId">
+					<span :id="titleId" class="bb-base-dialog__title">
+						<slot name="title" :text="title">{{ title }}</slot>
+					</span>
+					<span class="bb-base-dialog__close">
+						<button
+							v-if="showClose"
+							:aria-label="closeLabel"
+							:disabled="props.disabled"
+							type="button"
+							@click="close"
+						>
+							<slot name="close">
+								<span class="bb-base-dialog__close-icon"
+									><svg
+										aria-hidden="true"
+										fill="none"
+										viewBox="0 0 24 24"
+										xmlns="http://www.w3.org/2000/svg"
+									>
+										<path
+											d="M23 23L1 1M23 1L1 23"
+											stroke="currentColor"
+											stroke-linecap="round"
+											stroke-width="3"
+										/>
+									</svg>
+								</span>
+							</slot>
+						</button>
+					</span>
+				</slot>
+			</div>
+			<div ref="body" class="bb-base-dialog__body scrollbar-border">
+				<div class="bb-base-dialog__body-content">
+					<slot
+						:description-id="descriptionId"
+						name="description"
+						:text="description"
+						><div
+							v-if="description"
+							:id="descriptionId"
+							class="bb-base-dialog__description sr-only"
+						>
+							{{ description }}
+						</div>
+					</slot>
+					<slot :close="close" :title-id="titleId"></slot>
+				</div>
+			</div>
+
+			<div ref="footer" class="bb-base-dialog__footer">
+				<slot name="footer"></slot>
+			</div>
+		</template>
+	</dialog>
+</template>
+
+<script setup lang="ts">
+import { computed, nextTick, onMounted, ref, watch, type Ref } from 'vue';
+import { parseSize } from '@/utilities/functions/parseSize';
+import { useId } from '@/composables/useId';
+import { useLocale } from '@/composables/useLocale';
+import { useMobile } from '@/composables/useMobile';
+import { useUntil } from '@/composables/useUntil';
+import { wait } from '@/utilities/functions/wait';
+import { _config } from '@/composables/useBbConfig';
+import type {
+	BaseDialogProps,
+	BaseDialogEvents,
+	BaseDialogSlots,
+} from './types';
+
+const props = withDefaults(defineProps<BaseDialogProps>(), {
+	showClose: true,
+	size: 'sm',
+	panelClasses: () => [],
+	overlayClasses: () => [],
+	transitionDuration: 300,
+});
+
+const emit = defineEmits<BaseDialogEvents>();
+
+defineSlots<BaseDialogSlots>();
+
+const model = defineModel<boolean>({ default: false });
+
+const { t } = useLocale();
+const closeLabel = computed(
+	() => props.closeLabel || t('dialog.closeLabel').value
+);
+
+const dialog = ref<HTMLDialogElement | null>(null);
+const hasRenderedAtLeastOnce: Ref<boolean> = useUntil(
+	() => model.value || props.eager,
+	{
+		initialValue: model.value || props.eager,
+	}
+);
+
+const titleId = `title_${useId().id.value}`;
+const descriptionId = `description_${useId().id.value}`;
+
+const handleKeyDown = (e: KeyboardEvent) => {
+	if (e.key !== 'Escape') return;
+	e.stopImmediatePropagation();
+	if (props.disabled || props.persistent) {
+		e.preventDefault();
+		denyClose.value = true;
+		wait(200).then(() => {
+			denyClose.value = false;
+		});
+		return false;
+	}
+};
+const openedTimes = ref(0);
+const toggleDialog = async (value: boolean) => {
+	if (value) {
+		emit('show');
+		openedTimes.value++;
+		// On first opening set variable for scrollbar width that is used to pad the body
+		if (
+			window.globalThis?.document &&
+			!document.documentElement.style.getPropertyValue('--scrollbar-width')
+		) {
+			document.documentElement.style.setProperty(
+				'--scrollbar-width',
+				`${getScrollBarWidth()}px`
+			);
+		}
+		document.addEventListener('keydown', handleKeyDown, { capture: true });
+		await nextTick();
+		dialog.value?.showModal();
+		if (props.focusTarget) {
+			const element = dialog.value?.querySelector(props.focusTarget!);
+			if (element && element instanceof HTMLElement) {
+				element.focus();
+			}
+		}
+		emit('shown');
+	} else {
+		emit('hide');
+		const currentOpenedTimes = openedTimes.value;
+		await wait(props.transitionDuration);
+		// If the dialog was opened again during the transition, do not close it
+		if (currentOpenedTimes !== openedTimes.value) return;
+		if (window.globalThis?.document) {
+			document.removeEventListener('keydown', handleKeyDown, { capture: true });
+		}
+		dialog.value?.close();
+		emit('hidden');
+	}
+};
+
+watch(model, toggleDialog);
+onMounted(() => {
+	if (model.value) toggleDialog(true);
+});
+
+const maxWidth = computed(() => {
+	if (!isFullscreen.value) {
+		return parseSize(props.size, _config.dialogDefaultSizes);
+	}
+
+	return '100%';
+});
+
+/**
+ * This function is called when the user attempts to close the dialog.
+ * It differs from programmatically closing the dialog in that it allows for
+ * custom logic to be executed.
+ */
+const cancelableClose = (event: Event) => {
+	event.preventDefault();
+	// If the user forces closing just allow them
+	if (props.disabled || props.persistent) {
+		denyClose.value = true;
+		wait(300).then(() => {
+			denyClose.value = false;
+		});
+		return false;
+	}
+
+	close();
+};
+
+const close = () => {
+	model.value = false;
+};
+
+const denyClose = ref(false);
+
+const getScrollBarWidth = () => {
+	if (!globalThis.document) return 0;
+	return window.innerWidth - document.documentElement.clientWidth;
+};
+
+const { isMobile } = useMobile();
+const isFullscreen = computed(
+	() =>
+		props.fullscreen === true ||
+		(props.fullscreen === 'mobile' && isMobile.value)
+);
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { CommonProps, Size } from '@/types/CommonProps';
+import type { Classes } from '@/types/Classes';
+
+/**
+ * Width presets (in pixels) used when the dialog `size` prop is set to one of the named breakpoints.
+ */
+export type Sizes = {
+	lg: number;
+	md: number;
+	sm: number;
+};
+
+/**
+ * Props controlling the BaseDialog appearance, accessibility, and closing behaviour.
+ */
+export type BaseDialogProps = {
+	/**
+	 * Accessible label for the close button. Defaults to the localized "close" string when omitted.
+	 */
+	closeLabel?: CommonProps['closeLabel'];
+	/**
+	 * Apply compact spacing to the dialog container.
+	 */
+	compact?: CommonProps['compact'];
+	/**
+	 * Short text describing the dialog contents. Provided text is linked to the dialog for screen readers.
+	 */
+	description?: string;
+	/**
+	 * Disable user interactions that would close the dialog (buttons remain disabled while true).
+	 */
+	disabled?: CommonProps['disabled'];
+	/**
+	 * Render dialog content immediately instead of waiting for the first open.
+	 */
+	eager?: CommonProps['eager'];
+	/**
+	 * CSS selector of the element to focus after opening. Defaults to the first tabbable element.
+	 */
+	focusTarget?: string;
+	/**
+	 * Display the dialog fullscreen. Use `'mobile'` to restrict fullscreen to small devices.
+	 */
+	fullscreen?: boolean | 'mobile';
+	/**
+	 * Hide the header of the dialog.
+	 * Remember to restore accessibility by passing a new `aria-labelledby` attribute to the dialog.
+	 */
+	hideHeader?: boolean;
+	/**
+	 * Additional classes applied to the dialog overlay.
+	 * @deprecated Pass a regular `class` attribute to the component instead.
+	 * @defaultValue `[]`
+	 */
+	overlayClasses?: Classes;
+	/**
+	 * Additional classes applied to the dialog panel.
+	 * @deprecated Pass a regular `class` attribute to the component instead.
+	 * @defaultValue `[]`
+	 */
+	panelClasses?: Classes;
+	/**
+	 * Prevent closing via outside clicks or Escape key. Programmatic close is still allowed.
+	 */
+	persistent?: CommonProps['persistent'];
+	/**
+	 * Toggle visibility of the default close button in the header.
+	 * @defaultValue `true`
+	 */
+	showClose?: CommonProps['showClose'];
+	/**
+	 * Controls the maximum width of the dialog. Accepts the named presets `'sm' | 'md' | 'lg'`,
+	 * a custom CSS width string, or a numeric pixel value.
+	 * @defaultValue `'sm'`
+	 */
+	size?: Size<Sizes>['size'];
+	/**
+	 * Title text announced to assistive technologies and rendered by the default header slot.
+	 */
+	title?: CommonProps['title'];
+	/**
+	 * Duration, in milliseconds, of the open/close transition.
+	 * @defaultValue `300`
+	 */
+	transitionDuration?: CommonProps['transitionDuration'];
+};
+
+export type BaseDialogEvents = {
+	/**
+	 * Emitted as soon as the dialog starts to open (model becomes true).
+	 */
+	(e: 'show'): void;
+	/**
+	 * Emitted as soon as the dialog starts to close (model becomes false).
+	 */
+	(e: 'hide'): void;
+	/**
+	 * Emitted after the dialog is fully opened via `showModal()`.
+	 */
+	(e: 'shown'): void;
+	/**
+	 * Emitted after the close transition completes and the dialog is fully dismissed.
+	 */
+	(e: 'hidden'): void;
+};
+
+/**
+ * Props exposed by the `default` slot.
+ */
+export type BaseDialogDefaultSlotProps = {
+	/**
+	 * Programmatically closes the dialog.
+	 */
+	close: () => void;
+	/**
+	 * The `id` of the title element; useful for custom `aria-labelledby` wiring.
+	 */
+	titleId: string;
+};
+
+/**
+ * Props exposed by the `description` slot.
+ */
+export type BaseDialogDescriptionSlotProps = {
+	/**
+	 * The `id` to assign to your custom description element for `aria-describedby` wiring.
+	 */
+	descriptionId: string;
+	/**
+	 * The `description` prop value.
+	 */
+	text: BaseDialogProps['description'];
+};
+
+/**
+ * Props exposed by the `header` slot.
+ */
+export type BaseDialogHeaderSlotProps = {
+	/**
+	 * The `id` to assign to your custom title element, wired to the dialog's `aria-labelledby`.
+	 */
+	titleId: string;
+	/**
+	 * Programmatically closes the dialog.
+	 */
+	close: () => void;
+	/**
+	 * The `title` prop value.
+	 */
+	title: BaseDialogProps['title'];
+};
+
+/**
+ * Props exposed by the `title` slot.
+ */
+export type BaseDialogTitleSlotProps = {
+	/**
+	 * The `title` prop value.
+	 */
+	text: BaseDialogProps['title'];
+};
+
+export type BaseDialogSlots = {
+	/**
+	 * Replaces the default close icon rendered inside the header's close button.
+	 */
+	close?: (props: object) => any;
+	/**
+	 * Primary body content of the dialog, rendered in the scrollable body area.
+	 */
+	default?: (props: BaseDialogDefaultSlotProps) => any;
+	/**
+	 * Replaces the default accessible description block. The provided content is linked to the dialog via `aria-describedby`.
+	 */
+	description?: (props: BaseDialogDescriptionSlotProps) => any;
+	/**
+	 * Content rendered in the dialog footer, below the body area. Typically used for action buttons.
+	 */
+	footer?: (props: object) => any;
+	/**
+	 * Replaces the entire dialog header section (title + close button). Maintains accessibility wiring via the provided props.
+	 */
+	header?: (props: BaseDialogHeaderSlotProps) => any;
+	/**
+	 * Replaces the default title text inside the header. Remains linked to the dialog through `aria-labelledby`.
+	 */
+	title?: (props: BaseDialogTitleSlotProps) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-base-dialog {
+	--page-padding: 14px;
+	--transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+	position: fixed;
+
+	max-width: min(var(--max-width), 100% - var(--page-padding) * 2);
+	max-height: calc(100% - var(--page-padding) * 2);
+	transition:
+		display var(--transition-duration) var(--transition-duration)
+			var(--transition-timing-function),
+		max-width var(--transition-duration) var(--transition-timing-function),
+		height var(--transition-duration) var(--transition-timing-function),
+		opacity var(--transition-duration) var(--transition-timing-function),
+		scale var(--transition-duration) var(--transition-timing-function);
+	background-color: var(--bb-panel);
+	border-radius: var(--bb-radius);
+	color: var(--bb-text);
+	display: flex;
+	flex-direction: column;
+	opacity: 0;
+	scale: 0.8;
+	z-index: var(--bb-overlay-z-index);
+	overscroll-behavior: contain;
+	width: 100%;
+	overflow: hidden;
+	outline: none;
+	transition-behavior: allow-discrete;
+	top: 50%;
+	left: 50%;
+	transform: translate(-50%, -50%);
+	transform-origin: center left;
+	margin: 0 0;
+
+	&.bb-base-dialog--fullscreen {
+		max-width: 100%;
+		max-height: 100%;
+		border-radius: 0;
+		width: 100%;
+		height: 100%;
+	}
+
+	&.bb-base-dialog--compact {
+		.bb-base-dialog__header {
+			border-bottom: none;
+		}
+		.bb-base-dialog__body {
+			padding-top: 0;
+		}
+	}
+
+	&.bb-base-dialog--open {
+		opacity: 1;
+		scale: 1;
+
+		@starting-style {
+			opacity: 0;
+			scale: 0.8;
+		}
+
+		&::backdrop {
+			opacity: 1;
+
+			@starting-style {
+				opacity: 0;
+			}
+		}
+
+		&:has(dialog::backdrop) {
+			scale: initial;
+		}
+	}
+
+	&.bb-base-dialog--deny-close {
+		scale: 0.9;
+	}
+
+	&:has(.bb-base-dialog.bb-base-dialog--open),
+	&:has(.bb-offcanvas.bb-offcanvas--open) {
+		opacity: 0;
+	}
+
+	&::backdrop {
+		background-color: color-mix(
+			in srgb,
+			var(--bb-overlay-color) calc(var(--bb-overlay-opacity) * 100%),
+			transparent
+		);
+		opacity: 0;
+		transition: opacity var(--transition-duration) cubic-bezier(0.4, 0, 0.2, 1);
+	}
+
+	.bb-base-dialog__header {
+		align-items: center;
+		border-bottom: 1px solid var(--bb-border);
+		column-gap: 12px;
+		display: flex;
+		justify-content: space-between;
+		padding: var(--bb-dialog-py) var(--bb-dialog-px);
+		flex-shrink: 0;
+
+		.bb-base-dialog__title {
+			font-size: var(--bb-dialog-title-size);
+			font-weight: var(--bb-dialog-title-weight);
+		}
+
+		.bb-base-dialog__close {
+			transition: color var(--transition-duration);
+			&:hover {
+				color: var(--bb-primary);
+			}
+
+			button {
+				border-radius: var(--bb-radius);
+				box-shadow: 0px 0px 0px 0px var(--bb-ring);
+				display: flex;
+				margin-right: -8px;
+				outline: 2px solid transparent;
+				outline-offset: 2px;
+				outline-style: none;
+				padding: 8px;
+				transition: box-shadow 0.2s;
+
+				&:focus-visible {
+					box-shadow: 0px 0px 0px var(--bb-ring-size) var(--bb-ring);
+				}
+			}
+
+			.bb-base-dialog__close-icon {
+				display: inline-flex;
+				svg {
+					width: var(--bb-dialog-close);
+				}
+			}
+		}
+	}
+
+	.bb-base-dialog__body {
+		overflow: auto;
+		position: relative;
+		flex: 1 1 auto;
+
+		.bb-base-dialog__body-content {
+			padding: var(--bb-dialog-py) var(--bb-dialog-px);
+		}
+
+		/* Hide any nested dialogs that are not open so that scale transition works without affecting fixed positioning */
+		.bb-base-dialog:not(.bb-base-dialog--open) {
+			display: none;
+		}
+	}
+
+	.bb-base-dialog__footer {
+		padding: var(--bb-dialog-py) var(--bb-dialog-px);
+		pointer-events: auto;
+
+		&:empty {
+			display: none;
+		}
+	}
+}
+
+body:has(.bb-base-dialog--open) {
+	overflow: hidden;
+	padding-right: var(--scrollbar-width);
+}
+```