DOC-0024 — Calendar 操作・HTML Functional Class

0. 文書情報

DOC ID: DOC-0024
TOC ID: TOC-0024
対象UI: UI-024
Component: #024 Calendar
Runtime Version: 1.0.15
HTML Functional Class: bf-calendar
DOC Version: 1.0.3
DOC Type: html-functional-class
Status: active

このDOCは #024 Calendar v1.0.15 の実Runtimeと実テスト画面だけを根拠に、通常操作、HTML Functional Class、Property、Public API、Security、#022/#040/#002との責務境界を説明します。存在しない commit / invoke / OUT は追加しません。

1. Calendarの役割

CalendarはPicker等から再利用するPrimitive UIの共通日付選択基盤です。月表示、月移動、日付セル、選択日、今日、min / max / step、Theme、開始曜日、Annotation、親依存または単体サイズ/配置を扱い、選択結果は bone-calendar:select Eventまたは onSelect callbackで呼び出し元へ返します。

Calendar自身は入力コンポーネントの編集中/確定済み状態を所有せず、commit、invoke、OUT、Delivery Channel、WAIT/FIFO/BLOCKEDを持ちません。

2. HTML Functional Class `bf-calendar`

2.1 最小利用

<div class="bf-calendar"></div>

bf-calendar を付けた要素をhostとして #024 Calendar Runtimeを子要素へmountします。通常利用Classはこの1個だけです。inheritParent=true の場合、生成された .bone-calendar から見た直接の親はこの bf-calendar hostになるため、同期させたい親外観はhostへ設定します。24個のPublic API名をClassへ変換する旧方式は使用しません。

2.2 設定付き利用

<div class="bf-calendar"
     data-value="2026-08-10"
     data-min="2026-08-01"
     data-max="2027-08-10"
     data-step="1"
     data-theme="dark"
     data-icon-visual="emoji"
     data-disabled="false"
     data-show-today-button="true"
     data-week-start="auto"
     data-locale="ja-JP"
     data-annotations='{"2026-08-11":{"items":[{"kind":"holiday","label":"山の日","icon":true}]}}'
     data-show-tasks="true"
     data-inherit-parent="false"
     data-width="360"
     data-height="360"
     data-position="center"></div>

data-* は同名Runtime Propertyへ変換され、最終検証は BoneCalendar.create() が行います。無効なRuntime値はRuntime自身の CALENDAR_* Errorで拒否されます。

Annotationは data-annotations にJSON Object文字列を指定できます。JSONとして読めない場合はFunctional Class側で BF_CALENDAR_ANNOTATIONS_JSON_INVALID として拒否します。

2.3 設定 → 実表示サンプル

ここでは「何を設定すると、Calendarのどこがどう変わるか」を実例で確認します。実表示欄は画像やASCIIではなく、DOCを開いているページの BoneCalendar v1.0.15 と bf-calendar をその場でmountした実Runtimeです。コード例と実表示を1組で確認してください。

Sample 1 — `value`: 選択日を表示する

設定:

<div class="bf-calendar"
     data-value="2026-08-13"
     data-theme="dark"
     data-icon-visual="emoji"></div>

表示結果:

2026年8月を表示します。
13日のセルがAccent背景で選択状態になります。
Footerの値表示も 2026-08-13 になります。

[[BF-CALENDAR-SAMPLE:value]]

Sample 2 — `min` / `max` / `step`: 選択可能日を絞る

設定:

<div class="bf-calendar"
     data-value="2026-08-14"
     data-min="2026-08-10"
     data-max="2026-08-20"
     data-step="2"></div>

表示結果:

10日より前、20日より後は選択不可です。
step=2 の基準が10日なので、10 / 12 / 14 / 16 / 18 / 20日が選択可能です。
11 / 13 / 15 / 17 / 19日は範囲内でもstep条件により無効表示になります。

[[BF-CALENDAR-SAMPLE:range-step]]

Sample 3 — `theme`: 4 Themeの違い

theme はCalendar全体のbackground / surface / header / text / border / accentをまとめて切り替えます。

設定 default:

<div class="bf-calendar" data-theme="default" data-value="2026-08-13"></div>

表示結果: 標準Dark系Theme。Runtime Defaultです。

[[BF-CALENDAR-SAMPLE:theme-default]]

設定 dark:

<div class="bf-calendar" data-theme="dark" data-value="2026-08-13"></div>

表示結果: default より暗いbackground / surfaceになります。

[[BF-CALENDAR-SAMPLE:theme-dark]]

設定 light:

<div class="bf-calendar" data-theme="light" data-value="2026-08-13"></div>

表示結果: 白系surface + 濃色textのCalendarになります。

[[BF-CALENDAR-SAMPLE:theme-light]]

設定 neon:

<div class="bf-calendar" data-theme="neon" data-value="2026-08-13"></div>

表示結果: シアンAccentを中心としたNeon Themeになります。これは#022 Hover Border EffectのON/OFFとは別です。

[[BF-CALENDAR-SAMPLE:theme-neon]]

Sample 4 — `weekStart`: 曜日の左端を変える

月曜開始:

<div class="bf-calendar"
     data-week-start="monday"
     data-locale="ja-JP"></div>

表示結果: 曜日列の左端が月曜日になります。

[[BF-CALENDAR-SAMPLE:week-monday]]

日曜開始:

<div class="bf-calendar"
     data-week-start="sunday"
     data-locale="ja-JP"></div>

表示結果: 曜日列の左端が日曜日になります。

[[BF-CALENDAR-SAMPLE:week-sunday]]

Sample 5 — `annotations` / `iconVisual=emoji`: 祝日・休日・記念日・Task

設定:

<div class="bf-calendar"
     data-value="2026-08-13"
     data-icon-visual="emoji"
     data-show-tasks="true"
     data-annotations='{
       "2026-08-10":{"items":[{"kind":"task","label":"10:00 定例会議"}]},
       "2026-08-11":{"items":[{"kind":"holiday","label":"山の日","icon":true}]},
       "2026-08-12":{"items":[{"kind":"customHoliday","label":"夏季休業","icon":true}]},
       "2026-08-15":{"items":[{"kind":"anniversary","label":"創立記念日","icon":true}]}
     }'></div>

