블록 타입 가이드 소개

Notionpresso은 Notion의 다양한 블록 타입을 지원하며, 각 블록 타입에 대해 Notion과 최대한 유사한 스타일의 컴포넌트를 제공합니다. 이 가이드에서는 현재 지원되는 블록 타입들, 각 블록 타입의 Props, 커스터마이징 방법, 그리고 내부 동작 원리에 대해 설명합니다.

지원되는 블록 타입

Notionpresso에서 현재 지원되는 블록 타입과 지원 예정인 블록 타입들의 목록입니다:

Block Type	지원 여부	Block Type Enum
Paragraph	✅ Yes	`paragraph`
Heading 1	✅ Yes	`heading_1`
Heading 2	✅ Yes	`heading_2`
Heading 3	✅ Yes	`heading_3`
Bulleted List Item	✅ Yes	`bulleted_list_item`
Numbered List Item	✅ Yes	`numbered_list_item`
To-do	❌ No	`to_do`
Toggle	✅ Yes	`toggle`
Quote	✅ Yes	`quote`
Callout	✅ Yes	`callout`
Equation	❌ No	`equation`
Code	❌ No	`code`
Image	❌ No	`image`
Video	❌ No	`video`
Bookmark	❌ No	`bookmark`
Divider	✅ Yes	`divider`
Table	❌ No	`table`
Table Row	❌ No	`table_row`
Column	❌ No	`column`
Column List	❌ No	`column_list`
Audio	❌ No	`audio`
Synced Block	❌ No	`synced_block`
Table Of Contents	❌ No	`table_of_contents`
Embed	❌ No	`embed`
Figma	❌ No	`figma`
Google Maps	❌ No	`maps`
Google Drive	❌ No	`drive`
Tweet	❌ No	`tweet`
PDF	❌ No	`pdf`
File	❌ No	`file`
Link	❌ No	`text` (inline)
Page Link	❌ No	`page`
External Page Link	❌ No	`text` (inline)
Collections	❌ No	-
Collection View	❌ No	`collection_view`
Collection View Table	❌ No	`collection_view`
Collection View Gallery	❌ No	`collection_view`
Collection View Board	❌ No	`collection_view`
Collection View List	❌ No	`collection_view`
Collection View Calendar	❌ No	`collection_view`
Collection View Page	❌ No	`collection_view_page`

이 목록은 지속적으로 업데이트될 예정이며, 향후 더 많은 블록 타입을 지원할 계획입니다.

Props 사용법

Notionpresso은 각 블록 타입에 대한 Props 타입을 제공합니다. 이러한 Props 타입들은 라이브러리에서 직접 import하여 사용할 수 있습니다.

예를 들어, Paragraph 컴포넌트의 Props는 다음과 같이 import하고 사용할 수 있습니다:

import { ParagraphProps } from "@notionpresso/react";

// ParagraphProps의 구조
interface ParagraphProps {
  type: "paragraph";
  paragraph: {
    rich_text: Array<RichTextItemResponse>;
    color: string;
  };
  id: string;
  has_children?: boolean;
}

// 사용 예시
const MyParagraph: React.FC<ParagraphProps> = (props) => {
  // 커스텀 구현
};

각 블록 타입별 Props의 상세한 구조는 해당 블록 타입 문서에서 확인할 수 있습니다.

커스텀 컴포넌트 적용

Notionpresso의 큰 장점 중 하나는 각 블록 타입에 대해 커스텀 컴포넌트로 완전히 교체할 수 있다는 점입니다. 커스텀 컴포넌트를 적용하는 방법은 다음과 같습니다:

import { Notion } from "@notionpresso/react";
import CustomParagraph from "./CustomParagraph";
import CustomHeading from "./CustomHeading";

const customComponents = {
  paragraph: CustomParagraph,
  heading_1: CustomHeading,
  heading_2: CustomHeading,
  heading_3: CustomHeading,
  // ... 기타 블록 타입에 대한 커스텀 컴포넌트
};

