@inkra/react 0.0.0-stage → 0.2.0

package/dist/form/context.d.ts

@@ -0,0 +1,12 @@
+export interface FieldContextValue {
+    controlId: string;
+    descriptionId?: string;
+    errorId?: string;
+    required: boolean;
+    invalid: boolean;
+    disabled: boolean;
+    readOnly: boolean;
+}
+export declare const FieldContext: import("react").Context<FieldContextValue | null>;
+export declare function useFieldContext(): FieldContextValue | null;
+export declare function mergeAriaIds(...values: Array<string | undefined>): string | undefined;

package/dist/form/context.js

@@ -0,0 +1,10 @@
+import { createContext, useContext } from 'react';
+export const FieldContext = createContext(null);
+export function useFieldContext() {
+    return useContext(FieldContext);
+}
+export function mergeAriaIds(...values) {
+    const ids = values.flatMap((value) => value?.split(/\s+/).filter(Boolean) ?? []);
+    const merged = Array.from(new Set(ids));
+    return merged.length ? merged.join(' ') : undefined;
+}

package/dist/form/controlProps.d.ts

@@ -0,0 +1,23 @@
+import type { AriaAttributes } from 'react';
+interface NativeControlState {
+    id?: string;
+    required?: boolean;
+    disabled?: boolean;
+    readOnly?: boolean;
+    'aria-describedby'?: string;
+    'aria-errormessage'?: string;
+    'aria-invalid'?: AriaAttributes['aria-invalid'];
+}
+export declare function useResolvedControlProps(props: NativeControlState & {
+    invalid?: boolean;
+}): {
+    id: string | undefined;
+    required: boolean;
+    disabled: boolean;
+    readOnly: boolean;
+    invalid: boolean;
+    describedBy: string | undefined;
+    errorMessage: string | undefined;
+    ariaInvalid: boolean | "true" | "false" | "grammar" | "spelling" | undefined;
+};
+export {};

package/dist/form/controlProps.js

@@ -0,0 +1,20 @@
+import { mergeAriaIds, useFieldContext } from './context.js';
+export function useResolvedControlProps(props) {
+    const field = useFieldContext();
+    const resolvedInvalid = Boolean(props.invalid
+        || field?.invalid
+        || props['aria-invalid'] === true
+        || props['aria-invalid'] === 'true');
+    const describedBy = mergeAriaIds(props['aria-describedby'], field?.descriptionId, field?.errorId);
+    const errorMessage = mergeAriaIds(props['aria-errormessage'], resolvedInvalid ? field?.errorId : undefined);
+    return {
+        id: field?.controlId ?? props.id,
+        required: Boolean(props.required || field?.required),
+        disabled: Boolean(props.disabled || field?.disabled),
+        readOnly: Boolean(props.readOnly || field?.readOnly),
+        invalid: resolvedInvalid,
+        describedBy,
+        errorMessage,
+        ariaInvalid: resolvedInvalid ? true : props['aria-invalid'],
+    };
+}

package/dist/form/index.d.ts

@@ -0,0 +1,7 @@
+export { Field } from './Field.js';
+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 { FieldControlSize, FieldControlStateProps } from './types.js';

package/dist/form/index.js

@@ -0,0 +1,3 @@
+export { Field } from './Field.js';
+export { Input } from './Input.js';
+export { Textarea } from './Textarea.js';

package/dist/form/types.d.ts

@@ -0,0 +1,6 @@
+export type FieldControlSize = 'sm' | 'md' | 'lg';
+export interface FieldControlStateProps {
+    invalid?: boolean;
+    size?: FieldControlSize;
+    seed?: string | number;
+}

package/dist/form/types.js

@@ -0,0 +1 @@
+export {};

package/dist/heatmap/index.d.ts

@@ -0,0 +1,59 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+export type HeatmapKey = string | number;
+export type HeatmapScaleType = 'continuous' | 'quantize';
+export interface HeatmapAxisItem {
+    id: HeatmapKey;
+    label: ReactNode;
+    ariaLabel?: string;
+}
+export interface HeatmapCell {
+    rowId: HeatmapKey;
+    columnId: HeatmapKey;
+    value?: number | null;
+    disabled?: boolean;
+    data?: unknown;
+}
+export interface HeatmapSelection {
+    rowId: HeatmapKey;
+    columnId: HeatmapKey;
+}
+export interface HeatmapCellContext {
+    row: HeatmapAxisItem;
+    column: HeatmapAxisItem;
+    color: string | null;
+    missing: boolean;
+    selected: boolean;
+    active: boolean;
+}
+export interface HeatmapDetailsContext extends HeatmapCellContext {
+    valueLabel: string;
+}
+export interface HeatmapProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'onChange'> {
+    rows: readonly HeatmapAxisItem[];
+    columns: readonly HeatmapAxisItem[];
+    cells: readonly HeatmapCell[];
+    label: ReactNode;
+    description?: ReactNode;
+    scaleType?: HeatmapScaleType;
+    domain?: readonly [number, number];
+    colorRange?: readonly string[];
+    binCount?: number;
+    showLegend?: boolean;
+    showValues?: boolean;
+    legendLabel?: ReactNode;
+    missingLabel?: ReactNode;
+    missingValueLabel?: string;
+    selectionMode?: 'single' | 'none';
+    selectedCell?: HeatmapSelection | null;
+    defaultSelectedCell?: HeatmapSelection | null;
+    onSelectedCellChange?: (selection: HeatmapSelection | null, cell: HeatmapCell | null) => void;
+    getValueLabel?: (value: number) => string;
+    getCellAriaLabel?: (cell: HeatmapCell, context: HeatmapDetailsContext) => string;
+    renderCell?: (cell: HeatmapCell, context: HeatmapCellContext) => ReactNode;
+    renderDetails?: (cell: HeatmapCell, context: HeatmapDetailsContext) => ReactNode;
+    cellSize?: number | string;
+    rowLabelWidth?: number | string;
+    rowHeaderLabel?: string;
+    emptyMessage?: ReactNode;
+}
+export declare const Heatmap: import("react").ForwardRefExoticComponent<HeatmapProps & import("react").RefAttributes<HTMLDivElement>>;

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;