Documentation
Year Planner for React is a source-available React component for long-range annual planning. This page is the entry point for the developer guides.
Documentation map
| Topic | Page |
|---|---|
| Getting started | getting-started.md |
| Classic year layout | classic-year-layout.md |
| Controlled API | controlled-api.md |
| Visibility semantics | visibility.md |
| Selection and keyboard | interaction.md (keyboard map: accessibility.md) |
| Theming | theming.md |
| Localization | localization.md |
| Customization and holidays | customization.md |
| Inspector and tooltip | inspector-tooltip.md |
| Dynamic months | dynamic-months.md |
| print.md | |
| Accessibility status | accessibility.md |
| Browser test selection and sharding | browser-tests.md |
| Performance status | performance.md |
| Limitations | limitations.md |
| Migration | migration.md |
| FAQ | faq.md |
| Licence and permitted uses | licensing.md |
Reference and evidence
- Controlled command lifecycle — validation, outcomes, retries and rollback.
- Architecture — the package and documentation pipeline.
- Security notes — XSS, CSP, hidden data, dependencies and accepted risk.
- Test report — commands, counts, browser matrix and known gaps.
- Benchmarks — measured layout and browser performance.
- ADR 0001 — the HTML/CSS renderer decision.
- Deferred capabilities — what R1 does not implement.
Published sites
The documentation site is one GitHub Pages artifact:
| Path | Content |
|---|---|
/year-planner/ | VitePress home, guide, tutorials, how-tos and examples |
/year-planner/storybook/ | The static Storybook catalogue |
/year-planner/api/ | The generated TypeDoc reference |
/year-planner/localization.html | Languages and message overrides |
This is a project site, so the base path is /year-planner/. There is no custom domain. The repository is public, Pages is enabled with GitHub Actions, and the site is live at https://blendsdk.github.io/year-planner/. The build accepts DOCS_BASE_PATH=/ when a custom domain is added later.
Publishing the site
The docs-site workflow builds the combined artifact. Pushing to main builds and uploads it; publication stays a manual workflow_dispatch run with deploy: true from main. The one-time setup is complete: the repository is public, Pages uses GitHub Actions, and the github-pages environment is configured. The build does not depend on a stored secret; the deploy job uses the GitHub OIDC token. The uploaded artifact is docs/.vitepress/dist.
Building the site locally
pnpm docs:dev # VitePress at /year-planner/
pnpm docs:site # packages, Storybook, TypeDoc, VitePress, copy, verify
pnpm docs:site -- --check-only # verify the last build without rebuilding
pnpm docs:preview # preview the last VitePress buildThe VitePress dev server proxies /year-planner/storybook to a Storybook dev server on http://localhost:6006, so the live examples work while you edit either side. Run pnpm storybook in another terminal.
Package status
The packages are published to npm at 0.3.2 with provenance. 0.3.0 was the unprovenanced bootstrap that created the package names. Install the component with pnpm add @blendsdk/react-year-planner; see getting-started.md.