@inkra/react 0.1.0 → 0.2.0

package/dist/heatmap/index.js

@@ -0,0 +1,248 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { scaleLinear, scaleQuantize } from 'd3-scale';
+import { forwardRef, useEffect, useId, useMemo, useRef, useState, } from 'react';
+import { PencilSurface } from '../PencilSurface.js';
+import { PencilText } from '../PencilText.js';
+const defaultColors = ['#f0dda0', '#b6d09b', '#70b19c', '#43869a', '#365f82'];
+function classes(...values) {
+    return values.filter(Boolean).join(' ');
+}
+function keyPart(value) {
+    return JSON.stringify([typeof value, value]);
+}
+function cellKey(rowId, columnId) {
+    return JSON.stringify([typeof rowId, rowId, typeof columnId, columnId]);
+}
+function sameSelection(a, b) {
+    return a != null && b != null && a.rowId === b.rowId && a.columnId === b.columnId;
+}
+function axisLabel(item) {
+    if (item.ariaLabel)
+        return item.ariaLabel;
+    if (typeof item.label === 'string' || typeof item.label === 'number')
+        return String(item.label);
+    return String(item.id);
+}
+function isMissing(cell) {
+    return typeof cell.value !== 'number' || !Number.isFinite(cell.value);
+}
+function normalizeCssSize(value, fallback) {
+    return typeof value === 'number'
+        ? Number.isFinite(value) ? `${Math.max(1, value)}px` : fallback
+        : value || fallback;
+}
+function normalizeDomain(values, requested) {
+    let minimum;
+    let maximum;
+    if (requested && Number.isFinite(requested[0]) && Number.isFinite(requested[1])) {
+        minimum = Math.min(requested[0], requested[1]);
+        maximum = Math.max(requested[0], requested[1]);
+    }
+    else if (values.length > 0) {
+        minimum = values[0];
+        maximum = values[0];
+        for (let index = 1; index < values.length; index += 1) {
+            minimum = Math.min(minimum, values[index]);
+            maximum = Math.max(maximum, values[index]);
+        }
+    }
+    else {
+        return [0, 1];
+    }
+    if (minimum !== maximum)
+        return [minimum, maximum];
+    const padding = Math.abs(minimum) * 0.5 || 1;
+    return [minimum - padding, maximum + padding];
+}
+function paletteDomain(domain, count) {
+    const [minimum, maximum] = domain;
+    if (count <= 1)
+        return [minimum];
+    return Array.from({ length: count }, (_, index) => minimum + ((maximum - minimum) * index) / (count - 1));
+}
+function clampBinCount(value) {
+    if (value === undefined || !Number.isFinite(value))
+        return 5;
+    return Math.max(2, Math.min(9, Math.round(value ?? 5)));
+}
+function resolvePosition(selection, rows, columns) {
+    if (!selection)
+        return null;
+    const rowIndex = rows.findIndex(row => row.id === selection.rowId);
+    const columnIndex = columns.findIndex(column => column.id === selection.columnId);
+    return rowIndex < 0 || columnIndex < 0 ? null : { rowIndex, columnIndex };
+}
+function positionEquals(a, b) {
+    return a?.rowIndex === b?.rowIndex && a?.columnIndex === b?.columnIndex;
+}
+function defaultValueLabel(value) {
+    return String(value);
+}
+function paintStyle(color) {
+    return {
+        '--inkra-accent': color,
+        '--inkra-accent-soft': color,
+        '--inkra-accent-strong': color,
+    };
+}
+export const Heatmap = forwardRef(function Heatmap({ rows, columns, cells, label, description, scaleType = 'continuous', domain: requestedDomain, colorRange = defaultColors, binCount, showLegend = true, showValues = true, legendLabel = 'Intensity', missingLabel = '—', missingValueLabel = 'Missing', selectionMode = 'single', selectedCell, defaultSelectedCell = null, onSelectedCellChange, getValueLabel = defaultValueLabel, getCellAriaLabel, renderCell, renderDetails, cellSize = 56, rowLabelWidth = '8rem', rowHeaderLabel = 'Rows', emptyMessage = 'No heatmap data', className, style, ...props }, forwardedRef) {
+    const generatedId = useId();
+    const labelId = `inkra-heatmap-${generatedId}-label`;
+    const descriptionId = description == null ? undefined : `inkra-heatmap-${generatedId}-description`;
+    const detailsId = `inkra-heatmap-${generatedId}-details`;
+    const isControlled = selectedCell !== undefined;
+    const [internalSelection, setInternalSelection] = useState(defaultSelectedCell);
+    const resolvedSelection = isControlled ? selectedCell ?? null : internalSelection;
+    const initialPosition = resolvePosition(resolvedSelection, rows, columns) ?? (rows.length > 0 && columns.length > 0 ? { rowIndex: 0, columnIndex: 0 } : null);
+    const [activePosition, setActivePosition] = useState(initialPosition);
+    const [hoveredPosition, setHoveredPosition] = useState(null);
+    const [focusedPosition, setFocusedPosition] = useState(null);
+    const cellRefs = useRef(new Map());
+    const rowSignature = JSON.stringify(rows.map(row => [typeof row.id, row.id]));
+    const columnSignature = JSON.stringify(columns.map(column => [typeof column.id, column.id]));
+    const cellsByKey = useMemo(() => {
+        const map = new Map();
+        for (const cell of cells)
+            map.set(cellKey(cell.rowId, cell.columnId), cell);
+        return map;
+    }, [cells]);
+    const matrix = useMemo(() => rows.map(row => columns.map(column => (cellsByKey.get(cellKey(row.id, column.id)) ?? { rowId: row.id, columnId: column.id, value: null }))), [cellsByKey, columns, rows]);
+    const values = useMemo(() => matrix.flat().filter(cell => !isMissing(cell)).map(cell => cell.value), [matrix]);
+    const domain = useMemo(() => normalizeDomain(values, requestedDomain), [requestedDomain, values]);
+    const colors = colorRange.length >= 2 ? colorRange : defaultColors;
+    const continuousScale = useMemo(() => scaleLinear()
+        .domain(paletteDomain(domain, colors.length))
+        .range([...colors])
+        .clamp(true), [colors, domain]);
+    const resolvedBinCount = clampBinCount(binCount);
+    const quantizedColors = useMemo(() => Array.from({ length: resolvedBinCount }, (_, index) => continuousScale(domain[0] + ((domain[1] - domain[0]) * index) / Math.max(1, resolvedBinCount - 1))), [continuousScale, domain, resolvedBinCount]);
+    const quantizeScale = useMemo(() => scaleQuantize()
+        .domain(domain)
+        .range(quantizedColors), [domain, quantizedColors]);
+    const colorForValue = (value) => scaleType === 'quantize' ? quantizeScale(value) : continuousScale(value);
+    const selectedPosition = resolvePosition(resolvedSelection, rows, columns);
+    const inspectedPosition = focusedPosition ?? hoveredPosition ?? selectedPosition ?? activePosition;
+    const inspectedCell = inspectedPosition ? matrix[inspectedPosition.rowIndex]?.[inspectedPosition.columnIndex] : undefined;
+    useEffect(() => {
+        const next = resolvePosition(resolvedSelection, rows, columns);
+        if (next)
+            setActivePosition(current => positionEquals(current, next) ? current : next);
+    }, [columnSignature, resolvedSelection?.columnId, resolvedSelection?.rowId, rowSignature]);
+    useEffect(() => {
+        if (rows.length === 0 || columns.length === 0) {
+            setActivePosition(null);
+            return;
+        }
+        setActivePosition(current => current && current.rowIndex < rows.length && current.columnIndex < columns.length
+            ? current
+            : { rowIndex: 0, columnIndex: 0 });
+    }, [columns.length, rows.length]);
+    const focusPosition = (position) => {
+        setActivePosition(position);
+        const cell = matrix[position.rowIndex]?.[position.columnIndex];
+        if (!cell)
+            return;
+        cellRefs.current.get(cellKey(cell.rowId, cell.columnId))?.focus();
+    };
+    const select = (cell) => {
+        if (selectionMode === 'none' || cell.disabled)
+            return;
+        const next = { rowId: cell.rowId, columnId: cell.columnId };
+        if (!isControlled)
+            setInternalSelection(next);
+        onSelectedCellChange?.(next, cell);
+    };
+    const onCellKeyDown = (event, position, cell) => {
+        let next = position;
+        if (event.key === 'ArrowLeft')
+            next = { ...position, columnIndex: Math.max(0, position.columnIndex - 1) };
+        else if (event.key === 'ArrowRight')
+            next = { ...position, columnIndex: Math.min(columns.length - 1, position.columnIndex + 1) };
+        else if (event.key === 'ArrowUp')
+            next = { ...position, rowIndex: Math.max(0, position.rowIndex - 1) };
+        else if (event.key === 'ArrowDown')
+            next = { ...position, rowIndex: Math.min(rows.length - 1, position.rowIndex + 1) };
+        else if (event.key === 'Home')
+            next = event.ctrlKey ? { rowIndex: 0, columnIndex: 0 } : { ...position, columnIndex: 0 };
+        else if (event.key === 'End')
+            next = event.ctrlKey
+                ? { rowIndex: rows.length - 1, columnIndex: columns.length - 1 }
+                : { ...position, columnIndex: columns.length - 1 };
+        else if (event.key === 'Enter' || event.key === ' ') {
+            event.preventDefault();
+            select(cell);
+            return;
+        }
+        else
+            return;
+        event.preventDefault();
+        focusPosition(next);
+    };
+    const rootStyle = {
+        ...style,
+        '--inkra-heatmap-cell-size': normalizeCssSize(cellSize, '56px'),
+        '--inkra-heatmap-row-label-width': normalizeCssSize(rowLabelWidth, '8rem'),
+        '--inkra-heatmap-column-count': columns.length,
+    };
+    const renderCellContent = (cell, context) => {
+        if (renderCell)
+            return renderCell(cell, context);
+        if (context.missing)
+            return missingLabel;
+        return showValues ? getValueLabel(cell.value) : _jsx("span", { "aria-hidden": "true", className: "inkra-heatmap__value-mark" });
+    };
+    const detailsFor = (cell, position) => {
+        const row = rows[position.rowIndex];
+        const column = columns[position.columnIndex];
+        const missing = isMissing(cell);
+        const valueLabel = missing ? missingValueLabel : getValueLabel(cell.value);
+        const context = {
+            row,
+            column,
+            color: missing ? null : colorForValue(cell.value),
+            missing,
+            selected: sameSelection(resolvedSelection, cell),
+            active: positionEquals(inspectedPosition, position),
+            valueLabel,
+        };
+        return { context, valueLabel };
+    };
+    return (_jsxs("div", { ...props, className: classes('inkra-heatmap', className), ref: forwardedRef, style: rootStyle, children: [_jsxs("div", { className: "inkra-heatmap__heading", children: [_jsx("div", { className: "inkra-heatmap__label", id: labelId, children: typeof label === 'string' ? _jsx(PencilText, { seed: `${generatedId}-label`, children: label }) : label }), description == null ? null : _jsx("div", { className: "inkra-heatmap__description", id: descriptionId, children: description })] }), rows.length === 0 || columns.length === 0 ? (_jsx("div", { className: "inkra-heatmap__empty", children: emptyMessage })) : (_jsx("div", { className: "inkra-heatmap__viewport", children: _jsxs("div", { "aria-describedby": classes(descriptionId, detailsId), "aria-labelledby": labelId, "aria-rowcount": rows.length + 1, "aria-colcount": columns.length + 1, className: "inkra-heatmap__grid", role: "grid", children: [_jsxs("div", { "aria-rowindex": 1, className: "inkra-heatmap__row inkra-heatmap__row--header", role: "row", children: [_jsx("span", { "aria-colindex": 1, "aria-label": rowHeaderLabel, className: "inkra-heatmap__corner", role: "columnheader" }), columns.map((column, columnIndex) => (_jsx("span", { "aria-colindex": columnIndex + 2, className: "inkra-heatmap__column-label", role: "columnheader", children: column.label }, keyPart(column.id))))] }), matrix.map((rowCells, rowIndex) => {
+                            const row = rows[rowIndex];
+                            return (_jsxs("div", { "aria-rowindex": rowIndex + 2, className: "inkra-heatmap__row", role: "row", children: [_jsx("span", { "aria-colindex": 1, className: "inkra-heatmap__row-label", role: "rowheader", children: row.label }), rowCells.map((cell, columnIndex) => {
+                                        const position = { rowIndex, columnIndex };
+                                        const column = columns[columnIndex];
+                                        const missing = isMissing(cell);
+                                        const selected = sameSelection(resolvedSelection, cell);
+                                        const active = positionEquals(inspectedPosition, position);
+                                        const color = missing ? null : colorForValue(cell.value);
+                                        const valueLabel = missing ? missingValueLabel : getValueLabel(cell.value);
+                                        const context = { row, column, color, missing, selected, active, valueLabel };
+                                        const ariaLabel = getCellAriaLabel?.(cell, context)
+                                            ?? `${axisLabel(row)}, ${axisLabel(column)}: ${valueLabel}`;
+                                        const resolvedPaintStyle = color ? paintStyle(color) : undefined;
+                                        return (_jsxs("button", { "aria-colindex": columnIndex + 2, "aria-disabled": cell.disabled || undefined, "aria-label": ariaLabel, "aria-selected": selectionMode === 'single' ? selected : undefined, className: "inkra-heatmap__cell", "data-active": active || undefined, "data-disabled": cell.disabled || undefined, "data-missing": missing || undefined, "data-selected": selected || undefined, "data-value": missing ? undefined : cell.value, onBlur: () => setFocusedPosition(current => positionEquals(current, position) ? null : current), onClick: () => select(cell), onFocus: () => {
+                                                setActivePosition(position);
+                                                setFocusedPosition(position);
+                                            }, onKeyDown: event => onCellKeyDown(event, position, cell), onMouseEnter: () => setHoveredPosition(position), onMouseLeave: () => setHoveredPosition(current => positionEquals(current, position) ? null : current), ref: node => {
+                                                const key = cellKey(cell.rowId, cell.columnId);
+                                                if (node)
+                                                    cellRefs.current.set(key, node);
+                                                else
+                                                    cellRefs.current.delete(key);
+                                            }, role: "gridcell", tabIndex: positionEquals(activePosition, position) ? 0 : -1, type: "button", children: [_jsx(PencilSurface, { "aria-hidden": "true", as: "span", className: "inkra-heatmap__cell-paint", radius: 6, seed: `heatmap-${cellKey(cell.rowId, cell.columnId)}-paint`, style: resolvedPaintStyle, variant: missing ? 'outline' : 'action' }), selected ? _jsx(PencilSurface, { "aria-hidden": "true", as: "span", className: "inkra-heatmap__cell-selection", radius: 6, seed: `heatmap-${cellKey(cell.rowId, cell.columnId)}-selection`, variant: "selection" }) : null, _jsx("span", { className: "inkra-heatmap__cell-content", children: renderCellContent(cell, context) })] }, cellKey(cell.rowId, cell.columnId)));
+                                    })] }, keyPart(row.id)));
+                        })] }) })), showLegend && rows.length > 0 && columns.length > 0 ? (_jsxs("div", { "aria-label": typeof legendLabel === 'string' ? legendLabel : undefined, className: "inkra-heatmap__legend", role: "group", children: [_jsx("div", { className: "inkra-heatmap__legend-label", children: legendLabel }), scaleType === 'continuous' ? (_jsxs("div", { className: "inkra-heatmap__legend-continuous", children: [_jsx("div", { "aria-hidden": "true", className: "inkra-heatmap__legend-strip", children: Array.from({ length: 7 }, (_, index) => {
+                                    const value = domain[0] + ((domain[1] - domain[0]) * index) / 6;
+                                    const color = continuousScale(value);
+                                    return _jsx(PencilSurface, { as: "span", className: "inkra-heatmap__legend-swatch", seed: `heatmap-legend-${index}`, style: paintStyle(color), variant: "action" }, index);
+                                }) }), _jsxs("div", { className: "inkra-heatmap__legend-values", children: [_jsx("span", { children: getValueLabel(domain[0]) }), _jsx("span", { children: getValueLabel((domain[0] + domain[1]) / 2) }), _jsx("span", { children: getValueLabel(domain[1]) })] })] })) : (_jsx("div", { className: "inkra-heatmap__legend-bins", role: "list", children: quantizedColors.map((color, index) => {
+                            const [from, to] = quantizeScale.invertExtent(color);
+                            return _jsxs("div", { className: "inkra-heatmap__legend-bin", role: "listitem", children: [_jsx(PencilSurface, { "aria-hidden": "true", as: "span", className: "inkra-heatmap__legend-swatch", seed: `heatmap-bin-${index}`, style: paintStyle(color), variant: "action" }), _jsxs("span", { children: [getValueLabel(from), "\u2013", getValueLabel(to)] })] }, `${color}-${index}`);
+                        }) })), _jsxs("div", { className: "inkra-heatmap__legend-missing", children: [_jsx(PencilSurface, { "aria-hidden": "true", as: "span", className: "inkra-heatmap__legend-swatch", seed: "heatmap-missing", variant: "outline" }), _jsx("span", { children: missingValueLabel })] })] })) : null, _jsx("div", { "aria-live": "polite", className: "inkra-heatmap__details", id: detailsId, children: inspectedCell && inspectedPosition ? (() => {
+                    const { context, valueLabel } = detailsFor(inspectedCell, inspectedPosition);
+                    return renderDetails
+                        ? renderDetails(inspectedCell, context)
+                        : _jsxs(_Fragment, { children: [_jsxs("strong", { children: [axisLabel(context.row), " \u00B7 ", axisLabel(context.column)] }), _jsx("span", { children: valueLabel })] });
+                })() : null })] }));
+});

