@symbo.ls/shorthand 2.34.32

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@symbo.ls/shorthand",
+  "description": "Shorthand syntax transpiler for Symbols properties",
+  "author": "symbo.ls",
+  "version": "2.34.32",
+  "repository": "https://github.com/symbo-ls/smbls",
+  "type": "module",
+  "module": "src/index.js",
+  "main": "src/index.js",
+  "exports": "./src/index.js",
+  "source": "src/index.js",
+  "publishConfig": {},
+  "scripts": {
+    "test": "node --experimental-vm-modules ../../node_modules/.bin/jest",
+    "copy:package:cjs": "cp ../../build/package-cjs.json dist/cjs/package.json",
+    "build:cjs": "npx cross-env NODE_ENV=$NODE_ENV npx esbuild ./src/*.js --target=node16 --format=cjs --outdir=dist/cjs",
+    "build": "npm run build:cjs",
+    "prepublish": "rimraf -I dist && npm run build && npm run copy:package:cjs"
+  },
+  "files": [
+    "src",
+    "dist",
+    "docs"
+  ],
+  "license": "ISC",
+  "gitHead": "99bd991fb87c092bcfd045ad358c15064a8b8c30"
+}

package/src/decode.js

@@ -0,0 +1,275 @@
+'use strict'
+
+import {
+  abbrToProp,
+  PRESERVE_VALUE_KEYS,
+  isComponentKey,
+  isSelectorKey
+} from './registry.js'
+
+/**
+ * Decode a shorthand string back into a Symbols component object.
+ *
+ * Syntax:
+ *   abbr:value   — key-value pair
+ *   _            — decoded to spaces in values
+ *   ,            — array values (ext:Flex,Box → extends: ['Flex', 'Box'])
+ *   bare abbr    — boolean true
+ *   !abbr        — boolean false
+ *
+ * @param {string} str — shorthand string
+ * @returns {Object} — Symbols component object
+ */
+export function decode(str) {
+  if (!str || typeof str !== 'string') return {}
+
+  const obj = {}
+  const tokens = tokenize(str)
+
+  for (const token of tokens) {
+    // Boolean false: !abbr
+    if (token.startsWith('!')) {
+      const abbr = token.slice(1)
+      const prop = abbrToProp[abbr] || abbr
+      obj[prop] = false
+      continue
+    }
+
+    const colonIdx = token.indexOf(':')
+
+    // Boolean true: bare abbreviation
+    if (colonIdx === -1) {
+      const prop = abbrToProp[token] || token
+      obj[prop] = true
+      continue
+    }
+
+    const abbr = token.slice(0, colonIdx)
+    const rawVal = token.slice(colonIdx + 1)
+    const prop = abbrToProp[abbr] || abbr
+
+    // Array value: comma-separated
+    if (rawVal.includes(',')) {
+      obj[prop] = rawVal.split(',').map(decodeValue)
+      continue
+    }
+
+    obj[prop] = decodeValue(rawVal)
+  }
+
+  return obj
+}
+
+/**
+ * Tokenize a shorthand string by splitting on spaces,
+ * respecting that underscores represent spaces within values.
+ */
+function tokenize(str) {
+  return str.trim().split(/\s+/).filter(Boolean)
+}
+
+/**
+ * Decode a single value: underscores → spaces, parse numbers and booleans.
+ */
+function decodeValue(val) {
+  const str = val.replace(/_/g, ' ')
+
+  // Try parsing as number
+  if (/^-?\d+(\.\d+)?$/.test(str)) {
+    return Number(str)
+  }
+
+  return str
+}
+
+/**
+ * Decode inline `in` string values preserving string types.
+ * Unlike decodeValue, this does NOT convert numeric strings to numbers,
+ * since CSS values like '0', '1', '.5' must stay as strings.
+ */
+function decodeInlineValue(val) {
+  return val.replace(/_/g, ' ')
+}
+
+/**
+ * Decode an `in` string (from stringify) back to key-value pairs.
+ * Uses string-preserving value decode to avoid lossy type coercion.
+ */
+function decodeInline(str) {
+  if (!str || typeof str !== 'string') return {}
+
+  const obj = {}
+  const tokens = tokenize(str)
+
+  for (const token of tokens) {
+    if (token.startsWith('!')) {
+      const abbr = token.slice(1)
+      const prop = abbrToProp[abbr] || abbr
+      obj[prop] = false
+      continue
+    }
+
+    const colonIdx = token.indexOf(':')
+
+    if (colonIdx === -1) {
+      const prop = abbrToProp[token] || token
+      obj[prop] = true
+      continue
+    }
+
+    const abbr = token.slice(0, colonIdx)
+    const rawVal = token.slice(colonIdx + 1)
+    const prop = abbrToProp[abbr] || abbr
+
+    // Array value: comma-separated
+    if (rawVal.includes(',')) {
+      obj[prop] = rawVal.split(',').map(decodeInlineValue)
+      continue
+    }
+
+    obj[prop] = decodeInlineValue(rawVal)
+  }
+
+  return obj
+}
+
+/**
+ * Recursively expand abbreviated property names back to full names.
+ *
+ * Inverse of shorten(). Handles:
+ * - PascalCase keys: kept, values recursed
+ * - CSS selectors / media / cases: kept, values recursed
+ * - Event abbreviations (@ck → onClick): expanded via registry
+ * - state, scope, attr, style, data, context, query, class values: preserved as-is
+ * - Everything else: key expanded, value recursed if object/array
+ *
+ * @param {Object} obj — shortened component object
+ * @returns {Object} — expanded component object with full property names
+ */
+export function expand(obj) {
+  if (!obj || typeof obj !== 'object') return obj
+  if (Array.isArray(obj)) {
+    return obj.map(function (item) {
+      if (item !== null && typeof item === 'object') return expand(item)
+      return item
+    })
+  }
+
+  const result = {}
+
+  for (const key in obj) {
+    const val = obj[key]
+
+    // PascalCase = child component → keep key, recurse value
+    if (isComponentKey(key)) {
+      result[key] = expandVal(val)
+      continue
+    }
+
+    // Try to resolve abbreviation first
+    const fullKey = abbrToProp[key] || key
+
+    // Selector/media/case key that is NOT an event abbreviation → keep key, recurse
+    if (isSelectorKey(key) && fullKey === key) {
+      result[key] = expandVal(val)
+      continue
+    }
+
+    // Preserved keys: value NOT recursed
+    if (PRESERVE_VALUE_KEYS.has(fullKey) || PRESERVE_VALUE_KEYS.has(key)) {
+      result[fullKey] = val
+      continue
+    }
+
+    result[fullKey] = expandVal(val)
+  }
+
+  return result
+}
+
+function expandVal(val) {
+  if (val === null || val === undefined) return val
+  if (typeof val === 'function') return val
+  if (Array.isArray(val)) {
+    return val.map(function (item) {
+      if (item !== null && typeof item === 'object') return expand(item)
+      return item
+    })
+  }
+  if (typeof val === 'object') return expand(val)
+  return val
+}
+
+/**
+ * Recursively convert a stringified object (with `in` properties) back
+ * to a full component object with expanded property names.
+ *
+ * Inverse of stringify(). Decodes `in` strings into flat key-value props,
+ * expands all abbreviated keys, and recurses into children/selectors.
+ *
+ * @param {Object} obj — stringified object with `in` properties
+ * @returns {Object} — full Symbols component object
+ */
+export function parse(obj) {
+  if (!obj || typeof obj !== 'object') return obj
+  if (Array.isArray(obj)) {
+    return obj.map(function (item) {
+      if (item !== null && typeof item === 'object') return parse(item)
+      return item
+    })
+  }
+
+  const result = {}
+
+  // Decode the `in` string first so its props come first in key order
+  if (typeof obj.in === 'string') {
+    const decoded = decodeInline(obj.in)
+    for (const prop in decoded) {
+      result[prop] = decoded[prop]
+    }
+  }
+
+  for (const key in obj) {
+    if (key === 'in') continue
+
+    const val = obj[key]
+
+    // PascalCase = child component → keep key, recurse value
+    if (isComponentKey(key)) {
+      result[key] = parseVal(val)
+      continue
+    }
+
+    // Try to resolve abbreviation
+    const fullKey = abbrToProp[key] || key
+
+    // Selector/media/case key that is NOT an event abbreviation → keep key, recurse
+    if (isSelectorKey(key) && fullKey === key) {
+      result[key] = parseVal(val)
+      continue
+    }
+
+    // Preserved keys: value NOT recursed
+    if (PRESERVE_VALUE_KEYS.has(fullKey) || PRESERVE_VALUE_KEYS.has(key)) {
+      result[fullKey] = val
+      continue
+    }
+
+    result[fullKey] = parseVal(val)
+  }
+
+  return result
+}
+
+function parseVal(val) {
+  if (val === null || val === undefined) return val
+  if (typeof val === 'function') return val
+  if (Array.isArray(val)) {
+    return val.map(function (item) {
+      if (item !== null && typeof item === 'object') return parse(item)
+      return item
+    })
+  }
+  if (typeof val === 'object') return parse(val)
+  return val
+}

