@lerx/promise-modal 0.10.4 → 0.11.0

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

@@ -0,0 +1,207 @@
+# Hooks Reference
+
+## useModal
+
+Returns modal handlers tied to component lifecycle.
+
+```typescript
+import { useModal } from '@lerx/promise-modal';
+
+function MyComponent() {
+  const modal = useModal({
+    ForegroundComponent: CustomForeground, // Hook-level config
+  });
+
+  const handleShow = async () => {
+    await modal.alert({ title: 'Alert', content: 'Hello!' });
+  };
+
+  return <button onClick={handleShow}>Open Modal</button>;
+}
+```
+
+**Key Feature**: Modals are automatically cleaned up when component unmounts.
+
+| Feature | Static Handlers | useModal Hook |
+|------|------------|-------------|
+| Lifecycle | Independent | Tied to component |
+| Cleanup | Manual | Auto on unmount |
+| Usage Location | Anywhere | Inside React components |
+
+---
+
+## useActiveModalCount
+
+Returns the count of currently active modals.
+
+```typescript
+import { useActiveModalCount } from '@lerx/promise-modal';
+
+function App() {
+  const count = useActiveModalCount();
+  // Optional: Filter with condition
+  const alertCount = useActiveModalCount(
+    (modal) => modal?.type === 'alert' && modal.visible
+  );
+
+  return <div>Open modals: {count}</div>;
+}
+```
+
+**Parameters**:
+- `filter?: (modal: ModalNode) => boolean` - Optional filter function
+
+**Returns**: `number` - Active modal count
+
+---
+
+## useModalAnimation
+
+Provides animation state callbacks.
+
+```typescript
+import { useModalAnimation } from '@lerx/promise-modal';
+
+function CustomForeground({ visible, children }) {
+  const ref = useRef(null);
+
+  useModalAnimation(visible, {
+    onVisible: () => ref.current?.classList.add('visible'),
+    onHidden: () => ref.current?.classList.remove('visible'),
+  });
+
+  return <div ref={ref}>{children}</div>;
+}
+```
+
+**Parameters**:
+- `visible: boolean` - Modal visibility state
+- `callbacks: { onVisible?: () => void; onHidden?: () => void }` - State change callbacks
+
+**Timing**:
+- `onVisible`: When modal starts becoming visible
+- `onHidden`: When modal starts becoming hidden
+
+---
+
+## useModalDuration
+
+Returns modal animation duration.
+
+```typescript
+import { useModalDuration } from '@lerx/promise-modal';
+
+function Component() {
+  const { duration, milliseconds } = useModalDuration();
+  // duration: '300ms', milliseconds: 300
+
+  return <div>Animation duration: {duration}</div>;
+}
+```
+
+**Returns**:
+```typescript
+{
+  duration: string;      // CSS format (e.g., '300ms')
+  milliseconds: number;  // Number format (e.g., 300)
+}
+```
+
+---
+
+## useDestroyAfter
+
+Automatically destroys modal after specified time.
+
+```typescript
+import { useDestroyAfter } from '@lerx/promise-modal';
+
+function ToastComponent({ id, duration }) {
+  useDestroyAfter(id, duration);
+  return <div>Toast message</div>;
+}
+```
+
+**Parameters**:
+- `id: number` - Modal ID
+- `duration: number | string` - Wait time before destruction
+
+**Use Case**: Auto-removal in toast notification implementation
+
+---
+
+## useSubscribeModal
+
+Subscribes to modal state changes.
+
+```typescript
+import { useSubscribeModal } from '@lerx/promise-modal';
+
+function ModalTracker({ modal }) {
+  const version = useSubscribeModal(modal);
+
+  useEffect(() => {
+    console.log('Modal state changed');
+  }, [version]);
+
+  return <div>Version: {version}</div>;
+}
+```
+
+**Parameters**:
+- `modal: ModalNode` - Modal node to subscribe to
+
+**Returns**: `number` - Modal version (increments on state change)
+
+**Purpose**: React to modal internal state changes
+
+---
+
+## useModalOptions
+
+Returns modal option configuration.
+
+```typescript
+import { useModalOptions } from '@lerx/promise-modal';
+
+function ModalDebugInfo() {
+  const options = useModalOptions();
+
+  return (
+    <div>
+      <p>Duration: {options.duration}</p>
+      <p>Backdrop: {options.backdrop}</p>
+      <p>Manual Destroy: {options.manualDestroy ? 'Yes' : 'No'}</p>
+    </div>
+  );
+}
+```
+
+**Returns**: `ModalOptions` - Current modal's options object
+
+**Included Properties**:
+- `duration` - Animation duration
+- `backdrop` - Background configuration
+- `manualDestroy` - Manual destruction mode
+- `closeOnBackdropClick` - Close on backdrop click
+- Other modal configuration options
+
+---
+
+## useModalBackdrop
+
+Returns only modal background configuration.
+
+```typescript
+import { useModalBackdrop } from '@lerx/promise-modal';
+
+function BackdropInfo() {
+  const backdrop = useModalBackdrop();
+
+  return <p>Current backdrop: {backdrop}</p>;
+}
+```
+
+**Returns**: `ModalBackground` - Background configuration value
+
+**Purpose**: Lighter alternative to `useModalOptions` when only backdrop configuration is needed

