@gtkx/react 0.21.0 → 1.0.0-rc.2

package/src/adw/element-behaviors.ts

@@ -0,0 +1,379 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import * as Adw from "@gtkx/gi/adw";
+import type { AlertDialogResponse } from "./prop-types.js";
+import {
+    addRemoveSlot,
+    adoptedChildrenSlot,
+    boxSlot,
+    childSetterSlot,
+    contentSetterSlot,
+    deferred,
+    list,
+    slot,
+} from "../reconciler/behaviors.js";
+import { type ElementConfig, registerElements } from "../reconciler/registry.js";
+import { BUILTIN_ELEMENTS } from "./element-config.js";
+
+type AdwChildSetter =
+    | Adw.Bin |
+    Adw.BreakpointBin |
+    Adw.Clamp |
+    Adw.ClampScrollable |
+    Adw.Dialog |
+    Adw.NavigationPage |
+    Adw.SplitButton |
+    Adw.StatusPage |
+    Adw.TabOverview |
+    Adw.ToastOverlay |
+    Adw.Toggle;
+
+type AdwContentSetter = Adw.ApplicationWindow | Adw.BottomSheet | Adw.Flap | Adw.OverlaySplitView | Adw.Window;
+type BreakpointHost = Adw.ApplicationWindow | Adw.Window | Adw.Dialog;
+type PageHost = Adw.PreferencesDialog | Adw.PreferencesWindow;
+type PrefixSuffixRow = Adw.ActionRow | Adw.EntryRow | Adw.ExpanderRow;
+
+const childSetter = childSetterSlot<AdwChildSetter>();
+const contentSetter = contentSetterSlot<AdwContentSetter>();
+
+const breakpoints = slot<BreakpointHost, Adw.Breakpoint>("breakpoints", "AdwBreakpoint", {
+    attach: (host, breakpoint) => {
+        host.addBreakpoint(breakpoint);
+    },
+});
+
+const prefixSuffix = [
+    slot<PrefixSuffixRow, Gtk.Widget>("prefix", "GtkWidget", {
+        attach: (row, child) => {
+            row.addPrefix(child);
+        },
+        detach: (row, child) => {
+            row.remove(child);
+        },
+    }),
+    slot<PrefixSuffixRow, Gtk.Widget>("suffix", "GtkWidget", {
+        attach: (row, child) => {
+            row.addSuffix(child);
+        },
+        detach: (row, child) => {
+            row.remove(child);
+        },
+    }),
+];
+
+const pageHostChildren = addRemoveSlot<Adw.PreferencesPage, PageHost>(
+    "children",
+    "AdwPreferencesPage",
+    (host, page) => {
+        host.add(page);
+    },
+    (host, page) => {
+        host.remove(page);
+    },
+);
+
+/** The runtime half of the built-in element configuration: the behaviors bound to each GObject type. */
+const BUILTIN_BEHAVIORS: Record<string, ElementConfig<never>> = {
+    AdwBin: {
+        behaviors: [childSetter],
+    },
+    AdwClamp: {
+        behaviors: [childSetter],
+    },
+    AdwClampScrollable: {
+        behaviors: [childSetter],
+    },
+    AdwNavigationPage: {
+        behaviors: [childSetter],
+    },
+    AdwSplitButton: {
+        behaviors: [childSetter],
+    },
+    AdwStatusPage: {
+        behaviors: [childSetter],
+    },
+    AdwTabOverview: {
+        behaviors: [childSetter],
+    },
+    AdwToastOverlay: {
+        behaviors: [childSetter],
+    },
+    AdwToggle: {
+        behaviors: [childSetter],
+    },
+    AdwBottomSheet: {
+        behaviors: [contentSetter],
+    },
+    AdwFlap: {
+        behaviors: [contentSetter],
+    },
+    AdwOverlaySplitView: {
+        behaviors: [contentSetter],
+    },
+    AdwDialog: {
+        behaviors: [childSetter, breakpoints],
+    },
+    AdwApplicationWindow: {
+        behaviors: [contentSetter, breakpoints],
+    },
+    AdwWindow: {
+        behaviors: [contentSetter, breakpoints],
+    },
+    AdwBreakpointBin: {
+        behaviors: [
+            childSetter,
+            addRemoveSlot<Adw.Breakpoint, Adw.BreakpointBin>(
+                "breakpoints",
+                "AdwBreakpoint",
+                (bin, breakpoint) => {
+                    bin.addBreakpoint(breakpoint);
+                },
+                (bin, breakpoint) => {
+                    bin.removeBreakpoint(breakpoint);
+                },
+            ),
+        ],
+    },
+    AdwActionRow: {
+        behaviors: prefixSuffix,
+    },
+    AdwEntryRow: {
+        behaviors: prefixSuffix,
+    },
+    AdwExpanderRow: {
+        behaviors: [
+            ...prefixSuffix,
+            addRemoveSlot<Gtk.Widget, Adw.ExpanderRow>(
+                "rows",
+                "GtkWidget",
+                (row, child) => {
+                    row.addRow(child);
+                },
+                (row, child) => {
+                    row.remove(child);
+                },
+            ),
+            addRemoveSlot<Gtk.Widget, Adw.ExpanderRow>(
+                "actions",
+                "GtkWidget",
+                (row, child) => {
+                    row.addAction(child);
+                },
+                (row, child) => {
+                    row.remove(child);
+                },
+            ),
+        ],
+    },
+    AdwNavigationSplitView: {
+        behaviors: [contentSetterSlot<Adw.NavigationSplitView, Adw.NavigationPage>("AdwNavigationPage")],
+    },
+    AdwLeaflet: {
+        behaviors: [boxSlot<Adw.Leaflet | Adw.WrapBox>()],
+    },
+    AdwWrapBox: {
+        behaviors: [boxSlot<Adw.Leaflet | Adw.WrapBox>()],
+    },
+    AdwCarousel: {
+        behaviors: [
+            slot<Adw.Carousel, Gtk.Widget>("children", "GtkWidget", {
+                attach: (carousel, child, info) => {
+                    carousel.insert(child, info.index);
+                },
+                detach: (carousel, child) => {
+                    carousel.remove(child);
+                },
+                reorder: (carousel, child, info) => {
+                    carousel.reorder(child, info.index);
+                },
+            }),
+        ],
+    },
+    AdwPreferencesPage: {
+        behaviors: [
+            slot<Adw.PreferencesPage, Adw.PreferencesGroup>("children", "AdwPreferencesGroup", {
+                attach: (page, group, info) => {
+                    page.insert(group, info.index);
+                },
+                detach: (page, group) => {
+                    page.remove(group);
+                },
+            }),
+        ],
+    },
+    AdwPreferencesDialog: {
+        behaviors: [pageHostChildren],
+    },
+    AdwPreferencesWindow: {
+        behaviors: [pageHostChildren],
+    },
+    AdwPreferencesGroup: {
+        behaviors: [
+            addRemoveSlot<Gtk.Widget, Adw.PreferencesGroup>(
+                "children",
+                "GtkWidget",
+                (group, child) => {
+                    group.add(child);
+                },
+                (group, child) => {
+                    group.remove(child);
+                },
+            ),
+        ],
+    },
+    AdwSqueezer: {
+        behaviors: [
+            addRemoveSlot<Gtk.Widget, Adw.Squeezer>(
+                "children",
+                "GtkWidget",
+                (squeezer, child) => {
+                    squeezer.add(child);
+                },
+                (squeezer, child) => {
+                    squeezer.remove(child);
+                },
+            ),
+        ],
+    },
+    AdwTabView: {
+        behaviors: [
+            slot<Adw.TabView, Gtk.Widget>("children", "GtkWidget", {
+                attach: (view, child, info) => view.insert(child, info.index),
+                reorder: (view, _child, info) => {
+                    if (info.adopted instanceof Adw.TabPage) {
+                        view.reorderPage(info.adopted, info.index);
+                    }
+                },
+                detach: (view, _child, info) => {
+                    if (info.adopted instanceof Adw.TabPage) {
+                        view.closePage(info.adopted);
+                    }
+                },
+                resolve: (view, child) => view.getPage(child),
+            }),
+        ],
+    },
+    AdwNavigationView: {
+        behaviors: [
+            addRemoveSlot<Adw.NavigationPage, Adw.NavigationView>(
+                "children",
+                "AdwNavigationPage",
+                (view, page) => {
+                    view.add(page);
+                },
+                (view, page) => {
+                    view.remove(page);
+                },
+            ),
+        ],
+    },
+    AdwViewStack: {
+        behaviors: [
+            adoptedChildrenSlot<Adw.ViewStack, Gtk.Widget>(
+                "GtkWidget",
+                (stack, child) => stack.add(child),
+                (stack, child) => {
+                    stack.remove(child);
+                },
+            ),
+            deferred<Adw.ViewStack, string>("visibleChildName", (stack, name) => stack.getChildByName(name) !== null),
+        ],
+    },
+    AdwToolbarView: {
+        behaviors: [
+            contentSetterSlot<Adw.ToolbarView>(),
+            slot<Adw.ToolbarView, Gtk.Widget>("topBar", "GtkWidget", {
+                attach: (view, child) => {
+                    view.addTopBar(child);
+                },
+                detach: (view, child) => {
+                    view.remove(child);
+                },
+            }),
+            slot<Adw.ToolbarView, Gtk.Widget>("bottomBar", "GtkWidget", {
+                attach: (view, child) => {
+                    view.addBottomBar(child);
+                },
+                detach: (view, child) => {
+                    view.remove(child);
+                },
+            }),
+        ],
+    },
+    AdwHeaderBar: {
+        behaviors: [
+            slot<Adw.HeaderBar, Gtk.Widget>("start", "GtkWidget", {
+                attach: (bar, child) => {
+                    bar.packStart(child);
+                },
+                detach: (bar, child) => {
+                    bar.remove(child);
+                },
+            }),
+            slot<Adw.HeaderBar, Gtk.Widget>("end", "GtkWidget", {
+                attach: (bar, child) => {
+                    bar.packEnd(child);
+                },
+                detach: (bar, child) => {
+                    bar.remove(child);
+                },
+            }),
+        ],
+    },
+    AdwShortcutsDialog: {
+        behaviors: [
+            slot<Adw.ShortcutsDialog, Adw.ShortcutsSection>("children", "AdwShortcutsSection", {
+                attach: (dialog, section) => {
+                    dialog.add(section);
+                },
+            }),
+        ],
+    },
+    AdwShortcutsSection: {
+        behaviors: [
+            slot<Adw.ShortcutsSection, Adw.ShortcutsItem>("children", "AdwShortcutsItem", {
+                attach: (section, item) => {
+                    section.add(item);
+                },
+            }),
+        ],
+    },
+    AdwToggleGroup: {
+        behaviors: [
+            addRemoveSlot<Adw.Toggle, Adw.ToggleGroup>(
+                "children",
+                "AdwToggle",
+                (group, toggle) => {
+                    group.add(toggle);
+                },
+                (group, toggle) => {
+                    group.remove(toggle);
+                },
+            ),
+            deferred<Adw.ToggleGroup, string>("activeName", (group, name) => group.getToggleByName(name) !== null),
+            deferred("active"),
+        ],
+    },
+    AdwAlertDialog: {
+        behaviors: [
+            list<Adw.AlertDialog, AlertDialogResponse>("responses", {
+                add: (dialog, response) => {
+                    dialog.addResponse(response.id, response.label);
+
+                    if (response.appearance !== undefined) {
+                        dialog.setResponseAppearance(response.id, response.appearance);
+                    }
+
+                    if (response.enabled !== undefined) {
+                        dialog.setResponseEnabled(response.id, response.enabled);
+                    }
+                },
+                remove: (dialog, response) => {
+                    dialog.removeResponse(response.id);
+                },
+            }),
+        ],
+    },
+};
+
+registerElements(BUILTIN_ELEMENTS);
+registerElements(BUILTIN_BEHAVIORS);

