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

package/tailwind/components/home/FixedBanner.tsx.txt

@@ -0,0 +1,68 @@
+import { memo } from 'react';
+import { Link } from '../common';
+
+export interface FixedBannerComponentProps {
+  data: {
+    image: {
+      url: string;
+      alt?: string;
+      small_url?: string;
+    };
+    url?: string;
+    title?: string;
+    position?: number;
+    [key: string]: unknown;
+  };
+  priority?: boolean;
+}
+
+export const FixedBanner = memo(function FixedBanner(props: FixedBannerComponentProps) {
+  const { data, priority = false } = props;
+  const image = data.image?.url;
+
+  if (!image) {
+    return null;
+  }
+
+  const url = data.url;
+  const altText = data.image.alt?.trim() ? data.image.alt : data.title || 'fixed banner';
+
+  const imgProps = priority
+    ? {
+        loading: 'eager' as const,
+        fetchPriority: 'high' as const,
+        decoding: 'sync' as const,
+      }
+    : {
+        loading: 'lazy' as const,
+        decoding: 'async' as const,
+      };
+
+  const smallUrl = data.image.small_url;
+
+  return (
+    <>
+      <div className="container">
+        <Link
+          to={url || '#'}
+          className="banner banner--fixed overflow-hidden"
+          aria-label={`Banner ${altText}`}
+        >
+          <picture>
+            {smallUrl && <source media="(max-width: 767px)" srcSet={smallUrl} />}
+            <img
+              width="1200"
+              height="300"
+              src={image}
+              alt={altText}
+              style={{ maxWidth: '100%', objectFit: 'contain' }}
+              loading={imgProps.loading}
+              decoding={imgProps.decoding}
+              {...(priority && { fetchPriority: imgProps.fetchPriority })}
+            />
+          </picture>
+        </Link>
+      </div>
+    </>
+  );
+});

package/tailwind/components/home/FixedProducts.tsx.txt

@@ -0,0 +1,72 @@
+import { Suspense } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { FixedProductsSkeleton } from '@salla.sa/twilight-components-react';
+import { Link } from '../common';
+import { product, ProductsListSource } from '../../api/product';
+import { ProductCard } from '../../components/product';
+import { useTranslation } from '../../providers/I18nProvider';
+
+export interface FixedProductsProps {
+  data: {
+    products: { source: ProductsListSource; source_value?: number[] | null };
+    title?: string;
+    limit?: number | string;
+    display_all_url?: string | null;
+    key?: string | null;
+    isVertical?: boolean;
+    position?: number;
+    [key: string]: unknown;
+  };
+}
+
+export function FixedProducts({ data }: FixedProductsProps) {
+  const { t } = useTranslation();
+
+  const title = data.title;
+  const limit = data.limit ? Number(data.limit) : undefined;
+  const isVertical = data.isVertical ?? true;
+
+  const { data: result, isLoading } = useQuery(
+    product.queries.list({
+      source: data.products.source,
+      sourceValue: data.products?.source_value,
+      perPage: limit,
+    })
+  );
+
+  const products = result?.items ?? [];
+
+  if (isLoading) {
+    return <FixedProductsSkeleton />;
+  }
+
+  if (!products.length) return null;
+
+  return (
+    <Suspense fallback={<FixedProductsSkeleton />}>
+      {title && (
+        <div className="s-block__title">
+          <div className="right-side">
+            <h2>{title}</h2>
+          </div>
+          {data.display_all_url && (
+            <Link to={data.display_all_url} className="s-block__display-all">
+              {t('blocks.home.display_all', 'View All')}
+              <i className="sicon-arrow-left"></i>
+            </Link>
+          )}
+        </div>
+      )}
+      <div
+        className={
+          's-products-list-wrapper ' +
+          (isVertical ? 's-products-list-vertical-cards' : 's-products-list-horizontal-cards')
+        }
+      >
+        {products.slice(0, 4).map((product) => (
+          <ProductCard key={product.id} product={product} />
+        ))}
+      </div>
+    </Suspense>
+  );
+}

