@symbo.ls/utils 3.14.0 → 3.14.1

package/README.md

@@ -6,7 +6,7 @@ Core utility functions for the DOMQL element system.
 
 The propertization system normalizes element definitions by classifying keys into child elements, framework keys, and CSS/design-token properties.
 
-In v4, 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`).
+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
 
@@ -15,7 +15,7 @@ In v4, properties go directly on the element (no `props:` wrapper needed). The p
 
 ### Key classification rules
 
-In v4, properties go directly on the element (no `props:` wrapper needed). The propertization system still operates internally for the CSS engine.
+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 |
 |---------|---------------|---------|

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/cookie.js

@@ -38,16 +38,19 @@ export const removeCookie = cname => {
  * @returns {*} -- parsed data or undefined
  */
 export function getLocalStorage (key) {
-  if (!window.localStorage) {
-    return undefined
-  }
-
-  const item = window.localStorage.getItem(key)
-
-  if (item === null) {
+  // 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) {
@@ -62,10 +65,14 @@ export function getLocalStorage (key) {
  * @param data - the data to save
  */
 export function setLocalStorage (key, data) {
-  if (!window.localStorage || data === undefined || data === null) {
-    return
+  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.
   }
-
-  const value = typeof data === 'object' ? JSON.stringify(data) : data
-  window.localStorage.setItem(key, value)
 }

package/dist/cjs/browser.js

@@ -16,6 +16,8 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/browser.js
 var browser_exports = {};
 __export(browser_exports, {
   toggleFullscreen: () => toggleFullscreen

package/dist/cjs/date.js

@@ -16,12 +16,14 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/date.js
 var date_exports = {};
 __export(date_exports, {
   formatDate: () => formatDate
 });
 module.exports = __toCommonJS(date_exports);
-const formatDate = (timestamp) => {
+var formatDate = (timestamp) => {
   if (!timestamp) return "";
   const d = new Date(timestamp);
   const ye = new Intl.DateTimeFormat("en", { year: "numeric" }).format(d);

package/dist/cjs/detectHeight.js

@@ -16,46 +16,37 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/detectHeight.js
 var detectHeight_exports = {};
 __export(detectHeight_exports, {
   detectHeightOnInit: () => detectHeightOnInit
 });
 module.exports = __toCommonJS(detectHeight_exports);
-const detectHeightOnInit = (element, state) => {
+var detectHeightOnInit = (element, state) => {
   const heightTimeout = setTimeout(() => {
     const { props } = element;
     if (!state.clientHeight) {
-      const {
-        node: { clientHeight }
-      } = element;
+      const { node: { clientHeight } } = element;
       if (clientHeight) {
         state.clientHeight = clientHeight;
       }
     }
     if (state.active) {
       if (props.height === "auto") return;
-      element.update(
-        {
-          height: state.clientHeight
-        },
-        { preventBeforeUpdateListener: true, preventChildrenUpdate: true }
-      );
+      element.update({
+        props: { height: state.clientHeight }
+      }, { preventBeforeUpdateListener: true, preventChildrenUpdate: true });
       const setAutoTimeout = setTimeout(() => {
-        element.update(
-          {
-            height: "auto"
-          },
-          { preventBeforeUpdateListener: true, preventChildrenUpdate: true }
-        );
+        element.update({
+          props: { height: "auto" }
+        }, { preventBeforeUpdateListener: true, preventChildrenUpdate: true });
         clearTimeout(setAutoTimeout);
       }, 450);
     } else {
-      element.update(
-        {
-          height: "0"
-        },
-        { preventBeforeUpdateListener: true, preventChildrenUpdate: true }
-      );
+      element.update({
+        props: { height: "0" }
+      }, { preventBeforeUpdateListener: true, preventChildrenUpdate: true });
     }
     clearTimeout(heightTimeout);
   });