bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/BbColorPalette.md

@@ -0,0 +1,360 @@
+# BbColorPalette
+
+## Template & Script
+
+```vue
+<template>
+	<!-- Activator slot — skipped when an external activator ref is passed -->
+	<slot
+		v-if="!hasExternalActivator"
+		name="activator"
+		v-bind="{
+			props: { ref: setActivatorRef },
+			anchorProps: { ref: setAnchorRef },
+			open: isOpen,
+			color: modelValue,
+			disabled,
+		}"
+	/>
+
+	<!-- Palette popover -->
+	<CommonPopover
+		v-model="isOpen"
+		:anchor="effectiveAnchor"
+		:aria-label="t('colorInput.dialogLabel').value"
+		:arrow-padding="arrowPadding"
+		:boundary="boundary"
+		class="bb-color-palette__popover"
+		dialog
+		:eager="eager"
+		:flip="flip"
+		:hide-arrow="!showArrow"
+		:offset="offset"
+		:padding="padding"
+		:placement="placement"
+		:transition-duration="transitionDuration"
+	>
+		<ColorPallette
+			ref="paletteRef"
+			:alpha="alpha"
+			:inert="!isOpen"
+			:model-value="modelValue"
+			:picker="picker"
+			:swatches="swatches"
+			@update:model-value="emit('update:modelValue', $event)"
+		/>
+	</CommonPopover>
+</template>
+
+<script setup lang="ts">
+import { computed, nextTick, onBeforeUnmount, ref, watch } from 'vue';
+import { extractDomContainer } from '@/utilities/functions/extractDomContainer';
+import { useLocale } from '@/composables/useLocale';
+import ColorPallette from '../BaseColorInput/ColorPalette.vue';
+import CommonPopover from '../CommonPopover/CommonPopover.vue';
+import type {
+	BbColorPaletteProps,
+	BbColorPaletteEvents,
+	BbColorPaletteSlots,
+} from './types';
+export type { BbColorPaletteProps, BbColorPaletteEvents, BbColorPaletteSlots };
+
+const props = withDefaults(defineProps<BbColorPaletteProps>(), {
+	alpha: false,
+	flip: true,
+	offset: 4,
+	padding: 6,
+	picker: false,
+	showArrow: false,
+	transitionDuration: 250,
+});
+
+const emit = defineEmits<BbColorPaletteEvents>();
+
+defineSlots<BbColorPaletteSlots>();
+
+const { t } = useLocale();
+
+// ---- Palette ref (for focus management) ----------------------------------------
+
+const paletteRef = ref<{ el: HTMLElement | null } | null>(null);
+
+// ---- Activator element ---------------------------------------------------------
+
+const activatorEl = ref<HTMLElement | undefined>();
+const anchorEl = ref<HTMLElement | undefined>();
+const hasExternalActivator = computed(() => props.activator != null);
+
+/** Ref callback passed to the activator slot. */
+const setActivatorRef = (reference: unknown) => {
+	activatorEl.value = extractDomContainer(reference) ?? undefined;
+};
+
+/** Ref callback for the anchor element when it differs from the activator. */
+const setAnchorRef = (reference: unknown) => {
+	anchorEl.value = extractDomContainer(reference) ?? undefined;
+};
+
+// Sync external activator prop → activatorEl
+watch(
+	() => props.activator,
+	(val) => {
+		activatorEl.value = extractDomContainer(val) ?? undefined;
+	},
+	{ immediate: true }
+);
+
+// Sync external anchor prop → anchorEl
+watch(
+	() => props.anchor,
+	(val) => {
+		anchorEl.value =
+			val != null ? (extractDomContainer(val) ?? undefined) : undefined;
+	},
+	{ immediate: true }
+);
+
+// The element the popover positions itself relative to
+const effectiveAnchor = computed(() => anchorEl.value ?? activatorEl.value);
+
+// ---- Open state ----------------------------------------------------------------
+
+const isOpen = ref(false);
+let previousFocus: HTMLElement | null = null;
+
+const onActivatorClick = (event: MouseEvent) => {
+	if (props.disabled || props.readonly) return;
+	event.stopPropagation();
+	isOpen.value = !isOpen.value;
+};
+
+/** Close when the backdrop (dialog element itself) is clicked. */
+const onClickDocument = (event: Event) => {
+	if (event.target instanceof HTMLDialogElement) {
+		isOpen.value = false;
+	}
+};
+
+// Side effects only: emit, document listener, focus management
+watch(isOpen, async (val) => {
+	emit('update:open', val);
+	if (val) {
+		previousFocus =
+			document.activeElement instanceof HTMLElement
+				? document.activeElement
+				: null;
+		document.addEventListener('click', onClickDocument, { passive: true });
+		// Wait for the popover to be rendered, then move focus into the palette
+		await nextTick();
+		paletteRef.value?.el?.querySelector<HTMLElement>('[tabindex="0"]')?.focus();
+	} else {
+		document.removeEventListener('click', onClickDocument);
+		// Restore focus to the element that was active before the palette opened
+		previousFocus?.focus();
+		previousFocus = null;
+	}
+});
+
+// ---- Programmatic listeners on the activator element ---------------------------
+
+let cleanupActivator: (() => void) | null = null;
+
+watch(
+	activatorEl,
+	(el) => {
+		cleanupActivator?.();
+		cleanupActivator = null;
+		if (!el) return;
+		el.addEventListener('click', onActivatorClick);
+		cleanupActivator = () => {
+			el.removeEventListener('click', onActivatorClick);
+			el.removeAttribute('aria-haspopup');
+			el.removeAttribute('aria-expanded');
+			el.removeAttribute('aria-label');
+		};
+	},
+	{ immediate: true }
+);
+
+// ---- Reactive ARIA on the activator element ------------------------------------
+// Runs for both slot and external-activator paths whenever the element, open
+// state, or label changes — keeping attributes always in sync.
+
+const effectiveLabel = computed(
+	() => props.label ?? t('colorInput.openPicker').value
+);
+
+watch(
+	[activatorEl, isOpen, effectiveLabel] as const,
+	([el, open, label]) => {
+		if (!el) return;
+		el.setAttribute('aria-haspopup', 'dialog');
+		el.setAttribute('aria-expanded', open ? 'true' : 'false');
+		el.setAttribute('aria-label', label);
+	},
+	{ immediate: true }
+);
+
+onBeforeUnmount(() => {
+	cleanupActivator?.();
+	document.removeEventListener('click', onClickDocument);
+});
+</script>
+```
+
+## Types
+
+```ts
+import type { CommonProps } from '@/types/CommonProps';
+
+export type BbColorPaletteProps = Pick<
+	CommonProps,
+	| 'arrowPadding'
+	| 'eager'
+	| 'offset'
+	| 'padding'
+	| 'placement'
+	| 'transitionDuration'
+> & {
+	/**
+	 * v-model: the current color as a `#RRGGBB` hex string (or `#RRGGBBAA` when
+	 * `alpha` is enabled), or `null` when empty.
+	 */
+	modelValue: string | null;
+
+	/**
+	 * Enable the alpha channel. The picker shows an opacity slider and emits
+	 * `#RRGGBBAA` hex8 values.
+	 *
+	 * @defaultValue `false`
+	 */
+	alpha?: boolean;
+
+	/**
+	 * Controls swatches display in the picker:
+	 * - `true`       — show the built-in Material-palette swatches
+	 * - `string[][]` — show custom swatches (each inner array = a column of shades)
+	 * - `false` / omitted — no swatches section
+	 */
+	swatches?: boolean | string[][];
+
+	/**
+	 * External activator element or component ref.
+	 * When provided, the `activator` slot is not rendered and click listeners are
+	 * attached programmatically to the referenced element — mirroring the
+	 * BbDropdown activator API.
+	 */
+	activator?: HTMLElement | Record<string, any> | null;
+
+	/**
+	 * Element or component ref the popover positions itself relative to.
+	 * Defaults to the activator element when omitted, allowing the popover to
+	 * be anchored to a larger container (e.g. the full input row) while a
+	 * smaller element (e.g. a color dot) remains the click target.
+	 */
+	anchor?: HTMLElement | Record<string, any> | null;
+
+	/**
+	 * Constrains the popover within a bounding element.
+	 * Accepts an HTMLElement, a Vue component ref, or a CSS selector string.
+	 */
+	boundary?: HTMLElement | Record<string, any> | string | null;
+
+	/**
+	 * Whether to flip the popover to the opposite side when there is not enough space.
+	 *
+	 * @defaultValue `true`
+	 */
+	flip?: boolean;
+
+	/**
+	 * Show the popover arrow. Hidden by default since the palette has its own visual frame.
+	 *
+	 * @defaultValue `false`
+	 */
+	showArrow?: boolean;
+
+	/**
+	 * Disable all interaction (activator and palette).
+	 */
+	disabled?: boolean;
+
+	/**
+	 * Prevent opening the palette while keeping the activator visible.
+	 */
+	readonly?: boolean;
+
+	/**
+	 * Accessible label applied to the activator element via `aria-label`.
+	 * Defaults to the locale string for "Open color picker" when omitted.
+	 */
+	label?: string;
+
+	/**
+	 * Show an eyedropper button inside the palette to sample any color on screen.
+	 * Uses the native EyeDropper API — hidden automatically on unsupported browsers.
+	 *
+	 * @defaultValue `false`
+	 */
+	picker?: boolean;
+};
+
+export type BbColorPaletteEvents = {
+	/** Emitted when the color value changes. Payload is `#RRGGBB` or `#RRGGBBAA` (when alpha is enabled), or `null` when cleared. */
+	(e: 'update:modelValue', value: string | null): void;
+	/** Emitted whenever the popover opens or closes. */
+	(e: 'update:open', value: boolean): void;
+};
+
+/** Props spread onto the activator element to wire up the dropdown reference. */
+export type BbColorPaletteActivatorProps = {
+	/** Ref callback to register the activator element. */
+	ref: (el: unknown) => void;
+};
+
+/** Props spread onto an optional anchor element when it differs from the activator. */
+export type BbColorPaletteAnchorProps = {
+	/** Ref callback to register the anchor element. */
+	ref: (el: unknown) => void;
+};
+
+/** Props exposed by the `activator` slot. */
+export type BbColorPaletteActivatorSlotProps = {
+	/**
+	 * Spread onto your activator element to register the ref.
+	 * ARIA attributes (`aria-haspopup`, `aria-expanded`, `aria-label`) are set
+	 * programmatically so they stay correct for both the slot and external activator paths.
+	 */
+	props: BbColorPaletteActivatorProps;
+	/**
+	 * Spread onto a wrapping element when you want the popover to anchor to
+	 * something larger than the click target (e.g. the full input row).
+	 * When unused the activator element is also the anchor.
+	 */
+	anchorProps: BbColorPaletteAnchorProps;
+	/** Whether the palette popover is currently open. */
+	open: boolean;
+	/** The current color value (mirrors `modelValue`). */
+	color: string | null;
+	/** Whether the palette is disabled. */
+	disabled?: boolean;
+};
+
+export type BbColorPaletteSlots = {
+	/**
+	 * Custom activator element.
+	 * Apply `v-bind="props"` to the element you want to use as the trigger —
+	 * this wires up the ref callback that lets BbColorPalette track the element.
+	 *
+	 * @example
+	 * ```vue
+	 * <BbColorPalette v-model="color">
+	 *   <template #activator="{ props: dotProps, open, color }">
+	 *     <button v-bind="dotProps" :style="{ background: color }">Pick</button>
+	 *   </template>
+	 * </BbColorPalette>
+	 * ```
+	 */
+	activator?: (props: BbColorPaletteActivatorSlotProps) => any;
+};
+```

package/dist/ai/BbConfirm.md

@@ -0,0 +1,160 @@
+# BbConfirm
+
+## Template & Script
+
+```vue
+<template>
+	<BaseDialog
+		:class="dialogClasses"
+		:hide-header="state.current?.hideHeader"
+		:model-value="state.processing"
+		:persistent="isBusy"
+		:show-close="!isBusy"
+		:size="state.current?.size"
+		:title="state.current?.title"
+		@update:model-value="onClose"
+	>
+		<div class="bb-confirm__content">
+			<BbSpinner v-if="state.loading" size="36" />
+			<div v-else-if="hasText" class="bb-confirm__text">
+				{{ state.current?.text }}
+			</div>
+			<!-- Teleport target for custom content injected via external components -->
+			<div v-show="showTeleport" class="bb-confirm__teleport"></div>
+		</div>
+		<template v-if="showActions" #footer>
+			<BbButton
+				v-if="state.current?.no !== false"
+				:loading="state.noBusy"
+				class="bb-confirm__no"
+				:disabled="state.yesBusy"
+				@click="onNoClick"
+			>
+				{{ state.current?.noText }}
+			</BbButton>
+
+			<BbButton
+				v-if="state.current?.yes !== false"
+				:loading="state.yesBusy"
+				class="bb-confirm__yes"
+				:disabled="state.noBusy"
+				@click="onYesClick"
+			>
+				{{ state.current?.yesText }}
+			</BbButton>
+		</template>
+	</BaseDialog>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import {
+	confirmState as state,
+	processMessage,
+} from '@/composables/useConfirm';
+import BaseDialog from '../BaseDialog/BaseDialog.vue';
+import BbSpinner from '../BbSpinner/BbSpinner.vue';
+import BbButton from '../BbButton/BbButton.vue';
+
+const isBusy = computed(
+	() => state.value.yesBusy || state.value.noBusy || state.value.loading
+);
+
+const hasText = computed(() => Boolean(state.value.current?.text));
+
+const showTeleport = computed(
+	() => state.value.current && !state.value.current.text && !state.value.loading
+);
+
+const showActions = computed(
+	() => state.value.current?.actions !== false && !state.value.loading
+);
+
+const dialogClasses = computed(() => [
+	'bb-confirm',
+	`bb-confirm--${state.value.current?.theme ?? 'default'}`,
+]);
+
+const onClose = (value: boolean) => {
+	if (!value) processMessage(false);
+};
+
+const onYesClick = () => processMessage(true);
+
+const onNoClick = () => processMessage(false, true);
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Styles
+
+```css
+.bb-confirm {
+	.bb-base-dialog {
+		&__overlay {
+		}
+		&__panel {
+		}
+
+		&__content {
+		}
+		&__header {
+			--bb-dialog-py: 15px;
+		}
+		&__title {
+		}
+		&-close {
+			button {
+			}
+
+			&__content {
+			}
+			&__label {
+			}
+			&__icon {
+			}
+		}
+		&__body {
+			--bb-dialog-py: 12px;
+			overflow: clip;
+
+			.bb-confirm__content {
+				.bb-confirm__text {
+				}
+				> .bb-spinner {
+					display: block;
+					margin-left: auto;
+					margin-right: auto;
+				}
+			}
+		}
+		&__description {
+		}
+		&__footer {
+			--bb-dialog-py: 15px;
+			&:not(:empty) {
+				text-align: right;
+				> :not(:last-child) {
+					margin-right: 12px;
+				}
+			}
+
+			.bb-confirm__no {
+				--color: var(--bb-panel);
+				--text-color: var(--bb-text);
+				border-color: var(--bb-border);
+				&:hover:not(:disabled),
+				&:focus-visible:not(:disabled) {
+					--color: var(--bb-primary);
+					--text-color: var(--bb-contrasting);
+				}
+			}
+			.bb-confirm__yes {
+			}
+		}
+	}
+}
+```