@proyecto-viviana/solid-stately 0.3.0 → 0.4.1

package/src/collections/createSelectionState.ts

@@ -74,11 +74,24 @@ export interface SelectionState {
   /** Extend selection to a key (for shift-click). */
   extendSelection(toKey: Key, collection: Collection): void;
   /** Select a key based on interaction. */
-  select(
-    key: Key,
-    e?: { shiftKey?: boolean; ctrlKey?: boolean; metaKey?: boolean },
-    collection?: Collection,
-  ): void;
+  select(key: Key, e?: SelectionPressEvent): void;
+}
+
+/**
+ * The press/pointer interaction consulted by {@link SelectionState.select}.
+ * Mirrors react-stately's `SelectionManager.select(e)`: only `pointerType` is
+ * read here (touch / virtual force toggle, since those devices have no modifier
+ * keys). Modifier keys (ctrl / meta / shift) are resolved one layer up in the
+ * aria-layer `onSelect` (solidaria `selectItem`), matching upstream's split
+ * between react-stately and react-aria. The modifier fields are accepted so a
+ * full press/pointer event is assignable, but they are not read here.
+ */
+export interface SelectionPressEvent {
+  pointerType?: "mouse" | "pen" | "touch" | "keyboard" | "virtual";
+  shiftKey?: boolean;
+  ctrlKey?: boolean;
+  metaKey?: boolean;
+  altKey?: boolean;
 }
 
 /**
@@ -268,33 +281,30 @@ export function createSelectionState(
     updateSelection(new Set(rangeKeys));
   };
 
-  const select = (
-    key: Key,
-    e?: { shiftKey?: boolean; ctrlKey?: boolean; metaKey?: boolean },
-    collection?: Collection,
-  ) => {
-    if (isDisabled(key)) return;
+  const select = (key: Key, e?: SelectionPressEvent) => {
+    // Mirrors react-stately's SelectionManager.select: only pointerType +
+    // selectionBehavior are consulted here. Modifier-key handling (ctrl / meta
+    // ⇒ toggle, shift ⇒ extend) lives one layer up in solidaria's aria-layer
+    // `selectItem`, which is where the platform-aware isCtrlKeyPressed is
+    // available. The primitives self-guard disabled keys, so no guard is
+    // needed here (matching upstream).
     if (selectionMode() === "none") return;
 
-    const mode = selectionMode();
-    const behavior = selectionBehavior();
-
-    if (mode === "single") {
-      if (behavior === "replace" || !isSelected(key)) {
+    if (selectionMode() === "single") {
+      // Single mode ignores selectionBehavior. Re-selecting the current item
+      // deselects it when empty selection is allowed; otherwise it stays
+      // selected (replace).
+      if (isSelected(key) && !disallowEmptySelection()) {
+        toggleSelection(key);
+      } else {
         replaceSelection(key);
-      } else if (!disallowEmptySelection()) {
-        clearSelection();
       }
-      return;
-    }
-
-    // Multiple selection
-    if (e?.shiftKey && collection) {
-      extendSelection(key, collection);
-      return;
-    }
-
-    if (e?.ctrlKey || e?.metaKey || behavior === "toggle") {
+    } else if (
+      selectionBehavior() === "toggle" ||
+      (e != null && (e.pointerType === "touch" || e.pointerType === "virtual"))
+    ) {
+      // touch / virtual (VoiceOver) have no modifier keys, so multi-select is
+      // only reachable by toggling.
       toggleSelection(key);
     } else {
       replaceSelection(key);

package/src/collections/getChildNodes.ts

@@ -0,0 +1,129 @@
+/**
+ * Helpers for traversing collection nodes and comparing their document order.
+ *
+ * Based on @react-stately/collections.
+ */
+
+import type { Collection, CollectionNode } from "./types";
+
+export function getChildNodes<T>(
+  node: CollectionNode<T>,
+  collection: Collection<T>,
+): Iterable<CollectionNode<T>> {
+  // New API: call collection.getChildren with the node key.
+  if (typeof collection.getChildren === "function") {
+    return collection.getChildren(node.key);
+  }
+
+  // Old API: access childNodes directly.
+  return node.childNodes;
+}
+
+export function getFirstItem<T>(iterable: Iterable<T>): T | undefined {
+  return getNthItem(iterable, 0);
+}
+
+export function getNthItem<T>(iterable: Iterable<T>, index: number): T | undefined {
+  if (index < 0) {
+    return undefined;
+  }
+
+  let i = 0;
+  for (const item of iterable) {
+    if (i === index) {
+      return item;
+    }
+
+    i++;
+  }
+}
+
+export function getLastItem<T>(iterable: Iterable<T>): T | undefined {
+  let lastItem: T | undefined = undefined;
+  for (const value of iterable) {
+    lastItem = value;
+  }
+
+  return lastItem;
+}
+
+const itemCountCache = new WeakMap<Collection<unknown>, number>();
+
+/**
+ * Counts the item nodes (recursing into sections, ignoring section headers and
+ * other non-item nodes) in a collection. Faithful port of
+ * @react-stately/collections `getItemCount`; used by createOption to populate
+ * `aria-setsize` when the listbox is virtualized. Cached per (immutable)
+ * collection identity, exactly like upstream.
+ */
+export function getItemCount<T>(collection: Collection<T>): number {
+  const cached = itemCountCache.get(collection);
+  if (cached != null) {
+    return cached;
+  }
+
+  let counter = 0;
+  const countItems = (items: Iterable<CollectionNode<T>>) => {
+    for (const item of items) {
+      if (item.type === "section") {
+        countItems(getChildNodes(item, collection));
+      } else if (item.type === "item") {
+        counter++;
+      }
+    }
+  };
+
+  countItems(collection);
+  itemCountCache.set(collection, counter);
+  return counter;
+}
+
+export function compareNodeOrder<T>(
+  collection: Collection<T>,
+  a: CollectionNode<T>,
+  b: CollectionNode<T>,
+): number {
+  // If the two nodes have the same parent, compare their indices.
+  if (a.parentKey === b.parentKey) {
+    return a.index - b.index;
+  }
+
+  // Otherwise, collect all of the ancestors from each node, and find the first one that doesn't match starting from the root.
+  // Include the base nodes in case we are comparing nodes of different levels so that we can compare the higher node to the lower level node's
+  // ancestor of the same level
+  const aAncestors = [...getAncestors(collection, a), a];
+  const bAncestors = [...getAncestors(collection, b), b];
+  const firstNonMatchingAncestor = aAncestors
+    .slice(0, bAncestors.length)
+    .findIndex((a, i) => a !== bAncestors[i]);
+  if (firstNonMatchingAncestor !== -1) {
+    // Compare the indices of two children within the common ancestor.
+    a = aAncestors[firstNonMatchingAncestor];
+    b = bAncestors[firstNonMatchingAncestor];
+    return a.index - b.index;
+  }
+
+  // If there isn't a non matching ancestor, we might be in a case where one of the nodes is the ancestor of the other.
+  if (aAncestors.findIndex((node) => node === b) >= 0) {
+    return 1;
+  } else if (bAncestors.findIndex((node) => node === a) >= 0) {
+    return -1;
+  }
+
+  // 🤷
+  return -1;
+}
+
+function getAncestors<T>(collection: Collection<T>, node: CollectionNode<T>): CollectionNode<T>[] {
+  const parents: CollectionNode<T>[] = [];
+
+  let currNode: CollectionNode<T> | null = node;
+  while (currNode?.parentKey != null) {
+    currNode = collection.getItem(currNode.parentKey);
+    if (currNode) {
+      parents.unshift(currNode);
+    }
+  }
+
+  return parents;
+}

