@taprootio/espalier 4.7.0 → 4.8.0

package/custom-elements.json

@@ -76118,6 +76118,48 @@
       "declarations": [],
       "exports": []
     },
+    {
+      "kind": "javascript-module",
+      "path": "dist/shared/theme-properties.js",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "computeThemeProperties",
+          "return": {
+            "type": {
+              "text": "Record<string, string>"
+            }
+          },
+          "parameters": [
+            {
+              "name": "theme",
+              "type": {
+                "text": "EspalierTheme"
+              },
+              "description": "A resolved theme."
+            },
+            {
+              "name": "scheme",
+              "type": {
+                "text": "ThemeScheme"
+              },
+              "description": "The scheme to compute, matching the theme it came from."
+            }
+          ],
+          "description": "Compute every CSS custom property for a resolved theme and scheme.\n\nThe result is a flat record keyed by property name including the leading\n`--`, exactly as `esp-root` writes it: scheme indicator, seed, variant and\ndata colors, the lightness ramp, APCA-enforced semantic colors, data\ncompanions, the type and space scales, font families and weights, and the\noptional background-image and vellum properties a theme declares.\n\nPass a **resolved** theme — one merged over `DEFAULT_LIGHT_THEME` or\n`DEFAULT_DARK_THEME` with `mergeTheme` from `./shared/theme`. An unparseable\n`seedColor` yields an empty record rather than throwing, and an unresolvable\ncolor source falls back to the seed with a `console.warn`, so a bad theme\nrenders branded rather than broken; use `validateTheme(encodeTheme(partial))`\nfrom `./shared/theme` to surface those before rendering."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "computeThemeProperties",
+          "declaration": {
+            "name": "computeThemeProperties",
+            "module": "dist/shared/theme-properties.js"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "dist/shared/theme-swatches.js",

package/dist/shared/font-helpers.js

@@ -1 +1 @@
-const m={100:"100 Thin",200:"200 Extra Light",300:"300 Light",400:"400 Regular",500:"500 Medium",600:"600 Semi Bold",700:"700 Bold",800:"800 Extra Bold",900:"900 Black"};function d(e){if(!e)return["400"];const t=new Set;for(const r of e.variants)r.includes("italic")||t.add(r==="regular"?"400":r);const n=[...t].sort((r,o)=>Number(r)-Number(o));return n.length>0?n:["400"]}function h(e,t){return e?e==="bold"?"700":e==="normal"?"400":e:t}function u(e,t){const n=e===void 0||e===""?t:e;if(n===void 0)return null;if(typeof n=="number")return Number.isInteger(n)&&n>=1&&n<=1e3?n:null;const r=n.trim().toLowerCase();if(r==="normal")return 400;if(r==="bold")return 700;if(!/^\d{1,4}$/.test(r))return null;const o=Number(r);return Number.isInteger(o)&&o>=1&&o<=1e3?o:null}function g(e,t){if(t.length===0)return"400";if(t.includes(e))return e;const n=Number(e);let r=t[0],o=Math.abs(Number(r)-n);for(const s of t){const i=Math.abs(Number(s)-n);i<o&&(r=s,o=i)}return r}function p(e){let t="",n="",r=!1,o=0;for(const i of e.trim()){if(r){t+=i,r=!1;continue}if(i==="\\"){t+=i,r=!0;continue}if(n){t+=i,i===n&&(n="");continue}if(i==='"'||i==="'"){t+=i,n=i;continue}if(i==="("&&(o+=1),i===")"&&(o=Math.max(0,o-1)),i===","&&o===0)break;t+=i}const s=t.trim();return s.length>=2&&(s.startsWith('"')&&s.endsWith('"')||s.startsWith("'")&&s.endsWith("'"))?s.slice(1,-1).replace(/\\([\\"'])/g,"$1"):s}const l=new Set(["serif","sans-serif","monospace","cursive","fantasy","system-ui","ui-serif","ui-sans-serif","ui-monospace","ui-rounded","math","fangsong","-apple-system","blinkmacsystemfont","arial","helvetica","helvetica neue","liberation sans","verdana","tahoma","trebuchet ms","georgia","times new roman","courier new","segoe ui"].map(e=>e.toLowerCase()));function b(e){return l.has(e.trim().toLowerCase())}function x(e){switch(e){case"serif":return"serif";case"monospace":return"monospace";case"handwriting":return"cursive";default:return"sans-serif"}}const a="data-esp-google-font-owner";function f(e,t){const n=u(t,400)??400,r=n!==400?`:wght@${n}`:"";return`https://fonts.googleapis.com/css2?family=${encodeURIComponent(e)}${r}&display=swap`}function c(e){return document.head.querySelector(`link[${a}="${CSS.escape(e)}"]`)}function y(e){const t=c(e.owner),n=e.family.trim(),r=String(u(e.weight,400)??400);if(e.enabled===!1||!n)return t?.remove(),null;if(t?.dataset.espFamily===n&&t.dataset.espWeight===r)return t;t?.remove();const o=document.createElement("link");o.rel="stylesheet",o.href=f(n,r),o.setAttribute(a,e.owner),o.dataset.espFamily=n,o.dataset.espWeight=r;for(const[s,i]of Object.entries(e.attributes??{}))o.setAttribute(s,i);return document.head.appendChild(o),o}function F(e){c(e)?.remove()}function L(e){for(const t of document.head.querySelectorAll(`link[${a}]`))t.getAttribute(a)?.startsWith(e)&&t.remove()}export{a as RUNTIME_GOOGLE_FONT_OWNER_ATTR,m as WEIGHT_LABELS,g as bestAvailableWeight,p as extractFamily,d as extractWeights,x as getFallbackFont,f as googleFontStylesheetUrl,b as isLocalFontFamily,u as normalizeFontFaceWeight,h as normalizeWeight,F as removeRuntimeGoogleFontLink,L as removeRuntimeGoogleFontLinks,y as syncRuntimeGoogleFontLink};
+const m={100:"100 Thin",200:"200 Extra Light",300:"300 Light",400:"400 Regular",500:"500 Medium",600:"600 Semi Bold",700:"700 Bold",800:"800 Extra Bold",900:"900 Black"};function d(e){if(!e)return["400"];const t=new Set;for(const r of e.variants)r.includes("italic")||t.add(r==="regular"?"400":r);const n=[...t].sort((r,o)=>Number(r)-Number(o));return n.length>0?n:["400"]}function h(e,t){return e?e==="bold"?"700":e==="normal"?"400":e:t}function u(e,t){const n=e===void 0||e===""?t:e;if(n===void 0)return null;if(typeof n=="number")return Number.isInteger(n)&&n>=1&&n<=1e3?n:null;const r=n.trim().toLowerCase();if(r==="normal")return 400;if(r==="bold")return 700;if(!/^\d{1,4}$/.test(r))return null;const o=Number(r);return Number.isInteger(o)&&o>=1&&o<=1e3?o:null}function g(e,t){if(t.length===0)return"400";if(t.includes(e))return e;const n=Number(e);let r=t[0],o=Math.abs(Number(r)-n);for(const s of t){const i=Math.abs(Number(s)-n);i<o&&(r=s,o=i)}return r}function p(e){let t="",n="",r=!1,o=0;for(const i of e.trim()){if(r){t+=i,r=!1;continue}if(i==="\\"){t+=i,r=!0;continue}if(n){t+=i,i===n&&(n="");continue}if(i==='"'||i==="'"){t+=i,n=i;continue}if(i==="("&&(o+=1),i===")"&&(o=Math.max(0,o-1)),i===","&&o===0)break;t+=i}const s=t.trim();return s.length>=2&&(s.startsWith('"')&&s.endsWith('"')||s.startsWith("'")&&s.endsWith("'"))?s.slice(1,-1).replace(/\\([\\"'])/g,"$1"):s}const l=new Set(["serif","sans-serif","monospace","cursive","fantasy","system-ui","ui-serif","ui-sans-serif","ui-monospace","ui-rounded","math","fangsong","-apple-system","blinkmacsystemfont","arial","helvetica","helvetica neue","liberation sans","liberation serif","liberation mono","verdana","tahoma","trebuchet ms","georgia","times new roman","courier new","segoe ui"].map(e=>e.toLowerCase()));function b(e){return l.has(e.trim().toLowerCase())}function x(e){switch(e){case"serif":return"serif";case"monospace":return"monospace";case"handwriting":return"cursive";default:return"sans-serif"}}const a="data-esp-google-font-owner";function f(e,t){const n=u(t,400)??400,r=n!==400?`:wght@${n}`:"";return`https://fonts.googleapis.com/css2?family=${encodeURIComponent(e)}${r}&display=swap`}function c(e){return document.head.querySelector(`link[${a}="${CSS.escape(e)}"]`)}function y(e){const t=c(e.owner),n=e.family.trim(),r=String(u(e.weight,400)??400);if(e.enabled===!1||!n)return t?.remove(),null;if(t?.dataset.espFamily===n&&t.dataset.espWeight===r)return t;t?.remove();const o=document.createElement("link");o.rel="stylesheet",o.href=f(n,r),o.setAttribute(a,e.owner),o.dataset.espFamily=n,o.dataset.espWeight=r;for(const[s,i]of Object.entries(e.attributes??{}))o.setAttribute(s,i);return document.head.appendChild(o),o}function F(e){c(e)?.remove()}function L(e){for(const t of document.head.querySelectorAll(`link[${a}]`))t.getAttribute(a)?.startsWith(e)&&t.remove()}export{a as RUNTIME_GOOGLE_FONT_OWNER_ATTR,m as WEIGHT_LABELS,g as bestAvailableWeight,p as extractFamily,d as extractWeights,x as getFallbackFont,f as googleFontStylesheetUrl,b as isLocalFontFamily,u as normalizeFontFaceWeight,h as normalizeWeight,F as removeRuntimeGoogleFontLink,L as removeRuntimeGoogleFontLinks,y as syncRuntimeGoogleFontLink};

package/dist/shared/theme-properties.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Public entry point for Espalier's theme → CSS custom property computation.
+ *
+ * `esp-root` hydrates a page by writing the result of this computation onto its
+ * host. A generator or server that renders the same page's shell — Taproot
+ * computes a published site's first-paint background this way — needs the same
+ * answer before any element upgrades, and must get it without importing a
+ * component module or a private package path.
+ *
+ * This module declares its own signature rather than re-exporting the internal
+ * implementation, so the published type graph stays limited to `EspalierTheme`
+ * from the already-public `./shared/theme` while the runtime still calls the
+ * one implementation — a generator and `esp-root` cannot compute different
+ * colors. The build-gate rationale for that shape is recorded in the
+ * repository's public-type-surface record, which is not published.
+ *
+ * The module is side-effect free: importing it registers no custom element and
+ * touches no DOM.
+ */
+import type { EspalierTheme } from "./theme.js";
+/** The two color schemes a theme resolves for. */
+export type ThemeScheme = "light" | "dark";
+/**
+ * Compute every CSS custom property for a resolved theme and scheme.
+ *
+ * The result is a flat record keyed by property name including the leading
+ * `--`, exactly as `esp-root` writes it: scheme indicator, seed, variant and
+ * data colors, the lightness ramp, APCA-enforced semantic colors, data
+ * companions, the type and space scales, font families and weights, and the
+ * optional background-image and vellum properties a theme declares.
+ *
+ * Pass a **resolved** theme — one merged over `DEFAULT_LIGHT_THEME` or
+ * `DEFAULT_DARK_THEME` with `mergeTheme` from `./shared/theme`. An unparseable
+ * `seedColor` yields an empty record rather than throwing, and an unresolvable
+ * color source falls back to the seed with a `console.warn`, so a bad theme
+ * renders branded rather than broken; use `validateTheme(encodeTheme(partial))`
+ * from `./shared/theme` to surface those before rendering.
+ *
+ * @param theme A resolved theme.
+ * @param scheme The scheme to compute, matching the theme it came from.
+ */
+export declare function computeThemeProperties(theme: EspalierTheme, scheme: ThemeScheme): Record<string, string>;

package/dist/shared/theme-properties.js

@@ -0,0 +1 @@
+import{computeThemeProperties as o}from"../root/helpers/compute-theme-properties.js";function m(e,r){return o(e,r)}export{m as computeThemeProperties};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/espalier",
-  "version": "4.7.0",
+  "version": "4.8.0",
   "packageManager": "bun@1.3.12",
   "description": "Espalier — a themeable, accessible, framework-agnostic, enterprise-grade design system built on web standards and love.",
   "customElements": "custom-elements.json",
@@ -305,6 +305,10 @@
       "types": "./dist/shared/theme.d.ts",
       "import": "./dist/shared/theme.js"
     },
+    "./shared/theme-properties": {
+      "types": "./dist/shared/theme-properties.d.ts",
+      "import": "./dist/shared/theme-properties.js"
+    },
     "./shared/data-colors": {
       "types": "./dist/shared/data-colors.d.ts",
       "import": "./dist/shared/data-colors.js"
@@ -333,6 +337,10 @@
       "types": "./dist/shared/justified-layout.d.ts",
       "import": "./dist/shared/justified-layout.js"
     },
+    "./shared/image-texture-registry": {
+      "types": "./dist/shared/image-texture-registry.d.ts",
+      "import": "./dist/shared/image-texture-registry.js"
+    },
     "./shared/esp-bus": {
       "types": "./dist/shared/esp-bus.d.ts",
       "import": "./dist/shared/esp-bus.js"