### Complete Usage Example - HTML

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/tooltip.md

Provides a comprehensive HTML example demonstrating the integration of both click and hover tooltips within a product options section.

```html
<div class="product-options">
  <!-- Click Tooltip -->
  <div class="tooltip-toggle--clickable">
    <i class="icon-help"></i>
    <div class="tooltip-content">
      <button class="close-tooltip">&times;</button>
      <h4>Product Options Help</h4>
      <p>Click on an option to select your variant</p>
    </div>
  </div>

  <!-- Hover Tooltip -->
  <div class="tooltip-hover-wrapper">
    <label class="tooltip-toggle--hover">
      <span>Size</span>
      <i class="icon-info"></i>
      <div class="tooltip-content">
        <p>Choose your preferred size from the options below</p>
      </div>
    </label>
  </div>
</div>
```

--------------------------------

### Complete App Initialization and Usage Example

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/app.md

A comprehensive example showing how to import the App class, create an instance, wait for the 'theme::ready' event, and then utilize various App methods for watching elements, adding event listeners, and loading the app.

```javascript
import App from './app.js';

// Create and load the app
const app = new App();

// Wait for the app to be fully loaded
document.addEventListener('theme::ready', () => {
  console.log('Theme loaded:', app.status);
  
  // Now you can use all app methods
  app.watchElements({
    cart: '.shopping-cart',
    header: 'header'
  });
  
  // Add event listeners
  app.onClick('.menu-toggle', () => {
    app.toggleElementClassIf(
      app.watchElement('sidebar', '.sidebar'),
      'open',
      'closed',
      (el) => !el.classList.contains('open')
    );
  });
});

// Initialize the application
app.loadTheApp();
```

--------------------------------

### App Initialization with Tooltips

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/tooltip.md

Example of integrating tooltip initialization into the main application's loading process. Requires importing `initTootTip`.

```javascript
// In app.js
import initTootTip from './partials/tooltip';

class App extends AppHelpers {
  loadTheApp() {
    // ... other initializations ...
    initTootTip();
    // ... rest of initialization ...
  }
}
```

--------------------------------

### AppHelpers Usage Example

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/app-helpers.md

Demonstrates initializing AppHelpers, watching elements, toggling classes conditionally, handling events, and iterating through elements.

```javascript
import AppHelpers from './app-helpers';

const helpers = new AppHelpers();

// Watch elements
helpers.watchElements({
  buttons: '.btn',
  header: '.header',
  content: 'main'
});

// Toggle classes based on condition
helpers.toggleClassIf('.nav-item', 'active', 'inactive', (el) => {
  return el.dataset.current === 'true';
});

// Event handling with chaining
helpers
  .onClick('.toggle-btn', (e) => {
    helpers.toggleClassIf('.sidebar', 'open', 'closed', (el) => !el.classList.contains('open'));
  })
  .onKeyUp('.search', (e) => {
    console.log('Searching for:', e.target.value);
  });

// Iterate elements
helpers.all('.item', (item) => {
  item.addEventListener('click', () => {
    helpers.addClass(item, 'selected');
  });
})
```

--------------------------------

### Custom Product Page Initialization

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/product-page.md

Example of extending the Product class to add custom logic within the onReady lifecycle method. This allows for additional initialization steps after the base Product class setup.

```javascript
class ProductPage extends Product {
  onReady() {
    super.onReady();
    console.log('Product page initialized');
  }
}
```

--------------------------------

### App Initialization Example

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/DOCUMENTATION_INDEX.md

Methods for theme initialization and management, including handling the mobile menu, sticky header, and modals. This class extends AppHelpers.

```javascript
class App extends AppHelpers {
  // ...
  /**
   * Initialize the theme.
   */
  init() {
    // ...
    document.dispatchEvent(new CustomEvent('theme::ready'));
  }

  /**
   * Toggle mobile menu.
   */
  toggleMobileMenu() {
    // ...
  }
  // ...
}
```

--------------------------------

### Product Form Data Usage Example

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/types.md

Shows how to create a FormDataObject from an HTML form and use it with the `salla.product.getPrice` method.

```javascript
const formData = new FormData(productForm);
salla.product.getPrice(formData);
```

--------------------------------

### Multilingual Support Example (JavaScript)

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/localization.md

Shows how `salla.lang.get` dynamically retrieves the correct language version of a string based on the current store's language setting.

```javascript
// Returns appropriate language version
salla.lang.get('blocks.header.cart')
// English: "Cart"
// Arabic: "السلة"
```

--------------------------------

### Complete Usage Example - JavaScript Initialization

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/tooltip.md

Shows how to import and initialize the tooltip utility in a JavaScript application. It includes initialization on DOM ready and within an app initialization flow.

```javascript
import initTooltip from './partials/tooltip';

// Initialize on DOM ready
document.addEventListener('DOMContentLoaded', () => {
  initTooltip();
});

// Or with app initialization
import App from './app';
const app = new App();
app.loadTheApp();
// initTooltip() is called inside app initialization
```

--------------------------------

### Click Tooltip Usage Example

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/tooltip.md

Illustrates the usage of a click-triggered tooltip within an HTML structure. This example shows how to apply the necessary classes to elements.

```html
<button class="tooltip-toggle--clickable" title="Terms & Conditions">?</button>
<div class="tooltip-content">
  Content here
</div>
```

--------------------------------

### Custom Element Initialization Example

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/DOCUMENTATION_INDEX.md

