@samva/markup 0.8.0 → 0.9.0

package/dist/template-_QE_rQND.d.ts

@@ -0,0 +1,65 @@
+import { m as EmailNode } from "./elements-cqldpaJt.js";
+import { r as InputSchema } from "./input-schema-7dPFVvNE.js";
+import { StandardJSONSchemaV1 } from "@standard-schema/spec";
+//#region src/template.d.ts
+/** One actual-input render owns all of a message's authored content. */
+interface EmailContent {
+  readonly subject: string;
+  readonly preheader?: string;
+  readonly body: EmailNode;
+  readonly text?: string;
+}
+/**
+ * The one naming contract for a template id and a fixture key: a letter, a digit or `_` first,
+ * then those plus `.`, `_` and `-`.
+ *
+ * Both names are written into file paths — a local export writes one page at
+ * `templates/<id>/<fixture>.html` — so each has to be a single plain path segment. The rule lives
+ * at the declaration, so a project that could not be exported is refused where the name is
+ * written rather than at the end of a build. Consumers that resolve a path from these names
+ * import this pattern; they do not restate it.
+ */
+declare const TEMPLATE_NAME_PATTERN: RegExp;
+/** Caller input for generated references and separate authoring consumers. */
+type TemplateInput<T extends {
+  readonly schema: unknown;
+}> = T["schema"] extends InputSchema<infer Input> ? Input : never;
+/**
+ * The one naming contract for a template `id`: lowercase kebab-case, the same rule as the CLI and
+ * API slug, so the id a definition declares is the handle a caller sends by.
+ */
+declare const TEMPLATE_ID_PATTERN: RegExp;
+/** The email channel of a template: an envelope and a body, each a function of the input. */
+interface EmailChannel<Input> {
+  readonly subject: (input: Input) => string;
+  readonly preheader?: ((input: Input) => string | undefined) | undefined;
+  readonly body: (input: Input) => EmailNode;
+}
+/** A template as `defineTemplate` returns it: its identity, input contract and each channel it declares. */
+interface SmlTemplate<Input> {
+  readonly id: string;
+  readonly schema: InputSchema<Input>;
+  readonly fixtures: Readonly<Record<string, Input>>;
+  readonly locale?: string | undefined;
+  readonly email?: EmailChannel<Input> | undefined;
+  readonly sms?: ((input: Input) => EmailNode) | undefined;
+  readonly whatsapp?: ((input: Input) => EmailNode) | undefined;
+}
+/**
+ * Define a template: one id, one input schema, named fixtures and one body per channel. Every
+ * function in it receives the validated input and returns JSX or a string; a compiler reads them
+ * without running them, so nothing here executes at send time. Types are inferred from the
+ * Standard JSON Schema input.
+ */
+declare const defineTemplate: <S extends StandardJSONSchemaV1>(definition: {
+  readonly id: string;
+  readonly schema: S;
+  readonly fixtures: Readonly<Record<string, NoInfer<StandardJSONSchemaV1.InferInput<S>>>>;
+  readonly locale?: string | undefined;
+  readonly email?: EmailChannel<NoInfer<StandardJSONSchemaV1.InferInput<S>>> | undefined;
+  readonly sms?: ((input: NoInfer<StandardJSONSchemaV1.InferInput<S>>) => EmailNode) | undefined;
+  readonly whatsapp?: ((input: NoInfer<StandardJSONSchemaV1.InferInput<S>>) => EmailNode) | undefined;
+}) => SmlTemplate<StandardJSONSchemaV1.InferInput<S>>;
+//#endregion
+export { TEMPLATE_NAME_PATTERN as a, TEMPLATE_ID_PATTERN as i, EmailContent as n, TemplateInput as o, SmlTemplate as r, defineTemplate as s, EmailChannel as t };
+//# sourceMappingURL=template-_QE_rQND.d.ts.map

package/dist/template.d.ts

@@ -1,2 +1,2 @@
-import { a as TemplateRuntime, i as TemplateInput, n as TEMPLATE_NAME_PATTERN, o as defineEmail, r as TemplateDefinition, s as isTemplateDefinition, t as EmailContent } from "./template-DWftqh4x.js";
-export { EmailContent, TEMPLATE_NAME_PATTERN, TemplateDefinition, TemplateInput, TemplateRuntime, defineEmail, isTemplateDefinition };
+import { a as TEMPLATE_NAME_PATTERN, i as TEMPLATE_ID_PATTERN, n as EmailContent, o as TemplateInput, r as SmlTemplate, s as defineTemplate, t as EmailChannel } from "./template-_QE_rQND.js";
+export { EmailChannel, EmailContent, SmlTemplate, TEMPLATE_ID_PATTERN, TEMPLATE_NAME_PATTERN, TemplateInput, defineTemplate };

