@signal24/vue-foundation 3.8.1 → 4.1.0

package/src/helpers/context-menu.ts

@@ -0,0 +1,108 @@
+interface ContextMenuItem {
+    title: string;
+    handler: () => void;
+    class?: string;
+    shouldConfirm?: boolean;
+}
+
+interface ContextMenuConfig {
+    targetClass?: string;
+    class?: string;
+    items: (ContextMenuItem | '-')[];
+}
+
+export function showContextMenu(e: MouseEvent, config: ContextMenuConfig) {
+    const wrapperEl = document.createElement('div');
+    wrapperEl.classList.add('vf-overlay');
+    wrapperEl.addEventListener('click', closeMenu);
+    document.body.appendChild(wrapperEl);
+
+    const menuEl = document.createElement('div');
+    menuEl.classList.add('vf-context-menu');
+    menuEl.style.position = 'absolute';
+    wrapperEl.appendChild(menuEl);
+
+    const target = e.currentTarget as HTMLElement;
+    target.style.userSelect = 'none';
+    target.classList.add('context-menu-active');
+
+    if (config.targetClass) {
+        target.classList.add(config.targetClass);
+    }
+
+    if (config.class) {
+        menuEl.classList.add(config.class);
+    }
+
+    config.items.forEach(item => {
+        if (item == '-') {
+            const separatorEl = document.createElement('div');
+            separatorEl.classList.add('separator');
+            menuEl.appendChild(separatorEl);
+            return;
+        }
+
+        const itemEl = document.createElement('div');
+        itemEl.classList.add('item');
+        itemEl.style.userSelect = 'none';
+        itemEl.innerText = item.title;
+        menuEl.appendChild(itemEl);
+
+        if (item.class) {
+            itemEl.classList.add(item.class);
+        }
+
+        if (item.shouldConfirm) {
+            itemEl.addEventListener('click', () => item.handler());
+        } else {
+            itemEl.addEventListener('click', () => confirmAction(itemEl, item.handler));
+        }
+    });
+
+    const dx = window.innerWidth - e.clientX;
+    const dy = window.innerHeight - e.clientY;
+    const menuHeight = menuEl.offsetHeight;
+    const menuWidth = menuEl.offsetWidth;
+
+    const left = dx < menuWidth ? e.clientX - menuWidth - 1 : e.clientX + 1;
+    const top = dy < menuHeight ? e.clientY - menuHeight - 1 : e.clientY + 1;
+
+    menuEl.style.left = left + 'px';
+    menuEl.style.top = top + 'px';
+
+    setTimeout(() => {
+        menuEl.style.width = menuEl.offsetWidth + 'px';
+    }, 50);
+
+    function closeMenu() {
+        if (config.targetClass) {
+            target.classList.remove(config.targetClass);
+        }
+
+        target.classList.remove('context-menu-active');
+        target.style.userSelect = '';
+
+        wrapperEl.remove();
+    }
+
+    function confirmAction(itemEl: HTMLElement, handler: () => void) {
+        if (itemEl.classList.contains('pending-confirm')) {
+            return handler();
+        }
+
+        const originalContent = itemEl.innerHTML;
+        itemEl.classList.add('pending-confirm');
+        itemEl.innerText = 'Confirm';
+
+        const onMouseLeave = () => {
+            itemEl.classList.remove('pending-confirm');
+            itemEl.innerHTML = originalContent;
+            itemEl.removeEventListener('mouseleave', onMouseLeave);
+        };
+
+        itemEl.addEventListener('mouseleave', onMouseLeave);
+        e.stopPropagation();
+    }
+}
+
+// TODO: actually de-select text rather than just using CSS to hide its selection

package/src/helpers/delay.ts

@@ -0,0 +1,2 @@
+export const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
+export const sleepSecs = (secs: number) => sleep(secs * 1000);

package/src/helpers/error.ts

