1.1.1066 • Published 1 week ago

ados-rcm

Licence

MIT

Version

1.1.1066

Deps

Size

6.8 MB

Vulns

Weekly

Summary Dependency Versions

ARCM

React 19 + TypeScript 기반 컴포넌트 라이브러리입니다. 버튼, 입력, 선택, 테이블, 트리, 피드백 UI 같은 공통 컴포넌트와 함께, 복잡한 문서 편집 요구를 처리하는 BEditor 리치 텍스트 에디터를 제공합니다.

이 README는 채용 포트폴리오 검토자가 프로젝트의 기술 범위, 설계 판단, 검증 방식을 빠르게 파악할 수 있도록 실제 코드와 스크립트에 근거해 정리했습니다.

Project Snapshot

항목	내용
패키지	`ados-rcm`
유형	React component library
공개 엔트리	`src/index.tsx`
대표 기능	`BEditor` 기반 리치 텍스트 편집, 테이블/미디어/툴바/풀스크린/읽기 모드
기술 스택	React 19, TypeScript, Vite 6, Sass modules, Storybook 10, Vitest, Testing Library
번들 출력	ESM, CJS, declaration files
라이선스	MIT (`package.json` 기준)

Why This Project Matters

ARCM은 단순 UI 모음이 아니라, 반복 사용 가능한 UI 계약을 패키지 단위로 정리한 프로젝트입니다.

src/index.tsx에서 42개의 AComponents 계열 export와 hooks, network helper, utility export를 관리합니다.
BEditor는 Tiptap 기반 에디터를 React 컴포넌트 API로 감싸고, controlled HTML sync, sanitizer, media/table overlay, keyboard/focus flow를 함께 다룹니다.
vite.config.ts는 library build, declaration output, CSS injection, React externalization, Storybook 분기 설정을 포함합니다.
scripts/check-beditor-browser.mjs와 scripts/verify-dist.mjs로 브라우저 smoke와 배포 산출물 검증을 분리했습니다.

Public API Surface

src/index.tsx 기준 공개 API는 크게 네 영역입니다.

영역	대표 export
Foundation	`ABase`, `AWrap`, `ATheme`, `AResource`, `ATypes`
Form controls	`AButton`, `AIconButton`, `AInput`, `ANumInput`, `ACheckBox`, `ASelect`, `AMultiSelect`, `ARadioSelect`, `ASwitch`, `ADatePicker`, `ADateRangePicker`
Data and layout	`ATable`, `ATree`, `AListView`, `ATab`, `ASpace`, `AFrame`, `AFloatMenu`, `AProgressBar`
Feedback and overlay	`ADialog`, `ADrawer`, `AToast`, `ATooltip`, `ALoadingBorder`, `AFileBox`, `AFileUploader`
Editor	`BEditor`, `AEditor`
Hooks and utilities	`useValues`, `useDB`, `useEvent`, `useInit`, `APIContext`, date/file/object/string/table/tree helpers

BEditor Spotlight

BEditor는 이 프로젝트의 가장 복잡한 포트폴리오 포인트입니다. 단일 입력 컴포넌트처럼 보이지만 내부에서는 에디터 런타임, HTML 정규화, table/media interaction, portal focus, browser smoke 검증까지 다룹니다.

Capability Matrix

기능	구현 신호
렌더 타입	`type: "Primary" \| "ReadOnly" \| "Raw" \| "Error"`
툴바 타입	`toolbarType: "Default" \| "Title"`
값 동기화	`useValue`, `valueSyncMode: "immediate" \| "deferred"`, `deferredSyncMs`
외부 제어	`editorRef`로 `focus`, `blur`, `copyContent`, `getEditor()` 제공. HTML/text/length 조회는 `getEditor()` adapter에서 수행
콘텐츠 안전 경계	DOMPurify 기반 display/input sanitizer, link/image/video URL sanitizer
미디어	이미지, data image, YouTube/Vimeo embed URL 처리, resize overlay
테이블	selection, resize, clipboard, command menu, gap insertion, keyboard flow
접근성/포커스	textbox role/name, portal focus ownership, toolbar/table/media keyboard flow
검증	unit tests, Storybook scenario, Chromium/CDP browser smoke

근거 파일:

Architecture

flowchart LR
  App["Consumer app"] --> Entry["src/index.tsx"]
  Entry --> Components["AComponents exports"]
  Entry --> Hooks["AHooks"]
  Entry --> Utils["AUtils / ANetwork"]
  Components --> BEditor["BEditor"]
  BEditor --> Runtime["Tiptap runtime"]
  BEditor --> Value["HTML normalize / sanitize / sync"]
  BEditor --> Overlays["Toolbar / table / media / fullscreen overlays"]
  Runtime --> Tests["Vitest + browser smoke"]
  Value --> Tests
  Overlays --> Tests
  Entry --> Build["Vite library build"]
  Build --> Dist["dist/index.es.js / index.cjs / index.d.ts"]

