create-magic-storefront 0.5.0 → 0.6.0

package/template/components/ui/button.tsx

@@ -0,0 +1,90 @@
+import type { ButtonHTMLAttributes, ReactNode } from 'react';
+
+import { Icon, type IconName } from './icon';
+
+export type ButtonVariant = 'primary' | 'secondary' | 'link';
+export type ButtonSize = 'sm' | 'md' | 'lg';
+
+/**
+ * The classes of a button, for a `<Link>` or `<a>` that looks like one. One primary action per
+ * view; `secondary` for the rest; `link` for an inline text action.
+ */
+export function buttonClass({
+  variant = 'secondary',
+  size = 'md',
+  full = false,
+  className,
+}: {
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+  full?: boolean;
+  className?: string;
+} = {}): string {
+  return [
+    'button',
+    `button--${variant}`,
+    size !== 'md' && `button--${size}`,
+    full && 'button--full',
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ');
+}
+
+/**
+ * A button. `loading` keeps it the same size, marks it `aria-busy` and blocks a second press while
+ * the request runs; the label stays for screen readers.
+ */
+export function Button({
+  variant = 'secondary',
+  size = 'md',
+  full = false,
+  loading = false,
+  className,
+  disabled,
+  type = 'button',
+  children,
+  ...rest
+}: {
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+  full?: boolean;
+  loading?: boolean;
+} & ButtonHTMLAttributes<HTMLButtonElement>) {
+  return (
+    <button
+      type={type}
+      className={buttonClass({ variant, size, full, className })}
+      disabled={disabled || loading}
+      aria-busy={loading || undefined}
+      {...rest}
+    >
+      {children}
+    </button>
+  );
+}
+
+/** A square icon-only button; `label` is its accessible name. */
+export function IconButton({
+  icon,
+  label,
+  className,
+  type = 'button',
+  children,
+  ...rest
+}: { icon: IconName; label: string; children?: ReactNode } & Omit<
+  ButtonHTMLAttributes<HTMLButtonElement>,
+  'aria-label'
+>) {
+  return (
+    <button
+      type={type}
+      className={className ? `icon-button ${className}` : 'icon-button'}
+      aria-label={label}
+      {...rest}
+    >
+      <Icon name={icon} />
+      {children}
+    </button>
+  );
+}

package/template/components/ui/drawer.tsx

@@ -0,0 +1,84 @@
+'use client';
+
+import { useEffect, useId, useRef, type ReactNode } from 'react';
+
+import { IconButton } from './button';
+
+/**
+ * A panel over the page from one side: a native `<dialog>` opened with `showModal()`, so the
+ * browser traps focus, makes the page behind it inert and closes it on Esc. Controlled: `open`
+ * says whether it shows, `onClose` is called for Esc, the close button and a click on the backdrop.
+ * Focus goes back to whatever had it before the drawer opened. The page behind does not scroll
+ * while it is open (`html:has(.drawer[open])` in components.css).
+ */
+export function Drawer({
+  open,
+  onClose,
+  title,
+  closeLabel,
+  side = 'right',
+  footer,
+  className,
+  children,
+}: {
+  open: boolean;
+  onClose: () => void;
+  title: ReactNode;
+  closeLabel: string;
+  side?: 'left' | 'right' | 'bottom' | 'top';
+  footer?: ReactNode;
+  className?: string;
+  children: ReactNode;
+}) {
+  const dialog = useRef<HTMLDialogElement>(null);
+  const returnFocus = useRef<HTMLElement | null>(null);
+  const titleId = useId();
+
+  useEffect(() => {
+    const element = dialog.current;
+    if (element === null) {
+      return;
+    }
+    if (open && !element.open) {
+      returnFocus.current =
+        document.activeElement instanceof HTMLElement ? document.activeElement : null;
+      element.showModal();
+    } else if (!open && element.open) {
+      element.close();
+    }
+  }, [open]);
+
+  return (
+    <dialog
+      ref={dialog}
+      className={['drawer', `drawer--${side}`, className].filter(Boolean).join(' ')}
+      aria-labelledby={titleId}
+      onCancel={(event) => {
+        // Esc: the parent decides, so `open` stays the one source of truth.
+        event.preventDefault();
+        onClose();
+      }}
+      onClose={() => {
+        returnFocus.current?.focus();
+        returnFocus.current = null;
+      }}
+      onClick={(event) => {
+        // The dialog element itself is the backdrop; its content is the inner panel.
+        if (event.target === event.currentTarget) {
+          onClose();
+        }
+      }}
+    >
+      <div className="drawer__panel">
+        <header className="drawer__header">
+          <h2 id={titleId} className="drawer__title">
+            {title}
+          </h2>
+          <IconButton icon="close" label={closeLabel} onClick={onClose} />
+        </header>
+        <div className="drawer__body">{children}</div>
+        {footer && <footer className="drawer__footer">{footer}</footer>}
+      </div>
+    </dialog>
+  );
+}

package/template/components/ui/empty-state.tsx

@@ -0,0 +1,27 @@
+import type { ReactNode } from 'react';
+
+import { Icon, type IconName } from './icon';
+
+/** What a page shows when there is nothing yet: a title, a line of help and the way out. */
+export function EmptyState({
+  title,
+  icon,
+  action,
+  children,
+  as: Heading = 'h2',
+}: {
+  title: string;
+  icon?: IconName;
+  action?: ReactNode;
+  children?: ReactNode;
+  as?: 'h1' | 'h2' | 'h3';
+}) {
+  return (
+    <div className="empty-state">
+      {icon && <Icon name={icon} size={32} className="empty-state__icon" />}
+      <Heading className="empty-state__title">{title}</Heading>
+      {children && <div className="empty-state__text">{children}</div>}
+      {action && <div className="empty-state__action">{action}</div>}
+    </div>
+  );
+}

package/template/components/ui/field.tsx

@@ -0,0 +1,33 @@
+'use client';
+
+import { useId, type InputHTMLAttributes } from 'react';
+
+/**
+ * A labelled input with the API's message for it underneath (`VALIDATION_FAILED`), linked by
+ * `aria-describedby` and marked `aria-invalid`.
+ */
+export function Field({
+  label,
+  error,
+  ...input
+}: { label: string; error?: string | undefined } & InputHTMLAttributes<HTMLInputElement>) {
+  const id = useId();
+  return (
+    <div className="field">
+      <label className="field__label" htmlFor={id}>
+        {label}
+      </label>
+      <input
+        id={id}
+        aria-invalid={error ? true : undefined}
+        aria-describedby={error ? `${id}-error` : undefined}
+        {...input}
+      />
+      {error && (
+        <p id={`${id}-error`} className="field__error">
+          {error}
+        </p>
+      )}
+    </div>
+  );
+}

package/template/components/ui/icon.tsx

@@ -0,0 +1,112 @@
+import type { SVGProps } from 'react';
+
+/**
+ * Outline icons from Tabler Icons (MIT, https://tabler.io/icons), inlined so the storefront needs no
+ * icon package. 24×24, stroked with `currentColor`; `star-filled` is the one filled shape.
+ */
+const PATHS = {
+  search: ['M3 10a7 7 0 1 0 14 0a7 7 0 1 0 -14 0', 'M21 21l-6 -6'],
+  cart: [
+    'M6.331 8h11.339a2 2 0 0 1 1.977 2.304l-1.255 8.152a3 3 0 0 1 -2.966 2.544h-6.852a3 3 0 0 1 -2.965 -2.544l-1.255 -8.152a2 2 0 0 1 1.977 -2.304z',
+    'M9 11v-5a3 3 0 0 1 6 0v5',
+  ],
+  user: ['M8 7a4 4 0 1 0 8 0a4 4 0 0 0 -8 0', 'M6 21v-2a4 4 0 0 1 4 -4h4a4 4 0 0 1 4 4v2'],
+  heart: ['M19.5 12.572l-7.5 7.428l-7.5 -7.428a5 5 0 1 1 7.5 -6.566a5 5 0 1 1 7.5 6.572'],
+  menu: ['M4 6l16 0', 'M4 12l16 0', 'M4 18l16 0'],
+  close: ['M18 6l-12 12', 'M6 6l12 12'],
+  'chevron-down': ['M6 9l6 6l6 -6'],
+  'chevron-right': ['M9 6l6 6l-6 6'],
+  'chevron-left': ['M15 6l-6 6l6 6'],
+  plus: ['M12 5l0 14', 'M5 12l14 0'],
+  minus: ['M5 12l14 0'],
+  check: ['M5 12l5 5l10 -10'],
+  star: [
+    'M12 17.75l-6.172 3.245l1.179 -6.873l-5 -4.867l6.9 -1l3.086 -6.253l3.086 6.253l6.9 1l-5 4.867l1.179 6.873z',
+  ],
+  share: [
+    'M3 12a3 3 0 1 0 6 0a3 3 0 1 0 -6 0',
+    'M15 6a3 3 0 1 0 6 0a3 3 0 1 0 -6 0',
+    'M15 18a3 3 0 1 0 6 0a3 3 0 1 0 -6 0',
+    'M8.7 10.7l6.6 -3.4',
+    'M8.7 13.3l6.6 3.4',
+  ],
+  play: ['M7 4v16l13 -8z'],
+  filter: [
+    'M12 6a2 2 0 1 0 4 0a2 2 0 1 0 -4 0',
+    'M4 6l8 0',
+    'M16 6l4 0',
+    'M6 12a2 2 0 1 0 4 0a2 2 0 1 0 -4 0',
+    'M4 12l2 0',
+    'M10 12l10 0',
+    'M15 18a2 2 0 1 0 4 0a2 2 0 1 0 -4 0',
+    'M4 18l11 0',
+    'M19 18l2 0',
+  ],
+  phone: [
+    'M5 4h4l2 5l-2.5 1.5a11 11 0 0 0 5 5l1.5 -2.5l5 2v4a2 2 0 0 1 -2 2a16 16 0 0 1 -15 -15a2 2 0 0 1 2 -2',
+  ],
+  mail: [
+    'M3 7a2 2 0 0 1 2 -2h14a2 2 0 0 1 2 2v10a2 2 0 0 1 -2 2h-14a2 2 0 0 1 -2 -2v-10z',
+    'M3 7l9 6l9 -6',
+  ],
+  'map-pin': [
+    'M9 11a3 3 0 1 0 6 0a3 3 0 0 0 -6 0',
+    'M17.657 16.657l-4.243 4.243a2 2 0 0 1 -2.827 0l-4.244 -4.243a8 8 0 1 1 11.314 0z',
+  ],
+  clock: ['M3 12a9 9 0 1 0 18 0a9 9 0 0 0 -18 0', 'M12 7v5l3 3'],
+  link: [
+    'M9 15l6 -6',
+    'M11 6l.463 -.536a5 5 0 0 1 7.071 7.072l-.534 .464',
+    'M13 18l-.397 .534a5.068 5.068 0 0 1 -7.127 0a4.972 4.972 0 0 1 0 -7.071l.524 -.463',
+  ],
+  trash: [
+    'M4 7l16 0',
+    'M10 11l0 6',
+    'M14 11l0 6',
+    'M5 7l1 12a2 2 0 0 0 2 2h8a2 2 0 0 0 2 -2l1 -12',
+    'M9 7v-3a1 1 0 0 1 1 -1h4a1 1 0 0 1 1 1v3',
+  ],
+  truck: [
+    'M3 17a2 2 0 1 0 4 0a2 2 0 1 0 -4 0',
+    'M15 17a2 2 0 1 0 4 0a2 2 0 1 0 -4 0',
+    'M5 17h-2v-11a1 1 0 0 1 1 -1h9v12m-4 0h6m4 0h2v-6h-8m0 -5h5l3 5',
+  ],
+} as const;
+
+export type IconName = keyof typeof PATHS | 'star-filled';
+
+/**
+ * An icon, decorative by default (`aria-hidden`): the control around it carries the name. Pass
+ * `label` for an icon that stands alone and means something.
+ */
+export function Icon({
+  name,
+  size = 20,
+  label,
+  className,
+  ...rest
+}: { name: IconName; size?: number; label?: string } & Omit<SVGProps<SVGSVGElement>, 'name'>) {
+  const filled = name === 'star-filled';
+  const paths = PATHS[filled ? 'star' : name];
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill={filled ? 'currentColor' : 'none'}
+      stroke="currentColor"
+      strokeWidth={1.75}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className={className ? `icon ${className}` : 'icon'}
+      {...(label ? { role: 'img', 'aria-label': label } : { 'aria-hidden': true })}
+      focusable="false"
+      {...rest}
+    >
+      {paths.map((d) => (
+        <path key={d} d={d} />
+      ))}
+    </svg>
+  );
+}