package/src/collections/index.ts

@@ -16,17 +16,29 @@ export type {
 
 export { ListCollection, createListCollection } from "./ListCollection";
 
+export {
+  getChildNodes,
+  getFirstItem,
+  getNthItem,
+  getLastItem,
+  getItemCount,
+  compareNodeOrder,
+} from "./getChildNodes";
+
 export {
   createSelectionState,
   type SelectionStateProps,
   type SelectionState,
+  type SelectionPressEvent,
 } from "./createSelectionState";
 
 export {
   createListState,
+  createFilteredListState,
   createSingleSelectListState,
   type ListStateProps,
   type ListState,
+  type ListFilterFn,
   type SingleSelectListStateProps,
   type SingleSelectListState,
 } from "./createListState";

package/src/collections/types.ts

@@ -88,6 +88,16 @@ export interface Collection<T = unknown> extends Iterable<CollectionNode<T>> {
 
   /** Get the text value for a key. */
   getTextValue(key: Key): string;
+
+  /**
+   * Filter the collection, returning a new collection containing only the item
+   * nodes for which `filterFn` returns true. Sections whose children are all
+   * filtered out are dropped. Mirrors @react-aria/collections
+   * `BaseCollection.filter` (and the optional `Collection.filter` in
+   * @react-types/shared). Used by Autocomplete to narrow the collection as the
+   * user types.
+   */
+  filter?(filterFn: (nodeValue: string, node: CollectionNode<T>) => boolean): Collection<T>;
 }
 
 /**

package/src/color/Color.ts

@@ -16,6 +16,11 @@ import type {
   HSLColor,
   HSBColor,
 } from "./types";
+import {
+  getColorStringForLocale,
+  formatColorMessage,
+  type ColorStringKey,
+} from "./intl";
 
 // Channel ranges
 const RGB_CHANNEL_RANGE: ColorChannelRange = {
@@ -46,18 +51,6 @@ const PERCENT_CHANNEL_RANGE: ColorChannelRange = {
   pageSize: 10,
 };
 
-// Channel names (English only for now)
-const CHANNEL_NAMES: Record<ColorChannel, string> = {
-  hue: "Hue",
-  saturation: "Saturation",
-  brightness: "Brightness",
-  lightness: "Lightness",
-  red: "Red",
-  green: "Green",
-  blue: "Blue",
-  alpha: "Alpha",
-};
-
 // React Stately uses OKLCH for color names so that lightness is perceptually
 // consistent across hues.
 const ORANGE_LIGHTNESS_THRESHOLD = 0.68;
@@ -122,46 +115,36 @@ function rgbToHsl(r: number, g: number, b: number): { h: number; s: number; l: n
     }
   }
 
+  // 2-decimal precision mirrors upstream RGBColor.toHSL (toFixedNumber(_, 2)); the
+  // old integer rounding silently shifted converted hues by up to half a degree,
+  // which surfaced as a 1-LSB gradient divergence in ColorArea.
   return {
-    h: Math.round(h * 360),
-    s: Math.round(s * 100),
-    l: Math.round(l * 100),
+    h: toFixed(h * 360, 2),
+    s: toFixed(s * 100, 2),
+    l: toFixed(l * 100, 2),
   };
 }
 
 /**
- * Convert HSL to RGB.
+ * Convert HSL to RGB. Mirrors upstream @react-stately/color HSLColor.toRGB
+ * bit-for-bit — the Wikipedia "HSL to RGB alternative" formula
+ * (https://en.wikipedia.org/wiki/HSL_and_HSV#HSL_to_RGB_alternative) — so the
+ * float64 LSB rounding matches the oracle exactly. The classic hue2rgb algorithm
+ * is equivalent in the reals but rounds a channel differently at .5 boundaries
+ * (e.g. hsl(50,100%,50%) green computes to 212.5 → 213 here, 212 upstream).
+ * h is in degrees [0,360]; s and l are percentages [0,100].
  */
 function hslToRgb(h: number, s: number, l: number): { r: number; g: number; b: number } {
-  h /= 360;
-  s /= 100;
-  l /= 100;
-
-  let r: number, g: number, b: number;
-
-  if (s === 0) {
-    r = g = b = l;
-  } else {
-    const hue2rgb = (p: number, q: number, t: number) => {
-      if (t < 0) t += 1;
-      if (t > 1) t -= 1;
-      if (t < 1 / 6) return p + (q - p) * 6 * t;
-      if (t < 1 / 2) return q;
-      if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;
-      return p;
-    };
-
-    const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
-    const p = 2 * l - q;
-    r = hue2rgb(p, q, h + 1 / 3);
-    g = hue2rgb(p, q, h);
-    b = hue2rgb(p, q, h - 1 / 3);
-  }
+  const saturation = s / 100;
+  const lightness = l / 100;
+  const a = saturation * Math.min(lightness, 1 - lightness);
+  const fn = (n: number, k = (n + h / 30) % 12) =>
+    lightness - a * Math.max(Math.min(k - 3, 9 - k, 1), -1);
 
   return {
-    r: Math.round(r * 255),
-    g: Math.round(g * 255),
-    b: Math.round(b * 255),
+    r: Math.round(fn(0) * 255),
+    g: Math.round(fn(8) * 255),
+    b: Math.round(fn(4) * 255),
   };
 }
 
@@ -194,72 +177,38 @@ function rgbToHsb(r: number, g: number, b: number): { h: number; s: number; b: n
     }
   }
 
