Skip to content

docs(mobile/v4): native-ui component audit — close the gaps between code and docs#426

Open
shanerbaner82 wants to merge 20 commits into
mainfrom
docs/mobile-v4-native-ui-audit
Open

docs(mobile/v4): native-ui component audit — close the gaps between code and docs#426
shanerbaner82 wants to merge 20 commits into
mainfrom
docs/mobile-v4-native-ui-audit

Conversation

@shanerbaner82

@shanerbaner82 shanerbaner82 commented Jul 11, 2026

Copy link
Copy Markdown
Contributor

Summary

A full audit compared every native-ui component (Elements, Components, Builders, traits, and both platform renderers) against the v4 mobile docs. This PR closes the gaps it found, plus carries two small follow-ups from local work.

New documentation

  • <native:bare-text-input> — the chromeless third text-input variant was completely undocumented (class-based styling pass-through, color attribute, chat-pill patterns)
  • Drawer / FloatingOverlay builder APIs — make(), width() defaults, modal()/reveal(), top()/bottom(), offset() null semantics
  • InteractsWithDrawer / InteractsWithFloatingOverlay per-screen override traits and their precedence, plus the drawer's built-in interaction model
  • keep-focus-on-submit, list plain prop + automatic inset-grouped style, per-platform icon signatures across components, dark-color on icon, sync-mode/debounce-ms as direct props with the 300ms default

Corrections (docs described things that don't exist or don't work)

  • List @leading-change / @trailing-change / @trailing-press Blade events were never wired — re-documented as the Element callbacks they actually are, with platform notes
  • Slider size prop/method removed — no renderer reads it
  • icon.md pointed at a dead plugin class — now the registered core Element with its real signatures
  • Badge/chip "no per-instance overrides" claims corrected (bg-* / rounded-* apply); chip label is optional; list separator is cross-platform; carousel clip shape is platform-specific; text-input font contradiction resolved
  • a11y-hint documented everywhere it's supported

Companion fixes in other repos (documented spellings now work)

  • NativePHP/native-ui fix/progress-bar-track-color-attr — track-color kebab attr
  • NativePHP/mobile-air element branch — kebab-case side-nav attributes

Also includes: --core-v4 uninstall flag in the upgrade guide, the new Floating overlay layouts section, and last night's custom-fonts docs commit.

🤖 Generated with Claude Code

shanerbaner82 and others added 9 commits July 11, 2026 11:56
@shanerbaner82 @claude
docs(mobile/4): custom fonts + leading-* line height
91db92f 
Text gets Custom fonts (font="Name" from resources/fonts/, bundled at
build; iOS PostScript matching, Android assets) and Line height sections
(leading-* multipliers + arbitrary [1.4]/[24px], with the iOS additive-
spacing caveat). Button and the text inputs cross-reference the font
attribute; the inputs note leading is Android-only for typed text.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@shanerbaner82 @claude
docs(mobile/v4): document --core-v4 plugin uninstall flag in the upgr…
4b4554a 
…ade guide

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@shanerbaner82 @claude
docs(mobile/v4): Floating overlay section in SuperNative layouts
8206c4c 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@shanerbaner82 @claude
docs(mobile/v4): text inputs — bare variant, keep-focus-on-submit, co…
54868f9 
…rrections

Documents the previously-missing <native:bare-text-input> (chromeless
variant with class-based styling pass-through and a color attribute),
the keep-focus-on-submit prop for chat composers, password keyboard
type, sync-mode/debounce-ms as direct props with the 300ms default,
per-platform leadingIcon()/trailingIcon() signatures, and lineHeight
attributes. Drops the stale 'no font overrides' claim.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@shanerbaner82 @claude
docs(mobile/v4): selection controls — drop no-op slider size, sync pr…
de4f42f 
…ops, a11y

Removes the slider size prop/method (never read by either renderer),
documents sync-mode/debounce-ms on checkbox and the 300ms debounce
default, adds a11y props to radio children, notes select options are
flat display strings, and adds theme-styling asides matching toggle's.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@shanerbaner82 @claude
docs(mobile/v4): buttons & indicators — icon element API, per-platfor…
7b1a01d 
…m icons, a11y-hint

