@ansh-ui/react 0.2.0

package/dist/primitives.d.ts

@@ -0,0 +1,294 @@
+import * as react from 'react';
+import { Ref, SyntheticEvent, ReactNode, RefObject, CSSProperties } from 'react';
+import { b as PositionResult, a as PositionOptions } from './position-DVScKcaa.js';
+export { A as Align, P as Placement, R as Rect, S as Side, c as computePosition } from './position-DVScKcaa.js';
+export { I as InViewOptions, u as useElementSize, a as useFrameBudget, b as useInView, c as useMergedRef, d as usePointer, e as useReducedMotion, f as useScrollProgress, g as useTicker, h as useWindowScroll } from './use-observers-B9qtimrk.js';
+import * as _ansh_ui_core from '@ansh-ui/core';
+import { MotionValue, AnimationOptions, SpringOptions } from '@ansh-ui/core';
+
+/**
+ * Create a stable {@link MotionValue}.
+ *
+ * The value survives re-renders and — critically — **does not cause them**. That is the whole
+ * point: 60 renders per second of a React tree is not viable at any realistic component count,
+ * so animated values live outside React's reactivity and are written straight to the DOM.
+ *
+ * Reach for {@link useMotionValueState} only when you genuinely need the value in render output.
+ */
+declare function useMotionValue<T>(initial: T): MotionValue<T>;
+/**
+ * Subscribe to a MotionValue as React state.
+ *
+ * Uses `useSyncExternalStore`, which is the correct primitive here rather than
+ * `useState` + `useEffect`: it is tear-free under concurrent rendering, and it reads the value
+ * during render so there is never a frame showing a stale value.
+ *
+ * **This re-renders on every change.** For a value driven by an animation that is 60 renders per
+ * second. Use it for values that change at interaction rate (a toggle, a settled spring's final
+ * state), never for a value being animated continuously.
+ */
+declare function useMotionValueState<T>(value: MotionValue<T>): T;
+/**
+ * Write a MotionValue directly to a DOM property, bypassing React entirely.
+ *
+ * This is the mechanism that makes smooth animation possible in React. The returned ref is
+ * attached to an element; every change to the MotionValue writes straight to the node in the
+ * ticker's `write` phase.
+ *
+ * ```tsx
+ * const x = useMotionValue(0)
+ * const ref = useMotionStyle(x, (v) => `translateX(${v}px)`, 'transform')
+ * return <div ref={ref} />
+ * ```
+ */
+declare function useMotionStyle<T, El extends HTMLElement = HTMLDivElement>(value: MotionValue<T>, format: (value: T) => string, property?: keyof CSSStyleDeclaration & string): (node: El | null) => void;
+/**
+ * A spring that continuously chases a target.
+ *
+ * Returns a MotionValue and a setter. Unlike `animate(…, { type: 'spring' })` the target may
+ * change at any time and the spring carries its momentum through — which is what a cursor
+ * follower or a drag handle needs.
+ */
+declare function useSpringValue(initial: number, options?: SpringOptions): [MotionValue<number>, (target: number) => void];
+/**
+ * Imperative animation, scoped to the component's lifetime.
+ *
+ * Returns a `start` function and cancels any in-flight animation on unmount — the leak that
+ * hand-rolled `useEffect` animation code almost always has.
+ */
+declare function useAnimate(): <T>(from: T | MotionValue<T>, to: T | readonly T[], options?: AnimationOptions<T>) => _ansh_ui_core.AnimationControls;
+/**
+ * A boolean that flips to `true` once the component has mounted on the client.
+ *
+ * The idiomatic guard for anything that must not run during SSR. Returning `false` on the server
+ * and on the first client render means the two agree, so React never reports a hydration
+ * mismatch — which is what a naive `typeof window !== 'undefined'` check in render *does* cause.
+ */
+declare function useIsMounted(): boolean;
+
+/**
+ * State that works both controlled and uncontrolled.
+ *
+ * Every non-trivial component in this library needs this. A `<Select>` must work as
+ * `<Select />` (it owns its value), as `<Select defaultValue="a" />` (it owns its value, seeded),
+ * and as `<Select value={v} onChange={setV} />` (the parent owns it). Writing that logic per
+ * component is how libraries end up with a `Dialog` that supports controlled mode and a `Popover`
+ * that silently doesn't.
+ *
+ * The rule this encodes: **`value !== undefined` means controlled**, checked per render rather than
+ * latched on mount. Latching would be more "correct" in React's own terms, but it makes a component
+ * that starts uncontrolled and later receives a value fail silently, which is a real pattern when
+ * data arrives asynchronously.
+ */
+declare function useControllableState<T>(options: {
+    /** The controlled value. Pass `undefined` to stay uncontrolled. */
+    value?: T | undefined;
+    /** Initial value when uncontrolled. */
+    defaultValue: T;
+    /** Called on every change, in both modes. */
+    onChange?: ((value: T) => void) | undefined;
+}): [T, (next: T | ((previous: T) => T)) => void];
+
+/**
+ * Run a component's own handler after the consumer's, unless the consumer prevented default.
+ *
+ * The order matters and so does the check. A consumer's `onClick` on a `<Dialog.Close>` should be
+ * able to call `event.preventDefault()` to stop the dialog closing — that is the escape hatch that
+ * keeps composed components usable. Calling the internal handler first would make it impossible.
+ */
+declare function composeEventHandlers<E extends SyntheticEvent | Event>(theirs: ((event: E) => void) | undefined, ours: (event: E) => void, options?: {
+    checkForDefaultPrevented?: boolean;
+}): (event: E) => void;
+/** Assign a node to any ref shape — callback, object, or nothing. */
+declare function assignRef<T>(ref: Ref<T> | undefined | null, node: T | null): void;
+/**
+ * Merge refs without a hook.
+ *
+ * `useMergedRef` is the hook form and should be preferred inside components. This exists for the
+ * places a ref must be merged outside of a render — cloning an element in a `Slot`, for instance.
+ */
+declare function mergeRefs<T>(...refs: Array<Ref<T> | undefined | null>): (node: T | null) => void;
+/**
+ * Merge two sets of props, with the child's winning for everything except handlers, `className`
+ * and `style`, which compose.
+ *
+ * This is the merge strategy `asChild` needs. A naive spread would let a child's `onClick`
+ * silently delete a `Popover.Trigger`'s open handler, producing a trigger that renders perfectly
+ * and does nothing.
+ */
+declare function mergeProps(slotProps: Record<string, unknown>, childProps: Record<string, unknown>): Record<string, unknown>;
+/** Join class names, dropping falsy entries. The whole of `clsx` that this library actually uses. */
+declare function cx(...parts: Array<string | false | null | undefined>): string;
+
+interface SlotProps {
+    children?: ReactNode;
+    [key: string]: unknown;
+}
+/**
+ * Render into the child element instead of rendering a wrapper.
+ *
+ * This is what powers `asChild`. Without it, a `<Tooltip.Trigger>` wrapping a `<Button>` emits a
+ * `<span>` around the button — which breaks flex layouts, adds a node that inherits nothing, and
+ * puts the trigger's ARIA attributes on the wrong element for assistive technology.
+ *
+ * ```tsx
+ * <Tooltip.Trigger asChild>
+ *   <Button>Save</Button>
+ * </Tooltip.Trigger>
+ * ```
+ *
+ * The button *is* the trigger: it carries `aria-describedby` and the handlers, and no extra DOM
+ * node exists.
+ */
+declare const Slot: react.ForwardRefExoticComponent<Omit<SlotProps, "ref"> & react.RefAttributes<HTMLElement>>;
+/**
+ * Pick between a host element and its child based on `asChild`.
+ *
+ * Every component in this library that accepts `asChild` uses this, so the behaviour is identical
+ * across all of them rather than reimplemented with small differences.
+ */
+declare function slotted(asChild: boolean | undefined, fallback: React.ElementType): React.ElementType;
+/** Count element children, ignoring `null`/`false` from conditional rendering. */
+declare function countElements(children: ReactNode): number;
+
+interface PortalProps {
+    children: ReactNode;
+    /** Where to mount. Defaults to `document.body`. */
+    container?: Element | null;
+    /** Skip the portal and render in place. Useful inside an already-portalled surface. */
+    disabled?: boolean;
+}
+/**
+ * Render children elsewhere in the DOM.
+ *
+ * Overlays must escape their parent's stacking and clipping context. A popover inside a container
+ * with `overflow: hidden` gets clipped; one inside a `transform`ed ancestor has its `position:
+ * fixed` resolved against that ancestor instead of the viewport, so it lands in the wrong place.
+ * Neither is fixable with z-index, and both are the single most common overlay bug.
+ *
+ * SSR-safe: renders nothing on the server and on the first client render, then portals after mount.
+ * Portalling during SSR is impossible (no DOM), and portalling on the first client render would
+ * produce markup the server didn't emit — a hydration mismatch.
+ */
+declare function Portal({ children, container, disabled }: PortalProps): react.JSX.Element | null;
+
+/** Every tabbable descendant, in tab order. */
+declare function getTabbable(container: HTMLElement | null): HTMLElement[];
+/**
+ * Trap Tab within a container while `active`.
+ *
+ * Implemented on `keydown` at the container rather than with sentinel elements at either end. The
+ * sentinel approach adds two focusable nodes to the accessibility tree that screen readers can
+ * land on and announce as blank; intercepting the key does not.
+ */
+declare function useFocusTrap(ref: RefObject<HTMLElement | null>, active: boolean): void;
+/**
+ * Restore focus to whatever was focused before `active` became true.
+ *
+ * The element is captured on activation, not on mount, because a component can be mounted long
+ * before it opens.
+ */
+declare function useFocusRestore(active: boolean): void;
+/**
+ * Move focus into a surface when it opens.
+ *
+ * Prefers an explicitly marked element, then the first tabbable one, then the container itself.
+ * The container fallback matters for a dialog whose only content is text: focus must land inside
+ * it so a screen reader announces the dialog rather than continuing from the page behind.
+ */
+declare function useAutoFocus(ref: RefObject<HTMLElement | null>, active: boolean, initialFocus?: RefObject<HTMLElement | null>): void;
+/**
+ * Roving tabindex for a composite widget (toolbar, tab list, menu).
+ *
+ * The ARIA authoring practice: a composite has exactly **one** tab stop, and arrow keys move
+ * within it. Ten tabs that are each a tab stop means a keyboard user presses Tab ten times to get
+ * past the tab bar — technically operable, practically hostile.
+ */
+declare function useRovingFocus(options: {
+    /** Items in DOM order. */
+    itemsRef: RefObject<Array<HTMLElement | null>>;
+    /** Index that currently owns the tab stop. */
+    active: number;
+    onActiveChange: (index: number) => void;
+    orientation?: 'horizontal' | 'vertical' | 'both';
+    loop?: boolean;
+}): (event: React.KeyboardEvent) => void;
+
+/** Ids of the currently open dismissable layers, outermost first. Exposed for tests. */
+declare function getLayerStack(): readonly string[];
+interface DismissOptions {
+    /** Close on pointer press outside the surface. Default `true`. */
+    outsidePress?: boolean;
+    /** Close on Escape. Only the topmost layer responds. Default `true`. */
+    escapeKey?: boolean;
+    /**
+     * Extra elements that count as "inside" — normally the trigger.
+     *
+     * Without this the trigger's own click closes the surface via the outside handler and then
+     * immediately reopens it via its own onClick, so the surface appears not to close at all.
+     */
+    ignore?: Array<RefObject<HTMLElement | null>>;
+}
+declare function useDismiss(ref: RefObject<HTMLElement | null>, open: boolean, onDismiss: () => void, options?: DismissOptions): void;
+declare function useScrollLock(active: boolean): void;
+
+/**
+ * Keep an element mounted while it animates out.
+ *
+ * The problem: `{open && <Dialog />}` cannot animate on close, because React removes the node the
+ * instant `open` flips. The fix is to keep rendering it and unmount when the exit animation
+ * actually finishes.
+ *
+ * Finishing is detected from `animationend`/`transitionend` rather than a duration prop. A duration
+ * prop has to be kept in sync with the CSS by hand, and it drifts the moment someone retimes the
+ * animation in the stylesheet — leaving either a flash (unmount too early) or a surface that lingers
+ * invisibly and swallows clicks (too late). The timeout below is only a safety net for the case
+ * where no animation is declared at all and no event ever fires.
+ */
+declare function usePresence(open: boolean, ref: RefObject<HTMLElement | null>): {
+    mounted: boolean;
+    state: 'open' | 'closed';
+};
+interface PresenceProps {
+    open: boolean;
+    children: (props: {
+        ref: RefObject<HTMLElement | null>;
+        state: 'open' | 'closed';
+    }) => ReactNode;
+}
+/**
+ * Render-prop form of `usePresence`, for callers that would otherwise need to hoist a ref.
+ *
+ * ```tsx
+ * <Presence open={open}>
+ *   {({ ref, state }) => <div ref={ref} data-state={state} className="fade" />}
+ * </Presence>
+ * ```
+ */
+declare function Presence({ open, children }: PresenceProps): react.JSX.Element | null;
+
+interface AnchoredPositionOptions extends PositionOptions {
+    /** Set the floating element's width to the anchor's — what a combobox listbox wants. */
+    matchWidth?: boolean;
+    /** Recompute while open. Default `true`. */
+    enabled?: boolean;
+}
+interface AnchoredPosition {
+    style: CSSProperties;
+    arrowStyle: CSSProperties | undefined;
+    placement: PositionResult['placement'];
+    side: PositionResult['side'];
+    /** Force a recompute — call after content changes size in a way observers can't see. */
+    update: () => void;
+}
+/**
+ * Keep a floating element positioned against an anchor.
+ *
+ * Recomputes on scroll (capture phase, so nested scroll containers are caught), on viewport
+ * resize, and whenever either element changes size. It deliberately does **not** poll on every
+ * frame: that costs a forced layout per frame for a value that changes only on discrete events,
+ * and it is the reason some popover libraries make scrolling janky.
+ */
+declare function useAnchoredPosition(anchorRef: RefObject<HTMLElement | null>, floatingRef: RefObject<HTMLElement | null>, open: boolean, options?: AnchoredPositionOptions): AnchoredPosition;
+
+export { type AnchoredPosition, type AnchoredPositionOptions, type DismissOptions, Portal, type PortalProps, PositionOptions, PositionResult, Presence, type PresenceProps, Slot, type SlotProps, assignRef, composeEventHandlers, countElements, cx, getLayerStack, getTabbable, mergeProps, mergeRefs, slotted, useAnchoredPosition, useAnimate, useAutoFocus, useControllableState, useDismiss, useFocusRestore, useFocusTrap, useIsMounted, useMotionStyle, useMotionValue, useMotionValueState, usePresence, useRovingFocus, useScrollLock, useSpringValue };

