@symbo.ls/utils 3.2.3 → 3.14.1

package/LICENSE

@@ -1,21 +1,34 @@
-MIT License
+Creative Commons Attribution-NonCommercial 4.0 International License
 
 Copyright (c) 2023 symbo.ls
 
-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:
+This work is licensed under the Creative Commons Attribution-NonCommercial
+4.0 International License. To view a copy of this license, visit
+https://creativecommons.org/licenses/by-nc/4.0/ or send a letter to
+Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+You are free to:
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  Share — copy and redistribute the material in any medium or format
+  Adapt — remix, transform, and build upon the material
+
+Under the following terms:
+
+  Attribution — You must give appropriate credit, provide a link to the
+  license, and indicate if changes were made. You may do so in any
+  reasonable manner, but not in any way that suggests the licensor endorses
+  you or your use.
+
+  NonCommercial — You may not use the material for commercial purposes.
+
+  No additional restrictions — You may not apply legal terms or
+  technological measures that legally restrict others from doing anything
+  the license permits.
+
+THE WORK 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.
+OUT OF OR IN CONNECTION WITH THE WORK OR THE USE OR OTHER DEALINGS IN THE
+WORK.

package/README.md

@@ -0,0 +1,106 @@
+# @domql/utils
+
+Core utility functions for the DOMQL element system.
+
+## Propertization (`props.js`)
+
+The propertization system normalizes element definitions by classifying keys into child elements, framework keys, and CSS/design-token properties.
+
+In v3.14, properties go directly on the element (no `props:` wrapper needed). The propertization system operates internally to route properties to the atomic CSS engine (`@symbo.ls/css`).
+
+### Two-phase process
+
+1. **`pickupPropsFromElement`** — Scans element root keys and classifies non-element, non-builtin keys for CSS processing
+2. **`pickupElementFromProps`** — Scans classified keys and moves element-like or builtin keys back to the element root
+
+### Key classification rules
+
+In v3.14, properties go directly on the element (no `props:` wrapper needed). The propertization system still operates internally for the CSS engine.
+
+| Pattern | Classification | Example |
+|---------|---------------|---------|
+| Starts with uppercase | Child element | `Header`, `Button`, `Nav` |
+| Numeric key | Child element | `0`, `1`, `2` |
+| In `DOMQ_PROPERTIES` | Framework builtin | `tag`, `extends`, `state` |
+| In `CSS_SELECTOR_PREFIXES` | CSS-in-props | `:hover`, `@mobileS`, `$isActive` |
+| Has define handler | Define key (stays at root) | `$router`, deprecated: `$propsCollection` |
+| `childProps` | Always in props | `childProps` |
+| `onXxx` + function | Event/lifecycle handler | `onClick`, `onSubmit`, `onInit`, `onRender` |
+| Everything else | CSS/design token prop | `padding`, `theme`, `color` |
+
+### CSS_SELECTOR_PREFIXES
+
+```javascript
+const CSS_SELECTOR_PREFIXES = new Set([
+  ':', '@', '[', '*', '+', '~', '&', '>', '$', '-', '.', '!'
+])
+```
+
+These single-character prefixes identify keys that should be processed by `css-in-props` via `transformersByPrefix`. When a key starts with one of these characters, it gets moved into `props`.
+
+### Define-awareness
+
+The `$` prefix is shared between css-in-props conditionals (`$isActive`) and define handlers (built-in `$router`). The propertization checks for define handlers before applying prefix rules to ensure define keys stay at the element root.
+
+### childProps handling
+
+`childProps` is a framework property that configures child element properties. Its value may contain uppercase keys that look like child elements but are not:
+
+```javascript
+// childProps: { Icon: { name: 'star' }, Hgroup: { ... } }
+// The uppercase keys inside are NOT child elements — they target named children
+```
+
+### ignoreChildProps
+
+When set on `element.props`, prevents the element from inheriting `childProps` from its parent via `inheritParentProps`. Used by fragment elements to avoid double-application of childProps (since fragments explicitly forward childProps to their children).
+
+## Scope (`scope.js`)
+
+### `createScope(element, parent)`
+
+Creates the scope for an element with prototype-chain inheritance:
+
+```
+el.scope → parent.scope → grandparent.scope → ... → root.scope → context.globalScope
+```
+
+**Behavior:**
+- **No own scope** — element inherits `parent.scope` directly (same reference)
+- **Own scope defined** (`scope: { myVar: 1 }`) — prototype is set to parent's scope, chaining up to `globalScope`
+- **No parent/root scope** — new scope created with `Object.create(context.globalScope)`
+- **No context** — plain `{}`
+
+### `globalScope`
+
+Automatically initialized as `context.globalScope = {}` if context exists. Sits at the bottom of every scope prototype chain, making its properties accessible from any element via `el.scope.X`.
+
+```js
+// In context or set by the serialization pipeline:
+context.globalScope = {
+  API_URL: 'https://api.example.com',
+  helpers: { capitalize: (s) => s[0].toUpperCase() + s.slice(1) }
+}
+
+// Accessible from any element — no import needed:
+onClick: (e, el) => fetch(el.scope.API_URL)
+
+// Also directly accessible:
+el.context.globalScope.API_URL
+```
+
+When a component defines its own scope, properties shadow parent/global values but the chain remains walkable:
+
+```js
+// Parent: scope = { theme: 'dark' }
+// Child:  scope = { count: 0 }
+// el.scope.count → 0      (own)
+// el.scope.theme → 'dark'  (parent, via prototype)
+// el.scope.API_URL → '...' (globalScope, via prototype chain)
+```
+
+## Key Sets (`keys.js`)
+
+- **`DOMQ_PROPERTIES`** — Framework-level keys that stay at element root
+- **`PROPS_METHODS`** — Keys on the props prototype (update, __element)
+- **`STATE_METHODS`** — State management methods (update, parse, set, toggle, etc.)

