calendar: one left edge for the day's rules, and optional half hours (§ 7.12)

Each block sized its own marker column — hours for a schedule, tick
boxes for a todo — and then started its rules wherever that column
happened to end, so the page had a ragged left edge instead of one.
_rules_left measures every block's column and hands them all the same
edge to rule from.

A schedule block may now rule the half hours (half_hours: true, off by
default so nothing existing changes). With them on the hour rule steps
up from FAINT to GUIDE, so the half stays subordinate rather than the
two reading as equals. On a block that has no hours the key is refused,
not ignored: a setting that does nothing where it stands is the silent
almost-right of § 5.1.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: DocAtPrompt

ctrlgrid/data/presets/calendar-a4.yaml

@@ -88,6 +88,8 @@ week_view: { surface: lines, tasks: true }
 # The day page — an ordered list of blocks. Reorder, resize, drop or repeat.
 day:
   blocks:
+    # `half_hours: true` rules the half hours too — the hour line then steps
+    # up a shade so the half stays subordinate.
     - { type: schedule, from: 7, to: 22, height: 55%, surface: lines }
     - { type: todo,     rows: 8,          height: 20% }
     - { type: notes,    height: rest,     surface: grid }

ctrlgrid/generators/calendar.py

@@ -118,6 +118,9 @@ class DayBlock(Section):
     start_hour: int | None = Field(default=None, alias="from", ge=0, le=24)
     end_hour: int | None = Field(default=None, alias="to", ge=0, le=24)
     rows: int | None = Field(default=None, ge=1)
+    #: Rule the half hours too. Off by default, so an existing definition draws
+    #: exactly what it drew before.
+    half_hours: bool = False
 
     @field_validator("height")
     @classmethod
@@ -135,6 +138,12 @@ def _schedule_has_a_span(self) -> DayBlock:
                 raise ValueError(
                     f"schedule `from` ({self.start_hour}) must be before `to` ({self.end_hour})"
                 )
+        elif self.half_hours:
+            # Refused rather than ignored: a key that does nothing where it
+            # stands is the silent almost-right § 5.1 warns about.
+            raise ValueError(
+                f"`half_hours` belongs to a schedule block, not to a {self.type} one (§ 7)"
+            )
         return self
 
 

ctrlgrid/generators/calendar_layout.py

