@hzblj/kara-router 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,8 @@
-# Temporary Holding Version
+# @hzblj/kara-router
 
-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 Expo Router pieces of kara-ui: native tabs (`Tabs`) and `navigationTheme`, which maps the active kara theme onto React Navigation's.
+
+**Install [`@hzblj/kara-ui`](https://www.npmjs.com/package/@hzblj/kara-ui) instead.** This package is one of its building
+blocks, published so the umbrella can depend on it; it is versioned together with it and has no standalone docs.
+
+MIT

package/lib/module/index.js

@@ -0,0 +1,5 @@
+"use strict";
+
+export * from "./navigation-theme.js";
+export * from "./tabs/index.js";
+//# sourceMappingURL=index.js.map

package/lib/module/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;AAAA,cAAc,uBAAoB;AAClC,cAAc,iBAAQ","ignoreList":[]}

package/lib/module/navigation-theme.js

@@ -0,0 +1,45 @@
+"use strict";
+
+import { fontFace, resolvePaletteColor } from '@hzblj/kara-theme';
+import { DefaultTheme } from 'expo-router';
+/**
+ * React Navigation types every colour as `string`, but the values only ever end up in a React Native
+ * style — which accepts any `ColorValue`, including the opaque `PlatformColor` a system token resolves to
+ * on iOS. Narrowing here rather than at each call site keeps the assertion to one place.
+ */
+const navColor = (theme, value) => resolvePaletteColor(theme, value);
+
+/**
+ * The app's own face for that weight where the theme names one, and React Navigation's platform default otherwise —
+ * which is the platform's face too, so headers and tab labels follow the same typeface as every other piece of text.
+ */
+const navFont = (theme, weight, fallback) => {
+  const fontFamily = fontFace(theme.fonts, weight);
+  return fontFamily ? {
+    fontFamily,
+    fontWeight: fallback.fontWeight
+  } : fallback;
+};
+
+/**
+ * Maps the active theme onto React Navigation's, for expo-router's `ThemeProvider`. Call it inside
+ * `KaraProvider` with `useAppTheme()`, so the system half of the palette is resolved for the same variant.
+ */
+export const navigationTheme = theme => ({
+  colors: {
+    background: 'transparent',
+    border: navColor(theme, theme.border.secondary.base),
+    card: navColor(theme, theme.surface.primary),
+    notification: navColor(theme, theme.fill.accent.primary),
+    primary: navColor(theme, theme.fill.accent.primary),
+    text: navColor(theme, theme.content.primary)
+  },
+  dark: theme.dark,
+  fonts: {
+    bold: navFont(theme, 'bold', DefaultTheme.fonts.bold),
+    heavy: navFont(theme, 'bold', DefaultTheme.fonts.heavy),
+    medium: navFont(theme, 'medium', DefaultTheme.fonts.medium),
+    regular: navFont(theme, 'regular', DefaultTheme.fonts.regular)
+  }
+});
+//# sourceMappingURL=navigation-theme.js.map

package/lib/module/navigation-theme.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["fontFace","resolvePaletteColor","DefaultTheme","navColor","theme","value","navFont","weight","fallback","fontFamily","fonts","fontWeight","navigationTheme","colors","background","border","secondary","base","card","surface","primary","notification","fill","accent","text","content","dark","bold","heavy","medium","regular"],"sourceRoot":"../../src","sources":["navigation-theme.ts"],"mappings":";;AAAA,SAAyBA,QAAQ,EAAqBC,mBAAmB,QAAmB,mBAAmB;AAC/G,SAAQC,YAAY,QAAsC,aAAa;AAIvE;AACA;AACA;AACA;AACA;AACA,MAAMC,QAAQ,GAAGA,CAACC,KAAY,EAAEC,KAAmB,KAAaJ,mBAAmB,CAACG,KAAK,EAAEC,KAAK,CAAW;;AAE3G;AACA;AACA;AACA;AACA,MAAMC,OAAO,GAAGA,CAACF,KAAY,EAAEG,MAAkB,EAAEC,QAAwB,KAAqB;EAC9F,MAAMC,UAAU,GAAGT,QAAQ,CAACI,KAAK,CAACM,KAAK,EAAEH,MAAM,CAAC;EAEhD,OAAOE,UAAU,GAAG;IAACA,UAAU;IAAEE,UAAU,EAAEH,QAAQ,CAACG;EAAU,CAAC,GAAGH,QAAQ;AAC9E,CAAC;;AAED;AACA;AACA;AACA;AACA,OAAO,MAAMI,eAAe,GAAIR,KAAY,KAAuB;EACjES,MAAM,EAAE;IACNC,UAAU,EAAE,aAAa;IACzBC,MAAM,EAAEZ,QAAQ,CAACC,KAAK,EAAEA,KAAK,CAACW,MAAM,CAACC,SAAS,CAACC,IAAI,CAAC;IACpDC,IAAI,EAAEf,QAAQ,CAACC,KAAK,EAAEA,KAAK,CAACe,OAAO,CAACC,OAAO,CAAC;IAC5CC,YAAY,EAAElB,QAAQ,CAACC,KAAK,EAAEA,KAAK,CAACkB,IAAI,CAACC,MAAM,CAACH,OAAO,CAAC;IACxDA,OAAO,EAAEjB,QAAQ,CAACC,KAAK,EAAEA,KAAK,CAACkB,IAAI,CAACC,MAAM,CAACH,OAAO,CAAC;IACnDI,IAAI,EAAErB,QAAQ,CAACC,KAAK,EAAEA,KAAK,CAACqB,OAAO,CAACL,OAAO;EAC7C,CAAC;EACDM,IAAI,EAAEtB,KAAK,CAACsB,IAAI;EAChBhB,KAAK,EAAE;IACLiB,IAAI,EAAErB,OAAO,CAACF,KAAK,EAAE,MAAM,EAAEF,YAAY,CAACQ,KAAK,CAACiB,IAAI,CAAC;IACrDC,KAAK,EAAEtB,OAAO,CAACF,KAAK,EAAE,MAAM,EAAEF,YAAY,CAACQ,KAAK,CAACkB,KAAK,CAAC;IACvDC,MAAM,EAAEvB,OAAO,CAACF,KAAK,EAAE,QAAQ,EAAEF,YAAY,CAACQ,KAAK,CAACmB,MAAM,CAAC;IAC3DC,OAAO,EAAExB,OAAO,CAACF,KAAK,EAAE,SAAS,EAAEF,YAAY,CAACQ,KAAK,CAACoB,OAAO;EAC/D;AACF,CAAC,CAAC","ignoreList":[]}