Demonstrates the structure and interaction of custom web elements like ProductCard and WishlistCard. Includes integration with Salla's platform elements such as product-options and quantity-input.

```javascript
// Example of initializing a custom element
const productCard = document.querySelector('product-card');
if (productCard) {
  productCard.addEventListener('click', () => {
    console.log('Product card clicked');
  });
}

// Example of interacting with a Salla platform element
const quantityInput = document.querySelector('quantity-input');
if (quantityInput) {
  quantityInput.value = 2;
}
```

--------------------------------

### Page Slug Usage Example

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/types.md

Demonstrates how to use the PageSlug type with the `initiateWhenReady` method to trigger initialization on specific pages like product and cart pages.

```javascript
class MyPage extends BasePage {
  // Runs only on product and cart pages
  MyPage.initiateWhenReady(['product.single', 'cart.index']);
}
```

--------------------------------

### Simple Fade-In Animation Example

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/anime-wrapper.md

Demonstrates a basic fade-in animation using the Anime.js wrapper. Sets duration, opacity, and easing.

```javascript
import Anime from './partials/anime';

const fadeIn = new Anime('.card')
  .duration(600)
  .opacity([0, 1])
  .easing('easeOutQuad')
  .play();
```

--------------------------------

### Product Page Implementation Example

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/DOCUMENTATION_INDEX.md

Page-specific methods for handling product details, including price updates, image zooming, and product options validation. Emits events for price updates.

```javascript
class Product extends BasePage {
  // ...
  /**
   * Update the product price.
   */
  updatePrice() {
    // ...
    this.emit('price-updated');
  }

  /**
   * Validate product options.
   */
  validateOptions() {
    // ...
  }
  // ...
}
```

--------------------------------

### Height Expansion with Callback Example

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/anime-wrapper.md

Demonstrates animating the height and opacity of an element, with a callback function executed upon completion to add a CSS class.

```javascript
const expand = new Anime('.collapsible-content')
  .height([0, 300])
  .opacity([0, 1])
  .duration(400)
  .easing('easeInOutCubic')
  .complete(() => {
    app.addClass('.collapsible', 'expanded');
  })
  .play();
```

--------------------------------

### Parameterized String Example (JavaScript)

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/localization.md

Demonstrates how parameterized strings, like bank offer descriptions, are handled in JavaScript. The `:bank_name` placeholder indicates where a dynamic value should be inserted.

```javascript
// Example: Bank offer single
const template = salla.lang.get('common.bank_offer_sub_title_single');
// Contains :bank_name placeholder - replace with actual bank name
```

--------------------------------

### onReady Lifecycle Hook

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/base-page.md

Override this method to implement page initialization logic. It is called during initiate() as the main entry point for page setup.

```javascript
onReady()
```

```javascript
class ProductPage extends BasePage {
  onReady() {
    console.log('Product page is ready');
    this.initImageSlider();
    this.setupPriceWatcher();
  }
}
```

--------------------------------

### Salla Platform API Usage

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/README.md

Examples of interacting with the Salla platform's global API for configuration, language, events, operations, and helpers.

```javascript
// Configuration
salla.config.get('key')
salla.lang.get('translation.key')
salla.url.get('endpoint')

// Events
salla.event.on('eventName', callback)
salla.product.event.onPriceUpdated(callback)
salla.cart.event.onUpdated(callback)
salla.wishlist.event.onAdded(callback)

// Operations
salla.cart.submit()
salla.wishlist.add(productId)
salla.wishlist.remove(productId)
salla.product.getPrice(formData)

// Helpers
salla.money(amount)
salla.notify.success(message)
salla.notify.error(message)
```

--------------------------------

### Usage Pattern: Single Page Class with Automatic Initialization

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/base-page.md

Example demonstrating how to define a page class, implement lifecycle hooks, and use initiateWhenReady for automatic initialization on specific pages.

```javascript
import BasePage from './base-page';

class ProductPage extends BasePage {
  onReady() {
    app.watchElements({
      price: '.product-price',
      image: '.product-image',
      quantity: '.quantity-input'
    });
    
    this.initImageZoom();
  }
  
  registerEvents() {
    salla.product.event.onPriceUpdated((res) => {
      this.updatePrice(res.data.price);
    });
  }
  
  initImageZoom() {
    // Setup image zoom
  }
  
  updatePrice(price) {
    app.element('.product-price').textContent = salla.money(price);
  }
}

// Automatically initialize on product pages
ProductPage.initiateWhenReady(['product.single']);
```

--------------------------------

### play

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/anime-wrapper.md

Executes the configured animation sequence. This method must be called to start the animation and returns the Anime.js timeline object.

```APIDOC
## play

### Description
Executes the animation and returns the Anime.js timeline.

### Method
```javascript
play()
```

### Return Type
- **object** - Anime.js animation timeline object

### Example
```javascript
const timeline = animation.play();
```
```

--------------------------------

### Accessing Window Global Variables

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/README.md

Examples of accessing global variables exposed by the theme, including the app instance, theme settings, and loaded libraries.

```javascript
// App instance
window.app           // App class instance (from app.js)

// Theme settings
window.header_is_sticky    // Boolean
window.imageZoom           // Boolean
window.enable_add_product_toast // Boolean

// Libraries
window.anime         // Anime.js library
window.fslightbox    // Lightbox library
```

--------------------------------

