@overpunch/vf-clamp 2.3.0 → 2.4.0

package/dist/naming.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function B(t,s){if(t===s)return t;const e=t.split(" "),r=s.split(" ");let a=0;for(;a<e.length&&a<r.length&&e[a]===r[a];)a++;let i=0;for(;i<e.length-a&&i<r.length-a&&e[e.length-1-i]===r[r.length-1-i];)i++;const g=e.slice(0,a).join(" "),l=e.slice(a,e.length-(i||0)).join(" "),p=r.slice(a,r.length-(i||0)).join(" "),d=i>0?e.slice(e.length-i).join(" "):"",x=l&&p?`${l}-${p}`:l||p;return[g,x,d].filter(Boolean).join(" ")}function E(t,s){const e=s.filter(r=>r.name===t);if(!e.length)throw new Error(`Named instance "${t}" not found in font`);if(e.length>1)throw new Error(`Named instance "${t}" is ambiguous: ${e.length} instances share that name`);return e[0]}const D={wght:"Regular",wdth:"Normal",ital:"Upright",slnt:"Upright"};function y(t){return t.toFixed(6).replace(/0+$/,"").replace(/\.$/,"")}function S(t){return(t||"").split(/\s+/).filter(Boolean)}function F(t,s,e,r={}){if(!t.length)return"";if(t.length===1)return t[0].name;const a=Object.fromEntries(e.map(n=>[n.tag,n.default])),i=e.map(n=>n.tag),g=(n,o)=>n.coordinates[o]??a[o],l=i.filter(n=>new Set(s.map(o=>g(o,n))).size>1),p=new Map,d=n=>{if(!p.has(n)){const o=s.filter(m=>S(m.name).includes(n)),f=o.length?l.filter(m=>new Set(o.map(w=>g(w,m))).size===1):[];p.set(n,f.length===1?f[0]:null)}return p.get(n)},x=(n,o)=>{const f=s.filter(m=>g(m,n)===o);return f.length?S(f[0].name).filter(m=>d(m)===n&&f.every(w=>S(w.name).includes(m))).join(" "):""},c=(n,o)=>{var f;return((f=r[n])==null?void 0:f[y(o)])||D[n]||`${n}${y(o)}`},u=n=>new Set(S(n.name).map(d).filter(o=>o!==null)),h=s.filter(n=>u(n).size>1),b=h.length?h:s,L=n=>{const o=b.flatMap(f=>S(f.name).flatMap((m,w)=>d(m)===n?[w]:[]));return o.length?Math.min(...o):1e4},O=[];i.forEach((n,o)=>{const f=[...new Set(t.map($=>g($,n)))].sort(($,M)=>$-M),m=f[0],w=f[f.length-1];let v;if(m===w){if(v=x(n,m),!v)return}else{const $=x(n,m)||c(n,m),M=x(n,w)||c(n,w);v=$===M?$:`${$}-${M}`}O.push([L(n),o,v])}),O.sort((n,o)=>n[0]-o[0]||n[1]-o[1]);const j=S(t[0].name),k=j.filter(n=>d(n)===null&&t.every(o=>S(o.name).includes(n))),A=j.flatMap((n,o)=>d(n)!==null?[o]:[]),z=A.length?Math.min(...A):j.length,P=k.filter(n=>j.indexOf(n)<z),U=k.filter(n=>j.indexOf(n)>=z);return[...P,...O.map(n=>n[2]),...U].join(" ").trim()||`${t[0].name}-${t[t.length-1].name}`}function I(t,s){const e={};for(const r of s){const a=t.map(i=>i.coordinates[r.tag]??r.default);e[r.tag]={min:Math.min(...a),max:Math.max(...a)}}return e}function N(t,s,e,r){return s.filter(a=>e.has(a)?!1:r.every(i=>{const g=a.coordinates[i.tag]??i.default,l=t[i.tag];return!l||g>=l.min&&g<=l.max}))}function K(t){return t.reduce((s,e)=>!s||e.maximum-e.minimum>s.maximum-s.minimum?e:s,void 0)}function R(t,s,e){const{axes:r,instances:a}=t,i=[...new Set(s)].map(c=>E(c,a));if(!i.length)return[];const g=new Set(i);let l;if(!N(I(i,r),a,g,r).length)l=[i];else{l=i.map(u=>[u]);let c=!0;for(;c;){c=!1;n:for(let u=0;u<l.length;u++)for(let h=u+1;h<l.length;h++){const b=[...l[u],...l[h]];if(!N(I(b,r),a,g,r).length){l[u]=b,l.splice(h,1),c=!0;break n}}}}const p=K(r),d=p?[p,...r.filter(c=>c.tag!==p.tag)]:r,x=(c,u)=>{for(const h of d){const b=(c.coordinates[h.tag]??h.default)-(u.coordinates[h.tag]??h.default);if(b)return b}return 0};return l=l.map(c=>[...c].sort(x)).sort((c,u)=>x(c[0],u[0])),l.map(c=>{const u=F(c,a,r,t.labels??{});return{name:e?`${e} ${u}`:u,instances:c.map(h=>h.name)}})}function T(t,s){const e=s.map(r=>E(r,t.instances));return e.length?N(I(e,t.axes),t.instances,new Set(e),t.axes).map(r=>r.name):[]}exports.compactName=B;exports.findInstance=E;exports.numberKey=y;exports.planOutputs=R;exports.rangeName=F;exports.unboughtInstances=T;

