@gtkx/react 0.9.4 → 0.10.0

package/dist/jsx.js

@@ -0,0 +1,392 @@
+import { createElement } from "react";
+/**
+ * Type-safe slot component for placing children in named widget slots.
+ *
+ * GTK widgets often have named slots for specific child positions (e.g., titleWidget,
+ * startWidget). This component provides type-safe access to those slots.
+ *
+ * @typeParam W - The widget type containing the slot
+ *
+ * @param props.for - The widget component type (used for type inference)
+ * @param props.id - The slot identifier (type-checked against available slots)
+ * @param props.children - Content to place in the slot
+ *
+ * @example
+ * ```tsx
+ * <GtkHeaderBar>
+ *   <Slot for={GtkHeaderBar} id="titleWidget">
+ *     <GtkLabel label="App Title" />
+ *   </Slot>
+ * </GtkHeaderBar>
+ * ```
+ *
+ * @internal
+ */
+export function Slot(props) {
+    return createElement("Slot", { id: props.id }, props.children);
+}
+/**
+ * Element type for pages within a GtkStack or AdwViewStack.
+ *
+ * @example
+ * ```tsx
+ * <GtkStack>
+ *   <StackPage name="page1" title="First Page">
+ *     <GtkLabel label="Content 1" />
+ *   </StackPage>
+ *   <StackPage name="page2" title="Second Page">
+ *     <GtkLabel label="Content 2" />
+ *   </StackPage>
+ * </GtkStack>
+ * ```
+ */
+export const StackPage = "StackPage";
+/**
+ * Element type for positioning children within a GtkGrid.
+ *
+ * @example
+ * ```tsx
+ * <GtkGrid>
+ *   <GridChild column={0} row={0}>
+ *     <GtkLabel label="Top Left" />
+ *   </GridChild>
+ *   <GridChild column={1} row={0} columnSpan={2}>
+ *     <GtkLabel label="Spans 2 columns" />
+ *   </GridChild>
+ * </GtkGrid>
+ * ```
+ */
+export const GridChild = "GridChild";
+/**
+ * Element type for positioning children within a GtkFixed.
+ *
+ * @example
+ * ```tsx
+ * <GtkFixed>
+ *   <FixedChild x={20} y={30}>
+ *     <GtkLabel label="Positioned at (20, 30)" />
+ *   </FixedChild>
+ *   <FixedChild x={100} y={50}>
+ *     <GtkButton label="At (100, 50)" />
+ *   </FixedChild>
+ * </GtkFixed>
+ * ```
+ */
+export const FixedChild = "FixedChild";
+/**
+ * Element type for declarative toast notifications within an AdwToastOverlay.
+ *
+ * When mounted, shows the toast. When unmounted, the toast auto-dismisses.
+ * Toasts can have an optional action button and callbacks.
+ *
+ * @example
+ * ```tsx
+ * <AdwToastOverlay>
+ *   <MyContent />
+ *   {showToast && (
+ *     <Toast
+ *       title="File saved"
+ *       timeout={3}
+ *       buttonLabel="Undo"
+ *       onButtonClicked={handleUndo}
+ *       onDismissed={() => setShowToast(false)}
+ *     />
+ *   )}
+ * </AdwToastOverlay>
+ * ```
+ */
+export const Toast = "Toast";
+/**
+ * Element types for pages within a GtkNotebook (tabbed interface).
+ *
+ * @example Simple text tabs
+ * ```tsx
+ * <GtkNotebook>
+ *   <Notebook.Page label="Tab 1">
+ *     <GtkLabel label="Content 1" />
+ *   </Notebook.Page>
+ *   <Notebook.Page label="Tab 2">
+ *     <GtkLabel label="Content 2" />
+ *   </Notebook.Page>
+ * </GtkNotebook>
+ * ```
+ *
+ * @example Custom tab widgets
+ * ```tsx
+ * <GtkNotebook>
+ *   <Notebook.Page>
+ *     <Notebook.PageTab>
+ *       <GtkBox orientation={Gtk.Orientation.HORIZONTAL}>
+ *         <GtkImage iconName="folder-symbolic" />
+ *         <GtkLabel label="Files" />
+ *       </GtkBox>
+ *     </Notebook.PageTab>
+ *     <GtkLabel label="Content" />
+ *   </Notebook.Page>
+ * </GtkNotebook>
+ * ```
+ */
+export const Notebook = {
+    /** A page within the notebook */
+    Page: "Notebook.Page",
+    /** Custom widget for the page tab label */
+    PageTab: "Notebook.PageTab",
+};
+/**
+ * Element type for items in a ListView or GridView.
+ *
+ * @example
+ * ```tsx
+ * <ListView renderItem={(item) => <GtkLabel label={item.name} />}>
+ *   <ListItem id="1" value={{ name: "Item 1" }} />
+ *   <ListItem id="2" value={{ name: "Item 2" }} />
+ * </ListView>
+ * ```
+ */
+export const ListItem = "ListItem";
+/**
+ * Component for defining columns in a ColumnView (table widget).
+ *
+ * @typeParam T - The type of row data
+ *
+ * @example
+ * ```tsx
+ * <GtkColumnView>
+ *   <ColumnViewColumn
+ *     id="name"
+ *     title="Name"
+ *     expand
+ *     renderCell={(item) => <GtkLabel label={item?.name ?? ""} />}
+ *   />
+ *   <ColumnViewColumn
+ *     id="status"
+ *     title="Status"
+ *     renderCell={(item) => <GtkLabel label={item?.status ?? ""} />}
+ *   />
+ * </GtkColumnView>
+ * ```
+ *
+ * @internal
+ */
+export function ColumnViewColumn(props) {
+    return createElement("ColumnViewColumn", props);
+}
+/**
+ * Virtualized list component with custom item rendering.
+ *
+ * Efficiently renders large lists by only creating widgets for visible items.
+ *
+ * @typeParam T - The type of items in the list
+ *
+ * @example
+ * ```tsx
+ * const items = [{ id: "1", name: "Apple" }, { id: "2", name: "Banana" }];
+ *
+ * <ListView renderItem={(item) => <GtkLabel label={item?.name ?? ""} />}>
+ *   {items.map((item) => (
+ *     <ListItem key={item.id} id={item.id} value={item} />
+ *   ))}
+ * </ListView>
+ * ```
+ *
+ * @internal
+ */
+export function ListView(props) {
+    return createElement("GtkListView", props);
+}
+/**
+ * Virtualized grid component with custom item rendering.
+ *
+ * Efficiently renders large grids by only creating widgets for visible items.
+ *
+ * @typeParam T - The type of items in the grid
+ *
+ * @example
+ * ```tsx
+ * <GridView renderItem={(item) => <GtkImage iconName={item?.icon ?? ""} />}>
+ *   {icons.map((icon) => (
+ *     <ListItem key={icon.id} id={icon.id} value={icon} />
+ *   ))}
+ * </GridView>
+ * ```
+ *
+ * @internal
+ */
+export function GridView(props) {
+    return createElement("GtkGridView", props);
+}
+/**
+ * Tree list component with hierarchical data and expand/collapse support.
+ *
+ * Renders a tree structure with expandable/collapsible rows using GTK's TreeListModel.
+ * Items are defined declaratively by nesting TreeListItem components.
+ *
+ * @typeParam T - The type of items in the tree
+ *
+ * @example
+ * ```tsx
+ * interface Category { name: string; }
+ * interface Setting { key: string; value: string; }
+ *
+ * <TreeListView<Category | Setting>
+ *   renderItem={(item, row) => (
+ *     <GtkLabel label={'name' in item ? item.name : item.key} />
+ *   )}
+ * >
+ *   {categories.map(cat => (
+ *     <TreeListItem key={cat.name} id={cat.name} value={cat}>
+ *       {cat.settings?.map(setting => (
+ *         <TreeListItem key={setting.key} id={setting.key} value={setting} />
+ *       ))}
+ *     </TreeListItem>
+ *   ))}
+ * </TreeListView>
+ * ```
+ *
+ * @internal
+ */
+export function TreeListView(props) {
+    return createElement("TreeListView", props);
+}
+/**
+ * Element type for items in a TreeListView.
+ *
+ * Nesting TreeListItem components defines the tree hierarchy.
+ *
+ * @example
+ * ```tsx
+ * <TreeListView renderItem={(item) => <GtkLabel label={item.name} />}>
+ *   <TreeListItem id="parent" value={{ name: "Parent" }}>
+ *     <TreeListItem id="child1" value={{ name: "Child 1" }} />
+ *     <TreeListItem id="child2" value={{ name: "Child 2" }} />
+ *   </TreeListItem>
+ * </TreeListView>
+ * ```
+ */
+export const TreeListItem = "TreeListItem";
+/**
+ * Element type for simple string-based list items.
+ *
+ * Use when list items only need string values without complex data.
+ *
+ * @example
+ * ```tsx
+ * <GtkDropDown>
+ *   <SimpleListItem id="opt1" value="Option 1" />
+ *   <SimpleListItem id="opt2" value="Option 2" />
+ * </GtkDropDown>
+ * ```
+ */
+export const SimpleListItem = "SimpleListItem";
+/**
+ * Slot positions for AdwActionRow, AdwEntryRow, and AdwExpanderRow widgets.
+ *
+ * @example
+ * ```tsx
+ * <AdwActionRow title="Setting">
+ *   <ActionRow.Prefix>
+ *     <GtkCheckButton />
+ *   </ActionRow.Prefix>
+ *   <ActionRow.Suffix>
+ *     <GtkButton iconName="go-next-symbolic" />
+ *   </ActionRow.Suffix>
+ * </AdwActionRow>
+ * ```
+ */
+export const ActionRow = {
+    /** Place child as a prefix (left side) of the row */
+    Prefix: "ActionRow.Prefix",
+    /** Place child as a suffix (right side) of the row */
+    Suffix: "ActionRow.Suffix",
+};
+/**
+ * Slot positions for HeaderBar and ActionBar widgets.
+ *
+ * @example
+ * ```tsx
+ * <GtkHeaderBar>
+ *   <Pack.Start>
+ *     <GtkButton label="Back" />
+ *   </Pack.Start>
+ *   <Pack.End>
+ *     <GtkMenuButton />
+ *   </Pack.End>
+ * </GtkHeaderBar>
+ * ```
+ */
+export const Pack = {
+    /** Place child at the start (left in LTR) of the bar */
+    Start: "Pack.Start",
+    /** Place child at the end (right in LTR) of the bar */
+    End: "Pack.End",
+};
+/**
+ * Slot positions for AdwToolbarView.
+ *
+ * @example
+ * ```tsx
+ * <AdwToolbarView>
+ *   <Toolbar.Top>
+ *     <AdwHeaderBar />
+ *   </Toolbar.Top>
+ *   <GtkLabel label="Content" />
+ *   <Toolbar.Bottom>
+ *     <GtkActionBar />
+ *   </Toolbar.Bottom>
+ * </AdwToolbarView>
+ * ```
+ */
+export const Toolbar = {
+    /** Place toolbar at the top */
+    Top: "Toolbar.Top",
+    /** Place toolbar at the bottom */
+    Bottom: "Toolbar.Bottom",
+};
+/**
+ * Element type for GtkOverlay main child container.
+ */
+export const Overlay = "Overlay";
+/**
+ * Element type for overlay children positioned above the main content.
+ *
+ * @example
+ * ```tsx
+ * <GtkOverlay>
+ *   <Overlay>
+ *     <GtkImage file="background.png" />
+ *   </Overlay>
+ *   <OverlayChild>
+ *     <GtkLabel label="Overlaid text" cssClasses={["title-1"]} />
+ *   </OverlayChild>
+ * </GtkOverlay>
+ * ```
+ */
+export const OverlayChild = "OverlayChild";
+/**
+ * Element types for declarative menu construction.
+ *
+ * Build menus with items, sections, and submenus declaratively.
+ *
+ * @example
+ * ```tsx
+ * <GtkMenuButton>
+ *   <Menu.Section>
+ *     <Menu.Item id="open" label="Open" onActivate={handleOpen} accels="<Control>o" />
+ *     <Menu.Item id="save" label="Save" onActivate={handleSave} accels="<Control>s" />
+ *   </Menu.Section>
+ *   <Menu.Submenu label="Export">
+ *     <Menu.Item id="pdf" label="As PDF" onActivate={exportPdf} />
+ *     <Menu.Item id="png" label="As PNG" onActivate={exportPng} />
+ *   </Menu.Submenu>
+ * </GtkMenuButton>
+ * ```
+ */
+export const Menu = {
+    /** A clickable menu item with action */
+    Item: "Menu.Item",
+    /** A section grouping related menu items */
+    Section: "Menu.Section",
+    /** A submenu containing nested items */
+    Submenu: "Menu.Submenu",
+};
+export * from "./generated/jsx.js";

