@pie-players/pie-players-shared 0.3.67 → 0.3.69

package/dist/ui/first-focusable.js

@@ -24,3 +24,50 @@ export function isProgrammaticFocusTarget(el) {
         return false;
     return el.offsetParent !== null || el.getClientRects().length > 0;
 }
+/**
+ * Whether `el` is in the sequential tab order.
+ *
+ * Stricter than {@link isProgrammaticFocusTarget}, which deliberately accepts
+ * `tabindex="-1"`: such an element is a valid `focus()` target — a roving-tabindex
+ * control or a landmark focused after a view change — but is explicitly not tabbable.
+ * A tab order that included it would stop on elements the browser skips.
+ */
+export function isTabbable(el) {
+    if (el.getAttribute("tabindex") === "-1")
+        return false;
+    return isProgrammaticFocusTarget(el);
+}
+/**
+ * Focusable descendants of `root` in tab order, descending into open shadow roots.
+ *
+ * `querySelectorAll` stops at a shadow boundary, which makes it the wrong tool for
+ * collecting a tab order in this codebase: every tool renders into `shadow: "open"`,
+ * so a container holding one has focusable content the selector cannot see. A focus
+ * trap built on the flat query traps Tab in the host's own chrome and never reaches
+ * the tool — the tool's controls are then unreachable by keyboard entirely.
+ *
+ * Closed shadow roots are invisible to script and are skipped; nothing can be done
+ * for them from outside.
+ */
+export function collectFocusable(root) {
+    const found = [];
+    const visit = (node) => {
+        for (const child of Array.from(node.children)) {
+            if (!(child instanceof HTMLElement))
+                continue;
+            // `inert` and its subtree take no focus, so there is nothing below to collect.
+            if (child.hasAttribute("inert"))
+                continue;
+            if (isTabbable(child))
+                found.push(child);
+            // A shadow host's own light children are slotted into its shadow tree, so the
+            // shadow root is where tab order continues.
+            if (child.shadowRoot)
+                visit(child.shadowRoot);
+            else
+                visit(child);
+        }
+    };
+    visit(root);
+    return found;
+}

package/dist/ui/focus-trap.js

