@propelinc/citrus-ui 0.6.0 → 1.0.0

package/src/composables/id.ts

@@ -0,0 +1,23 @@
+import type { Ref } from 'vue';
+import { computed } from 'vue';
+
+let idCounter = 0;
+
+/**
+ * Generates a unique ID for a component.
+ *
+ * This is a very rudimentary backport of Vue 3.5's `useId` composable that is
+ * _not_ stable across server and client.
+ *
+ * @param id - The ID to use. If not provided, a unique ID will be generated.
+ * @returns A computed value that returns the provided ID or a unique ID.
+ */
+export function useId(id: Ref<string | null | undefined>): Ref<string> {
+  return computed(() => {
+    if (id.value) {
+      return id.value;
+    } else {
+      return `c-${idCounter++}`;
+    }
+  });
+}

package/src/composables/input-mask.ts

@@ -0,0 +1,139 @@
+import { Mask, MaskInput, type MaskInputOptions, type MaskOptions, type MaskaDetail } from 'maska';
+import { type Ref, computed, watch } from 'vue';
+
+import { useInternalValue } from '@propelinc/citrus-ui/src/composables/binding';
+
+const toNumber = (value: number | string | null): number | null => {
+  if (value === null || value === '') {
+    return null;
+  } else if (typeof value === 'number') {
+    return value;
+  } else {
+    const parsed = parseInt(value, 10);
+    return isNaN(parsed) ? null : parsed;
+  }
+};
+
+export function useInputMask(
+  /** Element to be masked */
+  input: Ref<HTMLInputElement | null>,
+  /** Value passed into the input */
+  value: Ref<string>,
+  /**
+   * Options for the mask.
+   * @see https://beholdr.github.io/maska/v2/#/?id=mask-options
+   */
+  options: Ref<MaskInputOptions>
+): {
+  mask: Ref<Mask>;
+  maskedValue: Ref<string>;
+  unmaskedValue: Ref<string>;
+} {
+  const internalValue = useInternalValue(value);
+
+  const maskOptions = computed<MaskInputOptions>((): MaskInputOptions => {
+    const onMaska = options.value.onMaska;
+    const onMaskaArray = Array.isArray(onMaska) ? onMaska : onMaska ? [onMaska] : [];
+    return {
+      ...options.value,
+      onMaska: [
+        (detail: MaskaDetail): void => {
+          internalValue.value = detail.unmasked;
+        },
+        ...onMaskaArray,
+      ],
+    };
+  });
+
+  let maskInput: MaskInput | null = null;
+  watch(input, (newInput) => {
+    if (newInput) {
+      maskInput = new MaskInput(newInput, maskOptions.value);
+    } else {
+      maskInput?.destroy();
+      maskInput = null;
+    }
+  });
+
+  const mask = computed(() => new Mask(maskOptions.value));
+  const maskedValue = computed(() => {
+    return mask.value ? mask.value.masked(internalValue.value) : value.value;
+  });
+
+  return {
+    mask,
+    maskedValue,
+    unmaskedValue: internalValue,
+  };
+}
+
+export function useMaskedMinLength(
+  minlength: Ref<number | string | null>,
+  value: Ref<string>,
+  options: Ref<MaskOptions>
+): Ref<number | null> {
+  const maskTokens = computed(() => {
+    // NOTE(mohan): '#', '@', '*' are the default tokens used by maska.
+    return ['#', '@', '*', ...Object.keys(options.value.tokens ?? {})];
+  });
+
+  // NOTE(mohan): We want `minlength` to only include token characters
+  // (e.g. '#' or '@') and ignore symbols like '-'. So, we iterate through
+  // the mask to see how many characters are required to hit minlength tokens.
+  const findMaskedMinLength = (mask: string, minlength: number): number => {
+    const maskArray = mask.split('');
+    const index = maskArray.findIndex((_, index) => {
+      const tokensInSlice = maskArray
+        .slice(0, index + 1)
+        .filter((char) => maskTokens.value.includes(char));
+      return tokensInSlice.length === minlength;
+    });
+
+    if (index === -1) {
+      return mask.length;
+    } else {
+      // Convert index to length
+      return index + 1;
+    }
+  };
+
+  const maskedMinLength = computed(() => {
+    const mask = options.value.mask;
+    const minlengthValue = toNumber(minlength.value);
+
+    if (!minlengthValue) {
+      return null;
+    } else if (!mask) {
+      return minlengthValue;
+    } else {
+      if (typeof mask === 'function') {
+        return findMaskedMinLength(mask(value.value), minlengthValue);
+      } else if (typeof mask === 'string') {
+        return findMaskedMinLength(mask, minlengthValue);
+      } else if (Array.isArray(mask)) {
+        return Math.min(...mask.map((m) => findMaskedMinLength(m, minlengthValue!)));
+      } else {
+        return minlengthValue;
+      }
+    }
+  });
+
+  return maskedMinLength;
+}
+
+export function useMaskedMaxLength(
+  maxlength: Ref<number | string | null>,
+  options: Ref<MaskOptions>
+): Ref<number | null> {
+  return computed(() => {
+    const mask = options.value.mask;
+    const maxlengthValue = toNumber(maxlength.value);
+    if (!maxlengthValue) {
+      return null;
+    } else if (!mask) {
+      return maxlengthValue;
+    } else {
+      return Math.max(maxlengthValue, mask.length);
+    }
+  });
+}

