Mobile v4 docs: mobile-ui install, list item reference, binding and build gaps

[simonhamp]

We had agents build the same small todo app on NativePHP Mobile v4 (nativephp/mobile 4.5.2, nativephp/mobile-ui 0.6.0). They read the docs through the MCP server and still kept opening vendor source, mostly ListItem.php. This fills the gaps they hit. Every claim here was checked against those two released versions, most of them in a scratch Laravel app with a Pest test.

What was missing or wrong:

• Nothing in installation or quick start told you to install and register nativephp/mobile-ui. Without it, <native:button> throws Unknown native element type and <native:text> / <native:column> draw nothing on device, because their renderers live in the plugin.
• Several pages still called the package nativephp/native-ui or linked to a repo that doesn't exist.
• <native:text-input> was used in data binding, lifecycle hooks and testing examples. That tag doesn't exist; it's outlined/filled/bare.
• The testing example used wire:model instead of native:model.
• List item: kebab-case spellings like leading-icon are silently dropped, leadingCheckbox="false" renders checked, and @trailing-press / on-trailing-press are ignored in 0.6.0. The accessibility page had an @trailing-press example that can never work, because core turns unknown @name attributes into child-component events.
• No guidance on when to debounce native:model. Live binding on a fast typist loses characters in 0.6.0 (Text input: a late echo of an earlier keystroke overwrites newer text (characters vanish while typing) mobile-ui#95).
• Nowhere said where native:run leaves the simulator .app and debug .apk.

What changed:

• Installation and quick start lead with laravel new my-app --using=nativephp/mobile-starter. The starter kit now requires mobile-ui ^0.6 (Require nativephp/mobile-ui ^0.6 and list it in boost.json mobile-starter#12), so no extra step is needed after it. A sentence explains that --no-node skips the npm install and build a SuperNative app doesn't need, and that laravel new also installs Laravel Boost for AI agent guidelines (--no-boost skips it). For an existing app, and on the EDGE intro and Native UI pages, they cover installing and registering mobile-ui.
• New "Attribute names" section on the EDGE intro page covering exact spellings and boolean binding with :.
• List page: a spelling note for list-item, handler argument order, a11y-label / a11y-hint, and a short "Testing a list" section. on-trailing-press and headline-line-through are documented with a note that they need the mobile-ui release containing Read on-trailing-press on list items mobile-ui#108 and Feature: new billing flow #109. Neither is promised for 0.6.0. The accessibility example now uses on-trailing-press with the same note.
• Text input gets a "Choosing a sync mode" section, and notes that @submit gets the field's text as its last argument. Data binding links to it.
• Development page gets "Finding the built app": output paths, install commands, and why to keep NATIVEPHP_APP_VERSION=DEBUG for shared builds (a fixed version only re-extracts when version or build number changes).
• A short aside for people running composer create-project nativephp/mobile-starter directly: add --stability=dev or you get the old v3 tag.
• Testing intro gets a setup section (Pest install, plugin registration applies in tests). Interactions shows how to target list row callbacks by expression.

How I tested: DocumentationRenderingTest and DocumentationTableOfContentsTest pass, and I rendered each changed page to check the new anchors and the escaped {{ }} in prose. The list-item, boolean and text-input behaviour was confirmed with a Pest test in a fresh Laravel app on the released packages. The build output paths come from reading RunsIos/RunsAndroid in 4.5.2. I didn't run a device build.

What to watch: the #108 and #109 notes should be replaced with a version number once those ship. #530 and #511 also touch list.md but in different sections, so they should merge cleanly.

🤖 Generated with Claude Code