@codeleap/web 6.2.3 → 6.8.0

package/src/components/TextInput/useTextInput.ts

@@ -1,10 +1,26 @@
 import React, { useCallback, useState } from 'react'
 import { TextInputProps } from './types'
 import { TypeGuards } from '@codeleap/types'
-import { useInputBase } from '../InputBase/useInputBase'
+import { useFieldInput } from '../Field'
 import { fields } from '@codeleap/form'
 
-export function useTextInput(props: Partial<TextInputProps>) {
+type Props = Pick<TextInputProps,  'onFocus'
+    | 'onBlur'
+    | 'field'
+    | 'multiline'
+    | 'forceError'
+    | 'value'
+    | 'onValueChange'
+    | 'onChangeText'
+ 
+>
+
+/**
+ * Manages focus state, change handling, and form-field validation wiring for `TextInput`.
+ * Bridges the native `onChange` event with both controlled `onValueChange` and `@codeleap/form` field APIs.
+ * No provider required; designed to be called only inside `TextInput`.
+ */
+export function useTextInput(props:Props) {
   const {
     onFocus,
     onBlur,
@@ -14,7 +30,7 @@ export function useTextInput(props: Partial<TextInputProps>) {
     value,
     onValueChange,
     onChangeText,
-    rows: providedRows,
+ 
   } = props
 
   const [isFocused, setIsFocused] = useState(false)
@@ -30,21 +46,21 @@ export function useTextInput(props: Partial<TextInputProps>) {
     wrapperRef,
     onInputValueChange,
     inputValue,
-  } = useInputBase<string>(
+  } = useFieldInput<string>(
     field,
     fields.text,
     { value, onValueChange: onValueChange ?? onChangeText as any },
     {
-    revealValue() {
-      setSecureTextEntry(false)
-    },
-    hideValue() {
-      setSecureTextEntry(true)
-    },
-    toggleValueVisibility() {
-      toggleSecureTextEntry()
-    },
-  }, [setSecureTextEntry])
+      revealValue() {
+        setSecureTextEntry(false)
+      },
+      hideValue() {
+        setSecureTextEntry(true)
+      },
+      toggleValueVisibility() {
+        toggleSecureTextEntry()
+      },
+    }, [setSecureTextEntry])
 
   const handleBlur = useCallback((e: React.FocusEvent<HTMLInputElement, Element>) => {
     validation?.onInputBlurred?.()
@@ -63,11 +79,11 @@ export function useTextInput(props: Partial<TextInputProps>) {
     onInputValueChange(inputValue)
   }, [onInputValueChange, onChangeText])
 
-  const rows = providedRows ?? (isMultiline ? 2 : undefined)
+  const rows =   (isMultiline ? 2 : undefined)
 
   const hasMultipleLines = isMultiline && (String(inputValue)?.includes('\n') || !!rows)
 
-  const hasError = validation?.showError || forceError
+  const hasError = validation?.showError || !!forceError
 
   const errorMessage = validation?.message || forceError
 
@@ -89,4 +105,4 @@ export function useTextInput(props: Partial<TextInputProps>) {
     inputValue: inputValue || '',
     onInputValueChange,
   }
-}
+}

package/src/components/Tooltip/index.tsx

@@ -19,6 +19,11 @@ import { useStylesFor } from '../../lib/hooks/useStylesFor'
 export * from './styles'
 export * from './types'
 
