@ng-cn/core 1.0.10 → 1.0.12

package/src/app/lib/components/ui/form/form-message.component.ts

@@ -0,0 +1,107 @@
+import { cn } from '@/lib/utils';
+import {
+    ChangeDetectionStrategy,
+    Component,
+    computed,
+    inject,
+    input,
+} from '@angular/core';
+import { FORM_FIELD_CONTEXT } from './form-context';
+
+/**
+ * FormMessage component - displays validation error messages.
+ *
+ * @example
+ * <FormMessage />
+ *
+ * <!-- Or with custom message -->
+ * <FormMessage>Custom error message</FormMessage>
+ */
+@Component({
+  selector: 'FormMessage',
+  template: `
+    @if (errorMessage() || hasContent) {
+      <ng-content />
+      @if (!hasContent && errorMessage()) {
+        {{ errorMessage() }}
+      }
+    }
+  `,
+  host: {
+    '[class]': 'computedClass()',
+    '[attr.id]': 'fieldContext?.formMessageId()',
+    '[attr.role]': 'hasError() ? "alert" : null',
+    'data-slot': 'form-message',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class FormMessage {
+  protected readonly fieldContext = inject(FORM_FIELD_CONTEXT, { optional: true });
+
+  /** Additional CSS classes to apply */
+  readonly class = input<string>('');
+
+  /** Whether component has projected content */
+  hasContent = false;
+
+  /** Check if field has error */
+  protected readonly hasError = computed(() => {
+    const control = this.fieldContext?.control();
+    return control?.invalid && (control?.dirty || control?.touched);
+  });
+
+  /** Get first error message */
+  protected readonly errorMessage = computed(() => {
+    const control = this.fieldContext?.control();
+    if (!control?.errors || !this.hasError()) return null;
+
+    const errors = control.errors;
+    const errorKeys = Object.keys(errors);
+    if (errorKeys.length === 0) return null;
+
+    const firstErrorKey = errorKeys[0];
+    const errorValue = errors[firstErrorKey];
+
+    // Handle common error types
+    switch (firstErrorKey) {
+      case 'required':
+        return 'This field is required';
+      case 'minlength':
+        return `Minimum length is ${errorValue.requiredLength} characters`;
+      case 'maxlength':
+        return `Maximum length is ${errorValue.requiredLength} characters`;
+      case 'min':
+        return `Minimum value is ${errorValue.min}`;
+      case 'max':
+        return `Maximum value is ${errorValue.max}`;
+      case 'email':
+        return 'Please enter a valid email address';
+      case 'pattern':
+        return 'Invalid format';
+      default:
+        // If error is a string, return it directly
+        if (typeof errorValue === 'string') {
+          return errorValue;
+        }
+        // If error has a message property
+        if (errorValue?.message) {
+          return errorValue.message;
+        }
+        return 'Invalid value';
+    }
+  });
+
+  /** Computed class combining base styles and custom classes */
+  protected readonly computedClass = computed(() =>
+    cn(
+      'text-destructive text-[0.8rem] font-medium',
+      !this.hasError() && !this.hasContent && 'hidden',
+      this.class()
+    )
+  );
+
+  ngAfterContentInit() {
+    // Check if there's projected content
+    // This is a simplified check - in production you might want to use ContentChild
+  }
+}

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

@@ -0,0 +1,123 @@
+import { cn } from '@/lib/utils';
+import {
+    ChangeDetectionStrategy,
+    Component,
+    computed,
+    forwardRef,
+    input,
+    signal,
+} from '@angular/core';
+import { FormGroup, ReactiveFormsModule } from '@angular/forms';
+import { FORM_CONTEXT, type FormContext } from './form-context';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Props for the Form component
+ */
+export interface FormProps {
+  /** The reactive form group to bind to */
+  formGroup?: FormGroup | null;
+  /** Additional CSS classes */
+  class?: string;
+}
+
+// ============================================================================
+// Component
+// ============================================================================
+
+/**
+ * @component Form
+ *
+ * Building forms with Angular Reactive Forms.
+ *
+ * @description
+ * Form provides a wrapper for Angular Reactive Forms that integrates with
+ * the form component system for consistent styling and accessibility.
+ *
+ * ## Features
+ * - Integrates with Angular Reactive Forms
+ * - Provides context for FormField, FormItem, FormLabel, etc.
+ * - Automatic error message display
+ * - Accessible form structure with proper ARIA relationships
+ * - Consistent validation styling
+ *
+ * ## Form Components
+ * - `Form` - Wrapper providing form context
+ * - `FormField` - Wraps a form control with context
+ * - `FormItem` - Container for label, control, description, message
+ * - `FormLabel` - Label with accessibility bindings
+ * - `FormControl` - Control with ARIA attributes
+ * - `FormDescription` - Helper text for the field
+ * - `FormMessage` - Error/validation messages
+ *
+ * ## Accessibility
+ * - `aria-describedby` links controls to description and errors
+ * - `aria-invalid` when field has errors
+ * - Labels properly associated with controls
+ *
+ * @example Basic usage
+ * ```html
+ * <Form [formGroup]="loginForm" (ngSubmit)="onSubmit()">
+ *   <FormField name="email">
+ *     <FormItem>
+ *       <FormLabel>Email</FormLabel>
+ *       <FormControl>
+ *         <Input type="email" formControlName="email" />
+ *       </FormControl>
+ *       <FormDescription>Enter your email address</FormDescription>
+ *       <FormMessage />
+ *     </FormItem>
+ *   </FormField>
+ *   <Button type="submit">Submit</Button>
+ * </Form>
+ * ```
+ *
+ * @example With validation
+ * ```typescript
+ * loginForm = this.fb.group({
+ *   email: ['', [Validators.required, Validators.email]],
+ *   password: ['', [Validators.required, Validators.minLength(8)]],
+ * });
+ * ```
+ */
+@Component({
+  selector: 'Form',
+  imports: [ReactiveFormsModule],
+  template: `<ng-content />`,
+  host: {
+    '[class]': 'computedClass()',
+    'data-slot': 'form',
+  },
+  providers: [
+    {
+      provide: FORM_CONTEXT,
+      useFactory: (component: Form) => component.context,
+      deps: [forwardRef(() => Form)],
+    },
+  ],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class Form {
+  /** The reactive form group */
+  readonly formGroup = input<FormGroup | null>(null);
+
+  /** Additional CSS classes */
+  readonly class = input<string>('');
+
+  /** Context for child components */
+  readonly context: FormContext = {
+    form: signal(this.formGroup()),
+  };
+
+  /** Computed class combining base styles and custom classes */
+  protected readonly computedClass = computed(() =>
+    cn('space-y-6', this.class())
+  );
+
+  ngOnChanges() {
+    this.context.form.set(this.formGroup());
+  }
+}

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

@@ -0,0 +1,17 @@
+// Context and types
+export {
+    FORM_CONTEXT,
+    FORM_FIELD_CONTEXT,
+    type FormContext,
+    type FormFieldContext
+} from './form-context';
+
+// Components and their types
+export { FormControl, FormControlInput } from './form-control.component';
+export { FormDescription } from './form-description.component';
+export { FormField } from './form-field.component';
+export { FormItem } from './form-item.component';
+export { FormLabel } from './form-label.component';
+export { FormMessage } from './form-message.component';
+export { Form, type FormProps } from './form.component';
+

package/src/app/lib/components/ui/hover-card/hover-card-content.component.ts

@@ -0,0 +1,203 @@
+import { cn, Presence } from '@/lib/utils';
+import {
+    ChangeDetectionStrategy,
+    Component,
+    computed,
+    ElementRef,
+    inject,
+    input,
+    OnDestroy,
+} from '@angular/core';
+import { HOVER_CARD_CONTEXT, HoverCardAlign, HoverCardSide } from './hover-card-context';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type HoverCardContentState = 'open' | 'closed';
+
+/**
+ * Props for the HoverCardContent component
+ */
+export interface HoverCardContentProps {
+  /** The preferred side of the trigger to render against.
+   * @default 'bottom' */
+  side?: HoverCardSide;
+  /** The distance in pixels from the trigger.
+   * @default 4 */
+  sideOffset?: number;
+  /** The preferred alignment against the trigger.
+   * @default 'center' */
+  align?: HoverCardAlign;
+  /** Additional CSS classes */
+  class?: string;
+}
+
+// ============================================================================
+// Component
+// ============================================================================
+
+/**
+ * @component HoverCardContent
+ *
+ * The component that pops out when the hover card is open.
+ *
+ * @description
+ * HoverCardContent displays the preview content. It stays open when
+ * hovered, allowing users to interact with the content.
+ *
+ * ## Features
+ * - Stays open when content is hovered
+ * - Configurable side and alignment
+ * - Smooth animations
+ * - Escape key to dismiss
+ *
+ * ## Accessibility
+ * - `role="dialog"` on the content
+ * - Focusable content items
+ * - Escape returns focus to trigger
+ *
+ * @example Basic usage
+ * ```html
+ * <HoverCardContent>
+ *   <p>Preview content</p>
+ * </HoverCardContent>
+ * ```
+ *
+ * @example With positioning
+ * ```html
+ * <HoverCardContent side="right" align="start">
+ *   <p>Right-aligned content</p>
+ * </HoverCardContent>
+ * ```
+ *
+ * @data-attributes
+ * - `data-state` - 'open' | 'closed'
+ * - `data-side` - 'top' | 'right' | 'bottom' | 'left'
+ * - `data-align` - 'start' | 'center' | 'end'
+ */
+@Component({
+  selector: 'HoverCardContent',
+  imports: [Presence],
+  template: `
+    <Presence [present]="context.open()">
+      <div
+        role="dialog"
+        [attr.aria-modal]="false"
+        tabindex="-1"
+        [class]="computedClass()"
+        [attr.data-state]="state()"
+        [attr.data-side]="side()"
+        [attr.data-align]="align()"
+        data-slot="hover-card-content"
+        (mouseenter)="onMouseEnter()"
+        (mouseleave)="onMouseLeave()"
+        (focusin)="onFocusIn()"
+        (focusout)="onFocusOut($event)"
+        (keydown.escape)="onEscape()"
+      >
+        <ng-content />
+      </div>
+    </Presence>
+  `,
+  host: {
+    class: 'contents',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class HoverCardContent implements OnDestroy {
+  protected readonly context = inject(HOVER_CARD_CONTEXT);
+  private readonly elementRef = inject(ElementRef<HTMLElement>);
+
+  /** The preferred side of the trigger to render against */
+  readonly side = input<HoverCardSide>('bottom');
+
+  /** The distance in pixels from the trigger */
+  readonly sideOffset = input<number>(4);
+
+  /** The preferred alignment against the trigger */
+  readonly align = input<HoverCardAlign>('center');
+
+  /** Additional CSS classes */
+  readonly class = input<string>('');
+
+  private closeTimeout: ReturnType<typeof setTimeout> | null = null;
+
+  /** Current state: open or closed */
+  protected readonly state = computed<HoverCardContentState>(() =>
+    this.context.open() ? 'open' : 'closed'
+  );
+
+  protected readonly computedClass = computed(() => {
+    const sideClasses = {
+      top: 'bottom-full mb-2',
+      bottom: 'top-full mt-2',
+      left: 'right-full mr-2',
+      right: 'left-full ml-2',
+    };
+
+    const alignClasses = {
+      start: 'left-0',
+      center: 'left-1/2 -translate-x-1/2',
+      end: 'right-0',
+    };
+
+    return cn(
+      'absolute z-50 w-64 rounded-md border bg-popover p-4 text-popover-foreground shadow-md outline-none',
+      'data-[state=open]:animate-in data-[state=closed]:animate-out',
+      'data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0',
+      'data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95',
+      'data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2',
+      'data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2',
+      sideClasses[this.side()],
+      this.side() === 'top' || this.side() === 'bottom' ? alignClasses[this.align()] : '',
+      this.class()
+    );
+  });
+
+  ngOnDestroy(): void {
+    this.clearTimeout();
+  }
+
+  onMouseEnter(): void {
+    this.clearTimeout();
+  }
+
+  onMouseLeave(): void {
+    this.closeTimeout = setTimeout(() => {
+      this.context.setOpen(false);
+    }, this.context.closeDelay);
+  }
+
+  onFocusIn(): void {
+    this.clearTimeout();
+  }
+
+  onFocusOut(event: FocusEvent): void {
+    const relatedTarget = event.relatedTarget as HTMLElement | null;
+    const trigger = this.elementRef.nativeElement.parentElement?.querySelector('[data-state]');
+
+    // Check if focus moved to trigger or stayed within content
+    if (relatedTarget && (trigger === relatedTarget || trigger?.contains(relatedTarget))) {
+      return;
+    }
+
+    this.closeTimeout = setTimeout(() => {
+      this.context.setOpen(false);
+    }, this.context.closeDelay);
+  }
+
+  onEscape(): void {
+    this.context.setOpen(false);
+    // Return focus to trigger
+    const trigger = this.elementRef.nativeElement.parentElement?.querySelector('[data-state]') as HTMLElement;
+    trigger?.focus();
+  }
+
+  private clearTimeout(): void {
+    if (this.closeTimeout) {
+      clearTimeout(this.closeTimeout);
+      this.closeTimeout = null;
+    }
+  }
+}

package/src/app/lib/components/ui/hover-card/hover-card-context.ts

@@ -0,0 +1,25 @@
+import { InjectionToken, WritableSignal } from '@angular/core';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type HoverCardSide = 'top' | 'right' | 'bottom' | 'left';
+export type HoverCardAlign = 'start' | 'center' | 'end';
+
+export interface HoverCardContextValue {
+  /** Signal for open state */
+  open: WritableSignal<boolean>;
+  /** Set open state */
+  setOpen: (open: boolean) => void;
+  /** The duration from when the pointer enters the trigger until the hover card opens (ms) */
+  openDelay: number;
+  /** The duration from when the pointer leaves the trigger/content until the hover card closes (ms) */
+  closeDelay: number;
+}
+
+// ============================================================================
+// Injection Tokens
+// ============================================================================
+
+export const HOVER_CARD_CONTEXT = new InjectionToken<HoverCardContextValue>('HOVER_CARD_CONTEXT');

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

@@ -0,0 +1,160 @@
+import {
+    ChangeDetectionStrategy,
+    Component,
+    ElementRef,
+    inject,
+    input,
+    OnDestroy,
+} from '@angular/core';
+import { HOVER_CARD_CONTEXT } from './hover-card-context';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Props for the HoverCardTrigger component
+ */
+export interface HoverCardTriggerProps {
+  /** Change the default rendered element for the one passed as a child.
+   * @default false */
+  asChild?: boolean;
+}
+
+// ============================================================================
+// Component
+// ============================================================================
+
+/**
+ * @component HoverCardTrigger
+ *
+ * The link that opens the hover card when hovered.
+ *
+ * @description
+ * HoverCardTrigger wraps the element that activates the hover card on hover
+ * or focus. It manages timing for open/close delays.
+ *
+ * ## Features
+ * - Opens on hover with delay
+ * - Opens immediately on focus (keyboard)
+ * - Toggle on Enter/Space (keyboard)
+ * - Escape dismisses and returns focus
+ *
+ * ## Accessibility
+ * - `aria-expanded` reflects open state
+ * - `aria-haspopup="dialog"` indicates content type
+ * - Focus triggers immediate open for keyboard users
+ * - Escape returns focus to trigger
+ *
+ * ## Keyboard Navigation
+ * - `Tab` - Focus triggers hover card
+ * - `Enter` / `Space` - Toggle hover card
+ * - `Escape` - Close and return focus
+ *
+ * @example Basic usage
+ * ```html
+ * <HoverCardTrigger>
+ *   <a href="#">&#64;username</a>
+ * </HoverCardTrigger>
+ * ```
+ *
+ * @example With custom element
+ * ```html
+ * <HoverCardTrigger>
+ *   <span class="cursor-pointer underline">Hover for info</span>
+ * </HoverCardTrigger>
+ * ```
+ *
+ * @data-attributes
+ * - `data-state` - 'open' | 'closed'
+ */
+@Component({
+  selector: 'HoverCardTrigger',
+  template: `<ng-content />`,
+  host: {
+    'tabindex': '0',
+    'role': 'button',
+    '(mouseenter)': 'onMouseEnter()',
+    '(mouseleave)': 'onMouseLeave()',
+    '(focus)': 'onFocus()',
+    '(blur)': 'onBlur($event)',
+    '(keydown.enter)': 'onKeyDown($event)',
+    '(keydown.space)': 'onKeyDown($event)',
+    '(keydown.escape)': 'onEscape()',
+    '[attr.data-state]': 'context.open() ? "open" : "closed"',
+    '[attr.aria-expanded]': 'context.open()',
+    '[attr.aria-haspopup]': '"dialog"',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class HoverCardTrigger implements OnDestroy {
+  protected readonly context = inject(HOVER_CARD_CONTEXT);
+  private readonly elementRef = inject(ElementRef<HTMLElement>);
+
+  /** Change the default rendered element for the one passed as a child */
+  readonly asChild = input<boolean>(false);
+
+  private openTimeout: ReturnType<typeof setTimeout> | null = null;
+  private closeTimeout: ReturnType<typeof setTimeout> | null = null;
+
+  ngOnDestroy(): void {
+    this.clearTimeouts();
+  }
+
+  onMouseEnter(): void {
+    this.clearTimeouts();
+    this.openTimeout = setTimeout(() => {
+      this.context.setOpen(true);
+    }, this.context.openDelay);
+  }
+
+  onMouseLeave(): void {
+    this.clearTimeouts();
+    this.closeTimeout = setTimeout(() => {
+      this.context.setOpen(false);
+    }, this.context.closeDelay);
+  }
+
+  onFocus(): void {
+    this.clearTimeouts();
+    // Open immediately on focus for keyboard users
+    this.context.setOpen(true);
+  }
+
+  onBlur(event: FocusEvent): void {
+    // Check if focus moved to the hover card content
+    const relatedTarget = event.relatedTarget as HTMLElement | null;
+    const hoverCardContent = this.elementRef.nativeElement.parentElement?.querySelector('[data-slot="hover-card-content"]');
+
+    if (relatedTarget && hoverCardContent?.contains(relatedTarget)) {
+      // Focus moved to content, don't close
+      return;
+    }
+
+    this.clearTimeouts();
+    this.closeTimeout = setTimeout(() => {
+      this.context.setOpen(false);
+    }, this.context.closeDelay);
+  }
+
+  onKeyDown(event: Event): void {
+    event.preventDefault();
+    this.context.setOpen(!this.context.open());
+  }
+
+  onEscape(): void {
+    this.context.setOpen(false);
+    this.elementRef.nativeElement.focus();
+  }
+
+  private clearTimeouts(): void {
+    if (this.openTimeout) {
+      clearTimeout(this.openTimeout);
+      this.openTimeout = null;
+    }
+    if (this.closeTimeout) {
+      clearTimeout(this.closeTimeout);
+      this.closeTimeout = null;
+    }
+  }
+}