@symbo.ls/utils 3.2.3 → 3.14.0

package/package.json

@@ -1,31 +1,47 @@
 {
   "name": "@symbo.ls/utils",
-  "version": "3.2.3",
-  "author": "symbo.ls",
+  "version": "3.14.0",
+  "license": "CC-BY-NC-4.0",
+  "type": "module",
+  "module": "./index.js",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js",
+    "./methods": "./methods.js",
+    "./*.js": "./*.js",
+    "./*": "./*.js",
+    "./package.json": "./package.json"
+  },
+  "source": "index.js",
   "files": [
-    "src",
-    "dist"
+    "dist",
+    "*.js"
   ],
-  "main": "src/index.js",
-  "type": "module",
-  "module": "src/index.js",
-  "unpkg": "dist/iife/index.js",
-  "jsdelivr": "dist/iife/index.js",
-  "exports": "./dist/cjs/index.js",
-  "source": "src/index.js",
-  "publishConfig": {},
   "scripts": {
     "copy:package:cjs": "cp ../../build/package-cjs.json dist/cjs/package.json",
-    "build:esm": "npx cross-env NODE_ENV=$NODE_ENV npx esbuild ./src/*.js ./src/**/*.js --target=es2017 --format=esm --outdir=dist/esm",
-    "build:cjs": "npx cross-env NODE_ENV=$NODE_ENV npx esbuild ./src/*.js ./src/**/*.js --target=node16 --format=cjs --outdir=dist/cjs --bundle",
-    "build:iife": "npx cross-env NODE_ENV=$NODE_ENV npx esbuild ./src/index.js --target=es2017 --format=iife --outdir=dist/iife --bundle --minify",
-    "build": "npm run build:cjs",
-    "prepublish": "rimraf -I dist && npm run build && npm run copy:package:cjs"
+    "build:esm": "NODE_ENV=$NODE_ENV esbuild *.js --target=es2020 --format=esm --outdir=dist/esm --define:process.env.NODE_ENV=process.env.NODE_ENV",
+    "build:cjs": "NODE_ENV=$NODE_ENV esbuild *.js --target=node18 --format=cjs --outdir=dist/cjs --define:process.env.NODE_ENV=process.env.NODE_ENV",
+    "build": "node ../../build/build.js",
+    "prepublish": "npm run build && npm run copy:package:cjs",
+    "build:iife": "NODE_ENV=$NODE_ENV esbuild index.js --bundle --target=es2020 --format=iife --global-name=DomqlUtils --outfile=dist/iife/index.js --define:process.env.NODE_ENV=process.env.NODE_ENV --external:@symbo.ls/element"
+  },
+  "gitHead": "9fc1b79b41cdc725ca6b24aec64920a599634681",
+  "peerDependencies": {
+    "@symbo.ls/fetch": "^3.14.0"
+  },
+  "peerDependenciesMeta": {
+    "@symbo.ls/fetch": {
+      "optional": true
+    }
   },
