@symbo.ls/shorthand 2.34.32 → 2.34.34

package/README.md

@@ -0,0 +1,181 @@
+# @symbo.ls/shorthand
+
+Bidirectional shorthand transpiler for [Symbols](https://github.com/symbo-ls/smbls) component properties. Compresses DOMQL component objects using abbreviated property names and compact string encoding — and losslessly expands them back.
+
+## Install
+
+```sh
+npm install @symbo.ls/shorthand
+```
+
+## API
+
+Six functions in three complementary pairs:
+
+| Pair       | Forward     | Inverse  | Description                                                  |
+| ---------- | ----------- | -------- | ------------------------------------------------------------ |
+| **String** | `encode`    | `decode` | Flat object ↔ single-line shorthand string                  |
+| **Object** | `shorten`   | `expand` | Recursive key abbreviation preserving structure              |
+| **Hybrid** | `stringify` | `parse`  | Primitive props → `in` string, structural props stay as keys |
+
+### encode / decode
+
+Converts flat primitive props into a compact single-line string.
+
+```js
+import { encode, decode } from '@symbo.ls/shorthand'
+
+encode({ padding: 'A B', background: 'red', hidden: true })
+// → 'p:A_B bg:red hid'
+
+decode('p:A_B bg:red hid')
+// → { padding: 'A B', background: 'red', hidden: true }
+```
+
+**Syntax rules:**
+
+- `abbr:value` — key-value pair
+- `_` — represents spaces inside values
+- `,` — array separator (`ext:Flex,Box` → `extends: ['Flex', 'Box']`)
+- bare `abbr` — boolean `true`
+- `!abbr` — boolean `false`
+
+Functions, objects, and other non-serializable values are skipped.
+
+### shorten / expand
+
+Recursively abbreviates (or expands) property keys throughout the component tree while preserving the full object structure — child components, selectors, functions, arrays, and everything else stays intact.
+
+```js
+import { shorten, expand } from '@symbo.ls/shorthand'
+
+const component = {
+  extends: 'Flex',
+  padding: 'A B',
+  gap: 'C',
+  flexDirection: 'column',
+  onClick: (e, el) => {},
+  Header: { fontSize: 'B' },
+  ':hover': { background: 'blue' }
+}
+
+shorten(component)
+// {
+//   ext: 'Flex',
+//   p: 'A B',
+//   g: 'C',
+//   fxd: 'column',
+//   '@ck': (e, el) => {},
+//   Header: { fs: 'B' },
+//   ':hover': { bg: 'blue' }
+// }
+
+expand(shorten(component)) // deeply equals original
+```
+
+**Preservation rules:**
+
+- **PascalCase keys** (child components) — key kept as-is, value recursed
+- **Selector keys** (`:hover`, `@dark`, `.isActive`, `> *`) — key kept, value recursed
+- **`state`, `scope`, `attr`, `style`, `data`, `context`, `query`, `class`** — values preserved as-is (no key abbreviation inside)
+- **Functions** — preserved, only the key is shortened
+
+### stringify / parse
+
+Hybrid encoding: flat primitive props go into a compact `in` string, while structural props (functions, nested objects, child components, selectors) remain as shortened object keys.
+
+```js
+import { stringify, parse } from '@symbo.ls/shorthand'
+
+const component = {
+  extends: 'Flex',
+  padding: 'A',
+  background: 'surface',
+  borderRadius: 'B',
+  onClick: (e, el) => {},
+  Header: { fontSize: 'B', color: 'title' }
+}
+
+stringify(component)
+// {
+//   in: 'ext:Flex p:A bg:surface bdr:B',
+//   '@ck': (e, el) => {},
+//   Header: { in: 'fs:B c:title' }
+// }
+
+parse(stringify(component)) // deeply equals original
+```
+
+**What goes into `in`:**
+
+- String props (except `text`, `html`, `content`, `placeholder`, `src`, `href`)
+- Boolean props
+- Primitive arrays (length > 1)
+
+**What stays as object keys:**
+
+- Functions, `null`, `undefined`
+- Nested objects, arrays of objects
+- PascalCase children, selector keys
+- Preserved keys (`state`, `scope`, `style`, etc.)
+- Skip-inline keys (`text`, `html`, `content`, `placeholder`, `src`, `href`)
+- Numbers (to preserve type through round-trip)
+- Strings containing `,` or `_` (to avoid encoding ambiguity)
+
+## Registry
+
+The package ships with 300+ bidirectional abbreviation mappings covering:
+
+- **DOMQL core** — `extends` → `ext`, `childExtends` → `cex`, `state` → `st`, `tag` → `tg`
+- **Symbols shorthand** — `flow` → `fl`, `align` → `aln`, `round` → `rnd`, `boxSize` → `bsz`
+- **CSS properties** — `padding` → `p`, `background` → `bg`, `flexDirection` → `fxd`, `zIndex` → `zi`
+- **HTML attributes** — `placeholder` → `phd`, `disabled` → `dis`, `required` → `req`
+- **ARIA attributes** — `ariaLabel` → `alb`, `ariaHidden` → `ahid`, `role` → `role`
+- **Events** — `onClick` → `@ck`, `onRender` → `@rn`, `onSubmit` → `@sm`, `onKeyDown` → `@kd`
+
+Access the maps directly:
+
+```js
+import { propToAbbr, abbrToProp } from '@symbo.ls/shorthand'
+
+propToAbbr['padding'] // 'p'
+propToAbbr['onClick'] // '@ck'
+abbrToProp['bg'] // 'background'
+abbrToProp['@rn'] // 'onRender'
+```
+
+### Helpers
+
+```js
+import {
+  isComponentKey,
+  isSelectorKey,
+  PRESERVE_VALUE_KEYS,
+  SKIP_INLINE_KEYS
+} from '@symbo.ls/shorthand'
+
+isComponentKey('Header') // true  (PascalCase)
+isComponentKey('padding') // false
+
+isSelectorKey(':hover') // true
+isSelectorKey('@dark') // true
+isSelectorKey('.isActive') // true
+isSelectorKey('> *') // true
+isSelectorKey('padding') // false
+```
+
+## Round-trip guarantee
+
+All three pairs are lossless — the inverse function always reproduces the original:
+
+```js
+decode(encode(obj)) // ≈ obj (flat primitives only)
+expand(shorten(obj)) // ≡ obj (full structure)
+parse(stringify(obj)) // ≡ obj (full structure)
+```
+
+The test suite verifies round-trip correctness against 200+ real-world Symbols components.
+
+## License
+
+ISC

package/dist/cjs/decode.js

@@ -0,0 +1,182 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var decode_exports = {};
+__export(decode_exports, {
+  decode: () => decode,
+  expand: () => expand,
+  parse: () => parse
+});
+module.exports = __toCommonJS(decode_exports);
+var import_registry = require("./registry.js");
+function decode(str) {
+  if (!str || typeof str !== "string") return {};
+  const obj = {};
+  const tokens = tokenize(str);
+  for (const token of tokens) {
+    if (token.startsWith("!")) {
+      const abbr2 = token.slice(1);
+      const prop2 = import_registry.abbrToProp[abbr2] || abbr2;
+      obj[prop2] = false;
+      continue;
+    }
+    const colonIdx = token.indexOf(":");
+    if (colonIdx === -1) {
+      const prop2 = import_registry.abbrToProp[token] || token;
+      obj[prop2] = true;
+      continue;
+    }
+    const abbr = token.slice(0, colonIdx);
+    const rawVal = token.slice(colonIdx + 1);
+    const prop = import_registry.abbrToProp[abbr] || abbr;
+    if (rawVal.includes(",")) {
+      obj[prop] = rawVal.split(",").map(decodeValue);
+      continue;
+    }
+    obj[prop] = decodeValue(rawVal);
+  }
+  return obj;
+}
+function tokenize(str) {
+  return str.trim().split(/\s+/).filter(Boolean);
+}
+function decodeValue(val) {
+  const str = val.replace(/_/g, " ");
+  if (/^-?\d+(\.\d+)?$/.test(str)) {
+    return Number(str);
+  }
+  return str;
+}
+function decodeInlineValue(val) {
+  return val.replace(/_/g, " ");
+}
+function decodeInline(str) {
+  if (!str || typeof str !== "string") return {};
+  const obj = {};
+  const tokens = tokenize(str);
+  for (const token of tokens) {
+    if (token.startsWith("!")) {
+      const abbr2 = token.slice(1);
+      const prop2 = import_registry.abbrToProp[abbr2] || abbr2;
+      obj[prop2] = false;
+      continue;
+    }
+    const colonIdx = token.indexOf(":");
+    if (colonIdx === -1) {
+      const prop2 = import_registry.abbrToProp[token] || token;
+      obj[prop2] = true;
+      continue;
+    }
+    const abbr = token.slice(0, colonIdx);
+    const rawVal = token.slice(colonIdx + 1);
+    const prop = import_registry.abbrToProp[abbr] || abbr;
+    if (rawVal.includes(",")) {
+      obj[prop] = rawVal.split(",").map(decodeInlineValue);
+      continue;
+    }
+    obj[prop] = decodeInlineValue(rawVal);
+  }
+  return obj;
+}
+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];
+    if ((0, import_registry.isComponentKey)(key)) {
+      result[key] = expandVal(val);
+      continue;
+    }
+    const fullKey = import_registry.abbrToProp[key] || key;
+    if ((0, import_registry.isSelectorKey)(key) && fullKey === key) {
+      result[key] = expandVal(val);
+      continue;
+    }
+    if (import_registry.PRESERVE_VALUE_KEYS.has(fullKey) || import_registry.PRESERVE_VALUE_KEYS.has(key)) {
+      result[fullKey] = val;
+      continue;
+    }
+    result[fullKey] = expandVal(val);
+  }
+  return result;
+}
+function expandVal(val) {
+  if (val === null || val === void 0) 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;
+}
+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 = {};
+  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];
+    if ((0, import_registry.isComponentKey)(key)) {
+      result[key] = parseVal(val);
+      continue;
+    }
+    const fullKey = import_registry.abbrToProp[key] || key;
+    if ((0, import_registry.isSelectorKey)(key) && fullKey === key) {
+      result[key] = parseVal(val);
+      continue;
+    }
+    if (import_registry.PRESERVE_VALUE_KEYS.has(fullKey) || import_registry.PRESERVE_VALUE_KEYS.has(key)) {
+      result[fullKey] = val;
+      continue;
+    }
+    result[fullKey] = parseVal(val);
+  }
+  return result;
+}
+function parseVal(val) {
+  if (val === null || val === void 0) 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/dist/cjs/encode.js

@@ -0,0 +1,180 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var encode_exports = {};
+__export(encode_exports, {
+  encode: () => encode,
+  shorten: () => shorten,
+  stringify: () => stringify
+});
+module.exports = __toCommonJS(encode_exports);
+var import_registry = require("./registry.js");
+function encode(obj) {
+  if (!obj || typeof obj !== "object") return "";
+  const tokens = [];
+  for (const prop in obj) {
+    const val = obj[prop];
+    if (typeof val === "function") continue;
+    if (val !== null && typeof val === "object" && !Array.isArray(val)) continue;
+    if (val === void 0) continue;
+    const abbr = import_registry.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(" ");
+}
+function encodeValue(val) {
+  const str = String(val);
+  return str.replace(/ /g, "_");
+}
+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];
+    if ((0, import_registry.isComponentKey)(key)) {
+      result[key] = shortenVal(val);
+      continue;
+    }
+    if ((0, import_registry.isSelectorKey)(key)) {
+      result[key] = shortenVal(val);
+      continue;
+    }
+    const shortKey = import_registry.propToAbbr[key] || key;
+    if (import_registry.PRESERVE_VALUE_KEYS.has(key) || import_registry.PRESERVE_VALUE_KEYS.has(shortKey)) {
+      result[shortKey] = val;
+      continue;
+    }
+    result[shortKey] = shortenVal(val);
+  }
+  return result;
+}
+function shortenVal(val) {
+  if (val === null || val === void 0) 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;
+}
+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];
+    if ((0, import_registry.isComponentKey)(key)) {
+      result[key] = stringifyVal(val);
+      continue;
+    }
+    if ((0, import_registry.isSelectorKey)(key)) {
+      result[key] = stringifyVal(val);
+      continue;
+    }
+    const shortKey = import_registry.propToAbbr[key] || key;
+    if (import_registry.PRESERVE_VALUE_KEYS.has(key) || import_registry.PRESERVE_VALUE_KEYS.has(shortKey)) {
+      result[shortKey] = val;
+      continue;
+    }
+    if (typeof val === "function") {
+      result[shortKey] = val;
+      continue;
+    }
+    if (val === null || val === void 0) {
+      result[shortKey] = val;
+      continue;
+    }
+    if (import_registry.SKIP_INLINE_KEYS.has(key) || import_registry.SKIP_INLINE_KEYS.has(shortKey)) {
+      result[shortKey] = val;
+      continue;
+    }
+    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;
+      }
+      if (val.length <= 1) {
+        result[shortKey] = val;
+        continue;
+      }
+      tokens.push(shortKey + ":" + val.map(encodeValue).join(","));
+      continue;
+    }
+    if (typeof val === "object") {
+      result[shortKey] = stringify(val);
+      continue;
+    }
+    if (val === true) {
+      tokens.push(shortKey);
+    } else if (val === false) {
+      tokens.push("!" + shortKey);
+    } else if (typeof val === "number") {
+      result[shortKey] = val;
+    } else if (typeof val === "string" && (val.includes(",") || val.includes("_"))) {
+      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 === void 0) 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;
+}