@gtkx/react 1.0.0-rc.3 → 1.0.0

package/src/adw/element-config.ts

@@ -3,7 +3,6 @@ import { type ElementConfig, forTypes, internal, type ModuleExport } from "../re
 const CHILD_SETTER_TYPES: string[] = [
     "AdwBin",
     "AdwClamp",
-    "AdwClampScrollable",
     "AdwNavigationPage",
     "AdwSplitButton",
     "AdwStatusPage",
@@ -12,30 +11,38 @@ const CHILD_SETTER_TYPES: string[] = [
     "AdwToggle",
 ];
 
-const CONTENT_SETTER_TYPES: string[] = ["AdwBottomSheet", "AdwFlap", "AdwOverlaySplitView"];
+const CONTENT_SETTER_TYPES: string[] = ["AdwBottomSheet", "AdwOverlaySplitView"];
 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> = {
     ...forTypes(CHILD_SETTER_TYPES, {
         props: childrenProps,
-        omitProps: ["child"],
+        omittedProps: ["child"],
     }),
     ...forTypes(CONTENT_SETTER_TYPES, {
         props: childrenProps,
-        omitProps: ["content"],
+        omittedProps: ["content"],
     }),
+    AdwClampScrollable: {
+        props: childrenProps,
+        omittedProps: ["child"],
+    },
     AdwViewStackPage: {
-        lazy: true,
+        isLazy: true,
     },
     AdwTabPage: {
-        lazy: true,
+        isLazy: true,
+    },
+    AdwLayout: {
+        isLazy: true,
+    },
+    AdwSidebarSection: {
+        props: childrenProps,
+    },
+    AdwMultiLayoutView: {
+        props: adw("AdwMultiLayoutViewProps"),
     },
     AdwPreferencesRow: {
         props: preferencesRowProps,
@@ -43,19 +50,19 @@ const BUILTIN_ELEMENTS: Record<string, ElementConfig> = {
     AdwDialog: {
         props: breakpointsProps,
         component: adw("createDialogComponent"),
-        omitProps: ["child"],
+        omittedProps: ["child"],
     },
     AdwApplicationWindow: {
         props: breakpointsProps,
-        omitProps: ["content"],
+        omittedProps: ["content"],
     },
     AdwWindow: {
         props: breakpointsProps,
-        omitProps: ["content"],
+        omittedProps: ["content"],
     },
     AdwBreakpointBin: {
         props: breakpointsProps,
-        omitProps: ["child"],
+        omittedProps: ["child"],
     },
     AdwActionRow: {
         props: preferencesRowProps,
@@ -68,10 +75,7 @@ const BUILTIN_ELEMENTS: Record<string, ElementConfig> = {
     },
     AdwNavigationSplitView: {
         props: childrenProps,
-        omitProps: ["content"],
-    },
-    AdwLeaflet: {
-        props: childrenProps,
+        omittedProps: ["content"],
     },
     AdwWrapBox: {
         props: childrenProps,
@@ -85,15 +89,9 @@ const BUILTIN_ELEMENTS: Record<string, ElementConfig> = {
     AdwPreferencesDialog: {
         props: childrenProps,
     },
-    AdwPreferencesWindow: {
-        props: childrenProps,
-    },
     AdwPreferencesGroup: {
         props: childrenProps,
     },
-    AdwSqueezer: {
-        props: childrenProps,
-    },
     AdwTabView: {
         props: childrenProps,
     },
@@ -105,7 +103,7 @@ const BUILTIN_ELEMENTS: Record<string, ElementConfig> = {
     },
     AdwToolbarView: {
         props: adw("AdwToolbarViewProps"),
-        omitProps: ["content"],
+        omittedProps: ["content"],
     },
     AdwHeaderBar: {
         props: internal("GtkHeaderBarProps"),
@@ -121,6 +119,7 @@ const BUILTIN_ELEMENTS: Record<string, ElementConfig> = {
     },
     AdwAlertDialog: {
         props: adw("AdwAlertDialogProps"),
+        omittedProps: ["extraChild"],
     },
 };
 

package/src/adw/index.ts

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

package/src/adw/prop-types.ts

@@ -2,36 +2,68 @@ import type * as Adw from "@gtkx/gi/adw";
 import type { ReactNode } from "react";
 import type { ChildrenProps } from "../prop-types.js";
 
+/** One button in an `Adw.AlertDialog`'s `responses` prop. */
 type AlertDialogResponse = {
+    /** Name the dialog reports on `onResponse` when this button is chosen. */
     id: string;
+    /** Text shown on the button. */
     label: string;
+    /** Styling the button is given, such as suggested or destructive; defaults to the plain appearance. */
     appearance?: Adw.ResponseAppearance;
-    enabled?: boolean;
+    /** Whether the button can be activated; defaults to true. */
+    isEnabled?: boolean;
 };
 
+/** Props of an `Adw.AlertDialog` element. */
 type AdwAlertDialogProps = {
+    /** Buttons the dialog offers, added and removed as the list changes. */
     responses?: AlertDialogResponse[] | null | undefined;
-} & ChildrenProps;
+    /**
+     * Widget set as the dialog's extra child, shown below the `heading` and `body` and above the
+     * response buttons, leaving the dialog's own chrome in place.
+     */
+    children?: ReactNode;
+};
 
+/** Props of an `Adw.PreferencesRow` element. */
 type AdwPreferencesRowProps = {
+    /** Widgets added at the start of the row, before its title. */
     prefix?: ReactNode | null | undefined;
+    /** Widgets added at the end of the row. */
     suffix?: ReactNode | null | undefined;
 };
 
+/** Props of an `Adw.ExpanderRow` element. */
 type AdwExpanderRowProps = {
+    /** Widgets added to the area the row reveals when it expands. */
     rows?: ReactNode | null | undefined;
-    actions?: ReactNode | null | undefined;
 } & AdwPreferencesRowProps;
 
+/** Props of an `Adw.ToolbarView` element, whose `children` is the content the bars surround. */
 type AdwToolbarViewProps = {
+    /** Widgets stacked above the content. */
     topBar?: ReactNode | null | undefined;
+    /** Widgets stacked below the content. */
     bottomBar?: ReactNode | null | undefined;
 } & ChildrenProps;
 
+/** Props of an element that hosts breakpoints, such as `Adw.Window` or `Adw.BreakpointBin`. */
 type AdwBreakpointsProps = {
+    /** `Adw.Breakpoint` elements added to the element, each applying while its condition holds. */
     breakpoints?: ReactNode | null | undefined;
 } & ChildrenProps;
 
+/** Props of an `Adw.MultiLayoutView` element. */
+type AdwMultiLayoutViewProps = {
+    /** `Adw.Layout` elements added to the view, each holding the content it lays out. */
+    layouts?: ReactNode | null | undefined;
+    /**
+     * Widget the view places in the `Adw.LayoutSlot` whose `id` is the prop name without its `Slot`
+     * suffix, so `sidebarSlot` fills the slot with id `sidebar` in whichever layout is current.
+     */
+    [slot: `${string}Slot`]: ReactNode | null | undefined;
+};
+
 export {
     type AlertDialogResponse,
     type AdwAlertDialogProps,
@@ -39,4 +71,5 @@ export {
     type AdwExpanderRowProps,
     type AdwToolbarViewProps,
     type AdwBreakpointsProps,
+    type AdwMultiLayoutViewProps,
 };

package/src/bootstrap.ts

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

package/src/components/application-window.tsx

@@ -0,0 +1,10 @@
+import type { ElementType, ReactNode } from "react";
+import { useApplication } from "../hooks/use-application.js";
+import { createPortaledComponent } from "./portaled.js";
+import { createPresentedWindowComponent } from "./window.js";
+
+const createApplicationWindowComponent = (Component: ElementType): ((props: unknown) => ReactNode) =>
+    createPortaledComponent(createPresentedWindowComponent(Component), useApplication);
+
+/** @internal */
+export { createApplicationWindowComponent };

package/src/components/application.tsx

@@ -1,10 +1,12 @@
 import type * as Gtk from "@gtkx/gi/gtk";
 import { quitApplication, runApplication } from "@gtkx/runtime";
 import { pickBy } from "@gtkx/utils";
+import process from "node:process";
 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";
+import { createPortaledComponent } from "./portaled.js";
 
 type ApplicationComponentProps = {
     applicationId?: string | null | undefined;
@@ -14,23 +16,44 @@ type ApplicationComponentProps = {
 
 const POST_ACTIVATE_PROPS = new Set(["menubar"]);
 
+const commandLine = (applicationId: string | null): string[] => [
+    applicationId?.split(".").at(-1) ?? "gtkx",
+    ...process.argv.slice(2),
+];
+
+const startApplication = (
+    application: Gtk.Application,
+    setActivated: (isActivated: boolean) => void,
+    applicationId: string | null,
+): void => {
+    application.on("activate", () => {
+        setActivated(true);
+    });
+
+    const { exitStatus } = runApplication(application, commandLine(applicationId));
+
+    if (exitStatus !== 0) {
+        process.exitCode = exitStatus;
+    }
+};
+
 const useApplicationLifecycle = (
     application: Gtk.Application | null,
     setActivated: (isActivated: boolean) => void,
+    applicationId: string | null,
 ): void => {
     useLayoutEffect(() => {
         if (!application) {
             return;
         }
 
-        runApplication(application);
-        setActivated(true);
+        startApplication(application, setActivated, applicationId);
 
         return () => {
             quitApplication(application);
             setActivated(false);
         };
-    }, [application, setActivated]);
+    }, [application, setActivated, applicationId]);
 };
 
 const applicationChildren = (application: Gtk.Application | null, children: ReactNode): ReactNode => {
@@ -41,13 +64,13 @@ const applicationChildren = (application: Gtk.Application | null, children: Reac
     return <ApplicationContext.Provider value={application}>{children}</ApplicationContext.Provider>;
 };
 
-const createApplicationComponent = (
+const createApplicationElement = (
     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);
+        useApplicationLifecycle(application, setActivated, applicationId);
         const mergedRef = useMergedRef(ref, setApplication);
         const appliedProps = activated ? rest : pickBy(rest, (_value, key) => !POST_ACTIVATE_PROPS.has(key));
 
@@ -59,4 +82,8 @@ const createApplicationComponent = (
     };
 };
 
+const createApplicationComponent = (Component: ElementType): ((props: unknown) => ReactNode) =>
+    createPortaledComponent(createApplicationElement(Component));
+
+/** @internal */
 export { createApplicationComponent };

package/src/components/element.tsx

@@ -2,46 +2,81 @@ 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 NO_PROP_CHILDREN: ReactNode[] = [];
 
 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)) {
+const isRoutedProp = (key: string, value: unknown): boolean =>
+    key !== "children" && key !== "ref" && hasElement(value);
+
+const collectPropChildren = (record: Props): ReactNode[] | null => {
+    let propChildren: ReactNode[] | null = null;
+
+    for (const key in record) {
+        if (!isRoutedProp(key, record[key])) {
+            continue;
+        }
+
+        propChildren ??= [];
+
         propChildren.push(
-            createElement(Prop, { propName: key, key: `${Prop}:${key}` }, value as ReactNode),
+            createElement(Prop, { propName: key, key: `${Prop}:${key}` }, record[key] as ReactNode),
         );
-    } else {
-        hostProps[key] = value;
     }
+
+    return propChildren;
 };
 
-const buildElement = (typeName: string, record: Props): ReactElement => {
-    const Host = typeName as ElementType;
+const hostPropsWithout = (record: Props): Props => {
     const hostProps: Props = {};
-    const propChildren: ReactNode[] = [];
 
     for (const key in record) {
-        if (key === "children") {
-            continue;
+        if (key !== "children" && !isRoutedProp(key, record[key])) {
+            hostProps[key] = record[key];
         }
+    }
+
+    return hostProps;
+};
 
-        routeProp(key, record[key], hostProps, propChildren);
+const buildElement = (typeName: string, record: Props): ReactElement => {
+    const Host = typeName as ElementType;
+    const propChildren = collectPropChildren(record);
+
+    if (propChildren === null) {
+        return (
+            <Host {...record}>
+                {NO_PROP_CHILDREN}
+                {record.children as ReactNode}
+            </Host>
+        );
     }
 
     return (
-        <Host {...hostProps}>
+        <Host {...hostPropsWithout(record)}>
             {propChildren}
             {record.children as ReactNode}
         </Host>
     );
 };
 
-const createElementComponent =
-    (typeName: string): ((props: unknown) => ReactNode) =>
-        (props: unknown): ReactNode =>
-            buildElement(typeName, isRecord(props) ? props : {});
+/**
+ * Builds the component that renders the element of a GLib type, which is how the generated `@gtkx/jsx`
+ * store exposes every widget. Reach for it to render a type codegen does not cover, such as one
+ * `registerClass` created: the element name is the GType name, and the component routes each prop whose
+ * value is an element into that prop's slot, which a bare intrinsic element cannot do.
+ *
+ * Name the props the element takes as the type argument, since the GType name says nothing about them.
+ * Left out, the component takes `unknown`, which accepts no attributes at all.
+ *
+ * @param typeName GType name to render, such as `GtkButton` or the `typeName` given to `registerClass`.
+ * @returns A component taking that type's props.
+ */
+/* eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters -- callers name the props */
+function createElementComponent<P = unknown>(typeName: string): (props: P) => ReactNode {
+    return (props: P): ReactNode => buildElement(typeName, isRecord(props) ? props : {});
+}
 
 export { Prop, createElementComponent };

package/src/components/portaled.tsx

@@ -0,0 +1,14 @@
+import type { ElementType, ReactNode } from "react";
+import { isRecord } from "@gtkx/utils";
+import type { Container } from "../reconciler/host-config.js";
+import { rootElement } from "../reconciler/root-element.js";
+import { createPortal } from "../reconciler/root.js";
+
+const useRootContainer = (): Container => rootElement;
+
+const createPortaledComponent =
+    (Component: ElementType, useContainer: () => Container = useRootContainer): ((props: unknown) => ReactNode) =>
+        (props: unknown): ReactNode =>
+            createPortal(<Component {...(isRecord(props) ? props : {})} />, useContainer());
+
+export { createPortaledComponent };

package/src/components/window.tsx

@@ -1,11 +1,13 @@
 import type * as Gtk from "@gtkx/gi/gtk";
-import { type ElementType, type ReactNode, type Ref, useLayoutEffect, useState } from "react";
-import { useMergedRef } from "../hooks/use-merged-refs.js";
+import { type ElementType, type ReactElement, type ReactNode, use } from "react";
 import { ParentWindowContext } from "../hooks/use-parent-window.js";
+import { createPresentedComponent, type PresentedProps } from "../hooks/use-presented-instance.js";
 import { applyWrite } from "../reconciler/signals.js";
+import { createPortaledComponent } from "./portaled.js";
 
-type WindowComponentProps = {
-    ref?: Ref<Gtk.Window | null> | undefined;
+type WindowComponentProps = PresentedProps<Gtk.Window> & {
+    // eslint-disable-next-line gtkx/accessor-naming
+    transientFor?: Gtk.Window | ReactElement | null | undefined;
 };
 
 const presentWindow = (window: Gtk.Window): void => {
@@ -20,29 +22,29 @@ const destroyWindow = (window: Gtk.Window): void => {
     });
 };
 
-const createWindowComponent = (Component: ElementType): ((props: WindowComponentProps) => ReactNode) => {
-    return ({ ref, ...rest }: WindowComponentProps): ReactNode => {
-        const [window, setWindow] = useState<Gtk.Window | null>(null);
-        const mergedRef = useMergedRef(ref, setWindow);
+const usePresentWindow = (): ((window: Gtk.Window) => void) => presentWindow;
 
-        useLayoutEffect(() => {
-            if (!window) {
-                return;
-            }
-
-            presentWindow(window);
+const createPresentedWindowComponent = (Component: ElementType): ((props: PresentedProps<Gtk.Window>) => ReactNode) =>
+    createPresentedComponent<Gtk.Window>(Component, {
+        usePresent: usePresentWindow,
+        dismiss: destroyWindow,
+        wrap: (element, window) => (
+            <ParentWindowContext.Provider value={window}>{element}</ParentWindowContext.Provider>
+        ),
+    });
 
-            return () => {
-                destroyWindow(window);
-            };
-        }, [window]);
+const withDefaultTransientFor = (Component: ElementType): ((props: WindowComponentProps) => ReactNode) => {
+    return (props: WindowComponentProps): ReactNode => {
+        const parent = use(ParentWindowContext);
+        const isDefaulted = props.transientFor === undefined && parent !== null;
 
-        return (
-            <ParentWindowContext.Provider value={window}>
-                <Component ref={mergedRef} {...rest} />
-            </ParentWindowContext.Provider>
-        );
+        return <Component {...(isDefaulted ? { ...props, transientFor: parent } : props)} />;
     };
 };
 
+const createWindowComponent = (Component: ElementType): ((props: unknown) => ReactNode) =>
+    createPortaledComponent(withDefaultTransientFor(createPresentedWindowComponent(Component)));
+
+export { createPresentedWindowComponent };
+/** @internal */
 export { createWindowComponent };

package/src/config.ts

@@ -1,10 +1,15 @@
+/** @public */
+export { createElementComponent } from "./components/element.js";
+/** @public */
 export { BUILTIN_ELEMENTS } from "./element-config.js";
-export type { DetachInfo, ElementBehavior, ElementConfig, ModuleExport, PlaceInfo } from "./reconciler/registry.js";
-export {
-    defineBehavior,
-    defineElements,
-    ELEMENTS,
-    forTypes,
-    internal,
-    mergeElementConfigs,
+/** @public */
+export type {
+    DetachInfo,
+    ElementBehavior,
+    ElementConfig,
+    ModuleExport,
+    PlaceInfo,
+    Props,
 } from "./reconciler/registry.js";
+/** @public */
+export { defineBehavior, defineElements, ELEMENTS, mergeElementConfigs } from "./reconciler/registry.js";

package/src/element-behaviors.ts

@@ -1,11 +1,13 @@
 import type * as GObject from "@gtkx/gi/gobject";
 import * as Gio from "@gtkx/gi/gio";
+import * as GLib from "@gtkx/gi/glib";
 import * as Gtk from "@gtkx/gi/gtk";
 import type {
     ActionAccel,
     CreditSection,
     DragSourceIcon,
     LevelBarOffset,
+    MainOption,
     MenuItem,
     ScaleMark,
     VflConstraints,
@@ -14,6 +16,7 @@ import { BUILTIN_ELEMENTS, SINGLE_CHILD_TYPES } from "./element-config.js";
 import {
     addRemoveSlot,
     adoptedChildrenSlot,
+    applicationCreator,
     boxSlot,
     childSetterSlot,
     controlledText,
@@ -25,7 +28,6 @@ import {
 } from "./reconciler/behaviors.js";
 import { type ElementConfig, forTypes, registerElements } from "./reconciler/registry.js";
 
-/** The runtime half of the built-in element configuration: the behaviors bound to each GObject type. */
 const BUILTIN_BEHAVIORS: Record<string, ElementConfig<never>> = {
     ...forTypes(SINGLE_CHILD_TYPES, {
         behaviors: [childSetterSlot()],
@@ -296,6 +298,7 @@ const BUILTIN_BEHAVIORS: Record<string, ElementConfig<never>> = {
     },
     GtkApplication: {
         behaviors: [
+            applicationCreator(Gtk.Application),
             addRemoveSlot<Gtk.Window, Gtk.Application>(
                 "children",
                 "GtkWindow",
@@ -314,6 +317,11 @@ const BUILTIN_BEHAVIORS: Record<string, ElementConfig<never>> = {
                     application.setAccelsForAction(item.detailedActionName, []);
                 },
             }),
+            list<Gtk.Application, MainOption>("mainOptions", {
+                add: (application, option) => {
+                    addMainOption(application, option);
+                },
+            }),
         ],
     },
     GtkAboutDialog: {
@@ -392,6 +400,17 @@ function layoutChild(parent: Gtk.Widget, child: Gtk.Widget): GObject.Object | nu
     return parent.getLayoutManager()?.getLayoutChild(child) ?? null;
 }
 
+const addMainOption = (application: Gtk.Application, option: MainOption): void => {
+    application.addMainOption(
+        option.longName,
+        option.shortName?.codePointAt(0) ?? 0,
+        option.flags ?? GLib.OptionFlags.NONE,
+        option.arg ?? GLib.OptionArg.NONE,
+        option.description,
+        option.argDescription ?? null,
+    );
+};
+
 const buildMenu = (items: MenuItem[]): Gio.Menu => {
     const menu = Gio.Menu.new();