znode-plugin 0.0.0-stage → 0.1.2

package/lib/templates.mjs

@@ -0,0 +1,316 @@
+// Starter packages for `znode create <kind> <name>`: each builds, installs and runs as it is, and shows
+// every extension point of its kind once, with a comment on when to use it. Files by path, relative to the package.
+
+const titleCase = (name) => name.replace(/(^|-)([a-z0-9])/g, (_, dash, letter) => `${dash ? " " : ""}${letter.toUpperCase()}`);
+const pascalCase = (name) => name.replace(/(^|-)([a-z0-9])/g, (_, __, letter) => letter.toUpperCase());
+
+const HOST = `import type { IBrowserHost, IReact } from "../extension-api";
+
+// The store's React, bound once by setup (browser.tsx); the other modules import these bindings, which stay live.
+// Module scope is per store on the server and per page in the browser, so a cache here never mixes two stores.
+
+export let React: IReact;
+// JSX compiles to h(...) / Fragment, bound to the store's React in setup
+export let h: IReact["createElement"];
+export let Fragment: (props: { children?: unknown }) => unknown;
+export let settings: Record<string, unknown> = {};
+
+export function bindHost(host: IBrowserHost) {
+  React = host.React;
+  h = React.createElement;
+  Fragment = React.Fragment as typeof Fragment;
+  settings = host.settings;
+}
+`;
+
+const buildScript = (name) => `#!/usr/bin/env sh
+# Packs ${name} (znode-package.json) and installs it into the store's plugin directory.
+# Usage: sh build-and-upload.sh [plugin directory]
+set -eu
+cd "$(dirname "$0")"
+npx znode pack .
+npx znode install "releases/$(node -p "const m=require('./znode-package.json'); m.name + '-' + m.version").zpkg.zip" "\${1:-\${RUNTIME_PLUGINS_DIR:?set RUNTIME_PLUGINS_DIR or pass the store folder}}"
+`;
+
+const marketplace = (name, kind, permissions, extra = {}) => ({
+  name,
+  version: "1.0.0",
+  kind,
+  apiVersion: 1,
+  label: titleCase(name),
+  publisher: "Your company",
+  description: `${titleCase(name)}: describe what it does for the store in one or two sentences.`,
+  license: "proprietary",
+  keywords: [kind],
+  // what the package does beyond showing UI, for the marketplace review (znode-package.mjs check compares it with the code)
+  permissions,
+  compatibility: { webstore: ">=10.0.0" },
+  ...extra,
+});
+
+const widgetSource = (component) => `import { h } from "../lib/host.js";
+
+// ${component}: a page-builder widget. The editor (EDITOR) gives it a name, a category and its fields; a merchant drops
+// it on any page and fills them in. Props arrive as saved; keep the server's HTML and the first browser render equal
+// (no Date.now() or window during render: use an effect).
+
+type I${component}Props = { id?: string; heading?: string; text?: string; buttonText?: string; buttonUrl?: string; tone?: "light" | "dark" };
+
+export function ${component}(props: I${component}Props) {
+  const dark = props.tone === "dark";
+  return (
+    <section
+      className="${component.replace(/[A-Z]/g, (letter, index) => (index ? "-" : "") + letter.toLowerCase())}"
+      data-test-selector={\`div${component}\${props.id || ""}\`}
+      style={{ padding: "48px 24px", textAlign: "center", background: dark ? "#111" : "var(--secondary-bg, #f6f6f6)", color: dark ? "#fff" : "inherit" }}
+    >
+      {props.heading && <h2 style={{ margin: "0 0 12px", fontSize: 32 }}>{props.heading}</h2>}
+      {props.text && <p style={{ margin: "0 auto 20px", maxWidth: 640 }}>{props.text}</p>}
+      {props.buttonText && props.buttonUrl && (
+        <a className="btn btn-primary" href={props.buttonUrl} data-test-selector="link${component}">
+          {props.buttonText}
+        </a>
+      )}
+    </section>
+  );
+}
+
+export const EDITOR = {
+  label: "${titleCase(component.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase())}",
+  category: "Content",
+  fields: {
+    heading: { type: "text", label: "Heading" },
+    text: { type: "textarea", label: "Text" },
+    buttonText: { type: "text", label: "Button text" },
+    buttonUrl: { type: "text", label: "Button link" },
+    tone: { type: "radio", label: "Tone", options: [{ value: "light", label: "Light" }, { value: "dark", label: "Dark" }] },
+  },
+  defaultProps: { heading: "Made for your business", text: "Tell buyers what makes this store worth their time.", buttonText: "Shop now", buttonUrl: "/", tone: "light" },
+};
+`;
+
+function theme(name) {
+  const widget = `${pascalCase(name)}Hero`;
+  return {
+    "znode-package.json": marketplace(name, "theme", [], {
+      build: { browser: "src/browser.tsx" },
+      styles: ["src/styles/*.css"],
+      messages: "src/i18n/labels.json",
+      widgets: [widget],
+      settingsSchema: {
+        announcement: { type: "string", label: "Announcement bar text (empty: no bar)", browser: true, default: "", attribute: "ThemeAnnouncement" },
+        accentColor: { type: "string", label: "Accent color (CSS)", browser: true, default: "#c4122f", attribute: "ThemeAccentColor" },
+        showBadges: { type: "boolean", label: "Show the New badge on product cards", browser: true, default: true },
+      },
+    }),
+    "build-and-upload.sh": buildScript(name),
+    "src/lib/host.ts": HOST,
+    "src/browser.tsx": `import type { IBrowserHost, IBrowserPlugin } from "./extension-api";
+import { bindHost, Fragment, h, settings } from "./lib/host.js";
+import { ${widget}, EDITOR } from "./widgets/${widget}.js";
+
+// ${titleCase(name)} theme, browser part. A theme changes the store three ways, cheapest first:
+//   1. CSS (src/styles): the store's own markup restyled through its tokens and data-test-selector attributes.
+//   2. Slots: wrap a store component (children is what the store renders) or replace it. Names: extension-api.d.ts.
+//   3. Widgets: new page-builder blocks.
+// Settings come from the registry or, per store, from Znode attributes (settingsSchema "attribute").
+
+function Header(props: { children?: unknown }) {
+  const text = String(settings.announcement || "");
+  return (
+    <>
+      {text && (
+        <div className="theme-announcement" data-test-selector="divThemeAnnouncement">
+          {text}
+        </div>
+      )}
+      {props.children}
+    </>
+  );
+}
+
+function ProductCard(props: { children?: unknown; product?: { isNew?: boolean; attributes?: { attributeCode?: string; attributeValues?: string }[] } }) {
+  const isNew = props.product?.attributes?.some((item) => item.attributeCode === "NewProduct" && item.attributeValues === "true");
+  return (
+    <div className="theme-card">
+      {settings.showBadges !== false && isNew && <span className="theme-badge">New</span>}
+      {props.children}
+    </div>
+  );
+}
+
+export default function setup(host: IBrowserHost): IBrowserPlugin {
+  bindHost(host);
+  if (typeof document !== "undefined" && settings.accentColor) document.documentElement.style.setProperty("--theme-accent", String(settings.accentColor));
+  return {
+    slots: { "layout.header": Header, "product.card": ProductCard },
+    widgets: { ${widget}: { render: ${widget}, ...EDITOR } },
+  };
+}
+`,
+    [`src/widgets/${widget}.tsx`]: widgetSource(widget),
+    "src/styles/10-tokens.css": `/* ${titleCase(name)}: the store's design tokens. Change these first; most of the store follows them. */
+:root {
+  --theme-accent: #c4122f;
+  --primary-btn-bg: var(--theme-accent);
+  --primary-btn-text-color: #fff;
+  --font-family: "Inter", system-ui, sans-serif;
+}
+`,
+    "src/styles/20-parts.css": `/* Parts of the store's own pages, found by their data-test-selector (stable across releases). */
+.theme-announcement {
+  background: var(--theme-accent);
+  color: #fff;
+  text-align: center;
+  padding: 8px 16px;
+  font-size: 14px;
+}
+.theme-card {
+  position: relative;
+}
+.theme-badge {
+  position: absolute;
+  top: 8px;
+  left: 8px;
+  z-index: 1;
+  background: var(--theme-accent);
+  color: #fff;
+  font-size: 12px;
+  padding: 2px 8px;
+}
+[data-test-selector="btnAddToCart"] {
+  border-radius: 0;
+}
+`,
+    "src/i18n/labels.json": JSON.stringify({ Common: { addToCart: "Add to cart" } }, null, 2) + "\n",
+  };
+}
+
+function plugin(name) {
+  return {
+    "znode-package.json": marketplace(name, "plugin", ["routes", "cartHooks"], {
+      build: { server: "src/server.ts", browser: "src/browser.tsx" },
+      settingsSchema: {
+        maxQuantity: {
+          type: "number",
+          label: "Most units of one SKU per order line (0: no limit)",
+          default: 0,
+          attribute: { code: "MaxLineQuantity", levels: ["store", "account"] },
+        },
+        note: { type: "string", label: "Note shown under Add to cart", browser: true, default: "Volume pricing for business accounts." },
+      },
+    }),
+    "build-and-upload.sh": buildScript(name),
+    "src/server.ts": `import type { IPluginRouteContext, IPluginRouteRequest, IRuntimeData, IRuntimeHookContext, IRuntimePlugin } from "./extension-api";
+
+// ${titleCase(name)}, server part. Runs inside the webstore for the stores it is installed for:
+//   routes  /api/extensions/plugins/${name}/<route>: your own endpoints (JSON, or a Response for files)
+//   hooks   change carts and add-to-cart requests on their way to Znode
+//   "overrides" in znode-package.json: take over a store API route (call context.original() to run the store's own)
+// Settings: context.settings, with those bound to Znode attributes already resolved for the store and the buyer.
+
+async function limits(_request: IPluginRouteRequest, context: IPluginRouteContext) {
+  // the buyer's B2B details come from the session: use them for role, account and budget rules
+  return { maxQuantity: Number(context.settings.maxQuantity) || 0, account: context.user?.accountCode || null, role: context.user?.roleName || null };
+}
+
+async function beforeAddToCart(request: IRuntimeData, context: IRuntimeHookContext): Promise<IRuntimeData | void> {
+  const max = Number(context.settings.maxQuantity) || 0;
+  if (!max) return;
+  const quantity = Number(request.quantity);
+  if (quantity > max) return { ...request, quantity: max };
+}
+
+const plugin: IRuntimePlugin = {
+  name: "${name}",
+  apiVersion: 1,
+  routes: { limits },
+  hooks: { beforeAddToCart },
+};
+
+export default plugin;
+`,
+    "src/lib/host.ts": HOST,
+    "src/browser.tsx": `import type { IBrowserHost, IBrowserPlugin } from "./extension-api";
+import { bindHost, Fragment, h, React, settings } from "./lib/host.js";
+
+// ${titleCase(name)}, browser part: a slot around the product page's Add to cart, asking this plugin's route for the
+// buyer's limit (account-specific, so it is not in the cacheable manifest).
+
+function AddToCart(props: { children?: unknown }) {
+  const [max, setMax] = React.useState(0);
+  React.useEffect(() => {
+    fetch("/api/extensions/plugins/${name}/limits")
+      .then((response) => (response.ok ? response.json() : null))
+      .then((data) => setMax(Number(data?.maxQuantity) || 0))
+      .catch(() => setMax(0));
+  }, []);
+  return (
+    <>
+      {props.children}
+      <p className="small" data-test-selector="txt${pascalCase(name)}Note">
+        {String(settings.note || "")}
+        {max > 0 && \` Up to \${max} per line.\`}
+      </p>
+    </>
+  );
+}
+
+export default function setup(host: IBrowserHost): IBrowserPlugin {
+  bindHost(host);
+  return { slots: { "product.addToCart": AddToCart } };
+}
+`,
+  };
+}
+
+function widget(name) {
+  const component = pascalCase(name);
+  return {
+    "znode-package.json": marketplace(name, "widget", [], { build: { browser: "src/browser.tsx" }, widgets: [component] }),
+    "build-and-upload.sh": buildScript(name),
+    "src/lib/host.ts": HOST,
+    "src/browser.tsx": `import type { IBrowserHost, IBrowserPlugin } from "./extension-api";
+import { bindHost } from "./lib/host.js";
+import { ${component}, EDITOR } from "./widgets/${component}.js";
+
+// ${titleCase(name)}: a widget package. It brings page-builder widgets and nothing else, so any store with any theme can
+// place them. Use the theme's CSS variables for colors so it fits every theme.
+
+export default function setup(host: IBrowserHost): IBrowserPlugin {
+  bindHost(host);
+  return { widgets: { ${component}: { render: ${component}, ...EDITOR } } };
+}
+`,
+    [`src/widgets/${component}.tsx`]: widgetSource(component),
+  };
+}
+
+function content(name) {
+  return {
+    "znode-package.json": marketplace(name, "content", [], { pages: { "/landing": "src/pages/landing.json" } }),
+    "build-and-upload.sh": buildScript(name),
+    "src/pages/landing.json":
+      JSON.stringify(
+        {
+          root: { props: { contentWidth: "full" } },
+          content: [
+            { type: "Heading", props: { id: "Heading-landing", text: "Landing page", align: "center" } },
+            {
+              type: "Text",
+              props: {
+                id: "Text-landing",
+                text: "Shown at /landing for the stores this package is installed for. Build the page in the page builder and paste its saved JSON here.",
+                align: "center",
+              },
+            },
+          ],
+          zones: {},
+        },
+        null,
+        2
+      ) + "\n",
+  };
+}
+
+export const TEMPLATES = { theme, plugin, widget, content };