@luna-oss/primitives

Headless behavior layer of Moon V5. Wraps React Aria Components and Floating UI v0.27 to give downstream @luna-oss/ui styled components a consistent, accessibility-first foundation.

What lives here

This package owns the behavior of UI primitives — focus management, keyboard handling, ARIA wiring, locale, dismiss/focus-trap semantics, and the shared live region. It deliberately ships no styles. Styled components in @luna-oss/ui compose these hooks and headless components to render their own visuals.

Installation

npm install @luna-oss/primitives

Quick start

import { MoonProvider } from "@luna-oss/primitives/provider";
import { Button } from "@luna-oss/primitives/button";

export function App() {
  return (
    <MoonProvider theme="light" density="comfortable" locale="en-US">
      <Button onPress={() => console.log("pressed")}>Click me</Button>
    </MoonProvider>
  );
}

Subpath exports

| Subpath | Purpose | | -------------------------------- | ----------------------------------------------- | | @luna-oss/primitives | Everything (re-exports all subpaths) | | @luna-oss/primitives/provider | MoonProvider, useMoonContext, setMoonTheme| | @luna-oss/primitives/button | useButton hook + headless Button | | @luna-oss/primitives/floating | Floating UI wrappers with Moon defaults | | @luna-oss/primitives/live-announcer | LiveAnnouncer + announce() |

Design principles

• Accessibility-first. All interactive primitives wrap React Aria so keyboard, screen reader, and reduced-motion behavior is correct by default.
• Headless. No CSS, no themes, no visual decisions. The styled @luna-oss/ui package layers presentation on top.
• Composable. Every behavior surface is exposed both as a hook (for max flexibility) and as a thin component (for ergonomic defaults).
• Strict TypeScript. Strict-mode-compatible end to end.

License

MIT © luna-oss.dev