package/dist/naming.d.ts

@@ -0,0 +1,149 @@
+/** One axis defined in the font's fvar table */
+export declare interface AxisDefinition {
+    /** Four-character axis tag, e.g. "wght", "wdth" */
+    tag: string;
+    /** Human-readable axis name from the font's name table */
+    name: string;
+    /** Minimum value on the axis */
+    minimum: number;
+    /** Default value (used when axis is not explicitly set) */
+    default: number;
+    /** Maximum value on the axis */
+    maximum: number;
+}
+
+/** Restrict an axis to a sub-range — the axis remains variable but clamped to [min, max] */
+declare interface AxisRange {
+    /** Minimum value on the axis */
+    min: number;
+    /** Maximum value on the axis */
+    max: number;
+}
+
+/**
+ * What to do with one axis when clamping a variable font:
+ * - number: pin to that value (axis locked and removed from output design space)
+ * - AxisRange: restrict to [min, max] (axis stays variable within that range)
+ * - null: omit this axis from the instancer call — axis keeps its full original range
+ *
+ * Axes not listed in the config also keep their full original range.
+ * Note: JS→Python bridge limitations prevent true axis dropping (fonttools' Python `None` semantic).
+ */
+declare type AxisValue = PinnedAxis | AxisRange | null;
+
+/**
+ * Produce a compact display name from the first and last selected instance names.
+ * Strips shared leading prefix and trailing suffix tokens, joins differing parts with a dash.
+ *
+ * Examples:
+ *   compactName('Inter Light', 'Inter Bold')         → 'Inter Light-Bold'
+ *   compactName('Condensed Thin', 'Condensed Black') → 'Condensed Thin-Black'
+ *   compactName('Regular', 'Regular')                → 'Regular'
+ *
+ * Canonical implementation — also duplicated in the Python plugins and VS Code webview
+ * (both sandboxed contexts that cannot import this package at runtime).
+ */
+export declare function compactName(first: string, last: string): string;
+
+/**
+ * Finds a named instance by name. Throws if it is missing, or if several instances share the name
+ * (e.g. "Bold" at two optical sizes), since a name alone can't say which one was bought.
+ */
+export declare function findInstance(name: string, fontInstances: FontInstance[]): FontInstance;
+
+/** One named instance from the font's fvar table */
+export declare interface FontInstance {
+    /** Instance name from the font's name table, e.g. "Regular", "Bold Condensed" */
+    name: string;
+    /** Axis coordinates for this instance, e.g. { wght: 400, wdth: 100 } */
+    coordinates: Record<string, number>;
+}
+
+/** Result of getInstances() — describes the full design space of a variable font */
+export declare interface FontInstancesResult {
+    /** All variable axes defined in the font */
+    axes: AxisDefinition[];
+    /** All named instances defined in the font */
+    instances: FontInstance[];
+    /** The font's family name (typographic family, nameID 16, else nameID 1); used to name outputs that set no name */
+    family?: string;
+    /** STAT names by axis tag and value key (numberKey), e.g. { wdth: { '100': 'Normal' } }; used for default names */
+    labels?: Record<string, Record<string, string>>;
+}
+
+/** Stable text key for an axis value, identical to number_key() in Python ('100', '87.5'). */
+export declare function numberKey(value: number): string;
+
+/**
+ * One output variant to produce from the source variable font.
+ * Specify instances, axes, or both — instances set the hull, axes override individual tags.
+ */
+export declare interface OutputConfig {
+    /** Name for this output — used in ClampResult.name. Defaults to instance range when omitted. */
+    name?: string;
+    /**
+     * Named instances to include. The axis hull (min/max per axis) is computed automatically
+     * across all listed instances — producing one variable font that spans exactly that range.
+     * Instance names must match the font's fvar name table exactly.
+     */
+    instances?: string[];
+    /**
+     * Explicit axis constraints, applied after any instance hull.
+     * Axes listed here override the hull computed from instances for that tag.
+     * Axis tags not listed keep their full original range.
+     */
+    axes?: Record<string, AxisValue>;
+}
+
+/** Pin an axis at a single value — the axis is locked and removed from the output font's design space */
+declare type PinnedAxis = number;
+
+/**
+ * Groups a customer's selected named instances into clampFont outputs so that no output's range
+ * contains a named instance the customer did not select.
+ *
+ * Selections merge into one output only when their combined range holds no unselected named
+ * instance: Regular + Medium + SemiBold + Bold → one output; Regular + Bold alone → two outputs
+ * (each pinned to its own instance). Output names come from rangeName() (one range per axis), optionally prefixed
+ * with `family`.
+ *
+ * @param font - The font's axes and named instances, from getInstances()
+ * @param selected - Names of the instances the customer bought (must match exactly)
+ * @param family - Optional family name to prefix each output name with, e.g. "Encode Sans"
+ * @returns OutputConfig entries ready for clampFont(), sorted along the primary axis
+ * @throws If a selected name is not a named instance of the font, or names more than one (ambiguous)
+ */
+export declare function planOutputs(font: FontInstancesResult, selected: string[], family?: string): OutputConfig[];
+
+/**
+ * Default name for a selection of named instances: one range per axis, in the font's own style words
+ * ("SemiCondensed-Normal Thin-Light"). TypeScript twin of range_name() in
+ * shared/plugin-views/vfclamp_naming.py; both are checked against shared/naming-cases.json, so change
+ * them together.
+ *
+ * Each word is attributed to the one axis that is constant wherever the word appears and varies across
+ * the font. An axis that varies in the selection becomes "low-high"; one that doesn't shows its word
+ * once, or nothing when that value has no word. A value with no word takes its STAT label, else a
+ * default word, else "<tag><value>". Parts follow the order the font's names use; words shared by every
+ * selected name and owned by no axis stay before or after them.
+ *
+ * @param selected - The selected named instances
+ * @param instances - Every named instance of the font
+ * @param axes - The font's axes (tag and default)
+ * @param labels - STAT names by axis tag and numberKey(value), e.g. { wdth: { '100': 'Normal' } }
+ */
+export declare function rangeName(selected: FontInstance[], instances: FontInstance[], axes: Array<{
+    tag: string;
+    default: number;
+}>, labels?: Record<string, Record<string, string>>): string;
+
+/**
+ * Lists the named instances that a single output built from `names` would include without being selected,
+ * e.g. ['Medium', 'SemiBold'] for Regular + Bold. An empty array means the output is purchase-safe.
+ *
+ * @param font - The font's axes and named instances, from getInstances()
+ * @param names - The instance names one output would hull
+ */
+export declare function unboughtInstances(font: FontInstancesResult, names: string[]): string[];
+
+export { }

