Skip to content

CRAFT-1987: chore(docs): RangeCalendar engineering docs #800

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
stephsprinkle merged 3 commits into from
Dec 16, 2025
Merged

CRAFT-1987: chore(docs): RangeCalendar engineering docs #800

stephsprinkle merged 3 commits into from
Dec 16, 2025

Conversation

@misama-ct
Copy link
Collaborator

@misama-ct misama-ct commented Dec 9, 2025

Summary

  • Add comprehensive engineering documentation for the RangeCalendar component (range-calendar.dev.mdx)
  • Add consumer-facing documentation tests (range-calendar.docs.spec.tsx)
  • Update live-code-editor to expose parseZonedDateTime, today, and getLocalTimeZone utilities from @internationalized/date for interactive documentation examples

Documentation Contents

Engineering Guide (range-calendar.dev.mdx)

Getting Started:

  • Import examples and basic usage patterns

Working with Date Values:

  • Date value types (CalendarDate from @internationalized/date)
  • Creating and parsing date values
  • Converting to ISO strings for API consumption
  • Date range structure (RangeValue<DateValue>)

Usage Examples:

  • Multi-month display with visibleDuration
  • Paging behavior (single vs visible)
  • Date constraints (minValue, maxValue)
  • Unavailable dates with isDateUnavailable
  • Non-contiguous ranges with allowsNonContiguousRanges
  • Custom week start with firstDayOfWeek
  • Form states (disabled, read-only)
  • Controlled and uncontrolled modes
  • Internationalization with NimbusI18nProvider

Component Requirements:

  • Date value type requirements
  • Accessibility guidelines (aria-label, keyboard navigation)

Common Patterns:

  • Booking period selection example
  • Business days only selection example

Documentation Tests (range-calendar.docs.spec.tsx)

Consumer-facing test examples covering:

  • Basic rendering (grid, navigation buttons, date cells)
  • Interactions (navigation between months/years)
  • Controlled mode (value display, null handling)
  • Component states (disabled, read-only)
  • Date constraints (min/max values, unavailable dates, multi-month display)

Live Code Editor Updates

Added exports needed for live documentation examples:

  • parseZonedDateTime
  • today
  • getLocalTimeZone

Test plan

  • Verify documentation renders correctly on the docs site
  • Verify all live code examples are interactive and functional
  • Verify documentation tests pass: pnpm test packages/nimbus/src/components/range-calendar/range-calendar.docs.spec.tsx
  • Verify tests are injected into .dev.mdx documentation at build time

🤖 Generated with Claude Code

@changeset-bot
Copy link

changeset-bot bot commented Dec 9, 2025 •
edited
Loading

⚠️ No Changeset found

Latest commit: f6cb159

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@vercel
Copy link

vercel bot commented Dec 9, 2025 •
edited
Loading

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Review Updated (UTC)
nimbus-documentation Ready Ready Preview, Comment Dec 16, 2025 6:17pm
nimbus-storybook Ready Ready Preview, Comment Dec 16, 2025 6:17pm

@misama-ct misama-ct changed the title chore(docs): RangeCalendar engineering docs CRAFT-1987: chore(docs): RangeCalendar engineering docs Dec 9, 2025
@misama-ct misama-ct requested review from a team, ByronDWall, ddouglasz, jaikamat, stephsprinkle, tylermorrisford and valoriecarli and removed request for a team December 9, 2025 13:42
@jaikamat jaikamat added the documentation Improvements or additions to documentation label Dec 9, 2025
misama-ct and others added 2 commits December 12, 2025 10:28
@misama-ct @claude
chore(docs): RangeCalendar engineering docs
e5db90a 
Add comprehensive engineering documentation for the RangeCalendar component
including implementation guides, working with date values, usage examples,
and consumer-facing test patterns.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@misama-ct @claude
fix: remove unused waitFor import in RangeCalendar docs spec
b32c19c 
Removed unused waitFor import from @testing-library/react that was causing a linting error.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@misama-ct misama-ct force-pushed the CRAFT-1987-nimbus-engineering-docs-range-calendar branch from d757af3 to b32c19c Compare December 12, 2025 09:35
tylermorrisford
tylermorrisford approved these changes Dec 16, 2025
View reviewed changes
Copy link
Contributor

