bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/BaseDialog.md

@@ -1,610 +0,0 @@
-# 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);
-}
-```