package/array.js

@@ -0,0 +1,162 @@
+'use strict'
+
+import { deepClone, deepMerge } from './object.js'
+import { isArray, isNumber, isString } from './types.js'
+
+export const arrayContainsOtherArray = (arr1, arr2) => {
+  return arr2.every(val => arr1.includes(val))
+}
+
+export const getFrequencyInArray = (arr, value) => {
+  let count = 0
+  for (let i = 0; i < arr.length; i++) {
+    if (arr[i] === value) count++
+  }
+  return count
+}
+
+export const removeFromArray = (arr, index) => {
+  if (isString(index)) index = parseInt(index)
+  if (isNumber(index)) {
+    if (index < 0 || index >= arr.length || isNaN(index)) {
+      throw new Error('Invalid index')
+    }
+    arr.splice(index, 1)
+  } else {
+    throw new Error('Invalid index')
+  }
+  return arr
+}
+
+export const swapItemsInArray = (arr, i, j) => {
+  if (i < 0 || j < 0 || i >= arr.length || j >= arr.length) return
+  ;[arr[i], arr[j]] = [arr[j], arr[i]]
+}
+
+export const joinArrays = (...arrays) => {
+  return [].concat(...arrays)
+}
+
+/**
+ * Merges array extendtypes
+ */
+export const unstackArrayOfObjects = (arr, exclude = []) => {
+  return arr.reduce(
+    (a, c) => deepMerge(a, deepClone(c, { exclude }), exclude),
+    {}
+  )
+}
+
+export const cutArrayBeforeValue = (arr, value) => {
+  const index = arr.indexOf(value)
+  if (index !== -1) {
+    return arr.slice(0, index)
+  }
+  return arr
+}
+
+export const cutArrayAfterValue = (arr, value) => {
+  if (!isArray(arr)) return
+  const index = arr.indexOf(value)
+  if (index !== -1) {
+    return arr.slice(index + 1)
+  }
+  return arr
+}
+
+export const removeValueFromArray = (arr, value) => {
+  const index = arr.indexOf(value)
+  if (index > -1) {
+    const newArray = [...arr]
+    newArray.splice(index, 1)
+    return newArray
+  }
+  return arr
+}
+
+export const removeValueFromArrayAll = (arr, value) => {
+  return arr.filter(item => item !== value)
+}
+
+export const addItemAfterEveryElement = (array, item) => {
+  // Create a new array to hold the result
+  const result = []
+
+  // Loop through the input array
+  for (let i = 0; i < array.length; i++) {
+    // Add the current element to the result array
+    result.push(array[i])
+
+    // If it's not the last element, add the item
+    if (i < array.length - 1) {
+      result.push(item)
+    }
+  }
+
+  return result
+}
+
+export const reorderArrayByValues = (array, valueToMove, insertBeforeValue) => {
+  const newArray = [...array] // Create a copy of the original array
+  const indexToMove = newArray.indexOf(valueToMove) // Find the index of the value to move
+  const indexToInsertBefore = newArray.indexOf(insertBeforeValue) // Find the index to insert before
+  if (indexToMove !== -1 && indexToInsertBefore !== -1) {
+    const removedItem = newArray.splice(indexToMove, 1)[0] // Remove the item to move
+    const insertIndex =
+      indexToInsertBefore < indexToMove
+        ? indexToInsertBefore
+        : indexToInsertBefore + 1 // Adjust insert index
+    newArray.splice(insertIndex, 0, removedItem) // Insert the removed item before the specified value
+  }
+  return newArray
+}
+
+export const arraysEqual = (arr1, arr2) => {
+  if (arr1.length !== arr2.length) {
+    return false
+  }
+
+  for (let i = 0; i < arr1.length; i++) {
+    if (arr1[i] !== arr2[i]) {
+      return false
+    }
+  }
+
+  return true
+}
+
+// Using filter and includes
+export const filterArrays = (sourceArr, excludeArr) => {
+  return sourceArr.filter(item => !excludeArr.includes(item))
+}
+
+// Using Set for better performance with large arrays
+export const filterArraysFast = (sourceArr, excludeArr) => {
+  const excludeSet = new Set(excludeArr)
+  return sourceArr.filter(item => !excludeSet.has(item))
+}
+
+export const checkIfStringIsInArray = (string, arr) => {
+  if (!string) return 0
+  let count = 0
+  for (let i = 0; i < arr.length; i++) {
+    if (string.includes(arr[i])) count++
+  }
+  return count
+}
+
+export const removeDuplicatesInArray = arr => {
+  if (!isArray(arr)) return arr
+  return [...new Set(arr)]
+}
+
+export const addProtoToArray = (state, proto) => {
+  for (const key in proto) {
+    Object.defineProperty(state, key, {
+      value: proto[key],
+      enumerable: false, // Set this to true if you want the method to appear in for...in loops
+      configurable: true, // Set this to true if you want to allow redefining/removing the property later
+      writable: true // Set this to true if you want to allow changing the function later
+    })
+  }
+}

