@matchstick-trading/primitives 0.0.10

package/dist/MenuParts.js

@@ -0,0 +1,202 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useEffect, useId, useMemo, useRef, useState } from 'react';
+import { buttonFace } from './accessible-name.js';
+import { useNameCheck, useToolbarContext, useToolbarItem } from './ToolbarParts.js';
+const Context = createContext(null);
+function useMenu(part) {
+    const context = useContext(Context);
+    if (!context)
+        throw new Error(`${part} needs a Menu.Root (or Submenu.Root) above it.`);
+    return context;
+}
+function useMenuState(parent, { open, onOpenChange }) {
+    const [inner, setInner] = useState(false);
+    const isOpen = open !== undefined ? open : inner;
+    const triggerRef = useRef(null);
+    const focusOnOpen = useRef('first');
+    const triggerId = useId();
+    const listId = useId();
+    const set = useCallback((next) => {
+        if (open === undefined)
+            setInner(next);
+        onOpenChange?.(next);
+    }, [open, onOpenChange]);
+    const show = useCallback((focus) => { focusOnOpen.current = focus; set(true); }, [set]);
+    const hide = useCallback((returnFocus) => {
+        set(false);
+        if (returnFocus)
+            triggerRef.current?.focus();
+    }, [set]);
+    const hideAll = useCallback((returnFocus) => {
+        if (parent)
+            parent.hideAll(returnFocus);
+        else
+            hide(returnFocus);
+    }, [parent, hide]);
+    return useMemo(() => ({ open: isOpen, show, hide, hideAll, triggerId, listId, triggerRef, focusOnOpen, submenu: parent !== null }), [isOpen, show, hide, hideAll, triggerId, listId, parent]);
+}
+/** Holds the open state and the wrapper element the List is placed against. */
+function Root({ className, open, onOpenChange, children }) {
+    const context = useMenuState(null, { open, onOpenChange });
+    const element = useRef(null);
+    // A press outside the menu, anywhere in the page, closes it.
+    useEffect(() => {
+        if (!context.open)
+            return;
+        const onDown = (event) => { if (!element.current?.contains(event.target))
+            context.hide(false); };
+        document.addEventListener('pointerdown', onDown);
+        return () => document.removeEventListener('pointerdown', onDown);
+    }, [context]);
+    return (_jsx(Context.Provider, { value: context, children: _jsx("div", { ref: element, className: className, "data-mt": "", "data-part": "menu", "data-state": context.open ? 'open' : 'closed', 
+            // Focus leaving for another control (Tab, or a script) closes the menu; a null target is the window losing focus.
+            onBlur: (event) => { if (context.open && event.relatedTarget && !element.current?.contains(event.relatedTarget))
+                context.hide(false); }, children: children }) }));
+}
+/** The button that opens the menu: `aria-haspopup="menu"` and `aria-expanded`. Inside a Toolbar it is one of its items. */
+function Trigger({ className, icon, label, hideLabel, children }) {
+    const menu = useMenu('Menu.Trigger');
+    const toolbar = useToolbarContext();
+    const item = useToolbarItem(menu.triggerRef);
+    const face = buttonFace(undefined, { icon, label, hideLabel, children });
+    useNameCheck(menu.triggerRef, 'Menu.Trigger');
+    const onKeyDown = (event) => {
+        if (event.altKey || event.ctrlKey || event.metaKey)
+            return;
+        // In a vertical toolbar Up and Down move between items, so the menu opens to the side instead.
+        const vertical = toolbar?.orientation === 'vertical';
+        const open = vertical ? event.key === 'ArrowRight' : event.key === 'ArrowDown';
+        if (!open && !(!vertical && event.key === 'ArrowUp'))
+            return;
+        event.preventDefault();
+        event.stopPropagation();
+        menu.show(event.key === 'ArrowUp' ? 'last' : 'first');
+    };
+    return (_jsx("button", { ref: menu.triggerRef, id: menu.triggerId, type: "button", className: className, "data-mt": "", "data-part": "menu-trigger", "data-touch-target": "", "data-state": menu.open ? 'open' : 'closed', "aria-haspopup": "menu", "aria-expanded": menu.open, "aria-controls": menu.open ? menu.listId : undefined, "aria-label": face['aria-label'], tabIndex: item.tabIndex, onFocus: item.onFocus, onKeyDown: onKeyDown, onClick: () => (menu.open ? menu.hide(false) : menu.show('first')), children: face.content }));
+}
+/** The items of a list: its own menuitems, not those of a submenu inside it. Disabled ones are skipped. */
+function itemsOf(list) {
+    return [...list.querySelectorAll("[role='menuitem'], [role='menuitemradio']")].filter((el) => el.closest("[role='menu']") === list && !el.disabled);
+}
+/** The open list, role="menu". It is not in the page while closed. */
+function List({ className, 'aria-label': label, children }) {
+    const menu = useMenu('Menu.List');
+    const ref = useRef(null);
+    const typed = useRef({ text: '', timer: 0 });
+    // Opening puts focus on an item. Arrow keys, a tap and Enter all arrive here.
+    useEffect(() => {
+        if (!menu.open)
+            return;
+        const items = itemsOf(ref.current);
+        (menu.focusOnOpen.current === 'last' ? items[items.length - 1] : items[0])?.focus();
+    }, [menu.open, menu.focusOnOpen]);
+    useEffect(() => () => window.clearTimeout(typed.current.timer), []);
+    if (!menu.open)
+        return null;
+    const onKeyDown = (event) => {
+        const list = ref.current;
+        // Keys from inside a submenu are handled by that submenu's list.
+        if (!list || event.target.closest("[role='menu']") !== list)
+            return;
+        if (event.altKey || event.ctrlKey || event.metaKey)
+            return;
+        const items = itemsOf(list);
+        const at = items.indexOf(document.activeElement);
+        const go = (index) => { event.preventDefault(); event.stopPropagation(); items[index]?.focus(); };
+        switch (event.key) {
+            case 'ArrowDown': return go(items.length === 0 ? 0 : (at + 1) % items.length);
+            case 'ArrowUp': return go(items.length === 0 ? 0 : (at - 1 + items.length) % items.length);
+            case 'Home': return go(0);
+            case 'End': return go(items.length - 1);
+            case 'Escape':
+                event.preventDefault();
+                event.stopPropagation(); // the toolbar or page behind must not also react
+                return menu.hide(true);
+            case 'ArrowLeft':
+            case 'ArrowRight': {
+                // A submenu closes with the arrow that points back toward its parent: Left in left-to-right text, Right in right-to-left.
+                const closing = getComputedStyle(list).direction === 'rtl' ? 'ArrowRight' : 'ArrowLeft';
+                if (!menu.submenu || event.key !== closing)
+                    return;
+                event.preventDefault();
+                event.stopPropagation();
+                return menu.hide(true);
+            }
+            case 'Tab':
+                return menu.hideAll(true); // focus goes back to the trigger first, so Tab then moves on from there
+            default:
+        }
+        // Typeahead: letters build a prefix (reset after a short pause); one letter repeated steps through items that share it.
+        if (event.key.length === 1 && event.key !== ' ') {
+            event.preventDefault();
+            window.clearTimeout(typed.current.timer);
+            typed.current.text += event.key.toLowerCase();
+            typed.current.timer = window.setTimeout(() => { typed.current.text = ''; }, 600);
+            const word = typed.current.text;
+            const name = (el) => {
+                const label = el.getAttribute('aria-label');
+                if (label !== null)
+                    return label.trim().toLowerCase();
+                const copy = el.cloneNode(true); // an icon is aria-hidden: its text is not the item's name
+                copy.querySelectorAll('[aria-hidden="true"]').forEach((hidden) => hidden.remove());
+                return (copy.textContent ?? '').trim().toLowerCase();
+            };
+            const repeated = word.length > 1 && [...word].every((c) => c === word[0]);
+            const prefix = repeated ? word[0] : word;
+            const order = [...items.slice(at + 1), ...items.slice(0, at + 1)];
+            (order.find((el) => name(el).startsWith(prefix)) ?? order.find((el) => name(el).startsWith(word)))?.focus();
+        }
+    };
+    return (_jsx("div", { ref: ref, id: menu.listId, className: className, "data-mt": "", "data-part": menu.submenu ? 'submenu-list' : 'menu-list', role: "menu", "aria-labelledby": label ? undefined : menu.triggerId, "aria-label": label, "aria-orientation": "vertical", onKeyDown: onKeyDown, children: children }));
+}
+/** One choice. A menuitem button; the roving focus is handled by the list, so it is not a tab stop. */
+function Item({ className, disabled, onSelect, keepOpen, icon, label, hideLabel, children }) {
+    const menu = useMenu('Menu.Item');
+    const ref = useRef(null);
+    const face = buttonFace(undefined, { icon, label, hideLabel, children });
+    useNameCheck(ref, 'Menu.Item');
+    return (_jsx("button", { ref: ref, type: "button", className: className, "data-mt": "", "data-part": "menu-item", "data-touch-target": "", role: "menuitem", tabIndex: -1, disabled: disabled, "aria-label": face['aria-label'], onClick: () => { onSelect?.(); if (!keepOpen)
+            menu.hideAll(true); }, children: face.content }));
+}
+/** A choice among several: `aria-checked` says which is on. Picking it runs onSelect and closes the menu. */
+function RadioItem({ className, checked, disabled, onSelect, keepOpen, icon, label, hideLabel, children }) {
+    const menu = useMenu('Menu.RadioItem');
+    const ref = useRef(null);
+    const face = buttonFace(undefined, { icon, label, hideLabel, children });
+    useNameCheck(ref, 'Menu.RadioItem');
+    return (_jsx("button", { ref: ref, type: "button", className: className, "data-mt": "", "data-part": "menu-radio-item", "data-touch-target": "", role: "menuitemradio", "aria-checked": checked, tabIndex: -1, disabled: disabled, "aria-label": face['aria-label'], onClick: () => { onSelect?.(); if (!keepOpen)
+            menu.hideAll(true); }, children: face.content }));
+}
+/** A thin divider between groups of items. */
+function Separator({ className }) {
+    return _jsx("div", { className: className, "data-mt": "", "data-part": "menu-separator", role: "separator" });
+}
+/** A menu inside a menu: put Submenu.Trigger and Submenu.List inside it, among the items of the parent List. */
+function SubmenuRoot({ className, open, onOpenChange, children }) {
+    const parent = useMenu('Submenu.Root');
+    const context = useMenuState(parent, { open, onOpenChange });
+    const element = useRef(null);
+    return (_jsx(Context.Provider, { value: context, children: _jsx("div", { ref: element, className: className, "data-mt": "", "data-part": "submenu", "data-state": context.open ? 'open' : 'closed', 
+            // Focus moving to a sibling item of the parent closes the submenu.
+            onBlur: (event) => { if (context.open && event.relatedTarget && !element.current?.contains(event.relatedTarget))
+                context.hide(false); }, children: children }) }));
+}
+/** The item that opens a submenu: a menuitem with `aria-haspopup` and `aria-expanded`. ArrowRight (ArrowLeft in right-to-left text) opens it. */
+function SubmenuTrigger({ className, icon, label, hideLabel, children }) {
+    const menu = useMenu('Submenu.Trigger');
+    const face = buttonFace(undefined, { icon, label, hideLabel, children });
+    useNameCheck(menu.triggerRef, 'Submenu.Trigger');
+    const onKeyDown = (event) => {
+        if (event.altKey || event.ctrlKey || event.metaKey)
+            return;
+        const rtl = getComputedStyle(event.currentTarget).direction === 'rtl';
+        if (event.key !== (rtl ? 'ArrowLeft' : 'ArrowRight'))
+            return;
+        event.preventDefault();
+        event.stopPropagation();
+        menu.show('first');
+    };
+    return (_jsx("button", { ref: menu.triggerRef, id: menu.triggerId, type: "button", className: className, "data-mt": "", "data-part": "submenu-trigger", "data-touch-target": "", "data-state": menu.open ? 'open' : 'closed', role: "menuitem", "aria-haspopup": "menu", "aria-expanded": menu.open, "aria-controls": menu.open ? menu.listId : undefined, "aria-label": face['aria-label'], tabIndex: -1, onKeyDown: onKeyDown, onClick: () => (menu.open ? menu.hide(false) : menu.show('first')), children: face.content }));
+}
+export { Root, Trigger, List, Item, RadioItem, Separator, SubmenuRoot, SubmenuTrigger };

