vUtils

Utility for vue 3.

Installation

CDN

this package published as vUtils module in umd.

<script src="https://unpkg.com/@termehui/vutils"></script>

NPM

npm i @termehui/vutils

Helpers

isEmptySlot

check if slot not passed or empty.

import { isEmptySlot } from "@termehui/vutils";
isEmptySlot($slots.header);

Composition Apis

Media

create reactive media query ref.

import { useMedia } from "@termehui/vutils";
const isMobile = useMedia("(max-width: 767px)");

Timer

create a reactive timer from milliseconds.

import { ref } from "vue";
import { useTimer } from "@termehui/vutils";
const amount = ref(60000);
const { startTimer, stopTimer, timer, timerAlive } = useTimer();

function start() {
  startTimer(amount.value);
}
function stop() {
  stopTimer();
}

Shortcut

Register keyboard shortcut handler in component. you must enter KeyboardEvent.Key as key.

import { useShortcut } from "@termehui/vutils";
const { addShortcut } = useShortcut();
addShortcut({
  key: "Enter",
  callback: callbackA,
  prevent: true,
  stop: true,
});
addShortcut({
  key: ["Escape", "-"],
  callback: callbackB,
  prevent: true,
  stop: true,
});

Lister

Help to parse and generate list related requests (paginate, filters, etc).

Note: you can pass unique key to store parameters (limit, sort, order) in localStorage.

import {onMounted} from "vue;
import { useLister } from "@termehui/vutils";
const { toggleFilterArr, onApply, filter, filterValue, filterExists, parseHash } = useLister(options, "admin-users");
const username = filter<string>("username");
const groups = filterValue<string[]>("groups");
const containsAdminGroup = filterExists("groups", "admin");

function toggleGroup(group: string) {
  toggleFilterArr("groups", group);
}

onApply((params, hash) => {
  makeCrudRequest(params); // get data from server
  setQueryString(hash); // update url
});

onMounted(() => parseHash(queryString)); // parse current data from url

Constructor Options

All options are optional and lister use default value if option not passed or invalid value passed.

Option	Type	Default	Description
triggers	Trigger[] or "all"	["page", "limit", "sort", "order"]	auto apply on field change
stores	Store[]	[]	stored items in local storage
limits	number[]	[]	valid limit list. if empty array passed all value allowed!
sorts	string[]	[]	valid sort list. if empty array passed all value allowed!
page	number	1	init page
limit	number	25	init limit
sort	string	_id	init sort
order	"asc" or "desc"	asc	init order
search	string	""	init search phrase
filters	Record<string, any>	{}	init filters list

Trigger can be "page" | "limit" | "sort" | "order" | "search" | "filters".

Store can be "limit" | "sort" | "order".

Note: if field not listed in trigger list, you must apply field changes manually!

Note: you can apply staged change using apply() method. Apply method apply all staged changes by default but you can list items must applied as parameter (e.g. apply(["page", "order"])).

Note: reset() method follow apply() pattern.

Usage

Method/Attribute	Type	Description
page	ref<number>	reactive page field
limit	ref<number>	reactive limit field
sort	ref<string>	reactive sort field
order	ref<OrderType>	reactive order field. accept 'asc' and 'desc' only. this field automatically change on sort value change
search	ref<string>	reactive search field
clearSearch	() => void	clear search field and fire apply(['search'])
removeFilter	(key: string) => void	remove filter
toggleFilter	(key: string, v: unknown) => void	toggle filter item (remove item if undefined passed)
toggleFilterArr	(key: string, v: unknown) => void	toggle array filter item
filter	<T = unknown>(key: string) => WritableComputedRef<T>	reactive ref for filter item
filterValue	<T = any>(k: string) => void	get a computed ref for filter item
filterExists	(k: string, v: any) => ComputedRef<boolean>	get a computed ref for filter item exists
clearFilters	() => void	clear filters and fire apply(["filters"])
apply	(items?: Trigger[] or "all") => void	apply staged changes
reset	(items?: Trigger[] pr "all") => void	discard staged (un-applied) changes
parseJson	(raw: any) => void	parse json response
parseHash	(hashed: string) => void	parse parameters from Base64 encoded string
onApply	(callback: Callback) => Callback	register a callback to call after request parameter changes
params	ComputedRef<{page,limit,sort,order,search,filters}>	request parameters
response	ComputedRef<Object>	all response data
hash	ComputedRef<string>	Base64 encoded params (can use as url query)
records	ComputedRef<any[]>	response data field as array
isEmpty	ComputedRef<boolean>	check if response has no records
total	ComputedRef<number>	response total field
from	ComputedRef<number>	response from field
to	ComputedRef<number>	response to field
pages	ComputedRef<number>	response pages field

Event Hub

create event hub.

import { useEvent } from "@termehui/vutils";

const eHub = useEvent();
eHub.onPass<number>("increment", (v) => console.log(`${v + 1}`));
eHub.onPass(["greet", "welcome"], (v) => console.log(`greeting ${v}`));
hub.onSuccess((m, v) => console.log(`${v} received from ${m} method!`)); // called if no receiver func registered for event

eHub.onFail("greet", (v) => console.error(`who are you`));
hub.onError((m, err) =>
  console.error(`${err} error received from ${m} method!`)
); // called if no error handler registered for event

Auto Importer

You can use this plugin to auto register components to app.

import { createApp } from "vue";
import { AutoComponent } from "@termehui/vutils";

const app = createApp(Layout);
app.use(
  AutoComponent([
    {
      files: import.meta.glob("./components/icons/*.vue", { eager: true }), // vite function to get files list
      prefix: "I",
    }, // register IAdd, IEdit, IDelete, ... icons component
  ])
);
app.mount();