@inkra/react 0.8.0 → 0.10.0

package/dist/slider/circular.js

@@ -0,0 +1,196 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useEffect, useId, useImperativeHandle, useRef, useState } from 'react';
+import { PencilSurface } from '../PencilSurface.js';
+import { PencilText } from '../PencilText.js';
+import { ProgressRing } from '../display/ProgressRing.js';
+import { advanceArcPosition, initialArcPosition, normalizeAngle, snapCircularValue, stepCircularValue } from './circularMath.js';
+const diameters = { sm: 128, md: 160, lg: 192 };
+const thicknesses = { sm: 5, md: 6, lg: 8 };
+const thumbSizes = { sm: 20, md: 24, lg: 28 };
+export const CircularSlider = forwardRef(function CircularSlider({ value, defaultValue, onValueChange, onValueCommit, min: suppliedMin = 0, max: suppliedMax = 100, step: suppliedStep = 1, disabled = false, readOnly = false, name, form, size = 'md', diameter, startAngle = 225, sweepAngle = 270, clockwise = true, showValue = true, centerIcon, centerContent, getValueLabel, seed, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-valuetext': ariaValueText, className, style, tabIndex, onPointerDown, onPointerMove, onPointerUp, onPointerCancel, onLostPointerCapture, onKeyDown, ...props }, forwardedRef) {
+    const id = useId();
+    const rootRef = useRef(null);
+    const inputRef = useRef(null);
+    const gesture = useRef(null);
+    useImperativeHandle(forwardedRef, () => rootRef.current);
+    const min = Number.isFinite(suppliedMin) ? suppliedMin : 0;
+    const max = Number.isFinite(suppliedMax) && Number.isFinite(suppliedMax - min) ? Math.max(min, suppliedMax) : min;
+    const step = Number.isFinite(suppliedStep) && suppliedStep > 0 ? suppliedStep : 1;
+    const initialValue = useRef(defaultValue ?? min);
+    const [uncontrolledValue, setUncontrolledValue] = useState(initialValue.current);
+    const controlled = value !== undefined;
+    const current = snapCircularValue(value ?? uncontrolledValue, min, max, step);
+    const latest = useRef({ current, controlled, min, max, step });
+    latest.current = { current, controlled, min, max, step };
+    const blocked = disabled || readOnly || min === max;
+    const resolvedDiameter = Math.min(512, Math.max(96, Number.isFinite(diameter) ? diameter : diameters[size]));
+    const start = normalizeAngle(Number.isFinite(startAngle) ? startAngle : 225);
+    const sweep = Math.min(360, Math.max(1, Number.isFinite(sweepAngle) ? sweepAngle : 270));
+    const ringDiameter = resolvedDiameter - 32;
+    // Explicitly tiny diameters scale visual weight rather than consuming the center slot.
+    const thickness = Math.min(thicknesses[size], 5 + (resolvedDiameter - 96) / 4);
+    const thumbSize = Math.min(thumbSizes[size], 16 + (resolvedDiameter - 96) / 2);
+    const radius = ringDiameter / 2 - thickness - 4;
+    const progress = max > min ? (current - min) / (max - min) : 0;
+    const angle = (start + progress * sweep * (clockwise ? 1 : -1)) * Math.PI / 180;
+    const label = getValueLabel?.(current) ?? String(current);
+    const content = centerContent === undefined ? (showValue ? label : null) : typeof centerContent === 'function' ? centerContent(current) : centerContent;
+    const hasCenterIcon = centerIcon != null && typeof centerIcon !== 'boolean';
+    const hasCenterContent = content != null && typeof content !== 'boolean';
+    // Compact icon/value stacks need more vertical room than an inscribed square.
+    const centerWidth = Math.max(16, (radius - thickness - 4) * 2) + 10;
+    const centerHeight = Math.max(20, (radius - thickness - 2) * 2);
+    const combinedCenter = hasCenterIcon && hasCenterContent;
+    const requestedIconSize = Math.min(24, Math.max(12, 16 + (resolvedDiameter - 104) / 4));
+    // Account for gap + padding, reserving a complete value line at every supported size.
+    const centerIconSize = combinedCenter ? Math.min(requestedIconSize, centerHeight - 20) : 24;
+    const centerLineHeight = Math.min(resolvedDiameter <= 112 ? 18 : 24, centerHeight - centerIconSize - 6);
+    const centerFontSize = centerLineHeight < 18 ? '12px' : centerLineHeight < 22 ? '14px' : 'var(--inkra-text-lg)';
+    const resolvedSeed = seed ?? `inkra-circular-slider-${id}`;
+    function releaseCapture(pointerId) {
+        const root = rootRef.current;
+        if (root?.hasPointerCapture?.(pointerId))
+            root.releasePointerCapture(pointerId);
+    }
+    useEffect(() => {
+        if (!blocked || !gesture.current)
+            return;
+        const pointerId = gesture.current.id;
+        gesture.current = null;
+        releaseCapture(pointerId);
+    }, [blocked]);
+    useEffect(() => () => {
+        const active = gesture.current;
+        gesture.current = null;
+        if (active)
+            releaseCapture(active.id);
+    }, []);
+    useEffect(() => {
+        const document = inputRef.current?.ownerDocument;
+        if (!document)
+            return;
+        let timer;
+        const reset = (event) => {
+            // Resolve ownership at dispatch time, including forms moved or replaced after mount.
+            if (event.target !== inputRef.current?.form)
+                return;
+            clearTimeout(timer);
+            timer = setTimeout(() => {
+                if (event.defaultPrevented)
+                    return;
+                const active = gesture.current;
+                gesture.current = null;
+                if (active)
+                    releaseCapture(active.id);
+                const state = latest.current;
+                const next = state.controlled ? state.current : snapCircularValue(initialValue.current, state.min, state.max, state.step);
+                if (!state.controlled)
+                    setUncontrolledValue(next);
+                if (inputRef.current)
+                    inputRef.current.value = String(next);
+            }, 0);
+        };
+        document.addEventListener('reset', reset, true);
+        return () => { clearTimeout(timer); document.removeEventListener('reset', reset, true); };
+    }, []);
+    function propose(next) {
+        if (!controlled)
+            setUncontrolledValue(next);
+        onValueChange?.(next);
+    }
+    function pointerPosition(clientX, clientY) {
+        const rect = rootRef.current?.getBoundingClientRect();
+        if (!rect || rect.width === 0 || rect.height === 0)
+            return null;
+        const x = (clientX - rect.left) / rect.width - 0.5;
+        const y = (clientY - rect.top) / rect.height - 0.5;
+        return { angle: normalizeAngle(Math.atan2(x, -y) * 180 / Math.PI), distance: Math.hypot(x, y) * resolvedDiameter };
+    }
+    function movePointer(clientX, clientY) {
+        const active = gesture.current;
+        const point = pointerPosition(clientX, clientY);
+        if (!active || !point || point.distance < Math.max(8, radius * 0.25))
+            return;
+        active.position = advanceArcPosition(active.position, active.angle, point.angle, sweep, clockwise);
+        active.angle = point.angle;
+        const next = snapCircularValue(min + active.position / sweep * (max - min), min, max, step);
+        if (next === active.value)
+            return;
+        active.value = next;
+        active.changed = true;
+        propose(next);
+    }
+    return _jsxs("div", { ...props, ref: rootRef, role: "slider", className: ['inkra-circular-slider', className].filter(Boolean).join(' '), "data-size": size, "data-disabled": disabled ? '' : undefined, "data-readonly": readOnly ? '' : undefined, "aria-label": ariaLabel ?? (ariaLabelledBy ? undefined : 'Value'), "aria-labelledby": ariaLabelledBy, "aria-valuemin": min, "aria-valuemax": max, "aria-valuenow": current, "aria-valuetext": getValueLabel ? label : ariaValueText, "aria-disabled": disabled || undefined, "aria-readonly": readOnly || undefined, tabIndex: disabled ? -1 : tabIndex ?? 0, style: { '--inkra-circular-slider-diameter': `${resolvedDiameter}px`, '--inkra-circular-slider-thumb-size': `${thumbSize}px`, '--inkra-circular-slider-center-width': `${centerWidth}px`, '--inkra-circular-slider-center-height': `${centerHeight + 6}px`, '--inkra-circular-slider-center-icon-size': `${centerIconSize}px`, '--inkra-circular-slider-center-font-size': combinedCenter ? centerFontSize : 'var(--inkra-text-lg)', '--inkra-circular-slider-center-line-height': combinedCenter ? `${centerLineHeight}px` : 'var(--inkra-line-ui)', ...style }, onPointerDown: event => {
+            onPointerDown?.(event);
+            if (event.defaultPrevented || blocked || gesture.current || event.button !== 0 || event.isPrimary === false)
+                return;
+            const point = pointerPosition(event.clientX, event.clientY);
+            if (!point || point.distance < Math.max(8, radius - 22) || point.distance > radius + 22)
+                return;
+            event.preventDefault();
+            event.currentTarget.focus({ preventScroll: true });
+            const thumbAngle = start + progress * sweep * (clockwise ? 1 : -1);
+            const delta = (point.angle - thumbAngle) * Math.PI / 180;
+            const thumbDistance = Math.sqrt(Math.max(0, point.distance ** 2 + radius ** 2 - 2 * point.distance * radius * Math.cos(delta)));
+            // The whole 44px thumb target grabs without changing the current value.
+            const position = thumbDistance <= 22 ? progress * sweep : initialArcPosition(point.angle, start, sweep, clockwise, progress * sweep);
+            const next = snapCircularValue(min + position / sweep * (max - min), min, max, step);
+            gesture.current = { id: event.pointerId, angle: point.angle, position, value: next, changed: next !== current };
+            try {
+                event.currentTarget.setPointerCapture(event.pointerId);
+            }
+            catch { /* Pointer capture is unavailable in some synthetic event environments. */ }
+            if (next !== current)
+                propose(next);
+        }, onPointerMove: event => {
+            onPointerMove?.(event);
+            if (event.defaultPrevented || blocked || event.pointerId !== gesture.current?.id)
+                return;
+            event.preventDefault();
+            movePointer(event.clientX, event.clientY);
+        }, onPointerUp: event => {
+            onPointerUp?.(event);
+            const active = gesture.current;
+            if (!active || active.id !== event.pointerId)
+                return;
+            if (!event.defaultPrevented && !blocked)
+                movePointer(event.clientX, event.clientY);
+            gesture.current = null;
+            releaseCapture(event.pointerId);
+            if (!event.defaultPrevented && !blocked && active.changed)
+                onValueCommit?.(active.value);
+        }, onPointerCancel: event => {
+            onPointerCancel?.(event);
+            if (event.pointerId !== gesture.current?.id)
+                return;
+            gesture.current = null;
+            releaseCapture(event.pointerId);
+        }, onLostPointerCapture: event => {
+            onLostPointerCapture?.(event);
+            if (event.pointerId === gesture.current?.id)
+                gesture.current = null;
+        }, onKeyDown: event => {
+            onKeyDown?.(event);
+            if (event.defaultPrevented || blocked || event.altKey || event.ctrlKey || event.metaKey)
+                return;
+            let next;
+            if (event.key === 'Home')
+                next = min;
+            else if (event.key === 'End')
+                next = max;
+            else if (['ArrowRight', 'ArrowUp', 'ArrowLeft', 'ArrowDown', 'PageUp', 'PageDown'].includes(event.key)) {
+                const sign = ['ArrowRight', 'ArrowUp', 'PageUp'].includes(event.key) ? 1 : -1;
+                const count = event.key.startsWith('Page') || event.shiftKey ? 10 : 1;
+                next = stepCircularValue(current, sign * count, min, max, step);
+            }
+            else
+                return;
+            event.preventDefault();
+            if (next !== current) {
+                propose(next);
+                onValueCommit?.(next);
+            }
+        }, children: [_jsxs("span", { className: "inkra-circular-slider__arc", "aria-hidden": "true", style: { transform: `rotate(${start}deg) scaleX(${clockwise ? 1 : -1})` }, children: [_jsx("span", { className: "inkra-circular-slider__track", children: _jsx(ProgressRing, { diameter: ringDiameter, thickness: thickness, percent: sweep / 3.6, seed: `${resolvedSeed}-track` }) }), _jsx("span", { className: "inkra-circular-slider__range", children: _jsx(ProgressRing, { diameter: ringDiameter, thickness: thickness, percent: progress * sweep / 3.6, seed: `${resolvedSeed}-range` }) })] }), (hasCenterIcon || hasCenterContent) && _jsxs("div", { className: "inkra-circular-slider__center", "aria-hidden": "true", inert: true, children: [hasCenterIcon && _jsx("div", { className: "inkra-circular-slider__center-icon", children: centerIcon }), hasCenterContent && _jsx("div", { className: "inkra-circular-slider__center-content", children: typeof content === 'string' || typeof content === 'number'
+                            ? _jsx(PencilText, { className: "inkra-circular-slider__value", ellipsis: centerContent !== undefined, children: String(content) })
+                            : content })] }), _jsx("span", { "aria-hidden": "true", className: "inkra-circular-slider__thumb", style: { left: `${50 + Math.sin(angle) * radius / resolvedDiameter * 100}%`, top: `${50 - Math.cos(angle) * radius / resolvedDiameter * 100}%` }, children: _jsx(PencilSurface, { as: "span", className: "inkra-circular-slider__thumb-surface", variant: "paper", radius: thumbSize / 2, seed: `${resolvedSeed}-thumb`, children: _jsx(PencilSurface, { as: "span", className: "inkra-circular-slider__focus-ring", variant: "outline", radius: thumbSize / 2 + 4, seed: `${resolvedSeed}-focus` }) }) }), _jsx("input", { ref: inputRef, type: "hidden", name: name, form: form, value: current, disabled: disabled })] });
+});

package/dist/slider/circularMath.d.ts

@@ -0,0 +1,10 @@
+/** Clock angles: 0 points up and positive angles turn clockwise. */
+export declare const normalizeAngle: (angle: number) => number;
+export declare const clampCircularValue: (value: number, min: number, max: number) => number;
+/** Snap to the grid anchored at min, retaining max as an attainable final stop. */
+export declare function snapCircularValue(value: number, min: number, max: number, step: number): number;
+export declare function stepCircularValue(value: number, steps: number, min: number, max: number, step: number): number;
+/** Map an initial track press to an arc, selecting the closest endpoint in its gap. */
+export declare function initialArcPosition(angle: number, start: number, sweep: number, clockwise: boolean, current: number): number;
+/** Unwrap small consecutive movements; crossing the seam never resets to zero. */
+export declare function advanceArcPosition(position: number, previousAngle: number, angle: number, sweep: number, clockwise: boolean): number;

package/dist/slider/circularMath.js

@@ -0,0 +1,34 @@
+/** Clock angles: 0 points up and positive angles turn clockwise. */
+export const normalizeAngle = (angle) => ((angle % 360) + 360) % 360;
+export const clampCircularValue = (value, min, max) => Math.min(max, Math.max(min, value));
+function cleanNumber(value) {
+    return Number(value.toPrecision(14));
+}
+/** Snap to the grid anchored at min, retaining max as an attainable final stop. */
+export function snapCircularValue(value, min, max, step) {
+    if (!Number.isFinite(value))
+        return min;
+    const bounded = clampCircularValue(value, min, max);
+    const snapped = clampCircularValue(cleanNumber(min + Math.round((bounded - min) / step) * step), min, max);
+    return max - bounded < Math.abs(snapped - bounded) ? max : snapped;
+}
+export function stepCircularValue(value, steps, min, max, step) {
+    const position = (value - min) / step;
+    const index = steps > 0 ? Math.floor(position + 1e-9) : Math.ceil(position - 1e-9);
+    return clampCircularValue(cleanNumber(min + (index + steps) * step), min, max);
+}
+/** Map an initial track press to an arc, selecting the closest endpoint in its gap. */
+export function initialArcPosition(angle, start, sweep, clockwise, current) {
+    const position = normalizeAngle((angle - start) * (clockwise ? 1 : -1));
+    if (sweep < 360)
+        return position <= sweep ? position : position - sweep < 360 - position ? sweep : 0;
+    // Only the exact seam represents two values; other track presses are absolute.
+    if (position < 1e-7 || 360 - position < 1e-7)
+        return current > 180 ? 360 : 0;
+    return position;
+}
+/** Unwrap small consecutive movements; crossing the seam never resets to zero. */
+export function advanceArcPosition(position, previousAngle, angle, sweep, clockwise) {
+    const delta = normalizeAngle(angle - previousAngle + 180) - 180;
+    return clampCircularValue(position + delta * (clockwise ? 1 : -1), 0, sweep);
+}

package/dist/slider/index.d.ts

@@ -1,11 +1,16 @@
 import * as SliderPrimitive from '@radix-ui/react-slider';
 export type SliderSize = 'sm' | 'md' | 'lg';
 export type SliderVariant = 'standard' | 'inset';
+export type SliderThumbAlignment = 'edge' | 'contain';
 export interface SliderProps extends Omit<SliderPrimitive.SliderProps, 'children' | 'asChild'> {
     size?: SliderSize;
     variant?: SliderVariant;
+    /** Align thumb centers with track endpoints, or retain the inset hit-target bounds. */
+    thumbAlignment?: SliderThumbAlignment;
     seed?: string | number;
     thumbLabels?: readonly string[];
     getValueLabel?: (value: number, index: number) => string;
 }
 export declare const Slider: import("react").ForwardRefExoticComponent<SliderProps & import("react").RefAttributes<HTMLSpanElement>>;
+export { CircularSlider } from './circular.js';
+export type { CircularSliderProps } from './circular.js';

package/dist/slider/index.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as SliderPrimitive from '@radix-ui/react-slider';
 import { forwardRef, useEffect, useId, useImperativeHandle, useRef, useState } from 'react';
 import { PencilSurface } from '../PencilSurface.js';
-export const Slider = forwardRef(function Slider({ 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, 'aria-valuetext': ariaValueText, className, defaultValue, dir, disabled = false, getValueLabel, inverted = false, min = 0, max = 100, name, form, onValueChange, onValueCommit, orientation = 'horizontal', seed, size = 'md', thumbLabels, value, variant = 'standard', ...props }, forwardedRef) {
+export const Slider = forwardRef(function Slider({ 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, 'aria-valuetext': ariaValueText, className, defaultValue, dir, disabled = false, getValueLabel, inverted = false, min = 0, max = 100, name, form, onValueChange, onValueCommit, orientation = 'horizontal', seed, size = 'md', thumbAlignment = 'edge', thumbLabels, value, variant = 'standard', ...props }, forwardedRef) {
     const generatedId = useId();
     const rootRef = useRef(null);
     useImperativeHandle(forwardedRef, () => rootRef.current);
@@ -70,16 +70,17 @@ export const Slider = forwardRef(function Slider({ 'aria-label': ariaLabel, 'ari
     const clip = {
         clipPath: orientation === 'horizontal' ? `inset(0 ${end}% 0 ${start}%)` : `inset(${start}% 0 ${end}% 0)`,
     };
-    return _jsxs(SliderPrimitive.Root, { ...props, className: ['inkra-slider', className].filter(Boolean).join(' '), "data-size": size, "data-variant": variant, dir: resolvedDir, disabled: disabled, form: radixFormId, inverted: inverted, min: min, max: max, onValueChange: next => {
+    return _jsxs(SliderPrimitive.Root, { ...props, className: ['inkra-slider', className].filter(Boolean).join(' '), "data-size": size, "data-variant": variant, "data-thumb-alignment": thumbAlignment, dir: resolvedDir, disabled: disabled, form: radixFormId, inverted: inverted, min: min, max: max, onValueChange: next => {
             if (!controlled)
                 setUncontrolledValue(next);
             onValueChange?.(next);
         }, onValueCommit: onValueCommit, orientation: orientation, ref: rootRef, value: values, children: [_jsxs(SliderPrimitive.Track, { className: "inkra-slider__track", children: [_jsx(PencilSurface, { as: "span", "aria-hidden": "true", className: "inkra-slider__track-surface", variant: "outline", radius: variant === 'inset' ? 8 : 3, seed: `${resolvedSeed}-track` }), _jsx("span", { "aria-hidden": "true", className: "inkra-slider__range", style: clip, children: _jsx(PencilSurface, { as: "span", className: "inkra-slider__range-surface", variant: "selection", seed: `${resolvedSeed}-range` }) })] }), values.map((current, index) => {
+                const position = reversed ? 100 - percentage(current) : percentage(current);
                 const thumbLabel = thumbLabels?.[index];
                 const labelledBy = thumbLabel ? undefined : ariaLabelledBy;
                 const label = thumbLabel ?? (ariaLabel ? `${ariaLabel}${values.length > 1 ? ` ${index + 1}` : ''}` : labelledBy ? undefined : `Value${values.length > 1 ? ` ${index + 1}` : ''}`);
                 const inputName = name ? values.length > 1 ? `${name}[]` : name : undefined;
-                return _jsxs(SliderPrimitive.unstable_ThumbProvider, { name: inputName, children: [_jsx(SliderPrimitive.unstable_ThumbTrigger, { "aria-describedby": ariaDescribedBy, "aria-label": label, "aria-labelledby": labelledBy, "aria-valuenow": current, "aria-valuetext": getValueLabel?.(current, index) ?? ariaValueText, className: "inkra-slider__thumb", children: _jsx(PencilSurface, { as: "span", "aria-hidden": "true", className: "inkra-slider__thumb-surface", variant: "paper", radius: 8, seed: `${resolvedSeed}-thumb-${index}`, children: _jsx(PencilSurface, { as: "span", className: "inkra-slider__focus-ring", variant: "outline", radius: 8, seed: `${resolvedSeed}-focus-${index}` }) }) }), _jsx(SliderPrimitive.unstable_BubbleInput, { disabled: disabled, form: form, name: inputName, ref: input => {
+                return _jsxs(SliderPrimitive.unstable_ThumbProvider, { name: inputName, children: [_jsx(SliderPrimitive.unstable_ThumbTrigger, { "aria-describedby": ariaDescribedBy, "aria-label": label, "aria-labelledby": labelledBy, "aria-valuenow": current, "aria-valuetext": getValueLabel?.(current, index) ?? ariaValueText, className: "inkra-slider__thumb", style: { '--inkra-slider-thumb-offset': `${position - 50}%` }, children: _jsx(PencilSurface, { as: "span", "aria-hidden": "true", className: "inkra-slider__thumb-surface", variant: "paper", radius: 8, seed: `${resolvedSeed}-thumb-${index}`, children: _jsx(PencilSurface, { as: "span", className: "inkra-slider__focus-ring", variant: "outline", radius: 8, seed: `${resolvedSeed}-focus-${index}` }) }) }), _jsx(SliderPrimitive.unstable_BubbleInput, { disabled: disabled, form: form, name: inputName, ref: input => {
                                 if (input)
                                     formInputRefs.current.set(index, input);
                                 else
@@ -87,3 +88,4 @@ export const Slider = forwardRef(function Slider({ 'aria-label': ariaLabel, 'ari
                             } })] }, index);
             })] });
 });
+export { CircularSlider } from './circular.js';

package/dist/styles/base.css

@@ -1,5 +1,7 @@
 @import "../tokens.css";
 
+@import "../assets/xiaolai.css";
+
 @font-face {
   font-family: "Trip Map Hand";
   font-style: normal;
@@ -129,13 +131,13 @@
 .inkra-pencil-text__source {
   color: inherit;
   font: inherit;
-  font-family: "Trip Map Hand", "HanziPen SC", "Hannotate SC", "Kaiti SC", "STKaiti", cursive;
   font-kerning: none;
   font-variant-ligatures: none;
   letter-spacing: 0;
 }
 
 .inkra-pencil-text {
+  font-family: var(--inkra-font-hand);
   display: inline-block;
   max-width: 100%;
   min-width: 0;
@@ -216,7 +218,7 @@
   color: var(--inkra-on-accent, var(--inkra-accent-strong));
   cursor: pointer;
   display: inline-flex;
-  font-family: "Trip Map Hand", "HanziPen SC", "Hannotate SC", "Kaiti SC", "STKaiti", cursive;
+  font-family: var(--inkra-font-hand);
   font-weight: var(--inkra-weight-regular);
   justify-content: center;
   letter-spacing: var(--inkra-letter-spacing);

package/dist/styles/breadcrumb.css

@@ -55,7 +55,7 @@
   align-items: center;
   box-sizing: border-box;
   display: inline-flex;
-  font-family: "Trip Map Hand", "HanziPen SC", "Hannotate SC", "Kaiti SC", "STKaiti", cursive;
+  font-family: var(--inkra-font-hand);
   font-size: var(--inkra-breadcrumb-item-font-size);
   gap: var(--inkra-breadcrumb-item-gap);
   justify-content: center;

package/dist/styles/guide.css

@@ -0,0 +1,202 @@
+.inkra-guide__spotlight,
+.inkra-guide__backdrop {
+  inset: 0;
+  pointer-events: none;
+  position: fixed;
+  z-index: calc(var(--inkra-z-modal, 30) + var(--inkra-floating-layer-offset, 0));
+}
+
+.inkra-guide__backdrop {
+  background: var(--inkra-overlay);
+}
+
+.inkra-guide__spotlight {
+  box-shadow: 0 0 0 100vmax var(--inkra-overlay);
+  overflow: visible;
+}
+
+.inkra-guide__spotlight > .inkra-pencil-surface__ink,
+.inkra-guide__spotlight > .inkra-pencil-surface__border {
+  border-radius: var(--inkra-guide-highlight-radius, 8px);
+}
+
+.inkra-guide__content {
+  max-height: min(70dvh, var(--radix-popover-content-available-height, 70dvh));
+  max-width: min(24rem, calc(100dvw - var(--inkra-space-6)));
+  outline: 0;
+  transform-origin: var(--radix-popover-content-transform-origin);
+  width: min(22rem, calc(100dvw - var(--inkra-space-6)));
+  z-index: calc(var(--inkra-z-modal, 30) + var(--inkra-floating-layer-offset, 0) + 1);
+}
+
+.inkra-guide__content:focus-visible {
+  outline: var(--inkra-focus-width) solid var(--inkra-focus);
+  outline-offset: var(--inkra-focus-offset);
+}
+
+.inkra-guide__skip-layer {
+  inset: 0;
+  pointer-events: none;
+  position: fixed;
+  z-index: calc(var(--inkra-z-modal, 30) + var(--inkra-floating-layer-offset, 0) + 2);
+}
+
+.inkra-guide__skip {
+  color: var(--inkra-ink-muted);
+  opacity: .72;
+  pointer-events: auto;
+  position: absolute;
+}
+
+.inkra-guide__skip:is(:hover, :focus-visible) {
+  color: var(--inkra-ink);
+  opacity: 1;
+}
+
+.inkra-guide__skip[data-placement^="top"] {
+  inset-block-start: max(var(--inkra-space-4), env(safe-area-inset-top));
+}
+
+.inkra-guide__skip[data-placement^="bottom"] {
+  inset-block-end: max(var(--inkra-space-4), env(safe-area-inset-bottom));
+}
+
+.inkra-guide__skip[data-placement$="start"] {
+  inset-inline-start: max(var(--inkra-space-4), env(safe-area-inset-left));
+}
+
+.inkra-guide__skip[data-placement$="end"] {
+  inset-inline-end: max(var(--inkra-space-4), env(safe-area-inset-right));
+}
+
+.inkra-guide__surface {
+  color: var(--inkra-ink);
+  display: block;
+  max-height: inherit;
+  width: 100%;
+}
+
+.inkra-guide__panel {
+  box-sizing: border-box;
+  display: grid;
+  gap: var(--inkra-space-4);
+  max-height: inherit;
+  overflow: auto;
+  overflow-wrap: anywhere;
+  overscroll-behavior: contain;
+  padding: var(--inkra-space-5);
+}
+
+.inkra-guide__header,
+.inkra-guide__footer,
+.inkra-guide__navigation {
+  align-items: center;
+  display: flex;
+  gap: var(--inkra-space-2);
+}
+
+.inkra-guide__header {
+  align-items: flex-start;
+}
+
+.inkra-guide__heading {
+  display: grid;
+  flex: 1;
+  gap: var(--inkra-space-1);
+  min-width: 0;
+}
+
+.inkra-guide__progress {
+  color: var(--inkra-ink-subtle);
+  font-family: var(--inkra-font-body);
+  font-size: var(--inkra-text-sm);
+  line-height: var(--inkra-line-ui);
+}
+
+.inkra-guide__title {
+  font-family: var(--inkra-font-display);
+  font-size: var(--inkra-text-xl);
+  font-weight: var(--inkra-weight-regular);
+  line-height: var(--inkra-line-ui);
+  margin: 0;
+}
+
+.inkra-guide__description {
+  color: var(--inkra-ink-muted);
+  font-family: var(--inkra-font-body);
+  font-size: var(--inkra-text-md);
+  line-height: var(--inkra-line-body);
+}
+
+.inkra-guide__close {
+  flex: none;
+}
+
+.inkra-guide__footer {
+  flex-wrap: wrap;
+  justify-content: space-between;
+}
+
+.inkra-guide__footer > :empty {
+  display: none;
+}
+
+.inkra-guide__navigation {
+  flex-wrap: wrap;
+  justify-content: flex-end;
+  margin-inline-start: auto;
+}
+
+.inkra-guide__footer .inkra-button {
+  max-width: 100%;
+}
+
+@media (max-width: 30rem) {
+  .inkra-guide__content {
+    max-height: calc(100dvh - var(--inkra-space-4));
+    max-width: calc(100dvw - var(--inkra-space-4));
+    width: calc(100dvw - var(--inkra-space-4));
+  }
+
+  .inkra-guide__panel {
+    padding: var(--inkra-space-4);
+  }
+
+  .inkra-guide__footer,
+  .inkra-guide__navigation {
+    width: 100%;
+  }
+
+  .inkra-guide__footer > .inkra-button,
+  .inkra-guide__navigation > .inkra-button {
+    flex: 1 1 auto;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .inkra-guide__content {
+    animation: none !important;
+  }
+}
+
+@media (forced-colors: active) {
+  .inkra-guide__backdrop {
+    background: CanvasText;
+    opacity: 0.25;
+  }
+
+  .inkra-guide__spotlight {
+    box-shadow: 0 0 0 100vmax color-mix(in srgb, CanvasText 25%, transparent);
+    outline: 2px solid Highlight;
+  }
+
+  .inkra-guide__surface {
+    background: Canvas;
+    border: 1px solid CanvasText;
+  }
+
+  .inkra-guide__skip {
+    color: ButtonText;
+    opacity: 1;
+  }
+}

package/dist/styles/image-viewer.css

@@ -79,6 +79,7 @@
 }
 
 .inkra-image-viewer__body {
+  position: relative;
   display: grid;
   flex: 1 1 auto;
   min-block-size: var(--inkra-touch-target);
@@ -226,6 +227,24 @@
   padding: var(--inkra-focus-offset);
   position: relative;
   scrollbar-gutter: auto;
+  pointer-events: auto;
+}
+
+.inkra-image-viewer__floating-tools {
+  position: absolute;
+  inset-inline: max(var(--inkra-space-3), env(safe-area-inset-left)) max(var(--inkra-space-3), env(safe-area-inset-right));
+  inset-block-start: max(var(--inkra-space-3), env(safe-area-inset-top));
+  display: flex;
+  justify-content: center;
+  padding-inline: var(--inkra-touch-target);
+  pointer-events: none;
+  z-index: 6;
+}
+
+.inkra-image-viewer__floating-tools[data-position="bottom"] {
+  inset-block-start: auto;
+  inset-block-end: max(var(--inkra-space-3), env(safe-area-inset-bottom));
+  padding-inline: 0;
 }
 
 .inkra-image-viewer__video-navigation {
@@ -345,6 +364,7 @@
 @media print {
   .inkra-image-viewer__close-control,
   .inkra-image-viewer__navigation,
+  .inkra-image-viewer__floating-tools,
   .inkra-image-viewer__bottom { display: none; }
 }