@cutoff/audio-ui-core 1.0.0-preview.20260123.1125

package/dist/utils/valueFormatters.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Collection of reusable value formatters for control components
+ */
+/**
+ * Calculates the center value for a range according to MIDI conventions.
+ *
+ * This is used for bipolar controls (pan, modulation depth) where the center point
+ * represents zero or neutral. The formula ensures proper centering for both even
+ * and odd ranges.
+ *
+ * @param min The minimum value
+ * @param max The maximum value
+ * @returns The center value according to MIDI conventions (floor((max - min + 1) / 2) + min)
+ *
+ * @example
+ * ```ts
+ * calculateCenterValue(-64, 63); // 0 (bipolar 7-bit MIDI)
+ * calculateCenterValue(0, 100); // 50
+ * ```
+ */
+export declare const calculateCenterValue: (min: number, max: number) => number;
+/**
+ * Formats a value with a bipolar display (adds + sign for positive values).
+ *
+ * This is useful for displaying values that can be positive or negative, such as
+ * pan controls or modulation depth. Zero and negative values are displayed as-is,
+ * while positive values get a "+" prefix.
+ *
+ * @param value The value to format
+ * @returns Formatted string with + prefix for positive values
+ *
+ * @example
+ * ```ts
+ * bipolarFormatter(50); // "+50"
+ * bipolarFormatter(-50); // "-50"
+ * bipolarFormatter(0); // "0"
+ * ```
+ */
+export declare const bipolarFormatter: (value: number) => string;
+/**
+ * Formats a value with MIDI bipolar convention (shifts value by center value).
+ *
+ * This formatter is designed for MIDI-style bipolar parameters where the raw value
+ * is in the range [min, max], but you want to display it as an offset from center.
+ * For example, a pan control with range [0, 127] centered at 64 would display as
+ * "+3" when the value is 67.
+ *
+ * @param value The value to format
+ * @param min The minimum value
+ * @param max The maximum value
+ * @returns Formatted string with the value shifted by center value
+ *
+ * @example
+ * ```ts
+ * midiBipolarFormatter(67, 0, 127); // "+3" (67 - 64 = 3)
+ * midiBipolarFormatter(60, 0, 127); // "-4" (60 - 64 = -4)
+ * ```
+ */
+export declare const midiBipolarFormatter: (value: number, min: number, max: number) => string;
+/**
+ * Creates a formatter function that appends a unit suffix to values.
+ *
+ * This is a higher-order function that returns a formatter. Useful for creating
+ * reusable formatters for parameters with units (dB, Hz, ms, etc.).
+ *
+ * @param unit The unit to append (e.g., "dB", "Hz", "ms")
+ * @returns A formatter function that appends the unit
+ *
+ * @example
+ * ```ts
+ * const dbFormatter = withUnit("dB");
+ * dbFormatter(-6.0); // "-6.0dB"
+ *
+ * // Can be combined with other formatters
+ * const formatter = combineFormatters(withPrecision(1), withUnit("Hz"));
+ * formatter(440.5); // "440.5Hz"
+ * ```
+ */
+export declare const withUnit: (unit: string) => (value: number) => string;
+/**
+ * Creates a formatter function that formats values with fixed decimal precision.
+ *
+ * This is a higher-order function that returns a formatter. Useful for ensuring
+ * consistent decimal display across your application.
+ *
+ * @param precision Number of decimal places (0-20)
+ * @returns A formatter function that formats with the specified precision
+ *
+ * @example
+ * ```ts
+ * const twoDecimals = withPrecision(2);
+ * twoDecimals(3.14159); // "3.14"
+ *
+ * // Can be combined with other formatters
+ * const formatter = combineFormatters(withPrecision(1), withUnit("dB"));
+ * formatter(-6.02); // "-6.0dB"
+ * ```
+ */
+export declare const withPrecision: (precision: number) => (value: number) => string;
+/**
+ * Combines multiple formatters into a single formatter function.
+ *
+ * Formatters are applied in sequence, with each formatter receiving the output
+ * of the previous one (after parsing back to a number if needed). This allows
+ * you to compose complex formatting pipelines.
+ *
+ * @param formatters Array of formatter functions to apply in sequence
+ * @returns A formatter function that applies all formatters in sequence
+ *
+ * @example
+ * ```ts
+ * // Combine precision and unit formatting
+ * const formatter = combineFormatters(
+ *   withPrecision(1),
+ *   withUnit("dB")
+ * );
+ * formatter(-6.02); // "-6.0dB"
+ *
+ * // Combine multiple transformations
+ * const complexFormatter = combineFormatters(
+ *   (v) => (v * 100).toString(), // Convert to percentage
+ *   withUnit("%")
+ * );
+ * complexFormatter(0.5); // "50%"
+ * ```
+ */
+export declare const combineFormatters: (...formatters: ((value: number, min?: number, max?: number) => string)[]) => (value: number, min?: number, max?: number) => string;
+/**
+ * Formats a value as a percentage based on its position in the min-max range.
+ *
+ * The percentage is calculated as: ((value - min) / (max - min)) * 100
+ * and rounded to the nearest integer.
+ *
+ * @param value The value to format
+ * @param min The minimum value (corresponds to 0%)
+ * @param max The maximum value (corresponds to 100%)
+ * @returns Formatted percentage string (e.g., "50%")
+ *
+ * @example
+ * ```ts
+ * percentageFormatter(50, 0, 100); // "50%"
+ * percentageFormatter(25, 0, 100); // "25%"
+ * percentageFormatter(75, 0, 200); // "38%" (75/200 = 37.5%, rounded to 38%)
+ * ```
+ */
+export declare const percentageFormatter: (value: number, min: number, max: number) => string;
+/**
+ * Formats a frequency value with appropriate units (Hz or kHz).
+ *
+ * Values >= 1000 Hz are displayed in kHz with one decimal place.
+ * Values < 1000 Hz are displayed in Hz as integers.
+ *
+ * This is optimized for audio frequency display where values can range from
+ * sub-audio (20 Hz) to ultrasonic (20 kHz+).
+ *
+ * @param value The frequency value in Hz
+ * @returns Formatted string with appropriate units (Hz, kHz)
+ *
+ * @example
+ * ```ts
+ * frequencyFormatter(440); // "440Hz"
+ * frequencyFormatter(1000); // "1.0kHz"
+ * frequencyFormatter(15000); // "15.0kHz"
+ * ```
+ */
+export declare const frequencyFormatter: (value: number) => string;
+//# sourceMappingURL=valueFormatters.d.ts.map

