sheer-ui 0.0.0

package/src/lib/internal/escape-layer/use-escape-layer.svelte.ts

@@ -0,0 +1,91 @@
+import {
+	DOMContext,
+	boxWith,
+	type Box,
+	type Getter,
+	type ReadableBox,
+	type ReadableBoxedValues,
+	type RefAttachment,
+} from '../tools/index.js';
+import { untrack } from 'svelte';
+import { on } from 'svelte/events';
+import { createAttachmentKey } from 'svelte/attachments';
+import type { EscapeBehaviorType, EscapeLayerImplProps } from './types.js';
+import { kbd } from '../kbd.js';
+import { createLayerStack } from '../layer-stack.js';
+import { globalSingleton } from '../global-singleton.js';
+
+const escapeLayers = globalSingleton('bitsEscapeLayers', () =>
+	createLayerStack<EscapeLayerState, ReadableBox<EscapeBehaviorType>>(
+		(box) => box.current === 'close' || box.current === 'ignore',
+	),
+);
+
+interface EscapeLayerStateOpts extends ReadableBoxedValues<Required<Omit<EscapeLayerImplProps, 'children' | 'ref'>>> {
+	ref: Box<HTMLElement | null>;
+}
+
+export class EscapeLayerState {
+	static create(opts: EscapeLayerStateOpts) {
+		return new EscapeLayerState(opts);
+	}
+	readonly opts: EscapeLayerStateOpts;
+	readonly domContext: DOMContext;
+
+	constructor(opts: EscapeLayerStateOpts) {
+		this.opts = opts;
+		this.domContext = new DOMContext(this.opts.ref);
+
+		$effect(() => {
+			if (!opts.enabled.current) return;
+
+			const unsubEvents = untrack(() => {
+				escapeLayers.register(this, opts.escapeKeydownBehavior);
+				return on(this.domContext.getDocument(), 'keydown', this.#onkeydown, { passive: false });
+			});
+
+			return () => {
+				unsubEvents();
+				escapeLayers.unregister(this);
+			};
+		});
+	}
+
+	#onkeydown = (e: KeyboardEvent) => {
+		if (e.key !== kbd.ESCAPE || !escapeLayers.isResponsible(this)) return;
+		const clonedEvent = new KeyboardEvent(e.type, e);
+		e.preventDefault();
+		const behaviorType = this.opts.escapeKeydownBehavior.current;
+		if (behaviorType !== 'close' && behaviorType !== 'defer-otherwise-close') return;
+		this.opts.onEscapeKeydown.current(clonedEvent);
+	};
+}
+
+/**
+ * The escape-key behavior as a spreadable Svelte attachment. Merge it into the props that
+ * land on the element which should participate in the global Escape stack, instead of nesting
+ * a renderless `<EscapeLayer>` wrapper. The element owns the lifecycle: on mount it registers
+ * in `bitsEscapeLayers` and listens for `keydown` on its owner document; on removal it
+ * deregisters and unsubscribes (via the `EscapeLayerState` effect). The stack and the
+ * responsibility algorithm are unchanged.
+ */
+export function escapeKeydownAttachment(opts: {
+	escapeKeydownBehavior: Getter<EscapeBehaviorType>;
+	onEscapeKeydown: Getter<(e: KeyboardEvent) => void>;
+	enabled: Getter<boolean>;
+}): RefAttachment<HTMLElement> {
+	return {
+		[createAttachmentKey()]: (node) => {
+			EscapeLayerState.create({
+				escapeKeydownBehavior: boxWith(opts.escapeKeydownBehavior),
+				onEscapeKeydown: boxWith(opts.onEscapeKeydown),
+				enabled: boxWith(opts.enabled),
+				// The state only reads the ref (to resolve the owner document), so a no-op setter is fine.
+				ref: boxWith(
+					() => node,
+					() => {},
+				),
+			});
+		},
+	};
+}

package/src/lib/internal/floating-layer/components/floating-layer-arrow.svelte