表示結果:

11日 holiday → 🎌
12日 customHoliday → 🏖️
15日 anniversary → ⭐
10日 task → 日付セル下部にtask dot、Hover/FocusでTooltip
祝日の 🎌 は通常Annotation iconより大きい16px表示です。

[[BF-CALENDAR-SAMPLE:annotations]]

Sample 6 — `showTasks=false`: Taskだけ消す

設定:

<div class="bf-calendar"
     data-show-tasks="false"
     data-icon-visual="emoji"
     data-annotations='{
       "2026-08-10":{"items":[{"kind":"task","label":"10:00 定例会議"}]},
       "2026-08-11":{"items":[{"kind":"holiday","label":"山の日","icon":true}]}
     }'></div>

表示結果:

Taskのdot / Tooltip項目だけ非表示になります。
祝日の 🎌 は残ります。

[[BF-CALENDAR-SAMPLE:tasks-off]]

Sample 7 — `disabled=true` + `showTodayButton=false`

設定:

<div class="bf-calendar"
     data-disabled="true"
     data-show-today-button="false"
     data-value="2026-08-13"></div>

表示結果:

Calendar全体がdisabled状態になります。
日付セル・前月/次月操作は選択操作できません。
Footerの「今日」ボタン自体が非表示になります。

[[BF-CALENDAR-SAMPLE:disabled]]

Sample 8 — `width` / `height` / `position=bottom-right`

設定:

<div class="bf-calendar"
     data-width="260"
     data-height="300"
     data-position="bottom-right"></div>

表示結果:

Calendar本体は260×300pxになります。
親領域内の右下へ配置されます。
inheritParent=true にするとこの単体サイズ・Position指定より親吸着が優先されます。

[[BF-CALENDAR-SAMPLE:position-bottom-right]]

Sample 9 — `inheritParent=true`: 親へ100%吸着

設定:

<div class="calendar-host">
  <div class="bf-calendar"
       data-inherit-parent="true"></div>
</div>

表示結果:

Calendarが直接親の幅・高さへ100%吸着します。
親のbackground / color / border / radius等を syncParentStyle() で同期します。
width / height / position の単体指定は視覚上優先されません。

[[BF-CALENDAR-SAMPLE:inherit-parent]]

Sample 10 — #022 Hover Border Effectを日付セルへ付ける

設定:

<div class="bf-calendar"
     data-hover-enabled="true"
     data-hover-effect="neon"
     data-hover-color="#35f4ff"
     data-hover-direction="clockwise"
     data-hover-speed="normal"></div>

表示結果:

CalendarのThemeを変えるのではなく、各日付セルのmouseover時だけ#022の枠Effectが動きます。
月移動・日付選択でセルが再描画された後も新セルへ再attachします。
#022が未読込ならCalendar自体を偽Effectで代替せず、依存Errorになります。

[[BF-CALENDAR-SAMPLE:hover-neon]]

2.4 18 Property「設定 → 表示結果」早見

value — 指定日が選択色になり、表示月とFooter値の基準になります。
min — 指定日より前の日付セルが選択不可表示になります。
max — 指定日より後の日付セルが選択不可表示になります。
step — 基準日からN日刻み以外の日付セルが選択不可表示になります。
theme — Calendar全体の背景・surface・文字・枠・Accent配色が変わります。
iconVisual — fontawesome は内蔵SVG、emoji は前後月とAnnotationを絵文字表示します。祝日は 🎌 です。
disabled — true でCalendar全体が無効表示になり操作不可になります。
className — それ単体では見た目を変えません。生成rootへ任意Classを追加し、利用者CSSを当てるための入口です。
ariaLabel — 見た目は変わりません。Calendar rootの aria-label が変わります。
showTodayButton — false でFooterの「今日」ボタンが消えます。
weekStart — 曜日列と月Matrixの左端が月曜または日曜に変わります。
locale — weekStart=auto のとき開始曜日判定へ影響します。単独でThemeや日付数字の見た目は変えません。
annotations — 祝日/休日/記念日のセルicon、task dot、Tooltip内容が追加されます。
showTasks — false でtaskのdot / Tooltip項目だけ消え、祝日等は残ります。
inheritParent — true でCalendarが親へ100%吸着し、親外観同期が優先されます。
width — inheritParent=false 時のCalendar横幅が240～1200pxで変わります。
height — inheritParent=false 時のCalendar高さが280～1200pxで変わります。
position — inheritParent=false 時に親領域内の9方向配置が変わります。

3. Default Property 全18件 — 個別Reference

この章は一覧を圧縮せず、18 Propertyを1件ずつ説明します。Runtime Defaultは BoneCalendar.defaults、HTML属性は bf-calendar の data-* 変換契約を基準にしています。Property Editorで値を変更する場合も最終検証はRuntime側が行います。

3.1 `value`

目的: 現在の選択日を指定します。
型: string または null。
Runtime Default: null。未選択状態です。
Property Editor初期値: 2026-08-10。これはテスト画面のfixtureであり、Runtime Defaultとは別です。
許容形式: 厳密な YYYY-MM-DD。例: 2026-08-10。
無効値: 実在しない日付、2026-8-10 のような別形式、文字列以外。
無効時: CALENDAR_DATE_FORMAT_INVALID / CALENDAR_DATE_INVALID / CALENDAR_DATE_TYPE_INVALID。
HTML指定: data-value="2026-08-10"。省略時は null。
表示への影響: 選択セルを表示し、初期表示月の基準になります。
関連Property: min / max / step / disabled。これらの条件で選択不可なら設定できません。
関連API: setValue() / getValue() / validateDate() / isDateSelectable()。

3.2 `min`

目的: 選択可能な最小日を設定します。
型: string または null。
Runtime Default: null。下限なし。
Property Editor初期値: 2026-08-01。テスト用選択範囲の開始日です。
許容形式: 厳密な YYYY-MM-DD。
無効値: 不正日付、または max より後の日付。
無効時: 日付自体のError、または CALENDAR_MIN_MAX_INVALID。
HTML指定: data-min="2026-08-01"。
表示への影響: min より前の日付セルは選択不可になります。
関連Property: max / step / value。step の基準日は min がある場合は min です。
関連API: setOptions() / validateDate() / isDateSelectable()。

