@basiln/utils

@basiln-utils

유용한 컴포넌트 및 유틸리티 모음

설치

yarn add @basiln/utils

• If
• Choose
• Flex
• Validate
• queryString
• hexToRgba
• SafeArea
• Spacing
• ellipsis 및 multiLineEllipsis
• Josa
• createContext
• debounce
• composeEventHandlers
• getVar
• Format
• DomainFormat
• useCombinedRefs
• useControllableState
• Grid

If

조건에 따라 자식 요소를 렌더링하는 컴포넌트입니다. condition 속성이 true일 때만 자식 요소를 렌더링합니다.

import { If } from '@basiln/utils';

<If condition={true}>
  <p>조건이 참일 때만 렌더링됩니다.</p>
</If>;

condition이 false일 경우에도 자식 요소를 평가하지 않으려면 render 속성을 사용하세요.

<If condition={false} render={() => <p>이 내용은 조건에 따라 평가됩니다.</p>} />

Choose

switch-case와 유사하게 조건에 따라 자식 요소를 렌더링하는 컴포넌트입니다. Choose에는 두 가지 하위 컴포넌트가 있습니다:

• Choose.When: condition이 true일 때 자식 요소를 렌더링합니다.
• Choose.Otherwise: Choose.When 조건이 모두 false일 때 렌더링됩니다.

import { Choose } from '@basiln/utils';

<Choose>
  <Choose.When condition={true}>
    <p>첫 번째 조건이 참일 때 렌더링됩니다.</p>
  </Choose.When>
  <Choose.When condition={false}>
    <p>이 내용은 렌더링되지 않습니다.</p>
  </Choose.When>
  <Choose.Otherwise>
    <p>모든 조건이 거짓일 때 렌더링됩니다.</p>
  </Choose.Otherwise>
</Choose>;

Flex

선언적으로 flex box 스타일링을 할 수 있는 컴포넌트입니다.

import { Flex } from '@basiln/utils';

<Flex justify="space-between" align="center" gap={20}>
  <div>Left</div>
  <div>Right</div>
</Flex>
<Flex gap='10%'>
  <div>Left</div>
  <div>Right</div>
</Flex>

Validate

정규식을 사용해 입력값을 검증할 수 있는 유틸리티입니다.

import { Validate } from '@basiln/utils';

Validate.email('[e-mail]'); // true
Validate.phoneNumber('010-1234-5678'); // true

queryString

URL의 쿼리 문자열을 생성, 파싱, 조회, 수정할 수 있는 유틸리티입니다.

import { queryString } from '@basiln/utils';

// 쿼리 문자열 생성
queryString.create({ a: '1', b: '2' }); // ?a=1&b=2

// 쿼리 문자열 파싱
queryString.parse('?a=1&b=2'); // { a: '1', b: '2' }

// 특정 키의 값 조회
queryString.get('a'); // '1'

// 특정 키의 값 수정
queryString.set({ qs: '?a=1', key: 'b', value: '2' }); // '?a=1&b=2'

hexToRgba

16진수 컬러 코드를 rgba() 표기로 변환하는 유틸리티입니다.

import { hexToRgba } from '@basiln/utils';

hexToRgba({ hex: '#000000', alpha: 0.5 }); // 'rgba(0, 0, 0, 0.5)'

SafeArea

웹뷰 환경에서 안전 영역(Safe Area)을 선언적으로 사용할 수 있는 컴포넌트입니다.

import { SafeArea, useSafeArea } from '@basiln/utils';

// 컴포넌트로 사용
<SafeArea>
  <p>안녕하세요</p>
</SafeArea>;

// 유틸리티로 사용
const { top, bottom } = useSafeArea();

Spacing

요소 간 간격을 선언적으로 설정할 수 있는 컴포넌트입니다.

import { Spacing } from '@basiln/utils';

<Spacing size={30} />;
<Spacing size="2rem" direction="horizontal" />;

ellipsis 및 multiLineEllipsis

텍스트가 일정한 길이를 초과할 경우 생략 표시를 적용하는 유틸리티입니다.

import { ellipsis, multiLineEllipsis } from '@basiln/utils';

// 단일 줄 텍스트 생략
<p css={ellipsis}>긴 텍스트</p>;

// 다중 줄 텍스트 생략
<p css={multiLineEllipsis({ line: 3 })}>긴 텍스트</p>;

Josa

한국어 문장에서 적절한 조사를 반환하는 유틸리티입니다.

import { josa } from '@basiln/utils';

josa({ josa: '을/를', word: '망곰이' }); // 망곰이를
josa.pick({ josa: '은/는', word: '하츄핑' }); // 은

createContext

React의 Context를 보다 선언적으로 생성하고 사용할 수 있는 유틸리티입니다.

사용법

import { createContext } from '@basiln/utils';

const [MyProvider, useMyContext] = createContext<{ value: string }>(
  'MyComponent'
);

function App() {
  return (
    <MyProvider value="Hello World">
      <Child />
    </MyProvider>
  );
}

