react-dockable-desktop 7.11.0 → 7.12.0-next.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/CHANGELOG.md +163 -1
- package/README.md +13 -4
- package/dist/index.cjs +10 -8
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +381 -3
- package/dist/index.d.ts +381 -3
- package/dist/index.js +10 -8
- package/dist/index.js.map +1 -1
- package/dist/styles.css +61 -0
- package/package.json +3 -1
package/dist/index.d.cts
CHANGED
|
@@ -295,7 +295,33 @@ interface PanelInfo {
|
|
|
295
295
|
* the owner panel saves its widgets itself. (7.11.0)
|
|
296
296
|
*/
|
|
297
297
|
owner?: PanelOwner;
|
|
298
|
+
/**
|
|
299
|
+
* Set while the panel is shown in its own browser window (`workspace.popOutPanel`). Such a
|
|
300
|
+
* panel is `state: 'floating'` and keeps its floating window entry, which the workspace does not
|
|
301
|
+
* draw. Runtime only: `saveLayout()` writes the panel where it would come back to (docked in its
|
|
302
|
+
* place, or floating at its rect), without it, and a loaded layout never has it. (7.12.0)
|
|
303
|
+
*/
|
|
304
|
+
poppedOut?: true;
|
|
298
305
|
}
|
|
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:
|
|
309
|
+
* - `'disabled'`: the workspace was created without `popOut: true`;
|
|
310
|
+
* - `'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;
|
|
313
|
+
* - `'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.
|
|
316
|
+
*
|
|
317
|
+
* The panel stays where it was on every refusal.
|
|
318
|
+
*/
|
|
319
|
+
type PopOutResult = {
|
|
320
|
+
ok: true;
|
|
321
|
+
} | {
|
|
322
|
+
ok: false;
|
|
323
|
+
reason: 'disabled' | 'not-open' | 'not-allowed' | 'no-gesture' | 'blocked' | 'no-window';
|
|
324
|
+
};
|
|
299
325
|
/** Who a hosted panel belongs to: see {@link PanelInfo.owner}. (7.11.0) */
|
|
300
326
|
interface PanelOwner {
|
|
301
327
|
/** The panel whose overlay opened the widget. */
|
|
@@ -461,6 +487,9 @@ interface WorkspaceActions {
|
|
|
461
487
|
* @param id - Panel instance ID.
|
|
462
488
|
* @param rect - Optional initial position and size. Omit to use the last known position or a cascaded default.
|
|
463
489
|
* @param anchor - Optional corner to pin the new floating window to. Omit (or pass `null`) for free-float.
|
|
490
|
+
*
|
|
491
|
+
* Ignored while the panel is in its own browser window (`popOutPanel`, 7.12.0): it has no window
|
|
492
|
+
* on the page to place until it returns.
|
|
464
493
|
*/
|
|
465
494
|
floatPanel: (id: string, rect?: {
|
|
466
495
|
x: number;
|
|
@@ -477,6 +506,8 @@ interface WorkspaceActions {
|
|
|
477
506
|
/**
|
|
478
507
|
* Maximizes a floating window to cover the entire workspace viewport.
|
|
479
508
|
* @param id - Panel instance ID.
|
|
509
|
+
*
|
|
510
|
+
* Ignored while the panel is in its own browser window (`popOutPanel`, 7.12.0).
|
|
480
511
|
*/
|
|
481
512
|
maximizePanel: (id: string) => void;
|
|
482
513
|
/**
|
|
@@ -734,6 +765,19 @@ interface InternalWindowActions extends WorkspaceActions {
|
|
|
734
765
|
* closes. `onDrop`, just before a `loadLayout` drops it: the widget is about to go home. (7.11.0)
|
|
735
766
|
*/
|
|
736
767
|
registerHostedCloseHandler: (id: string, onClose: () => void, onDrop?: () => void) => () => void;
|
|
768
|
+
/**
|
|
769
|
+
* @internal Marks an open panel as shown in its own window (7.12.0): a docked or minimized panel
|
|
770
|
+
* becomes floating first, remembering its group. Returns `false`, changing nothing, when the
|
|
771
|
+
* workspace has no `popOut` or there is no such panel.
|
|
772
|
+
*/
|
|
773
|
+
setPoppedOut: (id: string) => boolean;
|
|
774
|
+
/**
|
|
775
|
+
* @internal Clears a panel's pop-out flag (7.12.0). With `restorePlace`, a panel that was docked
|
|
776
|
+
* goes back where it was: its tab-mates' group, its own kept empty group, beside the panels it was
|
|
777
|
+
* next to, the grid when no panel is docked, else floating (or the first group for a type that
|
|
778
|
+
* can't float). See `WorkspaceClient.returnPanel`.
|
|
779
|
+
*/
|
|
780
|
+
clearPoppedOut: (id: string, restorePlace: boolean) => void;
|
|
737
781
|
}
|
|
738
782
|
/** @internal Where a hosted panel opens. (7.11.0) */
|
|
739
783
|
type HostedPanelPlacement = {
|
|
@@ -873,6 +917,13 @@ interface PanelRegistryEntry {
|
|
|
873
917
|
* reloads. Off by default. @default false
|
|
874
918
|
*/
|
|
875
919
|
preserveEmbeds?: boolean;
|
|
920
|
+
/**
|
|
921
|
+
* `true`: a panel of this type can move into its own browser window (7.12.0), from its "Open
|
|
922
|
+
* in new window" menu item or `workspace.popOutPanel(id)`. Needs a workspace created with
|
|
923
|
+
* `popOut: true`. It gates the menu item and new calls only: a window already open stays open
|
|
924
|
+
* when this changes. @default false
|
|
925
|
+
*/
|
|
926
|
+
canPopOut?: boolean;
|
|
876
927
|
};
|
|
877
928
|
}
|
|
878
929
|
/**
|
|
@@ -1064,6 +1115,26 @@ declare const defaultPredefinedMessages: {
|
|
|
1064
1115
|
readonly id: "dockable-desktop-untitledPanel";
|
|
1065
1116
|
readonly defaultMessage: "Panel";
|
|
1066
1117
|
};
|
|
1118
|
+
readonly popOutWindow: {
|
|
1119
|
+
readonly id: "dockable-desktop-popOutWindow";
|
|
1120
|
+
readonly defaultMessage: "Open in new window";
|
|
1121
|
+
};
|
|
1122
|
+
readonly returnToDesktop: {
|
|
1123
|
+
readonly id: "dockable-desktop-returnToDesktop";
|
|
1124
|
+
readonly defaultMessage: "Return to desktop";
|
|
1125
|
+
};
|
|
1126
|
+
readonly inOwnWindow: {
|
|
1127
|
+
readonly id: "dockable-desktop-inOwnWindow";
|
|
1128
|
+
readonly defaultMessage: "in its own window";
|
|
1129
|
+
};
|
|
1130
|
+
readonly backIntoPanel: {
|
|
1131
|
+
readonly id: "dockable-desktop-backIntoPanel";
|
|
1132
|
+
readonly defaultMessage: "Back into the panel";
|
|
1133
|
+
};
|
|
1134
|
+
readonly popOutBlocked: {
|
|
1135
|
+
readonly id: "dockable-desktop-popOutBlocked";
|
|
1136
|
+
readonly defaultMessage: "The browser blocked the new window. Allow pop-ups for this site and try again.";
|
|
1137
|
+
};
|
|
1067
1138
|
};
|
|
1068
1139
|
/**
|
|
1069
1140
|
* Union of every key in `defaultMessages`.
|
|
@@ -1144,6 +1215,95 @@ declare const usePredefinedMessages: () => Record<MessageKey, MessageDescriptor>
|
|
|
1144
1215
|
*/
|
|
1145
1216
|
declare function usePanelContextMenu(items: ContextMenuItem[]): void;
|
|
1146
1217
|
|
|
1218
|
+
/**
|
|
1219
|
+
* @file popOutWindows.ts
|
|
1220
|
+
* @description A workspace's pop-out windows (7.12.0): a panel shown in its own browser window.
|
|
1221
|
+
* Internal: the public face is `workspace.popOutPanel` / `workspace.returnPanel`.
|
|
1222
|
+
*
|
|
1223
|
+
* The workspace client owns the windows, because `window.open` must run synchronously inside the
|
|
1224
|
+
* user's click, outside React. The store marks the panel (`PanelInfo.poppedOut`, a floating panel
|
|
1225
|
+
* whose frame the workspace doesn't draw); the provider subscribes here and renders, per window,
|
|
1226
|
+
* the library's frame and a slot into the child's `<body>`, which the panel's preserved element
|
|
1227
|
+
* moves into. Nothing remounts.
|
|
1228
|
+
*
|
|
1229
|
+
* Every way back ends in one function, {@link PopOutWindows.returnPanel}'s core: the frame's
|
|
1230
|
+
* button, the app's call, the child's `pagehide` (the element is moved back to the main document
|
|
1231
|
+
* inside the handler, before the child's document goes), a `closed` poll as a backstop, and the
|
|
1232
|
+
* main page's own `pagehide`. A panel that stops being a popped-out floating panel some other way
|
|
1233
|
+
* (closed, docked or minimized by the app, dropped by `loadLayout`) closes its window too: the
|
|
1234
|
+
* windows follow the store, never the other way round.
|
|
1235
|
+
*/
|
|
1236
|
+
|
|
1237
|
+
/** @internal What the provider lends the windows: the panel's element, where it is and how to take it back. */
|
|
1238
|
+
interface PopOutHost {
|
|
1239
|
+
/** Moves the panel's element back into the main document, now. */
|
|
1240
|
+
park(id: string): void;
|
|
1241
|
+
/** The panel's box on the main page, or null when it isn't shown. */
|
|
1242
|
+
rectOf(id: string): {
|
|
1243
|
+
left: number;
|
|
1244
|
+
top: number;
|
|
1245
|
+
width: number;
|
|
1246
|
+
height: number;
|
|
1247
|
+
} | null;
|
|
1248
|
+
}
|
|
1249
|
+
/** @internal One open window, as the provider renders it. `doc` is null until its page has loaded. */
|
|
1250
|
+
interface PopOutEntry {
|
|
1251
|
+
/** This window's own name: unique per window opened, so a re-opened panel renders afresh. */
|
|
1252
|
+
readonly key: string;
|
|
1253
|
+
readonly id: string;
|
|
1254
|
+
readonly win: Window;
|
|
1255
|
+
readonly doc: Document | null;
|
|
1256
|
+
}
|
|
1257
|
+
/**
|
|
1258
|
+
* @internal What a managed widget's overlay lends for its hosted panel (7.12.0, S5): the panel is
|
|
1259
|
+
* popped out through the widget (it may have to leave its panel first), and comes back into the
|
|
1260
|
+
* panel when its window closes (D17).
|
|
1261
|
+
*/
|
|
1262
|
+
interface HostedPopOut {
|
|
1263
|
+
/** `popOutPanel(hostedId)`: the widget's own `popOut()`. */
|
|
1264
|
+
popOut(): PopOutResult;
|
|
1265
|
+
/** Its window is closing to bring it back (not a move from code): before the element moves. */
|
|
1266
|
+
returning(): void;
|
|
1267
|
+
/** ...and it is out of the window: the widget goes back into its panel. */
|
|
1268
|
+
returned(): void;
|
|
1269
|
+
}
|
|
1270
|
+
/** @internal How a hosted panel is popped out: the widget has checked its own rules. */
|
|
1271
|
+
interface HostedPopOutOptions {
|
|
1272
|
+
/** Called once the window is open, before the panel moves in: takes the widget out of its panel if needed. */
|
|
1273
|
+
prepare: () => boolean;
|
|
1274
|
+
/** Where the widget is on the main page (client pixels), for the window's place and size. */
|
|
1275
|
+
rect?: {
|
|
1276
|
+
left: number;
|
|
1277
|
+
top: number;
|
|
1278
|
+
width: number;
|
|
1279
|
+
height: number;
|
|
1280
|
+
} | null;
|
|
1281
|
+
}
|
|
1282
|
+
/** @internal A workspace's pop-out windows: what `WorkspaceClient` and the provider use. */
|
|
1283
|
+
interface PopOutWindows {
|
|
1284
|
+
/** See `WorkspaceClient.popOutPanel`. With `hosted`, a managed widget's own pop-out (S5). */
|
|
1285
|
+
popOut(id: string, hosted?: HostedPopOutOptions): PopOutResult;
|
|
1286
|
+
/** Brings a panel's window forward, best effort (7.12.0, S6); false when it has none. */
|
|
1287
|
+
focusWindow(id: string): boolean;
|
|
1288
|
+
/** Lends a hosted panel's widget rules; returns the function that takes them back. */
|
|
1289
|
+
registerHosted(panelId: string, hosted: HostedPopOut): () => void;
|
|
1290
|
+
/** See `WorkspaceClient.returnPanel`. */
|
|
1291
|
+
returnPanel(id: string): {
|
|
1292
|
+
ok: boolean;
|
|
1293
|
+
};
|
|
1294
|
+
/** Whether the user may pop this panel out now (the menu item's rule). */
|
|
1295
|
+
canPopOut(id: string): boolean;
|
|
1296
|
+
/** Whether the workspace was created with `popOut: true`. */
|
|
1297
|
+
readonly enabled: boolean;
|
|
1298
|
+
/** The app's page for a pop-out (`<DockableDesktopProvider popoutUrl>`); a blank window without one. */
|
|
1299
|
+
setUrl(url: string | undefined): void;
|
|
1300
|
+
/** The provider lends its panel host; returns the function that takes it back. */
|
|
1301
|
+
bindHost(host: PopOutHost): () => void;
|
|
1302
|
+
/** For `useSyncExternalStore`: the open windows, a new array whenever they change. */
|
|
1303
|
+
subscribe(cb: () => void): () => void;
|
|
1304
|
+
getSnapshot(): readonly PopOutEntry[];
|
|
1305
|
+
}
|
|
1306
|
+
|
|
1147
1307
|
/** Built-in lifecycle events always available on the workspace event bus. */
|
|
1148
1308
|
interface BuiltInEvents {
|
|
1149
1309
|
'panel:opened': {
|
|
@@ -1159,6 +1319,40 @@ interface BuiltInEvents {
|
|
|
1159
1319
|
'panel:restored': {
|
|
1160
1320
|
id: string;
|
|
1161
1321
|
};
|
|
1322
|
+
/**
|
|
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.
|
|
1326
|
+
*/
|
|
1327
|
+
'panel:popped-out': {
|
|
1328
|
+
id: string;
|
|
1329
|
+
window: Window;
|
|
1330
|
+
};
|
|
1331
|
+
/**
|
|
1332
|
+
* A panel that was in its own window is back in the page (7.12.0), whatever brought it back: the
|
|
1333
|
+
* 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.
|
|
1336
|
+
*/
|
|
1337
|
+
'panel:returned': {
|
|
1338
|
+
id: string;
|
|
1339
|
+
};
|
|
1340
|
+
/**
|
|
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.
|
|
1344
|
+
*/
|
|
1345
|
+
'panel:popping-out': {
|
|
1346
|
+
id: string;
|
|
1347
|
+
};
|
|
1348
|
+
/**
|
|
1349
|
+
* 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.
|
|
1352
|
+
*/
|
|
1353
|
+
'panel:returning': {
|
|
1354
|
+
id: string;
|
|
1355
|
+
};
|
|
1162
1356
|
/**
|
|
1163
1357
|
* Fires whenever something `saveLayout()` would capture changes — open/close/minimize/restore,
|
|
1164
1358
|
* float/dock/re-order/dock-to-edge, closing a group, maximizing a minimized panel, and an
|
|
@@ -1247,6 +1441,21 @@ interface WorkspaceClientConfig {
|
|
|
1247
1441
|
* ```
|
|
1248
1442
|
*/
|
|
1249
1443
|
canDrop?: (drop: PanelDrop) => boolean;
|
|
1444
|
+
/**
|
|
1445
|
+
* Lets panels move into their own browser window, for a second monitor (7.12.0): a panel type
|
|
1446
|
+
* opts in with `defaultOptions.canPopOut`, and the user opens it with "Open in new window" or
|
|
1447
|
+
* the app with `workspace.popOutPanel(id)`. Set once, here. With `false`, nothing of it runs: no menu item, and `popOutPanel` returns
|
|
1448
|
+
* `{ ok: false, reason: 'disabled' }`. @default false
|
|
1449
|
+
*
|
|
1450
|
+
* @example
|
|
1451
|
+
* ```ts
|
|
1452
|
+
* const workspace = createWorkspace({
|
|
1453
|
+
* popOut: true,
|
|
1454
|
+
* panels: { chart: { component: ChartPanel, defaultOptions: { canPopOut: true } } },
|
|
1455
|
+
* });
|
|
1456
|
+
* ```
|
|
1457
|
+
*/
|
|
1458
|
+
popOut?: boolean;
|
|
1250
1459
|
}
|
|
1251
1460
|
/**
|
|
1252
1461
|
* A workspace: the layout, every action on it, the panel registry and the event bus. Create one
|
|
@@ -1287,6 +1496,8 @@ declare class WorkspaceClient<TUserEvents extends object = Record<string, unknow
|
|
|
1287
1496
|
readonly config: Pick<WorkspaceClientConfig, 'formatMessage' | 'predefinedMessages' | 'dir' | 'defaultSplitRatio' | 'defaultEdgeSplitRatio' | 'zIndexBase'>;
|
|
1288
1497
|
/** @internal The workspace store. Live from construction; a provider only subscribes to it. */
|
|
1289
1498
|
readonly _core: WorkspaceCore;
|
|
1499
|
+
/** @internal The workspace's pop-out windows (7.12.0); the provider renders them. */
|
|
1500
|
+
readonly _popOut: PopOutWindows;
|
|
1290
1501
|
/** The store's actions, to which every method below forwards. */
|
|
1291
1502
|
private get _actions();
|
|
1292
1503
|
constructor(config?: WorkspaceClientConfig);
|
|
@@ -1304,6 +1515,7 @@ declare class WorkspaceClient<TUserEvents extends object = Record<string, unknow
|
|
|
1304
1515
|
* For floating panels: raises z-index so the window appears on top.
|
|
1305
1516
|
* For docked panels: selects the tab within its leaf group.
|
|
1306
1517
|
* For minimized panels: makes it the active one, but leaves it minimized.
|
|
1518
|
+
* For a panel in its own window (7.12.0): also brings that window forward, best effort.
|
|
1307
1519
|
*/
|
|
1308
1520
|
focusPanel(id: string): void;
|
|
1309
1521
|
/**
|
|
@@ -1317,6 +1529,61 @@ declare class WorkspaceClient<TUserEvents extends object = Record<string, unknow
|
|
|
1317
1529
|
focusPanel(id: string, options: {
|
|
1318
1530
|
restore?: boolean;
|
|
1319
1531
|
}): void;
|
|
1532
|
+
/**
|
|
1533
|
+
* Brings forward the window that holds a panel, and makes it the active panel (7.12.0): its
|
|
1534
|
+
* pop-out for a panel in its own window (a widget's panel too), the main window for one in the
|
|
1535
|
+
* page. Best effort: a browser may keep another window in front. `ok` is false for an id that
|
|
1536
|
+
* isn't open.
|
|
1537
|
+
* @example
|
|
1538
|
+
* ```tsx
|
|
1539
|
+
* // From a widget in its own window: bring its owner panel's window forward.
|
|
1540
|
+
* workspace.focusPanelWindow(useWidget()!.ownerPanelId!);
|
|
1541
|
+
* ```
|
|
1542
|
+
*/
|
|
1543
|
+
focusPanelWindow(id: string): {
|
|
1544
|
+
ok: boolean;
|
|
1545
|
+
};
|
|
1546
|
+
/**
|
|
1547
|
+
* Moves a panel into its own browser window (7.12.0), for a second monitor. Nothing remounts:
|
|
1548
|
+
* the panel's state, scroll offsets and a canvas's WebGL context go with it. A docked panel
|
|
1549
|
+
* remembers its group and goes back into it on return.
|
|
1550
|
+
*
|
|
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.
|
|
1555
|
+
*
|
|
1556
|
+
* Needs `createWorkspace({ popOut: true })` and the panel type's `defaultOptions.canPopOut`.
|
|
1557
|
+
* The window opens `<DockableDesktopProvider popoutUrl>`, or a blank window. When that page can't
|
|
1558
|
+
* be used after all (another origin, or it doesn't load within 10 s), the panel comes back and the
|
|
1559
|
+
* window closes, after this has returned `{ ok: true }`.
|
|
1560
|
+
*
|
|
1561
|
+
* @example
|
|
1562
|
+
* ```tsx
|
|
1563
|
+
* <button onClick={() => {
|
|
1564
|
+
* const result = workspace.popOutPanel('chart-1');
|
|
1565
|
+
* if (!result.ok && result.reason === 'blocked') alert('Allow pop-ups for this site.');
|
|
1566
|
+
* }}>Pop out</button>
|
|
1567
|
+
* ```
|
|
1568
|
+
*/
|
|
1569
|
+
popOutPanel(id: string): PopOutResult;
|
|
1570
|
+
/**
|
|
1571
|
+
* Brings a panel back from its own window (7.12.0), where it was. A panel that was floating
|
|
1572
|
+
* floats at its rect. One that was docked goes, in this order:
|
|
1573
|
+
* - into the group of its tab-mates, among their tabs, when one of them is docked;
|
|
1574
|
+
* - into its own group, when that group was kept and waits empty;
|
|
1575
|
+
* - beside the panels it was next to, on the same side at the same size (the nearest part of its
|
|
1576
|
+
* old layout still docked);
|
|
1577
|
+
* - into the grid, when no panel is docked there;
|
|
1578
|
+
* - otherwise floating, or into the first group for a type that can't float.
|
|
1579
|
+
*
|
|
1580
|
+
* Panels out at the same time come back, in any order, to the layout they left. The window
|
|
1581
|
+
* closes. Closing the window, or its "Return to desktop" button, does the same. `ok` is false
|
|
1582
|
+
* when the panel wasn't in a window.
|
|
1583
|
+
*/
|
|
1584
|
+
returnPanel(id: string): {
|
|
1585
|
+
ok: boolean;
|
|
1586
|
+
};
|
|
1320
1587
|
/** Returns `true` if a panel with this ID is currently open. */
|
|
1321
1588
|
isOpen(id: string): boolean;
|
|
1322
1589
|
/** Returns the IDs of all currently open panels. */
|
|
@@ -1669,7 +1936,7 @@ type PanelState = PanelInfo['state'];
|
|
|
1669
1936
|
*
|
|
1670
1937
|
* **Identity.** `id` and the five functions (`close`, `minimize`, `setDirty`, `setTitle`,
|
|
1671
1938
|
* `setIcon`) never change identity for the panel's lifetime. The handle object itself changes
|
|
1672
|
-
* when `containerType`, `isActive`, `isMinimized` or `
|
|
1939
|
+
* when `containerType`, `isActive`, `isMinimized`, `isFloating` or `isPoppedOut` does. So don't list the handle
|
|
1673
1940
|
* in a dependency array: depend on the function you call, or on the values you write.
|
|
1674
1941
|
*/
|
|
1675
1942
|
interface PanelHandle {
|
|
@@ -1681,8 +1948,13 @@ interface PanelHandle {
|
|
|
1681
1948
|
isActive: boolean;
|
|
1682
1949
|
/** A workspace panel that is minimized to the taskbar. */
|
|
1683
1950
|
isMinimized: boolean;
|
|
1684
|
-
/** A workspace panel shown as a floating window. */
|
|
1951
|
+
/** A workspace panel shown as a floating window. True too while it is in its own browser window. */
|
|
1685
1952
|
isFloating: boolean;
|
|
1953
|
+
/**
|
|
1954
|
+
* A workspace panel shown in its own browser window (`workspace.popOutPanel`, 7.12.0). Its
|
|
1955
|
+
* window and document are {@link usePanelWindow}'s.
|
|
1956
|
+
*/
|
|
1957
|
+
isPoppedOut: boolean;
|
|
1686
1958
|
/** Asks the container to close, honouring close guards and the dirty flag. */
|
|
1687
1959
|
close: (options?: CloseOptions) => void;
|
|
1688
1960
|
/** Minimizes a workspace panel. No effect in a modal or drawer. */
|
|
@@ -1822,6 +2094,42 @@ type RddContextMenuProps = ContextMenuProps & {
|
|
|
1822
2094
|
*/
|
|
1823
2095
|
declare const RddContextMenu: React$1.ForwardRefExoticComponent<RddContextMenuProps & React$1.RefAttributes<ContextMenuHandle>>;
|
|
1824
2096
|
|
|
2097
|
+
/**
|
|
2098
|
+
* @file panelWindow.tsx
|
|
2099
|
+
* @description The window a panel is in (7.12.0, S4): the main one, or its pop-out's. Panel code
|
|
2100
|
+
* reads it with `usePanelWindow()`; the app's `popoutWrapper` gets it as props, so a CSS-in-JS
|
|
2101
|
+
* cache can follow the panel into the pop-out's document.
|
|
2102
|
+
*/
|
|
2103
|
+
|
|
2104
|
+
/** The window and document a panel is shown in. See {@link usePanelWindow}. (7.12.0) */
|
|
2105
|
+
interface PanelWindow {
|
|
2106
|
+
window: Window;
|
|
2107
|
+
document: Document;
|
|
2108
|
+
}
|
|
2109
|
+
/** The props of `<DockableDesktopProvider popoutWrapper>`. (7.12.0) */
|
|
2110
|
+
interface PopoutWrapperProps extends PanelWindow {
|
|
2111
|
+
children: ReactNode;
|
|
2112
|
+
}
|
|
2113
|
+
/**
|
|
2114
|
+
* The window and document the panel is shown in (7.12.0): the pop-out's while the panel is in its
|
|
2115
|
+
* own window, the main ones otherwise (and outside a workspace panel, or with `popOut` off). It
|
|
2116
|
+
* changes when the panel pops out and when it returns, so code that listens on the window, uses
|
|
2117
|
+
* its `requestAnimationFrame`, `devicePixelRatio` or `matchMedia`, or creates elements, can follow.
|
|
2118
|
+
*
|
|
2119
|
+
* @example
|
|
2120
|
+
* ```tsx
|
|
2121
|
+
* function Chart() {
|
|
2122
|
+
* const { window: win } = usePanelWindow();
|
|
2123
|
+
* useEffect(() => {
|
|
2124
|
+
* const onResize = () => redraw(win.devicePixelRatio);
|
|
2125
|
+
* win.addEventListener('resize', onResize);
|
|
2126
|
+
* return () => win.removeEventListener('resize', onResize);
|
|
2127
|
+
* }, [win]);
|
|
2128
|
+
* }
|
|
2129
|
+
* ```
|
|
2130
|
+
*/
|
|
2131
|
+
declare function usePanelWindow(): PanelWindow;
|
|
2132
|
+
|
|
1825
2133
|
/** Props for `<DockableDesktopProvider>`. */
|
|
1826
2134
|
interface DockableDesktopProviderProps {
|
|
1827
2135
|
children: React$1.ReactNode;
|
|
@@ -1855,6 +2163,43 @@ interface DockableDesktopProviderProps {
|
|
|
1855
2163
|
zIndexBase?: number;
|
|
1856
2164
|
/** Context menu implementation. Defaults to the built-in menu. */
|
|
1857
2165
|
contextMenuAdapter?: ContextMenuAdapter;
|
|
2166
|
+
/**
|
|
2167
|
+
* The page a pop-out window opens (7.12.0): a same-origin page of the app, such as
|
|
2168
|
+
* `/popout.html`, with an empty `<body>`. The library waits for it to load, then moves the panel
|
|
2169
|
+
* in. Without it, the window opens blank. A page that can't be read (another origin, or a redirect
|
|
2170
|
+
* off this one) or doesn't load within 10 s sends the panel back. Only used with
|
|
2171
|
+
* `createWorkspace({ popOut: true })`. Set it when a third-party embed refuses a blank window: a
|
|
2172
|
+
* YouTube player, for one, shows error 153 there.
|
|
2173
|
+
*/
|
|
2174
|
+
popoutUrl?: string;
|
|
2175
|
+
/**
|
|
2176
|
+
* A component around every panel's content, given the window and document the panel is in (7.12.0):
|
|
2177
|
+
* the main ones, then the pop-out's while it is in its own window. For CSS-in-JS: a cache per
|
|
2178
|
+
* document, so the panel's styles are inserted where it is shown (a pop-out doesn't get rules
|
|
2179
|
+
* inserted with `insertRule` from the page). Rendered for every panel, for its whole life, while
|
|
2180
|
+
* the workspace has `popOut: true` (none otherwise), so nothing remounts when a panel moves. Pass
|
|
2181
|
+
* a stable component (defined outside a render), not an inline function. In a pop-out it is also
|
|
2182
|
+
* rendered around the window's frame (the icon and title you give the panel), a context menu and
|
|
2183
|
+
* the toasts shown there, with that window: keep one cache per document, not per wrapper.
|
|
2184
|
+
*
|
|
2185
|
+
* @example
|
|
2186
|
+
* ```tsx
|
|
2187
|
+
* import createCache from '@emotion/cache';
|
|
2188
|
+
* import { CacheProvider } from '@emotion/react';
|
|
2189
|
+
*
|
|
2190
|
+
* const caches = new WeakMap<Document, ReturnType<typeof createCache>>();
|
|
2191
|
+
* const cacheFor = (doc: Document) => {
|
|
2192
|
+
* let c = caches.get(doc);
|
|
2193
|
+
* if (!c) { c = createCache({ key: 'app', container: doc.head }); caches.set(doc, c); }
|
|
2194
|
+
* return c;
|
|
2195
|
+
* };
|
|
2196
|
+
* const PopoutWrapper = ({ document, children }: PopoutWrapperProps) =>
|
|
2197
|
+
* <CacheProvider value={cacheFor(document)}>{children}</CacheProvider>;
|
|
2198
|
+
*
|
|
2199
|
+
* <DockableDesktopProvider workspace={workspace} popoutWrapper={PopoutWrapper}>…</DockableDesktopProvider>
|
|
2200
|
+
* ```
|
|
2201
|
+
*/
|
|
2202
|
+
popoutWrapper?: React$1.ComponentType<PopoutWrapperProps>;
|
|
1858
2203
|
}
|
|
1859
2204
|
/**
|
|
1860
2205
|
* The one provider. Place it above everything from this library: `<RddDesktop>`, `<RddSidebar>`,
|
|
@@ -2600,6 +2945,13 @@ interface ManagedWidget {
|
|
|
2600
2945
|
* an iframe reloads as before. As `preserveEmbeds` on a panel type's `defaultOptions`. @default false
|
|
2601
2946
|
*/
|
|
2602
2947
|
preserveEmbeds?: boolean;
|
|
2948
|
+
/**
|
|
2949
|
+
* It may move into its own browser window (7.12.0): `useFloatingWidgets().popOut(id)`, or an item
|
|
2950
|
+
* the app offers in its {@link ManagedWidget.titleMenu} (`w.popOut()`). Needs a workspace created
|
|
2951
|
+
* with `popOut: true`. Changeable while open: call `open()` again; a window already open stays
|
|
2952
|
+
* open. @default false
|
|
2953
|
+
*/
|
|
2954
|
+
canPopOut?: boolean;
|
|
2603
2955
|
}
|
|
2604
2956
|
/**
|
|
2605
2957
|
* Where a managed widget is, as plain JSON (7.11.0): from `useFloatingWidgets().placement(id)`,
|
|
@@ -2620,6 +2972,12 @@ interface WidgetMenuContext {
|
|
|
2620
2972
|
canDock: boolean;
|
|
2621
2973
|
/** Its config's `canFloat`. */
|
|
2622
2974
|
canFloat: boolean;
|
|
2975
|
+
/** Its config's `canPopOut`, on a workspace with `popOut` (7.12.0). */
|
|
2976
|
+
canPopOut: boolean;
|
|
2977
|
+
/** It is in its own browser window now (`location` is then `'floating'`). (7.12.0) */
|
|
2978
|
+
isPoppedOut: boolean;
|
|
2979
|
+
/** `useFloatingWidgets().popOut()` for this widget (7.12.0). */
|
|
2980
|
+
popOut(): PopOutResult;
|
|
2623
2981
|
/** `useFloatingWidgets().move()` for this widget. */
|
|
2624
2982
|
move(to: WidgetTarget): MoveResult;
|
|
2625
2983
|
/** Closes the widget, wherever it is. */
|
|
@@ -2949,6 +3307,21 @@ interface FloatingWidgetsApi {
|
|
|
2949
3307
|
* widgets.open('table', { ...config, placement: saved ?? undefined }); // later: it opens where it was
|
|
2950
3308
|
*/
|
|
2951
3309
|
placement(id: string): WidgetPlacement | null;
|
|
3310
|
+
/**
|
|
3311
|
+
* 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.
|
|
3317
|
+
*
|
|
3318
|
+
* Back: `move()` to any place returns it first, as one move; closing the window, or its "Back into
|
|
3319
|
+
* the panel" button, puts it back into its panel where it was (D17). `onWillMove` / `onMoved` run
|
|
3320
|
+
* around each, and the `panel:popped-out` / `panel:returned` events are sent for its panel.
|
|
3321
|
+
* @example
|
|
3322
|
+
* <button onClick={() => widgets.popOut('table')}>Open in new window</button>
|
|
3323
|
+
*/
|
|
3324
|
+
popOut(id: string): PopOutResult;
|
|
2952
3325
|
}
|
|
2953
3326
|
/**
|
|
2954
3327
|
* Imperative hook for spawning N named floating windows at runtime from data or event handlers.
|
|
@@ -2990,6 +3363,11 @@ interface WidgetHandle {
|
|
|
2990
3363
|
panelId: string | null;
|
|
2991
3364
|
/** Where it is shown now. A component that calls `useWidget()` re-renders when it changes. */
|
|
2992
3365
|
location: WidgetLocation;
|
|
3366
|
+
/**
|
|
3367
|
+
* It is in its own browser window (`useFloatingWidgets().popOut`, 7.12.0); `location` is then
|
|
3368
|
+
* `'floating'`. Its content's `usePanelWindow()` gives that window.
|
|
3369
|
+
*/
|
|
3370
|
+
isPoppedOut: boolean;
|
|
2993
3371
|
/**
|
|
2994
3372
|
* Called just before the widget's content element moves to another container: into or out of
|
|
2995
3373
|
* its panel, between docked, tabbed and floating, minimised or restored. Save what a move would
|
|
@@ -3197,4 +3575,4 @@ declare function isElementRtl(el: HTMLElement | null): boolean;
|
|
|
3197
3575
|
*/
|
|
3198
3576
|
declare function isComputedRtl(el: Element | null | undefined): boolean;
|
|
3199
3577
|
|
|
3200
|
-
export { type AlertOptions, type BuiltInEvents, type ButtonVariant, type CloseOptions, type ConfirmOptions, type ContainerType, type ContextMenuAdapter, type ContextMenuCheckbox, type ContextMenuHandle, type ContextMenuItem, type ContextMenuLabel, type ContextMenuSeparator, type ContextMenuSimpleItem, type ContextMenuSubMenu, type DirtyStateOptions, DockableDesktopProvider, type DockableDesktopProviderProps, type DropPosition, type DropTarget, type FloatAnchor, type FloatingWidgetsApi, type FloatingWindow, type HostClasses, type LayoutGridNode, type LayoutLeafNode, type LayoutNode, type ManagedWidget, type MenuItemAction, type MessageDescriptor, type MessageFormatter, type MessageKey, type ModalOptions, type ModalsApi, type MoveResult, type OpenPanelOptions, type OverlayId, type OverlayInstance, type OverlayState, type PanelContribution, type PanelDefinition, type PanelDrop, type PanelDropTarget, type PanelEvents, type PanelFloatPlacement, type PanelHandle, type PanelInfo, type PanelMap, type PanelOwner, type PanelPropsOf, PanelRegistry, type PanelRegistryEntry, type PanelSidebarSection, type PanelState, type PanelTitle, type PanelTitleDescriptor, type PointerDragConfig, AlertForm as RddAlert, type RddAlertProps, ConfirmationForm as RddConfirm, type RddConfirmProps, RddContextMenu, type RddContextMenuProps, WindowManager as RddDesktop, type RddDesktopProps, PanelFloatingWindow as RddFloatingWidget, type RddFloatingWidgetProps, ModalStackRenderer as RddModals, PanelOverlayRoot as RddPanelOverlay, type RddPanelOverlayProps, PanelToolbar as RddPanelToolbar, type RddPanelToolbarProps, SecondarySidebar as RddSecondarySidebar, type RddSecondarySidebarProps, RddSidePanels, type RddSidePanelsProps, Sidebar as RddSidebar, type RddSidebarProps, ToastContainer as RddToasts, type RddToastsProps, Toolbar as RddToolbar, ToolbarButton as RddToolbarButton, type RddToolbarButtonProps, ToolbarCenter as RddToolbarCenter, ToolbarItem as RddToolbarItem, type RddToolbarProps, ToolbarSearchInput as RddToolbarSearch, type RddToolbarSearchProps, ToolbarSeparator as RddToolbarSeparator, ToolbarSpacer as RddToolbarSpacer, ToolbarToggle as RddToolbarToggle, type RddToolbarToggleProps, type ResizeConstraints, type ResizeDir, type ResizeRect, type ResolvedToastOptions, type SearchResult, type SerializedLayout, type ShowContextMenuOptions, type SidePanelOptions, type SidePanelsApi, type SidebarActionButton, type SidebarContextValue as SidebarContext, type SidebarCustomEntry, type SidebarHandle, type SidebarHeaderAction, type SidebarRailEntry, type SidebarTab, type SidebarTabContextValue as SidebarTabContext, type SplitDirection, type SplitOrientation, type Stretch, type TabContentProps, type TaskbarVisibility, type ToastAdapter, type ToastFunction, type ToastOptions, type ToastPosition, type ToastPromiseMessages, type ToastType, type ToolbarActionItem, type ToolbarContextValue, type ToolbarGroupEntry, type ToolbarGroupItem, type ToolbarGroupSubItem, type ToolbarHandle, type ToolbarItem$1 as ToolbarItem, type ToolbarPosition, type ToolbarRadioItem, type ToolbarSeparator$1 as ToolbarSeparator, type ToolbarToggleItem, type ToolbarVariant, type TypedWorkspace, type WidgetHandle, type WidgetLocation, type WidgetMenuContext, type WidgetPlacement, type WidgetTarget, type Workspace, type WorkspaceActions, type WorkspaceConfig, type WorkspaceState, computeResizedRect, createWorkspace, defaultPredefinedMessages as defaultMessages, definePanels, formatLabel, isComputedRtl, isElementRtl, isSerializable, sidebarSectionToTab as sectionToTab, startPointerDrag, toast, useActivePanelContribution as useActiveContribution, useBeforeClose, useColorScheme, useShowContextMenu as useContextMenu, usePanelFloatingWindowManager as useFloatingWidgets, useFormatMessage, useStyleClasses as useHostClasses, useMergedSidebarTabs, useMergedToolbarItems, usePredefinedMessages as useMessages, useModals, usePanel, usePanelContextMenu, usePanelContribution, usePanelEvents, usePanelSize, useSaveState, useSidePanels, useSidebar, useSidebarTab, useToolbar, useWidget, useWorkspace, useWindowManagerState as useWorkspaceState };
|
|
3578
|
+
export { type AlertOptions, type BuiltInEvents, type ButtonVariant, type CloseOptions, type ConfirmOptions, type ContainerType, type ContextMenuAdapter, type ContextMenuCheckbox, type ContextMenuHandle, type ContextMenuItem, type ContextMenuLabel, type ContextMenuSeparator, type ContextMenuSimpleItem, type ContextMenuSubMenu, type DirtyStateOptions, DockableDesktopProvider, type DockableDesktopProviderProps, type DropPosition, type DropTarget, type FloatAnchor, type FloatingWidgetsApi, type FloatingWindow, type HostClasses, type LayoutGridNode, type LayoutLeafNode, type LayoutNode, type ManagedWidget, type MenuItemAction, type MessageDescriptor, type MessageFormatter, type MessageKey, type ModalOptions, type ModalsApi, type MoveResult, type OpenPanelOptions, type OverlayId, type OverlayInstance, type OverlayState, type PanelContribution, type PanelDefinition, type PanelDrop, type PanelDropTarget, type PanelEvents, type PanelFloatPlacement, type PanelHandle, type PanelInfo, type PanelMap, type PanelOwner, type PanelPropsOf, PanelRegistry, type PanelRegistryEntry, type PanelSidebarSection, type PanelState, type PanelTitle, type PanelTitleDescriptor, type PanelWindow, type PointerDragConfig, type PopOutResult, type PopoutWrapperProps, AlertForm as RddAlert, type RddAlertProps, ConfirmationForm as RddConfirm, type RddConfirmProps, RddContextMenu, type RddContextMenuProps, WindowManager as RddDesktop, type RddDesktopProps, PanelFloatingWindow as RddFloatingWidget, type RddFloatingWidgetProps, ModalStackRenderer as RddModals, PanelOverlayRoot as RddPanelOverlay, type RddPanelOverlayProps, PanelToolbar as RddPanelToolbar, type RddPanelToolbarProps, SecondarySidebar as RddSecondarySidebar, type RddSecondarySidebarProps, RddSidePanels, type RddSidePanelsProps, Sidebar as RddSidebar, type RddSidebarProps, ToastContainer as RddToasts, type RddToastsProps, Toolbar as RddToolbar, ToolbarButton as RddToolbarButton, type RddToolbarButtonProps, ToolbarCenter as RddToolbarCenter, ToolbarItem as RddToolbarItem, type RddToolbarProps, ToolbarSearchInput as RddToolbarSearch, type RddToolbarSearchProps, ToolbarSeparator as RddToolbarSeparator, ToolbarSpacer as RddToolbarSpacer, ToolbarToggle as RddToolbarToggle, type RddToolbarToggleProps, type ResizeConstraints, type ResizeDir, type ResizeRect, type ResolvedToastOptions, type SearchResult, type SerializedLayout, type ShowContextMenuOptions, type SidePanelOptions, type SidePanelsApi, type SidebarActionButton, type SidebarContextValue as SidebarContext, type SidebarCustomEntry, type SidebarHandle, type SidebarHeaderAction, type SidebarRailEntry, type SidebarTab, type SidebarTabContextValue as SidebarTabContext, type SplitDirection, type SplitOrientation, type Stretch, type TabContentProps, type TaskbarVisibility, type ToastAdapter, type ToastFunction, type ToastOptions, type ToastPosition, type ToastPromiseMessages, type ToastType, type ToolbarActionItem, type ToolbarContextValue, type ToolbarGroupEntry, type ToolbarGroupItem, type ToolbarGroupSubItem, type ToolbarHandle, type ToolbarItem$1 as ToolbarItem, type ToolbarPosition, type ToolbarRadioItem, type ToolbarSeparator$1 as ToolbarSeparator, type ToolbarToggleItem, type ToolbarVariant, type TypedWorkspace, type WidgetHandle, type WidgetLocation, type WidgetMenuContext, type WidgetPlacement, type WidgetTarget, type Workspace, type WorkspaceActions, type WorkspaceConfig, type WorkspaceState, computeResizedRect, createWorkspace, defaultPredefinedMessages as defaultMessages, definePanels, formatLabel, isComputedRtl, isElementRtl, isSerializable, sidebarSectionToTab as sectionToTab, startPointerDrag, toast, useActivePanelContribution as useActiveContribution, useBeforeClose, useColorScheme, useShowContextMenu as useContextMenu, usePanelFloatingWindowManager as useFloatingWidgets, useFormatMessage, useStyleClasses as useHostClasses, useMergedSidebarTabs, useMergedToolbarItems, usePredefinedMessages as useMessages, useModals, usePanel, usePanelContextMenu, usePanelContribution, usePanelEvents, usePanelSize, usePanelWindow, useSaveState, useSidePanels, useSidebar, useSidebarTab, useToolbar, useWidget, useWorkspace, useWindowManagerState as useWorkspaceState };
|