neatkit 0.9.0 → 0.10.0

package/dist/components/Select/Select.d.ts

@@ -1,78 +1,10 @@
-import { type ButtonHTMLAttributes, type CSSProperties, type ReactElement, type ReactNode, type RefAttributes, type SelectHTMLAttributes } from "react";
-import { type IconType } from "../Icon";
+import { type ReactElement, type RefAttributes } from "react";
+import { type CustomSelectProps } from "./components/CustomSelect";
+import { type NativeSelectProps } from "./components/NativeSelect";
 import "./styles/select.css";
-/** A type representing one option in a custom Select. */
-export type SelectOption = {
-    /** Whether the option is unavailable for selection. */
-    disabled?: boolean;
-    /** The optional icon displayed beside the option label. */
-    icon?: IconType;
-    /** The visible and accessible option label. */
-    label: string;
-    /** The form value represented by the option. */
-    value: string;
-};
-/** A type representing custom trigger content independent of selection. */
-export type SelectDisplayOverride = {
-    /** The optional icon displayed beside the trigger label. */
-    icon?: IconType;
-    /** The label displayed by the trigger. */
-    label: string;
-};
-/** A type representing the existing native Select mode properties. */
-export type NativeSelectProps = Omit<SelectHTMLAttributes<HTMLSelectElement>, "children" | "className" | "multiple" | "size" | "style"> & {
-    /** The native option and optgroup content displayed by the Select. */
-    children: ReactNode;
-    /** The additional class name applied to the composite Select root. */
-    className?: string;
-    /** Whether the Select exposes an invalid semantic and visual state. */
-    invalid?: boolean;
-    /** The disabled empty-value guidance displayed before selection. */
-    placeholder?: string;
-    /** The inline styles applied to the composite Select root. */
-    style?: CSSProperties;
-    /** Custom options select portal mode and cannot accompany children. */
-    options?: never;
-};
-/** A type representing the portal-backed custom Select mode properties. */
-export type CustomSelectProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" | "className" | "defaultValue" | "onChange" | "style" | "value"> & {
-    /** Whether an outside pointer interaction closes the listbox. */
-    closeOnOutsideInteraction?: boolean;
-    /** Whether the Escape key closes the listbox. */
-    closeOnEscape?: boolean;
-    /** The additional class name applied to the composite Select root. */
-    className?: string;
-    /** The initially selected value for uncontrolled usage. */
-    defaultValue?: string;
-    /** The optional content displayed independently from the selected option. */
-    displayOverride?: SelectDisplayOverride;
-    /** Whether the Select exposes an invalid semantic and visual state. */
-    invalid?: boolean;
-    /** The native form name submitted through the custom Select. */
-    name?: string;
-    /** The callback invoked with a newly selected option value. */
-    onChange?: (value: string) => void;
-    /** The callback invoked whenever the listbox opens or closes. */
-    onOpenChange?: (open: boolean) => void;
-    /** The callback receiving Escape before its default closing behavior. */
-    onEscapeKeyDown?: (event: KeyboardEvent) => void;
-    /** The callback receiving an outside press before default behavior. */
-    onPointerDownOutside?: (event: PointerEvent) => void;
-    /** The options rendered by the portal-backed listbox. */
-    options: readonly SelectOption[];
-    /** The guidance displayed when no option is selected. */
-    placeholder?: string;
-    /** The inline styles applied to the composite Select root. */
-    style?: CSSProperties;
-    /** Whether the custom Select communicates that a value is required. */
-    required?: boolean;
-    /** The selected value for controlled usage. */
-    value?: string;
-    /** The width applied to the composite Select root. */
-    width?: CSSProperties["width"];
-    /** Native children belong to native mode and cannot accompany options. */
-    children?: never;
-};
+export type { CustomSelectProps, SelectDisplayOverride, } from "./components/CustomSelect";
+export type { NativeSelectProps } from "./components/NativeSelect";
+export type { SelectOption } from "./utils/options";
 /** A type representing properties accepted by either Select mode. */
 export type SelectProps = NativeSelectProps | CustomSelectProps;
 /** A type representing the public Select component overloads. */

