@pie-players/pie-assessment-toolkit 0.3.66 → 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/content-capability-resolution.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Whether a content capability has anything to show, for one entity and one
+ * profile.
+ *
+ * Two independent halves, and a capability is in play only when both answer yes:
+ * policy granted one of its support ids, and its own `requiresAuthoredContent`
+ * found the resource in this entity's catalogs. Neither implies the other — a
+ * learner with an accommodation still sees nothing on an item carrying no
+ * resource, and an item carrying one shows nothing to a learner without the
+ * grant.
+ *
+ * Policy answers in three states rather than two, because a host gate is not the
+ * absence of a grant: `resolvesWithoutGrant` lets a capability answer from the
+ * content when nobody was granted anything, and a host that switched the
+ * capability off must not be read as nobody having spoken. Resolution order is
+ * denial, then grant, then the content exception.
+ *
+ * It lives here, data-only and DOM-free, because two renderers ask it. The
+ * section player asks continuously: policy and catalogs both change under a
+ * mounted card, and it re-resolves to reconcile what is on screen. Print asks
+ * once — one learner, one profile, decided before the page exists, with nothing
+ * to toggle. A second implementation for the one-shot case would be two
+ * renderers disagreeing about the same card, which is the failure this exists to
+ * prevent.
+ *
+ * Capability-neutral, and gated as such: nothing here names a support id, a
+ * catalog type, or a surface. The caller passes the registrations and the slot,
+ * a capability interprets its own cards, and the resolution owns only the
+ * two-halves rule and its one documented exception.
+ */
+import type { ToolRegistration } from "../services/ToolRegistry.js";
+import type { CatalogOwnerSnapshot } from "../services/AccessibilityCatalogResolver.js";
+/** What policy answered about one feature id. */
+export type ContentCapabilityPolicy = {
+    outcome: "granted";
+    /** The support id that was granted — a capability may declare several. */
+    featureId: string;
+    /** Feature parameters carried by the decision, if any. */
+    parameters?: unknown;
+}
+/**
+ * No source granted it and none denied it. A capability declaring
+ * {@link ToolRegistration.resolvesWithoutGrant} may still answer from the
+ * content: silence is what an authored-presentation alternate looks like,
+ * since no profile speaks for one either way.
+ */
+ | {
+    outcome: "silent";
+}
+/**
+ * A host gate denied it — the off switch, not the absence of a grant. It
+ * outranks `resolvesWithoutGrant`, because a host saying a capability has no
+ * place in this delivery is a statement authored content cannot overrule.
+ */
+ | {
+    outcome: "denied";
+};
+/** Which half of a capability's resolution failed. */
+export type ContentCapabilityPhase = "policy" | "content";
+/** A capability that is in play, and everything its renderer needs to mount it. */
+export interface ResolvedContentCapability {
+    registration: ToolRegistration;
+    /**
+     * The granted support id, or `""` when the capability resolved without a
+     * grant. Passed through to the render context unchanged, so a capability that
+     * serves both an authored-presentation case and an accommodation can still
+     * tell them apart at render time.
+     */
+    featureId: string;
+    parameters?: unknown;
+    /** Whatever the capability's own `resolve` returned; never inspected here. */
+    content: unknown;
+}
+export interface ResolveContentCapabilitiesArgs {
+    /**
+     * The capabilities to consider. A caller with a registry passes
+     * `getToolsBySurface(surface)`, which is what keeps a renderer from naming
+     * one.
+     */
+    registrations: readonly ToolRegistration[];
+    /** The entity's cards, or `null` when no resolver is available. */
+    catalogs: CatalogOwnerSnapshot | null;
+    /**
+     * Policy's answer about one feature id, in three states.
+     *
+     * Granting requires a documented need, so an unconfigured feature is
+     * `"silent"`, never granted. What the third state buys is the distinction
+     * `"silent"` cannot carry: a host that switched the capability off said
+     * something, and a capability allowed to answer from content alone must not
+     * treat that as nobody having spoken.
+     */
+    policyFor: (featureId: string) => ContentCapabilityPolicy;
+    /**
+     * Report a capability that threw. It is dropped either way; this is how a
+     * caller surfaces it as its own recoverable warning rather than letting one
+     * capability's defect reach the learner's content.
+     */
+    onError?: (registration: ToolRegistration, phase: ContentCapabilityPhase, error: unknown) => void;
+}
+/**
+ * The capabilities in play, in the order the caller offered them.
+ *
+ * Registry order is preserved so a renderer's slot ordering stays a property of
+ * the registry rather than of resolution timing.
+ */
+export declare function resolveContentCapabilities(args: ResolveContentCapabilitiesArgs): ResolvedContentCapability[];

package/dist/tools/content-capability-resolution.js