+  // 2-decimal precision mirrors upstream RGBColor.toHSB (toFixedNumber(_, 2)).
   return {
-    h: Math.round(h * 360),
-    s: Math.round(s * 100),
-    b: Math.round(v * 100),
+    h: toFixed(h * 360, 2),
+    s: toFixed(s * 100, 2),
+    b: toFixed(v * 100, 2),
   };
 }
 
 /**
- * Convert HSB to RGB.
+ * Convert HSB (HSV) to RGB. Mirrors upstream @react-stately/color HSBColor.toRGB
+ * bit-for-bit — the Wikipedia "HSV to RGB alternative" formula
+ * (https://en.wikipedia.org/wiki/HSL_and_HSV#HSV_to_RGB_alternative) — so the
+ * float64 LSB rounding matches the oracle exactly. The classic sextant algorithm
+ * is equivalent in the reals but can round a channel differently at .5 boundaries.
+ * h is in degrees [0,360]; s and b are percentages [0,100].
  */
 function hsbToRgb(h: number, s: number, b: number): { r: number; g: number; b: number } {
-  h /= 360;
-  s /= 100;
-  b /= 100;
-
-  let r: number, g: number, bl: number;
-
-  const i = Math.floor(h * 6);
-  const f = h * 6 - i;
-  const p = b * (1 - s);
-  const q = b * (1 - f * s);
-  const t = b * (1 - (1 - f) * s);
-
-  switch (i % 6) {
-    case 0:
-      r = b;
-      g = t;
-      bl = p;
-      break;
-    case 1:
-      r = q;
-      g = b;
-      bl = p;
-      break;
-    case 2:
-      r = p;
-      g = b;
-      bl = t;
-      break;
-    case 3:
-      r = p;
-      g = q;
-      bl = b;
-      break;
-    case 4:
-      r = t;
-      g = p;
-      bl = b;
-      break;
-    default:
-      r = b;
-      g = p;
-      bl = q;
-      break;
-  }
+  const saturation = s / 100;
+  const brightness = b / 100;
+  const fn = (n: number, k = (n + h / 60) % 6) =>
+    brightness - saturation * brightness * Math.max(Math.min(k, 4 - k, 1), 0);
 
   return {
-    r: Math.round(r * 255),
-    g: Math.round(g * 255),
-    b: Math.round(bl * 255),
+    r: Math.round(fn(5) * 255),
+    g: Math.round(fn(3) * 255),
+    b: Math.round(fn(1) * 255),
   };
 }
 