3.3 `max`

目的: 選択可能な最大日を設定します。
型: string または null。
Runtime Default: null。上限なし。
Property Editor初期値: 2027-08-10。テスト用選択範囲の終了日です。
許容形式: 厳密な YYYY-MM-DD。
無効値: 不正日付、または min より前の日付。
無効時: 日付自体のError、または CALENDAR_MIN_MAX_INVALID。
HTML指定: data-max="2027-08-10"。
表示への影響: max より後の日付セルは選択不可になります。
関連Property: min / step / value。
関連API: setOptions() / validateDate() / isDateSelectable()。

3.4 `step`

目的: 選択可能日をN日刻みに制限します。
型: 1～3650の整数、または文字列 any。
Runtime Default: 1。毎日選択できます。
Property Editor初期値: 1。
単位: 日。
許容値: any、1～3650の整数。
無効値: 0、負数、小数、3651以上、数値化できない値。
無効時: CALENDAR_STEP_INVALID。
HTML指定: data-step="2" または data-step="any"。
基準日: min があれば min、なければ 1970-01-01。
関連Property: min / max / value / disabled。
関連API: validateDate() / isDateSelectable()。

3.5 `theme`

目的: Calendar全体のThemeを選択します。
型: enum。
Runtime Default: default。
Property Editor初期値: default。
許容値: default / dark / light / neon の4値のみ。
無効値: cyber 等の未定義値。
無効時: CALENDAR_OPTION_ENUM_INVALID。
HTML指定: data-theme="neon"。
表示への影響: background / surface / header / text / border / accent / muted / Sunday / SaturdayのTheme変数を一括変更します。
関連Property: inheritParent=true の場合、親同期した色がTheme色より優先されます。
関連API: setOptions() / getOptions()。

3.6 `iconVisual`

目的: 前後月ナビとAnnotation iconの表現を選びます。
型: enum。
Runtime Default: fontawesome。
Property Editor初期値: emoji。今回のユーザー指定により、テスト画面では祝日を 🎌 で表示します。Runtime Default自体は互換性維持のため fontawesome のままです。
許容値: fontawesome / emoji の2値。
fontawesome: CDNを使わずRuntime内蔵SVGを表示します。
emoji: 前月 ◀️、次月 ▶️、祝日 🎌、カスタム休日 🏖️、記念日 ⭐ を表示します。
このDOCの祝日サンプル: 祝日は emoji を使用し、日付セルへ 🎌 を表示します。
無効値: cdn 等の未定義値。
無効時: CALENDAR_OPTION_ENUM_INVALID。
HTML指定: data-icon-visual="emoji"。
関連Property: annotations。taskは日付セルiconを持たないため、iconVisual の対象外です。
関連API: setOptions()。

3.7 `disabled`

目的: Calendar全体の操作可否を切り替えます。
型: boolean。
Runtime Default: false。
Property Editor初期値: 直接設定欄なし。テスト画面はRuntime Default false を使用します。
false: 前月/次月、日付選択、Today等を通常操作できます。
true: Calendar全体を無効化し、日付は選択不可になります。
HTML指定: data-disabled="true" / data-disabled="false"。
Functional Class無効値: true / false 以外は BF_CALENDAR_BOOLEAN_INVALID。
関連Property: value / min / max / step。
関連API: setOptions() / isDateSelectable() / validateDate()。

3.8 `className`

目的: Runtimeが生成する .bone-calendar rootへ追加Classを付与します。
型: string。
Runtime Default: 空文字 ""。
Property Editor初期値: 直接設定欄なし。
HTML指定: data-class-name="my-calendar"。
注意: 通常利用HTML Functional Class bf-calendar とは別物です。bf-calendar hostへ機能を付与し、className は生成後Runtime rootへ追加されます。
無効値: Runtimeは文字列化するため、独自意味を持つ値をDOC側で追加しません。
関連API: create() / setOptions()。

3.9 `ariaLabel`

目的: Calendar rootのアクセシブルネームを設定します。
型: string。
Runtime Default: Calendar。
Property Editor初期値: 直接設定欄なし。
HTML指定: data-aria-label="予約日カレンダー"。
空指定: Runtime Default Calendar へ戻ります。
表示への影響: 視覚文字ではなく aria-label へ反映されます。
関連API: create() / setOptions()。

3.10 `showTodayButton`

目的: Footerの「今日」ボタン表示を切り替えます。
型: boolean。
Runtime Default: true。
Property Editor初期値: 直接設定欄なし。テスト画面はRuntime Default true を使用します。
true: Todayボタンを表示します。
false: Todayボタンを非表示にします。
HTML指定: data-show-today-button="false"。
Functional Class無効値: true / false 以外は BF_CALENDAR_BOOLEAN_INVALID。
関連API: selectToday()。ボタン非表示でもPublic APIは別経路として存在します。

3.11 `weekStart`

目的: 曜日見出しと月Matrixの週開始曜日を指定します。
型: enum。
Runtime Default: auto。
Property Editor初期値: auto。
許容値: auto / monday / sunday。
auto: locale と実行環境から月曜/日曜を解決します。
monday: 常に月曜開始。
sunday: 常に日曜開始。
無効値: friday 等。
無効時: CALENDAR_OPTION_ENUM_INVALID。
HTML指定: data-week-start="monday"。
関連Property: locale。
関連API: resolveWeekStart() / monthMatrix() / setOptions()。

3.12 `locale`

目的: weekStart=auto の解決に使うLocaleを明示します。
型: string または null。
Runtime Default: null。実行環境を参照します。
Property Editor初期値: 直接設定欄なし。テスト画面の週開始は weekStart=auto の環境解決を確認します。
許容例: ja / ja-JP / en-US。
形式: 2～3文字の言語コード + 任意の - 区切りsubtag。
無効値: 規定形式に合わない文字列。
無効時: CALENDAR_LOCALE_INVALID。
HTML指定: data-locale="ja-JP"。
関連Property: weekStart。weekStart=monday/sunday のとき開始曜日はLocaleに左右されません。
関連API: resolveWeekStart() / monthMatrix()。