package/assets.js

@@ -0,0 +1,117 @@
+'use strict'
+
+/**
+ * Asset resolution + variant emitters shared across media components
+ * (Img, Video, Audio, AssetPicture, …) and any plugin that reads from
+ * `context.assets` / `context.files`.
+ *
+ * Components don't care WHERE an asset lives — runner-discovered file,
+ * cloud-uploaded entry, or hand-authored URL — they call `resolveAsset`
+ * with the element and get back a normalized shape (or null).
+ */
+
+/**
+ * Look up `el.src` in `el.context.assets`, falling back to
+ * `el.context.files`. Normalizes the two source-side shapes:
+ *
+ *   - **String URL** — cloud-resolved or hand-authored bare URLs.
+ *     Returns `{ src, type: null, variants: null }`. Components emit
+ *     a single-source tag with no `<source>` chain and no `srcset`.
+ *
+ *   - **Manifest object** — `{ src, type, category, variants[] }`.
+ *     Shape produced by the runner's filename-based asset walker
+ *     (and any cloud provider that exposes variant metadata). Returned
+ *     verbatim.
+ *
+ * Anything else (object without `.src`, missing key, non-string `el.src`)
+ * returns null. Components fall through to plain markup using `el.src`.
+ */
+export const resolveAsset = (el) => {
+  const key = el && el.src
+  if (!key || typeof key !== 'string') return null
+  const ctx = el.context
+  if (!ctx) return null
+  const found = (ctx.assets && ctx.assets[key]) || (ctx.files && ctx.files[key])
+  if (!found) return null
+  if (typeof found === 'string') {
+    return { src: found, type: null, variants: null }
+  }
+  if (typeof found === 'object' && typeof found.src === 'string') {
+    return found
+  }
+  return null
+}
+
+/**
+ * Render an `srcset` value from a list of variants.
+ *
+ * Width descriptors take precedence over scale when present. Bare 1x
+ * entries are kept or dropped based on context:
+ *
+ *   - `<source srcset>` (`keepOneX: true`, default): bare 1x URLs are
+ *     required because `<source>` has no `src` fallback — without a 1x
+ *     entry the source can't match default-DPR clients.
+ *   - `<img srcset>` (`keepOneX: false`): bare 1x URLs are redundant
+ *     because the `src` attribute already covers them.
+ */
+export const srcsetFor = (variants, { keepOneX = true } = {}) => {
+  if (!Array.isArray(variants) || !variants.length) return ''
+  const usingWidth = variants.some((v) => typeof v.width === 'number')
+  const parts = []
+  for (const v of variants) {
+    if (usingWidth && typeof v.width === 'number') {
+      parts.push(`${v.src} ${v.width}w`)
+    } else if (!usingWidth) {
+      if (v.scale === 1 && keepOneX) parts.push(v.src)
+      else if (v.scale && v.scale !== 1) parts.push(`${v.src} ${v.scale}x`)
+    }
+  }
+  return parts.join(', ')
+}
+
+/**
+ * Same-format srcset for an `<img>` tag — filtered to the asset's
+ * primary format and with `keepOneX: false`. Used by `<Img>`.
+ */
+export const buildImgSrcset = (asset) => {
+  if (!asset || !Array.isArray(asset.variants)) return ''
+  const sameFormat = asset.variants.filter((v) => v.format === asset.type)
+  return srcsetFor(sameFormat, { keepOneX: false })
+}
+
+/**
+ * Build the children of an `<picture>` (or any format-negotiating tag)
+ * from an asset manifest: one `<source type="…" srcset="…">` per non-
+ * primary format, plus a trailing `<img>` for the primary format.
+ *
+ * Returns a list of DOMQL element configs. When the asset has no
+ * variants array (cloud-string URL or single-source entry), returns
+ * just the `<img>`.
+ */
+export const buildSourcesAndImg = (asset, alt) => {
+  if (!asset || typeof asset !== 'object' || typeof asset.src !== 'string') return []
+  if (!Array.isArray(asset.variants) || !asset.variants.length) {
+    return [{ tag: 'img', attr: { src: asset.src, alt: alt || '' } }]
+  }
+  // Group by format. Format that matches `asset.type` is the fallback
+  // and gets emitted as the trailing `<img>` (browsers fall through to
+  // it when no `<source>` matches). Other formats become `<source>`.
+  const byFormat = new Map()
+  for (const v of asset.variants) {
+    if (!byFormat.has(v.format)) byFormat.set(v.format, [])
+    byFormat.get(v.format).push(v)
+  }
+  const sources = []
+  for (const [format, list] of byFormat) {
+    if (format === asset.type) continue
+    sources.push({
+      tag: 'source',
+      attr: { type: format, srcset: srcsetFor(list, { keepOneX: true }) }
+    })
+  }
+  const sameFormat = byFormat.get(asset.type) || []
+  const fallbackSrcset = srcsetFor(sameFormat, { keepOneX: false })
+  const imgAttr = { src: asset.src, alt: alt || '' }
+  if (fallbackSrcset) imgAttr.srcset = fallbackSrcset
+  return [...sources, { tag: 'img', attr: imgAttr }]
+}

