feat: add alignValues option (#102)

## PR Checklist

- [x] Addresses an existing open issue: fixes #12
- [x] That issue was marked as [`status: accepting
prs`](https://github.com/dmnd/dedent/issues?q=is%3Aopen+is%3Aissue+label%3A%22status%3A+accepting+prs%22)
- [x] Steps in
[CONTRIBUTING.md](https://github.com/dmnd/dedent/blob/main/.github/CONTRIBUTING.md)
were taken

## Overview

This PR implements the `alignValues` option for `dedent()` to handle
interpolated values with proper indentation alignment. When enabled via
`dedent({ alignValues: true })`, the function will align each
interpolated value's indentation to match its starting line's
indentation within the template literal.

And added a basic test for nested interpolated string.

---------

Co-authored-by: Josh Goldberg ✨ <[email protected]>

Author: PaperStrike

README.md

@@ -93,6 +93,52 @@ dedenter`input`;
 dedenter(`input`);
 ```
 
+### `alignValues`
+
+When an interpolation evaluates to a multi-line string, only its first line is placed where the `${...}` appears. Subsequent lines keep whatever indentation they already had inside that value (often none), so they can appear “shifted left”.
+
+Enable `alignValues` to fix that visual jump. When `true`, for every multi-line interpolated value, each line after the first gets extra indentation appended so it starts in the same column as the first line.
+
+```js
+import dedent from "dedent";
+
+const list = dedent`
+	- apples
+	- bananas
+	- cherries
+`;
+
+const withoutAlign = dedent`
+	List without alignValues (default):
+		${list}
+	Done.
+`;
+
+const withAlign = dedent.withOptions({ alignValues: true })`
+	List with alignValues: true
+		${list}
+	Done.
+`;
+
+console.log(withoutAlign);
+console.log("---");
+console.log(withAlign);
+```
+
+```plaintext
+List without alignValues (default):
+	- apples
+- bananas
+- cherries
+Done.
+---
+List with alignValues: true
+	- apples
+	- bananas
+	- cherries
+Done.
+```
+
 ### `escapeSpecialCharacters`
 
 JavaScript string tags by default add an extra `\` escape in front of some special characters such as `$` dollar signs.

src/__snapshots__/dedent.test.ts.snap

@@ -96,6 +96,39 @@ exports[`dedent string tag character escapes with escapeSpecialCharacters undefi
 
 exports[`dedent string tag character escapes with escapeSpecialCharacters undefined opening braces 1`] = `"{"`;
 
+exports[`dedent with alignValues false with nested text 1`] = `
+"Some nested items I want to dedent:
+	* first
+	* second
+* third
+	* fourth
+	* fifth
+* sixth
+That's all!"
+`;
+
+exports[`dedent with alignValues true with nested text 1`] = `
+"Some nested items I want to dedent:
+	* first
+	* second
+	* third
+	* fourth
+	* fifth
+	* sixth
+That's all!"
+`;
+
+exports[`dedent with alignValues undefined with nested text 1`] = `
+"Some nested items I want to dedent:
+	* first
+	* second
+* third
+	* fourth
+	* fifth
+* sixth
+That's all!"
+`;
+
 exports[`dedent with trimWhitespace false with leading whitespace 1`] = `
 "
 

src/dedent.test.ts

@@ -273,4 +273,26 @@ describe("dedent", () => {
 	it("does not replace \\n when called as a function", () => {
 		expect(dedent(`\\nu`)).toBe("\\nu");
 	});
+
+	describe.each([undefined, false, true])(
+		"with alignValues %s",
+		(alignValues) => {
+			test("with nested text", () => {
+				expect(
+					dedent.withOptions({ alignValues })`
+						Some nested items I want to dedent:
+							* first
+							${dedent`
+								* second
+								* third`}
+							* fourth
+							${dedent`
+								* fifth
+								* sixth`}
+						That's all!
+					`,
+				).toMatchSnapshot();
+			});
+		},
+	);
 });

src/dedent.ts

@@ -20,6 +20,7 @@ function createDedent(options: DedentOptions) {
 	) {
 		const raw = typeof strings === "string" ? [strings] : strings.raw;
 		const {
+			alignValues = false,
 			escapeSpecialCharacters = Array.isArray(strings),
 			trimWhitespace = true,
 		} = options;
@@ -41,8 +42,10 @@ function createDedent(options: DedentOptions) {
 			result += next;
 
 			if (i < values.length) {
+				const value = alignValues ? alignValue(values[i], result) : values[i];
+
 				// eslint-disable-next-line @typescript-eslint/restrict-plus-operands
-				result += values[i];
+				result += value;
 			}
 		}
 
@@ -84,3 +87,21 @@ function createDedent(options: DedentOptions) {
 		return result;
 	}
 }
+
+/**
+ * Adjusts the indentation of a multi-line interpolated value to match the current line.
+ */
+function alignValue(value: unknown, precedingText: string) {
+	if (typeof value !== "string" || !value.includes("\n")) {
+		return value;
+	}
+
+	const currentLine = precedingText.slice(precedingText.lastIndexOf("\n") + 1);
+	const indentMatch = currentLine.match(/^(\s+)/);
+	if (indentMatch) {
+		const indent = indentMatch[1];
+		return value.replace(/\n/g, `\n${indent}`);
+	}
+
+	return value;
+}

src/types.ts

@@ -1,4 +1,5 @@
 export interface DedentOptions {
+	alignValues?: boolean;
 	escapeSpecialCharacters?: boolean;
 	trimWhitespace?: boolean;
 }