3.13 `annotations`

目的: 日付ごとの祝日・独自休日・記念日・taskを表示します。
型: 日付キーを持つplain object。
Runtime Default: 空Object {}。
Property Editor初期値: raw JSON入力欄はありません。テスト画面は2026–2027の祝日/予定fixtureをAnnotation機能確認用に読込みます。
日付キー: 厳密な YYYY-MM-DD。
Entry形式: item配列、または {items:[...]}。
kind全4値: holiday / customHoliday / anniversary / task。
HTML指定: data-annotations にJSON Object文字列を指定します。
HTML JSON不正: BF_CALENDAR_ANNOTATIONS_JSON_INVALID。
Runtime不正: CALENDAR_ANNOTATIONS_INVALID 等のAnnotation Error。
表示への影響: holiday/customHoliday/anniversaryは日付セルiconとTooltip、taskはTooltipとtask dotを表示します。
祝日表示: iconVisual=emoji のとき holiday は 🎌 を表示します。
関連Property: iconVisual / showTasks。
関連API: setAnnotations() / getAnnotations() / validateAnnotations() / annotationsForDate()。

3.14 `showTasks`

目的: task Annotationだけの表示可否を切り替えます。
型: boolean。
Runtime Default: true。
Property Editor初期値: true（チェックON）。
true: task Tooltip / dotを表示します。
false: taskを非表示にします。holiday/customHoliday/anniversaryは維持します。
HTML指定: data-show-tasks="false"。
Functional Class無効値: true / false 以外は BF_CALENDAR_BOOLEAN_INVALID。
関連Property: annotations。
関連API: setOptions()。

3.15 `inheritParent`

目的: 単体サイズ/配置ではなく、直接親へ100%吸着して親外観を同期します。
型: boolean。
Runtime Default: false。
Property Editor初期値: false（チェックOFF）。
false: width / height / position を使用します。
true: 幅/高さを100%にし、親のcomputed background/color/border/radius等を同期します。
HTML指定: data-inherit-parent="true"。
Functional Class無効値: true / false 以外は BF_CALENDAR_BOOLEAN_INVALID。
競合: true の間は単体 width / height / position の視覚的意味が失われます。
関連API: syncParentStyle() / setOptions()。

3.16 `width`

目的: inheritParent=false 時のCalendar単体幅を指定します。
型: integer。
Runtime Default: 360。
Property Editor初期値: 360。
単位: px。
範囲: 240～1200px。
無効値: 239以下、1201以上、小数、非数値。
Runtime無効時: CALENDAR_DIMENSION_INVALID。
Functional Classで数値化不可: BF_CALENDAR_NUMBER_INVALID。
HTML指定: data-width="480"。
競合: inheritParent=true では100%吸着が優先されます。
関連Property: height / position / inheritParent。

3.17 `height`

目的: inheritParent=false 時のCalendar単体高さを指定します。
型: integer。
Runtime Default: 360。
Property Editor初期値: 360。
単位: px。
範囲: 280～1200px。
無効値: 279以下、1201以上、小数、非数値。
Runtime無効時: CALENDAR_DIMENSION_INVALID。
Functional Classで数値化不可: BF_CALENDAR_NUMBER_INVALID。
HTML指定: data-height="420"。
競合: inheritParent=true では100%吸着が優先されます。
関連Property: width / position / inheritParent。

3.18 `position`

目的: inheritParent=false 時に親領域内の単体配置を指定します。
型: enum。
Runtime Default: center。
Property Editor初期値: center。
許容値: top-left / top-center / top-right / middle-left / center / middle-right / bottom-left / bottom-center / bottom-right の9値。
無効値: 上記以外。
無効時: CALENDAR_OPTION_ENUM_INVALID。
HTML指定: data-position="bottom-right"。
競合: inheritParent=true では親吸着が優先され、単体Positionの視覚的意味は失われます。
関連Property: width / height / inheritParent。
関連API: setOptions()。

4. 日付・範囲・step

`value`

YYYY-MM-DD の厳密なGregorian calendar dateです。例: 2026-08-10。空/nullは未選択を表します。実在しない日付、別形式、文字列以外は拒否されます。

`min` / `max`

どちらもnullまたは厳密な YYYY-MM-DD。min > max は CALENDAR_MIN_MAX_INVALID。日付セルの選択可否に使い、前月/次月および previousMonth() / nextMonth() の表示月も min / max の月境界を越えません。

`step`

any: step条件による制限なし。
1: 毎日。Runtime Default。
2～3650: N日刻み。

正整数範囲は1～3650、単位は日です。基準日は min があれば min、なければ 1970-01-01 です。0、負数、小数、3651以上は CALENDAR_STEP_INVALID。

5. Theme 全4値

`default`

意味/表示: 標準Dark系Theme。Runtime Defaultです。
HTML例: data-theme="default"。
関連: inheritParent=false ではTheme変数がそのまま表示に使われます。inheritParent=true では親から同期する外観が優先されます。

`dark`

意味/表示: default より暗いbackground/surfaceを使うDark Themeです。
Default: いいえ。
HTML例: data-theme="dark"。
関連: inheritParent=true では親同期外観が優先されます。

`light`

意味/表示: 白系backgroundと濃色textを使うLight Themeです。
Default: いいえ。
HTML例: data-theme="light"。
関連: inheritParent=true では親同期外観が優先されます。

`neon`

意味/表示: シアンAccentを中心にしたNeon Themeです。
Default: いいえ。
HTML例: data-theme="neon"。
関連: #022 Hover Border Effectとは別責務です。Themeをneonにしても#022 Effectは自動有効化されません。

Themeは default / dark / light / neon の4値のみです。Theme内部の色は#024 CalendarのTheme責務であり、個別Color Propertyへ分解しません。

6. 表示・基本操作Property

`iconVisual`

fontawesome: CDNを使わない内蔵SVG。Default。
emoji: 前後月ナビやAnnotationを絵文字表現へ切替。

`disabled`

