@sabrenski/spire-ui 0.0.1

package/src/utils/date.ts

@@ -0,0 +1,380 @@
+/**
+ * Calendar grid item representing a single day cell.
+ */
+export interface CalendarDay {
+  /** The date object for this cell */
+  date: Date
+  /** Day of the month (1-31) */
+  day: number
+  /** Whether this day belongs to the currently viewed month */
+  currentMonth: boolean
+}
+
+/**
+ * Generate a 42-item grid (6 rows × 7 columns) for a calendar month view.
+ * The grid always starts on Sunday and includes days from previous/next months
+ * to fill the complete 6-row layout.
+ *
+ * @param year - Full year (e.g., 2024)
+ * @param month - Month (0-11, where 0 = January)
+ * @returns Array of 42 CalendarDay objects
+ *
+ * Time complexity: O(1) - Fixed 42 iterations
+ * Space complexity: O(1) - Fixed 42-element array
+ */
+export function generateCalendarGrid(year: number, month: number): CalendarDay[] {
+  const grid: CalendarDay[] = []
+  const firstDayOfMonth = new Date(year, month, 1)
+  const startDayOfWeek = firstDayOfMonth.getDay()
+  const startDate = new Date(year, month, 1 - startDayOfWeek)
+
+  for (let i = 0; i < 42; i++) {
+    const date = new Date(startDate)
+    date.setDate(startDate.getDate() + i)
+
+    grid.push({
+      date,
+      day: date.getDate(),
+      currentMonth: date.getMonth() === month
+    })
+  }
+
+  return grid
+}
+
+/**
+ * Get the number of days in a given month, correctly handling leap years.
+ *
+ * @param year - Full year (e.g., 2024)
+ * @param month - Month (0-11, where 0 = January)
+ * @returns Number of days in the month (28-31)
+ *
+ * Time complexity: O(1)
+ * Space complexity: O(1)
+ */
+export function getDaysInMonth(year: number, month: number): number {
+  return new Date(year, month + 1, 0).getDate()
+}
+
+/**
+ * Format a Date object to ISO 8601 date string (YYYY-MM-DD).
+ *
+ * @param date - Date object to format
+ * @returns ISO date string in YYYY-MM-DD format
+ *
+ * Time complexity: O(1)
+ * Space complexity: O(1)
+ */
+export function formatDate(date: Date): string {
+  const year = date.getFullYear()
+  const month = String(date.getMonth() + 1).padStart(2, '0')
+  const day = String(date.getDate()).padStart(2, '0')
+  return `${year}-${month}-${day}`
+}
+
+/**
+ * Parse an ISO 8601 date string (YYYY-MM-DD) to a Date object.
+ * Returns null for invalid input.
+ *
+ * @param dateString - ISO date string in YYYY-MM-DD format
+ * @returns Date object or null if invalid
+ *
+ * Time complexity: O(1)
+ * Space complexity: O(1)
+ */
+export function parseDate(dateString: string): Date | null {
+  if (!dateString || !/^\d{4}-\d{2}-\d{2}$/.test(dateString)) {
+    return null
+  }
+
+  const [year, month, day] = dateString.split('-').map(Number)
+  const date = new Date(year, month - 1, day)
+
+  if (
+    date.getFullYear() !== year ||
+    date.getMonth() !== month - 1 ||
+    date.getDate() !== day
+  ) {
+    return null
+  }
+
+  return date
+}
+
+/**
+ * Check if two dates represent the same calendar day (ignoring time).
+ *
+ * @param d1 - First date
+ * @param d2 - Second date
+ * @returns True if both dates are the same day
+ *
+ * Time complexity: O(1)
+ * Space complexity: O(1)
+ */
+export function isSameDate(d1: Date | null, d2: Date | null): boolean {
+  if (!d1 || !d2) return false
+
+  return (
+    d1.getFullYear() === d2.getFullYear() &&
+    d1.getMonth() === d2.getMonth() &&
+    d1.getDate() === d2.getDate()
+  )
+}
+
+/**
+ * Check if a date is before another date (day-level comparison).
+ *
+ * @param date - Date to check
+ * @param reference - Reference date
+ * @returns True if date is before reference
+ *
+ * Time complexity: O(1)
+ * Space complexity: O(1)
+ */
+export function isDateBefore(date: Date, reference: Date): boolean {
+  const d = new Date(date.getFullYear(), date.getMonth(), date.getDate())
+  const r = new Date(reference.getFullYear(), reference.getMonth(), reference.getDate())
+  return d.getTime() < r.getTime()
+}
+
+/**
+ * Check if a date is after another date (day-level comparison).
+ *
+ * @param date - Date to check
+ * @param reference - Reference date
+ * @returns True if date is after reference
+ *
+ * Time complexity: O(1)
+ * Space complexity: O(1)
+ */
+export function isDateAfter(date: Date, reference: Date): boolean {
+  const d = new Date(date.getFullYear(), date.getMonth(), date.getDate())
+  const r = new Date(reference.getFullYear(), reference.getMonth(), reference.getDate())
+  return d.getTime() > r.getTime()
+}
+
+/**
+ * Get localized month name.
+ *
+ * @param month - Month (0-11)
+ * @param locale - Locale string (defaults to browser locale)
+ * @returns Localized month name
+ *
+ * Time complexity: O(1)
+ * Space complexity: O(1)
+ */
+export function getMonthName(month: number, locale?: string): string {
+  const date = new Date(2000, month, 1)
+  return date.toLocaleDateString(locale, { month: 'long' })
+}
+
+/**
+ * Get localized weekday abbreviations starting from Sunday.
+ *
+ * @param locale - Locale string (defaults to browser locale)
+ * @returns Array of 7 weekday abbreviations
+ *
+ * Time complexity: O(1) - Fixed 7 iterations
+ * Space complexity: O(1) - Fixed 7-element array
+ */
+export function getWeekdayNames(locale?: string): string[] {
+  const weekdays: string[] = []
+  const baseDate = new Date(2024, 0, 7)
+
+  for (let i = 0; i < 7; i++) {
+    const date = new Date(baseDate)
+    date.setDate(baseDate.getDate() + i)
+    weekdays.push(date.toLocaleDateString(locale, { weekday: 'short' }))
+  }
+
+  return weekdays
+}
+
+/**
+ * Check if a date falls within an optional min/max range.
+ *
+ * @param date - Date to check
+ * @param min - Minimum allowed date (inclusive)
+ * @param max - Maximum allowed date (inclusive)
+ * @returns True if date is within range or no constraints exist
+ *
+ * Time complexity: O(1)
+ * Space complexity: O(1)
+ */
+export function isDateInRange(date: Date, min?: Date | null, max?: Date | null): boolean {
+  if (min && isDateBefore(date, min)) return false
+  if (max && isDateAfter(date, max)) return false
+  return true
+}
+
+/**
+ * Check if a date falls strictly between two dates (exclusive).
+ *
+ * @param date - Date to check
+ * @param start - Range start date
+ * @param end - Range end date
+ * @returns True if date is between start and end (exclusive)
+ *
+ * Time complexity: O(1)
+ * Space complexity: O(1)
+ */
+export function isDateBetween(date: Date, start: Date | null, end: Date | null): boolean {
+  if (!start || !end) return false
+  const d = new Date(date.getFullYear(), date.getMonth(), date.getDate()).getTime()
+  const s = new Date(start.getFullYear(), start.getMonth(), start.getDate()).getTime()
+  const e = new Date(end.getFullYear(), end.getMonth(), end.getDate()).getTime()
+  return d > Math.min(s, e) && d < Math.max(s, e)
+}
+
+/**
+ * Range selection state for two-click selection.
+ */
+export type RangeState = 'idle' | 'selecting'
+
+/**
+ * Computed range class for a date cell in range mode.
+ */
+export type RangeClass = 'start' | 'end' | 'in-range' | null
+
+/**
+ * Determine the CSS class for a date in range selection mode.
+ * Handles the "flip" when user selects end date before start date.
+ *
+ * @param date - Date to classify
+ * @param start - Selected start date (or first click)
+ * @param end - Selected end date (or null if selecting)
+ * @param hover - Currently hovered date (for preview during selection)
+ * @returns Range class for styling
+ *
+ * Time complexity: O(1)
+ * Space complexity: O(1)
+ */
+export function getRangeClass(
+  date: Date,
+  start: Date | null,
+  end: Date | null,
+  hover: Date | null
+): RangeClass {
+  if (!start) return null
+
+  const effectiveEnd = end || hover
+  if (!effectiveEnd) {
+    return isSameDate(date, start) ? 'start' : null
+  }
+
+  const startTime = new Date(start.getFullYear(), start.getMonth(), start.getDate()).getTime()
+  const endTime = new Date(effectiveEnd.getFullYear(), effectiveEnd.getMonth(), effectiveEnd.getDate()).getTime()
+  const dateTime = new Date(date.getFullYear(), date.getMonth(), date.getDate()).getTime()
+
+  const rangeStart = Math.min(startTime, endTime)
+  const rangeEnd = Math.max(startTime, endTime)
+
+  if (dateTime === rangeStart) return 'start'
+  if (dateTime === rangeEnd) return 'end'
+  if (dateTime > rangeStart && dateTime < rangeEnd) return 'in-range'
+
+  return null
+}
+
+/**
+ * Normalize a range to ensure start <= end.
+ *
+ * @param start - First selected date
+ * @param end - Second selected date
+ * @returns Tuple [start, end] in chronological order
+ *
+ * Time complexity: O(1)
+ * Space complexity: O(1)
+ */
+export function normalizeRange(start: Date, end: Date): [Date, Date] {
+  const s = new Date(start.getFullYear(), start.getMonth(), start.getDate()).getTime()
+  const e = new Date(end.getFullYear(), end.getMonth(), end.getDate()).getTime()
+  return s <= e ? [start, end] : [end, start]
+}
+
+/**
+ * Get all month names for a locale (short format for month grid).
+ *
+ * @param locale - Locale string (defaults to browser locale)
+ * @returns Array of 12 short month names
+ *
+ * Time complexity: O(1) - Fixed 12 iterations
+ * Space complexity: O(1) - Fixed 12-element array
+ */
+export function getMonthNamesShort(locale?: string): string[] {
+  const months: string[] = []
+  for (let i = 0; i < 12; i++) {
+    const date = new Date(2000, i, 1)
+    months.push(date.toLocaleDateString(locale, { month: 'short' }))
+  }
+  return months
+}
+
+/**
+ * Generate a 20-year window centered around a given year for year grid view.
+ *
+ * @param centerYear - Year to center the window around
+ * @returns Array of 20 years [start, start+1, ..., start+19]
+ *
+ * Time complexity: O(1) - Fixed 20 iterations
+ * Space complexity: O(1) - Fixed 20-element array
+ */
+export function generateYearGrid(centerYear: number): number[] {
+  const startYear = Math.floor(centerYear / 20) * 20
+  return Array.from({ length: 20 }, (_, i) => startYear + i)
+}
+
+/**
+ * Get the start of a date range preset.
+ *
+ * @param preset - Preset name
+ * @returns [start, end] date tuple
+ */
+export function getPresetRange(preset: string): [Date, Date] {
+  const today = new Date()
+  const todayStart = new Date(today.getFullYear(), today.getMonth(), today.getDate())
+
+  switch (preset) {
+    case 'today':
+      return [todayStart, todayStart]
+
+    case 'yesterday': {
+      const yesterday = new Date(todayStart)
+      yesterday.setDate(yesterday.getDate() - 1)
+      return [yesterday, yesterday]
+    }
+
+    case 'last7days': {
+      const start = new Date(todayStart)
+      start.setDate(start.getDate() - 6)
+      return [start, todayStart]
+    }
+
+    case 'last30days': {
+      const start = new Date(todayStart)
+      start.setDate(start.getDate() - 29)
+      return [start, todayStart]
+    }
+
+    case 'thisMonth': {
+      const start = new Date(today.getFullYear(), today.getMonth(), 1)
+      const end = new Date(today.getFullYear(), today.getMonth() + 1, 0)
+      return [start, end]
+    }
+
+    case 'lastMonth': {
+      const start = new Date(today.getFullYear(), today.getMonth() - 1, 1)
+      const end = new Date(today.getFullYear(), today.getMonth(), 0)
+      return [start, end]
+    }
+
+    case 'thisYear': {
+      const start = new Date(today.getFullYear(), 0, 1)
+      const end = new Date(today.getFullYear(), 11, 31)
+      return [start, end]
+    }
+
+    default:
+      return [todayStart, todayStart]
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,23 @@
+export { getInitials } from './string'
+export { getNestedValue } from './object'
+export {
+  generateCalendarGrid,
+  getDaysInMonth,
+  formatDate,
+  parseDate,
+  isSameDate,
+  isDateBefore,
+  isDateAfter,
+  getMonthName,
+  getMonthNamesShort,
+  getWeekdayNames,
+  isDateInRange,
+  isDateBetween,
+  getRangeClass,
+  normalizeRange,
+  generateYearGrid,
+  getPresetRange,
+  type CalendarDay,
+  type RangeState,
+  type RangeClass
+} from './date'

package/src/utils/object.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect } from 'vitest'
+import { getNestedValue } from './object'
+
+describe('getNestedValue', () => {
+  it('returns undefined for empty path', () => {
+    expect(getNestedValue({ name: 'John' }, '')).toBeUndefined()
+  })
+
+  it('returns top-level property', () => {
+    expect(getNestedValue({ name: 'John' }, 'name')).toBe('John')
+  })
+
+  it('returns nested property', () => {
+    const obj = { user: { email: 'a@b.com' } }
+    expect(getNestedValue(obj, 'user.email')).toBe('a@b.com')
+  })
+
+  it('returns deeply nested property', () => {
+    const obj = { a: { b: { c: { d: 'deep' } } } }
+    expect(getNestedValue(obj, 'a.b.c.d')).toBe('deep')
+  })
+
+  it('returns undefined for missing property', () => {
+    expect(getNestedValue({}, 'missing')).toBeUndefined()
+  })
+
+  it('returns undefined for missing nested property', () => {
+    expect(getNestedValue({ user: {} }, 'user.email')).toBeUndefined()
+  })
+
+  it('returns undefined when intermediate path is missing', () => {
+    expect(getNestedValue({}, 'user.email.domain')).toBeUndefined()
+  })
+
+  it('handles null values in path', () => {
+    const obj = { user: null }
+    expect(getNestedValue(obj as Record<string, unknown>, 'user.email')).toBeUndefined()
+  })
+
+  it('returns arrays', () => {
+    const obj = { items: [1, 2, 3] }
+    expect(getNestedValue(obj, 'items')).toEqual([1, 2, 3])
+  })
+
+  it('returns objects', () => {
+    const obj = { user: { name: 'John', age: 30 } }
+    expect(getNestedValue(obj, 'user')).toEqual({ name: 'John', age: 30 })
+  })
+
+  it('returns boolean false', () => {
+    const obj = { active: false }
+    expect(getNestedValue(obj, 'active')).toBe(false)
+  })
+
+  it('returns number zero', () => {
+    const obj = { count: 0 }
+    expect(getNestedValue(obj, 'count')).toBe(0)
+  })
+
+  it('returns empty string', () => {
+    const obj = { name: '' }
+    expect(getNestedValue(obj, 'name')).toBe('')
+  })
+
+  it('blocks prototype chain access via __proto__', () => {
+    const obj = { safe: 'value' }
+    expect(getNestedValue(obj, '__proto__')).toBeUndefined()
+  })
+
+  it('blocks constructor access', () => {
+    const obj = { safe: 'value' }
+    expect(getNestedValue(obj, 'constructor')).toBeUndefined()
+  })
+
+  it('blocks nested prototype traversal', () => {
+    const obj = { nested: { value: 'test' } }
+    expect(getNestedValue(obj, 'nested.__proto__')).toBeUndefined()
+    expect(getNestedValue(obj, 'nested.constructor')).toBeUndefined()
+  })
+})

package/src/utils/object.ts

@@ -0,0 +1,25 @@
+/**
+ * Access a nested property in an object using dot notation.
+ *
+ * @param obj - The object to access
+ * @param path - Dot-notation path (e.g., 'user.email', 'address.city')
+ * @returns The value at the path, or undefined if not found
+ *
+ * @example
+ * getNestedValue({ user: { email: 'a@b.com' } }, 'user.email') // 'a@b.com'
+ * getNestedValue({ name: 'John' }, 'name') // 'John'
+ * getNestedValue({}, 'missing.path') // undefined
+ */
+export function getNestedValue(
+  obj: Record<string, unknown>,
+  path: string
+): unknown {
+  if (!path) return undefined
+
+  return path.split('.').reduce<unknown>((acc, key) => {
+    if (acc && typeof acc === 'object' && Object.hasOwn(acc as object, key)) {
+      return (acc as Record<string, unknown>)[key]
+    }
+    return undefined
+  }, obj)
+}

package/src/utils/string.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest'
+import { getInitials } from './string'
+
+describe('getInitials', () => {
+  describe('basic functionality', () => {
+    it('returns initials for two-word name', () => {
+      expect(getInitials('John Doe')).toBe('JD')
+    })
+
+    it('returns initials for single name (first N chars)', () => {
+      expect(getInitials('Madonna')).toBe('MA')
+    })
+
+    it('returns first and last initials for multi-word names', () => {
+      expect(getInitials('John von Doe')).toBe('JD')
+      expect(getInitials('Mary Jane Watson')).toBe('MW')
+    })
+  })
+
+  describe('edge cases', () => {
+    it('returns empty string for undefined', () => {
+      expect(getInitials(undefined)).toBe('')
+    })
+
+    it('returns empty string for empty string', () => {
+      expect(getInitials('')).toBe('')
+    })
+
+    it('returns empty string for whitespace only', () => {
+      expect(getInitials('   ')).toBe('')
+    })
+
+    it('handles multiple spaces between words', () => {
+      expect(getInitials('John    Doe')).toBe('JD')
+    })
+
+    it('handles leading/trailing whitespace', () => {
+      expect(getInitials('  John Doe  ')).toBe('JD')
+    })
+
+    it('handles single character name', () => {
+      expect(getInitials('X')).toBe('X')
+    })
+  })
+
+  describe('limit parameter', () => {
+    it('respects custom limit for single names', () => {
+      expect(getInitials('Madonna', 1)).toBe('M')
+      expect(getInitials('Madonna', 3)).toBe('MAD')
+    })
+
+    it('limit does not affect multi-word names (always 2 chars)', () => {
+      expect(getInitials('John Doe', 1)).toBe('JD')
+    })
+  })
+
+  describe('case handling', () => {
+    it('returns uppercase regardless of input case', () => {
+      expect(getInitials('john doe')).toBe('JD')
+      expect(getInitials('JOHN DOE')).toBe('JD')
+      expect(getInitials('jOhN dOe')).toBe('JD')
+    })
+  })
+})

package/src/utils/string.ts

@@ -0,0 +1,32 @@
+/**
+ * Extract initials from a name string.
+ *
+ * @param name - Full name (e.g., "John Doe", "Madonna", "John von Doe")
+ * @param limit - Maximum characters to return (default: 2)
+ * @returns Uppercase initials (e.g., "JD", "M", "JD")
+ *
+ * @example
+ * getInitials("John Doe")      // "JD"
+ * getInitials("Madonna")       // "MA"
+ * getInitials("John von Doe")  // "JD" (first + last)
+ * getInitials("")              // ""
+ */
+export function getInitials(name?: string, limit = 2): string {
+  if (!name) return ''
+
+  // Split by spaces, filter empty (handles "John  Doe")
+  const parts = name.trim().split(/\s+/)
+
+  if (parts.length === 0 || parts[0] === '') return ''
+
+  // Single name "Madonna" -> "MA" (first `limit` chars)
+  if (parts.length === 1) {
+    return parts[0].substring(0, limit).toUpperCase()
+  }
+
+  // Multi name "John von Doe" -> "JD" (First and Last)
+  const first = parts[0][0]
+  const last = parts[parts.length - 1][0]
+
+  return (first + last).toUpperCase()
+}