@numueg/theme-cli 0.4.1 → 0.6.0

package/templates/scaffold/src/dev-entry.tsx

@@ -0,0 +1,244 @@
+/**
+ * Local dev harness for `numu-theme dev` (plain Vite + index.html).
+ *
+ * The marketplace bundle's real entry is `main.tsx` (mount/createApp). Here we
+ * call that same `mount(el, ctx)` with a mock Arabic store, catalog and cart so
+ * the full provider tree (cart, shop, page, localization, direction) is live —
+ * every section renders exactly as it will inside the storefront, including the
+ * live "Add to cart" → drawer flow. This file is NOT part of the built theme.js.
+ *
+ * `themeSettings` is sent with EMPTY templates/section_groups on purpose so the
+ * bundle exercises its own theme.json presets (the marketplace-preview path).
+ */
+import { mount } from "./main";
+import type { Product, Store, Cart, Collection } from "@numueg/theme-sdk";
+
+const img = (seed: string) => ({
+  id: seed,
+  url: `https://picsum.photos/seed/${seed}/1000/1000`,
+  alt: seed,
+  position: 0,
+});
+
+const products: Product[] = [
+  {
+    id: "p1",
+    name: "تيشيرت قطن ثقيل",
+    slug: "heavy-tee",
+    description: "تيشيرت قطن 280 جرام، قصة واسعة ولمسة ناعمة.",
+    price: 450,
+    compare_at_price: 600,
+    currency: "EGP",
+    images: [img("tee"), img("tee2")],
+    category: "ملابس",
+    tags: ["جديد"],
+    options: [{ name: "المقاس", position: 0, values: ["S", "M", "L", "XL"] }],
+    variants: [
+      { id: "p1-s", position: 0, option_values: { المقاس: "S" }, price: 450, inventory_quantity: 5, is_in_stock: true },
+      { id: "p1-m", position: 1, option_values: { المقاس: "M" }, price: 450, inventory_quantity: 5, is_in_stock: true },
+      { id: "p1-l", position: 2, option_values: { المقاس: "L" }, price: 450, inventory_quantity: 0, is_in_stock: false },
+      { id: "p1-xl", position: 3, option_values: { المقاس: "XL" }, price: 450, inventory_quantity: 3, is_in_stock: true },
+    ],
+    in_stock: true,
+    attributes: {
+      size_chart: {
+        mode: "custom",
+        unit: "cm",
+        column_headers: ["الصدر", "الطول", "الكتف"],
+        rows: [
+          { size: "S", values: ["96", "70", "42"] },
+          { size: "M", values: ["102", "72", "44"] },
+          { size: "L", values: ["108", "74", "46"] },
+          { size: "XL", values: ["114", "76", "48"] },
+        ],
+        notes: "القياسات بالسنتيمتر، بهامش ±1 سم.",
+      },
+    },
+  } as Product,
+  {
+    id: "p2",
+    name: "حقيبة جلد طبيعي",
+    slug: "leather-bag",
+    description: "حقيبة جلد طبيعي بخامة فاخرة تدوم لسنوات.",
+    price: 1250,
+    currency: "EGP",
+    images: [img("bag")],
+    category: "إكسسوارات",
+    options: [],
+    variants: [
+      { id: "p2-o", position: 0, option_values: {}, price: 1250, inventory_quantity: 8, is_in_stock: true },
+    ],
+    in_stock: true,
+  },
+  {
+    id: "p3",
+    name: "حذاء رياضي أبيض",
+    slug: "white-sneakers",
+    description: "حذاء رياضي كلاسيكي بتصميم نظيف يناسب كل الإطلالات.",
+    price: 980,
+    compare_at_price: 1200,
+    currency: "EGP",
+    images: [img("shoe")],
+    category: "أحذية",
+    tags: ["الأكثر مبيعاً"],
+    options: [{ name: "المقاس", position: 0, values: ["40", "41", "42", "43"] }],
+    variants: [
+      { id: "p3-40", position: 0, option_values: { المقاس: "40" }, price: 980, inventory_quantity: 4, is_in_stock: true },
+      { id: "p3-41", position: 1, option_values: { المقاس: "41" }, price: 980, inventory_quantity: 4, is_in_stock: true },
+      { id: "p3-42", position: 2, option_values: { المقاس: "42" }, price: 980, inventory_quantity: 2, is_in_stock: true },
+      { id: "p3-43", position: 3, option_values: { المقاس: "43" }, price: 980, inventory_quantity: 0, is_in_stock: false },
+    ],
+    in_stock: true,
+  },
+  {
+    id: "p4",
+    name: "نظارة شمسية",
+    slug: "sunglasses",
+    description: "نظارة شمسية بإطار معدني خفيف وعدسات مستقطبة.",
+    price: 520,
+    currency: "EGP",
+    images: [img("glasses")],
+    category: "إكسسوارات",
+    options: [],
+    variants: [
+      { id: "p4-o", position: 0, option_values: {}, price: 520, inventory_quantity: 12, is_in_stock: true },
+    ],
+    in_stock: true,
+  },
+  {
+    id: "p5",
+    name: "ساعة يد كلاسيكية",
+    slug: "classic-watch",
+    description: "ساعة يد بتصميم أنيق وحزام جلد.",
+    price: 1800,
+    currency: "EGP",
+    images: [img("watch")],
+    category: "إكسسوارات",
+    options: [],
+    variants: [
+      { id: "p5-o", position: 0, option_values: {}, price: 1800, inventory_quantity: 6, is_in_stock: true },
+    ],
+    in_stock: true,
+  },
+];
+
+const collections: Collection[] = [
+  { id: "c1", name: "ملابس", slug: "clothing", product_count: 1, image_url: img("clothing").url, products },
+  { id: "c2", name: "إكسسوارات", slug: "accessories", product_count: 3, image_url: img("acc").url, products },
+  { id: "c3", name: "أحذية", slug: "shoes", product_count: 1, image_url: img("shoesc").url, products },
+  { id: "c4", name: "وصل حديثاً", slug: "new", product_count: 2, image_url: img("new").url, products },
+  { id: "c5", name: "تخفيضات", slug: "sale", product_count: 2, image_url: img("sale").url, products },
+];
+
+const store: Store = {
+  id: "dev-store",
+  name: "إمباير",
+  slug: "nt",
+  domain: "localhost",
+  currency: "EGP",
+  default_language: "ar",
+  use_nextjs_storefront: true,
+};
+
+const initialCart: Cart = {
+  id: "dev-cart",
+  items: [],
+  subtotal: 0,
+  total: 0,
+  currency: "EGP",
+};
+
+const themeSettings = {
+  schema_version: 3,
+  theme_id: "__THEME_ID__",
+  global_settings: {},
+  templates: {},
+  section_groups: {},
+} as any;
+
+if (typeof window !== "undefined") {
+  window.requestAnimationFrame(() => {
+    const path = window.location.pathname;
+    const params = new URLSearchParams(window.location.search);
+
+    let template = params.get("template") || "home";
+    let slug: string | null = params.get("slug");
+    if (path.startsWith("/products/")) {
+      template = "product";
+      slug = decodeURIComponent(
+        path.slice("/products/".length).replace(/\/$/, ""),
+      );
+    } else if (path === "/products") {
+      template = "products";
+    } else if (path.startsWith("/collections/")) {
+      template = "collection";
+    } else if (path.startsWith("/cart")) {
+      template = "cart";
+    } else if (path.startsWith("/order")) {
+      template = "order-confirmation";
+    }
+
+    const activeProduct = products.find((p) => p.slug === slug) ?? products[0];
+
+    const pageByTemplate: Record<string, any> = {
+      home: { type: "home", title: "الرئيسية", data: { products, collections } },
+      product: {
+        type: "product",
+        title: activeProduct.name,
+        handle: activeProduct.slug,
+        data: { product: activeProduct, products },
+      },
+      products: {
+        type: "products",
+        title: "كل المنتجات",
+        data: { products, collections },
+      },
+      collection: {
+        type: "collection",
+        title: "المجموعة",
+        data: { collection: collections[0], products },
+      },
+      cart: { type: "cart", title: "السلة", data: {} },
+      "order-confirmation": {
+        type: "order-confirmation",
+        title: "تأكيد الطلب",
+        data: {},
+      },
+    };
+
+    // Dev-only template switcher, mounted OUTSIDE the theme root.
+    const bar = document.createElement("div");
+    bar.style.cssText =
+      "position:fixed;bottom:12px;left:50%;transform:translateX(-50%);z-index:9999;display:flex;gap:4px;padding:6px;background:#000;border-radius:999px;font:500 12px sans-serif;box-shadow:0 8px 24px rgba(0,0,0,.3)";
+    const navItems: Array<[string, string, string]> = [
+      ["الرئيسية", "/", "home"],
+      ["منتج", `/products/${products[0].slug}`, "product"],
+      ["المنتجات", "/products", "products"],
+      ["مجموعة", "/collections/clothing", "collection"],
+      ["السلة", "/cart", "cart"],
+    ];
+    for (const [label, href, tpl] of navItems) {
+      const a = document.createElement("a");
+      a.href = href;
+      a.textContent = label;
+      const active = tpl === template;
+      a.style.cssText = `padding:5px 12px;border-radius:999px;text-decoration:none;color:${active ? "#000" : "#e7e2d8"};background:${active ? "#e7e2d8" : "transparent"}`;
+      bar.appendChild(a);
+    }
+    document.body.appendChild(bar);
+
+    const root = document.getElementById("root");
+    if (root) {
+      mount(root, {
+        store,
+        themeSettings,
+        currentTemplate: template,
+        initialCart,
+        initialProducts: products,
+        initialCollections: collections,
+        locale: "ar",
+        page: pageByTemplate[template] ?? pageByTemplate.home,
+      } as any);
+    }
+  });
+}