package/dist/Notice.d.ts

@@ -0,0 +1,18 @@
+import type { ReactNode } from 'react';
+export type NoticeKind = 'gap' | 'stale' | 'truncated' | 'unsupported' | 'rights' | 'info' | 'ok' | 'error';
+export interface NoticeProps {
+    /** `status` is polite (a normal condition); `alert` is for refusals and errors. */
+    role?: 'status' | 'alert';
+    kind?: NoticeKind;
+    /** Element to render: a paragraph by default, a span for inline text. */
+    as?: 'p' | 'span';
+    /** Host class, kept so existing styles keep matching. */
+    className?: string;
+    children?: ReactNode;
+}
+/**
+ * One integrity message. Replaces the repeated `<p role="status">` / `<p role="alert">` paragraphs: the same
+ * element, role and class as before, plus `data-mt` (the scope the token styles hang on) and `data-kind` so a host can style by kind.
+ */
+export declare function Notice({ role, kind, as, className, children }: NoticeProps): import("react").JSX.Element;
+//# sourceMappingURL=Notice.d.ts.map

package/dist/Notice.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * One integrity message. Replaces the repeated `<p role="status">` / `<p role="alert">` paragraphs: the same
+ * element, role and class as before, plus `data-mt` (the scope the token styles hang on) and `data-kind` so a host can style by kind.
+ */
+export function Notice({ role = 'status', kind, as = 'p', className, children }) {
+    const Tag = as;
+    return (_jsx(Tag, { role: role, className: className, "data-mt": true, "data-kind": kind, children: children }));
+}

