# @ramathibodi/nuxt-commons

Nuxt module for Nuxt 3 and Nuxt 4 that provides shared runtime building blocks for Rama projects:
- globally auto-imported UI components
- auto-imported composables
- runtime plugins for permission/dialog/default behavior
- utility and lab exports

## Documentation & playground

The live playground is the project's documentation site — every component has a real demo page running the real module against the real Vuetify theme, with a Vuetify-docs-style API panel (Props / Emits / Slots / Exposed) sourced from `docs/ai-summary.json`. Bug-repro fixtures live under *Scenarios*.

→ **https://ramacare.gitlab.rama.mahidol.ac.th/frontend/rama-modules/** _(published from `master` by the `pages` CI job; if the project later moves to a unique Pages domain, update `NUXT_APP_BASE_URL` in the CI job accordingly)_

Run it locally with `pnpm run dev`. See `CLAUDE.md` &gt; *Playground* for the conventions every new/modified component must follow.

## Install

```bash
# pnpm
pnpm add -D @ramathibodi/nuxt-commons

# yarn
yarn add --dev @ramathibodi/nuxt-commons

# npm
npm install --save-dev @ramathibodi/nuxt-commons
```

## Nuxt Setup

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@ramathibodi/nuxt-commons'],
})
```

Supported Nuxt versions: `^3.16.0 || ^4.0.0`

## Plugin Initialization (Required)

After registering the module, apps **must** create a Nuxt plugin that provides `$appGraphql` and `$appAuthentication`. This wires up the module's internal bridge system so that `ModelTable`, `ModelSelect`, `useGraphQl()`, and other model-driven components can resolve GraphQL operations and access authentication state.

```ts
// app/plugins/graphql.ts (or any plugin name)
// graphqlOperation, graphqlType, graphqlInputType, scalarType are
// auto-imported from your generated composables/graphqlObject.ts.
// useAuthentication is auto-imported from your app/composables/authentication.ts.

export default defineNuxtPlugin(() => {
  return {
    provide: {
      appAuthentication: () => useAuthentication(),
      appGraphql: {
        scalarType,
        graphqlType,
        graphqlInputType,
        graphqlOperation,
      },
    },
  }
})
```

**`$appGraphql`** — Provides generated GraphQL operation metadata (scalar types, object types, input types, and operations) so `useGraphqlBridge()` and `useGraphqlModelOperation()` inside the module can resolve queries/mutations by name.

**`$appAuthentication`** — Provides a factory function returning the app's authentication state (`token`, `hasPermission`, `login`, `logout`, etc.) so the module's `useAuthentication()` bridge can access auth context for API calls and permission checks.

Prerequisites:
1. Run your GraphQL codegen to generate `composables/graphqlObject.ts` and `types/graphql.ts`.
2. Implement `useAuthentication()` in your app returning at minimum `{ token, hasPermission, login, logout }`.

See [`playground/plugins/nuxtCommon.ts`](playground/plugins/nuxtCommon.ts) for a working example.

## What The Module Registers

Configured in `src/module.ts`:
- Components from `src/runtime/components` (global + prefixed)
- Composables from `src/runtime/composables/**` (auto-imported)
- Plugins:
  - `src/runtime/plugins/permission.ts`
  - `src/runtime/plugins/dialogManager.ts` (client)
  - `src/runtime/plugins/clientConfig.ts` (client)
  - `src/runtime/plugins/default.ts` (client)
- Type templates from `src/runtime/types/*.d.ts`

## Runtime Config

This module uses public runtime config at:

```ts
runtimeConfig.public['nuxt-commons']
```

Module options are merged into this key by module setup.

## Development

```bash
# Install dependencies
npm install

# Prepare stubs/types
npm run dev:prepare

# Run playground
npm run dev

# Build playground
npm run dev:build

# Lint and test
npm run lint
npm run test
```

## Concepts

- [Model Components — Endpoint Reference](docs/model-endpoints.md) — how `modelName` translates to GraphQL operations and REST API endpoints, with body/response shapes and the `By<Qualifier>` rule for `model/*` components.
- [Document Template JSON Spec](docs/document-template-json-spec.md) — schema and conventions for document templates.

## Documentation

Generate documentation artifacts from source:

```bash
# Vue component API docs (vue-docgen)
npm run docs:api:components

# Composable API docs (typedoc)
npm run docs:api:composables

# Both API docs
npm run docs:api

# AI-focused summary + type index
npm run docs:ai:summary
```

`docs:api:components` now runs a post-process step that enriches missing prop/event descriptions and missing type/default cells in generated markdown using `docs/ai-summary.json`.

Documentation config files:
- [`docs/vue-docgen.config.cjs`](docs/vue-docgen.config.cjs) for component docs generation
- [`docs/typedoc.json`](docs/typedoc.json) for composable docs generation
- [`docs/typedoc.tsconfig.json`](docs/typedoc.tsconfig.json) for docs-only TypeScript scope

Generated outputs:
- [`docs/components/`](docs/components/) (vue-docgen output)
- [`docs/composables/`](docs/composables/) (typedoc output)
- [`docs/ai-summary.md`](docs/ai-summary.md) (compact AI-oriented markdown summary)
- [`docs/ai-summary.json`](docs/ai-summary.json) (machine-readable component/composable metadata)
- [`docs/type-index.json`](docs/type-index.json) (type index for tooling/AI pipelines)

`docs:ai:summary` generates:
- `docs/ai-summary.md`
- `docs/ai-summary.json`
- `docs/type-index.json`

## Publish Notes

`package.json` `version` is used to select the publish line by `major.minor`:

- Keep the same `major.minor` line to continue normal releases.
- Change it to `0.2.0`, `1.1.0`, etc. to start publishing that new line on the next release.

```bash
npm run dev:build
npm run release
```
