npm package: @fluid-app/web-widgets
Description: This package provides web components for integrating Fluid into your website. It supports two distribution methods:
Latest version: 0.3.6

# Fluid Web Widgets

This package provides web components for integrating Fluid into your website. It supports two distribution methods:

1. **NPM Package** - For bundled applications
2. **CDN / Script Tag** - For direct inclusion in HTML

## Distribution Methods

### NPM Package Distribution

Use this method if you're building a modern JavaScript application with a bundler (webpack, Vite, etc.).

#### Installation

```bash
# Using npm
npm install @fluid-app/web-widgets

# Using yarn
yarn add @fluid-app/web-widgets

# Using pnpm
pnpm add @fluid-app/web-widgets
```

#### Usage

```javascript
// Import the components and styles
import { initializeFluid } from "@fluid-app/fluid";
import { registerWebComponents } from "@fluid-app/web-widgets";

import "@fluid-app/web-widgets/styles.css";

// Initialize Fluid SDK with your shop ID (server-side attribution)
initializeFluid({
  fluidShop: "your-shop-id",
});

// Or with attribution override - you can use any of these formats:
// Attribution by email
initializeFluid({
  fluidShop: "your-shop-id",
  attributionOverride: {
    email: "affiliate@example.com",
  },
});

// Attribution by username
initializeFluid({
  fluidShop: "your-shop-id",
  attributionOverride: {
    username: "influencer-username",
  },
});

// Attribution by share GUID
initializeFluid({
  fluidShop: "your-shop-id",
  attributionOverride: {
    share_guid: "abc123-def456-ghi789",
  },
});

// Attribution by Fluid rep ID
initializeFluid({
  fluidShop: "your-shop-id",
  attributionOverride: {
    fluid_rep_id: 12345,
  },
});

// Attribution by external ID
initializeFluid({
  fluidShop: "your-shop-id",
  attributionOverride: {
    external_id: "external-affiliate-id",
  },
});

// Register the web components
registerWebComponents();
```

Then use the components in your HTML:

```html
<fluid-cart-widget
  position="bottom-right"
  fluid-shop-display-name="Your Store Name"
></fluid-cart-widget>
```

### CDN / Script Tag Distribution

Use this method for direct inclusion in a website without a build step.

```html
<!-- Basic server-side attribution -->
<script
  id="fluid-cdn-script"
  src="https://assets.fluid.app/scripts/fluid-sdk/latest/web-widgets/index.js"
  data-fluid-shop="your-shop-id"
  data-fluid-api-base-url="https://api.your-custom-endpoint.com"
></script>

<!-- With attribution override -->
<script
  id="fluid-cdn-script"
  src="https://assets.fluid.app/scripts/fluid-sdk/latest/web-widgets/index.js"
  data-fluid-shop="your-shop-id"
  data-share-guid="your-affiliate-id"
></script>

<!-- Add the cart widget anywhere on your page -->
<fluid-cart-widget
  position="bottom-right"
  fluid-shop-display-name="Your Store Name"
></fluid-cart-widget>
```

#### Key Benefits of CDN Distribution

- **No NPM installation required** - Works with any HTML page
- **Automatic style injection** - No separate CSS file to include
- **Single script tag does everything** - Initializes SDK, loads styles, registers components
- **Server-side attribution** - Attribution calculated automatically server-side

#### Configuration Options

| Data Attribute          | Description                                                     | Required |
| ----------------------- | --------------------------------------------------------------- | -------- |
| data-fluid-shop         | Your Fluid shop identifier                                      | Yes      |
| data-share-guid         | Attribution override share GUID (overrides server-side)         | No       |
| data-fluid-api-base-url | Custom API endpoint URL for development or testing environments | No       |
| data-debug              | Enable debug mode (set to "true" to enable)                     | No       |

The `data-fluid-api-base-url` attribute allows you to specify a custom API endpoint for local development or testing against different environments. When not provided, the system uses the default production endpoint.

**Server-Side Attribution:** Attribution is now calculated server-side automatically based on the current page URL. The system detects page changes (including SPA navigation) and refreshes attribution data as needed. Use `data-share-guid` when you need to override this with a specific attribution value.

## Controlling the Cart

There are two ways to control the cart functionality:

### Declarative Controls (HTML)

Use data attributes for the simplest implementation:

```html
<button data-fluid-cart="open">Open Cart</button>
<button data-fluid-cart="close">Close Cart</button>
<button data-fluid-cart="toggle">Toggle Cart</button>
```

### JavaScript Controls

For programmatic control:

```javascript
// When using NPM package
import { closeCart, openCart, toggleCart } from "@fluid-app/react-widgets";

openCart();
closeCart();
toggleCart();

// When using CDN
window.fluidCart.open();
window.fluidCart.close();
window.fluidCart.toggle();
```

## Displaying Cart Count

You can easily display the current cart item count anywhere on your page by using an element with the ID `fluid-cart-count`. The SDK will automatically update this element whenever the cart changes.

