@platecms/delta-client 0.4.1 → 1.0.0

package/README.md

@@ -1,148 +1,356 @@
-# delta-client-schema
+# @platecms/delta-client
 
-This library is part of the [Delta Client]() utility packages.
-It provides a utility to convert abstract building blocks and their values to usable data structures.
+Utilities and functions to interact with the Delta CMS.
 
-## Usage
+## Overview
 
-Defining a schema looks as follows consists of a root object and nested fields.
-For example for a building block that has a welcome message, the schema would look like this:
+The `@platecms/delta-client` package provides a comprehensive set of utilities for working with the Delta CMS. It includes schema parsing, Slate.js integration, Apollo Client setup, and various helper functions for content management.
 
-```ts
-import { s } from "@platecms/delta-client/schema";
-
-const heroBuildingBlock = s.object({
-    title: s.primitive(c('root', 'title')),
-    description: s.cast(c('root', 'description')),
-    images: s.array(s.asset())
-})
+## Installation
 
+```bash
+npm install @platecms/delta-client
 ```
 
-The schema can then be used to convert the abstract building block to a usable data structure:
+## Package Structure
 
-```ts
-import { p as parser } from "@platecms/delta-client/schema";
+This package is organized into several main modules:
 
-const heroBuildingBlock = parser.parse(schema, buildingBlockFieldFulfillments);
-```
+### 📦 Main Exports
+
+- **`@platecms/delta-client`** - Main package entry point
+- **`@platecms/delta-client/slate`** - Slate.js integration and type definitions
+- **`@platecms/delta-client/schema`** - Schema parsing and validation utilities
+- **`@platecms/delta-client/apollo`** - Apollo Client configuration and setup
+
+## Features
+
+### 🎯 Schema Parsing (`/schema`)
+
+The schema module provides a powerful type-safe way to parse and validate content from the Delta CMS.
+
+#### Basic Usage
+
+```typescript
+import { schema } from '@platecms/delta-client/schema';
+
+// Define a content structure
+const articleSchema = schema.buildingBlock({
+  // Multiple types for a field
+  title: [schema.string(), schema.number()],
+  content: schema.smartText(),
+  publishedAt: schema.date(),
+  featured: schema.boolean(),
+  // Array of items
+  tags: schema.array(schema.tag()),
+  // For related content items
+  author: schema.contentItem({
+    name: schema.string(),
+    email: schema.string(),
+  }),
+});
 
-Yields:
+// Parse content data
+const article = articleSchema.parse(buildingBlockFieldFulfillments);
 
-```ts
-const heroBuildingBlock = {
-    title: "Hero Title",
-    description: {
-        type: 'root',
+// Result
+{
+    title: "My article",
+    content: {
+        type: "root",
         children: [
             {
-                type: 'text',
-                value: 'Welcome to our website'
+                type: "paragraph",
+                children: [
+                    {
+                        type: "text",
+                        value: "My first article"
+                    }
+                ]
             }
         ]
     },
-    images: [
-        {
-            fileName: "first image",
-            url: 'https://example.com/image.jpg',
-        }
-    ]
+    publishedAt: new Date(),
+    featured: true,
+    tags: [{
+        name: "Higlighted",
+        //...other tag fields
+    }],
+    author: {
+        name: "Plate",
+        email: "my@email.com"
+    }
 }
 ```
 
-## API
-
-### Object
+#### Available Types
+
+- **`schema.string()`** - String values
+- **`schema.number()`** - Numeric values  
+- **`schema.boolean()`** - Boolean values
+- **`schema.date()`** - Date values
+- **`schema.asset()`** - Asset references
+- **`schema.smartText()`** - Rich text content
+- **`schema.contentItem()`** - Related content items
+- **`schema.buildingBlock()`** - Building block structures
+- **`schema.array()`** - Arrays of any schema
+- **`schema.gridPlacement()`** - Grid layout placements
+- **`schema.contentType()`** - Content type references
+- **`schema.pathPart()`** - URL path components
+- **`schema.tag()`** - Tag references
+
+#### Advanced Features
+
+```typescript
+// Nullable fields with placeholders
+const schema = schema.contentItem({
+  title: schema.string().nullable(false), // Required field, throws
+  description: schema.string().placeholder("No description available"), // Default value
+});
+
+// Array handling
+const tagsSchema = schema.array(schema.tag());
+
+// Nested structures
+const pageSchema = schema.buildingBlock({
+  hero: schema.contentItem({
+    title: schema.string(),
+    image: schema.asset(),
+  }),
+  sections: schema.array(schema.contentItem({
+    type: schema.string(),
+    content: schema.smartText(),
+  })),
+});
+```
 
