@gtkx/components 0.21.0 → 1.0.0-rc.1

package/src/hooks/use-list-model.ts

@@ -2,107 +2,131 @@ import type * as Gio from "@gtkx/gi/gio";
 import type * as GObject from "@gtkx/gi/gobject";
 import type * as Gtk from "@gtkx/gi/gtk";
 import { useLayoutEffect, useMemo, useRef } from "react";
-import type { ListItem } from "../types.js";
-import {
-    createControlledResolver,
-    createModelResolver,
-    createSectionHeaderResolver,
-    type ItemResolver,
-    type RowValue,
-} from "../utils/item-resolver.js";
-import { detectStructure, type ListStructure, structuralSignature } from "../utils/list-item-flatten.js";
+import type { ItemNode, SectionNode } from "../types.js";
 import {
     createFlatModel,
     createSectionModel,
     createTreeModel,
     resizeFlatModel,
     retagRows,
-} from "../utils/position-only-model.js";
-
-export interface ControlledListMode<T, S> {
-    items: ListItem<T, S>[] | undefined;
-    autoexpand?: boolean | undefined;
-    model?: never;
-}
+} from "../utils/item-models.js";
+import {
+    createItemResolver,
+    createSectionHeaderResolver,
+    createTreeResolver,
+    type ItemResolver,
+    type RowValue,
+} from "../utils/item-resolver.js";
+import { detectStructure, type ListStructure, structuralSignature } from "../utils/list-item-flatten.js";
 
-export interface UncontrolledListMode {
-    model: Gio.ListModel;
-    items?: never;
-    autoexpand?: never;
-}
+type ListModelInput<T, S> = {
+    items: ItemNode<T>[] | undefined;
+    sections?: SectionNode<S, T>[] | undefined;
+};
 
-export interface ListModelResult<T, S> {
+type ListModelResult<T, S> = {
     model: Gio.ListModel;
+    treeModel: Gtk.TreeListModel | null;
     resolver: ItemResolver<T, S>;
     headerResolver: ItemResolver<T, S>;
-}
+    rowValues: WeakMap<GObject.Object, RowValue<T>>;
+};
+
+type ListModelStructure = "sections" | ListStructure;
 
-interface ControlledState<T, S> {
+type ListModelState<T, S> = {
     model: Gio.ListModel;
+    treeModel: Gtk.TreeListModel | null;
     flatModel: Gtk.StringList | undefined;
-    items: ListItem<T, S>[] | undefined;
-    structure: ListStructure;
-    autoexpand: boolean;
+    items: ItemNode<T>[] | undefined;
+    sections: SectionNode<S, T>[] | undefined;
+    structure: ListModelStructure;
     signature: string;
-    rowValues: WeakMap<GObject.Object, RowValue<T, S>>;
+    rowValues: WeakMap<GObject.Object, RowValue<T>>;
     placeholdersById: Map<string, GObject.Object>;
-}
+};
+
+const sectionRows = <T, S>(sections: SectionNode<S, T>[] | undefined): ItemNode<T>[] => {
+    if (sections === undefined) return [];
+    const rows: ItemNode<T>[] = [];
+    for (const section of sections) rows.push(...section.data);
+    return rows;
+};
+
+const sectionSignature = <T, S>(sections: SectionNode<S, T>[] | undefined): string => {
+    if (sections === undefined) return "";
+    const parts: string[] = [];
+    for (const section of sections) {
+        parts.push(`${section.id}{${structuralSignature(section.data)}}`);
+    }
+    return parts.join(",");
+};
+
+const signatureOf = <T, S>(
+    structure: ListModelStructure,
+    items: ItemNode<T>[] | undefined,
+    sections: SectionNode<S, T>[] | undefined,
+): string => {
+    if (structure === "sections") return `sections|${sectionSignature(sections)}`;
+    return structure === "flat" ? "" : `${structure}|${structuralSignature(items)}`;
+};
 
-const controlledSignature = <T, S>(
-    structure: ListStructure,
-    autoexpand: boolean,
-    items: ListItem<T, S>[] | undefined,
-): string => (structure === "flat" ? "" : `${structure}|${autoexpand ? 1 : 0}|${structuralSignature(items)}`);
+type ListModelInternalInput<T, S> = {
+    items: ItemNode<T>[] | undefined;
+    sections: SectionNode<S, T>[] | undefined;
+    structure: ListModelStructure;
+    signature: string;
+};
 
