@inkra/react 0.6.0 → 0.9.0

package/dist/layout/GridResizable.js

@@ -0,0 +1,35 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment, forwardRef, useId, useState } from 'react';
+import { Resizable } from '../resizable/index.js';
+const equal = (a, b) => Object.keys(a).length === Object.keys(b).length
+    && Object.keys(a).every(key => Math.abs(a[key] - (b[key] ?? -1)) < 0.001);
+const even = (tracks) => Object.fromEntries(tracks.map(track => [track.id, 100 / tracks.length]));
+const scoped = (layout, prefix) => Object.fromEntries(Object.entries(layout).map(([key, value]) => [`${prefix}${key}`, value]));
+const unscoped = (layout, prefix) => Object.fromEntries(Object.entries(layout).map(([key, value]) => [key.slice(prefix.length), value]));
+/** Shared column sizes keep every row aligned; the existing Resizable engine owns all gestures. */
+export const GridResizable = forwardRef(function GridResizable({ columns, rows, columnSizes, defaultColumnSizes, rowSizes, defaultRowSizes, onColumnSizesChange, onRowSizesChange, onColumnSizesCommit, onRowSizesCommit, resizeColumns = true, resizeRows = true, disabled = false, getHandleLabel, className, children, ...props }, ref) {
+    const id = useId();
+    const [localColumns, setColumns] = useState(() => defaultColumnSizes ?? even(columns));
+    const [localRows, setRows] = useState(() => defaultRowSizes ?? even(rows));
+    const currentColumns = columnSizes ?? localColumns;
+    const currentRows = rowSizes ?? localRows;
+    const rowPrefix = `${id}-row-`;
+    const changeColumns = (next) => {
+        if (equal(next, currentColumns))
+            return;
+        if (columnSizes === undefined)
+            setColumns(next);
+        onColumnSizesChange?.(next);
+    };
+    const changeRows = (next) => {
+        if (equal(next, currentRows))
+            return;
+        if (rowSizes === undefined)
+            setRows(next);
+        onRowSizesChange?.(next);
+    };
+    return _jsx("div", { ...props, ref: ref, className: ['inkra-grid-resizable', className].filter(Boolean).join(' '), children: _jsx(Resizable.Root, { id: `${id}-rows`, orientation: "vertical", disabled: disabled || !resizeRows, layout: scoped(currentRows, rowPrefix), onLayoutChange: next => changeRows(unscoped(next, rowPrefix)), onLayoutCommit: next => onRowSizesCommit?.(unscoped(next, rowPrefix)), children: rows.map((row, rowIndex) => {
+                const columnPrefix = `${id}-${row.id}-column-`;
+                return _jsxs(Fragment, { children: [rowIndex > 0 && _jsx(Resizable.Handle, { label: getHandleLabel?.('row', rows[rowIndex - 1].id, row.id) }), _jsx(Resizable.Panel, { ...row, id: `${rowPrefix}${row.id}`, children: _jsx(Resizable.Root, { id: `${id}-${row.id}-columns`, disabled: disabled || !resizeColumns, layout: scoped(currentColumns, columnPrefix), onLayoutChange: next => changeColumns(unscoped(next, columnPrefix)), onLayoutCommit: next => onColumnSizesCommit?.(unscoped(next, columnPrefix)), children: columns.map((column, columnIndex) => _jsxs(Fragment, { children: [columnIndex > 0 && _jsx(Resizable.Handle, { label: getHandleLabel?.('column', columns[columnIndex - 1].id, column.id) }), _jsx(Resizable.Panel, { ...column, id: `${columnPrefix}${column.id}`, children: _jsx("div", { className: "inkra-grid-resizable__cell", children: children({ row: row.id, column: column.id, rowIndex, columnIndex }) }) })] }, column.id)) }) })] }, row.id);
+            }) }) });
+});

package/dist/layout/index.d.ts

@@ -1,4 +1,11 @@
-import type { CSSProperties, HTMLAttributes } from 'react';
+import type { CSSProperties, HTMLAttributes, ReactNode } from 'react';
+import { GridBoard } from './GridBoard.js';
+import { type LayoutSwipeNavigation } from './swipeNavigation.js';
+export type { LayoutSwipeNavigation } from './swipeNavigation.js';
+export { GridResizable } from './GridResizable.js';
+export type { GridResizableProps, GridTrack } from './GridResizable.js';
+export { GridBoard } from './GridBoard.js';
+export type { GridBoardProps, GridBoardLayout, GridBoardLayoutItem } from './GridBoard.js';
 export type LayoutSpace = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | 12 | 16;
 export type LayoutElement = 'div' | 'section' | 'article' | 'nav' | 'header' | 'footer' | 'main' | 'aside' | 'ul' | 'ol' | 'li';
 export type LayoutAlign = 'start' | 'center' | 'end' | 'stretch' | 'baseline';
@@ -30,7 +37,10 @@ export interface GridProps extends LayoutElementProps {
     columnGap?: LayoutSpace;
     align?: LayoutAlign;
 }
