modal-system 1.0.0

package/README.md

@@ -0,0 +1,386 @@
+# modal-system
+
+Type-safe modal management for React. One provider, one hook, full TypeScript autocomplete for modal names and their data shapes.
+
+Supports **shadcn/ui** (Radix UI or Base UI) and **DaisyUI** out of the box.
+
+---
+
+## Installation
+
+```bash
+bun add modal-system
+# or
+npm install modal-system
+# or
+yarn add modal-system
+```
+
+**Peer dependencies** — make sure these are already in your project:
+
+```bash
+bun add react react-dom
+```
+
+---
+
+## Quick start
+
+### 1. Run the interactive init
+
+```bash
+bunx modal-system init
+# or
+npx modal-system init
+```
+
+The CLI will ask:
+- Which UI library? (`shadcn/ui` or `DaisyUI`)
+- If shadcn — which primitive? (`Radix UI` or `Base UI`)
+- Where to put the files? (default: `src/modals`)
+
+It generates a ready-to-use `modals/` folder:
+
+```
+src/modals/
+  index.ts          ← MODALS registry + useModal hook
+  modals.ts         ← data interfaces for each modal
+  ConfirmModal.tsx  ← starter confirm modal component
+  Modal.tsx         ← (DaisyUI only) native <dialog> primitive
+```
+
+### 2. Wrap your app with `ModalProvider`
+
+```tsx
+// src/main.tsx  (or app/layout.tsx for Next.js)
+import { ModalProvider } from "modal-system";
+import { MODALS } from "./modals";
+
+export default function App() {
+  return (
+    <ModalProvider modals={MODALS}>
+      <YourApp />
+    </ModalProvider>
+  );
+}
+```
+
+### 3. Open a modal from any component
+
+```tsx
+import { useModal } from "./modals";
+
+export function DeleteButton({ userId }: { userId: string }) {
+  const { openModal } = useModal();
+
+  return (
+    <button
+      onClick={() =>
+        openModal("confirm", {
+          title: "Delete account?",
+          description: "This action cannot be undone.",
+          actionText: "Delete",
+          isActionButtonDestructive: true,
+          onConfirm: () => deleteUser(userId),
+        })
+      }
+    >
+      Delete
+    </button>
+  );
+}
+```
+
+Both `"confirm"` and the data object are **fully typed** — wrong keys or wrong value types are caught at compile time.
+
+---
+
+## Adding a new modal
+
+**1. Add a data interface in `modals.ts`:**
+
+```ts
+export interface DeleteUserModalData {
+  userId: string;
+  userName: string;
+  onDeleted?: () => void;
+}
+```
+
+**2. Create the component:**
+
+```tsx
+// src/modals/DeleteUserModal.tsx
+import type { BaseModalProps } from "modal-system";
+import type { DeleteUserModalData } from "./modals";
+
+export function DeleteUserModal({ isOpen, onClose, data }: BaseModalProps<DeleteUserModalData>) {
+  // data?.userId, data?.userName, data?.onDeleted
+  return (/* your JSX */);
+}
+```
+
+**3. Register it in `index.ts`:**
+
+```ts
+import { DeleteUserModal } from "./DeleteUserModal";
+
+export const MODALS = defineModals({
+  confirm:    ConfirmModal,
+  deleteUser: DeleteUserModal, // ← add here
+});
+```
+
+`openModal("deleteUser", { userId: "123", userName: "Alice" })` is now fully typed.
+
+---
+
+## API
+
+### `<ModalProvider modals={MODALS}>`
+
+Renders all registered modals and exposes the modal context. Must wrap the part of the tree where `useModal` is called.
+
+| Prop     | Type             | Description                          |
+|----------|------------------|--------------------------------------|
+| `modals` | `ModalRegistry`  | Object mapping name → component      |
+| `children` | `ReactNode`    | Your application tree                |
+
+### `createModalHook(MODALS)`
+
+Factory that returns a typed `useModal` hook bound to your specific registry. **Import `useModal` from your own `modals/index.ts`**, not from `modal-system` directly.
+
+```ts
+export const useModal = createModalHook(MODALS);
+```
+
+### `useModal()`
+
+Returns:
+
+| Field        | Type                                          | Description              |
+|--------------|-----------------------------------------------|--------------------------|
+| `openModal`  | `(name: K, data?: DataMap[K]) => void`        | Open a modal by name     |
+| `closeModal` | `() => void`                                  | Close the active modal   |
+
+### `defineModals(modals)`
+
+Identity helper that enforces `ModalRegistry` type constraint and enables inference.
+
+```ts
+export const MODALS = defineModals({
+  confirm: ConfirmModal,
+});
+```
+
+### `BaseModalProps<TData>`
+
+Base props interface that every modal component should extend.
+
+```ts
+interface BaseModalProps<TData = unknown> {
+  isOpen:  boolean;
+  onClose: () => void;
+  data?:   TData;
+}
+```
+
+---
+
+## Supported UI libraries
+
+| Template         | Primitive             | Install                                  |
+|------------------|-----------------------|------------------------------------------|
+| `shadcn/ui`      | Radix UI              | `npx shadcn@latest add dialog button`    |
+| `shadcn/ui`      | Base UI               | `bun add @base-ui-components/react`      |
+| `DaisyUI`        | Native `<dialog>`     | `bun add daisyui` + Tailwind CSS         |
+
+---
+
+## TypeScript
+
+The library ships with bundled `.d.ts` declarations — no `@types/*` package needed.
+
+Exported types:
+
+```ts
+import type { BaseModalProps, ModalRegistry, ModalDataMap } from "modal-system";
+```
+
+---
+
+---
+
+# modal-system (на русском)
+
+Типобезопасное управление модальными окнами для React. Один провайдер, один хук, полный автокомплит TypeScript для имён модалок и форм данных.
+
+Поддерживает **shadcn/ui** (Radix UI или Base UI) и **DaisyUI**.
+
+---
+
+## Установка
+
+```bash
+bun add modal-system
+# или
+npm install modal-system
+```
+
+**Peer-зависимости** — должны уже быть в вашем проекте:
+
+```bash
+bun add react react-dom
+```
+
+---
+
+## Быстрый старт
+
+### 1. Запустите интерактивную инициализацию
+
+```bash
+bunx modal-system init
+# или
+npx modal-system init
+```
+
+CLI задаст вопросы:
+- Какая UI-библиотека? (`shadcn/ui` или `DaisyUI`)
+- Если shadcn — какой примитив? (`Radix UI` или `Base UI`)
+- Куда положить файлы? (по умолчанию: `src/modals`)
+
+Будет создана папка `modals/` с готовыми файлами:
+
+```
+src/modals/
+  index.ts          ← реестр MODALS и хук useModal
+  modals.ts         ← интерфейсы данных для каждой модалки
+  ConfirmModal.tsx  ← стартовый компонент подтверждения
+  Modal.tsx         ← (только DaisyUI) примитив на базе <dialog>
+```
+
+### 2. Оберните приложение в `ModalProvider`
+
+```tsx
+// src/main.tsx  (или app/layout.tsx для Next.js)
+import { ModalProvider } from "modal-system";
+import { MODALS } from "./modals";
+
+export default function App() {
+  return (
+    <ModalProvider modals={MODALS}>
+      <YourApp />
+    </ModalProvider>
+  );
+}
+```
+
+### 3. Откройте модалку из любого компонента
+
+```tsx
+import { useModal } from "./modals";
+
+export function DeleteButton({ userId }: { userId: string }) {
+  const { openModal } = useModal();
+
+  return (
+    <button
+      onClick={() =>
+        openModal("confirm", {
+          title: "Удалить аккаунт?",
+          description: "Это действие нельзя отменить.",
+          actionText: "Удалить",
+          isActionButtonDestructive: true,
+          onConfirm: () => deleteUser(userId),
+        })
+      }
+    >
+      Удалить
+    </button>
+  );
+}
+```
+
+И `"confirm"`, и объект данных **полностью типизированы** — неверные ключи или типы значений обнаруживаются на этапе компиляции.
+
+---
+
+## Добавление новой модалки
+
+**1. Добавьте интерфейс данных в `modals.ts`:**
+
+```ts
+export interface DeleteUserModalData {
+  userId: string;
+  userName: string;
+  onDeleted?: () => void;
+}
+```
+
+**2. Создайте компонент:**
+
+```tsx
+// src/modals/DeleteUserModal.tsx
+import type { BaseModalProps } from "modal-system";
+import type { DeleteUserModalData } from "./modals";
+
+export function DeleteUserModal({ isOpen, onClose, data }: BaseModalProps<DeleteUserModalData>) {
+  // data?.userId, data?.userName, data?.onDeleted
+  return (/* ваш JSX */);
+}
+```
+
+**3. Зарегистрируйте в `index.ts`:**
+
+```ts
+import { DeleteUserModal } from "./DeleteUserModal";
+
+export const MODALS = defineModals({
+  confirm:    ConfirmModal,
+  deleteUser: DeleteUserModal, // ← добавить здесь
+});
+```
+
+Теперь `openModal("deleteUser", { userId: "123", userName: "Алиса" })` полностью типизирован.
+
+---
+
+## API
+
+### `<ModalProvider modals={MODALS}>`
+
+Рендерит все зарегистрированные модалки и предоставляет контекст. Должен оборачивать ту часть дерева, где вызывается `useModal`.
+
+### `createModalHook(MODALS)`
+
+Фабрика, возвращающая типизированный хук `useModal`, привязанный к вашему реестру. **Импортируйте `useModal` из своего `modals/index.ts`**, а не из `modal-system` напрямую.
+
+### `useModal()`
+
+| Поле         | Тип                                           | Описание                        |
+|--------------|-----------------------------------------------|---------------------------------|
+| `openModal`  | `(name: K, data?: DataMap[K]) => void`        | Открыть модалку по имени        |
+| `closeModal` | `() => void`                                  | Закрыть активную модалку        |
+
+### `BaseModalProps<TData>`
+
+Базовый интерфейс пропсов, который должен использовать каждый компонент модалки.
+
+```ts
+interface BaseModalProps<TData = unknown> {
+  isOpen:  boolean;
+  onClose: () => void;
+  data?:   TData;
+}
+```
+
+---
+
+## Поддерживаемые UI-библиотеки
+
+| Шаблон           | Примитив              | Установка                                |
+|------------------|-----------------------|------------------------------------------|
+| `shadcn/ui`      | Radix UI              | `npx shadcn@latest add dialog button`    |
+| `shadcn/ui`      | Base UI               | `bun add @base-ui-components/react`      |
+| `DaisyUI`        | Нативный `<dialog>`   | `bun add daisyui` + Tailwind CSS         |