package/dist/hotkey/index.d.ts

@@ -0,0 +1,37 @@
+import type { HTMLAttributes, InputHTMLAttributes, ReactNode } from 'react';
+import type { FieldControlSize, FieldControlStateProps } from '../form/types.js';
+import { detectHotkeyPlatform, formatHotkey, getHotkeyTokens, hotkeyFromKeyboardEvent, hotkeySignature, normalizeHotkey } from './model.js';
+import type { HotkeyModifier, HotkeyPlatform, HotkeyValue, ResolvedHotkeyPlatform } from './model.js';
+export type HotkeyValidationResult = boolean | string | null | undefined;
+export type HotkeyInputChangeReason = 'record' | 'clear';
+export interface HotkeyInputChangeDetails {
+    reason: HotkeyInputChangeReason;
+    conflict?: string;
+}
+export interface HotkeyProps extends Omit<HTMLAttributes<HTMLElement>, 'children'> {
+    value: HotkeyValue;
+    platform?: HotkeyPlatform;
+    separator?: ReactNode;
+    size?: FieldControlSize;
+}
+export interface HotkeyInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'children' | 'defaultValue' | 'onChange' | 'readOnly' | 'size' | 'value'>, FieldControlStateProps {
+    value?: HotkeyValue | null;
+    defaultValue?: HotkeyValue | null;
+    onValueChange?: (value: HotkeyValue | null, details: HotkeyInputChangeDetails) => void;
+    onCancel?: () => void;
+    validateHotkey?: (value: HotkeyValue) => HotkeyValidationResult;
+    onConflict?: (value: HotkeyValue, message: string) => void;
+    conflict?: boolean | string;
+    conflictMessage?: string;
+    platform?: HotkeyPlatform;
+    placeholder?: string;
+    clearable?: boolean;
+    clearButtonLabel?: string;
+    blurOnCapture?: boolean;
+    readOnly?: boolean;
+    classNames?: Partial<Record<'root' | 'control' | 'input' | 'value' | 'message', string>>;
+}
+export declare const Hotkey: import("react").ForwardRefExoticComponent<HotkeyProps & import("react").RefAttributes<HTMLElement>>;
+export declare const HotkeyInput: import("react").ForwardRefExoticComponent<HotkeyInputProps & import("react").RefAttributes<HTMLInputElement>>;
+export type { FieldControlSize, HotkeyModifier, HotkeyPlatform, HotkeyValue, ResolvedHotkeyPlatform, };
+export { detectHotkeyPlatform, formatHotkey, getHotkeyTokens, hotkeyFromKeyboardEvent, hotkeySignature, normalizeHotkey, };