package/tailwind/components/home/HomePageRenderer.tsx.txt

@@ -0,0 +1,284 @@
+import { memo, useEffect, useRef, type ReactNode } from 'react';
+import { registry } from '../ComponentRegistry';
+import { RenderWhenVisible } from '../common';
+import { ComponentErrorBoundary } from './ComponentErrorBoundary';
+import type { AnyHomeComponent } from './index';
+import type { HomeComponentData } from '../../types';
+import {
+  BackgroundSliderSkeleton,
+  BulletDeliverySkeleton,
+  FixedProductsSkeleton,
+  ListSkeleton,
+  ProductsSliderSkeleton,
+  Pulse,
+  ReviewItemSkeleton,
+  SliderSkeleton,
+} from '@salla.sa/twilight-components-react';
+
+function SquareGridSkeleton() {
+  return (
+    <div className="s-block container grid grid-cols-2 sm:grid-cols-4 gap-4 py-8">
+      {[1, 2, 3, 4].map((i) => (
+        <Pulse key={i} className="aspect-square" />
+      ))}
+    </div>
+  );
+}
+
+export type HomeComponentsProps = {
+  data: HomeComponentData & {
+    position?: number;
+    [key: string]: unknown;
+  };
+};
+
+/**
+ * Fallback component for unknown/unregistered components
+ * Only shows in development mode
+ */
+const FallbackComponent = memo(function FallbackComponent({ data }: HomeComponentsProps) {
+  if (process.env.NODE_ENV === 'production') return null;
+
+  return (
+    <section
+      dir="ltr"
+      className="s-block container overflow-hidden bg-yellow-50 border border-yellow-200 p-4"
+    >
+      <p className="text-yellow-800 text-sm">
+        <strong>Unknown component:</strong> {data.path}
+      </p>
+      <p className="text-yellow-700 text-xs mt-1">
+        Register it in setup.ts: <code>registry.register('home:{data.path}', YourComponent)</code>
+      </p>
+      <details className="mt-2">
+        <summary className="text-xs cursor-pointer">Component Data</summary>
+        <pre className="text-xs mt-1 overflow-auto max-h-32">{JSON.stringify(data, null, 2)}</pre>
+      </details>
+    </section>
+  );
+});
+
+/**
+ * Get the React component for a given home component path
+ * Looks up from registry only - theme must register components
+ */
+function getComponentByPath(data: HomeComponentData): AnyHomeComponent {
+  const { path, view_style: viewStyle } = data;
+
+  // 1. Check for view_style variant first
+  if (viewStyle) {
+    const variantKey = `home:${path}:${viewStyle}`;
+    const variant = registry.resolve(variantKey);
+    if (variant) {
+      return variant as AnyHomeComponent;
+    }
+  }
+
+  // 2. Check registry for component
+  const registryKey = `home:${path}`;
+  const component = registry.resolve(registryKey);
+  if (component) {
+    return component as AnyHomeComponent;
+  }
+
+  // 3. Fallback for unknown components
+  return FallbackComponent;
+}
+
+/** Same breakpoint and rules the Store injects for Twig themes (`ComponentVisibilityStyles`). */
+const CHANNEL_VISIBILITY_CSS =
+  '@media (max-width:767.98px){.s-hide-on-mobile{display:none!important}}' +
+  '@media (min-width:768px){.s-hide-on-desktop{display:none!important}}';
+
+/**
+ * Hide class for the merchant's per-channel pick. A missing key, or one that
+ * hides on both channels, means visible everywhere: hiding a block outright
+ * is the `is_visible` toggle's job, and stores without the feature send no key.
+ */
+export function channelVisibilityClass(data: HomeComponentData): string {
+  const raw = data.channel_visibility;
+  if (!raw || typeof raw !== 'object') return '';
+  const desktop = raw.desktop !== false;
+  const mobile = raw.mobile !== false;
+  if (desktop && !mobile) return 's-hide-on-mobile';
+  if (mobile && !desktop) return 's-hide-on-desktop';
+  return '';
+}
+
+/**
+ * Render-shell config for a home block: the values the lazy-load wrapper
+ * (`RenderWhenVisible`) needs *before* the block mounts — reserved height, the
+ * skeleton placeholder, and the wrapper's className/id.
+ *
+ * Themes register config for blocks they own via `registerHomeComponentConfig`;
+ * the engine knows nothing about theme-specific blocks.
+ */
+export type HomeComponentConfig = {
+  height?: string;
+  className?: string | ((data: HomeComponentData) => string);
+  id?: string | ((data: HomeComponentData) => string);
+  placeholder?: ReactNode;
+  /** Mount on page load instead of when the block nears the viewport. */
+  renderOnMount?: boolean;
+};
+
+const COMPONENT_CONFIG: Record<string, HomeComponentConfig> = {
+  'products-slider': { height: '450px', placeholder: <ProductsSliderSkeleton /> },
+  'fixed-products': { height: '450px', placeholder: <FixedProductsSkeleton /> },
+  'featured-products': {
+    height: '450px',
+    placeholder: <ProductsSliderSkeleton />,
+    className: (data) => {
+      const style = data.view_style;
+      if (style === 'style1')
+        return 's-block s-block--featured-products s-block-tabs s-block--special-products container tabs-initialized';
+      if (style === 'style2')
+        return `s-block s-block--featured-products s-block-tabs s-block--tabs-produtcs s-block--full-bg tabs-initialized ${data.is_slider ? 'as-slider' : 'as-grid'} bg-gray-100 py-8 sm:py-16`;
+      if (style === 'style3')
+        return `s-block s-block--featured-products s-block--features-products${Array.isArray(data.items) && data.items.length > 1 ? ' two-cols' : ''} container`;
+      return 's-block s-block--featured-products container overflow-hidden';
+    },
+    id: (data) => `featured-products-${data.view_style}-${data.position ?? 0}`,
+  },
+  testimonial: { height: '350px', placeholder: <ReviewItemSkeleton /> },
+  'store-features': { height: '200px', placeholder: <BulletDeliverySkeleton /> },
+  'parallax-background': { height: '500px', placeholder: <BackgroundSliderSkeleton /> },
+  'fixed-banner': { height: '350px', placeholder: <BackgroundSliderSkeleton /> },
+  'photos-slider': {
+    height: 'clamp(130px, 30vw, 350px)',
+    placeholder: <SliderSkeleton />,
+    className: (data) =>
+      `s-block s-block--photos-slider${data.is_repeated ? ' repeated-block' : ''}`,
+  },
+  'square-photos': { height: '250px', placeholder: <SquareGridSkeleton /> },
+  youtube: { height: '350px', placeholder: <SliderSkeleton /> },
+  'bundle-component': {
+    height: '400px',
+    placeholder: <ProductsSliderSkeleton />,
+    className: (data) => `s-block s-block--bundle-${data.component_name}`,
+    // As in Twig, where merchant scripts wait a limited time for the bundle's markup.
+    renderOnMount: true,
+  },
+  'main-links': {
+    height: '200px',
+    placeholder: <ListSkeleton />,
+    className: (data) => {
+      const mergeWithTop = data.merge_links_with_top_component;
+      const position = data.position;
+      return [
+        's-block',
+        's-block--main-links',
+        mergeWithTop && position ? 'merge-with-top-component' : '',
+        !data.title && mergeWithTop ? 'merged-has-no-title' : '',
+      ]
+        .filter(Boolean)
+        .join(' ');
+    },
+  },
+  'square-links': { height: '200px', placeholder: <SquareGridSkeleton /> },
+};
+
+/**
+ * Theme-registered render-shell config, keyed by home component path. Themes own
+ * the display of their blocks by registering config here; at render time a path's
+ * theme entry replaces (not field-merges) the engine's built-in `COMPONENT_CONFIG`
+ * entry for that path.
+ */
+const themeComponentConfig: Record<string, HomeComponentConfig> = {};
+
+/**
+ * Register render-shell config for home blocks a theme owns (height, placeholder,
+ * className, id). Merges by path and overwrites existing keys, so it is safe to
+ * call more than once and idempotent for the same keys.
+ */
+export function registerHomeComponentConfig(config: Record<string, HomeComponentConfig>): void {
+  Object.assign(themeComponentConfig, config);
+}
+
+/**
+ * Resolve a block's render-shell config: theme-registered config takes precedence
+ * over the engine's built-in config; returns `undefined` when neither defines the
+ * path so the renderer can apply generic defaults.
+ */
+function resolveComponentConfig(path: string): HomeComponentConfig | undefined {
+  return themeComponentConfig[path] ?? COMPONENT_CONFIG[path];
+}
+
+/**
+ * Memoized component renderer with scroll-based lazy loading
+ * Components only mount when scrolled into view - preventing API calls until needed
+ */
+export const HomeComponentRenderer = memo(function HomeComponentRenderer({
+  data,
+  index,
+  priority,
+}: {
+  data: HomeComponentData;
+  index: number;
+  /** Mount right away with eager images. Defaults to the first three blocks of the page. */
+  priority?: boolean;
+}) {
+  const renderCountRef = useRef(0);
+  renderCountRef.current += 1;
+
+  if (process.env.NODE_ENV === 'development') {
+    console.log(
+      `[HomeComponentRenderer] RENDER: path=${data.path}, index=${index}, renderCount=${renderCountRef.current}`
+    );
+  }
+
+  useEffect(() => {
+    console.log(
+      `[HomeComponentRenderer] MOUNT: path=${data.path}, index=${index}, renderCount=${renderCountRef.current}`
+    );
+    return () => {
+      console.log(`[HomeComponentRenderer] UNMOUNT: path=${data.path}, index=${index}`);
+    };
+  }, [data.path, index]);
+
+  const isFirstComponent = priority ?? index <= 2;
+  const Component = getComponentByPath(data);
+
+  const config = resolveComponentConfig(data.path);
+
+  const resolvedClassName = config?.className
+    ? typeof config.className === 'function'
+      ? config.className(data)
+      : config.className
+    : `s-block s-block--${data.path}`;
+  const hideClass = channelVisibilityClass(data);
+  const resolvedId = config?.id
+    ? typeof config.id === 'function'
+      ? config.id(data)
+      : config.id
+    : undefined;
+  const height = config?.height || '400px';
+  // A theme's config replaces the engine's, but keeps its mount timing unless the theme sets one.
+  const renderOnMount = config?.renderOnMount ?? COMPONENT_CONFIG[data.path]?.renderOnMount;
+
+  const content = (
+    <ComponentErrorBoundary data={data} position={index + 1}>
+      <Component data={{ ...data, position: index + 1, priority: isFirstComponent }} />
+    </ComponentErrorBoundary>
+  );
+
+  return (
+    <>
+      {hideClass && (
+        <style href="twilight-channel-visibility" precedence="default">
+          {CHANNEL_VISIBILITY_CSS}
+        </style>
+      )}
+      <RenderWhenVisible
+        rootMargin="50px"
+        className={hideClass ? `${resolvedClassName} ${hideClass}` : resolvedClassName}
+        id={resolvedId}
+        estimatedHeight={height}
+        renderOnMount={isFirstComponent || renderOnMount === true}
+        placeholder={config?.placeholder ?? <ProductsSliderSkeleton />}
+      >
+        {content}
+      </RenderWhenVisible>
+    </>
+  );
+});

