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

package/README.md

@@ -138,6 +138,7 @@ Both layout elements support:
 - `content-max-width-with-passage` (number, optional): max width in px when passages are present. Clamped to 320–2200. Unset by default (layout uses available width).
 - `split-pane-min-region-width` (number, optional): splitpane minimum pane width in px. Clamped to 160–1200. Unset by default (split bounds stay at 20–80). (Ignored by vertical layout; supported for API parity.)
 - `split-pane-collapse-strategy` (string, optional): splitpane stacked-mode strategy. Supported values: `tabbed` (default) and `vertical`. (Ignored by vertical/tabbed layouts; supported for API parity.)
+- `base-heading-level` (number, optional): the heading level this player's card headings occupy, and the level every descendant's outline derives from. Clamped to 1–6; default 2. See [Heading structure](#heading-structure).
 - `show-toolbar` (boolean-like): accepts `true/false` and common string forms (`"true"`, `"false"`, `"1"`, `"0"`, `"yes"`, `"no"`)
 - Host extension props (JS properties only): `toolRegistry`, `sectionHostButtons`, `itemHostButtons`, `passageHostButtons`, `hooks`
 
@@ -170,6 +171,51 @@ To force splitpane stacked mode to use vertical rendering:
 
 By default, splitpane stacked mode uses tabs. The dedicated `pie-section-player-tabbed` layout also always renders passage/items tabs when passages are present.
 
+### Heading structure
+
+The player publishes one number and every descendant derives its outline from it.
+Set `base-heading-level` to the level the cards should occupy in the surrounding
+page — 2 when the page has its own `<h1>` above the player, 3 when the player sits
+under an `<h2>`, and so on:
+
+```html
+<pie-section-player-splitpane base-heading-level="3"></pie-section-player-splitpane>
+```
+
+At the default of 2 that produces:
+
+```
+h2   Passage                    <- passage card heading
+h3     Sea Turtles in Trouble   <- passage title
+h4       Danger on Land         <- authored data-heading content
+h2   Question 1                 <- item card heading
+h3     Part A                   <- authored data-heading content in the prompt
+```
+
+The two content kinds derive different levels from the same number, and the
+difference is deliberate. An item card's heading *is* the item's heading, so the
+item player is told not to emit a screen-reader item heading of its own — one at
+that level already exists, and a second would read as its sibling. A passage
+card's heading is a group label, so the passage player is told to start one level
+deeper, putting the passage's own title beneath it.
+
+Authored `data-heading="headingN"` markup in passages and prompts becomes real
+heading elements only when a level is published, which the player now always does.
+Content authored against
+[PIE-151](https://illuminate.atlassian.net/browse/PIE-151) therefore renders as
+structure without any host configuration.
+
+A host that needs the element's own screen-reader item heading — because it is not
+supplying question headings of its own — overrides per player through the runtime:
+
+```js
+sectionPlayer.runtime = { player: { includeSrHeading: true } };
+```
+
+The pattern behind this, and the reason the value is published rather than pushed,
+is in
+[`docs/architecture/composition-context.md`](../../docs/architecture/composition-context.md).
+
 ### Tab styling hooks
 
 `pie-section-player-tabbed` and splitpane `tabbed` collapse mode expose canonical `pie-*`
@@ -232,34 +278,47 @@ 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
+### Content-card tool surfaces
+
+Item and passage cards offer two content-scoped host surfaces:
+
+- `content-lead` is a full-width stack before the authored player content.
+- `content-media` is the resizable region beside that content.
+
+They are host surfaces, not features: whatever capability declares one of those
+names in `surfaces` may render there, and this package names no capability. A
+surface becomes mountable only when policy grants the capability and its own
+`requiresAuthoredContent` resolves, so an item or passage without the authored
+resource gets no dead affordance.
 
-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.
+Today's occupant is `@pie-players/pie-tool-sign-language` — a signed (ASL)
+translation gated on the `signLanguage` PNP support. It is not part of the
+packaged capability set: a deployment opts in by registering it on the tool
+registry it passes to the player.
 
-It sits to the right of the question content and is resizable via a
+The `content-media` adapter sits to the right of the 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;
-}
-```
+This package owns the region's share of the card width and nothing inside it. A
+capability mounted here sizes its own content: signing legibility needs height for
+hands and face, so it is sized by an aspect-ratio target with a height floor
+rather than by width alone. The `--pie-section-player-item-media-*` tokens hosts
+set for that belong to `@pie-players/pie-tool-sign-language` and are documented
+with their defaults in [its README](../tool-sign-language/README.md) — they keep
+the `pie-section-player` prefix because hosts already set them by those names.
+
+All three section-player surfaces (`content-lead`, `content-media`, and
+`section-overlay`) share one internal Tool Surface Host. It observes live
+`ToolRegistry` mutations and policy/catalog changes, preserves registration
+order across lazy loads, synchronizes an existing element when its current
+context changes, and always calls `destroy()` before removing it. Surface
+failures are isolated per capability and emitted as recoverable
+`framework-error` warnings; they never block readiness or remove another
+working capability. A `renderSurface()` result of `null` is a normal
+mountable-but-unoccupied result, not an error.
 
 ### API direction: CE defaults first, JS customization for advanced cases
 

package/dist/components/shared/card-media-region.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The media region a content card docks an alternate into: its surface name, and
+ * how wide it is.
+ *
+ * Sizing only. Which capability fills the region, and whether it has anything to
+ * show, belongs to the capability: the card asks the registry for whatever is
+ * registered on the surface below and knows nothing else about it. The
+ * signed-alternate resolution that used to live here moved to
+ * `@pie-players/pie-tool-sign-language` behind that capability's own
+ * `requiresAuthoredContent`.
+ */
+/**
+ * Host slot for media docked beside a card's content.
+ *
+ * Named for the relationship rather than for one card kind, because item cards
+ * and passage cards open the same slot: an alternate is authored against a
+ * content node, and a passage owns content nodes exactly as an item does. A
+ * capability declares this surface once and reaches both.
+ */
+export declare const CONTENT_MEDIA_SURFACE = "content-media";
+/**
+ * Host slot for a text alternate that has to be read in order with the content:
+ * full width, above the card body, in document flow.
+ *
+ * Separate from {@link CONTENT_MEDIA_SURFACE} because the geometry is the whole
+ * difference. Docked media is watched beside the content and is sized by an
+ * aspect ratio; a transcript or a plain-language alternate is read *before* the
+ * control it belongs to, which a sticky side column cannot express.
+ */
+export declare const CONTENT_LEAD_SURFACE = "content-lead";
+/**
+ * Default and bounds for the media region's share of the card width.
+ *
+ * Docked media generally needs height rather than width — a person on camera
+ * needs room 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 mounted element's own 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/section-player-view-state.d.ts

@@ -1,6 +1,39 @@
 import { ItemEntity } from '@pie-players/pie-players-shared/types';
 import { SectionCompositionModel } from '../../controllers/types.js';
 import { PlayerElementParams } from './player-action.js';
+/**
+ * Heading depth as composition context.
+ *
+ * Where an item's headings belong in a document outline is a fact about the
+ * page, not about the item: the same item renders under a host `<h1>` here and
+ * three levels down there. The section player is the publisher — it knows the
+ * level its own card headings occupy — and each PIE element is a resolver,
+ * reading the level off the player host and deriving the outline it emits.
+ * `docs/architecture/composition-context.md` states the pattern and its
+ * invariants.
+ *
+ * The two content kinds get different values from the same level, and the
+ * difference is not arbitrary:
+ *
+ * - An item card's heading ("Question 3") *is* the item's heading. The element
+ *   must not emit a second one at that level, so it renders no screen-reader
+ *   item heading and nests authored content one level below.
+ * - A passage card's heading ("Passage") is a group label. The passage's own
+ *   title is real content and belongs beneath it, so the passage player's level
+ *   is one deeper again.
+ *
+ * At the default this yields card `h2` -> passage title `h3` -> passage content
+ * `h4`, and question `h2` -> prompt content `h3`, which is the outline
+ * PIE-159 specifies.
+ */
+export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+/** Matches the level the cards rendered at before it was configurable. */
+export declare const DEFAULT_SECTION_BASE_HEADING_LEVEL: HeadingLevel;
+export declare function normalizeBaseHeadingLevel(value: unknown): HeadingLevel;
+/** Card heading fills the item's slot, so the element adds none of its own. */
+export declare function itemHeadingContext(level: HeadingLevel): Record<string, unknown>;
+/** Card heading is a group label; the passage's own title sits one below it. */
+export declare function passageHeadingContext(level: HeadingLevel): Record<string, unknown>;
 export type LayoutCompositionSnapshot = {
     compositionModel: SectionCompositionModel;
     passages: SectionCompositionModel["passages"];
@@ -17,6 +50,7 @@ export declare function getPassagePlayerParams(args: {
     resolvedPlayerAttributes: Record<string, string>;
     resolvedPlayerProps: Record<string, unknown>;
     playerStrategy: string;
+    baseHeadingLevel?: HeadingLevel;
 }): PlayerElementParams;
 export declare function getItemPlayerParams(args: {
     item: ItemEntity;
@@ -26,6 +60,7 @@ export declare function getItemPlayerParams(args: {
     resolvedPlayerProps: Record<string, unknown>;
     playerStrategy: string;
     itemIndex?: number;
+    baseHeadingLevel?: HeadingLevel;
 }): PlayerElementParams;
 export declare function getCanonicalItemId(args: {
     compositionModel: SectionCompositionModel;

package/dist/components/shared/tool-surface-host.d.ts

@@ -0,0 +1,28 @@
+import { CatalogOwnerContext, ToolRegistry, ToolSurfaceServices } from '@pie-players/pie-assessment-toolkit';
+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;
+}
+/** Create one lifecycle owner for one host surface anchor. */
+export declare function createToolSurfaceHost(onSnapshot: (snapshot: ToolSurfaceHostSnapshot) => void): ToolSurfaceHost;