package/dist/hotkey/index.js

@@ -0,0 +1,130 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useEffect, useId, useImperativeHandle, useRef, useState, } from 'react';
+import { PencilIcon } from '../PencilIcon.js';
+import { PencilSurface } from '../PencilSurface.js';
+import { PencilText } from '../PencilText.js';
+import { useResolvedControlProps } from '../form/controlProps.js';
+import { detectHotkeyPlatform, formatHotkey, getHotkeyTokens, hotkeyFromKeyboardEvent, hotkeySignature, isHotkeyClear, isHotkeyEscape, normalizeHotkey, } from './model.js';
+const clearPaths = [{ d: 'M18 6 6 18' }, { d: 'm6 6 12 12' }];
+const classes = (...values) => values.filter(Boolean).join(' ');
+function browserPlatform() {
+    if (typeof navigator === 'undefined')
+        return '';
+    const userAgentData = navigator.userAgentData;
+    return userAgentData?.platform ?? navigator.platform ?? navigator.userAgent;
+}
+function useHotkeyPlatform(platform) {
+    const explicit = platform === 'auto' ? null : platform;
+    const [detected, setDetected] = useState('windows');
+    useEffect(() => {
+        if (!explicit)
+            setDetected(detectHotkeyPlatform(browserPlatform()));
+    }, [explicit]);
+    return explicit ?? detected;
+}
+function conflictText(result, fallback) {
+    if (typeof result === 'string')
+        return result || undefined;
+    return result ? fallback : undefined;
+}
+export const Hotkey = forwardRef(function Hotkey({ 'aria-label': ariaLabel, className, platform = 'auto', separator, size = 'md', value, ...props }, ref) {
+    const resolvedPlatform = useHotkeyPlatform(platform);
+    const normalized = normalizeHotkey(value);
+    const tokens = getHotkeyTokens(normalized, resolvedPlatform);
+    const label = formatHotkey(normalized, resolvedPlatform);
+    return (_jsx("kbd", { ...props, "aria-label": ariaLabel ?? label, className: classes('inkra-hotkey', className), "data-platform": resolvedPlatform, "data-size": size, ref: ref, children: tokens.map((token, index) => (_jsxs("span", { className: "inkra-hotkey__part", children: [index > 0 && resolvedPlatform !== 'mac' ? (_jsx("span", { "aria-hidden": "true", className: "inkra-hotkey__separator", children: separator ?? '+' })) : null, _jsx(PencilSurface, { "aria-hidden": "true", as: "span", className: "inkra-hotkey__key", radius: 4, seed: `${hotkeySignature(normalized)}-${resolvedPlatform}-${index}`, variant: "quiet", children: _jsx(PencilText, { seed: `${hotkeySignature(normalized)}-${resolvedPlatform}-${index}-label`, children: token }) })] }, `${token}-${index}`))) }));
+});
+export const HotkeyInput = forwardRef(function HotkeyInput({ 'aria-describedby': ariaDescribedBy, 'aria-errormessage': ariaErrorMessage, 'aria-invalid': ariaInvalid, 'aria-label': ariaLabel, blurOnCapture = true, className, classNames = {}, clearable = true, clearButtonLabel = 'Clear shortcut', conflict, conflictMessage = 'Shortcut already assigned', defaultValue = null, disabled, id, invalid = false, onBlur, onCancel, onCompositionEnd, onCompositionStart, onConflict, onFocus, onKeyDown, onValueChange, placeholder = 'Press shortcut', platform = 'auto', readOnly, required, seed, size = 'md', validateHotkey, value, ...props }, forwardedRef) {
+    const generatedId = useId();
+    const inputRef = useRef(null);
+    const composingRef = useRef(false);
+    const isControlled = value !== undefined;
+    const [uncontrolledValue, setUncontrolledValue] = useState(() => defaultValue ? normalizeHotkey(defaultValue) : null);
+    const [focused, setFocused] = useState(false);
+    const [localConflict, setLocalConflict] = useState(null);
+    const currentValue = isControlled ? (value ? normalizeHotkey(value) : null) : uncontrolledValue;
+    const resolvedPlatform = useHotkeyPlatform(platform);
+    const externalConflict = conflictText(conflict, conflictMessage);
+    const currentSignature = hotkeySignature(currentValue);
+    const validationMessage = externalConflict ?? (localConflict?.signature === currentSignature ? localConflict.message : undefined);
+    const messageId = validationMessage ? `${id ?? generatedId}-hotkey-conflict` : undefined;
+    const state = useResolvedControlProps({
+        id,
+        required,
+        disabled,
+        readOnly,
+        invalid: invalid || Boolean(validationMessage),
+        'aria-describedby': [ariaDescribedBy, messageId].filter(Boolean).join(' ') || undefined,
+        'aria-errormessage': validationMessage ? messageId : ariaErrorMessage,
+        'aria-invalid': ariaInvalid,
+    });
+    const resolvedSeed = seed ?? `inkra-hotkey-input-${state.id ?? generatedId}`;
+    const displayValue = currentValue ? formatHotkey(currentValue, resolvedPlatform) : '';
+    useImperativeHandle(forwardedRef, () => inputRef.current);
+    const updateValue = (nextValue, details) => {
+        if (!isControlled)
+            setUncontrolledValue(nextValue);
+        onValueChange?.(nextValue, details);
+    };
+    const clear = () => {
+        if (state.disabled || state.readOnly || !currentValue)
+            return;
+        setLocalConflict(null);
+        updateValue(null, { reason: 'clear' });
+        inputRef.current?.focus({ preventScroll: true });
+    };
+    const handleKeyDown = (event) => {
+        onKeyDown?.(event);
+        if (event.defaultPrevented || state.disabled || state.readOnly)
+            return;
+        const nativeEvent = event.nativeEvent;
+        const eventLike = {
+            key: event.key,
+            code: event.code,
+            ctrlKey: event.ctrlKey,
+            altKey: event.altKey,
+            shiftKey: event.shiftKey,
+            metaKey: event.metaKey,
+            isComposing: composingRef.current || nativeEvent.isComposing,
+            keyCode: nativeEvent.keyCode,
+        };
+        if (isHotkeyEscape(eventLike)) {
+            onCancel?.();
+            event.currentTarget.blur();
+            return;
+        }
+        if (isHotkeyClear(eventLike)) {
+            clear();
+            return;
+        }
+        if (event.key === 'Tab')
+            return;
+        const nextValue = hotkeyFromKeyboardEvent(eventLike);
+        if (!nextValue)
+            return;
+        const result = validateHotkey?.(nextValue);
+        const message = conflictText(result, conflictMessage);
+        setLocalConflict(message ? { signature: hotkeySignature(nextValue), message } : null);
+        if (message)
+            onConflict?.(nextValue, message);
+        updateValue(nextValue, { reason: 'record', ...(message ? { conflict: message } : {}) });
+        if (blurOnCapture)
+            event.currentTarget.blur();
+    };
+    const handleFocus = (event) => {
+        setFocused(true);
+        onFocus?.(event);
+    };
+    const handleBlur = (event) => {
+        setFocused(false);
+        onBlur?.(event);
+    };
+    return (_jsxs("span", { className: classes('inkra-hotkey-input', classNames.root), "data-disabled": state.disabled || undefined, "data-focus-within": focused || undefined, "data-invalid": state.invalid || undefined, "data-readonly": state.readOnly || undefined, "data-size": size, children: [_jsxs(PencilSurface, { as: "span", className: classes('inkra-hotkey-input__control', classNames.control), clipContent: true, seed: resolvedSeed, variant: state.invalid ? 'danger' : 'outline', children: [_jsx("input", { ...props, "aria-describedby": state.describedBy, "aria-errormessage": state.errorMessage, "aria-invalid": state.ariaInvalid, "aria-label": ariaLabel, autoComplete: "off", className: classes('inkra-hotkey-input__native', className, classNames.input), disabled: state.disabled, id: state.id, inputMode: "none", onBlur: handleBlur, onChange: () => { }, onCompositionEnd: event => {
+                            composingRef.current = false;
+                            onCompositionEnd?.(event);
+                        }, onCompositionStart: event => {
+                            composingRef.current = true;
+                            onCompositionStart?.(event);
+                        }, onFocus: handleFocus, onKeyDown: handleKeyDown, readOnly: state.readOnly, ref: inputRef, required: state.required, spellCheck: false, value: displayValue }), _jsx("span", { "aria-hidden": "true", className: classes('inkra-hotkey-input__value', classNames.value), children: currentValue ? _jsx(Hotkey, { value: currentValue, platform: resolvedPlatform, size: size }) : _jsx(PencilText, { className: "inkra-hotkey-input__placeholder", seed: `${resolvedSeed}-placeholder`, children: placeholder }) }), clearable && currentValue ? (_jsx("button", { "aria-label": clearButtonLabel, className: "inkra-hotkey-input__clear", disabled: state.disabled || state.readOnly, onClick: clear, onPointerDown: event => event.preventDefault(), title: clearButtonLabel, type: "button", children: _jsx(PencilIcon, { paths: clearPaths, seed: `${resolvedSeed}-clear`, size: size === 'sm' ? 18 : size === 'lg' ? 26 : 22, sourceSize: 24 }) })) : null] }), validationMessage ? (_jsx(PencilText, { as: "span", className: classes('inkra-hotkey-input__message', classNames.message), id: messageId, role: "alert", seed: `${resolvedSeed}-message`, children: validationMessage })) : null] }));
+});
+export { detectHotkeyPlatform, formatHotkey, getHotkeyTokens, hotkeyFromKeyboardEvent, hotkeySignature, normalizeHotkey, };