-const buildControlledState = <T, S>(
-    items: ListItem<T, S>[] | undefined,
-    autoexpand: boolean,
-    structure: ListStructure,
-    signature: string,
-): ControlledState<T, S> => {
-    const rowValues = new WeakMap<GObject.Object, RowValue<T, S>>();
+const buildState = <T, S>(input: ListModelInternalInput<T, S>): ListModelState<T, S> => {
+    const { items, sections, structure, signature } = input;
+    const rowValues = new WeakMap<GObject.Object, RowValue<T>>();
     const placeholdersById = new Map<string, GObject.Object>();
     let model: Gio.ListModel;
+    let treeModel: Gtk.TreeListModel | null = null;
     let flatModel: Gtk.StringList | undefined;
     if (structure === "sections") {
-        model = createSectionModel(items ?? []);
+        model = createSectionModel(sections ?? []);
     } else if (structure === "tree") {
-        model = createTreeModel(items ?? [], autoexpand, rowValues, placeholdersById);
+        treeModel = createTreeModel(items ?? [], rowValues, placeholdersById);
+        model = treeModel;
     } else {
         flatModel = createFlatModel(items?.length ?? 0);
         model = flatModel;
     }
-    return { model, flatModel, items, structure, autoexpand, signature, rowValues, placeholdersById };
+    return { model, treeModel, flatModel, items, sections, structure, signature, rowValues, placeholdersById };
 };
 
-const resolveControlledState = <T, S>(
-    prev: ControlledState<T, S> | null,
-    items: ListItem<T, S>[] | undefined,
-    autoexpand: boolean,
-): ControlledState<T, S> => {
-    if (prev !== null && prev.items === items && prev.autoexpand === autoexpand) return prev;
-    const structure = detectStructure(items);
-    const signature = controlledSignature(structure, autoexpand, items);
+const resolveState = <T, S>(
+    prev: ListModelState<T, S> | null,
+    items: ItemNode<T>[] | undefined,
+    sections: SectionNode<S, T>[] | undefined,
+): ListModelState<T, S> => {
+    if (prev !== null && prev.items === items && prev.sections === sections) {
+        return prev;
+    }
+    const structure: ListModelStructure = sections !== undefined ? "sections" : detectStructure(items);
+    const signature = signatureOf(structure, items, sections);
+    const input: ListModelInternalInput<T, S> = { items, sections, structure, signature };
     if (prev === null || prev.structure !== structure) {
-        return buildControlledState(items, autoexpand, structure, signature);
+        return buildState(input);
     }
     if (structure !== "flat" && prev.signature !== signature) {
-        return buildControlledState(items, autoexpand, structure, signature);
+        return buildState(input);
     }
-    if (structure !== "flat") {
+    if (structure === "tree") {
         retagRows(items ?? [], prev.rowValues, prev.placeholdersById);
     }
     prev.items = items;
-    prev.autoexpand = autoexpand;
+    prev.sections = sections;
     prev.signature = signature;
     return prev;
 };
 
-const useControlledModel = <T, S>(mode: ControlledListMode<T, S>): ListModelResult<T, S> => {
-    const { items } = mode;
-    const autoexpand = mode.autoexpand ?? false;
-    const stateRef = useRef<ControlledState<T, S> | null>(null);
-    const state = resolveControlledState(stateRef.current, items, autoexpand);
+export const useListModel = <T, S>(input: ListModelInput<T, S>): ListModelResult<T, S> => {
+    const { items, sections } = input;
+    const stateRef = useRef<ListModelState<T, S> | null>(null);
+    const state = resolveState(stateRef.current, items, sections);
     stateRef.current = state;
     const { structure, flatModel } = state;
 
@@ -112,34 +136,26 @@ const useControlledModel = <T, S>(mode: ControlledListMode<T, S>): ListModelResu
         }
     }, [flatModel, items]);
 
-    const resolver = useMemo(
-        () => createControlledResolver(items, structure !== "flat" && autoexpand, state.rowValues),
-        [items, structure, autoexpand, state.rowValues],
-    );
+    const resolver = useMemo(() => {
+        if (structure === "sections") {
+            return createItemResolver<T, S>(sectionRows(sections), true, state.rowValues);
+        }
+        if (structure === "tree" && state.treeModel !== null) {
+            return createTreeResolver<T, S>(items, state.rowValues, state.treeModel);
+        }
+        return createItemResolver<T, S>(items, false, state.rowValues);
+    }, [items, sections, structure, state.rowValues, state.treeModel]);
 
     const headerResolver = useMemo(
-        () => createSectionHeaderResolver(structure === "sections" ? items : undefined),
-        [items, structure],
+        () => createSectionHeaderResolver<T, S>(structure === "sections" ? sections : undefined),
+        [sections, structure],
     );
 
-    return { model: state.model, resolver, headerResolver };
+    return {
+        model: state.model,
+        treeModel: state.treeModel,
+        resolver,
+        headerResolver,
+        rowValues: state.rowValues,
+    };
 };
-
-const useUncontrolledModel = <T, S>(mode: UncontrolledListMode): ListModelResult<T, S> => {
-    const { model } = mode;
-    const resolver = useMemo<ItemResolver<T, S>>(() => createModelResolver(model), [model]);
-    const headerResolver = useMemo<ItemResolver<T, S>>(() => createSectionHeaderResolver<T, S>(undefined), []);
-    return { model, resolver, headerResolver };
-};
-
-export const useListModel = <T, S>(mode: ControlledListMode<T, S> | UncontrolledListMode): ListModelResult<T, S> => {
-    const controlled = useControlledModel<T, S>(
-        mode.model === undefined ? { items: mode.items, autoexpand: mode.autoexpand } : { items: [] },
-    );
-    const uncontrolled = useUncontrolledModel<T, S>(
-        mode.model === undefined ? { model: EMPTY_MODEL } : { model: mode.model },
-    );
-    return mode.model === undefined ? controlled : uncontrolled;
-};
-
-const EMPTY_MODEL: Gio.ListModel = createFlatModel(0);

package/src/hooks/use-placed-child.ts

@@ -0,0 +1,79 @@
+import type * as GObject from "@gtkx/gi/gobject";
+import { createPortal, rootElement } from "@gtkx/react";
+import { useMergeRefs } from "@gtkx/react/internal";
+import {
+    type Context,
+    createContext,
+    type ReactNode,
+    type Ref,
+    type RefCallback,
+    type RefObject,
+    useCallback,
+    useContext,
+    useLayoutEffect,
+    useRef,
+} from "react";
+
+export type ParentContext<T> = {
+    Context: Context<RefObject<T | null> | null>;
+    useParentRef: () => RefObject<T | null>;
+};
+
+export const createParentContext = <T>(orphanMessage: string): ParentContext<T> => {
+    const context = createContext<RefObject<T | null> | null>(null);
+    return {
+        Context: context,
+        useParentRef: (): RefObject<T | null> => {
+            const ref = useContext(context);
+            if (!ref) throw new Error(orphanMessage);
+            return ref;
+        },
+    };
+};
+
+export type PlacedChildRender<T> = (ref: RefCallback<T>) => ReactNode;
+
+export type PlacedChildOptions<T extends GObject.Object, P> = {
+    render: PlacedChildRender<T>;
+    ref?: Ref<T | null> | undefined;
+    placement: P;
+    samePlacement: (a: P, b: P) => boolean;
+    place: (object: T, placement: P, previous: P | undefined) => void;
+    release: (object: T) => void;
+};
+
+export const usePlacedChild = <T extends GObject.Object, P>(options: PlacedChildOptions<T, P>): ReactNode => {
+    const { render, ref, placement, samePlacement, place, release } = options;
+    const objectRef = useRef<T | null>(null);
+    const appliedRef = useRef<{ object: T; placement: P } | null>(null);
+    const captureObject = useCallback<RefCallback<T>>((object) => {
+        objectRef.current = object;
+    }, []);
+    const setObjectRef = useMergeRefs<T>(ref, captureObject);
+
+    useLayoutEffect(() => {
+        const object = objectRef.current;
+        const applied = appliedRef.current;
+        if (applied !== null && applied.object !== object) {
+            release(applied.object);
+            appliedRef.current = null;
+        }
+        if (object === null) return;
+        const current = appliedRef.current;
+        if (current === null || !samePlacement(current.placement, placement)) {
+            place(object, placement, current?.placement);
+            appliedRef.current = { object, placement };
+        }
+    });
+
+    useLayoutEffect(
+        () => () => {
+            const applied = appliedRef.current;
+            if (applied !== null) release(applied.object);
+            appliedRef.current = null;
+        },
+        [],
+    );
+
+    return createPortal(render(setObjectRef), rootElement);
+};

package/src/hooks/use-selection-model.ts

@@ -1,16 +1,17 @@
 import type * as Gio from "@gtkx/gi/gio";
 import * as Gtk from "@gtkx/gi/gtk";
 import { useSignal } from "@gtkx/react";
+import { isSameArray } from "@gtkx/utils";
 import { useLayoutEffect, useRef } from "react";
 import type { ItemResolver } from "../utils/item-resolver.js";
 
-export interface SelectionModelOptions<T, S> {
+type SelectionModelOptions<T, S> = {
     base: Gio.ListModel;
     selectionMode: Gtk.SelectionMode | null | undefined;
-    selected: string[] | null | undefined;
+    selectedIds: string[] | null | undefined;
     onSelectionChanged: ((ids: string[]) => void) | null | undefined;
     resolver: ItemResolver<T, S>;
-}
+};
 
 type WrappingSelectionModel = (Gtk.SingleSelection | Gtk.MultiSelection | Gtk.NoSelection) & Gtk.SelectionModel;
 
@@ -36,7 +37,7 @@ const applySelectedPositions = (model: Gtk.SelectionModel, positions: number[]):
             return;
         }
         const requested = bitsetOf(positions);