Corrects icon.md to the registered core Element class and documents its
full make()/name() signatures, enum-bound :ios/:android attrs, and
dark-color. Documents per-platform icon() signatures on button, chip
and tab items, the text-only button slot, lineHeight attrs, NavAction
menus, badge/chip style overrides (bg-*/rounded-*), optional chip
label, and a11y-hint across all seven pages.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@shanerbaner82 @claude
docs(mobile/v4): lists — plain prop, Element-only toggle callbacks, p…
2368b0b 
…latform accuracy

The @leading-change/@trailing-change/@trailing-press Blade events were
documented but never wired (not in the precompiler whitelist) — they
are now documented as the Element callbacks they actually are, with
platform interactivity noted. Adds the plain prop and the automatic
inset-grouped style for sectioned lists, per-platform list-item icon
attrs and signatures, the shared badge icon key, the auto ellipsis
anchor for trailing-menu, ListSection methods, and the virtual-list
default window (rows 0-29). Marks separator cross-platform.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@shanerbaner82 @claude
docs(mobile/v4): drawer & floating-overlay builder APIs and per-scree…
5896e69 
…n overrides

Documents the Drawer builder (make/width/modal/reveal, default width),
its built-in interaction model (auto hamburger, edge-swipe, scrim tap,
auto-close on drawer-less screens), the FloatingOverlay builder
(top/bottom/offset semantics), and the InteractsWithDrawer /
InteractsWithFloatingOverlay per-screen override traits with their
precedence.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@shanerbaner82 @claude
docs(mobile/v4): overlays & tabs — a11y-hint, carousel a11y + clip sh…
9c61acf 
…ape, per-platform tab icons

Adds a11y-hint to modal, bottom-sheet and tab-row; gives carousel its
missing a11y props/methods and corrects the clip shape (16pt on iOS,
Material extraLarge on Android); documents sync-mode on tab-row and
the per-platform Tab::icon() signature.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@shanerbaner82 shanerbaner82 requested a review from simonhamp July 11, 2026 16:06
shanerbaner82 and others added 9 commits July 11, 2026 16:36
@shanerbaner82 @claude
docs(mobile/v4): gestures — document only the shipped animation surface
e2a5b56 
@drag-end described unshipped phase-3b behavior: it isn't in the
precompiler event whitelist, GestureArea never reads it, and no
callback is registered, so the documented handler never fired. Both
pages now center on what works — pan-y SharedValue binding, chainable
interpolate/clamp/multiply/add formulas, the animatable props, and
PHP-side ->value() reads.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@shanerbaner82 @claude
docs(mobile/v4): core element fixes — divider example, rect children,…
e6582b7 
… scroll-view props

Divider::make()->borderColor() doesn't exist (fatals) — the real API is
->border(width, color). <native:rect> is self-closing, so the badge
example that nested text inside it never rendered; it now layers with a
stack. scroll-view gains the undocumented axis (vertical/horizontal/
both) and scroll-anchor=bottom props plus an Element section.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@shanerbaner82 @claude
docs(mobile/v4): command reference — add the missing commands
08a9d30 
native:make, native:rm, native:make-test, native:validate,
native:debug, native:emulator and native:sim were absent from the
'complete reference'; native-ui:generate-icons joins the plugin
section. native:font is intentionally left to the in-flight custom
fonts work.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@shanerbaner82 @claude
docs(mobile/v4): icons — point enum examples at native-ui:generate-icons
ef70041 
The App\Icons enums used in icon.md's examples don't exist until the
generator runs; both pages now say so, and icons.md leads its
platform-specific section with the first-class ios/android attributes
instead of the System::isIos() ternary.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@shanerbaner82 @claude
docs(mobile/v4): routing — @Navigate directive; pressable — @Doubletap …
20b8d7f 
…+ press feedback

routing.md now documents the @Navigate Blade directive where readers
look: short and args forms, the eight transition modifiers, and the
.back/.replace/.exitToWeb actions (combinable). Transition::ParallaxPush
joins the enum list. pressable.md lists @Doubletap and @Navigate and
gains a press-feedback section (press-scale/press-opacity/
press-translate-y) linking to the animation guide.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@shanerbaner82 @claude
docs(mobile/v4): typography — full text styling surface, complete cla…
7ae779a 
…ss table