@@ -0,0 +1,41 @@
+import { showAlert } from '@/components/alert-helpers';
+
+import { VfOptions } from '../config';
+
+export class UserError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'UserError';
+    }
+}
+
+export function formatError(err: any): string {
+    if (err instanceof UserError) {
+        return err.message;
+    }
+
+    const errMessage = toError(err).message;
+    return `An application error has occurred:\n\n${errMessage}\n\nPlease refresh the page and try again. If this error persists, ${VfOptions.unhandledErrorSupportText}.`;
+}
+
+export function toError(err: any) {
+    return err instanceof Error ? err : new Error(String(err));
+}
+
+export async function handleErrorAndAlert(errIn: any, alertTitle?: string) {
+    const err = toError(errIn);
+
+    if (!(err instanceof UserError)) {
+        VfOptions.errorHandler(err);
+    }
+
+    return alertTitle ? showAlert(alertTitle, err) : showAlert(err);
+}
+
+export async function handleError(errIn: any) {
+    const err = toError(errIn);
+
+    if (!(err instanceof UserError)) {
+        VfOptions.errorHandler(err);
+    }
+}

package/src/helpers/index.ts

@@ -0,0 +1,9 @@
+export * from './array';
+export * from './context-menu';
+export * from './delay';
+export * from './error';
+export * from './mask';
+export * from './number';
+export * from './object';
+export * from './openapi';
+export * from './string';

package/src/helpers/mask.ts

@@ -0,0 +1,105 @@
+import type { AnyComponentPublicInstance } from '@/components';
+
+/*///////////////////////////////////////////////
+Component Overlay Masking
+//////////////////////////////////////////////*/
+const MaskState = Symbol('MaskState');
+interface IMaskState {
+    [MaskState]?: {
+        maskEl: HTMLElement;
+    };
+}
+type MaskElement = Element & IMaskState;
+
+export function maskComponent(cmp: AnyComponentPublicInstance, message?: string) {
+    const el = cmp.$.vnode.el;
+    const modalParentlEl = el!.closest('.vf-modal');
+    return maskEl(modalParentlEl ?? el, message);
+}
+
+export function unmaskComponent(cmp: AnyComponentPublicInstance) {
+    const el = cmp.$.vnode.el;
+    const modalParentlEl = el!.closest('.vf-modal');
+    return unmaskEl(modalParentlEl ?? el);
+}
+
+export function maskEl(el: MaskElement, message?: string) {
+    if (!el[MaskState]) {
+        const maskEl = document.createElement('div');
+        maskEl.classList.add('vf-mask');
+        el.appendChild(maskEl);
+        el[MaskState] = { maskEl };
+    }
+
+    el[MaskState].maskEl.innerText = message ?? '';
+
+    // todo: add inner HTML to config
+
+    return () => unmaskEl(el);
+}
+
+export function unmaskEl(el: MaskElement) {
+    if (!el[MaskState]) return;
+    el.removeChild(el[MaskState].maskEl);
+}
+
+/*///////////////////////////////////////////////
+Form Masking
+//////////////////////////////////////////////*/
+const FormMaskState = Symbol('FormMaskState');
+interface IFormMaskState {
+    [FormMaskState]?: {
+        disabledElements: HTMLElement[];
+        waitButton: HTMLElement;
+        buttonText: string;
+    };
+}
+type FormMaskElement = Element & IFormMaskState;
+
+export function maskForm(formOrCmp: Element | AnyComponentPublicInstance, buttonSelector?: string | Element, buttonText?: string) {
+    const form = formOrCmp instanceof Element ? formOrCmp : getFormFromCmp(formOrCmp);
+    form.classList.add('vf-masked');
+
+    const buttonEl = (
+        buttonSelector instanceof Element ? buttonSelector : form.querySelectorAll(buttonSelector ?? 'button:not([disabled])')[0]
+    ) as HTMLElement;
+    const originalButtonText = buttonEl.tagName === 'INPUT' ? (buttonEl as HTMLInputElement).value : buttonEl.innerText;
+    buttonEl.setAttribute('disabled', 'disabled');
+    buttonEl.innerText = buttonText ?? 'Please wait...';
+
+    const inputsQR = form.querySelectorAll('input:not([disabled]), select:not([disabled]), textarea:not([disabled]), button:not([disabled])');
+    const inputs = [...inputsQR] as HTMLElement[];
+    inputs.forEach(el => el.setAttribute('disabled', 'disabled'));
+
+    (form as FormMaskElement)[FormMaskState] = {
+        disabledElements: inputs,
+        waitButton: buttonEl,
+        buttonText: originalButtonText
+    };
+
+    return () => unmaskForm(form);
+}
+
+export function unmaskForm(formOrCmp: Element | AnyComponentPublicInstance) {
+    const form = formOrCmp instanceof Element ? formOrCmp : getFormFromCmp(formOrCmp);
+
+    const state = (form as FormMaskElement)[FormMaskState];
+    if (!state) return;
+
+    form.classList.remove('vf-masked');
+
+    state.disabledElements.forEach(el => el.removeAttribute('disabled'));
+    state.waitButton.innerText = state.buttonText;
+    state.waitButton.removeAttribute('disabled');
+
+    delete (form as FormMaskElement)[FormMaskState];
+}
+
+function getFormFromCmp(cmp: AnyComponentPublicInstance) {
+    const cmpEl = cmp.$.vnode.el!;
+    if (cmpEl.tagName === 'FORM') {
+        return cmpEl as HTMLElement;
+    } else {
+        return cmpEl.querySelector('form') as HTMLElement;
+    }
+}

