ajo-ui 0.1.0

package/src/tooltip.tsx

@@ -0,0 +1,359 @@
+import type { IntrinsicElements, Stateful, Stateless, WithChildren } from 'ajo'
+import { callHandler, statefulRootAttrs as rootAttrs } from 'ajo-cloves'
+import { context } from 'ajo/context'
+import { contentAttrs, popup, type PopupView } from './popup'
+import { PopupSurface } from './popup-surface'
+import type { ReservedPositionArg } from './position'
+import { popupStyle, triggerAttrs, type FixedArgs, type OmitArg, type PopupPosition } from './utils'
+export type { PopupPlacement, PopupPosition } from './utils'
+
+/** Props for shared timing and hover defaults inherited by tooltips. */
+export type TooltipProviderArgs = WithChildren<IntrinsicElements['div'] & {
+	/** Delay before a tooltip opens, in milliseconds. */
+	delayDuration?: number
+	/** Delay window after a tooltip closes. */
+	skipDelayDuration?: number
+	/** Close immediately when pointer leaves the trigger instead of allowing hover over the content. */
+	disableHoverableContent?: boolean
+	/** Additional CSS classes. */
+	class?: string
+	/** Inline CSS string. */
+	style?: string
+}>
+
+/** Props for the tooltip root and its controlled open state. */
+export type TooltipArgs = WithChildren<OmitArg<IntrinsicElements['div'], 'onchange' | ReservedPositionArg> & PopupPosition & {
+	/** Controlled open state. */
+	open?: boolean
+	/** Initial open state for uncontrolled usage. */
+	defaultOpen?: boolean
+	/** Disable trigger activation. */
+	disabled?: boolean
+	/** Delay before this tooltip opens, in milliseconds. */
+	delayDuration?: number
+	/** Close immediately when pointer leaves the trigger instead of allowing hover over the content. */
+	disableHoverableContent?: boolean
+	/** Called whenever the tooltip opens or closes. */
+	onOpenChange?: (open: boolean, event?: Event) => void
+	/** Additional CSS classes. */
+	class?: string
+}> & FixedArgs<'onchange' | ReservedPositionArg>
+
+/** Props for the button or span that opens a tooltip. */
+export type TooltipTriggerArgs = WithChildren<(IntrinsicElements['button'] & IntrinsicElements['span']) & {
+	/** Render the trigger wrapper as a button or span. */
+	as?: 'button' | 'span'
+	/** Additional CSS classes. */
+	class?: string
+}>
+
+/** Props for the positioned tooltip panel. */
+export type TooltipContentArgs = WithChildren<OmitArg<IntrinsicElements['div'], 'align' | 'arrow' | 'id' | 'popover' | 'role' | 'tabindex' | 'tabIndex' | ReservedPositionArg> & {
+	/** Additional CSS classes. */
+	class?: string
+	/** Inline CSS string. */
+	style?: string
+}> & FixedArgs<'arrow' | 'gap' | 'id' | 'placement' | 'popover' | 'role' | 'tabindex' | 'tabIndex' | ReservedPositionArg>
+
+type ProviderContextValue = {
+	delayDuration: number
+	disableHoverableContent: boolean
+	markClosed: () => void
+	shouldSkipDelay: () => boolean
+}
+
+type TooltipContextValue = {
+	arrowAttrs: PopupView['arrowAttrs']
+	contentId: string
+	contentStyle: PopupView['contentStyle']
+	disabled: boolean
+	open: boolean
+	registerContentHover: (hovering: boolean, event?: Event) => void
+	registerFocus: (focused: boolean, event?: Event) => void
+	registerTriggerHover: (hovering: boolean, event?: Event) => void
+	setContent: (element: HTMLDivElement | null) => void
+	setTrigger: (element: HTMLElement | null) => void
+	triggerId: string
+}
+
+const ProviderContext = context<ProviderContextValue | null>(null)
+const TooltipContext = context<TooltipContextValue | null>(null)
+
+const TooltipProviderRoot: Stateful<TooltipProviderArgs> = function* () {
+	let lastClosedAt = 0
+	let skipDelayDuration = 300
+
+	for (const args of this) {
+		skipDelayDuration = Math.max(0, Number(args.skipDelayDuration ?? 300))
+
+		ProviderContext({
+			delayDuration: Math.max(0, Number(args.delayDuration ?? 0)),
+			disableHoverableContent: Boolean(args.disableHoverableContent),
+			markClosed: () => lastClosedAt = Date.now(),
+			shouldSkipDelay: () => skipDelayDuration > 0 && Date.now() - lastClosedAt < skipDelayDuration,
+		})
+
+		yield <>{args.children}</>
+	}
+}
+
+
+/** Unstyled shared defaults provider for descendant tooltips. */
+const TooltipProvider: Stateless<TooltipProviderArgs> = ({
+	children,
+	class: classes,
+	'data-slot': slot = 'tooltip-provider',
+	delayDuration,
+	disableHoverableContent,
+	skipDelayDuration,
+	style,
+	...attrs
+}) => (
+	<TooltipProviderRoot
+		{...rootAttrs(attrs)}
+		delayDuration={delayDuration}
+		disableHoverableContent={disableHoverableContent}
+		skipDelayDuration={skipDelayDuration}
+		attr:class={classes}
+		attr:data-slot={slot}
+		attr:style={style}
+	>
+		{children}
+	</TooltipProviderRoot>
+)
+
+const TooltipRoot: Stateful<TooltipArgs> = function* ({ defaultOpen, open }) {
+	let delayDuration = 0
+	let disabled = false
+	let disableHoverableContent = false
+	let onOpenChange: TooltipArgs['onOpenChange']
+	let provider: ProviderContextValue | null = null
+	let tip: PopupView<HTMLElement, HTMLDivElement>
+
+	tip = popup<HTMLElement, HTMLDivElement>(this, {
+		prefix: 'tooltip',
+		profile: 'tooltip',
+		initialOpen: Boolean(open ?? defaultOpen),
+		disabled: () => disabled,
+		hover: {
+			openDelay: () => delayDuration <= 0 || provider?.shouldSkipDelay() ? 0 : delayDuration,
+			closeDelay: () => disableHoverableContent ? 0 : 80,
+		},
+		onOpenChange: (next, event) => onOpenChange?.(next, event),
+		onSync: next => {
+			if (!next) provider?.markClosed()
+		},
+		referenceHidden: 'hide',
+		dismiss: {
+			prevent: true,
+			onDismiss: (event, view) => {
+				view.cancelHover()
+				view.setOpen(false, event)
+			},
+		},
+	})
+
+	const registerContentHover = (hovering: boolean, event?: Event) => {
+		if (hovering) {
+			if (!disableHoverableContent) tip.hold('content', event as Event)
+		}
+		else tip.release('content', event as Event)
+	}
+
+	const registerTriggerHover = (hovering: boolean, event?: Event) => {
+		if (hovering) tip.hold('trigger', event as Event)
+		else tip.release('trigger', event as Event)
+	}
+
+	const registerFocus = (next: boolean, event?: Event) => {
+		if (next) tip.hold('focus', event as Event)
+		else tip.release('focus', event as Event)
+	}
+
+	for (const args of this) {
+		provider = ProviderContext()
+		delayDuration = Math.max(0, Number(args.delayDuration ?? provider?.delayDuration ?? 0))
+		disabled = Boolean(args.disabled)
+		disableHoverableContent = Boolean(args.disableHoverableContent ?? provider?.disableHoverableContent)
+		onOpenChange = args.onOpenChange
+		const opened = tip.sync(args.open == null ? null : Boolean(args.open), {
+			placement: args.placement,
+			gap: args.gap,
+		})
+
+		TooltipContext({
+			...tip,
+			disabled,
+			open: opened,
+			registerContentHover,
+			registerFocus,
+			registerTriggerHover,
+		})
+
+		yield <>{args.children}</>
+	}
+}
+
+
+/** Unstyled root provider for one tooltip. */
+const Tooltip: Stateless<TooltipArgs> = ({
+	children,
+	class: classes,
+	'data-slot': slot = 'tooltip',
+	defaultOpen,
+	delayDuration,
+	disabled,
+	disableHoverableContent,
+	gap,
+	onOpenChange,
+	open,
+	placement,
+	...attrs
+}) => (
+	<TooltipRoot
+		{...rootAttrs(attrs)}
+		defaultOpen={defaultOpen}
+		delayDuration={delayDuration}
+		disabled={disabled}
+		disableHoverableContent={disableHoverableContent}
+		gap={gap}
+		onOpenChange={onOpenChange}
+		open={open}
+		placement={placement}
+		attr:class={classes}
+		attr:data-slot={slot}
+	>
+		{children}
+	</TooltipRoot>
+)
+
+/** Unstyled element that owns the tooltip description. */
+const TooltipTrigger: Stateless<TooltipTriggerArgs> = ({
+	as = 'button',
+	children,
+	class: classes,
+	'data-slot': slot = 'tooltip-trigger',
+	disabled,
+	id,
+	ref,
+	type = 'button',
+	'aria-describedby': describedBy,
+	'set:onblur': onBlur,
+	'set:onfocus': onFocus,
+	'set:onkeydown': onKeydown,
+	'set:onmouseleave': onMouseLeave,
+	'set:onmouseenter': onMouseEnter,
+	...attrs
+}) => {
+	const tooltip = TooltipContext()
+	const disabledFlag = Boolean(disabled ?? tooltip?.disabled)
+	const descriptions = [...new Set(
+		`${describedBy ?? ''} ${tooltip?.contentId ?? ''}`.trim().split(/\s+/).filter(Boolean),
+	)].join(' ') || undefined
+
+	const common = {
+		...attrs,
+		...triggerAttrs({
+			describedby: descriptions,
+			id,
+			open: Boolean(tooltip?.open),
+			ref,
+			setTrigger: tooltip?.setTrigger,
+			triggerId: tooltip?.triggerId,
+		}),
+		class: classes,
+		'data-slot': slot,
+		'set:onblur': (event: FocusEvent) => {
+			callHandler(onBlur, event)
+			tooltip?.registerFocus(false, event)
+		},
+		'set:onfocus': (event: FocusEvent) => {
+			callHandler(onFocus, event)
+			if (event.defaultPrevented || disabledFlag) return
+			tooltip?.registerFocus(true, event)
+		},
+		'set:onkeydown': (event: KeyboardEvent) => {
+			callHandler(onKeydown, event)
+		},
+		'set:onmouseleave': (event: MouseEvent) => {
+			callHandler(onMouseLeave, event)
+			tooltip?.registerTriggerHover(false, event)
+		},
+		'set:onmouseenter': (event: MouseEvent) => {
+			callHandler(onMouseEnter, event)
+			if (event.defaultPrevented || disabledFlag) return
+			tooltip?.registerTriggerHover(true, event)
+		},
+	}
+
+	if (as === 'span') {
+		return (
+			<span
+				{...common}
+				aria-disabled={disabledFlag ? 'true' : undefined}
+			>
+				{children}
+			</span>
+		)
+	}
+
+	return (
+		<button
+			{...common}
+			disabled={disabledFlag}
+			type={type}
+		>
+			{children}
+		</button>
+	)
+}
+
+/** Unstyled non-interactive text bubble shown for a TooltipTrigger. */
+const TooltipContent: Stateless<TooltipContentArgs> = ({
+	children,
+	class: classes,
+	'data-slot': slot = 'tooltip-content',
+	ref,
+	style,
+	'set:onmouseleave': onMouseLeave,
+	'set:onmouseenter': onMouseEnter,
+	...attrs
+}) => {
+	const tooltip = TooltipContext()
+
+	return (
+		<div
+			{...attrs}
+			{...contentAttrs({
+				id: tooltip?.contentId,
+				open: Boolean(tooltip?.open),
+				ref,
+				setContent: tooltip?.setContent,
+				style: tooltip?.contentStyle(style) ?? popupStyle(style),
+				tabindex: undefined,
+			})}
+			class={classes}
+			data-arrow="true"
+			data-slot={slot}
+			role="tooltip"
+			set:onmouseleave={(event: MouseEvent) => {
+				callHandler(onMouseLeave, event)
+				tooltip?.registerContentHover(false, event)
+			}}
+			set:onmouseenter={(event: MouseEvent) => {
+				callHandler(onMouseEnter, event)
+				tooltip?.registerContentHover(true, event)
+			}}
+		>
+			<PopupSurface arrow popup={tooltip} />
+			{children}
+		</div>
+	)
+}
+
+export {
+	Tooltip,
+	TooltipContent,
+	TooltipProvider,
+	TooltipTrigger,
+}