package/dist/hotkey/model.d.ts

@@ -0,0 +1,27 @@
+export type HotkeyPlatform = 'auto' | 'mac' | 'windows';
+export type ResolvedHotkeyPlatform = Exclude<HotkeyPlatform, 'auto'>;
+export type HotkeyModifier = 'control' | 'alt' | 'shift' | 'meta';
+export interface HotkeyValue {
+    key: string;
+    code?: string;
+    modifiers?: readonly HotkeyModifier[];
+}
+export interface HotkeyKeyboardEventLike {
+    key: string;
+    code?: string;
+    ctrlKey?: boolean;
+    altKey?: boolean;
+    shiftKey?: boolean;
+    metaKey?: boolean;
+    isComposing?: boolean;
+    keyCode?: number;
+}
+export declare function detectHotkeyPlatform(platform?: string): ResolvedHotkeyPlatform;
+export declare function normalizeHotkey(value: HotkeyValue): HotkeyValue;
+export declare function normalizeHotkeyKey(key: string): string;
+export declare function hotkeyFromKeyboardEvent(event: HotkeyKeyboardEventLike): HotkeyValue | null;
+export declare function hotkeySignature(value: HotkeyValue | null | undefined): string;
+export declare function getHotkeyTokens(value: HotkeyValue, platform: ResolvedHotkeyPlatform): string[];
+export declare function formatHotkey(value: HotkeyValue, platform: ResolvedHotkeyPlatform): string;
+export declare function isHotkeyEscape(event: HotkeyKeyboardEventLike): boolean;
+export declare function isHotkeyClear(event: HotkeyKeyboardEventLike): boolean;

