@passui/react 0.1.17 → 0.1.20

package/dist/types/src/components/sheet/sheet.d.ts

@@ -0,0 +1,21 @@
+import { type ReactNode } from "react";
+export type SheetPlacement = "adaptive" | "center";
+export interface SheetProps {
+    /** Controls whether the sheet is presented. */
+    open: boolean;
+    /** Called on Escape or an outside press. */
+    onClose: () => void;
+    /** Read out by screen readers as the sheet's name. */
+    label: string;
+    /** ID of a visible heading to use instead of label for the accessible name. */
+    labelledBy?: string;
+    /** `adaptive` rises from the bottom on phones; `center` always floats. @default "adaptive" */
+    placement?: SheetPlacement;
+    className?: string;
+    children: ReactNode;
+}
+/**
+ * A modal card: rises from the bottom edge on phones and floats in the
+ * middle on larger screens. Escape or a tap outside closes it.
+ */
+export declare function Sheet({ open, ...props }: SheetProps): import("react").JSX.Element;

package/dist/types/src/components/sheet/use-sheet-focus.d.ts

@@ -0,0 +1,3 @@
+import { type RefObject } from "react";
+/** Keeps keyboard focus in the foremost sheet, including its floating pickers. */
+export declare function useSheetFocus(panel: RefObject<HTMLDivElement | null>, onClose: () => void): void;

package/dist/types/src/components/sidebar/sidebar.d.ts

@@ -0,0 +1,19 @@
+import { type ReactNode } from "react";
+export interface SidebarSectionProps {
+    /** Visible heading for this group of navigation rows. */
+    title: string;
+    children: ReactNode;
+}
+export interface SidebarItemContentProps {
+    icon?: ReactNode;
+    /** Optional trailing count. */
+    count?: number;
+    /** Matches the router link's active state. */
+    active?: boolean;
+    children: ReactNode;
+}
+export declare function SidebarSection({ title, children }: SidebarSectionProps): import("react").JSX.Element;
+/** Classes for a sidebar row; apply to the app's router link. */
+export type SidebarDensity = "regular" | "compact";
+export declare function sidebarItemClass(active?: boolean, density?: SidebarDensity): string;
+export declare function SidebarItemContent({ icon, count, active, children }: SidebarItemContentProps): import("react").JSX.Element;

package/dist/types/src/components/skeleton/skeleton.d.ts

@@ -0,0 +1,6 @@
+import type { ComponentProps } from "react";
+export interface SkeletonProps extends ComponentProps<"div"> {
+    label?: string;
+}
+/** A loading placeholder that becomes still when Reduce Motion is enabled. */
+export declare function Skeleton({ label, className, ...props }: SkeletonProps): import("react").JSX.Element;

package/dist/types/src/components/slider/slider.d.ts

@@ -0,0 +1,14 @@
+import { type ComponentProps } from "react";
+export interface SliderProps extends Omit<ComponentProps<"input">, "type" | "value" | "defaultValue" | "onChange" | "min" | "max" | "step"> {
+    value: number;
+    onChange: (value: number) => void;
+    label: string;
+    min?: number;
+    max?: number;
+    step?: number;
+    description?: string;
+    /** Provides a localized, spoken description of the current value. */
+    formatValue?: (value: number) => string;
+}
+/** Native keyboard, touch and pointer behavior with Passui's control treatment. */
+export declare function Slider({ value, onChange, label, min, max, step, description, formatValue, id: suppliedId, className, disabled, ...props }: SliderProps): import("react").JSX.Element;

package/dist/types/src/components/slosh-slider/liquid-step.d.ts

@@ -0,0 +1,6 @@
+export interface LiquidState {
+    fill: number;
+    velocity: number;
+}
+/** Bencho's frame-normalized liquid spring. See THIRD_PARTY_NOTICES.md. */
+export declare function stepLiquid(state: LiquidState, target: number, viscosity: number, dt: number): LiquidState;

package/dist/types/src/components/slosh-slider/slosh-slider.d.ts

