@osimart/create-storefront 0.0.0-stage → 1.0.0

package/app/composables/UseThemeGroup.js

@@ -0,0 +1,575 @@
+/**
+ * Read a group of theme settings with defaults applied.
+ *
+ * `theme.settings` is a flat key/value map — the `group` attribute in
+ * THEME_SETTINGS_SCHEMA is a dashboard UI concern only, it doesn't nest the
+ * stored JSON. So `useThemeGroup('HEADER')` filters by prefix and layers the
+ * defaults below underneath.
+ *
+ * Defaults live here rather than being read from the schema because the
+ * storefront never receives the schema — bootstrap sends resolved values only.
+ * A merchant on an older theme version is missing keys the storefront already
+ * uses, and every one of those has to render as something.
+ *
+ * Keep these in sync with builder/schemas.py's THEME_SETTINGS_SCHEMA. If they drift,
+ * the storefront wins for missing keys and the dashboard wins for set ones —
+ * which shows up as "the default looks different from what the editor shows".
+ */
+const DEFAULTS = {
+  // Shopify's "Logo and favicon"
+  BRAND: {
+    LOGO: null,
+    LOGO_MOBILE: null,
+    LOGO_WIDTH: 120,
+    LOGO_WIDTH_MOBILE: null,
+    FAVICON: null,
+  },
+
+  // "Search engine listing and sharing"
+  SEO: {
+    SEO_TITLE: "",
+    SEO_DESCRIPTION: "",
+    SEO_TITLE_FORMAT: "PAGE_STORE",
+    SEO_TITLE_SEPARATOR: "|",
+    SEO_SHARE_IMAGE: null,
+    SEO_NO_INDEX: false,
+  },
+
+  // "Social media" — the store-wide accounts. The footer uses its own
+  // FOOTER_SOCIAL_* slots first and falls back to these.
+  SOCIAL_MEDIA: {
+    SOCIAL_INSTAGRAM_URL: "",
+    SOCIAL_FACEBOOK_URL: "",
+    SOCIAL_TIKTOK_URL: "",
+    SOCIAL_TWITTER_URL: "",
+    SOCIAL_YOUTUBE_URL: "",
+    SOCIAL_PINTEREST_URL: "",
+    SOCIAL_LINKEDIN_URL: "",
+    SOCIAL_SNAPCHAT_URL: "",
+    SOCIAL_WHATSAPP_URL: "",
+    SOCIAL_X_HANDLE: "",
+  },
+
+  WHATSAPP: {
+    WHATSAPP_ENABLED: false,
+    WHATSAPP_NUMBER: "",
+    WHATSAPP_MESSAGE: "",
+    WHATSAPP_POSITION: "BOTTOM_RIGHT",
+    WHATSAPP_SHOW_ON: "ALL",
+    WHATSAPP_HIDE_ON_CHECKOUT: true,
+    WHATSAPP_ICON: "DEFAULT",
+    WHATSAPP_IMAGE: null,
+    WHATSAPP_SVG: "",
+    WHATSAPP_STYLE: "FILLED",
+    WHATSAPP_SHAPE: "CIRCLE",
+    WHATSAPP_SIZE: 56,
+    WHATSAPP_ICON_SIZE: 30,
+    WHATSAPP_BG: "#25D366",
+    WHATSAPP_ICON_COLOR: "#FFFFFF",
+    WHATSAPP_SHADOW: true,
+    WHATSAPP_PULSE: false,
+    WHATSAPP_LABEL: "",
+    WHATSAPP_LABEL_SHOW: "HOVER",
+    WHATSAPP_OFFSET_X: 20,
+    WHATSAPP_OFFSET_Y: 20,
+    WHATSAPP_OFFSET_Y_MOBILE: 16,
+  },
+
+  // "Animations"
+  ANIMATIONS: {
+    ANIMATION_REVEAL: false,
+    ANIMATION_HOVER: "NONE",
+  },
+
+  CUSTOM_CSS: {
+    CUSTOM_CSS: "",
+  },
+
+  ANNOUNCEMENT: {
+    ANNOUNCEMENT_COLOR_SCHEME: null,
+    ANNOUNCEMENT_AUTOPLAY: true,
+    ANNOUNCEMENT_SPEED: 5,
+    ANNOUNCEMENT_SHOW_ARROWS_MOBILE: true,
+  },
+
+  HEADER: {
+    // structure
+    HEADER_LAYOUT: "LOGO_CENTER",
+    HEADER_MENU: "main-menu",
+    HEADER_STICKY: "ON_SCROLL_UP",
+
+    // colour — scheme first, the three overrides fall through to it when unset
+    HEADER_COLOR_SCHEME: null,
+    HEADER_BACKGROUND: null,
+    HEADER_TEXT_COLOR: null,
+    HEADER_ICON_COLOR: null,
+
+    // icons
+    HEADER_ICON_SET: "LINE",
+    HEADER_ICON_SIZE: 20,
+
+    // search
+    HEADER_SHOW_SEARCH: true,
+    HEADER_SEARCH_STYLE: "ICON_OVERLAY",
+    HEADER_SEARCH_PANEL_HEIGHT: "50vh",
+
+    // cart
+    HEADER_CART_COUNT: "BADGE",
+
+    // chrome
+    HEADER_SHOW_ACCOUNT: true,
+    HEADER_SHOW_BORDER: true,
+    HEADER_TRANSPARENT_ON_INDEX: false,
+    HEADER_PADDING_Y: 12,
+
+    // nav links — desktop inline navigation only; the drawer is SIDEBAR
+    HEADER_MENU_GAP: 24,
+    HEADER_MENU_GAP_MOBILE: 4,
+    HEADER_MENU_FONT: "BODY",
+    HEADER_MENU_SIZE: 14,
+    HEADER_MENU_WEIGHT: "400",
+    HEADER_MENU_COLOR: null,
+    HEADER_MENU_HOVER_COLOR: null,
+    HEADER_MENU_LETTER_SPACING: 0,
+    HEADER_MENU_TRANSFORM: "NONE",
+    HEADER_MENU_HOVER_EFFECT: "UNDERLINE_GROW",
+    HEADER_MENU_ACTIVE_STYLE: "UNDERLINE",
+    HEADER_MENU_ACTIVE_COLOR: null,
+    HEADER_MENU_ACTIVE_BACKGROUND: null,
+    HEADER_MENU_ACTIVE_UNDERLINE_WIDTH: 2,
+    HEADER_MENU_ACTIVE_UNDERLINE_OFFSET: 6,
+
+    // mobile menu trigger — icon style/size/colour reuse HEADER_ICON_*
+    HEADER_SHOW_MENU_BUTTON: true,
+    HEADER_MENU_BUTTON_VISIBILITY: "MOBILE_ONLY",
+    HEADER_MENU_BUTTON_SIZE: 40,
+    HEADER_MENU_BUTTON_RADIUS: 0,
+    HEADER_MENU_BUTTON_BACKGROUND: null,
+    HEADER_MENU_BUTTON_HOVER_BACKGROUND: null,
+  },
+
+  // The sidebar renders HEADER_MENU. There is no SIDEBAR_MENU by design: two
+  // menus to keep in sync is one menu that silently goes stale.
+  SIDEBAR: {
+    SIDEBAR_ENABLED: true,
+    SIDEBAR_POSITION: "START",
+    SIDEBAR_WIDTH: 380,
+    SIDEBAR_WIDTH_MOBILE: 88,
+    SIDEBAR_ANIMATION: "SLIDE",
+    SIDEBAR_ANIMATION_DURATION: 500,
+    SIDEBAR_OVERLAY: true,
+    SIDEBAR_OVERLAY_COLOR: "#000000",
+    SIDEBAR_OVERLAY_OPACITY: 45,
+    SIDEBAR_CLOSE_ON_OVERLAY: true,
+    SIDEBAR_LOCK_SCROLL: true,
+    SIDEBAR_COLOR_SCHEME: null,
+    SIDEBAR_BACKGROUND: null,
+    SIDEBAR_TEXT_COLOR: null,
+    SIDEBAR_MUTED_COLOR: null,
+    SIDEBAR_LINK_COLOR: null,
+    SIDEBAR_LINK_HOVER_COLOR: null,
+    SIDEBAR_ACTIVE_COLOR: null,
+    SIDEBAR_ACTIVE_BACKGROUND: null,
+    SIDEBAR_BORDER_COLOR: null,
+    SIDEBAR_ICON_COLOR: null,
+    SIDEBAR_SHOW_BORDER: false,
+    SIDEBAR_BORDER_WIDTH: 1,
+    SIDEBAR_RADIUS: 0,
+    SIDEBAR_SHOW_DIVIDERS: false,
+    SIDEBAR_PADDING_TOP: 8,
+    SIDEBAR_PADDING_BOTTOM: 24,
+    SIDEBAR_PADDING_X: 20,
+    SIDEBAR_LINK_GAP: 2,
+    SIDEBAR_LINK_PADDING_Y: 12,
+    SIDEBAR_GROUP_GAP: 20,
+    SIDEBAR_LINK_FONT: "BODY",
+    SIDEBAR_LINK_SIZE: 16,
+    SIDEBAR_LINK_SIZE_MOBILE: 16,
+    SIDEBAR_LINK_WEIGHT: "500",
+    SIDEBAR_LINK_LINE_HEIGHT: 130,
+    SIDEBAR_LINK_LETTER_SPACING: 0,
+    SIDEBAR_LINK_TRANSFORM: "NONE",
+    SIDEBAR_SUBMENU_SIZE: 14,
+    SIDEBAR_SUBMENU_WEIGHT: "400",
+    SIDEBAR_SUBMENU_COLOR: null,
+    SIDEBAR_SUBMENU_MODE: "ACCORDION",
+    SIDEBAR_MAX_DEPTH: 3,
+    SIDEBAR_SHOW_ARROWS: true,
+    SIDEBAR_ARROW_STYLE: "CHEVRON",
+    SIDEBAR_ARROW_SIZE: 16,
+    SIDEBAR_SUBMENU_ANIMATION: "SLIDE",
+    SIDEBAR_SUBMENU_MULTIPLE_OPEN: false,
+    SIDEBAR_SUBMENU_INDENT: 16,
+    SIDEBAR_SHOW_HEADER: true,
+    SIDEBAR_HEADER_HEIGHT: 64,
+    SIDEBAR_HEADER_BORDER: true,
+    SIDEBAR_SHOW_LOGO: true,
+    SIDEBAR_LOGO_WIDTH: 100,
+    SIDEBAR_LOGO_ALIGNMENT: "LEFT",
+    SIDEBAR_SHOW_CLOSE: true,
+    SIDEBAR_CLOSE_POSITION: "END",
+    SIDEBAR_SHOW_FOOTER: true,
+    SIDEBAR_FOOTER_SHOW_ACCOUNT: true,
+    SIDEBAR_FOOTER_SHOW_SEARCH: false,
+    SIDEBAR_FOOTER_SHOW_CART: false,
+    SIDEBAR_FOOTER_SHOW_SOCIAL: true,
+    SIDEBAR_FOOTER_TEXT: null,
+  },
+
+  // Mirrors THEME_SETTINGS_SCHEMA's FOOTER group one-for-one. Every id, and
+  // every default matching the schema's — a value that differs here is a
+  // setting that looks one way in the editor and another on a store that
+  // hasn't saved it yet.
+  FOOTER: {
+    FOOTER_COLOR_SCHEME: null,
+    // Appearance overrides over the scheme (empty = the scheme's).
+    FOOTER_BACKGROUND: null,
+    FOOTER_TEXT_COLOR: null,
+    FOOTER_LINK_COLOR: null,
+    FOOTER_LINK_HOVER_COLOR: null,
+    // The bar under the footer: its own scheme / background (empty = the footer's).
+    FOOTER_BOTTOM_COLOR_SCHEME: null,
+    FOOTER_BOTTOM_BACKGROUND: null,
+    FOOTER_CONTAINER: "NORMAL",
+    FOOTER_CONTAINER_PADDING_X: 16,
+    FOOTER_SHOW_DIVIDER: true,
+    FOOTER_DIVIDER_COLOR: null,
+    FOOTER_PADDING_TOP: 64,
+    FOOTER_PADDING_BOTTOM: 32,
+
+    // logo
+    FOOTER_LOGO: null,
+    FOOTER_LOGO_POSITION: "TOP_CENTER", // HIDDEN | TOP_CENTER | INLINE_START | INLINE_END
+    FOOTER_LOGO_WIDTH: 64,
+    FOOTER_LOGO_WIDTH_MOBILE: null,
+    FOOTER_LOGO_ALIGNMENT: "CENTER",
+    FOOTER_SHOW_BRAND_DESCRIPTION: false,
+    FOOTER_BRAND_DESCRIPTION: "",
+    FOOTER_BRAND_DESCRIPTION_WIDTH: 32,
+
+    // newsletter
+    FOOTER_SHOW_NEWSLETTER: false,
+    FOOTER_NEWSLETTER_POSITION: "START", // START | END
+    FOOTER_NEWSLETTER_WIDTH: 32,
+    FOOTER_NEWSLETTER_LAYOUT: "INLINE", // INLINE | STACKED
+    FOOTER_NEWSLETTER_ALIGNMENT: "LEFT",
+    FOOTER_NEWSLETTER_HEADING: "Be a part of our world",
+    FOOTER_NEWSLETTER_TEXT: "",
+    FOOTER_NEWSLETTER_PLACEHOLDER: "Your email",
+    FOOTER_NEWSLETTER_BUTTON_LABEL: "Sign up",
+    FOOTER_NEWSLETTER_SUCCESS_MESSAGE: "Thanks for subscribing!",
+    FOOTER_NEWSLETTER_SHOW_CONSENT: true,
+    FOOTER_NEWSLETTER_CONSENT_TEXT: "",
+
+    // columns
+    FOOTER_COLUMNS_ALIGNMENT: "END", // START | END | SPREAD
+    FOOTER_COLUMNS_VERTICAL_ALIGNMENT: "TOP",
+    FOOTER_COLUMN_WIDTH_MODE: "EQUAL", // EQUAL | CUSTOM
+    FOOTER_COLUMN_GAP: 64,
+    FOOTER_COLUMN_ROW_GAP: 16,
+    FOOTER_LINK_GAP: 12,
+    FOOTER_COLUMN_TEXT_ALIGNMENT: "LEFT",
+
+    // No default: the schema's FOOTER_MENU_1 has none either, so a store with
+    // no footer menu shows no first column rather than a broken link to a
+    // "footer-menu" handle that may not exist.
+    FOOTER_MENU_1: "",
+    FOOTER_MENU_1_TITLE: "",
+    FOOTER_MENU_1_WIDTH: 33,
+    FOOTER_MENU_2: "",
+    FOOTER_MENU_2_TITLE: "",
+    FOOTER_MENU_2_WIDTH: 33,
+    FOOTER_MENU_3: "",
+    FOOTER_MENU_3_TITLE: "",
+    FOOTER_MENU_3_WIDTH: 34,
+
+    // typography — the two text_style() sets, spelled out
+    FOOTER_HEADING_SIZE: 13,
+    FOOTER_HEADING_SIZE_MOBILE: null,
+    FOOTER_HEADING_WEIGHT: "600",
+    FOOTER_HEADING_COLOR: null,
+    FOOTER_HEADING_LINE_HEIGHT: 130,
+    FOOTER_HEADING_LETTER_SPACING: 0,
+    FOOTER_HEADING_FONT: "BODY",
+    FOOTER_HEADING_TRANSFORM: "UPPERCASE",
+
+    FOOTER_LINK_SIZE: 14,
+    FOOTER_LINK_SIZE_MOBILE: null,
+    FOOTER_LINK_WEIGHT: "400",
+    FOOTER_LINK_COLOR: null,
+    FOOTER_LINK_LINE_HEIGHT: 130,
+    FOOTER_LINK_LETTER_SPACING: 0,
+    FOOTER_LINK_FONT: "BODY",
+    FOOTER_LINK_TRANSFORM: "NONE",
+
+    FOOTER_TEXT: "",
+
+    // social — the URL slots are the source the footer prefers; when every one
+    // is empty it falls back to store.social_medias
+    FOOTER_SHOW_SOCIAL: true,
+    FOOTER_SOCIAL_INSTAGRAM_URL: "",
+    FOOTER_SOCIAL_FACEBOOK_URL: "",
+    FOOTER_SOCIAL_TIKTOK_URL: "",
+    FOOTER_SOCIAL_TWITTER_URL: "",
+    FOOTER_SOCIAL_YOUTUBE_URL: "",
+    FOOTER_SOCIAL_PINTEREST_URL: "",
+    FOOTER_SOCIAL_LINKEDIN_URL: "",
+    FOOTER_SOCIAL_POSITION: "OWN_COLUMN", // OWN_COLUMN | UNDER_MENU | UNDER_NEWSLETTER | WITH_COPYRIGHT
+    FOOTER_SOCIAL_ALIGNMENT: "LEFT",
+    FOOTER_SOCIAL_LABEL: "Socials",
+    FOOTER_SOCIAL_DISPLAY: "TEXT", // TEXT | ICONS | ICON_TEXT
+    FOOTER_SOCIAL_ICON_STYLE: "PLAIN", // shape: PLAIN | CIRCLE | SQUARE
+    FOOTER_SOCIAL_ICON_BACKGROUND: "FILLED", // fill: FILLED | OUTLINE | NONE
+    FOOTER_SOCIAL_ICON_SIZE: 18,
+    FOOTER_SOCIAL_ICON_COLOR: null,
+    FOOTER_SOCIAL_GAP: 16,
+
+    // locale
+    FOOTER_SHOW_LANGUAGE_SELECTOR: false,
+    FOOTER_SHOW_COUNTRY_SELECTOR: false,
+
+    // bottom row
+    FOOTER_SHOW_PAYMENT_ICONS: false,
+    FOOTER_PAYMENT_ICON_SIZE: 20,
+    FOOTER_PAYMENT_ICON_GAP: 8,
+    FOOTER_COPYRIGHT: "",
+    FOOTER_BOTTOM_LAYOUT: "INLINE", // INLINE | THREE_ZONE
+    FOOTER_BOTTOM_ALIGNMENT: "CENTER", // START | CENTER | SPREAD
+    FOOTER_SHOW_BOTTOM_BAR_DIVIDER: true,
+    FOOTER_BOTTOM_PADDING_Y: 16,
+    FOOTER_SHOW_POWERED_BY: false,
+    FOOTER_POWERED_BY_TEXT: "",
+    FOOTER_POWERED_BY_URL: "",
+    FOOTER_SHOW_POLICY_LINKS: true,
+    FOOTER_POLICY_1_LABEL: "",
+    FOOTER_POLICY_1_URL: "",
+    FOOTER_POLICY_2_LABEL: "",
+    FOOTER_POLICY_2_URL: "",
+    FOOTER_POLICY_3_LABEL: "",
+    FOOTER_POLICY_3_URL: "",
+    FOOTER_POLICY_4_LABEL: "",
+    FOOTER_POLICY_4_URL: "",
+
+    // mobile
+    FOOTER_MOBILE_COLUMN_LAYOUT: "STACKED", // STACKED | ACCORDION
+    FOOTER_MOBILE_ACCORDION_EXPAND_FIRST: false,
+  },
+
+  // Every storefront button that isn't individually styled: cart drawer,
+  // login, checkout, account pages, and any section button left on defaults.
+  BUTTONS: {
+    BUTTON_STYLE: "SOLID", // SOLID | OUTLINE | UNDERLINE | TEXT
+    BUTTON_RADIUS: 4,
+    BUTTON_BORDER_WIDTH: 1,
+    BUTTON_SHADOW: "NONE", // NONE | SMALL | MEDIUM | LARGE (legacy: true/false)
+    BUTTON_SHADOW_COLOR: null,
+    BUTTON_PADDING_Y: 12,
+    BUTTON_PADDING_X: 28,
+    BUTTON_PADDING_Y_MOBILE: null,
+    BUTTON_PADDING_X_MOBILE: null,
+    BUTTON_FONT: "BODY",
+    BUTTON_FONT_SIZE: 14,
+    BUTTON_FONT_WEIGHT: "MEDIUM",
+    BUTTON_TRANSFORM: "NONE",
+    BUTTON_LETTER_SPACING: 0,
+    // colours — unset follows the section's colour scheme
+    BUTTON_BG_COLOR: null,
+    BUTTON_TEXT_COLOR: null,
+    BUTTON_BORDER_COLOR: null,
+    BUTTON_HOVER_EFFECT: "FADE", // FADE | DARKEN | INVERT | LIFT | NONE
+    BUTTON_HOVER_BG_COLOR: null,
+    BUTTON_HOVER_TEXT_COLOR: null,
+    BUTTON_HOVER_BORDER_COLOR: null,
+    BUTTON_HOVER_SHADOW: null,
+    SECONDARY_BUTTON_BG_COLOR: null,
+    SECONDARY_BUTTON_TEXT_COLOR: null,
+    SECONDARY_BUTTON_BORDER_COLOR: null,
+  },
+
+  // Every storefront field: same controls CONTACT_FORM has per section.
+  INPUTS: {
+    INPUT_STYLE: "OUTLINE", // OUTLINE | FILLED | UNDERLINE
+    INPUT_LABEL_STYLE: "FLOATING", // FLOATING | ABOVE | PLACEHOLDER
+    INPUT_SHOW_REQUIRED_MARK: true,
+    INPUT_RADIUS: 4,
+    INPUT_BORDER_WIDTH: 1,
+    INPUT_SHADOW: "NONE",
+    INPUT_SHADOW_COLOR: null,
+    INPUT_PADDING_Y: 10,
+    INPUT_PADDING_X: 12,
+    INPUT_PADDING_Y_MOBILE: null,
+    INPUT_PADDING_X_MOBILE: null,
+    INPUT_FONT_SIZE: 15,
+    INPUT_FONT_SIZE_MOBILE: null,
+    INPUT_GAP: 16,
+    INPUT_BG_COLOR: null,
+    INPUT_TEXT_COLOR: null,
+    INPUT_BORDER_COLOR: null,
+    INPUT_FOCUS_COLOR: null,
+    INPUT_PLACEHOLDER_COLOR: null,
+    INPUT_ERROR_COLOR: null,
+    INPUT_LABEL_SIZE: 12,
+    INPUT_LABEL_WEIGHT: "MEDIUM",
+    INPUT_LABEL_TRANSFORM: "NONE",
+    INPUT_LABEL_LETTER_SPACING: 0,
+    INPUT_LABEL_COLOR: null,
+  },
+
+  CART: {
+    CART_TYPE: "DRAWER",
+    CART_DRAWER_TITLE: "Your cart",
+    CART_DRAWER_SHOW_COUNT: true,
+    CART_DRAWER_WIDTH: 440,
+    CART_DRAWER_COLOR_SCHEME: null,
+    CART_DRAWER_BACKGROUND: null,
+    CART_DRAWER_TEXT_COLOR: null,
+    CART_DRAWER_EMPTY_TITLE: "Your cart is empty",
+    CART_DRAWER_EMPTY_TEXT: "Have a look around — we think you will find something you love.",
+    CART_DRAWER_EMPTY_BUTTON: "Continue shopping",
+    CART_DRAWER_EMPTY_URL: "/categories/all",
+    CART_DRAWER_FREE_SHIPPING: false,
+    CART_DRAWER_FREE_SHIPPING_THRESHOLD: 100,
+    CART_DRAWER_FREE_SHIPPING_MESSAGE: "You're {amount} away from free shipping",
+    CART_DRAWER_FREE_SHIPPING_SUCCESS: "You've got free shipping!",
+    CART_DRAWER_PROGRESS_COLOR: null,
+    CART_DRAWER_PROGRESS_DONE_COLOR: null,
+    CART_DRAWER_RECOMMENDATIONS: true,
+    CART_DRAWER_RECOMMENDATIONS_TITLE: "You may also like",
+    CART_DRAWER_RECOMMENDATIONS_PRODUCTS: [],
+    CART_DRAWER_RECOMMENDATIONS_LIMIT: 4,
+    CART_DRAWER_RECS_LAYOUT: "GRID",
+    CART_DRAWER_RECS_COLUMNS: 2,
+    CART_DRAWER_RECS_GAP: 12,
+    CART_DRAWER_RECS_IMAGE_RATIO: "PORTRAIT",
+    CART_DRAWER_RECS_IMAGE_SIZE: 72,
+    CART_DRAWER_RECS_IMAGE_RADIUS: 6,
+    CART_DRAWER_RECS_CARD_STYLE: "NONE",
+    CART_DRAWER_RECS_LINE_COLOR: null,
+    CART_DRAWER_RECS_CARD_RADIUS: 8,
+    CART_DRAWER_RECS_CARD_PADDING_X: 0,
+    CART_DRAWER_RECS_CARD_PADDING_Y: 0,
+    // Buttons: empty = the theme's (Theme settings → Buttons).
+    CART_DRAWER_CHECKOUT_STYLE: "THEME",
+    CART_DRAWER_EMPTY_BTN_STYLE: "THEME",
+    CART_DRAWER_RECS_ADD_STYLE: "THEME",
+    CART_DRAWER_QTY_SIZE: 30,
+    CART_DRAWER_RECS_CARD_BACKGROUND: null,
+    CART_DRAWER_RECS_PRICE_POSITION: "BELOW",
+    CART_DRAWER_RECS_NAME_LINES: 2,
+    CART_DRAWER_RECS_NAME_SIZE: 13,
+    CART_DRAWER_RECS_PRICE_SIZE: 13,
+    CART_DRAWER_RECS_PRICE_COLOR: null,
+    CART_DRAWER_RECS_SHOW_ADD: false,
+    CART_DRAWER_RECS_ADD_LABEL: "Add",
+    CART_DRAWER_SUBTOTAL_NOTE: "Taxes and shipping calculated at checkout.",
+    CART_DRAWER_CHECKOUT_LABEL: "Checkout",
+    CART_DRAWER_SHOW_CONTINUE: true,
+  },
+
+  // Set once for the store. Sections may override individual keys, but the
+  // default is that every card in the store looks the same.
+  PRODUCT_CARD: {
+    // structure — these three are the ones that also produce a class
+    CARD_TEXT_POSITION: "BELOW", // BELOW | OVERLAY_BOTTOM | OVERLAY_HOVER
+    CARD_CTA_STYLE: "HOVER_OVER_IMAGE", // HOVER_OVER_IMAGE | UNDER_CONTENT | NONE
+    CARD_WISHLIST_POSITION: "TOP_END", // TOP_END | TOP_START | WITH_TITLE | NONE
+
+    // image
+    CARD_IMAGE_RATIO: "PORTRAIT", // PORTRAIT | SQUARE | LANDSCAPE | NATURAL
+    CARD_IMAGE_FIT: "COVER", // COVER | CONTAIN
+    CARD_SHOW_SECOND_IMAGE_ON_HOVER: true,
+
+    // text
+    CARD_TEXT_ALIGN: "START", // START | CENTER | END
+    CARD_NAME_SIZE: 14,
+    CARD_PRICE_SIZE: 14,
+    CARD_CONTENT_GAP: 4,
+    CARD_CONTENT_PADDING: 12,
+
+    // chrome
+    CARD_BADGE_POSITION: "TOP_START", // TOP_START | TOP_END | BOTTOM_START
+    CARD_BORDER_RADIUS: 0,
+    CARD_BACKGROUND: null,
+    CARD_TEXT_COLOR: null,
+    CARD_OVERLAY_SCRIM: "linear-gradient(transparent, rgba(0,0,0,0.55))",
+    CARD_CTA_FULL_WIDTH: true,
+
+    // behaviour
+    CARD_SHOW_QUICK_SHOP: true,
+    CARD_SHOW_SWATCHES: true,
+
+    // escape hatch — scoped to the card and sanitised, see scopeCardCss()
+    CARD_CUSTOM_CSS: "",
+  },
+};
+
+/**
+ * Which stored keys belong to which group.
+ *
+ * Needed because the group name isn't always the key prefix: BRAND's keys are
+ * LOGO / FAVICON, CART's are CART_TYPE / SHOW_VENDOR, and PRODUCT_CARD's are
+ * CARD_*. Prefixes are matched with startsWith, so SIDEBAR_LOGO_WIDTH does not
+ * fall into BRAND — it doesn't start with "LOGO".
+ */
+const GROUP_KEYS = {
+  BRAND: ["LOGO", "FAVICON"],
+  SEO: ["SEO_"],
+  SOCIAL_MEDIA: ["SOCIAL_"],
+  WHATSAPP: ["WHATSAPP_"],
+  ANIMATIONS: ["ANIMATION_"],
+  CUSTOM_CSS: ["CUSTOM_CSS"],
+  ANNOUNCEMENT: ["ANNOUNCEMENT_"],
+  HEADER: ["HEADER_"],
+  SIDEBAR: ["SIDEBAR_"],
+  FOOTER: ["FOOTER_"],
+  BUTTONS: ["BUTTON_", "SECONDARY_BUTTON_"],
+  INPUTS: ["INPUT_"],
+  CART: ["CART_", "SHOW_VENDOR"],
+  PRODUCT_CARD: ["CARD_"],
+};
+
+/**
+ * @param {string} group  BRAND | ANNOUNCEMENT | HEADER | SIDEBAR | FOOTER | BUTTONS | INPUTS | CART | PRODUCT_CARD
+ * @returns {ComputedRef<object>} settings for that group, defaults filled in
+ */
+export function useThemeGroup(group) {
+  const { theme } = useStorefront();
+  const fallback = DEFAULTS[group] ?? {};
+  const prefixes = GROUP_KEYS[group] ?? [];
+
+  return computed(() => {
+    const settings = theme.value ?? {};
+    const resolved = { ...fallback };
+
+    // Iterate the PAYLOAD, not the fallback.
+    //
+    // The reverse — for (key of Object.keys(fallback)) — turns DEFAULTS into an
+    // allow-list: any setting the backend sends that hasn't also been added
+    // here is silently dropped, so a new schema field renders as its hardcoded
+    // fallback and editing it in the builder appears to do nothing. DEFAULTS is
+    // meant to fill gaps in old themes, not to gate new ones.
+    for (const [key, value] of Object.entries(settings)) {
+      const belongs = key in fallback || prefixes.some((p) => key.startsWith(p));
+      if (!belongs) continue;
+      // An unset setting arrives as undefined or null; false and 0 are real
+      // values a merchant chose and must survive.
+      if (value !== undefined && value !== null) resolved[key] = value;
+    }
+
+    if (import.meta.dev) {
+      for (const key of Object.keys(settings)) {
+        if (!prefixes.some((p) => key.startsWith(p))) continue;
+        if (key in fallback) continue;
+        console.warn(
+          `[theme] ${key} has no entry in THEME_GROUP_DEFAULTS.${group}. It ` +
+            `still renders, but a store that hasn't saved it gets undefined ` +
+            `instead of the schema default.`
+        );
+      }
+    }
+
+    return resolved;
+  });
+}
+
+export { DEFAULTS as THEME_GROUP_DEFAULTS };

