@northlight/ui 2.41.0 → 2.41.1

package/lib/components/select/sortable-select.tsx

@@ -0,0 +1,428 @@
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import {
+  ActionMeta,
+  MultiValue,
+  OnChangeValue,
+} from 'chakra-react-select'
+import { DndContext, DragEndEvent, DragOverEvent, closestCenter } from '@dnd-kit/core'
+import { restrictToParentElement } from '@dnd-kit/modifiers'
+import {
+  SortableContext,
+  arrayMove,
+  horizontalListSortingStrategy,
+} from '@dnd-kit/sortable'
+import { Select } from './select'
+import { Option, SelectProps } from './types'
+import { SortableMultiValue, SortableMultiValueRemove } from './sortable-select-values'
+
+export interface SortableSelectProps<T extends Option>
+  extends Omit<SelectProps<T, true>, 'isMulti'> {
+  /** The currently selected options */
+  value?: T[] | string[]
+  /** Callback when the order or selection changes */
+  onChange?: (selected: MultiValue<T>, event: ActionMeta<T>) => void
+}
+
+const isOptionArray = <T extends Option>(value: unknown): value is T[] =>
+  Array.isArray(value) &&
+  value.length > 0 &&
+  typeof value[0] === 'object' &&
+  value[0] !== null &&
+  'value' in value[0]
+
+const isStringArray = (value: unknown): value is string[] =>
+  Array.isArray(value) &&
+  value.length > 0 &&
+  typeof value[0] === 'string'
+
+/**
+ * SortableSelect component that provides drag-and-drop reordering for multi-select options.
+ * It is built on top of the Select component with @dnd-kit integration.
+ *
+ * Drag-and-drop reordering.
+ * Supports both string arrays and option objects as values.
+ * Preserves order from value prop (not options order).
+ * Works seamlessly with react-hook-form.
+ * All Select component props and styling supported.
+ *
+ * @see Select
+ * @see MultiSort
+ * @see Draggable
+ * @see {@link https://northlight.dev/reference/sortable-select}
+ *
+ * @example (Example)
+ * ## Basic Usage with String Array
+ * (?
+ * +
+ * const MyComponent = () => {
+ *   const [selected, setSelected] = useState(['USD', 'EUR', 'GBP'])
+ *
+ *   const currencyOptions = [
+ *     { label: 'US Dollar', value: 'USD' },
+ *     { label: 'Euro', value: 'EUR' },
+ *     { label: 'British Pound', value: 'GBP' },
+ *     { label: 'Japanese Yen', value: 'JPY' },
+ *   ]
+ *
+ *   return (
+ *     <SortableSelect
+ *       options={currencyOptions}
+ *       value={selected}
+ *       onChange={(value) => setSelected((value || []).map(v => v.value))}
+ *       placeholder="Select currencies"
+ *     />
+ *   )
+ * }
+ *
+ * render(<MyComponent />)
+ * ?)
+ *
+ * @example (Example)
+ * ## Usage with Option Objects
+ * (?
+ * +
+ * const MyComponent = () => {
+ *   const [selected, setSelected] = useState([
+ *     { label: 'Apple', value: 'apple' },
+ *     { label: 'Banana', value: 'banana' }
+ *   ])
+ *
+ *   const fruitOptions = [
+ *     { label: 'Apple', value: 'apple' },
+ *     { label: 'Banana', value: 'banana' },
+ *     { label: 'Cherry', value: 'cherry' },
+ *     { label: 'Date', value: 'date' },
+ *   ]
+ *
+ *   return (
+ *     <SortableSelect
+ *       options={fruitOptions}
+ *       value={selected}
+ *       onChange={(value) => setSelected(value || [])}
+ *     />
+ *   )
+ * }
+ *
+ * render(<MyComponent />)
+ * ?)
+ *
+ * @example (Example)
+ * ## React Hook Form Integration
+ * _Use with react-hook-form for controlled form state with reordering_
+ * (?
+ * +
+ * const tagOptions = [
+ *   { label: 'React', value: 'react' },
+ *   { label: 'TypeScript', value: 'typescript' },
+ *   { label: 'JavaScript', value: 'javascript' },
+ *   { label: 'Node.js', value: 'nodejs' },
+ * ]
+ *
+ * const MyFormFields = () => {
+ *   const { setValue } = useFormContext()
+ *   const selectedTags = useWatch({ name: 'tags' })
+ *
+ *   const handleChange = (value, actionMeta) => {
+ *     const tags = (value || []).map(v => v.value)
+ *     setValue('tags', tags, {
+ *       shouldDirty: true,
+ *       shouldValidate: true,
+ *     })
+ *   }
+ *
+ *   return (
+ *     <SortableSelect
+ *       name="tags"
+ *       options={tagOptions}
+ *       value={selectedTags}
+ *       onChange={handleChange}
+ *     />
+ *   )
+ * }
+ *
+ * const MyForm = () => (
+ *   <Form
+ *     initialValues={{ tags: ['react'] }}
+ *     onSubmit={(values) => console.log(values)}
+ *   >
+ *     {() => <MyFormFields />}
+ *   </Form>
+ * )
+ *
+ * render(<MyForm />)
+ * ?)
+ *
+ * @example (Example)
+ * ## Handling Different Actions
+ * (?
+ * +
+ * const MyComponent = () => {
+ *   const [selected, setSelected] = useState(['red'])
+ *
+ *   const options = [
+ *     { label: 'Red', value: 'red' },
+ *     { label: 'Green', value: 'green' },
+ *     { label: 'Blue', value: 'blue' },
+ *   ]
+ *
+ *   const handleChange = (value, actionMeta) => {
+ *     const { action, removedValue, option } = actionMeta
+ *
+ *     switch (action) {
+ *       case 'select-option':
+ *         console.log('Added:', option)
+ *         break
+ *       case 'remove-value':
+ *         console.log('Removed:', removedValue)
+ *         break
+ *       case 'clear':
+ *         console.log('Reordered:', value?.map(v => v.value))
+ *         break
+ *     }
+ *
+ *     setSelected((value || []).map(v => v.value))
+ *   }
+ *
+ *   return (
+ *     <SortableSelect
+ *       options={options}
+ *       value={selected}
+ *       onChange={handleChange}
+ *     />
+ *   )
+ * }
+ *
+ * render(<MyComponent />)
+ * ?)
+ *
+ * @example (Example)
+ * ## Customizing Selected Options
+ * _Customize the appearance of selected option pills while keeping drag functionality_
+ * (?
+ * +
+ * const MyComponent = () => {
+ *   const [selected, setSelected] = useState(['js', 'ts'])
+ *
+ *   const options = [
+ *     { label: 'JavaScript', value: 'js' },
+ *     { label: 'TypeScript', value: 'ts' },
+ *     { label: 'Python', value: 'py' },
+ *     { label: 'Rust', value: 'rust' },
+ *   ]
+ *
+ *   return (
+ *     <SortableSelect
+ *       options={options}
+ *       value={selected}
+ *       onChange={(value) => setSelected((value || []).map(v => v.value))}
+ *       components={{
+ *         MultiValueLabel: (props) => (
+ *           <HStack spacing={1} px={2}>
+ *             <Icon as={Code} />
+ *             <Text>{props.children}</Text>
+ *           </HStack>
+ *         )
+ *       }}
+ *       chakraStyles={{
+ *         multiValue: (styles) => ({
+ *           ...styles,
+ *           backgroundColor: 'purple.100',
+ *           borderRadius: 'full',
+ *         }),
+ *       }}
+ *     />
+ *   )
+ * }
+ *
+ * render(<MyComponent />)
+ * ?)
+ *
+ * @example (Example)
+ * ## With Custom Tag Component
+ * _Use customTag prop for simpler customization_
+ * (?
+ * +
+ * const customTag = ({ label }) => (
+ *   <HStack spacing={1} px={2} py={1} bg="blue.50" borderRadius="md">
+ *     <Badge colorScheme="blue" variant="solid" fontSize="xs">NEW</Badge>
+ *     <Text fontSize="sm" fontWeight="medium">{label}</Text>
+ *   </HStack>
+ * )
+ *
+ * const MyComponent = () => {
+ *   const [selected, setSelected] = useState(['react'])
+ *
+ *   return (
+ *     <SortableSelect
+ *       options={[
+ *         { label: 'React', value: 'react' },
+ *         { label: 'Vue', value: 'vue' },
+ *         { label: 'Angular', value: 'angular' },
+ *       ]}
+ *       value={selected}
+ *       onChange={(value) => setSelected((value || []).map(v => v.value))}
+ *       customTag={customTag}
+ *     />
+ *   )
+ * }
+ *
+ * render(<MyComponent />)
+ * ?)
+ *
+ * @example (Example)
+ * ## Disabled State
+ * (?
+ * <SortableSelect
+ *   options={[
+ *     { label: 'Admin', value: 'admin' },
+ *     { label: 'Editor', value: 'editor' },
+ *     { label: 'Viewer', value: 'viewer' },
+ *   ]}
+ *   value={['viewer']}
+ *   onChange={(value) => console.log('Changed:', value)}
+ *   isDisabled={true}
+ *   placeholder="Select items (disabled)"
+ * />
+ * ?)
+ *
+ * @example (Example)
+ * ## With Styling
+ * (?
+ * <SortableSelect
+ *   options={[
+ *     { label: 'Apple', value: 'apple' },
+ *     { label: 'Banana', value: 'banana' },
+ *     { label: 'Orange', value: 'orange' },
+ *     { label: 'Pear', value: 'pear' },
+ *   ]}
+ *   value={['apple', 'banana']}
+ *   onChange={(value) => console.log('Changed:', value)}
+ *   colorScheme="blue"
+ *   chakraStyles={{
+ *     multiValue: (styles) => ({
+ *       ...styles,
+ *       backgroundColor: 'red.100',
+ *     }),
+ *   }}
+ * />
+ * ?)
+ */
+export const SortableSelect = <T extends Option>({
+  value,
+  onChange,
+  components: customComponents,
+  options,
+  ...rest
+}: SortableSelectProps<T>) => {
+  const matchedValue = useMemo(() => {
+    if (!value || !Array.isArray(value) || value.length === 0) return []
+
+    const optionsArray = Array.isArray(options) ? options : []
+
+    if (isOptionArray<T>(value)) {
+      return value.filter((item) => item != null)
+    }
+
+    if (isStringArray(value)) {
+      return value.reduce<T[]>((acc, val) => {
+        const found = optionsArray.find((opt) => opt.value === val)
+        if (found !== undefined) {
+          acc.push(found)
+        }
+        return acc
+      }, [])
+    }
+
+    return []
+  }, [ value, options ])
+
+  const [ activeItems, setActiveItems ] = useState<T[]>(matchedValue)
+  const activeItemsRef = useRef<T[]>(activeItems)
+
+  useEffect(() => {
+    setActiveItems(matchedValue)
+    activeItemsRef.current = matchedValue
+  }, [ matchedValue ])
+
+  useEffect(() => {
+    activeItemsRef.current = activeItems
+  }, [ activeItems ])
+
+  const handleChange = (selectedOptions: OnChangeValue<T, true>, actionMeta: ActionMeta<T>) => {
+    if (onChange) {
+      onChange(selectedOptions, actionMeta)
+    }
+  }
+
+  const handleDragOver = useCallback(
+    (event: DragOverEvent) => {
+      const { active, over } = event
+
+      if (!active || !over || active.id === over.id) return
+
+      setActiveItems((items) => {
+        const oldIndex = items.findIndex((item) => item.value === active.id)
+        const newIndex = items.findIndex((item) => item.value === over.id)
+
+        if (oldIndex !== -1 && newIndex !== -1) {
+          return arrayMove(items, oldIndex, newIndex)
+        }
+        return items
+      })
+    },
+    []
+  )
+
+  const handleDragEnd = useCallback(
+    (_event: DragEndEvent) => {
+      if (!onChange) return
+
+      const finalOrder = activeItemsRef.current
+      if (finalOrder.length === 0) return
+
+      const orderChanged = !matchedValue.every((item, index) =>
+        item.value === finalOrder[index]?.value
+      )
+
+      if (orderChanged) {
+        onChange(finalOrder as MultiValue<T>, {
+          action: 'clear',
+          name: rest.name,
+        } as ActionMeta<T>)
+      }
+    },
+    [ matchedValue, onChange, rest.name ]
+  )
+
+  const mergedComponents = {
+    ...customComponents,
+    MultiValue: SortableMultiValue,
+    MultiValueRemove: SortableMultiValueRemove,
+  }
+
+  const sortableItems = activeItems.map((item) => item.value)
+
+  return (
+    <DndContext
+      modifiers={ [ restrictToParentElement ] }
+      onDragOver={ handleDragOver }
+      onDragEnd={ handleDragEnd }
+      collisionDetection={ closestCenter }
+    >
+      <SortableContext
+        items={ sortableItems }
+        strategy={ horizontalListSortingStrategy }
+      >
+        <Select
+          isMulti={ true }
+          options={ options }
+          value={ activeItems }
+          onChange={ handleChange }
+          components={ mergedComponents }
+          closeMenuOnSelect={ false }
+          { ...rest }
+        />
+      </SortableContext>
+    </DndContext>
+  )
+}

