create-magic-storefront 0.5.0 → 0.6.0

package/template/components/wishlist/wishlist-view.tsx

@@ -0,0 +1,134 @@
+'use client';
+
+import {
+  MagicStoreError,
+  useMagicStore,
+  useStorefrontClient,
+  useWishlist,
+} from '@magicstoreai/hydrogen';
+import type { Schema } from '@magicstoreai/storefront-client';
+import Link from 'next/link';
+import { useEffect, useState } from 'react';
+
+import { ProductCard } from '@/components/product-card';
+import { buttonClass } from '@/components/ui/button';
+import { EmptyState } from '@/components/ui/empty-state';
+import { Icon } from '@/components/ui/icon';
+import { Skeleton } from '@/components/ui/skeleton';
+import { messages } from '@/lib/i18n';
+
+type Product = Schema<'Product'>;
+
+/** The API's page ceiling; a longer wishlist is asked for in several pages. */
+const PER_REQUEST = 100;
+
+/**
+ * The saved products: `useWishlist` holds ids, the products come from `productsIndex`
+ * (`filter[ids]`), in the wishlist's order. A product the shop no longer sells is left out. A
+ * guest's list lives on this device only, which the page says.
+ */
+export function WishlistView() {
+  const { locale } = useMagicStore();
+  const t = messages(locale);
+  const client = useStorefrontClient();
+  const { productIds, owner, status, remove } = useWishlist();
+  const key = productIds.join(',');
+  const [result, setResult] = useState<{ key: string; products: Product[] } | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let current = true;
+    const ids = key === '' ? [] : key.split(',');
+    const chunks = [];
+    for (let start = 0; start < ids.length; start += PER_REQUEST) {
+      chunks.push(ids.slice(start, start + PER_REQUEST));
+    }
+    Promise.all(
+      chunks.map((chunk) =>
+        client.productsIndex({
+          query: { 'filter[ids]': chunk.join(','), perPage: PER_REQUEST },
+        }),
+      ),
+    ).then(
+      (pages) => {
+        if (!current) {
+          return;
+        }
+        const byId = new Map(pages.flatMap((page) => page.data).map((p) => [p.id, p]));
+        setError(null);
+        setResult({
+          key,
+          products: ids.map((id) => byId.get(id)).filter((p): p is Product => p !== undefined),
+        });
+      },
+      (e: unknown) => {
+        if (current) {
+          setError(e instanceof MagicStoreError ? (e.detail ?? e.message) : t.somethingWentWrong);
+        }
+      },
+    );
+    return () => {
+      current = false;
+    };
+  }, [client, key, t.somethingWentWrong]);
+
+  if (error) {
+    return (
+      <p className="error" role="alert">
+        {error}
+      </p>
+    );
+  }
+  // Until the list and its products are in (a removal shows at once: the old products, filtered).
+  if (result === null || status === 'loading') {
+    return (
+      <ul className="product-grid" aria-busy="true">
+        {[0, 1, 2, 3].map((index) => (
+          <li key={index}>
+            <Skeleton ratio="var(--media-ratio)" />
+          </li>
+        ))}
+      </ul>
+    );
+  }
+  const products = result.products.filter((product) => productIds.includes(product.id));
+  if (productIds.length === 0 || products.length === 0) {
+    return (
+      <EmptyState
+        title={t.wishlistEmpty}
+        icon="heart"
+        action={
+          <Link href="/collections" className={buttonClass({ variant: 'primary' })}>
+            {t.shopNow}
+          </Link>
+        }
+      >
+        {t.wishlistEmptyHint}
+      </EmptyState>
+    );
+  }
+  return (
+    <div className="stack stack--loose">
+      {owner === 'guest' && (
+        <p className="wishlist__hint">
+          {t.wishlistGuestHint} <Link href="/account">{t.signIn}</Link>
+        </p>
+      )}
+      <ul className="product-grid">
+        {products.map((product) => (
+          <li key={product.id} className="wishlist__item">
+            <ProductCard product={product} locale={locale} />
+            <button
+              type="button"
+              className="icon-button wishlist__remove"
+              aria-label={t.removeFromWishlist(product.title)}
+              onClick={() => void remove(product.id)}
+            >
+              <Icon name="close" size={18} />
+            </button>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}

package/template/lib/article-outline.ts

@@ -0,0 +1,35 @@
+/** A heading of an article body, for its table of contents. */
+export type OutlineHeading = { id: string; text: string; level: 2 | 3 };
+
+const HEADING = /<h([23])(\s[^>]*)?>([\s\S]*?)<\/h\1>/gi;
+const ENTITIES: Record<string, string> = {
+  '&amp;': '&',
+  '&lt;': '<',
+  '&gt;': '>',
+  '&quot;': '"',
+  '&#39;': "'",
+  '&nbsp;': ' ',
+};
+
+/**
+ * The article's `h2` / `h3` headings, each given an anchor (`section-1`, `section-2`…) in the
+ * returned HTML so a table of contents can link to it. The body is the server's sanitised
+ * `bodyHtml` (no scripts, no handlers); a heading that already has an `id` keeps it.
+ */
+export function outlineArticle(bodyHtml: string): { html: string; headings: OutlineHeading[] } {
+  const headings: OutlineHeading[] = [];
+  const html = bodyHtml.replace(HEADING, (tag, level: string, attributes = '', inner: string) => {
+    const existing = /\sid="([^"]+)"/.exec(attributes)?.[1];
+    const id = existing ?? `section-${headings.length + 1}`;
+    const text = inner
+      .replace(/<[^>]+>/g, '')
+      .replace(/&(amp|lt|gt|quot|#39|nbsp);/g, (entity) => ENTITIES[entity] ?? entity)
+      .trim();
+    if (text === '') {
+      return tag;
+    }
+    headings.push({ id, text, level: level === '2' ? 2 : 3 });
+    return existing ? tag : `<h${level} id="${id}"${attributes}>${inner}</h${level}>`;
+  });
+  return { html, headings };
+}

package/template/lib/catalog-params.ts

@@ -0,0 +1,170 @@
+import type { Schema } from '@magicstoreai/storefront-client';
+
+export type Filter = Schema<'Filter'>;
+
+/** What a catalog page's URL says: the page, the order and the chosen filters. */
+export type Catalog = {
+  page: number;
+  sort: SortKey | undefined;
+  /** By filter id (`vendor`, `options[Color]`, `inStock`): the chosen values, in URL order. */
+  selected: Record<string, string[]>;
+  price: { min: number | undefined; max: number | undefined };
+};
+
+/** The orders a catalog page offers; anything else in `?sort=` means the default order. */
+export const SORT_KEYS = ['-createdAt', 'price', '-price', '-bestSellers', '-rating'] as const;
+export type SortKey = (typeof SORT_KEYS)[number];
+
+export type SearchParams = Record<string, string | string[] | undefined>;
+
+/**
+ * A filter's URL parameter: the API's own key (`filter[vendor]`, `filter[options][Color]`), so a
+ * plain GET form builds the URL.
+ */
+export function filterParam(id: string): string {
+  const option = OPTION_ID.exec(id);
+  return option ? `filter[options][${option[1]}]` : `filter[${id}]`;
+}
+
+/** An option filter's id: `options[<option name>]`. */
+const OPTION_ID = /^options\[(.+)\]$/;
+
+/** `q` of `search` / `searchFilters` (spec `maxLength`): a longer one is `VALIDATION_FAILED`. */
+export const SEARCH_QUERY_MAX = 200;
+
+export const PRICE_MIN = 'filter[price][min]';
+export const PRICE_MAX = 'filter[price][max]';
+
+function all(value: string | string[] | undefined): string[] {
+  return value === undefined ? [] : Array.isArray(value) ? value : [value];
+}
+
+function priceBound(value: string | string[] | undefined): number | undefined {
+  const raw = all(value)[0]?.trim();
+  if (!raw) {
+    return undefined;
+  }
+  const number = Number(raw);
+  return Number.isFinite(number) && number >= 0 ? number : undefined;
+}
+
+/**
+ * Reads a catalog page's `searchParams`, keeping only what the API offers: filters and values the
+ * filters endpoint returned for this page, a known sort, a page of at least 1. Anything else (an
+ * old link, a hand-edited URL) is dropped, so the API never sees it and never answers
+ * `VALIDATION_FAILED`. A LIST value may repeat (`filter[vendor]=a&filter[vendor]=b`) or be
+ * comma-joined.
+ */
+export function parseCatalog(params: SearchParams, filters: Filter[]): Catalog {
+  const selected: Record<string, string[]> = {};
+  let price: Catalog['price'] = { min: undefined, max: undefined };
+  for (const filter of filters) {
+    if (filter.type === 'PRICE_RANGE') {
+      price = { min: priceBound(params[PRICE_MIN]), max: priceBound(params[PRICE_MAX]) };
+      continue;
+    }
+    const given = all(params[filterParam(filter.id)]).flatMap((value) => value.split(','));
+    const allowed =
+      filter.type === 'BOOLEAN'
+        ? given.filter((value) => value === 'true')
+        : given.filter((value) => filter.values.some((option) => option.value === value));
+    const unique = [...new Set(allowed)];
+    if (unique.length > 0) {
+      selected[filter.id] = filter.type === 'BOOLEAN' ? ['true'] : unique;
+    }
+  }
+  const sort = SORT_KEYS.find((key) => key === all(params.sort)[0]);
+  const page = Math.max(1, Math.trunc(Number(all(params.page)[0])) || 1);
+  return { page, sort, selected, price };
+}
+
+/** Whether any filter is chosen (sort and page do not count). */
+export function hasFilters(catalog: Catalog): boolean {
+  return (
+    Object.keys(catalog.selected).length > 0 ||
+    catalog.price.min !== undefined ||
+    catalog.price.max !== undefined
+  );
+}
+
+/**
+ * The catalog as the API's query: `filter[vendor]=a,b`, `filter[options][Color]=Red,Blue`,
+ * `filter[price][min]`, `filter[inStock]=true`, `sort`, `page`.
+ */
+export function apiQuery(catalog: Catalog): Record<string, unknown> {
+  const query: Record<string, unknown> = { page: catalog.page };
+  const options: Record<string, string> = {};
+  for (const [id, values] of Object.entries(catalog.selected)) {
+    const option = OPTION_ID.exec(id);
+    if (option) {
+      options[option[1]!] = values.join(',');
+    } else {
+      query[filterParam(id)] = values.join(',');
+    }
+  }
+  if (Object.keys(options).length > 0) {
+    query['filter[options]'] = options;
+  }
+  if (catalog.price.min !== undefined) {
+    query[PRICE_MIN] = catalog.price.min;
+  }
+  if (catalog.price.max !== undefined) {
+    query[PRICE_MAX] = catalog.price.max;
+  }
+  if (catalog.sort !== undefined) {
+    query.sort = catalog.sort;
+  }
+  return query;
+}
+
+/**
+ * The page URL's query string for a catalog, `extra` first (the search page's `q`). Page 1 is left
+ * out, so every filtered or sorted link starts from the first page.
+ */
+export function catalogQuery(catalog: Catalog, extra: Record<string, string> = {}): string {
+  const params = new URLSearchParams(extra);
+  if (catalog.sort !== undefined) {
+    params.set('sort', catalog.sort);
+  }
+  for (const [id, values] of Object.entries(catalog.selected)) {
+    for (const value of values) {
+      params.append(filterParam(id), value);
+    }
+  }
+  if (catalog.price.min !== undefined) {
+    params.set(PRICE_MIN, String(catalog.price.min));
+  }
+  if (catalog.price.max !== undefined) {
+    params.set(PRICE_MAX, String(catalog.price.max));
+  }
+  if (catalog.page > 1) {
+    params.set('page', String(catalog.page));
+  }
+  const query = params.toString();
+  return query === '' ? '' : `?${query}`;
+}
+
+/** The same catalog on another page. */
+export function onPage(catalog: Catalog, page: number): Catalog {
+  return { ...catalog, page };
+}
+
+/** The catalog without one value of a filter (or the whole filter, or the price), back on page 1. */
+export function without(catalog: Catalog, id: string | 'price', value?: string): Catalog {
+  if (id === 'price') {
+    return { ...catalog, page: 1, price: { min: undefined, max: undefined } };
+  }
+  const selected = { ...catalog.selected };
+  const remaining = value === undefined ? [] : (selected[id] ?? []).filter((v) => v !== value);
+  if (remaining.length > 0) {
+    selected[id] = remaining;
+  } else {
+    delete selected[id];
+  }
+  return { ...catalog, page: 1, selected };
+}
+
+/** No filters, the same order, page 1. */
+export function cleared(catalog: Catalog): Catalog {
+  return { ...catalog, page: 1, selected: {}, price: { min: undefined, max: undefined } };
+}

package/template/lib/contacts.ts

@@ -0,0 +1,34 @@
+import type { Schema } from '@magicstoreai/storefront-client';
+
+type Contacts = Schema<'Contacts'>;
+type Social = Contacts['socials'][number];
+
+/** Network names are brand names: the same in every language. */
+export const SOCIAL_NAMES: Record<Social['network'], string> = {
+  TELEGRAM: 'Telegram',
+  INSTAGRAM: 'Instagram',
+  FACEBOOK: 'Facebook',
+  YOUTUBE: 'YouTube',
+  TIKTOK: 'TikTok',
+};
+
+/** `tel:` keeps only the digits and a leading plus; the shown number stays as the merchant wrote it. */
+export function telHref(number: string): string {
+  return `tel:${number.replace(/[^\d+]/g, '')}`;
+}
+
+/** A plain map link to a point: no embedded map, no script. */
+export function mapHref({ latitude, longitude }: { latitude: number; longitude: number }): string {
+  return `https://www.google.com/maps/search/?api=1&query=${latitude},${longitude}`;
+}
+
+/** Whether the shop gave any way to reach it at all. */
+export function hasContacts(contacts: Contacts): boolean {
+  return (
+    contacts.phones.length > 0 ||
+    contacts.email !== null ||
+    contacts.socials.length > 0 ||
+    contacts.headOffice !== null ||
+    contacts.branches.length > 0
+  );
+}

package/template/lib/errors.ts

@@ -6,6 +6,35 @@ export function describe(error: unknown, fallback: string): string {
   return error instanceof MagicStoreError ? (error.detail ?? error.message) : fallback;
 }
 
+/**
+ * A refused form, split for the screen: `fields` holds the messages of the `VALIDATION_FAILED`
+ * members the form has an input for (shown under each input), and `summary` one line for the rest —
+ * a refused member with no input on screen (`paymentMethodId`, `gender`…) or any other failure.
+ * Without that line such a refusal would leave the buyer with no message at all.
+ */
+export function formErrors(
+  error: unknown,
+  shown: readonly string[],
+  fallback: string,
+): { fields: Record<string, string>; summary: string | null } {
+  if (!(error instanceof MagicStoreError) || error.code !== 'VALIDATION_FAILED') {
+    return { fields: {}, summary: describe(error, fallback) };
+  }
+  const fields: Record<string, string> = {};
+  const rest: string[] = [];
+  for (const entry of error.errors) {
+    if (shown.includes(entry.field)) {
+      fields[entry.field] = entry.message;
+    } else {
+      rest.push(entry.message);
+    }
+  }
+  if (rest.length > 0) {
+    return { fields, summary: rest.join(' ') };
+  }
+  return { fields, summary: Object.keys(fields).length > 0 ? null : describe(error, fallback) };
+}
+
 /**
  * Why sharing the Telegram phone (`POST /customer/phone-verification`) failed. `CONTACT_EXPIRED`
  * asks to share again; `CONTACT_INVALID`, `CONTACT_NOT_OWN`, `INVALID_PHONE` and `TAKEN` show the