react-dockable-desktop 7.0.0 → 7.1.0

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
@@ -1,4 +1,4 @@
1
- import React$1, { ComponentType } from 'react';
1
+ import React$1, { ComponentType, ReactNode } from 'react';
2
2
 
3
3
  /**
4
4
  * @file predefinedMessages.ts
@@ -392,6 +392,10 @@ interface PanelInfo {
392
392
  * key, `openPanel` focuses that existing panel instead of creating a new one — see
393
393
  * {@link WorkspaceActions.openPanel}'s `dedupeKey` option and {@link WorkspaceActions.findPanelId}. */
394
394
  dedupeKey?: string;
395
+ /** Icon set at runtime with `usePanel().setIcon()` or {@link WorkspaceActions.setPanelIcon},
396
+ * shown instead of the registration's `defaultOptions.icon`. Never saved by `saveLayout()`;
397
+ * `loadLayout()` keeps it for a panel that is still open. */
398
+ icon?: React$1.ReactNode;
395
399
  }
396
400
  /**
397
401
  * Options accepted by {@link WorkspaceActions.openPanel}.
@@ -712,6 +716,14 @@ interface WorkspaceActions {
712
716
  * @param title - New title string or localizable message descriptor.
713
717
  */
714
718
  updatePanelTitle: (id: string, title: string | MessageDescriptor) => void;
719
+ /**
720
+ * Sets the icon shown on an open panel's tab, floating title bar and taskbar button, in place
721
+ * of its registration's `defaultOptions.icon`. `null` restores the registration's icon. The icon
722
+ * lives only in memory: `saveLayout()` never writes it.
723
+ * @param id - Panel instance ID.
724
+ * @param icon - The icon, or `null` to go back to the registration's.
725
+ */
726
+ setPanelIcon: (id: string, icon: React$1.ReactNode | null) => void;
715
727
  /**
716
728
  * Closes a panel, first running any registered close guards.
717
729
  * If the panel is dirty, shows the built-in unsaved-changes confirmation dialog.
@@ -1088,6 +1100,8 @@ declare class WorkspaceClient<TUserEvents extends object = Record<string, unknow
1088
1100
  setPanelDirty(id: string, dirty: boolean, options?: DirtyStateOptions): void;
1089
1101
  /** Updates a panel's displayed title. */
1090
1102
  updatePanelTitle(id: string, title: string | MessageDescriptor): void;
1103
+ /** Sets an open panel's tab/window/taskbar icon; `null` restores its registration's icon. Not saved by `saveLayout()`. */
1104
+ setPanelIcon(id: string, icon: ReactNode | null): void;
1091
1105
  /**
1092
1106
  * Requests that a panel close, honoring its dirty flag and any registered close guard.
1093
1107
  * Resolves once the close (or user cancellation) has been resolved.
@@ -1259,7 +1273,14 @@ declare function createWorkspace<TEvents extends object = Record<string, unknown
1259
1273
  declare function useWorkspace<TEvents extends object = Record<string, unknown>>(): Workspace<TEvents>;
1260
1274
  /** The state of a workspace panel: where it is. */
1261
1275
  type PanelState = PanelInfo['state'];
1262
- /** What a panel component knows about, and can do to, its own container. See {@link usePanel}. */
1276
+ /**
1277
+ * What a panel component knows about, and can do to, its own container. See {@link usePanel}.
1278
+ *
1279
+ * **Identity.** `id` and the five functions (`close`, `minimize`, `setDirty`, `setTitle`,
1280
+ * `setIcon`) never change identity for the panel's lifetime. The handle object itself changes
1281
+ * when `containerType`, `isActive`, `isMinimized` or `isFloating` does. So don't list the handle
1282
+ * in a dependency array: depend on the function you call, or on the values you write.
1283
+ */
1263
1284
  interface PanelHandle {
1264
1285
  /** This panel's instance id. */
1265
1286
  id: string;
@@ -1279,12 +1300,24 @@ interface PanelHandle {
1279
1300
  setDirty: (dirty: boolean, options?: DirtyStateOptions) => void;
1280
1301
  /** Changes the title shown on the tab, window or modal. */
1281
1302
  setTitle: (title: string | MessageDescriptor) => void;
1282
- /** Changes the icon shown on the tab or window. */
1303
+ /**
1304
+ * Changes the icon on the panel's tab, floating title bar and taskbar button, or in a modal's or
1305
+ * drawer's header. In a workspace panel, `null` goes back to the registration's
1306
+ * `defaultOptions.icon`. The icon is not saved by `saveLayout()`.
1307
+ */
1283
1308
  setIcon: (icon: React$1.ReactNode) => void;
1284
1309
  }
1285
1310
  /**
1286
1311
  * The panel's own container: its id, where it is, and what it can do. Works in docked panels,
1287
1312
  * floating windows, modals and side drawers.
1313
+ *
1314
+ * The functions on the handle are stable; the handle object is not (see {@link PanelHandle}).
1315
+ * To keep the tab title in step with a document:
1316
+ *
1317
+ * ```tsx
1318
+ * const { setTitle, setDirty } = usePanel();
1319
+ * useEffect(() => { setTitle(doc.title); setDirty(doc.dirty); }, [setTitle, setDirty, doc.title, doc.dirty]);
1320
+ * ```
1288
1321
  */
1289
1322
  declare function usePanel(): PanelHandle;
1290
1323
  /** Lifecycle callbacks for {@link usePanelEvents}. Each is called at the moment it describes. */
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import React$1, { ComponentType } from 'react';
1
+ import React$1, { ComponentType, ReactNode } from 'react';
2
2
 
3
3
  /**
4
4
  * @file predefinedMessages.ts
@@ -392,6 +392,10 @@ interface PanelInfo {
392
392
  * key, `openPanel` focuses that existing panel instead of creating a new one — see
393
393
  * {@link WorkspaceActions.openPanel}'s `dedupeKey` option and {@link WorkspaceActions.findPanelId}. */
394
394
  dedupeKey?: string;
395
+ /** Icon set at runtime with `usePanel().setIcon()` or {@link WorkspaceActions.setPanelIcon},
396
+ * shown instead of the registration's `defaultOptions.icon`. Never saved by `saveLayout()`;
397
+ * `loadLayout()` keeps it for a panel that is still open. */
398
+ icon?: React$1.ReactNode;
395
399
  }
