@gtkx/components 0.21.0 → 1.0.0-rc.2

package/src/collection-view.tsx

@@ -1,125 +0,0 @@
-import type * as Gio from "@gtkx/gi/gio";
-import type * as Gtk from "@gtkx/gi/gtk";
-import { useForwardedRef } from "@gtkx/react";
-import {
-    createElement,
-    type ElementType,
-    type ReactElement,
-    type ReactNode,
-    type Ref,
-    useCallback,
-    useRef,
-} from "react";
-import { useListModel } from "./hooks/use-list-model.js";
-import { useModelInstallation } from "./hooks/use-model-installation.js";
-import { type FactoryBinding, useRealizedSlots } from "./hooks/use-realized-slots.js";
-import { useSelectionModel } from "./hooks/use-selection-model.js";
-import { ListPortalHost } from "./list-portal-host.js";
-import type { SlotRenderer } from "./list-slot.js";
-import type { ListItem } from "./types.js";
-import type { ItemResolver } from "./utils/item-resolver.js";
-import type { RealizedSlotStore } from "./utils/realized-slot-store.js";
-
-export interface ModelBinding<W extends Gtk.Widget> {
-    install(widget: W, model: Gio.ListModel): void;
-}
-
-export interface CollectionViewProps<T, S, W extends Gtk.Widget> {
-    element: ElementType;
-    intrinsicProps: Record<string, unknown>;
-    ref: Ref<W | null> | undefined;
-    items: ListItem<T, S>[] | undefined;
-    model: Gio.ListModel | undefined;
-    renderItem: SlotRenderer<T, S>;
-    autoexpand: boolean | undefined;
-    renderHeader: ((value: S | undefined) => ReactNode) | undefined;
-    estimatedHeight: number | undefined;
-    estimatedWidth: number | undefined;
-    selected: string[] | null | undefined;
-    selectionMode: Gtk.SelectionMode | null | undefined;
-    onSelectionChanged: ((ids: string[]) => void) | null | undefined;
-    factoryBinding: FactoryBinding<W>;
-    headerFactoryBinding: FactoryBinding<W> | undefined;
-    modelBinding: ModelBinding<W>;
-    children?: ReactNode;
-}
-
-const headerRenderer =
-    <T, S>(renderHeader: ((value: S | undefined) => ReactNode) | undefined): SlotRenderer<T, S> =>
-    (value) =>
-        renderHeader ? renderHeader(value as S | undefined) : null;
-
-interface CollectionWiring<T, S, W extends Gtk.Widget> {
-    setRef: (value: W | null) => void;
-    resolver: ItemResolver<T, S>;
-    headerResolver: ItemResolver<T, S>;
-    itemStore: RealizedSlotStore;
-    headerStore: RealizedSlotStore;
-}
-
-const useCollectionWiring = <T, S, W extends Gtk.Widget>(
-    props: CollectionViewProps<T, S, W>,
-): CollectionWiring<T, S, W> => {
-    const widgetRef = useRef<W | null>(null);
-    const captureWidget = useCallback((value: W | null) => {
-        widgetRef.current = value;
-    }, []);
-    const [, setRef] = useForwardedRef<W>(props.ref, captureWidget);
-
-    const externalModel = props.model;
-    const listModel = useListModel<T, S>(
-        externalModel === undefined ? { items: props.items, autoexpand: props.autoexpand } : { model: externalModel },
-    );
-
-    const controlledSelection = useSelectionModel<T, S>({
-        base: listModel.model,
-        selectionMode: props.selectionMode,
-        selected: props.selected,
-        onSelectionChanged: props.onSelectionChanged,
-        resolver: listModel.resolver,
-    });
-    const installedModel: Gio.ListModel = externalModel === undefined ? controlledSelection : externalModel;
-
-    const items = useRealizedSlots<W>({
-        target: widgetRef,
-        binding: props.factoryBinding,
-        estimatedHeight: props.estimatedHeight,
-        estimatedWidth: props.estimatedWidth,
-    });
-    const headers = useRealizedSlots<W>({
-        target: props.headerFactoryBinding ? widgetRef : null,
-        binding: props.headerFactoryBinding ?? props.factoryBinding,
-        estimatedHeight: props.estimatedHeight,
-        estimatedWidth: props.estimatedWidth,
-    });
-
-    useModelInstallation(widgetRef, installedModel, (widget, model) => props.modelBinding.install(widget, model));
-
-    return {
-        setRef,
-        resolver: listModel.resolver,
-        headerResolver: listModel.headerResolver,
-        itemStore: items.store,
-        headerStore: headers.store,
-    };
-};
-
-export const CollectionView = <T, S, W extends Gtk.Widget>(props: CollectionViewProps<T, S, W>): ReactNode => {
-    const { setRef, resolver, headerResolver, itemStore, headerStore } = useCollectionWiring(props);
-    const intrinsic: ReactElement = createElement(props.element, { ...props.intrinsicProps, ref: setRef });
-
-    return (
-        <>
-            {intrinsic}
-            <ListPortalHost store={itemStore} resolver={resolver} render={props.renderItem} />
-            {props.headerFactoryBinding ? (
-                <ListPortalHost
-                    store={headerStore}
-                    resolver={headerResolver}
-                    render={headerRenderer<T, S>(props.renderHeader)}
-                />
-            ) : null}
-            {props.children}
-        </>
-    );
-};

