open-index/open-npm huggingface dataset:
npm package: @ryvora/number
Description: A collection of number utilities for JavaScript/TypeScript.
Latest version: 2.0.0

# @ryvora/number 🔢

Hello Number Cruncher! 🧮

The `@ryvora/number` package provides handy utilities for working with numbers in JavaScript/TypeScript. Perfect for math helpers, value clamping, and more.

It's like having a math assistant for your code!

## Why would you need this?

- Clamp values within a range
- Build UI components that need numeric constraints
- Simplify math operations in your codebase

## How it Works (Typically):

It provides a `clamp` function to restrict a number within a given range.

## Basic Usage

```ts
import { clamp } from '@ryvora/number';

const value = clamp(15, [0, 10]); // value === 10
```

Keep your numbers in check and your logic clean! ✨

## Installation

```sh
pnpm add @ryvora/number
```

## License

MIT
npm package: @ryvora/primitive
Description: Low-level utility functions and types for building robust JavaScript/TypeScript libraries.
Latest version: 2.0.0

# @ryvora/primitive 🛠️

Hello Abstraction Builder! 🧩

The `@ryvora/primitive` package offers foundational utilities for composing event handlers and building robust abstractions in JavaScript/TypeScript libraries.

It's like having a reliable toolkit for your event logic!

## Why would you need this?

- Compose multiple event handlers safely
- Prevent default event propagation when needed
- Build reusable, low-level utilities for UI libraries

## How it Works (Typically):

It provides a function to combine event handlers, ensuring your logic runs only when appropriate.

## Basic Usage

```ts
import { composeEventHandlers } from '@ryvora/primitive';

const handleClick = composeEventHandlers(
  (event) => console.log('User handler', event),
  (event) => console.log('Library handler', event)
);

// Use handleClick as your event handler
```

Build your abstractions on a solid foundation! 🏗️

## License

MIT
npm package: @ryvora/react-arrow
Description: 🏹 A fun and flexible arrow component for tooltips, popovers, and dropdowns! Points the way in your UI.
Latest version: 2.0.0

# Arrow 🏹

Hey there, UI adventurer! 👋

This nifty little module, `arrow`, is all about helping you point things out! 🎯 It's used to create those cool little arrow/triangle thingies that you often see on tooltips, popovers, or dropdown menus, indicating what they're attached to.

Think of it as your UI's personal GPS, always showing the way! 🗺️

## Basic Usage

```tsx
import { Arrow } from '@ryvora/react-arrow'; // (Assuming this is how you'd import it)
import * as Popover from '@ryvora/react-popover'; // Or any other component that uses an arrow

function MyPopover() {
  return (
    <Popover.Root>
      <Popover.Trigger>My Trigger</Popover.Trigger>
      <Popover.Content>
        Hello, I'm a popover!
        <Popover.Arrow asChild>
          <Arrow />
        </Popover.Arrow>
      </Popover.Content>
    </Popover.Root>
  );
}
```

Isn't that neat? ✨ Now go forth and point with style!
npm package: @ryvora/react-collection
Description: 📚 Manage and query collections of items in your UI! Perfect for dropdowns, selects, and more.
Latest version: 2.0.0

# Collection 📚

Well hello there, data wrangler! 🤠

The `collection` module is your go-to buddy for managing a... well, a collection of items! 🧺 It's super handy when you have a list of things (like in a dropdown menu or a select component) and you need to keep track of them, navigate through them, or query them.

It helps turn a chaotic bunch of items into an orderly lineup! 🚶‍♂️🚶‍♀️🚶

## Core Idea

Imagine you have a list of selectable items. This module helps to:

- Register each item.
- Allow querying for items (e.g., find the first, last, or an item by its value).
- Facilitate keyboard navigation between items.

It's the librarian for your UI components! 🤫

## Simplified Usage Example (Conceptual)

```tsx
// Inside a component like Select or DropdownMenu
import { createCollection } from '@ryvora/react-collection';

const [Collection, useCollection, createCollectionScope] = createCollection<ItemElement, ItemData>();

// In your main component (e.g., Select)
<Collection.Provider scope={scope}>
  {/* Items will register themselves here */}
  {children}
</Collection.Provider>

// In your item component (e.g., SelectItem)
<Collection.Slot scope={scope}>
  <Primitive.div ref={itemRef}>{/* ... */}</Primitive.div>
</Collection.Slot>

// To get items
const getItems = useCollection(scope);
const allItems = getItems();
```

Organize all the things! 🧹
npm package: @ryvora/react-compose-refs
Description: 🔗 Compose multiple refs into one! The ultimate utility for advanced React ref management.
Latest version: 2.0.0

# Compose Refs 🔗

Greetings, Ref Master! 🧙‍♂️

Ever found yourself in a tricky situation where you need to attach _multiple_ refs to a single React component? 🤔 The `compose-refs` module is here to save the day! It elegantly merges multiple refs into a single ref callback that you can pass to your component.

It's like a Voltron for your refs, combining their powers! 🤖

## Why, though?

Sometimes you have a `forwardedRef` from a parent, and you _also_ need an internal ref to the same DOM element for measurements or imperative calls. This module makes that clean and easy.

## Basic Usage

```tsx
import { useComposedRefs } from '@ryvora/react-compose-refs';
import React, { useRef } from 'react';

const MyComponent = React.forwardRef((props, forwardedRef) => {
  const internalRef = useRef<HTMLDivElement>(null);
  const composedRefs = useComposedRefs(forwardedRef, internalRef);

  // Now, if forwardedRef exists, it will be updated.
  // And internalRef will also point to the div!

  return <div ref={composedRefs}>Hello!</div>;
});
```

Ref-tastic! 💫 Keep those refs in check!
npm package: @ryvora/react-context
Description: 🌐 Create scoped React contexts for complex component trees. No more context cross-talk!
Latest version: 2.0.0

