@gtkx/components 1.0.0-rc.4 → 1.0.0

package/src/internal/slots.ts

@@ -0,0 +1,67 @@
+import { decodePartAt, encodePart } from "./keys.js";
+
+type SlotKey = {
+    levelPath: string;
+    slot: number;
+};
+
+type SlotMap = Map<string, Set<number>>;
+
+function getLevelBoundary(path: string): number {
+    let offset = 0;
+    let boundary = 0;
+
+    while (offset < path.length) {
+        const part = decodePartAt(path, offset);
+
+        if (part === null) {
+            return boundary;
+        }
+
+        boundary = offset;
+        offset += encodePart(part).length;
+    }
+
+    return boundary;
+}
+
+function getSlotKey(path: string): SlotKey | null {
+    const boundary = getLevelBoundary(path);
+    const part = decodePartAt(path, boundary);
+
+    if (part === null) {
+        return null;
+    }
+
+    return { levelPath: path.slice(0, boundary), slot: Number(part) };
+}
+
+function trackPath(slots: SlotMap, path: string): void {
+    const key = getSlotKey(path);
+
+    if (key === null) {
+        return;
+    }
+
+    const level = slots.get(key.levelPath);
+
+    if (level === undefined) {
+        slots.set(key.levelPath, new Set([key.slot]));
+
+        return;
+    }
+
+    level.add(key.slot);
+}
+
+function trackPaths(paths: Iterable<string>): SlotMap {
+    const slots: SlotMap = new Map();
+
+    for (const path of paths) {
+        trackPath(slots, path);
+    }
+
+    return slots;
+}
+
+export { getSlotKey, trackPath, trackPaths, type SlotMap };

package/src/internal/tree-expansion.ts

@@ -0,0 +1,110 @@
+import type { CollectionIndex } from "./collection-index.js";
+import type { SlotMap } from "./slots.js";
+import type { VisibleOrder } from "./tree-order.js";
+import { encodePart } from "./keys.js";
+import { getSlotKey, trackPath, trackPaths } from "./slots.js";
+import { buildVisibleOrder } from "./tree-order.js";
+
+type TreeExpansion = {
+    index: CollectionIndex;
+    expanded: Set<string>;
+    slots: SlotMap;
+    order: VisibleOrder | null;
+    isApplying: boolean;
+    isSyncing: boolean;
+};
+
+function dropSubtree(expansion: TreeExpansion, path: string): void {
+    expansion.expanded.delete(path);
+    const level = expansion.slots.get(path);
+
+    if (level === undefined) {
+        return;
+    }
+
+    expansion.slots.delete(path);
+
+    for (const slot of level) {
+        dropSubtree(expansion, path + encodePart(String(slot)));
+    }
+}
+
+function createTreeExpansion(index: CollectionIndex): TreeExpansion {
+    return { index, expanded: new Set(), slots: new Map(), order: null, isApplying: false, isSyncing: false };
+}
+
+function orderFor(expansion: TreeExpansion): VisibleOrder {
+    expansion.order ??= buildVisibleOrder(expansion.index, expansion.slots);
+
+    return expansion.order;
+}
+
+function adoptOrder(expansion: TreeExpansion, order: VisibleOrder): void {
+    expansion.expanded = new Set(order.expandedPaths);
+    expansion.slots = trackPaths(order.expandedPaths);
+    expansion.order = order;
+}
+
+function prunePath(expansion: TreeExpansion, path: string): void {
+    const key = getSlotKey(path);
+
+    if (key !== null) {
+        expansion.slots.get(key.levelPath)?.delete(key.slot);
+    }
+
+    dropSubtree(expansion, path);
+    expansion.order = null;
+}
+
+function pruneSlots(expansion: TreeExpansion, levelPath: string, isPruned: (slot: number) => boolean): void {
+    const level = expansion.slots.get(levelPath);
+
+    if (level === undefined) {
+        return;
+    }
+
+    for (const slot of level) {
+        if (!isPruned(slot)) {
+            continue;
+        }
+
+        level.delete(slot);
+        dropSubtree(expansion, levelPath + encodePart(String(slot)));
+    }
+
+    expansion.order = null;
+}
+
+function markExpanded(expansion: TreeExpansion, path: string, isExpanded: boolean): void {
+    if (isExpanded) {
+        expansion.expanded.add(path);
+        trackPath(expansion.slots, path);
+        expansion.order = null;
+
+        return;
+    }
+
+    prunePath(expansion, path);
+}
+
+function resetExpansion(expansion: TreeExpansion): void {
+    expansion.expanded = new Set();
+    expansion.slots = new Map();
+    expansion.order = null;
+}
+
+function adoptIndex(expansion: TreeExpansion, index: CollectionIndex): void {
+    expansion.index = index;
+    expansion.order = null;
+}
+
+export {
+    adoptIndex,
+    adoptOrder,
+    createTreeExpansion,
+    markExpanded,
+    orderFor,
+    pruneSlots,
+    resetExpansion,
+    type TreeExpansion,
+};