false: 操作可能。Default。
true: Calendar全体を操作不可にします。

`className`

Runtimeが生成する .bone-calendar rootへ追加する任意Class名です。HTML Functional Class bf-calendar 自体とは別です。

`ariaLabel`

Calendar rootのアクセシブルネーム。Defaultは Calendar。

`showTodayButton`

true: 今日ボタンを表示。Default。
false: 今日ボタンを非表示。

7. `weekStart` と `locale`

許容値は auto / monday / sunday の3値です。

`weekStart=auto`

意味/表示: Runtime Default。開始曜日をLocale/環境から解決します。
解決: 明示 locale が ja / ja-* なら月曜、それ以外の明示Localeは日曜。locale 未指定時だけ実行環境の言語/Timezoneを参照し、日本環境を月曜開始にします。
HTML例: data-week-start="auto" data-locale="ja-JP"。
関連: locale が結果へ影響するのは auto のときだけです。

`weekStart=monday`

意味/表示: Localeに関係なく月曜日を左端の週開始にします。
Default: いいえ。
HTML例: data-week-start="monday"。
関連: locale を指定しても開始曜日は変わりません。

`weekStart=sunday`

意味/表示: Localeに関係なく日曜日を左端の週開始にします。
Default: いいえ。
HTML例: data-week-start="sunday"。
関連: locale を指定しても開始曜日は変わりません。

locale は ja-JP、en-US のような形式。無効形式は CALENDAR_LOCALE_INVALID。

8. Annotationと`showTasks`

Annotation kindは全4値です。

holiday: 祝日。セル内アイコン + Tooltip。iconVisual=emoji では 🎌。例: 山の日。
customHoliday: 独自休日。セル内アイコン + Tooltip。iconVisual=emoji では 🏖️。例: お盆休み。
anniversary: 記念日。セル内アイコン + Tooltip。iconVisual=emoji では ⭐。例: 創立記念日。
task: 予定。日付Tooltipとtask dot。hrefを任意指定可能。絵文字日付セルiconの対象ではありません。

{
  "2026-08-11": {"items":[{"kind":"holiday","label":"山の日","icon":true}]},
  "2026-08-10": {"items":[{"kind":"task","label":"10:00 定例会議","href":"/schedule/123"}]}
}

label は1～240文字。task.href は相対URLまたは http/https のみです。protocol-relative URL、制御文字、javascript: 等は拒否します。href はtask以外へ指定できません。

showTasks=true はtask Tooltip/dotを表示、false はtaskだけを非表示にし、holiday/customHoliday/anniversaryは維持します。

このDOCの祝日サンプルは iconVisual=emoji を使用します。holiday の日付セルiconは 🎌、customHoliday は 🏖️、anniversary は ⭐ です。Runtime Defaultの iconVisual 自体は互換性維持のため fontawesome のままです。

9. サイズ・親要素・9方向Position

`inheritParent`

false: width / height / position を使う単体表示。Default。
true: 親へ幅/高さ100%で吸着し、syncParentStyle() により親のbackground/color/border/radius等を同期します。

`width`

240～1200の整数px。Default 360px。

`height`

280～1200の整数px。Default 360px。

`position` 全9値

top-left: 親領域の左上。Defaultではありません。HTML例 data-position="top-left"。
top-center: 親領域の上中央。Defaultではありません。HTML例 data-position="top-center"。
top-right: 親領域の右上。Defaultではありません。HTML例 data-position="top-right"。
middle-left: 親領域の左中央。Defaultではありません。HTML例 data-position="middle-left"。
center: 親領域の中央。Runtime / Property Editor Default。HTML例 data-position="center"。
middle-right: 親領域の右中央。Defaultではありません。HTML例 data-position="middle-right"。
bottom-left: 親領域の左下。Defaultではありません。HTML例 data-position="bottom-left"。
bottom-center: 親領域の下中央。Defaultではありません。HTML例 data-position="bottom-center"。
bottom-right: 親領域の右下。Defaultではありません。HTML例 data-position="bottom-right"。

無効値は CALENDAR_OPTION_ENUM_INVALID。inheritParent=true の場合は親吸着が優先されるため、単体Positionの視覚的意味は失われます。

FITとの関係

#024 Calendarには独立した FIT Propertyはありません。親へ合わせる正式経路は inheritParent=true と syncParentStyle() です。

10. #022 Hover Border Effect連携

HTML Functional Classでは必要時だけ data-hover-enabled="true" を指定します。DefaultはOFFです。TriggerはCalendar日付セルのmouse over契約のため mouseover 固定です。

10.1 `trigger`

値: mouseover 固定。
Default: mouseover。
#024側で別Triggerを捏造しません。

10.2 `effect` 全5値

normal: 標準枠Effect。Functional Class Default。
neon: Neon発光枠。
spin: 回転枠。
cross: Cross系枠。
blink: Blink系枠。
HTML指定: data-hover-effect="neon" 等。

10.3 `direction` 全2値

clockwise: 時計回り。Default。
counterclockwise: 反時計回り。
HTML指定: data-hover-direction="counterclockwise"。

10.4 `speed` 全3値

slow: 低速。
normal: 標準。Default。
fast: 高速。
HTML指定: data-hover-speed="fast"。

10.5 `spinWidth`

#022契約範囲: 1～24px。
Functional Class Default: 2px。
HTML指定: data-hover-spin-width="2"。
#024は数値を#022へ渡し、Effect本体の最終契約は#022が所有します。

10.6 `spinGlow`

#022契約範囲: 0～40px。
Functional Class Default: 12px。
HTML指定: data-hover-spin-glow="12"。

10.7 `color`

種別: solid色。
Functional Class Default: #35f4ff。
HTML指定: data-hover-color="#35f4ff"。
色選択UIは#040 ColorPickerの責務です。

#024は日付セルを再描画します。そのため月移動や選択後は旧日付セルからEffectをdetachし、再描画後の .bone-calendar__day 全体へ再attachします。Functional Classも bone-calendar:select / bone-calendar:month-change 後に同じ再attachを行います。

#022本体のEffect実装を#024へ複製しません。

