@pie-players/pie-section-player 0.3.28 → 0.3.30

package/README.md

@@ -4,6 +4,7 @@ Section rendering package with layout custom elements:
 
 - `pie-section-player-splitpane`
 - `pie-section-player-vertical`
+- `pie-section-player-tabbed`
 
 The package no longer exposes the legacy `pie-section-player` layout orchestration API.
 
@@ -38,6 +39,7 @@ Import the custom-element registration entrypoint in consumers:
 ```ts
 import '@pie-players/pie-section-player/components/section-player-splitpane-element';
 import '@pie-players/pie-section-player/components/section-player-vertical-element';
+import '@pie-players/pie-section-player/components/section-player-tabbed-element';
 import '@pie-players/pie-section-player/components/section-player-item-card-element';
 import '@pie-players/pie-section-player/components/section-player-passage-card-element';
 ```
@@ -60,14 +62,86 @@ Both layout elements support:
 - `debug` (boolean-like): verbose debug logging control (`"true"` enables, `"false"`/`"0"` disables)
 - `toolbar-position` (string): `top|right|bottom|left|none`
 - `narrow-layout-breakpoint` (number, optional): viewport width in px below which the layout collapses (split pane: single column; vertical: toolbar moves to top). Clamped to 400–2000; default 1100.
+- `content-max-width-no-passage` (number, optional): max width in px when no passages exist. Clamped to 320–2200. Unset by default (layout uses available width).
+- `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 (legacy 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.)
 - `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`, `cardTitleFormatter`
+- Host extension props (JS properties only): `toolRegistry`, `sectionHostButtons`, `itemHostButtons`, `passageHostButtons`, `hooks`
 
-When viewport width is within the collapsed range (~1100px and below), inline section
-toolbar positions (`left`/`right`) normalize to `top` so controls remain horizontally
-laid out and easier to access.
+When viewport width is within the collapsed range (~1100px and below), splitpane and
+vertical layout hosts normalize section toolbar placement to `top`. This includes
+`left`, `right`, `bottom`, and `none` values.
 
-`cardTitleFormatter` remains active across responsive splitpane transitions (split -> stacked and stacked -> split), because title rendering is provided through shared card context rather than layout-specific state.
+`hooks.cardTitleFormatter` remains active across responsive splitpane transitions (split -> stacked and stacked -> split), because title rendering is provided through shared card context rather than layout-specific state.
+
+To opt into PIE-117 dimensions from a host, configure:
+
+```html
+<pie-section-player-splitpane
+  content-max-width-no-passage="800"
+  content-max-width-with-passage="1200"
+  split-pane-min-region-width="280"
+></pie-section-player-splitpane>
+```
+
+Use the same max-width attributes on `pie-section-player-vertical` when you want the same no-passage/with-passage width behavior in vertical mode.
+
+To force splitpane stacked mode to use vertical rendering:
+
+```html
+<pie-section-player-splitpane
+  narrow-layout-breakpoint="1100"
+  split-pane-collapse-strategy="vertical"
+></pie-section-player-splitpane>
+```
+
+By default, splitpane stacked mode uses tabs. The dedicated `pie-section-player-tabbed` layout also always renders passage/items tabs when passages are present.
+
+### Tab styling hooks
+
+`pie-section-player-tabbed` and splitpane `tabbed` collapse mode expose canonical `pie-*`
+hooks for theming:
+
+- `pie-section-player-tabs`
+- `pie-section-player-tab`
+- `pie-section-player-tab--active`
+- `pie-section-player-tab-panel`
+
+For theme compatibility with existing passage-label patterns, tabs also expose:
+
+- `data-pie-purpose="passage-label"` and alias class `passage-label`
+- `data-pie-purpose="item-label"` and alias class `item-label`
+
+Tab colors/spacing can be themed via CSS variables such as:
+`--pie-section-player-tab-color`, `--pie-section-player-tab-active-color`,
+`--pie-section-player-tab-indicator-color`, and `--pie-section-player-tab-spacing`.
+
+### Card header styling hooks
+
+Passage and item cards share a common header row
+(`.pie-section-player-content-card-header`, with the card-specific aliases
+`.pie-section-player-passage-header` / `.pie-section-player-item-header`).
+
+- Title and toolbar are centered vertically by default. There is no prop or
+  attribute for this — hosts needing a non-standard alignment should override
+  the selector in their own stylesheet.
+- The header fill is transparent by default. Hosts/themes opt into a color
+  via the `--pie-section-player-card-header-background` CSS variable; the
+  framework does not ship a brand palette.
+
+Example (host CSS):
+
+```css
+pie-section-player-passage-card,
+pie-section-player-item-card {
+  --pie-section-player-card-header-background: #c9e5e6;
+}
+```
+
+When both max-width attributes are set, the with-passage cap resolves to the greater
+of the two configured values (after clamp), so with-passage mode never ends up narrower
+than no-passage mode.
 
 ### API direction: CE defaults first, JS customization for advanced cases
 
@@ -75,29 +149,107 @@ The intended usage model is:
 
 - **CE props for default/standard flows (roughly 90% use cases)**:
   - `assessment-id`, `section`, `section-id`, `attempt-id`, `debug`
-  - `show-toolbar`, `toolbar-position`, `narrow-layout-breakpoint`, `enabled-tools`, `item-toolbar-tools`, `passage-toolbar-tools`
+  - `show-toolbar`, `toolbar-position`, `narrow-layout-breakpoint`
+  - `content-max-width-no-passage`, `content-max-width-with-passage`, `split-pane-min-region-width`, `split-pane-collapse-strategy`
+  - `enabled-tools`, `item-toolbar-tools`, `passage-toolbar-tools`
 - **JS API for advanced customization**:
   - Get the controller handle via `getSectionController()` or `waitForSectionController()`
   - Listen to `section-controller-ready`
   - Apply custom policy/gating in host code (for example, domain-specific `canNext` based on controller events like `section-items-complete-changed`)
   - Compose forward/backward eligibility in host code using `selectNavigation()` + host state; there is intentionally no separate parallel CE gating API for this
   - Inject custom toolbar tooling with `toolRegistry` and optional host button arrays (`sectionHostButtons`, `itemHostButtons`, `passageHostButtons`)
-  - Customize item/passage card headings via `cardTitleFormatter`
+  - Register host callbacks via `hooks` (for example `hooks.cardTitleFormatter`)
 
 Example:
 
 ```ts
 const host = document.querySelector("pie-section-player-splitpane") as any;