package/src/composables/router.ts

@@ -0,0 +1,64 @@
+import { type ComputedRef, type Ref, computed } from 'vue';
+import type { RouteLocationRaw } from 'vue-router';
+import { useLink } from 'vue-router';
+
+interface RouterComposableHelpers {
+  /**
+   * V-bind this to an element to make it accessible as a link.
+   */
+  linkAttrs: Ref<{
+    role?: string;
+    tabindex?: string;
+    href?: string;
+  }>;
+  /**
+   * The href to link to.
+   */
+  href: Ref<string | undefined>;
+  /**
+   * Navigates to the given route or href. If you're not using an `<a>` tag,
+   * you'll need to call this on `@click` and on `@keydown.enter`
+   */
+  navigate: (event: MouseEvent) => Promise<void>;
+}
+
+function useLinkAttrs(href: Ref<string | undefined>): ComputedRef<{
+  role?: string;
+  tabindex?: string;
+  href?: string;
+}> {
+  return computed(() => (href.value ? { role: 'link', tabindex: '0', href: href.value } : {}));
+}
+
+/**
+ * Adds router-link functionality to any component. Accepts an `undefined`
+ * route, which disables routing.
+ *
+ * @param to - The route to link to.
+ * @returns A few helpers can be used to link to the given route.
+ */
+export function useRouterLink(to: Ref<RouteLocationRaw | undefined>): RouterComposableHelpers {
+  // NOTE(mohan): We need to provide a default here or else `useLink` will throw
+  // an error.
+  const toWithDefault = computed(() => to.value ?? '');
+  const useLinkResult = useLink({ to: toWithDefault });
+  const { navigate: _navigate, href: _href } = useLinkResult;
+
+  const isRouterLink = computed(() => !!to.value);
+  const href = computed(() => (isRouterLink.value ? _href.value : undefined));
+  const linkAttrs = useLinkAttrs(href);
+  const navigate = async (event: MouseEvent): Promise<void> => {
+    if (isRouterLink.value) {
+      try {
+        await _navigate(event);
+      } catch (error) {
+        // NOTE(mohan): This matches RouterLink's behavior, which doesn't throw
+        // on navigation errors.
+        // eslint-disable-next-line no-console
+        console.debug(error);
+      }
+    }
+  };
+
+  return { linkAttrs, href, navigate };
+}

package/src/composables/slots.ts

