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

package/src/NativeBottomBar.ts

@@ -0,0 +1,43 @@
+import { Platform, requireNativeComponent } from 'react-native';
+import type {
+  HostComponent,
+  StyleProp,
+  ViewProps,
+  ViewStyle,
+} from 'react-native';
+
+/**
+ * The native view, on whichever platform this is.
+ *
+ * Both platforms register the same component name, and both are legacy view
+ * managers bridged through React Native's interop layer — so there is one
+ * `requireNativeComponent` call and no per-platform file.
+ *
+ * `null` on anything else rather than absent: `requireNativeComponent` throws
+ * at REQUIRE time where the view is not registered, so it cannot sit at module
+ * scope unguarded on, say, web.
+ */
+
+/** The shape the native side is declared with, not the public API. */
+export interface NativeBottomBarProps {
+  items: unknown[];
+  selectedIndex: number;
+  selectedColor?: string;
+  unselectedColor?: string;
+  labeled: boolean;
+  onTabSelected?: (event: { nativeEvent: { index: number } }) => void;
+  style?: StyleProp<ViewStyle>;
+  pointerEvents?: ViewProps['pointerEvents'];
+
+  /** Android only; the iOS bar gets its material from UIKit. */
+  iconSize?: number;
+  blurAmount?: number;
+  scrimColor?: string;
+}
+
+const SUPPORTED = Platform.OS === 'ios' || Platform.OS === 'android';
+
+export const NativeBottomBar: HostComponent<NativeBottomBarProps> | null =
+  SUPPORTED
+    ? requireNativeComponent<NativeBottomBarProps>('LQBottomBarView')
+    : null;

package/src/index.tsx

