@akinon/pz-theme 2.0.37-rc.0 → 2.0.38-beta.0

package/src/blocks/store-locator-block.tsx

@@ -0,0 +1,1184 @@
+'use client';
+
+import React, {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState
+} from 'react';
+import {
+  useGetRetailStoreQuery,
+  useGetStoresQuery
+} from '@akinon/next/data/client/address';
+import { useGetRetailStoreStockMutation } from '@akinon/next/data/client/product';
+import { useLocalization } from '@akinon/next/hooks';
+import { getResponsiveValue, partAttrs } from '../utils';
+import { useOverlay } from '../hooks/use-overlay';
+import { formatDecimal } from './commerce-format';
+import {
+  pickProductField,
+  readToggle,
+  useThemeProduct
+} from './product-block-utils';
+import type {
+  ThemeProduct,
+  ThemeVariantGroup
+} from './product-block-utils';
+import { hasItemTemplate, ItemTemplateList } from './item-template';
+import { listingPlaceholderStyle } from './listing-context';
+import { BlockRendererProps } from './block-renderer-registry';
+
+interface StoreLike {
+  pk?: number | string;
+  name?: string;
+  address?: string;
+  phone_number?: string;
+  latitude?: string | number;
+  longitude?: string | number;
+  city?: { name?: string } | string | null;
+  township?: { name?: string; city?: { name?: string } | null } | null;
+}
+
+/**
+ * One row of `GET /retail_store_stock/{productPk}/?city_id=…&size=…`.
+ *
+ * Commerce answers with the store's own fields plus a stock count, and NO
+ * store pk — which is why rows are matched back onto the store list by name
+ * and by coordinates rather than by id.
+ */
+interface StoreStockRow {
+  name?: string;
+  address?: string;
+  latitude?: string | number;
+  longitude?: string | number;
+  stock?: string | number;
+}
+
+interface RetailStoreCity {
+  pk?: number | string;
+  name?: string;
+}
+
+/**
+ * 'unknown' is a first-class answer, not a fallback for 'unavailable'. The
+ * stock endpoint is scoped to ONE city and needs a product; outside that scope
+ * commerce has told us nothing, and a shopper who reads "not in stock" for a
+ * store nobody asked about is being sent away for no reason.
+ */
+type AvailabilityState = 'available' | 'unavailable' | 'unknown';
+
+const ALL_CITIES = '';
+const ALLOWED_DISPLAY_MODES = ['inline', 'trigger'];
+const ALLOWED_PANEL_PLACEMENTS = ['center', 'right'];
+const ALLOWED_DISTANCE_UNITS = ['km', 'mi'];
+
+const EARTH_RADIUS_KM = 6371;
+const MILES_PER_KM = 0.621371;
+
+const SCRIPT_SCHEME = /^(?:javascript|vbscript):/;
+
+/**
+ * The "check availability" route is typed by a merchant and ends up in an
+ * href. Browsers strip whitespace and control characters while parsing a url,
+ * so a tab wedged into "javascript:" still resolves to a live handler; the
+ * value is normalised the same way before it is judged. A rejected url is
+ * dropped rather than escaped, which leaves the label as plain text — the same
+ * place an unset url lands.
+ */
+const safeHelpHref = (value: string): string => {
+  const trimmed = String(value || '').trim();
+  if (!trimmed) return '';
+
+  const normalized = Array.from(trimmed)
+    .filter((character) => character.charCodeAt(0) > 32)
+    .join('')
+    .toLowerCase();
+
+  return SCRIPT_SCHEME.test(normalized) ? '' : trimmed;
+};
+
+/**
+ * Commerce nests the city under the township on retail stores, but some brands
+ * flatten it onto the record. Both shapes are probed so the filter is populated
+ * either way instead of silently offering a single empty option.
+ */
+const resolveCity = (store: StoreLike): string => {
+  const nested = store.township?.city?.name;
+  if (typeof nested === 'string' && nested.trim()) return nested.trim();
+
+  const flat = store.city;
+  if (typeof flat === 'string' && flat.trim()) return flat.trim();
+  if (flat && typeof flat === 'object' && typeof flat.name === 'string') {
+    return flat.name.trim();
+  }
+
+  return '';
+};
+
+/** Only a complete coordinate pair produces a usable map link. */
+const mapHref = (store: StoreLike): string => {
+  const lat = Number(store.latitude);
+  const lng = Number(store.longitude);
+
+  if (!Number.isFinite(lat) || !Number.isFinite(lng)) return '';
+  if (lat === 0 && lng === 0) return '';
+
+  return `https://www.google.com/maps/search/?api=1&query=${lat},${lng}`;
+};
+
+const clampColumns = (value: unknown, fallback: number) => {
+  const numeric = Math.round(Number(value));
+  if (!Number.isFinite(numeric)) return fallback;
+  return Math.min(4, Math.max(1, numeric));
+};
+
+/**
+ * The store list and the stock answer are two different commerce records of
+ * the same shop, typed by two different teams — "Kanyon AVM" against
+ * "Kanyon Avm.". Casing, spacing and the separators brands use are folded away
+ * so the two still meet; anything more aggressive would start merging shops.
+ */
+const normalizeStoreKey = (value: unknown, locale: string): string =>
+  String(value || '')
+    .toLocaleLowerCase(locale || undefined)
+    .replace(/[\s.,;:/\\_-]+/g, ' ')
+    .trim();
+
+/**
+ * A coordinate bucket, used only when the names disagree. Rounded to ~11m so
+ * two records of the same shop still land together; a bucket is dropped
+ * entirely when either half is missing or the pair is the null island, which
+ * is what commerce sends for a store nobody geocoded.
+ */
+const coordinateKey = (lat: unknown, lng: unknown): string => {
+  const a = Number(lat);
+  const b = Number(lng);
+
+  if (!Number.isFinite(a) || !Number.isFinite(b)) return '';
+  if (a === 0 && b === 0) return '';
+
+  return `${Math.round(a * 1e4)},${Math.round(b * 1e4)}`;
+};
+
+const toRadians = (degrees: number): number => (degrees * Math.PI) / 180;
+
+/** Great-circle distance in km, or null unless both points are complete. */
+const distanceInKm = (
+  origin: { lat: number; lng: number } | null,
+  store: StoreLike
+): number | null => {
+  if (!origin) return null;
+  if (!coordinateKey(store.latitude, store.longitude)) return null;
+
+  const lat = Number(store.latitude);
+  const lng = Number(store.longitude);
+  const deltaLat = toRadians(lat - origin.lat);
+  const deltaLng = toRadians(lng - origin.lng);
+  const a =
+    Math.sin(deltaLat / 2) ** 2 +
+    Math.cos(toRadians(origin.lat)) *
+      Math.cos(toRadians(lat)) *
+      Math.sin(deltaLng / 2) ** 2;
+
+  return EARTH_RADIUS_KM * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+};
+
+/**
+ * A stock count commerce did not send, or sent as something unparseable, is
+ * NOT a zero. Only a real number decides between available and unavailable.
+ */
+const readStockState = (row: StoreStockRow | undefined): AvailabilityState => {
+  if (!row) return 'unknown';
+
+  const numeric = Number.parseInt(String(row.stock ?? ''), 10);
+  if (!Number.isFinite(numeric)) return 'unknown';
+
+  return numeric > 0 ? 'available' : 'unavailable';
+};
+
+/**
+ * The value the stock endpoint's `size` parameter wants: the selected option of
+ * the variant group the brand names. Commerce keys that group differently per
+ * catalogue ('size', 'beden', 'shoe_size'), so the key is authorable; a product
+ * with exactly one group falls back to it, and a product with none is simply
+ * asked about without a size.
+ */
+const readSelectedVariantValue = (
+  product: ThemeProduct | null,
+  attributeKey: string
+): string => {
+  const groups = product?.variants;
+  if (!Array.isArray(groups) || groups.length === 0) return '';
+
+  const wanted = attributeKey.trim().toLowerCase();
+  const match =
+    groups.find(
+      (group: ThemeVariantGroup) =>
+        String(group?.attribute_key || '').toLowerCase() === wanted ||
+        String(group?.attribute_name || '').toLowerCase() === wanted
+    ) ?? (groups.length === 1 ? groups[0] : undefined);
+
+  if (!match) return '';
+
+  const selected = (match.options || []).find((option) => option?.is_selected);
+
+  return selected ? String(selected.value ?? '') : '';
+};
+
+/**
+ * Functional content block: the brand's store/branch list with a city filter
+ * and an optional map link per store. Store CONTENT stays commerce-driven (the
+ * retail store service); the editor owns the filter, the cap and the styling.
+ *
+ * Two opt-in modes sit on top of that list, both off by default so a published
+ * block renders exactly what it rendered before:
+ *
+ *  - `productMode` scopes the block to the ambient product and answers "is it
+ *    in stock here?" per store, from `/retail_store_stock/{pk}/`. That endpoint
+ *    is scoped to a single city and needs a product, so outside that scope the
+ *    marker says 'unknown' and can carry an authorable link instead — never a
+ *    guessed in-stock claim.
+ *  - `displayMode: 'trigger'` renders the block as a button that opens the list
+ *    in a panel over the page, which is the "Mağazada Bul" control every
+ *    audited product page puts on the buy row. Opened, it is a real dialog:
+ *    focus moves in, Tab is held inside, Escape and the close button both back
+ *    out, focus returns to the trigger and the page behind it stops scrolling.
+ *    All of that is `useOverlay`'s rather than this block's, so two panels on
+ *    one page queue instead of fighting. None of it runs in the designer, where
+ *    the panel is held open to be styled and the canvas stays the author's.
+ *
+ * Properties: showCityFilter, cityFilterLabel, allCitiesLabel, limit, sort,
+ * columns, columnsMobile, showAddress, showCity, showPhone, showMap, mapLabel,
+ * loadingLabel, emptyLabel, showEmptyState, productMode, variantAttributeKey,
+ * availableLabel, unavailableLabel, unknownLabel, availabilityHelpUrl,
+ * availabilityNotice, showDistance, distanceUnit, distanceTemplate,
+ * locationLabel, locationDeniedLabel, displayMode, triggerLabel, panelTitle,
+ * panelCloseLabel, panelPlacement.
+ * Parts: filter, filter-label, select, list, card, name, address, city, phone,
+ * map-link, empty, availability, distance, location-button, notice,
+ * notice-link, trigger, backdrop, panel, panel-title, panel-close.
+ */
+const StoreLocatorBlock = ({
+  block,
+  placeholderId,
+  sectionId,
+  selectedBlockId = null,
+  currentBreakpoint = 'desktop',
+  isDesigner = false
+}: BlockRendererProps) => {
+  const prop = (key: string, fallback: string) =>
+    String(
+      getResponsiveValue(block.properties?.[key], currentBreakpoint, fallback)
+    );
+
+  const showCityFilter = readToggle(
+    block.properties?.showCityFilter,
+    currentBreakpoint,
+    true
+  );
+  const cityFilterLabel = prop('cityFilterLabel', 'City');
+  const allCitiesLabel = prop('allCitiesLabel', 'All cities');
+  const mapLabel = prop('mapLabel', 'View on map');
+  const loadingLabel = prop('loadingLabel', 'Store locator (loading)');
+  const emptyLabel = prop('emptyLabel', 'Store locator (no stores)');
+  const showEmptyState = readToggle(
+    block.properties?.showEmptyState,
+    currentBreakpoint,
+    false
+  );
+  const showAddress = readToggle(
+    block.properties?.showAddress,
+    currentBreakpoint,
+    true
+  );
+  const showCity = readToggle(
+    block.properties?.showCity,
+    currentBreakpoint,
+    true
+  );
+  const showPhone = readToggle(
+    block.properties?.showPhone,
+    currentBreakpoint,
+    true
+  );
+  const showMap = readToggle(block.properties?.showMap, currentBreakpoint, true);
+  const sort = prop('sort', 'default');
+  const columns = clampColumns(
+    getResponsiveValue(block.properties?.columns, currentBreakpoint, 1),
+    1
+  );
+  const columnsMobile = clampColumns(
+    getResponsiveValue(block.properties?.columnsMobile, currentBreakpoint, 1),
+    1
+  );
+
+  // A `target: 'property'` slider stores a bare number, so a unit would arrive
+  // here as NaN; the fallback keeps the block populated either way.
+  const rawLimit = Number(
+    getResponsiveValue(block.properties?.limit, currentBreakpoint, 12)
+  );
+  const limit = Number.isFinite(rawLimit)
+    ? Math.min(100, Math.max(1, Math.round(rawLimit)))
+    : 12;
+
+  // Both new modes default to the block's original behaviour: `productMode`
+  // off leaves every availability hook idle, and 'inline' is the layout every
+  // published composition already has.
+  const productMode = readToggle(
+    block.properties?.productMode,
+    currentBreakpoint,
+    false
+  );
+  const variantAttributeKey = prop('variantAttributeKey', 'size');
+  const availableLabel = prop('availableLabel', 'In stock');
+  const unavailableLabel = prop('unavailableLabel', 'Not in stock');
+  const unknownLabel = prop('unknownLabel', 'Check availability');
+  const availabilityHelpUrl = prop('availabilityHelpUrl', '');
+  const availabilityNotice = prop(
+    'availabilityNotice',
+    'Pick a city to see stock for this product'
+  );
+  const showDistance = readToggle(
+    block.properties?.showDistance,
+    currentBreakpoint,
+    false
+  );
+  const distanceUnitValue = prop('distanceUnit', 'km');
+  const distanceUnit = ALLOWED_DISTANCE_UNITS.includes(distanceUnitValue)
+    ? distanceUnitValue
+    : 'km';
+  const distanceTemplate = prop('distanceTemplate', '{value} km');
+  const locationLabel = prop('locationLabel', 'Use my location');
+  const locationDeniedLabel = prop(
+    'locationDeniedLabel',
+    'Location unavailable'
+  );
+  const displayModeValue = prop('displayMode', 'inline');
+  const displayMode = ALLOWED_DISPLAY_MODES.includes(displayModeValue)
+    ? displayModeValue
+    : 'inline';
+  const triggerLabel = prop('triggerLabel', 'Find in store');
+  const panelTitle = prop('panelTitle', 'Find in store');
+  const panelCloseLabel = prop('panelCloseLabel', 'Close');
+  const panelPlacementValue = prop('panelPlacement', 'center');
+  const panelPlacement = ALLOWED_PANEL_PLACEMENTS.includes(panelPlacementValue)
+    ? panelPlacementValue
+    : 'center';
+
+  const { locale } = useLocalization();
+  const { data, isLoading } = useGetStoresQuery(undefined as never);
+  const [selectedCity, setSelectedCity] = useState(ALL_CITIES);
+
+  const product = useThemeProduct();
+  const productPk = pickProductField<number | string>(product, 'pk');
+  const variantValue = productMode
+    ? readSelectedVariantValue(product, variantAttributeKey)
+    : '';
+
+  // The one gate every availability request passes through. In the designer
+  // there is no shopper, no product and no reason to hit commerce, so the mode
+  // renders its markup with everything 'unknown' instead of fetching.
+  const canQueryStock =
+    productMode &&
+    !isDesigner &&
+    productPk !== undefined &&
+    productPk !== null &&
+    String(productPk) !== '';
+
+  // `/retail_store_stock/` is keyed by CITY PK while this block has always
+  // filtered by city NAME, so the city list is what bridges the two. It is
+  // skipped entirely unless the mode is on, keeping the request count of a
+  // plain store list exactly where it was.
+  const { data: cityData } = useGetRetailStoreQuery(undefined as never, {
+    skip: !canQueryStock
+  });
+  const [fetchStock] = useGetRetailStoreStockMutation();
+  /**
+   * The answer is kept WITH the question it answers.
+   *
+   * The hook's own `data` outlives the request that produced it, so between a
+   * city change and the next response the previous city's rows are still in
+   * hand — and a store name that exists in both cities ("Merkez") would be
+   * painted in stock on the strength of a different city's answer. Pinning the
+   * signature makes a mismatched answer unusable instead of merely unlikely.
+   */
+  const [stockAnswer, setStockAnswer] = useState<{
+    signature: string;
+    rows: StoreStockRow[];
+  } | null>(null);
+
+  const [origin, setOrigin] = useState<{ lat: number; lng: number } | null>(
+    null
+  );
+  const [locationDenied, setLocationDenied] = useState(false);
+  const [isPanelOpen, setIsPanelOpen] = useState(false);
+  const triggerRef = useRef<HTMLButtonElement | null>(null);
+
+  const stores = useMemo(
+    () =>
+      ((data as { results?: StoreLike[] } | undefined)?.results ?? []).filter(
+        (store) => Boolean(store?.name)
+      ),
+    [data]
+  );
+
+  const cities = useMemo(() => {
+    const unique = new Set<string>();
+    stores.forEach((store) => {
+      const city = resolveCity(store);
+      if (city) unique.add(city);
+    });
+
+    // Collated with the storefront locale so Turkish city names sort the way a
+    // shopper expects rather than by code point.
+    return Array.from(unique).sort((a, b) => a.localeCompare(b, locale));
+  }, [stores, locale]);
+
+  const selectedCityId = useMemo(() => {
+    if (!canQueryStock || !selectedCity) return '';
+
+    const wanted = normalizeStoreKey(selectedCity, locale);
+    const match = (
+      (cityData as { results?: RetailStoreCity[] } | undefined)?.results ?? []
+    ).find((city) => normalizeStoreKey(city?.name, locale) === wanted);
+
+    return match?.pk === undefined || match?.pk === null
+      ? ''
+      : String(match.pk);
+  }, [canQueryStock, selectedCity, cityData, locale]);
+
+  /**
+   * The exact question being asked of commerce, or '' when there is none.
+   * `/retail_store_stock/` needs a product AND a city, so the empty signature
+   * is the whole degrade path: no product on the page, no city chosen, or the
+   * designer.
+   */
+  const stockQuery = useMemo(() => {
+    if (!canQueryStock || !selectedCityId) return '';
+
+    const params = new URLSearchParams();
+    params.set('city_id', selectedCityId);
+    // Commerce rejects an empty `size`; a product without variants is asked
+    // about as a whole, exactly as the legacy find-in-store form does.
+    if (variantValue) params.set('size', variantValue);
+
+    return `${productPk}|${params.toString()}`;
+  }, [canQueryStock, selectedCityId, variantValue, productPk]);
+
+  useEffect(() => {
+    if (!stockQuery) return;
+
+    let cancelled = false;
+    const queryString = stockQuery.slice(stockQuery.indexOf('|') + 1);
+
+    fetchStock({ productPk: String(productPk), queryString })
+      .unwrap()
+      .then((rows) => {
+        if (cancelled) return;
+        setStockAnswer({
+          signature: stockQuery,
+          rows: (rows ?? []) as unknown as StoreStockRow[]
+        });
+      })
+      .catch(() => {
+        // A request that failed is not an out-of-stock answer. Recording an
+        // empty row set for this signature leaves every marker 'unknown',
+        // which is the only thing we can honestly say.
+        if (!cancelled) setStockAnswer({ signature: stockQuery, rows: [] });
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [stockQuery, productPk, fetchStock]);
+
+  const stockIndex = useMemo(() => {
+    const byName = new Map<string, StoreStockRow>();
+    const byCoordinate = new Map<string, StoreStockRow>();
+
+    if (!stockQuery || stockAnswer?.signature !== stockQuery) {
+      return { byName, byCoordinate };
+    }
+
+    stockAnswer.rows.forEach((row) => {
+      const nameKey = normalizeStoreKey(row?.name, locale);
+      if (nameKey && !byName.has(nameKey)) byName.set(nameKey, row);
+
+      const coordinate = coordinateKey(row?.latitude, row?.longitude);
+      if (coordinate && !byCoordinate.has(coordinate)) {
+        byCoordinate.set(coordinate, row);
+      }
+    });
+
+    return { byName, byCoordinate };
+  }, [stockQuery, stockAnswer, locale]);
+
+  const resolveAvailability = useCallback(
+    (store: StoreLike): AvailabilityState => {
+      // Every branch that cannot produce a commerce-backed answer lands on
+      // 'unknown': mode off, no product, no city, request in flight, request
+      // failed, or a store this city's answer never mentioned. The index is
+      // empty in all of them, so this is one rule rather than five.
+      const row =
+        stockIndex.byName.get(normalizeStoreKey(store.name, locale)) ??
+        stockIndex.byCoordinate.get(
+          coordinateKey(store.latitude, store.longitude)
+        );
+
+      return readStockState(row);
+    },
+    [stockIndex, locale]
+  );
+
+  const resolveDistance = useCallback(
+    (store: StoreLike): number | null => {
+      const km = distanceInKm(origin, store);
+      if (km === null) return null;
+
+      return distanceUnit === 'mi' ? km * MILES_PER_KM : km;
+    },
+    [origin, distanceUnit]
+  );
+
+  const requestLocation = useCallback(() => {
+    // Nothing is prompted, measured or stored inside the designer.
+    if (isDesigner) return;
+    if (typeof navigator === 'undefined' || !navigator.geolocation) {
+      setLocationDenied(true);
+      return;
+    }
+
+    navigator.geolocation.getCurrentPosition(
+      (position) => {
+        setLocationDenied(false);
+        setOrigin({
+          lat: position.coords.latitude,
+          lng: position.coords.longitude
+        });
+      },
+      () => setLocationDenied(true)
+    );
+  }, [isDesigner]);
+
+  /**
+   * The whole modal contract — the focus trap, the `aria-modal` claim, the
+   * scroll lock, Escape, and returning focus to the trigger — is the shared
+   * overlay primitive's, not this block's.
+   *
+   * It used to be three effects here, and the focus trap among them registered
+   * a DOCUMENT-level `focusin` listener that pulled focus back into THIS panel.
+   * A product page carries this block twice, once on the mobile buy row and
+   * once on the desktop one, so two open panels is the ordinary composition —
+   * and two such listeners read each other's focus as "outside" and pulled
+   * against each other until the tab died with a call-stack overflow. The
+   * primitive keeps one stack for the page: only the topmost overlay traps
+   * focus, claims `aria-modal` and answers Escape, and the scroll lock is
+   * counted across every block rather than per block.
+   *
+   * `isDesigner` keeps all of it inert: on the canvas the panel is held open to
+   * be styled, and nothing may steal focus, freeze the page or close the thing
+   * the author is working on.
+   */
+  const overlay = useOverlay<HTMLDivElement>({
+    open: displayMode === 'trigger' && isPanelOpen,
+    onClose: () => setIsPanelOpen(false),
+    isDesigner,
+    modal: true,
+    returnFocusRef: triggerRef
+  });
+
+  const visibleStores = useMemo(() => {
+    const filtered = selectedCity
+      ? stores.filter((store) => resolveCity(store) === selectedCity)
+      : stores;
+
+    // 'default' keeps whatever order commerce returned, which is what every
+    // published block shows today.
+    const ordered =
+      sort === 'default'
+        ? filtered
+        : [...filtered].sort((a, b) => {
+            if (sort === 'distance') {
+              const first = distanceInKm(origin, a);
+              const second = distanceInKm(origin, b);
+              // A store we cannot measure sinks below every store we can,
+              // rather than pretending to be the nearest.
+              if (first === null && second === null) return 0;
+              if (first === null) return 1;
+              if (second === null) return -1;
+
+              return first - second;
+            }
+
+            if (sort === 'city') {
+              return resolveCity(a).localeCompare(resolveCity(b), locale);
+            }
+
+            const compared = String(a.name || '').localeCompare(
+              String(b.name || ''),
+              locale
+            );
+
+            return sort === 'name-desc' ? -compared : compared;
+          });
+
+    return ordered.slice(0, limit);
+  }, [stores, selectedCity, limit, sort, locale, origin]);
+
+  const cards = useMemo(
+    () =>
+      visibleStores.map((store, index) => {
+        // With the mode off there is no availability to bind, and an authored
+        // row must not be handed "Check availability" for a block that never
+        // asked commerce anything.
+        const availability = productMode ? resolveAvailability(store) : '';
+        const distance = resolveDistance(store);
+
+        return {
+          id: String(store.pk ?? `store-${index}`),
+          name: String(store.name || ''),
+          address: String(store.address || ''),
+          city: resolveCity(store),
+          phone: String(store.phone_number || ''),
+          url: mapHref(store),
+          latitude: store.latitude ?? '',
+          longitude: store.longitude ?? '',
+          availability,
+          availabilityLabel:
+            availability === 'available'
+              ? availableLabel
+              : availability === 'unavailable'
+              ? unavailableLabel
+              : availability === 'unknown'
+              ? unknownLabel
+              : '',
+          distance:
+            distance === null ? '' : formatDecimal(distance, locale, 1)
+        };
+      }),
+    [
+      visibleStores,
+      productMode,
+      resolveAvailability,
+      resolveDistance,
+      availableLabel,
+      unavailableLabel,
+      unknownLabel,
+      locale
+    ]
+  );
+
+  // A designer who marked a child as the card layout gets that layout repeated
+  // per store; otherwise the built-in card renders unchanged.
+  const customCards = hasItemTemplate(block, currentBreakpoint) ? (
+    <ItemTemplateList
+      block={block}
+      items={cards}
+      placeholderId={placeholderId}
+      sectionId={sectionId}
+      isDesigner={isDesigner}
+      selectedBlockId={selectedBlockId}
+      currentBreakpoint={currentBreakpoint}
+    />
+  ) : null;
+
+  const listId = String(block.id || 'store-locator').replace(
+    /[^a-zA-Z0-9_-]/g,
+    ''
+  );
+
+  /**
+   * The trigger form wraps the SAME body the inline form renders, so the two
+   * cannot drift. In 'inline' mode the wrapper is skipped entirely and the body
+   * keeps the root `data-store-locator` attribute it has always carried.
+   */
+  const withTriggerShell = (body: React.ReactNode): React.ReactElement => {
+    if (displayMode !== 'trigger') return body as React.ReactElement;
+
+    // The designer needs the panel visible to style it; a shopper does not.
+    const open = isDesigner || isPanelOpen;
+
+    return (
+      <div
+        data-store-locator=""
+        data-store-locator-mode="trigger"
+        style={{ position: 'relative' }}
+      >
+        <button
+          type="button"
+          ref={triggerRef}
+          data-store-locator-trigger=""
+          {...partAttrs('trigger', { open })}
+          aria-haspopup="dialog"
+          aria-expanded={open ? 'true' : 'false'}
+          // The designer holds the panel open, so a click there would only
+          // desynchronise the state the author is styling against.
+          onClick={() => {
+            if (!isDesigner) setIsPanelOpen((previous) => !previous);
+          }}
+          style={{
+            display: 'inline-flex',
+            alignItems: 'center',
+            gap: '8px',
+            padding: '10px 16px',
+            border: '1px solid var(--store-locator-border, #e5e7eb)',
+            background: 'transparent',
+            color: 'inherit',
+            font: 'inherit',
+            cursor: 'pointer'
+          }}
+        >
+          {triggerLabel}
+        </button>
+
+        {open && (
+          <>
+            <div
+              data-store-locator-backdrop=""
+              {...partAttrs('backdrop')}
+              // Decoration behind the dialog: it carries no content, and the
+              // close button is the route assistive tech is offered instead.
+              aria-hidden="true"
+              // Inert in the designer: closing the panel from a stray canvas
+              // click would hide the thing being styled.
+              onClick={() => {
+                if (!isDesigner) setIsPanelOpen(false);
+              }}
+              style={{
+                position: 'fixed',
+                inset: 0,
+                background: 'var(--store-locator-backdrop, rgba(0,0,0,0.4))',
+                zIndex: 40
+              }}
+            />
+            <div
+              data-store-locator-panel=""
+              {...partAttrs('panel', { open: true })}
+              role="dialog"
+              // Carries the panel ref and `aria-modal`, and the claim is made
+              // only where it is true: never in the designer, where the panel
+              // is held open next to a canvas the author must keep reaching,
+              // and never on the lower of two open panels, which is not the
+              // one hiding the page. Spread after `role` so the attribute
+              // order the golden captured stays put.
+              {...overlay.overlayProps}
+              aria-label={panelTitle}
+              // The dialog itself is the fallback focus target while it holds
+              // focus, but it must stay out of the Tab order otherwise.
+              tabIndex={-1}
+              style={{
+                position: 'fixed',
+                zIndex: 41,
+                display: 'flex',
+                flexDirection: 'column',
+                gap: 'var(--store-locator-gap, 16px)',
+                background: 'var(--store-locator-panel-bg, #ffffff)',
+                color: 'inherit',
+                padding: '20px',
+                overflowY: 'auto',
+                ...(panelPlacement === 'right'
+                  ? {
+                      top: 0,
+                      right: 0,
+                      bottom: 0,
+                      width: 'min(420px, 100%)'
+                    }
+                  : {
+                      top: '50%',
+                      left: '50%',
+                      transform: 'translate(-50%, -50%)',
+                      width: 'min(560px, calc(100% - 32px))',
+                      maxHeight: 'calc(100% - 64px)'
+                    })
+              }}
+            >
+              <div
+                style={{
+                  display: 'flex',
+                  alignItems: 'center',
+                  justifyContent: 'space-between',
+                  gap: '12px'
+                }}
+              >
+                <span
+                  data-store-locator-panel-title=""
+                  {...partAttrs('panel-title')}
+                  style={{ fontWeight: 600 }}
+                >
+                  {panelTitle}
+                </span>
+                <button
+                  type="button"
+                  data-store-locator-panel-close=""
+                  {...partAttrs('panel-close')}
+                  onClick={() => {
+                    if (!isDesigner) setIsPanelOpen(false);
+                  }}
+                  style={{
+                    border: 'none',
+                    background: 'transparent',
+                    color: 'inherit',
+                    font: 'inherit',
+                    cursor: 'pointer',
+                    padding: '4px'
+                  }}
+                >
+                  {panelCloseLabel}
+                </button>
+              </div>
+
+              {body}
+            </div>
+          </>
+        )}
+      </div>
+    );
+  };
+
+  /** In 'trigger' mode the shell owns the root attribute, so the body drops it. */
+  const bodyRootAttrs =
+    displayMode === 'trigger' ? {} : { 'data-store-locator': '' };
+
+  // The mode is on but commerce has not been asked anything a shopper can act
+  // on — no product on the page, or no city picked. Saying so is the honest
+  // alternative to painting every store with a guess.
+  const showNotice = productMode && Boolean(availabilityNotice) && !stockQuery;
+  const helpHref = safeHelpHref(availabilityHelpUrl);
+
+  /**
+   * The same route the unknown marker carries, offered where there is no
+   * marker to carry it.
+   *
+   * Inside the overlay the list can be the whole content, and both states that
+   * leave it empty of answers — no city chosen yet, or no store matching at
+   * all — used to end with the shopper facing a wall of "unknown" or a bare
+   * "no stores" line and nowhere to go. It is the SAME authorable label and
+   * the SAME url, not a second pair of properties, so a brand words its
+   * fallback once.
+   */
+  const availabilityRoute =
+    productMode && helpHref && unknownLabel ? (
+      <a
+        data-store-locator-notice-link=""
+        {...partAttrs('notice-link')}
+        href={isDesigner ? '#' : helpHref}
+        onClick={(event) => {
+          if (isDesigner) event.preventDefault();
+        }}
+        style={{ fontSize: '0.9em', color: 'inherit', width: 'fit-content' }}
+      >
+        {unknownLabel}
+      </a>
+    ) : null;
+
+  if (visibleStores.length === 0 && !customCards) {
+    // With the availability mode off this is the empty message the block has
+    // always rendered; the route only appears for a composition that opted in.
+    const emptyContent = (
+      <>
+        {isLoading ? loadingLabel : emptyLabel}
+        {availabilityRoute}
+      </>
+    );
+
+    if (!isDesigner) {
+      // Historically the storefront rendered nothing here, so the notice is
+      // opt-in and the block stays invisible until a brand asks for it.
+      if (!showEmptyState && displayMode !== 'trigger') return null;
+
+      return withTriggerShell(
+        <div
+          {...bodyRootAttrs}
+          data-store-locator-state="empty"
+          {...partAttrs('empty')}
+        >
+          {emptyContent}
+        </div>
+      );
+    }
+
+    return withTriggerShell(
+      <div
+        {...bodyRootAttrs}
+        data-store-locator-state="empty"
+        {...partAttrs('empty')}
+        style={listingPlaceholderStyle}
+      >
+        {emptyContent}
+      </div>
+    );
+  }
+
+  // Column counts are block PROPERTIES, and properties are resolved with the
+  // designer breakpoint only — on the live storefront currentBreakpoint is
+  // always 'desktop'. A scoped rule with the same 1023px cutoff the theme CSS
+  // generator uses keeps real mobile viewports in sync with the editor. A
+  // single-column list keeps the original flex layout so nothing published
+  // against it shifts.
+  const isGrid = columns > 1 || columnsMobile > 1;
+  const baseColumns = currentBreakpoint === 'mobile' ? columnsMobile : columns;
+  // A designer-authored card is a block tree, not an <li>, so the container
+  // drops to a <div> in that case rather than nesting invalid list children.
+  const ListTag = customCards ? 'div' : 'ul';
+
+  const renderAvailability = (state: AvailabilityState) => {
+    const label =
+      state === 'available'
+        ? availableLabel
+        : state === 'unavailable'
+        ? unavailableLabel
+        : unknownLabel;
+
+    if (!label) return null;
+
+    const attrs = {
+      'data-store-locator-availability': '',
+      'data-store-locator-availability-state': state,
+      ...partAttrs('availability', {
+        available: state === 'available',
+        unavailable: state === 'unavailable',
+        unknown: state === 'unknown'
+      })
+    };
+    const style: React.CSSProperties = {
+      fontSize: '0.85em',
+      color:
+        state === 'available'
+          ? 'var(--store-locator-available-color, #15803d)'
+          : state === 'unavailable'
+          ? 'var(--store-locator-unavailable-color, #b91c1c)'
+          : 'var(--store-locator-unknown-color, #6b7280)',
+      // 'unknown' is deliberately neither of the other two: a neutral colour
+      // plus a dotted underline reads as "we have not checked", which is what
+      // it means.
+      borderBottom:
+        state === 'unknown'
+          ? '1px dotted var(--store-locator-unknown-color, #6b7280)'
+          : undefined,
+      width: 'fit-content'
+    };
+
+    // An unknown answer can carry the brand's own "check availability" route —
+    // a help page, a store-finder, a WhatsApp line. Without one it stays text,
+    // because a link to nowhere is worse than a plain label.
+    if (state === 'unknown' && helpHref) {
+      return (
+        <a
+          {...attrs}
+          href={isDesigner ? '#' : helpHref}
+          onClick={(event) => {
+            if (isDesigner) event.preventDefault();
+          }}
+          style={style}
+        >
+          {label}
+        </a>
+      );
+    }
+
+    return (
+      <span {...attrs} style={style}>
+        {label}
+      </span>
+    );
+  };
+
+  const body = (
+    <div
+      {...bodyRootAttrs}
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--store-locator-gap, 16px)'
+      }}
+    >
+      {showCityFilter && cities.length > 0 && (
+        <label
+          data-store-locator-filter=""
+          {...partAttrs('filter')}
+          style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}
+        >
+          <span {...partAttrs('filter-label')}>{cityFilterLabel}</span>
+          <select
+            value={selectedCity}
+            {...partAttrs('select')}
+            // Filtering is local state only, so it stays harmless in the
+            // designer and needs no navigation guard.
+            onChange={(event) => setSelectedCity(event.target.value)}
+            style={{
+              border: '1px solid var(--store-locator-border, #e5e7eb)',
+              background: 'transparent',
+              color: 'inherit',
+              padding: '8px 10px'
+            }}
+          >
+            <option value={ALL_CITIES}>{allCitiesLabel}</option>
+            {cities.map((city) => (
+              <option key={city} value={city}>
+                {city}
+              </option>
+            ))}
+          </select>
+        </label>
+      )}
+
+      {showDistance && (
+        <button
+          type="button"
+          data-store-locator-location=""
+          {...partAttrs('location-button', { disabled: locationDenied })}
+          onClick={requestLocation}
+          style={{
+            display: 'inline-flex',
+            alignItems: 'center',
+            gap: '8px',
+            width: 'fit-content',
+            padding: '8px 12px',
+            border: '1px solid var(--store-locator-border, #e5e7eb)',
+            background: 'transparent',
+            color: 'inherit',
+            font: 'inherit',
+            cursor: 'pointer'
+          }}
+        >
+          {locationDenied ? locationDeniedLabel : locationLabel}
+        </button>
+      )}
+
+      {showNotice && (
+        <>
+          <span
+            data-store-locator-notice=""
+            {...partAttrs('notice')}
+            style={{ fontSize: '0.9em', opacity: 0.8 }}
+          >
+            {availabilityNotice}
+          </span>
+          {availabilityRoute}
+        </>
+      )}
+
+      {isGrid && (
+        <style>
+          {`[data-store-locator-id="${listId}"]{grid-template-columns:repeat(${baseColumns},minmax(0,1fr));}` +
+            `@media (max-width:1023px){[data-store-locator-id="${listId}"]{grid-template-columns:repeat(${columnsMobile},minmax(0,1fr));}}`}
+        </style>
+      )}
+
+      <ListTag
+        {...partAttrs('list')}
+        {...(isGrid ? { 'data-store-locator-id': listId } : {})}
+        style={{
+          display: isGrid ? 'grid' : 'flex',
+          flexDirection: isGrid ? undefined : 'column',
+          gap: 'var(--store-locator-gap, 16px)',
+          listStyle: 'none',
+          margin: 0,
+          padding: 0
+        }}
+      >
+        {customCards ??
+          visibleStores.map((store, index) => {
+            const href = mapHref(store);
+            const city = resolveCity(store);
+            const distance = showDistance ? resolveDistance(store) : null;
+
+            return (
+              <li
+                key={store.pk ?? `store-${index}`}
+                data-store-locator-item=""
+                {...partAttrs('card')}
+                style={{
+                  display: 'flex',
+                  flexDirection: 'column',
+                  gap: '4px',
+                  paddingBottom: '12px',
+                  borderBottom: '1px solid var(--store-locator-border, #e5e7eb)'
+                }}
+              >
+                <span
+                  data-store-locator-name=""
+                  {...partAttrs('name')}
+                  style={{ fontWeight: 600 }}
+                >
+                  {store.name}
+                </span>
+
+                {productMode && renderAvailability(resolveAvailability(store))}
+
+                {distance !== null && (
+                  <span
+                    data-store-locator-distance=""
+                    {...partAttrs('distance')}
+                    style={{ opacity: 0.7, fontSize: '0.85em' }}
+                  >
+                    {distanceTemplate.replace(
+                      /\{value\}/g,
+                      formatDecimal(distance, locale, 1)
+                    )}
+                  </span>
+                )}
+
+                {showAddress && store.address && (
+                  <span
+                    data-store-locator-address=""
+                    {...partAttrs('address')}
+                    style={{ opacity: 0.8 }}
+                  >
+                    {store.address}
+                  </span>
+                )}
+
+                {showCity && city && (
+                  <span
+                    data-store-locator-city=""
+                    {...partAttrs('city')}
+                    style={{ opacity: 0.7 }}
+                  >
+                    {city}
+                  </span>
+                )}
+
+                {showPhone && store.phone_number && (
+                  <a
+                    data-store-locator-phone=""
+                    {...partAttrs('phone')}
+                    href={isDesigner ? '#' : `tel:${store.phone_number}`}
+                    onClick={(event) => {
+                      if (isDesigner) event.preventDefault();
+                    }}
+                    style={{ color: 'inherit' }}
+                  >
+                    {store.phone_number}
+                  </a>
+                )}
+
+                {showMap && href && (
+                  <a
+                    data-store-locator-map=""
+                    {...partAttrs('map-link')}
+                    // Google Maps is off-origin, so this is a plain anchor rather
+                    // than NextLink; it is still inert inside the designer.
+                    href={isDesigner ? '#' : href}
+                    target={isDesigner ? undefined : '_blank'}
+                    rel="noopener noreferrer"
+                    onClick={(event) => {
+                      if (isDesigner) event.preventDefault();
+                    }}
+                    style={{ color: 'inherit' }}
+                  >
+                    {mapLabel}
+                  </a>
+                )}
+              </li>
+            );
+          })}
+      </ListTag>
+    </div>
+  );
+
+  return withTriggerShell(body);
+};
+
+export default StoreLocatorBlock;