@pie-players/pie-tool-dictionary 0.3.67

package/README.md

@@ -0,0 +1,102 @@
+# @pie-players/pie-tool-dictionary
+
+Dictionary panel for the PIE assessment player. Registers
+`<pie-tool-dictionary>`.
+
+## Lookup is host-supplied
+
+PIE ships no dictionary endpoint. The corpus behind a dictionary is licensed per
+programme, so a default here would bake one deployment into the package.
+
+Two ways to supply one, in precedence order:
+
+```html
+<!-- Built-in POST shaping -->
+<pie-tool-dictionary endpoint="/api/dictionary" language="en"></pie-tool-dictionary>
+```
+
+```js
+// Your own client, preferred when you already have one
+element.lookup = async ({ keyword, language, max }, signal) => ({
+  status: "ok",
+  items: [{ word: keyword, senses: [{ definition: "…" }] }],
+});
+```
+
+With neither, the panel says no service is configured rather than offering a field
+that silently fails.
+
+### Request
+
+`POST` with `{ keyword, language?, max? }`. `keyword` is normalised before it is
+sent: whitespace collapsed, surrounding punctuation stripped, internal hyphens and
+apostrophes kept. A selection longer than four words is refused without a request.
+
+### Response
+
+```json
+{
+  "entries": [
+    {
+      "word": "reason",
+      "pronunciation": "ˈriːzən",
+      "senses": [
+        { "partOfSpeech": "noun", "definition": "A cause or explanation.", "example": "…" }
+      ]
+    }
+  ]
+}
+```
+
+Unknown extra fields are ignored, so the payload can be extended without a change
+here. An entry carrying no usable definition is dropped: rendering a bare headword
+tells a learner the word exists and nothing they asked for. Zero entries is
+reported as "no entry", distinct from a service failure — a learner must not be
+told their word is not real when the network is down.
+
+The endpoint is called `same-origin`, so a route already behind the assessment's own
+session answers with no further configuration — naming the endpoint is the whole
+setup. A host authorising some other way passes a `headers` function, read per request
+so a short-lived token is fetched fresh rather than captured at mount, and one that
+wants no ambient credentials at all passes `credentials: "omit"`. Both are properties
+rather than attributes, and both are optional.
+
+## Two entry points, deliberately
+
+The `term` property is set by whatever selection affordance the host offers. Under
+`<pie-assessment-toolkit>` that is the annotation strip: selecting a word offers a
+lookup, and activating it opens this panel with the word already searched, through
+the coordinator's `requestTool`. The
+field is how a learner looks up a word without one, and it is the reason the tool
+is keyboard accessible rather than a convenience: a sighted keyboard-only learner
+cannot originate a text selection in non-editable content, because Chromium does
+not extend one with Shift+Arrow there unless caret browsing is on — an OS-level
+toggle absent on mobile. A selection-only dictionary is unreachable for them.
+
+The two entry points have to coexist within one open panel, which is what
+`termRequestId` is for. A requested term is reapplied on every sync, so the term alone
+cannot distinguish a re-render from a fresh ask: without an id, reopening the panel
+re-searches the term that opened it and discards whatever the learner typed since. A
+host setting `term` directly can leave the id unset and gets term-identity behaviour,
+which is enough to stop a re-render re-issuing.
+
+## Properties
+
+| Name       | Attribute  | Type              | Notes                                        |
+| ---------- | ---------- | ----------------- | -------------------------------------------- |
+| `visible`  | `visible`  | boolean           | Owned by the toolbar shell.                  |
+| `toolId`   | `tool-id`  | string            | Scoped tool instance id.                     |
+| `term`     | `term`     | string            | Pre-fills and searches when the panel is open. |
+| `termRequestId` | —     | string \| number  | Identity of the current `term`; optional. |
+| `endpoint` | `endpoint` | string            | Enables the built-in POST lookup.            |
+| `language` | `language` | string            | BCP-47 tag sent with the request.            |
+| `lookup`   | —          | function          | Host resolver; takes precedence over `endpoint`. |
+| `headers`  | —          | function          | Extra request headers for `endpoint`, read per request. |
+| `credentials` | —       | string            | Overrides the `same-origin` default for `endpoint`. |
+
+A `lookup` resolves to `{ status: "ok", items }`, `{ status: "empty" }`, or
+`{ status: "error", reason }` — the same three states the shared term-lookup contract
+in `@pie-players/pie-players-shared/tools/term-lookup` defines for both dictionaries.
+
+The panel renders its body only. Floating chrome — title bar, drag, resize, close —
+belongs to the toolbar shell.

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/lookup.d.ts

@@ -0,0 +1,33 @@
+import { TermLookup, TermLookupRequest, TermLookupResult } from '@pie-players/pie-players-shared/tools/term-lookup';
+/** What a host's dictionary service is asked for. */
+export type DictionaryLookupRequest = TermLookupRequest;
+export interface DictionarySense {
+    partOfSpeech?: string;
+    definition: string;
+    example?: string;
+}
+export interface DictionaryEntry {
+    word: string;
+    /** Respelling or IPA, whichever the host's corpus carries. */
+    pronunciation?: string;
+    senses: DictionarySense[];
+}
+export type DictionaryLookupResult = TermLookupResult<DictionaryEntry>;
+export type DictionaryLookup = TermLookup<DictionaryEntry>;
+/** Entries a single lookup may render before the tool stops asking for more. */
+export declare const DEFAULT_MAX_ENTRIES = 6;
+/** Read a host response into a result, ignoring unknown extra fields. */
+export declare function readLookupResponse(payload: unknown): DictionaryLookupResult;
+/**
+ * A lookup that POSTs to a host endpoint.
+ *
+ * The session cookie rides along by default, because a host is expected to put its
+ * dictionary route behind the same session boundary as the assessment; `credentials`
+ * and `headers` are there for a host that authorises some other way.
+ */
+export declare function createEndpointLookup(args: {
+    endpoint: string;
+    headers?: () => Promise<Record<string, string>> | Record<string, string>;
+    credentials?: RequestCredentials;
+    fetchImpl?: typeof fetch;
+}): DictionaryLookup;