orionplace-react 0.1.0 → 0.2.1

package/templates/lib/orionplace/nativeApp.ts

@@ -0,0 +1,365 @@
+import type {
+  OrionplaceApiRequest,
+  OrionplaceApiResponse,
+} from '@/lib/orionplace/api';
+
+/*
+ * Android app build (ORIONPLACE_APP_ORIGIN, see orionplace/README.md and
+ * orionplace/runtime/app.mjs).
+ *
+ * The app runs from https://localhost inside the Android WebView. Its API
+ * requests go to the public storefront (for example
+ * https://shop.example.com/api/...) through Capacitor's native HTTP, so the
+ * storefront answers them exactly as the website's requests. The requests
+ * carry the storefront Origin and Referer, which the backend needs for CSRF
+ * checks and which a WebView fetch can not set. The session and CSRF cookies
+ * live in the native cookie store, which neither document.cookie nor
+ * Capacitor's getCookies shows for the storefront, so the CSRF token is read
+ * from the responses' Set-Cookie headers.
+ */
+
+interface NativeHttpResponse {
+  status: number;
+  headers: Record<string, string>;
+  data: unknown;
+}
+
+interface AppPlugin {
+  addListener?: (
+    event: 'backButton',
+    listener: (data: { canGoBack: boolean }) => void,
+  ) => unknown;
+  exitApp?: () => Promise<void>;
+}
+
+interface CapacitorBridge {
+  nativePromise?: <T>(
+    plugin: string,
+    method: string,
+    options: Record<string, unknown>,
+  ) => Promise<T>;
+  isPluginAvailable?: (name: string) => boolean;
+  Plugins?: { App?: AppPlugin };
+}
+
+/** Storefront cookies received in this app run, by name. */
+const storefrontCookies = new Map<string, string>();
+
+function bridge() {
+  const nativePromise = (globalThis as { Capacitor?: CapacitorBridge })
+    .Capacitor?.nativePromise;
+  if (!nativePromise) {
+    throw new Error('The Android app bridge is not available.');
+  }
+
+  return nativePromise;
+}
+
+/** The public storefront origin of an app build; empty on the website. */
+export function nativeAppOrigin(configured: unknown): string {
+  return typeof configured === 'string' ? configured : '';
+}
+
+/**
+ * The backend serves some media itself (blog images and videos) and sends
+ * them as root-relative `/ps3/...` paths. The website's gateway answers
+ * them; an app build has no server of its own, so they load from the
+ * storefront. Other addresses stay as they are.
+ */
+export function appMediaUrl(url: string, origin: string): string {
+  return origin && url.startsWith('/') && !url.startsWith('//')
+    ? origin + url
+    : url;
+}
+
+/** This build's storefront origin: next.config.ts sets it for the app build. */
+export const APP_ORIGIN = nativeAppOrigin(process.env.ORIONPLACE_APP_ORIGIN);
+
+const LOCALE_KEY = 'orionplace-app-locale';
+
+/**
+ * The language the customer picked last. The app opens at its start page
+ * without `?locale`, so the device keeps the choice between launches.
+ */
+export function savedAppLocale(): string {
+  try {
+    return localStorage.getItem(LOCALE_KEY) ?? '';
+  } catch {
+    return '';
+  }
+}
+
+export function saveAppLocale(code: string) {
+  try {
+    localStorage.setItem(LOCALE_KEY, code);
+  } catch {
+    // Without storage the app starts in the storefront's language.
+  }
+}
+
+/*
+ * The last open menu (language, currency, catalog…) gets the Escape key; it
+ * tells it closed by preventing the key's default.
+ */
+function closeOpenMenu(): boolean {
+  const open   = [...document.querySelectorAll('[aria-expanded="true"]')]
+    .filter((control) => control.getClientRects().length > 0);
+  const escape = new KeyboardEvent('keydown', {
+    key: 'Escape',
+    bubbles: true,
+    cancelable: true,
+  });
+  open.at(-1)?.dispatchEvent(escape);
+  return escape.defaultPrevented;
+}
+
+/**
+ * The Android back button closes the open dialog or menu, otherwise goes
+ * one page back and leaves the app on the first page. It needs the
+ * @capacitor/app plugin; without it Android closes the app on the first press.
+ */
+export function handleAppBackButton(): boolean {
+  const app = (globalThis as { Capacitor?: CapacitorBridge }).Capacitor
+    ?.Plugins?.App;
+  if (!app?.addListener) {
+    return false;
+  }
+  app.addListener('backButton', ({ canGoBack }) => {
+    const dialogs = document.querySelectorAll('dialog[open]');
+    const dialog  = dialogs[dialogs.length - 1] as HTMLDialogElement | undefined;
+    if (dialog) {
+      // Dialogs close themselves on `cancel`, as on the Escape key.
+      if (dialog.dispatchEvent(new Event('cancel', { cancelable: true }))) {
+        dialog.close();
+      }
+    } else if (closeOpenMenu()) {
+      // An open menu closed, as on the Escape key; the page stays.
+    } else if (canGoBack) {
+      history.back();
+    } else {
+      void app.exitApp?.();
+    }
+  });
+
+  return true;
+}
+
+/** A file as base64, the form Capacitor's Filesystem writes. */
+function base64(file: Blob): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader   = new FileReader();
+    reader.onload  = () => resolve(String(reader.result).replace(/^data:[^,]*,/, ''));
+    reader.onerror = () => reject(reader.error);
+    reader.readAsDataURL(file);
+  });
+}
+
+/**
+ * Saves a downloaded file in the Android app and opens Android's sheet to
+ * open or share it: the WebView ignores a download link. It needs the
+ * @capacitor/filesystem and @capacitor/share plugins; without them (and on
+ * the website) it returns false and the page uses its download link.
+ */
+export async function saveAppFile(file: Blob, filename: string): Promise<boolean> {
+  const capacitor = (globalThis as { Capacitor?: CapacitorBridge }).Capacitor;
+  if (
+    !capacitor?.nativePromise ||
+    !capacitor.isPluginAvailable?.('Filesystem') ||
+    !capacitor.isPluginAvailable('Share')
+  ) {
+    return false;
+  }
+  const name    = filename
+    .split(/[\\/]/)
+    .pop()
+    ?.replace(/[\u0000-\u001f\u007f]/g, '') || 'download';
+  const { uri } = await capacitor.nativePromise<{ uri: string }>('Filesystem', 'writeFile', {
+    path: `downloads/${name}`,
+    data: await base64(file),
+    directory: 'CACHE',
+    recursive: true,
+  });
+  try {
+    await capacitor.nativePromise('Share', 'share', {
+      title: name,
+      dialogTitle: name,
+      files: [uri],
+    });
+  } catch {
+    // Closing the sheet without a choice rejects too; the file is saved.
+  }
+  return true;
+}
+
+/** The storefront cookies as a Cookie header string, for the CSRF token. */
+export function nativeAppCookies(): string {
+  return [...storefrontCookies]
+    .map(([name, value]) => `${name}=${value}`)
+    .join('; ');
+}
+
+/*
+ * Android joins several Set-Cookie headers with a comma. A comma inside an
+ * Expires date is not followed by `name=`, so it does not split a cookie.
+ * A storefront proxy may expire a host-only copy next to the real cookie
+ * (`csrftoken=; Max-Age=0` beside `csrftoken=…; Domain=…`): a value set in
+ * the same response wins over that expiry.
+ */
+function rememberCookies(header: string) {
+  const live    = new Map<string, string>();
+  const expired = new Set<string>();
+  for (const cookie of header.split(/,\s*(?=[\w!#$%&'*+.^`|~-]+=)/)) {
+    const [pair = '', ...attributes] = cookie.split(';');
+    const separator                  = pair.indexOf('=');
+    const name                       = pair.slice(0, separator).trim();
+    if (separator < 1) {
+      continue;
+    }
+    const removed                    = attributes.some((attribute) =>
+      /^\s*max-age\s*=\s*0*\s*$|^\s*max-age\s*=\s*-/i.test(attribute),
+    );
+    if (removed) {
+      expired.add(name);
+    } else {
+      live.set(name, pair.slice(separator + 1).trim());
+    }
+  }
+  for (const name of expired) {
+    if (!live.has(name)) {
+      storefrontCookies.delete(name);
+    }
+  }
+  for (const [name, value] of live) {
+    storefrontCookies.set(name, value);
+  }
+}
+
+// GET parameters, encoded as the website's requests encode them.
+function withQuery(url: string, data: object) {
+  const query = new URLSearchParams();
+  for (const [name, value] of Object.entries(data)) {
+    for (const item of Array.isArray(value) ? value : [value]) {
+      if (item === undefined) {
+        continue;
+      }
+      query.append(
+        name,
+        item !== null && typeof item === 'object'
+          ? JSON.stringify(item)
+          : String(item ?? ''),
+      );
+    }
+  }
+  const text  = query.toString();
+
+  return text ? `${url}${url.includes('?') ? '&' : '?'}${text}` : url;
+}
+
+async function base64File(file: File) {
+  const bytes = new Uint8Array(await file.arrayBuffer());
+  let binary  = '';
+  for (let index = 0; index < bytes.length; index += 0x8000) {
+    binary += String.fromCharCode(...bytes.subarray(index, index + 0x8000));
+  }
+
+  return btoa(binary);
+}
+
+async function nativeBody(data: OrionplaceApiRequest['data']) {
+  if (!(data instanceof FormData)) {
+    return { data: JSON.stringify(data), dataType: 'json' };
+  }
+  const entries = [];
+  for (const [key, value] of data.entries()) {
+    entries.push(
+      value instanceof File
+        ? {
+            key,
+            value: await base64File(value),
+            type: 'base64File',
+            contentType: value.type,
+            fileName: value.name,
+          }
+        : { key, value, type: 'string' },
+    );
+  }
+
+  return { data: entries, dataType: 'formData' };
+}
+
+function header(headers: Record<string, string>, name: string) {
+  const entry = Object.entries(headers).find(
+    ([key]) => key.toLowerCase() === name,
+  );
+
+  return entry?.[1] ?? '';
+}
+
+/** Sends one API request of the Android app to the storefront origin. */
+export async function nativeAppRequest(
+  origin: string,
+  path: string,
+  request: OrionplaceApiRequest,
+): Promise<OrionplaceApiResponse> {
+  const isGet    = request.method === 'GET';
+  const url      =
+    isGet && !(request.data instanceof FormData)
+      ? withQuery(`${origin}${path}`, request.data)
+      : `${origin}${path}`;
+  const headers  = {
+    ...request.headers,
+    Origin: origin,
+    Referer: `${origin}/`,
+  } as Record<string, string>;
+  if (request.data instanceof FormData) {
+    // Android writes no body without this type; it adds the boundary itself.
+    for (const name of Object.keys(headers)) {
+      if (name.toLowerCase() === 'content-type') {
+        delete headers[name];
+      }
+    }
+    headers['Content-Type'] = 'multipart/form-data';
+  }
+  request.signal?.throwIfAborted();
+  const call     = bridge();
+  const options  = {
+    url,
+    method: request.method,
+    headers,
+    // JSON answers arrive parsed; files arrive as base64.
+    responseType: 'blob',
+    connectTimeout: 35_000,
+    readTimeout: 35_000,
+    ...(isGet ? {} : await nativeBody(request.data)),
+  };
+  let response: NativeHttpResponse;
+  try {
+    response = await call<NativeHttpResponse>('CapacitorHttp', 'request', options);
+  } catch {
+    // No network or no answer: fail as fetch does (a TypeError), so pages
+    // show their translated network message, not Android's own text.
+    request.signal?.throwIfAborted();
+    throw new TypeError('Network request failed');
+  }
+  request.signal?.throwIfAborted();
+  rememberCookies(header(response.headers, 'set-cookie'));
+
+  const type     = header(response.headers, 'content-type');
+  let body       = response.data;
+  if (!type.includes('json') && typeof body === 'string' && response.status < 300) {
+    const bytes = Uint8Array.from(atob(body), (character) =>
+      character.charCodeAt(0),
+    );
+    body        = new Blob([bytes], { type });
+  }
+
+  return {
+    body,
+    status: response.status,
+    cookies: [],
+    headers: {
+      'content-type': type,
+      'content-disposition': header(response.headers, 'content-disposition'),
+    },
+  };
+}

package/templates/lib/orionplace/navigation.tsx

@@ -0,0 +1,121 @@
+'use client';
+
+import NextLink from 'next/link';
+import { useRouter } from 'next/navigation';
+import type { ComponentProps, MouseEvent } from 'react';
+import { APP_ORIGIN } from '@/lib/orionplace/nativeApp';
+
+/*
+ * Navigation of the storefront. The website uses the Next.js router. The
+ * Android app build is one static page (app/[[...path]]/page.app.tsx), so it
+ * changes the address with the History API, which Next.js reports to
+ * usePathname and useSearchParams; app/_storefront/AppRoutes.tsx then shows
+ * the page of that address.
+ */
+
+type Href = ComponentProps<typeof NextLink>['href'];
+
+/** Set by a push that asks for the top of the next page. */
+let scrollOnNextPage = false;
+
+/** Set by a replace: the page changed its own address (a tab, a page number). */
+let replacedAddress = '';
+
+/** The address of a link: a string, or Next.js's { pathname, query } object. */
+export function hrefText(href: Href): string {
+  if (typeof href === 'string') {
+    return href;
+  }
+  const query = new URLSearchParams();
+  for (const [name, value] of Object.entries(href.query ?? {})) {
+    for (const item of Array.isArray(value) ? value : [value]) {
+      if (item !== undefined && item !== null) {
+        query.append(name, String(item));
+      }
+    }
+  }
+  const search = query.toString();
+  return `${href.pathname ?? ''}${search ? `?${search}` : ''}${href.hash ?? ''}`;
+}
+
+const appRouter = {
+  push(href: string, options?: { scroll?: boolean }) {
+    scrollOnNextPage = options?.scroll !== false;
+    replacedAddress  = '';
+    history.pushState(null, '', href);
+  },
+  replace(href: string, options?: { scroll?: boolean }) {
+    scrollOnNextPage = options?.scroll !== false;
+    replacedAddress  = href;
+    history.replaceState(null, '', href);
+  },
+  back() {
+    history.back();
+  },
+  forward() {
+    history.forward();
+  },
+  refresh() {},
+  prefetch() {},
+};
+
+/** Whether the page shown next opens at the top; reading it clears it. */
+export function takeAppPageScroll() {
+  const scroll     = scrollOnNextPage;
+  scrollOnNextPage = false;
+  return scroll;
+}
+
+/**
+ * Whether the page replaced its own address with the current one; reading it
+ * clears it, so Back after a replace to the same address is not taken for one.
+ */
+export function takeAppPageReplace() {
+  const replaced  = replacedAddress ? new URL(replacedAddress, location.href) : null;
+  replacedAddress = '';
+  return replaced?.pathname === location.pathname && replaced.search === location.search;
+}
+
+/** The storefront router: Next.js's on the website, the History API in the app. */
+export function useStorefrontRouter() {
+  const router = useRouter();
+  return APP_ORIGIN ? appRouter : router;
+}
+
+/** Opens a storefront address in the app without reloading it. */
+export function openAppAddress(href: string) {
+  appRouter.push(href);
+}
+
+function plainClick(event: MouseEvent<HTMLAnchorElement>) {
+  return (
+    event.button === 0 &&
+    !event.metaKey &&
+    !event.ctrlKey &&
+    !event.shiftKey &&
+    !event.altKey
+  );
+}
+
+/** next/link on the website; in the app a link that the app opens itself. */
+export function StorefrontLink(props: ComponentProps<typeof NextLink>) {
+  if (!APP_ORIGIN) {
+    return <NextLink {...props} />;
+  }
+  const { href, onClick, prefetch: _prefetch, replace, scroll, ...anchor } = props;
+  const address                                                        = hrefText(href);
+  return (
+    <a
+      {...anchor}
+      href={address}
+      onClick={(event) => {
+        onClick?.(event);
+        if (event.defaultPrevented || !plainClick(event) || anchor.target) {
+          return;
+        }
+        event.preventDefault();
+        (replace ? appRouter.replace : appRouter.push)(address, { scroll });
+      }}
+    />
+  );
+}

package/templates/lib/orionplace/notice.ts

@@ -0,0 +1,22 @@
+/**
+ * Brings a notice that just appeared into view. A cart action started far
+ * down the page (an option, a delivery) answers with its error at the top of
+ * the cart, out of sight, so the customer saw nothing happen (option refusal
+ * «The package is too large», 2026-10-15). Instant with reduced motion.
+ */
+export function revealNotice(element: Element | null | undefined) {
+  if (!element || typeof window === 'undefined') {
+    return;
+  }
+
+  const bounds = element.getBoundingClientRect();
+  if (bounds.top >= 0 && bounds.bottom <= window.innerHeight) {
+    return;
+  }
+
+  const reduce = window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+  element.scrollIntoView({
+    block: 'center',
+    behavior: reduce ? 'auto' : 'smooth',
+  });
+}