### Product Page JavaScript Usage Example

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/product-page.md

This JavaScript class demonstrates how to manage product page elements, handle price updates, validate options, and initialize image zooming. It utilizes Salla's app and salla.product APIs.

```javascript
import BasePage from './base-page';
import { zoom } from './partials/image-zoom';

class Product extends BasePage {
  onReady() {
    // Watch product elements
    app.watchElements({
      totalPrice: '.total-price',
      productWeight: '.product-weight',
      beforePrice: '.before-price',
      startingPriceTitle: '.starting-price-title',
      productSku: '.product-sku',
    });

    // Initialize validations
    this.initProductOptionValidations();

    // Setup image zoom if enabled
    if (imageZoom) {
      this.initImagesZooming();
      window.addEventListener('resize', () => this.initImagesZooming());
    }
  }

  initProductOptionValidations() {
    document.querySelector('.product-form')?.addEventListener('change', function(){
      this.reportValidity() && salla.product.getPrice(new FormData(this));
    });
  }

  initImagesZooming() {
    const imageZoom = document.querySelector('.image-slider .magnify-wrapper.swiper-slide-active .img-magnifier-glass');
    if (window.innerWidth < 1024 || imageZoom) return;

    setTimeout(() => {
      const image = document.querySelector('.image-slider .swiper-slide-active img');
      zoom(image?.id, 2);
    }, 250);

    document.querySelector('salla-slider.details-slider').addEventListener('slideChange', (e) => {
      setTimeout(() => {
        const imageZoom = document.querySelector('.image-slider .swiper-slide-active .img-magnifier-glass');
        if (window.innerWidth < 1024 || imageZoom) return;
        
        const image = document.querySelector('.image-slider .magnify-wrapper.swiper-slide-active img');
        zoom(image?.id, 2);
      }, 250);
    });
  }

  registerEvents() {
    // Price updated from options
    salla.product.event.onPriceUpdated((res) => {
      const data = res.data;
      const isOnSale = data.has_sale_price && data.regular_price > data.price;

      app.startingPriceTitle?.classList.add('hidden');

      app.productWeight.forEach((el) => {el.innerHTML = data.weight || ''});
      app.totalPrice.forEach((el) => {el.innerHTML = salla.money(data.price)});
      app.beforePrice.forEach((el) => {el.innerHTML = salla.money(data.regular_price)});
      app.productSku.forEach((el) => {el.innerHTML = data.sku || ''});

      app.toggleClassIf('.price_is_on_sale','showed','hidden', ()=> isOnSale);
      app.toggleClassIf('.starting-or-normal-price','hidden','showed', ()=> isOnSale);

      document.querySelectorAll('.total-price, .product-weight').forEach(el => {
        el.classList.remove('scale-pulse');
        void el.offsetWidth;
        el.classList.add('scale-pulse');
      });
    });

    // Price update failed
    salla.event.on('product::price.updated.failed',()=>{
      app.element('.price-wrapper').classList.add('hidden');
      const outOfStock = app.element('.out-of-stock');
      outOfStock.classList.remove('hidden');
      outOfStock.classList.remove('scale-pulse');
      void outOfStock.offsetWidth;
      outOfStock.classList.add('scale-pulse');
    });

    // Show more button
    app.onClick('#btn-show-more', e => app.all('#more-content', div => {
      e.target.classList.add('is-expanded');
      div.style = `max-height:${div.scrollHeight}px`;
    }) || e.target.remove());
  }
}

Product.initiateWhenReady(['product.single']);
```

--------------------------------

### Cart Page Implementation Example

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/DOCUMENTATION_INDEX.md

Methods for managing the shopping cart, including cart updates, item validation, and checkout submission. Emits events for cart and item changes.

```javascript
class Cart extends BasePage {
  // ...
  /**
   * Update an item in the cart.
   */
  updateItem() {
    // ...
    this.emit('item-updated');
  }

  /**
   * Remove an item from the cart.
   */
  removeItem() {
    // ...
    this.emit('item-removed');
  }

  /**
   * Submit the checkout.
   */
  submitCheckout() {
    // ...
  }
  // ...
}
```

--------------------------------

### JavaScript Example with Bulk Translations and Loaded Check

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/localization.md

This snippet demonstrates adding bulk translations and retrieving several strings within the `onLoaded` callback, ensuring they are available before use.

```javascript
salla.lang.onLoaded(() => {
  salla.lang.addBulk({
    'pages.cart.added_to_cart': { ar: 'تمت الإضافة إلى سلة التسوق', en: 'Added to Cart' },
    'pages.cart.view_cart': { ar: 'عرض السلة', en: 'View Cart' }
  });
  this.successMessage = salla.lang.get('pages.cart.added_to_cart');
  this.viewCartText = salla.lang.get('pages.cart.view_cart');
  this.checkoutText = salla.lang.get('pages.cart.complete_order');
  this.showMoreText = salla.lang.get('pages.checkout.show_more');
});
```

--------------------------------

### Image Zooming with Resize Listener

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/product-page.md

This example shows how to conditionally initialize image zooming and reinitialize it on window resize events. It ensures the zoom functionality remains active across different screen sizes.

```javascript
// Controlled by theme setting 'imageZoom'
if (imageZoom) {
  this.initImagesZooming();
  window.addEventListener('resize', () => this.initImagesZooming());
}
```

--------------------------------

### ProductCard getProductPrice Method

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/custom-elements.md