package/lib/components/select/types.ts

@@ -0,0 +1,67 @@
+import {
+  ActionMeta,
+  Props as ChakraReactSelectProps,
+  GroupBase,
+  MenuListProps,
+  MultiValue,
+  SelectInstance,
+  SingleValue,
+} from 'chakra-react-select'
+import { Icon, StackDirection } from '@chakra-ui/react'
+import { ComponentProps, ComponentType, Ref } from 'react'
+import { RegisterOptions } from 'react-hook-form'
+import { InputFieldProps } from '../../types'
+
+export type { SingleValue, MultiValue } from 'chakra-react-select'
+
+type Size = 'sm' | 'md' | 'lg'
+export interface Option<T extends string = string> {
+  label: string
+  value: T
+  isCreation?: boolean
+  icon?: ComponentProps<typeof Icon>
+}
+
+export interface SelectProps<T, K extends boolean>
+  extends Omit<
+  ChakraReactSelectProps<T, K, GroupBase<T>>,
+  'onChange' | 'value' | 'isMulti'
+  > {
+  /** Whatever is currently selected by the select will be controlled by value prop, if value is
+   *  of type string then it will automatically pair it up with matching object from options list */
+  value?: K extends true ? T[] | string[] : T | string | null
+  /** Take a look at the second argument, the event,
+   *  for info as to which specific element was added */
+  onChange?: (option: K extends true ? MultiValue<T> : SingleValue<T>, event: ActionMeta<T>) => void
+  onAdd?: (val: unknown) => void
+  onRemove?: (val: unknown) => void
+  /** Used for accessibility */
+  name?: string
+  size?: Size
+  'data-testid'?: string
+  loadingList?:
+  | ComponentType<MenuListProps<T, K, GroupBase<T>>>
+  | undefined
+  /** Custom icon that will be put to the faremost right of the component */
+  icon?: ComponentType<any>
+  /** Custom components that will be put to the faremost left of the select input box */
+  leftComponent?: React.ReactNode
+  customOption?: ((option: T) => JSX.Element) | null
+  isMulti?: K
+  ref?: Ref<SelectInstance<T, K, GroupBase<T>>>
+  /** Should return a unique key that is tracked so when the key changes
+      the sub-components for react-select will be recomputed/rerendered
+  */
+  generateComponentsUpdateKey?: () => unknown
+}
+
+export type SelectFieldProps<T, K extends boolean = false> = SelectProps<T, K> &
+Omit<InputFieldProps, 'isMulti'> & {
+  direction?: StackDirection
+  name: string
+  label: string
+  validate?: RegisterOptions
+  isRequired?: boolean
+  onChange?: (option: K extends true ? MultiValue<T> | undefined : SingleValue<T> | undefined,
+    event: ActionMeta<T>) => void
+}