package/lib/module/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/lib/module/tabs/index.js

@@ -0,0 +1,5 @@
+"use strict";
+
+export * from "./tabs.js";
+export * from "./tabs.types.js";
+//# sourceMappingURL=index.js.map

package/lib/module/tabs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../../src","sources":["tabs/index.ts"],"mappings":";;AAAA,cAAc,WAAQ;AACtB,cAAc,iBAAc","ignoreList":[]}

package/lib/module/tabs/tabs.js

@@ -0,0 +1,69 @@
+"use strict";
+
+import { iconResourceName } from '@hzblj/kara-native';
+import { NativeTabs } from 'expo-router/unstable-native-tabs';
+import { Children, isValidElement } from 'react';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const {
+  Icon,
+  Label
+} = NativeTabs.Trigger;
+
+/**
+ * Declares one tab and renders nothing itself — `Tabs` reads these props and emits the trigger.
+ * The navigator collects its tabs by matching child element type exactly, so a component that
+ * merely *renders* a trigger is invisible to it and the tab bar comes up empty.
+ */
+const TabsScreen = () => null;
+
+/**
+ * The tab's icon, natively on both sides: the app icon's image set in the iOS asset catalog, its vector drawable on
+ * Android — one name, the one the config plugin gave both. No icon font, no bitmap rendered in JavaScript.
+ */
+const renderTrigger = ({
+  hidden,
+  icon,
+  name,
+  selectedIcon,
+  testID,
+  title
+}) => {
+  const asset = iconResourceName(icon);
+  const selected = selectedIcon ? iconResourceName(selectedIcon) : undefined;
+  return /*#__PURE__*/_jsxs(NativeTabs.Trigger, {
+    hidden: hidden,
+    name: name,
+    testID: testID,
+    children: [/*#__PURE__*/_jsx(Icon, {
+      drawable: selected ? {
+        default: asset,
+        selected
+      } : asset,
+      xcasset: selected ? {
+        default: asset,
+        selected
+      } : asset
+    }), /*#__PURE__*/_jsx(Label, {
+      children: title
+    })]
+  }, name);
+};
+const TabsRoot = ({
+  children,
+  minimizeBehavior = 'never'
+}) => /*#__PURE__*/_jsx(NativeTabs, {
+  minimizeBehavior: minimizeBehavior,
+  children: Children.map(children, child => /*#__PURE__*/isValidElement(child) && child.type === TabsScreen ? renderTrigger(child.props) : child)
+});
+
+/**
+ * Native bottom tabs — a SwiftUI `TabView` on iOS and a Material navigation bar on Android, both
+ * driven by Expo Router's own navigator. Nothing here may come from the standalone
+ * `@react-navigation/*` packages: Expo Router 57 vendors its own fork of them, so a navigator built
+ * against the npm copies registers into a context tree that never exists and throws
+ * "Couldn't register the navigator" the moment this layout mounts.
+ */
+export const Tabs = Object.assign(TabsRoot, {
+  Screen: TabsScreen
+});
+//# sourceMappingURL=tabs.js.map