package/src/column-view-column.tsx

@@ -1,73 +0,0 @@
-import type * as Gtk from "@gtkx/gi/gtk";
-import { GtkColumnViewColumn, type GtkColumnViewColumnProps } from "@gtkx/jsx/gtk";
-import { createElement, type ReactNode, useLayoutEffect, useRef, useState } from "react";
-import { useColumnViewContext } from "./contexts/column-view-context.js";
-import { useHeaderMenu } from "./hooks/use-header-menu.js";
-import { type FactoryBinding, useRealizedSlots } from "./hooks/use-realized-slots.js";
-import { ListPortalHost } from "./list-portal-host.js";
-import type { SlotRenderer } from "./list-slot.js";
-import type { ColumnViewColumnProps } from "./types.js";
-
-const factoryBinding: FactoryBinding<Gtk.ColumnViewColumn> = {
-    install: (column, factory) => column.setFactory(factory),
-    uninstall: (column) => column.setFactory(null),
-};
-
-/**
- * Props for the {@link ColumnViewColumn} component: the raw
- * `GtkColumnViewColumn` element surface (minus its imperative `factory` and
- * `sorter` properties) with its cell wiring replaced by the declarative
- * {@link ColumnViewColumnProps} API.
- */
-export type ColumnViewColumnComponentProps<T = unknown> = Omit<GtkColumnViewColumnProps, "factory" | "sorter"> &
-    ColumnViewColumnProps<T>;
-
-/**
- * A single column of a {@link ColumnView}, rendering each row's cell through
- * the declarative `renderCell` callback and optionally attaching a header
- * context menu.
- */
-export const ColumnViewColumn = <T = unknown>(props: ColumnViewColumnComponentProps<T>): ReactNode => {
-    const { id, title, expand, resizable, fixedWidth, visible, sortable, renderCell, headerMenu } = props;
-    const context = useColumnViewContext();
-    const [column, setColumn] = useState<Gtk.ColumnViewColumn | null>(null);
-
-    const captureColumn = useRef((value: Gtk.ColumnViewColumn | null) => {
-        setColumn(value);
-    }).current;
-
-    const { store } = useRealizedSlots<Gtk.ColumnViewColumn>({
-        target: column,
-        binding: factoryBinding,
-    });
-
-    const registerRef = useRef(context.register);
-    registerRef.current = context.register;
-    const unregisterRef = useRef(context.unregister);
-    unregisterRef.current = context.unregister;
-
-    useLayoutEffect(() => {
-        if (column === null) return;
-        registerRef.current({ id, column, sortable: sortable ?? false });
-        return () => unregisterRef.current(id);
-    }, [column, id, sortable]);
-
-    const headerMenuPortal = useHeaderMenu(column, headerMenu);
-
-    const slotRenderer: SlotRenderer<unknown, unknown> = (value, _treeRow, isHeader) =>
-        isHeader ? null : renderCell(value as T);
-
-    const intrinsicProps: Record<string, unknown> = { id, title, ref: captureColumn };
-    if (expand !== undefined) intrinsicProps["expand"] = expand;
-    if (resizable !== undefined) intrinsicProps["resizable"] = resizable;
-    if (fixedWidth !== undefined) intrinsicProps["fixedWidth"] = fixedWidth;
-    if (visible !== undefined) intrinsicProps["visible"] = visible;
-
-    return (
-        <>
-            {createElement(GtkColumnViewColumn, intrinsicProps)}
-            <ListPortalHost store={store} resolver={context.resolver} render={slotRenderer} />
-            {headerMenuPortal}
-        </>
-    );
-};

