@nxgt/mail-ui 0.1.0

package/dist/packaged.d.ts

@@ -0,0 +1,27 @@
+import type { MaizzleConfig } from '@maizzle/framework';
+/** A Vite plugin, as Maizzle's `vite.plugins` takes one. */
+type VitePlugins = NonNullable<NonNullable<MaizzleConfig['vite']>['plugins']>;
+/** A folder of components, and the prefix Maizzle gives their names, if any. */
+export interface ComponentsFolder {
+    readonly path: string;
+    readonly prefix?: string;
+}
+/**
+ * The first `.vue` file at the top of `folders`, in order, that Maizzle names
+ * `tag` — `button.vue` under the prefix `Nx`, or a project's `nx-button.vue`
+ * or `NxButton.vue`, for `<NxButton>`. Named, not guessed: `2fa.vue` under
+ * `Nx` is `<Nx2fa>`, which no case conversion of the tag gives back. A missing
+ * folder is skipped.
+ */
+export declare function fileForTag(folders: readonly ComponentsFolder[], tag: string): string | undefined;
+/**
+ * Maizzle resolves the tags of a template (`<NxButton>`, `<Container>`) with
+ * unplugin-vue-components, which skips every file under `node_modules` — so a
+ * component or a template installed from npm would render empty, and the
+ * build would pass. These plugins resolve the tags of those files the way
+ * Maizzle would: the project's `components/` first, then ours, then Maizzle's
+ * built-ins.
+ */
+export declare function packagedComponents(ours: ComponentsFolder): VitePlugins;
+export {};
+//# sourceMappingURL=packaged.d.ts.map

package/dist/packaged.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"packaged.d.ts","sourceRoot":"","sources":["../src/packaged.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGxD,4DAA4D;AAC5D,KAAK,WAAW,GAAG,WAAW,CAAC,WAAW,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;AAsC9E,gFAAgF;AAChF,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB;AAcD;;;;;;GAMG;AACH,wBAAgB,UAAU,CACzB,OAAO,EAAE,SAAS,gBAAgB,EAAE,EACpC,GAAG,EAAE,MAAM,GACT,MAAM,GAAG,SAAS,CAYpB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,WAAW,CA0BtE"}

package/dist/plugin.d.ts

@@ -0,0 +1,55 @@
+import { type MailPlugin } from '@nxgt/mail-config';
+/** Who sends the e-mail: the layout's header and footer. */
+export interface Brand {
+    /** The name the header shows without a logo, and the footer always. */
+    readonly name: string;
+    /** Where the header and the footer link to, as `https://acme.example`. */
+    readonly url?: string;
+    /** The header's image, by absolute URL: a mail client loads nothing relative. */
+    readonly logo?: {
+        readonly src: string;
+        /** In pixels. Default 120. */
+        readonly width?: number;
+        /** Default the brand's name. */
+        readonly alt?: string;
+    };
+}
+export interface UiOptions {
+    readonly brand: Brand;
+    /**
+     * Tokens of `theme.css` to override, named without their `--`:
+     * `{ 'color-primary': '#0f766e', 'radius-lg': '4px' }`. The tints of a
+     * colour follow it.
+     */
+    readonly theme?: Readonly<Record<string, string>>;
+}
+/** What `NxLayout` injects: the brand and the theme's CSS. */
+export interface UiContext {
+    readonly brand: Brand;
+    readonly css: string;
+}
+/** The `provide` key the components read the {@link UiContext} from. */
+export declare const UI_CONTEXT = "nxgt:mail-ui";
+/**
+ * Where the template types go, under the project: `.maizzle/*.d.ts` is in the
+ * starter's `tsconfig.json`, and `maizzle.config.ts` — which imports this
+ * package — is not, so an editor would not know `brand` without it.
+ */
+export declare const TYPES_FILE = ".maizzle/nxgt-mail-ui.d.ts";
+/** The components, beside `src/` and `dist/` in the package. */
+export declare const COMPONENTS_DIR: string;
+/**
+ * The components of `@nxgt/mail-ui`, for `defineMailConfig`:
+ *
+ * ```ts
+ * defineMailConfig({
+ *   plugins: [ui({ brand: { name: 'Acme' } }), i18n({ locales: ['en', 'fr'] })],
+ * });
+ * ```
+ *
+ * It registers `NxLayout`, `NxButton`, … — a project's own
+ * `components/nx-button.vue` replaces ours — gives every template `brand`,
+ * and themes the layout with `theme.css` and the `theme` overrides.
+ */
+export declare function ui(options: UiOptions): MailPlugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAIA,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAItE,4DAA4D;AAC5D,MAAM,WAAW,KAAK;IACrB,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,QAAQ,CAAC,IAAI,CAAC,EAAE;QACf,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,8BAA8B;QAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QACxB,gCAAgC;QAChC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;CACF;AAED,MAAM,WAAW,SAAS;IACzB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAClD;AAED,8DAA8D;AAC9D,MAAM,WAAW,SAAS;IACzB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACrB;AAED,wEAAwE;AACxE,eAAO,MAAM,UAAU,iBAAiB,CAAC;AAEzC;;;;GAIG;AACH,eAAO,MAAM,UAAU,+BAA+B,CAAC;AAiBvD,gEAAgE;AAChE,eAAO,MAAM,cAAc,QAE1B,CAAC;AA8CF;;;;;;;;;;;;GAYG;AACH,wBAAgB,EAAE,CAAC,OAAO,EAAE,SAAS,GAAG,UAAU,CAiCjD"}

