@lerx/promise-modal 0.10.4 → 0.11.0

package/docs/claude/skills/expert/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: promise-modal-expert
+description: "@lerx/promise-modal library expert. Guide users on React-based Promise modal utilities (alert, confirm, prompt), architecture, and customization."
+user-invocable: false
+---
+
+# Promise Modal Expert Skill
+
+## Role
+
+You are an expert on the `@lerx/promise-modal` library. Help users effectively implement modal dialogs using React-based Promise modal utilities.
+
+## Core Knowledge
+
+### Library Overview
+
+`@lerx/promise-modal` is a universal modal utility for React that provides:
+- Promise-based modal interactions (alert, confirm, prompt)
+- Usage both inside and outside React components
+- High-level component customization
+- Automatic lifecycle management
+- Programmatic modal cancellation via AbortSignal
+
+### Architecture
+
+The library uses a layered architecture:
+
+1. **Core Layer** - Main API functions (alert, confirm, prompt)
+2. **Application Layer** - ModalManager singleton for lifecycle and DOM management
+3. **Bootstrap Layer** - ModalProvider component for initialization
+4. **Provider Layer** - Context providers for configuration and state
+5. **Component Layer** - Customizable UI components
+
+### Configuration Priority
+
+Configuration is applied hierarchically, with lower levels overriding higher levels:
+
+```
+Provider Config (Lowest) < Hook Config < Handler Config (Highest)
+```
+
+| Level | Location | Description |
+|------|------|------|
+| **Provider** | `ModalProvider` props | App-wide default configuration |
+| **Hook** | `useModal(config)` | Component-level configuration |
+| **Handler** | `alert/confirm/prompt(options)` | Individual modal configuration |
+
+---
+
+## Basic Usage Patterns
+
+### Pattern 1: Basic Static API
+
+Static functions usable outside React components.
+
+```typescript
+import { alert, confirm, prompt } from '@lerx/promise-modal';
+
+// Simple alert
+await alert({
+  title: 'Alert',
+  content: 'Task completed successfully.',
+  subtype: 'success'
+});
+
+// Confirmation modal
+if (await confirm({
+  title: 'Confirm',
+  content: 'Are you sure you want to delete this?'
+})) {
+  // User confirmed
+}
+
+// Prompt input
+const name = await prompt({
+  title: 'Enter Name',
+  defaultValue: '',
+  Input: ({ value, onChange }) => (
+    <input
+      value={value}
+      onChange={(e) => onChange(e.target.value)}
+      placeholder="Enter your name"
+    />
+  ),
+});
+```
+
+### Pattern 2: Component-Scoped with useModal
+
+Tied to component lifecycle, automatically cleaned up on unmount.
+
+```typescript
+import { useModal } from '@lerx/promise-modal';
+
+function MyComponent() {
+  const modal = useModal({
+    ForegroundComponent: CustomForeground, // Hook-level config
+  });
+
+  const handleDelete = async () => {
+    if (await modal.confirm({ content: 'Delete this item?' })) {
+      // Delete logic
+    }
+  };
+
+  return <button onClick={handleDelete}>Delete</button>;
+}
+```
+
+**Key Differences**:
+
+| Feature | Static Handlers | useModal Hook |
+|------|------------|-------------|
+| Lifecycle | Independent | Tied to component |
+| Cleanup | Manual | Auto on unmount |
+| Usage Location | Anywhere | Inside React components |
+
+---
+
+## Troubleshooting
+
+### Modal Not Appearing
+
+1. Verify `ModalProvider` is at app root
+2. (For manual mode) Ensure `initialize()` was called
+3. Check for z-index and CSS conflicts
+
+### Modal Not Closing
+
+1. Check `manualDestroy` option
+2. Verify `closeOnBackdropClick` configuration
+3. Ensure `onClose` or `onConfirm` is being called
+
+### Animation Not Working
+
+1. Verify `useModalAnimation` hook is used correctly
+2. Check CSS transition properties
+3. Confirm Provider's `duration` option
+
+### prompt Type Errors
+
+1. Specify generic type: `prompt<string>(...)`
+2. Ensure `defaultValue` matches type
+3. Check `onChange` handler type
+
+---
+
+## Best Practices
+
+1. **Place ModalProvider at Root**: Wrap entire app
+2. **Use useModal in Components**: For automatic cleanup
+3. **Use Static API in Utilities**: For non-component code
+4. **Customize at Provider Level**: Set global styles once
+5. **Use subtype Semantically**: info, success, warning, error
+6. **Handle Promises Properly**: Always await or handle rejection
+7. **Keep Modal Content Simple**: Avoid complex state in modals
+8. **Test Accessibility**: Verify keyboard navigation
+9. **Leverage AbortSignal**: When programmatic modal closure is needed
+
+---
+
+## Knowledge Files Reference
+
+For detailed API, advanced patterns, and type definitions, refer to these knowledge files:
+
+| File | Contents |
+|------|------|
+| `knowledge/api-reference.md` | Static functions (alert, confirm, prompt) and ModalProvider detailed API |
+| `knowledge/hooks-reference.md` | Complete reference for 8 hooks (useModal, useActiveModalCount, etc.) |
+| `knowledge/advanced-patterns.md` | Advanced patterns including AbortSignal, toast, nested modals, custom anchors |
+| `knowledge/type-definitions.md` | TypeScript interface definitions (ModalFrameProps, etc.) |

