@human-kit/svelte-components 1.0.0-alpha.2 → 1.0.0-alpha.4

package/dist/FOCUS_STATE_CONTRACT.md

@@ -0,0 +1,63 @@
+# Focus State Contract
+
+## Scope
+
+Focus-state contract for composed and interactive library components.
+
+## Canonical Attributes
+
+- `data-focused`: focused interactive element (real focus or logical focus for active item).
+- `data-focus-visible`: visible focus based on keyboard/screen-reader modality.
+- `data-focus-within`: any descendant inside the composed container has focus.
+
+## Serialization Rules
+
+1. Attributes are serialized as presence (`"true"`) or absence.
+2. Never serialize `"false"`.
+
+## Invariants
+
+1. On containers, `data-focus-visible` implies `data-focus-within`.
+2. On items, `data-focus-visible` implies `data-focused`.
+3. On external blur (focus leaves scope), clear container `data-focus-within` and `data-focus-visible`.
+
+## Modality
+
+- Keyboard/SR: may activate `data-focus-visible`.
+- Pointer: should not activate `data-focus-visible` by default.
+
+Canonical implementation lives in `primitives/input-modality.ts`:
+
+- `trackInteractionModality(event, target)` records input modality transitions.
+- `shouldShowFocusVisible(target)` resolves whether `data-focus-visible` should be shown.
+- `focusWithModality(target, modality)` atomically sets modality + programmatic focus restore.
+- Keep explicit `trackInteractionModality` calls in component keyboard/pointer handlers to guarantee deterministic modality updates before local focus-state logic runs.
+
+## Restore focus
+
+On overlay/popover close, transient trigger state is allowed:
+
+- `escape-key` => `data-focused=true` and `data-focus-visible=true`.
+- `outside-press` => `data-focused=true` and `data-focus-visible` absent.
+
+## Recommended Implementation
+
+- Native visual baseline: `:focus`, `:focus-visible`, `:focus-within`.
+- Use `data-*` for composed state and restore semantics.
+- Avoid overengineering: centralize minimal synchronization utilities and validate with contract tests.
+
+## Operational Template
+
+- Use `FOCUS_STATE_REVIEW_TEMPLATE.md` for PR/release reviews (modality matrix + component status + checklist).
+
+## Component Coverage
+
+The following components implement this contract:
+
+- **Popover** — trigger + content, restore focus on close.
+- **Dialog** — trigger + overlay/content, nested stack support.
+- **DatePicker** — segment spinbuttons, trigger, popover (calendar).
+- **TimePicker** — segment spinbuttons, trigger, popover (scrollable columns). Follows the same contract as DatePicker.
+- **Calendar** — grid cells with roving tabindex.
+- **ComboBox** — input + listbox with virtual focus.
+- **ListBox** — items with roving tabindex.

package/dist/FOCUS_STATE_REVIEW_TEMPLATE.md

