@mdui/shared 1.0.0

package/helpers/breakpoint.js

@@ -0,0 +1,102 @@
+/**
+ * 断点相关的 js 函数
+ * 这些函数直接导出到 mdui 全局对象下，供应用使用。框架内部使用时，为避免循环依赖，从 @mdui/shared 包内导入
+ */
+import { getDocument, getWindow } from 'ssr-window';
+import { $ } from '@mdui/jq/$.js';
+import '@mdui/jq/methods/innerWidth.js';
+import { isElement, isNumber } from '@mdui/jq/shared/helper.js';
+/**
+ * 获取断点对象，通过返回的对象可用于判断指定宽度、或指定元素的宽度、或当前窗口宽度与各个断点值的关系
+ *
+ * * 未传入参数时，获取的是 `window` 的宽度对应的断点对象
+ * * 若传入数值，则获取的是该数值宽度对应的断点对象
+ * * 若传入 CSS 选择器，则获取的是该选择器对应元素的宽度对应的断点对象
+ * * 若传入 HTML 元素，则获取的是该元素的宽度对应的断点对象
+ * * 若传入 JQ 对象，则获取的是该 JQ 对象中的元素的宽度对应的断点对象
+ *
+ * 返回的对象包含以下方法：
+ *
+ * * `up(breakpoint)`：判断当前宽度是否大于指定断点值
+ * * `down(breakpoint)`：判断当前宽度是否小于指定断点值
+ * * `only(breakpoint)`：判断当前宽度是否在指定断点值内
+ * * `not(breakpoint)`：判断当前宽度是否不在指定断点值内
+ * * `between(startBreakpoint, endBreakpoint)`：判断当前宽度是否在指定断点值之间
+ */
+export const breakpoint = (width) => {
+    const window = getWindow();
+    const document = getDocument();
+    const computedStyle = window.getComputedStyle(document.documentElement);
+    // 容器的宽度
+    const containerWidth = isElement(width)
+        ? $(width).innerWidth()
+        : isNumber(width)
+            ? width
+            : $(window).innerWidth();
+    // 断点对应的宽度值
+    const getBreakpointValue = (breakpoint) => {
+        const width = computedStyle
+            .getPropertyValue(`--mdui-breakpoint-${breakpoint}`)
+            .toLowerCase();
+        return parseFloat(width);
+    };
+    // 获取比指定断点更大的一个断点
+    const getNextBreakpoint = (breakpoint) => {
+        switch (breakpoint) {
+            case 'xs':
+                return 'sm';
+            case 'sm':
+                return 'md';
+            case 'md':
+                return 'lg';
+            case 'lg':
+                return 'xl';
+            case 'xl':
+                return 'xxl';
+        }
+    };
+    return {
+        /**
+         * 当前宽度是否大于指定断点值
+         * @param breakpoint
+         */
+        up(breakpoint) {
+            return containerWidth >= getBreakpointValue(breakpoint);
+        },
+        /**
+         * 当前宽度是否小于指定断点值
+         * @param breakpoint
+         */
+        down(breakpoint) {
+            return containerWidth < getBreakpointValue(breakpoint);
+        },
+        /**
+         * 当前宽度是否在指定断点值内
+         * @param breakpoint
+         */
+        only(breakpoint) {
+            if (breakpoint === 'xxl') {
+                return this.up(breakpoint);
+            }
+            else {
+                return this.up(breakpoint) && this.down(getNextBreakpoint(breakpoint));
+            }
+        },
+        /**
+         * 当前宽度是否不在指定断点值内
+         * @param breakpoint
+         */
+        not(breakpoint) {
+            return !this.only(breakpoint);
+        },
+        /**
+         * 当前宽度是否在指定断点值之间
+         * @param startBreakpoint
+         * @param endBreakpoint
+         * @returns
+         */
+        between(startBreakpoint, endBreakpoint) {
+            return this.up(startBreakpoint) && this.down(endBreakpoint);
+        },
+    };
+};

