@structyl/core 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,282 @@
+import * as React from 'react';
+import { Strategy } from '@floating-ui/react';
+
+declare const NODES: readonly ["a", "button", "div", "form", "h2", "h3", "img", "input", "label", "li", "nav", "ol", "p", "span", "svg", "ul"];
+type PrimitivePropsWithRef<E extends React.ElementType> = React.ComponentPropsWithRef<E> & {
+    asChild?: boolean;
+};
+type Primitives = {
+    [E in (typeof NODES)[number]]: PrimitiveForwardRefComponent<E>;
+};
+type PrimitiveForwardRefComponent<E extends React.ElementType> = React.ForwardRefExoticComponent<PrimitivePropsWithRef<E>>;
+declare const Primitive: Primitives;
+
+interface SlotProps extends React.HTMLAttributes<HTMLElement> {
+    children?: React.ReactNode;
+}
+/**
+ * Renders a copy of its child element with merged props.
+ * Powers the `asChild` pattern across the library.
+ */
+declare const Slot: React.ForwardRefExoticComponent<SlotProps & React.RefAttributes<HTMLElement>>;
+declare const Slottable: ({ children }: {
+    children: React.ReactNode;
+}) => React.JSX.Element;
+
+type Scope<C = unknown> = {
+    [scopeName: string]: React.Context<C>[];
+} | undefined;
+type ScopeHook = (scope: Scope) => {
+    [__scopeProp: string]: Scope;
+};
+interface CreateScope {
+    scopeName: string;
+    (): ScopeHook;
+}
+/**
+ * Create a typed context with a sensible error when used outside its Provider.
+ *
+ * @example
+ * const [DialogProvider, useDialogContext] = createContext<DialogContextValue>('Dialog');
+ */
+declare function createContext<ContextValueType extends object | null>(rootComponentName: string, defaultContext?: ContextValueType): readonly [
+    React.FC<ContextValueType & {
+        children: React.ReactNode;
+    }>,
+    (consumerName: string) => ContextValueType
+];
+/**
+ * Create a scoped context factory. Solves context leakage when the same
+ * component family is nested inside itself (e.g. nested Dialogs, nested Menus)
+ * or when two families share an internal primitive (e.g. both use PopperContext).
+ *
+ * Returns `[createContext, createScope]`:
+ * - `createContext` behaves like the simple version above but scoped.
+ * - `createScope` is a CreateScope factory consumed by other component families
+ *   that depend on this one.
+ *
+ * @example
+ * const [createDialogContext, createDialogScope] = createContextScope('Dialog');
+ * const [DialogProvider, useDialogContext] = createDialogContext<DialogContextValue>('Dialog');
+ *
+ * // In Dialog.Root:
+ * function Root({ __scopeDialog, ...props }) {
+ *   const scope = useDialogScope(__scopeDialog);
+ *   return <DialogProvider {...scope} open={...}>{props.children}</DialogProvider>;
+ * }
+ */
+declare function createContextScope(scopeName: string, createContextScopeDeps?: CreateScope[]): readonly [
+    <ContextValueType extends object | null>(rootComponentName: string, defaultContext?: ContextValueType) => readonly [
+        React.FC<ContextValueType & {
+            scope: Scope;
+            children: React.ReactNode;
+        }>,
+        (consumerName: string, scope: Scope) => ContextValueType
+    ],
+    CreateScope
+];
+/**
+ * Merge multiple CreateScope factories into one. Used internally when a
+ * component family depends on another (e.g. DropdownMenu depends on Popper).
+ */
+declare function composeContextScopes(...scopes: CreateScope[]): CreateScope;
+
+interface PortalProps extends React.ComponentPropsWithoutRef<typeof Primitive.div> {
+    /** Element where the portal renders. Defaults to `document.body`. */
+    container?: Element | DocumentFragment | null;
+}
+declare const Portal: React.ForwardRefExoticComponent<PortalProps & React.RefAttributes<HTMLDivElement>>;
+
+type VisuallyHiddenProps = React.ComponentPropsWithoutRef<typeof Primitive.span>;
+declare const VisuallyHidden: React.ForwardRefExoticComponent<Omit<React.ClassAttributes<HTMLSpanElement> & React.HTMLAttributes<HTMLSpanElement> & {
+    asChild?: boolean;
+}, "ref"> & React.RefAttributes<HTMLSpanElement>>;
+
+type Direction = 'ltr' | 'rtl';
+interface DirectionProviderProps {
+    children?: React.ReactNode;
+    dir: Direction;
+}
+declare const DirectionProvider: React.FC<DirectionProviderProps>;
+declare function useDirection(localDir?: Direction): Direction;
+
+/**
+ * Drives an animation-aware presence state machine. When `present` flips from
+ * true → false the node remains mounted until a CSS animation or transition
+ * completes, allowing exit animations to play.
+ */
+declare function usePresence(present: boolean): {
+    isPresent: boolean;
+    ref: (el: HTMLElement | null) => void;
+};
+interface PresenceProps {
+    present: boolean;
+    children: React.ReactElement | ((props: {
+        present: boolean;
+    }) => React.ReactElement);
+    /** Force the element to stay mounted regardless of `present`. */
+    forceMount?: boolean;
+}
+declare const Presence: React.FC<PresenceProps>;
+
+interface FocusScopeProps extends React.ComponentPropsWithoutRef<typeof Primitive.div> {
+    /** When true, tabbing from the last focusable wraps to the first. */
+    loop?: boolean;
+    /** When true, focus cannot leave the scope while it is mounted. */
+    trapped?: boolean;
+    /** Called when focus moves into the scope. Call `event.preventDefault()` to prevent default. */
+    onMountAutoFocus?: (event: Event) => void;
+    /** Called when focus is about to leave the scope on unmount. Call `event.preventDefault()` to prevent default restoration. */
+    onUnmountAutoFocus?: (event: Event) => void;
+}
+declare const FocusScope: React.ForwardRefExoticComponent<FocusScopeProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Inject visually-hidden focusable sentinel elements at the start and end of
+ * the document body. When Tab attempts to leave a trapped FocusScope the
+ * sentinels catch focus and FocusScope re-enters the scope.
+ *
+ * Counted singleton — multiple `<FocusGuards />` mounted at once still only
+ * inserts one pair of guards.
+ */
+declare function useFocusGuards(): void;
+declare const FocusGuards: React.FC<{
+    children?: React.ReactNode;
+}>;
+
+type PointerDownOutsideEvent = CustomEvent<{
+    originalEvent: PointerEvent;
+}>;
+type FocusOutsideEvent = CustomEvent<{
+    originalEvent: FocusEvent;
+}>;
+interface DismissableLayerProps extends React.ComponentPropsWithoutRef<typeof Primitive.div> {
+    /** When true, hovering outside the layer disables pointer events on outside elements. */
+    disableOutsidePointerEvents?: boolean;
+    /** Called when Escape is pressed. Call `event.preventDefault()` to cancel dismissal. */
+    onEscapeKeyDown?: (event: KeyboardEvent) => void;
+    /** Called on pointerdown outside the layer. */
+    onPointerDownOutside?: (event: PointerDownOutsideEvent) => void;
+    /** Called when focus moves outside the layer. */
+    onFocusOutside?: (event: FocusOutsideEvent) => void;
+    /** Called on any interaction (pointer or focus) outside the layer. */
+    onInteractOutside?: (event: PointerDownOutsideEvent | FocusOutsideEvent) => void;
+    /** Called when the layer should dismiss. */
+    onDismiss?: () => void;
+}
+declare const DismissableLayer: React.ForwardRefExoticComponent<DismissableLayerProps & React.RefAttributes<HTMLDivElement>>;
+interface DismissableLayerBranchProps extends React.ComponentPropsWithoutRef<typeof Primitive.div> {
+}
+declare const DismissableLayerBranch: React.ForwardRefExoticComponent<DismissableLayerBranchProps & React.RefAttributes<HTMLDivElement>>;
+
+type Orientation = 'horizontal' | 'vertical';
+interface RovingFocusGroupProps extends React.ComponentPropsWithoutRef<typeof Primitive.div> {
+    orientation?: Orientation;
+    dir?: Direction;
+    loop?: boolean;
+    currentTabStopId?: string | null;
+    defaultCurrentTabStopId?: string;
+    onCurrentTabStopIdChange?: (tabStopId: string | null) => void;
+    onEntryFocus?: (event: Event) => void;
+    preventScrollOnEntryFocus?: boolean;
+}
+declare const RovingFocusGroup: React.ForwardRefExoticComponent<RovingFocusGroupProps & React.RefAttributes<HTMLDivElement>>;
+interface RovingFocusItemProps extends React.ComponentPropsWithoutRef<typeof Primitive.span> {
+    tabStopId?: string;
+    focusable?: boolean;
+    active?: boolean;
+}
+declare const RovingFocusItem: React.ForwardRefExoticComponent<RovingFocusItemProps & React.RefAttributes<HTMLSpanElement>>;
+
+type CollectionElement = HTMLElement;
+type ItemData<I> = {
+    ref: React.RefObject<CollectionElement | null>;
+} & I;
+/**
+ * Create an ordered collection for tracking child items in DOM order.
+ * Used by RovingFocusGroup, Menu, Select, etc. to expose
+ * `getItems()` returning items sorted as they appear in the DOM.
+ */
+declare function createCollection<I extends Record<string, unknown> = Record<string, unknown>>(name: string): readonly [{
+    readonly Provider: React.FC<{
+        children?: React.ReactNode;
+    }>;
+    readonly Slot: React.ForwardRefExoticComponent<{
+        children: React.ReactNode;
+    } & React.RefAttributes<HTMLElement>>;
+    readonly ItemSlot: React.ForwardRefExoticComponent<React.PropsWithoutRef<{
+        children: React.ReactNode;
+    } & I> & React.RefAttributes<HTMLElement>>;
+}, () => () => Array<ItemData<I>>];
+
+interface ArrowProps extends React.ComponentPropsWithoutRef<typeof Primitive.svg> {
+    width?: number;
+    height?: number;
+}
+/**
+ * SVG arrow used by `Popper` (and any tooltip/popover that needs a pointer).
+ * Composed via `Popper.Arrow` which positions and rotates this element.
+ */
+declare const Arrow: React.ForwardRefExoticComponent<ArrowProps & React.RefAttributes<SVGSVGElement>>;
+
+interface AccessibleIconProps {
+    /** Visually-hidden label announced to assistive tech. */
+    label: string;
+    /** The icon element (must be a single React element). */
+    children: React.ReactElement;
+}
+/**
+ * Wraps an icon element with `aria-hidden` and an adjacent visually-hidden label,
+ * so the icon is decorative to sighted users but still announced to screen readers.
+ */
+declare const AccessibleIcon: React.FC<AccessibleIconProps>;
+
+/**
+ * Lock body scroll while mounted. Compensates for scrollbar disappearance
+ * to avoid layout shift. Reference-counted so nested usages work.
+ */
+declare function useScrollLock(enabled?: boolean): void;
+declare const ScrollLock: React.FC<{
+    children?: React.ReactNode;
+    enabled?: boolean;
+}>;
+
+type Side = 'top' | 'right' | 'bottom' | 'left';
+type Align = 'start' | 'center' | 'end';
+type Sticky = 'partial' | 'always';
+declare const Popper: React.FC<{
+    children?: React.ReactNode;
+}>;
+interface PopperAnchorProps extends React.ComponentPropsWithoutRef<typeof Primitive.div> {
+    virtualRef?: React.RefObject<{
+        getBoundingClientRect: () => DOMRect;
+    }>;
+}
+declare const PopperAnchor: React.ForwardRefExoticComponent<PopperAnchorProps & React.RefAttributes<HTMLDivElement>>;
+interface PopperContentProps extends React.ComponentPropsWithoutRef<typeof Primitive.div> {
+    side?: Side;
+    sideOffset?: number;
+    align?: Align;
+    alignOffset?: number;
+    arrowPadding?: number;
+    avoidCollisions?: boolean;
+    collisionBoundary?: Element | Element[] | null;
+    collisionPadding?: number | Partial<Record<Side, number>>;
+    sticky?: Sticky;
+    hideWhenDetached?: boolean;
+    updatePositionStrategy?: 'always' | 'optimized';
+    onPlaced?: () => void;
+    strategy?: Strategy;
+}
+declare const PopperContent: React.ForwardRefExoticComponent<PopperContentProps & React.RefAttributes<HTMLDivElement>>;
+declare const PopperArrow: React.ForwardRefExoticComponent<ArrowProps & React.RefAttributes<SVGSVGElement>>;
+
+type popper_Align = Align;
+type popper_PopperAnchorProps = PopperAnchorProps;
+type popper_PopperContentProps = PopperContentProps;
+type popper_Side = Side;
+declare namespace popper {
+  export { type popper_Align as Align, PopperAnchor as Anchor, PopperArrow as Arrow, PopperContent as Content, type popper_PopperAnchorProps as PopperAnchorProps, type popper_PopperContentProps as PopperContentProps, Popper as Root, type popper_Side as Side };
+}
+
+export { AccessibleIcon, type AccessibleIconProps, Arrow, type ArrowProps, type Direction, DirectionProvider, DismissableLayer, DismissableLayerBranch, type DismissableLayerBranchProps, type DismissableLayerProps, FocusGuards, type FocusOutsideEvent, FocusScope, type FocusScopeProps, type Orientation, type PointerDownOutsideEvent, popper as Popper, Portal, type PortalProps, Presence, type PresenceProps, Primitive, type PrimitivePropsWithRef, RovingFocusGroup, type RovingFocusGroupProps, RovingFocusItem, type RovingFocusItemProps, ScrollLock, Slot, type SlotProps, Slottable, VisuallyHidden, type VisuallyHiddenProps, composeContextScopes, createCollection, createContext, createContextScope, useDirection, useFocusGuards, usePresence, useScrollLock };