-        const changed = model.getSelection();
+        const changed = model.getSelection().copy();
         changed.difference(requested);
         if (changed.isEmpty()) return;
         model.setSelection(requested, changed);
@@ -66,22 +67,14 @@ const idsToPositions = <T, S>(ids: string[] | null | undefined, resolver: ItemRe
     if (ids === undefined || ids === null) return [];
     const positions: number[] = [];
     for (const id of ids) {
-        const position = resolver.positionOf(id);
+        const position = resolver.positionOfId(id);
         if (position >= 0) positions.push(position);
     }
     return positions;
 };
 
-const sameIds = (a: string[], b: string[]): boolean => {
-    if (a.length !== b.length) return false;
-    for (let index = 0; index < a.length; index++) {
-        if (a[index] !== b[index]) return false;
-    }
-    return true;
-};
-
 export const useSelectionModel = <T, S>(options: SelectionModelOptions<T, S>): Gtk.SelectionModel => {
-    const { base, selectionMode, selected, onSelectionChanged, resolver } = options;
+    const { base, selectionMode, selectedIds, onSelectionChanged, resolver } = options;
     const mode = selectionMode ?? Gtk.SelectionMode.SINGLE;
 
     const modelRef = useRef<WrappingSelectionModel | null>(null);
@@ -102,7 +95,7 @@ export const useSelectionModel = <T, S>(options: SelectionModelOptions<T, S>): G
         const callback = onChangedRef.current;
         if (!callback) return;
         const ids = readSelectedIds(model, resolverRef.current);
-        if (lastReportedRef.current !== null && sameIds(lastReportedRef.current, ids)) return;
+        if (lastReportedRef.current !== null && isSameArray(lastReportedRef.current, ids)) return;
         lastReportedRef.current = ids;
         callback(ids);
     };