package/src/helpers/number.ts

@@ -0,0 +1,3 @@
+export function formatNumber(value: number) {
+    return value.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+}

package/src/helpers/object.ts

@@ -0,0 +1,19 @@
+import { cloneDeep } from 'lodash';
+
+export function cloneProp<T>(prop: T | undefined | null, fallback: T): T {
+    if (prop !== undefined && prop !== null) {
+        return cloneDeep(prop);
+    } else {
+        return fallback;
+    }
+}
+
+export function nullifyEmptyInputs<T extends Record<string, unknown>, K extends keyof T>(obj: T, fields: K[]): T {
+    const result = { ...obj };
+    for (const key of fields) {
+        if (result[key] === '') {
+            result[key] = null as any;
+        }
+    }
+    return result;
+}

package/src/helpers/openapi.ts

@@ -0,0 +1,82 @@
+import { UserError } from './error';
+
+interface IRequestOptions {
+    readonly method: 'GET' | 'PUT' | 'POST' | 'DELETE' | 'OPTIONS' | 'HEAD' | 'PATCH';
+    readonly url: string;
+    readonly path?: Record<string, any>;
+    readonly cookies?: Record<string, any>;
+    readonly headers?: Record<string, any>;
+    readonly query?: Record<string, any>;
+    readonly formData?: Record<string, any>;
+    readonly body?: any;
+    readonly mediaType?: string;
+    readonly responseHeader?: string;
+    readonly errors?: Record<number, string>;
+}
+
+interface IBaseHttpRequest {
+    request<T>(options: IRequestOptions): ICancelablePromise<T>;
+}
+
+interface IApiClient {
+    request: IBaseHttpRequest;
+}
+
+interface IApiError extends Error {
+    status: number;
+    statusText: string;
+    body: any;
+}
+
+declare class ICancelablePromise<T = any> {
+    constructor(executor: (resolve: (value: any) => void, reject: (reason: any) => void, onCancel: (cancel: () => void) => void) => void);
+    then<TResult1 = any, TResult2 = never>(
+        onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | undefined | null,
+        onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null
+    ): Promise<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | null): Promise<T | TResult>;
+    finally(onfinally?: (() => void) | undefined | null): Promise<T>;
+    cancel(): void;
+}
+
+interface IWrappedApiClientOptions<P extends ICancelablePromise = ICancelablePromise, Arguments extends unknown[] = any[]> {
+    apiClient: IApiClient;
+    onRequest?: (options: IRequestOptions) => IRequestOptions;
+    onError?: (err: Error, options: IRequestOptions) => Error | null | void;
+    CancelablePromise: new (...arguments_: Arguments) => P;
+}
+
+function isApiError(err: any): err is IApiError {
+    return err instanceof Error && 'status' in err && 'body' in err;
+}
+
+export function installApiClientInterceptors({ apiClient, onRequest, onError, CancelablePromise }: IWrappedApiClientOptions) {
+    const originalRequest = apiClient.request.request.bind(apiClient.request);
+    apiClient.request.request = (options: IRequestOptions) => {
+        if (onRequest) {
+            options = onRequest(options);
+        }
+
+        return new CancelablePromise((resolve: (value: any) => void, reject: (err: any) => void, onCancel: (handler: () => void) => void) => {
+            const promise = originalRequest(options);
+            onCancel(promise.cancel);
+            promise.then(resolve).catch(err => {
+                if (isApiError(err) && typeof err.body === 'object' && 'error' in err.body) {
+                    if (err.status === 422) {
+                        return reject(new UserError(err.body.error));
+                    }
+                }
+                if (onError) {
+                    const handlerResult = onError(err, options);
+                    if (handlerResult === null) {
+                        return;
+                    }
+                    if (handlerResult instanceof Error) {
+                        return reject(handlerResult);
+                    }
+                }
+                reject(err);
+            });
+        });
+    };
+}

