@overpunch/vf-clamp 2.2.0 → 2.4.0

package/dist/index.d.ts

@@ -56,8 +56,9 @@ export declare interface ClampOptions {
      */
     format?: OutputFormat;
     /**
-     * Refuse any instances-based output whose range would include a named instance that was not listed
-     * (e.g. Regular + Bold would also hand over Medium and SemiBold). Throws instead of clamping.
+     * Refuse any output whose range would include a named instance that was not listed
+     * (e.g. Regular + Bold would also hand over Medium and SemiBold). Axes-only outputs list none,
+     * so they pass only if their range holds no named instance. Throws instead of clamping.
      * Use planOutputs() to split a customer's selection into safe outputs. Defaults to false.
      */
     strict?: boolean;
@@ -117,6 +118,10 @@ export declare interface FontInstancesResult {
     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>>;
 }
 
 /**
@@ -129,6 +134,9 @@ export declare interface FontInstancesResult {
  */
 export declare function getInstances(input: ArrayBuffer | Uint8Array | Buffer): Promise<FontInstancesResult>;
 
+/** 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.
@@ -166,17 +174,39 @@ export declare type PinnedAxis = number;
  *
  * 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 compactName(), optionally prefixed
+ * (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
+ * @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;
+
 /** @deprecated Use OutputConfig instead */
 export declare type SubfamilyConfig = OutputConfig;