@nepdatejs/dom 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shishir Rai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,27 @@
-# Temporary Holding Version
+# @nepdatejs/dom
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Small browser helpers shared by the `@nepdatejs` adapters. It knows nothing about dates and depends on no package. Every helper is a safe no-op during server rendering, and the ones that listen return a cleanup function.
+
+```ts
+import { onEscape, onOutsidePointer, trackPosition } from '@nepdatejs/dom';
+
+const stop = [
+  trackPosition(input, panel), // top layer when supported; flips and stays on screen
+  onOutsidePointer([field, panel], close),
+  onEscape(close), // capture phase, so an enclosing dialog stays open
+];
+// later: stop.forEach((cleanup) => cleanup());
+```
+
+| Helper                                                        | Does                                                                                                   |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `computePosition(anchorRect, panelHeight, viewport, options)` | Pure placement maths.                                                                                  |
+| `placePopover(anchor, panel, options)` / `trackPosition(…)`   | Show and position (and keep positioned); `layout: 'auto' \| 'popover' \| 'sheet'`, `sheetBelow` (480). |
+| `onOutsidePointer(elements, callback)`                        | Pointer down outside the elements.                                                                     |
+| `onEscape(callback, { capture, stop })`                       | Escape key.                                                                                            |
+| `onBackdropPointer(panel, callback)`                          | Tap on a bottom sheet's backdrop.                                                                      |
+| `resolveLayout(layout, viewportWidth, sheetBelow?)`           | `'popover'` or `'sheet'` for a width.                                                                  |
+| `focusFirst(container, selector?)`, `restoreFocus(element)`   | Focus helpers.                                                                                         |
+| `supportsPopover()`, `prefersReducedMotion()`, `hasDom()`     | Feature checks.                                                                                        |
+
+MIT © Shishir Rai

package/dist/index.cjs