@@ -0,0 +1,18 @@
+export interface SloshSliderProps {
+    label: string;
+    value?: number;
+    defaultValue?: number;
+    onChange?: (value: number) => void;
+    /** 0 is rigid; 100 is loose liquid. @default 15 */
+    viscosity?: number;
+    /** How far the handle coasts after release, 0–100. @default 55 */
+    momentum?: number;
+    /** Lean of the liquid's leading edge, 0–100. @default 45 */
+    tilt?: number;
+    /** Track corner, from square to a pill, 0–20. @default 20 */
+    corner?: number;
+    disabled?: boolean;
+    className?: string;
+    formatValue?: (value: number) => string;
+}
+export declare function SloshSlider({ label, value, defaultValue, onChange, viscosity, momentum, tilt, corner, disabled, className, formatValue, }: SloshSliderProps): import("react").JSX.Element;

package/dist/types/src/components/stat-tile/index.d.ts

@@ -0,0 +1 @@
+export * from "./stat-tile";

package/dist/types/src/components/stat-tile/stat-tile.d.ts

@@ -0,0 +1,15 @@
+import type { ReactNode } from "react";
+export type StatTileTone = "critical";
+export interface StatTileProps {
+    label: string;
+    value: number;
+    /** A quiet line under the number, like "3 signed in now". */
+    caption?: ReactNode;
+    /** Turns the number red once it's above zero. */
+    tone?: StatTileTone;
+    /** Makes the tile a toggle, e.g. a filter. */
+    onClick?: () => void;
+    active?: boolean;
+}
+/** One number with its label, optionally a toggle. */
+export declare function StatTile({ label, value, caption, tone, onClick, active }: StatTileProps): import("react").JSX.Element;

package/dist/types/src/components/status-indicator/status-indicator.d.ts

@@ -0,0 +1,14 @@
+import type { HTMLAttributes, ReactNode } from "react";
+declare const dots: {
+    readonly saved: "bg-success";
+    readonly syncing: "bg-warning animate-pulse";
+    readonly offline: "bg-label-tertiary";
+};
+export type StatusIndicatorState = keyof typeof dots;
+export interface StatusIndicatorProps extends HTMLAttributes<HTMLSpanElement> {
+    /** Visual treatment of the status dot. */
+    state: StatusIndicatorState;
+    children: ReactNode;
+}
+export declare function StatusIndicator({ state, children, className, ...props }: StatusIndicatorProps): import("react").JSX.Element;
+export {};

package/dist/types/src/components/stepper/rolling-digit.d.ts

@@ -0,0 +1,11 @@
+/** Counts at a place retain carries: the tens column of 1284 targets 128. */
+export declare function digitAt(count: number): number;
+export declare function advanceDigit(position: number, velocity: number, target: number, frames: number): {
+    position: number;
+    velocity: number;
+};
+/** Three recycled cells keep the strip continuous through either side of zero. */
+export declare function RollingDigit({ count, place }: {
+    count: number;
+    place: number;
+}): import("react").JSX.Element;

package/dist/types/src/components/stepper/stepper.d.ts

@@ -0,0 +1,19 @@
+export interface StepperProps {
+    value: number;
+    onChange: (value: number) => void;
+    label: string;
+    /** Localized accessible names for each action. */
+    labels: {
+        decrement: string;
+        increment: string;
+    };
+    min?: number;
+    max?: number;
+    step?: number;
+    disabled?: boolean;
+    className?: string;
+    /** Formats the displayed value. */
+    formatValue?: (value: number) => string;
+}
+/** Discrete increments with disabled boundary actions and a spoken value. */
+export declare function Stepper({ value, onChange, label, labels, min, max, step, disabled, className, formatValue, }: StepperProps): import("react").JSX.Element;

package/dist/types/src/components/swatch-picker/swatch-picker.d.ts

