Repository navigation
docs(i18n): calendars guide, with Calendars nested under Internationalization - #9625
nynexman4464 wants to merge 20 commits into
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
meta-cla
Bot
added
the
CLA Signed
|
AI review status for this pull request.
|
github-actions
Bot
added
the
needs:spec-owner-review
PR Analysis Report🔎 Preview ·
|
![astracat-bot[bot]](https://avatars.githubusercontent.com/in/4796231?s=60&v=4){kind=small}
There was a problem hiding this comment.
This can't be approved yet. It rewrites architecture:internationalization INV10 and adds new Calendar and InternationalizationProvider spec clauses and public API that rest on the still-draft spec:AST-111. An engineering owner needs to approve that direction by commenting /approve-spec <full head SHA>, and the author can do this as an engineering owner. Separately, these need fixing:
- Where
Temporalis native, Chinese and Korean day buttons are named one day off from the number they show on 9 Chinese and 4 Korean month starts (2027-02-06 shows 1 but is announced "Twelfth Month 30, 2026"), so the guide's "Each environment agrees with itself" does not hold yet. - A provider
calendaralso switches the Calendar inside DateInput, DateRangeInput and DateTimeInput while their fields stay Gregorian, so keep those popovers Gregorian for now and narrow the guide's "Date components…" wording toCalendar. - The branch still carries all of #9622 (about 2,300 authored lines); rebasing after #9622 lands, or retargeting the base to its branch, leaves only the 175-line guide.
- AST-013 FR10 asks for real-browser evidence of the
Temporalfallback, and the fallback warning should mention aTemporalthat lacks the calendar (such as the defaulttemporal-polyfillbuild), not only a missing one.
[Automated review]
| } | ||
|
|
||
| /** A day's full label, such as "Friday, Aban 8, 1405 AP", in the calendar. */ | ||
| function formatDateLabel( |
There was a problem hiding this comment.
Day names come from Intl.DateTimeFormat here, but the visible day number comes from Temporal (useCalendarMonthDays). Where Temporal is native, the two disagree for chinese and dangi on 9 and 4 month starts between 1900 and 2100. In Chromium 149, 2027-02-06 shows 1 in First Month 2027 but is named "Saturday, Twelfth Month 30, 2026". Building the name from the grid's own day number (for example, formatToParts of the month's middle day with the day and weekday parts replaced) keeps the two in step.
| items: [ | ||
| 'Native `Temporal` in Chrome, Edge, Firefox, and Node.js 26 agrees with official observatory data from 1900 through 2100.', | ||
| "A polyfill reads the platform's `Intl` data instead. Under a polyfill, Node.js 24 starts nine Chinese and four Korean months in that range one day apart from the native result: Chinese New Year 2027 is February 6 with native `Temporal` and February 7 under the polyfill. Safari uses the same kind of `Intl` data, so expect the same differences there.", | ||
| 'Each environment agrees with itself: what a person sees and picks is consistent in their browser. Only two different runtimes can disagree.', |
There was a problem hiding this comment.
Not true yet where Temporal is native: Calendar's day names come from Intl, which disagrees with native Temporal on the same Chinese and Korean month starts this list describes. A screen reader hears a different date than the one shown.
| content: [ | ||
| { | ||
| type: 'prose', | ||
| text: 'Date components show the Gregorian calendar unless you choose another one. Pass `calendar` to `<InternationalizationProvider>` to set it for a subtree. A locale with an explicit `-u-ca-` keyword, such as `th-TH-u-ca-buddhist`, selects its calendar too. A locale on its own never changes the calendar: `fa-IR` shows Gregorian dates in Persian until you pass `calendar="persian"`.', |
There was a problem hiding this comment.
At this head only Calendar follows the calendar. DateInput, DateRangeInput and DateTimeInput keep Gregorian fields while their popover Calendar follows the provider: the field reads "October 30, 2026" and the popover reads "Aban 1405". Either keep those popovers Gregorian for now, or name Calendar here and in "A date component also takes its own calendar".
| warnOnce( | ||
| `calendar-unavailable:${calendar}`, | ||
| source, | ||
| `The "${calendar}" calendar needs Temporal, which this runtime does not ` + |
There was a problem hiding this comment.
This message also fires when Temporal exists but lacks the calendar. The default temporal-polyfill build throws "Unknown calendar persian; might need temporal-polyfill/full". Wording such as "needs a Temporal that supports it, such as temporal-polyfill/full/global" covers both cases.
There was a problem hiding this comment.
This guide can't be approved yet: it documents the calendar prop and non-Gregorian Calendar grids, which current architecture:internationalization INV10 still rules out, and the records that would allow them (the spec edits in #9622 and the draft spec:AST-111 in #9605) are not approved. An engineering owner needs to decide whether the guide waits for those records to land on main or may document that direction now, and records the decision by commenting /approve-spec <full head SHA> on this pull request; the author can do this as an engineering owner. Separately, two fixes are needed whatever the decision:
- The new doc and summary fail six CLI golden snapshot tests (
docs-list.json, anddocs-tree.json,search-icon-set.json,doctor-doc-counts.txtanddoctor-installed-set.jsonunderno-icon-set/), so regenerate them with vitest's update flag and commit the diff. - The "Within one browser … agree" bullet does not hold with native
Temporal:Calendarnames days withIntlbut numbers them fromTemporal, so on 9 Chinese and 4 Korean months (2027-02-06, for example) a screen reader hears a date one day off from the number shown.
[Automated review]
| items: [ | ||
| 'Native `Temporal` in Chrome, Edge, Firefox, and Node.js 26 agrees with official observatory data from 1900 through 2100.', | ||
| "A polyfill reads the platform's `Intl` data instead. Under a polyfill, Node.js 24 starts nine Chinese and four Korean months in that range one day apart from the native result: Chinese New Year 2027 is February 6 with native `Temporal` and February 7 under the polyfill. Safari uses the same kind of `Intl` data, so expect the same differences there.", | ||
| 'Within one browser, the day numbers a person sees, the dates a screen reader announces, and the value they pick agree. Only two different runtimes can disagree.', |
There was a problem hiding this comment.
With native Temporal this does not hold yet. Calendar numbers each day from the Temporal month but names it with Intl.DateTimeFormat, and the two disagree on 9 Chinese and 4 Korean month starts between 1900 and 2100. On 2027-02-06 the grid shows 1 while the day is named "Saturday, Twelfth Month 30, 2026". Either fix the day names in #9622 first, or say here that a screen reader can announce those month starts one day off with native Temporal.
| lang: 'ts', | ||
| label: 'Load the polyfill only where Temporal is missing', | ||
| code: `// temporal-setup.ts: import before your app renders, on the server and in the browser | ||
| if (typeof globalThis.Temporal === 'undefined') { |
There was a problem hiding this comment.
Non-blocking: under tsc --strict with lib: ["es2022", "dom"] this line fails with TS7017, because globalThis has no Temporal there and the polyfill's full/global types declare none. if (!('Temporal' in globalThis)) type-checks under any lib.
| title: 'Internationalization', | ||
| summary: | ||
| 'Set the active locale, load catalogs, coexist with your own i18n library, handle RTL, and test translations.', | ||
| 'Set the active locale, load catalogs, coexist with your own i18n library, show other calendars, handle RTL, and test translations.', |
There was a problem hiding this comment.
This summary is pinned in packages/cli/test/__golden__/docs-list.json, and the new guide also changes docs-tree.json, search-icon-set.json, doctor-doc-counts.txt and doctor-installed-set.json under __golden__/no-icon-set/. Six snapshot tests fail until they are regenerated (vitest run packages/cli/test/experimental-isolation.test.mjs --update and vitest run -u packages/cli/test/golden-reads.test.mjs).
ef65980 to
3847801
Compare
There was a problem hiding this comment.
This guide can't be approved yet: it documents the calendar prop and non-Gregorian Calendar grids, which current architecture:internationalization INV10 still rules out, and the records that would allow them (the spec edits in #9622 and the draft spec:AST-111 in #9605) are not approved. An engineering owner needs to decide whether the guide waits for those records to land on main or may document that direction now, and records the decision by commenting /approve-spec <full head SHA> on this pull request (the author may do so as an engineering owner); separately, this needs fixing whatever the decision:
- The new doc and namespace summary fail six CLI golden snapshot tests (
docs-list.json, anddocs-tree.json,search-icon-set.json,doctor-doc-counts.txtanddoctor-installed-set.jsonunderno-icon-set/), so regenerate them with vitest's update flag and commit the diff.
The earlier concern about spoken and shown Chinese and Korean dates is resolved by #9622's day-label fix. Optionally, if (!('Temporal' in globalThis)) in the polyfill snippet type-checks without the esnext lib.
[Automated review]
There was a problem hiding this comment.
This can't be approved yet: both guides document the calendar prop and non-Gregorian Calendar grids, which current architecture:internationalization INV10 still rules out, and the records that would allow them (#9622's spec edits and the draft spec:AST-111 in #9605) are not approved.
An engineering owner needs to decide whether the guides wait for those records to land on main or may document that direction now, and records the decision by commenting /approve-spec <full head SHA> on this pull request (the author can do this as an engineering owner); separately, these need fixing whatever the decision:
- Five snapshots in
packages/cli/test/experimental-isolation.test.mjsstill fail (docs-tree.json,search-icon-set.jsontwice,doctor-doc-counts.txtanddoctor-installed-set.jsonunder__golden__/no-icon-set/), so regenerate them with vitest's--updateflag and commit the diff. core-doc-quality.test.mjs("repeat no passage word for word") fails because line 30 ofi18n-calendars.doc.mjsrepeats the opening ofcalendar-systems.doc.mjsline 30 word for word, so reword the short guide's opening.- Line 42 of
calendars.doc.mjssays date components follow the application's calendar, but DateInput, DateRangeInput and DateTimeInput keep Gregorian popovers, so nameCalendarthere and say the date inputs stay Gregorian.
Optionally, if (!('Temporal' in globalThis)) in the polyfill snippet type-checks without the esnext lib.
[Automated review]
| blocks: [ | ||
| { | ||
| type: 'prose', | ||
| text: 'Date components show the Gregorian calendar unless the application chooses another one. Values never change with the calendar: they stay Gregorian ISO dates. {@link generic:i18n-calendars} has the short version.', |
There was a problem hiding this comment.
DateInput, DateRangeInput and DateTimeInput pass calendar="gregory" to their popover Calendar on #9622's branch, so they stay Gregorian when the provider sets calendar. Suggested wording: "Calendar shows the Gregorian calendar unless the application chooses another one; DateInput, DateRangeInput and DateTimeInput stay Gregorian."
| content: [ | ||
| { | ||
| type: 'prose', | ||
| text: '`Calendar` shows the Gregorian calendar unless you choose another one. Pass `calendar` to `<InternationalizationProvider>` for a subtree, or to `Calendar` itself. Values stay Gregorian ISO dates (`YYYY-MM-DD`) in every calendar.', |
There was a problem hiding this comment.
This opening repeats calendar-systems.doc.mjs line 30 word for word, and core-doc-quality.test.mjs ("repeat no passage word for word") fails on it. Rewording it keeps the fact in one place, for example: "Set calendar on <InternationalizationProvider> for a subtree, or on Calendar itself; without it, Calendar is Gregorian."
| lang: 'ts', | ||
| label: 'Load the polyfill only where Temporal is missing', | ||
| code: `// temporal-setup.ts: import before your app renders, on the server and in the browser | ||
| if (typeof globalThis.Temporal === 'undefined') { |
There was a problem hiding this comment.
Non-blocking: under tsc --strict with lib: ["es2022", "dom"] this line fails with TS7017. if (!('Temporal' in globalThis)) type-checks under any lib.
nynexman4464
changed the title
There was a problem hiding this comment.
This can't be approved yet. It amends spec:AST-046 FR14 so the docsite can give a nested namespace its own page, which the description notes needs the owner's approval, and both guides document non-Gregorian Calendar grids that current architecture:internationalization INV10 still rules out, while #9622's record edits and the draft spec:AST-111 in #9605 are unapproved. An engineering owner needs to approve the FR14 amendment and decide whether the guides may document the calendar direction now or wait for those records, and records the decision by commenting /approve-spec <full head SHA> on this pull request (the author can do this as an engineering owner).
These need fixing whatever the decision:
- Five snapshots in
packages/cli/test/experimental-isolation.test.mjsfail (docs-tree.json,search-icon-set.jsontwice,doctor-doc-counts.txtanddoctor-installed-set.jsonunder__golden__/no-icon-set/), so regenerate them with vitest's--updateflag and commit the diff. core-doc-quality.test.mjs("repeat no passage word for word") fails because line 30 ofi18n-calendars.doc.mjsrepeats the opening of line 30 ofcalendar-systems.doc.mjs, so reword the short guide's opening.- Line 45 of
calendars.doc.mjssays date components follow the application's calendar, but DateInput, DateRangeInput and DateTimeInput stay Gregorian, so nameCalendarthere.
Optionally, keep the sidebar parent open when Calendars opens without a reload, write the polyfill check as if (!('Temporal' in globalThis)) so it type-checks under any lib, and call the short guide "Other calendars" in the changeset.
[Automated review]
| blocks: [ | ||
| { | ||
| type: 'prose', | ||
| text: 'Date components show the Gregorian calendar unless the application chooses another one. Values never change with the calendar: they stay Gregorian ISO dates. {@link generic:i18n-calendars} has the short version.', |
There was a problem hiding this comment.
DateInput, DateRangeInput and DateTimeInput pass calendar="gregory" to their popover Calendar (DateInput.tsx line 1028, DateRangeInput.tsx line 870, DateTimeInput.tsx line 1974), so they stay Gregorian when the provider sets calendar. Suggested wording: "Calendar shows the Gregorian calendar unless the application chooses another one; DateInput, DateRangeInput and DateTimeInput stay Gregorian."
| content: [ | ||
| { | ||
| type: 'prose', | ||
| text: '`Calendar` shows the Gregorian calendar unless you choose another one. Pass `calendar` to `<InternationalizationProvider>` for a subtree, or to `Calendar` itself. Values stay Gregorian ISO dates (`YYYY-MM-DD`) in every calendar.', |
There was a problem hiding this comment.
This opening repeats line 30 of calendar-systems.doc.mjs word for word, and core-doc-quality.test.mjs ("repeat no passage word for word") fails on it. For example: "Set calendar on <InternationalizationProvider> for a subtree, or on Calendar itself; without it, Calendar is Gregorian."
| { | ||
| "topic": "internationalization", | ||
| "description": "Set the active locale, load catalogs, coexist with your own i18n library, handle RTL, and test translations.", | ||
| "description": "Set the active locale, load catalogs, coexist with your own i18n library, show other calendars, handle RTL, and test translations.", |
There was a problem hiding this comment.
The new docs also change five snapshots under __golden__/no-icon-set/ (docs-tree.json, search-icon-set.json, doctor-doc-counts.txt, doctor-installed-set.json), and experimental-isolation.test.mjs fails until they are regenerated: vitest run packages/cli/test/experimental-isolation.test.mjs --update.
| href={`/docs/${page.topic}`} | ||
| isSelected={pathname === `/docs/${page.topic}`} | ||
| collapsible={{ | ||
| defaultIsCollapsed: !children.some( |
There was a problem hiding this comment.
Non-blocking: SideNavItem reads defaultIsCollapsed once, and DocsShell stays mounted across navigations, so opening Calendars from another guide page without a reload (as the docs search does) leaves Internationalization collapsed and the open page's entry hidden. Controlling isCollapsed from the pathname, with a local override, would keep the open page visible.
| lang: 'ts', | ||
| label: 'Load the polyfill only where Temporal is missing', | ||
| code: `// temporal-setup.ts: import before your app renders, on the server and in the browser | ||
| if (typeof globalThis.Temporal === 'undefined') { |
There was a problem hiding this comment.
Non-blocking: under tsc --strict with lib: ["es2022", "dom"] this line fails with TS7017. if (!('Temporal' in globalThis)) type-checks under any lib.
There was a problem hiding this comment.
This can't be approved yet: it amends spec:AST-046 FR14 so the docsite can give a nested namespace its own page and nest any page under a parent in the sidebar, and both guides document non-Gregorian Calendar grids that current architecture:internationalization INV10 still rules out, while #9622's record edits and the draft spec:AST-111 in #9605 are unapproved. An engineering owner needs to approve the FR14 amendment (including moving Icon sets under Icons and Styling components under Styling overview) and decide whether the guides may document the calendar direction now or wait for those records, recording the decision by commenting /approve-spec <full head SHA> on this pull request (the author can do this as an engineering owner).
These need fixing whatever the decision:
- Five snapshots in
packages/cli/test/experimental-isolation.test.mjsfail (docs-tree.json,search-icon-set.jsontwice,doctor-doc-counts.txtanddoctor-installed-set.jsonunder__golden__/no-icon-set/), so regenerate them with vitest's--updateflag and commit the diff. core-doc-quality.test.mjs("repeat no passage word for word") fails because line 30 ofi18n-calendars.doc.mjsrepeats the opening of line 30 ofcalendar-systems.doc.mjs, so reword the short guide's opening.- Line 45 of
calendars.doc.mjssays date components follow the application's calendar, but DateInput, DateRangeInput and DateTimeInput stay Gregorian, so nameCalendarthere. - The new FR14 sentence (lines 279-281 of
docs/specs/AST-046-docs-tree/spec.md) says a page with a sidebar parent keeps "its own group" and also sits "in the parent's group", so say it keeps itscategoryand shows in the parent's group.
Optionally, keep a sidebar parent open when its child page opens without a reload, write the polyfill check as if (!('Temporal' in globalThis)) so it type-checks under any lib, and call the short guide "Other calendars" in the changeset.
[Automated review]
| blocks: [ | ||
| { | ||
| type: 'prose', | ||
| text: 'Date components show the Gregorian calendar unless the application chooses another one. Values never change with the calendar: they stay Gregorian ISO dates. {@link generic:i18n-calendars} has the short version.', |
There was a problem hiding this comment.
DateInput, DateRangeInput and DateTimeInput pass calendar="gregory" to their popover Calendar on #9622's branch, so they stay Gregorian when the provider sets calendar. Suggested wording: "Calendar shows the Gregorian calendar unless the application chooses another one; DateInput, DateRangeInput and DateTimeInput stay Gregorian."
| content: [ | ||
| { | ||
| type: 'prose', | ||
| text: '`Calendar` shows the Gregorian calendar unless you choose another one. Pass `calendar` to `<InternationalizationProvider>` for a subtree, or to `Calendar` itself. Values stay Gregorian ISO dates (`YYYY-MM-DD`) in every calendar.', |
There was a problem hiding this comment.
This opening repeats line 30 of calendar-systems.doc.mjs word for word, and core-doc-quality.test.mjs ("repeat no passage word for word") fails on it. For example: "Set calendar on <InternationalizationProvider> for a subtree, or on Calendar itself; without it, Calendar is Gregorian."
| { | ||
| "topic": "internationalization", | ||
| "description": "Set the active locale, load catalogs, coexist with your own i18n library, handle RTL, and test translations.", | ||
| "description": "Set the active locale, load catalogs, coexist with your own i18n library, show other calendars, handle RTL, and test translations.", |
There was a problem hiding this comment.
The new docs also change five snapshots under __golden__/no-icon-set/ (docs-tree.json, search-icon-set.json, doctor-doc-counts.txt, doctor-installed-set.json), and experimental-isolation.test.mjs fails until they are regenerated: vitest run packages/cli/test/experimental-isolation.test.mjs --update.
| docsite MAY name a sidebar parent page for any page: the page keeps its | ||
| slug and its own group, and its sidebar entry sits under the parent's | ||
| entry, in the parent's group. Sidebar nesting is one level deep. A |
There was a problem hiding this comment.
FR14 uses "group" for the sidebar group, so for Icon sets (a Guide page under Icons in Foundations) this sentence asks for both its own group and the parent's. Suggested: "the page keeps its slug and its category; its sidebar entry sits under the parent's entry, in the parent's group."
| key={page.topic} | ||
| {...docLink(page)} | ||
| collapsible={{ | ||
| defaultIsCollapsed: !children.some( |
There was a problem hiding this comment.
Non-blocking: SideNavItem reads defaultIsCollapsed once, and DocsShell stays mounted in the docs layout, so opening Calendars, Icon sets or Styling components without a reload (the search palette pushes the route) leaves the parent collapsed and the open page's entry hidden. Controlling isCollapsed from the pathname, or keying the parent on whether a child is open, keeps it visible.
| lang: 'ts', | ||
| label: 'Load the polyfill only where Temporal is missing', | ||
| code: `// temporal-setup.ts: import before your app renders, on the server and in the browser | ||
| if (typeof globalThis.Temporal === 'undefined') { |
There was a problem hiding this comment.
Non-blocking: under tsc --strict with lib: ["es2022", "dom"] this line fails with TS7017. if (!('Temporal' in globalThis)) type-checks under any lib.
| '@astryxdesign/cli': patch | ||
| --- | ||
|
|
||
| [docs] Internationalization gains a short Calendars guide: choose a calendar on `InternationalizationProvider` or `Calendar`, values stay Gregorian ISO dates, and most calendars need `Temporal` (load `temporal-polyfill/full/global` where it is missing). A new `astryx docs internationalization/calendars` namespace has the detail: the supported calendars, loading `Temporal` on the server and in the browser, why the Chinese and Korean calendars can differ by a day between runtimes, and ISO 8601 week numbers. |
There was a problem hiding this comment.
Non-blocking: the short guide is titled "Other calendars"; Calendars is the namespace. Suggested: "Internationalization gains a short Other calendars guide".
c13e940 to
53da574
Compare
4943c1a to
0dfdec0
Compare
There was a problem hiding this comment.
This can't be approved yet: both guides document non-Gregorian Calendar grids and navigation, which current architecture:internationalization INV10 still keeps Gregorian (the records that would change it, in #9622 and the draft spec:AST-111 in #9605, are unapproved), and the PR amends spec:AST-046 FR14 so the docsite can give a nested namespace its own page and nest any page under a parent in the sidebar. An engineering owner needs to (1) approve or amend the FR14 amendment, including moving Icon sets under Icons and Styling components under Styling overview, and (2) decide whether the guides may document the calendar direction now or wait for those records; they record the decision by commenting /approve-spec <full head SHA> on this pull request, and the author may do so as an engineering owner.
These need fixing whatever the decision:
- Five snapshots in
packages/cli/test/experimental-isolation.test.mjsfail (docs-tree.json,search-icon-set.jsontwice,doctor-doc-counts.txtanddoctor-installed-set.jsonunder__golden__/no-icon-set/), so regenerate them with vitest's--updateflag and commit the diff. core-doc-quality.test.mjs("repeat no passage word for word") fails because line 30 ofi18n-calendars.doc.mjsrepeats the opening of line 30 ofcalendar-systems.doc.mjs, so reword the short guide's opening.- Line 45 of
calendars.doc.mjssays date components follow the application's calendar, but DateInput, DateRangeInput and DateTimeInput stay Gregorian, so nameCalendarthere. - The new FR14 sentence (
spec.mdlines 279-281) says a nested page keeps "its own group" and also sits "in the parent's group", so say the page keeps its slug andcategoryand its entry sits in the parent's group. DocsShell.tsxlines 181-185 set the parent's collapse state only once, so opening Calendars, Icon sets or Styling components from search leaves the parent collapsed and no sidebar entry marked as the current page; derive the collapsed state from the path instead.
Two small optional fixes: if (!('Temporal' in globalThis)) in the polyfill snippet type-checks without esnext libs, and the changeset could call the short guide "Other calendars".
[Automated review]
| blocks: [ | ||
| { | ||
| type: 'prose', | ||
| text: 'Date components show the Gregorian calendar unless the application chooses another one. Values never change with the calendar: they stay Gregorian ISO dates. {@link generic:i18n-calendars} has the short version.', |
There was a problem hiding this comment.
DateInput, DateRangeInput and DateTimeInput pass calendar="gregory" to their popover Calendar on the base branch, so they stay Gregorian when the provider sets a calendar. Suggested: "Calendar shows the Gregorian calendar unless the application chooses another one; DateInput, DateRangeInput and DateTimeInput stay Gregorian."
| content: [ | ||
| { | ||
| type: 'prose', | ||
| text: '`Calendar` shows the Gregorian calendar unless you choose another one. Pass `calendar` to `<InternationalizationProvider>` for a subtree, or to `Calendar` itself. Values stay Gregorian ISO dates (`YYYY-MM-DD`) in every calendar.', |
There was a problem hiding this comment.
This opening repeats line 30 of calendar-systems.doc.mjs word for word, and core-doc-quality.test.mjs ("repeat no passage word for word") fails on it. For example: "Set calendar on <InternationalizationProvider> for a subtree, or on Calendar itself; without it, Calendar is Gregorian."
| { | ||
| "topic": "internationalization", | ||
| "description": "Set the active locale, load catalogs, coexist with your own i18n library, handle RTL, and test translations.", | ||
| "description": "Set the active locale, load catalogs, coexist with your own i18n library, show other calendars, handle RTL, and test translations.", |
There was a problem hiding this comment.
The new docs also change five snapshots under __golden__/no-icon-set/ (docs-tree.json, search-icon-set.json, doctor-doc-counts.txt, doctor-installed-set.json), and experimental-isolation.test.mjs fails five tests on them. Regenerate with vitest run packages/cli/test/experimental-isolation.test.mjs --update and commit the diff.
| docsite MAY name a sidebar parent page for any page: the page keeps its | ||
| slug and its own group, and its sidebar entry sits under the parent's | ||
| entry, in the parent's group. Sidebar nesting is one level deep. A |
There was a problem hiding this comment.
FR14 uses "group" for the sidebar group, so for Icon sets (a Guide page under Icons in Foundations) this asks for both its own group and the parent's; docsSidebarGroups uses the parent's. Suggested: "the page keeps its slug and its category; its sidebar entry sits under the parent's entry, in the parent's group."
| key={page.topic} | ||
| {...docLink(page)} | ||
| collapsible={{ | ||
| defaultIsCollapsed: !children.some( |
There was a problem hiding this comment.
SideNavItem reads defaultIsCollapsed once, and DocsShell stays mounted in the docs layout. Opening Calendars from the search palette while on Internationalization leaves the parent collapsed: the Calendars link has aria-current="page" inside an inert, aria-hidden group and nothing visible is marked current. Control isCollapsed from the pathname (expanded whenever a child is open), or key the parent on whether a child is open.
| lang: 'ts', | ||
| label: 'Load the polyfill only where Temporal is missing', | ||
| code: `// temporal-setup.ts: import before your app renders, on the server and in the browser | ||
| if (typeof globalThis.Temporal === 'undefined') { |
There was a problem hiding this comment.
Non-blocking: under --strict with lib: ["es2022", "dom"] this line fails with TS7017. if (!('Temporal' in globalThis)) type-checks under any lib.
| '@astryxdesign/cli': patch | ||
| --- | ||
|
|
||
| [docs] Internationalization gains a short Calendars guide: choose a calendar on `InternationalizationProvider` or `Calendar`, values stay Gregorian ISO dates, and most calendars need `Temporal` (load `temporal-polyfill/full/global` where it is missing). A new `astryx docs internationalization/calendars` namespace has the detail: the supported calendars, loading `Temporal` on the server and in the browser, why the Chinese and Korean calendars can differ by a day between runtimes, and ISO 8601 week numbers. |
There was a problem hiding this comment.
Non-blocking: the short guide is titled "Other calendars"; Calendars is the namespace. Suggested: "Internationalization gains a short Other calendars guide".
f485a40 to
50df6ad
Compare
… server hydration for Chinese and Korean
Calendars is now internationalization/calendars, beside the short guide, so 'astryx docs internationalization' lists it. The title no longer carries a sidebar-sort prefix.
FR14 kept every nested namespace on its root namespace's page. The docsite may now name a nested namespace that gets one full page at its own slug, left off the root page, listed under the root page in the sidebar, with its guides' slugs redirecting into it.
NESTED_NAMESPACE_PAGES names nested namespaces that get a full page at their own slug. The root page leaves them out, their guides' slugs redirect into the new page, and the page records its root page as parent. internationalization/calendars is the first: /docs/internationalization-calendars.
In the Guide section, a page with a parent is a child of its parent's item. The parent stays a link and gets its own expand toggle; it starts expanded when the child page is open.
The docsite files now match the nested sidebar pages change, which generalizes the nesting: SIDEBAR_PARENTS names a sidebar parent for any page, in Guide or Foundations, and NESTED_NAMESPACE_PAGES starts empty. The next commit adds Calendars back as a consumer. These files drop out when this branch rebases onto that change.
internationalization/calendars is a nested namespace with a page of its own at /docs/internationalization-calendars, shown under Internationalization in the sidebar. Its guide's slug redirects to its section there.
Icon sets and Icon set files are the two halves of the icon set guide, so both show under Icons in Foundations. The URL is unchanged.
… update the docs snapshots The Calendars page names Calendar and says the date inputs stay Gregorian. The short guide's opening no longer repeats the calendars topic, the polyfill check type-checks without esnext libs, and the changeset names the Other calendars guide. The no-icon-set snapshots include the new pages.
"Its own group" read against "in the parent's group". The page keeps its `category`; only its sidebar entry moves to the parent's group.
…s is current The docs shell stays mounted across links and site search, and the parent entry read its open state only on mount, so a move from the parent page to its child left the child hidden. The parent entry is now open whenever a child page is current, and otherwise follows the reader's toggle.
A clean install does not hoist `@stylexjs/stylex` to the root `node_modules`, so doctor in the test project still warns that Core's peer is missing. The golden passed only where a parent directory held the package. It now records the warning again; only the two docs counts change.
While a child page was current, the parent entry stayed open whatever the reader pressed, so its "Collapse" toggle did nothing there. The entry now holds its own open state: each move to one of its pages opens it, and the reader's toggle wins until the next move.
Prose says "the lunisolar calendars" for `chinese` and `dangi`, and "Minguo" for `roc`; a single calendar goes by its identifier. The Lunisolar calendars section and the Lunisolar row in the supported calendars table replace the per-calendar names, and the 2027 example names the first month of the 2027 `chinese` year.
…n dates The guide says that a locale with a -u-ca- keyword keeps Gregorian dates, and that an identifier such as islamic shows Gregorian dates.
astryx theme build writes apps/docsite/src/themes/astryx.css.d.ts on every docsite generate.
50df6ad to
e0f6654
Compare
There was a problem hiding this comment.
Approved. The calendar guides match architecture:internationalization INV10 and component:Calendar FR8–FR10 now on main, the engineering owner's spec approval at this head covers the spec:AST-046 FR14 amendment for the nested Calendars page and sidebar parents, and CI passes.
- The Icon sets, Icon set files and Styling components sidebar moves come from #9786; if #9786 changes before this lands, rebase onto it.
[Automated review]
Reader impact
People building for Persian, Hebrew, Islamic, Thai, Japanese, Ethiopian users, or users of the Chinese or Dangi calendar, have no guide on showing dates in those calendars. After this change:
Temporal;astryx docs internationalization/calendars) holds the detail. On the docsite it's its own page, nested under Internationalization in the sidebar.Source of truth
spec:AST-111(approved in spec(AST-111): date components use the calendar the application chooses #9605):Temporalboundary and fallback;calendarprop onInternationalizationProvider(feat(i18n): InternationalizationProvider takes a calendar and exposes the resolved calendar #9791) and onCalendar(feat(Calendar): show the months of the selected calendar system #9622), and the Gregorian fallback with its development warning.spec:AST-046FR14 as amended in feat(docsite): nest docs pages under a parent page in the sidebar #9786, for the nested page. This branch carries the same change on main's docsite nav model (DocsNavTopiccarriesparent).Correction
internationalization/i18n-calendars, "Other calendars": one short section covering:Calendar, with an example;Temporal(loadtemporal-polyfill/full/globalwhere it's missing).It links to Calendars.
internationalization/calendars: a nested namespace with one guide,calendar-systems. The namespace says that onlyCalendarfollows the calendar and the date inputs stay Gregorian. The guide covers:-u-ca-locale keeps Gregorian dates;Temporal;Temporalis missing, on the server and in the browser, and why the server matters for hydration;Docsite:
internationalization/calendarsis an entry inNESTED_NAMESPACE_PAGES(from feat(docsite): nest docs pages under a parent page in the sidebar #9786), so Calendars gets its own page at/docs/internationalization-calendars, nested under Internationalization in the sidebar.Housekeeping: keywords sit only on the
calendarsnamespace, so each is declared once. The internationalization namespace'sguidesslot accepts namespaces, ascliandauthoringdo.Generated and incidental files: the CLI golden snapshots (docs list, docs tree, doctor counts, search counts) and a CLI changeset. The diff also has whitespace-only formatting in
CodeExampleBlock.tsxandthemeShowcaseContent.ts.Evidence
astryx docs internationalizationlists Other calendars and Calendars.astryx docs internationalization/calendarslists thecalendar-systemsguide./docs/internationalization-calendars-calendar-systemsredirects to the new page (route-resolution test).chineseyear comes from nativeTemporalin Node.js 26 (2027-02-06) and fromtemporal-polyfill/full1.0.6 on Node.js 24 (2027-02-07).Screenshots
Local docsite build of this branch.
Sidebar on the Calendars page: Calendars is nested and selected under an expanded Internationalization.
Sidebar on the Internationalization page: the child is collapsed.
Writing rubric results
No record changes of its own. The only record change in the diff is the carried
spec:AST-046FR14 amendment, identical to #9786. Its results:Scope
Testing
experimental-isolation,golden-reads,docs-graph,docs-topic-refs,global-mode-docs,core-prop-docsandcore-doc-quality): 90 of 91 pass. The failure, the doctor case inexperimental-isolation.test.mjs, fails only when the repository is checked out inside another checkout; it fails the same way on feat(Calendar): show the months of the selected calendar system #9622's branch, which has no docs change.pnpm -F @astryxdesign/docsite generate, then the docsite tests: 806 passed, 7 skipped.tsc --noEmit: clean.pnpm check:knowledgeandpnpm check:changesets: pass.node scripts/pre-review.mjs --base nynexman4464/feat/calendar-systems-core: 1,067 authored lines.