11. #040 ColorPickerとの責務分離

#024テスト画面の親背景色・親文字色・#022 Effect色は #040 ColorPicker Caller APIを使用し、Consumer側は solid のみ許可します。Native <input type="color"> を#024 Consumerの色選択UIとして追加しません。

#040は「色を選ぶ」責務、#024は「返された色を既存Propertyへ適用する」責務です。Calendar Theme内部色を#040へ委譲しません。

12. 操作

前月: Calendar Headerの前月ボタン、または previousMonth()。
次月: Calendar Headerの次月ボタン、または nextMonth()。
日付選択: 選択可能な日付セルをクリック。bone-calendar:select を発火。
今日: Todayボタンまたは selectToday()。
月表示の直接変更: setView()。
Property変更: setOptions()。Runtimeが再描画します。

日付選択結果を確定入力へcommitするか、別UIへOUTするかは呼び出し元の責務です。

13. Security

#024は日付、Locale、Annotation、URLをRuntimeで検証します。主な拒否条件:

日付型/形式/実在日付不正
min > max
enum不正
width/height範囲外
Annotationがplain objectでない
Annotation item不正
label空/240文字超
task以外へのhref
protocol-relative URL
javascript: 等の非http/https scheme
URL内制御文字

Accessor/Proxy等のuntrusted objectを「安全だと仮定して実行」する機能はDOCで追加しません。Runtimeが受け付ける型・検証結果をそのまま基準とします。

14. #002 Joint / WAIT / FIFO / BLOCKED

#024テスト画面の接続イメージは #002 Bone Joint の実判定/実描画を使用します。

ただし #024 Calendar Runtime自身は OUT とDelivery Channelを持ちません。そのため:

WAIT: N/A
FIFO: N/A
BLOCKED: N/A

WAIT/FIFO/BLOCKEDを見た目だけ追加することもしません。選択結果のDeliveryは呼び出し元Component側の責務です。

15. Public API 全24件

Public APIはHTML Functional Classとは別管理です。function APIはRuntime実体どおり24件です。

create(options) — Calendar DOMを生成します。
destroy(element) — Instanceを破棄します。
setOptions(element, patch) — Property差分を更新して再描画します。
getOptions(element) — 正規化済みPropertyを取得します。
setValue(element, value, source) — 選択日を設定します。
getValue(element) — 選択日を取得します。
setView(element, value) — 表示月を YYYY-MM または {year,month} で設定します。
getView(element) — 表示年月を取得します。
previousMonth(element) — 前月へ移動します。
nextMonth(element) — 次月へ移動します。
selectToday(element) — 今日を選択します。
setAnnotations(element, annotations) — Annotationを更新します。
getAnnotations(element) — Annotationを取得します。
validateAnnotations(annotations) — Annotationを例外を投げずValidation resultとして検証します。
validateDate(value, options) — 日付形式と選択可否を検証します。
isDateSelectable(value, options) — min/max/step/disabledを含む選択可否をbooleanで返します。
isInstance(element) — Calendar Instanceか判定します。
resolveWeekStart(weekStart, locale) — auto を monday / sunday へ解決します。
annotationsForDate(annotations, date) — 指定日のAnnotation itemを取得します。
syncParentStyle(element) — 親外観を同期して再描画します。
monthMatrix(year, month, weekStart, locale) — 42セルの月Matrixを生成します。
daysInMonth(year, month) — 月の日数を返します。
isLeapYear(year) — Gregorian calendarの閏年を判定します。
today() — 今日を YYYY-MM-DD で返します。

Runtime objectには version / componentId / type / status / defaults / enum配列等のmetadataもありますが、24件の数にはfunction APIだけを数えています。

15.1 Public API 詳細

1. `create(options)`

引数: plain object。Default Propertyに加えて任意の onSelect / onMonthChange callbackを渡せます。
戻り値: 生成された <section class="bone-calendar"> Element。
役割: Runtime Instanceを生成し、初期表示をrenderします。DOMがない環境では CALENDAR_DOM_REQUIRED。

2. `destroy(element)`

引数: Calendar Element。
戻り値: 破棄した場合 true、未登録Elementなら false。
役割: Instance登録とTooltip timerを破棄し、親DOMからElementを外します。

3. `setOptions(element, patch)`

引数: Calendar Element、plain objectの差分Property。
戻り値: 同じCalendar Element。
役割: 既存値を維持しつつPropertyを再正規化して再描画します。onSelect / onMonthChange callback差替えもここで行えます。

4. `getOptions(element)`

引数: Calendar Element。
戻り値: 正規化済みPropertyのfrozen object。
役割: 現在Propertyの読取。内部state objectそのものは返しません。

5. `setValue(element, value, source)`

引数: Calendar Element、YYYY-MM-DD または null/空、任意source文字列。
戻り値: {selected,value,previousDate,event} 相当のfrozen result。選択不可なら selected:false。
役割: 選択日を設定し、選択成功時は表示月をその日へ合わせて bone-calendar:select を発火します。null/空は未選択へ戻します。

6. `getValue(element)`

引数: Calendar Element。
戻り値: 現在の YYYY-MM-DD または null。
役割: 選択値の読取だけを行います。

7. `setView(element, value)`

引数: Calendar Element、YYYY-MM または {year, month}。
戻り値: 同じCalendar Element。
役割: 表示月を直接設定して bone-calendar:month-change を発火します。setView はmin/max月外を CALENDAR_VIEW_RANGE_INVALID で拒否します。前月/次月ボタン・previousMonth / nextMonth も同じ月境界を越えず、境界側のナビゲーションボタンはdisabledになります。

8. `getView(element)`

引数: Calendar Element。
戻り値: {year, month, value:"YYYY-MM"} のfrozen object。
役割: 現在の表示月を取得します。

9. `previousMonth(element)`

引数: Calendar Element。
戻り値: 移動できた場合 true、min の月境界またはCalendar年範囲を越える場合 false。
役割: 1か月前へ移動して bone-calendar:month-change を発火します。min の月境界を越える移動は行いません。

10. `nextMonth(element)`

