@honeypathkar/react-native-lq-bottom-bar 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 honeypathkar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,342 @@
-# Temporary Holding Version
+# react-native-lq-bottom-bar
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The **real** iOS `UITabBar` — liquid glass on iOS 26, UIKit's own selection
+animation, the system's accessibility — on **any** screen. Plus a matching
+Android bar with a blurred backdrop.
+
+Takes **React icons**, not only images.
+
+```jsx
+import LQBottomBar from '@honeypathkar/react-native-lq-bottom-bar';
+import { House, Ticket, MessageCircle, User } from 'lucide-react-native';
+
+<LQBottomBar
+  style={{ height: 49 + insets.bottom }}
+  selectedIndex={index}
+  onTabSelected={setIndex}
+  selectedColor="#4F8EF7"
+  items={[
+    { key: 'home', title: 'Home', icon: <House /> },
+    { key: 'events', title: 'Events', icon: <Ticket /> },
+    { key: 'chat', title: 'Chats', icon: <MessageCircle /> },
+    { key: 'profile', title: 'Profile', icon: <User /> },
+  ]}
+/>;
+```
+
+## Why this exists
+
+A native tab bar normally only exists inside a `UITabBarController`, and a
+`UITabBarController` only draws its bar for its own child view controllers. So
+a screen pushed **above** a tab navigator cannot have one, and every app ends
+up hand-drawing a replacement that does not quite match.
+
+That constraint is real for the **controller**. It is not real for the **bar**.
+`UITabBar` is a plain `UIView`: it can be added to any hierarchy, given
+`UITabBarItem`s, and told which one is selected. Doing that gets the genuine
+control rather than a copy of it —
+
+- On iOS 26 the system applies **liquid glass**, including the scroll-edge
+  treatment, because the appearance is resolved by the bar itself and not by
+  its controller.
+- The selection animation, the icon bounce and the label crossfade are UIKit's
+  own.
+- VoiceOver, Dynamic Type, Reduce Motion and the high-contrast variants all
+  come for free, because this **is** the system control.
+
+## Install
+
+```sh
+npm install @honeypathkar/react-native-lq-bottom-bar react-native-svg
+cd ios && pod install
+```
+
+Autolinked on both platforms. `react-native-svg` is a peer dependency, needed
+only for React-element icons — which is the point of the package, so you almost
+certainly want it.
+
+---
+
+## Icons
+
+`items[].icon` accepts any of:
+
+| Form | Example | Platforms |
+| --- | --- | --- |
+| React element | `<House />`, any `<Svg>` | iOS, Android |
+| Render function | `({ selected, color, size }) => <Icon … />` | iOS, Android |
+| Bundled asset | `require('./home.png')` | iOS |
+| Asset catalogue | `{ name: 'home' }` | iOS |
+| SF Symbol | `{ sfSymbol: 'house.fill' }` | iOS |
+
+### ⚠️ Your icon must forward its ref to an `<Svg>`
+
+**This is the single most common reason icons do not appear.** Read it before
+anything else.
+
+Both platforms draw their own tab items natively, so a React icon has to become
+a PNG before it reaches the bar. The capture is done through react-native-svg's
+`toDataURL()`, which needs a ref on the `<Svg>` itself. A plain function
+component **silently drops the ref**:
+
+```jsx
+// ✗ Ref goes nowhere. Renders a title with no glyph.
+const HomeIcon = ({ size }) => <Svg width={size} height={size}>…</Svg>;
+
+// ✓ Ref reaches the Svg.
+const HomeIcon = forwardRef(({ size }, ref) => (
+  <Svg ref={ref} width={size} height={size}>…</Svg>
+));
+HomeIcon.displayName = 'HomeIcon';
+```
+
+Lucide icons already do this — `createLucideIcon` is built on `forwardRef` and
+passes the ref straight to its `<Svg>` — so `lucide-react-native` works
+unmodified. Your own icon components probably do not, unless you wrote them
+that way.
+
+The same applies to an icon wrapped in a `<View>`: the ref lands on the wrapper
+and the SVG underneath is unreachable.
+
+In development the package **warns** when a capture fails, naming the item:
+
+```
+[lq-bottom-bar] Could not rasterise the icon for "home". The icon must be a
+react-native-svg <Svg> element, or a component that forwards its ref to one …
+```
+
+If you see a bar with labels and no glyphs, check your logs for that line.
+
+### How a React element becomes a tab-bar icon
+
+A `UITabBar` renders its items natively and accepts only `UIImage`. That is not
+a limitation to argue with — it is precisely **why** the bar looks and behaves
+like the system's own, since UIKit draws the items rather than compositing
+someone else's views over them. The Android bar draws its own items too.
+
+So the package mounts each icon off-screen once, captures it with `toDataURL()`,
+hands the base64 to the native bar, and memoises the result by icon identity.
+
+The alternative — overlaying JS icons on top of the native bar — accepts any
+renderer and needs none of this, but forfeits UIKit's selection animation,
+which is the thing the native bar is for. A one-off rasterisation is the
+cheaper trade.
+
+**What it costs.** The first frame for an uncached icon shows the title with no
+glyph. Successful captures are cached at module scope, so that is one frame per
+distinct icon per app launch, not per mount.
+
+**Failures are not cached across mounts.** An icon that could not be captured is
+retried next time the bar mounts, rather than being written off for the life of
+the JS context — otherwise fixing a broken icon during a Fast Refresh session
+would appear to do nothing, because the failure would outlive the fix.
+
+### Tinting, and the solid face
+
+The capture is handed to the platform as a **template**: its alpha channel is
+the shape and the system picks the colour, selected against unselected. One
+artwork covers both states and follows the platform's own treatment.
+
+This means you want the **solid, opaque** face of a two-state icon, not the
+outlined one. An outline variant wrapped in `<G opacity="0.5">` bakes
+half-transparency into the alpha and comes out washed out in **both** states:
+
+```jsx
+// Rasterise the solid face. The system decides the colour from there.
+icon: ({ size }) => <MyIcon isActive size={size} />;
+```
+
+Set `tintable: false` on an item whose own colours **are** the content — an
+avatar, a brand mark. It will then look identical selected and not, which is
+right for those and wrong for a glyph.
+
+### Cache keys
+
+Captures are memoised by icon identity. Pass a stable `key` per item whenever
+the list is static, which it nearly always is:
+
+```jsx
+{ key: 'home', title: 'Home', icon: <House /> }
+```
+
+Without it the key is derived from the icon's component type and a
+serialisation of its props — correct, but it costs that serialisation on every
+render, and it collapses any function-valued prop into a single bucket.
+
+---
+
+## Props
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `items` | `LQBottomBarItem[]` | — | `{ title?, icon, key?, tintable?, accessibilityLabel? }` |
+| `selectedIndex` | `number` | — | **You own this**; see below |
+| `onTabSelected` | `(index: number) => void` | — | A report, not a commit |
+| `selectedColor` | `string` | system | Tint for the selected item |
+| `unselectedColor` | `string` | system | Tint for the rest |
+| `labeled` | `boolean` | `true` | `false` hides titles and re-centres the glyphs |
+| `iconSize` | `number` | `24` | Points |
+| `style` | `ViewStyle` | — | The bar is laid out by Yoga; height and width are whatever this says |
+| `pointerEvents` | `ViewProps['pointerEvents']` | — | `"box-none"` lets touches through the empty space around the items |
+| `blurAmount` | `number` | `20` | **Android only.** `0` disables the blur entirely |
+| `androidBackgroundColor` | `string` | `rgba(20,20,20,0.45)` | **Android only.** The material's tint, over the blur — keep it translucent |
+
+### `selectedIndex` is yours, on purpose
+
+`onTabSelected` **reports** a press; it does not commit to it. Both bars put
+their highlight back where `selectedIndex` says it is after every press, so a
+tap you decline to act on — one that opens a detail screen instead of switching
+tabs — cannot leave the bar showing the wrong item.
+
+```jsx
+onTabSelected={index => {
+  if (index === HOME && activePremise) {
+    navigation.navigate('PremiseDetail');   // declined: the bar does not move
+    return;
+  }
+  setIndex(index);
+}}
+```
+
+---
+
+## Layout: in flow, or overlaid?
+
+The bar is sized entirely by `style`. UIKit's standard body is **49pt**,
+excluding the home-indicator inset:
+
+```jsx
+style={{ height: 49 + insets.bottom }}
+```
+
+`marginHorizontal` plus a `borderRadius` narrows it into a floating pill; the
+bar spreads its items evenly across whatever width it ends up with.
+
+**Decide early which of these two you are doing, and apply it consistently.**
+Mixing them is the single biggest source of layout bugs with this component.
+
+**In flow** — the bar is an ordinary flex child and claims its own band:
+
+```jsx
+<View style={{ flex: 1 }}>
+  <View style={{ flex: 1 }}>{screens}</View>
+  <LQBottomBar style={{ height: 49 + insets.bottom }} … />
+</View>
+```
+
+Every screen's viewport ends where the bar begins, so a control pinned at
+`bottom: 0` sits above it and **no screen should add clearance** — doing so
+reserves the band twice and opens a strip of dead page. The cost is that a
+translucent `UITabBar` has only your root view behind it, so the material
+renders over whatever colour that is. Give the container a background you are
+happy to see through glass.
+
+**Overlaid** — the bar floats over the content:
+
+```jsx
+<LQBottomBar
+  pointerEvents="box-none"
+  style={{ position: 'absolute', left: 0, right: 0, bottom: 0,
+           height: 49 + insets.bottom }}
+  …
+/>
+```
+
+This is what the material is designed for: the page runs underneath and the
+glass refracts it. But then **every** screen must reserve the bar's height
+itself — scroll views via `contentContainerStyle.paddingBottom`, pinned
+controls via `bottom`. Any screen that forgets gets its bottom content covered.
+
+---
+
+## Android
+
+There is no system bottom bar to borrow — Material's `NavigationBarView` is a
+different control with its own shape and opinions — so the Android bar is drawn
+to match: same dimensions, same tint crossfade, same icon bounce on UIKit's own
+timing curve, with a blurred backdrop standing in for the iOS material.
+
+Styling comes from React Native's standard props, because the view subclasses
+`ReactViewGroup`: `borderRadius`, `backgroundColor`, `overflow` and elevation
+all work as they do on a `<View>`.
+
+### The blur, and its one real limitation
+
+Android has no API for blurring what is **behind** a view.
+`RenderEffect.createBlurEffect` blurs a view's *own* content, and
+`Window.setBackgroundBlurRadius` applies to a window, not a view inside one. So
+the backdrop is produced the way every Android blur library produces it: draw
+the root view into a small off-screen bitmap, blur that, and paint it under the
+bar's contents. `RenderEffect` does the blur on API 31+; a three-pass box blur
+does it below that.
+
+That technique uses a **software** draw, and content the GPU owns exclusively
+does not participate. A `SurfaceView` or `TextureView` — **video, a map, a
+camera preview** — captures as a blank region, so the bar reads as frosted over
+nothing there. There is no fix available from inside the view hierarchy. Where
+that matters, pass `blurAmount={0}` and let the flat `androidBackgroundColor`
+scrim carry the bar; the capture work and its per-frame cost stop entirely.
+
+No JitPack dependency is involved, deliberately — the obvious off-the-shelf
+choice would force every consuming app to add that repository to its own
+`settings.gradle` before this package would resolve.
+
+---
+
+## Troubleshooting
+
+**Labels show but glyphs do not.** Your icon component is not forwarding its
+ref to an `<Svg>`. See the warning section above — this is nearly always it.
+
+**A white or mismatched strip under the bar.** The bar is in flow and the
+translucent material has only your root view behind it. Give that container a
+background colour, or move to the overlaid layout.
+
+**Dead space above the bar.** Something is reserving the bar's height twice —
+usually an in-flow bar plus a screen that also adds bottom clearance.
+
+**`Unable to resolve module` when linked with `file:`.** Metro only serves
+files under roots it knows about; add the package's real path to
+`watchFolders`. Metro reads its config once at startup, so restart it.
+
+**`Cannot read property 'useMemo' of null` when linked with `file:`.** Two
+copies of React — the linked package has its own in `node_modules`. Pin the
+singletons in `metro.config.js`; `extraNodeModules` will **not** do it, because
+it is only a fallback for modules that fail to resolve, and these resolve fine
+to the wrong copy:
+
+```js
+const SINGLETONS = ['react', 'react-native', 'react-native-svg'];
+
+resolver: {
+  resolveRequest: (context, moduleName, platform) =>
+    context.resolveRequest(
+      SINGLETONS.some(n => moduleName === n || moduleName.startsWith(`${n}/`))
+        ? { ...context, originModulePath: path.join(__dirname, 'index.js') }
+        : context,
+      moduleName,
+      platform,
+    ),
+}
+```
+
+---
+
+## Architecture notes
+
+Both platforms use a **legacy view manager**, bridged through React Native's
+interop layer, rather than a Fabric component. On iOS a Fabric component view
+must be written in Objective-C++, which cannot host Swift directly and
+interacts badly with `use_frameworks!` linkage; on Android it would need a
+codegen spec kept in step for no behaviour this bar needs.
+
+The podspec calls `install_modules_dependencies` rather than depending on
+`React-Core` directly. With the new architecture on, a pod that touches React
+headers needs the whole Fabric/JSI header surface and its flags; `React-Core`
+alone leaves `jsi/jsi.h` off the search path, and the failure then surfaces
+inside React's **own** targets — which looks like a broken app rather than a
+bad podspec.
+
+## License
+
+MIT

