@crombolo/core 0.0.0-stage → 0.9.1

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,30 @@
 {
   "name": "@crombolo/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.9.1",
+  "description": "Domain model, entity keys and shared contracts for crombolo. No I/O.",
+  "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/core"
+  },
+  "bugs": {
+    "url": "https://github.com/kineco-au/crombolo-cms/issues"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/api-paths.ts

@@ -0,0 +1,22 @@
+/**
+ * The paths the vendored client hard-codes.
+ *
+ * Umbraco's `UmbracoPath` moves the editor, not its API: the Management API is
+ * declared by the contract and the client's generated SDK calls it at
+ * `/umbraco/management/api/v1/...` however the backoffice is mounted. The two
+ * SignalR hubs are built the same way in the client's own source. So these stay
+ * put while `backOfficePath` moves the shell, the login page, the static assets
+ * and the SPA's own routes.
+ */
+export const MANAGEMENT_API_PREFIX = '/umbraco/management/api/'
+
+export const MANAGEMENT_API_PATH = `${MANAGEMENT_API_PREFIX}v1`
+
+/** `server-event.context.js`: `${serverURL}/umbraco/serverEventHub`. */
+export const SERVER_EVENT_HUB_PATH = '/umbraco/serverEventHub'
+
+/** `preview.context.js`: `${serverUrl}/umbraco/PreviewHub`. */
+export const PREVIEW_HUB_PATH = '/umbraco/PreviewHub'
+
+/** Where the editor is mounted unless a site overrides `backOfficePath`. */
+export const DEFAULT_BACKOFFICE_PATH = '/crombolo'

package/src/content-types.ts

@@ -0,0 +1,257 @@
+/**
+ * The content-type aggregate: a content type plus its property groups, property
+ * types, compositions, allowed children and templates.
+ *
+ * Kept as one aggregate because the editor saves it as one document, and because
+ * the property set is only meaningful together with the compositions it inherits.
+ */
+export interface PropertyTypeModel {
+  key: string
+  alias: string
+  name: string
+  description: string | null
+  dataTypeKey: string
+  /** The group this property renders in, or null for the generic tab. */
+  containerKey: string | null
+  sortOrder: number
+  variesByCulture: boolean
+  variesBySegment: boolean
+  mandatory: boolean
+  mandatoryMessage: string | null
+  regEx: string | null
+  regExMessage: string | null
+  labelOnTop: boolean
+  /** The file's `since`, when written. */
+  sinceVersion?: string | null
+  /** Set when the element is not yet live on the reading node: the state it goes live in. */
+  pending?: { version: string; revision: string } | null
+  /** Member types only: shown to the member on their profile. */
+  memberCanView?: boolean
+  /** Member types only: editable by the member on their profile. */
+  memberCanEdit?: boolean
+  /** Member types only: hidden from users without sensitive-data access. */
+  isSensitive?: boolean
+}
+
+export interface PropertyGroupModel {
+  key: string
+  name: string | null
+  alias: string | null
+  /** 'Tab' or 'Group'; the wire format is a string. */
+  type: string
+  sortOrder: number
+  parentKey: string | null
+}
+
+export type CompositionType = 'Composition' | 'Inheritance'
+
+export interface CompositionModel {
+  contentTypeKey: string
+  compositionType: CompositionType
+}
+
+export interface AllowedChildModel {
+  contentTypeKey: string
+  sortOrder: number
+}
+
+export interface CleanupModel {
+  preventCleanup: boolean
+  keepAllVersionsNewerThanDays: number | null
+  keepLatestVersionPerDayForDays: number | null
+}
+
+export interface ContentTypeAggregate {
+  key: string
+  alias: string
+  name: string
+  description: string | null
+  icon: string
+  allowedAsRoot: boolean
+  variesByCulture: boolean
+  variesBySegment: boolean
+  isElement: boolean
+  allowedInLibrary: boolean
+  collectionKey: string | null
+  cleanup: CleanupModel
+  properties: PropertyTypeModel[]
+  containers: PropertyGroupModel[]
+  compositions: CompositionModel[]
+  allowedContentTypes: AllowedChildModel[]
+  allowedComponentKeys: string[]
+  defaultComponentKey: string | null
+  /** Folder placement in the tree, which is not the composition graph. */
+  parentKey: string | null
+  sinceVersion?: string | null
+  pending?: { version: string; revision: string } | null
+}
+
+/**
+ * Umbraco's system media types (`IsSystemMediaType`): always present, not
+ * deletable, alias fixed. Keys from its installer.
+ */
+export const SYSTEM_MEDIA_TYPE_KEYS: Readonly<Record<'Folder' | 'Image' | 'File', string>> = {
+  Folder: 'f38bd2d7-65d0-48e6-95dc-87ce06ec2d3d',
+  Image: 'cc07b313-0843-4aa8-bbda-871c8da728c8',
+  File: '4c52d8ab-54e6-40cd-999c-7a5f24903e4d',
+}
+
+export function isSystemMediaType(key: string): boolean {
+  return Object.values(SYSTEM_MEDIA_TYPE_KEYS).includes(key.toLowerCase())
+}
+
+/**
+ * Umbraco's one built-in member type, "Member", by the key its installer uses:
+ * always present, so a fresh install can create a member without a schema file.
+ */
+export const SYSTEM_MEMBER_TYPE_KEY = 'd59be02f-1df9-4228-aa1e-01917d806cda'
+
+export function isSystemMemberType(key: string): boolean {
+  return key.toLowerCase() === SYSTEM_MEMBER_TYPE_KEY
+}
+
+/**
+ * Content types this CMS ships: always present, not deletable, alias fixed. A
+ * site may add fields to one, but not remove or change the ones it ships with.
+ */
+export const SYSTEM_CONTENT_TYPE_KEYS: Readonly<Record<'SeoFields', string>> = {
+  SeoFields: '5e0f1c2a-7b3d-4c8e-9a61-0d2b4f6e8a13',
+}
+
+export function isSystemContentType(kind: 'document' | 'media' | 'member', key: string): boolean {
+  if (kind === 'media') return isSystemMediaType(key)
+  if (kind === 'member') return isSystemMemberType(key)
+  return Object.values(SYSTEM_CONTENT_TYPE_KEYS).includes(key.toLowerCase())
+}
+
+/** A field a system content type ships with, which a site may not remove or change. */
+export interface SystemPropertyModel {
+  key: string
+  alias: string
+  name: string
+  description: string
+  dataTypeKey: string
+}
+
+/**
+ * The "Search & sharing" composition's own fields. Invariant as shipped: the data
+ * layer does not mask a property's variance by the composing type's, so a site
+ * that wants per-language values turns variance on in its own file.
+ */
+export const SEO_FIELDS_PROPERTIES: readonly SystemPropertyModel[] = [
+  {
+    key: '8d1f3a52-6c0e-4b7a-9e24-1a5c7d9f0b31',
+    alias: 'seoTitle',
+    name: 'Search title',
+    description: 'Shown in search results and browser tabs. Leave empty to use the page name.',
+    dataTypeKey: '0cc0eba1-9960-42c9-bf9b-60e150b429ae',
+  },
+  {
+    key: '2b7e9c41-0d5f-4a63-8b18-6e4c2a0f7d52',
+    alias: 'seoDescription',
+    name: 'Search description',
+    description: 'A sentence or two shown under the title in search results and when shared.',
+    dataTypeKey: 'c6bac0dd-4ab9-45b1-8e30-e4b619ee5da3',
+  },
+  {
+    key: 'f4a60d83-9e2b-4c15-a7d0-3b8e1f5c9a64',
+    alias: 'seoImage',
+    name: 'Sharing image',
+    description: 'Shown when the page is shared. Leave empty to use the site image.',
+    dataTypeKey: 'ad9f0cf2-bda2-45d5-9ea1-a63cfc873fd3',
+  },
+  {
+    key: '6c3b8e14-2f7a-4d90-b5e1-9a0d4c7f2e75',
+    alias: 'seoCanonical',
+    name: 'Preferred address',
+    description:
+      'Only when the same content lives at another address search engines should use instead.',
+    dataTypeKey: '0cc0eba1-9960-42c9-bf9b-60e150b429ae',
+  },
+  {
+    key: '0e9d5a27-4b1c-4f86-8c32-7d6f0a3e1b86',
+    alias: 'seoNoindex',
+    name: 'Hide from search engines',
+    description: 'Asks search engines to leave this page out of their results.',
+    dataTypeKey: '92897bc6-a5f3-4ffe-ae27-f2e7e33dda49',
+  },
+  {
+    key: 'a7f2c6e9-8d4b-4e31-b0a5-2c9e6f1d3a97',
+    alias: 'seoSitemapHide',
+    name: 'Hide from sitemap',
+    description: 'Leaves this page out of the list of pages offered to search engines.',
+    dataTypeKey: '92897bc6-a5f3-4ffe-ae27-f2e7e33dda49',
+  },
+]
+
+/** The fields a system content type ships with, by the type's key. */
+export function systemContentTypeProperties(key: string): readonly SystemPropertyModel[] {
+  return key.toLowerCase() === SYSTEM_CONTENT_TYPE_KEYS.SeoFields ? SEO_FIELDS_PROPERTIES : []
+}
+
+/**
+ * Why a change to a system content type's fields is refused, or undefined when
+ * it keeps every shipped field's key, alias and data type. Fields may be added,
+ * relabelled, moved, and switched to vary by culture.
+ */
+export function systemFieldViolation(
+  key: string,
+  properties: ReadonlyArray<{ key: string; alias: string; dataTypeKey: string }>,
+): string | undefined {
+  for (const shipped of systemContentTypeProperties(key)) {
+    const found = properties.find((p) => p.key.toLowerCase() === shipped.key)
+    if (
+      !found ||
+      found.alias !== shipped.alias ||
+      found.dataTypeKey.toLowerCase() !== shipped.dataTypeKey
+    )
+      return `The '${shipped.name}' field is provided by Crombolo and cannot be removed or changed. You can add your own fields beside it.`
+  }
+  return undefined
+}
+
+/** How the editor labels a pending element. */
+export function pendingLabel(until: { version: string }): string {
+  return `goes live in ${until.version}`
+}
+
+export interface DataTypeModel {
+  key: string
+  /** Schema files reference a data type by this; Umbraco itself has only key and name. */
+  alias: string | null
+  name: string
+  editorAlias: string
+  editorUiAlias: string | null
+  /** One of ValueStorageType. */
+  dbType: string
+  values: Array<{ alias: string; value: unknown }>
+  parentKey: string | null
+}
+
+export interface ComponentModel {
+  key: string
+  name: string
+  alias: string
+  content: string | null
+  /** Derived from `export const layout = '…'` in the view; the tree hangs children under it. */
+  masterKey?: string | null
+}
+
+/** One entry in a backoffice tree. */
+export interface TreeItem {
+  key: string
+  name: string
+  hasChildren: boolean
+  parentKey: string | null
+  icon: string | null
+  isFolder: boolean
+  isElement?: boolean
+  editorUiAlias?: string | null
+  /** The content type of a blueprint in the blueprint tree. */
+  contentTypeKey?: string | null
+}
+
+export interface Page<T> {
+  total: number
+  items: T[]
+}

package/src/documents.ts

@@ -0,0 +1,124 @@
+/**
+ * The document aggregate.
+ *
+ * Values are a flat list keyed by (alias, culture, segment), matching the wire
+ * format, because that is also how they are stored: one `property_data` row per
+ * combination.
+ */
+export interface DocumentValue {
+  alias: string
+  culture: string | null
+  segment: string | null
+  value: unknown
+  /** Present on responses so the editor knows which editor rendered the value. */
+  editorAlias?: string
+  /** The data type's configuration, on reads; converters that depend on it use it. */
+  config?: Record<string, unknown>
+}
+
+/**
+ * Per-culture state. `NotCreated` means the culture has no name yet;
+ * `PublishedPendingChanges` means the draft differs from what is published.
+ */
+export type VariantState =
+  | 'NotCreated'
+  | 'Draft'
+  | 'Published'
+  | 'PublishedPendingChanges'
+  | 'Trashed'
+
+export interface DocumentVariant {
+  culture: string | null
+  segment: string | null
+  name: string
+  state: VariantState
+  createDate: Date
+  updateDate: Date
+  publishDate: Date | null
+  /** When a scheduled publish of this variant will run. */
+  scheduledPublishDate?: Date | null
+  scheduledUnpublishDate?: Date | null
+}
+
+export interface DocumentAggregate {
+  key: string
+  contentTypeKey: string
+  contentTypeAlias: string
+  contentTypeIcon: string
+  /** The list view the type shows its children in, if any. */
+  contentTypeCollectionKey?: string | null
+  componentKey: string | null
+  parentKey: string | null
+  sortOrder: number
+  isTrashed: boolean
+  /** True when any culture is published. */
+  published: boolean
+  /** True when the draft differs from the published version. */
+  edited: boolean
+  values: DocumentValue[]
+  variants: DocumentVariant[]
+}
+
+/** One property that failed validation, in the terms the editor highlights. */
+export interface DocumentValidationError {
+  alias: string
+  culture: string | null
+  segment: string | null
+  messages: string[]
+}
+
+/** What the content tree shows for a document, beyond the generic tree item. */
+export interface DocumentTreeItem {
+  key: string
+  name: string
+  hasChildren: boolean
+  parentKey: string | null
+  contentTypeKey: string
+  contentTypeCollectionKey?: string | null
+  icon: string
+  isTrashed: boolean
+  createDate: Date
+  ancestorKeys: string[]
+  variants: Array<{ culture: string | null; name: string; state: VariantState }>
+}
+
+/**
+ * A row in the Library tree, which mixes folders and elements: a folder carries
+ * the name and nothing else, so `documentType` is reported as null and its single
+ * variant as `NotCreated` — the contract's own way of saying there is no content
+ * here.
+ */
+export interface ElementTreeItem extends DocumentTreeItem {
+  isFolder: boolean
+}
+
+export interface DocumentVersionSummary {
+  id: string
+  documentKey: string
+  versionDate: Date
+  /** The draft that is currently being edited. */
+  isCurrentDraft: boolean
+  isCurrentPublished: boolean
+  preventCleanup: boolean
+  userKey: string | null
+  culture: string | null
+  /** What made this version: a save, publish, rollback or schema migration. */
+  kind?: 'save' | 'publish' | 'rollback' | 'migrate'
+}
+
+/** A value keyed for lookup, so variance handling stays explicit. */
+export function valueKey(alias: string, culture: string | null, segment: string | null): string {
+  return `${alias}|${culture ?? ''}|${segment ?? ''}`
+}
+
+/**
+ * The culture a value belongs to, honouring the effective variance: a value sent
+ * with a culture for an invariant property is stored invariant, which is what
+ * keeps a type change from orphaning data.
+ */
+export function normaliseValueCulture(
+  culture: string | null,
+  propertyVariesByCulture: boolean,
+): string | null {
+  return propertyVariesByCulture ? culture : null
+}