@@ -0,0 +1,17 @@
+export interface SwatchPickerOption<T extends string> {
+    value: T;
+    label: string;
+    /** Swatch background color. */
+    color: string;
+    /** Color of the selected checkmark. */
+    ink: string;
+}
+export interface SwatchPickerProps<T extends string> {
+    value: T;
+    options: ReadonlyArray<SwatchPickerOption<T>>;
+    onChange: (value: T) => void;
+    /** Accessible name for the group. */
+    label: string;
+}
+/** Colour swatches with a check on the chosen one. */
+export declare function SwatchPicker<T extends string>({ value, options, onChange, label, }: SwatchPickerProps<T>): import("react").JSX.Element;

package/dist/types/src/components/tab-bar/tab-bar.d.ts

@@ -0,0 +1,40 @@
+import { type ReactNode } from "react";
+export interface TabBarTab<Id extends string = string> {
+    id: Id;
+    label: string;
+    icon: ReactNode;
+}
+/** What a tab's link receives; spread it onto the router's own link. */
+export interface TabBarLinkProps {
+    className: string;
+    "aria-current": "page" | undefined;
+    onClick: () => void;
+    children: ReactNode;
+}
+export type TabBarMinimizeBehavior = "platform" | "scroll" | "never";
+export interface TabBarProps<Tab extends TabBarTab> {
+    /** `platform` follows the platform, `scroll` always minimizes, `never` stays expanded. @default "platform" */
+    minimizeBehavior?: TabBarMinimizeBehavior;
+    tabs: readonly Tab[];
+    /** Active tab ID, or null for a destination outside the bar. */
+    active: Tab["id"] | null;
+    /** Renders your router's link with the supplied appearance and accessibility props. */
+    renderLink: (tab: Tab, props: TabBarLinkProps) => ReactNode;
+    search?: {
+        label: string;
+        onPress: () => void;
+    };
+    /** Accessible name for the navigation. */
+    label: string;
+    className?: string;
+}
+/**
+ * The app's main places a thumb's reach away, drawn as iOS 26 draws them: a
+ * floating glass capsule of tabs, with Search as its own round button at the
+ * trailing end. Scrolling down through content shrinks the capsule to the
+ * current tab; scrolling back up, or a tap, restores it. Android shares the
+ * glass, but its bar stays full size, as Android's own bars do.
+ *
+ * Links stay the app's own (`renderLink`), so the bar works with any router.
+ */
+export declare function TabBar<Tab extends TabBarTab>({ tabs, active, renderLink, search, label, className, minimizeBehavior, }: TabBarProps<Tab>): import("react").JSX.Element;

package/dist/types/src/components/tab-view/tab-view.d.ts

@@ -0,0 +1,24 @@
+import { type ReactNode } from "react";
+export type TabViewAlign = "start" | "center";
+export interface TabViewProps<Value extends string> {
+    /** Available tabs, in keyboard navigation order. */
+    options: readonly {
+        value: Value;
+        label: string;
+        disabled?: boolean;
+    }[];
+    /** Initial selection when value is not controlled. */
+    defaultValue: Value;
+    /** Controlled selection; omit to keep selection inside TabView. */
+    value?: Value;
+    onValueChange?: (value: Value) => void;
+    /** Tab alignment: `start` or `center`. @default "center" */
+    align?: TabViewAlign;
+    /** Accessible name for the tab list. */
+    label: string;
+    /** Renders the selected tab's panel. */
+    children: (value: Value) => ReactNode;
+    className?: string;
+}
+/** Content tabs with native buttons, roving focus and automatic keyboard activation. */
+export declare function TabView<Value extends string>({ options, defaultValue, value: controlledValue, onValueChange, align, label, children, className, }: TabViewProps<Value>): import("react").JSX.Element | null;

package/dist/types/src/components/table/table.d.ts

