@entropix/react 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,379 @@
+import { AccessibilityProps, KeyboardHandlerConfig, KeyIntent, UseDialogOptions, UseTabsOptions, UseAccordionOptions, UseMenuOptions } from '@entropix/core';
+import * as react from 'react';
+import react__default from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Maps platform-neutral AccessibilityProps from @entropix/core
+ * to DOM-ready aria-* attributes.
+ *
+ * Filters out undefined values to keep rendered DOM clean.
+ */
+declare function mapAccessibilityToAria(props: AccessibilityProps): Record<string, unknown>;
+
+/**
+ * Converts a core KeyboardHandlerConfig + intent-to-callback map
+ * into a React onKeyDown handler.
+ *
+ * Returns undefined when no keyboardConfig is provided (e.g., disabled state).
+ */
+declare function useKeyboardHandler(keyboardConfig: KeyboardHandlerConfig | undefined, actionMap: Partial<Record<KeyIntent, () => void>>): React.KeyboardEventHandler<HTMLElement> | undefined;
+
+/**
+ * Traps focus within a container element when active.
+ *
+ * - Tab at the last focusable element wraps to the first
+ * - Shift+Tab at the first focusable element wraps to the last
+ * - Auto-focuses the first focusable element on activation
+ *
+ * All DOM access is inside useEffect for SSR safety.
+ */
+declare function useFocusTrap(containerRef: React.RefObject<HTMLElement | null>, isActive: boolean): void;
+
+/**
+ * Saves the currently focused element when isActive transitions to true,
+ * and restores focus to it when isActive transitions to false.
+ *
+ * Guards against elements that have been removed from the DOM.
+ * All DOM access inside useEffect for SSR safety.
+ */
+declare function useFocusRestore(isActive: boolean): void;
+
+interface ButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLElement>, "disabled"> {
+    /** Whether the button is disabled */
+    disabled?: boolean;
+    /** Whether the button is in a loading state */
+    loading?: boolean;
+    /** Called when the button is activated */
+    onPress?: () => void;
+    /** Render as a different element type */
+    as?: React.ElementType;
+    /** Visual variant for CSS targeting via data-variant */
+    variant?: string;
+    /** Size for CSS targeting via data-size */
+    size?: string;
+}
+/**
+ * Button component — web adapter for @entropix/core's useButton.
+ *
+ * Renders a `<button>` by default. Use the `as` prop for other elements.
+ * Provides data-state, data-variant, data-size attributes for CSS targeting.
+ */
+declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLElement>>;
+
+interface ToggleProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onChange" | "disabled"> {
+    /** Controlled checked state */
+    checked?: boolean;
+    /** Default checked state for uncontrolled mode */
+    defaultChecked?: boolean;
+    /** Called when checked state changes */
+    onChange?: (checked: boolean) => void;
+    /** Whether the toggle is disabled */
+    disabled?: boolean;
+    /** Accessible label (if no children) */
+    label?: string;
+}
+/**
+ * Toggle component — web adapter for @entropix/core's useToggle.
+ *
+ * Renders a `<button type="button">` with role="checkbox".
+ * Use the Switch component for role="switch" semantics.
+ * Sets data-state="checked"|"unchecked" for CSS targeting.
+ */
+declare const Toggle: react.ForwardRefExoticComponent<ToggleProps & react.RefAttributes<HTMLButtonElement>>;
+
+type SwitchProps = ToggleProps;
+/**
+ * Switch component — Toggle with role="switch" semantics.
+ *
+ * API-identical to Toggle, but renders with `role="switch"`
+ * instead of `role="checkbox"`.
+ */
+declare const Switch: react.ForwardRefExoticComponent<ToggleProps & react.RefAttributes<HTMLButtonElement>>;
+
+interface DialogProps extends UseDialogOptions {
+    children: React.ReactNode;
+}
+/**
+ * Dialog root — provides dialog state to compound sub-components.
+ * Renders no DOM of its own.
+ */
+declare function Dialog({ children, isOpen, defaultOpen, onOpenChange, closeOnOverlayPress, closeOnEscape, modal, role, }: DialogProps): react_jsx_runtime.JSX.Element;
+
+interface DialogTriggerProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+}
+/**
+ * DialogTrigger — button that opens/closes the dialog.
+ * Maps core's getTriggerProps() to DOM attributes.
+ */
+declare const DialogTrigger: react.ForwardRefExoticComponent<DialogTriggerProps & react.RefAttributes<HTMLButtonElement>>;
+
+interface DialogContentProps extends React.HTMLAttributes<HTMLDivElement> {
+}
+/**
+ * DialogContent — the dialog panel rendered in a portal.
+ *
+ * Implements focus trap, focus restore, Escape-to-close keyboard handling,
+ * and portal rendering. SSR-safe via useEffect mount gating.
+ */
+declare const DialogContent: react.ForwardRefExoticComponent<DialogContentProps & react.RefAttributes<HTMLDivElement>>;
+
+interface DialogTitleProps extends React.HTMLAttributes<HTMLHeadingElement> {
+}
+/**
+ * DialogTitle — heading element with auto-linked ID for aria-labelledby.
+ */
+declare const DialogTitle: react.ForwardRefExoticComponent<DialogTitleProps & react.RefAttributes<HTMLHeadingElement>>;
+
+interface DialogDescriptionProps extends React.HTMLAttributes<HTMLParagraphElement> {
+}
+/**
+ * DialogDescription — paragraph element with auto-linked ID for aria-describedby.
+ */
+declare const DialogDescription: react.ForwardRefExoticComponent<DialogDescriptionProps & react.RefAttributes<HTMLParagraphElement>>;
+
+interface DialogCloseProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+}
+/**
+ * DialogClose — button that closes the dialog.
+ * Maps core's getCloseProps() to DOM attributes.
+ */
+declare const DialogClose: react.ForwardRefExoticComponent<DialogCloseProps & react.RefAttributes<HTMLButtonElement>>;
+
+interface DialogOverlayProps extends React.HTMLAttributes<HTMLDivElement> {
+}
+/**
+ * DialogOverlay — backdrop element behind the dialog.
+ * Hidden from the accessibility tree. Optionally closes the dialog on click.
+ */
+declare const DialogOverlay: react.ForwardRefExoticComponent<DialogOverlayProps & react.RefAttributes<HTMLDivElement>>;
+
+interface TabsProps extends UseTabsOptions {
+    children: react__default.ReactNode;
+    className?: string;
+}
+declare function Tabs({ children, className, orientation, activationMode, ...options }: TabsProps): react_jsx_runtime.JSX.Element;
+
+interface TabListProps {
+    children: react__default.ReactNode;
+    className?: string;
+}
+declare function TabList({ children, className }: TabListProps): react_jsx_runtime.JSX.Element;
+
+interface TabProps {
+    value: string;
+    children: react__default.ReactNode;
+    className?: string;
+}
+declare function Tab({ value, children, className }: TabProps): react_jsx_runtime.JSX.Element;
+
+interface TabPanelProps {
+    value: string;
+    children: react__default.ReactNode;
+    className?: string;
+}
+declare function TabPanel({ value, children, className }: TabPanelProps): react_jsx_runtime.JSX.Element | null;
+
+interface AccordionProps extends UseAccordionOptions {
+    children: react__default.ReactNode;
+    className?: string;
+}
+declare function Accordion({ children, className, ...options }: AccordionProps): react_jsx_runtime.JSX.Element;
+
+interface AccordionItemProps {
+    value: string;
+    children: react__default.ReactNode;
+    className?: string;
+}
+declare function AccordionItem({ value, children, className, }: AccordionItemProps): react_jsx_runtime.JSX.Element;
+
+interface AccordionTriggerProps {
+    children: react__default.ReactNode;
+    className?: string;
+}
+declare function AccordionTrigger({ children, className, }: AccordionTriggerProps): react_jsx_runtime.JSX.Element;
+
+interface AccordionPanelProps {
+    children: react__default.ReactNode;
+    className?: string;
+}
+declare function AccordionPanel({ children, className }: AccordionPanelProps): react_jsx_runtime.JSX.Element | null;
+
+interface MenuProps extends UseMenuOptions {
+    children: react__default.ReactNode;
+}
+declare function Menu({ children, ...options }: MenuProps): react_jsx_runtime.JSX.Element;
+
+interface MenuTriggerProps {
+    children: react__default.ReactNode;
+    className?: string;
+}
+declare function MenuTrigger({ children, className }: MenuTriggerProps): react_jsx_runtime.JSX.Element;
+
+interface MenuContentProps {
+    children: react__default.ReactNode;
+    className?: string;
+}
+declare function MenuContent({ children, className }: MenuContentProps): react_jsx_runtime.JSX.Element | null;
+
+interface MenuItemProps {
+    index: number;
+    onSelect?: () => void;
+    disabled?: boolean;
+    children: react__default.ReactNode;
+    className?: string;
+}
+declare function MenuItem({ index, onSelect, disabled, children, className, }: MenuItemProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Breakpoint values in pixels, matching @entropix/tokens breakpoint primitives.
+ */
+declare const BREAKPOINTS: {
+    readonly sm: 640;
+    readonly md: 768;
+    readonly lg: 1024;
+    readonly xl: 1280;
+    readonly "2xl": 1536;
+};
+type Breakpoint = "base" | "sm" | "md" | "lg" | "xl" | "2xl";
+/**
+ * Returns the current breakpoint name based on viewport width.
+ *
+ * - `"base"` — <640px (mobile)
+ * - `"sm"` — ≥640px (landscape phones)
+ * - `"md"` — ≥768px (tablets)
+ * - `"lg"` — ≥1024px (laptops)
+ * - `"xl"` — ≥1280px (desktops)
+ * - `"2xl"` — ≥1536px (wide screens)
+ *
+ * ```tsx
+ * const breakpoint = useBreakpoint();
+ * const isMobile = breakpoint === "base" || breakpoint === "sm";
+ * ```
+ */
+declare function useBreakpoint(): Breakpoint;
+/**
+ * Subscribes to a CSS media query and returns whether it matches.
+ *
+ * ```tsx
+ * const isMobile = useMediaQuery("(max-width: 767px)");
+ * const prefersDark = useMediaQuery("(prefers-color-scheme: dark)");
+ * ```
+ */
+declare function useMediaQuery(query: string): boolean;
+/**
+ * Returns true if the current viewport is at or above the given breakpoint.
+ *
+ * ```tsx
+ * const isDesktop = useBreakpointValue("lg");
+ * // true when viewport ≥1024px
+ * ```
+ */
+declare function useBreakpointValue(breakpoint: Exclude<Breakpoint, "base">): boolean;
+
+type SpacingSize$1 = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
+interface StackProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Gap between children. Default uses --entropix-space-layout-stack token */
+    gap?: SpacingSize$1;
+    /** Cross-axis alignment */
+    align?: "start" | "center" | "end" | "stretch";
+    /** Whether to take full width */
+    fullWidth?: boolean;
+    /** Render as a different element */
+    as?: React.ElementType;
+}
+/**
+ * Stack — vertical flex layout primitive.
+ *
+ * Uses the `space.layout.stack` token (16px) as default gap.
+ *
+ * ```tsx
+ * <Stack gap="lg" align="center">
+ *   <Button>First</Button>
+ *   <Button>Second</Button>
+ * </Stack>
+ * ```
+ */
+declare const Stack: react.ForwardRefExoticComponent<StackProps & react.RefAttributes<HTMLDivElement>>;
+
+type SpacingSize = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
+interface InlineProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Gap between children. Default uses --entropix-space-layout-inline token */
+    gap?: SpacingSize;
+    /** Cross-axis alignment */
+    align?: "start" | "center" | "end" | "stretch" | "baseline";
+    /** Main-axis justification */
+    justify?: "start" | "center" | "end" | "between" | "around";
+    /** Whether to wrap children */
+    wrap?: boolean;
+    /** Render as a different element */
+    as?: React.ElementType;
+}
+/**
+ * Inline — horizontal flex layout primitive.
+ *
+ * Uses the `space.layout.inline` token (12px) as default gap.
+ *
+ * ```tsx
+ * <Inline gap="sm" justify="between" wrap>
+ *   <Button variant="primary">Save</Button>
+ *   <Button variant="ghost">Cancel</Button>
+ * </Inline>
+ * ```
+ */
+declare const Inline: react.ForwardRefExoticComponent<InlineProps & react.RefAttributes<HTMLDivElement>>;
+
+type ContainerSize = "xs" | "sm" | "md" | "lg" | "xl" | "full";
+interface ContainerProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Maximum width constraint. Default: "lg" (1024px) */
+    maxWidth?: ContainerSize;
+    /** Whether to center children vertically */
+    center?: boolean;
+    /** Render as a different element */
+    as?: React.ElementType;
+}
+/**
+ * Container — page-level width constraint with horizontal margins.
+ *
+ * Uses the `space.layout.page-margin` token (24px) for horizontal padding.
+ * Centers itself horizontally via auto margins.
+ *
+ * ```tsx
+ * <Container maxWidth="lg">
+ *   <Stack gap="xl">
+ *     <h1>Page Title</h1>
+ *     <p>Content</p>
+ *   </Stack>
+ * </Container>
+ * ```
+ */
+declare const Container: react.ForwardRefExoticComponent<ContainerProps & react.RefAttributes<HTMLDivElement>>;
+
+interface DividerProps extends React.HTMLAttributes<HTMLHRElement> {
+    /** Orientation of the divider */
+    orientation?: "horizontal" | "vertical";
+    /** Spacing above and below (or left and right for vertical) */
+    spacing?: "sm" | "md" | "lg";
+}
+/**
+ * Divider — visual separator line.
+ *
+ * Uses the `color.border.default` token for line color.
+ *
+ * ```tsx
+ * <Stack>
+ *   <p>Section A</p>
+ *   <Divider spacing="md" />
+ *   <p>Section B</p>
+ * </Stack>
+ *
+ * <Inline>
+ *   <span>Left</span>
+ *   <Divider orientation="vertical" spacing="sm" />
+ *   <span>Right</span>
+ * </Inline>
+ * ```
+ */
+declare const Divider: react.ForwardRefExoticComponent<DividerProps & react.RefAttributes<HTMLHRElement>>;
+
+export { Accordion, AccordionItem, type AccordionItemProps, AccordionPanel, type AccordionPanelProps, type AccordionProps, AccordionTrigger, type AccordionTriggerProps, BREAKPOINTS, type Breakpoint, Button, type ButtonProps, Container, type ContainerProps, type ContainerSize, Dialog, DialogClose, type DialogCloseProps, DialogContent, type DialogContentProps, DialogDescription, type DialogDescriptionProps, DialogOverlay, type DialogOverlayProps, type DialogProps, DialogTitle, type DialogTitleProps, DialogTrigger, type DialogTriggerProps, Divider, type DividerProps, Inline, type InlineProps, Menu, MenuContent, type MenuContentProps, MenuItem, type MenuItemProps, type MenuProps, MenuTrigger, type MenuTriggerProps, type SpacingSize$1 as SpacingSize, Stack, type StackProps, Switch, type SwitchProps, Tab, TabList, type TabListProps, TabPanel, type TabPanelProps, type TabProps, Tabs, type TabsProps, Toggle, type ToggleProps, mapAccessibilityToAria, useBreakpoint, useBreakpointValue, useFocusRestore, useFocusTrap, useKeyboardHandler, useMediaQuery };