@hzblj/kara-components 0.2.0 → 0.3.0

package/lib/module/organisms/sheet/use-sheet-header.js

@@ -0,0 +1,118 @@
+"use strict";
+
+import { isScrollEdgeEffectAvailable } from '@hzblj/kara-native';
+import { spacing } from '@hzblj/kara-theme';
+import { useCallback, useMemo, useRef, useState } from 'react';
+import { Platform } from 'react-native';
+import { Box } from "../../atoms/box/index.js";
+import { RnText } from "../../atoms/rn-text/index.js";
+import { NavigationBar } from "../../molecules/navigation-bar/index.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** The bar's own height (`NavigationBar`) plus the room above it, before the header has been measured. */
+const ESTIMATED_HEADER_HEIGHT = (Platform.OS === 'ios' ? 56 : 64) + spacing.s16;
+
+/** Where a large title's bar title appears once it has scrolled away: the platform's own place for it. */
+const COLLAPSED_TITLE_ALIGNMENT = Platform.OS === 'ios' ? 'center' : 'leading';
+
+/** Lays the header over the content so the content can scroll under it — the edge effect needs it there. */
+const OVERLAY_HEADER_STYLE = {
+  left: 0,
+  position: 'absolute',
+  right: 0,
+  top: 0,
+  zIndex: 1
+};
+const SOFT_EDGE_EFFECTS = {
+  bottomScrollEdgeEffect: 'soft',
+  topScrollEdgeEffect: 'soft'
+};
+const SheetLargeTitle = ({
+  onLayout,
+  title
+}) => /*#__PURE__*/_jsx(Box, {
+  onLayout: onLayout,
+  pb: "s8",
+  pt: "s8",
+  px: "s16",
+  children: /*#__PURE__*/_jsx(RnText, {
+    accessibilityRole: "header",
+    variant: "headingM",
+    children: title
+  })
+});
+
+/**
+ * Turns `<Sheet.Header>`'s props into what the native sheet takes: its header element, how that is laid out, the scroll
+ * edge effects, and the context a `<Sheet.ScrollView>` reads. On iOS 26 a scrollable sheet's header is laid over the
+ * content (which is then inset by the header's measured height) so the system's soft edge blurs what scrolls under it;
+ * everywhere else the header simply sits above the content.
+ */
+export const useSheetHeader = ({
+  header: headerProps,
+  scrollable
+}) => {
+  const title = headerProps?.title;
+  const titleStyle = headerProps?.titleStyle ?? 'center';
+  const leadingItems = headerProps?.leadingItems;
+  const trailingItems = headerProps?.trailingItems;
+  const inverted = headerProps?.inverted;
+  const search = headerProps?.search;
+  const accessory = headerProps?.children;
+  const hasBar = title !== undefined || !!leadingItems?.length || !!trailingItems?.length || !!search;
+  const hasHeader = hasBar || !!accessory;
+  const isOverlay = isScrollEdgeEffectAvailable() && hasHeader && scrollable;
+  const isLargeTitle = titleStyle === 'large' && !!title;
+  const [headerHeight, setHeaderHeight] = useState(hasBar ? ESTIMATED_HEADER_HEIGHT : 0);
+  const [largeTitleScrolledAway, setLargeTitleScrolledAway] = useState(false);
+  const largeTitleHeight = useRef(0);
+  const handleHeaderLayout = useCallback(event => {
+    setHeaderHeight(event.nativeEvent.layout.height);
+  }, []);
+  const handleLargeTitleLayout = useCallback(event => {
+    largeTitleHeight.current = event.nativeEvent.layout.height;
+  }, []);
+  const handleScroll = useCallback(event => {
+    if (largeTitleHeight.current === 0) {
+      return;
+    }
+    setLargeTitleScrolledAway(event.nativeEvent.contentOffset.y >= largeTitleHeight.current);
+  }, []);
+  const titleAlignment = titleStyle === 'large' ? COLLAPSED_TITLE_ALIGNMENT : titleStyle;
+  const titleVisible = !isLargeTitle || scrollable && largeTitleScrolledAway;
+  const headerElement = useMemo(() => {
+    if (!hasHeader) {
+      return undefined;
+    }
+    return /*#__PURE__*/_jsxs(Box, {
+      onLayout: isOverlay ? handleHeaderLayout : undefined,
+      pt: "s16",
+      children: [hasBar ? /*#__PURE__*/_jsx(NavigationBar, {
+        inverted: inverted,
+        leadingItems: leadingItems,
+        search: search,
+        title: title,
+        titleAlignment: titleAlignment,
+        titleVisible: titleVisible,
+        trailingItems: trailingItems
+      }) : null, accessory]
+    });
+  }, [accessory, handleHeaderLayout, hasBar, hasHeader, inverted, isOverlay, leadingItems, search, title, titleAlignment, titleVisible, trailingItems]);
+  const largeTitle = useMemo(() => title && isLargeTitle ? /*#__PURE__*/_jsx(SheetLargeTitle, {
+    onLayout: handleLargeTitleLayout,
+    title: title
+  }) : null, [handleLargeTitleLayout, isLargeTitle, title]);
+  const scrollContext = useMemo(() => ({
+    largeTitle: scrollable ? largeTitle : null,
+    onScroll: scrollable && isLargeTitle ? handleScroll : undefined,
+    topInset: isOverlay ? headerHeight : 0
+  }), [handleScroll, headerHeight, isLargeTitle, isOverlay, largeTitle, scrollable]);
+  return {
+    header: headerElement,
+    headerStyle: isOverlay ? OVERLAY_HEADER_STYLE : undefined,
+    scrollableOptions: isOverlay ? SOFT_EDGE_EFFECTS : undefined,
+    scrollContext,
+    /** Without a scroll view to carry it, a large title simply leads the content. */
+    staticLargeTitle: scrollable ? null : largeTitle
+  };
+};
+//# sourceMappingURL=use-sheet-header.js.map

