panelui-native 0.80.0 → 0.81.0

package/src/components/planner/planner-entries.ts

@@ -153,3 +153,36 @@ export function summariseMonth<T extends PlannerDatedEntry>(
     })),
   };
 }
+
+/**
+ * Minutes since midnight, or `null` for an entry that lands exactly on it.
+ *
+ * The grid has only ever read an entry's day, so a date with no time set is
+ * midnight — and that is indistinguishable from something genuinely scheduled
+ * at 00:00. Reading it as all-day is the right way round: a set of entries
+ * built without times renders as a list of things happening that day, which is
+ * what it is, rather than as a column of midnights.
+ */
+export function entryTimeMinutes(date: Date): number | null {
+  const minutes = date.getHours() * 60 + date.getMinutes();
+  return minutes === 0 ? null : minutes;
+}
+
+/**
+ * All-day first, then by time, keeping the caller's order within each.
+ *
+ * All-day leads because it frames the rest of the day rather than falling at a
+ * point in it, and a list that opens with "All day" reads as a heading for
+ * what follows.
+ */
+export function sortByTime<T extends PlannerDatedEntry>(entries: readonly T[]): T[] {
+  return entries
+    .map((entry, index) => ({ entry, index, at: entryTimeMinutes(entry.date) }))
+    .sort((a, b) => {
+      if (a.at === null && b.at === null) return a.index - b.index;
+      if (a.at === null) return -1;
+      if (b.at === null) return 1;
+      return a.at === b.at ? a.index - b.index : a.at - b.at;
+    })
+    .map(({ entry }) => entry);
+}

package/src/components/planner/planner-grid-navigation.ts

@@ -6,40 +6,75 @@ export type PlannerGridNavigationKey =
   | 'Home'
   | 'End';
 
+/**
+ * Whether a cell can take focus. Some looks leave the days either side of the
+ * month blank, and a blank has nothing to focus — so the caller says which
+ * indices are real and movement steps over the rest.
+ */
+export type PlannerGridNavigable = (index: number) => boolean;
+
 /** Returns the next visible cell for a bounded, row-major month grid. */
 export function plannerGridTarget(
   key: string,
   index: number,
   count: number,
-  columns = 7
+  columns = 7,
+  navigable?: PlannerGridNavigable
 ): number | null {
   if (!Number.isInteger(index) || index < 0 || index >= count || columns < 1) {
     return null;
   }
 
   let target: number;
+  /*
+   * Which way to keep going when the first landing is blank. The arrows carry
+   * on away from where you were; Home and End start at the edge of the row and
+   * come back inward, because the cell they want is the outermost real one and
+   * anything past it is off the row entirely.
+   */
+  let step: number;
   switch (key as PlannerGridNavigationKey) {
     case 'ArrowLeft':
       target = index - 1;
+      step = -1;
       break;
     case 'ArrowRight':
       target = index + 1;
+      step = 1;
       break;
     case 'ArrowUp':
       target = index - columns;
+      step = -columns;
       break;
     case 'ArrowDown':
       target = index + columns;
+      step = columns;
       break;
     case 'Home':
       target = index - (index % columns);
+      step = 1;
       break;
     case 'End':
       target = index + (columns - 1 - (index % columns));
+      step = -1;
       break;
     default:
       return null;
   }
 
-  return target >= 0 && target < count ? target : index;
+  if (target < 0 || target >= count) return index;
+  if (!navigable) return target;
+
+  /*
+   * Stepping stops at the cell you started from rather than running past it.
+   * That covers both directions at once: an arrow that finds nothing before
+   * the grid ends stays put, and Home or End on a row whose edge is blank
+   * walks in until it reaches a real day or arrives back where it began.
+   */
+  while (target !== index && !navigable(target)) {
+    target += step;
+    if (target < 0 || target >= count) return index;
+  }
+
+  return target;
 }

package/src/components/planner/planner-weeks.ts

@@ -0,0 +1,90 @@
+/**
+ * The arithmetic behind a calendar that scrolls instead of paging: which weeks
+ * are reachable, where a week starts, and which month a week belongs to.
+ *
+ * Nothing here imports anything, for the same reason as `planner-entries`: the
+ * tests run this file through `node --test` with type stripping rather than a
+ * bundler, so an extensionless import of a sibling does not resolve.
+ *
+ * A week is seven days whatever calendar is in force, so all of this is plain
+ * day arithmetic. Naming the month a week falls in is not, and is left to the
+ * caller, which has the calendar system.
+ */
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** Local midnight, so two dates on the same day compare equal. */
+function atMidnight(date: Date): Date {
+  const copy = new Date(date);
+  copy.setHours(0, 0, 0, 0);
+  return copy;
+}
+
+/**
+ * Days added by the calendar rather than by milliseconds.
+ *
+ * A day is not always 24 hours — the ones a daylight-saving change falls on are
+ * 23 or 25 — so stepping by `DAY_MS` drifts across a transition and lands a
+ * week row an hour before or after midnight, which then reads as the wrong day.
+ */
+export function addDaysLocal(date: Date, days: number): Date {
+  const copy = new Date(date);
+  copy.setDate(copy.getDate() + days);
+  return atMidnight(copy);
+}
+
+/** The first day of the week `date` falls in, for a week starting on `weekStartsOn`. */
+export function startOfWeek(date: Date, weekStartsOn: number): Date {
+  const start = ((weekStartsOn % 7) + 7) % 7;
+  const midnight = atMidnight(date);
+  const shift = (midnight.getDay() - start + 7) % 7;
+  return addDaysLocal(midnight, -shift);
+}
+
+/**
+ * The day a week is named after: its midpoint.
+ *
+ * A week straddling a month boundary belongs to whichever month holds most of
+ * it, and the fourth day is the cheapest way to ask that — it is on the heavier
+ * side by definition. Naming the week after its first day would put the last
+ * week of January under December for as little as one day's overlap.
+ */
+export function weekAnchor(weekStart: Date): Date {
+  return addDaysLocal(weekStart, 3);
+}
+
+/** The seven days of a week, in order. */
+export function weekDays(weekStart: Date): Date[] {
+  return Array.from({ length: 7 }, (_unused, day) => addDaysLocal(weekStart, day));
+}
+
+/**
+ * Every week start from `weeksBefore` before the anchor's week to `weeksAfter`
+ * after it, in order.
+ *
+ * A bounded range rather than an endless one: a scroller needs to know how tall
+ * it is to place a scrollbar and to jump to a month without rendering its way
+ * there, and neither is possible over an infinite list.
+ */
+export function weekRange(anchor: Date, weekStartsOn: number, weeksBefore: number, weeksAfter: number): Date[] {
+  const first = startOfWeek(anchor, weekStartsOn);
+  const before = Math.max(0, Math.trunc(weeksBefore));
+  const after = Math.max(0, Math.trunc(weeksAfter));
+  return Array.from({ length: before + after + 1 }, (_unused, step) =>
+    addDaysLocal(first, (step - before) * 7)
+  );
+}
+
+/**
+ * Where `date`'s week sits in a range, or `-1`.
+ *
+ * Computed from the span rather than searched for, so jumping to a month costs
+ * the same whether it is one screen away or a year.
+ */
+export function weekIndex(weeks: readonly Date[], date: Date, weekStartsOn: number): number {
+  const first = weeks[0];
+  if (!first) return -1;
+  const target = startOfWeek(date, weekStartsOn);
+  const index = Math.round((target.getTime() - first.getTime()) / (7 * DAY_MS));
+  return index >= 0 && index < weeks.length ? index : -1;
+}

package/src/index.ts

@@ -833,6 +833,8 @@ export {
   type PlannerNavProps,
   type PlannerActionProps,
   type PlannerGridProps,
+  type PlannerScrollerProps,
+  type PlannerVariant,
   type PlannerDayProps,
   type PlannerDayState,
   type PlannerDayRenderer,

package/src/utils/date.ts

@@ -535,13 +535,23 @@ export function monthNames(locale: DateLocale, style: 'long' | 'short' = 'long')
 }
 
 /** Column headings, rotated so the first one is `weekStartsOn`. */
-export function weekdayNames(locale: DateLocale, weekStartsOn: number): string[] {
+export function weekdayNames(
+  locale: DateLocale,
+  weekStartsOn: number,
+  /*
+   * `narrow` is a single letter in most locales, and several of them repeat —
+   * English has T twice and S twice. That is only safe where the column it
+   * heads is already unambiguous by position, which is why it is a caller's
+   * choice rather than the default.
+   */
+  width: 'short' | 'narrow' = 'short'
+): string[] {
   const first = normalizeWeekStart(weekStartsOn);
   // 2021-08-01 was a Sunday, so adding the index lands on each weekday in turn.
   return Array.from({ length: 7 }, (_unused, day) => {
     const index = (day + first) % 7;
-    const formatted = formatGregory(new Date(2021, 7, 1 + index), locale, { weekday: 'short' });
-    return formatted ?? WEEKDAYS_EN[index]!;
+    const formatted = formatGregory(new Date(2021, 7, 1 + index), locale, { weekday: width });
+    return formatted ?? (width === 'narrow' ? WEEKDAYS_EN[index]![0]! : WEEKDAYS_EN[index]!);
   });
 }