logo-soup 0.1.0 → 0.2.1

package/README.md

@@ -10,7 +10,7 @@ logo-soup analyzes SVG/PNG images with `sharp`, detects their content bounding b
 ## Installation
 
 ```bash
-pnpm add logo-soup
+pnpm add -D logo-soup
 
 # Or run directly
 npx logo-soup ./logos
@@ -22,19 +22,64 @@ npx logo-soup ./logos
 logo-soup ./public/logos -o logo-metrics.json
 ```
 
-Output JSON keys are filenames only (e.g. `"logo.svg"`), so consumers can prepend their own base path.
+Output keys are filenames only (e.g. `"logo.svg"`), so you can prepend your own base path.
 
 ```
 logo-soup <dir> [options]
 
 Options:
   --output, -o        Output JSON file path (default: "logo-metrics.json")
-  --base-size         Base size for normalization in px (default: 48)
+  --base-size         Base size for normalization in px (default: 64)
   --scale-factor      Aspect ratio normalization 0-1 (default: 0.5)
   --density-factor    Density compensation 0-1 (default: 0.5)
   --extensions, -e    Comma-separated file extensions (default: "svg,png")
 ```
 
+## Usage
+
+Running the CLI produces a JSON file mapping each filename to its normalized dimensions:
+
+```json
+{
+  "acme-wordmark.svg": { "width": 143, "height": 28, "offsetX": 0, "offsetY": 0.5 },
+  "globex-icon.svg": { "width": 64, "height": 64, "offsetX": 0, "offsetY": 0 },
+  "initech-monogram.svg": { "width": 52, "height": 79, "offsetX": -0.4, "offsetY": 0 }
+}
+```
+
+`width` and `height` are pixel dimensions normalized so every logo feels the same visual size – use them directly as `width`/`height` attributes. `offsetX`/`offsetY` are optional sub-pixel corrections (see [Visual Center Offsets](#visual-center-offsets)).
+
+### Logo Strip
+
+The most common use case: a "trusted by" row or partner logo strip. Apply `width` and `height` directly – the normalization ensures all logos feel balanced side by side.
+
+```html
+<div class="flex flex-wrap items-center justify-center gap-8">
+  <img src="/logos/acme-wordmark.svg" width="143" height="28" alt="Acme">
+  <img src="/logos/globex-icon.svg" width="64" height="64" alt="Globex">
+  <img src="/logos/initech-monogram.svg" width="52" height="79" alt="Initech">
+</div>
+```
+
+> [!TIP]
+> The default `baseSize` is 64px, so a square logo renders at 64×64px. For a different base, pass `--base-size <n>` to the CLI (or `{ baseSize }` to `normalize()`), or scale uniformly with CSS – the proportions stay correct either way.
+
+### Visual Center Offsets
+
+Some logos have visual weight that doesn't match their geometric center – a play button or an arrow, for instance. `offsetX`/`offsetY` correct for this by nudging the logo toward its optical center.
+
+These offsets are typically small (< 2px) and `width`/`height` alone handle most of the balancing. For pixel-perfect alignment, apply them as CSS transforms:
+
+```html
+<img src="/logos/acme-wordmark.svg" width="143" height="28" style="transform: translate(0px, 0.5px)">
+```
+
+For horizontal strips where only vertical alignment matters, you can apply just the Y offset:
+
+```html
+<img src="/logos/acme-wordmark.svg" width="143" height="28" style="transform: translateY(0.5px)">
+```
+
 ## Programmatic API
 
 ```ts
@@ -43,7 +88,7 @@ import { analyze, analyzeDirectory, normalize } from 'logo-soup'
 // Single file
 const metrics = await analyze('./logo.svg')
 if (metrics) {
-  const dimensions = normalize(metrics, { baseSize: 48 })
+  const dimensions = normalize(metrics)
   console.log(dimensions) // { width, height, offsetX, offsetY }
 }
 
@@ -104,7 +149,7 @@ Converts raw metrics into display dimensions using aspect ratio normalization wi
 function normalize(metrics: Metrics, options?: NormalizeOptions): NormalizedDimensions
 
 interface NormalizeOptions {
-  /** Base size in pixels (default: 48) */
+  /** Base size in pixels (default: 64) */
   baseSize?: number
   /** Aspect ratio normalization factor, 0–1 (default: 0.5) */
   scaleFactor?: number

package/dist/cli.mjs

@@ -1,13 +1,14 @@
-import { c as DENSITY_FACTOR, d as SCALE_FACTOR, i as BASE_SIZE, o as DEFAULT_EXTENSIONS, r as analyzeDirectory, t as normalize } from "./normalize-BN3StFfP.mjs";
+import { c as DENSITY_FACTOR, d as SCALE_FACTOR, i as BASE_SIZE, o as DEFAULT_EXTENSIONS, r as analyzeDirectory, t as normalize } from "./normalize-B5apzI38.mjs";
 import * as fsp from "node:fs/promises";
 import * as path from "node:path";
 import process from "node:process";
 import { defineCommand, runMain } from "citty";
 import { consola } from "consola";
+import { colors } from "consola/utils";
 
 //#region package.json
 var name = "logo-soup";
-var version = "0.1.0";
+var version = "0.2.1";
 var description = "Normalize logo dimensions for visual balance";
 
 //#endregion
@@ -62,10 +63,9 @@ const command = defineCommand({
 		const baseSize = parseNumericArg(args["base-size"], "base-size", BASE_SIZE);
 		const scaleFactor = parseNumericArg(args["scale-factor"], "scale-factor", SCALE_FACTOR);
 		const densityFactor = parseNumericArg(args["density-factor"], "density-factor", DENSITY_FACTOR);
-		const extensions = args.extensions ? args.extensions.split(",").map((ext) => ext.trim().toLowerCase()) : DEFAULT_EXTENSIONS;
-		consola.start(`Analyzing logos in ${dirPath}`);
-		const metricsMap = await analyzeDirectory(dirPath, { extensions });
+		const metricsMap = await analyzeDirectory(dirPath, { extensions: args.extensions ? args.extensions.split(",").map((ext) => ext.trim().toLowerCase()) : DEFAULT_EXTENSIONS });
 		const results = {};
+		const entries = [];
 		for (const [file, metrics] of metricsMap) {
 			const dimensions = normalize(metrics, {
 				baseSize,
@@ -73,22 +73,35 @@ const command = defineCommand({
 				densityFactor
 			});
 			results[file] = dimensions;
-			consola.log(`  ${file} → ${dimensions.width}×${dimensions.height}px`);
+			entries.push([file, dimensions]);
+		}
+		console.log();
+		console.log(`${colors.cyan("●")} ${colors.bold(name)} ${colors.dim(`v${version}`)}`);
+		console.log();
+		const maxEntryLength = Math.max(...entries.map(([entry]) => entry.length));
+		const total = entries.length;
+		for (const [i, [file, dimensions]] of entries.entries()) {
+			const branch = i === total - 1 ? "└─" : "├─";
+			const dimStr = `${dimensions.width}${colors.dim("×")}${dimensions.height}`;
+			const padding = " ".repeat(maxEntryLength - file.length + 2);
+			console.log(`  ${colors.dim(branch)} ${colors.cyan(file)}${padding}${dimStr}`);
 		}
 		const outputPath = path.resolve(args.output);
 		await fsp.mkdir(path.dirname(outputPath), { recursive: true });
 		await fsp.writeFile(outputPath, `${JSON.stringify(results, null, 2)}\n`);
-		consola.success(`Wrote ${Object.keys(results).length} entries to ${outputPath}`);
+		const relativeOutput = path.relative(process.cwd(), outputPath);
+		console.log();
+		consola.success(`Wrote ${colors.bold(String(total))} entries to ${colors.cyan(relativeOutput)}`);
 	}
 });
 function parseNumericArg(value, name, fallback) {
-	if (value === void 0) return fallback;
-	const parsed = Number(value);
-	if (Number.isNaN(parsed)) {
+	if (value == null) return fallback;
+	const parsedNumber = Number(value);
+	if (Number.isNaN(parsedNumber)) {
 		consola.error(`Invalid value for --${name}: "${value}" (expected a number)`);
 		process.exit(1);
 	}
-	return parsed;
+	return parsedNumber;
 }
 runMain(command);
 

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import { a as CONTRAST_THRESHOLD, c as DENSITY_FACTOR, d as SCALE_FACTOR, i as BASE_SIZE, l as REFERENCE_DENSITY, n as analyze, o as DEFAULT_EXTENSIONS, r as analyzeDirectory, s as DENSITY_DAMPENING, t as normalize, u as SAMPLE_MAX_SIZE } from "./normalize-BN3StFfP.mjs";
+import { a as CONTRAST_THRESHOLD, c as DENSITY_FACTOR, d as SCALE_FACTOR, i as BASE_SIZE, l as REFERENCE_DENSITY, n as analyze, o as DEFAULT_EXTENSIONS, r as analyzeDirectory, s as DENSITY_DAMPENING, t as normalize, u as SAMPLE_MAX_SIZE } from "./normalize-B5apzI38.mjs";
 
 export { BASE_SIZE, CONTRAST_THRESHOLD, DEFAULT_EXTENSIONS, DENSITY_DAMPENING, DENSITY_FACTOR, REFERENCE_DENSITY, SAMPLE_MAX_SIZE, SCALE_FACTOR, analyze, analyzeDirectory, normalize };

package/dist/{normalize-BN3StFfP.mjs → normalize-B5apzI38.mjs}

@@ -8,7 +8,7 @@ const SAMPLE_MAX_SIZE = 200;
 /** Minimum contrast threshold to consider a pixel as content. */
 const CONTRAST_THRESHOLD = 10;
 /** Base size in pixels for the normalized output. */
-const BASE_SIZE = 48;
+const BASE_SIZE = 64;
 /** Aspect ratio normalization factor (0–1). */
 const SCALE_FACTOR = .5;
 /** Density compensation factor (0–1). */
@@ -38,10 +38,7 @@ async function analyze(filePath, options = {}) {
 }
 async function analyzeDirectory(dirPath, options = {}) {
 	const { extensions = DEFAULT_EXTENSIONS, ...analyzeOptions } = options;
-	const files = (await fsp.readdir(dirPath)).filter((fileName) => {
-		const ext = path.extname(fileName).slice(1).toLowerCase();
-		return extensions.includes(ext);
-	});
+	const files = (await fsp.readdir(dirPath)).filter((entry) => extensions.includes(path.extname(entry).slice(1).toLowerCase()));
 	const results = /* @__PURE__ */ new Map();
 	for (const file of files) {
 		const absolutePath = path.resolve(dirPath, file);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "logo-soup",
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "packageManager": "pnpm@10.30.0",
   "description": "Normalize logo dimensions for visual balance",
   "author": "Johann Schopplich <hello@johannschopplich.com>",