@gentleduck/registry-ui 0.3.0 → 0.3.1

package/.turbo/turbo-test.log

@@ -9,12 +9,12 @@ bun test v1.3.10 (30e609e0)
 
 ::group::src/sidebar/__test__/sidebar.test.tsx:
 (pass) registry-ui sidebar > SidebarTrigger prefers a provided icon over the default panel icon [1.00ms]
-(pass) registry-ui sidebar > SidebarTrigger still renders the default panel icon when no icon is provided [1.00ms]
+(pass) registry-ui sidebar > SidebarTrigger still renders the default panel icon when no icon is provided
 
 ::endgroup::
 
 ::group::src/chart/__test__/chart.test.tsx:
-(pass) registry-ui chart > ChartContainer server render does not emit invalid size warnings [9.00ms]
+(pass) registry-ui chart > ChartContainer server render does not emit invalid size warnings [11.00ms]
 
 ::endgroup::
 
@@ -29,7 +29,7 @@ bun test v1.3.10 (30e609e0)
 (pass) registry-ui button > buttonVariants applies explicit variant and size overrides
 (pass) registry-ui button > button exports keep stable display names
 (pass) registry-ui button > Button renders loading state as a busy disabled native button [1.00ms]
-(pass) registry-ui button > Button preserves explicit disabled state even when loading is false [1.00ms]
+(pass) registry-ui button > Button preserves explicit disabled state even when loading is false
 (pass) registry-ui button > Button collapses into icon-only mode and hides secondary content
 (pass) registry-ui button > AnimationIcon renders left and right placements around children
 
@@ -38,4 +38,4 @@ bun test v1.3.10 (30e609e0)
  14 pass
  0 fail
  43 expect() calls
-Ran 14 tests across 5 files. [403.00ms]
+Ran 14 tests across 5 files. [441.00ms]

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @gentleduck/registry-ui
 
+## 0.3.1
+
+### Patch Changes
+
+- Updated dependencies [58d1c61]
+  - @gentleduck/calendar@0.2.0
+
 ## 0.3.0
 
 ### Minor Changes

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 @gentleduck 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/SECURITY.md

@@ -0,0 +1,19 @@
+# Security Policy
+
+## Supported Versions
+We provide security updates for the latest major release of gentleduck/ui.  
+Older versions may not receive patches.
+
+## Reporting a Vulnerability
+⚠️ **Please do not disclose security issues publicly.**  
+If you discover a vulnerability in gentleduck/ui:
+
+1. Report it privately by emailing: **security@gentleduck.org**
+2. Include a detailed description of the vulnerability and how to reproduce it.
+3. We will confirm receipt within **48 hours** and provide a timeline for a fix.
+
+## Responsible Disclosure
+We ask security researchers to give us **90 days** to address issues before public disclosure.  
+We will credit you in release notes unless you prefer to remain anonymous.
+
+Thank you for helping keep gentleduck/ui secure.

package/package.json

@@ -4,6 +4,7 @@
     "node": ">=22.0.0"
   },
   "dependencies": {
+    "@gentleduck/calendar": "workspace:*",
     "@gentleduck/hooks": "^0.1.12",
     "@gentleduck/libs": "^0.1.15",
     "@gentleduck/motion": "^0.1.17",
@@ -14,7 +15,6 @@
     "lucide-react": "0.577.0",
     "next-themes": "^0.4.6",
     "react": "^19.2.4",
-    "react-day-picker": "^9.8.1",
     "react-dom": "^19.2.4",
     "react-hook-form": "^7.71.1",
     "react-resizable-panels": "^4.7.0",
@@ -56,5 +56,13 @@
     "test": "bun test"
   },
   "type": "module",
-  "version": "0.3.0"
+  "version": "0.3.1",
+  "description": "Styled Tailwind components for Duck UI.",
+  "keywords": [
+    "gentleduck",
+    "react",
+    "components",
+    "tailwind",
+    "ui"
+  ]
 }

package/src/calendar/calendar-day.tsx

