@gunham7728/report-builder

표/차트 기반 보고서를 편집하고 미리보기/출력할 수 있는 React 컴포넌트입니다. 데이터(JSON)를 넘기면 {{key}} 템플릿으로 셀·차트에 값이 바인딩되고, 배열을 넘기면 표/차트가 자동으로 반복됩니다.

설치

npm install @gunham7728/report-builder
# peer dependencies (앱에 없으면 함께 설치)
npm install react react-dom chart.js react-chartjs-2

npm 레지스트리에 올리지 않고 내부망에서 쓸 경우: 이 패키지의 dist/ + package.json을 복사해 npm install ./libs/report-builder (로컬 경로) 로 설치하거나, npm pack 으로 만든 .tgz를 설치하면 됩니다.

빠른 시작

import { Report } from "@gunham7728/report-builder";
// ★ CSS 별도 import 불필요 — 컴포넌트가 자동으로 스타일을 주입합니다

export default function App() {
  return <Report editor />; // 빈 편집기로 시작
}

Props

| Prop | 타입 | 기본값 | 설명 | | ---------- | ------------------------------ | ----------- | --------------------------------------------------------------------------- | | editor | boolean | false | true면 편집 UI + 미리보기 토글, false면 미리보기(뷰어) 전용 | | data | ReportState | undefined | 보고서 상태(제목·데이터·섹션). 주면 controlled 모드가 됩니다(아래 참고) | | onChange | (state: ReportState) => void | undefined | 편집으로 상태가 바뀔 때 호출 | | modal | boolean | false | true면 전체화면 모달(오버레이) 안에 렌더 | | onClose | () => void | undefined | modal=true일 때 X 버튼·배경 클릭 시 호출 | | theme | ReportTheme | undefined | 색상 테마 기본값. 편집기 🎨 테마에서 수정 시 state.theme이 우선 적용 |

색상 테마 (theme)

표 헤더·제목 등의 색상을 한 번에 지정합니다. 미설정 키는 기본값을 씁니다.

<Report
  editor
  theme={{
    headerBg: '#3f3f46',     // 컬럼 헤더 배경
    headerText: '#ffffff',   // 컬럼 헤더 글자
    rowHeaderBg: '#f4f4f5',  // 행 헤더 배경
    rowHeaderText: '#3f3f46',// 행 헤더 글자
    title: '#1e40af',        // 섹션 제목
    docTitle: '#1e40af',     // 문서 제목
    docTitleBg: '#eef4fc',   // 문서 제목 줄 배경
  }}
/>

• 편집기 툴바의 🎨 테마 버튼으로 직접 색을 바꿀 수 있고, 바꾼 값은 내보내기(JSON)에 함께 저장됩니다.
• 개별 셀에 지정한 배경/글자색은 테마보다 우선합니다.
• theme prop과 저장된 state.theme이 함께 있으면 state.theme이 우선합니다.

인쇄 제외 (섹션별)

각 섹션 컨트롤의 🖨인쇄 / 🚫인쇄 토글로 인쇄/PDF에서 해당 섹션을 뺄 수 있습니다. 제외된 섹션은 편집기 화면에서 회색 커버로 표시되고, 실제 인쇄에선 완전히 빠집니다. 이 설정도 JSON에 저장됩니다.

스타일: v0.2.0부터 CSS가 자동 주입됩니다. 더 이상 import "@gunham7728/report-builder/style.css" 가 필요 없습니다 (해당 줄이 있으면 삭제하세요).

모달로 열기

import { useState } from "react";
import { Report } from "@gunham7728/report-builder";

function Page() {
  const [open, setOpen] = useState(false);
  return (
    <>
      <button onClick={() => setOpen(true)}>리포트 편집기 열기</button>
      {open && <Report modal editor onClose={() => setOpen(false)} />}
    </>
  );
}

인쇄(PDF) 시에는 모달·부모 페이지 UI가 모두 제외되고 보고서 본문만 출력됩니다.

⚠️ controlled / uncontrolled 동작 (중요)

• data를 주지 않으면 컴포넌트가 내부 상태로 편집을 관리합니다 (uncontrolled).
• data를 주면 항상 그 값을 그대로 렌더합니다 (controlled). 편집기로 쓰면서 초기 데이터를 주려면 반드시 onChange로 상태를 받아 다시 data로 넘겨야 합니다. 안 그러면 편집해도 화면이 안 바뀝니다.

사용 패턴

1) 뷰어 (저장된 보고서 보기 / 출력)

import { Report } from "@gunham7728/report-builder";

<Report data={savedState} />; // editor 생략 = 미리보기 전용

2) 편집기 — 빈 상태로 시작

<Report editor onChange={(state) => console.log(state)} />

3) 편집기 — 초기 데이터 + 상태 관리 (controlled)

import { useState } from "react";
import { Report, type ReportState } from "@gunham7728/report-builder";

function Editor() {
  const [state, setState] = useState<ReportState>(initialState);
  return <Report editor data={state} onChange={setState} />;
}

데이터를 어떻게 넘기나 — ReportState

interface ReportState {
  title: string;
  data: Record<string, unknown>; // 변수 바인딩용 실제 값 (여기에 진짜 데이터를 넣음)
  sections: Section[]; // 보고서 구성(표/차트/텍스트 등)
}

• data : 셀/차트에서 {{key}}로 참조하는 값들. 중첩 객체는 {{a.b}}, 배열은 반복에 사용.
• sections : 보고서를 이루는 블록들 (KV 그리드, 헤더 테이블, 그룹 테이블, 비교표, 파이/도넛·라인·레이더 차트, 텍스트 등).

예시:

const state: ReportState = {
  title: "매장 보고서",
  data: {
    storeName: "강남점",
    sales: 5000000,
    stores: [
      // 배열 → 표/차트 반복에 사용
      { name: "강남점", sales: 5000000 },
      { name: "서초점", sales: 4200000 },
    ],
  },
  sections: [
    /* ... */
  ],
};

템플릿 바인딩 규칙

• 셀/텍스트에 {{storeName}} → data.storeName 값으로 치환
• 텍스트 중간에 섞어 쓰기 가능: 본 점포는 {{storeName}}, 매출 {{sales}}원
• 반복(배열): 표/차트에서 배열(data.stores)을 지정하면 각 항목이 행/조각/시리즈로 자동 생성됩니다. 반복 항목 안에서는 그 항목의 필드를 {{name}}, {{sales}} 로 참조합니다.

샘플 상태 가져오기

빠르게 동작을 보고 싶으면 내장 샘플을 사용하세요:

import { Report, getSampleState } from "@gunham7728/report-builder";

<Report editor data={getSampleState()} onChange={/* ... */} />;

Export 목록

import {
  Report, // 메인 컴포넌트
  getSampleState, // 샘플 ReportState 생성 함수
  INITIAL_MOCK_DATA, // 샘플 데이터 객체
  type ReportState,
  type Section,
  type Cell,
  type SectionType,
  type ModeType,
} from "@gunham7728/report-builder";

빌드 (이 저장소에서)

npm run build   # dist/ 에 ESM·CJS·타입(d.ts) 생성 (CSS는 JS에 인라인)

라이선스

사내 사용.