package/app/composables/useAddToCart.js

@@ -0,0 +1,87 @@
+import CartServices from "#osi/services/CartServices";
+import { useToast } from "vue-toastification";
+import { useCart } from "./useCart";
+import { useSidebar } from "./useSidebar";
+
+export function useAddToCart() {
+  const router = useRouter();
+  const { fetchCart } = useCart();
+  const { toggleCartSidebar } = useSidebar();
+  const { cartType } = useStorefront();
+
+  function openCartUi() {
+    if (cartType.value === "PAGE") {
+      router.push("/cart");
+    } else {
+      toggleCartSidebar(true);
+    }
+  }
+
+  /** A real price somewhere: the range ("25 - 27") or the single variant's. */
+  function isPriced(product) {
+    const parts = String(product?.discounted_price_range ?? product?.price_range ?? "")
+      .split("-")
+      .map((v) => parseFloat(v))
+      .filter((n) => Number.isFinite(n) && n > 0);
+    if (parts.length) return true;
+    return (product?.product_variants ?? []).some((v) => Number(v.price) > 0);
+  }
+
+  async function handleAddToCart(product) {
+    if (!product) return;
+    // No price: not for sale yet — never added (the button says so too).
+    if (!isPriced(product)) return;
+
+    // If product is already added (from Quick Shop), just open UI
+    if (product.added) {
+      openCartUi();
+      return;
+    }
+
+    // If product has multiple variants, redirect to detail page
+    if (Array.isArray(product.product_variants) && product.product_variants.length > 1) {
+      const categorySlug = product.categories?.[0]?.category?.slugified_name || 'products';
+      router.push(`/${categorySlug}/${product.slugified_name}/`);
+      return;
+    }
+
+    try {
+      const variantId = product.product_variants?.[0]?.id;
+      const quantityStep = product.quantity_step || 1;
+
+      if (!variantId) {
+        throw new Error("No variant available for this product.");
+      }
+
+      const response = await CartServices.EditCart(variantId, quantityStep, "add", {
+        product,
+        variant: product.product_variants?.[0],
+      });
+      if (response) {
+        await fetchCart();
+        openCartUi();
+      }
+    } catch (error) {
+      console.error("[useAddToCart] Error adding to cart:", error);
+      try {
+        const toast = useToast();
+        const data = error?.data;
+
+        if (Array.isArray(data) && data.length > 0) {
+          toast.error(data.length === 1 ? data[0] : data.map(e => `• ${e}`).join('\n'));
+        } else if (data && typeof data === 'object') {
+          const messages = Object.values(data).flat();
+          toast.error(messages.length === 1 ? messages[0] : messages.map(m => `• ${m}`).join('\n'));
+        } else {
+          toast.error(error?.message || 'An error occurred while adding to cart.');
+        }
+      } catch {
+        /* ignore toast context error */
+      }
+    }
+  }
+
+  return {
+    handleAddToCart,
+  };
+}

package/app/composables/useAnalytics.js

@@ -0,0 +1,15 @@
+import { analytics } from "#osi/utils/analytics";
+
+/**
+ * Analytics for components and composables.
+ *
+ *   const analytics = useAnalytics();
+ *   analytics.viewItem(product);
+ *
+ * Safe everywhere: on the server, in the page-builder preview, and in a store
+ * with no tracking IDs every method is a silent no-op, so callers never check.
+ * See utils/analytics.js for the event list and how each maps to GA4 and Meta.
+ */
+export function useAnalytics() {
+  return analytics;
+}