@@ -0,0 +1,131 @@
+'use client'
+
+import type { CalendarDay as CalendarDayType, DayProps } from '@gentleduck/calendar'
+import { cn } from '@gentleduck/libs/cn'
+import * as React from 'react'
+import { buttonVariants } from '../button'
+import { getCachedNumberFormat } from './calendar.utils'
+
+const HEBREW_ONES = [
+  '',
+  '\u05D0\u05F3',
+  '\u05D1\u05F3',
+  '\u05D2\u05F3',
+  '\u05D3\u05F3',
+  '\u05D4\u05F3',
+  '\u05D5\u05F3',
+  '\u05D6\u05F3',
+  '\u05D7\u05F3',
+  '\u05D8\u05F3',
+]
+const HEBREW_TENS = ['', '\u05D9\u05F3', '\u05DB\u05F3', '\u05DC\u05F3']
+
+function toHebrewNumeral(n: number): string {
+  if (n === 15) return '\u05D8\u05F4\u05D5'
+  if (n === 16) return '\u05D8\u05F4\u05D6'
+  const ten = Math.floor(n / 10)
+  const one = n % 10
+  if (one === 0) return HEBREW_TENS[ten] ?? String(n)
+  if (ten === 0) return HEBREW_ONES[one] ?? String(n)
+  const t = (HEBREW_TENS[ten] ?? '').replace('\u05F3', '')
+  const o = (HEBREW_ONES[one] ?? '').replace('\u05F3', '')
+  return `${t}\u05F4${o}`
+}
+
+interface CalendarDayCellProps {
+  day: CalendarDayType<Date>
+  dayProps: Omit<DayProps, 'role' | 'aria-selected' | 'onMouseEnter'>
+  isFocused: boolean
+  isSelectedSingle: boolean
+  isFirstInRow: boolean
+  isLastInRow: boolean
+  locale?: string
+  onFocusDate: (date: Date) => void
+  renderDay?: (day: CalendarDayType<Date>, children: React.ReactNode) => React.ReactNode
+}
+
+function formatDayNumber(d: number, locale?: string): React.ReactNode {
+  if (!locale) return d
+  if (locale.startsWith('ar')) return getCachedNumberFormat(`${locale}-u-nu-arab`).format(d)
+  if (locale.startsWith('he')) return toHebrewNumeral(d)
+  return getCachedNumberFormat(locale).format(d)
+}
+
+export const CalendarDayCell = React.memo(function CalendarDayCell({
+  day,
+  dayProps,
+  isFocused,
+  isSelectedSingle,
+  isFirstInRow,
+  isLastInRow,
+  locale,
+  onFocusDate,
+  renderDay,
+}: CalendarDayCellProps) {
+  const isInRange = day.isRangeStart || day.isRangeEnd || day.isRangeMiddle
+  const dayNum = formatDayNumber(day.date.getDate(), locale)
+
+  return (
+    // biome-ignore lint/a11y/useSemanticElements: gridcell on div per WAI-ARIA grid pattern
+    // biome-ignore lint/a11y/useFocusableInteractive: gridcell focus is on the child button
+    <div
+      role="gridcell"
+      aria-selected={day.isSelected}
+      data-selected={day.isSelected ? 'true' : undefined}
+      data-focused={isFocused ? 'true' : undefined}
+      className={cn(
+        'group/day relative aspect-square h-full w-full select-none p-0 text-center',
+        day.isHidden && 'invisible',
+        isInRange && 'overflow-hidden',
+        day.isRangeStart && 'rounded-s-md bg-accent',
+        day.isRangeEnd && 'rounded-e-md bg-accent',
+        day.isRangeMiddle && 'bg-accent',
+        isInRange && isFirstInRow && !day.isRangeStart && 'rounded-s-md',
+        isInRange && isLastInRow && !day.isRangeEnd && 'rounded-e-md',
+        day.isOutside && !day.isHidden && 'text-muted-foreground',
+        day.isOutside && !day.isHidden && day.isSelected && 'text-muted-foreground',
+        day.isDisabled && !day.isHidden && 'pointer-events-none text-muted-foreground opacity-50',
+      )}>
+      <button
+        type="button"
+        {...dayProps}
+        disabled={day.isDisabled}
+        tabIndex={day.isDisabled ? -1 : dayProps.tabIndex}
+        onClick={(e) => {
+          if (day.isDisabled) return
+          dayProps.onClick({ shiftKey: e.shiftKey })
+          onFocusDate(day.date)
+          // Remove browser focus so the cell returns to neutral visual state
+          ;(e.currentTarget as HTMLElement).blur()
+        }}
+        data-day={day.date.toLocaleDateString()}
+        data-range-end={day.isRangeEnd || undefined}
+        data-range-middle={day.isRangeMiddle || undefined}
+        data-range-start={day.isRangeStart || undefined}
+        data-selected-single={isSelectedSingle || undefined}
+        data-today={day.isToday || undefined}
+        data-focused={isFocused || undefined}
+        className={cn(
+          buttonVariants({ variant: 'ghost', size: 'icon' }),
+          'flex aspect-square size-auto w-full min-w-(--gentleduck-calendar-cell) flex-col gap-1 font-normal leading-none focus-visible:ring-0 focus-visible:ring-offset-0',
+          // Single selection
+          'data-[selected-single=true]:rounded-md data-[selected-single=true]:bg-primary data-[selected-single=true]:text-primary-foreground',
+          // Range selection
+          'data-[range-start=true]:rounded-s-md data-[range-start=true]:bg-primary data-[range-start=true]:text-primary-foreground',
+          'data-[range-end=true]:rounded-e-md data-[range-end=true]:bg-primary data-[range-end=true]:text-primary-foreground',
+          'data-[range-middle=true]:rounded-none data-[range-middle=true]:bg-accent data-[range-middle=true]:text-accent-foreground',
+          // Outside month
+          day.isOutside && 'text-muted-foreground/50',
+          // Today
+          'data-[today=true]:font-semibold',
+          // Focus ring
+          'group-data-[focused=true]/day:relative group-data-[focused=true]/day:z-10 group-data-[focused=true]/day:rounded-md group-data-[focused=true]/day:border group-data-[focused=true]/day:border-ring group-data-[focused=true]/day:ring-1 group-data-[focused=true]/day:ring-ring/50',
+          '[&>span]:text-xs [&>span]:opacity-70',
+        )}>
+        {renderDay ? renderDay(day, dayNum) : dayNum}
+      </button>
+    </div>
+  )
+})
+
+CalendarDayCell.displayName = 'CalendarDayCell'

package/src/calendar/calendar-header.tsx

