@zylem/ui 0.1.1 → 0.2.3

package/src/layers/LayerContext.tsx

@@ -0,0 +1,132 @@
+import {
+	createContext,
+	createMemo,
+	createSignal,
+	onMount,
+	useContext,
+	type Accessor,
+	type JSX,
+} from 'solid-js';
+import { ensureLayerContainer, LAYER_PORTAL_CLASS } from './resolve-mount';
+import { layerTierVars, type LayerTier } from './tiers';
+
+export type { LayerTier };
+
+interface LayerContextValue {
+	container: Accessor<HTMLElement | undefined>;
+}
+
+const LayerCtx = createContext<LayerContextValue>();
+
+export interface LayerProviderProps {
+	children: JSX.Element;
+}
+
+/**
+ * Root of the layer system: resolves the tree the app lives in — shadow root or
+ * document — and owns the container overlays portal into.
+ *
+ * Optional. `useLayer` resolves a container by itself when no provider is
+ * mounted, so a page with one `Tooltip` needs no setup. It earns its keep when an
+ * app spans several trees, such as two web components on one page, by pinning
+ * each subtree to the container in its own tree.
+ */
+export function LayerProvider(props: LayerProviderProps) {
+	const [container, setContainer] = createSignal<HTMLElement>();
+	let markerRef: HTMLSpanElement | undefined;
+
+	// Deferred to mount so `getRootNode()` can see an enclosing shadow root.
+	onMount(() => setContainer(ensureLayerContainer(markerRef)));
+
+	return (
+		<LayerCtx.Provider value={{ container }}>
+			<span ref={markerRef} style={{ display: 'none' }} aria-hidden="true" />
+			{props.children}
+		</LayerCtx.Provider>
+	);
+}
+
+export interface LayerScopeProps {
+  children: JSX.Element;
+  class?: string | undefined;
+  style?: JSX.CSSProperties | undefined;
+}
+
+/**
+ * A subtree that layers independently of the rest of the page.
+ *
+ * Two things make that work: the scope is a stacking context, so its
+ * descendants' `z-index` values are only compared with each other and none of
+ * them can paint above anything outside; and the scope owns the portal container
+ * its descendants mount into, so overlays opened inside it stay inside it.
+ *
+ * A dialog wraps its content in one, so a tooltip opened within the dialog floats
+ * over the dialog body without also floating over a menu belonging to the page.
+ */
+export function LayerScope(props: LayerScopeProps) {
+	const [container, setContainer] = createSignal<HTMLElement>();
+
+	return (
+		<div
+			class={props.class ? `zylem-layer-scope ${props.class}` : 'zylem-layer-scope'}
+			style={props.style}
+		>
+			<LayerCtx.Provider value={{ container }}>{props.children}</LayerCtx.Provider>
+			<div class={LAYER_PORTAL_CLASS} ref={setContainer} />
+		</div>
+	);
+}
+
+export interface ResolvedLayer {
+	/** Where to portal. `undefined` until mounted, so callers gate on it. */
+	mount: Accessor<HTMLElement | undefined>;
+	/** Value for the overlay's `z-index`. */
+	zIndex: Accessor<string>;
+	/**
+	 * Attach to any element inside the component. Lets the tree be resolved
+	 * without a `LayerProvider`, which is what keeps overlays styled inside a
+	 * shadow root. Ignored when a provider is present.
+	 */
+	anchorRef: (element: Element) => void;
+}
+
+/**
+ * Resolve a tier to a portal target and a `z-index`.
+ *
+ * @param rank Offset within the tier, for ordering peers — raising a clicked
+ * window above its siblings, say. Bands are 1000 apart, so ranks below that stay
+ * inside their tier. The offset means the same thing inside a `LayerScope` as
+ * out, so a panel can be lifted above a scope's tooltips while staying under its
+ * menus.
+ */
+export function useLayer(
+	tier: LayerTier,
+	rank: Accessor<number> | number = 0,
+): ResolvedLayer {
+	const context = useContext(LayerCtx);
+	const [fallback, setFallback] = createSignal<HTMLElement>();
+	let anchor: Element | undefined;
+
+	if (!context) {
+		// Runs after the ref below has been assigned and the element is in the
+		// document, which `getRootNode()` needs. With no anchor attached this
+		// still resolves, just to the document body.
+		onMount(() => setFallback(ensureLayerContainer(anchor)));
+	}
+
+	const zIndex = createMemo(() => {
+		const offset = typeof rank === 'function' ? rank() : rank;
+		const token = layerTierVars[tier];
+		// Left as a `calc` over the custom property rather than resolved here, so
+		// the cascade stays in charge of the tier's actual value.
+		return offset ? `calc(${token} + ${offset})` : token;
+	});
+
+	return {
+		mount: context ? context.container : fallback,
+		zIndex,
+		anchorRef: (element: Element) => {
+			anchor = element;
+		},
+	};
+}

