@enigmax/primitives 0.22.0 → 0.24.0

package/src/index.ts

@@ -1,6 +1,6 @@
 export { createMarquee, type MarqueeOptions, type MarqueeInstance, type MarqueeHover } from "@/core/marquee";
 export { createInput, type InputOptions, type InputInstance, type InputAction, type InputIcon, type InputActionState } from "@/core/input";
-export { createSearch, subsequenceMatcher, type SearchOptions, type SearchInstance, type SearchMatch, type FuseConstructor, type FuseLike } from "@/core/search";
+export { createSearch, subsequenceMatcher, shortenQuery, type SearchOptions, type SearchInstance, type SearchMatch, type FuseConstructor, type FuseLike } from "@/core/search";
 export { createButton, type ButtonOptions, type ButtonInstance, type ButtonState, type ButtonElement, type ButtonCooldown } from "@/core/button";
 export { INPUT_ICON_PATHS, iconMarkup } from "@/core/input";
 export {
@@ -12,6 +12,23 @@ export {
     type PasswordStrengthReport,
     type PasswordScore
 } from "@/core/password";
+// The colour maths behind `<Input type="color">`. The picker is React, the conversions are
+// not, so a vanilla page drawing its own square has the same parser and the same hue rule.
+export {
+    parseColor,
+    formatColor,
+    toHex,
+    rgbToHsv,
+    hsvToRgb,
+    rgbToHsl,
+    hslToRgb,
+    colorEquals,
+    type Rgb,
+    type Hsv,
+    type Hsl,
+    type ColorFormat,
+    type FormatColorOptions
+} from "@/core/color";
 export { createNotifications, type Notifications, type Notification, type NotificationInput, type NotificationTone, type NotificationAction, type NotificationsOptions, type PromiseMessages } from "@/core/notifications";
 export { createNetworkMonitor, SERVER_NETWORK_STATE, type NetworkState, type NetworkMonitor } from "@/core/network";
 export {
@@ -61,3 +78,77 @@ export {
     type PositionedRow,
     type PaletteKey
 } from "@/core/palette";
+// The select's non-rendering half, for the same reason as the palette's: the selection
+// rules, the filter and the highlight are arithmetic, not React.
+export {
+    createSelect,
+    SELECT_SEARCH_KEYS,
+    type SelectOption,
+    type SelectOptions,
+    type SelectInstance,
+    type SelectState,
+    type SelectMoveKey
+} from "@/core/select";
+// The context menu's non-rendering half: the tree, the highlight, the filter and the cache
+// of a fetched submenu are arithmetic, so a renderer that is not React only has to draw.
+export {
+    createContextMenu,
+    isAction,
+    CONTEXT_MENU_SEARCH_KEYS,
+    type ContextMenuEntry,
+    type ContextMenuAction,
+    type ContextMenuSeparator,
+    type ContextMenuLabel,
+    type ContextMenuOptions,
+    type ContextMenuInstance,
+    type ContextMenuState,
+    type ContextMenuLevel,
+    type ContextMenuPoint,
+    type ContextMenuMoveKey
+} from "@/core/context-menu";
+// Copy, Cut and Paste for a menu, and the DOM questions behind them: what is selected,
+// whether it can be written to, and how text goes back in without breaking undo.
+export {
+    CLIPBOARD_PREFIX,
+    clipboardEntries,
+    clipboardAction,
+    clipboardHasText,
+    inspectClipboardTarget,
+    performClipboardAction,
+    type ClipboardAction,
+    type ClipboardTarget,
+    type ClipboardMenuOptions,
+    type ClipboardMenuLabels
+} from "@/core/clipboard-menu";
+
+// The selection model, for the same reason: what a Ctrl+click does to a set is not React.
+export {
+    createSelection,
+    DEFAULT_SELECTION_SHORTCUTS,
+    type SelectionCommand,
+    type SelectionCommandName,
+    type SelectionCommandEvent,
+    type SelectionShortcuts,
+    type SelectionOptions,
+    type SelectionInstance,
+    type SelectionState,
+    type SelectionClickModifiers
+} from "@/core/selection";
+// Shortcuts as data, shared by the two above: the menu PRINTS what the list LISTENS for, and
+// a menu whose label says Ctrl+A over a list bound to Cmd+A is the defect that splitting them
+// produces.
+export {
+    parseShortcut,
+    matchesShortcut,
+    shortcutTokens,
+    shortcutText,
+    shortcutList,
+    isApplePlatform,
+    typeaheadStep,
+    TYPEAHEAD_MS,
+    type Shortcut,
+    type ShortcutSpec,
+    type ShortcutEvent,
+    type TypeaheadState,
+    type TypeaheadStep
+} from "@/core/keys";

package/src/react/context-menu/context.ts

@@ -0,0 +1,64 @@
+"use client";
+
+import { createContext, useContext } from "react";
+import type { ReactNode, RefObject } from "react";
+import type { ContextMenuAction, ContextMenuEntry, ContextMenuInstance, ContextMenuPoint, ContextMenuState } from "@/core/context-menu";
+
+/**
+ * One row, as React draws it. The core carries `icon` as `unknown` because it cannot know
+ * what a node is; here it is one.
+ */
+export interface ContextMenuItem extends Omit<ContextMenuAction, "icon" | "items"> {
+    icon?: ReactNode;
+    items?: readonly ContextMenuNode[];
+}
+
+/** Anything that can appear in a menu, with React's icon type. */
+export type ContextMenuNode = ContextMenuItem | Exclude<ContextMenuEntry, ContextMenuAction>;
+
+export interface ContextMenuContextValue {
+    instance: ContextMenuInstance;
+    state: ContextMenuState;
+    /**
+     * Open at a point, over what the press landed on. False when there was nothing to show,
+     * so the press is left alone.
+     *
+     * `target` is what the clipboard rows are built from - the field or the selection under
+     * the pointer - and a caller that leaves it out gets a menu with none of them, which is
+     * the right answer for a menu opened from somewhere that is not a press.
+     */
+    open: (point: ContextMenuPoint, target?: EventTarget | null) => boolean;
+    close: () => void;
+    /** ids the parts need to point at each other. */
+    ids: { trigger: string; };
+    panelId: (level: number) => string;
+    itemId: (level: number, index: number) => string;
+    triggerRef: RefObject<HTMLElement | null>;
+    /** Which panel the keyboard is in. Always the deepest open one. */
+    onMenuKeyDown: (event: React.KeyboardEvent) => void;
+    /** How long the pointer must rest on a row before its submenu opens, and before one closes. */
+    delays: { open: number; close: number; };
+    /** Drop the pending close, wherever it was scheduled. Called wherever the pointer lands. */
+    cancelClose: () => void;
+    /** Close everything below `level`, after the beat - replacing any close already waiting. */
+    scheduleClose: (level: number) => void;
+    /** Draw a row instead of the default icon / label / shortcut. */
+    renderItem?: (item: ContextMenuItem, level: number, index: number) => ReactNode;
+    /** Shown while a fetched submenu has not answered. */
+    loadingLabel: ReactNode;
+    /** Shown when a filter matched nothing, or a fetched submenu came back with nothing. */
+    emptyLabel: ReactNode;
+}
+
+/**
+ * Null rather than a default: a part rendered outside its Root is a mistake with an obvious
+ * fix, and a silent default would leave it half-working - a trigger that opens nothing, a row
+ * that invokes into the void.
+ */
+export const ContextMenuContext = createContext<ContextMenuContextValue | null>(null);
+
+export function useContextMenuContext(part: string): ContextMenuContextValue {
+    const value = useContext(ContextMenuContext);
+    if (!value) throw new Error(`<${part}> must be rendered inside <ContextMenu.Root>.`);
+    return value;
+}

package/src/react/context-menu/index.tsx

@@ -0,0 +1,108 @@
+"use client";
+
+import type { ReactNode } from "react";
+import * as parts from "@/react/context-menu/root";
+import { useContextMenuContext } from "@/react/context-menu/context";
+import type { ContextMenuRootProps, ContextMenuTriggerProps, ContextMenuContentProps } from "@/react/context-menu/root";
+
+export type ContextMenuProps = ContextMenuRootProps & {
+    /** How many rows to put in the document at once. `Infinity` renders the lot. */
+    chunk?: ContextMenuContentProps["chunk"];
+    /** Open on a long press as well, which is what a right-click is on a touch screen. */
+    longPress?: boolean;
+    triggerProps?: ContextMenuTriggerProps;
+    contentProps?: ContextMenuContentProps;
+};
+
+/**
+ * The context menu, assembled.
+ *
+ * ```tsx
+ * <ContextMenu
+ *     title={file.name}
+ *     items={[
+ *         { id: "rename", label: "Rename", shortcut: "F2", icon: <Pencil /> },
+ *         { type: "separator" },
+ *         { id: "delete", label: "Delete", shortcut: "Delete", destructive: true }
+ *     ]}
+ *     onSelect={(item) => run(item.id)}
+ * >
+ *     <FileRow file={file} />
+ * </ContextMenu>
+ * ```
+ *
+ * Everything it renders is a part you can render yourself instead - see `ContextMenu.Root`
+ * for the anatomy. This is those parts in the order they belong in, not a different
+ * component: the children become the area a right-click opens the menu over.
+ *
+ * A menu with no rows to show does not open, and the press falls through to the browser's own
+ * menu - an empty box at the pointer tells the reader nothing, and swallowing the press to
+ * show one tells them less.
+ */
+export function ContextMenu(props: ContextMenuProps): ReactNode {
+    const { chunk, longPress, triggerProps, contentProps, children, ...rest } = props;
+
+    return (
+        <parts.ContextMenuRoot {...rest}>
+            <parts.ContextMenuTrigger longPress={longPress} {...triggerProps}>{children}</parts.ContextMenuTrigger>
+            <parts.ContextMenuContent chunk={chunk} {...contentProps} />
+        </parts.ContextMenuRoot>
+    );
+}
+
+ContextMenu.Root = parts.ContextMenuRoot;
+ContextMenu.Trigger = parts.ContextMenuTrigger;
+ContextMenu.Content = parts.ContextMenuContent;
+ContextMenu.Panel = parts.ContextMenuPanel;
+ContextMenu.Search = parts.ContextMenuSearch;
+ContextMenu.List = parts.ContextMenuList;
+ContextMenu.Item = parts.ContextMenuRow;
+
+export {
+    ContextMenuRoot,
+    ContextMenuTrigger,
+    ContextMenuContent,
+    ContextMenuPanel,
+    ContextMenuSearch,
+    ContextMenuList,
+    ContextMenuRow,
+    type ContextMenuRootProps,
+    type ContextMenuTriggerProps,
+    type ContextMenuContentProps,
+    type ContextMenuPanelProps,
+    type ContextMenuSearchProps,
+    type ContextMenuListProps,
+    type ContextMenuRowProps
+} from "@/react/context-menu/root";
+export { useContextMenuContext, type ContextMenuItem, type ContextMenuNode, type ContextMenuContextValue } from "@/react/context-menu/context";
+export {
+    createContextMenu,
+    isAction,
+    CONTEXT_MENU_SEARCH_KEYS,
+    type ContextMenuEntry,
+    type ContextMenuAction,
+    type ContextMenuSeparator,
+    type ContextMenuLabel,
+    type ContextMenuOptions,
+    type ContextMenuInstance,
+    type ContextMenuState,
+    type ContextMenuLevel,
+    type ContextMenuPoint,
+    type ContextMenuMoveKey
+} from "@/core/context-menu";
+// The clipboard rows as their own surface: a menu built from the parts can add them
+// itself, and a caller that performs Copy in its own way has the same reader and writer.
+export {
+    CLIPBOARD_PREFIX,
+    clipboardEntries,
+    clipboardAction,
+    clipboardHasText,
+    inspectClipboardTarget,
+    performClipboardAction,
+    type ClipboardAction,
+    type ClipboardTarget,
+    type ClipboardMenuOptions,
+    type ClipboardMenuLabels
+} from "@/core/clipboard-menu";
+export { CONTEXT_MENU_STYLES } from "@/react/context-menu/styles";
+export { shortcutTokens, shortcutText, parseShortcut, matchesShortcut, type Shortcut, type ShortcutSpec } from "@/core/keys";