text-input-guard 0.1.3 → 0.1.5

package/dist/types/text-input-guard.d.ts

@@ -156,6 +156,30 @@ type GuardContext = {
      * - IME変換中かどうか
      */
     composing: boolean;
+    /**
+     * - 直前の入力操作種別（insertText / insertFromPaste / insertCompositionText 等）
+     */
+    inputType: string | null;
+    /**
+     * - 挿入前の全文字列（置換範囲は除去済み）
+     */
+    beforeText: string;
+    /**
+     * - 挿入位置/置換開始位置（selectionStart）
+     */
+    replaceStart: number;
+    /**
+     * - 置換終了位置（selectionEnd）
+     */
+    replaceEnd: number;
+    /**
+     * - 挿入された文字列
+     */
+    insertedText: string;
+    /**
+     * - 挿入後の全文字列（後で代入する）
+     */
+    afterText: string;
     /**
      * - エラーを登録する関数
      */
@@ -232,35 +256,539 @@ type AttachOptions = {
     separateValue?: SeparateValueOptions;
 };
 /**
- * selection（カーソル/選択範囲）の退避情報
+ * revert要求（入力を巻き戻す指示）
+ */
+type RevertRequest = {
+    /**
+     * - ルール名や理由（例: "digits.int_overflow"）
+     */
+    reason: string;
+    /**
+     * - デバッグ用の詳細
+     */
+    detail?: any;
+};
+
+/**
+ * numeric ルールのオプション
+ * @typedef {Object} NumericRuleOptions
+ * @property {boolean} [allowFullWidth=true] - 全角数字/記号を許可して半角へ正規化する
+ * @property {boolean} [allowMinus=false] - マイナス記号を許可する（先頭のみ）
+ * @property {boolean} [allowDecimal=false] - 小数点を許可する（1つだけ）
+ * @property {boolean} [allowEmpty=true] - 空文字を許可するか
  */
-type SelectionState = {
+/**
+ * 数値入力向けルールを生成する
+ * - normalize.char: 全角→半角、記号統一、不要文字の除去
+ * - normalize.structure: 「-は先頭のみ」「.は1つだけ」など構造を整える
+ * - fix: 確定時（blur）に「-」「.」「-.」や末尾の「.」を空/削除にする
+ *
+ * @param {NumericRuleOptions} [options]
+ * @returns {import("../text-input-guard.js").Rule}
+ */
+declare function numeric(options?: NumericRuleOptions): Rule;
+declare namespace numeric {
+    /**
+     * datasetから numeric ルールを生成する
+     * - data-tig-rules-numeric が無ければ null
+     * - オプションは data-tig-rules-numeric-xxx から読む
+     *
+     * 対応する data 属性（dataset 名）
+     * - data-tig-rules-numeric                       -> dataset.tigRulesNumeric
+     * - data-tig-rules-numeric-allow-full-width      -> dataset.tigRulesNumericAllowFullWidth
+     * - data-tig-rules-numeric-allow-minus           -> dataset.tigRulesNumericAllowMinus
+     * - data-tig-rules-numeric-allow-decimal         -> dataset.tigRulesNumericAllowDecimal
+     * - data-tig-rules-numeric-allow-empty           -> dataset.tigRulesNumericAllowEmpty
+     *
+     * @param {DOMStringMap} dataset
+     * @param {HTMLInputElement|HTMLTextAreaElement} _el
+     * @returns {import("../text-input-guard.js").Rule|null}
+     */
+    function fromDataset(dataset: DOMStringMap, _el: HTMLInputElement | HTMLTextAreaElement): Rule | null;
+}
+/**
+ * numeric ルールのオプション
+ */
+type NumericRuleOptions = {
     /**
-     * - selectionStart
+     * - 全角数字/記号を許可して半角へ正規化する
      */
-    start: number | null;
+    allowFullWidth?: boolean;
     /**
-     * - selectionEnd
+     * - マイナス記号を許可する（先頭のみ）
      */
-    end: number | null;
+    allowMinus?: boolean;
     /**
-     * - selectionDirection
+     * - 小数点を許可する（1つだけ）
      */
-    direction: "forward" | "backward" | "none" | null;
+    allowDecimal?: boolean;
+    /**
+     * - 空文字を許可するか
+     */
+    allowEmpty?: boolean;
 };
+
 /**
- * revert要求（入力を巻き戻す指示）
+ * digits ルールを生成する
+ * @param {DigitsRuleOptions} [options]
+ * @returns {import("../text-input-guard.js").Rule}
  */
-type RevertRequest = {
+declare function digits(options?: DigitsRuleOptions): Rule;
+declare namespace digits {
+    /**
+     * datasetから digits ルールを生成する
+     * - data-tig-rules-digits が無ければ null
+     * - オプションは data-tig-rules-digits-xxx から読む
+     *
+     * 対応する data 属性（dataset 名）
+     * - data-tig-rules-digits                          -> dataset.tigRulesDigits
+     * - data-tig-rules-digits-int                      -> dataset.tigRulesDigitsInt
+     * - data-tig-rules-digits-frac                     -> dataset.tigRulesDigitsFrac
+     * - data-tig-rules-digits-count-leading-zeros      -> dataset.tigRulesDigitsCountLeadingZeros
+     * - data-tig-rules-digits-fix-int-on-blur          -> dataset.tigRulesDigitsFixIntOnBlur
+     * - data-tig-rules-digits-fix-frac-on-blur         -> dataset.tigRulesDigitsFixFracOnBlur
+     * - data-tig-rules-digits-overflow-input-int       -> dataset.tigRulesDigitsOverflowInputInt
+     * - data-tig-rules-digits-overflow-input-frac      -> dataset.tigRulesDigitsOverflowInputFrac
+     * - data-tig-rules-digits-force-frac-on-blur       -> dataset.tigRulesDigitsForceFracOnBlur
+     *
+     * @param {DOMStringMap} dataset
+     * @param {HTMLInputElement|HTMLTextAreaElement} _el
+     * @returns {import("../text-input-guard.js").Rule|null}
+     */
+    function fromDataset(dataset: DOMStringMap, _el: HTMLInputElement | HTMLTextAreaElement): Rule | null;
+}
+/**
+ * digits ルールのオプション
+ */
+type DigitsRuleOptions = {
     /**
-     * - ルール名や理由（例: "digits.int_overflow"）
+     * - 整数部の最大桁数（省略可）
      */
-    reason: string;
+    int?: number;
     /**
-     * - デバッグ用の詳細
+     * - 小数部の最大桁数（省略可）
      */
-    detail?: any;
+    frac?: number;
+    /**
+     * - 整数部の先頭ゼロを桁数に含める
+     */
+    countLeadingZeros?: boolean;
+    /**
+     * - blur時の整数部補正
+     */
+    fixIntOnBlur?: "none" | "truncateLeft" | "truncateRight" | "clamp";
+    /**
+     * - blur時の小数部補正
+     */
+    fixFracOnBlur?: "none" | "truncate" | "round";
+    /**
+     * - 入力中：整数部が最大桁を超える入力をブロックする
+     */
+    overflowInputInt?: "none" | "block";
+    /**
+     * - 入力中：小数部が最大桁を超える入力をブロックする
+     */
+    overflowInputFrac?: "none" | "block";
+    /**
+     * - blur時に小数部を必ず表示（frac桁まで0埋め）
+     */
+    forceFracOnBlur?: boolean;
 };
 
-export { attach, attachAll };
-export type { AttachOptions, ElementKind, Guard, GuardContext, GuardGroup, PhaseName, RevertRequest, Rule, SelectionState, SeparateValueOptions, SetValueInput, SetValueMode, TigError };
+/**
+ * The script is part of TextInputGuard.
+ *
+ * AUTHOR:
+ *  natade-jp (https://github.com/natade-jp)
+ *
+ * LICENSE:
+ *  The MIT license https://opensource.org/licenses/MIT
+ */
+/**
+ * カンマ付与ルール
+ * - blur時のみ整数部に3桁区切りカンマを付与する
+ * @returns {import("../text-input-guard.js").Rule}
+ */
+declare function comma(): Rule;
+declare namespace comma {
+    /**
+     * datasetから comma ルールを生成する
+     * - data-tig-rules-comma が無ければ null
+     *
+     * 対応する data 属性（dataset 名）
+     * - data-tig-rules-comma -> dataset.tigRulesComma
+     *
+     * @param {DOMStringMap} dataset
+     * @param {HTMLInputElement|HTMLTextAreaElement} _el
+     * @returns {import("../text-input-guard.js").Rule|null}
+     */
+    function fromDataset(dataset: DOMStringMap, _el: HTMLInputElement | HTMLTextAreaElement): Rule | null;
+}
+
+/**
+ * kana ルールのオプション
+ * @typedef {Object} KanaRuleOptions
+ * @property {"katakana-full"|"katakana-half"|"hiragana"} [target="katakana-full"] - 統一先
+ * @property {boolean} [nfkc=true] - 事前に Unicode NFKC 正規化を行う（合体文字などを正規化）
+ */
+/**
+ * kana ルールを生成する
+ * @param {KanaRuleOptions} [options]
+ * @returns {import("../text-input-guard.js").Rule}
+ */
+declare function kana(options?: KanaRuleOptions): Rule;
+declare namespace kana {
+    /**
+     * datasetから kana ルールを生成する
+     * - data-tig-rules-kana が無ければ null
+     * - オプションは data-tig-rules-kana-xxx から読む
+     *
+     * 対応する data 属性（dataset 名）
+     * - data-tig-rules-kana               -> dataset.tigRulesKana
+     * - data-tig-rules-kana-target        -> dataset.tigRulesKanaTarget
+     * - data-tig-rules-kana-nfkc          -> dataset.tigRulesKanaNfkc
+     *
+     * @param {DOMStringMap} dataset
+     * @param {HTMLInputElement|HTMLTextAreaElement} _el
+     * @returns {import("../text-input-guard.js").Rule|null}
+     */
+    function fromDataset(dataset: DOMStringMap, _el: HTMLInputElement | HTMLTextAreaElement): Rule | null;
+}
+/**
+ * kana ルールのオプション
+ */
+type KanaRuleOptions = {
+    /**
+     * - 統一先
+     */
+    target?: "katakana-full" | "katakana-half" | "hiragana";
+    /**
+     * - 事前に Unicode NFKC 正規化を行う（合体文字などを正規化）
+     */
+    nfkc?: boolean;
+};
+
+/**
+ * ascii ルールのオプション
+ * @typedef {Object} AsciiRuleOptions
+ * @property {"none"|"upper"|"lower"} [case] - 英字の大文字/小文字統一
+ */
+/**
+ * ascii ルールを生成する
+ * - 全角英数字・記号・全角スペースを半角へ正規化する
+ * - 必要に応じて英字を大文字/小文字へ統一
+ *
+ * @param {AsciiRuleOptions} [options]
+ * @returns {import("../text-input-guard.js").Rule}
+ */
+declare function ascii(options?: AsciiRuleOptions): Rule;
+declare namespace ascii {
+    /**
+     * datasetから ascii ルールを生成する
+     *
+     * 対応する data 属性
+     * - data-tig-rules-ascii
+     * - data-tig-rules-ascii-case   ("none" | "upper" | "lower")
+     *
+     * @param {DOMStringMap} dataset
+     * @param {HTMLInputElement|HTMLTextAreaElement} _el
+     * @returns {import("../text-input-guard.js").Rule|null}
+     */
+    function fromDataset(dataset: DOMStringMap, _el: HTMLInputElement | HTMLTextAreaElement): Rule | null;
+}
+/**
+ * ascii ルールのオプション
+ */
+type AsciiRuleOptions = {
+    /**
+     * - 英字の大文字/小文字統一
+     */
+    case?: "none" | "upper" | "lower";
+};
+
+/**
+ * filter ルールを生成する
+ * - mode="drop": 不要文字を落とすだけ
+ * - mode="error": 文字は落とさず validate でエラーを積む
+ *
+ * @param {FilterRuleOptions} [options]
+ * @returns {import("../text-input-guard.js").Rule}
+ */
+declare function filter(options?: FilterRuleOptions): Rule;
+declare namespace filter {
+    /**
+     * datasetから filter ルールを生成する
+     * - data-tig-rules-filter が無ければ null
+     *
+     * 対応する data 属性（dataset 名）
+     * - data-tig-rules-filter               -> dataset.tigRulesFilter
+     * - data-tig-rules-filter-mode          -> dataset.tigRulesFilterMode ("drop"|"error")
+     * - data-tig-rules-filter-category      -> dataset.tigRulesFilterCategory ("a,b,c")
+     * - data-tig-rules-filter-allow         -> dataset.tigRulesFilterAllow
+     * - data-tig-rules-filter-allow-flags   -> dataset.tigRulesFilterAllowFlags
+     * - data-tig-rules-filter-deny          -> dataset.tigRulesFilterDeny
+     * - data-tig-rules-filter-deny-flags    -> dataset.tigRulesFilterDenyFlags
+     *
+     * @param {DOMStringMap} dataset
+     * @param {HTMLInputElement|HTMLTextAreaElement} _el
+     * @returns {import("../text-input-guard.js").Rule|null}
+     */
+    function fromDataset(dataset: DOMStringMap, _el: HTMLInputElement | HTMLTextAreaElement): Rule | null;
+}
+/**
+ * filter ルールのカテゴリ名
+ *
+ * - "digits"         : ASCII 数字 (0-9)
+ * - "alpha-upper"    : ASCII 英字大文字 (A-Z)
+ * - "alpha-lower"    : ASCII 英字小文字 (a-z)
+ * - "ascii"          : ASCII 可視文字 + スペース含む (U+0020–U+007E)
+ * - "hiragana"       : ひらがな (U+3040–U+309F)
+ * - "katakana-full"  : 全角カタカナ (U+30A0–U+30FF)
+ * - "katakana-half"  : 半角カタカナ (U+FF65–U+FF9F)
+ * - "bmp-only"       : BMP のみ許可（U+0000–U+FFFF、サロゲートペア、補助平面禁止）
+ * - "sjis-only"      : 正規 Shift_JIS（JIS X 0208 + 1バイト領域）のみ許可
+ * - "cp932-only"     : Windows-31J (CP932) でエンコード可能な文字のみ許可
+ * - "single-codepoint-only" : 単一コードポイントのみ許可（結合文字や異体字セレクタを含まない）
+ */
+type FilterCategory = "digits" | "alpha-upper" | "alpha-lower" | "ascii" | "hiragana" | "katakana-full" | "katakana-half" | "bmp-only" | "sjis-only" | "cp932-only" | "single-codepoint-only";
+/**
+ * filter ルールの動作モード
+ */
+type FilterMode = "drop" | "error";
+/**
+ * filter ルールのオプション
+ * - category は和集合で扱う（複数指定OK）
+ * - allow は追加許可（和集合）
+ * - deny は除外（差集合）
+ *
+ * allowed = (category の和集合 ∪ allow) − deny
+ */
+type FilterRuleOptions = {
+    /**
+     * - drop: 不要文字を削除 / error: 削除せずエラーを積む
+     */
+    mode?: FilterMode;
+    /**
+     * - カテゴリ（配列）
+     */
+    category?: FilterCategory[];
+    /**
+     * - 追加で許可する正規表現（1文字にマッチさせる想定）
+     */
+    allow?: RegExp | string;
+    /**
+     * - allow が文字列のときの flags（"iu" など。g/y は無視）
+     */
+    allowFlags?: string;
+    /**
+     * - 除外する正規表現（1文字にマッチさせる想定）
+     */
+    deny?: RegExp | string;
+    /**
+     * - deny が文字列のときの flags（"iu" など。g/y は無視）
+     */
+    denyFlags?: string;
+};
+
+/**
+ * length ルールを生成する
+ * @param {LengthRuleOptions} [options]
+ * @returns {import("../text-input-guard.js").Rule}
+ */
+declare function length(options?: LengthRuleOptions): Rule;
+declare namespace length {
+    /**
+     * datasetから length ルールを生成する
+     * - data-tig-rules-length が無ければ null
+     * - オプションは data-tig-rules-length-xxx から読む
+     *
+     * 対応する data 属性（dataset 名）
+     * - data-tig-rules-length                     -> dataset.tigRulesLength
+     * - data-tig-rules-length-max                 -> dataset.tigRulesLengthMax
+     * - data-tig-rules-length-overflow-input      -> dataset.tigRulesLengthOverflowInput
+     * - data-tig-rules-length-unit                -> dataset.tigRulesLengthUnit
+     *
+     * @param {DOMStringMap} dataset
+     * @param {HTMLInputElement|HTMLTextAreaElement} _el
+     * @returns {import("../text-input-guard.js").Rule|null}
+     */
+    function fromDataset(dataset: DOMStringMap, _el: HTMLInputElement | HTMLTextAreaElement): Rule | null;
+}
+/**
+ * length ルールのオプション
+ */
+type LengthRuleOptions = {
+    /**
+     * - 最大長（グラフェム数）。未指定なら制限なし
+     */
+    max?: number;
+    /**
+     * - 入力中に最大長を超えたときの挙動
+     */
+    overflowInput?: "block" | "error";
+    /**
+     * - 長さの単位
+     *
+     * block   : 最大長を超える部分を切る
+     * error   : エラーを積むだけ（値は変更しない）
+     */
+    unit?: "grapheme" | "utf-16" | "utf-32";
+};
+
+/**
+ * The script is part of TextInputGuard.
+ *
+ * AUTHOR:
+ *  natade-jp (https://github.com/natade-jp)
+ *
+ * LICENSE:
+ *  The MIT license https://opensource.org/licenses/MIT
+ */
+/**
+ * prefix ルールのオプション
+ * @typedef {Object} PrefixRuleOptions
+ * @property {string} text - 先頭に付ける文字列
+ * @property {boolean} [showWhenEmpty=false] - 値が空でも表示するか
+ */
+/**
+ * 先頭装飾（prefix）ルール
+ * - 表示用として先頭に文字列を付与する
+ * - 手動入力された同文字列は normalizeStructure で除去する
+ *
+ * @param {PrefixRuleOptions} options
+ * @returns {import("../text-input-guard.js").Rule}
+ */
+declare function prefix(options: PrefixRuleOptions): Rule;
+declare namespace prefix {
+    /**
+     * datasetから prefix ルールを生成する
+     * - data-tig-rules-prefix が無ければ null
+     *
+     * 対応する data 属性（dataset 名）
+     * - data-tig-rules-prefix                  -> dataset.tigRulesPrefix
+     * - data-tig-rules-prefix-text             -> dataset.tigRulesPrefixText
+     * - data-tig-rules-prefix-show-when-empty  -> dataset.tigRulesPrefixShowWhenEmpty
+     *
+     * @param {DOMStringMap} dataset
+     * @param {HTMLInputElement|HTMLTextAreaElement} _el
+     * @returns {import("../text-input-guard.js").Rule|null}
+     */
+    function fromDataset(dataset: DOMStringMap, _el: HTMLInputElement | HTMLTextAreaElement): Rule | null;
+}
+/**
+ * prefix ルールのオプション
+ */
+type PrefixRuleOptions = {
+    /**
+     * - 先頭に付ける文字列
+     */
+    text: string;
+    /**
+     * - 値が空でも表示するか
+     */
+    showWhenEmpty?: boolean;
+};
+
+/**
+ * The script is part of TextInputGuard.
+ *
+ * AUTHOR:
+ *  natade-jp (https://github.com/natade-jp)
+ *
+ * LICENSE:
+ *  The MIT license https://opensource.org/licenses/MIT
+ */
+/**
+ * suffix ルールのオプション
+ * @typedef {Object} SuffixRuleOptions
+ * @property {string} text - 末尾に付ける文字列
+ * @property {boolean} [showWhenEmpty=false] - 値が空でも表示するか
+ */
+/**
+ * 末尾装飾（suffix）ルール
+ * - 表示用として末尾に文字列を付与する
+ * - 手動入力された同文字列は normalizeStructure で除去する
+ *
+ * @param {SuffixRuleOptions} options
+ * @returns {import("../text-input-guard.js").Rule}
+ */
+declare function suffix(options: SuffixRuleOptions): Rule;
+declare namespace suffix {
+    /**
+     * datasetから suffix ルールを生成する
+     * - data-tig-rules-suffix が無ければ null
+     *
+     * 対応する data 属性（dataset 名）
+     * - data-tig-rules-suffix                  -> dataset.tigRulesSuffix
+     * - data-tig-rules-suffix-text             -> dataset.tigRulesSuffixText
+     * - data-tig-rules-suffix-show-when-empty  -> dataset.tigRulesSuffixShowWhenEmpty
+     *
+     * @param {DOMStringMap} dataset
+     * @param {HTMLInputElement|HTMLTextAreaElement} _el
+     * @returns {import("../text-input-guard.js").Rule|null}
+     */
+    function fromDataset(dataset: DOMStringMap, _el: HTMLInputElement | HTMLTextAreaElement): Rule | null;
+}
+/**
+ * suffix ルールのオプション
+ */
+type SuffixRuleOptions = {
+    /**
+     * - 末尾に付ける文字列
+     */
+    text: string;
+    /**
+     * - 値が空でも表示するか
+     */
+    showWhenEmpty?: boolean;
+};
+
+/**
+ * The script is part of TextInputGuard.
+ *
+ * AUTHOR:
+ *  natade-jp (https://github.com/natade-jp)
+ *
+ * LICENSE:
+ *  The MIT license https://opensource.org/licenses/MIT
+ */
+/**
+ * トリムするルール
+ * @returns {import("../text-input-guard.js").Rule}
+ */
+declare function trim(): Rule;
+declare namespace trim {
+    /**
+     * datasetから trim ルールを生成する
+     * - data-tig-rules-trim が無ければ null
+     *
+     * 対応する data 属性（dataset 名）
+     * - data-tig-rules-trim -> dataset.tigRulesTrim
+     *
+     * @param {DOMStringMap} dataset
+     * @param {HTMLInputElement|HTMLTextAreaElement} _el
+     * @returns {import("../text-input-guard.js").Rule|null}
+     */
+    function fromDataset(dataset: DOMStringMap, _el: HTMLInputElement | HTMLTextAreaElement): Rule | null;
+}
+
+declare function autoAttach(root?: Document | DocumentFragment | ShadowRoot | Element): GuardGroup;
+declare namespace rules {
+    export { numeric };
+    export { digits };
+    export { comma };
+    export { kana };
+    export { ascii };
+    export { filter };
+    export { length };
+    export { prefix };
+    export { suffix };
+    export { trim };
+}
+/**
+ * バージョン（ビルド時に置換したいならここを差し替える）
+ * 例: rollup replace で "__VERSION__" を package.json の version に置換
+ */
+declare const version: any;
+
+export { ascii, attach, attachAll, autoAttach, comma, digits, filter, kana, length, numeric, prefix, rules, suffix, trim, version };