package/src/layers/dismiss-guard.ts

@@ -0,0 +1,81 @@
+/**
+ * Keeps a dismissable overlay open when the interaction that "left" it never did.
+ *
+ * Kobalte decides an interaction is outside a layer by reading `event.target` in a
+ * capture-phase listener on `document`. Inside a shadow root that target has been
+ * retargeted to the host element, so the check asks whether the panel contains the
+ * whole web component — which it never does. Every pointerdown in the tree then
+ * reads as an outside click and the overlay closes on pointerdown, before the
+ * click can reach whatever was pressed. The same listener serves `focusin`, so
+ * focusing a field inside the panel closes it too.
+ *
+ * The original event survives on the dismissal event's `detail`, and its
+ * `composedPath()` still crosses the shadow boundary, so it can name the element
+ * actually pressed. Preventing the event cancels only the dismissal — a genuine
+ * outside interaction is left alone and still closes the overlay.
+ */
+
+/**
+ * The shape of Kobalte's interact-outside events.
+ *
+ * Declared structurally rather than imported: the type is not re-exported from
+ * `@kobalte/core`'s entry point, and reaching into the package's internals to
+ * borrow it would tie this to their file layout.
+ */
+export interface DismissalEvent {
+	detail: { originalEvent: Event };
+	preventDefault: () => void;
+}
+
+export interface DismissGuard {
+	/** Attach to the overlay's content element. */
+	ref: (element: HTMLElement) => void;
+	/** Pass to the content's `onInteractOutside`. */
+	onInteractOutside: (event: DismissalEvent) => void;
+}
+
+/** Whether a finished event's coordinates fall within `content`. */
+function hitByPoint(event: Event, content: HTMLElement): boolean {
+	if (!('clientX' in event) || !('clientY' in event)) return false;
+	const { clientX, clientY } = event as MouseEvent;
+
+	const rect = content.getBoundingClientRect();
+	return (
+		clientX >= rect.left
+		&& clientX <= rect.right
+		&& clientY >= rect.top
+		&& clientY <= rect.bottom
+	);
+}
+
+function isInside(original: Event, content: HTMLElement): boolean {
+	const path = original.composedPath();
+	if (path.length > 0) return path.includes(content);
+
+	// Touch takes a slower road: Kobalte defers the check to the following
+	// `click`, by which point the pointerdown has finished dispatching and its
+	// composed path has been emptied. Geometry is what is left to go on.
+	return hitByPoint(original, content);
+}
+
+/**
+ * Guard one overlay.
+ *
+ * Per-overlay rather than global because the answer depends on which content
+ * element is asking: a menu nested inside a dialog has to be able to dismiss
+ * without also dismissing the dialog around it.
+ */
+export function createDismissGuard(): DismissGuard {
+	let content: HTMLElement | undefined;
+
+	return {
+		ref: (element: HTMLElement) => {
+			content = element;
+		},
+		onInteractOutside: (event: DismissalEvent) => {
+			if (!content) return;
+			if (!isInside(event.detail.originalEvent, content)) return;
+			event.preventDefault();
+		},
+	};
+}