package/dist/naming.js

@@ -0,0 +1,121 @@
+function W(t, s) {
+  if (t === s) return t;
+  const e = t.split(" "), r = s.split(" ");
+  let a = 0;
+  for (; a < e.length && a < r.length && e[a] === r[a]; )
+    a++;
+  let i = 0;
+  for (; i < e.length - a && i < r.length - a && e[e.length - 1 - i] === r[r.length - 1 - i]; )
+    i++;
+  const g = e.slice(0, a).join(" "), l = e.slice(a, e.length - (i || 0)).join(" "), p = r.slice(a, r.length - (i || 0)).join(" "), d = i > 0 ? e.slice(e.length - i).join(" ") : "", x = l && p ? `${l}-${p}` : l || p;
+  return [g, x, d].filter(Boolean).join(" ");
+}
+function z(t, s) {
+  const e = s.filter((r) => r.name === t);
+  if (!e.length) throw new Error(`Named instance "${t}" not found in font`);
+  if (e.length > 1) throw new Error(`Named instance "${t}" is ambiguous: ${e.length} instances share that name`);
+  return e[0];
+}
+const B = { wght: "Regular", wdth: "Normal", ital: "Upright", slnt: "Upright" };
+function A(t) {
+  return t.toFixed(6).replace(/0+$/, "").replace(/\.$/, "");
+}
+function j(t) {
+  return (t || "").split(/\s+/).filter(Boolean);
+}
+function D(t, s, e, r = {}) {
+  if (!t.length) return "";
+  if (t.length === 1) return t[0].name;
+  const a = Object.fromEntries(e.map((n) => [n.tag, n.default])), i = e.map((n) => n.tag), g = (n, o) => n.coordinates[o] ?? a[o], l = i.filter((n) => new Set(s.map((o) => g(o, n))).size > 1), p = /* @__PURE__ */ new Map(), d = (n) => {
+    if (!p.has(n)) {
+      const o = s.filter((m) => j(m.name).includes(n)), f = o.length ? l.filter((m) => new Set(o.map((w) => g(w, m))).size === 1) : [];
+      p.set(n, f.length === 1 ? f[0] : null);
+    }
+    return p.get(n);
+  }, x = (n, o) => {
+    const f = s.filter((m) => g(m, n) === o);
+    return f.length ? j(f[0].name).filter((m) => d(m) === n && f.every((w) => j(w.name).includes(m))).join(" ") : "";
+  }, c = (n, o) => {
+    var f;
+    return ((f = r[n]) == null ? void 0 : f[A(o)]) || B[n] || `${n}${A(o)}`;
+  }, u = (n) => new Set(j(n.name).map(d).filter((o) => o !== null)), h = s.filter((n) => u(n).size > 1), $ = h.length ? h : s, F = (n) => {
+    const o = $.flatMap((f) => j(f.name).flatMap((m, w) => d(m) === n ? [w] : []));
+    return o.length ? Math.min(...o) : 1e4;
+  }, O = [];
+  i.forEach((n, o) => {
+    const f = [...new Set(t.map((b) => g(b, n)))].sort((b, M) => b - M), m = f[0], w = f[f.length - 1];
+    let v;
+    if (m === w) {
+      if (v = x(n, m), !v) return;
+    } else {
+      const b = x(n, m) || c(n, m), M = x(n, w) || c(n, w);
+      v = b === M ? b : `${b}-${M}`;
+    }
+    O.push([F(n), o, v]);
+  }), O.sort((n, o) => n[0] - o[0] || n[1] - o[1]);
+  const S = j(t[0].name), I = S.filter((n) => d(n) === null && t.every((o) => j(o.name).includes(n))), N = S.flatMap((n, o) => d(n) !== null ? [o] : []), k = N.length ? Math.min(...N) : S.length, L = I.filter((n) => S.indexOf(n) < k), U = I.filter((n) => S.indexOf(n) >= k);
+  return [...L, ...O.map((n) => n[2]), ...U].join(" ").trim() || `${t[0].name}-${t[t.length - 1].name}`;
+}
+function y(t, s) {
+  const e = {};
+  for (const r of s) {
+    const a = t.map((i) => i.coordinates[r.tag] ?? r.default);
+    e[r.tag] = { min: Math.min(...a), max: Math.max(...a) };
+  }
+  return e;
+}
+function E(t, s, e, r) {
+  return s.filter((a) => e.has(a) ? !1 : r.every((i) => {
+    const g = a.coordinates[i.tag] ?? i.default, l = t[i.tag];
+    return !l || g >= l.min && g <= l.max;
+  }));
+}
+function P(t) {
+  return t.reduce((s, e) => !s || e.maximum - e.minimum > s.maximum - s.minimum ? e : s, void 0);
+}
+function _(t, s, e) {
+  const { axes: r, instances: a } = t, i = [...new Set(s)].map((c) => z(c, a));
+  if (!i.length) return [];
+  const g = new Set(i);
+  let l;
+  if (!E(y(i, r), a, g, r).length)
+    l = [i];
+  else {
+    l = i.map((u) => [u]);
+    let c = !0;
+    for (; c; ) {
+      c = !1;
+      n: for (let u = 0; u < l.length; u++)
+        for (let h = u + 1; h < l.length; h++) {
+          const $ = [...l[u], ...l[h]];
+          if (!E(y($, r), a, g, r).length) {
+            l[u] = $, l.splice(h, 1), c = !0;
+            break n;
+          }
+        }
+    }
+  }
+  const p = P(r), d = p ? [p, ...r.filter((c) => c.tag !== p.tag)] : r, x = (c, u) => {
+    for (const h of d) {
+      const $ = (c.coordinates[h.tag] ?? h.default) - (u.coordinates[h.tag] ?? h.default);
+      if ($) return $;
+    }
+    return 0;
+  };
+  return l = l.map((c) => [...c].sort(x)).sort((c, u) => x(c[0], u[0])), l.map((c) => {
+    const u = D(c, a, r, t.labels ?? {});
+    return { name: e ? `${e} ${u}` : u, instances: c.map((h) => h.name) };
+  });
+}
+function C(t, s) {
+  const e = s.map((r) => z(r, t.instances));
+  return e.length ? E(y(e, t.axes), t.instances, new Set(e), t.axes).map((r) => r.name) : [];
+}
+export {
+  W as compactName,
+  z as findInstance,
+  A as numberKey,
+  _ as planOutputs,
+  D as rangeName,
+  C as unboughtInstances
+};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@overpunch/vf-clamp",
-	"version": "2.3.0",
+	"version": "2.4.0",
 	"description": "Restrict a variable font's axis ranges to the named styles a customer bought — like CSS clamp() for design space.",
 	"type": "module",
 	"main": "dist/index.cjs",
@@ -10,6 +10,11 @@
 			"types": "./dist/index.d.ts",
 			"import": "./dist/index.js",
 			"require": "./dist/index.cjs"
+		},
+		"./naming": {
+			"types": "./dist/naming.d.ts",
+			"import": "./dist/naming.js",
+			"require": "./dist/naming.cjs"
 		}
 	},
 	"files": [