package/helpers/decorator.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 在原生的 HTML 中，布尔属性只要添加了属性名，不论属性值设置成什么，属性值都是 true
+ * 但这里设置了 attr="false" 时，要把属性设置为 false
+ *
+ * 原因是：
+ * 在 vue3 中，通过 :attr="value" 设置属性时，vue 会优先从 DOM 属性中寻找是否存在 attr 属性名，
+ * 若存在，则设置对应的 DOM 属性，否则设置对应的 attribute 属性
+ * 但在 vue 的服务端渲染（ssr）时，不存在 DOM 对象，所以会把 attribute 属性设置成 attr="true" 或 attr="false"
+ * 所以在 attribute 属性 attr="false" 时，需要把属性值转换为布尔值 false
+ *
+ * 这段代码不能封装成函数，否则生成 custom-elements.json 会识别不了
+ * 这段注释仅在这里写一次，其他地方不再重复
+ *
+ * @see https://v3-migration.vuejs.org/zh/breaking-changes/attribute-coercion.html
+ */
+export declare const booleanConverter: (value: string | null) => boolean;

package/helpers/decorator.js

@@ -0,0 +1,18 @@
+/**
+ * 在原生的 HTML 中，布尔属性只要添加了属性名，不论属性值设置成什么，属性值都是 true
+ * 但这里设置了 attr="false" 时，要把属性设置为 false
+ *
+ * 原因是：
+ * 在 vue3 中，通过 :attr="value" 设置属性时，vue 会优先从 DOM 属性中寻找是否存在 attr 属性名，
+ * 若存在，则设置对应的 DOM 属性，否则设置对应的 attribute 属性
+ * 但在 vue 的服务端渲染（ssr）时，不存在 DOM 对象，所以会把 attribute 属性设置成 attr="true" 或 attr="false"
+ * 所以在 attribute 属性 attr="false" 时，需要把属性值转换为布尔值 false
+ *
+ * 这段代码不能封装成函数，否则生成 custom-elements.json 会识别不了
+ * 这段注释仅在这里写一次，其他地方不再重复
+ *
+ * @see https://v3-migration.vuejs.org/zh/breaking-changes/attribute-coercion.html
+ */
+export const booleanConverter = (value) => {
+    return value !== null && value !== 'false';
+};

package/helpers/delay.d.ts

@@ -0,0 +1,4 @@
+/**
+ * 延迟多少毫秒执行
+ */
+export declare const delay: (duration?: number) => Promise<unknown>;

package/helpers/delay.js

@@ -0,0 +1,6 @@
+/**
+ * 延迟多少毫秒执行
+ */
+export const delay = (duration = 0) => {
+    return new Promise((resolve) => setTimeout(resolve, duration));
+};

package/helpers/event.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 触发自定义事件
+ * @param element
+ * @param type
+ * @param options 通常只用到 cancelable 和 detail；bubbles、composed 统一不用
+ */
+export declare const emit: (element: HTMLElement, type: string, options?: CustomEventInit) => CustomEvent;

package/helpers/event.js

@@ -0,0 +1,17 @@
+/**
+ * 触发自定义事件
+ * @param element
+ * @param type
+ * @param options 通常只用到 cancelable 和 detail；bubbles、composed 统一不用
+ */
+export const emit = (element, type, options) => {
+    const event = new CustomEvent(type, {
+        bubbles: true,
+        cancelable: false,
+        composed: true,
+        detail: {},
+        ...options,
+    });
+    element.dispatchEvent(event);
+    return event;
+};

package/helpers/modal.d.ts

@@ -0,0 +1,12 @@
+export declare class Modal {
+    private readonly element;
+    private tabDirection;
+    constructor(element: HTMLElement);
+    activate(): void;
+    deactivate(): void;
+    private isActive;
+    private checkFocus;
+    private handleFocusIn;
+    private handleKeyDown;
+    private handleKeyUp;
+}

package/helpers/modal.js

