@ninna-ui/utils

Shared utility functions for the Ninna-UI design system — class merging, ref composition, type-safe context, and SSR helpers.

Shared utility functions used across all Ninna UI component packages. Core utilities (cn, KEYS, canUseDOM) are pure functions with no React dependency. React-aware utilities (createContext, composeRefs) use React as an optional peer dependency.

Installation

pnpm add @ninna-ui/utils

Exports

cn(...inputs) — Class Name Merger

Combines Tailwind CSS classes with intelligent conflict resolution. Built on clsx + tailwind-merge.

import { cn } from '@ninna-ui/utils';

cn('px-4 py-2', 'px-6');              // "py-2 px-6" — px-4 overridden
cn('text-red-500', false && 'hidden'); // "text-red-500"
cn('rounded-md', undefined, 'p-4');    // "rounded-md p-4"

composeRefs(...refs) — Ref Composition

Combines multiple React refs into a single ref callback. Essential for forwardRef components that also use internal refs.

import { composeRefs } from '@ninna-ui/utils';

const Component = forwardRef((props, forwardedRef) => {
  const internalRef = useRef(null);
  return <div ref={composeRefs(forwardedRef, internalRef)} />;
});

composeEventHandlers(external, internal) — Event Handler Composition

Chains event handlers so both external (user-provided) and internal handlers run. Respects event.preventDefault().

import { composeEventHandlers } from '@ninna-ui/utils';

<button onClick={composeEventHandlers(props.onClick, handleInternalClick)} />

createContext(name) — Type-Safe Context

Creates a React context with a required provider. Throws a helpful error if consumed outside its provider.

import { createContext } from '@ninna-ui/utils';

const [FormProvider, useFormContext] = createContext<FormContextValue>('FormControl');

KEYS — Keyboard Constants

Standard keyboard key constants for accessible event handling:

import { KEYS } from '@ninna-ui/utils';

KEYS.ENTER      // "Enter"
KEYS.ESCAPE     // "Escape"
KEYS.SPACE      // " "
KEYS.ARROW_UP   // "ArrowUp"
KEYS.ARROW_DOWN // "ArrowDown"
KEYS.TAB        // "Tab"

canUseDOM / getOwnerWindow — SSR Safety

Runtime checks for safe DOM access in server-side rendering contexts:

import { canUseDOM, getOwnerWindow } from '@ninna-ui/utils';

if (canUseDOM) {
  // Safe to access window, document
}

const win = getOwnerWindow(element); // Get the owner window of a DOM element

Architecture Rules

• React is optional — cn, KEYS, canUseDOM are pure; createContext and composeRefs require React
• No DOM APIs — Must work in SSR contexts (canUseDOM is a check, not a usage)
• No @ninna-ui/* imports — This is a leaf dependency
• No side effects — All functions are pure

Related Packages

• @ninna-ui/core — Design tokens and theme presets
• All packages — Complete package list

License

MIT