@bspk/ui-ngx 0.0.1

package/src/lib/textarea/textarea.ts

@@ -0,0 +1,126 @@
+import { Component, ViewEncapsulation, computed, input, model } from '@angular/core';
+import { CommonProps, FieldControlProps, AsInputSignal } from '../../types/common';
+
+export type TextareaProps = CommonProps<'size'> &
+    FieldControlProps & {
+        /** The placeholder of the field. */
+        placeholder?: string;
+        /**
+         * The maximum number of characters that the field will accept.
+         *
+         * @minimum 1
+         */
+        maxLength?: number;
+        /**
+         * The minimum number of rows that the textarea will show.
+         *
+         * @default 3
+         * @minimum 3
+         * @maximum 10
+         */
+        minRows?: number;
+        /**
+         * The maximum number of rows that the textarea will show.
+         *
+         * When set the textarea will automatically adjust its height to fit the content up to this limit.
+         *
+         * @default 10
+         * @minimum 3
+         * @maximum 10
+         */
+        maxRows?: number;
+    };
+
+/**
+ * A component that allows users to input large amounts of text that could span multiple lines.
+ *
+ * This component gives you a textarea HTML element that automatically adjusts its height to match the length of the
+ * content within maximum and minimum rows. A character counter when a maxLength is set to show the number of characters
+ * remaining below the limit.
+ *
+ * For a more complete example with field usage, see the TextareaField component.
+ *
+ * @example
+ *     <ui-textarea
+ *     [value]="textareaValue()"
+ *     (valueChange)="updateTextarea($event)"
+ *     id="default-textarea"
+ *     name="default-textarea"
+ *     ariaLabel="Textarea Label "/>
+ *
+ * @element
+ *
+ * @name Textarea
+ * @phase UXReview
+ */
+@Component({
+    selector: 'ui-textarea',
+    standalone: true,
+    template: `
+        <textarea
+            #el
+            data-main-input
+            [attr.aria-labelledby]="ariaLabelledBy() || null"
+            [attr.aria-describedby]="ariaDescribedBy() || null"
+            [attr.ariaErrorMessage]="ariaErrorMessage() || null"
+            [attr.aria-label]="ariaLabel() || null"
+            [attr.aria-invalid]="invalid() || null"
+            [disabled]="disabled()"
+            [id]="id()"
+            [attr.name]="name() || null"
+            [attr.placeholder]="placeholder() || null"
+            [attr.maxLength]="maxLength() ?? null"
+            [readOnly]="readOnly() || null"
+            [required]="required() || null"
+            [value]="value() ?? ''"
+            (blur)="handleBlur($event)"
+            (input)="handleInput($event)"
+            wrap="hard"></textarea>
+        <div aria-hidden="true" data-replicated-value>
+            {{ value() }}
+        </div>
+    `,
+    styleUrl: './textarea.scss',
+    host: {
+        'data-bspk': 'textarea',
+        '[attr.data-disabled]': 'disabled() || null',
+        '[attr.data-invalid]': 'invalid() || null',
+        '[attr.data-readonly]': 'readOnly() || null',
+        '[attr.data-size]': 'size() || "medium"',
+        '[style.--min-rows]': 'minRowsValid()',
+        '[style.--max-rows]': 'maxRowsValid()',
+    },
+    encapsulation: ViewEncapsulation.None,
+})
+export class UITextarea implements AsInputSignal<TextareaProps> {
+    readonly name = input.required<TextareaProps['name']>();
+    readonly value = model<string | undefined>('');
+
+    readonly ariaLabel = input<TextareaProps['ariaLabel']>(undefined);
+    readonly disabled = input<TextareaProps['disabled']>(false);
+    readonly id = input<TextareaProps['id']>(undefined);
+    readonly invalid = input<TextareaProps['invalid']>(false);
+    readonly maxLength = input<TextareaProps['maxLength']>(undefined);
+    readonly maxRows = input<TextareaProps['maxRows']>(10);
+    readonly minRows = input<TextareaProps['minRows']>(3);
+    readonly placeholder = input<TextareaProps['placeholder']>(undefined);
+    readonly readOnly = input<TextareaProps['readOnly']>(false);
+    readonly required = input<TextareaProps['required']>(false);
+    readonly size = input<TextareaProps['size']>('medium');
+
+    readonly ariaLabelledBy = input<TextareaProps['ariaLabelledBy']>(undefined);
+    readonly ariaDescribedBy = input<TextareaProps['ariaDescribedBy']>(undefined);
+    readonly ariaErrorMessage = input<TextareaProps['ariaErrorMessage']>(undefined);
+
+    readonly minRowsValid = computed(() => Math.min(10, Math.max(3, this.minRows() || 3)));
+    readonly maxRowsValid = computed(() => Math.min(10, Math.max(3, this.maxRows() || 10)));
+
+    handleBlur(event: FocusEvent) {
+        const target = event.target as HTMLTextAreaElement;
+        target.scrollTop = 0;
+    }
+
+    handleInput(event: Event) {
+        this.value.set((event.target as HTMLTextAreaElement).value);
+    }
+}