package/dist/primitives.js

@@ -0,0 +1,9 @@
+'use client';
+export { useAnimate, useIsMounted, useMotionStyle, useMotionValue, useMotionValueState, useSpringValue } from './chunk-O2PX54KX.js';
+export { Presence, Slot, countElements, getTabbable, slotted, useAutoFocus, useFocusRestore, useFocusTrap, usePresence, useRovingFocus } from './chunk-HO2YSF5O.js';
+export { Portal, computePosition, getLayerStack, useAnchoredPosition, useDismiss, useScrollLock } from './chunk-XEP6P7E6.js';
+export { useControllableState } from './chunk-LXCIXR5T.js';
+export { useElementSize, useFrameBudget, useInView, useMergedRef, usePointer, useReducedMotion, useScrollProgress, useTicker, useWindowScroll } from './chunk-IBXLC5IE.js';
+export { assignRef, composeEventHandlers, cx, mergeProps, mergeRefs } from './chunk-H34OXXJU.js';
+//# sourceMappingURL=primitives.js.map
+//# sourceMappingURL=primitives.js.map

package/dist/primitives.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"primitives.js"}

package/dist/sidebar-D-PafAXw.d.cts

@@ -0,0 +1,71 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+interface NavItem {
+    id: string;
+    label: string;
+    href?: string;
+    icon?: ReactNode;
+    /** Count or status shown on the right. */
+    badge?: ReactNode;
+    disabled?: boolean;
+    onClick?: () => void;
+    /** Nested items, rendered in a collapsible group. */
+    items?: readonly NavItem[];
+}
+interface NavSection {
+    id: string;
+    /** Heading above the group. Omit for an unlabelled block. */
+    label?: string;
+    items: readonly NavItem[];
+}
+interface SidebarProps {
+    sections: readonly NavSection[];
+    /** Id of the active item. */
+    activeId?: string;
+    onNavigate?: (item: NavItem) => void;
+    /** Collapse to an icon rail. */
+    collapsed?: boolean;
+    defaultCollapsed?: boolean;
+    onCollapsedChange?: (collapsed: boolean) => void;
+    /** Content above the nav — a logo, a workspace switcher. */
+    header?: ReactNode;
+    /** Content pinned to the bottom — the user menu, usually. */
+    footer?: ReactNode;
+    /** Show the collapse toggle. Default `true`. */
+    collapsible?: boolean;
+    label?: string;
+    className?: string;
+}
+/**
+ * The application sidebar.
+ *
+ * A `<nav>` containing lists of links — the structure a screen reader user navigates by landmark,
+ * and the reason this isn't a stack of divs. Nested groups are `<button aria-expanded>` controlling
+ * a `<ul>`, so their state is announced.
+ *
+ * Collapsing to an icon rail keeps the labels in the DOM (visually hidden), rather than removing
+ * them. Removing them would leave a rail of unlabelled icons for anyone using assistive technology,
+ * which is exactly the population for whom the space saving is irrelevant.
+ */
+declare function Sidebar({ sections, activeId, onNavigate, collapsed, defaultCollapsed, onCollapsedChange, header, footer, collapsible, label, className, }: SidebarProps): react.JSX.Element;
+interface AppShellProps {
+    sidebar?: ReactNode;
+    header?: ReactNode;
+    children: ReactNode;
+    className?: string;
+}
+/**
+ * The header + sidebar + content frame.
+ *
+ * A grid rather than nested flex containers, so the sidebar and header can be `position: sticky`
+ * without the content needing compensating margins — the arrangement that breaks the moment the
+ * header's height changes.
+ *
+ * The skip link is the first focusable element on the page. It is the cheapest accessibility win
+ * available and it is missing from almost every application shell: without it, a keyboard user
+ * traverses the entire navigation on every single page load.
+ */
+declare function AppShell({ sidebar, header, children, className }: AppShellProps): react.JSX.Element;
+
+export { AppShell as A, type NavItem as N, Sidebar as S, type AppShellProps as a, type NavSection as b, type SidebarProps as c };

