@typescript-calendar-lib/cli 0.1.1

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@typescript-calendar-lib/cli",
+  "version": "0.1.1",
+  "type": "module",
+  "bin": {
+    "typescript-calendar": "src/bin.ts"
+  },
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "!src/*.test.ts"
+  ],
+  "dependencies": {
+    "@typescript-calendar/core": "workspace:*",
+    "cli-table3": "^0.6.5"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/src/align.ts

@@ -0,0 +1,35 @@
+// ─── テキスト整列 ────────────────────────────────────────
+
+/** 東アジアの全角文字（ターミナル表示幅2列） */
+const WIDE =
+  /[\u1100-\u115f\u2e80-\u303e\u3041-\u33ff\u3400-\u4dbf\u4e00-\u9fff\ua000-\ua4cf\ua960-\ua97f\uac00-\ud7a3\uf900-\ufaff\ufe30-\ufe4f\uff00-\uff60\uffe0-\uffe6]/;
+
+/** ターミナル上の表示幅を返す（全角文字は2列として数える） */
+export function displayWidth(text: string): number {
+  let width = 0;
+  for (const ch of text) {
+    width += WIDE.test(ch) ? 2 : 1;
+  }
+  return width;
+}
+
+/** 表示幅 width に右詰めする（全角文字対応） */
+export function padStartWidth(text: string, width: number): string {
+  return " ".repeat(Math.max(0, width - displayWidth(text))) + text;
+}
+
+/** タイトルを幅の中央に揃える */
+export function centerText(text: string, width: number): string {
+  const padding = Math.max(0, Math.floor((width - displayWidth(text)) / 2));
+  return " ".repeat(padding) + text;
+}
+
+/** タイトルを中央に揃え、幅一杯まで埋める（枠内用） */
+export function centerTextFull(text: string, width: number): string {
+  const padding = Math.max(0, Math.floor((width - displayWidth(text)) / 2));
+  return (
+    " ".repeat(padding) +
+    text +
+    " ".repeat(Math.max(0, width - padding - displayWidth(text)))
+  );
+}

package/src/ansi.ts

@@ -0,0 +1,18 @@
+// ─── ANSI 色付け ─────────────────────────────────────────
+
+const ANSI_PATTERN = new RegExp(`${"\u001b"}\\[[0-9;]*m`, "g");
+
+/** ANSI コードを付与する（code が undefined ならそのまま） */
+export function colorize(
+  text: string,
+  code: number | undefined,
+  enabled: boolean,
+): string {
+  if (!enabled || code === undefined) return text;
+  return `\u001b[${code}m${text}\u001b[0m`;
+}
+
+/** ANSI エスケープシーケンスを除去した表示幅を返す */
+export function visibleWidth(text: string): number {
+  return text.replace(ANSI_PATTERN, "").length;
+}

package/src/bin.ts

@@ -0,0 +1,234 @@
+#!/usr/bin/env bun
+import type {
+  HighlightStyle,
+  Locale,
+  WeekStart,
+} from "@typescript-calendar/core";
+import { calendar } from "./calendar.ts";
+import type { ColorSchemeName, ThemeName } from "./theme.ts";
+
+const THEMES: readonly ThemeName[] = ["default", "modern"];
+const COLOR_SCHEMES: readonly ColorSchemeName[] = [
+  "default",
+  "ocean",
+  "forest",
+  "sunset",
+  "mono",
+];
+const LOCALES: readonly Locale[] = ["en", "ja", "es", "de", "fr", "ko", "zh"];
+const WEEK_STARTS: readonly WeekStart[] = ["sunday", "monday"];
+const HIGHLIGHT_STYLES: readonly HighlightStyle[] = ["bracket", "reverse"];
+
+export interface CliArgs {
+  year?: number;
+  month?: number;
+  theme?: ThemeName;
+  colorScheme?: ColorSchemeName;
+  color?: boolean;
+  locale?: Locale;
+  weekStart?: WeekStart;
+  highlight?: Date;
+  highlightStyle?: HighlightStyle;
+}
+
+export interface ParseResult {
+  args: CliArgs;
+  error?: string;
+  help?: boolean;
+}
+
+/** YYYY-MM-DD 形式の日付文字列をパースする */
+export function parseDate(value: string): Date | null {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+  if (!match) return null;
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  if (month < 1 || month > 12) return null;
+  if (day < 1 || day > 31) return null;
+  const date = new Date(year, month - 1, day);
+  if (
+    date.getFullYear() !== year ||
+    date.getMonth() !== month - 1 ||
+    date.getDate() !== day
+  )
+    return null;
+  return date;
+}
+
+/** 指定した候補リストに値が含まれるか検証する */
+function validateChoice<T extends string>(
+  value: T | undefined,
+  choices: readonly T[],
+  name: string,
+): string | undefined {
+  if (value === undefined) return undefined;
+  if (!choices.includes(value)) {
+    return `Invalid ${name}: "${value}" (expected: ${choices.join(" | ")})`;
+  }
+  return undefined;
+}
+
+/**
+ * CLI 引数をパースする。テスト可能なように副作用を分離している。
+ */
+export function parseArgs(args: readonly string[]): ParseResult {
+  const result: CliArgs = {};
+  const missing = (name: string): ParseResult => ({
+    args: result,
+    error: `Missing value for option: ${name}`,
+  });
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    const next = (): string | undefined => args[++i];
+
+    switch (arg) {
+      case "-h":
+      case "--help":
+        return { args: result, help: true };
+      case "--theme": {
+        const value = next();
+        if (value === undefined) return missing("--theme");
+        result.theme = value as ThemeName;
+        break;
+      }
+      case "--color-scheme": {
+        const value = next();
+        if (value === undefined) return missing("--color-scheme");
+        result.colorScheme = value as ColorSchemeName;
+        break;
+      }
+      case "--color":
+        result.color = true;
+        break;
+      case "--locale": {
+        const value = next();
+        if (value === undefined) return missing("--locale");
+        result.locale = value as Locale;
+        break;
+      }
+      case "--week-start": {
+        const value = next();
+        if (value === undefined) return missing("--week-start");
+        result.weekStart = value as WeekStart;
+        break;
+      }
+      case "--highlight": {
+        const value = next();
+        if (value === undefined) return missing("--highlight");
+        const parsed = parseDate(value);
+        if (parsed === null) {
+          return {
+            args: result,
+            error: `Invalid --highlight date: "${value}" (expected YYYY-MM-DD, e.g. 2026-09-08)`,
+          };
+        }
+        result.highlight = parsed;
+        break;
+      }
+      case "--highlight-style": {
+        const value = next();
+        if (value === undefined) return missing("--highlight-style");
+        result.highlightStyle = value as HighlightStyle;
+        break;
+      }
+      default: {
+        if (arg.startsWith("-")) {
+          return { args: result, error: `Unknown option: ${arg}` };
+        }
+        if (!/^\d+$/.test(arg)) {
+          return {
+            args: result,
+            error: `Invalid argument: "${arg}" (expected a year or month number)`,
+          };
+        }
+        if (result.year === undefined) {
+          result.year = Number(arg);
+        } else if (result.month === undefined) {
+          result.month = Number(arg);
+        } else {
+          return { args: result, error: `Too many arguments: "${arg}"` };
+        }
+      }
+    }
+  }
+
+  // 値のバリデーション
+  if (result.year !== undefined && (result.year < 1 || result.year > 9999)) {
+    return {
+      args: result,
+      error: `Invalid year: ${result.year} (expected 1–9999)`,
+    };
+  }
+  if (result.month !== undefined && (result.month < 1 || result.month > 12)) {
+    return {
+      args: result,
+      error: `Invalid month: ${result.month} (expected 1–12)`,
+    };
+  }
+
+  for (const [value, choices, name] of [
+    [result.theme, THEMES, "theme"] as const,
+    [result.colorScheme, COLOR_SCHEMES, "color-scheme"] as const,
+    [result.locale, LOCALES, "locale"] as const,
+    [result.weekStart, WEEK_STARTS, "week-start"] as const,
+    [result.highlightStyle, HIGHLIGHT_STYLES, "highlight-style"] as const,
+  ]) {
+    const error = validateChoice(value, choices, name);
+    if (error) return { args: result, error };
+  }
+
+  return { args: result };
+}
+
+export function printUsage(): string {
+  return `Usage: typescript-calendar [YYYY] [MM] [options]
+
+  typescript-calendar                       Render the current month
+  typescript-calendar 2026                  Render the current month of 2026
+  typescript-calendar 2026 9                Render September 2026
+
+Options:
+  --theme <name>           Look: default | modern (default: default)
+  --color-scheme <name>    Colors: default | ocean | forest | sunset | mono
+  --color                  Enable ANSI colors
+  --locale <lang>          Language: en | ja | es | de | fr | ko | zh (default: en)
+  --week-start <day>       First weekday: sunday | monday (default: sunday)
+  --highlight <YYYY-MM-DD> Highlight a date (e.g. 2026-09-08)
+  --highlight-style <style> Highlight style: bracket | reverse (default: bracket)
+  -h, --help               Show this help
+`;
+}
+
+if (import.meta.main) {
+  const { args, error, help } = parseArgs(process.argv.slice(2));
+
+  if (help) {
+    console.log(printUsage());
+    process.exit(0);
+  }
+  if (error) {
+    console.error(`Error: ${error}`);
+    console.error(printUsage());
+    process.exit(1);
+  }
+
+  const now = new Date();
+  const year = args.year ?? now.getFullYear();
+  const month = args.month ?? now.getMonth() + 1;
+
+  console.log(
+    calendar({
+      year,
+      month,
+      theme: args.theme,
+      colorScheme: args.colorScheme,
+      color: args.color,
+      locale: args.locale,
+      weekStart: args.weekStart,
+      highlight: args.highlight,
+      highlightStyle: args.highlightStyle,
+    }),
+  );
+}