+/**
+ * Contextual bubble that floats near a trigger element, supporting hover and/or press to open.
+ * Visibility can be fully controlled via `visible` / `toggle` or left to internal state.
+ * Uses: `View`, `useStylesFor`
+ */
 export const Tooltip = (props: TooltipProps) => {
   const allProps = {
     ...Tooltip.defaultProps,
@@ -122,7 +127,6 @@ export const Tooltip = (props: TooltipProps) => {
           asChild
           ref={triggerRef}
           {...triggerProps}
-          //@ts-expect-error
           css={styles.triggerWrapper}
         >
           <TriggerWrapper
@@ -134,7 +138,6 @@ export const Tooltip = (props: TooltipProps) => {
           </TriggerWrapper>
         </TooltipTrigger>
         <TooltipPortal {...portalProps}>
-          {/* @ts-expect-error icss type */}
           <TooltipContent ref={contentRef} css={[tooltipDirectionStyle, styles.content]} sideOffset={2} side={side} {...contentProps}>
             {
               TypeGuards.isFunction(Content)
@@ -148,7 +151,6 @@ export const Tooltip = (props: TooltipProps) => {
             }
             <TooltipArrow
               {...arrowProps}
-              //@ts-expect-error icss type
               css={styles.arrow}
             />
           </TooltipContent>

package/src/components/Tooltip/types.ts

@@ -10,7 +10,9 @@ import {
 import { AnyFunction, StylesOf } from '@codeleap/types'
 import { TooltipComposition } from './styles'
 import { ViewProps } from '../View'
-import { StyledProp } from '@codeleap/styles'
+import { StyleProp } from '@codeleap/styles'
+
+export interface TooltipStyleDef {}
 
 type TooltipComponentProps = {
   contentProps?: TooltipContentProps
@@ -26,15 +28,22 @@ export type TooltipProps =
   {
     toggle?: AnyFunction
     visible?: boolean
+    /** Tooltip bubble content. Accepts a node or a render function that receives all resolved props and `variantsStyles`. */
     content: React.ReactNode | ((props: TooltipProps & { variantsStyles: StylesOf<TooltipComposition> }) => React.ReactElement)
+    /** Element type wrapping the trigger children. Defaults to `View`. */
     triggerWrapper?: React.ElementType
     triggerWrapperProps?: Partial<ViewProps>
-    style?: StyledProp<TooltipComposition>
+    style?: StyleProp<TooltipComposition, keyof TooltipStyleDef>
+    /** Side of the trigger the bubble appears on. Defaults to `"bottom"`. */
     side?: 'left' | 'right' | 'bottom' | 'top'
+    /** Open the tooltip on pointer/keyboard press. Defaults to `true`. */
     openOnPress?: boolean
+    /** Open the tooltip on mouse enter. Defaults to `true`. */
     openOnHover?: boolean
     disabled?: boolean
+    /** Delay in ms before the tooltip opens on hover. Defaults to `0`. */
     delayDuration?: number
+    /** Close when clicking outside the content element. Only applies when `openOnHover` is `false`. Defaults to `false`. */
     closeOnClickOutside?: boolean
     onOpen?: AnyFunction
     onClose?: AnyFunction

package/src/components/Touchable/index.tsx

@@ -1,18 +1,23 @@
 import { onMount } from '@codeleap/hooks'
 import { TypeGuards } from '@codeleap/types'
-import React, { ComponentType, ElementType, forwardRef, HTMLAttributes } from 'react'
+import React, { ComponentType, ElementType, HTMLAttributes } from 'react'
 import { stopPropagation } from '../../lib'
 import { getTestId } from '../../lib/utils/test'
 import { TouchableProps } from './types'
 import { useStylesFor } from '../../lib/hooks/useStylesFor'
 import { WebStyleRegistry } from '../../lib/WebStyleRegistry'
-import { AnyRecord, IJSX, StyledComponentProps, StyledComponentWithProps } from '@codeleap/styles'
-import { logger } from '@codeleap/logger'
+import { AnyRecord, IJSX, StyledComponentProps } from '@codeleap/styles'
+import { useTouchableInteraction } from '../../lib/hooks/useTouchableEvents'
 
 export * from './styles'
 export * from './types'
 
-export const Touchable = (touchableProps: TouchableProps) => {
+/**
+ * Click wrapper that normalises keyboard Enter presses as clicks, debounces
+ * repeated presses, propagates analytics events, and applies disabled state.
+ * Uses: `useStylesFor`, `WebStyleRegistry`
+ */
+export function Touchable<T extends ElementType>(touchableProps: TouchableProps<T>){
   const allProps = {
     ...Touchable.defaultProps,
     ...touchableProps,
@@ -22,7 +27,7 @@ export const Touchable = (touchableProps: TouchableProps) => {
     propagate,
     debounce,
     leadingDebounce,
-    setPressed,
+ 
     component,
     disabled,
     onPress,
@@ -37,6 +42,8 @@ export const Touchable = (touchableProps: TouchableProps) => {
     ...props
   } = allProps
 
+   
+
   const styles = useStylesFor(Touchable.styleRegistryName, style)
 
   const pressed = React.useRef(!!leadingDebounce)
@@ -63,18 +70,6 @@ export const Touchable = (touchableProps: TouchableProps) => {
     const _onPress = () => {
       if (event && (event?.type !== 'click' && event?.keyCode !== 13 && event?.key !== 'Enter')) return null
 
-      logger.log(
-        `<${debugComponent || 'Touchable'}/> pressed:`,
-        { debugName, debugComponent },
-      )
-
-      // if (analyticsEnabled) {
-      //   const name = analyticsName || debugName
-      //   if (!!name?.trim?.()) {
-      //     logger.analytics?.interaction(name, analyticsData)
-      //   }
-      // }
-
       if (TypeGuards.isFunction(onClick)) onClick?.(event)
       onPress?.()
     }
@@ -83,11 +78,11 @@ export const Touchable = (touchableProps: TouchableProps) => {
       if (pressed.current) {
         return
       }
-      setPressed?.(true)
+
       pressed.current = true
       _onPress()
       setTimeout(() => {
-        setPressed?.(false)
+
         pressed.current = false
       }, debounce)
     } else {
@@ -100,10 +95,16 @@ export const Touchable = (touchableProps: TouchableProps) => {
   return (
     <Component
       {...props}
+      disabled={disabled}
       onClick={handleClick}
       onKeyDown={handleClick}
+      aria-disabled={disabled || undefined}
       ref={ref}
-      css={[styles.wrapper, disabled && styles['wrapper:disabled']]}
+      css={[
+        styles.wrapper,
+        
+        disabled && styles?.['wrapper:disabled'],
+      ]}
       data-testid={testId}
     />
   )
@@ -112,15 +113,12 @@ export const Touchable = (touchableProps: TouchableProps) => {
 Touchable.styleRegistryName = 'Touchable'
 Touchable.elements = ['wrapper']
 Touchable.rootElement = 'wrapper'
-
-Touchable.withVariantTypes = <S extends AnyRecord>(styles: S) => {
-  return Touchable as <T extends ElementType = 'button'>(props: StyledComponentProps<TouchableProps<T>, typeof styles>) => IJSX
-}
+ 
 
 Touchable.defaultProps = {
   propagate: true,
   debounce: null,
-  component: 'div',
+  component: 'button',
   analyticsEnabled: false,
   analyticsName: null,
   analyticsData: {},

package/src/components/Touchable/types.ts

@@ -1,23 +1,35 @@
 import { AnyFunction } from '@codeleap/types'
 import { ComponentPropsWithRef, ElementType, ReactNode } from 'react'
 import { TouchableComposition } from './styles'
-import { AnyRecord, StyledProp } from '@codeleap/styles'
+import { AnyRecord, ICSS, StyleProp } from '@codeleap/styles'
+import type { TouchableInteractionHandler } from '../../lib/hooks/useTouchableEvents'
 
-export type TouchableProps<T extends ElementType = 'button'> =
-  Omit<ComponentPropsWithRef<T>, 'style'> &
-  {
-    component?: ElementType<AnyRecord>
-    disabled?: boolean
-    propagate?: boolean
-    onPress?: AnyFunction
-    debugName: string
-    debugComponent?: string
-    style?: StyledProp<TouchableComposition>
-    debounce?: number
-    leadingDebounce?: boolean
-    setPressed?: (pressed: boolean) => void
-    analyticsEnabled?: boolean
-    analyticsName?: string
-    analyticsData?: Record<string, any>
-    children?: ReactNode
-  }
+export interface TouchableStyleDef {
+  __internal: Record<TouchableComposition, ICSS>
+}
+
+/**
+ * Props for the `Touchable` component.
+ *
+ * `debugName` is required to support analytics and test-id attribution.
+ */
+export type TouchableProps<T extends ElementType = 'button'> = Omit<ComponentPropsWithRef<T>, 'style'> & {
+  component?: ElementType<AnyRecord>
+  disabled?: boolean
+  /** When false, `stopPropagation` is called on every click event. Defaults to `true`. */
+  propagate?: boolean
+  onPress?: AnyFunction
+  debugName: string
+  debugComponent?: string
+  style?: StyleProp<TouchableComposition, keyof TouchableStyleDef>
+  /** Milliseconds to suppress repeated presses after the first; ignored when falsy. */
+  debounce?: number
+  /** When true, the debounce lock is active from mount and released after `debounce` ms. */
+  leadingDebounce?: boolean
+
+  analyticsEnabled?: boolean
+  analyticsName?: string
+  analyticsData?: Record<string, any>
+  children?: ReactNode
+
+}

package/src/components/View/index.tsx

@@ -1,5 +1,5 @@
 import { TypeGuards } from '@codeleap/types'
-import React, { ElementType } from 'react'
+import { ElementType } from 'react'
 import { motion } from 'motion/react'
 import { ViewProps } from './types'
 import { getTestId } from '../../lib/utils/test'
@@ -10,7 +10,12 @@ import { AnyRecord, IJSX, StyledComponentProps, StyledComponentWithProps } from
 export * from './styles'
 export * from './types'
 
-export const View = (viewProps: ViewProps) => {
+/**
+ * Generic layout wrapper that renders any DOM element with responsive styling,
+ * hover callbacks, and optional Framer Motion animation.
+ * Uses: `useStylesFor`, `WebStyleRegistry`
+ */
+export function View<T extends ElementType>(viewProps: ViewProps<T>) {
   const {
     component,
     children,
@@ -62,10 +67,7 @@ export const View = (viewProps: ViewProps) => {
 View.styleRegistryName = 'View'
 View.elements = ['wrapper']
 View.rootElement = 'wrapper'
-
-View.withVariantTypes = <S extends AnyRecord>(styles: S) => {
-  return View as <T extends ElementType = 'div'>(props: StyledComponentProps<ViewProps<T>, typeof styles>) => IJSX
-}
+ 
 
 View.defaultProps = {
   component: 'div',

package/src/components/View/types.ts

@@ -1,8 +1,17 @@
 import { TargetAndTransition, MotionProps } from 'motion/react'
-import { AnyRecord, StyledProp } from '@codeleap/styles'
+import { AnyRecord, StyleProp } from '@codeleap/styles'
 import { ViewComposition } from './styles'
 import { ComponentPropsWithRef, ElementType } from 'react'
 
+export interface ViewStyleDef {}
+
+/**
+ * Props for the `View` component.
+ *
+ * Merges native element props with Framer Motion target values; use `animated`
+ * to opt in to Motion rendering and `animatedProps` to pass motion-specific
+ * configuration.
+ */
 export type ViewProps<T extends ElementType = 'div'> =
   Omit<ComponentPropsWithRef<T>, 'style' | 'children'> &
   Omit<TargetAndTransition, 'style' | 'children'> &
@@ -13,9 +22,12 @@ export type ViewProps<T extends ElementType = 'div'> =
     not?: any
     up?: any
     down?: any
+    /** Called with `true` on mouseenter, `false` on mouseleave. */
     onHover?: (isMouseOverElement: boolean) => void
+    /** When true, renders a `motion.*` element instead of a plain DOM element. */
     animated?: boolean
+    /** Framer Motion props applied on top of the native element props; only used when `animated` is true. */
     animatedProps?: Partial<MotionProps>
-    style?: StyledProp<ViewComposition>
+    style?: StyleProp<ViewComposition, keyof ViewStyleDef>
     children?: React.ReactNode
   }

package/src/components/components.ts

@@ -7,7 +7,6 @@ export * from './List'
 export * from './ActivityIndicator'
 export * from './Button'
 export * from './Modal'
-export * from './ActionIcon'
 export * from './Checkbox'
 export * from './Collapse'
 export * from './Drawer'
@@ -20,16 +19,16 @@ export * from './FileInput'
 export * from './Slider'
 export * from './List'
 export * from './LoadingOverlay'
-export * from './InputBase'
 export * from './Switch'
 export * from './NumberIncrement'
 export * from './SearchInput'
 export * from './Tooltip'
-export * from './SegmentedControl'
+export * from './Field'
 export * from './Carousel'
 export * from './EmptyPlaceholder'
 export * from './Badge'
 export * from './CropPicker'
+export * from './Calendar'
 export * from './DatePicker'
 export * from './Dropzone'
 export * from './Progress'
@@ -40,4 +39,4 @@ export * from './PaginationButtons'
 export * from './SectionFilters'
 export * from './PaginationIndicator'
 export * from './Carousel'
-export * from './VirtualList'
+

package/src/css.d.ts

@@ -0,0 +1,10 @@
+declare module '*.css' {}
+
+import { CSSObject, Interpolation } from '@emotion/react'
+
+declare module '@codeleap/styles' {
+
+  export interface ICSS extends CSSObject {
+    
+  }
+}

package/src/lib/ThemeVariables.tsx

@@ -0,0 +1,38 @@
+import React from 'react'
+import { DOM_COLOR_SCHEME_KEY } from '@codeleap/styles'
+
+type ThemeVariablesTheme = {
+  getCssVariables: (schemeName?: string) => Record<string, string>
+  alternateColors?: Record<string, any>
+}
+
+const toDeclarations = (vars: Record<string, string>) =>
+  Object.entries(vars).map(([n, v]) => `  ${n}: ${v};`).join('\n')
+
+export const ThemeVariables = ({ theme }: { theme: ThemeVariablesTheme }) => {
+  const defaultVars = theme.getCssVariables()
+  const alternateColors = theme.alternateColors ?? {}
+
+  const blocks: string[] = [
+    `:root {\n${toDeclarations(defaultVars)}\n}`,
+    `[data-color-scheme="light"] {\n${toDeclarations(defaultVars)}\n}`,
+  ]
+
+  for (const scheme of Object.keys(alternateColors)) {
+    const vars = theme.getCssVariables(scheme)
+    if (scheme === 'dark') {
+      blocks.push(
+        `@media (prefers-color-scheme: dark) {\n  :root:not([data-color-scheme="light"]) {\n${toDeclarations(vars)}\n  }\n}`,
+      )
+    }
+    blocks.push(`[data-color-scheme="${scheme}"] {\n${toDeclarations(vars)}\n}`)
+  }
+
+  return <style dangerouslySetInnerHTML={{ __html: blocks.join('\n\n') }} />
+}
+
+const FOUC_SCRIPT = `(function(){try{var s=localStorage.getItem('${DOM_COLOR_SCHEME_KEY}');if(s&&s!=='default')document.documentElement.dataset.colorScheme=s;}catch(e){}})()`
+
+export const ColorSchemeFoucScript = () => (
+  <script dangerouslySetInnerHTML={{ __html: FOUC_SCRIPT }} />
+)

package/src/lib/WebStyleRegistry.ts

@@ -19,7 +19,24 @@ let instance: WebStyleRegistry
 
 const components: CodeleapStyleRegistry['components'][string][] = []
 
+/**
+ * Singleton style registry for the web platform.
+ *
+ * Extends `CodeleapStyleRegistry` with localStorage-backed style persistence
+ * and a variant-element map that tracks which HTML element tag should be used
+ * for each component variant.
+ *
+ * Only one instance exists per JS runtime. The first `new WebStyleRegistry()`
+ * call creates the instance; subsequent calls return the same object. Components
+ * register themselves via the static `WebStyleRegistry.registerComponent()` —
+ * call this at module level so registrations survive before the registry is
+ * instantiated (they are replayed on construction).
+ *
+ * Access the live singleton via `WebStyleRegistry.current`.
+ */
 export class WebStyleRegistry extends CodeleapStyleRegistry {
+  variantElements: Record<string, Record<string, string>> = {}
+
   constructor() {
     super(persistor)
 
@@ -34,6 +51,16 @@ export class WebStyleRegistry extends CodeleapStyleRegistry {
     return instance
   }
 
+  /** Registers the HTML element tag to render for each variant of a component (e.g. `{ h1: 'h1', p: 'p' }`). */
+  registerVariantElements(componentName: string, elements: Record<string, string>) {
+    this.variantElements[componentName] = elements
+  }
+
+  /** Returns the element tag registered for the given component variant, or `undefined` if none was registered. */
+  variantElementFor(componentName: string, variantName: string): string | undefined {
+    return this.variantElements[componentName]?.[variantName]
+  }
+
   createStyle(css: ICSS): ICSS {
     return css
   }

package/src/lib/hooks/index.ts

@@ -15,6 +15,9 @@ export * from './useWindowFocus'
 export * from './useWindowSize'
 export * from './useKeydown'
 export * from './useRefresh'
-export * from './useCropPicker'
 export * from './useFileInput'
 export * from './useStylesFor'
+export * from './useAsyncSelect'
+
+export * from './useListFocus'
+export * from './usePopoverDismiss'

package/src/lib/hooks/useAnimatedStyle.ts

@@ -11,6 +11,13 @@ type UseAnimatedStyleReturn = {
   transition: Transition | undefined
 }
 
+/**
+ * Drives a Framer Motion `animate` prop from a reactive updater function.
+ *
+ * The transition from the initial call is captured once and held stable; only
+ * the animated target re-evaluates on dependency changes. Returns `initial: false`
+ * so Motion skips the mount animation and begins from the current state.
+ */
 export const useAnimatedStyle = (updater: () => UpdaterReturn, deps: Array<any>): UseAnimatedStyleReturn => {
   const initialStyle = updater()
 

package/src/lib/hooks/useAnimatedVariantStyles.ts

@@ -10,6 +10,12 @@ type UseAnimatedVariantStylesConfig<T extends Record<string | number | symbol, a
   dependencies?: any[]
 }
 
+/**
+ * Derives a Framer Motion animation target from a component's variant styles,
+ * animating only the properties listed in `animatedProperties` while keeping the
+ * rest static (via `useStaticAnimationStyles`). Re-evaluates the `updater` whenever
+ * `dependencies` change.
+ */
 export function useAnimatedVariantStyles<T extends Record<string | number | symbol, any>, K extends keyof T>(config: UseAnimatedVariantStylesConfig<T, K>) {
   const { animatedProperties, updater, variantStyles, dependencies = [] } = config