@semi-solid/solid 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 semi-solid contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# @semi-solid/solid
+
+SolidJS runtime layer for Semi-Solid. Sits between the zero-dependency stubs in `@semi-solid/runtime` and your components, providing reactive implementations that depend on `solid-js`.
+
+## Install
+
+```bash
+bun add @semi-solid/solid
+```
+
+`solid-js ^1.9.0` is a peer dependency — install it alongside this package.
+
+## What's inside
+
+| Export | Source | Description |
+|--------|--------|-------------|
+| `tap`, `tapWhen`, `tapRemote`, `tapPersonalized`, `liquidRaw`, `blockAttrs` | re-exported from `@semi-solid/runtime` | Compile-time stubs — the compiler replaces these with Liquid output and reactive signals |
+| `t`, `setTranslations` | re-exported from `@semi-solid/runtime` | i18n translation helper |
+| `createTapSignal`, `__setSectionId` | `tapWhen.ts` | Reactive signal that re-fetches from a Shopify data section when dependencies change |
+| `__tapRemoteHtml` | `tapRemote.ts` | Fetches rendered section HTML from another route via the Section Rendering API |
+| `createPersonalizedSignal`, `__setPersonalizationBaseUrl`, `buildUrl` | `tapPersonalized.ts` | Fetches personalized data from an external API with prefetch support |
+| `createStore` | `store.ts` | localStorage-backed reactive store (wishlists, recently viewed, etc.) |
+
+## Usage
+
+Components never import from this package directly. They use the `$lib/` Vite alias, which resolves to `packages/solid/src/`:
+
+```tsx
+// src/snippets/ProductCard.tsx
+import { tap } from '$lib/runtime';
+import { t } from '$lib/i18n';
+
+const title = tap('{{ product.title }}', 'Product');
+```
+
+The compiler transforms `tap()` / `tapWhen()` / `tapPersonalized()` calls at build time. The reactive implementations (`createTapSignal`, `createPersonalizedSignal`, etc.) are auto-imported by the compiler into the cleaned output — you don't call them yourself.
+
+### createStore
+
+`createStore` is the one export you use directly in component code:
+
+```tsx
+import { createStore } from '$lib/runtime';
+
+const recentlyViewed = createStore<Product>('recently-viewed', { maxItems: 10 });
+
+// Read
+const items = recentlyViewed.items(); // Accessor<Product[]>
+
+// Write
+recentlyViewed.add(product);    // prepends, deduplicates, persists to localStorage
+recentlyViewed.remove(product); // removes by JSON equality
+recentlyViewed.clear();         // empties the store
+```
+
+## Architecture
+
+```
+@semi-solid/runtime   (zero dependencies — stubs + types)
+       |
+@semi-solid/solid     (solid-js — reactive implementations)
+       |
+  Components          (import via $lib/ alias)
+       |
+@semi-solid/compiler  (Vite plugin — transforms source at build time)
+```
+
+The compiler emits `$lib/runtime` and `$lib/tapWhen` imports in the transformed output. The `$lib` alias in `vite.config.ts` points to `packages/solid/src/`, so Vite resolves everything without any component files needing to know the physical path.
+
+## Development
+
+```bash
+# Run tests
+bun run test
+
+# Watch mode
+bun run test:watch
+```

package/dist/index.d.ts