package/src/adw/element-config.ts

@@ -0,0 +1,140 @@
+import { type ElementConfig, internal, type ModuleExport } from "../reconciler/registry.js";
+
+const childrenProps = internal("ChildrenProps");
+const breakpointsProps = adw("AdwBreakpointsProps");
+const preferencesRowProps = adw("AdwPreferencesRowProps");
+
+/**
+ * The static, runtime-free half of the built-in element configuration: which base props interface each
+ * generated element extends, which component wraps it, and whether its GObject is created lazily by its
+ * parent. Codegen imports this module, so it must never reach the GObject bindings.
+ */
+const BUILTIN_ELEMENTS: Record<string, ElementConfig> = {
+    AdwBin: {
+        props: childrenProps,
+    },
+    AdwClamp: {
+        props: childrenProps,
+    },
+    AdwClampScrollable: {
+        props: childrenProps,
+    },
+    AdwNavigationPage: {
+        props: childrenProps,
+    },
+    AdwSplitButton: {
+        props: childrenProps,
+    },
+    AdwStatusPage: {
+        props: childrenProps,
+    },
+    AdwTabOverview: {
+        props: childrenProps,
+    },
+    AdwToastOverlay: {
+        props: childrenProps,
+    },
+    AdwToggle: {
+        props: childrenProps,
+    },
+    AdwBottomSheet: {
+        props: childrenProps,
+    },
+    AdwFlap: {
+        props: childrenProps,
+    },
+    AdwOverlaySplitView: {
+        props: childrenProps,
+    },
+    AdwViewStackPage: {
+        lazy: true,
+    },
+    AdwTabPage: {
+        lazy: true,
+    },
+    AdwPreferencesRow: {
+        props: preferencesRowProps,
+    },
+    AdwDialog: {
+        props: breakpointsProps,
+        component: adw("createDialogComponent"),
+    },
+    AdwApplicationWindow: {
+        props: breakpointsProps,
+    },
+    AdwWindow: {
+        props: breakpointsProps,
+    },
+    AdwBreakpointBin: {
+        props: breakpointsProps,
+    },
+    AdwActionRow: {
+        props: preferencesRowProps,
+    },
+    AdwEntryRow: {
+        props: preferencesRowProps,
+    },
+    AdwExpanderRow: {
+        props: adw("AdwExpanderRowProps"),
+    },
+    AdwNavigationSplitView: {
+        props: childrenProps,
+    },
+    AdwLeaflet: {
+        props: childrenProps,
+    },
+    AdwWrapBox: {
+        props: childrenProps,
+    },
+    AdwCarousel: {
+        props: childrenProps,
+    },
+    AdwPreferencesPage: {
+        props: childrenProps,
+    },
+    AdwPreferencesDialog: {
+        props: childrenProps,
+    },
+    AdwPreferencesWindow: {
+        props: childrenProps,
+    },
+    AdwPreferencesGroup: {
+        props: childrenProps,
+    },
+    AdwSqueezer: {
+        props: childrenProps,
+    },
+    AdwTabView: {
+        props: childrenProps,
+    },
+    AdwNavigationView: {
+        props: childrenProps,
+    },
+    AdwViewStack: {
+        props: childrenProps,
+    },
+    AdwToolbarView: {
+        props: adw("AdwToolbarViewProps"),
+    },
+    AdwHeaderBar: {
+        props: internal("GtkHeaderBarProps"),
+    },
+    AdwShortcutsDialog: {
+        props: childrenProps,
+    },
+    AdwShortcutsSection: {
+        props: childrenProps,
+    },
+    AdwToggleGroup: {
+        props: childrenProps,
+    },
+    AdwAlertDialog: {
+        props: adw("AdwAlertDialogProps"),
+    },
+};
+
+function adw(name: string): ModuleExport {
+    return { module: "@gtkx/react/adw", export: name };
+}
+
+export { BUILTIN_ELEMENTS };