package/docs/claude/skills/expert/knowledge/advanced-patterns.md

@@ -0,0 +1,294 @@
+# Advanced Patterns
+
+## Pattern 3: Modal Cancellation with AbortSignal
+
+Programmatically cancel modals.
+
+```typescript
+import { alert } from '@lerx/promise-modal';
+import { useState } from 'react';
+
+function ManualAbortControl() {
+  const [controller, setController] = useState<AbortController | null>(null);
+
+  const handleOpen = () => {
+    const newController = new AbortController();
+    setController(newController);
+
+    alert({
+      title: 'Manually Cancelable',
+      content: 'Click "Cancel" button to close this modal.',
+      signal: newController.signal,
+      closeOnBackdropClick: false,
+    }).then(() => {
+      setController(null);
+    });
+  };
+
+  const handleAbort = () => {
+    if (controller) {
+      controller.abort();
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={handleOpen} disabled={!!controller}>Open Modal</button>
+      <button onClick={handleAbort} disabled={!controller}>Cancel Modal</button>
+    </div>
+  );
+}
+```
+
+**Use Cases**:
+- Timer-based auto-close
+- Close modals in response to external events
+- Programmatic modal control
+
+---
+
+## Pattern 4: Toast Implementation
+
+Implement auto-dismissing toast notifications.
+
+```typescript
+import { alert, useModalAnimation, useModalDuration, useDestroyAfter } from '@lerx/promise-modal';
+import { useRef, useEffect } from 'react';
+
+const ToastForeground = ({ id, visible, children, onClose, onDestroy }) => {
+  const ref = useRef(null);
+  const { duration } = useModalDuration();
+
+  // Auto-close after 3 seconds
+  useEffect(() => {
+    const timer = setTimeout(onClose, 3000);
+    return () => clearTimeout(timer);
+  }, [onClose]);
+
+  // Handle animations
+  useModalAnimation(visible, {
+    onVisible: () => ref.current?.classList.add('visible'),
+    onHidden: () => ref.current?.classList.remove('visible'),
+  });
+
+  // Remove from DOM after animation
+  useDestroyAfter(id, duration);
+
+  return <div ref={ref}>{children}</div>;
+};
+
+// Pattern for removing previous toast
+let onDestroyPrevToast: () => void;
+
+export const toast = (message: ReactNode, duration = 1250) => {
+  onDestroyPrevToast?.(); // Remove previous toast
+
+  return alert({
+    content: message,
+    ForegroundComponent: (props) => {
+      onDestroyPrevToast = props.onDestroy;
+      return <ToastForeground {...props} />;
+    },
+    footer: false,
+    dimmed: false,
+    closeOnBackdropClick: false,
+  });
+};
+```
+
+**Usage Example**:
+```typescript
+toast('Task completed successfully!');
+toast('An error occurred.', 2000);
+```
+
+---
+
+## Pattern 5: Nested Modals
+
+Display multiple modals sequentially in steps.
+
+```typescript
+import { alert, confirm, prompt } from '@lerx/promise-modal';
+
+async function multiStepProcess() {
+  // Step 1: Start confirmation
+  if (!await confirm({
+    title: 'Start?',
+    content: 'Do you want to continue?'
+  })) return;
+
+  // Step 2: Collect user info
+  const name = await prompt({
+    title: 'Name',
+    defaultValue: '',
+    Input: ({ value, onChange }) => (
+      <input
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        placeholder="Enter your name"
+      />
+    ),
+  });
+
+  if (!name) return;
+
+  // Step 3: Completion notification
+  await alert({
+    title: 'Complete',
+    content: `Hello, ${name}!`,
+    subtype: 'success',
+  });
+}
+```
+
+**Notes**:
+- Each modal opens after the previous one closes
+- Natural flow through Promise chaining
+- Entire process stops if user cancels
+
+---
+
+## Pattern 6: Custom Anchor
+
+Render modals inside a specific DOM element.
+
+```typescript
+import { useInitializeModal } from '@lerx/promise-modal';
+import { useRef, useEffect } from 'react';
+
+function CustomAnchorExample() {
+  const { initialize, portal } = useInitializeModal({ mode: 'manual' });
+  const containerRef = useRef(null);
+
+  useEffect(() => {
+    if (containerRef.current) {
+      initialize(containerRef.current);
+    }
+  }, [initialize]);
+
+  return (
+    <div>
+      <h1>Custom Modal Container</h1>
+      <div
+        ref={containerRef}
+        style={{
+          position: 'relative',
+          height: 500,
+          border: '2px solid #ccc',
+        }}
+      />
+      {portal}
+    </div>
+  );
+}
+```
+
+**Use Cases**:
+- Restrict modals to specific area
+- Manage multiple modal containers
+- Use modals inside iframe or Shadow DOM
+
+---
+
+## Pattern 7: Complex Form Input
+
+Collect complex form data using prompt.
+
+```typescript
+import { prompt } from '@lerx/promise-modal';
+
+interface UserForm {
+  name: string;
+  email: string;
+  age: number;
+  agree: boolean;
+}
+
+async function collectUserInfo() {
+  const userInfo = await prompt<UserForm>({
+    title: 'Enter User Information',
+    defaultValue: {
+      name: '',
+      email: '',
+      age: 18,
+      agree: false,
+    },
+    Input: ({ value, onChange }) => (
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 10 }}>
+        <input
+          type="text"
+          placeholder="Name"
+          value={value.name}
+          onChange={(e) => onChange({ ...value, name: e.target.value })}
+        />
+        <input
+          type="email"
+          placeholder="Email"
+          value={value.email}
+          onChange={(e) => onChange({ ...value, email: e.target.value })}
+        />
+        <input
+          type="number"
+          placeholder="Age"
+          value={value.age}
+          onChange={(e) => onChange({ ...value, age: Number(e.target.value) })}
+        />
+        <label>
+          <input
+            type="checkbox"
+            checked={value.agree}
+            onChange={(e) => onChange({ ...value, agree: e.target.checked })}
+          />
+          I agree to the terms
+        </label>
+      </div>
+    ),
+    disabled: (value) => !value.name || !value.email || !value.agree,
+  });
+
+  console.log('Collected info:', userInfo);
+}
+```
+
+**Key Points**:
+- Type-safe handling of complex objects
+- Validation with `disabled` function
+- Confirm button disabled until all fields are filled
+
+---
+
+## Pattern 8: Conditional Modal Styles
+
+Display different styled modals based on situation.
+
+```typescript
+import { alert } from '@lerx/promise-modal';
+
+type NotificationType = 'info' | 'success' | 'warning' | 'error';
+
+function notify(type: NotificationType, message: string) {
+  return alert({
+    title: {
+      info: 'Information',
+      success: 'Success',
+      warning: 'Warning',
+      error: 'Error',
+    }[type],
+    content: message,
+    subtype: type,
+    footer: {
+      confirm: 'OK',
+    },
+  });
+}
+
+// Usage examples
+notify('success', 'Data saved successfully.');
+notify('error', 'Network error occurred.');
+```
+
+**Advantages**:
+- Consistent notification interface
+- Automatic styling by type
+- Reusable utility function