@@ -0,0 +1,52 @@
+/** https://github.com/shoelace-style/shoelace/blob/next/src/internal/modal.ts */
+import { getTabbableBoundary } from './tabbable.js';
+let activeModals = [];
+export class Modal {
+    constructor(element) {
+        this.tabDirection = 'forward';
+        this.element = element;
+        this.handleFocusIn = this.handleFocusIn.bind(this);
+        this.handleKeyDown = this.handleKeyDown.bind(this);
+        this.handleKeyUp = this.handleKeyUp.bind(this);
+    }
+    activate() {
+        activeModals.push(this.element);
+        document.addEventListener('focusin', this.handleFocusIn);
+        document.addEventListener('keydown', this.handleKeyDown);
+        document.addEventListener('keyup', this.handleKeyUp);
+    }
+    deactivate() {
+        activeModals = activeModals.filter((modal) => modal !== this.element);
+        document.removeEventListener('focusin', this.handleFocusIn);
+        document.removeEventListener('keydown', this.handleKeyDown);
+        document.removeEventListener('keyup', this.handleKeyUp);
+    }
+    isActive() {
+        // The "active" modal is always the most recent one shown
+        return activeModals[activeModals.length - 1] === this.element;
+    }
+    checkFocus() {
+        if (this.isActive()) {
+            if (!this.element.matches(':focus-within')) {
+                const { start, end } = getTabbableBoundary(this.element);
+                const target = this.tabDirection === 'forward' ? start : end;
+                if (typeof (target === null || target === void 0 ? void 0 : target.focus) === 'function') {
+                    target.focus({ preventScroll: true });
+                }
+            }
+        }
+    }
+    handleFocusIn() {
+        this.checkFocus();
+    }
+    handleKeyDown(event) {
+        if (event.key === 'Tab' && event.shiftKey) {
+            this.tabDirection = 'backward';
+        }
+        // Ensure focus remains trapped after they key is pressed
+        requestAnimationFrame(() => this.checkFocus());
+    }
+    handleKeyUp() {
+        this.tabDirection = 'forward';
+    }
+}

package/helpers/motion.d.ts

@@ -0,0 +1,13 @@
+import '@mdui/jq/methods/css.js';
+/**
+ * 获取由 CSS 变量定义的缓动曲线值
+ * @param element 在指定元素上获取值；若需要获取全局值，则传入 document.body
+ * @param name 缓动曲线名称
+ */
+export declare const getEasing: (element: HTMLElement, name: 'linear' | 'standard' | 'standard-accelerate' | 'standard-decelerate' | 'emphasized' | 'emphasized-accelerate' | 'emphasized-decelerate') => string;
+/**
+ * 获取由 CSS 变量定义的动画持续时间
+ * @param element 在指定元素上获取值；若需要获取全局值，则传入 document.body
+ * @param name 持续时间名称
+ */
+export declare const getDuration: (element: HTMLElement, name: 'short1' | 'short2' | 'short3' | 'short4' | 'medium1' | 'medium2' | 'medium3' | 'medium4' | 'long1' | 'long2' | 'long3' | 'long4' | 'extra-long1' | 'extra-long2' | 'extra-long3' | 'extra-long4') => number;

package/helpers/motion.js

@@ -0,0 +1,20 @@
+import { $ } from '@mdui/jq/$.js';
+import '@mdui/jq/methods/css.js';
+/**
+ * 获取由 CSS 变量定义的缓动曲线值
+ * @param element 在指定元素上获取值；若需要获取全局值，则传入 document.body
+ * @param name 缓动曲线名称
+ */
+export const getEasing = (element, name) => {
+    const cssVariableName = `--mdui-motion-easing-${name}`;
+    return $(element).css(cssVariableName).trim();
+};
+/**
+ * 获取由 CSS 变量定义的动画持续时间
+ * @param element 在指定元素上获取值；若需要获取全局值，则传入 document.body
+ * @param name 持续时间名称
+ */
+export const getDuration = (element, name) => {
+    const cssVariableName = `--mdui-motion-duration-${name}`;
+    return parseFloat($(element).css(cssVariableName).trim());
+};

package/helpers/observeResize.d.ts

@@ -0,0 +1,16 @@
+import '@mdui/jq/methods/each.js';
+import type { JQ } from '@mdui/jq/shared/core.js';
+export interface ObserveResize {
+    /**
+     * 取消监听
+     */
+    unobserve: () => void;
+}
+type Callback = (this: ObserveResize, entry: ResizeObserverEntry, observer: ObserveResize) => void;
+/**
+ * 监听元素的尺寸变化
+ * @param target 监听该元素的尺寸变化
+ * @param callback 尺寸变化时执行的回调函数，`this` 指向监听的元素
+ */
+export declare const observeResize: (target: string | HTMLElement | JQ<HTMLElement>, callback: Callback) => ObserveResize;
+export {};

