@hzblj/kara-router 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @hzblj/kara-router
+
+## 0.1.0
+
+### Minor Changes
+
+- [`f919c7b`](https://github.com/hzblj/kara-ui/commit/f919c7b06f3798cebd58eef1581076bf1ee61cd1) Thanks [@hzblj](https://github.com/hzblj)! - First release of the kara-ui design system: theme and tokens, the `sx` engine, atoms, molecules, organisms and `Screen`, native tabs (`@hzblj/kara-ui/router`), the KaraUI native module (Liquid Glass, scroll edge effect, native countdown, context menu with preview, rich tooltip, FAB menu), and `KaraProvider` with theme overrides — colours, the app's own fonts, the Material seed, and Material You dynamic colour on Android. Text uses the platform's face by default. Install `@hzblj/kara-ui`; the scoped packages are its building blocks.
+
+### Patch Changes
+
+- Updated dependencies [[`f919c7b`](https://github.com/hzblj/kara-ui/commit/f919c7b06f3798cebd58eef1581076bf1ee61cd1)]:
+  - @hzblj/kara-theme@0.1.0
+  - @hzblj/kara-components@0.1.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,67 @@
+"use strict";
+
+import MaterialIcons from '@expo/vector-icons/MaterialIcons';
+import { MATERIAL_ICONS, SF_SYMBOLS } from '@hzblj/kara-components';
+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,
+  VectorIcon
+} = NativeTabs.Trigger;
+const sfSymbol = name => SF_SYMBOLS[name];
+const materialIcon = name => /*#__PURE__*/_jsx(VectorIcon, {
+  family: MaterialIcons,
+  name: MATERIAL_ICONS[name]
+});
+
+/**
+ * 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;
+const renderTrigger = ({
+  hidden,
+  icon,
+  name,
+  selectedIcon,
+  testID,
+  title
+}) => /*#__PURE__*/_jsxs(NativeTabs.Trigger, {
+  hidden: hidden,
+  name: name,
+  testID: testID,
+  children: [/*#__PURE__*/_jsx(Icon, {
+    sf: selectedIcon ? {
+      default: sfSymbol(icon),
+      selected: sfSymbol(selectedIcon)
+    } : sfSymbol(icon),
+    src: selectedIcon ? {
+      default: materialIcon(icon),
+      selected: materialIcon(selectedIcon)
+    } : materialIcon(icon)
+  }), /*#__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":["MaterialIcons","MATERIAL_ICONS","SF_SYMBOLS","NativeTabs","Children","isValidElement","jsx","_jsx","jsxs","_jsxs","Icon","Label","VectorIcon","Trigger","sfSymbol","name","materialIcon","family","TabsScreen","renderTrigger","hidden","icon","selectedIcon","testID","title","children","sf","default","selected","src","TabsRoot","minimizeBehavior","map","child","type","props","Tabs","Object","assign","Screen"],"sourceRoot":"../../../src","sources":["tabs/tabs.tsx"],"mappings":";;AAAA,OAAOA,aAAa,MAAM,kCAAkC;AAC5D,SAAuBC,cAAc,EAAEC,UAAU,QAAO,wBAAwB;AAChF,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,KAAK;EAAEC;AAAU,CAAC,GAAGT,UAAU,CAACU,OAAO;AAEpD,MAAMC,QAAQ,GAAIC,IAAc,IAAKb,UAAU,CAACa,IAAI,CAAa;AAEjE,MAAMC,YAAY,GAAID,IAAc,iBAAKR,IAAA,CAACK,UAAU;EAACK,MAAM,EAAEjB,aAAc;EAACe,IAAI,EAAEd,cAAc,CAACc,IAAI;AAAE,CAAE,CAAC;;AAE1G;AACA;AACA;AACA;AACA;AACA,MAAMG,UAAmC,GAAGA,CAAA,KAAM,IAAI;AAEtD,MAAMC,aAAa,GAAGA,CAAC;EAACC,MAAM;EAAEC,IAAI;EAAEN,IAAI;EAAEO,YAAY;EAAEC,MAAM;EAAEC;AAAsB,CAAC,kBACvFf,KAAA,CAACN,UAAU,CAACU,OAAO;EAACO,MAAM,EAAEA,MAAO;EAAYL,IAAI,EAAEA,IAAK;EAACQ,MAAM,EAAEA,MAAO;EAAAE,QAAA,gBACxElB,IAAA,CAACG,IAAI;IACHgB,EAAE,EAAEJ,YAAY,GAAG;MAACK,OAAO,EAAEb,QAAQ,CAACO,IAAI,CAAC;MAAEO,QAAQ,EAAEd,QAAQ,CAACQ,YAAY;IAAC,CAAC,GAAGR,QAAQ,CAACO,IAAI,CAAE;IAChGQ,GAAG,EAAEP,YAAY,GAAG;MAACK,OAAO,EAAEX,YAAY,CAACK,IAAI,CAAC;MAAEO,QAAQ,EAAEZ,YAAY,CAACM,YAAY;IAAC,CAAC,GAAGN,YAAY,CAACK,IAAI;EAAE,CAC9G,CAAC,eACFd,IAAA,CAACI,KAAK;IAAAc,QAAA,EAAED;EAAK,CAAQ,CAAC;AAAA,GALiBT,IAMrB,CACrB;AAED,MAAMe,QAAQ,GAAGA,CAAC;EAACL,QAAQ;EAAEM,gBAAgB,GAAG;AAAkB,CAAC,kBACjExB,IAAA,CAACJ,UAAU;EAAC4B,gBAAgB,EAAEA,gBAAiB;EAAAN,QAAA,EAC5CrB,QAAQ,CAAC4B,GAAG,CAACP,QAAQ,EAAEQ,KAAK,IAC3B,aAAA5B,cAAc,CAAkB4B,KAAK,CAAC,IAAIA,KAAK,CAACC,IAAI,KAAKhB,UAAU,GAAGC,aAAa,CAACc,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,EAAErB;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,33 @@
+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;
+    icon: IconName;
+    name: string;
+    /** Swapped in while the tab is active — the filled/solid counterpart of `icon` on iOS. */
+    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,88 @@
 {
   "name": "@hzblj/kara-router",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.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": "^0.1.0",
+    "@hzblj/kara-theme": "^0.1.0",
+    "sf-symbols-typescript": "^2.2.0"
+  },
+  "peerDependencies": {
+    "@expo/vector-icons": "*",
+    "expo-router": "*",
+    "react": "*",
+    "react-native": "*"
+  },
+  "devDependencies": {
+    "@expo/ui": "~57.0.18",
+    "@expo/vector-icons": "^15.1.1",
+    "@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,46 @@
+import MaterialIcons from '@expo/vector-icons/MaterialIcons'
+import {type IconName, MATERIAL_ICONS, SF_SYMBOLS} from '@hzblj/kara-components'
+import {NativeTabs} from 'expo-router/unstable-native-tabs'
+import {Children, isValidElement} from 'react'
+import type {SFSymbol} from 'sf-symbols-typescript'
+import type {TabsComponent, TabsProps, TabsScreenProps} from './tabs.types'
+
+const {Icon, Label, VectorIcon} = NativeTabs.Trigger
+
+const sfSymbol = (name: IconName) => SF_SYMBOLS[name] as SFSymbol
+
+const materialIcon = (name: IconName) => <VectorIcon family={MaterialIcons} name={MATERIAL_ICONS[name]} />
+
+/**
+ * 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
+
+const renderTrigger = ({hidden, icon, name, selectedIcon, testID, title}: TabsScreenProps) => (
+  <NativeTabs.Trigger hidden={hidden} key={name} name={name} testID={testID}>
+    <Icon
+      sf={selectedIcon ? {default: sfSymbol(icon), selected: sfSymbol(selectedIcon)} : sfSymbol(icon)}
+      src={selectedIcon ? {default: materialIcon(icon), selected: materialIcon(selectedIcon)} : materialIcon(icon)}
+    />
+    <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,37 @@
+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
+  icon: IconName
+  name: string
+  /** Swapped in while the tab is active — the filled/solid counterpart of `icon` on iOS. */
+  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
+}