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

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';

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

@@ -0,0 +1,28 @@
+import { lazy } from 'react';
+
+/**
+ * Lazy-loaded common components
+ * Use these for code-splitting non-critical components
+ *
+ * NOTE: Skeleton components are sourced from @salla.sa/twilight-components-react
+ * because they must render instantly during route transitions.
+ */
+export const LazyBreadcrumb = lazy(() =>
+  import('./Breadcrumb').then((m) => ({ default: m.Breadcrumb }))
+);
+
+export const LazyNoContent = lazy(() =>
+  import('./NoContent').then((m) => ({ default: m.NoContent }))
+);
+
+export const LazyRenderWhenVisible = lazy(() =>
+  import('./RenderWhenVisible').then((m) => ({ default: m.RenderWhenVisible }))
+);
+
+export const LazyCurrencySymbol = lazy(() =>
+  import('./CurrencySymbol').then((m) => ({ default: m.CurrencySymbol }))
+);
+
+export const LazyErrorPage = lazy(() =>
+  import('./ErrorPage').then((m) => ({ default: m.ErrorPage }))
+);

package/tailwind/components/defineComponent.ts.txt

@@ -0,0 +1,32 @@
+import { registry } from './ComponentRegistry';
+import type { ComponentType } from '../types';
+
+interface DefineComponentConfig<P = Record<string, unknown>> {
+  name: string;
+  component: ComponentType<P>;
+  override?: boolean;
+}
+
+export function defineComponent<P = Record<string, unknown>>(
+  config: DefineComponentConfig<P>
+): ComponentType<P> {
+  if (config.override) {
+    registry.override(config.name, config.component);
+  } else {
+    registry.register(config.name, config.component);
+  }
+
+  return config.component;
+}
+
+export function registerComponents(components: Record<string, ComponentType>): void {
+  for (const [name, component] of Object.entries(components)) {
+    registry.register(name, component);
+  }
+}
+
+export function overrideComponents(components: Record<string, ComponentType>): void {
+  for (const [name, component] of Object.entries(components)) {
+    registry.override(name, component);
+  }
+}

package/tailwind/components/drawer/Drawer.tsx.txt