package/lib/components/show/index.ts

@@ -0,0 +1,4 @@
+export {
+  Show,
+  Hide,
+} from '@chakra-ui/react'

package/lib/components/simple-grid/index.ts

@@ -0,0 +1,3 @@
+export {
+  SimpleGrid,
+} from '@chakra-ui/react'

package/lib/components/skeleton/index.ts

@@ -0,0 +1,5 @@
+export {
+  Skeleton,
+  SkeletonCircle,
+  SkeletonText,
+} from '@chakra-ui/react'

package/lib/components/slider/index.ts

@@ -0,0 +1,7 @@
+export {
+  Slider,
+  SliderTrack,
+  SliderFilledTrack,
+  SliderThumb,
+  SliderMark,
+} from '@chakra-ui/react'

package/lib/components/spinner/index.ts

@@ -0,0 +1,2 @@
+export * from './spinner'
+export * from './types'

package/lib/components/spinner/spinner.tsx

@@ -0,0 +1,15 @@
+import React from 'react'
+import { Spinner as ChakraSpinner } from '@chakra-ui/react'
+import { SpinnerProps } from './types'
+
+/**
+ * Loading indicator
+ * @see {@link https://northlight.dev/reference/spinner }
+ * @example
+ * (? <Spinner /> ?)
+ */
+export const Spinner = (({
+  ...rest
+}: SpinnerProps) => (
+  <ChakraSpinner { ...rest } />
+))