package/src/internal/tree-order.ts

@@ -0,0 +1,138 @@
+import type { ListItem } from "../types.js";
+import type { CollectionIndex, Level } from "./collection-index.js";
+import type { SlotMap } from "./slots.js";
+import { encodePart } from "./keys.js";
+
+type VisibleRow = {
+    level: Level;
+    slot: number;
+    item: ListItem;
+    position: number;
+    isOpen: boolean;
+    isMarked: boolean;
+};
+
+type VisibleOrder = {
+    expandedPaths: string[];
+    expandedIds: string[];
+};
+
+type RowVisitor = (row: VisibleRow) => void;
+
+type WalkOptions = {
+    index: CollectionIndex;
+    slots: SlotMap;
+    marks?: SlotMap | undefined;
+    visit?: RowVisitor | undefined;
+};
+
+type WalkFrame = {
+    level: Level;
+    cursor: number;
+    open: Set<number> | undefined;
+    marked: Set<number> | undefined;
+};
+
+type WalkState = {
+    options: WalkOptions;
+    stack: WalkFrame[];
+    row: VisibleRow;
+    order: VisibleOrder;
+};
+
+const NO_LEVEL: Level = { path: "", items: [], expandableFlags: [] };
+const NO_ITEM: ListItem = { id: "", value: undefined };
+
+const getRowPath = (row: VisibleRow): string => row.level.path + encodePart(String(row.slot));
+
+function frameFor(options: WalkOptions, level: Level): WalkFrame {
+    return { level, cursor: 0, open: options.slots.get(level.path), marked: options.marks?.get(level.path) };
+}
+
+function descend(state: WalkState, path: string): void {
+    const child = state.options.index.children.get(path);
+
+    if (child === undefined || child.items.length === 0) {
+        return;
+    }
+
+    state.order.expandedPaths.push(path);
+    state.order.expandedIds.push(state.row.item.id);
+    state.stack.push(frameFor(state.options, child));
+}
+
+function visitSlot(state: WalkState, frame: WalkFrame, slot: number): void {
+    const item = frame.level.items[slot];
+
+    if (item === undefined) {
+        return;
+    }
+
+    const { row } = state;
+    row.level = frame.level;
+    row.slot = slot;
+    row.item = item;
+    row.isOpen = frame.open?.has(slot) ?? false;
+    row.isMarked = frame.marked?.has(slot) ?? false;
+    state.options.visit?.(row);
+    row.position += 1;
+
+    if (row.isOpen) {
+        descend(state, getRowPath(row));
+    }
+}
+
+function advanceFrame(state: WalkState): void {
+    const frame = state.stack.at(-1);
+
+    if (frame === undefined || frame.cursor >= frame.level.items.length) {
+        state.stack.pop();
+
+        return;
+    }
+
+    const slot = frame.cursor;
+    frame.cursor += 1;
+    visitSlot(state, frame, slot);
+}
+
+function walkVisible(options: WalkOptions): VisibleOrder {
+    const order: VisibleOrder = { expandedPaths: [], expandedIds: [] };
+    const row: VisibleRow = { level: NO_LEVEL, slot: 0, item: NO_ITEM, position: 0, isOpen: false, isMarked: false };
+    const frames = options.index.groups.map((level) => frameFor(options, level));
+    const state: WalkState = { options, stack: frames.toReversed(), row, order };
+
+    while (state.stack.length > 0) {
+        advanceFrame(state);
+    }
+
+    return order;
+}
+
+function buildVisibleOrder(index: CollectionIndex, slots: SlotMap): VisibleOrder {
+    return walkVisible({ index, slots });
+}
+
+function findPositions(index: CollectionIndex, slots: SlotMap, ids: Set<string>): number[] {
+    const found: number[] = [];
+
+    walkVisible({
+        index,
+        slots,
+        visit: (row) => {
+            if (ids.has(row.item.id)) {
+                found.push(row.position);
+            }
+        },
+    });
+
+    return found;
+}
+
+export {
+    buildVisibleOrder,
+    findPositions,
+    walkVisible,
+    type VisibleOrder,
+    type WalkOptions,
+};

