Week Picker

Accessible, unstyled calendar that selects whole weeks and shows ISO week numbers.


Package	`@vizejs/ui/week-picker`
Maturity	stable
Own the source	`vize lib pull week-picker`
Requires	calendar, context, controllable-state, id, locale
Aliases	week selector, iso week, week input, sprint week
Covers	HTML input type=week, ISO 8601 week dates, WAI-ARIA grid

Usage

import { WeekPicker, WeekPickerRoot, WeekPickerGrid, WeekPickerHeading, WeekPickerMonthSelect, WeekPickerNext, WeekPickerPrev, WeekPickerYearSelect } from "@vizejs/ui/week-picker";

Or copy the source into your project with vize lib pull week-picker (see Source Distribution).

API

`WeekPicker`

Source: src/families/date-time/week-picker/week-picker-root.vue

Props

Prop	Type	Default	Description
`id`	`string \| null \| undefined`	`undefined`	Consumer-owned base id; nullish values use a deterministic fallback.
`modelValue`	`DateRange \| null \| undefined`	`undefined`	Controlled week as a start–end range; `undefined` selects uncontrolled mode and `null` clears.
`defaultValue`	`DateRange \| null \| undefined`	`null`	Initial uncontrolled week.
`focusedDate`	`PlainDate \| null \| undefined`	`undefined`	Controlled keyboard focus date; also decides which months are visible.
`min`	`PlainDate \| null \| undefined`	`undefined`	Earliest selectable date, inclusive.
`max`	`PlainDate \| null \| undefined`	`undefined`	Latest selectable date, inclusive.
`isDateUnavailable`	`DateMatcher \| undefined`	`undefined`	Predicate for dates that stay focusable but cannot be selected.
`locale`	`string \| undefined`	`undefined`	BCP 47 locale; defaults to the nearest LocaleProvider.
`calendar`	`string \| undefined`	`undefined`	Intl calendar used for display labels only, for example `japanese`.
`numberingSystem`	`string \| undefined`	`undefined`	Intl numbering system for labels.
`dir`	`CalendarDirection \| undefined`	`undefined`	Text direction; defaults to the nearest LocaleProvider.
`weekStartsOn`	`Weekday \| undefined`	`undefined`	First day of week (`0` = Sunday); defaults to the locale preference.
`weekdayFormat`	`CalendarWeekdayFormat \| undefined`	`"short"`	Weekday column label width.
`numberOfMonths`	`number \| undefined`	`1`	Number of consecutive months rendered.
`pagedNavigation`	`boolean \| undefined`	`false`	Move month controls by `numberOfMonths` instead of one month.
`fixedWeeks`	`boolean \| undefined`	`false`	Always render six week rows per month.
`today`	`PlainDate \| null \| undefined`	`undefined`	Explicit current date; the SSR-safe way to mark today.
`now`	`DateTimeNow \| undefined`	`undefined`	Injectable clock evaluated during setup on server and client.
`timeZone`	`string \| undefined`	`undefined`	IANA time zone used with `now` and the post-mount host clock.
`disabled`	`boolean \| undefined`	`false`	Disable navigation, focus, and selection.
`readOnly`	`boolean \| undefined`	`false`	Allow navigation while blocking selection.
`name`	`string \| undefined`	`undefined`	Hidden input name that submits the ISO 8601 week (`YYYY-Www`) of the selected week.
`hideWeekNumbers`	`boolean \| undefined`	`false`	Omit ISO week numbers from the default grid composition.
`ariaLabel`	`string \| undefined`	`undefined`	Accessible name for the calendar group.
`ariaLabelledby`	`string \| undefined`	`undefined`	Ids that label the calendar group; defaults to the heading.
`ariaDescribedby`	`string \| undefined`	`undefined`	Ids that describe the calendar group.

Events

Event	Payload	Description
`update:modelValue`	`[value: DateRange \| null]`	Fired when the picker requests a new controlled week.
`change`	`[value: DateRange \| null, previous: DateRange \| null, nativeEvent: Event \| null]`	Fired after a distinct committed week with the previous week and triggering event.
`select`	`[value: DateRange, nativeEvent: Event]`	Fired for every week activation, even when the week is unchanged.
`update:focusedDate`	`[date: PlainDate]`	Fired when keyboard or navigation moves the focus date.

Slots

Slot	Slot props	Description
`default`	`CalendarSlotState`	Week picker composition. Receives months, weekdays, heading, and state; defaults to a header plus one grid per month.

Exposed

Member	Type	Description
`value`	—
`isoWeek`	—
`setValue`	—

`WeekPickerRoot`

Source: src/families/date-time/week-picker/week-picker-root.vue

Props