package/src/utils.ts

@@ -0,0 +1,204 @@
+import type { Stateless } from 'ajo'
+import { callRef } from 'ajo-cloves'
+import { jsx } from 'ajo/jsx-runtime'
+
+type SlotArgs = Record<string, unknown> & { 'data-slot'?: string }
+
+/** Logical placement shared by Ajo popup roots. */
+export type PopupPlacement =
+	| 'top' | 'top-start' | 'top-end'
+	| 'right' | 'right-start' | 'right-end'
+	| 'bottom' | 'bottom-start' | 'bottom-end'
+	| 'left' | 'left-start' | 'left-end'
+	| 'auto'
+
+/** Small semantic positioning contract shared by Ajo popup roots. */
+export type PopupPosition = {
+	/** Preferred logical placement; auto chooses the most available space. */
+	placement?: PopupPlacement
+	/** Distance between the reference and floating box, in CSS pixels. */
+	gap?: number
+}
+
+type TriggerAttrsOptions<Element extends HTMLElement> = {
+	controls?: string
+	describedby?: string
+	expanded?: boolean
+	haspopup?: 'dialog' | 'listbox' | 'menu'
+	id?: unknown
+	open: boolean
+	ref?: unknown
+	setTrigger?: (element: Element | null) => void
+	triggerId?: string
+}
+
+/** Builds state, popup relations, ids and a composed trigger ref. */
+export const triggerAttrs = <Element extends HTMLElement>(options: TriggerAttrsOptions<Element>): Record<string, unknown> => {
+	const { controls, describedby, expanded, haspopup, id, open, ref, setTrigger, triggerId } = options
+	const attrs: Record<string, unknown> = { 'data-state': open ? 'open' : 'closed' }
+	if ('controls' in options) attrs['aria-controls'] = controls
+	if ('describedby' in options) attrs['aria-describedby'] = describedby
+	if ('expanded' in options) attrs['aria-expanded'] = expanded ? 'true' : 'false'
+	if ('haspopup' in options) attrs['aria-haspopup'] = haspopup
+	if ('id' in options || 'triggerId' in options) attrs.id = id ?? triggerId
+	if ('ref' in options || 'setTrigger' in options) {
+		attrs.ref = (element: Element | null) => {
+			setTrigger?.(element)
+			callRef(ref, element)
+		}
+	}
+	return attrs
+}
+
+/** Inline reset for a native popover plus caller-owned declarations. */
+export const popupStyle = (...parts: unknown[]) =>
+	['inset:auto', 'margin:0', ...parts.filter((part): part is string => typeof part === 'string' && part.length > 0)].join(';')
+
+/** Omits named arguments without collapsing Ajo's open Args index signature. */
+export type OmitArg<T, Keys extends PropertyKey> = {
+	[Key in keyof T as Key extends Keys ? never : Key]: T[Key]
+}
+
+/** Marks component arguments owned by an adapter as unavailable to callers. */
+export type FixedArgs<Keys extends PropertyKey> = {
+	[Key in Keys]?: never
+}
+
+/** Wraps a re-exported family part with a fixed data-slot and optional defaults. */
+export const withSlot = <Args extends SlotArgs>(
+	Component: Stateless<Args>,
+	slot: string,
+	defaults?: Partial<Args>,
+): Stateless<Args> => attrs => jsx(Component, { ...defaults, ...attrs, 'data-slot': slot })
+
+/** Marks a boolean state attr: 'true' when set, absent otherwise. */
+export const flag = (value: unknown) => value ? 'true' : undefined
+
+/** Parses boolean-ish attr input (true, '', 'true'). */
+export const bool = (value: unknown) =>
+	value === true || value === '' || value === 'true'
+
+/** Normalized state shared by native and visual checked controls. */
+export type CheckedState = 'checked' | 'indeterminate' | 'unchecked'
+
+/** Maps a checked-state token to the native aria-checked vocabulary. */
+export const ariaChecked = (state: CheckedState) =>
+	state === 'indeterminate' ? 'mixed' : state === 'checked' ? 'true' : 'false'
+
+/** Mirrors a native input's live checked state onto it and one visual companion. */
+export const syncCheckedState = (input: HTMLInputElement, companion?: HTMLElement | null): CheckedState => {
+	const state = input.type === 'checkbox' && input.indeterminate
+		? 'indeterminate'
+		: input.checked ? 'checked' : 'unchecked'
+	input.dataset.state = state
+	input.setAttribute('aria-checked', ariaChecked(state))
+	if (companion) companion.dataset.state = state
+	return state
+}
+
+/** Flattens JSX children into their concatenated plain-text content. */
+export const text = (value: unknown): string => {
+	if (value == null || value === false) return ''
+	if (typeof value === 'string' || typeof value === 'number' || typeof value === 'bigint') return String(value)
+	if (Array.isArray(value)) return value.map(text).join('')
+	return ''
+}
+
+/** Copies a multi-value array while coercing each present value to a string. */
+export const strings = (value: unknown): string[] =>
+	Array.isArray(value) ? value.map(String) : []
+
+/** Token match: every whitespace-separated search token appears in the haystack, case-insensitive; an empty search matches. */
+export const matchesTokens = (search: string, haystack: string) => {
+	const query = search.trim().toLowerCase()
+	if (!query) return true
+	const target = haystack.trim().toLowerCase()
+	return query.split(/\s+/).every(part => target.includes(part))
+}
+
+/** Formats the default English result count for filterable collections. */
+export const defaultResultsLabel = (count: number) =>
+	`${count} result${count === 1 ? '' : 's'}`
+
+const passAll = () => true
+
+/** Resolves undefined to the built-in filter, null to unfiltered, and preserves a custom filter. */
+export const resolveFilter = <Args extends unknown[]>(
+	filter: ((...args: Args) => boolean) | null | undefined,
+	fallback: (...args: Args) => boolean,
+): ((...args: Args) => boolean) =>
+	filter === undefined ? fallback : filter ?? passAll
+
+/** Joins conditional class names, returning undefined when empty. */
+export const clx = (...values: Array<string | false | null | undefined>) =>
+	values.filter(Boolean).join(' ') || undefined
+
+/** Coerces to a finite number, falling back otherwise. */
+export const toNumber = (value: unknown, fallback: number) => {
+	const next = Number(value)
+	return Number.isFinite(next) ? next : fallback
+}
+
+/** Returns true when JSX children carry no visible content. */
+export const emptyChildren = (children: unknown) =>
+	children == null ||
+	children === false ||
+	(Array.isArray(children) && children.every(child => child == null || child === false))
+
+type DomStyleProperty = Exclude<{
+	[Key in keyof CSSStyleDeclaration]-?: Key extends string
+		? CSSStyleDeclaration[Key] extends string ? Key : never
+		: never
+}[keyof CSSStyleDeclaration], 'cssText'>
+
+type KebabCase<Value extends string> = Value extends `${infer Head}${infer Tail}`
+	? Head extends Lowercase<Head>
+		? `${Head}${KebabCase<Tail>}`
+		: `-${Lowercase<Head>}${KebabCase<Tail>}`
+	: Value
+
+type StyleProperty = DomStyleProperty | KebabCase<DomStyleProperty>
+
+/** Primitive value accepted by one inline style property. */
+export type StyleValue = string | number | false | null | undefined
+
+/** Typed inline style properties, including custom CSS variables. */
+export type StyleObject = {
+	[Key in StyleProperty]?: StyleValue
+} & {
+	[Key in `--${string}`]?: StyleValue
+}
+
+/** Recursive input accepted by the inline style serializer. */
+export type StyleInput = StyleValue | true | StyleObject | readonly StyleInput[]
+
+const property = (key: string) => {
+	if (key === 'cssFloat') return 'float'
+	if (key.startsWith('--')) return key
+	const css = key.replace(/[A-Z]/g, match => `-${match.toLowerCase()}`)
+	return css.startsWith('ms-') ? `-${css}` : css
+}
+
+const collectStyles = (input: StyleInput, result: string[]) => {
+	if (!input || input === true || typeof input === 'number') return
+	if (typeof input === 'string') {
+		const value = input.trim().replace(/;+$/, '')
+		if (value) result.push(value)
+		return
+	}
+	if (Array.isArray(input)) {
+		for (const item of input) collectStyles(item, result)
+		return
+	}
+	for (const [key, value] of Object.entries(input)) {
+		if (value == null || value === false) continue
+		result.push(`${property(key)}:${value}`)
+	}
+}
+
+/** Build an inline style string from strings, objects, arrays, and falsey entries. */
+export const stlx = (...input: StyleInput[]) => {
+	const result: string[] = []
+	for (const item of input) collectStyles(item, result)
+	return result.join(';')
+}