@inkra/react 0.8.0 → 0.9.0

package/README.md

@@ -17,6 +17,52 @@ Inkra components require a React client boundary. Next.js and React Server Compo
 
 ## Usage
 
+### Guided And Asynchronous Experiences
+
+`Guide.Root`, `Guide.Trigger` and `Guide.Step` compose a targeted walkthrough.
+`showSkip` exposes skipping; `onSkip` is separate from `onFinish`, so leaving
+early never reports completion. Controlled `open` and `step`, target resolution,
+focus restoration and localized labels are available.
+
+`Loading` supports `inline`, `region` and `fullscreen` carriers with six layout
+presets: `brand-center`, `scene-bottom`, `intel`, `staged`, `edge` and `skeleton`.
+Supply real progress or `null` for indeterminate progress. The application owns
+`status` and the cancel/retry/continue actions. Fullscreen blocking and scroll
+locking can be configured independently; the edge preset is non-blocking by
+default. Backgrounds, logos, stages, six logical content slots and rotating
+ReactNode tips share the same component. Tips support manual navigation, pause,
+controlled indices and sequential or non-repeating random rotation.
+
+`InfiniteScroll` loads at `top`, `bottom`, `left` or `right` boundaries. Configure
+automatic boundary loading and touch pull-and-release separately per direction;
+buttons remain available for keyboard use. `onLoad` receives an abort signal,
+direction and source. Stable item identities support anchored prepends, while
+errors, retry, exhausted directions and in-flight requests remain explicit.
+
+`Masonry` arranges measured items in shortest-column or sequential order while
+retaining DOM order. It supports adaptive or fixed columns, independent gaps,
+RTL and dynamic item sizes. Supply unique stable keys, image alternatives and
+your own data fetching, optionally through `InfiniteScroll`:
+
+```tsx
+<InfiniteScroll
+  directions="bottom"
+  hasMore={hasMore}
+  onLoad={({ signal }) => fetchNextPage(signal)}
+  style={{ maxHeight: 640, overflow: 'auto' }}
+>
+  <Masonry
+    items={items}
+    getItemKey={item => item.id}
+    minColumnWidth={220}
+    renderItem={({ item }) => <article>{item.content}</article>}
+  />
+</InfiniteScroll>
+```
+
+These APIs are included in this source candidate. Local browser checks are not
+real-device certification or a claim that this candidate has been published.
+
 Import the component styles once near the application entry point:
 
 ```tsx
@@ -435,6 +481,22 @@ motion and SSR show deterministic final values. Intermediate frames are visual;
 the polite announcement updates only at the final value. Use `getValueLabel`
 when units or custom rendering need a complete accessible phrase.
 
+Use `animation="roll"` for vertical, place-aligned digit reels. Integers align
+from the right and fractions from the decimal point; carry, multiplication,
+shrinking values and sign changes expand or collapse the affected columns.
+Grouping, signs, currency and compact units remain formatted text, not digit
+reels. `rollDirection="auto"` rolls up for increasing values and down for
+decreasing values; `up` or `down` fixes the direction. `duration` and `easing`
+apply to both modes. The default `animation="count"` retains value interpolation.
+`renderValue` takes precedence over the built-in reels. Changing the formatting
+or animation mode settles immediately, as do disabled/reduced motion, invalid
+durations, and transitions with more than 128 formatted tokens. Exact strings
+and bigint values retain their original precision in either mode.
+
+```tsx
+<NumberTicker value={amount} animation="roll" rollDirection="auto" duration={650} />
+```
+
 Set `compact` to follow `locale` (Chinese units for `zh`, English units otherwise),
 or use `compact="en"` / `compact="zh"` to select a unit table explicitly.
 English uses this library's short-scale suffix convention: K, M, B, T, Qa, Qi,
@@ -546,6 +608,33 @@ The matching inherited tokens are `--inkra-icon-stroke-width`,
 and `--inkra-icon-break-count`. Finite explicit props override those tokens.
 See `docs/pencil-contract.md` in the workspace for the material contract.
 
+Icons support `variant="outline"` (default) and `variant="filled"`. Filled icons
+keep holes and internal marks transparent, join overlapping silhouettes and do
+not close open arrows or checks into polygons. Set `fillColor` independently of
+the contour's CSS `color`; it defaults to `currentColor` and accepts CSS variables.
+The silhouette stays continuous while stroke controls affect its exterior.
+
+```tsx
+<PencilIcon paths={folderPaths} variant="filled" fillColor="var(--folder-color)"
+  sourceSize={24} size={32} style={{ color: 'var(--inkra-ink)' }} />
+```
+
+Supply `filledPaths` when a shape needs a dedicated filled silhouette. Each path
+can use `mode: 'fill'` with an optional `color` for independently colored regions,
+or `mode: 'cutout'` for transparent details. Closed cutouts remove an area; open
+cutouts remove a stroke without implicitly closing it. Explicit fills accept
+`fillRule: 'nonzero' | 'evenodd'` (default `nonzero`). These authored regions do
+not add their own contour stroke. For lighter colored-pencil regions, use
+`mode: 'wash'` with the same optional `color` and `fillRule`: paper remains visible
+between pigment strokes, with a light pencil edge in the icon's CSS `color`.
+Dense `fill` regions are unchanged.
+Explicit `mode: 'stroke'` keeps a line symbol
+even when its path closes; omitted mode detects filled silhouettes automatically.
+An empty `filledPaths` intentionally hides the
+base shape in filled mode. `badge` accepts the same three props and inherits the
+base variant and fill color unless overridden. Intensity applies once to the
+completed image, including its fills, exterior strokes and badge.
+
 `PencilLine` is an aria-hidden canvas decoration using the same pressure, grain, breaks, and repeated-pass renderer as surfaces and icons. It defaults to horizontal and supports a native vertical stroke without rotating a horizontal bitmap:
 
 ```tsx