package/lib/module/organisms/sheet/use-sheet-header.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["isScrollEdgeEffectAvailable","spacing","useCallback","useMemo","useRef","useState","Platform","Box","RnText","NavigationBar","jsx","_jsx","jsxs","_jsxs","ESTIMATED_HEADER_HEIGHT","OS","s16","COLLAPSED_TITLE_ALIGNMENT","OVERLAY_HEADER_STYLE","left","position","right","top","zIndex","SOFT_EDGE_EFFECTS","bottomScrollEdgeEffect","topScrollEdgeEffect","SheetLargeTitle","onLayout","title","pb","pt","px","children","accessibilityRole","variant","useSheetHeader","header","headerProps","scrollable","titleStyle","leadingItems","trailingItems","inverted","search","accessory","hasBar","undefined","length","hasHeader","isOverlay","isLargeTitle","headerHeight","setHeaderHeight","largeTitleScrolledAway","setLargeTitleScrolledAway","largeTitleHeight","handleHeaderLayout","event","nativeEvent","layout","height","handleLargeTitleLayout","current","handleScroll","contentOffset","y","titleAlignment","titleVisible","headerElement","largeTitle","scrollContext","onScroll","topInset","headerStyle","scrollableOptions","staticLargeTitle"],"sourceRoot":"../../../../src","sources":["organisms/sheet/use-sheet-header.tsx"],"mappings":"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","ignoreList":[]}

package/lib/typescript/molecules/navigation-bar/navigation-bar.types.d.ts

