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

package/tailwind/routes/product-listing/loader.ts.txt

@@ -0,0 +1,323 @@
+import type { ProductListLoaderData, ProductListLoaderContext, ProductListSource } from './types';
+import type { ProductsListSource } from '../../api/product';
+import { category } from '../../api/category';
+import { product } from '../../api/product';
+import { brand } from '../../api/brands';
+import { notFound, orThrow, unauthorized } from '../../providers/NavigationProvider';
+import { getAuthToken } from '../../api/client';
+import { getTwilightContext } from '../../twilight/context';
+import { RouteId } from '../../router/route-ids';
+
+const DEFAULT_SORT = 'ourSuggest';
+
+const SOURCE_TO_API: Record<ProductListSource, ProductsListSource> = {
+  categories: 'categories',
+  latest: 'latest',
+  sales: 'sales',
+  offers: 'offers',
+  search: 'search',
+  tags: 'tags',
+  brands: 'brands',
+  reorder: 'reorder',
+};
+
+type StaticSource = 'latest' | 'sales' | 'offers' | 'reorder';
+
+const SOURCE_TITLE_KEY: Record<StaticSource, string> = {
+  latest: 'blocks.home.latest_products',
+  sales: 'common.titles.most_sales',
+  offers: 'common.titles.discounts',
+  reorder: 'pages.orders.repurchase',
+};
+
+const SOURCE_SLUG: Record<StaticSource, string> = {
+  latest: 'products?source=latest',
+  sales: 'products?source=sales',
+  offers: 'products?source=offers',
+  reorder: 'products?source=reorder',
+};
+
+export async function productListLoader(
+  ctx: ProductListLoaderContext
+): Promise<ProductListLoaderData> {
+  const { params, search } = ctx;
+  // A number is a page from an old Twig link; the API pages only by its own cursor.
+  const page = search?.page ? String(search.page) : undefined;
+  const cursor = page && Number.isNaN(Number(page)) ? page : undefined;
+  const sort = search?.sort ?? DEFAULT_SORT;
+
+  const sourceType = params.source ?? (params.id ? 'categories' : undefined);
+
+  if (!sourceType) {
+    throw new Error('ProductList loader requires source type');
+  }
+
+  if (sourceType === 'categories' && params.id) {
+    return loadCategoryProducts(params.id, cursor, sort);
+  }
+
+  if (sourceType === 'search') {
+    const keyword = (search?.q ?? params.keyword ?? '').trim();
+    return loadSearchProducts(keyword, cursor, sort);
+  }
+
+  if (sourceType === 'tags' && params.id) {
+    return loadTagProducts(params.id, cursor, sort);
+  }
+
+  if (sourceType === 'brands' && params.id) {
+    return loadBrandProducts(params.id, cursor, sort);
+  }
+
+  // Only a signed-in customer has products to order again; the API answers a guest 401.
+  if (sourceType === 'reorder' && !getAuthToken()) throw unauthorized();
+
+  if (sourceType in SOURCE_TITLE_KEY) {
+    return loadStaticProducts(
+      sourceType as StaticSource,
+      params.title ?? '',
+      params.slug ?? '',
+      cursor,
+      sort
+    );
+  }
+
+  throw new Error(`Unknown source type: ${sourceType}`);
+}
+
+// ============================================================================
+// Source-Specific Loaders
+// ============================================================================
+
+async function loadCategoryProducts(
+  id: string,
+  cursor: string | undefined,
+  sort: string
+): Promise<ProductListLoaderData> {
+  const { queryClient, i18n } = getTwilightContext();
+  let categoryData, productsResult;
+  try {
+    [categoryData, productsResult] = await Promise.all([
+      queryClient.fetchQuery(category.queries.detail(id)),
+      queryClient.fetchQuery(
+        product.queries.list({
+          source: 'categories',
+          sourceValue: id,
+          cursor,
+          sort,
+          filterable: true,
+        })
+      ),
+    ]);
+  } catch {
+    throw notFound();
+  }
+
+  if (!categoryData) throw notFound();
+
+  return {
+    page: {
+      slug: RouteId.PRODUCT_INDEX,
+      id,
+      title: categoryData.name,
+      breadcrumbs: [
+        { name: i18n.t('common.titles.home'), url: '/' },
+        { name: categoryData.name, url: categoryData.url },
+      ],
+    },
+    source: { type: 'categories', value: id, entity: categoryData },
+    query: { sort, filters: true },
+    products: productsResult.items,
+    pagination: {
+      next: productsResult.next,
+    },
+    filters: productsResult.filters,
+  };
+}
+
+async function loadSearchProducts(
+  keyword: string,
+  cursor: string | undefined,
+  sort: string
+): Promise<ProductListLoaderData> {
+  if (!keyword) {
+    const { i18n } = getTwilightContext();
+    return {
+      page: {
+        slug: RouteId.SEARCH,
+        title: i18n.t('pages.products.search_result'),
+        breadcrumbs: [
+          { name: i18n.t('common.titles.home'), url: '/' },
+          { name: i18n.t('pages.products.search_result'), url: '/search' },
+        ],
+      },
+      source: { type: 'search', value: '' },
+      query: { sort, filters: true },
+      products: [],
+      pagination: { next: null },
+    };
+  }
+
+  const { queryClient, i18n } = getTwilightContext();
+  const productsResult = await queryClient.fetchQuery(
+    product.queries.list({
+      source: 'search',
+      sourceValue: keyword,
+      cursor,
+      sort,
+      filterable: true,
+    })
+  );
+
+  return {
+    page: {
+      slug: RouteId.SEARCH,
+      title: i18n.t('common.elements.search_about').replace(':word', keyword),
+      breadcrumbs: [
+        { name: i18n.t('common.titles.home'), url: '/' },
+        { name: keyword, url: '/search' },
+      ],
+    },
+    source: { type: 'search', value: keyword },
+    query: { sort, filters: true },
+    products: productsResult.items,
+    pagination: {
+      next: productsResult.next,
+    },
+    filters: productsResult.filters,
+  };
+}
+
+async function loadTagProducts(
+  id: string,
+  cursor: string | undefined,
+  sort: string
+): Promise<ProductListLoaderData> {
+  const { queryClient, i18n } = getTwilightContext();
+  const [tagData, productsResult] = await Promise.all([
+    orThrow(queryClient.fetchQuery(product.queries.tag(id))),
+    queryClient.fetchQuery(
+      product.queries.list({
+        source: 'tags',
+        sourceValue: id,
+        cursor,
+        sort,
+      })
+    ),
+  ]);
+
+  if (!tagData) throw notFound();
+
+  // List products carry their tags without an id, so the URL is there only sometimes.
+  const tagUrl = productsResult.items[0]?.tags?.find((t) => String(t.id) === id)?.url ?? '';
+  const tag = { id: Number(tagData.id), name: tagData.name, url: tagUrl };
+
+  return {
+    page: {
+      slug: RouteId.PRODUCT_INDEX_TAG,
+      id,
+      title: tag.name,
+      breadcrumbs: [
+        { name: i18n.t('common.titles.home'), url: '/' },
+        // Laravel's own `tags/{id}` route, for when the listed tags carry no URL.
+        { name: tag.name, url: tag.url || `/tags/${id}` },
+      ],
+    },
+    source: { type: 'tags', value: id, entity: tag },
+    query: { sort, filters: false },
+    products: productsResult.items,
+    pagination: {
+      next: productsResult.next,
+    },
+  };
+}
+
+async function loadBrandProducts(
+  id: string,
+  cursor: string | undefined,
+  sort: string
+): Promise<ProductListLoaderData> {
+  const { queryClient, i18n } = getTwilightContext();
+  let brandData, productsResult;
+  try {
+    [brandData, productsResult] = await Promise.all([
+      queryClient.fetchQuery(brand.queries.detail(id)),
+      queryClient.fetchQuery(
+        product.queries.list({
+          source: 'brands',
+          sourceValue: id,
+          cursor,
+          sort,
+        })
+      ),
+    ]);
+  } catch {
+    throw notFound();
+  }
+
+  if (!brandData) throw notFound();
+
+  return {
+    page: {
+      slug: RouteId.BRANDS_INDEX,
+      id,
+      title: brandData.name,
+      breadcrumbs: [
+        { name: i18n.t('common.titles.home'), url: '/' },
+        // The brand API sends no url.
+        { name: brandData.name, url: `/brands/${id}` },
+      ],
+    },
+    source: { type: 'brands', value: id, entity: brandData },
+    query: { sort, filters: false },
+    products: productsResult.items,
+    pagination: {
+      next: productsResult.next,
+    },
+  };
+}
+
+const SOURCE_ROUTE_ID: Record<StaticSource, string> = {
+  latest: RouteId.PRODUCT_INDEX_LATEST,
+  sales: RouteId.PRODUCT_INDEX_SALES,
+  offers: RouteId.PRODUCT_INDEX_OFFERS,
+  reorder: RouteId.PRODUCT_INDEX,
+};
+
+async function loadStaticProducts(
+  source: StaticSource,
+  title: string,
+  slug: string,
+  cursor: string | undefined,
+  sort: string
+): Promise<ProductListLoaderData> {
+  const { queryClient, i18n } = getTwilightContext();
+  const resolvedTitle = title || i18n.t(SOURCE_TITLE_KEY[source]);
+  const resolvedSlug = slug || SOURCE_SLUG[source];
+  const productsResult = await queryClient.fetchQuery({
+    ...product.queries.list({
+      source: SOURCE_TO_API[source],
+      cursor,
+      sort,
+    }),
+    // The reorder key names no customer, so a cached list could be another session's.
+    ...(source === 'reorder' && { staleTime: 0 }),
+  });
+
+  return {
+    page: {
+      slug: SOURCE_ROUTE_ID[source],
+      title: resolvedTitle,
+      breadcrumbs: [
+        { name: i18n.t('common.titles.home'), url: '/' },
+        { name: resolvedTitle, url: `/${resolvedSlug}` },
+      ],
+    },
+    source: { type: source },
+    query: { sort, filters: false },
+    products: productsResult.items,
+    pagination: {
+      next: productsResult.next,
+    },
+  };
+}