package/lib/components/spinner/types.ts

@@ -0,0 +1,3 @@
+import { SpinnerProps as ChakraSpinnerProps } from '@chakra-ui/react'
+
+export type SpinnerProps = ChakraSpinnerProps

package/lib/components/split-pane/index.ts

@@ -0,0 +1,4 @@
+export * from './split-pane'
+export * from './pane-item'
+export * from './pane-divider'
+export * from './types'

package/lib/components/split-pane/pane-divider.tsx

@@ -0,0 +1,25 @@
+import React from 'react'
+import { Box, BoxProps, forwardRef, useStyleConfig } from '@chakra-ui/react'
+
+/**
+ * Simple vertical line for split screen
+ * @see SplitPane
+ * @see PaneItem
+ * @see {@link https://northlight.dev/reference/pane-divider}
+ * @example
+ * (?
+ * <Box h="xs">
+ * <PaneDivider />
+ * </Box>
+ * ?)
+ * */
+export const PaneDivider = forwardRef((props: BoxProps, ref: any) => {
+  const style = useStyleConfig('PaneDivider')
+  return (
+    <Box
+      ref={ ref }
+      sx={ style }
+      { ...props }
+    />
+  )
+})

package/lib/components/split-pane/pane-item.tsx

@@ -0,0 +1,14 @@
+import React from 'react'
+import { GridItem, GridItemProps } from '@chakra-ui/react'
+
+/**
+ *  Wrapper around child of split pane
+ * @see SplitPane
+ * @see {@link https://northlight.dev/reference/PaneItem}
+ *
+ */
+export const PaneItem = ({ children, ...rest } : GridItemProps) => (
+  <GridItem overflow="hidden" { ...rest }>
+    { children }
+  </GridItem>
+)