package/src/constraint-layout-apply.ts

@@ -1,121 +0,0 @@
-import * as GObject from "@gtkx/gi/gobject";
-import * as Gtk from "@gtkx/gi/gtk";
-import type { ConstraintGuideProps, ConstraintProps, ConstraintVflProps } from "./types.js";
-
-const SUPER_ID = "super";
-
-const unknownIdMessage = (role: string, id: string): string =>
-    `<ConstraintLayout.Constraint> references unknown id '${id}'. ` +
-    `Set name="${id}" on the ${role} widget, or add a <ConstraintLayout.Guide id="${id}">.`;
-
-const guideRegistry = new WeakMap<Gtk.ConstraintLayout, Map<string, Gtk.ConstraintGuide>>();
-
-const guidesFor = (layout: Gtk.ConstraintLayout): Map<string, Gtk.ConstraintGuide> => {
-    let map = guideRegistry.get(layout);
-    if (!map) {
-        map = new Map<string, Gtk.ConstraintGuide>();
-        guideRegistry.set(layout, map);
-    }
-    return map;
-};
-
-const explicitWidgetName = (widget: Gtk.Widget): string | null => {
-    const value = new GObject.Value();
-    value.init(GObject.TYPE_STRING);
-    widget.getProperty("name", value);
-    const name = value.getString();
-    return name !== null && name.length > 0 ? name : null;
-};
-
-function* namedChildren(layout: Gtk.ConstraintLayout): Generator<[string, Gtk.Widget]> {
-    const host = layout.getWidget();
-    if (!host) return;
-    for (let child = host.getFirstChild(); child; child = child.getNextSibling()) {
-        const name = explicitWidgetName(child);
-        if (name !== null) yield [name, child];
-    }
-}
-
-const findChildByName = (layout: Gtk.ConstraintLayout, id: string): Gtk.Widget | undefined => {
-    for (const [name, child] of namedChildren(layout)) {
-        if (name === id) return child;
-    }
-    return undefined;
-};
-
-const resolveConstraintTarget = (
-    layout: Gtk.ConstraintLayout,
-    id: string | undefined,
-): Gtk.ConstraintTarget | null | undefined => {
-    if (id === undefined || id === SUPER_ID) return null;
-    return findChildByName(layout, id) ?? guidesFor(layout).get(id);
-};
-
-const constraintViews = (layout: Gtk.ConstraintLayout): Map<string, Gtk.ConstraintTarget> => {
-    const views = new Map<string, Gtk.ConstraintTarget>();
-    for (const [name, child] of namedChildren(layout)) views.set(name, child);
-    for (const [name, guide] of guidesFor(layout)) {
-        if (!views.has(name)) views.set(name, guide);
-    }
-    return views;
-};
-
-const isLayoutLive = (layout: Gtk.ConstraintLayout): boolean => layout.getWidget() !== null;
-
-export function applyConstraint(layout: Gtk.ConstraintLayout, props: ConstraintProps): () => void {
-    const target = resolveConstraintTarget(layout, props.target);
-    if (target === undefined) throw new Error(unknownIdMessage("target", String(props.target)));
-    const source = resolveConstraintTarget(layout, props.source);
-    if (source === undefined) throw new Error(unknownIdMessage("source", String(props.source)));
-
-    const constraint = new Gtk.Constraint({
-        target,
-        targetAttribute: props.targetAttribute,
-        relation: props.relation ?? Gtk.ConstraintRelation.EQ,
-        source,
-        sourceAttribute: props.sourceAttribute ?? Gtk.ConstraintAttribute.NONE,
-        multiplier: props.multiplier ?? 1,
-        constant: props.constant ?? 0,
-        strength: props.strength ?? Gtk.ConstraintStrength.REQUIRED,
-    });
-    layout.addConstraint(constraint);
-
-    return () => {
-        if (isLayoutLive(layout)) layout.removeConstraint(constraint);
-    };
-}
-
-export function applyVfl(layout: Gtk.ConstraintLayout, props: ConstraintVflProps): () => void {
-    const views = constraintViews(layout);
-    const constraints = layout.addConstraintsFromDescription(
-        props.lines,
-        props.hspacing ?? 0,
-        props.vspacing ?? 0,
-        views,
-    );
-
-    return () => {
-        if (!isLayoutLive(layout)) return;
-        for (const constraint of constraints) layout.removeConstraint(constraint);
-    };
-}
-
-export function applyGuide(layout: Gtk.ConstraintLayout, props: ConstraintGuideProps): () => void {
-    const guide = new Gtk.ConstraintGuide({
-        name: props.id,
-        minWidth: props.minWidth,
-        minHeight: props.minHeight,
-        natWidth: props.natWidth,
-        natHeight: props.natHeight,
-        maxWidth: props.maxWidth,
-        maxHeight: props.maxHeight,
-        strength: props.strength,
-    });
-    layout.addGuide(guide);
-    guidesFor(layout).set(props.id, guide);
-
-    return () => {
-        guidesFor(layout).delete(props.id);
-        if (isLayoutLive(layout)) layout.removeGuide(guide);
-    };
-}