package/docs/claude/skills/expert/knowledge/type-definitions.md

@@ -0,0 +1,172 @@
+# Type Definitions
+
+## ModalFrameProps
+
+Props passed to Foreground/Background components.
+
+```typescript
+interface ModalFrameProps<Context = any, B = any> {
+  id: number;
+  type: 'alert' | 'confirm' | 'prompt';
+  alive: boolean;
+  visible: boolean;
+  initiator: string;
+  manualDestroy: boolean;
+  closeOnBackdropClick: boolean;
+  background?: ModalBackground<B>;
+  onConfirm: () => void;
+  onClose: () => void;
+  onChange: (value: any) => void;
+  onDestroy: () => void;
+  onChangeOrder: Function;
+  context: Context;
+  children: ReactNode;
+}
+```
+
+**Property Descriptions**:
+
+| Property | Type | Description |
+|------|------|------|
+| `id` | `number` | Unique modal ID |
+| `type` | `'alert' \| 'confirm' \| 'prompt'` | Modal type |
+| `alive` | `boolean` | Whether modal exists in DOM |
+| `visible` | `boolean` | Whether modal is visible on screen |
+| `initiator` | `string` | Identifier of modal creator |
+| `manualDestroy` | `boolean` | Whether manual destruction mode is enabled |
+| `closeOnBackdropClick` | `boolean` | Whether close on backdrop click is enabled |
+| `background` | `ModalBackground<B>` | Background configuration |
+| `onConfirm` | `() => void` | Confirm button click handler |
+| `onClose` | `() => void` | Modal close handler |
+| `onChange` | `(value: any) => void` | Value change handler (for prompt) |
+| `onDestroy` | `() => void` | Modal destruction handler |
+| `onChangeOrder` | `Function` | Modal order change handler |
+| `context` | `Context` | User-defined context data |
+| `children` | `ReactNode` | Modal internal content |
+
+---
+
+## FooterComponentProps
+
+Props for custom footer components.
+
+```typescript
+interface FooterComponentProps {
+  type: 'alert' | 'confirm' | 'prompt';
+  onConfirm: (value?: any) => void;
+  onClose: () => void;
+  onCancel?: () => void;
+  disabled?: boolean;
+  footer?: FooterOptions;
+  context: any;
+}
+```
+
+**Property Descriptions**:
+
+| Property | Type | Description |
+|------|------|------|
+| `type` | `'alert' \| 'confirm' \| 'prompt'` | Modal type |
+| `onConfirm` | `(value?: any) => void` | Confirm button click handler |
+| `onClose` | `() => void` | Close button click handler |
+| `onCancel` | `() => void` | Cancel button click handler (optional) |
+| `disabled` | `boolean` | Confirm button disabled state (optional) |
+| `footer` | `FooterOptions` | Footer configuration options (optional) |
+| `context` | `any` | User-defined context data |
+
+**Usage Example**:
+
+```typescript
+const CustomFooter: React.FC<FooterComponentProps> = ({
+  type,
+  onConfirm,
+  onClose,
+  disabled,
+  footer,
+}) => {
+  return (
+    <div className="custom-footer">
+      {type !== 'alert' && (
+        <button onClick={onClose}>
+          {footer?.cancel || 'Cancel'}
+        </button>
+      )}
+      <button onClick={() => onConfirm()} disabled={disabled}>
+        {footer?.confirm || 'Confirm'}
+      </button>
+    </div>
+  );
+};
+```
+
+---
+
+## PromptInputProps<T>
+
+Props for prompt input components.
+
+```typescript
+interface PromptInputProps<T> {
+  value?: T;
+  defaultValue?: T;
+  onChange: (value: T | undefined) => void;
+  onConfirm: () => void;
+  onCancel: () => void;
+  context: any;
+}
+```
+
+**Property Descriptions**:
+
+| Property | Type | Description |
+|------|------|------|
+| `value` | `T` | Current input value (optional) |
+| `defaultValue` | `T` | Default input value (optional) |
+| `onChange` | `(value: T \| undefined) => void` | Value change handler |
+| `onConfirm` | `() => void` | Confirm action handler (e.g., Enter key) |
+| `onCancel` | `() => void` | Cancel action handler (e.g., Escape key) |
+| `context` | `any` | User-defined context data |
+
+**Usage Examples**:
+
+```typescript
+// Simple text input
+const TextInput: React.FC<PromptInputProps<string>> = ({
+  value = '',
+  onChange,
+  onConfirm,
+}) => {
+  return (
+    <input
+      type="text"
+      value={value}
+      onChange={(e) => onChange(e.target.value)}
+      onKeyPress={(e) => e.key === 'Enter' && onConfirm()}
+    />
+  );
+};
+
+// Complex object input
+interface FormData {
+  name: string;
+  email: string;
+}
+
+const FormInput: React.FC<PromptInputProps<FormData>> = ({
+  value = { name: '', email: '' },
+  onChange,
+}) => {
+  return (
+    <div>
+      <input
+        value={value.name}
+        onChange={(e) => onChange({ ...value, name: e.target.value })}
+      />
+      <input
+        value={value.email}
+        onChange={(e) => onChange({ ...value, email: e.target.value })}
+      />
+    </div>
+  );
+};
+```