-export declare const Grid: import("react").ForwardRefExoticComponent<GridProps & import("react").RefAttributes<HTMLElement>>;
+export declare const Grid: import("react").ForwardRefExoticComponent<GridProps & import("react").RefAttributes<HTMLElement>> & {
+    Resizable: import("react").ForwardRefExoticComponent<import("./GridResizable.js").GridResizableProps & import("react").RefAttributes<HTMLDivElement>>;
+    Board: typeof GridBoard;
+};
 export interface ContainerProps extends LayoutElementProps {
     size?: 'sm' | 'md' | 'lg' | 'xl' | 'full';
     padding?: LayoutSpace;
@@ -40,6 +50,8 @@ export declare const Container: import("react").ForwardRefExoticComponent<Contai
 export interface LayoutProps extends LayoutElementProps {
     gap?: LayoutSpace;
     collapseAt?: 'sm' | 'md' | 'never';
+    sidebarWidth?: CSSProperties['width'];
+    swipeNavigation?: LayoutSwipeNavigation;
 }
 export interface LayoutBodyProps extends LayoutElementProps {
     gap?: LayoutSpace;
@@ -51,13 +63,16 @@ export interface LayoutRegionProps extends LayoutElementProps {
 export interface LayoutSidebarProps extends LayoutRegionProps {
     width?: CSSProperties['width'];
 }
+export interface LayoutHeaderProps extends LayoutRegionProps {
+    sidebar?: ReactNode;
+    sidebarDivided?: boolean;
+}
 export type LayoutContentProps = Omit<LayoutRegionProps, 'divided'>;
 export declare const Layout: Readonly<{
     Root: import("react").ForwardRefExoticComponent<LayoutProps & import("react").RefAttributes<HTMLElement>>;
-    Header: import("react").ForwardRefExoticComponent<LayoutRegionProps & import("react").RefAttributes<HTMLElement>>;
+    Header: import("react").ForwardRefExoticComponent<LayoutHeaderProps & import("react").RefAttributes<HTMLElement>>;
     Body: import("react").ForwardRefExoticComponent<LayoutBodyProps & import("react").RefAttributes<HTMLElement>>;
     Sidebar: import("react").ForwardRefExoticComponent<LayoutSidebarProps & import("react").RefAttributes<HTMLElement>>;
     Content: import("react").ForwardRefExoticComponent<LayoutContentProps & import("react").RefAttributes<HTMLElement>>;
     Footer: import("react").ForwardRefExoticComponent<LayoutRegionProps & import("react").RefAttributes<HTMLElement>>;
 }>;
-export {};

package/dist/layout/index.js

@@ -1,6 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { createElement, forwardRef } from 'react';
+import { createContext, createElement, forwardRef, useContext, useRef } from 'react';
 import { PencilLine } from '../PencilLine.js';
+import { GridResizable } from './GridResizable.js';
+import { GridBoard } from './GridBoard.js';
+import { useBrowserLayoutEffect } from '../internal/useBrowserLayoutEffect.js';
+import { createLayoutSwipeNavigation } from './swipeNavigation.js';
+export { GridResizable } from './GridResizable.js';
+export { GridBoard } from './GridBoard.js';
 const Box = forwardRef(function Box({ as = 'div', ...props }, ref) {
     return createElement(as, { ...props, ref });
 });
@@ -17,7 +23,7 @@ export const Stack = forwardRef(function Stack({ direction = 'column', className
     return _jsx(Flex, { ...props, ref: ref, direction: direction, className: classes('inkra-stack', className) });
 });
 const columnCount = (value, fallback) => value === undefined || !Number.isFinite(value) ? fallback : Math.min(12, Math.max(1, Math.trunc(value)));
-export const Grid = forwardRef(function Grid({ as: Element = 'div', columns = 1, gap = 3, rowGap = gap, columnGap = gap, align = 'stretch', className, style, ...props }, ref) {
+const GridRoot = forwardRef(function Grid({ as: Element = 'div', columns = 1, gap = 3, rowGap = gap, columnGap = gap, align = 'stretch', className, style, ...props }, ref) {
     const responsive = typeof columns === 'number' ? { base: columns } : columns;
     const base = columnCount(responsive.base, 1);
     const sm = columnCount(responsive.sm, base);
@@ -29,29 +35,59 @@ export const Grid = forwardRef(function Grid({ as: Element = 'div', columns = 1,
     };
     return _jsx(Box, { as: Element, ...props, ref: ref, className: classes('inkra-grid', className), style: resolvedStyle });
 });
+export const Grid = /* @__PURE__ */ Object.assign(GridRoot, { Resizable: GridResizable, Board: GridBoard });
 const containerWidths = { sm: '640px', md: '768px', lg: '1024px', xl: '1280px', full: 'none' };
 export const Container = forwardRef(function Container({ as: Element = 'div', size = 'lg', padding = 5, centered = true, className, style, ...props }, ref) {
     return _jsx(Box, { as: Element, ...props, ref: ref, className: classes('inkra-container', className), style: { maxWidth: containerWidths[size], paddingInline: space(padding),
             marginInline: centered ? 'auto' : 0, ...style } });
 });
-const LayoutRoot = forwardRef(function LayoutRoot({ as: Element = 'div', gap = 0, collapseAt = 'sm', className, style, ...props }, ref) {
-    return _jsx(Box, { as: Element, ...props, ref: ref, className: classes('inkra-layout', className), "data-collapse-at": collapseAt, style: { gap: space(gap), ...style } });
+const LayoutColumnContext = createContext(false);
+const normalizeSidebarWidth = (width = 240) => typeof width === 'number' ? (Number.isFinite(width) ? Math.max(0, width) : 240) : width;
+const isCollapsedWidth = (width) => width === 0 || (typeof width === 'string' && /^0(?:\.0+)?(?:[a-z]+|%)?$/i.test(width.trim()));
+const LayoutRoot = forwardRef(function LayoutRoot({ as: Element = 'div', gap = 0, collapseAt = 'sm', sidebarWidth = 240, className, style, swipeNavigation, onTouchStart, ...props }, ref) {
+    const sharedWidth = normalizeSidebarWidth(sidebarWidth);
+    const resolvedStyle = {
+        '--inkra-layout-shared-sidebar-width': typeof sharedWidth === 'number' ? `${sharedWidth}px` : sharedWidth,
+        gap: space(gap), ...style,
+    };
+    const options = useRef(swipeNavigation);
+    const gesture = useRef(null);
+    if (!gesture.current)
+        gesture.current = createLayoutSwipeNavigation(() => options.current);
+    useBrowserLayoutEffect(() => { options.current = swipeNavigation; });
+    useBrowserLayoutEffect(() => { gesture.current?.cancel(); }, [swipeNavigation?.enabled, swipeNavigation?.open, swipeNavigation?.side, swipeNavigation?.edgeWidth, swipeNavigation?.threshold]);
+    useBrowserLayoutEffect(() => () => gesture.current?.dispose(), []);
+    return _jsx(LayoutColumnContext.Provider, { value: isCollapsedWidth(sharedWidth), children: _jsx(Box, { as: Element, ...props, ref: ref, className: classes('inkra-layout', className), onTouchStart: event => {
+                onTouchStart?.(event);
+                if (!event.defaultPrevented)
+                    gesture.current?.start(event.nativeEvent, event.currentTarget);
+            }, "data-collapse-at": collapseAt, style: resolvedStyle }) });
 });
 const LayoutBody = forwardRef(function LayoutBody({ as: Element = 'div', gap = 0, className, style, ...props }, ref) {
     return _jsx(Box, { as: Element, ...props, ref: ref, className: classes('inkra-layout__body', className), style: { gap: space(gap), ...style } });
 });
-const LayoutHeader = forwardRef(function LayoutHeader({ as: Element = 'header', padding = 5, divided = false, className, style, children, ...props }, ref) {
-    return _jsxs(Box, { as: Element, ...props, ref: ref, className: classes('inkra-layout__header', className), style: { padding: space(padding), ...style }, children: [children, divided && _jsx(PencilLine, { className: "inkra-layout__divider" })] });
+const LayoutHeader = forwardRef(function LayoutHeader({ as: Element = 'header', padding = 5, divided = false, sidebar, sidebarDivided = false, className, style, children, ...props }, ref) {
+    const collapsed = useContext(LayoutColumnContext);
+    const split = sidebar !== undefined && sidebar !== null && typeof sidebar !== 'boolean';
+    const resolvedStyle = {
+        '--inkra-layout-header-padding': space(padding),
+        padding: split ? 0 : space(padding), ...style,
+    };
+    return _jsxs(Box, { as: Element, ...props, ref: ref, className: classes('inkra-layout__header', className), "data-shared-sidebar": split || undefined, style: resolvedStyle, children: [split ? _jsxs(_Fragment, { children: [_jsxs("div", { className: "inkra-layout__header-sidebar", hidden: collapsed, inert: collapsed || undefined, "aria-hidden": collapsed || undefined, children: [sidebar, sidebarDivided && _jsx(PencilLine, { className: "inkra-layout__header-sidebar-divider", orientation: "vertical" })] }), _jsx("div", { className: "inkra-layout__header-content", children: children })] }) : children, divided && _jsx(PencilLine, { className: "inkra-layout__divider" })] });
 });
 const LayoutFooter = forwardRef(function LayoutFooter({ as: Element = 'footer', padding = 5, divided = false, className, style, children, ...props }, ref) {
     return _jsxs(Box, { as: Element, ...props, ref: ref, className: classes('inkra-layout__footer', className), style: { padding: space(padding), ...style }, children: [divided && _jsx(PencilLine, { className: "inkra-layout__divider" }), children] });
 });
-const LayoutSidebar = forwardRef(function LayoutSidebar({ as: Element = 'aside', width = 240, padding = 5, divided = false, className, style, children, ...props }, ref) {
+const LayoutSidebar = forwardRef(function LayoutSidebar({ as: Element = 'aside', width, padding = 5, divided = false, className, style, children, hidden, inert, ...props }, ref) {
+    const sharedCollapsed = useContext(LayoutColumnContext);
+    const resolvedWidth = width === undefined ? undefined : normalizeSidebarWidth(width);
+    const collapsed = resolvedWidth === undefined ? sharedCollapsed : isCollapsedWidth(resolvedWidth);
     const resolvedStyle = {
-        '--inkra-layout-sidebar-width': typeof width === 'number' ? `${width}px` : width,
+        '--inkra-layout-sidebar-width': resolvedWidth === undefined ? 'var(--inkra-layout-shared-sidebar-width, 240px)'
+            : typeof resolvedWidth === 'number' ? `${resolvedWidth}px` : resolvedWidth,
         padding: space(padding), ...style,
     };
-    return _jsxs(Box, { as: Element, ...props, ref: ref, className: classes('inkra-layout__sidebar', className), style: resolvedStyle, children: [children, divided && _jsxs(_Fragment, { children: [_jsx(PencilLine, { className: "inkra-layout__sidebar-divider", orientation: "vertical" }), _jsx(PencilLine, { className: "inkra-layout__sidebar-divider-mobile" })] })] });
+    return _jsxs(Box, { as: Element, ...props, ref: ref, hidden: collapsed || hidden, inert: collapsed || inert, "aria-hidden": collapsed ? true : props['aria-hidden'], className: classes('inkra-layout__sidebar', className), style: resolvedStyle, children: [children, divided && _jsxs(_Fragment, { children: [_jsx(PencilLine, { className: "inkra-layout__sidebar-divider", orientation: "vertical" }), _jsx(PencilLine, { className: "inkra-layout__sidebar-divider-mobile" })] })] });
 });
 const LayoutContent = forwardRef(function LayoutContent({ as: Element = 'div', padding = 5, className, style, ...props }, ref) {
     return _jsx(Box, { as: Element, ...props, ref: ref, className: classes('inkra-layout__content', className), style: { padding: space(padding), ...style } });

package/dist/layout/swipeNavigation.d.ts

@@ -0,0 +1,15 @@
+export interface LayoutSwipeNavigation {
+    enabled?: boolean;
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    side?: 'start' | 'end';
+    /** Opening starts within this many local CSS pixels of the sidebar edge. */
+    edgeWidth?: number;
+    /** Minimum horizontal travel before release commits the gesture. */
+    threshold?: number;
+}
+export declare function createLayoutSwipeNavigation(read: () => LayoutSwipeNavigation | undefined): {
+    start: (event: TouchEvent, root: HTMLElement) => void;
+    cancel: () => void;
+    dispose: () => void;
+};

package/dist/layout/swipeNavigation.js

@@ -0,0 +1,121 @@
+const ignored = 'input, textarea, select, [contenteditable]:not([contenteditable="false"]), [role="slider"], [role="spinbutton"], [role="combobox"], [role="separator"], [role="listbox"], video, audio, [data-layout-swipe-ignore]';
+const positive = (value, fallback) => value !== undefined && Number.isFinite(value) && value > 0 ? value : fallback;
+// Listen only for the lifetime of one edge/closing gesture. Vertical scroll and
+// nested horizontal tools keep their native behavior; no global touch-action override.
+export function createLayoutSwipeNavigation(read) {
+    let cancel = () => { };
+    let clearClick = () => { };
+    function start(event, root) {
+        clearClick();
+        cancel();
+        const options = read();
+        const view = root.ownerDocument.defaultView;
+        if (!options || options.enabled === false || !view || event.defaultPrevented || event.touches.length !== 1)
+            return;
+        const target = event.target;
+        if (!target?.closest || target.closest(ignored) || target.closest('.inkra-layout') !== root)
+            return;
+        for (let node = target; node && node !== root; node = node.parentElement) {
+            if (node.scrollWidth > node.clientWidth + 1 && /auto|scroll/.test(view.getComputedStyle(node).overflowX))
+                return;
+        }
+        const rect = root.getBoundingClientRect();
+        if (!rect.width || !root.clientWidth)
+            return;
+        const scale = root.clientWidth / rect.width;
+        const touch = event.touches[0];
+        const rtl = view.getComputedStyle(root).direction === 'rtl';
+        const right = (options.side === 'end') !== rtl;
+        const edge = Math.min(root.clientWidth / 2, positive(options.edgeWidth, 24));
+        const startX = (touch.clientX - rect.left) * scale;
+        if (!options.open && (right ? root.clientWidth - startX : startX) > edge)
+            return;
+        const direction = (right ? -1 : 1) * (options.open ? -1 : 1);
+        const threshold = positive(options.threshold, 48);
+        const doc = root.ownerDocument;
+        let locked = false;
+        let stopped = false;
+        let travel = 0;
+        const suppressClick = () => {
+            clearClick();
+            const block = (click) => {
+                if (!click.detail || ('pointerType' in click && click.pointerType !== 'touch'))
+                    return;
+                click.preventDefault();
+                click.stopImmediatePropagation();
+                clearClick();
+            };
+            root.addEventListener('click', block, { capture: true });
+            const timer = view.setTimeout(() => clearClick(), 700);
+            clearClick = () => {
+                root.removeEventListener('click', block, { capture: true });
+                view.clearTimeout(timer);
+                clearClick = () => { };
+            };
+        };
+        const cleanup = () => {
+            stopped = true;
+            doc.removeEventListener('touchstart', multi);
+            doc.removeEventListener('touchmove', move);
+            doc.removeEventListener('touchend', end);
+            doc.removeEventListener('touchcancel', abort);
+            view.removeEventListener('blur', abort);
+            if (locked)
+                suppressClick();
+            cancel = () => { };
+        };
+        const valid = () => {
+            const next = read();
+            return root.isConnected && next && next.enabled !== false && next.open === options.open
+                && (next.side ?? 'start') === (options.side ?? 'start')
+                && (view.getComputedStyle(root).direction === 'rtl') === rtl
+                && Math.abs(root.getBoundingClientRect().width - rect.width) < 1;
+        };
+        const abort = () => cleanup();
+        const multi = (next) => { if (next.touches.length !== 1)
+            cleanup(); };
+        const move = (next) => {
+            if (stopped)
+                return;
+            const point = Array.from(next.touches).find(item => item.identifier === touch.identifier);
+            if (!valid() || next.defaultPrevented || next.touches.length !== 1 || !point) {
+                cleanup();
+                return;
+            }
+            const dx = (point.clientX - touch.clientX) * scale;
+            const dy = (point.clientY - touch.clientY) * scale;
+            if (!locked) {
+                if (Math.max(Math.abs(dx), Math.abs(dy)) < 8)
+                    return;
+                if (dx * direction <= 0 || Math.abs(dx) < Math.abs(dy) * 1.25) {
+                    cleanup();
+                    return;
+                }
+            }
+            if (!next.cancelable) {
+                cleanup();
+                return;
+            }
+            locked = true;
+            travel = Math.abs(dx) >= Math.abs(dy) * 1.25 ? dx * direction : 0;
+            next.preventDefault();
+        };
+        const end = (next) => {
+            const point = Array.from(next.changedTouches).find(item => item.identifier === touch.identifier);
+            const dx = point ? (point.clientX - touch.clientX) * scale : 0;
+            const dy = point ? (point.clientY - touch.clientY) * scale : 0;
+            const commit = !next.defaultPrevented && next.touches.length === 0 && valid() && locked
+                && point && travel >= threshold && dx * direction >= threshold && Math.abs(dx) >= Math.abs(dy) * 1.25;
+            cleanup();
+            if (commit)
+                read()?.onOpenChange(!options.open);
+        };
+        doc.addEventListener('touchstart', multi, { passive: true });
+        doc.addEventListener('touchmove', move, { passive: false });
+        doc.addEventListener('touchend', end);
+        doc.addEventListener('touchcancel', abort);
+        view.addEventListener('blur', abort);
+        cancel = cleanup;
+    }
+    return { start, cancel: () => cancel(), dispose: () => { cancel(); clearClick(); } };
+}

package/dist/loading/index.d.ts

@@ -0,0 +1,58 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+import { type LoadingLabels } from './locales.js';
+import { type LoadingTipOrder } from './model.js';
+export type { LoadingLabels } from './locales.js';
+export type { LoadingTipOrder } from './model.js';
+export type LoadingMode = 'inline' | 'region' | 'fullscreen';
+export type LoadingPreset = 'brand-center' | 'scene-bottom' | 'intel' | 'staged' | 'edge' | 'skeleton';
+export type LoadingAnimation = 'progress' | 'orbit' | 'dots' | 'pulse' | 'trail';
+export type LoadingStatus = 'loading' | 'error' | 'complete';
+export type LoadingStageState = 'pending' | 'active' | 'complete' | 'error';
+export type LoadingSlot = 'top-start' | 'top-end' | 'center' | 'bottom-start' | 'bottom-center' | 'bottom-end';
+export type LoadingTipTransition = 'fade' | 'slide' | 'none';
+export interface LoadingStage {
+    id: string;
+    label: ReactNode;
+    state?: LoadingStageState;
+    description?: ReactNode;
+}
+export interface LoadingProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'title'> {
+    active?: boolean;
+    mode?: LoadingMode;
+    preset?: LoadingPreset;
+    animation?: LoadingAnimation;
+    status?: LoadingStatus;
+    blocking?: boolean;
+    lockScroll?: boolean;
+    delay?: number;
+    minDuration?: number;
+    logo?: ReactNode;
+    title?: ReactNode;
+    description?: ReactNode;
+    background?: ReactNode;
+    skeleton?: ReactNode;
+    children?: ReactNode;
+    slots?: Partial<Record<LoadingSlot, ReactNode>>;
+    progress?: number | null;
+    max?: number;
+    progressLabel?: ReactNode;
+    stages?: readonly LoadingStage[];
+    activeStage?: string;
+    tips?: readonly ReactNode[];
+    tipOrder?: LoadingTipOrder;
+    tipInterval?: number;
+    tipAutoPlay?: boolean;
+    tipPaused?: boolean;
+    defaultTipPaused?: boolean;
+    onTipPausedChange?: (paused: boolean) => void;
+    tipIndex?: number;
+    defaultTipIndex?: number;
+    onTipIndexChange?: (index: number) => void;
+    tipTransition?: LoadingTipTransition;
+    showTipControls?: boolean;
+    labels?: Partial<LoadingLabels>;
+    onCancel?: () => void;
+    onRetry?: () => void;
+    onContinue?: () => void;
+}
+export declare const Loading: import("react").ForwardRefExoticComponent<LoadingProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/loading/index.js

@@ -0,0 +1,188 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { FocusScope } from 'react-aria/FocusScope';
+import { ariaHideOutside } from 'react-aria/private/overlays/ariaHideOutside';
+import { usePreventScroll } from 'react-aria/usePreventScroll';
+import { forwardRef, useCallback, useEffect, useId, useMemo, useRef, useState, } from 'react';
+import { createPortal } from 'react-dom';
+import { Button } from '../Button.js';
+import { PencilLine } from '../PencilLine.js';
+import { PencilSurface } from '../PencilSurface.js';
+import { PencilText } from '../PencilText.js';
+import { Progress, Skeleton } from '../display/index.js';
+import { useInkraLocale } from '../i18n/index.js';
+import { PortalThemeBridge, PortalThemeProvider, usePortalTriggerRef, } from '../overlay/themeBridge.js';
+import { formatLoadingLabel, resolveLoadingLabels } from './locales.js';
+import { finiteDuration, nextTipIndex, normalizeLoadingMax, normalizeLoadingProgress, normalizeTipIndex, } from './model.js';
+function classes(...values) {
+    return values.filter(Boolean).join(' ');
+}
+function assignRef(ref, value) {
+    if (typeof ref === 'function')
+        ref(value);
+    else if (ref)
+        ref.current = value;
+}
+function useTimedPresence(active, delay, minDuration) {
+    const startsVisible = active && delay === 0;
+    const [present, setPresent] = useState(startsVisible);
+    const visibleAt = useRef(startsVisible ? Date.now() : null);
+    useEffect(() => {
+        let timer;
+        if (active) {
+            if (present)
+                return undefined;
+            timer = setTimeout(() => {
+                visibleAt.current = Date.now();
+                setPresent(true);
+            }, delay);
+        }
+        else if (present) {
+            const elapsed = visibleAt.current == null ? minDuration : Date.now() - visibleAt.current;
+            timer = setTimeout(() => {
+                visibleAt.current = null;
+                setPresent(false);
+            }, Math.max(0, minDuration - elapsed));
+        }
+        return () => clearTimeout(timer);
+    }, [active, delay, minDuration, present]);
+    return present;
+}
+function useControllableTipIndex(controlledIndex, defaultIndex, length, onChange) {
+    const [uncontrolledIndex, setUncontrolledIndex] = useState(() => normalizeTipIndex(defaultIndex, length));
+    const controlled = controlledIndex !== undefined;
+    const index = normalizeTipIndex(controlled ? controlledIndex : uncontrolledIndex, length);
+    const setIndex = useCallback((next) => {
+        const normalized = normalizeTipIndex(next, length);
+        if (!controlled)
+            setUncontrolledIndex(normalized);
+        if (normalized !== index)
+            onChange?.(normalized);
+    }, [controlled, index, length, onChange]);
+    return [index, setIndex];
+}
+function useControllableBoolean(value, defaultValue, onChange) {
+    const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue);
+    const controlled = value !== undefined;
+    const current = controlled ? value : uncontrolledValue;
+    const setCurrent = useCallback((next) => {
+        if (!controlled)
+            setUncontrolledValue(next);
+        if (next !== current)
+            onChange?.(next);
+    }, [controlled, current, onChange]);
+    return [current, setCurrent];
+}
+function DefaultSkeleton() {
+    return _jsxs("div", { className: "inkra-loading__skeleton", "aria-hidden": "true", children: [_jsx(Skeleton, { height: 28, width: "42%" }), _jsx(Skeleton, { height: 16, width: "88%" }), _jsx(Skeleton, { height: 16, width: "76%" }), _jsxs("div", { className: "inkra-loading__skeleton-grid", children: [_jsx(Skeleton, { height: 96 }), _jsx(Skeleton, { height: 96 }), _jsx(Skeleton, { height: 96 })] })] });
+}
+function LoadingAnimationVisual({ animation, seed }) {
+    const marks = [0, 1, 2];
+    return _jsx("span", { className: "inkra-loading__animation-visual", "data-kind": animation, "aria-hidden": "true", children: animation === 'trail'
+            ? marks.map(index => _jsx(PencilLine, { className: "inkra-loading__animation-mark", seed: `${seed}-trail-${index}` }, index))
+            : marks.map(index => _jsx(PencilSurface, { as: "span", "aria-hidden": "true", className: "inkra-loading__animation-mark", radius: 8, seed: `${seed}-${animation}-${index}`, variant: animation === 'pulse' ? 'outline' : 'quiet' }, index)) });
+}
+function stageState(stage, activeStage) {
+    if (stage.state)
+        return stage.state;
+    return stage.id === activeStage ? 'active' : 'pending';
+}
+function LoadingLayer({ 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, activeStage, animation = 'progress', background, blocking, children, className, defaultTipIndex, defaultTipPaused = false, description, forwardedRef, labelsResolved, lockScroll, logo, max, mode = 'inline', onCancel, onContinue, onRetry, onTipIndexChange, onTipPausedChange, preset = 'brand-center', present, progress, progressLabel, showTipControls = false, skeleton, slots, stages = [], status = 'loading', style, tipAutoPlay = true, tipIndex, tipInterval, tipOrder = 'sequence', tipPaused, tips = [], tipTransition = 'fade', title, ...props }) {
+    const id = useId();
+    const rootRef = useRef(null);
+    const titleId = `${id}-title`;
+    const resolvedMax = normalizeLoadingMax(max);
+    const resolvedProgress = normalizeLoadingProgress(progress, resolvedMax);
+    const showCustomAnimation = animation !== 'progress'
+        && status === 'loading'
+        && (progress === undefined || progress === null);
+    const showProgress = progress !== undefined
+        && (animation === 'progress' || progress !== null);
+    const interval = Math.max(1000, finiteDuration(tipInterval, 5000));
+    const [currentTip, setCurrentTip] = useControllableTipIndex(tipIndex, defaultTipIndex, tips.length, onTipIndexChange);
+    const [tipsPaused, setTipsPaused] = useControllableBoolean(tipPaused, defaultTipPaused, onTipPausedChange);
+    const activeStageIndex = stages.findIndex(stage => stage.id === activeStage || stageState(stage, activeStage) === 'active');
+    const stageAnnouncement = stages.length > 0 && activeStageIndex >= 0
+        ? formatLoadingLabel(labelsResolved.stageProgress, { current: activeStageIndex + 1, total: stages.length })
+        : undefined;
+    const defaultStatus = labelsResolved[status];
+    const effectiveBlocking = mode === 'fullscreen' && (blocking ?? preset !== 'edge');
+    const effectiveLockScroll = mode === 'fullscreen' && (lockScroll ?? effectiveBlocking);
+    usePreventScroll({ isDisabled: !(effectiveLockScroll && present) });
+    useEffect(() => {
+        if (!effectiveBlocking || !present || !rootRef.current)
+            return undefined;
+        return ariaHideOutside([rootRef.current], { shouldUseInert: true });
+    }, [effectiveBlocking, present]);
+    useEffect(() => {
+        if (!present || tips.length <= 1 || !tipAutoPlay || tipsPaused || status !== 'loading')
+            return undefined;
+        const timer = setInterval(() => setCurrentTip(nextTipIndex(currentTip, tips.length, tipOrder)), interval);
+        return () => clearInterval(timer);
+    }, [currentTip, interval, present, setCurrentTip, status, tipAutoPlay, tipOrder, tips.length, tipsPaused]);
+    const renderedTitle = title ?? defaultStatus;
+    const showActions = Boolean(onCancel || status === 'error' && onRetry || status === 'complete' && onContinue);
+    const hasInteractiveContent = showActions || showTipControls || children != null
+        || Object.values(slots ?? {}).some(node => node != null);
+    const semanticRole = effectiveBlocking ? 'dialog' : hasInteractiveContent ? 'region' : 'status';
+    const content = _jsxs("div", { ...props, "aria-busy": status === 'loading' || undefined, "aria-label": ariaLabel ?? (ariaLabelledBy || typeof renderedTitle === 'string' ? undefined : defaultStatus), "aria-labelledby": ariaLabelledBy ?? (typeof renderedTitle === 'string' ? titleId : undefined), "aria-live": semanticRole === 'status' ? 'polite' : undefined, "aria-modal": effectiveBlocking || undefined, className: classes('inkra-loading', className), "data-animation": animation, "data-blocking": effectiveBlocking || undefined, "data-mode": mode, "data-preset": preset, "data-status": status, ref: node => {
+            rootRef.current = node;
+            assignRef(forwardedRef, node);
+        }, role: semanticRole, style: style, tabIndex: effectiveBlocking ? -1 : undefined, children: [background == null ? null : _jsx("div", { className: "inkra-loading__background", "aria-hidden": "true", children: background }), _jsx("div", { className: "inkra-loading__veil", "aria-hidden": "true" }), semanticRole === 'region' ? _jsx("span", { className: "inkra-loading__sr-status", role: "status", children: defaultStatus }) : null, _jsx("div", { className: "inkra-loading__layout", children: _jsxs("div", { className: "inkra-loading__main", children: [logo == null ? null : _jsx("div", { className: "inkra-loading__logo", children: logo }), _jsxs("div", { className: "inkra-loading__copy", children: [typeof renderedTitle === 'string'
+                                    ? _jsx(PencilText, { as: "div", className: "inkra-loading__title", id: titleId, seed: `${id}-title`, children: renderedTitle })
+                                    : _jsx("div", { className: "inkra-loading__title", id: titleId, children: renderedTitle }), description == null ? null : typeof description === 'string'
+                                    ? _jsx(PencilText, { as: "div", className: "inkra-loading__description", seed: `${id}-description`, children: description })
+                                    : _jsx("div", { className: "inkra-loading__description", children: description })] }), showCustomAnimation ? _jsxs("div", { className: "inkra-loading__animation-progress", children: [progressLabel == null ? null : typeof progressLabel === 'string'
+                                    ? _jsx(PencilText, { as: "div", className: "inkra-loading__animation-label", children: progressLabel })
+                                    : _jsx("div", { className: "inkra-loading__animation-label", children: progressLabel }), _jsx("div", { "aria-label": typeof progressLabel === 'string' ? progressLabel : defaultStatus, className: "inkra-loading__animation", role: "progressbar", children: _jsx(LoadingAnimationVisual, { animation: animation, seed: `${id}-animation` }) })] }) : null, preset === 'skeleton' ? (skeleton ?? _jsx(DefaultSkeleton, {})) : null, stages.length > 0 ? _jsx("div", { className: "inkra-loading__stages", "aria-label": stageAnnouncement, children: stages.map((stage, index) => {
+                                const state = stageState(stage, activeStage);
+                                return _jsxs("div", { className: "inkra-loading__stage", "data-state": state, children: [_jsx(PencilSurface, { className: "inkra-loading__stage-marker", variant: state === 'active' ? 'selection' : state === 'error' ? 'danger' : 'outline', radius: 8, children: _jsx(PencilText, { children: state === 'complete' ? '✓' : state === 'error' ? '!' : String(index + 1) }) }), _jsxs("div", { className: "inkra-loading__stage-copy", children: [typeof stage.label === 'string' ? _jsx(PencilText, { children: stage.label }) : stage.label, stage.description == null ? null : _jsx("span", { className: "inkra-loading__stage-description", children: stage.description })] })] }, stage.id);
+                            }) }) : null, showProgress ? _jsx(Progress, { "aria-label": typeof progressLabel === 'string' ? progressLabel : defaultStatus, className: "inkra-loading__progress", label: progressLabel, max: resolvedMax, shape: preset === 'brand-center' ? 'circular' : 'linear', size: preset === 'brand-center' ? 'sm' : 'md', value: resolvedProgress ?? null, children: resolvedProgress == null || preset === 'brand-center' ? null : `${Math.round(resolvedProgress / resolvedMax * 100)}%` }) : null, tips.length > 0 ? _jsxs("div", { className: "inkra-loading__tips", "data-transition": tipTransition, children: [_jsx("div", { className: "inkra-loading__tip", children: tips[currentTip] }, `${currentTip}-${tipTransition}`), showTipControls && tips.length > 1 ? _jsxs("div", { className: "inkra-loading__tip-controls", children: [_jsx(Button, { "aria-label": labelsResolved.previousTip, size: "icon-sm", variant: "ghost", onClick: () => setCurrentTip(currentTip - 1), children: "\u2190" }), _jsxs("span", { className: "inkra-loading__tip-position", "aria-live": "off", children: [currentTip + 1, " / ", tips.length] }), tipAutoPlay ? _jsx(Button, { "aria-label": tipsPaused ? labelsResolved.resumeTips : labelsResolved.pauseTips, size: "icon-sm", variant: "ghost", onClick: () => setTipsPaused(!tipsPaused), children: tipsPaused ? '▶' : 'Ⅱ' }) : null, _jsx(Button, { "aria-label": labelsResolved.nextTip, size: "icon-sm", variant: "ghost", onClick: () => setCurrentTip(currentTip + 1), children: "\u2192" })] }) : null] }) : null, children == null ? null : _jsx("div", { className: "inkra-loading__content-layer", children: children }), showActions ? _jsxs("div", { className: "inkra-loading__actions", children: [onCancel ? _jsx(Button, { variant: "ghost", onClick: onCancel, children: labelsResolved.cancel }) : null, status === 'error' && onRetry ? _jsx(Button, { onClick: onRetry, children: labelsResolved.retry }) : null, status === 'complete' && onContinue ? _jsx(Button, { onClick: onContinue, children: labelsResolved.continue }) : null] }) : null] }) }), Object.entries(slots ?? {}).map(([slot, node]) => node == null ? null :
+                _jsx("div", { className: "inkra-loading__slot", "data-slot": slot, children: node }, slot)), preset === 'edge' ? _jsx(PencilLine, { className: "inkra-loading__edge-line", seed: `${id}-edge` }) : null] });
+    return effectiveBlocking
+        ? _jsx(FocusScope, { contain: true, restoreFocus: true, autoFocus: true, children: content })
+        : content;
+}
+function FullscreenPortal(props) {
+    const [mounted, setMounted] = useState(false);
+    const anchorRef = usePortalTriggerRef(null);
+    const restoreFocusRef = useRef(typeof document !== 'undefined' && document.activeElement instanceof HTMLElement
+        ? document.activeElement
+        : null);
+    const restoreGenerationRef = useRef(0);
+    useEffect(() => setMounted(true), []);
+    useEffect(() => {
+        const generation = ++restoreGenerationRef.current;
+        return () => {
+            const target = restoreFocusRef.current;
+            if (!target?.isConnected || typeof requestAnimationFrame !== 'function')
+                return;
+            requestAnimationFrame(() => {
+                if (restoreGenerationRef.current !== generation || !target.isConnected)
+                    return;
+                if (document.activeElement === document.body)
+                    target.focus({ preventScroll: true });
+            });
+        };
+    }, []);
+    const layer = _jsx(PortalThemeBridge, { children: _jsx(LoadingLayer, { ...props }) });
+    return _jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": "true", className: "inkra-loading__theme-anchor", ref: anchorRef }), mounted && typeof document !== 'undefined' ? createPortal(layer, document.body) : layer] });
+}
+export const Loading = forwardRef(function Loading({ active = true, delay, labels, minDuration, mode = 'inline', ...props }, ref) {
+    const { locale } = useInkraLocale();
+    const resolvedDelay = finiteDuration(delay, 0);
+    const resolvedMinDuration = finiteDuration(minDuration, 0);
+    const present = useTimedPresence(active, resolvedDelay, resolvedMinDuration);
+    const labelsResolved = useMemo(() => resolveLoadingLabels(locale, labels), [labels, locale]);
+    if (!present)
+        return null;
+    const layerProps = {
+        ...props,
+        forwardedRef: ref,
+        labelsResolved,
+        mode,
+        present,
+    };
+    return mode === 'fullscreen'
+        ? _jsx(PortalThemeProvider, { children: _jsx(FullscreenPortal, { ...layerProps }) })
+        : _jsx(LoadingLayer, { ...layerProps });
+});

package/dist/loading/locales.d.ts

@@ -0,0 +1,15 @@
+export interface LoadingLabels {
+    loading: string;
+    error: string;
+    complete: string;
+    cancel: string;
+    retry: string;
+    continue: string;
+    previousTip: string;
+    nextTip: string;
+    pauseTips: string;
+    resumeTips: string;
+    stageProgress: string;
+}
+export declare function resolveLoadingLabels(locale: string, overrides?: Partial<LoadingLabels>): LoadingLabels;
+export declare function formatLoadingLabel(template: string, values: Record<string, string | number>): string;

package/dist/loading/locales.js

@@ -0,0 +1,34 @@
+import { resolveInkraLocale } from '../i18n/index.js';
+const loadingLabels = {
+    en: {
+        loading: 'Loading', error: 'Unable to continue', complete: 'Ready', cancel: 'Cancel', retry: 'Retry',
+        continue: 'Continue', previousTip: 'Previous tip', nextTip: 'Next tip', pauseTips: 'Pause tips',
+        resumeTips: 'Resume tips', stageProgress: 'Step {current} of {total}',
+    },
+    'zh-CN': {
+        loading: '正在加载', error: '暂时无法继续', complete: '准备就绪', cancel: '取消', retry: '重试',
+        continue: '继续', previousTip: '上一条提示', nextTip: '下一条提示', pauseTips: '暂停提示',
+        resumeTips: '继续提示', stageProgress: '第 {current} 步，共 {total} 步',
+    },
+    ja: {
+        loading: '読み込み中', error: '続行できません', complete: '準備完了', cancel: 'キャンセル', retry: '再試行',
+        continue: '続ける', previousTip: '前のヒント', nextTip: '次のヒント', pauseTips: 'ヒントを一時停止',
+        resumeTips: 'ヒントを再開', stageProgress: '{total} ステップ中 {current}',
+    },
+    ko: {
+        loading: '불러오는 중', error: '계속할 수 없습니다', complete: '준비 완료', cancel: '취소', retry: '다시 시도',
+        continue: '계속', previousTip: '이전 도움말', nextTip: '다음 도움말', pauseTips: '도움말 일시 정지',
+        resumeTips: '도움말 계속', stageProgress: '{total}단계 중 {current}단계',
+    },
+    fr: {
+        loading: 'Chargement', error: 'Impossible de continuer', complete: 'Prêt', cancel: 'Annuler', retry: 'Réessayer',
+        continue: 'Continuer', previousTip: 'Conseil précédent', nextTip: 'Conseil suivant', pauseTips: 'Suspendre les conseils',
+        resumeTips: 'Reprendre les conseils', stageProgress: 'Étape {current} sur {total}',
+    },
+};
+export function resolveLoadingLabels(locale, overrides) {
+    return { ...loadingLabels[resolveInkraLocale(locale)], ...overrides };
+}
+export function formatLoadingLabel(template, values) {
+    return template.replace(/\{([A-Za-z][A-Za-z0-9]*)\}/g, (match, name) => Object.prototype.hasOwnProperty.call(values, name) ? String(values[name]) : match);
+}

package/dist/loading/model.d.ts

@@ -0,0 +1,6 @@
+export type LoadingTipOrder = 'sequence' | 'random';
+export declare function finiteDuration(value: number | undefined, fallback: number): number;
+export declare function normalizeLoadingMax(max: number | undefined): number;
+export declare function normalizeLoadingProgress(value: number | null | undefined, max: number): number | null | undefined;
+export declare function normalizeTipIndex(index: number | undefined, length: number): number;
+export declare function nextTipIndex(current: number, length: number, order: LoadingTipOrder, random?: () => number): number;