bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/BaseButton.md

@@ -0,0 +1,448 @@
+# BaseButton
+
+## Template & Script
+
+```vue
+<template>
+	<RouterComponent v-if="asRouting" :class="classes" v-bind="attributes"
+		><slot>{{ text }}</slot></RouterComponent
+	>
+	<component :is="'a'" v-else-if="asLink" :class="classes" v-bind="attributes"
+		><slot>{{ text }}</slot></component
+	>
+	<component :is="tag" v-else :class="classes" v-bind="attributes"
+		><slot>{{ text }}</slot></component
+	>
+</template>
+
+<script setup lang="ts">
+/**
+ * BaseButton Component
+ *
+ * A polymorphic button component that adapts its rendering based on props and framework context.
+ *
+ * Rendering Strategy (priority order):
+ * 1. RouterComponent: When `to` is provided or `href` with Inertia (without target)
+ *    - Handles Vue Router links, Nuxt links, and Inertia links
+ * 2. Anchor (<a>): When `href` is provided (with target) or disabled router link
+ *    - Regular HTML links, typically for external navigation
+ * 3. Native Element: Defaults to <button>, or custom element via `tag` prop
+ *    - Standard buttons or custom interactive elements
+ *
+ * Framework Compatibility:
+ * - Vue 3 + Vue Router: Standard SPA routing
+ * - Nuxt.js: Uses NuxtLink for routing
+ * - Inertia.js: Uses Inertia Link for server-driven SPA navigation
+ *
+ * Note: Component resolution for RouterComponent happens at setup time (not computed)
+ * to maintain compatibility with Nuxt's component resolution system.
+ */
+import { computed, getCurrentInstance } from 'vue';
+import RouterComponent from './RouterComponent.vue';
+import { useFrameworkDetection } from '@/composables/useFrameworkDetection';
+import { _config } from '@/composables/useBbConfig';
+import type { BaseButtonProps, BaseButtonSlots } from './types';
+
+const props = withDefaults(defineProps<BaseButtonProps>(), {
+	tag: 'button',
+	type: 'button',
+});
+
+defineSlots<BaseButtonSlots>();
+
+const { isInertia } = useFrameworkDetection();
+const instance = getCurrentInstance();
+
+const inertiaPathname = computed(() => {
+	const url = instance?.proxy?.$page?.url;
+	if (!url) return undefined;
+	try {
+		return new URL(url, 'http://localhost').pathname;
+	} catch {
+		return undefined;
+	}
+});
+
+const isExactActive = computed(() => {
+	if (!isInertia || !props.href || !inertiaPathname.value) return false;
+	try {
+		return (
+			new URL(props.href, 'http://localhost').pathname === inertiaPathname.value
+		);
+	} catch {
+		return false;
+	}
+});
+
+const isActive = computed(() => {
+	if (!isInertia || !props.href || !inertiaPathname.value) return false;
+	try {
+		return inertiaPathname.value.startsWith(
+			new URL(props.href, 'http://localhost').pathname
+		);
+	} catch {
+		return false;
+	}
+});
+
+/**
+ * Determines if the component should render as a routing component (Inertia/Vue Router).
+ *
+ * Note: Inertia links with a `target` attribute fall back to regular anchors because
+ * Inertia cannot handle external links that open in new windows/tabs. This ensures
+ * external links (e.g., href="google.com" target="_blank") work as expected.
+ */
+const asRouting = computed(() => {
+	// Use Inertia routing only if no target (external links need regular anchors)
+	if (props.href && isInertia && !props.disabled && !props.target) {
+		return true;
+	}
+	if (props.to && !props.disabled) {
+		return true;
+	}
+	return false;
+});
+
+/**
+ * Determines if the component should render as a regular anchor tag.
+ *
+ * This includes:
+ * - Links with `href` that don't qualify for Inertia routing (see asRouting)
+ * - Disabled router links (`to` with `disabled`), which fall back to anchors
+ *   to maintain link semantics while preventing navigation
+ */
+const asLink = computed(() => {
+	if (props.href || (props.to && props.disabled)) {
+		return true;
+	}
+	return false;
+});
+
+const resolvedActiveClass = computed(
+	() => props.activeClass ?? _config.linkActiveClass
+);
+const resolvedExactActiveClass = computed(
+	() => props.exactActiveClass ?? _config.linkExactActiveClass
+);
+
+const classes = computed(() => ({
+	'base-btn': true,
+	'base-btn--block': props.block,
+	'base-btn--disabled': props.disabled,
+	[resolvedActiveClass.value]: isActive.value,
+	[resolvedExactActiveClass.value]: isExactActive.value,
+}));
+
+type PossibleAttributes = {
+	activeClass: BaseButtonProps['activeClass'];
+	'aria-disabled': boolean;
+	ariaCurrentValue: BaseButtonProps['ariaCurrentValue'];
+	data: BaseButtonProps['data'];
+	disabled: boolean;
+	exactActiveClass: BaseButtonProps['exactActiveClass'];
+	headers: BaseButtonProps['headers'];
+	href: string | null;
+	method: BaseButtonProps['method'];
+	onBefore: BaseButtonProps['onBefore'];
+	onCancel: BaseButtonProps['onCancel'];
+	onCancelToken: BaseButtonProps['onCancelToken'];
+	onFinish: BaseButtonProps['onFinish'];
+	only: BaseButtonProps['only'];
+	onProgress: BaseButtonProps['onProgress'];
+	onStart: BaseButtonProps['onStart'];
+	onSuccess: BaseButtonProps['onSuccess'];
+	preserveScroll: BaseButtonProps['preserveScroll'];
+	preserveState: BaseButtonProps['preserveState'];
+	queryStringArrayFormat: BaseButtonProps['queryStringArrayFormat'];
+	replace: BaseButtonProps['replace'];
+	role: string;
+	target: string;
+	to: BaseButtonProps['to'];
+	type: string;
+};
+
+/**
+ * Returns attributes for native button rendering
+ */
+const getNativeButtonAttributes = (): Partial<PossibleAttributes> => {
+	return {
+		disabled: props.disabled,
+		type: props.type,
+	};
+};
+
+/**
+ * Returns attributes for anchor/Inertia link rendering
+ */
+const getAnchorAttributes = (): Partial<PossibleAttributes> => {
+	// When rendering as anchor, prevent navigation if disabled
+	// https://getbootstrap.com/docs/4.0/components/buttons/#disabled-state
+	if (props.disabled) {
+		return {
+			'aria-disabled': true,
+			role: 'link',
+			href: null,
+		};
+	}
+
+	// Only attach href to active links
+	// https://www.scottohara.me/blog/2021/05/28/disabled-links.html
+	const attrs: Partial<PossibleAttributes> = {
+		href: props.href,
+		target: props.target,
+	};
+
+	// Attach Inertia-specific props if in Inertia context
+	if (isInertia) {
+		attrs.data = props.data;
+		attrs.headers = props.headers;
+		attrs.method = props.method;
+		attrs.onBefore = props.onBefore;
+		attrs.onCancel = props.onCancel;
+		attrs.onCancelToken = props.onCancelToken;
+		attrs.onFinish = props.onFinish;
+		attrs.only = props.only;
+		attrs.onProgress = props.onProgress;
+		attrs.onStart = props.onStart;
+		attrs.onSuccess = props.onSuccess;
+		attrs.preserveScroll = props.preserveScroll;
+		attrs.preserveState = props.preserveState;
+		attrs.queryStringArrayFormat = props.queryStringArrayFormat;
+		attrs.replace = props.replace;
+	}
+
+	return attrs;
+};
+
+/**
+ * Returns attributes for Vue Router link rendering
+ */
+const getRouterAttributes = (): Partial<PossibleAttributes> => {
+	return {
+		activeClass: resolvedActiveClass.value,
+		ariaCurrentValue: props.ariaCurrentValue,
+		exactActiveClass: resolvedExactActiveClass.value,
+		replace: props.replace,
+		target: props.target,
+		to: props.to,
+	};
+};
+
+const attributes = computed(() => {
+	if (!asRouting.value && !asLink.value) {
+		return getNativeButtonAttributes();
+	} else if (asLink.value || (asRouting.value && isInertia)) {
+		return getAnchorAttributes();
+	} else if (asRouting.value) {
+		return getRouterAttributes();
+	}
+	return {};
+});
+</script>
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { RouteLocationRaw } from 'vue-router';
+
+export type BaseButtonProps = {
+	/**
+	 * CSS class applied when the component renders as a link and the target of the link is the current route or the url matches partially.
+	 * Ported for Inertia compatibility.
+	 * @defaultValue `'router-link-active'`
+	 */
+	activeClass?: string;
+	/**
+	 * Value forwarded to the `aria-current` attribute when the component renders
+	 * as a router link and the target route is an exact match.
+	 *
+	 * Use to communicate the current location to assistive technologies.
+	 * @defaultValue `'page'`
+	 */
+	ariaCurrentValue?:
+		| 'page'
+		| 'step'
+		| 'location'
+		| 'date'
+		| 'time'
+		| 'true'
+		| 'false';
+	/**
+	 * Makes the component take the full available width (block-level layout).
+	 * Adds the `base-btn--block` modifier class.
+	 */
+	block?: boolean;
+	/**
+	 * Request payload forwarded to Inertia when navigating via `href` in an
+	 * Inertia-enabled app. Ignored when not using Inertia.
+	 */
+	data?: object;
+	/**
+	 * Disables user interaction.
+	 *
+	 * - When rendering as a native button, sets the `disabled` attribute.
+	 * - When rendering as a link (anchor/Inertia), removes `href`, adds
+	 *   `aria-disabled="true"`, and prevents navigation while keeping focusable
+	 *   semantics consistent.
+	 */
+	disabled?: boolean;
+	/**
+	 * CSS class applied when the component renders as a link and the target of the link
+	 * and the url matches exactly.
+	 * Ported for Inertia compatibility.
+	 * @defaultValue `'router-link-exact-active'`
+	 */
+	exactActiveClass?: string;
+	/**
+	 * Additional HTTP headers forwarded to Inertia when navigating via `href`
+	 * in an Inertia-enabled app.
+	 */
+	headers?: object;
+	/**
+	 * Hyperlink reference used when rendering as an anchor (or as an Inertia
+	 * link in Inertia-enabled apps). If provided and not disabled, the component
+	 * renders as an anchor/Inertia link.
+	 */
+	href?: HTMLAnchorElement['href'];
+	/**
+	 * HTTP method used for Inertia navigation when `href` is provided in an
+	 * Inertia-enabled app. Ignored otherwise.
+	 */
+	method?: 'get' | 'post' | 'put' | 'patch' | 'delete';
+	/**
+	 * Lifecycle hook invoked by Inertia right before the request is sent.
+	 */
+	onBefore?: () => void;
+	/**
+	 * Lifecycle hook invoked by Inertia when a request is cancelled.
+	 */
+	onCancel?: () => void;
+	/**
+	 * Receives the Inertia cancel token source when a request is initiated.
+	 * Can be used to cancel the request.
+	 */
+	onCancelToken?: (cancelToken: import('axios').CancelTokenSource) => void;
+	/**
+	 * Lifecycle hook invoked by Inertia after the request has finished
+	 * (regardless of success or error).
+	 */
+	onFinish?: () => void;
+	/**
+	 * Limits the properties that are preserved in Inertia partial reloads.
+	 */
+	only?: string[];
+	/**
+	 * Progress callback invoked by Inertia with the upload/download percentage
+	 * when available.
+	 */
+	onProgress?: (progress: { percentage: number | undefined }) => void;
+	/**
+	 * Lifecycle hook invoked by Inertia when a request starts.
+	 */
+	onStart?: () => void;
+	/**
+	 * Lifecycle hook invoked by Inertia when a request succeeds.
+	 */
+	onSuccess?: () => void;
+	/**
+	 * Controls whether Inertia should preserve the current scroll position after
+	 * navigation. Can be a boolean or a predicate receiving the visit props.
+	 * @defaultValue `false`
+	 */
+	preserveScroll?: boolean | ((props: { [key: string]: unknown }) => boolean);
+	/**
+	 * Controls whether Inertia should preserve the current state after navigation.
+	 * Can be a boolean or a predicate receiving the visit props.
+	 * @defaultValue `false`
+	 */
+	preserveState?:
+		| boolean
+		| ((props: { [key: string]: unknown }) => boolean)
+		| null;
+	/**
+	 * Format to use when serializing array values into the query string for
+	 * Inertia requests.
+	 * @defaultValue `'brackets'`
+	 */
+	queryStringArrayFormat?: 'brackets' | 'indices';
+	/**
+	 * Uses history replacement instead of push navigation.
+	 *
+	 * - With Vue Router (`to`), calls `router.replace`.
+	 * - With Inertia (`href`), performs a replace visit.
+	 */
+	replace?: boolean;
+	/**
+	 * Custom HTML tag used when rendering as a native element (neither router
+	 * link nor anchor). Must correspond to a non-void HTML element.
+	 * @defaultValue `'button'`
+	 */
+	tag?: string;
+	/**
+	 * Target browsing context for anchor/Inertia links (e.g. `_self`, `_blank`).
+	 * Ignored when rendering as a native button.
+	 */
+	target?: HTMLAnchorElement['target'];
+	/**
+	 * Fallback text content rendered when no default slot is provided.
+	 */
+	text?: string;
+	/**
+	 * Route location to navigate to. When provided (and not disabled), the
+	 * component renders as a Vue Router link.
+	 */
+	to?: RouteLocationRaw;
+	/**
+	 * Native `type` attribute used when rendering as a button (e.g. `button`,
+	 * `submit`, `reset`).
+	 *
+	 * @defaultValue `'button'`
+	 */
+	type?: HTMLButtonElement['type'];
+};
+
+export type BaseButtonSlots = {
+	/**
+	 * Primary content rendered inside the button element. Falls back to the `text` prop when empty.
+	 */
+	default?: (props: object) => any;
+};
+```
+
+## Styles
+
+```css
+.base-btn {
+	box-shadow: 0px 0px 0px 0px var(--bb-ring);
+	color: var(--bb-text);
+	cursor: pointer;
+	outline: 2px solid transparent;
+	outline-offset: 2px;
+	text-align: center;
+	transition-duration: 150ms;
+	transition-property:
+		color, background-color, border-color, text-decoration-color, box-shadow;
+	transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+	user-select: none;
+	&--block {
+		width: 100%;
+	}
+	&--disabled {
+		cursor: not-allowed;
+		pointer-events: none;
+	}
+	&:focus-visible {
+		box-shadow: 0px 0px 0px var(--bb-ring-size) var(--bb-ring);
+	}
+}
+
+a.base-btn {
+	&:hover {
+		text-decoration: inherit;
+	}
+}
+```