package/helpers/observeResize.js

@@ -0,0 +1,57 @@
+import { $ } from '@mdui/jq/$.js';
+import '@mdui/jq/methods/each.js';
+import { uniqueId } from './uniqueId.js';
+let weakMap;
+// ResizeObserver 实例，所有 resizeObserver 函数内部共用一个 ResizeObserver 实例
+let observer;
+/**
+ * 监听元素的尺寸变化
+ * @param target 监听该元素的尺寸变化
+ * @param callback 尺寸变化时执行的回调函数，`this` 指向监听的元素
+ */
+export const observeResize = (target, callback) => {
+    const $target = $(target);
+    const key = uniqueId();
+    // 取消监听函数
+    const result = {
+        unobserve: () => {
+            $target.each((_, target) => {
+                var _a;
+                const coArr = (_a = weakMap.get(target)) !== null && _a !== void 0 ? _a : [];
+                const index = coArr.findIndex((co) => co.key === key);
+                if (index !== -1) {
+                    coArr.splice(index, 1);
+                }
+                if (!coArr.length) {
+                    observer.unobserve(target);
+                    weakMap.delete(target);
+                }
+                else {
+                    weakMap.set(target, coArr);
+                }
+            });
+        },
+    };
+    // 初始化
+    if (!weakMap) {
+        weakMap = new WeakMap();
+        observer = new ResizeObserver((entries) => {
+            entries.forEach((entry) => {
+                const target = entry.target;
+                const coArr = weakMap.get(target);
+                coArr.forEach((co) => {
+                    co.callback.call(result, entry, result);
+                });
+            });
+        });
+    }
+    // 添加监听
+    $target.each((_, target) => {
+        var _a;
+        observer.observe(target);
+        const coArr = (_a = weakMap.get(target)) !== null && _a !== void 0 ? _a : [];
+        coArr.push({ callback, key });
+        weakMap.set(target, coArr);
+    });
+    return result;
+};

package/helpers/queue.d.ts

@@ -0,0 +1,18 @@
+type Func = () => void;
+/**
+ * 根据队列名，获取队列中所有函数
+ * @param name 队列名
+ */
+export declare function queue(name: string): Func[];
+/**
+ * 写入队列
+ * @param name 队列名
+ * @param func 函数
+ */
+export declare function queue(name: string, func: Func): void;
+/**
+ * 从队列中移除第一个函数，并执行该函数
+ * @param name 队列名
+ */
+export declare function dequeue(name: string): void;
+export {};

package/helpers/queue.js

@@ -0,0 +1,25 @@
+import { isUndefined } from '@mdui/jq/shared/helper.js';
+const container = {};
+export function queue(name, func) {
+    if (isUndefined(container[name])) {
+        container[name] = [];
+    }
+    if (isUndefined(func)) {
+        return container[name];
+    }
+    container[name].push(func);
+}
+/**
+ * 从队列中移除第一个函数，并执行该函数
+ * @param name 队列名
+ */
+export function dequeue(name) {
+    if (isUndefined(container[name])) {
+        return;
+    }
+    if (!container[name].length) {
+        return;
+    }
+    const func = container[name].shift();
+    func();
+}

package/helpers/scroll.d.ts

@@ -0,0 +1,14 @@
+import '@mdui/jq/methods/addClass.js';
+import '@mdui/jq/methods/removeClass.js';
+/**
+ * 锁定指定元素，禁止滚动。对同一个元素多次调用此方法，只会锁定一次
+ * @param element
+ * @param target 锁定该元素的滚动状态，默认为 body
+ */
+export declare const lockScreen: (element: HTMLElement, target?: HTMLElement) => void;
+/**
+ * 解除指定元素的滚动状态锁定。
+ * @param element
+ * @param target 锁定该元素的滚动状态，默认为 body
+ */
+export declare const unlockScreen: (element: HTMLElement, target?: HTMLElement) => void;