# Context createContextScope 🌐

Hey Context Connoisseur! 🧐

The `context` module, especially with `createContextScope`, is your secret weapon for taming React's Context API in complex component systems. It helps you create scoped contexts, preventing annoying cross-talk between different instances of the same component tree.

Think of it as creating private communication channels for your component families! 👨‍👩‍👧‍👦

## The Problem it Solves

Imagine multiple `DropdownMenu` components on a page. Without scoped context, the `DropdownMenuContent` of one menu might accidentally listen to the state of a _different_ `DropdownMenuTrigger`. Chaos! 😱 `createContextScope` ensures each family talks only to itself.

## Basic Idea

```tsx
import { createContextScope } from '@ryvora/react-context';

const [createMyComponentContext, createMyComponentScope] = createContextScope('MyComponent');

// Then you define your context type and use it:
interface MyContextValue {
  /* ... */
}
const [MyContextProvider, useMyContext] = createMyComponentContext<MyContextValue>('MyComponent');

// In your component:
// <MyContextProvider scope={__scopeMyComponent} value={...}>
// const context = useMyContext('MySubComponent', __scopeMyComponent);
```

It's all about keeping things neat and tidy in their own little worlds. 🌍✨
npm package: @ryvora/react-dialog
Description: 💬 Accessible, composable dialog/modal component for React. Focus management, ARIA, and more!
Latest version: 2.0.0

# Dialog 💬

Hello, Interaction Designer! 🎨

The `dialog` module is your go-to for creating accessible and robust dialog windows (also known as modals). It handles all the tricky bits like focus trapping, ARIA attributes, and overlay behavior, so you can focus on making your dialogs look great! 🤩

It's like a well-behaved pop-up that plays by all the accessibility rules! правила (pravila - rules in Russian, for fun) 🧐

## Features

- ✅ Accessible (ARIA attributes, focus management)
- 🚪 Modal and non-modal (though typically modal)
- 🎬 Can be animated with `@ryvora/react-presence`
- 🧩 Composable: `Dialog.Trigger`, `Dialog.Portal`, `Dialog.Overlay`, `Dialog.Content`, `Dialog.Title`, `Dialog.Description`, `Dialog.Close`

## Basic Usage

```tsx
import * as Dialog from '@ryvora/react-dialog';

function MyDialog() {
  return (
    <Dialog.Root>
      <Dialog.Trigger asChild>
        <button>Open Dialog</button>
      </Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Overlay />
        <Dialog.Content>
          <Dialog.Title>Dialog Title</Dialog.Title>
          <Dialog.Description>This is the description of the dialog.</Dialog.Description>
          <Dialog.Close asChild>
            <button aria-label="Close">X</button>
          </Dialog.Close>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  );
}
```

Time to make some delightful dialogs! ✨
npm package: @ryvora/react-direction
Description: 🧭 Handle text direction (LTR/RTL) for internationalized React UIs. Your UI's compass!
Latest version: 2.0.0

# Direction 🧭

Hey Globetrotter! 🌍

The `direction` module helps your components understand text directionality (Left-to-Right or Right-to-Left). This is super important for internationalization (i18n) and making sure your UI looks and behaves correctly for users all around the world! 🌐

It's like a little compass for your components, telling them which way is "start" and which way is "end"! 🗺️

## How it Works (Usually)

This module typically provides a hook like `useDirection` that consumes a `dir` prop (e.g., from a parent `DirectionProvider` or passed directly). It then returns the current direction, which can be used to conditionally apply styles or logic.

## Conceptual Usage

```tsx
import { useDirection, DirectionProvider } from '@ryvora/react-direction'; // Assuming provider exists

// In your app's root or a specific section
// <DirectionProvider dir="rtl">
//   <App />
// </DirectionProvider>

function MyComponent({ dir: propDir }) {
  const localDir = useDirection(propDir);
  const isRTL = localDir === 'rtl';

  return (
    <div style={{ textAlign: isRTL ? 'right' : 'left' }}>
      {isRTL ? '!dlroW olleH' : 'Hello World!'}
    </div>
  );
}
```

Now your components can speak everyone's language (direction-wise, at least)! 😉
npm package: @ryvora/react-dismissable-layer
Description: 💨 Dismissable layer for popovers, dialogs, and dropdowns. Handles outside clicks, Escape key, and more!
Latest version: 2.0.0

# Dismissable Layer 💨

Ahoy, Escape Artist! Houdini in the house! 🎩🐇

The `dismissable-layer` module is a clever helper for components like popovers, dialogs, or dropdowns. It creates a layer that, when interacted with _outside_ of its content (e.g., clicking outside, pressing the Escape key), can trigger a dismiss action.

It's like an invisible force field that knows when you're trying to leave! 🛡️

## Key Features

- 🖱️ **Pointer Down Outside:** Detects clicks/taps outside the main content.
- ⌨️ **Escape Key:** Listens for the Escape key to dismiss.
- 🧠 **Focus Outside:** Can detect if focus moves outside the layer.
- 🚫 **Disabling Interaction:** Can prevent interaction with elements outside the layer (useful for modals).

## Conceptual Usage

```tsx
import { DismissableLayer } from '@ryvora/react-dismissable-layer';
import React, { useState } from 'react';

function MyPopup() {
  const [isOpen, setIsOpen] = useState(false);

  if (!isOpen) {
    return <button onClick={() => setIsOpen(true)}>Open Popup</button>;
  }

  return (
    <DismissableLayer onDismiss={() => setIsOpen(false)}>
      <div>
        <p>I am a popup! Click outside or press Esc to close me.</p>
        <button onClick={() => setIsOpen(false)}>Close Manually</button>
      </div>
    </DismissableLayer>
  );
}
```

Now you see it, now you don't! ✨ Perfect for those "poof, it's gone!" moments.
npm package: @ryvora/react-dropdown-menu
Description: 🍔 Fully accessible, composable dropdown menu for React. Keyboard navigation, ARIA, and more!
Latest version: 2.0.0

