@monstermann/signals-modal 0.4.3 → 0.4.5

package/dist/position/withBoundary.mjs

@@ -8,19 +8,49 @@ import { fromWindow } from "@monstermann/geometry/Rect/fromWindow.mjs";
 const path = "@signals-modal/position/withBoundary.ts";
 const meta = {
 	path,
-	line: 15,
+	line: 45,
 	name: "withBoundary.$rect"
 };
 const meta1 = {
 	path,
-	line: 20,
+	line: 50,
 	name: "withBoundary.$boundary"
 };
 const meta2 = {
 	path,
-	line: 24,
+	line: 54,
 	name: "withBoundary"
 };
+/**
+* # withBoundary
+*
+* ```ts
+* function withBoundary(options: {
+*     $status: Reactive<ModalStatus>;
+*     transform?: (rect: Rect) => Rect;
+* }): Memo<Rect>;
+* ```
+*
+* Constructs a `Rect` resembling the window dimensions, to be fed into `withPlacement` and `withPosition`, used to constrain the floating element to be within the window boundary. This function must be called inside a `createModal` callback.
+*
+* The optional `transform` option can be used to eg. make the `Rect` smaller, increasing the distance between the floating element and the edges of the window.
+*
+* ## Example
+*
+* ```ts
+* import {
+*     createModal,
+*     withModalStatus,
+*     withBoundary,
+* } from "@monstermann/signals-modal";
+*
+* createModal("key", () => {
+*     const { $status } = withModalStatus();
+*     const $boundary = withBoundary({ $status });
+* });
+* ```
+*
+*/
 function withBoundary(options) {
 	const modal = currentModal();
 	const $rect = signal(origin, {

package/dist/position/withPlacement.d.mts

@@ -1,9 +1,86 @@
 import { Memo } from "@monstermann/signals";
-import { Rect } from "@monstermann/fn";
+import { Rect } from "@monstermann/geometry";
 
 //#region src/position/withPlacement.d.ts
 type ModalPlacementOption = "vertical-center" | "vertical-left" | "vertical-right" | "horizontal-center" | "horizontal-up" | "horizontal-down" | "up-center" | "down-center" | "left-down" | "right-down";
 type ModalPlacement = "down-center" | "down-left" | "down-right" | "left-center" | "left-down" | "left-up" | "right-center" | "right-down" | "right-up" | "up-center" | "up-left" | "up-right";
+/**
+ * # withPlacement
+ *
+ * ```ts
+ * function withPlacement(options: {
+ *     placement: ModalPlacementOption;
+ *     $boundary: () => Rect;
+ *     $anchorMeasurement: () => Rect;
+ *     $floatingMeasurement: () => Rect;
+ * }): Memo<ModalPlacement>;
+ *
+ * type ModalPlacementOption =
+ *     | "vertical-center"
+ *     | "vertical-left"
+ *     | "vertical-right"
+ *     | "horizontal-center"
+ *     | "horizontal-up"
+ *     | "horizontal-down"
+ *     | "up-center"
+ *     | "down-center"
+ *     | "left-down"
+ *     | "right-down";
+ *
+ * type ModalPlacement =
+ *     | "down-center"
+ *     | "down-left"
+ *     | "down-right"
+ *     | "left-center"
+ *     | "left-down"
+ *     | "left-up"
+ *     | "right-center"
+ *     | "right-down"
+ *     | "right-up"
+ *     | "up-center"
+ *     | "up-left"
+ *     | "up-right";
+ * ```
+ *
+ * Takes a `ModalPlacementOption` and resolves it to `ModalPlacement`, picking whichever side has more space. This function must be called inside a `createModal` callback.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import {
+ *     createModal,
+ *     withModalStatus,
+ *     withAnchorElement,
+ *     withAnchorMeasurement,
+ *     withFloatingElement,
+ *     withFloatingMeasurement,
+ *     withBoundary,
+ *     withPlacement,
+ * } from "@monstermann/signals-modal";
+ *
+ * createModal("key", () => {
+ *     const { $status } = withModalStatus();
+ *     const $anchorElement = withAnchorElement();
+ *     const $floatingElement = withFloatingElement();
+ *     const $anchorMeasurement = withAnchorMeasurement({
+ *         $status,
+ *         $anchorElement,
+ *     });
+ *     const $floatingMeasurement = withFloatingMeasurement({
+ *         $status,
+ *         $floatingElement,
+ *     });
+ *     const $boundary = withBoundary({ $status });
+ *     const $placement = withPlacement({
+ *         placement: "vertical-center",
+ *         $boundary,
+ *         $anchorMeasurement,
+ *         $floatingMeasurement,
+ *     });
+ * });
+ * ```
+ *
+ */
 declare function withPlacement(options: {
   placement: ModalPlacementOption;
   $anchorMeasurement: () => Rect;

package/dist/position/withPlacement.mjs

@@ -7,7 +7,7 @@ import { height } from "@monstermann/geometry/Rect/height.mjs";
 //#region src/position/withPlacement.ts
 const meta = {
 	path: "@signals-modal/position/withPlacement.ts",
-	line: 97,
+	line: 174,
 	name: "withPlacement.$placement"
 };
 const placementResolvers = {
@@ -40,6 +40,83 @@ const placementResolvers = {
 		return height(getBoundaryDown(o.boundary, o.anchor)) >= height(up) ? "down-right" : "up-right";
 	}
 };
+/**
+* # withPlacement
+*
+* ```ts
+* function withPlacement(options: {
+*     placement: ModalPlacementOption;
+*     $boundary: () => Rect;
+*     $anchorMeasurement: () => Rect;
+*     $floatingMeasurement: () => Rect;
+* }): Memo<ModalPlacement>;
+*
+* type ModalPlacementOption =
+*     | "vertical-center"
+*     | "vertical-left"
+*     | "vertical-right"
+*     | "horizontal-center"
+*     | "horizontal-up"
+*     | "horizontal-down"
+*     | "up-center"
+*     | "down-center"
+*     | "left-down"
+*     | "right-down";
+*
+* type ModalPlacement =
+*     | "down-center"
+*     | "down-left"
+*     | "down-right"
+*     | "left-center"
+*     | "left-down"
+*     | "left-up"
+*     | "right-center"
+*     | "right-down"
+*     | "right-up"
+*     | "up-center"
+*     | "up-left"
+*     | "up-right";
+* ```
+*
+* Takes a `ModalPlacementOption` and resolves it to `ModalPlacement`, picking whichever side has more space. This function must be called inside a `createModal` callback.
+*
+* ## Example
+*
+* ```ts
+* import {
+*     createModal,
+*     withModalStatus,
+*     withAnchorElement,
+*     withAnchorMeasurement,
+*     withFloatingElement,
+*     withFloatingMeasurement,
+*     withBoundary,
+*     withPlacement,
+* } from "@monstermann/signals-modal";
+*
+* createModal("key", () => {
+*     const { $status } = withModalStatus();
+*     const $anchorElement = withAnchorElement();
+*     const $floatingElement = withFloatingElement();
+*     const $anchorMeasurement = withAnchorMeasurement({
+*         $status,
+*         $anchorElement,
+*     });
+*     const $floatingMeasurement = withFloatingMeasurement({
+*         $status,
+*         $floatingElement,
+*     });
+*     const $boundary = withBoundary({ $status });
+*     const $placement = withPlacement({
+*         placement: "vertical-center",
+*         $boundary,
+*         $anchorMeasurement,
+*         $floatingMeasurement,
+*     });
+* });
+* ```
+*
+*/
 function withPlacement(options) {
 	const modal = currentModal();
 	const $placement = memo(() => {

package/dist/position/withPosition.d.mts

@@ -1,6 +1,6 @@
 import { ModalPlacement } from "./withPlacement.mjs";
 import { Memo } from "@monstermann/signals";
-import { Rect } from "@monstermann/fn";
+import { Rect } from "@monstermann/geometry";
 
 //#region src/position/withPosition.d.ts
 interface ModalPosition {
@@ -11,6 +11,72 @@ interface ModalPosition {
   originX: number;
   originY: number;
 }
+/**
+ * # withPosition
+ *
+ * ```ts
+ * function withPosition(options: {
+ *     $boundary: () => Rect;
+ *     $placement: () => ModalPlacement;
+ *     $anchorMeasurement: () => Rect;
+ *     $floatingMeasurement: () => Rect;
+ *     transform?: (rect: Rect) => Rect;
+ * }): Memo<{
+ *     floatingX: number;
+ *     floatingY: number;
+ *     maxHeight: number;
+ *     maxWidth: number;
+ *     originX: number;
+ *     originY: number;
+ * }>;
+ * ```
+ *
+ * Consumes a range of measurements and calculates the final position for the floating element. This function must be called inside a `createModal` callback.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import {
+ *     createModal,
+ *     withModalStatus,
+ *     withAnchorElement,
+ *     withAnchorMeasurement,
+ *     withFloatingElement,
+ *     withFloatingMeasurement,
+ *     withBoundary,
+ *     withPlacement,
+ *     withPosition,
+ * } from "@monstermann/signals-modal";
+ *
+ * createModal("key", () => {
+ *     const { $status } = withModalStatus();
+ *     const $anchorElement = withAnchorElement();
+ *     const $floatingElement = withFloatingElement();
+ *     const $anchorMeasurement = withAnchorMeasurement({
+ *         $status,
+ *         $anchorElement,
+ *     });
+ *     const $floatingMeasurement = withFloatingMeasurement({
+ *         $status,
+ *         $floatingElement,
+ *     });
+ *     const $boundary = withBoundary({ $status });
+ *     const $placement = withPlacement({
+ *         placement: "vertical-center",
+ *         $boundary,
+ *         $anchorMeasurement,
+ *         $floatingMeasurement,
+ *     });
+ *     const $position = withPosition({
+ *         $boundary,
+ *         $placement,
+ *         $anchorMeasurement,
+ *         $floatingMeasurement,
+ *     });
+ * });
+ * ```
+ *
+ */
 declare function withPosition(options: {
   $anchorMeasurement: () => Rect;
   $boundary: () => Rect;

package/dist/position/withPosition.mjs

@@ -7,7 +7,7 @@ import { left } from "@monstermann/geometry/Rect/left.mjs";
 import { right } from "@monstermann/geometry/Rect/right.mjs";
 import { width } from "@monstermann/geometry/Rect/width.mjs";
 import { height } from "@monstermann/geometry/Rect/height.mjs";
-import { pipe } from "@monstermann/fn";
+import { pipe } from "@monstermann/dfdl";
 import { alignCenterX } from "@monstermann/geometry/Rect/alignCenterX.mjs";
 import { snapBelow } from "@monstermann/geometry/Rect/snapBelow.mjs";
 import { clamp } from "@monstermann/geometry/Rect/clamp.mjs";
@@ -26,7 +26,7 @@ import { snapAbove } from "@monstermann/geometry/Rect/snapAbove.mjs";
 //#region src/position/withPosition.ts
 const meta = {
 	path: "@signals-modal/position/withPosition.ts",
-	line: 313,
+	line: 378,
 	name: "withPosition.$position"
 };
 const positionResolvers = {
@@ -195,6 +195,72 @@ const positionResolvers = {
 		};
 	}
 };
+/**
+* # withPosition
+*
+* ```ts
+* function withPosition(options: {
+*     $boundary: () => Rect;
+*     $placement: () => ModalPlacement;
+*     $anchorMeasurement: () => Rect;
+*     $floatingMeasurement: () => Rect;
+*     transform?: (rect: Rect) => Rect;
+* }): Memo<{
+*     floatingX: number;
+*     floatingY: number;
+*     maxHeight: number;
+*     maxWidth: number;
+*     originX: number;
+*     originY: number;
+* }>;
+* ```
+*
+* Consumes a range of measurements and calculates the final position for the floating element. This function must be called inside a `createModal` callback.
+*
+* ## Example
+*
+* ```ts
+* import {
+*     createModal,
+*     withModalStatus,
+*     withAnchorElement,
+*     withAnchorMeasurement,
+*     withFloatingElement,
+*     withFloatingMeasurement,
+*     withBoundary,
+*     withPlacement,
+*     withPosition,
+* } from "@monstermann/signals-modal";
+*
+* createModal("key", () => {
+*     const { $status } = withModalStatus();
+*     const $anchorElement = withAnchorElement();
+*     const $floatingElement = withFloatingElement();
+*     const $anchorMeasurement = withAnchorMeasurement({
+*         $status,
+*         $anchorElement,
+*     });
+*     const $floatingMeasurement = withFloatingMeasurement({
+*         $status,
+*         $floatingElement,
+*     });
+*     const $boundary = withBoundary({ $status });
+*     const $placement = withPlacement({
+*         placement: "vertical-center",
+*         $boundary,
+*         $anchorMeasurement,
+*         $floatingMeasurement,
+*     });
+*     const $position = withPosition({
+*         $boundary,
+*         $placement,
+*         $anchorMeasurement,
+*         $floatingMeasurement,
+*     });
+* });
+* ```
+*
+*/
 function withPosition(options) {
 	const modal = currentModal();
 	const $position = memo(() => {

package/dist/scroll/withCloseOnScroll.d.mts

@@ -2,6 +2,43 @@ import { ModalStatus } from "../status/types.mjs";
 import { Reactive } from "@monstermann/signals";
 
 //#region src/scroll/withCloseOnScroll.d.ts
+
+/**
+ * # withCloseOnScroll
+ *
+ * ```ts
+ * function withCloseOnScroll(options: {
+ *     $anchorElement: Reactive<HTMLElement | null>;
+ *     $status: Reactive<ModalStatus>;
+ * }): void;
+ * ```
+ *
+ * Automatically closes the modal when any scrollable ancestor of the anchor element is scrolled. This function must be called inside a `createModal` callback.
+ *
+ * The function listens for scroll events on all scrollable parent elements of the anchor element and triggers a close when scrolling occurs. Scroll listeners are only active when the modal is opening or opened (not when closing or closed).
+ *
+ * ## Example
+ *
+ * ```ts
+ * import {
+ *     createModal,
+ *     withModalStatus,
+ *     withAnchorElement,
+ *     withCloseOnScroll,
+ * } from "@monstermann/signals-modal";
+ *
+ * createModal("key", () => {
+ *     const { $status } = withModalStatus();
+ *     const $anchorElement = withAnchorElement();
+ *
+ *     withCloseOnScroll({
+ *         $status,
+ *         $anchorElement,
+ *     });
+ * });
+ * ```
+ *
+ */
 declare function withCloseOnScroll(options: {
   $anchorElement: Reactive<HTMLElement | null>;
   $status: Reactive<ModalStatus>;

package/dist/scroll/withCloseOnScroll.mjs

@@ -5,9 +5,45 @@ import { INTERNAL, effect } from "@monstermann/signals";
 //#region src/scroll/withCloseOnScroll.ts
 const meta = {
 	path: "@signals-modal/scroll/withCloseOnScroll.ts",
-	line: 13,
+	line: 49,
 	name: "withCloseOnScroll"
 };
+/**
+* # withCloseOnScroll
+*
+* ```ts
+* function withCloseOnScroll(options: {
+*     $anchorElement: Reactive<HTMLElement | null>;
+*     $status: Reactive<ModalStatus>;
+* }): void;
+* ```
+*
+* Automatically closes the modal when any scrollable ancestor of the anchor element is scrolled. This function must be called inside a `createModal` callback.
+*
+* The function listens for scroll events on all scrollable parent elements of the anchor element and triggers a close when scrolling occurs. Scroll listeners are only active when the modal is opening or opened (not when closing or closed).
+*
+* ## Example
+*
+* ```ts
+* import {
+*     createModal,
+*     withModalStatus,
+*     withAnchorElement,
+*     withCloseOnScroll,
+* } from "@monstermann/signals-modal";
+*
+* createModal("key", () => {
+*     const { $status } = withModalStatus();
+*     const $anchorElement = withAnchorElement();
+*
+*     withCloseOnScroll({
+*         $status,
+*         $anchorElement,
+*     });
+* });
+* ```
+*
+*/
 function withCloseOnScroll(options) {
 	const modal = currentModal();
 	const onScroll = () => closeModal(modal.key);

package/dist/status/closeAllModals.d.mts

@@ -1,4 +1,37 @@
 //#region src/status/closeAllModals.d.ts
+/**
+ * # closeAllModals
+ *
+ * ```ts
+ * function closeAllModals(): void;
+ * ```
+ *
+ * Closes all modals by setting their status to `"closing"`. Skips modals that are already `"closing"` or `"closed"`.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import {
+ *     createModal,
+ *     withModalStatus,
+ *     openModal,
+ *     closeAllModals,
+ * } from "@monstermann/signals-modal";
+ *
+ * createModal("modal1", () => {
+ *     withModalStatus();
+ * });
+ *
+ * createModal("modal2", () => {
+ *     withModalStatus();
+ * });
+ *
+ * openModal("modal1");
+ * openModal("modal2");
+ * closeAllModals();
+ * ```
+ *
+ */
 declare function closeAllModals(): void;
 //#endregion
 export { closeAllModals };

package/dist/status/closeAllModals.mjs

@@ -2,6 +2,39 @@ import { $keysToStatus } from "./internals.mjs";
 import { untrack } from "@monstermann/signals";
 
 //#region src/status/closeAllModals.ts
+/**
+* # closeAllModals
+*
+* ```ts
+* function closeAllModals(): void;
+* ```
+*
+* Closes all modals by setting their status to `"closing"`. Skips modals that are already `"closing"` or `"closed"`.
+*
+* ## Example
+*
+* ```ts
+* import {
+*     createModal,
+*     withModalStatus,
+*     openModal,
+*     closeAllModals,
+* } from "@monstermann/signals-modal";
+*
+* createModal("modal1", () => {
+*     withModalStatus();
+* });
+*
+* createModal("modal2", () => {
+*     withModalStatus();
+* });
+*
+* openModal("modal1");
+* openModal("modal2");
+* closeAllModals();
+* ```
+*
+*/
 function closeAllModals() {
 	untrack(() => {
 		for (const $status of $keysToStatus().values()) {

package/dist/status/closeLastModal.d.mts

@@ -1,4 +1,22 @@
 //#region src/status/closeLastModal.d.ts
+/**
+ * # closeLastModal
+ *
+ * ```ts
+ * function closeLastModal(): void;
+ * ```
+ *
+ * Closes the last opened modal by setting its status to `"closing"`.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import { closeLastModal } from "@monstermann/signals-modal";
+ *
+ * closeLastModal();
+ * ```
+ *
+ */
 declare function closeLastModal(): void;
 //#endregion
 export { closeLastModal };

package/dist/status/closeLastModal.mjs

@@ -2,6 +2,24 @@ import { $openedModals } from "./internals.mjs";
 import { closeModal } from "./closeModal.mjs";
 
 //#region src/status/closeLastModal.ts
+/**
+* # closeLastModal
+*
+* ```ts
+* function closeLastModal(): void;
+* ```
+*
+* Closes the last opened modal by setting its status to `"closing"`.
+*
+* ## Example
+*
+* ```ts
+* import { closeLastModal } from "@monstermann/signals-modal";
+*
+* closeLastModal();
+* ```
+*
+*/
 function closeLastModal() {
 	const key = Array.from($openedModals()).at(-1);
 	if (key) closeModal(key);

package/dist/status/closeModal.d.mts

@@ -1,4 +1,32 @@
 //#region src/status/closeModal.d.ts
+/**
+ * # closeModal
+ *
+ * ```ts
+ * function closeModal(key: string): void;
+ * ```
+ *
+ * Closes a modal by setting its status to `"closing"`. Does nothing if the modal is already `"closing"` or `"closed"`, or if the modal doesn't exist.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import {
+ *     createModal,
+ *     withModalStatus,
+ *     openModal,
+ *     closeModal,
+ * } from "@monstermann/signals-modal";
+ *
+ * createModal("key", () => {
+ *     withModalStatus();
+ * });
+ *
+ * openModal("key");
+ * closeModal("key");
+ * ```
+ *
+ */
 declare function closeModal(key: string): void;
 //#endregion
 export { closeModal };

package/dist/status/closeModal.mjs

@@ -2,6 +2,34 @@ import { $keysToStatus } from "./internals.mjs";
 import { untrack } from "@monstermann/signals";
 
 //#region src/status/closeModal.ts
+/**
+* # closeModal
+*
+* ```ts
+* function closeModal(key: string): void;
+* ```
+*
+* Closes a modal by setting its status to `"closing"`. Does nothing if the modal is already `"closing"` or `"closed"`, or if the modal doesn't exist.
+*
+* ## Example
+*
+* ```ts
+* import {
+*     createModal,
+*     withModalStatus,
+*     openModal,
+*     closeModal,
+* } from "@monstermann/signals-modal";
+*
+* createModal("key", () => {
+*     withModalStatus();
+* });
+*
+* openModal("key");
+* closeModal("key");
+* ```
+*
+*/
 function closeModal(key) {
 	untrack(() => {
 		const $status = $keysToStatus().get(key);