@anfo/nuxt-dialogs-plugin 1.0.0

package/README.md

@@ -0,0 +1,162 @@
+# @anfo/nuxt-dialogs-plugin
+
+A Nuxt module that auto-scans a directory for Vue dialog/drawer components and exposes them through a fully type-safe virtual module (`virtual:dialogs`). Dialogs are mounted programmatically into isolated Vue app instances — no `<Teleport>` boilerplate, no global store, automatic cleanup on close.
+
+**Nuxt-native extras** — dialog apps automatically inherit the Nuxt app's context, so Pinia, i18n, UI libraries, global components and directives work inside dialogs with zero wiring. `dialogs` and the runtime composables are auto-imported.
+
+> This is the Nuxt counterpart of [`@anfo/vite-dialogs-plugin`](https://github.com/) — it is a standalone package and does not depend on it.
+
+## Installation
+
+```bash
+npm install -D @anfo/nuxt-dialogs-plugin
+```
+
+## Quick Start
+
+### 1. Register the module — `nuxt.config.ts`
+
+```ts
+export default defineNuxtConfig({
+  modules: ["@anfo/nuxt-dialogs-plugin"],
+
+  // Optional — these are the defaults
+  dialogs: {
+    dir: "dialogs", // relative to srcDir
+    // pattern: /(Dialog|Drawer)\.vue$/,
+    // inheritNuxtApp: true,
+  },
+});
+```
+
+### 2. Create a dialog component
+
+Every `.vue` file whose name ends with `Dialog.vue` or `Drawer.vue` inside your `dir` becomes a key on the `dialogs` object. No tsconfig changes are needed — the module generates the type declarations for you.
+
+```vue
+<!-- dialogs/ConfirmDialog.vue -->
+<script setup lang="ts">
+import {
+  useDialogContext,
+  createDialogExpose,
+  type DialogExposed,
+} from "@anfo/nuxt-dialogs-plugin/runtime";
+
+defineProps<{ message: string }>();
+
+const { resolve, reject } = useDialogContext<boolean>();
+
+defineExpose<DialogExposed<boolean>>(createDialogExpose<boolean>());
+</script>
+
+<template>
+  <div class="overlay">
+    <div class="box">
+      <p>{{ message }}</p>
+      <button @click="resolve(true)">Confirm</button>
+      <button @click="resolve(false)">Cancel</button>
+    </div>
+  </div>
+</template>
+```
+
+### 3. Open dialogs from anywhere
+
+`dialogs` is auto-imported — no import statement needed:
+
+```vue
+<script setup lang="ts">
+const result = await dialogs.ConfirmDialog({ message: "Delete this item?" });
+if (result.type === "resolve" && result.value) {
+  // confirmed
+}
+
+// Or chain callbacks
+dialogs
+  .ConfirmDialog({ message: "Are you sure?" })
+  .resolve((value) => console.log("resolved:", value))
+  .reject((reason) => console.log("rejected:", reason));
+</script>
+```
+
+## Context inheritance — why dialogs "just work"
+
+Each dialog is mounted into its own isolated `createApp()` instance. By default (`inheritNuxtApp: true`) the module captures the Nuxt app and clones its context — global components, directives and `provide`s — onto every dialog app. That means everything your Nuxt app registered is available inside dialogs automatically:
+
+- **Pinia** stores (`@pinia/nuxt`)
+- **i18n** (`@nuxtjs/i18n` — `$t`, translations)
+- **UI libraries** (Element Plus, PrimeVue, Vuetify… registered via Nuxt plugins)
+- **Global components and directives**
+- **The `nuxtApp` itself** — `useNuxtApp()`, `useRoute()`… work inside dialogs
+
+Set `inheritNuxtApp: false` to keep dialogs fully isolated (parity with plain Vite projects), and register exactly what you need with `configureDialogs()`:
+
+```ts
+// plugins/dialogs.ts
+export default defineNuxtPlugin((nuxtApp) => {
+  configureDialogs({
+    use: [
+      (app) => {
+        app.config.globalProperties.$something = "...";
+      },
+    ],
+  });
+});
+```
+
+Both plugin objects (`{ install(app) {} }`) and plain `(app) => void` functions are accepted.
+
+## Module Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `dir` | `string` | `"dialogs"` | Directory containing dialog components; relative paths resolve against `srcDir`. |
+| `pattern` | `RegExp` | `/(Dialog\|Drawer)\.vue$/` | RegExp to identify which files are dialogs. |
+| `inheritNuxtApp` | `boolean` | `true` | Dialog apps inherit the Nuxt app's context (components, directives, provides). |
+
+## Auto-imports
+
+| Name | From | Description |
+|---|---|---|
+| `dialogs` | `virtual:dialogs` | Open dialogs — `dialogs.ConfirmDialog(props)`. |
+| `useDialogContext` | `./runtime` | Get `{ resolve, reject }` inside a dialog component. |
+| `createDialogExpose` | `./runtime` | Typed expose helper for `defineExpose`. |
+| `configureDialogs` | `./runtime` | Register extra plugins for every dialog app. |
+
+## Package Exports
+
+| Specifier | Contents |
+|---|---|
+| `@anfo/nuxt-dialogs-plugin` | Nuxt module |
+| `@anfo/nuxt-dialogs-plugin/runtime` | Types, `useDialogContext`, `createDialogExpose`, `configureDialogs`, `DialogExposed` |
+
+## SSR
+
+Dialogs are DOM-only. Calling `dialogs.*` during server-side rendering is safe — it warns and settles as `{ type: "reject", reason }` instead of crashing the render. Open dialogs from event handlers or `onMounted`.
+
+> Do not import `virtual:dialogs` from Nitro server code (`server/api`, `server/routes`) — the virtual module is only available in the app build.
+
+## Project Structure
+
+```
+<srcDir>/
+├── dialogs/              ← your dialog components (configurable)
+│   ├── ConfirmDialog.vue
+│   ├── AlertDialog.vue
+│   └── UserDrawer.vue
+└── nuxt.config.ts
+```
+
+## How It Works
+
+1. On startup the module registers a Vite plugin, a tiny runtime plugin (context capture), auto-imports and a type template.
+2. The Vite plugin generates a virtual module (`virtual:dialogs`) that imports each component through the `#dialogs-components` alias and wraps it in `mountDialog()`.
+3. `mountDialog()` creates an isolated `createApp()` instance per call, inherits the Nuxt app context, provides a `DialogController`, mounts it into a temporary `<div>`, and returns a Promise-based handle.
+4. When the component calls `resolve(value)` or `reject(reason)`, the app is unmounted and the host element removed automatically.
+5. A `.d.ts` type template is written into `.nuxt/` so every `dialogs.*` entry is typed end-to-end — props, return value, and callbacks. It regenerates when dialog files are added or removed during dev.
+
+> See [SKILL.md](SKILL.md) for step-by-step examples covering all dialog patterns.
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,274 @@
+# Skill Guide — Creating Dialog Components in Nuxt
+
+This guide shows every pattern for building dialog and drawer components that work with `@anfo/nuxt-dialogs-plugin`. All types and composables are auto-imported in Nuxt — explicit imports from `@anfo/nuxt-dialogs-plugin/runtime` also work and are shown here for clarity.
+
+---
+
+## Runtime API Reference
+
+Import from `@anfo/nuxt-dialogs-plugin/runtime` (or rely on auto-imports):
+
+| Export                    | Auto-imported | Description                                                                       |
+| ------------------------- | ------------- | --------------------------------------------------------------------------------- |
+| `dialogs`                 | ✅            | Open dialogs — `dialogs.ConfirmDialog(props)` (virtual module `virtual:dialogs`)   |
+| `useDialogContext<T>()`   | ✅            | Composable — returns `{ resolve, reject }` inside a dialog component              |
+| `createDialogExpose<T>()` | ✅            | Helper — creates the typed expose object (shorthand for `{} as DialogExposed<T>`) |
+| `configureDialogs()`      | ✅            | Register extra Vue plugins to `app.use()` on every dialog app                     |
+| `DialogExposed<T>`        | — type        | Marker type — put in `defineExpose<>` to declare the resolve value type           |
+| `DialogController<T>`     | — type        | `{ resolve: DialogResolve<T>, reject: DialogReject }`                             |
+| `DialogSettledResult<T>`  | — type        | Union of `DialogResolvedResult<T>` and `DialogRejectedResult`                     |
+| `DialogResolvedResult<T>` | — type        | `{ type: "resolve" }` or `{ type: "resolve"; value: T }`                          |
+| `DialogRejectedResult`    | — type        | `{ type: "reject"; reason?: unknown }`                                            |
+| `DialogAppPlugin`         | — type        | Alias of Vue's `Plugin` — a plugin object or a function taking the app            |
+
+---
+
+## Nuxt setup
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ["@anfo/nuxt-dialogs-plugin"],
+
+  // Optional — defaults shown
+  dialogs: {
+    dir: "dialogs", // relative to srcDir
+    // pattern: /(Dialog|Drawer)\.vue$/,
+    // inheritNuxtApp: true,
+  },
+});
+```
+
+Place dialog components in `<srcDir>/dialogs/` (or configure `dir`). Files ending in `Dialog.vue` or `Drawer.vue` become keys on the `dialogs` object. Types are generated into `.nuxt/` automatically — no tsconfig changes needed.
+
+---
+
+## Context inheritance
+
+By default every dialog app **inherits the Nuxt app's context** — global components, directives and provides. Inside dialog components this means:
+
+- Pinia stores work (`@pinia/nuxt`)
+- `$t` / i18n works (`@nuxtjs/i18n`)
+- UI library components registered in Nuxt work
+- `useNuxtApp()`, `useRoute()` work
+
+No wiring needed. To opt out, set `inheritNuxtApp: false` and register exactly what you need with `configureDialogs()`:
+
+```ts
+// plugins/dialogs.ts
+export default defineNuxtPlugin((nuxtApp) => {
+  configureDialogs({
+    use: [
+      // plain functions and plugin objects both work
+      (app) => {
+        app.config.globalProperties.$t = translate;
+      },
+    ],
+  });
+});
+```
+
+---
+
+## Pattern 1 — Simple dialog, no return value
+
+The simplest case: open, the user clicks a button, dialog closes.
+
+```vue
+<!-- dialogs/AlertDialog.vue -->
+<script setup lang="ts">
+import { useDialogContext } from "@anfo/nuxt-dialogs-plugin/runtime";
+
+defineProps<{ message: string }>();
+
+const { resolve } = useDialogContext();
+</script>
+
+<template>
+  <div class="overlay">
+    <div class="box">
+      <p>{{ message }}</p>
+      <button @click="resolve()">OK</button>
+    </div>
+  </div>
+</template>
+```
+
+```vue
+<!-- Caller (auto-imported `dialogs`) -->
+<script setup lang="ts">
+await dialogs.AlertDialog({ message: "File saved." });
+// resolves with { type: "resolve" } — no value
+</script>
+```
+
+---
+
+## Pattern 2 — Dialog that returns a typed value
+
+Use `defineExpose<DialogExposed<T>>` to declare what `resolve()` carries. The generic `T` flows all the way to the caller's return type.
+
+```vue
+<!-- dialogs/ConfirmDialog.vue -->
+<script setup lang="ts">
+import {
+  useDialogContext,
+  createDialogExpose,
+  type DialogExposed,
+} from "@anfo/nuxt-dialogs-plugin/runtime";
+
+defineProps<{
+  message: string;
+  confirmLabel?: string;
+}>();
+
+const { resolve } = useDialogContext<boolean>();
+
+// Declare the resolve type — T = boolean
+defineExpose<DialogExposed<boolean>>(createDialogExpose<boolean>());
+</script>
+
+<template>
+  <div class="overlay">
+    <div class="box">
+      <p>{{ message }}</p>
+      <button @click="resolve(true)">{{ confirmLabel ?? "Confirm" }}</button>
+      <button @click="resolve(false)">Cancel</button>
+    </div>
+  </div>
+</template>
+```
+
+```ts
+// Caller — result.value is typed as boolean | undefined
+const result = await dialogs.ConfirmDialog({ message: "Delete item?" });
+if (result.type === "resolve" && result.value) {
+  await deleteItem();
+}
+```
+
+---
+
+## Pattern 3 — Dialog with reject
+
+Call `reject(reason)` for explicit cancellation that the caller can distinguish from a normal close.
+
+```vue
+<!-- dialogs/PromptDialog.vue -->
+<script setup lang="ts">
+import { ref } from "vue";
+import {
+  useDialogContext,
+  createDialogExpose,
+  type DialogExposed,
+} from "@anfo/nuxt-dialogs-plugin/runtime";
+
+defineProps<{ label: string }>();
+
+const { resolve, reject } = useDialogContext<string>();
+const input = ref("");
+
+defineExpose<DialogExposed<string>>(createDialogExpose<string>());
+</script>
+
+<template>
+  <div class="overlay">
+    <div class="box">
+      <label>{{ label }}</label>
+      <input v-model="input" @keydown.enter="resolve(input)" />
+      <button @click="resolve(input)">OK</button>
+      <button @click="reject('cancelled')">Cancel</button>
+    </div>
+  </div>
+</template>
+```
+
+```ts
+// Caller — chain style
+dialogs
+  .PromptDialog({ label: "Enter a name" })
+  .resolve((name) => console.log("Got:", name))
+  .reject((reason) => console.log("Cancelled:", reason));
+
+// Caller — await style
+const result = await dialogs.PromptDialog({ label: "Enter a name" });
+if (result.type === "resolve") {
+  console.log(result.value); // string | undefined
+} else {
+  console.log(result.reason); // "cancelled"
+}
+```
+
+---
+
+## Pattern 4 — Drawer
+
+Files ending in `Drawer.vue` are matched by the default pattern and work identically to dialogs.
+
+```vue
+<!-- dialogs/UserDrawer.vue -->
+<script setup lang="ts">
+import { useDialogContext } from "@anfo/nuxt-dialogs-plugin/runtime";
+
+defineProps<{ userId: string }>();
+const { resolve } = useDialogContext();
+</script>
+
+<template>
+  <aside class="drawer">
+    <p>User: {{ userId }}</p>
+    <button @click="resolve()">Close</button>
+  </aside>
+</template>
+```
+
+```ts
+await dialogs.UserDrawer({ userId: "abc123" });
+```
+
+---
+
+## Pattern 5 — Dialog using Pinia / global components
+
+Thanks to context inheritance, dialogs can use anything registered in the Nuxt app — e.g. a Pinia store and UI-library components:
+
+```vue
+<!-- dialogs/CartDialog.vue -->
+<script setup lang="ts">
+import { useCartStore } from "~/stores/cart";
+import { useDialogContext } from "@anfo/nuxt-dialogs-plugin/runtime";
+
+const cart = useCartStore();
+const { resolve } = useDialogContext();
+</script>
+
+<template>
+  <div class="overlay">
+    <div class="box">
+      <p>{{ cart.items.length }} items — {{ cart.total }}</p>
+      <button @click="resolve()">Done</button>
+    </div>
+  </div>
+</template>
+```
+
+---
+
+## SSR behavior
+
+Dialogs are DOM-only. Calling `dialogs.*` during SSR warns and settles as `{ type: "reject", reason }` — it never crashes the server render. Open dialogs from event handlers or `onMounted`. Don't import `virtual:dialogs` from Nitro server code (`server/api`, `server/routes`).
+
+---
+
+## Summary
+
+| Task                     | How                                                                        |
+| ------------------------ | -------------------------------------------------------------------------- |
+| Get resolve/reject       | `const { resolve, reject } = useDialogContext<T>()`                        |
+| Declare return type      | `defineExpose<DialogExposed<T>>(createDialogExpose<T>())`                  |
+| Open from app code       | `dialogs.MyDialog(props)` — auto-imported, or import from `virtual:dialogs` |
+| Await result             | `const result = await dialogs.MyDialog(props)`                             |
+| Chain callbacks          | `.resolve(cb).reject(cb)`                                                  |
+| Share Pinia / UI libs    | Automatic via `inheritNuxtApp` (default); extras via `configureDialogs()`  |
+
+The module auto-regenerates the virtual module and types whenever you add or remove dialog files during dev — no manual registration needed.