@symbo.ls/utils 3.1.2 → 3.14.0

package/function.js

@@ -0,0 +1,145 @@
+'use strict'
+
+/**
+ * Debounces a function, ensuring that it is only executed after a specified timeout
+ * period has elapsed since the last invocation.
+ *
+ * @param {function} func - The function to be debounced.
+ * @param {number} [timeout=300] - The time (in milliseconds) to wait after the last call to
+ *     `debounce` before executing the `func`.
+ * @returns {function} - A debounced version of the input function `func`.
+ * @example
+ * // Usage example:
+ * const debouncedFunction = debounce(this, myFunction, 500);
+ * window.addEventListener('resize', debouncedFunction);
+ */
+export function debounce (func, wait, immediate) {
+  let timeout
+  return function () {
+    const context = this
+    const args = arguments
+    const later = function () {
+      timeout = null
+      if (!immediate) func.apply(context, args)
+    }
+    const callNow = immediate && !timeout
+    clearTimeout(timeout)
+    timeout = setTimeout(later, wait)
+    if (callNow) func.apply(context, args)
+  }
+}
+
+/**
+ * Debounces a function, ensuring that it is only executed after a specified timeout
+ * period has elapsed since the last invocation.
+ *
+ * @param {Object} element - The context (this) to which the debounced function will be applied.
+ * @param {function} func - The function to be debounced.
+ * @param {number} [timeout=300] - The time (in milliseconds) to wait after the last call to
+ *     `debounce` before executing the `func`.
+ * @returns {function} - A debounced version of the input function `func`.
+ * @example
+ * // Usage example:
+ * const debouncedFunction = debounce(this, myFunction, 500);
+ * window.addEventListener('resize', debouncedFunction);
+ */
+export const debounceOnContext = (element, func, timeout = 300) => {
+  let timer
+  return (...args) => {
+    clearTimeout(timer)
+    timer = setTimeout(() => {
+      func.apply(element, args)
+    }, timeout)
+  }
+}
+
+export const memoize = fn => {
+  const cache = {}
+  return (...args) => {
+    const n = args[0]
+    if (n in cache) {
+      return cache[n]
+    } else {
+      const result = fn(n)
+      cache[n] = result
+      return result
+    }
+  }
+}
+
+const RE_STRING_FUNCTION = /^((function\s*\([^)]*\)\s*\{[^}]*\})|(\([^)]*\)\s*=>))/
+
+export const isStringFunction = inputString => {
+  return RE_STRING_FUNCTION.test(inputString)
+}
+
+/**
+ * Resolve an event handler through context plugins.
+ *
+ * If `handler` is already a function it is returned as-is.
+ * Otherwise, iterates `context.plugins` looking for a plugin
+ * with a `resolveHandler` method that can compile the handler
+ * (e.g. a funcql schema) into a callable function.
+ *
+ * @param {*} handler - event handler (function, object, array, string)
+ * @param {object} element - domql element
+ * @returns {function|*} resolved handler
+ */
+/**
+ * Check if context has any plugin that can resolve non-function handlers.
+ */
+export const hasHandlerPlugin = (ctx) => {
+  const plugins = ctx?.plugins
+  if (!plugins || !plugins.length) return false
+  for (const plugin of plugins) {
+    if (plugin.resolveHandler) return true
+  }
+  return false
+}
+
+export const resolveHandler = (handler, element) => {
+  if (typeof handler === 'function') return handler
+  const plugins = element?.context?.plugins
+  if (!plugins) return handler
+  for (const plugin of plugins) {
+    if (plugin.resolveHandler) {
+      const resolved = plugin.resolveHandler(handler, element)
+      if (typeof resolved === 'function') return resolved
+    }
+  }
+  return handler
+}
+
+/**
+ * Run a named hook across all context plugins.
+ *
+ * @param {string} hookName - lifecycle hook name
+ * @param {object} element - domql element
+ * @param {*[]} args - additional arguments forwarded to each plugin hook
+ */
+export const runPluginHook = (hookName, element, ...args) => {
+  const plugins = element?.context?.plugins
+  if (!plugins) return false
+  let handled = false
+  for (const plugin of plugins) {
+    if (typeof plugin[hookName] === 'function') {
+      plugin[hookName](element, ...args)
+      handled = true
+    }
+  }
+  return handled
+}
+
+export function cloneFunction (fn, win = window) {
+  const temp = function () {
+    return fn.apply(win, arguments)
+  }
+
+  // Copy properties from original function
+  for (const key in fn) {
+    if (Object.prototype.hasOwnProperty.call(fn, key)) {
+      temp[key] = fn[key]
+    }
+  }
+  return temp
+}

package/globals.js

