ドロップゾーン

hc-dropzone は、ネイティブの <input type="file"> をドロップ面で飾ります。対話要素はあくまで input です: 包んでいる <label> がクリックでピッカーを開き、キーボードフォーカスは(視覚的に隠されているがフォーカス可能な)input に着地し、required / accept / field-errors の配線はいつもどおり input に付きます。ドラッグ& ドロップはポインタ専用のエンハンスメントです — ドロップは dataTransfer.files を input に代入して普通のバブリングする change を発火するため、下流のすべて(フォームシリアライズ、ファイルアップロードレシピ、バリデーション)からは、ファイルが「参照」で選ばれなかったことを見分けられません。

別名: ファイルドロップ、ドラッグ&ドロップアップロード。

基本の HTML

Drop a file here, or click to browse

<label class="hc-dropzone">
  <input class="hc-dropzone__input" type="file" name="doc">
  <span class="hc-dropzone__body">
    <span class="hc-dropzone__hint">Drop a file here, or click to browse</span>
    <span class="hc-dropzone__files"></span>
  </span>
</label>

.hc-dropzone__files は選択されたファイル名を表示します(ドロップでも参照でも、change のたびにビヘイビアが設定)。空のときは畳まれます。ヒントは作者が書くマークアップです — アプリの言語で書いてください。

ビヘイビア — `installDropzone()`

自動初期化の ./behaviors バンドルに含まれます。ファイルがゾーンの上をドラッグしている間は data-dragover を設定し(スタイルは下記)、ドロップはファイルを input に代入して — 単一ファイルの input は最初の 1 つだけを取り — バブリングする change を発火します。ファイルを運ばないドラッグ (テキスト選択)は無視され、input が disabled のゾーンも同様です。新しいイベントなし、ネットワークなし。

状態

状態	セレクタ	効果
ドラッグオーバー	`[data-dragover]`	実線のアクセント枠線(`--hc-dropzone-dragover-border`、`data-color` に追従)+ ティント背景。
キーボードフォーカス	`:focus-within`	標準のフォーカスリング(フォーカスは input 上)。
無効	`:has(> .hc-dropzone__input:disabled)`	ミュート表示、`cursor: not-allowed`。ビヘイビアはドロップを無視。
無効値	`:has(> .hc-dropzone__input[aria-invalid="true"])`	エラー枠線 — 他のコントロール同様、field-errors が設定。

サイズ

data-size="sm" は密なフォーム向けにパディングを詰めます。

Drop a file here, or click to browse

<label class="hc-dropzone" data-size="sm">
  <!-- …the same input and body… -->
</label>

htmx での利用

アップロードはファイルアップロードレシピの契約です: フォームの data-hx-encoding="multipart/form-data"、 installUploadProgress() によるライブ進捗、サーバのレスポンスの形はすべてそこにあります。ドロップゾーンはそのフォームに無変更で差し込めます — ドロップは「参照」と同じネイティブの change に行き着きます。

アクセシビリティ

キーボードや支援技術の利用者が必要とするものはすべてネイティブの input です: ラベルによる起動、フォーカス + Enter/Space、制約バリデーション、 field-errors からの aria-invalid / aria-describedby。
ドラッグ&ドロップはエンハンスメントです。すべての結果は「参照」経由で到達可能です。ARIA の発明はありません。
選択された名前はラベル内の見えるテキストです。それ以上の読み上げが必要なら、トーストと組み合わせてください。
非目標(v1): ペーストによるアップロード、ディレクトリのドロップ。

テーマ用トークン

component トークン(component.tokens.json)— すべて semantic トークンを参照するため、テーマ、アクセント(data-color)、ダークモードが自動で適用されます:

トークンパス	用途
`dropzone.bg` / `fg`	面の背景とテキスト。
`dropzone.border`	破線の枠線色。
`dropzone.hint`	ヒントテキストの色。
`dropzone.radius`	角丸。
`dropzone.padding-y` / `padding-x`	面のパディング(`data-size="sm"` が上書き)。
`dropzone.dragover-border` / `dragover-bg`	ドラッグオーバーのアクセント(`data-color` に追従)。
`dropzone.error-border`	無効値状態の枠線。

CSS 変数

生成される CSS 変数を表示

--hc-dropzone-bg | -fg | -border | -hint | -radius
--hc-dropzone-padding-y | -padding-x
--hc-dropzone-dragover-border | -dragover-bg
--hc-dropzone-error-border