Skip to content

docs: explain the attribute model — data-numkey is the switch, the rest are options #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jlc488 merged 1 commit into from
Jul 17, 2026
Merged

docs: explain the attribute model — data-numkey is the switch, the rest are options #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 42 additions & 2 deletions README.ko.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,15 +52,55 @@ numkey는 그 인풋을 한 번에 끝냅니다:

(또는 서버에서 콤마를 제거해도 됩니다 — POST되는 값은 표시 값입니다.)

### 속성이 동작하는 방식

**`data-numkey`가 스위치입니다.** 인풋을 바인딩시키는 것이 바로 이 속성이고
(자동 초기화가 `input[data-numkey]`를 감시합니다), 값은 최대 소수 자릿수를
겸합니다 — 빈 값이면 정수 전용. 나머지 `data-numkey-*` 속성들은 전부
`data-numkey`가 있는 인풋에서만 읽히는 *옵션*이라, 단독으로는 아무것도 하지
않습니다:

```html
<input data-numkey> <!-- ON, 정수: 1,234,567 -->
<input data-numkey="2"> <!-- ON, 소수 2자리: 1,234.56 -->
<input data-numkey="2" data-numkey-negative> <!-- 옵션은 겹쳐 씀 -->
<input data-numkey-locale="auto"> <!-- ✗ 아무것도 안 함 — data-numkey 없음 -->
<input> <!-- 평범한 인풋, 건드리지 않음 -->
```

| 속성 | 의미 |
|---|---|
| `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
<!-- 모두가 1,234,567.89 — 기본값, 로케일 무관 -->
<input data-numkey="2">

<!-- 방문자의 브라우저 언어를 따름:
독일어 브라우저 → 1.234.567,89
한국어 브라우저 → 1,234,567.89 -->
<input data-numkey="2" data-numkey-locale="auto">

<!-- 모든 방문자에게 독일식으로 고정 -->
<input data-numkey="2" data-numkey-locale="de-DE">
```

로케일이 바꾸는 건 **그리는 방식뿐**입니다. 정식 값은 항상
`"1234567.89"` — 세 경우 모두 `numkey.getValue(el)`이 같은 문자열을
돌려줍니다. 일반 폼 POST는 *표시 값*을 전송하므로, 로케일을 쓰는 폼은
제출 전에 `getValue`를 hidden 필드에 담거나 서버에서 정규화하세요.

> `type="text"` 인풋을 쓰세요. numkey가 `inputmode`를 설정해 모바일에서 숫자
> 키패드가 뜹니다. `type="number"`는 커서 API가 없어 포맷팅과 충돌합니다.
Expand Down
45 changes: 43 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
<input data-numkey> <!-- ON, integers: 1,234,567 -->
<input data-numkey="2"> <!-- ON, 2 decimals: 1,234.56 -->
<input data-numkey="2" data-numkey-negative> <!-- options stack -->
<input data-numkey-locale="auto"> <!-- ✗ does NOTHING — no data-numkey -->
<input> <!-- plain input, untouched -->
```

| 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
<!-- everyone sees 1,234,567.89 — the default, no locale involved -->
<input data-numkey="2">

<!-- follows the visitor's browser language:
a German browser shows 1.234.567,89
a Korean browser shows 1,234,567.89 -->
<input data-numkey="2" data-numkey-locale="auto">

<!-- pinned to German formatting for every visitor -->
<input data-numkey="2" data-numkey-locale="de-DE">
```

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.
Expand Down
12 changes: 10 additions & 2 deletions site/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,9 +93,17 @@ <h2>Try it — everything below is just markup <span class="ko">/ 전부 마크
<div class="card">
<h2>Locale (opt-in) <span class="ko">/ 로케일은 옵트인 — 기본값은 브라우저와 무관하게 고정</span></h2>
<p style="font-size:0.9rem; margin-top:0">
By default the display is deterministic (<code>1,234,567.89</code>) no matter the visitor's
browser. Add <code>data-numkey-locale</code> only when you want locale separators.
<code>data-numkey</code> is the on-switch; <code>data-numkey-locale</code> is an option on top
of it that only changes how the value is <em>drawn</em>. The canonical value stays the same.<br>
<span class="ko"><code>data-numkey</code>가 스위치, <code>data-numkey-locale</code>은 그 위의
표시 옵션 — 정식 값은 그대로입니다.</span>
</p>
<pre>&lt;input data-numkey="2"&gt; &lt;!-- everyone: 1,234,567.89 --&gt;
&lt;input data-numkey="2" data-numkey-locale="auto"&gt; &lt;!-- browser language:
de → 1.234.567,89
ko → 1,234,567.89 --&gt;
&lt;input data-numkey="2" data-numkey-locale="de-DE"&gt; &lt;!-- pinned German --&gt;
&lt;input data-numkey-locale="auto"&gt; &lt;!-- ✗ nothing: no data-numkey --&gt;</pre>
<label>
<select id="locale-select">
<option value="">default (deterministic)</option>
Expand Down