@samva/markup 0.9.0 → 0.10.0

package/dist/{theme-css.d.ts → brand.d.ts}

@@ -1,5 +1,14 @@
-import { Diagnostic } from "./diagnostics.js";
+import { C as withoutUnsubscribeRow, S as renderedFooterMarkers, _ as EmailBrandSocialLink, a as assetUrl, b as UNSUBSCRIBE_ROW_ATTRIBUTE, c as isExternalAsset, d as BrandFooterProps, f as BrandLogoProps, g as EmailBrandFooter, h as EmailBrandAssets, i as assetEntry, l as BRAND_COMPONENT_CLASSES, m as EmailBrandAddress, n as AssetEntry, o as checkAssetBase, p as EmailBrand, r as AssetManifest, s as isAssetPath, t as ASSET_CONTENT_TYPES, u as BrandComponents, v as FOOTER_ATTRIBUTE, x as brandComponents, y as RenderedFooterMarkers } from "./assets-BIsyMQ92.js";
+import { t as Diagnostic } from "./diagnostic-model-DxthUZBT.js";
 import { Result } from "better-result";
+//#region src/internal/unsubscribe-link.d.ts
+/**
+ * The per-recipient unsubscribe URL is not known at render: the send path
+ * substitutes each delivery's link for this placeholder, or removes the
+ * unsubscribe row when the send resolved no unsubscribe group.
+ */
+declare const UNSUBSCRIBE_URL_PLACEHOLDER = "%samva:unsubscribe-url%";
+//#endregion
 //#region src/theme-css.d.ts
 /** One `@font-face` a brand declares. `src` is the declaration value as authored. */
 interface BrandFontFace {
@@ -61,5 +70,5 @@ declare const brandThemeVariables: (brand: BrandCss) => Readonly<Record<string,
 /** The stylesheet Tailwind compiles for `@import "samva:brand"`: `brandThemeVariables` and the font faces. */
 declare const brandTailwindCss: (brand: BrandCss) => string;
 //#endregion
-export { BRAND_COLOR_VARIABLE, BRAND_FOREGROUND_VARIABLE, BrandCss, BrandFontFace, brandForegroundDefaults, brandTailwindCss, brandThemeVariables, contrastForeground, darkVariableName, parseBrandCss, printBrandCss };
-//# sourceMappingURL=theme-css.d.ts.map
+export { ASSET_CONTENT_TYPES, AssetEntry, AssetManifest, BRAND_COLOR_VARIABLE, BRAND_COMPONENT_CLASSES, BRAND_FOREGROUND_VARIABLE, BrandComponents, BrandCss, BrandFontFace, BrandFooterProps, BrandLogoProps, EmailBrand, EmailBrandAddress, EmailBrandAssets, EmailBrandFooter, EmailBrandSocialLink, FOOTER_ATTRIBUTE, RenderedFooterMarkers, UNSUBSCRIBE_ROW_ATTRIBUTE, UNSUBSCRIBE_URL_PLACEHOLDER, assetEntry, assetUrl, brandComponents, brandForegroundDefaults, brandTailwindCss, brandThemeVariables, checkAssetBase, contrastForeground, darkVariableName, isAssetPath, isExternalAsset, parseBrandCss, printBrandCss, renderedFooterMarkers, withoutUnsubscribeRow };
+//# sourceMappingURL=brand.d.ts.map

package/dist/brand.js

@@ -0,0 +1,4 @@
+import { i as UNSUBSCRIBE_URL_PLACEHOLDER } from "./unsubscribe-link-CoesnQDU.js";
+import { a as brandThemeVariables, c as parseBrandCss, i as brandTailwindCss, l as printBrandCss, n as BRAND_FOREGROUND_VARIABLE, o as contrastForeground, r as brandForegroundDefaults, s as darkVariableName, t as BRAND_COLOR_VARIABLE } from "./theme-css-JtRCm1fb.js";
+import { a as renderedFooterMarkers, c as assetEntry, d as isAssetPath, f as isExternalAsset, i as brandComponents, l as assetUrl, n as FOOTER_ATTRIBUTE, o as withoutUnsubscribeRow, r as UNSUBSCRIBE_ROW_ATTRIBUTE, s as ASSET_CONTENT_TYPES, t as BRAND_COMPONENT_CLASSES, u as checkAssetBase } from "./brand-C0MKTwmX.js";
+export { ASSET_CONTENT_TYPES, BRAND_COLOR_VARIABLE, BRAND_COMPONENT_CLASSES, BRAND_FOREGROUND_VARIABLE, FOOTER_ATTRIBUTE, UNSUBSCRIBE_ROW_ATTRIBUTE, UNSUBSCRIBE_URL_PLACEHOLDER, assetEntry, assetUrl, brandComponents, brandForegroundDefaults, brandTailwindCss, brandThemeVariables, checkAssetBase, contrastForeground, darkVariableName, isAssetPath, isExternalAsset, parseBrandCss, printBrandCss, renderedFooterMarkers, withoutUnsubscribeRow };

package/dist/compiler.d.ts

@@ -1,13 +1,67 @@
-import { i as EmailDiagnosticSeverity, n as EmailCompileError, o as formatEmailDiagnostic, r as EmailDiagnostic, s as hasBlockingDiagnostic } from "./diagnostics-B-Gym34R.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-cqldpaJt.js";
-import { a as emailAuthoringTarget, c as emailSelectionIndex, l as emailSelectionSiblings, n as EmittedPosition, o as emailDefinitionInstances, r as INSTANCE_PATH_ATTRIBUTE, s as emailSelectionAncestry, t as EmailElementSelection, u as emailSelections } from "./preview-Ekdg1dXG.js";
-import { a as escapeAttribute, c as serializeEmailHtml, n as SerializeEmailOptions, o as escapeText, t as EmailHtmlOutput } from "./html-BJepOwZ4.js";
-import { _ as checkEmailCompatibility, a as ClassDiscovery, c as TailwindOutput, d as COMPATIBILITY_PROVENANCE, f as CompatibilityInput, g as EmailClientTarget, h as ESSENTIAL_CONSTRUCTS, i as transformProject, l as compileTailwind, m as EMAIL_CLIENT_MATRIX, n as TransformOptions, o as TailwindLimits, p as CompatibilityProvenance, r as projectBrandSpecifier, s as TailwindOptions, t as ProjectTransform, u as discoverClassCandidates, v as hasBlockingCompatibility, y as unknownCoverage } from "./transform-Ct2OMkFN.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-BVQKICKC.js";
-import { EMAIL_DOCTYPE, EmailCompileOutput, RenderedEmail, compileEmail } from "./email/render.js";
-import { a as assetUrl, c as isExternalAsset, i as assetEntry, n as AssetEntry, o as checkAssetBase, r as AssetManifest, s as isAssetPath, t as ASSET_CONTENT_TYPES } from "./assets-C5duwTya.js";
-import { a as EmailBrand, c as EmailBrandFooter, l as EmailBrandSocialLink, o as EmailBrandAddress, s as EmailBrandAssets } from "./brand-B-0bN_Ir.js";
+import { a as TemplateDiagnostic, r as EmailDiagnostic } from "./diagnostics-B-Gym34R.js";
+import { r as EmailNode } from "./jsx-runtime-ylIOnaSf.js";
+import { n as AssetEntry, p as EmailBrand, u as BrandComponents } from "./assets-BIsyMQ92.js";
+import { C as Compound, D as EmittedPosition, S as CompiledSelector, T as matchesSelector, _ as Specificity, b as parseStylesheet, ct as TemplateIr, g as CssRule, h as CssDeclaration, r as RenderedEmail, v as Stylesheet, w as classListOf, x as Ancestry, y as compileSelector } from "./render-BPonDpCl.js";
+import { a as TEMPLATE_NAME_PATTERN, n as EmailContent } from "./template-DMPwxMSq.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/css-values.d.ts
 /**
  * Expand `var(--x, fallback)` against the collected custom properties.
@@ -64,6 +118,93 @@ declare const applyStylesheet: (root: EmailNode, sheet: Stylesheet, options?: {
 /** 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;
+  /**
+   * The project path `css` was read from (`theme.css` by default). Its
+   * relative `@import`s resolve from this file's directory.
+   */
+  readonly cssPath?: 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[];
+}
+/**
+ * What the project theme's `@import`s resolve to, already checked by
+ * `resolveThemeImports`: project stylesheets by path, and the brand theme
+ * `samva:brand` stands for.
+ */
+interface TailwindImports {
+  readonly stylesheets: ReadonlyMap<string, string>;
+  readonly brandCss?: string | undefined;
+}
+/** Compile the discovered class set into CSS with the pinned Tailwind release. */
+declare const compileTailwind: (candidates: Iterable<string>, options?: TailwindOptions, imports?: TailwindImports) => 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;
+  /** `false` compiles no Tailwind at all. */
+  readonly tailwind?: TailwindOptions | false | undefined;
+  /**
+   * The brand `samva:brand` resolves to, supplied by the host. A project that
+   * imports `samva:brand` with no brand here fails to compile.
+   */
+  readonly brand?: EmailBrand | undefined;
+}
+interface ProjectTransform {
+  readonly assets: readonly AssetEntry[];
+  /** The compiled Tailwind sheet, when the project used any utility class. */
+  readonly tailwindSheet: Stylesheet | undefined;
+  /** Every project stylesheet, parsed, by path. */
+  readonly stylesheets: ReadonlyMap<string, Stylesheet>;
+  readonly diagnostics: readonly EmailDiagnostic[];
+}
+/**
+ * The `samva:brand` specifier a project imports — from its theme's `@import`s
+ * or its TSX — so a host can fetch that brand before it compiles. `undefined`
+ * when the project imports no brand. A project that names two brands gets the
+ * first here and a refusal from the compile.
+ */
+declare const projectBrandSpecifier: (files: Readonly<Record<string, string | Uint8Array>>, themePath?: string) => string | undefined;
+/** Read a whole project, then compile the classes its scripts used. */
+declare const transformProject: (files: Readonly<Record<string, string | Uint8Array>>, options: TransformOptions) => Promise<ProjectTransform>;
+//#endregion
 //#region src/email/theme-imports.d.ts
 /** The CSS and TSX specifier a template uses to reach its organization's brand. */
 declare const BRAND_SPECIFIER = "samva:brand";
