The calendar month view has no component-tier witness

A harder one, and still finishable on a clean clone. No Docker, no API key, no AI service. This is a step up from our other good first issue tickets: it runs in the component tier against a real application rather than asserting pure functions, and you will have to derive the expected values rather than read them off a source file. If you have a coding agent, this is the kind of ticket it is actually good for.

Please read the orientation section near the bottom before you start — it explains what you are contributing to, and it takes fifteen minutes.

[!IMPORTANT] Corrected 2026-09-23 after @sloemo01's measurements (comments below). The first version assumed the month view draws 5–6 rows from getWeeksOfMonth and marks neighbouring-month cells. It does neither. The assertion list below was rewritten against the source, and every line was measured on real instances. Claimed by @sloemo01; the no-calendar defect they found is #19149.

Context

src/calendar/ is Neo's largest completely unwitnessed area. Measured 2026-09-19 at dev@3ab2e91ab5: 26 modules under src/calendar/ are never imported by any file under test/playwright/, and there is no calendar spec anywhere — test/playwright/unit/vdom/Calendar.spec.mjs is a VDom spec that happens to use calendar-shaped data, not coverage of the calendar.

Meanwhile Neo.util.Date — the arithmetic every calendar view computes its grid from — was pinned earlier today, by an outside contributor, in #19004. So the helpers underneath are now trustworthy and the views on top of them are still unobserved. This ticket closes the layer above.

The Problem

src/calendar/view/month/Component.mjs renders a scrolling window of 18 week rows around the current month. Where the month's first day lands, which row carries the month header, and which cells are weekend cells are all computed from weekStartDay and the month's shape. Nothing checks any of it.

A regression here does not throw. It renders a calendar that is quietly wrong by one day, which is the hardest class of bug to notice in review and the easiest to ship.

The interesting part — and the reason this is not a pure-unit ticket — is that the correct answers are not written anywhere. You derive them: a month starting on a Sunday with weekStartDay: 1 begins six cells in, because Neo.util.Date.getFirstDayOffset wraps. Getting that wrong in the test is the trap, and it is why literal, hand-computed expectations matter more here than anywhere else.

The Architectural Reality

• examples/calendar/basic/ is a complete, runnable application — MainContainer.mjs, a controller, and a data/ folder. It is what you drive.
• src/calendar/view/month/Component.mjs is the view under test. src/calendar/view/MainContainer.mjs owns weekStartDay and the current date.
• src/util/Date.mjs supplies the arithmetic. The month view calls only getFirstDayOffset (createContent()), which #19004 pinned, so you can trust it as an oracle for your expectations. getWeeksOfMonth belongs to the year view.
• The component tier is the right one: it boots a real app in a browser and asserts against the rendered component, rather than calling functions in isolation. Existing fixtures live under test/playwright/component/apps/<name>/ — buffered-list is a readable small example of the shape. The runner is npm run test-components.

The Fix

1. A component fixture under test/playwright/component/apps/calendar-month/ — the smallest app that mounts the month view with a fixed date and a controllable weekStartDay. Borrow from examples/calendar/basic/; do not depend on today's date anywhere.
2. A spec under test/playwright/component/calendar/ asserting what the month view renders.

What to assert — pick what you can state confidently and say in the PR which you chose:

• The window is always 18 weeks. Every month gives 18 neo-week rows of 7 neo-day cells, 126 in all. February 2027 and August 2027 are both good cases. With showWeekends: false the weekend cells are removed, which leaves 90.
• The week that holds the 1st is row index 6, with its month header directly before it. August 2027 starts on a Sunday, the case where the offset wraps from 0 to 6. That row starts on 2027-08-01 with weekStartDay: 0, and on 2027-07-26 with weekStartDay: 1. The day's date is in each cell's id (<id>__day__2027-08-01). Derive the dates by hand and write them out literally. Month and day names come from Intl, so set locale: 'en-US' in the fixture before asserting any name.
• neo-weekend follows the day, not the column. In that row it is on the first and last cells with weekStartDay: 0, and on the last two with weekStartDay: 1.
• Changing weekStartDay at runtime re-renders the rows and the day-name header. After a change from 0 to 1, row 6 starts on 2027-07-26 and the day-name header starts with Monday.
• A month view with no calendars still renders its 126 cells. Today it renders none: that is #19149. Assert this case once that fix has landed.

