tcy/docs/spec-ja.md

A JavaScript library for processing Japanese vertical text, handling Tate-Chu-Yoko and text orientation adjustments

# TCY プログラム仕様書

## 概要
TCYは、特定のHTML要素に対して特別なクラスを追加するライブラリです。このライブラリは、縦中横（Tate-Chu-Yoko）やテキストの向きを調整するために使用されます。

## 機能要件

### 処理対象
- **テキストノードのみを処理対象とする**:
  - HTMLのテキストノードのみを対象に変換処理を行い、タグノードはそのまま保持する。

### 処理対象の変換
- **特定の文字は特別なクラスでラップする**:
  - 数字のシーケンス（デフォルトは2桁）や感嘆符（疑問符）のシーケンスは、`<span class="tcy">`でラップする。
  - 特定の文字（例: 漢字や記号）は、`<span class="upright">`または`<span class="sideways">`でラップし、テキストの向きを調整する。

### 除外対象
- **特定のタグやクラス名を持つノードは除外する**:
  - 特定のタグ（例: `code`, `pre`, `math`, `svg`）や以下のクラス名を持つノードは、変換処理から除外する。
    - `tcy`: 縦中横の処理を行うためのクラス。
    - `upright`: 正立のテキストを示すためのクラス。
    - `sideways`: 横転のテキストを示すためのクラス。

- **メールアドレスは変換処理から除外する**:
  - メールアドレスは、変換処理の対象外とし、元の形式を保持する。

- **URLは変換処理から除外する**:
  - URLも変換処理の対象外とし、元の形式を保持する。

- **文字参照は変換処理から除外する**:
  - HTML文字参照（例: `&#x3042;`）は、変換処理の対象外とし、元の形式を保持する。

- **不正なHTMLの処理**:
  - 不正なHTMLが入力された場合、元のテキストを返し、エラーメッセージを出力する。

### オプションによる設定
- **`tcyDigit`オプション**:
  - `.tcy`クラスを追加する数字の最大桁数を設定できる。0に設定すると、`.tcy`クラスは追加されない。

- **`autoTextOrientation`オプション**:
  - `.upright`および`.sideways`クラスを追加するかどうかを設定できる。

### 親ノードのチェック
- **特定のタグやクラス名を持つノードは除外する**:
  - 特定のタグ（例: `code`, `pre`, `math`, `svg`）や上記のクラス名を持つノードは、変換処理から除外する。

### フィルタリング処理
- **URL、メールアドレス、文字参照を検出し、除外する**:
  - URL、メールアドレス、文字参照を正規表現で検出し、変換処理から除外するためのフィルタリング処理が必要。

## 主な機能
1. **テキスト変換**:
   - 数字のシーケンス（デフォルトは2桁）や感嘆符（疑問符）のシーケンスを`span.tcy`でラップします。
   - 各文字を`span.upright`または`span.sideways`でラップし、テキストの向きを調整します。
   - `tcyDigit`が0の場合、`.tcy`クラスは追加されません。

2. **HTMLの処理**:
   - HTML文字列を受け取り、ボディタグ内のテキストノードのみを変換します。
   - 不正なHTMLが入力された場合、元のテキストを返し、エラーメッセージをSTDERRに出力します。