@codeleap/mobile 6.2.3 → 6.8.0

package/dist/utils/theme.d.ts

@@ -3,13 +3,16 @@ type Options = {
     getStatusBarHeight?: () => number;
     getAndroidNavbarHeight?: () => number;
 };
+/**
+ * Safe-area insets are computed statically from `DeviceInfo` flags rather than from `react-native-safe-area-context` so the values are available synchronously before the context provider mounts. The `initialWindowMetrics` argument should come from `SafeAreaProvider`'s `initialMetrics` prop to seed Android bottom inset before the provider has measured. On iOS, notch/island presence is inferred from hardware flags rather than from `initialWindowMetrics` because those metrics are not stable across orientation changes at init time.
+ */
 export declare function getMobileThemeValues(initialWindowMetrics: any, options?: Options): {
     pixel: number;
     hasNotch: boolean;
     hasIsland: boolean;
     prefersConstantNavigationBar: boolean;
     safeAreaTop: number;
-    safeAreaBottom: any;
+    safeAreaBottom: number | undefined;
     keyboardVerticalOffset: number;
     bottomNavHeight: number;
     window: {
@@ -22,3 +25,4 @@ export declare function getMobileThemeValues(initialWindowMetrics: any, options?
     fontScale: number;
 };
 export {};
+//# sourceMappingURL=theme.d.ts.map

package/dist/utils/theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../../src/utils/theme.ts"],"names":[],"mappings":"AAGA,KAAK,OAAO,GAAG;IACb,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,kBAAkB,CAAC,EAAE,MAAM,MAAM,CAAA;IACjC,sBAAsB,CAAC,EAAE,MAAM,MAAM,CAAA;CACtC,CAAA;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,oBAAoB,KAAA,EAAE,OAAO,GAAE,OAAY;;;;;;;;;;;;;;;;;EAoC/E"}

package/dist/utils/useQueryListRefresh.d.ts

@@ -7,5 +7,9 @@ type useQueryListRefresh = (listQuery: Parameters<QueryManagerOptions<any, any>[
     onFocus?: AnyFunction;
     onBlur?: AnyFunction;
 }) => void;
+/**
+ * Uses `useFocusEffect` (not `useEffect`) so the refetch/stale timer is tied to React Navigation screen focus — a background tab never triggers an unnecessary network request. The stale window starts on blur and is cleared on the next focus, meaning a very fast back-and-forward (faster than `staleTime`) will not refetch.
+ */
 export declare const useQueryListRefresh: useQueryListRefresh;
 export {};
+//# sourceMappingURL=useQueryListRefresh.d.ts.map

package/dist/utils/useQueryListRefresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useQueryListRefresh.d.ts","sourceRoot":"","sources":["../../src/utils/useQueryListRefresh.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAc,MAAM,iBAAiB,CAAA;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAErD,KAAK,mBAAmB,GAAG,CACzB,SAAS,EAAE,UAAU,CAAC,mBAAmB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,EACxE,OAAO,CAAC,EAAE;IACR,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAC7B,OAAO,CAAC,EAAE,WAAW,CAAA;IACrB,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB,KACE,IAAI,CAAA;AAET;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,mBAuCjC,CAAA"}

package/package.json

@@ -1,7 +1,20 @@
 {
   "name": "@codeleap/mobile",
-  "version": "6.2.3",
+  "version": "6.8.0",
   "main": "src/index.ts",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
   "license": "UNLICENSED",
   "repository": {
     "url": "https://github.com/codeleap-uk/internal-libs-monorepo.git",
@@ -9,28 +22,29 @@
     "directory": "packages/mobile"
   },
   "devDependencies": {
-    "@codeleap/types": "6.2.3",
-    "@codeleap/utils": "6.2.3",
-    "@codeleap/hooks": "6.2.3",
-    "@codeleap/form": "6.2.3",
-    "@codeleap/query": "6.2.3",
-    "@codeleap/logger": "6.2.3",
-    "@codeleap/config": "6.2.3",
-    "@codeleap/modals": "6.2.3"
+    "@codeleap/config": "6.8.0",
+    "@codeleap/form": "6.8.0",
+    "@codeleap/hooks": "6.8.0",
+    "@codeleap/logger": "6.8.0",
+    "@codeleap/portals": "6.8.0",
+    "@codeleap/query": "6.8.0",
+    "@codeleap/styles": "6.8.0",
+    "@codeleap/types": "6.8.0",
+    "@codeleap/utils": "6.8.0"
   },
   "scripts": {
-    "build": "tsc --build",
+    "build": "tsc --build tsconfig.build.json",
     "lint": "eslint -c  .eslintrc.js --fix \"./src/**/*.{ts,tsx,js,jsx}\""
   },
   "peerDependencies": {
-    "@codeleap/types": "6.2.3",
-    "@codeleap/utils": "6.2.3",
-    "@codeleap/hooks": "6.2.3",
-    "@codeleap/form": "6.2.3",
-    "@codeleap/query": "6.2.3",
-    "@codeleap/logger": "6.2.3",
-    "@codeleap/styles": "6.2.3",
-    "@codeleap/modals": "6.2.3",
+    "@codeleap/types": "6.8.0",
+    "@codeleap/utils": "6.8.0",
+    "@codeleap/hooks": "6.8.0",
+    "@codeleap/form": "6.8.0",
+    "@codeleap/query": "6.8.0",
+    "@codeleap/logger": "6.8.0",
+    "@codeleap/styles": "6.8.0",
+    "@codeleap/portals": "6.8.0",
     "@d11/react-native-fast-image": "8.12.0",
     "@react-native-firebase/messaging": "23.4.1",
     "@react-navigation/bottom-tabs": "7.4.9",
@@ -50,7 +64,6 @@
     "typescript": "5.5.2"
   },
   "dependencies": {
-    "@gorhom/portal": "1.0.14",
     "@miblanchard/react-native-slider": "2.3.1",
     "react-native-currency-input": "^1.1.1",
     "react-native-masked-text": "1.13.0",
@@ -58,4 +71,4 @@
     "react-native-sortables": "1.1.1",
     "react-native-uuid": "2.0.3"
   }
-}
+}

package/src/Registry.ts

@@ -20,6 +20,11 @@ let instance: MobileStyleRegistry
 
 const components: CodeleapStyleRegistry['components'][string][] = []
 
+/**
+ * Singleton — the constructor enforces a single instance and returns it on every `new` call, so any module that imports this class and instantiates it will always get the same registry. Components registered via the static `registerComponent` before the first instantiation are buffered in `components[]` and replayed on construction; registrations after instantiation go straight to the live instance.
+ *
+ * `createStyle` passes every style object through `StyleSheet.create` so React Native can intern it on the native side; skipping this would cause equality checks in layout diffing to always fail.
+ */
 export class MobileStyleRegistry extends CodeleapStyleRegistry {
   constructor() {
     super(persistor)

package/src/components/ActivityIndicator/index.tsx

@@ -4,7 +4,6 @@ import { ActivityIndicatorProps } from './types'
 import { MobileStyleRegistry } from '../../Registry'
 import { AnyRecord, IJSX, StyledComponentProps } from '@codeleap/styles'
 import { useStylesFor } from '../../hooks'
-import { ActionIconProps } from '../ActionIcon'
 
 export * from './styles'
 export * from './types'
@@ -23,6 +22,8 @@ export const ActivityIndicator = <T extends React.ComponentType = typeof RNActiv
 
   const wrapperStyle = styles?.wrapper as CSSProperties
 
+  /** `color` and `size` are extracted from the style token rather than passed as props so that
+   *  theme variants can control them via the design-token system instead of inline overrides. */
   const color = wrapperStyle?.color || '#000'
   const size = (wrapperStyle?.height || wrapperStyle?.width || 'large') as number
 
@@ -39,7 +40,7 @@ export const ActivityIndicator = <T extends React.ComponentType = typeof RNActiv
 ActivityIndicator.styleRegistryName = 'ActivityIndicator'
 ActivityIndicator.elements = ['wrapper']
 ActivityIndicator.rootElement = 'wrapper'
-ActivityIndicator.defaultProps = {} as Partial<ActionIconProps>
+ActivityIndicator.defaultProps = {} as Partial<ActivityIndicatorProps>
 
 ActivityIndicator.withVariantTypes = <S extends AnyRecord>(styles: S) => {
   return ActivityIndicator as (<T extends React.ComponentType = typeof RNActivityIndicator>(props: StyledComponentProps<ActivityIndicatorProps<T>, typeof styles>) => IJSX)

package/src/components/Autocomplete/index.tsx

@@ -34,6 +34,14 @@ const defaultGetLabel = (option) => {
   }
 }
 
+/**
+ * Unlike Select, Autocomplete renders inline (no modal) — the result list is positioned below
+ * the search input in the same scroll context, so `scrollEnabled` is false on the inner List to
+ * avoid nested scroll conflicts.
+ *
+ * `selectable` must be true for item presses to update `value`; without it, `onItemPressed`
+ * fires but selection state is never written.
+ */
 export const Autocomplete = <T extends string | number = string, Multi extends boolean = false>(autocomplete: AutocompleteProps<T, Multi>) => {
   const allProps = {
     ...Autocomplete.defaultProps,

package/src/components/Autocomplete/types.ts

@@ -23,6 +23,11 @@ export type AutocompleteRenderFN<T> = (props: AutocompleteRenderFNProps<T>) => R
 
 export type AutocompleteValue<T, Multi extends boolean = false> = Multi extends true ? T[] : T
 
+/**
+ * `value` and `onValueChange` are required (no uncontrolled mode); the component never owns
+ * selection state internally. `loadOptions` receives the raw search string — debounce (800 ms)
+ * is applied by the component, but rate-limiting beyond that is the caller's responsibility.
+ */
 export type ValueBoundAutocompleteProps<T, Multi extends boolean = false> = {
   options?: Options<T>
   defaultOptions?: Options<T>

package/src/components/Avatar/components/Content.tsx

@@ -6,6 +6,10 @@ import { AvatarText } from './Text'
 import { AvatarOverlayIcon } from './OverlayIcon'
 import { AvatarWrapper } from './Wrapper'
 
+/**
+ * When `children` are provided the sub-components (Badge, OverlayIcon, Illustration/Text) are
+ * NOT rendered automatically — the caller is fully responsible for composing them inside children.
+ */
 export const AvatarContent = ({ children }: React.PropsWithChildren) => {
   const { icon, image } = useAvatarContext()
 

package/src/components/Avatar/components/Wrapper.tsx

@@ -11,6 +11,11 @@ const UnMemoizedAvatarWrapper = ({ children }: React.PropsWithChildren) => {
   // @ts-expect-error ICSS
   const bgColor = styles?.touchable?.backgroundColor
 
+  /**
+   * Falls back to a deterministic colour derived from the first letter of `name` when no
+   * explicit `backgroundColor` is set in the style token, so initials avatars are always
+   * distinguishable without requiring per-avatar colour configuration.
+   */
   const randomBgColor = useMemo(() => {
     if (!!bgColor) return bgColor
 

package/src/components/AvatarGroup/index.tsx

@@ -9,6 +9,10 @@ import { useStylesFor } from '../../hooks'
 export * from './styles'
 export * from './types'
 
+/**
+ * Uses percentage-based `right` offset so overlap scales with the container width; a fixed
+ * pixel offset would break on different screen densities and container sizes.
+ */
 const getAvatarStyle = (index: number, displacement: number = 20.5) => {
   const right = index * displacement
   return { right: `${right}%` }

package/src/components/Backdrop/index.tsx

@@ -29,6 +29,7 @@ export const Backdrop = (props: BackdropProps) => {
 
   const isPressable = !!props?.onPress
 
+  /** Early return unmounts the node entirely when hidden, which means the `exiting` animation will NOT play — callers that need a fade-out must keep `visible` true until after the exit animation completes, or drive visibility through `opacity`/`pointerEvents` instead. */
   if (!visible) return null
 
   return (

package/src/components/Badge/index.tsx

@@ -10,6 +10,7 @@ import { useStylesFor } from '../../hooks'
 export * from './styles'
 export * from './types'
 
+/** Caps display at `maxCount+` so the badge dot stays small; truncation is visual only — the real count is always passed through props. */
 const defaultGetBadgeContent = ({ count, maxCount }: BadgeContent) => {
   if (Number(count) > maxCount) {
     return `${maxCount}+`
@@ -38,6 +39,7 @@ export const Badge = (props: BadgeProps) => {
     ...rest
   } = allProps
 
+  /** `badge={false}` or `badge={undefined}` hides the element entirely (returns null), not just empties it. */
   const visible = (TypeGuards.isBoolean(badge) && badge === true) || TypeGuards.isNumber(badge)
 
   const styles = useStylesFor(Badge.styleRegistryName, style)

package/src/components/Badge/types.ts

@@ -4,6 +4,11 @@ import { Text } from '../Text'
 import { View, ViewProps } from '../View'
 import { BadgeComposition } from './styles'
 
+/**
+ * The Badge is rendered inside the parent's layout flow, not absolutely positioned by default.
+ * To overlay it on a sibling (e.g. a notification dot on an icon), the parent must use
+ * `position: 'relative'` and the badge wrapper style must declare `position: 'absolute'`.
+ */
 export type BadgeProps =
   Omit<ViewProps, 'style'> &
   {

package/src/components/Button/index.tsx

@@ -61,6 +61,8 @@ export const Button = forwardRef<GetRefType<TouchableProps['ref']>, ButtonProps>
 
   const disableFeedback = !onPress || props?.noFeedback
 
+  // Two independent feedback tracks: text color animates via `textFeedback`, wrapper border
+  // animates via `wrapperFeedback`. Both are optional — omitting the style key disables that track.
   const { getFeedbackStyle } = usePressableFeedback(styles.text, {
     hightlightPropertyIn: 'color',
     hightlightPropertyOut: 'color',
@@ -77,6 +79,9 @@ export const Button = forwardRef<GetRefType<TouchableProps['ref']>, ButtonProps>
 
   const rightFeedback = getFeedbackStyle(pressed)
 
+  // `display: 'none'` on the leftIcon style element is the intended mechanism to suppress the
+  // icon slot when no `icon` prop is passed; the suppression check reads the resolved style rather
+  // than the prop so theme variants can control visibility without prop drilling.
   // @ts-expect-error This is a hack to hide the icon when there is no text
   const isLeftIconHidden = componentStyles?.leftIcon?.display != 'none'
 

package/src/components/Button/types.ts

@@ -11,6 +11,7 @@ export type ButtonProps =
     text?: string
     rightIcon?: AppIcon
     icon?: AppIcon
+    /** When true, replaces the left icon with an ActivityIndicator and keeps the button pressable (debounce still applies); disable separately if you want to block interaction. */
     loading?: boolean
     debounce?: number
     debugName: string

package/src/components/Calendar/index.tsx

@@ -13,6 +13,7 @@ dayjs.extend(isSameOrBefore)
 export * from './styles'
 export * from './types'
 
+/** react-native-calendars requires dates keyed as YYYY-MM-DD strings in markedDates; any other format silently produces no highlights. */
 const DATE_FORMAT = 'YYYY-MM-DD'
 
 export const Calendar = (props: CalendarProps) => {
@@ -27,6 +28,7 @@ export const Calendar = (props: CalendarProps) => {
 
   const isRange = Array.isArray(value)
 
+  /** `removeTimezoneAndFormat` strips the timezone offset before formatting so that a UTC midnight doesn't shift to the previous calendar day in negative-offset locales. */
   const stringValue = useMemo(() => {
     if (!value) return isRange ? [] : ''
 
@@ -68,6 +70,10 @@ export const Calendar = (props: CalendarProps) => {
     return marked
   }, [stringValue, isRange])
 
+  /**
+   * Range selection uses a two-tap model: first tap sets start (array of 1), second tap completes
+   * the range (array of 2). Tapping again resets to a new start. Always sorted so start ≤ end.
+   */
   const handleDateChange = useCallback((date: DateData) => {
     if (!onValueChange) return
 

package/src/components/Calendar/styles.ts

@@ -1,5 +1,10 @@
 import { Theme } from 'react-native-calendars/src/types'
 
+/**
+ * `calendar` maps to react-native-calendars' `theme` prop and must use the library's own Theme
+ * keys (camelCase colour/font tokens), not style-system tokens — the object is passed through
+ * verbatim without transformation.
+ */
 export type CalendarComposition = 'wrapper' | 'header' | 'calendar'
 
 export type CalendarThemeConfig = Theme

package/src/components/CalendarInput/index.tsx

@@ -13,6 +13,11 @@ import { InputOverlay, inputOverlayManager } from '../InputOverlay'
 export * from './styles'
 export * from './types'
 
+/**
+ * The calendar overlay is managed by `inputOverlayManager`, not local state — this means only
+ * one CalendarInput can be open at a time application-wide when `autoClosePeersCalendars` is true.
+ * Setting `overlay={false}` renders the calendar inline in the document flow instead.
+ */
 export const CalendarInput = (props: CalendarInputProps) => {
   const {
     style,
@@ -45,6 +50,10 @@ export const CalendarInput = (props: CalendarInputProps) => {
 
   const { isOpen, toggle, id } = inputOverlayManager.use()
 
+  /**
+   * For range mode, an incomplete selection (only start date chosen) intentionally shows an empty
+   * string so the TextInput doesn't display a partial "start - " label.
+   */
   const formattedValue = useMemo(() => {
     if (!inputValue) return ''
 

package/src/components/Checkbox/index.tsx

@@ -14,6 +14,7 @@ import { fields } from '@codeleap/form'
 export * from './styles'
 export * from './types'
 
+/** Reversed order puts the innerWrapper (the visual checkbox) before the label, matching right-aligned checkbox layouts without a separate style override. */
 const reversedOrder = [...InputBaseDefaultOrder].reverse()
 
 export const Checkbox = (props: CheckboxProps) => {
@@ -87,6 +88,7 @@ export const Checkbox = (props: CheckboxProps) => {
     dependencies: [inputValue, disabled],
   })
 
+  /** Same `__props` escape-hatch as RadioGroup — lets the style variant set the default side without requiring a prop at every call site. */
   // @ts-expect-error
   const _checkboxOnLeft = checkboxOnLeft ?? styles.__props?.checkboxOnLeft
 

package/src/components/Checkbox/styles.ts

@@ -8,6 +8,7 @@ export type CheckboxAnimationStates = 'checked' | 'unchecked' | 'disabled-checke
 
 export type CheckboxStates = InputBaseStates
 
+/** `*:transition` keys are consumed by `useAnimatedVariantStyles` to configure the Reanimated transition — they are not applied as RN styles directly. */
 export type CheckboxComposition =
   | CheckboxParts
   | `${CheckboxParts}:${CheckboxStates}`

package/src/components/Collapse/index.tsx

@@ -23,12 +23,14 @@ export const Collapse = (props: CollapseProps) => {
     ...props,
   }
 
+  /** Two separate SharedValues are required: `height` is the measured natural height (written once and never animated), while `animatedHeight` is the value that actually drives the transition. Keeping them separate avoids re-triggering `onLayout` effects when the animation runs. */
   const height = useSharedValue(0)
   const animatedHeight = useSharedValue(0)
 
   const onLayout = useCallback((event: LayoutChangeEvent) => {
     const measuredHeight = event.nativeEvent.layout.height
 
+    /** Guard prevents overwriting the measured height if children re-trigger layout (e.g. after a font-load or image decode). */
     if (height.value != 0) return
 
     if (measuredHeight) {
@@ -40,6 +42,7 @@ export const Collapse = (props: CollapseProps) => {
     }
   }, [open])
 
+  /** `maxHeight` is animated rather than `height` so the inner View can still measure its natural size via `onLayout`; animating `height` directly would freeze the measurement. The `'auto'` fallback keeps content visible before the first layout completes. */
   const animatedStyle = useAnimatedStyle(() => {
     return {
       maxHeight: height.value === 0 ? 'auto' : animatedHeight.value,

package/src/components/DatePickerModal/index.tsx

@@ -33,6 +33,7 @@ const OuterInputComponent: DatePickerModalProps['outerInputComponent'] = (props)
   />
 }
 
+/** Uses local `Date` getters (not UTC), so the displayed string shifts with the device timezone. Pass a custom `formatDate` to normalise if the stored value is UTC. */
 const defaultFormatDate: DatePickerModalProps['formatDate'] = (_date) => {
   if (!_date) return null
   const date = new Date(_date)
@@ -133,6 +134,11 @@ export const DatePickerModal = (props: DatePickerModalProps) => {
 
   const formattedDate = inputValue ? formatDate(inputValue) : ''
 
+  /**
+   * Staging ref for `commitDate === 'onConfirm'` mode: the picker fires `onDateChange` on every
+   * scroll tick, so writing to state there would cause excessive re-renders. Value is committed
+   * only when the user taps Confirm.
+   */
   const tempDate = useRef<Date | null>(initialDate instanceof Date ? initialDate : new Date(initialDate))
 
   const onConfirm = () => {

package/src/components/DatePickerModal/types.ts

@@ -29,6 +29,7 @@ export type DatePickerModalProps =
     debugName: string
     label?: string
     placeholder?: string
+    /** When false the native `react-native-date-picker` modal is used (`modal={true}`) without any custom wrapper, which means Modal-level style tokens and footer are not applied. */
     isCustomModal?: boolean
     mode?: DatePickerProps['mode']
     cancelButtonProps?: Partial<ButtonProps>
@@ -36,6 +37,7 @@ export type DatePickerModalProps =
     datePickerProps?: Partial<DatePickerProps>
     outerInputComponent?: React.ComponentType<DatePickerModalOuterInputProps>
     formatDate?: (date: Date) => string
+    /** `'onConfirm'` buffers the date in a ref until the user taps Confirm; `'onChange'` writes on every picker scroll tick. Choose `'onConfirm'` for controlled forms to avoid intermediate invalid states. */
     commitDate?: 'onConfirm' | 'onChange'
     showDoneButton?: boolean
     footerComponent?: React.ComponentType<DatePickerModalFooterProps>

package/src/components/EmptyPlaceholder/components/Button.tsx

@@ -5,6 +5,7 @@ import { useEmptyPlaceholderContext } from '../context'
 import { Button } from '../../Button'
 import { TypeGuards } from '@codeleap/types'
 
+/** Renders nothing unless `onPress` is a function — absence of a handler is the gate, not a `visible` prop. */
 export const EmptyPlaceholderButton = (props: EmptyPlaceholderButtonProps) => {
   const { styles, buttonText, text, onPress, ...buttonProps } = useEmptyPlaceholderContext(props)
 

package/src/components/EmptyPlaceholder/components/Content.tsx

@@ -14,6 +14,11 @@ const orderMap: Record<EmptyPlaceholderProps['order'][0], any> = {
   button: EmptyPlaceholderButton,
 }
 
+/**
+ * Acts as the layout root and the loading/content switch.
+ * When `loading` is true the entire content tree is replaced by the loading state —
+ * `order` and `children` are ignored until loading becomes false.
+ */
 export const EmptyPlaceholderContent = ({ children }: React.PropsWithChildren) => {
   const { loading, styles, order } = useEmptyPlaceholderContext()
 

package/src/components/EmptyPlaceholder/components/Loading.tsx

@@ -11,6 +11,9 @@ export const EmptyPlaceholderLoading = () => {
 
   if (!loading) return null
 
+  /** `LoadingComponent` is accepted as a pre-rendered element (not a component class/function),
+   *  so callers must pass `<MySpinner />`, not `MySpinner`. Passing a component reference will
+   *  fail the `isValidElement` check and fall through to the default ActivityIndicator. */
   if (React.isValidElement(LoadingComponent)) {
     return <>{LoadingComponent}</>
   }

package/src/components/EmptyPlaceholder/index.tsx

@@ -12,6 +12,12 @@ import { EmptyPlaceholderContent } from './components/Content'
 export * from './styles'
 export * from './types'
 
+/**
+ * Compound component — all props are forwarded to context so sub-components
+ * (Info, Button, Illustration) can be placed anywhere inside children without prop drilling.
+ * The `order` prop only controls the default slot rendering; when `children` is provided it
+ * bypasses the order map entirely and renders children directly inside the wrapper.
+ */
 export const EmptyPlaceholder = (props: EmptyPlaceholderProps) => {
   const {
     children,

package/src/components/FileInput/index.tsx

@@ -3,7 +3,7 @@ import { MobileFile } from '@codeleap/types'
 import { parseFilePathData } from '@codeleap/utils'
 import ImageCropPicker, { ImageOrVideo, Options } from 'react-native-image-crop-picker'
 import { FileInputImageSource, FileInputProps, FileInputRef, FileResult } from './types'
-import { alert } from '@codeleap/modals'
+import { alert } from '@codeleap/portals'
 
 export * from './types'
 

package/src/components/FileInput/types.ts

@@ -1,6 +1,6 @@
 import { AnyRef, MobileInputFile } from '@codeleap/types'
 import { Options } from 'react-native-image-crop-picker'
-import { AlertOptions } from '@codeleap/modals'
+import { AlertOptions } from '@codeleap/portals'
 
 export type FileInputImageSource = 'camera' | 'library' | 'fs'
 

package/src/components/Grid/types.ts

@@ -10,6 +10,10 @@ export type GridAugmentedRenderItemInfo<T> =
     isOnlyInRow: boolean
   }
 
+/**
+ * Changing `numColumns` at runtime requires a `key` change on the FlatList to force a full
+ * remount; React Native cannot dynamically update `numColumns` on an existing list.
+ */
 export type GridProps<T extends ListItem = ListItem> =
   Omit<FlatListProps<T>, 'style' | 'renderItem'> &
   {

package/src/components/Icon/index.tsx

@@ -25,6 +25,9 @@ export const IconComponent = (props: IconProps) => {
     ...props,
   }
 
+  // Icons are React components registered on the theme object at app startup — they are not
+  // font glyphs or image assets. If the name is not in the registry the component silently
+  // renders nothing, so a missing registration will not crash but will produce an invisible slot.
   const icons = useTheme(store => store.theme?.icons)
 
   const styles = useStylesFor(Icon.styleRegistryName, style)
@@ -42,6 +45,8 @@ export const IconComponent = (props: IconProps) => {
   if (badge || TypeGuards.isNumber(badge)) {
     const badgeStyles = useNestedStylesByKey('badge', styles)
 
+    // `size` is a shorthand not in RN's style spec; the @ts-expect-error suppresses that.
+    // The wrapper needs an explicit size so Badge can be absolutely positioned correctly.
     const sized = {
       // @ts-expect-error
       height: styles.icon?.size || styles.icon?.height || props?.size,

package/src/components/Image/index.tsx

@@ -76,6 +76,8 @@ export const Image = React.memo((props: ImageProps) => {
 
   const loadEndedEarly = React.useRef(false)
 
+  // The 60 ms delay before showing the overlay suppresses a flash when the image is already
+  // cached and resolves synchronously — `loadEndedEarly` acts as the cancellation flag.
   const loadProps = React.useRef({
     onLoadStart: () => {
       if (withLoadingOverlay) {
@@ -146,6 +148,8 @@ Image.withVariantTypes = <S extends AnyRecord>(styles: S) => {
   return Image as (props: StyledComponentProps<ImageProps, typeof styles>) => IJSX
 }
 
+/** `fast` defaults to true, meaning FastImage is used by default for disk/memory caching.
+ *  Set to false only when you need native `Image` semantics (e.g. animated GIFs, data URIs). */
 Image.defaultProps = {
   fast: true,
   resizeMode: 'contain',

package/src/components/Image/types.ts

@@ -10,6 +10,7 @@ export type ImageProps =
     fast?: boolean
     style?: StyledProp<ImageComposition>
     resizeMode?: keyof typeof FastImage.resizeMode
+    /** When set, the image becomes tappable and opens the ImageView spotlight viewer with this string as the image identifier. Requires `ImageView` to be mounted in the tree. */
     spotlight?: string
     maintainAspectRatio?: boolean
     withLoadingOverlay?: boolean | ((props: LoadingOverlayProps) => React.ReactElement)

package/src/components/ImageView/Spotlight.tsx

@@ -30,6 +30,11 @@ type TSpotlightCtx = {
 
 const SpotlightCtx = React.createContext({} as TSpotlightCtx)
 
+/**
+ * Must wrap any tree that uses `useSpotlight`, `useImageSpotlight`, or `Spotlight`.
+ * A single provider can host multiple named spotlights simultaneously — each `name` string
+ * is an isolated namespace, so different image galleries don't interfere.
+ */
 export const SpotlightProvider: React.FC<React.PropsWithChildren<any>> = ({ children }) => {
   const [spotlights, setSpotlights] = useState<TSpotlightCtx['spotlights']>({})
   const [indexes, setIndexes] = useState<TSpotlightCtx['indexes']>({})
@@ -45,6 +50,11 @@ export const SpotlightProvider: React.FC<React.PropsWithChildren<any>> = ({ chil
   </SpotlightCtx.Provider>
 }
 
+/**
+ * Returns an imperative API — call `open(id)` to display the viewer at the image matching `id`.
+ * The viewer's `imageIndex` is derived by finding the id in the ordered image list, so insertion
+ * order (creation timestamp) determines display order, not registration order.
+ */
 export function useSpotlight(name: string) {
   const ctx = useContext(SpotlightCtx)
 
@@ -122,6 +132,12 @@ export function useSpotlight(name: string) {
   }
 }
 
+/**
+ * Registers a single image into the named spotlight and returns `onImagePressed`.
+ * Pass `name=null` to opt out without conditionally calling the hook (hook rules safe).
+ * The image is automatically removed from the spotlight when the component unmounts,
+ * so stale images never appear in the gallery after the source component is gone.
+ */
 export const useImageSpotlight = (name: string | null, src: ImageProps['source']) => {
   const [id, setId] = useState(null)
   const spotlight = useSpotlight(name)

package/src/components/ImageView/component.tsx

@@ -7,6 +7,12 @@ import { StatusBar } from 'react-native'
 
 export type ImageViewProps = PropsOf<typeof _ImageView>
 
+/**
+ * Hides the status bar while the viewer is open via an imperative StatusBar call.
+ * `presentationStyle='overFullScreen'` is forced so the viewer covers navigation bars;
+ * overriding it will break the full-screen illusion on iOS.
+ * `doubleTapToZoomEnabled` is off by default to avoid conflicting gesture handlers in lists.
+ */
 export const ImageView = (props: ImageViewProps) => {
   onUpdate(() => {
     StatusBar.setHidden(props.visible)