@octolearn/training-ui 0.1.0 → 0.2.0

package/dist/types/base-element.d.ts

@@ -8,6 +8,8 @@ import { type TrainingLanguage, type TrainingStrings } from './i18n/strings';
  *   changes; to switch the language at runtime, set it on the element.
  * - `strings` (property): replaces single texts, e.g. `{ check: 'Prüfen' }`.
  * - `theme` (attribute): `dark` for dark surfaces.
+ * - `short` (reflected attribute, set by the element itself): the visible area is short, e.g. a phone's on-screen keyboard
+ *   covers half of it. The elements then use a compact layout (`:host([short])` in their styles).
  *
  * Templates start with `<div class="root" lang=…>` (see baseStyles), which also tells screen readers the language.
  */
@@ -18,6 +20,11 @@ export declare class OctolearnElement extends LitElement {
     language?: string;
     strings?: Partial<TrainingStrings>;
     theme?: 'light' | 'dark';
+    /** The visible area is short (on-screen keyboard open): compact layout. Follows `window.visualViewport`. */
+    short: boolean;
+    private endViewportWatch?;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
     protected get resolvedLanguage(): TrainingLanguage;
     /** The texts in the element's language, with the page's overrides. */
     protected get t(): TrainingStrings;

package/dist/types/d-icons.d.ts

@@ -3,7 +3,7 @@ import { type TemplateResult } from 'lit';
  * The stroke icons of design D, drawn on the canvas as inline SVG (not Font Awesome). Decorative: hidden from screen
  * readers; the button around them carries the name.
  */
-export type DIconName = 'speaker' | 'speaker-quiet' | 'check' | 'cross' | 'arrow';
+export type DIconName = 'speaker' | 'speaker-quiet' | 'check' | 'cross' | 'arrow' | 'zoom';
 /** A D icon of the given size in px; strokes in currentColor. */
 export declare function dIcon(name: DIconName, size: number, strokeWidth?: number): TemplateResult;
 /** D's five-point star (24×24 box). */

package/dist/types/elements/card.d.ts

@@ -6,7 +6,8 @@ export type CardState = 'question' | 'right' | 'wrong';
  * `<octolearn-card>`: design D's question card. Lined paper, a coloured band on top (orange while asking, green after a
  * right answer, red after a wrong one), a header with the octolearn logo, the format label ("DIKTAT"), an optional chip
  * ("Deutsch → Englisch") and the progress stars, and Inkie peeking over the top edge while a question is open. The
