@codeleap/web 6.3.0 → 6.8.0

package/src/components/Field/elements.tsx

@@ -0,0 +1,159 @@
+import React, { RefObject } from 'react'
+import { TypeGuards } from '@codeleap/types'
+import { Text } from '../Text'
+import { View } from '../View'
+import { useFieldContext } from './context'
+import { FieldSectionProps, FieldStateDataProps } from './types'
+import { ICSS } from '@codeleap/styles'
+import { toDataAttrs } from '../../lib'
+import { Touchable } from '../Touchable'
+
+type HeadingProps = React.PropsWithChildren<{
+  style?: ICSS
+  component?: React.ComponentType<any>
+  ref?: RefObject<HTMLParagraphElement | null>
+}>
+
+/**
+ * Renders the field label linked to the input via `aria-labelledby`.
+ * Reads content from `FieldProvider` context; renders nothing when no label is present.
+ * Must be inside `FieldProvider`.
+ */
+export const FieldHeading = (props: HeadingProps) => {
+  const ctx = useFieldContext()
+
+  const label = props?.children ?? ctx?.props?.label
+
+  if(!label && !props.component) return null
+
+  const Component = props?.component ?? Text
+
+
+  return <Component id={ctx.labelId} component={'label'} ref={props.ref} style={[ctx?.styles?.heading, props?.style]} className={ctx.getClassName('heading')} >
+    {label}
+  </Component>
+}
+
+type HelperProps = React.PropsWithChildren<{
+  style?: ICSS
+  component?: React.ComponentType<any>
+  ref?: RefObject<HTMLParagraphElement | null>
+}>
+
+/**
+ * Renders the field helper/description text.
+ * Reads content from `FieldProvider` context; renders nothing when no helper is present.
+ * Must be inside `FieldProvider`.
+ */
+export const FieldHelper = (props: HelperProps) => {
+  const ctx = useFieldContext()
+
+  const label = props?.children ?? ctx?.props?.helper
+
+  if(!label && !props.component) return null
+  
+
+  const Component = props?.component ?? Text.Span
+
+  return <Component id={ctx.helperId} ref={props.ref} style={[ctx?.styles?.helper, props?.style]} className={ctx.getClassName('helper')}>
+    {label}
+  </Component>
+}
+
+type BoxProps = React.PropsWithChildren<{
+  style?: ICSS
+  component?: React.ComponentType<any>
+  onPress?: () => void
+  ref?: RefObject<HTMLElement | null>
+  [key: string]: any
+}>
+
+/**
+ * Input container row that receives state `data-*` attributes from context;
+ * renders as `Touchable` when `onPress` is provided, otherwise as `View`.
+ * Must be inside `FieldProvider`.
+ * Uses: `View`, `Touchable`
+ */
+export const FieldBox = ({ component = View, style, ref, children, onPress, ...rest }: BoxProps) => {
+  const ctx = useFieldContext()
+  const attrs = toDataAttrs(ctx.stateContext)
+
+  if (onPress) {
+    return (
+      <Touchable debugName='field-box' css={[ctx?.styles?.box, style]} onPress={onPress} className={ctx.getClassName('box')} {...attrs} {...rest} ref={ref ?? ctx?.props?.boxRef}>
+        {children}
+      </Touchable>
+    )
+  }
+
+  return (
+    <View css={[ctx?.styles?.box, style]} className={ctx.getClassName('box')} {...attrs} {...rest} ref={ref ?? ctx?.props?.boxRef}>
+      {children}
+    </View>
+  )
+}
+
+type WrapperProps = React.PropsWithChildren<{
+  style?: ICSS
+  component?: React.ComponentType<any>
+  ref?: RefObject<HTMLDivElement | null>
+}>
+
+/**
+ * Outermost container for the full field layout; forwards state `data-*`
+ * attributes and resolves the `wrapperRef` from context.
+ * Must be inside `FieldProvider`.
+ */
+export const FieldWrapper = (props: WrapperProps) => {
+  const ctx = useFieldContext()
+  const Component = props?.component ?? View
+
+  const attrs = toDataAttrs(ctx.stateContext)
+
+  return <Component ref={props.ref ?? ctx?.props?.wrapperRef } style={[ctx.styles.wrapper, props?.style]} {...attrs} className={ctx.getClassName('wrapper')}>
+    {props?.children}
+  </Component>
+}
+
+type SectionSlotProps = React.PropsWithChildren<{
+  position?: FieldSectionProps['data-section-position']
+  style?: ICSS
+  component?: React.ComponentType<FieldSectionProps>
+}>
+
+/**
+ * Renders either the `leftSection` or `rightSection` prop from `FieldProvider`
+ * context; supports static ReactNode and render-function forms.
+ * Must be inside `FieldProvider`.
+ */
+export const SectionSlot = (props: SectionSlotProps) => {
+  const ctx = useFieldContext()
+
+  const sectionProp = props?.position === 'left' ? ctx.props.leftSection : ctx.props.rightSection
+    const style = props.position === 'left' ? ctx.styles.leftSection : ctx.styles.rightSection
+  let Component: React.ComponentType<FieldSectionProps> | null = null
+
+  if (props?.component) {
+    Component = props?.component
+  } else if (TypeGuards.isFunction(sectionProp)) {
+    Component = sectionProp
+  } else {
+
+    if(!sectionProp) return null
+    
+    return <View style={[ctx.styles.section, style]}  className={ctx.getClassName('section', `${props.position}_section`)}>
+      {sectionProp}
+    </View>
+  }
+
+
+  const attrs = toDataAttrs(ctx.stateContext)
+  const Render = Component as React.ComponentType<any>
+
+  return <Render
+    {...attrs}
+    data-section-position={props.position}
+    style={[ctx.styles.section, style]}
+    className={ctx.getClassName('section', `${props.position}_section`)}
+  />
+}