package/template/components/ui/price.tsx

@@ -0,0 +1,35 @@
+import { Money } from '@magicstoreai/hydrogen';
+import { moneyAmount, type Money as MoneyValue } from '@magicstoreai/hydrogen/core';
+
+/**
+ * A price as the API sent it, through `<Money>` (the shop's format). The compare-at price shows,
+ * struck through, only when it is above the price: an equal or lower one is no discount. Nothing is
+ * computed; a missing price renders nothing.
+ */
+export function Price({
+  price,
+  compareAtPrice = null,
+  size = 'md',
+  className,
+}: {
+  price: MoneyValue | null | undefined;
+  compareAtPrice?: MoneyValue | null;
+  size?: 'sm' | 'md' | 'lg';
+  className?: string;
+}) {
+  if (price === null || price === undefined) {
+    return null;
+  }
+  const onSale = compareAtPrice !== null && moneyAmount(compareAtPrice) > moneyAmount(price);
+  const classes = ['price', `price--${size}`, onSale && 'price--sale', className].filter(Boolean);
+  return (
+    <span className={classes.join(' ')}>
+      <Money data={price} className="price__current" />
+      {onSale && (
+        <s className="price__compare">
+          <Money data={compareAtPrice} />
+        </s>
+      )}
+    </span>
+  );
+}

