@moyarich/console-addon-navigation 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @moyarich/console-addon-navigation
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Navigate errors and warnings. Jump between visible errors and warnings, or annotated messages when annotations are enabled.
+
+[Documentation and live examples](https://moyarich.github.io/console/)
+
+## Install
+
+```bash
+npm install @moyarich/console @moyarich/console-addon-navigation
+```
+
+Configure the `@moyarich` scope and authenticate with GitHub Packages as described in the [installation guide](../../../README.md#installation).
+
+Required peer dependencies: `@moyarich/console-core@^0.2.0`.
+
+## Quick start
+
+```tsx
+import { Console } from "@moyarich/console";
+import { createConsoleNavigationAddon } from "@moyarich/console-addon-navigation";
+
+const addons = [createConsoleNavigationAddon()];
+
+// Pass your application's structured messages to Console.
+<Console messages={messages} addons={addons} />;
+```
+
+The addon is optional and can be combined with other Console addons. The host application remains responsible for supplying and retaining messages.
+
+## Learn more
+
+Explore [runnable package examples](./examples) and the [Console documentation](https://moyarich.github.io/console/) for available settings and integration patterns.
+
+Review the [changelog](./CHANGELOG.md) for changes by version and [package metadata](./package.json) for dependency requirements.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,187 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const consoleCore = require("@moyarich/console-core");
+const CONSOLE_NAVIGATION_ADDON_ID = "@moyarich/console-addon-navigation";
+const annotationLookupService = consoleCore.createConsoleServiceToken(
+  "@moyarich/console-addon-annotations.controller"
+);
+const consoleNavigationService = consoleCore.createConsoleServiceToken(
+  `${CONSOLE_NAVIGATION_ADDON_ID}.controller`
+);
+function messageMatches(message, kind, annotations) {
+  if (!message.id) return false;
+  if (kind === "error") return message.method === "error";
+  if (kind === "warning") {
+    return message.method === "warn" || message.method === "assert";
+  }
+  return annotations.has(message.id);
+}
+function createConsoleNavigationController(dependencies) {
+  let state = Object.freeze({ boundary: null });
+  const listeners = /* @__PURE__ */ new Set();
+  const update = (next) => {
+    state = Object.freeze(next);
+    for (const listener of listeners) listener();
+  };
+  const getVisibleMessages = () => {
+    const snapshot = dependencies.getData()?.getSnapshot();
+    return snapshot?.mode === "console" ? snapshot.visible : [];
+  };
+  const controller = {
+    getState: () => state,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    jumpToMessage(id) {
+      const normalized = id.trim();
+      if (!normalized) return false;
+      const visible = getVisibleMessages();
+      if (!visible.some((message) => message.id === normalized)) return false;
+      const scrolled = dependencies.getViewport()?.scrollToMessage(normalized, {
+        block: "nearest"
+      }) ?? false;
+      if (scrolled) {
+        update({ currentTargetId: normalized, boundary: null });
+      }
+      return scrolled;
+    },
+    navigate(kind, direction) {
+      const annotations = new Set(
+        dependencies.getAnnotations()?.getAnnotatedMessageIds() ?? []
+      );
+      const candidates = getVisibleMessages().filter(
+        (message) => messageMatches(message, kind, annotations)
+      );
+      const ids = candidates.flatMap(
+        (message) => message.id ? [message.id] : []
+      );
+      if (ids.length === 0) {
+        update({
+          currentTargetId: state.currentTargetId,
+          kind,
+          boundary: direction === "next" ? "end" : "start"
+        });
+        return void 0;
+      }
+      const currentIndex = state.currentTargetId ? ids.indexOf(state.currentTargetId) : -1;
+      const targetIndex = direction === "next" ? currentIndex < 0 ? 0 : currentIndex + 1 : currentIndex < 0 ? ids.length - 1 : currentIndex - 1;
+      if (targetIndex < 0 || targetIndex >= ids.length) {
+        update({
+          currentTargetId: state.currentTargetId,
+          kind,
+          boundary: direction === "next" ? "end" : "start"
+        });
+        return void 0;
+      }
+      const targetId = ids[targetIndex];
+      const scrolled = dependencies.getViewport()?.scrollToMessage(targetId, {
+        block: "nearest"
+      }) ?? false;
+      if (!scrolled) return void 0;
+      update({ currentTargetId: targetId, kind, boundary: null });
+      return targetId;
+    },
+    nextError() {
+      return controller.navigate("error", "next");
+    },
+    previousError() {
+      return controller.navigate("error", "previous");
+    },
+    nextWarning() {
+      return controller.navigate("warning", "next");
+    },
+    previousWarning() {
+      return controller.navigate("warning", "previous");
+    },
+    nextAnnotated() {
+      return controller.navigate("annotated", "next");
+    },
+    previousAnnotated() {
+      return controller.navigate("annotated", "previous");
+    },
+    reset() {
+      update({ boundary: null });
+    }
+  };
+  return controller;
+}
+function createShortcuts(controller) {
+  return [
+    {
+      id: `${CONSOLE_NAVIGATION_ADDON_ID}:next-error`,
+      key: "F8",
+      preventDefault: true,
+      when: ({ mode }) => mode === "console",
+      onTrigger: () => {
+        controller.nextError();
+      }
+    },
+    {
+      id: `${CONSOLE_NAVIGATION_ADDON_ID}:previous-error`,
+      key: "F8",
+      shiftKey: true,
+      preventDefault: true,
+      when: ({ mode }) => mode === "console",
+      onTrigger: () => {
+        controller.previousError();
+      }
+    },
+    {
+      id: `${CONSOLE_NAVIGATION_ADDON_ID}:next-warning`,
+      key: "ArrowDown",
+      altKey: true,
+      preventDefault: true,
+      when: ({ mode }) => mode === "console",
+      onTrigger: () => {
+        controller.nextWarning();
+      }
+    },
+    {
+      id: `${CONSOLE_NAVIGATION_ADDON_ID}:previous-warning`,
+      key: "ArrowUp",
+      altKey: true,
+      preventDefault: true,
+      when: ({ mode }) => mode === "console",
+      onTrigger: () => {
+        controller.previousWarning();
+      }
+    }
+  ];
+}
+function createConsoleNavigationAddon(options = {}) {
+  let activeHost;
+  const controller = createConsoleNavigationController({
+    getData: () => activeHost?.services.get(consoleCore.consoleServices.data),
+    getViewport: () => activeHost?.services.get(
+      consoleCore.consoleServices.viewport
+    ),
+    getAnnotations: () => activeHost?.services.get(
+      annotationLookupService
+    )
+  });
+  return {
+    id: CONSOLE_NAVIGATION_ADDON_ID,
+    controller,
+    activate(host) {
+      activeHost = host;
+      host.services.provide(consoleNavigationService, controller);
+      if (options.keyboardShortcuts !== false) {
+        for (const shortcut of createShortcuts(controller)) {
+          host.extensions.register(
+            consoleCore.consoleExtensionPoints.keyboardShortcut,
+            shortcut,
+            { id: shortcut.id }
+          );
+        }
+      }
+      return () => {
+        activeHost = void 0;
+      };
+    }
+  };
+}
+exports.CONSOLE_NAVIGATION_ADDON_ID = CONSOLE_NAVIGATION_ADDON_ID;
+exports.consoleNavigationService = consoleNavigationService;
+exports.createConsoleNavigationAddon = createConsoleNavigationAddon;
+exports.createConsoleNavigationController = createConsoleNavigationController;

package/dist/index.d.cts

@@ -0,0 +1,41 @@
+import { type ConsoleAddon, type ConsoleDataService, type ConsoleViewportService } from "@moyarich/console-core";
+export declare const CONSOLE_NAVIGATION_ADDON_ID = "@moyarich/console-addon-navigation";
+export type ConsoleNavigationKind = "error" | "warning" | "annotated";
+export type ConsoleNavigationDirection = "next" | "previous";
+export type ConsoleNavigationBoundary = "start" | "end" | null;
+export interface ConsoleNavigationState {
+    readonly currentTargetId?: string;
+    readonly kind?: ConsoleNavigationKind;
+    readonly boundary: ConsoleNavigationBoundary;
+}
+export interface ConsoleNavigationController {
+    getState(): ConsoleNavigationState;
+    subscribe(listener: () => void): () => void;
+    jumpToMessage(id: string): boolean;
+    navigate(kind: ConsoleNavigationKind, direction: ConsoleNavigationDirection): string | undefined;
+    nextError(): string | undefined;
+    previousError(): string | undefined;
+    nextWarning(): string | undefined;
+    previousWarning(): string | undefined;
+    nextAnnotated(): string | undefined;
+    previousAnnotated(): string | undefined;
+    reset(): void;
+}
+export interface ConsoleNavigationAddonOptions {
+    keyboardShortcuts?: boolean;
+}
+export interface ConsoleNavigationAddon extends ConsoleAddon {
+    readonly controller: ConsoleNavigationController;
+}
+interface ConsoleAnnotationsLookup {
+    getAnnotatedMessageIds(): readonly string[];
+}
+export declare const consoleNavigationService: import("@moyarich/console-core").ConsoleServiceToken<ConsoleNavigationController>;
+interface ConsoleNavigationDependencies {
+    getData(): ConsoleDataService | undefined;
+    getViewport(): ConsoleViewportService | undefined;
+    getAnnotations(): ConsoleAnnotationsLookup | undefined;
+}
+export declare function createConsoleNavigationController(dependencies: ConsoleNavigationDependencies): ConsoleNavigationController;
+export declare function createConsoleNavigationAddon(options?: ConsoleNavigationAddonOptions): ConsoleNavigationAddon;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+import { type ConsoleAddon, type ConsoleDataService, type ConsoleViewportService } from "@moyarich/console-core";
+export declare const CONSOLE_NAVIGATION_ADDON_ID = "@moyarich/console-addon-navigation";
+export type ConsoleNavigationKind = "error" | "warning" | "annotated";
+export type ConsoleNavigationDirection = "next" | "previous";
+export type ConsoleNavigationBoundary = "start" | "end" | null;
+export interface ConsoleNavigationState {
+    readonly currentTargetId?: string;
+    readonly kind?: ConsoleNavigationKind;
+    readonly boundary: ConsoleNavigationBoundary;
+}
+export interface ConsoleNavigationController {
+    getState(): ConsoleNavigationState;
+    subscribe(listener: () => void): () => void;
+    jumpToMessage(id: string): boolean;
+    navigate(kind: ConsoleNavigationKind, direction: ConsoleNavigationDirection): string | undefined;
+    nextError(): string | undefined;
+    previousError(): string | undefined;
+    nextWarning(): string | undefined;
+    previousWarning(): string | undefined;
+    nextAnnotated(): string | undefined;
+    previousAnnotated(): string | undefined;
+    reset(): void;
+}
+export interface ConsoleNavigationAddonOptions {
+    keyboardShortcuts?: boolean;
+}
+export interface ConsoleNavigationAddon extends ConsoleAddon {
+    readonly controller: ConsoleNavigationController;
+}
+interface ConsoleAnnotationsLookup {
+    getAnnotatedMessageIds(): readonly string[];
+}
+export declare const consoleNavigationService: import("@moyarich/console-core").ConsoleServiceToken<ConsoleNavigationController>;
+interface ConsoleNavigationDependencies {
+    getData(): ConsoleDataService | undefined;
+    getViewport(): ConsoleViewportService | undefined;
+    getAnnotations(): ConsoleAnnotationsLookup | undefined;
+}
+export declare function createConsoleNavigationController(dependencies: ConsoleNavigationDependencies): ConsoleNavigationController;
+export declare function createConsoleNavigationAddon(options?: ConsoleNavigationAddonOptions): ConsoleNavigationAddon;
+export {};

package/dist/index.js

@@ -0,0 +1,187 @@
+import { createConsoleServiceToken, consoleExtensionPoints, consoleServices } from "@moyarich/console-core";
+const CONSOLE_NAVIGATION_ADDON_ID = "@moyarich/console-addon-navigation";
+const annotationLookupService = createConsoleServiceToken(
+  "@moyarich/console-addon-annotations.controller"
+);
+const consoleNavigationService = createConsoleServiceToken(
+  `${CONSOLE_NAVIGATION_ADDON_ID}.controller`
+);
+function messageMatches(message, kind, annotations) {
+  if (!message.id) return false;
+  if (kind === "error") return message.method === "error";
+  if (kind === "warning") {
+    return message.method === "warn" || message.method === "assert";
+  }
+  return annotations.has(message.id);
+}
+function createConsoleNavigationController(dependencies) {
+  let state = Object.freeze({ boundary: null });
+  const listeners = /* @__PURE__ */ new Set();
+  const update = (next) => {
+    state = Object.freeze(next);
+    for (const listener of listeners) listener();
+  };
+  const getVisibleMessages = () => {
+    const snapshot = dependencies.getData()?.getSnapshot();
+    return snapshot?.mode === "console" ? snapshot.visible : [];
+  };
+  const controller = {
+    getState: () => state,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    jumpToMessage(id) {
+      const normalized = id.trim();
+      if (!normalized) return false;
+      const visible = getVisibleMessages();
+      if (!visible.some((message) => message.id === normalized)) return false;
+      const scrolled = dependencies.getViewport()?.scrollToMessage(normalized, {
+        block: "nearest"
+      }) ?? false;
+      if (scrolled) {
+        update({ currentTargetId: normalized, boundary: null });
+      }
+      return scrolled;
+    },
+    navigate(kind, direction) {
+      const annotations = new Set(
+        dependencies.getAnnotations()?.getAnnotatedMessageIds() ?? []
+      );
+      const candidates = getVisibleMessages().filter(
+        (message) => messageMatches(message, kind, annotations)
+      );
+      const ids = candidates.flatMap(
+        (message) => message.id ? [message.id] : []
+      );
+      if (ids.length === 0) {
+        update({
+          currentTargetId: state.currentTargetId,
+          kind,
+          boundary: direction === "next" ? "end" : "start"
+        });
+        return void 0;
+      }
+      const currentIndex = state.currentTargetId ? ids.indexOf(state.currentTargetId) : -1;
+      const targetIndex = direction === "next" ? currentIndex < 0 ? 0 : currentIndex + 1 : currentIndex < 0 ? ids.length - 1 : currentIndex - 1;
+      if (targetIndex < 0 || targetIndex >= ids.length) {
+        update({
+          currentTargetId: state.currentTargetId,
+          kind,
+          boundary: direction === "next" ? "end" : "start"
+        });
+        return void 0;
+      }
+      const targetId = ids[targetIndex];
+      const scrolled = dependencies.getViewport()?.scrollToMessage(targetId, {
+        block: "nearest"
+      }) ?? false;
+      if (!scrolled) return void 0;
+      update({ currentTargetId: targetId, kind, boundary: null });
+      return targetId;
+    },
+    nextError() {
+      return controller.navigate("error", "next");
+    },
+    previousError() {
+      return controller.navigate("error", "previous");
+    },
+    nextWarning() {
+      return controller.navigate("warning", "next");
+    },
+    previousWarning() {
+      return controller.navigate("warning", "previous");
+    },
+    nextAnnotated() {
+      return controller.navigate("annotated", "next");
+    },
+    previousAnnotated() {
+      return controller.navigate("annotated", "previous");
+    },
+    reset() {
+      update({ boundary: null });
+    }
+  };
+  return controller;
+}
+function createShortcuts(controller) {
+  return [
+    {
+      id: `${CONSOLE_NAVIGATION_ADDON_ID}:next-error`,
+      key: "F8",
+      preventDefault: true,
+      when: ({ mode }) => mode === "console",
+      onTrigger: () => {
+        controller.nextError();
+      }
+    },
+    {
+      id: `${CONSOLE_NAVIGATION_ADDON_ID}:previous-error`,
+      key: "F8",
+      shiftKey: true,
+      preventDefault: true,
+      when: ({ mode }) => mode === "console",
+      onTrigger: () => {
+        controller.previousError();
+      }
+    },
+    {
+      id: `${CONSOLE_NAVIGATION_ADDON_ID}:next-warning`,
+      key: "ArrowDown",
+      altKey: true,
+      preventDefault: true,
+      when: ({ mode }) => mode === "console",
+      onTrigger: () => {
+        controller.nextWarning();
+      }
+    },
+    {
+      id: `${CONSOLE_NAVIGATION_ADDON_ID}:previous-warning`,
+      key: "ArrowUp",
+      altKey: true,
+      preventDefault: true,
+      when: ({ mode }) => mode === "console",
+      onTrigger: () => {
+        controller.previousWarning();
+      }
+    }
+  ];
+}
+function createConsoleNavigationAddon(options = {}) {
+  let activeHost;
+  const controller = createConsoleNavigationController({
+    getData: () => activeHost?.services.get(consoleServices.data),
+    getViewport: () => activeHost?.services.get(
+      consoleServices.viewport
+    ),
+    getAnnotations: () => activeHost?.services.get(
+      annotationLookupService
+    )
+  });
+  return {
+    id: CONSOLE_NAVIGATION_ADDON_ID,
+    controller,
+    activate(host) {
+      activeHost = host;
+      host.services.provide(consoleNavigationService, controller);
+      if (options.keyboardShortcuts !== false) {
+        for (const shortcut of createShortcuts(controller)) {
+          host.extensions.register(
+            consoleExtensionPoints.keyboardShortcut,
+            shortcut,
+            { id: shortcut.id }
+          );
+        }
+      }
+      return () => {
+        activeHost = void 0;
+      };
+    }
+  };
+}
+export {
+  CONSOLE_NAVIGATION_ADDON_ID,
+  consoleNavigationService,
+  createConsoleNavigationAddon,
+  createConsoleNavigationController
+};

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@moyarich/console-addon-navigation",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "First-party stable-ID message navigation for @moyarich/console hosts.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com"
+  },
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json && node ../../../scripts/prepare-cjs-types.mjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@moyarich/console-core": "^0.2.0"
+  },
+  "devDependencies": {
+    "@moyarich/console-core": "0.2.0",
+    "typescript": "^5.9.2",
+    "vite": "^7.1.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moyarich/console.git",
+    "directory": "packages/addons/navigation"
+  },
+  "bugs": {
+    "url": "https://github.com/moyarich/console/issues"
+  },
+  "homepage": "https://github.com/moyarich/console#readme",
+  "keywords": [
+    "console",
+    "addon",
+    "navigation",
+    "errors",
+    "warnings",
+    "developer-tools"
+  ],
+  "publisher": "moyarich",
+  "author": "Moya Richards",
+  "engines": {
+    "node": ">=24"
+  },
+  "private": false
+}