package/src/helpers/string.ts

@@ -0,0 +1,27 @@
+// placing this here so we don't have to use the ESLint rule everywhere
+// eslint-disable-next-line vue/prefer-import-from-vue
+export { escapeHtml } from '@vue/shared';
+
+export function nl2br(value: string) {
+    return value.replace(/\n/g, '<br>');
+}
+
+export function desnakeCase(value: string) {
+    return value.replace(/_/g, ' ');
+}
+
+export function formatPhone(value: string) {
+    const cleanValue = value.replace(/\D/g, '').replace(/^1/, '');
+    if (cleanValue.length != 10) return value;
+    return '(' + cleanValue.substring(0, 3) + ') ' + cleanValue.substring(3, 6) + '-' + cleanValue.substring(6);
+}
+
+export function formatUSCurrency(value: string | number) {
+    return (
+        '$' +
+        Number(value)
+            .toFixed(3)
+            .replace(/0$/, '')
+            .replace(/\B(?=(\d{3})+(?!\d))/g, ',')
+    );
+}

package/src/hooks/index.ts

@@ -0,0 +1,2 @@
+export { useInfiniteScroll } from './infinite-scroll';
+export { useResizeWatcher } from './resize-watcher';

package/src/hooks/infinite-scroll.ts

@@ -0,0 +1,107 @@
+import { type ComponentInternalInstance, getCurrentInstance, onActivated, onBeforeUnmount, onDeactivated, onMounted } from 'vue';
+
+const HookState = Symbol('HookState');
+interface IHookState {
+    el?: InfiniteScrollHandler;
+    ancestor?: InfiniteScrollHandler;
+    window?: InfiniteScrollHandler;
+}
+type InfiniteScrollComponent = ComponentInternalInstance & { [HookState]?: IHookState };
+
+export interface IInfiniteScrollOptions {
+    elScrolledToBottom?: () => void;
+    ancestorScrolledToBottom?: () => void;
+    windowScrolledToBottom?: () => void;
+}
+
+export function useInfiniteScroll(options: IInfiniteScrollOptions, instance?: ComponentInternalInstance) {
+    const resolvedInstance = instance ?? getCurrentInstance()!;
+    onMounted(() => installScrollHook(resolvedInstance, options), resolvedInstance);
+    onActivated(() => reinstallScrollHook(resolvedInstance), resolvedInstance);
+    onDeactivated(() => uninstallScrollHook(resolvedInstance), resolvedInstance);
+    onBeforeUnmount(() => uninstallScrollHook(resolvedInstance), resolvedInstance);
+}
+
+export function installScrollHook(cmp: InfiniteScrollComponent, options: IInfiniteScrollOptions) {
+    const hookState: IHookState = {};
+
+    if (options.elScrolledToBottom) {
+        hookState.el = new InfiniteScrollHandler(cmp.vnode.el as Element, options.elScrolledToBottom);
+        hookState.el.install();
+    }
+
+    if (options.ancestorScrolledToBottom) {
+        const scrollableAncestorEl = discoverScrollableAncestorEl(cmp.vnode.el as Element);
+        if (scrollableAncestorEl) {
+            hookState.ancestor = new InfiniteScrollHandler(scrollableAncestorEl, options.ancestorScrolledToBottom);
+            hookState.ancestor.install();
+        } else {
+            console.warn('no scollable ancestor found for component:', cmp);
+        }
+    }
+
+    if (options.windowScrolledToBottom) {
+        hookState.window = new InfiniteScrollHandler(window as unknown as Element, options.windowScrolledToBottom);
+        hookState.window.install();
+    }
+
+    cmp[HookState] = hookState;
+}
+
+export function reinstallScrollHook(cmp: InfiniteScrollComponent) {
+    const hookState = cmp[HookState];
+    hookState?.el?.install();
+    hookState?.ancestor?.install();
+    hookState?.window?.install();
+}
+
+export function uninstallScrollHook(cmp: InfiniteScrollComponent) {
+    const hookState = cmp[HookState];
+    hookState?.el?.uninstall();
+    hookState?.ancestor?.uninstall();
+    hookState?.window?.uninstall();
+}
+
+const ScrollableOverflowValues = ['auto', 'scroll'];
+function discoverScrollableAncestorEl(el: Element): Element | null {
+    const parent = el.parentElement;
+    if (!parent) return null;
+
+    const computedStyle = window.getComputedStyle(parent);
+    if (
+        ScrollableOverflowValues.includes(computedStyle.overflow) ||
+        ScrollableOverflowValues.includes(computedStyle.overflowX) ||
+        ScrollableOverflowValues.includes(computedStyle.overflowY)
+    ) {
+        return parent;
+    }
+
+    return discoverScrollableAncestorEl(parent);
+}
+
+// TODO: switch to intersection observer
+export class InfiniteScrollHandler {
+    isTripped = false;
+
+    constructor(private el: Element, private handler: (e: Event) => void) {}
+
+    install() {
+        this.el.addEventListener('scroll', this.onScrollWithContext);
+    }
+
+    uninstall() {
+        this.el.removeEventListener('scroll', this.onScrollWithContext);
+    }
+
+    onScrollWithContext = this.onScroll.bind(this);
+    onScroll(e: Event) {
+        if (Math.ceil(this.el.scrollTop + this.el.clientHeight + 5) >= this.el.scrollHeight) {
+            if (!this.isTripped) {
+                this.handler(e);
+                this.isTripped = true;
+            }
+        } else if (this.isTripped) {
+            this.isTripped = false;
+        }
+    }
+}