package/template/components/ui/quantity-stepper.tsx

@@ -0,0 +1,91 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+import { Icon } from './icon';
+
+/**
+ * A quantity: minus, a number field, plus; 44px targets. `max` is the stock the API sent
+ * (`quantityAvailable`, `null` = not tracked). Typing is kept as a draft and applied on blur or
+ * Enter, clamped to `min`…`max`; arrow keys step at once. `onChange` only ever receives a value in
+ * range and different from `value`.
+ */
+export function QuantityStepper({
+  value,
+  onChange,
+  min = 1,
+  max = null,
+  label,
+  decreaseLabel,
+  increaseLabel,
+  disabled = false,
+}: {
+  value: number;
+  onChange: (quantity: number) => void;
+  min?: number;
+  max?: number | null;
+  label: string;
+  decreaseLabel: string;
+  increaseLabel: string;
+  disabled?: boolean;
+}) {
+  const [draft, setDraft] = useState(String(value));
+  useEffect(() => setDraft(String(value)), [value]);
+
+  const clamp = (quantity: number) =>
+    Math.max(min, max === null ? quantity : Math.min(max, quantity));
+  const commit = (quantity: number) => {
+    const next = clamp(Number.isFinite(quantity) ? Math.trunc(quantity) : value);
+    setDraft(String(next));
+    if (next !== value) {
+      onChange(next);
+    }
+  };
+
+  // An empty or non-numeric draft means "never mind": the value stays.
+  const commitDraft = () => commit(draft.trim() === '' ? Number.NaN : Number(draft));
+
+  return (
+    <div className="quantity" role="group" aria-label={label}>
+      <button
+        type="button"
+        className="quantity__button"
+        aria-label={decreaseLabel}
+        disabled={disabled || value <= min}
+        onClick={() => commit(value - 1)}
+      >
+        <Icon name="minus" size={16} />
+      </button>
+      <input
+        className="quantity__input"
+        type="number"
+        inputMode="numeric"
+        aria-label={label}
+        min={min}
+        max={max ?? undefined}
+        value={draft}
+        disabled={disabled}
+        onChange={(event) => setDraft(event.target.value)}
+        onBlur={commitDraft}
+        onKeyDown={(event) => {
+          if (event.key === 'Enter') {
+            event.preventDefault();
+            commitDraft();
+          } else if (event.key === 'ArrowUp' || event.key === 'ArrowDown') {
+            event.preventDefault();
+            commit(value + (event.key === 'ArrowUp' ? 1 : -1));
+          }
+        }}
+      />
+      <button
+        type="button"
+        className="quantity__button"
+        aria-label={increaseLabel}
+        disabled={disabled || (max !== null && value >= max)}
+        onClick={() => commit(value + 1)}
+      >
+        <Icon name="plus" size={16} />
+      </button>
+    </div>
+  );
+}