package/tailwind/routes/product-listing/types.ts.txt

@@ -0,0 +1,96 @@
+/**
+ * Product List Route Types
+ * Unified types for all product listing pages (categories, search, tags, brands, latest/sales/offers).
+ */
+
+import type { Product, Category } from '../../types';
+import type { Brand } from '../brands/types';
+import type { RoutePagination } from '../types';
+import type { Filter } from '../../api/product';
+
+// Re-export for convenience
+export type { Category } from '../../types';
+export type { Brand } from '../brands/types';
+export type { RoutePagination } from '../types';
+
+// ============================================================================
+// Source Types
+// ============================================================================
+
+/** Unified source type matching API sources directly */
+export type ProductListSource =
+  'categories' | 'latest' | 'sales' | 'offers' | 'search' | 'tags' | 'brands' | 'reorder';
+
+/** Tag entity - products can be filtered by tags */
+export interface ProductListTag {
+  id: number;
+  name: string;
+  url: string;
+}
+
+/** Entity union type for source metadata */
+export type ProductListEntity = Category | ProductListTag | Brand;
+
+// ============================================================================
+// Loader Data
+// ============================================================================
+
+/** Static page metadata */
+export interface ProductListPageMeta {
+  title: string;
+  slug: string;
+  id?: string;
+  breadcrumbs?: import('../../types').Breadcrumb[];
+}
+
+/** Source configuration */
+export interface ProductListSourceConfig {
+  type: ProductListSource;
+  value?: string;
+  entity?: ProductListEntity;
+}
+
+/** URL query parameters — no page field, product list uses cursor-based pagination */
+export interface ProductListQuery {
+  sort: string;
+  filters?: boolean;
+}
+
+/** Unified loader data for all product listing pages */
+export interface ProductListLoaderData {
+  page: ProductListPageMeta;
+  source: ProductListSourceConfig;
+  query: ProductListQuery;
+  products: Product[];
+  pagination: RoutePagination;
+  filters?: Filter[];
+}
+
+// ============================================================================
+// Loader Params & Context
+// ============================================================================
+
+export interface ProductListLoaderParams {
+  id?: string;
+  source?: ProductListSource;
+  title?: string;
+  slug?: string;
+  keyword?: string;
+}
+
+export interface ProductListLoaderContext {
+  params: ProductListLoaderParams;
+  locale?: string;
+  search?: { page?: string | number; sort?: string; q?: string };
+}
+
+// ============================================================================
+// Props Types
+// ============================================================================
+
+/** Props for Category/Collection Page component */
+export interface CategoryPageProps {
+  page: ProductListPageMeta;
+  category: Category;
+  products: Product[];
+}

