@baklavue/mcp 1.0.0

package/dist/docs/guide/installation.md

@@ -0,0 +1,287 @@
+# Installation
+
+This guide covers installation of BaklaVue in various setups: new projects, existing Vue 3 apps, Vite, Nuxt, and Vue CLI. It also includes configuration requirements and troubleshooting.
+
+## Package Installation
+
+### Core Packages
+
+BaklaVue is split into two packages:
+
+| Package | Description |
+| ------- | ----------- |
+| `@baklavue/ui` | Vue 3 components wrapping Baklava web components |
+| `@baklavue/composables` | Vue composables (theme, notifications, CSV, scroll-to-error, etc.) |
+
+Install both:
+
+```bash
+npm install @baklavue/ui @baklavue/composables
+```
+
+Or with other package managers:
+
+```bash
+# yarn
+yarn add @baklavue/ui @baklavue/composables
+
+# pnpm
+pnpm add @baklavue/ui @baklavue/composables
+
+# bun
+bun add @baklavue/ui @baklavue/composables
+```
+
+### Peer Dependencies
+
+BaklaVue expects these peer dependencies in your project:
+
+| Dependency | Version | Notes |
+| ---------- | ------- | ----- |
+| `vue` | ^3.5.21 | Required for components |
+| `typescript` | ^5.9.2 | Recommended for type support |
+
+These are usually already present in a Vue 3 project. If not:
+
+```bash
+npm install vue@^3.5.21 typescript@^5.9.2
+```
+
+### Transitive Dependencies
+
+BaklaVue brings in:
+
+- `@trendyol/baklava` ^3.4.2 — Core design system
+- `@trendyol/baklava-icons` ^1.1.0 — Icons (used by components)
+- `papaparse` — Used by `useFile` for CSV/TSV (in `@baklavue/composables` only)
+- `xlsx` — Used by `useFile` for Excel (in `@baklavue/composables` only)
+
+You do not need to install these manually.
+
+## Framework Integration
+
+### Vite + Vue 3
+
+BaklaVue works out of the box with Vite. Create a new project and add BaklaVue:
+
+```bash
+npm create vue@latest my-app
+cd my-app
+npm install @baklavue/ui @baklavue/composables
+```
+
+**Required Vite config:** BaklaVue components render Baklava web components (`bl-*` custom elements). Vue must treat these as custom elements, not Vue components. Add this to `vite.config.ts`:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import vue from "@vitejs/plugin-vue";
+
+export default defineConfig({
+  plugins: [
+    vue({
+      template: {
+        compilerOptions: {
+          isCustomElement: (tag) => tag.startsWith("bl-"),
+        },
+      },
+    }),
+  ],
+});
+```
+
+Without this, Vue may warn: `Failed to resolve component: bl-*`.
+
+### Nuxt 3
+
+For Nuxt 3:
+
+```bash
+npx nuxi@latest init my-app
+cd my-app
+npm install @baklavue/ui @baklavue/composables
+```
+
+Configure Nuxt to treat `bl-*` as custom elements. Create or edit `nuxt.config.ts`:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  vue: {
+    compilerOptions: {
+      isCustomElement: (tag) => tag.startsWith("bl-"),
+    },
+  },
+});
+```
+
+**Optional:** For tree-shaking and a smaller bundle, you can auto-import components via a Nuxt module or `components/` directory. The default approach is to import components explicitly where needed.
+
+### Vue CLI
+
+For Vue CLI projects:
+
+```bash
+vue create my-app
+cd my-app
+npm install @baklavue/ui @baklavue/composables
+```
+
+Add custom element configuration in `vue.config.js`:
+
+```js
+// vue.config.js
+const { defineConfig } = require("@vue/cli-service");
+
+module.exports = defineConfig({
+  chainWebpack: (config) => {
+    config.module
+      .rule("vue")
+      .use("vue-loader")
+      .tap((options) => {
+        options.compilerOptions = {
+          ...options.compilerOptions,
+          isCustomElement: (tag) => tag.startsWith("bl-"),
+        };
+        return options;
+      });
+  },
+});
+```
+
+## Vite Configuration (Detailed)
+
+### Custom Element Detection
+
+Baklava components are implemented as web components with tags like `bl-button`, `bl-input`, `bl-dialog`. Vue’s template compiler must not resolve these as Vue components. The `isCustomElement` option tells Vue to leave them as native custom elements:
+
+```ts
+vue({
+  template: {
+    compilerOptions: {
+      isCustomElement: (tag) => tag.startsWith("bl-"),
+    },
+  },
+});
+```
+
+### Path Aliases (Optional)
+
+If you use `@` for `src`:
+
+```ts
+// vite.config.ts
+import { resolve } from "path";
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      "@": resolve(__dirname, "src"),
+    },
+  },
+});
+```
+
+BaklaVue does not require path aliases; imports from `@baklavue/ui` and `@baklavue/composables` work as-is.
+
+## TypeScript Configuration
+
+For TypeScript, ensure your `tsconfig.json` supports module resolution and includes Vue types:
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "bundler",
+    "types": ["vite/client"],
+    "strict": true
+  },
+  "include": ["src/**/*.ts", "src/**/*.vue"]
+}
+```
+
+BaklaVue types are distributed with the packages; no extra `@types` packages are needed.
+
+## Importing Styles
+
+BaklaVue components load Baklava styles automatically when they mount. In typical usage you do not need to import anything manually.
+
+If you prefer to load styles yourself (e.g. in the entry file):
+
+```typescript
+// main.ts or main.js
+import "@trendyol/baklava/dist/themes/default.css";
+```
+
+When using the CDN (via `loadBaklavaResources`), styles are injected from jsDelivr; no manual import is needed.
+
+## Verify Installation
+
+Create a simple test component:
+
+```vue
+<template>
+  <BvButton variant="primary">Test Button</BvButton>
+</template>
+
+<script setup>
+import { BvButton } from "@baklavue/ui";
+</script>
+```
+
+If the button renders with correct styling, installation is working.
+
+## Troubleshooting
+
+### "Failed to resolve component: bl-*" warning
+
+**Cause:** Vue is trying to resolve `bl-*` tags as Vue components.
+
+**Fix:** Add `isCustomElement` so Vue treats them as custom elements. See [Vite Configuration](#vite-configuration-detailed) above.
+
+### Components not rendering or look unstyled
+
+**Possible causes:**
+
+1. **Baklava CSS not loaded** — Components load it on mount. If you render before components mount, styles may be missing. Ensure at least one BaklaVue component is mounted, or call `loadBaklavaResources()` manually.
+2. **Wrong Vue version** — BaklaVue requires Vue 3.0+. Check with `npm list vue`.
+3. **Incorrect imports** — Use `BvButton`, not `Button`, and import from `@baklavue/ui`.
+
+### TypeScript errors
+
+1. **Module not found** — Ensure `@baklavue/ui` and `@baklavue/composables` are installed.
+2. **Type errors** — Use TypeScript 5.9.2+. Run `npm list typescript`.
+3. **Vue types** — If using Vite, include `"types": ["vite/client"]` in `tsconfig.json`.
+
+### Build errors
+
+1. **Peer dependency warnings** — Install `vue` and `typescript` at the versions above.
+2. **Version conflicts** — Try a clean install:
+
+   ```bash
+   rm -rf node_modules
+   rm package-lock.json  # or bun.lock, pnpm-lock.yaml
+   npm install
+   ```
+
+3. **Custom element errors** — Confirm `isCustomElement` is configured for your bundler.
+
+### SSR (Nuxt, etc.)
+
+BaklaVue components rely on Baklava web components, which are client-side. For SSR:
+
+- Use `<ClientOnly>` (or equivalent) around BaklaVue components that must not run on the server.
+- Or defer mounting until the client; the documentation site uses this approach.
+
+## Version Compatibility
+
+| BaklaVue | Vue | Baklava | Node |
+| -------- | --- | ------- | ---- |
+| 1.x      | ^3.5.21 | ^3.4.2 | 18+ |
+
+See the [GitHub releases](https://github.com/erbilnas/baklavue/releases) for specific version notes.
+
+## Next Steps
+
+- [Getting Started](/guide/getting-started) — First steps with BaklaVue
+- [Components](/components/) — Component catalog
+- [API Reference](/api/) — Full API docs

package/dist/docs/guide/localization.md

@@ -0,0 +1,132 @@
+# Localization
+
+Baklava (the underlying design system) has built-in localization support via [lit-localize](https://lit.dev/docs/localization/). It reads the `lang` attribute from the `<html>` element and uses a mutation observer to dynamically update localized components when the language changes. This includes components like Datepicker (month names, weekday labels) and Pagination (Previous/Next labels).
+
+## Setup
+
+Initialize localization by calling `init()` from Baklava's localization module in your app entry point (e.g., `main.ts` or `App.vue`):
+
+```typescript
+import { init } from "@trendyol/baklava/dist/localization.js";
+
+// Call before or when your app loads
+init();
+```
+
+If you load Baklava via CDN (as BaklaVue does by default), ensure the localization init runs after Baklava scripts have loaded. For example:
+
+```vue
+<script setup>
+import { onMounted } from "vue";
+import { loadBaklavaResources } from "@baklavue/ui";
+
+onMounted(async () => {
+  loadBaklavaResources();
+  // Wait for Baklava to load, then init localization
+  const { init } = await import(
+    "@trendyol/baklava/dist/localization.js"
+  );
+  await init();
+});
+</script>
+```
+
+## Setting the Locale
+
+Baklava reads the `lang` attribute from the root `<html>` element. To change the locale:
+
+**Option 1: Set in your HTML**
+
+```html
+<html lang="tr">
+```
+
+**Option 2: Set programmatically**
+
+```typescript
+document.documentElement.lang = "tr";
+```
+
+When `lang` changes, Baklava's mutation observer automatically updates all localized components. No page reload is required.
+
+## Supported Locales
+
+Baklava supports the following locales (see [Baklava translations](https://github.com/Trendyol/baklava/tree/next/translations)):
+
+| Code | Language  |
+| ---- | --------- |
+| `en` | English   |
+| `tr` | Turkish   |
+| `ar` | Arabic    |
+| `ro` | Romanian  |
+
+If no `lang` attribute is set, Baklava defaults to English.
+
+## Live Example
+
+Use the locale switcher below to see the Datepicker and Pagination update in real time. Notice how month names and weekday labels change when you switch from English to Turkish or Arabic.
+
+<div class="component-demo">
+
+<LocalizationDemo />
+
+</div>
+
+```vue
+<template>
+  <div>
+    <div class="locale-buttons">
+      <BvButton
+        v-for="loc in locales"
+        :key="loc.code"
+        :variant="currentLocale === loc.code ? 'primary' : 'secondary'"
+        size="small"
+        @click="setLocale(loc.code)"
+      >
+        {{ loc.label }}
+      </BvButton>
+    </div>
+    <BvDatepicker v-model="date" label="Select date" placeholder="Pick a date" />
+  </div>
+</template>
+
+<script setup>
+import { ref } from "vue";
+import { BvButton, BvDatepicker } from "@baklavue/ui";
+
+const date = ref("");
+const currentLocale = ref("en");
+
+const locales = [
+  { code: "en", label: "English" },
+  { code: "tr", label: "Türkçe" },
+  { code: "ar", label: "العربية" },
+  { code: "ro", label: "Română" },
+];
+
+function setLocale(code) {
+  document.documentElement.lang = code;
+  currentLocale.value = code;
+  // For Arabic, consider also: document.documentElement.dir = "rtl";
+}
+</script>
+```
+
+## RTL Support
+
+For Arabic (`ar`) and other right-to-left languages, set the `dir` attribute on the document for proper layout:
+
+```typescript
+document.documentElement.lang = "ar";
+document.documentElement.dir = "rtl";
+```
+
+Baklava has [built-in RTL support](https://baklava.design) using CSS logical properties. When switching back to LTR languages, reset `dir`:
+
+```typescript
+document.documentElement.dir = "ltr";
+```
+
+## Contributing Translations
+
+To add new translations or improve existing ones, submit a pull request to the [Baklava repository](https://github.com/Trendyol/baklava). Translations live in the [translations](https://github.com/Trendyol/baklava/tree/next/translations) folder.

package/dist/docs/guide/mcp.md

@@ -0,0 +1,141 @@
+# MCP (Model Context Protocol) Support
+
+Baklavue provides an MCP server that lets AI assistants (Cursor, Claude, Windsurf, etc.) access component documentation, composables, and usage examples directly. This helps AI tools generate accurate Baklavue code when you're building Vue applications.
+
+## What is MCP?
+
+[Model Context Protocol (MCP)](https://modelcontextprotocol.io) is a standardized protocol that enables AI assistants to access external data and tools. The Baklavue MCP server exposes structured data about components, composables, and documentation so AI tools can assist with Baklavue development.
+
+## Available Tools
+
+The Baklavue MCP server provides these tools:
+
+| Tool | Description |
+| ---- | ----------- |
+| `list_components` | List all Bv* components with category and basic info |
+| `get_component` | Full component docs: props, events, slots, types, usage examples |
+| `get_component_metadata` | Lightweight: props, events, slots only |
+| `list_composables` | List composables (useNotification, useTheme, etc.) |
+| `get_composable` | Composable API and usage documentation |
+| `search_components_by_category` | Filter by category (form, feedback, layout, etc.) |
+| `get_documentation_page` | Get guide pages (installation, getting-started, design-tokens) |
+| `list_documentation_pages` | List all available guide pages |
+
+## Low Budget: Run Locally (No Hosted Service)
+
+The Baklavue MCP server runs **entirely on your machine**—no cloud service, no API keys, no monthly fees. Your AI client (Cursor, Claude Desktop, etc.) spawns the server process locally and talks to it over stdin/stdout. This is the intended and free way to use it.
+
+**What you need:**
+- Bun or Node.js installed
+- Baklavue repo cloned locally, or `@baklavue/mcp` as a dependency
+
+**How it works:** When you open a project, your AI client runs `bun run mcp` (or `npx @baklavue/mcp`) and keeps that process alive. All data stays on your machine. No external servers are involved.
+
+**Quick start (local only):**
+
+1. Clone Baklavue or add `@baklavue/mcp` to your project.
+2. Add the MCP config to `.cursor/mcp.json` (see [Cursor setup](#cursor) below).
+3. Restart your AI client. The server runs on your machine when needed.
+
+**For teams:** Each developer runs the server locally from their own clone or from the published package. There is no central MCP host—everyone uses their own local process.
+
+---
+
+## Setup
+
+### Cursor
+
+1. The Baklavue repo includes a project-level MCP config at `.cursor/mcp.json`
+2. If you're using Baklavue in your own project, add to your `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "Baklavue": {
+      "command": "bun",
+      "args": ["run", "mcp"]
+    }
+  }
+}
+```
+
+Or when running from the Baklavue repo:
+
+```json
+{
+  "mcpServers": {
+    "Baklavue": {
+      "command": "bun",
+      "args": ["run", "--cwd", "packages/mcp", "start"]
+    }
+  }
+}
+```
+
+3. Restart Cursor to load the MCP server
+
+### Claude Desktop
+
+Add to your Claude config (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "baklavue": {
+      "command": "npx",
+      "args": ["@baklavue/mcp"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "Baklavue": {
+      "type": "stdio",
+      "command": "bun",
+      "args": ["run", "--cwd", "/path/to/baklavue", "mcp"]
+    }
+  }
+}
+```
+
+## Usage Examples
+
+Once configured, you can ask your AI assistant:
+
+- "List all Baklavue components"
+- "Get BvButton component documentation"
+- "What props does BvInput accept?"
+- "Find form-related components"
+- "Show me useNotification composable usage"
+- "Get installation guide"
+
+The AI will use the MCP server to fetch structured data and provide accurate Baklavue code and guidance.
+
+## Running Locally
+
+The MCP server communicates over stdio and is designed to be spawned by your AI client. You can also run it manually for testing:
+
+```bash
+# From repo root
+bun run mcp
+
+# Or from packages/mcp
+cd packages/mcp && bun run start
+```
+
+No HTTP server or port is required—everything runs over stdin/stdout on your machine. See [Low Budget: Run Locally](#low-budget-run-locally-no-hosted-service) for the full setup.
+
+## Package
+
+The MCP server lives in `packages/mcp`. When published, it will be available as `@baklavue/mcp`:
+
+```bash
+npx @baklavue/mcp
+```

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};