package/templates/scaffold/src/lib/CouponForm.tsx

@@ -0,0 +1,90 @@
+import { useState } from "react";
+import { useCart } from "@numueg/theme-sdk";
+
+/**
+ * Coupon / discount-code input wired to the live cart. Applies via the SDK's
+ * `applyDiscount` (which re-fetches the cart with the dashboard-computed
+ * discount); once a code is on the cart it shows an "applied" chip with a
+ * remove action. Shared by the cart drawer and the full cart page.
+ */
+export function CouponForm({ compact = false }: { compact?: boolean }) {
+  const { cart, applyDiscount, removeDiscount, loading } = useCart();
+  const [code, setCode] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  const applied = cart?.discount_code;
+
+  async function submit(e: React.FormEvent) {
+    e.preventDefault();
+    const value = code.trim();
+    if (!value || busy || loading) return;
+    setError(null);
+    setBusy(true);
+    try {
+      await applyDiscount(value);
+      setCode("");
+    } catch {
+      setError("تعذّر تطبيق الكود. تأكد من صحته وحاول مرة أخرى.");
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function remove() {
+    if (busy || loading) return;
+    setBusy(true);
+    try {
+      await removeDiscount();
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  if (applied) {
+    return (
+      <div className={`nt-coupon nt-coupon--applied${compact ? " is-compact" : ""}`}>
+        <span className="nt-coupon__tag">
+          كود الخصم: <strong>{applied}</strong>
+        </span>
+        <button
+          type="button"
+          className="nt-coupon__remove"
+          onClick={remove}
+          disabled={busy || loading}
+        >
+          إزالة
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <form
+      className={`nt-coupon${compact ? " is-compact" : ""}`}
+      onSubmit={submit}
+    >
+      <div className="nt-coupon__row">
+        <input
+          className="nt-input"
+          type="text"
+          value={code}
+          placeholder="كود الخصم"
+          aria-label="كود الخصم"
+          onChange={(e) => {
+            setCode(e.target.value);
+            if (error) setError(null);
+          }}
+        />
+        <button
+          className="nt-btn-outline"
+          type="submit"
+          disabled={busy || loading || !code.trim()}
+        >
+          {busy ? "..." : "تطبيق"}
+        </button>
+      </div>
+      {error ? <p className="nt-coupon__err">{error}</p> : null}
+    </form>
+  );
+}

package/templates/scaffold/src/lib/EditableText.tsx

@@ -0,0 +1,178 @@
+"use client";
+
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ElementType,
+  type ReactNode,
+} from "react";
+
+/**
+ * Empire's in-place inline text editor (Canva-style), drop-in compatible with
+ * the SDK's <EditableText> API so sections keep `as` / `sectionId` /
+ * `settingId` / `value`.
+ *
+ * Why local instead of the SDK component: the host PreviewBridge only does
+ * section click-to-select; the SDK <EditableText> just posts
+ * `numu:editor:select-field` (focuses the side-panel field) — no in-place edit.
+ * This component restores the proven Empire behavior:
+ *   - Inside the customizer iframe (or `?editor=` flag) the text shows a gold
+ *     dashed frame on hover; click → contenteditable + select-all.
+ *   - Blur / Enter (single-line) posts `numu:editor:inline-edit`
+ *     {sectionId, blockId?, key, value}; the hub patches the draft and the
+ *     iframe re-renders with the persisted value. Escape cancels.
+ *   - On the public storefront (top-level window) it's inert — plain text.
+ */
+export interface EditableTextProps {
+  sectionId: string;
+  blockId?: string | null;
+  groupId?: string;
+  settingId: string;
+  value: string | undefined | null;
+  as?: ElementType;
+  /** Force multi-line (Enter inserts newline instead of committing). Defaults
+   *  to true for block tags (p/div), false for inline/heading tags. */
+  multiline?: boolean;
+  className?: string;
+  style?: CSSProperties;
+  placeholder?: ReactNode;
+  /** Accepted for SDK API parity; inline editing always edits plain text. */
+  html?: boolean;
+}
+
+function isInsideEditor(): boolean {
+  if (typeof window === "undefined") return false;
+  try {
+    if (new URLSearchParams(window.location.search).get("editor")) return true;
+  } catch {
+    /* ignore */
+  }
+  return typeof window !== "undefined" && window.parent !== window;
+}
+
+const BLOCK_TAGS = new Set(["p", "div", "blockquote", "li"]);
+
+export function EditableText({
+  sectionId,
+  blockId,
+  groupId,
+  settingId,
+  value,
+  as,
+  multiline,
+  className,
+  style,
+  placeholder,
+}: EditableTextProps) {
+  const Tag = (as ?? "span") as ElementType;
+  const ref = useRef<HTMLElement | null>(null);
+  const [editing, setEditing] = useState(false);
+  const [inEditor, setInEditor] = useState(false);
+  const isMultiline =
+    multiline ?? (typeof Tag === "string" && BLOCK_TAGS.has(Tag));
+
+  useEffect(() => {
+    setInEditor(isInsideEditor());
+  }, []);
+
+  const commit = useCallback(
+    (next: string) => {
+      setEditing(false);
+      if (ref.current) ref.current.removeAttribute("contenteditable");
+      const trimmed = isMultiline ? next : next.replace(/\s+/g, " ").trim();
+      if (trimmed === (value ?? "")) return;
+      if (typeof window === "undefined") return;
+      try {
+        window.parent.postMessage(
+          {
+            type: "numu:editor:inline-edit",
+            payload: { sectionId, blockId, groupId, key: settingId, value: trimmed },
+          },
+          "*",
+        );
+      } catch {
+        /* ignore */
+      }
+    },
+    [sectionId, blockId, groupId, settingId, value, isMultiline],
+  );
+
+  const cancel = useCallback(() => {
+    setEditing(false);
+    if (ref.current) {
+      ref.current.removeAttribute("contenteditable");
+      ref.current.textContent = value ?? "";
+    }
+  }, [value]);
+
+  const startEditing = useCallback(
+    (e: React.MouseEvent) => {
+      if (!inEditor) return;
+      e.preventDefault();
+      e.stopPropagation();
+      const el = ref.current;
+      if (!el || typeof window === "undefined" || typeof document === "undefined")
+        return;
+      el.setAttribute("contenteditable", "true");
+      el.focus();
+      const sel = window.getSelection();
+      if (sel) {
+        const range = document.createRange();
+        range.selectNodeContents(el);
+        sel.removeAllRanges();
+        sel.addRange(range);
+      }
+      setEditing(true);
+    },
+    [inEditor],
+  );
+
+  const onKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLElement>) => {
+      if (!editing) return;
+      if (e.key === "Escape") {
+        e.preventDefault();
+        cancel();
+        ref.current?.blur();
+      } else if (e.key === "Enter" && !isMultiline && !e.shiftKey) {
+        e.preventDefault();
+        commit(ref.current?.textContent ?? "");
+        ref.current?.blur();
+      }
+    },
+    [editing, isMultiline, commit, cancel],
+  );
+
+  const onBlur = useCallback(() => {
+    if (!editing) return;
+    commit(ref.current?.textContent ?? "");
+  }, [editing, commit]);
+
+  const composed = [
+    className,
+    inEditor ? "nt-inline-edit nt-inline-edit--armed" : null,
+    editing ? "nt-inline-edit--editing" : null,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  return (
+    <Tag
+      ref={ref as React.Ref<HTMLElement & HTMLDivElement>}
+      className={composed || undefined}
+      style={style}
+      data-numu-inline-section={sectionId}
+      data-numu-inline-key={settingId}
+      data-numu-inline-block={blockId || undefined}
+      onClick={inEditor ? startEditing : undefined}
+      onKeyDown={onKeyDown}
+      onBlur={onBlur}
+      suppressContentEditableWarning
+    >
+      {value || placeholder || null}
+    </Tag>
+  );
+}

package/templates/scaffold/src/lib/ProductCard.tsx

@@ -0,0 +1,99 @@
+import { useState } from "react";
+import {
+  useCart,
+  useLocalization,
+  useShop,
+  type Product,
+} from "@numueg/theme-sdk";
+import { openCart } from "./cartUI";
+
+/**
+ * Empire product card — monochrome, square media with a hover "quick add"
+ * pill, a category badge (top-start) and a discount badge (accent blue,
+ * top-end). Shared by the featured rail and the products grid so the card
+ * looks identical everywhere. Writes to the live SDK cart and pops the drawer.
+ */
+export function ProductCard({ product }: { product: Product }) {
+  const { addItem } = useCart();
+  const { formatMoney } = useLocalization();
+  const shop = useShop();
+  const [pending, setPending] = useState(false);
+
+  const image = product.images?.[0];
+  const currency = product.currency || shop?.currency;
+  // Coerce — some endpoints return price/compare_at_price as strings, which
+  // breaks numeric comparison (lexicographic) and arithmetic.
+  const priceNum = Number(product.price) || 0;
+  const compareNum = Number(product.compare_at_price) || 0;
+  const price = formatMoney(priceNum, currency);
+  const hasCompare = compareNum > priceNum;
+  const compareAt = hasCompare ? formatMoney(compareNum, currency) : null;
+  const discountPct = hasCompare
+    ? Math.round((1 - priceNum / compareNum) * 100)
+    : 0;
+  const categoryBadge = product.tags?.[0] || product.category;
+  const variantId = product.variants?.[0]?.id;
+  const href = `/products/${product.slug}`;
+
+  async function handleAdd(e: React.MouseEvent) {
+    e.preventDefault();
+    if (pending || !product.in_stock) return;
+    setPending(true);
+    try {
+      await addItem(product.id, variantId, 1);
+      openCart();
+    } finally {
+      setPending(false);
+    }
+  }
+
+  return (
+    <article className="nt-card">
+      <div className="nt-card__media">
+        <a href={href} aria-label={product.name}>
+          {image?.url ? (
+            <img
+              src={image.url}
+              alt={image.alt || product.name}
+              loading="lazy"
+              onError={(e) => {
+                (e.target as HTMLImageElement).style.display = "none";
+              }}
+            />
+          ) : (
+            <div className="nt-card__placeholder" aria-hidden="true" />
+          )}
+        </a>
+        {categoryBadge ? (
+          <span className="nt-badge">{categoryBadge}</span>
+        ) : null}
+        {discountPct > 0 ? (
+          <span className="nt-badge nt-badge--blue">-{discountPct}%</span>
+        ) : null}
+        {product.in_stock ? (
+          <button
+            className="nt-card__add"
+            type="button"
+            disabled={pending}
+            onClick={handleAdd}
+          >
+            {pending ? "..." : "أضف للسلة"}
+          </button>
+        ) : (
+          <span className="nt-card__add" style={{ opacity: 1 }}>
+            نفذ المخزون
+          </span>
+        )}
+      </div>
+      <a href={href} className="nt-card__body">
+        <h3 className="nt-card__name">{product.name}</h3>
+        <p className="nt-card__price">
+          {price}
+          {compareAt ? (
+            <span className="nt-card__compare">{compareAt}</span>
+          ) : null}
+        </p>
+      </a>
+    </article>
+  );
+}

package/templates/scaffold/src/lib/cartUI.ts

@@ -0,0 +1,43 @@
+import { useSyncExternalStore } from "react";
+
+/**
+ * Tiny cross-section UI store for the slide-over cart drawer.
+ *
+ * Sections render as independent components inside the host's React tree, so
+ * the Header (which owns the drawer) and any product card's "Add" button can't
+ * share React state directly. They DO share this module, so a module-level
+ * external store is the clean bridge — no window globals, no context plumbing,
+ * SSR-safe via a constant server snapshot.
+ */
+let open = false;
+const listeners = new Set<() => void>();
+
+function emit() {
+  for (const l of listeners) l();
+}
+
+export function openCart() {
+  if (open) return;
+  open = true;
+  emit();
+}
+
+export function closeCart() {
+  if (!open) return;
+  open = false;
+  emit();
+}
+
+function subscribe(cb: () => void) {
+  listeners.add(cb);
+  return () => listeners.delete(cb);
+}
+
+/** React hook: is the drawer open? Re-renders subscribers on toggle. */
+export function useCartOpen(): boolean {
+  return useSyncExternalStore(
+    subscribe,
+    () => open,
+    () => false, // server snapshot — drawer is always closed on first paint
+  );
+}

package/templates/scaffold/src/lib/i18n.ts

@@ -0,0 +1,17 @@
+import { useLocale } from "@numueg/theme-sdk";
+
+/**
+ * Locale-aware string picker for the theme's own chrome (nav, buttons, empty
+ * states, etc.) so the store reads correctly in both English (LTR) and Arabic
+ * (RTL). Merchant-authored content comes from settings; this only covers the
+ * fixed UI strings the theme ships.
+ *
+ *   const t = useT();
+ *   t("Add to cart", "أضف إلى السلة")
+ */
+export function useT(): (en: string, ar: string) => string {
+  const locale = useLocale();
+  const isAr =
+    typeof locale === "string" && locale.toLowerCase().startsWith("ar");
+  return (en, ar) => (isAr ? ar : en);
+}

package/templates/scaffold/src/lib/section.ts

@@ -0,0 +1,12 @@
+import type { SectionProps } from "@numueg/theme-sdk";
+
+/**
+ * `main.tsx` passes each section component its instance `id` and `type` in
+ * addition to the SDK's `SectionProps` (settings/blocks/blockOrder). The SDK
+ * type doesn't declare those, so we widen it here — the `id` is what
+ * `<EditableText sectionId=…>` / `<EditableImage>` need for inline editing.
+ */
+export interface EmpSectionProps extends SectionProps {
+  id: string;
+  type?: string;
+}