Package Boundary

Public package entry는 src/index.tsx 하나로 모읍니다.
BEditor 내부 모듈은 기본적으로 implementation detail로 취급합니다.
vite-plugin-dts은 tests, stories, playground, smoke declaration이 배포 산출물에 섞이지 않도록 exclude합니다.
scripts/verify-dist.mjs는 dist/index.es.js, dist/index.cjs, dist/index.d.ts 존재와 비런타임 declaration 누출을 검사합니다.

BEditor Data Flow

Component props에서 mode, size, limit, toolbar, read-only/raw 상태를 해석합니다.
외부 HTML value는 sanitizer와 normalizer를 거쳐 editor runtime에 들어갑니다.
Tiptap editor update는 문서 크기와 sync mode에 따라 immediate 또는 deferred path로 parent state에 반영됩니다.
Table, media, toolbar, fullscreen UI는 portal/overlay로 분리하고 focus ownership을 별도 관리합니다.
Read-only/raw 출력은 display sanitizer를 다시 통과합니다.

Quick Start

Local Development

npm install
npm run dev

Vite dev server 기본 포트는 3030입니다.

Storybook

npm run storybook

Storybook은 현재 BEditor 중심 시나리오를 제공합니다.

Consumer Example

import { useState } from 'react';
import { AButton, BEditor } from 'ados-rcm';

export function EditorExample() {
  const [html, setHtml] = useState('<p>Initial content</p>');

  return (
    <section>
      <BEditor
        label="Content"
        maxLength={5000}
        placeholder="Write rich content"
        toolbarType="Default"
        useValue={[html, setHtml]}
        valueSyncMode="deferred"
      />

      <AButton type="Primary">Save</AButton>
    </section>
  );
}

Quality Gates

목적	명령
TypeScript 검증	`npx tsc --noEmit`
Lint	`npm run lint`
자동 정리	`npm run lint:fix`
Unit tests	`npx vitest run`
BEditor unit scope	`npx vitest run src/AModule/AComponents/BEditor/tests`
Storybook	`npm run storybook`
Storybook build	`npm run build-storybook`
BEditor browser smoke	`npm run check:beditor-browser`
Release artifact check	`npm run build` (`verify:dist` 포함)

현재 저장소에는 66개의 *.test.ts(x) 파일이 있지만 package.json에 별도 npm test script는 없습니다. 그래서 테스트 실행은 npx vitest run을 직접 사용합니다.

Browser Smoke Coverage

npm run check:beditor-browser는 dependency-light Chromium/CDP smoke gate입니다. 주요 확인 범위는 다음과 같습니다.

BEditor playground render와 sample media load
editable textbox role/name/multiline contract
toolbar button target size
portal picker Tab, Shift+Tab, Escape flow
link tooltip focus chrome과 focus return
table picker grid와 roving focus
media overlay keyboard entry, resize/delete ownership, Escape recovery
root editor resizer ARIA/keyboard behavior
table menu disabled reason, Shift+F10, Escape flow

자세한 유지보수 기준은 BEditor Architecture에 정리되어 있습니다.

Portfolio Review Guide

채용 리뷰어에게 보여줄 때는 아래 순서가 가장 효과적입니다.

src/index.tsx에서 공개 API 범위 확인
BEditor.tsx와 core/types.ts로 컴포넌트 API 설계 확인
core/value.ts와 media/media.ts로 sanitizer와 trust boundary 확인
ARCHITECTURE.md로 고위험 변경 영역과 검증 기준 확인
scripts/check-beditor-browser.mjs로 실제 브라우저 smoke 흐름 확인

Honest Gaps

포트폴리오에서는 강점만큼 현재 한계도 명확히 설명하는 편이 신뢰도가 높습니다.

npm test script가 없어 Vitest는 npx vitest run으로 직접 실행해야 합니다.
Storybook은 현재 BEditor 중심입니다. 전체 컴포넌트 카탈로그로 확장할 여지가 있습니다.
성능 수치나 운영 서비스 adoption 수치는 README에 넣지 않았습니다. 저장소 내 실측 근거가 없기 때문입니다.
접근성은 keyboard/focus handling과 browser smoke가 존재하지만, README에서는 WCAG 준수처럼 과장하지 않았습니다.

License

MIT. 자세한 라이선스 파일이 필요하면 package.json의 license 값을 기준으로 별도 LICENSE 파일을 추가하세요.