npm - @symbo.ls/brender - Versions diffs - 3.6.4 → 3.6.7 - Mend

@symbo.ls/brender 3.6.4 → 3.6.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/README.md CHANGED Viewed

@@ -59,12 +59,14 @@ Browser DOM (static)              DOMQL Tree (no nodes)         After hydrate()
 | File | Purpose |
 |------|---------|
-| `render.js` | `render()` — full project render via smbls pipeline; `renderElement()` — single component via @domql/element |
+| `render.js` | `render()` — full project render via smbls pipeline; `renderElement()` — single component; `renderPage()` — complete HTML page |
 | `hydrate.js` | `collectBrNodes()` — scans DOM for data-br nodes; `hydrate()` — reconnects DOMQL tree to DOM |
 | `env.js` | `createEnv()` — linkedom virtual DOM with browser API stubs (requestAnimationFrame, history, location, etc.) |
 | `keys.js` | `resetKeys()`, `assignKeys()` — stamps data-br on DOM nodes; `mapKeysToElements()` — builds registry |
 | `metadata.js` | Re-exports from [`@symbo.ls/helmet`](../helmet/) — `extractMetadata()`, `generateHeadHtml()`, `resolveMetadata()`, `applyMetadata()` |
+| `prefetch.js` | `prefetchPageData()` — SSR data prefetching via DB adapter (Supabase); `injectPrefetchedState()` — injects fetched data into page definitions |
 | `load.js` | `loadProject()` — imports a symbols/ directory; `loadAndRenderAll()` — renders every route |
+| `sitemap.js` | `generateSitemap()` — generates sitemap.xml from routes |
 | `index.js` | Re-exports everything |
 ## API
