dashboardity 1.1.0 → 1.2.0

package/dist/index.d.mts

@@ -79,16 +79,22 @@ type BreakpointWidths = Partial<Record<Exclude<BreakpointKey, "base">, number>>;
 type ColumnsByBreakpoint = Partial<Record<BreakpointKey, number>> & {
     base: number;
 };
+/** 브레이크포인트별 레이아웃. 지정 시 해당 구간에서 스케일 대신 이 레이아웃 사용 */
+type LayoutByBreakpoint = {
+    items: GridItem[];
+};
 /**
  * 대시보드 공식 스펙. "대시보드 = JSON"
  * layout.items[].id === panels[].id 1:1. panels에는 좌표 없음.
  * breakpoints + columnsByBreakpoint 있으면 뷰포트 너비에 따라 columns 해석.
+ * layoutsByBreakpoint 있으면 해당 구간에서 layout 대신 그 레이아웃 사용(브레이크포인트별 배치).
  */
 type DashboardSpec = {
     id: string;
     title: string;
     /** 현재 저장된 레이아웃의 열 수. columnsByBreakpoint 사용 시에도 직렬화 시 이 값으로 저장 */
     columns: number;
+    /** 기본/캐논칼 레이아웃. layoutsByBreakpoint 미지정 구간은 여기서 스케일 */
     layout: {
         items: GridItem[];
     };
@@ -97,6 +103,8 @@ type DashboardSpec = {
     breakpoints?: BreakpointWidths;
     /** 브레이크포인트별 열 수. 지정 시 반응형 columns 적용 */
     columnsByBreakpoint?: ColumnsByBreakpoint;
+    /** 브레이크포인트별 레이아웃. 지정한 구간은 스케일 없이 이 배치 사용 */
+    layoutsByBreakpoint?: Partial<Record<BreakpointKey, LayoutByBreakpoint>>;
 };
 /** 편집 / 보기 모드 (Grafana 핵심 UX) */
 type DashboardMode = "view" | "edit";
@@ -271,22 +279,26 @@ declare const DashboardRuntime: React$1.ForwardRefExoticComponent<DashboardRunti
 declare const createEmptyPanel: (type: string, defaultTitle?: string) => PanelConfig;
 /**
  * 라이브러리 레벨: store + panels + meta → JSON 스펙.
- * 순서 보존, deterministic, side-effect 없음.
- * breakpoints/columnsByBreakpoint가 있으면 그대로 직렬화(저장 시 현재 columns 사용).
+ * breakpoints/columnsByBreakpoint/layoutsByBreakpoint 있으면 그대로 직렬화.
+ * layoutCache: 현재 브레이크포인트 포함 편집된 구간별 레이아웃(merge되어 출력).
  */
 declare const serializeDashboard: (store: LayoutStore, panels: PanelConfig[], meta: {
     id: string;
     title: string;
-}, specOverrides?: Pick<DashboardSpec, "breakpoints" | "columnsByBreakpoint">) => DashboardSpec;
+}, specOverrides?: Pick<DashboardSpec, "breakpoints" | "columnsByBreakpoint" | "layoutsByBreakpoint">) => DashboardSpec;
 type LoadDashboardOptions = {
     /** 뷰포트/컨테이너 너비(px). columnsByBreakpoint 있을 때 이 너비로 열 수 해석 */
     width?: number;
     /** 이미 해석된 열 수. 지정 시 width 무시하고 이 값으로 스토어 생성 */
     resolvedColumns?: number;
+    /** 현재 브레이크포인트. layoutsByBreakpoint[breakpointKey] 있으면 그 레이아웃 사용 */
+    breakpointKey?: BreakpointKey;
+    /** 런타임 캐시(구간별 레이아웃). breakpointKey에 대한 캐시가 있으면 spec보다 우선 */
+    layoutCache?: Partial<Record<BreakpointKey, GridItem[]>>;
 };
 /**
  * JSON 스펙 → store + panels 복원.
- * spec.columnsByBreakpoint + breakpoints 있으면 width 또는 resolvedColumns로 열 수 해석 후 레이아웃 스케일.
+ * layoutsByBreakpoint 또는 layoutCache로 해당 구간 레이아웃 사용, 없으면 layout 스케일.
  */
 declare const loadDashboard: (spec: DashboardSpec, options?: LoadDashboardOptions) => {
     store: LayoutStore;
@@ -425,4 +437,4 @@ type WidgetContainerProps = {
  */
 declare const WidgetContainer: React$1.FC<WidgetContainerProps>;
 
-export { type BreakpointKey, type BreakpointWidths, type ColumnsByBreakpoint, DEFAULT_BREAKPOINT_WIDTHS, Dashboard, type DashboardGridOptions, type DashboardMode, type DashboardOption, DashboardPicker, type DashboardPickerProps, type DashboardProps, DashboardRuntime, type DashboardRuntimeHandle, type DashboardRuntimeProps, type DashboardSpec, type DataSource, FallbackWidget, type LoadDashboardOptions, 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, getBreakpointKey, loadDashboard, resolveColumns, scaleLayout, serializeDashboard, spacing, typography, useContainerWidth, useResponsiveGrid };
+export { type BreakpointKey, type BreakpointWidths, type ColumnsByBreakpoint, DEFAULT_BREAKPOINT_WIDTHS, Dashboard, type DashboardGridOptions, type DashboardMode, type DashboardOption, DashboardPicker, type DashboardPickerProps, type DashboardProps, DashboardRuntime, type DashboardRuntimeHandle, type DashboardRuntimeProps, type DashboardSpec, type DataSource, FallbackWidget, type LayoutByBreakpoint, type LoadDashboardOptions, 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, getBreakpointKey, loadDashboard, resolveColumns, scaleLayout, serializeDashboard, spacing, typography, useContainerWidth, useResponsiveGrid };

package/dist/index.d.ts

@@ -79,16 +79,22 @@ type BreakpointWidths = Partial<Record<Exclude<BreakpointKey, "base">, number>>;
 type ColumnsByBreakpoint = Partial<Record<BreakpointKey, number>> & {
     base: number;
 };
+/** 브레이크포인트별 레이아웃. 지정 시 해당 구간에서 스케일 대신 이 레이아웃 사용 */
+type LayoutByBreakpoint = {
+    items: GridItem[];
+};
 /**
  * 대시보드 공식 스펙. "대시보드 = JSON"
  * layout.items[].id === panels[].id 1:1. panels에는 좌표 없음.
  * breakpoints + columnsByBreakpoint 있으면 뷰포트 너비에 따라 columns 해석.
+ * layoutsByBreakpoint 있으면 해당 구간에서 layout 대신 그 레이아웃 사용(브레이크포인트별 배치).
  */
 type DashboardSpec = {
     id: string;
     title: string;
     /** 현재 저장된 레이아웃의 열 수. columnsByBreakpoint 사용 시에도 직렬화 시 이 값으로 저장 */
     columns: number;
+    /** 기본/캐논칼 레이아웃. layoutsByBreakpoint 미지정 구간은 여기서 스케일 */
     layout: {
         items: GridItem[];
     };
@@ -97,6 +103,8 @@ type DashboardSpec = {
     breakpoints?: BreakpointWidths;
     /** 브레이크포인트별 열 수. 지정 시 반응형 columns 적용 */
     columnsByBreakpoint?: ColumnsByBreakpoint;
+    /** 브레이크포인트별 레이아웃. 지정한 구간은 스케일 없이 이 배치 사용 */
+    layoutsByBreakpoint?: Partial<Record<BreakpointKey, LayoutByBreakpoint>>;
 };
 /** 편집 / 보기 모드 (Grafana 핵심 UX) */
 type DashboardMode = "view" | "edit";
@@ -271,22 +279,26 @@ declare const DashboardRuntime: React$1.ForwardRefExoticComponent<DashboardRunti
 declare const createEmptyPanel: (type: string, defaultTitle?: string) => PanelConfig;
 /**
  * 라이브러리 레벨: store + panels + meta → JSON 스펙.
- * 순서 보존, deterministic, side-effect 없음.
- * breakpoints/columnsByBreakpoint가 있으면 그대로 직렬화(저장 시 현재 columns 사용).
+ * breakpoints/columnsByBreakpoint/layoutsByBreakpoint 있으면 그대로 직렬화.
+ * layoutCache: 현재 브레이크포인트 포함 편집된 구간별 레이아웃(merge되어 출력).
  */
 declare const serializeDashboard: (store: LayoutStore, panels: PanelConfig[], meta: {
     id: string;
     title: string;
-}, specOverrides?: Pick<DashboardSpec, "breakpoints" | "columnsByBreakpoint">) => DashboardSpec;
+}, specOverrides?: Pick<DashboardSpec, "breakpoints" | "columnsByBreakpoint" | "layoutsByBreakpoint">) => DashboardSpec;
 type LoadDashboardOptions = {
     /** 뷰포트/컨테이너 너비(px). columnsByBreakpoint 있을 때 이 너비로 열 수 해석 */
     width?: number;
     /** 이미 해석된 열 수. 지정 시 width 무시하고 이 값으로 스토어 생성 */
     resolvedColumns?: number;
+    /** 현재 브레이크포인트. layoutsByBreakpoint[breakpointKey] 있으면 그 레이아웃 사용 */
+    breakpointKey?: BreakpointKey;
+    /** 런타임 캐시(구간별 레이아웃). breakpointKey에 대한 캐시가 있으면 spec보다 우선 */
+    layoutCache?: Partial<Record<BreakpointKey, GridItem[]>>;
 };
 /**
  * JSON 스펙 → store + panels 복원.
- * spec.columnsByBreakpoint + breakpoints 있으면 width 또는 resolvedColumns로 열 수 해석 후 레이아웃 스케일.
+ * layoutsByBreakpoint 또는 layoutCache로 해당 구간 레이아웃 사용, 없으면 layout 스케일.
  */
 declare const loadDashboard: (spec: DashboardSpec, options?: LoadDashboardOptions) => {
     store: LayoutStore;
@@ -425,4 +437,4 @@ type WidgetContainerProps = {
  */
 declare const WidgetContainer: React$1.FC<WidgetContainerProps>;
 
-export { type BreakpointKey, type BreakpointWidths, type ColumnsByBreakpoint, DEFAULT_BREAKPOINT_WIDTHS, Dashboard, type DashboardGridOptions, type DashboardMode, type DashboardOption, DashboardPicker, type DashboardPickerProps, type DashboardProps, DashboardRuntime, type DashboardRuntimeHandle, type DashboardRuntimeProps, type DashboardSpec, type DataSource, FallbackWidget, type LoadDashboardOptions, 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, getBreakpointKey, loadDashboard, resolveColumns, scaleLayout, serializeDashboard, spacing, typography, useContainerWidth, useResponsiveGrid };
+export { type BreakpointKey, type BreakpointWidths, type ColumnsByBreakpoint, DEFAULT_BREAKPOINT_WIDTHS, Dashboard, type DashboardGridOptions, type DashboardMode, type DashboardOption, DashboardPicker, type DashboardPickerProps, type DashboardProps, DashboardRuntime, type DashboardRuntimeHandle, type DashboardRuntimeProps, type DashboardSpec, type DataSource, FallbackWidget, type LayoutByBreakpoint, type LoadDashboardOptions, 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, getBreakpointKey, loadDashboard, resolveColumns, scaleLayout, serializeDashboard, spacing, typography, useContainerWidth, useResponsiveGrid };

package/dist/index.js

@@ -35,7 +35,7 @@ __export(index_exports, {
   cn: () => cn3,
   colors: () => colors,
   createEmptyPanel: () => createEmptyPanel,
-  createLayoutStore: () => import_layout_store3.createLayoutStore,
+  createLayoutStore: () => import_layout_store2.createLayoutStore,
   createStaticDataSource: () => createStaticDataSource,
   createWidgetRegistry: () => createWidgetRegistry,
   defaultTheme: () => defaultTheme,
@@ -518,7 +518,6 @@ var Dashboard = ({
 
 // src/core/DashboardRuntime.tsx
 var import_react4 = require("react");
-var import_layout_store2 = require("@dashboardity/layout-store");
 
 // src/core/DashboardSerializer.ts
 var import_layout_store = require("@dashboardity/layout-store");
@@ -542,13 +541,32 @@ var serializeDashboard = (store, panels, meta, specOverrides) => {
   if (specOverrides?.breakpoints) base.breakpoints = specOverrides.breakpoints;
   if (specOverrides?.columnsByBreakpoint)
     base.columnsByBreakpoint = specOverrides.columnsByBreakpoint;
+  if (specOverrides?.layoutsByBreakpoint != null)
+    base.layoutsByBreakpoint = specOverrides.layoutsByBreakpoint;
   return base;
 };
+var getItemsForBreakpoint = (spec, breakpointKey, resolvedColumns, layoutCache) => {
+  const cached = layoutCache?.[breakpointKey];
+  if (cached != null && cached.length > 0) return [...cached];
+  const byBp = spec.layoutsByBreakpoint?.[breakpointKey]?.items;
+  if (byBp != null && byBp.length > 0) return [...byBp];
+  return scaleLayout(
+    spec.layout.items,
+    spec.columns,
+    resolvedColumns
+  );
+};
 var loadDashboard = (spec, options) => {
   const savedColumns = spec.columns;
   const colConfig = spec.columnsByBreakpoint ?? savedColumns;
   const resolved = options?.resolvedColumns ?? (options?.width != null ? resolveColumns(options.width, colConfig, spec.breakpoints) : savedColumns);
-  const items = resolved !== savedColumns ? scaleLayout(spec.layout.items, savedColumns, resolved) : [...spec.layout.items];
+  const breakpointKey = options?.breakpointKey ?? "xl";
+  const items = getItemsForBreakpoint(
+    spec,
+    breakpointKey,
+    resolved,
+    options?.layoutCache
+  );
   const store = (0, import_layout_store.createLayoutStore)({
     items,
     columns: resolved
@@ -749,16 +767,26 @@ var DashboardRuntime = (0, import_react4.forwardRef)((props, ref) => {
   const isEdit = mode === "edit";
   const gridWrapRef = (0, import_react4.useRef)(null);
   const containerWidth = useContainerWidth(gridWrapRef);
+  const widthForBreakpoint = containerWidth || (typeof window !== "undefined" ? window.innerWidth : 1024);
+  const currentBreakpoint = (0, import_react4.useMemo)(
+    () => getBreakpointKey(widthForBreakpoint, initialSpec.breakpoints),
+    [widthForBreakpoint, initialSpec.breakpoints]
+  );
   const resolvedColumns = (0, import_react4.useMemo)(() => {
     const colConfig = initialSpec.columnsByBreakpoint ?? initialSpec.columns;
-    const width = containerWidth || (typeof window !== "undefined" ? window.innerWidth : 1024);
-    return resolveColumns(width, colConfig, initialSpec.breakpoints);
+    return resolveColumns(
+      widthForBreakpoint,
+      colConfig,
+      initialSpec.breakpoints
+    );
   }, [
-    containerWidth,
+    widthForBreakpoint,
     initialSpec.columns,
     initialSpec.columnsByBreakpoint,
     initialSpec.breakpoints
   ]);
+  const initialSpecRef = (0, import_react4.useRef)(initialSpec);
+  initialSpecRef.current = initialSpec;
   const [store, setStore] = (0, import_react4.useState)(() => loadDashboard(initialSpec).store);
   const [panels, setPanels] = (0, import_react4.useState)(() => [
     ...loadDashboard(initialSpec).panels
@@ -767,29 +795,52 @@ var DashboardRuntime = (0, import_react4.forwardRef)((props, ref) => {
   const specIdRef = (0, import_react4.useRef)(initialSpec.id);
   const storeRef = (0, import_react4.useRef)(store);
   storeRef.current = store;
+  const prevBreakpointRef = (0, import_react4.useRef)(currentBreakpoint);
+  const layoutCacheRef = (0, import_react4.useRef)({});
+  const currentBreakpointRef = (0, import_react4.useRef)(currentBreakpoint);
+  currentBreakpointRef.current = currentBreakpoint;
   (0, import_react4.useEffect)(() => {
     if (resolvedColumns < 1) return;
-    if (specIdRef.current !== initialSpec.id) {
-      specIdRef.current = initialSpec.id;
-      const loaded = loadDashboard(initialSpec, { resolvedColumns });
-      setStore(loaded.store);
-      setPanels([...loaded.panels]);
+    const spec = initialSpecRef.current;
+    if (specIdRef.current !== spec.id) {
+      specIdRef.current = spec.id;
+      prevBreakpointRef.current = currentBreakpoint;
+      layoutCacheRef.current = {};
+      Object.keys(spec.layoutsByBreakpoint ?? {}).forEach(
+        (k) => {
+          const items = spec.layoutsByBreakpoint?.[k]?.items;
+          if (items) layoutCacheRef.current[k] = [...items];
+        }
+      );
+      const loaded2 = loadDashboard(spec, {
+        resolvedColumns,
+        breakpointKey: currentBreakpoint,
+        layoutCache: layoutCacheRef.current
+      });
+      setStore(loaded2.store);
+      setPanels([...loaded2.panels]);
+      layoutCacheRef.current[currentBreakpoint] = loaded2.store.getState().items;
       return;
     }
+    const prevBp = prevBreakpointRef.current;
     const current = storeRef.current;
-    if (!current) {
-      const loaded = loadDashboard(initialSpec, { resolvedColumns });
-      setStore(loaded.store);
-      setPanels([...loaded.panels]);
+    if (prevBp === currentBreakpoint && current?.getState().columns === resolvedColumns) {
       return;
     }
-    const state = current.getState();
-    if (state.columns === resolvedColumns) return;
-    const scaled = scaleLayout(state.items, state.columns, resolvedColumns);
-    setStore(
-      (0, import_layout_store2.createLayoutStore)({ items: scaled, columns: resolvedColumns })
-    );
-  }, [initialSpec, resolvedColumns]);
+    if (current) {
+      layoutCacheRef.current[prevBp] = [...current.getState().items];
+    }
+    prevBreakpointRef.current = currentBreakpoint;
+    const loaded = loadDashboard(spec, {
+      resolvedColumns,
+      breakpointKey: currentBreakpoint,
+      layoutCache: layoutCacheRef.current
+    });
+    const loadedItems = loaded.store.getState().items;
+    layoutCacheRef.current[currentBreakpoint] = [...loadedItems];
+    setStore(loaded.store);
+    setPanels([...loaded.panels]);
+  }, [initialSpec.id, resolvedColumns, currentBreakpoint]);
   const meta = (0, import_react4.useMemo)(
     () => ({ id: initialSpec.id, title: initialSpec.title }),
     [initialSpec.id, initialSpec.title]
@@ -797,15 +848,32 @@ var DashboardRuntime = (0, import_react4.forwardRef)((props, ref) => {
   const panelsRef = (0, import_react4.useRef)(panels);
   panelsRef.current = panels;
   const notifyChange = (0, import_react4.useCallback)(() => {
+    const cache = layoutCacheRef.current;
+    const layoutsByBreakpoint = Object.keys(cache).length > 0 ? Object.fromEntries(
+      Object.entries(cache).map(([k, v]) => [k, { items: v }])
+    ) : initialSpec.layoutsByBreakpoint;
     onChange?.(
       serializeDashboard(store, panelsRef.current, meta, {
         breakpoints: initialSpec.breakpoints,
-        columnsByBreakpoint: initialSpec.columnsByBreakpoint
+        columnsByBreakpoint: initialSpec.columnsByBreakpoint,
+        layoutsByBreakpoint
       })
     );
-  }, [onChange, store, meta, initialSpec.breakpoints, initialSpec.columnsByBreakpoint]);
+  }, [
+    onChange,
+    store,
+    meta,
+    initialSpec.breakpoints,
+    initialSpec.columnsByBreakpoint,
+    initialSpec.layoutsByBreakpoint
+  ]);
   (0, import_react4.useEffect)(() => {
-    const unsub = store.subscribe(notifyChange);
+    const unsub = store.subscribe(() => {
+      layoutCacheRef.current[currentBreakpointRef.current] = [
+        ...store.getState().items
+      ];
+      notifyChange();
+    });
     return unsub;
   }, [store, notifyChange]);
   (0, import_react4.useEffect)(() => {
@@ -873,13 +941,23 @@ var DashboardRuntime = (0, import_react4.forwardRef)((props, ref) => {
     },
     [store]
   );
-  const exportSpec = (0, import_react4.useCallback)(
-    () => serializeDashboard(store, panelsRef.current, meta, {
+  const exportSpec = (0, import_react4.useCallback)(() => {
+    const cache = layoutCacheRef.current;
+    const layoutsByBreakpoint = Object.keys(cache).length > 0 ? Object.fromEntries(
+      Object.entries(cache).map(([k, v]) => [k, { items: v }])
+    ) : initialSpec.layoutsByBreakpoint;
+    return serializeDashboard(store, panelsRef.current, meta, {
       breakpoints: initialSpec.breakpoints,
-      columnsByBreakpoint: initialSpec.columnsByBreakpoint
-    }),
-    [store, meta, initialSpec.breakpoints, initialSpec.columnsByBreakpoint]
-  );
+      columnsByBreakpoint: initialSpec.columnsByBreakpoint,
+      layoutsByBreakpoint
+    });
+  }, [
+    store,
+    meta,
+    initialSpec.breakpoints,
+    initialSpec.columnsByBreakpoint,
+    initialSpec.layoutsByBreakpoint
+  ]);
   (0, import_react4.useImperativeHandle)(
     ref,
     () => ({
@@ -956,7 +1034,7 @@ var DashboardRuntime = (0, import_react4.forwardRef)((props, ref) => {
 DashboardRuntime.displayName = "DashboardRuntime";
 
 // src/index.ts
-var import_layout_store3 = require("@dashboardity/layout-store");
+var import_layout_store2 = require("@dashboardity/layout-store");
 
 // src/app-shell/TopBar.tsx
 var import_jsx_runtime7 = require("react/jsx-runtime");