@occluze/tether 0.6.6 → 0.6.8

package/src/astro.js

@@ -10,91 +10,256 @@
  *   PUBLIC_SHOPIFY_DOMAIN=your-store.myshopify.com
  *   PUBLIC_SHOPIFY_STOREFRONT_TOKEN=your-public-storefront-token
  *
- * Options are Tether's config (domain and token override .env). Functions (onError, formatMoney,
- * hooks) can't be passed here: set them in window.TETHER_CONFIG in your layout, it is merged in.
- * View Transitions (<ClientRouter />) work without extra code. In dev, changes to
- * src/shop.config.js restart the dev server (other files: tether({ ..., watch: ['my/config.js'] })).
+ * Options are Tether's config (domain and token override .env). Functions (onError, formatMoney, hooks) can't be
+ * passed here: set them in window.TETHER_CONFIG in your layout, it is merged in. View Transitions (<ClientRouter />)
+ * work without extra code. In dev, changes to src/shop.config.js restart the dev server (other files:
+ * tether({ ..., watch: ['my/config.js'] })). Runs in Node, inside Astro's config step.
  */
+import { isSecretShopifyToken, STORE_ENV_NAMES } from './shopify-values.js';
 
-const ENV_KEYS = {
-  domain: ['PUBLIC_SHOPIFY_DOMAIN', 'PUBLIC_SHOPIFY_STORE_DOMAIN', 'SHOPIFY_DOMAIN'],
-  token: ['PUBLIC_SHOPIFY_STOREFRONT_TOKEN', 'PUBLIC_SHOPIFY_STOREFRONT_ACCESS_TOKEN', 'SHOPIFY_STOREFRONT_TOKEN'],
-};
+/**
+ * Astro isn't a dependency, so the parts of its integration API this file uses are described here.
+ *
+ * @typedef {{ warn: (message: string) => void }} AstroLogger
+ * @typedef {(options: { context: 'client', access: 'public', optional: boolean }) => unknown} EnvStringField
+ * @typedef {object} AstroConfigSetup The argument of Astro's `astro:config:setup` hook.
+ * @property {(stage: 'head-inline' | 'page', content: string) => void} injectScript
+ * @property {string} command `dev`, `build`, `preview` or `sync`.
+ * @property {{ root?: URL }} config
+ * @property {AstroLogger} logger
+ * @property {(path: string) => void} [addWatchFile]
+ * @property {(config: { env: { schema: Record<string, unknown> } }) => void} [updateConfig]
+ */
+
+/**
+ * @typedef {object} TetherAstroOptions Tether's serializable config, plus the integration's own options.
+ * @property {boolean} [inject] Add the Tether script to every page (default true).
+ * @property {string[] | null} [watch] Files that restart the dev server when they change.
+ */
+/** @typedef {{ domain?: unknown, token?: unknown, [option: string]: unknown }} PageConfig */
+/** @typedef {Record<string, string | undefined>} Env */
 