@tylermorrisford tylermorrisford left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Very nice, very nice indeed

stephsprinkle
stephsprinkle approved these changes Dec 16, 2025
View reviewed changes
Copy link
Contributor

@stephsprinkle stephsprinkle left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A few nits. Generally, I have a question about how the range calendar is being displayed. Sometimes it takes up the entire width of the container, other times it's part of the container, then it's wildin' with the multi-month display. Obviously not a docs problem (or maybe it is??). @ByronDWall @valoriecarli would love your thoughts.

Image Image

packages/nimbus/src/components/range-calendar/range-calendar.dev.mdx

return (
<Stack direction="column" gap="400">
<Text textStyle="sm" color="neutral.11">
Copy link
Contributor

@stephsprinkle stephsprinkle Dec 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want all of these informational blurbs to be bolded? Or at least have them all be consistent?

Copy link
Collaborator

@valoriecarli valoriecarli Dec 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am leaning towards bold, but after further inspection, I am going to add this to the misc ticket to ensure whatever decision we make is consistent

I see we have a few scattered about, so ill straighten it out and give them all a docs label (regardless of category).

Copy link
Contributor

@stephsprinkle stephsprinkle Dec 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok let's tackle it as a larger effort 👍

packages/nimbus/src/components/range-calendar/range-calendar.dev.mdx Outdated
}
}}
/>
<Text textStyle="sm">{selectedRange}</Text>
Copy link
Contributor

@stephsprinkle stephsprinkle Dec 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be cool if the selected range was displayed the same in both examples

Image

Copy link
Collaborator

@valoriecarli valoriecarli Dec 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

completed with f6cb159, there might be other places to update as well if youd like them all to be consistent.

@valoriecarli
Copy link
Collaborator

valoriecarli commented Dec 16, 2025

A few nits. Generally, I have a question about how the range calendar is being displayed. Sometimes it takes up the entire width of the container, other times it's part of the container, then it's wildin' with the multi-month display. Obviously not a docs problem (or maybe it is??). @ByronDWall @valoriecarli would love your thoughts.
Image Image

@stephsprinkle .. after a cursory review, i see that this pattern is ofc replicated in Calendar as well (looking through Storybook).
This pattern might have been deliberate at the time, but we might want to revisit it:

Ill go ahead and create a ticket to follow up on this

@stephsprinkle stephsprinkle merged commit 71353d1 into main Dec 16, 2025
12 checks passed
@stephsprinkle stephsprinkle deleted the CRAFT-1987-nimbus-engineering-docs-range-calendar branch December 16, 2025 19:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@stephsprinkle stephsprinkle stephsprinkle approved these changes

@tylermorrisford tylermorrisford tylermorrisford approved these changes

@jaikamat jaikamat Awaiting requested review from jaikamat jaikamat was automatically assigned from commercetools/craft-team-fe-tag-all

@ddouglasz ddouglasz Awaiting requested review from ddouglasz ddouglasz was automatically assigned from commercetools/craft-team-fe-tag-all

@valoriecarli valoriecarli Awaiting requested review from valoriecarli valoriecarli was automatically assigned from commercetools/craft-team-fe-tag-all

@ByronDWall ByronDWall Awaiting requested review from ByronDWall ByronDWall was automatically assigned from commercetools/craft-team-fe-tag-all

Assignees

@misama-ct misama-ct

Labels

documentation Improvements or additions to documentation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

6 participants

@misama-ct @valoriecarli @stephsprinkle @tylermorrisford @jaikamat