```html
<!-- Simple cart count display -->
<span id="fluid-cart-count">0</span>

<!-- Cart count with styling -->
<div class="cart-icon">
  <i class="fas fa-shopping-cart"></i>
  <span class="badge" id="fluid-cart-count">0</span>
</div>
```

The cart count is updated automatically when:

- Items are added to the cart
- Items are removed from the cart
- Item quantities are updated
- The cart is cleared
- A new cart is created
- The cart is refreshed from the API

## Adding Products to Cart

### Declarative Product Controls (HTML)

Use data attributes to add products to cart without writing JavaScript:

```html
<!-- Add a single product (variant) to cart -->
<button data-fluid-add-to-cart="123456">Add to Cart</button>

<!-- Specify quantity -->
<button data-fluid-add-to-cart="123456" data-fluid-quantity="2">
  Add 2 to Cart
</button>

<!-- Add to cart and open cart drawer immediately -->
<button data-fluid-add-to-cart="123456" data-fluid-open-cart-after-add="true">
  Add to Cart and View
</button>

<!-- Add with subscription enabled -->
<button data-fluid-add-to-cart="123456" data-fluid-subscribe="true">
  Add with Subscription
</button>

<!-- Add multiple products with different subscription settings -->
<button
  data-fluid-add-to-cart="123456,789012"
  data-fluid-subscribe="true,false"
>
  Add Multiple Items
</button>

<!-- Combine subscription with quantity and cart opening -->
<button
  data-fluid-add-to-cart="123456"
  data-fluid-subscribe="true"
  data-fluid-quantity="2"
  data-fluid-open-cart-after-add="true"
>
  Add 2 with Subscription and View
</button>
```

### Adding Enrollment Packs

Enrollment packs can be added to the cart using data attributes:

```html
<!-- Add an enrollment pack to cart -->
<button data-fluid-add-enrollment-pack="42">Add Enrollment Pack</button>

<!-- Add enrollment pack and open cart drawer immediately -->
<button
  data-fluid-add-enrollment-pack="42"
  data-fluid-open-cart-after-add="true"
>
  Add Enrollment Pack and View
</button>
```

## Customizing Widget Styles

You can customize the widgets to match your brand's color scheme and typography using CSS variables:

```css
/* In your CSS file */
:root {
  --company-color: #3461ff; /* Replace with your brand color */
  --ff-body: "Your Custom Font", sans-serif; /* Your custom font */
}
```

Available customization variables:

- `--company-color`: Controls primary colors, accents, and highlights
- `--ff-body`: Sets the font family used throughout the widgets (falls back to system fonts if not specified)

## Available Components

### Cart Widget (`<fluid-cart-widget>`)

| Attribute/Property      | Type    | Default        | Description                                                                |
| ----------------------- | ------- | -------------- | -------------------------------------------------------------------------- |
| position                | string  | 'bottom-right' | Position on screen: 'top-left', 'top-right', 'bottom-left', 'bottom-right' |
| size                    | number  | 60             | Size of the widget button in pixels                                        |
| x-margin                | number  | 40             | Horizontal margin from the edge of the screen in pixels                    |
| y-margin                | number  | 98             | Vertical margin from the edge of the screen in pixels                      |
| z-index                 | number  | 50             | Z-index for layering                                                       |
| fluid-shop-display-name | string  | 'My Store'     | Shop name displayed in the cart header                                     |
| hide-widget             | boolean | false          | When true, hides button but keeps cart functionality                       |

### Banner Widget (`<fluid-banner-widget>`)

| Attribute/Property | Type    | Default    | Description                                                  |
| ------------------ | ------- | ---------- | ------------------------------------------------------------ |
| title              | string  | -          | Title text for the banner                                    |
| description        | string  | -          | Description or promotional text                              |
| image-url          | string  | -          | URL for the banner image                                     |
| image-alt          | string  | -          | Alternative text for the image                               |
| position           | string  | 'center'   | Position: 'top', 'bottom', 'left', 'right', 'center'         |
| variant            | string  | 'default'  | Style variant: 'default', 'outline', 'vibrant', 'minimal'    |
| size               | string  | 'md'       | Size of the banner: 'sm', 'md', 'lg', 'full'                 |
| target-url         | string  | -          | Banner click destination URL                                 |
| button-text        | string  | 'Shop Now' | Text for the call-to-action button                           |
| show-button        | boolean | true       | Whether to show a button or make the entire banner clickable |
| class-name         | string  | -          | Optional additional CSS classes                              |
| tracking-id        | string  | -          | Optional tracking ID for analytics                           |
| aspect-ratio       | number  | 16/9       | Aspect ratio for the banner                                  |
| hide-widget        | boolean | false      | When true, hides the banner completely                       |

## For More Information

For full documentation on attribution settings and advanced configuration, refer to the `@fluid-app/fluid` documentation.

For a complete working example, see the [cdn-example.html](./cdn-example.html) file in this package.