@proyecto-viviana/solid-stately 0.2.7 → 0.4.0

package/README.md

@@ -1,113 +1,23 @@
 # @proyecto-viviana/solid-stately
 
-A SolidJS port of [React Stately](https://react-spectrum.adobe.com/react-stately/) - headless state management for UI components.
+SolidJS port of React Stately state primitives.
 
-## Installation
+This package is the state layer below `solidaria` and
+`solidaria-components`. It owns controlled/uncontrolled state, collection
+models, selection, date/time state, validation state, and related utilities.
+
+## Install
 
 ```bash
-bun add @proyecto-viviana/solid-stately solid-js
+npm install @proyecto-viviana/solid-stately solid-js
 ```
 
-## Overview
-
-solid-stately provides state management hooks that handle the complex logic for UI components like toggles, selections, overlays, and collections. These hooks return reactive state and update functions that you can use with any UI.
-
-This package is the foundation layer of the Proyecto Viviana component library, providing the state logic that powers the accessibility hooks in `@proyecto-viviana/solidaria`.
-
-## Available Hooks
-
-### Toggle & Selection
-
-| Hook | Description |
-|------|-------------|
-| `createToggleState` | Boolean toggle state for checkboxes, switches |
-| `createCheckboxGroupState` | Multi-selection checkbox group |
-| `createRadioGroupState` | Single-selection radio group |
-
-### Overlays
-
-| Hook | Description |
-|------|-------------|
-| `createOverlayTriggerState` | Open/close state for modals, popovers, menus |
-
-### Collections & Lists
-
-| Hook | Description |
-|------|-------------|
-| `createListState` | List with selection and keyboard focus |
-| `createSingleSelectListState` | Single-selection list (e.g., for select dropdowns) |
-| `createSelectionState` | Low-level selection management |
-| `createMenuState` | Menu state with action support |
-| `createMenuTriggerState` | Menu trigger open/close state |
-| `createSelectState` | Select dropdown state |
-| `ListCollection` | Collection data structure for lists |
-| `createListCollection` | Create a list collection from items |
-
-### Navigation
-
-| Hook | Description |
-|------|-------------|
-| `createTabListState` | Tab navigation state with keyboard support |
-
-### Form Controls
-
-| Hook | Description |
-|------|-------------|
-| `createTextFieldState` | Text input state |
-| `createNumberFieldState` | Numeric input with validation |
-| `createSearchFieldState` | Search input with clear functionality |
-| `createSliderState` | Range slider state |
-| `createFormValidationState` | Form validation state with realtime/native modes |
-
-### Grid & Table
-
-| Hook | Description |
-|------|-------------|
-| `createGridState` | Grid state with keyboard navigation |
-| `createTableState` | Table state with sorting and selection |
-| `TableCollection` | Collection data structure for tables |
-
-### Tree
-
-| Hook | Description |
-|------|-------------|
-| `createTreeState` | Tree state with expand/collapse |
-| `TreeCollection` | Collection data structure for trees |
-
-### Color
-
-| Hook | Description |
-|------|-------------|
-| `createColorSliderState` | Color channel slider state |
-| `createColorAreaState` | 2D color area picker state |
-| `createColorWheelState` | Circular hue wheel state |
-| `createColorFieldState` | Color text input state |
-
-### Drag & Drop
-
-| Hook | Description |
-|------|-------------|
-| `createDragState` | Drag operation state |
-| `createDropState` | Drop target state |
-| `createDraggableCollectionState` | Collection-level drag state |
-| `createDroppableCollectionState` | Collection-level drop state |
-
-### Utilities
-
-| Hook | Description |
-|------|-------------|
-| `createId` | Generate unique IDs (SSR-safe) |
-| `createIsSSR` | Detect server-side rendering |
-| `canUseDOM` | Check if DOM is available |
-
-## Usage Examples
-
-### Toggle State
+## Usage
 
 ```tsx
-import { createToggleState } from '@proyecto-viviana/solid-stately';
+import { createToggleState } from "@proyecto-viviana/solid-stately";
 
-function Checkbox(props) {
+export function Toggle(props) {
   const state = createToggleState({
     isSelected: props.isSelected,
     defaultSelected: props.defaultSelected,
@@ -115,198 +25,35 @@ function Checkbox(props) {
   });
 
   return (
-    <label>
-      <input
-        type="checkbox"
-        checked={state.isSelected()}
-        onChange={() => state.toggle()}
-      />
+    <button aria-pressed={state.isSelected()} onClick={() => state.toggle()}>
       {props.children}
-    </label>
+    </button>
   );
 }
 ```
 
-### List State with Selection
-
-```tsx
-import { createListState } from '@proyecto-viviana/solid-stately';
-
-function ListBox(props) {
-  const state = createListState({
-    items: props.items,
-    getKey: (item) => item.id,
-    getTextValue: (item) => item.name,
-    selectionMode: 'single',
-    onSelectionChange: props.onSelectionChange,
-  });
-
-  return (
-    <ul>
-      <For each={props.items}>
-        {(item) => {
-          const key = item.id;
-          const isSelected = () => state.selectionManager.isSelected(key);
-          
-          return (
-            <li
-              onClick={() => state.selectionManager.toggleSelection(key)}
-              style={{ background: isSelected() ? 'blue' : 'white' }}
-            >
-              {item.name}
-            </li>
-          );
-        }}
-      </For>
-    </ul>
-  );
-}
-```
+## Public Surface
 
-### Overlay State
+The source of truth is [`src/index.ts`](src/index.ts). Keep this README focused
+on package purpose and verification rather than duplicating the full export
+list.
 
-```tsx
-import { createOverlayTriggerState } from '@proyecto-viviana/solid-stately';
+Major areas currently covered:
 
-function Modal(props) {
-  const state = createOverlayTriggerState({
-    isOpen: props.isOpen,
-    defaultOpen: props.defaultOpen,
-    onOpenChange: props.onOpenChange,
-  });
+- toggles, checkbox groups, radio groups, and disclosure;
+- overlays, tooltips, toasts, forms, and validation;
+- collections, selection, menus, selects, combo boxes, tabs;
+- grid, table, tree, list data, and async list helpers;
+- date/time/calendar state and internationalized date helpers;
+- number fields, search fields, sliders, and color state;
+- drag-and-drop state and SSR utilities.
 
-  return (
-    <>
-      <button onClick={() => state.open()}>Open Modal</button>
-      <Show when={state.isOpen()}>
-        <div class="modal">
-          {props.children}
-          <button onClick={() => state.close()}>Close</button>
-        </div>
-      </Show>
-    </>
-  );
-}
-```
+## Verification
 
-### Tab State
-
-```tsx
-import { createTabListState } from '@proyecto-viviana/solid-stately';
-
-function Tabs(props) {
-  const state = createTabListState({
-    items: props.tabs,
-    getKey: (tab) => tab.id,
-    selectedKey: props.selectedKey,
-    onSelectionChange: props.onSelectionChange,
-  });
-
-  return (
-    <div>
-      <div role="tablist">
-        <For each={props.tabs}>
-          {(tab) => (
-            <button
-              role="tab"
-              aria-selected={state.selectedKey() === tab.id}
-              onClick={() => state.setSelectedKey(tab.id)}
-            >
-              {tab.label}
-            </button>
-          )}
-        </For>
-      </div>
-      <div role="tabpanel">
-        {props.tabs.find(t => t.id === state.selectedKey())?.content}
-      </div>
-    </div>
-  );
-}
-```
-
-### Slider State
-
-```tsx
-import { createSliderState } from '@proyecto-viviana/solid-stately';
-
-function Slider(props) {
-  const state = createSliderState({
-    value: props.value,
-    defaultValue: props.defaultValue ?? 50,
-    minValue: props.minValue ?? 0,
-    maxValue: props.maxValue ?? 100,
-    step: props.step ?? 1,
-    onChange: props.onChange,
-  });
-
-  const percent = () => state.getValuePercent() * 100;
-
-  return (
-    <div>
-      <input
-        type="range"
-        min={state.minValue}
-        max={state.maxValue}
-        step={state.step}
-        value={state.value()}
-        onInput={(e) => state.setValue(parseFloat(e.target.value))}
-      />
-      <span>{state.getFormattedValue()}</span>
-    </div>
-  );
-}
-```
-
-## Key Concepts
-
-### Controlled vs Uncontrolled
-
-All state hooks support both controlled and uncontrolled patterns:
-
-```tsx
-// Uncontrolled - uses internal state
-const state = createToggleState({
-  defaultSelected: false,
-  onChange: (isSelected) => console.log('Changed:', isSelected),
-});
-
-// Controlled - uses external state
-const [isSelected, setIsSelected] = createSignal(false);
-const state = createToggleState({
-  isSelected: isSelected(),
-  onChange: setIsSelected,
-});
-```
-
-### MaybeAccessor Pattern
-
-Props can be passed as values or accessors for reactive updates:
-
-```tsx
-// Static value
-createToggleState({ defaultSelected: true });
-
-// Reactive accessor
-createToggleState({ 
-  get isDisabled() { return props.isDisabled; } 
-});
-```
-
-## TypeScript
-
-All hooks are fully typed. Import types as needed:
-
-```tsx
-import { 
-  createListState,
-  type ListState,
-  type ListStateProps,
-  type Key,
-  type Selection,
-} from '@proyecto-viviana/solid-stately';
+```bash
+vp run --filter @proyecto-viviana/solid-stately build
+vp test run packages
 ```
 
-## License
-
-MIT
+State changes should include tests for controlled and uncontrolled use, default
+values, callbacks, validation, and disabled/read-only behavior where applicable.

package/dist/autocomplete/createAutocompleteState.d.ts

@@ -3,8 +3,8 @@
  *
  * Based on @react-stately/autocomplete useAutocompleteState.
  */
-import { type Accessor } from 'solid-js';
-import { type MaybeAccessor } from '../utils';
+import { type Accessor } from "solid-js";
+import { type MaybeAccessor } from "../utils";
 export interface AutocompleteState {
     /** The current value of the autocomplete input. */
     inputValue: Accessor<string>;

package/dist/autocomplete/index.d.ts

@@ -1 +1 @@
-export { createAutocompleteState, type AutocompleteState, type AutocompleteStateOptions, } from './createAutocompleteState';
+export { createAutocompleteState, type AutocompleteState, type AutocompleteStateOptions, } from "./createAutocompleteState";

package/dist/calendar/IncompleteDate.d.ts

@@ -0,0 +1,61 @@
+/**
+ * IncompleteDate for Solid-Stately
+ *
+ * Represents a date that is incomplete or otherwise invalid as a result of user
+ * editing (for example February 31st, if the day is edited before the month).
+ * This lets a date field hold an invalid intermediate value while typing and
+ * only constrain it on blur, matching upstream behavior.
+ *
+ * Based on @react-stately/datepicker IncompleteDate
+ */
+import { type AnyDateTime, type Calendar, type DateValue } from "@internationalized/date";
+import type { DateSegmentType } from "./createDateFieldState";
+type HourCycle = "h12" | "h11" | "h23" | "h24";
+/**
+ * This class represents a date that is incomplete or otherwise invalid as a result of user editing.
+ * For example, it can represent temporary dates such as February 31st if the user edits the day
+ * before the month. Times are represented according to an hour cycle rather than always in 24 hour
+ * time. This enables the user to adjust the day period (e.g. am/pm) independently from the hour.
+ */
+export declare class IncompleteDate {
+    calendar: Calendar;
+    era: string | null;
+    year: number | null;
+    month: number | null;
+    day: number | null;
+    hour: number | null;
+    hourCycle: HourCycle;
+    dayPeriod: number | null;
+    minute: number | null;
+    second: number | null;
+    millisecond: number | null;
+    offset: number | null;
+    constructor(calendar: Calendar, hourCycle: HourCycle, dateValue?: Partial<Omit<AnyDateTime, "copy">> | null);
+    copy(): IncompleteDate;
+    /** Checks whether all the specified segments have a value. */
+    isComplete(segments: DateSegmentType[]): boolean;
+    /** Checks whether the given date value matches this value for the specified segments. */
+    validate(dt: DateValue, segments: DateSegmentType[]): boolean;
+    /** Checks if the date is empty (i.e. all specified segments are null). */
+    isCleared(segments: DateSegmentType[]): boolean;
+    /** Sets the given field. */
+    set(field: DateSegmentType, value: number | string, placeholder: DateValue): IncompleteDate;
+    /** Sets the given field to null. */
+    clear(field: DateSegmentType): IncompleteDate;
+    /**
+     * Increments or decrements the given field. If it is null, then it is set to the placeholder
+     * value.
+     */
+    cycle(field: DateSegmentType, amount: number, placeholder: DateValue, displaySegments: DateSegmentType[]): IncompleteDate;
+    /**
+     * Converts the incomplete date to a full date value, using the provided value for any unset
+     * fields.
+     */
+    toValue(value: DateValue): DateValue;
+    getSegmentLimits(type: string): {
+        value: number | null;
+        minValue: number;
+        maxValue: number;
+    } | undefined;
+}
+export {};

package/dist/calendar/createCalendarState.d.ts

@@ -4,17 +4,24 @@
  * Provides state management for calendar components.
  * Based on @react-stately/calendar useCalendarState
  */
-import { type Accessor } from 'solid-js';
-import { type CalendarDate, type DateValue } from '@internationalized/date';
-import { type MaybeAccessor } from '../utils';
-export type ValidationState = 'valid' | 'invalid';
-export interface CalendarStateProps<T extends DateValue = DateValue> {
+import { type Accessor } from "solid-js";
+import { type Calendar as InternationalizedCalendar, type CalendarDate, type CalendarIdentifier, type DateValue } from "@internationalized/date";
+import { type MaybeAccessor } from "../utils";
+export type ValidationState = "valid" | "invalid";
+export type CalendarPageBehavior = "single" | "visible";
+export type CalendarSelectionAlignment = "start" | "center" | "end";
+export type CalendarDayOfWeek = "sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat";
+export type CalendarSelectionMode = "single" | "multiple";
+export type CalendarValueType<T, M extends CalendarSelectionMode> = M extends "single" ? T : readonly T[];
+export interface CalendarStateProps<T extends DateValue = DateValue, M extends CalendarSelectionMode = "single"> {
     /** The current value (controlled). */
-    value?: MaybeAccessor<T | null>;
+    value?: MaybeAccessor<CalendarValueType<T | null, M> | undefined>;
     /** The default value (uncontrolled). */
-    defaultValue?: T | null;
+    defaultValue?: CalendarValueType<T | null, M> | null;
     /** Handler called when the value changes. */
-    onChange?: (value: T) => void;
+    onChange?: (value: CalendarValueType<T | null, M>) => void;
+    /** Whether single or multiple date selection is enabled. */
+    selectionMode?: MaybeAccessor<M>;
     /** The minimum allowed date. */
     minValue?: MaybeAccessor<DateValue | undefined>;
     /** The maximum allowed date. */
@@ -26,17 +33,23 @@ export interface CalendarStateProps<T extends DateValue = DateValue> {
     /** Whether dates outside the visible range are automatically focused. */
     autoFocus?: boolean;
     /** The date that is focused when the calendar first mounts. */
-    focusedValue?: MaybeAccessor<DateValue | undefined>;
+    focusedValue?: MaybeAccessor<DateValue | null | undefined>;
     /** The default focused date (uncontrolled). */
     defaultFocusedValue?: DateValue;
     /** Handler called when the focused date changes. */
     onFocusChange?: (date: CalendarDate) => void;
     /** The locale to use for formatting. */
-    locale?: string;
+    locale?: MaybeAccessor<string | undefined>;
+    /** Creates a calendar object for a locale calendar identifier. */
+    createCalendar?: (identifier: CalendarIdentifier) => InternationalizedCalendar;
     /** Callback that is called for each date in the calendar to determine if it is unavailable. */
     isDateUnavailable?: (date: DateValue) => boolean;
     /** The number of months to display at once. */
     visibleMonths?: number;
+    /** Controls whether paging advances by one month or by the visible month range. */
+    pageBehavior?: CalendarPageBehavior;
+    /** Determines how the visible months align around the initial focused date. */
+    selectionAlignment?: CalendarSelectionAlignment;
     /** Whether to automatically focus the calendar when it is mounted. */
     autoFocusOnMount?: boolean;
     /** Controls which days are disabled. */
@@ -48,15 +61,21 @@ export interface CalendarStateProps<T extends DateValue = DateValue> {
     /** The first day of the week (0 = Sunday, 1 = Monday, etc.). */
     firstDayOfWeek?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
 }
-export interface CalendarState<T extends DateValue = DateValue> {
-    /** The currently selected date. */
-    value: Accessor<T | null>;
-    /** Sets the selected date. */
-    setValue: (value: T | null) => void;
+export interface CalendarState<T extends DateValue = DateValue, M extends CalendarSelectionMode = "single"> {
+    /** Whether single or multiple selection is enabled. */
+    selectionMode: Accessor<CalendarSelectionMode>;
+    /** The currently selected date(s). */
+    value: Accessor<CalendarValueType<T | null, M>>;
+    /** Sets the selected date(s). */
+    setValue: (value: CalendarValueType<T | null, M>) => void;
     /** The currently focused date. */
     focusedDate: Accessor<CalendarDate>;
     /** Sets the focused date. */
     setFocusedDate: (date: CalendarDate) => void;
+    /** The minimum allowed date that a user may select. */
+    minValue: Accessor<DateValue | null>;
+    /** The maximum allowed date that a user may select. */
+    maxValue: Accessor<DateValue | null>;
     /** Whether the calendar is disabled. */
     isDisabled: Accessor<boolean>;
     /** Whether the calendar is read-only. */
@@ -68,8 +87,14 @@ export interface CalendarState<T extends DateValue = DateValue> {
     }>;
     /** The timezone used for date calculations. */
     timeZone: string;
+    /** The locale used for formatting and locale-specific week starts. */
+    locale: Accessor<string>;
+    /** The explicitly requested first weekday, or undefined for the locale default. */
+    firstDayOfWeek: Accessor<CalendarDayOfWeek | undefined>;
     /** The validation state. */
     validationState: Accessor<ValidationState | undefined>;
+    /** Whether the current value is invalid according to validation state. */
+    isValueInvalid: Accessor<boolean>;
     /** Whether a date is selected. */
     isSelected: (date: DateValue) => boolean;
     /** Whether a date is focused. */
@@ -126,4 +151,4 @@ export interface CalendarState<T extends DateValue = DateValue> {
 /**
  * Provides state management for a calendar component.
  */
-export declare function createCalendarState<T extends DateValue = CalendarDate>(props?: CalendarStateProps<T>): CalendarState<T>;
+export declare function createCalendarState<T extends DateValue = CalendarDate, M extends CalendarSelectionMode = "single">(props?: CalendarStateProps<T, M>): CalendarState<T, M>;

package/dist/calendar/createDateFieldState.d.ts

@@ -3,19 +3,26 @@
  *
  * Provides state management for date field components with segment-based editing.
  * Based on @react-stately/datepicker useDateFieldState
+ *
+ * Editing is modeled with an {@link IncompleteDate} display value so that invalid
+ * intermediate dates (e.g. February 31st, produced by editing the day before the
+ * month) are held as-typed while the field is focused and only constrained on blur
+ * via `confirmPlaceholder`, matching upstream behavior. Out-of-range values are
+ * never snapped to `minValue`/`maxValue`; they are kept and reported as invalid.
  */
-import { type Accessor } from 'solid-js';
-import { type CalendarDate, type DateValue } from '@internationalized/date';
-import { type MaybeAccessor } from '../utils';
-import type { ValidationState } from './createCalendarState';
-export type DateSegmentType = 'year' | 'month' | 'day' | 'hour' | 'minute' | 'second' | 'dayPeriod' | 'era' | 'timeZoneName' | 'literal';
+import { type Accessor } from "solid-js";
+import { type CalendarDateTime, type DateValue } from "@internationalized/date";
+import { type MaybeAccessor } from "../utils";
+import type { ValidationState } from "./createCalendarState";
+import { type ValidationBehavior, type ValidationFunction, type ValidationResult } from "../form";
+export type DateSegmentType = "year" | "month" | "day" | "hour" | "minute" | "second" | "dayPeriod" | "era" | "timeZoneName" | "literal";
 export interface DateSegment {
     /** The type of segment. */
     type: DateSegmentType;
     /** The text content of the segment. */
     text: string;
     /** The numeric value of the segment (if applicable). */
-    value?: number;
+    value?: number | null;
     /** The minimum value for the segment. */
     minValue?: number;
     /** The maximum value for the segment. */
@@ -44,18 +51,26 @@ export interface DateFieldStateProps<T extends DateValue = DateValue> {
     isReadOnly?: MaybeAccessor<boolean>;
     /** Whether the field is required. */
     isRequired?: MaybeAccessor<boolean>;
+    /** Whether the value is invalid (controlled). */
+    isInvalid?: boolean;
     /** The locale to use for formatting. */
     locale?: string;
     /** The granularity of the date/time (day, hour, minute, second). */
-    granularity?: 'day' | 'hour' | 'minute' | 'second';
+    granularity?: "day" | "hour" | "minute" | "second";
     /** Whether to show the hour in 12 or 24 hour format. */
     hourCycle?: 12 | 24;
     /** Whether to hide the time zone. */
     hideTimeZone?: boolean;
     /** The placeholder date (determines segment structure). */
     placeholderValue?: DateValue;
+    /** Whether to force leading zeroes in month/day segments. */
+    shouldForceLeadingZeros?: boolean;
     /** Validation state. */
     validationState?: MaybeAccessor<ValidationState | undefined>;
+    /** Validation behavior mode. */
+    validationBehavior?: ValidationBehavior;
+    /** Custom validation function. */
+    validate?: ValidationFunction<T>;
     /** Description text. */
     description?: string;
     /** Error message. */
@@ -64,6 +79,8 @@ export interface DateFieldStateProps<T extends DateValue = DateValue> {
     allowsNonContiguousRanges?: boolean;
     /** Whether to create a date or datetime. */
     createCalendar?: (name: string) => unknown;
+    /** Whether a date is unavailable. */
+    isDateUnavailable?: (date: DateValue) => boolean;
 }
 export interface DateFieldState<T extends DateValue = DateValue> {
     /** The current value. */
@@ -95,15 +112,28 @@ export interface DateFieldState<T extends DateValue = DateValue> {
     /** The validation state. */
     validationState: Accessor<ValidationState | undefined>;
     /** The granularity. */
-    granularity: 'day' | 'hour' | 'minute' | 'second';
+    granularity: "day" | "hour" | "minute" | "second";
     /** Whether the value is invalid. */
     isInvalid: Accessor<boolean>;
+    /** Realtime validation results, including native and custom constraints. */
+    realtimeValidation: Accessor<ValidationResult>;
+    /** Currently displayed validation results. */
+    displayValidation: Accessor<ValidationResult>;
+    /** Updates the current validation result. */
+    updateValidation: (result: ValidationResult) => void;
+    /** Resets displayed validation to valid. */
+    resetValidation: () => void;
+    /** Commits realtime validation to displayed validation. */
+    commitValidation: () => void;
     /** The locale. */
     locale: string;
     /** The time zone. */
     timeZone: string;
+    /** The default value. */
+    defaultValue: T | null;
 }
 /**
  * Provides state management for a date field component.
  */
-export declare function createDateFieldState<T extends DateValue = CalendarDate>(props?: DateFieldStateProps<T>): DateFieldState<T>;
+export declare function createDateFieldState<T extends DateValue = DateValue>(props?: DateFieldStateProps<T>): DateFieldState<T>;
+export type { CalendarDateTime };