function MyNotionPage({ blocks }) {
  return (
    <Notion custom={customComponents}>
      <Notion.Blocks blocks={blocks} />
    </Notion>
  );
}

Notion 컴포넌트에 주입되는 components의 타입은 다음과 같습니다:

type NotionComponents = Record<string, React.ComponentType<any>>;

여기서 key는 Notion 블록의 타입(예: 'paragraph', 'heading_1' 등)이고, value는 해당 타입을 렌더링할 React 컴포넌트입니다.

데이터 전처리 과정

Notionpresso은 Notion API에서 가져온 블록 데이터를 UI 렌더링에 최적화된 형태로 전처리합니다. 이 과정에서 ContextedBlock이라는 새로운 타입을 정의하여 사용합니다.

+----------------------+
|    Notion API        |
|    Block Data        |
| +------------------+ |
| | Block            | |
| | - id             | |
| | - type           | |
| | - has_children   | |
| | - [type_specific]| |
| +------------------+ |
+----------------------+
           |
           | (Input)
           v
+---------------------------+
| resolveToContextedBlocks  |
| +-------------------------+
| | For each block:         |
| | +---------------------+ |
| | |resolveToContextedBlo| |
| | |ck (recursive)       | |
| | +---------------------+ |
| |   |                     |
| |   v                     |
| | Map parent-child        |
| | relationships           |
| +-------------------------+
|   |
|   v
| Map sibling relationships |
+---------------------------+
           |
           | (Output)
           v
+---------------------------+
|     ContextedBlocks       |
| +-------------------------+
| | ContextedBlock          |
| | - ...Block properties   |
| | - context:              |
| |   - previous (sibling)  |
| |   - next (sibling)      |
| |   - parent              |
| | - blocks (children)     |
| +-------------------------+
+---------------------------+
           |
           | (Used by)
           v
    +----------------+
    | Notion.Blocks  |
    | Component      |
    +----------------+

ContextedBlock은 기존 Block 타입을 확장하여 다음과 같은 추가 정보를 포함합니다:

이전 블록 (형제 관계)
다음 블록 (형제 관계)
부모 블록

이러한 추가 정보는 특정 블록 컴포넌트에서 유용하게 사용될 수 있습니다.

렌더링 프로세스

Notionpresso의 렌더링 프로세스는 다음과 같습니다:

+-------------------+      +------------------+
|   Custom          |      |   Default        |
|   Components      |      |   Components     |
+-------------------+      +------------------+
          |                         |
          |   +-----------------+   |
          +-->|     Notion      |<--+
              |    Component    |
              |(React.Provider) |
              +-----------------+
                    |     |
         +----------+     +------------+
         |                             |
+----------------+             +----------------+
| Notion.Cover   |             | Notion.Body    |
+----------------+             +----------------+
                                       |
                               +----------------+
                               | Notion.Title   |
                               +----------------+
                                       |
                               +----------------+
                               | Notion.Blocks  |
                               +----------------+
                                       |
                                       v
                               +----------------+
                               | Rendered       |
                               | Notion Page    |
                               +----------------+

이 프로세스를 통해 커스텀 컴포넌트와 기본 컴포넌트가 함께 작동하여 Notion 페이지를 렌더링합니다.

스타일링

현재 제공되는 Notion 컴포넌트들은 Notion의 스타일을 최대한 유사하게 구현했습니다. 각 컴포넌트는 notion- 접두사를 가진 CSS 클래스를 사용하여 스타일링되어 있습니다.

향후 계획

더 많은 블록 타입 지원 추가
테마를 적용한 컴포넌트 셋 개발
고급 커스터마이징 옵션 확장

이어지는 페이지들에서 각 블록 타입에 대한 상세한 설명, Props 구조, 사용 예시, 그리고 커스터마이징 옵션을 확인할 수 있습니다.