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

package/tailwind/components/product/ProductGallery.tsx.txt

@@ -0,0 +1,234 @@
+import { SallaSlider } from '@salla.sa/twilight-components-react/slider';
+import { Suspense, useEffect, useMemo, useState } from 'react';
+import { registry } from '../ComponentRegistry';
+import { useTwilight } from '../../providers/TwilightProvider';
+import { useTranslation } from '../../providers/I18nProvider';
+import type { Product, ProductImage } from '../../types';
+import { Image } from '../common/Image';
+import { ImageModal } from '../modal';
+import { isNativeApp } from '../../native-app';
+
+const PRODUCT_GALLERY_KEY = 'product:gallery';
+
+export interface ProductGalleryProps {
+  product: Product;
+}
+
+type ImagePreview = { src: string; alt: string };
+type GalleryMedia = { url: string; type: 'image' | 'video' | '3d-image' };
+
+function ProductGalleryContent({ product }: ProductGalleryProps) {
+  const { t } = useTranslation();
+  const { theme } = useTwilight();
+  const sliderId = `details-slider-${product.id}`;
+  const objectFit = theme.settings.slider_background_size ?? 'cover';
+
+  // Clicking an image opens an in-app lightbox instead of navigating to the CDN URL.
+  const [preview, setPreview] = useState<ImagePreview | null>(null);
+
+  useEffect(() => {
+    const raf = requestAnimationFrame(() => {
+      const el = document.getElementById(sliderId);
+      if (!el?.parentElement) return;
+      const { parentElement, nextSibling } = el;
+      parentElement.removeChild(el);
+      parentElement.insertBefore(el, nextSibling);
+    });
+    return () => cancelAnimationFrame(raf);
+  }, [sliderId]);
+
+  // The product-details API only returns `image` (singular).
+  // Fall back so the main image always renders even without the full gallery array.
+  const images: ProductImage[] =
+    product.images && product.images.length > 0
+      ? product.images
+      : product.image?.url
+        ? [product.image]
+        : [];
+
+  const hasManyImages = images.length > 1;
+  const nativeGallery = images.flatMap<GalleryMedia>((image) => {
+    if (image.three_d_image_url) return [{ url: image.three_d_image_url, type: '3d-image' }];
+    if (image.video_url) return [{ url: image.video_url, type: 'video' }];
+    return image.url ? [{ url: image.url, type: 'image' }] : [];
+  });
+  const openNativeGallery = () => {
+    if (!isNativeApp()) return false;
+    window.salla?.event.dispatch('mobile::gallery.open', { images: nativeGallery });
+    return true;
+  };
+
+  return (
+    <div className="sidebar md:sticky top-24 w-full md:!w-2/4 rtl:ml-8 ltr:mr-8 pb-8 md:pb-16 overflow-hidden shrink-0">
+      <SallaSlider
+        id={sliderId}
+        className="details-slider rounded-md image-slider"
+        type="thumbs"
+        loop={false}
+        autoHeight
+        listenToThumbnailsOption
+        showThumbsControls={false}
+        sliderConfig={{ watchOverflow: true, autoHeight: true }}
+      >
+        {product.promotion_title && (
+          <div className="promotion-title">{product.promotion_title}</div>
+        )}
+
+        {product.calories && (
+          <div className="absolute z-[2] top-4 rtl:left-4 ltr:right-4 bg-white shadow-sm flex flex-col justify-center items-center rounded-full w-20 h-20 md:w-24 md:h-24">
+            <span className="text-red-500 text-xl leading-none font-bold">{product.calories}</span>
+            <span className="text-xs text-gray-500">
+              {t('pages.products.calories', 'Calories')}
+            </span>
+          </div>
+        )}
+
+        <div slot="items">
+          {images.map((image, index) => (
+            <ImageSlide
+              key={image.id ?? image.three_d_image_url ?? image.video_url ?? image.url}
+              image={image}
+              product={product}
+              index={index}
+              objectFit={objectFit}
+              onPreview={setPreview}
+              onNativeOpen={openNativeGallery}
+            />
+          ))}
+        </div>
+
+        {hasManyImages && (
+          <div slot="thumbs">
+            {images.map((image, index) => (
+              <ThumbSlide
+                key={image.id ?? image.three_d_image_url ?? image.video_url ?? image.url}
+                image={image}
+                index={index}
+              />
+            ))}
+          </div>
+        )}
+      </SallaSlider>
+
+      <Suspense fallback={null}>
+        <ImageModal
+          isOpen={!!preview}
+          onClose={() => setPreview(null)}
+          src={preview?.src ?? ''}
+          alt={preview?.alt}
+        />
+      </Suspense>
+    </div>
+  );
+}
+
+export function ProductGallery(props: ProductGalleryProps) {
+  const Component = useMemo(() => {
+    const resolved = registry.resolve<ProductGalleryProps>(PRODUCT_GALLERY_KEY);
+    // A theme that seeds the key with this component (register + override) would
+    // otherwise recurse into itself when it has not actually overridden anything.
+    return resolved === ProductGallery ? null : resolved;
+  }, []);
+
+  if (Component) {
+    return <Component {...props} />;
+  }
+
+  return <ProductGalleryContent {...props} />;
+}
+
+function ImageSlide({
+  image,
+  product,
+  index,
+  objectFit,
+  onPreview,
+  onNativeOpen,
+}: {
+  image: ProductImage;
+  product: Product;
+  index: number;
+  objectFit: 'cover' | 'contain';
+  onPreview: (preview: ImagePreview) => void;
+  onNativeOpen: () => boolean;
+}) {
+  const [loaded, setLoaded] = useState(false);
+  const isVideo = Boolean(image.video_url);
+
+  if (image.three_d_image_url) {
+    return (
+      // biome-ignore lint/a11y/noStaticElementInteractions: model-viewer is an interactive web component.
+      <model-viewer
+        style={{ minHeight: '500px' }}
+        className="swiper-slide model-entry w-full h-full"
+        loading="lazy"
+        camera-controls
+        touch-action="pan-y"
+        auto-rotate
+        poster={image.url || undefined}
+        src={image.three_d_image_url}
+        shadow-intensity="1"
+        alt={image.alt}
+        onClick={onNativeOpen}
+      ></model-viewer>
+    );
+  }
+
+  return (
+    <a
+      data-fslightbox={`product_${product.id}`}
+      data-img-id={image.id}
+      data-slid-index={index}
+      {...(image.video_url ? { 'data-video-src': image.video_url } : {})}
+      data-caption={image.alt}
+      data-infinite="false"
+      data-type={image.video_url ? 'youtube' : 'image'}
+      href={image.video_url || image.url}
+      // FsLightbox isn't loaded in this React theme, so the bare href would leave the SPA.
+      // Open images in an in-app lightbox; let videos open in a new tab.
+      {...(isVideo ? { target: '_blank', rel: 'noopener noreferrer' } : {})}
+      onClick={(event) => {
+        if (onNativeOpen()) {
+          event.preventDefault();
+          return;
+        }
+        if (isVideo || !image.url) return;
+        event.preventDefault();
+        onPreview({ src: image.url, alt: image.alt || product.name });
+      }}
+      aria-label={product.name}
+      className={`swiper-slide magnify-wrapper homeslider__slide ${image.video_url ? 'video-entry' : ''}`}
+    >
+      <div className={`w-full ${loaded ? '' : 'aspect-square bg-gray-100 animate-pulse'}`}>
+        <Image
+          id={String(image.id)}
+          src={image.url}
+          alt={image.alt || product.name}
+          className={`h-full w-full object-${objectFit}`}
+          aspectRatio="1/1"
+          priority={index === 0}
+          noWrapper
+          onLoad={() => setLoaded(true)}
+        />
+      </div>
+    </a>
+  );
+}
+
+function ThumbSlide({ image, index }: { image: ProductImage; index: number }) {
+  return (
+    <div
+      className={`slide--one-fourth ${image.video_url ? 'video-entry' : ''} ${image.three_d_image_url ? 'model-entry' : ''}`}
+      data-caption={image.alt}
+    >
+      <Image
+        src={image.url}
+        alt={image.alt || ''}
+        className="object-cover w-full h-full bg-gray-100 rounded-md overflow-hidden"
+        title={image.alt}
+        priority={index < 5}
+        noWrapper
+      />
+    </div>
+  );
+}

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