# Dropdown Menu 🍔

Hey Menu Maestro! 👨‍🍳

The `dropdown-menu` module is your recipe for creating fantastic, accessible dropdown menus (sometimes called "hamburger menus" or "context menus"). It builds upon `@ryvora/react-menu` and `@ryvora/react-popper` to give you a fully-featured dropdown experience.

It's like a bento box 🍱 for your actions and links – neat, organized, and delightful!

## What's Cooking?

- ✅ Fully accessible (ARIA, keyboard navigation).
- 📐 Positioned smartly using Popper.
- 🧩 Composable: `DropdownMenu.Trigger`, `DropdownMenu.Portal`, `DropdownMenu.Content`, `DropdownMenu.Item`, `DropdownMenu.CheckboxItem`, `DropdownMenu.RadioGroup`, `DropdownMenu.RadioItem`, `DropdownMenu.Label`, `DropdownMenu.Separator`, `DropdownMenu.Sub` (for nested menus!).
- 💅 Styleable and customizable.

## A Taste of Usage

```tsx
import * as DropdownMenu from '@ryvora/react-dropdown-menu';

function MyAwesomeMenu() {
  return (
    <DropdownMenu.Root>
      <DropdownMenu.Trigger asChild>
        <button>Options</button>
      </DropdownMenu.Trigger>

      <DropdownMenu.Portal>
        <DropdownMenu.Content sideOffset={5}>
          <DropdownMenu.Label>My Menu</DropdownMenu.Label>
          <DropdownMenu.Item onSelect={() => console.log('Cut')}>Cut</DropdownMenu.Item>
          <DropdownMenu.Item onSelect={() => console.log('Copy')}>Copy</DropdownMenu.Item>
          <DropdownMenu.Item onSelect={() => console.log('Paste')} disabled>
            Paste (Disabled)
          </DropdownMenu.Item>
          <DropdownMenu.Arrow />
        </DropdownMenu.Content>
      </DropdownMenu.Portal>
    </DropdownMenu.Root>
  );
}
```

Bon appétit! 🍽️ Serve up some slick menus!
npm package: @ryvora/react-focus-guards
Description: 💂‍♂️ Invisible focus guards for robust focus trapping in modals, dialogs, and more.
Latest version: 2.0.0

# Focus Guards 💂‍♂️

Salutations, Focus Guardian! 🛡️

The `focus-guards` module is a nifty utility, often used internally by other components (like `FocusScope`), to help trap focus within a specific area of your page. It achieves this by adding hidden, focusable elements at the beginning and end of a section.

Think of them as invisible sentinels standing guard at the edges of a focus trap, ensuring the focus doesn't escape! 🏰

## How They Work

When focus tries to leave the "guarded" area by tabbing, it hits one of these guards. The guard then programmatically redirects the focus back into the area (e.g., to the last or first focusable element within the trap).

This is crucial for accessibility in components like modals or dialogs, where focus should remain within the component as long as it's active.

## Conceptual Usage (Usually Internal)

```tsx
import { useFocusGuards } from '@ryvora/react-focus-guards'; // Or a component that uses it

function MyFocusTrappedArea({ children }) {
  // This hook would typically add the guard elements around the children
  // or be part of a <FocusScope> component.
  useFocusGuards();

  return (
    <div>
      {/* FocusGuard at the start (conceptually) */}
      {children}
      {/* FocusGuard at the end (conceptually) */}
    </div>
  );
}
```

Keep that focus on lockdown! 🔒 Your users will thank you!
npm package: @ryvora/react-focus-scope
Description: 🎯 Trap and manage focus within a section of your app. Essential for modals and dialogs!
Latest version: 2.0.0

# Focus Scope 🎯

Greetings, Focus Commander! 🎖️

The `focus-scope` module is a powerful tool for managing focus within a specific section of your application. It's essential for creating accessible modals, dialogs, and other UI elements that need to "trap" focus temporarily.

It's like creating a VIP lounge for keyboard focus – once you're in, you can't easily leave until the party's over! 🥳

## Key Powers

- 🔒 **Focus Trapping:** Keeps the Tab key (and Shift+Tab) cycling within the scope.
- 🚀 **Auto Focus on Mount:** Can automatically focus on a specific element when the scope mounts.
- 🧐 **Restore Focus on Unmount:** Remembers what was focused before the scope became active and restores focus to it when the scope unmounts.
- 💂 **Uses Focus Guards:** Often utilizes `focus-guards` internally for robust trapping.

## Basic Usage

```tsx
import { FocusScope } from '@ryvora/react-focus-scope';
import React, { useState } from 'react';

function MyModal() {
  const [isOpen, setIsOpen] = useState(false);
  const triggerRef = React.useRef<HTMLButtonElement>(null);

  if (!isOpen) {
    return (
      <button ref={triggerRef} onClick={() => setIsOpen(true)}>
        Open Modal
      </button>
    );
  }

  return (
    <FocusScope
      trapped
      onMountAutoFocus={(e) => e.preventDefault()}
      onUnmountAutoFocus={() => triggerRef.current?.focus()}
    >
      <div role="dialog" aria-modal="true">
        <p>I am a modal! Focus is trapped here.</p>
        <input type="text" placeholder="Try tabbing" />
        <button onClick={() => setIsOpen(false)}>Close</button>
      </div>
    </FocusScope>
  );
}
```

Stay focused and build accessible UIs! 🌟
npm package: @ryvora/react-id
Description: 🆔 Generate unique IDs for your React components. Perfect for accessibility and SSR!
Latest version: 2.0.0

# ID Generator 🆔

Hello, Uniqueness Seeker! 🕵️‍♀️

The `id` module, typically providing a `useId` hook, is your trusty assistant for generating unique IDs within your React components. This is incredibly useful for accessibility (a11y) attributes like `aria-labelledby`, `aria-describedby`, or associating labels with form inputs.