package/dist/components/Select/components/CustomSelect.d.ts

@@ -0,0 +1,59 @@
+import { type ButtonHTMLAttributes, type CSSProperties, type ForwardedRef } from "react";
+import { type IconType } from "../../Icon";
+import { type SelectOption } from "../utils/options";
+/** A type representing custom trigger content independent of selection. */
+export type SelectDisplayOverride = {
+    /** The optional icon displayed beside the trigger label. */
+    icon?: IconType;
+    /** The label displayed by the trigger. */
+    label: string;
+};
+/** A type representing the portal-backed custom Select mode properties. */
+export type CustomSelectProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" | "className" | "defaultValue" | "onChange" | "style" | "value"> & {
+    /** Whether an outside pointer interaction closes the listbox. */
+    closeOnOutsideInteraction?: boolean;
+    /** Whether the Escape key closes the listbox. */
+    closeOnEscape?: boolean;
+    /** The additional class name applied to the composite Select root. */
+    className?: string;
+    /** The initially selected value for uncontrolled usage. */
+    defaultValue?: string;
+    /** The optional content displayed independently from the selected option. */
+    displayOverride?: SelectDisplayOverride;
+    /** Whether the Select exposes an invalid semantic and visual state. */
+    invalid?: boolean;
+    /** The native form name submitted through the custom Select. */
+    name?: string;
+    /** The callback invoked with a newly selected option value. */
+    onChange?: (value: string) => void;
+    /** The callback invoked whenever the listbox opens or closes. */
+    onOpenChange?: (open: boolean) => void;
+    /** The callback receiving Escape before its default closing behavior. */
+    onEscapeKeyDown?: (event: KeyboardEvent) => void;
+    /** The callback receiving an outside press before default behavior. */
+    onPointerDownOutside?: (event: PointerEvent) => void;
+    /** The options rendered by the portal-backed listbox. */
+    options: readonly SelectOption[];
+    /** The guidance displayed when no option is selected. */
+    placeholder?: string;
+    /** The inline styles applied to the composite Select root. */
+    style?: CSSProperties;
+    /** Whether the custom Select communicates that a value is required. */
+    required?: boolean;
+    /** The selected value for controlled usage. */
+    value?: string;
+    /** The width applied to the composite Select root. */
+    width?: CSSProperties["width"];
+    /** Native children belong to native mode and cannot accompany options. */
+    children?: never;
+};
+/**
+ * Renders the options-driven, portal-backed Select mode.
+ *
+ * @param props - The custom Select properties and forwarded reference.
+ *
+ * @returns The rendered custom Select trigger and listbox portal.
+ */
+export default function CustomSelect(props: CustomSelectProps & {
+    forwardedReference: ForwardedRef<HTMLButtonElement>;
+}): import("react").JSX.Element;

package/dist/components/Select/components/NativeSelect.d.ts

@@ -0,0 +1,26 @@
+import type { CSSProperties, ForwardedRef, ReactNode, SelectHTMLAttributes } from "react";
+/** A type representing the existing native Select mode properties. */
+export type NativeSelectProps = Omit<SelectHTMLAttributes<HTMLSelectElement>, "children" | "className" | "multiple" | "size" | "style"> & {
+    /** The native option and optgroup content displayed by the Select. */
+    children: ReactNode;
+    /** The additional class name applied to the composite Select root. */
+    className?: string;
+    /** Whether the Select exposes an invalid semantic and visual state. */
+    invalid?: boolean;
+    /** The disabled empty-value guidance displayed before selection. */
+    placeholder?: string;
+    /** The inline styles applied to the composite Select root. */
+    style?: CSSProperties;
+    /** Custom options select portal mode and cannot accompany children. */
+    options?: never;
+};
+/**
+ * Renders a themed native single-selection control.
+ *
+ * @param props - The native Select properties and forwarded reference.
+ *
+ * @returns The rendered native Select control.
+ */
+export default function NativeSelect(props: NativeSelectProps & {
+    forwardedReference: ForwardedRef<HTMLSelectElement>;
+}): import("react").JSX.Element;

package/dist/components/Select/components/SelectListbox.d.ts

