@raclettejs/core 0.0.1

package/services/frontend/vite-plugin-component-path.ts

@@ -0,0 +1,162 @@
+import { chadsay } from "./src/core/lib/eggs/chadsay"
+import type { Plugin } from "vite"
+
+export const componentPathPlugin = (): Plugin => {
+  const VIRTUAL_PLUGIN_MODULE = "virtual:plugin-key"
+  const VIRTUAL_SETUP_MODULE = "virtual:plugin-setup"
+
+  const resolvedPluginModuleId = "\0" + VIRTUAL_PLUGIN_MODULE
+  const resolvedSetupModuleId = "\0" + VIRTUAL_SETUP_MODULE
+
+  // Cache for path resolution
+  let pluginPathMappingModule: string | null = null
+
+  return {
+    name: "vite-plugin-component-path",
+    enforce: "pre", // Run before Vue compilation
+
+    configResolved(config) {
+      // We can use this hook to log debug info when Vite starts
+      console.log("[componentPathPlugin] Plugin initialized")
+      console.log("[componentPathPlugin] Vite mode:", config.mode)
+      console.log("[componentPathPlugin] Vite root:", config.root)
+      console.log(chadsay("Be aware of hot Cheese!"))
+    },
+
+    resolveId: (id) => {
+      if (id === VIRTUAL_PLUGIN_MODULE) {
+        return resolvedPluginModuleId
+      }
+      if (id === VIRTUAL_SETUP_MODULE) {
+        return resolvedSetupModuleId
+      }
+    },
+
+    load: (id) => {
+      // Plugin key management module
+      if (id === resolvedPluginModuleId) {
+        return `
+          const pluginKeyMap = new Map();
+          
+          export function definePluginKey(key, instanceId) {
+            console.debug("[componentPathPlugin] Defining plugin key:", key, "for instance:", instanceId);
+            pluginKeyMap.set(instanceId, key);
+          }
+          
+          export function getCurrentPluginKey(instanceId) {
+            const key = pluginKeyMap.get(instanceId);
+            console.debug("[componentPathPlugin] Getting plugin key for instance:", instanceId, "result:", key);
+            return key;
+          }
+          
+          export function cleanupPluginKey(instanceId) {
+            console.debug("[componentPathPlugin] Cleaning up plugin key for instance:", instanceId);
+            pluginKeyMap.delete(instanceId);
+          }
+        `
+      }
+
+      // Setup module (pre-imports Vue dependencies)
+      if (id === resolvedSetupModuleId) {
+        return `
+          import { getCurrentInstance, onUnmounted } from 'vue';
+          import { definePluginKey, cleanupPluginKey } from 'virtual:plugin-key';
+          import { pluginPathMapping } from '@racletteCore/setup/plugin-system';
+          
+          export function usePluginSetup(filePath, fallbackPluginKey) {
+            const instance = getCurrentInstance();
+            if (!instance) {
+              console.error('Plugin setup must be called within component setup');
+              return;
+            }
+
+            // Try to resolve plugin key from path mapping
+            let pluginKey = null;
+            
+            // Find the matching path prefix in the mapping
+            for (const [pathPrefix, identifier] of Object.entries(pluginPathMapping)) {
+              if (filePath.includes(pathPrefix)) {
+                pluginKey = identifier;
+                break;
+              }
+            }
+            
+            // Use fallback if no match found
+            if (!pluginKey && fallbackPluginKey) {
+              pluginKey = fallbackPluginKey;
+            }
+            
+            if (!pluginKey) {
+              // this is expected for all widgets that are not coming from plugins
+              // console.warn(\`[componentPathPlugin] Could not determine plugin key for \${filePath}\`);
+              return;
+            }
+
+            definePluginKey(pluginKey, instance.uid);
+            
+            onUnmounted(() => {
+              cleanupPluginKey(instance.uid);
+            });
+          }
+        `
+      }
+    },
+
+    transform: (code, id) => {
+      // Only transform .vue files that might be in a plugin
+      if (id.endsWith(".vue")) {
+        // Use normalized path for consistent matching
+        const normalizedPath = id.replace(/\\/g, "/")
+
+        // Import for setup
+        const setupImport = `import { usePluginSetup } from 'virtual:plugin-setup';`
+
+        const scriptSetupMatch = code.match(
+          /<script\s+(?=.*\bsetup\b)(?=.*\blang=["']ts["'])?[^>]*>/,
+        )
+
+        // Check if we have <script setup>
+        // Add to existing <script setup>
+        if (scriptSetupMatch) {
+          const insertIndex =
+            scriptSetupMatch.index + scriptSetupMatch[0].length
+
+          // TODO: support options api in the future
+          return (
+            code.slice(0, insertIndex) +
+            `\n${setupImport}\nusePluginSetup('${normalizedPath}');\n` +
+            code.slice(insertIndex)
+          )
+        }
+        // Add new <script setup> block before any existing script
+
+        const scriptSetup = `<script setup>\n${setupImport}\nusePluginSetup('${normalizedPath}');\n</script>\n\n`
+        // Find existing script tag or insert at start
+        const existingScript = code.match(/<script.*?>/)
+
+        if (existingScript) {
+          return (
+            code.slice(0, existingScript.index) +
+            scriptSetup +
+            code.slice(existingScript.index)
+          )
+        }
+
+        return scriptSetup + code
+      }
+
+      return code
+    },
+
+    // Add a custom handler for HMR to help with debugging
+    handleHotUpdate({ file, modules }) {
+      // This is helpful for debugging when components are updated
+      // if (file.endsWith(".vue")) {
+      //   console.log("[componentPathPlugin] File updated:", file)
+      // }
+
+      // Don't intercept the update - let Vite handle it normally
+      return modules
+    },
+  }
+}

package/services/frontend/vite.config.ts

@@ -0,0 +1,58 @@
+import { defineConfig } from "vite"
+import vue from "@vitejs/plugin-vue"
+import path from "path"
+import { componentPathPlugin } from "./vite-plugin-component-path"
+import tailwindcss from "@tailwindcss/vite"
+
+export default defineConfig({
+  server: {
+    port: 8081,
+  },
+  preview: {
+    port: 8081,
+  },
+  envPrefix: "RACLETTE_",
+  build: {
+    chunkSizeWarningLimit: 1000,
+    target: "es2023",
+    rollupOptions: {
+      output: {
+        manualChunks: {
+          "vue-vendor": ["vue", "vue-router"],
+          vuetify: ["vuetify"],
+          // login: [
+          //   "@racletteOrchestrator/LoginApp.vue",
+          //   "@racletteOrchestrator/setup/loginApp.ts",
+          // ],
+        },
+      },
+      maxParallelFileOps: 1,
+    },
+  },
+  optimizeDeps: {
+    include: ["vue", "vue-router", "vuetify"],
+    exclude: [
+      "virtual:plugin-key",
+      "virtual:plugin-setup",
+      "@racletteOrchestrator/composables/usePluginApi",
+    ],
+  },
+  plugins: [vue(), componentPathPlugin(), tailwindcss()],
+  resolve: {
+    extensions: [".js", ".ts", ".vue"],
+    alias: {
+      "@app": path.resolve(__dirname, "./src/app"), // plugin import
+      "@raclettejs/core/frontend": path.resolve(__dirname, "./src/core"), // plugin import
+      "@raclettejs/core/orchestrator": path.resolve(
+        __dirname,
+        "./src/orchestrator",
+      ), // plugin import
+      "@raclettejs/workbench/app": path.resolve(__dirname, "./src/app"), // plugin import
+      "@raclettejs/workbench": path.resolve(__dirname, "./src"), // plugin import
+      "@raclettejs/core": path.resolve(__dirname, "./types"), // type import only
+      "@racletteOrchestrator": path.resolve(__dirname, "./src/orchestrator"), // internal core import
+      "@racletteCore": path.resolve(__dirname, "./src/core"), // internal core import
+      "@shared": path.resolve(__dirname, "./src/shared"), // plugin import
+    },
+  },
+})

package/services/frontend/vue3-component-style-guide.md

@@ -0,0 +1,350 @@
+# Vue 3 Component Style Guide - Composition API
+
+## Component Structure
+
+Components should be structured in the following order:
+
+1. `<template>`
+2. `<script setup>`
+3. `<style>`
+
+## Order of Properties in `<script setup>`
+
+1. **Type Imports** (if using TypeScript)
+
+   ```ts
+   import type { PropType } from "vue"
+   import type { MyInterface } from "@/types"
+   ```
+
+2. **Component Imports**
+
+   ```ts
+   import { ref, computed, onMounted } from "vue"
+   import BaseButton from "@/components/BaseButton.vue"
+   ```
+
+3. **Composable Imports**
+
+   ```ts
+   import { useRouter } from "vue-router"
+   import { useStore } from "vuex"
+   import { useMyComposable } from "@/composables/useMyComposable"
+   ```
+
+4. **Constants and Utilities**
+
+   ```ts
+   const ITEMS_PER_PAGE = 10
+   const DEFAULT_THEME = "light"
+   ```
+
+5. **Component Options**
+
+   ```ts
+   // Props
+   const props = defineProps<{
+     title: string
+     items?: string[]
+     callback?: (id: number) => void
+   }>()
+
+   // Emits
+   const emit = defineEmits<{
+     "update:selected": [value: string]
+     submit: [payload: { id: number; data: string }]
+   }>()
+
+   // Model
+   const model = defineModel<string>({
+     required: true,
+     default: "",
+   })
+
+   // Expose (when needed)
+   defineExpose({
+     reset,
+     validate,
+   })
+   ```
+
+6. **Dependency Injection**
+
+   ```ts
+   // Provide
+   provide("key", value)
+
+   // Inject
+   const injectedValue = inject("key")
+   const injectedWithDefault = inject("key", defaultValue)
+   ```
+
+7. **Composable Usage**
+
+   ```ts
+   const router = useRouter()
+   const store = useStore()
+   const { data, loading } = useMyComposable()
+   ```
+
+8. **Local State**
+
+   ```ts
+   // Refs
+   const count = ref(0)
+   const name = ref("")
+
+   // Reactive objects
+   const form = reactive({
+     username: "",
+     password: "",
+   })
+   ```
+
+9. **Computed Properties**
+
+   ```ts
+   const doubleCount = computed(() => count.value * 2)
+   const isValid = computed(() => {
+     return form.username && form.password.length >= 8
+   })
+   ```
+
+10. **Methods**
+
+    ```ts
+    // Event handlers
+    const handleClick = () => {
+      count.value++
+    }
+
+    // Business logic
+    const calculateTotal = () => {
+      // calculation logic
+    }
+
+    // Async methods
+    const fetchData = async () => {
+      try {
+        const response = await api.get("/data")
+        // handle response
+      } catch (error) {
+        // handle error
+      }
+    }
+    ```
+
+11. **Watchers**
+
+    ```ts
+    // Simple watch
+    watch(count, (newVal, oldVal) => {
+      console.log(`Count changed from ${oldVal} to ${newVal}`)
+    })
+
+    // Watch with options
+    watch(
+      () => props.title,
+      (newVal) => {
+        // handle change
+      },
+      { immediate: true, deep: true },
+    )
+
+    // watchEffect
+    watchEffect(() => {
+      // reactive effect
+    })
+    ```
+
+12. **Lifecycle Hooks**
+
+    ```ts
+    onBeforeMount(() => {
+      // before mount logic
+    })
+
+    onMounted(() => {
+      // mounted logic
+    })
+
+    onBeforeUnmount(() => {
+      // cleanup logic
+    })
+    ```
+
+## Complete Example
+
+```vue
+<template>
+  <div class="users-list">
+    <input v-model="searchQuery" placeholder="Search users..." />
+
+    <div v-if="isLoading" class="loading">Loading...</div>
+
+    <ul v-else>
+      <li
+        v-for="user in paginatedUsers"
+        :key="user.id"
+        @click="handleUserClick(user)"
+      >
+        {{ user.name }}
+      </li>
+    </ul>
+
+    <BaseButton @click="currentPage++"> Next Page </BaseButton>
+  </div>
+</template>
+
+<script setup lang="ts">
+// Type imports
+import type { PropType } from "vue"
+import type { User } from "@/types"
+
+// Component imports
+import {
+  ref,
+  computed,
+  watch,
+  onMounted,
+  provide,
+  inject,
+  defineModel,
+} from "vue"
+import BaseButton from "@/components/BaseButton.vue"
+
+// Composable imports
+import { useRouter } from "vue-router"
+import { useUserStore } from "@/stores/user"
+
+// Constants
+const PAGINATION_LIMIT = 10
+const THEME_KEY = "app-theme"
+
+// Props
+const props = defineProps<{
+  users: User[]
+  initialPage?: number
+}>()
+
+// Emits
+const emit = defineEmits<{
+  "update:page": [page: number]
+  "user-selected": [user: User]
+}>()
+
+// Model
+const searchQuery = defineModel<string>("search", {
+  default: "",
+})
+
+// Provide/Inject
+provide("theme", THEME_KEY)
+const parentTheme = inject("parent-theme", "light")
+
+// Composables
+const router = useRouter()
+const userStore = useUserStore()
+
+// State
+const currentPage = ref(props.initialPage ?? 1)
+const isLoading = ref(false)
+
+// Computed
+const filteredUsers = computed(() => {
+  return props.users.filter((user) =>
+    user.name.toLowerCase().includes(searchQuery.value.toLowerCase()),
+  )
+})
+
+const paginatedUsers = computed(() => {
+  const start = (currentPage.value - 1) * PAGINATION_LIMIT
+  return filteredUsers.value.slice(start, start + PAGINATION_LIMIT)
+})
+
+// Methods
+const handleUserClick = (user: User) => {
+  emit("user-selected", user)
+}
+
+const fetchUserDetails = async (userId: number) => {
+  isLoading.value = true
+  try {
+    await userStore.fetchUserDetails(userId)
+  } finally {
+    isLoading.value = false
+  }
+}
+
+// Watchers
+watch(currentPage, (newPage) => {
+  emit("update:page", newPage)
+  router.push({ query: { page: newPage.toString() } })
+})
+
+watchEffect(() => {
+  document.title = `Users (${filteredUsers.value.length})`
+})
+
+// Lifecycle Hooks
+onMounted(() => {
+  fetchUserDetails(props.users[0].id)
+})
+</script>
+
+<style scoped>
+.users-list {
+  padding: 1rem;
+}
+
+.loading {
+  color: #666;
+}
+</style>
+```
+
+## Additional Best Practices
+
+1. **Type Safety**
+   - Use TypeScript whenever possible
+   - Define proper interfaces/types for props and events
+   - Use type inference where appropriate
+
+2. **Naming Conventions**
+   - Use PascalCase for component names
+   - Use camelCase for ref/reactive variables
+   - Prefix boolean variables with `is`, `has`, or `should`
+   - Prefix event handlers with `handle` or `on`
+
+3. **File Organization**
+   - One component per file
+   - Use meaningful file names that match component names
+   - Group related components in subdirectories
+
+4. **Props**
+   - Always define prop types
+   - Use required props when necessary
+   - Provide default values when appropriate
+   - Document complex props with comments
+
+5. **Events**
+   - Use kebab-case for event names
+   - Prefix v-model events with 'update:'
+   - Document event payloads with TypeScript types
+
+6. **Performance**
+   - Use `shallowRef` for large objects when deep reactivity isn't needed
+   - Use `computed` properties instead of methods for derived state
+   - Avoid unnecessary watchers
+   - Use `v-once` for static content
+
+7. **Error Handling**
+   - Always handle async errors
+   - Provide meaningful error states in the UI
+   - Use error boundaries where appropriate
+
+8. **Testing**
+   - Write unit tests for complex computed properties
+   - Test component events and user interactions
+   - Mock external dependencies
+   - Test error states and edge cases