package/src/constraint-layout.tsx

@@ -1,130 +0,0 @@
-import type * as Gtk from "@gtkx/gi/gtk";
-import { GtkConstraintLayout } from "@gtkx/jsx/gtk";
-import { useForwardedRef } from "@gtkx/react";
-import {
-    type Context,
-    createContext,
-    createElement,
-    type ReactNode,
-    type Ref,
-    type RefObject,
-    useCallback,
-    useContext,
-    useEffect,
-    useLayoutEffect,
-    useRef,
-} from "react";
-import { applyConstraint, applyGuide, applyVfl } from "./constraint-layout-apply.js";
-import type { ConstraintGuideProps, ConstraintProps, ConstraintVflProps } from "./types.js";
-
-const ORPHAN_MESSAGE = "<ConstraintLayout.Constraint> / <Guide> / <Vfl> must be a child of <ConstraintLayout>";
-
-const ConstraintLayoutContext: Context<RefObject<Gtk.ConstraintLayout | null> | null> =
-    createContext<RefObject<Gtk.ConstraintLayout | null> | null>(null);
-
-const useConstraintLayoutRef = (): RefObject<Gtk.ConstraintLayout | null> => {
-    const ref = useContext(ConstraintLayoutContext);
-    if (!ref) throw new Error(ORPHAN_MESSAGE);
-    return ref;
-};
-
-export type ConstraintLayoutProps = {
-    children?: ReactNode;
-    ref?: Ref<Gtk.ConstraintLayout | null>;
-};
-
-type ContributionCleanupRef = { current: (() => void) | null };
-
-const cleanupContribution = (cleanupRef: ContributionCleanupRef): void => {
-    const cleanup = cleanupRef.current;
-    if (!cleanup) return;
-    cleanupRef.current = null;
-    cleanup();
-};
-
-const useLayoutContribution = (apply: (layout: Gtk.ConstraintLayout) => () => void, deps: unknown[]): void => {
-    const layoutRef = useConstraintLayoutRef();
-    useLayoutEffect(() => {
-        const layout = layoutRef.current;
-        if (!layout) return;
-        return apply(layout);
-    }, deps);
-};
-
-const useDeferredContribution = (apply: (layout: Gtk.ConstraintLayout) => () => void, deps: unknown[]): void => {
-    const layoutRef = useConstraintLayoutRef();
-    const cleanupRef = useRef<(() => void) | null>(null);
-
-    useLayoutEffect(() => () => cleanupContribution(cleanupRef), deps);
-
-    useEffect(() => {
-        const layout = layoutRef.current;
-        if (!layout) return;
-        const cleanup = apply(layout);
-        cleanupRef.current = cleanup;
-        return () => {
-            if (cleanupRef.current === cleanup) cleanupContribution(cleanupRef);
-        };
-    }, deps);
-};
-
-export const ConstraintLayout: ((props: ConstraintLayoutProps) => ReactNode) & {
-    Guide: (props: ConstraintGuideProps) => ReactNode;
-    Constraint: (props: ConstraintProps) => ReactNode;
-    Vfl: (props: ConstraintVflProps) => ReactNode;
-} = Object.assign(
-    ({ children, ref }: ConstraintLayoutProps): ReactNode => {
-        const layoutRef = useRef<Gtk.ConstraintLayout | null>(null);
-        const captureLayout = useCallback(
-            (layout: Gtk.ConstraintLayout | null): void => {
-                layoutRef.current = layout;
-            },
-            [layoutRef],
-        );
-        const [, mergedRef] = useForwardedRef<Gtk.ConstraintLayout>(ref, captureLayout);
-        return (
-            <>
-                {createElement(GtkConstraintLayout, { ref: mergedRef })}
-                <ConstraintLayoutContext.Provider value={layoutRef}>{children}</ConstraintLayoutContext.Provider>
-            </>
-        );
-    },
-    {
-        Guide: (props: ConstraintGuideProps): ReactNode => {
-            useLayoutContribution(
-                (layout) => applyGuide(layout, props),
-                [
-                    props.id,
-                    props.minWidth,
-                    props.minHeight,
-                    props.natWidth,
-                    props.natHeight,
-                    props.maxWidth,
-                    props.maxHeight,
-                    props.strength,
-                ],
-            );
-            return null;
-        },
-        Constraint: (props: ConstraintProps): ReactNode => {
-            useDeferredContribution(
-                (layout) => applyConstraint(layout, props),
-                [
-                    props.target,
-                    props.targetAttribute,
-                    props.relation,
-                    props.source,
-                    props.sourceAttribute,
-                    props.multiplier,
-                    props.constant,
-                    props.strength,
-                ],
-            );
-            return null;
-        },
-        Vfl: (props: ConstraintVflProps): ReactNode => {
-            useDeferredContribution((layout) => applyVfl(layout, props), [props.lines, props.hspacing, props.vspacing]);
-            return null;
-        },
-    },
-);