package/docs/claude/skills/expert/knowledge/api-reference.md

@@ -0,0 +1,175 @@
+# API Reference
+
+## Static Functions
+
+### `alert(options)`
+
+Opens a simple notification modal.
+
+```typescript
+import { alert } from '@lerx/promise-modal';
+
+await alert({
+  title: 'Alert',
+  content: 'Task completed successfully.',
+  subtype: 'success', // 'info' | 'success' | 'warning' | 'error'
+  dimmed: true,
+  closeOnBackdropClick: true,
+  manualDestroy: false,
+  signal: abortController.signal, // Optional AbortSignal
+});
+```
+
+**Options**:
+
+| Option | Type | Description |
+|------|------|------|
+| `title` | `ReactNode` | Modal title |
+| `subtitle` | `ReactNode` | Subtitle below title |
+| `content` | `ReactNode \| ComponentType` | Modal content |
+| `subtype` | `'info' \| 'success' \| 'warning' \| 'error'` | Modal styling type |
+| `dimmed` | `boolean` | Whether to darken background |
+| `closeOnBackdropClick` | `boolean` | Close on backdrop click |
+| `manualDestroy` | `boolean` | Manual destruction mode |
+| `duration` | `number \| string` | Animation duration |
+| `background` | `ModalBackground` | Background configuration |
+| `footer` | `Function \| Object \| false` | Footer configuration |
+| `ForegroundComponent` | `ComponentType` | Custom foreground component |
+| `BackgroundComponent` | `ComponentType` | Custom background component |
+| `signal` | `AbortSignal` | AbortSignal for modal cancellation |
+
+**Return Value**: `Promise<void>`
+
+---
+
+### `confirm(options)`
+
+Opens a confirmation modal for user decision.
+
+```typescript
+import { confirm } from '@lerx/promise-modal';
+
+const result = await confirm({
+  title: 'Confirm',
+  content: 'Are you sure you want to delete this?',
+  footer: {
+    confirm: 'Delete',
+    cancel: 'Cancel',
+  },
+});
+
+if (result) {
+  console.log('User confirmed');
+} else {
+  console.log('User cancelled');
+}
+```
+
+**Options**: Same options available as `alert()`
+
+**Return Value**: `Promise<boolean>` - `true` if confirmed, `false` if cancelled
+
+---
+
+### `prompt<T>(options)`
+
+Opens a prompt modal to collect user input.
+
+```typescript
+import { prompt } from '@lerx/promise-modal';
+
+// Simple text input
+const name = await prompt<string>({
+  title: 'Enter Name',
+  defaultValue: '',
+  Input: ({ value, onChange }) => (
+    <input
+      value={value}
+      onChange={(e) => onChange(e.target.value)}
+      placeholder="Enter your name"
+    />
+  ),
+  disabled: (value) => value.length < 2,
+});
+
+// Complex object input
+const userInfo = await prompt<{ name: string; age: number }>({
+  title: 'User Information',
+  defaultValue: { name: '', age: 0 },
+  Input: ({ value, onChange }) => (
+    <div>
+      <input
+        value={value.name}
+        onChange={(e) => onChange({ ...value, name: e.target.value })}
+      />
+      <input
+        type="number"
+        value={value.age}
+        onChange={(e) => onChange({ ...value, age: Number(e.target.value) })}
+      />
+    </div>
+  ),
+});
+```
+
+**Additional Options**:
+
+| Option | Type | Description |
+|------|------|------|
+| `Input` | `(props: PromptInputProps<T>) => ReactNode` | Input component (required) |
+| `defaultValue` | `T` | Default input value |
+| `disabled` | `(value: T) => boolean` | Condition to disable confirm button |
+| `returnOnCancel` | `boolean` | Whether to return default value on cancel |
+
+**Return Value**: `Promise<T>`
+
+---
+
+## ModalProvider
+
+Main Provider component for initialization.
+
+```typescript
+import { ModalProvider } from '@lerx/promise-modal';
+import { useLocation } from 'react-router-dom';
+
+function App() {
+  return (
+    <ModalProvider
+      usePathname={useLocation}  // Router integration (auto-close on path change)
+      ForegroundComponent={CustomForeground}
+      BackgroundComponent={CustomBackground}
+      TitleComponent={CustomTitle}
+      SubtitleComponent={CustomSubtitle}
+      ContentComponent={CustomContent}
+      FooterComponent={CustomFooter}
+      options={{
+        duration: '200ms',
+        backdrop: 'rgba(0, 0, 0, 0.35)',
+        manualDestroy: true,
+        closeOnBackdropClick: true,
+      }}
+      context={{
+        theme: 'light',
+        locale: 'en-US',
+      }}
+    >
+      <YourApp />
+    </ModalProvider>
+  );
+}
+```
+
+**Props**:
+
+| Prop | Type | Description |
+|------|------|------|
+| `usePathname` | `() => { pathname: string }` | Router path hook (closes modals on path change) |
+| `ForegroundComponent` | `ComponentType<ModalFrameProps>` | Custom foreground component |
+| `BackgroundComponent` | `ComponentType<ModalFrameProps>` | Custom background component |
+| `TitleComponent` | `ComponentType` | Custom title component |
+| `SubtitleComponent` | `ComponentType` | Custom subtitle component |
+| `ContentComponent` | `ComponentType` | Custom content component |
+| `FooterComponent` | `ComponentType<FooterComponentProps>` | Custom footer component |
+| `options` | `ModalOptions` | Global modal options |
+| `context` | `any` | User-defined context data |