package/dist/sidebar-D-PafAXw.d.ts

@@ -0,0 +1,71 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+interface NavItem {
+    id: string;
+    label: string;
+    href?: string;
+    icon?: ReactNode;
+    /** Count or status shown on the right. */
+    badge?: ReactNode;
+    disabled?: boolean;
+    onClick?: () => void;
+    /** Nested items, rendered in a collapsible group. */
+    items?: readonly NavItem[];
+}
+interface NavSection {
+    id: string;
+    /** Heading above the group. Omit for an unlabelled block. */
+    label?: string;
+    items: readonly NavItem[];
+}
+interface SidebarProps {
+    sections: readonly NavSection[];
+    /** Id of the active item. */
+    activeId?: string;
+    onNavigate?: (item: NavItem) => void;
+    /** Collapse to an icon rail. */
+    collapsed?: boolean;
+    defaultCollapsed?: boolean;
+    onCollapsedChange?: (collapsed: boolean) => void;
+    /** Content above the nav — a logo, a workspace switcher. */
+    header?: ReactNode;
+    /** Content pinned to the bottom — the user menu, usually. */
+    footer?: ReactNode;
+    /** Show the collapse toggle. Default `true`. */
+    collapsible?: boolean;
+    label?: string;
+    className?: string;
+}
+/**
+ * The application sidebar.
+ *
+ * A `<nav>` containing lists of links — the structure a screen reader user navigates by landmark,
+ * and the reason this isn't a stack of divs. Nested groups are `<button aria-expanded>` controlling
+ * a `<ul>`, so their state is announced.
+ *
+ * Collapsing to an icon rail keeps the labels in the DOM (visually hidden), rather than removing
+ * them. Removing them would leave a rail of unlabelled icons for anyone using assistive technology,
+ * which is exactly the population for whom the space saving is irrelevant.
+ */
+declare function Sidebar({ sections, activeId, onNavigate, collapsed, defaultCollapsed, onCollapsedChange, header, footer, collapsible, label, className, }: SidebarProps): react.JSX.Element;
+interface AppShellProps {
+    sidebar?: ReactNode;
+    header?: ReactNode;
+    children: ReactNode;
+    className?: string;
+}
+/**
+ * The header + sidebar + content frame.
+ *
+ * A grid rather than nested flex containers, so the sidebar and header can be `position: sticky`
+ * without the content needing compensating margins — the arrangement that breaks the moment the
+ * header's height changes.
+ *
+ * The skip link is the first focusable element on the page. It is the cheapest accessibility win
+ * available and it is missing from almost every application shell: without it, a keyboard user
+ * traverses the entire navigation on every single page load.
+ */
+declare function AppShell({ sidebar, header, children, className }: AppShellProps): react.JSX.Element;
+
+export { AppShell as A, type NavItem as N, Sidebar as S, type AppShellProps as a, type NavSection as b, type SidebarProps as c };