new: list-state primitive for Solid 2.0

packages/list-state/CHANGELOG.md

@@ -0,0 +1,20 @@
+# @solid-primitives/list-state
+
+## 0.1.0
+
+### Initial Release
+
+- Added `createListState` - Single-select list with keyboard navigation
+- Added `createMultiSelectListState` - Multi-select list with cursor-based navigation and range selection
+- Full keyboard support: Arrow keys, Vim bindings (hjkl), Home/End, Tab
+- Configurable orientation: Vertical or horizontal lists
+- Bidirectional text: RTL and LTR support
+- List looping: Optional looping at list boundaries
+- Range selection: Shift+Arrow for multi-select range expansion
+- Type-safe: Full TypeScript support with generic item types
+- SSR-safe: Works in both browser and server environments
+- Zero dependencies: Relies only on Solid.js primitives
+
+### Credits
+
+Adapted from [corvu's solid-list](https://github.com/corvudev/corvu/tree/main/packages/solid-list) by [Jasmin Noetzli](https://github.com/GiyoMoon) and migrated to Solid Primitives for Solid 2.0. Used under the MIT License.

packages/list-state/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2024 Solid Core Team
+Copyright (c) 2023-2025 Jasmin Noetzli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This package includes code adapted from corvu's solid-list
+(https://github.com/corvudev/corvu/tree/main/packages/solid-list)
+which is also licensed under the MIT License.

packages/list-state/README.md

@@ -0,0 +1,232 @@
+<p>
+  <img width="100%" src="https://assets.solidjs.com/banner?type=Primitives&background=tiles&project=list-state" alt="Solid Primitives list-state">
+</p>
+
+# @solid-primitives/list-state
+
+[![size](https://img.shields.io/bundlephobia/minzip/@solid-primitives/list-state?style=for-the-badge&label=size)](https://bundlephobia.com/package/@solid-primitives/list-state)
+[![version](https://img.shields.io/npm/v/@solid-primitives/list-state?style=for-the-badge)](https://www.npmjs.com/package/@solid-primitives/list-state)
+[![stage](https://img.shields.io/endpoint?style=for-the-badge&url=https%3A%2F%2Fraw.githubusercontent.com%2Fsolidjs-community%2Fsolid-primitives%2Fmain%2Fassets%2Fbadges%2Fstage-1.json)](https://github.com/solidjs-community/solid-primitives#contribution-process)
+
+Primitives for managing keyboard-navigable list state. Provides accessible, fully-featured list state management with support for single-select and multi-select patterns.
+
+- [`createListState`](#createliststate) — Single-select list with keyboard navigation
+- [`createMultiSelectListState`](#createmultiselectliststate) — Multi-select list with cursor-based navigation and range selection
+
+## Installation
+
+```bash
+npm install @solid-primitives/list-state
+# or
+yarn add @solid-primitives/list-state
+# or
+pnpm add @solid-primitives/list-state
+```
+
+## Features
+
+- **Full keyboard support**: Arrow keys, Vim bindings (hjkl), Home/End, Tab
+- **Configurable orientation**: Vertical or horizontal lists
+- **Bidirectional text**: RTL and LTR support
+- **List looping**: Optional looping at list boundaries
+- **Range selection**: Shift+Arrow for multi-select range expansion
+- **Type-safe**: Full TypeScript support with generic item types
+- **SSR-safe**: Works in both browser and server environments
+- **Zero dependencies**: Relies only on Solid.js primitives
+
+## `createListState`
+
+A reactive primitive for single-select list navigation. Returns an `active` signal for the currently selected item and an `onKeyDown` handler for keyboard events.
+
+```ts
+import { createListState } from "@solid-primitives/list-state";
+import { createSignal } from "solid-js";
+
+export function MyList() {
+  const items = ["Apple", "Banana", "Cherry"];
+  const { active, setActive, onKeyDown } = createListState({
+    items,
+    initialActive: items[0],
+  });
+
+  return (
+    <ul role="listbox" onKeyDown={onKeyDown}>
+      {items.map((item) => (
+        <li
+          role="option"
+          aria-selected={active() === item}
+          onClick={() => setActive(item)}
+          class={{ selected: active() === item }}
+        >
+          {item}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### Props
+
+```ts
+interface ListStateProps<T> {
+  /** The items in the list. Should be in the same order as they appear in the DOM. */
+  items: MaybeAccessor<T[]>;
+
+  /** The initially active item. @default null */
+  initialActive?: T | null;
+
+  /** The orientation of the list. @default "vertical" */
+  orientation?: MaybeAccessor<"vertical" | "horizontal">;
+
+  /** Whether the list should loop. @default true */
+  loop?: MaybeAccessor<boolean>;
+
+  /** The text direction of the list. @default "ltr" */
+  textDirection?: MaybeAccessor<"ltr" | "rtl">;
+
+  /** Whether tab key presses should be handled. @default true */
+  handleTab?: MaybeAccessor<boolean>;
+
+  /** Whether vim movement key bindings should be used. @default false */
+  vimMode?: MaybeAccessor<boolean>;
+
+  /** The vim movement key bindings. @default { up: 'k', down: 'j', right: 'l', left: 'h' } */
+  vimKeys?: MaybeAccessor<{ up: string; down: string; right: string; left: string }>;
+
+  /** Callback fired when the active item changes. */
+  onActiveChange?: (active: T | null) => void;
+}
+```
+
+### Returns
+
+```ts
+interface ListStateReturn<T> {
+  active: Accessor<T | null>;
+  setActive: (value: T | null) => void;
+  onKeyDown: (event: KeyboardEvent) => void;
+}
+```
+
+### Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| <kbd>↑</kbd> / <kbd>↓</kbd> | Navigate vertically (or ← / → for horizontal) |
+| <kbd>Home</kbd> | Jump to first item |
+| <kbd>End</kbd> | Jump to last item |
+| <kbd>Tab</kbd> | Navigate forward (if `handleTab` is true) |
+| <kbd>Shift</kbd>+<kbd>Tab</kbd> | Navigate backward (if `handleTab` is true) |
+| <kbd>k</kbd> / <kbd>j</kbd> | Vim navigation (if `vimMode` is true) |
+
+## `createMultiSelectListState`
+
+A reactive primitive for multi-select list navigation with range selection. Maintains three separate states: `cursor` (focused item), `active` (range of focused items), and `selected` (user-selected items).
+
+```ts
+import { createMultiSelectListState } from "@solid-primitives/list-state";
+
+export function MyMultiSelectList() {
+  const items = ["Apple", "Banana", "Cherry"];
+  const { cursor, active, selected, setCursorActive, toggleSelected, onKeyDown } =
+    createMultiSelectListState({
+      items,
+    });
+
+  return (
+    <ul role="listbox" onKeyDown={onKeyDown}>
+      {items.map((item) => (
+        <li
+          role="option"
+          aria-selected={selected().includes(item)}
+          onClick={() => setCursorActive(item)}
+          onDoubleClick={() => toggleSelected(item)}
+          class={{
+            cursor: cursor() === item,
+            selected: selected().includes(item),
+          }}
+        >
+          {item}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### Props
+
+```ts
+interface MultiSelectListStateProps<T> {
+  // Same as ListStateProps<T>, plus:
+
+  /** The initially focused item (cursor). @default null */
+  initialCursor?: T | null;
+
+  /** The initially active items (range). @default [] */
+  initialActive?: T[];
+
+  /** The initially selected items. @default [] */
+  initialSelected?: T[];
+
+  /** Callback fired when the cursor changes. */
+  onCursorChange?: (cursor: T | null) => void;
+
+  /** Callback fired when the active items change. */
+  onActiveChange?: (active: T[]) => void;
+
+  /** Callback fired when the selected items change. */
+  onSelectedChange?: (selected: T[]) => void;
+}
+```
+
+### Returns
+
+```ts
+interface MultiSelectListStateReturn<T> {
+  cursor: Accessor<T | null>;
+  setCursor: (value: T | null) => void;
+  active: Accessor<T[]>;
+  setActive: (value: T[]) => void;
+  setCursorActive: (item: T | null) => void;
+  selected: Accessor<T[]>;
+  setSelected: (value: T[]) => void;
+  toggleSelected: (item: T) => void;
+  onKeyDown: (event: KeyboardEvent) => void;
+}
+```
+
+### Keyboard Shortcuts
+
+All shortcuts from `createListState` plus:
+
+| Key | Action |
+|-----|--------|
+| <kbd>Shift</kbd>+<kbd>↑</kbd> / <kbd>↓</kbd> | Expand/contract selection range |
+
+## Types
+
+```ts
+export type Orientation = "vertical" | "horizontal";
+export type TextDirection = "ltr" | "rtl";
+
+export type VimKeys = {
+  up: string;
+  down: string;
+  right: string;
+  left: string;
+};
+```
+
+## Server-Side Rendering
+
+Both primitives are fully SSR-safe and will work correctly in both browser and server environments.
+
+## Credits
+
+This primitive was adapted from [corvu's solid-list](https://github.com/corvudev/corvu/tree/main/packages/solid-list) by [Jasmin Noetzli](https://github.com/GiyoMoon) and migrated to Solid Primitives for Solid 2.0. Used under the MIT License.
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md)

packages/list-state/dev/index.tsx

@@ -0,0 +1,89 @@
+import { createListState, createMultiSelectListState } from "../src/index.js";
+
+const items = ["Apple", "Banana", "Cherry", "Date", "Elderberry"];
+
+export function SingleSelectDemo() {
+  const { active, onKeyDown } = createListState({
+    items: items,
+    initialActive: items[0],
+  });
+
+  return (
+    <div>
+      <h2>Single-Select List</h2>
+      <p>Active: {active()}</p>
+      <ul
+        role="listbox"
+        onKeyDown={onKeyDown}
+        style={{
+          border: "1px solid #ccc",
+          padding: "1rem",
+          "list-style": "none",
+        }}
+      >
+        {items.map((item) => (
+          <li
+            class={{
+              active: active() === item,
+            }}
+            style={{
+              padding: "0.5rem",
+              background: active() === item ? "#0066cc" : "transparent",
+              color: active() === item ? "white" : "black",
+              cursor: "pointer",
+            }}
+          >
+            {item}
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+
+export function MultiSelectDemo() {
+  const { cursor, active, selected, setCursorActive, toggleSelected, onKeyDown } =
+    createMultiSelectListState({
+      items: items,
+      initialCursor: items[0],
+    });
+
+  return (
+    <div>
+      <h2>Multi-Select List</h2>
+      <p>Cursor: {cursor()}</p>
+      <p>Selected: {selected().join(", ") || "None"}</p>
+      <ul
+        role="listbox"
+        onKeyDown={onKeyDown}
+        style={{
+          border: "1px solid #ccc",
+          padding: "1rem",
+          "list-style": "none",
+        }}
+      >
+        {items.map((item) => (
+          <li
+            class={{
+              cursor: cursor() === item,
+              selected: selected().includes(item),
+            }}
+            onClick={() => setCursorActive(item)}
+            onDoubleClick={() => toggleSelected(item)}
+            style={{
+              padding: "0.5rem",
+              background: cursor() === item ? "#0066cc" : selected().includes(item) ? "#cce5ff" : "transparent",
+              color: cursor() === item ? "white" : "black",
+              cursor: "pointer",
+            }}
+          >
+            {item}
+          </li>
+        ))}
+      </ul>
+      <p style={{ "font-size": "0.85em", color: "#666" }}>
+        Double-click to toggle selection
+      </p>
+    </div>
+  );
+}