package/cache.js

@@ -0,0 +1,7 @@
+'use strict'
+
+export const cache = {}
+
+// Shared mutable options populated by create.js (cacheOptions/resetOptions).
+// Holds .create (initial create options) and .defaultOptions (per-render overrides).
+export const OPTIONS = {}

package/cdn.js

@@ -0,0 +1,83 @@
+'use strict'
+
+function onlyDotsAndNumbers (str) {
+  return /^[0-9.]+$/.test(str) && str !== ''
+}
+
+export const CDN_PROVIDERS = {
+  skypack: {
+    url: 'https://cdn.skypack.dev',
+    formatUrl: (pkg, version) =>
+      `${CDN_PROVIDERS.skypack.url}/${pkg}${version !== 'latest' ? `@${version}` : ''}`
+  },
+  esmsh: {
+    url: 'https://esm.sh',
+    formatUrl: (pkg, version) =>
+      `${CDN_PROVIDERS.esmsh.url}/${pkg}${version !== 'latest' ? `@${version}` : ''}`
+  },
+  unpkg: {
+    url: 'https://unpkg.com',
+    formatUrl: (pkg, version) =>
+      `${CDN_PROVIDERS.unpkg.url}/${pkg}${version !== 'latest' ? `@${version}` : ''}?module`
+  },
+  jsdelivr: {
+    url: 'https://cdn.jsdelivr.net/npm',
+    formatUrl: (pkg, version) =>
+      `${CDN_PROVIDERS.jsdelivr.url}/${pkg}${version !== 'latest' ? `@${version}` : ''}/+esm`
+  },
+  symbols: {
+    url: 'https://pkg.symbo.ls',
+    formatUrl: (pkg, version) => {
+      if (pkg.split('/').length > 2 || !onlyDotsAndNumbers(version)) {
+        return `${CDN_PROVIDERS.symbols.url}/${pkg}`
+      }
+      return `${CDN_PROVIDERS.symbols.url}/${pkg}/${version}.js`
+    }
+  }
+}
+
+// Maps symbols.json packageManager values to CDN_PROVIDERS keys
+export const PACKAGE_MANAGER_TO_CDN = {
+  'esm.sh': 'esmsh',
+  'unpkg': 'unpkg',
+  'skypack': 'skypack',
+  'jsdelivr': 'jsdelivr',
+  'pkg.symbo.ls': 'symbols'
+}
+
+/**
+ * Derive the CDN provider key from a symbols config object.
+ * Returns null when packageManager is a local tool (npm/yarn/pnpm/bun).
+ */
+export const getCdnProviderFromConfig = (symbolsConfig = {}) => {
+  const { packageManager } = symbolsConfig
+  return PACKAGE_MANAGER_TO_CDN[packageManager] || null
+}
+
+export const getCDNUrl = (
+  packageName,
+  version = 'latest',
+  provider = 'esmsh'
+) => {
+  const cdnConfig = CDN_PROVIDERS[provider] || CDN_PROVIDERS.esmsh
+  return cdnConfig.formatUrl(packageName, version)
+}
+
+/**
+ * Generate an HTML <script type="importmap"> tag from project dependencies.
+ */
+export const getImportMapScript = (data, defaultProvider = 'skypack') => {
+  const dependencies = data.dependencies || {}
+  const keys = Object.keys(dependencies)
+  if (!keys.length) return ''
+
+  const imports = {}
+  for (const pkgName of keys) {
+    const version = dependencies[pkgName] || 'latest'
+    imports[pkgName] = getCDNUrl(pkgName, version, defaultProvider)
+  }
+
+  return `<script type="importmap">{
+    "imports": ${JSON.stringify(imports, null, 2)}
+  }</script>`
+}

