@jcsoftdev/ui 0.1.6 → 0.2.0

package/src/primitives/focusable.ts

@@ -0,0 +1,85 @@
+const TABBABLE_SELECTOR = [
+  "a[href]",
+  "area[href]",
+  "button:not([disabled])",
+  "input:not([disabled]):not([type=hidden])",
+  "select:not([disabled])",
+  "textarea:not([disabled])",
+  "iframe",
+  "audio[controls]",
+  "video[controls]",
+  "summary",
+  "[contenteditable]:not([contenteditable=false])",
+  "[tabindex]",
+].join(",");
+
+function isRendered(element: HTMLElement): boolean {
+  if (element.closest("[inert]")) return false;
+  if (typeof element.checkVisibility === "function") {
+    return element.checkVisibility({ visibilityProperty: true });
+  }
+  return element.getClientRects().length > 0;
+}
+
+/** Elements reachable with Tab inside `root`, in DOM order. */
+export function getTabbables(root: HTMLElement): HTMLElement[] {
+  const found = root.querySelectorAll<HTMLElement>(TABBABLE_SELECTOR);
+  return Array.from(found).filter((element) => element.tabIndex >= 0 && isRendered(element));
+}
+
+/**
+ * Where Tab or Shift+Tab must be redirected to keep focus inside a trap, or `null`
+ * when the browser's own move stays inside. An `active` outside `items` (the
+ * container itself, or `body`) enters the list from the matching end.
+ */
+export function resolveTabWrap<T>(items: readonly T[], active: T | null, shift: boolean): T | null {
+  if (items.length === 0) return null;
+  const first = items[0] as T;
+  const last = items[items.length - 1] as T;
+  if (active === null || !items.includes(active)) return shift ? last : first;
+  if (!shift && active === last) return first;
+  if (shift && active === first) return last;
+  return null;
+}
+
+/**
+ * Tab target when focus sits on a non-tabbable node inside the container (a
+ * `tabindex="-1"` region): the neighbouring tabbable in document order, wrapping
+ * at the ends. Mirrors the browser's own sequential navigation start point.
+ */
+export function resolveTabFromInside(
+  items: readonly HTMLElement[],
+  active: HTMLElement,
+  shift: boolean,
+): HTMLElement | null {
+  if (items.length === 0) return null;
+  const follows = (item: HTMLElement) =>
+    Boolean(active.compareDocumentPosition(item) & Node.DOCUMENT_POSITION_FOLLOWING);
+  if (shift) {
+    const before = items.filter((item) => !follows(item));
+    return before[before.length - 1] ?? items[items.length - 1] ?? null;
+  }
+  return items.find((item) => follows(item)) ?? items[0] ?? null;
+}
+
+/**
+ * Where focus goes when a portaled layer opened from `trigger` is left with Tab: the
+ * first tabbable after the trigger in document order, or with `backwards` the trigger
+ * itself when tabbable, else the closest tabbable before it. Elements inside `exclude`
+ * (the layer) or the trigger are skipped; `null` when nothing qualifies.
+ */
+export function resolveTabOut(
+  trigger: HTMLElement,
+  exclude: HTMLElement | null,
+  backwards: boolean,
+): HTMLElement | null {
+  const items = getTabbables(document.body).filter((element) => !exclude?.contains(element));
+  const follows = (element: HTMLElement) =>
+    Boolean(trigger.compareDocumentPosition(element) & Node.DOCUMENT_POSITION_FOLLOWING);
+  if (!backwards) {
+    return items.find((element) => !trigger.contains(element) && follows(element)) ?? null;
+  }
+  if (items.includes(trigger)) return trigger;
+  const before = items.filter((element) => !trigger.contains(element) && !follows(element));
+  return before[before.length - 1] ?? null;
+}

package/src/primitives/global-singleton.ts

@@ -0,0 +1,10 @@
+/**
+ * One instance per `key` across every copy of this module on the page (duplicate
+ * package installs, split bundles), so layer, scroll-lock and hide state stay shared.
+ */
+export function globalSingleton<T>(key: string, create: () => T): T {
+  const store = globalThis as unknown as Record<symbol, unknown>;
+  const symbol = Symbol.for(key);
+  if (!(symbol in store)) store[symbol] = create();
+  return store[symbol] as T;
+}

package/src/primitives/hide-others.ts

