@treygrr/vjml 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VJML contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+# vjml
+
+[![CI](https://github.com/treygrr/vjml/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/treygrr/vjml/actions/workflows/ci.yml)
+
+VJML is a Vue-only MJML-style email component library for standard Vue apps. It provides a plugin for global component registration, typed component exports, and browser-side render helpers for turning Vue email components into email-safe HTML.
+
+It includes:
+
+- the copied MJML-style runtime components
+- plugin-based global registration for Vue apps
+- metadata and typed component prop exports
+- browser-side render helpers for converting a Vue email component into email-safe HTML
+
+## Repository layout
+
+- `src` contains the publishable component library and is the only code compiled into `dist`.
+- `test` contains the component parity suites, shared test utilities, and end-to-end sample email fixtures.
+- `website` contains the Nuxt documentation site and is managed as a workspace from the repository root.
+- `playground` contains the local development app used for previewing and testing the library.
+- The playground imports the library through the local `vjml` source alias, while the published npm package name is `@treygrr/vjml`.
+
+Run `npm install` from the repository root. The root package manages both the publishable library and the `website` workspace.
+
+## Scripts
+
+- `npm run dev` starts the local playground.
+- `npm run dev:playground` also starts the local playground explicitly.
+- `npm run dev:website` starts the Nuxt docs site from the root workspace.
+- `npm run docs:dev` is an alias for `npm run dev:website`.
+- `npm run docs:build` builds the docs site from the root workspace.
+- `npm run docs:generate` generates the static docs output from the root workspace.
+- `npm run docs:preview` previews the built docs site locally.
+- `npm run build` builds both the library and the website from the repository root.
+- `npm run build:lib` runs the library build directly.
+- `npm run build:website` runs only the Nuxt docs build.
+- `npm run test` runs the renderer parity test suite.
+- `npm run test:accordion` runs the first component parity suite against the accordion fixtures.
+- `npm run typecheck` validates the playground and library source.
+- `npm run typecheck:website` runs the Nuxt workspace typecheck from the repository root.
+
+## Component parity tests
+
+The parity harness lives under `test/components`.
+
+- Each component gets its own folder.
+- Each variant is represented by a `.vue` fixture and a matching `.mjml` fixture.
+- The component test renders both sides, normalizes the generated HTML, and compares the results.
+
+## Contributing
+
+Contributions go through GitHub pull requests. Before opening a pull request, make sure the change is covered by tests, run the relevant verification commands, and update docs or generated metadata when the public surface changes.
+
+- Changes to existing behavior need updated coverage.
+- New features and new components need new coverage.
+- Runtime and component changes should update parity fixtures under `test/components` or `test/samples`.
+- Library changes should be verified with `npm run typecheck`, `npm run test`, and `npm run build`.
+- Docs changes live under `website/` and should be verified with `cd website && npm run build`.
+
+See `CONTRIBUTING.md` for the full contributor workflow and GitHub merge policy.
+
+## License
+
+MIT. See `LICENSE`.
+
+## Install the plugin
+
+```ts
+import { createApp } from 'vue'
+import App from './App.vue'
+import VjmlPlugin from '@treygrr/vjml'
+
+createApp(App)
+	.use(VjmlPlugin, {
+		includeUnprefixedAliases: true,
+		prefix: 'VJ',
+		render: {
+			validation: 'warn',
+		},
+	})
+	.mount('#app')
+```
+
+Set `includeUnprefixedAliases: true` when you want both `VJText`-style prefixed names and bare aliases such as `Text` or `Mjml` available from the plugin.
+
+You can also import components directly:
+
+```ts
+import { Body, Button, Column, Mjml, Section, Text } from '@treygrr/vjml'
+```
+
+## Preview in the browser
+
+The main `@treygrr/vjml` entry now includes a browser-side renderer and an iframe preview component.
+
+```vue
+<script setup lang="ts">
+import WelcomeEmail from './WelcomeEmail.vue'
+import { VjmlRenderFrame } from '@treygrr/vjml'
+</script>
+
+<template>
+	<VjmlRenderFrame :component="WelcomeEmail" />
+</template>
+```
+
+If you want the generated HTML directly in a browser runtime, use `createVjmlRenderer()` from `@treygrr/vjml`.
+
+```ts
+import WelcomeEmail from './WelcomeEmail.vue'
+import { createVjmlRenderer } from '@treygrr/vjml'
+
+const { renderToHtml } = createVjmlRenderer()
+const { html, issues } = await renderToHtml(WelcomeEmail)
+```
+
+## Render an email component
+
+```ts
+import WelcomeEmail from './WelcomeEmail.vue'
+import { createVjmlRenderer } from '@treygrr/vjml'
+
+const { renderToHtml } = createVjmlRenderer({
+	render: {
+		validation: 'strict',
+	},
+})
+
+const { html, issues } = await renderToHtml(WelcomeEmail, {
+	props: {
+		firstName: 'Ada',
+	},
+})
+```
+
+Inside a setup context, `useVjmlRenderer()` is also available from `@treygrr/vjml` and merges the injected plugin config automatically.
+
+## Important entries
+
+- `src/index.ts` exports the plugin, components, metadata, and shared utilities.
+- `src/runtime/components` contains the copied VJML component implementations.
+- `src/runtime/internal` contains the browser render pipeline and document/context helpers.
+- `src/metadata.ts` and `src/metadata.generated.ts` provide component metadata used by validation and serialization.
+- `playground/App.vue` is the development catalog that imports and exercises the library.

package/dist/types/components/VjmlRenderFrame.vue.d.ts

@@ -0,0 +1,69 @@
+import { type Component, type PropType } from 'vue';
+import type { VjmlRuntimeConfigInput, VjmlValidationIssue } from '../vjml';
+declare function renderFrame(): Promise<void>;
+declare const __VLS_export: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    component: {
+        required: true;
+        type: PropType<Component>;
+    };
+    height: {
+        default: string;
+        type: (NumberConstructor | StringConstructor)[];
+    };
+    renderProps: {
+        default: () => {};
+        type: PropType<Record<string, unknown>>;
+    };
+    runtime: {
+        default: () => {};
+        type: PropType<VjmlRuntimeConfigInput>;
+    };
+    title: {
+        default: string;
+        type: StringConstructor;
+    };
+}>, {
+    html: import("vue").Ref<string, string>;
+    issues: import("vue").Ref<{
+        code: string;
+        message: string;
+        severity: import("..").VjmlValidationSeverity;
+        path?: string | undefined;
+        tagName?: string | undefined;
+    }[], VjmlValidationIssue[] | {
+        code: string;
+        message: string;
+        severity: import("..").VjmlValidationSeverity;
+        path?: string | undefined;
+        tagName?: string | undefined;
+    }[]>;
+    renderFrame: typeof renderFrame;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    component: {
+        required: true;
+        type: PropType<Component>;
+    };
+    height: {
+        default: string;
+        type: (NumberConstructor | StringConstructor)[];
+    };
+    renderProps: {
+        default: () => {};
+        type: PropType<Record<string, unknown>>;
+    };
+    runtime: {
+        default: () => {};
+        type: PropType<VjmlRuntimeConfigInput>;
+    };
+    title: {
+        default: string;
+        type: StringConstructor;
+    };
+}>> & Readonly<{}>, {
+    title: string;
+    height: string | number;
+    renderProps: Record<string, unknown>;
+    runtime: VjmlRuntimeConfigInput;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/types/composables/useVjml.d.ts

@@ -0,0 +1 @@
+export { useVjml } from '../runtime/composables/useVjml';

package/dist/types/index.d.ts

@@ -0,0 +1,15 @@
+export { default, VjmlPlugin, registerVjmlComponents, resolveVjmlPluginConfig } from './plugin';
+export { default as VjmlRenderFrame } from './components/VjmlRenderFrame.vue';
+export { DEFAULT_VJML_FONTS, DEFAULT_VJML_PREFIX, DEFAULT_VJML_RENDER_OPTIONS, VJML_COMPONENT_NAME_EXAMPLES, mergeVjmlRuntimeConfig, resolveVjmlRenderOptions, resolveVjmlRuntimeConfig, toVjmlComponentBaseName, toVjmlComponentName, } from './vjml';
+export { VJML_COMPONENT_METADATA, VJML_COMPONENT_METADATA_BY_TAG_NAME, VJML_MANUAL_COMPONENT_TAG_NAMES, getVjmlComponentMetadata, } from './metadata';
+export { VJML_RUNTIME_COMPONENTS } from './runtime/manifest.generated';
+export { useVjml } from './runtime/composables/useVjml';
+export { useVjmlComponentName } from './runtime/composables/useVjmlComponentName';
+export { createVjmlRenderer, useVjmlRenderer } from './runtime/client/useVjmlRenderer';
+export { renderVjmlToDebugTree } from './runtime/client/renderVjmlToDebugTree';
+export { renderVjmlToHtml } from './runtime/client/renderVjmlToHtml';
+export * from './runtime/components.generated';
+export * from './runtime/component-types.generated';
+export type { RenderVjmlToHtmlOptions, VjmlDebugDocumentState, VjmlDebugNode, VjmlDebugRenderResult, VjmlFontMap, VjmlRenderMode, VjmlRenderOptions, VjmlRenderResult, VjmlRuntimeConfig, VjmlRuntimeConfigInput, VjmlValidationIssue, VjmlValidationMode, VjmlValidationSeverity, } from './vjml';
+export type { VjmlComponentMetadata, VjmlComponentMetadataSource, VjmlComponentSerializationMetadata, VjmlComponentSlotKind, } from './metadata';
+export type { VjmlPluginOptions } from './plugin';

package/dist/types/metadata.d.ts

@@ -0,0 +1,24 @@
+export type VjmlComponentMetadataSource = 'manual' | 'preset-core';
+export type VjmlComponentSlotKind = 'html' | 'mjml' | 'none' | 'text';
+export interface VjmlComponentSerializationMetadata {
+    allowsArbitraryAttributes: boolean;
+    preservesRawContent: boolean;
+    slotKind: VjmlComponentSlotKind;
+}
+export interface VjmlComponentMetadata {
+    tagName: string;
+    componentBaseName: string;
+    source: VjmlComponentMetadataSource;
+    allowedAttributes: Record<string, string>;
+    defaultAttributes: Record<string, string>;
+    allowedChildTagNames: string[];
+    allowedParentTagNames: string[];
+    supportsAnyChildTag: boolean;
+    endingTag: boolean;
+    rawElement: boolean;
+    serialization: VjmlComponentSerializationMetadata;
+}
+export declare const VJML_COMPONENT_METADATA: readonly VjmlComponentMetadata[];
+export declare const VJML_COMPONENT_METADATA_BY_TAG_NAME: Readonly<Record<string, VjmlComponentMetadata>>;
+export declare const VJML_MANUAL_COMPONENT_TAG_NAMES: readonly string[];
+export declare function getVjmlComponentMetadata(tagName: string): VjmlComponentMetadata | null;