@nxgt/mail-ui 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steve Tsala
+
+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,311 @@
+# @nxgt/mail-ui
+
+E-mail components for a normal [Maizzle](https://maizzle.com) 6 project, in
+the style of `@nxgt/material-vue`: `<NxLayout>`, `<NxButton>`, `<NxCard>`,
+`<NxAlert>`, `<NxTable>`, `<NxTimeline>`, `<NxStatCard>`… with its variants,
+colours and tokens, rendered with tables and
+inlined styles. One plugin gives every template the components, your brand
+and the theme; a second export gives `@nxgt/mail-i18n` the messages they share.
+
+```ts
+// maizzle.config.ts
+import { defineMailConfig } from '@nxgt/mail-config';
+import { i18n } from '@nxgt/mail-i18n';
+import { ui, uiCatalogues } from '@nxgt/mail-ui';
+
+export default defineMailConfig({
+	plugins: [
+		ui({ brand: { name: 'Acme', url: 'https://acme.example' } }),
+		i18n({ locales: ['en', 'fr'], catalogues: [uiCatalogues] }),
+	],
+});
+```
+
+Your project stays a Maizzle project: `emails/`, `components/`, `public/`,
+`maizzle serve`, `maizzle build`. Maizzle's own components (`<Button>`,
+`<Spacer>`) stay available; ours carry the `Nx` prefix and never shadow them.
+
+<img src="https://raw.githubusercontent.com/softistx/nxgt-mail/refs/tags/@nxgt/mail-ui@0.1.0/packages/mail-ui/previews/components-en.png" width="420" alt="An e-mail using the first Nx components: layout, typography, code, buttons, separator, card with badge, summary data and status, alert, banner, link">
+
+The components from `NxLayout` to `NxCode` in one e-mail, with the brand
+`Acme` and the default theme —
+[in French](https://raw.githubusercontent.com/softistx/nxgt-mail/refs/tags/@nxgt/mail-ui@0.1.0/packages/mail-ui/previews/components-fr.png).
+
+> **0.x.** A minor version may still change the surface; the changelog says how.
+
+## Install
+
+```sh
+bun add @nxgt/mail-ui @nxgt/mail-config @maizzle/framework @maizzle/tailwindcss vue
+```
+
+Peers, all required:
+
+- `@maizzle/framework` (`^6.1.7`) — Maizzle itself.
+- `@nxgt/mail-config` — `ui()` is a plugin for its `defineMailConfig`. It
+  needs `@maizzle/tailwindcss` (`^1.5.6`) **as a direct dependency of your
+  project**; see [Setup](#setup).
+- `vue` (`^3.5`) — the components are Vue single-file components, and the
+  package types `brand` on Vue's template properties.
+- `typescript` (6). Bundler resolution (`"moduleResolution": "bundler"`) is
+  what is supported and tested; `nodenext` is out of contract.
+
+`@nxgt/mail-i18n` is not a peer: add it (`bun add @nxgt/mail-i18n`) to
+translate your e-mails and to use `uiCatalogues`.
+
+One dependency comes with the package: `unplugin-vue-components`, which
+Maizzle already uses. Maizzle resolves no tag in a `.vue` file under
+`node_modules`, so `ui()` resolves them itself for the files a package ships —
+ours, and a package's templates such as `@nxgt/mail-presets`'. See
+[Components from a package](docs/guide/plugin.md#components-from-a-package).
+
+## Setup
+
+```css
+/* what <NxLayout> writes in its <style> — you do not write it */
+@import "@maizzle/tailwindcss";
+```
+
+That import is resolved from your project. Under an isolated install (Bun
+workspaces, pnpm) it fails **silently** unless `@maizzle/tailwindcss` is in
+your own `package.json`, as the `bun add` above makes it: the build succeeds,
+and no style is generated.
+
+```jsonc
+// tsconfig.json — the official starter's include; keep .maizzle/*.d.ts in it
+{ "include": ["**/*.vue", ".maizzle/*.d.ts"] }
+```
+
+```jsonc
+// package.json — the starter's postinstall
+{ "scripts": { "postinstall": "maizzle prepare" } }
+```
+
+Each time the config loads (`maizzle prepare`, `serve`, `build`), `ui()`
+writes `.maizzle/nxgt-mail-ui.d.ts`, which loads the type of `brand` for the
+templates. The starter's `tsconfig.json` does not include
+`maizzle.config.ts`, so this file is how the editor learns it. `.maizzle/` is
+in the starter's `.gitignore`. See
+[Editor and type checking](#editor-and-type-checking).
+
+## Exports
+
+| Export | What it is |
+| --- | --- |
+| `ui(options)` | The plugin, for `defineMailConfig({ plugins })`: the `Nx*` components, `brand` in every template, the theme |
+| `uiCatalogues` | The shared messages in `en` and `fr`, for `i18n({ catalogues: [uiCatalogues] })` |
+| `UI_CONTEXT` | `'nxgt:mail-ui'`, the Vue `provide` key a component reads the brand and the theme's CSS from |
+| `COMPONENTS_DIR` | The absolute path of the package's `components/` folder |
+| `THEME_FILE` | The absolute path of the package's `theme.css` |
+| `Brand`, `UiOptions`, `UiContext` | The brand, the plugin's options, and what `UI_CONTEXT` provides |
+
+| Subpath | What it is |
+| --- | --- |
+| `@nxgt/mail-ui` | The exports above |
+| `@nxgt/mail-ui/theme.css` | The theme: `@theme` tokens for Tailwind 4 |
+
+## Usage
+
+### A template
+
+```vue
+<!-- emails/verify-email.vue -->
+<template>
+  <NxLayout :preheader="t('verifyEmail.title')">
+    <NxTypography variant="headline-small">{{ t('verifyEmail.title') }}</NxTypography>
+    <NxTypography>{{ t('common.greeting', { name: placeholder('name') }) }}</NxTypography>
+    <NxButton :href="placeholder('link')">{{ t('verifyEmail.action') }}</NxButton>
+    <Spacer height="24px" />
+    <NxAlert variant="warning" title="The link expires in 15 minutes." />
+    <NxTypography variant="caption">{{ t('common.footer.ignore') }}</NxTypography>
+  </NxLayout>
+</template>
+```
+
+`<NxLayout>` is the page: the brand's logo or name at the top, the content on
+a card, and a footer that says why the e-mail came (`common.footer.why`) and
+links the brand. Every other component goes inside it. `t` and `placeholder`
+come from `@nxgt/mail-i18n`; without it, write the text directly. See
+[Components](docs/guide/components.md) for every component, its props and
+its slots.
+
+### The plugin — `ui({ brand, theme })`
+
+```ts
+import { ui } from '@nxgt/mail-ui';
+
+ui({
+	brand: {
+		name: 'Acme',
+		url: 'https://acme.example',
+		logo: { src: 'https://acme.example/logo.png', width: 96, alt: 'Acme' },
+	},
+	theme: { 'color-primary': '#0f766e', 'radius-xl': '8px' },
+});
+```
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `brand.name` | `string` | — (required) | Shown in the header without a logo, and in the footer always |
+| `brand.url` | `string` | none | An absolute `http(s)` URL the header and the footer link to |
+| `brand.logo` | `{ src, width?, alt? }` | none | The header's image: `src` an absolute `http(s)` URL, `width` in pixels (120), `alt` (the brand's name) |
+| `theme` | `Record<string, string>` | `{}` | Tokens of `theme.css` to override, named without their `--` |
+
+A wrong option is a bare `TypeError` when the config loads:
+`ui: brand.logo.src must be an absolute http(s) URL — a mail client loads
+nothing relative`. Every template also gets `brand`: `{{ brand.name }}`. See
+[The plugin](docs/guide/plugin.md).
+
+### The theme
+
+`theme.css` holds material-vue's light tokens. Maizzle turns each colour into
+a hex value in the built HTML, and material-vue's translucent `bg-primary/15`
+is `bg-primary-15` here, a plain colour, because a mail client drops an
+alpha. Override a colour, and its tints follow:
+
+```ts
+ui({ brand: { name: 'Acme' }, theme: { 'color-primary': '#0f766e' } });
+// <NxButton> is #0f766e; <NxButton variant="tonal"> is #dbeae9, 15% of it over white
+```
+
+See [The theme](docs/guide/theme.md) for every token.
+
+### The shared messages — `uiCatalogues`
+
+```ts
+i18n({ locales: ['en', 'fr'], catalogues: [uiCatalogues] });
+```
+
+`common.greeting` (`Hello {name},`), `common.footer.why`,
+`common.footer.ignore`, `common.avatarGroup.more`, `common.timeline.empty`,
+`common.metrics.ofTarget`, `common.metrics.thisPeriod`,
+`common.metrics.lastPeriod` and `common.seeAlso`, in `en` and `fr`. Your `locales/<locale>.json`
+overrides any of them, key by key:
+
+```json
+// locales/en.json
+{ "common": { "greeting": "Hi {name}," } }
+```
+
+See [Shared messages](docs/guide/messages.md).
+
+### Editor and type checking
+
+With the [Setup](#setup) above, Vue's language tools (the **Vue - Official**
+extension in the editor, `vue-tsc` in CI) know `brand` in every template, and
+Maizzle's `.maizzle/prefixed-components.d.ts` gives them the `Nx*` components
+and their props:
+
+```vue
+<!-- emails/welcome.vue -->
+<template>
+  <NxTypography>Welcome to {{ brand.nam }}</NxTypography>
+  <!-- Property 'nam' does not exist on type 'Brand'. Did you mean 'name'? -->
+</template>
+```
+
+```sh
+bun add -d vue-tsc
+bunx vue-tsc --noEmit   # after maizzle prepare, as in CI
+```
+
+`t`, `locale` and `placeholder` are typed by `@nxgt/mail-i18n`, which writes
+its own file beside this one. See
+[`brand` in templates](docs/guide/plugin.md#brand-in-templates), and
+[`Property 'brand' does not exist`](docs/troubleshooting.md#the-editor-says-property-brand-does-not-exist-in-a-template)
+if the editor does not know `brand`.
+
+### Replacing a component
+
+```vue
+<!-- components/nx-badge.vue — replaces the package's <NxBadge> in every template -->
+<template>
+  <span class="rounded-sm bg-primary px-2 text-xs text-primary-foreground"><slot /></span>
+</template>
+```
+
+`components/NxBadge.vue` works as well: Maizzle names a component the same
+from either case.
+
+A file in your `components/` named as one of our tags wins over ours — in
+your templates, in ours, and in a package's. A copy of ours must be renamed:
+ours are named without the prefix `ui()` adds, so a copied `badge.vue` is
+`<Badge>` and replaces nothing until it is `nx-badge.vue`. See
+[The plugin](docs/guide/plugin.md#replacing-a-component) and
+[A project's own component does not replace the package's](docs/troubleshooting.md#a-projects-own-component-does-not-replace-the-packages).
+
+## Traps
+
+**List `ui()` in `plugins`.** A component used without it fails the build:
+`NxLayout: ui() is not in the plugins of defineMailConfig`.
+
+**With `@nxgt/mail-i18n`, give it the shared messages.** `<NxLayout>` calls
+`t('common.footer.why')` once the i18n plugin is listed, and the build fails
+with `calls t('common.footer.why'), which is not a key of the catalogues`
+unless `catalogues: [uiCatalogues]` is passed, or your catalogues hold the
+key.
+
+**Another locale writes the `common` keys itself.** `uiCatalogues` has `en`
+and `fr` only: a project in `de` adds its nine keys — `common.greeting`,
+`common.footer.why`, `common.footer.ignore`, `common.avatarGroup.more`,
+`common.timeline.empty`, `common.metrics.ofTarget`,
+`common.metrics.thisPeriod`, `common.metrics.lastPeriod` and
+`common.seeAlso` — to `locales/de.json`.
+
+**Icons are slots.** An e-mail has no icon font: pass an `<img>` with an
+absolute URL, or a character, to `#icon`.
+
+**Light only.** The layout declares `<meta name="color-scheme" content="light">`;
+there is no dark theme.
+
+**Use Maizzle's `<Spacer>` for vertical space**: `<Spacer height="24px" />`.
+
+**Never branch on a placeholder** in a component or a template:
+`v-if="link.startsWith('https:')"` is decided on the string `{{ link }}`.
+
+## Type safety, counted
+
+**8 plausible mistakes, 8 refused** at compile time, each measured by a
+`@ts-expect-error` in
+[`test/types/refusals.ts`](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail-ui/test/types/refusals.ts)
+that fails the typecheck the moment it stops holding:
+
+1. `ui()` without a `brand`.
+2. A `brand` given as its name alone, rather than `{ name }`.
+3. A `logo` given as its URL alone, rather than `{ src }`.
+4. A logo `width` that is not a number of pixels (`'96px'`).
+5. A `theme` value that is not a CSS string (`{ 'radius-lg': 4 }`).
+6. A template that assigns `brand`.
+7. A `logo` without its `src`.
+8. A `brand.url` that is not a string.
+
+The same file holds the calls that must keep compiling: a refusal that refuses
+the correct call is a bug.
+
+**2 template mistakes, 2 refused** by `.maizzle/nxgt-mail-ui.d.ts`, each
+measured by a `@vue-expect-error` in
+[`test/fixture/types/refusals.vue`](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail-ui/test/fixture/types/refusals.vue),
+checked by `vue-tsc` after `maizzle prepare` (`bun run typecheck:templates`):
+
+1. A field the brand does not have (`brand.nmae`).
+2. `brand.logo.src` without `?.`: the logo is optional.
+
+A theme token is a `string`: whether `theme.css` declares it is checked when
+`ui()` is called. A component's props are not in this count: Maizzle declares
+the components in `.maizzle/prefixed-components.d.ts`, and Vue's language
+tools check them in the editor.
+
+## Documentation
+
+- [The guides](docs/README.md) — one page per area, with every option,
+  component and error.
+- [Troubleshooting](docs/troubleshooting.md) — an error message, its cause and
+  its fix.
+- [Roadmap](docs/roadmap.md) — what is next, and what is deliberately not
+  planned.
+- [Vocabulary](https://github.com/softistx/nxgt-mail/blob/develop/docs/vocabulary.md)
+  — the words these pages use, defined once.
+
+## Licence
+
+MIT

package/components/alert.vue

@@ -0,0 +1,75 @@
+<script setup lang="ts">
+import { twMerge } from '@maizzle/framework';
+import { computed, useAttrs, useSlots } from 'vue';
+
+/** material-vue's Alert: a tinted block with a thick bar on its left. */
+type Variant =
+	| 'primary'
+	| 'secondary'
+	| 'error'
+	| 'success'
+	| 'info'
+	| 'warning'
+	| 'foreground';
+
+defineOptions({ inheritAttrs: false });
+
+const props = withDefaults(
+	defineProps<{
+		variant?: Variant;
+		title?: string;
+		description?: string;
+	}>(),
+	{ variant: 'primary' },
+);
+
+const VARIANT: Record<Variant, string> = {
+	primary: 'border-primary bg-primary-5',
+	secondary: 'border-secondary bg-secondary-5',
+	error: 'border-error bg-error-5',
+	success: 'border-success bg-success-5',
+	info: 'border-info bg-info-5',
+	warning: 'border-warning bg-warning-5',
+	foreground: 'border-foreground bg-muted',
+};
+
+/** material-vue colours the icon with the variant: `[&_svg]:text-<variant>`. */
+const ICON: Record<Variant, string> = {
+	primary: 'text-primary',
+	secondary: 'text-secondary',
+	error: 'text-error',
+	success: 'text-success',
+	info: 'text-info',
+	warning: 'text-warning',
+	foreground: 'text-foreground',
+};
+
+const attrs = useAttrs();
+const slots = useSlots();
+const classes = computed(() =>
+	twMerge(
+		'border-0 border-l-8 border-solid p-4',
+		VARIANT[props.variant],
+		attrs.class as string,
+	),
+);
+</script>
+
+<template>
+  <table class="mb-4 w-full" role="presentation" cellpadding="0" cellspacing="0">
+    <tr>
+      <td v-bind="{ ...attrs, class: undefined }" :class="classes">
+        <table class="w-full" role="presentation" cellpadding="0" cellspacing="0">
+          <tr>
+            <td v-if="slots.icon" :class="`w-6 pr-2 align-top ${ICON[props.variant]}`"><slot name="icon" /></td>
+            <td class="align-top">
+              <p v-if="title || slots.title" class="m-0 mb-1 text-base font-bold text-foreground"><slot name="title">{{ title }}</slot></p>
+              <p v-if="description || slots.description" class="m-0 text-sm text-muted-foreground"><slot name="description">{{ description }}</slot></p>
+              <slot />
+            </td>
+          </tr>
+        </table>
+      </td>
+    </tr>
+  </table>
+</template>

package/components/avatar-fallback.vue

@@ -0,0 +1,21 @@
+<script setup lang="ts">
+import { twMerge } from '@maizzle/framework';
+import { computed, inject, useAttrs } from 'vue';
+import { AVATAR_SIZE } from './ui';
+
+/** material-vue's AvatarFallback: initials, centred on a muted ground. */
+defineOptions({ inheritAttrs: false });
+
+const attrs = useAttrs();
+const px = inject(AVATAR_SIZE, 32);
+const classes = computed(() =>
+	twMerge(
+		'block rounded-full bg-muted text-center text-[12px] font-medium text-foreground',
+		attrs.class as string,
+	),
+);
+</script>
+
+<template>
+  <span v-bind="{ ...attrs, class: undefined }" :class="classes" :style="`width: ${px}px; height: ${px}px; line-height: ${px}px;`"><slot /></span>
+</template>

package/components/avatar-group.vue

@@ -0,0 +1,44 @@
+<script setup lang="ts">
+import { twMerge } from '@maizzle/framework';
+import { computed, getCurrentInstance, provide, useAttrs, useSlots } from 'vue';
+import { AVATAR_SIZE, sharedMessage, slotComponents } from './ui';
+
+/**
+ * material-vue's AvatarGroup: its `NxAvatar`s in a row, each ringed with the
+ * background, and past `max`, one more reading `+N`. They sit side by side
+ * rather than overlapping: Gmail drops the negative margin that stacks them.
+ */
+type Size = 'sm' | 'md' | 'lg';
+
+defineOptions({ inheritAttrs: false });
+
+const props = withDefaults(defineProps<{ max?: number; size?: Size }>(), {
+	size: 'md',
+});
+
+const SIZE: Record<Size, number> = { sm: 24, md: 32, lg: 40 };
+
+const attrs = useAttrs();
+const slots = useSlots();
+provide(AVATAR_SIZE, SIZE[props.size]);
+const avatars = computed(() => slotComponents(slots.default?.()));
+// As material-vue's: no `max`, or one under 1, shows them all.
+const shown = computed(() =>
+	props.max === undefined || props.max < 1
+		? avatars.value
+		: avatars.value.slice(0, props.max),
+);
+const rest = computed(() => avatars.value.length - shown.value.length);
+const globals: Record<string, unknown> =
+	getCurrentInstance()?.appContext.config.globalProperties ?? {};
+const moreLabel = computed(() =>
+	sharedMessage(globals, 'common.avatarGroup.more', `${rest.value} more`, {
+		count: rest.value,
+	}),
+);
+const classes = computed(() => twMerge('mb-4', attrs.class as string));
+</script>
+
+<template>
+  <div v-bind="{ ...attrs, class: undefined }" :class="classes"><span v-for="(avatar, index) in shown" :key="index" class="mr-1 inline-block rounded-full border-2 border-solid border-background align-middle"><component :is="avatar" /></span><span v-if="rest > 0" class="inline-block rounded-full border-2 border-solid border-background align-middle" :title="moreLabel" role="img" :aria-label="moreLabel"><NxAvatar><NxAvatarFallback>+{{ rest }}</NxAvatarFallback></NxAvatar></span></div>
+</template>

package/components/avatar-image.vue

@@ -0,0 +1,20 @@
+<script setup lang="ts">
+import { twMerge } from '@maizzle/framework';
+import { computed, inject, useAttrs } from 'vue';
+import { AVATAR_SIZE } from './ui';
+
+/** material-vue's AvatarImage: the picture, by absolute URL, cut round. */
+defineOptions({ inheritAttrs: false });
+
+defineProps<{ src: string; alt?: string }>();
+
+const attrs = useAttrs();
+const px = inject(AVATAR_SIZE, 32);
+const classes = computed(() =>
+	twMerge('block rounded-full', attrs.class as string),
+);
+</script>
+
+<template>
+  <img v-bind="{ ...attrs, class: undefined }" :src="src" :alt="alt ?? ''" :width="px" :height="px" :class="classes">
+</template>

package/components/avatar.vue

@@ -0,0 +1,29 @@
+<script setup lang="ts">
+import { twMerge } from '@maizzle/framework';
+import { computed, inject, provide, useAttrs } from 'vue';
+import { AVATAR_SIZE } from './ui';
+
+/**
+ * material-vue's Avatar: a round box of `size` pixels (32 by default, or its
+ * `NxAvatarGroup`'s) holding an `NxAvatarImage` or an `NxAvatarFallback`.
+ * An e-mail cannot fall back when an image fails: give one or the other.
+ */
+defineOptions({ inheritAttrs: false });
+
+const props = defineProps<{ size?: number }>();
+
+const attrs = useAttrs();
+const inherited = inject(AVATAR_SIZE, 32);
+const px = computed(() => props.size ?? inherited);
+provide(AVATAR_SIZE, px.value);
+const classes = computed(() =>
+	twMerge(
+		'inline-block overflow-hidden rounded-full align-middle',
+		attrs.class as string,
+	),
+);
+</script>
+
+<template>
+  <span v-bind="{ ...attrs, class: undefined }" :class="classes" :style="`width: ${px}px; height: ${px}px;`"><slot /></span>
+</template>

package/components/badge.vue

@@ -0,0 +1,47 @@
+<script setup lang="ts">
+import { twMerge } from '@maizzle/framework';
+import { computed, useAttrs } from 'vue';
+
+/** material-vue's Badge: a small pill of text. */
+type Variant =
+	| 'default'
+	| 'secondary'
+	| 'destructive'
+	| 'error'
+	| 'success'
+	| 'info'
+	| 'warning'
+	| 'outline'
+	| 'outlined';
+
+defineOptions({ inheritAttrs: false });
+
+const props = withDefaults(defineProps<{ variant?: Variant }>(), {
+	variant: 'default',
+});
+
+const VARIANT: Record<Variant, string> = {
+	default: 'border-primary bg-primary text-primary-foreground',
+	secondary: 'border-secondary bg-secondary text-secondary-foreground',
+	destructive: 'border-error bg-error text-white',
+	error: 'border-error bg-error text-error-foreground',
+	success: 'border-success bg-success text-success-foreground',
+	info: 'border-info bg-info text-info-foreground',
+	warning: 'border-warning bg-warning text-warning-foreground',
+	outline: 'border-border text-foreground',
+	outlined: 'border-border text-foreground',
+};
+
+const attrs = useAttrs();
+const classes = computed(() =>
+	twMerge(
+		'inline-block whitespace-nowrap rounded-full border border-solid px-2 py-0.5 text-xs font-medium',
+		VARIANT[props.variant],
+		attrs.class as string,
+	),
+);
+</script>
+
+<template>
+  <span v-bind="{ ...attrs, class: undefined }" :class="classes"><slot /></span>
+</template>

package/components/banner.vue

@@ -0,0 +1,57 @@
+<script setup lang="ts">
+import { twMerge } from '@maizzle/framework';
+import { computed, useAttrs, useSlots } from 'vue';
+import type { Tone } from './ui';
+
+/**
+ * material-vue's Banner: a status in a tinted, bordered box, with an
+ * `action` on the right. Its icon is a slot: an e-mail has no icon font.
+ */
+defineOptions({ inheritAttrs: false });
+
+const props = withDefaults(
+	defineProps<{
+		tone?: Tone;
+		title?: string;
+		description?: string;
+	}>(),
+	{ tone: 'info' },
+);
+
+const TONE: Record<Tone, string> = {
+	info: 'border-info-40 bg-info-10',
+	success: 'border-success-40 bg-success-10',
+	warning: 'border-warning-40 bg-warning-10',
+	error: 'border-error-40 bg-error-10',
+};
+
+const attrs = useAttrs();
+const slots = useSlots();
+const classes = computed(() =>
+	twMerge(
+		'rounded-md border border-solid px-4 py-3',
+		TONE[props.tone],
+		attrs.class as string,
+	),
+);
+</script>
+
+<template>
+  <table class="mb-4 w-full" role="presentation" cellpadding="0" cellspacing="0">
+    <tr>
+      <td v-bind="{ ...attrs, class: undefined }" :class="classes">
+        <table class="w-full" role="presentation" cellpadding="0" cellspacing="0">
+          <tr>
+            <td v-if="slots.icon" :class="`w-4 pr-3 align-top text-${tone}`"><slot name="icon" /></td>
+            <td class="align-top text-foreground">
+              <p v-if="title" class="m-0 text-sm font-semibold">{{ title }}</p>
+              <p v-if="description" class="m-0 text-sm text-muted-foreground">{{ description }}</p>
+              <slot />
+            </td>
+            <td v-if="slots.action" class="pl-3 text-right align-middle"><slot name="action" /></td>
+          </tr>
+        </table>
+      </td>
+    </tr>
+  </table>
+</template>

package/components/breakdown-card.vue

@@ -0,0 +1,27 @@
+<script setup lang="ts">
+/**
+ * material-vue's BreakdownCard: parts of a whole, each a label, its value
+ * (its share when none is given) and a thin `NxProgress` of its share.
+ */
+defineProps<{
+	label: string;
+	items: readonly { label: string; value?: string; percent: number }[];
+}>();
+</script>
+
+<template>
+  <NxCard class="py-4">
+    <NxCardContent class="px-4">
+      <NxCardDescription class="mt-0">{{ label }}</NxCardDescription>
+      <template v-for="(item, position) in items" :key="item.label">
+        <table :class="['w-full', position === 0 ? 'mt-4' : 'mt-3']" role="presentation" cellpadding="0" cellspacing="0">
+          <tr>
+            <td class="align-bottom text-sm font-medium text-foreground">{{ item.label }}</td>
+            <td class="whitespace-nowrap pl-3 text-right align-bottom text-sm text-muted-foreground">{{ item.value ?? `${Math.round(item.percent)}%` }}</td>
+          </tr>
+        </table>
+        <NxProgress class="mb-0 mt-1.5" :model-value="item.percent" :height="6" />
+      </template>
+    </NxCardContent>
+  </NxCard>
+</template>

package/components/card-content.vue

@@ -0,0 +1,16 @@
+<script setup lang="ts">
+import { twMerge } from '@maizzle/framework';
+import { computed, useAttrs } from 'vue';
+
+/** material-vue's CardContent: a row of the card, padded as the others. */
+defineOptions({ inheritAttrs: false });
+
+const attrs = useAttrs();
+const classes = computed(() => twMerge('px-6', attrs.class as string));
+</script>
+
+<template>
+  <tr>
+    <td v-bind="{ ...attrs, class: undefined }" :class="classes"><slot /></td>
+  </tr>
+</template>