-/** The mode Astro runs in: --mode, else development for dev and production for build. */
+const DEFAULT_WATCH = ['src/shop.config.js', 'src/shop.config.mjs', 'src/shop.config.ts'];
+/**
+ * Astro is an optional peer dependency. A variable specifier keeps both tsc and the bundler from resolving it.
+ */
+const ASTRO_CONFIG_MODULE = 'astro/config';
+const ENV_LINE = /^\s*(?:export\s+)?([\w.-]+)\s*=\s*(.*?)\s*$/;
+/** A quoted value; a `#` comment may follow the closing quote. */
+const QUOTED_VALUE = /^(["'])(.*?)\1/;
+
+/**
+ * @param {string} command
+ * @param {readonly string[]} [argv]
+ * @returns {string} The mode Astro runs in: `--mode`, else development for dev and production for everything else.
+ */
 function modeOf(command, argv = process.argv) {
-  const i = argv.findIndex((a) => a === '--mode' || a.startsWith('--mode='));
-  if (i >= 0) return argv[i].includes('=') ? argv[i].split('=')[1] : argv[i + 1];
-  return command === 'dev' ? 'development' : 'production';
+  const defaultMode = command === 'dev' ? 'development' : 'production';
+  const index = argv.findIndex((arg) => arg === '--mode' || arg.startsWith('--mode='));
+  if (index < 0) return defaultMode;
+  const flag = argv[index] ?? '';
+  const mode = flag.includes('=') ? flag.split('=')[1] : argv[index + 1];
+  return mode ?? defaultMode;
+}
+
+/**
+ * @param {unknown} error
+ * @returns {boolean} True for Node's "no such file" error.
+ */
+const isMissingFile = (error) => error instanceof Error && Reflect.get(error, 'code') === 'ENOENT';
+
+/**
+ * @param {string} path
+ * @returns {Promise<string | null>} The file's text, `null` when it doesn't exist: every .env file is optional.
+ */
+async function readOptionalFile(path) {
+  const { readFile } = await import('node:fs/promises');
+  try {
+    return await readFile(path, 'utf8');
+  } catch (error) {
+    if (isMissingFile(error)) return null;
+    throw error;
+  }
+}
+
+/**
+ * @param {string} text A .env file.
+ * @param {Env} into Receives each variable; a later line wins.
+ */
+function parseEnvFile(text, into) {
+  for (const line of text.split(/\r?\n/)) {
+    const match = ENV_LINE.exec(line);
+    if (!match || line.trim().startsWith('#')) continue;
+    const [, name = '', raw = ''] = match;
+    const quoted = QUOTED_VALUE.exec(raw);
+    into[name] = quoted ? (quoted[2] ?? '') : raw.replace(/\s+#.*$/, '');
+  }
 }
 
-/** .env files the way Vite reads them (later files win), plus process.env on top. */
+/**
+ * @param {string} command
+ * @param {string} root The project folder.
+ * @returns {Promise<Env>} The .env files the way Vite reads them (later files win), with `process.env` on top.
+ */
 async function readEnv(command, root) {
+  const path = await import('node:path');
   const mode = modeOf(command);
-  const out = {};
-  try {
-    const { readFile } = await import('node:fs/promises');
-    const { join } = await import('node:path');
-    for (const name of ['.env', '.env.local', `.env.${mode}`, `.env.${mode}.local`]) {
-      let text;
-      try { text = await readFile(join(root, name), 'utf8'); } catch { continue; }
-      for (const line of text.split(/\r?\n/)) {
-        const m = /^\s*(?:export\s+)?([\w.-]+)\s*=\s*(.*?)\s*$/.exec(line);
-        if (!m || line.trim().startsWith('#')) continue;
-        let v = m[2];
-        const q = /^(["'])(.*?)\1/.exec(v); // "quoted" (a # comment may follow)
-        v = q ? q[2] : v.replace(/\s+#.*$/, '');
-        out[m[1]] = v;
-      }
+  /** @type {Env} */
+  const env = {};
+  for (const name of ['.env', '.env.local', `.env.${mode}`, `.env.${mode}.local`]) {
+    const text = await readOptionalFile(path.join(root, name));
+    if (text !== null) parseEnvFile(text, env);
+  }
+  return { ...env, ...process.env };
+}
+
+/**
+ * Fills the store's domain and token from .env when the options don't set them, and refuses a secret token: whatever
+ * is read here is written into every page.
+ *
+ * @param {PageConfig} config Changed in place.
+ * @param {Env} env
+ * @param {AstroLogger} logger
+ * @throws {Error} When the token is a secret Shopify token.
+ */
+function applyStoreEnv(config, env, logger) {
+  for (const key of /** @type {const} */ (['domain', 'token'])) {
+    if (config[key]) continue;
+    const name = STORE_ENV_NAMES[key].find((candidate) => env[candidate]);
+    if (!name) continue;
+    config[key] = env[name];
+    // Whatever is read here is written into every page, so a name without PUBLIC_ is a mistake waiting to happen.
+    if (!name.startsWith('PUBLIC_')) {
+      logger.warn(`${name} is written into every page as Tether's ${key}. Name it PUBLIC_${name} to say so.`);
     }
-  } catch { /* not in Node: nothing to read */ }
-  return { ...out, ...process.env };
+  }
+  if (typeof config.token === 'string' && isSecretShopifyToken(config.token)) {
+    throw new Error(
+      'The Shopify token for Tether is a secret token (shpat_/shpss_/…), which would be published in every page. Use the public Storefront API token from the Headless channel.',
+    );
+  }
+}
+
+/**
+ * The options usually come from a file the Astro config imports (src/shop.config.js): the dev server restarts when it
+ * changes, so the browser gets the new config too.
+ *
+ * @param {string} root
+ * @param {readonly string[]} files
+ * @param {(path: string) => void} addWatchFile
+ */
+async function watchConfigFiles(root, files, addWatchFile) {
+  const { existsSync } = await import('node:fs');
+  const path = await import('node:path');
+  for (const file of files) {
+    const absolute = path.resolve(root, file);
+    if (existsSync(absolute)) addWatchFile(absolute);
+  }
+}
+
+/**
+ * @param {string} specifier
+ * @returns {Promise<unknown>} The module, `null` when the package isn't installed.
+ */
+async function importIfInstalled(specifier) {
+  try {
+    /** @type {unknown} */
+    const module = await import(specifier);
+    return module;
+  } catch (error) {
+    if (error instanceof Error && Reflect.get(error, 'code') === 'ERR_MODULE_NOT_FOUND') return null;
+    throw error;
+  }
+}
+
+/**
+ * Declares the store variables in `astro:env` (Astro 5+), so Astro checks them. Astro 4 has no `envField`.
+ *
+ * @param {NonNullable<AstroConfigSetup['updateConfig']>} updateConfig
+ * @param {AstroLogger} logger
+ */
+async function declareEnvSchema(updateConfig, logger) {
+  const astroConfig = await importIfInstalled(ASTRO_CONFIG_MODULE);
+  /** @type {unknown} */
+  const envField =
+    typeof astroConfig === 'object' && astroConfig !== null ? Reflect.get(astroConfig, 'envField') : null;
+  if (typeof envField !== 'object' || envField === null || typeof Reflect.get(envField, 'string') !== 'function')
+    return;
+  // Checked above: Astro's `envField.string`.
+  const fields = /** @type {{ string: EnvStringField }} */ (envField);
+  const field = () => fields.string({ context: 'client', access: 'public', optional: true });
+  try {
+    updateConfig({ env: { schema: { PUBLIC_SHOPIFY_DOMAIN: field(), PUBLIC_SHOPIFY_STOREFRONT_TOKEN: field() } } });
+  } catch (error) {
+    // Astro versions with `envField` but without a stable `env` option refuse it; the variables still work unchecked.
+    logger.warn(`.env variables not declared in astro:env: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+/**
+ * @param {PageConfig} config Changed in place: functions can't be written into a page.
+ * @param {AstroLogger} logger
+ */
+function dropFunctions(config, logger) {
+  const functions = Object.keys(config).filter((key) => typeof config[key] === 'function');
+  for (const key of functions) Reflect.deleteProperty(config, key);
+  if (functions.length) {
+    logger.warn(
+      `${functions.join(', ')}: functions can't be passed here. Set them in window.TETHER_CONFIG in your layout.`,
+    );
+  }
 }
 
+/**
+ * @param {AstroConfigSetup['injectScript']} injectScript
+ * @param {PageConfig} config
+ */
+function injectTether(injectScript, config) {
+  // Before any module runs: window.TETHER_CONFIG in the layout doesn't auto-start a second init.
+  injectScript('head-inline', 'window.TETHER_INTEGRATION="astro";');
+  injectScript(
+    'page',
+    [
+      "import Tether from '@occluze/tether';",
+      // As the base config (like window.TETHER_CONFIG), not as overrides: a visitor's saved market (country, money
+      // format) then wins over the defaults, as on a plain script-tag site.
+      `window.TETHER_CONFIG = { ...${JSON.stringify({ autoMount: false, ...config })}, ...(window.TETHER_CONFIG || {}) };`,
+      'Tether.init().then(() => Tether.mount(document));',
+    ].join('\n'),
+  );
+}
+
+/**
+ * @param {TetherAstroOptions & PageConfig} [options]
+ * @returns {{ name: string, hooks: { 'astro:config:setup': (setup: AstroConfigSetup) => Promise<void> } }}
+ */
 export default function tether(options = {}) {
-  const { inject = true, watch = ['src/shop.config.js', 'src/shop.config.mjs', 'src/shop.config.ts'], ...config } = options;
+  const { inject = true, watch = DEFAULT_WATCH, ...pageOptions } = options;
   return {
     name: '@occluze/tether',
     hooks: {
-      'astro:config:setup': async ({ injectScript, command, config: astroConfig, logger, addWatchFile, updateConfig }) => {
-        const root = astroConfig?.root ? decodeURIComponent(new URL(astroConfig.root).pathname) : process.cwd();
-        // The options usually come from a file the Astro config imports (src/shop.config.js):
-        // the dev server restarts when it changes, so the browser gets the new config too.
-        if (command === 'dev' && addWatchFile) {
-          const { existsSync } = await import('node:fs');
-          const { resolve } = await import('node:path');
-          [].concat(watch || []).map((f) => resolve(root, f)).filter((f) => existsSync(f)).forEach((f) => addWatchFile(f));
-        }
-        // Astro 5+: declare the store variables, so Astro checks them (astro:env).
-        if (updateConfig) {
-          try {
-            const { envField } = await import('astro/config');
-            if (envField) {
-              const field = () => envField.string({ context: 'client', access: 'public', optional: true });
-              updateConfig({ env: { schema: { PUBLIC_SHOPIFY_DOMAIN: field(), PUBLIC_SHOPIFY_STOREFRONT_TOKEN: field() } } });
-            }
-          } catch { /* Astro 4: no astro:env */ }
-        }
-        const env = await readEnv(command, root);
-        for (const [key, names] of Object.entries(ENV_KEYS)) {
-          if (!config[key]) config[key] = names.map((n) => env[n]).find(Boolean);
-        }
-        const bad = Object.entries(config).filter(([, v]) => typeof v === 'function').map(([k]) => k);
-        bad.forEach((k) => delete config[k]);
-        if (bad.length) logger.warn(`${bad.join(', ')}: functions can't be passed here. Set them in window.TETHER_CONFIG in your layout.`);
+      'astro:config:setup': async ({
+        injectScript,
+        command,
+        config: astroConfig,
+        logger,
+        addWatchFile,
+        updateConfig,
+      }) => {
+        const { fileURLToPath } = await import('node:url');
+        const root = astroConfig.root ? fileURLToPath(astroConfig.root) : process.cwd();
+        if (command === 'dev' && addWatchFile) await watchConfigFiles(root, watch ?? [], addWatchFile);
+        if (updateConfig) await declareEnvSchema(updateConfig, logger);
+        /** @type {PageConfig} */
+        const config = { ...pageOptions };
+        applyStoreEnv(config, await readEnv(command, root), logger);
+        dropFunctions(config, logger);
         if (!config.domain || !config.token) {
-          logger.warn('No Shopify store configured: set PUBLIC_SHOPIFY_DOMAIN and PUBLIC_SHOPIFY_STOREFRONT_TOKEN in .env (the public Storefront API token).');
+          logger.warn(
+            'No Shopify store configured: set PUBLIC_SHOPIFY_DOMAIN and PUBLIC_SHOPIFY_STOREFRONT_TOKEN in .env (the public Storefront API token).',
+          );
         }
-        if (!inject) return;
-        // Before any module runs: window.TETHER_CONFIG in the layout doesn't auto-start a second init.
-        injectScript('head-inline', 'window.TETHER_INTEGRATION="astro";');
-        injectScript('page', [
-          "import Tether from '@occluze/tether';",
-          // As the base config (like window.TETHER_CONFIG), not as overrides: a visitor's saved market
-          // (country, money format) then wins over the defaults, as on a plain script-tag site.
-          `window.TETHER_CONFIG = { ...${JSON.stringify({ autoMount: false, ...config })}, ...(window.TETHER_CONFIG || {}) };`,
-          'Tether.init().then(() => Tether.mount(document));',
-        ].join('\n'));
+        if (inject) injectTether(injectScript, config);
       },
     },
   };

package/src/cart/checkout.js

@@ -0,0 +1,97 @@
+/**
+ * Sending the visitor to Shopify's checkout. The URL comes from Shopify at click time, because the cart's checkout URL
+ * changes with its market and customer; a logged-in customer's account part may supply its own (`beforeCheckout`).
+ */
+import { cfg, reportError } from '../config.js';
+import { TetherError } from '../client.js';
+import { isHttpsUrl } from '../shopify-values.js';
+import { emit } from '../dom.js';
+import { fetchCheckoutUrl } from './mutations.js';
+import { customer, currentCart, savedCartId } from './store.js';
+/** @import { CheckoutTarget } from '../config.js' */
+
+/** @typedef {{ kind: 'url', url: string | null } | { kind: 'failed', error: unknown }} CheckoutUrlAnswer */
+
+/**
+ * @param {string} cartId
+ * @returns {Promise<CheckoutUrlAnswer>} Shopify's answer as a value, so the request can run alongside the account's
+ *   and its failure is read only when its URL is the one used.
+ */
+const askCheckoutUrl = (cartId) =>
+  fetchCheckoutUrl(cartId).then(
+    (url) => ({ kind: /** @type {const} */ ('url'), url }),
+    (/** @type {unknown} */ error) => ({ kind: /** @type {const} */ ('failed'), error }),
+  );
+
+/**
+ * @returns {Promise<string | null>} The logged-in customer's checkout URL. When the account can't give one, the
+ *   failure is reported and the cart's own checkout URL is used, which still checks out (without the login).
+ */
+async function accountCheckoutUrl() {
+  if (!customer.beforeCheckout) return null;
+  try {
+    return await customer.beforeCheckout();
+  } catch (error) {
+    reportError(error, 'account checkout');
+    return null;
+  }
+}
+
+/**
+ * @param {string} cartId
+ * @returns {Promise<string>}
+ * @throws {TetherError} `ERROR` without a checkout URL (the cart is empty or Shopify no longer has it).
+ */
+async function checkoutUrl(cartId) {
+  const cartAnswer = askCheckoutUrl(cartId);
+  let url = await accountCheckoutUrl();
+  if (!url) {
+    const answer = await cartAnswer;
+    if (answer.kind === 'failed') throw answer.error;
+    url = answer.url;
+  }
+  if (!url) throw new TetherError('No checkoutUrl (cart empty or expired)');
+  if (!customer.accessToken) return url;
+  return `${url}${url.includes('?') ? '&' : '?'}logged_in=true`;
+}
+
+/**
+ * A new tab's `opener` gives the checkout page a handle on this one; a browser that doesn't let a script clear it
+ * leaves the tab as it opened.
+ *
+ * @param {Window} tab
+ */
+function detachOpenerIfAllowed(tab) {
+  try {
+    tab.opener = null;
+  } catch {
+    // The browser keeps `opener` read-only: see the function's comment.
+  }
+}
+
+/**
+ * Goes to Shopify's checkout. With `_blank` the tab opens inside the click (Safari blocks `window.open` after an
+ * await) and gets its URL once there is one.
+ *
+ * @param {CheckoutTarget} target
+ * @returns {Promise<string | null>} The checkout URL, `null` with nothing to check out or after a reported failure.
+ */
+export async function checkout(target = cfg.checkoutTarget) {
+  const cartId = savedCartId();
+  const cart = currentCart();
+  if (!cartId || (cart && !cart.totalQuantity)) return null;
+  const tab = target === '_blank' ? window.open('', '_blank') : null;
+  if (tab) detachOpenerIfAllowed(tab);
+  try {
+    const url = await checkoutUrl(cartId);
+    if (!isHttpsUrl(url)) throw new TetherError('The checkout URL is not https: not opened');
+    emit('checkout', { url, cart: currentCart() });
+    if (tab && !tab.closed) tab.location.href = url;
+    else window.location.href = url;
+    return url;
+  } catch (error) {
+    tab?.close();
+    reportError(error, 'checkout failed');
+    return null;
+  }
+}

package/src/cart/drawer.js

@@ -0,0 +1,138 @@
+/**
+ * The cart drawer: every `[tether-cart-drawer]` on the page opens and closes together, as a modal dialog. Focus moves
+ * into the open cart, Tab stays inside it and focus returns on close (`cartFocus`). A page without a drawer (a cart
+ * built in React, Svelte or Vue) still has an open state, for `Tether.cart.subscribe`.
+ */
+import { cfg } from '../config.js';
+import { sel, get, qsa, emit } from '../dom.js';
+
+const FOCUSABLE =
+  'a[href],button:not([disabled]),input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex="-1"])';
+
+/** Long enough for the drawer's open transition to make its content visible: hidden elements can't take focus. */
+const FOCUS_AFTER_OPEN_MS = 60;
+
+/** The open state of a page without a drawer element. */
+let openWithoutDrawer = false;
+
+/** @type {HTMLElement | null} Where focus was before the cart opened. */
+let returnFocus = null;
+
+/**
+ * @param {Element | null} el
+ * @returns {el is HTMLElement}
+ */
+const isFocusable = (el) => el !== null && 'focus' in el;
+
+/**
+ * @param {ParentNode} drawer
+ * @returns {HTMLElement[]} The visible focusable elements inside `drawer`, in document order.
+ */
+const focusables = (drawer) =>
+  qsa(drawer, FOCUSABLE).filter((el) => el.offsetParent !== null || el === document.activeElement);
+
+/** @returns {HTMLElement[]} Every cart drawer on the page. */
+export const drawers = () => qsa(document, sel('cart-drawer'));
+
+/** @param {HTMLElement} drawer */
+const isOpenDrawer = (drawer) => drawer.classList.contains(cfg.cartDrawerOpenClass);
+
+/** @returns {boolean} True while a drawer, or the drawer-less cart, is open. */
+export function isOpen() {
+  const all = drawers();
+  return all.length ? all.some(isOpenDrawer) : openWithoutDrawer;
+}
+
+/**
+ * `aria-expanded` on the open buttons, and dialog semantics on the drawers unless their markup has its own. A closed
+ * drawer is hidden from screen readers and, with `cartFocus`, out of the Tab order (inert), like a closed dialog.
+ *
+ * @param {boolean} open
+ */
+export function syncDrawerAria(open) {
+  qsa(document, sel('cart-open')).forEach((button) => {
+    button.setAttribute('aria-expanded', String(open));
+  });
+  drawers().forEach((drawer) => {
+    if (!drawer.hasAttribute('role')) drawer.setAttribute('role', 'dialog');
+    if (!drawer.hasAttribute('aria-label') && !drawer.hasAttribute('aria-labelledby')) {
+      drawer.setAttribute('aria-label', get(drawer, 'cart-label') || 'Cart');
+    }
+    drawer.setAttribute('aria-modal', String(open));
+    if (isOpenDrawer(drawer)) return;
+    drawer.setAttribute('aria-hidden', 'true');
+    if (cfg.cartFocus) drawer.inert = true;
+  });
+}
+
+/** @param {HTMLElement} drawer */
+function focusInto(drawer) {
+  const target = focusables(drawer)[0] ?? drawer;
+  if (target === drawer && !drawer.hasAttribute('tabindex')) drawer.tabIndex = -1;
+  target.focus({ preventScroll: true });
+}
+
+/** Opens every drawer except `tether-cart-drawer="manual"` ones, which the site opens itself. */
+export function openCart() {
+  if (isOpen()) return;
+  openWithoutDrawer = true;
+  const opened = drawers().filter((drawer) => get(drawer, 'cart-drawer') !== 'manual');
+  opened.forEach((drawer) => {
+    drawer.inert = false;
+    drawer.classList.add(cfg.cartDrawerOpenClass);
+    drawer.setAttribute('aria-hidden', 'false');
+  });
+  syncDrawerAria(true);
+  const [first] = opened;
+  if (cfg.cartFocus && first) {
+    returnFocus = isFocusable(document.activeElement) ? document.activeElement : null;
+    setTimeout(() => {
+      focusInto(first);
+    }, FOCUS_AFTER_OPEN_MS);
+  }
+  cfg.onCartOpen?.(opened);
+  emit('cart-toggled', { open: true });
+}
+
+export function closeCart() {
+  if (!isOpen()) return;
+  openWithoutDrawer = false;
+  const all = drawers();
+  const hadFocus = all.some((drawer) => drawer.contains(document.activeElement));
+  all.forEach((drawer) => {
+    drawer.classList.remove(cfg.cartDrawerOpenClass);
+    drawer.setAttribute('aria-hidden', 'true');
+    if (cfg.cartFocus) drawer.inert = true;
+  });
+  syncDrawerAria(false);
+  if (hadFocus && returnFocus?.isConnected) returnFocus.focus({ preventScroll: true });
+  returnFocus = null;
+  cfg.onCartClose?.(all);
+  emit('cart-toggled', { open: false });
+}
+
+export function toggleCart() {
+  if (isOpen()) closeCart();
+  else openCart();
+}
+
+/**
+ * Keeps Tab inside the open drawer (`cartFocus`): from the last focusable element it wraps to the first, with Shift
+ * from the first to the last, and from outside the drawer it goes in. For a document `keydown` listener.
+ *
+ * @param {KeyboardEvent} event
+ */
+export function trapFocus(event) {
+  if (event.key !== 'Tab' || !cfg.cartFocus || !isOpen()) return;
+  const drawer = drawers().find(isOpenDrawer);
+  if (!drawer) return;
+  const inside = focusables(drawer);
+  const first = inside[0];
+  const last = inside.at(-1);
+  if (!first || !last) return;
+  const active = document.activeElement;
+  const leaving = event.shiftKey ? active === first : active === last;
+  if (drawer.contains(active) && !leaving) return;
+  event.preventDefault();
+  (event.shiftKey ? last : first).focus();
+}