beta_calendars 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 49e4c5c571e4c9878ab8006fe05159c07a3e3dc86c48a73d425b40368e3d74c2
+  data.tar.gz: a4ba1e530f4f2ed9ee885fdf3cd9b53fbb388628b9ed6362c3d90822b195ed12
+SHA512:
+  metadata.gz: 8c96ba768ca43572525d54f7abcb5d3b826fec126b52389070b6370769dfc8d444c2f1a15ae3f6995c88afbb4b22ad397fe6db66eccb99e24c8bdff436aec103
+  data.tar.gz: eabe8fdaaa4628ce79a5169f96a114bd872a9e56e0ece0a56dd04b2f6f0680e2a9116399a42a5d9a6238a83c500df99fafc75bec0d12a86717cf168e45c30918

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0
+
+- Generate month and year calendar grids with Sunday or Monday week starts.
+- Include optional adjacent-month dates and six-row print layouts.
+- Provide blank planning grids and ISO week metadata.
+- Serialize calendar structures to hashes and JSON.
+- Add the `beta-calendars` command-line interface.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,22 @@
+# Contributor Covenant Code of Conduct
+
+## Our pledge
+
+We are committed to making participation in this project a respectful,
+welcoming experience for everyone, regardless of background or identity.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment include being
+kind, considering differing viewpoints, giving and accepting constructive
+feedback, and taking responsibility for mistakes.
+
+Unacceptable behavior includes harassment, insults, personal attacks, and
+publishing another person's private information without permission.
+
+## Enforcement
+
+Report conduct concerns through the project's GitHub issue tracker. Project
+maintainers will review reports and take appropriate, proportionate action.
+
+This code of conduct is adapted from the Contributor Covenant, version 2.1.

