prettier-plugin-embed 0.7.3 → 0.8.0

package/README.md

@@ -4,6 +4,8 @@
 
 # Prettier Plugin Embed
 
+[Online playground](https://sec-ant.github.io/prettier-plugin-embed/) · [Run the playground locally](./playground/README.md)
+
 [![npm version](https://img.shields.io/npm/v/prettier-plugin-embed?cacheSeconds=300)](https://www.npmjs.com/package/prettier-plugin-embed/v/latest) [![npm downloads](https://img.shields.io/npm/dm/prettier-plugin-embed?cacheSeconds=300)](https://www.npmjs.com/package/prettier-plugin-embed/v/latest) [![npm license](https://img.shields.io/npm/l/prettier-plugin-embed?cacheSeconds=300)](https://www.npmjs.com/package/prettier-plugin-embed/v/latest) [![All Contributors](https://img.shields.io/github/all-contributors/Sec-ant/prettier-plugin-embed?color=56b3b4)](#contributors)
 
 [![github last commit](https://img.shields.io/github/last-commit/Sec-ant/prettier-plugin-embed?cacheSeconds=300)](https://github.com/Sec-ant/prettier-plugin-embed) [![bundlephobia minzipped](https://img.shields.io/bundlephobia/minzip/prettier-plugin-embed?cacheSeconds=300)](https://bundlephobia.com/package/prettier-plugin-embed@latest) [![](https://img.shields.io/jsdelivr/npm/hm/prettier-plugin-embed?cacheSeconds=300&color=ff5627)](https://www.jsdelivr.com/package/npm/prettier-plugin-embed)
@@ -78,6 +80,14 @@ Projects can also use Yarn's default `pnpFallbackMode: dependencies-only` or pnp
 
 ## Usage
 
+### Playground
+
+Try the plugin in the [online playground](https://sec-ant.github.io/prettier-plugin-embed/). Edit JavaScript or TypeScript alongside your `.prettierrc` configuration, including the `plugins` array and embedded-language options. Formatting runs locally in your browser.
+
+To report a formatting issue, keep the original code in Input, enable Compare to inspect the native Prettier output, then use **Copy issue report**. The report includes the input, configuration, output or error, formatter versions, and a shareable playground link. **Share** copies a link containing the current example and configuration.
+
+See the [playground guide](./playground/README.md) for local development, keyboard shortcuts, browser limitations, and GitHub Pages deployment.
+
 ### Getting Started
 
 This is a Prettier plugin, which follows the [standard usage pattern](https://prettier.io/docs/en/plugins.html#using-plugins) of many other Prettier plugins:
@@ -899,6 +909,8 @@ Supply the `svelte` compiler alongside the formatter plugin, using versions comp
 
 Formatting embedded TOML language requires the [`prettier-plugin-toml`](https://github.com/un-ts/prettier/tree/master/packages/toml#readme) plugin to be loaded as well. And [options](https://github.com/un-ts/prettier/blob/master/packages/toml/src/options.ts) supported by `prettier-plugin-toml` can therefore be used to further control the formatting behavior.
 
+`prettier-plugin-toml` 4 requires Node.js 20 or later and its platform-specific optional native dependency. Keep optional dependencies enabled when installing it. Use version 3 for Node.js 18.
+
 #### TS (TypeScript)
 
 ##### `embeddedTsComments`
@@ -939,6 +951,8 @@ If you want to specify different parsers for different comments or tags, check [
 
 Embedded XML uses the parser provided by [`@prettier/plugin-xml`](https://github.com/prettier/plugin-xml#readme), which must be loaded when XML formatting is enabled. Its [options](https://github.com/prettier/plugin-xml#configuration) control the XML formatting behavior.
 
+Use version 3 or later with Prettier 3. Version 2 uses the older Prettier 2 embed API and is incompatible.
+
 #### XQuery
 
 ##### `embeddedXQueryComments`
@@ -993,13 +1007,21 @@ Embedded YAML uses the parsers and printers included with Prettier.
 
 This preserves the original exterior whitespace characters, including their indentation. Without this option, whitespace-sensitive markup such as HTML and Jinja preserves whether boundary whitespace exists and allows its indentation to be formatted.
 
+Preserved multiline boundary indentation also sets the margin for subsequent content lines. No extra template indentation is added, including when this option is combined with `noEmbeddedMultiLineIndentation`. If content starts on the same line as the opening backtick, its preserved margin is zero. Content indentation, such as the four spaces of a Markdown code block, belongs to the content rather than to exterior whitespace.
+
 ##### `noEmbeddedMultiLineIndentation`
 
 - **Type**: `string[]`
 - **Default**: `[]`
 - **Description**: Turns off auto indentation in the formatting results for the specified comments or tags when they are formatted to span multi lines.
 
-This removes the extra indentation level added around the embedded content. Indentation within the embedded language is still formatted. For example, `"noEmbeddedMultiLineIndentation": ["html", "jinja"]` disables that extra level for both tags and comments. It can be combined with `preserveEmbeddedExteriorWhitespaces`.
+This prints embedded content from the current document root without inheriting the surrounding JavaScript or TypeScript indentation. Indentation within the embedded language is still formatted. For example, `"noEmbeddedMultiLineIndentation": ["html", "jinja"]` disables automatic template indentation for both tags and comments. It can be combined with `preserveEmbeddedExteriorWhitespaces`, which takes precedence and uses the original boundary margin.
+
+Markdown retains its root-aligned behavior, so headings inside deeply nested JavaScript do not become indented code blocks. Other languages now follow the same rule. This option affects output layout only; it does not change how the embedded source is parsed or remove its lists, code blocks, or other meaningful indentation. YAML content uses spaces for its internal indentation even when the host uses tabs.
+
+Before parsing, the plugin removes only the exact whitespace prefix shared by every nonempty content line. A column-zero content line makes that prefix empty. This template margin is determined before trimming boundary whitespace, and tabs and spaces are compared literally. The remaining indentation is passed to the language formatter. This convention applies equally to tags and comments and to both indentation options. It treats a common prefix as template framing; Markdown consisting entirely of indented code can use a fenced code block to make its intent explicit.
+
+The plugin formats template source and does not insert a runtime dedent operation. For raw whitespace-sensitive values, author content without a common source margin and enable `noEmbeddedMultiLineIndentation` to keep automatic host indentation out of the string value.
 
 ##### `embeddedOverrides`
 

package/dist/embedded/create-embedder.d.ts

@@ -5,10 +5,9 @@ interface EmbedderConfiguration {
     parserOption?: string;
     parserOptions?: Partial<Options>;
     markup?: boolean;
-    newlineHandling?: false | "hardline" | "literalline";
-    dedentContent?: boolean;
+    preserveTrailingWhitespace?: boolean;
     placeholderPrefix?: string;
     transformDoc?: (doc: Doc) => Doc;
 }
-export declare function createEmbedder({ parser, parserOption, parserOptions, markup, newlineHandling, dedentContent, placeholderPrefix, transformDoc, }: EmbedderConfiguration): Embedder;
+export declare function createEmbedder({ parser, parserOption, parserOptions, markup, preserveTrailingWhitespace, placeholderPrefix, transformDoc, }: EmbedderConfiguration): Embedder;
 export {};

package/dist/embedded/markdown/embedder.d.ts

@@ -1,10 +1,5 @@
-import type { Options } from "prettier";
-import type { Embedder } from "../../types.js";
 import { language } from "./language.js";
-export declare const embedder: Embedder<Options>;
-/**
- * Register the embedder to the EmbeddedEmbedders
- */
+export declare const embedder: import("../../types.js").Embedder;
 declare module "../types.js" {
     interface EmbeddedEmbedders {
         [language]: typeof embedder;

package/dist/embedded/register.d.ts

@@ -15,21 +15,21 @@ import * as __glob__0_8 from "./handlebars/index.js";
 import * as __glob__0_9 from "./html/index.js";
 import * as __glob__0_10 from "./hugo/index.js";
 import * as __glob__0_11 from "./ini/index.js";
-import * as __glob__0_12 from "./java/index.js";
+import * as __glob__0_12 from "./jinja/index.js";
 import * as __glob__0_13 from "./json/index.js";
-import * as __glob__0_14 from "./jinja/index.js";
+import * as __glob__0_14 from "./java/index.js";
 import * as __glob__0_15 from "./jsonata/index.js";
 import * as __glob__0_16 from "./jte/index.js";
-import * as __glob__0_17 from "./latex/index.js";
-import * as __glob__0_18 from "./liquid/index.js";
-import * as __glob__0_19 from "./markdown/index.js";
-import * as __glob__0_20 from "./marko/index.js";
+import * as __glob__0_17 from "./liquid/index.js";
+import * as __glob__0_18 from "./latex/index.js";
+import * as __glob__0_19 from "./marko/index.js";
+import * as __glob__0_20 from "./markdown/index.js";
 import * as __glob__0_21 from "./motoko/index.js";
 import * as __glob__0_22 from "./mustache/index.js";
-import * as __glob__0_23 from "./nginx/index.js";
-import * as __glob__0_24 from "./noop/index.js";
-import * as __glob__0_25 from "./nunjucks/index.js";
-import * as __glob__0_26 from "./pegjs/index.js";
+import * as __glob__0_23 from "./noop/index.js";
+import * as __glob__0_24 from "./nunjucks/index.js";
+import * as __glob__0_25 from "./pegjs/index.js";
+import * as __glob__0_26 from "./nginx/index.js";
 import * as __glob__0_27 from "./php/index.js";
 import * as __glob__0_28 from "./powershell/index.js";
 import * as __glob__0_29 from "./prisma/index.js";

package/dist/embedded/utils.d.ts

@@ -3,8 +3,8 @@ import type { AstPath, Doc, Options } from "prettier";
 import { builders } from "prettier/doc";
 import type { LiteralUnion, OmitIndexSignature, UnionToIntersection } from "../type-utils.js";
 import type { InternalPrintFun } from "../types.js";
-export declare function prepareTemplate(node: TemplateLiteral, createPlaceholder: (index: number) => string): {
-    trimmedText: string;
+export declare function prepareTemplate(node: TemplateLiteral, createPlaceholder: (index: number) => string, preserveTrailingWhitespace?: boolean): {
+    text: string;
     leadingWhitespaces: string;
     trailingWhitespaces: string;
 };
@@ -16,16 +16,13 @@ export declare function printTemplateExpression(path: AstPath<Expression & {
     comments?: Comment[];
 }>, print: InternalPrintFun, templateLiteral: TemplateLiteral, index: number, tabWidth: number, preserveIndentation?: boolean, knownIndentSize?: number): builders.Group;
 export declare function printTemplateExpressions(path: AstPath<TemplateLiteral>, print: InternalPrintFun, options?: Options, preserveIndentation?: boolean): builders.Group[];
-export declare function simpleRehydrateDoc(doc: Doc, placeholderRegex: RegExp, expressionDocs: Doc[], 
-/**
- * How to handle newlines in the formatted content:
- * - false: keep newlines as-is (default)
- * - "hardline": replace newlines with hardline (adds indentation)
- * - "literalline": replace newlines with literalline via replaceEndOfLine (preserves original indentation)
- */
-newlineHandling?: false | "hardline" | "literalline", lineBreakBeforeExpressions?: ReadonlySet<number>, interpolationTabWidth?: number, escapeClosingScript?: boolean): builders.Doc[] | builders.DocCommand;
+export declare function simpleRehydrateDoc(doc: Doc, placeholderRegex: RegExp, expressionDocs: Doc[], { lineBreakBeforeExpressions, interpolationTabWidth, escapeClosingScript, }?: {
+    lineBreakBeforeExpressions?: ReadonlySet<number>;
+    interpolationTabWidth?: number;
+    escapeClosingScript?: boolean;
+}): builders.Doc;
 export declare function insertLanguage(languages: string[], language: string, firstLanguage: string): void;
-export declare const randomUUID: () => string;
+export declare function randomUUID(): string;
 export declare function preparePlaceholder(leading?: string, trailing?: string): {
     createPlaceholder: (index: number) => string;
     placeholderRegex: RegExp;

package/dist/embedded/yaml/embedder.d.ts

@@ -1,10 +1,5 @@
-import type { Options } from "prettier";
-import type { Embedder } from "../../types.js";
 import { language } from "./language.js";
-export declare const embedder: Embedder<Options>;
-/**
- * Register the embedder to the EmbeddedEmbedders
- */
+export declare const embedder: import("../../types.js").Embedder;
 declare module "../types.js" {
     interface EmbeddedEmbedders {
         [language]: typeof embedder;