@pie-players/pie-section-player 0.3.63 → 0.3.64

package/README.md

@@ -232,6 +232,35 @@ When both max-width attributes are set, the with-passage cap resolves to the gre
 of the two configured values (after clamp), so with-passage mode never ends up narrower
 than no-passage mode.
 
+### Item card media region
+
+An item card can carry a `data-region="media"` region beside its content region,
+holding a resolved accessibility-catalog media card — today a sign-language
+(ASL) video, gated on the `signLanguage` PNP support. The region only appears
+when the item carries a matching catalog card *and* policy grants the feature, so
+there is no dead affordance on items without signing.
+
+It sits to the right of the question content and is resizable via a
+keyboard-accessible divider (`role="separator"`; arrow keys, `Home`/`End`,
+`Escape` to cancel a drag). Below a card width of 560px the region stacks under
+the content and the divider is withdrawn. Placement is fixed in this iteration:
+there is no orientation toggle and no free repositioning.
+
+Signing legibility needs height for hands and face, so the video is sized by an
+aspect-ratio target with a height floor rather than by width alone. Hosts can
+retune it:
+
+- `--pie-section-player-item-media-aspect-ratio` (default `3 / 4`)
+- `--pie-section-player-item-media-min-height` (default `220px`)
+- `--pie-section-player-item-media-max-height` (default `60vh`)
+
+```css
+pie-section-player-item-card {
+  --pie-section-player-item-media-aspect-ratio: 4 / 5;
+  --pie-section-player-item-media-min-height: 260px;
+}
+```
+
 ### API direction: CE defaults first, JS customization for advanced cases
 
 The intended usage model is:

package/dist/components/shared/section-item-media.d.ts

@@ -0,0 +1,88 @@
+import { AccessibilityCatalogResolverApi, CatalogOwnerContext, SignLanguageMedia } from '@pie-players/pie-assessment-toolkit';
+import { ItemEntity } from '@pie-players/pie-players-shared/types';
+/**
+ * QTI 3.0 / AfA support id gating signed alternates. Excluded from the computed
+ * default PNP profile by `ACCOMMODATION_ONLY_SUPPORT_IDS`, so it is only ever
+ * granted deliberately.
+ */
+export declare const SIGN_LANGUAGE_FEATURE_ID = "signLanguage";
+/** A catalog on this item that carries at least one sign-language card. */
+export interface SignLanguageCatalogRef {
+    catalogId: string;
+    /** Set when the catalog is owned by one model rather than the item root. */
+    modelId?: string;
+}
+export interface ResolvedSignLanguageAlternate extends SignLanguageMedia {
+    catalogId: string;
+}
+/**
+ * Collect the catalog identifiers on an item that carry signing cards.
+ *
+ * The region resolves through the catalog resolver, but the resolver is keyed by
+ * identifier within an owner scope — something has to say *which* identifiers
+ * this item put in play, and whether each belongs to the item or to one model.
+ * That is the same walk the runtime does when it registers an item's catalogs,
+ * so it is borrowed rather than repeated: a ref can only name a scope
+ * registration actually files under. Only the "does this catalog carry signing"
+ * filter is ours.
+ *
+ * The owner identity here is a placeholder: the assessment and section ids are
+ * not known at extraction time and are supplied by the caller at lookup time
+ * (see `resolveSignLanguageAlternate`). Nothing but `modelId` is read from the
+ * walk's contexts.
+ */
+export declare function collectSignLanguageCatalogRefs(item: ItemEntity | null | undefined): SignLanguageCatalogRef[];
+export interface SignLanguageLookupArgs {
+    resolver: AccessibilityCatalogResolverApi;
+    refs: SignLanguageCatalogRef[];
+    /** Owner context for the item, without `modelId` — added per ref. */
+    ownerContext: CatalogOwnerContext;
+    /** Sign language the learner is entitled to, ISO 639-3. */
+    requestedSignLang?: string;
+}
+/**
+ * Resolve the signed alternate to show for an item, or `null`.
+ *
+ * Priority, language fallback and owner scoping are the resolver's job and are
+ * not re-implemented here. What *is* enforced here is the one deliberate
+ * departure from the resolver's default behaviour: **no cross-sign-language
+ * substitution.** The resolver's last fallback rung matches any card of the
+ * requested type regardless of language, which for spoken content is helpful
+ * and for signing is not — handing an ASL learner a BSL recording is worse than
+ * handing them nothing. So a card the resolver returns by that rung is accepted
+ * only if its language actually matches, or if the card asserts no language at
+ * all.
+ *
+ * MVP takes the first resolvable card: sample content is one recording per item.
+ * The refs stay per-node capable for when choice-level docking lands.
+ */
+export declare function resolveSignLanguageAlternate(args: SignLanguageLookupArgs): ResolvedSignLanguageAlternate | null;
+/**
+ * Default and bounds for the media region's share of the card width.
+ *
+ * Signing needs height for hands and face, so the region is sized by an
+ * aspect-ratio target with a minimum height rather than by width alone — a flat
+ * viewport percentage either wastes space on a short clip or crushes it on a
+ * narrow device. The percentage below only decides how the card's width is
+ * split; legibility is defended by the region's CSS.
+ */
+export declare const MEDIA_REGION_DEFAULT_PERCENT = 34;
+export declare const MEDIA_REGION_MIN_PERCENT = 20;
+export declare const MEDIA_REGION_MAX_PERCENT = 55;
+/** Below this card width the split is dropped and the region stacks. */
+export declare const MEDIA_REGION_STACK_BREAKPOINT_PX = 560;
+export declare function clampMediaRegionPercent(value: number, min?: number, max?: number): number;
+/**
+ * Convert a pointer drag into a media-region width percentage.
+ *
+ * Container-relative, unlike the passage/items divider's fixed 0.1%-per-pixel
+ * factor: the same drag has to mean the same thing in a wide card and a narrow
+ * one. The region is on the right, so dragging left grows it.
+ */
+export declare function mediaRegionPercentFromDrag(args: {
+    startPercent: number;
+    deltaX: number;
+    containerWidthPx: number;
+    min?: number;
+    max?: number;
+}): number;