-```ts
-s.object({
-    // shape of the object
-})
+### 🎨 Slate.js Integration (`/slate`)
+
+Provides TypeScript definitions and utilities for working with Slate.js in the Delta CMS context.
+
+#### Type Definitions
+
+```typescript
+import { DeltaElement, DeltaLeaf } from '@platecms/delta-client/slate';
+
+// Available element types
+type DeltaElement = 
+  | ParagraphElement
+  | HeadingElement  
+  | ListElement
+  | ListItemElement
+  | BlockquoteElement
+  | CodeElement
+  | ContentValueElement
+  | LinkElement;
+
+// Leaf node with formatting
+type DeltaLeaf = {
+  text: string;
+  bold?: true;
+  italic?: true;
+  underline?: true;
+  strikethrough?: true;
+  inlineCode?: true;
+  highlight?: true;
+  title?: true;
+};
 ```
 
-### Array
+### 🚀 Apollo Client Setup (`/apollo`)
 
-Default array with one placeholder
+Pre-configured Apollo Client for GraphQL communication with Delta CMS.
 
-```ts
-s.array(
-    s.primitive('value')
-)
-```
+#### Basic Setup
 
-Array with a limit of the maximum number of items to display
+```typescript
+import { createApolloClient } from '@platecms/delta-client/apollo';
 
-```ts
-s.array(
-    s.primitive('value'), 5 // limit to 5 items
-)
+const client = createApolloClient('https://api.delta-cms.com/graphql', {
+  name: 'delta-cms-client',
+  headers: {
+    'Authorization': 'Bearer your-token',
+  },
+});
 ```
 
-Array with an array of placeholders, also uses this a minimum number of items to display
-
-```ts
-s.array(
-    [
-        s.primitive('value'),
-        s.primitive('value'),
-        // other fields
-    ]
-)
+#### Advanced Configuration
+
+```typescript
+import { createApolloClient } from '@platecms/delta-client/apollo';
+import { onError } from '@apollo/client/link/error';
+
+const errorLink = onError(({ graphQLErrors, networkError }) => {
+  if (graphQLErrors) {
+    graphQLErrors.forEach(({ message, locations, path }) =>
+      console.log(`GraphQL error: Message: ${message}, Location: ${locations}, Path: ${path}`)
+    );
+  }
+});
+
+const client = createApolloClient('https://api.delta-cms.com/graphql', {
+  name: 'delta-cms-client',
+  errorLink,
+  headers: {
+    'X-Custom-Header': 'value',
+  },
+});
 ```
 
-### Primitive
+### 🛠️ Utilities (`/utils`)
 
-#### string
+Helper functions and connectors for Delta CMS integration.
 
-```ts
-s.primitive('value')
+#### Connectors
+
+```typescript
+import { WindowConnector, ConnectorEvents } from '@platecms/delta-client/utils';
+
+// Window-based communication
+const connector = new WindowConnector();
+connector.on(ConnectorEvents.CONTENT_UPDATED, (data) => {
+  console.log('Content updated:', data);
+});
 ```
 
-#### number
+#### Draft Types
+
+```typescript
+import { Draft } from '@platecms/delta-client/utils';
+
+type DraftArticle = Draft<{
+  title: string;
+  content: string;
+}>;
 
-```ts
-s.primitive(23)
+// Draft objects include isDraft and uuid properties
+const draft: DraftArticle = {
+  title: "My Article",
+  content: "Article content...",
+  isDraft: true,
+  uuid: "123e4567-e89b-12d3-a456-426614174000",
+};
 ```
 
-### Asset
+## API Reference
 
-Accepts a partial Asset object as a placeholder
+### Schema schemas
 
-```ts
-s.asset({
-    fileName: 'first',
-    url: 'https://example.com/image.jpg'
-})
+All schemas support the following methods:
+
+- **`.nullable(boolean)`** - Set whether the field can be null
+- **`.placeholder(value)`** - Set default value when data is missing
+- **`.parse(data, config?)`** - Parse data with optional configuration
+
+### Configuration Options
+
+```typescript
+interface schemaConfig {
+  placeholders?: boolean; // Enable placeholder values
+}
 ```
 
