@urbicon-ui/blocks 6.1.4 → 6.1.5

package/dist/components/Calendar/Calendar.svelte

@@ -10,7 +10,8 @@
     toIso,
     stripTime,
     addDays,
-    clampMonth
+    clampMonth,
+    daysInMonth
   } from '../../date';
   import { DateGridController } from '../../internal/date-grid';
   import type { DateGridSelection, DateGridView } from '../../internal/date-grid';
@@ -43,6 +44,7 @@
     // Selection
     selectionMode = 'single',
     value = $bindable(undefined),
+    defaultDate,
     defaultMonth,
     defaultYear,
     // Locale
@@ -130,8 +132,12 @@
   // --- Reference date: the single anchor the grid is built around ---
   // Priority:
   //   1. the first selected date — a populated picker opens on its selection
-  //   2. `defaultMonth` / `defaultYear` — fallback when no value
-  //   3. today
+  //   2. `defaultDate` — an explicit day anchor (the only one that anchors a
+  //      week/day view on a specific week without also selecting that day)
+  //   3. `defaultMonth` / `defaultYear` — month/year anchor (resolves to the 1st;
+  //      fine for month/year views, but a week/day view then opens on the 1st's
+  //      week, which can fall mostly in the prior month — use `defaultDate` there)
+  //   4. today
   // Read at mount time only; the user navigates freely afterwards. Remount (e.g.
   // via DatePicker's popover open/close) to re-anchor on the current selection.
   function firstDateOf(v: CalendarProps['value']): Date | undefined {
@@ -142,16 +148,19 @@
   }
   function resolveInitialReference(
     v: CalendarProps['value'],
+    date: Date | undefined,
     month: number | undefined,
     year: number | undefined
   ): Date {
-    const anchor = firstDateOf(v);
+    const anchor = firstDateOf(v) ?? date;
     if (anchor) return stripTime(anchor);
     const today = stripTime(new Date());
     if (month == null && year == null) return today;
     return new Date(year ?? today.getFullYear(), month ?? today.getMonth(), 1);
   }
-  let referenceDate = $state(resolveInitialReference(value, defaultMonth, defaultYear));
+  let referenceDate = $state(
+    resolveInitialReference(value, defaultDate, defaultMonth, defaultYear)
+  );
 
   // The month/year derived from the single reference date.
   const displayedMonth = $derived(referenceDate.getMonth());
@@ -373,7 +382,15 @@
     const targetMonth = ((total % 12) + 12) % 12;
     const clamped = clampMonth(targetMonth, targetYear, minDate, maxDate);
     controller.navDirection = delta > 0 ? 'forward' : 'backward';
-    referenceDate = new Date(clamped.year, clamped.month, 1);
+    // Preserve the day-of-month (clamped) so a later switch to week/day view
+    // anchors on a real in-month day, not the 1st's (possibly prior-month) week.
+    const day = Math.min(referenceDate.getDate(), daysInMonth(clamped.year, clamped.month));
+    let next = new Date(clamped.year, clamped.month, day);
+    // clampMonth bounds the month; clamp the day too so it never lands before
+    // minDate / after maxDate within that boundary month.
+    if (minDate && next < stripTime(minDate)) next = stripTime(minDate);
+    if (maxDate && next > stripTime(maxDate)) next = stripTime(maxDate);
+    referenceDate = next;
     onMonthChange?.(clamped.month, clamped.year);
   }
 
