panelui-native 0.80.0 → 0.82.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/components/select/index.tsx

@@ -81,6 +81,11 @@ const selectVariants = tv({
     triggerLabel: 'flex-1 text-base font-medium text-foreground',
     placeholder: 'flex-1 text-base text-muted-foreground',
     list: 'overflow-hidden rounded-xl border border-border bg-popover p-2 shadow-sm',
+    // The block of options inside a sheet. The sheet is the surface there, so
+    // this is what `listClassName` has to reach instead of `list`.
+    options: 'gap-1 pb-2',
+    search: 'pb-2',
+    empty: 'px-3 py-6 text-center text-sm text-muted-foreground',
     item: 'flex-row items-center gap-2 rounded-lg px-3 py-3',
     itemLabel: 'flex-1 text-base font-medium text-foreground',
     itemIndicator: 'h-5 w-5 items-center justify-center',
@@ -113,13 +118,51 @@ export type SelectPresentation = 'sheet' | 'inline' | 'overlay';
 interface SelectContextValue {
   value: string | undefined;
   onSelect: (value: string) => void;
+  query: string;
+  setQuery: (query: string) => void;
 }
 
 const SelectContext = createContext<SelectContextValue | null>(null);
 
+/**
+ * The filter field's text, from inside an open Select.
+ *
+ * Select can only filter the options it renders itself. A caller who hands it
+ * a virtualized list is rendering their own rows, from their own data, and
+ * this is how they get the query to filter that data with — `Select.Item`
+ * still works wherever those rows put it, because selection travels by
+ * context rather than by position.
+ *
+ * ```tsx
+ * function Options() {
+ *   const { query } = useSelectSearch();
+ *   const rows = useMemo(() => filter(timezones, query), [query]);
+ *   return (
+ *     <FlashList
+ *       data={rows}
+ *       renderItem={({ item }) => <Select.Item value={item.id} label={item.name} />}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * `setQuery` is there for a caller who wants to clear or seed the field.
+ */
+export function useSelectSearch(): { query: string; setQuery: (query: string) => void } {
+  const context = useContext(SelectContext);
+  if (!context) {
+    throw new Error('useSelectSearch must be used within a <Select>');
+  }
+  return { query: context.query, setQuery: context.setQuery };
+}
+
 export interface SelectItemProps {
   value: string;
   label: string;
+  /** Extra classes for the option row. */
+  className?: string;
+  /** Extra classes for the option's label. */
+  labelClassName?: string;
   /**
    * Shows the option but refuses it — a plan above the current tier, a region
    * with nothing in stock. Kept in the list rather than dropped from it, because
@@ -129,7 +172,7 @@ export interface SelectItemProps {
 }
 
 /** Declarative option. Rendered inside whichever surface is presenting. */
-function SelectItem({ value, label, disabled }: SelectItemProps) {
+function SelectItem({ value, label, disabled, className, labelClassName }: SelectItemProps) {
   const context = useContext(SelectContext);
   if (!context) {
     throw new Error('Select.Item must be used within a <Select>');
@@ -148,9 +191,9 @@ function SelectItem({ value, label, disabled }: SelectItemProps) {
       accessibilityState={{ selected, disabled: !!disabled }}
       disabled={disabled}
       onPress={() => context.onSelect(value)}
-      className={item()}
+      className={item({ className })}
     >
-      <Text className={itemLabel()}>{label}</Text>
+      <Text className={itemLabel({ className: labelClassName })}>{label}</Text>
       <View className={itemIndicator()}>
         {selected ? (
           <CheckIcon
@@ -220,37 +263,62 @@ function eachOption(children: ReactNode, visit: (option: SelectItemProps) => voi
   });
 }
 
+/** What a pass of the filter left, and how much there was to filter. */
+interface FilterResult {
+  /** The children to render. */
+  kept: ReactNode[];
+  /** How many `Select.Item`s the pass saw, at any depth it can reach. */
+  seen: number;
+}
+
 /**
  * The children a query leaves standing.
  *
  * A group is rebuilt around whatever survives inside it and dropped when that
  * is nothing — a heading with no options under it reads as a section that
- * failed to load rather than one the filter emptied. Anything that is neither
- * an item nor a group is left alone: a caption or a divider the caller put in
- * the list is not something a filter has an opinion about.
+ * failed to load rather than one the filter emptied.
+ *
+ * Anything that is neither an item nor a group is left alone: a caption or a
+ * divider the caller put in the list is not something a filter has an opinion
+ * about, and neither is a list component rendering its own rows. Dropping
+ * those was how a `Select.Item` inside a virtualized list disappeared the
+ * moment anybody typed — the list was not an item, so nothing kept it.
+ *
+ * `seen` is what tells an empty result from an unfilterable one. Zero items
+ * seen means the caller is rendering their own rows and filtering them
+ * themselves through `useSelectSearch`, so there is nothing to call empty.
  */
-function filterOptions(children: ReactNode, needle: string): ReactNode[] {
+function filterOptions(children: ReactNode, needle: string): FilterResult {
   const kept: ReactNode[] = [];
+  let seen = 0;
 
   Children.forEach(children, (child) => {
-    if (!isValidElement(child)) return;
+    if (!isValidElement(child)) {
+      if (child !== null && child !== undefined && child !== false) kept.push(child);
+      return;
+    }
 
     if (child.type === SelectGroup) {
       const props = child.props as SelectGroupProps;
       const inner = filterOptions(props.children, needle);
-      if (inner.length) {
-        kept.push(cloneElement(child as ReactElement<SelectGroupProps>, {}, inner));
+      seen += inner.seen;
+      if (inner.kept.length) {
+        kept.push(cloneElement(child as ReactElement<SelectGroupProps>, {}, inner.kept));
       }
       return;
     }
 
     if (child.type === SelectItem) {
+      seen += 1;
       const { label } = child.props as SelectItemProps;
       if (label.toLowerCase().includes(needle)) kept.push(child);
+      return;
     }
+
+    kept.push(child);
   });
 
-  return kept;
+  return { kept, seen };
 }
 
 /** Trigger frame in window coordinates, measured when the list opens. */
@@ -262,11 +330,52 @@ interface Anchor {
 }
 
 export interface SelectProps {
+  /**
+   * Extra classes for the wrapper around the trigger — the box the select
+   * occupies in your layout, which is where margins and widths belong. To
+   * restyle the field itself, use `triggerClassName`.
+   */
   className?: string;
+  /** The selected option's `value`. Leave unset for the placeholder. */
   value?: string;
+  /**
+   * What the trigger shows for the current `value`.
+   *
+   * Select reads the label off its `Select.Item` children, which it cannot do
+   * when a list component renders those rows — the elements do not exist until
+   * the list decides to draw them, and the selected one may be scrolled far
+   * out of view. Pass the label yourself in that case; otherwise leave it
+   * unset and the trigger will find it.
+   */
+  valueLabel?: string;
+  /** Called with the `value` of the option that was picked. */
   onValueChange: (value: string) => void;
+  /** Shown on the trigger while nothing is selected. */
   placeholder?: string;
+  /** Refuses the trigger and dims it. The options cannot be opened. */
   disabled?: boolean;
+  /** Extra classes for the trigger — the field you press to open the list. */
+  triggerClassName?: string;
+  /** Extra classes for the selected option's text on the trigger. */
+  valueClassName?: string;
+  /** Extra classes for the placeholder text on the trigger. */
+  placeholderClassName?: string;
+  /**
+   * Extra classes for the surface the options sit on. In `sheet` the sheet is
+   * that surface, so this reaches the block of options inside it instead.
+   */
+  listClassName?: string;
+  /** Extra classes for the row the filter field sits in. `searchable` only. */
+  searchClassName?: string;
+  /** Extra classes for the filter field itself. `searchable` only. */
+  searchInputClassName?: string;
+  /**
+   * Extra classes for the box drawn around the filter field — its fill, border
+   * and radius. `searchable` only.
+   */
+  searchContainerClassName?: string;
+  /** Extra classes for the message shown when the filter matches nothing. */
+  emptyClassName?: string;
   /**
    * Where the options appear. `sheet` takes the bottom of the screen, `inline`
    * expands the list in layout flow, `overlay` floats it above the page
@@ -318,9 +427,18 @@ export interface SelectProps {
 function SelectRoot({
   className,
   value,
+  valueLabel,
   onValueChange,
   placeholder = 'Select an option',
   disabled,
+  triggerClassName,
+  valueClassName,
+  placeholderClassName,
+  listClassName,
+  searchClassName,
+  searchInputClassName,
+  searchContainerClassName,
+  emptyClassName,
   presentation = 'sheet',
   title,
   contentWidth = 'trigger',
@@ -357,8 +475,8 @@ function SelectRoot({
     native && nativeSelectSupportsOptions(options) ? getNativeUI() : null;
 
   const selectedLabel = useMemo(
-    () => options.find((option) => option.value === value)?.label,
-    [options, value]
+    () => valueLabel ?? options.find((option) => option.value === value)?.label,
+    [options, value, valueLabel]
   );
 
   /*
@@ -374,6 +492,14 @@ function SelectRoot({
     return filterOptions(children, needle);
   }, [children, query, searchable]);
 
+  /*
+   * Nothing left, out of something there was. A caller rendering their own
+   * rows filters them themselves, so `seen` is zero and their list stands —
+   * saying "no matches" over the top of it would be Select claiming to know an
+   * answer it was never shown.
+   */
+  const noMatches = filtered !== null && filtered.seen > 0 && filtered.kept.length === 0;
+
   const close = useCallback(() => {
     chevron.value = withTiming(0, { duration: 160 });
     setOpen(false);
@@ -420,8 +546,10 @@ function SelectRoot({
         onValueChange(next);
         close();
       },
+      query,
+      setQuery,
     }),
-    [value, onValueChange, close]
+    [value, onValueChange, close, query]
   );
 
   const slots = selectVariants({ disabled: !!disabled, presentation });
@@ -468,12 +596,12 @@ function SelectRoot({
       accessibilityState={{ disabled: !!disabled, expanded: open }}
       disabled={disabled}
       onPress={toggle}
-      className={slots.trigger()}
+      className={slots.trigger({ className: triggerClassName })}
     >
       {selectedLabel ? (
-        <Text className={slots.triggerLabel()}>{selectedLabel}</Text>
+        <Text className={slots.triggerLabel({ className: valueClassName })}>{selectedLabel}</Text>
       ) : (
-        <Text className={slots.placeholder()}>{placeholder}</Text>
+        <Text className={slots.placeholder({ className: placeholderClassName })}>{placeholder}</Text>
       )}
       <Animated.View style={chevronStyle}>
         <ChevronDownIcon
@@ -490,7 +618,7 @@ function SelectRoot({
    * what it is.
    */
   const search = searchable ? (
-    <View className="pb-2">
+    <View className={slots.search({ className: searchClassName })}>
       <InputGroup>
         <InputGroup.Prefix isDecorative>
           <SearchIcon
@@ -501,6 +629,8 @@ function SelectRoot({
         <InputGroup.Input
           variant="filled"
           size="sm"
+          className={searchInputClassName}
+          containerClassName={searchContainerClassName}
           value={query}
           onChangeText={setQuery}
           placeholder={searchPlaceholder}
@@ -514,16 +644,13 @@ function SelectRoot({
     </View>
   ) : null;
 
-  const optionList =
-    filtered === null ? (
-      textChildren(children)
-    ) : filtered.length ? (
-      filtered
-    ) : (
-      <Text className="px-3 py-6 text-center text-sm text-muted-foreground">
-        {emptyMessage}
-      </Text>
-    );
+  const optionList = noMatches ? (
+    <Text className={slots.empty({ className: emptyClassName })}>{emptyMessage}</Text>
+  ) : filtered === null ? (
+    textChildren(children)
+  ) : (
+    filtered.kept
+  );
 
   if (presentation === 'sheet') {
     return (
@@ -556,7 +683,7 @@ function SelectRoot({
                 keyboardDismissMode="on-drag"
                 keyboardShouldPersistTaps="handled"
               >
-                <View className="gap-1 pb-2">{optionList}</View>
+                <View className={slots.options({ className: listClassName })}>{optionList}</View>
               </ScrollView>
             </SelectContext.Provider>
           </BottomSheet.Content>
@@ -574,7 +701,7 @@ function SelectRoot({
             <Animated.View
               entering={FadeIn.duration(140)}
               exiting={FadeOut.duration(120)}
-              className={slots.list()}
+              className={slots.list({ className: listClassName })}
             >
               {search}
               {optionList}
@@ -651,7 +778,7 @@ function SelectRoot({
                * has to say it itself.
                */
               accessibilityViewIsModal
-              className={slots.list()}
+              className={slots.list({ className: listClassName })}
             >
               {search}
               <ScrollView