@@ -0,0 +1,70 @@
+# Focus State Review Template
+
+## Usage
+
+Template to validate focus-related changes without adding extra CI guardrails.
+Fill this out for PRs that modify interaction, keyboard navigation, overlays, or focus-based styling.
+
+## 1) Review Metadata
+
+- PR/Branch:
+- Component(s):
+- Reviewer:
+- Date:
+- Verified browsers:
+  - [ ] Chromium
+  - [ ] Firefox
+  - [ ] WebKit/Safari
+
+## 2) Minimum Modality Matrix (per component)
+
+> Mark **OK/NA/FAIL** and add a short note when failing.
+
+| Scenario                           | What to validate                                                            | Status | Note |
+| ---------------------------------- | --------------------------------------------------------------------------- | ------ | ---- |
+| Keyboard (Tab/Arrow/Home/End/Page) | `data-*` and ARIA stay in sync with logical focus                           |        |      |
+| Pointer (click/mousedown)          | do not elevate `data-focus-visible` by default                              |        |      |
+| External blur                      | transient state cleanup (`data-focus-within`, `data-focus-visible`)         |        |      |
+| Close restore (`escape-key`)       | trigger: `data-focused=true`, `data-focus-visible=true` (when applicable)   |        |      |
+| Close restore (`outside-press`)    | trigger: `data-focused=true`, `data-focus-visible` absent (when applicable) |        |      |
+| Programmatic focus                 | does not break invariants or leave stale state                              |        |      |
+
+## 3) Required Invariants
+
+- [ ] Never serialize `'false'` for `data-focused`, `data-focus-visible`, `data-focus-within`.
+- [ ] On containers: `data-focus-visible => data-focus-within`.
+- [ ] On items: `data-focus-visible => data-focused`.
+- [ ] No visible desync between real focus, logical focus, and `data-*` attributes.
+
+## 4) Component Status (living status)
+
+> Use one row per component touched or audited.
+
+| Component  | Status                            | Current coverage | Residual risk   | Owner |
+| ---------- | --------------------------------- | ---------------- | --------------- | ----- |
+| DatePicker | Contract-ready / Partial / Legacy | tests + manual   | low/medium/high |       |
+| Popover    | Contract-ready / Partial / Legacy | tests + manual   | low/medium/high |       |
+| ListBox    | Contract-ready / Partial / Legacy | tests + manual   | low/medium/high |       |
+| ComboBox   | Contract-ready / Partial / Legacy | tests + manual   | low/medium/high |       |
+| Dialog     | Contract-ready / Partial / Legacy | tests + manual   | low/medium/high |       |
+| Calendar   | Contract-ready / Partial / Legacy | tests + manual   | low/medium/high |       |
+
+## 5) PR Checklist
+
+- [ ] If focus/keyboard/overlay behavior changed, tests were added or updated.
+- [ ] Shared helper was used: `src/lib/test-utils/focus-contract.ts`.
+- [ ] Focused suites for affected components were run.
+- [ ] If the change was cross-cutting, full package test suite was run.
+
+## 6) Suggested Commands
+
+- Focused (example):
+  - `bun run test -- --run src/lib/datepicker src/lib/popover src/lib/listbox src/lib/combobox src/lib/dialog src/lib/calendar`
+- Full:
+  - `bun run test -- --run`
+
+## 7) Final Decision
+
+- Final status: [ ] Approved [ ] Approved with risk [ ] Blocked
+- Residual risk summary:
+- Follow-up actions:

package/dist/calendar/README.md

@@ -12,6 +12,7 @@
 - In `single` mode, `value/defaultValue` is `YYYY-MM-DD`.
 - In `range` mode, `value/defaultValue` is `{ start?: 'YYYY-MM-DD', end?: 'YYYY-MM-DD' }`.
 - `visibleMonths` controls how many months are rendered and how paging behaves.
+- `showOutsideDays` controls whether days outside the current month are shown; default is `false`.
 - `isDateUnavailable` marks specific days as non-focusable and non-selectable.
 - Use `LocaleProvider` to localize month/day labels and first day of week.
 - Keyboard navigation uses `Arrow` keys for day/week movement and `Home/End` for month edges.
@@ -20,7 +21,7 @@
 
 - Each `grid` exposes an accessible name using the visible month heading.
 - Today exposes `aria-current="date"`.
-- Unavailable cells expose `aria-disabled="true"` and are neither focusable nor selectable.
+- Unavailable cells expose `aria-disabled="true"`. According to ARIA Grid specifications, disabled cells remain focusable so that screen reader users can spatially navigate and discover them, but they are not selectable.
 
 ### Keyboard
 

package/dist/calendar/TODO.md

@@ -1,109 +1,23 @@
 # Calendar TODO
 
