@joewinke/jatui 0.32.0 → 0.34.0

package/dist/components/review/mediaZoom.js

@@ -0,0 +1,161 @@
+/**
+ * mediaZoom — the pure core of MediaZoomLightbox (jatui-c79nt, ported from
+ * mardukos media-picker/zoom.ts, mos-0wvol).
+ *
+ * Zoom/pan math, frame stepping, view/item paging and the key table. The
+ * transform is `translate(x, y) scale(s)` on a wrapper whose origin is the
+ * stage centre, so every geometry helper works in stage-centred pixels.
+ * No DOM — every helper here is unit-tested in isolation.
+ *
+ * The key table (`MEDIA_ZOOM_KEYS`) is the single source for BOTH the
+ * keydown handler (`resolveMediaZoomKey`) and the on-screen hint
+ * (`mediaZoomHint`), so the documented keys can't drift from the behaviour
+ * (docs/review-ux/proposal.md → "One keyboard map").
+ */
+export const MIN_ZOOM = 1;
+export const MAX_ZOOM = 8;
+export const ZOOM_STEP = 1.25;
+export const ZOOM_IDENTITY = Object.freeze({ scale: 1, x: 0, y: 0 });
+/** Frame step: the asset's fps is unknown to the page; review loops are 30fps. */
+export const DEFAULT_FPS = 30;
+export const DEFAULT_SPEEDS = [0.25, 0.5, 0.75, 1];
+export function clampScale(s) {
+    if (!Number.isFinite(s))
+        return MIN_ZOOM;
+    return Math.min(MAX_ZOOM, Math.max(MIN_ZOOM, s));
+}
+/** Keep the content covering the stage: at scale s the slack is (s-1)·w/2. */
+export function clampPan(z, w, h) {
+    const mx = ((z.scale - 1) * w) / 2;
+    const my = ((z.scale - 1) * h) / 2;
+    return {
+        scale: z.scale,
+        x: Math.min(mx, Math.max(-mx, z.x)),
+        y: Math.min(my, Math.max(-my, z.y))
+    };
+}
+/**
+ * Zoom by `factor` keeping the point (cx, cy) — stage-centred px — fixed
+ * under the pointer. Back at scale 1 the pan resets.
+ */
+export function zoomAt(z, factor, cx, cy, w, h) {
+    const scale = clampScale(z.scale * factor);
+    if (scale === MIN_ZOOM)
+        return { ...ZOOM_IDENTITY };
+    const k = scale / z.scale;
+    return clampPan({ scale, x: cx - (cx - z.x) * k, y: cy - (cy - z.y) * k }, w, h);
+}
+export function panBy(z, dx, dy, w, h) {
+    if (z.scale <= MIN_ZOOM)
+        return z;
+    return clampPan({ scale: z.scale, x: z.x + dx, y: z.y + dy }, w, h);
+}
+/** Wheel delta → multiplicative zoom factor (smooth on trackpads too). */
+export function wheelFactor(deltaY) {
+    return Math.exp(-deltaY * 0.0015);
+}
+export function zoomTransform(z) {
+    return `translate(${z.x}px, ${z.y}px) scale(${z.scale})`;
+}
+/** `m:ss.cc` — sub-second precision because frame-stepping is the point. */
+export function formatMediaTime(sec) {
+    if (!Number.isFinite(sec) || sec < 0)
+        sec = 0;
+    const m = Math.floor(sec / 60);
+    const s = sec - m * 60;
+    return `${m}:${s.toFixed(2).padStart(5, '0')}`;
+}
+/** Move `frames` frames from `time`, clamped to [0, duration]. */
+export function stepFrameTime(time, frames, duration, fps = DEFAULT_FPS) {
+    const rate = Number.isFinite(fps) && fps > 0 ? fps : DEFAULT_FPS;
+    const max = Number.isFinite(duration) && duration > 0 ? duration : Infinity;
+    const base = Number.isFinite(time) ? time : 0;
+    return Math.min(max, Math.max(0, base + frames / rate));
+}
+export function clampIndex(i, length) {
+    if (length <= 0 || !Number.isFinite(i))
+        return 0;
+    return Math.min(Math.max(0, Math.trunc(i)), length - 1);
+}
+export function stepView(index, delta, length, opts = {}) {
+    const next = index + delta;
+    if (next >= 0 && next < length)
+        return { kind: 'view', index: next };
+    if (delta > 0 && opts.hasNextItem)
+        return { kind: 'item', dir: 1 };
+    if (delta < 0 && opts.hasPrevItem)
+        return { kind: 'item', dir: -1 };
+    if (length < 2)
+        return { kind: 'none' };
+    return { kind: 'view', index: (next + length) % length };
+}
+/**
+ * j/k and ↓/↑ page ITEMS (the review-wide "next / previous item" keys), ←/→
+ * page VIEWS and spill into items at an edge, 1–9 pick a view. Verdict keys
+ * (a/x/r/b/u/n), rounds ([ / ]) and `?` are deliberately absent: they bubble
+ * out to the host, which owns them (the footer snippet renders VerdictControl).
+ * `k` is NOT play/pause here (it was in the MOS port) — it is "previous item".
+ */
+export const MEDIA_ZOOM_KEYS = [
+    { action: 'play-pause', keys: [' '], label: 'Space', description: 'play/pause', video: true },
+    { action: 'frame-back', keys: [','], label: ',', description: 'frame back', video: true },
+    { action: 'frame-forward', keys: ['.'], label: '.', description: 'frame forward', video: true },
+    { action: 'slower', keys: ['<'], label: '<', description: 'slower', video: true },
+    { action: 'faster', keys: ['>'], label: '>', description: 'faster', video: true },
+    { action: 'loop', keys: ['l', 'L'], label: 'L', description: 'loop', video: true },
+    { action: 'zoom-in', keys: ['+', '='], label: '+', description: 'zoom in' },
+    { action: 'zoom-out', keys: ['-', '_'], label: '−', description: 'zoom out' },
+    { action: 'zoom-reset', keys: ['0'], label: '0', description: 'fit' },
+    { action: 'prev-view', keys: ['ArrowLeft'], label: '←', description: 'previous view' },
+    { action: 'next-view', keys: ['ArrowRight'], label: '→', description: 'next view' },
+    { action: 'pick-view', keys: ['1', '2', '3', '4', '5', '6', '7', '8', '9'], label: '1–9', description: 'pick view', views: true },
+    { action: 'next-item', keys: ['j', 'J', 'ArrowDown'], label: 'j', description: 'next item', items: true },
+    { action: 'prev-item', keys: ['k', 'K', 'ArrowUp'], label: 'k', description: 'previous item', items: true },
+    { action: 'close', keys: ['Escape'], label: 'Esc', description: 'close' }
+];
+function applies(def, ctx) {
+    if (def.video && !ctx.isVideo)
+        return false;
+    if (def.items && !ctx.hasItems)
+        return false;
+    if (def.views && ctx.viewCount < 2)
+        return false;
+    return true;
+}
+/** keydown `key` → the action it triggers in this context, or null (let it bubble). */
+export function resolveMediaZoomKey(key, ctx) {
+    for (const def of MEDIA_ZOOM_KEYS) {
+        if (def.keys.includes(key) && applies(def, ctx))
+            return def.action;
+    }
+    return null;
+}
+/** The keys that work right now, for the on-screen hint. */
+export function mediaZoomKeys(ctx) {
+    return MEDIA_ZOOM_KEYS.filter((def) => {
+        if (!applies(def, ctx))
+            return false;
+        // ←/→ with a single view and no item paging do nothing.
+        if ((def.action === 'prev-view' || def.action === 'next-view') && ctx.viewCount < 2 && !ctx.hasItems)
+            return false;
+        return true;
+    });
+}
+/** One-line hint built from the key table: "Space play/pause · , frame back · …". */
+export function mediaZoomHint(ctx) {
+    const parts = mediaZoomKeys(ctx).map((d) => `${d.label} ${d.description}`);
+    parts.push('wheel/pinch zoom, drag to pan');
+    return parts.join(' · ');
+}
+/** The next/previous entry in `speeds` from `current` (clamped at the ends). */
+export function stepSpeed(current, dir, speeds = DEFAULT_SPEEDS) {
+    if (speeds.length === 0)
+        return current;
+    const sorted = [...speeds].sort((a, b) => a - b);
+    if (dir > 0)
+        return sorted.find((s) => s > current + 1e-9) ?? sorted[sorted.length - 1];
+    for (let i = sorted.length - 1; i >= 0; i--)
+        if (sorted[i] < current - 1e-9)
+            return sorted[i];
+    return sorted[0];
+}