@@ -0,0 +1,291 @@
+'use client'
+
+import { buildCalendarYear, type DateAdapter, goToMonth, goToYear, NativeAdapter } from '@gentleduck/calendar'
+import { cn } from '@gentleduck/libs/cn'
+import { CheckIcon, ChevronDownIcon, ChevronLeftIcon, ChevronRightIcon } from 'lucide-react'
+import * as React from 'react'
+import { buttonVariants } from '../button'
+import { getCachedNumberFormat } from './calendar.utils'
+
+const defaultAdapter = new NativeAdapter()
+
+/** Height of each dropdown item in pixels. */
+const ITEM_HEIGHT = 28
+/** Number of items visible in the dropdown viewport. */
+const VISIBLE_ITEMS = 9
+const LIST_HEIGHT = ITEM_HEIGHT * VISIBLE_ITEMS
+/** Extra items rendered above/below the visible area for smooth scrolling. */
+const OVERSCAN = 3
+
+// ---------------------------------------------------------------------------
+// VirtualizedDropdown  -  shared by month and year
+// ---------------------------------------------------------------------------
+
+function VirtualizedDropdown({
+  items,
+  activeValue,
+  onSelect,
+  open,
+}: {
+  items: { value: string; label: string }[]
+  activeValue: string
+  onSelect: (value: string) => void
+  open: boolean
+}) {
+  const scrollRef = React.useRef<HTMLDivElement>(null)
+  const [scrollTop, setScrollTop] = React.useState(() => {
+    const idx = items.findIndex((i) => i.value === activeValue)
+    return Math.max(0, idx * ITEM_HEIGHT - LIST_HEIGHT / 2 + ITEM_HEIGHT / 2)
+  })
+
+  const totalHeight = items.length * ITEM_HEIGHT
+
+  React.useLayoutEffect(() => {
+    if (!open || !scrollRef.current) return
+    const idx = items.findIndex((i) => i.value === activeValue)
+    const target = Math.max(0, idx * ITEM_HEIGHT - LIST_HEIGHT / 2 + ITEM_HEIGHT / 2)
+    scrollRef.current.scrollTop = target
+    setScrollTop(target)
+  }, [activeValue, items, open])
+
+  const startIndex = Math.max(0, Math.floor(scrollTop / ITEM_HEIGHT) - OVERSCAN)
+  const endIndex = Math.min(items.length, Math.ceil((scrollTop + LIST_HEIGHT) / ITEM_HEIGHT) + OVERSCAN)
+
+  // Find the longest label to size the container
+  const longestLabel = React.useMemo(
+    () => items.reduce((a, b) => (b.label.length > a.length ? b.label : a), ''),
+    [items],
+  )
+
+  return (
+    <div
+      ref={scrollRef}
+      data-state={open ? 'open' : 'closed'}
+      className={cn(
+        'overflow-y-auto rounded-md border bg-popover p-1 shadow-md',
+        'data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[state=open]:slide-in-from-top-2 data-[state=closed]:slide-out-to-top-2 origin-top data-[state=closed]:hidden data-[state=closed]:animate-out data-[state=open]:animate-in',
+        'transition-all transition-discrete duration-150 ease-(--duck-motion-ease)',
+      )}
+      style={{ height: LIST_HEIGHT, scrollBehavior: 'auto' }}
+      onScroll={(e) => setScrollTop(e.currentTarget.scrollTop)}>
+      {/* Hidden sizer  -  establishes the intrinsic width from the longest label */}
+      <div
+        aria-hidden
+        className="pointer-events-none invisible flex h-0 items-center gap-2 overflow-hidden ps-6 pe-4 text-sm">
+        <CheckIcon className="size-3.5 shrink-0" />
+        {longestLabel}
+      </div>
+      <div style={{ height: totalHeight, position: 'relative' }}>
+        {items.slice(startIndex, endIndex).map((item, i) => {
+          const isActive = item.value === activeValue
+          return (
+            <button
+              key={item.value}
+              type="button"
+              className={cn(
+                'flex w-full cursor-default select-none items-center gap-2 whitespace-nowrap rounded-sm ps-6 pe-2 text-sm outline-none hover:bg-accent hover:text-accent-foreground',
+                isActive && 'bg-accent font-medium text-accent-foreground',
+              )}
+              style={{
+                position: 'absolute',
+                top: (startIndex + i) * ITEM_HEIGHT,
+                height: ITEM_HEIGHT,
+                left: 0,
+                right: 0,
+              }}
+              onClick={() => onSelect(item.value)}>
+              {isActive && <CheckIcon className="absolute start-1.5 size-3.5" />}
+              {item.label}
+            </button>
+          )
+        })}
+      </div>
+    </div>
+  )
+}
+
+// ---------------------------------------------------------------------------
+// DropdownTrigger  -  shared trigger button
+// ---------------------------------------------------------------------------
+
+function DropdownTrigger({ label, open, onClick }: { label: string; open: boolean; onClick: () => void }) {
+  return (
+    <button
+      type="button"
+      dir="ltr"
+      aria-expanded={open}
+      onClick={onClick}
+      className="flex h-7 w-fit shrink-0 items-center gap-1 whitespace-nowrap rounded-md border px-2 font-medium text-sm shadow-xs">
+      <span dir="auto">{label}</span>
+      <ChevronDownIcon className="size-3 text-muted-foreground" />
+    </button>
+  )
+}
+
+// ---------------------------------------------------------------------------
+// CalendarHeader
+// ---------------------------------------------------------------------------
+
+interface CalendarHeaderProps {
+  adapter?: DateAdapter<Date>
+  month: Date
+  title: string
+  direction: 'ltr' | 'rtl'
+  locale?: string
+  buttonVariant: string
+  showDropdowns: boolean
+  yearRange: { from: number; to: number }
+  getNavProps: (dir: 'prev' | 'next') => { 'aria-label': string; disabled: boolean; onClick: () => void }
+  getHeaderProps: () => { id: string; 'aria-live': 'polite' }
+  onMonthSelect: (date: Date) => void
+}
+
+/** Prevents Select portal interactions from dismissing parent Popover. */
+function stopPopoverDismiss(e: React.PointerEvent) {
+  e.stopPropagation()
+}
+
+export function CalendarHeader({
+  adapter: adapterProp,
+  month,
+  title,
+  direction,
+  locale,
+  buttonVariant,
+  showDropdowns,
+  yearRange,
+  getNavProps,
+  getHeaderProps,
+  onMonthSelect,
+}: CalendarHeaderProps) {
+  const adapter = adapterProp ?? defaultAdapter
+  const headerProps = getHeaderProps()
+  const currentYear = adapter.getYear(month)
+  const currentMonth = adapter.getMonth(month)
+  const [monthOpen, setMonthOpen] = React.useState(false)
+  const [yearOpen, setYearOpen] = React.useState(false)
+  const dropdownRef = React.useRef<HTMLDivElement>(null)
+
+  // Close dropdowns on click outside (without a fixed backdrop that breaks Popover)
+  React.useEffect(() => {
+    if (!monthOpen && !yearOpen) return
+    function handlePointerDown(e: PointerEvent) {
+      if (dropdownRef.current && !dropdownRef.current.contains(e.target as Node)) {
+        setMonthOpen(false)
+        setYearOpen(false)
+      }
+    }
+    document.addEventListener('pointerdown', handlePointerDown, true)
+    return () => document.removeEventListener('pointerdown', handlePointerDown, true)
+  }, [monthOpen, yearOpen])
+
+  const isArabic = locale?.startsWith('ar')
+  const formatLocaleTag = isArabic ? `${locale}-u-nu-arab` : locale
+
+  const monthItems = React.useMemo(() => {
+    const entries = buildCalendarYear(adapter, month, locale)
+    return entries.map((e) => ({
+      value: String(e.month),
+      label: isArabic ? e.label : e.label.slice(0, 3),
+    }))
+  }, [adapter, month, locale, isArabic])
+
+  const yearItems = React.useMemo(() => {
+    const fmt = formatLocaleTag ? getCachedNumberFormat(formatLocaleTag, { useGrouping: false }) : null
+    const result: { value: string; label: string }[] = []
+    for (let y = yearRange.from; y <= yearRange.to; y++) {
+      result.push({ value: String(y), label: fmt ? fmt.format(y) : String(y) })
+    }
+    return result
+  }, [yearRange.from, yearRange.to, formatLocaleTag])
+
+  return (
+    <div className="flex h-(--gentleduck-calendar-cell) w-full items-center justify-center px-(--gentleduck-calendar-cell)">
+      <div className="absolute inset-x-0 top-0 flex w-full items-center justify-between gap-1">
+        <button
+          type="button"
+          {...getNavProps('prev')}
+          className={cn(
+            buttonVariants({ variant: buttonVariant as 'ghost' }),
+            'size-(--gentleduck-calendar-cell) select-none p-0 aria-disabled:opacity-50',
+          )}>
+          <ChevronLeftIcon className={cn('size-4', direction === 'rtl' && 'rotate-180')} />
+        </button>
+
+        {showDropdowns ? (
+          <div
+            ref={dropdownRef}
+            {...headerProps}
+            className="flex items-center gap-1.5"
+            onPointerDown={stopPopoverDismiss}>
+            {/* Month dropdown */}
+            <div className="relative">
+              <DropdownTrigger
+                label={adapter.format(month, { month: isArabic ? 'long' : 'short' }, formatLocaleTag)}
+                open={monthOpen}
+                onClick={() => {
+                  setMonthOpen((o) => !o)
+                  setYearOpen(false)
+                }}
+              />
+              <div className="absolute start-0 top-full z-50 mt-1">
+                <VirtualizedDropdown
+                  items={monthItems}
+                  activeValue={String(currentMonth)}
+                  open={monthOpen}
+                  onSelect={(v) => {
+                    onMonthSelect(goToMonth(adapter, month, Number(v)))
+                    setMonthOpen(false)
+                  }}
+                />
+              </div>
+            </div>
+
+            {/* Year dropdown */}
+            <div className="relative">
+              <DropdownTrigger
+                label={
+                  formatLocaleTag
+                    ? getCachedNumberFormat(formatLocaleTag, { useGrouping: false }).format(currentYear)
+                    : String(currentYear)
+                }
+                open={yearOpen}
+                onClick={() => {
+                  setYearOpen((o) => !o)
+                  setMonthOpen(false)
+                }}
+              />
+              <div className="absolute end-0 top-full z-50 mt-1">
+                <VirtualizedDropdown
+                  items={yearItems}
+                  activeValue={String(currentYear)}
+                  open={yearOpen}
+                  onSelect={(v) => {
+                    onMonthSelect(goToYear(adapter, month, Number(v)))
+                    setYearOpen(false)
+                  }}
+                />
+              </div>
+            </div>
+          </div>
+        ) : (
+          <div {...headerProps} className="select-none font-medium text-sm">
+            {title}
+          </div>
+        )}
+
+        <button
+          type="button"
+          {...getNavProps('next')}
+          className={cn(
+            buttonVariants({ variant: buttonVariant as 'ghost' }),
+            'size-(--gentleduck-calendar-cell) select-none p-0 aria-disabled:opacity-50',
+          )}>
+          <ChevronRightIcon className={cn('size-4', direction === 'rtl' && 'rotate-180')} />
+        </button>
+      </div>
+    </div>
+  )
+}
+
+CalendarHeader.displayName = 'CalendarHeader'