396
400
  /**
397
401
  * Options accepted by {@link WorkspaceActions.openPanel}.
@@ -712,6 +716,14 @@ interface WorkspaceActions {
712
716
  * @param title - New title string or localizable message descriptor.
713
717
  */
714
718
  updatePanelTitle: (id: string, title: string | MessageDescriptor) => void;
719
+ /**
720
+ * Sets the icon shown on an open panel's tab, floating title bar and taskbar button, in place
721
+ * of its registration's `defaultOptions.icon`. `null` restores the registration's icon. The icon
722
+ * lives only in memory: `saveLayout()` never writes it.
723
+ * @param id - Panel instance ID.
724
+ * @param icon - The icon, or `null` to go back to the registration's.
725
+ */
726
+ setPanelIcon: (id: string, icon: React$1.ReactNode | null) => void;
715
727
  /**
716
728
  * Closes a panel, first running any registered close guards.
717
729
  * If the panel is dirty, shows the built-in unsaved-changes confirmation dialog.
@@ -1088,6 +1100,8 @@ declare class WorkspaceClient<TUserEvents extends object = Record<string, unknow
1088
1100
  setPanelDirty(id: string, dirty: boolean, options?: DirtyStateOptions): void;
1089
1101
  /** Updates a panel's displayed title. */
1090
1102
  updatePanelTitle(id: string, title: string | MessageDescriptor): void;
1103
+ /** Sets an open panel's tab/window/taskbar icon; `null` restores its registration's icon. Not saved by `saveLayout()`. */
1104
+ setPanelIcon(id: string, icon: ReactNode | null): void;
1091
1105
  /**
1092
1106
  * Requests that a panel close, honoring its dirty flag and any registered close guard.
1093
1107
  * Resolves once the close (or user cancellation) has been resolved.
@@ -1259,7 +1273,14 @@ declare function createWorkspace<TEvents extends object = Record<string, unknown
1259
1273
  declare function useWorkspace<TEvents extends object = Record<string, unknown>>(): Workspace<TEvents>;
1260
1274
  /** The state of a workspace panel: where it is. */
1261
1275
  type PanelState = PanelInfo['state'];
1262
- /** What a panel component knows about, and can do to, its own container. See {@link usePanel}. */
1276
+ /**
1277
+ * What a panel component knows about, and can do to, its own container. See {@link usePanel}.
1278
+ *
1279
+ * **Identity.** `id` and the five functions (`close`, `minimize`, `setDirty`, `setTitle`,
1280
+ * `setIcon`) never change identity for the panel's lifetime. The handle object itself changes
1281
+ * when `containerType`, `isActive`, `isMinimized` or `isFloating` does. So don't list the handle
1282
+ * in a dependency array: depend on the function you call, or on the values you write.
1283
+ */
1263
1284
  interface PanelHandle {
1264
1285
  /** This panel's instance id. */
1265
1286
  id: string;
@@ -1279,12 +1300,24 @@ interface PanelHandle {
1279
1300
  setDirty: (dirty: boolean, options?: DirtyStateOptions) => void;
1280
1301
  /** Changes the title shown on the tab, window or modal. */
1281
1302
  setTitle: (title: string | MessageDescriptor) => void;
1282
- /** Changes the icon shown on the tab or window. */
1303
+ /**
1304
+ * Changes the icon on the panel's tab, floating title bar and taskbar button, or in a modal's or
1305
+ * drawer's header. In a workspace panel, `null` goes back to the registration's
1306
+ * `defaultOptions.icon`. The icon is not saved by `saveLayout()`.
1307
+ */
1283
1308
  setIcon: (icon: React$1.ReactNode) => void;
1284
1309
  }
1285
1310
  /**
1286
1311
  * The panel's own container: its id, where it is, and what it can do. Works in docked panels,
1287
1312
  * floating windows, modals and side drawers.
1313
+ *
1314
+ * The functions on the handle are stable; the handle object is not (see {@link PanelHandle}).
1315
+ * To keep the tab title in step with a document:
1316
+ *
1317
+ * ```tsx
1318
+ * const { setTitle, setDirty } = usePanel();
1319
+ * useEffect(() => { setTitle(doc.title); setDirty(doc.dirty); }, [setTitle, setDirty, doc.title, doc.dirty]);
1320
+ * ```
1288
1321
  */
1289
1322
  declare function usePanel(): PanelHandle;
1290
1323
  /** Lifecycle callbacks for {@link usePanelEvents}. Each is called at the moment it describes. */