@@ -1,24 +1,63 @@
-import type { ReactNode } from 'react';
+import type { ReactNode, Ref } from 'react';
+import type { IconName } from '../../atoms/icon';
+type NavigationBarItemBase = {
+    onPress: () => void;
+    /**
+     * iOS 26: neighbouring items on one side share a glass capsule; this gives the item its own. A close next to
+     * actions usually wants it. Material has no grouped capsules, so Android ignores it.
+     */
+    separated?: boolean;
+    /** iOS: the item's accessibility identifier; Android: its test tag. */
+    testID?: string;
+};
+/**
+ * One item of the bar. `back` and `close` are the platform's own — a chevron and the system close item on iOS, the
+ * Material arrow and cross on Android — with `Back` / `Close` as their labels unless given others. `icon` is one of the
+ * app's icons and names itself for VoiceOver and TalkBack.
+ */
+export type NavigationBarItem = (NavigationBarItemBase & {
+    label?: string;
+    type: 'back' | 'close';
+}) | (NavigationBarItemBase & {
+    icon: IconName;
+    label: string;
+    type: 'icon';
+});
+export type NavigationBarSearchRef = {
+    /** Empties the field and ends editing. */
+    clear: () => void;
+};
+/** A search field in place of the title — iOS only for now; Android keeps the title. */
+export type NavigationBarSearch = {
+    onChangeText: (text: string) => void;
+    onFocusChange?: (focused: boolean) => void;
+    placeholder: string;
+    ref?: Ref<NavigationBarSearchRef>;
+    testID?: string;
+};
+export type NavigationBarTitleAlignment = 'center' | 'leading';
 /**
- * A title with back and close items, for a sheet that is not a navigation screen. On iOS a standalone
- * `UINavigationBar`, so the items press and render exactly like a native-stack header's — on iOS 26 they share the
- * bar's glass instead of swelling as standalone glass buttons do. On Android a Material row of icon buttons. The React
- * Native tier: it needs no host.
+ * A title with items on either side, for a header that is not a navigation screen's — `Sheet.Header` is built on it.
+ * On iOS a standalone `UINavigationBar`, so the items press and render exactly like a native-stack header's: on iOS 26
+ * neighbours share a glass capsule instead of swelling as standalone glass buttons do. On Android Material's top app
+ * bar. Where an item goes is the caller's choice — the bar places nothing by itself, so a close can sit on either side.
+ * The React Native tier: it needs no host.
  */
 export type NavigationBarProps = {
-    /** The back item's accessibility label. `Back` by default. */
-    backLabel?: string;
-    /** iOS: the back item's accessibility identifier. */
-    backTestID?: string;
-    /** The close item's accessibility label. `Close` by default. */
-    closeLabel?: string;
-    /** iOS: the close item's accessibility identifier. */
-    closeTestID?: string;
-    /** Shows the back item. */
-    onBack?: () => void;
-    /** Shows the close item. */
-    onClose?: () => void;
+    /** Light items and title, for a bar laid over an image or a dark hero. */
+    inverted?: boolean;
+    /** In screen order, from the leading edge. */
+    leadingItems?: NavigationBarItem[];
+    /** Replaces the title with a search field (iOS). */
+    search?: NavigationBarSearch;
     testID?: string;
     title?: string;
+    /** `center` by default — iOS's own; `leading` is Material's top app bar. */
+    titleAlignment?: NavigationBarTitleAlignment;
+    /** Fades the title out and in without moving the items — for a large title that scrolls under the bar. */
+    titleVisible?: boolean;
+    /** In screen order, toward the trailing edge. */
+    trailingItems?: NavigationBarItem[];
 };
 export type NavigationBarComponent = (props: NavigationBarProps) => ReactNode;
+export {};

package/lib/typescript/organisms/sheet/index.d.ts

@@ -1,2 +1,3 @@
 export * from './sheet';
 export * from './sheet.types';
+export { useSheetScroll } from './sheet-scroll';

package/lib/typescript/organisms/sheet/sheet-header.d.ts

@@ -0,0 +1,3 @@
+import type { SheetHeaderProps } from './sheet.types';
+/** A slot, never rendered: `Sheet` reads its props and builds the header into the native sheet's own header area. */
+export declare const SheetHeader: (_props: SheetHeaderProps) => never;

package/lib/typescript/organisms/sheet/sheet-scroll.d.ts