text.md documents the shipped italic/underline/line-through/
text-transform/letter-spacing/font-family surface (classes, attributes,
Element methods) and the 1-7 weight clamp. layout.md's class table adds
the missing families (leading-*, tracking-*, font style/family, text
decoration/transform, flex-wrap, aspect, object-fit) and @Doubletap
joins the shared events. Button/text-input line-height props move to
the kebab spellings now accepted by the elements.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@shanerbaner82 @claude
docs(mobile/v4): new pages for lazy-grid and refreshable
74a7717 
Both elements ship with renderers on each platform but had zero docs.
lazy-grid covers columns/gap/horizontal, cell sizing, and Android's
bounded-height requirement for true lazy composition; refreshable
covers @refresh, the it-is-the-scroll-container rule, the ~800ms
spinner window, and when to prefer list's built-in on-refresh.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@shanerbaner82 @claude
docs(mobile/v4): per-screen chrome — TabBarOptions, full NavBarOption…
3cd0eef 
…s, side-nav browser opt

bottom-nav.md gains the previously-undocumented per-screen surface:
tabBarOptions() with hidden/highlight/activeColor/backgroundColor and
the hidesTabBar shortcut. top-bar.md now lists every NavBarOptions
field, side-nav.md documents open-in-browser, and layouts.md mentions
the native-ui-layouts publish tag.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@shanerbaner82 @claude
docs(mobile/v4): testing — assertDontSee, assertNotSet, assertTransition
2796f5d 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@shanerbaner82

shanerbaner82 commented Jul 11, 2026

Copy link
Copy Markdown
Contributor Author

Second batch pushed — a full sweep of the remaining docs surface (core EDGE components, the-basics, testing, commands):

  • Fixed docs that didn't match reality: @drag-end (unshipped phase 3b) removed from the gesture pages, which now document the shipped native-driven animation surface; divider's fatal borderColor() example; the self-closing <native:rect> children claim; icon enum examples now point at native-ui:generate-icons.
  • New pages: lazy-grid and refreshable (both shipped with zero docs).
  • New coverage: @navigate in routing (all modifiers), @doubleTap, press feedback on pressable, per-screen TabBarOptions/hidesTabBar, the full NavBarOptions field set, scroll-view axis/scroll-anchor, the complete Tailwind class table (typography families), testing assertions, seven missing native:* commands.
  • Companion code fixes (mobile-air element / native-ui fix/progress-bar-track-color-attr): kebab-case attributes now accepted on text typography props (font-size etc. were silently dropped — the docs' spellings never worked as direct attributes), bottom-nav-item badge-color, and button/text-input line-height.

native:font and the app-wide default-font config are deliberately left to the in-flight custom-fonts work.

🤖 Generated with Claude Code

shanerbaner82 and others added 2 commits July 11, 2026 21:50
@shanerbaner82 @claude
docs(mobile/4): chrome fonts + single-file weight caveat
06203da 
Layouts gets a Chrome fonts section: the three override tiers (layout
$font, bar ->font(), per-screen options), fallthrough to the theme
default, and the iOS limits (system large titles keep the app default;
Liquid Glass tab labels aren't fontable). Text's custom-fonts aside now
warns that a single-file font has one weight — Android synthesizes a
faux bold while iOS ignores the weight — so bundle and reference the
real Bold file instead of font-bold until multi-weight families land.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@shanerbaner82 @claude
Mobile v4: document the color value grammar
c187fd5 
Theming gets a "Color values" section — hex (incl. CSS #RRGGBBAA
alpha), Tailwind palette names, white/black/transparent, and /N opacity
modifiers, accepted for theme tokens, element color props, and
arbitrary classes — plus notes that components render tokens solid
(tonal fills are authored on the token) and disabled controls draw the
surface-variant / on-surface-variant pair.

Button documents the disabled/loading token styling and the
tonal-via-token pattern; List's color-override props link to the
grammar instead of claiming hex-only.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@simonhamp simonhamp Awaiting requested review from simonhamp

At least 2 approving reviews are required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@shanerbaner82