package/src/calendar/calendar.tsx

@@ -1,211 +1,224 @@
 'use client'
 
+import { NativeAdapter, useCalendar } from '@gentleduck/calendar'
 import { cn } from '@gentleduck/libs/cn'
-import { type Direction, useDirection } from '@gentleduck/primitives/direction'
-import { ChevronDownIcon, ChevronLeftIcon, ChevronRightIcon } from 'lucide-react'
+import { useDirection } from '@gentleduck/primitives/direction'
+import { ChevronLeftIcon, ChevronRightIcon } from 'lucide-react'
 import * as React from 'react'
-import { type DayButton, DayPicker, getDefaultClassNames } from 'react-day-picker'
-import { Button, buttonVariants } from '../button'
+import { buttonVariants } from '../button'
+import type { CalendarProps } from './calendar.types'
+import { CalendarDayCell } from './calendar-day'
+import { CalendarHeader } from './calendar-header'
 
-function mergeRefs<T>(...refs: (React.Ref<T> | undefined)[]): React.RefCallback<T> {
-  return (node) => {
-    for (const ref of refs) {
-      if (typeof ref === 'function') {
-        ref(node)
-      } else if (ref != null) {
-        ;(ref as React.MutableRefObject<T | null>).current = node
-      }
-    }
-  }
-}
+const defaultAdapter = new NativeAdapter()
 
