@entry-ui/qwik 0.3.0 → 0.5.0

package/lib/_internal/components/primitive/primitive.d.ts

@@ -4,7 +4,7 @@ import type { Component } from '@qwik.dev/core';
  * List of HTML elements that can be created as primitive components.
  * Each node in this array will have a corresponding component in the `Primitive` object.
  */
-declare const NODES: readonly ["div", "span"];
+declare const NODES: readonly ["button", "div", "span"];
 /**
  * A factory function that creates a polymorphic Qwik component for a specific HTML tag.
  */
@@ -20,6 +20,7 @@ export declare const createPrimitive: <Node extends (typeof NODES)[number]>(node
  */
 export declare const Primitive: {
     div: Component<PrimitiveProps<"div">>;
+    button: Component<PrimitiveProps<"button">>;
     span: Component<PrimitiveProps<"span">>;
 };
 export {};

package/lib/_internal/components/primitive/primitive.qwik.mjs

@@ -1,6 +1,7 @@
 import { jsx } from "@qwik.dev/core/jsx-runtime";
 import { component$, Slot } from "@qwik.dev/core";
 const NODES = [
+  "button",
   "div",
   "span"
 ];

package/lib/_internal/components/primitive/primitive.types.d.ts

@@ -1,4 +1,9 @@
 import type { Component, PropsOf } from '@qwik.dev/core';
+/**
+ * Props for polymorphic primitive components.
+ * Combines the standard attributes of the specified HTML element (`Node`)
+ * with the `as` prop to allow component composition and semantic overrides.
+ */
 export type PrimitiveProps<Node> = {
     /**
      * The element or component this component should render as.

package/lib/_internal/index.d.ts

@@ -1 +1,2 @@
 export * from './components';
+export * from './utilities';

package/lib/_internal/utilities/error/error.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Logs an error message to the console with a standardized `"[Entry UI Qwik]"` prefix.
+ *
+ * This utility function simplifies error reporting by automatically
+ * prepending a consistent prefix to all messages originating
+ * from the Entry UI Qwik library.
+ */
+export declare const error: (messages: string[]) => void;

package/lib/_internal/utilities/error/index.d.ts

@@ -0,0 +1 @@
+export { error } from './error';

package/lib/_internal/utilities/fail/fail.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Throws an error message with a standardized `"[Entry UI Qwik]"` prefix.
+ *
+ * This utility function simplifies error reporting by automatically
+ * prepending a consistent prefix to all messages originating
+ * from the Entry UI Qwik library, ensuring immediate execution termination.
+ */
+export declare const fail: (messages: string[]) => never;

package/lib/_internal/utilities/fail/fail.qwik.mjs

@@ -0,0 +1,10 @@
+import { fail as fail$1 } from "@entry-ui/utilities/fail";
+const fail = (messages) => {
+  fail$1({
+    prefix: "[Entry UI Qwik]",
+    messages
+  });
+};
+export {
+  fail
+};

package/lib/_internal/utilities/fail/index.d.ts

@@ -0,0 +1 @@
+export { fail } from './fail';

package/lib/_internal/utilities/index.d.ts

@@ -0,0 +1,3 @@
+export * from './error';
+export * from './fail';
+export * from './warn';

package/lib/_internal/utilities/warn/index.d.ts

@@ -0,0 +1 @@
+export { warn } from './warn';

package/lib/_internal/utilities/warn/warn.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Logs a warning message to the console with a standardized `"[Entry UI Qwik]"` prefix.
+ *
+ * This utility serves as a wrapper around the core warning function, ensuring that
+ * all logs originating from this library are easily identifiable and consistent.
+ */
+export declare const warn: (messages: string[]) => void;

package/lib/components/alert/parts/alert-root/alert-root.types.d.ts

@@ -1,4 +1,8 @@
 import type { Component, PropsOf } from '@qwik.dev/core';
+/**
+ * Props for the `Alert.Root` component.
+ * Extends the standard HTML attributes for a `div` element.
+ */
 export interface AlertRootProps extends PropsOf<'div'> {
     /**
      * The element or component this component should render as.

package/lib/components/index.d.ts

@@ -1,2 +1,3 @@
 export * from './alert';
 export * from './separator';
+export * from './toggle';

package/lib/components/separator/parts/separator-root/separator-root.types.d.ts

@@ -1,4 +1,8 @@
 import type { Component, PropsOf } from '@qwik.dev/core';
+/**
+ * Props for the `Separator.Root` component.
+ * Extends the standard HTML attributes for a `div` element.
+ */
 export interface SeparatorRootProps extends PropsOf<'div'> {
     /**
      * The element or component this component should render as.

package/lib/components/toggle/contexts/index.d.ts

@@ -0,0 +1 @@
+export * from './toggle-root-context';

package/lib/components/toggle/contexts/toggle-root-context/index.d.ts

@@ -0,0 +1,2 @@
+export type { ToggleRootContextValue } from './toggle-root-context.types';
+export { ToggleRootContext } from './toggle-root-context';

package/lib/components/toggle/contexts/toggle-root-context/toggle-root-context.d.ts

@@ -0,0 +1,6 @@
+import type { ToggleRootContextValue } from './toggle-root-context.types';
+/**
+ * Provides the context for the `Toggle.Root` component, allowing descendant
+ * components to access readonly signals and `QRL` functions without prop drilling.
+ */
+export declare const ToggleRootContext: import("@qwik.dev/core").ContextId<ToggleRootContextValue>;

package/lib/components/toggle/contexts/toggle-root-context/toggle-root-context.qwik.mjs

@@ -0,0 +1,5 @@
+import { createContextId } from "@qwik.dev/core";
+const ToggleRootContext = createContextId("entry-ui-qwik-toggle-root-context");
+export {
+  ToggleRootContext
+};

package/lib/components/toggle/contexts/toggle-root-context/toggle-root-context.types.d.ts

@@ -0,0 +1,22 @@
+import type { ReadonlySignal, QRL } from '@qwik.dev/core';
+/**
+ * The value provided by the `Toggle.Root` context.
+ * Contains the readonly signals and `QRL` functions shared with descendant components.
+ */
+export interface ToggleRootContextValue {
+    /**
+     * A readonly signal whose value indicates the toggle's current pressed state.
+     * It is `true` when the toggle is on, and `false` when off.
+     */
+    pressed: ReadonlySignal<boolean>;
+    /**
+     * A `QRL` function used to programmatically set the pressed state of the toggle.
+     * When invoked with `true`, the toggle will be on; with `false`, it will be off.
+     */
+    setPressed$: QRL<(pressed: boolean) => void>;
+    /**
+     * A readonly signal that indicates whether the toggle is disabled.
+     * Its value is `true` if the toggle is disabled, preventing user interaction.
+     */
+    disabled: ReadonlySignal<boolean>;
+}

package/lib/components/toggle/hooks/index.d.ts

@@ -0,0 +1 @@
+export * from './use-toggle-root-context';

package/lib/components/toggle/hooks/use-toggle-root-context/index.d.ts

@@ -0,0 +1,2 @@
+export type { UseToggleRootContextReturnValue } from './use-toggle-root-context.types';
+export { useToggleRootContext } from './use-toggle-root-context';

package/lib/components/toggle/hooks/use-toggle-root-context/use-toggle-root-context.d.ts

@@ -0,0 +1,7 @@
+import type { UseToggleRootContextReturnValue } from './use-toggle-root-context.types';
+/**
+ * A hook that provides access to the `Toggle.Root` component's internal state.
+ * It exposes readonly signals and `QRL` functions to interact with the toggle's state,
+ * allowing descendant components to control or react to its pressed/unpressed state.
+ */
+export declare const useToggleRootContext: () => UseToggleRootContextReturnValue;

package/lib/components/toggle/hooks/use-toggle-root-context/use-toggle-root-context.qwik.mjs

@@ -0,0 +1,13 @@
+import { useContext } from "@qwik.dev/core";
+import { ToggleRootContext } from "../../contexts/toggle-root-context/toggle-root-context.qwik.mjs";
+const useToggleRootContext = () => {
+  const { pressed, setPressed$, disabled } = useContext(ToggleRootContext);
+  return {
+    pressed,
+    setPressed$,
+    disabled
+  };
+};
+export {
+  useToggleRootContext
+};

package/lib/components/toggle/hooks/use-toggle-root-context/use-toggle-root-context.types.d.ts

@@ -0,0 +1,22 @@
+import type { ReadonlySignal, QRL } from '@qwik.dev/core';
+/**
+ * The value returned by the `useToggleRootContext` hook.
+ * Provides access to the toggle's readonly signals and `QRL` functions for descendant components.
+ */
+export interface UseToggleRootContextReturnValue {
+    /**
+     * A readonly signal whose value indicates the toggle's current pressed state.
+     * It is `true` when the toggle is on, and `false` when off.
+     */
+    pressed: ReadonlySignal<boolean>;
+    /**
+     * A `QRL` function used to programmatically set the pressed state of the toggle.
+     * When invoked with `true`, the toggle will be on; with `false`, it will be off.
+     */
+    setPressed$: QRL<(pressed: boolean) => void>;
+    /**
+     * A readonly signal that indicates whether the toggle is disabled.
+     * Its value is `true` if the toggle is disabled, preventing user interaction.
+     */
+    disabled: ReadonlySignal<boolean>;
+}

package/lib/components/toggle/index.d.ts

@@ -0,0 +1,2 @@
+export * as Toggle from './parts';
+export * from './hooks';

package/lib/components/toggle/index.qwik.mjs

@@ -0,0 +1,6 @@
+import * as index from "./parts/index.qwik.mjs";
+import { useToggleRootContext } from "./hooks/use-toggle-root-context/use-toggle-root-context.qwik.mjs";
+export {
+  index as Toggle,
+  useToggleRootContext
+};

package/lib/components/toggle/parts/index.d.ts

@@ -0,0 +1,2 @@
+export type { ToggleRootProps as RootProps } from './toggle-root';
+export { ToggleRoot as Root } from './toggle-root';

package/lib/components/toggle/parts/index.qwik.mjs

@@ -0,0 +1,4 @@
+import { ToggleRoot } from "./toggle-root/toggle-root.qwik.mjs";
+export {
+  ToggleRoot as Root
+};

package/lib/components/toggle/parts/toggle-root/index.d.ts

@@ -0,0 +1,2 @@
+export type { ToggleRootProps } from './toggle-root.types';
+export { ToggleRoot } from './toggle-root';

package/lib/components/toggle/parts/toggle-root/toggle-root.d.ts

@@ -0,0 +1,7 @@
+import type { ToggleRootProps } from './toggle-root.types';
+/**
+ * Contains the content for the toggle.
+ *
+ * Renders a `<button>` element.
+ */
+export declare const ToggleRoot: import("@qwik.dev/core").Component<ToggleRootProps>;

package/lib/components/toggle/parts/toggle-root/toggle-root.qwik.mjs

@@ -0,0 +1,43 @@
+import { jsx } from "@qwik.dev/core/jsx-runtime";
+import { component$, useComputed$, $, useContextProvider, Slot } from "@qwik.dev/core";
+import { useControllable } from "../../../../hooks/use-controllable/use-controllable.qwik.mjs";
+import { Primitive } from "../../../../_internal/components/primitive/primitive.qwik.mjs";
+import { ToggleRootContext } from "../../contexts/toggle-root-context/toggle-root-context.qwik.mjs";
+const ToggleRoot = component$((props) => {
+  const { as = "button", defaultPressed, pressed: _pressed, onPressedChange$, disabled: _disabled = false, onClick$, ...others } = props;
+  const { state: pressed, setState$: setPressed$ } = useControllable({
+    defaultValue: defaultPressed ?? false,
+    controlledSignal: _pressed,
+    onChange$: onPressedChange$
+  });
+  const disabled = useComputed$(() => _disabled);
+  const handleClick$ = $((event) => {
+    const entryUIQwikEvent = event;
+    if (!entryUIQwikEvent.entryUIQwikHandlerPrevented && !disabled.value) {
+      setPressed$(!pressed.value);
+    }
+  });
+  useContextProvider(ToggleRootContext, {
+    pressed,
+    setPressed$,
+    disabled
+  });
+  return /* @__PURE__ */ jsx(Primitive.button, {
+    as,
+    type: "button",
+    disabled: disabled.value,
+    "aria-pressed": pressed.value,
+    "data-entry-ui-qwik-toggle-root": "",
+    "data-state": pressed.value ? "on" : "off",
+    "data-disabled": disabled.value ? "" : void 0,
+    onClick$: [
+      onClick$,
+      handleClick$
+    ],
+    ...others,
+    children: /* @__PURE__ */ jsx(Slot, {})
+  });
+});
+export {
+  ToggleRoot
+};

package/lib/components/toggle/parts/toggle-root/toggle-root.types.d.ts

@@ -0,0 +1,41 @@
+import type { PropsOf, Component, Signal, QRL } from '@qwik.dev/core';
+/**
+ * Props for the `Toggle.Root` component.
+ * Extends the standard HTML attributes for a `button` element.
+ */
+export interface ToggleRootProps extends PropsOf<'button'> {
+    /**
+     * The element or component this component should render as.
+     *
+     * @see {@link https://github.com/ZAHON/entry-ui/tree/main/packages/qwik/docs/guides/composition.md Composition} guide for more details.
+     *
+     * @default "button"
+     */
+    as?: string | Component;
+    /**
+     * The pressed state of the toggle when it is initially rendered.
+     * Use when you do not need to control its pressed state.
+     *
+     * @default undefined
+     */
+    defaultPressed?: boolean;
+    /**
+     * The controlled pressed state of the toggle.
+     * Must be used in conjunction with `onPressedChange$`.
+     *
+     * @default undefined
+     */
+    pressed?: Signal<boolean>;
+    /**
+     * A `QRL` callback function that is called when the pressed state of the toggle changes.
+     *
+     * @default undefined
+     */
+    onPressedChange$?: QRL<(pressed: boolean) => void>;
+    /**
+     * When `true`, prevents the user from interacting with the toggle.
+     *
+     * @default false
+     */
+    disabled?: boolean;
+}

package/lib/hooks/index.d.ts

@@ -0,0 +1,3 @@
+export * from './use-boolean';
+export * from './use-controllable';
+export * from './use-cycle';

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

@@ -0,0 +1,2 @@
+export type { UseBooleanReturnValue } from './use-boolean.types';
+export { useBoolean } from './use-boolean';

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

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

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

@@ -0,0 +1,12 @@
+import type { UseBooleanReturnValue } from './use-boolean.types';
+/**
+ * A hook that manages a boolean state with common utility methods.
+ *
+ * The hook accepts a single `initialState` parameter, which defaults to `false`.
+ * It simplifies the management of boolean flags (toggles, modals, drawers) by
+ * encapsulating a boolean signal and exposing it as a readonly signal.
+ *
+ * State mutations are performed exclusively through the provided `QRL`
+ * functions (`setFalse$` ,`setTrue$`, `toggle$`), promoting a predictable data flow.
+ */
+export declare const useBoolean: (initialState?: boolean) => UseBooleanReturnValue;

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

@@ -0,0 +1,22 @@
+import { useSignal, $ } from "@qwik.dev/core";
+const useBoolean = (initialState = false) => {
+  const state = useSignal(initialState);
+  const setFalse$ = $(() => {
+    state.value = false;
+  });
+  const setTrue$ = $(() => {
+    state.value = true;
+  });
+  const toggle$ = $(() => {
+    state.value = !state.value;
+  });
+  return {
+    state,
+    setFalse$,
+    setTrue$,
+    toggle$
+  };
+};
+export {
+  useBoolean
+};

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

@@ -0,0 +1,22 @@
+import type { ReadonlySignal, QRL } from '@qwik.dev/core';
+/**
+ * Represents the object returned by the `useBoolean` hook.
+ */
+export interface UseBooleanReturnValue {
+    /**
+     * A readonly signal whose value indicates the current boolean state.
+     */
+    state: ReadonlySignal<boolean>;
+    /**
+     * A `QRL` function to set the boolean state to `false`.
+     */
+    setFalse$: QRL<() => void>;
+    /**
+     * A `QRL` function to set the boolean state to `true`.
+     */
+    setTrue$: QRL<() => void>;
+    /**
+     * A `QRL` function to toggle the boolean state.
+     */
+    toggle$: QRL<() => void>;
+}

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

@@ -0,0 +1,2 @@
+export type { UseControllableParams, UseControllableReturnValue } from './use-controllable.types';
+export { useControllable } from './use-controllable';

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

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

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

@@ -0,0 +1,14 @@
+import type { UseControllableParams, UseControllableReturnValue } from './use-controllable.types';
+/**
+ * A hook that manages state in either controlled or uncontrolled mode.
+ *
+ * It provides a unified interface for handling state updates, regardless of whether
+ * the data is managed internally or by a parent component. This pattern is essential
+ * for building flexible UI components that need to support both "set-and-forget"
+ * usage and tight integration with external state.
+ *
+ * State synchronization is handled automatically:
+ * - **Controlled**: Uses the provided `controlledSignal` and requests changes via `onChange$`.
+ * - **Uncontrolled**: Manages an internal signal initialized by `defaultValue`.
+ */
+export declare const useControllable: <T>(params?: UseControllableParams<T>) => UseControllableReturnValue<T>;

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

@@ -0,0 +1,35 @@
+import { $, useSignal } from "@qwik.dev/core";
+import { isDev } from "@qwik.dev/core/build";
+import { fail } from "../../_internal/utilities/fail/fail.qwik.mjs";
+const useControllable = (params = {}) => {
+  const { defaultValue, controlledSignal, onChange$ } = params;
+  if (controlledSignal !== void 0) {
+    const handleExternalStateChange$ = $((value) => {
+      onChange$?.(value);
+    });
+    return {
+      state: controlledSignal,
+      setState$: handleExternalStateChange$,
+      controlled: true
+    };
+  }
+  if (isDev && defaultValue === void 0) {
+    fail([
+      `The 'defaultValue' parameter in 'useControllable' hook is required when 'controlledSignal' is not provided.`,
+      `Either provide a 'defaultValue' for uncontrolled mode, or pass a 'controlledSignal' for controlled mode.`
+    ]);
+  }
+  const internalState = useSignal(defaultValue);
+  const handleInternalStateChange$ = $((value) => {
+    internalState.value = value;
+    onChange$?.(value);
+  });
+  return {
+    state: internalState,
+    setState$: handleInternalStateChange$,
+    controlled: false
+  };
+};
+export {
+  useControllable
+};

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

@@ -0,0 +1,52 @@
+import type { Signal, QRL, ReadonlySignal } from '@qwik.dev/core';
+/**
+ * Configuration parameters for the `useControllable` hook.
+ * This interface defines the inputs required to initialize the hook in either
+ * controlled or uncontrolled mode, allowing for flexible state management
+ * strategies within the same component.
+ */
+export interface UseControllableParams<T> {
+    /**
+     * The initial value used when the component is in uncontrolled mode.
+     * This value is only used to initialize the internal state if `controlledSignal` is not provided.
+     */
+    defaultValue?: T;
+    /**
+     * An optional external signal for controlled state management.
+     * If provided, the hook operates in controlled mode, delegating state authority to the parent.
+     * If omitted, the hook operates in uncontrolled mode using internal state.
+     */
+    controlledSignal?: Signal<T>;
+    /**
+     * An optional `QRL` callback invoked whenever the state value changes.
+     * In controlled mode, it notifies the parent to update the external signal.
+     * In uncontrolled mode, it acts as a listener for internal state changes.
+     */
+    onChange$?: QRL<(value: T) => void>;
+}
+/**
+ * The stable interface returned by the `useControllable` hook.
+ * It provides a unified way to access the current state and perform updates,
+ * abstracting away the complexity of switching between controlled and
+ * uncontrolled internal logic.
+ */
+export interface UseControllableReturnValue<T> {
+    /**
+     * A readonly signal representing the current state.
+     * Provides the value from the `controlledSignal` in controlled mode,
+     * or the internal signal in uncontrolled mode.
+     */
+    state: ReadonlySignal<T>;
+    /**
+     * A `QRL` function to update the state.
+     * In controlled mode, it triggers `onChange$` to request a change from the parent.
+     * In uncontrolled mode, it updates the internal signal and then invokes `onChange$`.
+     */
+    setState$: QRL<(value: T) => void>;
+    /**
+     * A boolean flag indicating the current management mode.
+     * Returns `true` if the state is managed externally via `controlledSignal`,
+     * and `false` if managed internally.
+     */
+    controlled: boolean;
+}

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

@@ -0,0 +1,2 @@
+export type { UseCycleParams, UseCycleReturnValue } from './use-cycle.types';
+export { useCycle } from './use-cycle';

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

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

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

@@ -0,0 +1,11 @@
+import type { UseCycleParams, UseCycleReturnValue } from './use-cycle.types';
+/**
+ * A hook that manages navigation through a predefined sequence of options.
+ *
+ * This hook provides a robust way to handle multi-state logic by rotating through an array of values.
+ * It features advanced navigation controls, allowing for forward and backward movement,
+ * direct jumps to the start or end of the sequence, and configurable looping behavior.
+ * It is particularly useful for building components such as carousels, steppers,
+ * multi-state switches, or any UI element requiring sequential state transitions.
+ */
+export declare const useCycle: <T>(params: UseCycleParams<T>) => UseCycleReturnValue<T>;

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

@@ -0,0 +1,54 @@
+import { useSignal, $ } from "@qwik.dev/core";
+const useCycle = (params) => {
+  const { options, defaultOption, loop = true } = params;
+  const option = useSignal(() => {
+    if (defaultOption !== void 0 && options.includes(defaultOption)) {
+      return defaultOption;
+    }
+    return options[0];
+  });
+  const next$ = $(() => {
+    const currentIndex = options.indexOf(option.value);
+    const nextIndex = currentIndex + 1;
+    if (loop) {
+      option.value = options[nextIndex % options.length];
+    } else {
+      if (nextIndex < options.length) {
+        option.value = options[nextIndex];
+      }
+    }
+  });
+  const previous$ = $(() => {
+    const currentIndex = options.indexOf(option.value);
+    const prevIndex = currentIndex - 1;
+    if (loop) {
+      option.value = options[(prevIndex + options.length) % options.length];
+    } else {
+      if (prevIndex >= 0) {
+        option.value = options[prevIndex];
+      }
+    }
+  });
+  const first$ = $(() => {
+    option.value = options[0];
+  });
+  const last$ = $(() => {
+    option.value = options[options.length - 1];
+  });
+  const set$ = $((value) => {
+    if (options.includes(value)) {
+      option.value = value;
+    }
+  });
+  return {
+    option,
+    next$,
+    previous$,
+    first$,
+    last$,
+    set$
+  };
+};
+export {
+  useCycle
+};

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

@@ -0,0 +1,63 @@
+import type { ReadonlySignal, QRL } from '@qwik.dev/core';
+/**
+ * Configuration parameters for the `useCycle` hook.
+ */
+export interface UseCycleParams<T> {
+    /**
+     * A readonly array of values to cycle through.
+     * This defines the sequence and the scope of all possible states the hook can manage.
+     */
+    options: readonly T[];
+    /**
+     * The initial value to be set when the hook is first initialized.
+     * If provided, it must be present in the `options` array.
+     * If the provided value is not found within the `options` array,
+     * the hook will fall back to the first element of the array.
+     *
+     * @default options[0]
+     */
+    defaultOption?: T;
+    /**
+     * Determines the behavior when navigating past the boundaries of the `options` array.
+     * If set to `true`, the sequence will wrap around (e.g., from last to first).
+     * If `false`, navigation will stop at the first or last element.
+     *
+     * @default true
+     */
+    loop?: boolean;
+}
+/**
+ * Represents the object returned by the `useCycle` hook.
+ */
+export interface UseCycleReturnValue<T> {
+    /**
+     * A readonly signal whose value represents the currently active option from the provided array.
+     * This signal is read-only, which means its value can only be changed by calling navigation `QRL` functions
+     * like `next$`, `previous$`, or `set$`, ensuring predictable state transitions.
+     */
+    option: ReadonlySignal<T>;
+    /**
+     * A `QRL` function that advances the value to the next option in the sequence.
+     * If `loop` is enabled, it cycles back to the first item upon reaching the end.
+     */
+    next$: QRL<() => void>;
+    /**
+     * A `QRL` function that moves the value to the previous option in the sequence.
+     * If `loop` is enabled, it cycles back to the last item upon reaching the start.
+     */
+    previous$: QRL<() => void>;
+    /**
+     * A `QRL` function that jumps directly to the first item in the `options` array.
+     */
+    first$: QRL<() => void>;
+    /**
+     * A `QRL` function that jumps directly to the last item in the `options` array.
+     */
+    last$: QRL<() => void>;
+    /**
+     * A `QRL` function that directly sets the `option` to a new value.
+     * This function includes a built-in validation check; the value will only be updated
+     * if it is present in the original `options` array.
+     */
+    set$: QRL<(value: T) => void>;
+}

package/lib/index.d.ts

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

package/lib/index.qwik.mjs

@@ -1,6 +1,22 @@
 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 { 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 { useCycle } from "./hooks/use-cycle/use-cycle.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 Separator,
+  index$2 as Toggle,
+  makeEventPreventable,
+  mergeRefs,
+  mergeStyles,
+  useBoolean,
+  useControllable,
+  useCycle,
+  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,2 @@
+export * from './entry-ui-qwik-event';
+export * from './entry-ui-qwik-event-state';

package/lib/utilities/index.d.ts

@@ -0,0 +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-refs/index.d.ts

@@ -0,0 +1,2 @@
+export type { PossibleRef } from './merge-refs.types';
+export { mergeRefs } from './merge-refs';

package/lib/utilities/merge-refs/index.qwik.mjs

@@ -0,0 +1,4 @@
+import { mergeRefs } from "./merge-refs.qwik.mjs";
+export {
+  mergeRefs
+};

package/lib/utilities/merge-refs/merge-refs.d.ts

@@ -0,0 +1,15 @@
+import type { PossibleRef } from './merge-refs.types';
+/**
+ * Combines 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
+ * useful when a component needs to maintain its own internal reference to an element
+ * while also forwarding a reference to a consumer via props.
+ *
+ * When the returned callback is executed, it iterates through all provided refs and:
+ * - Updates the `.value` property if the ref is a `Signal`.
+ * - Invokes the function if the `ref` is a callback.
+ * - Gracefully ignores `undefined` values.
+ */
+export declare const mergeRefs: <T extends Element>(refs: PossibleRef<T>[]) => import("@qwik.dev/core").QRL<(node: T) => void>;

package/lib/utilities/merge-refs/merge-refs.qwik.mjs

@@ -0,0 +1,17 @@
+import { noSerialize, $, isSignal } from "@qwik.dev/core";
+const mergeRefs = (refs) => {
+  const _refs = noSerialize(refs);
+  return $((node) => {
+    _refs?.forEach((ref) => {
+      if (!ref) return;
+      if (isSignal(ref)) {
+        ref.value = node;
+      } else if (typeof ref === "function") {
+        ref(node);
+      }
+    });
+  });
+};
+export {
+  mergeRefs
+};

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

@@ -0,0 +1,14 @@
+import type { Signal } from '@qwik.dev/core';
+/**
+ * Represents the various ways a reference can be assigned to a DOM element in Qwik.
+ *
+ * This type provides flexibility for handling references, supporting:
+ *
+ * - `Signal<T | undefined>` or `Signal<Element | undefined>`: The standard Qwik approach using `useSignal`.
+ * It allows the element to be reactively tracked within the `.value` property.
+ *
+ * - `(node: T) => void`: A callback ref (ref-callback) that provides direct access to the DOM node upon mounting.
+ *
+ * - `undefined`: Designed for optional references. This allows you to pass component props directly into the utility without manual null-checks.
+ */
+export type PossibleRef<T> = Signal<Element | undefined> | Signal<T | undefined> | ((node: T) => void) | undefined;

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

@@ -0,0 +1,2 @@
+export type { PossibleStyle } from './merge-styles.types';
+export { mergeStyles } from './merge-styles';

package/lib/utilities/merge-styles/index.qwik.mjs

@@ -0,0 +1,4 @@
+import { mergeStyles } from "./merge-styles.qwik.mjs";
+export {
+  mergeStyles
+};

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

@@ -0,0 +1,13 @@
+import type { PossibleStyle } from './merge-styles.types';
+import type { CSSProperties } from '@qwik.dev/core';
+/**
+ * Merges multiple style values into a single, unified style object.
+ *
+ * This function consolidates a variety of style formats (inline strings, CSS objects,
+ * or undefined) into a single `CSSProperties` object. It ensures that all property
+ * keys are normalized to camelCase (preserving CSS variables and handling vendor
+ * prefixes appropriately) to remain compatible with JavaScript-based styling engines.
+ * The merging process follows the CSS cascade principle: styles appearing later in
+ * the array will override matching properties from earlier styles.
+ */
+export declare const mergeStyles: (styles: PossibleStyle[]) => CSSProperties;

package/lib/utilities/merge-styles/merge-styles.qwik.mjs

@@ -0,0 +1,7 @@
+import { mergeStyles as mergeStyles$1 } from "@entry-ui/utilities/merge-styles";
+const mergeStyles = (styles) => {
+  return mergeStyles$1(styles);
+};
+export {
+  mergeStyles
+};

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

@@ -0,0 +1,15 @@
+import type { CSSProperties } from '@qwik.dev/core';
+/**
+ * Represents the accepted formats for style declarations.
+ *
+ * This type allows for flexibility in how styles are defined, supporting:
+ *
+ * - `string`: Standard inline CSS strings (e.g., `"color: red; padding: 10px"`).
+ *
+ * - `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
+ * to ensure a valid type (e.g., `isActive ? "color: red" : undefined`).
+ */
+export type PossibleStyle = string | CSSProperties | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@entry-ui/qwik",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "",
   "keywords": [],
   "homepage": "https://github.com/ZAHON/entry-ui#readme",
@@ -22,6 +22,37 @@
     "./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"
+    },
+    "./use-controllable": {
+      "types": "./lib/hooks/use-controllable/index.d.ts",
+      "import": "./lib/hooks/use-controllable/index.qwik.mjs"
+    },
+    "./use-cycle": {
+      "types": "./lib/hooks/use-cycle/index.d.ts",
+      "import": "./lib/hooks/use-cycle/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"
+    },
+    "./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": [
@@ -61,7 +92,7 @@
     "qwik": "qwik"
   },
   "dependencies": {
-    "@entry-ui/utilities": "workspace:*"
+    "@entry-ui/utilities": "^0.3.0"
   },
   "devDependencies": {
     "@entry-ui/eslint": "workspace:*",
@@ -75,6 +106,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",