@@ -0,0 +1,50 @@
+import { type RefObject } from "react";
+import type { ListboxPosition } from "../utils/listbox-position";
+import type { SelectOption } from "../utils/options";
+/** A type representing properties used by a mounted custom listbox. */
+export type SelectListboxProps = {
+    /** Whether the listbox remains interactively open. */
+    active: boolean;
+    /** Whether Escape closes the listbox. */
+    closeOnEscape: boolean;
+    /** Whether outside pointer interaction closes the listbox. */
+    closeOnOutsideInteraction: boolean;
+    /** The highlighted option index. */
+    highlightedIndex: number;
+    /** The identifier assigned to the listbox. */
+    id: string;
+    /** The reference receiving the mounted listbox. */
+    listboxReference: (element: HTMLDivElement | null) => void;
+    /** The callback closing the listbox because of Escape. */
+    onEscapeDismiss: () => void;
+    /** The callback receiving Escape before default closing behavior. */
+    onEscapeKeyDown?: (event: KeyboardEvent) => void;
+    /** The callback updating the highlighted option. */
+    onHighlight: (index: number) => void;
+    /** The callback closing the listbox because of an outside press. */
+    onOutsideDismiss: () => void;
+    /** The callback receiving an outside press before default behavior. */
+    onPointerDownOutside?: (event: PointerEvent) => void;
+    /** The callback selecting an enabled option. */
+    onSelect: (option: SelectOption) => void;
+    /** The options displayed by the listbox. */
+    options: readonly SelectOption[];
+    /** The document owning the listbox layer. */
+    ownerDocument: Document;
+    /** The boundary-relative position fitted for the listbox. */
+    position: ListboxPosition | null;
+    /** The selected option value. */
+    selectedValue: string;
+    /** The visual phase exposed to transition styles. */
+    state: "closing" | "open";
+    /** The reference containing the Select trigger. */
+    triggerReference: RefObject<HTMLButtonElement | null>;
+};
+/**
+ * Renders one mounted custom Select listbox and its shared layer behavior.
+ *
+ * @param props - The listbox options, position, state, and callbacks.
+ *
+ * @returns The active or exiting custom listbox.
+ */
+export default function SelectListbox(props: SelectListboxProps): import("react").JSX.Element;

package/dist/components/Select/hooks/useSelectFormReset.d.ts

@@ -0,0 +1,27 @@
+import { type MutableRefObject, type RefObject } from "react";
+/** A type representing options accepted by the form reset hook. */
+export type SelectFormResetOptions = {
+    /**
+     * The form the Select is associated with.
+     *
+     * Observed rather than read, so the listener follows a reassociated form.
+     */
+    form?: string;
+    /** The callback restoring Select state alongside the proxied control. */
+    onReset: () => void;
+    /** The option value the proxied control defaults back to. */
+    resetValue: string;
+    /** The reference containing the Select trigger. */
+    triggerReference: RefObject<HTMLButtonElement | null>;
+};
+/**
+ * Restores the proxied form control and the Select on a native form reset.
+ *
+ * The listener follows the trigger's form rather than the proxied control's,
+ * because a Select submitting no value still restores what it displays.
+ *
+ * @param options - The reset value, form association, and restoration.
+ *
+ * @returns The reference assigned to the proxied form control.
+ */
+export declare function useSelectFormReset(options: SelectFormResetOptions): MutableRefObject<HTMLSelectElement | null>;

package/dist/components/Select/hooks/useSelectPosition.d.ts

@@ -0,0 +1,12 @@
+import { type ListboxPosition } from "../utils/listbox-position";
+/**
+ * Keeps a custom listbox aligned to its trigger and inside its boundary.
+ *
+ * @param active - Whether positioning observers should remain active.
+ * @param trigger - The trigger anchoring the listbox.
+ * @param listbox - The mounted listbox being positioned.
+ * @param boundary - The Boundary that constrains the listbox position.
+ *
+ * @returns The boundary-relative coordinates and size constraints.
+ */
+export declare function useSelectPosition(active: boolean, trigger: HTMLButtonElement | null, listbox: HTMLDivElement | null, boundary: HTMLElement | null): ListboxPosition | null;

