@ng-cn/core 1.0.11 → 1.0.12

package/src/app/lib/components/ui/typography/typography-list.component.ts

@@ -0,0 +1,31 @@
+import { cn } from '@/lib/utils';
+import {
+    ChangeDetectionStrategy,
+    Component,
+    computed,
+    input,
+} from '@angular/core';
+
+/**
+ * Typography List component (unordered list)
+ *
+ * @example
+ * <TypographyList>
+ *   <li>Item 1</li>
+ *   <li>Item 2</li>
+ * </TypographyList>
+ */
+@Component({
+  selector: 'TypographyList',
+  template: `<ng-content />`,
+  host: {
+    '[class]': 'computedClass()',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class TypographyList {
+  readonly class = input<string>('');
+  protected readonly computedClass = computed(() =>
+    cn('my-6 ml-6 list-disc [&>li]:mt-2', this.class())
+  );
+}

package/src/app/lib/components/ui/typography/typography-muted.component.ts

@@ -0,0 +1,28 @@
+import { cn } from '@/lib/utils';
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  input,
+} from '@angular/core';
+
+/**
+ * Typography Muted component
+ *
+ * @example
+ * <TypographyMuted>Muted helper text</TypographyMuted>
+ */
+@Component({
+  selector: 'TypographyMuted',
+  template: `<ng-content />`,
+  host: {
+    '[class]': 'computedClass()',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class TypographyMuted {
+  readonly class = input<string>('');
+  protected readonly computedClass = computed(() =>
+    cn('text-sm text-muted-foreground', this.class())
+  );
+}

package/src/app/lib/components/ui/typography/typography-p.component.ts

@@ -0,0 +1,29 @@
+import { cn } from '@/lib/utils';
+import {
+    ChangeDetectionStrategy,
+    Component,
+    computed,
+    input,
+} from '@angular/core';
+
+/**
+ * Typography P (paragraph) component
+ *
+ * @example
+ * <TypographyP>This is a paragraph of text.</TypographyP>
+ */
+@Component({
+  selector: 'TypographyP',
+  template: `<ng-content />`,
+  host: {
+    '[class]': 'computedClass()',
+    style: 'display: block',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class TypographyP {
+  readonly class = input<string>('');
+  protected readonly computedClass = computed(() =>
+    cn('leading-7 [&:not(:first-child)]:mt-6', this.class())
+  );
+}

package/src/app/lib/components/ui/typography/typography-small.component.ts

@@ -0,0 +1,28 @@
+import { cn } from '@/lib/utils';
+import {
+    ChangeDetectionStrategy,
+    Component,
+    computed,
+    input,
+} from '@angular/core';
+
+/**
+ * Typography Small component
+ *
+ * @example
+ * <TypographySmall>Small text</TypographySmall>
+ */
+@Component({
+  selector: 'TypographySmall',
+  template: `<ng-content />`,
+  host: {
+    '[class]': 'computedClass()',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class TypographySmall {
+  readonly class = input<string>('');
+  protected readonly computedClass = computed(() =>
+    cn('text-sm font-medium leading-none', this.class())
+  );
+}

package/src/app/lib/index.ts

@@ -0,0 +1,7 @@
+// shadcn-angular Library Public API
+
+// Utils
+export { cn } from './utils';
+
+// UI Components
+export * from './components/ui';

package/src/app/lib/utils/accessibility/aria-id.service.ts

@@ -0,0 +1,118 @@
+import { Injectable, signal } from '@angular/core';
+
+/**
+ * Service to generate and manage unique ARIA IDs for accessibility relationships.
+ * Handles aria-labelledby, aria-describedby, aria-controls, etc.
+ */
+@Injectable({ providedIn: 'root' })
+export class AriaIdService {
+  private readonly counter = signal(0);
+  private readonly prefix = 'aria';
+
+  /**
+   * Generates a unique ID with an optional prefix.
+   * @param customPrefix - Optional prefix for the ID (e.g., 'dialog', 'menu')
+   * @returns A unique string ID
+   */
+  generateId(customPrefix?: string): string {
+    const count = this.counter();
+    this.counter.set(count + 1);
+    const basePrefix = customPrefix ? `${this.prefix}-${customPrefix}` : this.prefix;
+    return `${basePrefix}-${count}-${Math.random().toString(36).substring(2, 9)}`;
+  }
+
+  /**
+   * Generates a set of related IDs for a component with title and description.
+   * Useful for dialogs, alerts, and other components needing ARIA relationships.
+   * @param prefix - Component type prefix (e.g., 'dialog', 'alert')
+   * @returns Object containing contentId, titleId, and descriptionId
+   */
+  generateDialogIds(prefix: string = 'dialog'): AriaDialogIds {
+    const base = this.generateId(prefix);
+    return {
+      contentId: `${base}-content`,
+      titleId: `${base}-title`,
+      descriptionId: `${base}-description`,
+    };
+  }
+
+  /**
+   * Generates IDs for menu/listbox patterns.
+   * @param prefix - Component type prefix (e.g., 'menu', 'listbox', 'combobox')
+   * @returns Object containing triggerId, contentId, and a function to generate item IDs
+   */
+  generateMenuIds(prefix: string = 'menu'): AriaMenuIds {
+    const base = this.generateId(prefix);
+    let itemCounter = 0;
+
+    return {
+      triggerId: `${base}-trigger`,
+      contentId: `${base}-content`,
+      labelId: `${base}-label`,
+      generateItemId: () => `${base}-item-${itemCounter++}`,
+    };
+  }
+
+  /**
+   * Generates IDs for tab patterns.
+   * @param prefix - Component type prefix
+   * @returns Object with functions to generate tab and panel IDs
+   */
+  generateTabIds(prefix: string = 'tabs'): AriaTabIds {
+    const base = this.generateId(prefix);
+    let tabCounter = 0;
+
+    return {
+      tablistId: `${base}-tablist`,
+      generateTabId: () => {
+        const id = `${base}-tab-${tabCounter}`;
+        tabCounter++;
+        return id;
+      },
+      generatePanelId: (index: number) => `${base}-panel-${index}`,
+    };
+  }
+
+  /**
+   * Generates IDs for accordion patterns.
+   * @param prefix - Component type prefix
+   * @returns Object with functions to generate trigger and content IDs
+   */
+  generateAccordionIds(prefix: string = 'accordion'): AriaAccordionIds {
+    const base = this.generateId(prefix);
+    let itemCounter = 0;
+
+    return {
+      generateTriggerId: () => {
+        const id = `${base}-trigger-${itemCounter}`;
+        itemCounter++;
+        return id;
+      },
+      generateContentId: (index: number) => `${base}-content-${index}`,
+    };
+  }
+}
+
+export interface AriaDialogIds {
+  contentId: string;
+  titleId: string;
+  descriptionId: string;
+}
+
+export interface AriaMenuIds {
+  triggerId: string;
+  contentId: string;
+  labelId: string;
+  generateItemId: () => string;
+}
+
+export interface AriaTabIds {
+  tablistId: string;
+  generateTabId: () => string;
+  generatePanelId: (index: number) => string;
+}
+
+export interface AriaAccordionIds {
+  generateTriggerId: () => string;
+  generateContentId: (index: number) => string;
+}

package/src/app/lib/utils/accessibility/click-outside.directive.ts

@@ -0,0 +1,85 @@
+import {
+    Directive,
+    ElementRef,
+    OnDestroy,
+    afterNextRender,
+    inject,
+    output,
+} from '@angular/core';
+
+/**
+ * Directive that detects clicks outside the host element.
+ * Uses CDK-grade event handling with proper cleanup.
+ *
+ * @example
+ * <div (clickOutside)="onClickOutside()">
+ *   Content here
+ * </div>
+ */
+@Directive({
+  selector: '[clickOutside]',
+})
+export class ClickOutsideDirective implements OnDestroy {
+  private readonly elementRef = inject(ElementRef);
+
+  /** Emits when a click occurs outside the host element */
+  readonly clickOutside = output<MouseEvent>();
+
+  private documentClickListener: ((event: MouseEvent) => void) | null = null;
+  private documentTouchListener: ((event: TouchEvent) => void) | null = null;
+
+  constructor() {
+    // Use afterNextRender for SSR compatibility
+    afterNextRender(() => {
+      this.setupListeners();
+    });
+  }
+
+  private setupListeners(): void {
+    // Use setTimeout to avoid capturing the opening click
+    setTimeout(() => {
+      this.documentClickListener = (event: MouseEvent) => {
+        this.handleEvent(event);
+      };
+
+      this.documentTouchListener = (event: TouchEvent) => {
+        // Convert touch to a simulated mouse event for the handler
+        const touch = event.touches[0] || event.changedTouches[0];
+        if (touch) {
+          const mouseEvent = new MouseEvent('click', {
+            bubbles: true,
+            cancelable: true,
+            clientX: touch.clientX,
+            clientY: touch.clientY,
+          });
+          this.handleEvent(mouseEvent);
+        }
+      };
+
+      document.addEventListener('click', this.documentClickListener, true);
+      document.addEventListener('touchstart', this.documentTouchListener, true);
+    }, 0);
+  }
+
+  private handleEvent(event: MouseEvent): void {
+    const targetElement = event.target as HTMLElement;
+
+    // Check if click is outside the element
+    if (
+      targetElement &&
+      !this.elementRef.nativeElement.contains(targetElement) &&
+      this.elementRef.nativeElement !== targetElement
+    ) {
+      this.clickOutside.emit(event);
+    }
+  }
+
+  ngOnDestroy(): void {
+    if (this.documentClickListener) {
+      document.removeEventListener('click', this.documentClickListener, true);
+    }
+    if (this.documentTouchListener) {
+      document.removeEventListener('touchstart', this.documentTouchListener, true);
+    }
+  }
+}

package/src/app/lib/utils/accessibility/focus-management.service.ts

@@ -0,0 +1,231 @@
+import { DOCUMENT } from '@angular/common';
+import { Injectable, inject, signal } from '@angular/core';
+
+/**
+ * Service to manage focus state across the application.
+ * Handles saving/restoring focus, tracking focus history, and managing focus on open/close.
+ */
+@Injectable({ providedIn: 'root' })
+export class FocusManagementService {
+  private readonly document = inject(DOCUMENT);
+  private readonly focusStack = signal<HTMLElement[]>([]);
+
+  /**
+   * Saves the currently focused element to the stack.
+   * Call this before opening a modal/overlay to restore focus later.
+   * @returns The element that was saved, or null if no element was focused
+   */
+  saveFocus(): HTMLElement | null {
+    const activeElement = this.document.activeElement as HTMLElement | null;
+    if (activeElement && activeElement !== this.document.body) {
+      this.focusStack.update((stack) => [...stack, activeElement]);
+      return activeElement;
+    }
+    return null;
+  }
+
+  /**
+   * Restores focus to the last saved element and removes it from the stack.
+   * Call this when closing a modal/overlay.
+   * @returns The element that was focused, or null if stack was empty
+   */
+  restoreFocus(): HTMLElement | null {
+    const stack = this.focusStack();
+    if (stack.length === 0) return null;
+
+    const lastElement = stack[stack.length - 1];
+    this.focusStack.update((s) => s.slice(0, -1));
+
+    if (lastElement && this.isElementFocusable(lastElement)) {
+      // Use setTimeout to ensure focus happens after any animations
+      setTimeout(() => {
+        lastElement.focus();
+      }, 0);
+      return lastElement;
+    }
+    return null;
+  }
+
+  /**
+   * Focuses the first focusable element within a container.
+   * @param container - The container element to search within
+   * @param options - Focus options
+   * @returns The element that was focused, or null if none found
+   */
+  focusFirstFocusable(
+    container: HTMLElement,
+    options: FocusOptions = {}
+  ): HTMLElement | null {
+    const focusable = this.getFocusableElements(container);
+    if (focusable.length > 0) {
+      const target = focusable[0];
+      this.focusElement(target, options);
+      return target;
+    }
+    return null;
+  }
+
+  /**
+   * Focuses the last focusable element within a container.
+   * @param container - The container element to search within
+   * @param options - Focus options
+   * @returns The element that was focused, or null if none found
+   */
+  focusLastFocusable(
+    container: HTMLElement,
+    options: FocusOptions = {}
+  ): HTMLElement | null {
+    const focusable = this.getFocusableElements(container);
+    if (focusable.length > 0) {
+      const target = focusable[focusable.length - 1];
+      this.focusElement(target, options);
+      return target;
+    }
+    return null;
+  }
+
+  /**
+   * Focuses a specific element with optional delay.
+   * @param element - The element to focus
+   * @param options - Focus options including preventScroll and delay
+   */
+  focusElement(element: HTMLElement, options: FocusOptions = {}): void {
+    const { preventScroll = false, delay = 0 } = options;
+
+    const doFocus = () => {
+      if (this.isElementFocusable(element)) {
+        element.focus({ preventScroll });
+      }
+    };
+
+    if (delay > 0) {
+      setTimeout(doFocus, delay);
+    } else {
+      doFocus();
+    }
+  }
+
+  /**
+   * Gets all focusable elements within a container.
+   * @param container - The container element to search within
+   * @returns Array of focusable HTML elements
+   */
+  getFocusableElements(container: HTMLElement): HTMLElement[] {
+    const selector = [
+      'a[href]',
+      'button:not([disabled])',
+      'input:not([disabled]):not([type="hidden"])',
+      'select:not([disabled])',
+      'textarea:not([disabled])',
+      '[tabindex]:not([tabindex="-1"])',
+      '[contenteditable="true"]',
+      'audio[controls]',
+      'video[controls]',
+      'details > summary:first-of-type',
+    ].join(', ');
+
+    const elements = Array.from(
+      container.querySelectorAll<HTMLElement>(selector)
+    );
+
+    return elements.filter((el) => this.isElementVisible(el));
+  }
+
+  /**
+   * Gets all tabbable elements (excludes tabindex="-1").
+   * @param container - The container element to search within
+   * @returns Array of tabbable HTML elements
+   */
+  getTabbableElements(container: HTMLElement): HTMLElement[] {
+    return this.getFocusableElements(container).filter((el) => {
+      const tabindex = el.getAttribute('tabindex');
+      return tabindex !== '-1';
+    });
+  }
+
+  /**
+   * Checks if an element is currently focusable.
+   * @param element - The element to check
+   * @returns true if the element can receive focus
+   */
+  isElementFocusable(element: HTMLElement): boolean {
+    if (!element || !this.document.body.contains(element)) return false;
+    if (!this.isElementVisible(element)) return false;
+
+    const tabindex = element.getAttribute('tabindex');
+    if (tabindex !== null && parseInt(tabindex, 10) < 0) return false;
+
+    // Check for disabled state
+    if (
+      element instanceof HTMLButtonElement ||
+      element instanceof HTMLInputElement ||
+      element instanceof HTMLSelectElement ||
+      element instanceof HTMLTextAreaElement
+    ) {
+      return !element.disabled;
+    }
+
+    // Check if element is naturally focusable
+    const focusableSelectors = [
+      'a[href]',
+      'button',
+      'input',
+      'select',
+      'textarea',
+      '[tabindex]',
+      '[contenteditable="true"]',
+    ];
+
+    return focusableSelectors.some((selector) => element.matches(selector));
+  }
+
+  /**
+   * Checks if an element is visible (not hidden by CSS).
+   * @param element - The element to check
+   * @returns true if the element is visible
+   */
+  private isElementVisible(element: HTMLElement): boolean {
+    if (!element) return false;
+
+    const style = getComputedStyle(element);
+    if (style.display === 'none' || style.visibility === 'hidden') return false;
+    if (element.hasAttribute('hidden')) return false;
+
+    // Check if any ancestor is hidden
+    let parent = element.parentElement;
+    while (parent) {
+      const parentStyle = getComputedStyle(parent);
+      if (
+        parentStyle.display === 'none' ||
+        parentStyle.visibility === 'hidden'
+      ) {
+        return false;
+      }
+      if (parent.hasAttribute('hidden')) return false;
+      parent = parent.parentElement;
+    }
+
+    return true;
+  }
+
+  /**
+   * Clears the focus history stack.
+   */
+  clearFocusHistory(): void {
+    this.focusStack.set([]);
+  }
+
+  /**
+   * Gets the current focus stack length.
+   */
+  getFocusStackDepth(): number {
+    return this.focusStack().length;
+  }
+}
+
+export interface FocusOptions {
+  /** Prevents scrolling to the focused element */
+  preventScroll?: boolean;
+  /** Delay in ms before focusing */
+  delay?: number;
+}