@kashi-ui/elements 0.0.0-stage → 0.25.0

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# @kashi-ui/elements
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+وب کامپوننت‌های [کاشی](https://kashi.sepantapouya.com)، دیزاین‌سیستم فارسی و راست‌به‌چپ؛ برای HTML ساده، وردپرس، Vue، Svelte، Angular و هر فریم‌ورک دیگری. بدون وابستگی به React و بدون Shadow DOM، تا تم و CSS شما مستقیم اعمال شود.
+
+```html
+<html lang="fa" dir="rtl">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@kashi-ui/css/dist/kashi.css">
+<script type="module" src="https://cdn.jsdelivr.net/npm/@kashi-ui/elements/dist/cdn/kashi-elements.js"></script>
+
+<form action="/checkout" method="post">
+  <kashi-national-id name="national_id" required></kashi-national-id>
+  <kashi-mobile name="mobile"></kashi-mobile>
+  <kashi-date-picker label="تاریخ تحویل" name="delivery" holidays></kashi-date-picker>
+  <button class="k-btn k-btn--primary">ثبت سفارش</button>
+</form>
+```
+
+یا با npm:
+
+```bash
+npm i @kashi-ui/elements @kashi-ui/css
+```
+
+```js
+import "@kashi-ui/css";
+import "@kashi-ui/elements";
+```
+
+## عنصرها
+
+- **فیلدهای فارسی:** `kashi-national-id`، `kashi-legal-id`، `kashi-mobile`، `kashi-landline`، `kashi-card-number`، `kashi-iban`، `kashi-postal-code`، `kashi-price`
+- **فیلدهای دیگر:** `kashi-time-input`، `kashi-plate-input`، `kashi-persian-textarea`، `kashi-keyboard-fix`، `kashi-password-strength`، `kashi-inline-edit`
+- **انتخاب:** `kashi-date-picker`، `kashi-calendar`، `kashi-date-range-picker`، `kashi-month-picker`، `kashi-otp`، `kashi-combobox`، `kashi-multi-select`، `kashi-province-select`، `kashi-city-select`، `kashi-tag-input`، `kashi-chip-group`، `kashi-number-input`، `kashi-slider`، `kashi-rating`، `kashi-color-picker`، `kashi-file-upload`
+- **نشانی و نقشه:** `kashi-address-form`، `kashi-iran-map`
+- **داده و نمودار:** `kashi-data-table`، `kashi-pagination`، `kashi-bar-chart`، `kashi-line-chart`، `kashi-pie-chart`، `kashi-bar-list`، `kashi-proportion-bar`، `kashi-sparkline`، `kashi-activity-heatmap`
+- **نمایش:** `kashi-money`، `kashi-date`، `kashi-relative-time`، `kashi-countdown`
+- **تعاملی:** `kashi-dialog`، `kashi-tabs`، `kashi-tooltip`، `kashi-dropdown-menu`، `kashi-popover`، `kashi-context-menu`، `kashi-command-palette`، `kashi-toaster` (و تابع `toast()`)، `kashi-copy-button`
+- **چیدمان:** `kashi-carousel`، `kashi-tree-view`، `kashi-tour`، `kashi-splitter`، `kashi-side-nav`
+
+فایل CDN فقط بخش‌هایی را دانلود می‌کند که تگشان در صفحه هست.
+
+هر فیلد با `name` مقدار خام را با ارقام انگلیسی در فرم ارسال می‌کند، مقدار نامعتبر جلوی ارسال فرم را می‌گیرد و با هر تغییر رویداد `kashi-change` می‌فرستد.
+
+راهنمای کامل، نمونه‌های زنده و تنظیم Vue و Angular: [kashi.sepantapouya.com/docs/web-components](https://kashi.sepantapouya.com/docs/web-components/)
+
+MIT

package/dist/base.d.ts

@@ -0,0 +1,47 @@
+/** در Node.js (رندر سمت سرور) HTMLElement وجود ندارد؛ import کردن پکیج نباید خطا بدهد */
+export declare const HTMLBase: typeof HTMLElement;
+/** ثبت عنصر، فقط در مرورگر و فقط یک بار (اگر پکیج دو بار بارگذاری شود خطا نمی‌دهد) */
+export declare function define(tag: string, ctor: CustomElementConstructor, display?: "block" | "inline" | "contents"): void;
+/**
+ * فرزندان عنصر را پس از خوانده شدن کامل HTML در اختیار cb می‌گذارد.
+ * اگر اسکریپت بدون type="module" در <head> باشد، عنصر پیش از فرزندانش به صفحه وصل می‌شود.
+ */
+export declare function afterParse(cb: () => void): void;
+/** شناسهٔ یکتا برای اتصال برچسب، راهنما و خطا */
+export declare const uid: (prefix: string) => string;
+/** متن امن برای قرار دادن در HTML */
+export declare const esc: (value: unknown) => string;
+/** ویژگی بولی: حضورش یعنی true، مگر «false» */
+export declare const bool: (el: Element, name: string, fallback?: boolean) => boolean;
+/** رویداد سفارشی که بالا می‌رود و از مرز عناصر هم رد می‌شود */
+export declare function emit<T>(el: Element, type: string, detail: T): void;
+export declare const svg: (body: string, strokeWidth?: number, mirror?: boolean) => string;
+export declare const ICONS: {
+    close: string;
+    info: string;
+    success: string;
+    warning: string;
+    error: string;
+    copy: string;
+    check: string;
+    calendar: string;
+    prev: string;
+    next: string;
+};
+export interface FieldOptions {
+    id: string;
+    label?: string | null;
+    required?: boolean;
+    optional?: string | null;
+    /** کادر کنترل، مثل <div class="k-input">…</div> */
+    control: string;
+}
+/** قالب مشترک برچسب + کنترل؛ ردیف راهنما و خطا را setMessages می‌سازد */
+export declare function fieldHTML({ id, label, required, optional, control }: FieldOptions): string;
+/**
+ * خطا و راهنمای زیر فیلد را به‌روز می‌کند و aria-invalid و aria-describedby کنترل را با آن‌ها همگام نگه می‌دارد.
+ * extra شناسه‌های دیگری است که کنترل را توصیف می‌کنند، مثل نام بانک.
+ */
+export declare function setMessages(field: Element, control: HTMLElement, id: string, error: string | null, hint: string | null, extra?: string | null): void;
+/** فیلد پنهان برای ارسال مقدار خام در فرم HTML معمولی */
+export declare function syncHidden(host: Element, name: string | null, value: string): void;

package/dist/base.js

@@ -0,0 +1,148 @@
+// پایهٔ مشترک وب کامپوننت‌ها: بدون Shadow DOM، تا کلاس‌های k-* از @kashi-ui/css و تم کاربر مستقیم اعمال شوند.
+/** در Node.js (رندر سمت سرور) HTMLElement وجود ندارد؛ import کردن پکیج نباید خطا بدهد */
+export const HTMLBase = typeof HTMLElement === "undefined" ? class {
+} : HTMLElement;
+const BLOCK_TAGS = [];
+const CONTENTS_TAGS = [];
+let style = null;
+/** ثبت عنصر، فقط در مرورگر و فقط یک بار (اگر پکیج دو بار بارگذاری شود خطا نمی‌دهد) */
+export function define(tag, ctor, display = "inline") {
+    if (typeof customElements === "undefined" || customElements.get(tag))
+        return;
+    if (display === "block")
+        BLOCK_TAGS.push(tag);
+    if (display === "contents")
+        CONTENTS_TAGS.push(tag);
+    upgradeProperties(ctor);
+    customElements.define(tag, ctor);
+    if (typeof document === "undefined")
+        return;
+    if (!style) {
+        style = document.createElement("style");
+        style.dataset.kashiElements = "";
+        document.head.prepend(style);
+    }
+    // در Cascade Layer و با :where تا CSS خود کاربر همیشه برنده باشد
+    const rules = [
+        BLOCK_TAGS.length && `:where(${BLOCK_TAGS.join(",")}) { display: block; }`,
+        CONTENTS_TAGS.length && `:where(${CONTENTS_TAGS.join(",")}) { display: contents; }`,
+    ].filter(Boolean);
+    style.textContent = `@layer kashi.elements { ${rules.join(" ")} }`;
+}
+/**
+ * ویژگی‌هایی که پیش از ثبت عنصر با JavaScript گذاشته شده‌اند (مثلاً Vue، یا element.data پیش از بارگذاری تنبل)
+ * روی خود نمونه می‌نشینند و setter کلاس را می‌پوشانند؛ پیش از اولین اتصال، از نمونه برداشته و دوباره از setter گذاشته می‌شوند.
+ */
+function upgradeProperties(ctor) {
+    const setters = new Set();
+    for (let p = ctor.prototype; p && p !== HTMLBase.prototype; p = Object.getPrototypeOf(p)) {
+        for (const [k, d] of Object.entries(Object.getOwnPropertyDescriptors(p)))
+            if (d.set)
+                setters.add(k);
+    }
+    const original = ctor.prototype.connectedCallback;
+    ctor.prototype.connectedCallback = function () {
+        for (const k of setters) {
+            if (!Object.prototype.hasOwnProperty.call(this, k))
+                continue;
+            const v = this[k];
+            delete this[k];
+            this[k] = v;
+        }
+        original?.call(this);
+    };
+}
+/**
+ * فرزندان عنصر را پس از خوانده شدن کامل HTML در اختیار cb می‌گذارد.
+ * اگر اسکریپت بدون type="module" در <head> باشد، عنصر پیش از فرزندانش به صفحه وصل می‌شود.
+ */
+export function afterParse(cb) {
+    if (typeof document !== "undefined" && document.readyState === "loading")
+        document.addEventListener("DOMContentLoaded", cb, { once: true });
+    else
+        cb();
+}
+let counter = 0;
+/** شناسهٔ یکتا برای اتصال برچسب، راهنما و خطا */
+export const uid = (prefix) => `${prefix}-${(++counter).toString(36)}`;
+const ENTITIES = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
+/** متن امن برای قرار دادن در HTML */
+export const esc = (value) => String(value ?? "").replace(/[&<>"']/g, (c) => ENTITIES[c]);
+/** ویژگی بولی: حضورش یعنی true، مگر «false» */
+export const bool = (el, name, fallback = false) => {
+    const v = el.getAttribute(name);
+    return v === null ? fallback : v !== "false";
+};
+/** رویداد سفارشی که بالا می‌رود و از مرز عناصر هم رد می‌شود */
+export function emit(el, type, detail) {
+    el.dispatchEvent(new CustomEvent(type, { detail, bubbles: true, composed: true }));
+}
+export const svg = (body, strokeWidth = 1.7, mirror = false) => `<svg${mirror ? ' data-k-mirror=""' : ""} viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="${strokeWidth}" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${body}</svg>`;
+export const ICONS = {
+    close: svg('<path d="m5 5 10 10M15 5 5 15"/>'),
+    info: svg('<circle cx="10" cy="10" r="7.5"/><path d="M10 13.5V9.5M10 6.5h.01"/>'),
+    success: svg('<circle cx="10" cy="10" r="7.5"/><path d="m6.75 10 2.25 2.25 4.25-4.5"/>'),
+    warning: svg('<path d="M8.6 3.4 2.4 14a1.6 1.6 0 0 0 1.4 2.4h12.4a1.6 1.6 0 0 0 1.4-2.4L11.4 3.4a1.6 1.6 0 0 0-2.8 0Z"/><path d="M10 7.5v3.25M10 13.5h.01"/>'),
+    error: svg('<circle cx="10" cy="10" r="7.5"/><path d="M10 6.5v4M10 13.5h.01"/>'),
+    copy: svg('<rect x="7" y="7" width="10" height="10" rx="2"/><path d="M13 7V5a2 2 0 0 0-2-2H5a2 2 0 0 0-2 2v6a2 2 0 0 0 2 2h2"/>'),
+    check: svg('<path d="m5 10.5 3.2 3L15 7"/>', 2),
+    calendar: svg('<rect x="3" y="4.5" width="14" height="12.5" rx="2"/><path d="M3 8.5h14M7 3v3M13 3v3"/>'),
+    prev: svg('<path d="m12 5-5 5 5 5"/>', 1.7, true),
+    next: svg('<path d="m8 5 5 5-5 5"/>', 1.7, true),
+};
+/** قالب مشترک برچسب + کنترل؛ ردیف راهنما و خطا را setMessages می‌سازد */
+export function fieldHTML({ id, label, required, optional, control }) {
+    const labelRow = label
+        ? `<div class="k-field__label-row"><label class="k-label" for="${id}">${esc(label)}${required ? '<span class="k-label__required" aria-hidden="true">*</span>' : ""}${optional ? `<span class="k-label__optional">${esc(optional)}</span>` : ""}</label></div>`
+        : "";
+    return `<div class="k-field">${labelRow}${control}</div>`;
+}
+/**
+ * خطا و راهنمای زیر فیلد را به‌روز می‌کند و aria-invalid و aria-describedby کنترل را با آن‌ها همگام نگه می‌دارد.
+ * extra شناسه‌های دیگری است که کنترل را توصیف می‌کنند، مثل نام بانک.
+ */
+export function setMessages(field, control, id, error, hint, extra) {
+    field.querySelector(":scope > .k-field__hint-row")?.remove();
+    if (error)
+        field.setAttribute("data-invalid", "");
+    else
+        field.removeAttribute("data-invalid");
+    if (error || hint) {
+        const row = document.createElement("div");
+        row.className = "k-field__hint-row";
+        row.innerHTML = `<div class="k-field__hints">${error ? `<p class="k-hint k-hint--error" id="${id}-error">${esc(error)}</p>` : ""}${hint ? `<p class="k-hint" id="${id}-hint">${esc(hint)}</p>` : ""}</div>`;
+        field.append(row);
+    }
+    const by = [extra, error ? `${id}-error` : null, hint ? `${id}-hint` : null].filter(Boolean).join(" ");
+    if (by)
+        control.setAttribute("aria-describedby", by);
+    else
+        control.removeAttribute("aria-describedby");
+    if (error)
+        control.setAttribute("aria-invalid", "true");
+    else
+        control.removeAttribute("aria-invalid");
+    const box = control.closest(".k-input, .k-select, .k-otp");
+    if (box?.classList.contains("k-input")) {
+        if (error)
+            box.setAttribute("data-state", "invalid");
+        else if (box.getAttribute("data-state") === "invalid")
+            box.removeAttribute("data-state");
+    }
+}
+/** فیلد پنهان برای ارسال مقدار خام در فرم HTML معمولی */
+export function syncHidden(host, name, value) {
+    let hidden = host.querySelector(":scope > input[type=hidden][data-kashi-value]");
+    if (!name) {
+        hidden?.remove();
+        return;
+    }
+    if (!hidden) {
+        hidden = document.createElement("input");
+        hidden.type = "hidden";
+        hidden.dataset.kashiValue = "";
+        host.append(hidden);
+    }
+    hidden.name = name;
+    hidden.value = value;
+}

package/dist/calendar.d.ts

@@ -0,0 +1,86 @@
+import { HTMLBase } from "./base.js";
+/**
+ * تقویم شمسی با الگوی grid در WAI-ARIA: پیمایش با فلش‌ها (در RTL فلش چپ یعنی روز بعد)،
+ * PageUp/PageDown برای ماه و با Shift برای سال، Home/End برای ابتدا و انتهای هفته.
+ */
+export declare class KashiCalendar extends HTMLBase {
+    static observedAttributes: string[];
+    /** غیرفعال کردن روزهای خاص، مثلاً (d) => d.getDay() === 5 */
+    isDateDisabled?: (date: Date) => boolean;
+    /** حالت بازه: روزهای بین start و end برجسته می‌شوند؛ با start بدون end، hover پیش‌نمایش می‌دهد */
+    private rangeValue;
+    private hover;
+    get range(): {
+        start: Date | null;
+        end: Date | null;
+    } | null;
+    set range(r: {
+        start: Date | null;
+        end: Date | null;
+    } | null);
+    /** نام تعطیلی هر روز؛ اگر ویژگی holidays گذاشته شود، تعطیلات ثابت ایران و جمعه‌ها */
+    holidayOf?: (date: Date) => string | null | false | undefined;
+    private selected;
+    private valueSet;
+    private focused;
+    private refocus;
+    private rendered;
+    private key;
+    connectedCallback(): void;
+    attributeChangedCallback(name: string, old: string | null, next: string | null): void;
+    /** تاریخ انتخاب‌شده به شکل YYYY-MM-DD میلادی */
+    get value(): string;
+    set value(v: string);
+    get date(): Date | null;
+    set date(d: Date | null);
+    /** فوکوس روی روز انتخاب‌شده یا امروز */
+    focus(): void;
+    private get min();
+    private get max();
+    private clamp;
+    private disabled;
+    private holiday;
+    private go;
+    private pick;
+    private onClick;
+    private onSelect;
+    private onKey;
+    /** برجسته کردن روزهای بازه، بدون ساختن دوبارهٔ جدول تا فوکوس سر جایش بماند */
+    private paintRange;
+    private render;
+}
+/**
+ * انتخاب تاریخ شمسی: تایپ مستقیم (۱۴۰۳/۰۵/۱۲) یا انتخاب از تقویم.
+ * با name، تاریخ میلادی به شکل YYYY-MM-DD در فرم ارسال می‌شود.
+ */
+export declare class KashiDatePicker extends HTMLBase {
+    static observedAttributes: string[];
+    isDateDisabled?: (date: Date) => boolean;
+    private selected;
+    private valueSet;
+    private invalid;
+    private rendered;
+    private key;
+    private input;
+    private toggle;
+    private pop;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, old: string | null, next: string | null): void;
+    get value(): string;
+    set value(v: string);
+    get date(): Date | null;
+    set date(d: Date | null);
+    focus(options?: FocusOptions): void;
+    private get digits();
+    private fmt;
+    private render;
+    private paint;
+    private commitText;
+    private commit;
+    /** باز کردن تقویم */
+    open(): void;
+    /** بستن تقویم؛ فوکوس به دکمهٔ تقویم برمی‌گردد */
+    close(returnFocus?: boolean): void;
+    private onOutside;
+}