package/dist/PencilIcon.d.ts

@@ -1,10 +1,17 @@
 import type { CanvasHTMLAttributes } from 'react';
 export interface PencilIconPath {
     d: string;
-    mode?: 'stroke' | 'wash' | 'scuff';
+    /** Filled icons: stroke stays a line, wash exposes paper, fill is dense; omitted mode detects closed silhouettes. */
+    mode?: 'stroke' | 'wash' | 'scuff' | 'fill' | 'cutout';
+    /** Optional pigment for an explicit fill region, including CSS custom properties. */
+    color?: string;
+    fillRule?: CanvasFillRule;
 }
 export interface PencilIconBadge {
     paths: readonly PencilIconPath[];
+    filledPaths?: readonly PencilIconPath[];
+    variant?: 'outline' | 'filled';
+    fillColor?: string;
     sourceSize?: number;
     position?: 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end';
     /** Relative canvas size, clamped to 0.35-0.65. Defaults to 0.55. */
@@ -12,6 +19,12 @@ export interface PencilIconBadge {
 }
 export interface PencilIconProps extends Omit<CanvasHTMLAttributes<HTMLCanvasElement>, 'children' | 'height' | 'width'> {
     paths: readonly PencilIconPath[];
+    /** Filled icons retain open symbols and use negative space for interior details. */
+    variant?: 'outline' | 'filled';
+    /** Optional authored geometry for shapes whose filled silhouette differs from the outline. */
+    filledPaths?: readonly PencilIconPath[];
+    /** Body pigment, independent of the CSS color used for the contour. Defaults to currentColor. */
+    fillColor?: string;
     badge?: PencilIconBadge;
     seed?: string | number;
     size?: number;

package/dist/PencilIcon.js

@@ -6,6 +6,7 @@ import { seedToNumber } from './internal/random.js';
 import { pencilStroke } from './internal/stroke.js';
 import { maxStrokeRoughness, pencilRenderDefaults, readRenderToken } from './internal/renderTokens.js';
 import { cachedPathParts } from './internal/iconGeometry.js';
+import { paintFilledIcon } from './internal/iconFill.js';
 const imageCache = new BoundedCache(128, 24 * 1024 * 1024);
 function drawFallbackPath(context, data, color, mode, weightScale = 1) {
     try {
@@ -47,56 +48,62 @@ function renderIcon(paths, options) {
     const offset = (40 - sourceSize) / 2;
     context.translate(offset, offset);
     let sampledPoints = 0;
-    paths.forEach((path, index) => {
-        if (path.d.length > 65536)
-            return;
-        const mode = path.mode ?? 'stroke';
-        const pathSeed = seed + index * 137;
-        if (mode === 'wash') {
+    if (options.variant === 'filled') {
+        paintFilledIcon(context, paths, { color, fillColor: options.fillColor ?? color, sourceSize, seed, weightScale, roughnessScale, breaks, breakCount, pressureVariation, coordinateScale });
+    }
+    else
+        paths.forEach((path, index) => {
+            if (path.d.length > 65536)
+                return;
+            const mode = path.mode ?? 'stroke';
+            if (mode === 'cutout')
+                return;
+            const pathSeed = seed + index * 137;
+            if (mode === 'wash' || mode === 'fill') {
+                try {
+                    context.save();
+                    context.clip(new Path2D(path.d));
+                    context.globalAlpha = active ? 0.76 : 0.34;
+                    for (let y = sourceSize * 0.18; y < sourceSize; y += 1.6) {
+                        pencilStroke(context, [[sourceSize * 0.15, y + 3], [sourceSize * 0.85, y - 3]], color, 1.1 * weightScale / (pencilRenderDefaults.strokeWidth / 1.2), pathSeed + Math.round(y * 17), 0.25, 2, false, { variation: Math.min(1, 0.85 * variationScale), fitPressure: true, breaks, breakCount, breakScale: coordinateScale, continuousBreaks: true, grain: 0.7, gain: 2.2, step: 0.35 });
+                    }
+                    context.restore();
+                }
+                catch {
+                    drawFallbackPath(context, path.d, color, mode, weightScale);
+                }
+                return;
+            }
             try {
-                context.save();
-                context.clip(new Path2D(path.d));
-                context.globalAlpha = active ? 0.76 : 0.34;
-                for (let y = sourceSize * 0.18; y < sourceSize; y += 1.6) {
-                    pencilStroke(context, [[sourceSize * 0.15, y + 3], [sourceSize * 0.85, y - 3]], color, 1.1 * weightScale / (pencilRenderDefaults.strokeWidth / 1.2), pathSeed + Math.round(y * 17), 0.25, 2, false, { variation: Math.min(1, 0.85 * variationScale), fitPressure: true, breaks, breakCount, breakScale: coordinateScale, continuousBreaks: true, grain: 0.7, gain: 2.2, step: 0.35 });
+                if (sampledPoints >= 65536) {
+                    drawFallbackPath(context, path.d, color, mode, weightScale);
+                    return;
+                }
+                const parts = cachedPathParts(path.d);
+                sampledPoints += parts.reduce((total, part) => total + part.length, 0);
+                if (sampledPoints > 65536) {
+                    drawFallbackPath(context, path.d, color, mode, weightScale);
+                    return;
+                }
+                for (const points of parts) {
+                    pencilStroke(context, points, color, (mode === 'scuff' ? 0.55 : 1.65) * weightScale, pathSeed, 0.3 * roughnessScale, mode === 'scuff' ? 1 : 3, false, {
+                        variation: pressureVariation,
+                        fitPressure: true,
+                        breaks,
+                        breakCount,
+                        breakScale: coordinateScale,
+                        continuousBreaks: true,
+                        grain: 0.68,
+                        gain: mode === 'scuff' ? 1.5 : 3,
+                        step: 0.35,
+                        taperLength: 0.65,
+                    });
                 }
-                context.restore();
             }
             catch {
                 drawFallbackPath(context, path.d, color, mode, weightScale);
             }
-            return;
-        }
-        try {
-            if (sampledPoints >= 65536) {
-                drawFallbackPath(context, path.d, color, mode, weightScale);
-                return;
-            }
-            const parts = cachedPathParts(path.d);
-            sampledPoints += parts.reduce((total, part) => total + part.length, 0);
-            if (sampledPoints > 65536) {
-                drawFallbackPath(context, path.d, color, mode, weightScale);
-                return;
-            }
-            for (const points of parts) {
-                pencilStroke(context, points, color, (mode === 'scuff' ? 0.55 : 1.65) * weightScale, pathSeed, 0.3 * roughnessScale, mode === 'scuff' ? 1 : 3, false, {
-                    variation: pressureVariation,
-                    fitPressure: true,
-                    breaks,
-                    breakCount,
-                    breakScale: coordinateScale,
-                    continuousBreaks: true,
-                    grain: 0.68,
-                    gain: mode === 'scuff' ? 1.5 : 3,
-                    step: 0.35,
-                    taperLength: 0.65,
-                });
-            }
-        }
-        catch {
-            drawFallbackPath(context, path.d, color, mode, weightScale);
-        }
-    });
+        });
     if (active) {
         pencilStroke(context, [[sourceSize * 0.2, sourceSize - 2], [sourceSize * 0.5, sourceSize - 1.5], [sourceSize * 0.8, sourceSize - 2.2]], color, 1.1 * weightScale, seed + 977, 0.25 * roughnessScale, 3, false, { variation: 0.8 * variationScale, fitPressure: true, breaks, breakCount, breakScale: coordinateScale, continuousBreaks: true, grain: 0.7, gain: 2.8, step: 0.35 });
     }
@@ -109,8 +116,10 @@ function renderIcon(paths, options) {
         const extent = 40 * scale;
         const x = onLeft ? 0 : 40 - extent;
         const y = position.startsWith('top') ? 0 : 40 - extent;
-        const badgeImage = renderIcon(badge.paths, {
+        const badgeVariant = badge.variant ?? options.variant;
+        const badgeImage = renderIcon(badgeVariant === 'filled' ? badge.filledPaths ?? badge.paths : badge.paths, {
             seed: seed + 1543, size: size * scale, sourceSize: badgeSourceSize, active: false, color, dpr,
+            variant: badgeVariant, fillColor: badge.fillColor ?? options.fillColor,
             weightScale: weightScale / scale, roughnessScale, breaks, breakCount, pressureVariation,
         });
         const mask = document.createElement('canvas');
@@ -140,17 +149,18 @@ function renderIcon(paths, options) {
     }
     return canvas;
 }
-export const PencilIcon = forwardRef(function PencilIcon({ active = false, badge, className = '', decorative = true, paths, seed, size = 40, sourceSize = 32, strokeWidth, intensity, breaks, breakCount, pressureVariation, ...props }, forwardedRef) {
+export const PencilIcon = forwardRef(function PencilIcon({ active = false, badge, className = '', decorative = true, paths, variant = 'outline', filledPaths, fillColor, seed, size = 40, sourceSize = 32, strokeWidth, intensity, breaks, breakCount, pressureVariation, ...props }, forwardedRef) {
     const canvasRef = useRef(null);
     const lastPaintRef = useRef('');
     useImperativeHandle(forwardedRef, () => canvasRef.current);
     // Compare values, not caller object identity. Serializing each render also
     // detects in-place edits; the effect receives a stable snapshot of that value.
-    const geometryKey = JSON.stringify(paths);
+    const originalGeometryKey = JSON.stringify(paths);
+    const geometryKey = variant === 'filled' && filledPaths ? JSON.stringify(filledPaths) : originalGeometryKey;
     const badgeKey = badge ? JSON.stringify(badge) : '';
     const stablePaths = useMemo(() => JSON.parse(geometryKey), [geometryKey]);
     const stableBadge = useMemo(() => badgeKey ? JSON.parse(badgeKey) : undefined, [badgeKey]);
-    const resolvedSeed = seedToNumber(seed ?? geometryKey);
+    const resolvedSeed = seedToNumber(seed ?? originalGeometryKey);
     useEffect(() => {
         const canvas = canvasRef.current;
         if (!canvas)
@@ -162,6 +172,28 @@ export const PencilIcon = forwardRef(function PencilIcon({ active = false, badge
             const dpr = effectiveDpr(3);
             const computed = getComputedStyle(canvas);
             const color = computed.color;
+            const resolveColor = (value) => {
+                if (!value || value === 'currentColor')
+                    return color;
+                const probe = document.createElement('span');
+                probe.style.color = value;
+                // Canvas fallback children inherit its own color and custom properties, not just its parent's.
+                canvas.appendChild(probe);
+                try {
+                    return getComputedStyle(probe).color || color;
+                }
+                finally {
+                    probe.remove();
+                }
+            };
+            const resolvedFill = variant === 'filled' ? resolveColor(fillColor) : color;
+            const resolvePaths = (items) => items.map(path => path.color ? { ...path, color: resolveColor(path.color) } : path);
+            const renderedPaths = variant === 'filled' ? resolvePaths(stablePaths) : stablePaths;
+            const renderedBadge = stableBadge ? { ...stableBadge,
+                fillColor: resolveColor(stableBadge.fillColor ?? fillColor),
+                paths: resolvePaths(stableBadge.paths),
+                filledPaths: stableBadge.filledPaths ? resolvePaths(stableBadge.filledPaths) : undefined,
+            } : undefined;
             const rtl = computed.direction === 'rtl';
             const iconWeight = readRenderToken(computed, '--inkra-icon-stroke-width', pencilRenderDefaults.iconStrokeWidth, 0.3, 3);
             const weightScale = (typeof strokeWidth === 'number' && Number.isFinite(strokeWidth) ? Math.min(3, Math.max(0.3, strokeWidth)) : iconWeight) / 1.2;
@@ -180,9 +212,10 @@ export const PencilIcon = forwardRef(function PencilIcon({ active = false, badge
                 : readRenderToken(computed, '--inkra-icon-break-count', pencilRenderDefaults.iconBreakCount, 0, 12));
             const key = JSON.stringify([
                 PENCIL_RENDERER_VERSION,
-                'icon-path-pressure-gaps-v4',
+                'icon-path-paper-wash-v8',
                 geometryKey,
                 badgeKey,
+                variant, resolvedFill, renderedPaths, renderedBadge,
                 rtl,
                 resolvedSeed,
                 size,
@@ -202,7 +235,7 @@ export const PencilIcon = forwardRef(function PencilIcon({ active = false, badge
                 image = undefined;
             }
             if (!image) {
-                image = renderIcon(stablePaths, { seed: resolvedSeed, size, sourceSize, active, color, dpr, badge: stableBadge, rtl, weightScale, roughnessScale, breaks: strokeBreaks, breakCount: strokeBreakCount, pressureVariation: strokeVariation });
+                image = renderIcon(renderedPaths, { seed: resolvedSeed, size, sourceSize, active, color, dpr, variant, fillColor: resolvedFill, badge: renderedBadge, rtl, weightScale, roughnessScale, breaks: strokeBreaks, breakCount: strokeBreakCount, pressureVariation: strokeVariation });
                 imageCache.set(key, image, canvasByteCost(image));
             }
             canvas.width = image.width;
@@ -236,7 +269,9 @@ export const PencilIcon = forwardRef(function PencilIcon({ active = false, badge
             inheritedColor.observe(element, { attributes: true, attributeFilter: ['style', 'class', 'dir', 'data-theme', 'data-inkra-theme'] });
         }
         const colorScheme = window.matchMedia('(prefers-color-scheme: dark)');
+        const forcedColors = window.matchMedia('(forced-colors: active)');
         colorScheme.addEventListener('change', paint);
+        forcedColors.addEventListener('change', paint);
         const stopRecovery = observeCanvasRecovery(() => { lastPaintRef.current = ''; paint(); });
         paint();
         return () => {
@@ -245,10 +280,11 @@ export const PencilIcon = forwardRef(function PencilIcon({ active = false, badge
             stopRecovery();
             inheritedColor.disconnect();
             colorScheme.removeEventListener('change', paint);
+            forcedColors.removeEventListener('change', paint);
         };
-    }, [active, stableBadge, badgeKey, geometryKey, stablePaths, resolvedSeed, size, sourceSize, strokeWidth, intensity, breaks, breakCount, pressureVariation]);
+    }, [active, stableBadge, badgeKey, geometryKey, stablePaths, resolvedSeed, size, sourceSize, strokeWidth, intensity, breaks, breakCount, pressureVariation, variant, fillColor]);
     const accessibilityProps = decorative
         ? { 'aria-hidden': true }
         : { role: props.role ?? 'img' };
-    return (_jsx("canvas", { ...props, ...accessibilityProps, className: ['inkra-pencil-icon', className].filter(Boolean).join(' '), "data-active": active || undefined, "data-composite": Boolean(badge?.paths.length) || undefined, "data-renderer": "inkra-pressure-pencil", ref: canvasRef, style: { width: size, height: size, ...props.style } }));
+    return (_jsx("canvas", { ...props, ...accessibilityProps, className: ['inkra-pencil-icon', className].filter(Boolean).join(' '), "data-active": active || undefined, "data-icon-variant": variant, "data-composite": Boolean(badge?.paths.length) || undefined, "data-renderer": "inkra-pressure-pencil", ref: canvasRef, style: { width: size, height: size, ...props.style } }));
 });

package/dist/guide/index.d.ts

@@ -0,0 +1,77 @@
+import * as PopoverPrimitive from '@radix-ui/react-popover';
+import type { ReactNode, RefObject } from 'react';
+type GuideSide = 'top' | 'right' | 'bottom' | 'left';
+type GuideAlign = 'start' | 'center' | 'end';
+export type GuideSkipPlacement = 'panel' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end';
+export type GuideSkipAppearance = 'icon' | 'text';
+export type GuideTarget = string | HTMLElement | RefObject<HTMLElement | null> | (() => HTMLElement | null);
+export interface GuideStepProps {
+    /** Stable identifier reported by callbacks. */
+    id?: string;
+    /** A selector, element, ref, or resolver. Missing targets fall back to the viewport. */
+    target: GuideTarget;
+    title: string;
+    description?: ReactNode;
+    children?: ReactNode;
+    side?: GuideSide;
+    align?: GuideAlign;
+    sideOffset?: number;
+    collisionPadding?: number;
+}
+export declare function GuideStep(_props: GuideStepProps): null;
+export declare namespace GuideStep {
+    var displayName: string;
+}
+export type GuideOpenChangeReason = 'trigger' | 'close' | 'escape' | 'finish' | 'skip';
+export interface GuideOpenChangeDetails {
+    reason: GuideOpenChangeReason;
+    step: number;
+    stepId?: string;
+}
+export interface GuideStepChangeDetails {
+    reason: 'next' | 'previous';
+    previousStep: number;
+    stepId?: string;
+}
+export interface GuideLabels {
+    previous: string;
+    next: string;
+    finish: string;
+    skip: string;
+    close: string;
+    /** Supports {current} and {total}. */
+    progress: string;
+}
+export interface GuideRootProps {
+    children?: ReactNode;
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean, details: GuideOpenChangeDetails) => void;
+    step?: number;
+    defaultStep?: number;
+    onStepChange?: (step: number, details: GuideStepChangeDetails) => void;
+    onFinish?: () => void;
+    onSkip?: () => void;
+    showSkip?: boolean;
+    skipPlacement?: GuideSkipPlacement;
+    skipAppearance?: GuideSkipAppearance;
+    showClose?: boolean;
+    closeOnEscape?: boolean;
+    scrollIntoView?: boolean | ScrollIntoViewOptions;
+    restoreFocus?: boolean;
+    highlightPadding?: number;
+    highlightRadius?: number;
+    locale?: string;
+    labels?: Partial<GuideLabels>;
+    portalContainer?: HTMLElement | null;
+    className?: string;
+}
+export type GuideTriggerProps = PopoverPrimitive.PopoverTriggerProps;
+export declare const GuideTrigger: import("react").ForwardRefExoticComponent<PopoverPrimitive.PopoverTriggerProps & import("react").RefAttributes<HTMLButtonElement>>;
+export declare function GuideRoot({ children, open, defaultOpen, onOpenChange, step, defaultStep, onStepChange, onFinish, onSkip, showSkip, skipPlacement, skipAppearance, showClose, closeOnEscape, scrollIntoView, restoreFocus, highlightPadding, highlightRadius, locale, labels, portalContainer, className, }: GuideRootProps): import("react").JSX.Element;
+export declare const Guide: Readonly<{
+    Root: typeof GuideRoot;
+    Trigger: import("react").ForwardRefExoticComponent<PopoverPrimitive.PopoverTriggerProps & import("react").RefAttributes<HTMLButtonElement>>;
+    Step: typeof GuideStep;
+}>;
+export {};