-### PathPart
+### Apollo Client Options
 
-Accepts a partial PathPart object as a placeholder
+```typescript
+interface ApolloClientOptions {
+  name?: string;
+  errorLink?: ApolloLink;
+  headers?: Record<string, string>;
+}
+```
+
+## Examples
+
+### Complete Content Parsing Example
+
+```typescript
+import { schema } from '@platecms/delta-client/schema';
+import { createApolloClient } from '@platecms/delta-client/apollo';
+
+// Define schema
+const blogPostSchema = schema.contentItem({
+  title: schema.string().nullable(false),
+  excerpt: schema.string().placeholder("No excerpt available"),
+  content: schema.smartText(),
+  author: schema.contentItem({
+    name: schema.string(),
+    avatar: schema.asset(),
+  }),
+  tags: schema.array(schema.tag()),
+  publishedAt: schema.date(),
+  featured: schema.boolean().placeholder(false),
+});
+
+// Setup Apollo Client
+const client = createApolloClient('https://api.delta-cms.com/graphql');
+
+// Parse content
+const blogPost = blogPostSchema.parse(contentValue, { placeholders: true });
+```
 
-```ts
-s.pathPart({
-    path: '/blogs',
-})
+### Slate.js Editor Integration
+
+```typescript
+import { BaseEditor } from 'slate';
+import { ReactEditor } from 'slate-react';
+import { DeltaElement, DeltaLeaf } from '@platecms/delta-client/slate';
+
+// Type your editor
+type CustomEditor = BaseEditor & ReactEditor;
+
+// Use in your editor component
+const MyEditor = () => {
+  const editor = useMemo(() => withReact(createEditor()), []);
+  
+  // Your editor implementation
+  return (
+    <Slate editor={editor} value={value} onChange={setValue}>
+      <Editable />
+    </Slate>
+  );
+};
 ```
 
-### GridPlacement
+## Dependencies
 
-Accepts a partial GridPlacement object as a placeholder
+### Peer Dependencies
 
-```ts
-s.gridPlacement({
-    prn: 'prn:grid:123',
-    row: 1
-})
+- `@platecms/delta-cast` - Core casting utilities
+- `@graphql-typed-document-node/core` - GraphQL type safety
+- `graphql` - GraphQL implementation
+- `lodash` - Utility functions
+- `slate` - Rich text editor framework
+- `slate-react` - React integration for Slate
+- `tslib` - TypeScript runtime library
+- `class-transformer` - Object transformation
+- `reflect-metadata` - Metadata reflection
+- `@apollo/client` - GraphQL client
+- `defu` - Object merging utility
+
+## Development
+
+This package is part of the Delta monorepo and uses Nx for build orchestration.
+
+### Building
+
+```bash
+nx build delta-client
 ```
 
-### Cast
+### Testing
 
-Accepts a correct root object to cast the schema to a usable data structure
+```bash
+nx test delta-client
+```
+
+### Linting
 
-```ts
-s.cast({
-    type: 'root',
-    children: []
-})
+```bash
+nx lint delta-client
 ```
+
+## Repository
+
+- **Homepage**: https://bitbucket.org/startmetplate/delta/src/dev/packages/delta-client
+- **Repository**: https://bitbucket.org/startmetplate/delta.git

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platecms/delta-client",
-  "version": "0.4.1",
+  "version": "1.0.0",
   "description": "Utilities and functions to interact with the Delta CMS.",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -18,7 +18,7 @@
     "src/**/*"
   ],
   "peerDependencies": {
-    "@platecms/delta-cast": "0.4.1",
+    "@platecms/delta-cast": "1.0.0",
     "@graphql-typed-document-node/core": "3.2.0",
     "graphql": "16.11.0",
     "lodash": "4.17.21",