@askrjs/askr 0.0.52 → 0.0.54

package/dist/foundations/interactions/pressable.d.ts

@@ -1,60 +0,0 @@
-import { DefaultPreventable, KeyboardLikeEvent, PropagationStoppable } from "../utilities/event-types.js";
-
-//#region src/foundations/interactions/pressable.d.ts
-/**
- * pressable
- *
- * Interaction helper that produces VNode props for 'press' semantics.
- * - Pure and deterministic: no DOM construction or mutation here
- * - The runtime owns event attachment and scheduling
- * - This helper returns plain props (handlers) intended to be attached by the runtime
- *
- * Behaviour:
- * - For native buttons: only an `onClick` prop is provided (no ARIA or keyboard shims)
- * - For non-button elements: add `role="button"` and `tabIndex` and keyboard handlers
- * - Activation: `Enter` activates on keydown, `Space` activates on keyup (matches native button)
- * - Disabled: handlers short-circuit and `aria-disabled` is set for all hosts
- *
- * POLICY DECISIONS (LOCKED):
- *
- * 1. Activation Timing (Platform Parity)
- *    - Enter fires on keydown (immediate response)
- *    - Space fires on keyup (allows cancel by moving focus, matches native)
- *    - Space keydown prevents scroll (matches native button behavior)
- *
- * 2. Disabled Enforcement Strategy
- *    - Native buttons: Use HTML `disabled` attribute (platform-enforced non-interactivity)
- *                     AND `aria-disabled` (consistent a11y signaling)
- *    - Non-native: Use `tabIndex=-1` (removes from tab order)
- *                  AND `aria-disabled` (signals disabled state to AT)
- *    - Click handler short-circuits as defense-in-depth (prevents leaked focus issues)
- *
- * 3. Key Repeat Behavior
- *    - Held Enter/Space will fire onPress repeatedly (matches native button)
- *    - No debouncing or repeat prevention (platform parity)
- */
-interface PressableOptions {
-  disabled?: boolean;
-  onPress?: (e: PressEvent) => void;
-  /**
-   * Whether the host is a native button. Defaults to false.
-   */
-  isNativeButton?: boolean;
-}
-type PressEvent = DefaultPreventable & PropagationStoppable;
-interface PressableResult {
-  onClick: (e: PressEvent) => void;
-  disabled?: true;
-  role?: 'button';
-  tabIndex?: number;
-  onKeyDown?: (e: KeyboardLikeEvent) => void;
-  onKeyUp?: (e: KeyboardLikeEvent) => void;
-  'aria-disabled'?: 'true';
-}
-declare function pressable({
-  disabled,
-  onPress,
-  isNativeButton
-}: PressableOptions): PressableResult;
-//#endregion
-export { PressableOptions, PressableResult, pressable };

package/dist/foundations/interactions/pressable.js

@@ -1,49 +0,0 @@
-import { ariaDisabled } from "../utilities/aria.js";
-//#region src/foundations/interactions/pressable.ts
-function pressable({ disabled, onPress, isNativeButton = false }) {
-	const props = { onClick: (e) => {
-		if (disabled) {
-			e.preventDefault?.();
-			e.stopPropagation?.();
-			return;
-		}
-		onPress?.(e);
-	} };
-	if (isNativeButton) {
-		if (disabled) {
-			props.disabled = true;
-			Object.assign(props, ariaDisabled(disabled));
-		}
-		return props;
-	}
-	props.role = "button";
-	props.tabIndex = disabled ? -1 : 0;
-	props.onKeyDown = (e) => {
-		if (disabled) {
-			e.preventDefault?.();
-			e.stopPropagation?.();
-			return;
-		}
-		if (e.key === "Enter") {
-			e.preventDefault?.();
-			onPress?.(e);
-			return;
-		}
-		if (e.key === " ") e.preventDefault?.();
-	};
-	props.onKeyUp = (e) => {
-		if (disabled) {
-			e.preventDefault?.();
-			e.stopPropagation?.();
-			return;
-		}
-		if (e.key === " ") {
-			e.preventDefault?.();
-			onPress?.(e);
-		}
-	};
-	if (disabled) Object.assign(props, ariaDisabled(disabled));
-	return props;
-}
-//#endregion
-export { pressable };

package/dist/foundations/interactions/roving-focus.d.ts