package/src/encode.js

@@ -0,0 +1,260 @@
+'use strict'
+
+import {
+  propToAbbr,
+  PRESERVE_VALUE_KEYS,
+  SKIP_INLINE_KEYS,
+  isComponentKey,
+  isSelectorKey
+} from './registry.js'
+
+/**
+ * Encode a Symbols component object into a shorthand string.
+ *
+ * Syntax:
+ *   abbr:value   — key-value pair
+ *   _            — replaces spaces inside values
+ *   ,            — array separator (extends: ['Flex', 'Box'] → ext:Flex,Box)
+ *   space        — token separator
+ *   bare abbr    — boolean true  (e.g. `hid` → hidden: true)
+ *   !abbr        — boolean false (e.g. `!hid` → hidden: false)
+ *
+ * Functions, objects, and other non-serializable values are skipped.
+ *
+ * @param {Object} obj — Symbols component object
+ * @returns {string} — shorthand string
+ */
+export function encode(obj) {
+  if (!obj || typeof obj !== 'object') return ''
+
+  const tokens = []
+
+  for (const prop in obj) {
+    const val = obj[prop]
+
+    // Skip functions and nested objects (events, childProps, scope, etc.)
+    if (typeof val === 'function') continue
+    if (val !== null && typeof val === 'object' && !Array.isArray(val)) continue
+    if (val === undefined) continue
+
+    const abbr = propToAbbr[prop] || prop
+
+    if (val === true) {
+      tokens.push(abbr)
+    } else if (val === false) {
+      tokens.push('!' + abbr)
+    } else if (Array.isArray(val)) {
+      const items = val.map((item) => encodeValue(item))
+      tokens.push(abbr + ':' + items.join(','))
+    } else {
+      tokens.push(abbr + ':' + encodeValue(val))
+    }
+  }
+
+  return tokens.join(' ')
+}
+
+/**
+ * Encode a single value: replace spaces with underscores.
+ */
+function encodeValue(val) {
+  const str = String(val)
+  return str.replace(/ /g, '_')
+}
+
+/**
+ * Recursively shorten property names in a Symbols component object.
+ *
+ * - PascalCase keys (child components) are kept as-is, values recursed
+ * - CSS selectors / media queries / cases are kept as-is, values recursed
+ * - Functions are preserved as-is (key is shortened)
+ * - state, scope, attr, style, data, context, query, class values are preserved as-is
+ * - Everything else: key shortened, value recursed if object/array
+ *
+ * @param {Object} obj — Symbols component object
+ * @returns {Object} — shortened component object
+ */
+export function shorten(obj) {
+  if (!obj || typeof obj !== 'object') return obj
+  if (Array.isArray(obj)) {
+    return obj.map(function (item) {
+      if (item !== null && typeof item === 'object') return shorten(item)
+      return item
+    })
+  }
+
+  const result = {}
+
+  for (const key in obj) {
+    const val = obj[key]
+
+    // PascalCase = child component → keep key, recurse value
+    if (isComponentKey(key)) {
+      result[key] = shortenVal(val)
+      continue
+    }
+
+    // CSS selectors, media queries, cases → keep key, recurse value
+    if (isSelectorKey(key)) {
+      result[key] = shortenVal(val)
+      continue
+    }
+
+    // Shorten the key
+    const shortKey = propToAbbr[key] || key
+
+    // Preserved keys: value NOT recursed (state data, scope fns, etc.)
+    if (PRESERVE_VALUE_KEYS.has(key) || PRESERVE_VALUE_KEYS.has(shortKey)) {
+      result[shortKey] = val
+      continue
+    }
+
+    result[shortKey] = shortenVal(val)
+  }
+
+  return result
+}
+
+function shortenVal(val) {
+  if (val === null || val === undefined) return val
+  if (typeof val === 'function') return val
+  if (Array.isArray(val)) {
+    return val.map(function (item) {
+      if (item !== null && typeof item === 'object') return shorten(item)
+      return item
+    })
+  }
+  if (typeof val === 'object') return shorten(val)
+  return val
+}
+
+/**
+ * Recursively convert a component object into a stringified form.
+ *
+ * Flat primitive props (strings, numbers, booleans, primitive arrays)
+ * are encoded into an `in` string using abbreviated keys.
+ * Structural props (functions, objects, arrays of objects, PascalCase children,
+ * selectors, state, scope) remain as shortened object keys.
+ *
+ * @param {Object} obj — Symbols component object
+ * @returns {Object} — stringified object with `in` property
+ */
+export function stringify(obj) {
+  if (!obj || typeof obj !== 'object') return obj
+  if (Array.isArray(obj)) {
+    return obj.map(function (item) {
+      if (item !== null && typeof item === 'object') return stringify(item)
+      return item
+    })
+  }
+
+  const result = {}
+  const tokens = []
+
+  for (const key in obj) {
+    const val = obj[key]
+
+    // PascalCase = child component → keep key, recurse value
+    if (isComponentKey(key)) {
+      result[key] = stringifyVal(val)
+      continue
+    }
+
+    // CSS selectors, media queries, cases → keep key, recurse value
+    if (isSelectorKey(key)) {
+      result[key] = stringifyVal(val)
+      continue
+    }
+
+    const shortKey = propToAbbr[key] || key
+
+    // Preserved keys (state, scope, etc.) → keep as-is
+    if (PRESERVE_VALUE_KEYS.has(key) || PRESERVE_VALUE_KEYS.has(shortKey)) {
+      result[shortKey] = val
+      continue
+    }
+
+    // Functions → keep as shortened key
+    if (typeof val === 'function') {
+      result[shortKey] = val
+      continue
+    }
+
+    // null / undefined → keep as shortened key
+    if (val === null || val === undefined) {
+      result[shortKey] = val
+      continue
+    }
+
+    // Skip-inline keys (text, html, content, placeholder, src, href) → keep as shortened key
+    if (SKIP_INLINE_KEYS.has(key) || SKIP_INLINE_KEYS.has(shortKey)) {
+      result[shortKey] = val
+      continue
+    }
+
+    // Arrays of objects → keep as shortened key, recurse items
+    if (Array.isArray(val)) {
+      const hasObjects = val.some(function (item) {
+        return item !== null && typeof item === 'object'
+      })
+      if (hasObjects) {
+        result[shortKey] = val.map(function (item) {
+          if (item !== null && typeof item === 'object') return stringify(item)
+          return item
+        })
+        continue
+      }
+      // Single-element arrays can't round-trip through in (decoded as scalar)
+      if (val.length <= 1) {
+        result[shortKey] = val
+        continue
+      }
+      // Primitive array → encode into `in` token
+      tokens.push(shortKey + ':' + val.map(encodeValue).join(','))
+      continue
+    }
+
+    // Objects → keep as shortened key, recurse
+    if (typeof val === 'object') {
+      result[shortKey] = stringify(val)
+      continue
+    }
+
+    // Primitives (string, number, boolean) → encode into `in` token
+    if (val === true) {
+      tokens.push(shortKey)
+    } else if (val === false) {
+      tokens.push('!' + shortKey)
+    } else if (typeof val === 'number') {
+      // Numbers must stay as object keys to preserve type
+      result[shortKey] = val
+    } else if (
+      typeof val === 'string' &&
+      (val.includes(',') || val.includes('_'))
+    ) {
+      // Strings with commas or underscores can't be safely encoded
+      result[shortKey] = val
+    } else {
+      tokens.push(shortKey + ':' + encodeValue(val))
+    }
+  }
+
+  if (tokens.length) {
+    result.in = tokens.join(' ')
+  }
+
+  return result
+}
+
+function stringifyVal(val) {
+  if (val === null || val === undefined) return val
+  if (typeof val === 'function') return val
+  if (Array.isArray(val)) {
+    return val.map(function (item) {
+      if (item !== null && typeof item === 'object') return stringify(item)
+      return item
+    })
+  }
+  if (typeof val === 'object') return stringify(val)
+  return val
+}

package/src/index.js

@@ -0,0 +1,12 @@
+'use strict'
+
+export { encode, shorten, stringify } from './encode.js'
+export { decode, expand, parse } from './decode.js'
+export {
+  propToAbbr,
+  abbrToProp,
+  PRESERVE_VALUE_KEYS,
+  SKIP_INLINE_KEYS,
+  isComponentKey,
+  isSelectorKey
+} from './registry.js'