@entry-ui/qwik 0.4.0 → 0.6.0

package/lib/hooks/use-counter/use-counter.types.d.ts

@@ -0,0 +1,73 @@
+import type { ReadonlySignal, QRL } from '@qwik.dev/core';
+/**
+ * Configuration parameters for the `useCounter` hook.
+ */
+export interface UseCounterParams {
+    /**
+     * The starting value of the counter.
+     * Must be a finite number. It will be automatically clamped if it
+     * falls outside the specified `min` and `max` range.
+     *
+     * @default 0
+     */
+    initialCount?: number;
+    /**
+     * The amount by which the counter increases or decreases during
+     * increment and decrement operations. Must be a finite number.
+     *
+     * @default 1
+     */
+    step?: number;
+    /**
+     * The lower numerical boundary of the counter.
+     * The counter value will never go below this limit.
+     * Must be less than or equal to `max`.
+     *
+     * @default -Number.MAX_VALUE
+     */
+    min?: number;
+    /**
+     * The upper numerical boundary of the counter.
+     * The counter value will never exceed this limit.
+     * Must be greater than or equal to `min`.
+     *
+     * @default Number.MAX_VALUE
+     */
+    max?: number;
+}
+/**
+ * Represents the object returned by the `useCounter` hook.
+ */
+export interface UseCounterReturnValue {
+    /**
+     * A readonly signal representing the current numeric state of the counter.
+     * This signal is read-only, meaning its value can only be modified by calling
+     * specific `QRL` functions like `increment$`, `decrement$`, `set$`,
+     * or `reset$`, ensuring consistent and predictable state updates.
+     */
+    count: ReadonlySignal<number>;
+    /**
+     * A `QRL` function that increases the counter value by the defined `step`.
+     * The resulting value is automatically clamped between `min` and `max`.
+     * Includes validation to ensure the operation results in a finite number.
+     */
+    increment$: QRL<() => void>;
+    /**
+     * A `QRL` function that decreases the counter value by the defined `step`.
+     * The resulting value is automatically clamped between `min` and `max`.
+     * Includes validation to ensure the operation results in a finite number.
+     */
+    decrement$: QRL<() => void>;
+    /**
+     * A `QRL` function that directly sets the counter to a specific numeric value.
+     * This function includes built-in validation; the value will only be updated if it
+     * is a finite number, and it will be clamped between `min` and `max`.
+     */
+    set$: QRL<(value: number) => void>;
+    /**
+     * A `QRL` function that restores the counter to its defined `initialCount`.
+     * The `initialCount` value is re-clamped during this operation to ensure
+     * it still adheres to the current `min` and `max` constraints.
+     */
+    reset$: QRL<() => void>;
+}

package/lib/hooks/use-lifecycle/index.d.ts

@@ -0,0 +1,2 @@
+export type { UseLifecycleParams } from './use-lifecycle.types';
+export { useLifecycle } from './use-lifecycle';

package/lib/hooks/use-lifecycle/index.qwik.mjs

@@ -0,0 +1,4 @@
+import { useLifecycle } from "./use-lifecycle.qwik.mjs";
+export {
+  useLifecycle
+};

package/lib/hooks/use-lifecycle/use-lifecycle.d.ts

@@ -0,0 +1,21 @@
+import type { UseLifecycleParams } from './use-lifecycle.types';
+/**
+ * A hook that manages component lifecycle events with reliable server-to-browser continuity.
+ *
+ * This hook addresses a fundamental limitation in Qwik's standard `useTask$`: the fact that
+ * server-defined cleanup functions are not transferred to the client. Unlike `useVisibleTask$`,
+ * which forces eager execution and impacts performance, `useLifecycle` leverages a
+ * global `MutationObserver` and the `qresume` event to ensure cleanup logic is
+ * consistently executed when an element is removed from the DOM.
+ *
+ * Lifecycle synchronization is handled via:
+ * - **Mounting**: Executes `onMount$` during the initial task run (server or client).
+ * - **Unmounting**: Automatically registers the element for tracking upon resumption
+ * or client-side mounting, ensuring `onUnmount$` runs even if the component was SSR-ed.
+ *
+ * @remarks
+ * This hook was inspired by and contains logic adapted from the `useMountTask$` implementation
+ * in the **Qwik Design System (QDS)**.
+ * @see {@link https://github.com/kunai-consulting/qwik-design-system/blob/v2-migration/libs/base/src/hooks/use-unmount.tsx QDS use-unmount implementation}
+ */
+export declare const useLifecycle: (params: UseLifecycleParams) => void;

