@codeleap/mobile 6.2.3 → 6.8.0

package/src/components/InputBase/index.tsx

@@ -1,7 +1,7 @@
 import React, { forwardRef } from 'react'
 import { TypeGuards } from '@codeleap/types'
 import { getRenderedComponent } from '@codeleap/utils'
-import { ActionIcon, ActionIconProps } from '../ActionIcon'
+import { } from '../Button'
 import { View } from '../View'
 import { useInputBaseStyles } from './styles'
 import { InputBaseProps } from './types'
@@ -50,20 +50,6 @@ export const InputBase = forwardRef<RNView, InputBaseProps>((props: InputBasePro
 
   const styles = useInputBaseStyles(props)
 
-  const _leftIcon = getRenderedComponent<Partial<ActionIconProps>>(leftIcon, ActionIcon, {
-    // @ts-ignore
-    style: styles.leftIconStyles,
-    debugName: `${debugName} left icon`,
-    dismissKeyboard: false,
-  })
-
-  const _rightIcon = getRenderedComponent<Partial<ActionIconProps>>(rightIcon, ActionIcon, {
-    // @ts-ignore
-    style: styles.rightIconStyles,
-    debugName: `${debugName} right icon`,
-    dismissKeyboard: false,
-  })
-
   const WrapperComponent = wrapper ?? View
 
   const InnerWrapperComponent = innerWrapper ?? View

package/src/components/InputBase/styles.ts

@@ -1,15 +1,9 @@
 import { TypeGuards } from '@codeleap/types'
-import { ActionIconParts } from '../ActionIcon'
+
 import { InputBaseProps } from './types'
 import { mergeStyles, useCompositionStyles } from '@codeleap/styles'
 import { useMemo } from 'react'
 
-type InputIcons = 'icon' | 'leftIcon' | 'rightIcon'
-
-type IconParts = ActionIconParts
-
-export type InputIconComposition = `${InputIcons}${Capitalize<IconParts>}`
-
 export type InputBaseStates = 'error' | 'focus' | 'disabled' | 'typed'
 
 export type InputBaseParts =
@@ -18,11 +12,9 @@ export type InputBaseParts =
   'label' |
   'errorMessage' |
   'description' |
-  'labelRow'|
-
-  InputIconComposition
+  'labelRow'
 
-export type IconLessInputBaseParts = Exclude<InputBaseParts, InputIconComposition>
+export type IconLessInputBaseParts = InputBaseParts
 
 export type InputBaseComposition = `${InputBaseParts}:${InputBaseStates}` | InputBaseParts
 

package/src/components/InputBase/types.ts

@@ -1,18 +1,15 @@
 import { PropsOf, StylesOf } from '@codeleap/types'
 import { InputBaseComposition } from './styles'
-import { ActionIcon } from '../ActionIcon'
 import { View, ViewProps } from 'react-native'
 
-type ActionIconProps = PropsOf<typeof ActionIcon>
-
 type OrderedParts = 'label' | 'description' | 'innerWrapper' | 'error'
-type IconProp = Partial<ActionIconProps> | React.ReactElement
+type IconProp = React.ReactElement
 
 export type InputBaseProps = React.PropsWithChildren<{
   label?: React.ReactNode
   error?: React.ReactNode
-  leftIcon?: IconProp
-  rightIcon?: IconProp
+  leftComponent?: IconProp
+  rightComponent?: IconProp
   wrapper?: (props: any) => React.ReactElement
   wrapperProps?: any
   innerWrapper?: (props: any) => React.ReactElement

package/src/components/InputBase/useInputBase.ts

@@ -4,11 +4,16 @@ import { useWrappingScrollable } from '../../modules/scroll'
 import { Field, IFieldRef, fields, useField } from '@codeleap/form'
 import { AnyRecord, TypeGuards } from '@codeleap/types'
 
+/**
+ * When both `value` and `onValueChange` are provided, the component runs in uncontrolled-by-form
+ * mode: `useField` is never called and the field ref (blur/focus/scrollIntoView) is a no-op stub.
+ * This check is frozen on mount — toggling between controlled and uncontrolled after mount is unsupported.
+ */
 export function useInputBase<V,  T extends Field<V, any, any, unknown> = Field<V, any, any, unknown>>(
   field: T,
   defaultField: (options?: AnyRecord) => T = fields.text as () => T,
   internalState: { value: V; onValueChange: (value: V) => void },
-  params: Partial<IFieldRef<V>> = {}, 
+  params: Partial<IFieldRef<V>> = {},
   deps: any[] = []
 ) {
   const { value, onValueChange } = internalState
@@ -33,6 +38,7 @@ export function useInputBase<V,  T extends Field<V, any, any, unknown> = Field<V
         return innerInputRef.current.state as V
       },
       scrollIntoView() {
+        /** Requires a wrapping ScrollView registered via `useWrappingScrollable`; silently does nothing if none is found. */
         return field.measurePosition(wrapperRef).then((measureResult) => {
           field.scrollTo(scrollable, measureResult)
         })

package/src/components/InputBase/useInputBasePartialStyles.ts

@@ -1,6 +1,11 @@
 import { useMemo } from 'react'
 import { TextStyle, ViewStyle } from 'react-native'
 
+/**
+ * Merges state-variant styles (e.g. `placeholder:error`) into a flat object keyed by part name.
+ * Pass a key as `[key, false]` to get only the active state overrides without the base style merged in
+ * — useful when RN props accept raw color values that must not be wrapped in a style array.
+ */
 export function useInputBasePartialStyles<C extends string, S extends Record<string, boolean>>(
   styles: Record<C, ViewStyle>,
   styleKeys: Array<C | [C, boolean]>,

package/src/components/InputBase/utils.ts

@@ -27,6 +27,11 @@ const varList:InputBaseKey[] = [
   'style',
 ]
 
+/**
+ * Splits a merged props object so InputBase receives only its own props and the
+ * native input/control component receives the rest — prevents unknown prop warnings
+ * on native elements and avoids spread collisions between the two prop surfaces.
+ */
 export function selectInputBaseProps<T extends BaseProps>(props: T): {
   inputBaseProps: BaseProps
   others: OmitDiff<T, T>

package/src/components/InputOverlay/index.tsx

@@ -7,6 +7,10 @@ import { DetectorProps, InterceptorProps, LayoutProps } from './types'
 
 export * from './store'
 
+/**
+ * Wraps a screen area so that tapping anywhere outside an `InputOverlay.Layout` closes all open overlays.
+ * `.runOnJS(true)` is mandatory because `inputOverlayManager.closeAll` mutates a nanostores atom on the JS thread.
+ */
 const Detector = ({ children, style, withWrapper = true }: DetectorProps) => {
   const tapGesture = Gesture.Tap()
     .onEnd((event) => {
@@ -29,6 +33,10 @@ const Detector = ({ children, style, withWrapper = true }: DetectorProps) => {
   )
 }
 
+/**
+ * Stops tap events from bubbling up to the `Detector` layer — without this, tapping inside a dropdown would immediately close it.
+ * RNGH does not bubble gestures natively; this works because both gestures are `Tap` and RNGH resolves same-type competing gestures by which `GestureDetector` is closer in the tree.
+ */
 const Interceptor = ({ children }: InterceptorProps) => {
   const tapGesture = Gesture.Tap()
     .onEnd(() => {

package/src/components/InputOverlay/store.ts

@@ -7,6 +7,7 @@ const defaultValue = '@input.atom'
 
 const inputIdAtom = atom<string>(defaultValue)
 
+/** The 100 ms delay lets any in-flight `FadeOut` animation on `Layout` complete before the atom resets, avoiding a flicker caused by React re-rendering before the Reanimated exit animation finishes. */
 const closeInputOverlays = () => {
   const currentInputId = inputIdAtom.get()
 
@@ -35,6 +36,7 @@ const useInputOverlay = (providedId?: string) => {
     const isOpen = currentInputId === id
 
     if (isAnyOtherOpen && !isOpen) {
+      /** Close the current overlay first and wait for its exit animation before opening the new one; opening both simultaneously causes z-index and animation conflicts. */
       inputIdAtom.set(defaultValue)
 
       setTimeout(() => {

package/src/components/LoadingOverlay/index.tsx

@@ -10,6 +10,13 @@ import { useStylesFor } from '../../hooks'
 export * from './styles'
 export * from './types'
 
+/**
+ * Renders in-place (not in a portal) — it does NOT block touch events on sibling content
+ * outside its own subtree. Position it as a full-screen absolute layer in the style variant
+ * if you need to cover the screen. The visibility transition is driven by Reanimated worklets
+ * via `useAnimatedVariantStyles`; the transition config is snapshotted into a ref on first
+ * render because mutating `styles.transition` after mount has no effect.
+ */
 export const LoadingOverlay = (props: LoadingOverlayProps) => {
   const {
     children,

package/src/components/LoadingOverlay/styles.ts

@@ -1,3 +1,5 @@
+/** `wrapper:transition` is a special token read at mount time to configure the Reanimated animation;
+ *  it is not applied as a style — changing it after first render has no effect. */
 import { ActivityIndicatorComposition } from '../ActivityIndicator'
 
 type WrapperStates = 'hidden' | 'visible'

package/src/components/Modal/index.tsx

@@ -1,4 +1,4 @@
-import React, { Fragment } from 'react'
+import React from 'react'
 import { View } from '../View'
 import { Scroll } from '../Scroll'
 import { TypeGuards } from '@codeleap/types'
@@ -6,17 +6,28 @@ import { Backdrop } from '../Backdrop'
 import { useBackButton } from '../../utils/hooks'
 import { Text } from '../Text'
 import { Touchable } from '../Touchable'
-import { ActionIcon } from '../ActionIcon'
 import { ModalHeaderProps, ModalProps } from './types'
 import { AnyRecord, AppIcon, useNestedStylesByKey, IJSX, StyledComponentProps } from '@codeleap/styles'
 import { MobileStyleRegistry } from '../../Registry'
 import { useStylesFor } from '../../hooks'
 import { FadeIn, FadeOut } from 'react-native-reanimated'
-import { Portal } from '@gorhom/portal'
+import { Platform, Modal as RNModal } from 'react-native'
+import { FullWindowOverlay } from 'react-native-screens'
+import { Button } from '../Button'
 
 export * from './styles'
 export * from './types'
 
+/**
+ * On iOS, React Native's `Modal` renders into a separate UIWindow that sits below the system keyboard, causing keyboard-aware layouts to break inside modals.
+ * `FullWindowOverlay` from react-native-screens renders at the top of the main UIWindow's view hierarchy instead, which the keyboard responder chain can reach.
+ * Android does not have this issue, so the standard `RNModal` is used there.
+ */
+const Overlay = Platform.select({
+  ios: FullWindowOverlay,
+  android: RNModal as any,
+})
+
 const DefaultHeader = (props: ModalHeaderProps) => {
   const {
     styles,
@@ -40,7 +51,7 @@ const DefaultHeader = (props: ModalHeaderProps) => {
           )}
 
           {(showClose && closable) ? (
-            <ActionIcon
+            <Button
               debugName={`${debugName} modal close button`}
               icon={closeIconName as AppIcon}
               onPress={toggle}
@@ -90,8 +101,7 @@ export const Modal = (modalProps: ModalProps) => {
   const ScrollComponent = scroll ? Scroll : View
   const scrollStyle = scroll ? styles?.scroll : styles?.innerWrapper
 
-  const Wrapper = withPortal ? Portal : Fragment
-
+  /** Returning `true` from the back-button handler is required to signal to Android that the event was consumed; without it the OS will still perform the default back navigation. */
   useBackButton(() => {
     if (visible && closeOnHardwareBackPress) {
       toggle()
@@ -100,7 +110,7 @@ export const Modal = (modalProps: ModalProps) => {
   }, [visible, toggle, closeOnHardwareBackPress])
 
   return (
-    <Wrapper>
+    <Overlay transparent visible={visible}>
       <View style={styles?.wrapper} pointerEvents={visible ? 'auto' : 'none'}>
         <Backdrop
           visible={visible}
@@ -164,7 +174,7 @@ export const Modal = (modalProps: ModalProps) => {
           }
         </ScrollComponent>
       </View>
-    </Wrapper>
+    </Overlay>
   )
 }
 
@@ -188,4 +198,4 @@ Modal.defaultProps = {
   renderHeader: DefaultHeader,
 } as Partial<ModalProps>
 
-MobileStyleRegistry.registerComponent(Modal)
+MobileStyleRegistry.registerComponent(Modal)

package/src/components/Modal/styles.ts

@@ -1,4 +1,4 @@
-import { ActionIconComposition } from '../ActionIcon'
+import { ButtonComposition } from '../Button'
 
 export type AnimatableParts = 'box' | 'backdrop'
 
@@ -15,7 +15,7 @@ export type ModalParts =
   | 'title'
   | 'description'
   | 'titleWrapper'
-  | `closeButton${Capitalize<ActionIconComposition>}`
+  | `closeButton${Capitalize<ButtonComposition>}`
 
 export type ModalComposition =
   | ModalParts

package/src/components/NumberIncrement/useNumberIncrement.ts

@@ -5,6 +5,7 @@ import { NumberIncrementProps } from './types'
 import { TypeGuards } from '@codeleap/types'
 import { Field, fields } from '@codeleap/form'
 
+/** Beyond this value JS floating-point arithmetic loses integer precision, so increment/decrement results become unreliable. */
 export const MAX_VALID_DIGITS = 1000000000000000 // maximum number of digits that the input supports to perform operations
 
 export function useNumberIncrement(props: Partial<NumberIncrementProps>) {
@@ -50,6 +51,11 @@ export function useNumberIncrement(props: Partial<NumberIncrementProps>) {
     return minLimit
   }, [inputValue])
 
+  /**
+   * The increment/decrement buttons briefly set `isFocused` to style the input as active, then
+   * clear it after `timeoutActionFocus` ms. The timeout must be cancelled if the user taps again
+   * or focuses the real text input before it fires, otherwise the focus state flickers off mid-type.
+   */
   const actionTimeoutRef = useRef(null)
 
   const clearActionTimeoutRef = useCallback(() => {
@@ -101,6 +107,7 @@ export function useNumberIncrement(props: Partial<NumberIncrementProps>) {
     return value
   }, [inputValue])
 
+  /** Clamps to min/max on blur so a user who clears the field or types an out-of-range number gets corrected without showing an error mid-type. */
   const handleBlur = useCallback((e: NativeSyntheticEvent<TextInputFocusEventData>) => {
     onInputValueChange(checkValue())
     validation?.onInputBlurred?.()

package/src/components/Pager/PagerDots.tsx

@@ -12,6 +12,7 @@ export type PagerDot = {
 }
 
 function Dot({ onPress, isActive, index, styles }: PagerDot) {
+  /** `isActive` is a plain boolean captured by the worklet closure — this is safe because the Dot remounts when `currentPage` changes (keyed list), so the closure is never stale. If Dot were memoized across page changes this would need a SharedValue instead. */
   const animation = useAnimatedStyle(() => {
     const scale = isActive ? 1 : 0.6
     return {

package/src/components/Pager/PagerItem.tsx

@@ -17,4 +17,5 @@ function PagerItemComponent(props: PagerItemComponentProps) {
   return <RenderItem {...info} item={item} />
 }
 
+/** Memoized only on `renderItem` and `item` — positional props (`isFirst`, `isLast`, etc.) are intentionally excluded so that changing the active page doesn't re-render every item in the carousel. */
 export const PagerItem = memoBy(PagerItemComponent, ['renderItem', 'item'])

package/src/components/Pager/index.tsx

@@ -65,6 +65,7 @@ export function Pager<T>(props: PagerProps<T>) {
     return info
   }, [])
 
+  /** `animationValue` is a Reanimated SharedValue driven by the carousel's scroll position; it is forwarded to each item so children can react to swipe progress on the UI thread without JS round-trips. */
   const customRenderItem = useCallback(({ item, index, animationValue }: CarouselRenderItemInfo<any>) => {
     const info = getItemInfo(index)
 
@@ -80,6 +81,7 @@ export function Pager<T>(props: PagerProps<T>) {
 
   const onFooterLayout = useCallback((event: LayoutChangeEvent) => {
     setFooterHeight(event.nativeEvent.layout.height)
+    /** Deferred a frame so `height` is stable before the carousel becomes visible, preventing a layout flash. */
     setTimeout(() => setLoaded(true), 0)
   }, [])
 

package/src/components/Pager/types.ts

@@ -4,6 +4,9 @@ import { PagerComposition } from './styles'
 import { TCarouselProps } from 'react-native-reanimated-carousel'
 import { CarouselRenderItemInfo } from 'react-native-reanimated-carousel/lib/typescript/types'
 
+/**
+ * `animationValue` inherited from `CarouselRenderItemInfo` is a UI-thread SharedValue — consuming it requires `useAnimatedStyle` or a worklet; reading it in plain JS will always return the initial value.
+ */
 export type PageProps<T> = CarouselRenderItemInfo<T> & {
   isLast: boolean
   isFirst: boolean
@@ -11,6 +14,7 @@ export type PageProps<T> = CarouselRenderItemInfo<T> & {
   index: number
 }
 
+/** `removeFixedHeight` / `removeFixedWidth` exist because carousel dimensions must be numeric — pass the pixel height of any sibling UI (tabs, headers) so the carousel does not overflow them. */
 export type PagerProps<T> = Partial<Omit<TCarouselProps<T>, 'data' | 'renderItem'>> & {
   pages: TCarouselProps<T>['data']
   renderItem?: (props: PageProps<T>) => React.ReactElement

package/src/components/PlacesAutocomplete/index.tsx

@@ -61,6 +61,7 @@ export const PlacesAutocomplete = (props: PlacesAutocompleteProps) => {
   const styles = useStylesFor(PlacesAutocomplete.styleRegistryName, style)
   const compositionStyles = useCompositionStyles(['input', 'list', 'loader'], styles)
 
+  /** When the caller fully controls the input value via `textInputProps.value`, the internal debounce is disabled to avoid double-buffering the typed string. */
   const hasCustomValue = !!textInputProps?.value
 
   const {

package/src/components/PlacesAutocomplete/types.ts

@@ -19,6 +19,12 @@ export type PlaceRowProps = {
   onPress?: PlacesAutocompleteProps['onPress']
 }
 
+/**
+ * The `data` prop must be driven externally — this component owns no Places API calls.
+ * Wire `onValueChange` to your debounced Places autocomplete query and pass the results back
+ * as `data`; the 250 ms internal debounce on `usePlacesAutocompleteUtils` adds a second layer
+ * of protection against excessive API requests when `textInputProps.value` is not controlled.
+ */
 export type PlacesAutocompleteProps = {
   style?: StyledProp<PlacesAutocompleteComposition>
   itemRow?: (props: any) => React.ReactElement

package/src/components/RadioInput/index.tsx

@@ -105,6 +105,7 @@ export const RadioGroup = <T extends string | number>(props: RadioGroupProps<T>)
     { value, onValueChange }
   )
 
+  /** `radioOnRight` can be baked into the style variant via `__props` so themes can set the default layout without requiring a prop on every usage site. */
   // @ts-expect-error icss type
   const _radioOnRight = radioOnRight ?? styles?.__props?.radioOnRight
 

package/src/components/RefreshControl/index.tsx

@@ -20,6 +20,7 @@ export const RefreshControl = (props: RefreshControlProps) => {
 
   const styles = useStylesFor(RefreshControl.styleRegistryName, style)
 
+  /** RN's `RefreshControl` accepts spinner colors only as raw `ColorValue` props, not via `style`; the design token values are therefore extracted from the style record and forwarded as explicit props. */
   const color: ColorValue = (styles?.loadingAnimation as AnyRecord)?.color
   const titleColor: ColorValue = (styles?.titleColor as AnyRecord)?.color
   const progressBackgroundColor: ColorValue = (styles?.progressBackgroundColor as AnyRecord)?.color

package/src/components/Scroll/index.tsx

@@ -30,6 +30,7 @@ export const Scroll = (scrollProps: ScrollProps) => {
 
   const _scrollRef = useRef<ScrollView>(null)
 
+  /** `useScrollPubSub` wires a pub/sub channel so that sibling components (e.g. sticky headers, parallax layers) can subscribe to scroll events without prop-drilling. The suppressed TS error is because the generic `ScrollView` ref type doesn't satisfy the overloaded signature inside `useScrollPubSub`. */
   // @ts-ignore
   const { ref: scrollRef, emit } = useScrollPubSub(_scrollRef)
 

package/src/components/SearchInput/index.tsx

@@ -5,6 +5,11 @@ import { TextInputProps, TextInput } from '../TextInput'
 import { TypeGuards } from '@codeleap/types'
 import { TextInput as RNTextInput } from 'react-native'
 
+/**
+ * `onSearchChange` fires after the debounce delay (default 500 ms), while `onValueChange`
+ * fires on every keystroke — use `onTypingChange` to show a loading indicator between the two.
+ * If `debounce` is `undefined` (not 0), `onSearchChange` fires synchronously with no timer.
+ */
 export type SearchInputProps = {
   onTypingChange?: (isTyping: boolean) => void
   onSearchChange: (search: string) => void
@@ -41,9 +46,10 @@ export const SearchInput: Component = forwardRef((props: SearchInputProps, ref)
     ...props,
   }
 
+  /** When `value` + `onValueChange` are both provided the component is fully controlled — the internal `useState` is skipped entirely, so the caller owns the displayed text and must update it on every keystroke. */
   const [search, setSearch] = !TypeGuards.isNil(value) && !!onValueChange ? [value, onValueChange] : useState('')
 
-  const setSearchTimeout = React.useRef<NodeJS.Timer | null>(null)
+  const setSearchTimeout = React.useRef<ReturnType<typeof setTimeout> | null>(null)
 
   const handleChangeSearch = useCallback((value: string) => {
     onTypingChange?.(true)

package/src/components/SectionFilters/index.tsx

@@ -27,6 +27,12 @@ const SectionComponent = memoBy((props: SectionComponentProps<TSectionFilterItem
   )
 }, ['renderWith'])
 
+/**
+ * `handle` can be provided externally to make the filter state controlled from outside;
+ * if omitted, an internal `useSectionFilters` instance is created from the same props.
+ * Either way, the handle is published to `SectionsFilterContext` so `renderSectionHeader`
+ * and `renderSectionFooter` can read per-section selection state via `useSectionFiltersContext`.
+ */
 export function SectionFilters<T extends TSectionFilterItem = TSectionFilterItem>(props: SectionFiltersProps<T>) {
   const {
     sections,

package/src/components/SectionFilters/useSectionFilters.tsx

@@ -26,6 +26,16 @@ export type UseSectionFilters<T = TSectionFilterItem> = {
   onToggleItem?: (item: T, section: Section<T>) => boolean
 }
 
+/**
+ * All selection state is owned internally — this hook is uncontrolled.
+ * Pass `initialSelectedItems` to seed state; after mount, changes are only possible
+ * through `toggleItem` / `clearSelectedItemsWithSection`.
+ * `onToggleItem` can intercept a toggle and return `true` to prevent the internal
+ * state update (useful for controlled scenarios without rewriting the whole hook).
+ * When `selectionLimit === 1` the entire per-section array is replaced on toggle
+ * rather than appended, so de-selecting by re-tapping the same item is not supported
+ * at limit=1 — tapping a new item simply replaces the previous selection.
+ */
 export function useSectionFilters<T = TSectionFilterItem>(props: UseSectionFilters<T>) {
   const {
     sections,
@@ -37,6 +47,8 @@ export function useSectionFilters<T = TSectionFilterItem>(props: UseSectionFilte
     onToggleItem,
   } = props
 
+  /** When `initialSelectedItems` is a plain array (no section keys), it is assigned to
+   *  section index 0 so single-section callers don't have to wrap in an object. */
   const [selectedItems, setSelectedItems] = React.useState<SelectedItemsPerSection<T>>(() => {
     if (TypeGuards.isArray(initialSelectedItems)) {
       return {

package/src/components/Sections/index.tsx

@@ -18,6 +18,14 @@ const RenderSeparator = (props: { separatorStyles: ViewProps['style'] }) => {
   return <View style={props.separatorStyles} />
 }
 
+/**
+ * Wraps React Native's SectionList. The `sections` data is augmented with a sequential `index`
+ * field internally — callers must not add their own `index` to section objects or it will be
+ * overwritten and position helpers (`isFirst`, `isLast`, `isOnly`) will break.
+ *
+ * There is no `keyExtractor` default — SectionList falls back to array index, which causes
+ * re-mount flicker on reorder. Always pass a `keyExtractor` when items can change order or identity.
+ */
 export function Sections<T>(sectionsProps: SectionProps<T>) {
   const {
     style,
@@ -40,6 +48,7 @@ export function Sections<T>(sectionsProps: SectionProps<T>) {
     ...sectionsProps,
   }
 
+  /** Deep-equality via JSON.stringify to avoid re-renders on reference changes; will miss non-serialisable values (functions, Dates) in section data. */
   const sections = useMemo(() => {
     return data?.map((section, index) => ({
       ...section,

package/src/components/SegmentedControl/index.tsx

@@ -22,6 +22,11 @@ const defaultAnimation = {
   easing: Easing.linear,
 }
 
+/**
+ * Always fully controlled — there is no internal selected state; `value` and `onValueChange`
+ * are required. The animated bubble position is driven by Reanimated worklets, so the bubble
+ * can only animate when `currentOptionIdx` changes (i.e. `value` changes from the parent).
+ */
 export const SegmentedControl = React.forwardRef<SegmentedControlRef, SegmentedControlProps>((props, ref) => {
   const [themeValues, themeSpacing] = useTheme(store => [store.theme?.values as any, store.theme?.spacing])
 
@@ -33,6 +38,7 @@ export const SegmentedControl = React.forwardRef<SegmentedControlRef, SegmentedC
     value,
     animation = {},
     scrollProps = {},
+    /** Default divides total screen width equally; override `getItemWidth` when options have variable label lengths or the control doesn't fill the screen. */
     getItemWidth = () => (themeValues?.width - themeSpacing?.value?.(4)) / options.length,
     renderBubble: BubbleView,
     scrollToCurrentOptionOnMount,
@@ -126,6 +132,7 @@ export const SegmentedControl = React.forwardRef<SegmentedControlRef, SegmentedC
     dependencies: [currentOptionIdx, widthStyle.width],
   })
 
+  /** Tracks the widest option measured during onLayout to set a uniform bubble width when `getItemWidth` is not provided; reset to 0 after each full pass so re-renders don't accumulate stale values. */
   const largestWidth = useRef(0)
 
   return (

package/src/components/Select/index.tsx

@@ -23,6 +23,7 @@ import { useInputBase } from '../InputBase/useInputBase'
 export * from './styles'
 export * from './types'
 
+/** Client-side only — skipped entirely when `loadOptions` is provided, since server search supersedes local filtering. */
 const defaultFilterFunction = (search: string, options: Options<any>) => {
   return options.filter((option) => {
     if (TypeGuards.isString(option.label)) {
@@ -46,6 +47,10 @@ const defaultGetLabel = (option) => {
   }
 }
 
+/**
+ * The TextInput here is intentionally non-editable — `onValueChange` returns the current label
+ * to prevent the native keyboard from mutating the display value directly. Editing is done via the modal.
+ */
 const OuterInput: ValueBoundSelectProps<any, boolean>['outerInputComponent'] = (props) => {
   const {
     currentValueLabel,
@@ -76,6 +81,11 @@ const OuterInput: ValueBoundSelectProps<any, boolean>['outerInputComponent'] = (
   />
 }
 
+/**
+ * Dropdown is always rendered inside a Modal — there is no native ActionSheet or platform-specific
+ * picker. Keyboard is not auto-dismissed on open; pass `keyboardShouldPersistTaps` via `listProps`
+ * if the modal appears beneath a focused input.
+ */
 export const Select = <T extends string | number = string, Multi extends boolean = false>(selectProps: SelectProps<T, Multi>) => {
   const allProps = {
     ...Select.defaultProps,
@@ -271,6 +281,7 @@ export const Select = <T extends string | number = string, Multi extends boolean
     }
   }
 
+  /** Debounce is only applied when `loadOptions` is provided; local filtering runs synchronously. */
   const searchHeader = searchable ? <SearchInput
     debugName={debugName}
     onTypingChange={(isTyping) => {

package/src/components/Select/types.ts

@@ -1,7 +1,7 @@
 import { Option, Options, PropsOf } from '@codeleap/types'
 import { AppIcon, StyledProp } from '@codeleap/styles'
 import { GetKeyboardAwarePropsOptions, StylesOf } from '../../types/utility'
-import { ActionIconProps } from '../ActionIcon'
+import { ButtonProps } from '../Button'
 import { Icon } from '../Icon'
 import { FlatListProps } from '../List'
 import { ModalProps } from '../Modal'
@@ -38,11 +38,17 @@ type SelectHeaderProps = {
 export type SelectOuterInputProps<T extends string | number = any, Multi extends boolean = false> = SelectProps<T, Multi> & {
   currentValueLabel: string
   styles?: StylesOf<TextInputComposition>
-  clearIcon?: Partial<ActionIconProps>
+  clearButton?: Partial<ButtonProps>
 }
 
 type OuterInputComponent<T extends string | number, Multi extends boolean> = (props: SelectOuterInputProps<T, Multi>) => React.ReactElement
 
+/**
+ * `loadOptions` is the escape hatch for server-driven search; when present it suppresses local
+ * `filterItems` and the component reports a loading state while the promise resolves.
+ * `defaultOptions` is shown before any search — omitting it when `loadOptions` is set means the
+ * list is empty until the user types.
+ */
 export type ValueBoundSelectProps<
   T extends string | number,
   Multi extends boolean = false

package/src/components/Slider/index.tsx

@@ -69,6 +69,11 @@ export const Slider = (props: SliderProps) => {
     onInputValueChange,
   } = useInputBase(field, fields.number, { value, onValueChange })
 
+  /**
+   * When `updateImmediately` is false, the committed value is only written on `onSlidingComplete`
+   * to avoid flooding the form/state store with every pixel of movement; `_value` is the local
+   * thumb position and `inputValue` is the last committed value.
+   */
   const [_value, _setValue] = updateImmediately ? [inputValue, onInputValueChange] : React.useState<number | Array<number>>(0)
 
   onUpdate(() => {

package/src/components/Slider/types.ts

@@ -10,6 +10,7 @@ export type SliderProps =
   {
     debounce?: number | null
     trackMarklabels?: string[]
+    /** Pass `Record<number, string>` to attach label text to each mark; pass the plain array form when marks are visual-only. */
     trackMarks?: RNSliderProps['trackMarks'] | Record<number, string>
     trackMarksClickable?: boolean
     labelClickable?: boolean