コンテンツにスキップ
Hypermedia Components

インプット

hc-input は、標準の <input>・<select>・<textarea> 要素に適用 します。状態(disabled、aria-invalid)は、素の HTML とまったく 同じように要素自身に置かれます。

別名: 入力欄、テキストフィールド、テキストボックス。

基本の HTML

Section titled “基本の HTML”

サイズ

Section titled “サイズ”

data-size は sm、md(デフォルト)、lg を受け付けます。

状態

Section titled “状態”

aria-invalid="true" 属性は、枠線をエラー色に切り替え、フォーカス リングの色も変えます。メッセージとの組み合わせは hc-field で行って ください。

バリアント

Section titled “バリアント”

data-variant はバリデーションの合図として枠線を塗り替えます — success(緑)、warning(アンバー)、error(赤)。 セレクト、 デートピッカーほかの フォームフィールドと同じ語彙です。(textarea も同じ属性を取ります。)

エラーには data-variant="error" より aria-invalid="true" を選んで ください — 同じ枠線を塗ったうえで、状態を支援技術へ伝えます。 success / warning にはネイティブ属性がないため、バリアントが唯一の 表現手段です。コンポーネント横断の バリアントマトリクスを 参照。

数値フィールド

Section titled “数値フィールド”

入力はデフォルトで数字を等幅数字 (font-variant-numeric: tabular-nums)でレンダリングします — 数字を タイプする間のリズムが安定し、テーブルセルとの幅の一致も得られます。 テキスト内容には影響しません。金額系のフィールドには data-numeric が 値を末尾揃えにします — テーブルのセルと 同じ属性・同じ意味論で、論理値なので RTL では自動反転します:

<label class="hc-field">
  <span class="hc-field__label">Amount</span>
  <input class="hc-input" name="amount" data-numeric inputmode="decimal">
</label>

金額のグループ表示

Section titled “金額のグループ表示”

金額フィールドには data-hc-format="number" を付けます — 自動 インストールされる installFormat() ビヘイビアが、表示はグループ化、 ワイヤ上は生値のまま保ちます:

<label class="hc-field">
  <span class="hc-field__label">Amount</span>
  <div class="hc-input-group">
    <span class="hc-input-addon">¥</span>
    <input class="hc-input" name="amount" type="text" inputmode="numeric"
           data-numeric data-hc-format="number" value="1,234,567">
  </div>
</label>
  • blur で全角数字を正規化(１２３４ → 1,234、NFKC)して ロケールに応じてグループ化し、focus で生値に戻します — 編集中に 区切り文字と戦うことがなく、ビヘイビアはキャレット管理を一切 必要としません。
  • サーバーは常に生値を受け取ります(amount=1234567): ビヘイビアは formdata イベントでエントリリストを書き換えます。このイベントは htmx のリクエスト(new FormData(form))でもネイティブ送信でも 発火します。
  • data-decimals="2" は小数部の最小桁数までパディングします (表示のみ — 丸めは決して行いません)。data-locale はグループ化 ロケールを上書きします(既定は最も近い [lang])。
  • 初期表示からグループ化して見せたい場合は、サーバー側でグループ化 した値をレンダリングしてください — どちらでもワイヤ上は生値です。

type="number" ではなく type="text" + inputmode="numeric" を 使ってください。type="number" はグループ化された値を拒否し、先頭の ゼロを落とし、スクロールで値が変わります — いずれも金額には不適切 です。解析できない入力は入力されたまま残ります。検証者はあくまで サーバーです(field-errors)。

IME 正規化

Section titled “IME 正規化”

data-hc-normalize(自動インストールされる installNormalize())は 確定時にコントロールの値を書き換えます。IME 入力で残った全角文字が、 入力し直しなしで自己修正されます:

<input class="hc-input" name="sku" data-hc-normalize="ascii">
<input class="hc-input" name="furigana" data-hc-normalize="kana">
  • ascii — 全角 ASCII を半角へ(ＡＢ１２ → AB12、NFKC)、全角 スペースを半角スペースへ。ワイヤ形式が ASCII のフィールド(コード、 識別子、電話番号の数字)にだけ付けてください。
  • kana — 半角カナを全角へ(ﾀﾛｳ → タロウ)、ひらがなをカタカナへ (やまだ → ヤマダ)。フリガナ欄向けです。

書き換えはキャプチャ段階の change リスナーで走るため、 target.value を読む htmx トリガーは正規化後の値を見ます — change が発火しなかった値には formdata のセーフティネットが あります。

入力マスク

Section titled “入力マスク”

data-hc-mask(自動インストールされる installMask())は、固定形式の コードを入力と同時に整形します — 区切り文字は自動で現れ、全角入力も スロットを埋めます:

<input class="hc-input" name="postal" inputmode="numeric"
       placeholder="123-4567" pattern="\d{3}-\d{4}"
       data-hc-mask="postal-jp">