package/src/lib/textarea-field/example.ts

@@ -0,0 +1,55 @@
+import { CommonModule } from '@angular/common';
+import { Component } from '@angular/core';
+import { UITextareaField } from './textarea-field';
+
+@Component({
+    selector: 'ui-textarea-example',
+    standalone: true,
+    imports: [CommonModule, UITextareaField],
+    template: `
+        <h2>Textarea</h2>
+
+        <h3>Default</h3>
+        <ui-textarea-field name="default" label="Textarea" />
+
+        <h3>Disabled</h3>
+        <ui-textarea-field name="disabled" label="Textarea" [disabled]="true" />
+
+        <h3>Invalid</h3>
+        <ui-textarea-field name="invalid" label="Textarea" [invalid]="true" />
+
+        <h3>Required</h3>
+        <ui-textarea-field name="required" label="Textarea" [required]="true" />
+
+        <h3>Read Only</h3>
+        <ui-textarea-field name="readonly" label="Textarea" [readOnly]="true" />
+
+        <h3>Placeholder</h3>
+        <ui-textarea-field name="placeholder" label="Textarea" placeholder="Type here..." />
+
+        <h3>size = small</h3>
+        <ui-textarea-field name="small" label="Textarea" size="small" />
+
+        <h3>size = medium</h3>
+        <ui-textarea-field name="medium" label="Textarea" size="medium" />
+
+        <h3>size = large</h3>
+        <ui-textarea-field name="large" label="Textarea" size="large" />
+
+        <h3>maxLength</h3>
+        <ui-textarea-field name="maxlength" label="Textarea" [maxLength]="120" placeholder="Max 120 chars" />
+
+        <h3>minRows (2) / maxRows (4)</h3>
+        <ui-textarea-field
+            name="minmaxrows"
+            label="Textarea"
+            [minRows]="2"
+            [maxRows]="4"
+            value="Line 1
+Line 2
+Line 3
+Line 4"
+            helperText="The minimum value for minRows is 3 so setting it to 2 will default to 3." />
+    `,
+})
+export class UITextareaFieldExample {}

package/src/lib/textarea-field/index.ts

@@ -0,0 +1 @@
+export * from './textarea-field';

package/src/lib/textarea-field/textarea-field.spec.ts

@@ -0,0 +1,22 @@
+import { ComponentFixture, TestBed } from '@angular/core/testing';
+
+import { hasNoBasicA11yIssues } from '../../testutils/hasNoBasicA11yIssues';
+import { UITextareaField } from './textarea-field';
+
+describe('UITextareaField', () => {
+    let fixture: ComponentFixture<UITextareaField>;
+
+    beforeEach(async () => {
+        await TestBed.configureTestingModule({
+            imports: [UITextareaField],
+        }).compileComponents();
+
+        fixture = TestBed.createComponent(UITextareaField);
+        fixture.componentRef.setInput('label', 'Textarea test');
+        fixture.componentRef.setInput('name', 'textarea-name');
+
+        fixture.detectChanges();
+    });
+
+    it('should have no basic a11y issues', async () => await hasNoBasicA11yIssues(fixture));
+});

