@crombolo/render 0.0.0-stage → 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kineco
+
+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/NOTICE

@@ -0,0 +1,69 @@
+crombolo
+Copyright (c) 2026 Kineco
+
+This product includes third-party software. crombolo is an independent project.
+It is not affiliated with, endorsed by, or sponsored by Umbraco A/S, which owns
+the Umbraco trademark.
+
+There are three places third-party material is redistributed, rather than merely
+depended on:
+
+  @crombolo/backoffice-dist   the built Umbraco backoffice and the browser
+                              packages bundled into it, produced by
+                              `bun run vendor:backoffice`
+  @crombolo/backoffice-dist   three CSS files copied unmodified from the Umbraco
+                              client source tree
+  @crombolo/contracts         the Umbraco Management API OpenAPI document,
+                              copied unmodified
+
+No Umbraco trademark is redistributed. The Umbraco wordmark, the "U" roundel
+favicon and the installer illustration are deliberately not carried in this
+repository: MIT grants copyright permission and says nothing about trademarks, so
+crombolo's own marks are served at those paths instead. See `BRANDED_ASSETS` in
+`@crombolo/backoffice-host`.
+
+The Umbraco backoffice
+----------------------
+@umbraco-cms/backoffice 18.2.0 — MIT — https://github.com/umbraco/Umbraco-CMS
+@umbraco-ui/uui 2.0.2 — MIT — https://github.com/umbraco/Umbraco.UI
+
+Static files from the Umbraco client source tree
+------------------------------------------------
+css/umb-css.css, css/rte-content.css, css/umbraco-blockgridlayout.css
+  — copied unmodified from Umbraco-CMS release-18.2.0 — MIT
+  — https://github.com/umbraco/Umbraco-CMS
+Shipped in @crombolo/backoffice-dist under `upstream-static/`.
+
+`rte-content.css` itself carries Tiptap's default editor styles, copied from
+tiptap v2.11.7 (MIT); the file records this in its own header.
+
+The Umbraco Management API contract
+-----------------------------------
+OpenApi.json — copied unmodified from Umbraco-CMS release-18.2.0
+  (src/Umbraco.Cms.Api.Management/OpenApi.json) — MIT
+  — https://github.com/umbraco/Umbraco-CMS
+Shipped in @crombolo/contracts, which also ships the TypeScript types generated
+from it.
+
+Browser runtime dependencies bundled into the backoffice build
+--------------------------------------------------------------
+@heximal/expressions 0.1.5 — BSD-3-Clause
+@microsoft/signalr 10.0.11 — MIT
+@tiptap/* 3.31.3 — MIT
+diff 9.0.0 — BSD-3-Clause
+dompurify 3.4.16 — Apache-2.0, elected from "MPL-2.0 OR Apache-2.0"
+element-internals-polyfill 3.0.2 — MIT
+lit 3.3.3 — BSD-3-Clause
+luxon 3.7.2 — MIT
+marked 18.0.14 — MIT
+monaco-editor 0.57.0 — MIT
+rxjs 7.8.2 — Apache-2.0
+uuid 14.0.2 — MIT
+
+dompurify is offered under either licence; Apache-2.0 is elected here, so no
+MPL-2.0 obligation attaches to the copy bundled into the backoffice build. Of the
+Apache-2.0 packages above, none ships a NOTICE file of its own, so Apache-2.0
+section 4(d) adds nothing to this file.
+
+Each package's own licence text ships inside its npm distribution and applies
+unchanged to the copies bundled here.

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@crombolo/render",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.10.0",
+  "description": "TSX server rendering and the published-content model for crombolo.",
+  "license": "MIT",
+  "author": "Crombolo",
+  "homepage": "https://github.com/kineco-au/crombolo-cms#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kineco-au/crombolo-cms.git",
+    "directory": "packages/render"
+  },
+  "bugs": {
+    "url": "https://github.com/kineco-au/crombolo-cms/issues"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./jsx-runtime": "./src/jsx-runtime.ts",
+    "./jsx-dev-runtime": "./src/jsx-runtime.ts",
+    "./loose/jsx-runtime": "./src/loose/jsx-runtime.ts",
+    "./loose/jsx-dev-runtime": "./src/loose/jsx-runtime.ts"
+  },
+  "files": [
+    "src",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@crombolo/core": "0.10.0",
+    "@types/react": "^19.3.0"
+  }
+}

package/src/context.ts

@@ -0,0 +1,112 @@
+/**
+ * Context for page templates: the page being rendered from any component, a
+ * value of the template's own handed down without props, and ids unique to the
+ * render.
+ *
+ * React carries context down an element tree it renders later. This runtime
+ * renders as it goes — a component's children have rendered before it runs —
+ * so the values live in storage scoped to the render instead, which follows
+ * every call and every `await` inside it and nothing outside it. Two requests
+ * rendering at once each see their own.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks'
+import type { Child } from './jsx-runtime.ts'
+import type { PageProps } from './model.ts'
+
+interface RenderScope {
+  page: PageProps | undefined
+  contexts: ReadonlyMap<symbol, unknown>
+  /** Shared by every scope a provider opens inside one render, so ids stay unique. */
+  ids: { next: number }
+}
+
+/**
+ * Kept on `globalThis` so that two copies of this module, a site's and the
+ * server's, share one store rather than each seeing nothing of the other's.
+ */
+const KEY = Symbol.for('crombolo.render-scope')
+const shared = globalThis as Record<symbol, unknown>
+if (!shared[KEY]) shared[KEY] = new AsyncLocalStorage<RenderScope>()
+const store = shared[KEY] as AsyncLocalStorage<RenderScope>
+
+/** Runs a render with `page` available to `usePage()`, and ids counted from zero. */
+export function renderScope<T>(page: PageProps, render: () => T): T {
+  return store.run({ page, contexts: new Map(), ids: { next: 0 } }, render)
+}
+
+function within(caller: string): RenderScope {
+  const scope = store.getStore()
+  if (!scope)
+    throw new Error(
+      `${caller} can only be called while a page is rendering: in a component, not at the top of a module or later in a timer.`,
+    )
+  return scope
+}
+
+/**
+ * The page being rendered, from any component: `model`, `nav`, `culture`,
+ * `member`, `signal` and the rest of what a template is given. Name the page's
+ * generated interface to type it: `usePage<HomePage>()`.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: an untyped page, as `PageProps` defaults to.
+export function usePage<Properties = any>(): PageProps<Properties> {
+  const { page } = within('usePage()')
+  if (!page)
+    throw new Error('usePage() was called inside a context Provider rendered outside a page.')
+  return page as PageProps<Properties>
+}
+
+/**
+ * An id unique within this render, for tying a label to its input or an
+ * `aria-describedby` to its text. Not for CSS selectors: the colons need escaping.
+ */
+export function useId(): string {
+  return `:b${within('useId()').ids.next++}:`
+}
+
+export interface ProviderProps<T> {
+  value: T
+  /**
+   * A function, unlike React: children written plainly have already rendered by
+   * the time the provider runs, so they could not see its value.
+   */
+  children: () => Child
+}
+
+/** A context: render it, or its `Provider`, to hand a value to everything inside. */
+export interface Context<T> {
+  (props: ProviderProps<T>): Child
+  readonly Provider: (props: ProviderProps<T>) => Child
+  readonly defaultValue: T
+  readonly key: symbol
+}
+
+/**
+ * A value handed down without props:
+ *
+ * ```tsx
+ * const Theme = createContext('light')
+ * <Theme.Provider value="dark">{() => <Sidebar />}</Theme.Provider>
+ * // and in Sidebar, however deep: useContext(Theme)
+ * ```
+ */
+export function createContext<T>(defaultValue: T): Context<T> {
+  const key = Symbol('context')
+  const Provider = ({ value, children }: ProviderProps<T>): Child => {
+    if (typeof children !== 'function')
+      throw new Error(
+        'A context Provider takes its children as a function, {() => <Sidebar />}. Written plainly they have already rendered, without its value.',
+      )
+    const outer = store.getStore()
+    const contexts = new Map(outer?.contexts)
+    contexts.set(key, value)
+    return store.run({ page: outer?.page, contexts, ids: outer?.ids ?? { next: 0 } }, children)
+  }
+  return Object.assign(Provider, { Provider, defaultValue, key }) as Context<T>
+}
+
+/** The value of the nearest provider of `context` around this component, or its default. */
+export function useContext<T>(context: Context<T>): T {
+  const contexts = store.getStore()?.contexts
+  return contexts?.has(context.key) ? (contexts.get(context.key) as T) : context.defaultValue
+}

