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

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,6 +278,34 @@ 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.
+It is a host surface named `item-media`, not a feature: whatever capability
+declares `surfaces: ['item-media']` in its registration renders there, and this
+package names none of them. The region appears only when policy grants the
+capability *and* the capability's own `requiresAuthoredContent` resolves, so
+there is no dead affordance on items that carry nothing.
+
+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
+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.
+
+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.
+
 ### API direction: CE defaults first, JS customization for advanced cases
 
 The intended usage model is:

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

@@ -0,0 +1,50 @@
+/**
+ * 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";
+/**
+ * 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/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;