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

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 }}
+    />
+  );
+}

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

@@ -0,0 +1,97 @@
+import { memo, useState, useEffect } from 'react';
+import type { Breadcrumb } from '../../types';
+import { Link } from './Link';
+
+const MAX_VISIBLE_ITEMS = 4;
+
+interface BreadcrumbTrailProps {
+  items: Breadcrumb[];
+  className?: string;
+}
+
+const ChevronIcon = () => (
+  <svg
+    version="1.1"
+    xmlns="http://www.w3.org/2000/svg"
+    width="32"
+    height="32"
+    viewBox="0 0 32 32"
+    aria-hidden="true"
+  >
+    <title>keyboard_arrow_left</title>
+    <path d="M20.563 22.104l-1.875 1.875-8-8 8-8 1.875 1.875-6.125 6.125z"></path>
+  </svg>
+);
+
+function truncateItems(items: Breadcrumb[]): Breadcrumb[] {
+  if (items.length <= MAX_VISIBLE_ITEMS) return items;
+
+  return [items[0], { name: '…', url: '' }, ...items.slice(-2)];
+}
+
+export const BreadcrumbTrail = memo(function BreadcrumbTrail({
+  items,
+  className,
+}: BreadcrumbTrailProps) {
+  const [expanded, setExpanded] = useState(false);
+
+  useEffect(() => {
+    setExpanded(false);
+  }, [items]);
+
+  if (items.length === 0) return null;
+
+  const displayItems = expanded ? items : truncateItems(items);
+
+  return (
+    <nav className={className ?? 'breadcrumbs w-full py-5'} aria-label="Breadcrumb">
+      <ol className="s-breadcrumb-wrapper" itemScope itemType="https://schema.org/BreadcrumbList">
+        {displayItems.map((item, index) => {
+          const isLast = index === displayItems.length - 1;
+          const isEllipsis = item.name === '…' && !item.url;
+
+          return (
+            <li
+              key={`${item.url}-${item.name}`}
+              className={['s-breadcrumb-item', isEllipsis ? 'cursor-pointer select-none' : ''].join(
+                ' '
+              )}
+              aria-current={isLast ? 'page' : undefined}
+              itemProp="itemListElement"
+              itemScope
+              itemType="https://schema.org/ListItem"
+            >
+              {isEllipsis ? (
+                <button
+                  type="button"
+                  onClick={() => {
+                    setExpanded(true);
+                  }}
+                  className="inline-flex items-center gap-1 hover:underline"
+                  aria-label="Show all breadcrumbs"
+                >
+                  <span aria-hidden="true" className="text-xs">
+                    •••
+                  </span>
+                </button>
+              ) : isLast ? (
+                <span itemProp="name">{item.name}</span>
+              ) : (
+                <>
+                  <Link to={item.url} itemProp="item">
+                    <span itemProp="name">{item.name}</span>
+                  </Link>
+                  <span aria-hidden="true" className="s-breadcrumb-arrow inline-flex">
+                    <ChevronIcon />
+                  </span>
+                  <meta itemProp="position" content={String(index + 1)} />
+                </>
+              )}
+              {isLast && <meta itemProp="position" content={String(index + 1)} />}
+            </li>
+          );
+        })}
+      </ol>
+    </nav>
+  );
+});

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

@@ -0,0 +1,8 @@
+/**
+ * Renders a currency symbol.
+ * SAR uses the dedicated `sicon-sar` icon; all other currencies render as text.
+ */
+export function CurrencySymbol({ currency }: { currency: string }) {
+  if (currency === 'SAR') return <i className="sicon-sar" aria-hidden="true" />;
+  return <span>{currency}</span>;
+}

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