package/tailwind/components/home/PageBlocks.tsx.txt

@@ -0,0 +1,24 @@
+import { memo } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { home, type BlockScope } from '../../api/home';
+import { HomeComponentRenderer } from './HomePageRenderer';
+
+export interface PageBlocksProps {
+  /** The page hook the merchant placed the blocks at, e.g. `product.single.before_customer_reviews`. */
+  hook: string;
+  /** The product, category or page being shown. */
+  scope: BlockScope;
+}
+
+/** Draws the blocks placed at a product, category or page hook, loaded in the browser. */
+export const PageBlocks = memo(function PageBlocks({ hook, scope }: PageBlocksProps) {
+  const { data: blocks = [] } = useQuery(home.queries.blocks(hook, scope));
+
+  return (
+    <>
+      {blocks.map((data, index) => (
+        <HomeComponentRenderer key={index} data={data} index={index} priority={false} />
+      ))}
+    </>
+  );
+});

package/tailwind/components/home/ParallaxBackground.tsx.txt

@@ -0,0 +1,50 @@
+import { memo } from 'react';
+import { Link } from '../common';
+
+interface ImageData {
+  url?: string;
+}
+
+export interface ParallaxBackgroundProps {
+  data: {
+    image: ImageData;
+    url?: string;
+    title?: string;
+    link_text?: string;
+    is_opacity?: boolean;
+    position?: number;
+    [key: string]: unknown;
+  };
+}
+
+export const ParallaxBackground = memo(function ParallaxBackground({
+  data,
+}: ParallaxBackgroundProps) {
+  const { image, url, title, link_text: linkText, is_opacity: isOpacity = false } = data;
+
+  if (!image?.url) return null;
+
+  return (
+    <>
+      <div className="full-banner-entry" style={{ backgroundImage: `url(${image.url})` }}>
+        <div
+          className={`overlay h-full w-full ${isOpacity ? 'bg-black' : ''} opacity-60 absolute top-0 left-0`}
+        ></div>
+        <div className="flex h-full items-center justify-center p-5 xs:p-11 relative">
+          <div>
+            {title && <h2 className="text-2xl font-bold leading-12">{title}</h2>}
+
+            {url && linkText && (
+              <Link
+                to={url}
+                className="inline-block text-white text-sm border rounded-md font-bold px-8 py-4"
+              >
+                {linkText}
+              </Link>
+            )}
+          </div>
+        </div>
+      </div>
+    </>
+  );
+});

