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

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

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

@@ -0,0 +1,119 @@
+import { memo } from 'react';
+import { getCdnImageSrcSet, getCdnImageUrl } from '../../utils/cdn-image';
+
+export interface ImageProps extends React.ImgHTMLAttributes<HTMLImageElement> {
+  /** Image source URL */
+  src?: string;
+  /** Alt text for accessibility */
+  alt: string;
+  /** Whether this image is above the fold / LCP candidate */
+  priority?: boolean;
+  /** Aspect ratio for CLS prevention (e.g. "16/9", "1/1", "4/3") */
+  aspectRatio?: string;
+  /** Object fit mode */
+  objectFit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';
+  /** Mobile image source for <picture> element */
+  mobileSrc?: string;
+  /** Mobile breakpoint for <source> media query (default: 768px) */
+  mobileBreakpoint?: number;
+  /** Skip the wrapper div */
+  noWrapper?: boolean;
+  /**
+   * CDN widths for a density `srcset`. Pass `sizes` so the browser picks a
+   * candidate close to the displayed CSS size.
+   */
+  srcSetWidths?: readonly number[];
+}
+
+/**
+ * Optimized Image component with native browser lazy loading.
+ *
+ * - Uses `loading="lazy"` + `decoding="async"` by default for below-the-fold images.
+ * - Uses `loading="eager"` + `fetchPriority="high"` for priority (above-the-fold / LCP) images.
+ * - Supports responsive `<picture>` with mobile source.
+ * - Provides `aspectRatio` for CLS prevention.
+ * - When `srcSetWidths` + `sizes` are set, emits a sized CDN `srcset`.
+ */
+export const Image = memo(function Image({
+  src,
+  alt,
+  priority = false,
+  aspectRatio,
+  objectFit = 'cover',
+  mobileSrc,
+  mobileBreakpoint = 768,
+  noWrapper = false,
+  className = '',
+  style,
+  width,
+  height,
+  sizes,
+  srcSet: srcSetProp,
+  srcSetWidths,
+  ...rest
+}: ImageProps) {
+  if (!src) return null;
+
+  const generatedSrcSet =
+    srcSetProp || (srcSetWidths?.length ? getCdnImageSrcSet(src, srcSetWidths) : undefined);
+  const generatedMobileSrcSet =
+    srcSetWidths?.length && mobileSrc ? getCdnImageSrcSet(mobileSrc, srcSetWidths) : undefined;
+  const cdnWidth = srcSetWidths?.length
+    ? width != null && srcSetWidths.includes(Number(width))
+      ? Number(width)
+      : srcSetWidths[0]
+    : width;
+  // Width-only CDN URLs so `src` matches a srcset candidate for preload.
+  const cdnOptions = generatedSrcSet ? { width: cdnWidth } : { width: cdnWidth, height };
+
+  const optimizedSrc = getCdnImageUrl(src, cdnOptions);
+  const optimizedMobileSrc = getCdnImageUrl(mobileSrc, cdnOptions);
+
+  const objectFitClass = `object-${objectFit}`;
+  const imgClasses = [className, objectFitClass].filter(Boolean).join(' ');
+
+  const loadingProps: React.ImgHTMLAttributes<HTMLImageElement> = priority
+    ? { loading: 'eager' as const, fetchPriority: 'high' as const, decoding: 'sync' as const }
+    : { loading: 'lazy' as const, decoding: 'async' as const };
+
+  const hasWrapper = !noWrapper && !!aspectRatio;
+
+  const img = (
+    <img
+      src={optimizedSrc}
+      alt={alt}
+      className={imgClasses}
+      width={width}
+      height={height}
+      sizes={sizes}
+      srcSet={generatedSrcSet}
+      // With a wrapper, `style` goes to the wrapper; otherwise it must land on the <img>.
+      style={hasWrapper ? undefined : style}
+      {...loadingProps}
+      {...rest}
+    />
+  );
+
+  const imgElement = optimizedMobileSrc ? (
+    <picture>
+      <source
+        media={`(max-width: ${mobileBreakpoint}px)`}
+        srcSet={generatedMobileSrcSet || optimizedMobileSrc}
+        sizes={generatedMobileSrcSet ? sizes : undefined}
+      />
+      {img}
+    </picture>
+  ) : (
+    img
+  );
+
+  if (!hasWrapper) {
+    return imgElement;
+  }
+
+  return (
+    <div className="relative overflow-hidden" style={{ aspectRatio, ...style }}>
+      {imgElement}
+    </div>
+  );
+});

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