@@ -1,6 +1,11 @@
-import { FOCUSABLE_SELECTOR, isProgrammaticFocusTarget, } from "./first-focusable.js";
+import { collectFocusable } from "./first-focusable.js";
+/**
+ * Shadow-aware: a trapped panel almost always hosts a custom element rendering into
+ * `shadow: "open"`, and a flat `querySelectorAll` would collect only the panel's own
+ * chrome — trapping Tab there and leaving the hosted tool's controls unreachable.
+ */
 function getFocusableElements(container) {
-    return Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR)).filter((el) => isProgrammaticFocusTarget(el));
+    return collectFocusable(container);
 }
 function getDeepActiveElement(root) {
     let active = root.activeElement;

package/dist/ui/pointer-drag.d.ts

@@ -0,0 +1,30 @@
+export type PointerDragPosition = {
+    x: number;
+    y: number;
+};
+export interface PointerDragControllerArgs {
+    getPosition: () => PointerDragPosition;
+    setPosition: (next: PointerDragPosition) => void;
+    /** Called once a drag starts, before the first move — e.g. to bring the element to front. */
+    onDragStart?: (container: Element) => void;
+}
+export interface PointerDragController {
+    isDragging: () => boolean;
+    /**
+     * Begin tracking a drag from a pointerdown. Callers own pointer-capture
+     * release and event-listener attach/detach — this only tracks the
+     * position math, since a caller may also need the same pointer-capture
+     * session for an unrelated interaction (e.g. a resize handle).
+     */
+    startDragging: (event: PointerEvent, container: Element) => void;
+    /** No-ops when a drag isn't in progress, so callers can route every pointermove through this unconditionally. */
+    handlePointerMove: (event: PointerEvent) => void;
+    endDragging: () => void;
+}
+/**
+ * Tracks a pointer-capture-based drag: the position delta between where the
+ * pointer went down (relative to the element's current position) and where
+ * it currently is. Shared by every floating tool overlay that repositions
+ * itself by dragging its own chrome.
+ */
+export declare function createPointerDragController(args: PointerDragControllerArgs): PointerDragController;

package/dist/ui/pointer-drag.js

@@ -0,0 +1,34 @@
+/**
+ * Tracks a pointer-capture-based drag: the position delta between where the
+ * pointer went down (relative to the element's current position) and where
+ * it currently is. Shared by every floating tool overlay that repositions
+ * itself by dragging its own chrome.
+ */
+export function createPointerDragController(args) {
+    let dragging = false;
+    let dragStart = { x: 0, y: 0 };
+    return {
+        isDragging: () => dragging,
+        startDragging(event, container) {
+            container.setPointerCapture(event.pointerId);
+            dragging = true;
+            const position = args.getPosition();
+            dragStart = {
+                x: event.clientX - position.x,
+                y: event.clientY - position.y,
+            };
+            args.onDragStart?.(container);
+        },
+        handlePointerMove(event) {
+            if (!dragging)
+                return;
+            args.setPosition({
+                x: event.clientX - dragStart.x,
+                y: event.clientY - dragStart.y,
+            });
+        },
+        endDragging() {
+            dragging = false;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/pie-players-shared",
-	"version": "0.3.67",
+	"version": "0.3.69",
 	"type": "module",
 	"description": "Shared runtime + UI utilities for PIE players",
 	"license": "MIT",
@@ -37,6 +37,14 @@
 			"types": "./dist/types/index.d.ts",
 			"import": "./dist/types/index.js"
 		},
+		"./formative": {
+			"types": "./dist/formative/index.d.ts",
+			"import": "./dist/formative/index.js"
+		},
+		"./timed-media": {
+			"types": "./dist/timed-media/index.d.ts",
+			"import": "./dist/timed-media/index.js"
+		},
 		"./pie": {
 			"types": "./dist/pie/index.d.ts",
 			"import": "./dist/pie/index.js"
@@ -53,10 +61,30 @@
 			"types": "./dist/server/npm-registry.d.ts",
 			"import": "./dist/server/npm-registry.js"
 		},
+		"./server/npm-auth-env": {
+			"types": "./dist/server/npm-auth-env.d.ts",
+			"import": "./dist/server/npm-auth-env.js"
+		},
 		"./i18n": {
 			"types": "./dist/i18n/index.d.ts",
 			"import": "./dist/i18n/index.js"
 		},
+		"./i18n/types": {
+			"types": "./dist/i18n/types.d.ts",
+			"import": "./dist/i18n/types.js"
+		},
+		"./i18n/provider": {
+			"types": "./dist/i18n/provider.d.ts",
+			"import": "./dist/i18n/provider.js"
+		},
+		"./i18n/catalogs": {
+			"types": "./dist/i18n/catalogs.d.ts",
+			"import": "./dist/i18n/catalogs.js"
+		},
+		"./i18n/language-tags": {
+			"types": "./dist/i18n/language-tags.d.ts",
+			"import": "./dist/i18n/language-tags.js"
+		},
 		"./nds-icon-button": {
 			"types": "./dist/components/vendor/nds/nds-icon-button.d.ts",
 			"import": "./dist/components/vendor/nds/nds-icon-button.js"
@@ -68,13 +96,17 @@
 		"./ui/content-styles": {
 			"types": "./dist/ui/content-styles.d.ts",
 			"import": "./dist/ui/content-styles.js"
+		},
+		"./tools/term-lookup": {
+			"types": "./dist/tools/term-lookup.d.ts",
+			"import": "./dist/tools/term-lookup.js"
 		}
 	},
 	"files": [
 		"dist"
 	],
 	"dependencies": {
-		"@pie-lib/math-rendering-module": "5.1.2",
+		"@pie-lib/math-rendering-module": "6.0.0",
 		"dompurify": "^3.4.13",
 		"semver": "^7.8.5"
 	},
@@ -89,13 +121,13 @@
 		"scan-hardcoded": "bun run src/i18n/scripts/scan-hardcoded.ts"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "^2.5.7",
-		"@happy-dom/global-registrator": "^20.11.1",
+		"@biomejs/biome": "^2.5.10",
+		"@happy-dom/global-registrator": "^20.11.6",
 		"@playwright/test": "^1.62.1",
 		"@types/semver": "^7.8.0",
-		"esbuild": "^0.28.1",
+		"esbuild": "^0.28.2",
 		"glob": "^13.0.0",
-		"svelte": "^5.56.8",
+		"svelte": "^5.56.10",
 		"typescript": "^5.9.3"
 	},
 	"homepage": "https://github.com/pie-framework/pie-players/tree/master/packages/players-shared#readme",

package/dist/i18n/loader.d.ts

@@ -1,35 +0,0 @@
-/**
- * Translation Loader
- *
- * Implements hybrid loading strategy:
- * - English bundled with application
- * - Other languages loaded on demand
- *
- * Part of PIE Players i18n system.
- */
-import type { TranslationBundle } from "./types.js";
-/**
- * Bundled English translations
- * Available immediately without network request
- */
-export declare const BUNDLED_TRANSLATIONS: Record<string, TranslationBundle>;
-/**
- * Load translations for a locale
- *
- * @param locale Locale code (e.g., 'en', 'es', 'zh', 'ar')
- * @returns Translation bundle with flattened keys
- */
-export declare function loadTranslations(locale: string): Promise<TranslationBundle>;
-/**
- * Get available locales
- *
- * @returns Array of locale codes
- */
-export declare function getAvailableLocales(): string[];
-/**
- * Check if locale is RTL
- *
- * @param locale Locale code
- * @returns True if locale is right-to-left
- */
-export declare function isRTLLocale(locale: string): boolean;

package/dist/i18n/loader.js

@@ -1,132 +0,0 @@
-/**
- * Translation Loader
- *
- * Implements hybrid loading strategy:
- * - English bundled with application
- * - Other languages loaded on demand
- *
- * Part of PIE Players i18n system.
- */
-// Import English translations (bundled)
-import enCommon from "./translations/en/common.json" with { type: "json" };
-import enToolkit from "./translations/en/toolkit.json" with { type: "json" };
-import enTools from "./translations/en/tools.json" with { type: "json" };
-// RTL locales
-const RTL_LOCALES = ["ar", "he", "fa", "ur"];
-/**
- * Bundled English translations
- * Available immediately without network request
- */
-export const BUNDLED_TRANSLATIONS = {
-    en: {
-        locale: "en",
-        direction: "ltr",
-        translations: {
-            ...flattenTranslations(enCommon),
-            ...flattenTranslations(enToolkit),
-            ...flattenTranslations(enTools),
-        },
-    },
-};
-const LOCALE_IMPORTS = {
-    es: () => Promise.all([
-        import("./translations/es/common.json"),
-        import("./translations/es/toolkit.json"),
-        import("./translations/es/tools.json"),
-    ]),
-    zh: () => Promise.all([
-        import("./translations/zh/common.json"),
-        import("./translations/zh/toolkit.json"),
-        import("./translations/zh/tools.json"),
-    ]),
-    ar: () => Promise.all([
-        import("./translations/ar/common.json"),
-        import("./translations/ar/toolkit.json"),
-        import("./translations/ar/tools.json"),
-    ]),
-};
-/**
- * Load translations for a locale
- *
- * @param locale Locale code (e.g., 'en', 'es', 'zh', 'ar')
- * @returns Translation bundle with flattened keys
- */
-export async function loadTranslations(locale) {
-    // Return bundled English immediately
-    if (locale === "en") {
-        return BUNDLED_TRANSLATIONS.en;
-    }
-    const importer = LOCALE_IMPORTS[locale];
-    if (!importer) {
-        throw new Error(`Translation files not found for locale: ${locale}. Ensure translation files exist in packages/players-shared/src/i18n/translations/${locale}/`);
-    }
-    // Lazy load other locales
-    try {
-        const [common, toolkit, tools] = await importer();
-        return {
-            locale,
-            direction: RTL_LOCALES.includes(locale) ? "rtl" : "ltr",
-            translations: {
-                ...flattenTranslations(common.default || common),
-                ...flattenTranslations(toolkit.default || toolkit),
-                ...flattenTranslations(tools.default || tools),
-            },
-        };
-    }
-    catch (error) {
-        console.error(`Failed to load translations for locale: ${locale}`, error);
-        throw new Error(`Translation files not found for locale: ${locale}. Ensure translation files exist in packages/players-shared/src/i18n/translations/${locale}/`);
-    }
-}
-/**
- * Flatten nested JSON to dot notation
- *
- * Converts:
- * { "common": { "save": "Save" } }
- *
- * To:
- * { "common.save": "Save" }
- *
- * @param obj Nested translation object
- * @param prefix Current key prefix
- * @param result Accumulated result
- * @returns Flattened translation object
- */
-function flattenTranslations(obj, prefix = "", result = {}) {
-    for (const [key, value] of Object.entries(obj)) {
-        const newKey = prefix ? `${prefix}.${key}` : key;
-        if (value && typeof value === "object" && !Array.isArray(value)) {
-            // Check if it's a plural form (has 'one' or 'other' keys)
-            if ("one" in value || "other" in value) {
-                // This is a plural translation, keep it as an object
-                result[newKey] = value;
-            }
-            else {
-                // This is a nested object, flatten recursively
-                flattenTranslations(value, newKey, result);
-            }
-        }
-        else {
-            // This is a leaf value
-            result[newKey] = value;
-        }
-    }
-    return result;
-}
-/**
- * Get available locales
- *
- * @returns Array of locale codes
- */
-export function getAvailableLocales() {
-    return ["en", "es", "zh", "ar"];
-}
-/**
- * Check if locale is RTL
- *
- * @param locale Locale code
- * @returns True if locale is right-to-left
- */
-export function isRTLLocale(locale) {
-    return RTL_LOCALES.includes(locale);
-}

package/dist/i18n/simple-i18n.d.ts

@@ -1,68 +0,0 @@
-/**
- * Simple I18n Implementation
- *
- * Lightweight i18n without external dependencies.
- * Used for standalone components that don't need the full service architecture.
- */
-import type { I18nConfig } from "./types.js";
-/**
- * Simple I18n class for standalone use
- */
-export declare class SimpleI18n {
-    private locale;
-    private fallbackLocale;
-    private direction;
-    private translations;
-    private listeners;
-    private loadingPromises;
-    private config;
-    constructor(config?: I18nConfig);
-    /**
-     * Initialize with locale
-     */
-    initialize(config: I18nConfig): Promise<void>;
-    /**
-     * Translate a key
-     */
-    t(key: string, params?: Record<string, any>): string;
-    /**
-     * Translate with pluralization
-     */
-    tn(key: string, count: number, params?: Record<string, any>): string;
-    /**
-     * Get current locale
-     */
-    getLocale(): string;
-    /**
-     * Change locale
-     */
-    setLocale(locale: string): Promise<void>;
-    /**
-     * Get current direction
-     */
-    getDirection(): "ltr" | "rtl";
-    /**
-     * Get available locales
-     */
-    getAvailableLocales(): string[];
-    /**
-     * Check if locale is loaded
-     */
-    isLocaleLoaded(locale: string): boolean;
-    /**
-     * Subscribe to changes
-     */
-    subscribe(listener: () => void): () => void;
-    /**
-     * Check if key exists
-     */
-    hasKey(key: string): boolean;
-    private notifyListeners;
-    private applyLocale;
-    private applyDOMDirection;
-    private loadTranslationsForLocale;
-    private getTranslation;
-    private interpolate;
-    private selectPluralForm;
-    private detectBrowserLocale;
-}

package/dist/i18n/simple-i18n.js

@@ -1,198 +0,0 @@
-/**
- * Simple I18n Implementation
- *
- * Lightweight i18n without external dependencies.
- * Used for standalone components that don't need the full service architecture.
- */
-/**
- * Simple I18n class for standalone use
- */
-export class SimpleI18n {
-    locale = "en";
-    fallbackLocale = "en";
-    direction = "ltr";
-    translations = new Map();
-    listeners = new Set();
-    loadingPromises = new Map();
-    config;
-    constructor(config = {}) {
-        this.config = config;
-        this.fallbackLocale = config.fallbackLocale || "en";
-        // Load bundled translations
-        if (config.bundledTranslations) {
-            for (const [locale, bundle] of Object.entries(config.bundledTranslations)) {
-                this.translations.set(locale, bundle);
-            }
-        }
-    }
-    /**
-     * Initialize with locale
-     */
-    async initialize(config) {
-        Object.assign(this.config, config);
-        const locale = config.locale || this.detectBrowserLocale();
-        await this.setLocale(locale);
-    }
-    /**
-     * Translate a key
-     */
-    t(key, params) {
-        const translation = this.getTranslation(key);
-        return this.interpolate(translation, params);
-    }
-    /**
-     * Translate with pluralization
-     */
-    tn(key, count, params) {
-        const translation = this.getTranslation(key);
-        if (typeof translation === "object") {
-            const pluralForm = this.selectPluralForm(count, this.locale);
-            const text = translation[pluralForm] || translation.other;
-            return this.interpolate(text, { ...params, count });
-        }
-        return this.interpolate(translation, { ...params, count });
-    }
-    /**
-     * Get current locale
-     */
-    getLocale() {
-        return this.locale;
-    }
-    /**
-     * Change locale
-     */
-    async setLocale(locale) {
-        // Check if already loading
-        if (this.loadingPromises.has(locale)) {
-            await this.loadingPromises.get(locale);
-            return;
-        }
-        // Check if already loaded
-        if (this.translations.has(locale)) {
-            this.applyLocale(locale);
-            return;
-        }
-        // Load translations
-        const loadingPromise = this.loadTranslationsForLocale(locale);
-        this.loadingPromises.set(locale, loadingPromise);
-        try {
-            await loadingPromise;
-            this.applyLocale(locale);
-        }
-        finally {
-            this.loadingPromises.delete(locale);
-        }
-    }
-    /**
-     * Get current direction
-     */
-    getDirection() {
-        return this.direction;
-    }
-    /**
-     * Get available locales
-     */
-    getAvailableLocales() {
-        return Array.from(this.translations.keys());
-    }
-    /**
-     * Check if locale is loaded
-     */
-    isLocaleLoaded(locale) {
-        return this.translations.has(locale);
-    }
-    /**
-     * Subscribe to changes
-     */
-    subscribe(listener) {
-        this.listeners.add(listener);
-        return () => {
-            this.listeners.delete(listener);
-        };
-    }
-    /**
-     * Check if key exists
-     */
-    hasKey(key) {
-        const bundle = this.translations.get(this.locale);
-        return !!bundle?.translations[key];
-    }
-    notifyListeners() {
-        for (const listener of this.listeners) {
-            listener();
-        }
-    }
-    applyLocale(locale) {
-        const bundle = this.translations.get(locale);
-        if (!bundle)
-            return;
-        this.locale = locale;
-        this.direction = bundle.direction;
-        this.applyDOMDirection();
-        this.notifyListeners();
-    }
-    applyDOMDirection() {
-        if (typeof document === "undefined")
-            return;
-        document.documentElement.setAttribute("dir", this.direction);
-        document.documentElement.setAttribute("lang", this.locale);
-    }
-    async loadTranslationsForLocale(locale) {
-        if (!this.config.loadTranslations) {
-            throw new Error(`No translation loader configured for locale: ${locale}`);
-        }
-        const bundle = await this.config.loadTranslations(locale);
-        this.translations.set(locale, bundle);
-    }
-    getTranslation(key) {
-        // Try current locale
-        const currentBundle = this.translations.get(this.locale);
-        if (currentBundle?.translations[key]) {
-            return currentBundle.translations[key];
-        }
-        // Try fallback locale
-        const fallbackBundle = this.translations.get(this.fallbackLocale);
-        if (fallbackBundle?.translations[key]) {
-            return fallbackBundle.translations[key];
-        }
-        // Missing key
-        if (this.config.onMissingKey) {
-            this.config.onMissingKey(key, this.locale);
-        }
-        return key;
-    }
-    interpolate(text, params) {
-        if (!params)
-            return text;
-        return text.replace(/\{(\w+)\}/g, (match, key) => {
-            return params[key]?.toString() || match;
-        });
-    }
-    selectPluralForm(count, locale) {
-        // Use Intl.PluralRules if available
-        if (typeof Intl !== "undefined" && Intl.PluralRules) {
-            try {
-                const rules = new Intl.PluralRules(locale);
-                const category = rules.select(count);
-                return category;
-            }
-            catch {
-                // Fall through to simple rules
-            }
-        }
-        // Fallback to simple rules
-        if (count === 0)
-            return "zero";
-        if (count === 1)
-            return "one";
-        return "other";
-    }
-    detectBrowserLocale() {
-        if (typeof navigator === "undefined")
-            return "en";
-        const browserLang = navigator.language ||
-            (navigator.languages && navigator.languages[0]) ||
-            "en";
-        return browserLang.split("-")[0];
-    }
-}

package/dist/i18n/translations/ar/common.json

@@ -1,36 +0,0 @@
-{
-    "common": {
-        "save": "حفظ",
-        "cancel": "إلغاء",
-        "close": "إغلاق",
-        "loading": "جار التحميل...",
-        "error": "خطأ",
-        "retry": "إعادة المحاولة",
-        "back": "رجوع",
-        "next": "التالي",
-        "previous": "السابق",
-        "submit": "إرسال",
-        "continue": "متابعة",
-        "finish": "إنهاء",
-        "yes": "نعم",
-        "no": "لا",
-        "ok": "موافق",
-        "settings": "الإعدادات",
-        "language": "اللغة",
-        "theme": "المظهر",
-        "settings_aria": "فتح قائمة الإعدادات",
-        "rtl_notice": "اتجاه النص من اليمين إلى اليسار نشط",
-        "question": {
-            "one": "سؤال",
-            "other": "أسئلة"
-        },
-        "item": {
-            "one": "عنصر",
-            "other": "عناصر"
-        },
-        "character": {
-            "one": "حرف",
-            "other": "حروف"
-        }
-    }
-}