Generates the HTML for displaying the product price, handling sale prices, starting prices for variable products, and regular prices.

```javascript
getProductPrice()
```

--------------------------------

### Conditional String Example (JavaScript)

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/localization.md

Illustrates how translation strings can vary based on context, such as singular versus plural forms. The `salla.lang.get` function retrieves the appropriate string.

```javascript
// Singular vs plural handling
const message = salla.lang.get('pages.products.remained');  // "X items remaining"
```

--------------------------------

### Config Value Types

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/types.md

Defines the structure for configuration values retrieved using `salla.config.get()`. Includes examples for page slugs, product display settings, theme placeholders, and user types.

```javascript
{
  'page.slug': PageSlug,
  'store.settings.product.fit_type': string,
  'store.settings.product.show_price_as_dash': boolean,
  'theme.settings.placeholder': string,
  'user.type': 'guest' | 'authenticated'
}
```

--------------------------------

### Image Zoom Integration Example

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/DOCUMENTATION_INDEX.md

Integrates a magnifying glass effect for product images, providing image magnification with touch support. This function is responsive and intended for desktop use (1024px+).

```javascript
/**
 * Apply image zoom functionality.
 * @param {string} imgID The ID of the image element.
 * @param {object} zoom Configuration object for zoom.
 */
function zoom(imgID, zoom) {
  // ... implementation for image zooming ...
  console.log(`Zooming image ${imgID} with settings:`, zoom);
}
```

--------------------------------

### Analytics Product Added Event Usage Example

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/types.md

Demonstrates how to access product ID and quantity from the analytics data payload within a 'Product Added' event listener.

```javascript
salla.event.on('Product Added', (analyticsData: AnalyticsData) => {
  const { product_id, quantity } = analyticsData[0];
});
```

--------------------------------

### Example Translation Keys Structure

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/configuration.md

Illustrates the nested structure for organizing translation keys in JSON locale files. Keys are grouped by 'blocks', 'pages', and 'common' for modularity.

```json
{
  "blocks": {
    "header": { "cart": "..." }
  },
  "pages": {
    "cart": { "..." },
    "order": { "..." }
  },
  "common": { "..." }
}
```

--------------------------------

### BasePage Lifecycle Hooks Example

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/DOCUMENTATION_INDEX.md

Provides lifecycle hooks and a static factory method for page-specific initialization and event registration. Supports various page types like Product, Cart, and Home.

```javascript
class BasePage {
  // ...
  /**
   * Lifecycle hook for page initialization.
   */
  init() {
    // ...
  }

  /**
   * Lifecycle hook for event registration.
   */
  registerEvents() {
    // ...
  }

  /**
   * Static factory method to create page instances.
   * @param {string} pageType The type of page.
   */
  static create(pageType) {
    // ...
  }
  // ...
}
```

--------------------------------

### Anime.js Animation Example

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/DOCUMENTATION_INDEX.md

Chainable animation methods for creating element animations, keyframe definitions, and easing functions using Anime.js. Supports complex multi-property animations.

```javascript
import anime from 'animejs';

// Fade-in animation
anime({
  targets: '.element', 
  opacity: [0, 1],
  duration: 1000,
  easing: 'easeOutQuad'
});

// Staggered animation
anime({
  targets: '.list-item',
  translateX: [-50, 0],
  delay: anime.stagger(100) 
});

// Complex multi-property animation
anime.timeline({
  loop: true
})
  .add({
    targets: '.el1',
    scale: [0, 1],
    duration: 1000
  })
  .add({
    targets: '.el2',
    translateX: 250,
    rotate: 360,
    duration: 1000
  });
```

--------------------------------

### Complex Multi-Property Animation Example

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/anime-wrapper.md

Showcases a complex animation involving multiple properties like opacity, scale, and translation, with custom delay and easing. Includes a completion callback.

```javascript
const complexAnimation = new Anime('.element')
  .opacity([0, 1])
  .scale([0.8, 1])
  .translateY([-50, 0])
  .duration(1000)
  .delay((el, i) => i * 150)
  .easing('easeOutElastic')
  .complete(() => {
    console.log('All elements animated');
  })
  .play();
```

--------------------------------

### Tooltip Functionality Example

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/DOCUMENTATION_INDEX.md

Provides click and hover tooltip functionality with device detection and accessibility considerations. Supports various patterns like click-triggered, hover-triggered, and includes close buttons.

```javascript
/**
 * Initialize tooltip functionality.
 */
function toolTip() {
  // ... implementation for tooltips ...
  console.log('Tooltip functionality initialized.');
}
```

--------------------------------

### AppHelpers DOM Manipulation Example

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/DOCUMENTATION_INDEX.md

Utility methods for DOM manipulation, including element selection, event handling, and class toggling. Useful for direct DOM interactions within the theme.

```javascript
class AppHelpers {
  // ...
  /**
   * Watch for changes in an element.
   * @param {HTMLElement} el The element to watch.
   * @param {function} callback The callback function to execute.
   */
  watchElement(el, callback) {
    // ...
  }

  /**
   * Toggle a class on an element.
   * @param {HTMLElement} el The element to toggle the class on.
   * @param {string} className The class name to toggle.
   */
  toggleClass(el, className) {
    // ...
  }
  // ...
}
```

--------------------------------

### Salla API Event Integration

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/base-page.md

