How unovue/reka-ui works
1. What this repo is
- Reka UI is a Vue 3 component library monorepo centered on accessible, headless UI primitives.
- The repository is organized so one source of truth in packages/core feeds the published package, the docs site, demo stories, and playground apps.
2. Core product package
- packages/core is the main library package (reka-ui on npm).
- It contains one folder per component or primitive, each typically with:
- Vue SFCs for the public parts
- an index.ts barrel export
- tests
- story/demo files
- This is the subsystem that actually implements the UI behaviors consumed by end users.
3. Component architecture pattern
- Most components follow a compound-component pattern: root, trigger, content, item, portal, overlay, etc.
- Examples include Dialog, Popover, Select, Tabs, Tooltip, Accordion, DropdownMenu, Calendar, and many others.
- The library exposes small composable parts rather than monolithic widgets, which matters for diagramming because consumers assemble behavior from multiple exported pieces.
4. Shared foundations / primitives
- packages/core/src/shared, Primitive, FocusScope, Presence, Teleport, DismissableLayer, Popper, RovingFocus, and Collection form the lower-level infrastructure layer.
- These modules provide reusable mechanics such as:
- focus management
- dismiss/outside-click handling
- portal/teleport behavior
- presence/animation mounting
- positioning and arrow/popup layout
- keyboard navigation and roving focus
- Many higher-level components depend on these rather than reimplementing interaction logic.
5. State, context, and cross-component coordination
- The codebase relies heavily on context propagation and composables (createContext, use* helpers) to coordinate nested parts.
- This is how roots communicate with children like triggers, content, items, and providers without prop-drilling.
- ConfigProvider, useDirection, useLocale, useId, useForwardProps, useEmitAsProps, and similar helpers support consistent behavior across all components.
6. Date, time, and calendar subsystem
- A large portion of the library is dedicated to date/time controls: DateField, DatePicker, DateRangePicker, MonthPicker, YearPicker, TimeField, Calendar, RangeCalendar, etc.
- These share internal date utilities under packages/core/src/date and packages/core/src/shared/date.
- This subsystem is distinct because it combines UI composition with calendar math, locale formatting, parsing, validation, and segmented inputs.
7. Color subsystem
- Color-related primitives live in ColorArea, ColorField, ColorSlider, ColorSwatch, and ColorSwatchPicker.
- Supporting color math lives in shared/color.
- These components are a smaller but separate domain with their own parsing, conversion, and gradient logic.
8. Complex interaction subsystems
- Some components have especially rich internal logic:
- Drawer includes swipe-dismiss behavior, snap points, viewport/overlay coordination, and body-locking.
- Splitter includes layout calculations, persistence, resize handling, and window-level behavior.
- Tree, Listbox, Combobox, Select, and NavigationMenu include filtering, virtualization, and keyboard/typeahead navigation.
- These are not just visual components; they coordinate DOM, input events, and layout state.
9. Testing and verification
- Each component area has tests under *.test.ts, plus snapshots where needed.
- The repo uses Vitest for unit/component testing.
- Story files under each component’s story folder act as executable examples and often cover variants, edge cases, and visual regressions.
10. Story/demo authoring layer
- docs/components/demo and the story folders in packages/core are the primary authored example layers.
- Histoire is configured in .histoire and is used for component exploration/stories.
- These demos are not the same as docs pages; they are a separate presentation layer for interactive component scenarios.
11. Documentation site
- docs is a VitePress site that serves the public documentation at reka-ui.com.
- It contains:
- markdown content under docs/content
- custom Vue components under docs/.vitepress/components
- layout/theme/config files under docs/.vitepress
- generated metadata and example data helpers
- The docs site is a consumer of the library package and a presentation layer over the same components and examples.
12. Docs content pipeline
- The docs tree includes large meta and components content collections for individual API pages and usage examples.
- Scripts in docs/scripts and functions under docs/.vitepress/functions suggest generation/aggregation of docs data, contributor lists, examples, and caches.
- That means some docs pages are static markdown, while others are assembled from structured metadata and component demos.
13. Plugin package
- packages/plugins is a separate package that provides integration tooling:
- a resolver
- Nuxt integration
- namespaced component generation
- This package matters architecturally because it sits between the core library and framework consumers, enabling auto-imports and framework-friendly integration.
14. Playgrounds
- playground/vue3 and playground/nuxt are consumer apps used to validate real-world usage.
- They demonstrate the library in a plain Vue 3 app and a Nuxt app, respectively.
- These are external-consumer mirrors: they depend on the published package behavior rather than internal docs/test harnesses.
15. Build, release, and repo boundaries
- The repo is managed as a pnpm workspace with multiple packages and apps.
- GitHub Actions in .github/workflows handle build, release, publish, and checks like typo validation.
- The important architectural boundary is:
- packages/core = runtime UI library
- packages/plugins = integration tooling
- docs/.histoire = documentation and demo surfaces
- playground/* = consumer validation apps
- For a diagram, the main data flow is: core source → package build/export → docs/stories/playgrounds consume it, with tests and CI validating each layer.
Main entry points: index.ts Package entry · build.yaml CI & release · shared Infrastructure · Select Inputs
Components 20
Core library
Main Vue 3 UI primitives and shared foundations.
- Package entry · Top-level entrypoints that aggregate the library package.
packages/core/src/index.ts - Accordion · Representative disclosure-style component built from root/item/trigger/content parts.
packages/core/src/Accordion - Overlays · Dialog, Popover, Tooltip, HoverCard, DropdownMenu, ContextMenu, Menubar, and related layered interactions.
packages/core/src/Dialog - Inputs · Editable, Select, Combobox, Listbox, TagsInput, NumberField, PinInput, Toggle, RadioGroup, Checkbox, Switch, Slider, Progress.
packages/core/src/Select - Dates · Date, time, calendar, range, and segmented-input components with shared date math and locale handling.
packages/core/src/DatePicker - Color · Color picker primitives, swatches, sliders, and shared color conversion logic.
packages/core/src/ColorArea - Layout · Splitter, ScrollArea, Tabs, Separator, Toolbar, NavigationMenu, Pagination, Stepper, and related structural components.
packages/core/src/Splitter - Collections · Tree, RovingFocus, Collection, and other navigable collection patterns with virtualization support.
packages/core/src/Tree - Infrastructure · Primitive, Slot, FocusScope, Presence, Teleport, DismissableLayer, Popper, RovingFocus, Collection, and shared utilities.
packages/core/src/shared - Context helpers · createContext, useId, useLocale, useDirection, forwarding helpers, and cross-component coordination utilities.
packages/core/src/shared/createContext.ts - Date utils · Shared calendar/date parsing, formatting, comparison, and segment utilities used by date components.
packages/core/src/shared/date - Color math · Color parsing, conversion, gradients, and related utility functions.
packages/core/src/shared/color
Docs & demos
VitePress docs, Histoire stories, and authored examples.
- Docs site · Public documentation site, page content, theme components, and generated docs data.
docs/.vitepress/config.ts - Demos · Interactive demo components and authored examples used by docs and story surfaces.
docs/components/demo - Histoire · Component exploration and story authoring environment configured in the Histoire workspace.
.histoire/vite.config.ts
Integration
Framework tooling and consumer playground apps.
- Plugins · Resolver, Nuxt integration, and namespaced component generation for framework consumers.
packages/plugins/src/nuxt/index.ts - Vue playground · Plain Vue 3 playground that exercises the published package in a real app shell.
playground/vue3/src/main.ts - Nuxt playground · Nuxt playground used to validate framework integration and auto-import behavior.
playground/nuxt/nuxt.config.ts
Ops
Workspace, testing, and release automation.
- Vitest · Unit, component, and snapshot tests validating library behavior.
packages/core/vitest.setup.ts - CI & release · Workspace management, GitHub Actions, build, publish, release, and repo checks.
.github/workflows/build.yaml
Connections 29
- Package entry → Accordion: exports · Public package entry exports component modules.
- Package entry → Overlays: exports · Exports layered overlay primitives and menus.
- Package entry → Inputs: exports · Exports form and control primitives.
- Package entry → Dates: exports · Exports date, time, and calendar components.
- Package entry → Color: exports · Exports color-related primitives.
- Package entry → Layout: exports · Exports structural and navigation components.
- Package entry → Collections: exports · Exports collection and navigation primitives.
- Accordion → Infrastructure: uses · Component behavior is built on shared primitives and interaction mechanics.
- Overlays → Infrastructure: uses · Overlay systems depend on focus, portal, presence, dismiss, and popper infrastructure.
- Inputs → Context helpers: uses · Parts coordinate through context and composable helpers.
- Inputs → Infrastructure: uses · Keyboard navigation, presence, and primitive rendering are reused here.
- Dates → Date utils: uses · Calendar and time controls share date math, parsing, and locale formatting.
- Dates → Context helpers: uses · Date roots and segmented inputs coordinate state via context.
- Color → Color math: uses · Color pickers and swatches rely on shared color conversion and gradient logic.
- Layout → Infrastructure: uses · Navigation and layout primitives use shared focus, scroll, and positioning utilities.
- Collections → Infrastructure: uses · Virtualized and navigable collections depend on shared collection and roving focus behavior.
- Docs site → Package entry: consumes · Docs pages render the published library package.
- Docs site → Demos: embeds · Docs pages assemble interactive demos and component examples.
- Histoire → Package entry: renders · Story stories import and exercise component APIs from source/package.
- Histoire → Demos: shares examples · Story and docs demo layers reuse authored example patterns.
- Plugins → Package entry: integrates · Framework tooling targets the core component exports.
- Vue playground → Package entry: consumes · Vue playground validates real consumer usage of the package.
- Nuxt playground → Plugins: uses · Nuxt playground validates plugin-based integration and auto-imports.
- Nuxt playground → Package entry: consumes · Also exercises the published UI package directly.
- CI & release → Vitest: validates · CI runs unit/component tests and repository checks.
- CI & release → Docs site: builds · CI builds and publishes the documentation site.
- CI & release → Plugins: releases · CI publishes or validates package release artifacts.
- CI & release → Vue playground: checks · Consumer apps are part of workspace verification.
- CI & release → Nuxt playground: checks · Consumer apps are part of workspace verification.