mother-mask 3.41.0 → 3.43.0

package/README.md

@@ -169,6 +169,1165 @@ server-only code can continue importing pure helpers from `mother-mask`.
 See the [React example](https://github.com/dan2dev/mother-mask/tree/main/examples/react-simple)
 for a runnable app and browser lifecycle/memory tests.
 
+## Vue
+
+Import the custom directives from the separate `mother-mask/vue` entry:
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { vMotherMask, vMotherMaskDecimal, formatDecimalValue } from 'mother-mask/vue'
+
+// Keep the options object stable across renders.
+const currency = { decimalPlaces: 2, prefix: '$', allowNegative: true }
+
+const phone = ref('')
+const amount = ref('')
+</script>
+
+<template>
+  <label for="phone">Phone</label>
+  <input
+    id="phone"
+    name="phone"
+    inputmode="tel"
+    v-mother-mask="{ mask: '(99) 99999-9999', value: phone, onValueChange: (v) => (phone = v) }"
+  />
+
+  <label for="amount">Amount</label>
+  <input
+    id="amount"
+    name="amount"
+    v-mother-mask-decimal="{ options: currency, value: amount, onValueChange: (v) => (amount = v) }"
+  />
+
+  <button type="button" @click="amount = formatDecimalValue(1234.5, currency)">
+    Set amount
+  </button>
+</template>
+```
+
+`mother-mask/vue` re-exports every core function, class, and type as well as
+the `vMotherMask` and `vMotherMaskDecimal` directives. Its core exports are
+aliases to `mother-mask`, sharing the same implementation and caches. The
+core ESM, CommonJS, and UMD builds remain independent of Vue. Vue is an
+optional peer dependency required only when importing `mother-mask/vue`; the
+supported version range is `^3.5.0`. Vue is not bundled.
+
+- `vMotherMask` takes `{ mask, options?, value?, onValueChange? }`;
+  `vMotherMaskDecimal` takes `{ options?, value?, onValueChange? }` and calls
+  `onValueChange(value, numericValue)`. `vMotherMaskDecimal` always sets
+  `inputmode="decimal"` on mount.
+- Both are exported pre-named `v` + PascalCase — Vue's own convention for a
+  local directive in `<script setup>` — so `import { vMotherMask } from
+  'mother-mask/vue'` alone makes `v-mother-mask="..."` available in the
+  template with no import rename. Register it globally instead with
+  `app.directive('mother-mask', vMotherMask)` to make `v-mother-mask`
+  available in every component.
+- `mounted` runs only once Vue mounts the element to the live DOM — Vue
+  never invokes directive hooks during server-side rendering, so this is
+  SSR-safe with no `typeof window` guard needed. `updated` runs on every
+  re-render of the owning component (not only when the bound value actually
+  changes), so it rebinds only if the mask, options, or an externally-set
+  value actually changed — an echo of the directive's own `onValueChange` is
+  ignored. `beforeUnmount` guarantees `dispose()` runs exactly once.
+- A `declare module 'vue' { interface GlobalDirectives { ... } }`
+  augmentation ships alongside each directive, so a globally-registered
+  `v-mother-mask`/`v-mother-mask-decimal` also type-checks in templates
+  without extra setup.
+
+See the [Vue example](https://github.com/dan2dev/mother-mask/tree/main/examples/vue-simple)
+for a runnable app.
+
+## Angular
+
+Import the standalone directives from the separate `mother-mask/angular` entry:
+
+```ts
+import { Component } from '@angular/core'
+import { MotherMaskDecimalDirective, MotherMaskDirective, formatDecimalValue } from 'mother-mask/angular'
+
+// Keep option objects stable across change detection cycles.
+const currency = { decimalPlaces: 2, prefix: '$', allowNegative: true }
+
+@Component({
+  standalone: true,
+  imports: [MotherMaskDirective, MotherMaskDecimalDirective],
+  template: `
+    <label for="phone">Phone</label>
+    <input id="phone" name="phone" motherMask="(99) 99999-9999" inputmode="tel" [(value)]="phone" />
+
+    <label for="amount">Amount</label>
+    <input id="amount" name="amount" motherMaskDecimal [motherMaskDecimalOptions]="currency" [(value)]="amount" />
+
+    <button type="button" (click)="amount = formatDecimalValue(1234.5, currency)">Set amount</button>
+  `,
+})
+export class FormComponent {
+  readonly currency = currency
+  // Plain fields, not signals: the directives below bind `value` through
+  // classic @Input/@Output (see why in the notes under this example), so
+  // `[(value)]` assigns to this property directly on each change.
+  phone = ''
+  amount = ''
+}
+```
+
+`mother-mask/angular` re-exports every core function, class, and type as well
+as `MotherMaskDirective` and `MotherMaskDecimalDirective`. Its core exports
+are aliases to `mother-mask`, sharing the same implementation and caches. The
+core ESM, CommonJS, and UMD builds remain independent of Angular. Angular is
+an optional peer dependency required only when importing
+`mother-mask/angular`; the supported version range is `^19.0.0 || ^20.0.0`.
+Angular is not bundled.
+
+- Both directives are attribute selectors (`input[motherMask]` and
+  `input[motherMaskDecimal]`) and support `[(value)]` two-way binding.
+  `MotherMaskDirective` accepts `motherMask` (a `MaskPattern`) and optional
+  `[motherMaskOptions]`; `MotherMaskDecimalDirective` accepts optional
+  `[motherMaskDecimalOptions]` and additionally emits `(numericValueChange)`.
+- The binding lifecycle is Signals-driven: `ngOnChanges` pushes the current
+  mask/options/value into an internal `signal`, and `afterRenderEffect` —
+  which Angular runs only on the browser, never during server-side
+  rendering, so no manual `typeof window` check is needed — reactively
+  (re)binds whenever that signal changes. `ngOnDestroy` disposes the
+  binding, and it is disposed and recreated whenever the mask/options change
+  or `value` is updated externally.
+- `value`/`valueChange` (and `numericValueChange`) use classic
+  `@Input`/`@Output` rather than the functional `input()`/`model()` API,
+  since Angular only wires signal-based inputs to template bindings through
+  the ngtsc compiler's static analysis — unavailable without the Angular CLI
+  build toolchain. Both forms compile to the same `[(value)]` template
+  syntax for consumers.
+- `MotherMaskDecimalDirective` always sets `inputmode="decimal"` via a host
+  binding.
+
+See the [Angular example](https://github.com/dan2dev/mother-mask/tree/main/examples/angular-simple)
+for a runnable app.
+
+## Svelte
+
+Import the Svelte 5 actions from the separate `mother-mask/svelte` entry:
+
+```svelte
+<script lang="ts">
+  import { motherMask, motherMaskDecimal, formatDecimalValue } from 'mother-mask/svelte'
+
+  // Keep the options object stable across renders.
+  const currency = { decimalPlaces: 2, prefix: '$', allowNegative: true }
+
+  let phone = $state('')
+  let amount = $state('')
+</script>
+
+<label for="phone">Phone</label>
+<input
+  id="phone"
+  name="phone"
+  inputmode="tel"
+  use:motherMask={{ mask: '(99) 99999-9999', value: phone, onValueChange: (v) => (phone = v) }}
+/>
+
+<label for="amount">Amount</label>
+<input
+  id="amount"
+  name="amount"
+  use:motherMaskDecimal={{ options: currency, value: amount, onValueChange: (v) => (amount = v) }}
+/>
+
+<button type="button" onclick={() => (amount = formatDecimalValue(1234.5, currency))}>
+  Set amount
+</button>
+```
+
+`mother-mask/svelte` re-exports every core function, class, and type as well
+as the `motherMask` and `motherMaskDecimal` actions. Its core exports are
+aliases to `mother-mask`, sharing the same implementation and caches. The
+core ESM, CommonJS, and UMD builds remain independent of Svelte, and this
+entry has no runtime dependency on the `svelte` package at all — it's plain
+TypeScript, usable from any Svelte 5 (or 4) component via `use:`.
+
+- Actions run only once Svelte mounts the element to the live DOM, and are
+  torn down when it leaves — Svelte never invokes `use:` directives during
+  server-side rendering, so this is SSR-safe with no `typeof window` guard.
+  `destroy()` guarantees `dispose()` runs exactly once.
+- `update(params)` is Svelte's own reactivity hook: whenever a `$state`
+  value read inside the `use:motherMask={...}` expression changes — `mask`,
+  `options`, or `value` — Svelte re-invokes it with the new params, and the
+  action rebinds only if the mask/options changed or `value` was set
+  externally (an echo of the action's own `onValueChange` is ignored).
+- `motherMask` takes `{ mask, options?, value?, onValueChange? }`;
+  `motherMaskDecimal` takes `{ options?, value?, onValueChange? }` and calls
+  `onValueChange(value, numericValue)`. `motherMaskDecimal` always sets
+  `inputmode="decimal"` on mount.
+
+See the [Svelte example](https://github.com/dan2dev/mother-mask/tree/main/examples/svelte-simple)
+for a runnable app.
+
+## SolidJS
+
+Import the custom directives from the separate `mother-mask/solid` entry:
+
+```tsx
+import { createSignal } from 'solid-js'
+import { motherMask, motherMaskDecimal, formatDecimalValue } from 'mother-mask/solid'
+
+// Keep the options object stable across renders.
+const currency = { decimalPlaces: 2, prefix: '$', allowNegative: true }
+
+export function Form() {
+  const [phone, setPhone] = createSignal('')
+  const [amount, setAmount] = createSignal('')
+
+  return (
+    <>
+      <label for="phone">Phone</label>
+      <input
+        id="phone"
+        name="phone"
+        inputmode="tel"
+        use:motherMask={{ mask: '(99) 99999-9999', value: phone(), onValueChange: setPhone }}
+      />
+
+      <label for="amount">Amount</label>
+      <input
+        id="amount"
+        name="amount"
+        use:motherMaskDecimal={{ options: currency, value: amount(), onValueChange: setAmount }}
+      />
+
+      <button type="button" onClick={() => setAmount(formatDecimalValue(1234.5, currency))}>
+        Set amount
+      </button>
+    </>
+  )
+}
+```
+
+Directive props are typed via `declare module 'solid-js' { namespace JSX { interface Directives { ... } } }`,
+so `use:motherMask`/`use:motherMaskDecimal` type-check without extra setup once
+`mother-mask/solid` is imported anywhere in your project.
+
+`mother-mask/solid` re-exports every core function, class, and type as well
+as the `motherMask` and `motherMaskDecimal` directives. Its core exports are
+aliases to `mother-mask`, sharing the same implementation and caches. The
+core ESM, CommonJS, and UMD builds remain independent of Solid. Solid is an
+optional peer dependency required only when importing `mother-mask/solid`;
+the supported version range is `^1.9.0`. Solid is not bundled.
+
+- Directives run when Solid mounts the element to the live DOM. Solid's
+  server-rendering path never instantiates real elements or invokes `use:`
+  callbacks, so this is SSR-safe with no `typeof window` guard needed.
+- `createEffect` gives fine-grained reactivity: it tracks only the signals
+  actually read while building the params object passed to `use:motherMask`
+  (e.g. `value: phone()`), and reruns exactly when those change — rebinding
+  only if the mask, options, or an externally-set value actually changed
+  (an echo of the directive's own `onValueChange` is ignored). `onCleanup`
+  guarantees `dispose()` runs exactly once, both before every rebind and
+  when the element unmounts.
+- `motherMask` takes `{ mask, options?, value?, onValueChange? }`;
+  `motherMaskDecimal` takes `{ options?, value?, onValueChange? }` and calls
+  `onValueChange(value, numericValue)`, and always sets `inputmode="decimal"`.
+
+See the [SolidJS example](https://github.com/dan2dev/mother-mask/tree/main/examples/solid-simple)
+for a runnable app.
+
+## Preact
+
+Import the Preact components from the separate `mother-mask/preact` entry:
+
+```tsx
+import { useState } from 'preact/hooks'
+import { InputMask, InputDecimal, formatDecimalValue } from 'mother-mask/preact'
+
+// Keep option objects and mask arrays stable across renders.
+const currency = { decimalPlaces: 2, prefix: '$', allowNegative: true }
+
+export function Form() {
+  const [phone, setPhone] = useState('')
+  const [amount, setAmount] = useState('')
+
+  return (
+    <>
+      <label htmlFor="phone">Phone</label>
+      <InputMask
+        id="phone"
+        name="phone"
+        mask="(99) 99999-9999"
+        inputMode="tel"
+        value={phone}
+        onValueChange={setPhone}
+      />
+      <label htmlFor="amount">Amount</label>
+      <InputDecimal
+        id="amount"
+        name="amount"
+        options={currency}
+        value={amount}
+        onValueChange={setAmount}
+      />
+      <button type="button" onClick={() => setAmount(formatDecimalValue(1234.5, currency))}>
+        Set amount
+      </button>
+    </>
+  )
+}
+```
+
+`mother-mask/preact` re-exports every core function, class, and type as well
+as `InputMask`, `InputDecimal`, `InputMaskProps`, and `InputDecimalProps`.
+Its core exports are aliases to `mother-mask`, sharing the same
+implementation and caches. The core ESM, CommonJS, and UMD builds remain
+independent of Preact. Preact is an optional peer dependency required only
+when importing `mother-mask/preact`; the supported version range is
+`^10.0.0`. Preact is not bundled, and this entry never imports
+`preact/compat` — it's built directly on `preact` + `preact/hooks` to keep
+Preact's footprint advantage intact.
+
+- Both components accept controlled string `value` or uncontrolled string
+  `defaultValue`, same as the React version. `InputMask` accepts `mask` and
+  optional `BindOptions`; `InputDecimal` accepts optional
+  `BindDecimalOptions` and reports `(value, numericValue)`.
+- Access to the underlying `<input>` is via an `inputRef` prop, not `ref`:
+  Preact passes `ref` on a function component straight through to the
+  built-in element/instance ref rather than forwarding it as a normal prop
+  (unlike React 19), so reusing `ref` here would require `preact/compat`'s
+  `forwardRef` — extra weight this entry deliberately avoids.
+- This is a leaner port than the React version: it drops the IME
+  composition and native-`reset` edge-case handling built for React-DOM's
+  synthetic event layer (which doesn't exist in Preact), keeping to
+  `useLayoutEffect`/`useRef`/`useState` from `preact/hooks`. The dispose
+  guarantee is identical — every rebind and unmount releases the previous
+  binding first.
+
+See the [Preact example](https://github.com/dan2dev/mother-mask/tree/main/examples/preact-simple)
+for a runnable app.
+
+## Lit
+
+Import the `<lit-mask-input>` and `<lit-mask-decimal>` custom elements from
+the separate `mother-mask/lit` entry — importing the module registers both
+elements as a side effect:
+
+```html
+<script type="module">
+  import 'mother-mask/lit'
+</script>
+
+<label for="phone">Phone</label>
+<lit-mask-input id="phone" name="phone" mask="(99) 99999-9999" input-mode="tel"></lit-mask-input>
+
+<label for="amount">Amount</label>
+<lit-mask-decimal id="amount" name="amount"></lit-mask-decimal>
+
+<script type="module">
+  const phone = document.getElementById('phone')
+  phone.addEventListener('value-change', (e) => console.log(e.detail))
+
+  const amount = document.getElementById('amount')
+  amount.options = { decimalPlaces: 2, prefix: '$', allowNegative: true }
+  amount.addEventListener('numeric-value-change', (e) => console.log(e.detail))
+</script>
+```
+
+`mother-mask/lit` re-exports every core function, class, and type as well as
+the `LitMaskInput` and `LitMaskDecimal` classes (for `instanceof` checks or
+subclassing). Its core exports are aliases to `mother-mask`, sharing the
+same implementation and caches. The core ESM, CommonJS, and UMD builds
+remain independent of Lit. Lit is an optional peer dependency required only
+when importing `mother-mask/lit`; the supported version range is `^3.0.0`.
+Lit is not bundled.
+
+- Both elements render into **light DOM** (`createRenderRoot()` returns
+  `this`, not a shadow root), so a page's own `<label for>` and global CSS
+  reach the native `<input>` directly, the same as any other text field.
+- `<lit-mask-input>` accepts `mask` (a plain string works as an HTML
+  attribute; assign an array/function `MaskPattern` as a JS property) and an
+  `options` object (JS property only — objects can't be expressed as plain
+  attributes). It emits `value-change` (`detail: string`).
+  `<lit-mask-decimal>` accepts an `options` object and emits both
+  `value-change` and `numeric-value-change` (`detail: number`), and always
+  sets `inputmode="decimal"`.
+- Binding happens in `firstUpdated` (Lit's DOM-is-ready hook) and disposes
+  in `disconnectedCallback` — both fire only on the browser, so there's no
+  `typeof window` guard to write. `updated` reactively rebinds whenever
+  `mask`/`options` change or `value` is set externally; an echo of the
+  element's own `value-change` event is ignored.
+- A curated set of native attributes forward to the inner `<input>`: `name`,
+  `placeholder`, `disabled`, `readonly`, `required`, `input-mode`, and
+  `autocomplete`. `id` is a special case: `<lit-mask-input id="phone">`
+  writes `id="phone"` onto the custom element itself, not the `<input>` it
+  renders — a `<label for="phone">` would then resolve to the (unfocusable)
+  host instead of the actual control. After first render, the element moves
+  its own `id` onto the rendered `<input>` and removes it from itself, so
+  `<label for="phone">` keeps working exactly as if `<lit-mask-input>`
+  weren't there.
+
+## Stencil
+
+Import the `<stencil-mask-input>` and `<stencil-mask-decimal>` custom
+elements from their own `mother-mask/stencil/mask-input` and
+`mother-mask/stencil/mask-decimal` entries — each registers its element as
+an import side effect:
+
+```html
+<script type="module">
+  import 'mother-mask/stencil/mask-input'
+  import 'mother-mask/stencil/mask-decimal'
+</script>
+
+<label for="phone">Phone</label>
+<stencil-mask-input id="phone" name="phone" mask="(99) 99999-9999" input-mode="tel"></stencil-mask-input>
+
+<label for="amount">Amount</label>
+<stencil-mask-decimal id="amount" name="amount"></stencil-mask-decimal>
+
+<script type="module">
+  const phone = document.getElementById('phone')
+  phone.addEventListener('value-change', (e) => console.log(e.detail))
+
+  const amount = document.getElementById('amount')
+  amount.options = { decimalPlaces: 2, prefix: '$', allowNegative: true }
+  amount.addEventListener('numeric-value-change', (e) => console.log(e.detail))
+</script>
+```
+
+Stencil components are fundamentally a compiled artifact — `@Component`,
+`@Prop`, `@Event`, and friends are erased by the Stencil compiler at build
+time and have no meaningful runtime implementation on their own, so (unlike
+every other integration in this README) `mother-mask/stencil` is **not**
+built by the same tsdown pipeline as the rest of this package; it's a
+separate Stencil project ([`stencil-src/`](../../packages/mother-mask/stencil-src))
+compiled with the Stencil CLI's `dist-custom-elements` output target and
+copied into `dist/stencil` as part of `bun run build`. Two consequences
+follow from that:
+
+- **No `mother-mask/stencil` barrel re-exporting core helpers or a
+  `@stencil/core` peer dependency.** The Stencil compiler bundles
+  `mother-mask`'s core logic directly into each component (there's no
+  shared module identity/cache with a page's own `mother-mask` import, the
+  way the other framework entries alias `export * from 'mother-mask'`), and
+  bundles its own tiny runtime too (`externalRuntime: false`) — so
+  `<stencil-mask-input>`/`<stencil-mask-decimal>` have **zero runtime
+  dependencies** at all, usable on any page. Import core helpers like
+  `formatDecimalValue` from `mother-mask` directly.
+- Each component is its own tree-shakeable module (`mask-input`,
+  `mask-decimal`) rather than one combined entry, matching how Stencil's
+  own `dist-custom-elements` output is meant to be consumed.
+
+- `<stencil-mask-input>` accepts `mask`, `options` (JS property only), and
+  a curated set of forwarded attributes: `name`, `placeholder`, `disabled`,
+  `readonly`, `required`, and `input-mode` (exposed as the `inputModeAttr`
+  JS property — not `inputMode`, since this class is a real `HTMLElement`
+  at runtime and already declares its own incompatible `inputMode`). It
+  emits `value-change` (`detail: string`). `<stencil-mask-decimal>` accepts
+  `options` and emits both `value-change` and `numeric-value-change`
+  (`detail: number`), and always sets `inputmode="decimal"`.
+- The ref to the native `<input>` is grabbed via `render()`'s `ref`
+  callback — the only point Stencil hands back a real DOM node. Binding
+  itself happens in `connectedCallback` when that ref is already available
+  (true on every *re*-connection — the element was moved or re-appended —
+  since the ref from the first render still exists) and otherwise in
+  `componentDidLoad`, which fires exactly once, right after the very first
+  render actually creates that ref. Either way, both only ever run in the
+  browser — Stencil's SSR/hydration path never calls them, so there's no
+  `typeof window` guard to write. `@Watch('mask')`/`@Watch('options')`/
+  `@Watch('value')` reactively rebind; `disconnectedCallback` always
+  disposes.
+- Same `id`-transfer behavior as Lit's elements (both render into light
+  DOM): after first render, a host `id` moves onto the rendered `<input>`
+  so `<label for>` keeps resolving to the actual control.
+- Because raw `.tsx` Stencil source can't run outside the Stencil compiler,
+  [`tests/stencil.test.ts`](../../packages/mother-mask/tests/stencil.test.ts)
+  exercises the *built* `dist/stencil` output directly rather than the
+  source — run `bun run build` before `bun run test` if you're working on
+  this entry locally.
+
+## Alpine.js
+
+Register the `x-mask` directive from the separate `mother-mask/alpine`
+entry with `Alpine.plugin(...)`:
+
+```html
+<script type="module">
+  import Alpine from 'alpinejs'
+  import motherMaskPlugin from 'mother-mask/alpine'
+
+  Alpine.plugin(motherMaskPlugin)
+  Alpine.start()
+</script>
+
+<div x-data="{ phone: '', amount: '' }">
+  <label for="phone">Phone</label>
+  <input
+    id="phone"
+    name="phone"
+    inputmode="tel"
+    x-mask="{ mask: '(99) 99999-9999', value: phone }"
+    x-on:mask-change="phone = $event.detail"
+  />
+
+  <label for="amount">Amount</label>
+  <input
+    id="amount"
+    name="amount"
+    x-mask.decimal="{ options: { decimalPlaces: 2, prefix: '$', allowNegative: true }, value: amount }"
+    x-on:mask-change="amount = $event.detail"
+  />
+</div>
+```
+
+`mother-mask/alpine` re-exports every core function, class, and type as well
+as `motherMaskPlugin` (both a named export and the module's default export,
+matching Alpine's own documented plugin convention — `export default
+function (Alpine) { ... }`). Its core exports are aliases to `mother-mask`,
+sharing the same implementation and caches. The core ESM, CommonJS, and UMD
+builds remain independent of Alpine. Alpine is an optional peer dependency
+required only when importing `mother-mask/alpine`; the supported version
+range is `^3.0.0`. Alpine is not bundled.
+
+- `x-mask` takes an expression evaluating to `{ mask, options?, value? }`;
+  `x-mask.decimal` takes `{ options?, value? }`. Reading a reactive value
+  inside that expression (e.g. `value: phone`) is what makes it reactive —
+  Alpine's own `effect()` re-runs the directive whenever a dependency read
+  while evaluating the expression changes, rebinding only if the mask,
+  options, or an externally-set value actually changed.
+- **Two-way binding goes through a DOM event, not `x-model`.** The
+  directive dispatches `mask-change` (`detail: string`, and for
+  `.decimal`, also `mask-numeric-change` with `detail: number`) — bind
+  those with `x-on:mask-change`, as shown above. Combining `x-mask` with
+  `x-model` on the same element isn't supported: both would independently
+  react to the native `input` event with no defined ordering between them,
+  and could fight over the field's live value on every keystroke.
+- The directive's callback runs when Alpine walks the live DOM tree —
+  Alpine has no server-rendering step, so there's no `typeof window` guard
+  to write. `cleanup()` guarantees `dispose()` runs exactly once, both
+  before every rebind and when the element is removed from the DOM.
+
+## Native Web Components
+
+Import the `<mm-mask-input>` and `<mm-mask-decimal>` custom elements from
+the separate `mother-mask/web-components` entry — no framework at all,
+plain `customElements`. Importing the module registers both elements as a
+side effect:
+
+```html
+<script type="module">
+  import 'mother-mask/web-components'
+</script>
+
+<label for="phone">Phone</label>
+<mm-mask-input id="phone" name="phone" mask="(99) 99999-9999" input-mode="tel"></mm-mask-input>
+
+<label for="amount">Amount</label>
+<mm-mask-decimal id="amount" name="amount"></mm-mask-decimal>
+
+<script type="module">
+  const phone = document.getElementById('phone')
+  phone.addEventListener('value-change', (e) => console.log(e.detail))
+
+  const amount = document.getElementById('amount')
+  amount.options = { decimalPlaces: 2, prefix: '$', allowNegative: true }
+  amount.addEventListener('numeric-value-change', (e) => console.log(e.detail))
+</script>
+```
+
+`mother-mask/web-components` re-exports every core function, class, and
+type as well as the `MotherMaskInputElement` and `MotherMaskDecimalElement`
+classes (for `instanceof` checks or subclassing). Its core exports are
+aliases to `mother-mask`, sharing the same implementation and caches. The
+core ESM, CommonJS, and UMD builds remain independent of this entry, and it
+has **zero runtime dependencies** of its own — it's the one integration in
+this README usable with no framework, no build step, and no peer
+dependency at all; drop the `<script type="module">` tag on any page.
+
+- Both elements render into **light DOM** (a single `<input>` appended as a
+  real child, no shadow root), so a page's own `<label for>` and global CSS
+  reach it directly, the same as Lit's and Stencil's entries.
+- `<mm-mask-input>` accepts `mask` and `options` as either a plain
+  attribute (`mask`, string patterns only) or a JS property (any
+  `MaskPattern`, including arrays/functions, plus `options` objects, which
+  can't be expressed as attributes at all). A curated set of other
+  attributes forward to the inner `<input>`: `name`, `placeholder`,
+  `disabled`, `readonly`, `required`, `input-mode`, and `autocomplete`. It
+  emits `value-change` (`detail: string`). `<mm-mask-decimal>` accepts
+  `options` (JS property only) and emits both `value-change` and
+  `numeric-value-change` (`detail: number`), and always sets
+  `inputmode="decimal"`.
+- Binding happens in `connectedCallback` and disposes in
+  `disconnectedCallback` — both fire only when a real document actually
+  connects/disconnects the element, so there's no `typeof window` guard to
+  write. `attributeChangedCallback` and the `mask`/`options`/`value`
+  property setters reactively rebind; an echo of the element's own
+  `value-change` event is ignored.
+- Same `id`-transfer behavior as Lit's and Stencil's elements: after
+  connecting, a host `id` moves onto the rendered `<input>` so
+  `<label for>` keeps resolving to the actual control.
+
+## Qwik
+
+Import the `InputMask` and `InputDecimal` components from the separate
+`mother-mask/qwik` entry:
+
+```tsx
+import { component$, useSignal } from '@builder.io/qwik'
+import { InputMask, InputDecimal, formatDecimalValue } from 'mother-mask/qwik'
+
+// Keep option objects outside the component so they stay stable across renders.
+const currency = { decimalPlaces: 2, prefix: '$', allowNegative: true }
+
+export default component$(() => {
+  const phone = useSignal('')
+  const amount = useSignal('')
+
+  return (
+    <>
+      <label for="phone">Phone</label>
+      <InputMask
+        id="phone"
+        name="phone"
+        mask="(99) 99999-9999"
+        inputMode="tel"
+        value={phone.value}
+        onValueChange$={(v) => (phone.value = v)}
+      />
+
+      <label for="amount">Amount</label>
+      <InputDecimal
+        id="amount"
+        name="amount"
+        options={currency}
+        value={amount.value}
+        onValueChange$={(v) => (amount.value = v)}
+      />
+
+      <button type="button" onClick$={() => (amount.value = formatDecimalValue(1234.5, currency))}>
+        Set amount
+      </button>
+    </>
+  )
+})
+```
+
+`mother-mask/qwik` re-exports every core function, class, and type as well
+as `InputMask`, `InputDecimal`, `InputMaskProps`, and `InputDecimalProps`.
+The core ESM, CommonJS, and UMD builds remain independent of Qwik. Qwik is
+an optional peer dependency required only when importing `mother-mask/qwik`;
+the supported version range is `^1.0.0`. Qwik's own components are not
+bundled here — see below for why this entry, alone among the ones in this
+README, ships close to raw source.
+
+- Both components accept `value` and `onValueChange$` (a QRL — inline
+  arrow functions work; the Qwik Optimizer converts them for you). `mask`
+  and `options` work the same as the React version.
+- Binding happens in `useVisibleTask$`, a hook Qwik only ever runs on the
+  client once the element is visible — Qwik's SSR renderer never executes
+  it, so this is safe to render on the server with no `typeof window`
+  guard. `track()` makes it reactive: it reruns whenever `mask`, `options`,
+  or `value` change, rebinding only if the mask, options, or an
+  externally-set value actually changed (an echo of the component's own
+  `onValueChange$` is ignored). `cleanup()` — called both before every
+  re-run and when the component unmounts — guarantees `dispose()` runs
+  exactly once per binding.
+- `InputDecimal` defaults to `inputMode="decimal"` and reports
+  `onValueChange$(value, numericValue)`.
+
+**Why this entry isn't built like the others.** `component$`, `useVisibleTask$`,
+and every other `$`-suffixed Qwik API throw at runtime ("Optimizer should
+replace all usages of $() ...") unless the Qwik Optimizer has already
+processed them — there's no plain-JS fallback the way Lit's or Solid's
+reactivity primitives have. So `mother-mask/qwik` is built with Vite's
+documented ["library" mode](https://qwik.dev/docs/advanced/library/)
+(`qwikVite()` + `build.lib`, see `qwik.vite.config.mjs`) rather than
+tsdown, and the output (`dist/qwik/index.qwik.mjs`) deliberately keeps
+`component$`/`useVisibleTask$` **unprocessed** — exactly like Qwik's own
+documented component-library recipe. A consuming Qwik app's own build
+(which always runs through `qwikVite` too) is what finishes optimizing
+these calls into lazy-loaded segments, scoped to that app. This also means
+`mother-mask/qwik` has no shared module identity/cache with a page's own
+`mother-mask` import, unlike every other framework entry's
+`export * from 'mother-mask'` aliasing.
+- Tests for this entry run under a separate config
+  ([`vitest.qwik.config.ts`](../../packages/mother-mask/vitest.qwik.config.ts),
+  `bun run test:qwik`) — Qwik's own `@builder.io/qwik/testing` needs the
+  `node` environment, not `jsdom` (the two DOM implementations collide),
+  and `qwikVite` as a plugin isn't scoped to its own `srcDir`, so adding it
+  to the main config broke every other framework's unrelated JSX.
+
+## Inferno
+
+Import the `InputMask` and `InputDecimal` class components from the
+separate `mother-mask/inferno` entry:
+
+```js
+import { Component, render } from 'inferno'
+import { InputMask, InputDecimal, formatDecimalValue } from 'mother-mask/inferno'
+
+// Keep option objects outside the component so they stay stable across renders.
+const currency = { decimalPlaces: 2, prefix: '$', allowNegative: true }
+
+class App extends Component {
+  state = { phone: '', amount: '' }
+
+  render() {
+    return (
+      <>
+        <label for="phone">Phone</label>
+        <InputMask
+          id="phone"
+          name="phone"
+          mask="(99) 99999-9999"
+          inputMode="tel"
+          value={this.state.phone}
+          onValueChange={(phone) => this.setState({ phone })}
+        />
+
+        <label for="amount">Amount</label>
+        <InputDecimal
+          id="amount"
+          name="amount"
+          options={currency}
+          value={this.state.amount}
+          onValueChange={(amount) => this.setState({ amount })}
+        />
+
+        <button type="button" onClick={() => this.setState({ amount: formatDecimalValue(1234.5, currency) })}>
+          Set amount
+        </button>
+      </>
+    )
+  }
+}
+
+render(<App />, document.getElementById('root'))
+```
+
+`mother-mask/inferno` re-exports every core function, class, and type as
+well as `InputMask`, `InputDecimal`, `InputMaskProps`, and
+`InputDecimalProps`. Its core exports are aliases to `mother-mask`, sharing
+the same implementation and caches. The core ESM, CommonJS, and UMD builds
+remain independent of this entry. Inferno is an optional peer dependency
+required only when importing `mother-mask/inferno`; the supported version
+range is `^9.0.0`.
+
+- Both components accept `value` and `onValueChange`. `mask` and `options`
+  work the same as the React version; other props are typed against
+  Inferno's own `InputHTMLAttributes<HTMLInputElement>`, so `name`,
+  `placeholder`, `inputMode`, and friends all get real autocomplete and
+  type-checking. `InputDecimal` always sets `inputmode="decimal"`
+  regardless (its own `inputMode` prop is omitted from its type, since
+  setting it wouldn't do anything).
+- Binding happens in `componentDidMount` and disposes in
+  `componentWillUnmount` — Inferno's server-rendering path
+  (`inferno-server`) never calls either, so this is safe to render on the
+  server with no `typeof window` guard. `componentDidUpdate` reactively
+  rebinds whenever `mask`/`options` change or `value` is set externally; an
+  echo of a component's own `onValueChange` is ignored.
+- `InputDecimal` reports `onValueChange(value, numericValue)`.
+- This entry ships without JSX: Inferno's own JSX support needs
+  `ts-plugin-inferno`/`babel-plugin-inferno` for correct compile-time vnode
+  flags, which isn't worth the extra toolchain for wrapping one leaf
+  `<input>` — internally each component calls Inferno's `createVNode`
+  directly through a small `h()` helper. This only affects the library's
+  own source; consuming apps keep using their own JSX/Babel/TypeScript
+  setup exactly as shown above.
+
+## Octane
+
+Import the `InputMask` and `InputDecimal` function components from the
+separate `mother-mask/octane` entry:
+
+```tsx
+/** @jsxImportSource octane */
+import { useState } from 'octane'
+import { InputMask, InputDecimal, formatDecimalValue } from 'mother-mask/octane'
+
+// Keep option objects outside the component so they stay stable across renders.
+const currency = { decimalPlaces: 2, prefix: '$', allowNegative: true }
+
+export function Checkout() {
+  const [phone, setPhone] = useState('')
+  const [amount, setAmount] = useState('')
+
+  return (
+    <>
+      <label for="phone">Phone</label>
+      <InputMask
+        id="phone"
+        name="phone"
+        mask="(99) 99999-9999"
+        inputMode="tel"
+        value={phone}
+        onValueChange={setPhone}
+      />
+
+      <label for="amount">Amount</label>
+      <InputDecimal id="amount" name="amount" options={currency} value={amount} onValueChange={setAmount} />
+
+      <button onClick={() => setAmount(formatDecimalValue(1234.5, currency))}>Set amount</button>
+    </>
+  )
+}
+```
+
+`mother-mask/octane` re-exports every core function, class, and type as
+well as `InputMask`, `InputDecimal`, `InputMaskProps`, and
+`InputDecimalProps`. Its core exports are aliases to `mother-mask`, sharing
+the same implementation and caches. Octane is an optional peer dependency
+required only when importing `mother-mask/octane`; the supported version
+range is `^0.2.0`.
+
+- Both components accept `value` and `onValueChange`. `mask` and `options`
+  work the same as the React version. Access to the underlying `<input>` is
+  through `inputRef` rather than `ref` — see **why this entry ships raw**
+  below for why a plain `ref` would collide.
+- Binding happens in `useLayoutEffect`, a hook Octane's server renderer
+  never executes — this is safe to render on the server with no
+  `typeof window` guard. It reconciles on every commit, rebinding only if
+  the mask, options, or an externally-set value actually changed (an echo
+  of this component's own `onValueChange` is ignored). The registered
+  cleanup guarantees `dispose()` runs exactly once per binding, including
+  on unmount.
+- `InputDecimal` defaults to `inputMode="decimal"` and reports
+  `onValueChange(value, numericValue)`.
+
+**Why this entry ships raw, unlike every other one in this README.**
+Octane compiles function components down to direct DOM-update code keyed to
+compiler-assigned hook slots — there's no virtual DOM diff at runtime, so
+`useState`/`useRef`/`useLayoutEffect` only work correctly once the Octane
+compiler has processed the file. Octane's own publishing guidance for
+component libraries is therefore to distribute source, not a pre-built
+bundle, and let the *consuming app's* own Octane toolchain (Vite, Rspack,
+or Rsbuild, all via an official Octane plugin) compile it — that plugin
+already knows to look inside `node_modules` for Octane-owned files, so no
+extra bundler configuration is needed on the consumer's side. Accordingly,
+`"./octane"` in this package's `exports` map points straight at
+`src/octane/index.ts` (and `src/octane/*.tsx`) rather than at anything in
+`dist/`, and this is the one entry in this README with no `tsdown` build
+step of its own. The `/** @jsxImportSource octane */` pragma at the top of
+each `.tsx` file is what opts a plain-TSX file into Octane's compiler (its
+Vite/Rspack plugins otherwise only claim `.tsrx` files by default).
+Tests for this entry run under a separate config
+([`vitest.octane.config.ts`](../../packages/mother-mask/vitest.octane.config.ts),
+`bun run test:octane`) with the Octane Vite plugin scoped to just that one
+test file, mirroring how Qwik's tests are isolated.
+
+## Mithril.js
+
+Import the `InputMask` and `InputDecimal` closure components from the
+separate `mother-mask/mithril` entry:
+
+```js
+import m from 'mithril'
+import { InputMask, InputDecimal, formatDecimalValue } from 'mother-mask/mithril'
+
+// Keep option objects outside the view so they stay stable across redraws.
+const currency = { decimalPlaces: 2, prefix: '$', allowNegative: true }
+
+let phone = ''
+let amount = ''
+
+const Checkout = {
+  view: () =>
+    m('div', [
+      m('label', { for: 'phone' }, 'Phone'),
+      m(InputMask, {
+        id: 'phone',
+        name: 'phone',
+        mask: '(99) 99999-9999',
+        inputmode: 'tel',
+        value: phone,
+        onValueChange: (v) => { phone = v },
+      }),
+
+      m('label', { for: 'amount' }, 'Amount'),
+      m(InputDecimal, {
+        id: 'amount',
+        name: 'amount',
+        options: currency,
+        value: amount,
+        onValueChange: (v) => { amount = v },
+      }),
+
+      m('button', { onclick: () => { amount = formatDecimalValue(1234.5, currency) } }, 'Set amount'),
+    ]),
+}
+
+m.mount(document.body, Checkout)
+```
+
+`mother-mask/mithril` re-exports every core function, class, and type as
+well as `InputMask`, `InputDecimal`, `InputMaskAttrs`, and
+`InputDecimalAttrs`. Its core exports are aliases to `mother-mask`, sharing
+the same implementation and caches. The core ESM, CommonJS, and UMD builds
+remain independent of this entry. Mithril is an optional peer dependency
+required only when importing `mother-mask/mithril`; the supported version
+range is `^2.0.0`.
+
+- Both components accept `value` and `onValueChange`; `mask` and `options`
+  work the same as the React version.
+- Binding happens in `oncreate` and disposes in `onremove` — Mithril's
+  server-side rendering never calls either, so this is safe to render on
+  the server with no `typeof window` guard. `onupdate` reactively rebinds
+  whenever `mask`/`options` change or `value` is set externally, ignoring
+  an echo of this component's own `onValueChange`. Elements with any of
+  these three hooks are exempt from Mithril's DOM-node recycling, so the
+  same `<input>` is reused across redraws for as long as the vnode stays
+  mounted.
+- `value` is deliberately never forwarded as an `m('input', ...)`
+  attribute: Mithril's vdom diff would otherwise reassign `.value` from
+  `vnode.attrs` on every redraw, fighting the mask's own intermediate
+  edits — the wrapper controls the DOM value directly instead, exactly
+  like every other framework entry in this package.
+- `InputDecimal` always sets `inputmode="decimal"` and reports
+  `onValueChange(value, numericValue)`.
+
+## Ember.js
+
+Import the `maskInput` and `maskDecimal` modifiers from the separate
+`mother-mask/ember` entry:
+
+```hbs
+{{! app/components/checkout.gjs / .gts, or a classic template }}
+import { maskInput, maskDecimal } from 'mother-mask/ember';
+import { formatDecimalValue } from 'mother-mask';
+
+<template>
+  <label for="phone">Phone</label>
+  <input
+    id="phone"
+    name="phone"
+    {{maskInput "(99) 99999-9999" value=this.phone onValueChange=this.setPhone}}
+  />
+
+  <label for="amount">Amount</label>
+  <input
+    id="amount"
+    name="amount"
+    {{maskDecimal options=this.currency value=this.amount onValueChange=this.setAmount}}
+  />
+
+  <button type="button" {{on "click" this.setPreset}}>Set amount</button>
+</template>
+```
+
+```js
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { action } from '@ember/object';
+
+export default class Checkout extends Component {
+  // Keep option objects outside the class body's reactive graph so they
+  // stay stable across renders — a fresh object literal here would read as
+  // a changed `options` argument on every re-render.
+  currency = { decimalPlaces: 2, prefix: '$', allowNegative: true };
+
+  @tracked phone = '';
+  @tracked amount = '';
+
+  @action setPhone(value) { this.phone = value; }
+  @action setAmount(value) { this.amount = value; }
+  @action setPreset() { this.amount = formatDecimalValue(1234.5, this.currency); }
+}
+```
+
+`mother-mask/ember` re-exports every core function, class, and type as well
+as `maskInput`, `maskDecimal`, `maskInputModifier`, `maskDecimalModifier`,
+`MaskInputNamedArgs`, and `MaskDecimalNamedArgs`. Its core exports are
+aliases to `mother-mask`, sharing the same implementation and caches. The
+core ESM, CommonJS, and UMD builds remain independent of this entry.
+`ember-modifier` is an optional peer dependency required only when
+importing `mother-mask/ember`; the supported version range is `^4.0.0`
+(ships in every app generated by current `ember-cli`).
+
+- `maskInput` takes the mask as its one positional argument
+  (`{{maskInput "999-999" ...}}`); `maskDecimal` takes none. Both accept
+  `value` and `onValueChange` as named arguments, plus `options`.
+- Binding happens the first time the element the modifier is attached to is
+  inserted into the document, and only on the client: Ember's server-side
+  rendering (FastBoot) renders to a string and never attaches real elements
+  or runs modifiers, so there is no `typeof window` guard to write.
+  `ember-modifier`'s own auto-tracking reruns the modifier — tearing down
+  the previous binding first — whenever an argument it reads changes,
+  including the mask, `options`, or an externally-set `value`.
+- Unlike every other framework entry in this README, that teardown-then-
+  rerun happens unconditionally on **every** value change, including an
+  echo of the modifier's own `onValueChange` — there's no hook to skip it
+  from inside the modifier, since Ember has already torn down the previous
+  binding by the time it runs again. This stays visually seamless anyway:
+  formatting an already-formatted value is a no-op (the element's `.value`
+  is never reassigned, so the caret never moves), and removing/re-adding
+  the underlying event listeners doesn't touch focus or selection.
+- `maskDecimal` always sets `inputmode="decimal"` and reports
+  `onValueChange(value, numericValue)`.
+- The masking logic lives in `maskInputModifier`/`maskDecimalModifier` —
+  plain functions with the exact `(element, positional, named)` shape
+  `ember-modifier` calls a function-based modifier with, exported
+  separately from the `modifier()`-wrapped `maskInput`/`maskDecimal` so
+  this package's own test suite can exercise them directly against a plain
+  `HTMLInputElement`. That split exists because `ember-modifier` imports
+  Ember framework internals (`@ember/application`, `@ember/modifier`,
+  `@ember/destroyable`) that only resolve inside a real Ember app's build —
+  they aren't separately installable npm packages — so the wrapped
+  `modifier()` exports are verified at the type level (`tsc --noEmit`
+  against `ember-modifier`'s published types) rather than by a runtime
+  test in this repository.
+
+## Knockout.js
+
+Import the separate `mother-mask/knockout` entry once, for its side effect
+of registering the `mask` and `maskDecimal` binding handlers on
+`ko.bindingHandlers`:
+
+```js
+import ko from 'knockout'
+import 'mother-mask/knockout'
+import { formatDecimalValue } from 'mother-mask'
+
+// Keep option objects outside the view model's observables so they stay
+// stable across recomputes.
+const currency = { decimalPlaces: 2, prefix: '$', allowNegative: true }
+
+function CheckoutViewModel() {
+  this.phone = ko.observable('')
+  this.amount = ko.observable('')
+  this.setPreset = () => this.amount(formatDecimalValue(1234.5, currency))
+}
+
+ko.applyBindings(new CheckoutViewModel(), document.getElementById('app'))
+```
+
+```html
+<div id="app">
+  <label for="phone">Phone</label>
+  <input id="phone" name="phone"
+         data-bind="mask: { mask: '(99) 99999-9999', value: phone, onValueChange: phone }">
+
+  <label for="amount">Amount</label>
+  <input id="amount" name="amount"
+         data-bind="maskDecimal: { options: { decimalPlaces: 2, prefix: '$', allowNegative: true }, value: amount, onValueChange: amount }">
+
+  <button data-bind="click: setPreset">Set amount</button>
+</div>
+```
+
+`mother-mask/knockout` re-exports every core function, class, and type as
+well as `maskBindingHandler`, `maskDecimalBindingHandler`,
+`MaskBindingConfig`, and `MaskDecimalBindingConfig`. Its core exports are
+aliases to `mother-mask`, sharing the same implementation and caches. The
+core ESM, CommonJS, and UMD builds remain independent of this entry.
+Knockout is an optional peer dependency required only when importing
+`mother-mask/knockout`; the supported version range is `^3.5.0`.
+
+- Both bindings take a single object: `value` (a plain string, a Knockout
+  observable/computed, or any accessor `ko.unwrap` understands) and
+  `onValueChange`. `mask` and `options` work the same as the React version
+  — `onValueChange` in the example above is passed directly as the
+  observable itself (`phone`/`amount`), since calling an observable with an
+  argument is how Knockout writes to it.
+- `init` binds once the element is live; `update` re-runs whenever an
+  observable read while evaluating the binding's object literal changes —
+  Knockout's own dependency tracking — rebinding only if the mask, options,
+  or an externally-set value actually changed. An echo of the binding's own
+  `onValueChange` is ignored.
+- `ko.utils.domNodeDisposal.addDisposeCallback` guarantees `dispose()` runs
+  exactly once, both before every rebind and when Knockout removes the
+  element (`ko.removeNode`, `ko.cleanNode`, or an `if`/`foreach`/template
+  removing it). Knockout never touches real DOM nodes during any
+  server-side step, since it has none — `applyBindings` only ever runs
+  against a live document, so there is no `typeof window` guard to write.
+- `maskDecimal` always sets `inputmode="decimal"` and reports
+  `onValueChange(value, numericValue)`.
+- Binding state (the live `dispose()`, the last-emitted value, the last
+  mask/options) lives in a `WeakMap` keyed by the element, not in the
+  handler's own closure: `ko.bindingHandlers.mask` is one object shared
+  across every element that uses the binding, unlike a fresh-per-instance
+  factory (a React hook call, Vue's `setup()`, …) elsewhere in this package.
+
+## Riot.js
+
+Import the `maskInput` and `maskDecimal` pure-component factories from the
+separate `mother-mask/riot` entry:
+
+```js
+import { pure } from 'riot'
+import { maskInput, maskDecimal, formatDecimalValue } from 'mother-mask/riot'
+
+// Keep option objects module-level so they stay stable across updates.
+const currency = { decimalPlaces: 2, prefix: '$', allowNegative: true }
+
+let phone = ''
+const phoneField = pure(maskInput)({
+  props: {
+    mask: '(99) 99999-9999',
+    name: 'phone',
+    inputMode: 'tel',
+    autocomplete: 'tel',
+    value: phone,
+    onValueChange: (v) => (phone = v),
+  },
+})
+phoneField.mount(document.getElementById('phone'))
+
+let amount = ''
+const amountField = pure(maskDecimal)({
+  props: { options: currency, name: 'amount', value: amount, onValueChange: (v) => (amount = v) },
+})
+amountField.mount(document.getElementById('amount'))
+
+// Later, e.g. from a parent Riot component's onUpdated:
+amountField.update({ options: currency, value: formatDecimalValue(1234.5, currency) })
+```
+
+```html
+<label for="phone">Phone</label>
+<span id="phone"></span>
+
+<label for="amount">Amount</label>
+<span id="amount"></span>
+```
+
+`mother-mask/riot` re-exports every core function, class, and type as well
+as `maskInput`, `maskDecimal`, `MaskInputProps`, and `MaskDecimalProps`. Its
+core exports are aliases to `mother-mask`, sharing the same implementation
+and caches. The core ESM, CommonJS, and UMD builds remain independent of
+this entry. Riot is an optional peer dependency required only when
+importing `mother-mask/riot`; the supported version range is `^10.0.0`.
+
+- Both factories accept `value` and `onValueChange`; `mask` (on `maskInput`
+  only) and `options` work the same as the React version. A curated set of
+  other props forward as plain attributes: `name`, `placeholder`,
+  `inputMode` (rendered as `inputmode`, `maskInput` only — `maskDecimal`
+  always sets it to `"decimal"`), `autocomplete`, `disabled`, `readonly`,
+  and `required`.
+- Renders into light DOM: the `<input>` is appended as a real child of the
+  host element the component mounts onto, so a page's own `<label for>` and
+  global CSS reach it directly, the same as this package's Lit/Stencil/Web
+  Components entries. A host `id` is moved onto the `<input>` once, right
+  after mounting, for the same reason those entries do it.
+- `maskDecimal` always sets `inputmode="decimal"` and reports
+  `onValueChange(value, numericValue)`.
+
+**Why this entry uses Riot's `pure()` instead of a compiled `.riot`
+component.** `pure()` is Riot's own documented escape hatch for
+mounting non-Riot-templated content — third-party libraries, plain DOM —
+as a node in a Riot component tree, bypassing the `.riot`-file/compiler
+pipeline entirely; that's a direct fit here, since this wrapper's only job
+is to own one plain `<input>` imperatively, exactly like every other
+framework entry in this package. `riot.pure`'s own lifecycle names —
+`mount`/`update`/`unmount` — serve the same purpose as a full `.riot`
+component's `onMounted`/`onUnmounted`, with one difference worth calling
+out: `update()` isn't automatically re-invoked by reactive tracking the
+way `onUpdated` is on a full component. A parent must call this
+component's own `update(props)` explicitly (typically from its own
+`onUpdated`, or right after changing props) to reformat for a new
+`mask`/`options`/`value` — `sync()` still rebinds only if the mask,
+options, or an externally-set value actually changed, and still ignores an
+echo of this component's own `onValueChange`, exactly like every other
+framework entry. `mount`/`update`/`unmount` only ever run on the client:
+Riot has no built-in server-side renderer of its own, so there is no
+`typeof window` guard to write.
+
 ## Decimal Inputs
 
 Use `bindDecimal` for numbers, currency fields, and values where the integer part should grow freely.