package/src/components/Field/index.tsx

@@ -0,0 +1,55 @@
+import { AnyRecord } from '@codeleap/types'
+import { FieldProvider, getFieldIds } from './context'
+import { FieldBox, FieldHeading, FieldHelper, FieldWrapper, SectionSlot } from './elements'
+import { FieldProps } from './types'
+import { IJSX, StyledComponentProps } from '@codeleap/styles'
+import { WebStyleRegistry } from '../../lib'
+
+/**
+ * Form field layout shell that composes a label, input box, helper text, and
+ * left/right section slots around any input child; distributes state (disabled,
+ * error, focused, hasValue) via context to all sub-elements.
+ * Exposes: `Field.Wrapper`, `Field.Box`, `Field.Heading`, `Field.Helper`,
+ * `Field.SectionSlot`, `Field.Provider`, `Field.getIds`.
+ * Uses: `FieldProvider`, `FieldWrapper`, `FieldHeading`, `FieldBox`, `FieldHelper`,
+ * `SectionSlot`, `WebStyleRegistry`
+ */
+export const Field = (props: React.PropsWithChildren<FieldProps>) => {
+
+  return <FieldProvider {...props}>
+    <FieldWrapper>
+      <FieldHeading />
+      <FieldBox >
+        <SectionSlot position='left'/>
+        {props?.children}
+        <SectionSlot position='right'/>
+      </FieldBox>
+      <FieldHelper />
+    </FieldWrapper>
+  </FieldProvider>
+}
+
+Field.withVariantTypes = <S extends AnyRecord>(styles: S) => {
+  return Field as (props: StyledComponentProps<FieldProps, typeof styles>) => IJSX
+}
+
+Field.styleRegistryName = 'Field'
+Field.rootElement = 'wrapper'
+Field.elements = [
+  'wrapper', 'box', 'heading', 'helper', 'section', 'leftSection', 'rightSection',
+]
+
+Field.SectionSlot = SectionSlot
+Field.Box = FieldBox
+Field.Wrapper = FieldWrapper
+Field.Heading = FieldHeading
+Field.Helper = FieldHelper
+Field.Provider = FieldProvider
+Field.getIds = getFieldIds
+
+WebStyleRegistry.registerComponent(Field)
+
+export * from './context'
+export * from './styles'
+export * from './types'
+export * from './useFieldInput'

package/src/components/Field/styles.ts

@@ -0,0 +1,18 @@
+import { ComponentContext } from '@codeleap/styles'
+
+export type FieldBoxSections = 'section' | 'leftSection' | 'rightSection'
+
+export type FieldParts = 'wrapper' | 'box' | 'heading' | 'helper' | FieldBoxSections
+
+export type FieldComposition = FieldParts
+
+/**
+ * Runtime state flags threaded through `FieldProvider` and forwarded as
+ * `data-*` attributes to every layout element so styles can react to them.
+ */
+export interface FieldStateContext extends ComponentContext {
+    hasValue?: boolean
+    disabled?: boolean
+    error?: boolean
+    focused?: boolean
+}

package/src/components/Field/types.ts