package/android/build.gradle

@@ -0,0 +1,78 @@
+buildscript {
+    ext {
+        buildToolsVersion = "34.0.0"
+        minSdkVersion = 24
+        compileSdkVersion = 35
+        targetSdkVersion = 35
+        kotlinVersion = "1.9.24"
+    }
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath "com.android.tools.build:gradle:8.2.1"
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion"
+    }
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+android {
+    namespace "com.honeypathkar.lqbottombar"
+    compileSdkVersion getExtOrDefault("compileSdkVersion", 35)
+
+    defaultConfig {
+        minSdkVersion getExtOrDefault("minSdkVersion", 24)
+        targetSdkVersion getExtOrDefault("targetSdkVersion", 35)
+    }
+
+    buildTypes {
+        release {
+            minifyEnabled false
+        }
+    }
+
+    lintOptions {
+        disable "GradleCompatible"
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+
+    kotlinOptions {
+        jvmTarget = "17"
+    }
+}
+
+def getExtOrDefault(name, defaultValue) {
+    return rootProject.ext.has(name) ? rootProject.ext.get(name) : defaultValue
+}
+
+def getKotlinVersion() {
+    return rootProject.ext.has("kotlinVersion") ? rootProject.ext.get("kotlinVersion") : "1.9.24"
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation "com.facebook.react:react-native:+"
+    implementation "org.jetbrains.kotlin:kotlin-stdlib:${getKotlinVersion()}"
+    implementation "androidx.core:core-ktx:1.13.1"
+
+    // NO BLUR LIBRARY, deliberately.
+    //
+    // The obvious candidate is Dimezis/BlurView, but it is published on
+    // JitPack: every consuming app would have to add that repository to its
+    // own settings.gradle before this package would even resolve, which is a
+    // poor thing to impose from a dependency. The backdrop blur is instead
+    // implemented against the platform in BackdropBlur.kt — the same
+    // capture-downscale-blur technique, using RenderEffect where the platform
+    // has it and a stack blur below that.
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />