@glatam/calendar-ui 1.0.0

package/src/glatam-calendar.ts

@@ -0,0 +1,197 @@
+import { LitElement, html } from 'lit';
+import { customElement, property, state } from 'lit/decorators.js';
+import { generateMonthDays, generateWeekDays, formatISODate, isTimeBlocked, BlockingRule, TimeSlot } from '@glatam/calendar-core';
+import { variablesStyles } from './styles/variables.css.js';
+import { calendarStyles } from './styles/calendar.css.js';
+import { getTimezoneOffsetDiff, shiftSlot } from './utils/timezone-utils.js';
+
+import './views/month-view.js';
+import './views/week-view.js';
+import './views/day-view.js';
+import './components/calendar-modal.js';
+
+const DEFAULT_SLOTS: TimeSlot[] = [
+  { start: '09:00', end: '10:00' }, { start: '10:00', end: '11:00' },
+  { start: '11:00', end: '12:00' }, { start: '12:00', end: '13:00' },
+  { start: '13:00', end: '14:00' }, { start: '14:00', end: '15:00' },
+  { start: '15:00', end: '16:00' }, { start: '16:00', end: '17:00' },
+  { start: '17:00', end: '18:00' },
+];
+
+@customElement('glatam-calendar')
+export class GlatamCalendar extends LitElement {
+  static styles = [variablesStyles, calendarStyles];
+
+  @property({ type: String }) role = 'provider';
+  @property({ type: String, reflect: true }) size = 'medium';
+  @property({ type: String }) view: 'month' | 'week' | 'day' = 'month';
+  @property({ type: String }) locale = 'es';
+  @property({ type: Number }) startOfWeekDay = 0;
+  @property({ type: Array }) rules: BlockingRule[] = [];
+  @property({ type: Array }) selectedDates: string[] = [];
+  @property({ type: Object }) selectedRange: { dateString: string; start: string; end: string } | null = null;
+  @property({ type: String }) hostTimezone = 'America/Bogota'; @property({ type: String }) activeTimezone = 'local';
+  @property({ type: Array }) slots: TimeSlot[] = DEFAULT_SLOTS;
+  @property({ type: String }) minDate = ''; @property({ type: String }) maxDate = '';
+  @property({ type: Boolean }) showNeighboringMonth = true;
+  @property({ attribute: false }) tileClassName: ((data: { date: Date; dateString: string }) => string) | null = null;
+
+  @state() private activeDate = new Date();
+  @state() private localRules: BlockingRule[] = [];
+  @state() private darkMode = false;
+  @state() private modalOpen = false;
+  @state() private modalDateString = '';
+  @state() private modalStartTime = '';
+  @state() private modalEndTime = '';
+  @state() private modalIsRange = false;
+  @state() private modalExistingRule: BlockingRule | null = null;
+
+  firstUpdated() { this.darkMode = window.matchMedia('(prefers-color-scheme: dark)').matches; this.localRules = [...this.rules]; }
+  willUpdate(changedProps: Map<string, any>) { if (changedProps.has('rules') && this.rules.length > 0 && this.localRules.length === 0) this.localRules = [...this.rules]; }
+  updated(changedProps: Map<string, any>) { if (changedProps.has('darkMode')) this.classList.toggle('dark-mode', this.darkMode); }
+
+  private handlePrev() {
+    const d = new Date(this.activeDate);
+    this.view === 'month' ? d.setMonth(d.getMonth() - 1) : this.view === 'week' ? d.setDate(d.getDate() - 7) : d.setDate(d.getDate() - 1);
+    this.activeDate = d;
+  }
+
+  private handleNext() {
+    const d = new Date(this.activeDate);
+    this.view === 'month' ? d.setMonth(d.getMonth() + 1) : this.view === 'week' ? d.setDate(d.getDate() + 7) : d.setDate(d.getDate() + 1);
+    this.activeDate = d;
+  }
+
+  private getHeaderTitle(): string {
+    const opt: Intl.DateTimeFormatOptions = this.view === 'month' ? { month: 'long', year: 'numeric' } : this.view === 'week' ? { month: 'short', year: 'numeric' } : { day: 'numeric', month: 'long', year: 'numeric' };
+    return new Intl.DateTimeFormat(this.locale, opt).format(this.activeDate);
+  }
+
+  private handleDaySelect(e: CustomEvent<{ dateString: string; isBlocked: boolean }>) {
+    const { dateString, isBlocked } = e.detail;
+    if (this.role === 'buyer' && isBlocked) return;
+    this.activeDate = new Date(dateString + 'T00:00:00');
+    this.view = 'day';
+    this.dispatchEvent(new CustomEvent('date-selected', { detail: { dateString }, bubbles: true, composed: true }));
+  }
+
+  private handleRangeSelect(e: CustomEvent<{ dateString: string; start: string; end: string }>) {
+    const { dateString, start, end } = e.detail, offset = this.activeTimezone === 'local' ? getTimezoneOffsetDiff(this.activeDate, this.hostTimezone, 'local') : 0;
+    const displaySlots = this.getDisplaySlots(offset), startIdx = displaySlots.findIndex(s => s.start === start), endIdx = displaySlots.findIndex(s => s.end === end);
+    const hostStart = this.slots[startIdx]?.start || start, hostEnd = this.slots[endIdx]?.end || end;
+    if (this.role === 'buyer') {
+      this.selectedRange = { dateString, start, end };
+      this.dispatchEvent(new CustomEvent('booking-selected', { detail: { dateString, start, end, hostStart, hostEnd }, bubbles: true, composed: true }));
+      return;
+    }
+    this.openModal(dateString, hostStart, hostEnd, true, null);
+  }
+
+  private handleSlotClick(e: CustomEvent<{ dateString: string; slot: TimeSlot }>) {
+    const { dateString, slot } = e.detail, date = new Date(dateString + 'T00:00:00'), offset = this.activeTimezone === 'local' ? getTimezoneOffsetDiff(this.activeDate, this.hostTimezone, 'local') : 0;
+    const displaySlots = this.getDisplaySlots(offset), idx = displaySlots.findIndex(s => s.start === slot.start), hostSlot = this.slots[idx] || slot;
+    if (this.role === 'buyer') {
+      this.selectedRange = { dateString, start: slot.start, end: slot.end };
+      this.dispatchEvent(new CustomEvent('booking-selected', { detail: { dateString, start: slot.start, end: slot.end, hostStart: hostSlot.start, hostEnd: hostSlot.end }, bubbles: true, composed: true }));
+      return;
+    }
+    const rule = this.localRules.find(r => isTimeBlocked(date, hostSlot, [r]));
+    this.openModal(dateString, hostSlot.start, hostSlot.end, true, rule || null);
+  }
+
+  private handleBlockDayAction() {
+    const dateStr = formatISODate(this.activeDate), rule = this.localRules.find(r => isTimeBlocked(this.activeDate, undefined, [r]));
+    this.openModal(dateStr, '', '', false, rule || null);
+  }
+
+  private openModal(date: string, start: string, end: string, isRange: boolean, rule: BlockingRule | null) {
+    this.modalDateString = date; this.modalStartTime = start; this.modalEndTime = end; this.modalIsRange = isRange; this.modalExistingRule = rule; this.modalOpen = true;
+  }
+
+  private handleSaveRule(e: CustomEvent) {
+    const data = e.detail, ruleId = this.modalExistingRule ? this.modalExistingRule.id : `rule-${Date.now()}`;
+    const newRule: BlockingRule = {
+      id: ruleId, type: data.isRecurring ? 'weekly' : 'date-range',
+      slots: data.blockAllDay ? undefined : [{ start: data.startTime, end: data.endTime }],
+      daysOfWeek: data.isRecurring ? data.selectedDays : undefined,
+      startDate: data.isRecurring ? undefined : data.dateString,
+      endDate: data.isRecurring ? undefined : data.dateString,
+      description: data.title
+    };
+    this.localRules = this.modalExistingRule ? this.localRules.map(r => r.id === ruleId ? newRule : r) : [...this.localRules, newRule];
+    this.modalOpen = false;
+    this.dispatchEvent(new CustomEvent('rules-changed', { detail: { rules: this.localRules }, bubbles: true, composed: true }));
+  }
+
+  private handleDeleteRule(e: CustomEvent<{ id: string }>) {
+    this.localRules = this.localRules.filter(r => r.id !== e.detail.id);
+    this.modalOpen = false;
+    this.dispatchEvent(new CustomEvent('rules-changed', { detail: { rules: this.localRules }, bubbles: true, composed: true }));
+  }
+
+  private getDisplaySlots(offset: number): TimeSlot[] {
+    if (offset === 0) return this.slots;
+    return this.slots.map(s => {
+      const shifted = shiftSlot(s, offset);
+      const suffix = shifted.dayShift > 0 ? ' (+1d)' : shifted.dayShift < 0 ? ' (-1d)' : '';
+      return { start: shifted.start + suffix, end: shifted.end + suffix };
+    });
+  }
+
+  render() {
+    const y = this.activeDate.getFullYear(), m = this.activeDate.getMonth(), isCurrentDayBlocked = isTimeBlocked(this.activeDate, undefined, this.localRules);
+    const offset = this.activeTimezone === 'local' ? getTimezoneOffsetDiff(this.activeDate, this.hostTimezone, 'local') : 0, displaySlots = this.getDisplaySlots(offset);
+    const mapDays = (days: any[]) => days.map(d => ({ ...d, slots: d.slots.map((s: any, idx: number) => ({ ...s, start: displaySlots[idx]?.start || s.start, end: displaySlots[idx]?.end || s.end })) }));
+    const tzCity = this.hostTimezone.split('/').pop()?.replace('_', ' ') || 'Anfitrión';
+
+    return html`
+      <div class="calendar-header">
+        <div class="nav-group">
+          <button class="btn" @click=${() => this.activeDate = new Date()}>Hoy</button>
+          <button class="btn" @click=${this.handlePrev}>&lt;</button>
+          <button class="btn" @click=${this.handleNext}>&gt;</button>
+          <span class="nav-title" style="text-transform: capitalize;">${this.getHeaderTitle()}</span>
+        </div>
+        
+        <div class="view-group">
+          ${this.role === 'provider' ? html`
+            <div class="timezone-badge">
+              🌐 Zona:
+              <select class="timezone-select" @change=${(e: any) => this.activeTimezone = e.target.value}>
+                <option value="local" ?selected=${this.activeTimezone === 'local'}>Mi Hora</option>
+                <option value="host" ?selected=${this.activeTimezone === 'host'}>Hora ${tzCity}</option>
+              </select>
+            </div>
+          ` : ''}
+          ${this.role === 'provider' && this.view === 'day'
+            ? html`<button class="btn btn-primary" @click=${this.handleBlockDayAction} style="margin-right: 8px;">${isCurrentDayBlocked ? 'Liberar Día' : 'Bloquear Día'}</button>`
+            : ''}
+          <button class="btn" @click=${() => this.darkMode = !this.darkMode} style="margin-right: 8px;">${this.darkMode ? '☀️' : '🌙'}</button>
+          <div class="btn-group">
+            <button class="btn ${this.view === 'month' ? 'active' : ''}" @click=${() => this.view = 'month'}>Mes</button>
+            <button class="btn ${this.view === 'week' ? 'active' : ''}" @click=${() => this.view = 'week'}>Semana</button>
+            <button class="btn ${this.view === 'day' ? 'active' : ''}" @click=${() => this.view = 'day'}>Día</button>
+          </div>
+        </div>
+      </div>
+
+      <div class="calendar-body">
+        ${this.view === 'month'
+          ? html`<glatam-calendar-month-view .days=${generateMonthDays(y, m, this.localRules, this.slots, this.startOfWeekDay)} .locale=${this.locale} .startOfWeekDay=${this.startOfWeekDay} .role=${this.role} .size=${this.size} .minDate=${this.minDate} .maxDate=${this.maxDate} .showNeighboringMonth=${this.showNeighboringMonth} .tileClassName=${this.tileClassName} @day-select=${this.handleDaySelect}></glatam-calendar-month-view>`
+          : this.view === 'week'
+          ? html`<glatam-calendar-week-view .days=${mapDays(generateWeekDays(this.activeDate, this.localRules, this.slots, this.startOfWeekDay))} .slots=${displaySlots} .locale=${this.locale} .selectedRange=${this.selectedRange} .role=${this.role} @range-select=${this.handleRangeSelect} @slot-click=${this.handleSlotClick}></glatam-calendar-week-view>`
+          : html`<glatam-calendar-day-view .day=${mapDays(generateWeekDays(this.activeDate, this.localRules, this.slots, this.startOfWeekDay)).find(d => d.dateString === formatISODate(this.activeDate)) || null} .slots=${displaySlots} .locale=${this.locale} .selectedRange=${this.selectedRange} .role=${this.role} @range-select=${this.handleRangeSelect} @slot-click=${this.handleSlotClick}></glatam-calendar-day-view>`}
+      </div>
+
+      <glatam-calendar-modal
+        .open=${this.modalOpen} .dateString=${this.modalDateString} .startTime=${this.modalStartTime} .endTime=${this.modalEndTime}
+        .isRange=${this.modalIsRange} .existingRule=${this.modalExistingRule} @save-rule=${this.handleSaveRule}
+        @delete-rule=${this.handleDeleteRule} @close=${() => this.modalOpen = false}
+      ></glatam-calendar-modal>
+    `;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap { 'glatam-calendar': GlatamCalendar; }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from './glatam-calendar.js';
+export * from './glatam-calendar-mini.js';
+export * from './views/month-view.js';
+export * from './views/week-view.js';
+export * from './views/day-view.js';
+export * from './components/calendar-modal.js';
+export * from './styles/variables.css.js';
+export * from './styles/calendar.css.js';
+export { formatISODate, parseISODate, isTimeBlocked } from '@glatam/calendar-core';

package/src/styles/calendar.css.ts

@@ -0,0 +1,259 @@
+import { css } from 'lit';
+
+export const calendarStyles = css`
+  :host {
+    display: grid;
+    min-width: 0;
+    font-family: var(--glatam-font-family);
+    color: var(--glatam-text);
+    background-color: var(--glatam-bg);
+    border-radius: var(--glatam-border-radius);
+    padding: var(--glatam-padding);
+    box-shadow: 0 4px 25px rgba(0, 0, 0, 0.05);
+    border: 1px solid var(--glatam-border);
+    box-sizing: border-box;
+    width: 100%;
+    max-width: 100%;
+    overflow: hidden;
+    transition: background-color var(--glatam-transition-normal), border-color var(--glatam-transition-normal);
+  }
+
+  *, *::before, *::after {
+    box-sizing: border-box;
+  }
+
+  .calendar-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    margin-bottom: var(--glatam-padding);
+    flex-wrap: wrap;
+    gap: 12px;
+  }
+
+  .nav-group, .view-group {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+  }
+
+  .nav-title {
+    font-size: 1.25rem;
+    font-weight: 600;
+    min-width: 140px;
+    text-align: center;
+    letter-spacing: -0.01em;
+  }
+
+  .btn {
+    font-family: inherit;
+    font-size: 0.875rem;
+    font-weight: 500;
+    padding: 8px 12px;
+    border-radius: 8px;
+    border: 1px solid var(--glatam-border);
+    background-color: var(--glatam-bg);
+    color: var(--glatam-text);
+    cursor: pointer;
+    transition: background-color var(--glatam-transition-fast), border-color var(--glatam-transition-fast), transform var(--glatam-transition-fast);
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    min-width: 36px;
+    height: 36px;
+  }
+
+  .btn:hover:not(:disabled) {
+    background-color: var(--glatam-surface);
+    border-color: var(--glatam-text-secondary);
+  }
+
+  .btn:active:not(:disabled) {
+    transform: scale(0.97);
+  }
+
+  .btn:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+
+  .btn-primary {
+    background-color: var(--glatam-primary);
+    color: var(--glatam-text-light);
+    border: none;
+  }
+
+  .btn-primary:hover:not(:disabled) {
+    background-color: var(--glatam-primary-hover);
+  }
+
+  .btn-group {
+    display: flex;
+    border-radius: 8px;
+    overflow: hidden;
+    border: 1px solid var(--glatam-border);
+  }
+
+  .btn-group .btn {
+    border-radius: 0;
+    border: none;
+    border-right: 1px solid var(--glatam-border);
+  }
+
+  .btn-group .btn:last-child {
+    border-right: none;
+  }
+
+  .btn-group .btn.active {
+    background-color: var(--glatam-primary-light);
+    color: var(--glatam-primary);
+    font-weight: 600;
+  }
+
+  /* Timezone Selector Styles */
+  .timezone-badge {
+    font-size: 0.75rem;
+    padding: 4px 8px;
+    background: var(--glatam-surface);
+    border: 1px solid var(--glatam-border);
+    border-radius: 20px;
+    display: inline-flex;
+    align-items: center;
+    gap: 4px;
+    color: var(--glatam-text-secondary);
+  }
+
+  .timezone-select {
+    background: transparent;
+    border: none;
+    color: var(--glatam-text);
+    font-family: inherit;
+    font-size: 0.75rem;
+    font-weight: 600;
+    cursor: pointer;
+    outline: none;
+    padding-right: 4px;
+  }
+
+  /* Mini Popover Variant Styles */
+  .dropdown-container {
+    position: relative;
+    display: inline-block;
+    width: 100%;
+  }
+
+  .dropdown-toggle {
+    width: 100%;
+    justify-content: space-between;
+    padding: 12px 16px;
+    border-radius: 12px;
+    font-weight: 600;
+    height: 48px;
+  }
+
+  .dropdown-card {
+    position: absolute;
+    top: calc(100% + 8px);
+    left: 0;
+    width: 320px;
+    background: var(--glatam-bg);
+    border-radius: 16px;
+    border: 1px solid var(--glatam-border);
+    box-shadow: 0 12px 40px rgba(0, 0, 0, 0.1);
+    z-index: 100;
+    padding: 16px;
+    display: flex;
+    flex-direction: column;
+    gap: 12px;
+    animation: fadeInUp 0.3s cubic-bezier(0.16, 1, 0.3, 1) forwards;
+  }
+
+  .slot-list {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+    max-height: 220px;
+    overflow-y: auto;
+    padding-right: 4px;
+  }
+
+  .slot-btn {
+    width: 100%;
+    padding: 10px;
+    border-radius: 8px;
+    border: 1px solid var(--glatam-border);
+    background: var(--glatam-bg);
+    color: var(--glatam-text);
+    cursor: pointer;
+    font-family: inherit;
+    font-size: 0.85rem;
+    font-weight: 500;
+    text-align: center;
+    transition: background-color var(--glatam-transition-fast);
+  }
+
+  .slot-btn:hover:not(.blocked) {
+    background-color: var(--glatam-surface);
+    border-color: var(--glatam-text-secondary);
+  }
+
+  .slot-btn.blocked {
+    background-color: var(--glatam-surface);
+    color: var(--glatam-blocked-text);
+    text-decoration: line-through;
+    cursor: not-allowed;
+    border-color: var(--glatam-border);
+    opacity: 0.6;
+  }
+
+  /* Smooth Apple Animation */
+  .calendar-body {
+    position: relative;
+    width: 100%;
+    overflow-x: auto;
+    animation: fadeInUp 0.4s cubic-bezier(0.16, 1, 0.3, 1) forwards;
+  }
+
+  @keyframes fadeInUp {
+    from {
+      opacity: 0;
+      transform: translateY(8px) scale(0.995);
+    }
+    to {
+      opacity: 1;
+      transform: translateY(0) scale(1);
+    }
+  }
+
+  @media (max-width: 600px) {
+    :host {
+      padding: 8px;
+    }
+    .calendar-header {
+      flex-direction: column;
+      align-items: stretch;
+      gap: 10px;
+    }
+    .nav-group, .view-group {
+      width: 100%;
+      justify-content: space-between;
+      flex-wrap: wrap;
+      gap: 6px;
+    }
+    .nav-title {
+      flex: 1;
+      font-size: 1.1rem;
+      min-width: unset;
+      text-align: right;
+      white-space: nowrap;
+      overflow: hidden;
+      text-overflow: ellipsis;
+    }
+    .btn {
+      font-size: 0.8rem;
+      padding: 6px 10px;
+      height: 32px;
+      min-width: 32px;
+    }
+  }
+`;

package/src/styles/variables.css.ts

@@ -0,0 +1,91 @@
+import { css } from 'lit';
+
+export const variablesStyles = css`
+  :host {
+    /* Fonts */
+    --glatam-font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+    
+    /* Colors - Premium Apple Light Theme */
+    --glatam-primary: #5856d6;
+    --glatam-primary-hover: #4745b4;
+    --glatam-primary-light: rgba(88, 86, 214, 0.1);
+    --glatam-primary-light-hover: rgba(88, 86, 214, 0.25);
+    
+    --glatam-bg: #ffffff;
+    --glatam-surface: #f5f5f7;
+    --glatam-border: #e5e5ea;
+    --glatam-text: #1d1d1f;
+    --glatam-text-secondary: #86868b;
+    --glatam-text-light: #ffffff;
+    
+    /* Blocked/Unavailable states */
+    --glatam-blocked-bg: #fcfcfd;
+    --glatam-blocked-stripe: #f2f2f7;
+    --glatam-blocked-text: #aeaeae;
+    --glatam-blocked-border: #e5e5ea;
+
+    /* Selection Colors */
+    --glatam-selection-bg: rgba(88, 86, 214, 0.15);
+    --glatam-selection-border: #5856d6;
+    
+    /* Today highlighting */
+    --glatam-today-text: #5856d6;
+    --glatam-today-bg: rgba(88, 86, 214, 0.08);
+    
+    /* Dimensions & Layout */
+    --glatam-border-radius: 12px;
+    --glatam-padding: 16px;
+    --glatam-grid-border-radius: 8px;
+    --glatam-day-min-height: 72px;
+    --glatam-time-col-width: 60px;
+    --glatam-slot-height: 48px;
+    
+    /* Animation duration */
+    --glatam-transition-fast: 0.15s ease;
+    --glatam-transition-normal: 0.25s ease;
+  }
+
+  :host(.dark-mode) {
+    /* Colors - Premium Apple Dark Theme */
+    --glatam-primary: #5e5ce6;
+    --glatam-primary-hover: #7d7aff;
+    --glatam-primary-light: rgba(94, 92, 230, 0.15);
+    --glatam-primary-light-hover: rgba(94, 92, 230, 0.3);
+    
+    --glatam-bg: #1c1c1e;
+    --glatam-surface: #2c2c2e;
+    --glatam-border: #38383a;
+    --glatam-text: #f5f5f7;
+    --glatam-text-secondary: #8e8e93;
+    
+    /* Blocked/Unavailable states */
+    --glatam-blocked-bg: #242426;
+    --glatam-blocked-stripe: #2c2c2e;
+    --glatam-blocked-text: #707074;
+    --glatam-blocked-border: #38383a;
+
+    /* Selection Colors */
+    --glatam-selection-bg: rgba(94, 92, 230, 0.25);
+    --glatam-selection-border: #5e5ce6;
+    
+    /* Today highlighting */
+    --glatam-today-text: #7d7aff;
+    --glatam-today-bg: rgba(94, 92, 230, 0.12);
+  }
+
+  :host([size="small"]) {
+    --glatam-day-min-height: 48px;
+    --glatam-slot-height: 36px;
+    --glatam-time-col-width: 48px;
+    --glatam-padding: 10px;
+    font-size: 0.8rem;
+  }
+
+  :host([size="large"]) {
+    --glatam-day-min-height: 96px;
+    --glatam-slot-height: 60px;
+    --glatam-time-col-width: 72px;
+    --glatam-padding: 24px;
+    font-size: 1.1rem;
+  }
+`;

package/src/utils/timezone-utils.ts

@@ -0,0 +1,87 @@
+import { TimeSlot } from '@glatam/calendar-core';
+
+/**
+ * Calculates the difference in minutes between two timezones on a specific date.
+ * 'local' represents the user's local timezone.
+ */
+export function getTimezoneOffsetDiff(date: Date, fromTz: string, toTz: string): number {
+  if (fromTz === toTz) return 0;
+
+  const getTzDate = (d: Date, tz: string) => {
+    const options: Intl.DateTimeFormatOptions = {
+      year: 'numeric', month: 'numeric', day: 'numeric',
+      hour: 'numeric', minute: 'numeric', second: 'numeric',
+      hour12: false,
+    };
+    if (tz !== 'local') {
+      options.timeZone = tz;
+    }
+    const formatter = new Intl.DateTimeFormat('en-US', options);
+    const parts = formatter.formatToParts(d);
+    const map = new Map(parts.map(p => [p.type, p.value]));
+    
+    const hourVal = Number(map.get('hour'));
+    const hour = hourVal === 24 ? 0 : hourVal;
+
+    return new Date(
+      Number(map.get('year')),
+      Number(map.get('month')) - 1,
+      Number(map.get('day')),
+      hour,
+      Number(map.get('minute')),
+      Number(map.get('second'))
+    );
+  };
+
+  try {
+    const d1 = getTzDate(date, fromTz);
+    const d2 = getTzDate(date, toTz);
+    return (d2.getTime() - d1.getTime()) / (60 * 1000);
+  } catch (e) {
+    // Fallback if timezone name is invalid
+    return 0;
+  }
+}
+
+/**
+ * Shifts a single TimeSlot's times by a given offset in minutes and returns the shifted slot and optional day offset.
+ */
+export function shiftSlot(slot: TimeSlot, offsetMinutes: number): { start: string; end: string; dayShift: number } {
+  if (offsetMinutes === 0) {
+    return { start: slot.start, end: slot.end, dayShift: 0 };
+  }
+
+  const parseToMinutes = (timeStr: string) => {
+    const [h, m] = timeStr.split(':').map(Number);
+    return h * 60 + m;
+  };
+
+  const formatFromMinutes = (totalMinutes: number) => {
+    // Normalize minutes to [0, 1439]
+    let normalized = totalMinutes % 1440;
+    if (normalized < 0) normalized += 1440;
+    const h = String(Math.floor(normalized / 60)).padStart(2, '0');
+    const m = String(normalized % 60).padStart(2, '0');
+    return `${h}:${m}`;
+  };
+
+  const startMin = parseToMinutes(slot.start);
+  const endMin = parseToMinutes(slot.end);
+
+  const shiftedStart = startMin + offsetMinutes;
+  const shiftedEnd = endMin + offsetMinutes;
+
+  // Determine if we crossed midnight (day shift)
+  let dayShift = 0;
+  if (shiftedStart < 0) {
+    dayShift = -1;
+  } else if (shiftedStart >= 1440) {
+    dayShift = 1;
+  }
+
+  return {
+    start: formatFromMinutes(shiftedStart),
+    end: formatFromMinutes(shiftedEnd),
+    dayShift
+  };
+}