@samva/markup 0.1.2 → 0.3.0

package/dist/compiler.d.ts

@@ -0,0 +1,303 @@
+import { a as formatEmailDiagnostic, i as EmailDiagnosticSeverity, n as EmailCompileError, o as hasBlockingDiagnostic, r as EmailDiagnostic } from "./diagnostics-Djd9ckLg.js";
+import { a as EmailGlobalProps, c as EmailStyle, d as isUrlAttribute, i as EmailElementSpec, l as EmailTag, m as EmailNode, n as EMAIL_GLOBAL_ATTRIBUTES, o as EmailIntrinsicElements, r as EmailAttributeSpec, s as EmailLayout, t as EMAIL_ELEMENTS, u as emailElement } from "./elements-DtwKlFVH.js";
+import { EmailElementSelection, EmittedPosition, INSTANCE_PATH_ATTRIBUTE, emailAuthoringTarget, emailDefinitionInstances, emailSelectionAncestry, emailSelectionIndex, emailSelectionSiblings, emailSelections } from "./email/selection.js";
+import { EmailHtmlOutput, SerializeEmailOptions, escapeAttribute, escapeText, serializeEmailHtml } from "./email/html.js";
+import { deriveEmailText } from "./email/text.js";
+import { a as compileSelector, c as CompiledSelector, d as matchesSelector, i as Stylesheet, l as Compound, n as CssRule, o as parseStylesheet, r as Specificity, s as Ancestry, t as CssDeclaration, u as classListOf } from "./css-ar2lU3NC.js";
+import { EMAIL_DOCTYPE, EmailCompileOutput, RenderedEmail, compileEmail, renderEmail } from "./email/render.js";
+import { collectStylesheets, hasStylesheets, registerStylesheet, resetStylesheets } from "./email/stylesheets.js";
+import { instrumentTsxSourceForPreview } from "./tsx-source-instrumentation.js";
+import { caniemail } from "caniemail";
+//#region src/email/compatibility.d.ts
+type CaniemailClient = Parameters<typeof caniemail>[0]["clients"][number];
+/** One client this compiler makes claims about. */
+interface EmailClientTarget {
+  readonly id: CaniemailClient;
+  readonly label: string;
+}
+/**
+ * The pinned matrix. Every finding is reported per client, and a client absent
+ * from this list is a client Samva makes no claim about.
+ */
+declare const EMAIL_CLIENT_MATRIX: readonly EmailClientTarget[];
+interface CompatibilityProvenance {
+  /** The exact rules package a finding came from. */
+  readonly rules: string;
+  readonly apiVersion: string;
+  /** The day caniemail last changed the data this build was checked against. */
+  readonly lastUpdate: string;
+}
+declare const COMPATIBILITY_PROVENANCE: CompatibilityProvenance;
+/**
+ * The constructs whose loss actually breaks a message: the recipient reads
+ * something different, in a different order, follows a link that does not work,
+ * or sees a layout that has collapsed. A target client dropping one of these
+ * blocks publication.
+ *
+ * The list is deliberately short and enumerated, because the contract is to
+ * block *known* failures. Nonessential differences require an assessment of
+ * emitted values: a concrete risk warns, expected differences and unverified
+ * behavior remain compatibility observations.
+ */
+declare const ESSENTIAL_CONSTRUCTS: ReadonlySet<string>;
+interface CompatibilityInput {
+  /** The document the recipient receives. */
+  readonly html: string;
+  /** The declared fixture checked by this invocation. */
+  readonly fixture?: string | undefined;
+  /** Retained head rules, when they are not already inside the HTML. */
+  readonly css?: string | undefined;
+  /** Emitted-offset ranges with the origins of the node that produced them. */
+  readonly positions?: readonly EmittedPosition[] | undefined;
+  readonly clients?: readonly EmailClientTarget[] | undefined;
+}
+/**
+ * Check the emitted document against the pinned matrix.
+ *
+ * Findings are grouped by construct rather than repeated per client, so one
+ * unsupported property is one diagnostic naming every client that drops it.
+ */
+declare const checkEmailCompatibility: (input: CompatibilityInput) => readonly EmailDiagnostic[];
+/**
+ * Constructs the pinned data says nothing about for a target client. These are
+ * reported so "we did not check that" is never mistaken for "that works".
+ */
+declare const unknownCoverage: (titles: Iterable<string>) => readonly EmailDiagnostic[];
+/** A publication carrying one of these is refused; the message would arrive broken. */
+declare const hasBlockingCompatibility: (findings: readonly EmailDiagnostic[]) => boolean;
+//#endregion
+//#region src/email/assets.d.ts
+/** Files a template may import, and what they are served as. */
+declare const ASSET_CONTENT_TYPES: Readonly<Record<string, string>>;
+interface AssetEntry {
+  /** Project-relative path the template imported. */
+  readonly path: string;
+  /** SHA-256 of the exact bytes, lowercase hex. */
+  readonly digest: string;
+  readonly bytes: number;
+  readonly contentType: string;
+  /** `<digest><ext>` — the name the asset has under any base. */
+  readonly fileName: string;
+}
+interface AssetManifest {
+  /** Where these assets are served from in this build. */
+  readonly base: string;
+  readonly assets: readonly AssetEntry[];
+}
+/** True when the compiler turns this import into a content-addressed asset. */
+declare const isAssetPath: (path: string) => boolean;
+/** Address one file by its content. */
+declare const assetEntry: (path: string, bytes: Uint8Array) => Promise<AssetEntry>;
+/**
+ * The URL an asset has under a base. The base is a build input: publication
+ * passes its hosted origin, and a local export passes whatever it will serve
+ * the exported files from.
+ */
+declare const assetUrl: (entry: AssetEntry, base: string) => string;
+/** Record, but never fetch, a URL the template points at. */
+declare const isExternalAsset: (reference: string) => boolean;
+/**
+ * Reject an asset base that would produce URLs a client will not load. The
+ * relative forms are the ones a page on disk resolves against its own
+ * directory, which is what a local export writes.
+ */
+declare const checkAssetBase: (base: string) => readonly EmailDiagnostic[];
+//#endregion
+//#region src/email/css-values.d.ts
+/** Expand `var(--x, fallback)` against the collected custom properties. */
+declare const resolveVariables: (value: string, variables: Readonly<Record<string, string>>, depth?: number) => string;
+/**
+ * Fold a constant `calc()` to a plain value. Tailwind writes every spacing
+ * utility as `calc(var(--spacing) * n)`, and classic Outlook does not implement
+ * `calc()` at all, so an unfolded value is a silently missing style. An
+ * expression that cannot be reduced to one term is left exactly as authored.
+ */
+declare const foldCalc: (value: string) => string;
+/** Resolve custom properties, then fold what the arithmetic allows. */
+declare const finalizeValue: (value: string, variables: Readonly<Record<string, string>>) => string;
+/** Media Queries Level 4 range syntax down to the `min-`/`max-` prefixes clients support. */
+declare const downlevelMediaQuery: (condition: string) => string;
+/** Render the rules that could not be inlined as one `<style>` body. */
+declare const renderHeadCss: (rules: readonly CssRule[], headAtRules: readonly string[], variables: Readonly<Record<string, string>>) => string;
+//#endregion
+//#region src/email/css-color.d.ts
+/** A color in extended sRGB, alpha included, before clamping and gamma. */
+interface Rgba {
+  readonly r: number;
+  readonly g: number;
+  readonly b: number;
+  readonly a: number;
+}
+/** Parse any supported color notation into extended sRGB. `undefined` means "leave it alone". */
+declare const parseColor: (value: string) => Rgba | undefined;
+/** sRGB hex, or `rgba()` when the color is not opaque. */
+declare const formatColor: (color: Rgba) => string;
+/** Rewrite every modern color function in a declaration value; other text is untouched. */
+declare const downlevelColors: (value: string) => string;
+//#endregion
+//#region src/email/cascade.d.ts
+interface AppliedStyles {
+  readonly tree: EmailNode;
+  /** Rules that could not be inlined, ready for a `<style>` element in `<head>`. */
+  readonly headCss: string;
+  readonly diagnostics: readonly EmailDiagnostic[];
+}
+/**
+ * Resolve every stylesheet against the tree: inline what a client will honor on
+ * the element, and keep the rest for `<head>`.
+ */
+declare const applyStylesheet: (root: EmailNode, sheet: Stylesheet, options?: {
+  readonly knownClasses?: ReadonlySet<string>;
+}) => AppliedStyles;
+//#endregion
+//#region src/email/tailwind-stylesheets.gen.d.ts
+/** The exact Tailwind release the compiler runs, recorded in every build manifest. */
+declare const TAILWIND_VERSION = "4.3.3";
+//#endregion
+//#region src/email/tailwind.d.ts
+interface TailwindOptions {
+  /**
+   * Project CSS appended to the compiled entry: `@theme` overrides, `@utility`
+   * definitions and ordinary rules. This is the project's pinned configuration.
+   */
+  readonly css?: string | undefined;
+  /** Classes the compiler cannot discover, declared by the project on purpose. */
+  readonly safelist?: readonly string[] | undefined;
+  /** Tailwind's browser reset is off by default; email clients do not want it. */
+  readonly preflight?: boolean | undefined;
+  /**
+   * Bounds on what the compiler may generate. Class discovery reads authored
+   * source, so a project can hand it an unbounded candidate set and get an
+   * unbounded stylesheet back — inside a build that has a wall clock and a
+   * bundle a Worker then has to load. A host that publishes supplies these.
+   */
+  readonly limits?: TailwindLimits | undefined;
+}
+interface TailwindLimits {
+  /** Distinct classes handed to the compiler. */
+  readonly candidates: number;
+  /** Bytes of generated CSS. */
+  readonly cssBytes: number;
+}
+interface TailwindOutput {
+  readonly css: string;
+  readonly version: string;
+  /** Every candidate handed to the compiler, sorted, for the build manifest. */
+  readonly candidates: readonly string[];
+}
+/** Compile the discovered class set into CSS with the pinned Tailwind release. */
+declare const compileTailwind: (candidates: Iterable<string>, options?: TailwindOptions) => Promise<TailwindOutput>;
+interface ClassDiscovery {
+  readonly candidates: readonly string[];
+  readonly diagnostics: readonly EmailDiagnostic[];
+}
+/**
+ * Collect the class names one module states literally, and report the positions
+ * where a class is assembled from values the compiler cannot see.
+ */
+declare const discoverClassCandidates: (source: string, fileName: string) => ClassDiscovery;
+//#endregion
+//#region src/email/transform.d.ts
+/** Where this build serves assets from, and how Tailwind is configured. */
+interface TransformOptions {
+  readonly assetBase: string;
+  /**
+   * Specifier the generated stylesheet modules import `registerStylesheet`
+   * from. It is the published subpath by default; a host that resolves the
+   * package differently states its own.
+   */
+  readonly stylesheetModule?: string | undefined;
+  /** `false` compiles no Tailwind at all. */
+  readonly tailwind?: TailwindOptions | false | undefined;
+}
+interface ModuleTransform {
+  /** Always JavaScript, whatever the input file was. */
+  readonly code: string;
+  readonly asset?: AssetEntry | undefined;
+  /** Class names this module states literally, for the Tailwind candidate set. */
+  readonly classes?: readonly string[] | undefined;
+  readonly diagnostics: readonly EmailDiagnostic[];
+}
+/**
+ * Transform one project file into a JavaScript module.
+ *
+ * `.tsx`/`.ts` keep their authored semantics and gain source origins. A
+ * stylesheet becomes a module that registers its parsed rules. An imported
+ * binary becomes a module exporting the content-addressed URL of its bytes.
+ */
+declare const transformModule: (id: string, source: string | Uint8Array, options: TransformOptions) => Promise<ModuleTransform>;
+interface ProjectTransform {
+  /** Every input file, transformed; keys are unchanged. */
+  readonly files: Readonly<Record<string, string>>;
+  readonly assets: readonly AssetEntry[];
+  /**
+   * The compiled Tailwind sheet as a registering module, when the project used
+   * any utility class. A host writes it at `path` and makes the entry import it
+   * first, so the generated layers sit below the project's own stylesheets.
+   */
+  readonly tailwind: {
+    readonly path: string;
+    readonly code: string;
+  } | undefined;
+  readonly diagnostics: readonly EmailDiagnostic[];
+}
+/**
+ * The generated Tailwind module is a real file at the project root, not a
+ * virtual id. A virtual module has no directory, so its own relative imports
+ * resolve differently from the project's and the bundler ends up with a second
+ * copy of the stylesheet registry — the sheet registers into a registry the
+ * render never reads.
+ */
+declare const TAILWIND_MODULE_PATH = ".samva-tailwind.css";
+/** The specifier an entry at this path uses to reach the generated module. */
+declare const tailwindSpecifierFor: (entryPoint: string) => string;
+/** Run the transform over a whole project, then compile the classes it used. */
+declare const transformProject: (files: Readonly<Record<string, string | Uint8Array>>, options: TransformOptions) => Promise<ProjectTransform>;
+/**
+ * Put a side-effect import ahead of an entry's own imports, after any leading
+ * comment so a `@jsxImportSource` pragma keeps its position. Import order is
+ * cascade order, so the generated sheet has to be first.
+ */
+declare const withLeadingImport: (source: string, specifier: string) => string;
+/** The generated entry every host builds, so both evaluate the same module. */
+declare const EMAIL_ENTRY_WRAPPER = ".samva-email-entry.ts";
+/**
+ * The generated module that clears the stylesheet registry. It is imported
+ * first, as its own module, because import order is evaluation order: a reset
+ * written as a statement in the wrapper would run after the wrapper's imports
+ * had already registered.
+ */
+declare const EMAIL_RESET_MODULE = ".samva-email-reset.ts";
+/**
+ * The wrapper's source. It exports the template beside a render bound to the
+ * sheets the project's own imports registered, so the render runs inside the
+ * project's module graph and keeps its styles when a later project loaded into
+ * the same process resets the registry. Importing the renderer from outside
+ * that graph reaches a second copy of the registry and silently renders unstyled.
+ */
+declare const emailEntryWrapper: (entryPoint: string, imports?: readonly string[]) => string;
+/**
+ * A host that renders more than one project in one process shares the registry
+ * through its module cache, so every project graph starts by clearing it.
+ */
+declare const emailResetModule: (options: TransformOptions) => string;
+interface CompiledEmailProject {
+  /** Every module as JavaScript, keyed by its authored path. */
+  readonly files: Readonly<Record<string, string>>;
+  /** The generated module a host bundles or evaluates. */
+  readonly entryPoint: string;
+  /** The project's own entry, which the wrapper re-exports. */
+  readonly authoredEntry: string;
+  readonly assets: readonly AssetEntry[];
+  readonly diagnostics: readonly EmailDiagnostic[];
+}
+/**
+ * The whole compile step, files in and files out: every module transformed, the
+ * generated Tailwind sheet written, the generated imports added and the wrapper
+ * built. Both hosts call exactly this, which is what stops their outputs from
+ * drifting apart.
+ */
+declare const compileEmailProject: (source: Readonly<Record<string, string | Uint8Array>>, authoredEntry: string, options: TransformOptions) => Promise<CompiledEmailProject>;
+//#endregion
+export { ASSET_CONTENT_TYPES, type Ancestry, type AppliedStyles, type AssetEntry, type AssetManifest, COMPATIBILITY_PROVENANCE, type ClassDiscovery, type CompatibilityInput, type CompatibilityProvenance, type CompiledEmailProject, type CompiledSelector, type Compound, type CssDeclaration, type CssRule, EMAIL_CLIENT_MATRIX, EMAIL_DOCTYPE, EMAIL_ELEMENTS, EMAIL_ENTRY_WRAPPER, EMAIL_GLOBAL_ATTRIBUTES, EMAIL_RESET_MODULE, ESSENTIAL_CONSTRUCTS, type EmailAttributeSpec, type EmailClientTarget, EmailCompileError, type EmailCompileOutput, EmailDiagnostic, EmailDiagnosticSeverity, EmailElementSelection, type EmailElementSpec, type EmailGlobalProps, type EmailHtmlOutput, type EmailIntrinsicElements, type EmailLayout, type EmailStyle, type EmailTag, EmittedPosition, INSTANCE_PATH_ATTRIBUTE, type ModuleTransform, type ProjectTransform, type RenderedEmail, type SerializeEmailOptions, type Specificity, type Stylesheet, TAILWIND_MODULE_PATH, TAILWIND_VERSION, type TailwindLimits, type TailwindOptions, type TailwindOutput, type TransformOptions, applyStylesheet, assetEntry, assetUrl, checkAssetBase, checkEmailCompatibility, classListOf, collectStylesheets, compileEmail, compileEmailProject, compileSelector, compileTailwind, deriveEmailText, discoverClassCandidates, downlevelColors, downlevelMediaQuery, emailAuthoringTarget, emailDefinitionInstances, emailElement, emailEntryWrapper, emailResetModule, emailSelectionAncestry, emailSelectionIndex, emailSelectionSiblings, emailSelections, escapeAttribute, escapeText, finalizeValue, foldCalc, formatColor, formatEmailDiagnostic, hasBlockingCompatibility, hasBlockingDiagnostic, hasStylesheets, instrumentTsxSourceForPreview, isAssetPath, isExternalAsset, isUrlAttribute, matchesSelector, parseColor, parseStylesheet, registerStylesheet, renderEmail, renderHeadCss, resetStylesheets, resolveVariables, serializeEmailHtml, tailwindSpecifierFor, transformModule, transformProject, unknownCoverage, withLeadingImport };
+//# sourceMappingURL=compiler.d.ts.map