<input class="hc-input" name="product" placeholder="AB-12"
       data-hc-mask="AA-##">
  • トークン: # 数字、a 英字、A 英字(大文字化)、* 英数字。 それ以外の文字はリテラルです。postal-jp は ###-#### の別名です。 どのスロットにも合わない文字は捨てられます。
  • 1234 と打つと 123-4 になります(リテラルは遅延レンダリング)。 Backspace / Delete はリテラル列を飛び越えて必ず生文字を 1 つ消すため、 キャレットがハイフンで詰まりません。
  • 送信値は表示どおりの正準形です。data-hc-mask-submit="raw" を付けると ワイヤ上でリテラルを除去します(7 桁の郵便番号を保存するサーバー向け) — 金額のグループ表示と同じ formdata 機構です。
  • pattern + placeholder でマスクを鏡写しにしてください。ビヘイビアは 送信を止めないので、no-JS の送信も検証可能なままです。

可変長の形式(固定電話番号)には固定マスクがありません — そうした フィールドはマスクせず、サーバー側で正規化してください。

複数値の条件

Section titled “複数値の条件”

業務画面では一覧に対して問い合わせたい場面が多くあります — 表計算 から貼り付けた注文番号の列など。この用途には <textarea> が適して おり（どんな量の貼り付けも受けられます）、installMultiValue() が 各行を個別の値としてワイヤに載せます。

<textarea class="hc-input" name="f-buyer" data-hc-multi="lines">ZAB001000000
ZAB001000001
ZAB001000002</textarea>
?f-buyer=ZAB001000000&f-buyer=ZAB001000001&f-buyer=ZAB001000002

分割は formdata イベントで行います。installFormat() と同じ フックで、htmx の new FormData(form) もネイティブ送信も発火するため、 リスナー 1 つで両方の経路をカバーでき、ネットワークには一切触れません。 値はトリムされ重複は除かれます。data-hc-multi="commas" はカンマでも 分割します。すべて空になったコントロールはエントリを 1 つも送りません — 空の条件は条件ではないからです。

サーバーは改行を含む生の値も受理してください。JavaScript がなければ textarea はまさにそれを送信するので、サーバー側で分割すれば no-JS 経路が そのまま生きます。

一覧が URL に収まらなくなったときの扱いは datagrid-filter レシピ にあります — id で参照する保存済みの条件セットで、これは決して fail open してはなりません。

htmx での利用

Section titled “htmx での利用”

hc-input は他の入力と同様に htmx と組み合います。live-search レシピは、入力に応じてリクエストを送るよう入力欄を配線します。

<input
  class="hc-input"
  type="search"
  name="q"
  placeholder="Search"
  data-hx-get="/items"
  data-hx-trigger="input changed delay:300ms, search"
  data-hx-target="#results"
  data-hx-swap="innerHTML">

アクセシビリティ

Section titled “アクセシビリティ”
  • 入力には常にラベルを関連付けてください。入力の id に紐づく <label for="..."> を使うか、入力を <label> 要素で包みます。
  • バリデーションエラーでは、入力に aria-invalid="true" を設定し、 aria-describedby でメッセージを参照してください。
  • フォーカスのアウトラインを消さないでください。このコンポーネントは デフォルトのアウトラインを、--hc-color-focus-ring で駆動される 見える枠線 + box-shadow リングに置き換えています。
  • 入力が操作不能であるべきときはネイティブの disabled 属性を選んで ください。コントロールがフォーカス可能であり続けるべきときだけ aria-disabled="true" を使います。

テーマ用トークン

Section titled “テーマ用トークン”

component トークン(component.tokens.json):

トークンパス用途
input.height / input.padding-xデフォルトサイズ。
input.radius角丸。
input.bg / input.fgデフォルトの色。
input.border / input.focus-border通常時 / フォーカス時の枠線。
input.success-border / input.warning-border / input.error-borderdata-variant="success" / "warning" / aria-invalid の枠線。
input.placeholderプレースホルダーの色。
input.disabled-bg無効時の背景。
input.{sm,lg}.{height,padding-x,font-size}サイズ別の上書き。

CSS 変数

Section titled “CSS 変数”
生成される CSS 変数を表示
--hc-input-height
--hc-input-padding-x
--hc-input-radius
--hc-input-font-size
--hc-input-bg | -fg | -border | -placeholder
--hc-input-focus-border
--hc-input-success-border | -warning-border | -error-border
--hc-input-disabled-bg
--hc-input-sm-height | -sm-padding-x | -sm-font-size
--hc-input-lg-height | -lg-padding-x | -lg-font-size
--hc-color-focus-ring
--hc-color-error

関連

Section titled “関連”

レシピでの利用: 自動保存 · ライブ検索 · 郵便番号住所補完 · 未保存ガード