-const Calendar = React.forwardRef<
-  HTMLDivElement,
-  React.ComponentProps<typeof DayPicker> & {
-    buttonVariant?: React.ComponentProps<typeof Button>['variant']
-  }
->(
+const Calendar = React.forwardRef<HTMLDivElement, CalendarProps>(
   (
     {
       className,
-      classNames,
-      showOutsideDays = true,
-      captionLayout = 'label',
+      adapter = defaultAdapter,
       buttonVariant = 'ghost',
-      formatters,
-      components,
+      mode = 'single',
+      selected,
+      onSelect,
+      disabled,
+      defaultMonth,
+      month: controlledMonth,
+      onMonthChange,
+      showOutsideDays = true,
+      fixedWeeks = false,
+      numberOfMonths = 1,
+      locale,
       dir,
-      ...props
+      fromDate,
+      toDate,
+      onDismiss,
+      showDropdowns = true,
+      yearRange,
+      renderDay,
+      renderHeader,
+      renderWeekday,
+      renderFooter,
     },
     ref,
   ) => {
-    const direction = useDirection(dir as Direction)
-    const defaultClassNames = getDefaultClassNames()
-    const localeTag = React.useMemo(() => {
-      const code = props.locale?.code
-      if (!code) return undefined
-      return code.startsWith('ar') ? `${code}-u-nu-arab` : code
-    }, [props.locale])
+    const direction = useDirection(dir)
+    const currentYear = new Date().getFullYear()
+    const resolvedYearRange = yearRange ?? { from: currentYear - 100, to: currentYear + 10 }
+    // Build full locale tag with numbering system for Arabic
+    const formatLocale = locale?.startsWith('ar') ? `${locale}-u-nu-arab` : locale
 
-    const monthFormatter = React.useMemo(() => {
-      return new Intl.DateTimeFormat(localeTag, { month: 'short' })
-    }, [localeTag])
+    const calendar = useCalendar({
+      adapter,
+      mode,
+      locale: locale ? { locale, weekStartDay: 0, direction } : { weekStartDay: 0, direction },
+      month: controlledMonth,
+      defaultMonth,
+      selected,
+      onSelect,
+      onMonthChange,
+      showOutsideDays,
+      fixedWeeks,
+      numberOfMonths,
+      disabled,
+      fromDate,
+      toDate,
+      onDismiss,
+    })
 
-    const captionFormatter = React.useMemo(() => {
-      return new Intl.DateTimeFormat(localeTag, { month: 'long', year: 'numeric' })
-    }, [localeTag])
+    const { state, getDayProps, getGridProps, getNavProps, getHeaderProps, announcer } = calendar
 
-    const numberFormatter = React.useMemo(() => {
-      return new Intl.NumberFormat(localeTag)
-    }, [localeTag])
+    // Only show focus ring during keyboard navigation, not on mouse clicks
+    const [keyboardActive, setKeyboardActive] = React.useState(false)
 
-    const formatLocalizedNumber = React.useCallback(
-      (value: number) => {
-        return numberFormatter.format(value)
-      },
-      [numberFormatter],
-    )
+    const prevNavProps = getNavProps('prev')
+    const nextNavProps = getNavProps('next')
 
     return (
-      <DayPicker
+      // biome-ignore lint/a11y/noStaticElementInteractions: keyboard/pointer tracking for focus ring management
+      <div
+        ref={ref}
+        data-slot="calendar"
         dir={direction}
-        captionLayout={captionLayout}
+        onKeyDown={() => {
+          if (!keyboardActive) setKeyboardActive(true)
+        }}
+        onPointerDown={() => {
+          if (keyboardActive) setKeyboardActive(false)
+        }}
         className={cn(
-          'group/calendar bg-background in-data-[slot=card-content]:bg-transparent in-data-[slot=popover-content]:bg-transparent p-3 [--cell-size:--spacing(8)]',
-          String.raw`rtl:**:[.rdp-button\_next>svg]:rotate-180`,
-          String.raw`rtl:**:[.rdp-button\_previous>svg]:rotate-180`,
+          'group/calendar w-fit bg-background p-3 [--gentleduck-calendar-cell:--spacing(8)]',
+          'rounded-md in-data-[slot=card-content]:bg-transparent in-data-[slot=popover-content]:bg-transparent',
           className,
-        )}
-        classNames={{
-          button_next: cn(
-            buttonVariants({ variant: buttonVariant }),
-            'size-(--cell-size) select-none p-0 aria-disabled:opacity-50',
-            defaultClassNames.button_next,
-          ),
-          button_previous: cn(
-            buttonVariants({ variant: buttonVariant }),
-            'size-(--cell-size) select-none p-0 aria-disabled:opacity-50',
-            defaultClassNames.button_previous,
-          ),
-          caption_label: cn(
-            'select-none font-medium',
-            captionLayout === 'label'
-              ? 'text-sm'
-              : 'flex h-8 items-center gap-1 rounded-md ps-2 pe-1 text-sm [&>svg]:size-3.5 [&>svg]:text-muted-foreground',
-            defaultClassNames.caption_label,
-          ),
-          day: cn(
-            'group/day relative aspect-square h-full w-full select-none p-0 text-center [&:first-child[data-selected=true]_button]:rounded-s-md [&:last-child[data-selected=true]_button]:rounded-e-md',
-            defaultClassNames.day,
-          ),
-          disabled: cn('text-muted-foreground opacity-50', defaultClassNames.disabled),
-          dropdown: cn('absolute inset-0 bg-popover opacity-0', defaultClassNames.dropdown),
-          dropdown_root: cn(
-            'relative rounded-md border border-input shadow-xs has-focus:border-ring has-focus:ring-[3px] has-focus:ring-ring/50',
-            defaultClassNames.dropdown_root,
-          ),
-          dropdowns: cn(
-            'flex h-(--cell-size) w-full items-center justify-center gap-1.5 font-medium text-sm',
-            defaultClassNames.dropdowns,
-          ),
-          hidden: cn('invisible', defaultClassNames.hidden),
-          month: cn('flex w-full flex-col gap-4', defaultClassNames.month),
-          month_caption: cn(
-            'flex h-(--cell-size) w-full items-center justify-center px-(--cell-size)',
-            defaultClassNames.month_caption,
-          ),
-          months: cn('relative flex flex-col gap-4 md:flex-row', defaultClassNames.months),
-          nav: cn('absolute inset-x-0 top-0 flex w-full items-center justify-between gap-1', defaultClassNames.nav),
-          outside: cn('text-muted-foreground aria-selected:text-muted-foreground', defaultClassNames.outside),
-          range_end: cn('rounded-e-md bg-accent', defaultClassNames.range_end),
-          range_middle: cn('rounded-none', defaultClassNames.range_middle),
-          range_start: cn('rounded-s-md bg-accent', defaultClassNames.range_start),
-          root: cn('w-fit', defaultClassNames.root),
-          table: 'w-full border-collapse',
-          today: cn(
-            'rounded-md bg-accent text-accent-foreground data-[selected=true]:rounded-none',
-            defaultClassNames.today,
-          ),
-          week: cn('mt-2 flex w-full', defaultClassNames.week),
-          week_number: cn('select-none text-[0.8rem] text-muted-foreground', defaultClassNames.week_number),
-          week_number_header: cn('w-(--cell-size) select-none', defaultClassNames.week_number_header),
-          weekday: cn(
-            'flex-1 select-none rounded-md font-normal text-[0.8rem] text-muted-foreground',
-            defaultClassNames.weekday,
-          ),
-          weekdays: cn('flex', defaultClassNames.weekdays),
-          ...classNames,
-        }}
-        components={{
-          Chevron: ({ className, orientation, ...props }) => {
-            if (orientation === 'left') {
-              return <ChevronLeftIcon className={cn('size-4', className)} {...props} />
-            }
+        )}>
+        <div className="relative flex flex-col gap-4">
+          {/* Nav header  -  spans full width above all months */}
+          {renderHeader ? (
+            renderHeader({
+              month: state.month,
+              title: adapter.format(state.month, { month: 'long', year: 'numeric' }, formatLocale),
+              direction,
+              goToPrevMonth: prevNavProps.onClick,
+              goToNextMonth: nextNavProps.onClick,
+              isPrevDisabled: prevNavProps.disabled,
+              isNextDisabled: nextNavProps.disabled,
+            })
+          ) : numberOfMonths <= 1 ? (
+            <CalendarHeader
+              adapter={adapter}
+              month={state.month}
+              title={adapter.format(state.month, { month: 'long', year: 'numeric' }, formatLocale)}
+              direction={direction}
+              locale={locale}
+              buttonVariant={buttonVariant}
+              showDropdowns={showDropdowns}
+              yearRange={resolvedYearRange}
+              getNavProps={getNavProps}
+              getHeaderProps={getHeaderProps}
+              onMonthSelect={calendar.actions.setMonth}
+            />
+          ) : (
+            <div className="relative flex w-full items-center">
+              <button
+                type="button"
+                {...prevNavProps}
+                className={cn(
+                  buttonVariants({ variant: buttonVariant as 'ghost' }),
+                  'absolute start-0 z-10 size-(--gentleduck-calendar-cell) select-none p-0 aria-disabled:opacity-50',
+                )}>
+                <ChevronLeftIcon className={cn('size-4', direction === 'rtl' && 'rotate-180')} />
+              </button>
+              {state.months.map((m) => (
+                <span key={m.month.getTime()} className="flex-1 select-none text-center font-medium text-sm">
+                  {adapter.format(m.month, { month: 'long', year: 'numeric' }, formatLocale)}
+                </span>
+              ))}
+              <button
+                type="button"
+                {...nextNavProps}
+                className={cn(
+                  buttonVariants({ variant: buttonVariant as 'ghost' }),
+                  'absolute end-0 z-10 size-(--gentleduck-calendar-cell) select-none p-0 aria-disabled:opacity-50',
+                )}>
+                <ChevronRightIcon className={cn('size-4', direction === 'rtl' && 'rotate-180')} />
+              </button>
+            </div>
+          )}
 
-            if (orientation === 'right') {
-              return <ChevronRightIcon className={cn('size-4', className)} {...props} />
-            }
-
-            return <ChevronDownIcon className={cn('size-4', className)} {...props} />
-          },
-          DayButton: CalendarDayButton,
-          Root: ({ className, rootRef, ...props }) => {
-            return <div className={cn(className)} data-slot="calendar" ref={mergeRefs(ref, rootRef)} {...props} />
-          },
-          WeekNumber: ({ children, ...props }) => {
-            return (
-              <td {...props}>
-                <div className="flex size-(--cell-size) items-center justify-center text-center">{children}</div>
-              </td>
-            )
-          },
-          ...components,
-        }}
-        formatters={{
-          formatCaption: (date) => captionFormatter.format(date),
-          formatDay: (date) => formatLocalizedNumber(date.getDate()),
-          formatMonthDropdown: (date) => monthFormatter.format(date),
-          formatWeekNumber: (weekNumber) => formatLocalizedNumber(weekNumber),
-          formatYearDropdown: (date) => String(date.getFullYear()),
-          ...formatters,
-        }}
-        showOutsideDays={showOutsideDays}
-        {...props}
-      />
+          <div className="flex flex-col gap-4 md:flex-row">
+            {state.months.map((monthGrid) => {
+              const gridProps = getGridProps()
+              return (
+                <div key={monthGrid.month.getTime()} className="flex w-full flex-col gap-4">
+                  <div {...gridProps}>
+                    {/* biome-ignore lint/a11y/useSemanticElements: role="row" on div per WAI-ARIA grid pattern */}
+                    {/* biome-ignore lint/a11y/useFocusableInteractive: weekday header row is not interactive */}
+                    <div role="row" className="flex">
+                      {state.weekdays.map((day, index) => (
+                        // biome-ignore lint/a11y/useSemanticElements: columnheader on div per WAI-ARIA grid pattern
+                        // biome-ignore lint/a11y/useFocusableInteractive: weekday headers are not interactive
+                        <div
+                          key={day}
+                          role="columnheader"
+                          className="flex-1 select-none rounded-md text-center font-normal text-[0.8rem] text-muted-foreground">
+                          {renderWeekday
+                            ? renderWeekday(day, index)
+                            : locale?.startsWith('ar')
+                              ? day.replace(/^ال/, '')
+                              : locale?.startsWith('fa')
+                                ? day.slice(0, 2)
+                                : locale?.startsWith('he')
+                                  ? day.replace(/^יום\s*/, '')
+                                  : day}
+                        </div>
+                      ))}
+                    </div>
+                    {monthGrid.weeks.map((week) => (
+                      // biome-ignore lint/a11y/useSemanticElements: role="row" on div per WAI-ARIA grid pattern
+                      // biome-ignore lint/a11y/useFocusableInteractive: grid rows are not interactive
+                      <div key={week.weekNumber} role="row" className="mt-2 flex w-full">
+                        {week.days.map((day, dayIdx) => {
+                          const {
+                            onMouseEnter: _,
+                            role: _role,
+                            'aria-selected': _ariaSel,
+                            ...dayProps
+                          } = getDayProps(day)
+                          const isSelectedSingle =
+                            day.isSelected && !day.isRangeStart && !day.isRangeEnd && !day.isRangeMiddle
+                          const isFocused = keyboardActive && day.date.getTime() === state.focusedDate.getTime()
+                          return (
+                            <CalendarDayCell
+                              key={day.date.getTime()}
+                              day={day}
+                              dayProps={dayProps}
+                              isFocused={isFocused}
+                              isSelectedSingle={isSelectedSingle}
+                              isFirstInRow={dayIdx === 0}
+                              isLastInRow={dayIdx === 6}
+                              locale={locale}
+                              onFocusDate={(date) => {
+                                setKeyboardActive(false)
+                                calendar.actions.focusDate(date)
+                              }}
+                              renderDay={renderDay}
+                            />
+                          )
+                        })}
+                      </div>
+                    ))}
+                  </div>
+                </div>
+              )
+            })}
+          </div>
+          {renderFooter?.(state.months)}
+        </div>
+        <announcer.AnnouncerPortal />
+      </div>
     )
   },
 )
 Calendar.displayName = 'Calendar'
 
