@entry-ui/qwik 0.5.0 → 0.7.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.qwik.mjs

@@ -1,22 +1,40 @@
-import * as index from "./components/alert/parts/index.qwik.mjs";
-import * as index$1 from "./components/separator/parts/index.qwik.mjs";
-import * as index$2 from "./components/toggle/parts/index.qwik.mjs";
+import * as index from "./components/accordion/parts/index.qwik.mjs";
+import { useAccordionRootContext } from "./components/accordion/hooks/use-accordion-root-context/use-accordion-root-context.qwik.mjs";
+import { useAccordionItemContext } from "./components/accordion/hooks/use-accordion-item-context/use-accordion-item-context.qwik.mjs";
+import { useAccordionItemTriggerContext } from "./components/accordion/hooks/use-accordion-item-trigger-context/use-accordion-item-trigger-context.qwik.mjs";
+import * as index$1 from "./components/alert/parts/index.qwik.mjs";
+import * as index$2 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$3 from "./components/separator/parts/index.qwik.mjs";
+import * as index$4 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$2 as Toggle,
+  index as Accordion,
+  index$1 as Alert,
+  index$2 as Collapsible,
+  index$3 as Separator,
+  index$4 as Toggle,
   makeEventPreventable,
   mergeRefs,
   mergeStyles,
+  useAccordionItemContext,
+  useAccordionItemTriggerContext,
+  useAccordionRootContext,
   useBoolean,
+  useCollapsibleRootContext,
+  useCollapsibleTriggerContext,
   useControllable,
+  useCounter,
   useCycle,
+  useLifecycle,
   useToggleRootContext
 };

package/lib/types/index.d.ts

@@ -1,2 +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/merge-refs/merge-refs.d.ts

@@ -1,6 +1,6 @@
 import type { PossibleRef } from './merge-refs.types';
 /**
- * Combines multiple references into a single callback ref.
+ * Merges multiple references into a single callback ref.
  *
  * This utility function allows you to assign a single DOM element to multiple
  * reference handlers (both Qwik Signals and callback functions). It is particularly

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@entry-ui/qwik",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "",
   "keywords": [],
   "homepage": "https://github.com/ZAHON/entry-ui#readme",
@@ -15,10 +15,18 @@
       "types": "./lib/index.d.ts",
       "import": "./lib/index.qwik.mjs"
     },
+    "./accordion": {
+      "types": "./lib/components/accordion/index.d.ts",
+      "import": "./lib/components/accordion/index.qwik.mjs"
+    },
     "./alert": {
       "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"
@@ -35,10 +43,18 @@
       "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"
@@ -92,7 +108,7 @@
     "qwik": "qwik"
   },
   "dependencies": {
-    "@entry-ui/utilities": "^0.3.0"
+    "@entry-ui/utilities": "^0.6.0"
   },
   "devDependencies": {
     "@entry-ui/eslint": "workspace:*",