react-dockable-desktop 7.12.0-next.1 → 7.12.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
@@ -304,15 +304,20 @@ interface PanelInfo {
304
304
  poppedOut?: true;
305
305
  }
306
306
  /**
307
- * What `workspace.popOutPanel(id)` did (7.12.0): `{ ok: true }` when the panel is in its own
308
- * window (or already was), otherwise why not, checked in this order:
307
+ * What `workspace.popOutPanel(id)` did (7.12.0): `{ ok: true }` when its window opened (or was
308
+ * already open; the panel moves in at once, or once `popoutUrl` has loaded), otherwise why not,
309
+ * checked in this order:
309
310
  * - `'disabled'`: the workspace was created without `popOut: true`;
310
311
  * - `'not-open'`: no open panel has this id;
311
- * - `'not-allowed'`: the panel's type has no `canPopOut` (or it shows a widget out of its panel);
312
- * - `'no-gesture'`: the call did not come from a user's click or key press, so no window may open;
312
+ * - `'not-allowed'`: the panel's type has no `canPopOut` (for a widget's panel, the widget's rules
313
+ * decide);
314
+ * - (a panel already out stops here: its window comes forward, `{ ok: true }`);
315
+ * - `'no-gesture'`: the call did not come from a user's activation (a click or key press, or soon
316
+ * after one), so no window may open;
317
+ * - `'no-window'`: no `<DockableDesktopProvider>` is mounted to show it;
313
318
  * - `'blocked'`: the browser's pop-up blocker refused the window;
314
- * - `'no-window'`: no `<DockableDesktopProvider>` is mounted to show it, or the window closed or
315
- * could not be used before the panel moved in.
319
+ * - `'no-window'`: the window closed or could not be used before the panel moved in;
320
+ * - `'not-allowed'`: a widget that could not leave its panel after all (its window closes again).
316
321
  *
317
322
  * The panel stays where it was on every refusal.
318
323
  */
@@ -1245,6 +1250,8 @@ interface PopOutHost {
1245
1250
  width: number;
1246
1251
  height: number;
1247
1252
  } | null;
1253
+ /** The panel's element, or null when it has none (7.12.0): where it is decides when the events are sent. */
1254
+ element(id: string): Element | null;
1248
1255
  }
1249
1256
  /** @internal One open window, as the provider renders it. `doc` is null until its page has loaded. */
