epic-modals 0.0.4

package/LICENSE

@@ -0,0 +1,93 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor's trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+**control** means ownership of substantially all the assets of an entity, or the
+power to direct its management and policies by vote, contract, or otherwise.
+Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,287 @@
+# epic-modals
+
+A stunning modal library with macOS-style animations, drag, resize, and dock. Supports Svelte 5, React, and vanilla JavaScript.
+
+**[Live Demo](https://epicmodals.eu)**
+
+## Installation
+
+```bash
+npm install epic-modals
+```
+
+## Quick Start
+
+### React
+
+```tsx
+import { ModalProvider, Modal, Dock, useModal } from 'epic-modals/react';
+import 'epic-modals/styles';
+
+// Modal IDs can be symbols (recommended) or strings
+const MODAL_ID = Symbol('my-modal');
+
+function App() {
+  return (
+    <ModalProvider>
+      <MyComponent />
+      <Dock />
+    </ModalProvider>
+  );
+}
+
+function MyComponent() {
+  const { open, close } = useModal(MODAL_ID);
+
+  return (
+    <>
+      <button onClick={(e) => open(e.currentTarget)}>Open</button>
+
+      <Modal id={MODAL_ID} title="Hello World" maxWidth="480px"
+        footer={<button onClick={close}>Close</button>}
+      >
+        <p>Your content here!</p>
+      </Modal>
+    </>
+  );
+}
+```
+
+### Svelte 5
+
+```svelte
+<script lang="ts">
+  import { ModalProvider, Modal, Dock, openModal, closeModal } from 'epic-modals/svelte';
+  import 'epic-modals/styles';
+
+  // Modal IDs can be symbols (recommended) or strings
+  const MODAL_ID = Symbol('my-modal');
+</script>
+
+<ModalProvider>
+  <button onclick={(e) => openModal(MODAL_ID, e.currentTarget)}>Open</button>
+
+  <Modal id={MODAL_ID} title="Hello World" maxWidth="480px">
+    <p>Your content here!</p>
+
+    {#snippet footer()}
+      <button onclick={() => closeModal(MODAL_ID)}>Close</button>
+    {/snippet}
+  </Modal>
+
+  <Dock />
+</ModalProvider>
+```
+
+### Vanilla JavaScript
+
+```js
+import { init, createModal, openModal, closeModal } from 'epic-modals/vanilla';
+import 'epic-modals/styles';
+
+// Modal IDs can be symbols (recommended) or strings
+const MODAL_ID = Symbol('my-modal');
+
+// Initialize library (creates backdrop + dock automatically)
+init();
+
+createModal({
+  id: MODAL_ID,
+  title: 'Hello World',
+  content: '<p>Your content here!</p>',
+  footer: '<button id="close-btn">Close</button>',
+  maxWidth: '480px',
+});
+
+document.querySelector('#close-btn').onclick = () => closeModal(MODAL_ID);
+document.querySelector('#open-btn').onclick = (e) => {
+  openModal(MODAL_ID, e.currentTarget);
+};
+```
+
+## Features
+
+- **Dock** - Minimized modals appear in a customizable dock
+- **Minimize/Restore** - Smooth genie animation to/from dock
+- **Resize** - 8-direction resize handles
+- **Drag** - Drag modals by header
+- **Parent-Child** - Modals can spawn child modals
+- **Attention Effect** - Shake animation to grab user attention
+- **Focus Trap** - Tab key stays within modal
+- **macOS Style** - Traffic light buttons (close, minimize, maximize)
+- **Theming** - Light/dark themes + full CSS variable customization
+
+## Hooks & Functions
+
+### React
+
+```tsx
+import { useModal, useModals } from 'epic-modals/react';
+
+const MODAL_ID = Symbol('my-modal');
+
+function MyComponent() {
+  const {
+    open,           // (element) => void - Open modal
+    close,          // () => void - Close modal
+    minimize,       // () => void - Minimize to dock
+    restore,        // () => void - Restore from dock
+    shake,          // () => void - Trigger attention effect
+    bringToFront,   // () => void - Focus modal (z-index)
+    isOpen,         // boolean
+    isMinimized,    // boolean
+    isRegistered,   // boolean
+  } = useModal(MODAL_ID);
+
+  return (
+    <button onClick={(e) => open(e.currentTarget)}>Open</button>
+  );
+}
+```
+
+### Svelte
+
+```svelte
+<script lang="ts">
+  import { useModal } from 'epic-modals/svelte';
+
+  const MODAL_ID = Symbol('my-modal');
+  const modal = useModal(MODAL_ID);
+
+  // modal.open(element)   - Open modal
+  // modal.close()         - Close modal
+  // modal.minimize()      - Minimize to dock
+  // modal.restore()       - Restore from dock
+  // modal.shake()         - Trigger attention effect
+  // modal.bringToFront()  - Focus modal (z-index)
+  // modal.isOpen()        - Check if open
+  // modal.isRegistered()  - Check if registered
+</script>
+
+<button onclick={(e) => modal.open(e.currentTarget)}>Open</button>
+```
+
+### Vanilla
+
+```js
+import {
+  openModal, closeModal, minimizeModal, restoreModal,
+  triggerAttention, bringToFront, isModalOpen
+} from 'epic-modals/vanilla';
+
+const MODAL_ID = Symbol('my-modal');
+
+openModal(MODAL_ID, buttonElement);
+closeModal(MODAL_ID);
+minimizeModal(MODAL_ID);
+restoreModal(MODAL_ID);
+triggerAttention(MODAL_ID);  // Shake effect
+bringToFront(MODAL_ID);
+isModalOpen(MODAL_ID);       // Returns boolean
+```
+
+## Parent-Child Modals
+
+```tsx
+// React
+import { useModal } from 'epic-modals/react';
+
+const PARENT_ID = Symbol('parent');
+const CHILD_ID = Symbol('child');
+
+function Parent() {
+  const parent = useModal(PARENT_ID);
+  const child = useModal(CHILD_ID);
+
+  return (
+    <Modal id={PARENT_ID} title="Parent">
+      <button onClick={(e) => child.openAsChild(PARENT_ID, e.currentTarget)}>
+        Open Child
+      </button>
+    </Modal>
+  );
+}
+```
+
+```svelte
+<!-- Svelte -->
+<script>
+  import { openChildModal } from 'epic-modals/svelte';
+
+  const PARENT_ID = Symbol('parent');
+  const CHILD_ID = Symbol('child');
+</script>
+
+<Modal id={PARENT_ID} title="Parent">
+  <button onclick={(e) => openChildModal(CHILD_ID, PARENT_ID, e.currentTarget)}>
+    Open Child
+  </button>
+</Modal>
+
+<Modal id={CHILD_ID} title="Child">
+  <p>I'm a child modal!</p>
+</Modal>
+```
+
+## Configuration
+
+```tsx
+<ModalProvider config={{
+  features: {
+    dock: true,           // Enable dock for minimized modals
+    minimize: true,       // Enable minimize button
+    resize: true,         // Enable resize handles
+    drag: true,           // Enable drag to move
+    focusTrap: true,      // Enable focus trapping
+    animations: true,     // Enable animations
+    backdrop: true,       // Enable backdrop overlay
+  },
+  dock: {
+    position: 'bottom',   // 'left' | 'right' | 'bottom'
+    labelMode: 'hidden',  // 'hidden' | 'beside' | 'below'
+  },
+  animations: {
+    open: 400,
+    close: 250,
+    minimize: 500,
+    restore: 400,
+  },
+  appearance: {
+    headerLayout: 'macos', // 'macos' | 'windows' | 'none'
+  },
+}}>
+```
+
+## Theming
+
+```css
+/* Import base styles */
+@import 'epic-modals/styles';
+
+/* Optional: Import a theme */
+@import 'epic-modals/styles/themes/light';
+@import 'epic-modals/styles/themes/dark';
+```
+
+Override CSS variables for custom theming:
+
+```css
+:root {
+  --modal-bg: #ffffff;
+  --modal-border-radius: 12px;
+  --modal-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
+  --modal-title-color: #1a1a1a;
+
+  /* Traffic lights */
+  --modal-btn-close: #ff5f57;
+  --modal-btn-minimize: #febc2e;
+  --modal-btn-maximize: #28c840;
+
+  /* Dock */
+  --modal-dock-bg: linear-gradient(to bottom, #f8f9fa, #f0f1f3);
+}
+```
+
+## License
+
+[Elastic License 2.0](https://www.elastic.co/licensing/elastic-license) - Free for commercial use, but you cannot offer it as a hosted service or redistribute it as your own product.

package/dist/core/config.svelte.d.ts

@@ -0,0 +1,85 @@
+import { DockPosition, DockLabelMode, ModalFeatures, AppearanceConfig } from './types';
+export type { ModalFeatures, AppearanceConfig } from './types';
+export interface DockConfig {
+    /** Dock position: left, right, bottom, or free-floating */
+    position: DockPosition;
+    /** Label display mode */
+    labelMode: DockLabelMode;
+    /** Enable reordering items in dock */
+    enableReorder: boolean;
+    /** Allow dock to be dragged freely (when position is 'free') */
+    enableFreeDrag: boolean;
+}
+export interface AnimationDurations {
+    /** Open animation duration */
+    open: number;
+    /** Close animation duration */
+    close: number;
+    /** Minimize animation duration */
+    minimize: number;
+    /** Restore animation duration */
+    restore: number;
+}
+export interface ZIndexConfig {
+    /** Base z-index for modals */
+    base: number;
+    /** Z-index for dock */
+    dock: number;
+    /** Z-index for toasts */
+    toast: number;
+}
+export interface ParentChildConfig {
+    /** Movement mode: 'realtime' (parent moves instantly) or 'animated' (parent animates after drag) */
+    movementMode: 'realtime' | 'animated';
+    /** Animation duration in milliseconds for animated movement mode */
+    animationDuration: number;
+}
+export interface PositioningConfig {
+    /**
+     * Strategy for placing new modals:
+     * - 'centered': Always center new modals (default, current behavior)
+     * - 'smart': Find position with least overlap with existing modals
+     */
+    strategy: 'centered' | 'smart';
+    /** Minimum gap between modals when using smart positioning (default: 16) */
+    modalGap: number;
+    /** CSS selectors for elements that modals should avoid overlapping (e.g., navigation bars, toolbars) */
+    avoidElements: string[];
+}
+export interface ModalLibraryConfig {
+    features: ModalFeatures;
+    dock: DockConfig;
+    animations: AnimationDurations;
+    appearance: AppearanceConfig;
+    zIndex: ZIndexConfig;
+    parentChild: ParentChildConfig;
+    positioning: PositioningConfig;
+    /** Portal target selector or element */
+    portalTarget: string | HTMLElement;
+}
+export declare const defaultConfig: ModalLibraryConfig;
+/**
+ * Get the config version for tracking changes in $derived
+ */
+export declare function getConfigVersion(): number;
+/**
+ * Get the current library configuration
+ */
+export declare function getConfig(): ModalLibraryConfig;
+/**
+ * Set the library configuration (called by ModalProvider)
+ */
+export declare function setConfig(config: Partial<ModalLibraryConfig>): void;
+/**
+ * Reset to default configuration
+ */
+export declare function resetConfig(): void;
+/**
+ * Deep merge configuration objects
+ */
+export declare function mergeConfig(base: ModalLibraryConfig, override: Partial<ModalLibraryConfig>): ModalLibraryConfig;
+/**
+ * Check if a feature is enabled
+ */
+export declare function isFeatureEnabled(feature: keyof ModalFeatures): boolean;
+//# sourceMappingURL=config.svelte.d.ts.map

package/dist/core/index.d.ts

@@ -0,0 +1,6 @@
+export * from './types';
+export * from './config.svelte';
+export * from './state.svelte';
+export * from './stacking.svelte';
+export * from './viewport';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/stacking.svelte.d.ts

@@ -0,0 +1,19 @@
+import { StackingLayerName } from './types';
+/**
+ * Initialize the z-index counter from config
+ */
+export declare function initializeStacking(): void;
+/**
+ * Get the next available z-index for a new modal
+ * Increments by 2 to leave room for floating elements (dropdowns, tooltips) at +1
+ */
+export declare function acquireModalZIndex(): number;
+/**
+ * Get a specific z-index for a layer
+ */
+export declare function getLayerZIndex(layer: StackingLayerName): number;
+/**
+ * Reset the z-index counter (useful for testing)
+ */
+export declare function resetStacking(): void;
+//# sourceMappingURL=stacking.svelte.d.ts.map