okno 1.0.0-alpha.1 → 1.0.0-beta5

package/README.md

@@ -0,0 +1,695 @@
+# okno Documentation
+
+## Introduction
+
+okno is a developer-friendly headless CMS with live editing capabilities for static and dynamic sites.
+
+### Installation
+
+```bash
+npm install okno
+npm install okno/astro  # Framework adapter
+
+```
+
+### Quick Start
+
+```tsx
+// /okno.ts
+import { schema, collection, page, string, richtext } from "okno"
+
+export const okno= schema({
+  articles: collection({
+    title: string(),
+    content: richtext()
+  }),
+
+  home: page({
+    heroTitle: string()
+  })
+})
+
+// Use in your components
+import { okno } from "@/okno"
+
+const articles = okno("articles")
+const homeTitle = okno("home.heroTitle")
+
+```
+
+---
+
+## Schema
+
+### Types
+
+okno has three content types:
+
+**Collections** - Multiple items (e.g., blog posts, products)
+
+```tsx
+articles: collection({
+  title: string(),
+  slug: slug("title"),
+  content: richtext()
+}).draftable()
+
+```
+
+**Pages** - Single items with optional routes (e.g., Home, About)
+
+```tsx
+home: page({
+  heroTitle: string(),
+  heroImage: media().image()
+}).route('/')
+
+```
+
+**Globals** - Site-wide singletons (e.g., Navbar, Footer, Settings)
+
+```tsx
+navbar: global({
+  logo: media().image(),
+  links: string().array()
+})
+
+```
+
+### Fields
+
+### Basic Fields
+
+```tsx
+// String types
+string()            // Basic text field, required by default
+string().optional() // Optional text field
+string().max(200)   // Length limit
+string().min(10)    // Minimum length
+string().email()    // Email validation
+string().url()      // URL validation
+string().phone()    // Phone validation
+string().pattern(/^[a-z0-9-]+$/) // Regex pattern
+string().array()    // Array of strings
+string().default('hello') // Default value
+string().help("Enter your full name") // Help text in editor
+string().protected() // Not editable in UI
+
+// Numbers
+number()            // Numeric field
+number().min(0).max(100) // With range
+number().default(0) // Default value
+
+// Boolean
+boolean()           // True/false
+boolean().default(false)
+
+// Enums
+enum(['draft', 'published', 'archived'])
+enum(['javascript', 'svelte', 'typescript']).multiple() // Multi-select
+
+// Dates
+date()              // Date field
+date().default(() => new Date()) // Dynamic default
+
+// Rich content
+richtext()          // HTML content field
+richtext().slots(['price', 'date']) // With dynamic slots
+markdown()          // TODO: Markdown content field (future)
+
+// Media
+media()             // Accept any media type
+media().image()     // Only images
+media().video()     // Only videos
+media().audio()     // Only audio
+media().document()  // Only documents (PDF, Word, etc)
+
+// Media with multiple types and rules
+media()
+  .image({ maxWidth: 1920, maxHeight: 1080, format: ['jpg', 'png', 'webp'] })
+  .video({ maxSize: '100MB', maxDuration: 300 })
+  .document({ maxSize: '10MB', accept: ['pdf', 'docx'] })
+
+```
+
+### System Fields
+
+```tsx
+slug("fieldName")   // Auto-generated from field
+
+```
+
+### Built-in Fields (Collections Only)
+
+All **collection items** automatically include:
+
+- `id` - unique identifier
+- `slug` - URL-friendly key (defined with `slug("fieldName")`)
+- `created` - timestamp
+- `updated` - timestamp
+- `published` - timestamp or null (for draftable collections)
+- `createdBy` - user reference
+- `updatedBy` - user reference
+- `publishedBy` - user reference or null
+
+Pages and globals do not have these fields - they are singletons identified by their key name.
+
+### Groups
+
+Organize related fields in the editor UI:
+
+```tsx
+article: collection({
+  title: string(),
+  content: richtext(),
+
+  seo: group({
+    metaTitle: string().max(60).help("Appears in search results"),
+    metaDescription: string().max(160),
+    ogImage: media().image()
+  }),
+
+  advanced: group({
+    customCSS: string().optional(),
+    trackingCode: string().optional()
+  })
+})
+
+// Access with dot notation
+okno("articles.my-post.seo.metaTitle")
+
+```
+
+### Conditional Fields
+
+Show/hide fields based on other field values:
+
+```tsx
+post: collection({
+  type: enum(['article', 'video', 'podcast']),
+
+  // Only show when type is 'article'
+  content: richtext().when('type', 'article'),
+
+  // Only show when type is 'video'
+  videoUrl: string().url().when('type', 'video'),
+  videoThumbnail: media().image().when('type', 'video'),
+
+  // Show when type is either 'video' or 'podcast'
+  duration: number().min(0).when('type', ['video', 'podcast'])
+})
+
+```
+
+Groups can also be conditional:
+
+```tsx
+article: collection({
+  type: enum(['article', 'video', 'podcast']),
+  premium: boolean().default(false),
+
+  // Show entire video group only when type is 'video'
+  video: group({
+    url: string().url().required(),
+    thumbnail: media().image(),
+    duration: number().min(0),
+    subtitles: string().optional()
+  }).when('type', 'video'),
+
+  // Show entire SEO group only when premium is true
+  seo: group({
+    metaTitle: string().max(60),
+    metaDescription: string().max(160),
+    ogImage: media().image()
+  }).when('premium', true)
+})
+
+```
+
+### Default Values
+
+```tsx
+article: collection({
+  status: enum(['draft', 'published']).default('draft'),
+  views: number().default(0),
+  featured: boolean().default(false),
+  publishedAt: date().default(() => new Date()),
+  tags: enum(['js', 'css', 'html']).multiple().default(['js'])
+})
+
+```
+
+### References
+
+Reference other collections:
+
+```tsx
+reference("collection")       // Single reference
+reference("collection").multiple() // Multiple references
+
+// Example
+articles: collection({
+  title: string(),
+  category: reference("categories"),
+  relatedPosts: reference("articles").multiple()
+})
+
+```
+
+### Users
+
+The `users` collection is special - it links to PocketBase authentication.
+
+### Defining Users
+
+```tsx
+users: collection({
+  bio: string().optional(),
+  avatar: media().image().optional(),
+  website: string().url().optional()
+})
+
+```
+
+When users authenticate, okno auto-creates their `users` record linked to their PocketBase auth user.
+
+### User References
+
+```tsx
+user()              // Reference to users collection
+user().multiple()   // Multiple user references
+user().default("current") // Default to logged-in user
+
+// Example
+articles: collection({
+  title: string(),
+  author: user().default("current"),
+  contributors: user().multiple()
+})
+
+```
+
+### Localization
+
+Enable multiple languages:
+
+```tsx
+export const okno = schema({
+  articles: collection({
+    title: string().localized(),
+    slug: slug("title"), // not localized
+    content: richtext().localized(),
+    featuredImage: media().image() // same for all locales
+  }).localized()
+})
+.locales({
+  en: locale({ name: "English", default: true }),
+  es: locale({ name: "Español" }),
+  "cs-CZ": locale({ name: "Čeština" })
+})
+
+```
+
+Content structure with locales:
+
+```tsx
+{
+  id: "123",
+  slug: "my-article",
+  title: {
+    en: "My Article",
+    es: "Mi Artículo",
+    "cs-CZ": "Můj článek"
+  },
+  content: {
+    en: "English content",
+    es: "Contenido en español"
+  }
+}
+
+```
+
+Query with locale:
+
+```tsx
+// Specific locale
+okno("articles", { locale: "es" })
+
+// All locales
+okno("articles", { locale: "*" }) // default
+
+// With fallback
+okno("articles", { locale: "es", fallback: ["en"] })
+
+```
+
+### Config
+
+Configuration is chained after schema and/or locales:
+
+```tsx
+export const okno = schema({
+  users: collection({...}),
+  articles: collection({...})
+})
+.locales({
+  en: locale({ name: "English", default: true })
+})
+.config({
+  siteUrl: 'https://mysite.com' // Required for user invitations
+})
+
+```
+
+### User Invitations
+
+The `siteUrl` enables user invitations in the editor:
+
+1. Owner clicks "Invite user" in editor
+2. Enters email and role (owner/editor/viewer)
+3. Invitation email sent: `https://mysite.com/invite?token=xyz`
+4. Recipient registers/logs in via PocketBase
+5. okno auto-creates their `users` record
+6. User has access to the space
+
+Without `siteUrl`, invite button is disabled with a setup warning.
+
+### Forms
+
+_Forms are not the current priority._
+
+Define forms in your schema:
+
+```tsx
+contact: form({
+  name: string().required(),
+  email: string().email().required(),
+  password: string().required(),
+  message: textarea().required()
+})
+
+```
+
+Spread forms and fields for automatic handling:
+
+```tsx
+<form {...okno("forms.contact")}>
+  {/* Fields auto-detect type from schema */}
+  <input {...okno("forms.contact.name")} />
+  {/* → type="text", name="name", required, etc. */}
+
+  <input {...okno("forms.contact.email")} />
+  {/* → type="email", name="email", required, etc. */}
+
+  {/* Override type when needed */}
+  <input {...okno("forms.contact.password")} type="password" />
+  {/* → type="password" (overridden), name="password", required, etc. */}
+
+  <textarea {...okno("forms.contact.message")}></textarea>
+
+  <button type="submit">Send</button>
+</form>
+
+{/* Error handling per field */}
+{#each okno("forms.contact.email").errors() as error}
+  <span class="error">{error.message}</span>
+{/each}
+
+```
+
+The form spread provides `onSubmit` that prevents default and POSTs to custom PocketBase endpoint.
+
+---
+
+## Query
+
+### Basic
+
+```tsx
+import { okno } from "@/okno"
+
+// Get single item by key
+okno("home.heroTitle")
+
+// Get collection
+okno("articles")
+
+// Get by slug
+okno("articles", { slug: "getting-started" })
+
+// Get by ID
+okno("articles", { id: "rec_123" })
+
+// Get specific fields
+okno("articles", { select: ["title", "slug", "excerpt"] })
+
+```
+
+### Filters
+
+```tsx
+// Simple filters
+okno("articles", {
+  where: {
+    featured: true,
+    category: "tutorial"
+  }
+})
+
+// Sorting
+okno("articles", {
+  sort: "-publishedAt" // Descending
+})
+
+okno("articles", {
+  sort: "title" // Ascending
+})
+
+// Limit
+okno("articles", {
+  limit: 10
+})
+
+// Combine filters, sorting, and limit
+okno("articles", {
+  where: { featured: true, category: "tutorial" },
+  sort: "-publishedAt",
+  limit: 10,
+  select: ["title", "slug", "excerpt"]
+})
+
+//TODO: pagination?
+```
+
+### Drafts
+
+For draftable collections:
+
+```tsx
+articles: collection({...}).draftable()
+```
+
+Content can be in three states:
+
+1. **Draft** - Created but not published
+2. **Published** - Live content
+3. **Published with edits** - Has unpublished changes
+
+Query drafts:
+
+```tsx
+okno("articles")                    // Published only (default)
+okno("articles", { drafts: true })  // Include drafts
+okno("articles", { drafts: 'only' }) // Only drafts
+
+```
+
+### Slots
+
+Define dynamic content placeholders:
+
+```tsx
+articles: collection({
+  content: richtext().slots(['price', 'count', 'date'])
+})
+
+// TODO: non defined slots, just .slots() and create them on the go.
+```
+
+Content with placeholders:
+
+```tsx
+{
+  content: "We have {{count}} items starting at {{price}}. Sale ends {{date}}!"
+}
+
+```
+
+Populate slots dynamically:
+
+```tsx
+okno("sale.content", {
+  slots: {
+    count: inventory.length,
+    price: "$9.99",
+    date: "March 31st"
+  }
+})
+// Returns: "We have 42 items starting at $9.99. Sale ends March 31st!"
+
+```
+
+---
+
+## Editor
+
+### Framework Support
+
+```bash
+npm install okno
+npm install okno/astro  # or okno/vite, okno/next, etc.
+```
+
+Framework adapters:
+
+```tsx
+// astro.config.mjs
+import { okno } from "okno/astro"
+
+// vite.config.js
+import { okno } from "okno/vite"
+```
+
+The editor is imported separately and handles live editing in the browser.
+
+### Content Rendering
+
+### Editable Content
+
+```
+<!-- Text content needs set:html for edit spans -->
+<h1 set:html={okno("home.title")} />
+
+<!-- Images don't need special handling -->
+<img {...okno("home.heroImage")} />
+
+```
+
+### Non-editable Context
+
+```
+<!-- Get plain text without HTML -->
+<meta name="description" content={okno("home.title", { plain: true })} />
+
+<!-- Get raw HTML without edit spans -->
+<div set:html={okno("home.content", { raw: true })} />
+
+```
+
+### Data Attributes
+
+All non-text content automatically includes `data-okno` attributes for editor targeting:
+
+```tsx
+// Images include data-okno
+okno("home.heroImage")
+// Returns:
+{
+  src: "/hero.jpg",
+  alt: "Hero image",
+  width: 1920,
+  height: 1080,
+  "data-okno": "home.heroImage"
+}
+
+// Just spread and it works
+<img {...okno("home.heroImage")} />
+// Renders: <img src="..." data-okno="home.heroImage" />
+
+```
+
+### Collection Items
+
+For collections, each item's fields include the specific item ID:
+
+```tsx
+const articles = okno("articles")
+
+articles.map(article => (
+  <article>
+    {/* Text fields are wrapped automatically */}
+    <h2 set:html={article.title} />
+
+    {/* Images include the specific article ID */}
+    <img {...article.featuredImage} />
+    {/* Renders: <img src="..." data-okno="articles.abc-123.featuredImage" /> */}
+  </article>
+))
+
+```
+
+### Data Attribute Format
+
+- **Direct queries**: `data-okno="home.heroImage"`
+- **Collection items**: `data-okno="articles.{id}.featuredImage"`
+- **Nested fields**: `data-okno="home.hero.backgroundImage"`
+
+This allows the editor to precisely target any piece of content for editing.
+
+---
+
+## TODO: Future Features
+
+The following features are planned but not yet implemented:
+
+### Rich Text Editor Configuration
+
+- Toolbar customization
+- Custom blocks/components
+- Image upload handling within richtext
+- Embed support (YouTube, Twitter, etc.)
+
+### Media Upload Configuration
+
+- Global upload limits (size, dimensions)
+- Storage provider configuration
+- Image optimization settings
+- CDN integration
+
+### Collection Ordering
+
+```tsx
+articles: collection({...}).sortable() // Manual drag-and-drop ordering
+```
+
+### Custom Validation Messages
+
+```tsx
+email: string().email("Please enter a valid email address")
+age: number().min(18, "Must be 18 or older")
+```
+
+### Full-Text Search
+
+```tsx
+okno("articles", { search: "keyword" }) // Search across all text fields
+okno("articles", { search: "keyword", fields: ["title", "content"] })
+
+```
+
+### Webhooks
+
+```tsx
+articles: collection({...})
+  .webhook({
+    onPublish: 'https://api.example.com/notify',
+    onUpdate: 'https://api.example.com/sync'
+  })
+```
+
+### Draft Preview URLs
+
+```tsx
+articles: collection({...})
+  .preview((item) => `/preview/${item.slug}?token=${item.previewToken}`)
+```

package/dist/adapters/astro.d.ts

@@ -0,0 +1,3 @@
+import type { AstroIntegration } from "astro";
+export declare function okno(): AstroIntegration;
+//# sourceMappingURL=astro.d.ts.map

package/dist/adapters/astro.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"astro.d.ts","sourceRoot":"","sources":["../../adapters/astro.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAC;AAK9C,wBAAgB,IAAI,IAAI,gBAAgB,CA4DvC"}