@@ -0,0 +1,139 @@
+import React, { useMemo } from 'react';
+import { Image, Platform, StyleSheet } from 'react-native';
+
+import { NativeBottomBar } from './NativeBottomBar';
+import { useRasterisedIcons } from './rasterise';
+import type {
+  LQBottomBarItem,
+  LQBottomBarProps,
+  LQIcon,
+  LQIconState,
+} from './types';
+
+export type { LQBottomBarItem, LQBottomBarProps, LQIcon, LQIconState };
+
+/**
+ * THE SYSTEM TAB BAR, HOSTED ANYWHERE.
+ *
+ * A native tab bar normally only exists inside a `UITabBarController`, which
+ * only draws its bar for its own children — so a screen pushed above a tab
+ * navigator cannot have one. That is true of the CONTROLLER, not the BAR:
+ * `UITabBar` is a plain `UIView`, and hosting one directly gets the real
+ * thing rather than a drawing of it. Liquid glass on iOS 26, UIKit's own
+ * selection animation, and the platform's accessibility, on any screen.
+ *
+ * Android has no system bar to borrow, so it draws a matching one: same
+ * dimensions, same tint crossfade and icon bounce, with a blurred backdrop
+ * standing in for the iOS material.
+ *
+ * BOTH PLATFORMS DRAW THEIR OWN ITEMS, which is why `src/rasterise.tsx`
+ * exists: a view that renders its items natively cannot be handed a React
+ * element, so a lucide or SVG icon is captured to a PNG once and the capture
+ * is what crosses the bridge. See that file for the trade this makes and what
+ * it costs.
+ */
+
+/**
+ * ASSETS ARE RESOLVED HERE, and they have to be.
+ *
+ * `require('./home.png')` evaluates to a NUMBER — an id into React Native's
+ * asset registry. The bridge converts that number into `{ uri, scale, ... }`
+ * only for props it knows are image sources, which it learns from the prop's
+ * declared type. `items` is declared as an array, so the bridge has no reason
+ * to look inside it: the number crosses to native as a number, the native
+ * loader finds nothing it recognises, and the bar draws labels with no
+ * glyphs. `Image.resolveAssetSource` does the same conversion by hand, which
+ * is what lets a caller keep writing `require(...)`.
+ */
+const resolveIcon = (icon: LQIcon): unknown => {
+  if (typeof icon === 'number') return Image.resolveAssetSource(icon);
+  return icon;
+};
+
+/**
+ * `overflow: 'hidden'` on Android, always.
+ *
+ * The blurred backdrop is a real child view, so without clipping it squares
+ * off whatever `borderRadius` the caller gave the bar — the corners stay
+ * rounded on the bar's own background while the blur fills them in. iOS needs
+ * none of this: `UITabBar` shapes its own material.
+ */
+const androidClip = StyleSheet.create({
+  bar: { overflow: 'hidden' },
+});
+
+const LQBottomBar = ({
+  items,
+  selectedIndex,
+  selectedColor,
+  unselectedColor,
+  labeled = true,
+  iconSize = 24,
+  onTabSelected,
+  style,
+  pointerEvents,
+  blurAmount = 20,
+  androidBackgroundColor = 'rgba(20, 20, 20, 0.45)',
+}: LQBottomBarProps) => {
+  const { sources, host } = useRasterisedIcons(items, iconSize);
+
+  const nativeItems = useMemo(
+    () =>
+      items.map((item, index) => {
+        const rasterised = sources[index];
+        return {
+          title: item.title,
+          /*
+           A captured glyph wins; otherwise the icon passes through as the
+           image or symbol descriptor it already was — which only iOS can
+           resolve. Until a capture lands this is `undefined`, which draws the
+           item with its title and no glyph for a frame; see the cost note in
+           `rasterise.tsx`.
+          */
+          icon: rasterised ? { uri: rasterised } : resolveIcon(item.icon),
+          // Default true: one artwork, tinted by the platform for both states.
+          tintable: item.tintable !== false,
+          accessibilityLabel: item.accessibilityLabel ?? item.title,
+        };
+      }),
+    [items, sources],
+  );
+
+  if (!NativeBottomBar) return null;
+
+  const platformProps =
+    Platform.OS === 'android'
+      ? {
+          iconSize,
+          blurAmount,
+          scrimColor: androidBackgroundColor,
+        }
+      : // Passing Android-only props to the iOS manager would log an unknown
+        // prop warning for each one on every render.
+        null;
+
+  return (
+    <>
+      {host}
+      <NativeBottomBar
+        style={Platform.OS === 'android' ? [style, androidClip.bar] : style}
+        pointerEvents={pointerEvents}
+        items={nativeItems}
+        selectedIndex={selectedIndex}
+        selectedColor={selectedColor}
+        unselectedColor={unselectedColor}
+        labeled={labeled !== false}
+        {...platformProps}
+        /*
+         A REPORT, NOT A COMMIT. Both bars put their highlight back where
+         `selectedIndex` says it is, so a tap the caller declines to act on —
+         one that opens a detail screen instead of switching tabs — cannot
+         leave the bar showing the wrong item.
+        */
+        onTabSelected={event => onTabSelected?.(event.nativeEvent.index)}
+      />
+    </>
+  );
+};
+
+export default LQBottomBar;

package/src/rasterise.tsx

