dashboardity 1.0.0

package/README.md

@@ -0,0 +1,130 @@
+# Dashboardity
+
+Grafana 스타일 대시보드: **대시보드 엔진 + 위젯 라이브러리 + 앱 쉘 + 데모 앱** 구조.
+
+## 구조
+
+```
+├── src/                 # 라이브러리 소스
+│   ├── core/            # 대시보드 엔진 (레이아웃, 스펙 해석, JSON → 렌더링)
+│   ├── widget-wrapper/  # Widget 공통 래퍼 (header, padding, error, empty)
+│   ├── app-shell/       # TopBar, SideNav, DashboardPicker, TimeRangePicker
+│   ├── data-adapter/    # API → 위젯 입력 포맷 변환
+│   └── shared/          # types, utils, theme
+├── examples/
+│   └── playground/      # 위젯/대시보드 테스트용 앱
+└── package.json
+```
+
+## 위젯 (사용자 정의)
+
+**기본 위젯은 내장하지 않습니다.** `WidgetDefinition` / `WidgetProps` 타입에 맞춰 위젯을 만들고 `createWidgetRegistry`로 등록해 사용합니다.
+
+```ts
+import { createWidgetRegistry, type WidgetDefinition } from "dashboardity";
+
+// 자체 위젯 정의 후
+const widgetRegistry = createWidgetRegistry({
+  stat: MyStatWidget,
+  text: MyTextWidget,
+});
+```
+
+## App shell / 커스텀 픽커
+
+`TopBar`에 `dashboardPicker`, `timeRangePicker` 슬롯이 있습니다. 기본 제공 컴포넌트를 쓰거나, **자기 걸** 넣을 수 있습니다.
+
+```tsx
+import { TopBar, DashboardPicker, TimeRangePicker } from "dashboardity";
+
+// 기본 픽커 사용
+<TopBar
+  title="My App"
+  dashboardPicker={<DashboardPicker options={...} value={...} onChange={...} />}
+  timeRangePicker={<TimeRangePicker value={...} onChange={...} />}
+/>
+
+// 커스텀 픽커 사용 (같은 props 타입 사용 가능: DashboardPickerProps, TimeRangePickerProps)
+<TopBar
+  title="My App"
+  dashboardPicker={<MyDashboardPicker ... />}
+  timeRangePicker={<MyTimeRangePicker ... />}
+/>
+```
+
+`dashboardPicker` / `timeRangePicker`를 넘기지 않으면 해당 슬롯은 비고, `children`으로만 우측 영역을 채울 수 있습니다.
+
+## 시작하기
+
+### 요구 사항
+
+- Node 18+
+
+### 의존성 (외부)
+
+- `@dashboardity/layout-core`, `@dashboardity/layout-store`, `react-griditty` — npm `^1.0.0` 사용.
+
+**로컬 개발만 할 때:** npm에 아직 안 올렸다면 `npm overrides` 또는 로컬 `file:` 로 임시 지정 가능.
+
+### 설치 및 실행
+
+```bash
+npm install
+npm run build      # 라이브러리 빌드
+npm run example    # playground 앱 실행
+```
+
+### 스크립트
+
+- `npm run build` — 라이브러리 빌드 (tsup)
+- `npm run dev` — 라이브러리 watch 빌드
+- `npm run example` — playground 앱 실행 (Vite)
+- `npm run clean` — dist 삭제
+
+### npm install 오류 시 (`Cannot read properties of null (reading 'matches')`)
+
+이전에 pnpm을 쓰던 폴더이거나 캐시 문제일 수 있습니다. **프로젝트 루트**에서 순서대로 시도하세요.
+
+```bash
+# 1) node_modules·lock 삭제
+rmdir /s /q node_modules
+del package-lock.json
+
+# 2) npm 캐시 정리
+npm cache clean --force
+
+# 3) npm 최신으로 업데이트 (선택)
+npm install -g npm@latest
+
+# 4) 다시 설치
+npm install
+```
+
+PowerShell: `node_modules` 삭제는 `Remove-Item -Recurse -Force node_modules`, lock 삭제는 `Remove-Item package-lock.json -ErrorAction SilentlyContinue`
+
+## 배포 (npm + Git)
+
+1. **Git**
+   - `package.json`의 `repository.url`에 실제 저장소 URL 넣기 (예: `"url": "https://github.com/사용자/react-dashitty.git"`).
+   - `git add .` → `git commit` → `git remote add origin ...` → `git push -u origin main` (또는 기본 브랜치 이름).
+
+2. **npm**
+   - [npmjs.com](https://www.npmjs.com) 로그인: 터미널에서 `npm login`.
+   - 패키지 이름이 이미 쓰였으면 `package.json`의 `name`을 바꾸거나 스코프 사용 (예: `@내계정/dashboardity`).
+   - `npm run build` 후 `npm publish`. (`prepublishOnly`로 publish 시 자동 빌드됨.)
+   - 비공개 패키지가 아니면 스코프 패키지 첫 배포 시: `npm publish --access public`.
+
+`dist/`는 `.gitignore`에 있어서 Git에는 안 올라가고, `npm publish` 시에만 `files: ["dist"]`로 포함됩니다.
+
+## 스펙 → 렌더링
+
+대시보드는 JSON 스펙으로 정의됩니다.
+
+```ts
+DashboardSpec
+  └─ panels[]
+      └─ widgets[]   // type + options + dataSourceId
+layout.items[]       // grid 좌표 (layout-store)
+```
+
+Grid 계산은 `@dashboardity/layout-core` / `@dashboardity/layout-store`를 사용하며, 위젯은 width/height만 신경 쓰면 됩니다.

package/dist/index.d.mts

@@ -0,0 +1,383 @@
+import { LayoutStore } from '@dashboardity/layout-store';
+export { LayoutState, LayoutStore, createLayoutStore } from '@dashboardity/layout-store';
+import React$1, { CSSProperties, ReactNode } from 'react';
+import { GridItem } from '@dashboardity/layout-core';
+export { GridItem, LayoutAction } from '@dashboardity/layout-core';
+
+/**
+ * 위젯 공통 props.
+ * data + options만 받아 독립적으로 렌더링.
+ */
+type WidgetProps<T = unknown> = {
+    data: T;
+    options?: Record<string, unknown>;
+    /** 루트 요소에 적용. 유저가 PanelConfig.widgetClassName 등으로 전달 가능 */
+    className?: string;
+};
+/** Registry에 등록 가능한 위젯. data는 런타임에 전달되므로 any로 수용 */
+type WidgetComponent = React.FC<WidgetProps<any>>;
+/** 위젯 옵션 필드 스키마 (플러그인 시스템). Editor 자동 생성용 */
+type WidgetOptionSchemaField = {
+    type: "string";
+    label: string;
+    placeholder?: string;
+} | {
+    type: "number";
+    label: string;
+    min?: number;
+    max?: number;
+} | {
+    type: "boolean";
+    label: string;
+} | {
+    type: "select";
+    label: string;
+    options: {
+        value: string;
+        label: string;
+    }[];
+} | {
+    type: "color";
+    label: string;
+};
+type WidgetOptionSchema = Record<string, WidgetOptionSchemaField>;
+/** 위젯 정의: 컴포넌트 + 옵션 스키마. Registry는 이걸로 확장 */
+type WidgetDefinition = {
+    Component: WidgetComponent;
+    options?: WidgetOptionSchema;
+};
+/** 레거시 호환: [type] => Component | WidgetDefinition */
+type WidgetRegistry = {
+    [type: string]: WidgetComponent | WidgetDefinition;
+};
+/**
+ * 패널 설정. (Grafana Panel JSON 참고, 단순화)
+ * layout(gridPos) 정보는 포함하지 않음 — layout-store 전담.
+ * JSON 직렬화 가능.
+ */
+type PanelConfig = {
+    id: string;
+    /** widget type (e.g. "stat", "chart", "text") */
+    type: string;
+    dataSourceId?: string;
+    options?: Record<string, unknown>;
+    style?: CSSProperties;
+    /** 패널 루트 요소 className */
+    className?: string;
+    /** WidgetContainer(제목+콘텐츠 래퍼) 루트 className */
+    containerClassName?: string;
+    /** 위젯 루트(Widget 컴포넌트 최상위)에 전달되는 className */
+    widgetClassName?: string;
+    /** Panel wrapper 옵션 */
+    containerStyle?: CSSProperties;
+};
+/**
+ * 대시보드 공식 스펙. "대시보드 = JSON"
+ * layout.items[].id === panels[].id 1:1. panels에는 좌표 없음.
+ */
+type DashboardSpec = {
+    id: string;
+    title: string;
+    columns: number;
+    layout: {
+        items: GridItem[];
+    };
+    panels: PanelConfig[];
+};
+/** 편집 / 보기 모드 (Grafana 핵심 UX) */
+type DashboardMode = "view" | "edit";
+/** 패널 액션 (remove, duplicate, edit placeholder) */
+type PanelAction = {
+    type: "remove";
+    id: string;
+} | {
+    type: "duplicate";
+    id: string;
+} | {
+    type: "edit";
+    id: string;
+};
+/**
+ * 데이터 소스 인터페이스.
+ * 비동기/캐시/폴링은 고려하지 않음.
+ * Dashboard는 data의 shape를 가정하지 않음.
+ */
+interface DataSource {
+    getData(dataSourceId: string, panelId: string): unknown;
+}
+/** 대시보드 그리드 UI 옵션 */
+type DashboardGridOptions = {
+    /** 리사이즈 핸들에 표시할 커스텀 아이콘(ReactNode). 미지정 시 기본 스타일 */
+    resizeHandle?: ReactNode;
+    /** 격자선 표시 여부 */
+    showGrid?: boolean;
+};
+/**
+ * 패널에 넘길 props.
+ * 위젯은 래퍼만 제공하고, 콘텐츠는 content로 주입.
+ */
+type PanelProps = {
+    item: GridItem;
+    title?: string;
+    content: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    containerClassName?: string;
+    containerStyle?: CSSProperties;
+    /** edit 모드에서 패널 액션(remove/duplicate/edit) 시 호출 */
+    onAction?: (action: PanelAction) => void;
+    /** edit 모드에서 패널 클릭 시 선택. selected면 시각 강조용 */
+    selected?: boolean;
+    onSelect?: () => void;
+};
+/**
+ * PanelOptionEditor props.
+ * layout/store 절대 접근 ❌. 오직 PanelConfig.options 수정만.
+ */
+type PanelOptionEditorProps = {
+    panel: PanelConfig;
+    /** 위젯 옵션 스키마 (widget definition에서). 없으면 기본 필드만 */
+    schema?: WidgetOptionSchema;
+    onChange: (next: PanelConfig) => void;
+};
+
+/** className 조합 유틸 */
+declare const cn: (...parts: (string | undefined)[]) => string;
+
+/** 색상 토큰 */
+declare const colors: {
+    readonly text: "#333";
+    readonly textMuted: "#555";
+    readonly textSubtle: "#999";
+    readonly border: "#e0e0e0";
+    readonly background: "#fff";
+    readonly primary: "#1976d2";
+    readonly success: "#73bf69";
+    readonly warning: "#ff9830";
+    readonly danger: "#f2495c";
+    readonly chartGradientStart: "#73bf69";
+    readonly chartGradientEnd: "#5794f2";
+};
+/** spacing (px) */
+declare const spacing: {
+    readonly xs: 4;
+    readonly sm: 8;
+    readonly md: 12;
+    readonly lg: 16;
+    readonly xl: 24;
+};
+/** typography */
+declare const typography: {
+    readonly fontSize: {
+        readonly xs: 11;
+        readonly sm: 12;
+        readonly md: 14;
+        readonly lg: 18;
+        readonly xl: 24;
+    };
+    readonly fontWeight: {
+        readonly normal: 400;
+        readonly medium: 500;
+        readonly semibold: 600;
+        readonly bold: 700;
+    };
+};
+type Theme = {
+    colors: typeof colors;
+    spacing: typeof spacing;
+    typography: typeof typography;
+};
+declare const defaultTheme: Theme;
+
+type DashboardProps = {
+    store: LayoutStore;
+    columns: number;
+    /** item.id로 조회. JSON 직렬화 가능한 설정만 포함 (layout 제외) */
+    panelConfigs: PanelConfig[];
+    dataSource: DataSource;
+    widgets: WidgetRegistry;
+    rowHeight?: number;
+    /** 그리드 UI 옵션: resize 아이콘, 격자 보기 등 */
+    gridOptions?: DashboardGridOptions;
+    /** view = 읽기 전용, edit = 드래그/리사이즈/패널 액션 허용 */
+    mode?: DashboardMode;
+    /** edit 모드에서 패널 액션(remove/duplicate/edit) 시 호출 */
+    onPanelAction?: (action: PanelAction) => void;
+    /** edit 모드에서 패널 클릭 시 선택. 선택된 id */
+    selectedPanelId?: string | null;
+    onPanelSelect?: (id: string) => void;
+    className?: string;
+    style?: React$1.CSSProperties;
+};
+declare const Dashboard: React$1.FC<DashboardProps>;
+
+type DashboardRuntimeProps = {
+    /** 초기 스펙. key={initialSpec.id} 로 대시보드 전환 시 리마운트 권장 */
+    initialSpec: DashboardSpec;
+    widgets: WidgetRegistry;
+    dataSource: DataSource;
+    mode?: "view" | "edit";
+    /** 레이아웃/패널 변경 시 직렬화된 스펙 전달 (저장/서버 연동용) */
+    onChange?: (spec: DashboardSpec) => void;
+    rowHeight?: number;
+    gridOptions?: DashboardGridOptions;
+    className?: string;
+    style?: React$1.CSSProperties;
+};
+/** ref 로 노출되는 API. 툴바/단축키/저장 연동용 */
+type DashboardRuntimeHandle = {
+    addPanel: (type: string) => void;
+    removePanel: (id: string) => void;
+    export: () => DashboardSpec;
+};
+declare const DashboardRuntime: React$1.ForwardRefExoticComponent<DashboardRuntimeProps & React$1.RefAttributes<DashboardRuntimeHandle>>;
+
+/**
+ * 빈 패널 생성 (Add Panel 플로우용).
+ * layout은 store.dispatch({ type: "add", item: { id, x, y, w, h } })로 호출 측에서 처리.
+ */
+declare const createEmptyPanel: (type: string, defaultTitle?: string) => PanelConfig;
+/**
+ * 라이브러리 레벨: store + panels + meta → JSON 스펙.
+ * 순서 보존, deterministic, side-effect 없음.
+ */
+declare const serializeDashboard: (store: LayoutStore, panels: PanelConfig[], meta: {
+    id: string;
+    title: string;
+}) => DashboardSpec;
+/**
+ * JSON 스펙 → store + panels 복원.
+ */
+declare const loadDashboard: (spec: DashboardSpec) => {
+    store: LayoutStore;
+    panels: PanelConfig[];
+};
+
+declare const Panel: React$1.FC<PanelProps>;
+
+/**
+ * PanelOptionEditor.
+ * layout/store 접근 없음. PanelConfig.options 만 수정.
+ */
+declare const PanelOptionEditor: React$1.FC<PanelOptionEditorProps>;
+
+/**
+ * 반응형 그리드: 화면(컨테이너) 크기와 columns에 맞춰 cellWidth/cellHeight만 동적 조정.
+ * GridItem 좌표(x,y,w,h)는 변경하지 않음. 픽셀 변환만 달라짐.
+ * 좌우 이동 자동 보정 없음. pack-up 규칙은 layout-core/store에서 유지.
+ */
+type UseResponsiveGridOptions = {
+    /** 그리드 열 수 (layout-store의 columns와 동일해야 함) */
+    columns: number;
+    /** 셀 높이(px). 미지정 시 cellWidth와 동일(정사각형) */
+    rowHeight?: number;
+};
+type ResponsiveGridSize = {
+    cellWidth: number;
+    cellHeight: number;
+};
+declare const useResponsiveGrid: (containerRef: React.RefObject<HTMLDivElement | null>, options: UseResponsiveGridOptions) => ResponsiveGridSize;
+
+/** 존재하지 않는 type용 fallback 위젯 */
+declare const FallbackWidget: WidgetComponent;
+/**
+ * Widget Registry 생성.
+ * 단순 객체 반환. 존재하지 않는 type에 대한 fallback은 Dashboard에서 처리.
+ */
+declare const createWidgetRegistry: (widgets: WidgetRegistry) => WidgetRegistry;
+
+type TopBarProps = {
+    title?: string;
+    /** 사용자 정의 대시보드 선택기. 미주입 시 기본 제공 안 함 → children으로 직접 넣거나 자체 컴포넌트 사용 */
+    dashboardPicker?: React$1.ReactNode;
+    /** 사용자 정의 시간 범위 선택기. 미주입 시 기본 제공 안 함 → children으로 직접 넣거나 자체 컴포넌트 사용 */
+    timeRangePicker?: React$1.ReactNode;
+    children?: React$1.ReactNode;
+    className?: string;
+    style?: React$1.CSSProperties;
+};
+declare const TopBar: React$1.FC<TopBarProps>;
+
+type SideNavItem = {
+    id: string;
+    label: string;
+    href?: string;
+};
+type SideNavProps = {
+    items?: SideNavItem[];
+    activeId?: string;
+    onSelect?: (id: string) => void;
+    className?: string;
+    style?: React$1.CSSProperties;
+};
+declare const SideNav: React$1.FC<SideNavProps>;
+
+type DashboardOption = {
+    id: string;
+    title: string;
+};
+type DashboardPickerProps = {
+    options?: DashboardOption[];
+    value?: string;
+    onChange?: (id: string) => void;
+    className?: string;
+    style?: React$1.CSSProperties;
+};
+declare const DashboardPicker: React$1.FC<DashboardPickerProps>;
+
+type TimeRangePreset = {
+    label: string;
+    value: string;
+};
+type TimeRangePickerProps = {
+    presets?: TimeRangePreset[];
+    value?: string;
+    onChange?: (value: string) => void;
+    className?: string;
+    style?: React$1.CSSProperties;
+};
+declare const TimeRangePicker: React$1.FC<TimeRangePickerProps>;
+
+/**
+ * 정적 데이터 소스.
+ * dataSourceId → 데이터 매핑으로 패널에 공급.
+ */
+declare const createStaticDataSource: (payload: {
+    dataByKey: Record<string, unknown>;
+}) => DataSource;
+/**
+ * PanelConfig + layout. layout-store 초기 상태용.
+ * layout은 오직 layout-store가 담당.
+ */
+type PanelConfigWithLayout = {
+    panelConfig: PanelConfig;
+    layout: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+};
+declare const buildInitialItemsFromPanelConfigs: (configs: PanelConfigWithLayout[]) => GridItem[];
+
+type WidgetContainerProps = {
+    /** 위젯 상단에 표시할 제목 (options.title 등) */
+    title?: string;
+    children: React$1.ReactNode;
+    /** 루트 요소 커스텀 */
+    className?: string;
+    style?: CSSProperties;
+    /** 제목 영역 커스텀 */
+    titleClassName?: string;
+    titleStyle?: CSSProperties;
+    /** 콘텐츠 영역 커스텀 */
+    contentClassName?: string;
+    contentStyle?: CSSProperties;
+};
+/**
+ * 모든 위젯이 공통으로 사용하는 컨테이너.
+ * 제목 + 콘텐츠 영역 레이아웃과 패딩을 통일. className/style로 커스텀 가능.
+ */
+declare const WidgetContainer: React$1.FC<WidgetContainerProps>;
+
+export { Dashboard, type DashboardGridOptions, type DashboardMode, type DashboardOption, DashboardPicker, type DashboardPickerProps, type DashboardProps, DashboardRuntime, type DashboardRuntimeHandle, type DashboardRuntimeProps, type DashboardSpec, type DataSource, FallbackWidget, Panel, type PanelAction, type PanelConfig, type PanelConfigWithLayout, PanelOptionEditor, type PanelOptionEditorProps, type PanelProps, type ResponsiveGridSize, SideNav, type SideNavItem, type SideNavProps, type Theme, TimeRangePicker, type TimeRangePickerProps, type TimeRangePreset, TopBar, type TopBarProps, type UseResponsiveGridOptions, type WidgetComponent, WidgetContainer, type WidgetContainerProps, type WidgetDefinition, type WidgetOptionSchema, type WidgetOptionSchemaField, type WidgetProps, type WidgetRegistry, buildInitialItemsFromPanelConfigs, cn, colors, createEmptyPanel, createStaticDataSource, createWidgetRegistry, defaultTheme, loadDashboard, serializeDashboard, spacing, typography, useResponsiveGrid };