@@ -0,0 +1,122 @@
+import { Suspense, memo, use, type ReactNode } from 'react';
+
+export interface DeferredDataProps<T> {
+  promise: Promise<T> | T;
+  fallback: ReactNode;
+  children: (data: T) => ReactNode;
+}
+
+const DEFERRED_KEY = Symbol.for('twilight.deferred');
+
+interface DeferredState<T> {
+  status: 'pending' | 'success' | 'error';
+  value?: T;
+  error?: unknown;
+}
+
+export interface DeferredPromise<T> extends Promise<T> {
+  [DEFERRED_KEY]?: DeferredState<T>;
+}
+
+const seenPromises = typeof WeakSet !== 'undefined' ? new WeakSet() : null;
+
+function defer<T>(promise: Promise<T>): DeferredPromise<T> {
+  const existing = (promise as DeferredPromise<T>)[DEFERRED_KEY];
+  if (existing) return promise as DeferredPromise<T>;
+
+  const state: DeferredState<T> = { status: 'pending' };
+
+  const deferred = promise as DeferredPromise<T>;
+  deferred[DEFERRED_KEY] = state;
+
+  promise.then(
+    (value) => {
+      state.status = 'success';
+      state.value = value;
+    },
+    (error) => {
+      state.status = 'error';
+      state.error = error;
+    }
+  );
+
+  return deferred;
+}
+
+const DeferredRenderer = memo(function DeferredRenderer<T>({
+  promise,
+  children,
+}: {
+  promise: DeferredPromise<T>;
+  children: (data: T) => ReactNode;
+}) {
+  const state = promise[DEFERRED_KEY];
+
+  if (state?.status === 'success') {
+    return children(state.value!);
+  }
+
+  if (state?.status === 'error') {
+    throw state.error;
+  }
+
+  const data = use(promise);
+  return children(data);
+}) as <T>(props: { promise: DeferredPromise<T>; children: (data: T) => ReactNode }) => ReactNode;
+
+function DeferredFallback<T>({
+  promise,
+  fallback,
+  children,
+}: {
+  promise: DeferredPromise<T>;
+  fallback: ReactNode;
+  children: (data: T) => ReactNode;
+}) {
+  const state = promise[DEFERRED_KEY];
+  if (state?.status === 'success') {
+    return children(state.value!);
+  }
+  return <>{fallback}</>;
+}
+
+export function resolveDeferred<T>(
+  promiseOrValue: Promise<T> | T | undefined
+): T | Promise<T> | undefined {
+  if (promiseOrValue == null || !(promiseOrValue instanceof Promise)) return promiseOrValue;
+  const deferred = defer(promiseOrValue);
+  const state = deferred[DEFERRED_KEY];
+  if (state?.status === 'success') return state.value as T;
+  return promiseOrValue;
+}
+
+export function DeferredData<T>({ promise, fallback, children }: DeferredDataProps<T>) {
+  if (!(promise instanceof Promise)) {
+    return children(promise);
+  }
+
+  if (seenPromises && promise instanceof Promise) seenPromises.add(promise);
+
+  const deferred = defer(promise);
+  const state = deferred[DEFERRED_KEY];
+
+  if (state?.status === 'success') {
+    return children(state.value!);
+  }
+
+  if (state?.status === 'error') {
+    throw state.error;
+  }
+
+  return (
+    <Suspense
+      fallback={
+        <DeferredFallback promise={deferred} fallback={fallback}>
+          {children}
+        </DeferredFallback>
+      }
+    >
+      <DeferredRenderer promise={deferred}>{children}</DeferredRenderer>
+    </Suspense>
+  );
+}

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

@@ -0,0 +1,69 @@
+import type { ComponentType, ReactNode } from 'react';
+import { useTranslation } from '../../providers/I18nProvider';
+
+const LINK_STYLE: React.CSSProperties = {
+  backgroundColor: 'var(--color-primary)',
+  color: 'var(--color-primary-reverse, #ffffff)',
+};
+
+export interface ErrorPageProps {
+  code?: string | number;
+  title?: string;
+  message?: string;
+  actionText?: string;
+  actionHref?: string;
+  showAction?: boolean;
+  LinkComponent?: ComponentType<{
+    to: string;
+    className?: string;
+    style?: React.CSSProperties;
+    children: ReactNode;
+  }>;
+  children?: ReactNode;
+}
+
+export function ErrorPage({
+  code,
+  title,
+  message,
+  actionText,
+  actionHref = '/',
+  showAction = true,
+  LinkComponent,
+  children,
+}: ErrorPageProps) {
+  const { t } = useTranslation();
+
+  const resolvedTitle = title ?? t(`common.errors.${code}`) ?? 'Error';
+  const resolvedMessage =
+    message ?? t('common.errors.error_occurred') ?? 'An unexpected error occurred.';
+  const resolvedActionText = actionText ?? t('common.elements.back_home') ?? 'Back to Home';
+
+  const linkClassName =
+    'inline-flex items-center px-6 py-3 rounded-lg transition-opacity hover:opacity-90';
+
+  return (
+    <div className="container py-16 text-center">
+      {code && (
+        <h1 className="text-6xl font-bold text-gray-300 mb-4" data-testid="error-code">
+          {code}
+        </h1>
+      )}
+      <h2 className="text-2xl font-semibold text-gray-700 mb-4">{resolvedTitle}</h2>
+      <p className="text-gray-500 mb-8">{resolvedMessage}</p>
+
+      {children}
+
+      {showAction &&
+        (LinkComponent ? (
+          <LinkComponent to={actionHref} className={linkClassName} style={LINK_STYLE}>
+            {resolvedActionText}
+          </LinkComponent>
+        ) : (
+          <a href={actionHref} className={linkClassName} style={LINK_STYLE}>
+            {resolvedActionText}
+          </a>
+        ))}
+    </div>
+  );
+}