@salla.sa/twilight-theme-engine 1.0.85 → 1.0.86

package/tailwind/components/cart/CartSummary.tsx.txt

@@ -0,0 +1,269 @@
+import { useCallback } from 'react';
+import { HookSlot } from '../../hooks/HookSlot';
+import { useTranslation } from '../../providers/I18nProvider';
+import { useCoupon } from '../../hooks/useCoupon';
+import { useMoney } from '../../hooks/useMoney';
+import { stripUnsafeHtml } from '../../utils/sanitize';
+import { SallaLoyalty } from '@salla.sa/twilight-components-react/loyalty';
+import { SallaGifting } from '@salla.sa/twilight-components-react/gifting';
+import { SallaButton } from '@salla.sa/twilight-components-react/button';
+import { SallaTieredOffer } from '@salla.sa/twilight-components-react/tiered-offer';
+import type { Cart } from '../../types';
+
+interface CartSummaryProps {
+  cart: Cart;
+  applyCouponEnabled?: boolean;
+  taxAmount?: number;
+  loyalty?: Cart['loyalty'];
+  gift?: Cart['gift'];
+  loyaltyPoints?: number;
+}
+
+export function CartSummary({
+  cart,
+  applyCouponEnabled = true,
+  taxAmount,
+  loyalty,
+  gift,
+  loyaltyPoints,
+}: CartSummaryProps) {
+  const { t } = useTranslation();
+  const { format } = useMoney();
+
+  const handleCartSubmit = useCallback(async () => {
+    // Twig's cart.js: a submit with an empty required option fails and the SDK resets the cart.
+    const forms = document.querySelectorAll<HTMLFormElement>('form[id^="item-"]');
+    if (![...forms].every((form) => form.reportValidity())) {
+      window.salla?.notify.error(window.salla.lang.get('common.messages.required_fields'));
+      return;
+    }
+    try {
+      await window.salla?.cart.submit();
+    } catch {
+      // Error handling
+    }
+  }, []);
+
+  return (
+    <div className="sticky top-24 w-full lg:w-96 rtl:lg:mr-8 ltr:lg:ml-8">
+      <HookSlot name="cart:summary.start" />
+      {cart.free_shipping_bar && <FreeShippingBar freeShippingBar={cart.free_shipping_bar} />}
+
+      {/* Twig: {% if loyalty and user.loyalty_points %} — top-level page vars rendered inside sidebar */}
+      {loyalty && loyaltyPoints && (
+        <div className="shadow-default mb-5 rounded-md p-3 xs:p-7 bg-white">
+          <SallaLoyalty
+            customerPoints={loyaltyPoints}
+            prizePoints={loyalty.prize.points}
+            prizeTitle={loyalty.prize.title}
+          />
+        </div>
+      )}
+
+      {/* Twig: {{gift.enabled ? '' : 'hidden'}} — top-level page var rendered inside sidebar */}
+      {gift?.enabled && (
+        <div id="cart-gifting" className="shadow-default bg-white xs:p-2 rounded-md mb-5 relative">
+          <SallaGifting
+            id="salla-gifting"
+            className="mt-5"
+            widgetTitle={t('pages.cart.gift_widget_title', 'Send as a gift')}
+            widgetSubtitle={gift.text}
+            {...(gift.type ? { [gift.type + 'Products']: true } : {})}
+            vertical
+          />
+        </div>
+      )}
+
+      <div className="shadow-default bg-white p-5 xs:p-7 rounded-md mb-5 relative transition-height duration-1000">
+        <h2 className="font-bold text-sm mb-5">{t('pages.cart.summary', 'Order Summary')}</h2>
+
+        <div className="flex justify-between text-sm mb-5">
+          <span className="text-gray-500">
+            {taxAmount
+              ? t('pages.cart.items_total_without_tax', 'Items total (excl. tax)')
+              : t('pages.cart.items_total', 'Items total')}
+          </span>
+          <b id="sub-total">{format(cart.sub_total)}</b>
+        </div>
+
+        {cart.options?.length > 0 && (
+          <div className="flex justify-between text-sm mb-5">
+            <span className="text-gray-500">
+              {t('pages.cart.order_options_total', 'Options total')}
+            </span>
+            <b id="cart-options-total">{format(cart.options_total ?? undefined)}</b>
+          </div>
+        )}
+
+        {cart.has_shipping && (
+          <div id="shipping-cost" className="flex justify-between text-sm mb-5">
+            <span className="text-gray-500">{t('pages.cart.shipping_cost', 'Shipping cost')}</span>
+            <b>{format(cart.real_shipping_cost)}</b>
+          </div>
+        )}
+
+        {applyCouponEnabled && <CouponInput initialCoupon={cart.coupon ?? undefined} />}
+
+        {!!cart.total_discount && (
+          <div id="total-discount" className="flex justify-between text-sm">
+            <span className="text-gray-500 block h-10">{t('pages.cart.discount', 'Discount')}</span>
+            <b>- {format(cart.total_discount)}</b>
+          </div>
+        )}
+
+        {!!taxAmount && (
+          <div className="flex justify-between text-sm mb-5">
+            <span className="text-gray-500">
+              {t('pages.cart.VAT_tax_amount', 'VAT Tax Amount')}
+            </span>
+            <b id="tax-amount">{format(taxAmount)}</b>
+          </div>
+        )}
+
+        <div className="flex justify-between text-lg mb-5">
+          <span className="text-gray-500">{t('pages.cart.final_total', 'Total')}</span>
+          <b data-cart-total>{format(cart.total)}</b>
+        </div>
+
+        <div className="cart-submit-wrap">
+          <HookSlot name="cart:submit.start" />
+          <SallaButton
+            id="cart-submit"
+            loaderPosition="center"
+            width="wide"
+            onClick={handleCartSubmit}
+          >
+            {t('pages.cart.complete_order', 'Complete Order')}
+          </SallaButton>
+          <HookSlot name="cart:submit.end" />
+        </div>
+
+        <HookSlot name="cart:summary.end" />
+      </div>
+
+      <SallaTieredOffer />
+    </div>
+  );
+}
+
+function FreeShippingBar({
+  freeShippingBar,
+}: {
+  freeShippingBar: NonNullable<Cart['free_shipping_bar']>;
+}) {
+  const isFree = freeShippingBar.has_free_shipping;
+  const { t } = useTranslation();
+
+  return (
+    <div className="shadow-default bg-white p-5 xs:p-7 rounded-md mb-5 relative" id="free-shipping">
+      <div className="flex rtl:space-x-reverse space-x-3 items-center">
+        <i className="bg-primary text-white rounded-icon sicon-shipping-fast"></i>
+        <div className="flex-1">
+          <h4 className="shipping-item font-bold text-sm mb-1.5">
+            {t('pages.cart.free_shipping', 'Free Shipping')}
+          </h4>
+          <p className="shipping-item text-sm text-gray-500">
+            {isFree ? (
+              <>
+                <span
+                  id="free-shipping-msg"
+                  dangerouslySetInnerHTML={{
+                    __html: stripUnsafeHtml(
+                      t('pages.cart.has_free_shipping', 'You have free shipping!')
+                    ),
+                  }}
+                />
+                <span className="emoji" id="free-shipping-applied">
+                  🎉
+                </span>
+              </>
+            ) : (
+              <span
+                id="free-shipping-msg"
+                dangerouslySetInnerHTML={{
+                  __html: stripUnsafeHtml(
+                    t(
+                      'pages.cart.free_shipping_alert',
+                      'Get free shipping when you add :amount more'
+                    ).replace(':amount', String(freeShippingBar.remaining))
+                  ),
+                }}
+              />
+            )}
+          </p>
+        </div>
+      </div>
+      {!isFree && (
+        <div className="mt-8 bg-border-color rounded-full" id="free-shipping-bar">
+          <div
+            className="progress-bg transition-all duration-500 h-2.5 bg-primary relative rounded-full flex justify-end"
+            style={{ width: `${freeShippingBar.percent}%` }}
+          >
+            <i className="inline-block sicon-shipping-fast absolute -top-5 rtl:left-0 ltr:right-0"></i>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+function CouponInput({ initialCoupon }: { initialCoupon?: string }) {
+  const { t } = useTranslation();
+  const { value, error, apply, remove } = useCoupon();
+
+  // Use initial coupon from cart if available
+  const appliedCoupon = value ?? initialCoupon;
+
+  const handleApplyCoupon = useCallback(
+    async (event: React.FormEvent<HTMLFormElement>) => {
+      event.preventDefault();
+      const formData = new FormData(event.currentTarget);
+      const code = formData.get('coupon') as string;
+      if (code?.trim()) {
+        await apply(code.trim());
+      }
+    },
+    [apply]
+  );
+
+  const handleRemoveCoupon = useCallback(async () => {
+    await remove();
+  }, [remove]);
+
+  return (
+    <form className="border-t border-gray-200 border-b py-5 mb-5" onSubmit={handleApplyCoupon}>
+      <label htmlFor="coupon-input" className="block text-sm">
+        {t('pages.cart.have_coupon', 'Have a coupon?')}
+      </label>
+      <div className="mt-2.5 relative">
+        <input
+          placeholder={t('pages.cart.coupon_placeholder', 'Enter coupon code')}
+          disabled={!!appliedCoupon}
+          className="rtl:pl-24 ltr:pr-24 form-input"
+          defaultValue={appliedCoupon}
+          id="coupon-input"
+          name="coupon"
+          aria-label={t('pages.cart.apply_coupon', 'Apply coupon')}
+          type="text"
+        />
+
+        <SallaButton
+          type="submit"
+          className={`btn--coupon ${appliedCoupon ? 'has-coupon btn--danger' : 'has-not-coupon btn--default'}`}
+          loaderPosition="center"
+          onClick={appliedCoupon ? handleRemoveCoupon : undefined}
+        >
+          <span className="coupon-text">
+            {appliedCoupon ? '' : t('pages.cart.apply_coupon_btn', 'Apply')}
+          </span>
+          {appliedCoupon && <i className="sicon-cancel icon text-xl w-8"></i>}
+        </SallaButton>
+      </div>
+      {error && (
+        <span className="text-xs text-red-700" id="coupon-error">
+          {error}
+        </span>
+      )}
+    </form>
+  );
+}

package/tailwind/components/cart/PreOrderNotification.tsx.txt

@@ -0,0 +1,16 @@
+import { useTranslation } from '../../providers/I18nProvider';
+
+export function PreOrderNotification() {
+  const { t } = useTranslation();
+
+  return (
+    <salla-alert
+      className="mb-5"
+      message={t(
+        'pages.cart.pre_order_shipping',
+        'Your order will be shipped when the pre-order product becomes available in the store.'
+      )}
+      variant="info"
+    />
+  );
+}

package/tailwind/components/cart/PriceQuoteButton.tsx.txt

@@ -0,0 +1,21 @@
+import { SallaButton } from '@salla.sa/twilight-components-react/button';
+import { useTranslation } from '../../providers/I18nProvider';
+
+const handlePriceQuote = async () => {
+  await window.salla?.cart.api.priceQuote?.();
+};
+
+export function PriceQuoteButton() {
+  const { t } = useTranslation();
+
+  return (
+    <SallaButton
+      id="request-price-quote-btn"
+      className="btn--oval btn--md"
+      fill="outline"
+      onClick={handlePriceQuote}
+    >
+      {t('pages.cart.request_price_quote', 'Request for Quotation')}
+    </SallaButton>
+  );
+}

package/tailwind/components/cart/SeoCartWidget.tsx.txt

@@ -0,0 +1,99 @@
+import { useEffect } from 'react';
+import { useTwilight } from '../../providers/TwilightProvider';
+import { useTranslation } from '../../providers/I18nProvider';
+import type { Cart } from '../../types';
+import { pushCheckoutEvent } from '../../lib/analytics/gtm';
+import { onSallaEvent } from '../../utils/sdk-helpers';
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface SeoCartWidgetProps {
+  /**
+   * Cart data from the TanStack Router loader — no extra fetch needed.
+   */
+  cart: Cart;
+  /**
+   * Current checkout funnel step.
+   * Defaults to `1` (cart view) — CartPage always passes this default.
+   * The widget internally listens to Salla SDK events to promote to 2 / 3.
+   */
+  step?: 1 | 2 | 3;
+}
+
+// ─── Page title translation keys (mirrors PHP SeoCartWidget::$pageTitle) ─────
+
+/**
+ * Matches the PHP backend exactly:
+ * ```php
+ * protected $pageTitle = [
+ *   self::STEP_CART     => 'common.titles.cart',
+ *   self::STEP_SHIPPING => 'common.titles.shipping',
+ *   self::STEP_PAYMENT  => 'common.titles.checkout',
+ * ];
+ * ```
+ */
+const PAGE_TITLE_KEYS: Record<1 | 2 | 3, string> = {
+  1: 'common.titles.cart',
+  2: 'common.titles.shipping',
+  3: 'common.titles.checkout',
+};
+
+// ─── Component ────────────────────────────────────────────────────────────────
+
+/**
+ * SeoCartWidget — Null-rendering analytics side-effect component.
+ *
+ * Responsibilities:
+ * 1. Fires a GTM `checkout` event (step 1) on cart page load.
+ * 2. Listens to Salla SDK checkout overlay events to fire steps 2 & 3.
+ * 3. Updates `document.title` to reflect the cart context.
+ *
+ * Architecture:
+ * - Lives in `theme-engine` so all themes using the engine get GTM tracking.
+ * - Mounted directly inside `CartPage`, which already has loader data.
+ * - `window.dataLayer` must be initialised by the store's GTM embed snippet;
+ *   the widget initialises it as a safe-guard but does NOT inject GTM itself.
+ * - Must be mounted inside `<TwilightProvider>` (reads `currency` from context).
+ *
+ * @example
+ * // In CartPage:
+ * <SeoCartWidget cart={cart} />
+ */
+export function SeoCartWidget({ cart, step = 1 }: SeoCartWidgetProps) {
+  const { store, currency } = useTwilight();
+  const { t } = useTranslation();
+  const currencyCode = currency?.code ?? 'SAR';
+
+  // ── Fire GTM checkout event for step 1 (or whichever step is passed) ────────
+  useEffect(() => {
+    pushCheckoutEvent(step, cart, currencyCode);
+    // Re-fire if the cart id, contents, or currency changes
+  }, [step, cart, currencyCode]);
+
+  // ── Subscribe to Salla SDK checkout step events (steps 2 & 3) ──────────────
+  // Fires GTM events when the user advances through the checkout overlay.
+  useEffect(() => {
+    const onShipping = () => pushCheckoutEvent(2, cart, currencyCode);
+    const onPayment = () => pushCheckoutEvent(3, cart, currencyCode);
+
+    const offShipping = onSallaEvent('checkout::step.shipping', onShipping);
+    const offPayment = onSallaEvent('checkout::step.payment', onPayment);
+
+    return () => {
+      offShipping();
+      offPayment();
+    };
+  }, [cart, currencyCode]);
+
+  // ── Update document title — mirrors PHP SeoCartWidget::$pageTitle ───────────
+  // Step 1 → 'common.titles.cart'    (e.g. "Cart")
+  // Step 2 → 'common.titles.shipping' (e.g. "Shipping")
+  // Step 3 → 'common.titles.checkout' (e.g. "Checkout")
+  useEffect(() => {
+    const storeTitle = store.meta?.title || store.name;
+    const stepTitle = t(PAGE_TITLE_KEYS[step], PAGE_TITLE_KEYS[step]);
+    document.title = storeTitle ? `${stepTitle} - ${storeTitle}` : stepTitle;
+  }, [step, store.meta?.title, store.name, t]);
+
+  return null;
+}

package/tailwind/components/cart/index.ts.txt

@@ -0,0 +1,11 @@
+import { LazyCartItem, LazyCartSummary, LazySeoCartWidget } from './lazy';
+
+// Lazy-loaded cart components (code-split)
+export {
+  LazyCartItem as CartItem,
+  LazyCartSummary as CartSummary,
+  LazySeoCartWidget as SeoCartWidget,
+};
+
+// Types are co-located with components (not in types.ts)
+export type { SeoCartWidgetProps } from './SeoCartWidget';

package/tailwind/components/cart/lazy.ts.txt

@@ -0,0 +1,15 @@
+import { lazy } from 'react';
+
+/**
+ * Lazy-loaded cart components
+ * Use these for code-splitting cart sections
+ */
+export const LazyCartItem = lazy(() => import('./CartItem').then((m) => ({ default: m.CartItem })));
+
+export const LazyCartSummary = lazy(() =>
+  import('./CartSummary').then((m) => ({ default: m.CartSummary }))
+);
+
+export const LazySeoCartWidget = lazy(() =>
+  import('./SeoCartWidget').then((m) => ({ default: m.SeoCartWidget }))
+);

package/tailwind/components/collapse/Collapse.tsx.txt

@@ -0,0 +1,95 @@
+/**
+ * Collapse Component
+ *
+ * A controlled collapsible content area with smooth animation.
+ *
+ * @example
+ * ```tsx
+ * function FAQItem({ question, answer }) {
+ *   const [isOpen, setIsOpen] = useState(false);
+ *
+ *   return (
+ *     <Collapse isOpen={isOpen} onToggle={() => setIsOpen(!isOpen)}>
+ *       <Collapse.Trigger>
+ *         <div className="flex justify-between">
+ *           <span>{question}</span>
+ *           <span>{isOpen ? '−' : '+'}</span>
+ *         </div>
+ *       </Collapse.Trigger>
+ *       <Collapse.Content>
+ *         <p>{answer}</p>
+ *       </Collapse.Content>
+ *     </Collapse>
+ *   );
+ * }
+ * ```
+ */
+
+import { type ReactNode, type HTMLAttributes, type ButtonHTMLAttributes } from 'react';
+
+export interface CollapseProps {
+  isOpen: boolean;
+  onToggle: () => void;
+  children: ReactNode;
+  /**
+   * Additional className for the collapse container
+   */
+  className?: string;
+}
+
+export function Collapse({ children, className }: CollapseProps) {
+  return <div className={`overflow-hidden ${className || ''}`}>{children}</div>;
+}
+
+// Trigger Component
+export interface CollapseTriggerProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  children: ReactNode;
+  isOpen?: boolean;
+  onToggle?: () => void;
+}
+
+Collapse.Trigger = function CollapseTrigger({
+  children,
+  isOpen = false,
+  onToggle,
+  className,
+  ...props
+}: CollapseTriggerProps) {
+  return (
+    <button
+      type="button"
+      onClick={onToggle}
+      className={`block cursor-pointer border-0 bg-transparent p-0 text-start ${className || ''}`}
+      aria-expanded={isOpen}
+      {...props}
+    >
+      {children}
+    </button>
+  );
+};
+
+// Content Component
+export interface CollapseContentProps extends HTMLAttributes<HTMLDivElement> {
+  children: ReactNode;
+  isOpen?: boolean;
+}
+
+Collapse.Content = function CollapseContent({
+  children,
+  isOpen = false,
+  className,
+  ...props
+}: CollapseContentProps) {
+  return (
+    <div
+      className={`transition-all duration-200 ease-out ${
+        isOpen ? 'grid grid-rows-[1fr] opacity-100' : 'grid grid-rows-[0fr] opacity-0'
+      } ${className || ''}`}
+      {...props}
+    >
+      <div className="overflow-hidden">
+        <div className="pb-2">{children}</div>
+      </div>
+    </div>
+  );
+};

package/tailwind/components/collapse/index.ts.txt

@@ -0,0 +1,41 @@
+/**
+ * Collapse Component System
+ *
+ * A controlled collapsible panel for FAQs, accordions, and expandable sections.
+ * Eager-loaded because it uses compound component pattern (Collapse.Trigger, Collapse.Content).
+ *
+ * @example
+ * ```tsx
+ * import { Collapse } from '@salla.sa/twilight-theme-engine/components/collapse';
+ *
+ * function Accordion() {
+ *   const [openId, setOpenId] = useState(null);
+ *
+ *   return (
+ *     <div className="space-y-2">
+ *       {items.map((item) => (
+ *         <Collapse
+ *           key={item.id}
+ *           isOpen={openId === item.id}
+ *           onToggle={() => setOpenId(openId === item.id ? null : item.id)}
+ *         >
+ *           <Collapse.Trigger isOpen={openId === item.id} onToggle={() => setOpenId(item.id)}>
+ *             <h3>{item.title}</h3>
+ *           </Collapse.Trigger>
+ *           <Collapse.Content isOpen={openId === item.id}>
+ *             <p>{item.content}</p>
+ *           </Collapse.Content>
+ *         </Collapse>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+
+export {
+  Collapse,
+  type CollapseProps,
+  type CollapseTriggerProps,
+  type CollapseContentProps,
+} from './Collapse';

package/tailwind/components/common/Breadcrumb.tsx.txt

@@ -0,0 +1,27 @@
+import type { Page } from '../../types';
+import { useBreadcrumbs } from '../../hooks/useBreadcrumbs';
+import { useTwilight } from '../../providers/TwilightProvider';
+import { BreadcrumbTrail } from './BreadcrumbTrail';
+import { BreadcrumbJsonLd } from './BreadcrumbJsonLd';
+
+export interface BreadcrumbProps {
+  page?: Page | null;
+  className?: string;
+}
+
+export function Breadcrumb({ page, className }: BreadcrumbProps) {
+  const { theme, store } = useTwilight();
+  const breadcrumbsEnabled = theme.settings.is_breadcrumbs_enabled ?? true;
+  const origin = store.url;
+
+  const items = useBreadcrumbs(page);
+
+  if (!breadcrumbsEnabled) return null;
+
+  return (
+    <>
+      <BreadcrumbTrail items={items} className={className} />
+      <BreadcrumbJsonLd items={items} origin={origin} />
+    </>
+  );
+}

package/tailwind/components/common/BreadcrumbJsonLd.tsx.txt

@@ -0,0 +1,40 @@
+import type { Breadcrumb } from '../../types';
+
+interface BreadcrumbJsonLdProps {
+  items: Breadcrumb[];
+  origin: string;
+}
+
+function toAbsoluteUrl(origin: string, path: string): string {
+  if (path.startsWith('http')) return path;
+  return origin + path;
+}
+
+export function BreadcrumbJsonLd({ items, origin }: BreadcrumbJsonLdProps) {
+  if (items.length === 0) return null;
+
+  const schema = {
+    '@context': 'https://schema.org',
+    '@type': 'BreadcrumbList',
+    itemListElement: items.map((item, index) => {
+      const isLast = index === items.length - 1;
+      const url = toAbsoluteUrl(origin, item.url);
+      return {
+        '@type': 'ListItem',
+        position: index + 1,
+        name: item.name,
+        ...(isLast ? { '@id': url } : { item: url }),
+      };
+    }),
+  };
+
+  const html = JSON.stringify(schema);
+
+  return (
+    <script
+      type="application/ld+json"
+      suppressHydrationWarning
+      dangerouslySetInnerHTML={{ __html: html }}
+    />
+  );
+}