package/src/layers/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Layering and portal system.
+ *
+ * Overlays read their `z-index` from a named tier instead of picking a number,
+ * and portal into a container resolved from the tree they were opened in rather
+ * than assuming `document.body`. See {@link LayerScope} for nesting.
+ */
+
+export {
+	LayerProvider,
+	LayerScope,
+	useLayer,
+	type LayerProviderProps,
+	type LayerScopeProps,
+	type ResolvedLayer,
+} from './LayerContext';
+export {
+	createDismissGuard,
+	type DismissalEvent,
+	type DismissGuard,
+} from './dismiss-guard';
+export {
+	ensureLayerContainer,
+	resolveLayerRoot,
+	LAYER_PORTAL_CLASS,
+} from './resolve-mount';
+export { layerTierVars, type LayerTier } from './tiers';

package/src/layers/layer-tokens.css.ts

@@ -0,0 +1,38 @@
+import { globalStyle } from '@vanilla-extract/css';
+
+/**
+ * Structural styles for the layer system. The tier values themselves are design
+ * tokens (`vars.layers.*` in theme.css.ts); this file only styles the two DOM
+ * roles the system introduces.
+ */
+
+/**
+ * Container that portaled overlays mount into. Deliberately unpositioned and
+ * without a `z-index` of its own: creating a stacking context here would trap
+ * its children, and the whole point is for a menu at the `menu` tier to compare
+ * directly against a panel at the `panel` tier.
+ */
+globalStyle('.zylem-layer-portals', {
+	// Overlays are interactive, and hosts often set `pointer-events: none` on the
+	// element the container is appended under so input reaches what is behind
+	// (the editor does this so clicks reach the running game). Opting back in
+	// here saves every overlay from remembering to.
+	pointerEvents: 'auto',
+});
+
+/**
+ * A subtree that layers independently of the rest of the page.
+ *
+ * `isolation: isolate` is the whole mechanism: it gives the subtree a stacking
+ * context, so its descendants' `z-index` values are only ever compared with each
+ * other. Nothing inside can paint above anything outside, however large its tier,
+ * and the scope as a whole sits wherever its own tier puts it.
+ *
+ * The tier variables are deliberately *not* redefined here. Keeping the same
+ * bands inside and outside means a rank offset means the same thing everywhere,
+ * which is what lets a panel inside a modal be lifted above that modal's
+ * tooltips while still sitting below its menus.
+ */
+globalStyle('.zylem-layer-scope', {
+	isolation: 'isolate',
+});

package/src/layers/resolve-mount.ts

@@ -0,0 +1,48 @@
+/**
+ * Where a portaled overlay should mount.
+ *
+ * Kobalte's portals default to `document.body`, which breaks inside a shadow
+ * root: the styles a web component injects into its own shadow tree do not apply
+ * to `document.body`, so the overlay renders unstyled. Resolving from the
+ * triggering element instead keeps the overlay in whatever tree its styles live
+ * in.
+ */
+
+/** Class on the container that layered overlays mount into. */
+export const LAYER_PORTAL_CLASS = 'zylem-layer-portals';
+
+/**
+ * The shadow root or document body that owns `node`.
+ *
+ * Must be called after the node is in the document — `getRootNode()` only sees
+ * the shadow root once the subtree has been inserted.
+ */
+export function resolveLayerRoot(
+	node: Node | null | undefined,
+): ShadowRoot | HTMLElement {
+	const root = node?.getRootNode();
+	if (root instanceof ShadowRoot) return root;
+	if (root instanceof Document) return root.body;
+	return document.body;
+}
+
+/**
+ * The portal container for `node`'s tree, creating it on first use.
+ *
+ * Appended last so it starts above its siblings in paint order even before
+ * z-index is considered, and reused across every overlay in the same tree so a
+ * page with many menus does not accumulate containers.
+ */
+export function ensureLayerContainer(node: Node | null | undefined): HTMLElement {
+	const root = resolveLayerRoot(node);
+	for (const child of Array.from(root.children)) {
+		if (child instanceof HTMLElement && child.classList.contains(LAYER_PORTAL_CLASS)) {
+			return child;
+		}
+	}
+
+	const container = document.createElement('div');
+	container.className = LAYER_PORTAL_CLASS;
+	root.appendChild(container);
+	return container;
+}

