@inkra/react 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # Inkra
 
-Inkra is a pencil-styled React component library. It includes action, form, overlay, navigation, content and feedback components, plus Calendar, DayAgenda, JourneyMap and deterministic drawing primitives. The first `0.1.0` release is being prepared; this package is still an unpublished candidate unless a corresponding registry release has been announced.
+Inkra is a pencil-styled React component library. It includes action, form, overlay, navigation, content and feedback components, plus Calendar, DayAgenda, JourneyMap and deterministic drawing primitives. Version `0.1.0` is published; the component expansion described below is available only in the current, unpublished source candidate.
 
 Source and maintenance: [inkrajs/inkra](https://github.com/inkrajs/inkra).
 
@@ -150,12 +150,31 @@ outside interaction, modal focus trapping and focus return.
 <Skeleton style={{ width: 200, height: 20 }} />
 <Progress label="Uploading" value={60} />
 <Progress aria-label="Loading" value={null} />
+<Progress shape="circular" value={72} diameter={128} thickness={6} aria-label="Download">
+  {({ percent }) => `${Math.round(percent ?? 0)}%`}
+</Progress>
+<Progress shape="circular" value={3} max={5} contentPosition="end" label="Files">
+  <span>3 / 5 files</span>
+</Progress>
 ```
 
 `Badge` variants are `neutral`, `accent`, `success`, `warning`, `danger` and `info`. `Separator` has horizontal/vertical orientation and a decorative opt-out. `Skeleton` is a static, aria-hidden placeholder; mark its loading container `aria-busy`. `Progress` clamps numeric values to `0..max` (default 100); `null` is indeterminate without a fabricated percentage. Always provide a progress label.
 
 `Badge.size` accepts `sm | md | lg` with optional `startIcon` and `endIcon`. `Separator.weight` clamps to 0.3–2 (default 0.9). `Skeleton.radius` uses the existing 0–8px pencil corner contract. `Progress.size` selects a 12/16/24px track (`sm/md/lg`); `dir`, `aria-valuetext`, refs and native DOM attributes remain available. Tooltip exposes the underlying delay, alignment, collision and hoverable-content controls alongside `Content.surfaceRadius`.
 
+Circular Progress uses a grainy pencil arc with naturally tapered ends and an
+empty gap for the remaining progress.
+`size` selects a 64/96/128px diameter; `diameter` overrides it (32-512px), and
+`thickness` sets the base stroke width (1-diameter/8px, affected by global stroke
+settings). `children` accepts non-interactive icons/text or a render function
+receiving normalized `{ value, max, percent }`; unknown value/percent are null.
+`contentPosition` supports `center`, `top`, `bottom`, `start`, and `end`; logical
+sides follow RTL. Circular defaults to center, linear to end (including explicit
+center). Keep center content short; longer descriptions belong outside the ring.
+Always supply a label or ARIA name, even for icon content. Progress updates reveal
+the existing texture; only unknown progress rotates, respecting reduced motion.
+Canvas failures, forced colors and printing retain an SVG progress fallback.
+
 ## Menus And Content
 
 `DropdownMenu` exposes `Root`, `Trigger`, `Portal`, `Content`, `Item`, `CheckboxItem`, `RadioGroup`, `RadioItem`, `Group`, `Label` and `Separator`. It supports controlled open state, placement/collision props, disabled items, keyboard navigation and focus return. Use `Trigger asChild` with a Button; use `Item.destructive` for dangerous actions. Portal content inherits the trigger theme. Submenus are not included yet.
@@ -176,6 +195,63 @@ Content layout options preserve existing defaults:
 - `Avatar.Root.radius` clamps to 0-8px, including pencil and image corners; `bordered={false}` removes the outline. `Avatar.Image.fit` accepts `cover | contain` (default cover).
 - `Table.Root.striped`, `hoverable` and `stickyHeader` default to false. Constrain `Table.Container` with `style={{ maxHeight: 240 }}` for sticky scrolling. `captionSide` accepts `top | bottom`. `Head.align` and `Cell.align` accept logical `start | center | end`, retaining native alignment values for compatibility. Hover feedback does not imply row actions.
 
+## Component Expansion (Unreleased)
+
+These exports are not present in the published 0.1.0 archive. Build, pack and
+install the local candidate to use them. The documentation playground includes
+working examples, live property tabs and per-component API/accessibility notes.
+
+| Component | Contract |
+| --- | --- |
+| Toast | `Provider`, `useToastManager`, `createToastManager`; add/update/close/promise notifications, named actions and timer pause managed by Base UI |
+| AlertDialog | Always-modal confirmation; `Root`, `Trigger`, `Portal`, `Backdrop`, `Content`, `Header`, `Body`, `Footer`, `Title`, `Description`, `Cancel`, `Action`; pending blocks user dismissal, async actions use `closeOnAction={false}` |
+| 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 |
+| 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 |
+| Upload | File selection/drop, type/size/count rejection, removal, progress, cancel and retry; application transport receives `AbortSignal` and `reportProgress` |
+| DataTable | Typed columns, required stable `getRowId`, sorting, filtering, pagination, selection, empty/loading state; native table semantics |
+| Tree | `Root`, `Item`, `ItemContent`, `ItemTitle`, `ItemDescription`; stable keys, expansion and selection via React Aria; no drag/drop |
+| 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 |
+
+## Utility Components (Unreleased)
+
+`Slot` is a fixed square visual container for arbitrary icons or content. Static
+slots render a `div`; `interactive` slots render one native button with
+`aria-pressed` selection and native Enter/Space behavior. `empty` preserves
+geometry, `count` reuses Badge, and `renderCount` keeps custom rendering at the
+logical corner. Keep nested controls out of interactive slots. Slot does not
+implement equipment rules, rarity, sorting or drag and drop.
+
+`Hotkey` formats shortcut values for Mac or Windows. `HotkeyInput` records only
+while its native input is focused, supports controlled/uncontrolled values,
+clear, Escape cancellation, read-only/disabled states, IME safeguards and
+caller-owned conflict validation. It does not register global shortcut listeners
+or suppress browser shortcuts.
+
+`NumberTicker` formats values with `Intl.NumberFormat`, optionally animates from
+the currently displayed frame, and can show a temporary signed delta. Reduced
+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.
+
+`Log` renders caller-ordered records with stable ids, optional level filters and
+pause/follow controls. It follows only append updates while the viewport remains
+near the bottom. The named scroll region supports Home/End and intentionally is
+not a live region, so a long stream is not repeatedly announced. Log does not
+provide persistence, virtualization or transport.
+
+Upload does not send files anywhere unless the application supplies `onUpload`.
+Without a transport, files remain selected, not successfully uploaded. Client
+validation is a convenience; the receiving server must validate files itself.
+DataTable does not replace `Table` and does not promise virtualization, cell
+editing or server-side transport. Tree is not a file-system permission boundary.
+All examples use public sample data.
+
 ## Travel Components
 
 `Calendar` wraps React DayPicker with default `appearance="itinerary"` day cards and optional `appearance="picker"`. It retains single/multiple/range selection, month control, disabled matchers, locale and keyboard navigation. Supply `selected` and `onSelect` for controlled selection. Events have independent `onEventSelect` handling; `displayRange` and `renderDayAccessory` customize the itinerary. Narrow itinerary grids retain seven columns and hide event text while preserving accessible names; picker targets remain at least 44px.
@@ -199,6 +275,33 @@ Content layout options preserve existing defaults:
 <PencilLine orientation="vertical" seed="sidebar-divider" className="sidebar-divider" />
 ```
 
+### Rendering tokens
+
+`PencilText` reads `--inkra-letter-variation`, `--inkra-letter-breaks`,
+`--inkra-letter-outline`, `--inkra-letter-fill`, and `--inkra-letter-grain` from
+its computed style. Values are clamped to 0-1; missing or invalid values use the
+default lettering preset (0.20, 0.50, 0.90, 0.90, 0.60 respectively). Apply these tokens to an ancestor to customize all
+text within that scope without changing layout, selectable text, or labels.
+
+`PencilLine` reads `--inkra-stroke-width` (0.3-3) and
+`--inkra-stroke-amplitude` (0-4) when `weight` or `roughness` is omitted.
+Explicit props take precedence. These tokens also scale surface outlines and icon
+strokes relative to their original presets, including button/card/input borders.
+The default values are 2 and 1.5. They do not change layout or text lettering.
+
+Surface fills read `--inkra-wash-strength` (0-1, default 0.8),
+`--inkra-wash-spacing` (1-6, default 2), `--inkra-wash-roughness` (0-6,
+default 3), and `--inkra-wash-angle` (-85 to 85 degrees, default -45).
+Strength scales each variant's original light/dark pigment intensity relative to
+the original 0.48 reference. These settings affect button fills, selections
+and swatches, not paper or lettering. Selection reveals follow the chosen angle.
+
+Only self/ancestor appearance changes invalidate decoration, not unrelated theme
+subtrees. Unchanged computed paint settings are reused, including when a dialog
+changes body pointer events or scroll locks. Rendering settings are part of the
+bounded texture cache keys. No page remount is needed. Forced-color, print, and
+unavailable-canvas fallbacks remain intact.
+
 ## Font license
 
 The package includes `Trip Map Hand`, a modified web subset of Yozai Light v0.868, under the SIL Open Font License 1.1. The font is not covered by Inkra's MIT software license. See `THIRD_PARTY_NOTICES.md` and `Yozai-OFL.txt` in the package.

package/dist/PencilIcon.js

@@ -4,6 +4,7 @@ import { BoundedCache, PENCIL_RENDERER_VERSION, canvasByteCost, canvasIsUsable,
 import { observeCanvasRecovery } from './internal/recovery.js';
 import { seedToNumber } from './internal/random.js';
 import { pencilStroke } from './internal/stroke.js';
+import { maxStrokeRoughness, pencilRenderDefaults, readRenderToken } from './internal/renderTokens.js';
 const geometryCache = new BoundedCache(256, 180000);
 const imageCache = new BoundedCache(128, 24 * 1024 * 1024);
 function cachedPathParts(data) {
@@ -45,6 +46,7 @@ function drawFallbackPath(context, data, color, mode, weightScale = 1) {
 function renderIcon(paths, options) {
     const { seed, size, sourceSize, active, color, dpr } = options;
     const weightScale = options.weightScale ?? 1;
+    const roughnessScale = options.roughnessScale ?? 1;
     const canvas = document.createElement('canvas');
     canvas.width = Math.round(size * dpr);
     canvas.height = Math.round(size * dpr);
@@ -76,7 +78,7 @@ function renderIcon(paths, options) {
         try {
             const parts = cachedPathParts(path.d);
             for (const points of parts) {
-                pencilStroke(context, points, color, (mode === 'scuff' ? 0.55 : 1.65) * weightScale, pathSeed, 0.3, mode === 'scuff' ? 1 : 3, false, {
+                pencilStroke(context, points, color, (mode === 'scuff' ? 0.55 : 1.65) * weightScale, pathSeed, 0.3 * roughnessScale, mode === 'scuff' ? 1 : 3, false, {
                     variation: 0.82,
                     breaks: 0.18,
                     grain: 0.68,
@@ -91,7 +93,7 @@ function renderIcon(paths, options) {
         }
     });
     if (active) {
-        pencilStroke(context, [[sourceSize * 0.2, sourceSize - 2], [sourceSize * 0.5, sourceSize - 1.5], [sourceSize * 0.8, sourceSize - 2.2]], color, 1.1, seed + 977, 0.25, 3, false, { variation: 0.8, breaks: 0.25, grain: 0.7, gain: 2.8, step: 0.35 });
+        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, breaks: 0.25, grain: 0.7, gain: 2.8, step: 0.35 });
     }
     if (options.badge?.paths.length) {
         const badge = options.badge;
@@ -104,7 +106,7 @@ function renderIcon(paths, options) {
         const y = position.startsWith('top') ? 0 : 40 - extent;
         const badgeImage = renderIcon(badge.paths, {
             seed: seed + 1543, size: size * scale, sourceSize: badgeSourceSize, active: false, color, dpr,
-            weightScale: 1 / scale,
+            weightScale: weightScale / scale, roughnessScale,
         });
         const mask = document.createElement('canvas');
         mask.width = badgeImage.width;
@@ -135,6 +137,7 @@ function renderIcon(paths, options) {
 }
 export const PencilIcon = forwardRef(function PencilIcon({ active = false, badge, className = '', decorative = true, paths, seed, size = 40, sourceSize = 32, ...props }, forwardedRef) {
     const canvasRef = useRef(null);
+    const lastPaintRef = useRef('');
     useImperativeHandle(forwardedRef, () => canvasRef.current);
     const geometryKey = useMemo(() => JSON.stringify(paths), [paths]);
     const badgeKey = useMemo(() => badge ? JSON.stringify(badge) : '', [badge]);
@@ -144,7 +147,6 @@ export const PencilIcon = forwardRef(function PencilIcon({ active = false, badge
         if (!canvas)
             return undefined;
         let disposed = false;
-        let lastPaint = '';
         const paint = () => {
             if (disposed)
                 return;
@@ -152,6 +154,8 @@ export const PencilIcon = forwardRef(function PencilIcon({ active = false, badge
             const computed = getComputedStyle(canvas);
             const color = computed.color;
             const rtl = computed.direction === 'rtl';
+            const weightScale = readRenderToken(computed, '--inkra-stroke-width', pencilRenderDefaults.strokeWidth, 0.3, 3) / 1.2;
+            const roughnessScale = readRenderToken(computed, '--inkra-stroke-amplitude', pencilRenderDefaults.strokeRoughness, 0, maxStrokeRoughness) / 0.6;
             const key = JSON.stringify([
                 PENCIL_RENDERER_VERSION,
                 geometryKey,
@@ -163,8 +167,9 @@ export const PencilIcon = forwardRef(function PencilIcon({ active = false, badge
                 active,
                 color,
                 dpr,
+                weightScale, roughnessScale,
             ]);
-            if (key === lastPaint && canvasIsUsable(canvas))
+            if (key === lastPaintRef.current && canvasIsUsable(canvas))
                 return;
             let image = imageCache.get(key);
             if (image && !canvasIsUsable(image)) {
@@ -172,7 +177,7 @@ export const PencilIcon = forwardRef(function PencilIcon({ active = false, badge
                 image = undefined;
             }
             if (!image) {
-                image = renderIcon(paths, { seed: resolvedSeed, size, sourceSize, active, color, dpr, badge, rtl });
+                image = renderIcon(paths, { seed: resolvedSeed, size, sourceSize, active, color, dpr, badge, rtl, weightScale, roughnessScale });
                 imageCache.set(key, image, canvasByteCost(image));
             }
             canvas.width = image.width;
@@ -181,26 +186,19 @@ export const PencilIcon = forwardRef(function PencilIcon({ active = false, badge
             if (!context || context.isContextLost?.())
                 return;
             context.drawImage(image, 0, 0);
-            lastPaint = key;
+            lastPaintRef.current = key;
         };
-        const appearance = new MutationObserver(paint);
-        appearance.observe(document.documentElement, {
-            attributes: true,
-            subtree: true,
-            attributeFilter: ['data-theme', 'data-inkra-theme'],
-        });
         const inheritedColor = new MutationObserver(paint);
         for (let element = canvas; element; element = element.parentElement) {
-            inheritedColor.observe(element, { attributes: true, attributeFilter: ['style', 'class', 'dir'] });
+            inheritedColor.observe(element, { attributes: true, attributeFilter: ['style', 'class', 'dir', 'data-theme', 'data-inkra-theme'] });
         }
         const colorScheme = window.matchMedia('(prefers-color-scheme: dark)');
         colorScheme.addEventListener('change', paint);
-        const stopRecovery = observeCanvasRecovery(() => { lastPaint = ''; paint(); });
+        const stopRecovery = observeCanvasRecovery(() => { lastPaintRef.current = ''; paint(); });
         paint();
         return () => {
             disposed = true;
             stopRecovery();
-            appearance.disconnect();
             inheritedColor.disconnect();
             colorScheme.removeEventListener('change', paint);
         };

package/dist/PencilLine.js

@@ -5,6 +5,7 @@ import { observeCanvasRecovery } from './internal/recovery.js';
 import { seedToNumber } from './internal/random.js';
 import { createPencilLinePoints, pencilLineHasDrawableSize } from './internal/line.js';
 import { pencilStroke } from './internal/stroke.js';
+import { maxStrokeRoughness, pencilRenderDefaults, readRenderToken } from './internal/renderTokens.js';
 const lineCache = new BoundedCache(96, 12 * 1024 * 1024);
 function renderLine(width, height, color, seed, weight, roughness, orientation, dpr) {
     const canvas = document.createElement('canvas');
@@ -17,7 +18,7 @@ function renderLine(width, height, color, seed, weight, roughness, orientation,
     pencilStroke(context, createPencilLinePoints(width, height, orientation, roughness), color, weight, seed, roughness, 3, false, { variation: 0.82, breaks: 0.18, grain: 0.68, gain: 2.6, step: 0.5, taperLength: 1.4 });
     return canvas;
 }
-export const PencilLine = forwardRef(function PencilLine({ className = '', orientation = 'horizontal', roughness = 0.6, seed = 'inkra-pencil-line', weight = 1.2, ...props }, forwardedRef) {
+export const PencilLine = forwardRef(function PencilLine({ className = '', orientation = 'horizontal', roughness, seed = 'inkra-pencil-line', weight, ...props }, forwardedRef) {
     const canvasRef = useRef(null);
     useImperativeHandle(forwardedRef, () => canvasRef.current);
     useEffect(() => {
@@ -26,6 +27,7 @@ export const PencilLine = forwardRef(function PencilLine({ className = '', orien
             return undefined;
         let frame = 0;
         let disposed = false;
+        let lastPaint = '';
         const paint = () => {
             frame = 0;
             if (disposed)
@@ -35,18 +37,23 @@ export const PencilLine = forwardRef(function PencilLine({ className = '', orien
             if (!pencilLineHasDrawableSize(width, height, orientation))
                 return;
             const dpr = effectiveDpr(2);
-            const color = getComputedStyle(canvas).color;
+            const style = getComputedStyle(canvas);
+            const color = style.color;
+            const resolvedWeight = weight ?? readRenderToken(style, '--inkra-stroke-width', pencilRenderDefaults.strokeWidth, 0.3, 3);
+            const resolvedRoughness = roughness ?? readRenderToken(style, '--inkra-stroke-amplitude', pencilRenderDefaults.strokeRoughness, 0, maxStrokeRoughness);
             const numericSeed = seedToNumber(seed);
             const key = JSON.stringify([
-                PENCIL_RENDERER_VERSION, orientation, width, height, color, numericSeed, weight, roughness, dpr,
+                PENCIL_RENDERER_VERSION, orientation, width, height, color, numericSeed, resolvedWeight, resolvedRoughness, dpr,
             ]);
+            if (key === lastPaint && canvasIsUsable(canvas))
+                return;
             let image = lineCache.get(key);
             if (image && !canvasIsUsable(image)) {
                 lineCache.delete(key);
                 image = undefined;
             }
             if (!image) {
-                image = renderLine(width, height, color, numericSeed, weight, roughness, orientation, dpr);
+                image = renderLine(width, height, color, numericSeed, resolvedWeight, resolvedRoughness, orientation, dpr);
                 lineCache.set(key, image, canvasByteCost(image));
             }
             canvas.width = image.width;
@@ -55,6 +62,7 @@ export const PencilLine = forwardRef(function PencilLine({ className = '', orien
             if (!context || context.isContextLost?.())
                 return;
             context.drawImage(image, 0, 0);
+            lastPaint = key;
         };
         const schedule = () => {
             if (!frame)
@@ -62,21 +70,19 @@ export const PencilLine = forwardRef(function PencilLine({ className = '', orien
         };
         const resize = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(schedule);
         resize?.observe(canvas);
-        const appearance = new MutationObserver(schedule);
-        appearance.observe(document.documentElement, {
-            attributes: true,
-            subtree: true,
-            attributeFilter: ['data-theme', 'data-inkra-theme'],
-        });
         const colorScheme = window.matchMedia('(prefers-color-scheme: dark)');
+        const inheritedStyle = new MutationObserver(schedule);
+        for (let element = canvas; element; element = element.parentElement) {
+            inheritedStyle.observe(element, { attributes: true, attributeFilter: ['style', 'class', 'data-theme', 'data-inkra-theme'] });
+        }
         colorScheme.addEventListener('change', schedule);
-        const stopRecovery = observeCanvasRecovery(schedule);
+        const stopRecovery = observeCanvasRecovery(() => { lastPaint = ''; schedule(); });
         paint();
         return () => {
             disposed = true;
             stopRecovery();
             resize?.disconnect();
-            appearance.disconnect();
+            inheritedStyle.disconnect();
             colorScheme.removeEventListener('change', schedule);
             cancelAnimationFrame(frame);
         };