@@ -101,7 +103,7 @@ const result = await renderElement(pageDef, {
 ### `render(data, options?)`
-Renders a full Symbols project. Requires the smbls pipeline (createDomqlElement) — handles routing, state, designSystem initialization, the full app context.
+Renders a full Symbols project. Requires the smbls pipeline (createDomqlElement) — handles routing, state, designSystem initialization, the full app context. Uses esbuild to bundle the smbls source tree (cached after first call).
 ```js
 import { render, loadProject } from '@symbo.ls/brender'
@@ -109,10 +111,40 @@ import { render, loadProject } from '@symbo.ls/brender'
 const data = await loadProject('/path/to/project')
 const result = await render(data, { route: '/about' })
-// result.html      -> full page HTML with data-br keys
-// result.metadata  -> { title, description, og:image, ... }
-// result.registry  -> { br-key: domqlElement }
-// result.element   -> root DOMQL element
+// result.html       -> full page HTML with data-br keys
+// result.metadata   -> { title, description, og:image, ... }
+// result.emotionCSS -> array of CSS rule strings from emotion
+// result.registry   -> { br-key: domqlElement }
+// result.element    -> root DOMQL element
+```
+### `renderPage(data, route, options?)`
+Renders a complete, ready-to-serve HTML page. Combines `render()` output with metadata, CSS (emotion + global), fonts, and optional ISR client bundle.
+```js
+import { renderPage, loadProject } from '@symbo.ls/brender'
+const data = await loadProject('/path/to/project')
+const result = await renderPage(data, '/about', {
+  lang: 'ka',
+  prefetch: true  // enable SSR data prefetching
+})
+// result.html       -> complete <!DOCTYPE html> page
+// result.route      -> '/about'
+// result.brKeyCount -> number of data-br keys
+```
+### `prefetchPageData(data, route, options?)`
+Fetches data for a page's declarative `fetch` definitions during SSR, using the project's DB adapter (e.g. Supabase).
+```js
+import { prefetchPageData } from '@symbo.ls/brender'
+const stateUpdates = await prefetchPageData(data, '/blog')
+// stateUpdates -> { articles: [...], events: [...] }
 ```
 ### `hydrate(element, options?)`
@@ -177,6 +209,40 @@ generateHeadHtml({ title: 'My Page', description: 'About', 'og:image': '/img.png
 Metadata values can also be functions — see the [helmet plugin](../helmet/) for details.
+## CLI
+The `smbls brender` command renders all static routes for a project:
+```bash
+# Basic usage — renders all static routes to dist-brender/
+smbls brender
+# Custom output directory
+smbls brender --out-dir build
+# Disable ISR client bundle
+smbls brender --no-isr
+# Disable SSR data prefetching
+smbls brender --no-prefetch
+# Watch mode — re-renders on file changes
+smbls brender --watch
+```
+Output directory defaults to `dist-brender` (or `brenderDistDir` from `symbols.json`) to avoid conflicting with the SPA's `dist/` folder.
+Param routes (e.g. `/blog/:id`) are automatically skipped — they need runtime data.
+### symbols.json
+```json
+{
+  "brender": true,
+  "brenderDistDir": "dist-brender"
+}
+```
 ## Examples
 The `examples/` directory contains runnable experiments. Copy a project's source into `examples/` first (gitignored), then run:
@@ -279,9 +345,13 @@ This means the server and client don't need to exchange the registry — as long
 - `renderElement()` uses `@domql/element` create directly — lightweight, no smbls bootstrap. Good for individual components
 - `render()` uses the full `smbls/src/createDomql.js` pipeline — handles routing, designSystem initialization, uikit defaults, the works. Needed for complete apps
+- The smbls source is bundled with esbuild (cached after first call) because the monorepo uses extensionless/directory imports that Node.js ESM can't resolve natively. The esbuild plugin patches SSR-incompatible code (window references, createRequire, circular imports) and stubs out browser-only packages (@symbo.ls/sync)
+- `render()` sets `globalThis.document` and `globalThis.location` before each render to match the linkedom virtual env, then restores them after. This allows the bundled smbls code (which reads `window = globalThis`) to work in SSR
 - `hydrate.js` is browser-only code (no linkedom dependency) — it's exported separately via `@symbo.ls/brender/hydrate`
 - `createEnv()` sets `globalThis.window/document/Node/HTMLElement` because `@domql/utils` `isDOMNode` uses `instanceof` checks against global constructors
+- Emotion CSS is extracted from the CSSOM sheet rules (emotion uses `insertRule()` which doesn't populate `textContent` in linkedom)
 - `onRender` callbacks that do network requests or call `s.update()` will error during SSR — this is expected and harmless since the HTML is already produced before those callbacks fire
+- Data prefetching (`prefetch.js`) walks page definitions to find `fetch` declarations, then executes them against the DB adapter before rendering. Fetched data is injected into page state so components render with real content
 ## Theme support

package/dist/cjs/index.js CHANGED Viewed

@@ -25,13 +25,16 @@ __export(index_exports, {
   generateHeadHtml: () => import_metadata.generateHeadHtml,
   generateSitemap: () => import_sitemap.generateSitemap,
   hydrate: () => import_hydrate.hydrate,
+  injectPrefetchedState: () => import_prefetch.injectPrefetchedState,
   loadAndRenderAll: () => import_load.loadAndRenderAll,
   loadProject: () => import_load.loadProject,
   mapKeysToElements: () => import_keys.mapKeysToElements,
+  prefetchPageData: () => import_prefetch.prefetchPageData,
   render: () => import_render.render,
   renderElement: () => import_render.renderElement,
   renderPage: () => import_render.renderPage,
   renderRoute: () => import_render.renderRoute,
+  resetGlobalCSSCache: () => import_render.resetGlobalCSSCache,
   resetKeys: () => import_keys.resetKeys
 });
 module.exports = __toCommonJS(index_exports);
@@ -42,6 +45,7 @@ var import_render = require("./render.js");
 var import_metadata = require("./metadata.js");
 var import_hydrate = require("./hydrate.js");
 var import_sitemap = require("./sitemap.js");
+var import_prefetch = require("./prefetch.js");
 var index_default = {
   createEnv: import_env.createEnv,
   resetKeys: import_keys.resetKeys,
@@ -53,9 +57,12 @@ var index_default = {
   renderElement: import_render.renderElement,
   renderRoute: import_render.renderRoute,
   renderPage: import_render.renderPage,
+  resetGlobalCSSCache: import_render.resetGlobalCSSCache,
   extractMetadata: import_metadata.extractMetadata,
   generateHeadHtml: import_metadata.generateHeadHtml,
   collectBrNodes: import_hydrate.collectBrNodes,
   hydrate: import_hydrate.hydrate,
-  generateSitemap: import_sitemap.generateSitemap
+  generateSitemap: import_sitemap.generateSitemap,
+  prefetchPageData: import_prefetch.prefetchPageData,
+  injectPrefetchedState: import_prefetch.injectPrefetchedState
 };

package/dist/cjs/prefetch.js ADDED Viewed

@@ -0,0 +1,199 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var prefetch_exports = {};
+__export(prefetch_exports, {
+  injectPrefetchedState: () => injectPrefetchedState,
+  prefetchPageData: () => prefetchPageData
+});
+module.exports = __toCommonJS(prefetch_exports);
+const isFunction = (v) => typeof v === "function";
+const isArray = (v) => Array.isArray(v);
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const resolveParams = (params, mockState) => {
+  if (!params) return void 0;
+  if (isFunction(params)) {
+    try {
+      const mockEl = {
+        state: mockState || {},
+        props: {},
+        call: () => void 0,
+        __ref: {}
+      };
+      return params(mockEl, mockState || {});
+    } catch {
+      return void 0;
+    }
+  }
+  return params;
+};
+const normalizeFetchConfig = (cfg, elementState) => {
+  if (!cfg) return null;
+  if (typeof cfg === "string") return { from: cfg, method: "select" };
+  const resolved = isFunction(cfg) ? null : { ...cfg };
+  if (!resolved) return null;
+  if (!resolved.method) resolved.method = "select";
+  if (isFunction(resolved.params)) {
+    resolved.params = resolveParams(resolved.params, elementState);
+  }
+  const isMutation = resolved.method === "insert" || resolved.method === "update" || resolved.method === "upsert" || resolved.method === "delete";
+  if (isMutation) return null;
+  if (resolved.on && resolved.on !== "create") return null;
+  return resolved;
+};
+const collectFetchDeclarations = (def, path = "") => {
+  if (!def || typeof def !== "object") return [];
+  if (isFunction(def)) return [];
+  const results = [];
+  const elementState = def.state || {};
+  if (def.fetch) {
+    const fetchDefs = isArray(def.fetch) ? def.fetch : [def.fetch];
+    for (const fd of fetchDefs) {
+      const config = normalizeFetchConfig(fd, elementState);
+      if (config) {
+        results.push({
+          config,
+          stateKey: config.as,
+          path,
+          elementState
+        });
+      }
+    }
+  }
+  for (const key in def) {
+    if (key === "fetch" || key === "state" || key === "props" || key === "attr" || key === "on" || key === "define" || key === "childExtends" || key === "childProps" || key === "childrenAs") continue;
+    if (key.charAt(0) >= "A" && key.charAt(0) <= "Z" && isObject(def[key])) {
+      results.push(...collectFetchDeclarations(def[key], path ? `${path}.${key}` : key));
+    }
+  }
+  return results;
+};
+const createSSRAdapter = async (dbConfig) => {
+  if (!dbConfig) return null;
+  const { adapter, createClient, url, key, projectId } = dbConfig;
+  if (adapter !== "supabase") return null;
+  const supabaseUrl = url || projectId && `https://${projectId}.supabase.co`;
+  if (!supabaseUrl || !key) return null;
+  let clientFactory = createClient;
+  if (!clientFactory) {
+    try {
+      const mod = await import("@supabase/supabase-js");
+      clientFactory = mod.createClient;
+    } catch {
+      return null;
+    }
+  }
+  const client = clientFactory(supabaseUrl, key);
+  return {
+    rpc: ({ from, params }) => client.rpc(from, params),
+    select: async ({ from, select: sel, params, limit, offset, order, single }) => {
+      let q = client.from(from).select(sel || "*");
+      if (params) {
+        for (const k in params) {
+          const v = params[k];
+          if (v === null) q = q.is(k, null);
+          else if (Array.isArray(v)) q = q.in(k, v);
+          else q = q.eq(k, v);
+        }
+      }
+      if (order) {
+        const orderBy = typeof order === "string" ? order : order.by;
+        q = q.order(orderBy, { ascending: order.asc !== false });
+      }
+      if (limit) q = q.limit(limit);
+      if (offset) q = q.range(offset, offset + (limit || 20) - 1);
+      if (single) q = q.single();
+      return q;
+    }
+  };
+};
+const executeSingle = async (adapter, config) => {
+  try {
+    const { method, from, params, transform, limit, offset, order, single } = config;
+    let result;
+    if (method === "rpc") {
+      result = await adapter.rpc({ from, params });
+    } else {
+      result = await adapter.select({ from, select: config.select, params, limit, offset, order, single });
+    }
+    let data = result?.data ?? null;
+    if (result?.error) {
+      return null;
+    }
+    if (data && transform && isFunction(transform)) {
+      try {
+        data = transform(data);
+      } catch {
+      }
+    }
+    return data;
+  } catch {
+    return null;
+  }
+};
+const prefetchPageData = async (data, route = "/", options = {}) => {
+  const pages = data.pages || {};
+  const pageDef = pages[route];
+  if (!pageDef) return /* @__PURE__ */ new Map();
+  const dbConfig = data.config?.db || data.settings?.db || data.db;
+  if (!dbConfig) return /* @__PURE__ */ new Map();
+  const adapter = await createSSRAdapter(dbConfig);
+  if (!adapter) return /* @__PURE__ */ new Map();
+  const declarations = collectFetchDeclarations(pageDef);
+  if (!declarations.length) return /* @__PURE__ */ new Map();
+  const stateUpdates = /* @__PURE__ */ new Map();
+  const results = await Promise.allSettled(
+    declarations.map(async ({ config, stateKey, path }) => {
+      const fetchedData = await executeSingle(adapter, config);
+      if (fetchedData !== null && stateKey) {
+        const existing = stateUpdates.get(path) || {};
+        existing[stateKey] = fetchedData;
+        stateUpdates.set(path, existing);
+      }
+    })
+  );
+  return stateUpdates;
+};
+const injectPrefetchedState = (pageDef, stateUpdates) => {
+  if (!stateUpdates || !stateUpdates.size) return;
+  for (const [path, data] of stateUpdates) {
+    let target = pageDef;
+    if (path) {
+      const parts = path.split(".");
+      for (const part of parts) {
+        if (!target || typeof target !== "object") break;
+        target = target[part];
+      }
+    }
+    if (target && typeof target === "object") {
+      if (!target.state || typeof target.state !== "object") {
+        target.state = {};
+      }
+      Object.assign(target.state, data);
+    }
+  }
+};