@@ -111,11 +104,11 @@ export const useSelectionModel = <T, S>(options: SelectionModelOptions<T, S>): G
 
     useLayoutEffect(() => {
         if (model.getModel() !== base) model.setModel(base);
-        if (selected !== undefined && selected !== null) {
-            applySelectedPositions(model, idsToPositions(selected, resolver));
+        if (selectedIds !== undefined && selectedIds !== null) {
+            applySelectedPositions(model, idsToPositions(selectedIds, resolver));
         }
         report();
-    }, [model, base, selected, resolver]);
+    }, [model, base, selectedIds, resolver]);
 
     return model;
 };

package/src/hooks/use-sort-handler.ts

@@ -1,15 +1,20 @@
 import * as Gtk from "@gtkx/gi/gtk";
-import { type GObjectTarget, resolveGobjectTarget } from "@gtkx/react/internal";
+import { type ObjectProp, resolveObjectProp } from "@gtkx/react/internal";
 import { useLayoutEffect, useRef } from "react";
-import type { ColumnRegistration } from "../contexts/column-view-context.js";
 
-export interface SortHandlerOptions {
-    columnView: GObjectTarget<Gtk.ColumnView>;
+export type ColumnRegistration = {
+    id: string;
+    column: Gtk.ColumnViewColumn;
+    sortable: boolean;
+};
+
+type SortHandlerOptions = {
+    columnView: ObjectProp<Gtk.ColumnView>;
     sortColumn: string | null | undefined;
     sortOrder: Gtk.SortType | null | undefined;
     onSortChanged: ((column: string | null, order: Gtk.SortType) => void) | null | undefined;
     columns: ColumnRegistration[];
-}
+};
 
 const neutralSorter = (): Gtk.CustomSorter => Gtk.CustomSorter.new(() => 0);
 