@@ -1,51 +0,0 @@
-import { KeyboardLikeEvent } from "../utilities/event-types.js";
-
-//#region src/foundations/interactions/roving-focus.d.ts
-type Orientation = 'horizontal' | 'vertical' | 'both';
-interface RovingFocusOptions {
-  /**
-   * Current focused index
-   */
-  currentIndex: number;
-  /**
-   * Total number of items
-   */
-  itemCount: number;
-  /**
-   * Navigation orientation
-   * - horizontal: ArrowLeft/ArrowRight
-   * - vertical: ArrowUp/ArrowDown
-   * - both: all arrow keys
-   */
-  orientation?: Orientation;
-  /**
-   * Whether to loop when reaching the end
-   */
-  loop?: boolean;
-  /**
-   * Callback when navigation occurs
-   */
-  onNavigate?: (index: number) => void;
-  /**
-   * Optional disabled state check per index
-   */
-  isDisabled?: (index: number) => boolean;
-}
-interface RovingFocusResult {
-  /**
-   * Props for the container element (composes via mergeProps)
-   */
-  container: {
-    onKeyDown: (e: KeyboardLikeEvent) => void;
-  };
-  /**
-   * Generate props for an item at the given index (composes via mergeProps)
-   */
-  item: (index: number) => {
-    tabIndex: number;
-    'data-roving-index': number;
-  };
-}
-declare function rovingFocus(options: RovingFocusOptions): RovingFocusResult;
-//#endregion
-export { Orientation, RovingFocusOptions, RovingFocusResult, rovingFocus };

package/dist/foundations/interactions/roving-focus.js

@@ -1,69 +0,0 @@
-//#region src/foundations/interactions/roving-focus.ts
-function rovingFocus(options) {
-	const { currentIndex, itemCount, orientation = "horizontal", loop = false, onNavigate, isDisabled } = options;
-	function findNextIndex(from, direction) {
-		let next = from;
-		for (let steps = 0; steps < itemCount; steps += 1) {
-			next += direction;
-			if (loop) {
-				if (next < 0) next = itemCount - 1;
-				if (next >= itemCount) next = 0;
-			} else if (next < 0 || next >= itemCount) return;
-			if (next === from) return void 0;
-			if (!isDisabled?.(next)) return next;
-		}
-	}
-	function handleKeyDown(e) {
-		const { key } = e;
-		let direction;
-		if (orientation === "horizontal" || orientation === "both") {
-			if (key === "ArrowRight") direction = 1;
-			if (key === "ArrowLeft") direction = -1;
-		}
-		if (orientation === "vertical" || orientation === "both") {
-			if (key === "ArrowDown") direction = 1;
-			if (key === "ArrowUp") direction = -1;
-		}
-		if (direction === void 0) return;
-		const nextIndex = findNextIndex(currentIndex, direction);
-		if (nextIndex === void 0) return;
-		e.preventDefault?.();
-		e.stopPropagation?.();
-		onNavigate?.(nextIndex);
-	}
-	return {
-		container: { onKeyDown: handleKeyDown },
-		item: (index) => ({
-			tabIndex: index === currentIndex ? 0 : -1,
-			"data-roving-index": index
-		})
-	};
-}
-/**
-* USAGE EXAMPLE:
-*
-* function Menu() {
-*   const [focusIndex, setFocusIndex] = state(0);
-*   const items = ['File', 'Edit', 'View'];
-*
-*   const navigation = rovingFocus({
-*     currentIndex: focusIndex(),
-*     itemCount: items.length,
-*     orientation: 'horizontal',
-*     loop: true,
-*     onNavigate: setFocusIndex,
-*   });
-*
-*   return (
-*     <div {...navigation.container}>
-*       {items.map((label, index) => (
-*         <button {...navigation.item(index)}>
-*           {label}
-*         </button>
-*       ))}
-*     </div>
-*   );
-* }
-*/
-//#endregion
-export { rovingFocus };

package/dist/foundations/state/controllable.d.ts

@@ -1,32 +0,0 @@
-import { State } from "../../runtime/state.js";
-//#region src/foundations/state/controllable.d.ts
-declare function isControlled<T>(value: T | undefined): value is T;
-declare function resolveControllable<T>(value: T | undefined, defaultValue: T): {
-  value: T;
-  isControlled: boolean;
-};
-declare function makeControllable<T>(options: {
-  value: T | undefined;
-  defaultValue: T;
-  onChange?: (next: T) => void;
-  setInternal?: (next: T) => void;
-}): {
-  set: (next: T) => void;
-  isControlled: boolean;
-};
-type ControllableState<T> = State<T> & {
-  isControlled: boolean;
-};
-/**
- * controllableState
- *
- * Hook-like primitive that mirrors `state()` semantics while supporting
- * controlled/uncontrolled behavior.
- */
-declare function controllableState<T>(options: {
-  value: T | undefined;
-  defaultValue: T;
-  onChange?: (next: T) => void;
-}): ControllableState<T>;
-//#endregion
-export { ControllableState, controllableState, isControlled, makeControllable, resolveControllable };