package/dist/Panels.d.ts

@@ -0,0 +1,9 @@
+import { Root, Layer, List, Move } from './PanelsParts.js';
+export * from './PanelsParts.js';
+export declare const Panels: {
+    Root: typeof Root;
+    Layer: typeof Layer;
+    List: typeof List;
+    Move: typeof Move;
+};
+//# sourceMappingURL=Panels.d.ts.map

package/dist/Panels.js

@@ -0,0 +1,5 @@
+import { Root, Layer, List, Move } from './PanelsParts.js';
+// The parts live in PanelsParts.js (a client module). The namespace object is built here, outside it, so a server
+// component can write `Panels.Root`: a property of an object exported from a client module is not reachable there.
+export * from './PanelsParts.js';
+export const Panels = { Root, Layer, List, Move };

package/dist/PanelsParts.d.ts

@@ -0,0 +1,62 @@
+import { type ReactNode } from 'react';
+import { type PanelLayout, type PanelSpec } from './core/panels.js';
+import { type AlignOptions } from './core/series.js';
+import { type PanelSeriesData, type PanelsContextValue } from './panels-context.js';
+/**
+ * Panels as parts: Panels.Root, Panels.Layer, Panels.List and Panels.Move. A chart is one or more vertical bands, each
+ * with its own price scale, on one shared time axis. The chart's own bars and volume stay in the first band, `main`.
+ * Other series (a value per bar, like a study) are placed in a band by id and moved between bands by a menu of relative
+ * destinations ("Move up to Main", "Move to a new panel below"), which works by touch and keyboard. Headless: the parts
+ * set `data-part` and `data-state='selected'`; tokens.css gives the lines a stroke and the host gives them colour.
+ *
+ * Everything is opt-in: without a Panels.Root above it, Chart draws exactly as it did.
+ */
+export interface PanelsRootProps {
+    /** How a series with `points` is placed on the bars. Default `{ mode: 'exact' }`; `asof` with `toleranceMs` takes the latest point at or before each bar. */
+    align?: AlignOptions;
+    /** The series to draw besides the chart's bars. Keep it stable (useMemo); a new array each render only costs a layout pass. */
+    series: readonly (PanelSeriesData & {
+        panel?: string;
+    })[];
+    /** Names and weights for the bands the series start in, below `main`. A panel a series names but this leaves out is created with its id as the label. */
+    panels?: readonly PanelSpec[];
+    /** Controlled layout; without it Root keeps its own. */
+    layout?: PanelLayout;
+    onLayoutChange?: (layout: PanelLayout) => void;
+    children?: ReactNode;
+}
+/** Holds the layout, says each move in a polite live region and tells Chart how tall the first band is. Wrap the Chart in it. */
+declare function Root({ series: given, panels: named, layout, onLayoutChange, align, children }: PanelsRootProps): import("react").JSX.Element;
+declare function usePanels(part: string): PanelsContextValue;
+/**
+ * Draws the series in their bands. Put it inside `Chart.Plot`, after the chart's own parts. The series in `main` use the
+ * chart's price scale (and keep themselves in view); every other band has its own scale, grid, price labels and
+ * a divider. With a Selection.Root above, a tap on a series line selects it. A band is never shorter than 40, so give the
+ * chart enough height for the bands you use.
+ */
+declare function Layer(): import("react").JSX.Element;
+export interface PanelsListProps {
+    className?: string;
+    /** Prints one value. Default: the chart's decimals. */
+    format?: (value: number) => string;
+}
+/**
+ * The series as text: each one's name, its panel, and its value at the crosshair bar (the last bar in view when there is
+ * no crosshair), so the numbers are not only a picture. With a Selection.Root above, each row has a button that selects
+ * the series. Put it outside the SVG, inside `Chart.Root`.
+ */
+declare function List({ className, format }: PanelsListProps): import("react").JSX.Element | null;
+export interface PanelsMoveProps {
+    className?: string;
+    /** The series to move. Default: the selected one (it needs a Selection.Root above). */
+    seriesId?: string;
+}
+/**
+ * The way to move a series to another panel without dragging: buttons for where it can go, relative to where it is
+ * (up, down, a new panel above, a new panel below). It shows while a series of the Root is selected (or for `seriesId`)
+ * and says each move in the live region. After a move the focus goes to the group, so a keyboard or screen reader user
+ * is not left on a button that is gone.
+ */
+declare function Move({ className, seriesId }: PanelsMoveProps): import("react").JSX.Element | null;
+export { Root, Layer, List, Move, usePanels };
+//# sourceMappingURL=PanelsParts.d.ts.map