package/src/lib/textarea-field/textarea-field.ts

@@ -0,0 +1,88 @@
+import { Component, computed, input, output, ViewEncapsulation } from '@angular/core';
+import { AsInputSignal } from '../../types/common';
+import { uniqueId } from '../../utils/random';
+import { describedById, errorMessageId, FieldProps, labelledById, UIField } from '../field';
+import { UITextarea } from '../textarea';
+
+/**
+ * A component that allows users to input large amounts of text that could span multiple lines.
+ *
+ * This component gives you a textarea HTML element that automatically adjusts its height to match the length of the
+ * content within maximum and minimum rows. A character counter when a maxLength is set to show the number of characters
+ * remaining below the limit.
+ *
+ * For a more complete example with field usage, see the TextareaField component.
+ *
+ * @example
+ *     <ui-textarea-field
+ *     [value]="textareaValue()"
+ *     (valueChange)="updateTextarea($event)"
+ *     id="default-textarea"
+ *     name="default-textarea"
+ *     label="Textarea Label "/>
+ *
+ * @element
+ *
+ * @name TextareaField
+ * @phase UXReview
+ */
+@Component({
+    selector: 'ui-textarea-field',
+    standalone: true,
+    imports: [UIField, UITextarea],
+    template: `
+        <ui-field
+            [errorMessage]="errorMessage()"
+            [label]="label()"
+            [helperText]="helperText()"
+            [labelTrailing]="labelTrailing()"
+            [controlId]="controlId()"
+            [style]="style()"
+            [required]="required()">
+            <ui-textarea
+                [ariaLabelledBy]="labelledById()"
+                [ariaDescribedBy]="describedById()"
+                [ariaErrorMessage]="errorMessageId()"
+                (valueChange)="valueChange.emit($event)"
+                [ariaLabel]="ariaLabel()"
+                [disabled]="disabled()"
+                [id]="controlId()"
+                [invalid]="invalid()"
+                [name]="name()"
+                [placeholder]="placeholder()"
+                [readOnly]="readOnly()"
+                [value]="value()"
+                [required]="required()"
+                [size]="size()"
+                [maxLength]="maxLength()"
+                [minRows]="minRows()"
+                [maxRows]="maxRows()" />
+        </ui-field>
+    `,
+    host: {
+        'data-bspk': 'textarea-field',
+        '[id]': 'controlId()+"-field"',
+    },
+    styleUrl: '../field/field.scss',
+    encapsulation: ViewEncapsulation.None,
+})
+export class UITextareaField extends UITextarea implements AsInputSignal<Omit<FieldProps, 'controlId' | 'label'>> {
+    readonly valueChange = output<string | undefined>();
+
+    readonly errorMessage = input<string | undefined>(undefined);
+    readonly label = input.required<string>();
+    readonly helperText = input<string | undefined>(undefined);
+    readonly labelTrailing = input<string | undefined>(undefined);
+    readonly style = input<string | undefined>(undefined);
+
+    readonly labelledById = computed(() => labelledById(this.controlId()));
+
+    readonly describedById = computed(
+        () => this.ariaDescribedBy() || (this.helperText() && describedById(this.controlId())) || undefined,
+    );
+    readonly errorMessageId = computed(
+        () => this.ariaErrorMessage() || (this.errorMessage() && errorMessageId(this.controlId())) || undefined,
+    );
+
+    readonly controlId = computed(() => this.id() || uniqueId('input-field-'));
+}

package/src/lib/tooltip/example.ts