@@ -0,0 +1,444 @@
+import React, {
+  cloneElement,
+  isValidElement,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { PixelRatio, Platform, StyleSheet, View } from 'react-native';
+import type { ReactElement } from 'react';
+
+import type { LQBottomBarItem, LQIcon } from './types';
+
+/**
+ * TURNING A REACT ICON INTO A UIImage.
+ *
+ * `UITabBar` renders its items natively and accepts only `UIImage`. That is
+ * not a limitation to argue with — it is the reason the bar looks and behaves
+ * like the system's own, since UIKit is drawing the items rather than
+ * compositing someone else's views over them.
+ *
+ * So the icon has to become an image BEFORE it reaches the bar. The way out
+ * is react-native-svg's `toDataURL()`: mount the icon off-screen once, ask the
+ * native SVG view to render itself into a PNG, hand the base64 to the bar,
+ * and remember the result. A lucide icon is a react-native-svg `<Svg>` with a
+ * forwarded ref, so one path covers lucide and hand-written SVG alike.
+ *
+ * THE ALTERNATIVE, for the record: overlay JS icons on top of the native bar.
+ * That accepts any renderer and needs none of this file — but it forfeits
+ * UIKit's selection animation, which is the thing the native bar is for. A
+ * one-off rasterisation is the cheaper trade.
+ *
+ * WHAT THIS COSTS. The first frame for an uncached icon has a title and no
+ * glyph. The cache is module-level, so it is one frame per distinct icon per
+ * app launch, not per mount — and a static `items` array, which is the normal
+ * case, pays it once at startup.
+ */
+
+/**
+ * Captured PNGs, keyed by icon identity. Module scope: see above.
+ *
+ * SUCCESSES ONLY. An earlier version also stored failures here, as an empty
+ * string, to stop an uncapturable icon being retried on every render. That
+ * was a trap: this map outlives every mount AND survives Fast Refresh, so a
+ * failure recorded once was permanent for the life of the JS context. Fixing
+ * the cause — an icon component that did not forward its ref — then changed
+ * nothing, because the poisoned entry was still there and the icon was never
+ * attempted again. Failures are tracked per mount instead; see `failed`.
+ */
+const cache = new Map<string, string>();
+
+/**
+ * Stable ids for component types, so a cache key can name "this icon
+ * component" without stringifying a function.
+ *
+ * Weak, because the key must not be the thing that keeps a lazily-imported
+ * icon module alive.
+ */
+const typeIds = new WeakMap<object, string>();
+let nextTypeId = 0;
+
+const typeId = (type: unknown): string => {
+  if (typeof type === 'string') return type;
+  if (typeof type !== 'function' && typeof type !== 'object') return 'anon';
+  if (type === null) return 'anon';
+  const existing = typeIds.get(type as object);
+  if (existing) return existing;
+  const id = `t${nextTypeId++}`;
+  typeIds.set(type as object, id);
+  return id;
+};
+
+/**
+ * OPAQUE BLACK, and the colour genuinely does not matter.
+ *
+ * The capture is handed to UIKit as a TEMPLATE image: the alpha channel is
+ * the shape and the system chooses the colour. What does matter is that the
+ * colour is RESOLVABLE — lucide defaults `color` to the literal string
+ * `"currentColor"`, which resolves against the `<Svg>`'s own `color` prop, and
+ * with nothing to resolve against the glyph rasterises empty. Setting `color`
+ * on the root is what gives `currentColor` a value.
+ */
+const RASTER_COLOR = '#000000';
+
+/**
+ * The dimension to ask `toDataURL` for, in whichever unit this platform means
+ * by it. See the long note at the call site for why they disagree.
+ */
+const captureSize = (size: number): number =>
+  Platform.OS === 'android' ? Math.round(PixelRatio.get() * size) : size;
+
+/** Props only ever serialised for the cache key, never compared deeply. */
+const stableStringify = (value: unknown): string => {
+  if (value === null || typeof value !== 'object') {
+    // A function in props cannot be serialised, and two renders produce two
+    // identities. Collapse it to its type: a caller whose icon varies by a
+    // callback should pass an explicit `key`.
+    return typeof value === 'function' ? 'fn' : String(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringify).join(',')}]`;
+  }
+  const record = value as Record<string, unknown>;
+  const keys = Object.keys(record).sort();
+  return `{${keys
+    .map(k => `${k}:${stableStringify(record[k])}`)
+    .join(',')}}`;
+};
+
+/** True for the two icon forms that have to be drawn before iOS can use them. */
+const needsRaster = (
+  icon: LQIcon,
+): icon is ReactElement | ((state: never) => ReactElement) =>
+  typeof icon === 'function' || isValidElement(icon);
+
+const cacheKey = (item: LQBottomBarItem, size: number): string | null => {
+  const { icon } = item;
+  if (!needsRaster(icon)) return null;
+
+  const base = item.key
+    ? `k:${item.key}`
+    : typeof icon === 'function'
+    ? `f:${typeId(icon)}`
+    : `e:${typeId((icon as ReactElement).type)}:${stableStringify(
+        (icon as ReactElement).props,
+      )}`;
+
+  return `${base}|${size}`;
+};
+
+/**
+ * Resolve an icon to the element that should actually be drawn, sized and
+ * coloured for capture.
+ */
+const rasterElement = (icon: LQIcon, size: number): ReactElement | null => {
+  if (typeof icon === 'function') {
+    /*
+     ALWAYS THE UNSELECTED FACE. UIKit owns the selected appearance: it tints
+     the one template image it was given. Capturing the selected face too
+     would produce a second artwork fighting the system's own treatment —
+     which is also why `tintable` exists for icons that should opt out.
+    */
+    return icon({ selected: false, color: RASTER_COLOR, size });
+  }
+  if (!isValidElement(icon)) return null;
+
+  const props = (icon.props ?? {}) as Record<string, unknown>;
+  return cloneElement(icon as ReactElement<Record<string, unknown>>, {
+    // Only filled in where the caller left them out, so an icon that sets its
+    // own size or colours keeps them.
+    size: props.size ?? size,
+    width: props.width ?? size,
+    height: props.height ?? size,
+    color: props.color ?? RASTER_COLOR,
+  });
+};
+
+/**
+ * How long to wait for a capture before re-issuing it, and how many times.
+ *
+ * Eight tries at 100ms is 800ms of patience before an icon is written off,
+ * which is generous for something that normally lands on the first frame and
+ * still short enough that a genuinely uncapturable icon does not hold the
+ * off-screen host mounted for the session.
+ */
+const RETRY_MS = 100;
+const MAX_TRIES = 8;
+
+interface CaptureProps {
+  cacheKey: string;
+  node: ReactElement;
+  size: number;
+  onCaptured: (key: string, dataUri: string | null) => void;
+}
+
+/**
+ * One off-screen icon, captured once.
+ *
+ * `toDataURL` needs the NATIVE view to exist and, on Android, to have been
+ * drawn at least once — neither of which is true when the effect first runs:
+ * React has committed the tree, but the native view is mounted and laid out a
+ * frame later. Hence the frame of delay.
+ *
+ * THE WATCHDOG IS NOT BELT-AND-BRACES, it is the only thing covering the worst
+ * failure mode. On Android `SvgViewModule.toDataURL` checks `notRendered()`
+ * and, if the view has not drawn yet, parks the request as a task to be run
+ * from the next `onDraw` — and returns WITHOUT invoking the callback. So a
+ * retry driven from inside the callback cannot fire: nothing ever calls it.
+ * Re-issuing the whole request on a timer is what breaks that deadlock, and
+ * the attempt cap is what stops it running forever if the icon simply cannot
+ * be drawn.
+ */
+const Capture = ({ cacheKey: key, node, size, onCaptured }: CaptureProps) => {
+  const ref = useRef<{ toDataURL?: Function } | null>(null);
+
+  /**
+   * Survives effect re-runs on purpose.
+   *
+   * `cancelled` below is per-run, so a re-run restarts a capture that has not
+   * landed. This one is per-COMPONENT, so a capture that already reported is
+   * never reported twice — which it would be if both flags were the same ref,
+   * and which the earlier version of this file got wrong in the other
+   * direction: a cleanup that set the shared flag killed every subsequent
+   * attempt, so any re-render before the first capture landed meant no glyph
+   * ever appeared.
+   */
+  const reported = useRef(false);
+
+  useEffect(() => {
+    let cancelled = false;
+    let tries = 0;
+    let watchdog: ReturnType<typeof setTimeout> | undefined;
+    let frame = 0;
+
+    const report = (dataUri: string | null) => {
+      if (cancelled || reported.current) return;
+      reported.current = true;
+      if (watchdog) clearTimeout(watchdog);
+      onCaptured(key, dataUri);
+    };
+
+    const issue = () => {
+      if (cancelled || reported.current) return;
+
+      if (tries >= MAX_TRIES) {
+        report(null);
+        return;
+      }
+      tries += 1;
+
+      const svg = ref.current;
+      if (!svg || typeof svg.toDataURL !== 'function') {
+        /*
+         Either the native view is not up yet, or this is not an <Svg> root at
+         all — the usual cause of the latter being an icon wrapped in a <View>,
+         where the ref lands on the wrapper and the SVG underneath is
+         unreachable. Both are retried, because the first resolves itself and
+         the second costs only the attempt budget before falling through to a
+         reported miss.
+        */
+        watchdog = setTimeout(issue, RETRY_MS);
+        return;
+      }
+
+      watchdog = setTimeout(issue, RETRY_MS);
+
+      svg.toDataURL(
+        (base64: string) => {
+          if (base64) {
+            /*
+             `toDataURL` yields BARE base64, not a data URI — the name is a
+             long-standing misnomer in react-native-svg. The prefix is added
+             here so the native side receives something it recognises as an
+             image source.
+            */
+            report(`data:image/png;base64,${base64}`);
+          }
+          // An empty result is left to the watchdog rather than retried here,
+          // so there is one retry path instead of two that can race.
+        },
+        /*
+         THE UNITS DIFFER BY PLATFORM, and getting it wrong fails quietly in
+         two different ways. Hence `captureSize`.
+
+         iOS takes POINTS. The renderer is a `UIGraphicsImageRenderer` at the
+         screen's scale, so a 24-point request yields a 24x24pt / 72x72px PNG
+         on a 3x device; PNG carries no scale, so the native side decodes it
+         with `UIScreen.main.scale` and the two cancel out. Asking for
+         `size * pixelRatio` here would double-apply the scale and draw the
+         glyph three times too large.
+
+         Android takes PIXELS. `SvgView.toDataURL(w, h)` allocates a bitmap of
+         exactly w by h pixels and then draws the SVG in the VIEW's own
+         coordinate space, which is already in pixels — so a 24-pixel bitmap
+         on a 3x device captures the top-left ninth of a 72-pixel glyph and
+         discards the rest. The bitmap has to be the full pixel size, and the
+         native side scales it back down to `size` dp when it draws.
+        */
+        { width: captureSize(size), height: captureSize(size) },
+      );
+    };
+
+    frame = requestAnimationFrame(issue);
+    return () => {
+      cancelled = true;
+      if (watchdog) clearTimeout(watchdog);
+      cancelAnimationFrame(frame);
+    };
+  }, [key, size, onCaptured]);
+
+  return cloneElement(node as ReactElement<{ ref?: unknown }>, { ref });
+};
+
+const styles = StyleSheet.create({
+  /**
+   * OFF-SCREEN, not invisible, and NOT CLIPPED.
+   *
+   * `opacity: 0` and `display: 'none'` are both tempting and both wrong: the
+   * first relies on the renderer still drawing a fully transparent subtree,
+   * and the second detaches the native view so there is nothing left to
+   * capture. Moving it out of the viewport keeps a real, laid-out native view
+   * that the user cannot see.
+   *
+   * No size and no `overflow: 'hidden'` either, which an earlier version had.
+   * Pinning the host to 1x1 and clipping is the obvious way to keep it out of
+   * the way, but on Android a capture is only possible once the SVG has been
+   * drawn at least once — so clipping the icons out of the host is clipping
+   * away the very thing being waited on. Without a size the host sizes itself
+   * to its content, and being off-screen is enough on its own.
+   */
+  host: {
+    position: 'absolute',
+    left: -10000,
+    top: -10000,
+  },
+});
+
+export interface RasterisedIcons {
+  /**
+   * Per item: the captured data URI, or `null` when the icon needs no
+   * rasterising (an image or SF Symbol) or has not been captured yet.
+   */
+  sources: (string | null)[];
+  /** Mount this somewhere in the tree. Renders nothing visible. */
+  host: ReactElement | null;
+}
+
+/**
+ * Capture every React-element icon in `items`, memoised by icon identity.
+ *
+ * Returns the captured sources plus the off-screen host that does the
+ * capturing — the caller has to render the host, since a hook cannot mount
+ * views on its own.
+ */
+export const useRasterisedIcons = (
+  items: LQBottomBarItem[],
+  size: number,
+): RasterisedIcons => {
+  const keys = useMemo(
+    () => items.map(item => cacheKey(item, size)),
+    [items, size],
+  );
+
+  /**
+   * Captures that landed during THIS mount.
+   *
+   * The module cache is the source of truth and survives unmounting, but a
+   * write to it is invisible to the reconciler. This mirror is what actually
+   * triggers the re-render; it is only ever added to, and it is seeded from
+   * nothing because a warm cache needs no re-render — `sources` reads it
+   * directly on the first pass.
+   */
+  const [captured, setCaptured] = useState<Record<string, string>>({});
+
+  /**
+   * Icons that could not be captured DURING THIS MOUNT.
+   *
+   * Held in a ref rather than in the module cache so the scope is right in
+   * both directions: within a mount an icon is attempted once, so a glyph that
+   * genuinely cannot be drawn does not spin; across mounts the slate is clean,
+   * so remounting the bar — or a Fast Refresh that fixed the icon — gets
+   * another go. A permanent record of failure is what made a fixed icon stay
+   * broken until the app was killed.
+   */
+  const failed = useRef<Set<string>>(new Set());
+
+  const onCaptured = useCallback((key: string, dataUri: string | null) => {
+    if (dataUri) {
+      cache.set(key, dataUri);
+    } else {
+      failed.current.add(key);
+      if (__DEV__) {
+        /*
+         LOUD, because the failure is otherwise invisible: the item renders
+         with its title and no glyph, which reads as a styling problem rather
+         than a capture that never happened.
+        */
+        console.warn(
+          `[lq-bottom-bar] Could not rasterise the icon for "${key}". ` +
+            'The icon must be a react-native-svg <Svg> element, or a component ' +
+            'that forwards its ref to one — a plain function component drops ' +
+            'the ref and cannot be captured. Wrap it in React.forwardRef.',
+        );
+      }
+    }
+    setCaptured(prev => ({ ...prev, [key]: dataUri ?? '' }));
+  }, []);
+
+  const sources = useMemo(
+    () =>
+      keys.map(key => {
+        if (!key) return null;
+        return cache.get(key) ?? null;
+      }),
+    // `captured` is what makes this re-run; the cache it reads is module state.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [keys, captured],
+  );
+
+  const pending = useMemo(
+    () =>
+      keys
+        .map((key, index) => ({ key, index }))
+        .filter(
+          (entry): entry is { key: string; index: number } =>
+            entry.key !== null &&
+            !cache.has(entry.key) &&
+            !failed.current.has(entry.key),
+        ),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [keys, captured],
+  );
+
+  const host =
+    pending.length === 0 ? null : (
+      <View style={styles.host} pointerEvents="none" collapsable={false}>
+        {pending.map(({ key, index }) => {
+          const node = rasterElement(items[index].icon, size);
+          if (!node) return null;
+          return (
+            /*
+             `onCaptured` IS PASSED AS-IS, not wrapped in an arrow.
+
+             An inline `dataUri => onCaptured(key, dataUri)` is a new function
+             identity on every render, which lands in `Capture`'s effect deps
+             and re-runs the effect — tearing down an in-flight capture on
+             every parent render. The key travels as a prop instead so the
+             callback can stay stable.
+            */
+            <Capture
+              key={key}
+              cacheKey={key}
+              node={node}
+              size={size}
+              onCaptured={onCaptured}
+            />
+          );
+        })}
+      </View>
+    );
+
+  return { sources, host };
+};