make_a_calendar_toolkit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7b1145ce898bcbfe87749ff4eadb6dff4bb610b0abde0bb8feecf1b0ced9b5e3
+  data.tar.gz: 4060c5b3ade3f1a1cabcd6704d9d77b186ac5772151cafbf1bf22ffba22679fb
+SHA512:
+  metadata.gz: ef360e90269be4d60dfda75aa937f991990bb1d4176b51a8c942e1ae8d08d3e6bda9fc7aee4f182d5dc6e662c5ef0327e8ff4753f00541866877e160eca5b930
+  data.tar.gz: 3e7d94d67856eab5874e7f83ba8ff292e04b5d7ea24f1c8632e6cfb5e41583755427c50e7777ce81148b39635ec923194d0448c4374fd32be8a4a30775c8eff5

data/.gitignore

@@ -0,0 +1,5 @@
+/.bundle/
+/vendor/
+*.gem
+coverage/
+.DS_Store

data/.rspec

@@ -0,0 +1 @@
+--format documentation

data/.rubocop.yml

@@ -0,0 +1,27 @@
+AllCops:
+  TargetRubyVersion: 2.7
+  NewCops: disable
+  SuggestExtensions: false
+  Exclude:
+    - "vendor/**/*"
+
+Layout/LineLength:
+  Max: 160
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/MethodLength:
+  Max: 30
+
+Style/Documentation:
+  Enabled: false
+
+Style/GuardClause:
+  Enabled: false
+
+Style/IfUnlessModifier:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+3.2.0

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.1.0 — 2026-10-12
+
+- Initial public release of calendar grids, date arithmetic, US federal holiday rules, business-day operations, recurring pay dates, shift schedules, NRF-style retail fiscal calendars, date converters, print-ready SVG/HTML, JSON/CSV, ICS, and CLI commands.
+- Core operations use Ruby's standard library and run offline.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,7 @@
+# Contributor Covenant Code of Conduct
+
+We are committed to a welcoming, respectful community. Be considerate, patient, and constructive. Harassment, discriminatory language, personal attacks, and unwanted attention are not acceptable.
+
+Project maintainers may remove, edit, or reject contributions that do not follow this code and may temporarily or permanently exclude contributors for unacceptable behavior. Report concerns privately through the repository's GitHub contact options.
+
+This code applies in project spaces and when someone is representing the project publicly.

data/CONTRIBUTING.md

@@ -0,0 +1,7 @@
+# Contributing
+
+Bug reports and focused pull requests are welcome. Please include the Ruby version, a minimal reproduction, expected result, and actual result. Date changes should include independent calendar references or clearly stated rules.
+
+Run the local checks with `ruby -Ilib spec/all_spec.rb`, `ruby -c` on changed Ruby files, and `gem build make_a_calendar_toolkit.gemspec`. Keep runtime dependencies at zero and document any new public behavior in the README or `docs/`.
+
+Do not include credentials, private data, generated files that are not deliberate samples, or changes copied from the Make a Calendar website's private implementation.

data/Gemfile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+gemspec

data/Gemfile.lock