package/lib/module/tabs/tabs.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["iconResourceName","NativeTabs","Children","isValidElement","jsx","_jsx","jsxs","_jsxs","Icon","Label","Trigger","TabsScreen","renderTrigger","hidden","icon","name","selectedIcon","testID","title","asset","selected","undefined","children","drawable","default","xcasset","TabsRoot","minimizeBehavior","map","child","type","props","Tabs","Object","assign","Screen"],"sourceRoot":"../../../src","sources":["tabs/tabs.tsx"],"mappings":";;AAAA,SAAQA,gBAAgB,QAAO,oBAAoB;AACnD,SAAQC,UAAU,QAAO,kCAAkC;AAC3D,SAAQC,QAAQ,EAAEC,cAAc,QAAO,OAAO;AAAA,SAAAC,GAAA,IAAAC,IAAA,EAAAC,IAAA,IAAAC,KAAA;AAI9C,MAAM;EAACC,IAAI;EAAEC;AAAK,CAAC,GAAGR,UAAU,CAACS,OAAO;;AAExC;AACA;AACA;AACA;AACA;AACA,MAAMC,UAAmC,GAAGA,CAAA,KAAM,IAAI;;AAEtD;AACA;AACA;AACA;AACA,MAAMC,aAAa,GAAGA,CAAC;EAACC,MAAM;EAAEC,IAAI;EAAEC,IAAI;EAAEC,YAAY;EAAEC,MAAM;EAAEC;AAAsB,CAAC,KAAK;EAC5F,MAAMC,KAAK,GAAGnB,gBAAgB,CAACc,IAAI,CAAC;EACpC,MAAMM,QAAQ,GAAGJ,YAAY,GAAGhB,gBAAgB,CAACgB,YAAY,CAAC,GAAGK,SAAS;EAE1E,oBACEd,KAAA,CAACN,UAAU,CAACS,OAAO;IAACG,MAAM,EAAEA,MAAO;IAAYE,IAAI,EAAEA,IAAK;IAACE,MAAM,EAAEA,MAAO;IAAAK,QAAA,gBACxEjB,IAAA,CAACG,IAAI;MACHe,QAAQ,EAAEH,QAAQ,GAAG;QAACI,OAAO,EAAEL,KAAK;QAAEC;MAAQ,CAAC,GAAGD,KAAM;MACxDM,OAAO,EAAEL,QAAQ,GAAG;QAACI,OAAO,EAAEL,KAAK;QAAEC;MAAQ,CAAC,GAAGD;IAAM,CACxD,CAAC,eACFd,IAAA,CAACI,KAAK;MAAAa,QAAA,EAAEJ;IAAK,CAAQ,CAAC;EAAA,GALiBH,IAMrB,CAAC;AAEzB,CAAC;AAED,MAAMW,QAAQ,GAAGA,CAAC;EAACJ,QAAQ;EAAEK,gBAAgB,GAAG;AAAkB,CAAC,kBACjEtB,IAAA,CAACJ,UAAU;EAAC0B,gBAAgB,EAAEA,gBAAiB;EAAAL,QAAA,EAC5CpB,QAAQ,CAAC0B,GAAG,CAACN,QAAQ,EAAEO,KAAK,IAC3B,aAAA1B,cAAc,CAAkB0B,KAAK,CAAC,IAAIA,KAAK,CAACC,IAAI,KAAKnB,UAAU,GAAGC,aAAa,CAACiB,KAAK,CAACE,KAAK,CAAC,GAAGF,KACrG;AAAC,CACS,CACb;;AAED;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMG,IAAmB,GAAGC,MAAM,CAACC,MAAM,CAACR,QAAQ,EAAE;EAACS,MAAM,EAAExB;AAAU,CAAC,CAAC","ignoreList":[]}