@@ -46,10 +51,10 @@ const primarySort = (sorter: Gtk.Sorter): { column: Gtk.ColumnViewColumn | null;
         ? { column: sorter.getPrimarySortColumn(), order: sorter.getPrimarySortOrder() }
         : { column: null, order: Gtk.SortType.ASCENDING };
 
-interface SorterSubscription {
+type SorterSubscription = {
     sorter: Gtk.Sorter | null;
     handler: ((change: Gtk.SorterChange) => void) | null;
-}
+};
 
 const disconnectSorter = (subscription: SorterSubscription): void => {
     if (subscription.sorter !== null && subscription.handler !== null) {
@@ -89,7 +94,7 @@ export const useSortHandler = (options: SortHandlerOptions): void => {
     };
 
     useLayoutEffect(() => {
-        const view = resolveGobjectTarget(columnView);
+        const view = resolveObjectProp(columnView);
         if (view === null) return;
         ensureColumnSorters(columns, activeId);
         suppressRef.current = true;

package/src/index.ts

@@ -1,31 +1,29 @@
-/**
- * Higher-level GTKX components: declarative, opinionated abstractions layered on
- * top of the generated `@gtkx/jsx` element bindings and the `@gtkx/react`
- * runtime. Each component pairs a GObject widget with a gtkx-authored prop
- * surface (item models, render callbacks, selection, sorting) and is exported
- * under an unprefixed name to distinguish it from the raw `Gtk*`/`Adw*`/`G*`
- * intrinsic element it builds upon.
- *
- * @packageDocumentation
- */
-
-export { ColumnView, type ColumnViewComponentProps } from "./column-view.js";
-export { ColumnViewColumn, type ColumnViewColumnComponentProps } from "./column-view-column.js";
+export {
+    type ColumnDef,
+    type ColumnDefDeclarativeProps,
+    ColumnView,
+    type ColumnViewDeclarativeProps,
+    type ColumnViewProps,
+    type ColumnViewSortProps,
+} from "./column-view.js";
 export { ConstraintLayout, type ConstraintLayoutProps } from "./constraint-layout.js";
-export { ComboRow, type ComboRowComponentProps, DropDown, type DropDownComponentProps } from "./drop-down.js";
-export { GridView, type GridViewComponentProps } from "./grid-view.js";
-export { ListView, type ListViewComponentProps } from "./list-view.js";
-export { Menu, type MenuProps } from "./menu.js";
+export type { ConstraintGuideProps, ConstraintProps, ConstraintVflProps } from "./constraint-layout-apply.js";
+export { DropDown, type DropDownDeclarativeProps, type DropDownItemRenderer, type DropDownProps } from "./drop-down.js";
+export { Fixed, type FixedChildProps, type FixedPlacementProps, type FixedProps } from "./fixed.js";
+export { Grid, type GridChildProps, type GridPlacement, type GridProps } from "./grid.js";
+export { GridView, type GridViewDeclarativeProps, type GridViewProps } from "./grid-view.js";
+export { ListView, type ListViewDeclarativeProps, type ListViewProps } from "./list-view.js";
+export { Menu, type MenuItemsProps, type MenuProps } from "./menu.js";
+export { Overlay, type OverlayChildProps, type OverlayPlacementProps, type OverlayProps } from "./overlay.js";
+export { SizeGroup, type SizeGroupChildProps, type SizeGroupProps } from "./size-group.js";
 export type {
-    ColumnViewColumnProps,
-    ColumnViewProps,
-    ConstraintGuideProps,
-    ConstraintProps,
-    ConstraintVflProps,
-    DropDownProps,
-    GridViewProps,
-    ListItem,
-    ListViewProps,
+    ChildProps,
+    CollectionItemSizeProps,
+    ControlledExpansionProps,
+    ControlledSelectionProps,
+    ItemNode,
     MenuEntry,
-    MenuItemsProps,
+    RenderItemProps,
+    SectionNode,
+    WidgetProps,
 } from "./types.js";