@startupjs-ui/multi-select 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+## [0.1.3](https://github.com/startupjs/startupjs-ui/compare/v0.1.2...v0.1.3) (2025-12-29)
+
+**Note:** Version bump only for package @startupjs-ui/multi-select
+
+
+
+
+
+## [0.1.2](https://github.com/startupjs/startupjs-ui/compare/v0.1.1...v0.1.2) (2025-12-29)
+
+
+### Features
+
+* add mdx and docs packages. Refactor docs to get rid of any @startupjs/ui usage and use startupjs-ui instead ([703c926](https://github.com/startupjs/startupjs-ui/commit/703c92636efb0421ffd11783f692fc892b74018f))
+* **multi-select:** refactor MultiSelect component ([65ea9c9](https://github.com/startupjs/startupjs-ui/commit/65ea9c9b06c68c1058c92a6f775fed735d509cb4))

package/README.mdx

@@ -0,0 +1,234 @@
+import { useState } from 'react'
+import { Sandbox } from '@startupjs-ui/docs'
+import Br from '@startupjs-ui/br'
+import Div from '@startupjs-ui/div'
+import Span from '@startupjs-ui/span'
+import MultiSelect, { _PropsJsonSchema as MultiSelectPropsJsonSchema } from './index'
+
+# MultiSelect
+
+MultiSelect lets user pick multiple options.
+
+```jsx
+import { MultiSelect } from 'startupjs-ui'
+```
+
+## Initialization
+
+Before use you need to configure [Portal](/docs/components/Portal)
+
+## Simple example
+
+```jsx example
+const OPTIONS = [
+  { label: 'New York', value: 'ny' },
+  { label: 'Los Angeles', value: 'la' },
+  { label: 'Tokyo', value: 'tk' },
+]
+
+const [cities, setCities] = useState([])
+
+return (
+  <MultiSelect
+    value={cities}
+    onChange={setCities}
+    options={OPTIONS}
+  />
+)
+```
+
+## Options
+
+You can pass array of objects `{ label, value }` or primitives to `options`.
+
+```jsx example
+const OBJECT_OPTIONS_EXAMPLE = [
+  { label: 'New York', value: 'ny' },
+  { label: 'Los Angeles', value: 'la' },
+]
+const PRIMITIVIES_OPTIONS_EXAMPLE = [
+  'New York',
+  'Los Angeles',
+]
+
+const [cities, setCities] = useState([])
+const [citiesArray, setCitiesArray] = useState([])
+
+return (
+  <>
+    <MultiSelect
+      value={cities}
+      onChange={setCities}
+      options={OBJECT_OPTIONS_EXAMPLE}
+    />
+    <Br />
+    <MultiSelect
+      value={citiesArray}
+      onChange={setCitiesArray}
+      options={PRIMITIVIES_OPTIONS_EXAMPLE}
+    />
+  </>
+)
+```
+
+## Disabled
+
+```jsx example
+const OPTIONS = [
+  { label: 'New York', value: 'ny' },
+  { label: 'Los Angeles', value: 'la' },
+  { label: 'Tokyo', value: 'tk' },
+]
+const [cities, setCities] = useState(['ny'])
+
+return (
+  <MultiSelect
+    disabled
+    value={cities}
+    onChange={setCities}
+    options={OPTIONS}
+  />
+)
+```
+
+## Readonly
+
+```jsx example
+const OPTIONS = [
+  { label: 'New York', value: 'ny' },
+  { label: 'Los Angeles', value: 'la' },
+  { label: 'Tokyo', value: 'tk' },
+]
+const [cities, setCities] = useState(['ny'])
+
+return (
+  <MultiSelect
+    readonly
+    value={cities}
+    onChange={setCities}
+    options={OPTIONS}
+  />
+)
+```
+
+## Tag
+
+You can add a custom tag component.
+
+```jsx example
+const OPTIONS = [
+  { label: 'New York', value: 'ny' },
+  { label: 'Los Angeles', value: 'la' },
+  { label: 'Tokyo', value: 'tk' },
+]
+
+const [cities, setCities] = useState([])
+
+return (
+  <MultiSelect
+    value={cities}
+    TagComponent={({ record }) => <Span>✔ {record.label} &nbsp;&nbsp;&nbsp;&nbsp;</Span>}
+    onChange={setCities}
+    options={OPTIONS}
+  />
+)
+```
+
+## Input Component
+
+You can add a custom input component.
+
+```jsx example
+const OPTIONS = [
+  { label: 'New York', value: 'ny' },
+  { label: 'Los Angeles', value: 'la' },
+  { label: 'Tokyo', value: 'tk' },
+]
+
+const [cities, setCities] = useState([])
+
+return (
+  <MultiSelect
+    value={cities}
+    InputComponent={
+      ({ children, onOpen }) => {
+        return (
+          <Div
+            onPress={onOpen}
+            style={{
+              border: '1px dotted green',
+              padding: 8
+            }}
+          >
+            {children}
+          </Div>
+        )
+      }
+    }
+    TagComponent={({ record }) => <Span>✔ {record.label} &nbsp;&nbsp;&nbsp;&nbsp;</Span>}
+    onChange={setCities}
+    options={OPTIONS}
+  />
+)
+```
+
+## Tag limit
+
+You can limit the number of displayed tags by passing `tagLimit={number}`.
+
+```jsx example
+const OPTIONS = [
+  { label: 'New York', value: 'ny' },
+  { label: 'Los Angeles', value: 'la' },
+  { label: 'Tokyo', value: 'tk' },
+]
+
+const [cities, setCities] = useState([])
+
+return (
+  <MultiSelect
+    tagLimit={2}
+    value={cities}
+    onChange={setCities}
+    options={OPTIONS}
+  />
+)
+```
+
+## Limit the number of selected tags
+
+You can limit the number of selected tags by passing `maxTagCount={number}`.
+
+```jsx example
+const OPTIONS = [
+  { label: 'New York', value: 'ny' },
+  { label: 'Los Angeles', value: 'la' },
+  { label: 'Tokyo', value: 'tk' },
+]
+
+const [cities, setCities] = useState([])
+
+return (
+  <MultiSelect
+    maxTagCount={2}
+    value={cities}
+    onChange={setCities}
+    options={OPTIONS}
+  />
+)
+```
+
+## Sandbox
+
+<Sandbox
+  Component={MultiSelect}
+  propsJsonSchema={MultiSelectPropsJsonSchema}
+  props={{
+    value: ['New York'],
+    options: ['New York', 'Los Angeles', 'Tokyo'],
+    onChange: value => console.info('New value is ' + JSON.stringify(value)),
+    onSelect: value => console.info('Value \"' + value + '\" is selected'),
+    onRemove: value => console.info('Value \"' + value + '\" is removed'),
+  }}
+  block
+/>

package/index.cssx.styl

@@ -0,0 +1,95 @@
+$inputBg = var(--color-bg-main-strong)
+$inputBorderWidth = 1px
+$inputBorderColor = var(--color-border-main)
+$inputBgDisabled = var(--color-bg-main)
+$inputPlaceholderColor = var(--color-text-placeholder)
+$focusedColor = var(--color-border-primary)
+$errorColor = var(--color-border-error)
+$swipeZoneColor = var(--color-bg-secondary-subtle)
+$suggestionsPopoverMaxHeight = 25u
+
+.input
+  padding 5px 1u
+  background-color $inputBg
+  border-width $inputBorderWidth
+  border-style solid
+  border-color $inputBorderColor
+  min-height 4u
+  min-width 8u
+  radius()
+
+  &.disabled
+    background-color $inputBgDisabled
+
+  &.focused
+    border-color $focusedColor
+
+  &.error
+    border-color $errorColor
+
+.placeholder
+  color $inputPlaceholderColor
+
+.tag
+  margin-right 0.5u
+
+  &.last
+    margin-right 0
+
+.row
+  padding-right 3u
+  width 100%
+
+.suggestions-web
+  padding 0 1u
+  max-height $suggestionsPopoverMaxHeight
+
+.suggestions-native
+  padding 1u 0
+
+.nativeListContent
+  padding-top 5u
+
+  &:part(swipe)
+    background-color $swipeZoneColor
+
+.suggestion
+  cursor pointer
+  padding 1u 2u
+  flex-direction row
+  align-items center
+
+  +desktop()
+    padding 1u
+
+.sugText
+  color var(--color-text-main)
+  font(h5)
+
+  +desktop()
+    font(body2)
+
+.backdropStyle
+  // Greater value than @startup/ui's Modal has
+  z-index 1501
+
+.popover
+  padding 0 .5u
+  max-height $suggestionsPopoverMaxHeight
+  min-width 20u
+
+.ellipsis
+  margin 0 1u
+
+.suggestionItem
+  padding 1u 0
+
+.check
+  width 2u
+
+.checkIcon
+  color var(--color-text-primary)
+
+.label
+  margin-right 1u
+  flex-grow 1

package/index.d.ts

@@ -0,0 +1,61 @@
+/* eslint-disable */
+// DO NOT MODIFY THIS FILE - IT IS AUTOMATICALLY GENERATED ON COMMITS.
+
+import { type ReactNode, type RefObject } from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+import './index.cssx.styl';
+declare const _default: import("react").ComponentType<MultiSelectProps>;
+export default _default;
+export declare const _PropsJsonSchema: {};
+export interface MultiSelectOption {
+    label: any;
+    value: any;
+}
+export interface MultiSelectProps {
+    /** Custom styles for the Popover anchor wrapper */
+    style?: StyleProp<ViewStyle>;
+    /** Custom styles for the input wrapper */
+    inputStyle?: StyleProp<ViewStyle>;
+    /** Available options (objects with `{ label, value }` or primitives) @default [] */
+    options?: Array<MultiSelectOption | string | number | boolean>;
+    /** Selected values @default [] */
+    value?: any[];
+    /** Placeholder text shown when empty @default 'Select' */
+    placeholder?: string;
+    /** Disable interactions @default false */
+    disabled?: boolean;
+    /** Render non-editable value @default false */
+    readonly?: boolean;
+    /** Maximum number of visible tags (extra tags are collapsed) */
+    tagLimit?: number;
+    /** Behavior when tags are limited (legacy prop) @default 'hidden' */
+    tagLimitVariant?: 'hidden' | 'disabled';
+    /** Maximum number of selectable tags */
+    maxTagCount?: number;
+    /** Custom tag renderer */
+    TagComponent?: any;
+    /** Custom input renderer */
+    InputComponent?: any;
+    /** Match Popover width to anchor on web @default false */
+    hasWidthCaption?: boolean;
+    /** Custom suggestion item renderer */
+    renderListItem?: (options: {
+        item: MultiSelectOption;
+        index: number;
+        selected: boolean;
+    }) => ReactNode;
+    /** Called when selected values change */
+    onChange?: (value: any[]) => void;
+    /** Called when a value is selected */
+    onSelect?: (value: any) => void;
+    /** Called when a value is removed */
+    onRemove?: (value: any) => void;
+    /** Called when dropdown opens */
+    onFocus?: () => void;
+    /** Called when dropdown closes */
+    onBlur?: () => void;
+    /** Ref providing imperative `focus()` / `blur()` methods */
+    ref?: RefObject<any>;
+    /** Error flag @private */
+    _hasError?: boolean;
+}

package/index.tsx

@@ -0,0 +1,394 @@
+import {
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useState,
+  type ReactNode,
+  type RefObject
+} from 'react'
+import { Platform, type StyleProp, type ViewStyle } from 'react-native'
+import { pug, observer, useDidUpdate } from 'startupjs'
+import { themed } from '@startupjs-ui/core'
+import Div from '@startupjs-ui/div'
+import Drawer from '@startupjs-ui/drawer'
+import Icon from '@startupjs-ui/icon'
+import Popover from '@startupjs-ui/popover'
+import ScrollView from '@startupjs-ui/scroll-view'
+import Span from '@startupjs-ui/span'
+import Tag from '@startupjs-ui/tag'
+import { faCheck } from '@fortawesome/free-solid-svg-icons/faCheck'
+import './index.cssx.styl'
+
+const IS_WEB = Platform.OS === 'web'
+
+export default observer(themed('MultiSelect', MultiSelect))
+
+export const _PropsJsonSchema = {/* MultiSelectProps */} // used in docs generation
+
+export interface MultiSelectOption {
+  label: any
+  value: any
+}
+
+export interface MultiSelectProps {
+  /** Custom styles for the Popover anchor wrapper */
+  style?: StyleProp<ViewStyle>
+  /** Custom styles for the input wrapper */
+  inputStyle?: StyleProp<ViewStyle>
+  /** Available options (objects with `{ label, value }` or primitives) @default [] */
+  options?: Array<MultiSelectOption | string | number | boolean>
+  /** Selected values @default [] */
+  value?: any[]
+  /** Placeholder text shown when empty @default 'Select' */
+  placeholder?: string
+  /** Disable interactions @default false */
+  disabled?: boolean
+  /** Render non-editable value @default false */
+  readonly?: boolean
+  /** Maximum number of visible tags (extra tags are collapsed) */
+  tagLimit?: number
+  /** Behavior when tags are limited (legacy prop) @default 'hidden' */
+  tagLimitVariant?: 'hidden' | 'disabled'
+  /** Maximum number of selectable tags */
+  maxTagCount?: number
+  /** Custom tag renderer */
+  TagComponent?: any
+  /** Custom input renderer */
+  InputComponent?: any
+  /** Match Popover width to anchor on web @default false */
+  hasWidthCaption?: boolean
+  /** Custom suggestion item renderer */
+  renderListItem?: (options: { item: MultiSelectOption, index: number, selected: boolean }) => ReactNode
+  /** Called when selected values change */
+  onChange?: (value: any[]) => void
+  /** Called when a value is selected */
+  onSelect?: (value: any) => void
+  /** Called when a value is removed */
+  onRemove?: (value: any) => void
+  /** Called when dropdown opens */
+  onFocus?: () => void
+  /** Called when dropdown closes */
+  onBlur?: () => void
+  /** Ref providing imperative `focus()` / `blur()` methods */
+  ref?: RefObject<any>
+  /** Error flag @private */
+  _hasError?: boolean
+}
+
+function MultiSelect ({
+  style,
+  inputStyle,
+  options = [],
+  value = [],
+  placeholder = 'Select',
+  disabled = false,
+  readonly = false,
+  tagLimitVariant = 'hidden',
+  TagComponent = DefaultTag,
+  InputComponent,
+  tagLimit,
+  maxTagCount,
+  hasWidthCaption = false,
+  renderListItem,
+  onChange,
+  onSelect,
+  onRemove,
+  onFocus,
+  onBlur,
+  ref,
+  _hasError,
+  ...props
+}: MultiSelectProps): ReactNode {
+  const [focused, setFocused] = useState(false)
+  const isOpenable = !(disabled || readonly)
+
+  const normalizedOptions = useMemo(() => {
+    return options.map(opt => typeof opt === 'object' && opt !== null
+      ? opt
+      : { label: opt, value: opt }
+    )
+  }, [options])
+
+  const shouldDisableSelection = maxTagCount
+    ? maxTagCount === value.length
+    : false
+
+  const focusHandler = useCallback(() => {
+    if (isOpenable) setFocused(true)
+  }, [isOpenable])
+
+  const blurHandler = useCallback(() => { setFocused(false) }, [])
+
+  const handleChangeVisible = (nextVisible: boolean) => {
+    if (!nextVisible) {
+      setFocused(false)
+      return
+    }
+    if (!isOpenable) return
+    setFocused(true)
+  }
+
+  useDidUpdate(() => {
+    if (focused) onFocus && onFocus()
+    else onBlur && onBlur()
+  }, [focused])
+
+  useImperativeHandle(ref, () => ({
+    focus: focusHandler,
+    blur: blurHandler
+  }), [focusHandler, blurHandler])
+
+  useDidUpdate(() => {
+    if (focused && !isOpenable) blurHandler()
+  }, [focused, isOpenable])
+
+  function _onRemove (_value: any) {
+    onRemove && onRemove(_value)
+    onChange && onChange(value.filter(v => v !== _value))
+  }
+
+  function _onSelect (_value: any) {
+    onSelect && onSelect(_value)
+    onChange && onChange([...value, _value])
+  }
+
+  const onItemPress = (itemValue: any, selected: boolean) => (checked: boolean) => {
+    if (disabled || readonly) return
+    if (shouldDisableSelection && checked && !selected) return
+    if (!checked) {
+      _onRemove(itemValue)
+    } else {
+      _onSelect(itemValue)
+    }
+  }
+
+  function _renderListItem ({ item, index }: { item: MultiSelectOption, index: number }): ReactNode {
+    const { label, value: itemValue } = item
+    const selected = value.includes(itemValue)
+    const onPress = onItemPress(itemValue, selected)
+
+    return pug`
+      Div(
+        key=itemValue
+        vAlign='center'
+        disabled=selected ? false : shouldDisableSelection
+        onPress=() => onPress(!selected)
+      )
+        if renderListItem
+          = renderListItem({ item, index, selected })
+        else
+          Div.suggestionItem(row)
+            Span.label= label
+            Div.check
+              if selected
+                Icon(icon=faCheck styleName='checkIcon')
+    `
+  }
+
+  function renderContent (): ReactNode {
+    return pug`
+      ScrollView.suggestions-web
+        each option, index in normalizedOptions
+          = _renderListItem({ item: option, index })
+    `
+  }
+
+  return IS_WEB
+    ? pug`
+      Popover.popover(
+        part='root'
+        ...props
+        captionStyle=style
+        visible=focused
+        matchAnchorWidth=hasWidthCaption
+        attachment='start'
+        position='bottom'
+        onChange=handleChangeVisible
+        renderContent=renderContent
+      )
+        MultiSelectInput(
+          part='input'
+          style=inputStyle
+          focused=focused
+          value=value
+          placeholder=placeholder
+          tagLimit=tagLimit
+          tagLimitVariant=tagLimitVariant
+          options=normalizedOptions
+          disabled=disabled
+          readonly=readonly
+          InputComponent=InputComponent
+          TagComponent=TagComponent
+          _hasError=_hasError
+          onOpen=focusHandler
+          onHide=blurHandler
+        )
+    `
+    : pug`
+      MultiSelectInput(
+        part='input'
+        style=inputStyle
+        onOpen=focusHandler
+        onHide=blurHandler
+        focused=focused
+        value=value
+        placeholder=placeholder
+        tagLimit=tagLimit
+        tagLimitVariant=tagLimitVariant
+        options=normalizedOptions
+        disabled=disabled
+        readonly=readonly
+        InputComponent=InputComponent
+        TagComponent=TagComponent
+        _hasError=_hasError
+      )
+      Drawer.nativeListContent(
+        part='root'
+        visible=focused
+        position='bottom'
+        onDismiss=blurHandler
+      )
+        ScrollView.suggestions-native
+          each option, index in normalizedOptions
+            = _renderListItem({ item: option, index })
+    `
+}
+
+function MultiSelectInput ({
+  style,
+  value,
+  placeholder,
+  options,
+  disabled,
+  readonly,
+  focused,
+  tagLimit,
+  tagLimitVariant,
+  TagComponent,
+  InputComponent,
+  onOpen,
+  onHide,
+  _hasError
+}: {
+  style?: StyleProp<ViewStyle>
+  value: any[]
+  placeholder?: string
+  options: MultiSelectOption[]
+  disabled?: boolean
+  readonly?: boolean
+  focused?: boolean
+  tagLimit?: number
+  tagLimitVariant?: 'hidden' | 'disabled'
+  TagComponent?: any
+  InputComponent?: any
+  onOpen?: () => void
+  onHide?: () => void
+  _hasError?: boolean
+}): ReactNode {
+  const values = tagLimit ? value.slice(0, tagLimit) : value
+  const hiddenTagsLength = tagLimit
+    ? value.slice(tagLimit, value.length).length
+    : 0
+
+  const EffectiveInputComponent = InputComponent ?? DefaultInput
+
+  return pug`
+    EffectiveInputComponent(
+      part='root'
+      style=style
+      value=values
+      placeholder=placeholder
+      disabled=disabled
+      focused=focused
+      readonly=readonly
+      onOpen=onOpen
+      onHide=onHide
+      _hasError=_hasError
+    )
+      each value, index in values
+        - const record = options.find(r => r.value === value) || {}
+        - const isLast = index + 1 === values.length
+        TagComponent(
+          key=value
+          index=index
+          isLast=isLast
+          record=record
+        )
+      if hiddenTagsLength
+        Span.ellipsis ...
+        DefaultTag(
+          index=0
+          record={ label: '+' + hiddenTagsLength }
+        )
+  `
+}
+
+function DefaultInput ({
+  style,
+  value = [],
+  placeholder,
+  disabled,
+  focused,
+  readonly,
+  children,
+  onOpen,
+  onHide,
+  _hasError,
+  ref
+}: {
+  style?: StyleProp<ViewStyle>
+  value?: any[]
+  placeholder?: string
+  disabled?: boolean
+  focused?: boolean
+  readonly?: boolean
+  children?: ReactNode
+  onOpen?: () => void
+  onHide?: () => void
+  _hasError?: boolean
+  ref?: RefObject<any>
+}): ReactNode {
+  useImperativeHandle(ref, () => ({
+    focus: () => { onOpen && onOpen() },
+    blur: () => { onHide && onHide() }
+  }), [onOpen, onHide])
+
+  useEffect(() => {
+    if (focused && disabled) onHide && onHide()
+  }, [disabled, focused, onHide])
+
+  return pug`
+    if readonly
+      Span= value.join(', ')
+    else
+      Div.input(
+        style=style
+        styleName={ disabled, focused, readonly, error: _hasError }
+        onPress=disabled || readonly ? void 0 : onOpen
+        wrap
+        row
+      )
+        if !value.length
+          Span.placeholder= placeholder || '-'
+
+        = children
+  `
+}
+
+function DefaultTag ({
+  record,
+  isLast
+}: {
+  record?: any
+  isLast?: boolean
+}): ReactNode {
+  return pug`
+    Tag.tag(
+      styleName={ last: isLast }
+      size='s'
+      variant='flat'
+      color='primary'
+    )= record?.label
+  `
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@startupjs-ui/multi-select",
+  "version": "0.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "index.tsx",
+  "types": "index.d.ts",
+  "type": "module",
+  "dependencies": {
+    "@startupjs-ui/core": "^0.1.3",
+    "@startupjs-ui/div": "^0.1.3",
+    "@startupjs-ui/drawer": "^0.1.3",
+    "@startupjs-ui/icon": "^0.1.3",
+    "@startupjs-ui/popover": "^0.1.3",
+    "@startupjs-ui/scroll-view": "^0.1.3",
+    "@startupjs-ui/span": "^0.1.3",
+    "@startupjs-ui/tag": "^0.1.3"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*",
+    "startupjs": "*"
+  },
+  "gitHead": "fd964ebc3892d3dd0a6c85438c0af619cc50c3f0"
+}