package/dist/components/Select/hooks/useTypeahead.d.ts

@@ -0,0 +1,14 @@
+import { type RefObject } from "react";
+/**
+ * Accumulates typed characters into a query for incremental search.
+ *
+ * A run of one repeated character narrows to that single character, so
+ * pressing a key repeatedly cycles the entries beginning with it rather
+ * than searching for a query nothing can match.
+ *
+ * @param elementReference - The element whose realm owns the reset timer.
+ *
+ * @returns Records one character and returns the query to search for, or
+ * null when the element has no realm to schedule a reset in.
+ */
+export declare function useTypeahead(elementReference: RefObject<HTMLElement | null>): (character: string) => string | null;

package/dist/components/Select/utils/options.d.ts

@@ -0,0 +1,38 @@
+import type { IconType } from "../../Icon";
+/** A type representing one option in a custom Select. */
+export type SelectOption = {
+    /** Whether the option is unavailable for selection. */
+    disabled?: boolean;
+    /** The optional icon displayed beside the option label. */
+    icon?: IconType;
+    /** The visible and accessible option label. */
+    label: string;
+    /** The form value represented by the option. */
+    value: string;
+};
+/**
+ * Returns the next enabled option index in a requested direction.
+ *
+ * @param options - The options inspected for availability.
+ * @param currentIndex - The index from which navigation begins.
+ * @param direction - The movement direction through the options.
+ *
+ * @returns The next enabled index, or -1 when no enabled option exists.
+ */
+export declare function findEnabledOptionIndex(options: readonly SelectOption[], currentIndex: number, direction: 1 | -1): number;
+/**
+ * Returns the next enabled option whose label starts with a query.
+ *
+ * @param options - The options inspected for a matching label.
+ * @param query - The normalized typeahead query.
+ * @param currentIndex - The index after which matching begins.
+ *
+ * @returns The next matching index, or -1 when no option matches.
+ */
+export declare function findMatchingOptionIndex(options: readonly SelectOption[], query: string, currentIndex: number): number;
+/**
+ * Validates that option values identify exactly one custom Select option.
+ *
+ * @param options - The options whose values are inspected.
+ */
+export declare function validateSelectOptions(options: readonly SelectOption[]): void;

package/dist/components/Sidebar/Sidebar.d.ts