引数: Calendar Element。
戻り値: 移動できた場合 true、max の月境界またはCalendar年範囲を越える場合 false。
役割: 1か月後へ移動して bone-calendar:month-change を発火します。max の月境界を越える移動は行いません。

11. `selectToday(element)`

引数: Calendar Element。
戻り値: setValueと同系統の選択result。
役割: Runtime today() の日付を選択します。min/max/step/disabled上選択不可なら selected:false。

12. `setAnnotations(element, annotations)`

引数: Calendar Element、Annotation object。
戻り値: 同じCalendar Element。
役割: setOptions(...,{annotations}) と同じ正規化/再描画経路でAnnotationを更新します。

13. `getAnnotations(element)`

引数: Calendar Element。
戻り値: 現在の正規化済みAnnotation object。
役割: 現在Annotationを読み取ります。

14. `validateAnnotations(annotations)`

引数: Annotation候補値。
戻り値: 成功時 {valid:true,dates,annotations,code:null}、失敗時 {valid:false,dates:0,annotations:{},code,message} 相当のfrozen object。
役割: 例外を呼出側へ投げず、Validation resultとして確認したい場合に使います。

15. `validateDate(value, options)`

引数: 日付候補、Property options。
戻り値: {valid,value,selectable,code,message?} のfrozen object。
役割: 厳密日付として有効かと、min/max/step/disabled上選択可能かをまとめて返します。

16. `isDateSelectable(value, options)`

引数: YYYY-MM-DD、Property options。
戻り値: boolean。
役割: 日付形式が正しい前提で、disabled/min/max/stepによる選択可否を直接判定します。不正入力はRuntime Errorを投げます。

17. `isInstance(element)`

引数: 任意Element。
戻り値: boolean。
役割: #024 Runtimeが管理中のCalendar Elementかを判定します。

18. `resolveWeekStart(weekStart, locale)`

引数: auto / monday / sunday、任意Locale。Runtime内部では環境Timezoneも考慮できます。
戻り値: monday または sunday。
役割: autoを最終開始曜日へ解決します。

19. `annotationsForDate(annotations, date)`

引数: Annotation object、YYYY-MM-DD。
戻り値: 指定日の正規化済みAnnotation item配列。該当なしは空配列。
役割: Calendar DOMを操作せず、指定日Annotationだけを取得します。

20. `syncParentStyle(element)`

引数: Calendar Element。
戻り値: inheritParent=true で同期できた場合は親Style情報のfrozen object、非依存/同期不可は null。
役割: 直接親のcomputed background/color/border/radius等を取り込み、Calendarを再描画します。

21. `monthMatrix(year, month, weekStart, locale)`

引数: year 1～9999、month 1～12、開始曜日、Locale。
戻り値: 常に42要素のfrozen array。月外セルは null。
役割: 6週×7日のCalendar Matrixを生成します。

22. `daysInMonth(year, month)`

引数: year、month。
戻り値: 28～31の日数。
役割: 2月は isLeapYear を使って日数を決定します。

23. `isLeapYear(year)`

引数: year。
戻り値: boolean。
役割: Gregorian calendarの閏年規則で判定します。

24. `today()`

引数: なし。
戻り値: 実行環境の今日を YYYY-MM-DD 文字列で返します。
役割: Today表示/選択の基準日取得です。

16. Error Code

Runtime Error

CALENDAR_ANNOTATIONS_INVALID: annotations全体がplain objectではありません。
CALENDAR_ANNOTATION_ENTRY_INVALID: 日付Entryがitem配列または {items:[...]} ではありません。
CALENDAR_ANNOTATION_HREF_INVALID: hrefが空、不正scheme、protocol-relative、制御文字等を含みます。
CALENDAR_ANNOTATION_HREF_KIND_INVALID: task 以外へhrefを指定しています。
CALENDAR_ANNOTATION_ITEM_INVALID: Annotation itemがplain objectではありません。
CALENDAR_ANNOTATION_LABEL_INVALID: labelが空、または240文字を超えています。
CALENDAR_DATE_FORMAT_INVALID: 日付が厳密な YYYY-MM-DD 形式ではありません。
CALENDAR_DATE_INVALID: Gregorian calendar上実在しない日付です。
CALENDAR_DATE_NOT_SELECTABLE: 日付自体は有効ですが、disabled/min/max/step上選択できません。
CALENDAR_DATE_TYPE_INVALID: 日付が文字列ではありません。
CALENDAR_DIMENSION_INVALID: width/heightが整数または許容範囲外です。
CALENDAR_DOM_REQUIRED: create() 実行に必要なDOM環境がありません。
CALENDAR_INSTANCE_INVALID: Runtime管理中ではないElementをInstance APIへ渡しました。
CALENDAR_LOCALE_INVALID: locale形式が不正です。
CALENDAR_MIN_MAX_INVALID: min > max です。
CALENDAR_MONTH_INVALID: year/monthがCalendar範囲外です。
CALENDAR_OPTIONS_INVALID: options/patchがplain objectではありません。
CALENDAR_OPTION_ENUM_INVALID: Theme/Icon/WeekStart/Position/Annotation kind等のenum値が不正です。
CALENDAR_STEP_INVALID: stepが any または1～3650の整数ではありません。
CALENDAR_VIEW_INVALID: viewが YYYY-MM / {year,month} の契約に合いません。
CALENDAR_VIEW_RANGE_INVALID: setView() の表示月がmin/max月の外です。

HTML Functional Class Integration Error

BF_CALENDAR_RUNTIME_REQUIRED: BoneCalendar v1.0.15 のPublic APIがありません。
BF_CALENDAR_HOVER_DEPENDENCY_REQUIRED: #022の attach / detach / getState / isAttached が不足しています。
BF_CALENDAR_ANNOTATIONS_JSON_INVALID: data-annotations がJSON Objectとして読めません。
BF_CALENDAR_BOOLEAN_INVALID: Boolean data-* が true / false 以外です。
BF_CALENDAR_NUMBER_INVALID: 数値 data-* が有限数へ変換できません。

17. トラブル時の確認

`bf-calendar` が表示されない

bone-calendar.js v1.0.15 と bone-calendar-functional-class.js が読まれているか確認します。

