@abraca/nuxt 0.1.0 → 0.2.0

package/README.md

@@ -1,84 +1,244 @@
-<!--
-Get your module up and running quickly.
-
-Find and replace all on all files (CMD+SHIFT+F):
-- Name: My Module
-- Package name: my-module
-- Description: My new Nuxt module
--->
-
-# My Module
+# @abraca/nuxt
 
 [![npm version][npm-version-src]][npm-version-href]
 [![npm downloads][npm-downloads-src]][npm-downloads-href]
 [![License][license-src]][license-href]
 [![Nuxt][nuxt-src]][nuxt-href]
 
-My new Nuxt module for doing amazing things.
+First-class Nuxt 4 module for the [Abracadabra](https://abra.cou.sh) CRDT collaboration platform. Drop real-time collaborative documents, multi-user awareness, offline-first sync, and a full rich-text editor into any Nuxt app.
 
-- [✨ &nbsp;Release Notes](/CHANGELOG.md)
-<!-- - [🏀 Online playground](https://stackblitz.com/github/your-org/my-module?file=playground%2Fapp.vue) -->
-<!-- - [📖 &nbsp;Documentation](https://example.com) -->
+- [Release Notes](/CHANGELOG.md)
 
 ## Features
 
-<!-- Highlight some of the features your module provide here -->
-- ⛰ &nbsp;Foo
-- 🚠 &nbsp;Bar
-- 🌲 &nbsp;Baz
+- Real-time collaborative editing via WebSocket + Yjs CRDT
+- Offline-first with IndexedDB persistence and background sync queue
+- Multi-user awareness — cursors, presence, typing indicators, voice/video
+- TipTap rich-text editor with 30+ built-in extensions
+- Built-in page renderers: Kanban, Table, Calendar, Gallery, Outline
+- Full-text search with trigram indexing
+- File uploads with offline blob caching
+- Passkey (WebAuthn) authentication
+- Server-side rendering with Nitro plugin system and doc cache
+- Extensible plugin architecture
+
+## Requirements
 
-## Quick Setup
+- Nuxt >= 4
+- `@abraca/dabra` >= 1.0.0
+- `@tiptap/core`, `@tiptap/vue-3`, `@tiptap/extension-collaboration`, `@tiptap/extension-collaboration-caret`
+- `yjs` >= 13
 
-Install the module to your Nuxt application with one command:
+## Setup
 
 ```bash
-npx nuxt module add my-module
+pnpm add @abraca/nuxt @abraca/dabra yjs @tiptap/core @tiptap/vue-3 @tiptap/extension-collaboration @tiptap/extension-collaboration-caret
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@abraca/nuxt'],
+  abracadabra: {
+    url: 'https://your-abracadabra-server.example.com',
+  }
+})
+```
+
+Wrap your app with `<AProvider>` and you're live:
+
+```vue
+<template>
+  <AProvider>
+    <NuxtPage />
+  </AProvider>
+</template>
+```
+
+## Configuration
+
+```ts
+abracadabra: {
+  // Connection
+  url?: string                    // Server URL (default: 'https://abra.cou.sh')
+  entryDocId?: string             // Root doc ID (skips space discovery)
+
+  // Auth
+  persistAuth?: boolean           // Persist JWT in localStorage (default: true)
+  authStorageKey?: string         // localStorage key (default: 'abracadabra:auth')
+  auth?: {
+    middleware?: boolean          // Register abracadabra-auth middleware
+    globalMiddleware?: boolean    // Apply to all routes
+    loginPath?: string            // Redirect target (default: '/login')
+  }
+
+  // Features (control what code is included)
+  features?: {
+    editor?: boolean              // TipTap editor (default: true)
+    search?: boolean              // Full-text search (default: true)
+    backgroundSync?: boolean      // Offline sync queue (default: true)
+    renderers?: boolean           // Built-in page renderers (default: true)
+    serverCache?: boolean         // Server doc-tree cache runner (default: true)
+  }
+
+  // UI
+  prefix?: string                 // Component name prefix (default: '')
+  locale?: Partial<AbracadabraLocale>
+  docBasePath?: string            // Doc route base (default: '/doc')
+
+  // Server-side service account (for Nitro runners)
+  service?: {
+    publicKey?: string            // Ed25519 public key (base64url)
+    privateKey?: string           // Ed25519 private key (base64url)
+  }
+
+  debug?: boolean
+}
 ```
 
-That's it! You can now use My Module in your Nuxt app ✨
+## Auto-imported Composables
+
+| Composable | Description |
+|---|---|
+| `useAbracadabra()` | Full collaboration state (client, provider, identity, docs) |
+| `useAbracadabraAuth()` | Auth — login, passkey, identity management |
+| `useAwareness()` | All connected users' raw awareness states |
+| `useAwarenessPeers()` | Typed peer list with idle detection |
+| `useAAField(key)` | Per-field interaction awareness (hover, press, focus) |
+| `useYDoc(ydoc)` | Reactive Yjs primitives — `useSyncedMap`, `useSyncedArray`, `useAwarenessOf`, `useSmoothedCursors` |
+| `useEditor(ydoc, opts)` | TipTap setup with collaboration + cursor extensions |
+| `useChildTree(docId)` | Document tree scoped to a parent |
+| `useDocumentPermissions(role)` | RBAC flags (canWrite, canDelete, etc.) |
+| `useChat(channel)` | Real-time group & DM chat |
+| `useNotifications()` | Server-pushed notifications |
+| `useSearchIndex()` | Full-text search over synced docs |
+| `useBackgroundSync()` | Offline sync queue status |
+| `useDocExport()` | Export docs as markdown, HTML, or ZIP |
+| `useDocImport()` | Import .md, .txt, .html files |
+| `useFileBlobStore()` | Offline file blob cache (IndexedDB) |
+| `useVoice()` | WebRTC voice/video state |
+| `useWindowManager()` | Floating window (PiP/panel) management |
+| `useCommandPalette()` | ⌘K command palette state & commands |
+| `useConnectionStatus()` | Connection status as UI-ready label + color |
+| `useRendererBase(docId)` | Shared setup for custom page renderers |
+| `useTrash()` | Document trash (move, restore, permanent delete) |
+| `usePasskeyAccounts()` | WebAuthn passkey account management |
+| `useFollowUser(userId)` | Cursor following for pair programming |
+
+## Auto-imported Components
+
+### Core
+| Component | Description |
+|---|---|
+| `<AProvider>` | Root wrapper — initializes SDK and syncs root doc |
+| `<AEditor>` | Full TipTap collaborative editor |
+| `<ADocumentTree>` | Hierarchical doc tree with drag-drop |
+| `<ANodePanel>` | Slide-over panel with doc metadata and children |
+| `<ACommandPalette>` | ⌘K search and command palette |
+| `<AConnectionStatus>` | Connection state badge |
+| `<APresence>` | Connected users presence indicator |
+| `<ANotifications>` | Notification center |
+| `<AVoiceBar>` | Voice/video call controls |
+| `<ADocTypeSelect>` | Page type selector |
+| `<APermissionGuard>` | Conditional render based on role |
+| `<ARoleBadge>` | Role badge (Owner, Editor, Viewer, etc.) |
+| `<AFloatingWindow>` | Floating/PiP window container |
+| `<AWindowLayer>` | Portal for floating windows |
+
+### Aware Interaction Components
+Interaction components that broadcast awareness state to other users:
+
+`<AArea>` `<AAvatar>` `<AButton>` `<AInput>` `<ATextarea>` `<ASelect>` `<ACursorLabel>` `<AFacepile>` `<AUserList>` `<ADocBadge>`
+
+### Page Renderers (requires `features.renderers`)
+`<AKanbanRenderer>` `<ATableRenderer>` `<ACalendarRenderer>` `<AGalleryRenderer>` `<AOutlineRenderer>`
+
+## Server-Side Usage
+
+Configure a service account for server-side doc access:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@abraca/nuxt'],
+  runtimeConfig: {
+    abracadabra: {
+      servicePublicKey: process.env.ABRA_SERVICE_PUBLIC_KEY,
+      servicePrivateKey: process.env.ABRA_SERVICE_PRIVATE_KEY,
+    }
+  }
+})
+```
 
+Register custom server runners via the Nitro hook:
+
+```ts
+// server/plugins/my-runner.ts
+export default defineNitroPlugin((nitro) => {
+  nitro.hooks.hook('abracadabra:before-runners', (ctx) => {
+    registerServerPlugin({
+      name: 'my-runner',
+      runners: [{
+        name: 'my-background-task',
+        run: async ({ provider, client }) => {
+          // background work
+          return () => { /* cleanup */ }
+        }
+      }]
+    })
+  })
+})
+```
+
+## Plugin System
+
+Extend the editor, add toolbar items, slash commands, and page types:
+
+```ts
+import type { AbracadabraPlugin } from '@abraca/nuxt'
+
+const myPlugin: AbracadabraPlugin = {
+  name: 'my-plugin',
+  extensions: () => [/* TipTap extensions */],
+  toolbarItems: () => [/* toolbar groups */],
+  suggestionItems: () => [/* slash commands */],
+  pageTypes: [{ type: 'my-type', label: 'My Page', component: MyRenderer }],
+  clientSetup: async (state) => { /* init */ }
+}
+```
 
 ## Contribution
 
-<details>
-  <summary>Local development</summary>
-  
-  ```bash
-  # Install dependencies
-  npm install
-  
-  # Generate type stubs
-  npm run dev:prepare
-  
-  # Develop with the playground
-  npm run dev
-  
-  # Build the playground
-  npm run dev:build
-  
-  # Run ESLint
-  npm run lint
-  
-  # Run Vitest
-  npm run test
-  npm run test:watch
-  
-  # Release new version
-  npm run release
-  ```
-
-</details>
+```bash
+# Install dependencies
+pnpm install
 
+# Generate type stubs
+pnpm dev:prepare
+
+# Develop with the playground
+pnpm dev
+
+# Build
+pnpm prepack
+
+# Lint
+pnpm lint
+
+# Test
+pnpm test
+pnpm test:watch
+```
 
 <!-- Badges -->
-[npm-version-src]: https://img.shields.io/npm/v/my-module/latest.svg?style=flat&colorA=020420&colorB=00DC82
-[npm-version-href]: https://npmjs.com/package/my-module
+[npm-version-src]: https://img.shields.io/npm/v/@abraca/nuxt/latest.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-version-href]: https://npmjs.com/package/@abraca/nuxt
 
-[npm-downloads-src]: https://img.shields.io/npm/dm/my-module.svg?style=flat&colorA=020420&colorB=00DC82
-[npm-downloads-href]: https://npm.chart.dev/my-module
+[npm-downloads-src]: https://img.shields.io/npm/dm/@abraca/nuxt.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-downloads-href]: https://npm.chart.dev/@abraca/nuxt
 
-[license-src]: https://img.shields.io/npm/l/my-module.svg?style=flat&colorA=020420&colorB=00DC82
-[license-href]: https://npmjs.com/package/my-module
+[license-src]: https://img.shields.io/npm/l/@abraca/nuxt.svg?style=flat&colorA=020420&colorB=00DC82
+[license-href]: https://npmjs.com/package/@abraca/nuxt
 
 [nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt
 [nuxt-href]: https://nuxt.com

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": ">=4.0.0"
   },
-  "version": "0.1.0",
+  "version": "0.2.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/runtime/components/ADocumentTree.d.vue.ts

@@ -1,53 +1,18 @@
-import type { AbracadabraLocale } from '../locale.js';
 type __VLS_Props = {
-    showTrash?: boolean;
-    allowFileDrop?: boolean;
-    draggable?: boolean;
+    collapsed?: boolean;
+    editable?: boolean;
     selectedId?: string | null;
-    labels?: Partial<AbracadabraLocale['documentTree']>;
 };
-interface FlatItem {
-    id: string;
-    label: string;
-    type?: string;
-    meta?: Record<string, any>;
-    depth: number;
-    parentId: string | null;
-    order: number;
-    isExpanded: boolean;
-    hasChildren: boolean;
-}
-declare var __VLS_1: {}, __VLS_20: {
-    entry: FlatItem;
-    depth: number;
-    isExpanded: boolean;
-}, __VLS_42: {}, __VLS_85: {};
-type __VLS_Slots = {} & {
-    header?: (props: typeof __VLS_1) => any;
-} & {
-    item?: (props: typeof __VLS_20) => any;
-} & {
-    empty?: (props: typeof __VLS_42) => any;
-} & {
-    footer?: (props: typeof __VLS_85) => any;
-};
-declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
-    select: (docId: string) => any;
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {
+    handleExternalDrop: (e: DragEvent, parentId?: string | null) => any;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    navigate: (id: string) => any;
     create: (parentId: string | null) => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
-    onSelect?: ((docId: string) => any) | undefined;
+    onNavigate?: ((id: string) => any) | undefined;
     onCreate?: ((parentId: string | null) => any) | undefined;
 }>, {
-    draggable: boolean;
-    showTrash: boolean;
-    allowFileDrop: boolean;
-    selectedId: string | null;
+    editable: boolean;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
-declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;
 export default _default;
-type __VLS_WithSlots<T, S> = T & {
-    new (): {
-        $slots: S;
-    };
-};