package/dist/components/review/reviewSummary.d.ts

@@ -0,0 +1,101 @@
+/**
+ * reviewSummary — the pure half of RoundHistory / ReviewProgress /
+ * ReviewFilterBar (jatui-xmrod, design mos-z8vgx docs/review-ux/proposal.md).
+ *
+ * No DOM, no runes: counting, the progress sentence, the standard filter set
+ * and round ordering live here so a host can compute the same numbers the
+ * components render (and tests can pin them without mounting anything).
+ *
+ * Verdicts are GENERIC: every block passes its own `{id, label, tone}` list
+ * (Pass/Fail/Blocked for a runbook, Approve/Needs work/Reject for a gallery).
+ * Nothing here knows any verdict id.
+ */
+/** Semantic colour of a verdict. Maps to the theme's status colours. */
+export type ReviewTone = 'success' | 'warning' | 'error' | 'info' | 'primary' | 'neutral';
+/** One verdict a block offers. Shape-compatible with VerdictControl options. */
+export interface ReviewVerdictDef {
+    id: string;
+    label: string;
+    tone: ReviewTone;
+}
+/** Counts of decided items keyed by verdict id. Unknown ids are ignored. */
+export type ReviewCounts = Record<string, number>;
+/** One locked, read-only line of an item's history. */
+export interface ReviewRound {
+    /** Round key — a version id ("v7") or a retestSince timestamp. Unique per item. */
+    round: string;
+    /** Verdict id given in that round, or null/undefined when it closed undecided. */
+    verdict?: string | null;
+    note?: string | null;
+    /** When the verdict was given — Date, ISO string or epoch ms. */
+    at?: Date | string | number | null;
+    /** Display label override ("v7"); defaults to "Round N". */
+    label?: string;
+}
+/** One chip of a ReviewFilterBar. */
+export interface ReviewFilterChip {
+    id: string;
+    label: string;
+    count: number;
+    tone?: ReviewTone;
+}
+export interface ReviewSummary {
+    total: number;
+    /** Items with a known verdict (clamped to total). */
+    decided: number;
+    undecided: number;
+    retest: number;
+    /** Per-verdict segments in `verdicts` order, zero counts dropped. */
+    segments: {
+        id: string;
+        label: string;
+        tone: ReviewTone;
+        count: number;
+    }[];
+}
+/**
+ * Sum per-block counts into one page-level count — the "aggregated
+ * ReviewProgress" in the Finish bar. Pass any number of count maps.
+ */
+export declare function mergeReviewCounts(...parts: (ReviewCounts | null | undefined)[]): ReviewCounts;
+/**
+ * Normalise counts against the verdict list and the item total. Decided is
+ * clamped to `total`, so a stale count can never draw a bar past 100%.
+ */
+export declare function summarizeReview(verdicts: readonly ReviewVerdictDef[], counts: ReviewCounts, total: number, retest?: number): ReviewSummary;
+/**
+ * "12 of 19 decided · 9 pass · 2 fail · 1 blocked · 4 to retest".
+ * Zero-count parts are omitted; verdict labels are lower-cased.
+ */
+export declare function reviewSentence(summary: ReviewSummary, decidedWord?: string): string;
+export interface BuildFiltersInput {
+    verdicts: readonly ReviewVerdictDef[];
+    counts: ReviewCounts;
+    total: number;
+    /** Items waiting on this viewer (retest first, then undecided). Omit to skip the chip. */
+    needsYou?: number;
+    /** Items in an open retest round. Omit to skip the chip. */
+    retest?: number;
+    /** Drop chips whose count is 0 (All is always kept). Default true. */
+    hideEmpty?: boolean;
+}
+/**
+ * The standard chip set, in the design's order:
+ * All · Needs you · Undecided · one per verdict · Retest.
+ * Ids are `all`, `needs-you`, `undecided`, the verdict id, `retest`.
+ */
+export declare function buildReviewFilters(input: BuildFiltersInput): ReviewFilterChip[];
+/**
+ * Rounds newest first, each paired with its 1-based chronological number.
+ * When every round has a parseable `at` they are ordered by it; otherwise the
+ * input is taken as append order (oldest first — how `history[]` grows).
+ */
+export declare function orderRounds(rounds: readonly ReviewRound[]): {
+    entry: ReviewRound;
+    n: number;
+}[];
+/** "Oct 10" (same year) / "Oct 10, 2025" — empty for a missing/invalid date. */
+export declare function formatRoundDate(at: ReviewRound['at'], now?: Date): string;
+/** DaisyUI status-colour background per tone — kept here so all three components agree. */
+export declare const TONE_BG: Record<ReviewTone, string>;
+export declare const TONE_TEXT: Record<ReviewTone, string>;

