@bspk/ui-ngx 0.0.1

package/src/utils/keydown-handler.ts

@@ -0,0 +1,70 @@
+import { KeyboardEventCode } from './keyboard';
+
+export type KeysCallback = Partial<Record<KeyboardEventCode, ((event: KeyboardEvent) => void) | null>>;
+
+export const getEventCode = (event: KeyboardEvent) => {
+    let eventCode = event.code as KeyboardEventCode;
+    if (event.ctrlKey && event.altKey && event.code === 'Space') eventCode = 'Ctrl+Option+Space';
+    if (event.shiftKey && !eventCode.startsWith('Shift')) eventCode = `Shift+${event.code}` as KeyboardEventCode;
+
+    return eventCode;
+};
+
+/**
+ * Handles multiple keydown events with specific callbacks for each key.
+ *
+ * @param keysCallback - An object where keys are keyboard event codes and values are callback functions.
+ * @returns A function that can be used as an event handler for keydown events.
+ */
+export function keydownHandler(
+    keysCallback: KeysCallback,
+    overrides?: { stopPropagation?: boolean; preventDefault?: boolean },
+): (event: KeyboardEvent) => KeyboardEventCode | null;
+export function keydownHandler(
+    keysCallback: KeysCallback[],
+    overrides?: { stopPropagation?: boolean; preventDefault?: boolean },
+): (event: KeyboardEvent) => KeyboardEventCode | null;
+export function keydownHandler(
+    keysCallbackProp: KeysCallback | KeysCallback[] = {},
+    overrides: { stopPropagation?: boolean; preventDefault?: boolean } = {},
+): (event: KeyboardEvent) => KeyboardEventCode | null {
+    const { stopPropagation = false, preventDefault = false } = overrides;
+
+    const keysCallback = Array.isArray(keysCallbackProp)
+        ? keysCallbackProp.reduce((acc, curr) => {
+              // Merge multiple KeysCallback objects into one merging individual callbacks
+              return {
+                  ...acc,
+                  ...Object.fromEntries(
+                      Object.entries(curr).map(([key, callback]) => {
+                          const existingCallback = acc[key as keyof KeysCallback];
+
+                          if (callback && existingCallback) {
+                              // If there's already a callback for this key, chain them
+                              return [
+                                  key,
+                                  (event: KeyboardEvent) => {
+                                      existingCallback(event);
+                                      callback(event);
+                                  },
+                              ];
+                          }
+                          return [key, callback];
+                      }),
+                  ),
+              };
+          }, {})
+        : keysCallbackProp;
+
+    return (event: KeyboardEvent) => {
+        const eventCode = getEventCode(event);
+        const callback = keysCallback[eventCode];
+
+        if (callback) {
+            callback(event);
+            if (stopPropagation) event.stopPropagation();
+            if (preventDefault) event.preventDefault();
+        }
+        return callback ? eventCode : null;
+    };
+}

package/src/utils/mask.ts

@@ -0,0 +1,84 @@
+export interface Mask {
+    /** The input mask */
+    mask: string;
+
+    /** The regex patterns for specific characters */
+    patterns: Record<string, { pattern: RegExp; optional?: boolean }>;
+
+    /** Any additional characters that should be considered special */
+    specialCharacters?: string[];
+
+    /** Drop special characters from the input value */
+    dropSpecialCharacters?: boolean;
+
+    /** For numeric fields, allow negative numbers */
+    allowNegative?: boolean;
+
+    /** The mask prefix */
+    prefix?: string;
+
+    /** The mask suffix */
+    suffix?: string;
+
+    /** The error message to display if invalid */
+    errorMessage?: string;
+}
+
+/** Mask for a phone number i.e. ###-###-#### */
+export const PhoneNumberMask: Mask = {
+    mask: '#00-000-0000',
+    patterns: {
+        '#': { pattern: /[2-9]/ },
+        '0': { pattern: /[0-9]/ },
+    },
+    errorMessage: 'Phone number must be formatted as ###-###-####',
+};
+
+/** Different variant using periods instead of dashes i.e. ###.###.#### */
+export const PhoneNumber2Mask: Mask = {
+    mask: '#00.000.0000',
+    patterns: {
+        '#': { pattern: /[2-9]/ },
+        '0': { pattern: /[0-9]/ },
+    },
+};
+
+/** Different variant using parentheses around the area code i.e. (###) ###-#### */
+export const PhoneNumber3Mask: Mask = {
+    mask: '(#00) 000-0000',
+    patterns: {
+        '#': { pattern: /[2-9]/ },
+        '0': { pattern: /[0-9]/ },
+    },
+};
+
+/** Mask for a zip code i.e. ##### OR #####-#### */
+export const ZipCodeMask: Mask = {
+    mask: '00000|00000-0000',
+    patterns: {},
+};
+
+/** Mask for a whole number i.e. #### */
+export const WholeNumberMask: Mask = {
+    mask: '0*',
+    patterns: {
+        '0': { pattern: /[0-9]/ },
+    },
+};
+
+/** Decimal number that supports two decimal places i.e. ###.## */
+export const DecimalNumberMask: Mask = Object.freeze({
+    mask: '0*.00',
+    patterns: {
+        '0': { pattern: /^(0|[1-9]d*)(.d+)?$/ },
+    },
+});
+
+export class Masks {
+    static from(mask: Mask, overrides?: Partial<Mask>) {
+        return {
+            ...mask,
+            ...overrides,
+        };
+    }
+}