package/src/adw/index.ts

@@ -0,0 +1,4 @@
+import "./element-behaviors.js";
+
+export { createDialogComponent } from "./dialog.js";
+export type * from "./prop-types.js";

package/src/adw/prop-types.ts

@@ -0,0 +1,42 @@
+import type * as Adw from "@gtkx/gi/adw";
+import type { ReactNode } from "react";
+import type { ChildrenProps } from "../prop-types.js";
+
+type AlertDialogResponse = {
+    id: string;
+    label: string;
+    appearance?: Adw.ResponseAppearance;
+    enabled?: boolean;
+};
+
+type AdwAlertDialogProps = {
+    responses?: AlertDialogResponse[] | null | undefined;
+} & ChildrenProps;
+
+type AdwPreferencesRowProps = {
+    prefix?: ReactNode | null | undefined;
+    suffix?: ReactNode | null | undefined;
+};
+
+type AdwExpanderRowProps = {
+    rows?: ReactNode | null | undefined;
+    actions?: ReactNode | null | undefined;
+} & AdwPreferencesRowProps;
+
+type AdwToolbarViewProps = {
+    topBar?: ReactNode | null | undefined;
+    bottomBar?: ReactNode | null | undefined;
+} & ChildrenProps;
+
+type AdwBreakpointsProps = {
+    breakpoints?: ReactNode | null | undefined;
+} & ChildrenProps;
+
+export {
+    type AlertDialogResponse,
+    type AdwAlertDialogProps,
+    type AdwPreferencesRowProps,
+    type AdwExpanderRowProps,
+    type AdwToolbarViewProps,
+    type AdwBreakpointsProps,
+};

