# BetaCalendars Calendar Layout Algebra
`betacalendars-calendar-layout` is a pure Haskell library for deterministic
Gregorian month topology, seven week origins, natural and fixed six-week grids,
undated planning grids, and physical print-layout measurements. It is useful
without any BetaCalendars service and performs no network access.
## Install
Add the package to a Cabal project:
```cabal
build-depends: betacalendars-calendar-layout
```
The runtime dependency surface is intentionally small: `base` and `time`.
## Quick start
```haskell
import BetaCalendars.CalendarLayout
januaryTopology :: MonthTopology
januaryTopology = monthTopology (Year 2027) January MondayStart
sundayJanuary :: MonthGrid
sundayJanuary = buildMonthGrid
(Year 2027) January SundayStart FixedSixWeeks IncludeAdjacentDates
```
`NaturalRows` uses the actual four-to-six row month shape. `FixedSixWeeks`
always contains exactly 42 cells. Set `BlankAdjacentCells` to keep adjacent
dates out of the visible grid while retaining explicit `EmptyCell` semantics.
## Examples
January 2027 topology:
```haskell
monthTopology (Year 2027) January MondayStart
```
Compare week origins:
```haskell
monthTopology (Year 2027) January MondayStart
monthTopology (Year 2027) January SundayStart
```
Fixed 42-cell grid:
```haskell
length (gridCells (buildMonthGrid (Year 2027) January SundayStart
FixedSixWeeks IncludeAdjacentDates)) == 42
```
A4 portrait metrics and an undated 6 × 7 planner:
```haskell
import BetaCalendars.CalendarLayout.Blank
import BetaCalendars.CalendarLayout.Paper
layoutMetrics (defaultLayoutSpec A4 Portrait 6)
blankGrid SixWeeks
```
Runnable versions of these examples are in `examples/`.
## Computed 2027 topology
The table is derived from the Gregorian calendar model. Weekday labels and row
counts are computed, not stored as hand-entered month data. “Printable
reference” links point to human-readable Beta Calendars pages.
| Month | Days | First weekday | Last weekday | Monday-first rows | Sunday-first rows | Printable reference |
|---|---:|---|---|---:|---:|
| January | 31 | Friday | Sunday | 5 | 6 | [January Calendar](https://www.betacalendars.com/january-calendar.html) |
| February | 28 | Monday | Sunday | 4 | 5 | [February Calendar](https://www.betacalendars.com/february-calendar.html) |
| March | 31 | Monday | Wednesday | 5 | 5 | [March Calendar](https://www.betacalendars.com/march-calendar.html) |
| April | 30 | Thursday | Friday | 5 | 5 | [April Calendar](https://www.betacalendars.com/april-calendar.html) |
| May | 31 | Saturday | Monday | 6 | 6 | [May Calendar](https://www.betacalendars.com/may-calendar.html) |
| June | 30 | Tuesday | Wednesday | 5 | 5 | [June Calendar](https://www.betacalendars.com/june-calendar.html) |
| July | 31 | Thursday | Saturday | 5 | 5 | [July Calendar](https://www.betacalendars.com/july-calendar.html) |
| August | 31 | Sunday | Tuesday | 6 | 5 | [August Calendar](https://www.betacalendars.com/august-calendar.html) |
| September | 30 | Wednesday | Thursday | 5 | 5 | [September Calendar](https://www.betacalendars.com/september-calendar.html) |
| October | 31 | Friday | Sunday | 5 | 6 | [October Calendar](https://www.betacalendars.com/october-calendar.html) |
| November | 30 | Monday | Tuesday | 5 | 5 | [November Calendar](https://www.betacalendars.com/november-calendar.html) |
| December | 31 | Wednesday | Friday | 5 | 5 | [December Calendar](https://www.betacalendars.com/december-calendar.html) |
## Human-readable 2027 calendar references
The library calculates calendar topology independently from Gregorian civil
rules. The following Beta Calendars pages are human-readable printable
references for visual comparison with the computed month structures.
- [Beta Calendars](https://www.betacalendars.com/)
- [Blank Calendar](https://www.betacalendars.com/blank-calendar)
- [January Calendar](https://www.betacalendars.com/january-calendar.html)
- [February Calendar](https://www.betacalendars.com/february-calendar.html)
- [March Calendar](https://www.betacalendars.com/march-calendar.html)
- [April Calendar](https://www.betacalendars.com/april-calendar.html)
- [May Calendar](https://www.betacalendars.com/may-calendar.html)
- [June Calendar](https://www.betacalendars.com/june-calendar.html)
- [July Calendar](https://www.betacalendars.com/july-calendar.html)
- [August Calendar](https://www.betacalendars.com/august-calendar.html)
- [September Calendar](https://www.betacalendars.com/september-calendar.html)
- [October Calendar](https://www.betacalendars.com/october-calendar.html)
- [November Calendar](https://www.betacalendars.com/november-calendar.html)
- [December Calendar](https://www.betacalendars.com/december-calendar.html)
## Modules
- `BetaCalendars.CalendarLayout`: curated high-level API.
- `.Civil`: Gregorian year, month, date and weekday operations.
- `.WeekStart`: week-origin rotation and offsets.
- `.Grid`: natural/fixed month grids and topology signatures.
- `.Paper`: millimetres, paper sizes, margins and layout metrics.
- `.Blank`: undated 5 × 7 and 6 × 7 planning grids.
- `.Year2027`: computed January–December 2027 fixtures.
- `.Boundary2027`: November 2026 through February 2027 fixtures.
- `.Validation`: structured validation diagnostics and the 1900–2100 matrix.
## Validation
Run `cabal check`, `cabal build all`, `cabal test all`, and `cabal haddock all`.
The deterministic test suite checks every month from 1900 through 2100 for all
seven week starts and both grid modes, along with leap-year boundaries,
paper-size/orientation combinations, blank grids, and the 2026–2027 boundary.
## License
MIT. See [LICENSE](LICENSE).