@symbo.ls/utils 3.2.3 → 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/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)
+  }
+}