1250
1257
  interface PopOutEntry {
@@ -1271,13 +1278,15 @@ interface HostedPopOut {
1271
1278
  interface HostedPopOutOptions {
1272
1279
  /** Called once the window is open, before the panel moves in: takes the widget out of its panel if needed. */
1273
1280
  prepare: () => boolean;
1274
- /** Where the widget is on the main page (client pixels), for the window's place and size. */
1281
+ /** Where the widget is (client pixels of `view`, else of the main page), for the window's place and size. */
1275
1282
  rect?: {
1276
1283
  left: number;
1277
1284
  top: number;
1278
1285
  width: number;
1279
1286
  height: number;
1280
1287
  } | null;
1288
+ /** The window `rect` was measured in, when not the main page's (7.12.1): its owner panel's pop-out. */
1289
+ view?: Window;
1281
1290
  }
1282
1291
  /** @internal A workspace's pop-out windows: what `WorkspaceClient` and the provider use. */
1283
1292
  interface PopOutWindows {
@@ -1320,9 +1329,10 @@ interface BuiltInEvents {
1320
1329
  id: string;
1321
1330
  };
1322
1331
  /**
1323
- * A panel moved into its own browser window (`popOutPanel`, 7.12.0), once that window's page is
1324
- * ready: `window` is it, the one `usePanelWindow()` now gives the panel. Sent for a managed
1325
- * widget's own panel too (`useFloatingWidgets().popOut`), with that panel's id.
1332
+ * A panel moved into its own browser window (`popOutPanel`, 7.12.0), sent once it is laid out
1333
+ * there (in the window's frame, and a frame later), so a `resize()` sees the window's size:
1334
+ * `window` is it, the one `usePanelWindow()` now gives the panel. Sent for a managed widget's own
1335
+ * panel too (`useFloatingWidgets().popOut`), with that panel's id.
1326
1336
  */
1327
1337
  'panel:popped-out': {
1328
1338
  id: string;
@@ -1331,24 +1341,27 @@ interface BuiltInEvents {
1331
1341
  /**
1332
1342
  * A panel that was in its own window is back in the page (7.12.0), whatever brought it back: the
1333
1343
  * app, the frame's button, the window closing, the provider unmounting. Not sent for a panel
1334
- * closed while out (`panel:closed` is). Sent for a managed widget's own panel too, as it goes back
1335
- * into its owner panel.
1344
+ * closed while out (`panel:closed` is). Sent once it is laid out in its place (a frame later); a
1345
+ * panel back as a tab that isn't selected is 0 x 0 then. Also sent, without `panel:popped-out`,
1346
+ * when the window fails before the panel got there. Sent for a managed widget's own panel too, as
1347
+ * it goes back into its owner panel.
1336
1348
  */
1337
1349
  'panel:returned': {
1338
1350
  id: string;
1339
1351
  };
1340
1352
  /**
1341
- * A panel is about to move into its own window (7.12.0): sent just before its element leaves the
1342
- * page, once that window's page is ready. `panel:popped-out` follows. Not sent for a refused
1343
- * pop-out, nor for docking or floating.
1353
+ * A panel is about to move into its own window (7.12.0): sent in the user's click, while its
1354
+ * element is still in the page at its size. `panel:popped-out` follows, or `panel:returned` when
1355
+ * the window fails before the panel got there. Not sent for a refused pop-out, nor for docking or
1356
+ * floating.
1344
1357
  */
1345
1358
  'panel:popping-out': {
1346
1359
  id: string;
1347
1360
  };
1348
1361
  /**
1349
1362
  * A panel in its own window is about to come back (7.12.0): sent just before its element leaves
1350
- * that window, whatever brings it back. `panel:returned` follows. Not sent for a panel closed while
1351
- * out.
1363
+ * that window, whatever brings it back, while it is still there at its size. `panel:returned`
1364
+ * follows. Not sent for a panel closed while out.
1352
1365
  */
1353
1366
  'panel:returning': {
1354
1367
  id: string;
@@ -1548,16 +1561,21 @@ declare class WorkspaceClient<TUserEvents extends object = Record<string, unknow
1548
1561
  * the panel's state, scroll offsets and a canvas's WebGL context go with it. A docked panel
1549
1562
  * remembers its group and goes back into it on return.
1550
1563
  *
1551
- * Call it inside the user's click or key press: browsers only open a window then. It is
1552
- * synchronous, and says what happened (see {@link PopOutResult}); on a refusal the panel stays
1553
- * where it is and nothing is shown to the user, so the app decides what to say. Calling it for a
1554
- * panel that is already out brings its window forward.
1564
+ * Call it inside the user's click or key press: browsers only open a window then. A click in
1565
+ * one of the app's pop-out windows counts too (7.12.1). It is synchronous, and says what
1566
+ * happened (see {@link PopOutResult}); on a refusal the panel stays where it is and nothing is
1567
+ * shown to the user, so the app decides what to say. Calling it for a panel that is already out
1568
+ * brings its window forward.
1555
1569
  *
1556
1570
  * Needs `createWorkspace({ popOut: true })` and the panel type's `defaultOptions.canPopOut`.
1557
1571
  * The window opens `<DockableDesktopProvider popoutUrl>`, or a blank window. When that page can't
1558
1572
  * be used after all (another origin, or it doesn't load within 10 s), the panel comes back and the
1559
1573
  * window closes, after this has returned `{ ok: true }`.
1560
1574
  *
1575
+ * On `{ ok: true }`, `panel:popping-out` was sent during the call, with the panel still in the
1576
+ * page; `panel:popped-out` follows once it is laid out in the window, or `panel:returned` when the
1577
+ * window fails first.
1578
+ *
1561
1579
  * @example
1562
1580
  * ```tsx
1563
1581
  * <button onClick={() => {
@@ -2190,7 +2208,7 @@ interface DockableDesktopProviderProps {
2190
2208
  * const caches = new WeakMap<Document, ReturnType<typeof createCache>>();
2191
2209
  * const cacheFor = (doc: Document) => {
2192
2210
  * let c = caches.get(doc);
2193
- * if (!c) { c = createCache({ key: 'app', container: doc.head }); caches.set(doc, c); }
2211
+ * if (!c) { c = createCache({ key: 'pop', container: doc.head }); caches.set(doc, c); }
2194
2212
  * return c;
2195
2213
  * };
2196
2214
  * const PopoutWrapper = ({ document, children }: PopoutWrapperProps) =>
@@ -2258,8 +2276,8 @@ interface RddDesktopProps {
2258
2276
  /**
2259
2277
  * Controls taskbar visibility.
2260
2278
  * - `'always'` — permanent bar at the bottom
2261
- * - `'compact'` — only visible when minimized panels exist
2262
- * - `'autohide'` — overlay bar with 8 px peek strip (default)
2279
+ * - `'compact'` — only visible when minimized panels exist, or a panel is in its own window (7.12.0)
2280
+ * - `'autohide'` — overlay bar with 8 px peek strip (default), shown under the same condition as `'compact'`
2263
2281
  * @default 'autohide'
2264
2282
  */
2265
2283
  taskbarVisibility?: TaskbarVisibility;
@@ -3309,11 +3327,12 @@ interface FloatingWidgetsApi {
3309
3327
  placement(id: string): WidgetPlacement | null;
3310
3328
  /**
3311
3329
  * Moves a widget into its own browser window (7.12.0), for a second monitor, without remounting
3312
- * its content. Synchronous: call it inside the user's click. From inside its panel it leaves the
3313
- * panel and goes into the window as one move; from docked, tabbed, floating or minimised, its
3314
- * panel moves. The same result and reasons as `workspace.popOutPanel` (`'not-allowed'` without
3315
- * {@link ManagedWidget.canPopOut}, or when its owner panel can't hold it out); a refusal changes
3316
- * nothing. While out, `location()` is `'floating'` and `useWidget().isPoppedOut` is true.
3330
+ * its content. Synchronous: call it inside the user's click, in the page or in a pop-out window
3331
+ * (its owner's, say: 7.12.1). From inside its panel it leaves the panel and goes into the window
3332
+ * as one move; from docked, tabbed, floating or minimised, its panel moves. The same result and
3333
+ * reasons as `workspace.popOutPanel` (`'not-allowed'` without {@link ManagedWidget.canPopOut}, or
3334
+ * when its owner panel can't hold it out); a refusal changes nothing. While out, `location()` is
3335
+ * `'floating'` and `useWidget().isPoppedOut` is true.
3317
3336
  *
3318
3337
  * Back: `move()` to any place returns it first, as one move; closing the window, or its "Back into
3319
3338
  * the panel" button, puts it back into its panel where it was (D17). `onWillMove` / `onMoved` run
package/dist/index.d.ts CHANGED
@@ -304,15 +304,20 @@ interface PanelInfo {
304
304
  poppedOut?: true;
305
305
  }
306
306
  /**
307
- * What `workspace.popOutPanel(id)` did (7.12.0): `{ ok: true }` when the panel is in its own
308
- * window (or already was), otherwise why not, checked in this order:
307
+ * What `workspace.popOutPanel(id)` did (7.12.0): `{ ok: true }` when its window opened (or was
308
+ * already open; the panel moves in at once, or once `popoutUrl` has loaded), otherwise why not,
309
+ * checked in this order:
309
310
  * - `'disabled'`: the workspace was created without `popOut: true`;
310
311
  * - `'not-open'`: no open panel has this id;
311
- * - `'not-allowed'`: the panel's type has no `canPopOut` (or it shows a widget out of its panel);
312
- * - `'no-gesture'`: the call did not come from a user's click or key press, so no window may open;
312
+ * - `'not-allowed'`: the panel's type has no `canPopOut` (for a widget's panel, the widget's rules
313
+ * decide);
314
+ * - (a panel already out stops here: its window comes forward, `{ ok: true }`);
315
+ * - `'no-gesture'`: the call did not come from a user's activation (a click or key press, or soon
316
+ * after one), so no window may open;
317
+ * - `'no-window'`: no `<DockableDesktopProvider>` is mounted to show it;
313
318
  * - `'blocked'`: the browser's pop-up blocker refused the window;
314
- * - `'no-window'`: no `<DockableDesktopProvider>` is mounted to show it, or the window closed or
315
- * could not be used before the panel moved in.
319
+ * - `'no-window'`: the window closed or could not be used before the panel moved in;
320
+ * - `'not-allowed'`: a widget that could not leave its panel after all (its window closes again).
316
321
  *
317
322
  * The panel stays where it was on every refusal.
318
323
  */
@@ -1245,6 +1250,8 @@ interface PopOutHost {
1245
1250
  width: number;
1246
1251
  height: number;
1247
1252
  } | null;
1253
+ /** The panel's element, or null when it has none (7.12.0): where it is decides when the events are sent. */
1254
+ element(id: string): Element | null;
1248
1255
  }
1249
1256
  /** @internal One open window, as the provider renders it. `doc` is null until its page has loaded. */
1250
1257
  interface PopOutEntry {
@@ -1271,13 +1278,15 @@ interface HostedPopOut {
1271
1278
  interface HostedPopOutOptions {
1272
1279
  /** Called once the window is open, before the panel moves in: takes the widget out of its panel if needed. */
1273
1280
  prepare: () => boolean;
1274
- /** Where the widget is on the main page (client pixels), for the window's place and size. */
1281
+ /** Where the widget is (client pixels of `view`, else of the main page), for the window's place and size. */
1275
1282
  rect?: {
1276
1283
  left: number;
1277
1284
  top: number;
1278
1285
  width: number;
1279
1286
  height: number;
1280
1287
  } | null;
1288
+ /** The window `rect` was measured in, when not the main page's (7.12.1): its owner panel's pop-out. */
1289
+ view?: Window;
1281
1290
  }
1282
1291
  /** @internal A workspace's pop-out windows: what `WorkspaceClient` and the provider use. */
1283
1292
  interface PopOutWindows {
@@ -1320,9 +1329,10 @@ interface BuiltInEvents {
1320
1329
  id: string;
1321
1330
  };
1322
1331
  /**
1323
- * A panel moved into its own browser window (`popOutPanel`, 7.12.0), once that window's page is
1324
- * ready: `window` is it, the one `usePanelWindow()` now gives the panel. Sent for a managed
1325
- * widget's own panel too (`useFloatingWidgets().popOut`), with that panel's id.
1332
+ * A panel moved into its own browser window (`popOutPanel`, 7.12.0), sent once it is laid out
1333
+ * there (in the window's frame, and a frame later), so a `resize()` sees the window's size:
1334
+ * `window` is it, the one `usePanelWindow()` now gives the panel. Sent for a managed widget's own
1335
+ * panel too (`useFloatingWidgets().popOut`), with that panel's id.
1326
1336
  */
1327
1337
  'panel:popped-out': {
1328
1338
  id: string;
@@ -1331,24 +1341,27 @@ interface BuiltInEvents {
1331
1341
  /**
1332
1342
  * A panel that was in its own window is back in the page (7.12.0), whatever brought it back: the
1333
1343
  * app, the frame's button, the window closing, the provider unmounting. Not sent for a panel
1334
- * closed while out (`panel:closed` is). Sent for a managed widget's own panel too, as it goes back
1335
- * into its owner panel.
1344
+ * closed while out (`panel:closed` is). Sent once it is laid out in its place (a frame later); a
1345
+ * panel back as a tab that isn't selected is 0 x 0 then. Also sent, without `panel:popped-out`,
1346
+ * when the window fails before the panel got there. Sent for a managed widget's own panel too, as
1347
+ * it goes back into its owner panel.
1336
1348
  */
1337
1349
  'panel:returned': {
1338
1350
  id: string;
1339
1351
  };
1340
1352
  /**
1341
- * A panel is about to move into its own window (7.12.0): sent just before its element leaves the
1342
- * page, once that window's page is ready. `panel:popped-out` follows. Not sent for a refused
1343
- * pop-out, nor for docking or floating.
1353
+ * A panel is about to move into its own window (7.12.0): sent in the user's click, while its
1354
+ * element is still in the page at its size. `panel:popped-out` follows, or `panel:returned` when
1355
+ * the window fails before the panel got there. Not sent for a refused pop-out, nor for docking or
1356
+ * floating.
1344
1357
  */
1345
1358
  'panel:popping-out': {
1346
1359
  id: string;
1347
1360
  };
1348
1361
  /**
1349
1362
  * A panel in its own window is about to come back (7.12.0): sent just before its element leaves
1350
- * that window, whatever brings it back. `panel:returned` follows. Not sent for a panel closed while
1351
- * out.
1363
+ * that window, whatever brings it back, while it is still there at its size. `panel:returned`
1364
+ * follows. Not sent for a panel closed while out.
1352
1365
  */
1353
1366
  'panel:returning': {
1354
1367
  id: string;
@@ -1548,16 +1561,21 @@ declare class WorkspaceClient<TUserEvents extends object = Record<string, unknow
1548
1561
  * the panel's state, scroll offsets and a canvas's WebGL context go with it. A docked panel
1549
1562
  * remembers its group and goes back into it on return.
1550
1563
  *
1551
- * Call it inside the user's click or key press: browsers only open a window then. It is
1552
- * synchronous, and says what happened (see {@link PopOutResult}); on a refusal the panel stays
1553
- * where it is and nothing is shown to the user, so the app decides what to say. Calling it for a
1554
- * panel that is already out brings its window forward.
1564
+ * Call it inside the user's click or key press: browsers only open a window then. A click in
1565
+ * one of the app's pop-out windows counts too (7.12.1). It is synchronous, and says what
1566
+ * happened (see {@link PopOutResult}); on a refusal the panel stays where it is and nothing is
1567
+ * shown to the user, so the app decides what to say. Calling it for a panel that is already out
1568
+ * brings its window forward.
1555
1569
  *
1556
1570
  * Needs `createWorkspace({ popOut: true })` and the panel type's `defaultOptions.canPopOut`.
1557
1571
  * The window opens `<DockableDesktopProvider popoutUrl>`, or a blank window. When that page can't
1558
1572
  * be used after all (another origin, or it doesn't load within 10 s), the panel comes back and the
1559
1573
  * window closes, after this has returned `{ ok: true }`.
1560
1574
  *
1575
+ * On `{ ok: true }`, `panel:popping-out` was sent during the call, with the panel still in the
1576
+ * page; `panel:popped-out` follows once it is laid out in the window, or `panel:returned` when the
1577
+ * window fails first.
1578
+ *
1561
1579
  * @example
1562
1580
  * ```tsx
1563
1581
  * <button onClick={() => {
@@ -2190,7 +2208,7 @@ interface DockableDesktopProviderProps {
2190
2208
  * const caches = new WeakMap<Document, ReturnType<typeof createCache>>();
2191
2209
  * const cacheFor = (doc: Document) => {
2192
2210
  * let c = caches.get(doc);
2193
- * if (!c) { c = createCache({ key: 'app', container: doc.head }); caches.set(doc, c); }
2211
+ * if (!c) { c = createCache({ key: 'pop', container: doc.head }); caches.set(doc, c); }
2194
2212
  * return c;
2195
2213
  * };
2196
2214
  * const PopoutWrapper = ({ document, children }: PopoutWrapperProps) =>
@@ -2258,8 +2276,8 @@ interface RddDesktopProps {
2258
2276
  /**
2259
2277
  * Controls taskbar visibility.
2260
2278
  * - `'always'` — permanent bar at the bottom
2261
- * - `'compact'` — only visible when minimized panels exist
2262
- * - `'autohide'` — overlay bar with 8 px peek strip (default)
2279
+ * - `'compact'` — only visible when minimized panels exist, or a panel is in its own window (7.12.0)
2280
+ * - `'autohide'` — overlay bar with 8 px peek strip (default), shown under the same condition as `'compact'`
2263
2281
  * @default 'autohide'
2264
2282
  */
2265
2283
  taskbarVisibility?: TaskbarVisibility;
@@ -3309,11 +3327,12 @@ interface FloatingWidgetsApi {
3309
3327
  placement(id: string): WidgetPlacement | null;
3310
3328
  /**
3311
3329
  * Moves a widget into its own browser window (7.12.0), for a second monitor, without remounting
3312
- * its content. Synchronous: call it inside the user's click. From inside its panel it leaves the
3313
- * panel and goes into the window as one move; from docked, tabbed, floating or minimised, its
3314
- * panel moves. The same result and reasons as `workspace.popOutPanel` (`'not-allowed'` without
3315
- * {@link ManagedWidget.canPopOut}, or when its owner panel can't hold it out); a refusal changes
3316
- * nothing. While out, `location()` is `'floating'` and `useWidget().isPoppedOut` is true.
3330
+ * its content. Synchronous: call it inside the user's click, in the page or in a pop-out window
3331
+ * (its owner's, say: 7.12.1). From inside its panel it leaves the panel and goes into the window
3332
+ * as one move; from docked, tabbed, floating or minimised, its panel moves. The same result and
3333
+ * reasons as `workspace.popOutPanel` (`'not-allowed'` without {@link ManagedWidget.canPopOut}, or
3334
+ * when its owner panel can't hold it out); a refusal changes nothing. While out, `location()` is
3335
+ * `'floating'` and `useWidget().isPoppedOut` is true.
3317
3336
  *
3318
3337
  * Back: `move()` to any place returns it first, as one move; closing the window, or its "Back into
3319
3338
  * the panel" button, puts it back into its panel where it was (D17). `onWillMove` / `onMoved` run