@@ -0,0 +1,117 @@
+export { blockAttrs, liquidRaw, setTranslations, t, tap, tapPersonalized, tapRemote, tapWhen } from '@semi-solid/runtime';
+import { Accessor } from 'solid-js';
+
+/**
+ * tapWhen runtime implementation.
+ *
+ * The compiler replaces every `tapWhen(liquidExpr, deps, fallback)` call with
+ * `createTapSignal(key, deps, fallback)`. The key is the LHS variable name,
+ * injected at compile time so the runtime knows which field to read from the
+ * JSON data section response.
+ *
+ * The data section is a Shopify section that renders only a
+ * <script type="application/json"> tag containing the component's tap-mapped
+ * values serialised with the | json Liquid filter. It can be fetched via:
+ *
+ *   GET {any-route}?section_id={component-name}-data
+ *
+ * The currently-mounted component's section ID is communicated via a
+ * module-level variable set by the hydration entry immediately before
+ * calling render(). This is safe because render() is synchronous and
+ * createTapSignal() captures the value in a closure at call time.
+ */
+
+declare function __setSectionId(id: string | null | undefined): void;
+/**
+ * Creates a reactive signal for a tap-mapped value.
+ *
+ * - Initialises the signal from `initial` (the prop value from data-props).
+ * - Captures the active section ID at call time (synchronously set by the
+ *   hydration entry before render()).
+ * - Registers a deferred createEffect that re-fetches the data section
+ *   whenever any dep changes and updates the signal.
+ *
+ * @param key     LHS variable name; used to index the JSON response.
+ * @param deps    Signal accessors whose changes trigger a re-fetch.
+ * @param initial Initial value, usually props.xxx from data-props.
+ */
+declare function createTapSignal<T>(key: string, deps: Accessor<unknown>[], initial: T): Accessor<T>;
+
+/**
+ * tapRemote runtime implementation.
+ *
+ * The compiler replaces every `tapRemote(Component, url)` call with
+ * `__tapRemoteHtml("remote-{kebab-name}", url)`. This function creates a
+ * SolidJS signal, fetches the rendered section HTML from the given URL via
+ * the Shopify Section Rendering API, and returns an accessor for raw HTML
+ * injection.
+ *
+ * If `url` is a reactive accessor (function), the section is re-fetched
+ * whenever the URL changes.
+ */
+
+declare function __tapRemoteHtml(sectionName: string, url: string | Accessor<string>): Accessor<string>;
+
+/**
+ * tapPersonalized runtime implementation.
+ *
+ * The compiler replaces every `tapPersonalized(url, params, fallback)` call with
+ * `createPersonalizedSignal(url, params, fallback)`. This function creates a
+ * SolidJS signal, fetches personalized data from the external API, and returns
+ * an accessor.
+ *
+ * The compiler also generates:
+ *   - <link rel="preconnect"> for the external domain
+ *   - An inline <script> that starts the fetch early (prefetch), storing the
+ *     promise on window.__p[url] so this runtime can pick it up without
+ *     duplicating the request.
+ */
+
+declare function __setPersonalizationBaseUrl(url: string | undefined): void;
+/**
+ * Builds a full URL from the endpoint and params.
+ * - Resolves relative URLs against _personalizedBaseUrl
+ * - Sorts param keys alphabetically (deterministic cache key matching with prefetch)
+ * - Builds query string with encodeURIComponent
+ */
+declare function buildUrl(endpoint: string, params: Record<string, unknown>): string;
+declare global {
+    interface Window {
+        __p?: Record<string, Promise<unknown>>;
+    }
+}
+/**
+ * Creates a reactive signal for personalized data from an external API.
+ *
+ * 1. Checks window.__p[url] for a prefetched promise (started by the
+ *    inline <head> script the compiler generates).
+ * 2. If no prefetch, fires a fetch immediately.
+ * 3. Sets up a deferred createEffect that re-fetches when any param
+ *    signal changes.
+ *
+ * @param url     API endpoint URL
+ * @param params  Named params — may contain signal accessors or plain values
+ * @param initial Initial/fallback value
+ */
+declare function createPersonalizedSignal<T>(url: string, params: Record<string, unknown>, initial: T): Accessor<T>;
+
+/**
+ * createStore — a localStorage-backed reactive store using SolidJS signals.
+ *
+ * Useful for recently viewed items, wishlists, and other client-side
+ * persistence that should survive page navigations and browser restarts.
+ */
+
+interface StoreOptions {
+    /** Maximum number of items to keep. Default: 20 */
+    maxItems?: number;
+}
+interface PersistentStore<T> {
+    items: Accessor<T[]>;
+    add: (item: T) => void;
+    remove: (item: T) => void;
+    clear: () => void;
+}
+declare function createStore<T>(key: string, options?: StoreOptions): PersistentStore<T>;
+
+export { __setPersonalizationBaseUrl, __setSectionId, __tapRemoteHtml, buildUrl, createPersonalizedSignal, createStore, createTapSignal };

package/dist/index.js