package/dist/components/review/reviewSummary.js

@@ -0,0 +1,122 @@
+/**
+ * reviewSummary — the pure half of RoundHistory / ReviewProgress /
+ * ReviewFilterBar (jatui-xmrod, design mos-z8vgx docs/review-ux/proposal.md).
+ *
+ * No DOM, no runes: counting, the progress sentence, the standard filter set
+ * and round ordering live here so a host can compute the same numbers the
+ * components render (and tests can pin them without mounting anything).
+ *
+ * Verdicts are GENERIC: every block passes its own `{id, label, tone}` list
+ * (Pass/Fail/Blocked for a runbook, Approve/Needs work/Reject for a gallery).
+ * Nothing here knows any verdict id.
+ */
+const nonNeg = (n) => (typeof n === 'number' && Number.isFinite(n) && n > 0 ? Math.floor(n) : 0);
+/**
+ * Sum per-block counts into one page-level count — the "aggregated
+ * ReviewProgress" in the Finish bar. Pass any number of count maps.
+ */
+export function mergeReviewCounts(...parts) {
+    const out = {};
+    for (const part of parts) {
+        if (!part)
+            continue;
+        for (const [id, n] of Object.entries(part)) {
+            const v = nonNeg(n);
+            if (v)
+                out[id] = (out[id] ?? 0) + v;
+        }
+    }
+    return out;
+}
+/**
+ * Normalise counts against the verdict list and the item total. Decided is
+ * clamped to `total`, so a stale count can never draw a bar past 100%.
+ */
+export function summarizeReview(verdicts, counts, total, retest = 0) {
+    const t = nonNeg(total);
+    let remaining = t;
+    const segments = [];
+    for (const v of verdicts) {
+        const n = Math.min(nonNeg(counts[v.id]), remaining);
+        if (!n)
+            continue;
+        remaining -= n;
+        segments.push({ id: v.id, label: v.label, tone: v.tone, count: n });
+    }
+    const decided = t - remaining;
+    return { total: t, decided, undecided: remaining, retest: Math.min(nonNeg(retest), t), segments };
+}
+/**
+ * "12 of 19 decided · 9 pass · 2 fail · 1 blocked · 4 to retest".
+ * Zero-count parts are omitted; verdict labels are lower-cased.
+ */
+export function reviewSentence(summary, decidedWord = 'decided') {
+    const parts = [`${summary.decided} of ${summary.total} ${decidedWord}`];
+    for (const s of summary.segments)
+        parts.push(`${s.count} ${s.label.toLowerCase()}`);
+    if (summary.retest)
+        parts.push(`${summary.retest} to retest`);
+    return parts.join(' · ');
+}
+/**
+ * The standard chip set, in the design's order:
+ * All · Needs you · Undecided · one per verdict · Retest.
+ * Ids are `all`, `needs-you`, `undecided`, the verdict id, `retest`.
+ */
+export function buildReviewFilters(input) {
+    const { verdicts, counts, total, needsYou, retest, hideEmpty = true } = input;
+    const sum = summarizeReview(verdicts, counts, total);
+    const chips = [{ id: 'all', label: 'All', count: sum.total }];
+    if (needsYou != null)
+        chips.push({ id: 'needs-you', label: 'Needs you', count: nonNeg(needsYou) });
+    chips.push({ id: 'undecided', label: 'Undecided', count: sum.undecided });
+    for (const v of verdicts)
+        chips.push({ id: v.id, label: v.label, tone: v.tone, count: nonNeg(counts[v.id]) });
+    if (retest != null)
+        chips.push({ id: 'retest', label: 'Retest', count: nonNeg(retest) });
+    return hideEmpty ? chips.filter((c) => c.id === 'all' || c.count > 0) : chips;
+}
+const toMs = (at) => {
+    if (at == null)
+        return NaN;
+    return at instanceof Date ? at.getTime() : new Date(at).getTime();
+};
+/**
+ * Rounds newest first, each paired with its 1-based chronological number.
+ * When every round has a parseable `at` they are ordered by it; otherwise the
+ * input is taken as append order (oldest first — how `history[]` grows).
+ */
+export function orderRounds(rounds) {
+    const indexed = rounds.map((entry, i) => ({ entry, i, ms: toMs(entry.at) }));
+    const allTimed = indexed.length > 0 && indexed.every((r) => Number.isFinite(r.ms));
+    const chrono = allTimed ? [...indexed].sort((a, b) => a.ms - b.ms || a.i - b.i) : indexed;
+    return chrono.map((r, k) => ({ entry: r.entry, n: k + 1 })).reverse();
+}
+/** "Oct 10" (same year) / "Oct 10, 2025" — empty for a missing/invalid date. */
+export function formatRoundDate(at, now = new Date()) {
+    const ms = toMs(at);
+    if (!Number.isFinite(ms))
+        return '';
+    const d = new Date(ms);
+    const opts = { month: 'short', day: 'numeric' };
+    if (d.getFullYear() !== now.getFullYear())
+        opts.year = 'numeric';
+    return d.toLocaleDateString(undefined, opts);
+}
+/** DaisyUI status-colour background per tone — kept here so all three components agree. */
+export const TONE_BG = {
+    success: 'bg-success',
+    warning: 'bg-warning',
+    error: 'bg-error',
+    info: 'bg-info',
+    primary: 'bg-primary',
+    neutral: 'bg-neutral'
+};
+export const TONE_TEXT = {
+    success: 'text-success',
+    warning: 'text-warning',
+    error: 'text-error',
+    info: 'text-info',
+    primary: 'text-primary',
+    neutral: 'text-base-content/70'
+};