function Child() {
  const context = useMyContext('Child');
  return <div>{context.value}</div>;
}

debounce

지정된 시간(ms) 동안 연속적으로 호출된 함수 실행을 지연시키는 유틸리티입니다.

일반적으로 연속된 사용자 입력 처리 시 사용됩니다.

사용법

import { debounce } from '@basiln/utils';

const debouncedLog = debounce(() => {
  console.log('Debounced Function Called');
}, 1000);

function App() {
  const handleClick = () => {
    debouncedLog();
  };

  return <button onClick={handleClick}>Click me</button>;
}

// 추가 메서드
debouncedLog.cancel(); // 예약된 호출 취소
debouncedLog.flush(); // 예약된 호출 즉시 실행

composeEventHandlers

두 개의 이벤트 핸들러를 결합하여 하나의 핸들러로 만드는 유틸리티입니다.

첫 번째 핸들러가 defaultPrevented를 호출하면 두 번째 핸들러는 실행되지 않습니다.

사용법

import { composeEventHandlers } from '@basiln/utils';

function App() {
  const onClickFirst = (event: React.MouseEvent) => {
    console.log('First Handler');
  };

  const onClickSecond = (event: React.MouseEvent) => {
    console.log('Second Handler');
  };

  const combinedHandler = composeEventHandlers(onClickFirst, onClickSecond);

  return <button onClick={combinedHandler}>Click Me</button>;
}

getVar

CSS 변수(--var)를 읽거나, 기본값을 지정하여 읽는 유틸리티입니다.

사용법

import { getVar } from '@basiln/utils';

const primaryColor = getVar('--primary-color', '#000');

function App() {
  return <div style={{ color: primaryColor }}>Hello</div>;
}

• getVar('--variable'): 지정된 변수 값을 읽습니다.
• getVar('--variable', 'default'): 변수가 정의되지 않았을 경우 기본값을 반환합니다.

:root {
  --primary-color: #ff5722;
}

Format

다양한 데이터를 원하는 형식으로 변환하는 포맷팅 유틸리티입니다.

사용법

import { Format } from '@basiln/utils';

Format.phone('01012345678'); // '010-1234-5678'
Format.commaize('123456'); // '123,456'
Format.padTime(1); // '01'
Format.email('[e-mail]'); // [e-mail]

DomainFormat

도메인 관련 데이터를 원하는 형식으로 변환하는 포맷팅 유틸입니다.

사용법

// 기본
DomainFormat.modeName('H'); // 난방
DomainFormat.modeColor('H'); // #e77676
DomainFormat.wind(3) // 강풍
DomainFormat.airLevelName(4) // 좋음
DomainFormat.airLevelColor(1) // #ff5d47
DomainFormat.userLevel({level: '1'}) // 마스터
DomainFormat.userLevel({level: '1', language: 'en'}) // MASTER

// Mode 추가가 필요한 경우 
DomainFormat.modeName('R', {R: '실외기 잠금'}); // 실외기 잠금
DomainFormat.modeColor('R', {N: 'gray'}); // 'gray'

useCombinedRefs

컴포넌트 내부에 선언된 ref와, 사용하는 부분에서 forwarded된 ref를 합칠 수 있도록 하는 hook 입니다.

사용법

const TextField = forwardRef((props, forwardedRef) => {
    const ref = useRef<HTMLInputElement | null>(null);
    const combinedRefs = useCombinedRefs(ref, forwardedRef);
    return <input ref={ref} />
})

useControllableState

사용자의 입력을 통해 상태를 관리할 때와 사용자의 입력을 상태로 관리하지 않고 싶을 때 두 경우 모두를 지원하는 hook 입니다.

사용법 (참고)

  const [value, setValue] = useControllableState({
    prop: valueFromProps,
    defaultProp: defaultValue,
    onChange: onValueChange,
  });
  return (
    <SelectProvider
      value={value}
      onValueChange={setValue}
      triggerWidth={triggerWidth}
      onTriggerWidthChange={setTriggerWidth}
    >
      <SelectPrimitive.Root value={value} onValueChange={setValue} {...restProps}>
        <div ref={ref}>{children}</div>
      </SelectPrimitive.Root>
    </SelectProvider>
  );
});

Grid

선언적으로 Grid 스타일링을 할 수 있는 컴포넌트입니다.

import { Grid } from '@basiln/utils';

<Grid columns={['1fr', '1fr', '1fr']} rows={['1fr']} gap={10}>
  <Grid.Item gridColumn={['1', '3']}>
    <Content1 />
  </Grid.Item>

  <Grid.Item>
    <Content2 />
  </Grid.Item>
</Grid>

<Grid areas={'"header header" "sidebar content"'}>
  <Grid.Item gridArea="header">
    <Header />
  </Grid.Item>

  <Grid.Item gridArea="content">
    <Content1 />
  </Grid.Item>

  <Grid.Item gridArea="sidebar">
    <Sidebar />
  </Grid.Item>
</Grid>