@@ -0,0 +1,116 @@
+import { globalSingleton } from "./global-singleton.js";
+
+/** Never hidden: scripts and styles, live regions (toaster) and explicit opt-outs. */
+const IGNORED = '[aria-live]:not([aria-live="off"]), [data-ui-overlay-ignore]';
+const SKIP = `script, style, template, ${IGNORED}`;
+
+interface Instance {
+  hide: ReadonlySet<Element>;
+}
+
+/** Attributes this module wrote on an element, with the value to put back. Absent means not ours. */
+interface Owned {
+  ariaHidden?: { previous: string | null };
+  inert?: { previous: string | null };
+}
+
+interface HideState {
+  instances: Instance[];
+  applied: Map<Element, Owned>;
+}
+
+const state = globalSingleton<HideState>("@jcsoftdev/ui/hide-others", () => ({
+  instances: [],
+  applied: new Map(),
+}));
+
+function put(element: Element, name: string, previous: string | null) {
+  if (previous === null) element.removeAttribute(name);
+  else element.setAttribute(name, previous);
+}
+
+/** Releases only what we wrote and only while it is still ours: values changed or removed by others stay as they are. */
+function release(element: Element, owned: Owned) {
+  if (owned.ariaHidden && element.getAttribute("aria-hidden") === "true") {
+    put(element, "aria-hidden", owned.ariaHidden.previous);
+  }
+  if (owned.inert && element.hasAttribute("inert")) {
+    put(element, "inert", owned.inert.previous);
+  }
+}
+
+/** Only the most recently opened modal decides what is hidden; releasing it re-applies the one below. */
+function reconcile() {
+  for (const [element, owned] of state.applied) release(element, owned);
+  state.applied.clear();
+  const top = state.instances[state.instances.length - 1];
+  if (!top) return;
+  for (const element of top.hide) {
+    if (!element.isConnected) continue;
+    const owned: Owned = {};
+    // Already hidden by someone else (e.g. a Radix menu's own hider): uncontrolled, never touched or restored.
+    if (element.getAttribute("aria-hidden") !== "true") {
+      owned.ariaHidden = { previous: element.getAttribute("aria-hidden") };
+      element.setAttribute("aria-hidden", "true");
+    }
+    if (!element.hasAttribute("inert")) {
+      owned.inert = { previous: null };
+      element.setAttribute("inert", "");
+    }
+    if (owned.ariaHidden || owned.inert) state.applied.set(element, owned);
+  }
+}
+
+function withinKept(node: Element, kept: readonly Element[]): boolean {
+  return kept.some((keep) => keep.contains(node));
+}
+
+function computeHidden(kept: readonly Element[]): Set<Element> {
+  const leaves = new Set<Element>(kept);
+  for (const ignored of document.querySelectorAll(IGNORED)) {
+    if (!withinKept(ignored, kept)) leaves.add(ignored);
+  }
+  const ancestors = new Set<Element>();
+  for (const leaf of leaves) {
+    for (let current = leaf.parentElement; current; current = current.parentElement) {
+      ancestors.add(current);
+      if (current === document.body) break;
+    }
+  }
+  const hide = new Set<Element>();
+  for (const ancestor of ancestors) {
+    for (const child of Array.from(ancestor.children)) {
+      if (leaves.has(child) || ancestors.has(child) || child.matches(SKIP)) continue;
+      hide.add(child);
+    }
+  }
+  return hide;
+}
+
+/**
+ * Makes everything outside `keep` unreachable (`aria-hidden` + `inert`) by hiding,
+ * at every level on the way to `body`, the siblings of each kept node. Live
+ * regions and `[data-ui-overlay-ignore]` elements stay reachable even when nested
+ * inside an otherwise hidden subtree. The most recent call wins, so a nested modal
+ * portaled into a container that an outer modal hid is still usable, and releases
+ * can happen in any order.
+ *
+ * Only attributes written here are released, and only while they still hold our
+ * value; an element already `aria-hidden="true"` or `inert` from elsewhere is left
+ * alone. Like Radix, nodes appended to `body` after a modal opens (and not kept)
+ * are not hidden until the modal is reopened.
+ */
+export function hideOthers(keep: ReadonlyArray<Element | null | undefined>): () => void {
+  const kept = keep.filter((node): node is Element => Boolean(node));
+  const instance: Instance = { hide: computeHidden(kept) };
+  state.instances.push(instance);
+  reconcile();
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    const index = state.instances.indexOf(instance);
+    if (index !== -1) state.instances.splice(index, 1);
+    reconcile();
+  };
+}

