@liquidcommerce/elements-sdk 2.2.0-beta.34 → 2.2.0-beta.35

package/dist/types/core/singleton-manager.service.d.ts

@@ -1,12 +1,12 @@
 import type { IClientConfigs } from '@/core/client/client-config.service';
-import type { LiquidCommerceElementsClientConstructor } from '@/interfaces/core.interface';
+import type { LiquidCommerceElementsBuilderClientConstructor, LiquidCommerceElementsClientConstructor } from '@/interfaces/core.interface';
 export declare class SingletonManager {
     private static instances;
     private static clientConstructor;
     private static getInstances;
     private constructor();
-    static setClientConstructor(lceConstructor: LiquidCommerceElementsClientConstructor): void;
-    static getClientConstructor(): LiquidCommerceElementsClientConstructor | null;
+    static setClientConstructor(lceConstructor: LiquidCommerceElementsClientConstructor | LiquidCommerceElementsBuilderClientConstructor): void;
+    static getClientConstructor(): LiquidCommerceElementsClientConstructor | LiquidCommerceElementsBuilderClientConstructor | null;
     static getClassInstance<T>(className: string, instanceCreator: () => T): T;
     static getClient<T>(clientConfigs: IClientConfigs): Promise<T>;
 }

package/dist/types/elements-base-client.d.ts

@@ -0,0 +1,49 @@
+import { AuthService } from '@/core/auth.service';
+import { ClientActionService } from '@/core/client/client-action.service';
+import { ClientConfigService, type IClientConfigs } from '@/core/client/client-config.service';
+import { CommandService } from '@/core/command/command.service';
+import { DebugPanelService } from '@/core/debug-panel/debug-panel.service';
+import { FingerPrintService } from '@/core/fingerprint.service';
+import { GoogleTagManagerService } from '@/core/google-tag-manager.service';
+import { LoggerFactory } from '@/core/logger/logger-factory';
+import { StoreService } from '@/core/store';
+import { TelemetryService } from '@/core/telemetry/telemetry.service';
+import { type ComponentType } from '@/enums';
+import type { IInjectedComponent, ILiquidCommerceElementsActions, IProcessInjectElementParams } from '@/interfaces/core.interface';
+import { ApiClientService } from '@/modules/api-client';
+import { ThemeProviderService } from '@/modules/theme-provider';
+export declare abstract class ElementsBaseClient {
+    protected readonly authService: AuthService;
+    protected readonly clientConfig: ClientConfigService;
+    protected readonly store: StoreService;
+    protected readonly commands: CommandService;
+    protected readonly apiClient: ApiClientService;
+    protected readonly themeProvider: ThemeProviderService;
+    protected readonly fingerPrintService: FingerPrintService;
+    protected readonly googleTagManager: GoogleTagManagerService;
+    protected readonly clientAction: ClientActionService;
+    protected readonly telemetry: TelemetryService;
+    protected readonly debugPanel: DebugPanelService;
+    protected readonly logger: ReturnType<typeof LoggerFactory.get>;
+    protected clientPrepared: boolean;
+    protected componentFactoryInitialized: boolean;
+    protected cartDrawerCreated: boolean;
+    protected gtmInitialized: boolean;
+    protected injectedComponents: Map<string, IInjectedComponent>;
+    constructor(clientConfigs: IClientConfigs);
+    prepare(): Promise<void>;
+    private prepareEssentialServices;
+    private deferHeavyInitialization;
+    private initializeHeavyServices;
+    get actions(): ILiquidCommerceElementsActions;
+    protected processInjectElement(params: IProcessInjectElementParams): Promise<IInjectedComponent | null>;
+    protected ensureCartDrawerExists(): void;
+    protected ensureAllComponentsRegistered(): void;
+    protected createInjectedComponentWrapper(containerId: string, type: ComponentType, element: HTMLElement): IInjectedComponent;
+    protected rerenderInjectedComponentsByType(type: ComponentType): void;
+    protected isElementsEnabled(): boolean;
+    protected injectDisabledElementsError(containerId: string, componentName: ComponentType): void;
+    private registerEssentialComponents;
+    protected registerComponents(): void;
+    protected registerAllComponents(): void;
+}