@@ -0,0 +1,51 @@
+import React, { RefObject } from 'react'
+import { FieldComposition, FieldStateContext } from './styles'
+import { ICSS, StyledProp, StyleProp } from '@codeleap/styles'
+import { DataAttrs } from '../../lib'
+
+export interface FieldStyleDef {
+  __internal: Record<FieldComposition, ICSS>
+}
+
+/** HTML `data-*` attribute counterparts of `FieldStateContext`, forwarded to DOM elements. */
+export type FieldStateDataProps = DataAttrs<FieldStateContext>
+
+/**
+ * Props injected into a function-style `leftSection` or `rightSection` renderer.
+ * Carries state data attributes so the section can style itself based on field state.
+ */
+export type FieldSectionProps = {
+  'data-section-position'?: 'left' | 'right'
+  className?: string
+  style?: ICSS
+} & FieldStateDataProps
+
+type FieldSection = React.ReactNode | ((state: FieldSectionProps) => React.ReactNode)
+
+/**
+ * Props for the `Field` component.
+ *
+ * State flags in `context` (disabled, error, focused, hasValue) are forwarded
+ * as `data-*` attributes to every layout element so CSS can style them.
+ */
+export type FieldProps = {
+    id?: string
+    label?: React.ReactNode
+    /** Help text rendered below the field box by `Field.Helper`. */
+    helper?: React.ReactNode
+    /** ReactNode or render function placed in the left slot of `Field.Box`. */
+    leftSection?: FieldSection
+    /** ReactNode or render function placed in the right slot of `Field.Box`. */
+    rightSection?: FieldSection
+    style?: StyleProp<FieldComposition, keyof FieldStyleDef>
+    /** State flags that drive disabled/error/focused/hasValue styling. */
+    context?: FieldStateContext
+    /** Added as a BEM-style prefix to generated class names alongside `field`. */
+    componentName?: string
+
+    boxRef?: RefObject<HTMLElement>
+    wrapperRef?: RefObject<HTMLElement>
+}
+
+/** Subset of `FieldProps` exposed to consumer components that embed a `Field`. */
+export type FieldExternalProps = Pick<FieldProps, 'label' | 'helper' | 'leftSection' | 'rightSection' | 'wrapperRef' | 'boxRef'>

package/src/components/{InputBase/useInputBase.ts → Field/useFieldInput.ts}

@@ -1,13 +1,22 @@
 import { useMemo, useRef } from 'react'
-// import { useWrappingScrollable } from ''
 import { Field, IFieldRef, fields, useField } from '@codeleap/form'
 import { AnyRecord, TypeGuards } from '@codeleap/types'
 
