one 1.2.6 → 1.2.8

package/src/ui/README.md

@@ -0,0 +1,121 @@
+# One Headless UI Components
+
+Headless UI components for the One framework.
+
+## Overview
+
+The headless tabs system provides complete control over tab navigation UI while maintaining full integration with One's file-based routing system. Unlike traditional tabs that use `@react-navigation/bottom-tabs` with opinionated styling, these components are completely unstyled.
+
+## Installation
+
+The UI components are available through the `one/ui` submodule:
+
+```tsx
+import { Tabs, TabList, TabTrigger, TabSlot } from 'one/ui'
+```
+
+## Core Components
+
+| Component | Description |
+|-----------|-------------|
+| `Tabs` | Root container that wraps the entire tab structure and manages navigation state |
+| `TabList` | Container for `TabTrigger` components, typically the tab bar |
+| `TabTrigger` | Pressable element that switches between tabs |
+| `TabSlot` | Renders the currently active tab's content |
+
+## Basic Usage
+
+```tsx
+import { Tabs, TabList, TabTrigger, TabSlot } from 'one/ui'
+
+export default function Layout() {
+  return (
+    <Tabs style={styles.root}>
+      <TabSlot />
+      <TabList style={styles.tabBar}>
+        <TabTrigger
+          name="home"
+          href="/"
+          asChild
+          resetOnFocus
+        >
+          <CustomButton icon="home">Home</CustomButton>
+        </TabTrigger>
+        <TabTrigger name="profile" href="/profile" asChild>
+          <CustomButton icon="user">Profile</CustomButton>
+        </TabTrigger>
+      </TabList>
+    </Tabs>
+  )
+}
+```
+
+## Advanced Usage with Hooks
+
+### useTabsWithChildren()
+
+Hook version of `<Tabs>` that allows custom wrapper components:
+
+```tsx
+export function MyTabs({ children }) {
+  const { NavigationContent } = useTabsWithChildren({ children })
+  return <NavigationContent />
+}
+```
+
+### useTabsWithTriggers()
+
+Explicit trigger array version for advanced custom navigators:
+
+```tsx
+export function MyTabs({ children }) {
+  const { NavigationContent } = useTabsWithTriggers({
+    triggers: [
+      { type: 'internal', name: 'home', href: '/' },
+      { type: 'internal', name: 'profile', href: '/profile' },
+    ]
+  })
+  return <NavigationContent />
+}
+```
+
+### useTabSlot()
+
+Returns current tab element for custom slot rendering:
+
+```tsx
+function MyTabSlot() {
+  const slot = useTabSlot()
+  return slot
+}
+```
+
+### useTabTrigger()
+
+Custom trigger logic for building custom tab buttons:
+
+```tsx
+function CustomTabBar() {
+  const home = useTabTrigger({ name: 'home' })
+  const profile = useTabTrigger({ name: 'profile' })
+
+  return (
+    <View style={styles.customBar}>
+      <Pressable {...home.triggerProps}>
+        <Text style={home.trigger?.isFocused && styles.active}>
+          Home
+        </Text>
+      </Pressable>
+      <Pressable {...profile.triggerProps}>
+        <Text style={profile.trigger?.isFocused && styles.active}>
+          Profile
+        </Text>
+      </Pressable>
+    </View>
+  )
+}
+```
+
+## Example
+
+See `/examples/one-basic/app/tabs/` for a working example with custom-styled tabs.

package/src/ui/Slot.tsx

@@ -0,0 +1,34 @@
+import { Slot as RUISlot } from '@radix-ui/react-slot'
+import {
+  forwardRef,
+  useMemo,
+  type ForwardRefExoticComponent,
+  type Component,
+  type RefAttributes,
+} from 'react'
+import { StyleSheet, type ViewProps } from 'react-native'
+
+/**
+ * RadixUI has special logic to handle the merging of `style` and `className` props.
+ * On the web styles are not allowed so Radix does not handle this scenario.
+ * This could be fixed upstream (PR open), but it may not as RN is not their target
+ * platform.
+ *
+ * This shim calls `StyleSheet.flatten` on the styles before we render the <Slot />
+ *
+ * @see https://github.com/expo/expo/issues/31352
+ * @see https://github.com/radix-ui/primitives/issues/3107
+ * @param Component
+ * @returns
+ */
+function ShimSlotForReactNative(Component: typeof RUISlot): typeof RUISlot {
+  return forwardRef(function RNSlotHOC({ style, ...props }, ref) {
+    style = useMemo(() => StyleSheet.flatten(style), [style])
+    return <Component ref={ref} {...props} style={style} />
+  })
+}
+
+export interface Slot<Props = ViewProps, Ref = Component<ViewProps>>
+  extends ForwardRefExoticComponent<Props & RefAttributes<Ref>> {}
+
+export const Slot: Slot = ShimSlotForReactNative(RUISlot) as Slot

