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

package/src/types.ts

@@ -0,0 +1,136 @@
+import type { ReactElement } from 'react';
+import type {
+  ImageSourcePropType,
+  StyleProp,
+  ViewProps,
+  ViewStyle,
+} from 'react-native';
+
+/**
+ * What an item's icon can be.
+ *
+ * The union is wide because the two platforms want opposite things and the
+ * caller should not have to care which.
+ *
+ * A native `UITabBar` draws its own items and accepts only `UIImage`, so a
+ * React element has to BECOME an image before it reaches the bar. The JS
+ * Android bar has no such constraint and renders the element directly, at
+ * full fidelity. `src/rasterise.tsx` is the bridge between those two facts.
+ */
+export type LQIcon =
+  /**
+   * A react-native-svg element — which is what a lucide icon is, under the
+   * hood. Rasterised once on iOS, rendered live on Android.
+   */
+  | ReactElement
+  /**
+   * The same, but told whether it is selected. Preferred over a bare element
+   * when the icon changes shape (not just tint) between states: an outline
+   * glyph when idle and a filled one when active, which is what this app's
+   * own set does.
+   *
+   * iOS calls this ONCE, with `selected: false`, because UIKit owns the
+   * selected appearance — see `tintable`.
+   */
+  | ((state: LQIconState) => ReactElement)
+  /** `require('./home.png')`, or `{ uri }`. */
+  | ImageSourcePropType
+  /** A name in the app's own asset catalogue. iOS only. */
+  | { name: string }
+  /** An SF Symbol. iOS only; ignored on Android. */
+  | { sfSymbol: string };
+
+export interface LQIconState {
+  selected: boolean;
+  /** `selectedColor` when selected, `unselectedColor` otherwise. */
+  color: string;
+  size: number;
+}
+
+export interface LQBottomBarItem {
+  /** Shown under the glyph unless `labeled` is false. */
+  title?: string;
+  icon: LQIcon;
+
+  /**
+   * A STABLE identity for this item's icon, and the cache key the
+   * rasteriser memoises on.
+   *
+   * Without it the key is derived from the icon's component type and its
+   * props, which is correct but costs a serialisation per render and misses
+   * when a prop is a function or a style object. Pass this whenever the item
+   * list is static, which it almost always is.
+   */
+  key?: string;
+
+  /**
+   * Whether UIKit may TINT this glyph, iOS only. Default true.
+   *
+   * True renders the image as a template: the alpha channel is the shape and
+   * the system picks the colour, selected against unselected. That is what
+   * makes one artwork cover both states and what makes the glyph follow the
+   * platform's own selected-state treatment.
+   *
+   * Set it false for an icon whose own colours ARE the content — an avatar, a
+   * brand mark — which then looks identical in both states.
+   */
+  tintable?: boolean;
+
+  /** Accessibility label. Falls back to `title`. */
+  accessibilityLabel?: string;
+}
+
+export interface LQBottomBarProps {
+  items: LQBottomBarItem[];
+
+  /**
+   * Which item is lit. JS OWNS THIS, on both platforms: `onTabSelected` is a
+   * report, not a commit, so a press that should not switch tabs (one that
+   * opens a detail screen instead, say) cannot desync the bar.
+   */
+  selectedIndex: number;
+
+  /** Tint for the selected item. Leave unset for the system default. */
+  selectedColor?: string;
+
+  /** Tint for everything else. */
+  unselectedColor?: string;
+
+  /** False hides the titles and re-centres the glyphs. Default true. */
+  labeled?: boolean;
+
+  /** Glyph size in points. Default 24. */
+  iconSize?: number;
+
+  onTabSelected?: (index: number) => void;
+
+  style?: StyleProp<ViewStyle>;
+
+  /**
+   * Forwarded to the native view, because a bar is very often absolutely
+   * positioned over a scrollable page.
+   *
+   * `"box-none"` is the useful value there: the bar's own items stay tappable
+   * while the empty space around them — the safe-area strip below, the gap
+   * either side of an inset pill — passes touches through to the content
+   * underneath instead of swallowing them.
+   */
+  pointerEvents?: ViewProps['pointerEvents'];
+
+  /**
+   * Android only: blur strength behind the bar, 0 disables it and leaves the
+   * flat `androidBackgroundColor` scrim. Default 20.
+   */
+  blurAmount?: number;
+
+  /**
+   * Android only: the material's TINT, painted over the blurred backdrop.
+   *
+   * That order is how UIKit composes a material — blur first, then a
+   * translucent colour on top — and it is why this must stay translucent. An
+   * opaque value stops being a tint and becomes a lid: the blur is still
+   * computed, still costs a software draw of the tree every frame, and is
+   * completely hidden behind it.
+   */
+  androidBackgroundColor?: string;
+}