package/template/components/ui/rating.tsx

@@ -0,0 +1,48 @@
+import type { CSSProperties } from 'react';
+
+import { Icon } from './icon';
+
+const STARS = [1, 2, 3, 4, 5];
+
+/**
+ * A product's rating as the API sent it (`rating.average`, `rating.count`): five stars filled to
+ * the average, and the count. Nothing without reviews. `label` is the text a screen reader hears
+ * instead of the stars (`ratingSummary` in `lib/i18n.ts`).
+ */
+export function Rating({
+  average,
+  count,
+  label,
+  showCount = true,
+}: {
+  average: number | null;
+  count: number;
+  label: string;
+  showCount?: boolean;
+}) {
+  if (average === null || count === 0) {
+    return null;
+  }
+  const fill = `${Math.min(Math.max(average / 5, 0), 1) * 100}%`;
+  return (
+    <span className="rating" role="img" aria-label={label}>
+      <span className="rating__stars" style={{ '--rating-fill': fill } as CSSProperties}>
+        <span className="rating__empty">
+          {STARS.map((star) => (
+            <Icon key={star} name="star" size={14} />
+          ))}
+        </span>
+        <span className="rating__full">
+          {STARS.map((star) => (
+            <Icon key={star} name="star-filled" size={14} />
+          ))}
+        </span>
+      </span>
+      {showCount && (
+        <span className="rating__count" aria-hidden="true">
+          {average.toFixed(1)} ({count})
+        </span>
+      )}
+    </span>
+  );
+}