@@ -0,0 +1,10 @@
+import type * as React from "react";
+declare function Table({ className, ...props }: React.ComponentProps<"table">): React.JSX.Element;
+declare function TableHeader({ className, ...props }: React.ComponentProps<"thead">): React.JSX.Element;
+declare function TableBody({ className, ...props }: React.ComponentProps<"tbody">): React.JSX.Element;
+declare function TableFooter({ className, ...props }: React.ComponentProps<"tfoot">): React.JSX.Element;
+declare function TableRow({ className, ...props }: React.ComponentProps<"tr">): React.JSX.Element;
+declare function TableHead({ className, ...props }: React.ComponentProps<"th">): React.JSX.Element;
+declare function TableCell({ className, ...props }: React.ComponentProps<"td">): React.JSX.Element;
+declare function TableCaption({ className, ...props }: React.ComponentProps<"caption">): React.JSX.Element;
+export { Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow };

package/dist/types/src/components/text-editor/text-editor.d.ts

@@ -0,0 +1,2 @@
+import type { ComponentProps } from "react";
+export declare function TextEditor({ className, ...props }: ComponentProps<"textarea">): import("react").JSX.Element;

package/dist/types/src/components/text-field/text-field.d.ts

@@ -0,0 +1,20 @@
+import { type ComponentProps, type ReactNode } from "react";
+export declare const textControlClasses: string;
+export type TextFieldProps = ComponentProps<"input"> & {
+    label: string;
+    description?: ReactNode;
+    errors?: string[];
+    /** A decorative icon before the text, such as a mail glyph. */
+    icon?: ReactNode;
+    /** A decorative icon after the text, such as a unit or a check. */
+    trailingIcon?: ReactNode;
+    /** An interactive control after the text, such as a clear button. Size it to the field: an `xs` or `icon-xs` button, never the default. */
+    action?: ReactNode;
+    revealLabels?: {
+        show: string;
+        hide: string;
+    };
+    /** Float the label into the outline on focus or when filled. @default "above" */
+    labelPlacement?: "above" | "floating";
+};
+export declare function TextField({ label, description, errors, icon, trailingIcon, action, revealLabels, labelPlacement, placeholder, type, id: suppliedId, className, ...props }: TextFieldProps): import("react").JSX.Element;

package/dist/types/src/components/toast/toast-store.d.ts

@@ -0,0 +1,47 @@
+/**
+ * App-wide toasts: short messages that confirm, report progress or explain
+ * a failure. Call `toast` from anywhere; render one `<Toaster />`.
+ */
+export type ToastTone = "neutral" | "success" | "error" | "loading";
+export interface ToastAction {
+    label: string;
+    onClick: () => void;
+}
+export interface Toast {
+    id: number;
+    tone: ToastTone;
+    title: string;
+    description?: string;
+    action?: ToastAction;
+    /** Milliseconds before it leaves on its own; `null` stays until dismissed. */
+    duration: number | null;
+    createdAt: number;
+}
+export interface ToastOptions {
+    description?: string;
+    action?: ToastAction;
+    duration?: number | null;
+}
+/** Changes a toast in place; it morphs to its new state. */
+declare function update(id: number, tone: ToastTone, title: string, options?: ToastOptions): number;
+declare function dismiss(id: number): void;
+interface PromiseMessages<T> {
+    loading: string;
+    success: string | ((value: T) => string);
+    error: string | ((error: unknown) => string);
+}
+export declare const toast: ((title: string, options?: ToastOptions) => number) & {
+    success: (title: string, options?: ToastOptions) => number;
+    error: (title: string, options?: ToastOptions) => number;
+    loading: (title: string, options?: ToastOptions) => number;
+    update: typeof update;
+    dismiss: typeof dismiss;
+    /** Shows progress, then morphs into the outcome. Returns the promise. */
+    promise<T>(promise: Promise<T>, messages: PromiseMessages<T>): Promise<T>;
+};
+export declare function subscribeToasts(listener: () => void): () => void;
+export declare function getToasts(): Toast[];
+export declare const toastLimits: {
+    readonly visible: 3;
+};
+export {};

package/dist/types/src/components/toast/toaster.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Toasts drop from the top centre like an island: a small pill carrying the
+ * icon, out of which the message flows. Both shapes sit under an SVG "goo"
+ * filter, so where they meet looks liquid while they grow, morph between
+ * states and shrink away. Text is drawn above the filter to stay crisp.
+ */
+export declare function Toaster({ className, label, }: {
+    className?: string;
+    label?: string;
+}): import("react").JSX.Element;

