react-dockable-desktop 7.12.0-next.0 → 7.12.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
@@ -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 {
@@ -1320,9 +1327,10 @@ interface BuiltInEvents {
1320
1327
  id: string;
1321
1328
  };
1322
1329
  /**
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.
1330
+ * A panel moved into its own browser window (`popOutPanel`, 7.12.0), sent once it is laid out
1331
+ * there (in the window's frame, and a frame later), so a `resize()` sees the window's size:
1332
+ * `window` is it, the one `usePanelWindow()` now gives the panel. Sent for a managed widget's own
1333
+ * panel too (`useFloatingWidgets().popOut`), with that panel's id.
1326
1334
  */
1327
1335
  'panel:popped-out': {
1328
1336
  id: string;
@@ -1331,12 +1339,31 @@ interface BuiltInEvents {
1331
1339
  /**
1332
1340
  * A panel that was in its own window is back in the page (7.12.0), whatever brought it back: the
1333
1341
  * 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.
1342
+ * closed while out (`panel:closed` is). Sent once it is laid out in its place (a frame later); a
1343
+ * panel back as a tab that isn't selected is 0 x 0 then. Also sent, without `panel:popped-out`,
1344
+ * when the window fails before the panel got there. Sent for a managed widget's own panel too, as
1345
+ * it goes back into its owner panel.
1336
1346
  */
1337
1347
  'panel:returned': {
1338
1348
  id: string;
1339
1349
  };
1350
+ /**
1351
+ * A panel is about to move into its own window (7.12.0): sent in the user's click, while its
1352
+ * element is still in the page at its size. `panel:popped-out` follows, or `panel:returned` when
1353
+ * the window fails before the panel got there. Not sent for a refused pop-out, nor for docking or
1354
+ * floating.
1355
+ */
1356
+ 'panel:popping-out': {
1357
+ id: string;
1358
+ };
1359
+ /**
1360
+ * A panel in its own window is about to come back (7.12.0): sent just before its element leaves
1361
+ * that window, whatever brings it back, while it is still there at its size. `panel:returned`
1362
+ * follows. Not sent for a panel closed while out.
1363
+ */
1364
+ 'panel:returning': {
1365
+ id: string;
1366
+ };
1340
1367
  /**
1341
1368
  * Fires whenever something `saveLayout()` would capture changes — open/close/minimize/restore,
1342
1369
  * float/dock/re-order/dock-to-edge, closing a group, maximizing a minimized panel, and an
@@ -1542,6 +1569,10 @@ declare class WorkspaceClient<TUserEvents extends object = Record<string, unknow
1542
1569
  * be used after all (another origin, or it doesn't load within 10 s), the panel comes back and the
1543
1570
  * window closes, after this has returned `{ ok: true }`.
1544
1571
  *
1572
+ * On `{ ok: true }`, `panel:popping-out` was sent during the call, with the panel still in the
1573
+ * page; `panel:popped-out` follows once it is laid out in the window, or `panel:returned` when the
1574
+ * window fails first.
1575
+ *
1545
1576
  * @example
1546
1577
  * ```tsx
1547
1578
  * <button onClick={() => {
@@ -2152,7 +2183,8 @@ interface DockableDesktopProviderProps {
2152
2183
  * `/popout.html`, with an empty `<body>`. The library waits for it to load, then moves the panel
2153
2184
  * in. Without it, the window opens blank. A page that can't be read (another origin, or a redirect
2154
2185
  * off this one) or doesn't load within 10 s sends the panel back. Only used with
2155
- * `createWorkspace({ popOut: true })`.
2186
+ * `createWorkspace({ popOut: true })`. Set it when a third-party embed refuses a blank window: a
2187
+ * YouTube player, for one, shows error 153 there.
2156
2188
  */
2157
2189
  popoutUrl?: string;
2158
2190
  /**
@@ -2161,7 +2193,9 @@ interface DockableDesktopProviderProps {
2161
2193
  * document, so the panel's styles are inserted where it is shown (a pop-out doesn't get rules
2162
2194
  * inserted with `insertRule` from the page). Rendered for every panel, for its whole life, while
2163
2195
  * the workspace has `popOut: true` (none otherwise), so nothing remounts when a panel moves. Pass
2164
- * a stable component (defined outside a render), not an inline function.
2196
+ * a stable component (defined outside a render), not an inline function. In a pop-out it is also
2197
+ * rendered around the window's frame (the icon and title you give the panel), a context menu and
2198
+ * the toasts shown there, with that window: keep one cache per document, not per wrapper.
2165
2199
  *
2166
2200
  * @example
2167
2201
  * ```tsx
@@ -2171,7 +2205,7 @@ interface DockableDesktopProviderProps {
2171
2205
  * const caches = new WeakMap<Document, ReturnType<typeof createCache>>();
2172
2206
  * const cacheFor = (doc: Document) => {
2173
2207
  * let c = caches.get(doc);
2174
- * if (!c) { c = createCache({ key: 'app', container: doc.head }); caches.set(doc, c); }
2208
+ * if (!c) { c = createCache({ key: 'pop', container: doc.head }); caches.set(doc, c); }
2175
2209
  * return c;
2176
2210
  * };
2177
2211
  * const PopoutWrapper = ({ document, children }: PopoutWrapperProps) =>
@@ -2239,8 +2273,8 @@ interface RddDesktopProps {
2239
2273
  /**
2240
2274
  * Controls taskbar visibility.
2241
2275
  * - `'always'` — permanent bar at the bottom
2242
- * - `'compact'` — only visible when minimized panels exist
2243
- * - `'autohide'` — overlay bar with 8 px peek strip (default)
2276
+ * - `'compact'` — only visible when minimized panels exist, or a panel is in its own window (7.12.0)
2277
+ * - `'autohide'` — overlay bar with 8 px peek strip (default), shown under the same condition as `'compact'`
2244
2278
  * @default 'autohide'
2245
2279
  */
2246
2280
  taskbarVisibility?: TaskbarVisibility;
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 {
@@ -1320,9 +1327,10 @@ interface BuiltInEvents {
1320
1327
  id: string;
1321
1328
  };
1322
1329
  /**
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.
1330
+ * A panel moved into its own browser window (`popOutPanel`, 7.12.0), sent once it is laid out
1331
+ * there (in the window's frame, and a frame later), so a `resize()` sees the window's size:
1332
+ * `window` is it, the one `usePanelWindow()` now gives the panel. Sent for a managed widget's own
1333
+ * panel too (`useFloatingWidgets().popOut`), with that panel's id.
1326
1334
  */
1327
1335
  'panel:popped-out': {
1328
1336
  id: string;
@@ -1331,12 +1339,31 @@ interface BuiltInEvents {
1331
1339
  /**
1332
1340
  * A panel that was in its own window is back in the page (7.12.0), whatever brought it back: the
1333
1341
  * 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.
1342
+ * closed while out (`panel:closed` is). Sent once it is laid out in its place (a frame later); a
1343
+ * panel back as a tab that isn't selected is 0 x 0 then. Also sent, without `panel:popped-out`,
1344
+ * when the window fails before the panel got there. Sent for a managed widget's own panel too, as
1345
+ * it goes back into its owner panel.
1336
1346
  */
1337
1347
  'panel:returned': {
1338
1348
  id: string;
1339
1349
  };
1350
+ /**
1351
+ * A panel is about to move into its own window (7.12.0): sent in the user's click, while its
1352
+ * element is still in the page at its size. `panel:popped-out` follows, or `panel:returned` when
1353
+ * the window fails before the panel got there. Not sent for a refused pop-out, nor for docking or
1354
+ * floating.
1355
+ */
1356
+ 'panel:popping-out': {
1357
+ id: string;
1358
+ };
1359
+ /**
1360
+ * A panel in its own window is about to come back (7.12.0): sent just before its element leaves
1361
+ * that window, whatever brings it back, while it is still there at its size. `panel:returned`
1362
+ * follows. Not sent for a panel closed while out.
1363
+ */
1364
+ 'panel:returning': {
1365
+ id: string;
1366
+ };
1340
1367
  /**
1341
1368
  * Fires whenever something `saveLayout()` would capture changes — open/close/minimize/restore,
1342
1369
  * float/dock/re-order/dock-to-edge, closing a group, maximizing a minimized panel, and an
@@ -1542,6 +1569,10 @@ declare class WorkspaceClient<TUserEvents extends object = Record<string, unknow
1542
1569
  * be used after all (another origin, or it doesn't load within 10 s), the panel comes back and the
1543
1570
  * window closes, after this has returned `{ ok: true }`.
1544
1571
  *
1572
+ * On `{ ok: true }`, `panel:popping-out` was sent during the call, with the panel still in the
1573
+ * page; `panel:popped-out` follows once it is laid out in the window, or `panel:returned` when the
1574
+ * window fails first.
1575
+ *
1545
1576
  * @example
1546
1577
  * ```tsx
1547
1578
  * <button onClick={() => {
@@ -2152,7 +2183,8 @@ interface DockableDesktopProviderProps {
2152
2183
  * `/popout.html`, with an empty `<body>`. The library waits for it to load, then moves the panel
2153
2184
  * in. Without it, the window opens blank. A page that can't be read (another origin, or a redirect
2154
2185
  * off this one) or doesn't load within 10 s sends the panel back. Only used with
2155
- * `createWorkspace({ popOut: true })`.
2186
+ * `createWorkspace({ popOut: true })`. Set it when a third-party embed refuses a blank window: a
2187
+ * YouTube player, for one, shows error 153 there.
2156
2188
  */
2157
2189
  popoutUrl?: string;
2158
2190
  /**
@@ -2161,7 +2193,9 @@ interface DockableDesktopProviderProps {
2161
2193
  * document, so the panel's styles are inserted where it is shown (a pop-out doesn't get rules
2162
2194
  * inserted with `insertRule` from the page). Rendered for every panel, for its whole life, while
2163
2195
  * the workspace has `popOut: true` (none otherwise), so nothing remounts when a panel moves. Pass
2164
- * a stable component (defined outside a render), not an inline function.
2196
+ * a stable component (defined outside a render), not an inline function. In a pop-out it is also
2197
+ * rendered around the window's frame (the icon and title you give the panel), a context menu and
2198
+ * the toasts shown there, with that window: keep one cache per document, not per wrapper.
2165
2199
  *
2166
2200
  * @example
2167
2201
  * ```tsx
@@ -2171,7 +2205,7 @@ interface DockableDesktopProviderProps {
2171
2205
  * const caches = new WeakMap<Document, ReturnType<typeof createCache>>();
2172
2206
  * const cacheFor = (doc: Document) => {
2173
2207
  * let c = caches.get(doc);
2174
- * if (!c) { c = createCache({ key: 'app', container: doc.head }); caches.set(doc, c); }
2208
+ * if (!c) { c = createCache({ key: 'pop', container: doc.head }); caches.set(doc, c); }
2175
2209
  * return c;
2176
2210
  * };
2177
2211
  * const PopoutWrapper = ({ document, children }: PopoutWrapperProps) =>
@@ -2239,8 +2273,8 @@ interface RddDesktopProps {
2239
2273
  /**
2240
2274
  * Controls taskbar visibility.
2241
2275
  * - `'always'` — permanent bar at the bottom
2242
- * - `'compact'` — only visible when minimized panels exist
2243
- * - `'autohide'` — overlay bar with 8 px peek strip (default)
2276
+ * - `'compact'` — only visible when minimized panels exist, or a panel is in its own window (7.12.0)
2277
+ * - `'autohide'` — overlay bar with 8 px peek strip (default), shown under the same condition as `'compact'`
2244
2278
  * @default 'autohide'
2245
2279
  */
2246
2280
  taskbarVisibility?: TaskbarVisibility;