@radix-ng/primitives 0.11.0 → 0.12.0

package/progress/src/progress-root.directive.ts

@@ -0,0 +1,134 @@
+import { Directive, inject, InjectionToken, Input, numberAttribute, OnChanges, SimpleChanges } from '@angular/core';
+
+let idIterator = 0;
+
+const MIN_PERCENT = 0;
+const DEFAULT_MAX = 100;
+const PROGRESS_NAME = 'Radix Progress';
+
+const RdxProgressToken = new InjectionToken<RdxProgressRootDirective>('RdxProgressDirective');
+
+/**
+ * Injects the current instance of RdxProgressRootDirective.
+ * @returns The instance of RdxProgressRootDirective.
+ */
+export function injectProgress(): RdxProgressRootDirective {
+    return inject(RdxProgressToken);
+}
+
+export type ProgressState = 'indeterminate' | 'complete' | 'loading';
+
+export interface ProgressProps {
+    value?: number | null | undefined;
+    max?: number;
+    getValueLabel?: string;
+}
+
+/**
+ * Directive to manage progress bar state and attributes.
+ *
+ * This directive provides a way to create a progress bar with customizable value and max attributes.
+ * It handles aria attributes for accessibility and provides different states like 'indeterminate', 'complete', and 'loading'.
+ */
+@Directive({
+    selector: 'div[rdxProgressRoot]',
+    exportAs: 'ProgressRoot',
+    standalone: true,
+    providers: [{ provide: RdxProgressToken, useExisting: RdxProgressRootDirective }],
+    host: {
+        role: 'progressbar',
+        '[id]': 'id',
+        '[attr.aria-valuemax]': 'max',
+        '[attr.aria-valuemin]': '0',
+        '[attr.aria-valuenow]': 'value',
+        '[attr.aria-valuetext]': 'valueLabel(value, max)',
+        '[attr.data-state]': 'state',
+        '[attr.data-value]': 'value',
+        '[attr.data-max]': 'max',
+        // set tab index to -1 so screen readers will read the aria-label
+        // Note: there is a known issue with JAWS that does not read progressbar aria labels on FireFox
+        tabindex: '-1'
+    }
+})
+export class RdxProgressRootDirective implements ProgressProps, OnChanges {
+    /**
+     * The unique ID for the progress bar.
+     * @default 'rdx-progress-bar-{idIterator}'
+     */
+    @Input() id = `rdx-progress-bar-${idIterator++}`;
+
+    /**
+     * The current value of the progress bar.
+     * @default 0
+     */
+    @Input({ alias: 'rdxValue', transform: numberAttribute }) value = MIN_PERCENT;
+
+    /**
+     * The maximum value of the progress bar.
+     * @default 100
+     */
+    @Input({ alias: 'rdxMax', transform: numberAttribute }) max = DEFAULT_MAX;
+
+    /**
+     * Function to generate the value label.
+     */
+    @Input('rdxValueLabel') valueLabel: (value: number, max: number) => string = (value, max) =>
+        this.defaultGetValueLabel(value, max);
+
+    /**
+     * Lifecycle hook that is called when any data-bound property of a directive changes.
+     * @param changes - The changed properties.
+     * @ignore
+     */
+    ngOnChanges(changes: SimpleChanges) {
+        if (changes['max'] && !this.isValidMaxNumber(this.max)) {
+            console.error(this.getInvalidMaxError(`${this.max}`, PROGRESS_NAME));
+        }
+
+        if (changes['value'] && this.value !== null && !this.isValidValueNumber(this.value, this.max)) {
+            console.error(this.getInvalidValueError(`${this.value}`, PROGRESS_NAME));
+        }
+    }
+
+    /**
+     * Get the state of the progress bar.
+     * @returns 'indeterminate' | 'loading' | 'complete'
+     * @ignore
+     */
+    get state(): ProgressState {
+        return this.getProgressState(this.value, this.max);
+    }
+
+    private getProgressState(value: number | undefined | null, maxValue: number): ProgressState {
+        return value == null ? 'indeterminate' : value === maxValue ? 'complete' : 'loading';
+    }
+
+    private defaultGetValueLabel(value: number, max: number) {
+        return `${Math.round((value / max) * 100)}%`;
+    }
+
+    private isValidMaxNumber(max: unknown): max is number {
+        return this.isNumber(max) && !isNaN(max) && max > 0;
+    }
+
+    private isNumber(value: unknown): value is number {
+        return typeof value === 'number';
+    }
+
+    private isValidValueNumber(value: unknown, max: number): value is number {
+        return this.isNumber(value) && !isNaN(value) && value <= max && value >= 0;
+    }
+
+    private getInvalidMaxError(propValue: string, componentName: string): string {
+        return `Invalid prop \`max\` of value \`${propValue}\` supplied to \`${componentName}\`. Only numbers greater than 0 are valid max values. Defaulting to \`${DEFAULT_MAX}\`.`;
+    }
+
+    private getInvalidValueError(propValue: string, componentName: string): string {
+        return `Invalid prop \`value\` of value \`${propValue}\` supplied to \`${componentName}\`. The \`value\` prop must be:
+    - a positive number
+    - less than the value passed to \`max\` (or ${DEFAULT_MAX} if no \`max\` prop is set)
+    - \`null\` or \`undefined\` if the progress is indeterminate.
+
+    Defaulting to \`null\`.`;
+    }
+}

