Twenty Front Reusable Patterns

packages/twenty-front/src/modules에서 재사용 가능한 구현 패턴을 카테고리별로 정리한다.

각 문서는 기본적으로 두 단계만 가진다.

1. 모듈 코드
2. 사용 예제

Global Managers

• Context-backed Imperative File Upload: hidden file input을 전역 파일 선택기처럼 여는 패턴.
• Queued Dialog Manager: dialog queue를 manager가 렌더링하고 caller는 enqueue만 하는 패턴.
• Queued Snack Bar Manager: snackbar queue를 provider가 렌더링하고 caller는 variant별 enqueue만 하는 패턴.
• Instance-scoped Modal: modalInstanceId로 modal open state를 분리하는 패턴.

State Context

• Component Instance State: 같은 atom state를 instanceId별로 격리하는 패턴.
• Required Context Provider Hook: Provider와 useXxxOrThrow hook을 함께 만드는 패턴.
• Field Context Injection: record field metadata/update hook을 하위 input/display에 주입하는 패턴.
• Command Menu Context Filtering: 현재 화면 context로 command menu item을 필터링하는 패턴.

Record UI

• Field Meta-Type Router: field metadata type guard로 display/input 컴포넌트를 선택하는 패턴.
• Inline Cell Edit Lifecycle: display/edit 전환과 persist/close/focus 복귀를 cell shell에 모으는 패턴.
• Anchored Portal Field Editor: record cell anchor 위치에 field editor를 portal로 렌더링하는 패턴.
• Junction Relation Resolver: many-to-many relation metadata를 picker/display/update용 junction config로 바꾸는 패턴.

Filter Metadata

• Advanced Filter Builder Pipeline: field/sub-field/relation target 선택을 advanced RecordFilter로 정규화하는 패턴.
• Object Filter Dropdown Operand Pipeline: operand와 typed value input을 dropdown state 기반 RecordFilter upsert로 연결하는 패턴.
• Object Metadata Selector Formatter Hooks: raw object/field metadata를 select, field definition, filter UI contract로 변환하는 패턴.
• Column Definition From Metadata: readable field metadata를 table column definition과 filter/sort capability로 변환하는 패턴.

Interactions

• Instance-scoped Dropdown: dropdownId로 dropdown open/focus state를 분리하는 패턴.
• Click Outside Listener: document-level pointer event를 안전한 outside click callback으로 바꾸는 패턴.
• Global Hotkeys: focus stack 설정을 통과한 hotkey만 실행하는 패턴.
• Drag Drop Context Adapter: dnd-kit 이벤트를 앱의 drop result 모델로 바꾸는 패턴.

Focus State

• Focus Stack Push/Remove: focus 대상 UI를 stack top으로 올리고 닫힐 때 제거하는 패턴.
• Current Focus Selectors: focus stack top에서 current focus id/item/hotkey config를 파생하는 패턴.
• Focus-Gated Global Hotkey Config: 현재 focus item의 config로 전역 hotkey 실행 여부를 제어하는 패턴.
• Reset Focus Stack To Item: UI 전환 후 focus stack을 하나의 기준 item으로 재초기화하는 패턴.

UI Primitives

• Selectable List With Hotkeys: list instance가 arrow navigation state를 갖고 item이 Enter action을 제공하는 패턴.
• Tab List Hidden Measurement: hidden layer에서 실제 tab widths를 측정해 visible/overflow tabs를 나누는 패턴.
• Resizable Panel Pointer Drag: document-level pointer tracking으로 panel width를 preview하고 release 때 commit하는 패턴.
• Expandable List Overflow Dropdown: inline overflow child를 +N chip과 floating dropdown으로 전환하는 패턴.

Data Operations

• Direct File Upload Pipeline: create target, PUT upload, complete mutation을 하나의 hook으로 묶는 패턴.
• Object Record CRUD Hook: object metadata 기반 GraphQL mutation, optimistic cache, store update를 감싸는 패턴.
• Generated GraphQL Fields: runtime metadata로 GraphQL selection set과 operation document를 만드는 패턴.
• Optimistic Record Effects: create/update/delete 결과를 Apollo connection cache와 record store에 즉시 반영하는 패턴.
• Apollo Record Cache Wrappers: metadata 기반 fragment read/write/cache modify를 helper로 감싸는 패턴.

Settings Integrations

• Billing Plan/Price Selector Hooks: billing catalog query를 plan/price selector hook으로 재사용하는 패턴.
• Stripe Promise/Payment Flow: Stripe promise memoization과 Elements payment/setup intent submit을 묶는 패턴.
• Provider Reconnect OAuth Trigger: connected account provider별 reconnect route/OAuth redirect를 분기하는 패턴.
• Data Model Select Option Bulk Parser: select options와 bulk textarea text를 metadata 보존 방식으로 변환하는 패턴.

Record Data Loading

• Generic Find Many Query Hook: metadata 기반 list query, cursor state, fetchMore를 하나의 hook으로 묶는 패턴.
• Lazy Query Pagination Fetch More: lazy query로 첫 페이지를 시작하고 cursor 기반 fetchMore로 이어가는 패턴.
• Record Table Virtualization Data Loader: virtual row slot과 real index map을 분리해 필요한 page만 로드하는 패턴.
• Aggregate Records Query: field aggregate 요청을 generated GraphQL aggregate query와 display state로 연결하는 패턴.