package/dist/types/elements-builder-client.d.ts

@@ -0,0 +1,2 @@
+import type { ILiquidCommerceElementsBuilderClient, ILiquidCommerceElementsBuilderConfig } from '@/interfaces/core.interface';
+export declare function ElementsBuilder(apiKey: string, config: ILiquidCommerceElementsBuilderConfig): Promise<ILiquidCommerceElementsBuilderClient | null>;

package/dist/types/index.d.ts

@@ -1,3 +1,4 @@
+export * from './elements-builder-client';
 export * from './elements-client';
 export * from './enums';
 export * from './interfaces/configs';

package/dist/types/index.umd.d.ts

@@ -1,2 +1,2 @@
-import { Elements } from './index';
-export { Elements };
+import { Elements, ElementsBuilder } from './index';
+export { Elements, ElementsBuilder };

package/dist/types/interfaces/core.interface.d.ts

@@ -17,12 +17,17 @@ export interface IClientCustomThemeConfig {
     cart?: UpdateCartComponent;
     checkout?: UpdateCheckoutComponent;
 }
+export interface ILiquidCommerceElementsBuilderConfig {
+    env?: ElementsEnv;
+    promoTicker?: IPromoTicker[];
+    customTheme?: IClientCustomThemeConfig;
+    debugMode?: DebugMode;
+}
 export interface ILiquidCommerceElementsConfig {
     env?: ElementsEnv;
     promoTicker?: IPromoTicker[];
     customTheme?: IClientCustomThemeConfig;
     proxy?: IElementsProxyConfig;
-    isBuilder?: boolean;
     debugMode?: DebugMode;
 }
 export interface IInjectProductElement {
@@ -39,21 +44,6 @@ export interface IInjectedComponent {
     getElement(): HTMLElement;
     rerender(): void;
 }
-export interface ILiquidCommerceElementsBuilderMethod {
-    updateComponentGlobalConfigs(configs: UpdateComponentGlobalConfigs): Promise<void>;
-    updateProductComponent(configs: UpdateProductComponent): Promise<void>;
-    updateAddressComponent(configs: UpdateAddressComponent): void;
-    updateCartComponent(configs: UpdateCartComponent): void;
-    updateCheckoutComponent(configs: UpdateCheckoutComponent): void;
-    injectElement(params: IBuilderInjectElementParams): Promise<IInjectedComponent | null>;
-    injectProductElement(params: IInjectProductElement[]): Promise<IInjectedComponent[]>;
-    injectAddressElement(containerId: string, options?: IAddressOptions): Promise<IInjectedComponent | null>;
-    injectCartElement(containerId: string): Promise<IInjectedComponent | null>;
-    injectCheckoutElement(containerId: string, options?: {
-        simulatePresale?: boolean;
-        presaleExpiresInMinutes?: number;
-    }): Promise<IInjectedComponent | null>;
-}
 export interface IProcessInjectElementParams {
     type: ComponentType;
     containerId: string;
@@ -72,8 +62,23 @@ export interface ILiquidCommerceElementsActions {
     cart: ICartActions;
     checkout: ICheckoutActions;
 }
+export interface ILiquidCommerceElementsBuilderClient {
+    updateComponentGlobalConfigs(configs: UpdateComponentGlobalConfigs): Promise<void>;
+    updateProductComponent(configs: UpdateProductComponent): Promise<void>;
+    updateAddressComponent(configs: UpdateAddressComponent): void;
+    updateCartComponent(configs: UpdateCartComponent): void;
+    updateCheckoutComponent(configs: UpdateCheckoutComponent): void;
+    injectElement(params: IBuilderInjectElementParams): Promise<IInjectedComponent | null>;
+    injectProductElement(params: IInjectProductElement[]): Promise<IInjectedComponent[]>;
+    injectAddressElement(containerId: string, options?: IAddressOptions): Promise<IInjectedComponent | null>;
+    injectCartElement(containerId: string): Promise<IInjectedComponent | null>;
+    injectCheckoutElement(containerId: string, options?: {
+        simulatePresale?: boolean;
+        presaleExpiresInMinutes?: number;
+    }): Promise<IInjectedComponent | null>;
+    actions: ILiquidCommerceElementsActions;
+}
 export interface ILiquidCommerceElementsClient {
-    builder: ILiquidCommerceElementsBuilderMethod;
     injectProductElement(params: IInjectProductElement[]): Promise<IInjectedComponent[]>;
     injectAddressElement(containerId: string, options?: IAddressOptions): Promise<IInjectedComponent | null>;
     injectCartElement(containerId: string): Promise<IInjectedComponent | null>;
@@ -83,3 +88,4 @@ export interface ILiquidCommerceElementsClient {
     getInjectedComponents(): Map<string, IInjectedComponent>;
 }
 export type LiquidCommerceElementsClientConstructor = new (clientConfigs: IClientConfigs) => ILiquidCommerceElementsClient;
+export type LiquidCommerceElementsBuilderClientConstructor = new (clientConfigs: IClientConfigs) => ILiquidCommerceElementsBuilderClient;

package/dist/types/modules/cart/components/index.d.ts

@@ -1,6 +1,7 @@
 export * from './cart-body.component';
 export * from './cart-footer.component';
 export * from './cart-fulfillment.component';
+export * from './cart-fulfillment.component';
 export * from './cart-header.component';
 export * from './cart-item.component';
 export * from './cart-item-quantity-price.component';

package/docs/CONFIGURATION.md

@@ -308,34 +308,158 @@ data-env="production"
 data-debug-mode="console"
 ```
 
-#### `data-cart-id`
+#### `data-cart-button`
 
 **Type:** `string`
 
-Container ID for cart button.
+Container ID, CSS selector, or position-prefixed selector for simple cart button (no badge).
 
 ```html
-data-cart-id="header-cart"
+<!-- Simple ID -->
+data-cart-button="header-cart"
+
+<!-- CSS Selector (from browser inspect tool) -->
+data-cart-button=".header .nav-links"
+data-cart-button="#main-navigation"
+
+<!-- Position-prefixed selectors -->
+data-cart-button="above:.header .logo"      <!-- Place above the target -->
+data-cart-button="below:#main-navigation"  <!-- Place below the target -->
+data-cart-button="replace:.old-cart"       <!-- Replace the target -->
+data-cart-button="inside:.header .nav"     <!-- Place inside the target (default) -->
 ```
 
-#### `data-show-cart-items`
+#### `data-cart-badge-button`
 
-**Type:** flag (no value)
+**Type:** `string`
 
-Show item count on cart button.
+Container ID, CSS selector, or position-prefixed selector for cart button with item count badge.
 
 ```html
-data-show-cart-items
+<!-- Simple ID -->
+data-cart-badge-button="header-cart"
+
+<!-- CSS Selector (from browser inspect tool) -->
+data-cart-badge-button=".header .nav-links"
+data-cart-badge-button="#main-navigation"
+
+<!-- Position-prefixed selectors -->
+data-cart-badge-button="above:.header .logo"      <!-- Place above the target -->
+data-cart-badge-button="below:#main-navigation"  <!-- Place below the target -->
+data-cart-badge-button="replace:.old-cart"       <!-- Replace the target -->
+data-cart-badge-button="inside:.header .nav"     <!-- Place inside the target (default) -->
 ```
 
-#### `data-hide-cart-floating-button`
+**Position Prefixes:**
+- `above:` - Place above the target element
+- `below:` - Place below the target element  
+- `replace:` - Replace the target element
+- `inside:` - Place inside the target element (default)
+
+#### `data-cart-button-hidden`
 
 **Type:** flag (no value)
 
-Hide the default floating cart button.
+Hide cart button completely.
 
 ```html
-data-hide-cart-floating-button
+data-cart-button-hidden
+```
+
+### Cart Button Examples
+
+**Simple cart button (no badge):**
+```html
+<script 
+  data-liquid-commerce-elements
+  data-token="your-api-key"
+  data-cart-button="header-cart"
+  src="elements.js">
+</script>
+```
+
+**Cart button with item count badge:**
+```html
+<script 
+  data-liquid-commerce-elements
+  data-token="your-api-key"
+  data-cart-badge-button="header-cart"
+  src="elements.js">
+</script>
+```
+
+**Using position-prefixed selectors:**
+```html
+<!-- Place inside the target element (default) -->
+<script 
+  data-liquid-commerce-elements
+  data-token="your-api-key"
+  data-cart-badge-button="inside:.header .nav-links"
+  src="elements.js">
+</script>
+
+<!-- Place above the target element -->
+<script 
+  data-liquid-commerce-elements
+  data-token="your-api-key"
+  data-cart-button="above:.header .logo"
+  src="elements.js">
+</script>
+
+<!-- Place below the target element -->
+<script 
+  data-liquid-commerce-elements
+  data-token="your-api-key"
+  data-cart-badge-button="below:#main-navigation"
+  src="elements.js">
+</script>
+
+<!-- Replace the target element -->
+<script 
+  data-liquid-commerce-elements
+  data-token="your-api-key"
+  data-cart-button="replace:.old-cart-button"
+  src="elements.js">
+</script>
+```
+
+**No cart button:**
+```html
+<script 
+  data-liquid-commerce-elements
+  data-token="your-api-key"
+  data-cart-button-hidden
+  src="elements.js">
+</script>
+```
+
+**Default behavior (floating cart button with badge):**
+```html
+<script 
+  data-liquid-commerce-elements
+  data-token="your-api-key"
+  src="elements.js">
+</script>
+```
+
+### Getting CSS Selectors from Browser
+
+**Super Easy Method:**
+1. **Right-click** on any element where you want the cart button
+2. Select **"Inspect"** or **"Inspect Element"**
+3. In developer tools, **right-click** on the highlighted element
+4. Select **"Copy" → "Copy selector"**
+5. Paste the selector into your `data-cart-button` or `data-cart-badge-button` attribute
+
+**Example:**
+```html
+<!-- After copying selector from browser inspect tool -->
+<script 
+  data-liquid-commerce-elements
+  data-token="your-api-key"
+  data-cart-badge-button="body > div.container > header > nav > div.nav-links"
+  src="elements.js">
+</script>
 ```
 
 ### Product Configuration

package/package.json

@@ -3,7 +3,7 @@
   "description": "LiquidCommerce Elements SDK",
   "license": "UNLICENSED",
   "author": "LiquidCommerce Team",
-  "version": "2.2.0-beta.34",
+  "version": "2.2.0-beta.35",
   "homepage": "https://docs.liquidcommerce.co/elements-sdk",
   "repository": {
     "type": "git",
@@ -71,7 +71,7 @@
     "embeddable commerce"
   ],
   "devDependencies": {
-    "@biomejs/biome": "2.2.6",
+    "@biomejs/biome": "2.2.7",
     "@commitlint/cli": "^20.1.0",
     "@commitlint/config-conventional": "^20.0.0",
     "@rollup/plugin-alias": "^5.1.1",
@@ -87,14 +87,14 @@
     "@semantic-release/npm": "^13.1.1",
     "@semantic-release/release-notes-generator": "^14.1.0",
     "@types/core-js": "^2.5.8",
-    "@types/node": "^24.9.0",
+    "@types/node": "^24.9.1",
     "conventional-changelog-cli": "^5.0.0",
     "husky": "^9.1.7",
     "process": "^0.11.10",
     "rollup": "^4.52.5",
     "rollup-obfuscator": "^4.1.1",
     "rollup-plugin-typescript2": "^0.36.0",
-    "semantic-release": "^24.2.9",
+    "semantic-release": "^25.0.1",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3"
   },