@@ -0,0 +1,145 @@
+import { CommonModule } from '@angular/common';
+import {
+    Component,
+    model,
+    AfterViewInit,
+    OnDestroy,
+    ElementRef,
+    viewChild,
+    inject,
+    EnvironmentInjector,
+    Renderer2,
+} from '@angular/core';
+import { UIButton } from '../button/button';
+import { TooltipUtility } from './tooltip';
+import { TooltipPlacement, UITooltipDirective } from './tooltip.directive';
+
+@Component({
+    selector: 'ui-tooltip-example',
+    standalone: true,
+    imports: [CommonModule, UITooltipDirective, UIButton],
+    template: `
+        <h2>Tooltip</h2>
+
+        <div ngx-example>
+            <ui-button label="Hover me" tooltip="I explain what this button does" tooltipId="button"></ui-button>
+        </div>
+        <p>This is a button with a tooltip but not using the ui-tooltip directive directly.</p>
+
+        @for (placement of placements; track $index) {
+            <h3>{{ placement | titlecase }}</h3>
+            <span [ui-tooltip]="{ label: placement + ' side tooltip', placement: placement }"
+                >Hover me ({{ placement }})</span
+            >
+        }
+
+        <h3>Truncated Only</h3>
+        <p>
+            This tooltip only appears when the content is truncated. Resize the window to see the effect. When the text
+            is fully visible, no tooltip will appear.
+        </p>
+        <div style="width: 200px; border: 1px solid #ccc; padding: 8px; margin-bottom: 16px;">
+            <span style="width: 100%" [ui-tooltip]="{ truncated: true }"
+                >This is some really long text that might be truncated when displayed in a small container.</span
+            >
+            <br />
+            <br />
+            <span style="width: 100%" [ui-tooltip]="{ truncated: true }">This is some text.</span>
+        </div>
+
+        <h3>Dynamic Placement</h3>
+        <div style="text-align: right;">
+            <span
+                [ui-tooltip]="{
+                    label: 'I change placement based on available space',
+                    placement: 'right',
+                }">
+                Hover me (placement: 'right)
+            </span>
+        </div>
+        <p>Placement is 'right' but the tooltip will adjusts as there is not enough space to the right.</p>
+
+        <h3>No tail</h3>
+        <span
+            [ui-tooltip]="{
+                label: 'No tail',
+                showTail: false,
+            }"
+            >Hover me (no tail)</span
+        >
+
+        <h3>Disabled</h3>
+        <span
+            [ui-tooltip]="{
+                label: 'Disabled tooltip',
+                disabled: true,
+            }"
+            >Hover me (disabled)</span
+        >
+
+        <h3>Updated Live</h3>
+        <p>This demonstrates that the tooltip responds to dynamic updates.</p>
+        <span
+            [ui-tooltip]="{
+                label: 'Updated tooltip (' + counter() + ')',
+            }"
+            >Hover me ({{ counter() }})</span
+        >
+
+        <h3>Reference and Tooltip removed from DOM</h3>
+        <p>
+            This demonstrates that when the reference element is removed from the DOM, the tooltip is also removed from
+            the DOM.
+        </p>
+        @if (counter() % 10 < 5) {
+            <span [ui-tooltip]="'Hello There'"
+                >I will disappear in {{ 5 - (counter() % 10) }} second{{ 5 - (counter() % 10) === 1 ? '' : 's' }}</span
+            >
+        } @else {
+            <span>Will return in {{ 10 - (counter() % 10) }} second{{ 10 - (counter() % 10) === 1 ? '' : 's' }}</span>
+        }
+
+        <h3>Tooltip Utility Component</h3>
+        <span #tooltipUtil>Hello there</span>
+    `,
+    styles: `
+        span[aria-labelledby] {
+            border: 1px dashed #666;
+        }
+    `,
+    host: {
+        // ensure the example tooltips are not cut off
+        style: `overflow: hidden;`,
+    },
+})
+export class UITooltipExample implements AfterViewInit, OnDestroy {
+    placements: TooltipPlacement[] = ['top', 'bottom', 'left', 'right'];
+
+    readonly counter = model(0);
+
+    interval: ReturnType<typeof setInterval> | undefined;
+
+    readonly tooltipUtil = viewChild('tooltipUtil', { read: ElementRef });
+
+    tooltip?: TooltipUtility;
+
+    renderer = inject(Renderer2);
+    env = inject(EnvironmentInjector);
+
+    ngAfterViewInit() {
+        this.interval = setInterval(() => {
+            this.counter.set(this.counter() + 1);
+        }, 1000);
+
+        this.tooltip = new TooltipUtility(this.renderer, this.env, {
+            label: 'Tooltip Utility says hello!',
+            placement: 'top',
+            reference: this.tooltipUtil()?.nativeElement,
+        });
+    }
+
+    ngOnDestroy() {
+        // make sure to clear interval on destroy
+        if (this.interval) clearInterval(this.interval);
+    }
+}

