@hashrytech/quick-components-kit 0.15.7 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @hashrytech/quick-components-kit
 
+## 0.16.0
+
+### Minor Changes
+
+- refactor: Drawer, Overlay and adding Portal component
+
 ## 0.15.7
 
 ### Patch Changes

package/dist/actions/stop-interaction.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @action stopInteraction
+ *
+ * A flexible Svelte action that prevents event propagation and/or default browser behavior
+ * for specified events using the capture phase. Useful for modals, drawers, popups, or any
+ * element where you want to intercept user interaction early in the event flow.
+ *
+ * @param node - The target HTML element to attach event listeners to.
+ * @param options - An optional object to configure the behavior.
+ *   - `stop` (default: `true`) — Calls `event.stopPropagation()` to prevent bubbling.
+ *   - `prevent` (default: `false`) — Calls `event.preventDefault()` to cancel default behavior.
+ *   - `events` (default: `['click', 'mousedown', 'mouseup', 'touchstart']`) — DOM event types to intercept.
+ *
+ * @example
+ * ```svelte
+ * <div use:stopInteraction />
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <div use:stopInteraction={{ prevent: true }} />
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <div use:stopInteraction={{ stop: true, prevent: true, events: ['click', 'touchstart'] }} />
+ * ```
+ */
+export type StopInteractionOptions = {
+    stop?: boolean;
+    prevent?: boolean;
+    events?: string[];
+};
+export declare function stopInteraction(node: HTMLElement, options?: StopInteractionOptions): {
+    destroy(): void;
+};

package/dist/actions/stop-interaction.js

@@ -0,0 +1,46 @@
+/**
+ * @action stopInteraction
+ *
+ * A flexible Svelte action that prevents event propagation and/or default browser behavior
+ * for specified events using the capture phase. Useful for modals, drawers, popups, or any
+ * element where you want to intercept user interaction early in the event flow.
+ *
+ * @param node - The target HTML element to attach event listeners to.
+ * @param options - An optional object to configure the behavior.
+ *   - `stop` (default: `true`) — Calls `event.stopPropagation()` to prevent bubbling.
+ *   - `prevent` (default: `false`) — Calls `event.preventDefault()` to cancel default behavior.
+ *   - `events` (default: `['click', 'mousedown', 'mouseup', 'touchstart']`) — DOM event types to intercept.
+ *
+ * @example
+ * ```svelte
+ * <div use:stopInteraction />
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <div use:stopInteraction={{ prevent: true }} />
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <div use:stopInteraction={{ stop: true, prevent: true, events: ['click', 'touchstart'] }} />
+ * ```
+ */
+export function stopInteraction(node, options = { stop: true, prevent: false }) {
+    const { stop = true, prevent = false, events = ['click'] } = options;
+    const cleanups = events.map((event) => {
+        const handler = (e) => {
+            if (stop)
+                e.stopPropagation();
+            if (prevent)
+                e.preventDefault();
+        };
+        node.addEventListener(event, handler, true); // capture
+        return () => node.removeEventListener(event, handler, true);
+    });
+    return {
+        destroy() {
+            cleanups.forEach((fn) => fn());
+        }
+    };
+}

package/dist/components/drawer/Drawer.svelte