package/src/layers/tiers.ts

@@ -0,0 +1,53 @@
+/**
+ * The layer tier ladder, as plain TypeScript.
+ *
+ * These live outside `theme.css.ts` because the runtime half of the layer
+ * system (`useLayer`) needs them, and `@zylem/ui/components` ships as source to
+ * consumers that do not compile vanilla-extract. A `.tsx` importing a `.css.ts`
+ * would drag `createGlobalTheme` into those apps, where it throws for want of a
+ * file scope. The theme imports these instead, so the ladder is still declared
+ * once.
+ */
+
+/**
+ * Stacking tiers, lowest first. Every overlay reads its `z-index` from one of
+ * these rather than picking a number, so the order is decided in one place.
+ */
+export type LayerTier = 'base' | 'panel' | 'modal' | 'popover' | 'tooltip' | 'menu';
+
+/**
+ * The `z-index` each tier resolves to. Fed to the theme as `tokens.layers`.
+ *
+ * Bands are 1000 apart to leave room for a per-instance rank offset, which is
+ * what dynamic ordering within a tier needs (raising the clicked window to the
+ * front of the other windows, say).
+ */
+export const layerTierValues = {
+	base: '0',
+	panel: '1000',
+	modal: '2000',
+	popover: '3000',
+	tooltip: '4000',
+	menu: '5000',
+} as const;
+
+/**
+ * Custom-property name per tier, sans the leading `--`. Fed to the theme as
+ * `varNames.layers`, and must stay in lock-step with {@link layerTierValues}.
+ */
+export const layerTierVarNames = {
+	base: 'zylem-layer-base',
+	panel: 'zylem-layer-panel',
+	modal: 'zylem-layer-modal',
+	popover: 'zylem-layer-popover',
+	tooltip: 'zylem-layer-tooltip',
+	menu: 'zylem-layer-menu',
+} as const;
+
+/**
+ * `var(--zylem-layer-*)` reference per tier — the same strings `vars.layers`
+ * carries, reachable without loading the theme's `.css.ts`.
+ */
+export const layerTierVars = Object.fromEntries(
+	Object.entries(layerTierVarNames).map(([tier, name]) => [tier, `var(--${name})`])
+) as Record<LayerTier, string>;

package/src/styles.ts

@@ -7,6 +7,7 @@
  */
 import './fonts.css';
 import './theme.css';
+import './layers/layer-tokens.css';
 import './global/logo.css';
 import './global/hyperglass-base.css';
 import './global/common.css';
@@ -44,5 +45,7 @@ import './components/Console/Console.css';
 import './components/Sidebar/Sidebar.css';
 import './components/Card/Card.css';
 import './components/SearchInput/SearchInput.css';
+import './components/MenuButton/MenuButton.css';
+import './components/ItemPicker/ItemPicker.css';
 import './components/EmptyState/EmptyState.css';
 import './components/Kbd/Kbd.css';

package/src/theme.css.ts

@@ -2,6 +2,7 @@ import {
 	createGlobalTheme,
 	createGlobalThemeContract,
 } from '@vanilla-extract/css';