package/dist/index.d.ts

@@ -284,3 +284,17 @@ export { default as BottomSheet } from './components/BottomSheet.svelte';
 export { default as VariantMatrixPicker } from './components/variant/VariantMatrixPicker.svelte';
 export { countCombinations, generateCombinations, generateVariantFilename, findVariantOption, variantCategoryMode } from './components/variant/variantCombinations';
 export type { VariantCategory, VariantOption, VariantSelection, VariantSelectionMode, VariantCombination } from './components/variant/variantCombinations';
+export { default as VerdictControl } from './components/review/VerdictControl.svelte';
+export { default as ReviewNote, NOTE_HINT } from './components/review/ReviewNote.svelte';
+export type { ReviewNoteSaveState } from './components/review/ReviewNote.svelte';
+export { default as ReviewShortcuts } from './components/review/ReviewShortcuts.svelte';
+export { default as RoundHistory } from './components/review/RoundHistory.svelte';
+export { default as ReviewProgress } from './components/review/ReviewProgress.svelte';
+export { default as ReviewFilterBar } from './components/review/ReviewFilterBar.svelte';
+export { default as MediaZoomLightbox } from './components/review/MediaZoomLightbox.svelte';
+export { reviewKeys, createReviewKeys, reviewKeyRows, resolveReviewKey, REVIEW_KEY_TABLE } from './actions/reviewKeys';
+export type { VerdictTone, VerdictOption, NeedsYou, ReviewKeyAction, ReviewKeyEntry, ReviewKeysOptions, ReviewKeyRow, ReviewKeysController } from './actions/reviewKeys';
+export { mergeReviewCounts, summarizeReview, reviewSentence, buildReviewFilters, orderRounds, formatRoundDate } from './components/review/reviewSummary';
+export type { ReviewTone, ReviewVerdictDef, ReviewCounts, ReviewRound, ReviewFilterChip, ReviewSummary, BuildFiltersInput } from './components/review/reviewSummary';
+export { MEDIA_ZOOM_KEYS, mediaZoomHint } from './components/review/mediaZoom';
+export type { MediaZoomState, MediaZoomView, MediaZoomFooterContext, MediaZoomAction, MediaZoomKeyDef, MediaZoomKeyContext } from './components/review/mediaZoom';

