some more docs

Author: shakyShane

special-pages/pages/new-tab/app/tabs/TabsProvider.js

@@ -1,15 +1,29 @@
 import { h, createContext } from 'preact';
 import { useContext, useEffect } from 'preact/hooks';
-import { TabsService } from './tabs.service';
 import { CustomizerThemesContext } from '../customizer/CustomizerProvider.js';
 import { signal, useComputed, useSignal } from '@preact/signals';
+import { TabsService } from './tabs.service';
+
+/**
+ * @template T
+ * @typedef {import('@preact/signals').ReadonlySignal<T>} ReadonlySignal<T>
+ */
 
-const TabsStateContext = createContext(signal(/** @type {import('../../types/new-tab').Tabs} */ (TabsService.DEFAULT)));
+/**
+ * @typedef {import("preact").ComponentChild} ComponentChild
+ * @typedef {import('../../types/new-tab').Tabs} Tabs
+ */
+
+const TabsStateContext = createContext(signal(/** @type {Tabs} */ (TabsService.DEFAULT)));
 
 /**
+ * Global state provider for tab information.
+ *
+ * This exposes a signal to the Tabs object. use the hook below to access the individual fields.
+ *
  * @param {object} props
- * @param {import("preact").ComponentChild} props.children
- * @param {import('./tabs.service').TabsService} props.service
+ * @param {ComponentChild} props.children
+ * @param {TabsService} props.service
  */
 export function TabsProvider({ children, service }) {
     const tabs = useSignal(service.snapshot());
@@ -21,6 +35,19 @@ export function TabsProvider({ children, service }) {
     return <TabsStateContext.Provider value={tabs}>{children}</TabsStateContext.Provider>;
 }
 
+/**
+ * Exposes 2 signals - one for the current tab ID and one for the list of tabIds.
+ *
+ * In a component, if you want to trigger a re-render based on the current tab, you can
+ * access the .value field directly.
+ *
+ * ```js
+ * const { current } = useTabState();
+ * return <MyComponent key={current.value} />
+ * ```
+ *
+ * @returns {{current: ReadonlySignal<string>, all: ReadonlySignal<string[]>}}
+ */
 export function useTabState() {
     const tabs = useContext(TabsStateContext);
     const current = useComputed(() => tabs.value.tabId);