@lilydesignsystem/react-headless 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -3,6 +3,37 @@
 The format is loosely based on [Keep a Changelog](https://keepachangelog.com/)
 and the package follows [Semantic Versioning](https://semver.org/).
 
+## 0.2.0 — 2026-09-21
+
+**`Listbox` and `IconButton` extended, additively, to support the
+`react-helpers` catalog's icon-button-triggered pickers depending on
+them instead of hand-rolling equivalent markup/keyboard logic** —
+porting the same change already made to `@lilydesignsystem/svelte-headless`.
+Both components had zero real consumers elsewhere in this
+491-component catalog (confirmed by search before changing either;
+`Listbox` had two doc-comment *mentions* as an example, no actual
+imports) — full suite (2679 tests) still green.
+
+- `IconButton` gains `baseClass` (default `"icon-button"`, unchanged)
+  and a forwarded ref (`React.forwardRef`) exposing the rendered
+  `<button>`. Its props interface now extends
+  `React.ButtonHTMLAttributes<HTMLButtonElement>` instead of a
+  `[key: string]: unknown` catch-all — restProps (`aria-haspopup`,
+  `aria-expanded`, `aria-controls`, `onKeyDown`, etc.) keep real types,
+  and `forwardRef`'s `Omit<P, "ref">` machinery no longer collapses
+  named properties on an indexed type during `.d.ts` generation (a
+  real build break this refactor hit and fixed, not a style choice).
+- `Listbox` gains an opt-in `navigation="active-descendant"` mode
+  (default remains `"roving-focus"`, byte-for-byte unchanged
+  behaviour): the root holds real focus and tracks a virtual cursor
+  (`aria-activedescendant`, a controlled/uncontrolled `activeIndex` +
+  `onActiveIndexChange`, mirroring Svelte's bindable `activeIndex`)
+  rather than moving DOM focus between options, plus `clamp` (vs.
+  wrap), `typeahead`, `pageSize` paging, `onActivate`/`onEscape`/
+  `onTabOut` callbacks, `baseClass`, `as` (root tag, default `"div"`),
+  and a forwarded ref. Same props interface fix as `IconButton`
+  (extends `React.HTMLAttributes<HTMLElement>`, no index signature).
+
 ## 0.1.0 — 2026-09-16
 
 **Package renamed: `lily-design-system-react-headless` → `@lilydesignsystem/react-headless`.** npm scoped packages

package/dist/index.d.ts

@@ -2724,23 +2724,17 @@ interface IconProps {
 }
 declare function Icon({ className, label, decorative, children, ...restProps }: IconProps): React__default.JSX.Element;
 
-interface IconButtonProps {
-    className?: string;
+interface IconButtonProps extends React__default.ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Base class token, replacing "icon-button" outright (not appended). */
+    baseClass?: string;
     /** aria-label for the icon button (required for accessibility) */
     label: string;
-    /** HTML button type */
-    type?: "button" | "submit" | "reset";
-    /** Whether the button is disabled */
-    disabled?: boolean;
     /** Toggle button pressed state (undefined = not a toggle) */
     pressed?: boolean;
-    /** Click event handler */
-    onClick?: (event: React__default.MouseEvent) => void;
     /** The icon content */
     children: React__default.ReactNode;
-    [key: string]: unknown;
 }
-declare function IconButton({ className, label, type, disabled, pressed, onClick, children, ...restProps }: IconButtonProps): React__default.JSX.Element;
+declare const IconButton: React__default.ForwardRefExoticComponent<IconButtonProps & React__default.RefAttributes<HTMLButtonElement>>;
 
 interface IconListProps {
     className?: string;
@@ -3192,15 +3186,37 @@ interface LineChartProps {
 }
 declare function LineChart({ className, label, children, ...restProps }: LineChartProps): React$1.JSX.Element;
 
-interface ListboxProps {
-    className?: string;
+interface ListboxProps extends React__default.HTMLAttributes<HTMLElement> {
+    /** Base class token, replacing "listbox" outright (not appended). */
+    baseClass?: string;
+    /** Root element tag. Default "div" (unchanged). */
+    as?: React__default.ElementType;
     /** Accessible label. */
     label: string;
     /** Option elements. */
     children: React__default.ReactNode;
-    [key: string]: unknown;
-}
-declare function Listbox({ className, label, children, ...restProps }: ListboxProps): React__default.JSX.Element;
+    /** Navigation/focus model. Default "roving-focus" (unchanged legacy behaviour). */
+    navigation?: "roving-focus" | "active-descendant";
+    /** Controlled virtual cursor position (active-descendant mode). */
+    activeIndex?: number;
+    /** Initial cursor when uncontrolled. Default -1. */
+    defaultActiveIndex?: number;
+    /** Fires on every cursor move (active-descendant mode). */
+    onActiveIndexChange?: (index: number) => void;
+    /** Arrow keys clamp instead of wrap (active-descendant mode). */
+    clamp?: boolean;
+    /** Printable-character typeahead (active-descendant mode). */
+    typeahead?: boolean;
+    /** PageUp/PageDown step size (active-descendant mode). */
+    pageSize?: number;
+    /** Enter/Space on the active option (active-descendant mode). */
+    onActivate?: (index: number) => void;
+    /** Escape pressed (active-descendant mode). */
+    onEscape?: () => void;
+    /** Tab pressed, called before the key is processed (active-descendant mode). */
+    onTabOut?: (event: React__default.KeyboardEvent) => void;
+}
+declare const Listbox: React__default.ForwardRefExoticComponent<ListboxProps & React__default.RefAttributes<HTMLElement>>;
 
 interface LoadingProps {
     className?: string;

package/dist/index.js

@@ -5858,31 +5858,37 @@ function Icon({
 }
 
 // components/IconButton.tsx
+import React29 from "react";
 import { jsx as jsx225 } from "react/jsx-runtime";
-function IconButton({
-  className = "",
-  label,
-  type = "button",
-  disabled = false,
-  pressed = void 0,
-  onClick = void 0,
-  children,
-  ...restProps
-}) {
-  return /* @__PURE__ */ jsx225(
-    "button",
-    {
-      className: `icon-button ${className}`,
-      type,
-      disabled,
-      "aria-label": label,
-      "aria-pressed": pressed,
-      onClick,
-      ...restProps,
-      children
-    }
-  );
-}
+var IconButton = React29.forwardRef(
+  function IconButton2({
+    className = "",
+    baseClass = "icon-button",
+    label,
+    type = "button",
+    disabled = false,
+    pressed = void 0,
+    onClick = void 0,
+    children,
+    ...restProps
+  }, ref) {
+    return /* @__PURE__ */ jsx225(
+      "button",
+      {
+        className: `${baseClass} ${className}`,
+        type,
+        disabled,
+        "aria-label": label,
+        "aria-pressed": pressed,
+        onClick,
+        ref,
+        ...restProps,
+        children
+      }
+    );
+  }
+);
+var IconButton_default = IconButton;
 
 // components/IconList.tsx
 import { jsx as jsx226 } from "react/jsx-runtime";
@@ -6758,60 +6764,170 @@ function LineChart({
 }
 
 // components/Listbox.tsx
-import { useRef as useRef5 } from "react";
+import React30, { useLayoutEffect, useRef as useRef5, useState as useState19 } from "react";
 import { jsx as jsx264 } from "react/jsx-runtime";
-function Listbox({
+var Listbox = React30.forwardRef(function Listbox2({
   className = "",
+  baseClass = "listbox",
+  as: Tag2 = "div",
   label,
   children,
+  navigation = "roving-focus",
+  activeIndex: controlledActiveIndex,
+  defaultActiveIndex = -1,
+  onActiveIndexChange,
+  clamp = false,
+  typeahead = false,
+  pageSize = 10,
+  onActivate,
+  onEscape,
+  onTabOut,
   ...restProps
-}) {
+}, forwardedRef) {
   const listRef = useRef5(null);
-  function handleKeyDown(event) {
-    if (!listRef.current) return;
-    const options = Array.from(
-      listRef.current.querySelectorAll("[role='option']")
-    );
+  const [uncontrolledActiveIndex, setUncontrolledActiveIndex] = useState19(defaultActiveIndex);
+  const activeIndex = controlledActiveIndex ?? uncontrolledActiveIndex;
+  const typeaheadBuffer = useRef5("");
+  const typeaheadTimer = useRef5(void 0);
+  function setRef(node) {
+    listRef.current = node;
+    if (typeof forwardedRef === "function") forwardedRef(node);
+    else if (forwardedRef) forwardedRef.current = node;
+  }
+  function setActiveIndex(next) {
+    if (controlledActiveIndex === void 0) setUncontrolledActiveIndex(next);
+    onActiveIndexChange?.(next);
+  }
+  function options() {
+    return listRef.current ? Array.from(listRef.current.querySelectorAll("[role='option']")) : [];
+  }
+  function handleRovingFocusKeyDown(event) {
+    const opts = options();
     const current = document.activeElement;
-    const index = options.indexOf(current);
+    const index = opts.indexOf(current);
     switch (event.key) {
       case "ArrowDown": {
         event.preventDefault();
-        const next = index < options.length - 1 ? index + 1 : 0;
-        options[next]?.focus();
+        const next = index < opts.length - 1 ? index + 1 : 0;
+        opts[next]?.focus();
         break;
       }
       case "ArrowUp": {
         event.preventDefault();
-        const prev = index > 0 ? index - 1 : options.length - 1;
-        options[prev]?.focus();
+        const prev = index > 0 ? index - 1 : opts.length - 1;
+        opts[prev]?.focus();
         break;
       }
       case "Home": {
         event.preventDefault();
-        options[0]?.focus();
+        opts[0]?.focus();
         break;
       }
       case "End": {
         event.preventDefault();
-        options[options.length - 1]?.focus();
+        opts[opts.length - 1]?.focus();
         break;
       }
     }
   }
+  function moveActive(delta) {
+    const count = options().length;
+    if (count === 0) return;
+    const next = activeIndex + delta;
+    setActiveIndex(clamp ? Math.min(Math.max(next, 0), count - 1) : (next % count + count) % count);
+  }
+  function runTypeahead(char) {
+    const opts = options();
+    if (opts.length === 0) return;
+    const lower = char.toLowerCase();
+    const buffer = typeaheadBuffer.current;
+    const sameCharRun = buffer === "" || [...buffer].every((c) => c === lower);
+    typeaheadBuffer.current += lower;
+    clearTimeout(typeaheadTimer.current);
+    typeaheadTimer.current = setTimeout(() => typeaheadBuffer.current = "", 500);
+    const query = sameCharRun ? lower : typeaheadBuffer.current;
+    const anchor = activeIndex < 0 ? 0 : activeIndex;
+    const start = sameCharRun ? anchor + 1 : anchor;
+    for (let n = 0; n < opts.length; n++) {
+      const i = (start + n) % opts.length;
+      if ((opts[i].textContent ?? "").trim().toLowerCase().startsWith(query)) {
+        setActiveIndex(i);
+        return;
+      }
+    }
+  }
+  function handleActiveDescendantKeyDown(event) {
+    switch (event.key) {
+      case "ArrowDown":
+        event.preventDefault();
+        moveActive(1);
+        break;
+      case "ArrowUp":
+        event.preventDefault();
+        moveActive(-1);
+        break;
+      case "Home":
+        event.preventDefault();
+        setActiveIndex(options().length ? 0 : -1);
+        break;
+      case "End":
+        event.preventDefault();
+        setActiveIndex(options().length - 1);
+        break;
+      case "PageDown":
+        event.preventDefault();
+        moveActive(pageSize);
+        break;
+      case "PageUp":
+        event.preventDefault();
+        moveActive(-pageSize);
+        break;
+      case "Enter":
+      case " ":
+        event.preventDefault();
+        if (activeIndex >= 0) onActivate?.(activeIndex);
+        break;
+      case "Escape":
+        event.preventDefault();
+        onEscape?.();
+        break;
+      case "Tab":
+        onTabOut?.(event);
+        break;
+      default:
+        if (typeahead && event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey) {
+          runTypeahead(event.key);
+        }
+    }
+  }
+  function handleKeyDown(event) {
+    if (navigation === "active-descendant") handleActiveDescendantKeyDown(event);
+    else handleRovingFocusKeyDown(event);
+  }
+  const [activeId, setActiveId] = useState19(void 0);
+  useLayoutEffect(() => {
+    if (navigation !== "active-descendant" || activeIndex < 0) {
+      setActiveId(void 0);
+      return;
+    }
+    setActiveId(options()[activeIndex]?.id || void 0);
+  });
   return /* @__PURE__ */ jsx264(
-    "div",
+    Tag2,
     {
-      className: `listbox ${className}`,
+      className: `${baseClass} ${className}`,
       role: "listbox",
       "aria-label": label,
-      ref: listRef,
+      tabIndex: navigation === "active-descendant" ? -1 : void 0,
+      "aria-activedescendant": activeId,
+      ref: setRef,
       onKeyDown: handleKeyDown,
       ...restProps,
       children
     }
   );
-}
+});
+var Listbox_default = Listbox;
 
 // components/Loading.tsx
 import { jsx as jsx265 } from "react/jsx-runtime";
@@ -7082,7 +7198,7 @@ function MeasurementUnitView({
 }
 
 // components/MedicalBanner.tsx
-import { useState as useState19 } from "react";
+import { useState as useState20 } from "react";
 import { Fragment as Fragment29, jsx as jsx277, jsxs as jsxs48 } from "react/jsx-runtime";
 function MedicalBanner({
   className = "",
@@ -7094,7 +7210,7 @@ function MedicalBanner({
   children,
   ...restProps
 }) {
-  const [visible, setVisible] = useState19(true);
+  const [visible, setVisible] = useState20(true);
   function dismiss() {
     setVisible(false);
     onClose?.();
@@ -8251,7 +8367,7 @@ function PasswordInput({
 }
 
 // components/PasswordInputOrTextInputDiv.tsx
-import { useState as useState20 } from "react";
+import { useState as useState21 } from "react";
 import { jsx as jsx324, jsxs as jsxs53 } from "react/jsx-runtime";
 function PasswordInputOrTextInputDiv({
   className = "",
@@ -8264,7 +8380,7 @@ function PasswordInputOrTextInputDiv({
   onChange,
   ...restProps
 }) {
-  const [visible, setVisible] = useState20(false);
+  const [visible, setVisible] = useState21(false);
   return /* @__PURE__ */ jsxs53(
     "div",
     {
@@ -8387,7 +8503,7 @@ function Pictogram({
 }
 
 // components/PinInputDiv.tsx
-import { useState as useState21, useRef as useRef8, useEffect as useEffect3 } from "react";
+import { useState as useState22, useRef as useRef8, useEffect as useEffect3 } from "react";
 import { jsx as jsx329 } from "react/jsx-runtime";
 function PinInputDiv({
   className = "",
@@ -8398,7 +8514,7 @@ function PinInputDiv({
   onChange,
   ...restProps
 }) {
-  const [digits, setDigits] = useState21(() => Array.from({ length }, () => ""));
+  const [digits, setDigits] = useState22(() => Array.from({ length }, () => ""));
   const inputRefs = useRef8([]);
   useEffect3(() => {
     const combined = digits.join("");
@@ -8989,7 +9105,7 @@ function RadioGroup({
 }
 
 // components/RadioInput.tsx
-import { useState as useState22 } from "react";
+import { useState as useState23 } from "react";
 import { jsx as jsx352 } from "react/jsx-runtime";
 function RadioInput({
   className = "",
@@ -9001,7 +9117,7 @@ function RadioInput({
   onChange,
   ...restProps
 }) {
-  const [checked, setChecked] = useState22(checkedProp);
+  const [checked, setChecked] = useState23(checkedProp);
   const handleChange = (e) => {
     setChecked(e.target.checked);
     onChange?.(e);
@@ -9898,7 +10014,7 @@ function SharePage({
 }
 
 // components/Sheet.tsx
-import { useState as useState23 } from "react";
+import { useState as useState24 } from "react";
 import { Fragment as Fragment34, jsx as jsx387 } from "react/jsx-runtime";
 function Sheet({
   className = "",
@@ -9909,7 +10025,7 @@ function Sheet({
   children,
   ...restProps
 }) {
-  const [open, setOpen] = useState23(openProp);
+  const [open, setOpen] = useState24(openProp);
   function handleKeyDown(event) {
     if (event.key === "Escape") {
       event.preventDefault();
@@ -10011,7 +10127,7 @@ function SkipLink({
 }
 
 // components/SlideOutDrawer.tsx
-import { useState as useState24 } from "react";
+import { useState as useState25 } from "react";
 import { Fragment as Fragment36, jsx as jsx392 } from "react/jsx-runtime";
 function SlideOutDrawer({
   className = "",
@@ -10021,7 +10137,7 @@ function SlideOutDrawer({
   children,
   ...restProps
 }) {
-  const [open, setOpen] = useState24(openProp);
+  const [open, setOpen] = useState25(openProp);
   function handleKeyDown(event) {
     if (event.key === "Escape") {
       setOpen(false);
@@ -10074,7 +10190,7 @@ function Slider({
 }
 
 // components/SliderButton.tsx
-import { useState as useState25 } from "react";
+import { useState as useState26 } from "react";
 import { jsx as jsx394 } from "react/jsx-runtime";
 function SliderButton({
   className = "",
@@ -10085,7 +10201,7 @@ function SliderButton({
   children,
   ...restProps
 }) {
-  const [position, setPosition] = useState25(0);
+  const [position, setPosition] = useState26(0);
   const fireIfComplete = (next) => {
     if (next >= 100) {
       setPosition(0);
@@ -10819,7 +10935,7 @@ function SverigePersonnummerView({
 }
 
 // components/SwitchButton.tsx
-import { useEffect as useEffect6, useState as useState26 } from "react";
+import { useEffect as useEffect6, useState as useState27 } from "react";
 import { jsx as jsx422 } from "react/jsx-runtime";
 function SwitchButton({
   className = "",
@@ -10829,7 +10945,7 @@ function SwitchButton({
   onChange,
   ...restProps
 }) {
-  const [checked, setChecked] = useState26(checkedProp);
+  const [checked, setChecked] = useState27(checkedProp);
   useEffect6(() => {
     setChecked(checkedProp);
   }, [checkedProp]);
@@ -11269,7 +11385,7 @@ function TaskList({
 }
 
 // components/TaskListItem.tsx
-import { useState as useState27 } from "react";
+import { useState as useState28 } from "react";
 import { jsx as jsx439, jsxs as jsxs71 } from "react/jsx-runtime";
 function TaskListItem({
   className = "",
@@ -11279,7 +11395,7 @@ function TaskListItem({
   onChange,
   ...restProps
 }) {
-  const [checked, setChecked] = useState27(checkedProp);
+  const [checked, setChecked] = useState28(checkedProp);
   const handleChange = (e) => {
     const newChecked = e.target.checked;
     setChecked(newChecked);
@@ -11845,7 +11961,7 @@ function Timer({
 }
 
 // components/TimerButton.tsx
-import { useEffect as useEffect7, useRef as useRef14, useState as useState28 } from "react";
+import { useEffect as useEffect7, useRef as useRef14, useState as useState29 } from "react";
 import { jsx as jsx458 } from "react/jsx-runtime";
 function TimerButton({
   className = "",
@@ -11856,7 +11972,7 @@ function TimerButton({
   children,
   ...restProps
 }) {
-  const [remainingSeconds, setRemainingSeconds] = useState28(duration);
+  const [remainingSeconds, setRemainingSeconds] = useState29(duration);
   const firedRef = useRef14(false);
   useEffect7(() => {
     if (disabled) return;
@@ -11917,7 +12033,7 @@ function Toast({
 }
 
 // components/ToggleButton.tsx
-import { useState as useState29 } from "react";
+import { useState as useState30 } from "react";
 import { Fragment as Fragment37, jsx as jsx460 } from "react/jsx-runtime";
 function ToggleButton({
   className = "",
@@ -11928,7 +12044,7 @@ function ToggleButton({
   children,
   ...restProps
 }) {
-  const [pressed, setPressed] = useState29(pressedProp);
+  const [pressed, setPressed] = useState30(pressedProp);
   function toggle() {
     if (!disabled) {
       const newPressed = !pressed;
@@ -12696,7 +12812,7 @@ function VideoPlayer({
 }
 
 // components/Visible.tsx
-import { useEffect as useEffect9, useRef as useRef18, useState as useState30 } from "react";
+import { useEffect as useEffect9, useRef as useRef18, useState as useState31 } from "react";
 import { jsx as jsx487 } from "react/jsx-runtime";
 function Visible({
   className = "",
@@ -12707,7 +12823,7 @@ function Visible({
   ...restProps
 }) {
   const ref = useRef18(null);
-  const [visible, setVisible] = useState30(false);
+  const [visible, setVisible] = useState31(false);
   useEffect9(() => {
     const el = ref.current;
     if (!el || typeof IntersectionObserver === "undefined") return;
@@ -13044,7 +13160,7 @@ export {
   HrvatskaOsobniIdentifikacijskiBrojInput,
   HrvatskaOsobniIdentifikacijskiBrojView,
   Icon,
-  IconButton,
+  IconButton_default as IconButton,
   IconList,
   IconListItem,
   Image,
@@ -13083,7 +13199,7 @@ export {
   LietuvaPasasInput,
   LietuvaPasasView,
   LineChart,
-  Listbox,
+  Listbox_default as Listbox,
   Loading,
   MaltaNationalIdentificationNumberInput,
   MaltaNationalIdentificationNumberView,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lilydesignsystem/react-headless",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "engines": {
     "node": "=26"
   },
@@ -38,20 +38,20 @@
   },
   "homepage": "https://lilydesignsystem.com/",
   "devDependencies": {
-    "@storybook/react-vite": "^10.5.10",
+    "@storybook/react-vite": "^10.6.0",
     "@testing-library/react": "^16.3.3",
     "@testing-library/user-event": "^14.6.7",
-    "@types/react": "^19.2.18",
-    "@types/react-dom": "^19.2.5",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "@vitejs/plugin-react": "^6.1.1",
-    "@vitest/ui": "^4.1.11",
+    "@vitest/ui": "^5.0.0",
     "jsdom": "^30.0.1",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
-    "storybook": "^10.5.10",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "storybook": "^10.6.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",