package/src/border.ts

@@ -0,0 +1,37 @@
+import type { FrameChars } from "./theme.ts";
+
+// ─── 枠線 ─────────────────────────────────────────────────
+
+/** 枠内のコンテンツ幅（例: 7列×3幅+区切り6 = 27） */
+export function innerWidth(cellWidth: number, cols: number): number {
+  return cols * cellWidth + (cols - 1);
+}
+
+/** 上枠: ┌────┬────...────┐ */
+export function topBorder(
+  frame: FrameChars,
+  cellWidth: number,
+  cols: number,
+): string {
+  return `${frame.topLeft}${frame.h.repeat(innerWidth(cellWidth, cols))}${frame.topRight}`;
+}
+
+/** 下枠: └────┴────...────┘ */
+export function bottomBorder(
+  frame: FrameChars,
+  cellWidth: number,
+  cols: number,
+): string {
+  const segments = Array<string>(cols).fill(frame.h.repeat(cellWidth));
+  return `${frame.bottomLeft}${segments.join(frame.footJ)}${frame.bottomRight}`;
+}
+
+/** 区切り行: ├────┬────...┬────┤ */
+export function separatorRow(
+  frame: FrameChars,
+  cellWidth: number,
+  cols: number,
+): string {
+  const segments = Array<string>(cols).fill(frame.h.repeat(cellWidth));
+  return `├${segments.join(frame.j)}┤`;
+}