@@ -0,0 +1,9 @@
+import type { SheetScrollContextValue, SheetScrollViewProps } from './sheet.types';
+export declare const SheetScrollContext: import("react").Context<SheetScrollContextValue | null>;
+/**
+ * For a scroll view of your own inside a sheet (a `RnFlatList`, say): pad its content by `topInset`, render
+ * `largeTitle` first, and forward `onScroll` — which is what `<Sheet.ScrollView>` does.
+ */
+export declare const useSheetScroll: () => SheetScrollContextValue;
+/** The sheet's scrolling body: starts below the header on iOS 26, carries a large title, and reports its scroll. */
+export declare const SheetScrollView: ({ children, content, keyboardShouldPersistTaps, onScroll, testID, }: SheetScrollViewProps) => import("react").JSX.Element;

package/lib/typescript/organisms/sheet/sheet.d.ts

@@ -1 +1,7 @@
-export * from './sheet.ios';
+import type { SheetComponent } from './sheet.types';
+/**
+ * A native sheet with an optional native header. `visible` presents and dismisses it; a swipe or a tap outside calls
+ * `onDismiss`, which should set `visible` back. `<Sheet.Header>` (a direct child) gives it a bar with a title and
+ * items; `<Sheet.ScrollView>` is the body of a `scrollable` sheet.
+ */
+export declare const Sheet: SheetComponent;

package/lib/typescript/organisms/sheet/sheet.types.d.ts

@@ -1,8 +1,91 @@
-import type { ReactNode } from 'react';
+import type { ResponsiveViewSx } from '@hzblj/kara-sx';
+import type { ColorToken } from '@hzblj/kara-theme';
+import type { ReactElement, ReactNode, Ref } from 'react';
+import type { NativeScrollEvent, NativeSyntheticEvent, ScrollViewProps } from 'react-native';
+import type { NavigationBarItem, NavigationBarSearch } from '../../molecules/navigation-bar';
+/** `auto` fits the content; a number is a fraction of the screen's height. */
+export type SheetDetent = 'auto' | number;
+/**
+ * `center` is iOS's own, `leading` Material's. `large` puts the title above the content in a large face, and once
+ * that scrolls under the bar the bar's own title fades in — centred on iOS, leading on Android.
+ */
+export type SheetTitleStyle = 'center' | 'large' | 'leading';
+/**
+ * The sheet's header: a `NavigationBar` with the title and items, and anything else that should stay put above the
+ * content (`children` — a segmented control, a search hint). On iOS 26 a scrollable sheet's content scrolls under it
+ * with the system's scroll edge effect; elsewhere it sits above the content.
+ */
+export type SheetHeaderProps = {
+    /** Pinned under the bar. */
+    children?: ReactNode;
+    /** Light items and title, for a sheet with a dark or image background. */
+    inverted?: boolean;
+    /** In screen order, from the leading edge. */
+    leadingItems?: NavigationBarItem[];
+    /** A search field in place of the title (iOS). */
+    search?: NavigationBarSearch;
+    title?: string;
+    /** `center` by default. */
+    titleStyle?: SheetTitleStyle;
+    /** In screen order, toward the trailing edge — the close item, by convention. */
+    trailingItems?: NavigationBarItem[];
+};
+export type SheetRef = {
+    dismiss: () => Promise<void>;
+    /** Presents at a detent — the first by default. */
+    present: (detentIndex?: number) => Promise<void>;
+    /** Moves to another detent. */
+    resize: (detentIndex: number) => Promise<void>;
+};
+/**
+ * A native sheet — `UISheetPresentationController` on iOS, Material's bottom sheet on Android — with an optional
+ * native header (`<Sheet.Header>` as a direct child). The React Native tier: it needs no host, and must not sit inside
+ * one; native atoms in its content go in an `Island`.
+ */
 export type SheetProps = {
+    /** The sheet's colour. `surface.primary` by default. */
+    bg?: ColorToken;
     children: ReactNode;
-    fitToContents?: boolean;
+    /** Where the sheet can rest, smallest first. `['auto']` — fit the content — by default. */
+    detents?: SheetDetent[];
+    /** Dims what is behind. On by default. */
+    dimmed?: boolean;
+    /** A swipe down or a tap outside closes it. On by default. */
+    dismissible?: boolean;
+    /** It follows the finger between detents. On by default. */
+    draggable?: boolean;
+    /** Pinned to the bottom, above the content and the keyboard. */
+    footer?: ReactElement;
+    /** The drag handle. On by default. */
+    grabber?: boolean;
+    /** The user dismissed it — `visible` going false does not call this. */
     onDismiss: () => void;
+    onDetentChange?: (detentIndex: number) => void;
+    onPresent?: () => void;
+    ref?: Ref<SheetRef>;
+    /**
+     * The content is a scroll view (`<Sheet.ScrollView>`) the sheet drives: dragging past its top resizes the sheet,
+     * and a header scrolls with the iOS 26 edge effect. Off by default — set it with a scrolling body.
+     */
+    scrollable?: boolean;
+    testID?: string;
     visible: boolean;
 };