@@ -682,19 +682,45 @@ def week_page(page: Page, cfg, n: Nav, months, weekdays, *, week_no, start_date,
 # ------------------------------------------------------------------- day blocks
 
 
+#: The hour numbers and the tick boxes sit in a marker column; this is the air
+#: between it and where the writing starts.
+_BLOCK_GUTTER = mm(3)
+
+
+def _rules_left(page: Page, blocks) -> int:
+    """The one left edge every block's rules start at (§ 7).
+
+    Each block has its own marker column — hours for a schedule, tick boxes for
+    a todo — of its own width. Left to itself each would start its rules
+    somewhere else, and the page would have a ragged left edge instead of one.
+    """
+    marker = 0
+    for b in blocks:
+        if b.type == "schedule":
+            size = pt(7)
+            marker = max(marker, pt(1) + max(
+                page.q.text_width(str(b.start_hour + i), family="sans", size=round(size))
+                for i in range(max(1, b.end_hour - b.start_hour))
+            ))
+        elif b.type == "todo":
+            marker = max(marker, pt(1) + mm(4))
+    return round(marker + _BLOCK_GUTTER) if marker else 0
+
+
 def _draw_blocks(page: Page, blocks, top) -> None:
     avail = page.H - top - pt(2)
     fixed = sum(int(b.height[:-1]) for b in blocks if b.height != "rest")
     rests = [b for b in blocks if b.height == "rest"]
     rest_h = round(avail * max(0, 100 - fixed) / 100 / len(rests)) if rests else 0
+    rules_left = _rules_left(page, blocks)
     y = top
     for b in blocks:
         h = rest_h if b.height == "rest" else round(avail * int(b.height[:-1]) / 100)
-        _draw_block(page, b, y, h)
+        _draw_block(page, b, y, h, rules_left)
         y += h
 
 
-def _draw_block(page: Page, b, top, h) -> None:
+def _draw_block(page: Page, b, top, h, rules_left: int = 0) -> None:
     page.hline(0, page.W, top, 0.35, GUIDE)
     inner = top + pt(2)
     if b.type == "schedule":
@@ -706,20 +732,23 @@ def _draw_block(page: Page, b, top, h) -> None:
         # a space is half a digit wide, so ` 7` used to end 0.7 mm short of `10`.
         widths = {s: page.q.text_width(s, family="sans", size=round(size)) for s in labels}
         num_right = pt(1) + max(widths.values())
-        # The rule starts just past the hours, not at a guessed inset, so an
-        # all-single-digit span (7–9) does not leave a wide empty gutter.
-        rule_left = num_right + mm(3)
+        rule_left = rules_left or num_right + _BLOCK_GUTTER
+        # With half hours on, the hour rule steps up to GUIDE so the half stays
+        # subordinate in FAINT; without them it keeps the FAINT it always had.
+        hour_color = GUIDE if b.half_hours else FAINT
         for i, label in enumerate(labels):
             ry = inner + i * rh
             page.text(num_right - widths[label], round(ry), label, size, INK)
-            page.hline(rule_left, page.W, ry + rh - pt(1), 0.2, FAINT)
+            if b.half_hours:
+                page.hline(rule_left, page.W, ry + rh / 2 - pt(1), 0.2, FAINT)
+            page.hline(rule_left, page.W, ry + rh - pt(1), 0.2, hour_color)
     elif b.type == "todo":
         rows = b.rows or max(1, int((h - pt(2)) // mm(8)))
         rh = (h - pt(2)) / rows
         for i in range(rows):
             ry = inner + i * rh
             page.box(pt(1), round(ry), mm(4), mm(4), 0.35, GUIDE)
-            page.hline(mm(7), page.W, round(ry + mm(4)), 0.2, FAINT)
+            page.hline(rules_left or mm(7), page.W, round(ry + mm(4)), 0.2, FAINT)
     else:  # notes
         page.surface(0, inner, page.W, h - pt(4), b.surface)
 

docs/CLAUDE.md

@@ -39,7 +39,7 @@ needs a human *and* the user has chosen to defer PyPI for now (see *Not done*).
 uv sync --extra dev && uv run pytest && uv run ruff check .
 ```
 
-988 tests, all green, ruff clean. Sixty-odd commits on `main`, linear history,
+992 tests, all green, ruff clean. Sixty-odd commits on `main`, linear history,
 pushed to **[github.com/DocAtPrompt/ctrlgrid](https://github.com/DocAtPrompt/ctrlgrid)**
 (public); CI runs green there on Linux (3.11–3.13), macOS and Windows. Eleven
 presets — one per generator (`lines`, `dots`, `polar`, `form`, `maze`,

tests/test_calendar.py

@@ -23,9 +23,9 @@
     day_count,
     days_of_year,
 )
-from ctrlgrid.generators.calendar_layout import pt
+from ctrlgrid.generators.calendar_layout import FAINT, GUIDE, pt
 from ctrlgrid.loader import loads
-from ctrlgrid.marks import Area, Polygon, Text
+from ctrlgrid.marks import Area, Polygon, Segment, Text
 from ctrlgrid.pages import build
 from ctrlgrid.writers.pdf import PdfWriter
 
@@ -716,3 +716,44 @@ def test_the_hours_share_one_right_edge(self) -> None:
             for t in self._hours()
         }
         assert len(edges) == 1
+
+
+class TestDayBlockRules:
+    """The day's blocks share one left edge, and the schedule may rule halves."""
+
+    def _day(self, blocks):
+        pages, _dests, _edges = _graph(cfg(day={"blocks": blocks}))
+        return next(p for p in pages if p.dest == "day-2026-05-03")
+
+    def _rules(self, page, color):
+        """The writing rules only — a block's own top border spans the full
+        width from x=0, and is not one of them."""
+        return [m for m in page.marks
+                if isinstance(m, Segment) and m.color == color
+                and m.start.y == m.end.y and m.start.x > 0]
+
+    def test_the_blocks_start_their_rules_at_one_edge(self) -> None:
+        # An hour column and a column of tick boxes are different widths; left
+        # to themselves the two blocks ruled from different places.
+        day = self._day([
+            {"type": "schedule", "from": 7, "to": 12, "height": "50%"},
+            {"type": "todo", "rows": 4, "height": "rest"},
+        ])
+        assert len({m.start.x for m in self._rules(day, FAINT)}) == 1
+
+    def test_half_hours_are_off_by_default(self) -> None:
+        day = self._day([{"type": "schedule", "from": 7, "to": 12, "height": "100%"}])
+        assert len(self._rules(day, FAINT)) == 5      # one rule per hour
+        assert self._rules(day, GUIDE) == []          # no hierarchy, nothing louder
+
+    def test_half_hours_add_a_lighter_rule_between_the_hours(self) -> None:
+        day = self._day([
+            {"type": "schedule", "from": 7, "to": 12, "height": "100%", "half_hours": True}
+        ])
+        # The hour steps up to GUIDE so the half stays subordinate in FAINT.
+        assert len(self._rules(day, GUIDE)) == 5
+        assert len(self._rules(day, FAINT)) == 5
+
+    def test_half_hours_on_a_block_that_has_no_hours_is_refused(self) -> None:
+        with pytest.raises(ValidationError, match="belongs to a schedule block"):
+            cfg(day={"blocks": [{"type": "todo", "rows": 4, "half_hours": True}]})