sheer-ui 0.0.0

package/src/lib/internal/paneforge/types.ts

@@ -0,0 +1,179 @@
+import type { HTMLAttributes } from 'svelte/elements';
+import type { Without, WithChild } from '../index.js';
+import type { Direction, PaneOnCollapse, PaneOnExpand, PaneOnResize, PaneResizeHandleOnDragging } from './internal/types.js';
+import type { PaneGroupStorage } from './internal/utils/storage.js';
+
+type Primitive<T> = Omit<T, 'id' | 'children'> & { id?: string | undefined };
+
+export type PaneForgePrimitiveDivAttributes = Primitive<HTMLAttributes<HTMLDivElement>>;
+
+export type PanePropsWithoutHTML = WithChild<{
+	/**
+	 * The size of the pane when it is in a collapsed state.
+	 */
+	collapsedSize?: number;
+
+	/**
+	 * Whether the pane can be collapsed.
+	 *
+	 * @defaultValue `false`
+	 */
+	collapsible?: boolean;
+
+	/**
+	 * The default size of the pane in percentage.
+	 */
+	defaultSize?: number;
+
+	/**
+	 * The maximum size of the pane in percentage of the group's size.
+	 *
+	 * @defaultValue `100`
+	 */
+	maxSize?: number;
+
+	/**
+	 * The minimum size of the pane in percentage of the group's size.
+	 *
+	 * @defaultValue `0`
+	 */
+	minSize?: number;
+
+	/**
+	 * The order of the pane in the group.
+	 * Useful for maintaining order when conditionally rendering panes.
+	 */
+	order?: number;
+
+	/**
+	 * A callback that is called when the pane is collapsed.
+	 */
+	onCollapse?: PaneOnCollapse;
+
+	/**
+	 * A callback that is called when the pane is expanded.
+	 */
+	onExpand?: PaneOnExpand;
+
+	/**
+	 * A callback that is called when the pane is resized.
+	 */
+	onResize?: PaneOnResize;
+}>;
+
+export type PaneProps = PanePropsWithoutHTML & Without<PaneForgePrimitiveDivAttributes, PanePropsWithoutHTML>;
+
+export type PaneGroupPropsWithoutHTML = WithChild<{
+	/**
+	 * The id to save the layout of the panes to in local storage.
+	 */
+	autoSaveId?: string | null;
+
+	/**
+	 * The direction of the panes.
+	 *
+	 * @required
+	 */
+	direction: Direction;
+
+	/**
+	 * The amount of space to add to the pane group when the keyboard
+	 * resize event is triggered.
+	 */
+	keyboardResizeBy?: number | null;
+
+	/**
+	 * A callback called when the layout of the panes within the group changes.
+	 */
+	onLayoutChange?: (layout: number[]) => void | null;
+
+	/**
+	 * The storage object to use for saving the layout of the panes in the group.
+	 */
+	storage?: PaneGroupStorage;
+}>;
+
+export type PaneGroupProps = PaneGroupPropsWithoutHTML & Without<PaneForgePrimitiveDivAttributes, PaneGroupPropsWithoutHTML>;
+
+export type PaneResizerPropsWithoutHTML = WithChild<{
+	/**
+	 * Whether the resize handle is disabled.
+	 *
+	 * @defaultValue `false`
+	 */
+	disabled?: boolean;
+
+	/**
+	 * A callback that is called when the resize handle is being dragged.
+	 */
+	onDraggingChange?: PaneResizeHandleOnDragging;
+
+	/**
+	 * The tabindex of the resize handle.
+	 */
+	tabindex?: number;
+}>;
+
+export type PaneResizerProps = PaneResizerPropsWithoutHTML & Without<PaneForgePrimitiveDivAttributes, PaneResizerPropsWithoutHTML>;
+
+export type PaneAPI = {
+	/* Collapse the pane to its minimum size */
+	collapse: () => void;
+	/* Expand the pane to its previous size */
+	expand: () => void;
+	/* Get the pane's id */
+	getId: () => string;
+	/** Get the panes size */
+	getSize: () => number;
+	/** Check if the pane is collapsed */
+	isCollapsed: () => boolean;
+	/** Check if the pane is expanded */
+	isExpanded: () => boolean;
+	/** Resize the pane to the specified size */
+	resize: (size: number) => void;
+};
+
+export type PaneGroupAPI = {
+	/** Get the ID of the PaneGroup */
+	getId: () => string;
+	/** Get the layout of the PaneGroup */
+	getLayout: () => number[];
+	/** Set the layout of the PaneGroup */
+	setLayout: (layout: number[]) => void;
+};
+
+/**
+ * Data attributes applied to the element rendered by the `Pane` component.
+ */
+export type PaneAttributes = {
+	/** Applied to every pane element. */
+	'data-pane': string;
+	/** The ID of the pane. */
+	'data-pane-id': string;
+	/** The ID of the pane's group. */
+	'data-pane-group-id': string;
+};
+
+export type PaneGroupAttributes = {
+	/** Applied to every pane group element. */
+	'data-pane-group': string;
+	/** The direction of the pane group. */
+	'data-direction': Direction;
+	/** The ID of the pane group. */
+	'data-pane-group-id': string;
+};
+
+export type PaneResizerAttributes = {
+	/** Applied to all resizer elements */
+	'data-pane-resizer': string;
+	/** The direction of the pane group the resize handle belongs to. */
+	'data-direction': Direction;
+	/** The ID of the pane group the resize handle belongs to. */
+	'data-pane-group-id': string;
+	/** Whether the resize handle is active or not. */
+	'data-active'?: 'pointer' | 'keyboard';
+	/** Whether the resize handle is enabled or not. */
+	'data-enabled'?: boolean;
+	/** The ID of the resize handle. */
+	'data-pane-resizer-id': string;
+};

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