-## MVP v1
-
-- [x] Controlled/uncontrolled root (`value`, `defaultValue`, `onChange`)
-- [x] Paginated navigation via `visibleMonths`
-- [x] Single-date selection
-- [x] `isDisabled`, `isReadOnly`, `isDateUnavailable` states
-- [x] Keyboard-accessible grid (baseline)
-- [x] Exports + docs page + initial tests
-
-## Future
-
-- [x] Range selection
-- [ ] Multi-select
-- [ ] Non-Gregorian calendar configuration
-- [ ] Advanced unavailable API (ranges/collections)
-
-### Advanced unavailable API (details)
-
-Goal: evolve from `isDateUnavailable?: (date) => boolean` to an expressive, composable, and performant API for blocking dates in real-world scenarios.
-
-#### 1) Functional requirements
-
-- [ ] Keep compatibility with the current `isDateUnavailable`.
-- [ ] Support `Set` of specific dates (`YYYY-MM-DD`) with O(1) lookup.
-- [ ] Support closed ranges `{ start, end }`.
-- [ ] Support recurring rules (for example: weekends, weekdays, dayOfWeek, dayOfMonth).
-- [ ] Support rule composition:
-  - [ ] `anyOf` (OR)
-  - [ ] `allOf` (AND)
-  - [ ] `except` (subtract dates/ranges)
-- [ ] Support combined usage (function + set + ranges + recurring rules).
-
-#### 2) Public API proposal
-
-- [ ] Add optional `unavailable` prop in `Calendar.Root`.
-- [ ] Base type design:
-  - [ ] `CalendarDateSet = Set<CalendarDateValue> | CalendarDateValue[]`
-  - [ ] `CalendarDateRange = { start: CalendarDateValue; end: CalendarDateValue }`
-  - [ ] `CalendarRecurringRule`
-  - [ ] `CalendarUnavailableRule = CalendarDateSet | CalendarDateRange | CalendarRecurringRule | ((date) => boolean)`
-  - [ ] `CalendarUnavailableConfig = CalendarUnavailableRule | { anyOf?: ...; allOf?: ...; except?: ... }`
-- [ ] Document precedence rules:
-  - [ ] `except` first
-  - [ ] then `allOf`
-  - [ ] then `anyOf`
-  - [ ] fallback to `false`
-- [ ] Clearly define how `unavailable` coexists with `isDateUnavailable` (for example: final OR for backward compatibility).
-
-#### 3) Validation and normalization
-
-- [ ] Validate invalid dates and reversed ranges in a robust way.
-- [ ] Normalize ranges (`start <= end`).
-- [ ] Silently ignore invalid entries or expose a dev warning (decide strategy).
-- [ ] Avoid runtime throws for partial input; prefer tolerant behavior.
-
-#### 4) Performance and caching
-
-- [ ] Compile `unavailable` to an internal predicate once per config change.
-- [ ] Cache results per visible date (`Map<CalendarDateValue, boolean>`).
-- [ ] Invalidate cache only when these change:
-  - [ ] locale
-  - [ ] visibleMonths
-  - [ ] `isDateUnavailable`
-  - [ ] `unavailable`
-- [ ] Avoid expensive recomputation during pending range selection.
-- [ ] Keep low complexity in `isDateDisabled` (prefer amortized O(1)).
-
-#### 5) Range mode integration
-
-- [ ] `isRangePathSelectable` must use the same unavailable source of truth.
-- [ ] If `except` exists, ensure endpoints and intermediate days follow the final composed rule.
-- [ ] Keep mouse hover preview and keyboard preview consistent.
-
-#### 6) Testing
-
-- [ ] Unit tests for unavailable parser/normalizer.
-- [ ] Compatibility tests with legacy `isDateUnavailable`.
-- [ ] Tests by type:
-  - [ ] date sets
-  - [ ] ranges
-  - [ ] recurring rules
-  - [ ] `anyOf`/`allOf`/`except` composition
-- [ ] Interaction tests (click/keyboard/range preview/confirm/cancel).
-- [ ] Performance tests (no unnecessary recomputation during selection and focus).
-
-#### 7) Documentation
-
-- [ ] Calendar README section for "Advanced unavailable".
-- [ ] Usage examples:
-  - [ ] block weekends
-  - [ ] block holidays (set)
-  - [ ] blackout by range
-  - [ ] composition with exceptions
-- [ ] Migration notes from current `isDateUnavailable`.
-
-#### 8) Demo
-
-- [ ] Extend docs demo with unavailable strategy selector.
-- [ ] Show derived state (active rule + visible blocked dates).
-- [ ] Include composition example (`anyOf` + `except`).
-
-#### 9) Completion criteria
-
-- [ ] `bun typecheck` passes without errors.
-- [ ] Calendar test suite is green.
-- [ ] Backward compatibility is verified.
-- [ ] API is documented with real examples.
+## Goal
+
+Track Calendar work with a single mandatory TODO format.
+
+## Backlog
+
+- [x] [M][P0][Area: Core API][Owner: Unassigned][Target: Done] Implement controlled/uncontrolled root (`value`, `defaultValue`, `onChange`).
+- [x] [M][P0][Area: Navigation][Owner: Unassigned][Target: Done] Implement paginated navigation via `visibleMonths`.
+- [x] [M][P0][Area: Selection][Owner: Unassigned][Target: Done] Implement single-date selection.
+- [x] [M][P0][Area: State][Owner: Unassigned][Target: Done] Support `isDisabled`, `isReadOnly`, and `isDateUnavailable`.
+- [x] [M][P0][Area: Accessibility][Owner: Unassigned][Target: Done] Deliver keyboard-accessible grid baseline.
+- [x] [M][P0][Area: Delivery][Owner: Unassigned][Target: Done] Ship exports, docs page, and initial tests.
+- [x] [S][P1][Area: Selection][Owner: Unassigned][Target: Done] Implement range selection.
+- [ ] [S][P1][Area: Selection][Owner: Unassigned][Target: TBD] Implement multi-select mode.
+- [ ] [C][P2][Area: Internationalization][Owner: Unassigned][Target: TBD] Add non-Gregorian calendar configuration.
+- [ ] [S][P1][Area: Availability API][Owner: Unassigned][Target: TBD] Add advanced unavailable API (set/ranges/rules).
+- [ ] [M][P0][Area: Availability API][Owner: Unassigned][Target: TBD] Keep backward compatibility with `isDateUnavailable`.
+- [ ] [M][P0][Area: Performance][Owner: Unassigned][Target: TBD] Compile unavailability config to cached predicate with proper invalidation.
+- [ ] [M][P0][Area: Testing][Owner: Unassigned][Target: TBD] Add coverage for unavailable parser, composition rules, and interaction flows.
+- [ ] [S][P1][Area: Documentation][Owner: Unassigned][Target: TBD] Document advanced unavailable API with migration examples.
+- [ ] [C][P2][Area: Demo][Owner: Unassigned][Target: TBD] Extend docs demo with unavailable strategy examples.

