purescript-betacalendars-grid-algebra

Pure functional algebra for Gregorian calendar grids, week origins, blank planner surfaces, and printable paper geometry.

Calendar dates and calendar pages are related but different problems. This package keeps Gregorian civil-date arithmetic independent from timestamps and time zones, then builds seven week-origin views, natural or fixed six-week grids, undated blank surfaces, and an explicit paper-geometry model on top.

The calculations are deterministic and have no network dependencies. The geometry values are nominal model outputs, not measurements of a particular printer or evidence about usability.

• Constructors validate the supported year and civil-date ranges.
• Monday-based weekday indices make week-origin rotation explicit.
• Natural month grids use four, five, or six rows as required.
• Fixed month grids always have 42 cells.
• Adjacent dates are an explicit policy; blank cells never receive invented dates.
• Layout functions return Either LayoutError instead of silently accepting impossible geometry.
• The civil calendar is proleptic Gregorian for years 1 through 9999.

Add the package to a Spago project:

spago install betacalendars-grid-algebra

The package is published under the MIT license. Its public source repository is purescript-betacalendars-grid-algebra.

import Data.Maybe (Maybe(..))
import BetaCalendars.GridAlgebra.Civil (Month(..), year)
import BetaCalendars.GridAlgebra.Grid (AdjacentPolicy(..), GridMode(..), monthGrid)
import BetaCalendars.GridAlgebra.WeekStart (WeekStart(..))

january2027 = case year 2027 of
  Nothing -> Nothing
  Just y -> Just (monthGrid y January MondayStart NaturalRows EmptyAdjacent)

monthGrid returns a row-major grid. The grid records its dimensions, topology, mode, adjacent-day policy, and one relation per cell.

BetaCalendars.GridAlgebra.Civil models year, month, and day values without a clock, timezone, or JavaScript Date. The Gregorian leap rule handles century exceptions: 1900 is common, 2000 and 2024 are leap years, while 2027 and 2100 are common years. nextDate and previousDate return Nothing outside the supported 1–9999 range.

BetaCalendars.GridAlgebra.WeekStart exposes Monday through Sunday as week starts. Weekday indices are Monday = 0 through Sunday = 6. Changing the week origin changes the leading-cell count, not the date or weekday.

NaturalRows allocates the minimum complete set of seven-day rows. FixedSixWeeks always creates 6 × 7 = 42 cells. EmptyAdjacent leaves cells outside the month empty; IncludeAdjacent puts the neighboring civil dates in those cells when they are within the supported year range.

BetaCalendars.GridAlgebra.Paper models A4 (210 × 297 mm), A5 (148 × 210 mm), US Letter (215.9 × 279.4 mm), US Legal (215.9 × 355.6 mm), and custom dimensions. LayoutSpec makes margins, title/header/notes areas, and row/column counts explicit. layoutMetrics returns printable dimensions and per-cell area or a structured error.

These are geometric assumptions for comparing grid configurations. They do not include printer non-printable margins, device calibration, handwriting studies, or physical validation.

BetaCalendars.GridAlgebra.Blank constructs dated-free 5 × 7, 6 × 7, and custom rectangular surfaces. Blank cells contain only row and column coordinates. The Beta Calendars blank calendar is a human-readable reference.

This table is generated from the package's Gregorian weekday and topology functions using a Monday-first week. Fixed cells is the capacity of the six-week representation.

The Year2027 module derives the full month fixtures. A separate regression window covers November and December 2026 through January and February 2027.

BetaCalendars.GridAlgebra.Validation exposes reusable checks for cell counts, date completeness, fixed-grid capacity, layout geometry, and year-wide topology. The test suite includes the leap-year sentinels, 2027 fixtures, year-boundary dates, and exhaustive checks for each month, week origin, and grid mode from 1900 through 2100. That finite validation is not a proof for all dates.

Run locally with:

pnpm install --frozen-lockfile
pnpm exec spago build
pnpm exec spago test
pnpm exec spago docs

• BetaCalendars.GridAlgebra: curated entry point
• BetaCalendars.GridAlgebra.Civil: bounded Gregorian dates and leap years
• BetaCalendars.GridAlgebra.WeekStart: weekdays and week-origin rotation
• BetaCalendars.GridAlgebra.Grid: month topology, signatures, and cells
• BetaCalendars.GridAlgebra.Paper: nominal paper sizes and layout metrics
• BetaCalendars.GridAlgebra.Blank: undated rectangular grids
• BetaCalendars.GridAlgebra.Year2027: computed 2027 fixtures
• BetaCalendars.GridAlgebra.Boundary2027: November 2026–February 2027 regression
• BetaCalendars.GridAlgebra.Validation: reusable invariants and checks

The computations are independent of these pages. They are human-readable examples for visual comparison, not scraped data sources.

• Beta Calendars
• Blank Calendar
• January Calendar
• February Calendar
• March Calendar
• April Calendar
• May Calendar
• June Calendar
• July Calendar
• August Calendar
• September Calendar
• October Calendar
• November Calendar
• December Calendar