package/src/primitives/index.ts

@@ -0,0 +1,42 @@
+/**
+ * Unstyled, headless behaviour primitives. No Tailwind classes or tokens live here:
+ * parts forward props and refs, expose `data-state`, and take `asChild` where a
+ * trigger makes sense. Styled components in `overlays/` are built on top of them.
+ *
+ * Only the building blocks meant for consumers are exported. Internals (layer
+ * stack singleton, scroll lock, `hideOthers`, tab helpers) are imported by file
+ * from inside the package. The package `./*` wildcard export already resolves
+ * `@jcsoftdev/ui/primitives` to this barrel (built as `dist/primitives/index.js`);
+ * deep paths such as `primitives/hide-others` do not resolve. The documented,
+ * explicit entry is defined in T14.
+ */
+export * as CommandPrimitive from "./command/command.js";
+export { type CommandFilter, commandScore } from "./command/score.js";
+export * as DialogPrimitive from "./dialog/dialog.js";
+export * as MenuPrimitive from "./menu/menu.js";
+export * as PopoverPrimitive from "./popover/popover.js";
+export type {
+  Align,
+  ArrowGeometry,
+  Direction,
+  Padding,
+  Placement,
+  PlacementInput,
+  Rect,
+  Side,
+  Size,
+} from "./popper/geometry.js";
+export { computePlacement } from "./popper/geometry.js";
+export * as PopperPrimitive from "./popper/popper.js";
+export { Portal } from "./portal.js";
+export {
+  type DismissableLayerOptions,
+  type FocusOutsideEvent,
+  type InteractOutsideEvent,
+  LAYER_BRANCH_ATTRIBUTE,
+  type PointerDownOutsideEvent,
+  useDismissableLayer,
+} from "./use-dismissable-layer.js";
+export { type FocusScopeOptions, useFocusScope } from "./use-focus-scope.js";
+export { useLayer } from "./use-layer.js";
+export { usePresence } from "./use-presence.js";

package/src/primitives/layer-stack.ts

@@ -0,0 +1,27 @@
+import { globalSingleton } from "./global-singleton.js";
+
+/** Ordered stack of open overlay layers; only the topmost reacts to Escape and outside presses. */
+export interface LayerStack<T extends object = object> {
+  push(layer: T): () => void;
+  isTop(layer: T): boolean;
+  size(): number;
+}
+
+export function createLayerStack<T extends object = object>(): LayerStack<T> {
+  const layers: T[] = [];
+  return {
+    push(layer) {
+      layers.push(layer);
+      return () => {
+        const index = layers.indexOf(layer);
+        if (index !== -1) layers.splice(index, 1);
+      };
+    },
+    isTop: (layer) => layers[layers.length - 1] === layer,
+    size: () => layers.length,
+  };
+}
+
+export const overlayLayers = globalSingleton("@jcsoftdev/ui/overlay-layers", () =>
+  createLayerStack(),
+);

package/src/primitives/menu/grace.ts

@@ -0,0 +1,40 @@
+export interface Point {
+  x: number;
+  y: number;
+}
+export interface BoxEdges {
+  left: number;
+  right: number;
+  top: number;
+  bottom: number;
+}
+
+/**
+ * Triangle-like area between the pointer leaving a submenu trigger and the submenu,
+ * so the pointer can cross other items on its way without closing the submenu.
+ */
+export function graceArea(exit: Point, side: "left" | "right", box: BoxEdges): Point[] {
+  const rightSide = side === "right";
+  const bleed = rightSide ? -5 : 5;
+  const near = rightSide ? box.left : box.right;
+  const far = rightSide ? box.right : box.left;
+  return [
+    { x: exit.x + bleed, y: exit.y },
+    { x: near, y: box.top },
+    { x: far, y: box.top },
+    { x: far, y: box.bottom },
+    { x: near, y: box.bottom },
+  ];
+}
+
+/** Ray-casting point-in-polygon test. */
+export function isPointInPolygon(point: Point, polygon: readonly Point[]): boolean {
+  const { x, y } = point;
+  let inside = false;
+  for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i++) {
+    const a = polygon[i] as Point;
+    const b = polygon[j] as Point;
+    if (a.y > y !== b.y > y && x < ((b.x - a.x) * (y - a.y)) / (b.y - a.y) + a.x) inside = !inside;
+  }
+  return inside;
+}