@@ -0,0 +1,15 @@
+import { LazyProductDetails, LazyAddToCartForm } from './lazy';
+import { ProductCard } from './ProductCard';
+import { ProductGallery } from './ProductGallery';
+
+export { ProductGallery };
+export type { ProductGalleryProps } from './ProductGallery';
+
+// Lazy-loaded product components (code-split)
+export { LazyProductDetails as ProductDetails, LazyAddToCartForm as AddToCartForm };
+
+// Eager components (lightweight, used frequently)
+export { ProductCard };
+export type { ProductCardProps, ProductCardLayout } from './ProductCard';
+
+// Types are co-located with components (not in types.ts)

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

@@ -0,0 +1,9 @@
+import { lazy } from 'react';
+
+export const LazyProductDetails = lazy(() =>
+  import('./ProductDetails').then((m) => ({ default: m.ProductDetails }))
+);
+
+export const LazyAddToCartForm = lazy(() =>
+  import('./AddToCartForm').then((m) => ({ default: m.AddToCartForm }))
+);

package/tailwind/components/snippets/AppsSnippets.tsx.txt

@@ -0,0 +1,225 @@
+import { useEffect, useMemo } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { apps, type AppSnippetRow } from '../../api/apps';
+import { installAppScope } from '../../utils/app-scope';
+import { applyThemeHookSlots } from '../../utils/theme-hook-slots';
+import { getTwilightContext } from '../../twilight/context';
+
+/** How long to wait on the SDK / settings before injecting anyway. */
+const READY_TIMEOUT_MS = 2500;
+
+// Module-level so StrictMode double-effects and remounts can't inject twice per page load.
+let injected = false;
+
+/** A snippet plus its app's scope id — the key that resolves its config bucket. */
+type OwnedSnippet = AppSnippetRow & { appScopeId: string };
+
+/**
+ * Appends raw snippet HTML to `target`, recreating each `<script>` — innerHTML-parsed
+ * scripts are flagged "already started" and never run.
+ */
+export function injectHtml(html: string, target: HTMLElement) {
+  const tpl = document.createElement('template');
+  tpl.innerHTML = html;
+  tpl.content.querySelectorAll('script').forEach((inert) => {
+    // importmap scripts can't be added post-init; the engine already injects its own.
+    if (inert.type === 'importmap') {
+      inert.remove();
+      return;
+    }
+    const script = document.createElement('script');
+    for (const attr of Array.from(inert.attributes)) {
+      script.setAttribute(attr.name, attr.value);
+    }
+    script.text = inert.text;
+    inert.replaceWith(script);
+  });
+  target.appendChild(tpl.content);
+}
+
+/**
+ * Replaces `{{customer.x}}` placeholders with SDK config `user.*` values. Non-`customer.`
+ * params are left untouched, matching the classic themes.
+ */
+export function resolveCustomerParams(content: string, params?: string[]): string {
+  if (!params?.length) return content;
+  for (const param of params) {
+    if (!param.startsWith('customer.')) continue;
+    const value = String(window.salla?.config?.get(param.replace(/^customer\./, 'user.')) ?? '');
+    // Tolerate inner whitespace (`{{ customer.email }}`); function replacement keeps `value`
+    // literal so a `$&` in customer data isn't expanded.
+    const escaped = param.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const placeholder = new RegExp(`\\{\\{\\s*${escaped}\\s*\\}\\}`, 'g');
+    content = content.replace(placeholder, () => value);
+  }
+  return content;
+}
+
+/** Resolves after `ms`, so a promise that may never settle can't block injection. */
+const timeout = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * `onReady` hangs forever if the SDK never initializes; race a timeout so a broken SDK
+ * degrades to unsubstituted placeholders instead of dropping every snippet.
+ */
+const waitForSdk = (): Promise<unknown> => {
+  const ready = window.salla?.onReady();
+  return ready ? Promise.race([ready, timeout(READY_TIMEOUT_MS)]) : Promise.resolve();
+};
+
+/** Holds the snippets' onReady callbacks until all are injected, as on Twig, where they parse before ready. */
+export function withDeferredOnReady(inject: () => void): void {
+  const sdk = window.salla;
+  const onReady = sdk?.onReady;
+  if (!sdk || typeof onReady !== 'function') return inject();
+
+  const queued: Array<() => void> = [];
+  sdk.onReady = (callback) =>
+    new Promise<void>((resolve, reject) => {
+      queued.push(() => onReady.call(sdk, callback).then(resolve, reject));
+    });
+  try {
+    inject();
+  } finally {
+    sdk.onReady = onReady;
+  }
+  queued.forEach((run) => run());
+}
+
+/**
+ * Whitelists hook slots, installs the config sandbox, then injects the inline snippets.
+ * Runs once per page load, after the SDK is ready.
+ */
+function mountSnippets(
+  owned: OwnedSnippet[],
+  clientSnippets: OwnedSnippet[],
+  buckets: Record<string, Record<string, unknown>>
+): void {
+  // Backstop for the inline head copy (see renderThemeHookSlotsScript) — that one runs at
+  // parse time, ahead of the snippet scripts; this only covers a head that didn't render.
+  applyThemeHookSlots();
+
+  // Install before any snippet resolves config. The inline SSR-head install normally got there
+  // first (with these buckets, or with none when its prefetch failed), so this either installs
+  // the factory or seeds the buckets into it. Pass the complete map once.
+  installAppScope({ apps: buckets });
+
+  // Flag every CDN scope with a missing bucket (SSR-rendered ones included).
+  const unresolved = new Set<string>();
+  for (const s of owned) {
+    if (s.url && !(s.appScopeId in buckets)) unresolved.add(s.appScopeId);
+  }
+
+  withDeferredOnReady(() => {
+    for (const snippet of clientSnippets) {
+      // Honour `place`: a head-placed snippet is often a <meta>/<link>/<style> (site
+      // verification, canonical, preload) that crawlers only read inside <head>.
+      const target = snippet.place?.includes('head') ? document.head : document.body;
+      try {
+        injectHtml(resolveCustomerParams(snippet.content, snippet.customer_parameters), target);
+      } catch (error) {
+        console.error(`[salla] failed to inject snippet for app ${snippet.appScopeId}`, error);
+      }
+    }
+  });
+
+  if (unresolved.size) {
+    // One line per page, not per snippet; expected during settings-endpoint rollout.
+    console.warn(
+      `[salla] app settings missing for ${unresolved.size} app(s); their snippets ran without app.* config`,
+      [...unresolved]
+    );
+  }
+}
+
+/** A CDN snippet reduced to what its SSR `<script>` tag needs. */
+interface SsrCdnScript {
+  key: string;
+  url: string;
+  snippetId?: number;
+  appScopeId: string;
+}
+
+/**
+ * Mounts installed apps' snippets once per page load:
+ *  - **CDN** — rendered as SSR `<script>` tags in <body> (see return), so they exist on first
+ *    paint. `place` doesn't apply: they're deferred scripts, which run in order either way.
+ *  - **inline** — injected client-side in the effect, into `place`'s target (head or body).
+ */
+export function AppsSnippets() {
+  // From twilight context, not useQuery: React Query isn't dehydrated here, so useQuery has no
+  // SSR data — but the CDN <script> tags must render server-side.
+  const ssrSnippets = getTwilightContext().appsSnippets;
+
+  // Client fallback for when the SSR prefetch failed or timed out (it fails open, non-fatal).
+  // Without it a single blip on `apps/snippets` would drop every installed app's snippets for
+  // the whole page load — no CDN tags, no inline scripts, no hook slots. Retries here because
+  // the query's own `retry: 0` exists only to bound the SSR wait.
+  const { data: fallbackSnippets } = useQuery({
+    ...apps.queries.snippets(),
+    enabled: !ssrSnippets,
+    retry: 2,
+  });
+  const data = ssrSnippets ?? fallbackSnippets;
+
+  const { data: settings, isSuccess, isError } = useQuery({ ...apps.queries.settings(), retry: 2 });
+
+  // Fail open: inject once settings settle either way, so snippets that never read `app.*`
+  // aren't dropped when the bucket is empty.
+  const settingsSettled = isSuccess || isError;
+
+  // Each enabled app's snippets, tagged with its scope id (the encoded `id`). Older payloads
+  // lacking `id` get a deterministic per-app fallback sharing one empty bucket.
+  const owned = useMemo<OwnedSnippet[]>(
+    () =>
+      (data ?? [])
+        .filter((app) => app.status === 'enabled')
+        .flatMap((app) =>
+          app.snippets.map((s) => ({ ...s, appScopeId: app.id ?? `unresolved-${app.app_id}` }))
+        ),
+    [data]
+  );
+
+  // Every CDN snippet → a real `<script>` tag in the SSR body (rendered below).
+  const ssrCdnScripts = useMemo<SsrCdnScript[]>(
+    () =>
+      owned
+        .filter((s) => s.url)
+        .map((s, i) => ({
+          key: `${s.appScopeId}:${s.id ?? i}`,
+          url: s.url as string,
+          snippetId: s.id,
+          appScopeId: s.appScopeId,
+        })),
+    [owned]
+  );
+
+  useEffect(() => {
+    if (injected || !data || !settingsSettled) return;
+    injected = true;
+
+    // Client-injected: inline snippets only. Every CDN snippet is SSR-rendered (below).
+    const clientSnippets = owned.filter((s) => !s.url);
+
+    // Always wait for the SDK: a snippet body calls the global `salla`/`Salla` (config, hooks,
+    // event bus) whether or not it declares customer parameters, and those are only populated
+    // after init. The wait is timeout-raced, so a broken SDK still can't strand injection.
+    void waitForSdk().then(() => mountSnippets(owned, clientSnippets, settings?.apps ?? {}));
+  }, [data, owned, settings, settingsSettled]);
+
+  // CDN snippets as classic `defer` scripts: non-blocking, in-order, kept in <body> (React hoists
+  // only `async` to <head>), and still exposing `document.currentScript` for the wrapper.
+  return (
+    <>
+      {ssrCdnScripts.map((s) => (
+        <script
+          key={s.key}
+          src={s.url}
+          defer
+          data-scope-id={s.appScopeId}
+          data-snippet-id={s.snippetId != null ? String(s.snippetId) : ''}
+        />
+      ))}
+    </>
+  );
+}