package/src/utils/math.ts

@@ -0,0 +1,3 @@
+export function clamp(value: number, min: number, max: number): number {
+    return Math.max(min, Math.min(max, value));
+}

package/src/utils/providers.ts

@@ -0,0 +1,14 @@
+import { forwardRef, Provider, Type } from '@angular/core';
+import { ControlValueAccessor, NG_VALIDATORS, NG_VALUE_ACCESSOR, Validator } from '@angular/forms';
+
+export const provideValueAccessor = (Component: Type<ControlValueAccessor>): Provider => ({
+    multi: true,
+    provide: NG_VALUE_ACCESSOR,
+    useExisting: forwardRef(() => Component),
+});
+
+export const provideValidator = (Component: Type<Validator>): Provider => ({
+    multi: true,
+    provide: NG_VALIDATORS,
+    useExisting: forwardRef(() => Component),
+});

package/src/utils/random.ts

@@ -0,0 +1,29 @@
+/**
+ * Returns a random integer between min and max (inclusive).
+ *
+ * @param min - The minimum value (inclusive).
+ * @param max - The maximum value (inclusive).
+ * @returns A random integer between min and max.
+ */
+export function randomNumber(min = 0, max = 100): number {
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+/**
+ * Returns a random string of alphanumeric characters.
+ *
+ * @param length - The length of the random ID to generate.
+ * @returns A random string of the specified length containing alphanumeric characters.
+ */
+export function randomString(length = 8): string {
+    const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
+    let result = '';
+    const rand = new Uint32Array(length);
+    window.crypto.getRandomValues(rand);
+    for (let i = 0; i < length; i++) result += chars[rand[i] % chars.length];
+    return result;
+}
+
+export function uniqueId(prefix: string): string {
+    return `${prefix}-${randomString(8)}`;
+}

package/src/utils/scroll-limit-style.ts

@@ -0,0 +1,27 @@
+export interface ScrollLimitStyleProps {
+    /**
+     * The maximum number of ListItems to show before scrolling is enabled.
+     *
+     * Used in conjunction with scrollLimitStyle utility.
+     */
+    scrollLimit?: number;
+}
+
+export function scrollLimitStyle(scrollLimitProp: unknown, itemCount: unknown) {
+    const scrollLimit = Number(scrollLimitProp);
+
+    // Check:
+    // 1. scrollLimit is valid
+    // 2. itemCount is a number
+    // 3. scrollLimit is less than itemCount
+    // If any of these fail, return undefined (no scrolling)
+    if (Number.isNaN(scrollLimit) || scrollLimit <= 0 || typeof itemCount !== 'number' || scrollLimit > itemCount)
+        return {};
+
+    return {
+        display: 'flex',
+        flexDirection: 'column',
+        maxHeight: `calc(var(--list-item-height) * ${scrollLimit})`,
+        overflow: 'hidden auto',
+    };
+}

package/src/utils/send-aria-live-message.ts

@@ -0,0 +1,17 @@
+/**
+ * This utility function sends an ARIA live message to assistive technologies by dynamically creating a live region
+ * element in the DOM.
+ *
+ * @param message The message to be announced by screen readers.
+ * @param live The ARIA live attribute value, either 'assertive' or 'polite'. Defaults to 'polite'.
+ */
+export function sendAriaLiveMessage(message: string, live: 'assertive' | 'polite' = 'polite') {
+    // remove existing AriaLiveMessage element from dom
+    document.querySelectorAll('[data-bspk-aria-live]').forEach((el) => el.remove());
+
+    // add new AriaLiveMessage element to dom
+    document.body.insertAdjacentHTML(
+        'beforeend',
+        `<div data-bspk-aria-live aria-live=${live || 'polite'} data-sr-only role="alert">${message}</div>`,
+    );
+}

package/src/utils/send-snackbar.ts

@@ -0,0 +1,55 @@
+import { sendAriaLiveMessage } from './send-aria-live-message';
+
+const snackbarContainer = () => {
+    return document.getElementById('bspk-snackbar-container') as HTMLDivElement | null;
+};
+
+/**
+ * A temporary utility to send a snackbar message to the user. In the future, this should be replaced with the proper
+ * snackbar service/component.
+ */
+export function sendSnackbar(message: string): void {
+    queueMicrotask(() => {
+        // minimal snackbar positioned center bottom in the body and removed after 3 seconds
+
+        let container = snackbarContainer();
+
+        if (!container) {
+            container = document.createElement('div');
+            container.style.position = 'fixed';
+            container.style.bottom = '1em';
+            container.style.left = '50%';
+            container.style.transform = 'translateX(-50%)';
+            container.style.display = 'flex';
+            container.style.flexDirection = 'column';
+            container.style.alignItems = 'center';
+            container.style.gap = '0.5em';
+            container.id = 'bspk-snackbar-container';
+            document.body.appendChild(container);
+        }
+
+        const snackbar = document.createElement('div');
+        snackbar.style.background = 'black';
+        snackbar.style.color = 'white';
+        snackbar.style.padding = '8px 16px';
+        snackbar.style.borderRadius = '4px';
+        snackbar.style.zIndex = 'var(--z-index-dialog)';
+        snackbar.textContent = message;
+        container.appendChild(snackbar);
+
+        setTimeout(() => {
+            container.removeChild(snackbar);
+        }, 3000);
+
+        // For environments where DOM is not available (e.g., server-side rendering), we can log the message
+        if (typeof document === 'undefined') {
+            // eslint-disable-next-line no-console
+            console.error(message);
+        }
+
+        // eslint-disable-next-line no-console
+        console.info('Snackbar message:', message);
+
+        sendAriaLiveMessage(message);
+    });
+}

package/src/utils/test-props.ts

@@ -0,0 +1,21 @@
+import { inputBinding, signal } from '@angular/core';
+import { TestComponentOptions } from '@angular/core/testing';
+
+/**
+ * This helps create test props for components in a type-safe way.
+ *
+ * @example
+ *     componentTestProps<UITag>({
+ *         label: 'Test Tag',
+ *         color: 'blue',
+ *     });
+ */
+export function componentTestProps<T>(
+    props: Partial<Record<keyof T, unknown>>,
+    additionalTestComponentOptions?: Partial<TestComponentOptions>,
+): TestComponentOptions {
+    return {
+        bindings: Object.entries(props).map(([key, value]) => inputBinding(key, signal(value))),
+        ...additionalTestComponentOptions,
+    };
+}

package/src/utils/util.ts

@@ -0,0 +1,3 @@
+export const noop = () => {
+    /* noop */
+};

package/tsconfig.lib.json

@@ -0,0 +1,15 @@
+/* To learn more about Typescript configuration file: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html. */
+/* To learn more about Angular compiler options: https://angular.dev/reference/configs/angular-compiler-options. */
+{
+    "extends": "../../tsconfig.json",
+    "compilerOptions": {
+        "outDir": "../../out-tsc/lib",
+        "declaration": true,
+        "declarationMap": true,
+        "inlineSources": true,
+        "sourceMap": true,
+        "types": []
+    },
+    "include": ["src/**/*.ts", "src/lib/scrim/example.ts"],
+    "exclude": ["**/*.spec.ts"]
+}

package/tsconfig.lib.prod.json

@@ -0,0 +1,11 @@
+/* To learn more about Typescript configuration file: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html. */
+/* To learn more about Angular compiler options: https://angular.dev/reference/configs/angular-compiler-options. */
+{
+    "extends": "./tsconfig.lib.json",
+    "compilerOptions": {
+        "declarationMap": false
+    },
+    "angularCompilerOptions": {
+        "compilationMode": "partial"
+    }
+}