package/tailwind/components/home/PhotosSlider.tsx.txt

@@ -0,0 +1,61 @@
+import { memo } from 'react';
+import { SallaSlider } from '@salla.sa/twilight-components-react/slider';
+import { Link, Image } from '../common';
+
+interface PhotoItem {
+  id?: string | number;
+  url?: string;
+  link_type?: string;
+  image?: string;
+}
+
+export interface PhotosSliderProps {
+  data: {
+    items: PhotoItem[];
+    position?: number;
+    is_repeated?: boolean;
+    [key: string]: unknown;
+  };
+}
+
+export const PhotosSlider = memo(function PhotosSlider({ data }: PhotosSliderProps) {
+  const items = data.items || [];
+  const position = data.position ?? 1;
+
+  if (!items.length) return null;
+
+  return (
+    <>
+      <SallaSlider
+        type="carousel"
+        className="home-slider photos-slider"
+        centered
+        autoPlay
+        pagination
+        id={`photos-${position}-slider`}
+        sliderConfig={{ watchOverflow: true }}
+      >
+        <div slot="items">
+          {items.map((item, index) => (
+            <div
+              key={item.id ?? `${item.url ?? ''}:${item.image ?? ''}`}
+              className="swiper-slide"
+              style={{ aspectRatio: '1200/300' }}
+            >
+              <Link to={item.url || '#'}>
+                <Image
+                  src={item.image}
+                  className="w-full h-full object-contain rounded-md"
+                  alt={`image-slider-${index}`}
+                  width={1200}
+                  height={300}
+                  priority={index === 0}
+                />
+              </Link>
+            </div>
+          ))}
+        </div>
+      </SallaSlider>
+    </>
+  );
+});