package/src/bootstrap.ts

@@ -0,0 +1,5 @@
+import { elements } from "virtual:gtkx-config";
+import "./element-behaviors.js";
+import { registerElements } from "./reconciler/registry.js";
+
+registerElements(elements, { prepend: true });

package/src/components/application.tsx

@@ -0,0 +1,62 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import { quitApplication, runApplication } from "@gtkx/runtime";
+import { pickBy } from "@gtkx/utils";
+import { type ElementType, type ReactNode, type Ref, useLayoutEffect, useState } from "react";
+import { applicationId as defaultApplicationId } from "virtual:gtkx-config";
+import { ApplicationContext } from "../hooks/use-application.js";
+import { useMergedRef } from "../hooks/use-merged-refs.js";
+
+type ApplicationComponentProps = {
+    applicationId?: string | null | undefined;
+    children?: ReactNode | undefined;
+    ref?: Ref<Gtk.Application | null> | undefined;
+};
+
+const POST_ACTIVATE_PROPS = new Set(["menubar"]);
+
+const useApplicationLifecycle = (
+    application: Gtk.Application | null,
+    setActivated: (isActivated: boolean) => void,
+): void => {
+    useLayoutEffect(() => {
+        if (!application) {
+            return;
+        }
+
+        runApplication(application);
+        setActivated(true);
+
+        return () => {
+            quitApplication(application);
+            setActivated(false);
+        };
+    }, [application, setActivated]);
+};
+
+const applicationChildren = (application: Gtk.Application | null, children: ReactNode): ReactNode => {
+    if (!application) {
+        return null;
+    }
+
+    return <ApplicationContext.Provider value={application}>{children}</ApplicationContext.Provider>;
+};
+
+const createApplicationComponent = (
+    Component: ElementType,
+): ((props: ApplicationComponentProps) => ReactNode) => {
+    return ({ applicationId = defaultApplicationId, children, ref, ...rest }: ApplicationComponentProps): ReactNode => {
+        const [application, setApplication] = useState<Gtk.Application | null>(null);
+        const [activated, setActivated] = useState(false);
+        useApplicationLifecycle(application, setActivated);
+        const mergedRef = useMergedRef(ref, setApplication);
+        const appliedProps = activated ? rest : pickBy(rest, (_value, key) => !POST_ACTIVATE_PROPS.has(key));
+
+        return (
+            <Component ref={mergedRef} applicationId={applicationId} {...appliedProps}>
+                {activated ? applicationChildren(application, children) : null}
+            </Component>
+        );
+    };
+};
+
+export { createApplicationComponent };

