create-magic-storefront 0.2.0 → 0.4.0

package/template/app/account/page.tsx

@@ -5,19 +5,29 @@ import {
   useCustomer,
   useMagicStore,
   useStorefrontClient,
+  useTelegramSignIn,
+  useTelegramWebApp,
   useWishlist,
 } from '@magicstoreai/hydrogen';
 import type { Schema } from '@magicstoreai/storefront-client';
 import { useEffect, useState } from 'react';
-import { describe } from '@/lib/errors';
+import { describe, describePhoneShare } from '@/lib/errors';
 import { messages } from '@/lib/i18n';
 
 export default function AccountPage() {
   const { customer, isSignedIn, signOut } = useCustomer();
-  const t = messages(useMagicStore().locale);
+  const { status, isTelegram, canRequestContact } = useTelegramWebApp();
+  const { locale, shop } = useMagicStore();
+  const t = messages(locale);
+  // Until the app has looked (`unknown`, server render included), a shop with a bot may be open in
+  // Telegram: hold the Telegram block's place so the phone form does not jump down after mount.
+  const maybeTelegram = status === 'unknown' && shop?.features.telegramBot === true;
   return isSignedIn && customer ? (
     <div className="stack">
       <h1>{customer.name || customer.phone}</h1>
+      {/* A customer who only ever signed in through Telegram has no phone yet; older Telegram
+          clients cannot share it. */}
+      {canRequestContact && !customer.phone && <SharePhone />}
       <Orders />
       <SavedCount />
       <div>
@@ -25,13 +35,76 @@ export default function AccountPage() {
       </div>
     </div>
   ) : (
-    <SignIn />
+    <div className="stack" style={{ maxWidth: 360 }}>
+      <h1>{t.signIn}</h1>
+      {isTelegram && <TelegramBlock />}
+      {maybeTelegram && <TelegramBlock placeholder />}
+      <PhoneSignIn />
+    </div>
+  );
+}
+
+/**
+ * The Telegram sign-in above the phone form. As a `placeholder` it renders the same markup, hidden,
+ * so the reserved space always matches the real block.
+ */
+function TelegramBlock({ placeholder = false }: { placeholder?: boolean }) {
+  const t = messages(useMagicStore().locale);
+  return (
+    <div
+      className="stack"
+      aria-hidden={placeholder || undefined}
+      style={placeholder ? { visibility: 'hidden' } : undefined}
+    >
+      <TelegramSignIn />
+      <p className="muted">{t.orWithPhone}</p>
+    </div>
   );
 }
 
-function SignIn() {
-  const { requestOtp, verifyOtp } = useCustomer();
+/**
+ * Inside a Mini App: sign in with the launch data. The automatic sign-in runs in
+ * components/telegram-shell.tsx; this is the manual retry. The hook shares the attempt's state, so
+ * this shows the automatic attempt too: "Signing in…" while it runs, the relaunch hint when it failed.
+ */
+function TelegramSignIn() {
+  const { status, error, signIn } = useTelegramSignIn({ auto: false });
   const t = messages(useMagicStore().locale);
+  // FORBIDDEN: the shop has no bot, so retrying is pointless.
+  const unavailable = error?.code === 'FORBIDDEN';
+  return (
+    <div className="stack">
+      {!unavailable && (
+        <button
+          className="primary"
+          disabled={status === 'signing-in'}
+          onClick={() => void signIn()}
+        >
+          {status === 'signing-in' ? t.signingIn : t.signInWithTelegram}
+        </button>
+      )}
+      {status === 'failed' && (
+        <p className="error" role="alert">
+          {error?.code === 'UNAUTHENTICATED'
+            ? t.telegramRelaunch
+            : unavailable
+              ? t.telegramUnavailable
+              : describe(error, t.tryAgainLater)}
+        </p>
+      )}
+    </div>
+  );
+}
+
+/**
+ * Phone sign-in: a code by SMS, or — on a shop whose sign-in code is off
+ * (`shop.features.otpLogin === false`) — the phone alone.
+ */
+function PhoneSignIn() {
+  const { requestOtp, verifyOtp, signInWithPhone } = useCustomer();
+  const { locale, shop } = useMagicStore();
+  const t = messages(locale);
+  const withoutCode = shop?.features.otpLogin === false;
   const [phone, setPhone] = useState('');
   const [sent, setSent] = useState(false);
   const [code, setCode] = useState('');
@@ -49,11 +122,12 @@ function SignIn() {
   return (
     <form
       className="stack"
-      style={{ maxWidth: 360 }}
       onSubmit={(event) => {
         event.preventDefault();
         void attempt(async () => {
-          if (!sent) {
+          if (withoutCode) {
+            await signInWithPhone(phone);
+          } else if (!sent) {
             await requestOtp(phone);
             setSent(true);
           } else {
@@ -62,7 +136,6 @@ function SignIn() {
         });
       }}
     >
-      <h1>{t.signIn}</h1>
       <input
         value={phone}
         onChange={(e) => setPhone(e.target.value)}
@@ -84,12 +157,55 @@ function SignIn() {
           required
         />
       )}
-      <button className="primary">{sent ? t.signIn : t.sendCode}</button>
-      {error && <p className="error">{error}</p>}
+      <button className="primary">{sent || withoutCode ? t.signIn : t.sendCode}</button>
+      {error && (
+        <p className="error" role="alert">
+          {error}
+        </p>
+      )}
     </form>
   );
 }
 
+/**
+ * Signed in inside a Mini App without a phone: share the Telegram contact, which proves the phone.
+ * A declined request changes nothing.
+ */
+function SharePhone() {
+  const { shareTelegramPhone } = useCustomer();
+  const t = messages(useMagicStore().locale);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  async function share() {
+    setBusy(true);
+    setError(null);
+    try {
+      await shareTelegramPhone();
+    } catch (e) {
+      setError(describePhoneShare(e, t));
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <section className="stack">
+      <p className="muted">{t.sharePhoneHint}</p>
+      <div>
+        <button className="primary" disabled={busy} onClick={() => void share()}>
+          {t.sharePhone}
+        </button>
+      </div>
+      {error && (
+        <p className="error" role="alert">
+          {error}
+        </p>
+      )}
+    </section>
+  );
+}
+
 function Orders() {
   const client = useStorefrontClient();
   const [orders, setOrders] = useState<Schema<'Order'>[] | null>(null);

package/template/app/api/magicstore/preview/route.ts

@@ -0,0 +1,56 @@
+import {
+  THEME_PREVIEW_COOKIE,
+  previewRedirectPath,
+  verifyThemePreview,
+} from '@magicstoreai/hydrogen/server';
+import { cookies, draftMode } from 'next/headers';
+import { redirect } from 'next/navigation';
+
+import { storefrontToken } from '@/lib/api';
+
+/**
+ * The admin's theme editor opens `/api/magicstore/preview?token=…&path=/` (in a frame or a tab) to
+ * show an unpublished theme or unsaved changes. A valid token turns on draft mode and is kept in an
+ * httpOnly cookie for its ten minutes; pages then send it as `X-Theme-Preview`, uncached.
+ * `?exit=1` ends the preview. The token is signed with the webhook secret and never logged.
+ */
+export async function GET(request: Request): Promise<Response> {
+  const secret = process.env.MAGICSTORE_WEBHOOK_SECRET;
+  if (!secret) {
+    return new Response('MAGICSTORE_WEBHOOK_SECRET is not set', { status: 501 });
+  }
+  if (!storefrontToken()) {
+    // The API previews only a request that names its storefront token.
+    return new Response('MAGICSTORE_STOREFRONT_TOKEN is not set', { status: 501 });
+  }
+  const params = new URL(request.url).searchParams;
+  const path = previewRedirectPath(params.get('path'));
+  const jar = await cookies();
+
+  if (params.has('exit')) {
+    (await draftMode()).disable();
+    jar.delete(THEME_PREVIEW_COOKIE);
+    redirect(path);
+  }
+
+  const token = params.get('token');
+  const now = Math.floor(Date.now() / 1000);
+  const preview = await verifyThemePreview(secret, token, now);
+  if (preview === null || token === null) {
+    return new Response('The preview link is invalid or has expired.', {
+      status: 403,
+      headers: { 'Cache-Control': 'no-store' },
+    });
+  }
+
+  (await draftMode()).enable();
+  jar.set(THEME_PREVIEW_COOKIE, token, {
+    httpOnly: true,
+    secure: true,
+    // The editor shows the storefront in a frame on the admin's origin.
+    sameSite: 'none',
+    path: '/',
+    maxAge: Math.max(1, preview.expiresAt - now),
+  });
+  redirect(path);
+}

package/template/app/globals.css

@@ -4,6 +4,9 @@
   --muted: #6b6b76;
   --line: #e7e7ec;
   --danger: #c62828;
+  /* Controls and image placeholders: white and light grey here, Telegram's colors in a Mini App. */
+  --surface: #fff;
+  --placeholder: #f3f3f6;
   /* Brand tokens: app/layout.tsx overrides them with the merchant's colors (lib/brand.ts). */
   --accent: #1f5eff;
   --on-accent: #fff;
@@ -20,6 +23,32 @@
   color: var(--fg);
   background: var(--bg);
 }
+/*
+ * Inside a Telegram Mini App (components/telegram-shell.tsx marks <html>): Telegram's theme, which
+ * its script writes as --tg-theme-* on <html>, with the defaults above as fallbacks. The merchant's
+ * accent from <html style> (lib/brand.ts) still wins over Telegram's button color.
+ */
+html[data-telegram] {
+  --bg: var(--tg-theme-bg-color, #fff);
+  --fg: var(--tg-theme-text-color, #16161a);
+  --muted: var(--tg-theme-hint-color, #6b6b76);
+  --danger: var(--tg-theme-destructive-text-color, #c62828);
+  --surface: var(--tg-theme-secondary-bg-color, #fff);
+  --placeholder: var(--tg-theme-secondary-bg-color, #f3f3f6);
+  --accent: var(--tg-theme-button-color, #1f5eff);
+  --on-accent: var(--tg-theme-button-text-color, #fff);
+}
+html[data-telegram][data-color-scheme='dark'] {
+  --line: rgba(255, 255, 255, 0.14);
+  color-scheme: dark;
+}
+html[data-telegram] body {
+  /* Telegram's stable viewport (the sheet can be dragged), the dynamic viewport outside it. */
+  min-height: var(--tg-viewport-stable-height, 100dvh);
+  padding-left: max(env(safe-area-inset-left), var(--tg-safe-area-inset-left, 0px));
+  padding-right: max(env(safe-area-inset-right), var(--tg-safe-area-inset-right, 0px));
+  padding-bottom: max(env(safe-area-inset-bottom), var(--tg-safe-area-inset-bottom, 0px));
+}
 * {
   box-sizing: border-box;
 }
@@ -76,7 +105,7 @@ header.site .brand img {
   height: auto;
   aspect-ratio: 1;
   object-fit: cover;
-  background: #f3f3f6;
+  background: var(--placeholder);
   border-radius: 8px;
 }
 .muted {
@@ -117,7 +146,9 @@ button,
   padding: 10px 16px;
   border-radius: 8px;
   border: 1px solid var(--line);
-  background: #fff;
+  background: var(--surface);
+  color: var(--fg);
+  min-height: 44px;
   cursor: pointer;
   text-decoration: none;
 }
@@ -137,7 +168,10 @@ button:disabled {
 input,
 select {
   font: inherit;
+  min-height: 44px;
   padding: 9px 12px;
+  background: var(--surface);
+  color: var(--fg);
   border: 1px solid var(--line);
   border-radius: 8px;
 }
@@ -286,7 +320,7 @@ fieldset {
   width: 80px;
   height: 80px;
   object-fit: cover;
-  background: #f3f3f6;
+  background: var(--placeholder);
   border-radius: 12px;
 }
 .stories-circle .story img,
@@ -364,7 +398,7 @@ footer.site nav {
   padding: 12px 16px;
   border-left: 4px solid var(--accent);
   border-radius: 8px;
-  background: #f6f7fb;
+  background: var(--placeholder);
 }
 .callout[data-callout='warning'] {
   border-left-color: var(--danger);
@@ -376,3 +410,111 @@ footer.site nav {
 .author h1 {
   margin: 0;
 }
+/* Theme sections (theme/sections/): the merchant edits their content in the admin. */
+/* A section with nothing to show yet renders nothing, but ThemeSections still wraps it. */
+[data-section-id]:empty {
+  display: none;
+}
+.site-announcement {
+  margin: 0;
+  padding: 8px 16px;
+  background: var(--accent);
+  color: var(--on-accent);
+  text-align: center;
+}
+.hero {
+  display: grid;
+  border-radius: 12px;
+  overflow: hidden;
+  background: var(--placeholder);
+}
+.hero > img,
+.hero-text {
+  grid-area: 1 / 1;
+}
+.hero > img {
+  width: 100%;
+  height: auto;
+  aspect-ratio: 21 / 9;
+  object-fit: cover;
+}
+.hero-text {
+  align-self: center;
+  padding: 40px 24px;
+}
+.hero > img + .hero-text {
+  background: linear-gradient(to top, rgb(0 0 0 / 0.7), rgb(0 0 0 / 0.35) 55%, transparent);
+  color: #fff;
+  text-shadow: 0 1px 2px rgb(0 0 0 / 0.4);
+  align-self: stretch;
+  justify-content: flex-end;
+}
+.hero-center .hero-text {
+  align-items: center;
+  text-align: center;
+}
+.hero-text h1,
+.hero-text p {
+  margin: 0;
+  max-width: 40ch;
+}
+.hero-text .button,
+.image-with-text .button {
+  align-self: flex-start;
+  text-shadow: none;
+}
+.hero-center .hero-text .button {
+  align-self: center;
+}
+@media (max-width: 720px) {
+  .hero > img {
+    aspect-ratio: 4 / 5;
+  }
+}
+.rich-text-narrow {
+  max-width: 760px;
+}
+.image-with-text {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+  gap: 32px;
+  align-items: center;
+}
+.image-with-text.image-right > img {
+  order: 2;
+}
+.image-with-text > img {
+  width: 100%;
+  height: auto;
+  aspect-ratio: 4 / 3;
+  object-fit: cover;
+  border-radius: 12px;
+}
+@media (max-width: 720px) {
+  .image-with-text {
+    grid-template-columns: 1fr;
+  }
+  .image-with-text.image-right > img {
+    order: 0;
+  }
+}
+.testimonials {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(260px, 1fr));
+  gap: 20px;
+}
+.testimonials figure {
+  margin: 0;
+  padding: 16px;
+  border: 1px solid var(--line);
+  border-radius: 12px;
+}
+.testimonials blockquote {
+  margin: 0;
+  padding: 0;
+  border: 0;
+}
+.testimonials .rating {
+  color: var(--accent);
+  letter-spacing: 2px;
+}

package/template/app/layout.tsx

@@ -1,11 +1,18 @@
 import type { Metadata } from 'next';
 import Link from 'next/link';
+import Script from 'next/script';
 import type { ReactNode } from 'react';
 import { Image } from '@magicstoreai/hydrogen';
+// From /core, not the "use client" entry: a plain string a server component can read.
+import { TELEGRAM_WEB_APP_SCRIPT } from '@magicstoreai/hydrogen/core';
+import { loadThemeSettings } from '@magicstoreai/hydrogen/server';
 import { CartLink } from '@/components/cart-link';
+import { TelegramShell } from '@/components/telegram-shell';
 import { api, locale } from '@/lib/api';
+import { themePreview } from '@/lib/preview';
 import { brandStyle } from '@/lib/brand';
 import { messages } from '@/lib/i18n';
+import theme from '@/theme';
 import { Providers } from './providers';
 import './globals.css';
 
@@ -23,18 +30,30 @@ export async function generateMetadata(): Promise<Metadata> {
 }
 
 export default async function RootLayout({ children }: { children: ReactNode }) {
-  const [{ data: shop }, { data: collections }, { data: pages }] = await Promise.all([
-    api.shop(),
-    api.collectionsIndex({ query: { perPage: 6 } }),
-    api.pagesIndex(),
-  ]);
+  const [{ data: shop }, { data: collections }, { data: pages }, themeSettings] = await Promise.all(
+    [
+      api.shop(),
+      api.collectionsIndex({ query: { perPage: 6 } }),
+      api.pagesIndex(),
+      themePreview().then((preview) => loadThemeSettings(api, theme, { locale, preview })),
+    ],
+  );
+  const announcement = themeSettings.announcement as string;
   const t = messages(locale);
 
   return (
     // The merchant's colors, read per request: a change in the admin shows after SHOP_UPDATED.
-    <html lang={locale} style={brandStyle(shop.branding)}>
+    // Telegram's script (beforeInteractive) writes --tg-viewport-* into <html style> before React
+    // hydrates; suppressHydrationWarning covers this element's attributes only, not its children.
+    <html lang={locale} style={brandStyle(shop.branding)} suppressHydrationWarning>
       <body>
+        {/* Telegram's Mini App script, only for a shop with a bot: nobody else can open it in Telegram. */}
+        {shop.features.telegramBot && (
+          <Script src={TELEGRAM_WEB_APP_SCRIPT} strategy="beforeInteractive" />
+        )}
         <Providers shop={shop}>
+          <TelegramShell />
+          {announcement && <p className="site-announcement">{announcement}</p>}
           <header className="site">
             <nav>
               <Link href="/" className="brand">

package/template/app/page.tsx

@@ -1,16 +1,25 @@
-import { HomeSections } from '@/components/sections';
-import { api } from '@/lib/api';
+import { loadTemplate } from '@magicstoreai/hydrogen/server';
+import { ThemeSections } from '@magicstoreai/hydrogen/theme';
 
+import { api, locale } from '@/lib/api';
+import { themePreview } from '@/lib/preview';
+import theme, { components } from '@/theme';
+
+/**
+ * Home: the merchant's `index` template (edited in the admin's theme editor), or the theme's bundled
+ * one until the theme is pushed; the admin's draft while it previews (lib/preview.ts). It never needs `GET /home`; the `platform-home` section brings
+ * that layout in when the merchant adds it.
+ */
 export default async function Home() {
-  const { data: home } = await api.home();
-  // A shop that has not laid out its home page yet still greets buyers with its newest products.
-  const sections =
-    home.sections.length > 0
-      ? home.sections
-      : [{ id: 'default', type: 'NEW_ARRIVALS' as const, settings: { limit: null } }];
+  const [{ data: shop }, preview] = await Promise.all([api.shop(), themePreview()]);
+  const sections = await loadTemplate(api, 'index', theme, {
+    locale,
+    defaultLocale: shop.defaultLocale,
+    preview,
+  });
   return (
     <div className="home">
-      <HomeSections sections={sections} />
+      <ThemeSections sections={sections} components={components} />
     </div>
   );
 }

package/template/app/pages/[handle]/page.tsx

@@ -1,7 +1,11 @@
 import type { Metadata } from 'next';
+import { loadTemplate } from '@magicstoreai/hydrogen/server';
 import { pageMeta } from '@magicstoreai/hydrogen/seo';
+import { ThemeSections, type SectionComponents } from '@magicstoreai/hydrogen/theme';
 import { api, locale, orNotFound } from '@/lib/api';
-import { messages } from '@/lib/i18n';
+import { themePreview } from '@/lib/preview';
+import theme, { components } from '@/theme';
+import { PageContent } from '@/theme/sections/page-content';
 
 type Props = { params: Promise<{ handle: string }> };
 
@@ -12,18 +16,29 @@ export async function generateMetadata({ params }: Props): Promise<Metadata> {
   return { title: meta.title, description: meta.description };
 }
 
-/** A merchant's content page (about, delivery, offer…). `body` is the merchant's HTML. */
+/**
+ * A merchant's content page (about, delivery, offer…), laid out by the theme's `page` template:
+ * `page-content` shows the page's own title and body, other sections sit around it.
+ */
 export default async function ContentPage({ params }: Props) {
   const { handle } = await params;
-  const { data: page } = await orNotFound(api.pagesShow({ path: { handle } }));
+  const [{ data: page }, { data: shop }, preview] = await Promise.all([
+    orNotFound(api.pagesShow({ path: { handle } })),
+    api.shop(),
+    themePreview(),
+  ]);
+  const sections = await loadTemplate(api, 'page', theme, {
+    locale,
+    defaultLocale: shop.defaultLocale,
+    preview,
+  });
+  const pageComponents: SectionComponents<typeof theme.sections> = {
+    ...components,
+    'page-content': (props) => <PageContent {...props} page={page} />,
+  };
   return (
-    <article className="stack">
-      <h1>{page.title}</h1>
-      {page.body ? (
-        <div dangerouslySetInnerHTML={{ __html: page.body }} />
-      ) : (
-        <p className="muted">{messages(locale).nothingHere}</p>
-      )}
-    </article>
+    <div className="home">
+      <ThemeSections sections={sections} components={pageComponents} />
+    </div>
   );
 }

package/template/components/sections/collections.tsx

@@ -6,7 +6,8 @@ import { api } from '@/lib/api';
 
 import type { SectionOf } from './types';
 
-function CollectionTiles({
+/** Collection tiles linking to each collection; renders nothing for none. */
+export function CollectionTiles({
   collections,
   className = '',
 }: {

package/template/components/sections/product-shelves.tsx

@@ -8,7 +8,8 @@ import { messages } from '@/lib/i18n';
 
 import { SHELF_SIZE, type SectionOf } from './types';
 
-function Shelf({
+/** A titled row of product cards; renders nothing for no products. */
+export function Shelf({
   title,
   href,
   products,

package/template/components/telegram-shell.tsx

@@ -0,0 +1,54 @@
+'use client';
+
+import {
+  useTelegramBackButton,
+  useTelegramSignIn,
+  useTelegramWebApp,
+} from '@magicstoreai/hydrogen';
+import { usePathname, useRouter } from 'next/navigation';
+import { useEffect, useRef } from 'react';
+
+/**
+ * The storefront as a Telegram Mini App. Renders nothing; outside Telegram every hook is a no-op.
+ *
+ * - marks `<html>` with `data-telegram` / `data-color-scheme`, so `globals.css` takes Telegram's
+ *   theme colors;
+ * - shows the header's back arrow on every page but the home page. It goes back only while there is
+ *   history of ours behind the page; on the history entry the Mini App opened on (a deep link from
+ *   the bot, the return from a payment page) it goes home. Where the browser has the Navigation API
+ *   the entry is told by its history index, so revisiting the first page through a link still goes
+ *   back; elsewhere by its path;
+ * - signs the buyer in with the launch data once per visit — the only automatic Telegram sign-in in
+ *   the app (`/account` offers a manual one). A failure keeps the buyer browsing as a guest;
+ *   `/account` explains it. A referral in the `startapp` parameter is read by the server.
+ */
+export function TelegramShell() {
+  const pathname = usePathname();
+  const router = useRouter();
+  useTelegramWebApp({ documentAttributes: true });
+  // The page the Mini App opened on: history before it is not ours.
+  const entry = useRef<{ pathname: string; index: number | null }>({ pathname, index: null });
+  useEffect(() => {
+    entry.current.index = historyIndex();
+  }, []);
+  useTelegramBackButton(pathname !== '/', () => {
+    const index = historyIndex();
+    const atEntry =
+      index !== null && entry.current.index !== null
+        ? index <= entry.current.index
+        : pathname === entry.current.pathname;
+    if (atEntry) {
+      router.push('/');
+    } else {
+      router.back();
+    }
+  });
+  useTelegramSignIn();
+  return null;
+}
+
+/** The current history entry's index (Navigation API), or null where the browser lacks the API. */
+function historyIndex(): number | null {
+  const { navigation } = window as { navigation?: { currentEntry: NavigationHistoryEntry | null } };
+  return navigation?.currentEntry?.index ?? null;
+}