package/dist/hotkey/model.js

@@ -0,0 +1,97 @@
+const modifierKeys = new Set([
+    'Alt', 'AltGraph', 'Control', 'Fn', 'FnLock', 'Hyper', 'Meta', 'OS', 'Shift', 'Super', 'Symbol', 'SymbolLock',
+]);
+const ignoredKeys = new Set(['Dead', 'Process', 'Unidentified']);
+const modifierOrder = ['control', 'alt', 'shift', 'meta'];
+const keyLabels = {
+    ' ': 'Space',
+    ArrowDown: '↓',
+    ArrowLeft: '←',
+    ArrowRight: '→',
+    ArrowUp: '↑',
+    Backspace: 'Backspace',
+    CapsLock: 'Caps Lock',
+    Delete: 'Delete',
+    End: 'End',
+    Enter: 'Enter',
+    Escape: 'Esc',
+    Home: 'Home',
+    PageDown: 'Page Down',
+    PageUp: 'Page Up',
+    Tab: 'Tab',
+};
+const macKeyLabels = {
+    Backspace: '⌫',
+    CapsLock: '⇪',
+    Delete: '⌦',
+    End: '↘',
+    Enter: '↩',
+    Escape: 'Esc',
+    Home: '↖',
+    PageDown: '⇟',
+    PageUp: '⇞',
+    Tab: '⇥',
+};
+const modifierLabels = {
+    mac: { control: '⌃', alt: '⌥', shift: '⇧', meta: '⌘' },
+    windows: { control: 'Ctrl', alt: 'Alt', shift: 'Shift', meta: 'Win' },
+};
+export function detectHotkeyPlatform(platform) {
+    return /mac|iphone|ipad|ipod/i.test(platform ?? '') ? 'mac' : 'windows';
+}
+export function normalizeHotkey(value) {
+    const modifiers = modifierOrder.filter(modifier => value.modifiers?.includes(modifier));
+    return {
+        key: normalizeHotkeyKey(value.key),
+        ...(value.code ? { code: value.code } : {}),
+        ...(modifiers.length ? { modifiers } : {}),
+    };
+}
+export function normalizeHotkeyKey(key) {
+    if (key === 'Spacebar')
+        return ' ';
+    if (key === 'Esc')
+        return 'Escape';
+    if (key.length === 1 && /[a-z]/i.test(key))
+        return key.toUpperCase();
+    return key;
+}
+export function hotkeyFromKeyboardEvent(event) {
+    if (event.isComposing || event.keyCode === 229 || modifierKeys.has(event.key) || ignoredKeys.has(event.key))
+        return null;
+    const modifiers = modifierOrder.filter(modifier => {
+        if (modifier === 'control')
+            return Boolean(event.ctrlKey);
+        if (modifier === 'alt')
+            return Boolean(event.altKey);
+        if (modifier === 'shift')
+            return Boolean(event.shiftKey);
+        return Boolean(event.metaKey);
+    });
+    return normalizeHotkey({ key: event.key, code: event.code, modifiers });
+}
+export function hotkeySignature(value) {
+    if (!value)
+        return '';
+    const normalized = normalizeHotkey(value);
+    return `${normalized.modifiers?.join('+') ?? ''}|${normalized.code ?? ''}|${normalized.key}`;
+}
+export function getHotkeyTokens(value, platform) {
+    const normalized = normalizeHotkey(value);
+    const modifiers = normalized.modifiers?.map(modifier => modifierLabels[platform][modifier]) ?? [];
+    const key = (platform === 'mac' ? macKeyLabels[normalized.key] : undefined)
+        ?? keyLabels[normalized.key]
+        ?? normalized.key;
+    return [...modifiers, key];
+}
+export function formatHotkey(value, platform) {
+    const tokens = getHotkeyTokens(value, platform);
+    return platform === 'mac' ? tokens.join('') : tokens.join(' + ');
+}
+export function isHotkeyEscape(event) {
+    return !event.isComposing && event.keyCode !== 229 && normalizeHotkeyKey(event.key) === 'Escape';
+}
+export function isHotkeyClear(event) {
+    return !event.isComposing && event.keyCode !== 229 && !event.ctrlKey && !event.altKey && !event.shiftKey && !event.metaKey
+        && (event.key === 'Backspace' || event.key === 'Delete');
+}