@@ -0,0 +1,21 @@
+PATH
+  remote: .
+  specs:
+    make_a_calendar_toolkit (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    minitest (5.11.3)
+    rake (12.3.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  make_a_calendar_toolkit!
+  minitest (~> 5.0)
+  rake (~> 12.0)
+
+BUNDLED WITH
+   2.5.23

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ethan
+
+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,154 @@
+# Make a Calendar Toolkit
+
+An offline Ruby toolkit for calendar grids, business scheduling, holiday dates, fiscal periods, date conversion, printable SVG/HTML, and iCalendar exports.
+
+[![CI](https://github.com/makeacalendar/make-a-calendar-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/makeacalendar/make-a-calendar-ruby/actions/workflows/ci.yml)
+
+## Contents
+
+- [What it is](#what-it-is)
+- [Install and start](#install-and-start)
+- [Calendar grids and print output](#calendar-grids-and-print-output)
+- [Business days and US federal holidays](#business-days-and-us-federal-holidays)
+- [Pay and shift schedules](#pay-and-shift-schedules)
+- [Retail fiscal calendars](#retail-fiscal-calendars)
+- [Converters](#converters)
+- [ICS export](#ics-export)
+- [Command line](#command-line)
+- [Rails use](#rails-use)
+- [Date rules and limitations](#date-rules-and-limitations)
+- [Development](#development)
+- [Documentation and related tools](#documentation-and-related-tools)
+- [Contributing, security, license](#contributing-security-license)
+
+## What it is
+
+Make a Calendar Toolkit packages reusable date and scheduling behavior for Ruby applications. It creates month and year grids, counts business days, applies a documented set of US federal holiday rules, builds pay and rotating-shift schedules, maps NRF-style 4-4-5/4-5-4/5-4-4 fiscal periods, converts common date representations, and exports calendars as SVG, print-oriented HTML, JSON, CSV, or date-only ICS.
+
+Core features work offline using Ruby's standard library. The gem does not call the Make a Calendar website and does not reproduce its private implementation. Rails is not a runtime dependency.
+
+The project was created by Ethan, the developer behind [Make a Calendar](https://make-a-calendar.com/), a browser-based calendar and date-tools platform.
+
+## Install and start
+
+```sh
+gem install make_a_calendar_toolkit
+```
+
+```ruby
+require "date"
+require "make_a_calendar"
+
+calendar = MakeACalendar.month(year: 2027, month: 10, week_start: :monday)
+puts calendar.to_json
+File.write("october-2027.svg", calendar.to_svg(theme: :editorial, page_size: :letter))
+```
+
+The library declares Ruby `>= 2.6` and has no runtime gem dependencies.
+
+## Calendar grids and print output
+
+Month grids contain four, five, or six rows unless `fixed_rows: 6` is requested. Cells carry civil `Date` values, adjacent-month information, weekdays, and ISO week data. A `Date` stays a date; no UTC instant is constructed to determine its weekday.
+
+```ruby
+month = MakeACalendar.month(year: 2027, month: 10, week_start: :sunday, fixed_rows: 6)
+puts month.to_csv
+File.write("planner.html", month.to_html(theme: :ink_saver, page_size: :letter_landscape))
+```
+
+Available print themes are `:editorial`, `:business`, `:academic`, and `:ink_saver`. Paper choices are `:letter`, `:a4`, `:letter_landscape`, and `:a4_landscape`. HTML includes print CSS; SVG is standalone and has accessible title and description elements. `MakeACalendar.year(year: 2027)` returns a twelve-month calendar suitable for one-page SVG or HTML output.
+
+## Business days and US federal holidays
+
+Date ranges include both endpoints by default. `inclusive: false` removes both endpoints. Saturday and Sunday are the default weekend (`Date#wday` values 6 and 0); pass your own weekend list for another work pattern. Adding a nonzero number of business days starts counting after the supplied date; zero returns that date unchanged.
+
+```ruby
+holidays = MakeACalendar.federal_holidays(2027)
+count = MakeACalendar.business_days_between(
+  Date.new(2027, 1, 1), Date.new(2027, 3, 31), holidays: holidays
+)
+deadline = MakeACalendar.add_business_days(Date.new(2027, 2, 1), 30, holidays: holidays)
+```
+
+Each federal `Holiday` keeps its legal date and observed weekday separately. The rule set includes effective-date distinctions for MLK Day, Juneteenth, the Monday holiday changes, and Veterans Day's 1971–1977 observance. It is a federal calendar reference, not state law, court rules, bank policy, or an employer's closure schedule. Add caller-owned holidays when a business uses different rules.
+
+## Pay and shift schedules
+
+`MakeACalendar::Scheduling.pay_dates` supports weekly, biweekly, semi-monthly, and monthly dates. Weekend/holiday adjustments must be selected explicitly with `:none`, `:following`, `:preceding`, or `:modified_following`. The library does not assume one employer's payday convention.
+
+`shift_dates` accepts a repeating list such as `[2, 2, 3]` or `"2-2-3"`; entries alternate on-duty and off-duty blocks, beginning on duty. Results are date labels only and do not represent hours worked or a fixed-length UTC shift across daylight-saving changes.
+
+## Retail fiscal calendars
+
+`MakeACalendar.fiscal_calendar(year: 2029, pattern: :four_four_five)` uses the Sunday nearest February 1. The default label is the ending year, so a fiscal year labeled 2029 starts in 2028. `:four_four_five`, `:four_five_four`, and `:five_four_four` are supported. A 53rd week is assigned to period 12 by default; use `extra_week: :first_period` to assign it to period 1. This is one documented convention, not a claim that every company's accounting calendar matches it.
+
+## Converters
+
+`MakeACalendar::Converters` includes Unix seconds/milliseconds/microseconds/nanoseconds with rational arithmetic, Excel 1900 and 1904 serial dates, Windows FILETIME, ISO-8601 timestamps that require an explicit offset, and unambiguous `YYYY-DDD` / `YYYYDDD` ordinal dates. Excel 1900 serial 60 raises because it represents Excel's fictitious 1900-02-29. Two-digit ordinal years and historical Julian calendar conversions are not inferred.
+
+## ICS export
+
+`MakeACalendar.to_ics` exports date-only events with CRLF line endings, escaped text fields, folded content lines, stable UID defaults, and exclusive `DTEND` dates. It does not emit time-zone definitions or promise full recurrence-rule support.
+
+```ruby
+ics = MakeACalendar.to_ics([
+  { date: "2027-10-12", summary: "Planning day", description: "Quarterly review" }
+])
+File.write("planning.ics", ics)
+```
+
+## Command line
+
+```sh
+make-calendar month --year 2027 --month 10 --format svg --output october.svg
+make-calendar year --year 2027 --format html
+make-calendar holidays --year 2027 --country us --observed
+make-calendar business-days --from 2027-01-01 --to 2027-03-31 --observed
+make-calendar add-business-days --date 2027-02-01 --days 30
+make-calendar fiscal --year 2029 --pattern 445
+make-calendar shifts --start 2027-01-01 --to 2027-01-31 --pattern 2-2-3
+make-calendar convert excel --serial 45000 --system 1900
+make-calendar convert unix --serial 1234567890 --system seconds
+make-calendar export-ics --input events.json --output events.ics
+```
+
+Output goes to standard output unless `--output` is supplied. Existing files are protected unless `--force` is used. Run `make-calendar --help` for the full syntax. The CLI accepts US holidays only in this release.
+
+## Rails use
+
+Rails is optional. In a Rails application, add the gem to the application's Gemfile, then call the Ruby API in a service object:
+
+```ruby
+# app/services/monthly_report_calendar.rb
+class MonthlyReportCalendar
+  def self.call(year:, month:)
+    MakeACalendar.month(year: year, month: month, week_start: :monday).to_svg
+  end
+end
+```
+
+No Rails modules are loaded by the gem.
+
+## Date rules and limitations
+
+Gregorian civil dates are represented by Ruby `Date`. Month grids use Sunday-first or Monday-first ordering. ISO weeks and week-years follow Ruby's ISO calendar fields. The standard `Date` implementation defines the supported range; invalid dates and invalid month values raise errors. Holiday rules are limited to the documented US federal rule set; local and organization-specific holidays remain caller data. Payroll dates and fiscal-week policies are configurable where the library has a defined option. PDF/PNG generation, time-zone-aware timed events, state holidays, and astronomical/historic calendar systems are outside 0.1.0.
+
+## Development
+
+```sh
+ruby -Ilib spec/all_spec.rb
+find lib exe spec examples -name '*.rb' -print0 | xargs -0 -n1 ruby -c
+gem build make_a_calendar_toolkit.gemspec
+```
+
+CI runs tests, Ruby syntax checks, package build, archive inspection, and CLI help on Ruby 2.7, 3.2, and 3.4. The test suite uses independent date expectations and covers calendar boundaries, holidays, business schedules, fiscal periods, converters, renderer escaping, ICS, and CLI behavior.
+
+## Documentation and related tools
+
+Technical guides are in [`docs/`](docs/). Helpful browser-based references include [monthly calendar templates](https://make-a-calendar.com/monthly-calendars), [date calculators](https://make-a-calendar.com/date-tools), [business-day calculator](https://make-a-calendar.com/business-days-calculator), [4-4-5 calendar overview](https://make-a-calendar.com/445-calendar), [date converters](https://make-a-calendar.com/converters), and the [iCalendar generator](https://make-a-calendar.com/ical-generator). Those pages are separate web tools; this gem runs locally and does not depend on them.
+
+## Contributing, security, license
+
+See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). Released under the [MIT License](LICENSE).
+
+Created by Ethan, the developer behind [Make a Calendar](https://make-a-calendar.com/).

data/Rakefile

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

data/SECURITY.md

@@ -0,0 +1,5 @@
+# Security policy
+
+Please report suspected vulnerabilities privately through GitHub's security advisory reporting for this repository. Include affected versions, impact, and a reproducible example when possible. Do not post credentials or sensitive personal information in a public issue.
+
+The library has no network client and no runtime gem dependencies. Treat user-provided paths as application input, validate them before use, and do not render untrusted HTML outside the provided escaped calendar renderers.

data/docs/README.md

@@ -0,0 +1,19 @@
+# Documentation
+
+- [Getting started](getting-started.md)
+- [Architecture](architecture.md)
+- [API reference map](api-reference.md)
+- [Date semantics](date-semantics.md)
+- [Calendar rendering](calendar-rendering.md)
+- [Printable calendars](printable-calendars.md)
+- [Business-day arithmetic](business-days.md)
+- [US federal holidays](holidays.md)
+- [Pay and shift schedules](recurring-dates.md)
+- [Fiscal 4-4-5 calendars](fiscal-445.md)
+- [Date converters](date-converters.md)
+- [iCalendar export](ics-export.md)
+- [Rails integration](rails-integration.md)
+- [Advanced examples](advanced-examples.md)
+- [Related online resources](online-resources.md)
+
+These guides document the behavior shipped in the gem. A dedicated documentation website is not configured in version 0.1.0; GitHub serves these source documents publicly.

data/docs/advanced-examples.md

@@ -0,0 +1,28 @@
+# Advanced examples
+
+## Fiscal period lookup
+
+```ruby
+fiscal = MakeACalendar.fiscal_calendar(year: 2029, pattern: :four_five_four)
+period = fiscal.period_for(Date.new(2028, 10, 1))
+puts [fiscal.label_year, period.quarter, period.number].join(" / ")
+```
+
+## Excel date validation
+
+```ruby
+begin
+  date = MakeACalendar::Converters.excel(60, system: "1900")
+rescue ArgumentError => error
+  warn error.message
+end
+```
+
+## iCalendar holiday export
+
+```ruby
+events = MakeACalendar.federal_holidays(2027).map do |holiday|
+  { date: holiday.observed_date, summary: holiday.name }
+end
+File.write("federal-holidays.ics", MakeACalendar.to_ics(events))
+```

data/docs/api-reference.md

@@ -0,0 +1,15 @@
+# API reference map
+
+Require `make_a_calendar`.
+
+- `MakeACalendar.month`, `MakeACalendar.year`
+- `MakeACalendar.business_days_between`, `MakeACalendar.add_business_days`
+- `MakeACalendar.federal_holidays`, `MakeACalendar.fiscal_calendar`, `MakeACalendar.to_ics`
+- `MakeACalendar::DateMath` for date grids, quarters, date ranges, ordinals, and ISO weeks
+- `MakeACalendar::BusinessDays` for iteration and month/year totals
+- `MakeACalendar::Scheduling` for pay dates and shift cycles
+- `MakeACalendar::Converters` for Unix, Excel, FILETIME, ISO 8601, and ordinal values
+- `Calendar#to_json`, `#to_csv`, `#to_html`, and `#to_svg`
+- `YearCalendar#to_json`, `#to_html`, and `#to_svg`
+
+See the README and focused guides for boundary conventions and examples.

data/docs/architecture.md

@@ -0,0 +1,5 @@
+# Architecture
+
+The `DateMath` module owns civil date operations and month-grid geometry. Calendar renderers consume immutable grids. Scheduling modules implement holiday rules, workday iteration, pay dates, rotating patterns, and NRF-style fiscal periods. Converter methods make source epochs and units explicit. The `ICS` module serializes date-only events. The executable maps options to these public modules and does not contain a separate date engine.
+
+The gem uses the Ruby standard library (`date`, `time`, `json`, `csv`, `cgi`, and `optparse`) and no runtime dependencies. It does not request data from Make a Calendar or claim to reproduce the site's private code.

data/docs/business-days.md

@@ -0,0 +1,7 @@
+# Business-day arithmetic
+
+Use `MakeACalendar.business_days_between(from, to, weekend: [0, 6], holidays: [], inclusive: true)` to count working dates. Ruby weekday numbers are Sunday 0 through Saturday 6. A `Holiday` contributes its observed date; a `Date` or ISO date string contributes itself.
+
+`MakeACalendar.add_business_days(date, count, ...)` counts after the start for nonzero values. `BusinessDays.each_workday` yields dates in the requested range. `in_month` and `in_year` count weekdays with the same options.
+
+The US federal holiday rules are convenience inputs. Add caller-owned dates for company closures and verify contract, court, payroll, and state rules independently.

data/docs/calendar-rendering.md

@@ -0,0 +1,5 @@
+# Calendar rendering
+
+`Calendar#to_svg` returns a standalone SVG with a title, description, legible day cells, and an optional holiday label. `Calendar#to_html` returns a document with print CSS. Both escape user-facing text and offer `:editorial`, `:business`, `:academic`, and `:ink_saver` themes. Paper dimensions accept Letter or A4 in portrait or landscape orientation.
+
+The yearly renderer lays out 12 month grids on one page. PDF and raster exports are not included; print HTML through a browser or convert SVG with an application chosen by the caller.

data/docs/date-converters.md

@@ -0,0 +1,5 @@
+# Date converters
+
+`Converters.unix` takes a value and explicit unit (`:seconds`, `:milliseconds`, `:microseconds`, or `:nanoseconds`) and returns UTC `Time`. `Converters.to_unix` reverses the conversion.
+
+`Converters.excel` accepts the 1900 or 1904 system; 1900 serial 60 is rejected. Fractional days return a UTC `Time`. `Converters.filetime` and `to_filetime` convert 100-nanosecond ticks since 1601-01-01 UTC. `parse_time` requires an explicit UTC marker or numeric offset. `ordinal` accepts only four-digit-year formats `YYYY-DDD` and `YYYYDDD`.

data/docs/date-semantics.md

@@ -0,0 +1,21 @@
+# Date semantics
+
+## Civil dates
+
+Pass a `Date` or ISO `YYYY-MM-DD` string to date-only APIs. A civil date has no time zone; its weekday is calculated directly as a calendar date.
+
+## Month grids
+
+Week starts are `:sunday` (Ruby `Date#wday` 0) or `:monday`. Natural grids use four through six rows. `fixed_rows: 6` creates a consistent print height. Cells outside the month carry adjacent dates. ISO week number and week-year are attached per cell.
+
+## Business-day ranges
+
+`BusinessDays.between` includes both endpoints by default, skips the configured weekend, and excludes the supplied holiday date or each holiday's `observed_date`. Set `inclusive: false` to exclude both range endpoints. Adding a nonzero number of workdays moves forward or backward after the start date.
+
+## Holiday history
+
+US federal rules distinguish actual dates from weekend-observed dates. Monday observances reflect the post-1971 Uniform Monday Holiday rules; Veterans Day's 1971–1977 Monday observance is accounted for. Juneteenth begins in 2021. Federal observance is not a proxy for state law, financial market closures, or a company's policy.
+
+## Timestamp conversion
+
+Timestamp functions require an explicit unit. ISO timestamps require a UTC marker or numeric offset. Excel's 1900 system rejects serial 60, and FILETIME uses 100-nanosecond ticks since 1601-01-01 UTC.

data/docs/fiscal-445.md

@@ -0,0 +1,11 @@
+# Retail 4-4-5 fiscal calendars
+
+The retail calendar starts on the Sunday nearest February 1. By default, the year label is the ending year: a calendar labeled 2029 begins at the anchor Sunday nearest February 1, 2028.
+
+```ruby
+fiscal = MakeACalendar.fiscal_calendar(year: 2029, pattern: :four_four_five)
+puts fiscal.to_h
+puts fiscal.period_for(Date.new(2029, 1, 10)).number
+```
+
+The 12 periods repeat the selected 4-4-5, 4-5-4, or 5-4-4 week sequence. A 53rd week goes to period 12 unless `extra_week: :first_period` is selected. Organizations can use different fiscal anchors or adjustment policies; this implementation does not claim universal accounting compatibility.

data/docs/getting-started.md

@@ -0,0 +1,12 @@
+# Getting started
+
+Install `make_a_calendar_toolkit`, require `make_a_calendar`, and call the same API from scripts, services, or Rails applications. Runtime code has no external gem dependencies and performs no network requests.
+
+```ruby
+require "make_a_calendar"
+
+calendar = MakeACalendar.month(year: 2027, month: 10, week_start: :monday)
+File.write("october.svg", calendar.to_svg)
+```
+
+For command-line use, install the gem then run `make-calendar --help`. By default, commands print to standard output; `--output FILE` writes a file and refuses to overwrite it unless `--force` is given.

data/docs/holidays.md

@@ -0,0 +1,7 @@
+# US federal holiday dates
+
+`MakeACalendar.federal_holidays(year)` returns `Holiday` entries with a legal date and a weekend-observed date. The model covers federal holidays in the modern statutory era and distinguishes important changes: Memorial Day's pre-1971 May 30 date, Washington's Birthday's pre-1971 February 22 date, Columbus Day from 1971, Veterans Day's 1971–1977 October observance, Juneteenth from 2021, and Thanksgiving's 1939 move to the fourth Thursday.
+
+The older Thanksgiving dates use a recurring November rule as a practical calendar approximation; Presidential proclamations varied in some early years. This is not an authoritative legal history or a state, bank, or employer closure calendar. Supply custom `Date` values or `Holiday` objects when a caller follows other rules.
+
+For a range spanning year boundaries, `Holidays.observed_dates(first_year, last_year)` includes adjacent legal years so a New Year's observed date on December 31 is available.

data/docs/ics-export.md

@@ -0,0 +1,5 @@
+# iCalendar export
+
+`MakeACalendar.to_ics(events, name: ...)` writes date-only VEVENT entries with a one-day exclusive `DTEND`. It escapes text fields, folds lines at the RFC 5545 octet limit, and writes CRLF separators. UIDs are deterministic for an ordered input list unless an event supplies one. `DTSTAMP` records the export time.
+
+This subset omits `VTIMEZONE`, timed events, and recurrence rules. Use it for all-day planning data, not for local-time meeting schedules where daylight-saving behavior matters.

data/docs/online-resources.md

@@ -0,0 +1,12 @@
+# Online calendar resources
+
+This gem is an offline Ruby library. For interactive browser workflows, the creator also maintains [Make a Calendar](https://make-a-calendar.com/).
+
+- [Monthly calendars](https://make-a-calendar.com/monthly-calendars) provides customizable month pages and printable layouts.
+- [Date tools](https://make-a-calendar.com/date-tools) groups business-day, pay-period, shift, and fiscal calculators.
+- [Business-day calculator](https://make-a-calendar.com/business-days-calculator) counts weekdays with observed US federal holidays.
+- [4-4-5 calendar](https://make-a-calendar.com/445-calendar) documents the site's retail calendar generator.
+- [Date converters](https://make-a-calendar.com/converters) covers timestamp and spreadsheet formats.
+- [iCalendar generator](https://make-a-calendar.com/ical-generator) builds all-day calendar files in the browser.
+
+These links are contextual resources; the Ruby toolkit uses its own original implementation and does not access the website.

data/docs/payroll-schedules.md

@@ -0,0 +1,5 @@
+# Payroll schedules
+
+`Scheduling.pay_dates` supports weekly and biweekly anchors plus semi-monthly and monthly schedules. Semi-monthly defaults to the 15th and the month's last day. Monthly schedules use the anchor's day and clamp to the last day in shorter months.
+
+Choose a non-working-day adjustment explicitly: `:none`, `:following`, `:preceding`, or `:modified_following`. Pass weekend dates and holiday dates as appropriate to the organization. No adjustment should be assumed to match every payroll contract.

data/docs/printable-calendars.md

@@ -0,0 +1,11 @@
+# Printable calendars
+
+Monthly SVG output uses a fixed page viewBox and scalable geometry. HTML output adds print CSS for A4/Letter paper in portrait or landscape. The `:ink_saver` theme uses a white background and dark lines; `:editorial`, `:business`, and `:academic` adjust the color palette. No remote fonts, logos, or tracking are added.
+
+```ruby
+calendar = MakeACalendar.month(year: 2027, month: 10, week_start: :monday, fixed_rows: 6)
+File.write("planner.svg", calendar.to_svg(theme: :ink_saver, page_size: :a4_landscape))
+File.write("planner.html", calendar.to_html(theme: :business, page_size: :letter))
+```
+
+SVG and HTML are provided; PDF and PNG are not. Print the HTML in a browser or use an external converter selected by your application.

data/docs/recurring-dates.md

@@ -0,0 +1,7 @@
+# Pay dates and shift rotations
+
+`Scheduling.pay_dates` creates weekly, biweekly, semi-monthly, or monthly dates. Weekly schedules use a seven-day anchor interval; biweekly uses fourteen days. Semi-monthly dates default to the 15th and month end. Monthly dates preserve the anchor's day and clamp to the last day in shorter months. The caller chooses weekend/holiday handling.
+
+`Scheduling.shift_dates` accepts alternating on/off block lengths. `"2-2-3"` means two on, two off, three on, then the cycle repeats. An anchor date establishes cycle day 1. The library returns civil dates and does not infer shift duration, timezone, or daylight-saving behavior.
+
+Generated date ranges are limited to 100 years to keep accidental oversized requests bounded.

data/examples/01-monthly-printable.rb

@@ -0,0 +1,3 @@
+# October 2027 monthly calendar as print-friendly SVG.
+require "make_a_calendar"
+puts MakeACalendar.month(year: 2027, month: 10).to_svg(theme: :ink_saver)

data/examples/02-yearly-svg.rb

@@ -0,0 +1,3 @@
+# Twelve-month 2027 calendar on a single SVG page.
+require "make_a_calendar"
+puts MakeACalendar.year(year: 2027).to_svg

data/examples/03-federal-holidays.rb

@@ -0,0 +1,4 @@
+# Legal and observed US federal holidays for 2027.
+require "json"
+require "make_a_calendar"
+puts JSON.pretty_generate(MakeACalendar.federal_holidays(2027).map(&:to_h))

data/examples/04-business-deadline.rb

@@ -0,0 +1,4 @@
+# Add 30 weekdays after a date, excluding observed federal holidays.
+require "make_a_calendar"
+holidays = MakeACalendar::Holidays.observed_dates(2027)
+puts MakeACalendar.add_business_days("2027-02-01", 30, holidays: holidays)

data/examples/05-biweekly-payroll.rb

@@ -0,0 +1,4 @@
+# Generate a biweekly Friday payroll schedule.
+require "make_a_calendar"
+dates = MakeACalendar::Scheduling.pay_dates(start_date: "2027-01-01", end_date: "2027-12-31", frequency: :biweekly, anchor: "2027-01-01", adjust: :preceding)
+puts dates.map(&:iso8601)

data/examples/06-rotating-shifts.rb

@@ -0,0 +1,4 @@
+# Repeat a 2-on, 2-off, 3-on rotation over January 2027.
+require "make_a_calendar"
+rows = MakeACalendar::Scheduling.shift_dates(start_date: "2027-01-01", end_date: "2027-01-31", pattern: "2-2-3", anchor: "2027-01-01")
+puts rows.select { |row| row[:on_duty] }.map { |row| row[:date].iso8601 }

data/examples/07-fiscal-445.rb

@@ -0,0 +1,4 @@
+# NRF-style fiscal periods labeled by their ending year.
+require "json"
+require "make_a_calendar"
+puts JSON.pretty_generate(MakeACalendar.fiscal_calendar(year: 2029, pattern: :four_four_five).to_h)

data/examples/08-excel-serial.rb

@@ -0,0 +1,3 @@
+# Convert an Excel 1900-system serial date.
+require "make_a_calendar"
+puts MakeACalendar::Converters.excel(45_000, system: "1900")

data/examples/09-windows-filetime.rb

@@ -0,0 +1,3 @@
+# Convert Windows FILETIME ticks to UTC.
+require "make_a_calendar"
+puts MakeACalendar::Converters.filetime("134000000000000000").utc.iso8601

data/examples/10-holidays-ics.rb

@@ -0,0 +1,4 @@
+# Export 2027 observed federal holidays as date-only iCalendar events.
+require "make_a_calendar"
+events = MakeACalendar.federal_holidays(2027).map { |holiday| { date: holiday.observed_date, summary: holiday.name } }
+print MakeACalendar.to_ics(events, name: "US Federal Holidays 2027")

data/examples/11-rails-style-service.rb

@@ -0,0 +1,8 @@
+# A service object for a Rails app; Rails itself is not required to run this example.
+require "make_a_calendar"
+class MonthlyCalendarService
+  def self.call(year:, month:)
+    MakeACalendar.month(year: year, month: month, week_start: :monday).to_html(theme: :business)
+  end
+end
+puts MonthlyCalendarService.call(year: 2027, month: 10).include?("<table>")

data/examples/12-ink-saver-planner.rb

@@ -0,0 +1,3 @@
+# A fixed six-row black-and-white planner with Monday-first weeks.
+require "make_a_calendar"
+puts MakeACalendar.month(year: 2027, month: 10, week_start: :monday, fixed_rows: 6).to_svg(theme: :ink_saver, page_size: :a4_landscape)