package/lib/module/tabs/tabs.types.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=tabs.types.js.map

package/lib/module/tabs/tabs.types.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../../src","sources":["tabs/tabs.types.ts"],"mappings":"","ignoreList":[]}

package/lib/typescript/index.d.ts

@@ -0,0 +1,2 @@
+export * from './navigation-theme';
+export * from './tabs';

package/lib/typescript/navigation-theme.d.ts

@@ -0,0 +1,7 @@
+import { type Theme } from '@hzblj/kara-theme';
+import { type Theme as NavigationTheme } from 'expo-router';
+/**
+ * Maps the active theme onto React Navigation's, for expo-router's `ThemeProvider`. Call it inside
+ * `KaraProvider` with `useAppTheme()`, so the system half of the palette is resolved for the same variant.
+ */
+export declare const navigationTheme: (theme: Theme) => NavigationTheme;

package/lib/typescript/tabs/index.d.ts

@@ -0,0 +1,2 @@
+export * from './tabs';
+export * from './tabs.types';

package/lib/typescript/tabs/tabs.d.ts

@@ -0,0 +1,9 @@
+import type { TabsComponent } from './tabs.types';
+/**
+ * Native bottom tabs — a SwiftUI `TabView` on iOS and a Material navigation bar on Android, both
+ * driven by Expo Router's own navigator. Nothing here may come from the standalone
+ * `@react-navigation/*` packages: Expo Router 57 vendors its own fork of them, so a navigator built
+ * against the npm copies registers into a context tree that never exists and throws
+ * "Couldn't register the navigator" the moment this layout mounts.
+ */
+export declare const Tabs: TabsComponent;

package/lib/typescript/tabs/tabs.types.d.ts

@@ -0,0 +1,34 @@
+import type { IconName } from '@hzblj/kara-components';
+import type { ReactNode } from 'react';
+export type TabsScreenProps = {
+    /**
+     * Drops the tab from the bar *and* makes the route unreachable by navigation. Prefer this over
+     * conditionally rendering the screen: every child route needs a declared tab, and toggling this
+     * at runtime remounts the navigator, so pass a build constant.
+     */
+    hidden?: boolean;
+    /** One of the app's icons — the asset-catalog image on iOS, the vector drawable on Android. */
+    icon: IconName;
+    name: string;
+    /** Swapped in while the tab is active — the filled counterpart of `icon`, say. */
+    selectedIcon?: IconName;
+    testID?: string;
+    title: string;
+};
+/** Maps to `UITabBarController.minimizeBehavior`. iOS 26+; ignored everywhere else. */
+export type TabsMinimizeBehavior = 'automatic' | 'never' | 'onScrollDown' | 'onScrollUp';
+export type TabsProps = {
+    children: ReactNode;
+    /**
+     * Whether the iOS 26 tab bar shrinks to a pill while scrolling.
+     *
+     * Off by default, unlike the system, which minimizes on scroll. Minimizing changes the tab bar's
+     * height mid-gesture, and a native tabs screen re-insets the first scroll view inside it to match —
+     * so the content shifts under the finger every time the scroll direction changes, and every list in
+     * the app inherits that. Opt in per screen once the content is built to absorb it.
+     */
+    minimizeBehavior?: TabsMinimizeBehavior;
+};
+export type TabsComponent = ((props: TabsProps) => ReactNode) & {
+    Screen: (props: TabsScreenProps) => ReactNode;
+};

package/package.json