- * question goes into the default slot.
+ * question goes into the default slot. While the visible area is short (`short`: a phone's keyboard is open) the header
+ * and Inkie step aside and the card gets tighter.
  *
  * ```html
  * <octolearn-card label="Diktat" current="3" total="5">

package/dist/types/elements/dictation-question.d.ts

@@ -9,9 +9,11 @@ export declare const SLOW_RATE = 0.7;
  *
  * The element reads the word aloud itself when the question arrives and on the buttons, using the browser's speech
  * synthesis. A page with its own speech output calls `preventDefault()` on `octolearn-speak` / `octolearn-stop`. If the
- * browser blocks speech until the first tap, a "Abspielen" hint appears.
+ * browser blocks speech until the first tap, a "Abspielen" hint appears. The word is read in its language (the content's
+ * `sourceLanguage`, else German); if the device has no voice for it, a note says so instead of letting another
+ * language's voice mispronounce it.
  *
- * @fires octolearn-speak - cancelable, `{ text, reason: 'auto' | 'repeat' | 'slow', rate? }`
+ * @fires octolearn-speak - cancelable, `{ text, reason: 'auto' | 'repeat' | 'slow', lang, rate? }`
  * @fires octolearn-stop - cancelable
  * @fires octolearn-settings - "Einstellungen" pressed (the button shows only with the `settings` attribute)
  * @fires octolearn-answer - `{ answer, dontKnow? }`
@@ -28,8 +30,15 @@ export declare class OctolearnDictationQuestion extends QuestionElement {
     /** Reads the word aloud, as the listen button does. */
     speak(reason?: SpeakEventDetail['reason']): void;
     stop(): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
     protected updated(changed: PropertyValues<this>): void;
     render(): TemplateResult | typeof nothing;
+    /** The word's language: the content's, else German (octolearn's dictations are German). */
+    private get wordLanguage();
+    /** Shown once the browser's voice list is known and has no voice for the word's language. */
+    private noVoiceHint;
+    private readonly handleVoicesChanged;
     private controls;
     private repeat;
     private slow;

package/dist/types/elements/picture-question.d.ts

@@ -1,15 +1,27 @@
-import { nothing, type TemplateResult } from 'lit';
+import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 import { QuestionElement } from './question-parts';
 /**
  * `<octolearn-picture-question>`: design D's "Bilderrätsel": "Was siehst du auf dem Bild?", the picture in a cream frame
  * left of "Schreib das Wort" and the field (above it on narrow screens), or above the answer tiles. `content.question` is
- * the picture's URL.
+ * the picture's URL. Tapping the picture shows it large in a modal dialog (closed by a tap anywhere, the close button or
+ * Escape); while it is open, the keys don't reach the answer (no number key picks a choice behind it).
  *
  * @fires octolearn-answer - `{ answer, dontKnow? }`
  */
 export declare class OctolearnPictureQuestion extends QuestionElement {
     static styles: (import("lit").CSSResult | import("lit").CSSResultGroup[])[];
+    /** The large picture is showing. */
+    private zoomed;
+    private zoomDialog?;
+    /** Shows the picture large (same as tapping it). */
+    enlargePicture(): void;
+    /** Closes the large picture. */
+    closePicture(): void;
+    protected willUpdate(changed: PropertyValues<this>): void;
+    protected updated(changed: PropertyValues<this>): void;
     render(): TemplateResult | typeof nothing;
+    private onZoomKeydown;
+    private onZoomClosed;
 }
 declare global {
     interface HTMLElementTagNameMap {

package/dist/types/elements/question-answer.d.ts

@@ -9,8 +9,6 @@ import { QuestionElement } from './question-parts';
  * @fires octolearn-speak - cancelable, `{ text, reason: 'read', lang }`
  */
 export declare class OctolearnQuestionAnswer extends QuestionElement {
-    noAutofocus: boolean;
-    protected willUpdate(): void;
     render(): TemplateResult | typeof nothing;
     /** A line above tiles or a Wortfragment, saying what to do. */
     private instruction;

package/dist/types/elements/question-parts.d.ts

@@ -8,10 +8,13 @@ import type { FlashcardRevealer } from './flashcard';
 /** The look shared by the question elements in design D. */
 export declare const questionStyles: import("lit").CSSResult;
 /**
- * Base of the question elements. A new `content` is a new question: the answer field is emptied, and with
- * `autofocusAnswer` the cursor goes into it. `speak()` reads text aloud through a cancelable `octolearn-speak` event, so a
+ * Base of the question elements. A new `content` is a new question: the answer field is emptied and the cursor goes into
+ * it (the first tile or button without a field); `no-autofocus` leaves the focus where it is. `speak()` reads text aloud through a cancelable `octolearn-speak` event, so a
  * page with its own voice output can take over; otherwise the built-in SpeechController speaks and, if the browser
  * blocks speech until the first tap, a "Abspielen" hint appears.
+ *
+ * While the visible area is short (a phone's keyboard is open) and the learner is in the answer, the question scrolls the
+ * card around it (or itself) to the top of what is visible, so the word or picture isn't hidden above the field.
  */
 export declare class QuestionElement extends OctolearnElement {
     static styles: import("lit").CSSResultGroup[];
@@ -21,8 +24,9 @@ export declare class QuestionElement extends OctolearnElement {
     noKeys: boolean;
     /** Fetches the answer of a Karteikarte (octolearn's web app), e.g. `content => session.revealFlashcard(content)`. */
     revealFlashcard?: FlashcardRevealer;
+    /** Leave the focus where it is when a new question arrives (e.g. a game that keeps the keyboard). */
+    noAutofocus: boolean;
     protected needsGesture: boolean;
-    protected autofocusAnswer: boolean;
     protected readonly speech: import("..").SpeechController;
     connectedCallback(): void;
     disconnectedCallback(): void;
@@ -31,6 +35,10 @@ export declare class QuestionElement extends OctolearnElement {
     protected playPending(): void;
     protected playHint(t: TrainingStrings): TemplateResult | typeof nothing;
     protected updated(changed: PropertyValues<this>): void;
+    /** After the field took the focus (autofocus waits for the field's own update) and the layout settled. */
+    private revealWhenFocused;
+    /** The `<octolearn-card>` around the question, across shadow roots. */
+    private closestCard;
     /** Puts the focus on the answer: the field, the first tile or the first button (e.g. when an overlay opens). */
     focusAnswer(): void;
 }

package/dist/types/elements/text-answer.d.ts

@@ -14,6 +14,10 @@ import { OctolearnElement } from '../base-element';
  * With `hint` (a Wortfragment, OC-126: "S____e") the known letters stand big above the field, each missing one a dashed
  * box (design D's Lückenwort look); screen readers hear "Hinweis: 6 Zeichen, beginnt mit „S“, endet mit „e“.".
  *
+ * While the visible area is short (`short`: a phone's keyboard covers half the screen) it takes as little height as it
+ * can: a round send button at the end of the field instead of "Fertig", the visible label as placeholder, the picture
+ * small left of the field and "Weiß ich nicht" as a small text button below.
+ *
  * @slot before - only with variant="box": shown left of the box
  * @slot media - only with variant="media": shown left of the field
  * @fires octolearn-answer - `{ answer, dontKnow? }`
@@ -38,6 +42,9 @@ export declare class OctolearnTextAnswer extends OctolearnElement {
     /** Puts the cursor into the field. */
     focus(options?: FocusOptions): void;
     render(): TemplateResult;
+    private renderActions;
+    /** Short: the send button is in the field; only "Weiß ich nicht", small, below it. */
+    private renderShortActions;
     private renderHint;
     private onInput;
     private onSubmit;

package/dist/types/i18n/strings.d.ts

@@ -15,6 +15,8 @@ export interface TrainingStrings {
     stop: string;
     playHintMessage: string;
     playHintButton: string;
+    /** {language} */
+    noVoiceMessage: string;
     feedbackCorrect: string;
     feedbackWrong: string;
     yourAnswer: string;
@@ -59,6 +61,9 @@ export interface TrainingStrings {
     pictureAlt: string;
     pictureCaptionVocabulary: string;
     pictureCaptionRiddle: string;
+    /** the button on the picture that shows it large */
+    enlargePicture: string;
+    closePicture: string;
     enterPictureVocabulary: string;
     enterPictureRiddle: string;
     arithmeticHeading: string;

package/dist/types/index.d.ts

@@ -29,3 +29,4 @@ export { createThirdPartyTransport, type ThirdPartyTransportOptions } from './se
 export { TrainingSession, type AnswerOutcome, type PairOutcome, type RoundProgress, type SessionState, type TrainingSessionOptions, } from './session/training-session';
 export { TransportError, type AnswerEvaluation, type TodaysStatistic, type Transport } from './session/transport';
 export { getSpeechController, MAX_RATE, MIN_RATE, SpeechController, type SpeakOptions, type SpeakResult, type SpeechControllerOptions, } from './speech';
+export { getViewportWatcher, SHORT_VIEWPORT_PX, ViewportWatcher } from './viewport';

package/dist/types/speech.d.ts

@@ -1,6 +1,8 @@
 /** The range of octolearn's speed slider. */
 export declare const MIN_RATE = 0.5;
 export declare const MAX_RATE = 1.5;
+/** How long a word waits for the browser's voice list before it is spoken with the language alone. */
+export declare const VOICE_WAIT_MS = 1000;
 /**
  * - `spoken`: speaking (or queued until the browser has loaded its voices)
  * - `blocked`: the browser wants a user gesture first (autoplay policy); call playPending() from a click
@@ -10,19 +12,23 @@ export type SpeakResult = 'spoken' | 'blocked' | 'unavailable';
 export interface SpeakOptions {
     /** Speed for this request only, e.g. 0.7 for "Langsam anhören"; default: the learner's speed. */
     rate?: number;
-    /** Language of the text (e.g. "en" for a vocabulary word); a voice of that language is used if there is one. */
+    /** Language of the text (e.g. "en" for a vocabulary word); default: the controller's `preferredLanguage`. */
     lang?: string;
 }
 export interface SpeechControllerOptions {
     /** Voice names tried first when the learner hasn't chosen one. Default: Google Deutsch. */
     preferredVoices?: readonly string[];
-    /** Without a preferred or stored voice, the first voice of this language (default `de`), else the first voice. */
+    /** Language of text spoken without a `lang` (default `de`); also the default voice of a settings dialog. */
     preferredLanguage?: string;
 }
 /**
  * Reads dictation words aloud with the Web Speech API. Ported from octolearn's training page: the voice and speed the
  * learner chose are remembered, the newest request wins, and a browser that blocks speech until the first user gesture
  * keeps the text until playPending() is called from one.
+ *
+ * A text is only read by a voice of its language: the learner's voice if it speaks that language, else a preferred
+ * voice or the first voice of it. Without one the browser gets only the language, never a voice of another language
+ * (left to itself, Chrome takes the voice of the browser's language, so German words came out English).
  */
 export declare class SpeechController {
     voices: SpeechSynthesisVoice[];
@@ -31,6 +37,7 @@ export declare class SpeechController {
     private pending;
     private requestId;
     private connections;
+    private voiceWait;
     private readonly preferredVoices;
     private readonly preferredLanguage;
     constructor(options?: SpeechControllerOptions);
@@ -41,11 +48,21 @@ export declare class SpeechController {
     speak(input: string | null | undefined, options?: SpeakOptions): SpeakResult;
     /** Speaks the text that was blocked; call it from a click. */
     playPending(): void;
+    /**
+     * Whether the browser has a voice for the language (default: `preferredLanguage`); `undefined` while its voice list
+     * is still loading or without speech synthesis.
+     */
+    hasVoiceFor(lang?: string): boolean | undefined;
     stop(): void;
     /** Remembers the voice (by name; the voice objects change when the browser reloads its list) and the speed. */
     choose(voice: SpeechSynthesisVoice | null, rate?: number): void;
     private readonly handleVoicesChanged;
+    /** Speaks the pending text now if the voice list is known, else on voiceschanged or after VOICE_WAIT_MS. */
+    private flushWhenVoicesKnown;
+    private stopWaitingForVoices;
+    /** Reads the browser's voice list; false while it is still empty. */
     private refreshVoices;
+    /** A voice that speaks the language: the learner's, else a preferred one, else the first; never one of another language. */
     private voiceFor;
     private preferredVoice;
     private flushPending;

package/dist/types/styles/d-parts.d.ts

@@ -7,6 +7,7 @@
  * - `.prompt` the handwritten instruction, `.label` the uppercase format label
  * - `.keys-only` for hints about keys ("Enter drücken oder"), hidden on touch screens
  * Sizes are D's at 1280 px. Below 560 px of width (the element's `.root`, or the card around it) they shrink to
- * phone sizes; elements that use these parts set `container-type: inline-size` on their `.root`.
+ * phone sizes; elements that use these parts set `container-type: inline-size` on their `.root`. While the visible area
+ * is short (`:host([short])`, a phone's keyboard is open) they shrink further.
  */
 export declare const dParts: import("lit").CSSResult;

package/dist/types/viewport.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Is the visible part of the page short, e.g. because a phone's on-screen keyboard covers half of it? CSS can't tell:
+ * iOS Safari and current Android Chrome shrink only the visual viewport when the keyboard opens, not the layout viewport
+ * that `vh` and media queries see. So the elements ask `window.visualViewport`; while it is short they switch to a
+ * compact layout (attribute `short`, see OctolearnElement).
+ */
+/** Below this height (CSS px, at zoom 1) the visible area counts as short. A phone with its keyboard open has ~300–400. */
+export declare const SHORT_VIEWPORT_PX = 520;
+type Listener = (short: boolean) => void;
+/** Watches `window.visualViewport` while anything listens. One per page: see getViewportWatcher(). */
+export declare class ViewportWatcher {
+    private readonly listeners;
+    private viewport;
+    private current;
+    /** The visible area is short right now (false without a visual viewport, e.g. old browsers). */
+    get short(): boolean;
+    /** Calls `listener` whenever `short` flips; returns the function that ends it. */
+    subscribe(listener: Listener): () => void;
+    private attach;
+    private detach;
+    private readonly onResize;
+    private static visualViewport;
+    /** Height times scale: zooming in with two fingers makes the visual viewport smaller, but the page isn't short. */
+    private static measure;
+}
+/** The watcher the elements use. One per page: there is one viewport. */
+export declare function getViewportWatcher(): ViewportWatcher;
+/**
+ * Scrolls `element` to the top of what the learner sees. On iOS the visual viewport is panned down inside the layout
+ * viewport while the keyboard is open (`offsetTop`); without the correction the element would sit above the visible part.
+ */
+export declare function revealAtTop(element: Element): void;
+/** The focus is inside `element` (also inside its shadow root and the shadow roots below). */
+export declare function hasFocusInside(element: Element): boolean;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octolearn/training-ui",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Octolearn's training components (questions, multiple choice, answer feedback, today's stats) as framework-independent web components.",
   "keywords": [
     "octolearn",