@gjsify/react-native 0.45.0 → 0.47.0

package/README.md

@@ -32,6 +32,46 @@ a real `react-native` install when one is resolvable — and it prints which of
 it did, because a gate that silently degrades to the weaker half is worse than one
 that has only the weaker half.
 
+## The PROP surface is a contract too, and it is published
+
+The support table answers "may this application import this name". One grain finer
+sits `src/primitives/table.ts`, which decides what each PRIMITIVE does with each
+PROP — and until [ADR 0039](../../../docs/adr/0039-react-native-prop-surface.md) it
+was not an entry point, so a refusal could only be discovered by RENDERING. That cost
+a whole tree once: a `<Text onPress>` in a tab stack that mounts every tab from the
+start route threw out of a render, and React unmounts the root when a render throws
+with no error boundary above it — 92 125 bytes of widget dump clean against 12 848
+with the throw, same screen, same host.
+
+The refusal is right and it still throws: a prop that silently does nothing is
+indistinguishable from a bug in the application, forever. What was missing is a way to
+ask FIRST, and that is `@gjsify/react-native/prop-table`:
+
+```ts
+import { acceptsProp, explainProp } from '@gjsify/react-native/prop-table';
+
+// in your own test suite, before a window exists
+expect(acceptsProp('Text', 'onPress')).toBe(false);
+expect(explainProp('Text', 'onPress')).toContain('Wrap it in a `<Pressable>`');
+```
+
+`explainProp` returns the very sentence a render would have thrown — one classifier
+(`src/primitives/answers.ts`) serves both, so the static answer cannot drift from the
+runtime one. [PROPS.md](PROPS.md) is the generated document, one section per
+primitive, held byte for byte by `check-rn-surface.mjs`.
+
+## `<TextInput>`'s ref is a handle, not the widget
+
+React Native's `TextInput` is a class, so `useRef<TextInput>(null)` and
+`ref.current?.focus()` are ordinary code. Here `TextInput` is a component function
+merged with an instance interface, and the ref receives `focus`, `blur`, `clear`,
+`isFocused` and `setSelection` over GTK, plus `widget` — the `Gtk.Entry` or
+`Gtk.TextView` itself, which is where anything the handle does not answer lives.
+`measure`, `measureInWindow`, `measureLayout` and `setNativeProps` are present and
+**refuse by name**, because an absent method is `undefined is not a function`.
+
+Every other primitive's ref is the `Gtk.Widget`, unchanged.
+
 ## Getting a window
 
 ```ts
@@ -184,166 +224,8 @@ refusals. The plugin walks a directory and emits what it found.
 
 ## Support
 
-<!-- BEGIN generated support table -->
-
-### Supported (4)
-
-| export | tier | GTK | why |
-|---|---|---|---|
-| `useColorScheme` | P1 | Adw.StyleManager.dark | Follows the Adwaita colour scheme — the dark property, which is what the user is looking at, not color-scheme, which is what the application asked for. |
-| `Appearance` | P2 | Adw.StyleManager | The imperative sibling of useColorScheme, over the SAME reader — getColorScheme reads Adw.StyleManager:dark (what the user is looking at) and setColorScheme writes :color-scheme (what the application asked for), which is exactly the split React Native’s getter and setter have. |
-| `EventEmitter` | — | — | Pure JavaScript; nothing in it touches a platform. |
-| `unstable_batchedUpdates` | — | — | React 19 batches automatically; this is the identity call it already is upstream. |
-
-### Supported, with named limits (29)
-
-| export | tier | GTK | why |
-|---|---|---|---|
-| `View` | P1 | Gtk.Box, or Gtk.Overlay when a child is absolutely positioned | The container primitive. Which widget it becomes depends on its children, not on the element. |
-| `Text` | P1 | Gtk.Label | Wrapping is ON by default in React Native and OFF on a Gtk.Label, so the default is set explicitly. |
-| `Pressable` | P1 | Gtk.Button (flat) | Press state is a GTK CSS :active pseudo-class; children-as-a-function is implemented over the state flag, and costs nothing when it is unused. |
-| `ScrollView` | P1 | Gtk.ScrolledWindow + an implicit content box | contentContainerStyle styles the inner box, which is a second styleable node. |
-| `ActivityIndicator` | P1 | Adw.Spinner | Direct counterpart. |
-| `TextInput` | P1 | Gtk.Entry / Gtk.TextView | Single- versus multi-line is one prop in React Native and two different widgets in GTK. |
-| `Linking` | P1 | Gtk.UriLauncher | openURL and canOpenURL only. |
-| `Switch` | P1 | Gtk.Switch | Direct counterpart. |
-| `Platform` | P1 | — | OS is "linux" \| "macos" \| "windows"; select() picks the default branch. |
-| `Share` | P1 | Gdk.Clipboard | No desktop share sheet worth pretending about; copying the link is the honest mapping. |
-| `AppRegistry` | P1 | Adw.Application + Adw.ApplicationWindow | The entry point. Nothing renders without a window, so this is P1 despite being a shim. |
-| `StyleSheet` | P1 | Gdk.Monitor.scale for hairlineWidth | create/flatten/compose/hairlineWidth/absoluteFill. Style objects go through the same partition as classes (ADR 0032 § 4), which is why create can be identity. |
-| `FlatList` | P2 | Gtk.ListView + Gio.ListStore, owned by the component | GTK virtualises for real. The list is NOT an ordinary element: a Gtk.ListView takes no children (measured — no append, add, insert, prepend, remove or set_child), so the component owns the view and drives the model from data, with React only inside the item factory. |
-| `SectionList` | P2 | Gtk.ListView + one flattened Gio.ListStore | The same component as FlatList, handed sections instead of data. |
-| `VirtualizedList` | P2 | Gtk.ListView | Its public surface is wide and mostly not worth honouring literally; the useful subset backs FlatList, and this name is that subset plus getItem/getItemCount. |
-| `VirtualizedSectionList` | P2 | Gtk.ListView | The section-shaped sibling of VirtualizedList, which is SectionList here. |
-| `Image` | P2 | Gtk.Picture | resizeMode becomes content-fit, and the default is inverted: React Native defaults to cover, a Gtk.Picture to contain (measured). |
-| `ImageBackground` | P2 | Gtk.Picture in a Gtk.Overlay | A picture with the children stacked over it. The picture is the overlay’s MAIN child, because a Gtk.Overlay paints every overlay child ABOVE it. |
-| `TouchableOpacity` | P2 | Gtk.Button (flat) | The same machinery as Pressable, written over it: one shared record of routes in the primitive table, one line of component. |
-| `TouchableHighlight` | P2 | Gtk.Button (flat) | As TouchableOpacity. The pressed style is Adwaita’s own unless a variant says otherwise. |
-| `TouchableWithoutFeedback` | P2 | Gtk.Box + Gtk.GestureClick | No chrome, so no button: a vertical Gtk.Box like a View, with a Gtk.GestureClick added to it. Measured: Gtk.Button emits activate and clicked, a Gtk.Box emits neither, and Gtk.GestureClick emits pressed/released/stopped/unpaired-release. |
-| `Button` | P2 | Gtk.Button | The one component whose React Native styling story is "you cannot", which GTK agrees with. title, onPress and disabled. |
-| `Dimensions` | P2 | Gtk.Window allocation, Gdk.Monitor geometry | get("window") is the window, not the screen — a desktop app is not full-screen, so the screen’s number would be wrong in the ordinary case. get("screen") is the monitor, because that is what it asks for. |
-| `useWindowDimensions` | P2 | Gdk.Surface notify::width/height, Gtk.Window allocation | The hook form of Dimensions, through useSyncExternalStore so a resize between render and commit cannot tear. |
-| `Alert` | P2 | Adw.AlertDialog | Direct counterpart, and buildable where Modal is not: Alert is a FUNCTION CALL, so no element is ever inserted into a widget. Measured on libadwaita 1.9.3 — present(null) from a plain function, with no parent and no window, returned with no diagnostic. |
-| `SafeAreaView` | P2 | Gtk.Box | The INSET has no desktop meaning; the layout does. It is a View in every other respect, and it has to be a real export to be imported. |
-| `StatusBar` | P2 | — | A desktop window has no status bar to configure, and <StatusBar/> is in the first ten lines of most React Native screens — so it renders NOTHING and says so, rather than failing to import. |
-| `KeyboardAvoidingView` | P2 | Gtk.Box | No on-screen keyboard eats a desktop window layout, so the AVOIDING is the no-op. React Native’s KeyboardAvoidingView is a View that changes its own height; what is left here is the View. |
-| `Keyboard` | P2 | — | Its events are on-screen-keyboard events, which do not occur — so the questions with a correct answer get it and the ones whose answer would have to be invented refuse. |
-
-### Planned (28)
-
-| export | tier | GTK | why |
-|---|---|---|---|
-| `Modal` | P1 | Adw.Dialog | An Adw.Dialog cannot be an ordinary element. MEASURED on libadwaita 1.9.3: box.append(dialog) calls g_error() — SIGABRT and a core dump, not a catchable exception — but ONLY when the box is rooted in a window. A detached box accepts the append in silence, so a re-test on a bare box appears to disprove this and puts the primitive back. A dialog is PRESENTED against a parent, never parented by it, so this is a PORTAL and needs a host seam that does not exist yet. |
-| `AppState` | P3 | Gtk.Application / Gdk.Surface state | active/background from window focus and visibility. |
-| `PixelRatio` | P3 | Gdk.Surface.scale-factor | The scale factor of the surface the widget is on. |
-| `PlatformColor` | P3 | Adwaita named colours | Maps unusually well — GTK’s palette is exactly this idea. |
-| `AccessibilityInfo` | P3 | Gtk.Accessible / AT-SPI | The highest-value P3 entry: GTK’s accessibility model is strong and the props map onto it well. |
-| `Animated` | P3 | Adw.TimedAnimation / Adw.SpringAnimation | Genuinely mappable, but it is a subsystem rather than a component. Doing it badly is worse than not doing it. |
-| `Easing` | P3 | — | Pure maths; it lands with Animated or not at all. |
-| `LayoutAnimation` | P3 | — | Needs an animated layout pass, which is the same subsystem as Animated. |
-| `InteractionManager` | P3 | — | Deferring work until interactions settle; a main-loop idle source is the counterpart. |
-| `useAnimatedValue` | P3 | — | Part of the Animated subsystem. |
-| `useAnimatedValueXY` | P3 | — | Part of the Animated subsystem. |
-| `useAnimatedColor` | P3 | — | Part of the Animated subsystem. |
-| `PanResponder` | P3 | Gtk.Gesture* controllers | The controllers exist; the arbitration model is not React Native’s, so this is its own project. |
-| `usePressability` | P3 | — | The hook behind the Touchable family; it lands with the gesture work. |
-| `DrawerLayoutAndroid` | P3 | Adw.OverlaySplitView | The pattern survives on a desktop even though the component is Android-only. |
-| `I18nManager` | P3 | Gtk.Widget.direction | RTL is a widget-direction question on GTK. |
-| `ToastAndroid` | P3 | Adw.Toast | Android-only by name, and Adwaita has the exact widget. |
-| `TouchableNativeFeedback` | P3 | Gtk.Button | Android-only ripple; shimmed to its portable sibling. |
-| `ActionSheetIOS` | P3 | Adw.AlertDialog with responses | iOS-only by name; the pattern is a dialog with choices. |
-| `Clipboard` | P3 | Gdk.Clipboard | Deprecated upstream in favour of a community package, but trivial here. |
-| `BackHandler` | P3 | — | An Android hardware back button. Routing has landed and this did NOT arrive with it, which the earlier reason assumed it would: BackHandler INTERCEPTS a back press and consumes it, and MEASURED on libadwaita 1.9.3, Adw.NavigationView emits `popped` AFTER the fact and has no vetoable "about to pop" signal at all — its only prevention is Adw.NavigationPage:can-pop, a property rather than an event. The honest counterpart is usePreventRemove, which the routing layer does honour through its popped bridge; this name needs a key controller of its own on the window. |
-| `DynamicColorIOS` | P3 | — | A light/dark colour pair; the Adwaita scheme already provides the switch. |
-| `processColor` | P3 | — | Colour string to a platform value; a Gdk.RGBA on this side. |
-| `UTFSequence` | P3 | — | A table of unicode constants. Pure data, no platform in it. |
-| `ReactNativeVersion` | P3 | — | The version this layer targets, reported honestly rather than spoofed. |
-| `ProgressBarAndroid` | P3 | Gtk.ProgressBar | Android-only by name; GTK has the widget. |
-| `NativeEventEmitter` | P3 | — | It would construct and subscribe, but nothing native would ever emit into it — shipping that needs a decision, not a class. |
-| `DeviceEventEmitter` | P3 | — | The global emitter. Lands with NativeEventEmitter, and for the same reason. |
-
-### No meaning on a desktop window (6)
-
-| export | tier | GTK | why |
-|---|---|---|---|
-| `LogBox` | P3 | — | A development overlay for a phone; the console is the desktop equivalent. |
-| `Systrace` | — | — | Android systrace has no desktop counterpart. |
-| `Vibration` | — | — | A desktop machine does not vibrate. |
-| `InputAccessoryView` | — | — | An iOS keyboard accessory bar; there is no keyboard to accessorise. |
-| `DevMenu` | — | — | The shake-to-open developer menu. |
-| `DevSettings` | — | — | Development-client settings for a phone runtime. |
-
-### Refused (25)
-
-| export | tier | GTK | why |
-|---|---|---|---|
-| `RefreshControl` | — | — | GTK has no pull-to-refresh idiom and should not grow one. Give the desktop build a refresh action instead. |
-| `PushNotificationIOS` | — | — | Platform notification plumbing. A desktop app uses Gio.Notification directly. |
-| `PermissionsAndroid` | — | — | Android runtime permissions have no desktop counterpart; portals are asked for at use time. |
-| `Settings` | — | — | An iOS user-defaults bridge. GSettings is the desktop answer and is not this API. |
-| `experimental_LayoutConformance` | — | — | An experimental switch between two React Native layout implementations. Neither is used here. |
-| `unstable_VirtualView` | — | — | Unstable React Native internal. |
-| `VirtualViewMode` | — | — | Unstable React Native internal. |
-| `unstable_NativeText` | — | — | Unstable React Native internal. |
-| `unstable_NativeView` | — | — | Unstable React Native internal. |
-| `unstable_TextAncestorContext` | — | — | Unstable React Native internal. |
-| `DeviceInfo` | — | — | A native module surface describing a phone. |
-| `NativeModules` | — | — | The native-module bridge. There is no bridge here; this layer renders in-process onto GTK. |
-| `TurboModuleRegistry` | — | — | The TurboModule lookup. Same reason as NativeModules. |
-| `NativeComponentRegistry` | — | — | Fabric component registration. The host owns widget creation. |
-| `requireNativeComponent` | — | — | Looks up a native view manager. Write a GTK widget descriptor instead. |
-| `codegenNativeComponent` | — | — | React Native codegen for Fabric components. |
-| `codegenNativeCommands` | — | — | React Native codegen for Fabric commands. |
-| `UIManager` | — | — | The legacy view-manager surface. The GTK host is the view manager here. |
-| `findNodeHandle` | — | — | Returns a native view tag. A ref here is the Gtk.Widget itself, which is more useful. |
-| `registerCallableModule` | — | — | Registers a module callable from the native side. There is no native side. |
-| `Networking` | — | — | React Native’s XHR internals. Use fetch, which gjsify provides. |
-| `NativeDialogManagerAndroid` | — | — | An Android dialog native module. Alert is the portable spelling. |
-| `Touchable` | — | — | The legacy mixin behind the Touchable family, not a public component. |
-| `NativeAppEventEmitter` | — | — | The legacy iOS app-event emitter. |
-| `RootTagContext` | — | — | A React Native surface identifier. This layer has one root per Adw window. |
-
-<!-- END generated support table -->
-
-### Routing surface
-
-<!-- BEGIN generated router support table -->
-
-### Supported, with named limits (5)
-
-| export | tier | GTK | why |
-|---|---|---|---|
-| `router` | P1 | Adw.NavigationView (push/pop) via React Navigation’s StackActions | push, back, replace and navigate — the four methods the measured application calls, 19 of the 27 calls being push. |
-| `useLocalSearchParams` | P1 | — | The current route’s params — the [param] values and the query string — read through React Navigation’s own useRoute(). |
-| `usePathname` | P1 | — | The current URL without its query string, from React Navigation’s getPathFromState over the published root state. |
-| `Stack` | P1 | Adw.NavigationView + Adw.NavigationPage | The stack navigator: React declares which pages exist, the widget owns their order, and the route key is the tag that joins the two. |
-| `Tabs` | P1 | Adw.ViewStack + Adw.ViewSwitcher | The tab navigator. The switcher is driven by the stack’s own page model, so a route file adds a button with no tab-bar bookkeeping. |
-
-### Planned (13)
-
-| export | tier | GTK | why |
-|---|---|---|---|
-| `Link` | P2 | Gtk.Button (flat) or Gtk.LinkButton | An href as an element rather than a call. Cheap once `router` exists, and the honest widget question — button or link — is worth measuring first. |
-| `Redirect` | P2 | — | A declarative navigate-on-render. It needs a rule for what happens when it redirects during the first commit, which is the commit that must not be empty. |
-| `Slot` | P2 | Adw.Bin | A layout that renders its child route with no navigator around it. It is the one layout shape that has no widget of its own. |
-| `useRouter` | P2 | — | The hook form of `router`. Identical behaviour, and it exists so a test can substitute the object — which is worth having once there is something to substitute. |
-| `useSegments` | P2 | — | The current route split into segments. Derivable from the published root state, and unused in the measured application. |
-| `useGlobalSearchParams` | P2 | — | The params of the focused route anywhere in the tree, rather than of the calling screen. It re-renders on every navigation by design, which is why expo-router documents preferring the local form. |
-| `useNavigation` | P2 | — | React Navigation’s own hook, re-exported by expo-router. It works already through @react-navigation/core; exporting it from here is a decision about what this surface promises, not a build. |
-| `useFocusEffect` | P2 | — | As useNavigation: it is core’s, and it works. The open question is the same one. |
-| `useRootNavigationState` | P3 | — | The root state as a hook. The store `usePathname` reads is already there; this is a second selector over it. |
-| `Drawer` | P3 | Adw.OverlaySplitView | A sidebar navigator. The pattern survives on a desktop better than it does on a phone, and Adwaita has the exact widget — it is a third navigator, not a variation on these two. |
-| `withLayoutContext` | P3 | — | The escape hatch that lets a third-party navigator take its screens from the file tree. It is exactly `useRouteNode` plus screen synthesis, made public — worth doing once a third navigator exists to prove the shape. |
-| `Navigator` | P3 | — | expo-router’s low-level navigator primitive. It belongs with withLayoutContext and for the same reason. |
-| `ErrorBoundary` | P3 | Adw.StatusPage | A per-route error screen. React 19 routes an uncaught error to the root’s handler and @gjsify/gtk-host/react rethrows it from render() — deliberately, so a refusal is not swallowed — and a boundary here has to be reconciled with that rather than bolted beside it. |
-
-### Refused (4)
-
-| export | tier | GTK | why |
-|---|---|---|---|
-| `ExpoRoot` | — | — | It takes a Metro `require.context`, which does not exist in this build chain. `RouterRoot` takes the manifest a bundler plugin emits instead — the same job, with the one input that is available. |
-| `useUnstableGlobalHref` | — | — | Unstable by its own name, and it answers the question usePathname already answers for the only surface this layer has. |
-| `useNavigationContainerRef` | — | — | The container ref is this layer’s own (one process routes one tree), and handing it out would let a consumer dispatch around the refusals `router` exists to give. |
-| `SplashScreen` | — | — | A native splash screen belongs to a phone launcher. A GTK application maps its window when it is ready, which is the desktop equivalent and is Gio.Application’s job, not the router’s. |
-
-<!-- END generated router support table -->
+See **[SUPPORT.md](SUPPORT.md)** — one section per declared surface, generated from
+`src/support-table.ts` in registry order. It is a separate document because
+`react-native`'s section alone is about a hundred table rows and the eighteen surfaces
+together are several hundred; putting them here would bury everything above.
+