package/progress/stories/progress.docs.mdx

@@ -0,0 +1,65 @@
+import { ArgTypes, Canvas, Markdown, Meta } from '@storybook/blocks';
+import { RdxProgressRootDirective } from '../src/progress-root.directive';
+import * as ProgressDirectiveStories from './progress.stories';
+
+<Meta title="Primitives/Progress" />
+
+# Progress
+
+#### Displays an indicator showing the completion progress of a task, typically displayed as a progress bar.
+
+<Canvas sourceState="hidden" of={ProgressDirectiveStories.Default} />
+
+## Features
+
+- ✅ Provides context for assistive technology to read the progress of a task.
+
+## Usage
+
+Get started with importing the directive:
+
+```typescript
+import { RdxProgressRootDirective, RdxProgressIndicatorDirective } from '@radix-ng/primitives/progress';
+```
+
+## Example
+
+```html
+<div class="ProgressRoot" rdxProgressRoot [rdxValue]="progress">
+  <div class="ProgressIndicator" rdxProgressIndicator [style.transform]="'translateX(-' + (100 - progress) +'%)'"></div>
+</div>
+```
+
+## API Reference
+
+### RdxProgressRootDirective
+
+<ArgTypes of={RdxProgressRootDirective} />
+
+<Markdown>
+  {`
+  | Data Attribute | Value |
+  | ----------- | --------- |
+  | [data-state]    | "complete" or "indeterminate" or "loading"   |
+  | [data-value]    | The current value          |
+  | [data-max] |  The max value     |
+  `}
+</Markdown>
+
+### RdxProgressIndicatorDirective
+
+Used to show the progress visually. It also makes progress accessible to assistive technologies.
+
+<Markdown>
+  {`
+  | Data Attribute | Value |
+  | ----------- | --------- |
+  | [data-state]    | "complete" or "indeterminate" or "loading"   |
+  | [data-value]    | The current value          |
+  | [data-max] |  The max value     |
+  `}
+</Markdown>
+
+## Accessibility
+
+Adheres to the [`progressbar` role requirements](https://www.w3.org/WAI/ARIA/apg/patterns/meter).

package/progress/stories/progress.stories.ts

@@ -0,0 +1,66 @@
+import { componentWrapperDecorator, Meta, moduleMetadata, StoryObj } from '@storybook/angular';
+import { RdxProgressIndicatorDirective } from '../src/progress-indicator.directive';
+import { RdxProgressRootDirective } from '../src/progress-root.directive';
+
+export default {
+    title: 'Primitives/Progress',
+    decorators: [
+        moduleMetadata({
+            imports: [RdxProgressRootDirective, RdxProgressIndicatorDirective]
+        }),
+        componentWrapperDecorator(
+            (story) =>
+                `<div class="radix-themes light light-theme"
+                      data-radius="medium"
+                      data-scaling="100%">${story}</div>`
+        )
+    ],
+    argTypes: {
+        progress: {
+            options: ['10', '30', '70', '95'],
+            control: { type: 'select' }
+        }
+    }
+} as Meta;
+
+type Story = StoryObj;
+
+export const Default: Story = {
+    args: {
+        progress: 70
+    },
+    render: (args) => ({
+        props: args,
+        template: `
+<style>
+.ProgressRoot {
+  position: relative;
+  overflow: hidden;
+  background: var(--black-a9);
+  border-radius: 99999px;
+  width: 300px;
+  height: 25px;
+
+  /* Fix overflow clipping in Safari */
+  /* https://gist.github.com/domske/b66047671c780a238b51c51ffde8d3a0 */
+  transform: translateZ(0);
+}
+
+.ProgressIndicator {
+  background-color: white;
+  width: 100%;
+  height: 100%;
+  transition: transform 660ms cubic-bezier(0.65, 0, 0.35, 1);
+}
+</style>
+
+<div rdxProgressRoot [rdxValue]="progress" class="ProgressRoot">
+    <div rdxProgressIndicator
+        [style.transform]="'translateX(-' + (100 - progress) +'%)'"
+        class="ProgressIndicator"
+    ></div>
+</div>
+
+`
+    })
+};

package/project.json

@@ -0,0 +1,39 @@
+{
+    "name": "primitives",
+    "$schema": "../../node_modules/nx/schemas/project-schema.json",
+    "sourceRoot": "packages/primitives",
+    "prefix": "rdx",
+    "projectType": "library",
+    "tags": [],
+    "targets": {
+        "build": {
+            "executor": "@nx/angular:package",
+            "outputs": ["{workspaceRoot}/dist/{projectRoot}"],
+            "options": {
+                "project": "packages/primitives/ng-package.json"
+            },
+            "configurations": {
+                "production": {
+                    "tsConfig": "packages/primitives/tsconfig.lib.prod.json"
+                },
+                "development": {
+                    "tsConfig": "packages/primitives/tsconfig.lib.json"
+                }
+            },
+            "defaultConfiguration": "production"
+        },
+        "compodoc": {
+            "executor": "nx:run-script",
+            "options": {
+                "script": "compodoc"
+            }
+        },
+        "test": {
+            "executor": "@nx/jest:jest",
+            "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
+            "options": {
+                "jestConfig": "packages/primitives/jest.config.ts"
+            }
+        }
+    }
+}

package/radio/{index.d.ts → index.ts}

@@ -1,3 +1,4 @@
 export * from './src/radio-root.directive';
+
 export * from './src/radio-indicator.directive';
 export * from './src/radio-item.directive';

package/radio/ng-package.json

@@ -0,0 +1,5 @@
+{
+    "lib": {
+        "entryFile": "index.ts"
+    }
+}

package/radio/src/radio-indicator.directive.ts

@@ -0,0 +1,17 @@
+import { Directive, inject } from '@angular/core';
+import { RdxRadioItemDirective } from './radio-item.directive';
+import { RDX_RADIO_GROUP, RadioGroupDirective } from './radio-tokens';
+
+@Directive({
+    selector: '[rdxRadioIndicator]',
+    exportAs: 'rdxRadioIndicator',
+    standalone: true,
+    host: {
+        '[attr.data-state]': 'radioItem.checked ? "checked" : "unchecked"',
+        '[attr.data-disabled]': 'radioItem.disabled ? "" : null'
+    }
+})
+export class RdxRadioIndicatorDirective {
+    protected readonly radioGroup: RadioGroupDirective = inject(RDX_RADIO_GROUP);
+    protected readonly radioItem: RdxRadioItemDirective = inject(RdxRadioItemDirective);
+}

package/radio/src/radio-item.directive.ts

@@ -0,0 +1,68 @@
+import { FocusableOption } from '@angular/cdk/a11y';
+import { booleanAttribute, Directive, ElementRef, inject, InjectionToken, Input, OnInit } from '@angular/core';
+import { RDX_RADIO_GROUP } from './radio-tokens';
+
+export const RdxRadioItemToken = new InjectionToken<RdxRadioItemDirective>('RadioItemToken');
+
+export function injectRadioItem(): RdxRadioItemDirective {
+    return inject(RdxRadioItemToken);
+}
+
+// Increasing integer for generating unique ids for radio components.
+let nextUniqueId = 0;
+
+@Directive({
+    selector: '[rdxRadioItem]',
+    exportAs: 'rdxRadioItem',
+    standalone: true,
+    providers: [{ provide: RdxRadioItemToken, useExisting: RdxRadioItemDirective }],
+    host: {
+        type: 'button',
+        role: 'radio',
+        '[attr.id]': 'id',
+        '[attr.aria-checked]': 'checked',
+        '[attr.data-disabled]': 'disabled ? "" : null',
+        '[attr.data-state]': 'checked ? "checked" : "unchecked"',
+        '[attr.tabindex]': 'tabIndex',
+        '(click)': '_onClick()',
+        '(blur)': '_onBlur()'
+    }
+})
+export class RdxRadioItemDirective implements FocusableOption, OnInit {
+    private readonly radioGroup = inject(RDX_RADIO_GROUP);
+    readonly element = inject(ElementRef);
+
+    @Input() id = `rdx-radio-${++nextUniqueId}`;
+
+    @Input({ required: true }) value!: string;
+
+    @Input({ transform: booleanAttribute }) disabled = false;
+
+    get tabIndex(): number {
+        return this.disabled ? -1 : this.radioGroup.value === this.value ? 0 : -1;
+    }
+
+    get checked(): boolean {
+        return this.radioGroup.value === this.value;
+    }
+
+    ngOnInit() {
+        if (this.radioGroup.defaultValue === this.value) {
+            this.radioGroup.select(this.value);
+        }
+    }
+
+    focus(): void {
+        this.element.nativeElement.focus();
+    }
+
+    _onClick(): void {
+        if (!this.disabled) {
+            this.radioGroup.select(this.value);
+        }
+    }
+
+    _onBlur(): void {
+        this.radioGroup.onTouched?.();
+    }
+}

package/radio/src/radio-root.directive.ts

@@ -0,0 +1,207 @@
+import { FocusKeyManager } from '@angular/cdk/a11y';
+import { DOWN_ARROW, ENTER, LEFT_ARROW, RIGHT_ARROW, SPACE, TAB, UP_ARROW } from '@angular/cdk/keycodes';
+import {
+    AfterContentInit,
+    booleanAttribute,
+    ContentChildren,
+    Directive,
+    EventEmitter,
+    Input,
+    OnDestroy,
+    Output,
+    QueryList
+} from '@angular/core';
+import { ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';
+import { Subject, takeUntil } from 'rxjs';
+import { RdxRadioItemDirective } from './radio-item.directive';
+import { RadioGroupDirective, RadioGroupProps, RDX_RADIO_GROUP } from './radio-tokens';
+
+@Directive({
+    selector: '[rdxRadioRoot]',
+    exportAs: 'rdxRadioRoot',
+    standalone: true,
+    providers: [
+        { provide: RDX_RADIO_GROUP, useExisting: RdxRadioGroupDirective },
+        { provide: NG_VALUE_ACCESSOR, useExisting: RdxRadioGroupDirective, multi: true }
+    ],
+    host: {
+        role: 'radiogroup',
+        '[attr.aria-orientation]': '_orientation',
+        '[attr.data-disabled]': 'disabled ? "" : null',
+        '[attr.tabindex]': '-1',
+        '[attr.dir]': 'dir',
+        '(keydown)': '_onKeydown($event)',
+        '(focusin)': '_onFocusin($event)'
+    }
+})
+export class RdxRadioGroupDirective
+    implements RadioGroupProps, RadioGroupDirective, ControlValueAccessor, AfterContentInit, OnDestroy
+{
+    @ContentChildren(RdxRadioItemDirective, { descendants: true }) radioItems!: QueryList<RdxRadioItemDirective>;
+    private focusKeyManager!: FocusKeyManager<RdxRadioItemDirective>;
+    private destroy$ = new Subject<void>();
+
+    name?: string | undefined;
+    @Input() value?: string;
+
+    @Input({ transform: booleanAttribute }) disabled = false;
+
+    @Input() dir?: string;
+
+    @Input() defaultValue?: string;
+
+    /**
+     * The orientation of the radio group only vertical.
+     * Horizontal radio buttons can sometimes be challenging to scan and localize.
+     * The horizontal arrangement of radio buttons may also lead to difficulties in determining which
+     * label corresponds to which button: whether the label is above or below the button.
+     * @default 'vertical'
+     */
+    readonly _orientation = 'vertical';
+
+    /**
+     * Event handler called when the value changes.
+     */
+    @Output() readonly onValueChange = new EventEmitter<string>();
+
+    /**
+     * The callback function to call when the value of the radio group changes.
+     */
+    private onChange: (value: string) => void = () => {
+        /* Empty */
+    };
+
+    /**
+     * The callback function to call when the radio group is touched.
+     */
+    onTouched: () => void = () => {
+        /* Empty */
+    };
+
+    ngAfterContentInit() {
+        this.focusKeyManager = new FocusKeyManager(this.radioItems).withWrap().withVerticalOrientation();
+
+        this.radioItems.changes.pipe(takeUntil(this.destroy$)).subscribe(() => {
+            this.updateActiveItem();
+        });
+
+        this.updateActiveItem(false);
+    }
+
+    ngOnDestroy() {
+        this.destroy$.next();
+        this.destroy$.complete();
+    }
+
+    /**
+     * Select a radio item.
+     * @param value The value of the radio item to select.
+     */
+    select(value: string): void {
+        this.value = value;
+        this.onValueChange.emit(value);
+        this.onChange?.(value);
+        this.updateActiveItem();
+        this.onTouched();
+    }
+
+    /**
+     * Update the value of the radio group.
+     * @param value The new value of the radio group.
+     * @internal
+     */
+    writeValue(value: string): void {
+        this.value = value;
+        if (this.radioItems) {
+            this.updateActiveItem(false);
+        }
+    }
+
+    /**
+     * Register a callback function to call when the value of the radio group changes.
+     * @param fn The callback function to call when the value of the radio group changes.
+     * @internal
+     */
+    registerOnChange(fn: (value: string) => void): void {
+        this.onChange = fn;
+    }
+
+    registerOnTouched(fn: () => void): void {
+        this.onTouched = fn;
+    }
+
+    /**
+     * Set the disabled state of the radio group.
+     * @param isDisabled Whether the radio group is disabled.
+     * @internal
+     */
+    setDisabledState(isDisabled: boolean): void {
+        this.disabled = isDisabled;
+    }
+
+    /**
+     * When focus leaves the radio group.
+     */
+    _onFocusin(event: FocusEvent): void {
+        const target = event.target as HTMLElement;
+        const radioItem = this.radioItems.find((item) => item.element.nativeElement === target);
+        if (radioItem) {
+            this.focusKeyManager.setActiveItem(radioItem);
+        }
+    }
+
+    _onKeydown(event: KeyboardEvent): void {
+        if (this.disabled) return;
+
+        switch (event.keyCode) {
+            case ENTER:
+            case SPACE:
+                event.preventDefault();
+                this.selectFocusedItem();
+                break;
+            case DOWN_ARROW:
+            case RIGHT_ARROW:
+                event.preventDefault();
+                this.focusKeyManager.setNextItemActive();
+                this.selectFocusedItem();
+                break;
+            case UP_ARROW:
+            case LEFT_ARROW:
+                event.preventDefault();
+                this.focusKeyManager.setPreviousItemActive();
+                this.selectFocusedItem();
+                break;
+            case TAB:
+                this.tabNavigation(event);
+                break;
+            default:
+                this.focusKeyManager.onKeydown(event);
+        }
+    }
+
+    private selectFocusedItem(): void {
+        const focusedItem = this.focusKeyManager.activeItem;
+        if (focusedItem) {
+            this.select(focusedItem.value);
+        }
+    }
+
+    private updateActiveItem(setFocus = true): void {
+        const activeItem = this.radioItems.find((item) => item.value === this.value);
+        if (activeItem) {
+            this.focusKeyManager.setActiveItem(activeItem);
+        } else if (this.radioItems.length > 0 && setFocus) {
+            this.focusKeyManager.setFirstItemActive();
+        }
+    }
+
+    private tabNavigation(event: KeyboardEvent): void {
+        event.preventDefault();
+        const checkedItem = this.radioItems.find((item) => item.checked);
+        if (checkedItem) {
+            checkedItem.focus();
+        } else if (this.radioItems.first) {
+            this.radioItems.first.focus();
+        }
+    }
+}

package/radio/src/{radio-tokens.d.ts → radio-tokens.ts}

@@ -1,12 +1,16 @@
 import { InjectionToken } from '@angular/core';
+
 export interface RadioGroupProps {
     name?: string;
     disabled?: boolean;
     defaultValue?: string;
     value?: string;
 }
+
 export interface RadioGroupDirective extends RadioGroupProps {
     select(value: string): void;
+
     onTouched(): void;
 }
-export declare const RDX_RADIO_GROUP: InjectionToken<RadioGroupDirective>;
+
+export const RDX_RADIO_GROUP = new InjectionToken<RadioGroupDirective>('RdxRadioGroup');

package/radio/stories/radio-group.component.ts

@@ -0,0 +1,39 @@
+import { Component } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { RdxLabelDirective } from '@radix-ng/primitives/label';
+import { RdxRadioGroupDirective, RdxRadioIndicatorDirective, RdxRadioItemDirective } from '@radix-ng/primitives/radio';
+
+@Component({
+    selector: 'radio-groups-forms-example',
+    standalone: true,
+    template: `
+        <div class="RadioGroupRoot" [(ngModel)]="hotelRoom" rdxRadioRoot aria-label="View density">
+            @for (room of rooms; track room) {
+                <div class="RadioGroup">
+                    <button class="RadioGroupItem" [value]="room" [id]="room" rdxRadioItem>
+                        <div class="RadioGroupIndicator" rdxRadioIndicator></div>
+                        <input class="Input" rdxRadioIndicator type="radio" aria-hidden="true" tabindex="-1" />
+                    </button>
+                    <label class="Label" [htmlFor]="room" rdxLabel>
+                        {{ room }}
+                    </label>
+                </div>
+            }
+        </div>
+        <p>
+            <span>Your room is: {{ hotelRoom }}</span>
+        </p>
+    `,
+    styleUrl: 'radio-group.styles.scss',
+    imports: [
+        FormsModule,
+        RdxLabelDirective,
+        RdxRadioItemDirective,
+        RdxRadioIndicatorDirective,
+        RdxRadioGroupDirective
+    ]
+})
+export class RadioGroupComponent {
+    hotelRoom: string | undefined;
+    rooms = ['Default', 'Comfortable'];
+}