+import { layerTierValues, layerTierVarNames } from './layers/tiers';
 
 /**
  * Concrete design-token values for the Zylem UI.
@@ -111,6 +112,11 @@ const tokens = {
 		normal: '160ms',
 		easeOut: 'cubic-bezier(.2,.8,.2,1)',
 	},
+	/**
+	 * Stacking tiers. Declared in `layers/tiers.ts` because the runtime side of
+	 * the layer system reads the same ladder without loading this file.
+	 */
+	layers: layerTierValues,
 } as const;
 
 /**
@@ -206,6 +212,7 @@ const varNames = {
 		normal: 'zylem-motion-normal',
 		easeOut: 'zylem-motion-ease-out',
 	},
+	layers: layerTierVarNames,
 } as const;
 
 /**

package/dist/chunk-VGOOWBSO.js

@@ -1 +0,0 @@
-var l={colors:{primary:"#61A6E8",primaryHover:"#3B8AD8",primaryActive:"#0C6EB8",accent:"#E64534",accentHover:"#C93A2C",accentActive:"#A82F24",background:"#11151C",backgroundTranslucent:"rgba(10, 20, 30, 0.46)",surface:"#1A1F27",surfaceHover:"#222831",border:"#2D3643",active:"rgba(20, 255, 60, 0.7)",activeHover:"rgba(20, 255, 60, 0.4)",successHover:"#2a6734b3",text:"#E6EBEF",textSecondary:"#88929E",consoleBackground:"rgba(20, 40, 60, 0.25)",consoleText:"#61A6E8"},spacing:{xxs:"0.125rem",xs:"0.25rem",sm:"0.5rem",md:"0.75rem",lg:"1rem",xl:"1.5rem",xxl:"2rem",xxxl:"3rem"},sizes:{icon:"28px",iconSm:"16px",iconLg:"96px"},typography:{fontFamily:"'Exo 2', sans-serif",fontSize:"14px"},borders:{radius:"12px",width:"1.5px"},material:{glassPanel:"linear-gradient(180deg, rgba(38, 76, 112, 0.74), rgba(10, 24, 38, 0.58))",glassPanelDark:"linear-gradient(180deg, rgba(26, 31, 39, 0.75), rgba(10, 20, 30, 0.68))",glossyBar:"linear-gradient(180deg, rgba(205, 232, 255, 0.55) 0%, rgba(97, 166, 232, 0.34) 38%, rgba(18, 54, 88, 0.86) 100%)",buttonGlass:"linear-gradient(180deg, rgba(178, 219, 255, 0.34), rgba(30, 94, 148, 0.72) 48%, rgba(9, 34, 58, 0.92))",buttonGlassHover:"linear-gradient(180deg, rgba(218, 242, 255, 0.58), rgba(48, 137, 220, 0.86) 48%, rgba(11, 62, 112, 0.96))",buttonGlassActive:"linear-gradient(180deg, rgba(190, 255, 203, 0.42), rgba(28, 174, 63, 0.78) 50%, rgba(9, 86, 31, 0.95))",buttonGlassDanger:"linear-gradient(180deg, rgba(255, 210, 202, 0.36), rgba(230, 69, 52, 0.82) 50%, rgba(96, 18, 13, 0.94))",fieldGlass:"linear-gradient(180deg, rgba(8, 19, 31, 0.82), rgba(15, 39, 62, 0.72))",panelHeaderGloss:"linear-gradient(180deg, rgba(190, 226, 255, 0.18), rgba(61, 118, 165, 0.16) 46%, rgba(10, 27, 44, 0.26))"},effects:{blurSm:"8px",blurMd:"14px",blurLg:"24px",shadowPanel:"0 22px 54px rgba(0, 0, 0, 0.48), inset 0 1px 0 rgba(255, 255, 255, 0.10)",shadowButton:"inset 0 1px 0 rgba(255,255,255,0.38), inset 0 -1px 0 rgba(0,0,0,0.45), 0 2px 7px rgba(0,0,0,0.35)",shadowInset:"inset 0 1px 2px rgba(0,0,0,0.42), inset 0 -1px 0 rgba(255,255,255,0.08)",glowPrimary:"0 0 18px rgba(97, 166, 232, 0.28)",glowActive:"0 0 20px rgba(20, 255, 60, 0.26)",glowDanger:"0 0 20px rgba(230, 69, 52, 0.24)",focusRing:"0 0 0 2px rgba(97, 166, 232, 0.38), 0 0 18px rgba(97, 166, 232, 0.22)"},radii:{window:"14px",panel:"12px",button:"7px",control:"6px",card:"10px"},motion:{fast:"120ms",normal:"160ms",easeOut:"cubic-bezier(.2,.8,.2,1)"}},o={colors:{primary:"var(--zylem-color-primary)",primaryHover:"var(--zylem-color-primary-hover)",primaryActive:"var(--zylem-color-primary-active)",accent:"var(--zylem-color-accent)",accentHover:"var(--zylem-color-accent-hover)",accentActive:"var(--zylem-color-accent-active)",background:"var(--zylem-color-background)",backgroundTranslucent:"var(--zylem-color-background-translucent)",surface:"var(--zylem-color-surface)",surfaceHover:"var(--zylem-color-surface-hover)",border:"var(--zylem-color-border)",active:"var(--zylem-color-active)",activeHover:"var(--zylem-color-active-hover)",successHover:"var(--zylem-color-success-hover)",text:"var(--zylem-color-text)",textSecondary:"var(--zylem-color-text-secondary)",consoleBackground:"var(--zylem-color-console-background)",consoleText:"var(--zylem-color-console-text)"},spacing:{xxs:"var(--zylem-spacing-xxs)",xs:"var(--zylem-spacing-xs)",sm:"var(--zylem-spacing-sm)",md:"var(--zylem-spacing-md)",lg:"var(--zylem-spacing-lg)",xl:"var(--zylem-spacing-xl)",xxl:"var(--zylem-spacing-xxl)",xxxl:"var(--zylem-spacing-xxxl)"},sizes:{icon:"var(--zylem-size-icon)",iconSm:"var(--zylem-size-icon-sm)",iconLg:"var(--zylem-size-icon-lg)"},typography:{fontFamily:"var(--zylem-font-family)",fontSize:"var(--zylem-font-size)"},borders:{radius:"var(--zylem-radius)",width:"var(--zylem-border)"},material:{glassPanel:"var(--zylem-material-glass-panel)",glassPanelDark:"var(--zylem-material-glass-panel-dark)",glossyBar:"var(--zylem-material-glossy-bar)",buttonGlass:"var(--zylem-material-button-glass)",buttonGlassHover:"var(--zylem-material-button-glass-hover)",buttonGlassActive:"var(--zylem-material-button-glass-active)",buttonGlassDanger:"var(--zylem-material-button-glass-danger)",fieldGlass:"var(--zylem-material-field-glass)",panelHeaderGloss:"var(--zylem-material-panel-header-gloss)"},effects:{blurSm:"var(--zylem-effect-blur-sm)",blurMd:"var(--zylem-effect-blur-md)",blurLg:"var(--zylem-effect-blur-lg)",shadowPanel:"var(--zylem-effect-shadow-panel)",shadowButton:"var(--zylem-effect-shadow-button)",shadowInset:"var(--zylem-effect-shadow-inset)",glowPrimary:"var(--zylem-effect-glow-primary)",glowActive:"var(--zylem-effect-glow-active)",glowDanger:"var(--zylem-effect-glow-danger)",focusRing:"var(--zylem-effect-focus-ring)"},radii:{window:"var(--zylem-radius-window)",panel:"var(--zylem-radius-panel)",button:"var(--zylem-radius-button)",control:"var(--zylem-radius-control)",card:"var(--zylem-radius-card)"},motion:{fast:"var(--zylem-motion-fast)",normal:"var(--zylem-motion-normal)",easeOut:"var(--zylem-motion-ease-out)"}};export{l as a,o as b};