package/src/lib/tooltip/index.ts

@@ -0,0 +1 @@
+export * from './tooltip.directive';

package/src/lib/tooltip/tooltip.directive.ts

@@ -0,0 +1,247 @@
+import { DOCUMENT } from '@angular/common';
+import {
+    Component,
+    ComponentRef,
+    Directive,
+    ElementRef,
+    EnvironmentInjector,
+    OnDestroy,
+    OnInit,
+    Renderer2,
+    ViewEncapsulation,
+    computed,
+    effect,
+    inject,
+    model,
+    signal,
+    viewChild,
+} from '@angular/core';
+import { Placement } from '@floating-ui/dom';
+import { addComponent } from '../../utils/add-component';
+import { uniqueId } from '../../utils/random';
+import { FloatingUtility } from '../floating/floating';
+
+export type TooltipPlacement = Extract<Placement, 'bottom' | 'left' | 'right' | 'top'>;
+
+export interface TooltipProps {
+    /** The tooltip content. */
+    label?: string;
+    /**
+     * The placement of the tooltip.
+     *
+     * @default top
+     */
+    placement?: TooltipPlacement;
+    /**
+     * Whether to visually show the arrow (tail).
+     *
+     * @default true
+     */
+    showTail?: boolean;
+    /**
+     * Determines if the tooltip is disabled.
+     *
+     * @default false
+     */
+    disabled?: boolean;
+}
+
+/**
+ * Brief message that provide additional guidance and helps users perform an action if needed.
+ *
+ * @example
+ *     <span [ui-tooltip]="{
+ *     label: 'I explain what this button does',
+ *     placement: 'top',
+ *     }">Hover me</span>
+ *
+ * @name Tooltip
+ * @phase Dev
+ */
+@Directive({
+    selector: '[ui-tooltip]',
+    standalone: true,
+    host: {
+        '(mouseenter)': 'handleOpenEvent($event)',
+        '(mouseleave)': 'handleCloseEvent()',
+        '(focusin)': 'handleOpenEvent($event)',
+        '(blur)': 'handleCloseEvent()',
+    },
+})
+export class UITooltipDirective implements OnDestroy, OnInit {
+    readonly value = model<TooltipProps | string | { truncated: true } | undefined>(undefined, {
+        alias: 'ui-tooltip',
+    });
+
+    readonly tooltipId = uniqueId('tooltip');
+
+    readonly props = computed(() => {
+        const value = this.value();
+
+        const next: TooltipProps & { truncated?: true } = {};
+
+        if (!value) return next;
+
+        if (typeof value === 'string') {
+            return { ...next, label: value.trim() };
+        } else {
+            return { ...next, ...value };
+        }
+    });
+
+    host = inject<ElementRef<HTMLElement>>(ElementRef);
+    renderer = inject(Renderer2);
+    env = inject(EnvironmentInjector);
+    document = inject<Document>(DOCUMENT);
+
+    floating = new FloatingUtility(this.renderer);
+
+    private readonly computedPlacement = signal<TooltipPlacement | null>(null);
+    private tooltipComponent?: ComponentRef<UITooltip> | null;
+
+    constructor() {
+        effect(() => {
+            this.updateTooltipProps(this.props());
+        });
+    }
+
+    get arrowEl() {
+        return this.tooltipComponent?.instance.arrowElement;
+    }
+
+    get tooltipEl() {
+        return this.tooltipComponent?.location.nativeElement as HTMLElement;
+    }
+
+    get referenceEl() {
+        let el = this.host.nativeElement;
+        if (!el?.checkVisibility?.()) el = (el?.firstElementChild as HTMLElement) || null;
+        return el;
+    }
+
+    updateTooltipProps(props: TooltipProps) {
+        if (!this.tooltipComponent) return;
+        this.tooltipComponent.instance.props.set({
+            ...props,
+
+            // ensure placement is always up to date
+            placement: this.computedPlacement() || props.placement,
+        });
+        this.tooltipComponent.changeDetectorRef.detectChanges();
+    }
+
+    handleOpenEvent(event: Event) {
+        const props = this.props();
+
+        if (
+            !props.label ||
+            event.target !== this.referenceEl ||
+            props.disabled ||
+            // skip if not actively truncated
+            (props.truncated && this.referenceEl?.scrollWidth <= this.referenceEl?.clientWidth)
+        )
+            return;
+
+        if (props.truncated) this.addComponent({ label: this.referenceEl.textContent || '' });
+
+        if (this.tooltipEl) this.renderer.setStyle(this.tooltipEl, 'display', 'block');
+
+        this.floating
+            .compute({
+                placement: this.props()?.placement || 'top',
+                reference: this.referenceEl,
+                floating: this.tooltipEl,
+                arrow: this.arrowEl,
+                offsetOptions: this.arrowEl ? 8 : 4,
+                refWidth: false,
+            })
+            .then(({ placement }) => {
+                if (this.tooltipEl && placement !== this.props()?.placement)
+                    this.computedPlacement.set(placement as TooltipPlacement);
+            });
+    }
+
+    handleCloseEvent() {
+        const { label, truncated } = this.props();
+        if (!label) return;
+
+        if (truncated) this.removeComponent();
+        if (this.tooltipEl) this.renderer.setStyle(this.tooltipEl, 'display', 'none');
+    }
+
+    ngOnDestroy(): void {
+        this.handleCloseEvent();
+        if (this.referenceEl) this.renderer.removeAttribute(this.referenceEl, 'aria-labelledby');
+
+        this.removeComponent();
+    }
+
+    removeComponent() {
+        if (this.tooltipComponent) {
+            this.renderer.removeChild(this.tooltipEl.parentNode, this.tooltipEl);
+            this.tooltipComponent.destroy();
+            this.tooltipComponent = null;
+        }
+    }
+
+    addComponent(props = this.props()): boolean {
+        if (
+            // if we can't render or already rendered or disabled or no label we can't show
+            !this.document ||
+            !this.referenceEl ||
+            !props.label
+        ) {
+            return false;
+        }
+
+        this.tooltipComponent = addComponent(this.env, UITooltip, 'ui-tooltip')!;
+
+        if (this.tooltipEl) this.renderer.setStyle(this.tooltipEl, 'display', 'none');
+        this.tooltipComponent.instance.id.set(this.tooltipId);
+        this.updateTooltipProps(props);
+        return true;
+    }
+
+    ngOnInit(): void {
+        if (!this.referenceEl || !this.props().label) return;
+
+        if (this.props().truncated) {
+            this.renderer.setAttribute(this.referenceEl, 'data-truncated', 'true');
+        } else {
+            this.renderer.setAttribute(this.referenceEl, 'aria-labelledby', this.tooltipId);
+            this.addComponent(this.props());
+        }
+    }
+}
+
+/** Single use component to display tooltip content. */
+@Component({
+    selector: 'ui-tooltip',
+    standalone: true,
+    template: `
+        <span data-text>{{ props().label }}</span>
+        @if (props().showTail !== false) {
+            <span aria-hidden="true" data-arrow #arrow></span>
+        }
+    `,
+    styleUrl: './tooltip.scss',
+    encapsulation: ViewEncapsulation.None,
+    host: {
+        'data-bspk': 'tooltip',
+        role: 'tooltip',
+        '[attr.data-placement]': 'props().placement || "top"',
+        '[attr.id]': 'id() || null',
+    },
+})
+export class UITooltip {
+    readonly arrow = viewChild<ElementRef>('arrow');
+
+    /** Tooltip id for a11y labelling */
+    readonly id = signal<string | undefined>(undefined);
+
+    readonly props = model<TooltipProps>({});
+
+    get arrowElement(): HTMLElement | null {
+        return this.arrow()?.nativeElement || null;
+    }
+}