It's like a little ID card printer for your components, ensuring everyone has a unique identifier! 💳

## Why is it important?

- **Accessibility:** Many ARIA attributes require ID references to link elements together (e.g., a custom select trigger to its listbox).
- **Server-Side Rendering (SSR):** Ensures that IDs generated on the server match those on the client, preventing hydration mismatches.

## Basic Usage

```tsx
import { useId } from '@ryvora/react-id';

function MyFormControl() {
  const inputId = useId();
  const descriptionId = useId();

  return (
    <div>
      <label htmlFor={inputId}>My Input:</label>
      <input id={inputId} type="text" aria-describedby={descriptionId} />
      <p id={descriptionId}>This is a description for the input.</p>
    </div>
  );
}
```

Keep your components uniquely identified and accessible! ✨
npm package: @ryvora/react-menu
Description: 🍽️ The engine for interactive menus in React. Handles selection, navigation, and open state!
Latest version: 2.0.0

# Menu 🍽️

Welcome, Menu Architect! 🏗️

The `menu` module is a foundational building block for creating interactive menus, like those found in `DropdownMenu`, `ContextMenu`, or `Select` components. It handles the core logic for item selection, keyboard navigation, and managing the open state.

Think of it as the engine ⚙️ that powers various menu-like components, providing the smarts behind the scenes!

## Core Responsibilities

- Managing a collection of menu items.
- Handling keyboard navigation (arrow keys, Home, End, type-ahead).
- Managing item selection and activation.
- Controlling the open/closed state of the menu content.
- Integrating with `@ryvora/react-popper` for positioning.
- Often used with `@ryvora/react-dismissable-layer` for closing behavior.

## Conceptual Structure (How it's typically used by other components)

```tsx
// This is a simplified view, often abstracted by DropdownMenu, Select, etc.
import * as MenuPrimitive from '@ryvora/react-menu';
import * as PopperPrimitive from '@ryvora/react-popper';

function MyCustomMenu() {
  // ... state for open, onOpenChange ...
  return (
    <PopperPrimitive.Root>
      <MenuPrimitive.Root open={isOpen} onOpenChange={setIsOpen}>
        <PopperPrimitive.Anchor asChild>
          <MenuPrimitive.Anchor asChild> {/* Or directly use PopperPrimitive.Anchor */}
            <button>Trigger</button>
          </MenuPrimitive.Anchor>
        </PopperPrimitive.Anchor>

        <MenuPrimitive.Portal>
          <PopperPrimitive.Content>
            <MenuPrimitive.Content>
              <MenuPrimitive.Item onSelect={...}>Item 1</MenuPrimitive.Item>
              <MenuPrimitive.Item onSelect={...}>Item 2</MenuPrimitive.Item>
            </MenuPrimitive.Content>
          </PopperPrimitive.Content>
        </MenuPrimitive.Portal>
      </MenuPrimitive.Root>
    </PopperPrimitive.Root>
  );
}
```

This module is the chef's secret ingredient for delicious interactive menus! 👨‍🍳
npm package: @ryvora/react-popover
Description: 💬🗯️ Delightful popover component for React. Anchored, dismissable, and fully accessible!
Latest version: 2.1.0

# Popover 💬🗯️

Hey there, Popover Pro! 👋

The `popover` module lets you create delightful little pop-up boxes of content that are anchored to a trigger element. Think tooltips, non-modal dialogs, or extra information displays! 💡

It's like a sticky note 🗒️ for your UI elements, providing context without cluttering the main interface.

## Cool Features:

- 🎯 **Anchored Positioning:** Uses `@ryvora/react-popper` to smartly position itself relative to a trigger or a custom anchor.
- 🚪 **Modal/Non-Modal:** Can be configured to be modal (trapping focus, overlay) or non-modal.
- 💨 **Dismissable:** Easily closed by clicking outside, pressing Escape, or via a close button (integrates with `DismissableLayer`).
- 🧩 **Composable API:** `Popover.Root`, `Popover.Trigger`, `Popover.Anchor` (optional), `Popover.Portal`, `Popover.Content`, `Popover.Close`, `Popover.Arrow`.
- 🎬 **Animatable:** Works nicely with `@ryvora/react-presence` for smooth entrances and exits.

## Quick Example:

```tsx
import * as Popover from '@ryvora/react-popover';

function MyInfoPopover() {
  return (
    <Popover.Root>
      <Popover.Trigger asChild>
        <button>More Info</button>
      </Popover.Trigger>
      <Popover.Portal>
        <Popover.Content sideOffset={5}>
          Here's some extra information for you!
          <Popover.Close asChild>
            <button aria-label="Close">X</button>
          </Popover.Close>
          <Popover.Arrow style={{ fill: 'white' }} />
        </Popover.Content>
      </Popover.Portal>
    </Popover.Root>
  );
}
```

Go ahead, make your UI pop with helpful info! ✨
npm package: @ryvora/react-popper
Description: 🎈 Positioning engine for floating UI elements in React. Keeps your popups perfectly placed!
Latest version: 2.0.0

# Popper (Positioning Engine) 🎈

Ahoy, Positioning Pilot! 🚀

The `popper` module (likely a wrapper around a library like Popper.js or a custom implementation) is the unsung hero behind perfectly positioned floating elements like tooltips, dropdown menus, and popovers. It dynamically calculates the best spot for your floating element relative to a reference (anchor) element.

It's like a magical tether that always keeps your floating UI bits in the right place, even when things scroll or resize! 🪄

## What it does:

- 📏 Calculates optimal placement (top, bottom, left, right, with alignments).
- 🔄 Updates position on scroll or resize.
- 🤏 Handles edge detection (prevents going off-screen by flipping or overflowing).
- 🏹 Often provides data for positioning an arrow element.

