@ng-cn/core 1.0.11 → 1.0.14

package/src/app/lib/components/ui/tooltip/tooltip-context.ts

@@ -0,0 +1,29 @@
+import { InjectionToken, WritableSignal } from '@angular/core';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type TooltipSide = 'top' | 'right' | 'bottom' | 'left';
+export type TooltipAlign = 'start' | 'center' | 'end';
+
+export interface TooltipContextValue {
+  /** Signal for open state */
+  open: WritableSignal<boolean>;
+  /** Set open state */
+  setOpen: (open: boolean) => void;
+  /** Delay before showing tooltip (ms) */
+  delayDuration: number;
+  /** Skip delay duration when quickly hovering between tooltips (ms) */
+  skipDelayDuration: number;
+  /** Unique ID for aria-describedby relationship */
+  tooltipId: string;
+  /** Whether hoverable content is disabled */
+  disableHoverableContent: () => boolean;
+}
+
+// ============================================================================
+// Injection Tokens
+// ============================================================================
+
+export const TOOLTIP_CONTEXT = new InjectionToken<TooltipContextValue>('TOOLTIP_CONTEXT');

package/src/app/lib/components/ui/tooltip/tooltip-provider.component.ts

@@ -0,0 +1,95 @@
+import {
+    ChangeDetectionStrategy,
+    Component,
+    forwardRef,
+    input,
+    signal,
+} from '@angular/core';
+import { TOOLTIP_CONTEXT, type TooltipContextValue } from './tooltip-context';
+
+let tooltipIdCounter = 0;
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Props for the TooltipProvider component
+ */
+export interface TooltipProviderProps {
+  /** The duration from when the pointer enters the trigger until the tooltip opens.
+   * @default 700 */
+  delayDuration?: number;
+  /** How much time a user has to enter another trigger without incurring a delay again.
+   * @default 300 */
+  skipDelayDuration?: number;
+  /** When true, trying to hover the content will result in the tooltip closing.
+   * @default false */
+  disableHoverableContent?: boolean;
+}
+
+// ============================================================================
+// Component
+// ============================================================================
+
+/**
+ * @component TooltipProvider
+ *
+ * Wraps your app to provide global tooltip behavior configuration.
+ *
+ * @description
+ * TooltipProvider allows you to configure shared tooltip behavior for all
+ * tooltips in your application. Place it near the root of your app.
+ *
+ * ## Features
+ * - Shared delay duration for all tooltips
+ * - Skip delay when rapidly moving between tooltips
+ * - Control hoverable content behavior
+ *
+ * @example Basic usage
+ * ```html
+ * <TooltipProvider>
+ *   <Tooltip>
+ *     <TooltipTrigger>Hover me</TooltipTrigger>
+ *     <TooltipContent>Tooltip content</TooltipContent>
+ *   </Tooltip>
+ * </TooltipProvider>
+ * ```
+ *
+ * @example Custom delays
+ * ```html
+ * <TooltipProvider [delayDuration]="400" [skipDelayDuration]="200">
+ *   <!-- Tooltips will use these delays -->
+ * </TooltipProvider>
+ * ```
+ */
+@Component({
+  selector: 'TooltipProvider',
+  template: `<ng-content />`,
+  providers: [
+    {
+      provide: TOOLTIP_CONTEXT,
+      useExisting: forwardRef(() => TooltipProvider),
+    },
+  ],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class TooltipProvider implements TooltipContextValue {
+  /** The duration from when the pointer enters the trigger until the tooltip opens */
+  readonly delayDuration = 700;
+
+  /** How much time a user has to enter another trigger without incurring a delay again */
+  readonly skipDelayDuration = 300;
+
+  /** Unique ID for aria-describedby relationship */
+  readonly tooltipId = `tooltip-provider-${++tooltipIdCounter}`;
+
+  /** When true, trying to hover the content will result in the tooltip closing */
+  readonly disableHoverableContent = input<boolean>(false);
+
+  readonly open = signal(false);
+
+  setOpen(open: boolean): void {
+    this.open.set(open);
+  }
+}

package/src/app/lib/components/ui/tooltip/tooltip-trigger.component.ts

@@ -0,0 +1,138 @@
+import {
+    ChangeDetectionStrategy,
+    Component,
+    inject,
+    input,
+    OnDestroy,
+} from '@angular/core';
+import { TOOLTIP_CONTEXT } from './tooltip-context';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Props for the TooltipTrigger component
+ */
+export interface TooltipTriggerProps {
+  /** Change the default rendered element for the one passed as a child.
+   * @default false */
+  asChild?: boolean;
+}
+
+// ============================================================================
+// Component
+// ============================================================================
+
+/**
+ * @component TooltipTrigger
+ *
+ * The element that triggers the tooltip when hovered or focused.
+ *
+ * @description
+ * TooltipTrigger wraps the element that activates the tooltip. It handles
+ * mouse and keyboard events to show/hide the tooltip.
+ *
+ * ## Features
+ * - Shows tooltip on hover with configurable delay
+ * - Shows tooltip on focus for keyboard users
+ * - Dismissible via Escape key (WCAG 1.4.13)
+ * - Supports custom trigger elements via content projection
+ *
+ * ## Accessibility
+ * - `aria-describedby` points to tooltip content when open
+ * - Escape key dismisses tooltip (WCAG 1.4.13 compliance)
+ * - Focus triggers tooltip for keyboard users
+ *
+ * ## Keyboard Navigation
+ * - `Escape` - Dismiss the tooltip
+ * - `Tab` - Focus triggers tooltip to show
+ *
+ * @example Basic usage
+ * ```html
+ * <TooltipTrigger>
+ *   <button>Hover me</button>
+ * </TooltipTrigger>
+ * ```
+ *
+ * @example With icon button
+ * ```html
+ * <TooltipTrigger>
+ *   <button class="icon-button">
+ *     <HelpIcon />
+ *   </button>
+ * </TooltipTrigger>
+ * ```
+ */
+@Component({
+  selector: 'TooltipTrigger',
+  template: `<ng-content />`,
+  host: {
+    '(mouseenter)': 'onMouseEnter()',
+    '(mouseleave)': 'onMouseLeave()',
+    '(focus)': 'onFocus()',
+    '(blur)': 'onBlur()',
+    '(keydown.escape)': 'onEscape()',
+    '[attr.aria-describedby]': 'context.open() ? context.tooltipId : null',
+    '[attr.data-state]': 'context.open() ? "open" : "closed"',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class TooltipTrigger implements OnDestroy {
+  protected readonly context = inject(TOOLTIP_CONTEXT);
+
+  /** Change the default rendered element for the one passed as a child */
+  readonly asChild = input<boolean>(false);
+
+  private showTimeout: ReturnType<typeof setTimeout> | null = null;
+  private hideTimeout: ReturnType<typeof setTimeout> | null = null;
+
+  ngOnDestroy(): void {
+    this.clearTimeouts();
+  }
+
+  onMouseEnter(): void {
+    this.clearTimeouts();
+    this.showTimeout = setTimeout(() => {
+      this.context.setOpen(true);
+    }, this.context.delayDuration);
+  }
+
+  onMouseLeave(): void {
+    this.clearTimeouts();
+    // Small delay to allow moving to tooltip content
+    this.hideTimeout = setTimeout(() => {
+      this.context.setOpen(false);
+    }, 100);
+  }
+
+  onFocus(): void {
+    // Show immediately on focus for keyboard users
+    this.context.setOpen(true);
+  }
+
+  onBlur(): void {
+    this.context.setOpen(false);
+  }
+
+  /**
+   * Escape key handler for WCAG 1.4.13 compliance.
+   * Content on hover/focus must be dismissible via Escape.
+   */
+  onEscape(): void {
+    if (this.context.open()) {
+      this.context.setOpen(false);
+    }
+  }
+
+  private clearTimeouts(): void {
+    if (this.showTimeout) {
+      clearTimeout(this.showTimeout);
+      this.showTimeout = null;
+    }
+    if (this.hideTimeout) {
+      clearTimeout(this.hideTimeout);
+      this.hideTimeout = null;
+    }
+  }
+}

package/src/app/lib/components/ui/tooltip/tooltip.component.ts

@@ -0,0 +1,159 @@
+import {
+    ChangeDetectionStrategy,
+    Component,
+    forwardRef,
+    input,
+    output,
+    signal,
+} from '@angular/core';
+import { TOOLTIP_CONTEXT, type TooltipContextValue } from './tooltip-context';
+
+let tooltipIdCounter = 0;
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type TooltipState = 'open' | 'closed';
+
+/**
+ * Props for the Tooltip component
+ */
+export interface TooltipProps {
+  /** The open state of the tooltip when initially rendered.
+   * Use when you do not need to control its open state.
+   * @default false */
+  defaultOpen?: boolean;
+  /** The controlled open state of the tooltip.
+   * Must be used in conjunction with onOpenChange. */
+  open?: boolean;
+  /** The duration from when the pointer enters the trigger until the tooltip opens.
+   * @default 700 */
+  delayDuration?: number;
+  /** How much time a user has to enter another trigger without incurring a delay again.
+   * @default 300 */
+  skipDelayDuration?: number;
+  /** When true, clicking on trigger will not close the tooltip.
+   * @default false */
+  disableHoverableContent?: boolean;
+}
+
+// ============================================================================
+// Component
+// ============================================================================
+
+/**
+ * @component Tooltip
+ *
+ * A popup that displays information related to an element when the element
+ * receives keyboard focus or the mouse hovers over it.
+ *
+ * @description
+ * Tooltip wraps the trigger and content and manages the open/closed state.
+ * It provides context for child components to coordinate behavior.
+ *
+ * ## Features
+ * - Shows on hover and focus
+ * - Supports controlled and uncontrolled state
+ * - Configurable open delay
+ * - Skip delay for rapid hover between tooltips
+ * - Keyboard support (Escape to dismiss)
+ * - ARIA compliant
+ *
+ * ## Accessibility
+ * Implements WCAG 2.1 Content on Hover or Focus (1.4.13):
+ * - Dismissible: Can be dismissed with Escape key
+ * - Hoverable: Content can be hovered without disappearing
+ * - Persistent: Remains visible until user dismisses
+ *
+ * ## Keyboard Navigation
+ * - `Escape` - Dismiss the tooltip
+ *
+ * @example Basic usage
+ * ```html
+ * <Tooltip>
+ *   <TooltipTrigger>
+ *     <button>Hover me</button>
+ *   </TooltipTrigger>
+ *   <TooltipContent>
+ *     <p>Tooltip content</p>
+ *   </TooltipContent>
+ * </Tooltip>
+ * ```
+ *
+ * @example With custom delay
+ * ```html
+ * <Tooltip [delayDuration]="0">
+ *   <TooltipTrigger>Instant tooltip</TooltipTrigger>
+ *   <TooltipContent>Shows immediately</TooltipContent>
+ * </Tooltip>
+ * ```
+ *
+ * @example Controlled
+ * ```html
+ * <Tooltip [open]="isOpen" (openChange)="isOpen = $event">
+ *   <TooltipTrigger>Controlled tooltip</TooltipTrigger>
+ *   <TooltipContent>Controlled content</TooltipContent>
+ * </Tooltip>
+ * ```
+ *
+ * @data-attributes
+ * - `data-state` - 'open' | 'closed' (on content)
+ */
+@Component({
+  selector: 'Tooltip',
+  template: `<ng-content />`,
+  host: {
+    class: 'relative inline-block',
+  },
+  providers: [
+    {
+      provide: TOOLTIP_CONTEXT,
+      useExisting: forwardRef(() => Tooltip),
+    },
+  ],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class Tooltip implements TooltipContextValue {
+  /** The open state of the tooltip when initially rendered */
+  readonly defaultOpen = input<boolean>(false);
+
+  /** The controlled open state of the tooltip */
+  readonly controlledOpen = input<boolean | undefined>(undefined, { alias: 'open' });
+
+  /** The duration from when the pointer enters the trigger until the tooltip opens */
+  readonly delayDuration = 700;
+
+  /** How much time a user has to enter another trigger without incurring a delay again */
+  readonly skipDelayDuration = 300;
+
+  /** When true, trying to hover the content will result in the tooltip closing */
+  readonly disableHoverableContent = input<boolean>(false);
+
+  /** Event handler called when the open state changes */
+  readonly openChange = output<boolean>();
+
+  /** Unique ID for aria-describedby relationship */
+  readonly tooltipId = `tooltip-${++tooltipIdCounter}`;
+
+  readonly open = signal(false);
+
+  constructor() {
+    // Initialize from defaultOpen
+    if (this.defaultOpen()) {
+      this.open.set(true);
+    }
+  }
+
+  setOpen(open: boolean): void {
+    const controlled = this.controlledOpen();
+    if (controlled === undefined) {
+      this.open.set(open);
+    }
+    this.openChange.emit(open);
+  }
+
+  isOpen(): boolean {
+    return this.controlledOpen() !== undefined ? this.controlledOpen()! : this.open();
+  }
+}

package/src/app/lib/components/ui/typography/index.ts

@@ -0,0 +1,13 @@
+export { TypographyBlockquote } from './typography-blockquote.component';
+export { TypographyH1 } from './typography-h1.component';
+export { TypographyH2 } from './typography-h2.component';
+export { TypographyH3 } from './typography-h3.component';
+export { TypographyH4 } from './typography-h4.component';
+export { TypographyInlineCode } from './typography-inline-code.component';
+export { TypographyLarge } from './typography-large.component';
+export { TypographyLead } from './typography-lead.component';
+export { TypographyList } from './typography-list.component';
+export { TypographyMuted } from './typography-muted.component';
+export { TypographyP } from './typography-p.component';
+export { TypographySmall } from './typography-small.component';
+

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

@@ -0,0 +1,31 @@
+import { cn } from '@/lib/utils';
+import {
+    ChangeDetectionStrategy,
+    Component,
+    computed,
+    input,
+} from '@angular/core';
+
+/**
+ * Typography Blockquote component
+ *
+ * @example
+ * <TypographyBlockquote>
+ *   "This is a quote from someone important."
+ * </TypographyBlockquote>
+ */
+@Component({
+  selector: 'TypographyBlockquote',
+  template: `<ng-content />`,
+  host: {
+    '[class]': 'computedClass()',
+    style: 'display: block',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class TypographyBlockquote {
+  readonly class = input<string>('');
+  protected readonly computedClass = computed(() =>
+    cn('mt-6 border-l-2 pl-6 italic', this.class())
+  );
+}

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

@@ -0,0 +1,32 @@
+import { cn } from '@/lib/utils';
+import {
+    ChangeDetectionStrategy,
+    Component,
+    computed,
+    input,
+} from '@angular/core';
+
+/**
+ * Typography H1 component
+ *
+ * @example
+ * <TypographyH1>Heading 1</TypographyH1>
+ */
+@Component({
+  selector: 'TypographyH1',
+  template: `<ng-content />`,
+  host: {
+    '[class]': 'computedClass()',
+    style: 'display: block',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class TypographyH1 {
+  readonly class = input<string>('');
+  protected readonly computedClass = computed(() =>
+    cn(
+      'scroll-m-20 text-4xl font-extrabold tracking-tight lg:text-5xl',
+      this.class()
+    )
+  );
+}

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

@@ -0,0 +1,32 @@
+import { cn } from '@/lib/utils';
+import {
+    ChangeDetectionStrategy,
+    Component,
+    computed,
+    input,
+} from '@angular/core';
+
+/**
+ * Typography H2 component
+ *
+ * @example
+ * <TypographyH2>Heading 2</TypographyH2>
+ */
+@Component({
+  selector: 'TypographyH2',
+  template: `<ng-content />`,
+  host: {
+    '[class]': 'computedClass()',
+    style: 'display: block',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class TypographyH2 {
+  readonly class = input<string>('');
+  protected readonly computedClass = computed(() =>
+    cn(
+      'scroll-m-20 border-b pb-2 text-3xl font-semibold tracking-tight first:mt-0',
+      this.class()
+    )
+  );
+}

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

@@ -0,0 +1,29 @@
+import { cn } from '@/lib/utils';
+import {
+    ChangeDetectionStrategy,
+    Component,
+    computed,
+    input,
+} from '@angular/core';
+
+/**
+ * Typography H3 component
+ *
+ * @example
+ * <TypographyH3>Heading 3</TypographyH3>
+ */
+@Component({
+  selector: 'TypographyH3',
+  template: `<ng-content />`,
+  host: {
+    '[class]': 'computedClass()',
+    style: 'display: block',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class TypographyH3 {
+  readonly class = input<string>('');
+  protected readonly computedClass = computed(() =>
+    cn('scroll-m-20 text-2xl font-semibold tracking-tight', this.class())
+  );
+}

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

@@ -0,0 +1,29 @@
+import { cn } from '@/lib/utils';
+import {
+    ChangeDetectionStrategy,
+    Component,
+    computed,
+    input,
+} from '@angular/core';
+
+/**
+ * Typography H4 component
+ *
+ * @example
+ * <TypographyH4>Heading 4</TypographyH4>
+ */
+@Component({
+  selector: 'TypographyH4',
+  template: `<ng-content />`,
+  host: {
+    '[class]': 'computedClass()',
+    style: 'display: block',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class TypographyH4 {
+  readonly class = input<string>('');
+  protected readonly computedClass = computed(() =>
+    cn('scroll-m-20 text-xl font-semibold tracking-tight', this.class())
+  );
+}

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

@@ -0,0 +1,31 @@
+import { cn } from '@/lib/utils';
+import {
+    ChangeDetectionStrategy,
+    Component,
+    computed,
+    input,
+} from '@angular/core';
+
+/**
+ * Typography InlineCode component
+ *
+ * @example
+ * <TypographyInlineCode>npm install</TypographyInlineCode>
+ */
+@Component({
+  selector: 'TypographyInlineCode',
+  template: `<ng-content />`,
+  host: {
+    '[class]': 'computedClass()',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class TypographyInlineCode {
+  readonly class = input<string>('');
+  protected readonly computedClass = computed(() =>
+    cn(
+      'relative rounded bg-muted px-[0.3rem] py-[0.2rem] font-mono text-sm font-semibold',
+      this.class()
+    )
+  );
+}

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

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

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

@@ -0,0 +1,31 @@
+import { cn } from '@/lib/utils';
+import {
+    ChangeDetectionStrategy,
+    Component,
+    computed,
+    input,
+} from '@angular/core';
+
+/**
+ * Typography Lead component - larger intro text
+ *
+ * @example
+ * <TypographyLead>
+ *   A modal dialog that interrupts the user with important content.
+ * </TypographyLead>
+ */
+@Component({
+  selector: 'TypographyLead',
+  template: `<ng-content />`,
+  host: {
+    '[class]': 'computedClass()',
+    style: 'display: block',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class TypographyLead {
+  readonly class = input<string>('');
+  protected readonly computedClass = computed(() =>
+    cn('text-xl text-muted-foreground', this.class())
+  );
+}