package/lib/hooks/use-lifecycle/use-lifecycle.qwik.mjs

@@ -0,0 +1,59 @@
+import { useTask$, useOnDocument, $ } from "@qwik.dev/core";
+import { isDev, isBrowser } from "@qwik.dev/core/build";
+import { error } from "../../_internal/utilities/error/error.qwik.mjs";
+import { createGlobalUnmountObserver } from "./utilities/create-global-unmount-observer/create-global-unmount-observer.qwik.mjs";
+const globalUnmountObserver = createGlobalUnmountObserver();
+const useLifecycle = (params) => {
+  const { element, onMount$, onUnmount$ } = params;
+  useTask$(async ({ cleanup }) => {
+    if (onMount$) {
+      try {
+        await Promise.resolve(onMount$());
+      } catch (err) {
+        if (isDev) {
+          error([
+            `An error occurred during the 'onMount$' lifecycle execution in 'useLifecycle' hook.`,
+            `The mount task failed.`,
+            `Check your 'onMount$' logic: ${err instanceof Error ? err.message : String(err)}`
+          ]);
+        }
+      }
+    }
+    cleanup(async () => {
+      if (isBrowser && onUnmount$) {
+        const elementRef = element.value;
+        if (elementRef) {
+          globalUnmountObserver.remove({
+            element: elementRef,
+            qrl: onUnmount$
+          });
+        }
+        try {
+          await Promise.resolve(onUnmount$());
+        } catch (err) {
+          if (isDev) {
+            error([
+              `An error occurred during the 'onUnmount$' lifecycle execution in 'useLifecycle'.`,
+              `The cleanup task failed.`,
+              `Check your 'onUnmount$' logic: ${err instanceof Error ? err.message : String(err)}`
+            ]);
+          }
+        }
+      }
+    });
+  });
+  useOnDocument("qresume", $(() => {
+    if (onUnmount$) {
+      const elementRef = element.value;
+      if (elementRef) {
+        globalUnmountObserver.add({
+          element: elementRef,
+          qrl: onUnmount$
+        });
+      }
+    }
+  }));
+};
+export {
+  useLifecycle
+};

package/lib/hooks/use-lifecycle/use-lifecycle.types.d.ts

@@ -0,0 +1,33 @@
+import type { SignalOrReadonlySignal } from '@/types';
+import type { QRL } from '@qwik.dev/core';
+/**
+ * Configuration parameters for the `useLifecycle` hook.
+ */
+export interface UseLifecycleParams {
+    /**
+     * A signal containing the reference to the target element.
+     * This reference is essential for the global unmount observer to track the
+     * element's presence in the DOM. It ensures that the unmount logic is
+     * correctly associated with the specific node, enabling reliable detection
+     * of its removal even across the server-to-browser boundary.
+     */
+    element: SignalOrReadonlySignal<HTMLElement | undefined | null>;
+    /**
+     * A `QRL` function executed when the component is first initialized or mounted.
+     * Unlike standard effects, this callback is designed to run within the `useTask$`
+     * scope, allowing for consistent initialization logic across both server and client
+     * environments.
+     *
+     * @default undefined
+     */
+    onMount$?: QRL<() => void> | QRL<() => Promise<void>>;
+    /**
+     * A `QRL` function executed when the element is removed from the DOM.
+     * This callback is the primary solution for the "lost cleanup" problem in Qwik.
+     * It is reliably triggered by a `MutationObserver` when the associated `element`
+     * leaves the document tree.
+     *
+     * @default undefined
+     */
+    onUnmount$?: QRL<() => void> | QRL<() => Promise<void>>;
+}

package/lib/hooks/use-lifecycle/utilities/create-global-unmount-observer/create-global-unmount-observer.d.ts