package/dist/template.js

@@ -1,8 +1,5 @@
-import { n as isObject } from "./guards-eV1qLbf2.js";
 import { n as inputSchema } from "./input-schema-zjkgrXn2.js";
 //#region src/template.ts
-/** Classify an evaluated module export without executing helpers as templates. */
-const isTemplateDefinition = (value) => isObject(value) && typeof value.id === "string" && typeof value.render === "function" && isObject(value.schema);
 /**
 * The one naming contract for a template id and a fixture key: a letter, a digit or `_` first,
 * then those plus `.`, `_` and `-`.
@@ -19,19 +16,27 @@ const checkTemplateName = (kind, value) => {
 	throw new TypeError(`${kind} ${JSON.stringify(value)} is not one path segment. A template id and a fixture key are written into file paths, so each must start with a letter, a digit or "_" and continue with letters, digits, ".", "_" or "-".`);
 };
 /**
-* Define an email template with caller-input inference from a Standard JSON Schema converter. The
-* helper is named for its channel because its render result is email content; `TemplateDefinition`
-* and `TemplateInput` stay channel-neutral.
+* The one naming contract for a template `id`: lowercase kebab-case, the same rule as the CLI and
+* API slug, so the id a definition declares is the handle a caller sends by.
 */
-const defineEmail = (definition) => {
-	checkTemplateName("Template id", definition.id);
-	for (const fixture of Object.keys(definition.fixtures)) checkTemplateName("Fixture key", fixture);
+const TEMPLATE_ID_PATTERN = /^(?=.{1,100}$)[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/**
+* Define a template: one id, one input schema, named fixtures and one body per channel. Every
+* function in it receives the validated input and returns JSX or a string; a compiler reads them
+* without running them, so nothing here executes at send time. Types are inferred from the
+* Standard JSON Schema input.
+*/
+const defineTemplate = (definition) => {
+	if (!TEMPLATE_ID_PATTERN.test(definition.id)) throw new TypeError(`Template id ${JSON.stringify(definition.id)} is not lowercase kebab-case. The id is the handle a send names, so write lowercase letters and digits joined by single hyphens, for example "order-shipped".`);
+	const fixtureNames = Object.keys(definition.fixtures);
+	if (fixtureNames.length === 0) throw new TypeError(`Template ${definition.id} declares no fixtures. Fixtures are the preview, the agent's render targets and the publish check; declare at least one.`);
+	for (const fixture of fixtureNames) checkTemplateName("Fixture key", fixture);
 	return {
 		...definition,
 		schema: inputSchema(definition.schema)
 	};
 };
 //#endregion
-export { TEMPLATE_NAME_PATTERN, defineEmail, isTemplateDefinition };
+export { TEMPLATE_ID_PATTERN, TEMPLATE_NAME_PATTERN, defineTemplate };
 
 //# sourceMappingURL=template.js.map

package/dist/theme-css.d.ts

@@ -1,4 +1,4 @@
-import { t as Diagnostic } from "./diagnostics-OcQKQYSY.js";
+import { Diagnostic } from "./diagnostics.js";
 import { Result } from "better-result";
 //#region src/theme-css.d.ts
 /** One `@font-face` a brand declares. `src` is the declaration value as authored. */

package/dist/theme-imports-lvBw3AD1.js

@@ -0,0 +1,109 @@
+import { buildLineMap, lineColumn } from "./diagnostics.js";
+import { parse } from "css-tree";
+//#region src/email/theme-imports.ts
+/** The CSS and TSX specifier a template uses to reach its organization's brand. */
+const BRAND_SPECIFIER = "samva:brand";
+const BRAND_IMPORT = /^samva:brand(?:\/([a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?))?$/;
+/** The brand a `samva:brand` specifier names: `undefined` slug means the default brand. */
+const parseBrandSpecifier = (specifier) => {
+	const match = BRAND_IMPORT.exec(specifier);
+	return match === null ? void 0 : { slug: match[1] };
+};
+/** The directory part of a project path, with no trailing slash (`""` at the root). */
+const projectDirectory = (path) => path.includes("/") ? path.slice(0, path.lastIndexOf("/")) : "";
+/** A relative or root-absolute stylesheet reference, resolved from a project directory. */
+const resolveFromDirectory = (directory, reference) => {
+	const segments = reference.startsWith("/") || directory === "" ? [] : directory.split("/");
+	for (const segment of reference.split("/")) {
+		if (segment === "" || segment === ".") continue;
+		if (segment === "..") {
+			if (segments.length === 0) return void 0;
+			segments.pop();
+		} else segments.push(segment);
+	}
+	return segments.length === 0 ? void 0 : segments.join("/");
+};
+const importTarget = (node) => {
+	if (node.type !== "Atrule" || node.prelude === null || node.prelude.type !== "AtrulePrelude") return { extra: true };
+	const parts = [...node.prelude.children].filter((part) => part.type !== "WhiteSpace");
+	const first = parts[0];
+	const target = first?.type === "String" ? first.value : first?.type === "Url" ? first.value : void 0;
+	return target === void 0 ? { extra: true } : {
+		target,
+		extra: parts.length > 1
+	};
+};
+/**
+* Walk the theme's `@import` graph. Project `.css` files resolve from the
+* importing file's directory; `samva:brand` and `samva:brand/<slug>` are
+* recorded for the brand the build supplies. Anything else is an error.
+*/
+const resolveThemeImports = (themePath, themeCss, files) => {
+	const stylesheets = /* @__PURE__ */ new Map([[themePath, themeCss]]);
+	const brandSpecifiers = /* @__PURE__ */ new Set();
+	const diagnostics = [];
+	const visit = (path, source, chain) => {
+		const lineMap = buildLineMap(source);
+		const ast = parse(source, {
+			positions: true,
+			parseValue: false,
+			parseRulePrelude: false
+		});
+		if (ast.type !== "StyleSheet") return;
+		for (const node of ast.children) {
+			if (node.type !== "Atrule" || node.name.toLowerCase() !== "import") continue;
+			const position = lineColumn(lineMap, node.loc?.start.offset ?? 0);
+			const origins = [{
+				fileName: path,
+				lineNumber: position.line,
+				columnNumber: position.column
+			}];
+			const refuse = (message) => diagnostics.push({
+				code: "css-import-unresolved",
+				severity: "error",
+				message,
+				origins
+			});
+			const { target, extra } = importTarget(node);
+			if (target === void 0) {
+				refuse(`${path}: @import needs a quoted stylesheet path or "samva:brand".`);
+				continue;
+			}
+			if (extra) {
+				refuse(`${path}: @import ${JSON.stringify(target)} takes no layer, supports or media conditions; the import order is the layering.`);
+				continue;
+			}
+			if (parseBrandSpecifier(target) !== void 0) {
+				brandSpecifiers.add(target);
+				continue;
+			}
+			if (!/^\.{0,2}\//.test(target) || !/\.css$/i.test(target.replace(/[?#].*$/, ""))) {
+				refuse(`${path}: @import ${JSON.stringify(target)} is not a project stylesheet or "samva:brand". The compiler supplies Tailwind itself; import project .css files by relative path.`);
+				continue;
+			}
+			const resolved = resolveFromDirectory(projectDirectory(path), target.replace(/[?#].*$/, ""));
+			const content = resolved === void 0 ? void 0 : files[resolved];
+			if (resolved === void 0 || typeof content !== "string") {
+				refuse(`${path}: @import ${JSON.stringify(target)} names no stylesheet in the project.`);
+				continue;
+			}
+			if (chain.includes(resolved)) {
+				refuse(`${path}: @import ${JSON.stringify(target)} imports itself through ${chain.join(" → ")}.`);
+				continue;
+			}
+			if (stylesheets.has(resolved)) continue;
+			stylesheets.set(resolved, content);
+			visit(resolved, content, [...chain, resolved]);
+		}
+	};
+	visit(themePath, themeCss, [themePath]);
+	return {
+		stylesheets,
+		brandSpecifiers: [...brandSpecifiers].sort(),
+		diagnostics
+	};
+};
+//#endregion
+export { resolveThemeImports as a, resolveFromDirectory as i, parseBrandSpecifier as n, projectDirectory as r, BRAND_SPECIFIER as t };
+
+//# sourceMappingURL=theme-imports-lvBw3AD1.js.map

package/dist/transform-Ct2OMkFN.d.ts

@@ -0,0 +1,153 @@
+import { r as EmailDiagnostic } from "./diagnostics-B-Gym34R.js";
+import { n as EmittedPosition } from "./preview-Ekdg1dXG.js";
+import { i as Stylesheet } from "./css-BVQKICKC.js";
+import { n as AssetEntry } from "./assets-C5duwTya.js";
+import { a as EmailBrand } from "./brand-B-0bN_Ir.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/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
+export { checkEmailCompatibility as _, ClassDiscovery as a, TailwindOutput as c, COMPATIBILITY_PROVENANCE as d, CompatibilityInput as f, EmailClientTarget as g, ESSENTIAL_CONSTRUCTS as h, transformProject as i, compileTailwind as l, EMAIL_CLIENT_MATRIX as m, TransformOptions as n, TailwindLimits as o, CompatibilityProvenance as p, projectBrandSpecifier as r, TailwindOptions as s, ProjectTransform as t, discoverClassCandidates as u, hasBlockingCompatibility as v, unknownCoverage as y };
+//# sourceMappingURL=transform-Ct2OMkFN.d.ts.map

package/dist/whatsapp.d.ts

@@ -0,0 +1,57 @@
+import { n as WhatsAppCategory, r as WhatsAppHeaderType } from "./channel-specs-C2feJwuP.js";
+import { f as EmailChild, m as EmailNode } from "./elements-cqldpaJt.js";
+//#region src/whatsapp.d.ts
+interface WhatsAppProps {
+  readonly name?: string | undefined;
+  /** The Meta language code, for example `en_US`. */
+  readonly language: string;
+  readonly category: WhatsAppCategory;
+  readonly children?: EmailChild;
+}
+interface WhatsAppHeaderProps {
+  /** `text` by default; for `image`, `video` and `document` the child is the media URL. */
+  readonly type?: WhatsAppHeaderType | undefined;
+  readonly children?: EmailChild;
+}
+interface WhatsAppTextProps {
+  readonly children?: EmailChild;
+}
+interface WhatsAppButtonsProps {
+  readonly children?: EmailChild;
+}
+interface WhatsAppUrlButtonProps {
+  readonly url: string;
+  /** The button label. */
+  readonly children?: EmailChild;
+}
+interface WhatsAppPhoneButtonProps {
+  readonly phone: string;
+  /** The button label. */
+  readonly children?: EmailChild;
+}
+interface WhatsAppQuickReplyButtonProps {
+  /** The button label. */
+  readonly children?: EmailChild;
+}
+interface WhatsAppCopyCodeButtonProps {
+  /** The code the button copies. */
+  readonly children?: EmailChild;
+}
+/**
+ * The root of a WhatsApp body. Meta's template anatomy is the vocabulary: `WhatsApp.Header`,
+ * `WhatsApp.Body`, `WhatsApp.Footer` and `WhatsApp.Buttons`, whose children are the four button
+ * kinds.
+ */
+declare const WhatsApp: ((props: WhatsAppProps) => EmailNode) & {
+  Header: (props: WhatsAppHeaderProps) => EmailNode;
+  Body: (props: WhatsAppTextProps) => EmailNode;
+  Footer: (props: WhatsAppTextProps) => EmailNode;
+  Buttons: (props: WhatsAppButtonsProps) => EmailNode;
+  UrlButton: (props: WhatsAppUrlButtonProps) => EmailNode;
+  QuickReplyButton: (props: WhatsAppQuickReplyButtonProps) => EmailNode;
+  PhoneButton: (props: WhatsAppPhoneButtonProps) => EmailNode;
+  CopyCodeButton: (props: WhatsAppCopyCodeButtonProps) => EmailNode;
+};
+//#endregion
+export { WhatsApp, WhatsAppButtonsProps, type WhatsAppCategory, WhatsAppCopyCodeButtonProps, WhatsAppHeaderProps, type WhatsAppHeaderType, WhatsAppPhoneButtonProps, WhatsAppProps, WhatsAppQuickReplyButtonProps, WhatsAppTextProps, WhatsAppUrlButtonProps };
+//# sourceMappingURL=whatsapp.d.ts.map

package/dist/whatsapp.js

@@ -0,0 +1,22 @@
+import { Fragment, jsx } from "./email/jsx-runtime.js";
+//#region src/whatsapp.ts
+const fragment = (children) => jsx(Fragment, { children });
+/**
+* The root of a WhatsApp body. Meta's template anatomy is the vocabulary: `WhatsApp.Header`,
+* `WhatsApp.Body`, `WhatsApp.Footer` and `WhatsApp.Buttons`, whose children are the four button
+* kinds.
+*/
+const WhatsApp = Object.assign((props) => fragment(props.children), {
+	Header: (props) => fragment(props.children),
+	Body: (props) => fragment(props.children),
+	Footer: (props) => fragment(props.children),
+	Buttons: (props) => fragment(props.children),
+	UrlButton: (props) => fragment(props.children),
+	QuickReplyButton: (props) => fragment(props.children),
+	PhoneButton: (props) => fragment(props.children),
+	CopyCodeButton: (props) => fragment(props.children)
+});
+//#endregion
+export { WhatsApp };
+
+//# sourceMappingURL=whatsapp.js.map