package/dist/calendar/body-cell/README.md

@@ -0,0 +1,15 @@
+# Calendar BodyCell
+
+## API reference
+
+### Calendar.BodyCell
+
+Name: `Calendar.BodyCell`  
+Description: Wrapper part for date grid cells inside `Calendar.GridBody`.
+
+| Prop           | Type                                   | Default     | Description                                                     |
+| -------------- | -------------------------------------- | ----------- | --------------------------------------------------------------- |
+| `date`         | `string`                               | `required`  | Calendar date value rendered by the cell (`YYYY-MM-DD`).        |
+| `children`     | `Snippet<[string]>`                    | `undefined` | Optional custom renderer receiving the day label text.          |
+| `class`        | `string`                               | `''`        | CSS class names for the inner gridcell element.                 |
+| `...restProps` | `HTMLAttributes<HTMLTableCellElement>` | `-`         | Additional attributes forwarded to the outer table cell (`td`). |

package/dist/calendar/body-cell/calendar-body-cell.svelte

@@ -1,9 +1,45 @@
+<script module lang="ts">
+	const ariaDateFormatterCache: Record<string, Intl.DateTimeFormat> = Object.create(null);
+
+	function getAriaDateFormatter(locale: string): Intl.DateTimeFormat {
+		let formatter = ariaDateFormatterCache[locale];
+		if (!formatter) {
+			formatter = new Intl.DateTimeFormat(locale, {
+				dateStyle: 'full',
+				timeZone: 'UTC'
+			});
+			ariaDateFormatterCache[locale] = formatter;
+		}
+		return formatter;
+	}
+
+	function formatAriaDateLabel(locale: string, date: string): string {
+		const [yearText, monthText, dayText] = date.split('-');
+		const year = Number(yearText);
+		const month = Number(monthText);
+		const day = Number(dayText);
+
+		if (!Number.isInteger(year) || !Number.isInteger(month) || !Number.isInteger(day)) {
+			return date;
+		}
+
+		const parsed = new Date(Date.UTC(year, month - 1, day));
+		if (Number.isNaN(parsed.getTime())) return date;
+
+		return getAriaDateFormatter(locale).format(parsed);
+	}
+</script>
+
 <script lang="ts">
 	import type { Snippet } from 'svelte';
 	import type { HTMLAttributes } from 'svelte/elements';
 	import { useCalendarContext } from '../root/context';
 	import { getCalendarMonthIndex } from '../grid/month-scope';
 	import { formatCalendarDate, getTodayUtcDate, parseCalendarDate } from '../root/date-utils';
+	import {
+		shouldShowFocusVisible,
+		trackInteractionModality
+	} from '../../primitives/input-modality';
 
 	type CalendarBodyCellProps = Omit<HTMLAttributes<HTMLTableCellElement>, 'children'> & {
 		date: string;
@@ -47,6 +83,11 @@
 		void $selectionVersion;
 		return calendar.focusedValue === date;
 	});