package/helpers/scroll.js

@@ -0,0 +1,28 @@
+import { getDocument } from 'ssr-window';
+import { $ } from '@mdui/jq/$.js';
+import '@mdui/jq/methods/addClass.js';
+import '@mdui/jq/methods/removeClass.js';
+const locks = new Set();
+const CSS_CLASS = 'mdui-lock-screen';
+/**
+ * 锁定指定元素，禁止滚动。对同一个元素多次调用此方法，只会锁定一次
+ * @param element
+ * @param target 锁定该元素的滚动状态，默认为 body
+ */
+export const lockScreen = (element, target) => {
+    const document = getDocument();
+    locks.add(element);
+    $(target || document.body).addClass(CSS_CLASS);
+};
+/**
+ * 解除指定元素的滚动状态锁定。
+ * @param element
+ * @param target 锁定该元素的滚动状态，默认为 body
+ */
+export const unlockScreen = (element, target) => {
+    const document = getDocument();
+    locks.delete(element);
+    if (locks.size === 0) {
+        $(target || document.body).removeClass(CSS_CLASS);
+    }
+};

package/helpers/slot.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 获取一个 slot 中的所有内容
+ * @param slot
+ */
+export declare const getInnerHtmlFromSlot: (slot: HTMLSlotElement) => string;
+/**
+ * 获取一个 slot 中的所有文本内容
+ * @param slot
+ */
+export declare const getTextContentFromSlot: (slot: HTMLSlotElement) => string;

package/helpers/slot.js

@@ -0,0 +1,31 @@
+/**
+ * 获取一个 slot 中的所有内容
+ * @param slot
+ */
+export const getInnerHtmlFromSlot = (slot) => {
+    const nodes = slot.assignedNodes({ flatten: true });
+    let html = '';
+    [...nodes].forEach((node) => {
+        if (node.nodeType === Node.ELEMENT_NODE) {
+            html += node.outerHTML;
+        }
+        if (node.nodeType === Node.TEXT_NODE) {
+            html += node.textContent;
+        }
+    });
+    return html;
+};
+/**
+ * 获取一个 slot 中的所有文本内容
+ * @param slot
+ */
+export const getTextContentFromSlot = (slot) => {
+    const nodes = slot.assignedNodes({ flatten: true });
+    let text = '';
+    [...nodes].forEach((node) => {
+        if (node.nodeType === Node.TEXT_NODE) {
+            text += node.textContent;
+        }
+    });
+    return text;
+};

package/helpers/tabbable.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns the first and last bounding elements that are tabbable. This is more performant than checking every single
+ * element because it short-circuits after finding the first and last ones.
+ */
+export declare function getTabbableBoundary(root: HTMLElement | ShadowRoot): {
+    start: HTMLElement | null;
+    end: HTMLElement | null;
+};

package/helpers/tabbable.js