-function CalendarDayButton({ className, day, modifiers, ...props }: React.ComponentProps<typeof DayButton>) {
-  const defaultClassNames = getDefaultClassNames()
-
-  const ref = React.useRef<HTMLButtonElement>(null)
-  React.useEffect(() => {
-    if (modifiers.focused) ref.current?.focus()
-  }, [modifiers.focused])
-
-  return (
-    <Button
-      className={cn(
-        'flex aspect-square size-auto w-full min-w-(--cell-size) flex-col gap-1 font-normal leading-none data-[range-end=true]:rounded-md data-[range-middle=true]:rounded-none data-[range-start=true]:rounded-md data-[range-start=true]:rounded-s-md data-[range-end=true]:rounded-e-md data-[range-end=true]:bg-primary data-[range-middle=true]:bg-accent data-[range-start=true]:bg-primary data-[selected-single=true]:bg-primary data-[range-end=true]:text-primary-foreground data-[range-middle=true]:text-accent-foreground data-[range-start=true]:text-primary-foreground data-[selected-single=true]:text-primary-foreground group-data-[focused=true]/day:relative group-data-[focused=true]/day:z-10 group-data-[focused=true]/day:border-ring group-data-[focused=true]/day:ring-[3px] group-data-[focused=true]/day:ring-ring/50 [&>span]:text-xs [&>span]:opacity-70',
-        defaultClassNames.day,
-        className,
-      )}
-      data-day={day.date.toLocaleDateString()}
-      data-range-end={modifiers.range_end}
-      data-range-middle={modifiers.range_middle}
-      data-range-start={modifiers.range_start}
-      data-selected-single={
-        modifiers.selected && !modifiers.range_start && !modifiers.range_end && !modifiers.range_middle
-      }
-      ref={ref}
-      size="icon"
-      variant="ghost"
-      {...props}
-    />
-  )
-}
-CalendarDayButton.displayName = 'CalendarDayButton'
-
-export { Calendar, CalendarDayButton }
+export { Calendar }

