# CODEBUDDY.md

This file provides guidance to CodeBuddy Code when working with code in this repository.

## Overview

G3Soft frontend infrastructure — a pnpm monorepo holding a self-built **Vue 3 component library** plus a **Docus documentation site**.

- `packages/ui` (`@g3soft/ui`) — component library, published to a private npm registry. One directory per component under `src/<name>/`.
- `packages/tokens` (`@g3soft/tokens`) — design tokens as plain CSS (`--g3-*` variables), shared by the library and the docs site.
- `docs` (`@g3soft/docs`) — Docus/Nuxt docs site. `private: true`, never published.
- `scripts/gen-api.mjs` — generates component API data from source.

Requires Node >= 20.19 and pnpm 11 (see `packageManager` in root `package.json`).

## Commands

```bash
pnpm install

pnpm dev            # start docs site (http://localhost:3000); live-reloads packages/ui via alias
pnpm build          # build all packages under packages/** (component lib -> dist)
pnpm build:docs     # build docs static site -> docs/.output/public
pnpm preview:docs   # preview the built docs site

pnpm gen:api        # regenerate docs/data/api/*.json from component source (REQUIRED after changing props/events/slots)
```

Deploying docs to a subpath:

```bash
NUXT_APP_BASE_URL=/docs/ pnpm build:docs
```

Releasing the component library (changesets):

```bash
pnpm changeset      # record the change
pnpm version        # bump versions + generate CHANGELOG
pnpm release        # build + publish to the private registry
```

`packages/ui` runs `publint` via `prepublishOnly` to validate package structure (`exports`/`files` consistency).

**Testing:** there is no test runner configured in this repo (no vitest/jest, no test files). Do not assume `pnpm test` exists.

### Running a single component's checks

There is no per-component test/lint script. The closest equivalent is `pnpm --filter @g3soft/ui build` (runs `vite build`, which type-checks declarations via `vite-plugin-dts`), and `pnpm gen:api` to verify the docgen extraction still parses a component.

## Architecture

### Two independent pipelines

The docs site and the component library are deliberately decoupled:

| | Docs site | Component package |
|---|---|---|
| Published | No (`private: true`) | Yes (private npm registry) |
| Versioning | None | changesets (`ignore: ["@g3soft/docs"]`) |
| Build | `pnpm build:docs` | `pnpm build` |
| Output | `docs/.output/public` (static) | `packages/ui/dist` (ESM + d.ts) |
| Dep boundary | Docus/Nuxt/Tailwind live only in the `docs` package | only `vue` (peer) + `@g3soft/tokens` |

Nuxt-related deps appear **only** in `docs/package.json`; the library's dependency tree has none of it. changesets' `ignore` keeps the docs site out of version tags.

### Component library build (`packages/ui`)

`vite.config.ts` builds ESM + type declarations. Critical points:
- `vue` is marked `external` — never bundle Vue, or consumers get duplicate instances.
- `preserveModules` keeps the `src` structure so consumers can tree-shake.
- `vite-plugin-dts` with `rollupTypes` emits a single `dist/index.d.ts`, matched by `exports.types`.
- `src/index.ts` is the public entry: it re-exports every component plus its types, and exports the optional `G3UI` install plugin for whole-library registration.

### Docs site (`docs`)

- `extends: ['docus']` — all navigation/search/theme comes from the Docus Nuxt Layer.
- `vite.resolve.alias` points `@g3soft/ui` and `@g3soft/tokens` **directly at `packages/*/src`**, so the docs site can develop against the library without building it. Editing `packages/ui` hot-reloads the docs immediately.
- `site.url` is required (sitemap, llms.txt, OG images) — missing it breaks prerender with a 500.
- Deploy base path comes from `NUXT_APP_BASE_URL` (Nuxt's env override for `app.baseURL`), never hardcoded.
- `docs/app/components/content/` holds components usable directly inside Markdown: `Demo.vue` (renders a runnable example + source) and `ApiTable.vue` (renders the generated API tables).

### API generation pipeline

`scripts/gen-api.mjs` uses `vue-docgen-api` to parse every `.vue` under `packages/ui/src`, extracts props/events/slots and their JSDoc comments, and writes `docs/data/api/<dirName>.json`. `ApiTable.vue` reads those JSON files by component name.

Consequence: **API tables are generated from source and must never be hand-written.** The component directory name is the doc key (`src/button/Button.vue` → `button`). After any change to a component's props/events/slots, run `pnpm gen:api`.

### Design tokens (`packages/tokens`)

- `src/index.css` imports `tokens.css` (light/default) and `dark.css`. Consumed as `import '@g3soft/tokens'`.
- Dark theme activates via `html[data-g3-theme='dark']` (`document.documentElement.dataset.g3Theme = 'dark'`).
- Re-theming/customer customization = overriding same-named `--g3-*` variables, no component changes.

### Windows: dev-server port selection

`docs/package.json` runs `node scripts/dev.mjs` for `dev` (not `nuxt dev` directly). On Windows, Node sets `SO_REUSEADDR`, so **two processes can bind the same `host:port`**. Nuxt's built-in "is the port free?" check works by *trying to bind* a probe socket — which therefore succeeds even when another service already listens on 3000, so `pnpm dev` silently lands on 3000 (no 3000→3001 fallback). `scripts/dev.mjs` sidesteps this by testing the port with a real TCP *connection* (`connect` to `127.0.0.1`/`::1`) and walking upward from `DOCS_PORT`/`PORT`/3000 until it finds a free one, then passing `--port`. `devServer.host: ''` (empty string — deliberately not `'0.0.0.0'`) makes listhen listen on all interfaces *and* print a usable `Local: http://localhost:<port>/` plus the LAN `Network:` URL; with `'0.0.0.0'` the Local line would be an unopenable `http://0.0.0.0:<port>/`.

## Conventions (must follow)

- **No `scoped` in component `<style>`.** Isolate with the `g3-` prefix + BEM naming so consumers can override.
- **Never hardcode colors or sizes** — always reference `--g3-*` variables, and give every variable a fallback value (e.g. `var(--g3-color-primary, #18181b)`) so components render correctly even when `@g3soft/tokens` is not loaded.
- **Component API docs are generated, not authored** — changes to props/events/slots require `pnpm gen:api`.
- **Examples** live at `docs/examples/<component>/<example>.vue` and are referenced in Markdown as `::demo{name="<component>/<example>"}`. API tables use `<ApiTable name="<component>" />`.
- New components get a `src/<name>/` directory (component `.vue`, `types.ts`, `index.ts`) and must be re-exported from `src/index.ts`.

## Version constraints (do not relax)

`pnpm-workspace.yaml` documents these deliberately — read it before touching dependency versions:

- **`nuxt` is pinned to exactly `4.4.8` in `docs/package.json`.** Do not widen to `^4.4.8` or upgrade to 4.5+. Nuxt 4.5+ pulls Vite 8 (Rolldown), which cannot resolve Nitro's `file:///D:/...` virtual modules on Windows, breaking `#nitro-internal-virtual/*` and causing every page to 500 (`Either manifest or precomputed data must be provided`). 4.4.8 → Vite 7 (Rollup) and matches Docus's official starter.
- **`pnpm 11` uses the `allowBuilds` map form** in `pnpm-workspace.yaml` — the v10 `onlyBuiltDependencies` array form is inert. `better-sqlite3` (Docus FTS5 search native module), `vue-demi`, and `esbuild` must stay allowed.
- `vue` and `typescript` versions are centralized in the workspace `catalog:`; each package references `"vue": "catalog:"` to avoid version drift.