# Contents

- Individual components
- Core library functions and types
- Icons definitions
- xStyled system custom types
- Theme definition
- Internal utilities

# Description

This folder includes full library's scope with all components, functions, mechanisms and definitions. Everything is exposed on the root level, as well as individual level.

Core folder exposes primary functions and types needed for the library main functionality. Its also intended to be consumed by the users of the library. It includes the theme provider (VuiProvider) with related components, utilities to create new base components, functions to modify or use the theme or media queries.

Icons folder includes a selected collection of base icons as defined in Figma. It includes icons cache, which stores a few icons in memory be default, but can be extended to hold more icons. All other icons not in the cache will be loaded from Veracity CDN at runtime.

System folder contains the custom definition of types for xStyled system is necessary in order to limit the amount of style props exposed on every component. Currently it supports ~200 props, instead of the original 1000+. This is only relevant for xStyled v2.x. When switching to v3, most of it will be removed.

Theme folder includes the definition of foundations (design tokens) and a compilation of individual components' theme definitions. It combines everything into a single VuiTheme, which is made available to consumers through VuiProvider. The theme can be extended or modified by augmenting the VuiThemeExtensions interface.

Utils folder includes utility functions used internally across the library. It holds common JS transformers and helpers, as well as React-specific function and general types.

# Component structure

Each component follows a very similar file structure and code patterns. Common files include:

- {component}.tsx - the main component
- {component}.types.ts - types for the main component and any related parts
- index.ts - exposes all contents of a component folder
- theme.ts - component theme definition with sizes and variants
- {componentPart}.tsx - optional, defines component part of the main composite component
- context.ts - optional, used by main component to share data with its parts (child components)
- consts.ts - optional, constant values used by the component
- helpers.ts - optional, helper functions used by the component

Main component is created with the 'vui' function and includes a base component, as well as a unique className, nested content, socket props, dynamic styles and logical operations. Base component is created with internal 'styled' function. The 'styled' function provides static CSS and state styles.

The base component is exposed together with the main component, so that library consumers can bulld their own components on top of the base, as well as refer to those components using [Styled Components targeting syntax](https://styled-components.com/docs/advanced#referring-to-other-components).

Example of a component structure:

```tsx
export const ComponentBase = styled.divBox`
  // static styles
`

export const Component = vui<'div', ComponentProps>((props, ref) => {
  const { children, className, ...rest } = omitThemingProps(props)
  const styles = useStyleConfig('Component', props)

  // set up dynamic props, functions, hooks, etc.

  return (
    <ComponentBase
      className={cs('vui-component', className)}
      ref={ref}
      // Dynamic styles
      {...styles.container}
      {...rest}
    >
      {/* sockets */}

      {children}

      {/* sockets */}
    </ComponentBase>
  )
})

export default Component
```
