@kintsugi/uikit

UI Kit library built with Vite, TypeScript, and React.

Installation

npm install @kintsugi/uikit

Required Peer Dependencies

Make sure to install all required peer dependencies in your consuming application:

npm install react react-dom @emotion/react @mui/material @mui/x-data-grid \
  @sds-eng/base @sds-eng/data-grid classnames date-fns i18next lodash moment \
  react-i18next react-router react-router-dom styled-components

Usage

Importing from the Library

The library supports multiple entry points for better tree-shaking:

// Import everything (not recommended for production)
import { Button, Text, Badge } from '@kintsugi/uikit'

// Import from specific entry points (recommended)
import { Button } from '@kintsugi/uikit/components'
import { SunIcon } from '@kintsugi/uikit/icons'
import { copyToClipboard, formatSize } from '@kintsugi/uikit/libs'
import { useHover, useVisible } from '@kintsugi/uikit/hooks'
import { ProjectTheme, ProjectLocal } from '@kintsugi/uikit/constants'
import { HostProvider, loadManifest } from '@kintsugi/uikit/mfe'
import { ThemeProvider, useHostContext } from '@kintsugi/uikit/theme'

Type Definitions

The library exports full TypeScript type definitions for all components, hooks, and utilities.

Component Props Types

Each component exports its props type with the pattern {ComponentName}Props:

import { Button, type ButtonProps } from '@kintsugi/uikit/components'

// Use the type for custom wrappers
const CustomButton = (props: ButtonProps) => {
  return <Button {...props} />
}

// Or for typed variables
const buttonConfig: ButtonProps = {
  title: 'Click me',
  size: 'md',
  view: 'primary',
  handleClick: () => console.log('clicked'),
  dataTestID: 'my-button'
}

Hook Return Types

Hooks export their return types for use in custom implementations:

import { useHover, useVisible, useOutsideClick } from '@kintsugi/uikit/hooks'

// useHover returns: { isHovered: boolean, ref: RefObject<HTMLDivElement> }
const { isHovered, ref } = useHover()

// useVisible returns: { ref: MutableRefObject<HTMLDivElement>, visible: boolean }
const { ref, visible } = useVisible()

// useOutsideClick returns: void (takes onClose and id as parameters)
useOutsideClick(() => console.log('closed'), 'modal-id')

Theme Types

import type { ProjectTheme, ThemeType } from '@kintsugi/uikit/theme'
import { useGetStyledTheme } from '@kintsugi/uikit/theme'

// Get the current theme object
const theme = useGetStyledTheme()

// Theme structure:
// {
//   colors: { ... },
//   font: { ... },
//   zIndex: { ... },
//   themeMode: ThemeType
// }

// Access typed theme values
const errorColor: string = theme.colors.error
const h1Font: string = theme.font.h1
const modalZIndex: number = theme.zIndex.modal

Constants Types

import { ProjectTheme, ProjectLocal } from '@kintsugi/uikit/constants'

// Enum values
const darkTheme: ProjectTheme = ProjectTheme.Dark
const russianLocale: ProjectLocal = ProjectLocal.Ru

// Use in switch statements with proper typing
const getThemeName = (theme: ProjectTheme): string => {
  switch (theme) {
    case ProjectTheme.Dark:
      return 'dark'
    case ProjectTheme.Light:
      return 'light'
  }
}

MFE Types

import type {
  IHostApi,
  MFEModule,
  MFEMeta,
  MountContext,
  Unmount,
} from '@kintsugi/uikit/mfe'
import { HostContext, HostProvider, loadManifest } from '@kintsugi/uikit/mfe'

// Host API interface for MFE communication
const hostApi: IHostApi = {
  theme: ProjectTheme.Light,
  lang: ProjectLocal.En,
  handleAddThemeListener: cb => {
    /* ... */
  },
  handleAddI18nListener: cb => {
    /* ... */
  },
  handleRemoveThemeListener: cb => {
    /* ... */
  },
  handleRemoveI18nListener: cb => {
    /* ... */
  },
}