@@ -0,0 +1,219 @@
+/**
+ * Drawer Component
+ *
+ * A slide-in panel from the side of the screen, commonly used for mobile menus.
+ */
+
+import React, { useEffect, useCallback, useRef, type ReactNode, type HTMLAttributes } from 'react';
+import { createPortal } from 'react-dom';
+import { useTwilight } from '../../providers/TwilightProvider';
+
+export interface DrawerProps {
+  isOpen: boolean;
+  onClose: () => void;
+  children: ReactNode;
+  /**
+   * Width of the drawer
+   * @default 'md'
+   */
+  size?: 'sm' | 'md' | 'lg' | 'full';
+  /**
+   * Close drawer when clicking backdrop
+   * @default true
+   */
+  closeOnBackdropClick?: boolean;
+  /**
+   * Close drawer on Escape key
+   * @default true
+   */
+  closeOnEscape?: boolean;
+  /**
+   * Prevent body scroll when drawer is open
+   * @default true
+   */
+  preventBodyScroll?: boolean;
+  /**
+   * Additional className for the drawer content
+   */
+  className?: string;
+}
+
+const sizeClasses = {
+  sm: 'w-64',
+  md: 'w-80',
+  lg: 'w-96',
+  full: 'w-full',
+};
+
+export function Drawer({
+  isOpen,
+  onClose,
+  children,
+  size = 'md',
+  closeOnBackdropClick = true,
+  closeOnEscape = true,
+  preventBodyScroll = true,
+  className,
+}: DrawerProps) {
+  const drawerRef = useRef<HTMLDivElement>(null);
+  const previousActiveElement = useRef<HTMLElement | null>(null);
+  // Use TwilightProvider to get theme direction
+  // Position is automatically determined: left for LTR, right for RTL
+  const { theme } = useTwilight();
+  const isRtl = theme?.is_rtl ?? false;
+  const position = isRtl ? 'right' : 'left';
+
+  // Handle Escape key
+  const handleKeyDown = useCallback(
+    (event: KeyboardEvent) => {
+      if (event.key === 'Escape' && closeOnEscape) {
+        onClose();
+      }
+    },
+    [closeOnEscape, onClose]
+  );
+
+  // Handle backdrop click
+  const handleBackdropClick = useCallback(
+    (_event: React.MouseEvent) => {
+      if (closeOnBackdropClick) {
+        onClose();
+      }
+    },
+    [closeOnBackdropClick, onClose]
+  );
+
+  // Focus management and body scroll
+  useEffect(() => {
+    if (isOpen) {
+      // Store the previously focused element
+      previousActiveElement.current = document.activeElement as HTMLElement;
+
+      // Focus the drawer
+      drawerRef.current?.focus();
+
+      // Prevent body scroll
+      if (preventBodyScroll) {
+        document.body.classList.add('menu-opened');
+      }
+
+      // Add keyboard listener
+      document.addEventListener('keydown', handleKeyDown);
+    }
+
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown);
+
+      // Restore body scroll
+      if (preventBodyScroll) {
+        document.body.classList.remove('menu-opened');
+      }
+
+      // Restore focus
+      previousActiveElement.current?.focus();
+    };
+  }, [isOpen, handleKeyDown, preventBodyScroll]);
+
+  if (!isOpen || typeof document === 'undefined') {
+    return null;
+  }
+
+  // Translate classes: left drawer slides from -100%, right drawer slides from +100%
+  const translateClass = isOpen
+    ? 'translate-x-0'
+    : position === 'left'
+      ? '-translate-x-full'
+      : 'translate-x-full';
+
+  return createPortal(
+    <div className="fixed inset-0 z-[200]" aria-modal="true" role="dialog">
+      {/* Backdrop */}
+      <div
+        className={`absolute inset-0 bg-black/50 transition-opacity duration-300 ${isOpen ? 'opacity-100' : 'opacity-0'}`}
+        onClick={handleBackdropClick}
+        onKeyDown={(e) => {
+          if ((e.key === 'Enter' || e.key === ' ') && closeOnBackdropClick) {
+            e.preventDefault();
+            onClose();
+          }
+        }}
+        role="presentation"
+      />
+
+      {/* Drawer Content */}
+      <div
+        ref={drawerRef}
+        tabIndex={-1}
+        className={`fixed top-0 bottom-0 flex flex-col bg-white shadow-xl ${sizeClasses[size]} ${position === 'left' ? 'left-0' : 'right-0'} transform transition-transform duration-300 ease-out ${translateClass} ${className || ''}`}
+      >
+        {children}
+      </div>
+    </div>,
+    document.body
+  );
+}
+
+// Drawer Sub-components
+export interface DrawerHeaderProps extends HTMLAttributes<HTMLDivElement> {
+  children: ReactNode;
+  showCloseButton?: boolean;
+  onClose?: () => void;
+}
+
+Drawer.Header = function DrawerHeader({
+  children,
+  showCloseButton = true,
+  onClose,
+  className,
+  ...props
+}: DrawerHeaderProps) {
+  return (
+    <div
+      className={`flex items-center justify-between border-b border-gray-200 px-4 py-3 ${className || ''}`}
+      {...props}
+    >
+      <h2 className="text-lg font-semibold text-gray-900">{children}</h2>
+      {showCloseButton && onClose && (
+        <button
+          type="button"
+          onClick={onClose}
+          className="rounded-md p-2 text-gray-400 hover:text-gray-500 hover:bg-gray-100 focus:outline-none focus:ring-2 focus:ring-gray-500"
+        >
+          <span className="sr-only">Close</span>
+          <svg className="h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth={2}
+              d="M6 18L18 6M6 6l12 12"
+            />
+          </svg>
+        </button>
+      )}
+    </div>
+  );
+};
+
+export interface DrawerBodyProps extends HTMLAttributes<HTMLDivElement> {
+  children: ReactNode;
+}
+
+Drawer.Body = function DrawerBody({ children, className, ...props }: DrawerBodyProps) {
+  return (
+    <div className={`flex-1 overflow-y-auto px-4 py-3 ${className || ''}`} {...props}>
+      {children}
+    </div>
+  );
+};
+
+export interface DrawerFooterProps extends HTMLAttributes<HTMLDivElement> {
+  children: ReactNode;
+}
+
+Drawer.Footer = function DrawerFooter({ children, className, ...props }: DrawerFooterProps) {
+  return (
+    <div className={`border-t border-gray-200 px-4 py-3 ${className || ''}`} {...props}>
+      {children}
+    </div>
+  );
+};