From 16ce5bee09651ef519a6f9c34c3df8c3e4ed7dee Mon Sep 17 00:00:00 2001 From: anna-lach Date: Thu, 7 May 2026 10:21:13 +0200 Subject: [PATCH 1/7] docs: add first version of documentation for calendar and date field components --- .../components/calendar/accessibility.md | 50 ++++++++ .../components/calendar/calendar.json | 16 +++ .../components/calendar/calendar.md | 15 +++ .../categories/components/calendar/code.md | 67 ++++++++++ .../categories/components/calendar/usage.md | 120 ++++++++++++++++++ .../categories/components/callout/callout.md | 2 +- .../components/date-field/accessibility.md | 63 +++++++++ .../categories/components/date-field/code.md | 58 +++++++++ .../components/date-field/date-field.json | 12 ++ .../components/date-field/date-field.md | 15 +++ .../categories/components/date-field/usage.md | 117 +++++++++++++++++ .../components/tool-bar/tool-bar.md | 2 +- website/src/ts/scripts/slds-components.ts | 2 + 13 files changed, 537 insertions(+), 2 deletions(-) create mode 100644 website/src/categories/components/calendar/accessibility.md create mode 100644 website/src/categories/components/calendar/calendar.json create mode 100644 website/src/categories/components/calendar/calendar.md create mode 100644 website/src/categories/components/calendar/code.md create mode 100644 website/src/categories/components/calendar/usage.md create mode 100644 website/src/categories/components/date-field/accessibility.md create mode 100644 website/src/categories/components/date-field/code.md create mode 100644 website/src/categories/components/date-field/date-field.json create mode 100644 website/src/categories/components/date-field/date-field.md create mode 100644 website/src/categories/components/date-field/usage.md diff --git a/website/src/categories/components/calendar/accessibility.md b/website/src/categories/components/calendar/accessibility.md new file mode 100644 index 0000000000..19b4f57760 --- /dev/null +++ b/website/src/categories/components/calendar/accessibility.md @@ -0,0 +1,50 @@ +--- +title: Calendar accessibility +tags: accessibility +eleventyNavigation: + parent: Calendar + key: CalendarAccessibility +--- +
+ +## Keyboard interactions + +The calendar supports full keyboard navigation through the month view, with shortcuts for moving between months and years. + +
+ +|Command| Description | +|-|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +|Tab| Moves focus into and out of the calendar grid and the month/year navigation controls. | +|Arrow Left/Right| Moves focus to the previous or next day. | +|Arrow Up/Down| Moves focus to the same day in the previous or next week. | +|Page Up/Down| Moves focus to the same day in the previous or next month. | +|Shift + Page Up/Down| Moves focus to the same day in the previous or next year. | +|Home/End| Moves focus to the first or last day of the current week. | +|Enter/Space| Selects the currently focused date. | + +{.ds-table .ds-table-align-top} + +
+ +
+ +
+ +## WAI-ARIA + +{{ 'aria-attributes' | recurringText }} + +
+ +|Attribute | Value | Description | +|-|-|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +|`aria-label`|string| Defines a string that labels the calendar. Useful when the calendar is used standalone, without a surrounding labelled control. | +|`aria-labelledby`|string| References the ID of the element that labels the calendar. | + +{.ds-table .ds-table-align-top} + +
+ +
+ diff --git a/website/src/categories/components/calendar/calendar.json b/website/src/categories/components/calendar/calendar.json new file mode 100644 index 0000000000..6fa2f9ffa0 --- /dev/null +++ b/website/src/categories/components/calendar/calendar.json @@ -0,0 +1,16 @@ +{ + "layout": "categories/components/components.njk", + "tags": "calendar", + "componentStatus": "draft", + "componentTagName": [ + { + "name": "Calendar", + "selector": "sl-calendar" + }, + { + "name": "Month view", + "selector": "sl-month-view" + } + ] +} + diff --git a/website/src/categories/components/calendar/calendar.md b/website/src/categories/components/calendar/calendar.md new file mode 100644 index 0000000000..b2d2dcb839 --- /dev/null +++ b/website/src/categories/components/calendar/calendar.md @@ -0,0 +1,15 @@ +--- +title: Calendar +description: The Calendar component displays a month view that lets users browse and select a date. It supports min/max constraints, disabled dates, indicator dates, week numbers and locale-aware formatting, and can be used standalone or embedded in other components such as the Date Field. +componentType: form +shortDescription: Calendar for browsing and selecting a date. +layout: "categories/components/components.njk" +tags: component +packageName: calendar +storybookCategory: form +eleventyNavigation: + parent: Components + key: Calendar + status: new +--- + diff --git a/website/src/categories/components/calendar/code.md b/website/src/categories/components/calendar/code.md new file mode 100644 index 0000000000..4d748a826c --- /dev/null +++ b/website/src/categories/components/calendar/code.md @@ -0,0 +1,67 @@ +--- +title: Calendar code +tags: code +APIdescription: { + sl-calendar: "Calendar component that combines day, month and year selection views to pick a date. Used internally by the date field, but can also be used standalone.", + sl-month-view: "Low-level component that renders a single month grid without navigation controls. Used internally by select-day and can be used to compose custom calendar layouts." +} +eleventyNavigation: + parent: Calendar + key: CalendarCode +--- +
+ +
+ +
+ +
+ + ```html + + ``` + +
+ +
+ + + +
+ +## Localization + +Month names, day names and the first day of the week follow the active locale (via `Intl.DateTimeFormat`). +\ +You can override the first day of the week with the `first-day-of-week` attribute (`0` for Sunday, `1` for Monday, etc.). + +
+ +
+ +## Min and max constraints + +Use the `min` and `max` attributes to restrict the selectable date range. Dates outside the range are visually disabled and cannot be selected. + +
+ +
+ +## Disabled and indicator dates + +Use `disabled-dates` to mark specific dates as non-selectable (for example, holidays or already booked days). Use `indicator-dates` to highlight specific dates with a visual indicator (for example, dates with events) without disabling them. + +
+ +
+ +## Week numbers + +Set `show-week-numbers` to display ISO week numbers next to each row of days. + +
+ +{% include "../component-table.njk" %} + diff --git a/website/src/categories/components/calendar/usage.md b/website/src/categories/components/calendar/usage.md new file mode 100644 index 0000000000..c8b58a6f25 --- /dev/null +++ b/website/src/categories/components/calendar/usage.md @@ -0,0 +1,120 @@ +--- +title: Calendar usage +tags: usage +eleventyNavigation: + parent: Calendar + key: CalendarUsage +--- + +
+ +
+ +
+ +
+ + ```html + + ``` + +
+ +
+ +
+ +## When to use + +The following guidance describes when to use the calendar component. + +### Visual date selection +Use the Calendar when users benefit from seeing a full month view to pick a date — for example, when context like weekdays, weekends, holidays or already booked days helps the choice. It works well embedded inside other components (such as the Date Field popover) or standalone in a panel. + +### Browsing dates +Use the Calendar when users need to browse and orient themselves in time, for example to see which weekday a date falls on, or to navigate between months and years before making a choice. + +
+ +
+ +## When not to use + +The Calendar may not be the best choice in the following scenarios: + +### Quick, known date entry +When users already know the exact date and just need to type it (for example a birth date), prefer the [Date Field](/categories/components/date-field/usage) which combines free typing with a popover calendar. + +### Relative timeframes +Avoid the Calendar when only approximate periods or relative notions of time are needed (e.g. "next week", "this month"). Use radio buttons, a segmented control, or a select instead. + +
+ +
+ +## Anatomy + +
+ +|Item|Name| Description | Optional| +|-|-|-|-| +|1|Header|Displays the current month and year and the navigation controls.|no| +|2|Navigation buttons|Move to the previous or next month (and optionally year).|no| +|3|Weekday row|Localized day-of-week labels.|no| +|4|Week numbers|ISO week numbers next to each row.|yes| +|5|Day grid|Grid of selectable days for the visible month.|no| +|6|Today indicator|Visual marker for today's date.|yes| +|7|Indicator dates|Visual markers for highlighted dates (e.g. events).|yes| + +{.ds-table .ds-table-align-top} + +
+ +
+ +
+ +## States + +- **Idle:** No date selected or with a selected date highlighted. +- **Hover:** Visual hover effects on focusable days. +- **Focus:** Display the focus ring on the focused day. +- **Selected:** Highlighted styling on the selected date. +- **Disabled day:** Days outside `min` / `max` or in `disabled-dates` are styled as non-selectable. +- **Indicator:** Days listed in `indicator-dates` show a visual marker. +- **Disabled (whole calendar):** Non-interactive, muted. +- **Read-only:** Visible state, no interaction. + +
+ +
+ +## Behavior + +### Selecting a date +Click a day or focus it with the keyboard and press `Enter` / `Space` to select it. Selecting a date emits an `sl-change` event. + +### Navigating months and years +Use the navigation buttons in the header, or use `Page Up` / `Page Down` (and `Shift + Page Up` / `Shift + Page Down`) to move between months and years from the keyboard. + +### Min and max +Days outside the configured `min` / `max` range are visually disabled and cannot be selected. + +### Disabled and indicator dates +`disabled-dates` marks specific dates as non-selectable while still showing them in the grid. `indicator-dates` adds a visual marker to specific dates without changing their interactivity, which is useful for highlighting dates with events, deadlines or notifications. + +### Today +When `show-today` is set, today's date is visually highlighted to help users orient themselves in the current month. + +
+ +
+ +## Related components +- [Date Field](/categories/components/date-field/usage): Input field that combines free typing with a calendar popover. +- [Time Field](/categories/components/time-field/usage): Companion component for selecting a time. + +
+ diff --git a/website/src/categories/components/callout/callout.md b/website/src/categories/components/callout/callout.md index cb4aa23241..a257a56f83 100644 --- a/website/src/categories/components/callout/callout.md +++ b/website/src/categories/components/callout/callout.md @@ -10,6 +10,6 @@ storybookCategory: layout eleventyNavigation: parent: Components key: Callout - status: new + status: ready --- diff --git a/website/src/categories/components/date-field/accessibility.md b/website/src/categories/components/date-field/accessibility.md new file mode 100644 index 0000000000..9bc4037b27 --- /dev/null +++ b/website/src/categories/components/date-field/accessibility.md @@ -0,0 +1,63 @@ +--- +title: Date field accessibility +tags: accessibility +eleventyNavigation: + parent: Date field + key: DateFieldAccessibility +--- +
+ +## Keyboard interactions + +The date field supports keyboard navigation for both the input and the calendar popover. + +
+ +|Command| Description | +|-|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +|Tab| When focus is outside the date field, moves focus to the input. If focus is on the input, pressing Tab moves to the calendar trigger button, then to the next focusable element. | +|Space/Enter (on button)| Toggles the calendar popover when the button has focus. | +|Escape| Closes the calendar popover. | +|Arrow Left/Right (in calendar)| Moves focus to the previous or next day. | +|Arrow Up/Down (in calendar)| Moves focus to the same day in the previous or next week. | +|Page Up/Down (in calendar)| Moves focus to the same day in the previous or next month. | +|Shift + Page Up/Down (in calendar)| Moves focus to the same day in the previous or next year. | +|Home/End (in calendar)| Moves focus to the first or last day of the current month. | +|Enter (in calendar)| Selects the currently focused date and closes the popover. | + +{.ds-table .ds-table-align-top} + +
+ +
+ +
+ +## WAI-ARIA + +{{ 'aria-attributes' | recurringText }} + +
+ +|Attribute | Value | Description | +|-|-|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +|`aria-label`|string| Defines a string that labels the date field. Required when not wrapped with `sl-form-field` and there is no `sl-label` component. | +|`aria-labelledby`|string| References the ID of the element that labels the date field. | +|`aria-required`|boolean| Informs the user that an element is required. When set to ‘true’, screen readers notify users that the element is required. If there is already a `required` attribute added, it is recommended to avoid adding `aria-required`. | +|`aria-disabled`|boolean| Announces the date field as disabled with a screen reader. See note below about difference from the `disabled` attribute. | + +{.ds-table .ds-table-align-top} + +
+ +**Notes:** + +1. The `aria-disabled` should not be used as a one-for-one replacement for the `disabled` attribute because they have different functionalities: + +- The `disabled` attribute dims the date field visually, removes it from tab focus, prevents all interactions, and announces it as disabled. +- The `aria-disabled` attribute only announces the disabled state but doesn't prevent interaction or remove focus. + +Use `disabled` for true disabled states, use `aria-disabled` only if you need the element to remain in the tab sequence for specific accessibility reasons. + +
+ diff --git a/website/src/categories/components/date-field/code.md b/website/src/categories/components/date-field/code.md new file mode 100644 index 0000000000..361fb8ed90 --- /dev/null +++ b/website/src/categories/components/date-field/code.md @@ -0,0 +1,58 @@ +--- +title: Date field code +tags: code +APIdescription: { + sl-date-field: "Form-aware date input with an integrated calendar popover. Supports localization, min/max constraints, validation and an optional select-only mode." +} +eleventyNavigation: + parent: Date field + key: DateFieldCode +--- +
+ +
+ +
+ +
+ + ```html + + ``` + +
+ +
+ + + +
+ +## Localization + +The date format and the first day of the week follow the active locale (via `Intl.DateTimeFormat`). +\ +You can override the first day of the week with the `first-day-of-week` attribute (`0` for Sunday, `1` for Monday, etc.). + +
+ +
+ +## Min and max constraints + +Use the `min` and `max` attributes to restrict the selectable date range. Dates outside the range are disabled in the calendar and rejected by validation. + +
+ +
+ +## Select-only mode + +Set `select-only` to disable free typing in the input. Users can only pick a date through the calendar popover. + +
+ +{% include "../component-table.njk" %} + diff --git a/website/src/categories/components/date-field/date-field.json b/website/src/categories/components/date-field/date-field.json new file mode 100644 index 0000000000..c56878d705 --- /dev/null +++ b/website/src/categories/components/date-field/date-field.json @@ -0,0 +1,12 @@ +{ + "layout": "categories/components/components.njk", + "tags": "date-field", + "componentStatus": "draft", + "componentTagName": [ + { + "name": "Date field", + "selector": "sl-date-field" + } + ] +} + diff --git a/website/src/categories/components/date-field/date-field.md b/website/src/categories/components/date-field/date-field.md new file mode 100644 index 0000000000..639cbb8c88 --- /dev/null +++ b/website/src/categories/components/date-field/date-field.md @@ -0,0 +1,15 @@ +--- +title: Date field +description: The Date Field allows users to enter a date by typing or by picking it from an integrated calendar popover. It supports configurable min/max constraints, locale-aware formatting, and a select-only mode that disables free typing. +componentType: form +shortDescription: Date input with integrated calendar popover and validation. +layout: "categories/components/components.njk" +tags: component +packageName: date-field +storybookCategory: form +eleventyNavigation: + parent: Components + key: Date field + status: new +--- + diff --git a/website/src/categories/components/date-field/usage.md b/website/src/categories/components/date-field/usage.md new file mode 100644 index 0000000000..35d90ff6cd --- /dev/null +++ b/website/src/categories/components/date-field/usage.md @@ -0,0 +1,117 @@ +--- +title: Date field usage +tags: usage +eleventyNavigation: + parent: Date field + key: DateFieldUsage +--- + +
+ +
+ +
+ +
+ + ```html + + ``` + +
+ +
+ +
+ +## When to use + +The following guidance describes when to use the date field component. + +### Precise date entry +Use the Date Field when the task requires an exact calendar date and you want to combine fast typing with visual confirmation through a calendar popover. It is ideal for booking dates, deadlines, birthdays, appointments, and any workflow where the date must be unambiguous. + +### Constrained date selection +Use the Date Field when only a specific date range is valid (for example, future dates only, dates within a school year, or dates between a start and end). The `min` and `max` attributes communicate the valid range visually in the calendar and through validation. + +
+ +
+ +## When not to use + +Date fields may not be the best choice in the following scenarios: + +### Relative timeframes +Avoid the Date Field when only approximate periods or relative notions of time are needed (e.g., "next week", "this month", "in three days"). In these cases, prefer radio buttons, a segmented control, or a select that reflects a relative period. + +### Date ranges +For selecting a start and end date together, prefer a dedicated date range picker rather than two separate date fields, when available. + +
+ +
+ +## Anatomy + +
+ +|Item|Name| Description | Optional| +|-|-|-|-| +|1|Container|Wraps the input and trigger, provides the focus ring and error visuals.|no| +|2|Input|Editable field for typing a date.|no| +|3|Placeholder|Hint text when no value is set (e.g. the expected date format).|yes| +|4|Icon Button|Opens the calendar popover.|no| +|5|Calendar popover|Calendar overlay for picking a date visually.|no| + +{.ds-table .ds-table-align-top} + +
+ +
+ +
+ +## States + +- **Idle:** Empty, showing the placeholder, or with a formatted date as the value. +- **Hover:** Visual hover effects that show the user that the field is interactive. +- **Focus:** Display the focus ring. It's shown when the field is active by clicking or keyboard navigation. +- **Invalid:** When an incorrect or out-of-range value is entered, the field is styled to indicate the error. +- **Disabled:** Non-interactive, muted. +- **Read-only:** Visible value, no interaction. + +
+ +
+ +## Behavior + +### Free Typing (Default) +Users can type any valid date matching the locale-aware format. The component validates for format, parsability, and the optional `min` / `max` range when the field loses focus. + +### Calendar popover +Click the calendar icon button or press `Space`/`Enter` on it to open the popover. Use the keyboard or pointer to focus a date and press `Enter` to select it. Pressing `Escape` closes the popover and returns focus to the input. + +### Select-only mode +When `select-only` is set, the input becomes read-only and users can only pick a date through the calendar popover. This is useful when you want to enforce valid input without relying on typed values. + +### Min and max +Dates outside the configured `min` / `max` range are disabled in the calendar and rejected by validation when typed. + +### Require confirmation +When `require-confirmation` is set, the user must explicitly confirm the selected date in the calendar before it becomes the field value. This is useful in workflows where accidental selection could trigger an action. + +
+ +
+ +## Related components +- [Calendar](/categories/components/calendar/usage): Standalone calendar for date selection or date browsing. +- [Time Field](/categories/components/time-field/usage): Companion component for selecting a time. +- [Text Field](/categories/components/text-field/usage): For free-form text input. + +
+ diff --git a/website/src/categories/components/tool-bar/tool-bar.md b/website/src/categories/components/tool-bar/tool-bar.md index 9ed6a26cae..bd766c9c8c 100644 --- a/website/src/categories/components/tool-bar/tool-bar.md +++ b/website/src/categories/components/tool-bar/tool-bar.md @@ -10,7 +10,7 @@ storybookCategory: actions eleventyNavigation: parent: Components key: Tool bar - status: new + status: ready --- diff --git a/website/src/ts/scripts/slds-components.ts b/website/src/ts/scripts/slds-components.ts index 67ba7352ad..7b8d9f8b93 100644 --- a/website/src/ts/scripts/slds-components.ts +++ b/website/src/ts/scripts/slds-components.ts @@ -61,11 +61,13 @@ import '@sl-design-system/badge/register.js'; import '@sl-design-system/breadcrumbs/register.js'; import '@sl-design-system/button/register.js'; import '@sl-design-system/button-bar/register.js'; +import '@sl-design-system/calendar/register.js'; import '@sl-design-system/callout/register.js'; import '@sl-design-system/card/register.js'; import '@sl-design-system/checkbox/register.js'; import '@sl-design-system/combobox/register.js'; import { ArrayListDataSource, FetchListDataSource, FetchListDataSourceError } from '@sl-design-system/data-source'; +import '@sl-design-system/date-field/register.js'; import '@sl-design-system/dialog/register.js'; import '@sl-design-system/drawer/register.js'; import '@sl-design-system/editor/register.js'; From 431375605e1f9264cd57ded707b2a86d19f1dd93 Mon Sep 17 00:00:00 2001 From: arecuenco-dsgn Date: Thu, 21 May 2026 12:47:42 +0200 Subject: [PATCH 2/7] Updated the Date Field Usage Docs --- .../categories/components/date-field/usage.md | 155 ++++++++++++++++-- 1 file changed, 140 insertions(+), 15 deletions(-) diff --git a/website/src/categories/components/date-field/usage.md b/website/src/categories/components/date-field/usage.md index 35d90ff6cd..30472b98f1 100644 --- a/website/src/categories/components/date-field/usage.md +++ b/website/src/categories/components/date-field/usage.md @@ -31,10 +31,11 @@ eleventyNavigation: The following guidance describes when to use the date field component. ### Precise date entry -Use the Date Field when the task requires an exact calendar date and you want to combine fast typing with visual confirmation through a calendar popover. It is ideal for booking dates, deadlines, birthdays, appointments, and any workflow where the date must be unambiguous. +Use the Date Field when the task requires an exact date and you want to combine fast typing with visual confirmation through a calendar popover. It is ideal for booking dates, deadlines, birthdays, appointments, and any workflow where the date must be unambiguous. ### Constrained date selection -Use the Date Field when only a specific date range is valid (for example, future dates only, dates within a school year, or dates between a start and end). The `min` and `max` attributes communicate the valid range visually in the calendar and through validation. +Use the Date Field when only a specific date range is valid, for example, future dates only, dates within a school year, or dates between a start and end. The `min` and `max` attributes communicate the valid range visually in the calendar and through validation. + @@ -45,10 +46,14 @@ Use the Date Field when only a specific date range is valid (for example, future Date fields may not be the best choice in the following scenarios: ### Relative timeframes -Avoid the Date Field when only approximate periods or relative notions of time are needed (e.g., "next week", "this month", "in three days"). In these cases, prefer radio buttons, a segmented control, or a select that reflects a relative period. +Avoid the Date Field when only approximate periods or relative notions of time are needed (e.g., "next week", "this month", "in three days"). In these cases, prefer select or radio buttons that reflects a relative period. ### Date ranges -For selecting a start and end date together, prefer a dedicated date range picker rather than two separate date fields, when available. +For selecting a start and end date together, prefer a dedicated date range picker rather than two separate date fields, when vailable. + +### Only calendar +Do not use the Date Field when the date selection needs to be shown directly in the layout instead of inside a dropdown. Use the [Calendar](/categories/components/calendar/) when the visual date picker is the main interaction. + @@ -58,13 +63,15 @@ For selecting a start and end date together, prefer a dedicated date range picke
-|Item|Name| Description | Optional| +|Item|Name|Description|Optional| |-|-|-|-| -|1|Container|Wraps the input and trigger, provides the focus ring and error visuals.|no| -|2|Input|Editable field for typing a date.|no| -|3|Placeholder|Hint text when no value is set (e.g. the expected date format).|yes| -|4|Icon Button|Opens the calendar popover.|no| -|5|Calendar popover|Calendar overlay for picking a date visually.|no| +|1|Label|Describes the purpose of the field and helps users understand which date to enter.|yes| +|2|Input field|Main input area where users can type a date or view the selected value.|no| +|3|Placeholder|Hint shown inside the field when no value is selected, usually showing the expected date format.|yes| +|4|Picker button|Icon-only button that opens the Picker dropdown for visual date selection.|no| +|5|Clear button|Icon-only button that appears when a date is selected and clears the current value.|yes| +|6|Picker|Dropdown connected to the field that contains the Calendar and optional picker panels.|yes| +|7|Calendar|Visual date picker used inside the Picker to navigate and select a date.|yes| {.ds-table .ds-table-align-top} @@ -76,15 +83,133 @@ For selecting a start and end date together, prefer a dedicated date range picke ## States -- **Idle:** Empty, showing the placeholder, or with a formatted date as the value. +These states describe what users see when the Date Field is available. + +- **Idle:** Empty, showing the placeholder, or with a formatted date as the value if the the field is filled. - **Hover:** Visual hover effects that show the user that the field is interactive. - **Focus:** Display the focus ring. It's shown when the field is active by clicking or keyboard navigation. - **Invalid:** When an incorrect or out-of-range value is entered, the field is styled to indicate the error. -- **Disabled:** Non-interactive, muted. -- **Read-only:** Visible value, no interaction. +- **Disabled:** Non-interactive, the field is visible but unavailable for interaction. + + + + +
+ +## Figma Properties + +These properties describe the Figma setup for the Date Field. Some properties represent real UI behaviour, while others are only used to preview or compose the component in Figma. + + +### sl-date_field + +Main component used to compose the Date Field and preview the closed or open Picker state. + +
+ +| Item | Options | Description | +| --- | --- | --- | +| Open | `false` `true` | Figma-only preview property that shows or hides the Picker dropdown. The open state is triggered by interaction in the product UI. | + +{.ds-table .ds-table-align-top} + +
+ + +### sl-date_field-variants + +Nested field component used to control the visible field content, label visibility, and clear action in Figma. + +
+ +| Item | Options | Description | +| --- | --- | --- | +| Text | `text` | Figma text property for the visible field value. Represents the selected or typed date shown in the field. | +| Placeholder text | `text` | Figma text property for the placeholder shown when the field has no value. | +| Label | `boolean` | Shows or hides the label above the field. | +| Clear | `boolean` | Shows or hides the clear button in Figma. In product UI, the clear button appears when a date is selected. | +| Variant | `Default` | Main visual style currently represented in Figma. | +| Size | `MD` | Figma size property. The current component setup represents the medium field size. | +| Placeholder | `false` | Figma setup property for previewing the placeholder state. The product UI should rely on the field value and placeholder text. | + +{.ds-table .ds-table-align-top} + +
+ + +### sl-base-label + +Nested label component used to configure the label content, hint, and optional information shown above the field. + +
+ +| Item | Options | Description | +| --- | --- | --- | +| Label | `text` | Sets the label text. | +| Show Info | `boolean` | Shows or hides the info icon next to the label. | +| Show Hint | `boolean` | Shows or hides the hint text. | +| Hint | `text` | Sets the hint content shown with the label. | +| Optional | `false` | Figma property present in the nested label setup. Not currently exposed as an alternative option in this component. | +| Required | `false` | Figma property present in the nested label setup. Not currently exposed as an alternative option in this component. | + +{.ds-table .ds-table-align-top} + +
+ + +### sl-date-calendar + +Nested Calendar component shown inside the Picker. It is shared with the Range Field and controls the visual date selection experience. + +
+ +| Item | Options | Description | +| --- | --- | --- | +| View | `Days` `Months` `Years` | Switches the Calendar between day, month, and year selection views. | +| Footer | `boolean` | Shows or hides the footer area for quick actions such as selecting today or clearing the date. | + +{.ds-table .ds-table-align-top} + +
+ + +### Calendar Day Grid + +Nested Calendar properties are used to compose and preview date, month, and year selection states inside Figma. + +
+ +| Item | Options | Description | +| --- | --- | --- | +| Weeks Number | `boolean` | Shows or hides week numbers in the day grid. | + +{.ds-table .ds-table-align-top} + +
+ + +### Calendar Day Toggle Button + +Nested Calendar properties are used to compose and preview date, month, and year selection states inside Figma. + +
+ +| Item | Options | Description | +| --- | --- | --- | +| Type | `Default` `Secondary` `Disabled` | Previews the visual role or availability of Calendar items. | +| Selected | `False` `True` | Previews whether a day, month, or year item is selected. | +| Today Indicator | `boolean` | Shows the marker for today in the day view. | +| Focus | `boolean` | Shows the focus ring for a Calendar item. | +| Event Indicator | `boolean` | Shows a small indicator under a day item. | +| Current Indicator | `boolean` | Shows the marker for the current month or year. | + +{.ds-table .ds-table-align-top} + +
+
## Behavior @@ -98,11 +223,11 @@ Click the calendar icon button or press `Space`/`Enter` on it to open the popove ### Select-only mode When `select-only` is set, the input becomes read-only and users can only pick a date through the calendar popover. This is useful when you want to enforce valid input without relying on typed values. -### Min and max +### Min and max dates Dates outside the configured `min` / `max` range are disabled in the calendar and rejected by validation when typed. ### Require confirmation -When `require-confirmation` is set, the user must explicitly confirm the selected date in the calendar before it becomes the field value. This is useful in workflows where accidental selection could trigger an action. +When `require-confirmation` is set, the user must explicitly confirm the selected date in the calendar using the confirm button in the popover footer before it is set as the field value. This is useful in workflows where accidental selection could trigger an action.
From 94dafc7f3c1e6875b559cdb1c0042bfa1d13adfe Mon Sep 17 00:00:00 2001 From: arecuenco-dsgn Date: Wed, 3 Jun 2026 08:56:24 +0200 Subject: [PATCH 3/7] Draft Calendar Docs --- .../categories/components/calendar/usage.md | 120 +++++++++++++++--- 1 file changed, 100 insertions(+), 20 deletions(-) diff --git a/website/src/categories/components/calendar/usage.md b/website/src/categories/components/calendar/usage.md index c8b58a6f25..11988f52dd 100644 --- a/website/src/categories/components/calendar/usage.md +++ b/website/src/categories/components/calendar/usage.md @@ -31,24 +31,28 @@ eleventyNavigation: The following guidance describes when to use the calendar component. ### Visual date selection -Use the Calendar when users benefit from seeing a full month view to pick a date — for example, when context like weekdays, weekends, holidays or already booked days helps the choice. It works well embedded inside other components (such as the Date Field popover) or standalone in a panel. +Use the Calendar when users benefit from seeing dates in a full month view. This is useful when context such as weekdays, weekends, holidays, deadlines, or already booked days helps users make a clear date choice. ### Browsing dates -Use the Calendar when users need to browse and orient themselves in time, for example to see which weekday a date falls on, or to navigate between months and years before making a choice. +Use the Calendar when users need to browse and orient themselves in time, for example to check which weekday a date falls on or to navigate between months and years before selecting a date. + +### Date navigation +Use the Calendar anywhere users need to navigate through dates and make a selection. This is useful when users need to move between months or years, explore available dates, or choose a date within a broader date-based workflow. +
## When not to use The Calendar may not be the best choice in the following scenarios: -### Quick, known date entry -When users already know the exact date and just need to type it (for example a birth date), prefer the [Date Field](/categories/components/date-field/usage) which combines free typing with a popover calendar. +### Date selection +Calendar is a standalone date navigation component designed for browsing and navigating days, months, and years in date-related content, rather than for simple date entry or relative timeframe selection. Use the [Date Field](/categories/components/date-field/usage) when users need to enter a specific date, and use radio buttons, a segmented control, or a select for relative periods. + + -### Relative timeframes -Avoid the Calendar when only approximate periods or relative notions of time are needed (e.g. "next week", "this month"). Use radio buttons, a segmented control, or a select instead.
@@ -64,7 +68,7 @@ Avoid the Calendar when only approximate periods or relative notions of time are |2|Navigation buttons|Move to the previous or next month (and optionally year).|no| |3|Weekday row|Localized day-of-week labels.|no| |4|Week numbers|ISO week numbers next to each row.|yes| -|5|Day grid|Grid of selectable days for the visible month.|no| +|5|Grid|Grid of selectable days, month or year visible. |yes| |6|Today indicator|Visual marker for today's date.|yes| |7|Indicator dates|Visual markers for highlighted dates (e.g. events).|yes| @@ -74,6 +78,7 @@ Avoid the Calendar when only approximate periods or relative notions of time are +
## States @@ -83,30 +88,106 @@ Avoid the Calendar when only approximate periods or relative notions of time are - **Focus:** Display the focus ring on the focused day. - **Selected:** Highlighted styling on the selected date. - **Disabled day:** Days outside `min` / `max` or in `disabled-dates` are styled as non-selectable. -- **Indicator:** Days listed in `indicator-dates` show a visual marker. - **Disabled (whole calendar):** Non-interactive, muted. - **Read-only:** Visible state, no interaction.
+ +
+ +## Figma Properties + +These properties describe the Figma setup for the Calendar. Some properties represent real component behaviour, while others are only used to preview or compose the component in Figma. + +### sl-calendar + +Main component used to compose the Calendar and preview its available views. + +
+ +| Item | Options | Description | +| ------ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| View | `Days` `Months` `Years` | Switches the Calendar preview between day, month, and year selection views. | +| Footer | `boolean` | Figma-only composition property. The footer is not part of the current code component and should move to the Date Field or Range Field Picker composition. | + +{.ds-table .ds-table-align-top} + +
+ +### cal-header + +Nested header component used to preview which view-switching buttons are available in the Calendar header. + +
+ +| Item | Options | Description | +| ------------- | --------- | -------------------------------------------------------- | +| Month Button | `boolean` | Shows or hides the month button in the Calendar header. | +| Year Button | `boolean` | Shows or hides the year button in the Calendar header. | +| Decade Button | `boolean` | Shows or hides the decade button in the Calendar header. | + +{.ds-table .ds-table-align-top} + +
+ +### date-cal-days_grid + +Nested day grid component used to preview the day view layout. + +
+ +| Item | Options | Description | +| ------------ | --------- | -------------------------------------------- | +| Weeks Number | `boolean` | Shows or hides week numbers in the day grid. | + +{.ds-table .ds-table-align-top} + +
+ +### cal-months_grid + +Nested month grid component used to compose the month selection view. + +
+ +| Item | Options | Description | +| ---------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | +| Month grid | `nested component` | Displays selectable months when the Calendar is shown in the month view. No exposed Figma property was provided in the current screenshots. | + +{.ds-table .ds-table-align-top} + +
+ +### cal-years_grid + +Nested year grid component used to compose the year selection view. + +
+ +| Item | Options | Description | +| --------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | +| Year grid | `nested component` | Displays selectable years when the Calendar is shown in the year view. No exposed Figma property was provided in the current screenshots. | + +{.ds-table .ds-table-align-top} + +
+ +
+ +
## Behavior ### Selecting a date -Click a day or focus it with the keyboard and press `Enter` / `Space` to select it. Selecting a date emits an `sl-change` event. +Click a day or focus it with the keyboard and press `Enter` / `Space` to select it. -### Navigating months and years +### Navigating through dates Use the navigation buttons in the header, or use `Page Up` / `Page Down` (and `Shift + Page Up` / `Shift + Page Down`) to move between months and years from the keyboard. -### Min and max -Days outside the configured `min` / `max` range are visually disabled and cannot be selected. - -### Disabled and indicator dates -`disabled-dates` marks specific dates as non-selectable while still showing them in the grid. `indicator-dates` adds a visual marker to specific dates without changing their interactivity, which is useful for highlighting dates with events, deadlines or notifications. - -### Today -When `show-today` is set, today's date is visually highlighted to help users orient themselves in the current month. +### Day indicators +Calendar day buttons can display different visual indications to help users understand the status of a date. When `show-today` is set, today's date is visually highlighted to help users orient themselves in the current month. Dates included in `indicator-dates` display a visual marker without changing their interactivity, which is useful for highlighting events, deadlines, or notifications. Dates included in `disabled-dates`, or dates outside the configured `min` and `max` range, remain visible in the grid but are shown as unavailable and cannot be selected.
@@ -116,5 +197,4 @@ When `show-today` is set, today's date is visually highlighted to help users ori - [Date Field](/categories/components/date-field/usage): Input field that combines free typing with a calendar popover. - [Time Field](/categories/components/time-field/usage): Companion component for selecting a time. - - + \ No newline at end of file From 08699f89e0a82947db6478d908c33d6de2c0a79b Mon Sep 17 00:00:00 2001 From: anna-lach Date: Wed, 17 Jun 2026 16:01:48 +0200 Subject: [PATCH 4/7] docs(month-view): update CSS parts and improve accessibility documentation --- packages/components/calendar/src/month-view.ts | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/packages/components/calendar/src/month-view.ts b/packages/components/calendar/src/month-view.ts index c09681f7f4..b65da26a02 100644 --- a/packages/components/calendar/src/month-view.ts +++ b/packages/components/calendar/src/month-view.ts @@ -46,8 +46,15 @@ const DAYS_IN_WEEK = 7; * * @csspart day - The day button. * @csspart disabled - The day button when shown as disabled. + * @csspart header - The thead element with week day names. * @csspart indicator - The day button for a date with an indicator. + * @csspart indicator-blue - The day button for a date with a blue indicator. + * @csspart indicator-red - The day button for a date with a red indicator. + * @csspart indicator-yellow - The day button for a date with a yellow indicator. + * @csspart indicator-green - The day button for a date with a green indicator. + * @csspart indicator-grey - The day button for a date with a grey indicator. * @csspart next-month - The day button for a day in the next month. + * @csspart out-of-range - The day button for a date outside the min/max range. * @csspart previous-month - The day button for a day in the previous month. * @csspart selected - The day button for the selected date. * @csspart today - The day button for today's date. @@ -148,7 +155,7 @@ export class MonthView extends LocaleMixin(ScopedElementsMixin(LitElement)) { /** * The list of dates that should display an indicator. Each item is an Indicator with a `date`, an - * optional `color` and 'label' that is used to improve accessibility (added as a tooltip). + * optional `color` and `label` that is used to improve accessibility (added as a tooltip). */ @property({ attribute: 'indicator-dates', converter: indicatorConverter }) indicatorDates?: Indicator[]; @@ -306,6 +313,7 @@ export class MonthView extends LocaleMixin(ScopedElementsMixin(LitElement)) { `; } + /** Renders the header row with week day names. Override this to customize the header. */ renderHeader(): TemplateResult { return html` @@ -325,6 +333,7 @@ export class MonthView extends LocaleMixin(ScopedElementsMixin(LitElement)) { `; } + /** Renders a single day cell. You can also use the `renderer` property to customize how days look. */ renderDay(day: Day): TemplateResult { let template: TemplateResult | undefined; @@ -395,8 +404,11 @@ export class MonthView extends LocaleMixin(ScopedElementsMixin(LitElement)) { ].filter(part => part !== ''); }; + /** @internal */ override focus(options?: FocusOptions): void; + /** @internal */ override focus(date: Date): void; + /** @internal */ override focus(dateOrOptions?: Date | FocusOptions): void { if (dateOrOptions instanceof Date) { const button = this.renderRoot.querySelector( From 63b6cc15573512284761bc11e58af5dfcf804339 Mon Sep 17 00:00:00 2001 From: anna-lach Date: Thu, 18 Jun 2026 12:04:05 +0200 Subject: [PATCH 5/7] docs: calendar and date field - refine keyboard navigation instructions and improve component descriptions --- packages/components/calendar/src/calendar.ts | 10 ++++-- .../components/calendar/src/month-view.ts | 10 ++++-- .../components/calendar/accessibility.md | 7 ++-- .../categories/components/calendar/code.md | 32 +++---------------- .../categories/components/calendar/usage.md | 6 ++-- .../components/date-field/accessibility.md | 4 +-- .../categories/components/date-field/code.md | 26 ++++----------- .../categories/components/date-field/usage.md | 4 +-- 8 files changed, 33 insertions(+), 66 deletions(-) diff --git a/packages/components/calendar/src/calendar.ts b/packages/components/calendar/src/calendar.ts index bce12fb65f..5d2af3d438 100644 --- a/packages/components/calendar/src/calendar.ts +++ b/packages/components/calendar/src/calendar.ts @@ -81,20 +81,24 @@ export class Calendar extends LocaleMixin(ScopedElementsMixin(LitElement)) { /** * The list of dates that should display an indicator. Each item has a `date` and optional `color` - * and `label` values that are used to improve accessibility. + * and `label` values that are used to improve accessibility. Use `indicator-dates` to highlight + * specific dates with a visual indicator (for example, exam dates or assignment deadlines) + * without disabling them. */ @property({ attribute: 'indicator-dates', converter: indicatorConverter }) indicatorDates?: Indicator[]; /** - * The maximum date selectable in the calendar. + * The maximum date selectable in the calendar. Dates outside the range are visually disabled and + * cannot be selected. * * @default undefined */ @property({ converter: dateConverter }) max?: Date; /** - * The minimum date selectable in the calendar. + * The minimum date selectable in the calendar. Dates outside the range are visually disabled and + * cannot be selected. * * @default undefined */ diff --git a/packages/components/calendar/src/month-view.ts b/packages/components/calendar/src/month-view.ts index b65da26a02..8f2b3a8331 100644 --- a/packages/components/calendar/src/month-view.ts +++ b/packages/components/calendar/src/month-view.ts @@ -155,7 +155,9 @@ export class MonthView extends LocaleMixin(ScopedElementsMixin(LitElement)) { /** * The list of dates that should display an indicator. Each item is an Indicator with a `date`, an - * optional `color` and `label` that is used to improve accessibility (added as a tooltip). + * optional `color` and `label` that is used to improve accessibility (added as a tooltip). Use + * `indicator-dates` to highlight specific dates with a visual indicator (for example, exam dates + * or assignment deadlines) without disabling them. */ @property({ attribute: 'indicator-dates', converter: indicatorConverter }) indicatorDates?: Indicator[]; @@ -164,14 +166,16 @@ export class MonthView extends LocaleMixin(ScopedElementsMixin(LitElement)) { @state() localizedWeekOfYear?: string; /** - * The maximum date selectable in the month. + * The maximum date selectable in the month. Dates outside the range are visually disabled and + * cannot be selected. * * @default undefined */ @property({ converter: dateConverter }) max?: Date; /** - * The minimum date selectable in the month. + * The minimum date selectable in the month. Dates outside the range are visually disabled and + * cannot be selected. * * @default undefined */ diff --git a/website/src/categories/components/calendar/accessibility.md b/website/src/categories/components/calendar/accessibility.md index 19b4f57760..155ce25d6f 100644 --- a/website/src/categories/components/calendar/accessibility.md +++ b/website/src/categories/components/calendar/accessibility.md @@ -9,7 +9,7 @@ eleventyNavigation: ## Keyboard interactions -The calendar supports full keyboard navigation through the month view, with shortcuts for moving between months and years. +The calendar supports keyboard navigation through the month view.
@@ -18,9 +18,7 @@ The calendar supports full keyboard navigation through the month view, with shor |Tab| Moves focus into and out of the calendar grid and the month/year navigation controls. | |Arrow Left/Right| Moves focus to the previous or next day. | |Arrow Up/Down| Moves focus to the same day in the previous or next week. | -|Page Up/Down| Moves focus to the same day in the previous or next month. | -|Shift + Page Up/Down| Moves focus to the same day in the previous or next year. | -|Home/End| Moves focus to the first or last day of the current week. | +|Home/End| Moves focus to the first or last focusable day in the calendar grid. | |Enter/Space| Selects the currently focused date. | {.ds-table .ds-table-align-top} @@ -47,4 +45,3 @@ The calendar supports full keyboard navigation through the month view, with shor
- diff --git a/website/src/categories/components/calendar/code.md b/website/src/categories/components/calendar/code.md index 4d748a826c..8c9c7f5e0c 100644 --- a/website/src/categories/components/calendar/code.md +++ b/website/src/categories/components/calendar/code.md @@ -3,7 +3,7 @@ title: Calendar code tags: code APIdescription: { sl-calendar: "Calendar component that combines day, month and year selection views to pick a date. Used internally by the date field, but can also be used standalone.", - sl-month-view: "Low-level component that renders a single month grid without navigation controls. Used internally by select-day and can be used to compose custom calendar layouts." + sl-month-view: "A component that renders a single month grid without navigation controls. Used internally by select-day and can be used to compose custom calendar layouts." } eleventyNavigation: parent: Calendar @@ -13,14 +13,16 @@ eleventyNavigation:
```html - + ```
@@ -39,29 +41,5 @@ You can override the first day of the week with the `first-day-of-week` attribut -
- -## Min and max constraints - -Use the `min` and `max` attributes to restrict the selectable date range. Dates outside the range are visually disabled and cannot be selected. - -
- -
- -## Disabled and indicator dates - -Use `disabled-dates` to mark specific dates as non-selectable (for example, holidays or already booked days). Use `indicator-dates` to highlight specific dates with a visual indicator (for example, dates with events) without disabling them. - -
- -
- -## Week numbers - -Set `show-week-numbers` to display ISO week numbers next to each row of days. - -
- {% include "../component-table.njk" %} diff --git a/website/src/categories/components/calendar/usage.md b/website/src/categories/components/calendar/usage.md index 11988f52dd..b435252294 100644 --- a/website/src/categories/components/calendar/usage.md +++ b/website/src/categories/components/calendar/usage.md @@ -10,14 +10,14 @@ eleventyNavigation:
```html - + ```
@@ -197,4 +197,4 @@ Calendar day buttons can display different visual indications to help users unde - [Date Field](/categories/components/date-field/usage): Input field that combines free typing with a calendar popover. - [Time Field](/categories/components/time-field/usage): Companion component for selecting a time. - \ No newline at end of file + diff --git a/website/src/categories/components/date-field/accessibility.md b/website/src/categories/components/date-field/accessibility.md index 9bc4037b27..748a550d40 100644 --- a/website/src/categories/components/date-field/accessibility.md +++ b/website/src/categories/components/date-field/accessibility.md @@ -20,9 +20,7 @@ The date field supports keyboard navigation for both the input and the calendar |Escape| Closes the calendar popover. | |Arrow Left/Right (in calendar)| Moves focus to the previous or next day. | |Arrow Up/Down (in calendar)| Moves focus to the same day in the previous or next week. | -|Page Up/Down (in calendar)| Moves focus to the same day in the previous or next month. | -|Shift + Page Up/Down (in calendar)| Moves focus to the same day in the previous or next year. | -|Home/End (in calendar)| Moves focus to the first or last day of the current month. | +|Home/End (in calendar)| Moves focus to the first or last focusable day in the calendar grid. | |Enter (in calendar)| Selects the currently focused date and closes the popover. | {.ds-table .ds-table-align-top} diff --git a/website/src/categories/components/date-field/code.md b/website/src/categories/components/date-field/code.md index 361fb8ed90..d4cb4fa2c7 100644 --- a/website/src/categories/components/date-field/code.md +++ b/website/src/categories/components/date-field/code.md @@ -2,7 +2,7 @@ title: Date field code tags: code APIdescription: { - sl-date-field: "Form-aware date input with an integrated calendar popover. Supports localization, min/max constraints, validation and an optional select-only mode." + sl-date-field: "Date input for forms with a built-in calendar popover. Includes a range of configurable properties for different use cases." } eleventyNavigation: parent: Date field @@ -13,13 +13,15 @@ eleventyNavigation:
```html - + ```
@@ -32,25 +34,9 @@ eleventyNavigation: ## Localization -The date format and the first day of the week follow the active locale (via `Intl.DateTimeFormat`). -\ -You can override the first day of the week with the `first-day-of-week` attribute (`0` for Sunday, `1` for Monday, etc.). +The date format and first day of the week follow the active locale (via `Intl.DateTimeFormat`). - - -
- -## Min and max constraints - -Use the `min` and `max` attributes to restrict the selectable date range. Dates outside the range are disabled in the calendar and rejected by validation. - -
- -
- -## Select-only mode - -Set `select-only` to disable free typing in the input. Users can only pick a date through the calendar popover. +You can set `first-day-of-week` to choose the week start (`0` for Sunday, `1` for Monday, etc.).
diff --git a/website/src/categories/components/date-field/usage.md b/website/src/categories/components/date-field/usage.md index 30472b98f1..065ef81fd8 100644 --- a/website/src/categories/components/date-field/usage.md +++ b/website/src/categories/components/date-field/usage.md @@ -10,14 +10,14 @@ eleventyNavigation:
```html - + ```
From 7ffb1c0e5b974a4ab194a950e8752dc08dd7080d Mon Sep 17 00:00:00 2001 From: anna-lach Date: Thu, 18 Jun 2026 12:16:52 +0200 Subject: [PATCH 6/7] Changes after Copilot review --- packages/components/calendar/src/month-view.ts | 2 +- website/src/categories/components/calendar/code.md | 2 +- website/src/categories/components/calendar/usage.md | 9 +-------- website/src/categories/components/date-field/usage.md | 6 +++--- 4 files changed, 6 insertions(+), 13 deletions(-) diff --git a/packages/components/calendar/src/month-view.ts b/packages/components/calendar/src/month-view.ts index 8f2b3a8331..6621ee3a43 100644 --- a/packages/components/calendar/src/month-view.ts +++ b/packages/components/calendar/src/month-view.ts @@ -46,7 +46,7 @@ const DAYS_IN_WEEK = 7; * * @csspart day - The day button. * @csspart disabled - The day button when shown as disabled. - * @csspart header - The thead element with week day names. + * @csspart header - The thead element with weekday names. * @csspart indicator - The day button for a date with an indicator. * @csspart indicator-blue - The day button for a date with a blue indicator. * @csspart indicator-red - The day button for a date with a red indicator. diff --git a/website/src/categories/components/calendar/code.md b/website/src/categories/components/calendar/code.md index 8c9c7f5e0c..daecd2968b 100644 --- a/website/src/categories/components/calendar/code.md +++ b/website/src/categories/components/calendar/code.md @@ -3,7 +3,7 @@ title: Calendar code tags: code APIdescription: { sl-calendar: "Calendar component that combines day, month and year selection views to pick a date. Used internally by the date field, but can also be used standalone.", - sl-month-view: "A component that renders a single month grid without navigation controls. Used internally by select-day and can be used to compose custom calendar layouts." + sl-month-view: "A component that renders a single month grid without navigation controls. Used internally by sl-select-day and can be used to compose custom calendar layouts." } eleventyNavigation: parent: Calendar diff --git a/website/src/categories/components/calendar/usage.md b/website/src/categories/components/calendar/usage.md index b435252294..fb5f54ffee 100644 --- a/website/src/categories/components/calendar/usage.md +++ b/website/src/categories/components/calendar/usage.md @@ -41,7 +41,6 @@ Use the Calendar anywhere users need to navigate through dates and make a select -
## When not to use @@ -51,9 +50,6 @@ The Calendar may not be the best choice in the following scenarios: ### Date selection Calendar is a standalone date navigation component designed for browsing and navigating days, months, and years in date-related content, rather than for simple date entry or relative timeframe selection. Use the [Date Field](/categories/components/date-field/usage) when users need to enter a specific date, and use radio buttons, a segmented control, or a select for relative periods. - - -
@@ -78,7 +74,6 @@ Calendar is a standalone date navigation component designed for browsing and nav
-
## States @@ -93,7 +88,6 @@ Calendar is a standalone date navigation component designed for browsing and nav
-
## Figma Properties @@ -175,7 +169,6 @@ Nested year grid component used to compose the year selection view.
-
## Behavior @@ -184,7 +177,7 @@ Nested year grid component used to compose the year selection view. Click a day or focus it with the keyboard and press `Enter` / `Space` to select it. ### Navigating through dates -Use the navigation buttons in the header, or use `Page Up` / `Page Down` (and `Shift + Page Up` / `Shift + Page Down`) to move between months and years from the keyboard. +Use the navigation buttons in the header to move between months and years. In the calendar grid, use arrow keys to move by day or week, and `Home` / `End` to move to the first or last focusable day in the grid. ### Day indicators Calendar day buttons can display different visual indications to help users understand the status of a date. When `show-today` is set, today's date is visually highlighted to help users orient themselves in the current month. Dates included in `indicator-dates` display a visual marker without changing their interactivity, which is useful for highlighting events, deadlines, or notifications. Dates included in `disabled-dates`, or dates outside the configured `min` and `max` range, remain visible in the grid but are shown as unavailable and cannot be selected. diff --git a/website/src/categories/components/date-field/usage.md b/website/src/categories/components/date-field/usage.md index 065ef81fd8..352fa917c3 100644 --- a/website/src/categories/components/date-field/usage.md +++ b/website/src/categories/components/date-field/usage.md @@ -46,10 +46,10 @@ Use the Date Field when only a specific date range is valid, for example, future Date fields may not be the best choice in the following scenarios: ### Relative timeframes -Avoid the Date Field when only approximate periods or relative notions of time are needed (e.g., "next week", "this month", "in three days"). In these cases, prefer select or radio buttons that reflects a relative period. +Avoid the Date Field when only approximate periods or relative notions of time are needed (e.g., "next week", "this month", "in three days"). In these cases, prefer select or radio buttons that reflect a relative period. ### Date ranges -For selecting a start and end date together, prefer a dedicated date range picker rather than two separate date fields, when vailable. +For selecting a start and end date together, prefer a dedicated date range picker rather than two separate date fields, when available. ### Only calendar Do not use the Date Field when the date selection needs to be shown directly in the layout instead of inside a dropdown. Use the [Calendar](/categories/components/calendar/) when the visual date picker is the main interaction. @@ -85,7 +85,7 @@ Do not use the Date Field when the date selection needs to be shown directly in These states describe what users see when the Date Field is available. -- **Idle:** Empty, showing the placeholder, or with a formatted date as the value if the the field is filled. +- **Idle:** Empty, showing the placeholder, or with a formatted date as the value if the field is filled. - **Hover:** Visual hover effects that show the user that the field is interactive. - **Focus:** Display the focus ring. It's shown when the field is active by clicking or keyboard navigation. - **Invalid:** When an incorrect or out-of-range value is entered, the field is styled to indicate the error. From 43dd345efac2c7e57ca154b33b224988b7683ec2 Mon Sep 17 00:00:00 2001 From: anna-lach Date: Thu, 18 Jun 2026 12:42:40 +0200 Subject: [PATCH 7/7] Changes after Copilot review --- .../src/categories/components/calendar/code.md | 2 +- .../components/date-field/accessibility.md | 18 +++++++++--------- .../categories/components/date-field/code.md | 3 +-- .../categories/components/date-field/usage.md | 2 +- 4 files changed, 12 insertions(+), 13 deletions(-) diff --git a/website/src/categories/components/calendar/code.md b/website/src/categories/components/calendar/code.md index daecd2968b..b75d680fea 100644 --- a/website/src/categories/components/calendar/code.md +++ b/website/src/categories/components/calendar/code.md @@ -36,7 +36,7 @@ eleventyNavigation: ## Localization Month names, day names and the first day of the week follow the active locale (via `Intl.DateTimeFormat`). -\ + You can override the first day of the week with the `first-day-of-week` attribute (`0` for Sunday, `1` for Monday, etc.).
diff --git a/website/src/categories/components/date-field/accessibility.md b/website/src/categories/components/date-field/accessibility.md index 748a550d40..8c224433f2 100644 --- a/website/src/categories/components/date-field/accessibility.md +++ b/website/src/categories/components/date-field/accessibility.md @@ -13,15 +13,15 @@ The date field supports keyboard navigation for both the input and the calendar
-|Command| Description | -|-|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -|Tab| When focus is outside the date field, moves focus to the input. If focus is on the input, pressing Tab moves to the calendar trigger button, then to the next focusable element. | -|Space/Enter (on button)| Toggles the calendar popover when the button has focus. | -|Escape| Closes the calendar popover. | -|Arrow Left/Right (in calendar)| Moves focus to the previous or next day. | -|Arrow Up/Down (in calendar)| Moves focus to the same day in the previous or next week. | -|Home/End (in calendar)| Moves focus to the first or last focusable day in the calendar grid. | -|Enter (in calendar)| Selects the currently focused date and closes the popover. | +| Command | Description | +|--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Tab | When focus is outside the date field, moves focus to the input. If focus is on the input, pressing Tab moves to the calendar trigger button, then to the next focusable element. | +| Space/Enter (on button) | Toggles the calendar popover when the button has focus. | +| Escape | Closes the calendar popover. | +| Arrow Left/Right (in calendar) | Moves focus to the previous or next day. | +| Arrow Up/Down (in calendar) | Moves focus to the same day in the previous or next week. | +| Home/End (in calendar) | Moves focus to the first or last focusable day in the calendar grid. | +| Enter/Space (in calendar) | Selects the currently focused date. Closes the popover unless `require-confirmation` is set. | {.ds-table .ds-table-align-top} diff --git a/website/src/categories/components/date-field/code.md b/website/src/categories/components/date-field/code.md index d4cb4fa2c7..9f57505bd8 100644 --- a/website/src/categories/components/date-field/code.md +++ b/website/src/categories/components/date-field/code.md @@ -13,7 +13,6 @@ eleventyNavigation:
@@ -21,7 +20,7 @@ eleventyNavigation:
```html - + ```
diff --git a/website/src/categories/components/date-field/usage.md b/website/src/categories/components/date-field/usage.md index 352fa917c3..8150f15982 100644 --- a/website/src/categories/components/date-field/usage.md +++ b/website/src/categories/components/date-field/usage.md @@ -215,7 +215,7 @@ Nested Calendar properties are used to compose and preview date, month, and year ## Behavior ### Free Typing (Default) -Users can type any valid date matching the locale-aware format. The component validates for format, parsability, and the optional `min` / `max` range when the field loses focus. +Users can type only numbers in the day, month, and year segments. The date is checked when focus leaves the field, and errors are shown then. ### Calendar popover Click the calendar icon button or press `Space`/`Enter` on it to open the popover. Use the keyboard or pointer to focus a date and press `Enter` to select it. Pressing `Escape` closes the popover and returns focus to the input.