-host.cardTitleFormatter = (context: any) => {
-  if (context.kind === "item") {
-    return `Question ${context.itemIndex + 1}: ${context.item?.name || context.defaultTitle}`;
-  }
-  return context.passage?.name || context.defaultTitle;
+host.hooks = {
+  cardTitleFormatter: (context: any) => {
+    if (context.kind === "item") {
+      return `Question ${context.itemIndex + 1}: ${context.item?.name || context.defaultTitle}`;
+    }
+    return context.passage?.name || context.defaultTitle;
+  },
 };
 ```
 
 Advanced CE props are still supported as escape hatches (`runtime`, `coordinator`, `createSectionController`, etc.), but hosts should prefer JS/controller composition for non-standard behavior.
 
+### Focus management
+
+Section-player owns its own focus contract so hosts can integrate a
+"Skip to Main" affordance and keyboard navigation without re-encoding
+the passage-first rule.
+
+**Public focus targets.** Both card custom elements are `tabindex="-1"`
+(programmatically focusable, never in sequential tab order) and expose a
+`:focus-visible` outline:
+
+- `<pie-section-player-passage-card>` (when the section has a passage)
+- `<pie-section-player-item-card>`
+
+The inner `.pie-section-player-content-card[data-section-item-card]`
+selector is an internal back-compat hook and is not part of the public
+contract — prefer querying the custom element tags.
+
+**Declarative control.** The `SectionPlayerFocusPolicy.autoFocus` strategy
+governs focus on every navigation event (Next / Back / `navigateTo`) and is
+also honored by the imperative `focusStart()`:
+
+- `"start-of-content"` *(default)* — focus the passage card when present,
+  otherwise the first item card. Matches the canonical assessment UX where
+  Skip-to-Main and navigation land in the same place. Best for
+  one-item-per-page layouts (splitpane, tabbed).
+- `"current-item"` — focus the newly-active item card (queried as
+  `pie-section-player-item-card[is-current]`). Best for stacked/list
+  layouts where multiple items are visible at once (vertical, custom
+  kernel-host variants). Works in both paginated and keep-together
+  sections — QTI 3 `keep-together` is a pagination hint only and does
+  not disable item-level navigation or current-item tracking.
+- `"none"` — framework never moves focus on navigation; the host owns it
+  entirely. `focusStart()` still moves focus (defaults to
+  start-of-content) because hosts only call it when they *want* focus to
+  move.
+
+```ts
+const host = document.querySelector("pie-section-player-splitpane") as any;
+host.policies = {
+  readiness: { mode: "progressive" },
+  preload: { enabled: true },
+  focus: { autoFocus: "start-of-content" },
+  telemetry: { enabled: true },
+};
+```
+
+**Imperative escape hatch (host-owned focus moments).** Every layout
+element (`pie-section-player-splitpane`, `-vertical`, `-tabbed`,
+`-kernel-host`, and `-base`) exposes a `focusStart(): boolean` method.
+Call it from host-owned affordances the framework cannot observe — most
+commonly a "Skip to Main" button in the host's ribbon:
+
+```ts
+document.querySelector("pie-section-player-splitpane")?.focusStart();
+```
+
+`focusStart()` honors the `autoFocus` strategy so Skip-to-Main lands
+wherever the host has opted in for navigation focus:
+
+- `"start-of-content"` *(default)* → passage card when present, else first
+  item card.
+- `"current-item"` → the item card currently marked `is-current`, falling
+  back to start-of-content if no current item is resolvable.
+- `"none"` → start-of-content (hosts call `focusStart()` precisely
+  because they want focus to move).
+
+For Next / Back / question-number navigation the host does **not** call
+`focusStart()` — the `autoFocus` policy fires automatically.
+
+**Deprecation.** `SectionPlayerFocusPolicy.autoFocusFirstItem` still
+works for one release (mapped onto `autoFocus`: `true` →
+`"start-of-content"`, `false` → `"none"`) and emits a one-time console
+warning. It will be removed in the next major. Migrate to `autoFocus`.
+
 ### Navigation signals
 
 - `item-selected`: item-level navigation change within the current section in the `SectionController` broadcast stream (`itemIndex`, `currentItemId`, `totalItems`).
@@ -333,6 +485,29 @@ await controller?.updateItemSession?.("q1", {
 The same controller snapshot is what the persistence strategy saves/loads.
 When a controller is reused for the same `sectionId`/`attemptId`, `updateInput()` refreshes composition input while preserving in-memory section session data.
 
+## Content trust boundary
+
+Section-player layouts embed `<pie-item-player>` elements for each item.
+Item and passage markup is sanitized by default via DOMPurify; see
+[pie-item-player README](./README.md#content-trust-boundary)
+property. Hosts can forward those settings through the section-player
+`runtime.player` overrides — the runtime flattens these onto the embedded
+`<pie-item-player>` instance, so any field not recognized by the kernel is
+passed straight through as a prop/attribute:
+
+```ts
+const runtime = {
+  playerType: "iife",
+  player: {
+    trustMarkup: false, // default, keeps DOMPurify on
+    // sanitizeMarkup: (html) => myCustomSanitize(html),
+  },
+};
+```
+
+Set `trustMarkup: true` only when the section payload is guaranteed to be
+produced by a trusted pipeline.
+
 ## Exports
 
 Published exports are intentionally minimal:
@@ -340,15 +515,20 @@ Published exports are intentionally minimal:
 - `@pie-players/pie-section-player`
 - `@pie-players/pie-section-player/components/section-player-splitpane-element`
 - `@pie-players/pie-section-player/components/section-player-vertical-element`
+- `@pie-players/pie-section-player/components/section-player-tabbed-element`
 - `@pie-players/pie-section-player/components/section-player-kernel-host-element`
 - `@pie-players/pie-section-player/components/section-player-shell-element`
 - `@pie-players/pie-section-player/components/section-player-item-card-element`
 - `@pie-players/pie-section-player/components/section-player-passage-card-element`
+- `@pie-players/pie-section-player/components/section-player-items-pane-element`
+- `@pie-players/pie-section-player/components/section-player-passages-pane-element`
 - `@pie-players/pie-section-player/contracts/layout-contract`
 - `@pie-players/pie-section-player/contracts/public-events`
 - `@pie-players/pie-section-player/contracts/runtime-host-contract`
 - `@pie-players/pie-section-player/contracts/layout-parity-metadata`
+- `@pie-players/pie-section-player/contracts/host-hooks`
 - `@pie-players/pie-section-player/policies`
+- `@pie-players/pie-section-player/utils/player-preload`
 
 ## Development