-  "license": "ISC",
-  "dependencies": {
-    "@domql/event": "^3.2.3",
-    "@domql/utils": "^3.2.3"
+  "devDependencies": {
+    "@babel/core": "^7.26.0"
   },
-  "gitHead": "9fc1b79b41cdc725ca6b24aec64920a599634681"
+  "browser": "./index.js",
+  "unpkg": "./dist/iife/index.js",
+  "jsdelivr": "./dist/iife/index.js",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/projectKeys.js

@@ -0,0 +1,30 @@
+// Top-level keys that must never land on `ProjectData.data.*` under any
+// circumstance. Two categories are universal and truly non-negotiable:
+//
+//   - JS-level pollution: assigning to `__proto__` / `constructor` /
+//     `prototype` can mutate the global prototype chain.
+//   - Mongo / server-owned metadata: `_id` / `__v` / `id` / `createdAt` /
+//     `updatedAt` / `schema` are allocated or maintained by the server and
+//     must be treated as opaque identity. Clients that accidentally send
+//     them would either overwrite server state or corrupt the doc.
+//
+// That's all that belongs here. The larger set of "Project-schema-owned"
+// fields (access, visibility, members, subscription, etc.) is derived on
+// the server at runtime from `Project.schema.paths`, not enumerated. See
+// the server's `services/ProjectContentGuard.js` for that derivation.
+// The CLI only needs the universal floor.
+
+export const UNIVERSAL_RESERVED_KEYS = new Set([
+  '__proto__',
+  'constructor',
+  'prototype',
+  '_id',
+  '__v',
+  'id',
+  'createdAt',
+  'updatedAt',
+  'schema',
+])
+
+export const isUniversallyReservedKey = (key) =>
+  typeof key === 'string' && UNIVERSAL_RESERVED_KEYS.has(key)

package/props.js

@@ -0,0 +1,327 @@
+'use strict'
+
+import { DOMQ_PROPERTIES, PROPS_METHODS } from './keys.js'
+import { addEventFromProps } from './events.js'
+import { deepClone, deepMerge, exec } from './object.js'
+import { is, isArray, isFunction, isObject, isObjectLike } from './types.js'
+import { lowercaseFirstLetter } from './string.js'
+import { hasHandlerPlugin } from './function.js'
+
+const RE_UPPER = /^[A-Z]/
+const RE_DIGITS = /^\d+$/
+
+// Characters that mark css-in-props selectors (pseudo-selectors, media queries, etc.)
+// These properties must always live in props so useCssInProps() can process them
+const CSS_SELECTOR_PREFIXES = new Set([':', '@', '[', '*', '+', '~', '&', '>', '$', '-', '.', '!'])
+
+const ELEMENT_INDICATOR_KEYS = new Set([
+  'extend', 'props', 'text', 'tag', 'on', 'if', 'childExtend',
+  'children', 'childrenAs', 'state', 'html', 'attr',
+  'define', 'content'
+])
+const looksLikeElement = (value) => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false
+  for (const k in value) {
+    if (ELEMENT_INDICATOR_KEYS.has(k)) return true
+    if (RE_UPPER.test(k)) return true
+  }
+  return false
+}
+
+export const createProps = (element, parent, key) => {
+  const { props, __ref: ref } = element
+  ref.__propsStack = []
+  if (props) ref.__initialProps = props
+  else return {}
+  if (!isObjectLike(props)) {
+    ref.__propsStack.push(props)
+    return {}
+  }
+  return { ...props }
+}
+
+export function pickupPropsFromElement (obj, opts = {}) {
+  const cachedKeys = opts.cachedKeys || []
+
+  for (const key in obj) {
+    const value = obj[key]
+
+    // Move top-level onXxx handlers directly into on.xxx (v3 style)
+    const isOnKey = key.length > 2 && key.charCodeAt(0) === 111 && key.charCodeAt(1) === 110 && key[2] === key[2].toUpperCase()
+    const isEventHandler = isOnKey && (isFunction(value) || (value != null && hasHandlerPlugin(this.context)))
+    if (isEventHandler) {
+      const eventName = lowercaseFirstLetter(key.slice(2))
+      if (obj.on) obj.on[eventName] = value
+      delete obj[key]
+      continue
+    }
+
+    // childProps is a framework property that must always live in props
+    // even though its value may contain uppercase keys (Icon, Hgroup, etc.)
+    if (key === 'childProps') {
+      obj.props[key] = value
+      delete obj[key]
+      cachedKeys.push(key)
+      continue
+    }
+
+    // Check define handlers - keys with define handlers must stay at root
+    // for throughInitialDefine to process them
+    const defineValue = this.define?.[key]
+    const globalDefineValue = this.context?.define?.[key]
+    const hasDefine = isObject(defineValue) || isFunction(defineValue)
+    const hasGlobalDefine = isObject(globalDefineValue) || isFunction(globalDefineValue)
+    if (hasDefine || hasGlobalDefine) continue
+
+    // CSS-in-props selectors (:after, :hover, @mobileS, etc.) must always
+    // live in props so useCssInProps() can process them via transformersByPrefix
+    const firstChar = key.charAt(0)
+    if (CSS_SELECTOR_PREFIXES.has(firstChar)) {
+      obj.props[key] = value
+      delete obj[key]
+      cachedKeys.push(key)
+      continue
+    }
+
+    const isElement = RE_UPPER.test(key) || RE_DIGITS.test(key) || looksLikeElement(value)
+    const isBuiltin = DOMQ_PROPERTIES.has(key)
+
+    // If it's not a special case, move to props
+    // Don't overwrite props already set by local definition (e.g. from childrenAs: 'props')
+    if (!isElement && !isBuiltin) {
+      if (!(key in obj.props)) obj.props[key] = value
+      delete obj[key]
+      cachedKeys.push(key)
+    }
+  }
+
+  return obj
+}
+
+export function pickupElementFromProps (obj = this, opts) {
+  const cachedKeys = opts.cachedKeys || []
+
+  for (const key in obj.props) {
+    const value = obj.props[key]
+
+    // Handle event handlers (functions, or plugin schemas when plugins are active)
+    const isEvent = key.length > 2 && key.charCodeAt(0) === 111 && key.charCodeAt(1) === 110
+    const isHandler = isFunction(value) || (value != null && hasHandlerPlugin(this.context))
+
+    if (isEvent && isHandler) {
+      addEventFromProps(key, obj)
+      delete obj.props[key]
+      continue
+    }
+
+    // Skip if key was originally from obj
+    if (cachedKeys.includes(key)) continue
+
+    // childProps must stay in props - it's consumed by inheritParentProps
+    if (key === 'childProps') continue
+
+    // CSS-in-props selectors must stay in props
+    const firstChar = key.charAt(0)
+    if (CSS_SELECTOR_PREFIXES.has(firstChar)) continue
+
+    const defineValue = this.define?.[key]
+    const globalDefineValue = this.context?.define?.[key]
+    const hasDefine = isObject(defineValue) || isFunction(defineValue)
+    const hasGlobalDefine = isObject(globalDefineValue) || isFunction(globalDefineValue)
+    const isElement = RE_UPPER.test(key) || RE_DIGITS.test(key)
+    const isBuiltin = DOMQ_PROPERTIES.has(key)
+
+    // Move qualifying properties back to obj root
+    if (isElement || isBuiltin || hasDefine || hasGlobalDefine) {
+      // Don't overwrite if root already has this property explicitly set
+      // Exception: null values should override to allow nullifying children from props
+      if (obj[key] === undefined || value === null) {
+        obj[key] = value
+        if (obj.props) delete obj.props[key]
+      }
+      // If root already has the property (e.g. from extends), keep it in props
+      // so functions like `text: ({ props }) => props.text` can still access it
+    }
+  }
+
+  return obj
+}
+
+// Helper function to maintain compatibility with original propertizeElement
+export function propertizeElement (element = this) {
+  const cachedKeys = []
+  pickupPropsFromElement.call(this, element, { cachedKeys })
+  pickupElementFromProps.call(this, element, { cachedKeys })
+  return element
+}
+
+export function propertizeUpdate (params = {}) {
+  if (!params.on) params.on = {}
+  if (!params.props) params.props = {}
+  return propertizeElement.call(this, params)
+}
+
+export const objectizeStringProperty = propValue => {
+  if (is(propValue)('string', 'number')) {
+    return { inheritedString: propValue }
+  }
+  return propValue
+}
+
+export const propExists = (prop, stack) => {
+  if (!prop || !stack.length) return false
+  return stack.includes(prop)
+}
+
+export const inheritParentProps = (element, parent) => {
+  const { __ref: ref } = element
+  const propsStack = ref.__propsStack || []
+  const parentProps = parent.props
+
+  if (!parentProps) return propsStack
+
+  const matchParentKeyProps = parentProps[element.key]
+  const matchParentChildProps = parentProps.childProps || parent.childProps
+
+  // Order matters: key-specific props should be added after childProps
+  const ignoreChildProps = element.props?.ignoreChildProps
+  if (matchParentChildProps && !ignoreChildProps) {
+    const childProps = objectizeStringProperty(matchParentChildProps)
+    propsStack.unshift(childProps)
+  }
+
+  if (matchParentKeyProps) {
+    const keyProps = objectizeStringProperty(matchParentKeyProps)
+    propsStack.unshift(keyProps)
+  }
+
+  return propsStack
+}
+
+export function update (props, options) {
+  const element = this.__element
+  element.update({ props }, options)
+}
+
+// TODO: check bind with promise
+export function setPropsPrototype (element) {
+  const methods = { update: update.bind(element.props), __element: element }
+  Object.setPrototypeOf(element.props, methods)
+}
+
+export const removeDuplicateProps = propsStack => {
+  const seen = new Set()
+
+  return propsStack.filter(prop => {
+    if (!prop || PROPS_METHODS.has(prop)) return false
+    if (seen.has(prop)) return false
+    seen.add(prop)
+    return true
+  })
+}
+
+export const syncProps = (propsStack, element, opts) => {
+  element.props = propsStack.reduce((mergedProps, v) => {
+    if (PROPS_METHODS.has(v)) return mergedProps
+    while (isFunction(v)) v = exec(v, element)
+    return deepMerge(mergedProps, deepClone(v, { exclude: PROPS_METHODS }))
+  }, {})
+  setPropsPrototype(element)
+  return element.props
+}
+
+export const createPropsStack = (element, parent) => {
+  const { props, __ref: ref } = element
+
+  // Start with parent props
+  let propsStack = ref.__propsStack || []
+
+  // Get parent props
+  if (parent?.props) {
+    const parentStack = inheritParentProps(element, parent)
+    propsStack = [...parentStack]
+  }
+
+  // Add current props
+  if (isObject(props)) propsStack.push(props)
+  else if (props === 'inherit' && parent?.props) propsStack.push(parent.props)
+  else if (props) propsStack.push(props)
+
+  // Add extends props
+  if (isArray(ref.__extendsStack)) {
+    for (let i = 0; i < ref.__extendsStack.length; i++) {
+      const _extends = ref.__extendsStack[i]
+      if (_extends.props && _extends.props !== props) {
+        propsStack.push(_extends.props)
+      }
+    }
+  }
+
+  // Remove duplicates and update reference
+  ref.__propsStack = removeDuplicateProps(propsStack)
+  return ref.__propsStack
+}
+
+export const applyProps = (element, parent) => {
+  const { __ref: ref } = element
+
+  // Create a fresh props stack
+  const propsStack = createPropsStack(element, parent)
+
+  // Update the element
+  if (propsStack.length) {
+    syncProps(propsStack, element)
+  } else {
+    ref.__propsStack = []
+    element.props = {}
+  }
+}
+
+export const initProps = function (element, parent, options) {
+  const { __ref: ref } = element
+
+  if (ref.__if) applyProps(element, parent)
+  else {
+    try {
+      applyProps(element, parent)
+    } catch (e) {
+      if (element.context?.designSystem?.verbose) {
+        console.warn('initProps error at', ref.path?.join('.'), e)
+      }
+      element.props = {}
+      ref.__propsStack = []
+    }
+  }
+
+  setPropsPrototype(element)
+
+  return element
+}
+
+export const updateProps = (newProps, element, parent) => {
+  const { __ref: ref } = element
+  const propsStack = ref.__propsStack || []
+
+  // Create a new array to avoid mutating the original
+  let newStack = [...propsStack]
+
+  // Add parent props first if they exist
+  const parentProps = inheritParentProps(element, parent)
+  if (parentProps.length) {
+    newStack = [...parentProps, ...newStack]
+  }
+
+  // Add new props if they exist
+  if (newProps) {
+    newStack = [newProps, ...newStack]
+  }
+
+  // Clean up duplicates
+  ref.__propsStack = removeDuplicateProps(newStack)
+
+  if (ref.__propsStack.length) {
+    syncProps(ref.__propsStack, element)
+  }
+
+  return element
+}