package/src/calendar.ts

@@ -0,0 +1,70 @@
+import { getMonthRange } from "@typescript-calendar/core";
+import { renderMonth, renderYear } from "./render.ts";
+import type {
+  CalendarOptions,
+  CalendarRangeOptions,
+  CalendarYearOptions,
+  RenderMonthOptions,
+} from "./types.ts";
+
+// ─── Options 解決 ─────────────────────────────────────────
+
+/**
+ * 各 API に共通のオプションをデフォルト値込みの描画オプションに正規化する。
+ * core 由来のオプションと CLI 固有のオプション（theme 等）をまとめる。
+ */
+function toRenderOptions(
+  options: CalendarOptions | CalendarYearOptions | CalendarRangeOptions,
+): RenderMonthOptions {
+  const {
+    locale = "en",
+    weekStart = "sunday",
+    highlight,
+    highlightStyle = "bracket",
+    range,
+    color = false,
+    theme,
+    colorScheme,
+    today,
+  } = options;
+
+  return {
+    locale,
+    weekStart,
+    highlight,
+    highlightStyle,
+    range,
+    color,
+    theme,
+    colorScheme,
+    today,
+  };
+}
+
+// ─── 公開API ─────────────────────────────────────────────
+
+/**
+ * 月カレンダーをテキストで返す
+ */
+export function calendar(options: CalendarOptions): string {
+  return renderMonth(options.year, options.month, toRenderOptions(options));
+}
+
+/**
+ * 年間カレンダーを4列×3行でテキストで返す
+ */
+export function calendarYear(options: CalendarYearOptions): string {
+  return renderYear(options.year, toRenderOptions(options));
+}
+
+/**
+ * 任意の日付範囲のカレンダーをテキストで返す
+ */
+export function calendarRange(options: CalendarRangeOptions): string {
+  const renderOptions = toRenderOptions(options);
+  const months = getMonthRange(options.from, options.to);
+
+  return months
+    .map(({ year, month }) => renderMonth(year, month, renderOptions))
+    .join("\n\n");
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+export {
+  calendar,
+  calendarRange,
+  calendarYear,
+} from "./calendar.ts";
+export type {
+  CliPalette,
+  CliTheme,
+  ColorSchemeName,
+  FrameChars,
+  ThemeName,
+} from "./theme.ts";
+export {
+  COLOR_SCHEMES,
+  resolveColorScheme,
+  resolveTheme,
+  THEMES,
+} from "./theme.ts";
+export type {
+  CalendarOptions,
+  CalendarRangeOptions,
+  CalendarYearOptions,
+  RenderMonthOptions,
+} from "./types.ts";

package/src/month.ts

@@ -0,0 +1,207 @@
+import {
+  buildMonthGrid,
+  getMonthName,
+  getWeekdayHeaders,
+  isDateInRange,
+  isSameDay,
+} from "@typescript-calendar/core";
+import { centerText, centerTextFull, padStartWidth } from "./align.ts";
+import { colorize } from "./ansi.ts";
+import { bottomBorder, innerWidth, separatorRow, topBorder } from "./border.ts";
+import type { CliPalette } from "./theme.ts";
+import { resolveColorScheme, resolveTheme } from "./theme.ts";
+import type { RenderMonthOptions } from "./types.ts";
+
+const CELL_WIDTH = 3;
+
+/**
+ * 1ヶ月分のカレンダーテキストを描画する
+ */
+export function renderMonth(
+  year: number,
+  month: number,
+  options: RenderMonthOptions = {},
+): string {
+  const {
+    locale = "en",
+    weekStart = "sunday",
+    highlight,
+    highlightStyle = "bracket",
+    range,
+    color = false,
+    theme: themeOption = "default",
+    colorScheme: schemeOption = "default",
+    today = new Date(),
+  } = options;
+
+  const theme = resolveTheme(themeOption);
+  const palette = resolveColorScheme(schemeOption);
+
+  const title = `${getMonthName(locale, month)} ${year}`;
+  const weekdays = getWeekdayHeaders(locale, weekStart);
+  const grid = buildMonthGrid(year, month, weekStart);
+
+  // bracket ハイライトは2桁の日付で `[10]` の4文字になるため、
+  // ハイライト中は全セルを4列に揃えて列ずれを防ぐ
+  const cellWidth =
+    highlight !== undefined && highlightStyle === "bracket"
+      ? CELL_WIDTH + 1
+      : CELL_WIDTH;
+
+  const lines: string[] = [];
+
+  if (theme.frame === null) {
+    // ── 枠なし（default） ──
+    const sep = theme.separator;
+    const totalWidth =
+      weekdays.length * cellWidth + (weekdays.length - 1) * sep.length;
+
+    lines.push(centerText(title, totalWidth));
+
+    lines.push(
+      weekdays
+        .map((d) =>
+          colorize(padStartWidth(d, cellWidth), palette.weekday, color),
+        )
+        .join(sep),
+    );
+
+    for (const row of grid) {
+      if (row.every((d) => d === null)) continue;
+
+      const cells = row.map((day) =>
+        renderCell(
+          year,
+          month,
+          day,
+          highlight,
+          highlightStyle,
+          range,
+          today,
+          color,
+          palette,
+          cellWidth,
+        ),
+      );
+
+      lines.push(cells.join(sep));
+    }
+  } else {
+    // ── 枠あり（modern） ──
+    const frame = theme.frame;
+
+    lines.push(
+      colorize(
+        topBorder(frame, cellWidth, weekdays.length),
+        palette.frame,
+        color,
+      ),
+    );
+    lines.push(
+      colorize(
+        `${frame.v}${centerTextFull(title, innerWidth(cellWidth, weekdays.length))}${frame.v}`,
+        palette.title,
+        color,
+      ),
+    );
+    lines.push(
+      colorize(
+        separatorRow(frame, cellWidth, weekdays.length),
+        palette.frame,
+        color,
+      ),
+    );
+    lines.push(
+      colorize(
+        `${frame.v}${weekdays.map((d) => padStartWidth(d, cellWidth)).join(frame.v)}${frame.v}`,
+        palette.weekday,
+        color,
+      ),
+    );
+    lines.push(
+      colorize(
+        separatorRow(frame, cellWidth, weekdays.length),
+        palette.frame,
+        color,
+      ),
+    );
+
+    for (const row of grid) {
+      if (row.every((d) => d === null)) continue;
+
+      const cells = row.map((day) =>
+        renderCell(
+          year,
+          month,
+          day,
+          highlight,
+          highlightStyle,
+          range,
+          today,
+          color,
+          palette,
+          cellWidth,
+        ),
+      );
+
+      lines.push(`${frame.v}${cells.join(frame.v)}${frame.v}`);
+    }
+
+    lines.push(
+      colorize(
+        bottomBorder(frame, cellWidth, weekdays.length),
+        palette.frame,
+        color,
+      ),
+    );
+  }
+
+  return lines.join("\n");
+}
+
+// ─── セル ─────────────────────────────────────────────────
+
+function renderCell(
+  year: number,
+  month: number,
+  day: number | null,
+  highlight: Date | undefined,
+  highlightStyle: "bracket" | "reverse",
+  range: { from: Date; to: Date } | undefined,
+  today: Date,
+  color: boolean,
+  palette: CliPalette,
+  cellWidth: number,
+): string {
+  if (day === null) {
+    return " ".repeat(cellWidth);
+  }
+
+  const date = new Date(year, month - 1, day);
+  const isHighlight = highlight !== undefined && isSameDay(date, highlight);
+  const isInRange = isDateInRange(date, range);
+  const isToday = isSameDay(date, today);
+  const isWeekend = date.getDay() === 0 || date.getDay() === 6;
+
+  let text: string;
+  if (isHighlight && highlightStyle === "bracket") {
+    text = `[${day}]`.padStart(cellWidth);
+  } else {
+    text = String(day).padStart(cellWidth);
+  }
+
+  let code: number | undefined;
+  if (isHighlight && highlightStyle === "reverse") {
+    code = palette.highlight ?? 7;
+  } else if (isInRange && !isHighlight) {
+    code = palette.range ?? 33;
+  } else if (isToday && palette.today !== undefined) {
+    code = palette.today;
+  } else if (isWeekend && palette.weekend !== undefined) {
+    code = palette.weekend;
+  } else if (palette.day !== undefined) {
+    code = palette.day;
+  }
+
+  return colorize(text, code, color);
+}

package/src/render.ts

@@ -0,0 +1,5 @@
+// レンダリングは責務ごとに ansi / align / border / month / year に分割されている。
+// このファイルは互換性のため公開 API を再エクスポートする。
+
+export { renderMonth } from "./month.ts";
+export { renderYear } from "./year.ts";

package/src/theme.ts

@@ -0,0 +1,148 @@
+// ─── テーマ ───────────────────────────────────────────────
+
+/** 組み込みテーマ名。カスタムテーマは CliTheme オブジェクトを直接渡せる */
+export type ThemeName = "default" | "modern";
+
+/** 枠線の文字セット（modern テーマで使用） */
+export interface FrameChars {
+  topLeft: string;
+  topRight: string;
+  bottomLeft: string;
+  bottomRight: string;
+  /** 水平線 */
+  h: string;
+  /** 垂直線 */
+  v: string;
+  /** ヘッダー/本文の区切り行で使う交差（┬ や ┼） */
+  j: string;
+  /** 下端区切りで使う交差（┴） */
+  footJ: string;
+}
+
+/** 文字ベースの見た目定義 */
+export interface CliTheme {
+  /** セル幅（日付表記の文字幅） */
+  cellWidth: number;
+  /** セル間の区切り文字（default: " " / modern: "│"） */
+  separator: string;
+  /** 枠線文字。null なら枠なし */
+  frame: FrameChars | null;
+}
+
+export const THEMES: Record<ThemeName, CliTheme> = {
+  default: {
+    cellWidth: 3,
+    separator: " ",
+    frame: null,
+  },
+  modern: {
+    cellWidth: 3,
+    separator: "│",
+    frame: {
+      topLeft: "┌",
+      topRight: "┐",
+      bottomLeft: "└",
+      bottomRight: "┘",
+      h: "─",
+      v: "│",
+      j: "┬",
+      footJ: "┴",
+    },
+  },
+};
+
+export function resolveTheme(theme?: ThemeName | CliTheme): CliTheme {
+  if (theme === undefined) return THEMES.default;
+  if (typeof theme === "string") return THEMES[theme] ?? THEMES.default;
+  return theme;
+}
+
+// ─── カラースキーム ───────────────────────────────────────
+
+/** 組み込みカラースキーム名。カスタムは CliPalette を直接渡せる */
+export type ColorSchemeName =
+  | "default"
+  | "ocean"
+  | "forest"
+  | "sunset"
+  | "mono";
+
+/**
+ * ANSIカラーパレット。
+ * 各フィールドは前景色（またはハイライト時の背景）のANSIコード。
+ * undefined はその要素を着色しない。
+ */
+export interface CliPalette {
+  title?: number;
+  weekday?: number;
+  day?: number;
+  weekend?: number;
+  today?: number;
+  /** highlightStyle: "reverse" のときに使うコード（default は 7 = 反転） */
+  highlight?: number;
+  range?: number;
+  frame?: number;
+  dim?: number;
+}
+
+export const COLOR_SCHEMES: Record<ColorSchemeName, CliPalette> = {
+  /** 従来どおり。着色は range(黄) と highlight(反転) のみ */
+  default: {
+    range: 33,
+    highlight: 7,
+  },
+  ocean: {
+    title: 36,
+    weekday: 36,
+    day: 37,
+    weekend: 34,
+    today: 36,
+    highlight: 7,
+    range: 34,
+    frame: 36,
+    dim: 90,
+  },
+  forest: {
+    title: 32,
+    weekday: 32,
+    day: 37,
+    weekend: 90,
+    today: 32,
+    highlight: 7,
+    range: 32,
+    frame: 32,
+    dim: 90,
+  },
+  sunset: {
+    title: 35,
+    weekday: 35,
+    day: 37,
+    weekend: 33,
+    today: 35,
+    highlight: 7,
+    range: 35,
+    frame: 35,
+    dim: 90,
+  },
+  mono: {
+    title: 37,
+    weekday: 37,
+    day: 37,
+    weekend: 90,
+    today: 37,
+    highlight: 7,
+    range: 90,
+    frame: 90,
+    dim: 90,
+  },
+};
+
+export function resolveColorScheme(
+  scheme?: ColorSchemeName | CliPalette,
+): CliPalette {
+  if (scheme === undefined) return COLOR_SCHEMES.default;
+  if (typeof scheme === "string") {
+    return COLOR_SCHEMES[scheme] ?? COLOR_SCHEMES.default;
+  }
+  return scheme;
+}

package/src/types.ts

@@ -0,0 +1,27 @@
+import type {
+  CalendarOptions as CoreCalendarOptions,
+  CalendarRangeOptions as CoreCalendarRangeOptions,
+  CalendarYearOptions as CoreCalendarYearOptions,
+  RenderMonthOptions as CoreRenderMonthOptions,
+} from "@typescript-calendar/core";
+import type {
+  CliPalette,
+  CliTheme,
+  ColorSchemeName,
+  ThemeName,
+} from "./theme.ts";
+
+/** CLI 固有のオプション（core のオプションに追加で受け付ける） */
+export interface CliExtraOptions {
+  /** 見た目テーマ。既定は "default" */
+  theme?: ThemeName | CliTheme;
+  /** カラースキーム。color: true のとき有効。既定は "default" */
+  colorScheme?: ColorSchemeName | CliPalette;
+  /** 今日の基準日。カラースキームの today 着色に使用 */
+  today?: Date;
+}
+
+export type CalendarOptions = CoreCalendarOptions & CliExtraOptions;
+export type CalendarYearOptions = CoreCalendarYearOptions & CliExtraOptions;
+export type CalendarRangeOptions = CoreCalendarRangeOptions & CliExtraOptions;
+export type RenderMonthOptions = CoreRenderMonthOptions & CliExtraOptions;

package/src/year.ts

@@ -0,0 +1,50 @@
+import { visibleWidth } from "./ansi.ts";
+import { renderMonth } from "./month.ts";
+import type { RenderMonthOptions } from "./types.ts";
+
+/**
+ * 年間カレンダーを4列×3行でテキストで返す
+ */
+export function renderYear(
+  year: number,
+  options: RenderMonthOptions = {},
+): string {
+  const months: string[] = [];
+  for (let m = 1; m <= 12; m++) {
+    months.push(renderMonth(year, m, options));
+  }
+
+  const monthLines = months.map((m) => m.split("\n"));
+  const maxLines = Math.max(...monthLines.map((l) => l.length));
+
+  const colWidths = monthLines.map((lines) =>
+    Math.max(...lines.map((l) => visibleWidth(l))),
+  );
+
+  const result: string[] = [];
+  for (let row = 0; row < 3; row++) {
+    const rowLines: string[] = [];
+    for (let lineIdx = 0; lineIdx < maxLines; lineIdx++) {
+      const parts: string[] = [];
+      for (let col = 0; col < 4; col++) {
+        const monthIdx = row * 4 + col;
+        if (monthIdx >= 12) {
+          parts.push("");
+          continue;
+        }
+        const lines = monthLines[monthIdx]!;
+        const line = lines[lineIdx] ?? "";
+        const pad = Math.max(0, colWidths[monthIdx]! - visibleWidth(line));
+        parts.push(line + " ".repeat(pad));
+      }
+      rowLines.push(parts.join("    "));
+    }
+    result.push(rowLines.join("\n"));
+
+    if (row < 2) {
+      result.push("");
+    }
+  }
+
+  return result.join("\n");
+}