@kashi-ui/elements 0.0.0-stage → 0.25.0

package/dist/combobox.js

@@ -0,0 +1,439 @@
+import { CITIES, PROVINCES, getCities, normalizePersian, toFaDigits } from "@kashi-ui/persian";
+import { HTMLBase, afterParse, define, emit, esc, fieldHTML, setMessages, syncHidden, uid } from "./base.js";
+/** متن یکدست برای جستجو: ي/ی، ك/ک، ارقام، حروف کوچک */
+export const searchText = (s) => normalizePersian(s, { digits: "latin" }).toLowerCase();
+/** بیشترین تعداد گزینهٔ رسم‌شده؛ برای فهرست‌های بلند مثل ۱۲۰۰ شهر، بقیه با تایپ پیدا می‌شوند */
+const MAX_RENDER = 300;
+const CHEVRON = '<svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 8 4 4 4-4"/></svg>';
+const CHECK = '<svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m5 10.5 3.2 3L15 7"/></svg>';
+/**
+ * جستجو و انتخاب با الگوی Combobox در WAI-ARIA: تایپ فهرست را فیلتر می‌کند، ↑↓ حرکت، Enter انتخاب،
+ * Esc بستن (و در حالت بسته، پاک کردن). جستجو «علي» و «علی» را یکی می‌داند.
+ * گزینه‌ها از فرزندان <option> (با data-description و <optgroup>) یا ویژگی options با JavaScript.
+ */
+export class KashiCombobox extends HTMLBase {
+    constructor() {
+        super(...arguments);
+        this.selected = null;
+        this.query = "";
+        this.list = null;
+        this.filtered = [];
+        this.typing = false;
+        this.isOpen = false;
+        this.active = -1;
+        this.rendered = false;
+        this.valueSet = false;
+        this.key = uid("kashi-combo");
+        /** برچسب پیش‌فرض وقتی label داده نشود */
+        this.defaultLabel = null;
+        this.defaultPlaceholder = "";
+        this.onOutside = (e) => {
+            if (!this.contains(e.target))
+                this.close();
+        };
+    }
+    connectedCallback() {
+        afterParse(() => {
+            if (!this.isConnected)
+                return;
+            if (!this.rendered) {
+                if (this.list === null)
+                    this.list = this.readOptions();
+                if (Object.prototype.hasOwnProperty.call(this, "value")) {
+                    const v = this.value;
+                    delete this.value;
+                    this.value = v ?? "";
+                }
+                else if (!this.valueSet) {
+                    const v = this.getAttribute("value");
+                    this.selected = v ? this.find(v) : null;
+                    this.query = this.selected?.label ?? "";
+                }
+            }
+            this.render();
+        });
+    }
+    disconnectedCallback() {
+        document.removeEventListener("pointerdown", this.onOutside);
+    }
+    attributeChangedCallback(name, old, next) {
+        if (!this.rendered || old === next)
+            return;
+        if (name === "value")
+            this.value = next ?? "";
+        else
+            this.render();
+    }
+    /** گزینه‌ها با JavaScript: [{ value, label, description?, group?, keywords?, disabled? }] */
+    get options() {
+        return this.list ?? [];
+    }
+    set options(list) {
+        this.list = [...list];
+        if (this.selected)
+            this.selected = this.find(this.selected.value);
+        if (this.rendered)
+            this.sync();
+    }
+    /** مقدار گزینهٔ انتخاب‌شده، یا رشتهٔ خالی */
+    get value() {
+        return this.selected?.value ?? "";
+    }
+    set value(v) {
+        this.valueSet = true;
+        this.selected = v ? this.find(v) : null;
+        this.query = this.selected?.label ?? "";
+        this.typing = false;
+        if (this.rendered)
+            this.sync();
+    }
+    /** گزینهٔ انتخاب‌شده با همهٔ اطلاعاتش */
+    get selectedOption() {
+        return this.selected;
+    }
+    focus(options) {
+        this.input?.focus(options);
+    }
+    readOptions() {
+        const out = [];
+        for (const el of [...this.querySelectorAll(":scope > option, :scope > optgroup > option")]) {
+            const group = el.parentElement?.tagName === "OPTGROUP" ? (el.parentElement.getAttribute("label") ?? undefined) : undefined;
+            out.push({
+                value: el.value,
+                label: el.textContent?.trim() ?? el.value,
+                description: el.dataset.description,
+                keywords: el.dataset.keywords?.split(/[,،]\s*/),
+                disabled: el.disabled,
+                group,
+            });
+        }
+        for (const el of [...this.querySelectorAll(":scope > option, :scope > optgroup")])
+            el.remove();
+        return out;
+    }
+    /** گزینه‌های قابل نمایش برای این جستجو؛ زیرکلاس‌ها (شهر) گزینهٔ «شهر دیگر» اضافه می‌کنند */
+    source(_query) {
+        return this.options;
+    }
+    accepts(o, query) {
+        const q = searchText(query.trim());
+        if (!q)
+            return true;
+        return [o.label, o.description ?? "", ...(o.keywords ?? [])].some((t) => searchText(t).includes(q));
+    }
+    find(value) {
+        return this.source("").find((o) => o.value === value) ?? null;
+    }
+    /** اطلاعات رویداد kashi-change */
+    detail() {
+        return { value: this.value, option: this.selected };
+    }
+    render() {
+        const id = this.key;
+        const ariaLabel = this.getAttribute("aria-label");
+        const label = this.hasAttribute("label") ? this.getAttribute("label") : ariaLabel ? null : this.defaultLabel;
+        const required = this.hasAttribute("required");
+        const disabled = this.hasAttribute("disabled");
+        const listId = `${id}-list`;
+        const control = `<div class="k-combobox"><div class="k-input"${disabled ? ' data-state="disabled"' : ""}><input id="${id}" class="k-input__control" type="text" role="combobox" aria-autocomplete="list" aria-expanded="false" aria-controls="${listId}" autocomplete="off" placeholder="${esc(this.getAttribute("placeholder") ?? this.defaultPlaceholder)}"${required ? " required" : ""}${disabled ? " disabled" : ""}${!label && ariaLabel ? ` aria-label="${esc(ariaLabel)}"` : ""}><button type="button" tabindex="-1" class="k-input__action k-combobox__toggle" aria-label="نمایش گزینه‌ها"${disabled ? " disabled" : ""}>${CHEVRON}</button></div><ul id="${listId}" role="listbox" class="k-listbox" hidden style="inset-block-start: calc(100% + 6px)"${label ? ` aria-label="${esc(label)}"` : ` aria-labelledby="${id}"`}></ul><span class="k-sr-only" aria-live="polite"></span></div>`;
+        this.querySelector(":scope > .k-field")?.remove();
+        this.insertAdjacentHTML("afterbegin", fieldHTML({ id, label, required, control }));
+        this.input = this.querySelector("input.k-input__control");
+        this.listbox = this.querySelector(".k-listbox");
+        this.live = this.querySelector(".k-combobox > .k-sr-only");
+        this.isOpen = false;
+        this.input.addEventListener("input", () => {
+            this.query = this.input.value;
+            this.typing = true;
+            this.active = -1;
+            this.open(false);
+            emit(this, "kashi-input", { query: this.query });
+        });
+        this.input.addEventListener("keydown", (e) => this.onKey(e));
+        this.input.addEventListener("click", () => !this.isOpen && this.open());
+        this.input.addEventListener("blur", (e) => {
+            if (this.contains(e.relatedTarget))
+                return;
+            this.close();
+        });
+        this.querySelector(".k-combobox__toggle").addEventListener("click", () => {
+            if (this.isOpen)
+                this.close();
+            else {
+                this.typing = false;
+                this.open();
+                this.input.focus();
+            }
+        });
+        this.listbox.addEventListener("pointerdown", (e) => e.preventDefault()); // فوکوس در فیلد بماند
+        this.listbox.addEventListener("click", (e) => {
+            const li = e.target.closest('[role="option"]');
+            if (!li || li.getAttribute("aria-disabled") === "true")
+                return;
+            this.commit(this.filtered[Number(li.dataset.i)]);
+        });
+        this.listbox.addEventListener("pointermove", (e) => {
+            const li = e.target.closest('[role="option"]');
+            if (li && li.getAttribute("aria-disabled") !== "true" && Number(li.dataset.i) !== this.active)
+                this.setActive(Number(li.dataset.i));
+        });
+        this.rendered = true;
+        this.sync();
+    }
+    /** متن فیلد، فیلد پنهان، خطا و فهرست را با وضعیت فعلی هماهنگ می‌کند */
+    sync() {
+        if (!this.typing && this.input.value !== this.query)
+            this.input.value = this.query;
+        setMessages(this.querySelector(":scope > .k-field"), this.input, this.key, this.getAttribute("error"), this.getAttribute("hint"));
+        this.syncHidden();
+        if (this.isOpen)
+            this.renderList();
+    }
+    syncHidden() {
+        syncHidden(this, this.getAttribute("name"), this.value);
+    }
+    enabled() {
+        return this.filtered.map((o, i) => (o.disabled ? -1 : i)).filter((i) => i >= 0);
+    }
+    open(reset = true, at = "selected") {
+        if (this.hasAttribute("disabled"))
+            return;
+        this.isOpen = true;
+        this.input.setAttribute("aria-expanded", "true");
+        this.listbox.hidden = false;
+        this.toggleAttribute("data-open", true);
+        this.querySelector(".k-combobox").setAttribute("data-open", "");
+        this.filter();
+        if (reset) {
+            const en = this.enabled();
+            const sel = this.filtered.findIndex((o) => o.value === this.selected?.value);
+            this.active = at === "last" ? (en.at(-1) ?? -1) : at === "first" || sel < 0 ? (en[0] ?? -1) : sel;
+        }
+        this.renderList();
+        document.addEventListener("pointerdown", this.onOutside);
+    }
+    close() {
+        if (!this.rendered)
+            return;
+        this.isOpen = false;
+        this.input.setAttribute("aria-expanded", "false");
+        this.input.removeAttribute("aria-activedescendant");
+        this.listbox.hidden = true;
+        this.querySelector(".k-combobox").removeAttribute("data-open");
+        this.live.textContent = "";
+        document.removeEventListener("pointerdown", this.onOutside);
+        // متن نیمه‌کاره به گزینهٔ انتخاب‌شده برمی‌گردد
+        if (this.typing) {
+            this.typing = false;
+            this.query = this.selected?.label ?? "";
+            this.input.value = this.query;
+        }
+    }
+    filter() {
+        const all = this.source(this.typing ? this.query : "");
+        this.filtered = this.typing ? all.filter((o) => this.accepts(o, this.query)) : all;
+    }
+    renderList() {
+        const q = this.typing ? searchText(this.query.trim()) : "";
+        const mark = (text) => {
+            const i = q ? searchText(text).indexOf(q) : -1;
+            return i < 0 ? esc(text) : `${esc(text.slice(0, i))}<mark>${esc(text.slice(i, i + q.length))}</mark>${esc(text.slice(i + q.length))}`;
+        };
+        const listId = `${this.key}-list`;
+        let last;
+        const shown = this.filtered.slice(0, MAX_RENDER);
+        const items = shown.map((o, i) => {
+            const header = o.group && o.group !== last ? `<li role="presentation" class="k-listbox__group">${esc(o.group)}</li>` : "";
+            last = o.group;
+            const on = o.value === this.selected?.value;
+            return `${header}<li id="${listId}-${i}" data-i="${i}" role="option" aria-selected="${on}"${o.disabled ? ' aria-disabled="true"' : ""}${i === this.active ? " data-active" : ""} class="k-option"><span class="k-option__body"><span>${mark(o.label)}</span>${o.description ? `<span class="k-option__desc">${esc(o.description)}</span>` : ""}</span>${on ? `<span class="k-option__check">${CHECK}</span>` : ""}</li>`;
+        });
+        if (!this.filtered.length)
+            items.push(`<li class="k-listbox__empty" role="presentation">${esc(this.getAttribute("empty-message") ?? "نتیجه‌ای پیدا نشد.")}</li>`);
+        if (this.filtered.length > MAX_RENDER)
+            items.push(`<li class="k-listbox__empty" role="presentation">${toFaDigits(this.filtered.length - MAX_RENDER)} گزینهٔ دیگر؛ برای پیدا کردن تایپ کنید.</li>`);
+        this.listbox.innerHTML = items.join("");
+        this.live.textContent = this.typing ? `${toFaDigits(this.filtered.length)} نتیجه` : "";
+        this.setActive(this.active);
+    }
+    setActive(i) {
+        this.active = i;
+        this.listbox.querySelector("[data-active]")?.removeAttribute("data-active");
+        const li = i >= 0 ? this.listbox.querySelector(`[data-i="${i}"]`) : null;
+        if (li) {
+            li.setAttribute("data-active", "");
+            li.scrollIntoView?.({ block: "nearest" });
+            this.input.setAttribute("aria-activedescendant", li.id);
+        }
+        else
+            this.input.removeAttribute("aria-activedescendant");
+    }
+    move(delta) {
+        const en = this.enabled().filter((i) => i < MAX_RENDER);
+        if (!en.length)
+            return;
+        const pos = en.indexOf(this.active);
+        this.setActive(en[(pos + delta + en.length) % en.length]);
+    }
+    onKey(e) {
+        if (e.key === "ArrowDown") {
+            e.preventDefault();
+            this.isOpen ? this.move(1) : this.open(true, e.altKey ? "selected" : "first");
+        }
+        else if (e.key === "ArrowUp") {
+            e.preventDefault();
+            this.isOpen ? this.move(-1) : this.open(true, "last");
+        }
+        else if (e.key === "Enter" && this.isOpen && this.active >= 0) {
+            e.preventDefault();
+            this.commit(this.filtered[this.active]);
+        }
+        else if (e.key === "Escape") {
+            if (this.isOpen) {
+                e.preventDefault();
+                this.close();
+            }
+            else if (this.input.value) {
+                e.preventDefault();
+                this.commit(null);
+            }
+        }
+        else if ((e.key === "Home" || e.key === "End") && this.isOpen) {
+            e.preventDefault();
+            const en = this.enabled();
+            this.setActive((e.key === "Home" ? en[0] : en.at(-1)) ?? -1);
+        }
+    }
+    commit(o) {
+        const changed = (o?.value ?? null) !== (this.selected?.value ?? null);
+        this.selected = o;
+        this.query = o?.label ?? "";
+        this.typing = false;
+        this.input.value = this.query;
+        this.close();
+        this.sync();
+        if (changed)
+            emit(this, "kashi-change", this.detail());
+    }
+}
+KashiCombobox.observedAttributes = ["label", "hint", "error", "placeholder", "required", "disabled", "name", "value", "empty-message", "aria-label"];
+/** انتخاب یکی از ۳۱ استان با جستجو؛ با نام مرکز استان هم پیدا می‌شود (مثلاً «مشهد») */
+export class KashiProvinceSelect extends KashiCombobox {
+    constructor() {
+        super(...arguments);
+        this.defaultLabel = "استان";
+        this.defaultPlaceholder = "جستجوی استان یا شهر";
+    }
+    source() {
+        const capital = this.getAttribute("show-capital") !== "false";
+        return PROVINCES.map((p) => ({ value: p.name, label: p.name, description: capital ? `مرکز: ${p.capital}` : undefined, keywords: [p.capital] }));
+    }
+    detail() {
+        return { value: this.value, province: PROVINCES.find((p) => p.name === this.value) ?? null };
+    }
+}
+KashiProvinceSelect.observedAttributes = [...KashiCombobox.observedAttributes, "show-capital"];
+const SEP = "|";
+// «علی آباد»، «علی‌آباد» و «علیآباد» یکی‌اند
+const loose = (s) => searchText(s).replace(/[\s‌]/g, "");
+/**
+ * انتخاب شهر با جستجو؛ با province فقط شهرهای همان استان، بدون آن همهٔ ۱۲۰۰+ شهر ایران با نام استان.
+ * شهری که در فهرست نیست (شهرهای تازه‌تأسیس) با همان نام تایپ‌شده پذیرفته می‌شود، مگر allow-custom="false".
+ */
+export class KashiCitySelect extends KashiCombobox {
+    constructor() {
+        super(...arguments);
+        this.defaultLabel = "شهر";
+        this.custom = null;
+    }
+    get province() {
+        return this.getAttribute("province") || null;
+    }
+    set province(p) {
+        if (p)
+            this.setAttribute("province", p);
+        else
+            this.removeAttribute("province");
+    }
+    /** نام شهر */
+    get value() {
+        return this.selected ? this.selected.value.split(SEP)[1] : "";
+    }
+    set value(city) {
+        this.valueSet = true;
+        this.custom = null;
+        const list = this.source("");
+        const p = this.province;
+        let o = city ? (list.find((x) => x.label === city && (!p || x.value.startsWith(`${p}${SEP}`))) ?? null) : null;
+        if (city && !o) {
+            this.custom = city;
+            o = { value: `custom${SEP}${city}`, label: city, description: "خارج از فهرست" };
+        }
+        this.selected = o;
+        this.query = o?.label ?? "";
+        if (this.isConnected && this.querySelector(".k-combobox"))
+            this.sync();
+    }
+    find(value) {
+        // مقدار ورودی نام شهر است؛ setter بالا آن را پیدا می‌کند
+        this.value = value;
+        return this.selected;
+    }
+    attributeChangedCallback(name, old, next) {
+        if (name !== "province")
+            return super.attributeChangedCallback(name, old, next);
+        if (old === next)
+            return;
+        if (this.selected) {
+            // شهر فقط وقتی می‌ماند که در استان تازه هم باشد
+            const city = this.value;
+            if (!next || !getCities(next).includes(city)) {
+                this.selected = null;
+                this.query = "";
+                this.custom = null;
+            }
+            else
+                this.selected = { value: `${next}${SEP}${city}`, label: city };
+        }
+        // بدون ساختن دوبارهٔ فیلد، تا فوکوس و متن کاربر از دست نرود
+        if (this.querySelector(".k-combobox")) {
+            this.input.placeholder = this.getAttribute("placeholder") ?? this.placeholderText();
+            this.input.value = this.query;
+            this.sync();
+        }
+    }
+    connectedCallback() {
+        this.defaultPlaceholder = this.placeholderText();
+        super.connectedCallback();
+    }
+    placeholderText() {
+        return this.province ? "جستجوی شهر" : "نام شهر، مثلاً کاشان";
+    }
+    source(query) {
+        const p = this.province;
+        const list = p
+            ? getCities(p).map((c) => ({ value: `${p}${SEP}${c}`, label: c }))
+            : Object.entries(CITIES).flatMap(([prov, cities]) => cities.map((c) => ({ value: `${prov}${SEP}${c}`, label: c, description: prov })));
+        if (this.custom)
+            list.unshift({ value: `custom${SEP}${this.custom}`, label: this.custom, description: "خارج از فهرست" });
+        const q = query.trim();
+        if (this.getAttribute("allow-custom") !== "false" && q && q !== this.custom && !list.some((o) => loose(o.label) === loose(q)))
+            list.push({ value: `custom${SEP}${q}`, label: q, description: "شهر دیگر؛ همین نام ثبت شود" });
+        return list;
+    }
+    accepts(o, q) {
+        return o.value.startsWith(`custom${SEP}`) || [o.label, o.description ?? ""].some((t) => loose(t).includes(loose(q)));
+    }
+    commit(o) {
+        this.custom = o?.value.startsWith(`custom${SEP}`) ? o.label : null;
+        super.commit(o);
+    }
+    detail() {
+        const [p] = this.selected ? this.selected.value.split(SEP) : [null];
+        return { value: this.value, province: p === "custom" ? null : p };
+    }
+}
+KashiCitySelect.observedAttributes = [...KashiCombobox.observedAttributes, "province", "allow-custom"];
+define("kashi-combobox", KashiCombobox, "block");
+define("kashi-province-select", KashiProvinceSelect, "block");
+define("kashi-city-select", KashiCitySelect, "block");