package/tailwind/components/home/ProductsSlider.tsx.txt

@@ -0,0 +1,87 @@
+import { Suspense, useCallback, useMemo } from 'react';
+import { product, ProductsListSource } from '../../api/product';
+import { ProductCard } from '../../components/product';
+import { ProductsSliderSkeleton, SallaProductsSlider } from '@salla.sa/twilight-components-react';
+import { useTranslation } from '../../providers/I18nProvider';
+
+interface ProductsSourceConfig {
+  source: ProductsListSource;
+  source_value?: number | number[] | null;
+}
+
+export interface ProductsSliderProps {
+  data: {
+    products: ProductsSourceConfig;
+    title?: string;
+    display_all_url?: string;
+    position?: number;
+    priority?: boolean;
+    show_controls?: boolean;
+    controls_outer?: boolean;
+    loop?: boolean;
+    centered?: boolean;
+    slides_per_view?: number | 'auto';
+    direction?: 'rtl' | 'ltr';
+    autoplay?: boolean;
+    [key: string]: unknown;
+  };
+}
+
+export function ProductsSlider({ data }: ProductsSliderProps) {
+  const { t } = useTranslation();
+  const {
+    products,
+    title,
+    display_all_url: displayAllUrl,
+    position = 1,
+    priority = false,
+    show_controls: showControls,
+    controls_outer: controlsOuter,
+    loop,
+    centered,
+    slides_per_view: slidesPerView,
+    direction,
+    autoplay,
+  } = data;
+
+  const sliderProps = useMemo(
+    () => ({
+      id: `slider-${position}`,
+      displayAllTitle: t('blocks.home.display_all', 'View All'),
+      ...(showControls !== undefined && { showControls }),
+      ...(controlsOuter !== undefined && { controlsOuter }),
+      ...(loop !== undefined && { loop }),
+      ...(centered !== undefined && { centered }),
+      ...(slidesPerView !== undefined && { slidesPerView }),
+      ...(direction !== undefined && { direction }),
+    }),
+    [position, t, showControls, controlsOuter, loop, centered, slidesPerView, direction]
+  );
+
+  const loader = useCallback(
+    () =>
+      product.list({
+        source: products.source,
+        sourceValue: products.source_value,
+      }),
+    [products.source, products.source_value]
+  );
+
+  return (
+    <Suspense fallback={<ProductsSliderSkeleton />}>
+      <SallaProductsSlider
+        id={`best-offers-${position}-slider`}
+        loader={loader}
+        sliderProps={sliderProps}
+        {...(displayAllUrl ? { displayAllUrl } : {})}
+        {...(title ? { blockTitle: title } : {})}
+        {...(autoplay !== undefined ? { autoplay } : {})}
+        skeleton={<ProductsSliderSkeleton />}
+      >
+        {(product, index) => (
+          <ProductCard product={product} imagePriority={priority && index < 2} />
+        )}
+      </SallaProductsSlider>
+    </Suspense>
+  );
+}

