@codeleap/web 6.3.0 → 6.8.0

package/src/components/RadioInput/types.ts

@@ -1,30 +1,38 @@
 import { Option } from '@codeleap/types'
-import { InputBaseProps } from '../InputBase'
-import { ReactNode } from 'react'
-import { ICSS, StyledProp } from '@codeleap/styles'
+import { ICSS, StyleProp } from '@codeleap/styles'
 import { RadioInputComposition } from './styles'
 import { SelectableField } from '@codeleap/form'
+import { FieldProps } from '../Field'
 
 type RadioOption<T extends string | number> = Option<T> & {
   disabled?: boolean
 }
 
+export interface RadioInputStyleDef {
+  __internal: Record<RadioInputComposition, ICSS>
+}
+
+/**
+ * Props for `RadioInput`.
+ * `options` is the full ordered list of choices; individual options may carry a `disabled` flag that overrides the top-level `disabled`.
+ */
 export type RadioInputProps<T extends string | number> =
-  Omit<InputBaseProps, 'style'> &
-  {
+  Pick<FieldProps, 'label' | 'helper' | 'leftSection' | 'rightSection'> & {
     options: RadioOption<T>[]
-    label: ReactNode
-    style?: StyledProp<RadioInputComposition>
+    style?: StyleProp<RadioInputComposition, keyof RadioInputStyleDef>
     field?: SelectableField<T, any>
     value?: T
     onValueChange?: (value: T) => void
+    disabled?: boolean
+    debugName?: string
   }
 
+/** Internal props for the per-option row rendered inside `RadioInput`. */
 export type RadioOptionProps<T extends string | number> = {
   item: RadioOption<T>
   selected: boolean
   onSelect(): void
-  styles?: Record<RadioInputComposition, ICSS>
+  styles: Record<RadioInputComposition, ICSS>
   debugName?: string
   disabled?: boolean
   separator?: boolean

package/src/components/SearchInput/index.tsx

@@ -2,6 +2,7 @@ import React, { useState } from 'react'
 import { TextInput, TextInputProps } from '../TextInput'
 import { AnyFunction, TypeGuards } from '@codeleap/types'
 import { AppIcon } from '@codeleap/styles'
+import { FieldSectionProps } from '../Field'
 
 export type SearchInputProps = {
   placeholder: string
@@ -9,14 +10,26 @@ export type SearchInputProps = {
   debugName: string
   clearIcon?: AppIcon
   searchIcon?: AppIcon
+  /** Delay in milliseconds before `onSearchChange` fires after the user stops typing; pass `null` to disable debouncing. */
   debounce?: number
+  /** Called with the current search string after the debounce delay (or immediately if `debounce` is `null`). */
   onSearchChange: (search: string) => void
+  /** Called with `true` when the user starts typing and `false` once the debounce timer fires. */
   onTypingChange?: (isTyping: boolean) => void
+  /** Controlled value setter; provide together with `value` to make the input fully controlled. */
   onValueChange?: (search: string) => void
   onClear?: AnyFunction
+  /** Replaces the default clear button; receives field section props plus a `clear()` callback. */
+  renderClearButton ?: (props: FieldSectionProps&{clear: () => void}) => React.ReactNode
   defaultValue?: string
 } & Partial<TextInputProps>
 
+/**
+ * Text input specialised for search with optional debouncing, a clearable state, and typing-state callbacks.
+ * Operates as an uncontrolled input by default (`defaultValue`); pass `value` + `onValueChange` to make it controlled.
+ * The clear button is only shown while the field has non-whitespace content and `clearable` is true.
+ * Uses: `TextInput`
+ */
 export const SearchInput = (props: SearchInputProps) => {
   const {
     debugName,
@@ -30,6 +43,7 @@ export const SearchInput = (props: SearchInputProps) => {
     debounce,
     value,
     onValueChange,
+    renderClearButton,
     defaultValue,
     ...rest
   } = {
@@ -40,7 +54,7 @@ export const SearchInput = (props: SearchInputProps) => {
   const hasStateProps = !TypeGuards.isNil(value) && TypeGuards.isFunction(onValueChange)
 
   const [search, setSearch] = hasStateProps ? [value, onValueChange] : useState(defaultValue)
-  const setSearchTimeout = React.useRef<NodeJS.Timer | null>(null)
+  const setSearchTimeout = React.useRef<ReturnType<typeof setTimeout> | null>(null)
 
   const handleChangeSearch = (value: string) => {
     setSearch(value)
@@ -65,6 +79,16 @@ export const SearchInput = (props: SearchInputProps) => {
 
   const showClearIcon = !!String(search)?.trim() && clearable
 
+
+  let rightSection = (props:FieldSectionProps) => {
+    if(!showClearIcon) return null
+
+    return renderClearButton?.({
+      ...props,
+      clear: handleClear
+    }) ?? null
+  }
+
   return (
     <TextInput
       value={search}
@@ -74,15 +98,12 @@ export const SearchInput = (props: SearchInputProps) => {
         handleChangeSearch(value)
       }}
       debugName={`Search ${debugName}`}
-      rightIcon={showClearIcon && {
-        debugName: `Search ${debugName} right icon`,
-        name: clearIcon,
-        onPress: handleClear,
-      }}
-      leftIcon={{
-        debugName: `Search ${debugName} left icon`,
-        name: searchIcon,
-      }}
+      type='search'
+
+      rightSection={
+        props?.rightSection ?? rightSection
+      }
+
       {...rest}
     />
   )

package/src/components/SectionFilters/index.tsx

@@ -60,6 +60,12 @@ const ItemOption = (props: OptionProps) => {
   )
 }
 
+/**
+ * Grouped filter panel that lets users toggle labelled options across multiple sections,
+ * with a two-stage draft/commit flow and an Apply / Clear footer.
+ * Renders nothing when `data` is empty.
+ * Uses: `View`, `Text`, `Button`
+ */
 export const SectionFilters = (props: SectionFiltersProps) => {
   const {
     data,

package/src/components/SectionFilters/types.ts

@@ -1,14 +1,17 @@
-import { ButtonComposition, ButtonProps } from '../Button'
-import { StylesOf } from '@codeleap/types'
+import { ButtonProps } from '../Button'
 import { SectionFiltersComposition } from './styles'
-import { StyledProp } from '@codeleap/styles'
+import { ICSS, StyleProp } from '@codeleap/styles'
 
+export interface SectionFiltersStyleDef {}
+
+/** A selectable option within a `SectionFilters` item; `label` falls back to `value` when omitted. */
 export type ItemOptionProps = {
   label?: string | number
   value: string | number
   itemProps?: Omit<ButtonProps, 'debugName'>
 }
 
+/** Internal payload passed to the selection handler when an option button is pressed. */
 export type OnPressOptionProps = {
   item: ItemProps
   option: ItemOptionProps
@@ -16,17 +19,23 @@ export type OnPressOptionProps = {
   hasMultipleOptions: boolean
 }
 
+/** Describes a filter section with its own group of options; items without `options` are treated as single-value toggles. */
 export type ItemProps = {
   id: string | number
   label?: string | number
+  /** When `true`, multiple `options` within this item can be active simultaneously. */
   canSelectMultiple?: boolean
   descriptionLabel?: string
+  /** When `false`, the `descriptionLabel` / `label` heading above the options is hidden. Defaults to `true`. */
   showDescriptionLabel?: boolean
   options?: ItemOptionProps[]
+  /** Extra `Button` props applied to all option buttons in this item (overridden by `ItemOptionProps.itemProps`). */
   itemProps?: Omit<ButtonProps, 'debugName'>
+  /** Extra `Button` props applied to an option button only while that option is selected. */
   selectedItemProps?: Omit<ButtonProps, 'debugName'>
 }
 
+/** Payload delivered to the `onSelectItem` callback whenever any option button is pressed. */
 export type onSelectItemProps = {
   id: ItemProps['id']
   option: ItemOptionProps
@@ -35,36 +44,49 @@ export type onSelectItemProps = {
 type ApplyFunction = (items?: ItemProps[]) => void
 type ClearFunction = () => void
 
+/** Props injected into the footer component (default or custom via `renderFooterComponent`). */
 export type SectionFilterFooterProps = {
   onClear: ClearFunction
   onApply: ApplyFunction
+  /** `true` when both the draft and committed selections are empty; use to disable Apply / Clear buttons. */
   shouldDisableActions: boolean
 }
 
 type Item = Record<string, any> | Array<any>
 
+/**
+ * Props for `SectionFilters`.
+ * Selections are managed through an internal two-stage draft/commit model:
+ * changes accumulate in the draft and are only promoted to `selectedItems` when the apply action fires,
+ * unless `filterOnOptionPress` is `true`, in which case each press also commits immediately.
+ */
 export type SectionFiltersProps = {
   data?: ItemProps[]
+  /** Committed (applied) selection state; provide with `setSelectedItems` for controlled usage. */
   selectedItems?: Item
   setSelectedItems?: (value: Item) => void
+  /** Draft (pending) selection state; provide with `setDraftItems` for controlled usage. */
   draftItems?: Item
   setDraftItems?: (value: Item) => void
+  /** Called immediately after any option is pressed, before the draft is updated. */
   onSelectItem?: (item: onSelectItemProps) => void
   onClearItems?: ClearFunction
   onApplyItems?: ApplyFunction
+  /** Replaces the default Apply / Clear footer; receives `SectionFilterFooterProps`. */
   renderFooterComponent?: (props: SectionFilterFooterProps) => React.ReactElement
   applyFilterButtonProps?: Omit<ButtonProps, 'debugName'>
   clearFilterButtonProps?: Omit<ButtonProps, 'debugName'>
+  /** When `true`, each option press also commits the draft immediately (bypasses the two-stage model). Defaults to `false`. */
   filterOnOptionPress?: boolean
   applyButtonText?: string
   clearButtonText?: string
-  style?: StyledProp<SectionFiltersComposition>
+  style?: StyleProp<SectionFiltersComposition, keyof SectionFiltersStyleDef>
 }
 
 export type OptionProps = {
   option: ItemOptionProps
   item: ItemProps
-  styles: StylesOf<ButtonComposition>
+  styles: ICSS
   selectedItems: object
   onPress: () => void
   canSelectMultiple: boolean

package/src/components/Select/context.tsx

@@ -0,0 +1,262 @@
+import { createContext, useCallback, useContext, useId, useImperativeHandle, useRef, useState, type RefObject } from 'react'
+import { logger } from '@codeleap/logger'
+import { TypeGuards } from '@codeleap/types'
+import { useValidate } from '@codeleap/form'
+import { type Key, type Selection } from 'react-aria-components'
+import { useListFocus, type ListFocusHandle, type ListFocusStrategy } from '../../lib/hooks/useListFocus'
+import { usePopoverDismiss } from '../../lib/hooks/usePopoverDismiss'
+import { useStylesFor } from '../../lib/hooks/useStylesFor'
+import { useTriggerWidth } from './useTriggerWidth'
+import { toDataAttrs } from '../../lib'
+import { Field } from '../Field'
+import { getFieldIds } from '../Field/context'
+import { type SelectComposition } from './styles'
+import { type SelectProps, type SelectFieldContext } from './types'
+
+function joinLabels<T extends { label: string; value: any }>(
+  values: T['value'][],
+  options: T[],
+  separator: string
+): string {
+  return (values ?? [])
+    .map(v => options?.find(o => o.value === v)?.label ?? String(v))
+    .join(separator)
+}
+
+/** Shape of the value carried by `SelectContext`; consumed by `SelectTrigger`, `SelectPopover`, and `SelectList`. */
+export type SelectContextValue = {
+  isOpen: boolean
+  isFocused: boolean
+  hasValue: boolean
+  displayLabel: string
+  selectedKeys: Set<string>
+  fieldContext: SelectFieldContext
+  stateAttrs: Record<string, string>
+
+  triggerRef: RefObject<HTMLElement | null>
+  popoverRef: RefObject<HTMLElement | null>
+  listBoxDOMRef: RefObject<HTMLDivElement | null>
+  listAutoFocusRef: RefObject<boolean | undefined>
+  triggerWidthStyle: React.CSSProperties
+
+  handleFocus: () => void
+  handleBlur: () => void
+  handleOpenChange: (open: boolean) => void
+  handleSelectionChange: (keys: Selection) => void
+  focusList: (strategy?: ListFocusStrategy) => void
+  openDropdown: (focus?: boolean) => void
+  closeDropdown: () => void
+
+  styles: Record<SelectComposition, any>
+
+  fieldId: string
+  labelId: string
+  helperId: string
+  helperContent: React.ReactNode
+
+  options: any[]
+  value: any
+  multiple: boolean
+  disabled: boolean
+  placement: SelectProps['placement']
+  debugName?: string
+  listRef?: RefObject<ListFocusHandle | null>
+}
+
+/** React context that shares `SelectContextValue` across all sub-components of a `Select`. */
+export const SelectContext = createContext<SelectContextValue | null>(null)
+
+/**
+ * Reads the nearest `SelectContext` value.
+ * Must be called inside a `SelectProvider` tree; throws if the context is absent.
+ */
+export const useSelectContext = (): SelectContextValue => {
+  const ctx = useContext(SelectContext)
+  if (!ctx) throw new Error('useSelectContext must be used inside Select.Provider')
+  return ctx
+}
+
+/**
+ * Derives the full `SelectContextValue` from `SelectProps`, encapsulating open/focus state, validation,
+ * key-based selection, display-label construction, and trigger-width measurement.
+ * Intended for use inside `SelectProvider`; consume the result via `useSelectContext` in sub-components.
+ */
+export function useSelectProvider(props: SelectProps<any, any>): SelectContextValue {
+  const {
+    options = [],
+    value,
+    onValueChange,
+    multiple,
+    limit,
+    placeholder,
+    disabled,
+    focused: _focused,
+    error,
+    validate,
+    onBlur,
+    onFocus,
+    placement = 'bottom start',
+    separatorMultiValue = ', ',
+    listRef,
+    onOpenChange: onOpenChangeProp,
+    helper,
+    debugName,
+    style,
+  } = props
+
+  const validation = useValidate(value, validate)
+  const hasError = validation?.showError || !!error
+  const errorMessage = validation?.message || error
+
+  const [isFocused, setIsFocused] = useState(false)
+  const [isOpen, setIsOpen] = useState(false)
+
+  const triggerRef = useRef<HTMLElement | null>(null)
+  const popoverRef = useRef<HTMLElement | null>(null)
+  const listBoxDOMRef = useRef<HTMLDivElement | null>(null)
+  const listAutoFocusRef = useRef<boolean | undefined>(undefined)
+
+  useImperativeHandle(props.ref as any, () => ({
+    focus: () => triggerRef.current?.focus(),
+  }), [])
+
+  const listFocus = useListFocus(listBoxDOMRef, listRef)
+
+  const focusList = useCallback((strategy?: ListFocusStrategy) => {
+    if (!listBoxDOMRef.current) {
+      logger.warn('[Select] focusList called before list is mounted')
+      return
+    }
+    listFocus.focus(strategy)
+  }, [listFocus])
+
+  const handleOpenChange = useCallback((open: boolean) => {
+    setIsOpen(open)
+    onOpenChangeProp?.(open)
+  }, [onOpenChangeProp])
+
+  usePopoverDismiss({ popoverRef, triggerRef, isOpen, onClose: () => handleOpenChange(false) })
+
+  const hasValue = multiple
+    ? ((value as any[])?.length ?? 0) > 0
+    : !TypeGuards.isNil(value)
+
+  const activeFocused = isFocused || !!_focused
+
+  const fieldContext: SelectFieldContext = {
+    disabled: !!disabled,
+    hasValue,
+    error: !!hasError,
+    focused: activeFocused,
+    multiple: !!multiple,
+  }
+
+  const styles = useStylesFor('Select', style, fieldContext) as Record<SelectComposition, any>
+  const stateAttrs = toDataAttrs(fieldContext) as Record<string, string>
+
+  const handleFocus = useCallback(() => { setIsFocused(true); onFocus?.() }, [onFocus])
+  const handleBlur = useCallback(() => {
+    validation?.onInputBlurred()
+    setIsFocused(false)
+    onBlur?.()
+  }, [validation?.onInputBlurred, onBlur])
+
+  const handleSelectionChange = useCallback((keys: Selection) => {
+    if (multiple) {
+      const newValues = [...(keys as Set<Key>)].map(k =>
+        options.find(o => String(o.value) === String(k))?.value ?? k
+      )
+      if (TypeGuards.isNumber(limit) && newValues.length > ((value as any[])?.length ?? 0) && newValues.length > limit) return
+      onValueChange?.(newValues as any)
+    } else {
+      const key = [...(keys as Set<Key>)][0]
+      if (!TypeGuards.isNil(key)) {
+        onValueChange?.(key as any)
+        setIsOpen(false)
+      }
+    }
+  }, [multiple, options, limit, value, onValueChange])
+
+  const openDropdown = useCallback((focus?: boolean) => {
+    listAutoFocusRef.current = focus
+    setIsOpen(true)
+  }, [])
+
+  const closeDropdown = useCallback(() => setIsOpen(false), [])
+
+  const fieldId = useId()
+  const { label: labelId, helper: helperId } = getFieldIds(fieldId)
+  const helperContent = hasError ? errorMessage : helper
+
+  const selectedKeys: Set<string> = multiple
+    ? new Set(((value as any[]) ?? []).map((v: any) => String(v)))
+    : hasValue ? new Set([String(value)]) : new Set()
+
+  const displayLabel = multiple
+    ? (hasValue ? joinLabels(value as any[], options, separatorMultiValue) : (placeholder ?? ''))
+    : (hasValue
+        ? (options.find(o => String(o.value) === String(value))?.label ?? String(value))
+        : (placeholder ?? ''))
+
+  const triggerWidthStyle = useTriggerWidth(triggerRef)
+
+  return {
+    isOpen,
+    isFocused,
+    hasValue,
+    displayLabel,
+    selectedKeys,
+    fieldContext,
+    stateAttrs,
+    triggerRef,
+    popoverRef,
+    listBoxDOMRef,
+    listAutoFocusRef,
+    triggerWidthStyle,
+    handleFocus,
+    handleBlur,
+    handleOpenChange,
+    handleSelectionChange,
+    focusList,
+    openDropdown,
+    closeDropdown,
+    styles,
+    fieldId,
+    labelId,
+    helperId,
+    helperContent,
+    options,
+    value,
+    multiple: !!multiple,
+    disabled: !!disabled,
+    placement,
+    debugName,
+    listRef,
+  }
+}
+
+type SelectProviderProps = React.PropsWithChildren<SelectProps<any, any>>
+
+/**
+ * Wires up `Field.Provider` and `SelectContext.Provider` so that all `Select` sub-components
+ * receive both field layout state and select-specific state.
+ * Must wrap `SelectTrigger`, `SelectPopover`, and `SelectList` when composing a custom select UI.
+ */
+export const SelectProvider = ({ children, ...props }: SelectProviderProps) => {
+  const value = useSelectProvider(props)
+  return (
+    <Field.Provider
+      id={value.fieldId}
+      context={value.fieldContext}
+      label={props.label}
+      helper={value.helperContent}
+      leftSection={props.leftSection}
+      rightSection={props.rightSection}
+      componentName='select'
+    >
+      <SelectContext.Provider value={value}>
+        {children}
+      </SelectContext.Provider>
+    </Field.Provider>
+  )
+}

package/src/components/Select/elements.tsx

@@ -0,0 +1,126 @@
+import { useCallback, type RefObject } from 'react'
+import {
+  ListBox,
+  ListBoxItem,
+  Popover,
+  type ListBoxItemRenderProps,
+} from 'react-aria-components'
+import { ICSS } from '@codeleap/styles'
+import { Field } from '../Field'
+import { View } from '../View'
+import { Text } from '../Text'
+import { Touchable } from '../Touchable'
+import { useSelectContext } from './context'
+import { type ItemRenderState, type SelectListProps } from './types'
+
+/**
+ * Clickable trigger button that opens or closes the `SelectPopover`.
+ * Reads all state from `SelectContext`; must be rendered inside a `SelectProvider`.
+ * Uses: `Field.Box`, `Field.SectionSlot`, `Text`, `Touchable`
+ */
+export const SelectTrigger = () => {
+  const {
+    styles, triggerRef, disabled, handleFocus, handleBlur,
+    isOpen, handleOpenChange, labelId, helperId, helperContent,
+    displayLabel, hasValue, stateAttrs, debugName,
+  } = useSelectContext()
+
+  return (
+    <Field.Box
+      component={Touchable}
+      ref={triggerRef as RefObject<HTMLElement>}
+      style={styles.trigger}
+      disabled={disabled}
+      onPress={() => handleOpenChange(!isOpen)}
+      onFocus={handleFocus}
+      onBlur={handleBlur}
+      aria-labelledby={labelId}
+      aria-describedby={helperContent ? helperId : undefined}
+      {...stateAttrs}
+    >
+      <Field.SectionSlot position='left' />
+      <Text
+        text={displayLabel}
+        debugName={debugName}
+        style={hasValue ? styles.value : styles.placeholder}
+      />
+      <Field.SectionSlot position='right' />
+    </Field.Box>
+  )
+}
+
+/**
+ * Non-modal `react-aria-components` `Popover` anchored to `SelectTrigger` and sized to match its width.
+ * Must be rendered inside a `SelectProvider`; wrap `SelectList` or custom list content as children.
+ */
+export const SelectPopover = ({ children }: React.PropsWithChildren) => {
+  const { styles, isOpen, handleOpenChange, triggerRef, popoverRef, triggerWidthStyle, placement } = useSelectContext()
+
+  return (
+    <Popover
+      triggerRef={triggerRef}
+      isOpen={isOpen}
+      ref={popoverRef}
+      onOpenChange={handleOpenChange}
+      css={(styles as any).popover}
+      isNonModal
+      style={triggerWidthStyle}
+      placement={placement}
+    >
+      {children}
+    </Popover>
+  )
+}
+
+/**
+ * Accessible list box that renders the selectable options, with support for single and multi-select modes.
+ * Accepts optional `renderItem` and `renderEmpty` overrides; falls back to default `Text`-based rendering.
+ * Must be rendered inside a `SelectProvider`.
+ * Uses: `Text`, `View`
+ */
+export const SelectList = <T extends { label: string; value: any } = { label: string; value: any }>({
+  renderItem,
+  renderEmpty,
+}: SelectListProps<T>) => {
+  const {
+    styles, options, selectedKeys, handleSelectionChange,
+    multiple, listBoxDOMRef, listAutoFocusRef, debugName, focusList, labelId,
+  } = useSelectContext()
+
+  const renderListItem = useCallback((item: T) => (
+    <ListBoxItem
+      key={String(item.value)}
+      id={String(item.value)}
+      textValue={item.label}
+      css={(styles as any).listItem}
+    >
+      {({ isSelected, isFocused: isItemFocused }: ListBoxItemRenderProps) => {
+        const state: ItemRenderState = { isSelected, isFocused: isItemFocused }
+        if (renderItem) return <>{renderItem(item, state, focusList)}</>
+        return <Text text={item.label} debugName={debugName} style={styles.listItemText} />
+      }}
+    </ListBoxItem>
+  ), [renderItem, styles, debugName, focusList])
+
+  const renderEmptyState = useCallback(() => {
+    if (renderEmpty) return <>{renderEmpty({ style: styles.emptyState as ICSS, focusList })}</>
+    return <View style={styles.emptyState}><Text text='No results' debugName={debugName} /></View>
+  }, [renderEmpty, styles, debugName, focusList])
+
+  return (
+    <ListBox
+      ref={listBoxDOMRef}
+      selectionMode={multiple ? 'multiple' : 'single'}
+      selectedKeys={selectedKeys}
+      onSelectionChange={handleSelectionChange}
+      items={options as T[]}
+      autoFocus={listAutoFocusRef.current}
+      css={(styles as any).list}
+      renderEmptyState={renderEmptyState}
+      aria-labelledby={labelId}
+    >
+      {renderListItem}
+    </ListBox>
+  )
+}
+