@@ -1,10 +1,52 @@
-<script lang="ts" module>    
+<!--
+@component Drawer
+
+A flexible slide-in drawer component built with Svelte 5 and Tailwind CSS. Supports positional rendering (`left`, `right`, `top`, `bottom`), transition control, accessibility, and optional background overlay. Typically used for side menus, filters, or modal-like panels.
+
+## Props
+
+- `open?`: `boolean` — Whether the drawer is visible. Bindable.
+- `escapeKeyClose?`: `boolean` — If true, pressing Escape closes the drawer. Default: `true`.
+- `disableBodyScroll?`: `boolean` — Prevents body scrolling when drawer is open. Default: `true`.
+- `ariaLabel?`: `string` — Accessibility label for the drawer. Default: `"Drawer"`.
+- `position?`: `"left" | "right" | "top" | "bottom"` — Direction the drawer slides from. Default: `"left"`.
+- `transitionDuration?`: `number` — Duration of fly transition in milliseconds. Defaults to `config.transitionDuration`.
+- `transitionDistance?`: `number` — Distance the drawer slides in from. Default: `240`.
+- `overlayClasses?`: `string` — Additional classes passed to the background overlay.
+- `class?`: `ClassNameValue` — Tailwind classes for the drawer content container.
+- `children?`: `Snippet` — Svelte fragment rendered inside the drawer content.
+
+## Slots
+
+This component uses `children` as a rendered snippet via `{@render}`.
+
+## Overlay
+
+The `<Overlay>` component is used to darken the background and optionally block interaction. It is clickable and will trigger the drawer to close unless stopped by event propagation. You can customize its styling using the `overlayClasses` prop.
+
+## Usage
+
+```svelte
+<script>
+  import Drawer from '@hashrytech/quick-components-kit';
+  let isOpen = false;
+</script>
+
+<Drawer bind:open={isOpen} position="right" ariaLabel="Menu" transitionDuration={300}>
+  <p class="p-4">Drawer content goes here</p>
+</Drawer>
+```
+-->
+
+<script lang="ts" module>
 	  import { type Snippet } from 'svelte';
     import type { ClassNameValue } from 'tailwind-merge';
     import { fly } from 'svelte/transition';
     import {twMerge} from 'tailwind-merge';
     import Overlay from '../overlay/Overlay.svelte';
     import { onKeydown } from '../../actions/on-keydown.js';