@@ -36,26 +36,29 @@ type SidebarComponent = typeof SidebarRoot & {
 export type SidebarProps = Omit<HTMLAttributes<HTMLElement>, "children" | "id" | "role" | "style" | "tabIndex"> & {
     /** The regions and groups composing the Sidebar. */
     children?: ReactNode;
+    /**
+     * Whether the Sidebar renders inline, as an overlay, or responsively. Where a
+     * responsive Sidebar switches at the medium breakpoint of its Boundary.
+     */
+    variant?: SidebarVariant;
+    /** The edge the overlay Sidebar occupies. */
+    side?: SidebarSide;
+    /** The width of the Sidebar in both presentations, as a CSS length. */
+    width?: string;
+    /** The height of the Sidebar in inline presentation, as a CSS length. */
+    height?: string;
+    /** The styles applied to the Sidebar panel. */
+    style?: SidebarStyle;
     /** Whether an uncontrolled overlay Sidebar is initially open. */
     defaultOpen?: boolean;
+    /** The controlled open state of the overlay Sidebar. */
+    open?: boolean;
     /** The preferred element focused when the overlay Sidebar opens. */
     initialFocusReference?: RefObject<HTMLElement | null>;
-    /** The distance the inline Sidebar is pinned below its scroll container. */
-    top?: string;
     /** Whether document scrolling is locked while the overlay is open. */
     lockScroll?: boolean;
-    /** The controlled open state of the overlay Sidebar. */
-    open?: boolean;
     /** Whether focus returns to the Trigger after the overlay closes. */
     restoreFocus?: boolean;
-    /** The edge the overlay Sidebar occupies. */
-    side?: SidebarSide;
-    /** The styles applied to the Sidebar panel. */
-    style?: SidebarStyle;
-    /** The responsive behavior selecting the Sidebar presentation. */
-    variant?: SidebarVariant;
-    /** The width of the Sidebar as a valid CSS length. */
-    width?: string;
     /** The callback invoked when an interaction requests a changed state. */
     onOpenChange?: (open: boolean, reason: SidebarOpenChangeReason) => void;
 };
@@ -85,26 +88,29 @@ export type SidebarProps = Omit<HTMLAttributes<HTMLElement>, "children" | "id" |
 declare const SidebarRoot: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLElement>, "id" | "style" | "tabIndex" | "role" | "children"> & {
     /** The regions and groups composing the Sidebar. */
     children?: ReactNode;
+    /**
+     * Whether the Sidebar renders inline, as an overlay, or responsively. Where a
+     * responsive Sidebar switches at the medium breakpoint of its Boundary.
+     */
+    variant?: SidebarVariant;
+    /** The edge the overlay Sidebar occupies. */
+    side?: SidebarSide;
+    /** The width of the Sidebar in both presentations, as a CSS length. */
+    width?: string;
+    /** The height of the Sidebar in inline presentation, as a CSS length. */
+    height?: string;
+    /** The styles applied to the Sidebar panel. */
+    style?: SidebarStyle;
     /** Whether an uncontrolled overlay Sidebar is initially open. */
     defaultOpen?: boolean;
+    /** The controlled open state of the overlay Sidebar. */
+    open?: boolean;
     /** The preferred element focused when the overlay Sidebar opens. */
     initialFocusReference?: RefObject<HTMLElement | null>;
-    /** The distance the inline Sidebar is pinned below its scroll container. */
-    top?: string;
     /** Whether document scrolling is locked while the overlay is open. */
     lockScroll?: boolean;
-    /** The controlled open state of the overlay Sidebar. */
-    open?: boolean;
     /** Whether focus returns to the Trigger after the overlay closes. */
     restoreFocus?: boolean;
-    /** The edge the overlay Sidebar occupies. */
-    side?: SidebarSide;
-    /** The styles applied to the Sidebar panel. */
-    style?: SidebarStyle;
-    /** The responsive behavior selecting the Sidebar presentation. */
-    variant?: SidebarVariant;
-    /** The width of the Sidebar as a valid CSS length. */
-    width?: string;
     /** The callback invoked when an interaction requests a changed state. */
     onOpenChange?: (open: boolean, reason: SidebarOpenChangeReason) => void;
 } & import("react").RefAttributes<HTMLElement>>;

package/dist/components/Sidebar/components/SidebarOverlay.d.ts

@@ -5,11 +5,10 @@ import { type SidebarPanelProps } from "./SidebarPanel";
  * A type representing properties for the mounted Sidebar overlay layer.
  *
  * The forwarded panel properties are derived rather than restated, so the
- * consumer attributes the root spreads through here stay described by one
- * declaration. The overlay supplies the presentation, open state, and
- * identifier itself, and a top offset applies to no overlay.
+ * consumer attributes that the root spreads through here, stay described by
+ * one declaration.
  */
-type SidebarOverlayProps = Omit<SidebarPanelProps, "top" | "open" | "panelId" | "panelReference" | "presentation" | "state"> & {
+type SidebarOverlayProps = Omit<SidebarPanelProps, "height" | "open" | "panelId" | "panelReference" | "presentation" | "state"> & {
     /** The elements treated as part of the overlay dismissal layer. */
     boundaries: readonly RefObject<HTMLElement | null>[];
     /** The preferred element focused when the Sidebar opens. */

package/dist/components/Sidebar/components/SidebarPanel.d.ts

@@ -12,8 +12,8 @@ export type SidebarStyle = CSSProperties & SidebarCustomProperties;
 export type SidebarPanelProps = Omit<HTMLAttributes<HTMLElement>, "children" | "style"> & {
     /** The regions and groups composing the Sidebar. */
     children?: ReactNode;
-    /** The distance the inline panel is pinned below its scroll container. */
-    top?: string;
+    /** The height of the inline panel as a CSS length. */
+    height?: string;
     /** The identifier associating the panel with its Trigger. */
     panelId?: string;
     /** The reference assigned to the rendered panel element. */