@pie-players/pie-assessment-toolkit 0.3.67 → 0.3.68

package/dist/services/tool-request.js

@@ -0,0 +1,127 @@
+/**
+ * Tool open requests.
+ *
+ * A surface that acts on the learner's current selection has to hand that selection
+ * to a tool it does not mount. The annotation strip is the case PIE ships: it is a
+ * section-scoped singleton in its own shadow root, and the tool it opens is mounted
+ * by a toolbar under a scoped instance id the strip cannot construct.
+ *
+ * Resolution is a claim, not a broadcast. Each toolbar registers as the target for its
+ * placement level, and a request reaches exactly one: the first target that currently
+ * hosts the tool, preferring section scope. A broadcast would open a panel in every
+ * toolbar whose scope contains the selection, which in a section player is the item
+ * card's toolbar and the section's both.
+ *
+ * `params` reaches the tool through the same seam a host-registered context resolver
+ * feeds, so receiving a request costs a tool nothing: whatever already reads
+ * `getToolRenderParams` sees it.
+ *
+ * Core names no capability. The requester supplies the tool id, which is why the
+ * pairing of a selection action to a dictionary lives in the composition layer.
+ */
+/** Level a request resolves against when the requester names none. */
+export const DEFAULT_TOOL_REQUEST_LEVEL = "section";
+/**
+ * Registry of the toolbars a request can reach.
+ *
+ * Insertion order is the tie-break within a level, so a target registered while an
+ * earlier one is still mounted does not displace it.
+ */
+export class ToolRequestRegistry {
+    targets = new Set();
+    changeListeners = new Set();
+    registerTarget(target) {
+        this.targets.add(target);
+        this.notifyChange();
+        return () => {
+            if (!this.targets.delete(target))
+                return;
+            this.notifyChange();
+        };
+    }
+    /**
+     * Whether a request for this tool would reach a toolbar.
+     *
+     * A surface asks before offering the affordance: a button that silently does
+     * nothing is worse than an absent one, and availability moves with policy —
+     * hence {@link onTargetsChange}.
+     */
+    canRequest(toolId, level) {
+        return this.findTarget(toolId, level) !== null;
+    }
+    /** Returns whether a target claimed the request. */
+    request(request) {
+        const target = this.findTarget(request.toolId, request.level);
+        if (!target)
+            return false;
+        try {
+            target.open(request.toolId, request.params);
+        }
+        catch (error) {
+            console.error(`[ToolRequestRegistry] Target failed to open "${request.toolId}":`, error);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Fires when a toolbar registers or unregisters.
+     *
+     * Not when a registered toolbar's own visible set changes: `hostsTool` is read
+     * live, so a caller re-asking `canRequest` gets the current answer. A surface
+     * that needs to notice a policy change should also follow the policy signal it
+     * already has.
+     */
+    onTargetsChange(listener) {
+        this.changeListeners.add(listener);
+        return () => {
+            this.changeListeners.delete(listener);
+        };
+    }
+    /**
+     * An explicit level is a constraint; the default is a preference.
+     *
+     * Falling back off `"section"` is what lets a host place a tool at item scope only
+     * and still have a section-scoped gateway reach it. Requesting a level explicitly
+     * does not fall back, because a requester that named one meant it.
+     */
+    findTarget(toolId, level) {
+        const preferred = this.findTargetAtLevel(toolId, level ?? DEFAULT_TOOL_REQUEST_LEVEL);
+        if (preferred || level !== undefined)
+            return preferred;
+        for (const target of this.targets) {
+            if (target.level === DEFAULT_TOOL_REQUEST_LEVEL)
+                continue;
+            if (this.hostsTool(target, toolId))
+                return target;
+        }
+        return null;
+    }
+    findTargetAtLevel(toolId, level) {
+        for (const target of this.targets) {
+            if (target.level !== level)
+                continue;
+            if (this.hostsTool(target, toolId))
+                return target;
+        }
+        return null;
+    }
+    hostsTool(target, toolId) {
+        try {
+            return target.hostsTool(toolId) === true;
+        }
+        catch (error) {
+            console.warn(`[ToolRequestRegistry] Target at level "${target.level}" failed the host check for "${toolId}":`, error);
+            return false;
+        }
+    }
+    notifyChange() {
+        for (const listener of this.changeListeners) {
+            try {
+                listener();
+            }
+            catch (error) {
+                console.warn("[ToolRequestRegistry] Target change listener threw:", error);
+            }
+        }
+    }
+}

package/dist/services/toolbar-items.d.ts

@@ -3,6 +3,12 @@ export interface ToolbarItemBase {
     label: string;
     ariaLabel?: string;
     icon?: string;
+    /**
+     * FontAwesome icon name, opting this item into `<nds-icon-button>` rendering
+     * where the host enables NDS icons. Set by a tool registration's button
+     * definition, or by a host contributing its own button.
+     */
+    faIconName?: string;
     tooltip?: string;
     active?: boolean;
     disabled?: boolean;

package/dist/tools/client.d.ts

@@ -8,7 +8,6 @@
  * '@pie-players/pie-assessment-toolkit' to ensure
  * they don't accidentally pull in server-side dependencies.
  */
-export { DesmosCalculatorProvider } from "./calculators/desmos-provider.js";
 export { COMMON_LIBRARIES, LibraryLoaderImpl, libraryLoader, } from "./library-loader.js";
 export { ResponseDiscoveryServiceImpl, responseDiscovery, } from "./response-discovery.js";
 export * from "./types.js";

package/dist/tools/client.js

@@ -8,8 +8,6 @@
  * '@pie-players/pie-assessment-toolkit' to ensure
  * they don't accidentally pull in server-side dependencies.
  */
-// Calculator providers (client-safe, have SSR guards)
-export { DesmosCalculatorProvider } from "./calculators/desmos-provider.js";
 // Library loader (client-safe, has SSR guards)
 export { COMMON_LIBRARIES, LibraryLoaderImpl, libraryLoader, } from "./library-loader.js";
 // Response discovery (client-safe, browser-only)

package/dist/tools/internal.d.ts

@@ -20,9 +20,15 @@
  */
 export type { HostedToolContext, HostedToolSize, ResolvedToolContext, ToolActivation, ToolContentDependency, ToolContentDependencyContext, ToolModuleLoader, ToolProviderDescriptor, ToolRegistration, ToolRenderElement, ToolSingletonScope, ToolSurfaceRenderContext, ToolSurfaceRenderResult, ToolSurfaceServices, ToolToolbarButtonDefinition, ToolToolbarRenderResult, ToolWindowShellConfig, ToolbarContext, } from "../services/ToolRegistry.js";
 export { ToolRegistry } from "../services/ToolRegistry.js";
+export { resolveToolRegistrationName } from "../services/ToolRegistry.js";
 export type { CatalogOwnerCard, CatalogOwnerSnapshot, } from "../services/AccessibilityCatalogResolver.js";
+export type { ToolSelectionAction, ToolSelectionContext, } from "../services/selection-action.js";
+export type { ToolOpenRequest, ToolRequestTarget, } from "../services/tool-request.js";
+export { resolveFallbackToolIcon, TOOL_FALLBACK_ICONS, } from "../services/tool-icons.js";
 export type { ContentCapabilityPhase, ContentCapabilityPolicy, ResolveContentCapabilitiesArgs, ResolvedContentCapability, } from "./content-capability-resolution.js";
 export { resolveContentCapabilities } from "./content-capability-resolution.js";
+export type { ToolSurfaceHost, ToolSurfaceHostInput, ToolSurfaceHostOptions, ToolSurfaceHostSnapshot, ToolSurfaceScope, } from "./tool-surface-host.js";
+export { createToolSurfaceHost } from "./tool-surface-host.js";
 export type { ToolContext, ToolLevel } from "../services/tool-context.js";
 export { hasChoiceInteraction, hasMathContent, hasReadableText, hasScienceContent, } from "../services/tool-context.js";
 export { createScopedToolId } from "../services/tool-instance-id.js";

package/dist/tools/internal.js

@@ -19,7 +19,14 @@
  * point — the mechanism is the same one our own registrations use.
  */
 export { ToolRegistry } from "../services/ToolRegistry.js";
+// A registration's own display name in the interface locale. A tool window's
+// title is the registration's name, so the shell needs the same `nameKey`-then-
+// `name` precedence the toolbar uses rather than the raw English field.
+export { resolveToolRegistrationName } from "../services/ToolRegistry.js";
+// So a gateway button and the toolbar button for the same tool draw one icon.
+export { resolveFallbackToolIcon, TOOL_FALLBACK_ICONS, } from "../services/tool-icons.js";
 export { resolveContentCapabilities } from "./content-capability-resolution.js";
+export { createToolSurfaceHost } from "./tool-surface-host.js";
 export { hasChoiceInteraction, hasMathContent, hasReadableText, hasScienceContent, } from "../services/tool-context.js";
 // Scoped tool instance ids, so two placements of one tool do not share state.
 export { createScopedToolId } from "../services/tool-instance-id.js";

package/dist/tools/tool-surface-host.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Headless host for capabilities that render into a renderer's surfaces.
+ *
+ * The interface deliberately exposes only current input, a two-boolean snapshot,
+ * and teardown. Discovery, policy/catalog invalidation, content resolution, lazy
+ * loading, DOM reconciliation, error isolation, and registry observation stay
+ * inside this module. Svelte callers are geometry adapters over this seam.
+ *
+ * It lives here rather than in `section-player`, where it was written, because a
+ * second renderer now opens a surface: the annotation toolbar hosts the
+ * capabilities that act on a text selection. Two copies of mount/reconcile/
+ * registry-observation would drift, and the drift would be invisible until one
+ * renderer stopped honouring the grant-AND-content rule. Nothing about the module
+ * was section-shaped — it already imported only from this package — so the move
+ * is a relocation, not a rewrite. The one thing that *was* section-shaped is the
+ * name it reported errors under, which is now {@link ToolSurfaceHostOptions.hostLabel}.
+ */
+import type { CatalogOwnerContext } from "../services/catalog-owner.js";
+import type { ToolRegistry, ToolSurfaceServices } from "../services/ToolRegistry.js";
+export type ToolSurfaceScope = {
+    kind: "content";
+    ownerContext: CatalogOwnerContext;
+} | {
+    kind: "section";
+    assessmentId: string;
+    sectionId: string;
+};
+export interface ToolSurfaceHostInput {
+    anchor: HTMLElement | null;
+    surface: string;
+    registry: ToolRegistry | null;
+    services: ToolSurfaceServices;
+    scope: ToolSurfaceScope;
+}
+export interface ToolSurfaceHostSnapshot {
+    /** At least one capability is eligible, including one still loading. */
+    mountable: boolean;
+    /** At least one capability successfully mounted an element. */
+    occupied: boolean;
+}
+export interface ToolSurfaceHost {
+    update(input: ToolSurfaceHostInput): void;
+    destroy(): void;
+}
+export interface ToolSurfaceHostOptions {
+    /**
+     * Which renderer this host belongs to, for framework-error `source` and console
+     * warnings — `"pie-section-player"`, `"pie-tool-annotation-toolbar"`.
+     *
+     * A warning that named the module but not its renderer would be unactionable
+     * now that two of them mount surfaces: the same `render` failure on the same
+     * `toolId` means different things depending on which surface asked.
+     */
+    hostLabel: string;
+}
+/** Create one lifecycle owner for one host surface anchor. */
+export declare function createToolSurfaceHost(onSnapshot: (snapshot: ToolSurfaceHostSnapshot) => void, options: ToolSurfaceHostOptions): ToolSurfaceHost;