Integrate with various Salla API events within a page class. This example demonstrates how to subscribe to events related to products, cart, wishlist, and comments, as well as general Salla events.

```javascript
class ExamplePage extends BasePage {
  registerEvents() {
    // Product events
    salla.product.event.onPriceUpdated((response) => {});
    salla.event.on('product::price.updated.failed', () => {});
    
    // Cart events
    salla.event.cart.onUpdated((data) => {});
    salla.cart.event.onItemUpdated((data, id) => {});
    salla.cart.event.onItemRemoved((data, id) => {});
    
    // Wishlist events
    salla.wishlist.event.onAdded((event, id) => {});
    salla.wishlist.event.onRemoved((response, id) => {});
    
    // Comment events
    salla.comment.event.onAdded(() => {});
    
    // General events
    salla.event.on('Product Added', (analyticsData) => {});
  }
}
```

--------------------------------

### Get All Translations

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/localization.md

Retrieve all available translation strings for the current language. Useful for debugging or logging.

```javascript
// Get all translations
salla.lang.all()
```

--------------------------------

### Get Cart Details

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/cart-page.md

Retrieves the details of a specific cart. It can optionally include product options.

```APIDOC
## Get Cart Details

### Description
Retrieves the details of a specific cart, with an option to include product options.

### Method
`salla.cart.details(cartId, options)`

### Parameters
#### Path Parameters
- **cartId** (string) - Required - The ID of the cart to retrieve.
- **options** (array) - Optional - An array of strings specifying which details to include, e.g., `['options']`.

### Response
#### Success Response (200)
- **cartDetails** (object) - Contains the details of the cart.
- **productOptions** (object) - If requested, contains the product options for the cart items.
```

--------------------------------

### App.loadTheApp()

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/app.md

Initializes the entire theme application, including all components and event listeners. It dispatches a 'theme::ready' event upon completion.

```APIDOC
## App.loadTheApp()

### Description
Initializes the entire theme application with all components and event listeners. Dispatches a 'theme::ready' event upon completion.

### Method
```javascript
loadTheApp()
```

### Return Type
void

### Example
```javascript
app.loadTheApp();

// Listen for app ready event
document.addEventListener('theme::ready', () => {
  console.log('Theme is ready!');
});
```
```

--------------------------------

### Get User Type

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/cart-page.md

Retrieves the current user's type, indicating whether they are a guest or authenticated.

```APIDOC
## Get User Type

### Description
Checks and returns the type of the current user, which can be either 'guest' or 'authenticated'.

### Method
`salla.config.get('user.type')`

### Parameters
- **'user.type'** (string) - Required - The configuration key to retrieve the user type.

### Response
#### Success Response (200)
- **userType** (string) - Returns either `'guest'` or `'authenticated'`.
```

--------------------------------

### BasePage initiateWhenReady Static Method

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/base-page.md

Create an instance and initialize it when the app is ready. This is a convenience method that handles the timing automatically.

```APIDOC
## initiateWhenReady

### Description
Create an instance and initialize it when the app is ready. This is a convenience method that handles the timing automatically. It checks if `window.app` is already ready or waits for the `theme::ready` event before initializing.

### Method Signature
```javascript
static initiateWhenReady(allowedPages)
```

### Parameters
#### Path Parameters
* **allowedPages** (array<string> or null) - Optional - Array of page slugs where this class should run

### Return Type
void

### Example
```javascript
// Define page class
class HomePage extends BasePage {
  onReady() {
    console.log('Home page initialized');
  }
}

// Use static method for automatic initialization
HomePage.initiateWhenReady(['index']);
// Runs on home page automatically
```

```javascript
// Without page restrictions
class GlobalFooter extends BasePage {
  onReady() {
    this.setupFooterTracking();
  }
}

GlobalFooter.initiateWhenReady();
// Runs on every page
```
```

--------------------------------

### Staggered List Animation Example

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/anime-wrapper.md

Applies a staggered fade-in and slide-up animation to a list of elements. Utilizes stagger for sequential animation.

```javascript
const listAnimation = new Anime('.list-item')
  .opacity([0, 1])
  .translateY([-20, 0])
  .stagger(100)
  .duration(800)
  .easing('easeOutCubic')
  .play();
```

--------------------------------

### Initialize Product Page

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/product-page.md

Initiates the Product page functionality when the document is ready. It's automatically called on pages with the 'product.single' slug.

```javascript
Product.initiateWhenReady(['product.single']);
```

--------------------------------

### Page Initialization Patterns

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/README.md

Demonstrates the recommended BasePage pattern for initializing pages and contrasts it with global DOMContentLoaded initialization.

```javascript
// Good - use BasePage pattern
class MyPage extends BasePage {
  onReady() { /* setup */ }
  registerEvents() { /* bind events */ }
}
MyPage.initiateWhenReady(['page.slug'])
```

```javascript
// Bad - global initialization
document.addEventListener('DOMContentLoaded', () => {
  // initialization
})
```

--------------------------------

### Preview Theme with Salla CLI

Source: https://github.com/sallaapp/theme-raed/blob/master/README.md

Use this command to preview your theme in live mode during development. Ensure you are in the theme's root folder before running.

```shell
salla theme preview
```

```shell
# Alias command for preview
salla theme p
```

--------------------------------

### Format Currency with Helper

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/localization.md

Re-demonstrates currency formatting using the salla.money utility, highlighting its adaptability to store settings.

```javascript
// Currency formatting
salla.money(99.99)
```