Timeline Activity

• Timeline Activity Type Filter: active type과 record별 selected type을 합쳐 activity filter로 적용하는 패턴.
• Timeline Events Month Grouping: flat timeline events를 렌더링 직전에 month group으로 바꾸는 패턴.
• Dynamic Timeline Activity Renderer: 기본 row 위에 standard/front component detail renderer를 선택적으로 붙이는 패턴.
• Field Diff Value Renderer: diff 값을 artificial record store에 넣고 기존 FieldDisplay로 표시하는 패턴.

View Layout State

• View Filter/Sort Apply-Save Pipeline: persisted view filter/sort와 현재 화면 filter/sort state를 적용, 비교, 저장하는 패턴.
• Page Layout Draft-To-Persist Pipeline: page layout draft를 edit state로 다루고 save/reset 시 persisted snapshot과 동기화하는 패턴.
• Layout Customization Dirty/Save/Cancel Flow: navigation, command menu, page layout customization draft를 한 save/cancel flow로 묶는 패턴.

Sync Effects

• Browser Event Listener: CustomEvent dispatch/listen을 typed hook과 feature filter로 감싸는 패턴.
• SSE Event To Optimistic Effect: SSE payload를 optimistic cache update와 browser event broadcast로 분기하는 패턴.
• Metadata Store Bootstrap Refresh: persisted metadata hash를 비교해 stale entity만 refresh하고 ready gate를 여는 패턴.

App Bootstrap Runtime

• Captcha Script Gated Provider: captcha가 필요한 route에서만 외부 script와 token refresh를 붙이는 패턴.
• Client Config Error Gate Provider: client config fetch 실패를 앱 공통 full-screen error gate로 처리하는 패턴.
• Auth Session Cross-tab Effects: sign-out broadcast와 pending server sign-out retry를 부트스트랩 effect로 묶는 패턴.
• Front Component Runtime Bridge: database-backed front component runtime에 host API, token, context를 주입하는 패턴.

AI Runtime

• Agent Chat Runtime Effects: AI chat이 열린 뒤에만 fetch, stream, preprompt, keepalive effect를 붙이는 패턴.
• Streaming Parts Diff Sync: incoming stream message를 diff한 뒤 변경된 part side effect만 실행하는 패턴.
• Chat Thread URL/Selection Sync: thread 선택을 state, draft, URL, side-panel navigation에 함께 반영하는 패턴.
• Dictation Availability/Event Emitter: Web Speech capability gate와 emitter 기반 dictation engine lifecycle 패턴.

Activity Composer

• Email Recipient Parse/Merge/Serialize Pipeline: free text와 chips를 같은 email recipient 배열 모델로 정규화하는 패턴.
• Email Composer State Hook: sender, recipients, body, attachments, validation, send action을 하나의 hook contract로 묶는 패턴.
• Calendar Event Composer Date Transitions: timed/all-day 전환과 start/end 변경을 valid date range로 유지하는 패턴.
• Activity Target Related Record Actions: record context용 task/note/file/email/calendar action을 같은 binding contract로 수집하는 패턴.

Spreadsheet Workflows

• Spreadsheet Import Workflow: upload부터 submit까지 step state로 import wizard를 연결하는 패턴.
• Spreadsheet Column Auto-Match: imported headers를 fields에 fuzzy match하고 mapping state에 반영하는 패턴.
• Spreadsheet Validation Pipeline: row/table hooks와 field validations로 imported rows를 검증하는 패턴.
• Object Records Spreadsheet Adapter: generic importer를 object metadata와 batch create mutation에 연결하는 패턴.

Routing Navigation

• Side Panel Routed Page Navigation: 일반 route path를 side panel navigation stack item으로 열고 내부 navigation도 같은 stack으로 이어가는 패턴.
• Navigation Mode Switcher: route-owned mode와 memorized tab state를 조합해 navigation drawer mode를 전환하는 패턴.

Navigation Menu Patterns

• Navigation Menu Tree Filter/Sort: raw navigation items를 readable tree display list로 바꾸는 패턴.
• Navigation Menu DnD Reorder Position: dnd-kit target을 folder destination과 사이 position update로 바꾸는 패턴.
• Navigation Menu Draft Save Pipeline: workspace navigation draft를 save 시 create/delete/recreate/update diff로 저장하는 패턴.
• Add-To-Navigation Drop Handler: 외부 draggable payload를 navigation draft item과 edit side panel로 연결하는 패턴.

Workflow Patterns

• Workflow Diagram Generation: workflow trigger/steps를 React Flow nodes/edges로 변환하는 패턴.
• Workflow Step Mutation Facade: step/edge 변경 mutation과 local flow/cache sync를 UI용 API로 감싸는 패턴.
• Workflow Run Action Hooks: run/stop/retry mutation 주변의 optimistic cache, SSE, browser event, side panel side effect를 hook에 모으는 패턴.
• Step Output Schema Computation: step settings와 object metadata를 variable picker용 output schema로 계산하고 cache하는 패턴.