@dloizides/ui-carousel 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0
+
+First release.
+
+- `CardDeck` — one card at a time with a verdict row, a back control and a progress line.
+- `useDeck` — all deck logic, no rendering: advance, complete, answered-once, keyboard routing.
+- `Card` / `RankBar` — the presentation halves, both themed from the UiProvider.
+- `Pressable` throughout (never `TouchableOpacity`, whose hover callbacks RN-web drops), with a
+  test that greps `src` so the regression cannot land silently.
+- A single in-flight latch guards every verdict emission, so a keyboard activation plus the click
+  a browser synthesizes from it counts once. Asserted at both the hook and the component level.
+- Keyboard: `1`..`9` rank, `Backspace` / `ArrowLeft` step back. Fully operable without a pointer.
+- No colour literals in `src`, enforced by a test.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 dloizides
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# @dloizides/ui-carousel
+
+A themable, brand-agnostic React Native (RN-web) **card deck with per-card ranking**: one card at
+a time, a row of verdict buttons, and a keyboard path that reaches every one of them.
+
+```tsx
+import { CardDeck } from '@dloizides/ui-carousel';
+
+<CardDeck
+  cards={cards}
+  verdicts={['loved', 'liked', 'bounced', 'never']}
+  onVerdict={(cardId, verdict) => record(cardId, verdict)}
+  onComplete={() => goToResults()}
+  testID="quiz-deck"
+  labels={{
+    verdictLabels: { loved: FM('quiz.loved'), liked: FM('quiz.liked') },
+    verdictHints: { loved: FM('quiz.lovedHint'), liked: FM('quiz.likedHint') },
+    backLabel: FM('quiz.back'),
+    backHint: FM('quiz.backHint'),
+    progress: (position, total) => FM('quiz.progress', String(position), String(total)),
+  }}
+/>;
+```
+
+## Why this is a package and not app code
+
+Two RN-web traps have cost this estate real defects. Both are handled once, here:
+
+1. **`TouchableOpacity` silently drops `onHoverIn` / `onHoverOut` on RN-web.** A hover affordance
+   written that way is dead on the web build with nothing in the console to find it by. This
+   package uses `Pressable` (via `@dloizides/ui-motion`'s `PressableScale`) and a test greps `src`
+   to prove `TouchableOpacity` never comes back.
+2. **Keyboard activation does not arrive as `onPress`.** The browser can deliver the key event AND
+   synthesize a click from the same press, which lands two verdicts in one tick. Every emission
+   passes a single in-flight latch in `useDeck` that is released only after React commits the
+   advance, so the second path is a no-op. `useDeck.test.ts` asserts the double-fire case directly.
+
+## Keyboard contract
+
+| Key | Effect |
+|---|---|
+| `1` .. `9` | rank the current card with the nth verdict (**verdict order is the contract**) |
+| `Backspace`, `ArrowLeft` | step back one card |
+
+A card is ranked **exactly once**. Stepping back shows a ranked card, it does not reopen it, so
+navigating back and forth cannot re-emit a verdict the caller has already recorded.
+
+## Theming and copy
+
+Colours come from the app's UiProvider theme (`@dloizides/ui-feedback`, fed by
+`@dloizides/design-tokens`). There is not one colour literal in `src`, and a test enforces it.
+
+The kit has no i18n. Every string arrives already localized through `labels`; a missing entry falls
+back to the verdict id, which is machine-readable rather than untranslated English.
+
+## Accessibility
+
+Every interactive control carries `testID` + `accessibilityLabel` + `accessibilityHint`, and the
+deck is fully operable by keyboard alone. A deck that only works by swipe is not accessible.
+
+## Exports
+
+`CardDeck` · `Card` · `RankBar` · `useDeck` · `DECK_TEST_ID_SUFFIX` · `digitToVerdictIndex`
+· types `CardDeckProps`, `DeckCard`, `DeckLabels`, `UseDeckOptions`, `UseDeckResult`.
+
+## Peer dependencies
+
+`react` >= 18 · `react-native` >= 0.74 · `@dloizides/ui-feedback` >= 1.2 (the theme provider).
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,159 @@
+import React from 'react';
+
+/**
+ * Public shapes for `@dloizides/ui-carousel`.
+ *
+ * `CardDeckProps` is fixed by the consuming spec. Every extra prop is OPTIONAL, so a
+ * caller that knows only the five required fields keeps compiling.
+ */
+/** One card in the deck. Presentation only: the deck never fetches anything. */
+interface DeckCard {
+    id: string;
+    title: string;
+    imageUrl?: string;
+    subtitle?: string;
+}
+/**
+ * Caller-supplied, already-localized copy. The kit has no i18n of its own (apps own
+ * `FM()`), so every string the deck renders arrives from here. A missing entry falls
+ * back to the verdict id, which is machine-readable rather than English prose.
+ */
+interface DeckLabels {
+    /** Per-verdict button label, keyed by verdict id. */
+    verdictLabels?: Readonly<Record<string, string>>;
+    /** Per-verdict `accessibilityHint`, keyed by verdict id. */
+    verdictHints?: Readonly<Record<string, string>>;
+    /** Label for the "go back one card" control. */
+    backLabel?: string;
+    /** Hint for the "go back one card" control. */
+    backHint?: string;
+    /** Progress line, e.g. "3 / 12". Receives the 1-based position and the total. */
+    progress?: (position: number, total: number) => string;
+    /** Label announced on the card region itself. Receives the card title. */
+    cardLabel?: (title: string) => string;
+    /** Hint announced on the card region (how to rank it). */
+    cardHint?: string;
+}
+interface CardDeckProps {
+    cards: DeckCard[];
+    /** Ordered verdict ids. Keyboard 1..n selects the nth, so ORDER IS THE CONTRACT. */
+    verdicts: readonly string[];
+    onVerdict: (cardId: string, verdict: string) => void;
+    onComplete: () => void;
+    testID: string;
+    /** Already-localized copy. Optional: verdict ids are used when a string is missing. */
+    labels?: DeckLabels;
+}
+
+/**
+ * CardDeck — a ranked card deck that is fully operable by keyboard alone.
+ *
+ * `1..n` rank the current card with the nth verdict, `Backspace` / `ArrowLeft` step
+ * back. The listener is attached to the document on web, so the deck works without
+ * the user having to tab into it first; every verdict still routes through the same
+ * `useDeck.submitVerdict`, which holds the single in-flight latch. That is what stops
+ * a browser-synthesized click from turning one key press into two verdicts.
+ *
+ * Colours come from the app UiProvider theme (`@dloizides/design-tokens`). There is not
+ * one colour literal in this package.
+ */
+
+declare const CardDeck: ({ cards, verdicts, onVerdict, onComplete, testID, labels, }: CardDeckProps) => React.ReactElement;
+
+/**
+ * Card — the presentation face of one deck entry.
+ *
+ * Deliberately NOT interactive: ranking happens in `RankBar`, so there is exactly one
+ * place a verdict can be emitted from. `imageUrl` is optional and a missing cover
+ * renders as a typographic card rather than a broken image box.
+ */
+
+interface CardProps {
+    card: DeckCard;
+    testID: string;
+    imageTestID: string;
+    /** Already-localized region label. Falls back to the card title. */
+    accessibilityLabel?: string;
+    /** Already-localized region hint telling the user how to rank. */
+    accessibilityHint?: string;
+}
+declare const Card: ({ card, testID, imageTestID, accessibilityLabel, accessibilityHint, }: CardProps) => React.ReactElement;
+
+/**
+ * RankBar — the verdict buttons, the back control and the progress line.
+ *
+ * Built on `PressableScale` (a `Pressable`), NEVER `TouchableOpacity`: RN-web silently
+ * drops `onHoverIn` / `onHoverOut` on TouchableOpacity, so a hover affordance written
+ * that way is dead on the web build with no error to find it by.
+ *
+ * Every control carries testID + accessibilityLabel + accessibilityHint. The labels are
+ * caller-supplied and already localized; a missing one falls back to the verdict id.
+ */
+
+interface RankBarProps {
+    verdicts: readonly string[];
+    labels?: DeckLabels;
+    onSelect: (verdict: string) => void;
+    onBack: () => void;
+    canGoBack: boolean;
+    /** 1-based position of the current card. */
+    position: number;
+    total: number;
+    testID: string;
+    backTestID: string;
+    progressTestID: string;
+    verdictTestIDPrefix: string;
+}
+declare const RankBar: ({ verdicts, labels, onSelect, onBack, canGoBack, position, total, testID, backTestID, progressTestID, verdictTestIDPrefix, }: RankBarProps) => React.ReactElement;
+
+interface UseDeckOptions {
+    cards: DeckCard[];
+    /** Ordered verdict ids. Keyboard 1..n selects the nth. */
+    verdicts: readonly string[];
+    onVerdict: (cardId: string, verdict: string) => void;
+    onComplete: () => void;
+}
+interface UseDeckResult {
+    /** 0-based position. Equals `cards.length` once the deck is finished. */
+    index: number;
+    /** The card awaiting a verdict, or `undefined` when the deck is finished. */
+    current: DeckCard | undefined;
+    total: number;
+    isComplete: boolean;
+    /** cardId to verdict, for every card ranked so far. */
+    answered: Readonly<Record<string, string>>;
+    /** Rank the current card. Ignored when it is already ranked or an emission is in flight. */
+    submitVerdict: (verdict: string) => void;
+    /** Step back one card. A no-op on the first card. */
+    goBack: () => void;
+    /** Route a raw key name from keydown. Returns true when the deck consumed it. */
+    handleKey: (key: string) => boolean;
+    /**
+     * Release the keyboard-activation latch. Bind to keyup: the click a browser
+     * synthesizes from a key press arrives BEFORE keyup, which is what makes this the
+     * window that suppresses it.
+     */
+    releaseKeyboardActivation: () => void;
+}
+declare function useDeck({ cards, verdicts, onVerdict, onComplete }: UseDeckOptions): UseDeckResult;
+
+/** Test ids, key names and layout metrics for the deck. Nothing here is a colour. */
+/** Stable test id suffixes. Each is appended to the caller-supplied `testID`. */
+declare const DECK_TEST_ID_SUFFIX: {
+    readonly card: "card";
+    readonly image: "card-image";
+    readonly rankBar: "rank-bar";
+    readonly verdict: "verdict";
+    readonly back: "back";
+    readonly progress: "progress";
+    readonly complete: "complete";
+};
+/** Keys that navigate rather than rank. */
+declare const KEY_BACK = "Backspace";
+declare const KEY_ARROW_LEFT = "ArrowLeft";
+/** Digit keys 1..9 pick the nth verdict. The deck never exposes more than nine. */
+declare const MAX_KEYBOARD_VERDICTS = 9;
+/** Parse a 1..9 digit key into a 0-based verdict index, or -1 when it is not one. */
+declare const digitToVerdictIndex: (key: string) => number;
+
+export { Card, CardDeck, type CardDeckProps, type CardProps, DECK_TEST_ID_SUFFIX, type DeckCard, type DeckLabels, KEY_ARROW_LEFT, KEY_BACK, MAX_KEYBOARD_VERDICTS, RankBar, type RankBarProps, type UseDeckOptions, type UseDeckResult, digitToVerdictIndex, useDeck };