-export type SheetComponent = (props: SheetProps) => ReactNode;
+export type SheetScrollHandler = (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
+/** What a scroll view inside a sheet needs: the room the header takes, the large title, the scroll listener. */
+export type SheetScrollContextValue = {
+    largeTitle: ReactNode;
+    onScroll?: SheetScrollHandler;
+    topInset: number;
+};
+export type SheetScrollViewProps = Pick<ScrollViewProps, 'keyboardShouldPersistTaps'> & {
+    children: ReactNode;
+    /** Styles the scrolling content — padding and gap belong here, as with `RnScrollView`. */
+    content?: ResponsiveViewSx;
+    onScroll?: SheetScrollHandler;
+    testID?: string;
+};
+export type SheetComponent = ((props: SheetProps) => ReactNode) & {
+    Header: (props: SheetHeaderProps) => ReactNode;
+    ScrollView: (props: SheetScrollViewProps) => ReactNode;
+};

package/lib/typescript/organisms/sheet/split-sheet-children.d.ts

@@ -0,0 +1,9 @@
+import { type ReactNode } from 'react';
+import type { SheetHeaderProps } from './sheet.types';
+type SheetChildren = {
+    content: ReactNode;
+    header?: SheetHeaderProps;
+};
+/** Takes `<Sheet.Header>` out of the children: its props become the native header, the rest is the content. */
+export declare const splitSheetChildren: (children: ReactNode) => SheetChildren;
+export {};

package/lib/typescript/organisms/sheet/use-sheet-header.d.ts

@@ -0,0 +1,24 @@
+import { type ViewStyle } from 'react-native';
+import type { SheetHeaderProps, SheetScrollContextValue } from './sheet.types';
+type UseSheetHeaderParams = {
+    header?: SheetHeaderProps;
+    scrollable: boolean;
+};
+/**
+ * Turns `<Sheet.Header>`'s props into what the native sheet takes: its header element, how that is laid out, the scroll
+ * edge effects, and the context a `<Sheet.ScrollView>` reads. On iOS 26 a scrollable sheet's header is laid over the
+ * content (which is then inset by the header's measured height) so the system's soft edge blurs what scrolls under it;
+ * everywhere else the header simply sits above the content.
+ */
+export declare const useSheetHeader: ({ header: headerProps, scrollable }: UseSheetHeaderParams) => {
+    header: import("react").JSX.Element | undefined;
+    headerStyle: ViewStyle | undefined;
+    scrollableOptions: {
+        readonly bottomScrollEdgeEffect: 'soft';
+        readonly topScrollEdgeEffect: 'soft';
+    } | undefined;
+    scrollContext: SheetScrollContextValue;
+    /** Without a scroll view to carry it, a large title simply leads the content. */
+    staticLargeTitle: import("react").JSX.Element | null;
+};
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hzblj/kara-components",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The atoms, molecules, organisms and templates of @hzblj/kara-ui — real SwiftUI and Jetpack Compose views through @expo/ui.",
   "author": "Jan Blazej",
   "license": "MIT",
@@ -59,13 +59,14 @@
     ]
   },
   "dependencies": {
-    "@hzblj/kara-native": "workspace:^",
-    "@hzblj/kara-sx": "workspace:^",
-    "@hzblj/kara-theme": "workspace:^",
+    "@hzblj/kara-native": "^0.3.0",
+    "@hzblj/kara-sx": "^0.3.0",
+    "@hzblj/kara-theme": "^0.3.0",
     "sf-symbols-typescript": "^2.2.0"
   },
   "peerDependencies": {
     "@expo/ui": "~57.0.0",
+    "@lodev09/react-native-true-sheet": ">=3.11.0",
     "@shopify/flash-list": ">=2.0.0",
     "expo": "~57.0.0",
     "expo-haptics": "*",
@@ -76,6 +77,7 @@
   },
   "devDependencies": {
     "@expo/ui": "~57.0.18",
+    "@lodev09/react-native-true-sheet": "3.11.18",
     "@shopify/flash-list": "^2.3.2",
     "@storybook/react-native": "^10.6.0",
     "@types/react": "~19.2.18",
@@ -93,4 +95,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/src/molecules/navigation-bar/navigation-bar.android.tsx

@@ -1,28 +1,55 @@
-import {HStack} from '../../atoms/h-stack'
+import {iconResourceName} from '@hzblj/kara-native'
+import {TopAppBar, type TopAppBarItem} from '@hzblj/kara-native/jetpack-compose'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
+import {StyleSheet} from 'react-native'
 import {Island} from '../../atoms/island'
-import {Spacer} from '../../atoms/spacer'
-import {Text} from '../../atoms/text'
-import {GlyphButton} from '../../glyph'
-import type {NavigationBarComponent, NavigationBarProps} from './navigation-bar.types'
+import type {NavigationBarComponent, NavigationBarItem, NavigationBarProps} from './navigation-bar.types'
 
-/**
- * Material's top bar shape — navigation icon, start-aligned title, action at the end — built from the atoms in its own
- * island. Compose's icon buttons take no accessibility identifier, so `backTestID`/`closeTestID` are iOS-only.
- */
+/** Material's small top app bar. */
+const BAR_HEIGHT = 64
+
+const styles = StyleSheet.create({
+  bar: {height: BAR_HEIGHT, width: '100%'},
+})
+
+const DEFAULT_LABELS = {back: 'Back', close: 'Close'} as const
+
+const toNativeItem = ({onPress, testID, ...item}: NavigationBarItem): TopAppBarItem =>
+  item.type === 'icon'
+    ? {iconName: iconResourceName(item.icon), label: item.label, onPress, testID, type: 'icon'}
+    : {label: item.label ?? DEFAULT_LABELS[item.type], onPress, testID, type: item.type}
+
+/** Material's top app bar in its own host. `search` is iOS-only for now, and `separated` has no Material counterpart. */
 export const NavigationBar: NavigationBarComponent = ({
-  backLabel = 'Back',
-  closeLabel = 'Close',
-  onBack,
-  onClose,
+  inverted = false,
+  leadingItems,
   testID,
   title,
-}: NavigationBarProps) => (
-  <Island testID={testID}>
-    <HStack align="center" px="s4" spacing="s4" wide>
-      {onBack ? <GlyphButton accessibilityLabel={backLabel} name="back" onPress={onBack} /> : null}
-      {title ? <Text variant="body">{title}</Text> : null}
-      <Spacer />
-      {onClose ? <GlyphButton accessibilityLabel={closeLabel} name="close" onPress={onClose} /> : null}
-    </HStack>
-  </Island>
-)
+  titleAlignment = 'center',
+  titleVisible = true,
+  trailingItems,
+}: NavigationBarProps) => {
+  const theme = useAppTheme()
+  const font = theme.typography.headline
+  const color = theme.color(inverted ? 'content.on.bg' : 'content.primary')
+
+  const nativeLeadingItems = useMemo(() => leadingItems?.map(toNativeItem), [leadingItems])
+  const nativeTrailingItems = useMemo(() => trailingItems?.map(toNativeItem), [trailingItems])
+
+  return (
+    <Island matchContents={false} style={styles.bar} testID={testID}>
+      <TopAppBar
+        fontFamily={font.fontFamily}
+        fontSize={font.fontSize}
+        itemColor={color}
+        leadingItems={nativeLeadingItems}
+        title={title}
+        titleAlignment={titleAlignment}
+        titleColor={color}
+        titleVisible={titleVisible}
+        trailingItems={nativeTrailingItems}
+      />
+    </Island>
+  )
+}