package/src/internal/use-collection.tsx

@@ -23,13 +23,13 @@ type CollectionResult = {
 
 function useCollectionData(options: CollectionDataOptions): Collection {
     const { items, sections, isFlat } = options;
-    const [gtk] = useState(createCollectionModel);
+    const [collectionModel] = useState(createCollectionModel);
     const index = useMemo(() => createCollectionIndex(items, sections, isFlat === true), [items, sections, isFlat]);
-    const collection = useMemo(() => createCollection(gtk, index), [gtk, index]);
+    const collection = useMemo(() => createCollection(collectionModel, index), [collectionModel, index]);
 
     useLayoutEffect(() => {
-        gtk.sync(index);
-    }, [gtk, index]);
+        collectionModel.sync(index);
+    }, [collectionModel, index]);
 
     return collection;
 }
@@ -54,4 +54,4 @@ function useCollection(options: CollectionOptions): CollectionResult {
     return { collection, selection };
 }
 
-export { useCollection, useCollectionData, type CollectionDataOptions, type CollectionOptions };
+export { useCollection, useCollectionData };

package/src/list-view.tsx

@@ -2,7 +2,7 @@ import type { ReactNode } from "react";
 import { GtkListView, GtkSignalListItemFactory } from "@gtkx/jsx/gtk";
 import { omit } from "@gtkx/utils";
 import type { ListViewProps } from "./types.js";