package/src/components/element.tsx

@@ -0,0 +1,47 @@
+import { isRecord } from "@gtkx/utils";
+import { createElement, type ElementType, isValidElement, type ReactElement, type ReactNode } from "react";
+import type { Props } from "../reconciler/registry.js";
+
+/** The intrinsic element that carries an object-valued prop's element into its parent's named property. */
+const Prop = "gtkx:prop";
+
+const hasElement = (value: unknown): boolean =>
+    isValidElement(value) || (Array.isArray(value) && value.some((item: unknown) => hasElement(item)));
+
+const routeProp = (key: string, value: unknown, hostProps: Props, propChildren: ReactNode[]): void => {
+    if (key !== "ref" && hasElement(value)) {
+        propChildren.push(
+            createElement(Prop, { propName: key, key: `${Prop}:${key}` }, value as ReactNode),
+        );
+    } else {
+        hostProps[key] = value;
+    }
+};
+
+const buildElement = (typeName: string, record: Props): ReactElement => {
+    const Host = typeName as ElementType;
+    const hostProps: Props = {};
+    const propChildren: ReactNode[] = [];
+
+    for (const key in record) {
+        if (key === "children") {
+            continue;
+        }
+
+        routeProp(key, record[key], hostProps, propChildren);
+    }
+
+    return (
+        <Host {...hostProps}>
+            {propChildren}
+            {record.children as ReactNode}
+        </Host>
+    );
+};
+
+const createElementComponent =
+    (typeName: string): ((props: unknown) => ReactNode) =>
+        (props: unknown): ReactNode =>
+            buildElement(typeName, isRecord(props) ? props : {});
+
+export { Prop, createElementComponent };