@gtkx/components 2.0.0-beta.10 → 2.0.0-beta.12

package/src/tab-collection.tsx

@@ -0,0 +1,124 @@
+import * as Adw from "@gtkx/gi/adw";
+import { AdwTabPage } from "@gtkx/jsx/adw";
+import { createRoot, flushSync, type Root } from "@gtkx/react";
+import { getClassType } from "@gtkx/runtime";
+import { createRef, type RefObject, useEffect } from "react";
+import type { TabCollection, TabCollectionOptions } from "./types.js";
+
+type TabHandle<T> = {
+    root: Root;
+    page: RefObject<Adw.TabPage | null>;
+    getPage: () => Adw.TabPage | null;
+    parent: Adw.TabPage | undefined;
+    item: T;
+};
+
+type ManagedTabProps<T> = {
+    handle: TabHandle<T>;
+    item: T;
+    options: TabCollectionOptions<T>;
+    forget: (handle: TabHandle<T>) => void;
+};
+
+const ManagedTab = <T,>({ handle, item, options, forget }: ManagedTabProps<T>) => {
+    const { page: pageRef, parent, getPage } = handle;
+    useEffect(() => () => forget(handle), [handle, forget]);
+    return <AdwTabPage {...options.pageProps(item, getPage)} ref={pageRef} parent={parent} />;
+};
+
+const ownerOf = (page: Adw.TabPage): Adw.TabView => {
+    const owner = page.getChild().getAncestor(getClassType(Adw.TabView));
+    if (!(owner instanceof Adw.TabView)) throw new Error("The tab has no native view");
+    return owner;
+};
+
+/**
+ * Creates a collection of JSX pages whose React state survives native transfers and source-window
+ * closure. Call append from an event handler because it commits synchronously. Page content lives in
+ * independent roots: pass context-dependent values through the item or wrap the content in providers.
+ */
+const createTabCollection = <T,>(options: TabCollectionOptions<T>): TabCollection<T> => {
+    const handles = new Set<TabHandle<T>>();
+    const forget = (handle: TabHandle<T>) => {
+        handles.delete(handle);
+    };
+    const find = (page: Adw.TabPage) => [...handles].find((handle) => handle.page.current === page);
+    const render = (handle: TabHandle<T>) => {
+        handle.root.render(<ManagedTab handle={handle} item={handle.item} options={options} forget={forget} />);
+    };
+    const remove = (handle: TabHandle<T>) => {
+        handles.delete(handle);
+        handle.root.unmount();
+    };
+
+    return {
+        append: (view, item, appendOptions = {}) => {
+            if (appendOptions.parent && ownerOf(appendOptions.parent) !== view) {
+                throw new RangeError("The parent page belongs to another tab view");
+            }
+            const pageRef = createRef<Adw.TabPage>();
+            const handle: TabHandle<T> = {
+                root: createRoot(view),
+                page: pageRef,
+                getPage: () => pageRef.current,
+                parent: appendOptions.parent,
+                item,
+            };
+            handles.add(handle);
+            try {
+                flushSync(() => render(handle));
+            } catch (error) {
+                remove(handle);
+                throw error;
+            }
+            const page = handle.page.current;
+            if (page === null) {
+                remove(handle);
+                throw new Error("The tab page did not render");
+            }
+            if (appendOptions.parent === undefined) {
+                view.reorderPage(page, page.getPinned() ? view.getNPinnedPages() - 1 : view.getNPages() - 1);
+            }
+            if (appendOptions.select !== false) view.setSelectedPage(page);
+            return page;
+        },
+        get: (page) => find(page)?.item,
+        update: (page, item) => {
+            const handle = find(page);
+            if (handle === undefined) throw new Error("The tab is not managed by this collection");
+            handle.item = item;
+            render(handle);
+        },
+        remove: (page) => {
+            const handle = find(page);
+            if (handle) remove(handle);
+        },
+        removeView: (view) => {
+            const pages = Array.from({ length: view.getNPages() }, (_, index) => view.getNthPage(index));
+            for (const page of pages) {
+                const handle = find(page);
+                if (handle) remove(handle);
+            }
+        },
+        transfer: (page, target, position) => {
+            if (find(page) === undefined) throw new Error("The tab is not managed by this collection");
+            const source = ownerOf(page);
+            const minimum = page.getPinned() ? 0 : target.getNPinnedPages();
+            const maximum = page.getPinned() ? target.getNPinnedPages() : target.getNPages();
+            const index = position ?? maximum;
+            if (!Number.isInteger(index) || index < minimum || index > maximum) {
+                throw new RangeError("The position is outside the tab's pinned or unpinned group");
+            }
+            if (source === target) {
+                target.reorderPage(page, Math.min(index, maximum - 1));
+            } else {
+                source.transferPage(page, target, index);
+            }
+        },
+        dispose: () => {
+            for (const handle of [...handles]) remove(handle);
+        },
+    };
+};
+
+export { createTabCollection };