@@ -0,0 +1,57 @@
+import type { Ref, VNode } from 'vue';
+import { Comment, Fragment, computed, useSlots } from 'vue';
+
+/**
+ * Recursively checks if a VNode or its children are visible.
+ */
+function isVisible(vnode: VNode): boolean {
+  if (vnode.type === Comment) {
+    return false;
+  }
+
+  // Handle fragments and templates recursively
+  if (vnode.type === Fragment || vnode.type === 'template') {
+    const children = vnode.children;
+
+    // Empty fragment is not visible
+    if (!children || (Array.isArray(children) && children.length === 0)) {
+      return false;
+    }
+
+    // If fragment has children, check if any child is visible
+    if (Array.isArray(children)) {
+      return children.some((child) => {
+        // Only check VNode children (filter out strings, numbers, etc.)
+        if (typeof child === 'object' && child !== null && 'type' in child) {
+          return isVisible(child as VNode);
+        }
+        // Non-VNode children (like strings) are considered visible
+        return true;
+      });
+    }
+  }
+
+  // All other vnodes are visible
+  return true;
+}
+
+export function useSlotHasContent(key: string): Ref<boolean> {
+  const slots = useSlots();
+
+  return computed(() => {
+    const slot = slots[key];
+
+    if (!slot) {
+      return false;
+    }
+
+    const slotContent = slot();
+
+    // NOTE(slanden): In Vue 3, nodes which are rendered conditionally with v-if
+    // are rendered as a comment like `<!--v-if--/>` when the condition is false.
+    // We need to filter these out to get only actually rendered content.
+    const visibleContent = slotContent.filter(isVisible);
+
+    return visibleContent.length > 0;
+  });
+}

package/src/composables/toast.ts

@@ -0,0 +1,64 @@
+import { type Ref, inject, provide, ref } from 'vue';
+
+import type { ToastVariant } from '../types';
+
+// NOTE(slanden): Cannot use a symbol here because it may break the inject/provide chain across MFEs
+const GlobalToast = 'GLOBAL_TOAST';
+
+export interface Toast {
+  id: number;
+  dataTest?: string;
+  message: string;
+  variant: ToastVariant;
+}
+
+interface ToastInjection {
+  dismissToast: (id: Toast['id']) => void;
+  showToast: (toast: Omit<Toast, 'id'>) => void;
+  toasts: Ref<Toast[]>;
+}
+
+let id = 0;
+
+function getNextIdDefault(): number {
+  return id++;
+}
+
+/**
+ * Custom provider for our toasts. Enables us to declaratively manage toasts in event handlers.
+ *
+ * NOTE: injecting `getNextId` allows us to test the composable without worry of side effects
+ */
+export function useToastProvider(getNextId: () => number = getNextIdDefault): ToastInjection {
+  const toasts = ref<Toast[]>([]);
+
+  function showToast(newToast: Omit<Toast, 'id'>): Toast['id'] {
+    const toastId = getNextId();
+
+    toasts.value.push({ ...newToast, id: toastId });
+
+    return toastId;
+  }
+
+  function dismissToast(id: Toast['id']): void {
+    toasts.value = toasts.value.filter((toast) => toast.id !== id);
+  }
+
+  const context: ToastInjection = {
+    dismissToast,
+    showToast,
+    toasts,
+  };
+
+  provide(GlobalToast, context);
+
+  return context;
+}
+
+export function useToast(): ToastInjection {
+  return inject<ToastInjection>(GlobalToast, {
+    dismissToast: () => {},
+    showToast: () => {},
+    toasts: ref<Toast[]>([]),
+  });
+}

package/src/composables/validations.ts