@@ -72,5 +213,84 @@ declare const parseBrandSpecifier: (specifier: string) => {
   readonly slug: string | undefined;
 } | undefined;
 //#endregion
-export { ASSET_CONTENT_TYPES, type Ancestry, type AppliedStyles, type AssetEntry, type AssetManifest, BRAND_SPECIFIER, COMPATIBILITY_PROVENANCE, type ClassDiscovery, type CompatibilityInput, type CompatibilityProvenance, type CompiledSelector, type Compound, type CssDeclaration, type CssRule, EMAIL_CLIENT_MATRIX, EMAIL_DOCTYPE, EMAIL_ELEMENTS, EMAIL_GLOBAL_ATTRIBUTES, ESSENTIAL_CONSTRUCTS, type EmailAttributeSpec, type EmailBrand, type EmailBrandAddress, type EmailBrandAssets, type EmailBrandFooter, type EmailBrandSocialLink, type EmailClientTarget, EmailCompileError, type EmailCompileOutput, type EmailDiagnostic, type EmailDiagnosticSeverity, type EmailElementSelection, type EmailElementSpec, type EmailGlobalProps, type EmailHtmlOutput, type EmailIntrinsicElements, type EmailLayout, type EmailStyle, type EmailTag, type EmittedPosition, INSTANCE_PATH_ATTRIBUTE, type ProjectTransform, type RenderedEmail, type SerializeEmailOptions, type Specificity, type Stylesheet, TAILWIND_VERSION, type TailwindLimits, type TailwindOptions, type TailwindOutput, type TransformOptions, applyStylesheet, assetEntry, assetUrl, checkAssetBase, checkEmailCompatibility, classListOf, compileEmail, compileSelector, compileTailwind, deriveEmailText, discoverClassCandidates, downlevelColors, downlevelMediaQuery, emailAuthoringTarget, emailDefinitionInstances, emailElement, emailSelectionAncestry, emailSelectionIndex, emailSelectionSiblings, emailSelections, escapeAttribute, escapeText, finalizeValue, foldCalc, formatColor, formatEmailDiagnostic, hasBlockingCompatibility, hasBlockingDiagnostic, isAssetPath, isExternalAsset, isUrlAttribute, matchesSelector, parseBrandSpecifier, parseColor, parseStylesheet, projectBrandSpecifier, renderHeadCss, resolveVariables, serializeEmailHtml, transformProject, unknownCoverage };
+//#region src/email/brand-footer.d.ts
+/** A footer block for the send path to append, and its plain-text tail. */
+interface RenderedBrandFooter {
+  readonly html: string;
+  readonly text: string;
+}
+/**
+ * Render `BrandFooter` against a brand on its own, for the send path to
+ * append to a message whose template renders no footer of its own. It
+ * compiles the same component, styled by the same brand theme, a template
+ * would get from `samva:brand`. Without `unsubscribe` the unsubscribe row is
+ * left out.
+ */
+declare const renderBrandFooter: (brand: EmailBrand, options: {
+  readonly unsubscribe: boolean;
+}) => Promise<RenderedBrandFooter>;
+/**
+ * Render content against a brand as a project whose `theme.css` is
+ * `@import "samva:brand";` renders it: Tailwind compiles the brand theme for
+ * the classes the content names, `BrandLogo` and `BrandFooter` are bound to the
+ * brand, and the render inlines the result. A brand preview renders through
+ * this, so it shows what a template importing the brand compiles to.
+ */
+declare const renderBrandSample: (brand: EmailBrand, sample: {
+  /** Every class the content names; nothing is discovered from source here. */
+  readonly classes: readonly string[];
+  readonly render: (components: BrandComponents) => EmailContent;
+}) => Promise<RenderedEmail>;
+//#endregion
+//#region src/sml/lower-project.d.ts
+interface CompiledTemplate {
+  /** The IR, or `undefined` when a finding blocks it. */
+  readonly ir: TemplateIr | undefined;
+  /** The fixtures read from the entry, with imported assets resolved to their URLs. */
+  readonly fixtures: Readonly<Record<string, unknown>>;
+  readonly assets: readonly AssetEntry[];
+  /** Errors block the IR; warnings ride along. */
+  readonly diagnostics: readonly TemplateDiagnostic[];
+}
+//#endregion
+//#region src/sml/compile.d.ts
+interface CompileTemplateOptions extends TransformOptions {
+  /** The project's files by path. Binary files are addressed as assets. */
+  readonly files: Readonly<Record<string, string | Uint8Array>>;
+  /** The entry: a `.tsx` file that default-exports `defineTemplate({ ... })`. */
+  readonly entry: string;
+  /**
+   * The portable JSON Schema, for an entry whose `schema` is not a literal `jsonSchema(...)`
+   * (a Zod or Effect schema needs a library to become JSON Schema). A host that has evaluated the
+   * schema passes its conversion here; a literal schema is read from source and this is ignored.
+   */
+  readonly schema?: Readonly<Record<string, unknown>> | undefined;
+}
+/** Compile a project's entry template to IR without evaluating any of it. */
+declare const compileTemplate: (options: CompileTemplateOptions) => Promise<CompiledTemplate>;
+//#endregion
+//#region src/sml/compatibility.d.ts
+/**
+ * Check what each declared fixture delivers against the pinned client matrix. The rules run on the
+ * rendered document, because what a client drops is what the compiler produced, and every finding
+ * is located at the source of the element that produced it.
+ */
+declare const checkTemplateCompatibility: (ir: TemplateIr, fixtures: Readonly<Record<string, unknown>>, options?: {
+  readonly clients?: readonly EmailClientTarget[] | undefined;
+}) => readonly EmailDiagnostic[];
+//#endregion
+//#region src/sml/profile.d.ts
+/**
+ * Check an entry against the static profile. Pass the entry's source alone, or the project's files
+ * and the entry's path. Imports of files that are absent are trusted to exist, and the brand,
+ * Tailwind and theme are not resolved, so the result holds only findings the source itself owns.
+ */
+declare const checkStaticProfile: (files: string | Readonly<Record<string, string | Uint8Array>>, entry?: string) => readonly TemplateDiagnostic[];
+/**
+ * The errors in `after` that `before` did not already have, compared by code and message so a
+ * finding that only moved does not count as new.
+ */
+declare const introducedProfileErrors: (before: readonly TemplateDiagnostic[], after: readonly TemplateDiagnostic[]) => readonly TemplateDiagnostic[];
+//#endregion
+export { type Ancestry, type AppliedStyles, BRAND_SPECIFIER, COMPATIBILITY_PROVENANCE, type ClassDiscovery, type CompatibilityInput, type CompatibilityProvenance, type CompileTemplateOptions, type CompiledSelector, type CompiledTemplate, type Compound, type CssDeclaration, type CssRule, EMAIL_CLIENT_MATRIX, ESSENTIAL_CONSTRUCTS, type EmailClientTarget, type EmailContent, type ProjectTransform, type RenderedBrandFooter, type Specificity, type Stylesheet, TAILWIND_VERSION, TEMPLATE_NAME_PATTERN, type TailwindLimits, type TailwindOptions, type TailwindOutput, type TransformOptions, applyStylesheet, checkEmailCompatibility, checkStaticProfile, checkTemplateCompatibility, classListOf, compileSelector, compileTailwind, compileTemplate, discoverClassCandidates, downlevelColors, downlevelMediaQuery, finalizeValue, foldCalc, formatColor, hasBlockingCompatibility, introducedProfileErrors, matchesSelector, parseBrandSpecifier, parseColor, parseStylesheet, projectBrandSpecifier, renderBrandFooter, renderBrandSample, renderHeadCss, resolveVariables, transformProject, unknownCoverage };
 //# sourceMappingURL=compiler.d.ts.map