@elvora/core 1.0.0-rc.1

package/dist/index.d.ts

@@ -0,0 +1,346 @@
+export { F as FocusTrap, a as FocusTrapOptions, c as createFocusTrap } from './focusTrap-Bko1L5FG.js';
+import { Tokens } from '@elvora/tokens';
+
+/**
+ * Shared semantic types used across every Elvora component on every framework.
+ * Keeping these in core means every adapter (React, RN, Angular, Vue) speaks
+ * the same vocabulary for sizes, variants, and statuses.
+ */
+type ElvoraSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+type ElvoraVariant = 'primary' | 'secondary' | 'tertiary' | 'ghost' | 'outline' | 'destructive' | 'link';
+type ElvoraStatus = 'info' | 'success' | 'warning' | 'error' | 'neutral';
+type ElvoraRadius = 'none' | 'sm' | 'md' | 'lg' | 'full';
+type ElvoraTone = 'solid' | 'subtle' | 'outline';
+type Orientation = 'horizontal' | 'vertical';
+type Placement = 'top' | 'top-start' | 'top-end' | 'right' | 'right-start' | 'right-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end';
+type Direction = 'ltr' | 'rtl';
+type Booleanish = boolean | 'true' | 'false';
+/** Helper to type a generic event handler that may be controlled or uncontrolled. */
+type ChangeHandler<T> = (value: T) => void;
+/** Helper for components that accept either a value or a callback to derive it. */
+type ValueOrCallback<T, Args extends unknown[] = []> = T | ((...args: Args) => T);
+
+/**
+ * Compose multiple refs into a single ref callback. Useful when a component
+ * needs both an internal ref (e.g. for focus management) and a forwarded ref
+ * from the caller.
+ *
+ * Framework-agnostic: works with any ref shape (callback or object with `.current`).
+ */
+type PossibleRef<T> = ((instance: T | null) => void) | {
+    current: T | null;
+} | null | undefined;
+declare function setRef<T>(ref: PossibleRef<T>, value: T | null): void;
+declare function composeRefs<T>(...refs: PossibleRef<T>[]): (node: T | null) => void;
+
+/**
+ * Compose two event handlers so the consumer's handler runs first; if it
+ * calls `event.preventDefault()` (or passes `checkForDefaultPrevented` and the
+ * synthetic event reports `defaultPrevented`), the internal handler is skipped.
+ *
+ * This pattern lets internal handlers do "after" work (e.g. close a popover)
+ * while still letting the consumer opt out.
+ */
+type AnyEvent = {
+    defaultPrevented?: boolean;
+};
+declare function composeEventHandlers<E extends AnyEvent>(originalEventHandler: ((event: E) => void) | undefined, ourEventHandler: ((event: E) => void) | undefined, { checkForDefaultPrevented }?: {
+    checkForDefaultPrevented?: boolean;
+}): (event: E) => void;
+
+type AnyProps = Record<string, unknown>;
+declare function mergeProps<A extends AnyProps, B extends AnyProps>(a: A, b: B): A & B;
+
+/**
+ * Helpers for conditionally emitting ARIA + data attributes. Returning
+ * `undefined` (instead of `false`) keeps DOM clean: the attribute is omitted
+ * entirely when the state isn't active.
+ */
+declare function dataAttr(condition: boolean | undefined): '' | undefined;
+declare function ariaAttr(condition: boolean | undefined): boolean | undefined;
+
+/**
+ * Minimal QR Code generator (byte mode only, error-correction levels L/M/Q/H,
+ * versions 1–10). Adapted from Nayuki's QR Code generator algorithm; this is a
+ * lean self-contained TypeScript port small enough to ship in a UI library
+ * without pulling in an external dependency.
+ *
+ * Returns a square boolean matrix (true = dark module, false = light) plus the
+ * chosen version. The caller is responsible for rendering it (SVG, canvas,
+ * native paths, …).
+ */
+type ErrorCorrection = 'L' | 'M' | 'Q' | 'H';
+interface QRMatrix {
+    size: number;
+    modules: boolean[][];
+    version: number;
+}
+/** Generate a QR matrix for the given text. */
+declare function generateQrMatrix(text: string, ecl?: ErrorCorrection): QRMatrix;
+
+/**
+ * Discover and walk focusable elements within a container. Used by focus traps,
+ * roving-tabindex managers, and keyboard-navigable lists/menus.
+ *
+ * Selectors are based on the WAI-ARIA Authoring Practices and the live
+ * `tabindex`/`disabled`/`inert` semantics of HTML.
+ */
+declare const FOCUSABLE_SELECTOR: string;
+declare function isElementVisible(el: HTMLElement): boolean;
+declare function isFocusable(el: HTMLElement): boolean;
+declare function getFocusableElements(container: HTMLElement): HTMLElement[];
+declare function getFirstFocusable(container: HTMLElement): HTMLElement | null;
+declare function getLastFocusable(container: HTMLElement): HTMLElement | null;
+
+/**
+ * Named keyboard constants. Adapters use these instead of magic strings so
+ * keyboard logic is consistent across frameworks.
+ */
+declare const Keys: {
+    readonly Enter: "Enter";
+    readonly Space: " ";
+    readonly Escape: "Escape";
+    readonly Tab: "Tab";
+    readonly ArrowUp: "ArrowUp";
+    readonly ArrowDown: "ArrowDown";
+    readonly ArrowLeft: "ArrowLeft";
+    readonly ArrowRight: "ArrowRight";
+    readonly Home: "Home";
+    readonly End: "End";
+    readonly PageUp: "PageUp";
+    readonly PageDown: "PageDown";
+    readonly Backspace: "Backspace";
+    readonly Delete: "Delete";
+};
+type KeyName = (typeof Keys)[keyof typeof Keys];
+/** True when the event represents an activation (Enter or Space). */
+declare function isActivationKey(key: string): boolean;
+
+/**
+ * Tiny, SSR-safe id generator. Prefer crypto.randomUUID when available, fall
+ * back to a monotonic counter otherwise so generated ids are stable across
+ * server/client when adapters seed them once.
+ */
+declare function generateId(prefix?: string): string;
+
+/**
+ * The shape of a Elvora theme. This is the contract every adapter depends on.
+ * The concrete `defaultTheme` / `darkTheme` values live in `@elvora/themes`,
+ * but the shape lives here so headless style descriptors don't need to import
+ * theme values — only the type.
+ */
+
+interface ElvoraTheme {
+    name: string;
+    mode: 'light' | 'dark';
+    tokens: Tokens;
+    colors: ThemeColors;
+    radii: {
+        sm: string;
+        md: string;
+        lg: string;
+        full: string;
+    };
+    shadows: {
+        sm: string;
+        md: string;
+        lg: string;
+        focus: string;
+    };
+    durations: {
+        fast: string;
+        normal: string;
+        slow: string;
+    };
+    easings: {
+        standard: string;
+        emphasized: string;
+    };
+}
+interface ThemeColors {
+    background: string;
+    surface: string;
+    surfaceElevated: string;
+    fg: string;
+    fgMuted: string;
+    fgSubtle: string;
+    border: string;
+    borderStrong: string;
+    intent: {
+        primary: IntentScale;
+        neutral: IntentScale;
+        success: IntentScale;
+        warning: IntentScale;
+        danger: IntentScale;
+        info: IntentScale;
+    };
+}
+interface IntentScale {
+    solid: string;
+    solidHover: string;
+    solidActive: string;
+    solidFg: string;
+    subtle: string;
+    subtleHover: string;
+    fg: string;
+    border: string;
+    ring: string;
+}
+
+/**
+ * Headless style descriptor for the Button component. Given a theme and the
+ * Button's variant/size/state, returns a flat style object usable by both web
+ * adapters (inline styles or vanilla-extract recipes) and React Native.
+ *
+ * Keeping this here means every framework adapter looks identical visually
+ * without re-implementing variant logic per framework.
+ */
+
+interface ButtonStyleInputs {
+    theme: ElvoraTheme;
+    variant: ElvoraVariant;
+    size: ElvoraSize;
+    fullWidth: boolean;
+    isLoading: boolean;
+    isDisabled: boolean;
+    isPressed: boolean;
+    isHovered: boolean;
+    isFocusVisible: boolean;
+    /** Intent overrides the variant's default color scheme (defaults to primary). */
+    intent?: keyof ElvoraTheme['colors']['intent'];
+}
+interface ButtonStyle {
+    /** Root style object — keys are camelCase so the same shape works in RN + web. */
+    root: Record<string, string | number | undefined>;
+    /** Label/text style. */
+    label: Record<string, string | number | undefined>;
+    /** Loading spinner color. */
+    spinnerColor: string;
+}
+declare function getButtonStyle(input: ButtonStyleInputs): ButtonStyle;
+
+interface InputStyleInputs {
+    theme: ElvoraTheme;
+    size: ElvoraSize;
+    status: ElvoraStatus;
+    isDisabled: boolean;
+    isReadOnly: boolean;
+    isInvalid: boolean;
+    isFocused: boolean;
+    isHovered: boolean;
+}
+declare function getInputStyle(input: InputStyleInputs): Record<string, string | number | undefined>;
+
+type FloatingLabelVariant = 'outlined' | 'filled';
+interface FloatingLabelStyleInputs {
+    theme: ElvoraTheme;
+    size: ElvoraSize;
+    variant: FloatingLabelVariant;
+    floated: boolean;
+    focused: boolean;
+    invalid: boolean;
+    /**
+     * Vertical resting position of the label when the field is empty. `center`
+     * suits single-line controls; `top` suits multi-line controls (textarea)
+     * where the text starts at the top.
+     */
+    restAlign?: 'center' | 'top';
+}
+interface FloatingLabelStyle {
+    wrapper: Record<string, string | number | undefined>;
+    label: Record<string, string | number | undefined>;
+}
+/**
+ * Headless style descriptor for a floating label. Drives the `outlined`
+ * (label notches the top border) and `filled` (label floats inside the field)
+ * variants. The float is React-state driven via `floated` because the library
+ * styles with inline CSS and cannot rely on `:focus`/`:placeholder-shown`.
+ */
+declare function getFloatingLabelStyle(input: FloatingLabelStyleInputs): FloatingLabelStyle;
+
+/**
+ * Framework-agnostic Button contract. Each adapter extends/maps this to its
+ * framework-idiomatic event names (onPress vs press vs @press) but the
+ * semantics are identical: same variants, same sizes, same states.
+ */
+
+interface ButtonOwnProps {
+    /** Visual variant. Defaults to `'primary'`. */
+    variant?: ElvoraVariant;
+    /** Size. Defaults to `'md'`. */
+    size?: ElvoraSize;
+    /** Override the intent (color scheme) for this button. */
+    intent?: keyof ElvoraTheme['colors']['intent'];
+    /** When true, stretches the button to fill its container. */
+    fullWidth?: boolean;
+    /** When true, shows a spinner and prevents activation. */
+    isLoading?: boolean;
+    /** Disabled state. */
+    isDisabled?: boolean;
+    /** Loading-state announcement for assistive tech. Defaults to "Loading". */
+    loadingText?: string;
+    /** Type attribute for HTML buttons. Defaults to `'button'`. */
+    type?: 'button' | 'submit' | 'reset';
+}
+declare const defaultButtonProps: {
+    variant: ElvoraVariant;
+    size: ElvoraSize;
+    type: "button";
+    fullWidth: boolean;
+    isLoading: boolean;
+    isDisabled: boolean;
+    loadingText: string;
+};
+
+interface InputOwnProps {
+    size?: ElvoraSize;
+    /** Validation status (changes border color and icon). */
+    status?: ElvoraStatus;
+    /** When true, renders a read-only input. */
+    isReadOnly?: boolean;
+    /** When true, disables the input. */
+    isDisabled?: boolean;
+    /** When true, the field is required for form submission. */
+    isRequired?: boolean;
+    /** When true, marks the input as invalid (`aria-invalid`). */
+    isInvalid?: boolean;
+}
+declare const defaultInputProps: {
+    size: ElvoraSize;
+    status: ElvoraStatus;
+    isReadOnly: boolean;
+    isDisabled: boolean;
+    isRequired: boolean;
+    isInvalid: boolean;
+};
+
+/**
+ * Headless Tabs contract. Each adapter renders tab buttons + panels and wires
+ * keyboard navigation per WAI-ARIA Tabs pattern.
+ */
+
+interface TabDescriptor<V extends string = string> {
+    /** Stable identifier for this tab; becomes the selected value. */
+    value: V;
+    /** Visible label. */
+    label: string;
+    /** Disable this tab. */
+    isDisabled?: boolean;
+}
+type TabsActivation = 'automatic' | 'manual';
+interface TabsKeyboardOptions {
+    orientation?: Orientation;
+    /** When `automatic` (default) arrow keys also select; `manual` only moves focus. */
+    activation?: TabsActivation;
+}
+/**
+ * Compute the next focusable tab index for a keyboard event. Returns the
+ * current index if the key shouldn't move focus.
+ */
+declare function getNextTabIndex(event: {
+    key: string;
+}, currentIndex: number, tabs: ReadonlyArray<{
+    isDisabled?: boolean;
+}>, options?: TabsKeyboardOptions): number;
+
+export { type Booleanish, type ButtonOwnProps, type ButtonStyle, type ButtonStyleInputs, type ChangeHandler, type Direction, type ElvoraRadius, type ElvoraSize, type ElvoraStatus, type ElvoraTheme, type ElvoraTone, type ElvoraVariant, type ErrorCorrection, FOCUSABLE_SELECTOR, type FloatingLabelStyle, type FloatingLabelStyleInputs, type FloatingLabelVariant, type InputOwnProps, type InputStyleInputs, type IntentScale, type KeyName, Keys, type Orientation, type Placement, type PossibleRef, type QRMatrix, type TabDescriptor, type TabsActivation, type TabsKeyboardOptions, type ThemeColors, type ValueOrCallback, ariaAttr, composeEventHandlers, composeRefs, dataAttr, defaultButtonProps, defaultInputProps, generateId, generateQrMatrix, getButtonStyle, getFirstFocusable, getFloatingLabelStyle, getFocusableElements, getInputStyle, getLastFocusable, getNextTabIndex, isActivationKey, isElementVisible, isFocusable, mergeProps, setRef };