@@ -0,0 +1,214 @@
+import type { Ref } from 'vue';
+import { computed, inject, onBeforeUnmount, ref, unref, watch } from 'vue';
+
+import { VALIDATIONS } from '@propelinc/citrus-ui/src/services/injections/forms';
+import type { ValidationState } from '@propelinc/citrus-ui/src/types/CForm';
+
+export type Rule<Value extends string | boolean> = (value: Value) => string | boolean;
+export type Rules<Value extends string | boolean> = Rule<Value>[];
+
+export type ValidationEvent = 'blur' | 'input' | 'change';
+
+export interface UseValidationRuleCheckOptions<Value extends string | boolean> {
+  value: Ref<Value>;
+  rules: Ref<Rules<Value>>;
+  required?: Ref<boolean>;
+  onValidationResultChange?: ({
+    message,
+    valid,
+  }: {
+    message: string | null;
+    valid: boolean;
+  }) => void;
+}
+
+interface UseValidationRuleCheckReturn {
+  /** The validation error message, if any. */
+  message: Ref<string | null>;
+  /** Whether the input element is valid. This is only set after
+   * `startValidating` is called. */
+  valid: Ref<boolean>;
+  /** Whether the input element is valid regardless of whether `startValidating`
+   * has been called. */
+  passesRules: Ref<boolean>;
+  /** Starts the validation process. */
+  startValidating: () => boolean;
+  /** Clears the validation results. */
+  clearValidations: () => void;
+}
+
+/**
+ * A composable that provides manual control of validation rules for a form
+ * control. For full validation support, please see the `useValidations`
+ * composable.
+ *
+ * @see {@link useValidations}
+ *
+ * @param options - The options for the composable.
+ */
+export function useValidationRuleCheck<Value extends string | boolean>(
+  options: UseValidationRuleCheckOptions<Value>
+): UseValidationRuleCheckReturn {
+  const { value, rules, required } = options;
+  const active = ref(false);
+
+  const message = ref<string | null>(null);
+  const valid = ref(true);
+
+  const isEmpty = (v: Value): boolean =>
+    v === undefined || v === null || (typeof v === 'string' && v.trim() === '');
+
+  const requiredRule: Rule<Value> = (val: Value): boolean => {
+    return required?.value ? !isEmpty(val) : true;
+  };
+
+  const rulesResult = computed(() => {
+    const allRules: Rules<Value> = [...rules.value, requiredRule];
+    for (const rule of allRules) {
+      const result = rule(value.value);
+      if (result === false || typeof result === 'string') {
+        return result;
+      }
+    }
+    return true;
+  });
+
+  const passesRules = computed(() => rulesResult.value === true);
+
+  const validate = (): boolean => {
+    if (active.value) {
+      valid.value = passesRules.value;
+      message.value = typeof rulesResult.value === 'string' ? rulesResult.value : null;
+      options.onValidationResultChange?.({ message: message.value, valid: valid.value });
+    }
+
+    return valid.value;
+  };
+
+  watch(value, () => validate(), { immediate: true });
+  watch(rules, () => validate());
+
+  if (required) {
+    watch(required, () => validate());
+  }
+
+  const startValidating = (): boolean => {
+    active.value = true;
+    return validate();
+  };
+
+  const clearValidations = (): void => {
+    message.value = null;
+    valid.value = true;
+    active.value = false;
+  };
+
+  return { message, valid, startValidating, clearValidations, passesRules };
+}
+
+export interface UseValidationsOptions<Value extends string | boolean> {
+  id?: Ref<string>;
+  /** The input element. The `aria-invalid` attribute will be set on this
+   * element. */
+  field?: Ref<HTMLElement | null>;
+  /** The value of the input element. */
+  value: Ref<Value>;
+  /** The validation rules to apply to the input element. */
+  rules: Ref<Rules<Value>>;
+  /** Value of the required attribute. */
+  required?: Ref<boolean>;
+  /** Which event to wait for before starting validation. */
+  validateOn?: ValidationEvent | Ref<ValidationEvent>;
+}
+
+interface UseValidationsReturn {
+  /** The validation error message, if any. */
+  message: Ref<string | null>;
+  /** Whether the input element is valid. */
+  valid: Ref<boolean | null>;
+  /** The event listeners to bind to the component using `v-on`. */
+  listeners: Record<string, (event: Event) => void>;
+  /** Triggers validation. */
+  startValidating: () => boolean;
+  /** Clears the validation results. */
+  clearValidations: () => void;
+}
+
+/** Registers this field with a parent form to enable form-wide validation. */
+export type ValidationStateWithOptionalId = Omit<ValidationState, 'id'> & { id?: string };
+export function useFormValidationSupport(state: ValidationStateWithOptionalId): void {
+  const formValidations = inject(VALIDATIONS, null);
+  if (formValidations) {
+    if (!state.id) {
+      throw new Error('id is required to support form validations');
+    }
+
+    formValidations.register(state as ValidationState);
+  }
+
+  onBeforeUnmount(() => {
+    if (formValidations && state.id) {
+      formValidations.unregister(state.id);
+    }
+  });
+}
+
+/**
+ * A composable that provides validation support for form controls. Please make sure to
+ * `v-bind` the returned `attrs` and `v-on` the returned `listeners` to the component.
+ *
+ * @param options - The options for the composable.
+ */
+export function useValidations<Value extends string | boolean>(
+  options: UseValidationsOptions<Value>
+): UseValidationsReturn {
+  const validateOn = computed(() => unref(options.validateOn) ?? 'blur');
+
+  const onValidationResultChange = ({ valid }: { valid: boolean }): void => {
+    if (options.field?.value) {
+      options.field.value.setAttribute('aria-invalid', valid ? 'false' : 'true');
+    }
+  };
+
+  const { message, valid, startValidating, passesRules, clearValidations } = useValidationRuleCheck(
+    {
+      value: options.value,
+      rules: options.rules,
+      required: options.required,
+      onValidationResultChange,
+    }
+  );
+
+  useFormValidationSupport({
+    id: options.id?.value,
+    valid: passesRules,
+    validate: startValidating,
+    field: options.field,
+  });
+
+  const onInput = (): void => {
+    if (validateOn.value === 'input') {
+      startValidating();
+    }
+  };
+
+  const onBlur = (): void => {
+    // NOTE(slanden): We always validate on blur, regardless of the validateOn setting.
+    startValidating();
+  };
+
+  const onChange = (): void => {
+    if (validateOn.value === 'change') {
+      startValidating();
+    }
+  };
+
+  watch(validateOn, (newValue, oldValue): void => {
+    if (['input', 'change'].includes(newValue) && newValue !== oldValue) {
+      startValidating();
+    }
+  });
+
+  const listeners = { input: onInput, blur: onBlur, change: onChange };
+  return { message, valid, listeners, startValidating, clearValidations };
+}