package/component.js

@@ -0,0 +1,25 @@
+'use strict'
+
+import { createExtendsFromKeys } from './extends.js'
+import { isString } from './types.js'
+
+export const matchesComponentNaming = key => {
+  if (!isString(key) || !key.length) return false
+  const code = key.charCodeAt(0)
+  return code >= 65 && code <= 90 // A-Z
+}
+
+export function getCapitalCaseKeys (obj) {
+  return Object.keys(obj).filter(key => /^[A-Z]/.test(key))
+}
+
+export function getSpreadChildren (obj) {
+  return Object.keys(obj).filter(key => /^\d+$/.test(key))
+}
+
+export function isContextComponent (element, parent, passedKey) {
+  const { context } = parent || {}
+  const [extendsKey] = createExtendsFromKeys(passedKey)
+  const key = passedKey || extendsKey
+  return context?.components?.[key] || context?.pages?.[key]
+}

package/cookie.js

@@ -0,0 +1,78 @@
+'use strict'
+
+import { isUndefined } from './types.js'
+import { document } from './globals.js'
+
+export const isMobile = (() =>
+  typeof navigator === 'undefined' ? false : /Mobi/.test(navigator.userAgent))()
+
+export const setCookie = (cname, cvalue, exdays = 365) => {
+  if (isUndefined(document) || isUndefined(document.cookie)) return
+  const d = new Date()
+  d.setTime(d.getTime() + exdays * 24 * 60 * 60 * 1000)
+  const expires = `expires=${d.toUTCString()}`
+  document.cookie = `${cname}=${cvalue};${expires};path=/`
+}
+
+export const getCookie = cname => {
+  if (isUndefined(document) || isUndefined(document.cookie)) return
+  const name = `${cname}=`
+  const decodedCookie = decodeURIComponent(document.cookie)
+  const ca = decodedCookie.split(';')
+  for (let i = 0; i < ca.length; i++) {
+    let c = ca[i]
+    while (c.charAt(0) === ' ') c = c.substring(1)
+    if (c.indexOf(name) === 0) return c.substring(name.length, c.length)
+  }
+  return ''
+}
+
+export const removeCookie = cname => {
+  if (isUndefined(document) || isUndefined(document.cookie)) return
+  document.cookie = cname + '=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/;'
+}
+/**
+ * Load item from the localStorage
+ *
+ * @param key -- string to identify the storage item
+ * @returns {*} -- parsed data or undefined
+ */
+export function getLocalStorage (key) {
+  // localStorage access throws in: Safari private mode (quota), sandboxed
+  // iframes without `allow-storage-access-by-user-activation`, Firefox with
+  // `dom.storage.enabled=false`. Wrap the access itself, not just the
+  // JSON.parse — the existing try only covered parse and let the read
+  // crash the host.
+  let item
+  try {
+    if (!window.localStorage) return undefined
+    item = window.localStorage.getItem(key)
+  } catch (e) {
+    return undefined
+  }
+  if (item === null) return undefined
+  try {
+    return JSON.parse(item)
+  } catch (e) {
+    return undefined
+  }
+}
+
+/**
+ * Save the data to window.localStorage
+ *
+ * @param key  - local storage key to save the data under
+ * @param data - the data to save
+ */
+export function setLocalStorage (key, data) {
+  if (data === undefined || data === null) return
+  try {
+    if (!window.localStorage) return
+    const value = typeof data === 'object' ? JSON.stringify(data) : data
+    window.localStorage.setItem(key, value)
+  } catch (e) {
+    // QuotaExceededError (Safari private + over quota), SecurityError
+    // (sandboxed iframe / disabled storage). Silent fail — caller doesn't
+    // expect an exception out of a "save best-effort" helper.
+  }
+}

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

@@ -14,14 +14,14 @@ export const detectHeightOnInit = (element, state) => {
 
     if (state.active) {
       if (props.height === 'auto') return
-      element.setProps(
+      element.update(
         {
           height: state.clientHeight
         },
         { preventBeforeUpdateListener: true, preventChildrenUpdate: true }
       )
       const setAutoTimeout = setTimeout(() => {
-        element.setProps(
+        element.update(
           {
             height: 'auto'
           },
@@ -30,7 +30,7 @@ export const detectHeightOnInit = (element, state) => {
         clearTimeout(setAutoTimeout)
       }, 450)
     } else {
-      element.setProps(
+      element.update(
         {
           height: '0'
         },