@@ -0,0 +1,8 @@
+'use strict'
+
+const global = globalThis
+const self = globalThis
+const window = globalThis
+const document = (this || window).document // eslint-disable-line
+
+export { global, self, window, document }

package/if.js

@@ -0,0 +1,30 @@
+'use strict'
+
+import { isFunction } from './types.js'
+import { exec } from './object.js'
+
+export const createIfConditionFlag = (element, parent) => {
+  const { __ref: ref } = element
+  const ifVal = element.if
+
+  if (isFunction(ifVal)) {
+    let result
+    try {
+      result = ifVal(element, element.state, element.context)
+    } catch (e) {
+      if (typeof console !== 'undefined') console.warn('[DOMQL] if condition error:', e)
+      delete ref.__if
+      return
+    }
+    if (!result) {
+      delete ref.__if
+    } else ref.__if = true
+  } else if (ifVal != null && typeof ifVal === 'object') {
+    // funcql schema — evaluate via exec() which delegates to plugins
+    const result = exec(ifVal, element)
+    if (!result) delete ref.__if
+    else ref.__if = true
+  } else {
+    ref.__if = true
+  }
+}

package/index.js

@@ -0,0 +1,41 @@
+'use strict'
+
+export * from './key.js'
+export * from './env.js'
+export * from './types.js'
+export * from './object.js'
+export * from './function.js'
+export * from './array.js'
+export * from './node.js'
+export * from './if.js'
+export * from './log.js'
+export * from './string.js'
+export * from './globals.js'
+export * from './cookie.js'
+export * from './tags.js'
+export * from './component.js'
+export * from './props.js'
+export * from './extends.js'
+export * from './element.js'
+export * from './state.js'
+export * from './keys.js'
+export * from './scope.js'
+export * from './methods.js'
+export * from './cache.js'
+export * from './update.js'
+export * from './triggerEvent.js'
+export * from './projectKeys.js'
+
+// ── Merged from the former @symbo.ls/smbls-utils package (4.x) ────────────
+export * from './browser.js'
+export * from './cdn.js'
+export * from './date.js'
+export * from './detectHeight.js'
+export * from './fibonacci.js'
+export * from './files.js'
+export * from './load.js'
+export * from './metadata.js'
+export * from './scaling.js'
+export * from './sharedLibraries.js'
+export * from './string-extra.js'
+export * from './style.js'

package/key.js

@@ -0,0 +1,20 @@
+'use strict'
+
+import { exec } from './object.js'
+
+export const generateKey = (function () {
+  let index = 0
+
+  function newId () {
+    index++
+    return index
+  }
+
+  return newId
+})()
+
+export const createSnapshotId = generateKey
+
+export const createKey = (element, parent, key) => {
+  return (exec(key, element) || key || element.key || generateKey()).toString()
+}

package/keys.js

@@ -0,0 +1,176 @@
+'use strict'
+
+export const DOMQ_PROPERTIES = new Set([
+  'attr',
+  'style',
+  'text',
+  'html',
+  'content',
+  'data',
+  'classlist',
+  'state',
+  'scope',
+  'root',
+  'deps',
+  'extend',
+  'extends',
+  '$router',
+  'routes',
+  'children',
+  'childExtend',
+  'childExtends',
+  'childExtendRecursive',
+  'childExtendsRecursive',
+  'props',
+  'if',
+  'define',
+  '__name',
+  '__ref',
+  '__hash',
+  '__text',
+  'key',
+  'tag',
+  'query',
+  'parent',
+  'node',
+  'variables',
+  'on',
+  'fetch',
+  'component',
+  'context',
+  'preventContentUpdate',
+  'preventContentRecreate'
+])
+
+export const PARSED_DOMQ_PROPERTIES = new Set([
+  'attr',
+  'style',
+  'text',
+  'html',
+  'content',
+  'data',
+  'class',
+  'state',
+  'scope',
+  'children',
+  'props',
+  'if',
+  'key',
+  'tag',
+  'query',
+  'on',
+  'context'
+])
+
+export const STATE_PROPERTIES = [
+  'ref',
+  'parent',
+  '__element',
+  '__depends',
+  '__ref',
+  '__children',
+  'root'
+]
+
+export const STATE_METHODS = new Set([
+  'update',
+  'parse',
+  'clean',
+  'create',
+  'destroy',
+  'add',
+  'toggle',
+  'remove',
+  'apply',
+  'set',
+  'reset',
+  'replace',
+  'quietReplace',
+  'quietUpdate',
+  'applyReplace',
+  'applyFunction',
+  'keys',
+  'values',
+  'ref',
+  'rootUpdate',
+  'parentUpdate',
+  'parent',
+  '__element',
+  '__depends',
+  '__ref',
+  '__children',
+  'root',
+  'setByPath',
+  'setPathCollection',
+  'removeByPath',
+  'removePathCollection',
+  'getByPath'
+])
+
+export const PROPS_METHODS = new Set(['update', '__element'])
+
+export const METHODS = new Set([
+  'set',
+  'reset',
+  'update',
+  'remove',
+  'updateContent',
+  'removeContent',
+  'lookup',
+  'lookdown',
+  'lookdownAll',
+  'getRef',
+  'getPath',
+  'setNodeStyles',
+  'spotByPath',
+  'keys',
+  'parse',
+  'setProps',
+  'parseDeep',
+  'variables',
+  'if',
+  'log',
+  'verbose',
+  'warn',
+  'error',
+  'call',
+  'nextElement',
+  'previousElement',
+  'getRootState',
+  'getRoot',
+  'getRootData',
+  'getRootContext',
+  'getContext',
+  'getQuery',
+  'getDB',
+  'getChildren',
+  'preventContentUpdate',
+  'preventContentRecreate'
+])
+
+export const METHODS_EXL = new Set([
+  'node', 'context', 'extends', '__element', '__ref',
+  ...METHODS,
+  ...STATE_METHODS,
+  ...PROPS_METHODS
+])
+
+export const DOMQL_EVENTS = new Set([
+  'init',
+  'beforeClassAssign',
+  'render',
+  'renderRouter',
+  'attachNode',
+  'stateInit',
+  'stateCreated',
+  'beforeStateUpdate',
+  'stateUpdate',
+  'beforeUpdate',
+  'done',
+  'create',
+  'complete',
+  'frame',
+  'update',
+  'fetchError',
+  'fetchComplete'
+])