package/dist/foundations/state/controllable.js

@@ -1,80 +0,0 @@
-import { state } from "../../runtime/state.js";
-import "../../runtime/index.js";
-//#region src/foundations/state/controllable.ts
-/**
-* controllable
-*
-* Small utilities for controlled vs uncontrolled components. These helpers are
-* intentionally minimal and do not manage state themselves; they help component
-* implementations make correct decisions about when to call `onChange` vs
-* update internal state.
-*
-* POLICY DECISIONS (LOCKED):
-*
-* 1. Controlled Detection
-*    A value is "controlled" if it is not `undefined`.
-*    This matches React conventions and is SSR-safe.
-*
-* 2. onChange Timing
-*    - Controlled mode: onChange called immediately, no internal update
-*    - Uncontrolled mode: internal state updated first, then onChange called
-*    This ensures onChange sees the new value in both modes.
-*
-* 3. Value Equality
-*    controllableState uses Object.is() to prevent unnecessary onChange calls.
-*    This is intentional — strict equality, no deep comparison.
-*/
-function isControlled(value) {
-	return value !== void 0;
-}
-function resolveControllable(value, defaultValue) {
-	const controlled = isControlled(value);
-	return {
-		value: controlled ? value : defaultValue,
-		isControlled: controlled
-	};
-}
-function makeControllable(options) {
-	const { value, defaultValue, onChange, setInternal } = options;
-	const { isControlled } = resolveControllable(value, defaultValue);
-	function set(next) {
-		if (isControlled) onChange?.(next);
-		else {
-			setInternal?.(next);
-			onChange?.(next);
-		}
-	}
-	return {
-		set,
-		isControlled
-	};
-}
-/**
-* controllableState
-*
-* Hook-like primitive that mirrors `state()` semantics while supporting
-* controlled/uncontrolled behavior.
-*/
-function controllableState(options) {
-	const isControlled = options.value !== void 0;
-	const internal = isControlled ? null : state(options.defaultValue);
-	function read() {
-		if (isControlled) return options.value;
-		return internal();
-	}
-	read.set = (nextOrUpdater) => {
-		const prev = read();
-		const next = typeof nextOrUpdater === "function" ? nextOrUpdater(prev) : nextOrUpdater;
-		if (Object.is(prev, next)) return;
-		if (isControlled) {
-			options.onChange?.(next);
-			return;
-		}
-		internal.set(nextOrUpdater);
-		options.onChange?.(next);
-	};
-	read.isControlled = isControlled;
-	return read;
-}
-//#endregion
-export { controllableState, isControlled, makeControllable, resolveControllable };

package/dist/foundations/structures/collection.d.ts

@@ -1,51 +0,0 @@
-//#region src/foundations/structures/collection.d.ts
-/**
- * createCollection
- *
- * Ordered descendant registry for coordinating items without DOM queries.
- *
- * INVARIANTS:
- * 1. Registration order determines item order (no DOM queries)
- * 2. Stable ordering across renders (insertion order preserved)
- * 3. Each item may have metadata (type-safe, user-defined)
- * 4. No implicit global state (explicit collection instances)
- * 5. No automatic cleanup (caller controls lifecycle)
- *
- * DESIGN:
- * - Returns a registry API ({ register, items, clear })
- * - Items are stored in insertion order
- * - Registration returns an unregister function
- * - No side effects on registration (pure data structure)
- *
- * USAGE:
- *   const collection = createCollection<HTMLElement, { disabled: boolean }>();
- *   const unregister = collection.register(element, { disabled: false });
- *   const allItems = collection.items();
- *   unregister();
- */
-type CollectionItem<TNode, TMetadata = unknown> = {
-  node: TNode;
-  metadata: TMetadata;
-};
-interface Collection<TNode, TMetadata = unknown> {
-  /**
-   * Register a node with optional metadata.
-   * Returns an unregister function.
-   */
-  register(node: TNode, metadata: TMetadata): () => void;
-  /**
-   * Get all registered items in insertion order.
-   */
-  items(): ReadonlyArray<CollectionItem<TNode, TMetadata>>;
-  /**
-   * Clear all registered items.
-   */
-  clear(): void;
-  /**
-   * Get the count of registered items.
-   */
-  size(): number;
-}
-declare function createCollection<TNode, TMetadata = unknown>(): Collection<TNode, TMetadata>;
-//#endregion
-export { Collection, CollectionItem, createCollection };

