@inkra/react 0.6.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
@@ -176,6 +222,39 @@ All standard `button` props, including `disabled`, `name`, `value`, `form`, `ari
 
 `Input` defaults to an underline appearance, with explicit `outline`, `soft` and `ghost` variants. It supports `startIcon`, `endIcon`, `prefix`, `suffix`, `clearable`, `loading`, `startAction`, `endAction`, `fullWidth` and logical `textAlign`. Use `onValueChange` for edits and clearing; native `onChange` does not receive fabricated clear events. `Field` connects labels, descriptions and errors.
 
+`Textarea` respects an explicit native `rows`, including `rows={1}`. Omit both
+`rows` and `autoSize` to retain the existing sm/md/lg minimum heights. Enable
+`autoSize` to grow and shrink with content, including lines wrapped by the actual
+container width:
+
+```tsx
+import { Textarea } from '@inkra/react/form';
+import type { TextareaAutoSizeOptions } from '@inkra/react/form';
+
+<Textarea rows={1} aria-label="Single-line initial height" />
+<Textarea autoSize={{ minRows: 1, maxRows: 6 }} aria-label="Note" />
+<Textarea autoSize rows={2} aria-label="At least two rows, unlimited growth" />
+```
+
+`autoSize` accepts `boolean | TextareaAutoSizeOptions` and defaults to `false`.
+Its `minRows` falls back to `rows`, then 1; omit `maxRows` for unlimited growth.
+Both limits accept positive safe integers; invalid values use these defaults and
+`maxRows` below `minRows` is raised to `minRows`. The limit counts visible text
+rows, including soft wraps, rather than newline characters or input length.
+Above the maximum, the native editor scrolls internally; deleting text shrinks it.
+Controlled value updates, native form reset, width and font changes remeasure
+without emitting change events or replacing the native control. Empty editors
+size from their minimum rows rather than their placeholder text.
+
+Automatic sizing owns `height`, `minHeight`, `maxHeight` and vertical overflow;
+it takes precedence over inline height and `resize="vertical"`, hiding the manual
+handle. With automatic sizing disabled, manual resizing keeps its existing
+behavior (an explicit `rows` supplies its minimum). Row limits apply only to the
+editor: the character counter retains its separate footer, even while its
+automatic indicator is hidden. On the server, native `rows` provides the initial
+height; existing multi-line content is measured after hydration. Avoid CSS
+`!important` height constraints when enabling automatic sizing.
+
 `InputNumber` places decrease and increase buttons on either side of a centered numeric input, with no clear button. Keyboard deletion produces `null`; decimal stepping and out-of-range validation remain native. `Slider` supports single/range values, horizontal/vertical layout and `standard` or `inset` appearance.
 
 `InputNumber` supports Shift-click and Shift-arrow increments of 10 by default.
@@ -328,7 +407,7 @@ working examples, live property tabs and per-component API/accessibility notes.
 | Drawer | Dialog parts plus section layout, four `Content.direction` values and token/custom `size`; focus trap, Escape and return focus, no swipe gesture API |
 | DatePicker | Calendar/Popover composition; single/range local dates, controlled/default values, clear, form fields and localized labels; no UTC conversion |
 | TimePicker | Native time input with clear, disabled/readOnly, min/max/step and optional seconds; browser/OS controls the native presentation |
-| Pagination | Page count/current page, boundary actions and ellipses; buttons change local state rather than pretending to navigate URLs |
+| Pagination | Page count/current page, boundary actions and ellipses; optional page-size selection, button variants, logical alignment and wrapping |
 | Empty | Optional `Root`, `Icon`, `Title`, `Description`, `Actions`; no mandatory card or live-region role |
 | ToggleGroup | `Root` and `Item`; array values for single/multiple toggles, roving focus and `aria-pressed`, not tabs |
 | Command | cmdk-backed search, grouped commands, empty/disabled states and optional modal composition |
@@ -338,6 +417,49 @@ working examples, live property tabs and per-component API/accessibility notes.
 | Steps | Ordered `items`, `current`, orientation and optional `onStepChange`; status and disabled steps |
 | Timeline | Ordered `items` with date/title/description/content, semantic `dateTime` and horizontal/vertical orientation |
 
+### Pagination page sizes
+
+```tsx
+const [page, setPage] = useState(1);
+const [pageSize, setPageSize] = useState(20);
+<Pagination totalPages={Math.ceil(itemCount / pageSize)}
+  page={page} onPageChange={setPage}
+  pageSize={pageSize} onPageSizeChange={setPageSize}
+  pageSizeOptions={[10, 20, 50]} hideOnSinglePage
+  variant="outline" align="end" wrap />
+```
+
+The caller computes `totalPages` and slices or fetches its data. `pageSize` is
+controlled; `defaultPageSize` initializes an uncontrolled size (default `10`).
+Only positive safe integers are accepted. Invalid sizes fall back to `10`;
+invalid options are ignored, duplicates removed and options sorted numerically.
+The current size is retained in a nonempty option list. Omit `pageSizeOptions`
+or provide no valid options to hide the selector.
+
+Selecting a different size first calls `onPageSizeChange(size)`, then requests
+`onPageChange(1)` when the current page exceeds one. Each uncontrolled state
+updates independently; controlled state changes only when the parent accepts
+the request. Rendering, changing totals or options, and clamping do not emit
+user callbacks. `hideOnSinglePage` hides page controls for zero or one page while
+retaining the size selector.
+
+`variant` uses the Button variants (default `ghost`). `align` accepts logical
+`start | center | end` (default `start`); `wrap` defaults to `false` and retains
+local horizontal scrolling. The size selector reuses Select, inherits disabled
+state and direction, and uses InkraProvider labels. Override
+`labels.pageSize` (accessible name) and `labels.pageSizeOption(size)` (visible
+option text) for application-specific copy. `simple`, `renderPage` and
+`renderSummary` compose with these options.
+
+分页容量由调用方计算总页数并切分或请求数据。`pageSize` 为受控值，
+`defaultPageSize` 为非受控初值，默认 10；只接收正安全整数。非法容量回退为
+10，非法选项忽略，选项去重并排序，有效列表保留当前容量。省略或提供空的有效
+选项列表时不显示选择器。切换容量先通知 `onPageSizeChange`，当前页大于 1 时
+再请求 `onPageChange(1)`；受控值由父组件决定是否接受。渲染、总页数及选项变化
+不触发交互回调。`hideOnSinglePage` 隐藏翻页按钮但保留容量选择器；`align`
+按逻辑方向对齐，`wrap` 允许换行，默认仍为局部横滚。容量选择复用 Select，
+继承禁用、方向和语言设置，可用 `labels.pageSize/pageSizeOption` 覆盖文案。
+
 ## Utility Components (Unreleased)
 
 `Slot` is a fixed square visual container for arbitrary icons or content. Static
@@ -359,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,
@@ -470,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/Button.js

@@ -36,7 +36,7 @@ function ButtonVisual({ children, endIcon, loading, loadingPosition, loadingIndi
     const label = typeof children === 'string'
         ? _jsx(PencilText, { seed: `${seed}-label`, children: children })
         : children == null ? null : _jsx("span", { children: children });
-    return (_jsxs(_Fragment, { children: [_jsx(PencilSurface, { as: "span", className: "inkra-button__surface", clipContent: sharedOutline, radius: sharedOutline ? 0 : undefined, seed: seed, variant: inputAction ? 'ghost' : surfaceVariant(variant), children: _jsxs("span", { className: "inkra-button__content", children: [loading && loadingPosition === 'center' ? indicator : null, iconSlot('start', startIcon), label == null ? null : _jsxs("span", { className: "inkra-button__label", children: [label, variant === 'link' ? _jsx(PencilLine, { className: "inkra-button__underline", seed: `${seed}-underline`, weight: 0.9 }) : null] }), iconSlot('end', endIcon)] }) }), _jsx(PencilSurface, { as: "span", "aria-hidden": "true", className: "inkra-button__focus-ring", variant: "outline", seed: `${seed}-focus` }), group === null ? null : _jsx(PencilLine, { className: "inkra-button-group__divider", orientation: group.orientation === 'horizontal' ? 'vertical' : 'horizontal', seed: `${seed}-group-divider` })] }));
+    return (_jsxs(_Fragment, { children: [_jsx(PencilSurface, { as: "span", className: "inkra-button__surface", clipContent: sharedOutline || variant === 'ghost', radius: sharedOutline ? 0 : undefined, seed: seed, variant: inputAction ? 'ghost' : surfaceVariant(variant), children: _jsxs("span", { className: "inkra-button__content", children: [loading && loadingPosition === 'center' ? indicator : null, iconSlot('start', startIcon), label == null ? null : _jsxs("span", { className: "inkra-button__label", children: [label, variant === 'link' ? _jsx(PencilLine, { className: "inkra-button__underline", seed: `${seed}-underline`, weight: 0.9 }) : null] }), iconSlot('end', endIcon)] }) }), _jsx(PencilSurface, { as: "span", "aria-hidden": "true", className: "inkra-button__focus-ring", variant: "outline", seed: `${seed}-focus` }), group === null ? null : _jsx(PencilLine, { className: "inkra-button-group__divider", orientation: group.orientation === 'horizontal' ? 'vertical' : 'horizontal', seed: `${seed}-group-divider` })] }));
 }
 export const Button = forwardRef(function Button({ children, 'aria-label': ariaLabel, className, disabled = false, endIcon, loading = false, loadingPosition = 'center', loadingIndicator, fullWidth = false, align = 'center', seed, size: sizeProp, startIcon, type = 'button', variant: variantProp, ...props }, ref) {
     const id = useId();

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/PencilText.js

@@ -324,6 +324,14 @@ const PencilTextImplementation = forwardRef(function PencilText({ as: Element =
             markDirty();
         });
         schedule();
+        // Ancestor layout effects can reveal a clipped label during the same commit.
+        if (!visible)
+            queueMicrotask(() => {
+                if (!disposed && dirty && inViewport()) {
+                    visible = true;
+                    schedule();
+                }
+            });
         return () => {
             disposed = true;
             stopRecovery();

package/dist/form/Textarea.d.ts

@@ -1,5 +1,7 @@
 import type { ReactNode, TextareaHTMLAttributes } from 'react';
 import type { FieldControlStateProps } from './types.js';
+import type { TextareaAutoSizeOptions } from './textareaSizing.js';
+export type { TextareaAutoSizeOptions } from './textareaSizing.js';
 export interface TextareaCountDetails {
     count: number;
     maxLength: number;
@@ -15,5 +17,7 @@ export interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElemen
     getCountLabel?: (details: TextareaCountDetails) => string;
     resize?: 'none' | 'vertical';
     resizeLabel?: string;
+    /** Grow and shrink with content. Takes precedence over manual resize and inline height. */
+    autoSize?: boolean | TextareaAutoSizeOptions;
 }
 export declare const Textarea: import("react").ForwardRefExoticComponent<TextareaProps & import("react").RefAttributes<HTMLTextAreaElement>>;

package/dist/form/Textarea.js

@@ -10,16 +10,19 @@ import { Progress } from '../display/index.js';
 import { useResolvedControlProps } from './controlProps.js';
 import { EditablePencilText } from './EditablePencilText.js';
 import { InputAction } from './InputAction.js';
+import { textareaResizeHeight, useTextareaSizing } from './textareaSizing.js';
 const resizePaths = [{ d: 'M12 3v18M8 7l4-4 4 4M8 17l4 4 4-4' }];
 export const Textarea = forwardRef(function Textarea(inkraProps, ref) {
     const { t } = useInkraLocale();
-    const { 'aria-describedby': ariaDescribedBy, 'aria-errormessage': ariaErrorMessage, 'aria-invalid': ariaInvalid, className, disabled, id, invalid = false, readOnly, required, seed, size = 'md', variant = 'outline', endAction, countMode = 'remaining', countDisplay = 'auto', countThreshold = 0.8, getCountLabel = ({ remaining }) => t(remaining < 0 ? 'textarea.overLimit' : 'textarea.countRemaining', { count: Math.abs(remaining) }), resize = 'none', resizeLabel = t('textarea.resize'), ...props } = inkraProps;
+    const { 'aria-describedby': ariaDescribedBy, 'aria-errormessage': ariaErrorMessage, 'aria-invalid': ariaInvalid, className, disabled, id, invalid = false, readOnly, required, seed, size = 'md', variant = 'outline', endAction, countMode = 'remaining', countDisplay = 'auto', countThreshold = 0.8, getCountLabel = ({ remaining }) => t(remaining < 0 ? 'textarea.overLimit' : 'textarea.countRemaining', { count: Math.abs(remaining) }), resize = 'none', resizeLabel = t('textarea.resize'), autoSize = false, ...props } = inkraProps;
     const generatedId = useId();
     const textareaRef = useRef(null);
     const [uncontrolledCount, setUncontrolledCount] = useState(() => String(props.defaultValue ?? '').length);
     const [height, setHeight] = useState();
     const [measuredHeight, setMeasuredHeight] = useState();
     const drag = useRef(null);
+    const sizing = useTextareaSizing(textareaRef, autoSize, props.rows, props.form, resize === 'vertical');
+    const manualResize = resize === 'vertical' && !sizing.enabled;
     const controlled = props.value != null;
     const count = controlled ? String(props.value).length : uncontrolledCount;
     const maximum = props.maxLength;
@@ -30,11 +33,12 @@ export const Textarea = forwardRef(function Textarea(inkraProps, ref) {
     const controlId = id ?? `inkra-textarea-${generatedId}`;
     const remaining = hasCount ? maximum - count : 0;
     const countLabel = hasCount ? getCountLabel({ count, maxLength: maximum, remaining }) : '';
-    const minimumHeight = size === 'sm' ? 80 : size === 'lg' ? 112 : 96;
-    const resizeTo = (next) => setHeight(Math.max(minimumHeight, Math.min(1200, next)));
+    const minimumHeight = (sizing.minimumHeight ?? (size === 'sm' ? 80 : size === 'lg' ? 112 : 96)) + sizing.boxAdjustment;
+    const maximumHeight = Math.max(1200, minimumHeight);
+    const resizeTo = (next) => setHeight(textareaResizeHeight(next, minimumHeight, maximumHeight, sizing.boxAdjustment));
     useEffect(() => {
         const control = textareaRef.current;
-        if (resize !== 'vertical' || !control)
+        if (!manualResize || !control)
             return;
         const measure = () => setMeasuredHeight(control.getBoundingClientRect().height);
         measure();
@@ -43,7 +47,7 @@ export const Textarea = forwardRef(function Textarea(inkraProps, ref) {
         const observer = new ResizeObserver(measure);
         observer.observe(control);
         return () => observer.disconnect();
-    }, [resize]);
+    }, [manualResize]);
     useEffect(() => {
         const control = textareaRef.current;
         const form = control?.form;
@@ -73,11 +77,13 @@ export const Textarea = forwardRef(function Textarea(inkraProps, ref) {
     });
     const resolvedSeed = seed ?? `inkra-textarea-${state.id ?? generatedId}`;
     const classes = ['inkra-textarea', className].filter(Boolean).join(' ');
-    return (_jsx("div", { className: "inkra-field-control-hit inkra-field-control-hit--textarea", "data-disabled": state.disabled || undefined, "data-invalid": state.invalid || undefined, "data-readonly": state.readOnly || undefined, "data-size": size, "data-variant": variant, "data-end-action": endAction != null || undefined, children: _jsxs(PencilSurface, { className: "inkra-field-control inkra-field-control--textarea", seed: resolvedSeed, variant: variant === 'underline' ? 'ghost' : state.invalid ? 'danger' : 'outline', children: [_jsx("textarea", { ...props, "aria-describedby": [state.describedBy, showCount && countId].filter(Boolean).join(' ') || undefined, "aria-errormessage": state.errorMessage, "aria-invalid": state.ariaInvalid, className: classes, disabled: state.disabled, id: state.id, readOnly: state.readOnly, ref: textareaRef, required: state.required, style: { ...props.style, ...(resize === 'vertical' && height !== undefined ? { height } : {}), resize: 'none' }, onInput: event => {
+    return (_jsx("div", { className: "inkra-field-control-hit inkra-field-control-hit--textarea", "data-disabled": state.disabled || undefined, "data-invalid": state.invalid || undefined, "data-readonly": state.readOnly || undefined, "data-size": size, "data-variant": variant, "data-end-action": endAction != null || undefined, "data-row-sizing": sizing.rowSizing || undefined, children: _jsxs(PencilSurface, { className: "inkra-field-control inkra-field-control--textarea", seed: resolvedSeed, variant: variant === 'underline' ? 'ghost' : state.invalid ? 'danger' : 'outline', children: [_jsx("textarea", { ...props, "aria-describedby": [state.describedBy, showCount && countId].filter(Boolean).join(' ') || undefined, "aria-errormessage": state.errorMessage, "aria-invalid": state.ariaInvalid, className: classes, disabled: state.disabled, id: state.id, readOnly: state.readOnly, ref: textareaRef, required: state.required, rows: sizing.enabled ? sizing.minRows : props.rows, style: { ...props.style, ...(manualResize && height !== undefined ? { height: Math.max(height, sizing.minimumHeight ?? height) } : {}), ...sizing.style, resize: 'none' }, onInput: event => {
                         if (!controlled)
                             setUncontrolledCount(event.currentTarget.value.length);
                         props.onInput?.(event);
-                    } }), _jsx(EditablePencilText, { controlRef: textareaRef, defaultValue: props.defaultValue, multiline: true, placeholder: props.placeholder, seed: `${resolvedSeed}-editable`, value: props.value }), endAction != null && _jsx("div", { className: "inkra-textarea__end-action", children: _jsx(InputAction, { disabled: Boolean(state.disabled), seed: `${resolvedSeed}-action`, children: endAction }) }), (hasCount || resize === 'vertical') && _jsxs("div", { className: "inkra-textarea__footer", children: [hasCount && _jsxs("div", { className: "inkra-textarea__count", id: countId, "data-visible": showCount, "data-limit": remaining <= 0 ? 'reached' : 'near', "aria-hidden": !showCount || undefined, children: [countMode === 'progress' && _jsx(Progress, { size: "sm", value: maximum === 0 ? 1 : count, max: maximum === 0 ? 1 : maximum, "aria-label": countLabel, "aria-valuetext": countLabel }), _jsx(PencilText, { children: countMode === 'fraction' ? `${count} / ${maximum}` : countLabel })] }), resize === 'vertical' && _jsx(Button, { className: "inkra-textarea__resize", variant: "ghost", size: "icon", role: "slider", "aria-label": resizeLabel, title: resizeLabel, "aria-controls": state.id, "aria-orientation": "vertical", "aria-valuemin": minimumHeight, "aria-valuemax": 1200, "aria-valuenow": Math.round(measuredHeight ?? minimumHeight), disabled: state.disabled, onPointerDown: event => {
+                        // Wait for React to accept or restore a controlled value before measuring.
+                        sizing.schedule();
+                    } }), _jsx(EditablePencilText, { controlRef: textareaRef, defaultValue: props.defaultValue, multiline: true, placeholder: props.placeholder, seed: `${resolvedSeed}-editable`, value: props.value }), endAction != null && _jsx("div", { className: "inkra-textarea__end-action", children: _jsx(InputAction, { disabled: Boolean(state.disabled), seed: `${resolvedSeed}-action`, children: endAction }) }), (hasCount || manualResize) && _jsxs("div", { className: "inkra-textarea__footer", children: [hasCount && _jsxs("div", { className: "inkra-textarea__count", id: countId, "data-visible": showCount, "data-limit": remaining <= 0 ? 'reached' : 'near', "aria-hidden": !showCount || undefined, children: [countMode === 'progress' && _jsx(Progress, { size: "sm", value: maximum === 0 ? 1 : count, max: maximum === 0 ? 1 : maximum, "aria-label": countLabel, "aria-valuetext": countLabel }), _jsx(PencilText, { children: countMode === 'fraction' ? `${count} / ${maximum}` : countLabel })] }), manualResize && _jsx(Button, { className: "inkra-textarea__resize", variant: "ghost", size: "icon", role: "slider", "aria-label": resizeLabel, title: resizeLabel, "aria-controls": state.id, "aria-orientation": "vertical", "aria-valuemin": minimumHeight, "aria-valuemax": maximumHeight, "aria-valuenow": Math.round(Math.max(measuredHeight ?? minimumHeight, minimumHeight)), disabled: state.disabled, onPointerDown: event => {
                                 if (event.button !== 0)
                                     return;
                                 drag.current = { y: event.clientY, height: textareaRef.current?.getBoundingClientRect().height ?? minimumHeight };
@@ -98,7 +104,7 @@ export const Textarea = forwardRef(function Textarea(inkraProps, ref) {
                                 else if (event.key === 'Home')
                                     resizeTo(minimumHeight);
                                 else if (event.key === 'End')
-                                    resizeTo(1200);
+                                    resizeTo(maximumHeight);
                                 else
                                     return;
                                 event.preventDefault();

package/dist/form/index.d.ts

@@ -3,5 +3,5 @@ export type { FieldProps } from './Field.js';
 export { Input } from './Input.js';
 export type { InputProps, InputVariant, InputTextAlign, InputValueChangeDetails, InputClassNames } from './Input.js';
 export { Textarea } from './Textarea.js';
-export type { TextareaProps, TextareaCountDetails } from './Textarea.js';
+export type { TextareaProps, TextareaCountDetails, TextareaAutoSizeOptions } from './Textarea.js';
 export type { FieldControlSize, FieldControlStateProps } from './types.js';

package/dist/form/textareaSizing.d.ts

@@ -0,0 +1,29 @@
+import type { CSSProperties, RefObject } from 'react';
+export interface TextareaAutoSizeOptions {
+    /** Minimum visible text rows. Falls back to rows, then 1. */
+    minRows?: number;
+    /** Maximum visible text rows, including soft wraps. Omit for unlimited growth. */
+    maxRows?: number;
+}
+export declare function resolveTextareaRows(autoSize: boolean | TextareaAutoSizeOptions | undefined, rows?: number): {
+    minRows: number;
+    maxRows: number;
+};
+/** Measure a native textarea without changing its value, selection, scroll position or height. */
+export declare function measureTextareaSize(control: HTMLTextAreaElement, minRows: number, maxRows: number, measureContent?: boolean): {
+    minimumHeight: number;
+    boxAdjustment: number;
+    height: number;
+    overflowY: "hidden" | "auto";
+} | undefined;
+export declare function useTextareaSizing(controlRef: RefObject<HTMLTextAreaElement | null>, autoSize: boolean | TextareaAutoSizeOptions | undefined, rows: number | undefined, form: string | undefined, manualResize?: boolean): {
+    enabled: boolean;
+    rowSizing: boolean;
+    minRows: number;
+    minimumHeight: number | undefined;
+    boxAdjustment: number;
+    style: CSSProperties | undefined;
+    schedule: () => void;
+};
+/** Manual handles and ARIA use visible border-box pixels; CSS height may use content-box pixels. */
+export declare function textareaResizeHeight(visibleHeight: number, minimum: number, maximum: number, boxAdjustment: number): number;