@@ -0,0 +1,13 @@
+import type { CreateGlobalUnmountObserverReturnValue } from './create-global-unmount-observer.types';
+/**
+ * A utility that creates a centralized observer to manage element unmounting across the application.
+ *
+ * This factory function returns an object with methods to track HTMLElements and execute
+ * associated cleanup QRLs when those elements are removed from the DOM. It solves
+ * the "ghost element" problem in Qwik by using a single `MutationObserver` instance,
+ * which is lazily initialized and automatically disconnected when no elements are
+ * being tracked, ensuring optimal memory management and performance.
+ * The observer uses a `WeakMap` internally to prevent memory leaks, allowing the
+ * garbage collector to reclaim elements even if they are still registered in the observer.
+ */
+export declare const createGlobalUnmountObserver: () => CreateGlobalUnmountObserverReturnValue;

package/lib/hooks/use-lifecycle/utilities/create-global-unmount-observer/create-global-unmount-observer.qwik.mjs

@@ -0,0 +1,91 @@
+import { isDev } from "@qwik.dev/core/build";
+import { error } from "../../../../_internal/utilities/error/error.qwik.mjs";
+const createGlobalUnmountObserver = () => {
+  let isInitialized = false;
+  let mutationObserver = void 0;
+  const qrlMap = /* @__PURE__ */ new WeakMap();
+  const elements = /* @__PURE__ */ new Set();
+  const processRemovedElements = () => {
+    const toRemove = [];
+    for (const element of elements) {
+      if (!document.contains(element)) {
+        toRemove.push(element);
+      }
+    }
+    for (const element of toRemove) {
+      const qrls = qrlMap.get(element);
+      if (qrls) {
+        const promises = [];
+        for (const qrl of qrls) {
+          const result = qrl();
+          if (result instanceof Promise) {
+            promises.push(result);
+          }
+        }
+        if (promises.length > 0) {
+          Promise.all(promises).catch((err) => {
+            if (isDev) {
+              error([
+                `An error occurred during the 'onUnmount$' lifecycle execution in 'useLifecycle' hook.`,
+                `Check the cleanup logic in your 'onUnmount$' QRL. `,
+                `One or more promises rejected during the element removal process: ${err instanceof Error ? err.message : String(err)}`
+              ]);
+            }
+          });
+        }
+        qrls.clear();
+      }
+      qrlMap.delete(element);
+      elements.delete(element);
+    }
+  };
+  const cleanupObserver = () => {
+    if (mutationObserver && elements.size === 0) {
+      mutationObserver.disconnect();
+      mutationObserver = void 0;
+      isInitialized = false;
+    }
+  };
+  const initMutationObserver = () => {
+    if (isInitialized || typeof MutationObserver === "undefined") return;
+    isInitialized = true;
+    mutationObserver = new MutationObserver(() => {
+      processRemovedElements();
+      cleanupObserver();
+    });
+    mutationObserver.observe(document.body, {
+      childList: true,
+      subtree: true
+    });
+  };
+  const add = (params) => {
+    const { element, qrl } = params;
+    if (!qrlMap.has(element)) {
+      qrlMap.set(element, /* @__PURE__ */ new Set());
+    }
+    const qrls = qrlMap.get(element);
+    qrls.add(qrl);
+    elements.add(element);
+    if (!isInitialized) {
+      processRemovedElements();
+    }
+    initMutationObserver();
+  };
+  const remove = (params) => {
+    const { element, qrl } = params;
+    const qrls = qrlMap.get(element);
+    if (!qrls) return;
+    qrls.delete(qrl);
+    if (qrls.size === 0) {
+      elements.delete(element);
+      cleanupObserver();
+    }
+  };
+  return {
+    add,
+    remove
+  };
+};
+export {
+  createGlobalUnmountObserver
+};

package/lib/hooks/use-lifecycle/utilities/create-global-unmount-observer/create-global-unmount-observer.types.d.ts