package/dist/foundations/structures/collection.js

@@ -1,49 +0,0 @@
-//#region src/foundations/structures/collection.ts
-function createCollection() {
-	const registry = /* @__PURE__ */ new Map();
-	function register(node, metadata) {
-		const item = {
-			node,
-			metadata
-		};
-		registry.set(node, item);
-		return () => {
-			registry.delete(node);
-		};
-	}
-	function items() {
-		return Array.from(registry.values());
-	}
-	function clear() {
-		registry.clear();
-	}
-	function size() {
-		return registry.size;
-	}
-	return {
-		register,
-		items,
-		clear,
-		size
-	};
-}
-/**
-* USAGE EXAMPLE:
-*
-* // Create a collection for menu items
-* const menuItems = createCollection<HTMLElement, { disabled: boolean }>();
-*
-* // Register items
-* const unregister1 = menuItems.register(element1, { disabled: false });
-* const unregister2 = menuItems.register(element2, { disabled: true });
-*
-* // Query items
-* const allItems = menuItems.items();
-* const enabledItems = allItems.filter(item => !item.metadata.disabled);
-*
-* // Cleanup
-* unregister1();
-* unregister2();
-*/
-//#endregion
-export { createCollection };

package/dist/foundations/structures/layer.d.ts

@@ -1,80 +0,0 @@
-//#region src/foundations/structures/layer.d.ts
-/**
- * createLayer
- *
- * Manages stacking order and coordination for overlays (modals, popovers, etc).
- *
- * INVARIANTS:
- * 1. Layers are ordered by registration time (FIFO)
- * 2. Only the top layer handles Escape key
- * 3. Only the top layer handles outside pointer events
- * 4. Nested layers are supported
- * 5. Does not implement portals (orthogonal concern)
- * 6. No automatic DOM insertion (caller controls mounting)
- *
- * DESIGN:
- * - Returns a layer manager with register/unregister API
- * - Each layer has a unique ID and can query if it's the top layer
- * - Escape and outside pointer coordination via callbacks
- * - No z-index management (CSS concern)
- *
- * USAGE:
- *   const manager = createLayer();
- *
- *   const layer = manager.register({
- *     onEscape: () => { ... },
- *     onOutsidePointer: () => { ... }
- *   });
- *
- *   layer.isTop(); // true if this is the topmost layer
- *   layer.unregister();
- */
-interface LayerOptions {
-  /**
-   * Called when Escape is pressed and this is the top layer
-   */
-  onEscape?: () => void;
-  /**
-   * Called when pointer event occurs outside and this is the top layer
-   */
-  onOutsidePointer?: (e: PointerEvent) => void;
-  /**
-   * Optional node reference for outside pointer detection
-   */
-  node?: Node | null;
-}
-interface Layer {
-  /**
-   * Unique layer ID
-   */
-  id: number;
-  /**
-   * Check if this layer is the topmost
-   */
-  isTop(): boolean;
-  /**
-   * Remove this layer from the stack
-   */
-  unregister(): void;
-}
-interface LayerManager {
-  /**
-   * Register a new layer
-   */
-  register(options: LayerOptions): Layer;
-  /**
-   * Get all active layers in order
-   */
-  layers(): ReadonlyArray<Layer>;
-  /**
-   * Manually trigger escape handling on the top layer
-   */
-  handleEscape(): void;
-  /**
-   * Manually trigger outside pointer handling on the top layer
-   */
-  handleOutsidePointer(e: PointerEvent): void;
-}
-declare function createLayer(): LayerManager;
-//#endregion
-export { Layer, LayerManager, LayerOptions, createLayer };

package/dist/foundations/structures/layer.js