@@ -0,0 +1,82 @@
+import { getWindow } from 'ssr-window';
+/** https://github.com/shoelace-style/shoelace/blob/next/src/internal/tabbable.ts */
+/** Determines if the specified element is tabbable using heuristics inspired by https://github.com/focus-trap/tabbable */
+function isTabbable(el) {
+    const window = getWindow();
+    const tag = el.tagName.toLowerCase();
+    // Elements with a -1 tab index are not tabbable
+    if (el.getAttribute('tabindex') === '-1') {
+        return false;
+    }
+    // Elements with a disabled attribute are not tabbable
+    if (el.hasAttribute('disabled')) {
+        return false;
+    }
+    // Elements with aria-disabled are not tabbable
+    if (el.hasAttribute('aria-disabled') &&
+        el.getAttribute('aria-disabled') !== 'false') {
+        return false;
+    }
+    // Radios without a checked attribute are not tabbable
+    if (tag === 'input' &&
+        el.getAttribute('type') === 'radio' &&
+        !el.hasAttribute('checked')) {
+        return false;
+    }
+    // Elements that are hidden have no offsetParent and are not tabbable
+    if (el.offsetParent === null) {
+        return false;
+    }
+    // Elements without visibility are not tabbable
+    if (window.getComputedStyle(el).visibility === 'hidden') {
+        return false;
+    }
+    // Audio and video elements with the controls attribute are tabbable
+    if ((tag === 'audio' || tag === 'video') && el.hasAttribute('controls')) {
+        return true;
+    }
+    // Elements with a tabindex other than -1 are tabbable
+    if (el.hasAttribute('tabindex')) {
+        return true;
+    }
+    // Elements with a contenteditable attribute are tabbable
+    if (el.hasAttribute('contenteditable') &&
+        el.getAttribute('contenteditable') !== 'false') {
+        return true;
+    }
+    // At this point, the following elements are considered tabbable
+    return [
+        'button',
+        'input',
+        'select',
+        'textarea',
+        'a',
+        'audio',
+        'video',
+        'summary',
+    ].includes(tag);
+}
+/**
+ * Returns the first and last bounding elements that are tabbable. This is more performant than checking every single
+ * element because it short-circuits after finding the first and last ones.
+ */
+export function getTabbableBoundary(root) {
+    var _a, _b;
+    const allElements = [];
+    function walk(el) {
+        if (el instanceof HTMLElement) {
+            allElements.push(el);
+            if (el.shadowRoot !== null && el.shadowRoot.mode === 'open') {
+                walk(el.shadowRoot);
+            }
+        }
+        const children = el.children;
+        [...children].forEach((e) => walk(e));
+    }
+    // Collect all elements including the root
+    walk(root);
+    // Find the first and last tabbable elements
+    const start = (_a = allElements.find((el) => isTabbable(el))) !== null && _a !== void 0 ? _a : null;
+    const end = (_b = allElements.reverse().find((el) => isTabbable(el))) !== null && _b !== void 0 ? _b : null;
+    return { start, end };
+}

package/helpers/template.d.ts

@@ -0,0 +1,2 @@
+import type { TemplateResult } from 'lit';
+export declare const nothingTemplate: TemplateResult;

package/helpers/template.js

@@ -0,0 +1,2 @@
+import { html, nothing } from 'lit';
+export const nothingTemplate = html `${nothing}`;

package/helpers/throttle.d.ts

@@ -0,0 +1,14 @@
+type ThrottledFunc<T extends (...args: any) => any> = (...args: Parameters<T>) => ReturnType<T>;
+/**
+ * 创建一个节流函数
+ * @param func 要执行的函数
+ * @param wait 最多多少毫秒执行一次
+ * @example
+```js
+window.addEventListener('scroll', throttle(() => {
+  console.log('这个函数最多 100ms 执行一次');
+}, 100));
+```
+ */
+export declare const throttle: <T extends (...args: any) => any>(func: T, wait?: number) => ThrottledFunc<T>;
+export {};

package/helpers/throttle.js

@@ -0,0 +1,28 @@
+import { getWindow } from 'ssr-window';
+/**
+ * 创建一个节流函数
+ * @param func 要执行的函数
+ * @param wait 最多多少毫秒执行一次
+ * @example
+```js
+window.addEventListener('scroll', throttle(() => {
+  console.log('这个函数最多 100ms 执行一次');
+}, 100));
+```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const throttle = (func, wait = 0) => {
+    const window = getWindow();
+    let timer;
+    let result;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return function (...args) {
+        if (timer === undefined) {
+            timer = window.setTimeout(() => {
+                result = func.apply(this, args);
+                timer = undefined;
+            }, wait);
+        }
+        return result;
+    };
+};

package/helpers/uniqueId.d.ts

@@ -0,0 +1,4 @@
+/**
+ * 返回一个唯一ID
+ */
+export declare const uniqueId: () => number;

package/helpers/uniqueId.js

@@ -0,0 +1,7 @@
+let id = 0;
+/**
+ * 返回一个唯一ID
+ */
+export const uniqueId = () => {
+    return ++id;
+};

package/icons/arrow-right.d.ts

@@ -0,0 +1,11 @@
+import { LitElement } from 'lit';
+import type { TemplateResult, CSSResultGroup } from 'lit';
+export declare class IconArrowRight extends LitElement {
+    static styles: CSSResultGroup;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'mdui-icon-arrow-right': IconArrowRight;
+    }
+}