dzql 0.5.33 → 0.6.0

package/docs/reference/client.md

@@ -1,224 +0,0 @@
-# DZQL Client Quick Start
-
-**TL;DR:** Copy-paste guide to get a DZQL Vue.js app running in minutes.
-
-## 1. Install
-
-```bash
-npm install dzql pinia vue-router
-```
-
-## 2. Copy Template
-
-Copy the canonical App.vue template:
-```bash
-cp node_modules/dzql/src/client/templates/App.vue src/App.vue
-```
-
-Or create it manually:
-
-**src/App.vue:**
-```vue
-<script setup>
-import { computed, onMounted } from 'vue'
-import { useWsStore, useAppStore } from 'dzql/client/stores'
-import LoginView from './components/LoginView.vue'
-
-const wsStore = useWsStore()
-const appStore = useAppStore()
-const state = computed(() => wsStore.appState)
-const profile = computed(() => wsStore.profile)
-
-onMounted(() => {
-  appStore.initialize({ title: 'My App' })
-})
-</script>
-
-<template>
-  <!-- CONNECTING -->
-  <div v-if="state === 'connecting'">Connecting...</div>
-  
-  <!-- LOGIN -->
-  <LoginView v-else-if="state === 'login'" />
-  
-  <!-- READY -->
-  <div v-else>
-    <nav>
-      <h1>{{ appStore.title }}</h1>
-      <button @click="wsStore.logout()">Logout</button>
-    </nav>
-    <router-view />
-  </div>
-</template>
-```
-
-## 3. Create LoginView
-
-**src/components/LoginView.vue:**
-```vue
-<script setup>
-import { ref } from 'vue'
-import { useWsStore } from 'dzql/client/stores'
-
-const wsStore = useWsStore()
-const email = ref('')
-const password = ref('')
-
-async function login() {
-  try {
-    await wsStore.login({ email: email.value, password: password.value })
-  } catch (err) {
-    alert(err.message)
-  }
-}
-</script>
-
-<template>
-  <form @submit.prevent="login">
-    <input v-model="email" type="email" placeholder="Email" required />
-    <input v-model="password" type="password" placeholder="Password" required />
-    <button type="submit">Login</button>
-  </form>
-</template>
-```
-
-**Registration with options (e.g., organisation name):**
-```vue
-<script setup>
-import { ref } from 'vue'
-import { useWsStore } from 'dzql/client/stores'
-
-const wsStore = useWsStore()
-const email = ref('')
-const password = ref('')
-const orgName = ref('')
-
-async function register() {
-  try {
-    await wsStore.register({
-      email: email.value,
-      password: password.value,
-      options: { org_name: orgName.value }
-    })
-  } catch (err) {
-    alert(err.message)
-  }
-}
-</script>
-
-<template>
-  <form @submit.prevent="register">
-    <input v-model="email" type="email" placeholder="Email" required />
-    <input v-model="password" type="password" placeholder="Password" required />
-    <input v-model="orgName" type="text" placeholder="Organisation Name" />
-    <button type="submit">Register</button>
-  </form>
-</template>
-```
-
-The `options` parameter allows passing additional JSONB data to the `register_user` and `login_user` PostgreSQL functions. This is useful for:
-- Organisation name during registration
-- Device ID for login tracking
-- Any custom fields your auth functions support
-
-See [API Reference - Authentication](./api.md#authentication) for details on configuring your PostgreSQL functions.
-
-## 4. Setup main.js
-
-**src/main.js:**
-```javascript
-import { createApp } from 'vue'
-import { createRouter, createWebHashHistory } from 'vue-router'
-import { createPinia } from 'pinia'
-import { useAppStore } from 'dzql/client/stores'
-import App from './App.vue'
-
-const pinia = createPinia()
-
-const router = createRouter({
-  history: createWebHashHistory(),
-  routes: [
-    { path: '/', name: 'home', component: () => import('./views/Home.vue') },
-    { path: '/:entity', name: 'entity-list', component: () => import('./views/EntityList.vue') },
-    { path: '/:entity/:id', name: 'entity-detail', component: () => import('./views/EntityDetail.vue') }
-  ]
-})
-
-const app = createApp(App)
-app.use(pinia)
-app.use(router)
-
-const appStore = useAppStore()
-appStore.setRouter(router)
-
-app.mount('#app')
-```
-
-## 5. Use DZQL API
-
-**Any component:**
-```vue
-<script setup>
-import { ref, onMounted } from 'vue'
-import { useWsStore } from 'dzql/client/stores'
-
-const wsStore = useWsStore()
-const ws = wsStore.getWs()
-const venues = ref([])
-
-onMounted(async () => {
-  const result = await ws.api.search.venues({ limit: 50 })
-  venues.value = result.data
-})
-
-async function createVenue() {
-  await ws.api.save.venues({ name: 'New Venue' })
-}
-</script>
-
-<template>
-  <div v-for="venue in venues" :key="venue.id">
-    {{ venue.name }}
-  </div>
-  <button @click="createVenue">Create</button>
-</template>
-```
-
-## That's It! 🎉
-
-You now have:
-- ✅ WebSocket connection with auto-reconnect
-- ✅ Three-phase lifecycle (connecting → login → ready)
-- ✅ Authentication (login/logout)
-- ✅ Router integration
-- ✅ DZQL API access
-
-## Next Steps
-
-- Read [Client Stores Guide](../guides/client-stores.md) for complete API reference
-- Customize the App.vue template
-- Add your own components
-- Style with Tailwind/DaisyUI
-
-## Common Issues
-
-**"Cannot find module 'dzql/client/stores'"**
-- Make sure you're using dzql v0.1.6 or later
-- Run `npm install dzql@latest`
-
-**Connection fails**
-- Check server is running
-- For dev, use explicit URL: `appStore.initialize({ wsUrl: 'ws://localhost:3000/ws' })`
-
-**Router not working**
-- Make sure you call `appStore.setRouter(router)` in main.js
-
-## Example Projects
-
-Check `packages/client` for a complete working example.
-
-## Help
-
-For more help, see:
-- [Client Stores Guide](../guides/client-stores.md) - Complete documentation
-- [GitHub Issues](https://github.com/blueshed/dzql/issues)

package/src/client/stores/index.js

@@ -1,8 +0,0 @@
-/**
- * DZQL Client Stores
- *
- * Canonical Pinia stores for DZQL applications
- */
-
-export { useWsStore } from './useWsStore.js'
-export { useAppStore } from './useAppStore.js'

package/src/client/stores/useAppStore.js

@@ -1,285 +0,0 @@
-/**
- * Canonical DZQL App Pinia Store
- *
- * Manages application-level state including:
- * - App initialization
- * - Router integration
- * - Global UI state
- * - Entity metadata caching
- *
- * Works with useWsStore to provide complete app lifecycle management.
- *
- * @example
- * // In main.js
- * import { createApp } from 'vue'
- * import { createPinia } from 'pinia'
- * import { useAppStore } from 'dzql/client/stores'
- * import App from './App.vue'
- *
- * const pinia = createPinia()
- * const app = createApp(App)
- * app.use(pinia)
- *
- * const appStore = useAppStore()
- * await appStore.initialize()
- *
- * app.mount('#app')
- */
-import { defineStore } from 'pinia'
-import { ref, computed } from 'vue'
-import { useWsStore } from './useWsStore.js'
-
-export const useAppStore = defineStore('dzql-app', () => {
-  // ===== State =====
-
-  /**
-   * App title
-   */
-  const title = ref('DZQL App')
-
-  /**
-   * Current route/entity context
-   */
-  const currentEntity = ref(null)
-  const currentId = ref(null)
-
-  /**
-   * Entity metadata cache
-   * Maps entity name -> metadata object
-   */
-  const entityMetadata = ref({})
-
-  /**
-   * Loading states
-   */
-  const isLoadingMetadata = ref(false)
-
-  /**
-   * UI state
-   */
-  const sidebarOpen = ref(true)
-  const propertiesPanelOpen = ref(true)
-
-  /**
-   * Router instance (set via setRouter)
-   */
-  let routerInstance = null
-
-  // ===== Computed =====
-
-  const hasMetadata = computed(() => Object.keys(entityMetadata.value).length > 0)
-
-  const entityList = computed(() => {
-    return Object.keys(entityMetadata.value).sort()
-  })
-
-  const currentEntityMeta = computed(() => {
-    if (!currentEntity.value) return null
-    return entityMetadata.value[currentEntity.value] || null
-  })
-
-  // ===== Actions =====
-
-  /**
-   * Initialize the app
-   *
-   * Connects to WebSocket and sets up app lifecycle.
-   *
-   * @param {Object} options
-   * @param {string} [options.wsUrl] - WebSocket URL (auto-detected if not provided)
-   * @param {string} [options.title] - App title
-   * @returns {Promise<void>}
-   *
-   * @example
-   * await appStore.initialize()
-   *
-   * @example
-   * await appStore.initialize({
-   *   wsUrl: 'ws://localhost:3000/ws',
-   *   title: 'My DZQL App'
-   * })
-   */
-  async function initialize(options = {}) {
-    const wsStore = useWsStore()
-
-    // Set app title if provided
-    if (options.title) {
-      title.value = options.title
-    }
-
-    // Connect to WebSocket
-    await wsStore.connect(options.wsUrl)
-
-    // If authenticated, fetch metadata
-    if (wsStore.isAuthenticated) {
-      await fetchMetadata()
-    }
-
-    console.log('[AppStore] Initialized')
-  }
-
-  /**
-   * Fetch entity metadata from server
-   *
-   * Called automatically after authentication.
-   *
-   * @returns {Promise<void>}
-   */
-  async function fetchMetadata() {
-    const wsStore = useWsStore()
-    const ws = wsStore.getWs()
-
-    if (!wsStore.isConnected) {
-      console.warn('[AppStore] Cannot fetch metadata: not connected')
-      return
-    }
-
-    try {
-      isLoadingMetadata.value = true
-
-      // Call the meta endpoint
-      const result = await ws.call('meta')
-
-      if (result && result.entities) {
-        entityMetadata.value = result.entities
-        console.log('[AppStore] Metadata loaded:', Object.keys(result.entities))
-      }
-
-    } catch (err) {
-      console.error('[AppStore] Failed to fetch metadata:', err)
-    } finally {
-      isLoadingMetadata.value = false
-    }
-  }
-
-  /**
-   * Set the router instance
-   *
-   * Call this in main.js after creating the router to enable
-   * programmatic navigation from the store.
-   *
-   * @param {Router} router - Vue Router instance
-   *
-   * @example
-   * import { createRouter } from 'vue-router'
-   * import { useAppStore } from 'dzql/client/stores'
-   *
-   * const router = createRouter({ ... })
-   * const appStore = useAppStore()
-   * appStore.setRouter(router)
-   */
-  function setRouter(router) {
-    routerInstance = router
-
-    // Watch route changes to update current context
-    if (router) {
-      router.afterEach((to) => {
-        currentEntity.value = to.params.entity || null
-        currentId.value = to.params.id || null
-      })
-    }
-  }
-
-  /**
-   * Navigate to entity list
-   *
-   * @param {string} entity - Entity name
-   *
-   * @example
-   * appStore.navigateToEntity('venues')
-   */
-  function navigateToEntity(entity) {
-    if (routerInstance) {
-      routerInstance.push({ name: 'entity-list', params: { entity } })
-    }
-    currentEntity.value = entity
-    currentId.value = null
-  }
-
-  /**
-   * Navigate to entity detail/edit
-   *
-   * @param {string} entity - Entity name
-   * @param {number|string} id - Record ID or 'new'
-   *
-   * @example
-   * appStore.navigateToEntityDetail('venues', 123)
-   * appStore.navigateToEntityDetail('venues', 'new')
-   */
-  function navigateToEntityDetail(entity, id) {
-    if (routerInstance) {
-      const routeName = id === 'new' ? 'entity-create' : 'entity-edit'
-      routerInstance.push({ name: routeName, params: { entity, id } })
-    }
-    currentEntity.value = entity
-    currentId.value = id
-  }
-
-  /**
-   * Navigate to home
-   *
-   * @example
-   * appStore.navigateToHome()
-   */
-  function navigateToHome() {
-    if (routerInstance) {
-      routerInstance.push({ name: 'home' })
-    }
-    currentEntity.value = null
-    currentId.value = null
-  }
-
-  /**
-   * Toggle sidebar
-   */
-  function toggleSidebar() {
-    sidebarOpen.value = !sidebarOpen.value
-  }
-
-  /**
-   * Toggle properties panel
-   */
-  function togglePropertiesPanel() {
-    propertiesPanelOpen.value = !propertiesPanelOpen.value
-  }
-
-  /**
-   * Set current context (useful for manual navigation)
-   *
-   * @param {string|null} entity - Entity name
-   * @param {number|string|null} id - Record ID
-   */
-  function setContext(entity, id = null) {
-    currentEntity.value = entity
-    currentId.value = id
-  }
-
-  // ===== Return Public API =====
-
-  return {
-    // State
-    title,
-    currentEntity,
-    currentId,
-    entityMetadata,
-    isLoadingMetadata,
-    sidebarOpen,
-    propertiesPanelOpen,
-
-    // Computed
-    hasMetadata,
-    entityList,
-    currentEntityMeta,
-
-    // Actions
-    initialize,
-    fetchMetadata,
-    setRouter,
-    navigateToEntity,
-    navigateToEntityDetail,
-    navigateToHome,
-    toggleSidebar,
-    togglePropertiesPanel,
-    setContext
-  }
-})