package/src/contexts/column-view-context.ts

@@ -1,28 +0,0 @@
-import type * as Gtk from "@gtkx/gi/gtk";
-import { type Context, createContext, type RefObject, useContext } from "react";
-import type { ItemResolver } from "../utils/item-resolver.js";
-
-export interface ColumnRegistration {
-    id: string;
-    column: Gtk.ColumnViewColumn;
-    sortable: boolean;
-}
-
-export interface ColumnViewContextValue {
-    columnView: RefObject<Gtk.ColumnView | null>;
-    resolver: ItemResolver<unknown, unknown>;
-    register(registration: ColumnRegistration): void;
-    unregister(id: string): void;
-}
-
-export const ColumnViewContext: Context<ColumnViewContextValue | null> = createContext<ColumnViewContextValue | null>(
-    null,
-);
-
-export const useColumnViewContext = (): ColumnViewContextValue => {
-    const context = useContext(ColumnViewContext);
-    if (context === null) {
-        throw new Error("<ColumnViewColumn> must be rendered inside a <ColumnView>.");
-    }
-    return context;
-};

package/src/hooks/use-drop-down-selection.ts

@@ -1,53 +0,0 @@
-import type * as GObject from "@gtkx/gi/gobject";
-import { useSignal } from "@gtkx/react";
-import { type GObjectTarget, resolveGobjectTarget, useGObjectSnapshot } from "@gtkx/react/internal";
-import { useLayoutEffect, useRef } from "react";
-import type { ItemResolver } from "../utils/item-resolver.js";
-
-export interface DropDownSelectionTarget extends GObject.Object {
-    getSelected(): number;
-    setSelected(position: number): void;
-}
-
-export interface DropDownSelectionOptions<T, S> {
-    widget: GObjectTarget<DropDownSelectionTarget>;
-    resolver: ItemResolver<T, S>;
-    selectedId: string | null | undefined;
-    onSelectionChanged: ((id: string) => void) | null | undefined;
-}
-
-const GTK_INVALID_LIST_POSITION = 4294967295;
-
-const normalizeSelected = (position: number): number =>
-    position === GTK_INVALID_LIST_POSITION || position < 0 ? -1 : position;
-
-export const useDropDownSelection = <T, S>(options: DropDownSelectionOptions<T, S>): number => {
-    const { widget, resolver, selectedId, onSelectionChanged } = options;
-    const resolved = resolveGobjectTarget(widget);
-
-    const selectedPosition = useGObjectSnapshot(widget, "notify::selected", (target) =>
-        target === null ? -1 : normalizeSelected(target.getSelected()),
-    );
-
-    const resolverRef = useRef(resolver);
-    resolverRef.current = resolver;
-    const onSelectionChangedRef = useRef(onSelectionChanged);
-    onSelectionChangedRef.current = onSelectionChanged;
-
-    useLayoutEffect(() => {
-        if (resolved === null || selectedId === undefined || selectedId === null) return;
-        const position = resolverRef.current.positionOf(selectedId);
-        if (position < 0) return;
-        if (normalizeSelected(resolved.getSelected()) !== position) resolved.setSelected(position);
-    }, [resolved, selectedId, resolver]);
-
-    useSignal(widget, "notify::selected", () => {
-        if (resolved === null) return;
-        const position = normalizeSelected(resolved.getSelected());
-        if (position < 0) return;
-        const id = resolverRef.current.idOf(position);
-        if (id !== undefined) onSelectionChangedRef.current?.(id);
-    });
-
-    return selectedPosition;
-};