package/template/components/ui/skeleton.tsx

@@ -0,0 +1,46 @@
+import type { CSSProperties } from 'react';
+
+/**
+ * A grey block the size of the content that will replace it (no layout shift when it arrives).
+ * Size it with a class, or `width` / `height` / `ratio`. Hidden from screen readers; the page
+ * announces loading once, not per block.
+ */
+export function Skeleton({
+  className,
+  width,
+  height,
+  ratio,
+}: {
+  className?: string;
+  width?: CSSProperties['width'];
+  height?: CSSProperties['height'];
+  ratio?: CSSProperties['aspectRatio'];
+}) {
+  return (
+    <span
+      className={className ? `skeleton ${className}` : 'skeleton'}
+      style={{ width, height, aspectRatio: ratio }}
+      aria-hidden="true"
+    />
+  );
+}
+
+/** Product cards while a grid loads: the card's image ratio and two text lines each. */
+export function ProductGridSkeleton({ count = 8 }: { count?: number }) {
+  return (
+    <ul className="product-grid" aria-hidden="true">
+      {Array.from({ length: count }, (_, index) => (
+        <li key={index} className="stack">
+          <Skeleton ratio="var(--media-ratio)" />
+          <Skeleton height="1rem" width="85%" />
+          <Skeleton height="1rem" width="40%" />
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+/** A page heading while the page loads. */
+export function TitleSkeleton({ width = '40%' }: { width?: string }) {
+  return <Skeleton className="skeleton--title" width={width} />;
+}