@@ -1,79 +0,0 @@
-//#region src/foundations/structures/layer.ts
-function createLayer() {
-	const stack = [];
-	let nextId = 1;
-	function register(options) {
-		const id = nextId++;
-		const entry = {
-			id,
-			options
-		};
-		stack.push(entry);
-		function isTop() {
-			return stack[stack.length - 1]?.id === id;
-		}
-		function unregister() {
-			const index = stack.findIndex((e) => e.id === id);
-			if (index !== -1) stack.splice(index, 1);
-		}
-		return {
-			id,
-			isTop,
-			unregister
-		};
-	}
-	function layers() {
-		return stack.map((entry) => ({
-			id: entry.id,
-			isTop: () => stack[stack.length - 1]?.id === entry.id,
-			unregister: () => {
-				const index = stack.findIndex((e) => e.id === entry.id);
-				if (index !== -1) stack.splice(index, 1);
-			}
-		}));
-	}
-	function handleEscape() {
-		const top = stack[stack.length - 1];
-		if (top) top.options.onEscape?.();
-	}
-	function handleOutsidePointer(e) {
-		const top = stack[stack.length - 1];
-		if (!top) return;
-		const node = top.options.node;
-		if (node && e.target instanceof Node) {
-			if (!node.contains(e.target)) top.options.onOutsidePointer?.(e);
-		} else top.options.onOutsidePointer?.(e);
-	}
-	return {
-		register,
-		layers,
-		handleEscape,
-		handleOutsidePointer
-	};
-}
-/**
-* USAGE EXAMPLE:
-*
-* const layerManager = createLayer();
-*
-* function Modal({ onClose }) {
-*   const modalRef = ref<HTMLDivElement>();
-*
-*   const layer = layerManager.register({
-*     node: modalRef.current,
-*     onEscape: onClose,
-*     onOutsidePointer: onClose,
-*   });
-*
-*   onUnmount(() => layer.unregister());
-*
-*   return (
-*     <div ref={modalRef}>
-*       <h1>Modal</h1>
-*       {layer.isTop() && <p>I am on top!</p>}
-*     </div>
-*   );
-* }
-*/
-//#endregion
-export { createLayer };

package/dist/foundations/structures/layout.d.ts

@@ -1,32 +0,0 @@
-import { RenderableChild } from "../../common/vnode.js";
-
-//#region src/foundations/structures/layout.d.ts
-/**
- * Layout helper.
- *
- * A layout is just a normal component that wraps children.
- * Persistence and reuse are handled by the runtime via component identity.
- *
- * This helper exists purely for readability and convention.
- *
- * POLICY DECISIONS (LOCKED):
- *
- * 1. Return Type is Opaque (unknown)
- *    Layout components return `unknown` to remain runtime-agnostic.
- *    The runtime owns concrete JSX element types.
- *
- * 2. Children Positioning
- *    Layout receives children as first argument (router-friendly).
- *    Props come second. This matches route layout conventions where
- *    children represent the nested route content.
- *
- * 3. Props Spreading
- *    Props are spread into the layout component. This is intentional
- *    and deterministic — no merging or composition.
- */
-type LayoutComponent<P = object> = (props: P & {
-  children?: RenderableChild;
-}) => unknown;
-declare function layout<P = object>(Layout: LayoutComponent<P>): (children?: RenderableChild, props?: P) => unknown;
-//#endregion
-export { LayoutComponent, layout };

package/dist/foundations/structures/layout.js

@@ -1,11 +0,0 @@
-//#region src/foundations/structures/layout.tsx
-function layout(Layout) {
-	return (children, props) => {
-		return Layout({
-			...props,
-			children
-		});
-	};
-}
-//#endregion
-export { layout };

package/dist/foundations/structures/portal.d.ts

@@ -1,2 +0,0 @@
-import { DefaultPortal, Portal, PortalProps, definePortal } from "../../runtime/portal.js";
-export { DefaultPortal, Portal, type PortalProps, definePortal };

package/dist/foundations/structures/portal.js

@@ -1,3 +0,0 @@
-import { DefaultPortal, Portal, definePortal } from "../../runtime/portal.js";
-import "../../runtime/index.js";
-export { DefaultPortal, Portal, definePortal };

package/dist/foundations/structures/presence.d.ts

@@ -1,36 +0,0 @@
-import { JSXElement } from "../../common/jsx.js";
-import { RenderableChild } from "../../common/vnode.js";
-//#region src/foundations/structures/presence.d.ts
-interface PresenceProps {
-  present: boolean | (() => boolean);
-  children?: RenderableChild;
-}
-/**
- * Presence
- *
- * Structural policy primitive for conditional mount/unmount.
- * - No timers
- * - No animation coupling
- * - No DOM side-effects
- *
- * POLICY DECISIONS (LOCKED):
- *
- * 1. Present as Function
- *    Accepts boolean OR function to support lazy evaluation patterns.
- *    Function is called once per render. Use boolean form for static values.
- *
- * 2. Children Type
- *    Presence forwards normal renderable child content only.
- *    Imperative DOM nodes are not part of the public contract.
- *
- * 3. Immediate Mount/Unmount
- *    No exit animations or transitions. When `present` becomes false,
- *    children are removed immediately. Animation must be layered above
- *    this primitive.
- */
-declare function Presence({
-  present,
-  children
-}: PresenceProps): JSXElement | null;
-//#endregion
-export { Presence, PresenceProps };