package/dist/hover-card/index.d.ts

@@ -0,0 +1,33 @@
+import type { PopoverCloseProps, PopoverContentProps, PopoverDescriptionProps, PopoverRootProps, PopoverTitleProps, PopoverTriggerProps } from '../overlay/index.js';
+export interface HoverCardRootProps extends Omit<PopoverRootProps, 'defaultOpen' | 'modal' | 'onOpenChange' | 'open'> {
+    /** Delay in milliseconds before hover or focus opens the card. */
+    openDelay?: number;
+    /** Delay in milliseconds before pointer or focus departure closes the card. */
+    closeDelay?: number;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    open?: boolean;
+}
+export declare function HoverCardRoot({ children, closeDelay, defaultOpen, onOpenChange, open, openDelay, ...props }: HoverCardRootProps): import("react").JSX.Element;
+export type HoverCardTriggerProps = PopoverTriggerProps;
+export declare const HoverCardTrigger: import("react").ForwardRefExoticComponent<import("@radix-ui/react-popover").PopoverTriggerProps & import("react").RefAttributes<HTMLButtonElement>>;
+export type HoverCardFocusOnOpen = 'always' | 'focus-and-press' | 'never' | 'press';
+export interface HoverCardContentProps extends PopoverContentProps {
+    /** Controls which activation reasons may move focus into the card. */
+    focusOnOpen?: HoverCardFocusOnOpen;
+}
+export declare const HoverCardContent: import("react").ForwardRefExoticComponent<HoverCardContentProps & import("react").RefAttributes<HTMLDivElement>>;
+export type HoverCardTitleProps = PopoverTitleProps;
+export declare const HoverCardTitle: import("react").ForwardRefExoticComponent<PopoverTitleProps & import("react").RefAttributes<HTMLHeadingElement>>;
+export type HoverCardDescriptionProps = PopoverDescriptionProps;
+export declare const HoverCardDescription: import("react").ForwardRefExoticComponent<PopoverDescriptionProps & import("react").RefAttributes<HTMLParagraphElement>>;
+export type HoverCardCloseProps = PopoverCloseProps;
+export declare const HoverCardClose: import("react").ForwardRefExoticComponent<Omit<import("@radix-ui/react-popover").PopoverCloseProps & import("react").RefAttributes<HTMLButtonElement>, "ref"> & import("react").RefAttributes<HTMLButtonElement>>;
+export declare const HoverCard: Readonly<{
+    Root: typeof HoverCardRoot;
+    Trigger: import("react").ForwardRefExoticComponent<import("@radix-ui/react-popover").PopoverTriggerProps & import("react").RefAttributes<HTMLButtonElement>>;
+    Content: import("react").ForwardRefExoticComponent<HoverCardContentProps & import("react").RefAttributes<HTMLDivElement>>;
+    Title: import("react").ForwardRefExoticComponent<PopoverTitleProps & import("react").RefAttributes<HTMLHeadingElement>>;
+    Description: import("react").ForwardRefExoticComponent<PopoverDescriptionProps & import("react").RefAttributes<HTMLParagraphElement>>;
+    Close: import("react").ForwardRefExoticComponent<Omit<import("@radix-ui/react-popover").PopoverCloseProps & import("react").RefAttributes<HTMLButtonElement>, "ref"> & import("react").RefAttributes<HTMLButtonElement>>;
+}>;