package/dist/node.d.ts

@@ -1,34 +1,17 @@
-import * as Gtk from "@gtkx/ffi/gtk";
-import type { Props, ROOT_NODE_CONTAINER } from "./factory.js";
-export declare const normalizeWidgetType: (type: string) => string;
-export declare abstract class Node<T extends Gtk.Widget | undefined = Gtk.Widget | undefined, S extends object | undefined = object | undefined> {
-    static matches(_type: string, _widget?: Gtk.Widget | typeof ROOT_NODE_CONTAINER): boolean;
-    static consumedPropNames: string[];
-    protected signalHandlers: Map<string, number>;
-    protected widget: T;
-    protected widgetType: string;
-    protected nodeType: string;
-    parent: Node | null;
-    private _state;
-    protected get state(): S;
-    protected set state(value: S);
-    protected isVirtual(): boolean;
-    protected isStandalone(): boolean;
-    constructor(type: string, widget?: Gtk.Widget);
-    initialize(props: Props): void;
-    protected createWidget(type: string, props: Props): T;
-    getWidget(): T;
-    appendChild(child: Node): void;
-    removeChild(child: Node): void;
-    insertBefore(child: Node, before: Node): void;
-    unmount(): void;
-    protected disconnectAllSignals(): void;
-    hasParent(): boolean;
-    protected consumedProps(): Set<string>;
-    updateProps(oldProps: Props, newProps: Props): void;
-    protected propKeyToEventName(key: string): string;
-    protected disconnectSignal(eventName: string): void;
-    protected connectSignal(widget: Gtk.Widget, eventName: string, handler: (...args: unknown[]) => unknown): void;
-    protected setProperty(widget: Gtk.Widget, key: string, value: unknown): void;
+import { SignalStore } from "./nodes/internal/signal-store.js";
+import type { Container, ContainerClass, Props } from "./types.js";
+export declare class Node<T = unknown, P = Props> {
+    static priority: number;
+    static matches(_type: string, _containerOrClass?: Container | ContainerClass): boolean;
+    static createContainer(_props: Props, _containerClass: ContainerClass, _rootContainer?: Container): unknown;
+    container: T;
+    typeName: string;
+    protected signalStore: SignalStore;
+    constructor(typeName: string, _props: P | undefined, container: T, _rootContainer?: Container);
+    appendChild(_child: Node): void;
+    removeChild(_child: Node): void;
+    insertBefore(_child: Node, _before: Node): void;
+    updateProps(_oldProps: P | null, _newProps: P): void;
     mount(): void;
+    unmount(): void;
 }