@tailng-ui/cdk

Headless Angular utilities and primitives for building accessible, interactive components.

Overview

@tailng-ui/cdk provides logic-only building blocks for Angular applications. This package contains utilities for accessibility, keyboard navigation, focus management, and component primitives that power the Tailng UI component library.

Installation

npm install @tailng-ui/cdk

Peer Dependencies

• @angular/core: ^21.0.0
• @angular/common: ^21.0.0

Features

• Accessibility (a11y): Focus trap directive and utilities for managing focus in modals and overlays
• Keyboard Navigation: Utilities for handling keyboard interactions in lists, menus, and interactive components
• Scroll Management: Utilities for scrolling elements into view
• Component Utilities: Helper functions for common component patterns like option lists

Usage

Focus Trap Directive

Manage focus trapping in modals, dialogs, and overlays:

import { Component } from '@angular/core';
import { TngFocusTrap } from '@tailng-ui/cdk';

@Component({
  selector: 'app-modal',
  standalone: true,
  imports: [TngFocusTrap],
  template: `
    <div tngFocusTrap>
      <h2>Modal Content</h2>
      <button>Close</button>
    </div>
  `,
})
export class ModalComponent {}

Keyboard Navigation

Handle keyboard navigation in lists and menus:

import { keyboardNavigation } from '@tailng-ui/cdk';

// Use in your component to handle arrow key navigation
const state = keyboardNavigation({
  // Configuration for keyboard navigation
});

Option List Utilities

Utilities for managing option list state and context:

import { OptionTplContext } from '@tailng-ui/cdk';

// Type for option template context
type MyOption = { id: string; label: string };
const context: OptionTplContext<MyOption> = {
  $implicit: { id: '1', label: 'Option 1' },
  index: 0,
  active: true,
  selected: false,
};

Scroll Utilities

Scroll elements into view:

import { scrollActiveIntoView } from '@tailng-ui/cdk';

scrollActiveIntoView({
  container: elementRef.nativeElement,
  activeIndex: 2,
  itemSelector: '[data-index]',
  behavior: 'smooth',
});

API Reference

Directives

• TngFocusTrap: Standalone directive for trapping focus within an element

Utilities

• createTngFocusTrap: Create a focus trap instance
• keyboardNavigation: Keyboard navigation state management
• scrollActiveIntoView: Scroll an element into view
• OptionTplContext: Type for option template context

Related Packages

• @tailng-ui/ui - UI components built on top of this CDK
• @tailng-ui/icons - Icon components
• @tailng-ui/theme - Tailwind CSS theme preset

License

MIT