@@ -0,0 +1,36 @@
+import { forwardRef } from 'react';
+import { useLinkAdapter } from '../../providers/LinkProvider';
+import type { BaseLinkProps } from './Link.types';
+
+/**
+ * Framework-agnostic Link component.
+ *
+ * Uses the LinkProvider context to render the framework-specific Link adapter.
+ * Works with TanStack Router, Next.js, or any configured adapter.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <Link to="/products">View Products</Link>
+ *
+ * // With preloading
+ * <Link to="/product/123" preload="intent">Product Details</Link>
+ *
+ * // With styling
+ * <Link to="/cart" className="nav-link" style={{ fontWeight: 'bold' }}>Cart</Link>
+ * ```
+ */
+export const Link = forwardRef<HTMLAnchorElement, BaseLinkProps>(
+  ({ to, href, children, ...props }, ref) => {
+    const Adapter = useLinkAdapter();
+    const destination = to ?? href ?? '/';
+
+    return (
+      <Adapter ref={ref} to={destination} {...props} data-spa-link="">
+        {children}
+      </Adapter>
+    );
+  }
+);
+
+Link.displayName = 'Link';

package/tailwind/components/common/Link.types.ts.txt

@@ -0,0 +1,85 @@
+import type { ReactNode, CSSProperties, MouseEventHandler, Ref } from 'react';
+
+/**
+ * Preload behavior for Link component
+ */
+export type LinkPreload = 'intent' | 'render' | false;
+
+/**
+ * Framework-agnostic Link props.
+ * Supported across TanStack Router, Next.js, and other React frameworks.
+ */
+export interface BaseLinkProps {
+  /**
+   * The destination path
+   */
+  to?: string;
+  /**
+   * Alternative to `to` - supported for compatibility
+   */
+  href?: string;
+  /**
+   * Children elements
+   */
+  children?: ReactNode;
+  /**
+   * Optional className for styling
+   */
+  className?: string;
+  /**
+   * Inline styles
+   */
+  style?: CSSProperties;
+  /**
+   * Optional title attribute
+   */
+  title?: string;
+  /**
+   * Target attribute for the anchor
+   */
+  target?: string;
+  /**
+   * Rel attribute for the anchor
+   */
+  rel?: string;
+  /**
+   * Click handler
+   */
+  onClick?: MouseEventHandler<HTMLAnchorElement>;
+  /**
+   * Preload behavior:
+   * - 'intent': Preload on hover/focus (default for TanStack)
+   * - 'render': Preload when link renders
+   * - false: No preloading
+   */
+  preload?: LinkPreload;
+  /**
+   * Replace current history entry instead of pushing
+   */
+  replace?: boolean;
+  /**
+   * ARIA label for accessibility
+   */
+  'aria-label'?: string;
+  /**
+   * HTML microdata itemProp attribute
+   */
+  itemProp?: string;
+  /**
+   * Ref forwarding
+   */
+  ref?: Ref<HTMLAnchorElement>;
+}
+
+/**
+ * Link adapter component type
+ */
+export type LinkAdapter = React.ComponentType<BaseLinkProps>;
+
+/**
+ * Props for LinkProvider
+ */
+export interface LinkProviderProps {
+  adapter: LinkAdapter;
+  children: ReactNode;
+}

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