-import { HeaderPortals, ItemPortals, useHeaderCells, useItemCells } from "./internal/cells.js";
+import { ItemPortals, useItemCells, useSectionHeader } from "./internal/cells.js";
 import { useCollection } from "./internal/use-collection.js";
 
 const LIST_VIEW_PROPS = [
@@ -15,6 +15,7 @@ const LIST_VIEW_PROPS = [
     "selectionMode",
     "expandedIds",
     "onExpandedChange",
+    "expanderDescriptions",
     "estimatedItemHeight",
     "estimatedItemWidth",
 ] as const satisfies (keyof ListViewProps)[];
@@ -24,27 +25,30 @@ const LIST_VIEW_PROPS = [
  * controlled selection, controlled tree expansion, and estimated item sizing.
  */
 function ListView<T = unknown, S = unknown>(props: ListViewProps<T, S>): ReactNode {
-    const { renderItem, renderHeader, expandedIds, estimatedItemHeight, estimatedItemWidth } = props;
+    const { renderItem, renderHeader, expandedIds, expanderDescriptions } = props;
+    const { estimatedItemHeight, estimatedItemWidth } = props;
     const rest = omit(props, LIST_VIEW_PROPS);
     const size = { width: estimatedItemWidth ?? -1, height: estimatedItemHeight ?? -1 };
     const { collection, selection } = useCollection(props);
     const itemCells = useItemCells(size);
-    const headerCells = useHeaderCells(size);
+    const header = useSectionHeader(renderHeader, collection, size);
 
     return (
         <>
             <GtkListView
                 model={selection}
                 factory={<GtkSignalListItemFactory {...itemCells.handlers} />}
-                {...(renderHeader != null && {
-                    headerFactory: <GtkSignalListItemFactory {...headerCells.handlers} />,
-                })}
+                {...header.factoryProps}
                 {...rest}
             />
-            <ItemPortals store={itemCells} render={renderItem} collection={collection} expandedIds={expandedIds} />
-            {renderHeader != null && (
-                <HeaderPortals store={headerCells} render={renderHeader} collection={collection} />
-            )}
+            <ItemPortals
+                registry={itemCells}
+                render={renderItem}
+                collection={collection}
+                expandedIds={expandedIds}
+                expanderDescriptions={expanderDescriptions}
+            />
+            {header.portals}
         </>
     );
 }

package/src/types.ts

@@ -13,18 +13,18 @@ import type { ReactNode } from "react";
  * arbitrary value. Nested items form a tree.
  */
 type ListItem<T = unknown> = {
-    /** Stable identifier used to track the item across updates and selection. */
+    /** Stable identifier used to track the item across updates and selection, naming every row that carries it. */
     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. */
     children?: ListItem<T>[] | undefined;
-    /** Hides the tree expander arrow even when the item has children. */
-    hideExpander?: boolean | undefined;
-    /** Adds indentation matching the item's depth in the tree. */
-    indentForDepth?: boolean | undefined;
-    /** Reserves indentation space for an expander icon. */
-    indentForIcon?: boolean | undefined;
+    /** Hides the tree expander arrow even when the item has children, through `hide-expander`. */
+    shouldHideExpander?: boolean | undefined;
+    /** Adds indentation matching the item's depth in the tree, through `indent-for-depth`. */
+    shouldIndentForDepth?: boolean | undefined;
+    /** Reserves indentation space for an expander icon, through `indent-for-icon`. */
+    shouldIndentForIcon?: boolean | undefined;
 };
 
 /** A group of items rendered under a shared section header. */
@@ -49,6 +49,24 @@ type ListItemRenderArgs<T> = {
     isExpanded?: boolean | undefined;
 };
 
+/**
+ * Properties applied to the row that carries one item's cells. A Gtk.ColumnViewRow is not a widget, so
+ * these are the only handles it offers; anything omitted falls back to the row's own default, which
+ * leaves the accessibility strings unset rather than setting them to an empty string.
+ */
+type ListRowProps = {
+    /** Name a screen reader announces for the row, through `accessible-label`. */
+    accessibleLabel?: string | undefined;
+    /** Longer description a screen reader announces for the row, through `accessible-description`. */
+    accessibleDescription?: string | undefined;
+    /** Whether activating the row emits the view's `activate` signal; rows are activatable by default. */
+    isActivatable?: boolean | undefined;
+    /** Whether the row takes keyboard focus; rows are focusable by default. */
+    isFocusable?: boolean | undefined;
+    /** Whether clicking or keying the row tries to select it; rows are selectable by default. */
+    isSelectable?: boolean | undefined;
+};
+
 /** Arguments passed to a {@link ListSectionRenderer} when rendering one section header. */
 type ListSectionRenderArgs<S> = {
     /** Value of the `ListSection` whose header is being rendered. */
@@ -59,6 +77,8 @@ type ListSectionRenderArgs<S> = {
 type ListItemRenderer<T> = (args: ListItemRenderArgs<T>) => ReactNode;
 /** Renders the contents of one section header of a collection view. */
 type ListSectionRenderer<S> = (args: ListSectionRenderArgs<S>) => ReactNode;
+/** Returns the {@link ListRowProps} to apply to the row displaying one item, re-run whenever the item renders. */
+type ListRowPropsResolver<T> = (args: ListItemRenderArgs<T>) => ListRowProps;
 
 /** Size a collection view requests for each cell before its contents render, keeping scroll estimates steady. */
 type ItemSizeProps = {
@@ -70,20 +90,56 @@ type ItemSizeProps = {
 
 /** Controlled selection shared by the multi-item collection views. */
 type SelectionProps = {
-    /** Ids of the items to keep selected; omitting it leaves the view's own selection alone. */
+    /**
+     * 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.
+     */
     selectedIds?: string[] | null | undefined;
-    /** Called with the ids of every selected item whenever the selection changes, and once on mount. */
+    /** Called with one id per selected row whenever the selection changes, and once on mount. */
     onSelectionChanged?: ((ids: string[]) => void) | null | undefined;
     /** How much the user may select, one item at a time unless `MULTIPLE` or `NONE` is given. */
     selectionMode?: Gtk.SelectionMode | null | undefined;
 };
 
+/**
+ * Wording a screen reader announces for the control that expands and collapses a row. GTK names that control
+ * after the row's own content and reports whether it is expanded, but says nothing about what activating it
+ * does, so these strings supply that and belong in the application's own language.
+ */
+type ExpanderDescriptions = {
+    /** Announced while the row is collapsed, such as "Expand". */
+    expand: string;
+    /** Announced while the row is expanded, such as "Collapse". */
+    collapse: string;
+};
+
 /** Controlled expansion for the views that turn nested `ListItem.children` into a tree. */
 type ExpansionProps = {
-    /** Ids of the items to keep expanded; omitting it leaves the rows' own expanded state alone. */
+    /**
+     * 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.
+     */
     expandedIds?: string[] | null | undefined;
-    /** Called with the ids of every expanded row whenever expansion changes. */
+    /** Called with one id per expanded row, in visible order, whenever expansion changes. */
     onExpandedChange?: ((ids: string[]) => void) | null | undefined;
+    /**
+     * Wording announced for the expander of every row that can expand, describing what activating it does.
+     * Omitting it leaves those expanders described only by the row they carry, and rows that cannot expand or
+     * that hide their expander are never described.
+     */
+    expanderDescriptions?: ExpanderDescriptions | null | undefined;
+};
+
+/** Controlled sorting for the views whose headers can sort the collection. */
+type SortProps = {
+    /** Id of the column the view is sorted by, making sorting controlled. */
+    sortColumn?: string | null | undefined;
+    /** Direction `sortColumn` is sorted in, defaulting to ascending. */
+    sortOrder?: Gtk.SortType | null | undefined;
+    /** Called when the user sorts from a header, with the primary column's id, or null, and its order. */
+    onSortChanged?: ((column: string | null, order: Gtk.SortType) => void) | null | undefined;
 };
 
 /** The data a collection view renders, either as a plain item list or grouped into sections. */
@@ -111,29 +167,26 @@ type ColumnViewColumn<T = unknown> = Omit<GtkColumnViewColumnProps, "factory" |
 /** The declarative collection props {@link ColumnView} adds on top of Gtk.ColumnView's own. */
 type ColumnViewOwnProps<T, S> = SelectionProps &
     ExpansionProps &
+    SortProps &
     SourceProps<T, S> &
     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;
-        /** Id of the column the view is sorted by, making sorting controlled. */
-        sortColumn?: string | null | undefined;
-        /** Direction `sortColumn` is sorted in, defaulting to ascending. */
-        sortOrder?: Gtk.SortType | null | undefined;
-        /** Called when the user sorts from a header, with the primary column's id, or null, and its order. */
-        onSortChanged?: ((column: string | null, order: Gtk.SortType) => void) | 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, and the columns to render.
+ * header renderer, per-row props, and the columns to render.
  */
 type ColumnViewProps<T = unknown, S = unknown> = Omit<
     GtkColumnViewProps,
-    "columns" | "model" | "headerFactory" | keyof ColumnViewOwnProps<T, S>
+    "columns" | "model" | "headerFactory" | "rowFactory" | keyof ColumnViewOwnProps<T, S>
 > &
 ColumnViewOwnProps<T, S>;
 
@@ -207,14 +260,18 @@ ListViewOwnProps<T, S>;
 
 export {
     type SelectionProps,
+    type ExpanderDescriptions,
     type ExpansionProps,
+    type SortProps,
     type DropDownOwnProps,
     type DropDownWidgetProps,
     type ListItem,
     type ListSection,
     type ListItemRenderArgs,
+    type ListRowProps,
     type ListSectionRenderArgs,
     type ListItemRenderer,
+    type ListRowPropsResolver,
     type ListSectionRenderer,
     type ColumnViewColumn,
     type ColumnViewProps,