package/tailwind/routes/product-listing/useAppliedFilters.ts.txt

@@ -0,0 +1,130 @@
+import { useCallback, useEffect, useState } from 'react';
+import { product } from '../../api/product';
+import type { ProductListFilters } from '../../api/product';
+import type { Product } from '../../types';
+import type { ProductListLoaderData } from './types';
+import { onSallaEvent } from '../../utils/sdk-helpers';
+
+type Source = ProductListLoaderData['source'];
+type Node = Record<string, unknown>;
+
+/** Path segments that would reach the shared prototype chain if used as object keys. */
+const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+/**
+ * Reads the `filters[...]` selection `<salla-filters>` writes to the address bar
+ * (`filters[k]=v`, `filters[k][]=v`, `filters[k][sub]=v`) back into an object, so a
+ * filtered link can be opened directly.
+ *
+ * The keys come straight from the URL, so nodes are null-prototype objects and any
+ * `__proto__` / `constructor` / `prototype` segment drops the whole entry — a crafted
+ * `?filters[__proto__][x]=1` must never reach `Object.prototype`.
+ */
+export function parseFiltersFromSearch(search: string): ProductListFilters | null {
+  const out: Node = Object.create(null);
+  new URLSearchParams(search).forEach((value, rawKey) => {
+    if (!rawKey.startsWith('filters[')) return;
+    const path = [...rawKey.matchAll(/\[([^\]]*)\]/g)].map((m) => m[1]);
+    const isList = path[path.length - 1] === '';
+    const keys = isList ? path.slice(0, -1) : path;
+    if (!keys.length || keys.includes('') || keys.some((key) => UNSAFE_KEYS.has(key))) return;
+
+    let node = out;
+    keys.slice(0, -1).forEach((key) => {
+      const existing = node[key];
+      if (typeof existing !== 'object' || existing === null || Array.isArray(existing)) {
+        node[key] = Object.create(null);
+      }
+      node = node[key] as Node;
+    });
+    const leaf = keys[keys.length - 1];
+    if (isList) {
+      node[leaf] = [...(Array.isArray(node[leaf]) ? (node[leaf] as string[]) : []), value];
+    } else {
+      node[leaf] = value;
+    }
+  });
+  return Object.keys(out).length ? (out as ProductListFilters) : null;
+}
+
+interface FilteredPage {
+  items: Product[];
+  next: string | null;
+}
+
+export type AppliedFiltersStatus = 'idle' | 'loading' | 'ready' | 'error';
+
+/**
+ * Applies the `<salla-filters>` selection to the product list.
+ *
+ * The filters component only rewrites the address bar (`history.pushState`, invisible
+ * to the router) and emits `salla-filters::changed`; nothing re-queries the list, so
+ * the route's loader output — fetched without filters — kept showing. This listens
+ * for that event (and for a filtered URL on first load) and fetches the first page
+ * with the selection.
+ *
+ * Each fetched page is stored with the selection that produced it, so `page` is only
+ * ever the page for the *current* selection. Until it arrives `status` is `loading`
+ * (and `lastPage` is the previous selection's page, for a dimmed placeholder); if the
+ * request fails `status` is `error` and `retry` re-runs it — the old products never
+ * pass for the new selection.
+ */
+export function useAppliedFilters(
+  source: Source,
+  sort: string,
+  enabled: boolean
+): {
+  filters: ProductListFilters | null;
+  page: FilteredPage | null;
+  lastPage: FilteredPage | null;
+  status: AppliedFiltersStatus;
+  retry: () => void;
+} {
+  const [filters, setFilters] = useState<ProductListFilters | null>(null);
+  const [result, setResult] = useState<{ key: string; page: FilteredPage } | null>(null);
+  const [failedKey, setFailedKey] = useState<string | null>(null);
+  const [attempt, setAttempt] = useState(0);
+
+  useEffect(() => {
+    if (!enabled) return;
+    setFilters(parseFiltersFromSearch(window.location.search));
+    const onChanged = (...args: unknown[]) => {
+      const next = args[0] as ProductListFilters | undefined;
+      setFilters(next && Object.keys(next).length ? { ...next } : null);
+    };
+    return onSallaEvent('salla-filters::changed', onChanged);
+  }, [enabled, source.type, source.value]);
+
+  const key = filters ? JSON.stringify([source.type, source.value, sort, filters]) : '';
+
+  useEffect(() => {
+    if (!filters) return;
+    const controller = new AbortController();
+    setFailedKey(null);
+    product
+      .list({
+        source: source.type,
+        sourceValue: source.value,
+        sort,
+        filterable: true,
+        filters,
+        signal: controller.signal,
+      })
+      .then((res) => setResult({ key, page: { items: res.items, next: res.next } }))
+      .catch(() => {
+        // Aborted by a newer selection (its own effect run owns the state now), or failed.
+        if (!controller.signal.aborted) setFailedKey(key);
+      });
+    return () => controller.abort();
+    // `key` already encodes filters + source + sort.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key, attempt]);
+
+  const retry = useCallback(() => setAttempt((n) => n + 1), []);
+
+  if (!filters) return { filters: null, page: null, lastPage: null, status: 'idle', retry };
+
+  const page = result?.key === key ? result.page : null;
+  const status: AppliedFiltersStatus = page ? 'ready' : failedKey === key ? 'error' : 'loading';
+  return { filters, page, lastPage: result?.page ?? null, status, retry };
+}

package/tailwind/routes/product-short-link.ts.txt

@@ -0,0 +1,104 @@
+import { useEffect, useState } from 'react';
+import { product } from '../api/product';
+import { isLocale } from '../providers/locale-constants';
+import { useLocation, useNavigate } from '../providers/NavigationProvider';
+
+/** Short codes are 5-10 letters/digits (e.g. `lvXvzln`). */
+const SHORT_CODE = /^[A-Za-z0-9]{5,10}$/;
+
+/**
+ * The product short code in a path shaped `/{locale}/{code}` or `/{code}` (the
+ * store base is already stripped from the router's location), plus the locale
+ * segment to keep when redirecting. `null` for any other path.
+ */
+export function parseShortLinkPath(pathname: string): { code: string; locale?: string } | null {
+  const segments = pathname.split('/').filter(Boolean);
+  if (segments.length === 2 && isLocale(segments[0]) && SHORT_CODE.test(segments[1])) {
+    return { code: segments[1], locale: segments[0] };
+  }
+  if (segments.length === 1 && !isLocale(segments[0]) && SHORT_CODE.test(segments[0])) {
+    return { code: segments[0] };
+  }
+  return null;
+}
+
+/** A product URL in the stores' "new URLs" format: `{sku}-{name}`, or `p{id}-{name}` without a SKU. */
+const PRODUCT_KEY = /^([0-9A-Za-z]+)-./;
+
+/** The `{sku}` or `p{id}` key of `/{locale}/{sku}-{name}` or `/{sku}-{name}`, with that locale. */
+export function parseProductKeyPath(pathname: string): { key: string; locale?: string } | null {
+  const segments = pathname.split('/').filter(Boolean);
+  const hasLocale = segments.length === 2 && isLocale(segments[0]);
+  if (!hasLocale && (segments.length !== 1 || isLocale(segments[0]))) return null;
+  const key = segments[segments.length - 1].match(PRODUCT_KEY)?.[1];
+  if (!key) return null;
+  return hasLocale ? { key, locale: segments[0] } : { key };
+}
+
+function productKeyOf(url: string | undefined): string | undefined {
+  try {
+    const last = new URL(url ?? '').pathname.split('/').filter(Boolean).pop() ?? '';
+    return last.match(PRODUCT_KEY)?.[1];
+  } catch {
+    return undefined;
+  }
+}
+
+/** Like Laravel: `p{id}` is the id; anything else is a SKU, which only search can find. */
+async function findByProductKey(key: string): Promise<number | null> {
+  const id = key.match(/^p(\d+)$/)?.[1];
+  if (id) return Number(id);
+  const { items } = await product.list({ source: 'search', keyword: key, perPage: 50 });
+  const found = items.find((item) => productKeyOf(item.url) === key);
+  return found ? Number(found.id) : null;
+}
+
+/** The SEO slug from a product URL (`…/{slug}/p{id}`), `-` when it has none. */
+export function slugFromProductUrl(url: string | undefined): string {
+  try {
+    const segments = new URL(url ?? '').pathname.split('/').filter(Boolean);
+    const last = segments[segments.length - 1] ?? '';
+    return /^p\d+$/.test(last) && segments.length > 1 ? segments[segments.length - 2] : '-';
+  } catch {
+    return '-';
+  }
+}
+
+/**
+ * Resolves a product URL that matched no route, a short link (`/ar/lvXvzln`) or
+ * a "new URLs" one (`/ar/1213asa-chocolate`), and replaces the URL with the
+ * product's page. Returns `true` while a lookup is in flight (so the 404 isn't
+ * flashed); settles to `false` when the path is neither or doesn't resolve.
+ */
+export function useProductShortLink(): boolean {
+  const { pathname } = useLocation();
+  const navigate = useNavigate();
+  const shortLink = parseShortLinkPath(pathname);
+  const productKey = parseProductKeyPath(pathname);
+  const lookup = shortLink?.code ?? productKey?.key;
+  const locale = shortLink?.locale ?? productKey?.locale;
+  const isShortLink = !!shortLink;
+  const [failed, setFailed] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!lookup) return;
+    let cancelled = false;
+    const productPath = isShortLink
+      ? product
+          .find(lookup)
+          .then((found) => (found?.id ? `${slugFromProductUrl(found.url)}/p${found.id}` : null))
+      : findByProductKey(lookup).then((id) => (id ? `-/p${id}` : null));
+    productPath
+      .then((path) => {
+        if (cancelled) return;
+        if (!path) return setFailed(lookup);
+        navigate(`${locale ? `/${locale}` : ''}/${path}`, { replace: true });
+      })
+      .catch(() => !cancelled && setFailed(lookup));
+    return () => {
+      cancelled = true;
+    };
+  }, [lookup, isShortLink, locale, navigate]);
+
+  return !!lookup && failed !== lookup;
+}