@@ -0,0 +1,191 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/env.ts
+/** True in a browser-like environment; false during server rendering. */
+function hasDom() {
+	return typeof window !== "undefined" && typeof document !== "undefined";
+}
+/** Whether the browser can show elements in the top layer (`popover` + `showPopover`). */
+function supportsPopover() {
+	return hasDom() && typeof HTMLElement !== "undefined" && typeof HTMLElement.prototype.showPopover === "function";
+}
+/** Whether the user asked the system for less motion. */
+function prefersReducedMotion() {
+	return hasDom() && typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+//#endregion
+//#region src/position.ts
+/** The layout to use for a viewport width. Pure. */
+function resolveLayout(layout, viewportWidth, sheetBelow = 480) {
+	if (layout !== void 0 && layout !== "auto") return layout;
+	return viewportWidth < sheetBelow ? "sheet" : "popover";
+}
+/**
+* Where to put a panel next to an anchor, in viewport (position: fixed)
+* coordinates. Pure, so it can be tested without a browser. Rules from the
+* institute-SaaS picker: prefer the requested side, flip when the panel does
+* not fit but does fit on the other side, and keep `gap` px from every edge
+* (the panel may overlap the anchor rather than leave the screen).
+*/
+function computePosition(anchor, panelHeight, viewport, options = {}) {
+	const gap = options.gap ?? 6;
+	const placement = options.placement ?? "bottom-start";
+	const width = Math.max(0, Math.min(options.width ?? 320, viewport.width - gap * 2));
+	const roomBelow = viewport.height - anchor.bottom - gap * 2;
+	const roomAbove = anchor.top - gap * 2;
+	const side = placement.startsWith("top") ? roomAbove >= panelHeight || roomAbove >= roomBelow ? "top" : "bottom" : roomBelow >= panelHeight || roomBelow >= roomAbove ? "bottom" : "top";
+	const rawTop = side === "bottom" ? anchor.bottom + gap : anchor.top - gap - panelHeight;
+	const rawLeft = placement.endsWith("end") ? anchor.right - width : anchor.left;
+	return {
+		top: Math.max(gap, Math.min(rawTop, viewport.height - gap - panelHeight)),
+		left: Math.max(gap, Math.min(rawLeft, viewport.width - width - gap)),
+		width,
+		side
+	};
+}
+/**
+* Show `panel` beside `anchor` once. Uses the browser's top layer when it can
+* (so dialogs and scrolling containers never clip the panel), otherwise
+* position: fixed. Returns a function that hides the panel again.
+*/
+function placePopover(anchor, panel, options = {}) {
+	if (!hasDom()) return noop$1;
+	const topLayer = supportsPopover();
+	if (topLayer) {
+		if (!panel.hasAttribute("popover")) panel.setAttribute("popover", "manual");
+		if (!panel.matches(":popover-open")) panel.showPopover();
+	}
+	const layout = resolveLayout(options.layout, window.innerWidth, options.sheetBelow);
+	panel.dataset["layout"] = layout;
+	if (layout === "sheet") {
+		Object.assign(panel.style, {
+			top: "",
+			left: "",
+			width: "",
+			position: "fixed",
+			margin: "0",
+			inset: "auto 0 0 0"
+		});
+		delete panel.dataset["side"];
+		return hider(panel, topLayer);
+	}
+	const position = computePosition(anchor.getBoundingClientRect(), panel.offsetHeight, {
+		width: window.innerWidth,
+		height: window.innerHeight
+	}, options);
+	Object.assign(panel.style, {
+		position: "fixed",
+		margin: "0",
+		inset: "auto",
+		top: `${position.top}px`,
+		left: `${position.left}px`,
+		width: `${position.width}px`
+	});
+	panel.dataset["side"] = position.side;
+	return hider(panel, topLayer);
+}
+function hider(panel, topLayer) {
+	return () => {
+		if (topLayer && panel.matches(":popover-open")) panel.hidePopover();
+	};
+}
+/**
+* Show the panel and keep it beside the anchor while the window resizes or
+* any ancestor scrolls. Returns a function that stops tracking and hides it.
+*/
+function trackPosition(anchor, panel, options = {}) {
+	if (!hasDom()) return noop$1;
+	let hide = placePopover(anchor, panel, options);
+	const place = () => {
+		hide = placePopover(anchor, panel, options);
+	};
+	window.addEventListener("resize", place);
+	window.addEventListener("scroll", place, true);
+	return () => {
+		window.removeEventListener("resize", place);
+		window.removeEventListener("scroll", place, true);
+		hide();
+	};
+}
+function noop$1() {}
+//#endregion
+//#region src/events.ts
+/**
+* Call `callback` when a pointer goes down outside all of `elements` (checked
+* in the capture phase, before the page reacts). Returns a cleanup function.
+*/
+function onOutsidePointer(elements, callback) {
+	if (!hasDom()) return noop;
+	const listener = (event) => {
+		const target = event.target;
+		const list = typeof elements === "function" ? elements() : elements;
+		if (!(target instanceof Node && list.some((element) => element?.contains(target) ?? false))) callback(event);
+	};
+	document.addEventListener("pointerdown", listener, true);
+	return () => {
+		document.removeEventListener("pointerdown", listener, true);
+	};
+}
+/**
+* Call `callback` when the pointer goes down on a panel's backdrop (the dimmed
+* area around a bottom sheet). A top-layer panel receives those events itself,
+* so they are told apart by position: on the panel, but outside its box.
+*/
+function onBackdropPointer(panel, callback) {
+	if (!hasDom()) return noop;
+	const listener = (event) => {
+		if (event.target !== panel) return;
+		const box = panel.getBoundingClientRect();
+		if (event.clientX < box.left || event.clientX > box.right || event.clientY < box.top || event.clientY > box.bottom) callback(event);
+	};
+	panel.addEventListener("pointerdown", listener);
+	return () => {
+		panel.removeEventListener("pointerdown", listener);
+	};
+}
+/**
+* Call `callback` on Escape. By default it listens in the capture phase and
+* stops the event, so an enclosing dialog does not close as well.
+*/
+function onEscape(callback, options = {}) {
+	if (!hasDom()) return noop;
+	const capture = options.capture ?? true;
+	const listener = (event) => {
+		if (event.key !== "Escape") return;
+		if (options.stop ?? true) {
+			event.stopPropagation();
+			event.preventDefault();
+		}
+		callback(event);
+	};
+	window.addEventListener("keydown", listener, capture);
+	return () => {
+		window.removeEventListener("keydown", listener, capture);
+	};
+}
+/** Focus the first element in `container` matching `selector` (the roving-tabindex day by default). */
+function focusFirst(container, selector = "[tabindex=\"0\"]") {
+	const element = container?.querySelector(selector);
+	if (!element) return false;
+	element.focus();
+	return true;
+}
+/** Put focus back, e.g. on the input after the panel closes. */
+function restoreFocus(element) {
+	element?.focus({ preventScroll: true });
+}
+function noop() {}
+//#endregion
+exports.computePosition = computePosition;
+exports.focusFirst = focusFirst;
+exports.hasDom = hasDom;
+exports.onBackdropPointer = onBackdropPointer;
+exports.onEscape = onEscape;
+exports.onOutsidePointer = onOutsidePointer;
+exports.placePopover = placePopover;
+exports.prefersReducedMotion = prefersReducedMotion;
+exports.resolveLayout = resolveLayout;
+exports.restoreFocus = restoreFocus;
+exports.supportsPopover = supportsPopover;
+exports.trackPosition = trackPosition;
+
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["noop"],"sources":["../src/env.ts","../src/position.ts","../src/events.ts"],"sourcesContent":["/** True in a browser-like environment; false during server rendering. */\nexport function hasDom(): boolean {\n  return typeof window !== 'undefined' && typeof document !== 'undefined';\n}\n\n/** Whether the browser can show elements in the top layer (`popover` + `showPopover`). */\nexport function supportsPopover(): boolean {\n  return (\n    hasDom() &&\n    typeof HTMLElement !== 'undefined' &&\n    typeof HTMLElement.prototype.showPopover === 'function'\n  );\n}\n\n/** Whether the user asked the system for less motion. */\nexport function prefersReducedMotion(): boolean {\n  return (\n    hasDom() &&\n    typeof window.matchMedia === 'function' &&\n    window.matchMedia('(prefers-reduced-motion: reduce)').matches\n  );\n}\n","import { hasDom, supportsPopover } from './env';\n\nexport type Placement = 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end';\n\n/** 'popover' sits beside the anchor; 'sheet' is a bottom sheet; 'auto' picks the sheet on narrow screens. */\nexport type PanelLayout = 'auto' | 'popover' | 'sheet';\n\nexport interface PlaceOptions {\n  /** Space between the anchor and the panel, and kept from the viewport edges. Default 6. */\n  readonly gap?: number | undefined;\n  /** Panel width in px; shrinks to fit narrow screens. Default 320. */\n  readonly width?: number | undefined;\n  /** Preferred side; flips when there is not enough room. Default 'bottom-start'. */\n  readonly placement?: Placement | undefined;\n  /** Default 'auto'. */\n  readonly layout?: PanelLayout | undefined;\n  /** 'auto' uses the sheet below this viewport width, in px. Default 480. */\n  readonly sheetBelow?: number | undefined;\n}\n\n/** The layout to use for a viewport width. Pure. */\nexport function resolveLayout(\n  layout: PanelLayout | undefined,\n  viewportWidth: number,\n  sheetBelow = 480,\n): 'popover' | 'sheet' {\n  if (layout !== undefined && layout !== 'auto') {\n    return layout;\n  }\n\n  return viewportWidth < sheetBelow ? 'sheet' : 'popover';\n}\n\nexport interface Rect {\n  readonly top: number;\n  readonly left: number;\n  readonly bottom: number;\n  readonly right: number;\n}\n\nexport interface Position {\n  readonly top: number;\n  readonly left: number;\n  readonly width: number;\n  /** Where the panel ended up after flipping. */\n  readonly side: 'top' | 'bottom';\n}\n\n/**\n * Where to put a panel next to an anchor, in viewport (position: fixed)\n * coordinates. Pure, so it can be tested without a browser. Rules from the\n * institute-SaaS picker: prefer the requested side, flip when the panel does\n * not fit but does fit on the other side, and keep `gap` px from every edge\n * (the panel may overlap the anchor rather than leave the screen).\n */\nexport function computePosition(\n  anchor: Rect,\n  panelHeight: number,\n  viewport: { readonly width: number; readonly height: number },\n  options: PlaceOptions = {},\n): Position {\n  const gap = options.gap ?? 6;\n  const placement = options.placement ?? 'bottom-start';\n  const width = Math.max(0, Math.min(options.width ?? 320, viewport.width - gap * 2));\n  const roomBelow = viewport.height - anchor.bottom - gap * 2;\n  const roomAbove = anchor.top - gap * 2;\n  const wantsTop = placement.startsWith('top');\n  const side: 'top' | 'bottom' = wantsTop\n    ? roomAbove >= panelHeight || roomAbove >= roomBelow\n      ? 'top'\n      : 'bottom'\n    : roomBelow >= panelHeight || roomBelow >= roomAbove\n      ? 'bottom'\n      : 'top';\n  const rawTop = side === 'bottom' ? anchor.bottom + gap : anchor.top - gap - panelHeight;\n  const rawLeft = placement.endsWith('end') ? anchor.right - width : anchor.left;\n\n  return {\n    // Keep the whole panel on screen; when it is taller than the room, its top edge wins.\n    top: Math.max(gap, Math.min(rawTop, viewport.height - gap - panelHeight)),\n    left: Math.max(gap, Math.min(rawLeft, viewport.width - width - gap)),\n    width,\n    side,\n  };\n}\n\n/**\n * Show `panel` beside `anchor` once. Uses the browser's top layer when it can\n * (so dialogs and scrolling containers never clip the panel), otherwise\n * position: fixed. Returns a function that hides the panel again.\n */\nexport function placePopover(\n  anchor: Element,\n  panel: HTMLElement,\n  options: PlaceOptions = {},\n): () => void {\n  if (!hasDom()) {\n    return noop;\n  }\n  const topLayer = supportsPopover();\n  if (topLayer) {\n    if (!panel.hasAttribute('popover')) {\n      panel.setAttribute('popover', 'manual');\n    }\n    if (!panel.matches(':popover-open')) {\n      panel.showPopover();\n    }\n  }\n  const layout = resolveLayout(options.layout, window.innerWidth, options.sheetBelow);\n  panel.dataset['layout'] = layout;\n  if (layout === 'sheet') {\n    // The stylesheet pins a sheet to the bottom edge; clear any popover coordinates.\n    Object.assign(panel.style, {\n      top: '',\n      left: '',\n      width: '',\n      position: 'fixed',\n      margin: '0',\n      inset: 'auto 0 0 0',\n    });\n    delete panel.dataset['side'];\n\n    return hider(panel, topLayer);\n  }\n  const position = computePosition(\n    anchor.getBoundingClientRect(),\n    panel.offsetHeight,\n    { width: window.innerWidth, height: window.innerHeight },\n    options,\n  );\n  Object.assign(panel.style, {\n    position: 'fixed',\n    margin: '0',\n    inset: 'auto',\n    top: `${position.top}px`,\n    left: `${position.left}px`,\n    width: `${position.width}px`,\n  });\n  panel.dataset['side'] = position.side;\n\n  return hider(panel, topLayer);\n}\n\nfunction hider(panel: HTMLElement, topLayer: boolean): () => void {\n  return () => {\n    if (topLayer && panel.matches(':popover-open')) {\n      panel.hidePopover();\n    }\n  };\n}\n\n/**\n * Show the panel and keep it beside the anchor while the window resizes or\n * any ancestor scrolls. Returns a function that stops tracking and hides it.\n */\nexport function trackPosition(\n  anchor: Element,\n  panel: HTMLElement,\n  options: PlaceOptions = {},\n): () => void {\n  if (!hasDom()) {\n    return noop;\n  }\n  let hide = placePopover(anchor, panel, options);\n  const place = (): void => {\n    hide = placePopover(anchor, panel, options);\n  };\n  window.addEventListener('resize', place);\n  window.addEventListener('scroll', place, true);\n\n  return () => {\n    window.removeEventListener('resize', place);\n    window.removeEventListener('scroll', place, true);\n    hide();\n  };\n}\n\nfunction noop(): void {\n  // Nothing to undo outside a browser.\n}\n","import { hasDom } from './env';\n\ntype Targets =\n  | readonly (Element | null | undefined)[]\n  | (() => readonly (Element | null | undefined)[]);\n\n/**\n * Call `callback` when a pointer goes down outside all of `elements` (checked\n * in the capture phase, before the page reacts). Returns a cleanup function.\n */\nexport function onOutsidePointer(\n  elements: Targets,\n  callback: (event: PointerEvent) => void,\n): () => void {\n  if (!hasDom()) {\n    return noop;\n  }\n  const listener = (event: PointerEvent): void => {\n    const target = event.target;\n    const list = typeof elements === 'function' ? elements() : elements;\n    const inside =\n      target instanceof Node &&\n      list.some((element) => element?.contains(target) ?? false);\n    if (!inside) {\n      callback(event);\n    }\n  };\n  document.addEventListener('pointerdown', listener, true);\n\n  return () => {\n    document.removeEventListener('pointerdown', listener, true);\n  };\n}\n\n/**\n * Call `callback` when the pointer goes down on a panel's backdrop (the dimmed\n * area around a bottom sheet). A top-layer panel receives those events itself,\n * so they are told apart by position: on the panel, but outside its box.\n */\nexport function onBackdropPointer(\n  panel: HTMLElement,\n  callback: (event: PointerEvent) => void,\n): () => void {\n  if (!hasDom()) {\n    return noop;\n  }\n  const listener = (event: PointerEvent): void => {\n    if (event.target !== panel) {\n      return;\n    }\n    const box = panel.getBoundingClientRect();\n    const outside =\n      event.clientX < box.left ||\n      event.clientX > box.right ||\n      event.clientY < box.top ||\n      event.clientY > box.bottom;\n    if (outside) {\n      callback(event);\n    }\n  };\n  panel.addEventListener('pointerdown', listener);\n\n  return () => {\n    panel.removeEventListener('pointerdown', listener);\n  };\n}\n\n/**\n * Call `callback` on Escape. By default it listens in the capture phase and\n * stops the event, so an enclosing dialog does not close as well.\n */\nexport function onEscape(\n  callback: (event: KeyboardEvent) => void,\n  options: { readonly capture?: boolean; readonly stop?: boolean } = {},\n): () => void {\n  if (!hasDom()) {\n    return noop;\n  }\n  const capture = options.capture ?? true;\n  const listener = (event: KeyboardEvent): void => {\n    if (event.key !== 'Escape') {\n      return;\n    }\n    if (options.stop ?? true) {\n      event.stopPropagation();\n      event.preventDefault();\n    }\n    callback(event);\n  };\n  window.addEventListener('keydown', listener, capture);\n\n  return () => {\n    window.removeEventListener('keydown', listener, capture);\n  };\n}\n\n/** Focus the first element in `container` matching `selector` (the roving-tabindex day by default). */\nexport function focusFirst(\n  container: ParentNode | null,\n  selector = '[tabindex=\"0\"]',\n): boolean {\n  const element = container?.querySelector<HTMLElement>(selector);\n  if (!element) {\n    return false;\n  }\n  element.focus();\n\n  return true;\n}\n\n/** Put focus back, e.g. on the input after the panel closes. */\nexport function restoreFocus(element: HTMLElement | null | undefined): void {\n  element?.focus({ preventScroll: true });\n}\n\nfunction noop(): void {\n  // Nothing to undo outside a browser.\n}\n"],"mappings":"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"}