package/tailwind/components/home/ReorderProducts.tsx.txt

@@ -0,0 +1,38 @@
+import { memo, useMemo } from 'react';
+import { useTranslation } from '../../providers/I18nProvider';
+import { getTwilightContext } from '../../twilight/context';
+import type { HomeComponentData } from '../../types';
+import { HomeComponentRenderer } from './HomePageRenderer';
+import { useReorderButtons } from './reorder-hooks';
+
+/**
+ * Twig's "order again" block (the Store app's ReorderProductsWidget): on the home page, for a
+ * signed-in customer of a store with Reorder on, the products they ordered before, drawn by the
+ * theme's own `products-slider` like the home's other product rows.
+ */
+export const ReorderProducts = memo(function ReorderProducts() {
+  const { t } = useTranslation();
+  const { authToken, settings } = getTwilightContext();
+  // The platform lists `reorder` in the store's features exactly when the Reorder setting is on.
+  const enabled = !!authToken && !!settings?.store?.features?.includes('reorder');
+  const title = t('pages.orders.repurchase');
+  useReorderButtons(enabled);
+
+  const data = useMemo<HomeComponentData>(
+    () => ({
+      path: 'products-slider',
+      title,
+      display_all_url: '/products?source=reorder',
+      products: { source: 'reorder' },
+    }),
+    [title]
+  );
+
+  if (!enabled) return null;
+
+  return (
+    <div id="reorder-section" data-source="reorder">
+      <HomeComponentRenderer data={data} index={-1} priority={false} />
+    </div>
+  );
+});