package/src/ui/TabContext.tsx

@@ -0,0 +1,115 @@
+import type { BottomTabNavigationOptions } from '@react-navigation/bottom-tabs'
+import type {
+  DefaultNavigatorOptions,
+  NavigationAction,
+  NavigationProp,
+  ParamListBase,
+  TabActionHelpers,
+  TabNavigationState,
+  TabRouterOptions,
+  useNavigationBuilder,
+} from '@react-navigation/native'
+import { createContext } from 'react'
+
+import type { TriggerMap } from './common'
+
+export type ExpoTabsProps = ExpoTabsNavigatorOptions
+
+export type ExpoTabsNavigatorScreenOptions = {
+  detachInactiveScreens?: boolean
+  unmountOnBlur?: boolean
+  freezeOnBlur?: boolean
+  lazy?: boolean
+}
+
+export type ExpoTabsNavigatorOptions = DefaultNavigatorOptions<
+  ParamListBase,
+  string | undefined,
+  TabNavigationState<ParamListBase>,
+  ExpoTabsScreenOptions,
+  TabNavigationEventMap,
+  ExpoTabsNavigationProp<ParamListBase>
+> &
+  // Should be set through `unstable_settings`
+  Omit<TabRouterOptions, 'initialRouteName'> &
+  ExpoTabsNavigatorScreenOptions
+
+export type ExpoTabsNavigationProp<
+  ParamList extends ParamListBase,
+  RouteName extends keyof ParamList = keyof ParamList,
+  NavigatorID extends string | undefined = undefined,
+> = NavigationProp<
+  ParamList,
+  RouteName,
+  NavigatorID,
+  TabNavigationState<ParamListBase>,
+  ExpoTabsScreenOptions,
+  TabNavigationEventMap
+>
+
+export type ExpoTabsScreenOptions = Pick<
+  BottomTabNavigationOptions,
+  'title' | 'lazy' | 'freezeOnBlur'
+> & {
+  params?: object
+  title: string
+  action: NavigationAction
+}
+
+export type TabNavigationEventMap = {
+  /**
+   * Event which fires on tapping on the tab in the tab bar.
+   */
+  tabPress: { data: undefined; canPreventDefault: true }
+  /**
+   * Event which fires on long press on the tab in the tab bar.
+   */
+  tabLongPress: { data: undefined }
+}
+
+/**
+ * The React Navigation custom navigator.
+ *
+ * @see [`useNavigationBuilder`](https://reactnavigation.org/docs/custom-navigators/#usenavigationbuilder) hook from React Navigation for more information.
+ */
+export type TabsContextValue = ReturnType<
+  typeof useNavigationBuilder<
+    TabNavigationState<any>,
+    TabRouterOptions,
+    TabActionHelpers<ParamListBase>,
+    ExpoTabsNavigatorScreenOptions,
+    TabNavigationEventMap
+  >
+>
+
+export type TabContextValue = TabsDescriptor['options']
+
+export const TabContext = createContext<TabContextValue>({})
+/**
+ * @hidden
+ */
+export const TabTriggerMapContext = createContext<TriggerMap>({})
+/**
+ * @hidden
+ */
+export const TabsDescriptorsContext = createContext<TabsContextValue['descriptors']>({})
+/**
+ * @hidden
+ */
+export const TabsNavigatorContext = createContext<TabsContextValue['navigation'] | null>(null)
+/**
+ * @hidden
+ */
+export const TabsStateContext = createContext<TabsContextValue['state']>({
+  type: 'tab',
+  preloadedRouteKeys: [],
+  history: [],
+  index: -1,
+  key: '',
+  stale: false,
+  routeNames: [],
+  routes: [],
+})
+
+export type Route = TabNavigationState<ParamListBase>['routes'][number]
+export type TabsDescriptor = TabsContextValue['descriptors'][number]