package/dist/theme.d.ts

@@ -0,0 +1,11 @@
+/** `theme.css`, beside `src/` and `dist/` in the package. */
+export declare const THEME_FILE: string;
+/** The tokens `css` declares, without their `--`: `color-primary`, … */
+export declare function declaredTokens(css: string): ReadonlySet<string>;
+/**
+ * The CSS a layout puts under `@import "@maizzle/tailwindcss"`: the theme,
+ * then an `@theme` block of the project's overrides, which wins. A token the
+ * theme does not declare, or a value that is not one, **throws**.
+ */
+export declare function themeCss(theme: Readonly<Record<string, string>>): string;
+//# sourceMappingURL=theme.d.ts.map

package/dist/theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../src/theme.ts"],"names":[],"mappings":"AAGA,6DAA6D;AAC7D,eAAO,MAAM,UAAU,QAEtB,CAAC;AAWF,wEAAwE;AACxE,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,CAO/D;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,MAAM,CAoBxE"}

package/dist/vue.d.ts

@@ -0,0 +1,9 @@
+import type { Brand } from './plugin';
+/** What a template gets from the ui plugin: `{{ brand.name }}`. */
+declare module 'vue' {
+    interface ComponentCustomProperties {
+        /** The `brand` given to `ui()`. */
+        readonly brand: Brand;
+    }
+}
+//# sourceMappingURL=vue.d.ts.map

package/dist/vue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vue.d.ts","sourceRoot":"","sources":["../src/vue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAEtC,mEAAmE;AACnE,OAAO,QAAQ,KAAK,CAAC;IACpB,UAAU,yBAAyB;QAClC,mCAAmC;QACnC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;KACtB;CACD"}

package/docs/README.md

@@ -0,0 +1,15 @@
+# @nxgt/mail-ui — documentation
+
+The [README](../README.md) shows that it works. These pages show how, one area
+at a time, with an example for every rule. The words they use (project,
+template, component, plugin, placeholder, catalogue) are defined once, in the
+[vocabulary](https://github.com/softistx/nxgt-mail/blob/develop/docs/vocabulary.md).
+
+| Page | Read it when |
+| --- | --- |
+| [The plugin](guide/plugin.md) | You are adding `ui({ brand, theme })` to `maizzle.config.ts`: the brand, `brand` in templates and how the editor and `vue-tsc` learn its type, replacing one of the components with your own, how the tags of installed components and a package's templates are resolved, writing your own layout on `UI_CONTEXT`, and every `TypeError` it throws |
+| [Components](guide/components.md) | You are writing `emails/*.vue` with the `Nx*` components: each one's props, defaults and slots, the material-vue component it mirrors, icons, spacing, and a complete template |
+| [The theme](guide/theme.md) | You want your colours or radii: every token of `theme.css`, the tints that stand for material-vue's translucent colours, what an override changes, and why there is no dark mode |
+| [Shared messages](guide/messages.md) | You translate with `@nxgt/mail-i18n`: the `common` messages `uiCatalogues` brings, overriding one, and a locale other than `en` and `fr` |
+| [Troubleshooting](troubleshooting.md) | You have an error message and want its cause and its fix |
+| [Roadmap](roadmap.md) | You want to know what is coming, what shipped, and what is deliberately not planned |