Merge pull request #163 from 01-binary/refactor/code-review-improvements-4

refactor(notion-to-jsx): 타입 안전성 강화, Props 전달 컨벤션 통일

Author: 01-binary

.changeset/slow-cars-wait.md

@@ -0,0 +1,5 @@
+---
+"notion-to-jsx": patch
+---
+
+타입 안전성 강화, Props 전달 컨벤션 통일

packages/notion-to-jsx/src/components/Cover/styles.css.ts

@@ -1,5 +1,6 @@
 import { style } from '@vanilla-extract/css';
 import { recipe } from '@vanilla-extract/recipes';
+export { skeletonWrapper } from '../../styles/loadingOverlay.css';
 
 export const coverContainer = style({
   position: 'relative',
@@ -18,31 +19,6 @@ export const coverContainer = style({
   },
 });
 
-export const skeletonWrapper = recipe({
-  base: {
-    position: 'absolute',
-    top: 0,
-    left: 0,
-    width: '100%',
-    height: '100%',
-    zIndex: 1,
-    transition: 'opacity 0.3s ease',
-  },
-  variants: {
-    isLoaded: {
-      true: {
-        opacity: 0,
-      },
-      false: {
-        opacity: 1,
-      },
-    },
-  },
-  defaultVariants: {
-    isLoaded: false,
-  },
-});
-
 export const imageStyle = recipe({
   base: {
     width: '100%',

packages/notion-to-jsx/src/components/Renderer/components/Block/BlockRenderer.tsx

@@ -39,7 +39,8 @@ type BlockRendererMap = {
  *
  * Props 전달 컨벤션:
  * - children이 있는 블록(Toggle, Table, ColumnList): block 통째 전달 (children 접근 필요)
- * - 그 외: 필요한 데이터만 추출하여 전달
+ * - 텍스트 블록(paragraph, heading): children으로 RichText 전달
+ * - 미디어/콘텐츠 블록: block.[type] 콘텐츠 객체를 전달 (컴포넌트가 내부 구조 처리)
  */
 const blockRenderers: BlockRendererMap = {
   link_preview: (block) => <MemoizedLinkPreview url={block.link_preview.url} />,
@@ -68,48 +69,29 @@ const blockRenderers: BlockRendererMap = {
     </Heading3>
   ),
 
-  code: (block) => (
-    <div>
-      <CodeBlock
-        code={block.code.rich_text.map(rt => rt.plain_text).join('')}
-        language={block.code.language}
-        caption={block.code.caption}
-      />
-    </div>
-  ),
+  code: (block) => <CodeBlock code={block.code} />,
 
   image: (block, isColumn) => (
     <figure>
-      <MemoizedImage
-        src={block.image.file?.url || block.image.external?.url || ''}
-        alt={block.image.caption?.[0]?.plain_text || 'Notion image'}
-        caption={block.image.caption}
-        format={block.image.format}
-        isColumn={isColumn}
-      />
+      <MemoizedImage image={block.image} isColumn={isColumn} />
     </figure>
   ),
 
-  bookmark: (block) => (
-    <MemoizedBookmark
-      url={block.bookmark.url}
-      metadata={block.bookmark.metadata}
-    />
-  ),
+  bookmark: (block) => <MemoizedBookmark bookmark={block.bookmark} />,
 
   column_list: (block) => <ColumnList block={block} />,
 
   column: () => null,
 
-  quote: (block) => <Quote richTexts={block.quote.rich_text} />,
+  quote: (block) => <Quote quote={block.quote} />,
 
   table: (block) => <Table block={block} />,
 
   toggle: (block) => <Toggle block={block} />,
 
   video: (block) => <Video video={block.video} />,
 
-  embed: (block) => <Embed url={block.embed.url} caption={block.embed.caption} />,
+  embed: (block) => <Embed embed={block.embed} />,
 };
 
 const BlockRenderer = memo(({ block, isColumn = false }: BlockRendererProps) => {

packages/notion-to-jsx/src/components/Renderer/components/Bookmark/Bookmark.tsx

@@ -11,15 +11,17 @@ import {
   favicon,
   urlText,
 } from './styles.css';
-import { OpenGraphData } from './type';
+import type { BookmarkBlock } from 'notion-types';
 import ExternalLink from '../shared/ExternalLink';
 
+type BookmarkData = BookmarkBlock['bookmark'];
+
 export interface BookmarkProps {
-  url: string;
-  metadata?: OpenGraphData;
+  bookmark: BookmarkData;
 }
 
-const Bookmark = ({ url, metadata }: BookmarkProps) => {
+const Bookmark = ({ bookmark }: BookmarkProps) => {
+  const { url, metadata } = bookmark;
   const [isImageBroken, setIsImageBroken] = useState(false);
 
   return (

packages/notion-to-jsx/src/components/Renderer/components/Caption/Caption.tsx

@@ -1,5 +1,5 @@
 import { memo } from 'react';
-import { RichTextItem } from '../RichText/RichTexts';
+import type { RichTextItem } from 'notion-types';
 import { MemoizedRichText } from '../MemoizedComponents';
 import { captionStyle } from './styles.css';
 

packages/notion-to-jsx/src/components/Renderer/components/Code/CodeBlock.tsx

@@ -2,7 +2,7 @@ import { ReactNode, useState, useEffect, useMemo, memo } from 'react';
 import { codeBlock } from './styles.css';
 import Prism, { Grammar, Token } from 'prismjs';
 import { Caption } from '../Caption';
-import { RichTextItem } from '../RichText/RichTexts';
+import type { CodeBlock as CodeBlockType } from 'notion-types';
 
 import 'prismjs/components/prism-typescript';
 import 'prismjs/components/prism-jsx';
@@ -31,17 +31,20 @@ const renderToken = (token: string | Token, i: number): ReactNode => {
   );
 };
 
+type CodeData = CodeBlockType['code'];
+
 export interface CodeBlockProps {
-  code: string;
-  language: string;
-  caption?: RichTextItem[];
+  code: CodeData;
 }
 
 // Prism.js는 브라우저 환경에서 window.Prism을 설정하여 추가 언어 플러그인을 등록합니다.
 // 이로 인해 서버(Node.js)와 클라이언트(브라우저)에서 토큰화 결과가 달라져
 // SSR 하이드레이션 불일치가 발생합니다. isMounted 패턴으로 클라이언트 마운트 후에만
 // 토큰화를 수행하여 이 문제를 방지합니다.
-const CodeBlock = memo(({ code, language, caption }: CodeBlockProps) => {
+const CodeBlock = memo(({ code }: CodeBlockProps) => {
+  const { rich_text, language, caption } = code;
+  const plainCode = rich_text.map(rt => rt.plain_text).join('');
+
   const [isMounted, setIsMounted] = useState(false);
 
   useEffect(() => {
@@ -52,18 +55,18 @@ const CodeBlock = memo(({ code, language, caption }: CodeBlockProps) => {
     if (!isMounted) return null;
     const prismLanguage =
       Prism.languages[language] || Prism.languages.plaintext;
-    return Prism.tokenize(code, prismLanguage as Grammar);
-  }, [code, language, isMounted]);
+    return Prism.tokenize(plainCode, prismLanguage as Grammar);
+  }, [plainCode, language, isMounted]);
 
   return (
-    <>
+    <div>
       <pre className={`${codeBlock} language-${language}`} tabIndex={0}>
         <code className={`language-${language}`}>
-          {tokens ? tokens.map((token, i) => renderToken(token, i)) : code}
+          {tokens ? tokens.map((token, i) => renderToken(token, i)) : plainCode}
         </code>
       </pre>
       <Caption caption={caption} />
-    </>
+    </div>
   );
 });
 

packages/notion-to-jsx/src/components/Renderer/components/Embed/Embed.tsx

@@ -8,14 +8,16 @@ import {
   isAllowedEmbedDomain,
 } from '../../utils/embedUrlParser';
 import { embedIframe } from './styles.css';
-import { RichTextItem } from '../RichText/RichTexts';
+import type { EmbedBlock } from 'notion-types';
+
+type EmbedData = EmbedBlock['embed'];
 
 interface EmbedProps {
-  url: string;
-  caption?: RichTextItem[];
+  embed: EmbedData;
 }
 
-const Embed = memo(({ url, caption }: EmbedProps) => {
+const Embed = memo(({ embed }: EmbedProps) => {
+  const { url, caption } = embed;
 
   if (!isAllowedEmbedDomain(url)) {
     return (

packages/notion-to-jsx/src/components/Renderer/components/Embed/styles.css.ts

@@ -1,8 +1,9 @@
 import { style } from '@vanilla-extract/css';
+import { vars } from '../../../../styles/theme.css';
 
 export const embedIframe = style({
   width: '100%',
   aspectRatio: '16 / 9',
   border: 'none',
-  borderRadius: '8px',
+  borderRadius: vars.borderRadius.lg,
 });

packages/notion-to-jsx/src/components/Renderer/components/Image/Image.tsx

@@ -5,17 +5,13 @@ import {
   imageStyle,
   skeletonWrapper,
 } from './styles.css';
-import { RichTextItem } from '../RichText/RichTexts';
+import type { ImageBlock } from 'notion-types';
 import Skeleton from '../../../Skeleton';
 import { useImageLoad } from '../../../../hooks/useImageLoad';
+import { CONTENT_MAX_WIDTH_PX } from '../../../../styles/layout';
 
-export interface ImageFormat {
-  block_width?: number;
-  block_height?: number;
-  block_aspect_ratio?: number;
-}
-
-const MAX_WIDTH = 720;
+type ImageData = ImageBlock['image'];
+type ImageFormat = ImageData['format'];
 
 const getWidthStyle = (format?: ImageFormat, isColumn: boolean = false) => {
   if (
@@ -27,7 +23,7 @@ const getWidthStyle = (format?: ImageFormat, isColumn: boolean = false) => {
   }
 
   if (format?.block_width) {
-    return format.block_width > MAX_WIDTH
+    return format.block_width > CONTENT_MAX_WIDTH_PX
       ? '100%'
       : `${format.block_width}px`;
   }
@@ -51,21 +47,17 @@ const getImageTagStyle = (format?: ImageFormat) => {
 };
 
 export interface ImageProps {
-  src: string;
-  alt: string;
-  caption?: RichTextItem[];
-  priority?: boolean;
-  format?: ImageFormat;
+  image: ImageData;
   isColumn?: boolean;
 }
 
 const Image = ({
-  src,
-  alt,
-  caption,
-  format,
+  image,
   isColumn = false,
 }: ImageProps) => {
+  const src = image.file?.url || image.external?.url || '';
+  const alt = image.caption?.[0]?.plain_text || 'Notion image';
+  const { caption, format } = image;
   const { isLoaded, imgRef, handleLoad } = useImageLoad(src);
 
   return (

packages/notion-to-jsx/src/components/Renderer/components/Image/styles.css.ts

@@ -52,27 +52,4 @@ export const imageStyle = recipe({
   },
 });
 
-export const skeletonWrapper = recipe({
-  base: {
-    position: 'absolute',
-    top: 0,
-    left: 0,
-    width: '100%',
-    height: '100%',
-    zIndex: 1,
-    transition: 'opacity 0.3s ease',
-  },
-  variants: {
-    isLoaded: {
-      true: {
-        opacity: 0,
-      },
-      false: {
-        opacity: 1,
-      },
-    },
-  },
-  defaultVariants: {
-    isLoaded: false,
-  },
-});
+export { skeletonWrapper } from '../../../../styles/loadingOverlay.css';