-export function useInputBase<V,  T extends Field<V, any, any, unknown> = Field<V, any, any, unknown>>(
+/**
+ * Bridges a `@codeleap/form` `Field` instance with an input element's DOM ref,
+ * or falls back to uncontrolled internal state when `onValueChange` and `value`
+ * are both provided.
+ *
+ * When a `field` instance is used, the hook registers blur/focus/getValue
+ * callbacks so the form layer can drive the input programmatically.
+ *
+ * Requires a `@codeleap/form` `Field` instance; does not need a React context.
+ */
+export function useFieldInput<V,  T extends Field<V, any, any, any> = Field<V, any, any, any>>(
   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
@@ -18,8 +27,6 @@ export function useInputBase<V,  T extends Field<V, any, any, unknown> = Field<V
 
   const innerInputRef = useRef<HTMLInputElement>(null)
 
-  // const scrollable = useWrappingScrollable()
-
   const fieldHandle = hasInternalState ? {} as Partial<ReturnType<typeof useField>> : useField<V, T>(field as T, [
     {
       blur() {
@@ -32,11 +39,7 @@ export function useInputBase<V,  T extends Field<V, any, any, unknown> = Field<V
         return innerInputRef.current.value as V
       },
       scrollIntoView() {
-        // @todo implement
         return
-        // return field.measurePosition(wrapperRef).then((measureResult) => {
-        //   field.scrollTo(scrollable, measureResult)
-        // })
       },
       ...params,
     },
@@ -53,4 +56,4 @@ export function useInputBase<V,  T extends Field<V, any, any, unknown> = Field<V
     inputValue: (hasInternalState ? value : fieldHandle?.value) as V,
     onInputValueChange: hasInternalState ? onValueChange : fieldHandle?.setValue,
   }
-}
+}

package/src/components/FileInput/index.tsx

@@ -1,10 +1,15 @@
-import React, { forwardRef, useImperativeHandle, useRef } from 'react'
+import React, { useImperativeHandle, useRef } from 'react'
 import { TypeGuards, WebInputFile } from '@codeleap/types'
 import { useCallback } from '@codeleap/hooks'
-import { FileInputProps, FileInputRef } from './types'
+import { FileInputProps } from './types'
 
 export * from './types'
 
+/**
+ * Invisible file-input that delegates file selection to the browser's native picker, exposed imperatively via `ref`.
+ * Renders a zero-size hidden `<input type="file">` — pair with a visible trigger that calls `ref.current.openFilePicker()`.
+ * Uses: `FileInputRef`
+ */
 export const FileInput = (props: FileInputProps) => {
   const inputRef = useRef<HTMLInputElement>(null)
 

package/src/components/FileInput/types.ts

@@ -2,15 +2,22 @@ import { WebInputFile } from '@codeleap/types'
 import { HTMLProps } from '../../types'
 import { RefObject } from 'react'
 
+/**
+ * Imperative handle exposed via `ref` on `FileInput`.
+ */
 export type FileInputRef = {
+  /** Opens the native file picker and resolves with the selected files. */
   openFilePicker: () => Promise<WebInputFile[]>
+  /** Resets the underlying `<input>` value so the same file can be re-selected. */
   clear: () => void
 }
 
-export type FileInputProps = 
-  Omit<HTMLProps<'input'>, 'type' | 'ref'> & 
+export type FileInputProps =
+  Omit<HTMLProps<'input'>, 'type' | 'ref'> &
   {
+    /** Called with the selected files after the user dismisses the picker. */
     onFileSelect?: (files: WebInputFile[]) => void
+    /** When `true` (default), the input value is cleared after each selection so the same file can trigger `onChange` again. */
     autoClear?: boolean
     ref?: RefObject<FileInputRef | null>
   }

package/src/components/Icon/index.tsx

@@ -1,17 +1,26 @@
 import { View } from '../View'
 import { useStylesFor } from '../../lib/hooks/useStylesFor'
-import { AnyRecord, IJSX, StyledComponentProps, useTheme } from '@codeleap/styles'
+import { AnyRecord, AppIcon, IJSX, StyledComponentProps, useTheme } from '@codeleap/styles'
 import { WebStyleRegistry } from '../../lib/WebStyleRegistry'
 import { IconProps } from './types'
+import { TypeGuards } from '@codeleap/types'
+import { Touchable } from '../Touchable'
 
 export * from './styles'
 export * from './types'
 
+/**
+ * Renders a theme-registered SVG icon; automatically wraps in `Touchable` when
+ * `onPress` is provided, and can render a sized empty placeholder when `icon` is absent.
+ * Uses: `Touchable`, `View`, `useStylesFor`, `WebStyleRegistry`
+ */
 export const Icon = (props:IconProps) => {
   const {
-    name,
+    icon,
     style,
+    onPress,
     renderEmptySpace,
+    debugName,
     ...otherProps
   } = {
     ...Icon.defaultProps,
@@ -22,9 +31,9 @@ export const Icon = (props:IconProps) => {
 
   const styles = useStylesFor(Icon.styleRegistryName, style)
 
-  const Component = themeIcons?.[name]
+  const Component = themeIcons?.[icon]
 
-  if (!name) {
+  if (!icon) {
     const iconStyle = styles.icon as React.CSSProperties & { size: number }
 
     return renderEmptySpace ? (
@@ -39,7 +48,26 @@ export const Icon = (props:IconProps) => {
 
   if (!Component) return null
 
-  return <Component {...otherProps} style={styles.icon} />
+  if (TypeGuards.isFunction(onPress)) {
+    return <Touchable
+      debugName={debugName}
+      component={Component}
+      onPress={onPress}
+      {...otherProps} css={styles.icon}
+    />
+  }
+
+  return <Component {...otherProps} css={styles.icon} />
+}
+
+Icon.Accessory = (props:IconProps) => {
+  const AcessoryIcon =  (renderProps: Partial<IconProps>) => {
+    return <Icon 
+      {...renderProps}
+      {...props}
+    />
+  }
+  return AcessoryIcon
 }
 
 Icon.styleRegistryName = 'Icon'

package/src/components/Icon/types.ts

@@ -1,15 +1,24 @@
 import { ComponentCommonProps } from '../../types'
 import { IconComposition } from './styles'
-import { AppIcon, StyledProp } from '@codeleap/styles'
+import { AppIcon, StyleProp } from '@codeleap/styles'
 import { CSSProperties } from 'react'
 
-export type IconProps = 
-  ComponentCommonProps & 
+export interface IconStyleDef {}
+
+/** Props for the `Icon` component. */
+export type IconProps =
+  ComponentCommonProps &
   {
-    name: AppIcon
-    style?: StyledProp<IconComposition>
+    /** Theme-registered icon name; renders nothing (or a sized placeholder) when absent. */
+    icon: AppIcon
+    style?: StyleProp<IconComposition, keyof IconStyleDef>
     size?: string | number
     color?: string
+    /** When `icon` is falsy, renders a same-sized invisible placeholder instead of null. */
     renderEmptySpace?: boolean
     forceStyle?: CSSProperties
+    /** When provided the icon is wrapped in a `Touchable`. */
+    onPress?: () => void
+    disabled?: boolean
+    className?: string
   }

package/src/components/List/context.tsx

@@ -0,0 +1,97 @@
+import React, { createContext, useCallback, useContext, useEffect, useRef, useState } from 'react'
+import { useDebounceCallback } from '@codeleap/hooks'
+import { deepEqual } from '@codeleap/utils'
+import { useStylesFor } from '../../lib/hooks/useStylesFor'
+import { useIsomorphicEffect } from '../../lib/hooks/useIsomorphicEffect'
+import { useElementScroll, useWindowScroll } from './scroll'
+import { ListPaddingProps, ListProviderProps, ListWrapperLayout, UseListScrollHook } from './types'
+import { ListComposition } from './styles'
+
+const LIST_STYLE_REGISTRY_NAME = 'List'
+
+function resolvePadding(props: ListProviderProps, stylePositioner: Record<string, any>) {
+  const get = (key: keyof ListPaddingProps) => (props as any)[key] ?? stylePositioner?.[key]
+
+  const p = get('padding') ?? 0
+  const ph = get('paddingHorizontal') ?? p
+  const pv = get('paddingVertical') ?? p
+
+  return {
+    paddingTop: get('paddingTop') ?? pv,
+    paddingBottom: get('paddingBottom') ?? pv,
+    paddingLeft: get('paddingLeft') ?? ph,
+    paddingRight: get('paddingRight') ?? ph,
+  }
+}
+
+function useListProvider(props: ListProviderProps) {
+  const wrapperRef = useRef<HTMLElement>(null)
+  const [wrapperLayout, setWrapperLayout] = useState<ListWrapperLayout | null>(null)
+
+  const styles = useStylesFor(LIST_STYLE_REGISTRY_NAME, props.style)
+  const stylePositioner = (styles as any)?.positioner ?? {}
+
+  const update = useCallback((target: HTMLElement) => {
+    const rect = target.getBoundingClientRect()
+    const next = { width: rect.width, offsetHeight: target.offsetHeight }
+    setWrapperLayout(current => deepEqual(next, current) ? current : next)
+  }, [])
+
+  const { debounce: updateDebounced } = useDebounceCallback(update, 200)
+
+  useIsomorphicEffect(() => {
+    if (typeof window === 'undefined') return
+    const el = wrapperRef.current
+    if (!el) return
+
+    update(el)
+
+    const observer = new ResizeObserver(([entry]) => {
+      updateDebounced(entry.target as HTMLElement)
+    })
+    observer.observe(el)
+    return () => observer.disconnect()
+  }, [wrapperRef.current, update, updateDebounced])
+
+  const scrollHook: UseListScrollHook =
+    props.scrollHook ?? (props.windowScroll ? useWindowScroll : useElementScroll)
+
+  const ready = !!wrapperLayout
+
+  return {
+    wrapperRef,
+    wrapperLayout,
+    styles: styles as Record<ListComposition, any>,
+    props,
+    scrollHook,
+    ready,
+    padding: resolvePadding(props, stylePositioner),
+  }
+}
+
+export type ListContextValue = ReturnType<typeof useListProvider>
+
+export const ListContext = createContext<ListContextValue | null>(null)
+
+/**
+ * Returns the nearest `List.Provider` context value.
+ * Throws when `required` is `true` (default) and no provider is found; pass `false` to allow optional usage.
+ */
+export const useListContext = (required=true): ListContextValue => {
+  const ctx = useContext(ListContext)
+  if (!ctx && required) throw new Error('useListContext must be used inside List.Provider')
+  return ctx
+}
+
+/**
+ * Provides layout measurements, resolved styles, scroll state, and positioner config to all List sub-components.
+ * Must wrap `List.Wrapper` / `List.Items`; `List` renders this automatically when used as the top-level component.
+ */
+export const ListProvider = (props: ListProviderProps) => {
+  const value = useListProvider(props)
+  return (
+    <ListContext value={value}>
+      {props.children}
+    </ListContext>
+  )
+}