react-embed-docs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nik Lucky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,422 @@
+# react-embed-docs
+
+Full-stack documentation system with BlockNote editor, hierarchical structure, and file uploads.
+
+## Features
+
+- 📝 **BlockNote Editor** - Notion-style block-based rich text editor
+- 🌳 **Hierarchical Structure** - Parent-child document relationships with drag-drop reordering
+- 🔍 **Full-Text Search** - Fast search with pre-built search index
+- 🎨 **Customizable** - Tailwind CSS styling with dark mode support
+- 📎 **File Uploads** - Built-in cover image support with PostgreSQL storage
+- 😀 **Emoji Icons** - Document icons with emoji picker
+- ⚡ **TypeScript** - Full type safety
+- 🗄️ **PostgreSQL** - Reliable data storage with Drizzle ORM
+
+## Installation
+
+```bash
+# Using bun
+bun install react-embed-docs
+
+# Using npm
+npm install react-embed-docs
+
+# Using yarn
+yarn add react-embed-docs
+```
+
+## Peer Dependencies
+
+```json
+{
+  "react": "^18.0.0",
+  "react-dom": "^18.0.0",
+  "@blocknote/core": "^0.46.0",
+  "@blocknote/react": "^0.46.0",
+  "@blocknote/mantine": "^0.46.0",
+  "drizzle-orm": "^0.31.0",
+  "@tanstack/react-query": "^5.0.0",
+  "postgres": "^3.4.0"
+}
+```
+
+## Quick Start
+
+### 1. Database Setup
+
+Run the migrations to create the necessary tables:
+
+```typescript
+import { drizzle } from 'drizzle-orm/postgres-js'
+import postgres from 'postgres'
+import { runMigrations } from 'react-embed-docs/server'
+
+const connection = postgres(process.env.DATABASE_URL)
+const db = drizzle(connection)
+
+// Run migrations on startup
+await runMigrations(db)
+```
+
+### 2. Server Setup (Hono)
+
+```typescript
+import { Hono } from 'hono'
+import { createDocsRouter, createFilesRouter } from 'react-embed-docs/server'
+
+const app = new Hono()
+
+// Add docs routes
+app.route('/api/docs', createDocsRouter({ db }))
+app.route('/api/files', createFilesRouter({ db }))
+
+// Or combine both
+import { createRouter } from 'react-embed-docs/server'
+app.route('/api', createRouter({ db }))
+```
+
+### 3. Client Setup (React)
+
+```tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { DocsLayout, DocumentEdit } from 'react-embed-docs/client'
+import 'react-embed-docs/styles'
+
+const queryClient = new QueryClient()
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <DocsLayout 
+        onNavigate={(id) => window.location.href = `/docs/${id}`}
+        userAvatar={<UserAvatar />} // Your custom avatar component
+      >
+        <DocumentEdit 
+          docId="new" 
+          onSave={(doc) => console.log('Saved:', doc)}
+          onNavigate={(id) => window.location.href = `/docs/${id}`}
+        />
+      </DocsLayout>
+    </QueryClientProvider>
+  )
+}
+```
+
+## API Reference
+
+### Server Exports
+
+```typescript
+import { 
+  DocsService, 
+  FilesService, 
+  createDocsRouter, 
+  createFilesRouter,
+  createRouter,
+  runMigrations,
+  documentsTable,
+  filesTable 
+} from 'react-embed-docs/server'
+```
+
+#### DocsService
+
+```typescript
+class DocsService {
+  // Queries
+  list(filters, options): Promise<ListDocumentsResult>
+  getById(id: string): Promise<Document | undefined>
+  getBySlug(slug: string): Promise<Document | undefined>
+  getChildren(parentId: string): Promise<Document[]>
+  getTree(): Promise<Document[]>
+  
+  // Mutations
+  create(data: InsertDocument): Promise<Document>
+  update(id: string, data: UpdateDocument): Promise<Document | undefined>
+  delete(id: string): Promise<Document | undefined>
+  
+  // Search
+  search(query: string, options): Promise<SearchResult[]>
+  searchText(query: string, options): Promise<SearchTextResult[]>
+  
+  // Reordering
+  reorder(id: string, newParentId: string | null, newOrder: number): Promise<Document | undefined>
+}
+```
+
+### Client Exports
+
+```typescript
+import { 
+  DocsLayout,
+  DocumentEdit,
+  DocumentView,
+  DocumentList,
+  EmojiPicker,
+  useDocumentsQuery,
+  useDocumentQuery,
+  useCreateDocumentMutation,
+  useUpdateDocumentMutation,
+  useDeleteDocumentMutation,
+  useReorderDocumentMutation,
+  useFileUpload
+} from 'react-embed-docs/client'
+```
+
+#### Components
+
+**DocsLayout**
+```tsx
+<DocsLayout
+  currentDocId?: string          // Currently active document ID
+  onNavigate?: (id: string) => void  // Navigation callback
+  userAvatar?: React.ReactNode   // User avatar component for header
+  onSearch?: (query: string) => void  // Search callback
+>
+  {children}
+</DocsLayout>
+```
+
+**DocumentEdit**
+```tsx
+<DocumentEdit
+  docId: string              // 'new' or document ID
+  parentId?: string          // Parent document ID (for creating child)
+  onSave?: (doc: Document) => void
+  onNavigate?: (id: string) => void
+/>
+```
+
+**DocumentView**
+```tsx
+<DocumentView
+  docId: string
+  onEdit?: (id: string) => void
+  onCreateChild?: (parentId: string) => void
+  onNavigate?: (id: string) => void
+/>
+```
+
+#### Hooks
+
+```typescript
+// Queries
+const { data, isLoading } = useDocumentsQuery({ search?: string, parentId?: string })
+const { data } = useDocumentQuery(docId)
+
+// Mutations
+const create = useCreateDocumentMutation()
+const update = useUpdateDocumentMutation()
+const delete = useDeleteDocumentMutation()
+const reorder = useReorderDocumentMutation()
+
+// File upload
+const { isUploading, progress, error, uploadFile } = useFileUpload({
+  maxSize: 5 * 1024 * 1024,  // 5MB
+  allowedTypes: ['image/jpeg', 'image/png', 'image/gif', 'image/webp']
+})
+```
+
+## Database Schema
+
+### Documents Table
+
+| Column | Type | Description |
+|--------|------|-------------|
+| id | varchar(21) | Primary key (nanoid) |
+| title | varchar(255) | Document title |
+| slug | varchar(255) | URL-friendly unique slug |
+| content | jsonb | BlockNote JSON content |
+| searchIndex | text | Pre-built search text (title + content) |
+| emoji | varchar(10) | Document icon emoji |
+| cover | varchar(500) | Cover image file ID |
+| isPublished | boolean | Published state |
+| parentId | varchar(21) | Parent document ID (self-reference) |
+| order | integer | Sort order within parent |
+| authorId | integer | Document author (optional) |
+| createdAt | timestamp | Creation time |
+| updatedAt | timestamp | Last update time |
+| deletedAt | timestamp | Soft delete timestamp |
+
+### Files Table
+
+| Column | Type | Description |
+|--------|------|-------------|
+| id | varchar(21) | Primary key (nanoid) |
+| filename | varchar(255) | Original filename |
+| mimeType | varchar(100) | File MIME type |
+| size | integer | File size in bytes |
+| content | text | Base64 encoded file content |
+| createdAt | timestamp | Upload time |
+
+## Styling
+
+The package includes a complete Tailwind CSS stylesheet with all utilities. Import it in your app:
+
+```typescript
+import 'react-embed-docs/styles'
+```
+
+This imports a pre-built CSS bundle that includes all Tailwind utilities used by the components. **No additional Tailwind configuration needed.**
+
+### Using with your own Tailwind setup
+
+If you prefer to process the styles through your own Tailwind build (e.g., for custom theming), use the source CSS instead:
+
+```typescript
+import 'react-embed-docs/styles/source'
+```
+
+Then add the package files to your Tailwind content config:
+
+```javascript
+// tailwind.config.js
+module.exports = {
+  content: [
+    './src/**/*.{js,ts,jsx,tsx}',
+    './node_modules/react-embed-docs/dist/client/**/*.js',
+  ],
+}
+```
+
+### Tailwind CSS Safelist (legacy)
+
+If you're using the source CSS and some classes aren't working, you can use the safelist:
+
+```javascript
+// tailwind.config.js
+module.exports = {
+  content: [
+    './src/**/*.{js,ts,jsx,tsx}',
+    // Add this to scan the safelist
+    './node_modules/react-embed-docs/styles/tailwind.safelist.js',
+  ],
+  safelist: [
+    // Option 1: Include all classes from the package
+    ...require('react-embed-docs/styles/tailwind.safelist.js'),
+    
+    // Option 2: Or manually add specific classes you need
+    'h-40', 'h-44', 'h-48', 'h-52', 'h-56', 'h-60',
+  ],
+}
+```
+
+### Dark Mode
+
+All components support dark mode through Tailwind's `dark:` variants. The components automatically adapt when you have `class="dark"` on your HTML element.
+
+## Configuration
+
+### Custom API Prefix
+
+```typescript
+app.route('/custom-prefix', createDocsRouter({ db }))
+```
+
+### File Upload Limits
+
+```typescript
+const { uploadFile } = useFileUpload({
+  maxSize: 10 * 1024 * 1024,  // 10MB
+  allowedTypes: ['image/jpeg', 'image/png', 'image/webp', 'application/pdf']
+})
+```
+
+### Authentication
+
+The package doesn't enforce authentication, allowing you to integrate with your own auth system:
+
+```typescript
+// Add your auth middleware before docs routes
+app.use('/api/docs/*', yourAuthMiddleware)
+app.route('/api/docs', createDocsRouter({ db }))
+```
+
+## Examples
+
+### Creating a New Document
+
+```typescript
+const createMutation = useCreateDocumentMutation()
+
+const handleCreate = async () => {
+  const doc = await createMutation.mutateAsync({
+    title: 'My New Document',
+    slug: 'my-new-document',
+    content: [],  // BlockNote blocks
+    emoji: '📝',
+    isPublished: true
+  })
+  
+  // Navigate to the new document
+  router.push(`/docs/${doc.id}`)
+}
+```
+
+### Uploading a Cover Image
+
+```typescript
+const { uploadFile } = useFileUpload()
+const updateMutation = useUpdateDocumentMutation()
+
+const handleCoverUpload = async (file: File) => {
+  const result = await uploadFile(file)
+  if (result) {
+    await updateMutation.mutateAsync({
+      id: docId,
+      cover: result.url  // /api/files/{id}
+    })
+  }
+}
+```
+
+### Searching Documents
+
+```typescript
+const [searchQuery, setSearchQuery] = useState('')
+const { data } = useDocumentsQuery({ search: searchQuery })
+
+// Results include documents matching title or content
+```
+
+## Migration Guide
+
+### From Existing Implementation
+
+If you're migrating from an existing docs implementation:
+
+1. **Database**: The schema is compatible but adds `searchIndex` column for faster search
+2. **Components**: Replace shadcn imports with `react-embed-docs/client`
+3. **Services**: Replace local services with `react-embed-docs/server`
+4. **Styling**: Import `react-embed-docs/styles` or copy CSS classes
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Build
+bun run build
+
+# Watch mode
+bun run dev
+
+# Run migrations
+bun run migrate
+```
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines before submitting PRs.
+
+## Support
+
+- 📧 Email: support@example.com
+- 🐛 Issues: [GitHub Issues](https://github.com/niklucky/react-embed-docs/issues)
+- 📖 Documentation: [Full Documentation](https://github.com/niklucky/react-embed-docs#readme)

package/dist/client/components/Breadcrumbs.d.ts

@@ -0,0 +1,21 @@
+interface BreadcrumbDoc {
+    id: string;
+    title: string;
+    slug: string;
+    emoji?: string;
+    parentId?: string | null;
+}
+interface BreadcrumbsProps {
+    docId?: string;
+    /**
+     * Array of all documents to build paths locally without API call.
+     * If not provided, will fetch from API.
+     */
+    documents?: BreadcrumbDoc[];
+    onNavigate?: (path: string) => void;
+    homeLabel?: string;
+    className?: string;
+}
+export declare function Breadcrumbs({ docId, documents, onNavigate, homeLabel, className, }: BreadcrumbsProps): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=Breadcrumbs.d.ts.map

package/dist/client/components/Breadcrumbs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Breadcrumbs.d.ts","sourceRoot":"","sources":["../../../src/client/components/Breadcrumbs.tsx"],"names":[],"mappings":"AAKA,UAAU,aAAa;IACrB,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACzB;AAED,UAAU,gBAAgB;IACxB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,SAAS,CAAC,EAAE,aAAa,EAAE,CAAA;IAC3B,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IACnC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAwCD,wBAAgB,WAAW,CAAC,EAC1B,KAAK,EACL,SAAS,EACT,UAAU,EACV,SAAkB,EAClB,SAAc,GACf,EAAE,gBAAgB,2CAmLlB"}

package/dist/client/components/Breadcrumbs.js

@@ -0,0 +1,123 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ChevronRight, Home, Loader2 } from 'lucide-react';
+import { useEffect, useMemo, useState } from 'react';
+// Fetch breadcrumbs from API
+async function fetchBreadcrumbs(docId) {
+    const response = await fetch(`/api/docs/${docId}/breadcrumbs`);
+    if (!response.ok) {
+        throw new Error('Failed to fetch breadcrumbs');
+    }
+    const data = await response.json();
+    return data.items;
+}
+// Build full path from root to document
+function buildPath(docId, allDocs, basePath = '/docs') {
+    const pathParts = [];
+    const visited = new Set();
+    let currentId = docId;
+    while (currentId) {
+        // Prevent infinite loops from circular references
+        if (visited.has(currentId))
+            break;
+        visited.add(currentId);
+        const doc = allDocs.find((d) => d.id === currentId);
+        if (!doc)
+            break;
+        pathParts.unshift(doc.slug || doc.id);
+        currentId = allDocs.find((d) => d.id === currentId)?.parentId ?? null;
+    }
+    if (pathParts.length === 0)
+        return basePath;
+    return `${basePath}/${pathParts.join('/')}`;
+}
+export function Breadcrumbs({ docId, documents, onNavigate, homeLabel = 'Home', className = '', }) {
+    const [fetchedBreadcrumbs, setFetchedBreadcrumbs] = useState([]);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    // Use provided documents or fetch from API
+    const breadcrumbs = useMemo(() => {
+        if (documents && docId) {
+            // Build breadcrumbs from provided documents
+            const result = [];
+            const visited = new Set();
+            let currentId = docId;
+            while (currentId) {
+                if (visited.has(currentId))
+                    break;
+                visited.add(currentId);
+                const doc = documents.find((d) => d.id === currentId);
+                if (!doc)
+                    break;
+                result.unshift(doc);
+                currentId = documents.find((d) => d.id === currentId)?.parentId ?? null;
+            }
+            return result;
+        }
+        return fetchedBreadcrumbs;
+    }, [documents, docId, fetchedBreadcrumbs]);
+    useEffect(() => {
+        // If documents are provided, don't fetch
+        if (documents || !docId) {
+            return;
+        }
+        setIsLoading(true);
+        setError(null);
+        fetchBreadcrumbs(docId)
+            .then((items) => {
+            setFetchedBreadcrumbs(items);
+            setIsLoading(false);
+        })
+            .catch((err) => {
+            setError(err instanceof Error ? err.message : 'Failed to load breadcrumbs');
+            setIsLoading(false);
+        });
+    }, [docId, documents]);
+    const handleNavigate = (targetDocId) => {
+        if (!onNavigate)
+            return;
+        if (!targetDocId) {
+            // Navigate to root
+            onNavigate('/docs');
+            return;
+        }
+        // Build full path
+        const pathParts = [];
+        const visited = new Set();
+        let currentId = targetDocId;
+        const allDocs = documents || breadcrumbs;
+        while (currentId) {
+            if (visited.has(currentId))
+                break;
+            visited.add(currentId);
+            const doc = allDocs.find((d) => d.id === currentId);
+            if (!doc)
+                break;
+            pathParts.unshift(doc.slug || doc.id);
+            currentId = allDocs.find((d) => d.id === currentId)?.parentId ?? null;
+        }
+        if (pathParts.length === 0) {
+            onNavigate('/docs');
+        }
+        else {
+            onNavigate(`/docs/${pathParts.join('/')}`);
+        }
+    };
+    if (!docId) {
+        return (_jsx("nav", { className: `flex items-center gap-1 text-sm ${className}`, children: _jsxs("button", { onClick: () => handleNavigate(null), className: "flex items-center gap-1.5 text-gray-500 hover:text-gray-700 transition-colors", children: [_jsx(Home, { className: "h-4 w-4" }), _jsx("span", { children: homeLabel })] }) }));
+    }
+    if (isLoading && !documents) {
+        return (_jsxs("div", { className: `flex items-center gap-2 text-sm text-gray-400 ${className}`, children: [_jsx(Loader2, { className: "h-4 w-4 animate-spin" }), _jsx("span", { children: "Loading..." })] }));
+    }
+    if (error && !documents) {
+        return (_jsxs("div", { className: `flex items-center gap-1 text-sm text-gray-500 ${className}`, children: [_jsxs("button", { onClick: () => handleNavigate(null), className: "flex items-center gap-1.5 hover:text-gray-700 transition-colors", children: [_jsx(Home, { className: "h-4 w-4" }), _jsx("span", { children: homeLabel })] }), _jsx(ChevronRight, { className: "h-4 w-4 text-gray-400" }), _jsx("span", { className: "text-gray-400", children: "Error loading path" })] }));
+    }
+    if (breadcrumbs.length === 0) {
+        return (_jsx("nav", { className: `flex items-center gap-1 text-sm ${className}`, children: _jsxs("button", { onClick: () => handleNavigate(null), className: "flex items-center gap-1.5 text-gray-500 hover:text-gray-700 transition-colors", children: [_jsx(Home, { className: "h-4 w-4" }), _jsx("span", { children: homeLabel })] }) }));
+    }
+    return (_jsxs("nav", { className: `flex items-center gap-1 text-sm ${className}`, children: [_jsxs("button", { onClick: () => handleNavigate(null), className: "flex items-center gap-1.5 text-gray-500 hover:text-gray-700 transition-colors shrink-0", title: homeLabel, children: [_jsx(Home, { className: "h-4 w-4" }), _jsx("span", { className: "hidden sm:inline", children: homeLabel })] }), breadcrumbs.map((doc, index) => {
+                const isLast = index === breadcrumbs.length - 1;
+                const displayTitle = doc.title || 'Untitled';
+                return (_jsxs("span", { className: "flex items-center gap-1 min-w-0", children: [_jsx(ChevronRight, { className: "h-4 w-4 text-gray-400 shrink-0" }), isLast ? (_jsxs("span", { className: "font-medium text-gray-900 truncate max-w-[200px] sm:max-w-[300px] md:max-w-[400px]", title: displayTitle, children: [doc.emoji && _jsx("span", { className: "mr-1", children: doc.emoji }), displayTitle] })) : (_jsxs("button", { onClick: () => handleNavigate(doc.id), className: "text-gray-500 hover:text-gray-700 transition-colors truncate max-w-[150px] sm:max-w-[200px]", title: displayTitle, children: [doc.emoji && _jsx("span", { className: "mr-1", children: doc.emoji }), displayTitle] }))] }, doc.id));
+            })] }));
+}

package/dist/client/components/DocsLayout.d.ts

@@ -0,0 +1,20 @@
+import { DocumentSummary } from '../../shared/types.js';
+interface DocsLayoutProps {
+    theme?: 'light' | 'dark';
+    children: React.ReactNode;
+    currentDocId?: string;
+    /**
+     * Called when navigating to a document.
+     * `path` is the full path from root to the document (e.g., "/docs/parent/child")
+     */
+    onNavigate?: (path: string) => void;
+    /**
+     * Base path for document URLs (default: "/docs")
+     */
+    basePath?: string;
+    userAvatar?: React.ReactNode;
+    onSearch?: (query: string) => DocumentSummary[];
+}
+export declare function DocsLayout({ children, currentDocId, onNavigate, basePath, userAvatar, onSearch, }: DocsLayoutProps): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=DocsLayout.d.ts.map

package/dist/client/components/DocsLayout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocsLayout.d.ts","sourceRoot":"","sources":["../../../src/client/components/DocsLayout.tsx"],"names":[],"mappings":"AAoCA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAavD,UAAU,eAAe;IACvB,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;IACxB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IACnC;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC5B,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,eAAe,EAAE,CAAA;CAChD;AAsQD,wBAAgB,UAAU,CAAC,EACzB,QAAQ,EACR,YAAY,EACZ,UAAU,EACV,QAAkB,EAClB,UAAU,EACV,QAAQ,GACT,EAAE,eAAe,2CAgcjB"}