@@ -0,0 +1,26 @@
+import type { QRL } from '@qwik.dev/core';
+/**
+ * Represents the object returned by the `createGlobalUnmountObserver` utility.
+ */
+export interface CreateGlobalUnmountObserverReturnValue {
+    /**
+     * Registers an element and its cleanup logic to be monitored.
+     * If the `MutationObserver` is not yet active, it will be initialized.
+     * If the element is already being tracked, the new `QRL` will be added
+     * to the existing set of cleanup tasks for that element.
+     */
+    add: (params: {
+        element: HTMLElement;
+        qrl: QRL<() => void> | QRL<() => Promise<void>>;
+    }) => void;
+    /**
+     * Unregisters a specific cleanup QRL from an element.
+     * If no more `QRL`s are associated with the element, the element is removed
+     * from tracking. If no elements are left in the tracking set, the
+     * `MutationObserver` is disconnected to free up system resources.
+     */
+    remove: (params: {
+        element: HTMLElement;
+        qrl: QRL<() => void> | QRL<() => Promise<void>>;
+    }) => void;
+}

package/lib/hooks/use-lifecycle/utilities/create-global-unmount-observer/index.d.ts

@@ -0,0 +1,2 @@
+export type { CreateGlobalUnmountObserverReturnValue } from './create-global-unmount-observer.types';
+export { createGlobalUnmountObserver } from './create-global-unmount-observer';

package/lib/hooks/use-lifecycle/utilities/index.d.ts

@@ -0,0 +1 @@
+export * from './create-global-unmount-observer';

package/lib/index.d.ts

@@ -1,3 +1,4 @@
 export * from './components';
 export * from './hooks';
+export * from './types';
 export * from './utilities';

package/lib/index.qwik.mjs

@@ -1,16 +1,32 @@
 import * as index from "./components/alert/parts/index.qwik.mjs";
-import * as index$1 from "./components/separator/parts/index.qwik.mjs";
+import * as index$1 from "./components/collapsible/parts/index.qwik.mjs";
+import { useCollapsibleRootContext } from "./components/collapsible/hooks/use-collapsible-root-context/use-collapsible-root-context.qwik.mjs";
+import { useCollapsibleTriggerContext } from "./components/collapsible/hooks/use-collapsible-trigger-context/use-collapsible-trigger-context.qwik.mjs";
+import * as index$2 from "./components/separator/parts/index.qwik.mjs";
+import * as index$3 from "./components/toggle/parts/index.qwik.mjs";
+import { useToggleRootContext } from "./components/toggle/hooks/use-toggle-root-context/use-toggle-root-context.qwik.mjs";
 import { useBoolean } from "./hooks/use-boolean/use-boolean.qwik.mjs";
 import { useControllable } from "./hooks/use-controllable/use-controllable.qwik.mjs";
+import { useCounter } from "./hooks/use-counter/use-counter.qwik.mjs";
 import { useCycle } from "./hooks/use-cycle/use-cycle.qwik.mjs";
+import { useLifecycle } from "./hooks/use-lifecycle/use-lifecycle.qwik.mjs";
+import { makeEventPreventable } from "./utilities/make-event-preventable/make-event-preventable.qwik.mjs";
 import { mergeRefs } from "./utilities/merge-refs/merge-refs.qwik.mjs";
 import { mergeStyles } from "./utilities/merge-styles/merge-styles.qwik.mjs";
 export {
   index as Alert,
-  index$1 as Separator,
+  index$1 as Collapsible,
+  index$2 as Separator,
+  index$3 as Toggle,
+  makeEventPreventable,
   mergeRefs,
   mergeStyles,
   useBoolean,
+  useCollapsibleRootContext,
+  useCollapsibleTriggerContext,
   useControllable,
-  useCycle
+  useCounter,
+  useCycle,
+  useLifecycle,
+  useToggleRootContext
 };

package/lib/types/entry-ui-qwik-event/entry-ui-qwik-event.types.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Represents a Qwik event augmented with Entry UI Qwik's custom prevention logic.
+ *
+ * This type extends the standard DOM event with additional methods and properties
+ * that allow for granular control over internal component handlers within the
+ * Entry UI Qwik library.
+ */
+export type EntryUIQwikEvent<EV extends Event> = EV & {
+    /**
+     * Prevents the internal Entry UI Qwik handler from executing for this event.
+     * When called, this method sets the `entryUIQwikHandlerPrevented` flag to `true`.
+     * Use this when you want to handle the event manually in a consumer-provided
+     * handler and prevent the component's default state updates or logic from firing.
+     */
+    preventEntryUIQwikHandler: () => void;
+    /**
+     * Indicates whether the internal Entry UI Qwik logic has been prevented for this event.
+     * This property is read-only and is typically checked by internal component
+     * handlers to determine if they should skip their default execution logic.
+     */
+    readonly entryUIQwikHandlerPrevented?: boolean;
+};

