@equal-experts/kuat-vue 0.1.4 → 0.2.0

package/README.md

@@ -0,0 +1,461 @@
+# @equal-experts/kuat-vue
+
+A guide for integrating the Kuat Design System Vue component library into your application.
+
+---
+
+## Installation
+
+### Prerequisites
+
+- Vue 3.4.0 or higher
+- Node.js 18 or higher
+- A package manager (npm, pnpm, or yarn)
+
+### Install the Package
+
+```bash
+# Using pnpm (recommended)
+pnpm add @equal-experts/kuat-vue
+
+# Using npm
+npm install @equal-experts/kuat-vue
+
+# Using yarn
+yarn add @equal-experts/kuat-vue
+```
+
+### Install Peer Dependencies
+
+The library requires Vue, Radix Vue, and Reka UI as peer dependencies:
+
+```bash
+# Required peer dependencies
+pnpm add vue radix-vue reka-ui
+
+# Optional: Install lucide-vue-next for icons (or use your preferred icon library)
+pnpm add lucide-vue-next
+```
+
+**Note:** `@equal-experts/kuat-core` is bundled with this package - you don't need to install it separately.
+
+---
+
+## Setup
+
+### 1. Configure Tailwind CSS
+
+The Kuat Design System uses Tailwind CSS v4. You'll need to configure Tailwind in your project.
+
+#### Install Tailwind CSS v4
+
+```bash
+pnpm add -D tailwindcss@next @tailwindcss/vite
+```
+
+#### Create `tailwind.config.ts`
+
+```typescript
+import type { Config } from "tailwindcss";
+
+const config: Config = {
+  content: [
+    "./src/**/*.{js,ts,jsx,tsx,vue}",
+    "./node_modules/@equal-experts/kuat-vue/**/*.{js,ts,vue}", // Include Kuat components
+  ],
+  theme: {
+    extend: {
+      colors: {
+        background: "var(--background)",
+        foreground: "var(--foreground)",
+        primary: {
+          DEFAULT: "var(--primary)",
+          foreground: "var(--primary-foreground)",
+        },
+        secondary: {
+          DEFAULT: "var(--secondary)",
+          foreground: "var(--secondary-foreground)",
+        },
+        // ... other color tokens from @equal-experts/kuat-core
+      },
+      borderRadius: {
+        lg: "var(--radius)",
+        md: "calc(var(--radius) - 2px)",
+        sm: "calc(var(--radius) - 4px)",
+      },
+      fontFamily: {
+        sans: ["var(--font-sans)"],
+        serif: ["var(--font-serif)"],
+        mono: ["var(--font-mono)"],
+      },
+    },
+  },
+  plugins: [],
+};
+
+export default config;
+```
+
+#### Configure Vite (if using Vite)
+
+```typescript
+// vite.config.ts
+import { defineConfig } from "vite";
+import vue from "@vitejs/plugin-vue";
+import tailwindcss from "@tailwindcss/vite";
+
+export default defineConfig({
+  plugins: [vue(), tailwindcss()],
+});
+```
+
+### 2. Import Styles
+
+Import the Kuat Design System styles in your application's entry point:
+
+```typescript
+// main.ts
+import { createApp } from "vue";
+import App from "./App.vue";
+import "@equal-experts/kuat-vue/styles";
+
+createApp(App).mount("#app");
+```
+
+This imports the bundled CSS file which includes all design tokens from `@equal-experts/kuat-core` (no need to install `@equal-experts/kuat-core` separately).
+
+**Note:** The styles include:
+- Design tokens from `@equal-experts/kuat-core` (colors, spacing, typography)
+- Tailwind CSS base styles
+- Component-specific styles
+
+### 3. (Optional) Configure Fonts
+
+The Kuat Design System uses Lexend (sans-serif), Lora (serif), and JetBrains Mono (monospace) fonts. These are loaded via Google Fonts in the core package.
+
+If you want to use different fonts or load them differently, you can override the CSS variables:
+
+```css
+:root {
+  --font-sans: 'Your Sans Font', sans-serif;
+  --font-serif: 'Your Serif Font', serif;
+  --font-mono: 'Your Mono Font', monospace;
+}
+```
+
+---
+
+## Basic Usage
+
+### Import Components
+
+```typescript
+import { Button } from "@equal-experts/kuat-vue";
+```
+
+### Use in Your App
+
+```vue
+<template>
+  <div>
+    <Button>Click me</Button>
+    <Button variant="outline">Outline button</Button>
+    <Button variant="destructive">Delete</Button>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { Button } from "@equal-experts/kuat-vue";
+</script>
+```
+
+---
+
+## Component Examples
+
+### Button
+
+The Button component supports multiple variants and sizes:
+
+```vue
+<template>
+  <div class="space-x-4">
+    <!-- Variants -->
+    <Button variant="default">Default</Button>
+    <Button variant="destructive">Destructive</Button>
+    <Button variant="outline">Outline</Button>
+    <Button variant="secondary">Secondary</Button>
+    <Button variant="ghost">Ghost</Button>
+    <Button variant="link">Link</Button>
+
+    <!-- Sizes -->
+    <Button size="sm">Small</Button>
+    <Button size="default">Default</Button>
+    <Button size="lg">Large</Button>
+    <Button size="icon">🚀</Button>
+    <Button size="icon-sm">📱</Button>
+    <Button size="icon-lg">💻</Button>
+
+    <!-- With click handler -->
+    <Button @click="handleClick">
+      Click me
+    </Button>
+
+    <!-- Disabled -->
+    <Button disabled>Disabled</Button>
+
+    <!-- As child (for composition) -->
+    <Button as-child>
+      <a href="/link">Link Button</a>
+    </Button>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { Button } from "@equal-experts/kuat-vue";
+
+function handleClick() {
+  alert("Clicked!");
+}
+</script>
+```
+
+### TypeScript Support
+
+All components are fully typed:
+
+```vue
+<script setup lang="ts">
+import { Button, type ButtonVariants } from "@equal-experts/kuat-vue";
+
+const variant: ButtonVariants["variant"] = "outline";
+const size: ButtonVariants["size"] = "lg";
+</script>
+
+<template>
+  <Button :variant="variant" :size="size">
+    Typed Button
+  </Button>
+</template>
+```
+
+---
+
+## Styling and Theming
+
+### Using Design Tokens
+
+The Kuat Design System provides CSS variables for all design tokens. Use them in your custom components:
+
+```vue
+<template>
+  <div class="custom-component">
+    Custom styled component
+  </div>
+</template>
+
+<style scoped>
+.custom-component {
+  background-color: var(--background);
+  color: var(--foreground);
+  padding: var(--spacing);
+  border-color: var(--border);
+  border-radius: var(--radius);
+}
+</style>
+```
+
+Or with Tailwind classes:
+
+```vue
+<template>
+  <div class="bg-background text-foreground p-4 rounded-lg border border-border">
+    Custom styled component
+  </div>
+</template>
+```
+
+### Dark Mode
+
+Dark mode is supported via the `.dark` class. Apply it to your root element:
+
+```vue
+<!-- In your root component -->
+<template>
+  <div :class="{ dark: isDark }">
+    <App />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+
+const isDark = ref(false);
+</script>
+```
+
+Or toggle dynamically:
+
+```vue
+<template>
+  <div :class="{ dark: isDark }">
+    <button @click="isDark = !isDark">
+      Toggle theme
+    </button>
+    <!-- Your app -->
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+
+const isDark = ref(false);
+</script>
+```
+
+### Customizing Colors
+
+Override CSS variables to customize the theme:
+
+```css
+/* In your global CSS file */
+:root {
+  --primary: oklch(0.645 0.163 237.5); /* Your primary color */
+  --primary-foreground: oklch(1.0 0.0 0.0); /* White */
+}
+
+.dark {
+  --primary: oklch(0.585 0.145 237.5); /* Darker primary for dark mode */
+  --primary-foreground: oklch(1.0 0.0 0.0); /* White */
+}
+```
+
+---
+
+## Advanced Usage
+
+### Composing Components
+
+Use the `as-child` prop to compose components:
+
+```vue
+<template>
+  <Button as-child variant="ghost">
+    <router-link to="/dashboard">Dashboard</router-link>
+  </Button>
+</template>
+
+<script setup lang="ts">
+import { Button } from "@equal-experts/kuat-vue";
+</script>
+```
+
+### Using Variants Programmatically
+
+Import and use variant functions:
+
+```vue
+<template>
+  <button :class="buttonClass">
+    Custom Button
+  </button>
+</template>
+
+<script setup lang="ts">
+import { buttonVariants } from "@equal-experts/kuat-vue";
+import { cn } from "@equal-experts/kuat-vue";
+
+const buttonClass = cn(
+  buttonVariants({ variant: "outline", size: "lg" }),
+  "custom-class"
+);
+</script>
+```
+
+### Global Component Registration
+
+Register components globally if preferred:
+
+```typescript
+// main.ts
+import { createApp } from "vue";
+import App from "./App.vue";
+import * as KuatComponents from "@equal-experts/kuat-vue";
+
+const app = createApp(App);
+
+// Register all components globally
+Object.entries(KuatComponents).forEach(([name, component]) => {
+  if (name !== "default" && typeof component === "object") {
+    app.component(name, component);
+  }
+});
+
+app.mount("#app");
+```
+
+Then use without importing:
+
+```vue
+<template>
+  <Button>No import needed</Button>
+</template>
+```
+
+---
+
+## Troubleshooting
+
+### Styles Not Loading
+
+1. **Check import order**: Ensure you import `@equal-experts/kuat-vue/styles` before your own styles
+2. **Verify Tailwind config**: Make sure `@equal-experts/kuat-vue` is included in your `content` paths
+3. **Check build output**: Ensure the CSS file is being included in your build
+4. **Vue SFC**: If using Single File Components, ensure styles are processed correctly
+
+### TypeScript Errors
+
+1. **Install types**: Ensure Vue TypeScript support is configured
+2. **Check TypeScript version**: Requires TypeScript 5.3 or higher
+3. **Verify imports**: Use named imports, not default imports
+4. **Vue TSConfig**: Ensure your `tsconfig.json` includes Vue file types
+
+### Components Not Rendering
+
+1. **Check Vue version**: Requires Vue 3.4.0 or higher
+2. **Verify peer dependencies**: Ensure `vue` is installed
+3. **Check console**: Look for runtime errors in the browser console
+4. **Build mode**: Ensure you're using the correct build mode (ES modules)
+
+---
+
+## Package Structure
+
+```
+@equal-experts/kuat-vue
+├── dist/
+│   ├── index.js          # Compiled JavaScript
+│   ├── index.d.ts        # TypeScript definitions
+│   └── index.css         # Compiled styles
+└── src/
+    ├── components/       # Component source files
+    ├── lib/             # Utilities
+    └── styles.css        # Style source
+```
+
+---
+
+## Additional Resources
+
+- **Design System Documentation**: See [../../docs/agent/design/design-system.md](../../docs/agent/design/design-system.md)
+- **Component Guidelines**: See [../../docs/agent/technical/component-guidelines.md](../../docs/agent/technical/component-guidelines.md)
+- **shadcn-vue Documentation**: [https://www.shadcn-vue.com](https://www.shadcn-vue.com)
+- **Tailwind CSS v4**: [https://tailwindcss.com](https://tailwindcss.com)
+- **Vue 3 Documentation**: [https://vuejs.org](https://vuejs.org)
+
+---
+
+## Support
+
+For issues, questions, or contributions, please refer to the main repository documentation or open an issue in the project repository.
+

package/dist/components/ui/button/Button.vue.d.ts

@@ -0,0 +1,43 @@
+import { PrimitiveProps } from 'reka-ui';
+import { HTMLAttributes } from 'vue';
+import { ButtonVariants } from '.';
+
+interface Props extends PrimitiveProps {
+    variant?: ButtonVariants["variant"];
+    size?: ButtonVariants["size"];
+    class?: HTMLAttributes["class"];
+}
+declare function __VLS_template(): {
+    default?(_: {}): any;
+};
+declare const __VLS_component: import('vue').DefineComponent<import('vue').ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<Props>, {
+    as: string;
+}>>, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<Props>, {
+    as: string;
+}>>> & Readonly<{}>, {
+    as: import('reka-ui').AsTag | import('vue').Component;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, ReturnType<typeof __VLS_template>>;
+export default _default;
+type __VLS_NonUndefinedable<T> = T extends undefined ? never : T;
+type __VLS_TypePropsToRuntimeProps<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? {
+        type: import('vue').PropType<__VLS_NonUndefinedable<T[K]>>;
+    } : {
+        type: import('vue').PropType<T[K]>;
+        required: true;
+    };
+};
+type __VLS_WithDefaults<P, D> = {
+    [K in keyof Pick<P, keyof P>]: K extends keyof D ? __VLS_Prettify<P[K] & {
+        default: D[K];
+    }> : P[K];
+};
+type __VLS_Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/ui/button/index.d.ts

@@ -0,0 +1,8 @@
+import { VariantProps } from 'class-variance-authority';
+
+export { default as Button } from './Button.vue';
+export declare const buttonVariants: (props?: ({
+    variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link" | null | undefined;
+    size?: "default" | "sm" | "lg" | "icon" | "icon-sm" | "icon-lg" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+export type ButtonVariants = VariantProps<typeof buttonVariants>;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { cn } from './lib/utils';
+export { Button, buttonVariants } from './components/ui/button';
+export type { ButtonVariants } from './components/ui/button';