@yam8d/m8-sdk 0.2.0 → 0.3.2

package/types/viewContext.d.ts

@@ -0,0 +1,112 @@
+/**
+ * viewContext.ts
+ *
+ * Derives semantic meaning from raw M8State by mapping cursor position and
+ * currentLine content to typed, labelled fields using the m8-view-context.json schema.
+ *
+ * The five grid views (song, chain, phrase, table, groove) are fully supported.
+ * Parameter views (inst, mixer, project, …) return a minimal context with viewName only.
+ */
+import type { M8State } from './types';
+export type M8FieldType = 'chainRef' | 'phraseRef' | 'note' | 'velocity' | 'instrumentRef' | 'fxCommand' | 'fxValue' | 'transpose' | 'ticks' | 'volume' | 'ppq' | 'instrumentName' | 'eqSlot' | 'rowIndex';
+/**
+ * A single parsed field value extracted from the currentLine.
+ */
+export interface M8ParsedField {
+    /** Column key as defined in the schema (e.g. 'fx1cmd', 'note', 'track3'). */
+    key: string;
+    /** Human-readable label (e.g. 'FX1 Command', 'Note (N)'). */
+    label: string;
+    /** Semantic type of this field. */
+    type: M8FieldType;
+    /** Raw text extracted from currentLine (trimmed). */
+    rawValue: string;
+    /**
+     * Parsed integer (from hex) when the field holds a numeric value.
+     * `null` for empty cells ('--', '---') and text-only types (note name, fxCommand).
+     */
+    hexValue: number | null;
+    /** True when the cell is empty/unused ('--', '---', '---00'). */
+    isEmpty: boolean;
+    /** Extra view-specific metadata (e.g. { trackIndex: 2 } for song view track columns). */
+    meta?: Record<string, unknown>;
+}
+/**
+ * All fields parsed from the current row (line at cursorPos.y).
+ */
+export interface M8ParsedRow {
+    /** Row index (hex-parsed) derived from the leftmost chars of currentLine. null if not parseable. */
+    rowIndex: number | null;
+    /** Schema key for the row index field (e.g. 'songRow', 'step', 'chainPos'). */
+    rowKey: string;
+    /** Map of column key → parsed field for every column in this view. */
+    fields: Record<string, M8ParsedField>;
+}
+/**
+ * The field currently under the cursor, plus row context.
+ */
+export interface M8ActiveField extends M8ParsedField {
+    /** Repetition of the view name for convenience. */
+    viewName: string;
+    /** Row index of the line containing this field (null if not parseable). */
+    rowIndex: number | null;
+}
+/**
+ * Full semantic context for the current M8State.
+ */
+export interface M8SemanticContext {
+    /** M8 view name (lowercased), e.g. 'song', 'phrase'. */
+    viewName: string;
+    /** Human-readable view title from schema ('Song View', 'Phrase View', …). */
+    viewTitle: string | null;
+    /** View description from the schema. */
+    viewDescription: string | null;
+    /**
+     * The numeric ID of the current view item, parsed from the screen title.
+     * e.g. 'F2' from ' CHAIN F2*', '03' from ' PHRASE 03'.
+     * null for views that have no item number (song, instrument pool).
+     */
+    viewId: string | null;
+    /** True when the title carries a '*' suffix, indicating unsaved changes. */
+    isUnsaved: boolean;
+    /** Whether this view is a structured grid (song/chain/phrase/table/groove). */
+    isGridView: boolean;
+    /** All fields on the line at cursorPos.y (null for non-grid views or missing line). */
+    row: M8ParsedRow | null;
+    /** The specific field under the cursor (null when cursor is out of any column range). */
+    activeField: M8ActiveField | null;
+}
+/**
+ * Look up the description of a 3-character FX command name.
+ * Returns undefined if the command is unknown.
+ */
+export declare function lookupFxCommand(cmd: string): {
+    description: string;
+} | undefined;
+/**
+ * Derives a full semantic context from the current M8State.
+ *
+ * @example
+ * ```ts
+ * const ctx = getSemanticContext(state)
+ * if (ctx?.activeField?.type === 'chainRef') {
+ *   const track = ctx.activeField.meta?.trackIndex  // 1–8
+ *   const chainNum = ctx.activeField.hexValue        // 0–255 or null if empty
+ *   const songRow = ctx.row?.rowIndex
+ * }
+ * ```
+ */
+export declare function getSemanticContext(state: M8State): M8SemanticContext | null;
+/**
+ * Returns a short human-readable description of what the cursor is currently on.
+ *
+ * @example
+ * "Track 3 — Chain 0A — Song Row 02"
+ * "Note A#4 — Step 7 (Phrase)"
+ * "FX1 Command: KIL (Kill Note) — Step 0"
+ */
+export declare function describeContext(ctx: M8SemanticContext): string;
+/**
+ * Formats a parsed field value as a human-readable string.
+ */
+export declare function formatFieldValue(field: M8ParsedField): string;