package/src/toast.tsx

@@ -1,7 +1,7 @@
 import type { ReactNode, RefObject } from "react";
 import * as Adw from "@gtkx/gi/adw";
 import { createContext, useContext, useMemo } from "react";
-import type { ToastController, ToastOptions, ToastOverlayController, ToastProviderProps } from "./types.js";
+import type { ToastController, ToastOptions, ToastProviderProps } from "./types.js";
 
 type OverlayRef = RefObject<Adw.ToastOverlay | null>;
 
@@ -11,7 +11,7 @@ const useOverlayRef = (): OverlayRef => {
     const overlayRef = useContext(ToastContext);
 
     if (overlayRef === null) {
-        throw new Error("useToast and useToastOverlay must be used within a ToastProvider");
+        throw new Error("useToast must be used within a ToastProvider");
     }
 
     return overlayRef;
@@ -36,7 +36,7 @@ const buildToast = (options: ToastOptions): Adw.Toast => {
     return toast;
 };
 
-/** Shares an Adw.ToastOverlay reference with the toast hooks in every descendant. */
+/** Shares an Adw.ToastOverlay reference with useToast in every descendant. */
 function ToastProvider(props: ToastProviderProps): ReactNode {
     return <ToastContext.Provider value={props.overlayRef}>{props.children}</ToastContext.Provider>;
 }
@@ -53,20 +53,6 @@ function useToast(): ToastController {
 
                 return toast;
             },
-            dismiss: (toast: Adw.Toast) => {
-                toast.dismiss();
-            },
-        }),
-        [overlayRef],
-    );
-}
-
-/** Returns a {@link ToastOverlayController} for the nearest provider's overlay as a whole. */
-function useToastOverlay(): ToastOverlayController {
-    const overlayRef = useOverlayRef();
-
-    return useMemo<ToastOverlayController>(
-        () => ({
             dismissAll: () => {
                 overlayRef.current?.dismissAll();
             },
@@ -75,4 +61,4 @@ function useToastOverlay(): ToastOverlayController {
     );
 }
 
-export { ToastProvider, useToast, useToastOverlay };
+export { ToastProvider, useToast };

package/src/types.ts

@@ -1,6 +1,7 @@
 import type * as Adw from "@gtkx/gi/adw";
+import type * as GObject from "@gtkx/gi/gobject";
 import type * as Gtk from "@gtkx/gi/gtk";
-import type { AdwComboRowProps, AdwToastProps } from "@gtkx/jsx/adw";
+import type { AdwComboRowProps, AdwTabPageProps, AdwToastProps } from "@gtkx/jsx/adw";
 import type {
     GtkColumnViewColumnProps,
     GtkColumnViewProps,
@@ -8,6 +9,7 @@ import type {
     GtkGridViewProps,
     GtkListViewProps,
 } from "@gtkx/jsx/gtk";
+import type { Primitive } from "@gtkx/utils";
 import type { ReactNode, RefObject } from "react";
 
 /**
@@ -15,11 +17,11 @@ import type { ReactNode, RefObject } from "react";
  * arbitrary value. Nested items form a tree.
  */
 type ListItem<T = unknown> = {
-    /** Stable identifier used to track the item across updates and selection, naming every row that carries it. */
+    /** Stable identifier, unique across the collection, used to preserve identity across updates and selection. */
     id: string;
     /** Payload handed to the cell renderer as `ListItemRenderArgs.item`. */
     value: T;
-    /** Child items nested under this one, which turn a plain item list into a tree, read only as rows are drawn. */
+    /** Child items in an acyclic tree, read only as rows are drawn. */
     children?: ListItem<T>[] | undefined;
     /** Hides the tree expander arrow even when the item has children, through `hide-expander`. */
     shouldHideExpander?: boolean | undefined;
@@ -31,7 +33,7 @@ type ListItem<T = unknown> = {
 
 /** A group of items rendered under a shared section header. */
 type ListSection<S = unknown, T = unknown> = {
-    /** Stable identifier used to track the section across updates. */
+    /** Stable identifier, unique among sections, used to track the section across updates. */
     id: string;
     /** Payload handed to the section header renderer as `ListSectionRenderArgs.section`. */
     value: S;
@@ -90,6 +92,10 @@ type ItemSizeProps = {
     estimatedItemWidth?: number | undefined;
 };
 
+type ListItemFactoryProps<T extends GObject.Object> = ItemSizeProps & {
+    renderItem: ListItemRenderer<T>;
+};
+
 /** The flat-collection hint shared by {@link ListView} and {@link ColumnView}. */
 type FlatnessProps = {
     /**
@@ -104,8 +110,7 @@ type FlatnessProps = {
 type SelectionProps = {
     /**
      * Ids of the items to keep selected; omitting it keeps nothing selected, and `onSelectionChanged` is how a
-     * user's selection is adopted into it. An id repeated in several branches of a tree names every matching row,
-     * and a single-selection view takes the first of them.
+     * user's selection is adopted into it.
      */
     selectedIds?: string[] | null | undefined;
     /** Called with one id per selected row whenever the selection changes, and once on mount. */
@@ -130,9 +135,7 @@ type ExpanderDescriptions = {
 type ExpansionProps = {
     /**
      * Ids of the items to keep expanded; omitting it keeps every row collapsed, and `onExpandedChange` is how a
-     * user's expansion is adopted into it. An id repeated in several branches names every matching row, so all of
-     * them expand together. An item whose children lead back to itself expands one level at a time, since a row
-     * repeating an item already expanded above it stays collapsed.
+     * user's expansion is adopted into it.
      */
     expandedIds?: string[] | null | undefined;
     /** Called with one id per expanded row, in visible order, whenever expansion changes. */
@@ -156,12 +159,18 @@ type SortProps = {
 };
 
 /** The data a collection view renders, either as a plain item list or grouped into sections. */
-type SourceProps<T, S> = {
-    /** Items to render, nesting through `ListItem.children` for a tree; ignored once `sections` is given. */
-    items?: ListItem<T>[] | undefined;
-    /** Items grouped under section headers, rendered in place of `items`. */
-    sections?: ListSection<S, T>[] | undefined;
-};
+type SourceProps<T, S> =
+    | ({
+          /** Items to render, nesting through `ListItem.children` for a tree. */
+          items?: ListItem<T>[] | undefined;
+      } & Partial<Record<"sections", undefined>> &
+          Partial<Record<"renderHeader", null | undefined>>)
+    | ({
+          /** Items grouped under section headers. */
+          sections: ListSection<S, T>[];
+          /** Renders the header shown above each section. */
+          renderHeader?: ListSectionRenderer<S> | null | undefined;
+      } & Partial<Record<"items", undefined>>);
 
 /** One column of a {@link ColumnView}, pairing Gtk.ColumnViewColumn props with a cell renderer. */
 type ColumnViewColumn<T = unknown> = Omit<GtkColumnViewColumnProps, "factory" | "sorter" | "id" | "title"> & {
@@ -186,36 +195,29 @@ type ColumnViewOwnProps<T, S> = SelectionProps &
     Omit<ItemSizeProps, "estimatedItemWidth"> & {
         /** Columns to render, in order; each carries its own cell renderer. */
         columns: ColumnViewColumn<T>[];
-        /** Renders the header shown above each section. */
-        renderHeader?: ListSectionRenderer<S> | null | undefined;
         /** Resolves the props of the row carrying one item's cells, such as its screen-reader label. */
         rowProps?: ListRowPropsResolver<T> | null | undefined;
     };
 
 /**
- * Props for {@link ColumnView}. Combines the underlying Gtk.ColumnView props with
- * declarative collection props: flat items or grouped sections, controlled selection
- * and expansion, sorting (sortColumn, sortOrder, onSortChanged), an optional section
- * header renderer, per-row props, and the columns to render.
+ * Native `Gtk.ColumnView` props with declarative columns and collections, controlled selection, expansion, and sorting.
  */
 type ColumnViewProps<T = unknown, S = unknown> = Omit<
     GtkColumnViewProps,
-    "columns" | "model" | "headerFactory" | "rowFactory" | keyof ColumnViewOwnProps<T, S>
+    "children" | "columns" | "model" | "headerFactory" | "rowFactory" | keyof ColumnViewOwnProps<T, S>
 > &
-ColumnViewOwnProps<T, S>;
+    ColumnViewOwnProps<T, S>;
 
 /** The declarative collection props {@link DropDown} and `ComboRow` add on top of their widget's own. */
 type DropDownOwnProps<T, S> = SourceProps<T, S> & {
     /** Id of the currently selected item, making the selection controlled. */
-    selectedId?: string | null | undefined;
-    /** Called with the id of the item that became selected. */
-    onSelectionChanged?: ((id: string) => void) | null | undefined;
-    /** Renders the collapsed display, and the popup rows too unless `renderListItem` is given. */
+    selectedId?: string | undefined;
+    /** Called with the selected id, or `null` when the model becomes empty. */
+    onSelectionChanged?: ((id: string | null) => void) | null | undefined;
+    /** Renders the collapsed display and, unless overridden, the popup rows. Required for non-primitive values. */
     renderItem?: ListItemRenderer<T> | null | undefined;
     /** Renderer for items in the open popup list, falling back to renderItem when omitted. */
     renderListItem?: ListItemRenderer<T> | null | undefined;
-    /** Renderer for section headers in the popup list. */
-    renderHeader?: ListSectionRenderer<S> | null | undefined;
 };
 
 /** A drop-down-shaped widget's props with its model and factories swapped for the declarative collection props. */
@@ -223,12 +225,11 @@ type DropDownWidgetProps<Widget, T, S> = Omit<
     Widget,
     "model" | "factory" | "listFactory" | "headerFactory" | keyof DropDownOwnProps<T, S>
 > &
-DropDownOwnProps<T, S>;
+    DropDownOwnProps<T, S> &
+    (SourceProps<T & Primitive, S> | Record<"renderItem", ListItemRenderer<T>>);
 
 /**
- * Props for {@link DropDown}. Combines the underlying Gtk.DropDown props with the declarative
- * collection props: flat items or grouped sections, controlled single selection, and renderers
- * for the collapsed display, popup rows, and popup section headers.
+ * Native `Gtk.DropDown` props with declarative collections, controlled selection, and display/popup renderers.
  */
 type DropDownProps<T = unknown, S = unknown> = DropDownWidgetProps<GtkDropDownProps, T, S>;
 
@@ -242,9 +243,7 @@ type GridViewOwnProps<T> = ItemSizeProps &
     };
 
 /**
- * Props for {@link GridView}. Combines the underlying Gtk.GridView props with
- * declarative collection props: items, a per-cell renderItem, controlled selection,
- * and estimated item sizing.
+ * Native `Gtk.GridView` props with declarative cells, controlled selection, and estimated sizing.
  */
 type GridViewProps<T = unknown> = Omit<GtkGridViewProps, "model" | "factory" | keyof GridViewOwnProps<T>> &
     GridViewOwnProps<T>;
@@ -257,26 +256,20 @@ type ListViewOwnProps<T, S> = ItemSizeProps &
     FlatnessProps & {
         /** Renders the contents of one row. */
         renderItem: ListItemRenderer<T>;
-        /** Renders the header shown above each section. */
-        renderHeader?: ListSectionRenderer<S> | null | undefined;
     };
 
 /**
- * Props for {@link ListView}. Combines the underlying Gtk.ListView props with
- * declarative collection props: flat items or grouped sections, a per-row renderItem,
- * an optional section header renderer, controlled selection and expansion, and
- * estimated item sizing.
+ * Native `Gtk.ListView` props with declarative rows and sections, controlled selection and expansion,
+ * and estimated sizing.
  */
 type ListViewProps<T = unknown, S = unknown> = Omit<
     GtkListViewProps,
     "model" | "factory" | "headerFactory" | keyof ListViewOwnProps<T, S>
 > &
-ListViewOwnProps<T, S>;
+    ListViewOwnProps<T, S>;
 
 /**
- * Props for {@link ComboRow}. Combines the underlying Adw.ComboRow props with the declarative
- * collection props: flat items or grouped sections, controlled single selection, and renderers
- * for the row display, popup rows, and popup section headers.
+ * Native `Adw.ComboRow` props with declarative collections, controlled selection, and display/popup renderers.
  */
 type ComboRowProps<T = unknown, S = unknown> = DropDownWidgetProps<AdwComboRowProps, T, S>;
 /**
@@ -285,16 +278,10 @@ type ComboRowProps<T = unknown, S = unknown> = DropDownWidgetProps<AdwComboRowPr
  */
 type ToastOptions = Adw.ToastConstructorProps & Pick<AdwToastProps, "onButtonClicked" | "onDismissed">;
 
-/** Imperative controls for individual toasts, returned by {@link useToast}. */
+/** Imperative controls for toasts, returned by {@link useToast}. */
 type ToastController = {
     /** Builds a toast, shows it through the overlay, and returns it. */
     show: (options?: ToastOptions) => Adw.Toast;
-    /** Dismisses a single toast, typically one returned by `ToastController.show`. */
-    dismiss: (toast: Adw.Toast) => void;
-};
-
-/** Imperative controls for the overlay as a whole, returned by {@link useToastOverlay}. */
-type ToastOverlayController = {
     /** Dismisses the shown toast and every queued one. */
     dismissAll: () => void;
 };
@@ -303,10 +290,46 @@ type ToastOverlayController = {
 type ToastProviderProps = {
     /** Ref also given to the `AdwToastOverlay` the toasts appear over. */
     overlayRef: RefObject<Adw.ToastOverlay | null>;
-    /** Subtree whose `useToast` and `useToastOverlay` calls target that overlay. */
+    /** Subtree whose `useToast` calls target that overlay. */
     children?: ReactNode | undefined;
 };
 
+/** Describes the JSX page rendered for each value in a {@link TabCollection}. */
+type TabCollectionOptions<T> = {
+    /** Native page props and JSX content. Call getPage in event handlers to access the mounted page. The collection owns its ref and parent relationship. */
+    pageProps: (item: T, getPage: () => Adw.TabPage | null) => Omit<AdwTabPageProps, "ref" | "parent">;
+};
+
+/** Options for adding a page to a {@link TabCollection}. */
+type TabAppendOptions = {
+    /** Inserts a related page after this parent and its descendants, using native tab ancestry. */
+    parent?: Adw.TabPage | undefined;
+    /** Selects the new page by default. */
+    select?: boolean | undefined;
+};
+
+/**
+ * Owns independent JSX tab roots across native view transfers. Its lifetime can span several windows.
+ * Remove a page after accepting its native close request, remove a view's pages before destroying that
+ * view, and dispose the collection when its owner is finished.
+ */
+type TabCollection<T> = {
+    /** Renders synchronously and returns the native page, including from an overview's create-tab handler. */
+    append: (view: Adw.TabView, item: T, options?: TabAppendOptions) => Adw.TabPage;
+    /** Returns a managed page's current value, or undefined for an unmanaged page. */
+    get: (page: Adw.TabPage) => T | undefined;
+    /** Updates the value and rerenders the existing JSX root, preserving component state and native identity. */
+    update: (page: Adw.TabPage, item: T) => void;
+    /** Unmounts a managed page from its current native owner; already removed pages are ignored. */
+    remove: (page: Adw.TabPage) => void;
+    /** Unmounts this collection's pages currently belonging to the given view, including transferred pages. */
+    removeView: (view: Adw.TabView) => void;
+    /** Moves a managed page to another view, appending within its pinned or unpinned group by default. */
+    transfer: (page: Adw.TabPage, target: Adw.TabView, position?: number) => void;
+    /** Unmounts every managed page. The collection may subsequently be reused. */
+    dispose: () => void;
+};
+
 export {
     type SelectionProps,
     type ExpanderDescriptions,
@@ -319,6 +342,7 @@ export {
     type ListRowProps,
     type ListSectionRenderArgs,
     type ListItemRenderer,
+    type ListItemFactoryProps,
     type ListRowPropsResolver,
     type ListSectionRenderer,
     type ColumnViewColumn,
@@ -329,6 +353,8 @@ export {
     type ComboRowProps,
     type ToastOptions,
     type ToastController,
-    type ToastOverlayController,
     type ToastProviderProps,
+    type TabAppendOptions,
+    type TabCollection,
+    type TabCollectionOptions,
 };