package/src/molecules/navigation-bar/navigation-bar.ios.tsx

@@ -1,33 +1,72 @@
-import {NavigationBar as NativeNavigationBar} from '@hzblj/kara-native/swift-ui'
+import {iconResourceName} from '@hzblj/kara-native'
+import {
+  NavigationBar as NativeNavigationBar,
+  type NavigationBarItem as NativeNavigationBarItem,
+  type NavigationBarRef,
+} from '@hzblj/kara-native/swift-ui'
 import {useAppTheme} from '@hzblj/kara-theme'
+import {useImperativeHandle, useMemo, useRef} from 'react'
 import {StyleSheet} from 'react-native'
-import type {NavigationBarComponent, NavigationBarProps} from './navigation-bar.types'
+import type {NavigationBarComponent, NavigationBarItem, NavigationBarProps} from './navigation-bar.types'
 
-/** UIKit's compact bar height. The bar centres itself vertically in whatever it is given. */
-const BAR_HEIGHT = 44
+/** Fits iOS 26's 44 pt glass items with the bar's own margin; the bar centres itself vertically in it. */
+const BAR_HEIGHT = 56
 
 const styles = StyleSheet.create({
   bar: {height: BAR_HEIGHT, width: '100%'},
 })
 
+const DEFAULT_LABELS = {back: 'Back', close: 'Close'} as const
+
+const toNativeItem = (item: NavigationBarItem): NativeNavigationBarItem =>
+  item.type === 'icon'
+    ? {...item, imageName: iconResourceName(item.icon), type: 'icon'}
+    : {...item, label: item.label ?? DEFAULT_LABELS[item.type]}
+
+const ignoreDetachedView = () => undefined
+
 export const NavigationBar: NavigationBarComponent = ({
-  backLabel = 'Back',
-  closeLabel = 'Close',
-  ...props
+  inverted = false,
+  leadingItems,
+  search,
+  testID,
+  title,
+  titleAlignment = 'center',
+  titleVisible = true,
+  trailingItems,
 }: NavigationBarProps) => {
   const theme = useAppTheme()
-  const title = theme.typography.body
+  const barRef = useRef<NavigationBarRef>(null)
+  const font = theme.typography.headline
+  const color = theme.color(inverted ? 'content.on.bg' : 'content.primary')
+
+  useImperativeHandle(
+    search?.ref,
+    () => ({clear: () => barRef.current?.clearSearchText().catch(ignoreDetachedView)}),
+    []
+  )
+
+  const nativeLeadingItems = useMemo(() => leadingItems?.map(toNativeItem), [leadingItems])
+  const nativeTrailingItems = useMemo(() => trailingItems?.map(toNativeItem), [trailingItems])
 
   return (
     <NativeNavigationBar
-      {...props}
-      backLabel={backLabel}
-      closeLabel={closeLabel}
-      fontFamily={title.fontFamily}
-      fontSize={title.fontSize}
-      itemColor={theme.color('content.primary')}
+      fontFamily={font.fontFamily}
+      fontSize={font.fontSize}
+      itemColor={color}
+      leadingItems={nativeLeadingItems}
+      onSearchFocusChange={search?.onFocusChange}
+      onSearchTextChange={search?.onChangeText}
+      ref={barRef}
+      searchPlaceholder={search?.placeholder}
+      searchTestID={search?.testID}
       style={styles.bar}
-      titleColor={theme.color('content.primary')}
+      testID={testID}
+      title={title}
+      titleAlignment={titleAlignment}
+      titleColor={color}
+      titleVisible={titleVisible}
+      trailingItems={nativeTrailingItems}
     />
   )
 }