Embeddable React Widget

Мощный standalone виджет на React с полноценным TypeScript API. Работает в любой среде - React, Vue, Svelte или чистый JavaScript. Включает все зависимости (React, ReactDOM).

✨ Возможности

• 🚀 Standalone - никаких внешних зависимостей
• 🌍 Универсальный - работает везде (React, Vue, Svelte, чистый JS)
• 🎨 Темы - light/dark/auto с кастомными стилями
• 🔗 Множественные экземпляры - создавайте сколько угодно виджетов
• 📡 Система событий - подписывайтесь на изменения
• 🎯 TypeScript - полная типизация API
• 🐛 Debug режим - инструменты для отладки

📦 Установка

npm install embeddable-react-widget-askdmnklm

🚀 Быстрый старт

Простое использование (Legacy API)

import { initApp } from 'embeddable-react-widget-askdmnklm';
import 'embeddable-react-widget-askdmnklm/dist/widget.css';

// Создает виджет с настройками по умолчанию
const widget = initApp('my-container');

Расширенное использование (New API)

import { 
  createWidget, 
  type WidgetConfig 
} from 'embeddable-react-widget-askdmnklm';
import 'embeddable-react-widget-askdmnklm/dist/widget.css';

const config: WidgetConfig = {
  containerId: 'my-container',
  title: 'Мой виджет',
  theme: 'dark',
  initialCount: 10,
  showCounter: true,
  onCountChange: (count) => console.log('Count:', count),
  customStyles: {
    backgroundColor: '#ff6b6b',
    borderRadius: '12px'
  }
};

const widget = createWidget(config);

🎯 Полное API

Основные функции

// Простая инициализация (обратная совместимость)
function initApp(id: string): WidgetInstance | null;

// Расширенная инициализация
function createWidget(config: WidgetConfig): WidgetInstance | null;

// Управление виджетами
function destroyWidget(containerId: string): boolean;
function getActiveWidgets(): string[];
function destroyAllWidgets(): number;

// Информация
function getWidgetInfo(): WidgetInfo;

WidgetInstance API

interface WidgetInstance {
  destroy(): void;                                    // Уничтожить виджет
  getCount(): number;                                 // Получить счетчик
  setCount(count: number): void;                      // Установить счетчик
  updateConfig(config: Partial<WidgetConfig>): void;  // Обновить конфиг
}

Конфигурация

interface WidgetConfig {
  containerId: string;                    // ID контейнера (обязательно)
  theme?: 'light' | 'dark' | 'auto';     // Тема
  title?: string;                         // Заголовок
  showCounter?: boolean;                  // Показать счетчик (по умолчанию: true)
  initialCount?: number;                  // Начальное значение (по умолчанию: 0)
  customStyles?: React.CSSProperties;    // Кастомные стили
  onCountChange?: (count: number) => void; // Callback изменения
}

📡 Система событий

import { addEventListener, removeEventListener } from 'embeddable-react-widget-askdmnklm';

// Подписка на события
addEventListener('widget:init', (data) => {
  console.log('Виджет создан:', data.containerId);
});

addEventListener('widget:count-change', (data) => {
  console.log(`Счетчик: ${data.previous} → ${data.count}`);
});

addEventListener('widget:destroy', (data) => {
  console.log('Виджет уничтожен:', data.containerId);
});

Доступные события

interface WidgetEvents {
  'widget:init': { containerId: string };
  'widget:count-change': { count: number; previous: number };
  'widget:destroy': { containerId: string };
}

🎨 Примеры использования

В React приложении

import React, { useEffect, useRef } from 'react';
import { createWidget, type WidgetInstance } from 'embeddable-react-widget-askdmnklm';
import 'embeddable-react-widget-askdmnklm/dist/widget.css';

function MyComponent() {
  const widgetRef = useRef<WidgetInstance | null>(null);

  useEffect(() => {
    widgetRef.current = createWidget({
      containerId: 'widget-container',
      title: 'React Widget',
      theme: 'auto',
      onCountChange: (count) => console.log('Count changed:', count)
    });

    return () => {
      widgetRef.current?.destroy();
    };
  }, []);

  const updateTheme = () => {
    widgetRef.current?.updateConfig({ theme: 'dark' });
  };

  return (
    <div>
      <button onClick={updateTheme}>Switch to Dark</button>
      <div id="widget-container"></div>
    </div>
  );
}

В Vue приложении

<template>
  <div>
    <button @click="toggleTheme">Toggle Theme</button>
    <div id="vue-widget"></div>
  </div>
</template>

<script setup>
import { onMounted, onUnmounted, ref } from 'vue';
import { createWidget } from 'embeddable-react-widget-askdmnklm';
import 'embeddable-react-widget-askdmnklm/dist/widget.css';

const widget = ref(null);
const isDark = ref(false);

onMounted(() => {
  widget.value = createWidget({
    containerId: 'vue-widget',
    title: 'Vue Integration',
    theme: 'light'
  });
});

onUnmounted(() => {
  widget.value?.destroy();
});

const toggleTheme = () => {
  isDark.value = !isDark.value;
  widget.value?.updateConfig({ 
    theme: isDark.value ? 'dark' : 'light' 
  });
};
</script>

В чистом JavaScript/HTML

<!DOCTYPE html>
<html>
<head>
    <link rel="stylesheet" href="node_modules/embeddable-react-widget-askdmnklm/dist/widget.css">
</head>
<body>
    <div id="js-widget"></div>
    <button onclick="updateWidget()">Update Widget</button>
    
    <script src="node_modules/embeddable-react-widget-askdmnklm/dist/widget.umd.js"></script>
    <script>
        let widget = EmbeddableWidget.createWidget({
            containerId: 'js-widget',
            title: 'JavaScript Widget',
            theme: 'auto',
            initialCount: 42,
            onCountChange: (count) => console.log('Count:', count)
        });

        function updateWidget() {
            widget.updateConfig({
                title: 'Updated Widget!',
                customStyles: { backgroundColor: '#4CAF50' }
            });
        }
    </script>
</body>
</html>

🐛 Debug и разработка

import { debug } from 'embeddable-react-widget-askdmnklm';

// Получить все активные виджеты
console.log(debug.getInstances());

// Получить список событий
console.log(debug.getEventListeners());

// Информация о библиотеке
console.log(debug.info());

📁 Структура пакета

dist/
├── widget.es.js      # ES модули (910KB) - для современных bundler'ов
├── widget.umd.js     # UMD версия (560KB) - для браузера через <script>
├── widget.css        # Стили (1.4KB)
├── widget.d.ts       # TypeScript типы
└── *.map             # Source maps

🔧 Разработка

npm run dev     # Режим разработки
npm run build   # Сборка
npm run lint    # Линтинг
npm run preview # Предпросмотр

📝 Лицензия

MIT

🚀 Миграция с простого API

Если вы использовали простое API:

// Старый способ
initApp('my-container');

// Новый способ (больше возможностей)
createWidget({
  containerId: 'my-container',
  title: 'My Widget',
  theme: 'dark',
  initialCount: 10
});

Старое API по-прежнему работает для обратной совместимости!