package/dist/utils/valueFormatters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"valueFormatters.d.ts","sourceRoot":"","sources":["../../src/utils/valueFormatters.ts"],"names":[],"mappings":"AAMA;;GAEG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,oBAAoB,GAAI,KAAK,MAAM,EAAE,KAAK,MAAM,KAAG,MAE/D,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,MAAM,KAAG,MAEhD,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,oBAAoB,GAAI,OAAO,MAAM,EAAE,KAAK,MAAM,EAAE,KAAK,MAAM,KAAG,MAI9E,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,QAAQ,GAAI,MAAM,MAAM,MACzB,OAAO,MAAM,KAAG,MAC3B,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,aAAa,GAAI,WAAW,MAAM,MACnC,OAAO,MAAM,KAAG,MAC3B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,iBAAiB,GAAI,GAAG,YAAY,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC,EAAE,MAC9F,OAAO,MAAM,EAAE,MAAM,MAAM,EAAE,MAAM,MAAM,KAAG,MAgBvD,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,mBAAmB,GAAI,OAAO,MAAM,EAAE,KAAK,MAAM,EAAE,KAAK,MAAM,KAAG,MAG7E,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,KAAG,MAKlD,CAAC"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@cutoff/audio-ui-core",
+  "version": "1.0.0-preview.20260123.1125",
+  "description": "Core logic and models for AudioUI by Cutoff",
+  "private": false,
+  "author": "Renaud Denis <mail@renauddenis.com> (https://renauddenis.com)",
+  "license": "GPL-3.0-only",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./styles.css": "./dist/styles/styles.css",
+    "./themes.css": "./dist/styles/themes.css"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "fast-deep-equal": "^3.1.3"
+  },
+  "devDependencies": {
+    "jsdom": "^24.1.3",
+    "typescript": "^5.9.3",
+    "vite": "^5.4.21",
+    "vite-plugin-dts": "^3.9.1",
+    "vitest": "^1.6.1"
+  },
+  "scripts": {
+    "build": "pnpm exec vite build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint \"src/**/*.ts\"",
+    "lint:fix": "eslint \"src/**/*.ts\" --fix || true",
+    "clean": "rm -rf node_modules dist .turbo"
+  }
+}