+	const isFocusVisible = $derived.by(() => {
+		void $selectionVersion;
+		return calendar.focusVisible;
+	});
+	const isVisuallyFocused = $derived(isFocused && isFocusVisible);
 	const isDisabled = $derived.by(() => {
 		void $layoutVersion;
 		void $selectionVersion;
@@ -56,56 +97,76 @@
 		void $layoutVersion;
 		return calendar.isDateUnavailable(date);
 	});
+	const isAriaDisabled = $derived(isDisabled || isUnavailable);
 	const isOutsideMonth = $derived.by(() => {
 		void $layoutVersion;
 		return calendar.isOutsideVisibleRange(date, monthIndex);
 	});
+	const showOutsideDays = $derived.by(() => {
+		void $layoutVersion;
+		return calendar.showOutsideDays;
+	});
+	const hidesOutsideDay = $derived(isOutsideMonth && !showOutsideDays);
+	const isSelectionDisabled = $derived(isDisabled || hidesOutsideDay);
+	const isFocusDisabled = $derived(calendar.isDisabled || hidesOutsideDay);
 	const todayDate = formatCalendarDate(getTodayUtcDate());
 	const isToday = $derived(date === todayDate);
+	const ariaDateLabel = $derived.by(() => {
+		void $layoutVersion;
+		return formatAriaDateLabel(calendar.locale, date);
+	});
 
-	let gridCellElement: HTMLDivElement | undefined;
+	let gridCellElement = $state<HTMLDivElement | undefined>(undefined);
 
 	$effect(() => {
-		if (!isFocused || isDisabled) return;
+		if (!isFocused || isFocusDisabled) return;
 		if (!gridCellElement) return;
 		if (document.activeElement === gridCellElement) return;
 		gridCellElement.focus();
 	});
 
 	$effect(() => {
-		if (!isDisabled) return;
+		if (!isFocusDisabled) return;
 		if (!gridCellElement) return;
 		if (document.activeElement !== gridCellElement) return;
 		gridCellElement.blur();
 	});
 
 	function handleClick() {
-		if (isDisabled) return;
+		if (isFocusDisabled) return;
 		calendar.setFocusedValue(date);
-		calendar.selectDate(date);
+		if (!isSelectionDisabled) {
+			calendar.selectDate(date);
+		}
 	}
 
 	function handleFocus() {
-		if (isDisabled) return;
+		if (isFocusDisabled) return;
 		calendar.setFocusedValue(date);
+		calendar.setFocusVisible(shouldShowFocusVisible(gridCellElement ?? null));
 	}
 
 	function handleMousedown(event: MouseEvent) {
-		if (!isDisabled) return;
-		event.preventDefault();
+		trackInteractionModality(event, gridCellElement ?? null);
+		calendar.setFocusVisible(false);
+		if (isSelectionDisabled) {
+			event.preventDefault();
+		}
 	}
 
 	function handleMouseenter() {
-		if (isDisabled) return;
+		if (isFocusDisabled) return;
 		calendar.setHoveredValue(date);
 	}
 
 	function handleMouseleave() {
-		if (isDisabled) return;
+		if (isFocusDisabled) return;
 		calendar.setHoveredValue(undefined);
 	}
 
 	function handleKeydown(event: KeyboardEvent) {
+		if (isFocusDisabled) return;
+		trackInteractionModality(event, gridCellElement ?? null);
 		calendar.handleCellKeydown(event, date);
 	}
 </script>
@@ -114,7 +175,8 @@
 	role="presentation"
 	data-selected={isSelected || undefined}
 	data-focused={isFocused || undefined}
-	data-disabled={isDisabled || undefined}
+	data-focus-visible={isVisuallyFocused || undefined}
+	data-disabled={isAriaDisabled || undefined}
 	data-unavailable={isUnavailable || undefined}
 	data-outside-month={isOutsideMonth || undefined}
 	data-range-start={isRangeStart || undefined}
@@ -122,34 +184,47 @@
 	data-in-range={isInRange || undefined}
 	{...restProps}
 >