## Conceptual Usage (Usually by other components like DropdownMenu, Popover, Tooltip):

```tsx
import * as PopperPrimitive from '@ryvora/react-popper'; // Or the specific name used

function MyFloatingComponent() {
  // Refs to the trigger/anchor and the content to be popped
  const triggerRef = React.useRef(null);
  const contentRef = React.useRef(null);

  // Popper hook or component would use these refs and options
  // const { styles, attributes } = usePopper(triggerRef, contentRef, { placement: 'bottom-start' });

  return (
    <PopperPrimitive.Root>
      {' '}
      {/* Manages Popper instance */}
      <PopperPrimitive.Anchor ref={triggerRef} asChild>
        <button>I am the Anchor</button>
      </PopperPrimitive.Anchor>
      {/* Portal is often used here */}
      <PopperPrimitive.Content ref={contentRef} sideOffset={5} align="start">
        <div>I am the Popper Content!</div>
        <PopperPrimitive.Arrow /> {/* Optional arrow */}
      </PopperPrimitive.Content>
    </PopperPrimitive.Root>
  );
}
```

Keep your UIs perfectly poised and positioned! ✨
npm package: @ryvora/react-portal
Description: 🚪✨ Render React components outside their parent DOM hierarchy. Perfect for modals and overlays!
Latest version: 2.0.0

# Portal 🚪✨

Greetings, DOM Teleporter! 🧙‍♀️

The `portal` module provides a `Portal` component that lets you render children into a different part of the DOM tree, outside of their parent component's DOM hierarchy. This is super useful for things like modals, tooltips, and dropdown menus that need to appear on top of everything else or escape an `overflow: hidden` parent.

It's like having a magic door in your component that leads anywhere in the DOM! 🌌

## Why Use Portals?

- **Stacking Context:** To avoid z-index issues and ensure your component appears on top.
- **Overflow:** To break out of a parent container that has `overflow: hidden` or other restrictive styles.
- **Accessibility:** For modals, it's common to portal them to the end of `document.body` to manage focus and ARIA attributes correctly.

## Basic Usage

```tsx
import { Portal } from '@ryvora/react-portal';
import React, { useState } from 'react';

function MyModal() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Open Modal</button>
      {isOpen && (
        <Portal container={document.body}>
          {' '}
          {/* Optional: defaults to document.body */}
          <div className="my-modal-overlay">
            <div className="my-modal-content">
              <h2>I am a Portalled Modal!</h2>
              <button onClick={() => setIsOpen(false)}>Close</button>
            </div>
          </div>
        </Portal>
      )}
    </>
  );
}
```

Teleport your components to where they need to be! 슝! (Swoosh!) 💨
npm package: @ryvora/react-presence
Description: 🎬 Animate React components in and out with presence detection. Smooth entrances and exits!
Latest version: 2.0.0

# Presence (Animations) 🎬

Hello, Animation Director! 🌟

The `presence` module, often providing a `Presence` component, is your key to smoothly animating components when they mount and unmount. It helps manage the lifecycle of an element that needs to animate in and out, especially when its visibility is controlled by a boolean state.

It's like a stage manager for your components, ensuring they make a grand entrance 💃 and a graceful exit 🕺, even if they're removed from the React tree!

## The Challenge it Solves

When a component unmounts, React removes it from the DOM immediately. This makes exit animations tricky. `Presence` keeps the component in the DOM long enough for an exit animation to complete before _actually_ removing it.

## How it Typically Works

1.  You wrap the component you want to animate with `<Presence present={isOpen}>`.
2.  When `isOpen` becomes `false`, `Presence` doesn't immediately remove its children.
3.  Instead, it waits for a CSS animation/transition to finish (or a JS callback) on its child before unmounting it.
4.  You use CSS (e.g., `data-state="open"` or `data-state="closed"`) to define the enter/exit animations.

## Conceptual Usage

```tsx
import { Presence } from '@ryvora/react-presence'; // Or similar name
import React, { useState } from 'react';
import './styles.css'; // Assuming animations are defined here

// styles.css might have:
// .my-animated-box[data-state="open"] { opacity: 1; transform: scale(1); transition: all 0.3s; }
// .my-animated-box[data-state="closed"] { opacity: 0; transform: scale(0.9); transition: all 0.3s; }

function MyAnimatedComponent() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <button onClick={() => setIsOpen(!isOpen)}>Toggle Animation</button>
      <Presence present={isOpen}>
        <div className="my-animated-box" data-state={isOpen ? 'open' : 'closed'}>
          Hello, I animate in and out!
        </div>
      </Presence>
    </>
  );
}
```

Bring your UI to life with beautiful and smooth presence animations! ✨💨
npm package: @ryvora/react-primitive
Description: 🧱 Foundational React primitives with asChild support. Build flexible, composable UIs!
Latest version: 2.0.0

# Primitive 🧱

Hey there, Component Architect! 🏗️

The `primitive` module is the bedrock of your component library! It provides a set of base components (like `Primitive.div`, `Primitive.button`, `Primitive.span`, etc.) that act as enhanced versions of standard HTML elements.

Think of them as foundational Lego bricks 🧱 – simple, versatile, and essential for building more complex structures!

## Why Primitives?

- **`asChild` Prop:** This is a super cool feature! If you pass `asChild` to a primitive, it will merge its own props and behavior with its direct child component, instead of rendering its own DOM element. This is amazing for building highly composable and flexible component APIs.
- **Accessibility:** Primitives can help enforce accessibility best practices or add default ARIA roles/attributes.
- **Styling Consistency:** They can be a central place to apply base styling or integrate with your styling solution.
- **Event Composition:** Might include utilities like `composeEventHandlers` to easily merge multiple event handlers.

## Basic Usage