package/src/index.ts

@@ -1,11 +1,11 @@
-import plugin from '@/plugin';
-
-import '@/styles/main.scss';
+import plugin from '@propelinc/citrus-ui/src/plugin';
 
 export default plugin;
 
-export * as Colors from '@/styles/_colors.scss';
-export { default as Theme } from '@/colors/theme';
-export { default as Icons } from '@/theme/icons';
+export { default as Colors } from '@propelinc/citrus-ui/src/colors/colors';
+export { default as Theme } from '@propelinc/citrus-ui/src/colors/theme';
+export { default as Icons } from '@propelinc/citrus-ui/src/theme/icons';
 
-export * from '@/components/index';
+export * from '@propelinc/citrus-ui/src/types';
+export * from '@propelinc/citrus-ui/src/components';
+export * from '@propelinc/citrus-ui/src/services/directives';

package/src/plugin.ts

@@ -1,12 +1,19 @@
-import _Vue, { PluginObject } from 'vue';
+import type { App, DefineComponent, Plugin } from 'vue';
 
-import * as Components from '@/components';
+import * as Components from '@propelinc/citrus-ui/src/components';
+import { scrollIntoView, tapAnimation } from '@propelinc/citrus-ui/src/services/directives';
 
-const plugin: PluginObject<never> = {
-  install(Vue: typeof _Vue): void {
-    Object.entries(Components).forEach(([name, component]) => {
-      Vue.component(name, component);
+const plugin: Plugin = {
+  install(app: App): void {
+    Object.entries(Components).forEach(([name, component]): void => {
+      app.component(name, component as DefineComponent);
     });
+
+    // TODO: this has to be passed to the vue() plugin for Vite instead
+    app.config.compilerOptions.isCustomElement = (tag): boolean => tag.startsWith('sl-');
+
+    app.directive('scroll-into-view', scrollIntoView);
+    app.directive('tap-animation', tapAnimation);
   },
 };