package/src/form-script.ts

@@ -0,0 +1,112 @@
+/**
+ * The progressive-enhancement script for a rendered form.
+ *
+ * Held as a string rather than a file so it travels with the package and needs
+ * no build step or path resolution. It is small on purpose: the server
+ * re-evaluates every condition anyway, so this only decides what a visitor
+ * *sees* between keystrokes. A visitor without JavaScript gets the server's
+ * answer when they submit, which is the same answer.
+ *
+ * Mirrors `isShown`/`evaluateRule` in `@crombolo/core`. The two are kept in
+ * step by `tests/forms-conditions.test.ts`, which runs the same cases through
+ * both.
+ */
+export const FORM_SCRIPT_PATH = '/crombolo/forms.js'
+
+export const FORM_SCRIPT = `/* crombolo form conditions */
+(function () {
+  if (window.__cromboloForms) return
+
+  function valuesOf(form, alias) {
+    var out = []
+    var inputs = form.querySelectorAll('[name="' + alias.replace(/"/g, '\\\\"') + '"]')
+    for (var i = 0; i < inputs.length; i++) {
+      var input = inputs[i]
+      if ((input.type === 'checkbox' || input.type === 'radio') && !input.checked) continue
+      if (input.value !== undefined && String(input.value).trim() !== '') out.push(String(input.value).trim())
+    }
+    return out
+  }
+
+  function numeric(a, b) {
+    var x = Number(a)
+    var y = Number(b)
+    return isFinite(x) && isFinite(y) ? x - y : undefined
+  }
+
+  function rule(form, r) {
+    var values = valuesOf(form, r.field)
+    var target = r.value === undefined ? '' : r.value
+    var first = values.length > 0 ? values[0] : ''
+    switch (r.operator) {
+      case 'is': return values.indexOf(target) !== -1
+      case 'isNot': return values.indexOf(target) === -1
+      case 'contains': return values.some(function (v) { return v.indexOf(target) !== -1 })
+      case 'doesNotContain': return !values.some(function (v) { return v.indexOf(target) !== -1 })
+      case 'startsWith': return first.indexOf(target) === 0
+      case 'endsWith': return first.length >= target.length && first.slice(first.length - target.length) === target
+      case 'greaterThan': {
+        var g = numeric(first, target)
+        return g === undefined ? first > target : g > 0
+      }
+      case 'lessThan': {
+        var l = numeric(first, target)
+        return l === undefined ? first < target : l < 0
+      }
+      case 'isEmpty': return values.length === 0
+      case 'isNotEmpty': return values.length > 0
+      default: return true
+    }
+  }
+
+  function shown(form, condition) {
+    if (!condition || !condition.rules || condition.rules.length === 0) return true
+    var matched = condition.match === 'any'
+      ? condition.rules.some(function (r) { return rule(form, r) })
+      : condition.rules.every(function (r) { return rule(form, r) })
+    return condition.action === 'hide' ? !matched : matched
+  }
+
+  function apply(form) {
+    var conditional = form.querySelectorAll('[data-condition]')
+    for (var i = 0; i < conditional.length; i++) {
+      var element = conditional[i]
+      var condition
+      try {
+        condition = JSON.parse(element.getAttribute('data-condition'))
+      } catch (error) {
+        continue
+      }
+      var visible = shown(form, condition)
+      element.hidden = !visible
+      // A hidden field must not be required, or the browser refuses to submit a
+      // form over something nobody can see.
+      var wasRequired = element.getAttribute('data-required') === 'true'
+      var inputs = element.querySelectorAll('input, select, textarea')
+      for (var j = 0; j < inputs.length; j++) {
+        var input = inputs[j]
+        if (visible) {
+          if (input.dataset.cromboloRequired === 'true' || wasRequired) input.required = true
+        } else {
+          if (input.required) input.dataset.cromboloRequired = 'true'
+          input.required = false
+        }
+      }
+    }
+  }
+
+  function attach(form) {
+    apply(form)
+    form.addEventListener('input', function () { apply(form) })
+    form.addEventListener('change', function () { apply(form) })
+  }
+
+  // Also the guard against running twice, which two forms on a page would
+  // otherwise do. Exposed rather than a bare flag so the suite can hold these
+  // two functions against the server's own -- see tests/forms-conditions.
+  window.__cromboloForms = { rule: rule, shown: shown, apply: apply }
+
+  var forms = document.querySelectorAll('form.crombolo-form')
+  for (var i = 0; i < forms.length; i++) attach(forms[i])
+})();
+`