```tsx
import { Primitive } from '@ryvora/react-primitive';

// Standard usage:
const MyButton = (props) => {
  return <Primitive.button {...props} style={{ backgroundColor: 'blue', color: 'white' }} />;
};

// Using asChild:
const FancyLink = React.forwardRef(({ children, ...props }, ref) => {
  return (
    <Primitive.a {...props} ref={ref} style={{ textDecoration: 'underline', color: 'purple' }}>
      {children}
    </Primitive.a>
  );
});

const MyComponent = () => {
  return (
    <Primitive.div asChild style={{ padding: '10px', border: '1px solid red' }}>
      <FancyLink href="#">
        This will be a link, styled by both Primitive.div and FancyLink!
      </FancyLink>
    </Primitive.div>
  );
};
```

Build solid foundations for your UI with Primitives! 🛠️
npm package: @ryvora/react-progress
Description: 📊⏳ Accessible and customizable progress bar for React. Show your users their progress!
Latest version: 2.1.0

# Progress 📊⏳

Hello Progress Tracker! 🚀

The `progress` module helps you create accessible and good-looking progress bars. Whether you're showing file upload progress, a setup wizard's completion, or just how much of a task is done, this component has got you covered! 💪

It's like a little visual cheerleader 📣 for your users, showing them how far they've come and how close they are to the finish line!

## Key Features:

- ✅ **Accessible:** Implements ARIA attributes for progress bars (`aria-valuenow`, `aria-valuemin`, `aria-valuemax`).
- 🔢 **Determinate & Indeterminate:** Supports both known progress values and an "I'm working on it!" indeterminate state.
- 🎨 **Styleable:** Easily customizable to fit your app's look and feel.
- 🧩 **Composable:** Typically consists of `Progress.Root` (the container) and `Progress.Indicator` (the part that fills up).

## Basic Usage:

```tsx
import * as Progress from '@ryvora/react-progress';
import React, { useState, useEffect } from 'react';

function MyLoadingComponent() {
  const [progressValue, setProgressValue] = useState(0);

  useEffect(() => {
    // Simulate progress
    if (progressValue < 100) {
      const timer = setTimeout(() => setProgressValue(progressValue + 10), 500);
      return () => clearTimeout(timer);
    }
  }, [progressValue]);

  return (
    <div>
      <p>Loading... {progressValue}%</p>
      <Progress.Root value={progressValue} max={100} style={{ width: '300px', height: '20px' }}>
        <Progress.Indicator
          style={{ width: `${progressValue}%`, height: '100%', backgroundColor: 'green' }}
        />
      </Progress.Root>

      {/* Indeterminate example */}
      {/* <Progress.Root value={null} style={{ width: '300px', height: '20px' }}> */}
      {/*   <Progress.Indicator style={{ width: '50%', height: '100%', backgroundColor: 'blue' }} /> */}
      {/* </Progress.Root> */}
    </div>
  );
}
```

Show that progress and keep your users in the loop! 🔄🎉
npm package: @ryvora/react-roving-focus
Description: 🚶‍♂️➡️🚶‍♀️ Roving tabindex for accessible keyboard navigation in React groups.
Latest version: 2.0.0

# Roving Focus (Roving Tabindex) 🚶‍♂️➡️🚶‍♀️

Hey Keyboard Navigator! ⌨️💨

The `roving-focus` module (or `RovingFocusGroup`) implements the "roving tabindex" pattern. This is a clever accessibility technique used for managing focus in a group of related elements (like toolbar buttons, tabs, or radio group items) where only one item in the group should be focusable at a time via the Tab key.

Think of it like a single spotlight 🔦 that moves between actors on a stage. Only one is in the spotlight (tab-focusable), but you can move the spotlight (focus) to others using arrow keys!

## Why Roving Tabindex?

- **Accessibility:** Prevents "tab traps" where users have to press Tab many times to get past a large group of items.
- **Intuitive Keyboard Navigation:** Allows users to navigate _within_ the group using arrow keys (or other custom keys) once one item in the group has focus.

## How it Works:

1.  Only one item in the group has `tabindex="0"` (making it part of the page's tab sequence).
2.  All other items in the group have `tabindex="-1"` (making them focusable programmatically but not via Tab).
3.  When the user navigates within the group (e.g., with arrow keys), the `tabindex="0"` is "roved" to the newly focused item, and the previously focused item gets `tabindex="-1"`.

## Conceptual Usage:

```tsx
import { RovingFocusGroup, RovingFocusItem } from '@ryvora/react-roving-focus'; // Assuming component names

function MyToolbar() {
  return (
    <RovingFocusGroup orientation="horizontal" loop>
      <RovingFocusItem asChild>
        <button>Cut</button>
      </RovingFocusItem>
      <RovingFocusItem asChild>
        <button>Copy</button>
      </RovingFocusItem>
      <RovingFocusItem asChild>
        <button>Paste</button>
      </RovingFocusItem>
    </RovingFocusGroup>
  );
}
```

Keep your keyboard navigation smooth and accessible! ✨🎹
npm package: @ryvora/react-scrollable-list
Description: 📜↔️ Horizontally scrollable list with navigation buttons for React. Perfect for carousels and tab lists!
Latest version: 4.0.0

# Scrollable List 📜↔️

Ahoy, Content Navigator! ⛵

The `scrollable-list` module is your trusty first mate for creating horizontally scrolling lists with snazzy previous/next buttons! ◀️▶️ It's perfect for image carousels, tab lists, or any collection of items that needs to fit into a constrained space while still being fully accessible.

It's like a conveyor belt for your UI elements, making sure users can see everything without overwhelming them! 🎢

## What it Offers:

- ↔️ **Horizontal Scrolling:** Smoothly scrolls content left and right.
- 👆 **Navigation Buttons:** Provides `PreviousButton` and `NextButton` that automatically enable/disable based on scroll position.
- 📦 **Composable Structure:**
  - `ScrollableList.Root`: The main container.
  - `ScrollableList.Viewport`: The actual scrollable area.
  - `ScrollableList.Item`: For individual items in the list.
  - `ScrollableList.PreviousButton`: Button to scroll left/previous.
  - `ScrollableList.NextButton`: Button to scroll right/next.
- 🛠️ **Customizable:** Style it to your heart's content!

## Example Ahoy!

```tsx
import * as ScrollableList from '@ryvora/react-scrollable-list';
import React from 'react';

const items = ['Item 1', 'Item 2', 'Item 3', 'Item 4', 'Item 5', 'Item 6'];

function MyScrollingTabs() {
  return (
    <ScrollableList.Root style={{ maxWidth: '300px', border: '1px solid #ccc' }}>
      <ScrollableList.PreviousButton>‹</ScrollableList.PreviousButton>
      <ScrollableList.Viewport style={{ padding: '10px 0' }}>
        {items.map((item) => (
          <ScrollableList.Item
            key={item}
            style={{
              display: 'inline-block',
              padding: '8px 12px',
              margin: '0 5px',
              border: '1px solid #eee',
              whiteSpace: 'nowrap',
            }}
          >
            {item}
          </ScrollableList.Item>
        ))}
      </ScrollableList.Viewport>
      <ScrollableList.NextButton>›</ScrollableList.NextButton>
    </ScrollableList.Root>
  );
}
```

Let your content flow freely and beautifully! 🌊✨
npm package: @ryvora/react-select
Description: 🔽☑️ Accessible, customizable select dropdown for React. Keyboard navigation, ARIA, and more!
Latest version: 3.0.0

# Select (Dropdown) 🔽☑️

Well hello there, Choice Champion! 🏆

The `select` module is your ultimate tool for creating highly accessible and customizable dropdown select menus. It allows users to choose an option from a list, just like a native `<select>` element, but with superpowers! 🦸‍♂️

It's like a magic hat 🎩 – you ask for choices, and it presents them beautifully!

## Awesome Features:

- 💯 **Super Accessible:** Full keyboard navigation, ARIA attributes, and screen reader support.
- 🎨 **Fully Styleable:** Customize every part to match your design system.
- 🧩 **Composable API:**
  - `Select.Root`: The main wrapper.
  - `Select.Trigger`: The button that opens the dropdown.
  - `Select.Value`: Displays the selected value (can have a placeholder).
  - `Select.Icon`: A little dropdown arrow icon.
  - `Select.Portal`: To render the dropdown content in a different part of the DOM.
  - `Select.Content`: The container for the list of items.
  - `Select.Viewport`: The scrollable area within the content.
  - `Select.Item`: A selectable option.
  - `Select.ItemText`: The text content of an item.
  - `Select.ItemIndicator`: A checkmark or other indicator for the selected item.
  - `Select.Group` & `Select.Label`: For organizing items.
  - `Select.Separator`: A visual divider.
- ⌨️ **Type-ahead:** Users can type to quickly find options.

## Quick Pick Example:

```tsx
import * as Select from '@ryvora/react-select';

function MyFruitSelector() {
  return (
    <Select.Root defaultValue="apple">
      <Select.Trigger aria-label="Fruit">
        <Select.Value placeholder="Select a fruit..." />
        <Select.Icon />
      </Select.Trigger>

      <Select.Portal>
        <Select.Content>
          <Select.Viewport>
            <Select.Item value="apple">
              <Select.ItemText>Apple 🍎</Select.ItemText>
              <Select.ItemIndicator />
            </Select.Item>
            <Select.Item value="banana">
              <Select.ItemText>Banana 🍌</Select.ItemText>
              <Select.ItemIndicator />
            </Select.Item>
            <Select.Item value="orange" disabled>
              <Select.ItemText>Orange 🍊 (Sold Out!)</Select.ItemText>
              <Select.ItemIndicator />
            </Select.Item>
          </Select.Viewport>
        </Select.Content>
      </Select.Portal>
    </Select.Root>
  );
}
```

Help your users make the perfect choice, every time! ✨👌
npm package: @ryvora/react-slot
Description: 🎰 Slot utility for composable React components. Pass props down and unlock asChild magic!
Latest version: 2.0.0

# Slot 🎰

Hey Component Customizer! 🛠️

The `slot` module (often providing a `Slot` component or a `useSlot` hook) is a clever utility that allows a component to "pass down" its props to its direct child element, effectively "slotting" the child into its own rendering logic. This is a key ingredient in making highly composable and flexible components, especially when used with the `asChild` prop pattern seen in `@ryvora/react-primitive`.

It's like having a special placeholder in your component that your users can fill with their own custom content, which then inherits the parent's behavior! 🧩➡️🎁

## The Magic of `asChild`

When a component like `Primitive.button` receives an `asChild` prop, it doesn't render its own `button` tag. Instead, it clones its _single React child element_, merging its own props (like event handlers or ARIA attributes) with the child's props. The `Slot` utility is often what powers this merging and cloning behavior internally.

## Conceptual Usage (Often Internal to Primitives)

```tsx
// Simplified example of how a Primitive might use Slot internally
import { Slot } from '@ryvora/react-slot'; // Or it might be an internal utility

const MyPrimitiveButton = React.forwardRef(({ asChild, children, ...props }, forwardedRef) => {
  const Comp = asChild ? Slot : 'button'; // If asChild, use Slot, else render a button
  return (
    <Comp ref={forwardedRef} {...props}>
      {children}
    </Comp>
  );
});

// User consuming MyPrimitiveButton with asChild:
function App() {
  return (
    <MyPrimitiveButton asChild onClick={() => console.log('Clicked wrapped link!')}>
      <a href="#">This link will behave like MyPrimitiveButton!</a>
    </MyPrimitiveButton>
  );
}
```

Unlock ultimate composability and flexibility in your component APIs! 🔗✨
npm package: @ryvora/react-use-callback-ref
Description: 📞🔄 Stable callback refs for React. Keep your event handlers up-to-date and performant!
Latest version: 2.0.0

# use-callback-ref 📞🔄

Hello State-Savvy Developer! 🧠

The `use-callback-ref` hook is a handy utility for situations where you have a callback function (like an event handler) that depends on some state or props, but you want to provide a _stable reference_ to that callback to a child component or a `useEffect` dependency array.

It's like having a phone number 📞 that never changes, even if the person answering (your callback logic) updates!

## The Problem:

If you define a callback inside your component that uses `useState` or props, its reference changes on every render. If you pass this changing callback to a memoized child or a `useEffect` with a dependency array, it can cause unnecessary re-renders or effect re-runs.

## The Solution:

`useCallbackRef` gives you a stable ref to a function. You can call this ref, and it will always execute the _latest version_ of your callback, even if the callback itself has been redefined with new state/props.

## Basic Usage:

```tsx
import { useCallbackRef } from '@ryvora/react-use-callback-ref';
import React, { useState, useEffect, useCallback } from 'react';

const MyChild = React.memo(({ onStableClick }) => {
  console.log('MyChild rendered');
  return <button onClick={onStableClick}>Click Me (Child)</button>;
});

function MyParent() {
  const [count, setCount] = useState(0);

  // This callback changes on every render because of `count`
  const handleClick = () => {
    console.log('Clicked! Count is:', count);
  };

  // But this ref to it is stable!
  const stableHandleClick = useCallbackRef(handleClick);

  useEffect(() => {
    console.log('Effect with stable callback ref');
    // stableHandleClick can be used in a dependency array without causing re-runs due to handleClick changing
  }, [stableHandleClick]);

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount((c) => c + 1)}>Increment</button>
      <MyChild onStableClick={stableHandleClick} />
    </div>
  );
}
```

Keep those callbacks stable and your components performant! ⚡👍
npm package: @ryvora/react-use-controllable-state
Description: 🎮🔄 Controlled/uncontrolled state hook for React. Build flexible, predictable components!
Latest version: 2.0.0

# use-controllable-state 🎮🔄

Hey Control Freak (in a good way!) 😉

The `use-controllable-state` hook is a super useful utility for creating components that can have both **controlled** (state managed by parent via props) and **uncontrolled** (internal state, with a default initial value) behavior for a piece of their state.

It's like giving your component a dual-mode switch 🕹️: let the parent drive, or drive itself!

## The Pattern:

Many native HTML elements work this way (e.g., `<input type="text">` can have `value` and `onChange` for controlled, or just `defaultValue` for uncontrolled).
This hook makes it easy to replicate that flexibility in your own components.

## How it Works:

You provide the hook with:

- `prop`: The controlled value from props (e.g., `props.value`).
- `defaultProp`: The default uncontrolled value (e.g., `props.defaultValue`).
- `onChange`: A callback to notify the parent when the value changes (used in controlled mode).

The hook then returns `[state, setState]`, where `state` is the current value (either from props or internal) and `setState` is a function to update it (which also calls `onChange` if controlled).

## Basic Usage:

```tsx
import { useControllableState } from '@ryvora/react-use-controllable-state';
import React from 'react';

interface MyInputProps {
  value?: string;
  defaultValue?: string;
  onChange?: (value: string) => void;
}

function MyInput({ value: valueProp, defaultValue, onChange }: MyInputProps) {
  const [value, setValue] = useControllableState({
    prop: valueProp,
    defaultProp: defaultValue ?? '',
    onChange,
    caller: 'MyInput', // Optional: for better debug messages
  });

  return <input type="text" value={value} onChange={(e) => setValue(e.target.value)} />;
}

// Usage:
// <MyInput onChange={...} value={controlledValue} />
// <MyInput defaultValue="I am uncontrolled!" />
```

Build flexible and predictable components with controllable state! 🌟💪
npm package: @ryvora/react-use-effect-event
Description: useEffect + event = ❤️. Always up-to-date event handlers for effects in React!
Latest version: 2.0.0

# use-effect-event 🤝 useEffect & Event

Hi Effect Optimizer! ⚡

The `use-effect-event` hook (sometimes named `useEvent` or similar, as proposed by the React team) helps you define an event handler or callback inside a `useEffect` that can access the latest props and state without needing to be included in the effect's dependency array.

It's like giving your `useEffect` a special, always-up-to-date lens 👓 to see the current component state, without triggering the effect every time that state changes!

## The Problem

Sometimes, a `useEffect` needs to call a function that depends on props or state. If you include that function in the dependency array, the effect re-runs whenever the function reference changes (which is often on every render if it captures props/state).

If you omit it, you get a stale closure and the function uses old props/state values. 😬

## The Solution

`use-effect-event` (or `useEvent`) provides a stable function reference that internally always calls the latest version of your event handler logic.

## Conceptual Usage (based on React RFC for `useEvent`)

```tsx
import { useEffectEvent } from '@ryvora/react-use-effect-event'; // Or `useEvent`
import React, { useState, useEffect } from 'react';

function ChatRoom({ roomId, theme }) {
  const [messages, setMessages] = useState([]);

  // This function would normally need to be in the effect's deps, or cause stale closures.
  const onMessage = useEffectEvent((newMessage) => {
    // Can access latest `theme` and `messages` without them being in deps
    console.log(`New message with theme ${theme}:`, newMessage);
    setMessages((prevMessages) => [...prevMessages, newMessage]);
  });

  useEffect(() => {
    // Subscribe to chat messages for `roomId`
    const connection = createConnection(roomId);
    connection.on('message', (msg) => {
      onMessage(msg); // Call the stable event handler
    });

    return () => connection.disconnect();
    // Only re-runs if `roomId` changes, not if `theme` or `messages` change!
  }, [roomId]);

  return <div>Messages: {messages.join(', ')}</div>;
}
```

Keep your effects clean and your dependencies minimal! ✨🧼