@@ -0,0 +1,35 @@
+<script lang="ts">
+	import { boxWith } from '../../tools/index.js';
+	import { mergeProps } from '../../merge-props.js';
+	import { FloatingArrowState } from '../use-floating-layer.svelte.js';
+	import type { FloatingLayerArrowProps } from '../types.js';
+	import { createId } from '../../create-id.js';
+
+	const uid = $props.id();
+
+	let { id = createId(uid), ref = $bindable(null), children, child, width = 10, height = 5, ...restProps }: FloatingLayerArrowProps = $props();
+
+	const arrowState = FloatingArrowState.create({
+		id: boxWith(() => id),
+		ref: boxWith(
+			() => ref,
+			(v) => (ref = v),
+		),
+	});
+
+	const mergedProps = $derived(mergeProps(restProps, arrowState.props));
+</script>
+
+{#if child}
+	{@render child({ props: mergedProps })}
+{:else}
+	<span {...mergedProps}>
+		{#if children}
+			{@render children?.()}
+		{:else}
+			<svg {width} {height} viewBox="0 0 30 10" preserveAspectRatio="none" data-arrow="">
+				<polygon points="0,0 30,0 15,10" fill="currentColor" />
+			</svg>
+		{/if}
+	</span>
+{/if}

package/src/lib/internal/floating-layer/components/floating-layer-content-static.svelte

@@ -0,0 +1,19 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import { createAttachmentKey } from 'svelte/attachments';
+
+	let {
+		content,
+		onPlaced,
+	}: {
+		content?: Snippet<[{ props: Record<string, unknown> }]>;
+		onPlaced?: () => void;
+	} = $props();
+
+	// Static content needs no positioning pass — it is "placed" as soon as the consumer's
+	// element (which receives these props) hits the DOM. Hoisted so the attachment identity
+	// is stable across renders.
+	const placed = { [createAttachmentKey()]: () => onPlaced?.() };
+</script>
+
+{@render content?.({ props: placed })}

package/src/lib/internal/floating-layer/components/floating-layer-content.svelte

@@ -0,0 +1,52 @@
+<script lang="ts">
+	import { boxWith } from '../../tools/index.js';
+	import { FloatingContentState } from '../use-floating-layer.svelte.js';
+	import type { ContentImplProps } from './index.js';
+
+	let {
+		content,
+		side = 'bottom',
+		sideOffset = 0,
+		align = 'center',
+		alignOffset = 0,
+		id,
+		arrowPadding = 0,
+		avoidCollisions = true,
+		collisionPadding = 0,
+		hideWhenDetached = false,
+		onPlaced = () => {},
+		dir = 'ltr',
+		style = {},
+		customAnchor = null,
+		enabled,
+		present,
+		tooltip = false,
+	}: ContentImplProps = $props();
+
+	const contentState = FloatingContentState.create(
+		{
+			side: boxWith(() => side),
+			sideOffset: boxWith(() => sideOffset),
+			align: boxWith(() => align),
+			alignOffset: boxWith(() => alignOffset),
+			id: boxWith(() => id),
+			arrowPadding: boxWith(() => arrowPadding),
+			avoidCollisions: boxWith(() => avoidCollisions),
+			collisionPadding: boxWith(() => collisionPadding),
+			hideWhenDetached: boxWith(() => hideWhenDetached),
+			onPlaced: boxWith(() => onPlaced),
+			dir: boxWith(() => dir),
+			style: boxWith(() => style),
+			enabled: boxWith(() => enabled),
+			present: boxWith(() => present ?? enabled),
+			customAnchor: boxWith(() => customAnchor),
+		},
+		tooltip,
+	);
+</script>
+
+<!-- a virtual anchor precedes the content, as CSS anchor resolution requires -->
+{#if contentState.virtualAnchorStyle}
+	<span style={contentState.virtualAnchorStyle}></span>
+{/if}
+{@render content?.({ props: contentState.props })}

package/src/lib/internal/floating-layer/components/floating-layer.svelte

@@ -0,0 +1,12 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import { FloatingRootState } from '../use-floating-layer.svelte.js';
+
+	let { children, tooltip = false }: { children?: Snippet; tooltip?: boolean } = $props();
+	const uid = $props.id();
+
+	// The anchor name is per root: one trigger/content pair positions against it.
+	FloatingRootState.create(`--bits-anchor-${uid}`, tooltip);
+</script>
+
+{@render children?.()}

package/src/lib/internal/floating-layer/components/index.ts

@@ -0,0 +1,6 @@
+export { default as Arrow } from './floating-layer-arrow.svelte';
+export { default as Content } from './floating-layer-content.svelte';
+export { default as ContentStatic } from './floating-layer-content-static.svelte';
+export { default as Root } from './floating-layer.svelte';
+
+export type { FloatingLayerContentImplProps as ContentImplProps, FloatingLayerContentProps as ContentProps } from '../types.js';

package/src/lib/internal/floating-layer/index.ts

@@ -0,0 +1,2 @@
+export * as FloatingLayer from './components/index.js';
+export { floatingAnchor, getFloatingContentCSSVars, setFloatingAnchor, type Measurable } from './use-floating-layer.svelte.js';

package/src/lib/internal/floating-layer/types.ts

@@ -0,0 +1,126 @@
+import type { Snippet } from 'svelte';
+import type { Align, Measurable, Side } from './use-floating-layer.svelte.js';
+import type { WithChild } from '../types.js';
+import type { Direction, StyleProperties } from '../index.js';
+import type { BitsPrimitiveSpanAttributes } from '../attribute-types.js';
+
+export type FloatingLayerContentProps = {
+	/**
+	 * The preferred side of the anchor to render against when open.
+	 * Flipped when it would overflow the viewport.
+	 */
+	side?: Side;
+
+	/**
+	 * The distance in pixels from the anchor to the floating element.
+	 */
+	sideOffset?: number;
+
+	/**
+	 * The preferred alignment of the anchor to render against when open.
+	 * Flipped when it would overflow the viewport.
+	 */
+	align?: Align;
+
+	/**
+	 * An offset in pixels from the "start" or "end" alignment options.
+	 */
+	alignOffset?: number | undefined;
+
+	/**
+	 * This describes the padding between the arrow and the edges of the floating element.
+	 * If your floating element has border-radius, this will prevent it from overflowing
+	 * the corners.
+	 */
+	arrowPadding?: number;
+
+	/**
+	 * When `true`, the `side` and `align` flip to keep the content inside the viewport.
+	 *
+	 * @default true
+	 */
+	avoidCollisions?: boolean | undefined;
+
+	/**
+	 * The amount in pixels of virtual padding around the viewport edges the content keeps
+	 * clear of.
+	 *
+	 * @default 0
+	 */
+	collisionPadding?: number | Partial<Record<Side, number>>;
+
+	/**
+	 * Hides the content while its anchor is scrolled out of view (`position-visibility`).
+	 *
+	 * @default false
+	 */
+	hideWhenDetached?: boolean;
+
+	content?: Snippet<[{ props: Record<string, unknown> }]>;
+
+	/**
+	 * The text direction of the content.
+	 */
+	dir?: Direction;
+
+	/**
+	 * Whether to prevent scrolling the body when the content is open.
+	 */
+	preventScroll?: boolean;
+
+	/**
+	 * Use an element other than the trigger to anchor the content to. If provided,
+	 * the content will be anchored to the provided element instead of the trigger.
+	 *
+	 * You can pass a selector string or an HTMLElement.
+	 */
+	customAnchor?: string | HTMLElement | Measurable | null;
+};
+
+export type FloatingLayerContentImplProps = {
+	id: string;
+
+	/**
+	 * The style properties to apply to the content.
+	 */
+	style?: StyleProperties | string | null;
+
+	/**
+	 * Callback that is called when the floating element is placed.
+	 */
+	onPlaced?: () => void;
+	enabled: boolean;
+	/**
+	 * Open, or closed with the exit transition still running. A closed-at-rest surface
+	 * drops its anchored position style so it costs anchor layout nothing.
+	 * @default enabled
+	 */
+	present?: boolean;
+	/**
+	 * Tooltips are special in that they are commonly composed
+	 * with other floating components, where the same trigger is
+	 * used for both the tooltip and the popover.
+	 *
+	 * For situations like this, we need to use a different context
+	 * symbol so that conflicts don't occur.
+	 */
+	tooltip?: boolean;
+} & FloatingLayerContentProps;
+
+export type FloatingLayerArrowPropsWithoutHTML = WithChild<{
+	/**
+	 * The width of the arrow in pixels.
+	 *
+	 * @defaultValue 10
+	 */
+	width?: number;
+
+	/**
+	 * The height of the arrow in pixels.
+	 *
+	 * @defaultValue 5
+	 */
+	height?: number;
+}>;
+
+export type FloatingLayerArrowProps = FloatingLayerArrowPropsWithoutHTML & BitsPrimitiveSpanAttributes;