package/src/ui/TabList.tsx

@@ -0,0 +1,47 @@
+import type { ReactElement, ComponentProps } from 'react'
+import { View, StyleSheet, type ViewProps } from 'react-native'
+
+import { ViewSlot } from './common'
+
+export type TabListProps = ViewProps & {
+  /** Forward props to child component and removes the extra `<View>`. Useful for custom wrappers. */
+  asChild?: boolean
+}
+
+/**
+ * Wrapper component for `TabTriggers`. `TabTriggers` within the `TabList` define the tabs.
+ *
+ * @example
+ * ```tsx
+ * <Tabs>
+ *  <TabSlot />
+ *  <TabList>
+ *   <TabTrigger name="home" href="/" />
+ *  </TabList>
+ * </Tabs>
+ * ```
+ */
+export function TabList({ asChild, style, ...props }: TabListProps) {
+  const Comp = asChild ? ViewSlot : View
+  return <Comp style={[styles.tabList, style]} {...props} />
+}
+
+/**
+ * @hidden
+ */
+export function isTabList(
+  child: ReactElement<any>
+): child is ReactElement<ComponentProps<typeof TabList>> {
+  return child.type === TabList
+}
+
+const styles = StyleSheet.create({
+  tabList: {
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+  },
+  tabTrigger: {
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+  },
+})

package/src/ui/TabRouter.tsx

@@ -0,0 +1,79 @@
+import {
+  type CommonNavigationAction,
+  type ParamListBase,
+  TabRouter as RNTabRouter,
+  type Router,
+  type TabActionType as RNTabActionType,
+  type TabNavigationState,
+  type TabRouterOptions as RNTabRouterOptions,
+} from '@react-navigation/native'
+
+import type { TriggerMap } from './common'
+
+export type ExpoTabRouterOptions = RNTabRouterOptions & {
+  triggerMap: TriggerMap
+}
+
+export type ExpoTabActionType =
+  | RNTabActionType
+  | CommonNavigationAction
+  | {
+      type: 'JUMP_TO'
+      source?: string
+      target?: string
+      payload: {
+        name: string
+        resetOnFocus?: boolean
+        params?: object
+      }
+    }
+
+export function ExpoTabRouter(options: ExpoTabRouterOptions) {
+  const rnTabRouter = RNTabRouter(options)
+
+  const router: Router<
+    TabNavigationState<ParamListBase>,
+    ExpoTabActionType | CommonNavigationAction
+  > = {
+    ...rnTabRouter,
+    getStateForAction(state, action, options) {
+      if (action.type !== 'JUMP_TO') {
+        return rnTabRouter.getStateForAction(state, action, options)
+      }
+
+      const route = state.routes.find((route) => route.name === action.payload.name)
+
+      if (!route) {
+        // This shouldn't occur, but lets just hand it off to the next navigator in case.
+        return null
+      }
+
+      // We should reset if this is the first time visiting the route
+      let shouldReset = !state.history.some((item) => item.key === route?.key) && !route.state
+
+      if (!shouldReset && 'resetOnFocus' in action.payload && action.payload.resetOnFocus) {
+        shouldReset = state.routes[state.index].key !== route.key
+      }
+
+      if (shouldReset) {
+        options.routeParamList[route.name] = {
+          ...options.routeParamList[route.name],
+        }
+        state = {
+          ...state,
+          routes: state.routes.map((r) => {
+            if (r.key !== route.key) {
+              return r
+            }
+            return { ...r, state: undefined }
+          }),
+        }
+        return rnTabRouter.getStateForAction(state, action, options)
+      } else {
+        return rnTabRouter.getStateForRouteFocus(state, route.key)
+      }
+    },
+  }
+
+  return router
+}

package/src/ui/TabSlot.tsx

