@maizzle/framework 6.0.0-rc.3 → 6.0.0-rc.4

package/dist/types/config.d.mts

@@ -4,62 +4,282 @@ import * as unplugin_vue_markdown_types0 from "unplugin-vue-markdown/types";
 
 //#region src/types/config.d.ts
 interface UrlQueryOptions {
+  /**
+   * CSS selectors for elements to process.
+   *
+   * @default ['a']
+   */
   tags?: string[];
+  /**
+   * HTML attributes containing URLs to append query params to.
+   *
+   * @default ['src', 'href', 'poster', 'srcset', 'background']
+   */
   attributes?: string[];
+  /**
+   * When `true`, only appends query params to absolute URLs.
+   *
+   * @default true
+   */
   strict?: boolean;
+  /**
+   * Options forwarded to the `query-string` library for controlling serialization.
+   *
+   * @default { encode: false }
+   */
   qs?: Record<string, unknown>;
 }
 type UrlQuery = Record<string, unknown> & {
   _options?: UrlQueryOptions;
 };
 interface UrlConfig {
+  /**
+   * Append query parameters to URLs in your HTML.
+   *
+   * @example
+   * url: {
+   *   query: {
+   *     utm_source: 'maizzle',
+   *     utm_medium: 'email',
+   *   }
+   * }
+   */
   query?: UrlQuery;
+  /**
+   * Prepend a base URL to relative paths.
+   *
+   * Pass a string to prepend to all tags, or an object for fine-grained control.
+   *
+   * @example
+   * url: {
+   *   base: 'https://cdn.example.com/emails/',
+   * }
+   */
   base?: string | {
-    url?: string;
-    tags?: string[] | Record<string, Record<string, string | boolean>>;
-    attributes?: Record<string, string>;
-    styleTag?: boolean;
+    /** The base URL to prepend. */url?: string; /** Tags or tag-attribute map to process. */
+    tags?: string[] | Record<string, Record<string, string | boolean>>; /** Attributes to process. */
+    attributes?: Record<string, string>; /** Also apply to URLs in `<style>` tags. */
+    styleTag?: boolean; /** Also apply to URLs in inline `style` attributes. */
     inlineCss?: boolean;
   };
 }
 interface CssConfig {
+  /**
+   * Base directory for Tailwind CSS `@source` resolution.
+   *
+   * Automatically set to `root` when `root` is configured.
+   */
   base?: string;
+  /**
+   * Remove unused CSS.
+   *
+   * Set to `true` to enable with defaults, or pass an options object.
+   *
+   * @default false
+   */
   purge?: boolean | Record<string, unknown>;
+  /**
+   * Inline CSS from `<style>` tags into matching HTML elements.
+   *
+   * Set to `true` to enable with defaults, or pass an options object for fine-grained control.
+   *
+   * @example
+   * css: {
+   *   inline: {
+   *     removeStyleTags: true,
+   *     applyWidthAttributes: true,
+   *   }
+   * }
+   */
   inline?: boolean | {
+    /**
+     * Convert HTML attributes like `width`, `height`, `bgcolor`, and `valign`
+     * to inline CSS styles. Set to `true` for all, or pass an array of attribute names.
+     *
+     * @default false
+     */
     attributeToStyle?: boolean | string[];
+    /**
+     * Remove `<style>` tags after inlining.
+     *
+     * @default false
+     */
     removeStyleTags?: boolean;
+    /**
+     * Remove selectors from `<style>` tags after they have been inlined.
+     *
+     * @default true
+     */
     removeInlinedSelectors?: boolean;
+    /**
+     * Convert `0px`, `0em` etc. to `0` in inline styles.
+     *
+     * @default true
+     */
     preferUnitlessValues?: boolean;
+    /**
+     * CSS selectors to preserve in `<style>` tags, even after inlining.
+     *
+     * @default []
+     */
     safelist?: string[];
+    /**
+     * Duplicate CSS properties to HTML attributes.
+     *
+     * @default {}
+     *
+     * @example
+     * styleToAttribute: {
+     *   'background-color': 'bgcolor',
+     * }
+     */
     styleToAttribute?: Record<string, string>;
+    /**
+     * Add `width` HTML attributes based on inline CSS width values.
+     *
+     * @default true
+     */
     applyWidthAttributes?: boolean;
+    /**
+     * Add `height` HTML attributes based on inline CSS height values.
+     *
+     * @default true
+     */
     applyHeightAttributes?: boolean;
+    /**
+     * Elements that can receive `width` HTML attributes.
+     *
+     * @default ['img', 'video']
+     */
     widthElements?: string[];
+    /**
+     * Elements that can receive `height` HTML attributes.
+     *
+     * @default ['img', 'video']
+     */
     heightElements?: string[];
+    /**
+     * CSS properties to exclude from inlining.
+     *
+     * @default []
+     */
     excludedProperties?: string[];
+    /**
+     * Template language code blocks to preserve during inlining.
+     *
+     * @default { EJS: { start: '<%', end: '%>' }, HBS: { start: '\{\{', end: '}}' } }
+     */
     codeBlocks?: Record<string, {
       start: string;
       end: string;
     }>;
+    /**
+     * Additional CSS string to inline alongside `<style>` tag contents.
+     */
     customCSS?: string;
-    [key: string]: unknown;
   };
+  /**
+   * Merge duplicate `@media` queries and sort them.
+   *
+   * Enabled by default. Set to `false` to disable, or pass an object to control sort order.
+   *
+   * @default true
+   *
+   * @example
+   * css: {
+   *   media: { sort: 'desktop-first' },
+   * }
+   */
   media?: boolean | {
+    /**
+     * Sort order for media queries.
+     *
+     * @default 'mobile-first'
+     */
     sort?: 'mobile-first' | 'desktop-first' | ((a: string, b: string) => number);
   };
+  /**
+   * Convert unitless CSS values to their unitless equivalents.
+   *
+   * For example, `line-height: 24px` with a `16px` font becomes `line-height: 1.5`.
+   *
+   * @default true
+   */
   preferUnitless?: boolean;
+  /**
+   * Resolve CSS `calc()` expressions to static values where possible.
+   *
+   * @default true
+   */
   resolveCalc?: boolean;
+  /**
+   * Resolve CSS custom properties (`var()`) to their computed values.
+   *
+   * @default true
+   */
   resolveProps?: boolean;
+  /**
+   * Replace unsafe CSS class names with email-safe equivalents.
+   *
+   * @default true
+   */
   safe?: boolean | Record<string, string>;
-  sixHex?: boolean;
+  /**
+   * Rewrite longhand CSS to shorthand where possible.
+   *
+   * For example, `padding: 10px 20px 10px 20px` becomes `padding: 10px 20px`.
+   *
+   * @default false
+   */
   shorthand?: boolean | {
     tags?: string[];
   };
+  /**
+   * Remove specific CSS declarations by selector.
+   *
+   * @example
+   * css: {
+   *   removeDeclarations: {
+   *     ':root': '*',
+   *   }
+   * }
+   */
   removeDeclarations?: Record<string, RemoveValue>;
+  /**
+   * File paths to exclude from CSS processing.
+   *
+   * @example
+   * css: {
+   *   exclude: ['emails/amp/**'],
+   * }
+   */
   exclude?: string[];
 }
 interface AttributesConfig {
+  /**
+   * Add attributes to HTML elements.
+   *
+   * @example
+   * html: {
+   *   attributes: {
+   *     add: {
+   *       table: { cellpadding: 0, cellspacing: 0, role: 'none' },
+   *       img: { alt: '' },
+   *     }
+   *   }
+   * }
+   */
   add?: false | Record<string, Record<string, string | boolean | number>>;
+  /**
+   * Remove attributes from HTML elements by name or name-value pair.
+   *
+   * @example
+   * html: {
+   *   attributes: {
+   *     remove: ['data-test', { name: 'class', value: /^js-/ }],
+   *   }
+   * }
+   */
   remove?: Array<string | {
     name: string;
     value?: string | RegExp;
@@ -67,77 +287,202 @@ interface AttributesConfig {
 }
 type EntitiesConfig = boolean | Record<string, string>;
 interface PostcssConfig {
-  /** Selector prefixes to strip from compiled CSS (e.g. ':host', ':lang'). */
+  /**
+   * Selector prefixes to strip from compiled CSS.
+   *
+   * @default [':host', ':lang']
+   *
+   * @example
+   * postcss: {
+   *   removeSelectors: [':host', ':lang', ':root'],
+   * }
+   */
   removeSelectors?: string[];
-  /** At-rule names to strip from compiled CSS (e.g. '@layer', '@property'). */
+  /**
+   * At-rule names to strip from compiled CSS.
+   *
+   * @default ['layer', 'property']
+   *
+   * @example
+   * postcss: {
+   *   removeAtRules: ['layer', 'property', 'charset'],
+   * }
+   */
   removeAtRules?: string[];
-  [key: string]: unknown;
 }
 interface HtmlConfig {
+  /** Configure HTML attribute transformations. */
   attributes?: AttributesConfig;
+  /**
+   * Decode HTML entities.
+   *
+   * Set to `true` to decode all, or pass a map of entities to decode.
+   *
+   * @default true
+   */
   decodeEntities?: EntitiesConfig;
+  /**
+   * Pretty-print the HTML output.
+   *
+   * Set to `true` to enable with defaults, or pass options.
+   */
   format?: boolean | oxfmt.FormatOptions;
+  /**
+   * Minify the HTML output.
+   *
+   * Set to `true` to enable with defaults, or pass options.
+   */
   minify?: boolean | Record<string, unknown>;
 }
 interface MaizzleConfig {
   /**
    * Root directory for the Maizzle email project.
    *
-   * When set, relative paths for `content`, `static.source`, component
-   * auto-import directories, `.d.ts` output, and `css.base` are all
-   * resolved relative to this directory.
+   * When set, relative paths for `content`, `static.source`,
+   * and `css.base` are all resolved relative to this directory.
    *
    * Defaults to `process.cwd()`.
    *
    * @example
-   * // In a Laravel app where emails live under resources/js/emails:
    * maizzle({
    *   root: 'resources/js/emails',
    *   content: ['./**\/*.vue'],
    * })
    */
   root?: string;
+  /** Options passed to `unplugin-vue-markdown` for Markdown template support. */
   markdown?: unplugin_vue_markdown_types0.Options;
+  /**
+   * Glob patterns for email template files to process.
+   *
+   * Resolved relative to `root`.
+   *
+   * @default ['emails/**\/*.{vue,md}']
+   */
   content?: string[];
+  /** Output configuration for built email templates. */
   output?: {
+    /**
+     * Directory to write compiled HTML files to.
+     *
+     * @default 'dist'
+     */
     path?: string;
+    /**
+     * File extension for compiled templates.
+     *
+     * @default 'html'
+     *
+     * @example
+     * output: {
+     *   extension: 'blade.php',
+     * }
+     */
     extension?: string;
   };
+  /** Static file copying configuration. */
   static?: {
+    /**
+     * Glob patterns for static files to copy to the output directory.
+     *
+     * @default ['public/**\/*.*']
+     */
     source?: string[];
+    /**
+     * Subdirectory in the output folder where static files are placed.
+     *
+     * @default 'public'
+     */
     destination?: string;
   };
+  /** Component auto-import configuration. */
   components?: {
+    /**
+     * Additional directories to scan for auto-imported Vue components.
+     *
+     * Resolved relative to `cwd` (not `root`), so paths outside the
+     * email root directory work as expected.
+     *
+     * @example
+     * components: {
+     *   source: ['resources/js/components/email'],
+     * }
+     */
     source?: string | string[];
   };
+  /** Dev server configuration. */
   server?: {
+    /**
+     * Port for the dev server.
+     *
+     * @default 3000
+     */
     port?: number;
+    /**
+     * Additional file paths to watch for changes.
+     *
+     * @default []
+     *
+     * @example
+     * server: {
+     *   watch: ['./tailwind.config.ts'],
+     * }
+     */
     watch?: string[];
   };
+  /** Tailwind CSS and email CSS optimization settings. */
   css?: CssConfig;
+  /**
+   * Generate a plaintext version of the email.
+   *
+   * Set to `true` to enable, or pass a string path or options object.
+   *
+   * @default false
+   */
   plaintext?: boolean | string | Record<string, unknown>;
+  /** PostCSS processing options. */
   postcss?: PostcssConfig;
+  /**
+   * Enable the transformer pipeline (CSS inlining, purging, shorthand, etc).
+   *
+   * @default true
+   */
   useTransformers?: boolean;
+  /**
+   * Replace strings in the final HTML output.
+   *
+   * @example
+   * replaceStrings: {
+   *   '{{ year }}': new Date().getFullYear().toString(),
+   * }
+   */
   replaceStrings?: Record<string, string>;
+  /** URL transformation settings (base URL, query string appending). */
   url?: UrlConfig;
+  /** HTML post-processing settings (attributes, formatting, minification). */
   html?: HtmlConfig;
+  /** Called before any templates are processed. */
   beforeCreate?: (params: {
     config: MaizzleConfig;
   }) => void | Promise<void>;
+  /** Called before each template is rendered. Return a string to replace the template source. */
   beforeRender?: (params: {
     config: MaizzleConfig;
     template: string;
   }) => string | void | Promise<string | void>;
+  /** Called after each template is rendered but before transformers run. Return a string to replace the output HTML. */
   afterRender?: (params: {
     config: MaizzleConfig;
     template: string;
     html: string;
   }) => string | void | Promise<string | void>;
+  /** Called after transformers have run on each template. Return a string to replace the output HTML. */
   afterTransform?: (params: {
     config: MaizzleConfig;
     template: string;
     html: string;
   }) => string | void | Promise<string | void>;
+  /** Called after all templates have been built. */
   afterBuild?: (params: {
     files: string[];
     config: MaizzleConfig;

package/dist/types/config.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.mts","names":[],"sources":["../../src/types/config.ts"],"mappings":";;;;;UAAiB,eAAA;EACf,IAAA;EACA,UAAA;EACA,MAAA;EACA,EAAA,GAAK,MAAA;AAAA;AAAA,KAGK,QAAA,GAAW,MAAA;EACrB,QAAA,GAAW,eAAA;AAAA;AAAA,UAGI,SAAA;EACf,KAAA,GAAQ,QAAA;EACR,IAAA;IACE,GAAA;IACA,IAAA,cAAkB,MAAA,SAAe,MAAA;IACjC,UAAA,GAAa,MAAA;IACb,QAAA;IACA,SAAA;EAAA;AAAA;AAAA,UAIa,SAAA;EACf,IAAA;EACA,KAAA,aAAkB,MAAA;EAClB,MAAA;IACE,gBAAA;IACA,eAAA;IACA,sBAAA;IACA,oBAAA;IACA,QAAA;IACA,gBAAA,GAAmB,MAAA;IACnB,oBAAA;IACA,qBAAA;IACA,aAAA;IACA,cAAA;IACA,kBAAA;IACA,UAAA,GAAa,MAAA;MAAiB,KAAA;MAAe,GAAA;IAAA;IAC7C,SAAA;IAAA,CACC,GAAA;EAAA;EAEH,KAAA;IACE,IAAA,wCAA4C,CAAA,UAAW,CAAA;EAAA;EAEzD,cAAA;EACA,WAAA;EACA,YAAA;EACA,IAAA,aAAiB,MAAA;EACjB,MAAA;EACA,SAAA;IAAwB,IAAA;EAAA;EACxB,kBAAA,GAAqB,MAAA,SAHE,WAAA;EAIvB,OAAA;AAAA;AAAA,UAGe,gBAAA;EACf,GAAA,WAAc,MAAA,SAAe,MAAA;EAC7B,MAAA,GAAS,KAAA;IAAiB,IAAA;IAAc,KAAA,YAAiB,MAAA;EAAA;AAAA;AAAA,KAG/C,cAAA,aAA2B,MAAA;AAAA,UAEtB,aAAA;EAjCb;EAmCF,eAAA;EAjCE;EAmCF,aAAA;EAAA,CACC,GAAA;AAAA;AAAA,UAGc,UAAA;EACf,UAAA,GAAa,gBAAA;EACb,cAAA,GAAiB,cAAA;EACjB,MAAA,aAD+B,KAAA,CACI,aAAA;EACnC,MAAA,aAAmB,MAAA;AAAA;AAAA,UAGJ,aAAA;EAvCgC;;;;;;;;;;;;;;;;EAwD/C,IAAA;EACA,QAAA,GAlB4B,4BAAA,CAkBqB,OAAA;EACjD,OAAA;EACA,MAAA;IACE,IAAA;IACA,SAAA;EAAA;EAEF,MAAA;IACE,MAAA;IACA,WAAA;EAAA;EAEF,UAAA;IACE,MAAA;EAAA;EAEF,MAAA;IACE,IAAA;IACA,KAAA;EAAA;EAEF,GAAA,GAAM,SAAA;EACN,SAAA,sBAA+B,MAAA;EAC/B,OAAA,GAAU,aAAA;EACV,eAAA;EACA,cAAA,GAAiB,MAAA;EACjB,GAAA,GAAM,SAAA;EACN,IAAA,GAAO,UAAA;EAGP,YAAA,IAAgB,MAAA;IAAU,MAAA,EAAQ,aAAA;EAAA,aAA2B,OAAA;EAC7D,YAAA,IAAgB,MAAA;IAAU,MAAA,EAAQ,aAAA;IAAe,QAAA;EAAA,sBAAuC,OAAA;EACxF,WAAA,IAAe,MAAA;IAAU,MAAA,EAAQ,aAAA;IAAe,QAAA;IAAkB,IAAA;EAAA,sBAAmC,OAAA;EACrG,cAAA,IAAkB,MAAA;IAAU,MAAA,EAAQ,aAAA;IAAe,QAAA;IAAkB,IAAA;EAAA,sBAAmC,OAAA;EACxG,UAAA,IAAc,MAAA;IAAU,KAAA;IAAiB,MAAA,EAAQ,aAAA;EAAA,aAA2B,OAAA;EAAA,CAG3E,GAAA;AAAA"}
+{"version":3,"file":"config.d.mts","names":[],"sources":["../../src/types/config.ts"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maizzle/framework",
-  "version": "6.0.0-rc.3",
+  "version": "6.0.0-rc.4",
   "description": "Maizzle is a framework that helps you quickly build HTML emails with Tailwind CSS.",
   "license": "MIT",
   "type": "module",