package/load.js

@@ -0,0 +1,236 @@
+'use strict'
+
+export const loadJavascriptFile = (
+  FILE_URL,
+  async = false,
+  doc = document,
+  type = 'text/javascript'
+) => {
+  return new Promise((resolve, reject) => {
+    try {
+      const scriptEle = doc.createElement('script')
+      scriptEle.type = type
+      scriptEle.async = async
+      scriptEle.src = FILE_URL
+
+      scriptEle.addEventListener('load', ev => {
+        resolve({
+          status: true
+        })
+      })
+
+      scriptEle.addEventListener('error', ev => {
+        reject(
+          new Error({
+            status: false,
+            message: `Failed to load the script ${FILE_URL}`
+          })
+        )
+      })
+
+      doc.body.appendChild(scriptEle)
+    } catch (error) {
+      reject(error)
+    }
+  })
+}
+
+export const loadJavascriptFileSync = (
+  fileUrl,
+  doc = document,
+  type = 'text/javascript'
+) => {
+  return new Promise((resolve, reject) => {
+    const scriptEle = doc.createElement('script')
+    scriptEle.type = type
+    scriptEle.src = fileUrl
+
+    // Create a blocking overlay
+    const blocker = doc.createElement('div')
+    blocker.style.cssText =
+      'position:fixed;top:0;left:0;right:0;bottom:0;background:rgba(255,255,255,0.8);z-index:9999;'
+    doc.body.appendChild(blocker)
+
+    scriptEle.onload = () => {
+      console.log(`Successfully loaded: ${fileUrl}`)
+      doc.body.removeChild(blocker)
+      resolve()
+    }
+
+    scriptEle.onerror = () => {
+      doc.body.removeChild(blocker)
+      reject(new Error(`Failed to load: ${fileUrl}`))
+    }
+
+    doc.body.appendChild(scriptEle)
+  })
+}
+
+export const loadJavascriptFileEmbedSync = (
+  FILE_URL,
+  doc = document,
+  fallback,
+  type = 'text/javascript'
+) => {
+  const xhr = new window.XMLHttpRequest()
+  xhr.open('GET', FILE_URL, false) // false makes the request synchronous
+  xhr.send()
+
+  if (xhr.status === 200) {
+    const scriptEle = doc.createElement('script')
+    scriptEle.type = type
+    scriptEle.text = xhr.responseText
+    doc.body.appendChild(scriptEle)
+    if (typeof fallback === 'function') fallback()
+  } else {
+    throw new Error(`Failed to load the script ${FILE_URL}`)
+  }
+}
+
+export const loadCssFile = (
+  FILE_URL,
+  async = false,
+  doc = document,
+  type = 'text/javascript'
+) => {
+  return new Promise((resolve, reject) => {
+    try {
+      const linkElem = doc.createElement('link')
+      linkElem.rel = 'stylesheet'
+      linkElem.href = FILE_URL
+
+      linkElem.addEventListener('load', ev => {
+        resolve({
+          status: true
+        })
+      })
+
+      doc.head.appendChild(linkElem)
+    } catch (error) {
+      reject(error)
+    }
+  })
+}
+
+export const loadJavascript = (
+  body,
+  async = false,
+  doc = document,
+  type = 'text/javascript',
+  id = 'smbls-script'
+) => {
+  try {
+    const scriptEle = doc.createElement('script')
+    scriptEle.type = type
+    scriptEle.async = async
+    scriptEle.id = id
+    scriptEle.innerHTML = body
+
+    doc.body.appendChild(scriptEle)
+  } catch (error) {
+    console.warn(error)
+  }
+}
+
+/**
+ * Dynamically loads a remote JavaScript file and returns a Promise
+ * that resolves when the script has completely loaded or rejects on error.
+ *
+ * @param {string} url - The URL of the remote JavaScript file to load
+ * @param {Object} [options] - Optional configuration
+ * @param {string} [options.id] - Optional ID to assign to the script element
+ * @param {boolean} [options.async=true] - Whether to load the script asynchronously
+ * @param {string} [options.type='text/javascript'] - The type attribute for the script
+ * @param {string} [options.integrity] - Optional integrity hash for SRI
+ * @param {string} [options.crossOrigin] - Optional crossorigin attribute
+ * @return {Promise} A promise that resolves when the script loads or rejects on error
+ */
+export function loadRemoteScript (url, options = {}) {
+  const { window = globalThis } = options
+  const { document = window.document } = options
+
+  return new Promise((resolve, reject) => {
+    // Check if script is already loaded
+    const existingScript = document.querySelector(`script[src="${url}"]`)
+    if (existingScript) {
+      return resolve(existingScript)
+    }
+
+    // Create script element
+    const script = document.createElement('script')
+    script.src = url
+    script.async = options.async === true
+    script.type = options.type || 'text/javascript'
+
+    // Add optional attributes
+    if (options.id) script.id = options.id
+    if (options.integrity) script.integrity = options.integrity
+    if (options.crossOrigin) script.crossOrigin = options.crossOrigin
+
+    // Setup load and error handlers
+    script.onload = () => {
+      script.onerror = script.onload = null
+      resolve(script)
+    }
+
+    script.onerror = () => {
+      script.onerror = script.onload = null
+      reject(new Error(`Failed to load script: ${url}`))
+    }
+
+    // Append the script to the document head
+    document.head.appendChild(script)
+  })
+}
+
+/**
+ * Dynamically loads a remote CSS file and returns a Promise
+ * that resolves when the stylesheet has completely loaded or rejects on error.
+ *
+ * @param {string} url - The URL of the remote CSS file to load
+ * @param {Object} [options] - Optional configuration
+ * @param {string} [options.id] - Optional ID to assign to the link element
+ * @param {string} [options.rel='stylesheet'] - The rel attribute for the link
+ * @param {string} [options.media='all'] - The media attribute
+ * @param {string} [options.integrity] - Optional integrity hash for SRI
+ * @param {string} [options.crossOrigin] - Optional crossorigin attribute
+ * @return {Promise} A promise that resolves when the stylesheet loads or rejects on error
+ */
+export async function loadRemoteCSS (url, options = {}) {
+  const { window = globalThis } = options
+  const { document = window.document } = options
+
+  return new Promise((resolve, reject) => {
+    // Check if stylesheet is already loaded
+    const existingLink = document.querySelector(`link[href="${url}"]`)
+    if (existingLink) {
+      return resolve(existingLink)
+    }
+
+    // Create link element
+    const link = document.createElement('link')
+    link.href = url
+    link.rel = options.rel || 'stylesheet'
+    link.type = 'text/css'
+    link.media = options.media || 'all'
+
+    // Add optional attributes
+    if (options.id) link.id = options.id
+    if (options.integrity) link.integrity = options.integrity
+    if (options.crossOrigin) link.crossOrigin = options.crossOrigin
+
+    // Setup load and error handlers
+    link.onload = () => {
+      link.onerror = link.onload = null
+      resolve(link)
+    }
+
+    link.onerror = () => {
+      link.onerror = link.onload = null
+      reject(new Error(`Failed to load stylesheet: ${url}`))
+    }
+
+    // Append the link to the document head
+    document.head.appendChild(link)
+  })
+}

package/log.js

@@ -0,0 +1,12 @@
+'use strict'
+
+export const logIf = (bool, ...arg) => {
+  if (bool) arg.map(v => console.log(v))
+}
+export const logGroupIf = (bool, key, ...arg) => {
+  if (bool) {
+    console.group(key)
+    arg.map(v => console.log(v))
+    console.groupEnd(key)
+  }
+}