@@ -1,6 +1,86 @@
 {
   "name": "@hzblj/kara-router",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Expo Router pieces of @hzblj/kara-ui: native tabs and a navigation theme mapped from the active kara theme.",
+  "author": "Jan Blazej",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hzblj/kara-ui.git",
+    "directory": "packages/router"
+  },
+  "bugs": {
+    "url": "https://github.com/hzblj/kara-ui/issues"
+  },
+  "homepage": "https://github.com/hzblj/kara-ui/tree/main/packages/router#readme",
+  "keywords": [
+    "react-native",
+    "expo",
+    "kara-ui"
+  ],
+  "main": "./lib/module/index.js",
+  "types": "./lib/typescript/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./lib/typescript/index.d.ts",
+      "default": "./lib/module/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "!**/*.stories.tsx",
+    "!**/contract.check.ts",
+    "!**/story-decorators.tsx",
+    "!**/__tests__"
+  ],
+  "scripts": {
+    "build": "bob build && tsc -p ./tsconfig.build.json && node ../../scripts/fallback-declarations.mjs",
+    "clean": "rm -rf lib",
+    "prepack": "yarn run -T turbo run build --filter=$npm_package_name...",
+    "lint": "yarn run -T concurrently \"yarn biome:check\" \"yarn tsc:check\"",
+    "lint:fix": "yarn run -T biome check --write .",
+    "biome:check": "yarn run -T biome check .",
+    "tsc:check": "yarn run -T concurrently \"tsc -p ./tsconfig.ios.json\" \"tsc -p ./tsconfig.android.json\""
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "exclude": "{**/__tests__/**,**/__fixtures__/**,**/__mocks__/**,**/*.stories.tsx,**/contract.check.ts,**/story-decorators.tsx}",
+    "targets": [
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ]
+    ]
+  },
+  "dependencies": {
+    "@hzblj/kara-components": "workspace:^",
+    "@hzblj/kara-native": "workspace:^",
+    "@hzblj/kara-theme": "workspace:^"
+  },
+  "peerDependencies": {
+    "expo-router": "*",
+    "react": "*",
+    "react-native": "*"
+  },
+  "devDependencies": {
+    "@expo/ui": "~57.0.18",
+    "@storybook/react-native": "^10.6.0",
+    "@types/react": "~19.2.18",
+    "expo": "~57.0.22",
+    "expo-router": "~57.0.21",
+    "react": "19.2.3",
+    "react-native": "0.86.3",
+    "react-native-builder-bob": "^0.43.0",
+    "storybook": "^10.6.0",
+    "typescript": "~7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './navigation-theme'
+export * from './tabs'

package/src/navigation-theme.ts

@@ -0,0 +1,43 @@
+import {type FontWeight, fontFace, type PaletteColor, resolvePaletteColor, type Theme} from '@hzblj/kara-theme'
+import {DefaultTheme, type Theme as NavigationTheme} from 'expo-router'
+
+type NavigationFont = NavigationTheme['fonts']['regular']
+
+/**
+ * React Navigation types every colour as `string`, but the values only ever end up in a React Native
+ * style — which accepts any `ColorValue`, including the opaque `PlatformColor` a system token resolves to
+ * on iOS. Narrowing here rather than at each call site keeps the assertion to one place.
+ */
+const navColor = (theme: Theme, value: PaletteColor): string => resolvePaletteColor(theme, value) as string
+
+/**
+ * The app's own face for that weight where the theme names one, and React Navigation's platform default otherwise —
+ * which is the platform's face too, so headers and tab labels follow the same typeface as every other piece of text.
+ */
+const navFont = (theme: Theme, weight: FontWeight, fallback: NavigationFont): NavigationFont => {
+  const fontFamily = fontFace(theme.fonts, weight)
+
+  return fontFamily ? {fontFamily, fontWeight: fallback.fontWeight} : fallback
+}
+
+/**
+ * Maps the active theme onto React Navigation's, for expo-router's `ThemeProvider`. Call it inside
+ * `KaraProvider` with `useAppTheme()`, so the system half of the palette is resolved for the same variant.
+ */
+export const navigationTheme = (theme: Theme): NavigationTheme => ({
+  colors: {
+    background: 'transparent',
+    border: navColor(theme, theme.border.secondary.base),
+    card: navColor(theme, theme.surface.primary),
+    notification: navColor(theme, theme.fill.accent.primary),
+    primary: navColor(theme, theme.fill.accent.primary),
+    text: navColor(theme, theme.content.primary),
+  },
+  dark: theme.dark,
+  fonts: {
+    bold: navFont(theme, 'bold', DefaultTheme.fonts.bold),
+    heavy: navFont(theme, 'bold', DefaultTheme.fonts.heavy),
+    medium: navFont(theme, 'medium', DefaultTheme.fonts.medium),
+    regular: navFont(theme, 'regular', DefaultTheme.fonts.regular),
+  },
+})

package/src/tabs/index.ts

@@ -0,0 +1,2 @@
+export * from './tabs'
+export * from './tabs.types'

package/src/tabs/tabs.tsx

@@ -0,0 +1,50 @@
+import {iconResourceName} from '@hzblj/kara-native'
+import {NativeTabs} from 'expo-router/unstable-native-tabs'
+import {Children, isValidElement} from 'react'
+
+import type {TabsComponent, TabsProps, TabsScreenProps} from './tabs.types'
+
+const {Icon, Label} = NativeTabs.Trigger
+
+/**
+ * Declares one tab and renders nothing itself — `Tabs` reads these props and emits the trigger.
+ * The navigator collects its tabs by matching child element type exactly, so a component that
+ * merely *renders* a trigger is invisible to it and the tab bar comes up empty.
+ */
+const TabsScreen: TabsComponent['Screen'] = () => null
+
+/**
+ * The tab's icon, natively on both sides: the app icon's image set in the iOS asset catalog, its vector drawable on
+ * Android — one name, the one the config plugin gave both. No icon font, no bitmap rendered in JavaScript.
+ */
+const renderTrigger = ({hidden, icon, name, selectedIcon, testID, title}: TabsScreenProps) => {
+  const asset = iconResourceName(icon)
+  const selected = selectedIcon ? iconResourceName(selectedIcon) : undefined
+
+  return (
+    <NativeTabs.Trigger hidden={hidden} key={name} name={name} testID={testID}>
+      <Icon
+        drawable={selected ? {default: asset, selected} : asset}
+        xcasset={selected ? {default: asset, selected} : asset}
+      />
+      <Label>{title}</Label>
+    </NativeTabs.Trigger>
+  )
+}
+
+const TabsRoot = ({children, minimizeBehavior = 'never'}: TabsProps) => (
+  <NativeTabs minimizeBehavior={minimizeBehavior}>
+    {Children.map(children, child =>
+      isValidElement<TabsScreenProps>(child) && child.type === TabsScreen ? renderTrigger(child.props) : child
+    )}
+  </NativeTabs>
+)
+
+/**
+ * Native bottom tabs — a SwiftUI `TabView` on iOS and a Material navigation bar on Android, both
+ * driven by Expo Router's own navigator. Nothing here may come from the standalone
+ * `@react-navigation/*` packages: Expo Router 57 vendors its own fork of them, so a navigator built
+ * against the npm copies registers into a context tree that never exists and throws
+ * "Couldn't register the navigator" the moment this layout mounts.
+ */
+export const Tabs: TabsComponent = Object.assign(TabsRoot, {Screen: TabsScreen})

package/src/tabs/tabs.types.ts

@@ -0,0 +1,38 @@
+import type {IconName} from '@hzblj/kara-components'
+import type {ReactNode} from 'react'
+
+export type TabsScreenProps = {
+  /**
+   * Drops the tab from the bar *and* makes the route unreachable by navigation. Prefer this over
+   * conditionally rendering the screen: every child route needs a declared tab, and toggling this
+   * at runtime remounts the navigator, so pass a build constant.
+   */
+  hidden?: boolean
+  /** One of the app's icons — the asset-catalog image on iOS, the vector drawable on Android. */
+  icon: IconName
+  name: string
+  /** Swapped in while the tab is active — the filled counterpart of `icon`, say. */
+  selectedIcon?: IconName
+  testID?: string
+  title: string
+}
+
+/** Maps to `UITabBarController.minimizeBehavior`. iOS 26+; ignored everywhere else. */
+export type TabsMinimizeBehavior = 'automatic' | 'never' | 'onScrollDown' | 'onScrollUp'
+
+export type TabsProps = {
+  children: ReactNode
+  /**
+   * Whether the iOS 26 tab bar shrinks to a pill while scrolling.
+   *
+   * Off by default, unlike the system, which minimizes on scroll. Minimizing changes the tab bar's
+   * height mid-gesture, and a native tabs screen re-insets the first scroll view inside it to match —
+   * so the content shifts under the finger every time the scroll direction changes, and every list in
+   * the app inherits that. Opt in per screen once the content is built to absorb it.
+   */
+  minimizeBehavior?: TabsMinimizeBehavior
+}
+
+export type TabsComponent = ((props: TabsProps) => ReactNode) & {
+  Screen: (props: TabsScreenProps) => ReactNode
+}