@opensaas/stack-tiptap 0.1.0 → 0.1.1

package/.turbo/turbo-build.log

@@ -1,8 +1,10 @@
 
-> @opensaas/stack-tiptap@0.1.0 build /home/runner/work/stack/stack/packages/tiptap
+> @opensaas/stack-tiptap@0.1.1 build /home/runner/work/stack/stack/packages/tiptap
 > tsc && npm run copy:css
 
+npm warn Unknown env config "verify-deps-before-run". This will stop working in the next major version of npm.
+npm warn Unknown env config "_jsr-registry". This will stop working in the next major version of npm.
 
-> @opensaas/stack-tiptap@0.1.0 copy:css
+> @opensaas/stack-tiptap@0.1.1 copy:css
 > mkdir -p dist/styles && cp src/styles/tiptap.css dist/styles/
 

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# @opensaas/stack-tiptap
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [9a3fda5]
+- Updated dependencies [f8ebc0e]
+- Updated dependencies [045c071]
+  - @opensaas/stack-core@0.1.1
+  - @opensaas/stack-ui@0.1.1

package/CLAUDE.md

@@ -0,0 +1,274 @@
+# @opensaas/stack-tiptap
+
+Third-party field package providing rich text editing with Tiptap editor for OpenSaas Stack.
+
+## Purpose
+
+Demonstrates how to create third-party field packages that extend OpenSaas Stack without modifying core. Provides production-ready rich text editing with JSON storage.
+
+## Key Files & Exports
+
+### Field Builder (`src/fields/richText.ts`)
+
+- `richText(options?)` - Field builder function
+- Returns `RichTextField` type implementing `BaseFieldConfig`
+- Methods: `getZodSchema()`, `getPrismaType()`, `getTypeScriptType()`
+
+### Component (`src/components/TiptapField.tsx`)
+
+- `TiptapField` - React component (client component)
+- Uses Tiptap editor with StarterKit
+- Supports edit/read modes, custom toolbar
+
+### Main Exports (`src/index.ts`)
+
+- Re-exports field builder and component
+- Separate exports for `/fields` and `/components`
+
+## Architecture
+
+### Self-Contained Field Pattern
+
+Complete third-party field implementation:
+
+```typescript
+// Field builder
+export function richText(options) {
+  return {
+    type: 'richText',
+    ...options,
+    getPrismaType: () => ({ type: 'Json', modifiers: '' }),
+    getTypeScriptType: () => ({ type: 'any', optional: !options?.validation?.isRequired }),
+    getZodSchema: (fieldName, operation) => {
+      return operation === 'create' && options?.validation?.isRequired
+        ? z.any().refine((val) => val, 'Required')
+        : z.any().optional()
+    },
+  }
+}
+```
+
+### Client-Side Registration
+
+Due to Next.js server/client boundaries:
+
+```typescript
+// lib/register-fields.ts
+'use client'
+import { registerFieldComponent } from '@opensaas/stack-ui'
+import { TiptapField } from '@opensaas/stack-tiptap'
+
+registerFieldComponent('richText', TiptapField)
+
+// app/admin/[[...admin]]/page.tsx
+import '../../../lib/register-fields' // Side-effect import
+```
+
+### JSON Storage
+
+Content stored as Prisma `Json` type:
+
+```prisma
+model Article {
+  content Json  // Tiptap JSON structure
+}
+```
+
+TypeScript type:
+
+```typescript
+type Article = {
+  content: any // JSON structure
+}
+```
+
+## Integration Points
+
+### With @opensaas/stack-core
+
+- Implements `BaseFieldConfig` interface
+- Works with generator system (no core changes)
+- Compatible with access control and hooks
+
+### With @opensaas/stack-ui
+
+- Uses component registry pattern
+- Receives UI options as props via pass-through
+- Follows field component prop interface
+
+### With Tiptap
+
+- Uses `@tiptap/react` and `@tiptap/starter-kit`
+- SSR-safe with `immediatelyRender: false`
+- JSON content structure
+
+## Common Patterns
+
+### Basic Usage
+
+```typescript
+// opensaas.config.ts
+import { richText } from '@opensaas/stack-tiptap/fields'
+
+fields: {
+  content: richText({
+    validation: { isRequired: true },
+    ui: {
+      placeholder: 'Start writing...',
+      minHeight: 200,
+      maxHeight: 800,
+    },
+  })
+}
+```
+
+### With Access Control
+
+```typescript
+content: richText({
+  access: {
+    read: () => true,
+    create: ({ session }) => !!session,
+    update: ({ session, item }) => session?.userId === item.authorId,
+  },
+})
+```
+
+### Custom Extensions
+
+```typescript
+// components/ExtendedTiptap.tsx
+'use client'
+import { useEditor, EditorContent } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import Link from '@tiptap/extension-link'
+import Image from '@tiptap/extension-image'
+
+export function ExtendedTiptap({ value, onChange, ...props }) {
+  const editor = useEditor({
+    extensions: [StarterKit, Link, Image],
+    content: value,
+    immediatelyRender: false,
+    onUpdate: ({ editor }) => onChange(editor.getJSON())
+  })
+
+  return <EditorContent editor={editor} />
+}
+
+// lib/register-fields.ts
+registerFieldComponent('richTextExtended', ExtendedTiptap)
+
+// opensaas.config.ts
+content: richText({ ui: { fieldType: 'richTextExtended' } })
+```
+
+## Third-Party Field Package Requirements
+
+This package demonstrates all requirements for third-party fields:
+
+### 1. Field Builder with Required Methods
+
+```typescript
+export type RichTextField = BaseFieldConfig & {
+  type: 'richText'
+  // Custom options
+}
+
+export function richText(options?): RichTextField {
+  return {
+    type: 'richText',
+    ...options,
+    getZodSchema: (fieldName, operation) => {
+      /* ... */
+    },
+    getPrismaType: (fieldName) => {
+      /* ... */
+    },
+    getTypeScriptType: () => {
+      /* ... */
+    },
+  }
+}
+```
+
+### 2. React Component with Standard Props
+
+```typescript
+export interface TiptapFieldProps {
+  name: string
+  value: any
+  onChange: (value: any) => void
+  label: string
+  error?: string
+  disabled?: boolean
+  required?: boolean
+  mode?: 'read' | 'edit'
+  // Plus custom UI options
+  placeholder?: string
+  minHeight?: number
+  maxHeight?: number
+}
+```
+
+### 3. Client-Side Registration
+
+```typescript
+'use client'
+import { registerFieldComponent } from '@opensaas/stack-ui'
+import { TiptapField } from '@opensaas/stack-tiptap'
+
+registerFieldComponent('richText', TiptapField)
+```
+
+### 4. SSR Safety
+
+```typescript
+const editor = useEditor({
+  extensions: [StarterKit],
+  content: value,
+  immediatelyRender: false, // Critical for Next.js SSR
+  onUpdate: ({ editor }) => onChange(editor.getJSON()),
+})
+```
+
+## Package Structure
+
+```
+packages/tiptap/
+├── src/
+│   ├── fields/
+│   │   └── richText.ts       # Field builder
+│   ├── components/
+│   │   └── TiptapField.tsx   # React component
+│   ├── config/
+│   │   └── types.ts          # Type definitions
+│   └── index.ts              # Public exports
+├── package.json
+└── README.md
+```
+
+## Exports
+
+```typescript
+// Main export
+import { richText, TiptapField } from '@opensaas/stack-tiptap'
+
+// Subpath exports
+import { richText } from '@opensaas/stack-tiptap/fields'
+import { TiptapField } from '@opensaas/stack-tiptap/components'
+```
+
+## Example
+
+See `examples/tiptap-demo` for complete working example.
+
+## Key Principles
+
+1. **No Core Modifications** - Extends stack via `BaseFieldConfig`
+2. **Self-Contained** - All behavior in field config methods
+3. **Client Registration** - Components registered on client side
+4. **UI Options Pass-Through** - Custom options automatically pass to component
+5. **SSR Safe** - Next.js compatible with proper hydration
+6. **Type Safe** - Full TypeScript support
+
+This package serves as reference implementation for creating third-party field packages.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 OpenSaas Stack Contributors
+
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensaas/stack-tiptap",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Tiptap rich text editor integration for OpenSaas Stack",
   "type": "module",
   "main": "./dist/index.js",
@@ -28,8 +28,8 @@
     "next": "^15.0.0 || ^16.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@opensaas/stack-core": "0.1.0",
-    "@opensaas/stack-ui": "0.1.0"
+    "@opensaas/stack-core": "0.1.1",
+    "@opensaas/stack-ui": "0.1.1"
   },
   "dependencies": {
     "@tiptap/react": "^3.7.2",
@@ -43,8 +43,8 @@
     "@types/react": "^19.2.2",
     "@types/react-dom": "^19.2.2",
     "typescript": "^5.9.3",
-    "@opensaas/stack-core": "0.1.0",
-    "@opensaas/stack-ui": "0.1.0"
+    "@opensaas/stack-core": "0.1.1",
+    "@opensaas/stack-ui": "0.1.1"
   },
   "scripts": {
     "build": "tsc && npm run copy:css",