Prop	Type	Default	Description
`id`	`string \| null \| undefined`	`undefined`	Consumer-owned base id; nullish values use a deterministic fallback.
`modelValue`	`DateRange \| null \| undefined`	`undefined`	Controlled week as a start–end range; `undefined` selects uncontrolled mode and `null` clears.
`defaultValue`	`DateRange \| null \| undefined`	`null`	Initial uncontrolled week.
`focusedDate`	`PlainDate \| null \| undefined`	`undefined`	Controlled keyboard focus date; also decides which months are visible.
`min`	`PlainDate \| null \| undefined`	`undefined`	Earliest selectable date, inclusive.
`max`	`PlainDate \| null \| undefined`	`undefined`	Latest selectable date, inclusive.
`isDateUnavailable`	`DateMatcher \| undefined`	`undefined`	Predicate for dates that stay focusable but cannot be selected.
`locale`	`string \| undefined`	`undefined`	BCP 47 locale; defaults to the nearest LocaleProvider.
`calendar`	`string \| undefined`	`undefined`	Intl calendar used for display labels only, for example `japanese`.
`numberingSystem`	`string \| undefined`	`undefined`	Intl numbering system for labels.
`dir`	`CalendarDirection \| undefined`	`undefined`	Text direction; defaults to the nearest LocaleProvider.
`weekStartsOn`	`Weekday \| undefined`	`undefined`	First day of week (`0` = Sunday); defaults to the locale preference.
`weekdayFormat`	`CalendarWeekdayFormat \| undefined`	`"short"`	Weekday column label width.
`numberOfMonths`	`number \| undefined`	`1`	Number of consecutive months rendered.
`pagedNavigation`	`boolean \| undefined`	`false`	Move month controls by `numberOfMonths` instead of one month.
`fixedWeeks`	`boolean \| undefined`	`false`	Always render six week rows per month.
`today`	`PlainDate \| null \| undefined`	`undefined`	Explicit current date; the SSR-safe way to mark today.
`now`	`DateTimeNow \| undefined`	`undefined`	Injectable clock evaluated during setup on server and client.
`timeZone`	`string \| undefined`	`undefined`	IANA time zone used with `now` and the post-mount host clock.
`disabled`	`boolean \| undefined`	`false`	Disable navigation, focus, and selection.
`readOnly`	`boolean \| undefined`	`false`	Allow navigation while blocking selection.
`name`	`string \| undefined`	`undefined`	Hidden input name that submits the ISO 8601 week (`YYYY-Www`) of the selected week.
`hideWeekNumbers`	`boolean \| undefined`	`false`	Omit ISO week numbers from the default grid composition.
`ariaLabel`	`string \| undefined`	`undefined`	Accessible name for the calendar group.
`ariaLabelledby`	`string \| undefined`	`undefined`	Ids that label the calendar group; defaults to the heading.
`ariaDescribedby`	`string \| undefined`	`undefined`	Ids that describe the calendar group.

Events

Event	Payload	Description
`update:modelValue`	`[value: DateRange \| null]`	Fired when the picker requests a new controlled week.
`change`	`[value: DateRange \| null, previous: DateRange \| null, nativeEvent: Event \| null]`	Fired after a distinct committed week with the previous week and triggering event.
`select`	`[value: DateRange, nativeEvent: Event]`	Fired for every week activation, even when the week is unchanged.
`update:focusedDate`	`[date: PlainDate]`	Fired when keyboard or navigation moves the focus date.

Slots

Slot	Slot props	Description
`default`	`CalendarSlotState`	Week picker composition. Receives months, weekdays, heading, and state; defaults to a header plus one grid per month.

Exposed

Member	Type	Description
`mode`	`CalendarSelectionMode`	Selection model of the root.
`months`	`readonly CalendarMonthState[]`	Visible month grids; empty while `pending`.
`weekdays`	`readonly CalendarWeekdayLabel[]`	Localized weekday labels in column order.
`heading`	`string`	Localized heading for the visible months.
`focusedDate`	`PlainDate \| null`	Keyboard focus target, or `null` while pending.
`today`	`PlainDate \| null`	Resolved current date, or `null` before a clock is available.
`locale`	`string`	Resolved BCP 47 locale.
`direction`	`CalendarDirection`	Resolved text direction.
`weekStartsOn`	`Weekday`	Resolved first day of week.
`disabled`	`boolean`	Whether every control is disabled.
`readOnly`	`boolean`	Whether selection is blocked while navigation works.
`pending`	`boolean`	Whether no date is known yet: no value, focused date, `today`, or `now` was supplied, so the grid waits for the client clock after mount.
`state`	`CalendarState`	Stable root state token.
`root`	`HTMLDivElement \| null`	Rendered root element.
`focus`	`(options?: FocusOptions) => boolean`	Focus the roving day button; returns whether focus moved.
`setFocusedDate`	`(date: PlainDate) => void`	Move the keyboard focus target (and visible months) to a date, clamped to `min`/`max`.
`setVisibleMonth`	`(month: PlainYearMonth) => void`	Show a month as the first visible month.
`navigate`	`(unit: CalendarNavigationUnit, direction: -1 \| 1) => boolean`	Navigate by one page of months or years; returns whether the view moved.
`value`	`DateRange \| null`	Selected week as an inclusive start–end range.
`isoWeek`	`IsoWeek \| null`	ISO 8601 week of the selection, taken from its fourth day.
`setValue`	`(value: DateRange \| null) => boolean`	Request a week; returns whether it differs.

