From 3564648f5f523e6123690f967e356694a9efcaa6 Mon Sep 17 00:00:00 2001 From: Sin-Kang Date: Fri, 17 Jul 2026 11:21:52 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20explain=20the=20attribute=20model=20?= =?UTF-8?q?=E2=80=94=20data-numkey=20is=20the=20switch,=20the=20rest=20are?= =?UTF-8?q?=20options?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Readers couldn't tell data-numkey and data-numkey-locale apart: the README listed the attributes in one flat table without saying that data-numkey is what binds an input (and that every other data-numkey-* attribute is inert without it), and the locale option had no examples showing default vs auto vs pinned-tag behavior. - README en/ko: 'How the attributes work' section with an on/off/anti-example block, table now marks data-numkey as THE switch, new 'Locale-aware display' section with the three variants and per-browser outcomes, plus the form-POST caveat (display value is what posts — getValue before submit) - demo site: same three-variant snippet in the locale card --- README.ko.md | 44 ++++++++++++++++++++++++++++++++++++++++++-- README.md | 45 +++++++++++++++++++++++++++++++++++++++++++-- site/index.html | 12 ++++++++++-- 3 files changed, 95 insertions(+), 6 deletions(-) diff --git a/README.ko.md b/README.ko.md index 120250d..88833a5 100644 --- a/README.ko.md +++ b/README.ko.md @@ -52,15 +52,55 @@ numkey는 그 인풋을 한 번에 끝냅니다: (또는 서버에서 콤마를 제거해도 됩니다 — POST되는 값은 표시 값입니다.) +### 속성이 동작하는 방식 + +**`data-numkey`가 스위치입니다.** 인풋을 바인딩시키는 것이 바로 이 속성이고 +(자동 초기화가 `input[data-numkey]`를 감시합니다), 값은 최대 소수 자릿수를 +겸합니다 — 빈 값이면 정수 전용. 나머지 `data-numkey-*` 속성들은 전부 +`data-numkey`가 있는 인풋에서만 읽히는 *옵션*이라, 단독으로는 아무것도 하지 +않습니다: + +```html + + + + + +``` + | 속성 | 의미 | |---|---| -| `data-numkey` | 바인딩; 값은 최대 소수 자릿수 (빈 값 = 정수) | +| `data-numkey` | **스위치** — 인풋을 바인딩; 값은 최대 소수 자릿수 (빈 값 = 정수) | | `data-numkey-negative` | 앞자리 마이너스 허용 | | `data-numkey-align="left"` | 자동 오른쪽 정렬 옵트아웃 | | `data-numkey-group="4"` | 그룹 크기 (기본 3, 만 단위는 4) | | `data-numkey-separator=" "` | 그룹 구분자 (기본 `,`) | | `data-numkey-point=","` | 필드에 표시되는 소수점 (기본 `.`) | -| `data-numkey-locale="auto"` | 로케일에서 구분자 유도 — `"auto"`(브라우저 언어) 또는 `"de-DE"` 같은 BCP 47 태그 | +| `data-numkey-locale` | 로케일에서 구분자 유도 — 아래 참조 | + +### 로케일 표시 (옵트인) + +기본 동작은 **고정 표시**입니다: 방문자 브라우저 설정이 무엇이든 모두가 +`1,234,567.89`를 봅니다 — 업무 폼이 보통 원하는 동작이죠. +`data-numkey-locale`을 붙인 필드만 로케일 구분자를 따릅니다: + +```html + + + + + + + + +``` + +로케일이 바꾸는 건 **그리는 방식뿐**입니다. 정식 값은 항상 +`"1234567.89"` — 세 경우 모두 `numkey.getValue(el)`이 같은 문자열을 +돌려줍니다. 일반 폼 POST는 *표시 값*을 전송하므로, 로케일을 쓰는 폼은 +제출 전에 `getValue`를 hidden 필드에 담거나 서버에서 정규화하세요. > `type="text"` 인풋을 쓰세요. numkey가 `inputmode`를 설정해 모바일에서 숫자 > 키패드가 뜹니다. `type="number"`는 커서 API가 없어 포맷팅과 충돌합니다. diff --git a/README.md b/README.md index 1168e7d..8267182 100644 --- a/README.md +++ b/README.md @@ -54,15 +54,56 @@ on load. To read the raw value back before submitting: (Or simply strip separators server-side — the posted value is the display value.) +### How the attributes work + +**`data-numkey` is the on-switch.** It is what gets an input bound (auto-init +watches `input[data-numkey]`), and its value doubles as the max decimal +places — empty means integers only. Every other `data-numkey-*` attribute is +an *option* that is only read from inputs that have `data-numkey`; on its own +it does nothing: + +```html + + + + + +``` + | Attribute | Meaning | |---|---| -| `data-numkey` | bind; the value is the max decimal places (empty = integer) | +| `data-numkey` | **the switch** — binds the input; the value is the max decimal places (empty = integer) | | `data-numkey-negative` | allow a leading minus | | `data-numkey-align="left"` | opt out of automatic right alignment | | `data-numkey-group="4"` | group size (default 3) | | `data-numkey-separator=" "` | group separator (default `,`) | | `data-numkey-point=","` | decimal mark shown in the field (default `.`) | -| `data-numkey-locale="auto"` | derive separators from a locale — `"auto"` (browser language) or a BCP 47 tag like `"de-DE"` | +| `data-numkey-locale` | derive separators from a locale — see below | + +### Locale-aware display (opt-in) + +By default the display is **deterministic**: every visitor sees +`1,234,567.89`, whatever their browser is set to — which is what business +forms usually need. `data-numkey-locale` opts a field into locale separators: + +```html + + + + + + + + +``` + +The locale changes **only how the value is drawn**. The canonical value is +always `"1234567.89"` — `numkey.getValue(el)` returns the same string in all +three cases. Since a plain form POST submits the *display* value, a form +using locales should read `getValue` into a hidden field (or normalize +server-side) before submitting. > Use `type="text"` inputs. numkey sets `inputmode` so mobile keyboards show > the numeric keypad; `type="number"` has no caret API and fights formatting. diff --git a/site/index.html b/site/index.html index 2568189..4d318dc 100644 --- a/site/index.html +++ b/site/index.html @@ -93,9 +93,17 @@

Try it — everything below is just markup / 전부 마크

Locale (opt-in) / 로케일은 옵트인 — 기본값은 브라우저와 무관하게 고정

- By default the display is deterministic (1,234,567.89) no matter the visitor's - browser. Add data-numkey-locale only when you want locale separators. + data-numkey is the on-switch; data-numkey-locale is an option on top + of it that only changes how the value is drawn. The canonical value stays the same.
+ data-numkey가 스위치, data-numkey-locale은 그 위의 + 표시 옵션 — 정식 값은 그대로입니다.

+
<input data-numkey="2">                          <!-- everyone: 1,234,567.89 -->
+<input data-numkey="2" data-numkey-locale="auto">  <!-- browser language:
+                                                        de → 1.234.567,89
+                                                        ko → 1,234,567.89 -->
+<input data-numkey="2" data-numkey-locale="de-DE"> <!-- pinned German -->
+<input data-numkey-locale="auto">                  <!-- ✗ nothing: no data-numkey -->