package/tailwind/components/snippets/SallaSdkScripts.tsx.txt

@@ -0,0 +1,14 @@
+import type { StoreContext } from '../../api/store';
+import { resolveTwilightSdkUrl, TICKETING_SCRIPT_URL } from '../../routes/root/head';
+
+/** SDK modules at the end of <body>, ahead of the snippets: same run order as from <head>, later download. */
+export function SallaSdkScripts({ settings }: { settings?: StoreContext }) {
+  return (
+    <>
+      <script id="salla-sdk" type="module" src={resolveTwilightSdkUrl(settings)} />
+      {settings?.store?.settings?.ticketing_system_enabled && (
+        <script id="salla-ticketing-script" type="module" src={TICKETING_SCRIPT_URL} />
+      )}
+    </>
+  );
+}

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

@@ -0,0 +1,4 @@
+// Component - injects installed marketplace apps' storefront snippets (inline + CDN).
+// `injectHtml` / `resolveCustomerParams` stay internal to the component (tests import them
+// from the module directly) — themes only ever render <AppsSnippets />.
+export { AppsSnippets } from './AppsSnippets';

package/tailwind/components/store/StoreClosedNotification.tsx.txt

@@ -0,0 +1,73 @@
+import { useState } from 'react';
+import { useIsProduct } from '../../providers/NavigationProvider';
+import { useTwilight } from '../../providers/TwilightProvider';
+import { useOpeningHours } from '../../hooks/useOpeningHours';
+import { useTranslation } from '../../providers/I18nProvider';
+
+export interface StoreClosedNotificationProps {
+  /** Whether to show the notification (defaults to true when store is closed on product page) */
+  show?: boolean;
+}
+
+/**
+ * StoreClosedNotification - Shows a notification bar when the store is closed.
+ *
+ * Mirrors PHP ReceivingOrdersTimesWidget:
+ * - Only shows on product pages
+ * - Only shows when store is closed for receiving orders
+ * - Displays when the store will open next
+ * - Has a close button to dismiss
+ *
+ * Injected via hook registry at body:start.
+ */
+export function StoreClosedNotification(_props: StoreClosedNotificationProps) {
+  const { store } = useTwilight();
+  const { t } = useTranslation();
+  const { isOpen, isEnabled, nextOpenFormatted } = useOpeningHours(store.settings?.opening_hours);
+  const [dismissed, setDismissed] = useState(false);
+
+  // Check if we're on a product page
+  const isProductPage = useIsProduct();
+
+  // Conditions: product page, opening hours enabled, store closed, not dismissed
+  if (!isProductPage || !isEnabled || isOpen || dismissed || !nextOpenFormatted) {
+    return null;
+  }
+
+  const handleClose = (e: React.MouseEvent) => {
+    e.preventDefault();
+    setDismissed(true);
+  };
+
+  return (
+    <div
+      className="store-notify"
+      id="store-closed-notification"
+      data-testid="store-closed-notification"
+      style={{
+        backgroundColor: '#d63031',
+        color: '#fff',
+        padding: '10px 15px',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        position: 'relative',
+      }}
+    >
+      <a
+        href="#"
+        id="notify-close"
+        onClick={handleClose}
+        style={{ position: 'absolute', left: 15, color: '#fff', textDecoration: 'none' }}
+      >
+        <i className="sicon-cancel" />
+      </a>
+      <p style={{ margin: 0, textAlign: 'center', flex: 1 }}>
+        {t('store.closed_notification', {
+          defaultValue: `المتجر حاليا مغلق لاستقبال الطلبات وسيتم فتحه (${nextOpenFormatted})`,
+          nextOpen: nextOpenFormatted,
+        })}
+      </p>
+    </div>
+  );
+}

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

@@ -0,0 +1,8 @@
+// Component - injects store closed notification bar via useEffect
+export {
+  StoreClosedNotification,
+  type StoreClosedNotificationProps,
+} from './StoreClosedNotification';
+
+// Lazy component
+export { LazyStoreClosedNotification } from './lazy';

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

@@ -0,0 +1,8 @@
+import { lazy } from 'react';
+
+/** Lazy-loaded StoreClosedNotification component. */
+export const LazyStoreClosedNotification = lazy(() =>
+  import('./StoreClosedNotification').then((m) => ({
+    default: m.StoreClosedNotification,
+  }))
+);