@@ -0,0 +1,136 @@
+/**
+ * Whether a content capability has anything to show, for one entity and one
+ * profile.
+ *
+ * Two independent halves, and a capability is in play only when both answer yes:
+ * policy granted one of its support ids, and its own `requiresAuthoredContent`
+ * found the resource in this entity's catalogs. Neither implies the other — a
+ * learner with an accommodation still sees nothing on an item carrying no
+ * resource, and an item carrying one shows nothing to a learner without the
+ * grant.
+ *
+ * Policy answers in three states rather than two, because a host gate is not the
+ * absence of a grant: `resolvesWithoutGrant` lets a capability answer from the
+ * content when nobody was granted anything, and a host that switched the
+ * capability off must not be read as nobody having spoken. Resolution order is
+ * denial, then grant, then the content exception.
+ *
+ * It lives here, data-only and DOM-free, because two renderers ask it. The
+ * section player asks continuously: policy and catalogs both change under a
+ * mounted card, and it re-resolves to reconcile what is on screen. Print asks
+ * once — one learner, one profile, decided before the page exists, with nothing
+ * to toggle. A second implementation for the one-shot case would be two
+ * renderers disagreeing about the same card, which is the failure this exists to
+ * prevent.
+ *
+ * Capability-neutral, and gated as such: nothing here names a support id, a
+ * catalog type, or a surface. The caller passes the registrations and the slot,
+ * a capability interprets its own cards, and the resolution owns only the
+ * two-halves rule and its one documented exception.
+ */
+/** The support ids a capability answers to, defaulting to its own id. */
+const supportIdsOf = (registration) => registration.pnpSupportIds?.length
+    ? registration.pnpSupportIds
+    : [registration.toolId];
+/**
+ * Everything policy has to say about one capability: a grant, an off switch, or
+ * nothing.
+ *
+ * Denial is checked ahead of a grant on each id rather than after the scan,
+ * because the two can only disagree when a host blocked one of a capability's ids
+ * while a profile granted another, and there the off switch is the later, more
+ * specific statement about this delivery.
+ *
+ * A host gate names *capabilities*, so the tool id is probed too when it is not
+ * already a declared support id — otherwise a capability whose id differs from
+ * its support ids would slip a host block. That probe is gate-only: a grant on
+ * the tool id is ignored, or blocking would double as a second way to switch a
+ * capability on.
+ */
+function policyForCapability(registration, args) {
+    const supportIds = supportIdsOf(registration);
+    for (const supportId of supportIds) {
+        const answer = args.policyFor(supportId);
+        if (answer.outcome === "denied")
+            return { grant: null, denied: true };
+        if (answer.outcome === "granted")
+            return { grant: answer, denied: false };
+    }
+    if (supportIds.includes(registration.toolId)) {
+        return { grant: null, denied: false };
+    }
+    return {
+        grant: null,
+        denied: args.policyFor(registration.toolId).outcome === "denied",
+    };
+}
+function resolveOne(registration, args) {
+    let grant = null;
+    try {
+        const answer = policyForCapability(registration, args);
+        // Nothing reopens a host denial — not a grant it outranked, and not the
+        // content exception below.
+        if (answer.denied)
+            return null;
+        grant = answer.grant;
+    }
+    catch (error) {
+        args.onError?.(registration, "policy", error);
+        return null;
+    }
+    // The exception, and the only one: a capability whose content can declare
+    // itself authored presentation is consulted even when policy granted nothing,
+    // because an item family designed to be delivered with its alternate on screen
+    // is not an accommodation and no profile grants or revokes it. The capability
+    // still decides — `granted` is how it tells the two cases apart.
+    if (!grant && !registration.resolvesWithoutGrant)
+        return null;
+    if (!registration.requiresAuthoredContent) {
+        // Nothing to look for in the content, so the grant is the whole answer. A
+        // capability reaching here without one has no second half to supply it.
+        if (!grant)
+            return null;
+        return {
+            registration,
+            featureId: grant.featureId,
+            parameters: grant.parameters,
+            content: null,
+        };
+    }
+    const context = {
+        featureId: grant?.featureId ?? "",
+        parameters: grant?.parameters,
+        catalogs: args.catalogs,
+        granted: Boolean(grant),
+    };
+    let content;
+    try {
+        content = registration.requiresAuthoredContent.resolve(context);
+    }
+    catch (error) {
+        args.onError?.(registration, "content", error);
+        return null;
+    }
+    // Absent content is the honest answer to "is there anything to show", not a
+    // failure: the item carries no resource for this capability.
+    if (content === null || content === undefined)
+        return null;
+    return {
+        registration,
+        featureId: context.featureId,
+        parameters: context.parameters,
+        content,
+    };
+}
+/**
+ * The capabilities in play, in the order the caller offered them.
+ *
+ * Registry order is preserved so a renderer's slot ordering stays a property of
+ * the registry rather than of resolution timing.
+ */
+export function resolveContentCapabilities(args) {
+    return args.registrations.flatMap((registration) => {
+        const resolved = resolveOne(registration, args);
+        return resolved ? [resolved] : [];
+    });
+}

package/dist/tools/internal.d.ts

@@ -20,7 +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,6 +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;