package/dist/controls.d.ts

@@ -0,0 +1,82 @@
+import { HTMLBase } from "./base.js";
+/**
+ * فیلد برچسب: با Enter، «,» یا «،» اضافه، با Backspace حذف آخرین، و چسباندن چند مورد با هم.
+ * با name هر برچسب یک فیلد پنهان هم‌نام در فرم است.
+ */
+export declare class KashiTagInput extends HTMLBase {
+    static observedAttributes: string[];
+    private tags;
+    private localError;
+    private rendered;
+    private valueSet;
+    private key;
+    private input;
+    /** اعتبارسنجی هر برچسب؛ پیام خطا یا undefined */
+    validate?: (tag: string) => string | undefined;
+    connectedCallback(): void;
+    attributeChangedCallback(name: string, old: string | null, next: string | null): void;
+    private parse;
+    /** برچسب‌ها به‌شکل آرایه */
+    get value(): string[];
+    set value(v: string[] | string);
+    focus(options?: FocusOptions): void;
+    private render;
+    private add;
+    private removeAt;
+    private commit;
+    private paint;
+    private paintMessages;
+}
+/** فیلد عدد با دکمه‌های − و +، ارقام فارسی، جداکنندهٔ هزارگان و کلیدهای ↑↓ و PageUp/PageDown */
+export declare class KashiNumberInput extends HTMLBase {
+    static observedAttributes: string[];
+    private current;
+    private rendered;
+    private valueSet;
+    private key;
+    private input;
+    connectedCallback(): void;
+    attributeChangedCallback(name: string, old: string | null, next: string | null): void;
+    get value(): number | null;
+    set value(v: number | null);
+    focus(options?: FocusOptions): void;
+    private num;
+    private get min();
+    private get max();
+    private clamp;
+    private show;
+    private render;
+    private bump;
+    private set;
+    private paint;
+    private paintState;
+}
+/** امتیاز ستاره‌ای روی رادیوهای بومی؛ با readonly فقط نمایش (با نیم‌ستاره برای امتیاز اعشاری) */
+export declare class KashiRating extends HTMLBase {
+    static observedAttributes: string[];
+    private current;
+    private valueSet;
+    private key;
+    connectedCallback(): void;
+    attributeChangedCallback(name: string, old: string | null, next: string | null): void;
+    get value(): number;
+    set value(v: number);
+    private render;
+}
+/** شماره‌های صفحه: ۱ … ۴ ۵ ۶ … ۲۰ */
+export declare function pageRange(page: number, total: number, siblings?: number): (number | null)[];
+/**
+ * صفحه‌بندی. با href (مثل "?page={page}") لینک می‌سازد و با رفتن به صفحهٔ دیگر صفحه عوض می‌شود؛
+ * بدون آن دکمه است و رویداد kashi-change با شمارهٔ صفحه می‌فرستد.
+ */
+export declare class KashiPagination extends HTMLBase {
+    static observedAttributes: string[];
+    connectedCallback(): void;
+    attributeChangedCallback(_n: string, old: string | null, next: string | null): void;
+    get page(): number;
+    set page(p: number);
+    get total(): number;
+    private render;
+}
+/** تبدیل متن سلول به عدد برای مرتب‌سازی: «۱٬۲۵۰٬۰۰۰ تومان» → 1250000 */
+export declare const cellNumber: (text: string) => number;