data/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing
+
+Bug reports, focused feature proposals, and pull requests are welcome. Please
+include a small example that shows the expected calendar dates and week-start
+policy when reporting a calculation issue.
+
+## Development
+
+The library targets Ruby 3.1 and newer and has no runtime gem dependencies.
+
+```sh
+bundle install
+bundle exec rake test
+gem build beta_calendars.gemspec
+```
+
+Keep changes deterministic, use Ruby's proleptic Gregorian `Date` calculations,
+and add meaningful tests for boundary dates. Do not add network access to the
+calendar computation path.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mateo Pedersen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,222 @@
+# Beta Calendars Ruby
+
+**Deterministic Gregorian calendar grids for Ruby applications.** Generate monthly and yearly calendar data locally, with week-start policies, ISO week metadata, adjacent dates, fixed six-week layouts, blank planning grids, JSON output, and a small CLI.
+
+## Why this exists
+
+A calendar grid looks simple, but correct output depends on leap years, weekday offsets, Sunday or Monday week starts, ISO week-year boundaries, and the geometry chosen for printing. This library turns those rules into a predictable data model without a web service, scraping, or runtime gem dependencies.
+
+## Installation
+
+```sh
+gem install beta_calendars
+```
+
+Or add it to a Gemfile:
+
+```ruby
+gem "beta_calendars"
+```
+
+The gem requires Ruby 3.1 or newer and uses Ruby's standard `Date` and `JSON` libraries.
+
+## Quick Start
+
+```ruby
+require "beta_calendars"
+
+calendar = BetaCalendars.month(year: 2027, month: 1, week_start: :monday)
+
+calendar.year       # => 2027
+calendar.month      # => 1
+calendar.month_name # => "January"
+calendar.days.size  # => 31
+calendar.weeks      # => rows of seven DayCell values
+calendar.to_h       # => developer-friendly nested hash
+calendar.to_json    # => JSON with ISO-8601 date strings
+```
+
+`DayCell` instances are immutable and expose `date`, `day`, `weekday`,
+`iso_week`, `iso_week_year`, `in_current_month`, and `weekend`. `weekday` follows
+Ruby's convention, where Sunday is `0`; `iso_weekday` follows ISO-8601, where
+Monday is `1` and Sunday is `7`.
+
+## Monthly Calendars
+
+`BetaCalendars.month` returns a month object. Its `days` array contains only
+dates in the requested month, while `weeks` and `matrix` contain the display
+grid. Each populated position is a `DayCell`, not just a day number.
+
+```ruby
+january = BetaCalendars.month(year: 2027, month: 1)
+january.month_name # => "January"
+january.days.first.date.iso8601 # => "2027-01-01"
+january.weeks.first.first.to_h
+# => {:date=>"2026-12-27", :day=>27, ...}
+```
+
+The grid uses the natural four, five, or six rows required by that month unless
+`fixed_six_weeks: true` is selected.
+
+## Monday vs Sunday Week Start
+
+Choose the first weekday explicitly. The API accepts `:monday` and `:sunday`
+(or their string forms); invalid values raise `BetaCalendars::InvalidWeekStartError`.
+
+```ruby
+sunday = BetaCalendars.month(year: 2027, month: 1, week_start: :sunday)
+monday = BetaCalendars.month(year: 2027, month: 1, week_start: :monday)
+
+sunday.weekdays # => ["Sunday", "Monday", ...]
+monday.weekdays # => ["Monday", "Tuesday", ...]
+```
+
+## Adjacent Month Dates
+
+Out-of-month cells contain the neighboring real dates by default. Set
+`adjacent_dates: false` to leave those cells as `nil`; this is useful when a
+renderer wants visibly empty leading and trailing cells.
+
+```ruby
+filled = BetaCalendars.month(year: 2027, month: 1, adjacent_dates: true)
+empty  = BetaCalendars.month(year: 2027, month: 1, adjacent_dates: false)
+
+filled.weeks.first.first.date.iso8601 # => "2026-12-27"
+empty.weeks.first.first               # => nil
+```
+
+## Fixed Six-Week Print Layouts
+
+For printable month pages that need identical geometry, set
+`fixed_six_weeks: true`. Every month then has exactly six rows and seven
+columns, including months that naturally need only four or five rows.
+
+```ruby
+print_month = BetaCalendars.month(
+  year: 2027,
+  month: 2,
+  week_start: :monday,
+  fixed_six_weeks: true
+)
+
+print_month.weeks.length # => 6
+print_month.weeks.all? { |week| week.length == 7 } # => true
+```
+
+With `adjacent_dates: false`, positions outside February remain `nil` even in
+the sixth row. The library supplies geometry; the application decides whether
+those positions render as whitespace, lines, or another design element.
+
+## Year Calendars
+
+`BetaCalendars.year` contains all twelve month objects. Indexing is one-based,
+so `year[1]` is January and `year[12]` is December.
+
+```ruby
+calendar_year = BetaCalendars.year(year: 2027, week_start: :monday)
+calendar_year.months.length # => 12
+calendar_year[1].month_name # => "January"
+calendar_year[12].month_name # => "December"
+calendar_year.to_h
+calendar_year.to_json
+```
+
+## Blank Calendar Grids
+
+`blank_grid` creates an empty seven-column planning structure with weekday
+labels and row/column metadata. It does not assign dates to the cells.
+
+```ruby
+planning_grid = BetaCalendars.blank_grid(rows: 6, week_start: :sunday)
+planning_grid.weeks.length # => 6
+planning_grid.weeks.first.length # => 7
+planning_grid.weeks.first.first.to_h
+# => {:row=>0, :column=>0, :weekday=>"Sunday"}
+```
+
+For a printable blank calendar example, see the [Beta Calendars blank
+calendar](https://www.betacalendars.com/blank-calendar). The returned grid is
+generic and can be used in unrelated planning applications.
+
+## JSON Output
+
+All calendar value objects implement `to_h` and `to_json`. Dates serialize as
+ISO-8601 strings such as `"2027-01-01"`; ISO week and week-year are separate
+integer fields, so year-boundary meaning is preserved.
+
+```ruby
+require "json"
+
+calendar = BetaCalendars.month(year: 2027, month: 1, week_start: :monday)
+json = calendar.to_json
+parsed = JSON.parse(json)
+parsed.fetch("weeks").first
+```
+
+You can also get the plain two-dimensional cell array directly:
+
+```ruby
+matrix = BetaCalendars.month_matrix(
+  year: 2027,
+  month: 1,
+  week_start: :monday,
+  adjacent_dates: false
+)
+```
+
+## CLI
+
+The installed `beta-calendars` executable offers readable terminal output or
+JSON. Options may follow the command arguments.
+
+```sh
+beta-calendars month 2027 1
+beta-calendars month 2027 1 --week-start monday
+beta-calendars month 2027 1 --json
+beta-calendars month 2027 2 --fixed-six-weeks --no-adjacent-dates
+beta-calendars year 2027 --json
+beta-calendars blank --rows 6 --week-start sunday
+beta-calendars info 2027
+```
+
+## Calendar Correctness
+
+The implementation uses Ruby's `Date` with the proleptic Gregorian calendar
+for month length, weekday placement, and ISO-8601 week calculations. It treats
+calendar dates as date-only values: there are no time zones, daylight-saving
+transitions, or remote data sources in the calculation path. Supported years
+are 1 through 9999.
+
+```ruby
+BetaCalendars.leap_year?(2024) # => true
+BetaCalendars.days_in_month(2027, 2) # => 28
+BetaCalendars.iso_week(Date.new(2021, 1, 1)).to_h # => {:week=>53, :year=>2020}
+```
+
+## Printing and Presentation
+
+This library produces calendar data models. Your application chooses how to
+render them as HTML, PDF, images, terminal output, or another format. For
+printable calendar examples and planning resources, see
+[Beta Calendars](https://www.betacalendars.com/).
+
+## Related resources
+
+- [Monthly calendar examples](https://www.betacalendars.com/monthly-calendar) show the month-grid use case supported by `BetaCalendars.month`.
+- [Monthly planner pages](https://www.betacalendars.com/monthly-planner) are a related planning use case for the library's blank grids.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+gem build beta_calendars.gemspec
+```
+
+The test suite covers leap years, month geometry, both week starts, adjacent
+dates, ISO week-year boundaries, fixed print grids, blank grids, JSON output,
+and the executable.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rake/testtask"
+require "bundler/gem_tasks"
+
+Rake::TestTask.new(:test) do |task|
+  task.libs << "test"
+  task.pattern = "test/**/*_test.rb"
+end
+
+task default: :test

data/beta_calendars.gemspec

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "lib/beta_calendars/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "beta_calendars"
+  spec.version = BetaCalendars::VERSION
+  spec.authors = ["Mateo Pedersen"]
+  spec.email = []
+
+  spec.summary = "Deterministic Ruby calendar grids for monthly, yearly and printable calendar applications."
+  spec.description = <<~DESCRIPTION
+    Beta Calendars Ruby generates Gregorian month and year calendar structures,
+    including configurable Sunday or Monday week starts, adjacent-month cells,
+    ISO week metadata, fixed six-week print grids, blank planning grids, JSON
+    serialization, and a small command-line interface. All calculations run
+    locally using Ruby's standard Date library.
+  DESCRIPTION
+  spec.homepage = "https://www.betacalendars.com/"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1"
+
+  spec.metadata = {
+    "homepage_uri" => spec.homepage,
+    "source_code_uri" => "https://github.com/mateopedersen/beta-calendars-ruby",
+    "documentation_uri" => "https://github.com/mateopedersen/beta-calendars-ruby#readme",
+    "changelog_uri" => "https://github.com/mateopedersen/beta-calendars-ruby/blob/main/CHANGELOG.md",
+    "bug_tracker_uri" => "https://github.com/mateopedersen/beta-calendars-ruby/issues",
+    "rubygems_mfa_required" => "true"
+  }
+
+  # An explicit allowlist keeps local credentials, build products, and unrelated
+  # project files out of the published gem.
+  spec.files = %w[
+    CHANGELOG.md
+    CODE_OF_CONDUCT.md
+    CONTRIBUTING.md
+    LICENSE.txt
+    README.md
+    Rakefile
+    beta_calendars.gemspec
+    exe/beta-calendars
+    lib/beta_calendars.rb
+    lib/beta_calendars/blank_grid.rb
+    lib/beta_calendars/cli.rb
+    lib/beta_calendars/day_cell.rb
+    lib/beta_calendars/errors.rb
+    lib/beta_calendars/iso_week.rb
+    lib/beta_calendars/month.rb
+    lib/beta_calendars/serializable.rb
+    lib/beta_calendars/version.rb
+    lib/beta_calendars/year.rb
+  ]
+  spec.bindir = "exe"
+  spec.executables = ["beta-calendars"]
+  spec.require_paths = ["lib"]
+  spec.add_development_dependency "minitest", ">= 5.0", "< 6"
+  spec.add_development_dependency "rake", ">= 12.3", "< 14"
+end

data/exe/beta-calendars

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "beta_calendars"
+
+exit(BetaCalendars::CLI.run(ARGV))

data/lib/beta_calendars/blank_grid.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module BetaCalendars
+  # A position in a date-free planning grid.
+  class BlankCell
+    include Serializable
+
+    attr_reader :row, :column, :weekday
+
+    def initialize(row:, column:, weekday:)
+      @row = row
+      @column = column
+      @weekday = weekday
+      freeze
+    end
+
+    def to_h
+      { row: row, column: column, weekday: weekday }
+    end
+  end
+
+  # A blank rows-by-seven structure ready for a planner or printable renderer.
+  class BlankGrid
+    include Serializable
+
+    attr_reader :rows, :week_start, :weekdays, :weeks
+
+    def initialize(rows:, week_start:)
+      unless rows.is_a?(Integer) && rows.between?(1, 60)
+        raise InvalidGridSizeError, "rows must be an integer from 1 to 60"
+      end
+
+      @rows = rows
+      @week_start = CalendarValidation.normalize_week_start(week_start)
+      @weekdays = Month::WEEKDAY_NAMES.rotate(week_start == :sunday ? 0 : 1).freeze
+      @weeks = rows.times.map do |row|
+        7.times.map do |column|
+          BlankCell.new(row: row, column: column, weekday: weekdays[column])
+        end.freeze
+      end.freeze
+      freeze
+    end
+
+    alias grid weeks
+
+    def to_h
+      {
+        rows: rows,
+        columns: 7,
+        week_start: week_start,
+        weekdays: weekdays,
+        weeks: weeks.map { |week| week.map(&:to_h).freeze }.freeze
+      }
+    end
+  end
+end

data/lib/beta_calendars/cli.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module BetaCalendars
+  # Small standard-library command-line interface.
+  module CLI
+    module_function
+
+    def run(arguments, out: $stdout, err: $stderr)
+      args = arguments.dup
+      command = args.shift
+      return help(out) if command.nil? || %w[help --help -h].include?(command)
+
+      options = { week_start: :sunday, adjacent_dates: true, fixed_six_weeks: false, json: false, rows: 6 }
+      parser = option_parser(options)
+      parser.parse!(args)
+
+      case command
+      when "month"
+        run_month(args, options, out)
+      when "year"
+        run_year(args, options, out)
+      when "blank"
+        run_blank(args, options, out)
+      when "info"
+        run_info(args, options, out)
+      else
+        raise OptionParser::InvalidArgument, "unknown command #{command.inspect}"
+      end
+      0
+    rescue OptionParser::ParseError, ArgumentError, BetaCalendars::Error => error
+      err.puts("beta-calendars: #{error.message}")
+      2
+    end
+
+    def option_parser(options)
+      OptionParser.new do |parser|
+        parser.banner = "Usage: beta-calendars COMMAND [arguments] [options]"
+        parser.on("--week-start START", "Week start: monday or sunday") { |value| options[:week_start] = value.to_sym }
+        parser.on("--fixed-six-weeks", "Force monthly grids to six rows") { options[:fixed_six_weeks] = true }
+        parser.on("--no-adjacent-dates", "Leave out-of-month cells empty") { options[:adjacent_dates] = false }
+        parser.on("--rows COUNT", Integer, "Blank grid rows (1-60)") { |value| options[:rows] = value }
+        parser.on("--json", "Print JSON") { options[:json] = true }
+        parser.on("-h", "--help", "Show this help") { raise OptionParser::InvalidArgument, parser.to_s }
+      end
+    end
+
+    def run_month(args, options, out)
+      require_count!(args, 2, "month YEAR MONTH")
+      calendar = BetaCalendars.month(
+        year: integer!(args[0], "year"),
+        month: integer!(args[1], "month"),
+        week_start: options[:week_start],
+        adjacent_dates: options[:adjacent_dates],
+        fixed_six_weeks: options[:fixed_six_weeks]
+      )
+      options[:json] ? out.puts(calendar.to_json) : print_month(calendar, out)
+    end
+
+    def run_year(args, options, out)
+      require_count!(args, 1, "year YEAR")
+      calendar = BetaCalendars.year(
+        year: integer!(args[0], "year"),
+        week_start: options[:week_start],
+        adjacent_dates: options[:adjacent_dates],
+        fixed_six_weeks: options[:fixed_six_weeks]
+      )
+      if options[:json]
+        out.puts(calendar.to_json)
+      else
+        out.puts("#{calendar.year} Calendar (weeks start #{calendar.week_start})")
+        calendar.months.each { |month| print_month(month, out) }
+      end
+    end
+
+    def run_blank(args, options, out)
+      require_count!(args, 0, "blank")
+      grid = BetaCalendars.blank_grid(rows: options[:rows], week_start: options[:week_start])
+      if options[:json]
+        out.puts(grid.to_json)
+      else
+        out.puts(grid.weekdays.map { |name| name[0, 2] }.join(" "))
+        grid.weeks.each { out.puts(Array.new(7, "  ").join(" ")) }
+      end
+    end
+
+    def run_info(args, options, out)
+      require_count!(args, 1, "info YEAR")
+      year = integer!(args[0], "year")
+      info = {
+        year: year,
+        leap_year: BetaCalendars.leap_year?(year),
+        months: (1..12).map do |month_number|
+          { month: month_number, name: Date::MONTHNAMES[month_number], days: BetaCalendars.days_in_month(year, month_number) }
+        end
+      }
+      options[:json] ? out.puts(JSON.generate(info)) : print_info(info, out)
+    end
+
+    def print_month(calendar, out)
+      out.puts("#{calendar.month_name} #{calendar.year}")
+      out.puts(calendar.weekdays.map { |name| name[0, 2] }.join(" "))
+      calendar.weeks.each do |week|
+        out.puts(week.map { |cell| cell ? format("%2d", cell.day) : "  " }.join(" "))
+      end
+      out.puts
+    end
+
+    def print_info(info, out)
+      out.puts("#{info[:year]}: #{info[:leap_year] ? 'leap year' : 'common year'}")
+      info[:months].each { |month| out.puts(format("%-9s %2d days", month[:name], month[:days])) }
+    end
+
+    def integer!(value, label)
+      Integer(value, 10)
+    rescue ArgumentError
+      raise OptionParser::InvalidArgument, "#{label} must be an integer"
+    end
+
+    def require_count!(args, expected, usage)
+      return if args.length == expected
+
+      raise OptionParser::InvalidArgument, "expected #{usage}"
+    end
+
+    def help(out)
+      out.puts <<~HELP
+        Usage: beta-calendars COMMAND [arguments] [options]
+
+        Commands:
+          month YEAR MONTH   Print one month grid
+          year YEAR          Print all twelve months
+          blank              Print a blank planning grid
+          info YEAR          Show leap-year and month-length information
+
+        Options:
+          --week-start monday|sunday
+          --fixed-six-weeks
+          --no-adjacent-dates
+          --rows COUNT        Blank grid rows (1-60)
+          --json
+      HELP
+      0
+    end
+  end
+end

data/lib/beta_calendars/day_cell.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module BetaCalendars
+  # Immutable metadata for one real Gregorian date in a month grid.
+  class DayCell
+    include Serializable
+
+    attr_reader :date, :day, :year, :month, :weekday, :iso_weekday,
+                :iso_week, :iso_week_year, :in_current_month, :weekend
+
+    def initialize(date:, current_year:, current_month:)
+      @date = date
+      @day = date.day
+      @year = date.year
+      @month = date.month
+      @weekday = date.wday # Sunday = 0, matching Ruby Date#wday.
+      @iso_weekday = date.cwday # Monday = 1 through Sunday = 7.
+      @iso_week = date.cweek
+      @iso_week_year = date.cwyear
+      @in_current_month = (date.year == current_year && date.month == current_month)
+      @weekend = (date.wday == 0 || date.wday == 6)
+      freeze
+    end
+
+    def to_h
+      {
+        date: date.iso8601,
+        day: day,
+        year: year,
+        month: month,
+        weekday: weekday,
+        iso_weekday: iso_weekday,
+        iso_week: iso_week,
+        iso_week_year: iso_week_year,
+        in_current_month: in_current_month,
+        weekend: weekend
+      }
+    end
+  end
+end

data/lib/beta_calendars/errors.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module BetaCalendars
+  class Error < StandardError; end
+
+  class InvalidWeekStartError < ArgumentError
+    def initialize(value)
+      super("week_start must be :monday or :sunday (got #{value.inspect})")
+    end
+  end
+
+  class InvalidCalendarDateError < ArgumentError; end
+  class InvalidGridSizeError < ArgumentError; end
+end

data/lib/beta_calendars/iso_week.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module BetaCalendars
+  # ISO-8601 week number and the week-based year that owns it.
+  class ISOWeek
+    include Serializable
+
+    attr_reader :week, :year
+    alias iso_year year
+
+    def initialize(week:, year:)
+      @week = week
+      @year = year
+      freeze
+    end
+
+    def to_h
+      { week: week, year: year }
+    end
+  end
+end

data/lib/beta_calendars/month.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module BetaCalendars
+  # Calendar grid and date metadata for one Gregorian month.
+  class Month
+    include Serializable
+
+    WEEKDAY_NAMES = %w[Sunday Monday Tuesday Wednesday Thursday Friday Saturday].freeze
+
+    attr_reader :year, :month, :week_start, :adjacent_dates, :fixed_six_weeks,
+                :days_in_month, :weeks, :weekdays
+
+    def initialize(year:, month:, week_start:, adjacent_dates:, fixed_six_weeks:)
+      CalendarValidation.validate_year!(year)
+      CalendarValidation.validate_month!(month)
+      @year = year
+      @month = month
+      @week_start = CalendarValidation.normalize_week_start(week_start)
+      @adjacent_dates = !!adjacent_dates
+      @fixed_six_weeks = !!fixed_six_weeks
+      @days_in_month = Date.new(year, month, -1, Date::GREGORIAN).day
+      @weekdays = ordered_weekday_names.freeze
+      @weeks = build_weeks.freeze
+      freeze
+    end
+
+    def month_name
+      Date::MONTHNAMES.fetch(month)
+    end
+
+    # Returns one immutable cell for each day in this month, excluding adjacent dates.
+    def days
+      (1..days_in_month).map do |day|
+        DayCell.new(date: Date.new(year, month, day, Date::GREGORIAN), current_year: year, current_month: month)
+      end.freeze
+    end
+
+    alias matrix weeks
+
+    def to_h
+      {
+        year: year,
+        month: month,
+        month_name: month_name,
+        week_start: week_start,
+        adjacent_dates: adjacent_dates,
+        fixed_six_weeks: fixed_six_weeks,
+        weekdays: weekdays,
+        weeks: weeks.map { |week| week.map { |cell| cell&.to_h }.freeze }.freeze
+      }
+    end
+
+    private
+
+    def ordered_weekday_names
+      start = (week_start == :sunday ? 0 : 1)
+      7.times.map { |offset| WEEKDAY_NAMES[(start + offset) % 7] }
+    end
+
+    def build_weeks
+      first_date = Date.new(year, month, 1, Date::GREGORIAN)
+      start_weekday = week_start == :sunday ? 0 : 1
+      leading = (first_date.wday - start_weekday) % 7
+      row_count = fixed_six_weeks ? 6 : ((leading + days_in_month + 6) / 7)
+      grid_start = first_date - leading
+
+      row_count.times.map do |row|
+        7.times.map do |column|
+          date = grid_start + (row * 7) + column
+          if adjacent_dates || (date.year == year && date.month == month)
+            DayCell.new(date: date, current_year: year, current_month: month)
+          end
+        end.freeze
+      end
+    end
+  end
+end

data/lib/beta_calendars/serializable.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module BetaCalendars
+  module Serializable
+    def to_json(*arguments)
+      JSON.generate(to_h, *arguments)
+    end
+  end
+end

data/lib/beta_calendars/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module BetaCalendars
+  VERSION = "0.1.0"
+end

data/lib/beta_calendars/year.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module BetaCalendars
+  # Twelve month value objects for one Gregorian calendar year.
+  class Year
+    include Serializable
+
+    attr_reader :year, :week_start, :adjacent_dates, :fixed_six_weeks, :months
+
+    def initialize(year:, week_start:, adjacent_dates:, fixed_six_weeks:)
+      CalendarValidation.validate_year!(year)
+      @year = year
+      @week_start = CalendarValidation.normalize_week_start(week_start)
+      @adjacent_dates = !!adjacent_dates
+      @fixed_six_weeks = !!fixed_six_weeks
+      @months = (1..12).map do |month_number|
+        Month.new(
+          year: year,
+          month: month_number,
+          week_start: @week_start,
+          adjacent_dates: @adjacent_dates,
+          fixed_six_weeks: @fixed_six_weeks
+        )
+      end.freeze
+      freeze
+    end
+
+    # Month numbers are one-based: year[1] is January and year[12] is December.
+    def [](month_number)
+      unless month_number.is_a?(Integer) && month_number.between?(1, 12)
+        raise IndexError, "month number must be between 1 and 12"
+      end
+
+      months.fetch(month_number - 1)
+    end
+
+    def to_h
+      {
+        year: year,
+        week_start: week_start,
+        adjacent_dates: adjacent_dates,
+        fixed_six_weeks: fixed_six_weeks,
+        months: months.map(&:to_h).freeze
+      }
+    end
+  end
+end

data/lib/beta_calendars.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "date"
+require "json"
+
+require_relative "beta_calendars/version"
+require_relative "beta_calendars/errors"
+require_relative "beta_calendars/serializable"
+
+module BetaCalendars
+  module CalendarValidation
+    module_function
+
+    def validate_year!(year)
+      unless year.is_a?(Integer) && year.between?(1, 9999)
+        raise InvalidCalendarDateError, "year must be an integer from 1 to 9999"
+      end
+    end
+
+    def validate_month!(month)
+      unless month.is_a?(Integer) && month.between?(1, 12)
+        raise InvalidCalendarDateError, "month must be an integer from 1 to 12"
+      end
+    end
+
+    def normalize_week_start(value)
+      normalized = value.respond_to?(:to_sym) ? value.to_sym : value
+      return normalized if %i[monday sunday].include?(normalized)
+
+      raise InvalidWeekStartError, value
+    end
+  end
+end
+
+require_relative "beta_calendars/day_cell"
+require_relative "beta_calendars/month"
+require_relative "beta_calendars/year"
+require_relative "beta_calendars/blank_grid"
+require_relative "beta_calendars/iso_week"
+require_relative "beta_calendars/cli"
+
+module BetaCalendars
+  class << self
+    # Build a local Gregorian month grid. Out-of-month cells contain adjacent
+    # dates by default; pass adjacent_dates: false to use nil cells instead.
+    # @param year [Integer] Gregorian year from 1 through 9999
+    # @param month [Integer] month number from 1 through 12
+    # @param week_start [Symbol, String] :monday or :sunday
+    # @param adjacent_dates [Boolean] populate cells from neighboring months
+    # @param fixed_six_weeks [Boolean] always create six rows
+    # @return [BetaCalendars::Month]
+    def month(year:, month:, week_start: :sunday, adjacent_dates: true, fixed_six_weeks: false)
+      Month.new(
+        year: year,
+        month: month,
+        week_start: week_start,
+        adjacent_dates: adjacent_dates,
+        fixed_six_weeks: fixed_six_weeks
+      )
+    end
+
+    # Build twelve monthly calendars for the selected Gregorian year.
+    # @param year [Integer] Gregorian year from 1 through 9999
+    # @param week_start [Symbol, String] :monday or :sunday
+    # @param adjacent_dates [Boolean] populate cells from neighboring months
+    # @param fixed_six_weeks [Boolean] always create six rows per month
+    # @return [BetaCalendars::Year]
+    def year(year:, week_start: :sunday, adjacent_dates: true, fixed_six_weeks: false)
+      Year.new(
+        year: year,
+        week_start: week_start,
+        adjacent_dates: adjacent_dates,
+        fixed_six_weeks: fixed_six_weeks
+      )
+    end
+
+    # Build an empty printable planning grid with seven weekday columns.
+    # @param rows [Integer] row count from 1 through 60
+    # @param week_start [Symbol, String] :monday or :sunday
+    # @return [BetaCalendars::BlankGrid]
+    def blank_grid(rows: 6, week_start: :sunday)
+      BlankGrid.new(rows: rows, week_start: week_start)
+    end
+
+    # Return whether a Gregorian year has 366 days.
+    # @param year [Integer] Gregorian year from 1 through 9999
+    # @return [Boolean]
+    def leap_year?(year)
+      CalendarValidation.validate_year!(year)
+      (year % 400).zero? || ((year % 4).zero? && !(year % 100).zero?)
+    end
+
+    # Return the number of days in a Gregorian month.
+    # @param year [Integer] Gregorian year from 1 through 9999
+    # @param month [Integer] month number from 1 through 12
+    # @return [Integer]
+    def days_in_month(year, month)
+      CalendarValidation.validate_year!(year)
+      CalendarValidation.validate_month!(month)
+      Date.new(year, month, -1, Date::GREGORIAN).day
+    end
+
+    # Return the ISO week and ISO week-year for a Date, or for year/month/day.
+    # @param date_or_year [Date, Integer] a Date or Gregorian year
+    # @param month [Integer, nil] month number when a year is supplied
+    # @param day [Integer, nil] day of month when a year is supplied
+    # @return [BetaCalendars::ISOWeek]
+    def iso_week(date_or_year, month = nil, day = nil)
+      date = if date_or_year.is_a?(Date) && month.nil? && day.nil?
+               date_or_year
+             elsif date_or_year.is_a?(Integer) && month.is_a?(Integer) && day.is_a?(Integer)
+               CalendarValidation.validate_year!(date_or_year)
+               CalendarValidation.validate_month!(month)
+               unless Date.valid_date?(date_or_year, month, day, Date::GREGORIAN)
+                 raise InvalidCalendarDateError, "day must be valid for the selected year and month"
+               end
+               Date.new(date_or_year, month, day, Date::GREGORIAN)
+             else
+               raise ArgumentError, "provide a Date or integer year, month, and day"
+             end
+      ISOWeek.new(week: date.cweek, year: date.cwyear)
+    end
+
+    # Return the same metadata-rich two-dimensional grid exposed by Month#weeks.
+    # @return [Array<Array<BetaCalendars::DayCell, nil>>]
+    def month_matrix(year:, month:, week_start: :sunday, adjacent_dates: true, fixed_six_weeks: false)
+      self.month(
+        year: year,
+        month: month,
+        week_start: week_start,
+        adjacent_dates: adjacent_dates,
+        fixed_six_weeks: fixed_six_weeks
+      ).weeks
+    end
+  end
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: beta_calendars
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mateo Pedersen
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '12.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '12.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '14'
+description: |
+  Beta Calendars Ruby generates Gregorian month and year calendar structures,
+  including configurable Sunday or Monday week starts, adjacent-month cells,
+  ISO week metadata, fixed six-week print grids, blank planning grids, JSON
+  serialization, and a small command-line interface. All calculations run
+  locally using Ruby's standard Date library.
+email: []
+executables:
+- beta-calendars
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- beta_calendars.gemspec
+- exe/beta-calendars
+- lib/beta_calendars.rb
+- lib/beta_calendars/blank_grid.rb
+- lib/beta_calendars/cli.rb
+- lib/beta_calendars/day_cell.rb
+- lib/beta_calendars/errors.rb
+- lib/beta_calendars/iso_week.rb
+- lib/beta_calendars/month.rb
+- lib/beta_calendars/serializable.rb
+- lib/beta_calendars/version.rb
+- lib/beta_calendars/year.rb
+homepage: https://www.betacalendars.com/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://www.betacalendars.com/
+  source_code_uri: https://github.com/mateopedersen/beta-calendars-ruby
+  documentation_uri: https://github.com/mateopedersen/beta-calendars-ruby#readme
+  changelog_uri: https://github.com/mateopedersen/beta-calendars-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/mateopedersen/beta-calendars-ruby/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Deterministic Ruby calendar grids for monthly, yearly and printable calendar
+  applications.
+test_files: []