-	<div
-		bind:this={gridCellElement}
-		class={className}
-		role="gridcell"
-		tabindex={isDisabled ? -1 : isFocused ? 0 : -1}
-		data-selected={isSelected || undefined}
-		data-focused={isFocused || undefined}
-		data-disabled={isDisabled || undefined}
-		data-unavailable={isUnavailable || undefined}
-		data-outside-month={isOutsideMonth || undefined}
-		data-range-start={isRangeStart || undefined}
-		data-range-end={isRangeEnd || undefined}
-		data-in-range={isInRange || undefined}
-		aria-selected={isSelected}
-		aria-disabled={isDisabled || undefined}
-		aria-current={isToday ? 'date' : undefined}
-		aria-label={date}
-		onmousedown={handleMousedown}
-		onmouseenter={handleMouseenter}
-		onmouseleave={handleMouseleave}
-		onclick={handleClick}
-		onfocus={handleFocus}
-		onkeydown={handleKeydown}
-	>
-		{#if children}
-			{@render children(date)}
-		{:else}
-			{dayLabel}
-		{/if}
-	</div>
+	{#if hidesOutsideDay}
+		<div
+			class={className}
+			role="presentation"
+			data-disabled={true}
+			data-outside-month={true}
+			aria-hidden="true"
+		></div>
+	{:else}
+		<div
+			bind:this={gridCellElement}
+			class={className}
+			role="gridcell"
+			tabindex={isFocusDisabled ? -1 : isFocused ? 0 : -1}
+			data-selected={isSelected || undefined}
+			data-focused={isFocused || undefined}
+			data-focus-visible={isVisuallyFocused || undefined}
+			data-disabled={isAriaDisabled || hidesOutsideDay || undefined}
+			data-unavailable={isUnavailable || undefined}
+			data-outside-month={isOutsideMonth || undefined}
+			data-range-start={isRangeStart || undefined}
+			data-range-end={isRangeEnd || undefined}
+			data-in-range={isInRange || undefined}
+			data-date={date}
+			aria-selected={isSelected}
+			aria-disabled={isAriaDisabled || hidesOutsideDay || undefined}
+			aria-current={isToday ? 'date' : undefined}
+			aria-label={ariaDateLabel}
+			style={isVisuallyFocused ? undefined : 'outline: none;'}
+			onmousedown={handleMousedown}
+			onmouseenter={handleMouseenter}
+			onmouseleave={handleMouseleave}
+			onclick={handleClick}
+			onfocus={handleFocus}
+			onkeydown={handleKeydown}
+		>
+			{#if children}
+				{@render children(date)}
+			{:else}
+				{dayLabel}
+			{/if}
+		</div>
+	{/if}
 </td>

package/dist/calendar/grid/README.md

@@ -0,0 +1,13 @@
+# Calendar Grid
+
+## API reference
+
+### Calendar.Grid
+
+Name: `Calendar.Grid`  
+Description: Calendar month table container rendered by `Calendar.Root`.
+
+| Prop       | Type      | Default     | Description                                   |
+| ---------- | --------- | ----------- | --------------------------------------------- |
+| `children` | `Snippet` | `undefined` | Optional custom month-grid content.           |
+| `class`    | `string`  | `''`        | CSS class names for the outer grid container. |

package/dist/calendar/grid-body/README.md

@@ -0,0 +1,13 @@
+# Calendar GridBody
+
+## API reference
+
+### Calendar.GridBody
+
+Name: `Calendar.GridBody`  
+Description: TBody container for week rows in `Calendar.Grid`.
+
+| Prop       | Type                | Default     | Description                                              |
+| ---------- | ------------------- | ----------- | -------------------------------------------------------- |
+| `children` | `Snippet<[string]>` | `undefined` | Optional custom renderer receiving each day date string. |
+| `class`    | `string`            | `''`        | CSS class names for the `tbody` element.                 |

package/dist/calendar/grid-header/README.md

@@ -0,0 +1,13 @@
+# Calendar GridHeader
+
+## API reference
+
+### Calendar.GridHeader
+
+Name: `Calendar.GridHeader`  
+Description: Header row group for weekday labels in `Calendar.Grid`.
+
+| Prop       | Type                | Default     | Description                                                      |
+| ---------- | ------------------- | ----------- | ---------------------------------------------------------------- |
+| `children` | `Snippet<[string]>` | `undefined` | Optional custom renderer receiving each localized weekday label. |
+| `class`    | `string`            | `''`        | CSS class names for the `thead` element.                         |

package/dist/calendar/header-cell/README.md

@@ -0,0 +1,14 @@
+# Calendar HeaderCell
+
+## API reference
+
+### Calendar.HeaderCell
+
+Name: `Calendar.HeaderCell`  
+Description: Weekday heading cell part used inside `Calendar.GridHeader`.
+
+| Prop           | Type                                   | Default     | Description                                        |
+| -------------- | -------------------------------------- | ----------- | -------------------------------------------------- |
+| `children`     | `Snippet`                              | `undefined` | Optional custom header cell content.               |
+| `class`        | `string`                               | `''`        | CSS class names for the header cell element.       |
+| `...restProps` | `HTMLAttributes<HTMLTableCellElement>` | `-`         | Additional attributes forwarded to the table cell. |

package/dist/calendar/heading/README.md

@@ -0,0 +1,13 @@
+# Calendar Heading
+
+## API reference
+
+### Calendar.Heading
+
+Name: `Calendar.Heading`  
+Description: Label part that displays the currently visible calendar period.
+
+| Prop           | Type                                 | Default | Description                                             |
+| -------------- | ------------------------------------ | ------- | ------------------------------------------------------- |
+| `class`        | `string`                             | `''`    | CSS class names for the heading element (`h2`).         |
+| `...restProps` | `HTMLAttributes<HTMLHeadingElement>` | `-`     | Additional attributes forwarded to the heading element. |

package/dist/calendar/root/README.md

@@ -0,0 +1,24 @@
+# Calendar Root
+
+## API reference
+
+### Calendar.Root
+
+Name: `Calendar.Root`  
+Description: Root state container for date grid rendering, navigation, selection, and locale-aware formatting.
+
+| Prop                | Type                                                       | Default     | Description                                                         |
+| ------------------- | ---------------------------------------------------------- | ----------- | ------------------------------------------------------------------- |
+| `selectionMode`     | `'single' \| 'range'`                                      | `'single'`  | Selection behavior and value shape.                                 |
+| `value`             | `CalendarDateValue \| CalendarRangeValue \| undefined`     | `bindable`  | Controlled selected value (single date or `{ start, end }`).        |
+| `defaultValue`      | `CalendarDateValue \| CalendarRangeValue \| undefined`     | `undefined` | Initial value for uncontrolled mode.                                |
+| `onChange`          | `(value: CalendarDateValue \| CalendarRangeValue) => void` | `undefined` | Called when selection changes.                                      |
+| `visibleMonths`     | `number`                                                   | `1`         | Number of month grids rendered simultaneously.                      |
+| `showOutsideDays`   | `boolean`                                                  | `false`     | Whether days outside the visible month remain rendered/interactive. |
+| `isDateUnavailable` | `(date: string) => boolean`                                | `undefined` | Marks specific dates as unavailable.                                |
+| `isDisabled`        | `boolean`                                                  | `false`     | Disables interaction and navigation.                                |
+| `isReadOnly`        | `boolean`                                                  | `false`     | Keeps navigation while preventing selection updates.                |
+| `children`          | `Snippet`                                                  | `undefined` | Composed `Calendar` parts.                                          |
+| `class`             | `string`                                                   | `''`        | CSS class names for the root wrapper.                               |
+| `id`                | `string`                                                   | `undefined` | Optional root id.                                                   |
+| `aria-label`        | `string`                                                   | `undefined` | Accessible label for the root wrapper.                              |

package/dist/calendar/root/calendar-root-test.svelte

@@ -5,6 +5,7 @@
 	type Props = {
 		selectionMode?: CalendarSelectionMode;
 		visibleMonths?: number;
+		showOutsideDays?: boolean;
 		isDisabled?: boolean;
 		isReadOnly?: boolean;
 		defaultValue?: CalendarValue;
@@ -14,6 +15,7 @@
 	let {
 		selectionMode = 'single',
 		visibleMonths = 1,
+		showOutsideDays = false,
 		isDisabled = false,
 		isReadOnly = false,
 		defaultValue,
@@ -32,6 +34,7 @@
 	<Calendar.Root
 		selectionMode="range"
 		{visibleMonths}
+		{showOutsideDays}
 		{isDisabled}
 		{isReadOnly}
 		defaultValue={rangeDefaultValue}
@@ -50,6 +53,7 @@
 	<Calendar.Root
 		selectionMode="single"
 		{visibleMonths}
+		{showOutsideDays}
 		{isDisabled}
 		{isReadOnly}
 		defaultValue={singleDefaultValue}