+    import { stopInteraction } from '../../actions/stop-interaction.js';
+    import { config } from '../../configs/config.js';
     
     export type DrawerProps = {
       open?: boolean;
@@ -22,7 +64,18 @@
 </script>
 
 <script lang="ts">  
-  let {open=$bindable(false), escapeKeyClose=true, disableBodyScroll=true, ariaLabel="Drawer", position="left", transitionDuration=200, transitionDistance=240, overlayClasses="", children, ...props}: DrawerProps = $props();
+  let {
+    open=$bindable(false), 
+    escapeKeyClose=true, 
+    disableBodyScroll=true, 
+    ariaLabel="Drawer", 
+    position="left", 
+    transitionDuration=config.transitionDuration, 
+    transitionDistance=240, 
+    overlayClasses="", 
+    children, 
+    ...props
+  }: DrawerProps = $props();
 
   const transitionProperties = {
     x: position == "left" ? -transitionDistance : position == "right" ? transitionDistance : 0,
@@ -52,7 +105,7 @@
 {#if open}
 <Overlay {transitionDuration} {disableBodyScroll} class={overlayClasses} onclick={() => open = false} />
 
-<div role="dialog" aria-modal="true" aria-label={ariaLabel} tabindex="{open ? 0 : -1}" aria-hidden="{!open}" 
+<div role="dialog" aria-modal="true" aria-label={ariaLabel} tabindex="{open ? 0 : -1}" aria-hidden="{!open}" use:stopInteraction={{ stop: true, prevent: true, events: [''] }}
   class={twMerge("fixed flex flex-col items-center gap-2 bg-white outline-0 focus:outline-0 active:outline-focus-primary focus:outline-focus-primary overflow-y-auto", postionClasses[position], props.class)}
   in:fly={transitionProperties}
   out:fly={transitionProperties}

package/dist/components/drawer/Drawer.svelte.d.ts

@@ -12,6 +12,45 @@ export type DrawerProps = {
     children?: Snippet;
     class?: ClassNameValue;
 };
+/**
+ * Drawer
+ *
+ * A flexible slide-in drawer component built with Svelte 5 and Tailwind CSS. Supports positional rendering (`left`, `right`, `top`, `bottom`), transition control, accessibility, and optional background overlay. Typically used for side menus, filters, or modal-like panels.
+ *
+ * ## Props
+ *
+ * - `open?`: `boolean` — Whether the drawer is visible. Bindable.
+ * - `escapeKeyClose?`: `boolean` — If true, pressing Escape closes the drawer. Default: `true`.
+ * - `disableBodyScroll?`: `boolean` — Prevents body scrolling when drawer is open. Default: `true`.
+ * - `ariaLabel?`: `string` — Accessibility label for the drawer. Default: `"Drawer"`.
+ * - `position?`: `"left" | "right" | "top" | "bottom"` — Direction the drawer slides from. Default: `"left"`.
+ * - `transitionDuration?`: `number` — Duration of fly transition in milliseconds. Defaults to `config.transitionDuration`.
+ * - `transitionDistance?`: `number` — Distance the drawer slides in from. Default: `240`.
+ * - `overlayClasses?`: `string` — Additional classes passed to the background overlay.
+ * - `class?`: `ClassNameValue` — Tailwind classes for the drawer content container.
+ * - `children?`: `Snippet` — Svelte fragment rendered inside the drawer content.
+ *
+ * ## Slots
+ *
+ * This component uses `children` as a rendered snippet via `{@render}`.
+ *
+ * ## Overlay
+ *
+ * The `<Overlay>` component is used to darken the background and optionally block interaction. It is clickable and will trigger the drawer to close unless stopped by event propagation. You can customize its styling using the `overlayClasses` prop.
+ *
+ * ## Usage
+ *
+ * ```svelte
+ * <script>
+ * import Drawer from '@hashrytech/quick-components-kit';
+ * let isOpen = false;
+ * </script>
+ *
+ * <Drawer bind:open={isOpen} position="right" ariaLabel="Menu" transitionDuration={300}>
+ * <p class="p-4">Drawer content goes here</p>
+ * </Drawer>
+ * ```
+ */
 declare const Drawer: import("svelte").Component<DrawerProps, {
     closeDrawer: () => void;
 }, "open">;

package/dist/components/overlay/Overlay.svelte

@@ -17,10 +17,10 @@
 </script>
 
 <script lang="ts">
-  let {disableBodyScroll=true, transitionDuration=100, ariaLabel="Overlay", onclick, children, ...props}: OverlayProps = $props();
+  let { disableBodyScroll=true, transitionDuration=100, ariaLabel="Overlay", onclick, children, ...props }: OverlayProps = $props();
 </script>
 
-<div transition:fade={{duration: transitionDuration}} class={twMerge("fixed top-0 left-0 right-0 bottom-0 bg-overlay-primary", props.class)} role="presentation" {onclick} 
-  use:disableScroll={disableBodyScroll}>
+<div transition:fade={{duration: transitionDuration}} class={twMerge("fixed top-0 left-0 right-0 bottom-0 bg-overlay-primary", props.class)} role="presentation" {onclick} use:disableScroll={disableBodyScroll}>
+  {@render children?.()}
 </div>
 

package/dist/components/portal/Portal.svelte

@@ -0,0 +1,73 @@
+<!--
+@component Portal
+
+A utility component that renders its children outside the current DOM hierarchy by prepending them into a target DOM element (e.g., `document.body`). Useful for modals, drawers, toasts, and overlays to avoid z-index and layout conflicts.
+
+## Props
+
+- `target?`: `HTMLElement` — The DOM node to render the content into. Defaults to `document.body` if not provided. Useful for directing content to a specific container.
+- `prepend?: boolean` — If true (default), the portal will be prepended to the target node. If false, it will be appended. This controls the render order of layered content.
+- `children?`: `Snippet` — The Svelte children content to render inside the portal. Use `{@render}` to render dynamic fragments.
+- `class?`: `ClassNameValue` — Tailwind CSS or custom classes applied to the outer container div.
+
+## Behavior
+
+- On mount, a new `div` is created and prepended to the `target`.
+- On destroy, the element is removed from the DOM.
+- Children are rendered via `{@render children?.()}` to support dynamic content blocks.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import Portal from './Portal.svelte';
+  let show = true;
+</script>
+
+{#if show}
+  <Portal>
+    <div class="absolute top-0 left-0 h-screen w-screen bg-black/50 z-50">
+      <div class="bg-white p-6 rounded shadow">Hello from Portal!</div>
+    </div>
+  </Portal>
+{/if}
+```
+-->
+
+<script lang="ts" module>    
+	import { type Snippet } from 'svelte';
+    import type { ClassNameValue } from 'tailwind-merge';    
+    import {twMerge} from 'tailwind-merge';
+    import { onMount, onDestroy } from 'svelte';
+    import { browser } from '$app/environment';
+    
+    export type PortalProps = {
+      target?: HTMLElement;
+      prepend?: boolean;    
+      children?: Snippet;
+      class?: ClassNameValue;
+    };
+
+</script>
+
+<script lang="ts">
+  let { target = browser ? document.body : undefined, prepend = true, children, ...props }: PortalProps = $props();  
+  let el: HTMLDivElement;
+
+  onMount(() => {    
+    if (!browser || !el) return;
+    if(prepend)
+        target?.prepend(el);
+    else
+        target?.append(el);
+  });
+
+  onDestroy(() => {
+    el?.remove();
+  });
+</script>
+
+<!-- This div will be appended to `target` -->
+<div bind:this={el} class={twMerge("", props.class)}>
+  {@render children?.()}
+</div>

package/dist/components/portal/Portal.svelte.d.ts

@@ -0,0 +1,46 @@
+import { type Snippet } from 'svelte';
+import type { ClassNameValue } from 'tailwind-merge';
+export type PortalProps = {
+    target?: HTMLElement;
+    prepend?: boolean;
+    children?: Snippet;
+    class?: ClassNameValue;
+};
+/**
+ * Portal
+ *
+ * A utility component that renders its children outside the current DOM hierarchy by prepending them into a target DOM element (e.g., `document.body`). Useful for modals, drawers, toasts, and overlays to avoid z-index and layout conflicts.
+ *
+ * ## Props
+ *
+ * - `target?`: `HTMLElement` — The DOM node to render the content into. Defaults to `document.body` if not provided. Useful for directing content to a specific container.
+ * - `prepend?: boolean` — If true (default), the portal will be prepended to the target node. If false, it will be appended. This controls the render order of layered content.
+ * - `children?`: `Snippet` — The Svelte children content to render inside the portal. Use `{@render}` to render dynamic fragments.
+ * - `class?`: `ClassNameValue` — Tailwind CSS or custom classes applied to the outer container div.
+ *
+ * ## Behavior
+ *
+ * - On mount, a new `div` is created and prepended to the `target`.
+ * - On destroy, the element is removed from the DOM.
+ * - Children are rendered via `{@render children?.()}` to support dynamic content blocks.
+ *
+ * ## Usage
+ *
+ * ```svelte
+ * <script lang="ts">
+ * import Portal from './Portal.svelte';
+ * let show = true;
+ * </script>
+ *
+ * {#if show}
+ * <Portal>
+ *   <div class="absolute top-0 left-0 h-screen w-screen bg-black/50 z-50">
+ *     <div class="bg-white p-6 rounded shadow">Hello from Portal!</div>
+ *   </div>
+ * </Portal>
+ * {/if}
+ * ```
+ */
+declare const Portal: import("svelte").Component<PortalProps, {}, "">;
+type Portal = ReturnType<typeof Portal>;
+export default Portal;

package/dist/components/portal/index.d.ts

@@ -0,0 +1 @@
+export { default as Portal } from './Portal.svelte';

package/dist/components/portal/index.js

@@ -0,0 +1 @@
+export { default as Portal } from './Portal.svelte';

package/dist/configs/config.d.ts

@@ -0,0 +1,3 @@
+export declare const config: {
+    transitionDuration: number;
+};

package/dist/configs/config.js

@@ -0,0 +1,3 @@
+export const config = {
+    transitionDuration: 150,
+};

package/dist/index.d.ts

@@ -8,10 +8,12 @@ export * from './components/overlay/index.js';
 export * from './components/radio/index.js';
 export * from './components/checkbox/index.js';
 export * from './components/tab-navigation/index.js';
+export * from './components/portal/index.js';
 export * from './actions/disable-scroll.js';
 export * from './actions/on-keydown.js';
 export * from './actions/lock-scroll.js';
 export * from './actions/scroll-to.js';
+export * from './actions/stop-interaction.js';
 export * from './modules/fetch-client.js';
 export * from './modules/api-proxy.js';
 export * from './modules/crypto.js';

package/dist/index.js

@@ -10,10 +10,12 @@ export * from './components/overlay/index.js';
 export * from './components/radio/index.js';
 export * from './components/checkbox/index.js';
 export * from './components/tab-navigation/index.js';
+export * from './components/portal/index.js';
 export * from './actions/disable-scroll.js';
 export * from './actions/on-keydown.js';
 export * from './actions/lock-scroll.js';
 export * from './actions/scroll-to.js';
+export * from './actions/stop-interaction.js';
 export * from './modules/fetch-client.js';
 export * from './modules/api-proxy.js';
 export * from './modules/crypto.js';

package/package.json

@@ -5,7 +5,7 @@
     "type": "git",
     "url": "git+https://github.com/hashrytech/quick-components-kit.git"
   },
-  "version": "0.15.7",
+  "version": "0.16.0",
   "license": "MIT",
   "author": "Hashry Tech",
   "files": [