`WeekPickerGrid`

Source: src/families/date-time/calendar/calendar-grid.vue

Props

Prop	Type	Default	Description
`monthIndex`	`number`	`0`	Zero-based index of the visible month this grid renders.
`showWeekNumbers`	`boolean`	`false`	Render a leading row header with the ISO 8601 week number of each row.
`weekNumberLabel`	`string`	`"Wk"`	Visible week-number column header.
`weekNumberHeader`	`string`	`"Week"`	Full week-number column header used as `abbr`.

Slots

Slot	Slot props	Description
`weekday`	`CalendarWeekdaySlotState`	Weekday column header content. Receives the weekday, its labels, and column index.
`weekNumber`	`CalendarWeekNumberSlotState`	Week-number row header content. Receives the ISO week and the row's days.
`day`	`CalendarDayState`	Day button content. Receives the complete day state; defaults to the localized day number.

`WeekPickerHeading`

Source: src/families/date-time/calendar/calendar-heading.vue

Slots

Slot	Slot props	Description
`default`	`CalendarHeadingSlotState`	Heading content. Receives the localized heading and visible months.

`WeekPickerMonthSelect`

Source: src/families/date-time/calendar/calendar-month-select.vue

Props

Prop	Type	Default	Description
`ariaLabel`	`string`	`"Month"`	Accessible name of the native select.

Events

Event	Payload	Description
`change`	`[month: number, nativeEvent: Event]`	Fired after the user picks a month, with the ISO month number.

`WeekPickerNext`

Source: src/families/date-time/calendar/calendar-next.vue

Props

Prop	Type	Default	Description
`unit`	`CalendarNavigationUnit`	`"month"`	Whether the control pages by month (or `numberOfMonths` when paged) or by year.
`ariaLabel`	`string`	`undefined`	Accessible name; defaults to "Next month" or "Next year".

Events

Event	Payload	Description
`click`	`[nativeEvent: MouseEvent]`	Fired before navigation. Call `preventDefault()` to keep the view unchanged.

Slots

Slot	Slot props	Description
`default`	`CalendarNavigationSlotState`	Control content. Receives the unit and whether navigation is possible.

`WeekPickerPrev`

Source: src/families/date-time/calendar/calendar-prev.vue

Props

Prop	Type	Default	Description
`unit`	`CalendarNavigationUnit`	`"month"`	Whether the control pages by month (or `numberOfMonths` when paged) or by year.
`ariaLabel`	`string`	`undefined`	Accessible name; defaults to "Previous month" or "Previous year".

Events

Event	Payload	Description
`click`	`[nativeEvent: MouseEvent]`	Fired before navigation. Call `preventDefault()` to keep the view unchanged.

Slots

Slot	Slot props	Description
`default`	`CalendarNavigationSlotState`	Control content. Receives the unit and whether navigation is possible.

`WeekPickerYearSelect`

Source: src/families/date-time/calendar/calendar-year-select.vue

Props

Prop	Type	Default	Description
`from`	`number`	`undefined`	First listed year; defaults to the `min` year or ten years before the view.
`to`	`number`	`undefined`	Last listed year; defaults to the `max` year or ten years after the view.
`ariaLabel`	`string`	`"Year"`	Accessible name of the native select.

Events

Event	Payload	Description
`change`	`[year: number, nativeEvent: Event]`	Fired after the user picks a year.

Behavior

Normative state x input -> outcome table for week-picker-root.vue (@vizejs/ui/week-picker). WeekPicker reuses the Calendar runtime and parts (calendar.behavior.md keyboard, locale, bounds, and SSR rows apply) with a whole-week selection model. Every row is proven by the named test.

#	State	Input	Outcome	Proven by
W1	any	render / day activation	grids show a leading `<th scope="row">` ISO week number column (omit with `hideWeekNumbers`); activating a day selects its locale week as a `DateRange`, emits `update:modelValue`, `change`, `select`, and `name` submits `YYYY-Www`	`activating any day selects its locale week and shows ISO week numbers`
W2	any	pointer / keyboard focus	the week under the pointer or focus is previewed with `data-preview`; weeks follow the locale start (Sunday for `en-US`); `isoWeek` and `setValue` are exposed	`pointer and keyboard focus preview the week; US locales start on Sunday`
W3	model	helpers	`isoWeekOf`, `startOfIsoWeek`, `formatIsoWeek`, and `parseIsoWeek` handle year boundaries and week 53; `weekOf` honors any week start	`ISO week helpers cover year boundaries and week 53`
W4	SSR	isolated requests	byte-identical markup and silent hydration	`renders byte-identical week picker markup across isolated SSR requests`, `hydrates week picker markup without mismatches`