@@ -0,0 +1,27 @@
+import { Link } from './Link';
+
+interface NoContentProps {
+  icon?: string;
+  message: string;
+  actionLabel?: string;
+  actionUrl?: string;
+}
+
+export function NoContent({
+  icon = 'sicon-shopping-bag',
+  message,
+  actionLabel,
+  actionUrl = '/',
+}: NoContentProps) {
+  return (
+    <div className="no-content-placeholder">
+      <i className={`${icon} icon`}></i>
+      <p>{message}</p>
+      {actionLabel && (
+        <Link to={actionUrl} className="btn btn--outline-primary btn--rounded-full">
+          {actionLabel}
+        </Link>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,92 @@
+import { memo, useState, useEffect, useRef, Suspense, type ReactNode } from 'react';
+
+function DefaultSkeleton({ height }: { height: string }) {
+  return <div style={{ minHeight: height }} className="animate-pulse rounded bg-gray-100" />;
+}
+
+/** Sibling of the children inside Suspense: its effect only runs once the boundary resolves. */
+function MarkMounted({ onMount }: { onMount: (mounted: boolean) => void }) {
+  useEffect(() => onMount(true), [onMount]);
+  return null;
+}
+
+export interface RenderWhenVisibleProps {
+  children: ReactNode;
+  rootMargin?: string;
+  placeholder?: ReactNode;
+  className?: string;
+  id?: string;
+  estimatedHeight?: string;
+  renderOnMount?: boolean;
+}
+
+/**
+ * RenderWhenVisible — defers mounting children until the container enters the viewport.
+ *
+ * Children are NOT in the React tree at all until the Intersection Observer fires,
+ * so no effects, API calls, or renders happen for off-screen sections.
+ * Once rendered, children stay mounted permanently (no re-unmount on scroll away).
+ *
+ * The `estimatedHeight` prop prevents the zero-height collapse problem: without it
+ * every unrendered section stacks at the top with 0px height, causing all observers
+ * to fire at once on mount. It applies as a min-height until the children have
+ * actually committed — through the Suspense window too, since a custom placeholder
+ * may be shorter than the estimate. After that the section's height is owned by its
+ * content, so shorter blocks don't leave reserved dead space below them.
+ */
+export const RenderWhenVisible = memo(function RenderWhenVisible({
+  children,
+  rootMargin = '50px',
+  placeholder,
+  className,
+  id,
+  estimatedHeight = '400px',
+  renderOnMount = false,
+}: RenderWhenVisibleProps) {
+  const ref = useRef<HTMLElement>(null);
+  const [visible, setVisible] = useState(renderOnMount);
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => {
+    if (renderOnMount || visible) return;
+    const el = ref.current;
+    if (!el) return;
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        // A busy main thread (e.g. mounting a page while the user is already
+        // scrolling) batches entries; reading only the first drops a
+        // [false, true] pair and the observer never fires again.
+        if (entries.some((entry) => entry.isIntersecting)) {
+          setVisible(true);
+          observer.disconnect();
+        }
+      },
+      { rootMargin }
+    );
+
+    observer.observe(el);
+
+    return () => observer.disconnect();
+  }, [renderOnMount, visible, rootMargin]);
+
+  const fallback = placeholder ?? <DefaultSkeleton height={estimatedHeight} />;
+
+  return (
+    <section
+      ref={!visible ? ref : undefined}
+      className={className}
+      id={id}
+      style={{ minHeight: mounted ? undefined : estimatedHeight }}
+    >
+      {visible ? (
+        <Suspense fallback={fallback}>
+          {children}
+          <MarkMounted onMount={setMounted} />
+        </Suspense>
+      ) : (
+        fallback
+      )}
+    </section>
+  );
+});

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

@@ -0,0 +1,42 @@
+import {
+  LazyBreadcrumb,
+  LazyNoContent,
+  LazyRenderWhenVisible,
+  LazyCurrencySymbol,
+  LazyErrorPage,
+} from './lazy';
+import { Image } from './Image';
+import { Link } from './Link';
+
+// Lazy-loaded common components (code-split)
+export {
+  LazyBreadcrumb as Breadcrumb,
+  LazyNoContent as NoContent,
+  LazyRenderWhenVisible as RenderWhenVisible,
+  LazyCurrencySymbol as CurrencySymbol,
+  LazyErrorPage as ErrorPage,
+};
+
+// Eager components (statically imported in multiple places)
+export { Image, Link };
+
+// Skeleton components — sourced from @salla.sa/twilight-components-react (kept eager for instant render during loading)
+export {
+  PageSkeleton,
+  ProductDetailSkeleton,
+  BlogSkeleton,
+  BreadcrumbSkeleton,
+  ProductCardSkeleton,
+  ProductGridSkeleton,
+  SkeletonPulse,
+  CustomerPageSkeleton,
+  CustomerLayoutSkeleton,
+} from '@salla.sa/twilight-components-react';
+export type { PageSkeletonProps } from '@salla.sa/twilight-components-react';
+
+// DeferredData - React 19 Suspense + use() pattern (eager, lightweight)
+export { DeferredData, resolveDeferred } from './DeferredData';
+export type { DeferredDataProps } from './DeferredData';
+
+// Shared types (exported for external use)
+export type { BaseLinkProps as LinkProps, LinkPreload } from './Link.types';