package/lib/types/entry-ui-qwik-event/index.d.ts

@@ -0,0 +1 @@
+export type { EntryUIQwikEvent } from './entry-ui-qwik-event.types';

package/lib/types/entry-ui-qwik-event-state/entry-ui-qwik-event-state.types.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Represents the state of a Qwik event within the Entry UI Qwik system.
+ *
+ * This type is a specialized version of the event object that includes only the
+ * state flag. It is typically used in internal component handlers to check
+ * if a previous handler in the execution chain has requested to prevent
+ * the default Entry UI Qwik logic.
+ */
+export type EntryUIQwikEventState<EV extends Event> = EV & {
+    /**
+     * Indicates whether the internal Entry UI Qwik logic has been prevented for this event.
+     * When `true`, it signals that a consumer or a preceding handler has invoked
+     * the prevention mechanism, and the current handler should likely skip
+     * its default state updates or behaviors.
+     */
+    readonly entryUIQwikHandlerPrevented?: boolean;
+};

package/lib/types/entry-ui-qwik-event-state/index.d.ts

@@ -0,0 +1 @@
+export type { EntryUIQwikEventState } from './entry-ui-qwik-event-state.types';

package/lib/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from './entry-ui-qwik-event';
+export * from './entry-ui-qwik-event-state';
+export * from './signal-or-readonly-signal';

package/lib/types/signal-or-readonly-signal/index.d.ts

@@ -0,0 +1 @@
+export type { SignalOrReadonlySignal } from './signal-or-readonly-signal.types';

package/lib/types/signal-or-readonly-signal/signal-or-readonly-signal.types.d.ts

@@ -0,0 +1,12 @@
+import type { Signal, ReadonlySignal } from '@qwik.dev/core';
+/**
+ * Represents a signal that can be either mutable or readonly.
+ *
+ * This type is useful for component props or utilities that need to read from a signal
+ * without concerned whether it was created as a standard `Signal` (mutable) or
+ * a `ReadonlySignal` (typically derived from `useComputed$`). It supports:
+ *
+ * - `Signal<T>`: A standard, mutable Qwik signal.
+ * - `ReadonlySignal<T>`: A readonly signal, such as those returned by `useComputed$`.
+ */
+export type SignalOrReadonlySignal<T> = Signal<T> | ReadonlySignal<T>;

package/lib/utilities/index.d.ts

@@ -1,2 +1,3 @@
+export * from './make-event-preventable';
 export * from './merge-refs';
 export * from './merge-styles';

package/lib/utilities/make-event-preventable/index.d.ts

@@ -0,0 +1 @@
+export { makeEventPreventable } from './make-event-preventable';

package/lib/utilities/make-event-preventable/index.qwik.mjs

@@ -0,0 +1,4 @@
+import { makeEventPreventable } from "./make-event-preventable.qwik.mjs";
+export {
+  makeEventPreventable
+};

package/lib/utilities/make-event-preventable/make-event-preventable.d.ts

@@ -0,0 +1,20 @@
+import type { EntryUIQwikEvent } from '@/types';
+/**
+ * Augments a standard event with internal handler prevention capabilities.
+ *
+ * This utility function transforms a standard event object into an `EntryUIQwikEvent`.
+ * It adds a `preventEntryUIQwikHandler` method, allowing developers to flag
+ * an event during its execution. This flag can then be checked by subsequent
+ * handlers in any Qwik event chain (such as `onClick$`, `onKeyDown$`, or `onInput$`)
+ * to determine if the internal component logic should be bypassed.
+ *
+ * It is particularly useful when a consumer needs to intercept an event and
+ * conditionally prevent the component's default behavior or state updates
+ * (like toggling a state or closing a dialog) without necessarily stopping
+ * native event propagation or other DOM-level behaviors.
+ *
+ * When `preventEntryUIQwikHandler()` is called:
+ * - The internal property `entryUIQwikHandlerPrevented` is set to `true`.
+ * - Subsequent handlers in the event array can verify this flag to skip their logic.
+ */
+export declare const makeEventPreventable: <EV extends Event>(event: EV) => EntryUIQwikEvent<EV>;