min/max入力欄とPreview状態が一致しない

Runtime QAはPreview本体をテスト用min/maxへ書き換えません。Property入力が min=2026-08-01 / max=2027-08-10 / step=1 の場合、2026年9月など範囲内月の日付は通常選択でき、2027年8月から9月への移動はできません。

月移動後にHover Effectが消える

#022 Runtimeが存在し、Functional Classの data-hover-enabled="true" が有効か確認します。月移動後は再描画された日付セルへの再attachが必要です。

`step` で一部日付が押せない

minがあればmin、なければ1970-01-01を基準にN日刻みです。

`auto` が期待と違う

明示 data-locale の値を確認します。ja/ja-* は月曜、それ以外の明示Localeは日曜です。

taskリンクが拒否される

相対URLまたはhttp/httpsだけを使用し、task以外へhrefを付けないでください。

18. 責務境界

#024 Calendar: Calendar UI、選択、表示月、Theme、Annotation表示、親同期。
#022 Hover Border Effect: 日付セル枠Effect本体。
#040 ColorPicker: 色選択UI/RETURN。
#002 Bone Joint: 接続判定/描画、Delivery責務を持つ側でのWAIT/FIFO/BLOCKED。
呼び出し元Picker/Input: editing/commit/invoke/OUT。

このDOC Integrationは共有 bone-doc-loader.js / bone-doc-guide.js / bone-doc-guide.css を#024都合で変更しません。

#024 Calendar

bf-calendar + BoneFlow.holidays

Calendar データ追加テスト

今日のタスク / 任意日のタスク

記念日

祝日CSV 自動取り込み

正式ガイド DOC-0024

DOC-0024 — Calendar 操作・HTML Functional Class

0. 文書情報

1. Calendarの役割

2. HTML Functional Class bf-calendar

2.1 最小利用

2.2 設定付き利用

2.3 設定 → 実表示サンプル

Sample 1 — value: 選択日を表示する

Sample 2 — min / max / step: 選択可能日を絞る

Sample 3 — theme: 4 Themeの違い

Sample 4 — weekStart: 曜日の左端を変える

Sample 5 — annotations / iconVisual=emoji: 祝日・休日・記念日・Task

Sample 6 — showTasks=false: Taskだけ消す

Sample 7 — disabled=true + showTodayButton=false

Sample 8 — width / height / position=bottom-right

Sample 9 — inheritParent=true: 親へ100%吸着

Sample 10 — #022 Hover Border Effectを日付セルへ付ける

2.4 18 Property「設定 → 表示結果」早見

3. Default Property 全18件 — 個別Reference

3.1 value

3.2 min

3.3 max

3.4 step

3.5 theme

3.6 iconVisual

3.7 disabled

3.8 className

3.9 ariaLabel

3.10 showTodayButton

3.11 weekStart

3.12 locale

3.13 annotations

3.14 showTasks

3.15 inheritParent

3.16 width

3.17 height

3.18 position

4. 日付・範囲・step

value

min / max

step

5. Theme 全4値

default

dark

light

neon

6. 表示・基本操作Property

iconVisual

disabled

className

ariaLabel

showTodayButton

7. weekStart と locale

weekStart=auto

weekStart=monday

weekStart=sunday

8. AnnotationとshowTasks

9. サイズ・親要素・9方向Position

inheritParent

width

height

position 全9値

FITとの関係

10. #022 Hover Border Effect連携

10.1 trigger

10.2 effect 全5値

10.3 direction 全2値

10.4 speed 全3値

10.5 spinWidth

10.6 spinGlow

10.7 color

11. #040 ColorPickerとの責務分離

12. 操作

2. HTML Functional Class `bf-calendar`

Sample 1 — `value`: 選択日を表示する

Sample 2 — `min` / `max` / `step`: 選択可能日を絞る

Sample 3 — `theme`: 4 Themeの違い

Sample 4 — `weekStart`: 曜日の左端を変える

Sample 5 — `annotations` / `iconVisual=emoji`: 祝日・休日・記念日・Task

Sample 6 — `showTasks=false`: Taskだけ消す

Sample 7 — `disabled=true` + `showTodayButton=false`

Sample 8 — `width` / `height` / `position=bottom-right`

Sample 9 — `inheritParent=true`: 親へ100%吸着

3.1 `value`

3.2 `min`

3.3 `max`

3.4 `step`

3.5 `theme`

3.6 `iconVisual`

3.7 `disabled`

3.8 `className`

3.9 `ariaLabel`

3.10 `showTodayButton`

3.11 `weekStart`

3.12 `locale`

3.13 `annotations`

3.14 `showTasks`

3.15 `inheritParent`

3.16 `width`

3.17 `height`

3.18 `position`

`value`

`min` / `max`

`step`

`default`

`dark`

`light`

`neon`

`iconVisual`

`disabled`

`className`

`ariaLabel`

`showTodayButton`

7. `weekStart` と `locale`

`weekStart=auto`

`weekStart=monday`

`weekStart=sunday`

8. Annotationと`showTasks`

`inheritParent`

`width`

`height`

`position` 全9値

10.1 `trigger`

10.2 `effect` 全5値

10.3 `direction` 全2値

10.4 `speed` 全3値

10.5 `spinWidth`

10.6 `spinGlow`

10.7 `color`

1. `create(options)`

2. `destroy(element)`

3. `setOptions(element, patch)`

4. `getOptions(element)`

5. `setValue(element, value, source)`

6. `getValue(element)`

7. `setView(element, value)`

8. `getView(element)`

9. `previousMonth(element)`

10. `nextMonth(element)`

11. `selectToday(element)`

12. `setAnnotations(element, annotations)`

13. `getAnnotations(element)`

14. `validateAnnotations(annotations)`

15. `validateDate(value, options)`

16. `isDateSelectable(value, options)`

17. `isInstance(element)`

18. `resolveWeekStart(weekStart, locale)`

19. `annotationsForDate(annotations, date)`

20. `syncParentStyle(element)`

21. `monthMatrix(year, month, weekStart, locale)`

22. `daysInMonth(year, month)`

23. `isLeapYear(year)`

24. `today()`