// Mount function type
const mount: (root: ShadowRoot | Element, ctx: MountContext) => Unmount = (
  root,
  ctx,
) => {
  // Mount your MFE module
  return () => {
    /* cleanup */
  }
}

Library Utility Types

import {
  copyToClipboard,
  formatSize,
  convertSizeTo,
  debounceAnimation,
  createElementAndAddToParent,
  hexToRGB,
  formatDate,
  formatTimestamp,
} from '@kintsugi/uikit/libs'

// All utilities are fully typed
const rgb = hexToRGB('#ffffff') // Returns: { r: number, g: number, b: number } | null
const formatted = formatSize(1024) // Returns: string
const dateStr = formatDate(new Date()) // Returns: string

TypeScript Configuration

For proper type resolution in your consuming application, ensure your tsconfig.json has:

{
  "compilerOptions": {
    "moduleResolution": "bundler", // or "node16"
    "esModuleInterop": true,
    "skipLibCheck": true,
    "strict": true
  }
}

Available Exports

Components (@kintsugi/uikit/components)

• Accordion, Autocomplete, Avatar, Badge, Breadcrumbs
• Button, Card, Checkbox, DataGrid, DatePicker, DateTimePicker
• Drawer, DropdownMenu, FileUploader, IconButton, InputNumber
• InputPassword, Link, Marker, Modal, OutsideMultiSelect
• Page, Popover, Rating, Select, SegmentsGroup, Sidebar
• Skeleton, Spinner, StatusCard, Switch, Tabs, Tag
• Text, Textarea, TextField, Tooltip, ValidatorInformation
• And more...

Icons (@kintsugi/uikit/icons)

• Support icons: Settings, Information, Search, Filter, etc.
• SQL introspection icons
• Sidebar icons: Logotip (full/short)

Utilities (@kintsugi/uikit/libs)

• array: isLastElementInArray
• buffer: copyToClipboard, convertSizeTo, formatSize
• date: formatDate, formatDuration, formatTimestamp, getUtcOffset
• dom: debounceAnimation, createElementAndAddToParent
• localStorage: getValue/setValue/removeValue functions
• sessionStorage: getValue/setValue functions
• string: hexToRGB, replaceLast, textCroppingWithLenght, validetaLenght

Hooks (@kintsugi/uikit/hooks)

• useHover - Track hover state on elements
• useVisible - IntersectionObserver-based visibility detection
• useOutsideClick - Detect clicks outside an element
• useScrollToElement - Scroll to element by ID
• useAddDataTestIDWithRef - Add data-testid attributes
• useBlockNavigate - Block navigation with confirmation modal

Constants (@kintsugi/uikit/constants)

• ProjectTheme enum: Dark, Light
• ProjectLocal enum: Ru, En

MFE (@kintsugi/uikit/mfe)

• HostContext, HostProvider, useHostContext
• HostApi class
• loadManifest function
• Types: IHostApi, MFEModule, MFEMeta, MountContext, Unmount

Theme (@kintsugi/uikit/theme)

• ThemeProvider - Main theme provider component
• useGetStyledTheme - Hook to get styled theme object
• useHostContext - Get MFE host context
• colors - Color constants
• Types: ProjectTheme, ThemeType

Example: Creating a Typed Wrapper Component

import { FC } from 'react'
import { Button, type ButtonProps } from '@kintsugi/uikit/components'

interface CustomButtonProps extends ButtonProps {
  isLoading?: boolean
}

export const CustomButton: FC<CustomButtonProps> = ({
  isLoading,
  title,
  ...props
}) => {
  return (
    <Button
      title={isLoading ? 'Loading...' : title}
      isDisabled={isLoading}
      {...props}
    />
  )
}

Example: Using Theme in a Component

import { FC } from 'react'
import { useGetStyledTheme } from '@kintsugi/uikit/theme'
import { Text } from '@kintsugi/uikit/components'

export const ThemedText: FC<{ text: string }> = ({ text }) => {
  const theme = useGetStyledTheme()

  return (
    <Text
      text={text}
      style={{ color: theme.colors.error }}
    />
  )
}

License

MIT