package/lib/components/split-pane/split-pane.tsx

@@ -0,0 +1,75 @@
+import React, { cloneElement, useCallback, useRef } from 'react'
+import { Grid, useStyleConfig } from '@chakra-ui/react'
+import { SplitPaneProps } from './types'
+
+/**
+ * Used for split screen layouts
+ * @see PaneItem
+ * @see PaneDivider
+ * @see {@link https://northlight.dev/reference/split-pane}
+ *
+ */
+export const SplitPane = ({
+  children,
+  initialSplit = 50,
+  isOpen,
+  minLeftWidth = 25,
+  minRightWidth = 50,
+  ...rest
+}: SplitPaneProps) => {
+  const dividerRef = useRef<HTMLDivElement | null>(null)
+
+  const mouseDownHandler = useCallback(
+    (e: React.PointerEvent<HTMLDivElement>) => {
+      if (e.target !== dividerRef.current) {
+        return
+      }
+      let requestedFrame: number | null = null
+
+      e.stopPropagation()
+      e.preventDefault()
+
+      const target = e.currentTarget
+
+      target.setPointerCapture(e.pointerId)
+
+      target.onpointermove = (moveEvent: PointerEvent) => {
+        if (!(moveEvent.buttons && 1)) {
+          target.onpointermove = null
+          target.releasePointerCapture(moveEvent.pointerId)
+          return
+        }
+
+        moveEvent.stopPropagation()
+        moveEvent.preventDefault()
+
+        if (!requestedFrame) {
+          const { offsetX } = moveEvent
+
+          requestedFrame = requestAnimationFrame(() => {
+            target.style.setProperty(
+              '--split-pos',
+              `${Math.max(offsetX, 0)}px`
+            )
+            requestedFrame = null
+          })
+        }
+      }
+    },
+    []
+  )
+
+  const containerStyle = useStyleConfig('SplitPane', { minLeftWidth, minRightWidth, initialSplit, isOpen })
+
+  return (
+    <Grid
+      sx={ containerStyle }
+      onPointerDown={ mouseDownHandler }
+      { ...rest }
+    >
+      { children[0] }
+      { isOpen && cloneElement(children[1], { ref: dividerRef }) }
+      { isOpen && children[2] }
+    </Grid>
+  )
+}

package/lib/components/split-pane/types.ts

@@ -0,0 +1,10 @@
+import { GridProps } from '@chakra-ui/react'
+import { ReactElement } from 'react'
+
+export interface SplitPaneProps extends GridProps {
+  isOpen: boolean
+  children: ReactElement[]
+  initialSplit?: number
+  minLeftWidth?: number
+  minRightWidth?: number
+}

package/lib/components/stack/index.ts

@@ -0,0 +1,7 @@
+export {
+  Stack,
+  HStack,
+  VStack,
+  StackDivider,
+} from '@chakra-ui/react'
+export type { StackProps } from '@chakra-ui/react'

package/lib/components/stat/index.ts

@@ -0,0 +1,8 @@
+export {
+  Stat,
+  StatLabel,
+  StatNumber,
+  StatHelpText,
+  StatArrow,
+  StatGroup,
+} from '@chakra-ui/react'

package/lib/components/status-pin/index.ts

@@ -0,0 +1,2 @@
+export * from './status-pin'
+export * from './types'