@ng-cn/core 1.0.10 → 1.0.12

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

@@ -0,0 +1,212 @@
+import { cn } from '@/lib/utils';
+import {
+    ChangeDetectionStrategy,
+    Component,
+    computed,
+    input,
+} from '@angular/core';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type ProgressState = 'indeterminate' | 'loading' | 'complete';
+
+export type ProgressProps = {
+  /** The current progress value (0 to max). Null for indeterminate. */
+  value?: number | null;
+  /** The maximum progress value */
+  max?: number;
+  /** Accessible label for the progress bar */
+  ariaLabel?: string;
+  /** Text description of current progress (e.g., "50% complete") */
+  ariaValueText?: string;
+  /** Additional CSS classes to apply to the root */
+  class?: string;
+  /** Additional CSS classes to apply to the indicator */
+  indicatorClass?: string;
+  /**
+   * Function to get value label for accessibility.
+   * Receives current value and returns descriptive text.
+   */
+  getValueLabel?: (value: number, max: number) => string;
+};
+
+// ============================================================================
+// Progress Component
+// ============================================================================
+
+/**
+ * Progress component displays progress feedback for tasks and operations.
+ * Based on Radix UI Progress primitive with shadcn/ui styling.
+ *
+ * ## Features
+ * - Determinate mode with value from 0 to max
+ * - Indeterminate mode when value is null (shows loading animation)
+ * - Complete state when value reaches max
+ * - Full ARIA progressbar implementation
+ * - Customizable indicator styling
+ *
+ * ## Accessibility
+ * - Uses native `progressbar` role
+ * - `aria-valuenow`, `aria-valuemin`, `aria-valuemax` for current state
+ * - `aria-valuetext` provides human-readable progress description
+ * - `aria-label` for accessible name
+ * - `aria-live="polite"` for screen reader announcements
+ *
+ * ## Data Attributes
+ * - `data-state`: "indeterminate" | "loading" | "complete"
+ * - `data-value`: Current numeric value
+ * - `data-max`: Maximum value
+ *
+ * @example
+ * <!-- Basic progress -->
+ * <Progress [value]="50" />
+ *
+ * @example
+ * <!-- With custom max -->
+ * <Progress [value]="30" [max]="50" />
+ *
+ * @example
+ * <!-- Indeterminate (loading) -->
+ * <Progress />
+ * <!-- or explicitly -->
+ * <Progress [value]="null" />
+ *
+ * @example
+ * <!-- Complete state -->
+ * <Progress [value]="100" />
+ *
+ * @example
+ * <!-- With accessible label -->
+ * <Progress [value]="66" ariaLabel="Downloading file" />
+ *
+ * @example
+ * <!-- With custom value text -->
+ * <Progress
+ *   [value]="3"
+ *   [max]="10"
+ *   ariaValueText="Step 3 of 10"
+ * />
+ *
+ * @example
+ * <!-- With custom value label function -->
+ * <Progress
+ *   [value]="bytesLoaded"
+ *   [max]="totalBytes"
+ *   [getValueLabel]="formatBytes"
+ * />
+ *
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/progress Radix Progress}
+ * @see {@link https://ui.shadcn.com/docs/components/progress shadcn/ui Progress}
+ */
+@Component({
+  selector: 'Progress',
+  template: `
+    <div
+      data-slot="progress-indicator"
+      [class]="computedIndicatorClass()"
+      [style.transform]="indicatorTransform()"
+    ></div>
+  `,
+  host: {
+    '[class]': 'computedClass()',
+    role: 'progressbar',
+    '[attr.aria-label]': 'ariaLabel()',
+    '[attr.aria-valuemin]': '0',
+    '[attr.aria-valuemax]': 'max()',
+    '[attr.aria-valuenow]': 'value()',
+    '[attr.aria-valuetext]': 'computedValueText()',
+    '[attr.aria-live]': '"polite"',
+    '[attr.data-state]': 'state()',
+    '[attr.data-value]': 'value()',
+    '[attr.data-max]': 'max()',
+    'data-slot': 'progress',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class Progress {
+  /** The current progress value (0 to max). Null for indeterminate. */
+  readonly value = input<number | null>(null);
+
+  /** The maximum progress value */
+  readonly max = input<number>(100);
+
+  /** Accessible label for the progress bar */
+  readonly ariaLabel = input<string>('Progress');
+
+  /** Text description of current progress (e.g., "50% complete") */
+  readonly ariaValueText = input<string | undefined>(undefined);
+
+  /**
+   * Function to get value label for accessibility.
+   * Receives current value and returns descriptive text.
+   */
+  readonly getValueLabel = input<
+    ((value: number, max: number) => string) | undefined
+  >(undefined);
+
+  /** Additional CSS classes to apply to the root */
+  readonly class = input<string>('');
+
+  /** Additional CSS classes to apply to the indicator */
+  readonly indicatorClass = input<string>('');
+
+  /** Calculate percentage (0-100) */
+  protected readonly percentage = computed(() => {
+    const val = this.value();
+    const maxVal = this.max();
+    if (val === null || maxVal === 0) return 0;
+    return Math.min(100, Math.max(0, (val / maxVal) * 100));
+  });
+
+  /** Calculate state for data attribute */
+  protected readonly state = computed((): ProgressState => {
+    const val = this.value();
+    if (val === null) return 'indeterminate';
+    return val >= this.max() ? 'complete' : 'loading';
+  });
+
+  /** Compute aria-valuetext */
+  protected readonly computedValueText = computed(() => {
+    const customText = this.ariaValueText();
+    if (customText) return customText;
+
+    const val = this.value();
+    if (val === null) return 'Loading';
+
+    const getLabel = this.getValueLabel();
+    if (getLabel) {
+      return getLabel(val, this.max());
+    }
+
+    return `${this.percentage().toFixed(0)}% complete`;
+  });
+
+  /** Transform for the indicator */
+  protected readonly indicatorTransform = computed(() => {
+    return `translateX(-${100 - this.percentage()}%)`;
+  });
+
+  /** Computed class combining base styles and custom classes */
+  protected readonly computedClass = computed(() =>
+    cn(
+      // Base styles
+      'bg-primary/20 relative h-2 w-full overflow-hidden rounded-full',
+      // Custom classes
+      this.class()
+    )
+  );
+
+  /** Computed indicator class */
+  protected readonly computedIndicatorClass = computed(() =>
+    cn(
+      // Base styles
+      'bg-primary h-full w-full flex-1 transition-all duration-300 ease-in-out',
+      // Indeterminate animation
+      this.state() === 'indeterminate' && 'animate-pulse',
+      // Custom classes
+      this.indicatorClass()
+    )
+  );
+}

package/src/app/lib/components/ui/radio-group/index.ts

@@ -0,0 +1,10 @@
+export {
+  RADIO_GROUP_CONTEXT,
+  type RadioGroupContext,
+  type RadioGroupOrientation,
+} from './radio-group-context';
+export {
+  RadioGroupItem,
+  type RadioGroupItemProps,
+} from './radio-group-item.component';
+export { RadioGroup, type RadioGroupProps } from './radio-group.component';

package/src/app/lib/components/ui/radio-group/radio-group-context.ts

@@ -0,0 +1,38 @@
+import { InjectionToken, WritableSignal } from '@angular/core';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type RadioGroupOrientation = 'horizontal' | 'vertical';
+
+export interface RadioGroupContext {
+  /** Current selected value */
+  value: WritableSignal<string>;
+  /** Whether the group is disabled */
+  disabled: WritableSignal<boolean>;
+  /** The name for radio inputs */
+  name: WritableSignal<string>;
+  /** Orientation for keyboard navigation */
+  orientation: WritableSignal<RadioGroupOrientation>;
+  /** Whether to loop focus at boundaries */
+  loop: WritableSignal<boolean>;
+  /** Whether the group is required */
+  required: WritableSignal<boolean>;
+  /** Registry of all radio item values */
+  itemValues: WritableSignal<string[]>;
+  /** Set the selected value */
+  setValue: (value: string) => void;
+  /** Move focus to the next radio item */
+  focusNext: (currentValue: string) => void;
+  /** Move focus to the previous radio item */
+  focusPrevious: (currentValue: string) => void;
+  /** Move focus to the first radio item */
+  focusFirst: () => void;
+  /** Move focus to the last radio item */
+  focusLast: () => void;
+}
+
+export const RADIO_GROUP_CONTEXT = new InjectionToken<RadioGroupContext>(
+  'RadioGroupContext'
+);

package/src/app/lib/components/ui/radio-group/radio-group-item.component.ts

@@ -0,0 +1,298 @@
+import { cn } from '@/lib/utils';
+import {
+    ChangeDetectionStrategy,
+    Component,
+    computed,
+    ElementRef,
+    inject,
+    input,
+    OnDestroy,
+    OnInit,
+    viewChild,
+} from '@angular/core';
+import { RADIO_GROUP_CONTEXT } from './radio-group-context';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type RadioGroupItemProps = {
+  /** The unique value for this radio item */
+  value: string;
+  /** The id for the radio input */
+  id?: string;
+  /** Whether this radio item is disabled */
+  disabled?: boolean;
+  /** Whether the item is required (inherited from group if not set) */
+  required?: boolean;
+  /** Additional CSS classes */
+  class?: string;
+};
+
+// ============================================================================
+// RadioGroupItem Component
+// ============================================================================
+
+/**
+ * RadioGroupItem component - individual radio option within a group.
+ * Based on Radix UI RadioGroup.Item with shadcn/ui styling.
+ * Implements roving tabindex (only checked or first item is tabbable).
+ *
+ * ## Features
+ * - Visual indicator shows checked state
+ * - Inherits disabled state from parent group
+ * - Roving tabindex for efficient keyboard navigation
+ * - Full keyboard support
+ *
+ * ## Accessibility
+ * - Uses native radio input for built-in accessibility
+ * - `aria-checked` indicates checked state
+ * - Part of roving tabindex pattern
+ * - Supports keyboard navigation from parent group
+ *
+ * ## Data Attributes
+ * - `data-state`: "checked" | "unchecked"
+ * - `data-disabled`: Present when disabled
+ * - `data-value`: The item's value
+ *
+ * @example
+ * <RadioGroupItem value="option1" id="option1" />
+ *
+ * @example
+ * <!-- With label -->
+ * <div class="flex items-center gap-2">
+ *   <RadioGroupItem value="apple" id="apple" />
+ *   <Label for="apple">Apple</Label>
+ * </div>
+ *
+ * @example
+ * <!-- Individually disabled -->
+ * <RadioGroupItem value="unavailable" [disabled]="true" />
+ *
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/radio-group Radix RadioGroup}
+ * @see {@link https://ui.shadcn.com/docs/components/radio-group shadcn/ui RadioGroup}
+ */
+@Component({
+  selector: 'RadioGroupItem',
+  template: `
+    <button
+      #buttonElement
+      type="button"
+      role="radio"
+      [attr.id]="id()"
+      [attr.aria-checked]="isChecked()"
+      [attr.data-state]="state()"
+      [attr.data-disabled]="isDisabled() ? '' : null"
+      [attr.data-value]="value()"
+      [disabled]="isDisabled()"
+      [attr.tabindex]="tabIndex()"
+      [class]="radioClass()"
+      (click)="select()"
+      (keydown)="onKeyDown($event)"
+    >
+      @if (isChecked()) {
+        <span
+          data-slot="radio-group-indicator"
+          class="flex items-center justify-center"
+        >
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="24"
+            height="24"
+            viewBox="0 0 24 24"
+            fill="currentColor"
+            class="size-2.5"
+          >
+            <circle cx="12" cy="12" r="10"></circle>
+          </svg>
+        </span>
+      }
+    </button>
+    <!-- Hidden input for form submission -->
+    @if (context?.name()) {
+      <input
+        type="radio"
+        [attr.name]="context?.name()"
+        [attr.value]="value()"
+        [checked]="isChecked()"
+        [disabled]="isDisabled()"
+        [required]="isRequired()"
+        aria-hidden="true"
+        tabindex="-1"
+        class="sr-only"
+      />
+    }
+  `,
+  host: {
+    '[class]': 'computedClass()',
+    'data-slot': 'radio-group-item',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class RadioGroupItem implements OnInit, OnDestroy {
+  protected readonly context = inject(RADIO_GROUP_CONTEXT, { optional: true });
+  private readonly buttonElement =
+    viewChild<ElementRef<HTMLButtonElement>>('buttonElement');
+
+  /** The id for the radio button - used for label association */
+  readonly id = input<string>();
+
+  /** The value of this radio option */
+  readonly value = input.required<string>();
+
+  /** Whether this radio is disabled */
+  readonly disabled = input<boolean>(false);
+
+  /** Whether this radio is required (inherited from group if not set) */
+  readonly required = input<boolean | undefined>(undefined);
+
+  /** Additional CSS classes to apply */
+  readonly class = input<string>('');
+
+  /** Whether this item is checked */
+  protected readonly isChecked = computed(() => {
+    return this.context?.value() === this.value();
+  });
+
+  /** State for data attribute */
+  protected readonly state = computed(() =>
+    this.isChecked() ? 'checked' : 'unchecked'
+  );
+
+  /** Whether this item is disabled */
+  protected readonly isDisabled = computed(() => {
+    return this.disabled() || this.context?.disabled() || false;
+  });
+
+  /** Whether this item is required */
+  protected readonly isRequired = computed(() => {
+    const explicitRequired = this.required();
+    if (explicitRequired !== undefined) return explicitRequired;
+    return this.context?.required() || false;
+  });
+
+  /**
+   * Roving tabindex: only the checked item (or first item if none checked) is tabbable.
+   */
+  protected readonly tabIndex = computed(() => {
+    if (this.isDisabled()) return -1;
+    if (!this.context) return 0;
+
+    const currentValue = this.context.value();
+    const itemValues = this.context.itemValues();
+
+    // If this item is checked, it's tabbable
+    if (currentValue === this.value()) return 0;
+
+    // If no item is checked and this is the first item, it's tabbable
+    if (
+      !currentValue &&
+      itemValues.length > 0 &&
+      itemValues[0] === this.value()
+    ) {
+      return 0;
+    }
+
+    return -1;
+  });
+
+  ngOnInit(): void {
+    // Register this item with the group
+    this.context?.itemValues.update((values) => {
+      if (!values.includes(this.value())) {
+        return [...values, this.value()];
+      }
+      return values;
+    });
+  }
+
+  ngOnDestroy(): void {
+    // Unregister this item from the group
+    this.context?.itemValues.update((values) =>
+      values.filter((v) => v !== this.value())
+    );
+  }
+
+  /** Select this radio option */
+  select(): void {
+    if (!this.isDisabled()) {
+      this.context?.setValue(this.value());
+    }
+  }
+
+  /** Focus the button element */
+  focus(): void {
+    this.buttonElement()?.nativeElement.focus();
+  }
+
+  /** Handle keyboard navigation */
+  onKeyDown(event: KeyboardEvent): void {
+    if (this.isDisabled() || !this.context) return;
+
+    const orientation = this.context.orientation();
+    const isVertical = orientation === 'vertical';
+    const isHorizontal = orientation === 'horizontal';
+
+    switch (event.key) {
+      case 'ArrowDown':
+        if (isVertical) {
+          event.preventDefault();
+          this.context.focusNext(this.value());
+        }
+        break;
+      case 'ArrowUp':
+        if (isVertical) {
+          event.preventDefault();
+          this.context.focusPrevious(this.value());
+        }
+        break;
+      case 'ArrowRight':
+        if (isHorizontal) {
+          event.preventDefault();
+          this.context.focusNext(this.value());
+        }
+        break;
+      case 'ArrowLeft':
+        if (isHorizontal) {
+          event.preventDefault();
+          this.context.focusPrevious(this.value());
+        }
+        break;
+      case 'Home':
+        event.preventDefault();
+        this.context.focusFirst();
+        break;
+      case 'End':
+        event.preventDefault();
+        this.context.focusLast();
+        break;
+      case ' ':
+        // Space should select if not already selected
+        event.preventDefault();
+        this.select();
+        break;
+    }
+  }
+
+  /** Computed class for wrapper */
+  protected readonly computedClass = computed(() =>
+    cn('relative inline-flex', this.class())
+  );
+
+  /** Computed radio visual class */
+  protected readonly radioClass = computed(() =>
+    cn(
+      // Base styles
+      'aspect-square size-4 shrink-0 rounded-full border shadow-xs',
+      'inline-flex items-center justify-center cursor-pointer',
+      'transition-[color,box-shadow] outline-none',
+      // Focus styles
+      'focus-visible:ring-[3px] focus-visible:ring-ring/50 focus-visible:border-ring',
+      // State styles
+      'border-input text-primary',
+      'data-[state=checked]:border-primary',
+      // Disabled styles
+      'disabled:cursor-not-allowed disabled:opacity-50'
+    )
+  );
+}