package/src/calendar/calendar.types.ts

@@ -0,0 +1,135 @@
+import type { CalendarDay, CalendarMonth, DateAdapter, SelectionMode } from '@gentleduck/calendar'
+import type { Direction } from '@gentleduck/primitives/direction'
+import type { Button } from '../button'
+
+export interface CalendarHeaderContext {
+  /** The current displayed month Date. */
+  month: Date
+  /** Formatted title string (e.g. "March 2026"). */
+  title: string
+  /** Resolved text direction. */
+  direction: 'ltr' | 'rtl'
+  /** Navigate to the previous month. */
+  goToPrevMonth: () => void
+  /** Navigate to the next month. */
+  goToNextMonth: () => void
+  /** Whether previous navigation is disabled. */
+  isPrevDisabled: boolean
+  /** Whether next navigation is disabled. */
+  isNextDisabled: boolean
+}
+
+export interface CalendarProps {
+  className?: string
+  /**
+   * Date adapter for alternative calendar systems (Islamic, Persian, etc.).
+   * Default uses `NativeAdapter` (Gregorian).
+   */
+  adapter?: DateAdapter<Date>
+  /** Variant style for navigation buttons. Default `'ghost'`. */
+  buttonVariant?: React.ComponentProps<typeof Button>['variant']
+  /** Selection mode. Default `'single'`. */
+  mode?: SelectionMode
+  /** Controlled selection value. Shape depends on `mode`. */
+  // biome-ignore lint/suspicious/noExplicitAny: CalendarValue union is narrowed by mode at runtime
+  selected?: any
+  /** Called when the selection changes. Value shape depends on `mode`. */
+  // biome-ignore lint/suspicious/noExplicitAny: CalendarValue union is narrowed by mode at runtime
+  onSelect?: (value: any) => void
+  /** Dates that cannot be selected. */
+  disabled?: Date[] | ((date: Date) => boolean)
+  /** Default month to display (uncontrolled). */
+  defaultMonth?: Date
+  /** Controlled month. */
+  month?: Date
+  /** Called when the displayed month changes. */
+  onMonthChange?: (month: Date) => void
+  /** Show days from adjacent months. Default `true`. */
+  showOutsideDays?: boolean
+  /** Always show 6 weeks. Default `false`. */
+  fixedWeeks?: boolean
+  /** How many months to show side by side. Default `1`. */
+  numberOfMonths?: number
+  /** BCP 47 locale tag (e.g. `'ar-SA'`). */
+  locale?: string
+  /** Text direction. */
+  dir?: Direction
+  /** Earliest selectable date. */
+  fromDate?: Date
+  /** Latest selectable date. */
+  toDate?: Date
+  /** Called when the user presses Escape. */
+  onDismiss?: () => void
+  /**
+   * Show month and year dropdowns in the header.
+   * Default `true`. Set to `false` for a minimal caption.
+   */
+  showDropdowns?: boolean
+  /**
+   * Range of years to show in the year dropdown.
+   * Default `{ from: currentYear - 100, to: currentYear + 10 }`.
+   */
+  yearRange?: { from: number; to: number }
+  /**
+   * Custom render function for day cells.
+   * Receives the day object and the default rendered children (the date number).
+   * Return a ReactNode to replace or wrap the default content.
+   *
+   * @example
+   * ```tsx
+   * renderDay={(day, children) => (
+   *   <>
+   *     {children}
+   *     {hasEvents(day.date) && <span className="size-1 rounded-full bg-primary" />}
+   *   </>
+   * )}
+   * ```
+   */
+  renderDay?: (day: CalendarDay<Date>, children: React.ReactNode) => React.ReactNode
+  /**
+   * Custom render function for the navigation header.
+   * Receives header context with month info and navigation controls.
+   * Return a ReactNode to replace the default header entirely.
+   *
+   * @example
+   * ```tsx
+   * renderHeader={({ title, goToPrevMonth, goToNextMonth }) => (
+   *   <div className="flex items-center justify-between">
+   *     <button onClick={goToPrevMonth}><-</button>
+   *     <span>{title}</span>
+   *     <button onClick={goToNextMonth}>-></button>
+   *   </div>
+   * )}
+   * ```
+   */
+  renderHeader?: (context: CalendarHeaderContext) => React.ReactNode
+  /**
+   * Custom render function for weekday column headers.
+   * Receives the weekday abbreviation (e.g. "Sun") and its index (0-6).
+   * Return a ReactNode to replace the default weekday label.
+   *
+   * @example
+   * ```tsx
+   * renderWeekday={(day, index) => (
+   *   <span className={index === 0 || index === 6 ? 'text-red-500' : ''}>
+   *     {day}
+   *   </span>
+   * )}
+   * ```
+   */
+  renderWeekday?: (day: string, index: number) => React.ReactNode
+  /**
+   * Render content below the calendar grid.
+   * Receives the current months array for context.
+   *
+   * @example
+   * ```tsx
+   * renderFooter={(months) => (
+   *   <div className="mt-2 text-xs text-muted-foreground">
+   *     Selected: {selected?.toLocaleDateString()}
+   *   </div>
+   * )}
+   * ```
+   */
+  renderFooter?: (months: CalendarMonth<Date>[]) => React.ReactNode
+}

