@gjsify/react-native 0.43.0 → 0.45.0

package/lib/types/components.d.ts

@@ -1,6 +1,8 @@
 import { type ReactElement, type ReactNode, type Ref } from 'react';
 import type { ClassNameInput } from './primitives/classes.js';
+import { type ChildContext, type PrimitivePlan, type WidgetNode } from './primitives/resolve.js';
 import type { StyleInput } from './primitives/style.js';
+import type { StyleTokens } from '@gjsify/gtk-host/style';
 /** What every primitive accepts on top of its own props. */
 export interface CommonProps {
     className?: ClassNameInput;
@@ -10,6 +12,36 @@ export interface CommonProps {
     ref?: Ref<unknown>;
     testID?: string;
 }
+type AnyProps = Readonly<Record<string, unknown>>;
+/** One plan node → its host props, in the order that makes precedence explicit. */
+export declare function nodeProps(node: WidgetNode, inherited: AnyProps, extra: AnyProps): AnyProps;
+export interface Rendered {
+    readonly plan: PrimitivePlan;
+    readonly children: readonly ReactNode[];
+    readonly inherited: AnyProps;
+    readonly extra: AnyProps;
+    /** `Gio.File` values and the slot, for the content node. */
+    readonly contentExtra: AnyProps;
+    /** `Gio.File` values and the slot, for the backdrop node. */
+    readonly backdropExtra: AnyProps;
+    readonly published: ChildContext;
+    readonly tokens: StyleTokens;
+    /** The element's own `Gtk.Widget`, once it is attached. The press and gesture seams need it. */
+    readonly widgetRef: {
+        current: unknown;
+    };
+}
+/**
+ * The shared body of all seven components.
+ *
+ * `props` is `object` and cast ONCE here, rather than each component's own props
+ * interface. An interface without an index signature is not assignable to
+ * `Record<string, unknown>` (TS2345), and widening every one of the seven with
+ * `[key: string]: unknown` would make a MISSPELLED prop type-check — which is
+ * exactly the refusal L2's unknown-prop throw exists to give at build time through
+ * these declarations.
+ */
+export declare function usePlan(primitive: string, authored: object): Rendered;
 export interface ViewProps extends CommonProps {
     /** `auto` and `none` only — GTK's `can-target` covers the widget AND its subtree. */
     pointerEvents?: 'auto' | 'none';
@@ -21,22 +53,27 @@ export interface TextProps extends CommonProps {
     selectable?: boolean;
 }
 export declare function Text(props: TextProps): ReactElement;
-export interface PressableProps extends CommonProps {
+/** What React Native hands a `Pressable`'s function child. */
+export interface PressableState {
+    readonly pressed: boolean;
+}
+export interface PressableProps extends Omit<CommonProps, 'children'> {
     onPress?: () => void;
     disabled?: boolean;
     pointerEvents?: 'auto' | 'none';
     /**
-     * `ReactNode`, NEVER a function.
+     * A node, or a function of `{ pressed }`.
      *
-     * ADR 0032 § 7: children-as-a-function-of-`{ pressed }` belongs to the "usable"
-     * milestone and is a NAMED BUILD-TIME REFUSAL until then. This declaration is
-     * that build-time half — `children={({ pressed }) => …}` becomes a type error
-     * naming the property — and it earns its place on its own: the press state is
-     * the GTK CSS `:active` pseudo-class, so `active:opacity-70` already does what
-     * nearly every use of the function form does, with no re-render at all. Measured
-     * in the application ADR 0032 read: ZERO occurrences of the function form.
+     * THE FUNCTION FORM IS THE EXPENSIVE ONE AND IT IS NOT THE DEFAULT PATH. ADR 0032
+     * § 7: press styling is the GTK CSS `:active` pseudo-class, `active:opacity-70`
+     * costs nothing, and GTK animates the state itself with no re-render — measured in
+     * the application ADR 0032 read, the function form occurs ZERO times. So the
+     * function form is implemented for the code that does use it, and an element that
+     * does not use it subscribes to nothing at all: `press.ts`' `pressWatchCount()`
+     * exists so a spec can hold that apart, because both render and only a count tells
+     * them apart.
      */
-    children?: ReactNode;
+    children?: ReactNode | ((state: PressableState) => ReactNode);
 }
 export declare function Pressable(props: PressableProps): ReactElement;
 export interface ScrollViewProps extends CommonProps {
@@ -75,3 +112,122 @@ export interface SwitchProps extends CommonProps {
     disabled?: boolean;
 }
 export declare function Switch(props: SwitchProps): ReactElement;
+/** React Native's `ImageSourcePropType`, as much of it as GTK can open. */
+export interface ImageURISource {
+    /** A local path, a `file:` URI or a `resource:` URI. Anything else is refused by name. */
+    uri: string;
+}
+export interface ImageProps extends Omit<CommonProps, 'children'> {
+    source?: ImageURISource;
+    /** `repeat` is absent on purpose: `Gtk.ContentFit` has no tiling member (measured). */
+    resizeMode?: 'cover' | 'contain' | 'stretch' | 'center';
+    /** React Native 0.71's own name for the accessible description — `Gtk.Picture:alternative-text`. */
+    alt?: string;
+}
+export declare function Image(props: ImageProps): ReactElement;
+export interface ImageBackgroundProps extends CommonProps {
+    source?: ImageURISource;
+    resizeMode?: 'cover' | 'contain' | 'stretch' | 'center';
+    alt?: string;
+    /** Styles the picture behind the children, not the container. React Native's own name. */
+    imageStyle?: StyleInput;
+    pointerEvents?: 'auto' | 'none';
+}
+export declare function ImageBackground(props: ImageBackgroundProps): ReactElement;
+/**
+ * The Touchable family, written OVER `Pressable` rather than beside it.
+ *
+ * ADR 0032's planning entries say "the same machinery as Pressable, and nearly free
+ * once it exists", and this is what that costs when it is true: the three components
+ * are one line each over the same `usePlan`/`render` pair, and the only thing that
+ * differs is the row L2 looks up — `TouchableOpacity` and `TouchableHighlight` spread
+ * `Pressable`'s own routes out of one shared record, and `TouchableWithoutFeedback` is
+ * a `Gtk.Box` with a gesture controller because it has no chrome to press.
+ *
+ * `activeOpacity` and `underlayColor` are refusals rather than mappings, and the
+ * reason is ADR 0032 § 3 rather than ADR 0032 § 7: honouring them would put an opacity
+ * and a colour into the styling path that did not come from the project's token scale.
+ * `active:opacity-70` and `active:bg-<token>` do the same thing through the mechanism
+ * that reads it.
+ */
+export interface TouchableProps extends PressableProps {
+    /** Refused by name — write `active:opacity-70`. Declared so the type says so too. */
+    activeOpacity?: never;
+}
+export declare function TouchableOpacity(props: TouchableProps): ReactElement;
+export interface TouchableHighlightProps extends TouchableProps {
+    /** Refused by name — write `active:bg-<token>`. */
+    underlayColor?: never;
+}
+export declare function TouchableHighlight(props: TouchableHighlightProps): ReactElement;
+export interface TouchableWithoutFeedbackProps extends Omit<TouchableProps, 'children'> {
+    children?: ReactNode;
+}
+export declare function TouchableWithoutFeedback(props: TouchableWithoutFeedbackProps): ReactElement;
+/**
+ * The one component whose styling story is "you cannot", in both vocabularies.
+ *
+ * `ButtonProps` does NOT extend `CommonProps`, which is the build-time half of the
+ * refusal: `<Button style={…}>` is a type error naming the property. The runtime half
+ * is L2's `refusesStyle`, checked before any prop is routed, so a JavaScript caller and
+ * the second L3 get the same sentence.
+ */
+export interface ButtonProps {
+    title: string;
+    onPress?: () => void;
+    disabled?: boolean;
+    testID?: string;
+    ref?: Ref<unknown>;
+}
+export declare function Button(props: ButtonProps): ReactElement;
+/**
+ * A no-op that still lays out — which is what keeps it a no-op rather than a bug.
+ *
+ * The insets a `SafeAreaView` exists to apply are zero on a desktop window, so the
+ * INSET is what disappears. Everything else about it is a `View`: a vertical box, its
+ * children in a column, the same overlay switch when one of them is absolutely
+ * positioned, the same style vocabulary. A component that rendered nothing, or that
+ * rendered a `Gtk.Box` with the children dropped, would be a layout that silently
+ * lost a screen.
+ */
+export declare function SafeAreaView(props: ViewProps): ReactElement;
+export interface KeyboardAvoidingViewProps extends ViewProps {
+    /** A declared no-op: there is no on-screen keyboard to move out of the way of. */
+    behavior?: 'height' | 'position' | 'padding';
+    keyboardVerticalOffset?: number;
+    enabled?: boolean;
+}
+/**
+ * The same no-op, and the same reason it still lays out.
+ *
+ * React Native's `KeyboardAvoidingView` IS a `View` that changes its own height,
+ * padding or position while a keyboard is up. No keyboard comes up here, so what is
+ * left is the `View` — and `behavior`, `keyboardVerticalOffset` and `enabled` are
+ * declared no-ops in the table rather than refusals, because they describe the
+ * behaviour that is already off.
+ */
+export declare function KeyboardAvoidingView(props: KeyboardAvoidingViewProps): ReactElement;
+export interface StatusBarProps {
+    barStyle?: 'default' | 'light-content' | 'dark-content';
+    hidden?: boolean;
+    backgroundColor?: string;
+    translucent?: boolean;
+    animated?: boolean;
+    networkActivityIndicatorVisible?: boolean;
+    showHideTransition?: 'fade' | 'slide' | 'none';
+}
+/**
+ * Renders NOTHING, and that is the whole of it — there is no status bar.
+ *
+ * The one component in this file with no widget. `<StatusBar barStyle="light-content"/>`
+ * is in the first ten lines of most React Native screens, so it has to render; a
+ * desktop window has no bar above it to configure, so it must not render a box that
+ * takes space in the column. `null` is both.
+ *
+ * Its props are ACCEPTED rather than refused, which is the one place this component
+ * differs from `Keyboard`: they are declarative appearance hints with nothing to apply
+ * them to, like `hidesWhenStopped` on the spinner. Its imperative statics are a
+ * different question and refuse by name — see `StatusBarStatics`.
+ */
+export declare function StatusBar(_props: StatusBarProps): null;
+export {};

package/lib/types/generated/own-exports.d.ts

@@ -0,0 +1 @@
+export declare const OWN_EXPORT_NAMES: readonly string[];

package/lib/types/generated/unsupported-exports.d.ts

@@ -1,23 +1,4 @@
 export declare const Modal: never;
-export declare const StyleSheet: never;
-export declare const FlatList: never;
-export declare const SectionList: never;
-export declare const VirtualizedList: never;
-export declare const VirtualizedSectionList: never;
-export declare const Image: never;
-export declare const ImageBackground: never;
-export declare const TouchableOpacity: never;
-export declare const TouchableHighlight: never;
-export declare const TouchableWithoutFeedback: never;
-export declare const Button: never;
-export declare const Dimensions: never;
-export declare const useWindowDimensions: never;
-export declare const Alert: never;
-export declare const Appearance: never;
-export declare const SafeAreaView: never;
-export declare const StatusBar: never;
-export declare const KeyboardAvoidingView: never;
-export declare const Keyboard: never;
 export declare const RefreshControl: never;
 export declare const AppState: never;
 export declare const PixelRatio: never;

package/lib/types/generated/unsupported-router-exports.d.ts

@@ -0,0 +1,17 @@
+export declare const Link: never;
+export declare const Redirect: never;
+export declare const Slot: never;
+export declare const useRouter: never;
+export declare const useSegments: never;
+export declare const useGlobalSearchParams: never;
+export declare const useNavigation: never;
+export declare const useFocusEffect: never;
+export declare const useRootNavigationState: never;
+export declare const Drawer: never;
+export declare const withLayoutContext: never;
+export declare const Navigator: never;
+export declare const ErrorBoundary: never;
+export declare const ExpoRoot: never;
+export declare const useUnstableGlobalHref: never;
+export declare const useNavigationContainerRef: never;
+export declare const SplashScreen: never;

package/lib/types/hooks.d.ts

@@ -1,4 +1,5 @@
 import { type ColorSchemeName } from './apis/color-scheme.js';
+import { type DisplayMetrics } from './apis/display.js';
 /**
  * The desktop's current colour scheme, re-rendering when it changes.
  *
@@ -11,3 +12,18 @@ import { type ColorSchemeName } from './apis/color-scheme.js';
  * environment that has none.
  */
 export declare function useColorScheme(): ColorSchemeName;
+/**
+ * The application window's size, re-rendering when it changes.
+ *
+ * The WINDOW and not the screen: a desktop application is not full-screen, so the
+ * screen's number would be wrong in the ordinary case rather than the rare one (ADR
+ * 0032's own planning entry). `apis/display.ts` holds the measurements — including the
+ * one that makes this hook's mechanism look odd: the notification comes from the
+ * `Gdk.Surface` and the VALUE comes from the window, because `Gtk.Widget` installs no
+ * size property and emits no size-allocate signal.
+ *
+ * The snapshot is cached by value (`windowMetricsSnapshot`), because
+ * `useSyncExternalStore` compares snapshots by identity and a fresh record per call is
+ * React's own "getSnapshot should be cached" loop.
+ */
+export declare function useWindowDimensions(): DisplayMetrics;

package/lib/types/index.d.ts

@@ -2,11 +2,15 @@ export { AppRegistry, registerRootComponent } from './app-registry.js';
 export type { ComponentProvider, RunApplicationOptions } from './app-registry.js';
 export { EventEmitter } from './event-emitter.js';
 export type { EventSubscription } from './event-emitter.js';
-export { ActivityIndicator, Pressable, ScrollView, Switch, Text, TextInput, View } from './components.js';
-export type { ActivityIndicatorProps, CommonProps, PressableProps, ScrollViewProps, SwitchProps, TextInputProps, TextProps, ViewProps, } from './components.js';
-export { Linking, Platform, Share } from './apis/index.js';
-export type { ColorSchemeName, PlatformOS, PlatformSelectSpec, ShareAction, ShareContent } from './apis/index.js';
-export { useColorScheme } from './hooks.js';
+export { ActivityIndicator, Button, Image, ImageBackground, KeyboardAvoidingView, Pressable, SafeAreaView, ScrollView, StatusBar, Switch, Text, TextInput, TouchableHighlight, TouchableOpacity, TouchableWithoutFeedback, View, } from './components.js';
+export type { ActivityIndicatorProps, ButtonProps, CommonProps, ImageBackgroundProps, ImageProps, ImageURISource, KeyboardAvoidingViewProps, PressableProps, PressableState, ScrollViewProps, StatusBarProps, SwitchProps, TextInputProps, TextProps, TouchableHighlightProps, TouchableProps, TouchableWithoutFeedbackProps, ViewProps, } from './components.js';
+export { FlatList, SectionList, VirtualizedList, VirtualizedSectionList } from './lists/components.js';
+export type { FlatListProps, ListRenderItemInfo, ListSeparators, ListSlot, SectionListProps, SectionListSection, VirtualizedListProps, } from './lists/components.js';
+export { Alert, Appearance, Dimensions, Keyboard, Linking, Platform, Share } from './apis/index.js';
+export type { AlertButton, AlertOptions, AppearancePreferences, ColorSchemeName, DimensionKey, DimensionsPayload, DisplayMetrics, PlatformOS, PlatformSelectSpec, ShareAction, ShareContent, } from './apis/index.js';
+export { useColorScheme, useWindowDimensions } from './hooks.js';
+export { StyleSheet } from './stylesheet.js';
+export type { NamedStyles } from './stylesheet.js';
 export { configureStyle, resetStyleConfig, styleConfig } from './style-config.js';
 export type { StyleConfig } from './style-config.js';
 export * as primitives from './primitives/index.js';
@@ -18,5 +22,5 @@ export { PrimitiveError } from './primitives/errors.js';
  */
 export declare function unstable_batchedUpdates<T, R>(callback: (argument: T) => R, argument: T): R;
 export * from './generated/unsupported-exports.js';
-export { SUPPORT_TABLE, SUPPORTED_NAMES, explainUnsupported, isImportable, type SupportEntry, type SupportStatus, type SupportTier, } from './support-table.js';
+export { OWN_EXPORT_NAMES, SUPPORT_TABLE, SUPPORTED_NAMES, explainUnsupported, isImportable, isOwnExport, type SupportEntry, type SupportStatus, type SupportTier, } from './support-table.js';
 export { UnsupportedError } from './unsupported.js';

package/lib/types/lists/components.d.ts

@@ -0,0 +1,102 @@
+import { type ComponentType, type ReactElement, type ReactNode } from 'react';
+import { type CommonProps } from '../components.js';
+/** What React Native's `renderItem` receives. */
+export interface ListRenderItemInfo<T> {
+    readonly item: T;
+    readonly index: number;
+    readonly separators: ListSeparators;
+}
+/**
+ * React Native's `separators`, refusing all three of its methods by name.
+ *
+ * They ask the list to restyle the separator above and below a row — and a
+ * `Gtk.ListView` has no separator widget to restyle: `show-separators` makes GTK draw
+ * the Adwaita line itself, between rows it owns. `ItemSeparatorComponent` is refused in
+ * the table for the same reason, so this is that refusal reaching the one other place
+ * it can be asked for.
+ */
+export interface ListSeparators {
+    highlight(): void;
+    unhighlight(): void;
+    updateProps(select: 'leading' | 'trailing', newProps: object): void;
+}
+/** A header/footer/empty slot: an element, or a component to render. */
+export type ListSlot = ReactNode | ComponentType<Record<string, never>>;
+/** The props every list in this file answers for. Each name is in L2's row. */
+export interface ListFrameProps extends Omit<CommonProps, 'children'> {
+    /**
+     * Where a ROW's own render error goes. Not a React Native prop, and it earns its
+     * place: a row is a React root of its own, so an error inside `renderItem` has no
+     * ancestor boundary in the outer tree to reach. Absent means the host's default —
+     * logged and rethrown, which is loud.
+     */
+    onRowError?: (error: Error) => void;
+    horizontal?: boolean;
+    showsVerticalScrollIndicator?: boolean;
+    showsHorizontalScrollIndicator?: boolean;
+    ListEmptyComponent?: ListSlot;
+    ListHeaderComponent?: ListSlot;
+    ListFooterComponent?: ListSlot;
+    onEndReached?: (info: {
+        distanceFromEnd: number;
+    }) => void;
+    /** Page-lengths from the end at which `onEndReached` fires. React Native's default is 0.5. */
+    onEndReachedThreshold?: number;
+    /** A change re-renders every bound row, for the rows whose keys did not change. */
+    extraData?: unknown;
+}
+export interface FlatListProps<T> extends ListFrameProps {
+    data?: readonly T[] | null;
+    renderItem?: (info: ListRenderItemInfo<T>) => ReactNode;
+    keyExtractor?: (item: T, index: number) => string;
+}
+export interface VirtualizedListProps<T> extends FlatListProps<T> {
+    /** `VirtualizedList`'s accessor form of `data` — three lines here, and honest. */
+    getItem?: (data: readonly T[] | null | undefined, index: number) => T;
+    getItemCount?: (data: readonly T[] | null | undefined) => number;
+}
+export interface SectionListSection<T> {
+    readonly data: readonly T[];
+    readonly key?: string;
+    readonly title?: string;
+}
+export interface SectionListProps<T> extends ListFrameProps {
+    sections?: readonly SectionListSection<T>[];
+    renderItem?: (info: ListRenderItemInfo<T>) => ReactNode;
+    renderSectionHeader?: (info: {
+        section: SectionListSection<T>;
+    }) => ReactNode;
+    keyExtractor?: (item: T, index: number) => string;
+}
+export declare function FlatList<T>(props: FlatListProps<T>): ReactElement;
+/**
+ * `VirtualizedList`, as the honest subset ADR 0032 asks for.
+ *
+ * Its own public surface is wide and most of it configures React Native's
+ * virtualisation, which `Gtk.ListView` does itself — those props are refused by name in
+ * L2's row. What is left is a real API and three lines: `getItemCount(data)` for the
+ * length and `getItem(data, i)` for a row, which is `FlatList` with the array
+ * behind an accessor.
+ */
+export declare function VirtualizedList<T>(props: VirtualizedListProps<T>): ReactElement;
+/**
+ * `SectionList`, with the sections FLATTENED into one model.
+ *
+ * MEASURED on gtk 4.22.4: GTK does have section models — `Gtk.SectionModel` exists,
+ * `Gtk.FlattenListModel` and every selection model implement it (`Gio.ListStore` and
+ * `Gtk.StringList` do not), `Gtk.ListView.set_header_factory` is there, and a
+ * `Gtk.FlattenListModel` over two stores answered `get_section(0) = [0, 2]`. So the
+ * sticky-header route is real and available.
+ *
+ * It is not the one taken, and the reason is what the sticky route costs: a second
+ * factory with its own React roots, a `Gtk.ListHeader` whose `start`/`end`/`n-items`
+ * have to be reconciled with React Native's `section` object, and a model of models
+ * whose splice semantics are one level deeper than the flat one. A flattened model with
+ * header ROWS is one model, one factory and one splice — and it delivers exactly what
+ * `stickySectionHeadersEnabled={false}` asks for, which is the support table's declared
+ * limit. The measurement is written down here so the sticky version is an upgrade with
+ * a known starting point rather than a rediscovery.
+ */
+export declare function SectionList<T>(props: SectionListProps<T>): ReactElement;
+/** The section-shaped sibling of `VirtualizedList`, which is `SectionList` here. */
+export declare function VirtualizedSectionList<T>(props: SectionListProps<T>): ReactElement;

package/lib/types/lists/controller.d.ts

@@ -0,0 +1,45 @@
+import { ListController, onScrollNearEnd } from '@gjsify/gtk-host/list';
+import { type ReactRoot } from '@gjsify/gtk-host/react';
+import { type ReactNode } from 'react';
+/** One row: an identity, and the React tree it renders to. */
+export interface ListRow {
+    /** `keyExtractor`'s answer. It decides whether the model has to be rebuilt at all. */
+    readonly key: string;
+    /** Called on every bind, so it always reads the latest `data`. */
+    render(): ReactNode;
+}
+/** The controller a list component owns: the shared core, wearing React's row sink. */
+export type ReactListController = ListController<ListRow, ReactRoot>;
+/** What a list component may tell its controller, beyond the rows themselves. */
+export interface ListControllerOptions {
+    /**
+     * Where a row's own render error goes.
+     *
+     * Absent means the host adapter's default: log it AND rethrow it from the
+     * `render()` call — which here is inside the microtask drain, so the rethrow leaves
+     * JS as an uncaught exception. That is loud and correct in an application; a caller
+     * with its own error surface (or a spec asserting a named refusal) passes a recorder
+     * instead, which is exactly what the adapter documents the option for.
+     */
+    readonly onRowError?: (error: Error) => void;
+}
+/** The list controller a React component owns. */
+export declare function createListController(options?: ListControllerOptions): ReactListController;
+/**
+ * `keyExtractor`, with React Native's own default.
+ *
+ * `item.key`, then `item.id`, then the index — the order React Native uses, and the
+ * index last because a key that is the position makes every row after an insertion
+ * change identity, which here means every row after it is re-bound.
+ */
+export declare function rowKey(item: unknown, index: number, keyExtractor?: (item: unknown, index: number) => string): string;
+/**
+ * The scroll edge behind `onEndReached`, re-exported rather than reimplemented.
+ *
+ * It lived here, and it was never React's: `Gtk.Adjustment` arithmetic with no React in
+ * it and no toolkit value import. `@gjsify/gtk-host/list` owns it now, so a Vue or Solid
+ * list gets the same measured behaviour instead of re-deriving it — which is the failure
+ * this whole extraction exists to prevent. `components.ts` imports it from here, so the
+ * move costs no consumer a rewrite.
+ */
+export { onScrollNearEnd };

package/lib/types/lists/lists.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/parent-context.d.ts

@@ -0,0 +1,15 @@
+import { type ReactElement, type ReactNode } from 'react';
+import type { ChildContext } from './primitives/resolve.js';
+/** `null` at a root, which is what makes an unresolvable `flex-1` there a refusal. */
+export declare const ParentContext: import("react").Context<ChildContext | null>;
+/**
+ * Publish `value` to everything rendered inside.
+ *
+ * A named component rather than `ParentContext.Provider` at each call site, so the
+ * two places that publish a context (an element's own children, and a list row's
+ * fresh root) spell it the same way.
+ */
+export declare function ParentProvider(props: {
+    readonly value: ChildContext;
+    readonly children?: ReactNode;
+}): ReactElement;

package/lib/types/press.d.ts

@@ -0,0 +1,27 @@
+import Gtk from 'gi://Gtk?version=4.0';
+/**
+ * How many elements are currently reporting their press state to JavaScript.
+ *
+ * Exported for the specs, and it is the only way to assert the distinction ADR 0032
+ * § 7 rests on: `<Pressable className="active:opacity-70">` must resolve to CSS and
+ * subscribe to nothing, while `<Pressable>{({ pressed }) => …}</Pressable>` must
+ * subscribe to exactly one thing. Both render, both look right, and only a count
+ * tells them apart — which is why the cheap path would otherwise disappear quietly.
+ */
+export declare const pressWatchCount: () => number;
+/**
+ * Report `widget`'s press state to `listener` as it changes; returns the unsubscribe.
+ *
+ * The listener is called once immediately, because a subscriber that only hears about
+ * CHANGES starts out disagreeing with the widget — and the first render of a
+ * function child has to know whether the button is already down.
+ */
+export declare function onPressStateChange(widget: Gtk.Widget, listener: (pressed: boolean) => void): () => void;
+/**
+ * Add a `Gtk.GestureClick` to `widget` and call `listener` on `signal`; returns the removal.
+ *
+ * The controller is REMOVED and the handler disconnected, in that order: a controller
+ * left on a widget outlives every JS reference to it, and its handler is then one of
+ * the callbacks GJS blocks during GC.
+ */
+export declare function onGesture(widget: Gtk.Widget, signal: string, listener: () => void): () => void;

package/lib/types/primitives/index.d.ts

@@ -4,8 +4,8 @@ export { PrimitiveError } from './errors.js';
 export { resolveIntent } from './intents.js';
 export type { ChildContext, ChildFacts, IntentInput, IntentResolution, Orientation, WidgetFacts } from './intents.js';
 export { declaresAbsolute, resolvePrimitive } from './resolve.js';
-export type { PrimitiveContext, PrimitivePlan, PrimitiveProps, ResolvedEvent, WidgetNode } from './resolve.js';
+export type { PrimitiveContext, PrimitivePlan, PrimitiveProps, ResolvedEvent, ResolvedFile, ResolvedGesture, WidgetNode, } from './resolve.js';
 export { flattenStyle, mintClass, normalise, variantDeclarations } from './style.js';
 export type { ClassNameSink, StyleAuthored, StyleInput, StyleObject } from './style.js';
 export { FRAMEWORK_PROPS, PRIMITIVE_NAMES, PRIMITIVES } from './table.js';
-export type { Coercion, ContentSpec, EventRoute, IgnoredRoute, PrimitiveSpec, PropRoute, PropertyRoute, RefusedRoute, StylePropertyRoute, } from './table.js';
+export type { Coercion, ContentSpec, EventRoute, FileRoute, GestureRoute, IgnoredRoute, NodeKind, PrimitiveSpec, PropRoute, PropertyRoute, RefusedRoute, StylePropertyRoute, } from './table.js';

package/lib/types/primitives/resolve.d.ts

@@ -2,6 +2,7 @@ import type { LayoutIntent, StyleTokens } from '@gjsify/gtk-host/style';
 import type { ClassNameInput } from './classes.js';
 import { type ChildContext, type ChildFacts, type Orientation, type WidgetFacts } from './intents.js';
 import { type ClassNameSink, type StyleInput } from './style.js';
+import { type NodeKind } from './table.js';
 /** Everything L2 needs that is not the primitive and not its props. */
 export interface PrimitiveContext {
     /** The project's own token scales. ADR 0032 § 3: the families are declared, the values are the project's. */
@@ -31,6 +32,31 @@ export interface ResolvedEvent {
     /** The widget property to read for the callback's argument, or null for no argument. */
     readonly read: string | null;
 }
+/**
+ * A widget property whose value is a `Gio.File`, decided here and BUILT one layer up.
+ *
+ * L2 holds every decision — which schemes have a synchronous loader, which shapes
+ * React Native accepts that this build chain cannot honour — and none of the
+ * construction, because building a `Gio.File` needs `gi://Gio` and nothing under
+ * `primitives/` imports `gi://`. That is not a stylistic rule: it is what lets this
+ * whole layer be asserted by comparison, with no display and no toolkit.
+ */
+export interface ResolvedFile {
+    /** Which node of the plan the property is on. */
+    readonly on: NodeKind;
+    /** The GTK property that takes it — `file` on a `Gtk.Picture`. */
+    readonly property: string;
+    /** `path` → `Gio.File.new_for_path`; `uri` → `Gio.File.new_for_uri`. */
+    readonly kind: 'path' | 'uri';
+    readonly value: string;
+}
+/** A press this element takes through a `Gtk.GestureClick` rather than a widget signal. */
+export interface ResolvedGesture {
+    /** The React Native prop that supplied the callback. */
+    readonly prop: string;
+    /** The `Gtk.GestureClick` signal — `released` is a completed press. */
+    readonly signal: string;
+}
 export interface PrimitivePlan {
     readonly primitive: string;
     /** The node the PARENT adopts. */
@@ -41,7 +67,17 @@ export interface PrimitivePlan {
     readonly slot: string | null;
     /** Where an absolutely positioned CHILD goes: into `node`, under this slot. */
     readonly absoluteSlot: string | null;
+    /** A node that takes no children and sits BEHIND them — `ImageBackground`'s picture. */
+    readonly backdrop: WidgetNode | null;
+    /** The slot `backdrop` declares to `node`, or null for the default slot. */
+    readonly backdropSlot: string | null;
+    /** The slot `content` declares to `node`, or null for the default slot. */
+    readonly contentSlot: string | null;
     readonly events: readonly ResolvedEvent[];
+    /** Widget properties whose value is a file the framework layer constructs. */
+    readonly files: readonly ResolvedFile[];
+    /** Presses that arrive through a gesture controller instead of a signal. */
+    readonly gestures: readonly ResolvedGesture[];
     /** Where a text child goes, or null when text under this primitive is refused. */
     readonly textSink: string | null;
     /** What this element publishes to its children. */