bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/BbOffCanvas.md

@@ -0,0 +1,549 @@
+# BbOffCanvas
+
+## Template & Script
+
+```vue
+<template>
+	<dialog
+		ref="dialog"
+		:aria-describedby="
+			hasRenderedAtLeastOnce && description ? descriptionId : undefined
+		"
+		:aria-labelledby="hasRenderedAtLeastOnce && title ? titleId : undefined"
+		:aria-live="model ? 'polite' : 'off'"
+		class="bb-offcanvas"
+		:class="
+			[
+				{
+					'bb-offcanvas--open': model,
+					'bb-offcanvas--fullscreen': isFullscreen,
+					'bb-offcanvas--compact': compact,
+					'bb-offcanvas--deny-close': denyClose,
+					[`bb-offcanvas--${props.direction}`]: true,
+				},
+				overlayClasses,
+				panelClasses,
+			].flat()
+		"
+		:inert="!model"
+		:style="{
+			'--max-size': maxSize,
+			'--transition-duration': `${props.transitionDuration}ms`,
+		}"
+		@cancel="userClose"
+		@click.self="userClose"
+	>
+		<template v-if="hasRenderedAtLeastOnce">
+			<div ref="header" class="bb-offcanvas__header">
+				<slot :close="close" name="header" :title="title" :title-id="titleId">
+					<span :id="titleId" class="bb-offcanvas__title">
+						<slot name="title" :text="title">{{ title }}</slot>
+					</span>
+					<span class="bb-offcanvas__close">
+						<button
+							v-if="showClose"
+							:aria-label="closeLabel"
+							:disabled="props.disabled"
+							type="button"
+							@click="close"
+						>
+							<slot name="close">
+								<span class="bb-offcanvas__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-offcanvas__body scrollbar-border">
+				<div class="bb-offcanvas__body-content">
+					<slot
+						:description-id="descriptionId"
+						name="description"
+						:text="description"
+						><div
+							v-if="description"
+							:id="descriptionId"
+							class="bb-offcanvas__description sr-only"
+						>
+							{{ description }}
+						</div>
+					</slot>
+					<slot></slot>
+				</div>
+			</div>
+
+			<div ref="footer" class="bb-offcanvas__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 {
+	BbOffCanvasProps,
+	BbOffCanvasEvents,
+	BbOffCanvasSlots,
+	Sizes,
+} from './types';
+export type { BbOffCanvasProps, BbOffCanvasEvents, BbOffCanvasSlots, Sizes };
+
+const props = withDefaults(defineProps<BbOffCanvasProps>(), {
+	direction: 'left',
+	showClose: true,
+	size: 'sm',
+	panelClasses: () => [],
+	overlayClasses: () => [],
+	transitionDuration: 300,
+});
+
+const emit = defineEmits<BbOffCanvasEvents>();
+
+defineSlots<BbOffCanvasSlots>();
+
+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 toggleDialog = async (value: boolean) => {
+	if (value) {
+		emit('show');
+		// 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');
+		await wait(props.transitionDuration);
+		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 maxSize = computed(() => {
+	if (!isFullscreen.value) {
+		if (props.size === 'auto') return 'fit-content';
+		return parseSize(props.size, _config.offCanvasDefaultSizes);
+	}
+
+	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 userClose = (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 { Classes } from '@/types/Classes';
+import type { CommonProps, Size } from '@/types/CommonProps';
+
+export type Sizes = {
+	sm: number;
+	md: number;
+	lg: number;
+};
+
+export type BbOffCanvasProps = Pick<
+	CommonProps,
+	| 'closeLabel'
+	| 'compact'
+	| 'disabled'
+	| 'eager'
+	| 'persistent'
+	| 'showClose'
+	| 'title'
+	| 'transitionDuration'
+> &
+	Size<Sizes> & {
+		/**
+		 * Description of the content of the modal. Extremely useful for accessibility reasons.
+		 */
+		description?: string;
+		/**
+		 * Element that obtains focus immediately after opening the dialog.
+		 * By default it's the first tabbable item.
+		 */
+		focusTarget?: string;
+		/**
+		 * Displays the modal as fullscreen with no margin to the page.
+		 */
+		fullscreen?: boolean | 'mobile';
+
+		/**
+		 * Classes to apply to the panel of the dialog.
+		 *
+		 * @deprecated Pass a common `class` attribute to the component instead.
+		 */
+		panelClasses?: Classes;
+		/**
+		 * Classes to apply to the overlay of the dialog.
+		 *
+		 * @deprecated Pass a common `class` attribute to the component instead.
+		 */
+		overlayClasses?: Classes;
+		/**
+		 * Defines the direction the offcanvas should appear from.
+		 *
+		 * @defaultValue `'left'`
+		 */
+		direction?: 'left' | 'top' | 'right' | 'bottom';
+	};
+
+export type BbOffCanvasEvents = {
+	/** Emitted as soon as the user triggers the open action (model becomes true). */
+	(e: 'show'): void;
+	/** Emitted as soon as the user triggers the close action (model becomes false). */
+	(e: 'hide'): void;
+	/** Emitted after the offcanvas is fully opened using `showModal()`. */
+	(e: 'shown'): void;
+	/** Emitted after the close transition completes and the offcanvas is fully dismissed. */
+	(e: 'hidden'): void;
+};
+
+/** Props exposed by the `header` slot. */
+export type BbOffCanvasHeaderSlotProps = {
+	/** The `id` assigned to the title element, wired to `aria-labelledby`. */
+	titleId: string;
+	/** Programmatically closes the off-canvas panel. */
+	close: () => void;
+	/** The `title` prop value. */
+	title: BbOffCanvasProps['title'];
+};
+
+/** Props exposed by the `title` slot. */
+export type BbOffCanvasTitleSlotProps = {
+	/** The `title` prop value. */
+	text: BbOffCanvasProps['title'];
+};
+
+/** Props exposed by the `description` slot. */
+export type BbOffCanvasDescriptionSlotProps = {
+	/** The `id` to assign to your custom description element for `aria-describedby` wiring. */
+	descriptionId: string;
+	/** The `description` prop value. */
+	text: BbOffCanvasProps['description'];
+};
+
+export type BbOffCanvasSlots = {
+	/**
+	 * Replaces the entire off-canvas header section (title + close button). Maintains accessibility wiring via the provided props.
+	 */
+	header?: (props: BbOffCanvasHeaderSlotProps) => any;
+	/**
+	 * Replaces the default title text inside the header. Remains linked to the panel through `aria-labelledby`.
+	 */
+	title?: (props: BbOffCanvasTitleSlotProps) => any;
+	/**
+	 * Replaces the default close icon rendered inside the header's close button.
+	 */
+	close?: (props: object) => any;
+	/**
+	 * Replaces the default accessible description block. The provided content is linked to the panel via `aria-describedby`.
+	 */
+	description?: (props: BbOffCanvasDescriptionSlotProps) => any;
+	/**
+	 * Primary body content of the off-canvas panel, rendered in the scrollable body area.
+	 */
+	default?: (props: object) => any;
+	/**
+	 * Content rendered in the panel footer, below the body area. Typically used for action buttons.
+	 */
+	footer?: (props: object) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-offcanvas {
+	--translate-x: 0%;
+	--translate-y: 0%;
+	--translate: 1;
+	--transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+	position: fixed;
+	transition:
+		max-width var(--transition-duration) var(--transition-timing-function),
+		max-height var(--transition-duration) var(--transition-timing-function),
+		translate var(--transition-duration) var(--transition-timing-function),
+		display var(--transition-duration) var(--transition-duration)
+			var(--transition-timing-function);
+	background-color: var(--bb-panel);
+	color: var(--bb-text);
+	display: flex;
+	flex-direction: column;
+	z-index: var(--bb-overlay-z-index);
+	overscroll-behavior: contain;
+	overflow: hidden;
+	outline: none;
+	transition-behavior: allow-discrete;
+	margin: 0 0;
+	translate: calc(var(--translate-x) * var(--translate))
+		calc(var(--translate-y) * var(--translate));
+
+	&.bb-offcanvas--left,
+	&.bb-offcanvas--right {
+		max-height: 100%;
+		max-width: var(--max-size);
+		width: 100%;
+		top: 0px;
+		height: 100%;
+	}
+	&.bb-offcanvas--left {
+		--translate-x: -100%;
+		left: 0px;
+	}
+	&.bb-offcanvas--right {
+		--translate-x: 100%;
+		right: 0px;
+		left: auto;
+	}
+	&.bb-offcanvas--top,
+	&.bb-offcanvas--bottom {
+		max-height: min(var(--max-size), 100%);
+		height: var(--max-size);
+		max-width: 100%;
+		width: 100%;
+		left: 0;
+		right: 0;
+	}
+	&.bb-offcanvas--top {
+		--translate-y: -100%;
+		top: 0px;
+		bottom: auto;
+	}
+	&.bb-offcanvas--bottom {
+		--translate-y: 100%;
+		bottom: 0px;
+		top: auto;
+	}
+
+	&.bb-offcanvas--fullscreen {
+		border-radius: 0;
+		width: 100%;
+		height: 100%;
+	}
+
+	&.bb-offcanvas--compact {
+		.bb-offcanvas__header {
+			border-bottom: none;
+		}
+		.bb-offcanvas__body {
+			padding-top: 0;
+		}
+	}
+
+	&.bb-offcanvas--open {
+		--translate: 0;
+
+		&::backdrop {
+			opacity: 1;
+
+			@starting-style {
+				opacity: 0;
+			}
+		}
+	}
+	&.bb-offcanvas--deny-close {
+		--translate: 0.1;
+	}
+
+	&:has(.bb-offcanvas.bb-offcanvas--open),
+	&:has(.bb-base-dialog.bb-base-dialog--open) {
+		--translate: 1;
+	}
+
+	&::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-offcanvas__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-offcanvas__title {
+			font-size: var(--bb-dialog-title-size);
+			font-weight: var(--bb-dialog-title-weight);
+		}
+
+		.bb-offcanvas__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-offcanvas__close-icon {
+				display: inline-flex;
+				svg {
+					width: var(--bb-dialog-close);
+				}
+			}
+		}
+	}
+
+	.bb-offcanvas__body {
+		overflow: auto;
+		position: relative;
+		padding: var(--bb-dialog-py) calc(var(--bb-dialog-px) - var(--bb-ring-size))
+			calc(var(--bb-dialog-py) - var(--bb-ring-size));
+		flex: 1 1 auto;
+
+		.bb-offcanvas__body-content {
+			margin: 0 min(var(--bb-ring-size), var(--bb-dialog-px));
+		}
+	}
+
+	.bb-offcanvas__footer {
+		padding: var(--bb-dialog-py) var(--bb-dialog-px);
+		pointer-events: auto;
+
+		&:empty {
+			display: none;
+		}
+	}
+}
+
+body:has(.bb-offcanvas--open) {
+	overflow: hidden;
+	padding-right: var(--scrollbar-width);
+}
+```