package/dist/types/src/components/toggle/toggle.d.ts

@@ -0,0 +1,17 @@
+export type ToggleStyle = "switch" | "checkbox";
+export interface ToggleProps {
+    /** Current on or off state. */
+    checked: boolean;
+    /** Called with the next checked state. */
+    onChange: (checked: boolean) => void;
+    /** Accessible name, including when the visible label is hidden. */
+    label: string;
+    disabled?: boolean;
+    /** `switch` for a setting, `checkbox` for a selection. @default "switch" */
+    style?: ToggleStyle;
+    /** Reports a mixed selection to assistive technology. @default false */
+    mixed?: boolean;
+    /** Keeps the accessible name while hiding the visible label. @default false */
+    labelHidden?: boolean;
+}
+export declare function Toggle({ checked, onChange, label, disabled, style, mixed, labelHidden, }: ToggleProps): import("react").JSX.Element;

package/dist/types/src/components/tooltip/tooltip-host.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Tooltips for any element with `data-tooltip`, on devices that can hover.
+ * One listener for the whole app: a short delay before the first, then
+ * instant while moving between controls, as on macOS.
+ */
+export declare function TooltipHost(): import("react").JSX.Element;

package/dist/types/src/components/view-controller/index.d.ts

@@ -0,0 +1 @@
+export * from "./view-controller";

package/dist/types/src/components/view-controller/view-controller.d.ts

@@ -0,0 +1,21 @@
+import type { PropsWithChildren, ReactNode } from "react";
+type ViewControllerProps = PropsWithChildren<{
+    heading: ReactNode;
+    className?: string;
+}>;
+type HeadingProps = {
+    title: ReactNode;
+    description?: ReactNode;
+    action?: ReactNode;
+    size?: keyof typeof titleSizes;
+};
+declare const titleSizes: {
+    readonly default: "text-3xl md:text-4xl";
+    readonly compact: "text-[1.75rem] font-semibold tracking-tight";
+};
+export declare function ViewController({ heading, className, children }: ViewControllerProps): import("react").JSX.Element;
+export declare namespace ViewController {
+    export { Heading };
+}
+declare function Heading({ title, description, action, size }: HeadingProps): import("react").JSX.Element;
+export {};

package/dist/types/src/components/wake-slider/wake-slider.d.ts

@@ -0,0 +1,12 @@
+export interface WakeSliderProps {
+    label: string;
+    value?: number;
+    defaultValue?: number;
+    onChange?: (value: number) => void;
+    bars?: number;
+    wake?: number;
+    disabled?: boolean;
+    className?: string;
+    formatValue?: (value: number) => string;
+}
+export declare function WakeSlider({ label, value: controlledValue, defaultValue, onChange, disabled, className, formatValue, bars, wake, }: WakeSliderProps): import("react").JSX.Element;

package/dist/types/src/hooks/scroll/minimize-decision.d.ts

@@ -0,0 +1,2 @@
+/** Programmatic restoration does not collapse chrome; reaching the top always restores it. */
+export declare function minimizeDecision(top: number, anchor: number, userDriven: boolean): boolean | null;

package/dist/types/src/hooks/use-anchored-disclosure.d.ts

@@ -0,0 +1,9 @@
+/** Keep the panel mounted until its material has returned to the trigger. */
+export declare function useAnchoredDisclosure(disabled?: boolean): {
+    open: boolean;
+    mounted: boolean;
+    show: () => void;
+    toggle: () => void;
+    close: () => void;
+    onExited: () => void;
+};

package/dist/types/src/hooks/use-anchored-placement.d.ts

@@ -0,0 +1,7 @@
+import { type AnchoredPlacement } from "../lib/anchored-placement";
+/**
+ * Places a panel of `width` and `needed` height under its anchor and
+ * keeps it there: re-places while the viewport resizes or anything
+ * scrolls, so it never hangs off the screen.
+ */
+export declare function useAnchoredPlacement(anchor: HTMLElement, width: number, needed: number, overlap?: boolean): AnchoredPlacement;