package/src/hooks/use-header-menu.ts

@@ -1,33 +0,0 @@
-import * as Gio from "@gtkx/gi/gio";
-import * as GObject from "@gtkx/gi/gobject";
-import type * as Gtk from "@gtkx/gi/gtk";
-import { createPortal } from "@gtkx/react";
-import { stateOf } from "@gtkx/react/internal";
-import { type ReactNode, useLayoutEffect, useRef } from "react";
-
-const findMenuModel = (container: GObject.Object): Gio.MenuModel | null => {
-    for (const child of stateOf(container).children) {
-        if (child instanceof Gio.MenuModel) return child;
-    }
-    return null;
-};
-
-export const useHeaderMenu = (column: Gtk.ColumnViewColumn | null, headerMenu: ReactNode): ReactNode => {
-    const containerRef = useRef<GObject.Object | null>(null);
-    if (containerRef.current === null) {
-        containerRef.current = new GObject.Object();
-    }
-    const container = containerRef.current;
-
-    useLayoutEffect(() => {
-        if (column === null) return;
-        if (headerMenu === undefined || headerMenu === null) {
-            column.setHeaderMenu(null);
-            return;
-        }
-        column.setHeaderMenu(findMenuModel(container));
-    });
-
-    if (headerMenu === undefined || headerMenu === null) return null;
-    return createPortal(headerMenu, container, "header-menu");
-};