package/dist/components/shared/shell-registration.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Registration dispatch for the item and passage shells.
+ *
+ * Registration is a statement of fact to the runtime, and the runtime takes it
+ * literally: a `pie-register` makes the toolkit unregister and re-register the
+ * content's accessibility catalogs, re-run `sectionEngine.register`, and
+ * re-notify the section controller. Both shells used to dispatch it from the
+ * same effect that attached their listeners, with `pie-unregister` in that
+ * effect's cleanup — so every re-run announced a teardown and a rebuild of state
+ * that had not moved, and between the two the content had no catalogs at all.
+ *
+ * Those effects re-run on prop changes, and a shell's props are re-applied
+ * whenever its parent card's template updates. That made the dispatch the far
+ * half of a cycle: a reader that re-renders in response to a catalog change
+ * re-applies a shell's props, which re-registers, which changes catalogs again.
+ * It shipped once at roughly a thousand rounds per item, ending in Svelte
+ * abandoning the update at its depth limit with the DOM half-applied — and every
+ * assertion about the rendered output passed while it was happening, because the
+ * elements were all present.
+ *
+ * So the dispatcher keeps the last identity it announced and says nothing when
+ * the next one matches.
+ */
+export type ShellRegistrationIdentity = {
+    kind: "item" | "passage";
+    host: HTMLElement;
+    itemId: string;
+    canonicalItemId: string;
+    contentKind: string;
+    item: unknown;
+};
+export type ShellRegistrationDispatcher = {
+    /**
+     * Announce `identity` if it says anything new, and retire the live
+     * registration when there is nothing left to describe — a shell without a host
+     * or an id no longer stands for content, and leaving its registration behind
+     * would strand it in the runtime.
+     *
+     * Never dispatches `pie-unregister` before a re-register: both registration
+     * paths in the toolkit are keyed by element and replace what is there, so the
+     * unregister only ever created the gap.
+     */
+    sync: (identity: ShellRegistrationIdentity | null) => void;
+    /**
+     * Retire the live registration, replaying the identity it was made under
+     * rather than whatever the props say now — by the time a registration is
+     * retired the props may already describe its replacement, and unregistering
+     * under the new identity would leave the old one live.
+     *
+     * Belongs in a teardown that runs on teardown only. Attaching it to an effect
+     * that re-runs on prop changes is what made the churn.
+     */
+    retire: () => void;
+};
+export declare function createShellRegistrationDispatcher(): ShellRegistrationDispatcher;