@hzblj/kara-components 0.2.1 → 0.3.0

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.1",
+  "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": "^0.2.1",
-    "@hzblj/kara-sx": "^0.2.1",
-    "@hzblj/kara-theme": "^0.2.1",
+    "@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",

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}
     />
   )
 }

package/src/molecules/navigation-bar/navigation-bar.types.ts

@@ -1,26 +1,65 @@
-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

package/src/organisms/sheet/index.ts

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

package/src/organisms/sheet/sheet-header.tsx

@@ -0,0 +1,6 @@
+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 const SheetHeader = (_props: SheetHeaderProps): never => {
+  throw new Error('[kara-ui] <Sheet.Header> must be a direct child of <Sheet>.')
+}

package/src/organisms/sheet/sheet-scroll.tsx

@@ -0,0 +1,69 @@
+import {useSx} from '@hzblj/kara-sx'
+import {createContext, useCallback, useContext, useMemo} from 'react'
+import {ScrollView} from 'react-native'
+
+import type {SheetScrollContextValue, SheetScrollHandler, SheetScrollViewProps} from './sheet.types'
+
+export const SheetScrollContext = createContext<SheetScrollContextValue | null>(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 const useSheetScroll = (): SheetScrollContextValue => {
+  const context = useContext(SheetScrollContext)
+
+  if (context === null) {
+    throw new Error('[kara-ui] useSheetScroll and <Sheet.ScrollView> must be used inside <Sheet>.')
+  }
+
+  return context
+}
+
+const NO_SX = {}
+
+/** The sheet's scrolling body: starts below the header on iOS 26, carries a large title, and reports its scroll. */
+export const SheetScrollView = ({
+  children,
+  content,
+  keyboardShouldPersistTaps,
+  onScroll,
+  testID,
+}: SheetScrollViewProps) => {
+  const {largeTitle, onScroll: onSheetScroll, topInset} = useSheetScroll()
+  const contentStyle = useSx(content ?? NO_SX)
+  // The header's room goes on top of the content's own top padding, not in place of it.
+  const containerStyle = useMemo(() => {
+    if (topInset === 0) {
+      return contentStyle
+    }
+
+    const ownTop = typeof contentStyle.paddingTop === 'number' ? contentStyle.paddingTop : 0
+
+    return [contentStyle, {paddingTop: topInset + ownTop}]
+  }, [contentStyle, topInset])
+
+  const handleScroll = useCallback<SheetScrollHandler>(
+    event => {
+      onSheetScroll?.(event)
+      onScroll?.(event)
+    },
+    [onScroll, onSheetScroll]
+  )
+
+  return (
+    <ScrollView
+      contentContainerStyle={containerStyle}
+      contentInsetAdjustmentBehavior="never"
+      keyboardShouldPersistTaps={keyboardShouldPersistTaps}
+      nestedScrollEnabled
+      onScroll={onSheetScroll || onScroll ? handleScroll : undefined}
+      overScrollMode="always"
+      scrollEventThrottle={16}
+      testID={testID}
+    >
+      {largeTitle}
+      {children}
+    </ScrollView>
+  )
+}