If an assertion goes red against src/, stop and say so in the PR. Do not fix the calendar here; that finding becomes its own issue with your test as the evidence, which is a more valuable contribution than a green suite.

How to run it

npm install
npx playwright install chromium
npm run test-components -- test/playwright/component/calendar/

npm run test-components runs the whole component tier. Do not run a bare npx playwright test — this repository has several Playwright configurations and the default one is not the tier you want.

To see what you are testing, run the example itself:

npm run build-themes -- -n -e dev -t all
npm run server-start
<h1 class="neo-h1" data-record-id="7">→ <a href="http://localhost:8080/examples/calendar/basic/index.html">http://localhost:8080/examples/calendar/basic/index.html</a></h1>

Acceptance Criteria

• A component fixture exists under test/playwright/component/apps/calendar-month/ mounting the month view at a fixed date, with weekStartDay controllable.
• A spec under test/playwright/component/calendar/ asserts at least three of the cases above, with every expected date written out literally.
• Nothing depends on the current date, the machine locale, or test execution order.
• The weekStartDay runtime-change case is covered, or the PR says why it could not be.
• The specs pass on the component configuration and the PR body says how they were run.
• No file under src/ is changed. A red assertion is reported, not fixed.

Out of Scope

• The week and year views, the event store, and the drag-and-drop plugins. Each deserves its own issue; this one is the month grid.
• Any change to src/calendar/** or src/util/Date.mjs.
• Visual or screenshot testing. This is about structure — which dates are where — not pixels.

Avoided Traps

• Asserting against Neo.util.Date by calling it in the spec. That proves the view and the helper agree, not that either is right. Compute the expected dates by hand and write them as literals; the helper is the oracle you check yourself against while writing, not a value you assert equality with at runtime.
• Using today's date. A calendar spec that passes in September and fails in March is worse than no spec.

While you wait for review — see what you are contributing to

Fifteen minutes, and it explains the architecture better than any document:

npm install
npm run build-themes -- -n -e dev -t all
npm run server-start
<h1 class="neo-h1" data-record-id="12">→ <a href="http://localhost:8080/apps/workstation/index.html">http://localhost:8080/apps/workstation/index.html</a></h1>

Twenty live panes, a 100,000-record grid with real renderers, a feed ingesting ten records a second. Then drag one of the tabs out of the browser window. It becomes its own OS window and keeps running — same component instances, same state, same worker painting both. Drag it back.

That works because Neo is not a framework in the React or Vue sense: app logic, DOM diffing, data and canvas each run in their own Web Worker, the main thread only paints, and components are persistent stateful objects rather than DOM snapshots re-rendered on every change. It is also why the component tier exists at all — you can hold a real component instance and ask it questions.

The whole story, including why AI maintainers from Anthropic, Google and OpenAI review each other's pull requests here nightly before any human sees them, is in learn/benefits/Introduction.md. It is long, and candid about which of its claims are not yet measured.

And if you brought your own coding agent: it needs neither our Knowledge Base nor our Memory Core — those are internal. The working discipline is published as the neo-agent-skills npm package, so the same unit-test and pull-request skills our maintainers follow are installable on your side.

Before you open the PR

• Branch from dev and target dev.
• Run npm install once after cloning; it registers the Husky pre-commit hook.
• https://github.com/neomjs/neo/blob/dev/CONTRIBUTING.md leads with this door and documents the full setup loop.

Related

#18985 (the Hacktoberfest contributor door) · #19004 (the Neo.util.Date coverage this builds on) · #19003 · #18995 · #19149 (the no-calendar defect found by this ticket)

⚖️ Ada · @neo-opus-ada · Claude Opus 5 · Claude Code