package/src/calendar/calendar.utils.ts

@@ -0,0 +1,23 @@
+const MAX_CACHE_SIZE = 20
+
+/** Cache Intl.NumberFormat instances to avoid recreating formatters on every render. */
+const NUMBER_FORMAT_CACHE = new Map<string, Intl.NumberFormat>()
+
+export function getCachedNumberFormat(locale: string, options?: Intl.NumberFormatOptions): Intl.NumberFormat {
+  const key = options ? `${locale}|${JSON.stringify(options)}` : locale
+  let fmt = NUMBER_FORMAT_CACHE.get(key)
+  if (fmt) {
+    // LRU: move to end
+    NUMBER_FORMAT_CACHE.delete(key)
+    NUMBER_FORMAT_CACHE.set(key, fmt)
+    return fmt
+  }
+  // Evict oldest if at capacity
+  if (NUMBER_FORMAT_CACHE.size >= MAX_CACHE_SIZE) {
+    const oldest = NUMBER_FORMAT_CACHE.keys().next().value
+    if (oldest !== undefined) NUMBER_FORMAT_CACHE.delete(oldest)
+  }
+  fmt = new Intl.NumberFormat(locale, options)
+  NUMBER_FORMAT_CACHE.set(key, fmt)
+  return fmt
+}

package/src/calendar/index.ts

@@ -1 +1,2 @@
-export * from './calendar'
+export { Calendar } from './calendar'
+export type { CalendarHeaderContext, CalendarProps } from './calendar.types'

package/src/sonner/sonner.chunks.tsx

@@ -31,7 +31,6 @@ const SonnerUpload = ({
         )}
       />
       <div className="flex w-full flex-col gap-2">
-        {/* biome-ignore lint/a11y/useSemanticElements: status role on div is intentional for live region announcements */}
         <div className="flex w-full justify-between" role="status">
           <p className="text-foreground text-sm">
             {progress >= 100