package/src/hooks/resize-watcher.ts

@@ -0,0 +1,8 @@
+import { onActivated, onBeforeUnmount, onDeactivated, onMounted } from 'vue';
+
+export function useResizeWatcher(fn: () => void) {
+    onMounted(() => window.addEventListener('resize', fn));
+    onActivated(() => window.addEventListener('resize', fn));
+    onDeactivated(() => window.removeEventListener('resize', fn));
+    onBeforeUnmount(() => window.removeEventListener('resize', fn));
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+import type { App } from 'vue';
+
+export * from './components';
+export { configureVf } from './config';
+export * from './filters';
+export * from './helpers';
+export * from './hooks';
+export * from './types';
+
+import { registerDirectives } from './directives';
+
+export function installVf(app: App) {
+    registerDirectives(app);
+}

package/src/types.ts

@@ -0,0 +1,14 @@
+import type { OptionalKeysOf, RequiredKeysOf } from 'type-fest';
+
+export type Branded<T, A> = A & { __brand: T };
+export type BrandOf<A> = [A] extends [Branded<infer R, unknown>] ? R : never;
+export type Debrand<A> = A extends Branded<BrandOf<A>, infer R> ? R : never;
+
+export type PickRequired<T> = T extends object ? Pick<T, RequiredKeysOf<T>> : never;
+export type PickOptional<T> = T extends object ? Pick<T, OptionalKeysOf<T>> : never;
+
+export type WithoutNever<T> = { [P in keyof T as T[P] extends never ? never : P]: T[P] };
+
+export type UnwrapBrand<T, B> = WithoutNever<{
+    [K in keyof T]: BrandOf<T[K]> extends B ? Debrand<T[K]> : never;
+}>;

package/src/vite-plugins/index.ts

@@ -0,0 +1,2 @@
+// todo: dunno why this needs .JS, but Vite panics with ERR_MODULE_NOT_FOUND if we don't
+export * from './vite-openapi-plugin.js';

package/src/vite-plugins/vite-openapi-plugin.cli.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+import { existsSync } from 'fs';
+
+import { generateOpenapiClient } from './vite-openapi-plugin.js';
+
+if (!process.argv[2]) {
+    throw new Error('Usage: vf-generate-openapi-client <openapi-yaml-path>');
+}
+
+if (!existsSync(process.argv[2])) {
+    throw new Error(`OpenAPI YAML file not found: ${process.argv[2]}`);
+}
+
+await generateOpenapiClient(process.argv[2]);

package/src/vite-plugins/vite-openapi-plugin.ts

@@ -0,0 +1,71 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, watch } from 'node:fs';
+import { rm } from 'node:fs/promises';
+
+import * as OpenAPI from 'openapi-typescript-codegen';
+
+let generatedHash: string | null = null;
+
+export function openapiClientGeneratorPlugin(openapiYamlPath: string) {
+    const generator = getGenerator(openapiYamlPath);
+
+    return {
+        name: 'openapi-types-generator',
+
+        closeBundle() {
+            generator?.close();
+        }
+    };
+}
+
+function getGenerator(openapiYamlPath: string) {
+    if (!existsSync(openapiYamlPath)) {
+        console.log(`OpenAPI YAML file not found: ${openapiYamlPath}`);
+        return null;
+    }
+
+    const watcher = watch(openapiYamlPath);
+    watcher.on('change', () => {
+        // give the writes a moment to settle
+        setTimeout(() => generateOpenapiClient(openapiYamlPath), 100);
+    });
+
+    generateOpenapiClient(openapiYamlPath);
+
+    return {
+        close() {
+            watcher.close();
+        }
+    };
+}
+
+export async function generateOpenapiClient(openapiYamlPath: string) {
+    const yaml = readFileSync(openapiYamlPath, 'utf8');
+    const hash = createHash('sha256').update(yaml).digest('hex');
+
+    if (hash === generatedHash) {
+        return;
+    }
+
+    generatedHash = hash;
+
+    try {
+        try {
+            await rm('./src/openapi-client-generated', { recursive: true });
+        } catch (e) {
+            // ignore
+        }
+
+        await OpenAPI.generate({
+            input: openapiYamlPath,
+            output: './src/openapi-client-generated',
+            clientName: 'ApiClient',
+            useOptions: true,
+            useUnionTypes: true
+        });
+
+        console.log(`[${new Date().toISOString()}] Generated client from ${openapiYamlPath} to ./src/openapi-client/`);
+    } catch (err) {
+        console.error(`[${new Date().toISOString()}] Error generating client from ${openapiYamlPath}:`, err);
+    }
+}

package/tsconfig.app.json

@@ -0,0 +1,22 @@
+{
+    "extends": "@vue/tsconfig/tsconfig.web.json",
+    "include": ["src/**/*.ts", "src/**/*.vue"],
+    "exclude": ["src/**/__tests__/*", "src/vite-plugins/*"],
+    "compilerOptions": {
+        "composite": true,
+        "baseUrl": ".",
+        "paths": {
+            "@/*": ["./src/*"]
+        },
+        "noImplicitAny": true,
+        "outDir": "dist",
+        "declaration": true,
+        "declarationDir": "dist",
+        "target": "ES2020",
+        "lib": [
+            "ES2020",
+            "DOM",
+            "DOM.Iterable"
+        ]
+    }
+}