package/lib/utilities/make-event-preventable/make-event-preventable.qwik.mjs

@@ -0,0 +1,10 @@
+const makeEventPreventable = (event) => {
+  const entryUIQwikEvent = event;
+  entryUIQwikEvent.preventEntryUIQwikHandler = () => {
+    entryUIQwikEvent.entryUIQwikHandlerPrevented = true;
+  };
+  return entryUIQwikEvent;
+};
+export {
+  makeEventPreventable
+};

package/lib/utilities/merge-styles/merge-styles.types.d.ts

@@ -6,7 +6,7 @@ import type { CSSProperties } from '@qwik.dev/core';
  *
  * - `string`: Standard inline CSS strings (e.g., `"color: red; padding: 10px"`).
  *
- * - `CSSProperties`: A structured object of CSS declarations (e.g., `{ color: 'red' }`).
+ * - `CSSProperties`: A structured object of CSS declarations (e.g., `{ color: "red" }`).
  *
  * - `undefined`: Useful for conditional styling where a style might not be present.
  * Since `boolean` is not accepted, use ternary operators or logical OR

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@entry-ui/qwik",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "",
   "keywords": [],
   "homepage": "https://github.com/ZAHON/entry-ui#readme",
@@ -19,10 +19,18 @@
       "types": "./lib/components/alert/index.d.ts",
       "import": "./lib/components/alert/index.qwik.mjs"
     },
+    "./collapsible": {
+      "types": "./lib/components/collapsible/index.d.ts",
+      "import": "./lib/components/collapsible/index.qwik.mjs"
+    },
     "./separator": {
       "types": "./lib/components/separator/index.d.ts",
       "import": "./lib/components/separator/index.qwik.mjs"
     },
+    "./toggle": {
+      "types": "./lib/components/toggle/index.d.ts",
+      "import": "./lib/components/toggle/index.qwik.mjs"
+    },
     "./use-boolean": {
       "types": "./lib/hooks/use-boolean/index.d.ts",
       "import": "./lib/hooks/use-boolean/index.qwik.mjs"
@@ -31,10 +39,22 @@
       "types": "./lib/hooks/use-controllable/index.d.ts",
       "import": "./lib/hooks/use-controllable/index.qwik.mjs"
     },
+    "./use-counter": {
+      "types": "./lib/hooks/use-counter/index.d.ts",
+      "import": "./lib/hooks/use-counter/index.qwik.mjs"
+    },
     "./use-cycle": {
       "types": "./lib/hooks/use-cycle/index.d.ts",
       "import": "./lib/hooks/use-cycle/index.qwik.mjs"
     },
+    "./use-lifecycle": {
+      "types": "./lib/hooks/use-lifecycle/index.d.ts",
+      "import": "./lib/hooks/use-lifecycle/index.qwik.mjs"
+    },
+    "./make-event-preventable": {
+      "types": "./lib/utilities/make-event-preventable/index.d.ts",
+      "import": "./lib/utilities/make-event-preventable/index.qwik.mjs"
+    },
     "./merge-refs": {
       "types": "./lib/utilities/merge-refs/index.d.ts",
       "import": "./lib/utilities/merge-refs/index.qwik.mjs"
@@ -42,6 +62,9 @@
     "./merge-styles": {
       "types": "./lib/utilities/merge-styles/index.d.ts",
       "import": "./lib/utilities/merge-styles/index.qwik.mjs"
+    },
+    "./types": {
+      "types": "./lib/types/index.d.ts"
     }
   },
   "files": [
@@ -81,7 +104,7 @@
     "qwik": "qwik"
   },
   "dependencies": {
-    "@entry-ui/utilities": "^0.2.0"
+    "@entry-ui/utilities": "^0.5.0"
   },
   "devDependencies": {
     "@entry-ui/eslint": "workspace:*",
@@ -95,6 +118,7 @@
     "jsdom": "^27.4.0",
     "prettier": "^3.7.4",
     "typescript": "^5.9.3",
+    "typescript-plugin-css-modules": "^5.2.0",
     "undici": "^7.18.2",
     "vite": "^7.3.1",
     "vite-tsconfig-paths": "^6.0.4",