package/dist/index.js

@@ -336,3 +336,15 @@ export { default as BottomSheet } from './components/BottomSheet.svelte';
 // Variant matrix picker + combination algebra (harvested from vid-gen FrameVariantGenerator — jatui-m4uz3.8).
 export { default as VariantMatrixPicker } from './components/variant/VariantMatrixPicker.svelte';
 export { countCombinations, generateCombinations, generateVariantFilename, findVariantOption, variantCategoryMode } from './components/variant/variantCombinations';
+// Review primitives (MOS epic mos-lsmve — jatui-et7pm/xmrod/c79nt, exported by jatui-2h5v9).
+// Full surface (incl. zoom/pan math and tone class maps) on the 'jatui/review' subpath.
+export { default as VerdictControl } from './components/review/VerdictControl.svelte';
+export { default as ReviewNote, NOTE_HINT } from './components/review/ReviewNote.svelte';
+export { default as ReviewShortcuts } from './components/review/ReviewShortcuts.svelte';
+export { default as RoundHistory } from './components/review/RoundHistory.svelte';
+export { default as ReviewProgress } from './components/review/ReviewProgress.svelte';
+export { default as ReviewFilterBar } from './components/review/ReviewFilterBar.svelte';
+export { default as MediaZoomLightbox } from './components/review/MediaZoomLightbox.svelte';
+export { reviewKeys, createReviewKeys, reviewKeyRows, resolveReviewKey, REVIEW_KEY_TABLE } from './actions/reviewKeys';
+export { mergeReviewCounts, summarizeReview, reviewSentence, buildReviewFilters, orderRounds, formatRoundDate } from './components/review/reviewSummary';
+export { MEDIA_ZOOM_KEYS, mediaZoomHint } from './components/review/mediaZoom';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joewinke/jatui",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",
@@ -68,6 +68,11 @@
       "types": "./dist/meet/index.d.ts",
       "svelte": "./dist/meet/index.js",
       "default": "./dist/meet/index.js"
+    },
+    "./review": {
+      "types": "./dist/components/review/index.d.ts",
+      "svelte": "./dist/components/review/index.js",
+      "default": "./dist/components/review/index.js"
     }
   },
   "files": [