package/dist/types/src/hooks/use-dismiss.d.ts

@@ -0,0 +1,9 @@
+import { type RefObject } from "react";
+/** Marks a floating layer (a pop-up list, a menu) whose clicks belong to what opened it. */
+export { FLOATING_LAYER } from "../lib/floating-layers";
+/**
+ * Calls `onDismiss` when the user presses Escape or clicks outside `ref`
+ * while `active`, for menus, popovers and sheets. Clicks in a floating
+ * layer opened from inside, such as a pop-up button's list, don't count.
+ */
+export declare function useDismiss(ref: RefObject<HTMLElement | null>, active: boolean, onDismiss: () => void): void;

package/dist/types/src/hooks/use-floating-dismiss.d.ts

@@ -0,0 +1,3 @@
+import { type RefObject } from "react";
+/** Dismiss an anchored portal without stealing focus from outside pointer interactions. */
+export declare function useFloatingDismiss(surface: RefObject<HTMLElement | null>, anchor: HTMLElement, onDismiss: (restoreFocus: boolean) => void): void;

package/dist/types/src/hooks/use-media-query.d.ts

@@ -0,0 +1,21 @@
+declare const BREAKPOINTS: {
+    readonly "2xl": 1536;
+    readonly "3xl": 1600;
+    readonly "4xl": 2000;
+    readonly lg: 1024;
+    readonly md: 800;
+    readonly sm: 640;
+    readonly xl: 1280;
+};
+export type Breakpoint = keyof typeof BREAKPOINTS;
+export type BreakpointQuery = Breakpoint | `max-${Breakpoint}` | `${Breakpoint}:max-${Breakpoint}`;
+export type MediaQueryInput = {
+    min?: Breakpoint | number;
+    max?: Breakpoint | number;
+    /** Touch-like input (finger). Use "fine" for mouse/trackpad. */
+    pointer?: PointerPrecision;
+};
+export type PointerPrecision = "coarse" | "fine";
+export declare function useMediaQuery(query: BreakpointQuery | MediaQueryInput | (string & {})): boolean;
+export declare function useIsMobile(): boolean;
+export {};

package/dist/types/src/hooks/use-minimize-on-scroll.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Minimized while you scroll down through content, restored when you scroll
+ * back up or reach the top: iOS 26's `tabBarMinimizeBehavior(.onScrollDown)`.
+ * Listens to every scroll container, since each screen scrolls its own pane.
+ */
+export declare function useMinimizeOnScroll(): readonly [boolean, import("react").Dispatch<import("react").SetStateAction<boolean>>];

package/dist/types/src/hooks/use-visual-viewport.d.ts

@@ -0,0 +1,4 @@
+import type { ViewportMetrics } from "./viewport/types";
+export type { ViewportMetrics } from "./viewport/types";
+/** Measures once per frame, including Android resize and Safari viewport panning. */
+export declare function useVisualViewport(): ViewportMetrics | null;

package/dist/types/src/hooks/viewport/types.d.ts

@@ -0,0 +1,19 @@
+export type ViewportInput = {
+    width: number;
+    height: number;
+    top: number;
+    left: number;
+    layoutHeight: number;
+    editing: boolean;
+};
+export type ViewportMetrics = {
+    width: number;
+    height: number;
+    top: number;
+    left: number;
+    keyboardOpen: boolean;
+};
+export type ViewportBaseline = {
+    width: number;
+    height: number;
+};

package/dist/types/src/hooks/viewport/viewport-metrics.d.ts

@@ -0,0 +1,3 @@
+import type { ViewportBaseline, ViewportInput, ViewportMetrics } from "./types";
+/** A resized WebView and Safari's overlaid keyboard share one visible rectangle. */
+export declare function viewportMetrics(input: ViewportInput, baseline: ViewportBaseline): ViewportMetrics;