@platecms/delta-client 0.4.1 → 0.7.0

package/README.md

@@ -1,148 +1,361 @@
-# 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());
+
+// Array handling with placeholders
+const tagsSchema = schema.array(
+  schema.string().placeholder('placeholder')
+).placeholder({ minLength: 1 });
+
+// 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": "0.7.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": "0.7.0",
     "@graphql-typed-document-node/core": "3.2.0",
     "graphql": "16.11.0",
     "lodash": "4.17.21",
@@ -34,8 +34,7 @@
     "./package.json": "./package.json",
     ".": {
       "import": "./index.esm.js",
-      "default": "./index.cjs.js",
-      "types": "./src/index.d.ts"
+      "default": "./index.cjs.js"
     },
     "./slate": {
       "types": "./src/slate/index.d.ts",
@@ -51,8 +50,7 @@
       "types": "./src/apollo/index.d.ts",
       "import": "./src/apollo/index.js",
       "default": "./src/apollo/index.cjs.js"
-    },
-    "./slate/index": "./src/slate/index.js"
+    }
   },
   "module": "./index.esm.js"
 }

package/src/__generated__/fragment-masking.ts

@@ -0,0 +1,87 @@
+/* eslint-disable */
+import { ResultOf, DocumentTypeDecoration, TypedDocumentNode } from '@graphql-typed-document-node/core';
+import { FragmentDefinitionNode } from 'graphql';
+import { Incremental } from './graphql';
+
+
+export type FragmentType<TDocumentType extends DocumentTypeDecoration<any, any>> = TDocumentType extends DocumentTypeDecoration<
+  infer TType,
+  any
+>
+  ? [TType] extends [{ ' $fragmentName'?: infer TKey }]
+    ? TKey extends string
+      ? { ' $fragmentRefs'?: { [key in TKey]: TType } }
+      : never
+    : never
+  : never;
+
+// return non-nullable if `fragmentType` is non-nullable
+export function useFragment<TType>(
+  _documentNode: DocumentTypeDecoration<TType, any>,
+  fragmentType: FragmentType<DocumentTypeDecoration<TType, any>>
+): TType;
+// return nullable if `fragmentType` is undefined
+export function useFragment<TType>(
+  _documentNode: DocumentTypeDecoration<TType, any>,
+  fragmentType: FragmentType<DocumentTypeDecoration<TType, any>> | undefined
+): TType | undefined;
+// return nullable if `fragmentType` is nullable
+export function useFragment<TType>(
+  _documentNode: DocumentTypeDecoration<TType, any>,
+  fragmentType: FragmentType<DocumentTypeDecoration<TType, any>> | null
+): TType | null;
+// return nullable if `fragmentType` is nullable or undefined
+export function useFragment<TType>(
+  _documentNode: DocumentTypeDecoration<TType, any>,
+  fragmentType: FragmentType<DocumentTypeDecoration<TType, any>> | null | undefined
+): TType | null | undefined;
+// return array of non-nullable if `fragmentType` is array of non-nullable
+export function useFragment<TType>(
+  _documentNode: DocumentTypeDecoration<TType, any>,
+  fragmentType: Array<FragmentType<DocumentTypeDecoration<TType, any>>>
+): Array<TType>;
+// return array of nullable if `fragmentType` is array of nullable
+export function useFragment<TType>(
+  _documentNode: DocumentTypeDecoration<TType, any>,
+  fragmentType: Array<FragmentType<DocumentTypeDecoration<TType, any>>> | null | undefined
+): Array<TType> | null | undefined;
+// return readonly array of non-nullable if `fragmentType` is array of non-nullable
+export function useFragment<TType>(
+  _documentNode: DocumentTypeDecoration<TType, any>,
+  fragmentType: ReadonlyArray<FragmentType<DocumentTypeDecoration<TType, any>>>
+): ReadonlyArray<TType>;
+// return readonly array of nullable if `fragmentType` is array of nullable
+export function useFragment<TType>(
+  _documentNode: DocumentTypeDecoration<TType, any>,
+  fragmentType: ReadonlyArray<FragmentType<DocumentTypeDecoration<TType, any>>> | null | undefined
+): ReadonlyArray<TType> | null | undefined;
+export function useFragment<TType>(
+  _documentNode: DocumentTypeDecoration<TType, any>,
+  fragmentType: FragmentType<DocumentTypeDecoration<TType, any>> | Array<FragmentType<DocumentTypeDecoration<TType, any>>> | ReadonlyArray<FragmentType<DocumentTypeDecoration<TType, any>>> | null | undefined
+): TType | Array<TType> | ReadonlyArray<TType> | null | undefined {
+  return fragmentType as any;
+}
+
+
+export function makeFragmentData<
+  F extends DocumentTypeDecoration<any, any>,
+  FT extends ResultOf<F>
+>(data: FT, _fragment: F): FragmentType<F> {
+  return data as FragmentType<F>;
+}
+export function isFragmentReady<TQuery, TFrag>(
+  queryNode: DocumentTypeDecoration<TQuery, any>,
+  fragmentNode: TypedDocumentNode<TFrag>,
+  data: FragmentType<TypedDocumentNode<Incremental<TFrag>, any>> | null | undefined
+): data is FragmentType<typeof fragmentNode> {
+  const deferredFields = (queryNode as { __meta__?: { deferredFields: Record<string, (keyof TFrag)[]> } }).__meta__
+    ?.deferredFields;
+
+  if (!deferredFields) return true;
+
+  const fragDef = fragmentNode.definitions[0] as FragmentDefinitionNode | undefined;
+  const fragName = fragDef?.name?.value;
+
+  const fields = (fragName && deferredFields[fragName]) || [];
+  return fields.length > 0 && fields.every(field => data && field in data);
+}

