@matchstick-trading/primitives 0.0.10

package/dist/DrawingsParts.d.ts

@@ -0,0 +1,194 @@
+import { type MutableRefObject, type ReactNode } from 'react';
+import { type NameProps } from './accessible-name.js';
+import type { CandleBar } from './core/chart-scale.js';
+import { type Drawing, type DrawingAnchor, type DrawingTool, type SnapMode } from './core/drawings.js';
+/**
+ * Drawings as parts: Root, Layer, Toolbar, List, Remove, Undo. Headless: parts draw SVG and add `data-part`, `data-tool`,
+ * `data-selected` and `data-draft`; the host gives them colour. Drawings are anchored to a time and a price, so they
+ * stay put when the chart pans, zooms or gets new bars.
+ *
+ * Root only holds state, with no element of its own, so put it above both the Chart and the Toolbar and List. Layer
+ * goes inside Chart.Plot. It takes no tab stop of its own: it listens for keys on the plot's own tab stop and only
+ * answers when a drawing is selected or a tool is in use, so the chart's keys work as before the rest of the time.
+ */
+/** A drawing being placed: the anchors set so far and where the pointer is now. */
+interface Draft {
+    tool: DrawingTool;
+    anchors: DrawingAnchor[];
+    preview: DrawingAnchor | null;
+}
+interface DrawingsContext {
+    drawings: readonly Drawing[];
+    setDrawings: (next: Drawing[]) => void;
+    tool: DrawingTool | null;
+    setTool: (tool: DrawingTool | null) => void;
+    selected: string | null;
+    setSelected: (id: string | null) => void;
+    snap: SnapMode;
+    draft: Draft | null;
+    setDraft: (draft: Draft | null) => void;
+    remove: (id: string) => void;
+    /** Lock or unlock one drawing. A locked drawing keeps its place: no drag, nudge, typed edit or removal. */
+    setLocked: (id: string, locked: boolean) => void;
+    /** Remove every drawing that is not locked. Undo puts them back. */
+    removeAll: () => void;
+    /** What the last removal took out, or null once it expired or was undone. */
+    removed: readonly Drawing[] | null;
+    /** Put the last removal back where it was. */
+    /** Puts the last removal back and says so in the live region. `describe` prints a drawing (default two decimals, UTC time); `focusRow` moves focus to the restored row of a List. */
+    undo: (options?: {
+        describe?: (drawing: Drawing) => string;
+        focusRow?: boolean;
+    }) => void;
+    /** How long a removal can be undone, in milliseconds; 0 means until the next removal. */
+    undoWindow: number;
+    /** The bars of the chart the Layer sits in (empty until a Layer mounts); the Edit form counts bars from them. */
+    bars: readonly CandleBar[];
+    setBars: (bars: readonly CandleBar[]) => void;
+    /** Say something in the polite live region of Drawings.Undo, for example "Updated Trend line ...". */
+    announce: (text: string) => void;
+    /** The last thing announced, or null. */
+    status: string | null;
+    /** The chart's plot element once a Layer mounts: where Escape in the toolbar sends focus. */
+    plotRef: MutableRefObject<SVGSVGElement | null>;
+    /** The Drawings.Undo region once it mounts, so a list that lost its last row can put focus on its Undo button. */
+    undoRegion: MutableRefObject<HTMLElement | null>;
+    /** Set by the Undo button: the List then focuses the restored row once it is back. */
+    focusRowNext: MutableRefObject<boolean>;
+    /** Set by a button that is about to remove drawings while focused: the Undo button takes focus once it shows. */
+    focusUndoNext: MutableRefObject<boolean>;
+}
+/** The drawings state of the Drawings.Root above. */
+export declare function useDrawings(part?: string): DrawingsContext;
+export interface DrawingsRootProps {
+    /** Controlled drawings; without it Root keeps its own list. */
+    drawings?: readonly Drawing[];
+    onDrawingsChange?: (drawings: Drawing[]) => void;
+    /** Controlled tool in use, or null for none. */
+    tool?: DrawingTool | null;
+    onToolChange?: (tool: DrawingTool | null) => void;
+    /** Controlled selected drawing id, or null. */
+    selected?: string | null;
+    onSelectedChange?: (id: string | null) => void;
+    /** 'magnet' puts new points on the nearest bar and its open, high, low or close. Default 'off'. */
+    snap?: SnapMode;
+    /** How long the last removal can be undone, in milliseconds. 0 keeps it until the next removal. Default 10 000. */
+    undoWindow?: number;
+    children?: ReactNode;
+}
+/** State for the other parts. Each of drawings, tool and selection is controlled when given, and kept here when not. */
+declare function Root({ drawings, onDrawingsChange, tool, onToolChange, selected, onSelectedChange, snap, undoWindow, children }: DrawingsRootProps): import("react").JSX.Element;
+/**
+ * Draws every drawing and the handles of the selected one. Put it inside Chart.Plot, after the candles.
+ *
+ * With a tool in use it adds a transparent `drawing-capture` rect over the plot: press to set the first point, move
+ * to preview, then release after a drag or click again to set the second. One-point tools place on the press. A new
+ * drawing is selected and the tool is put away. With no tool, pressing a drawing selects it and dragging moves it,
+ * or moves one anchor when a handle is grabbed; pressing anywhere else is left to the plot, which pans.
+ *
+ * From the keyboard, with a tool in use and the chart focused: Enter places a point at the crosshair (the bar the arrow keys
+ * moved to, at the crosshair price, which from the keyboard is that bar's close), Enter again places the second point of a
+ * two-point tool, and Escape drops the half-placed drawing. Each step is announced in Drawings.Undo's live region.
+ *
+ * `newText` is the words a new text note gets. `formatTime` prints times in those announcements (default HH:MM in UTC). The
+ * layer is hidden from assistive technology: the List is its text.
+ */
+declare function Layer({ className, newText, formatTime }: {
+    className?: string;
+    newText?: string;
+    formatTime?: (timestamp: number) => string;
+}): import("react").JSX.Element;
+export interface DrawingsToolbarProps {
+    className?: string;
+    'aria-label'?: string;
+    /** Which tools to offer, in order. Default all nine. */
+    tools?: readonly DrawingTool[];
+    /**
+     * A graphic for each tool, drawn before its words and hidden from assistive technology: an object by tool, or a
+     * function of the tool. No icons ship with the package. With `hideLabels` the icon is all that shows.
+     */
+    icon?: Partial<Record<DrawingTool, ReactNode>> | ((tool: DrawingTool) => ReactNode);
+    /** Each tool's words (its accessible name), by tool. Default: "Trend line", "Ray" and so on. */
+    labels?: Partial<Record<DrawingTool, string>>;
+    /** Show only the icons; the labels become each button's `aria-label`. Needs `icon`. Default false. */
+    hideLabels?: boolean;
+}
+/**
+ * One button per tool, built on Toolbar: one tab stop, the arrow keys, Home and End move between the buttons, and Tab
+ * leaves. A pressed button is the tool in use; pressing it again puts the tool away. Escape sends focus to the chart.
+ * Every button has its tool in words, even when an icon is all that shows.
+ */
+declare function Toolbar({ className, 'aria-label': label, tools, icon, labels, hideLabels }: DrawingsToolbarProps): import("react").JSX.Element;
+export interface DrawingsListProps {
+    className?: string;
+    'aria-label'?: string;
+    /** Decimals for printed prices. Default 2. */
+    decimals?: number;
+    /** Prints a time. Default HH:MM in UTC, with the date when a drawing spans days. */
+    formatTime?: (timestamp: number) => string;
+    /** Shown when there are no drawings. */
+    empty?: string;
+}
+/**
+ * The drawings in words, with a button to select and a button to remove each. The selected one has aria-current.
+ * Delete or Backspace on a drawing's line removes it, as on the chart, and so does its Remove button. Focus moves to the
+ * next line; after the last line is removed it goes to the Undo button when Drawings.Undo is showing it, else to the empty
+ * list (the "No drawings" line), never to the top of the page.
+ */
+declare function List({ className, 'aria-label': label, decimals, formatTime, empty }: DrawingsListProps): import("react").JSX.Element;
+export interface DrawingsRemoveProps extends NameProps {
+    className?: string;
+    /** Remove every drawing that is not locked, not only the selected one. */
+    all?: boolean;
+    /** The button's words. Default "Remove", or "Remove all" with `all`. */
+    children?: ReactNode;
+}
+/**
+ * A button that removes the selected drawing, or with `all` every drawing that is not locked. It acts only on a
+ * selection that already exists, never on what was under a finger when it was pressed, and the removal can be undone
+ * (see Undo). With nothing to remove it is `aria-disabled` rather than disabled, so keyboard focus stays on it.
+ */
+declare function Remove({ className, all, icon, label, hideLabel, children }: DrawingsRemoveProps): import("react").JSX.Element;
+export interface DrawingsUndoProps extends NameProps {
+    className?: string;
+    /** Decimals for printed prices. Default 2. */
+    decimals?: number;
+    formatTime?: (timestamp: number) => string;
+}
+/**
+ * Says what the last removal took out and offers Undo for as long as the Root's undoWindow lasts (10 seconds by
+ * default). The region is always in the page and announced politely, so a screen reader hears each removal as it
+ * happens. It is also where the other drawing announcements land (a point placed from the keyboard, an applied Edit), in
+ * a `data-part='drawing-status'` line, so one live region carries everything. Ctrl or Cmd + Z does the same from the chart. Only the last removal can be undone. Undo says what it restored in the same region. Focus moves to the
+ * restored row of Drawings.List when one is showing, else to the region (which then holds that sentence), so the button going away does not drop it to the top of the page.
+ */
+declare function Undo({ className, decimals, formatTime, icon, label, hideLabel }: DrawingsUndoProps): import("react").JSX.Element;
+export interface DrawingsLockProps extends NameProps {
+    className?: string;
+    /** The button's words. Default "Lock". The state is carried by aria-pressed, so the words do not change. */
+    children?: ReactNode;
+}
+/**
+ * A toggle for the selected drawing's lock. Pressed means locked: it cannot be dragged, nudged, edited by typing or
+ * removed until it is unlocked. With nothing selected it is `aria-disabled` and does nothing.
+ */
+declare function Lock({ className, icon, label, hideLabel, children }: DrawingsLockProps): import("react").JSX.Element;
+export interface DrawingsEditProps extends NameProps {
+    className?: string;
+    /** Decimals shown in the price fields. Default 2. */
+    decimals?: number;
+    /** Prints a time in the "Updated ..." announcement. Default HH:MM in UTC. */
+    formatTime?: (timestamp: number) => string;
+    /** The toggle button's words. Default "Edit". */
+    children?: ReactNode;
+}
+/**
+ * Type exact values for the selected drawing: a price and/or a time (UTC) for each anchor, and the words of a text
+ * note. A closed "Edit" button opens a small form with only the fields that tool has (a horizontal line has just a
+ * price). Enter applies, Escape closes without applying, a bad value is named next to its field and nothing is half
+ * applied and "Updated ..." is announced in Drawings.Undo's live region. This is also the way to place a line at an exact
+ * price without a pointer. A locked drawing cannot be edited.
+ */
+declare function Edit({ className, decimals: rawDecimals, formatTime, icon, label, hideLabel, children }: DrawingsEditProps): import("react").JSX.Element;
+export { Root, Layer, Toolbar, List, Remove, Undo, Lock, Edit };
+//# sourceMappingURL=DrawingsParts.d.ts.map