--------------------------------

### Get a Single Translation String

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/localization.md

Retrieve a specific translation string using its key. This is the most common way to access localized text.

```javascript
const cartLabel = salla.lang.get('blocks.header.cart');
```

--------------------------------

### Load Theme Application

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/app.md

Initializes the entire theme application, including all components and event listeners. It dispatches a 'theme::ready' event upon completion.

```javascript
app.loadTheApp();

// Listen for app ready event
document.addEventListener('theme::ready', () => {
  console.log('Theme is ready!');
});
```

--------------------------------

### Play Animation

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/anime-wrapper.md

Executes the defined animation sequence. This method must be called to start the animation and returns the Anime.js timeline object.

```javascript
play()
```

```javascript
const timeline = animation.play();
```

--------------------------------

### BasePage initiate Method

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/base-page.md

Initialize the page if it matches the allowed pages configuration. Calls onReady() and registerEvents() if the page is allowed.

```APIDOC
## initiate

### Description
Initialize the page if it matches the allowed pages configuration. Calls onReady() and registerEvents() if the page is allowed.

### Method Signature
```javascript
initiate(allowedPages)
```

### Parameters
#### Path Parameters
* **allowedPages** (array<string> or null) - Optional - Array of page slugs where this page class should run. If null, runs on all pages.

### Return Type
void

### Page Slug Examples
- `'product.single'` - Product detail page
- `'product.index'` - Products list page
- `'cart.index'` - Shopping cart page
- `'order.index'` - Order list page
- `'index'` - Home page

### Example
```javascript
const productPage = new ProductPage();
productPage.initiate(['product.single']);

// This page class only runs on product detail pages
// It logs: "The Class For (product.single) Loaded🎉"
```

```javascript
const generalPage = new GeneralPage();
generalPage.initiate(); // No restriction, runs on all pages
generalPage.initiate(null); // Equivalent to above
```
```

--------------------------------

### Detect Current Language and Direction

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/localization.md

Get the current store language and document direction. Language determines the locale, and direction affects layout.

```javascript
// Language is determined by store settings
const currentLanguage = salla.lang.current; // 'en' or 'ar'

// Direction is set based on language
const direction = document.documentElement.getAttribute('dir'); // 'ltr' or 'rtl'
```

--------------------------------

### Development Build Commands

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/README.md

Commands to initiate development builds for the theme. Use 'watch' for continuous development.

```bash
# Development build with watch
npm run watch

# Development build
npm run development

# Production build
npm run production
```

--------------------------------

### Accessible Tooltip Structure

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/tooltip.md

HTML structure for an accessible tooltip using ARIA attributes and appropriate roles. This example uses a button-like div for interaction.

```html
<div class="tooltip-toggle--clickable" aria-label="Help" role="button" tabindex="0">
  <i class="icon-help" aria-hidden="true"></i>
  <div class="tooltip-content" role="tooltip">
    <p>Help information</p>
  </div>
</div>
```

--------------------------------

### Initialize Responsive Menu Behavior

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/custom-elements.md

Sets up the responsive behavior for the navigation menu, handling overflow, visibility, and touch support.

```javascript
initializeResponsiveMenu()
```

--------------------------------

### Initialize Notification System

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/app.md

Sets up the notification or toast system. The specific implementation depends on the notification library used.

```javascript
initiateNotifier()
```

```javascript
app.initiateNotifier()
```

--------------------------------

### Initialize Dropdown Menus

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/app.md

Sets up the behavior for dropdown menu components, allowing them to be opened and closed.

```javascript
initiateDropdowns()
```

```javascript
app.initiateDropdowns()
```

--------------------------------

### initiateWhenReady Static Method

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/base-page.md

A convenience static method to create an instance and initialize it when the app is ready. It handles timing automatically, waiting for the theme::ready event if necessary.

```javascript
static initiateWhenReady(allowedPages)
```

```javascript
// Define page class
class HomePage extends BasePage {
  onReady() {
    console.log('Home page initialized');
  }
}

// Use static method for automatic initialization
HomePage.initiateWhenReady(['index']);
// Runs on home page automatically
```

```javascript
// Without page restrictions
class GlobalFooter extends BasePage {
  onReady() {
    this.setupFooterTracking();
  }
}

GlobalFooter.initiateWhenReady();
// Runs on every page
```

--------------------------------

### Set Animation Delay

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/anime-wrapper.md

Specify the delay in milliseconds before the animation starts. Supports a function for staggered delays based on element index. Returns the instance for chaining.

```javascript
animation.delay(100)  // 100ms delay

// Staggered delay based on element index
animation.delay((el, i) => i * 50)  // Each element 50ms apart
```

--------------------------------

### open

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/custom-elements.md

Displays a toast notification with product information.

```APIDOC
## open

### Description
Show toast notification.

### Method
```javascript
open(productData)
```

### Parameters
#### Path Parameters
- **productData** (object) - Required - Product information to display

**productData Structure:**
```javascript
{
  id: number,
  name: string,
  image: string,
  price: number,
  originalPrice: number,
  hasDiscount: boolean,
  isOnSale: boolean,
  quantity: number,
  url: string,
  options: array
}
```
```

--------------------------------

### initiate Method for Page Initialization

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/base-page.md

Initializes the page if it matches the allowed pages configuration. Calls onReady() and registerEvents() if the page is allowed.

```javascript
initiate(allowedPages)
```