package/src/__generated__/gql.ts

@@ -0,0 +1,52 @@
+/* eslint-disable */
+import * as types from './graphql';
+import { TypedDocumentNode as DocumentNode } from '@graphql-typed-document-node/core';
+
+/**
+ * Map of all GraphQL operations in the project.
+ *
+ * This map has several performance disadvantages:
+ * 1. It is not tree-shakeable, so it will include all operations in the project.
+ * 2. It is not minifiable, so the string of a GraphQL query will be multiple times inside the bundle.
+ * 3. It does not support dead code elimination, so it will add unused operations.
+ *
+ * Therefore it is highly recommended to use the babel or swc plugin for production.
+ * Learn more about it here: https://the-guild.dev/graphql/codegen/plugins/presets/preset-client#reducing-bundle-size
+ */
+type Documents = {
+    "query tag($prn: [PRN!]!) {\n  tag(prn: $prn) {\n    ...tagFragment\n  }\n}": typeof types.TagDocument,
+    "fragment tagFragment on Tag {\n  _id: prn\n  prn\n  name\n  path\n  color\n  visibility\n  forceVisibilityOnDescendants\n  stage\n  amountOfChildren\n  amountOfContentExperiences\n  amountOfContentItems\n  hasForcedVisibility\n  nestingLevel\n  createdAt\n  updatedAt\n}": typeof types.TagFragmentFragmentDoc,
+};
+const documents: Documents = {
+    "query tag($prn: [PRN!]!) {\n  tag(prn: $prn) {\n    ...tagFragment\n  }\n}": types.TagDocument,
+    "fragment tagFragment on Tag {\n  _id: prn\n  prn\n  name\n  path\n  color\n  visibility\n  forceVisibilityOnDescendants\n  stage\n  amountOfChildren\n  amountOfContentExperiences\n  amountOfContentItems\n  hasForcedVisibility\n  nestingLevel\n  createdAt\n  updatedAt\n}": types.TagFragmentFragmentDoc,
+};
+
+/**
+ * The graphql function is used to parse GraphQL queries into a document that can be used by GraphQL clients.
+ *
+ *
+ * @example
+ * ```ts
+ * const query = graphql(`query GetUser($id: ID!) { user(id: $id) { name } }`);
+ * ```
+ *
+ * The query argument is unknown!
+ * Please regenerate the types.
+ */
+export function graphql(source: string): unknown;
+
+/**
+ * The graphql function is used to parse GraphQL queries into a document that can be used by GraphQL clients.
+ */
+export function graphql(source: "query tag($prn: [PRN!]!) {\n  tag(prn: $prn) {\n    ...tagFragment\n  }\n}"): (typeof documents)["query tag($prn: [PRN!]!) {\n  tag(prn: $prn) {\n    ...tagFragment\n  }\n}"];
+/**
+ * The graphql function is used to parse GraphQL queries into a document that can be used by GraphQL clients.
+ */
+export function graphql(source: "fragment tagFragment on Tag {\n  _id: prn\n  prn\n  name\n  path\n  color\n  visibility\n  forceVisibilityOnDescendants\n  stage\n  amountOfChildren\n  amountOfContentExperiences\n  amountOfContentItems\n  hasForcedVisibility\n  nestingLevel\n  createdAt\n  updatedAt\n}"): (typeof documents)["fragment tagFragment on Tag {\n  _id: prn\n  prn\n  name\n  path\n  color\n  visibility\n  forceVisibilityOnDescendants\n  stage\n  amountOfChildren\n  amountOfContentExperiences\n  amountOfContentItems\n  hasForcedVisibility\n  nestingLevel\n  createdAt\n  updatedAt\n}"];
+
+export function graphql(source: string) {
+  return (documents as any)[source] ?? {};
+}
+
+export type DocumentType<TDocumentNode extends DocumentNode<any, any>> = TDocumentNode extends DocumentNode<  infer TType,  any>  ? TType  : never;