Update README.md with comprehensive documentation and module reference

README.md

@@ -1,4 +1,380 @@
-# ugc-widget-utils
-Utilities to help you with building your next widget!
+# @stackla/widget-utils
 
-Enjoy!
+> 🎨 A comprehensive TypeScript utility library for building powerful User-Generated Content (UGC) widgets
+
+[![npm version](https://img.shields.io/npm/v/@stackla/widget-utils.svg)](https://www.npmjs.com/package/@stackla/widget-utils)
+
+## 🚀 Overview
+
+`@stackla/widget-utils` is a feature-rich library that provides everything you need to build, customize, and deploy UGC widgets. Whether you're creating a simple content gallery or a complex interactive widget with carousels, infinite scrolling, and dynamic templates, this library has you covered.
+
+## ✨ Features
+
+- **🎯 TypeScript First** - Fully typed API for excellent IDE support and type safety
+- **🎨 Flexible Templating** - Support for Handlebars templates with custom helpers
+- **⚛️ JSX Support** - Build widgets using JSX syntax without React
+- **🎪 Widget Loading** - Automated widget initialization and lifecycle management
+- **🔄 Infinite Scrolling** - Built-in React hooks for seamless content loading
+- **📦 Modular Architecture** - Import only what you need with tree-shakeable exports
+- **🎠 Extension Support** - Includes Swiper carousel integration out of the box
+- **🎨 CSS Variables** - Dynamic theming and styling support
+- **📡 Event System** - Comprehensive event handling for widget interactions
+- **🔌 Embed Utilities** - Easy widget embedding for both v2 and v3 widgets
+
+## 📦 Installation
+
+```bash
+npm install @stackla/widget-utils
+```
+
+```bash
+yarn add @stackla/widget-utils
+```
+
+```bash
+pnpm add @stackla/widget-utils
+```
+
+## 🎯 Quick Start
+
+### Basic Widget Setup
+
+```typescript
+import { loadWidget } from "@stackla/widget-utils"
+
+// Initialize a widget with default settings
+const sdk = await loadWidget({
+  features: {
+    showTitle: true,
+    preloadImages: true,
+    addNewTilesAutomatically: true
+  }
+})
+```
+
+### Using JSX for Widget Components
+
+```typescript
+import { jsx } from '@stackla/widget-utils/jsx';
+
+const TileComponent = ({ title, image }) => (
+  <div className="tile">
+    <img src={image} alt={title} />
+    <h3>{title}</h3>
+  </div>
+);
+```
+
+### Handlebars Templates
+
+```typescript
+import { renderHTMLWithTemplates } from "@stackla/widget-utils/handlebars"
+
+const html = await renderHTMLWithTemplates(tileTemplate, layoutTemplate, tiles, options)
+```
+
+### Infinite Scrolling with React
+
+```typescript
+import { useInfiniteScroller } from "@stackla/widget-utils/hooks"
+
+function MyWidget() {
+  const { loadMore, hasMore } = useInfiniteScroller({
+    onLoadMore: fetchMoreTiles
+  })
+
+  // Your component logic
+}
+```
+
+## 📚 Module Reference
+
+### Core Modules
+
+#### `@stackla/widget-utils` (Main Export)
+
+The primary entry point providing widget loading, core types, events, and library utilities.
+
+**Key Exports:**
+
+- `loadWidget()` - Initialize and configure widgets
+- `ISdk` - TypeScript interface for widget SDK
+- Widget lifecycle hooks and event handlers
+
+#### `@stackla/widget-utils/types`
+
+Comprehensive TypeScript type definitions for widgets, tiles, components, and services.
+
+**Includes:**
+
+- `Widget`, `Tile`, `Placement` - Core data types
+- `WidgetOptions`, `WidgetSettings` - Configuration types
+- Service interfaces for tiles, events, and widgets
+- Component types for static content, products, and UGC
+
+#### `@stackla/widget-utils/jsx`
+
+JSX-to-HTML runtime that lets you write components using JSX syntax without React.
+
+**Features:**
+
+- Lightweight JSX transformation
+- Event handler support
+- Ref support for DOM access
+- Type-safe JSX elements
+
+#### `@stackla/widget-utils/handlebars`
+
+Handlebars template engine with custom helpers designed for widget rendering.
+
+**Custom Helpers:**
+
+- `{{tile}}` - Render tile components
+- `{{ifEquals}}` - Conditional rendering
+- `{{lazy}}` - Lazy loading support
+- `{{join}}` - Array joining
+- `{{ifAutoPlayVideo}}` - Video autoplay detection
+- `{{ifHasProductTags}}` - Product tag checking
+- `{{ifHasPublicTags}}` - Public tag checking
+- `{{tagFallbackUsername}}` - Username fallback logic
+
+#### `@stackla/widget-utils/libs`
+
+Core library utilities for widget features and functionality.
+
+**Includes:**
+
+- CSS variable management
+- Widget feature toggles
+- Layout utilities
+- Tile manipulation helpers
+
+#### `@stackla/widget-utils/components`
+
+Pre-built component utilities for common widget patterns.
+
+**Available Components:**
+
+- Static content components
+- Product display components
+- Share menu components
+- Add-to-cart components
+- UGC tile components
+
+#### `@stackla/widget-utils/extensions`
+
+Widget extensions for enhanced functionality.
+
+**Current Extensions:**
+
+- **Swiper** - Carousel/slider integration
+
+#### `@stackla/widget-utils/extensions/swiper`
+
+Full Swiper carousel integration for creating image/content sliders.
+
+**Features:**
+
+- Automatic initialization
+- Responsive configuration
+- Touch/swipe support
+- Navigation and pagination
+
+#### `@stackla/widget-utils/hooks`
+
+React hooks for common widget patterns.
+
+**Available Hooks:**
+
+- `useInfiniteScroller` - Infinite scroll implementation
+
+#### `@stackla/widget-utils/events`
+
+Event system for widget lifecycle and user interactions.
+
+**Event Types:**
+
+- Widget initialization events
+- Tile interaction events
+- Load more events
+- User action events
+
+#### `@stackla/widget-utils/embed`
+
+Utilities for embedding widgets into web pages.
+
+**Features:**
+
+- Support for v2 and v3 widgets
+- Environment configuration (staging/production)
+- Auto-detection of widget version
+- Shadow DOM support
+
+#### `@stackla/widget-utils/templates`
+
+Template utilities and pre-built templates.
+
+#### `@stackla/widget-utils/bundle`
+
+Bundled distribution for direct browser usage.
+
+## 🔧 Configuration
+
+### Widget Settings
+
+```typescript
+interface WidgetSettings {
+  features?: {
+    showTitle?: boolean // Display widget title
+    preloadImages?: boolean // Preload images for performance
+    disableWidgetIfNotEnabled?: boolean // Auto-disable on config
+    addNewTilesAutomatically?: boolean // Auto-add new tiles
+    handleLoadMore?: boolean // Enable load more functionality
+    hideBrokenImages?: boolean // Hide broken image tiles
+    loadTileContent?: boolean // Load tile content dynamically
+    loadTimephrase?: boolean // Load time phrases
+  }
+  callbacks?: {
+    // Custom callback functions
+  }
+  templates?: {
+    // Custom templates
+  }
+  config?: {
+    // Additional configuration
+  }
+}
+```
+
+## 🎨 Examples
+
+### Creating a Gallery Widget
+
+```typescript
+import { loadWidget } from "@stackla/widget-utils"
+import { renderTilesWithTemplate } from "@stackla/widget-utils/handlebars"
+
+const sdk = await loadWidget({
+  features: {
+    preloadImages: true,
+    hideBrokenImages: true
+  }
+})
+
+const tiles = await sdk.getTiles()
+const html = await renderTilesWithTemplate(tileTemplate, tiles, {
+  wid: "your-widget-id"
+})
+```
+
+### Using Swiper Extension
+
+```typescript
+import { initSwiper } from "@stackla/widget-utils/extensions/swiper"
+
+const swiper = initSwiper(".swiper-container", {
+  slidesPerView: 3,
+  spaceBetween: 30,
+  navigation: true,
+  pagination: {
+    clickable: true
+  }
+})
+```
+
+### Embedding a Widget
+
+```typescript
+import { embed } from "@stackla/widget-utils/embed"
+
+await embed({
+  widgetId: "your-widget-id",
+  root: document.getElementById("widget-container"),
+  environment: "production",
+  dataProperties: {
+    // Custom data attributes
+  }
+})
+```
+
+## 🏗️ Project Structure
+
+```
+src/
+├── constants.ts           # Global constants
+├── embed/                 # Widget embedding utilities
+├── events/                # Event system
+├── fonts.ts              # Font loading utilities
+├── handlebars/           # Handlebars templates and helpers
+├── hooks/                # React hooks
+├── index.ts              # Main entry point
+├── libs/                 # Core library utilities
+│   ├── components/       # Component utilities
+│   ├── css-variables.ts  # CSS variable management
+│   ├── extensions/       # Widget extensions
+│   ├── jsx-html.ts       # JSX runtime
+│   ├── tile.lib.ts       # Tile utilities
+│   ├── widget.features.ts # Widget features
+│   ├── widget.layout.ts   # Layout utilities
+│   └── widget.utils.ts    # Widget utilities
+├── styles/               # Style utilities
+├── types/                # TypeScript type definitions
+│   ├── components/       # Component types
+│   ├── core/            # Core types
+│   ├── services/        # Service types
+│   └── loader.ts        # Loader types
+└── widget-loader.ts      # Widget loader implementation
+```
+
+## 🧪 Development
+
+### Running Tests
+
+```bash
+npm test
+```
+
+### Building
+
+```bash
+npm run build
+```
+
+### Linting
+
+```bash
+npm run lint
+```
+
+### Type Checking
+
+```bash
+npm run typecheck
+```
+
+## 📝 Contributing
+
+Contributions are welcome! Please ensure your code:
+
+- Passes all tests (`npm test`)
+- Follows the linting rules (`npm run lint`)
+- Includes proper TypeScript types
+- Is documented with JSDoc comments where appropriate
+
+## 🔗 Links
+
+- [NPM Package](https://www.npmjs.com/package/@stackla/widget-utils)
+- [Repository](https://github.com/Stackla/widget-utils)
+- [Changelog](./CHANGELOG.md)
+
+## 🎯 Use Cases
+
+- **Social Media Galleries** - Display Instagram, Twitter, and other social feeds
+- **Product Showcases** - Feature user-generated product reviews and photos
+- **Event Coverage** - Aggregate and display event content from multiple sources
+- **Community Walls** - Create interactive community content displays
+- **Marketing Campaigns** - Build engaging campaign landing pages with UGC
+
+---
+
+Built with ❤️ by Nosto