@@ -0,0 +1,2 @@
+export { default as PopperLayer } from "./popper-layer.svelte";
+export type { PopperLayerProps } from "./types.js";

package/src/lib/internal/popper-layer/popper-content.svelte

@@ -0,0 +1,19 @@
+<script lang="ts">
+	import FloatingLayerContentStatic from "../floating-layer/components/floating-layer-content-static.svelte";
+	import FloatingLayerContent from "../floating-layer/components/floating-layer-content.svelte";
+	import type { FloatingLayerContentImplProps } from "../floating-layer/types.js";
+
+	let {
+		content,
+		isStatic = false,
+		onPlaced,
+		...restProps
+	}: FloatingLayerContentImplProps & { isStatic: boolean } = $props();
+
+</script>
+
+{#if isStatic}
+	<FloatingLayerContentStatic {content} {onPlaced} />
+{:else}
+	<FloatingLayerContent {content} {onPlaced} {...restProps} />
+{/if}

package/src/lib/internal/popper-layer/popper-layer-inner.svelte

@@ -0,0 +1,122 @@
+<script lang="ts">
+	import { mergeProps } from '../merge-props.js';
+	import { scrollLockAttachment } from '../body-scroll-lock.svelte.js';
+	import type { PopperLayerImplProps } from './types.js';
+	import PopperContent from './popper-content.svelte';
+	import { escapeKeydownAttachment } from '../escape-layer/use-escape-layer.svelte.js';
+	import { interactOutsideAttachment } from '../dismissible-layer/use-dismissable-layer.svelte.js';
+	import { createFocusScopeProps } from '../focus-scope/focus-scope.svelte.js';
+
+	let {
+		popper,
+		onEscapeKeydown,
+		escapeKeydownBehavior,
+		preventOverflowTextSelection,
+		id,
+		side,
+		sideOffset,
+		align,
+		alignOffset,
+		arrowPadding,
+		avoidCollisions,
+		collisionPadding,
+		hideWhenDetached,
+		dir,
+		preventScroll,
+		style,
+		onPlaced,
+		onInteractOutside,
+		onCloseAutoFocus,
+		onOpenAutoFocus,
+		onFocusOutside,
+		interactOutsideBehavior = 'close',
+		loop,
+		trapFocus = true,
+		isValidEvent,
+		customAnchor = null,
+		isStatic = false,
+		enabled,
+		ref,
+		present,
+		tooltip = false,
+		contentPointerEvents = 'auto',
+		...restProps
+	}: Omit<PopperLayerImplProps, 'open' | 'children' | 'shouldRender'> & {
+		enabled: boolean;
+		contentPointerEvents?: 'auto' | 'none';
+	} = $props();
+
+	const resolvedPreventScroll = $derived(preventScroll ?? true);
+
+	const escapeAttachment = escapeKeydownAttachment({
+		escapeKeydownBehavior: () => escapeKeydownBehavior ?? 'close',
+		onEscapeKeydown: () => onEscapeKeydown ?? (() => {}),
+		enabled: () => enabled,
+	});
+
+	const dismissible = interactOutsideAttachment({
+		id: () => id,
+		interactOutsideBehavior: () => interactOutsideBehavior,
+		onInteractOutside: () => onInteractOutside,
+		onFocusOutside: () => onFocusOutside,
+		enabled: () => enabled,
+		isValidEvent: () => isValidEvent,
+	});
+
+	// Flags the open surface for the CSS text-selection guard in ui.css.
+	const textSelectionGuard = $derived(enabled && (preventOverflowTextSelection ?? true) ? { 'data-text-selection-guard': '' } : {});
+
+	// The content is always mounted, so the lock gates on `present` (open, or still exiting — the
+	// window element lifecycle gave the old <ScrollLock> mount).
+	const isPresent = $derived(present ?? enabled);
+	const scrollLock = scrollLockAttachment({
+		enabled: () => resolvedPreventScroll && isPresent,
+	});
+
+	const focusScope = createFocusScopeProps({
+		enabled: () => enabled,
+		trap: () => trapFocus,
+		loop: () => loop ?? false,
+		onCloseAutoFocus: () => onCloseAutoFocus ?? (() => {}),
+		onOpenAutoFocus: () => onOpenAutoFocus ?? (() => {}),
+	});
+</script>
+
+<PopperContent
+	{isStatic}
+	{id}
+	{side}
+	{sideOffset}
+	{align}
+	{alignOffset}
+	{arrowPadding}
+	{avoidCollisions}
+	{collisionPadding}
+	{hideWhenDetached}
+	{dir}
+	{style}
+	{onPlaced}
+	{customAnchor}
+	{enabled}
+	present={isPresent}
+	{tooltip}>
+	{#snippet content({ props: floatingProps })}
+		{@render popper?.({
+			props: mergeProps(
+				restProps,
+				floatingProps,
+				dismissible.props,
+				dismissible.attachment,
+				focusScope.props,
+				escapeAttachment,
+				textSelectionGuard,
+				scrollLock,
+				{
+					style: {
+						pointerEvents: contentPointerEvents,
+					},
+				},
+			),
+		})}
+	{/snippet}
+</PopperContent>

package/src/lib/internal/popper-layer/popper-layer.svelte

@@ -0,0 +1,71 @@
+<script lang="ts">
+	import type { PopperLayerImplProps } from './types.js';
+	import PopperLayerInner from './popper-layer-inner.svelte';
+
+	let {
+		popper,
+		open,
+		onEscapeKeydown,
+		escapeKeydownBehavior,
+		preventOverflowTextSelection,
+		id,
+		side,
+		sideOffset,
+		align,
+		alignOffset,
+		arrowPadding,
+		avoidCollisions,
+		collisionPadding,
+		hideWhenDetached,
+		dir,
+		preventScroll,
+		style,
+		onPlaced,
+		onInteractOutside,
+		onCloseAutoFocus,
+		onOpenAutoFocus,
+		onFocusOutside,
+		interactOutsideBehavior = 'close',
+		loop,
+		trapFocus = true,
+		isValidEvent = () => false,
+		customAnchor = null,
+		isStatic = false,
+		ref,
+		present,
+		...restProps
+	}: PopperLayerImplProps = $props();
+</script>
+
+<PopperLayerInner
+	{popper}
+	{onEscapeKeydown}
+	{escapeKeydownBehavior}
+	{preventOverflowTextSelection}
+	{id}
+	{side}
+	{sideOffset}
+	{align}
+	{alignOffset}
+	{arrowPadding}
+	{avoidCollisions}
+	{collisionPadding}
+	{hideWhenDetached}
+	{dir}
+	{preventScroll}
+	{style}
+	{onPlaced}
+	{customAnchor}
+	{isStatic}
+	enabled={open}
+	{onInteractOutside}
+	{onCloseAutoFocus}
+	{onOpenAutoFocus}
+	{interactOutsideBehavior}
+	{loop}
+	{trapFocus}
+	{isValidEvent}
+	{onFocusOutside}
+	{present}
+	{ref}
+	{...restProps} />

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

@@ -0,0 +1,65 @@
+import type { Snippet } from "svelte";
+import type { EscapeLayerImplProps, EscapeLayerProps } from "../escape-layer/types.js";
+import type {
+	DismissibleLayerImplProps,
+	DismissibleLayerProps,
+} from "../dismissible-layer/types.js";
+import type {
+	FloatingLayerContentImplProps,
+	FloatingLayerContentProps,
+} from "../floating-layer/types.js";
+import type { TextSelectionGuardProps } from "../types.js";
+import type { ReadableBox } from "../tools/index.js";
+import type { FocusScopeImplProps, FocusScopeProps } from "../focus-scope/types.js";
+import type { ScrollLockProps } from "../body-scroll-lock.svelte.js";
+import type { Direction } from "../index.js";
+
+export type PopperLayerProps = EscapeLayerProps &
+	Omit<DismissibleLayerProps, "onInteractOutsideStart"> &
+	FloatingLayerContentProps &
+	TextSelectionGuardProps &
+	FocusScopeProps &
+	Omit<ScrollLockProps, "restoreScrollDelay">;
+
+export type PopperLayerStaticProps = EscapeLayerProps &
+	Omit<DismissibleLayerProps, "onInteractOutsideStart"> &
+	TextSelectionGuardProps &
+	FocusScopeProps &
+	Omit<ScrollLockProps, "restoreScrollDelay"> & {
+		content?: Snippet<[{ props: Record<string, unknown> }]>;
+		dir?: Direction;
+	};
+
+export type PopperLayerImplProps = Omit<
+	EscapeLayerImplProps &
+		DismissibleLayerImplProps &
+		FloatingLayerContentImplProps &
+		{ open: boolean; ref: ReadableBox<HTMLElement | null> } &
+		TextSelectionGuardProps &
+		FocusScopeImplProps & {
+			popper: Snippet<[{ props: Record<string, unknown> }]>;
+			isStatic?: 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;
+
+			/**
+			 * Whether the always-mounted content is still rendered — open, or closed with its exit
+			 * transition running. Gates the scroll lock. Defaults to the open state.
+			 */
+			present?: boolean;
+
+			/**
+			 * Override for the content's pointer-events style.
+			 * @default "auto"
+			 */
+			contentPointerEvents?: "auto" | "none";
+		},
+	"enabled"
+>;

package/src/lib/internal/portal/index.ts

@@ -0,0 +1,2 @@
+export { default as Portal } from './portal.svelte';
+export type { PortalProps, PortalTarget } from './portal.svelte';

package/src/lib/internal/portal/portal.svelte

@@ -0,0 +1,61 @@
+<script lang="ts" module>
+	import type { Snippet } from 'svelte';
+
+	export type PortalTarget = Element | ShadowRoot | string;
+
+	export type PortalProps = {
+		/**
+		 * Where to portal the content to.
+		 *
+		 * @default document.body
+		 */
+		to?: PortalTarget;
+
+		/**
+		 * Disable portalling and render the component inline
+		 *
+		 * @defaultValue false
+		 */
+		disabled?: boolean;
+
+		/**
+		 * The children content to render within the portal.
+		 */
+		children?: Snippet;
+	};
+</script>
+
+<script lang="ts">
+	import { resolvePortalToProp } from '../prop-resolvers.js';
+	import { DEV } from 'esm-env';
+
+	let { to: toProp, children, disabled }: PortalProps = $props();
+
+	const to = resolvePortalToProp(() => toProp);
+</script>
+
+{#if disabled}
+	{@render children?.()}
+{:else}
+	<div
+		class="contents"
+		{@attach (node) => {
+			// Re-runs when `to` changes: svelte wraps the attachment in an effect, so the
+			// to.current read here is a tracked dependency and a new target re-teleports the node.
+			const t = to.current;
+			const target = typeof t === 'string' ? document.querySelector(t) : t;
+			// ShadowRoot (and other non-Element containers) take appendChild too
+			if (!(target instanceof Element || target instanceof ShadowRoot)) {
+				if (DEV) {
+					if (typeof t === 'string') throw new Error(`Target element "${t}" not found.`);
+					throw new TypeError(`Unknown portal target type: ${typeof t}. Allowed types: string (query selector), Element or ShadowRoot.`);
+				}
+				return;
+			}
+			target.appendChild(node);
+			return () => node.remove();
+		}}
+	>
+		{@render children?.()}
+	</div>
+{/if}

package/src/lib/internal/prop-resolvers.ts

@@ -0,0 +1,14 @@
+import { boxWith, type Getter, type ReadableBox } from './tools/index.js';
+import type { PortalTarget } from './portal';
+
+const createPropResolver =
+	<T>(fallback: T) =>
+	(getProp: Getter<T | undefined>): ReadableBox<T> =>
+		boxWith(() => {
+			const prop = getProp();
+			return prop !== undefined ? prop : fallback;
+		});
+
+export const resolveLocaleProp = createPropResolver<string>('en');
+
+export const resolvePortalToProp = createPropResolver<PortalTarget>('body');

package/src/lib/internal/roving-focus-group.ts

@@ -0,0 +1,147 @@
+import { type Box, type ReadableBox, simpleBox } from './tools/index.js';
+import { getDirectionalKeys, kbd } from './kbd.js';
+import type { Direction, Orientation } from './index.js';
+import { isHTMLElement } from './tools/utils/dom.js';
+import { BROWSER } from 'esm-env';
+
+type RovingFocusGroupOptions = (
+	| {
+			/**
+			 * The selector used to find the focusable candidates.
+			 */
+			candidateAttr: string;
+			candidateSelector?: undefined;
+			candidateNodes?: undefined;
+	  }
+	| {
+			/**
+			 * Custom candidate selector
+			 */
+			candidateSelector: string;
+			candidateAttr?: undefined;
+			candidateNodes?: undefined;
+	  }
+	| {
+			/**
+			 * Collects the candidates from the root node, for groups no selector can express.
+			 */
+			candidateNodes: (rootNode: HTMLElement) => HTMLElement[];
+			candidateAttr?: undefined;
+			candidateSelector?: undefined;
+	  }
+) & {
+	/**
+	 * The id of the root node
+	 */
+	rootNode: Box<HTMLElement | null>;
+
+	/**
+	 * Whether to loop through the candidates when reaching the end.
+	 */
+	loop: ReadableBox<boolean>;
+
+	/**
+	 * The orientation of the roving focus group. Used
+	 * to determine how keyboard navigation should work.
+	 */
+	orientation: ReadableBox<Orientation>;
+
+	/**
+	 * A callback function called when a candidate is focused.
+	 */
+	onCandidateFocus?: (node: HTMLElement) => void;
+};
+
+export class RovingFocusGroup {
+	readonly #opts: RovingFocusGroupOptions;
+	readonly #currentTabStopId = simpleBox<string | null>(null);
+
+	constructor(opts: RovingFocusGroupOptions) {
+		this.#opts = opts;
+	}
+
+	getCandidateNodes() {
+		const rootNode = this.#opts.rootNode.current;
+		if (!BROWSER || !rootNode) return [];
+		if (this.#opts.candidateNodes) return this.#opts.candidateNodes(rootNode);
+
+		const selector = this.#opts.candidateSelector ?? `[${this.#opts.candidateAttr}]:not([data-disabled])`;
+		return Array.from(rootNode.querySelectorAll<HTMLElement>(selector));
+	}
+
+	focusFirstCandidate() {
+		const items = this.getCandidateNodes();
+		if (!items.length) return;
+		items[0]?.focus();
+	}
+
+	handleKeydown(node: HTMLElement | null | undefined, e: KeyboardEvent, both: boolean = false) {
+		const rootNode = this.#opts.rootNode.current;
+		if (!rootNode || !node) return;
+
+		const items = this.getCandidateNodes();
+		if (!items.length) return;
+
+		const currentIndex = items.indexOf(node);
+		const dir = (rootNode.ownerDocument.defaultView ?? window).getComputedStyle(rootNode).direction as Direction;
+		const { nextKey, prevKey } = getDirectionalKeys(dir, this.#opts.orientation.current);
+		const loop = this.#opts.loop.current;
+
+		const keyToIndex = {
+			[nextKey]: currentIndex + 1,
+			[prevKey]: currentIndex - 1,
+			[kbd.HOME]: 0,
+			[kbd.END]: items.length - 1,
+		};
+
+		if (both) {
+			const altNextKey = nextKey === kbd.ARROW_DOWN ? kbd.ARROW_RIGHT : kbd.ARROW_DOWN;
+			const altPrevKey = prevKey === kbd.ARROW_UP ? kbd.ARROW_LEFT : kbd.ARROW_UP;
+			keyToIndex[altNextKey] = currentIndex + 1;
+			keyToIndex[altPrevKey] = currentIndex - 1;
+		}
+
+		let itemIndex = keyToIndex[e.key];
+		if (itemIndex === undefined) return;
+		e.preventDefault();
+
+		if (itemIndex < 0 && loop) {
+			itemIndex = items.length - 1;
+		} else if (itemIndex === items.length && loop) {
+			itemIndex = 0;
+		}
+
+		const itemToFocus = items[itemIndex];
+		if (!itemToFocus) return;
+		itemToFocus.focus();
+		this.#currentTabStopId.current = itemToFocus.id;
+		this.#opts.onCandidateFocus?.(itemToFocus);
+		return itemToFocus;
+	}
+
+	getTabIndex(node: HTMLElement | null | undefined) {
+		const items = this.getCandidateNodes();
+		const anyActive = this.#currentTabStopId.current !== null;
+
+		if (node && !anyActive && items[0] === node) {
+			this.#currentTabStopId.current = node.id;
+			return 0;
+		} else if (node?.id === this.#currentTabStopId.current) {
+			return 0;
+		}
+
+		return -1;
+	}
+
+	setCurrentTabStopId(id: string) {
+		this.#currentTabStopId.current = id;
+	}
+
+	focusCurrentTabStop() {
+		const currentTabStopId = this.#currentTabStopId.current;
+		if (!currentTabStopId) return;
+		const currentTabStop = this.#opts.rootNode.current?.querySelector(`#${currentTabStopId}`);
+		if (!currentTabStop || !isHTMLElement(currentTabStop)) return;
+		currentTabStop.focus();
+	}
+}