```javascript
const productPage = new ProductPage();
productPage.initiate(['product.single']);

// This page class only runs on product detail pages
// It logs: "The Class For (product.single) Loaded🎉"
```

```javascript
const generalPage = new GeneralPage();
generalPage.initiate(); // No restriction, runs on all pages
generalPage.initiate(null); // Equivalent to above
```

--------------------------------

### Initialize Anime Instance

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/anime-wrapper.md

Create a new Anime instance targeting specific elements with optional animation configurations. Defaults include opacity from 0 to 1, staggered delays, and a 2000ms duration.

```javascript
const animation = new Anime('.card', {
  duration: 1500,
  opacity: [0, 1]
});
```

--------------------------------

### RTL Utilities in Tailwind CSS

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/localization.md

Example CSS classes from Tailwind that enable Right-to-Left (RTL) layout adjustments, such as padding and text alignment, for Arabic language support.

```css
/* RTL utilities in Tailwind */
rtl:pr-5      /* Padding-right in RTL mode */
ltr:pl-5      /* Padding-left in LTR mode */
rtl:text-right
ltr:text-left
```

--------------------------------

### Listen for Theme Ready Event

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/app.md

Listens for the custom 'theme::ready' event, which is dispatched when the theme has finished loading and initialization.

```javascript
document.addEventListener('theme::ready', () => {
  // Theme is ready for use
  console.log(window.app.status);
});
```

--------------------------------

### Instantiate App Class

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/app.md

Creates a new App instance. The constructor automatically sets `window.app = this`, making the instance globally accessible.

```javascript
const app = new App();
```

--------------------------------

### Global App Instance Access

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/app.md

Demonstrates how to access the global App instance from any script to use its utility methods.

```javascript
// Access the theme app from anywhere
window.app.log('Message from any script');
window.app.addClass('.element', 'class-name');
```

--------------------------------

### initiateMobileMenu

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/app.md

Initializes the mobile menu using the MMenu Light library, providing touch-friendly navigation for mobile devices.

```APIDOC
## initiateMobileMenu

### Description
Initializes the mobile navigation menu using the MMenu Light library.

### Method
`initiateMobileMenu()`

### Return Type
void

### Example
```javascript
app.initiateMobileMenu();
```
```

--------------------------------

### initiateModals

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/app.md

Initializes the modal or dialog components, setting up their behavior for displaying information or user interaction.

```APIDOC
## initiateModals

### Description
Initializes the modal and dialog components, setting up their behavior.

### Method
`initiateModals()`

### Return Type
void

### Example
```javascript
app.initiateModals();
```
```

--------------------------------

### Initialize Modals

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/app.md

Sets up the behavior for modal or dialog components, enabling them to be displayed and interacted with.

```javascript
initiateModals()
```

```javascript
app.initiateModals()
```

--------------------------------

### Get DOM Element or NodeList

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/app-helpers.md

Retrieves a DOM element or a NodeList of elements using a CSS selector. Handles both single and multi-element selectors, returning null if no element is found.

```javascript
element(selector)
```

```javascript
const element = app.element('.header');
const elements = app.element('.price'); // Returns NodeList if multi-selector
```

--------------------------------

### Theme Raed Application Initialization Flow

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/README.md

Illustrates the sequence of events from page load to component rendering in Theme Raed, highlighting the initialization steps managed by the main App class and page-specific subclasses.

```text
1. Page Load
   ↓
2. App.loadTheApp() initialization
   ├── Initialize mobile menu
   ├── Setup sticky header
   ├── Initialize dropdowns & modals
   ├── Setup event listeners
   └── Dispatch 'theme::ready' event
   ↓
3. Page-specific initialization
   └── BasePage subclasses (Product, Cart, Home, etc.)
   ↓
4. Component rendering & interaction
   └── Custom elements & web components
```

--------------------------------

### initiateDropdowns

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/app.md

Initializes the dropdown menu components, setting up their behavior for user interaction.

```APIDOC
## initiateDropdowns

### Description
Initializes the dropdown menu components, enabling their interactive behavior.

### Method
`initiateDropdowns()`

### Return Type
void

### Example
```javascript
app.initiateDropdowns();
```
```

--------------------------------

### Initialize Add to Cart Functionality

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/app.md

Sets up the event handlers for the add-to-cart button on product pages.

```javascript
initAddToCart()
```

```javascript
app.initAddToCart()
```

--------------------------------

### initiateNotifier

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/app.md

Sets up the notification or toast system for the application. The specific implementation details depend on the notification library used.

```APIDOC
## initiateNotifier

### Description
Initializes the toast/notification components of the application.

### Method
`initiateNotifier()`

### Return Type
void

### Example
```javascript
app.initiateNotifier();
```
```

--------------------------------

### initAddToCart

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/app.md

Sets up the functionality for the add-to-cart button, initializing handlers for adding products to the shopping cart.

```APIDOC
## initAddToCart

### Description
Initializes the handlers for the add-to-cart button functionality.

### Method
`initAddToCart()`

### Return Type
void

### Example
```javascript
app.initAddToCart();
```
```

--------------------------------

### BasePage onReady Method

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/base-page.md

Lifecycle hook called when the page is ready for initialization. Override this method to implement page initialization logic.

