@ng-cn/core 1.0.10 → 1.0.12

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

@@ -0,0 +1,263 @@
+import { cn } from '@/lib/utils';
+import { AriaIdService } from '@/lib/utils/accessibility';
+import {
+    ChangeDetectionStrategy,
+    Component,
+    computed,
+    effect,
+    ElementRef,
+    forwardRef,
+    inject,
+    input,
+    model,
+    output,
+    signal,
+} from '@angular/core';
+import { SELECT_CONTEXT, type SelectContext } from './select-context';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type SelectState = 'open' | 'closed';
+
+/**
+ * Props for the Select component
+ */
+export interface SelectProps {
+  /** The value of the select when initially rendered.
+   * Use when you do not need to control the state of the select. */
+  defaultValue?: string;
+  /** The controlled value of the select.
+   * Should be used in conjunction with onValueChange. */
+  value?: string;
+  /** The controlled open state of the select.
+   * Must be used in conjunction with onOpenChange. */
+  open?: boolean;
+  /** When true, prevents the user from interacting with select.
+   * @default false */
+  disabled?: boolean;
+  /** The name of the select. Submitted with its owning form as part of a name/value pair. */
+  name?: string;
+  /** When true, indicates that the user must select a value before the owning form can be submitted.
+   * @default false */
+  required?: boolean;
+  /** Additional CSS classes */
+  class?: string;
+}
+
+// ============================================================================
+// Component
+// ============================================================================
+
+/**
+ * @component Select
+ *
+ * Displays a list of options for the user to pick from—triggered by a button.
+ *
+ * @description
+ * Select provides a dropdown selection input that implements the WAI-ARIA
+ * listbox pattern with full keyboard navigation.
+ *
+ * ## Features
+ * - Full keyboard navigation
+ * - Supports controlled and uncontrolled usage
+ * - Groups and separators for organizing options
+ * - Disabled items and groups
+ * - Custom trigger and value display
+ * - Form submission with native hidden input
+ *
+ * ## Accessibility
+ * Implements the WAI-ARIA Listbox Pattern:
+ * - `role="listbox"` on content
+ * - `role="option"` on items
+ * - `aria-expanded` on trigger
+ * - `aria-labelledby` relationships
+ * - Roving tabindex for keyboard navigation
+ *
+ * ## Keyboard Navigation
+ * When focus is on the trigger:
+ * - `Enter` / `Space` / `ArrowDown` / `ArrowUp` - Open the select
+ *
+ * When focus is on an item:
+ * - `Enter` / `Space` - Select the focused item
+ * - `ArrowDown` - Focus next item
+ * - `ArrowUp` - Focus previous item
+ * - `Home` - Focus first item
+ * - `End` - Focus last item
+ * - `Escape` - Close the select
+ * - Type to search - Focus matching item
+ *
+ * @example Basic usage
+ * ```html
+ * <Select [(value)]="selectedFruit">
+ *   <SelectTrigger class="w-[180px]">
+ *     <SelectValue placeholder="Select a fruit" />
+ *   </SelectTrigger>
+ *   <SelectContent>
+ *     <SelectItem value="apple">Apple</SelectItem>
+ *     <SelectItem value="banana">Banana</SelectItem>
+ *     <SelectItem value="orange">Orange</SelectItem>
+ *   </SelectContent>
+ * </Select>
+ * ```
+ *
+ * @example With groups
+ * ```html
+ * <Select>
+ *   <SelectTrigger>
+ *     <SelectValue placeholder="Select a timezone" />
+ *   </SelectTrigger>
+ *   <SelectContent>
+ *     <SelectGroup>
+ *       <SelectLabel>North America</SelectLabel>
+ *       <SelectItem value="est">Eastern Time</SelectItem>
+ *       <SelectItem value="cst">Central Time</SelectItem>
+ *     </SelectGroup>
+ *     <SelectSeparator />
+ *     <SelectGroup>
+ *       <SelectLabel>Europe</SelectLabel>
+ *       <SelectItem value="gmt">GMT</SelectItem>
+ *       <SelectItem value="cet">Central European</SelectItem>
+ *     </SelectGroup>
+ *   </SelectContent>
+ * </Select>
+ * ```
+ *
+ * @example Form usage
+ * ```html
+ * <Select name="fruit" [required]="true">
+ *   <SelectTrigger>
+ *     <SelectValue placeholder="Required field" />
+ *   </SelectTrigger>
+ *   <SelectContent>
+ *     <SelectItem value="apple">Apple</SelectItem>
+ *   </SelectContent>
+ * </Select>
+ * ```
+ *
+ * @data-attributes
+ * - `data-state` - 'open' | 'closed'
+ * - `data-disabled` - Present when disabled
+ */
+@Component({
+  selector: 'Select',
+  template: `<ng-content />`,
+  host: {
+    '[class]': 'computedClass()',
+    '[attr.data-state]': 'context.open() ? "open" : "closed"',
+    '[attr.data-disabled]': 'disabled() ? "" : null',
+    'data-slot': 'select',
+  },
+  providers: [
+    {
+      provide: SELECT_CONTEXT,
+      useFactory: (component: Select) => component.context,
+      deps: [forwardRef(() => Select)],
+    },
+  ],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class Select {
+  private readonly elementRef = inject(ElementRef<HTMLElement>);
+  private readonly ariaIdService = inject(AriaIdService);
+  private readonly ariaIds = this.ariaIdService.generateMenuIds('select');
+
+  /** The controlled value of the select */
+  readonly value = model<string>('');
+
+  /** The controlled open state of the select */
+  readonly open = model<boolean>(false);
+
+  /** When true, prevents the user from interacting with select */
+  readonly disabled = input<boolean>(false);
+
+  /** The name of the select for form submission */
+  readonly name = input<string>('');
+
+  /** When true, indicates that the user must select a value */
+  readonly required = input<boolean>(false);
+
+  /** Additional CSS classes */
+  readonly class = input<string>('');
+
+  /** Event handler called when the value changes */
+  readonly valueChange = output<string>();
+
+  /** Event handler called when the open state changes */
+  readonly openChange = output<boolean>();
+
+  /** Internal signals for context */
+  private readonly _value = signal<string>('');
+  private readonly _open = signal<boolean>(false);
+  private readonly _disabled = signal<boolean>(false);
+
+  /** Context for child components */
+  readonly context: SelectContext = {
+    value: this._value,
+    open: this._open,
+    disabled: this._disabled,
+    placeholder: signal(''),
+    selectedLabel: signal(''),
+    contentId: this.ariaIds.contentId,
+    triggerElement: signal<HTMLElement | null>(null),
+    itemValues: signal<string[]>([]),
+    focusedIndex: signal(-1),
+    required: () => this.required(),
+    name: () => this.name(),
+    setValue: (value: string, label?: string) => {
+      this._value.set(value);
+      this.value.set(value);
+      this.valueChange.emit(value);
+      if (label) {
+        this.context.selectedLabel.set(label);
+      }
+      this._open.set(false);
+      this.open.set(false);
+      this.openChange.emit(false);
+      // Restore focus to trigger
+      const trigger = this.context.triggerElement();
+      if (trigger) {
+        setTimeout(() => trigger.focus());
+      }
+    },
+    focusItem: (index: number) => this.focusItemByIndex(index),
+  };
+
+  /** Computed class combining base styles and custom classes */
+  protected readonly computedClass = computed(() =>
+    cn('relative inline-block', this.class())
+  );
+
+  constructor() {
+    // Sync value input to internal signal
+    effect(() => {
+      this._value.set(this.value());
+    });
+
+    // Sync open input to internal signal
+    effect(() => {
+      this._open.set(this.open());
+    });
+
+    // Sync disabled input to internal signal
+    effect(() => {
+      this._disabled.set(this.disabled());
+    });
+  }
+
+  /** Focus an item by index */
+  private focusItemByIndex(index: number): void {
+    const values = this.context.itemValues();
+    if (index < 0 || index >= values.length) return;
+
+    this.context.focusedIndex.set(index);
+    const value = values[index];
+    const item = this.elementRef.nativeElement.querySelector(
+      `[data-slot="select-item"][data-value="${value}"]`
+    ) as HTMLElement;
+    if (item) {
+      item.focus();
+    }
+  }
+}

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

@@ -0,0 +1,6 @@
+export {
+    Separator,
+    type SeparatorOrientation,
+    type SeparatorProps
+} from './separator.component';
+

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

@@ -0,0 +1,128 @@
+import { cn } from '@/lib/utils';
+import {
+    ChangeDetectionStrategy,
+    Component,
+    computed,
+    input,
+} from '@angular/core';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type SeparatorOrientation = 'horizontal' | 'vertical';
+
+export type SeparatorProps = {
+  /** The orientation of the separator */
+  orientation?: SeparatorOrientation;
+  /**
+   * Whether the separator is purely decorative.
+   * When true, removes from accessibility tree (role="none").
+   * When false, uses role="separator" for screen readers.
+   */
+  decorative?: boolean;
+  /** Additional CSS classes to apply */
+  class?: string;
+};
+
+// ============================================================================
+// Separator Component
+// ============================================================================
+
+/**
+ * Separator component creates a visual divider between content.
+ * Based on Radix UI Separator primitive with shadcn/ui styling.
+ *
+ * ## Features
+ * - Horizontal or vertical orientation
+ * - Decorative mode for purely visual separators
+ * - Semantic separator role for accessibility when not decorative
+ * - Full ARIA support
+ *
+ * ## Accessibility
+ * - Uses `role="separator"` for semantic meaning (unless decorative)
+ * - `aria-orientation` indicates the separator direction
+ * - Decorative separators are hidden from assistive technology
+ *
+ * @example
+ * <!-- Horizontal separator (default) -->
+ * <div class="space-y-4">
+ *   <p>Some content above</p>
+ *   <Separator />
+ *   <p>Some content below</p>
+ * </div>
+ *
+ * @example
+ * <!-- Vertical separator -->
+ * <div class="flex h-5 items-center space-x-4 text-sm">
+ *   <span>Blog</span>
+ *   <Separator orientation="vertical" />
+ *   <span>Docs</span>
+ *   <Separator orientation="vertical" />
+ *   <span>Source</span>
+ * </div>
+ *
+ * @example
+ * <!-- Decorative separator (hidden from screen readers) -->
+ * <Separator [decorative]="true" />
+ *
+ * @example
+ * <!-- With custom styling -->
+ * <Separator class="my-4 bg-primary/50" />
+ *
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/separator Radix Separator}
+ * @see {@link https://ui.shadcn.com/docs/components/separator shadcn/ui Separator}
+ */
+@Component({
+  selector: 'Separator',
+  template: ``,
+  host: {
+    '[class]': 'computedClass()',
+    '[attr.role]': 'role()',
+    '[attr.aria-orientation]': 'ariaOrientation()',
+    '[attr.data-orientation]': 'orientation()',
+    'data-slot': 'separator',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class Separator {
+  /** The orientation of the separator */
+  readonly orientation = input<SeparatorOrientation>('horizontal');
+
+  /**
+   * Whether the separator is purely decorative.
+   * When true, removes from accessibility tree.
+   */
+  readonly decorative = input<boolean>(false);
+
+  /** Additional CSS classes to apply */
+  readonly class = input<string>('');
+
+  /** Computed role - none for decorative, separator otherwise */
+  protected readonly role = computed(() =>
+    this.decorative() ? 'none' : 'separator'
+  );
+
+  /**
+   * aria-orientation is only needed for non-decorative separators.
+   * Per WAI-ARIA, separators default to horizontal, so we only need
+   * to specify when vertical.
+   */
+  protected readonly ariaOrientation = computed(() => {
+    if (this.decorative()) return undefined;
+    // Only specify aria-orientation for vertical (horizontal is default)
+    return this.orientation() === 'vertical' ? 'vertical' : undefined;
+  });
+
+  /** Computed class based on orientation */
+  protected readonly computedClass = computed(() =>
+    cn(
+      // Base styles
+      'bg-border shrink-0',
+      // Orientation-specific styles
+      this.orientation() === 'horizontal' ? 'h-px w-full' : 'h-full w-px',
+      // Custom classes
+      this.class()
+    )
+  );
+}

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

@@ -0,0 +1,11 @@
+export { SheetClose } from './sheet-close.component';
+export { SheetContent } from './sheet-content.component';
+export { SHEET_CONTEXT, type SheetContextValue } from './sheet-context';
+export { SheetDescription } from './sheet-description.component';
+export { SheetFooter } from './sheet-footer.component';
+export { SheetHeader } from './sheet-header.component';
+export { SheetTitle } from './sheet-title.component';
+export { SheetTrigger } from './sheet-trigger.component';
+export { sheetVariants, type SheetVariants } from './sheet-variants';
+export { Sheet } from './sheet.component';
+

package/src/app/lib/components/ui/sheet/sheet-close.component.ts

@@ -0,0 +1,32 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  inject,
+  input,
+} from '@angular/core';
+import { SHEET_CONTEXT } from './sheet-context';
+
+/**
+ * SheetClose component - button that closes the sheet.
+ * Matches shadcn/ui React SheetClose exactly.
+ */
+@Component({
+  selector: 'SheetClose',
+  template: `<ng-content />`,
+  host: {
+    class: 'contents',
+    '(click)': 'onClick($event)',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class SheetClose {
+  protected readonly context = inject(SHEET_CONTEXT);
+
+  /** Render as child */
+  readonly asChild = input<boolean>(false);
+
+  onClick(event: Event): void {
+    event.stopPropagation();
+    this.context.setOpen(false);
+  }
+}

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

@@ -0,0 +1,157 @@
+import { cn, Presence } from '@/lib/utils';
+import { FocusTrapDirective } from '@/lib/utils/accessibility';
+import {
+    ChangeDetectionStrategy,
+    Component,
+    computed,
+    effect,
+    inject,
+    input,
+    OnDestroy
+} from '@angular/core';
+import { SHEET_CONTEXT } from './sheet-context';
+import { sheetVariants, type SheetVariants } from './sheet-variants';
+
+/**
+ * SheetContent component - the content of the sheet panel.
+ * Matches shadcn/ui React SheetContent exactly.
+ * Includes focus trapping, focus restoration, proper ARIA relationships,
+ * and Radix-compatible exit animations via Presence component.
+ */
+@Component({
+  selector: 'SheetContent',
+  imports: [FocusTrapDirective, Presence],
+  template: `
+    <Presence [present]="context.open()">
+      <!-- Overlay -->
+      <div
+        class="fixed inset-0 z-[100] bg-black/50 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0"
+        [attr.data-state]="context.open() ? 'open' : 'closed'"
+        (click)="onOverlayClick($event)"
+        aria-hidden="true"
+      ></div>
+      <!-- Content -->
+      <div
+        hlmFocusTrap
+        [trapFocus]="context.open()"
+        [autoFocus]="true"
+        [restoreFocus]="false"
+        [class]="computedClass()"
+        [attr.data-state]="context.open() ? 'open' : 'closed'"
+        [attr.data-side]="side()"
+        [attr.id]="context.contentId"
+        [attr.aria-labelledby]="context.titleId"
+        [attr.aria-describedby]="context.descriptionId"
+        role="dialog"
+        aria-modal="true"
+        (keydown.escape)="onEscapeKey()"
+      >
+        <ng-content />
+        <!-- Close button -->
+        <button
+          type="button"
+          class="absolute right-4 top-4 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none data-[state=open]:bg-secondary"
+          (click)="onClose()"
+          aria-label="Close sheet"
+        >
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="24"
+            height="24"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+            class="h-4 w-4"
+            aria-hidden="true"
+          >
+            <path d="M18 6 6 18" />
+            <path d="m6 6 12 12" />
+          </svg>
+          <span class="sr-only">Close</span>
+        </button>
+      </div>
+    </Presence>
+  `,
+  host: {
+    class: 'contents',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class SheetContent implements OnDestroy {
+  protected readonly context = inject(SHEET_CONTEXT);
+
+  /** Side from which the sheet appears */
+  readonly side = input<SheetVariants['side']>('right');
+
+  /** Additional CSS classes */
+  readonly class = input<string>('');
+
+  /** Previous body overflow for restoration */
+  private previousBodyOverflow = '';
+
+  protected readonly computedClass = computed(() =>
+    cn(sheetVariants({ side: this.side() }), this.class())
+  );
+
+  constructor() {
+    // Handle body scroll lock based on open state (browser-only via effect + afterNextRender)
+    effect(() => {
+      const isOpen = this.context.open();
+      if (isOpen) {
+        this.lockBodyScroll();
+      } else {
+        this.unlockBodyScroll();
+      }
+    });
+  }
+
+  private lockBodyScroll(): void {
+    if (typeof document !== 'undefined') {
+      this.previousBodyOverflow = document.body.style.overflow;
+      document.body.style.overflow = 'hidden';
+    }
+  }
+
+  private unlockBodyScroll(): void {
+    if (typeof document !== 'undefined') {
+      document.body.style.overflow = this.previousBodyOverflow;
+    }
+  }
+
+  ngOnDestroy(): void {
+    // Restore body scroll
+    this.unlockBodyScroll();
+    // Restore focus to trigger element
+    this.restoreFocus();
+  }
+
+  onOverlayClick(event: Event): void {
+    event.stopPropagation();
+    this.close();
+  }
+
+  onEscapeKey(): void {
+    this.close();
+  }
+
+  onClose(): void {
+    this.close();
+  }
+
+  private close(): void {
+    this.restoreFocus();
+    this.context.setOpen(false);
+  }
+
+  private restoreFocus(): void {
+    const triggerEl = this.context.triggerElement();
+    if (triggerEl) {
+      setTimeout(() => {
+        triggerEl.focus();
+      }, 0);
+    }
+  }
+}

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

@@ -0,0 +1,15 @@
+import { InjectionToken, Signal, WritableSignal } from '@angular/core';
+
+export interface SheetContextValue {
+  open: Signal<boolean>;
+  setOpen: (open: boolean) => void;
+  side: 'top' | 'right' | 'bottom' | 'left';
+  /** Unique IDs for ARIA relationships */
+  titleId: string;
+  descriptionId: string;
+  contentId: string;
+  /** Trigger element reference for focus restoration */
+  triggerElement: WritableSignal<HTMLElement | null>;
+}
+
+export const SHEET_CONTEXT = new InjectionToken<SheetContextValue>('SHEET_CONTEXT');

package/src/app/lib/components/ui/sheet/sheet-description.component.ts

@@ -0,0 +1,34 @@
+import { cn } from '@/lib/utils';
+import {
+    ChangeDetectionStrategy,
+    Component,
+    computed,
+    inject,
+    input,
+} from '@angular/core';
+import { SHEET_CONTEXT } from './sheet-context';
+
+/**
+ * SheetDescription component - description text of the sheet.
+ * Matches shadcn/ui React SheetDescription exactly.
+ * Automatically links to sheet via aria-describedby.
+ */
+@Component({
+  selector: 'SheetDescription',
+  template: `<ng-content />`,
+  host: {
+    '[class]': 'computedClass()',
+    '[attr.id]': 'context.descriptionId',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class SheetDescription {
+  protected readonly context = inject(SHEET_CONTEXT);
+
+  /** Additional CSS classes */
+  readonly class = input<string>('');
+
+  protected readonly computedClass = computed(() =>
+    cn('text-sm text-muted-foreground', this.class())
+  );
+}

package/src/app/lib/components/ui/sheet/sheet-footer.component.ts

@@ -0,0 +1,28 @@
+import { cn } from '@/lib/utils';
+import {
+    ChangeDetectionStrategy,
+    Component,
+    computed,
+    input,
+} from '@angular/core';
+
+/**
+ * SheetFooter component - footer area of the sheet.
+ * Matches shadcn/ui React SheetFooter exactly.
+ */
+@Component({
+  selector: 'SheetFooter',
+  template: `<ng-content />`,
+  host: {
+    '[class]': 'computedClass()',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class SheetFooter {
+  /** Additional CSS classes */
+  readonly class = input<string>('');
+
+  protected readonly computedClass = computed(() =>
+    cn('flex flex-col-reverse sm:flex-row sm:justify-end sm:space-x-2', this.class())
+  );
+}