package/{src/scaling.js → scaling.js}

@@ -1,6 +1,6 @@
 'use strict'
 
-import { isObject, isArray } from '@domql/utils'
+import { isObject, isArray } from './types.js'
 
 export const findClosestNumber = (number, arr) => {
   return (isArray(arr) ? arr : Object.values(arr)).reduce((prev, curr) => {

package/scope.js

@@ -0,0 +1,32 @@
+'use strict'
+
+// Create scope - shared object across the elements to the own or the nearest parent
+// Prototype chain: own scope → parent scope → ... → root scope → globalScope
+export const createScope = (element, parent) => {
+  const { __ref: ref } = element
+  const context = element.context || parent.context || ref.root?.context
+
+  // Ensure globalScope exists on context
+  if (context && !context.globalScope) context.globalScope = {}
+
+  const parentScope = parent.scope || ref.root?.scope
+  const globalScope = context?.globalScope
+
+  if (!element.scope) {
+    // No own scope defined — inherit parent scope directly
+    if (parentScope) {
+      element.scope = parentScope
+    } else if (globalScope) {
+      // No parent scope either — create root-level scope with globalScope as prototype
+      element.scope = Object.create(globalScope)
+    } else {
+      element.scope = {}
+    }
+  } else if (typeof element.scope === 'object' && element.scope !== null) {
+    // Element defines its own scope — chain prototype to parent scope (or globalScope)
+    if (Object.getPrototypeOf(element.scope) === Object.prototype) {
+      const proto = parentScope || globalScope
+      if (proto) Object.setPrototypeOf(element.scope, proto)
+    }
+  }
+}

package/sharedLibraries.js

@@ -0,0 +1,184 @@
+'use strict'
+
+import { isObject, isString } from './types.js'
+
+const DEFAULT_LIBRARY_OWNER = 'system'
+
+const KV_BASE_URL = 'https://smbls-kv.nika-980.workers.dev'
+const API_BASE_URL = 'https://api.symbols.app'
+
+/**
+ * Normalize any library key format to canonical { owner, key, full } form.
+ *
+ * Accepts:
+ *   "system/default"          → { owner: "system",  key: "default",  full: "system/default" }
+ *   "default"                 → { owner: "system",  key: "default",  full: "system/default" }
+ *   "default.symbo.ls"        → { owner: "system",  key: "default",  full: "system/default" }
+ *   "myorg/mylib"             → { owner: "myorg",   key: "mylib",    full: "myorg/mylib" }
+ */
+export function normalizeLibraryKey (raw) {
+  const s = String(raw || '').trim()
+  if (!s) return { owner: DEFAULT_LIBRARY_OWNER, key: '', full: '' }
+
+  let owner = null
+  let key = s
+
+  if (s.includes('/')) {
+    const idx = s.indexOf('/')
+    owner = s.slice(0, idx)
+    key = s.slice(idx + 1)
+  }
+
+  // Strip deprecated .symbo.ls suffix
+  key = key.replace(/\.symbo\.ls$/iu, '')
+
+  if (!owner) owner = DEFAULT_LIBRARY_OWNER
+
+  const full = key ? `${owner}/${key}` : ''
+
+  return { owner, key, full }
+}
+
+/**
+ * Recursively set defaults: copy keys from source into target
+ * only where target is missing them. Non-destructive.
+ */
+export const deepDefaults = (target, source) => {
+  for (const k in source) {
+    if (!(k in target)) {
+      target[k] = source[k]
+    } else if (isObject(target[k]) && isObject(source[k])) {
+      deepDefaults(target[k], source[k])
+    }
+  }
+}
+
+/**
+ * Merge an array of shared library objects into a context.
+ * - designSystem: deep defaults (non-destructive recursive)
+ * - other object keys (components, pages, etc.): shallow add missing
+ * - new top-level keys: copy from library
+ */
+export const mergeSharedLibraries = (context, libraries) => {
+  if (!libraries || !libraries.length) return
+  for (let i = 0; i < libraries.length; i++) {
+    const sharedLib = libraries[i]
+    if (!isObject(sharedLib)) continue
+    for (const key in sharedLib) {
+      if (!Object.prototype.hasOwnProperty.call(sharedLib, key)) continue
+      if (isObject(sharedLib[key]) && isObject(context[key])) {
+        if (key === 'designSystem') {
+          deepDefaults(context[key], sharedLib[key])
+        } else {
+          for (const k in sharedLib[key]) {
+            if (!(k in context[key])) context[key][k] = sharedLib[key][k]
+          }
+        }
+      } else if (!(key in context)) {
+        context[key] = sharedLib[key]
+      }
+    }
+  }
+}
+
+/**
+ * Fetch a single library's data by identifier.
+ *
+ * @param {string} identifier - "owner/key" format
+ * @param {object} [opts]
+ * @param {string} [opts.provider='kv'] - 'kv' or 'api'
+ * @param {string} [opts.env='production'] - KV environment
+ * @param {string} [opts.kvBaseUrl] - Override KV base URL
+ * @param {string} [opts.apiBaseUrl] - Override API base URL
+ * @returns {Promise<object|null>} Library data or null
+ */
+export async function fetchLibraryData (identifier, opts = {}) {
+  const provider = opts.provider || 'kv'
+
+  if (provider === 'api') {
+    return fetchLibraryFromApi(identifier, opts)
+  }
+
+  // KV provider (default)
+  const result = await fetchLibraryFromKv(identifier, opts)
+  if (result) return result
+
+  // Fallback to API if KV returns nothing
+  return fetchLibraryFromApi(identifier, opts)
+}
+
+async function fetchLibraryFromKv (identifier, opts = {}) {
+  const baseUrl = opts.kvBaseUrl || KV_BASE_URL
+  const env = opts.env || 'production'
+  const url = `${baseUrl}/kv/${encodeURIComponent(identifier)}?env=${env}`
+  try {
+    const response = await fetch(url, { method: 'GET' })
+    if (!response.ok) return null
+    const json = await response.json()
+    return json?.value || null
+  } catch {
+    return null
+  }
+}
+
+async function fetchLibraryFromApi (identifier, opts = {}) {
+  const baseUrl = opts.apiBaseUrl || API_BASE_URL
+  const { key } = normalizeLibraryKey(identifier)
+  try {
+    // Resolve library ID from the available list
+    const listUrl = `${baseUrl}/core/projects/libraries/available?search=${encodeURIComponent(key)}&limit=10`
+    const listRes = await fetch(listUrl, { method: 'GET' })
+    if (!listRes.ok) return null
+    const listJson = await listRes.json()
+    const items = listJson?.items || listJson?.data || (Array.isArray(listJson) ? listJson : [])
+    const match = items.find(lib => {
+      const { key: libKey } = normalizeLibraryKey(lib?.key)
+      return libKey.toLowerCase() === key.toLowerCase()
+    })
+    if (!match?.id && !match?._id) return null
+    const libId = match.id || match._id
+
+    // Fetch full library data
+    const dataUrl = `${baseUrl}/core/projects/${encodeURIComponent(libId)}/data?branch=main`
+    const dataRes = await fetch(dataUrl, { method: 'GET' })
+    if (!dataRes.ok) return null
+    const dataJson = await dataRes.json()
+    return dataJson?.data || dataJson || null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Resolve an array that may contain strings and/or objects.
+ * Strings are treated as library identifiers and fetched.
+ * Objects pass through unchanged.
+ *
+ * @param {Array<string|object>} libraries - Mixed array
+ * @param {object} [opts] - Options passed to fetchLibraryData
+ * @returns {Promise<object[]>} Array of resolved library objects
+ */
+export async function resolveSharedLibraries (libraries, opts = {}) {
+  if (!libraries || !libraries.length) return []
+  const resolved = await Promise.all(
+    libraries.map(async (entry) => {
+      if (isObject(entry)) return entry
+      if (isString(entry)) {
+        const { full } = normalizeLibraryKey(entry)
+        if (!full) return null
+        try {
+          const data = await fetchLibraryData(full, opts)
+          if (!data) {
+            console.warn(`[smbls] Shared library "${full}" not found`)
+          }
+          return data
+        } catch (e) {
+          console.warn(`[smbls] Failed to fetch shared library "${full}":`, e.message)
+          return null
+        }
+      }
+      return null
+    })
+  )
+  return resolved.filter(Boolean)
+}