TabGroupState.sys.mjs (5540B)
1 /* This Source Code Form is subject to the terms of the Mozilla Public 2 * License, v. 2.0. If a copy of the MPL was not distributed with this file, 3 * You can obtain one at http://mozilla.org/MPL/2.0/. */ 4 5 /** 6 * @typedef {object} TabGroupStateData 7 * State of a tab group inside of an open window. 8 * @property {string} id 9 * Unique ID of the tab group. 10 * @property {string} name 11 * User-defined name of the tab group. 12 * @property {"blue"|"purple"|"cyan"|"orange"|"yellow"|"pink"|"green"|"gray"|"red"} color 13 * User-selected color name for the tab group's label/icons. 14 * @property {boolean} collapsed 15 * Whether the tab group is collapsed or expanded in the tab strip. 16 */ 17 18 /** 19 * @typedef {TabGroupStateData} ClosedTabGroupStateData 20 * State of a tab group that was explicitly closed by the user. 21 * @property {number} closedAt 22 * Timestamp from `Date.now()`. 23 * @property {string} sourceWindowId 24 * Window that the tab group was in before it was closed. 25 * @property {ClosedTabStateData[]} tabs 26 * Copy of all tab data for the tabs that were in this tab group 27 * at the time it was closed. 28 */ 29 30 /** 31 * @typedef {TabGroupStateData} SavedTabGroupStateData 32 * State of a tab group that was explicitly saved and closed by the user 33 * or implicitly saved on behalf of the user when the user explicitly closed 34 * a window. 35 * @property {true} saved 36 * Indicates that the tab group was saved explicitly by the user or 37 * automatically by the browser. 38 * @property {number} closedAt 39 * Timestamp from `Date.now()`. 40 * @property {string} [sourceWindowId] 41 * Window that the tab group was in before a user explicitly saved it. Not set 42 * when the tab group is saved automatically due to a window closing. 43 * @property {number} [windowClosedId] 44 * `closedId` of the closed window if this tab group was saved automatically 45 * due to a window closing. Not set when a user explicitly saves a tab group. 46 * @property {ClosedTabStateData[]} tabs 47 * Copy of all tab data for the tabs that were in this tab group 48 * at the time it was saved. 49 */ 50 51 /** 52 * Module that contains tab group state collection methods. 53 */ 54 class _TabGroupState { 55 /** 56 * Collect data related to a single tab group, synchronously. 57 * 58 * @param {MozTabbrowserTabGroup} tabGroup 59 * Tab group browser element 60 * @returns {TabGroupStateData} 61 * Serialized tab group data 62 */ 63 collect(tabGroup) { 64 return { 65 id: tabGroup.id, 66 name: tabGroup.label, 67 color: tabGroup.color, 68 collapsed: tabGroup.collapsed, 69 saveOnWindowClose: tabGroup.saveOnWindowClose, 70 }; 71 } 72 73 /** 74 * Create initial state for a tab group that is about to close inside of an 75 * open window. 76 * 77 * The caller is responsible for hydrating closed tabs data into `tabs` 78 * using the `TabState` class. 79 * 80 * @param {MozTabbrowserTabGroup} tabGroup 81 * @param {string} sourceWindowId 82 * `window.__SSi` window ID of the open window where the tab group is closing. 83 * @returns {ClosedTabGroupStateData} 84 */ 85 closed(tabGroup, sourceWindowId) { 86 let closedData = this.collect(tabGroup); 87 closedData.closedAt = Date.now(); 88 closedData.sourceWindowId = sourceWindowId; 89 closedData.tabs = []; 90 return closedData; 91 } 92 93 /** 94 * Create initial state for a tab group that is about to be explicitly saved 95 * by the user inside of an open window. 96 * 97 * The caller is responsible for hydrating closed tabs data into `tabs` 98 * using the `TabState` class. 99 * 100 * @param {MozTabbrowserTabGroup} tabGroup 101 * @param {string} sourceWindowId 102 * `window.__SSi` window ID of the open window where the tab group 103 * is being saved. 104 * @returns {SavedTabGroupStateData} 105 */ 106 savedInOpenWindow(tabGroup, sourceWindowId) { 107 let savedData = this.closed(tabGroup, sourceWindowId); 108 savedData.saved = true; 109 return savedData; 110 } 111 112 /** 113 * Convert an existing tab group's state to saved tab group state. The input 114 * tab group state should come from a closing/closed window; if you need the 115 * state of a tab group that still exists in the browser, use `savedInOpenWindow` 116 * instead. This should be used when a tab group is being saved automatically 117 * due to a user closing a window containing some tab groups. 118 * 119 * The caller is responsible for hydrating closed tabs data into `tabs` 120 * using the `TabState` class. 121 * 122 * @param {TabGroupStateData} tabGroupState 123 * @param {number} windowClosedId 124 * `WindowStateData.closedId` of the closed window from which this tab group 125 * should be automatically saved. 126 */ 127 savedInClosedWindow(tabGroupState, windowClosedId) { 128 let savedData = tabGroupState; 129 savedData.saved = true; 130 savedData.closedAt = Date.now(); 131 savedData.windowClosedId = windowClosedId; 132 savedData.tabs = []; 133 return savedData; 134 } 135 136 /** 137 * In cases where we surface tab group metadata to external callers, we may want 138 * to provide an abbreviated set of metadata. This can help hide internal details 139 * from browser code or from extensions. Hiding those details can make the public 140 * session APIs simpler and more stable. 141 * 142 * @param {TabGroupStateData} tabGroupState 143 * @returns {TabGroupStateData} 144 */ 145 abbreviated(tabGroupState) { 146 let abbreviatedData = { 147 id: tabGroupState.id, 148 name: tabGroupState.name, 149 color: tabGroupState.color, 150 collapsed: tabGroupState.collapsed, 151 }; 152 return abbreviatedData; 153 } 154 } 155 156 export const TabGroupState = new _TabGroupState();