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

package/src/internal/cells.tsx

@@ -1,9 +1,10 @@
 import type * as GObject from "@gtkx/gi/gobject";
-import type { ReactElement, ReactNode } from "react";
+import type { ReactElement, ReactNode, RefObject } from "react";
 import * as Gtk from "@gtkx/gi/gtk";
 import { GtkBox, GtkSignalListItemFactory, GtkTreeExpander } from "@gtkx/jsx/gtk";
 import { createPortal, useProperty } from "@gtkx/react";
-import { Fragment, memo, useInsertionEffect, useLayoutEffect, useRef, useState, useSyncExternalStore } from "react";
+import { useLatestRef } from "@gtkx/react/internal";
+import { createRef, Fragment, memo, useLayoutEffect, useRef, useState, useSyncExternalStore } from "react";
 import type {
     ExpanderDescriptions,
     ListItem,
@@ -34,7 +35,7 @@ type CellHost = FactoryHost & {
 type CellEntry<H extends FactoryHost> = {
     key: string;
     host: H;
-    identity: ItemIdentityStore;
+    identity: RefObject<ItemIdentity | null>;
 };
 
 type FactoryHandlers = {
@@ -95,11 +96,6 @@ type CollectionState = {
     expandedIds: string[] | null | undefined;
 };
 
-type CollectionStateStore = {
-    read: () => CollectionState;
-    write: (state: CollectionState) => void;
-};
-
 type ItemIdentity = {
     itemKey: string;
     item: ListItem | undefined;
@@ -107,15 +103,10 @@ type ItemIdentity = {
     isExpanded: boolean;
 };
 
-type ItemIdentityStore = {
-    read: () => ItemIdentity | null;
-    write: (identity: ItemIdentity) => void;
-};
-
 type ItemCellProps = {
     entry: CellEntry<Gtk.ListItem>;
     render: ListItemRenderer<never>;
-    state: CollectionStateStore;
+    state: RefObject<CollectionState>;
     hasExpander: boolean;
     expanderDescriptions: ExpanderDescriptions | null | undefined;
 } & ItemIdentity;
@@ -132,7 +123,7 @@ type ItemPortalsProps = {
 type ItemRowProps = {
     entry: CellEntry<Gtk.ColumnViewRow>;
     rowProps: ListRowPropsResolver<never>;
-    state: CollectionStateStore;
+    state: RefObject<CollectionState>;
 } & ItemIdentity;
 
 type RowPortalsProps = {
@@ -231,7 +222,7 @@ function notifyRegistry<H extends FactoryHost>(state: CellRegistryState<H>): voi
 function createEntry<H extends FactoryHost>(state: CellRegistryState<H>, host: H): CellEntry<H> {
     state.serial += 1;
 
-    return { key: `gtkx-cell-${String(state.serial)}`, host, identity: createItemIdentityStore() };
+    return { key: `gtkx-cell-${String(state.serial)}`, host, identity: createRef<ItemIdentity>() };
 }
 
 function setupHost<H extends FactoryHost>(state: CellRegistryState<H>, host: H): void {
@@ -386,7 +377,7 @@ function slotFor(options: ItemSlotOptions): ItemSlot | null {
 
 function useItemSlot(
     entry: CellEntry<PositionedHost>,
-    state: CollectionStateStore,
+    state: RefObject<CollectionState>,
     identity: ItemIdentity,
 ): ItemSlot | null {
     const position = useProperty(entry.host, "position");
@@ -397,14 +388,14 @@ function useItemSlot(
         return identity.item === undefined
             ? null
             : {
-                    itemKey: identity.itemKey,
-                    item: identity.item,
-                    row,
-                    args: itemArgs(identity.item, position, row, identity.isExpanded),
-                };
+                  itemKey: identity.itemKey,
+                  item: identity.item,
+                  row,
+                  args: itemArgs(identity.item, position, row, identity.isExpanded),
+              };
     }
 
-    const { collection, expandedIds } = state.read();
+    const { collection, expandedIds } = state.current;
 
     return slotFor({ item, position, row, collection, expandedIds });
 }
@@ -435,7 +426,7 @@ function isSameItemIdentity(previous: ItemIdentity, next: ItemIdentity): boolean
 }
 
 function isSameItemCell(previous: ItemCellProps, next: ItemCellProps): boolean {
-    const identity = previous.entry.identity.read() ?? previous;
+    const identity = previous.entry.identity.current ?? previous;
 
     return (
         previous.entry === next.entry &&
@@ -447,22 +438,11 @@ function isSameItemCell(previous: ItemCellProps, next: ItemCellProps): boolean {
 }
 
 function isSameItemRow(previous: ItemRowProps, next: ItemRowProps): boolean {
-    const identity = previous.entry.identity.read() ?? previous;
+    const identity = previous.entry.identity.current ?? previous;
 
     return previous.entry === next.entry && previous.rowProps === next.rowProps && isSameItemIdentity(identity, next);
 }
 
-function createItemIdentityStore(): ItemIdentityStore {
-    let current: ItemIdentity | null = null;
-
-    return {
-        read: () => current,
-        write: (identity) => {
-            current = identity;
-        },
-    };
-}
-
 function createNativeItemKeyStore(): NativeItemKeyStore {
     const keys: WeakMap<GObject.Object, string> = new WeakMap();
     let serial = 0;
@@ -494,35 +474,12 @@ function renderedIdentity(entry: CellEntry<PositionedHost>, slot: ItemSlot | nul
 }
 
 function useRememberIdentity(entry: CellEntry<PositionedHost>, slot: ItemSlot | null): void {
+    const identityRef = entry.identity;
     useLayoutEffect(() => {
-        entry.identity.write(renderedIdentity(entry, slot));
+        identityRef.current = renderedIdentity(entry, slot);
     });
 }
 
-function createCollectionStateStore(initial: CollectionState): CollectionStateStore {
-    let current = initial;
-
-    return {
-        read: () => current,
-        write: (state) => {
-            current = state;
-        },
-    };
-}
-
-function useCollectionState(
-    collection: Collection,
-    expandedIds: string[] | null | undefined,
-): CollectionStateStore {
-    const [state] = useState(() => createCollectionStateStore({ collection, expandedIds }));
-
-    useInsertionEffect(() => {
-        state.write({ collection, expandedIds });
-    }, [state, collection, expandedIds]);
-
-    return state;
-}
-
 function expanderDescriptionFor(
     slot: ItemSlot,
     descriptions: ExpanderDescriptions | null | undefined,
@@ -544,21 +501,19 @@ function wrapExpander(
     const { item, row } = slot;
 
     const expander: ReactNode =
-        row === null
-            ? (
-                    content
-                )
-            : (
-                    <GtkTreeExpander
-                        listRow={row}
-                        hideExpander={item.shouldHideExpander ?? false}
-                        indentForDepth={item.shouldIndentForDepth ?? true}
-                        indentForIcon={item.shouldIndentForIcon ?? true}
-                        accessibleDescription={expanderDescriptionFor(slot, descriptions)}
-                    >
-                        {content}
-                    </GtkTreeExpander>
-                );
+        row === null ? (
+            content
+        ) : (
+            <GtkTreeExpander
+                listRow={row}
+                hideExpander={item.shouldHideExpander ?? false}
+                indentForDepth={item.shouldIndentForDepth ?? true}
+                indentForIcon={item.shouldIndentForIcon ?? true}
+                accessibleDescription={expanderDescriptionFor(slot, descriptions)}
+            >
+                {content}
+            </GtkTreeExpander>
+        );
 
     return expander;
 }
@@ -576,16 +531,13 @@ function itemBody(
     const renderItem = render as ListItemRenderer<unknown>;
     const content = renderItem(slot.args);
 
-    return (
-        <Fragment key={slot.itemKey}>{hasExpander ? wrapExpander(slot, content, descriptions) : content}</Fragment>
-    );
+    return <Fragment key={slot.itemKey}>{hasExpander ? wrapExpander(slot, content, descriptions) : content}</Fragment>;
 }
 
 function rowText(value: string | undefined): string | null {
     return value ?? null;
 }
 
-/* eslint-disable-next-line unicorn/consistent-boolean-name -- reads the flag off a row, paired with rowText */
 function rowFlag(value: boolean | undefined): boolean {
     return value ?? true;
 }
@@ -603,11 +555,7 @@ function rowPropsFor(slot: ItemSlot | null, rowProps: ListRowPropsResolver<never
     };
 }
 
-function applyRowProps(
-    host: Gtk.ColumnViewRow,
-    props: ResolvedRowProps,
-    previous: ResolvedRowProps | null,
-): void {
+function applyRowProps(host: Gtk.ColumnViewRow, props: ResolvedRowProps, previous: ResolvedRowProps | null): void {
     if (previous?.accessibleLabel !== props.accessibleLabel) {
         host.accessibleLabel = props.accessibleLabel;
     }
@@ -664,32 +612,26 @@ function HeaderCellImpl({ entry, render, collection }: HeaderCellProps): ReactNo
     return createPortal(headerBody(slotRefFor(item), render, collection), entry.host, entry.key);
 }
 
-function NativeItemCell<T extends GObject.Object>({
-    entry,
-    render,
-    keys,
-    size,
-}: NativeItemCellProps<T>): ReactNode {
+function NativeItemCell<T extends GObject.Object>({ entry, render, keys, size }: NativeItemCellProps<T>): ReactNode {
     const position = useProperty(entry.host, "position");
     const item = useProperty(entry.host, "item") ?? null;
     let body: ReactNode = null;
 
     if (item !== null && position !== undefined) {
         const content = render({ item: item as T, index: position });
-        const child = content == null || typeof content === "boolean"
-            ? <GtkBox widthRequest={size.width} heightRequest={size.height} />
-            : content;
+        const child =
+            content == null || typeof content === "boolean" ? (
+                <GtkBox widthRequest={size.width} heightRequest={size.height} />
+            ) : (
+                content
+            );
         body = <Fragment key={keys.keyFor(item)}>{child}</Fragment>;
     }
 
     return createPortal(body, entry.host, entry.key);
 }
 
-function headerBody(
-    ref: SlotRef | null,
-    render: ListSectionRenderer<never>,
-    collection: Collection,
-): ReactNode {
+function headerBody(ref: SlotRef | null, render: ListSectionRenderer<never>, collection: Collection): ReactNode {
     if (ref === null) {
         return null;
     }
@@ -719,7 +661,7 @@ const ItemPortals = ({
     expanderDescriptions,
 }: ItemPortalsProps): ReactNode => {
     const entries = usePortalEntries(registry);
-    const state = useCollectionState(collection, expandedIds);
+    const state = useLatestRef({ collection, expandedIds });
 
     return entries.map((entry) => (
         <ItemCell
@@ -736,7 +678,7 @@ const ItemPortals = ({
 
 const RowPortals = ({ registry, rowProps, collection, expandedIds }: RowPortalsProps): ReactNode => {
     const entries = usePortalEntries(registry);
-    const state = useCollectionState(collection, expandedIds);
+    const state = useLatestRef({ collection, expandedIds });
 
     return entries.map((entry) => (
         <ItemRow
@@ -799,11 +741,4 @@ const useRowProps = (
     };
 };
 
-export {
-    useItemCells,
-    useRowProps,
-    useSectionHeader,
-    ItemPortals,
-    NativeItemPortals,
-    type CellSize,
-};
+export { useItemCells, useRowProps, useSectionHeader, ItemPortals, NativeItemPortals, type CellSize };

package/src/internal/drop-down.tsx

@@ -59,11 +59,7 @@ const defaultRenderItem = ({ item }: ListItemRenderArgs<Primitive>): ReactNode =
     item == null ? null : <GtkLabel>{String(item)}</GtkLabel>;
 const faceRenderer = (props: DropDownBaseProps): ListItemRenderer<never> => props.renderItem ?? defaultRenderItem;
 
-const resolvePosition = (
-    widget: SelectableWidget,
-    collection: Collection,
-    selectedId: string | undefined,
-): number => {
+const resolvePosition = (widget: SelectableWidget, collection: Collection, selectedId: string | undefined): number => {
     if (selectedId === undefined) {
         return widget.getSelected();
     }

package/src/internal/tree-expansion.ts

@@ -92,12 +92,4 @@ function adoptIndex(expansion: TreeExpansion, index: CollectionIndex): void {
     expansion.order = null;
 }
 
-export {
-    adoptIndex,
-    adoptOrder,
-    createTreeExpansion,
-    markExpanded,
-    orderFor,
-    pruneSlots,
-    type TreeExpansion,
-};
+export { adoptIndex, adoptOrder, createTreeExpansion, markExpanded, orderFor, pruneSlots, type TreeExpansion };

package/src/internal/tree-order.ts

@@ -133,12 +133,4 @@ function findIds(index: CollectionIndex, slots: SlotMap, positions: Set<number>)
     return found;
 }
 
-export {
-    expandedPathsFor,
-    findIds,
-    findRows,
-    walkVisible,
-    type MatchedRows,
-    type VisibleOrder,
-    type WalkOptions,
-};
+export { expandedPathsFor, findIds, findRows, walkVisible, type MatchedRows, type VisibleOrder, type WalkOptions };

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/types.ts

@@ -1,7 +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,
@@ -159,15 +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. */
-    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>>);
+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"> & {
@@ -203,7 +206,7 @@ type ColumnViewProps<T = unknown, S = unknown> = Omit<
     GtkColumnViewProps,
     "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> & {
@@ -222,8 +225,8 @@ type DropDownWidgetProps<Widget, T, S> = Omit<
     Widget,
     "model" | "factory" | "listFactory" | "headerFactory" | keyof DropDownOwnProps<T, S>
 > &
-DropDownOwnProps<T, S> &
-(SourceProps<T & Primitive, S> | Record<"renderItem", ListItemRenderer<T>>);
+    DropDownOwnProps<T, S> &
+    (SourceProps<T & Primitive, S> | Record<"renderItem", ListItemRenderer<T>>);
 
 /**
  * Native `Gtk.DropDown` props with declarative collections, controlled selection, and display/popup renderers.
@@ -263,7 +266,7 @@ type ListViewProps<T = unknown, S = unknown> = Omit<
     GtkListViewProps,
     "model" | "factory" | "headerFactory" | keyof ListViewOwnProps<T, S>
 > &
-ListViewOwnProps<T, S>;
+    ListViewOwnProps<T, S>;
 
 /**
  * Native `Adw.ComboRow` props with declarative collections, controlled selection, and display/popup renderers.
@@ -291,6 +294,42 @@ type ToastProviderProps = {
     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,
@@ -315,4 +354,7 @@ export {
     type ToastOptions,
     type ToastController,
     type ToastProviderProps,
+    type TabAppendOptions,
+    type TabCollection,
+    type TabCollectionOptions,
 };