package/dist/index.d.ts

@@ -0,0 +1,159 @@
+import React from 'react';
+
+/**
+ * Public shapes for `@dloizides/ui-carousel`.
+ *
+ * `CardDeckProps` is fixed by the consuming spec. Every extra prop is OPTIONAL, so a
+ * caller that knows only the five required fields keeps compiling.
+ */
+/** One card in the deck. Presentation only: the deck never fetches anything. */
+interface DeckCard {
+    id: string;
+    title: string;
+    imageUrl?: string;
+    subtitle?: string;
+}
+/**
+ * Caller-supplied, already-localized copy. The kit has no i18n of its own (apps own
+ * `FM()`), so every string the deck renders arrives from here. A missing entry falls
+ * back to the verdict id, which is machine-readable rather than English prose.
+ */
+interface DeckLabels {
+    /** Per-verdict button label, keyed by verdict id. */
+    verdictLabels?: Readonly<Record<string, string>>;
+    /** Per-verdict `accessibilityHint`, keyed by verdict id. */
+    verdictHints?: Readonly<Record<string, string>>;
+    /** Label for the "go back one card" control. */
+    backLabel?: string;
+    /** Hint for the "go back one card" control. */
+    backHint?: string;
+    /** Progress line, e.g. "3 / 12". Receives the 1-based position and the total. */
+    progress?: (position: number, total: number) => string;
+    /** Label announced on the card region itself. Receives the card title. */
+    cardLabel?: (title: string) => string;
+    /** Hint announced on the card region (how to rank it). */
+    cardHint?: string;
+}
+interface CardDeckProps {
+    cards: DeckCard[];
+    /** Ordered verdict ids. Keyboard 1..n selects the nth, so ORDER IS THE CONTRACT. */
+    verdicts: readonly string[];
+    onVerdict: (cardId: string, verdict: string) => void;
+    onComplete: () => void;
+    testID: string;
+    /** Already-localized copy. Optional: verdict ids are used when a string is missing. */
+    labels?: DeckLabels;
+}
+
+/**
+ * CardDeck — a ranked card deck that is fully operable by keyboard alone.
+ *
+ * `1..n` rank the current card with the nth verdict, `Backspace` / `ArrowLeft` step
+ * back. The listener is attached to the document on web, so the deck works without
+ * the user having to tab into it first; every verdict still routes through the same
+ * `useDeck.submitVerdict`, which holds the single in-flight latch. That is what stops
+ * a browser-synthesized click from turning one key press into two verdicts.
+ *
+ * Colours come from the app UiProvider theme (`@dloizides/design-tokens`). There is not
+ * one colour literal in this package.
+ */
+
+declare const CardDeck: ({ cards, verdicts, onVerdict, onComplete, testID, labels, }: CardDeckProps) => React.ReactElement;
+
+/**
+ * Card — the presentation face of one deck entry.
+ *
+ * Deliberately NOT interactive: ranking happens in `RankBar`, so there is exactly one
+ * place a verdict can be emitted from. `imageUrl` is optional and a missing cover
+ * renders as a typographic card rather than a broken image box.
+ */
+
+interface CardProps {
+    card: DeckCard;
+    testID: string;
+    imageTestID: string;
+    /** Already-localized region label. Falls back to the card title. */
+    accessibilityLabel?: string;
+    /** Already-localized region hint telling the user how to rank. */
+    accessibilityHint?: string;
+}
+declare const Card: ({ card, testID, imageTestID, accessibilityLabel, accessibilityHint, }: CardProps) => React.ReactElement;
+
+/**
+ * RankBar — the verdict buttons, the back control and the progress line.
+ *
+ * Built on `PressableScale` (a `Pressable`), NEVER `TouchableOpacity`: RN-web silently
+ * drops `onHoverIn` / `onHoverOut` on TouchableOpacity, so a hover affordance written
+ * that way is dead on the web build with no error to find it by.
+ *
+ * Every control carries testID + accessibilityLabel + accessibilityHint. The labels are
+ * caller-supplied and already localized; a missing one falls back to the verdict id.
+ */
+
+interface RankBarProps {
+    verdicts: readonly string[];
+    labels?: DeckLabels;
+    onSelect: (verdict: string) => void;
+    onBack: () => void;
+    canGoBack: boolean;
+    /** 1-based position of the current card. */
+    position: number;
+    total: number;
+    testID: string;
+    backTestID: string;
+    progressTestID: string;
+    verdictTestIDPrefix: string;
+}
+declare const RankBar: ({ verdicts, labels, onSelect, onBack, canGoBack, position, total, testID, backTestID, progressTestID, verdictTestIDPrefix, }: RankBarProps) => React.ReactElement;
+
+interface UseDeckOptions {
+    cards: DeckCard[];
+    /** Ordered verdict ids. Keyboard 1..n selects the nth. */
+    verdicts: readonly string[];
+    onVerdict: (cardId: string, verdict: string) => void;
+    onComplete: () => void;
+}
+interface UseDeckResult {
+    /** 0-based position. Equals `cards.length` once the deck is finished. */
+    index: number;
+    /** The card awaiting a verdict, or `undefined` when the deck is finished. */
+    current: DeckCard | undefined;
+    total: number;
+    isComplete: boolean;
+    /** cardId to verdict, for every card ranked so far. */
+    answered: Readonly<Record<string, string>>;
+    /** Rank the current card. Ignored when it is already ranked or an emission is in flight. */
+    submitVerdict: (verdict: string) => void;
+    /** Step back one card. A no-op on the first card. */
+    goBack: () => void;
+    /** Route a raw key name from keydown. Returns true when the deck consumed it. */
+    handleKey: (key: string) => boolean;
+    /**
+     * Release the keyboard-activation latch. Bind to keyup: the click a browser
+     * synthesizes from a key press arrives BEFORE keyup, which is what makes this the
+     * window that suppresses it.
+     */
+    releaseKeyboardActivation: () => void;
+}
+declare function useDeck({ cards, verdicts, onVerdict, onComplete }: UseDeckOptions): UseDeckResult;
+
+/** Test ids, key names and layout metrics for the deck. Nothing here is a colour. */
+/** Stable test id suffixes. Each is appended to the caller-supplied `testID`. */
+declare const DECK_TEST_ID_SUFFIX: {
+    readonly card: "card";
+    readonly image: "card-image";
+    readonly rankBar: "rank-bar";
+    readonly verdict: "verdict";
+    readonly back: "back";
+    readonly progress: "progress";
+    readonly complete: "complete";
+};
+/** Keys that navigate rather than rank. */
+declare const KEY_BACK = "Backspace";
+declare const KEY_ARROW_LEFT = "ArrowLeft";
+/** Digit keys 1..9 pick the nth verdict. The deck never exposes more than nine. */
+declare const MAX_KEYBOARD_VERDICTS = 9;
+/** Parse a 1..9 digit key into a 0-based verdict index, or -1 when it is not one. */
+declare const digitToVerdictIndex: (key: string) => number;
+
+export { Card, CardDeck, type CardDeckProps, type CardProps, DECK_TEST_ID_SUFFIX, type DeckCard, type DeckLabels, KEY_ARROW_LEFT, KEY_BACK, MAX_KEYBOARD_VERDICTS, RankBar, type RankBarProps, type UseDeckOptions, type UseDeckResult, digitToVerdictIndex, useDeck };