@tcn/ui-utils

A collection of essential utility components, hooks, and functions that provide common functionality needed across React applications.

Overview

@tcn/ui-utils provides a set of reusable utilities that solve common UI patterns and challenges. These utilities are designed to be lightweight, performant, and easy to integrate into any React application.

What's Included

Event Listeners

• ClickAwayListener: Detects clicks outside of a component, useful for modals, dropdowns, and popovers
• ScrollAwayListener: Monitors scroll events outside of a component, helpful for scroll-triggered interactions
• FocusRedirect: Manages focus behavior and redirects focus to appropriate elements

React Hooks

• useResizeObserver: Efficiently tracks element size changes with configurable triggers
• useForkRef: Combines multiple refs into a single ref for complex ref scenarios
• makeContextHook: Utility for creating context hooks with proper typing

Calendar Utilities

• Calendar Date Management: Helper functions for working with dates in calendar components
• Month/Year Generators: Utilities for generating calendar month and year data
• Day/Week Helpers: Functions for working with days of the week and calendar navigation

Utility Functions

• StyleInjector: Component for dynamically injecting styles into the DOM
• Default Value: Utility for providing fallback values with type safety

Key Features

• Performance Optimized: Uses efficient event handling and minimal re-renders
• TypeScript First: Full type safety with excellent IntelliSense support
• Accessibility Focused: Built with accessibility best practices in mind
• Lightweight: Minimal bundle size impact with maximum utility
• Composable: Utilities can be combined and extended as needed

Common Use Cases

Modal and Dropdown Management

import { ClickAwayListener } from '@tcn/ui-utils';

function Modal({ isOpen, onClose, children }) {
  if (!isOpen) return null;
  
  return (
    <ClickAwayListener onClickAway={onClose}>
      <div className="modal">
        {children}
      </div>
    </ClickAwayListener>
  );
}

Responsive Layouts

import { useResizeObserver } from '@tcn/ui-utils';

function ResponsiveComponent() {
  const [size, setSize] = useState({ width: 0, height: 0 });
  
  const ref = useResizeObserver((width, height) => {
    setSize({ width, height });
  });
  
  return (
    <div ref={ref}>
      Current size: {size.width} x {size.height}
    </div>
  );
}

Calendar Components

import { getMonthsOfYear, getDaysOfWeek } from '@tcn/ui-utils';

// Generate calendar data
const months = getMonthsOfYear();
const weekDays = getDaysOfWeek();

Integration

This package is designed to work seamlessly with other Blackcat UI packages and can be used independently in any React application. It provides the building blocks for:

• Complex UI Interactions: Event handling for sophisticated user interactions
• Responsive Design: Size monitoring and responsive behavior
• Accessibility: Focus management and keyboard navigation
• Data Management: Calendar utilities and data helpers

When to Use

Choose @tcn/ui-utils when you need:

• Event handling for clicks outside components
• Responsive behavior based on element size changes
• Calendar-related functionality
• Focus management and accessibility features
• Utility functions for common UI patterns

Architecture

The utilities are organized into logical groups:

1. Event Listeners: Components that handle external events
2. Hooks: Custom React hooks for common functionality
3. Calendar Utils: Date and calendar-related functions
4. Helpers: General utility functions and components

License

Apache-2.0