react-dockable-desktop 7.3.0 → 7.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -187,7 +187,7 @@ interface DirtyStateOptions {
187
187
  * Custom header title text or localizable message descriptor.
188
188
  * Replaces the default "Unsaved Changes" title.
189
189
  */
190
- title?: string | MessageDescriptor;
190
+ title?: string | MessageDescriptor | (() => string);
191
191
  /**
192
192
  * Custom warning explanation text or localizable message descriptor.
193
193
  * Replaces the standard default message body templates.
@@ -363,7 +363,7 @@ interface PanelInfo {
363
363
  /** Unique panel identifier. */
364
364
  id: string;
365
365
  /** Plain text label or localizable message descriptor. */
366
- title: string | MessageDescriptor;
366
+ title: string | MessageDescriptor | (() => string);
367
367
  /** String matching the component registration ID in the workspace's {@link PanelRegistry}. */
368
368
  component: string;
369
369
  /** Current workspace placement mode. */
@@ -408,7 +408,7 @@ interface PanelInfo {
408
408
  */
409
409
  interface OpenPanelOptions<P extends object = Record<string, unknown>> {
410
410
  /** Override the panel tab/window title. Accepts a plain string or an i18n message descriptor. */
411
- title?: string | MessageDescriptor;
411
+ title?: string | MessageDescriptor | (() => string);
412
412
  /** Initial placement: `'floating'`, `'docked'` (default when a grid exists), or `'tabbed'`. */
413
413
  initialTarget?: 'floating' | 'docked' | 'tabbed';
414
414
  /** Pin the new floating window to a workspace corner on creation. Has no effect when
@@ -445,7 +445,7 @@ interface WorkspaceState {
445
445
  /** Array of minimized panels waiting in the taskbar dock. */
446
446
  minimized: {
447
447
  id: string;
448
- title: string | MessageDescriptor;
448
+ title: string | MessageDescriptor | (() => string);
449
449
  component: string;
450
450
  }[];
451
451
  /** Map indexing panel metadata descriptors. */
@@ -721,7 +721,7 @@ interface WorkspaceActions {
721
721
  * @param id - Panel instance ID.
722
722
  * @param title - New title string or localizable message descriptor.
723
723
  */
724
- updatePanelTitle: (id: string, title: string | MessageDescriptor) => void;
724
+ updatePanelTitle: (id: string, title: string | MessageDescriptor | (() => string)) => void;
725
725
  /**
726
726
  * Sets the icon shown on an open panel's tab, floating title bar and taskbar button, in place
727
727
  * of its registration's `defaultOptions.icon`. `null` restores the registration's icon. The icon
@@ -808,7 +808,7 @@ interface SerializedLayout {
808
808
  floating: FloatingWindow[];
809
809
  minimized: {
810
810
  id: string;
811
- title: string | MessageDescriptor;
811
+ title: string | MessageDescriptor | (() => string);
812
812
  component: string;
813
813
  }[];
814
814
  panels: Record<string, PanelInfo>;
@@ -824,6 +824,29 @@ interface WorkspaceCore {
824
824
  zIndexBase?: number;
825
825
  }) => void;
826
826
  }
827
+ /**
828
+ * The live workspace state. The component re-renders whenever it changes — or, given a selector,
829
+ * only when the selected value changes.
830
+ *
831
+ * For reads without a subscription, call the workspace's `isOpen()` or `getOpenPanelIds()`.
832
+ *
833
+ * The selector must return a value that stays the same while the state does — a primitive, or a
834
+ * part of the state as it is (`s => s.panels[id]`). A selector that builds a new object or array
835
+ * on each call (`s => ({ n: s.floating.length })`, `s => s.floating.map(...)`) is a new value
836
+ * every time React asks, and React stops with "Maximum update depth exceeded". Select the parts
837
+ * separately, or
838
+ * derive the object with `useMemo` from what you selected.
839
+ *
840
+ * @returns The current workspace state, or the selector's result.
841
+ * @throws Error if used outside `<DockableDesktopProvider>`.
842
+ * @example
843
+ * ```tsx
844
+ * function PanelCount() {
845
+ * const count = useWorkspaceState(s => Object.keys(s.panels).length);
846
+ * return <span>{count} open</span>;
847
+ * }
848
+ * ```
849
+ */
827
850
  declare function useWindowManagerState(): WorkspaceState;
828
851
  declare function useWindowManagerState<T>(selector: (state: WorkspaceState) => T): T;
829
852
  /**
@@ -833,7 +856,7 @@ declare const useFormatMessage: () => MessageFormatter;
833
856
  /**
834
857
  * Helper to resolve dynamic label strings or localizable descriptor objects into text.
835
858
  */
836
- declare const formatLabel: (label: string | MessageDescriptor | undefined, formatter: MessageFormatter) => string;
859
+ declare const formatLabel: (label: string | MessageDescriptor | (() => string) | undefined, formatter: MessageFormatter) => string;
837
860
  /**
838
861
  * React hook to fetch the localizable predefined message map catalog.
839
862
  */
@@ -873,7 +896,7 @@ interface PanelRegistryEntry {
873
896
  id: string;
874
897
  defaultMessage?: string;
875
898
  values?: Record<string, string | number>;
876
- };
899
+ } | (() => string);
877
900
  /** Icon placed next to title tags. */
878
901
  icon?: React.ReactNode;
879
902
  /** Initial mounting state inside the desktop layout grid. */
@@ -1108,7 +1131,7 @@ declare class WorkspaceClient<TUserEvents extends object = Record<string, unknow
1108
1131
  /** Sets/clears a panel's dirty (unsaved changes) flag. */
1109
1132
  setPanelDirty(id: string, dirty: boolean, options?: DirtyStateOptions): void;
1110
1133
  /** Updates a panel's displayed title. */
1111
- updatePanelTitle(id: string, title: string | MessageDescriptor): void;
1134
+ updatePanelTitle(id: string, title: string | MessageDescriptor | (() => string)): void;
1112
1135
  /** Sets an open panel's tab/window/taskbar icon; `null` restores its registration's icon. Not saved by `saveLayout()`. */
1113
1136
  setPanelIcon(id: string, icon: ReactNode | null): void;
1114
1137
  /**
@@ -1180,8 +1203,13 @@ interface PanelTitleDescriptor {
1180
1203
  /** Parameters to inject into the translated text string. */
1181
1204
  values?: Record<string, string | number>;
1182
1205
  }
1183
- /** Union type representing either a plain string or a localizable title descriptor. */
1184
- type PanelTitle = string | PanelTitleDescriptor;
1206
+ /**
1207
+ * A panel, window, drawer or modal title: a plain string, a localizable descriptor, or (7.4.0) a
1208
+ * function returning the text — called each time the title is rendered, so a title built with the
1209
+ * app's own translation function follows a language change. A function title is not saved in a
1210
+ * layout: a restored panel takes its registered default title.
1211
+ */
1212
+ type PanelTitle = string | PanelTitleDescriptor | (() => string);
1185
1213
  /** Configuration options applied when opening a SidePanel. */
1186
1214
  interface SidePanelOptions {
1187
1215
  /** Display title for the side-panel header. */
@@ -1309,7 +1337,7 @@ interface PanelHandle {
1309
1337
  /** Marks the panel as having unsaved changes. */
1310
1338
  setDirty: (dirty: boolean, options?: DirtyStateOptions) => void;
1311
1339
  /** Changes the title shown on the tab, window or modal. */
1312
- setTitle: (title: string | MessageDescriptor) => void;
1340
+ setTitle: (title: string | MessageDescriptor | (() => string)) => void;
1313
1341
  /**
1314
1342
  * Changes the icon on the panel's tab, floating title bar and taskbar button, or in a modal's or
1315
1343
  * drawer's header. In a workspace panel, `null` goes back to the registration's
@@ -1511,6 +1539,24 @@ interface RddDesktopProps {
1511
1539
  /** Enables the library's own transitions/animations (tab hover, dock preview, etc.). Never affects the consumer's own page. @default true */
1512
1540
  animations?: boolean;
1513
1541
  }
1542
+ /**
1543
+ * The desktop itself: the docked grid of tab groups, the floating windows, the taskbar of
1544
+ * minimized panels, and the drop targets while a panel is dragged. Render it inside
1545
+ * `<DockableDesktopProvider>`, in a container that gives it a size (`rdd-fill-viewport` fills the
1546
+ * page), and import `react-dockable-desktop/styles.css` once.
1547
+ *
1548
+ * Exported as `RddDesktop`.
1549
+ *
1550
+ * @example
1551
+ * ```tsx
1552
+ * <DockableDesktopProvider workspace={workspace}>
1553
+ * <div className="rdd-fill-viewport">
1554
+ * <RddDesktop skin="vscode" taskbarVisibility="autohide" />
1555
+ * </div>
1556
+ * <RddModals />
1557
+ * </DockableDesktopProvider>
1558
+ * ```
1559
+ */
1514
1560
  declare const WindowManager: React$1.FC<RddDesktopProps>;
1515
1561
 
1516
1562
  /**
@@ -1528,7 +1574,7 @@ interface RddConfirmProps {
1528
1574
  id: string;
1529
1575
  defaultMessage?: string;
1530
1576
  values?: any;
1531
- };
1577
+ } | (() => string);
1532
1578
  /** Main message text or localizable descriptor to display. */
1533
1579
  message: string | {
1534
1580
  id: string;
package/dist/index.d.ts CHANGED
@@ -187,7 +187,7 @@ interface DirtyStateOptions {
187
187
  * Custom header title text or localizable message descriptor.
188
188
  * Replaces the default "Unsaved Changes" title.
189
189
  */
190
- title?: string | MessageDescriptor;
190
+ title?: string | MessageDescriptor | (() => string);
191
191
  /**
192
192
  * Custom warning explanation text or localizable message descriptor.
193
193
  * Replaces the standard default message body templates.
@@ -363,7 +363,7 @@ interface PanelInfo {
363
363
  /** Unique panel identifier. */
364
364
  id: string;
365
365
  /** Plain text label or localizable message descriptor. */
366
- title: string | MessageDescriptor;
366
+ title: string | MessageDescriptor | (() => string);
367
367
  /** String matching the component registration ID in the workspace's {@link PanelRegistry}. */
368
368
  component: string;
369
369
  /** Current workspace placement mode. */
@@ -408,7 +408,7 @@ interface PanelInfo {
408
408
  */
409
409
  interface OpenPanelOptions<P extends object = Record<string, unknown>> {
410
410
  /** Override the panel tab/window title. Accepts a plain string or an i18n message descriptor. */
411
- title?: string | MessageDescriptor;
411
+ title?: string | MessageDescriptor | (() => string);
412
412
  /** Initial placement: `'floating'`, `'docked'` (default when a grid exists), or `'tabbed'`. */
413
413
  initialTarget?: 'floating' | 'docked' | 'tabbed';
414
414
  /** Pin the new floating window to a workspace corner on creation. Has no effect when
@@ -445,7 +445,7 @@ interface WorkspaceState {
445
445
  /** Array of minimized panels waiting in the taskbar dock. */
446
446
  minimized: {
447
447
  id: string;
448
- title: string | MessageDescriptor;
448
+ title: string | MessageDescriptor | (() => string);
449
449
  component: string;
450
450
  }[];
451
451
  /** Map indexing panel metadata descriptors. */
@@ -721,7 +721,7 @@ interface WorkspaceActions {
721
721
  * @param id - Panel instance ID.
722
722
  * @param title - New title string or localizable message descriptor.
723
723
  */
724
- updatePanelTitle: (id: string, title: string | MessageDescriptor) => void;
724
+ updatePanelTitle: (id: string, title: string | MessageDescriptor | (() => string)) => void;
725
725
  /**
726
726
  * Sets the icon shown on an open panel's tab, floating title bar and taskbar button, in place
727
727
  * of its registration's `defaultOptions.icon`. `null` restores the registration's icon. The icon
@@ -808,7 +808,7 @@ interface SerializedLayout {
808
808
  floating: FloatingWindow[];
809
809
  minimized: {
810
810
  id: string;
811
- title: string | MessageDescriptor;
811
+ title: string | MessageDescriptor | (() => string);
812
812
  component: string;
813
813
  }[];
814
814
  panels: Record<string, PanelInfo>;
@@ -824,6 +824,29 @@ interface WorkspaceCore {
824
824
  zIndexBase?: number;
825
825
  }) => void;
826
826
  }
827
+ /**
828
+ * The live workspace state. The component re-renders whenever it changes — or, given a selector,
829
+ * only when the selected value changes.
830
+ *
831
+ * For reads without a subscription, call the workspace's `isOpen()` or `getOpenPanelIds()`.
832
+ *
833
+ * The selector must return a value that stays the same while the state does — a primitive, or a
834
+ * part of the state as it is (`s => s.panels[id]`). A selector that builds a new object or array
835
+ * on each call (`s => ({ n: s.floating.length })`, `s => s.floating.map(...)`) is a new value
836
+ * every time React asks, and React stops with "Maximum update depth exceeded". Select the parts
837
+ * separately, or
838
+ * derive the object with `useMemo` from what you selected.
839
+ *
840
+ * @returns The current workspace state, or the selector's result.
841
+ * @throws Error if used outside `<DockableDesktopProvider>`.
842
+ * @example
843
+ * ```tsx
844
+ * function PanelCount() {
845
+ * const count = useWorkspaceState(s => Object.keys(s.panels).length);
846
+ * return <span>{count} open</span>;
847
+ * }
848
+ * ```
849
+ */
827
850
  declare function useWindowManagerState(): WorkspaceState;
828
851
  declare function useWindowManagerState<T>(selector: (state: WorkspaceState) => T): T;
829
852
  /**
@@ -833,7 +856,7 @@ declare const useFormatMessage: () => MessageFormatter;
833
856
  /**
834
857
  * Helper to resolve dynamic label strings or localizable descriptor objects into text.
835
858
  */
836
- declare const formatLabel: (label: string | MessageDescriptor | undefined, formatter: MessageFormatter) => string;
859
+ declare const formatLabel: (label: string | MessageDescriptor | (() => string) | undefined, formatter: MessageFormatter) => string;
837
860
  /**
838
861
  * React hook to fetch the localizable predefined message map catalog.
839
862
  */
@@ -873,7 +896,7 @@ interface PanelRegistryEntry {
873
896
  id: string;
874
897
  defaultMessage?: string;
875
898
  values?: Record<string, string | number>;
876
- };
899
+ } | (() => string);
877
900
  /** Icon placed next to title tags. */
878
901
  icon?: React.ReactNode;
879
902
  /** Initial mounting state inside the desktop layout grid. */
@@ -1108,7 +1131,7 @@ declare class WorkspaceClient<TUserEvents extends object = Record<string, unknow
1108
1131
  /** Sets/clears a panel's dirty (unsaved changes) flag. */
1109
1132
  setPanelDirty(id: string, dirty: boolean, options?: DirtyStateOptions): void;
1110
1133
  /** Updates a panel's displayed title. */
1111
- updatePanelTitle(id: string, title: string | MessageDescriptor): void;
1134
+ updatePanelTitle(id: string, title: string | MessageDescriptor | (() => string)): void;
1112
1135
  /** Sets an open panel's tab/window/taskbar icon; `null` restores its registration's icon. Not saved by `saveLayout()`. */
1113
1136
  setPanelIcon(id: string, icon: ReactNode | null): void;
1114
1137
  /**
@@ -1180,8 +1203,13 @@ interface PanelTitleDescriptor {
1180
1203
  /** Parameters to inject into the translated text string. */
1181
1204
  values?: Record<string, string | number>;
1182
1205
  }
1183
- /** Union type representing either a plain string or a localizable title descriptor. */
1184
- type PanelTitle = string | PanelTitleDescriptor;
1206
+ /**
1207
+ * A panel, window, drawer or modal title: a plain string, a localizable descriptor, or (7.4.0) a
1208
+ * function returning the text — called each time the title is rendered, so a title built with the
1209
+ * app's own translation function follows a language change. A function title is not saved in a
1210
+ * layout: a restored panel takes its registered default title.
1211
+ */
1212
+ type PanelTitle = string | PanelTitleDescriptor | (() => string);
1185
1213
  /** Configuration options applied when opening a SidePanel. */
1186
1214
  interface SidePanelOptions {
1187
1215
  /** Display title for the side-panel header. */
@@ -1309,7 +1337,7 @@ interface PanelHandle {
1309
1337
  /** Marks the panel as having unsaved changes. */
1310
1338
  setDirty: (dirty: boolean, options?: DirtyStateOptions) => void;
1311
1339
  /** Changes the title shown on the tab, window or modal. */
1312
- setTitle: (title: string | MessageDescriptor) => void;
1340
+ setTitle: (title: string | MessageDescriptor | (() => string)) => void;
1313
1341
  /**
1314
1342
  * Changes the icon on the panel's tab, floating title bar and taskbar button, or in a modal's or
1315
1343
  * drawer's header. In a workspace panel, `null` goes back to the registration's
@@ -1511,6 +1539,24 @@ interface RddDesktopProps {
1511
1539
  /** Enables the library's own transitions/animations (tab hover, dock preview, etc.). Never affects the consumer's own page. @default true */
1512
1540
  animations?: boolean;
1513
1541
  }
1542
+ /**
1543
+ * The desktop itself: the docked grid of tab groups, the floating windows, the taskbar of
1544
+ * minimized panels, and the drop targets while a panel is dragged. Render it inside
1545
+ * `<DockableDesktopProvider>`, in a container that gives it a size (`rdd-fill-viewport` fills the
1546
+ * page), and import `react-dockable-desktop/styles.css` once.
1547
+ *
1548
+ * Exported as `RddDesktop`.
1549
+ *
1550
+ * @example
1551
+ * ```tsx
1552
+ * <DockableDesktopProvider workspace={workspace}>
1553
+ * <div className="rdd-fill-viewport">
1554
+ * <RddDesktop skin="vscode" taskbarVisibility="autohide" />
1555
+ * </div>
1556
+ * <RddModals />
1557
+ * </DockableDesktopProvider>
1558
+ * ```
1559
+ */
1514
1560
  declare const WindowManager: React$1.FC<RddDesktopProps>;
1515
1561
 
1516
1562
  /**
@@ -1528,7 +1574,7 @@ interface RddConfirmProps {
1528
1574
  id: string;
1529
1575
  defaultMessage?: string;
1530
1576
  values?: any;
1531
- };
1577
+ } | (() => string);
1532
1578
  /** Main message text or localizable descriptor to display. */
1533
1579
  message: string | {
1534
1580
  id: string;