```APIDOC
## onReady

### Description
Lifecycle hook called when the page is ready for initialization. Override this method to implement page initialization logic.

### Method Signature
```javascript
onReady()
```

### Return Type
void

### Usage
This method is called during `initiate()` and provides the main entry point for page setup. Override it in subclasses to run initialization code.

### Example
```javascript
class ProductPage extends BasePage {
  onReady() {
    console.log('Product page is ready');
    this.initImageSlider();
    this.setupPriceWatcher();
  }
}
```
```

--------------------------------

### Product Form Data Object

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/types.md

Represents the data structure for form submissions related to product operations, including product ID, quantity, and selected options. This is used for operations like getting product prices.

```javascript
{
  product_id: string,
  quantity: string,
  options: {
    [key: string]: string
  }
}
```

--------------------------------

### App Constructor

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/app.md

Creates a new App instance. The constructor automatically sets `window.app = this`, making the instance globally accessible.

```APIDOC
## App Constructor

### Description
Creates a new App instance and makes it globally accessible via `window.app`.

### Method
```javascript
constructor()
```

### Example
```javascript
const app = new App();
```
```

--------------------------------

### Configure Image Display Size

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/configuration.md

This JSON snippet shows the configuration structure for a dropdown list setting that controls how images are displayed in an items list. It includes the setting ID, type, format, label, and an example of a selected option.

```json
{
  "id": "squar_photo_bg_image_size",
  "type": "items",
  "format": "dropdown-list",
  "label": "طريقة عرض الصور في قسم قائمة عناصر",
  "selected": [{ "label": "...", "value": "contain" }],
  "options": [ /* ... */ ],
  "required": true
}
```

--------------------------------

### Initialize Tooltip System

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/tooltip.md

Exports the default function to initialize the tooltip system for the entire page. This function sets up the necessary event listeners.

```javascript
export default function toolTip()
```

--------------------------------

### Cart Item Form Structure for Submission

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/cart-page.md

This HTML structure represents a single cart item's form, which is used for validation during cart submission. Ensure each form has an ID starting with 'item-' and includes necessary Salla components.

```html
<form id="item-123">
  <salla-product-options></salla-product-options>
  <salla-quantity-input></salla-quantity-input>
</form>
<button id="cart-submit">Proceed to Checkout</button>
```

--------------------------------

### Multiple Pages in One File

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/base-page.md

Define and initialize multiple page-specific classes within a single file. Each class extends BasePage and can have its own `onReady` logic. Use `initiateWhenReady` with an array of page slugs to control when each class is activated.

```javascript
import BasePage from './base-page';

class ProductPage extends BasePage {
  onReady() {
    console.log('Product page ready');
  }
}

class ProductsListPage extends BasePage {
  onReady() {
    console.log('Products list ready');
  }
}

// Initialize both
ProductPage.initiateWhenReady(['product.single']);
ProductsListPage.initiateWhenReady(['product.index']);
```

--------------------------------

### Initialize Images Zooming

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/product-page.md

The initImagesZooming method sets up image magnification on desktop devices. It's controlled by a theme setting and reinitializes on window resize or slider changes, with debouncing for performance.

```javascript
initImagesZooming()
```

--------------------------------

### App Class API

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/DOCUMENTATION_INDEX.md

Documentation for the App class, which extends AppHelpers and includes over 10 methods for theme initialization and management, such as mobile menu, sticky header, and modals. It also documents the 'theme::ready' custom event.

```APIDOC
## Class: App

### Description
Initializes and manages theme functionalities.

### Extends
AppHelpers

### Methods
10+ initialization and management methods.

### Topics
Theme initialization, mobile menu, sticky header, modals.

### Events
theme::ready custom event.

### Example Code
App initialization patterns.
```

--------------------------------

### Animate Elements Using Anime Wrapper with App Class

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/anime-wrapper.md

Integrate the Anime wrapper with the App class to select elements and apply animations. Requires importing the Anime wrapper and using app.element() for selection.

```javascript
import Anime from './partials/anime';

// Select elements with app
const cards = app.element('.card');

// Animate with Anime wrapper
const animation = new Anime(cards)
  .opacity([0, 1])
  .translateY([-30, 0])
  .duration(500)
  .stagger(100)
  .play();
```

--------------------------------

### Product Class onReady Method

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/product-page.md

The onReady method is part of the Product class lifecycle. It sets up page elements, validates product options, and initializes image zooming if enabled.

```javascript
onReady()
```

--------------------------------

### salla-product-options

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/custom-elements.md

Renders the product options/variants selector. Emits a 'changed' event when option selection changes.

```APIDOC
### salla-product-options

**Description:** Renders product options/variants selector.

**Events:**
- `changed` - When option selection changes
```

--------------------------------

### Format Numbers with Helper

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/localization.md

Re-demonstrates number formatting using the salla.helpers.number utility, showing its output for Arabic and English locales.

```javascript
// Format numbers with current language
salla.helpers.number(1000)
// English: "1,000"
// Arabic: "١٬٠٠٠"
```

--------------------------------

### AddToCartsToast init Method

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/custom-elements.md

Initializes the `AddToCartsToast` element by loading translations and setting up necessary event listeners for its functionality.

```javascript
init()
```

--------------------------------

### Initialize Collapsible Sections

Source: https://github.com/sallaapp/theme-raed/blob/master/_autodocs/api-reference/app.md

Sets up the behavior for collapsible sections or accordions, allowing content to be shown or hidden.

```javascript
initiateCollapse()
```

```javascript
app.initiateCollapse()
```