npm package: @kimonokit/storyblok-angular
Description: Angular SDK for Storyblok
Author: Benedikt Grimm
Latest version: 0.1.0

# @kimonokit/storyblok-angular

<div align="center">
  <h1>@kimonokit/storyblok-angular</h1>
  <p>
    The Angular SDK for <a href="http://www.storyblok.com" target="_blank">Storyblok</a>, featuring full Visual Editor integration and real-time updates.
    <br /><br />
    This is a first draft.
  </p>
</div>

## Features

- 🔄 Real-time Visual Editor integration
- 🎯 Dynamic component loading
- 📝 Rich text rendering
- 🌐 Full TypeScript support
- 🚀 SSR (Server-Side Rendering) compatible
- 🔌 API client included

## Installation

```bash
npm install @kimonokit/storyblok-angular
```

## Quick Start

1. Import the StoryblokModule in your app.module.ts:

```typescript
import { StoryblokModule } from "@kimonokit/storyblok-angular";

@NgModule({
  imports: [
    StoryblokModule.forRoot({
      accessToken: "your_access_token",
      bridge: true, // Enable Visual Editor
    }),
  ],
})
export class AppModule {}
```

2. Create your components and register them with Storyblok:

```typescript
import { Component } from "@angular/core";
import { StoryblokComponent } from "@kimonokit/storyblok-angular";

@Component({
  selector: "app-teaser",
  template: `
    <div [storyblokEditable]="blok">
      <h2>{{ blok.headline }}</h2>
      <p>{{ blok.description }}</p>
    </div>
  `,
})
export class TeaserComponent {
  blok: any;
}

// Register your component
StoryblokDynamicComponent.registerComponent("teaser", TeaserComponent);
```

3. Use the StoryblokService to fetch content:

```typescript
import { Component, OnInit } from "@angular/core";
import { StoryblokService } from "@kimonokit/storyblok-angular";

@Component({
  selector: "app-page",
  template: `
    <div *ngIf="story" [storyblokEditable]="story.content">
      <storyblok-component [blok]="story.content"></storyblok-component>
    </div>
  `,
})
export class PageComponent implements OnInit {
  story: any;

  constructor(private storyblok: StoryblokService) {}

  ngOnInit() {
    // Get your story
    this.storyblok.getStory("home").subscribe((story) => (this.story = story));

    // Listen for changes in Visual Editor
    this.storyblok.onStoryChange().subscribe((story) => {
      if (story) {
        this.story = story;
      }
    });
  }
}
```

## API Reference

### StoryblokService

The main service for interacting with Storyblok:

```typescript
// Fetch a single story
storyblok.getStory(slug: string, params?: any): Observable<StoryblokStory>

// Fetch multiple stories
storyblok.getStories(params?: any): Observable<StoryblokStory[]>

// Listen for Visual Editor changes
storyblok.onStoryChange(): Observable<StoryblokStory | null>

// Render rich text
storyblok.renderRichText(data: any): string

// Access the underlying API client
storyblok.apiClient: StoryblokClient
```

### StoryblokConfig

Configuration options when initializing the module:

```typescript
interface StoryblokConfig {
  accessToken: string;
  version?: "draft" | "published";
  bridge?: boolean;
  richTextSchema?: any;
  apiOptions?: {
    region?: "us" | "eu" | "ap" | "ca" | "cn";
    cache?: any;
    [key: string]: any;
  };
}
```

### Directives

- `[storyblokEditable]`: Makes a component editable in the Visual Editor
- `<storyblok-component>`: Dynamic component renderer

## Region Configuration

For spaces created in regions other than EU, specify the region in the configuration:

```typescript
StoryblokModule.forRoot({
  accessToken: "your_access_token",
  apiOptions: {
    region: "us", // 'us', 'eu', 'ap', 'ca', or 'cn'
  },
});
```

## Rich Text Rendering

You can customize rich text rendering by providing a schema:

```typescript
StoryblokModule.forRoot({
  accessToken: "your_access_token",
  richTextSchema: {
    // Your custom schema
  },
});
```

## TypeScript Support

The SDK includes TypeScript definitions for all Storyblok interfaces:

```typescript
import { StoryblokStory, StoryblokComponent } from "@kimonokit/storyblok-angular";

interface MyStoryContent extends StoryblokComponent {
  title: string;
  description: string;
}

// Use with generics
const story: StoryblokStory<MyStoryContent>;
```

## Contributing

We welcome contributions! Please feel free to submit a Pull Request.

## Support

- 🐛 For bug reports and feature requests, open an issue
- 📚 For documentation, visit [Storyblok Docs](https://www.storyblok.com/docs)

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.