package/dist/index.d.cts

@@ -0,0 +1,90 @@
+//#region src/env.d.ts
+/** True in a browser-like environment; false during server rendering. */
+export declare function hasDom(): boolean;
+/** Whether the browser can show elements in the top layer (`popover` + `showPopover`). */
+export declare function supportsPopover(): boolean;
+/** Whether the user asked the system for less motion. */
+export declare function prefersReducedMotion(): boolean;
+//#endregion
+//#region src/position.d.ts
+type Placement = "bottom-start" | "bottom-end" | "top-start" | "top-end";
+/** 'popover' sits beside the anchor; 'sheet' is a bottom sheet; 'auto' picks the sheet on narrow screens. */
+type PanelLayout = "auto" | "popover" | "sheet";
+interface PlaceOptions {
+  /** Space between the anchor and the panel, and kept from the viewport edges. Default 6. */
+  readonly gap?: number | undefined;
+  /** Panel width in px; shrinks to fit narrow screens. Default 320. */
+  readonly width?: number | undefined;
+  /** Preferred side; flips when there is not enough room. Default 'bottom-start'. */
+  readonly placement?: Placement | undefined;
+  /** Default 'auto'. */
+  readonly layout?: PanelLayout | undefined;
+  /** 'auto' uses the sheet below this viewport width, in px. Default 480. */
+  readonly sheetBelow?: number | undefined;
+}
+/** The layout to use for a viewport width. Pure. */
+export declare function resolveLayout(layout: PanelLayout | undefined, viewportWidth: number, sheetBelow?: number): "popover" | "sheet";
+interface Rect {
+  readonly top: number;
+  readonly left: number;
+  readonly bottom: number;
+  readonly right: number;
+}
+interface Position {
+  readonly top: number;
+  readonly left: number;
+  readonly width: number;
+  /** Where the panel ended up after flipping. */
+  readonly side: "top" | "bottom";
+}
+/**
+ * Where to put a panel next to an anchor, in viewport (position: fixed)
+ * coordinates. Pure, so it can be tested without a browser. Rules from the
+ * institute-SaaS picker: prefer the requested side, flip when the panel does
+ * not fit but does fit on the other side, and keep `gap` px from every edge
+ * (the panel may overlap the anchor rather than leave the screen).
+ */
+export declare function computePosition(anchor: Rect, panelHeight: number, viewport: {
+  readonly width: number;
+  readonly height: number;
+}, options?: PlaceOptions): Position;
+/**
+ * Show `panel` beside `anchor` once. Uses the browser's top layer when it can
+ * (so dialogs and scrolling containers never clip the panel), otherwise
+ * position: fixed. Returns a function that hides the panel again.
+ */
+export declare function placePopover(anchor: Element, panel: HTMLElement, options?: PlaceOptions): () => void;
+/**
+ * Show the panel and keep it beside the anchor while the window resizes or
+ * any ancestor scrolls. Returns a function that stops tracking and hides it.
+ */
+export declare function trackPosition(anchor: Element, panel: HTMLElement, options?: PlaceOptions): () => void;
+//#endregion
+//#region src/events.d.ts
+type Targets = readonly (Element | null | undefined)[] | (() => readonly (Element | null | undefined)[]);
+/**
+ * Call `callback` when a pointer goes down outside all of `elements` (checked
+ * in the capture phase, before the page reacts). Returns a cleanup function.
+ */
+export declare function onOutsidePointer(elements: Targets, callback: (event: PointerEvent) => void): () => void;
+/**
+ * Call `callback` when the pointer goes down on a panel's backdrop (the dimmed
+ * area around a bottom sheet). A top-layer panel receives those events itself,
+ * so they are told apart by position: on the panel, but outside its box.
+ */
+export declare function onBackdropPointer(panel: HTMLElement, callback: (event: PointerEvent) => void): () => void;
+/**
+ * Call `callback` on Escape. By default it listens in the capture phase and
+ * stops the event, so an enclosing dialog does not close as well.
+ */
+export declare function onEscape(callback: (event: KeyboardEvent) => void, options?: {
+  readonly capture?: boolean;
+  readonly stop?: boolean;
+}): () => void;
+/** Focus the first element in `container` matching `selector` (the roving-tabindex day by default). */
+export declare function focusFirst(container: ParentNode | null, selector?: string): boolean;
+/** Put focus back, e.g. on the input after the panel closes. */
+export declare function restoreFocus(element: HTMLElement | null | undefined): void;
+//#endregion
+export type { PanelLayout, PlaceOptions, Placement, Position, Rect };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -0,0 +1,90 @@
+//#region src/env.d.ts
+/** True in a browser-like environment; false during server rendering. */
+export declare function hasDom(): boolean;
+/** Whether the browser can show elements in the top layer (`popover` + `showPopover`). */
+export declare function supportsPopover(): boolean;
+/** Whether the user asked the system for less motion. */
+export declare function prefersReducedMotion(): boolean;
+//#endregion
+//#region src/position.d.ts
+type Placement = "bottom-start" | "bottom-end" | "top-start" | "top-end";
+/** 'popover' sits beside the anchor; 'sheet' is a bottom sheet; 'auto' picks the sheet on narrow screens. */
+type PanelLayout = "auto" | "popover" | "sheet";
+interface PlaceOptions {
+  /** Space between the anchor and the panel, and kept from the viewport edges. Default 6. */
+  readonly gap?: number | undefined;
+  /** Panel width in px; shrinks to fit narrow screens. Default 320. */
+  readonly width?: number | undefined;
+  /** Preferred side; flips when there is not enough room. Default 'bottom-start'. */
+  readonly placement?: Placement | undefined;
+  /** Default 'auto'. */
+  readonly layout?: PanelLayout | undefined;
+  /** 'auto' uses the sheet below this viewport width, in px. Default 480. */
+  readonly sheetBelow?: number | undefined;
+}
+/** The layout to use for a viewport width. Pure. */
+export declare function resolveLayout(layout: PanelLayout | undefined, viewportWidth: number, sheetBelow?: number): "popover" | "sheet";
+interface Rect {
+  readonly top: number;
+  readonly left: number;
+  readonly bottom: number;
+  readonly right: number;
+}
+interface Position {
+  readonly top: number;
+  readonly left: number;
+  readonly width: number;
+  /** Where the panel ended up after flipping. */
+  readonly side: "top" | "bottom";
+}
+/**
+ * Where to put a panel next to an anchor, in viewport (position: fixed)
+ * coordinates. Pure, so it can be tested without a browser. Rules from the
+ * institute-SaaS picker: prefer the requested side, flip when the panel does
+ * not fit but does fit on the other side, and keep `gap` px from every edge
+ * (the panel may overlap the anchor rather than leave the screen).
+ */
+export declare function computePosition(anchor: Rect, panelHeight: number, viewport: {
+  readonly width: number;
+  readonly height: number;
+}, options?: PlaceOptions): Position;
+/**
+ * Show `panel` beside `anchor` once. Uses the browser's top layer when it can
+ * (so dialogs and scrolling containers never clip the panel), otherwise
+ * position: fixed. Returns a function that hides the panel again.
+ */
+export declare function placePopover(anchor: Element, panel: HTMLElement, options?: PlaceOptions): () => void;
+/**
+ * Show the panel and keep it beside the anchor while the window resizes or
+ * any ancestor scrolls. Returns a function that stops tracking and hides it.
+ */
+export declare function trackPosition(anchor: Element, panel: HTMLElement, options?: PlaceOptions): () => void;
+//#endregion
+//#region src/events.d.ts
+type Targets = readonly (Element | null | undefined)[] | (() => readonly (Element | null | undefined)[]);
+/**
+ * Call `callback` when a pointer goes down outside all of `elements` (checked
+ * in the capture phase, before the page reacts). Returns a cleanup function.
+ */
+export declare function onOutsidePointer(elements: Targets, callback: (event: PointerEvent) => void): () => void;
+/**
+ * Call `callback` when the pointer goes down on a panel's backdrop (the dimmed
+ * area around a bottom sheet). A top-layer panel receives those events itself,
+ * so they are told apart by position: on the panel, but outside its box.
+ */
+export declare function onBackdropPointer(panel: HTMLElement, callback: (event: PointerEvent) => void): () => void;
+/**
+ * Call `callback` on Escape. By default it listens in the capture phase and
+ * stops the event, so an enclosing dialog does not close as well.
+ */
+export declare function onEscape(callback: (event: KeyboardEvent) => void, options?: {
+  readonly capture?: boolean;
+  readonly stop?: boolean;
+}): () => void;
+/** Focus the first element in `container` matching `selector` (the roving-tabindex day by default). */
+export declare function focusFirst(container: ParentNode | null, selector?: string): boolean;
+/** Put focus back, e.g. on the input after the panel closes. */
+export declare function restoreFocus(element: HTMLElement | null | undefined): void;
+//#endregion
+export type { PanelLayout, PlaceOptions, Placement, Position, Rect };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,179 @@
+//#region src/env.ts
+/** True in a browser-like environment; false during server rendering. */
+function hasDom() {
+	return typeof window !== "undefined" && typeof document !== "undefined";
+}
+/** Whether the browser can show elements in the top layer (`popover` + `showPopover`). */
+function supportsPopover() {
+	return hasDom() && typeof HTMLElement !== "undefined" && typeof HTMLElement.prototype.showPopover === "function";
+}
+/** Whether the user asked the system for less motion. */
+function prefersReducedMotion() {
+	return hasDom() && typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+//#endregion
+//#region src/position.ts
+/** The layout to use for a viewport width. Pure. */
+function resolveLayout(layout, viewportWidth, sheetBelow = 480) {
+	if (layout !== void 0 && layout !== "auto") return layout;
+	return viewportWidth < sheetBelow ? "sheet" : "popover";
+}
+/**
+* Where to put a panel next to an anchor, in viewport (position: fixed)
+* coordinates. Pure, so it can be tested without a browser. Rules from the
+* institute-SaaS picker: prefer the requested side, flip when the panel does
+* not fit but does fit on the other side, and keep `gap` px from every edge
+* (the panel may overlap the anchor rather than leave the screen).
+*/
+function computePosition(anchor, panelHeight, viewport, options = {}) {
+	const gap = options.gap ?? 6;
+	const placement = options.placement ?? "bottom-start";
+	const width = Math.max(0, Math.min(options.width ?? 320, viewport.width - gap * 2));
+	const roomBelow = viewport.height - anchor.bottom - gap * 2;
+	const roomAbove = anchor.top - gap * 2;
+	const side = placement.startsWith("top") ? roomAbove >= panelHeight || roomAbove >= roomBelow ? "top" : "bottom" : roomBelow >= panelHeight || roomBelow >= roomAbove ? "bottom" : "top";
+	const rawTop = side === "bottom" ? anchor.bottom + gap : anchor.top - gap - panelHeight;
+	const rawLeft = placement.endsWith("end") ? anchor.right - width : anchor.left;
+	return {
+		top: Math.max(gap, Math.min(rawTop, viewport.height - gap - panelHeight)),
+		left: Math.max(gap, Math.min(rawLeft, viewport.width - width - gap)),
+		width,
+		side
+	};
+}
+/**
+* Show `panel` beside `anchor` once. Uses the browser's top layer when it can
+* (so dialogs and scrolling containers never clip the panel), otherwise
+* position: fixed. Returns a function that hides the panel again.
+*/
+function placePopover(anchor, panel, options = {}) {
+	if (!hasDom()) return noop$1;
+	const topLayer = supportsPopover();
+	if (topLayer) {
+		if (!panel.hasAttribute("popover")) panel.setAttribute("popover", "manual");
+		if (!panel.matches(":popover-open")) panel.showPopover();
+	}
+	const layout = resolveLayout(options.layout, window.innerWidth, options.sheetBelow);
+	panel.dataset["layout"] = layout;
+	if (layout === "sheet") {
+		Object.assign(panel.style, {
+			top: "",
+			left: "",
+			width: "",
+			position: "fixed",
+			margin: "0",
+			inset: "auto 0 0 0"
+		});
+		delete panel.dataset["side"];
+		return hider(panel, topLayer);
+	}
+	const position = computePosition(anchor.getBoundingClientRect(), panel.offsetHeight, {
+		width: window.innerWidth,
+		height: window.innerHeight
+	}, options);
+	Object.assign(panel.style, {
+		position: "fixed",
+		margin: "0",
+		inset: "auto",
+		top: `${position.top}px`,
+		left: `${position.left}px`,
+		width: `${position.width}px`
+	});
+	panel.dataset["side"] = position.side;
+	return hider(panel, topLayer);
+}
+function hider(panel, topLayer) {
+	return () => {
+		if (topLayer && panel.matches(":popover-open")) panel.hidePopover();
+	};
+}
+/**
+* Show the panel and keep it beside the anchor while the window resizes or
+* any ancestor scrolls. Returns a function that stops tracking and hides it.
+*/
+function trackPosition(anchor, panel, options = {}) {
+	if (!hasDom()) return noop$1;
+	let hide = placePopover(anchor, panel, options);
+	const place = () => {
+		hide = placePopover(anchor, panel, options);
+	};
+	window.addEventListener("resize", place);
+	window.addEventListener("scroll", place, true);
+	return () => {
+		window.removeEventListener("resize", place);
+		window.removeEventListener("scroll", place, true);
+		hide();
+	};
+}
+function noop$1() {}
+//#endregion
+//#region src/events.ts
+/**
+* Call `callback` when a pointer goes down outside all of `elements` (checked
+* in the capture phase, before the page reacts). Returns a cleanup function.
+*/
+function onOutsidePointer(elements, callback) {
+	if (!hasDom()) return noop;
+	const listener = (event) => {
+		const target = event.target;
+		const list = typeof elements === "function" ? elements() : elements;
+		if (!(target instanceof Node && list.some((element) => element?.contains(target) ?? false))) callback(event);
+	};
+	document.addEventListener("pointerdown", listener, true);
+	return () => {
+		document.removeEventListener("pointerdown", listener, true);
+	};
+}
+/**
+* Call `callback` when the pointer goes down on a panel's backdrop (the dimmed
+* area around a bottom sheet). A top-layer panel receives those events itself,
+* so they are told apart by position: on the panel, but outside its box.
+*/
+function onBackdropPointer(panel, callback) {
+	if (!hasDom()) return noop;
+	const listener = (event) => {
+		if (event.target !== panel) return;
+		const box = panel.getBoundingClientRect();
+		if (event.clientX < box.left || event.clientX > box.right || event.clientY < box.top || event.clientY > box.bottom) callback(event);
+	};
+	panel.addEventListener("pointerdown", listener);
+	return () => {
+		panel.removeEventListener("pointerdown", listener);
+	};
+}
+/**
+* Call `callback` on Escape. By default it listens in the capture phase and
+* stops the event, so an enclosing dialog does not close as well.
+*/
+function onEscape(callback, options = {}) {
+	if (!hasDom()) return noop;
+	const capture = options.capture ?? true;
+	const listener = (event) => {
+		if (event.key !== "Escape") return;
+		if (options.stop ?? true) {
+			event.stopPropagation();
+			event.preventDefault();
+		}
+		callback(event);
+	};
+	window.addEventListener("keydown", listener, capture);
+	return () => {
+		window.removeEventListener("keydown", listener, capture);
+	};
+}
+/** Focus the first element in `container` matching `selector` (the roving-tabindex day by default). */
+function focusFirst(container, selector = "[tabindex=\"0\"]") {
+	const element = container?.querySelector(selector);
+	if (!element) return false;
+	element.focus();
+	return true;
+}
+/** Put focus back, e.g. on the input after the panel closes. */
+function restoreFocus(element) {
+	element?.focus({ preventScroll: true });
+}
+function noop() {}
+//#endregion
+export { computePosition, focusFirst, hasDom, onBackdropPointer, onEscape, onOutsidePointer, placePopover, prefersReducedMotion, resolveLayout, restoreFocus, supportsPopover, trackPosition };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["noop"],"sources":["../src/env.ts","../src/position.ts","../src/events.ts"],"sourcesContent":["/** True in a browser-like environment; false during server rendering. */\nexport function hasDom(): boolean {\n  return typeof window !== 'undefined' && typeof document !== 'undefined';\n}\n\n/** Whether the browser can show elements in the top layer (`popover` + `showPopover`). */\nexport function supportsPopover(): boolean {\n  return (\n    hasDom() &&\n    typeof HTMLElement !== 'undefined' &&\n    typeof HTMLElement.prototype.showPopover === 'function'\n  );\n}\n\n/** Whether the user asked the system for less motion. */\nexport function prefersReducedMotion(): boolean {\n  return (\n    hasDom() &&\n    typeof window.matchMedia === 'function' &&\n    window.matchMedia('(prefers-reduced-motion: reduce)').matches\n  );\n}\n","import { hasDom, supportsPopover } from './env';\n\nexport type Placement = 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end';\n\n/** 'popover' sits beside the anchor; 'sheet' is a bottom sheet; 'auto' picks the sheet on narrow screens. */\nexport type PanelLayout = 'auto' | 'popover' | 'sheet';\n\nexport interface PlaceOptions {\n  /** Space between the anchor and the panel, and kept from the viewport edges. Default 6. */\n  readonly gap?: number | undefined;\n  /** Panel width in px; shrinks to fit narrow screens. Default 320. */\n  readonly width?: number | undefined;\n  /** Preferred side; flips when there is not enough room. Default 'bottom-start'. */\n  readonly placement?: Placement | undefined;\n  /** Default 'auto'. */\n  readonly layout?: PanelLayout | undefined;\n  /** 'auto' uses the sheet below this viewport width, in px. Default 480. */\n  readonly sheetBelow?: number | undefined;\n}\n\n/** The layout to use for a viewport width. Pure. */\nexport function resolveLayout(\n  layout: PanelLayout | undefined,\n  viewportWidth: number,\n  sheetBelow = 480,\n): 'popover' | 'sheet' {\n  if (layout !== undefined && layout !== 'auto') {\n    return layout;\n  }\n\n  return viewportWidth < sheetBelow ? 'sheet' : 'popover';\n}\n\nexport interface Rect {\n  readonly top: number;\n  readonly left: number;\n  readonly bottom: number;\n  readonly right: number;\n}\n\nexport interface Position {\n  readonly top: number;\n  readonly left: number;\n  readonly width: number;\n  /** Where the panel ended up after flipping. */\n  readonly side: 'top' | 'bottom';\n}\n\n/**\n * Where to put a panel next to an anchor, in viewport (position: fixed)\n * coordinates. Pure, so it can be tested without a browser. Rules from the\n * institute-SaaS picker: prefer the requested side, flip when the panel does\n * not fit but does fit on the other side, and keep `gap` px from every edge\n * (the panel may overlap the anchor rather than leave the screen).\n */\nexport function computePosition(\n  anchor: Rect,\n  panelHeight: number,\n  viewport: { readonly width: number; readonly height: number },\n  options: PlaceOptions = {},\n): Position {\n  const gap = options.gap ?? 6;\n  const placement = options.placement ?? 'bottom-start';\n  const width = Math.max(0, Math.min(options.width ?? 320, viewport.width - gap * 2));\n  const roomBelow = viewport.height - anchor.bottom - gap * 2;\n  const roomAbove = anchor.top - gap * 2;\n  const wantsTop = placement.startsWith('top');\n  const side: 'top' | 'bottom' = wantsTop\n    ? roomAbove >= panelHeight || roomAbove >= roomBelow\n      ? 'top'\n      : 'bottom'\n    : roomBelow >= panelHeight || roomBelow >= roomAbove\n      ? 'bottom'\n      : 'top';\n  const rawTop = side === 'bottom' ? anchor.bottom + gap : anchor.top - gap - panelHeight;\n  const rawLeft = placement.endsWith('end') ? anchor.right - width : anchor.left;\n\n  return {\n    // Keep the whole panel on screen; when it is taller than the room, its top edge wins.\n    top: Math.max(gap, Math.min(rawTop, viewport.height - gap - panelHeight)),\n    left: Math.max(gap, Math.min(rawLeft, viewport.width - width - gap)),\n    width,\n    side,\n  };\n}\n\n/**\n * Show `panel` beside `anchor` once. Uses the browser's top layer when it can\n * (so dialogs and scrolling containers never clip the panel), otherwise\n * position: fixed. Returns a function that hides the panel again.\n */\nexport function placePopover(\n  anchor: Element,\n  panel: HTMLElement,\n  options: PlaceOptions = {},\n): () => void {\n  if (!hasDom()) {\n    return noop;\n  }\n  const topLayer = supportsPopover();\n  if (topLayer) {\n    if (!panel.hasAttribute('popover')) {\n      panel.setAttribute('popover', 'manual');\n    }\n    if (!panel.matches(':popover-open')) {\n      panel.showPopover();\n    }\n  }\n  const layout = resolveLayout(options.layout, window.innerWidth, options.sheetBelow);\n  panel.dataset['layout'] = layout;\n  if (layout === 'sheet') {\n    // The stylesheet pins a sheet to the bottom edge; clear any popover coordinates.\n    Object.assign(panel.style, {\n      top: '',\n      left: '',\n      width: '',\n      position: 'fixed',\n      margin: '0',\n      inset: 'auto 0 0 0',\n    });\n    delete panel.dataset['side'];\n\n    return hider(panel, topLayer);\n  }\n  const position = computePosition(\n    anchor.getBoundingClientRect(),\n    panel.offsetHeight,\n    { width: window.innerWidth, height: window.innerHeight },\n    options,\n  );\n  Object.assign(panel.style, {\n    position: 'fixed',\n    margin: '0',\n    inset: 'auto',\n    top: `${position.top}px`,\n    left: `${position.left}px`,\n    width: `${position.width}px`,\n  });\n  panel.dataset['side'] = position.side;\n\n  return hider(panel, topLayer);\n}\n\nfunction hider(panel: HTMLElement, topLayer: boolean): () => void {\n  return () => {\n    if (topLayer && panel.matches(':popover-open')) {\n      panel.hidePopover();\n    }\n  };\n}\n\n/**\n * Show the panel and keep it beside the anchor while the window resizes or\n * any ancestor scrolls. Returns a function that stops tracking and hides it.\n */\nexport function trackPosition(\n  anchor: Element,\n  panel: HTMLElement,\n  options: PlaceOptions = {},\n): () => void {\n  if (!hasDom()) {\n    return noop;\n  }\n  let hide = placePopover(anchor, panel, options);\n  const place = (): void => {\n    hide = placePopover(anchor, panel, options);\n  };\n  window.addEventListener('resize', place);\n  window.addEventListener('scroll', place, true);\n\n  return () => {\n    window.removeEventListener('resize', place);\n    window.removeEventListener('scroll', place, true);\n    hide();\n  };\n}\n\nfunction noop(): void {\n  // Nothing to undo outside a browser.\n}\n","import { hasDom } from './env';\n\ntype Targets =\n  | readonly (Element | null | undefined)[]\n  | (() => readonly (Element | null | undefined)[]);\n\n/**\n * Call `callback` when a pointer goes down outside all of `elements` (checked\n * in the capture phase, before the page reacts). Returns a cleanup function.\n */\nexport function onOutsidePointer(\n  elements: Targets,\n  callback: (event: PointerEvent) => void,\n): () => void {\n  if (!hasDom()) {\n    return noop;\n  }\n  const listener = (event: PointerEvent): void => {\n    const target = event.target;\n    const list = typeof elements === 'function' ? elements() : elements;\n    const inside =\n      target instanceof Node &&\n      list.some((element) => element?.contains(target) ?? false);\n    if (!inside) {\n      callback(event);\n    }\n  };\n  document.addEventListener('pointerdown', listener, true);\n\n  return () => {\n    document.removeEventListener('pointerdown', listener, true);\n  };\n}\n\n/**\n * Call `callback` when the pointer goes down on a panel's backdrop (the dimmed\n * area around a bottom sheet). A top-layer panel receives those events itself,\n * so they are told apart by position: on the panel, but outside its box.\n */\nexport function onBackdropPointer(\n  panel: HTMLElement,\n  callback: (event: PointerEvent) => void,\n): () => void {\n  if (!hasDom()) {\n    return noop;\n  }\n  const listener = (event: PointerEvent): void => {\n    if (event.target !== panel) {\n      return;\n    }\n    const box = panel.getBoundingClientRect();\n    const outside =\n      event.clientX < box.left ||\n      event.clientX > box.right ||\n      event.clientY < box.top ||\n      event.clientY > box.bottom;\n    if (outside) {\n      callback(event);\n    }\n  };\n  panel.addEventListener('pointerdown', listener);\n\n  return () => {\n    panel.removeEventListener('pointerdown', listener);\n  };\n}\n\n/**\n * Call `callback` on Escape. By default it listens in the capture phase and\n * stops the event, so an enclosing dialog does not close as well.\n */\nexport function onEscape(\n  callback: (event: KeyboardEvent) => void,\n  options: { readonly capture?: boolean; readonly stop?: boolean } = {},\n): () => void {\n  if (!hasDom()) {\n    return noop;\n  }\n  const capture = options.capture ?? true;\n  const listener = (event: KeyboardEvent): void => {\n    if (event.key !== 'Escape') {\n      return;\n    }\n    if (options.stop ?? true) {\n      event.stopPropagation();\n      event.preventDefault();\n    }\n    callback(event);\n  };\n  window.addEventListener('keydown', listener, capture);\n\n  return () => {\n    window.removeEventListener('keydown', listener, capture);\n  };\n}\n\n/** Focus the first element in `container` matching `selector` (the roving-tabindex day by default). */\nexport function focusFirst(\n  container: ParentNode | null,\n  selector = '[tabindex=\"0\"]',\n): boolean {\n  const element = container?.querySelector<HTMLElement>(selector);\n  if (!element) {\n    return false;\n  }\n  element.focus();\n\n  return true;\n}\n\n/** Put focus back, e.g. on the input after the panel closes. */\nexport function restoreFocus(element: HTMLElement | null | undefined): void {\n  element?.focus({ preventScroll: true });\n}\n\nfunction noop(): void {\n  // Nothing to undo outside a browser.\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@nepdatejs/dom",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Tiny browser helpers for @nepdatejs adapters: popover placement, outside click, Escape, focus.",
+  "keywords": [
+    "nepali",
+    "bikram-sambat",
+    "bs",
+    "nepali-date",
+    "date",
+    "calendar",
+    "datepicker",
+    "nepal"
+  ],
+  "license": "MIT",
+  "author": "Shishir Rai",
+  "homepage": "https://github.com/nepdate/nepdate/tree/main/packages/dom#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nepdate/nepdate.git",
+    "directory": "packages/dom"
+  },
+  "bugs": {
+    "url": "https://github.com/nepdate/nepdate/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "@nepdatejs/source": "./src/index.ts",
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.cts",
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json",
+    "check:package": "publint --strict && attw --pack"
+  }
 }

