@radix-ng/primitives 0.11.1 → 0.12.0

package/progress/__test__/progress.spec.ts

@@ -0,0 +1,55 @@
+import { Component } from '@angular/core';
+import { ComponentFixture, TestBed } from '@angular/core/testing';
+import { RdxProgressIndicatorDirective } from '../src/progress-indicator.directive';
+import { RdxProgressRootDirective } from '../src/progress-root.directive';
+
+@Component({
+    template: `
+        <div [rdxValue]="value" [rdxMax]="max" [id]="id" rdxProgressRoot>
+            <div rdxProgressIndicator></div>
+        </div>
+    `
+})
+class TestHostComponent {
+    value: number | null | undefined = 50;
+    max = 100;
+    id = 'test-progress';
+}
+
+describe('RdxProgress', () => {
+    let component: TestHostComponent;
+    let fixture: ComponentFixture<TestHostComponent>;
+
+    beforeEach(async () => {
+        await TestBed.configureTestingModule({
+            imports: [RdxProgressRootDirective, RdxProgressIndicatorDirective],
+            declarations: [TestHostComponent]
+        }).compileComponents();
+
+        fixture = TestBed.createComponent(TestHostComponent);
+        component = fixture.componentInstance;
+        fixture.detectChanges();
+    });
+
+    it('should set the correct aria attributes and data attributes', () => {
+        const progressElement: HTMLElement = fixture.nativeElement.querySelector('div[role="progressbar"]');
+
+        expect(progressElement.getAttribute('aria-valuemax')).toBe('100');
+        expect(progressElement.getAttribute('aria-valuemin')).toBe('0');
+        expect(progressElement.getAttribute('aria-valuenow')).toBe('50');
+        expect(progressElement.getAttribute('aria-valuetext')).toBe('50%');
+        expect(progressElement.getAttribute('data-state')).toBe('loading');
+        expect(progressElement.getAttribute('data-value')).toBe('50');
+        expect(progressElement.getAttribute('data-max')).toBe('100');
+        expect(progressElement.id).toBe('test-progress');
+    });
+
+    it('should show complete state when value equals max', () => {
+        component.value = 100;
+        fixture.detectChanges();
+
+        const progressElement: HTMLElement = fixture.nativeElement.querySelector('div[role="progressbar"]');
+
+        expect(progressElement.getAttribute('data-state')).toBe('complete');
+    });
+});

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

@@ -1,3 +1,4 @@
 export * from './src/progress-indicator.directive';
 export * from './src/progress-root.directive';
+
 export type { ProgressProps } from './src/progress-root.directive';

package/progress/ng-package.json

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

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

@@ -0,0 +1,26 @@
+import { Directive } from '@angular/core';
+import { injectProgress } from './progress-root.directive';
+
+/**
+ * Directive to manage progress indicator state and attributes.
+ *
+ * This directive is used to display the progress indicator inside the progress bar.
+ * It inherits the state and value from the `RdxProgressRootDirective`.
+ */
+@Directive({
+    selector: 'div[rdxProgressIndicator]',
+    exportAs: 'ProgressIndicator',
+    standalone: true,
+    host: {
+        '[attr.data-state]': 'progress.state',
+        '[attr.data-value]': 'progress.value',
+        '[attr.data-max]': 'progress.max'
+    }
+})
+export class RdxProgressIndicatorDirective {
+    /**
+     *
+     * This allows the directive to access the progress bar state and values.
+     */
+    protected readonly progress = injectProgress();
+}

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?.();
+    }
+}