sard 1.0.0 → 1.0.2

package/utils/color.js

@@ -0,0 +1,341 @@
+import { clamp, round } from "./number.js";
+//#region packages/sard/utils/color.ts
+const DEFAULT_COLOR = {
+	h: 210,
+	s: 100,
+	l: 50,
+	a: 1
+};
+const normalizeHue = (value) => {
+	if (value === 360) return value;
+	const normalized = value % 360;
+	return normalized < 0 ? normalized + 360 : normalized;
+};
+const formatAlpha = (value) => {
+	return round(clamp(value, 0, 1), 2).toString().replace(/\.0+$/, "");
+};
+const formatNumber = (value, precision = 0) => {
+	return round(value, precision);
+};
+const toHex = (value) => {
+	return clamp(Math.round(value), 0, 255).toString(16).padStart(2, "0");
+};
+const splitAlpha = (value) => {
+	const [base, alpha] = value.split("/").map((item) => item.trim());
+	return {
+		base,
+		alpha
+	};
+};
+const parseUnitValue = (value, { scale = 1, percentBase } = {}) => {
+	if (!value) return NaN;
+	if (value.endsWith("%")) {
+		const numberValue = Number.parseFloat(value.slice(0, -1));
+		if (Number.isNaN(numberValue)) return NaN;
+		return percentBase === void 0 ? numberValue / 100 : numberValue / 100 * percentBase;
+	}
+	const numberValue = Number.parseFloat(value);
+	return Number.isNaN(numberValue) ? NaN : numberValue * scale;
+};
+const parseHue = (value) => {
+	if (value.endsWith("turn")) return Number.parseFloat(value) * 360;
+	if (value.endsWith("rad")) return Number.parseFloat(value) * 180 / Math.PI;
+	if (value.endsWith("grad")) return Number.parseFloat(value) * .9;
+	return Number.parseFloat(value);
+};
+function normalizeHsla(color) {
+	return {
+		h: normalizeHue(color?.h ?? DEFAULT_COLOR.h),
+		s: clamp(color?.s ?? DEFAULT_COLOR.s, 0, 100),
+		l: clamp(color?.l ?? DEFAULT_COLOR.l, 0, 100),
+		a: clamp(color?.a ?? DEFAULT_COLOR.a, 0, 1)
+	};
+}
+function normalizeHsva(color) {
+	return {
+		h: normalizeHue(color?.h ?? DEFAULT_COLOR.h),
+		s: clamp(color?.s ?? DEFAULT_COLOR.s, 0, 100),
+		v: clamp(color?.v ?? 100, 0, 100),
+		a: clamp(color?.a ?? DEFAULT_COLOR.a, 0, 1)
+	};
+}
+function hslToRgb(color) {
+	const h = normalizeHue(color.h) / 360;
+	const s = clamp(color.s, 0, 100) / 100;
+	const l = clamp(color.l, 0, 100) / 100;
+	if (s === 0) {
+		const gray = Math.round(l * 255);
+		return {
+			r: gray,
+			g: gray,
+			b: gray,
+			a: color.a
+		};
+	}
+	const hueToRgb = (p, q, t) => {
+		let current = t;
+		if (current < 0) current += 1;
+		if (current > 1) current -= 1;
+		if (current < 1 / 6) return p + (q - p) * 6 * current;
+		if (current < 1 / 2) return q;
+		if (current < 2 / 3) return p + (q - p) * (2 / 3 - current) * 6;
+		return p;
+	};
+	const q = l < .5 ? l * (1 + s) : l + s - l * s;
+	const p = 2 * l - q;
+	return {
+		r: Math.round(hueToRgb(p, q, h + 1 / 3) * 255),
+		g: Math.round(hueToRgb(p, q, h) * 255),
+		b: Math.round(hueToRgb(p, q, h - 1 / 3) * 255),
+		a: color.a
+	};
+}
+function rgbToHsl(red, green, blue, alpha = 1) {
+	const r = clamp(red, 0, 255) / 255;
+	const g = clamp(green, 0, 255) / 255;
+	const b = clamp(blue, 0, 255) / 255;
+	const max = Math.max(r, g, b);
+	const min = Math.min(r, g, b);
+	const delta = max - min;
+	const lightness = (max + min) / 2;
+	let hue = 0;
+	let saturation = 0;
+	if (delta !== 0) {
+		saturation = lightness > .5 ? delta / (2 - max - min) : delta / (max + min);
+		switch (max) {
+			case r:
+				hue = (g - b) / delta + (g < b ? 6 : 0);
+				break;
+			case g:
+				hue = (b - r) / delta + 2;
+				break;
+			default:
+				hue = (r - g) / delta + 4;
+				break;
+		}
+		hue *= 60;
+	}
+	return normalizeHsla({
+		h: hue,
+		s: saturation * 100,
+		l: lightness * 100,
+		a: alpha
+	});
+}
+function hslToHsv(color) {
+	const lightness = clamp(color.l, 0, 100) / 100;
+	const value = lightness + clamp(color.s, 0, 100) / 100 * Math.min(lightness, 1 - lightness);
+	const nextSaturation = value === 0 ? 0 : 2 * (1 - lightness / value);
+	return normalizeHsva({
+		h: color.h,
+		s: nextSaturation * 100,
+		v: value * 100,
+		a: color.a
+	});
+}
+function hsvToHsl(color) {
+	const value = clamp(color.v, 0, 100) / 100;
+	const lightness = value * (1 - clamp(color.s, 0, 100) / 100 / 2);
+	const nextSaturation = lightness === 0 || lightness === 1 ? 0 : (value - lightness) / Math.min(lightness, 1 - lightness);
+	return normalizeHsla({
+		h: color.h,
+		s: nextSaturation * 100,
+		l: lightness * 100,
+		a: color.a
+	});
+}
+function hslToHwb(color) {
+	const rgb = hslToRgb(color);
+	const r = rgb.r / 255;
+	const g = rgb.g / 255;
+	const b = rgb.b / 255;
+	return {
+		h: normalizeHue(color.h),
+		w: round(Math.min(r, g, b) * 100),
+		bk: round((1 - Math.max(r, g, b)) * 100),
+		a: color.a
+	};
+}
+function hwbToHsl(hue, white, black, alpha = 1) {
+	let w = clamp(white, 0, 100) / 100;
+	let bk = clamp(black, 0, 100) / 100;
+	if (w + bk > 1) {
+		const total = w + bk;
+		w /= total;
+		bk /= total;
+	}
+	const pure = hslToRgb({
+		h: hue,
+		s: 100,
+		l: 50,
+		a: alpha
+	});
+	const ratio = 1 - w - bk;
+	return rgbToHsl((pure.r / 255 * ratio + w) * 255, (pure.g / 255 * ratio + w) * 255, (pure.b / 255 * ratio + w) * 255, alpha);
+}
+function parseHex(value) {
+	const raw = value.trim().replace("#", "");
+	if (![
+		3,
+		4,
+		6,
+		8
+	].includes(raw.length) || !/^[\da-f]+$/i.test(raw)) return null;
+	const expanded = raw.length <= 4 ? raw.split("").map((item) => item + item).join("") : raw;
+	const alpha = expanded.length === 8 ? Number.parseInt(expanded.slice(6, 8), 16) / 255 : 1;
+	return rgbToHsl(Number.parseInt(expanded.slice(0, 2), 16), Number.parseInt(expanded.slice(2, 4), 16), Number.parseInt(expanded.slice(4, 6), 16), alpha);
+}
+function parseRgb(value) {
+	const matched = value.match(/^rgba?\((.*)\)$/i);
+	if (!matched) return null;
+	const body = matched[1].trim();
+	let channels;
+	let alphaRaw = "";
+	if (body.includes(",")) {
+		const parts = body.split(",").map((item) => item.trim());
+		if (parts.length < 3 || parts.length > 4) return null;
+		channels = parts.slice(0, 3);
+		alphaRaw = parts[3] ?? "";
+	} else {
+		const split = splitAlpha(body);
+		channels = split.base.split(/\s+/).filter(Boolean);
+		alphaRaw = split.alpha ?? "";
+	}
+	if (channels.length !== 3) return null;
+	const [r, g, b] = channels.map((item) => parseUnitValue(item, { percentBase: 255 }));
+	const alpha = alphaRaw ? parseUnitValue(alphaRaw) : 1;
+	if ([
+		r,
+		g,
+		b,
+		alpha
+	].some((item) => Number.isNaN(item))) return null;
+	return rgbToHsl(r, g, b, alpha);
+}
+function parseHsl(value) {
+	const matched = value.match(/^hsla?\((.*)\)$/i);
+	if (!matched) return null;
+	const body = matched[1].trim();
+	let channels;
+	let alphaRaw = "";
+	if (body.includes(",")) {
+		const parts = body.split(",").map((item) => item.trim());
+		if (parts.length < 3 || parts.length > 4) return null;
+		channels = parts.slice(0, 3);
+		alphaRaw = parts[3] ?? "";
+	} else {
+		const split = splitAlpha(body);
+		channels = split.base.split(/\s+/).filter(Boolean);
+		alphaRaw = split.alpha ?? "";
+	}
+	if (channels.length !== 3) return null;
+	const hue = parseHue(channels[0]);
+	const saturation = parseUnitValue(channels[1], { percentBase: 100 });
+	const lightness = parseUnitValue(channels[2], { percentBase: 100 });
+	const alpha = alphaRaw ? parseUnitValue(alphaRaw) : 1;
+	if ([
+		hue,
+		saturation,
+		lightness,
+		alpha
+	].some((item) => Number.isNaN(item))) return null;
+	return normalizeHsla({
+		h: hue,
+		s: saturation,
+		l: lightness,
+		a: alpha
+	});
+}
+function parseHwb(value) {
+	const matched = value.match(/^hwb\((.*)\)$/i);
+	if (!matched) return null;
+	const split = splitAlpha(matched[1].trim());
+	const channels = split.base.split(/\s+/).filter(Boolean);
+	if (channels.length !== 3) return null;
+	const hue = parseHue(channels[0]);
+	const white = parseUnitValue(channels[1], { percentBase: 100 });
+	const black = parseUnitValue(channels[2], { percentBase: 100 });
+	const alpha = split.alpha ? parseUnitValue(split.alpha) : 1;
+	if ([
+		hue,
+		white,
+		black,
+		alpha
+	].some((item) => Number.isNaN(item))) return null;
+	return hwbToHsl(hue, white, black, alpha);
+}
+function parseColor(value) {
+	if (!value) return null;
+	const input = value.trim();
+	if (!input) return null;
+	if (input.startsWith("#")) {
+		const color = parseHex(input);
+		return color ? {
+			color,
+			format: "hex"
+		} : null;
+	}
+	if (/^rgba?\(/i.test(input)) {
+		const color = parseRgb(input);
+		return color ? {
+			color,
+			format: "rgb"
+		} : null;
+	}
+	if (/^hsla?\(/i.test(input)) {
+		const color = parseHsl(input);
+		return color ? {
+			color,
+			format: "hsl"
+		} : null;
+	}
+	if (/^hwb\(/i.test(input)) {
+		const color = parseHwb(input);
+		return color ? {
+			color,
+			format: "hwb"
+		} : null;
+	}
+	return null;
+}
+function formatColor(colorValue, format, showAlpha = false) {
+	const color = normalizeHsla(colorValue);
+	const effective = showAlpha ? color : {
+		...color,
+		a: 1
+	};
+	const rgb = hslToRgb(effective);
+	switch (format) {
+		case "rgb": return effective.a < 1 && showAlpha ? `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, ${formatAlpha(effective.a)})` : `rgb(${rgb.r}, ${rgb.g}, ${rgb.b})`;
+		case "hsl": return effective.a < 1 && showAlpha ? `hsla(${formatNumber(effective.h)}, ${formatNumber(effective.s)}%, ${formatNumber(effective.l)}%, ${formatAlpha(effective.a)})` : `hsl(${formatNumber(effective.h)}, ${formatNumber(effective.s)}%, ${formatNumber(effective.l)}%)`;
+		case "hwb": {
+			const hwb = hslToHwb(effective);
+			return effective.a < 1 && showAlpha ? `hwb(${formatNumber(hwb.h)} ${formatNumber(hwb.w)}% ${formatNumber(hwb.bk)}% / ${formatAlpha(hwb.a)})` : `hwb(${formatNumber(hwb.h)} ${formatNumber(hwb.w)}% ${formatNumber(hwb.bk)}%)`;
+		}
+		default: return `#${toHex(rgb.r)}${toHex(rgb.g)}${toHex(rgb.b)}${showAlpha ? toHex(effective.a * 255) : ""}`.toUpperCase();
+	}
+}
+function getPreviewColor(colorValue, showAlpha = false) {
+	return formatColor(colorValue, "rgb", showAlpha);
+}
+const defaultColorPickerValue = "#1989FA";
+const defaultColorPickerPresets = [
+	"#FFFFFF",
+	"#EF4444",
+	"#F97316",
+	"#F59E0B",
+	"#EAB308",
+	"#84CC16",
+	"#2ECC71",
+	"#10B981",
+	"#06B6D4",
+	"#0EA5E9",
+	"#1989FA",
+	"#6366F1",
+	"#8B5CF6",
+	"#A855F7",
+	"#EC4899",
+	"#111827"
+];
+//#endregion
+export { defaultColorPickerPresets, defaultColorPickerValue, formatColor, getPreviewColor, hslToHsv, hslToHwb, hslToRgb, hsvToHsl, hwbToHsl, normalizeHsla, normalizeHsva, parseColor, rgbToHsl };

package/utils/common.d.ts

@@ -0,0 +1,3 @@
+export interface AnyObject {
+    [key: string]: any;
+}

package/utils/component.d.ts

@@ -0,0 +1,21 @@
+import { type Component, type ComponentOptions, type DefineSetupFnComponent, type ExtractPropTypes, type ExtractPublicPropTypes, type RenderFunction } from 'vue';
+import type { ComponentProps } from '../type-helpers';
+type Data = Record<string, unknown>;
+type SatisfyEmitsOptions<T> = {} & T;
+type SatisfySlotsType<T> = {} & T;
+export declare function defineSetupFnComponent<P, E, S, Expose>(setup: (props: ExtractPropTypes<P>, ctx: {
+    attrs: Data;
+    slots: S;
+    emit: E;
+    expose: (exposed?: Expose) => void;
+}) => RenderFunction | Promise<RenderFunction>, options?: Pick<ComponentOptions, 'name' | 'inheritAttrs'> & {
+    props?: P;
+    emits?: E;
+    slots?: S;
+    expose?: Expose;
+}): DefineSetupFnComponent<ExtractPublicPropTypes<P>, SatisfyEmitsOptions<E>, SatisfySlotsType<S>>;
+export type EnhancedComponent<T extends Component> = T & {
+    setPropsDefaults: (defaults: ComponentProps<T>) => void;
+};
+export declare function enhanceComponent<T extends Component>(component: T): EnhancedComponent<T>;
+export {};

package/utils/component.js

@@ -0,0 +1,31 @@
+import { isPlainObject } from "./is.js";
+import { defineComponent } from "vue";
+//#region packages/sard/utils/component.ts
+function defineSetupFnComponent(setup, options) {
+	return defineComponent(setup, options);
+}
+function enhanceComponent(component) {
+	let props = component?.props;
+	props = Array.isArray(props) ? props.reduce((obj, key) => (obj[key] = {}, obj), {}) : props;
+	return Object.assign(component, { setPropsDefaults(defaults) {
+		if (!props) return;
+		for (const [key, value] of Object.entries(defaults)) {
+			if (!props.hasOwnProperty(key)) continue;
+			const prop = props[key];
+			if (isPlainObject(prop)) {
+				props[key] = {
+					...prop,
+					default: value
+				};
+				continue;
+			}
+			props[key] = {
+				type: prop,
+				default: value
+			};
+		}
+		component.props = props;
+	} });
+}
+//#endregion
+export { defineSetupFnComponent, enhanceComponent };

package/utils/createImperativeComponent.d.ts

@@ -0,0 +1,10 @@
+import { type Component } from 'vue';
+interface ImperativeConfig<Expose> {
+    onShow?: (expose: Expose) => void;
+    onHide?: (expose: Expose) => void;
+}
+export declare function createImperativeComponent<Options, Expose>(component: Component, defaultOptions?: Options, config?: ImperativeConfig<Expose>): {
+    show: (options?: Options) => void;
+    hide: () => void;
+};
+export {};

package/utils/createImperativeComponent.js

@@ -0,0 +1,54 @@
+import { createApp, createVNode, defineComponent, ref } from "vue";
+//#region packages/sard/utils/createImperativeComponent.ts
+function createAgent(component, defaultOptions, config) {
+	return defineComponent({ setup(_, { expose }) {
+		const compRef = ref();
+		const innerProps = ref({});
+		const show = (options) => {
+			innerProps.value = {
+				...defaultOptions,
+				...options,
+				visible: true
+			};
+			config?.onShow?.(compRef.value);
+		};
+		const hide = () => {
+			innerProps.value = {
+				...innerProps.value,
+				visible: false
+			};
+			config?.onHide?.(compRef.value);
+		};
+		expose({
+			show,
+			hide
+		});
+		return () => {
+			return createVNode(component, {
+				ref: compRef,
+				...innerProps.value,
+				"onUpdate:visible": (value) => {
+					innerProps.value.visible = value;
+					innerProps.value["onUpdate:visible"]?.(value);
+				}
+			});
+		};
+	} });
+}
+function createImperativeComponent(component, defaultOptions, config) {
+	const container = document.createElement("div");
+	document.body.appendChild(container);
+	const instance = createApp(createAgent(component, defaultOptions, config)).mount(container);
+	function show(options) {
+		instance.show(options);
+	}
+	function hide() {
+		instance.hide();
+	}
+	return {
+		show,
+		hide
+	};
+}
+//#endregion
+export { createImperativeComponent };

package/utils/date.d.ts

@@ -0,0 +1,119 @@
+/**
+ * 判断是否为闰年。
+ */
+export declare function isLeapYear(year: number): boolean;
+/**
+ * 获取某月的天数，月份从0开始。
+ */
+export declare function getDaysInMonth(year: number, month: number): number;
+/**
+ * 获取当前日期是一年中的第几天。
+ */
+export declare function getDayOfYear(date: Date): number;
+/**
+ * 获取指定月份第一天是星期几，月份从0开始。
+ */
+export declare function getFirstDayWeekday(year: number, month: number): number;
+/**
+ * 获取从基准日期（如1970-01-01）到指定日期的总天数。
+ */
+export declare function getDaysSinceUnixEpoch(date: Date): number;
+/**
+ * 把日期转换为年月日数值，例如：2025年7月1号 -> 20250601。
+ */
+export declare function toDateNumber(date: Date): number;
+/**
+ * 把日期转换为年月日字符串，，例如：2025年7月1号 -> 2025-7-1。
+ */
+export declare function toDateString(date: Date): string;
+/**
+ * 把日期转换为年月数值，例如：2025年7月1号 -> 20250600。
+ */
+export declare function toMonthNumber(date: Date): number;
+/**
+ * 计算当前月份1号前面需要显示的上个月末尾的天数。
+ */
+export declare function getDaysBeforeFirstDay(year: number, month: number, weekStartsOn?: number): number;
+/**
+ * 获取当前月份最后一天之后需要显示的下个月开始的天数。
+ */
+export declare function getDaysAfterLastDay(year: number, month: number, weekStartsOn?: number): number;
+/**
+ * 获取当前月份1号之前需要显示的上个月末尾的日期。
+ */
+export declare function getPrevMonthTailDays(year: number, month: number, weekStartsOn?: number): Date[];
+/**
+ * 获取当前月份最后一天之后需要显示的下个月开始的日期。
+ */
+export declare function getNextMonthHeadDays(year: number, month: number, weekStartsOn?: number): Date[];
+/**
+ * 根据传入的占位符返回格式化后的日期。
+ */
+export declare function formatDate(date: Date, format?: string): string;
+/**
+ * 解析日期的字符串表示形式，并返回 Date 实例对象。
+ */
+export declare function parseDate(value: string, format?: string): Date;
+export declare function toDate(date: Date | string, valueFormat?: string): Date;
+export declare function minmaxDate(date: Date, minDate: Date, maxDate: Date): Date;
+export declare function getPrevMonthDate(date: Date): Date;
+export declare function getNextMonthDate(date: Date): Date;
+/****************************************************************
+ * 农历
+ ****************************************************************/
+export declare const lunarInfo: number[];
+export declare const springFestivals: number[][];
+export declare const baseLunarYear = 1900;
+/**
+ * 获取农历某年闰月的月份，月份从1开始（0表示无闰月）。
+ */
+export declare function getLunarLeapMonth(year: number): number;
+/**
+ * 获取农历某年闰月的天数。
+ */
+export declare function getLunarLeapMonthDays(year: number): number;
+/**
+ * 获取农历某年的总天数。
+ */
+export declare function getLunarYearDays(year: number): number;
+/**
+ * 获取农历某年某月的天数，月份从1开始。
+ */
+export declare function getLunarMonthDays(year: number, month: number): number;
+/**
+ * 公历转农历，月份从1开始（返回的闰月为负数）。
+ */
+export declare function solarToLunar(year: number, month: number, day: number): {
+    year: number;
+    month: number;
+    day: number;
+};
+/**
+ * 农历转公历（闰月需传递负数）。
+ */
+export declare function lunarToSolar(year: number, month: number, day: number): {
+    year: number;
+    month: number;
+    day: number;
+};
+export declare const lunarYearNames: string[];
+/**
+ * 将阿拉伯数字的年份转为汉字数字年份
+ */
+export declare function getLunarYearName(year: number): string;
+export declare const lunarMonthNames: string[];
+/**
+ * 获取农历月份名称，月份从1开始，例如：正月，十月，腊月。
+ */
+export declare function getLunarMonthName(month: number, isLeapMonth?: boolean): string;
+export declare const lunarDayNames: string[];
+/**
+ * 获取农历日期名称，例如：初一，十二，廿一。
+ */
+export declare function getLunarDayName(day: number): string;
+export declare const heavenlyStems: string[];
+export declare const earthlyBranches: string[];
+/**
+ * 获取农历时辰名称，例如：子初、子正、午初，午正。
+ */
+export declare function getLunarHourName(hour: number): string;