package/src/env.ts

@@ -0,0 +1,22 @@
+/** True in a browser-like environment; false during server rendering. */
+export function hasDom(): boolean {
+  return typeof window !== 'undefined' && typeof document !== 'undefined';
+}
+
+/** Whether the browser can show elements in the top layer (`popover` + `showPopover`). */
+export function supportsPopover(): boolean {
+  return (
+    hasDom() &&
+    typeof HTMLElement !== 'undefined' &&
+    typeof HTMLElement.prototype.showPopover === 'function'
+  );
+}
+
+/** Whether the user asked the system for less motion. */
+export function prefersReducedMotion(): boolean {
+  return (
+    hasDom() &&
+    typeof window.matchMedia === 'function' &&
+    window.matchMedia('(prefers-reduced-motion: reduce)').matches
+  );
+}

package/src/events.ts

@@ -0,0 +1,118 @@
+import { hasDom } from './env';
+
+type Targets =
+  | readonly (Element | null | undefined)[]
+  | (() => readonly (Element | null | undefined)[]);
+
+/**
+ * Call `callback` when a pointer goes down outside all of `elements` (checked
+ * in the capture phase, before the page reacts). Returns a cleanup function.
+ */
+export function onOutsidePointer(
+  elements: Targets,
+  callback: (event: PointerEvent) => void,
+): () => void {
+  if (!hasDom()) {
+    return noop;
+  }
+  const listener = (event: PointerEvent): void => {
+    const target = event.target;
+    const list = typeof elements === 'function' ? elements() : elements;
+    const inside =
+      target instanceof Node &&
+      list.some((element) => element?.contains(target) ?? false);
+    if (!inside) {
+      callback(event);
+    }
+  };
+  document.addEventListener('pointerdown', listener, true);
+
+  return () => {
+    document.removeEventListener('pointerdown', listener, true);
+  };
+}
+
+/**
+ * Call `callback` when the pointer goes down on a panel's backdrop (the dimmed
+ * area around a bottom sheet). A top-layer panel receives those events itself,
+ * so they are told apart by position: on the panel, but outside its box.
+ */
+export function onBackdropPointer(
+  panel: HTMLElement,
+  callback: (event: PointerEvent) => void,
+): () => void {
+  if (!hasDom()) {
+    return noop;
+  }
+  const listener = (event: PointerEvent): void => {
+    if (event.target !== panel) {
+      return;
+    }
+    const box = panel.getBoundingClientRect();
+    const outside =
+      event.clientX < box.left ||
+      event.clientX > box.right ||
+      event.clientY < box.top ||
+      event.clientY > box.bottom;
+    if (outside) {
+      callback(event);
+    }
+  };
+  panel.addEventListener('pointerdown', listener);
+
+  return () => {
+    panel.removeEventListener('pointerdown', listener);
+  };
+}
+
+/**
+ * Call `callback` on Escape. By default it listens in the capture phase and
+ * stops the event, so an enclosing dialog does not close as well.
+ */
+export function onEscape(
+  callback: (event: KeyboardEvent) => void,
+  options: { readonly capture?: boolean; readonly stop?: boolean } = {},
+): () => void {
+  if (!hasDom()) {
+    return noop;
+  }
+  const capture = options.capture ?? true;
+  const listener = (event: KeyboardEvent): void => {
+    if (event.key !== 'Escape') {
+      return;
+    }
+    if (options.stop ?? true) {
+      event.stopPropagation();
+      event.preventDefault();
+    }
+    callback(event);
+  };
+  window.addEventListener('keydown', listener, capture);
+
+  return () => {
+    window.removeEventListener('keydown', listener, capture);
+  };
+}
+
+/** Focus the first element in `container` matching `selector` (the roving-tabindex day by default). */
+export function focusFirst(
+  container: ParentNode | null,
+  selector = '[tabindex="0"]',
+): boolean {
+  const element = container?.querySelector<HTMLElement>(selector);
+  if (!element) {
+    return false;
+  }
+  element.focus();
+
+  return true;
+}
+
+/** Put focus back, e.g. on the input after the panel closes. */
+export function restoreFocus(element: HTMLElement | null | undefined): void {
+  element?.focus({ preventScroll: true });
+}
+
+function noop(): void {
+  // Nothing to undo outside a browser.
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @nepdatejs/dom: small browser helpers shared by the DOM adapters (vanilla,
+ * react, angular). Knows nothing about dates. Every helper is safe to call
+ * during server rendering and returns a cleanup function where it listens.
+ */
+export { hasDom, prefersReducedMotion, supportsPopover } from './env';
+export {
+  computePosition,
+  placePopover,
+  resolveLayout,
+  type PanelLayout,
+  trackPosition,
+  type Placement,
+  type PlaceOptions,
+  type Position,
+  type Rect,
+} from './position';
+export {
+  focusFirst,
+  onBackdropPointer,
+  onEscape,
+  onOutsidePointer,
+  restoreFocus,
+} from './events';

package/src/position.ts

@@ -0,0 +1,180 @@
+import { hasDom, supportsPopover } from './env';
+
+export type Placement = 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end';
+
+/** 'popover' sits beside the anchor; 'sheet' is a bottom sheet; 'auto' picks the sheet on narrow screens. */
+export type PanelLayout = 'auto' | 'popover' | 'sheet';
+
+export interface PlaceOptions {
+  /** Space between the anchor and the panel, and kept from the viewport edges. Default 6. */
+  readonly gap?: number | undefined;
+  /** Panel width in px; shrinks to fit narrow screens. Default 320. */
+  readonly width?: number | undefined;
+  /** Preferred side; flips when there is not enough room. Default 'bottom-start'. */
+  readonly placement?: Placement | undefined;
+  /** Default 'auto'. */
+  readonly layout?: PanelLayout | undefined;
+  /** 'auto' uses the sheet below this viewport width, in px. Default 480. */
+  readonly sheetBelow?: number | undefined;
+}
+
+/** The layout to use for a viewport width. Pure. */
+export function resolveLayout(
+  layout: PanelLayout | undefined,
+  viewportWidth: number,
+  sheetBelow = 480,
+): 'popover' | 'sheet' {
+  if (layout !== undefined && layout !== 'auto') {
+    return layout;
+  }
+
+  return viewportWidth < sheetBelow ? 'sheet' : 'popover';
+}
+
+export interface Rect {
+  readonly top: number;
+  readonly left: number;
+  readonly bottom: number;
+  readonly right: number;
+}
+
+export interface Position {
+  readonly top: number;
+  readonly left: number;
+  readonly width: number;
+  /** Where the panel ended up after flipping. */
+  readonly side: 'top' | 'bottom';
+}
+
+/**
+ * Where to put a panel next to an anchor, in viewport (position: fixed)
+ * coordinates. Pure, so it can be tested without a browser. Rules from the
+ * institute-SaaS picker: prefer the requested side, flip when the panel does
+ * not fit but does fit on the other side, and keep `gap` px from every edge
+ * (the panel may overlap the anchor rather than leave the screen).
+ */
+export function computePosition(
+  anchor: Rect,
+  panelHeight: number,
+  viewport: { readonly width: number; readonly height: number },
+  options: PlaceOptions = {},
+): Position {
+  const gap = options.gap ?? 6;
+  const placement = options.placement ?? 'bottom-start';
+  const width = Math.max(0, Math.min(options.width ?? 320, viewport.width - gap * 2));
+  const roomBelow = viewport.height - anchor.bottom - gap * 2;
+  const roomAbove = anchor.top - gap * 2;
+  const wantsTop = placement.startsWith('top');
+  const side: 'top' | 'bottom' = wantsTop
+    ? roomAbove >= panelHeight || roomAbove >= roomBelow
+      ? 'top'
+      : 'bottom'
+    : roomBelow >= panelHeight || roomBelow >= roomAbove
+      ? 'bottom'
+      : 'top';
+  const rawTop = side === 'bottom' ? anchor.bottom + gap : anchor.top - gap - panelHeight;
+  const rawLeft = placement.endsWith('end') ? anchor.right - width : anchor.left;
+
+  return {
+    // Keep the whole panel on screen; when it is taller than the room, its top edge wins.
+    top: Math.max(gap, Math.min(rawTop, viewport.height - gap - panelHeight)),
+    left: Math.max(gap, Math.min(rawLeft, viewport.width - width - gap)),
+    width,
+    side,
+  };
+}
+
+/**
+ * Show `panel` beside `anchor` once. Uses the browser's top layer when it can
+ * (so dialogs and scrolling containers never clip the panel), otherwise
+ * position: fixed. Returns a function that hides the panel again.
+ */
+export function placePopover(
+  anchor: Element,
+  panel: HTMLElement,
+  options: PlaceOptions = {},
+): () => void {
+  if (!hasDom()) {
+    return noop;
+  }
+  const topLayer = supportsPopover();
+  if (topLayer) {
+    if (!panel.hasAttribute('popover')) {
+      panel.setAttribute('popover', 'manual');
+    }
+    if (!panel.matches(':popover-open')) {
+      panel.showPopover();
+    }
+  }
+  const layout = resolveLayout(options.layout, window.innerWidth, options.sheetBelow);
+  panel.dataset['layout'] = layout;
+  if (layout === 'sheet') {
+    // The stylesheet pins a sheet to the bottom edge; clear any popover coordinates.
+    Object.assign(panel.style, {
+      top: '',
+      left: '',
+      width: '',
+      position: 'fixed',
+      margin: '0',
+      inset: 'auto 0 0 0',
+    });
+    delete panel.dataset['side'];
+
+    return hider(panel, topLayer);
+  }
+  const position = computePosition(
+    anchor.getBoundingClientRect(),
+    panel.offsetHeight,
+    { width: window.innerWidth, height: window.innerHeight },
+    options,
+  );
+  Object.assign(panel.style, {
+    position: 'fixed',
+    margin: '0',
+    inset: 'auto',
+    top: `${position.top}px`,
+    left: `${position.left}px`,
+    width: `${position.width}px`,
+  });
+  panel.dataset['side'] = position.side;
+
+  return hider(panel, topLayer);
+}
+
+function hider(panel: HTMLElement, topLayer: boolean): () => void {
+  return () => {
+    if (topLayer && panel.matches(':popover-open')) {
+      panel.hidePopover();
+    }
+  };
+}
+
+/**
+ * Show the panel and keep it beside the anchor while the window resizes or
+ * any ancestor scrolls. Returns a function that stops tracking and hides it.
+ */
+export function trackPosition(
+  anchor: Element,
+  panel: HTMLElement,
+  options: PlaceOptions = {},
+): () => void {
+  if (!hasDom()) {
+    return noop;
+  }
+  let hide = placePopover(anchor, panel, options);
+  const place = (): void => {
+    hide = placePopover(anchor, panel, options);
+  };
+  window.addEventListener('resize', place);
+  window.addEventListener('scroll', place, true);
+
+  return () => {
+    window.removeEventListener('resize', place);
+    window.removeEventListener('scroll', place, true);
+    hide();
+  };
+}
+
+function noop(): void {
+  // Nothing to undo outside a browser.
+}