@@ -0,0 +1,200 @@
+// src/index.ts
+import { tap, tapWhen, liquidRaw, blockAttrs, tapRemote, tapPersonalized } from "@semi-solid/runtime";
+import { t, setTranslations } from "@semi-solid/runtime";
+
+// src/tapWhen.ts
+import { createSignal, createEffect, on } from "solid-js";
+var _activeSectionId;
+function __setSectionId(id) {
+  _activeSectionId = id ?? void 0;
+}
+async function fetchSectionData(sectionId) {
+  const url = new URL(
+    window.location.pathname + window.location.search,
+    window.location.origin
+  );
+  url.searchParams.set("section_id", sectionId);
+  const html = await fetch(url.toString()).then((r) => r.text());
+  const doc = new DOMParser().parseFromString(html, "text/html");
+  const script = doc.querySelector('script[type="application/json"]');
+  return JSON.parse(script?.textContent ?? "{}");
+}
+function createTapSignal(key, deps, initial) {
+  const sectionId = _activeSectionId;
+  const [value, setValue] = createSignal(initial);
+  if (sectionId && deps.length > 0) {
+    createEffect(
+      on(
+        deps,
+        async () => {
+          try {
+            const data = await fetchSectionData(sectionId);
+            if (key in data) setValue(() => data[key]);
+          } catch (e) {
+            console.error(`[tapWhen] failed to refresh "${key}":`, e);
+          }
+        },
+        { defer: true }
+        // skip initial run — data-props covers the first render
+      )
+    );
+  }
+  return value;
+}
+
+// src/tapRemote.ts
+import { createSignal as createSignal2, createEffect as createEffect2, on as on2 } from "solid-js";
+async function fetchSection(sectionName, url) {
+  const target = new URL(url, window.location.origin);
+  target.searchParams.set("section_id", sectionName);
+  const html = await fetch(target.toString()).then((r) => r.text());
+  const doc = new DOMParser().parseFromString(html, "text/html");
+  const wrapper = doc.querySelector('[id^="shopify-section-"]');
+  return wrapper?.innerHTML ?? html;
+}
+function __tapRemoteHtml(sectionName, url) {
+  const [html, setHtml] = createSignal2("");
+  if (typeof url === "function") {
+    createEffect2(
+      on2(url, async (currentUrl) => {
+        try {
+          const result = await fetchSection(sectionName, currentUrl);
+          setHtml(() => result);
+        } catch (e) {
+          console.error(`[tapRemote] failed to fetch "${sectionName}":`, e);
+        }
+      })
+    );
+  } else {
+    fetchSection(sectionName, url).then(
+      (result) => setHtml(() => result),
+      (e) => console.error(`[tapRemote] failed to fetch "${sectionName}":`, e)
+    );
+  }
+  return html;
+}
+
+// src/tapPersonalized.ts
+import { createSignal as createSignal3, createEffect as createEffect3, on as on3 } from "solid-js";
+var _personalizedBaseUrl;
+function __setPersonalizationBaseUrl(url) {
+  _personalizedBaseUrl = url;
+}
+function buildUrl(endpoint, params) {
+  let base;
+  if (/^https?:\/\//.test(endpoint)) {
+    base = endpoint;
+  } else {
+    const origin = _personalizedBaseUrl ?? "";
+    base = origin.replace(/\/$/, "") + "/" + endpoint.replace(/^\//, "");
+  }
+  const keys = Object.keys(params).sort();
+  if (keys.length === 0) return base;
+  const qs = keys.map((k) => `${encodeURIComponent(k)}=${encodeURIComponent(String(params[k] ?? ""))}`).join("&");
+  return `${base}?${qs}`;
+}
+function createPersonalizedSignal(url, params, initial) {
+  const [value, setValue] = createSignal3(initial);
+  function resolveParams() {
+    const resolved = {};
+    for (const [k, v] of Object.entries(params)) {
+      resolved[k] = typeof v === "function" ? v() : v;
+    }
+    return resolved;
+  }
+  async function fetchData() {
+    const resolved = resolveParams();
+    const fullUrl = buildUrl(url, resolved);
+    try {
+      const prefetch = window.__p?.[fullUrl];
+      let data;
+      if (prefetch) {
+        data = await prefetch;
+        delete window.__p[fullUrl];
+      } else {
+        const res = await fetch(fullUrl);
+        data = await res.json();
+      }
+      setValue(() => data);
+    } catch (e) {
+      console.error(`[tapPersonalized] failed to fetch "${url}":`, e);
+    }
+  }
+  const accessors = Object.values(params).filter(
+    (v) => typeof v === "function"
+  );
+  if (accessors.length > 0) {
+    fetchData();
+    createEffect3(
+      on3(
+        accessors,
+        () => {
+          fetchData();
+        },
+        { defer: true }
+      )
+    );
+  } else {
+    fetchData();
+  }
+  return value;
+}
+
+// src/store.ts
+import { createSignal as createSignal4 } from "solid-js";
+function readStorage(key) {
+  try {
+    const raw = localStorage.getItem(key);
+    if (!raw) return [];
+    return JSON.parse(raw);
+  } catch {
+    return [];
+  }
+}
+function writeStorage(key, value) {
+  try {
+    localStorage.setItem(key, JSON.stringify(value));
+  } catch {
+  }
+}
+function createStore(key, options) {
+  const maxItems = options?.maxItems ?? 20;
+  const initial = readStorage(key);
+  const [items, setItems] = createSignal4(initial);
+  function persist(next) {
+    setItems(() => next);
+    writeStorage(key, next);
+  }
+  function add(item) {
+    const serialised = JSON.stringify(item);
+    const deduped = items().filter((existing) => JSON.stringify(existing) !== serialised);
+    const next = [item, ...deduped].slice(0, maxItems);
+    persist(next);
+  }
+  function remove(item) {
+    const serialised = JSON.stringify(item);
+    const next = items().filter((existing) => JSON.stringify(existing) !== serialised);
+    persist(next);
+  }
+  function clear() {
+    persist([]);
+  }
+  return { items, add, remove, clear };
+}
+export {
+  __setPersonalizationBaseUrl,
+  __setSectionId,
+  __tapRemoteHtml,
+  blockAttrs,
+  buildUrl,
+  createPersonalizedSignal,
+  createStore,
+  createTapSignal,
+  liquidRaw,
+  setTranslations,
+  t,
+  tap,
+  tapPersonalized,
+  tapRemote,
+  tapWhen
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@semi-solid/solid",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@semi-solid/runtime": "0.1.0"
+  },
+  "peerDependencies": {
+    "solid-js": "^1.9.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}