@@ -0,0 +1,170 @@
+import { type ComponentProps, type ReactElement, useState } from 'react'
+import { Platform, StyleSheet } from 'react-native'
+import { ScreenContainer, Screen } from 'react-native-screens'
+
+import { TabContext, type TabsDescriptor } from './TabContext'
+import type { TabListProps } from './TabList'
+import { useNavigatorContext } from '../views/Navigator'
+
+export type TabSlotProps = ComponentProps<typeof ScreenContainer> & {
+  /**
+   * Remove inactive screens.
+   */
+  detachInactiveScreens?: boolean
+  /**
+   * Override how the `Screen` component is rendered.
+   */
+  renderFn?: typeof defaultTabsSlotRender
+}
+
+/**
+ * Options provided to the `UseTabSlotOptions`.
+ */
+export type TabsSlotRenderOptions = {
+  /**
+   * Index of screen.
+   */
+  index: number
+  /**
+   * Whether the screen is focused.
+   */
+  isFocused: boolean
+  /**
+   * Whether the screen has been loaded.
+   */
+  loaded: boolean
+  /**
+   * Should the screen be unloaded when inactive.
+   */
+  detachInactiveScreens: boolean
+}
+
+/**
+ * Returns a `ReactElement` of the current tab.
+ *
+ * @example
+ * ```tsx
+ * function MyTabSlot() {
+ *   const slot = useTabSlot();
+ *
+ *   return slot;
+ * }
+ * ```
+ */
+export function useTabSlot({
+  detachInactiveScreens = ['android', 'ios', 'web'].includes(Platform.OS),
+  style,
+  renderFn = defaultTabsSlotRender,
+}: TabSlotProps = {}) {
+  const { state, descriptors } = useNavigatorContext()
+  const focusedRouteKey = state.routes[state.index].key
+  const [loaded, setLoaded] = useState({ [focusedRouteKey]: true })
+
+  if (!loaded[focusedRouteKey]) {
+    setLoaded({ ...loaded, [focusedRouteKey]: true })
+  }
+
+  return (
+    <ScreenContainer
+      enabled={detachInactiveScreens}
+      hasTwoStates
+      style={[styles.screenContainer, style]}
+    >
+      {state.routes.map((route, index) => {
+        const descriptor = descriptors[route.key] as unknown as TabsDescriptor
+
+        return (
+          <TabContext.Provider key={descriptor.route.key} value={descriptor.options}>
+            {renderFn(descriptor, {
+              index,
+              isFocused: state.index === index,
+              loaded: loaded[route.key],
+              detachInactiveScreens,
+            })}
+          </TabContext.Provider>
+        )
+      })}
+    </ScreenContainer>
+  )
+}
+
+/**
+ * Renders the current tab.
+ *
+ * @see [`useTabSlot`](#usetabslot) for a hook version of this component.
+ *
+ * @example
+ * ```tsx
+ * <Tabs>
+ *  <TabSlot />
+ *  <TabList>
+ *   <TabTrigger name="home" href="/" />
+ *  </TabList>
+ * </Tabs>
+ * ```
+ */
+export function TabSlot(props: TabSlotProps) {
+  return useTabSlot(props)
+}
+
+/**
+ * @hidden
+ */
+export function defaultTabsSlotRender(
+  descriptor: TabsDescriptor,
+  { isFocused, loaded, detachInactiveScreens }: TabsSlotRenderOptions
+) {
+  const { lazy = true, unmountOnBlur, freezeOnBlur } = descriptor.options
+
+  if (unmountOnBlur && !isFocused) {
+    return null
+  }
+
+  if (lazy && !loaded && !isFocused) {
+    // Don't render a lazy screen if we've never navigated to it
+    return null
+  }
+
+  return (
+    <Screen
+      key={descriptor.route.key}
+      enabled={detachInactiveScreens}
+      activityState={isFocused ? 2 : 0}
+      freezeOnBlur={freezeOnBlur}
+      style={[styles.screen, isFocused ? styles.focused : styles.unfocused]}
+    >
+      {descriptor.render()}
+    </Screen>
+  )
+}
+
+/**
+ * @hidden
+ */
+export function isTabSlot(child: ReactElement<any>): child is ReactElement<TabListProps> {
+  return child.type === TabSlot
+}
+
+const styles = StyleSheet.create({
+  screen: {
+    flex: 1,
+    position: 'relative',
+    height: '100%',
+  },
+  screenContainer: {
+    flexShrink: 0,
+    flexGrow: 1,
+  },
+  focused: {
+    zIndex: 1,
+    display: 'flex',
+    flexShrink: 0,
+    flexGrow: 1,
+  },
+  unfocused: {
+    zIndex: -1,
+    display: 'none',
+    flexShrink: 1,
+    flexGrow: 0,
+  },
+})