-function getOklchHueName(l: number, c: number, h: number): [string, number] {
+function getOklchHueName(l: number, c: number, h: number, locale: string): [string, number] {
   if (c < GRAY_THRESHOLD) {
-    return ["gray", l];
+    return [getColorStringForLocale("gray", locale), l];
   }
 
   for (let i = 0; i < OKLCH_HUES.length; i += 1) {
@@ -280,27 +229,29 @@ function getOklchHueName(l: number, c: number, h: number): [string, number] {
         hueName = "yellow green";
       }
 
-      return [hueName.toLocaleLowerCase(), l];
+      const name = getColorStringForLocale(hueName as ColorStringKey, locale).toLocaleLowerCase(
+        locale
+      );
+      return [name, l];
     }
   }
 
-  return ["pink", l];
+  return [getColorStringForLocale("pink", locale).toLocaleLowerCase(locale), l];
 }
 
-function getColorNameFromColor(color: Color): string {
+function getColorNameFromColor(color: Color, locale: string): string {
   let [l, c, h] = toOKLCH(color);
-  const alpha = color.getChannelValue("alpha");
 
   if (l > 0.999) {
-    return alpha < 1 ? `white ${Math.round((1 - alpha) * 100)}% transparent` : "white";
+    return getColorStringForLocale("white", locale);
   }
 
   if (l < 0.001) {
-    return alpha < 1 ? `black ${Math.round((1 - alpha) * 100)}% transparent` : "black";
+    return getColorStringForLocale("black", locale);
   }
 
   let hue: string;
-  [hue, l] = getOklchHueName(l, c, h);
+  [hue, l] = getOklchHueName(l, c, h, locale);
 
   let chroma = "";
   if (c <= 0.1 && c >= GRAY_THRESHOLD) {
@@ -322,17 +273,34 @@ function getColorNameFromColor(color: Color): string {
     lightness = "very light";
   }
 
-  const name = [lightness, chroma, hue].filter(Boolean).join(" ").replace(/\s+/g, " ").trim();
-  if (alpha < 1) {
-    return `${Math.round((1 - alpha) * 100)}% transparent ${name}`.trim();
+  if (chroma) {
+    chroma = getColorStringForLocale(chroma as ColorStringKey, locale);
+  }
+  if (lightness) {
+    lightness = getColorStringForLocale(lightness as ColorStringKey, locale);
   }
 
-  return name;
+  const alpha = color.getChannelValue("alpha");
+  if (alpha < 1) {
+    const percentTransparent = new Intl.NumberFormat(locale, { style: "percent" }).format(1 - alpha);
+    return formatColorMessage("transparentColorName", locale, {
+      lightness,
+      chroma,
+      hue,
+      percentTransparent,
+    })
+      .replace(/\s+/g, " ")
+      .trim();
+  }
+
+  return formatColorMessage("colorName", locale, { lightness, chroma, hue })
+    .replace(/\s+/g, " ")
+    .trim();
 }
 
-function getHueNameFromColor(color: Color): string {
+function getHueNameFromColor(color: Color, locale: string): string {
   const [l, c, h] = toOKLCH(color);
-  const [name] = getOklchHueName(l, c, h);
+  const [name] = getOklchHueName(l, c, h, locale);
   return name;
 }
 
@@ -543,8 +511,8 @@ class RGBColorImpl implements Color {
     }
   }
 
-  getChannelName(channel: ColorChannel, _locale: string): string {
-    return CHANNEL_NAMES[channel] || channel;
+  getChannelName(channel: ColorChannel, locale: string): string {
+    return getColorStringForLocale(channel as ColorStringKey, locale);
   }
 
   getChannelFormatOptions(channel: ColorChannel): Intl.NumberFormatOptions {
@@ -576,12 +544,12 @@ class RGBColorImpl implements Color {
     return ["red", "green", "blue"];
   }
 
-  getColorName(_locale: string): string {
-    return getColorNameFromColor(this);
+  getColorName(locale: string): string {
+    return getColorNameFromColor(this, locale);
   }
 
-  getHueName(_locale: string): string {
-    return getHueNameFromColor(this);
+  getHueName(locale: string): string {
+    return getHueNameFromColor(this, locale);
   }
 }
 
@@ -595,9 +563,11 @@ class HSLColorImpl implements Color {
   private alpha: number;
 
   constructor(hue: number, saturation: number, lightness: number, alpha: number = 1) {
-    this.hue = clamp(Math.round(hue) % 360, 0, 360);
-    this.saturation = clamp(Math.round(saturation), 0, 100);
-    this.lightness = clamp(Math.round(lightness), 0, 100);
+    // Store raw like upstream HSLColor's constructor — precision comes from the
+    // conversion (toFixed(_, 2)); rounding to integers here diverged from S2.
+    this.hue = clamp(hue % 360, 0, 360);
+    this.saturation = clamp(saturation, 0, 100);
+    this.lightness = clamp(lightness, 0, 100);
     this.alpha = clamp(toFixed(alpha, 2), 0, 1);
   }
 
@@ -711,8 +681,8 @@ class HSLColorImpl implements Color {
     }
   }
 
-  getChannelName(channel: ColorChannel, _locale: string): string {
-    return CHANNEL_NAMES[channel] || channel;
+  getChannelName(channel: ColorChannel, locale: string): string {
+    return getColorStringForLocale(channel as ColorStringKey, locale);
   }
 
   getChannelFormatOptions(channel: ColorChannel): Intl.NumberFormatOptions {
@@ -750,12 +720,12 @@ class HSLColorImpl implements Color {
     return ["hue", "saturation", "lightness"];
   }
 
-  getColorName(_locale: string): string {
-    return getColorNameFromColor(this);
+  getColorName(locale: string): string {
+    return getColorNameFromColor(this, locale);
   }
 
-  getHueName(_locale: string): string {
-    return getHueNameFromColor(this);
+  getHueName(locale: string): string {
+    return getHueNameFromColor(this, locale);
   }
 }
 
@@ -769,9 +739,10 @@ class HSBColorImpl implements Color {
   private alpha: number;
 
   constructor(hue: number, saturation: number, brightness: number, alpha: number = 1) {
-    this.hue = clamp(Math.round(hue) % 360, 0, 360);
-    this.saturation = clamp(Math.round(saturation), 0, 100);
-    this.brightness = clamp(Math.round(brightness), 0, 100);
+    // Store raw like upstream HSBColor's constructor (see HSLColorImpl).
+    this.hue = clamp(hue % 360, 0, 360);
+    this.saturation = clamp(saturation, 0, 100);
+    this.brightness = clamp(brightness, 0, 100);
     this.alpha = clamp(toFixed(alpha, 2), 0, 1);
   }
 
@@ -884,8 +855,8 @@ class HSBColorImpl implements Color {
     }
   }
 
-  getChannelName(channel: ColorChannel, _locale: string): string {
-    return CHANNEL_NAMES[channel] || channel;
+  getChannelName(channel: ColorChannel, locale: string): string {
+    return getColorStringForLocale(channel as ColorStringKey, locale);
   }
 
   getChannelFormatOptions(channel: ColorChannel): Intl.NumberFormatOptions {
@@ -923,12 +894,12 @@ class HSBColorImpl implements Color {
     return ["hue", "saturation", "brightness"];
   }
 
-  getColorName(_locale: string): string {
-    return getColorNameFromColor(this);
+  getColorName(locale: string): string {
+    return getColorNameFromColor(this, locale);
   }
 
-  getHueName(_locale: string): string {
-    return getHueNameFromColor(this);
+  getHueName(locale: string): string {
+    return getHueNameFromColor(this, locale);
   }
 }