@inventure71/paddockjs 0.1.0 → 0.3.0

package/src/ui/componentTemplates.js

@@ -2,6 +2,13 @@ function buttonHiddenAttribute(isVisible) {
   return isVisible ? '' : ' hidden';
 }
 
+let telemetryDrawerIdSequence = 0;
+
+function createTelemetryDrawerId() {
+  telemetryDrawerIdSequence += 1;
+  return `paddock-telemetry-drawer-${telemetryDrawerIdSequence}`;
+}
+
 function createLoadingMarkup(label = 'Loading') {
   return `
       <div class="paddock-loading" data-paddock-loading aria-label="${escapeHtml(label)} loading">
@@ -110,6 +117,7 @@ export function createCameraControlsMarkup({ embedded = false } = {}) {
 export function createRaceCanvasMarkup({
   includeRaceDataPanel = false,
   includeTimingTower = false,
+  includeTelemetrySectorBanner = false,
   timingTowerVerticalFit,
   assets,
   totalLaps,
@@ -147,6 +155,7 @@ export function createRaceCanvasMarkup({
       </div>
       ${showEmbeddedCameraControls ? createCameraControlsMarkup({ embedded: true }) : ''}
       ${includeRaceDataPanel ? createRaceDataPanelMarkup({ assets, ui }) : ''}
+      ${includeTelemetrySectorBanner ? createTelemetrySectorBannerMarkup({ ui }) : ''}
       <div class="race-finish-panel" data-race-finish-panel hidden aria-live="polite">
         <span>Race winner</span>
         <strong data-race-finish-winner>--</strong>
@@ -159,13 +168,17 @@ export function createRaceCanvasMarkup({
 
 export function createRaceDataPanelMarkup({ ui = {} } = {}) {
   const sizeMode = ui.raceDataBannerSize === 'auto' ? 'auto' : 'custom';
+  const telemetryDetail = Boolean(ui.raceDataTelemetryDetail);
+  const classNames = ['race-data-panel', `race-data-panel--${sizeMode}`];
+  if (telemetryDetail) classNames.push('race-data-panel--with-telemetry');
   return `
-    <div class="race-data-panel race-data-panel--${sizeMode}" data-paddock-component="race-data-panel" data-race-data-panel aria-live="polite">
+    <div class="${classNames.join(' ')}" data-paddock-component="race-data-panel" data-race-data-panel aria-live="polite">
       <div class="race-data-copy">
         <span class="race-data-kicker" data-race-data-kicker>Project</span>
         <strong data-race-data-title>Select driver</strong>
         <span class="race-data-subtitle" data-race-data-subtitle>Race entry</span>
       </div>
+      ${telemetryDetail ? createRaceDataTelemetryMarkup() : ''}
       <strong class="race-data-number" data-race-data-number>--</strong>
       <button class="race-data-link" type="button" data-race-data-open>Open project</button>
       ${createLoadingMarkup('Race data')}
@@ -173,6 +186,22 @@ export function createRaceDataPanelMarkup({ ui = {} } = {}) {
   `;
 }
 
+function createRaceDataTelemetryMarkup() {
+  return `
+      <div class="race-data-telemetry" data-race-data-telemetry aria-label="Project sector telemetry">
+        <span class="race-data-telemetry__label">Sectors</span>
+        <div class="race-data-telemetry__bars">
+          ${[1, 2, 3].map((sector) => `
+          <div class="telemetry-sector-bar race-data-sector-bar" data-telemetry-sector-bar="${sector}" style="--sector-fill: 0%">
+            <span>S${sector}</span>
+            <strong data-telemetry-sector-time="${sector}">--</strong>
+          </div>
+          `).join('')}
+        </div>
+      </div>
+  `;
+}
+
 export function createCarDriverOverviewMarkup({ assets }) {
   const cells = Array.from({ length: 7 }, (_, index) => `
           <div class="car-overview-cell car-overview-cell--slot-${index + 1}" data-overview-field data-overview-slot="${index}">
@@ -205,9 +234,33 @@ export function createCarDriverOverviewMarkup({ assets }) {
   `;
 }
 
-export function createTelemetryPanelMarkup(options, { includeOverview = options.ui?.telemetryIncludesOverview !== false } = {}) {
+function getTelemetryModules(ui = {}) {
+  const defaults = {
+    core: true,
+    sectors: true,
+    lapTimes: true,
+    sectorTimes: true,
+  };
+  const modules = ui.telemetryModules;
+  if (modules === false) return Object.fromEntries(Object.keys(defaults).map((name) => [name, false]));
+  if (Array.isArray(modules)) {
+    const requested = new Set(modules);
+    return Object.fromEntries(Object.keys(defaults).map((name) => [name, requested.has(name)]));
+  }
+  if (!modules || typeof modules !== 'object') return defaults;
+  return Object.fromEntries(Object.entries(defaults).map(([name, fallback]) => [
+    name,
+    modules[name] == null ? fallback : Boolean(modules[name]),
+  ]));
+}
+
+function getTelemetryModuleClass(componentName) {
+  return `sim-telemetry telemetry-component telemetry-component--${componentName}`;
+}
+
+export function createTelemetryCoreMarkup() {
   return `
-    <aside class="sim-telemetry" data-paddock-component="telemetry-panel" aria-label="Selected car telemetry">
+    <section class="${getTelemetryModuleClass('core')}" data-paddock-component="telemetry-core" aria-label="Selected car core telemetry">
       <div class="telemetry-header">
         <span data-selected-code>---</span>
         <strong data-selected-name>Select car</strong>
@@ -222,8 +275,152 @@ export function createTelemetryPanelMarkup(options, { includeOverview = options.
         <div><dt>Interval</dt><dd data-telemetry-gap>--</dd></div>
         <div><dt>Leader</dt><dd data-telemetry-leader-gap>--</dd></div>
       </dl>
+      ${createLoadingMarkup('Core telemetry')}
+    </section>
+  `;
+}
+
+export function createTelemetrySectorsMarkup() {
+  return `
+      <section class="${getTelemetryModuleClass('sectors')} telemetry-sector-strip" data-paddock-component="telemetry-sectors" data-telemetry-sector-strip aria-label="Sector progress">
+        <div class="telemetry-module-header">
+          <span>Sector map</span>
+          <strong data-telemetry-current-sector>S1</strong>
+        </div>
+        <div class="telemetry-sector-bars">
+          ${[1, 2, 3].map((sector) => `
+          <div class="telemetry-sector-bar" data-telemetry-sector-bar="${sector}" style="--sector-fill: 0%">
+            <span>S${sector}</span>
+            <strong data-telemetry-sector-time="${sector}">--</strong>
+          </div>
+          `).join('')}
+        </div>
+        ${createLoadingMarkup('Sector telemetry')}
+      </section>
+  `;
+}
+
+export function createTelemetrySectorBannerMarkup() {
+  return `
+      <section class="telemetry-sector-banner" data-paddock-component="telemetry-sector-banner" data-telemetry-sector-banner aria-label="Broadcast sector telemetry">
+        <div class="telemetry-sector-banner__copy">
+          <span><b data-selected-code>--</b> sector telemetry</span>
+          <strong data-selected-name>Select driver</strong>
+          <em data-telemetry-current-sector>S1</em>
+        </div>
+        <div class="telemetry-sector-banner__bars">
+          ${[1, 2, 3].map((sector) => `
+          <div class="telemetry-sector-bar" data-telemetry-sector-bar="${sector}" style="--sector-fill: 0%">
+            <span>S${sector}</span>
+            <strong data-telemetry-sector-time="${sector}">--</strong>
+          </div>
+          `).join('')}
+        </div>
+        ${createLoadingMarkup('Sector banner')}
+      </section>
+  `;
+}
+
+export function createTelemetryLapTimesMarkup() {
+  return `
+      <section class="${getTelemetryModuleClass('lap-times')} telemetry-lap-module" data-paddock-component="telemetry-lap-times" aria-label="Lap timing">
+        <div class="telemetry-module-header">
+          <span>Lap timing</span>
+          <strong data-telemetry-completed-laps>0 laps</strong>
+        </div>
+        <table class="telemetry-lap-table" data-telemetry-lap-table>
+          <tbody>
+            <tr><th scope="row">Current</th><td data-telemetry-current-lap-time>--</td></tr>
+            <tr><th scope="row">Last</th><td data-telemetry-last-lap-time>--</td></tr>
+            <tr><th scope="row">Best</th><td data-telemetry-best-lap-time>--</td></tr>
+          </tbody>
+        </table>
+        ${createLoadingMarkup('Lap telemetry')}
+      </section>
+  `;
+}
+
+export function createTelemetrySectorTimesMarkup() {
+  return `
+      <section class="${getTelemetryModuleClass('sector-times')} telemetry-sector-table-module" data-paddock-component="telemetry-sector-times" aria-label="Sector timing table">
+        <div class="telemetry-module-header">
+          <span>Sector timing</span>
+          <strong>Last / Best</strong>
+        </div>
+        <table class="telemetry-sector-table" data-telemetry-sector-table>
+          <thead>
+            <tr><th scope="col">Sector</th><th scope="col">Last</th><th scope="col">Best</th></tr>
+          </thead>
+          <tbody>
+            ${[1, 2, 3].map((sector) => `
+            <tr data-telemetry-sector-row="${sector}">
+              <th scope="row">S${sector}</th>
+              <td data-telemetry-sector-last="${sector}">--</td>
+              <td data-telemetry-sector-best="${sector}">--</td>
+            </tr>
+            `).join('')}
+          </tbody>
+        </table>
+        ${createLoadingMarkup('Sector table')}
+      </section>
+  `;
+}
+
+function createTelemetryComponentMarkup(options, modules = getTelemetryModules(options.ui)) {
+  return `
+      ${modules.core ? createTelemetryCoreMarkup(options) : ''}
+      ${modules.sectors ? createTelemetrySectorsMarkup(options) : ''}
+      ${modules.lapTimes ? createTelemetryLapTimesMarkup(options) : ''}
+      ${modules.sectorTimes ? createTelemetrySectorTimesMarkup(options) : ''}
+  `;
+}
+
+export function createTelemetryPanelMarkup(options, { includeOverview = options.ui?.telemetryIncludesOverview !== false } = {}) {
+  const modules = getTelemetryModules(options.ui);
+  return `
+    <aside class="telemetry-stack" data-paddock-component="telemetry-stack" aria-label="Selected car telemetry stack">
+      ${createTelemetryComponentMarkup(options, modules)}
       ${includeOverview ? createCarDriverOverviewMarkup(options) : ''}
-      ${createLoadingMarkup('Telemetry')}
     </aside>
   `;
 }
+
+export function createRaceTelemetryDrawerMarkup(options, {
+  timingTowerVerticalFit,
+  drawerInitiallyOpen = false,
+  raceDataTelemetryDetail = options.ui?.raceDataTelemetryDetail,
+} = {}) {
+  const openClass = drawerInitiallyOpen ? ' is-telemetry-open' : '';
+  const drawerId = createTelemetryDrawerId();
+  const drawerOptions = {
+    ...options,
+    ui: {
+      ...(options.ui ?? {}),
+      raceDataTelemetryDetail: Boolean(raceDataTelemetryDetail),
+    },
+  };
+  return `
+    <section class="race-telemetry-drawer${openClass}" data-paddock-component="race-telemetry-drawer" data-race-telemetry-drawer aria-label="Race view with telemetry drawer">
+      <div class="race-telemetry-drawer__race">
+        ${createRaceCanvasMarkup({
+          ...drawerOptions,
+          includeRaceDataPanel: true,
+          includeTimingTower: true,
+          timingTowerVerticalFit,
+        })}
+      </div>
+      <div class="race-telemetry-drawer__controls" aria-label="Race workbench controls">
+        ${createSafetyCarControlMarkup({ compact: true })}
+        <button class="telemetry-drawer-toggle" type="button" data-telemetry-drawer-toggle aria-expanded="${drawerInitiallyOpen ? 'true' : 'false'}" aria-controls="${drawerId}">
+          ${drawerInitiallyOpen ? 'Close telemetry' : 'Telemetry'}
+        </button>
+      </div>
+      <aside id="${drawerId}" class="telemetry-drawer" data-telemetry-drawer aria-label="Telemetry drawer" aria-hidden="${drawerInitiallyOpen ? 'false' : 'true'}"${drawerInitiallyOpen ? '' : ' inert'}>
+        <div class="telemetry-drawer__header" aria-hidden="true"></div>
+        <div class="telemetry-drawer__content">
+          ${createTelemetryComponentMarkup(options)}
+        </div>
+      </aside>
+    </section>
+  `;
+}

package/AGENTS.md

@@ -1,86 +0,0 @@
-# AGENTS.md
-
-## Project
-
-PaddockJS is an installable browser component package for an F1-style project race simulator.
-
-The package lives independently from the portfolio website. Host websites install it and mount it with:
-
-```js
-import { mountF1Simulator } from '@inventure71/paddockjs';
-```
-
-It can also be mounted as rearrangeable package-owned pieces with:
-
-```js
-import { createPaddockSimulator } from '@inventure71/paddockjs';
-```
-
-## What Is In This Repo
-
-- `src/index.js`: public package API.
-- `src/api/`: public composable mounting controller.
-- `src/app/`: browser runtime, DOM bindings, PixiJS app lifecycle, controls, readouts, and camera orchestration.
-- `src/config/`: default options and bundled default asset mapping.
-- `src/data/`: driver/project data normalization, driver/car pairing, rating conversion, and demo data.
-- `src/rendering/`: PixiJS track rendering helpers and render interpolation.
-- `src/simulation/`: race rules, driver AI, vehicle physics, track model, and math utilities.
-- `src/ui/`: generated markup for the all-in-one shell and individually mounted UI surfaces.
-- `src/__tests__/`: package tests.
-- `assets/`: simulator-owned default assets.
-- `docs/`: package specs and design documentation.
-- `INSTALL_AND_UPDATE.md`: install/update workflow.
-
-## Required Documentation Discipline
-
-When changing simulator behavior, update docs in the same change.
-
-Use this mapping:
-
-- Public API, lifecycle, install assumptions: update `docs/system_specs.md` and `README.md` if needed.
-- Race behavior, DRS, safety car, starts, physics, collisions: update `docs/rules.md`.
-- Vocabulary or domain model: update `docs/concepts.md`.
-- Driver/entry/options/assets callback shapes: update `docs/data_contract.md`.
-- Module ownership or data/control flow: update `docs/architecture.md`.
-- Local install/update workflow: update `INSTALL_AND_UPDATE.md`.
-
-Do not leave docs describing old behavior after code changes.
-
-## Linear Work Logging
-
-For any implementation that is more than a trivial/no-op change, log the work in the PaddockJS project on Linear.
-
-The Linear update must include:
-
-- what task was done
-- how it was solved
-- any important verification or remaining follow-up
-
-## Engineering Rules
-
-- Preserve the package boundary: PaddockJS should stay reusable and host-agnostic.
-- Host-specific routing belongs in `onDriverOpen(driver)`, not package internals.
-- Host-specific project data should be passed as `drivers` and `entries`, not hardcoded into the runtime.
-- The package should own default simulator assets so hosts do not need to copy them.
-- Treat the timing board width and broadcast proportions as package-owned. Do not resize or retune timing-board width as a casual fix; preserve its intended width and solve layout bugs through internal column/content constraints unless the user explicitly asks to redesign the timing board sizing.
-- Prefer small, focused modules when extracting from `F1SimulatorApp.js`.
-- Keep simulation logic deterministic for the same seed, track seed, drivers, entries, and rules.
-- Do not claim completion without running verification.
-
-## Verification
-
-Run before claiming package changes are complete:
-
-```bash
-npm run check
-```
-
-For portfolio integration changes, also run from the portfolio repo:
-
-```bash
-cd /Users/inventure71/VSProjects/Inventure71.github.io
-npm install ../PaddockJS
-npm run check
-```
-
-Browser behavior changes need a browser smoke test against the host page.

package/src/standalone.js

@@ -1,15 +0,0 @@
-import { DEMO_PROJECT_DRIVERS, mountF1Simulator } from './index.js';
-
-const root = document.getElementById('f1-simulator-root');
-
-if (root) {
-  mountF1Simulator(root, {
-    drivers: DEMO_PROJECT_DRIVERS,
-    onDriverOpen(driver) {
-      if (driver.link) window.location.href = driver.link;
-    },
-  }).catch((error) => {
-    root.dataset.simulatorState = 'error';
-    console.error('F1 simulator failed to initialize.', error);
-  });
-}