@@ -391,8 +408,10 @@
 
   function navigateYear(delta: number) {
     controller.navDirection = delta > 0 ? 'forward' : 'backward';
-    referenceDate = new Date(displayedYear + delta, displayedMonth, 1);
-    onMonthChange?.(displayedMonth, displayedYear + delta);
+    const targetYear = displayedYear + delta;
+    const day = Math.min(referenceDate.getDate(), daysInMonth(targetYear, displayedMonth));
+    referenceDate = new Date(targetYear, displayedMonth, day);
+    onMonthChange?.(displayedMonth, targetYear);
   }
 
   function goToToday() {
@@ -400,7 +419,8 @@
   }
 
   function goToMonth(month: number, year: number) {
-    referenceDate = new Date(year, month, 1);
+    const day = Math.min(referenceDate.getDate(), daysInMonth(year, month));
+    referenceDate = new Date(year, month, day);
   }
 
   function setView(v: CalendarViewMode) {

package/dist/components/Calendar/index.d.ts

@@ -5,10 +5,13 @@ import type { CalendarEvent, CalendarEventCategory, CalendarSelection, CalendarV
 import type { CalendarVariants } from './calendar.variants';
 export type CalendarSlotName = 'base' | 'header' | 'title' | 'nav' | 'navButton' | 'grid' | 'weekdayHeader' | 'weekday' | 'weekRow' | 'weekNumber' | 'day' | 'dayNumber' | 'dotContainer' | 'dot' | 'list' | 'dateHeader' | 'empty' | 'item' | 'colorBar' | 'eventTitle' | 'eventDescription' | 'eventHelper' | 'legend' | 'legendItem' | 'legendDot' | 'legendLabel' | 'yearGrid' | 'yearMonth' | 'yearMonthTitle' | 'yearMiniDay' | 'yearMiniDot' | 'weekGrid' | 'weekColumn' | 'weekColumnHeader' | 'weekColumnDayName' | 'weekColumnDayNumber' | 'weekEventList' | 'weekAllDayEvent' | 'multiDayBar' | 'multiDayBarContainer' | 'agendaView' | 'agendaDayGroup' | 'agendaDayHeader' | 'agendaEventList' | 'dayView' | 'dayViewHeader' | 'dayEventList' | 'timeGrid' | 'timeLabel' | 'timeSlotRow' | 'timeDayColumn' | 'timeEvent' | 'allDayArea' | 'currentTimeLine' | 'weekTimeLayout' | 'eventPopover' | 'eventPopoverItem' | 'miniCalendar' | 'miniCalendarHeader' | 'miniCalendarTitle' | 'miniCalendarNavButton' | 'miniCalendarWeekday' | 'miniCalendarDay';
 /**
- * @description Flexible calendar component with month, year, week, and day views,
- * event display, date selection, and configurable layout.
+ * @description Flexible calendar component with month, year, week, and day views.
+ * Renders timed appointments, multi-day spans and recurrence on a time grid, with
+ * event display, date selection and configurable layout. For a headless grid that
+ * buckets your own domain content (meals, shifts, bookings) per day, use `Planner`.
  *
  * @tag display
+ * @related Planner
  * @related DatePicker
  * @related DateRangePicker
  *
@@ -53,8 +56,17 @@ export interface CalendarProps extends Omit<CalendarVariants, 'dayState' | 'hasE
     /** Currently selected date(s). Supports bind:value. */
     value?: CalendarSelection;
     /**
-     * Initial displayed month (0–11). Used only when `value` is unset;
-     * when `value` is provided, the calendar opens on the value's month.
+     * Initial reference day the grid is anchored on, without selecting it. Use
+     * this to open a **week** or **day** view on a specific week — `defaultMonth`/
+     * `defaultYear` resolve to the 1st, whose week can fall mostly in the previous
+     * month. Ignored when `value` is set (the selection anchors instead); takes
+     * priority over `defaultMonth`/`defaultYear`. Read at mount only.
+     */
+    defaultDate?: Date;
+    /**
+     * Initial displayed month (0–11). Used only when `value` and `defaultDate`
+     * are unset; when `value` is provided, the calendar opens on the value's
+     * month. Best for month/year views — for week/day views prefer `defaultDate`.
      * Defaults to current month.
      */
     defaultMonth?: number;

package/dist/components/ChartFrame/index.d.ts

@@ -12,6 +12,16 @@ import type { ChartMargin, ChartPlot, ChartSlotClasses } from '../../internal/ch
  * @related BarChart
  * @related Sankey
  * @stability beta
+ *
+ * @example
+ * ```svelte
+ * <ChartFrame height={200} ariaLabel="Weekly revenue">
+ *   {#snippet children({ innerWidth, innerHeight })}
+ *     <!-- map your data onto innerWidth / innerHeight, then draw SVG marks -->
+ *     <polyline points={pts} fill="none" class="stroke-primary" stroke-width="2" />
+ *   {/snippet}
+ * </ChartFrame>
+ * ```
  */
 export interface ChartFrameProps extends Omit<HTMLAttributes<HTMLElement>, 'children'> {
     /** Fixed SVG height in px. @default 240 */

package/dist/date/geometry.d.ts

@@ -37,6 +37,11 @@ export declare function getYearMonths(year: number): {
     month: number;
     year: number;
 }[];
+/**
+ * Number of days in a month, leap years included. `month` is 0-based
+ * (0 = January). Day 0 of the next month is the last day of this one.
+ */
+export declare function daysInMonth(year: number, month: number): number;
 /**
  * Clamp a month/year to optional min/max date boundaries.
  * Returns the (possibly adjusted) month/year plus flags for whether navigating

package/dist/date/geometry.js

@@ -77,6 +77,13 @@ export function getWeekNumber(date) {
 export function getYearMonths(year) {
     return Array.from({ length: 12 }, (_, i) => ({ month: i, year }));
 }
+/**
+ * Number of days in a month, leap years included. `month` is 0-based
+ * (0 = January). Day 0 of the next month is the last day of this one.
+ */
+export function daysInMonth(year, month) {
+    return new Date(year, month + 1, 0).getDate();
+}
 /**
  * Clamp a month/year to optional min/max date boundaries.
  * Returns the (possibly adjusted) month/year plus flags for whether navigating

package/dist/date/index.d.ts

@@ -14,5 +14,5 @@
  */
 export { daysBetween, isInMonth, isInRange, isSameDay, isWeekend, stripTime } from './compare';
 export { formatDate, formatDateFull, formatDateRange, formatDayTitle, formatMonthShort, formatMonthYear, formatWeekRange, formatWeekTitle, getWeekdayNames } from './format';
-export { clampMonth, getMonthGrid, getWeekDates, getWeekNumber, getYearMonths } from './geometry';
+export { clampMonth, daysInMonth, getMonthGrid, getWeekDates, getWeekNumber, getYearMonths } from './geometry';
 export { addDays, eachDayOfRange, endOfWeek, isoToDate, startOfWeek, toIso } from './range';

package/dist/date/index.js

@@ -14,5 +14,5 @@
  */
 export { daysBetween, isInMonth, isInRange, isSameDay, isWeekend, stripTime } from './compare';
 export { formatDate, formatDateFull, formatDateRange, formatDayTitle, formatMonthShort, formatMonthYear, formatWeekRange, formatWeekTitle, getWeekdayNames } from './format';
-export { clampMonth, getMonthGrid, getWeekDates, getWeekNumber, getYearMonths } from './geometry';
+export { clampMonth, daysInMonth, getMonthGrid, getWeekDates, getWeekNumber, getYearMonths } from './geometry';
 export { addDays, eachDayOfRange, endOfWeek, isoToDate, startOfWeek, toIso } from './range';

package/dist/internal/date-grid/date-grid.svelte.js

@@ -13,7 +13,7 @@
  * the source of truth (`bind:value`). Only `focusedDate`, `hoveredDate` and
  * `navDirection` are controller-owned `$state`.
  */
-import { addDays, clampMonth, daysBetween, endOfWeek, formatDateRange, formatDayTitle, formatMonthYear, formatWeekTitle, getMonthGrid, getWeekDates, getWeekdayNames, getWeekNumber, isInMonth, isInRange, isSameDay, isWeekend, startOfWeek, stripTime, toIso } from '../../date';
+import { addDays, clampMonth, daysBetween, daysInMonth, endOfWeek, formatDateRange, formatDayTitle, formatMonthYear, formatWeekTitle, getMonthGrid, getWeekDates, getWeekdayNames, getWeekNumber, isInMonth, isInRange, isSameDay, isWeekend, startOfWeek, stripTime, toIso } from '../../date';
 export class DateGridController {
     #opts;
     /** The roving keyboard focus target (local midnight). Controller-owned. */
@@ -228,7 +228,21 @@ export class DateGridController {
                 const targetYear = Math.floor(total / 12);
                 const targetMonth = ((total % 12) + 12) % 12;
                 const clamped = clampMonth(targetMonth, targetYear, minDate, maxDate);
-                next = new Date(clamped.year, clamped.month, 1);
+                // Preserve the day-of-month (clamped to the target month's length, e.g.
+                // 31 Jan → 28 Feb) rather than snapping to the 1st. Month view ignores the
+                // day, but a week/day view sharing this reference then anchors on a real
+                // in-month day — anchoring on the 1st can land its week mostly in the prior
+                // month (1 Mar 2026 is a Sunday → its Monday-week is 23 Feb–1 Mar). Matches
+                // the keyboard PageUp/PageDown month step, which already clamps the day.
+                const day = Math.min(referenceDate.getDate(), daysInMonth(clamped.year, clamped.month));
+                next = new Date(clamped.year, clamped.month, day);
+                // clampMonth bounds the month; clamp the preserved day too so it never lands
+                // before minDate / after maxDate within that boundary month (a week view
+                // would otherwise open on an all-disabled week just outside the range).
+                if (minDate && next < stripTime(minDate))
+                    next = stripTime(minDate);
+                if (maxDate && next > stripTime(maxDate))
+                    next = stripTime(maxDate);
                 break;
             }
             case 'week':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbicon-ui/blocks",
-  "version": "6.1.4",
+  "version": "6.1.5",
   "description": "Svelte 5 UI component library with Tailwind CSS 4, OKLCH design tokens and zero runtime dependencies",
   "license": "MIT",
   "repository": {
@@ -90,8 +90,8 @@
     "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^7.0.0",
     "@tailwindcss/vite": "^4.3.1",
-    "@urbicon-ui/i18n": "6.1.4",
-    "@urbicon-ui/shared-types": "6.1.4",
+    "@urbicon-ui/i18n": "6.1.5",
+    "@urbicon-ui/shared-types": "6.1.5",
     "prettier": "^3.8.4",
     "prettier-plugin-svelte": "^4.1.1",
     "prettier-plugin-tailwindcss": "^0.8.0",