From 8e9d4626084cc81577b8a068afc902cd3325c85f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 17 Oct 2025 00:13:10 +0000 Subject: [PATCH 1/5] Initial plan From f764cfe5e819fe37c32b124b0edba133fb44ee5e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 17 Oct 2025 00:18:32 +0000 Subject: [PATCH 2/5] Update README with comprehensive documentation Co-authored-by: oliverkuchies <11084292+oliverkuchies@users.noreply.github.com> --- README.md | 367 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 364 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 128668c..d9e4dad 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,365 @@ -# ugc-widget-utils -Utilities to help you with building your next widget! +# @stackla/widget-utils -Enjoy! \ No newline at end of file +> ๐ŸŽจ 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) +[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC) + +## ๐Ÿš€ 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 }) => ( +
+ {title} +

{title}

+
+); +``` + +### 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 + +## ๐Ÿ“„ License + +ISC + +## ๐Ÿ”— 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 Stackla \ No newline at end of file From c73e670726f7453b79e78c466a30512eeee00688 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 17 Oct 2025 00:20:22 +0000 Subject: [PATCH 3/5] Apply prettier formatting to README Co-authored-by: oliverkuchies <11084292+oliverkuchies@users.noreply.github.com> --- README.md | 100 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 60 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index d9e4dad..d45934c 100644 --- a/README.md +++ b/README.md @@ -41,16 +41,16 @@ pnpm add @stackla/widget-utils ### Basic Widget Setup ```typescript -import { loadWidget } from '@stackla/widget-utils'; +import { loadWidget } from "@stackla/widget-utils" // Initialize a widget with default settings const sdk = await loadWidget({ features: { showTitle: true, preloadImages: true, - addNewTilesAutomatically: true, + addNewTilesAutomatically: true } -}); +}) ``` ### Using JSX for Widget Components @@ -69,26 +69,21 @@ const TileComponent = ({ title, image }) => ( ### Handlebars Templates ```typescript -import { renderHTMLWithTemplates } from '@stackla/widget-utils/handlebars'; +import { renderHTMLWithTemplates } from "@stackla/widget-utils/handlebars" -const html = await renderHTMLWithTemplates( - tileTemplate, - layoutTemplate, - tiles, - options -); +const html = await renderHTMLWithTemplates(tileTemplate, layoutTemplate, tiles, options) ``` ### Infinite Scrolling with React ```typescript -import { useInfiniteScroller } from '@stackla/widget-utils/hooks'; +import { useInfiniteScroller } from "@stackla/widget-utils/hooks" function MyWidget() { const { loadMore, hasMore } = useInfiniteScroller({ onLoadMore: fetchMoreTiles - }); - + }) + // Your component logic } ``` @@ -98,35 +93,43 @@ function MyWidget() { ### 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 @@ -137,18 +140,22 @@ Handlebars template engine with custom helpers designed for widget rendering. - `{{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 @@ -156,48 +163,60 @@ Pre-built component utilities for common widget patterns. - 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 @@ -207,24 +226,24 @@ Bundled distribution for direct browser usage. ```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 - }; + 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 - }; + } } ``` @@ -233,50 +252,50 @@ interface WidgetSettings { ### Creating a Gallery Widget ```typescript -import { loadWidget } from '@stackla/widget-utils'; -import { renderTilesWithTemplate } from '@stackla/widget-utils/handlebars'; +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 tiles = await sdk.getTiles() const html = await renderTilesWithTemplate(tileTemplate, tiles, { - wid: 'your-widget-id' -}); + wid: "your-widget-id" +}) ``` ### Using Swiper Extension ```typescript -import { initSwiper } from '@stackla/widget-utils/extensions/swiper'; +import { initSwiper } from "@stackla/widget-utils/extensions/swiper" -const swiper = initSwiper('.swiper-container', { +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'; +import { embed } from "@stackla/widget-utils/embed" await embed({ - widgetId: 'your-widget-id', - root: document.getElementById('widget-container'), - environment: 'production', + widgetId: "your-widget-id", + root: document.getElementById("widget-container"), + environment: "production", dataProperties: { // Custom data attributes } -}); +}) ``` ## ๐Ÿ—๏ธ Project Structure @@ -337,6 +356,7 @@ 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 @@ -362,4 +382,4 @@ ISC --- -Built with โค๏ธ by Stackla \ No newline at end of file +Built with โค๏ธ by Stackla From d958d48959bc9d06062e7280670f8f4539c24e3c Mon Sep 17 00:00:00 2001 From: Oliver Kucharzewski Date: Fri, 17 Oct 2025 11:41:05 +1100 Subject: [PATCH 4/5] Update README to remove license and change attribution Removed license section and updated attribution. --- README.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/README.md b/README.md index d45934c..66a40a2 100644 --- a/README.md +++ b/README.md @@ -362,10 +362,6 @@ Contributions are welcome! Please ensure your code: - Includes proper TypeScript types - Is documented with JSDoc comments where appropriate -## ๐Ÿ“„ License - -ISC - ## ๐Ÿ”— Links - [NPM Package](https://www.npmjs.com/package/@stackla/widget-utils) @@ -382,4 +378,4 @@ ISC --- -Built with โค๏ธ by Stackla +Built with โค๏ธ by Nosto From 0ce301558fdfc2df075fc1d985387df4dca8459b Mon Sep 17 00:00:00 2001 From: Oliver Kucharzewski Date: Fri, 17 Oct 2025 11:41:16 +1100 Subject: [PATCH 5/5] Update README.md --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 66a40a2..4fc8863 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,6 @@ > ๐ŸŽจ 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) -[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC) ## ๐Ÿš€ Overview