@thesimonharms/basa 0.1.0 → 0.1.2

package/src/tui/Footer.ts

@@ -1,65 +0,0 @@
-import { BaseComponent } from '@mudah-cli/tui';
-import { detectCapabilities } from '@mudah-cli/terminal';
-import { paint } from '@mudah-cli/ui';
-
-const KEYS: ReadonlyArray<{ key: string; label: string; tone: 'good' | 'meh' | 'bad' | 'neutral' }> = [
-  { key: '1', label: 'Again', tone: 'bad' },
-  { key: '2', label: 'Hard',  tone: 'meh' },
-  { key: '3', label: 'Good',  tone: 'good' },
-  { key: '4', label: 'Easy',  tone: 'good' },
-];
-
-const TONES: Record<'good' | 'meh' | 'bad' | 'neutral', string> = {
-  good: '#4ade80',
-  meh: '#fbbf24',
-  bad: '#f87171',
-  neutral: '#94a3b8',
-};
-
-/** The key legend. Centered, three rows: title, four key chips, hints. */
-export class Footer extends BaseComponent {
-  readonly focusable = false;
-
-  private width: number;
-
-  constructor(width: number) {
-    super();
-    this.width = width;
-  }
-
-  resize(width: number): void {
-    this.width = width;
-  }
-
-  render(): string[] {
-    const lvl = detectCapabilities().colorLevel;
-    const chips = KEYS.map((k) => {
-      const color = TONES[k.tone];
-      return `${paint('#0f172a', ` ${k.key} `, lvl)}${paint(color, ` ${k.label} `, lvl)}`;
-    }).join('  ');
-    const row1 = centerLine(chips, this.width);
-    const row2 = centerLine(
-      paint('#64748b', 'space/enter: reveal   n: skip   esc: quit', lvl),
-      this.width,
-    );
-    return ['', row1, row2];
-  }
-}
-
-function centerLine(text: string, width: number): string {
-  return ' '.repeat(Math.max(0, Math.floor((width - visibleOf(text)) / 2))) + text;
-}
-
-function visibleOf(text: string): number {
-  let visible = 0;
-  let inEscape = false;
-  for (const ch of text) {
-    if (ch === '\x1b') { inEscape = true; continue; }
-    if (inEscape) {
-      if (ch === 'm') inEscape = false;
-      continue;
-    }
-    visible++;
-  }
-  return visible;
-}

package/src/tui/Header.ts

@@ -1,58 +0,0 @@
-import { BaseComponent } from '@mudah-cli/tui';
-import { detectCapabilities } from '@mudah-cli/terminal';
-import { paint } from '@mudah-cli/ui';
-
-export interface HeaderOptions {
-  deckName: string;
-  reviewed: number;
-  total: number;
-  width: number;
-}
-
-/** Deck name + progress bar. One row, centered. */
-export class Header extends BaseComponent {
-  readonly focusable = false;
-
-  private readonly options: HeaderOptions;
-
-  constructor(options: HeaderOptions) {
-    super();
-    this.options = options;
-  }
-
-  update(options: HeaderOptions): void {
-    Object.assign(this.options, options);
-  }
-
-  render(): string[] {
-    const lvl = detectCapabilities().colorLevel;
-    const barWidth = Math.max(10, Math.min(40, this.options.width - 30));
-    const ratio = this.options.total > 0 ? this.options.reviewed / this.options.total : 0;
-    const filled = Math.round(ratio * barWidth);
-    const bar = '█'.repeat(filled) + '░'.repeat(barWidth - filled);
-    const left = paint('#e2e8f0', this.options.deckName, lvl);
-    const right = paint('#94a3b8', ` ${this.options.reviewed}/${this.options.total}`, lvl);
-    const progress = paint(ratio >= 1 ? '#4ade80' : '#60a5fa', bar, lvl);
-    const line = `${left}  ${progress}${right}`;
-    return [centerLine(line, this.options.width)];
-  }
-}
-
-function centerLine(text: string, width: number): string {
-  // Use a simple visible-length estimate: count chars, ignore ANSI.
-  return ' '.repeat(Math.max(0, Math.floor((width - visibleOf(text)) / 2))) + text;
-}
-
-function visibleOf(text: string): number {
-  let visible = 0;
-  let inEscape = false;
-  for (const ch of text) {
-    if (ch === '\x1b') { inEscape = true; continue; }
-    if (inEscape) {
-      if (ch === 'm') inEscape = false;
-      continue;
-    }
-    visible++;
-  }
-  return visible;
-}

package/src/tui/StudyApp.ts

@@ -1,147 +0,0 @@
-import { Container } from '@mudah-cli/tui';
-import type { Deck, Grade, ReviewCard } from '../flashcards/types.js';
-import { grade, pickNext } from '../flashcards/srs.js';
-import { saveReviewCards } from '../flashcards/deck.js';
-import { BasaFx } from '../flashcards/sound.js';
-import { CardView } from './CardView.js';
-import { Header } from './Header.js';
-import { Footer } from './Footer.js';
-
-export interface StudyAppOptions {
-  deck: Deck;
-  deckPath: string;
-  cards: ReviewCard[];
-  width: number;
-  height: number;
-  fx: BasaFx;
-}
-
-interface SessionStats {
-  reviewed: number;
-  again: number;
-  hard: number;
-  good: number;
-  easy: number;
-}
-
-/**
- * The study session. Owns SRS state, the focused card, the session stats.
- * Exposes a `Container` for the TUI program to mount, plus `tick()` and
- * `resize()` methods the host calls every frame and on terminal resize.
- */
-export class StudyApp {
-  readonly root: Container;
-  private readonly cardView: CardView;
-  private readonly header: Header;
-  private readonly footer: Footer;
-  private cards: ReviewCard[];
-  private current: ReviewCard | undefined;
-  private stats: SessionStats = { reviewed: 0, again: 0, hard: 0, good: 0, easy: 0 };
-  private width: number;
-  private height: number;
-
-  private readonly options: StudyAppOptions;
-
-  constructor(options: StudyAppOptions) {
-    this.options = options;
-    this.cards = options.cards;
-    this.width = options.width;
-    this.height = options.height;
-
-    const cardHeight = Math.max(8, options.height - 8);
-    this.cardView = new CardView({
-      deckPath: options.deckPath,
-      cellsWidth: options.width,
-      cellsHeight: cardHeight,
-      onGraded: (g, typed) => void this.handleGrade(g, typed),
-      onSkip: () => this.handleSkip(),
-    });
-    this.header = new Header({
-      deckName: options.deck.name,
-      reviewed: 0,
-      total: this.cards.length,
-      width: options.width,
-    });
-    this.footer = new Footer(options.width);
-
-    this.root = new Container().add(this.header).add(this.cardView).add(this.footer);
-    void this.advance();
-  }
-
-  /** Drive animations. Called by the host on every frame. */
-  tick(): void {
-    this.cardView.tick();
-  }
-
-  /** Apply a terminal resize. */
-  resize(width: number, height: number): void {
-    this.width = width;
-    this.height = height;
-    this.header.update({
-      deckName: this.options.deck.name,
-      reviewed: this.stats.reviewed,
-      total: this.cards.length,
-      width,
-    });
-    this.footer.resize(width);
-    const cardHeight = Math.max(8, height - 8);
-    this.cardView.resize(width, cardHeight);
-  }
-
-  /** Persist state on shutdown. Safe to call multiple times. */
-  async persist(): Promise<void> {
-    await saveReviewCards(this.options.deckPath, this.cards).catch(() => {});
-  }
-
-  private async advance(): Promise<void> {
-    this.current = pickNext(this.cards, Date.now());
-    if (this.current === undefined) {
-      await this.cardView.setCard(undefined, this.stats);
-      return;
-    }
-    await this.cardView.setCard(this.current);
-  }
-
-  private async handleGrade(gradeValue: Grade, _typed: string): Promise<void> {
-    if (this.current === undefined) return;
-    const idx = this.cards.indexOf(this.current);
-    if (idx < 0) return;
-    const next = grade(this.current.state, gradeValue);
-    this.cards[idx] = { card: this.current.card, state: next };
-    this.stats = {
-      reviewed: this.stats.reviewed + 1,
-      again: this.stats.again + (gradeValue === 0 ? 1 : 0),
-      hard: this.stats.hard + (gradeValue === 1 ? 1 : 0),
-      good: this.stats.good + (gradeValue === 2 ? 1 : 0),
-      easy: this.stats.easy + (gradeValue === 3 ? 1 : 0),
-    };
-    this.header.update({
-      deckName: this.options.deck.name,
-      reviewed: this.stats.reviewed,
-      total: this.cards.length,
-      width: this.width,
-    });
-
-    if (gradeValue === 0) {
-      await this.options.fx.playIncorrect();
-    } else {
-      await this.options.fx.playCorrect(gradeValue);
-    }
-
-    // Persist after every grade so a crash doesn't lose progress.
-    await saveReviewCards(this.options.deckPath, this.cards).catch(() => {});
-
-    await this.advance();
-  }
-
-  private handleSkip(): void {
-    if (this.current === undefined) return;
-    const idx = this.cards.indexOf(this.current);
-    if (idx < 0) return;
-    this.cards[idx] = {
-      card: this.current.card,
-      state: { ...this.current.state, due: Date.now() + 30_000 },
-    };
-    void this.advance();
-  }
-}

package/src/tui/effects.ts

@@ -1,81 +0,0 @@
-/**
- * Visual effect helpers. Each is a small mutable object that the card view
- * ticks every frame. They never touch the terminal directly — they just
- * transform strings the component is about to render.
- */
-
-export interface TypeOnState {
-  /** Total frames the effect should run for. */
-  durationFrames: number;
-  /** Frame counter, incremented by the host. */
-  frame: number;
-}
-
-/** Reveal a string array row-by-row. 0 → 0 rows, 1 → all rows. */
-export function typeOnRows(state: TypeOnState, rows: string[]): string[] {
-  const t = Math.min(1, state.frame / Math.max(1, state.durationFrames));
-  const visible = Math.max(1, Math.ceil(rows.length * t));
-  return rows.slice(0, visible);
-}
-
-export interface ShakeState {
-  durationFrames: number;
-  frame: number;
-}
-
-/** Apply a per-row horizontal jitter that decays. The component pads each
- *  row with random leading spaces within a window that shrinks over time. */
-export function shakeRows(state: ShakeState, rows: string[], seed: number): string[] {
-  const t = Math.min(1, state.frame / Math.max(1, state.durationFrames));
-  const amplitude = Math.round((1 - t) * 3);
-  if (amplitude === 0) return rows;
-  return rows.map((row, i) => {
-    // Deterministic pseudo-random per row+frame so the diff renderer still works.
-    const x = pseudo(seed + i * 7 + state.frame * 13);
-    const offset = Math.floor(x * (amplitude * 2 + 1)) - amplitude;
-    if (offset === 0) return row;
-    if (offset > 0) return ' '.repeat(offset) + row;
-    return row.slice(-offset);
-  });
-}
-
-function pseudo(n: number): number {
-  const x = Math.sin(n * 12.9898) * 43758.5453;
-  return x - Math.floor(x);
-}
-
-export interface ConfettiSpec {
-  /** Frame counter, incremented by the host. */
-  frame: number;
-  /** Total frames. */
-  durationFrames: number;
-  /** Pseudo-random seed. */
-  seed: number;
-  /** Width in cells. */
-  width: number;
-  /** Palette: 24-bit color codes as strings. */
-  palette: string[];
-}
-
-/** Render a confetti overlay as N rows. Each row is a string. */
-export function confettiRows(spec: ConfettiSpec, height: number): string[] {
-  const out: string[] = [];
-  for (let row = 0; row < height; row++) {
-    let line = '';
-    for (let col = 0; col < spec.width; col++) {
-      const x = pseudo(spec.seed + row * 91 + col * 17 + spec.frame * 5);
-      const visible = x > 0.65;
-      if (!visible) {
-        line += ' ';
-        continue;
-      }
-      const colorIndex = Math.floor(pseudo(spec.seed + row + col + spec.frame * 3) * spec.palette.length);
-      const color = spec.palette[colorIndex] ?? spec.palette[0]!;
-      const glyphs = ['✦', '✧', '•', '·', '◆', '◇'];
-      const glyph = glyphs[Math.floor(pseudo(spec.seed + col + row) * glyphs.length)] ?? '·';
-      line += `${color}${glyph}\x1b[0m`;
-    }
-    out.push(line);
-  }
-  return out;
-}

package/test/CardView.test.ts

@@ -1,157 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { CardView } from '../src/tui/CardView.js';
-import type { ReviewCard } from '../src/flashcards/types.js';
-import { freshState } from '../src/flashcards/srs.js';
-import type { KeyEvent } from '@mudah-cli/terminal';
-
-function key(name: string, ch?: string): KeyEvent {
-  return { name, ch, kind: 'press' };
-}
-
-function makeCard(front: string, back: string): ReviewCard {
-  return { card: { front, back }, state: freshState(0) };
-}
-
-describe('CardView', () => {
-  it('renders the front text and a "press space to reveal" prompt', async () => {
-    const view = new CardView({
-      deckPath: '/tmp/x.yml',
-      cellsWidth: 60,
-      cellsHeight: 16,
-      onGraded: () => {},
-      onSkip: () => {},
-    });
-    await view.setCard(makeCard('hola', 'hello'));
-    const rows = view.render();
-    const all = rows.join('\n');
-    expect(all).toContain('hola');
-    expect(all).toContain('reveal');
-    expect(all).not.toContain('hello');
-  });
-
-  it('space reveals the back and renders the answer', async () => {
-    let grade = -1;
-    const view = new CardView({
-      deckPath: '/tmp/x.yml',
-      cellsWidth: 60,
-      cellsHeight: 16,
-      onGraded: (g) => { grade = g; },
-      onSkip: () => {},
-    });
-    await view.setCard(makeCard('hola', 'hello'));
-    view.onKey(key('space'));
-    // Drive the reveal animation to completion.
-    for (let i = 0; i < 20; i++) view.tick();
-    const all = view.render().join('\n');
-    expect(all).toContain('hello');
-    expect(grade).toBe(-1);
-  });
-
-  it('keys 1..4 grade after reveal; 0 → Again, 3 → Easy', async () => {
-    const grades: number[] = [];
-    const view = new CardView({
-      deckPath: '/tmp/x.yml',
-      cellsWidth: 60,
-      cellsHeight: 16,
-      onGraded: (g) => grades.push(g),
-      onSkip: () => {},
-    });
-    await view.setCard(makeCard('a', 'A'));
-    view.onKey(key('space'));
-    for (let i = 0; i < 20; i++) view.tick();
-    view.onKey(key('1'));
-    expect(grades).toEqual([0]);
-
-    await view.setCard(makeCard('b', 'B'));
-    view.onKey(key('space'));
-    for (let i = 0; i < 20; i++) view.tick();
-    view.onKey(key('4'));
-    expect(grades).toEqual([0, 3]);
-  });
-
-  it('keys 1..4 grade after reveal even when the live KeyEvent carries ch (real parseKeys output)', async () => {
-    // parseKeys emits digits as { name: '1', ch: '1', kind: 'press' } — see
-    // @mudah-cli/terminal/keys.js. The keymap must not buffer the digit into
-    // the typed-answer field before the grade switch has a chance to run.
-    const grades: number[] = [];
-    const typed: string[] = [];
-    const view = new CardView({
-      deckPath: '/tmp/x.yml',
-      cellsWidth: 60,
-      cellsHeight: 16,
-      onGraded: (g, t) => { grades.push(g); typed.push(t); },
-      onSkip: () => {},
-    });
-    await view.setCard(makeCard('a', 'A'));
-    view.onKey(key('space'));
-    for (let i = 0; i < 20; i++) view.tick();
-    view.onKey({ name: '1', ch: '1', kind: 'press' });
-    expect(grades).toEqual([0]);
-    expect(typed).toEqual(['']);
-  });
-
-  it('keys 1..4 do nothing before reveal', async () => {
-    const grades: number[] = [];
-    const view = new CardView({
-      deckPath: '/tmp/x.yml',
-      cellsWidth: 60,
-      cellsHeight: 16,
-      onGraded: (g) => grades.push(g),
-      onSkip: () => {},
-    });
-    await view.setCard(makeCard('a', 'A'));
-    view.onKey(key('1'));
-    expect(grades).toEqual([]);
-  });
-
-  it('typing buffers characters and backspace removes them', async () => {
-    const view = new CardView({
-      deckPath: '/tmp/x.yml',
-      cellsWidth: 60,
-      cellsHeight: 16,
-      onGraded: () => {},
-      onSkip: () => {},
-    });
-    await view.setCard(makeCard('a', 'A'));
-    view.onKey(key('h', 'h'));
-    view.onKey(key('e', 'e'));
-    view.onKey(key('l', 'l'));
-    view.onKey(key('l', 'l'));
-    view.onKey(key('o', 'o'));
-    let all = view.render().join('\n');
-    expect(all).toContain('hello');
-
-    view.onKey(key('backspace'));
-    all = view.render().join('\n');
-    expect(all).toContain('hell');
-  });
-
-  it('"n" skips without grading', async () => {
-    let skipped = false;
-    const view = new CardView({
-      deckPath: '/tmp/x.yml',
-      cellsWidth: 60,
-      cellsHeight: 16,
-      onGraded: () => {},
-      onSkip: () => { skipped = true; },
-    });
-    await view.setCard(makeCard('a', 'A'));
-    view.onKey(key('n'));
-    expect(skipped).toBe(true);
-  });
-
-  it('setCard(undefined) shows the done view', async () => {
-    const view = new CardView({
-      deckPath: '/tmp/x.yml',
-      cellsWidth: 60,
-      cellsHeight: 16,
-      onGraded: () => {},
-      onSkip: () => {},
-    });
-    await view.setCard(undefined, { reviewed: 5, again: 1, hard: 1, good: 2, easy: 1 });
-    const all = view.render().join('\n');
-    expect(all).toContain('session complete');
-    expect(all).toContain('reviewed');
-    expect(all).toContain('5');
-  });
-});

package/test/deck.test.ts

@@ -1,144 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { loadDeck, saveReviewCards, loadReviewCards, createDeck, DeckLoadError, listDecks, defaultDecksDir } from '../src/flashcards/deck.js';
-import { mkdtemp, rm, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { freshState, grade } from '../src/flashcards/srs.js';
-
-async function withTempDir<T>(fn: (dir: string) => Promise<T>): Promise<T> {
-  const dir = await mkdtemp(join(tmpdir(), 'basa-test-'));
-  try {
-    return await fn(dir);
-  } finally {
-    await rm(dir, { recursive: true, force: true });
-  }
-}
-
-describe('deck loading', () => {
-  it('loads a YAML deck with string sides', async () => {
-    await withTempDir(async (dir) => {
-      const file = join(dir, 'greetings.yml');
-      await writeFile(
-        file,
-        'name: greetings\ncards:\n  - front: hola\n    back: hello\n  - front: adios\n    back: goodbye\n',
-        'utf8',
-      );
-      const deck = await loadDeck(file);
-      expect(deck.name).toBe('greetings');
-      expect(deck.cards).toHaveLength(2);
-      expect(deck.cards[0]?.front).toBe('hola');
-      expect(deck.cards[0]?.back).toBe('hello');
-    });
-  });
-
-  it('loads a JSON deck with field-list sides', async () => {
-    await withTempDir(async (dir) => {
-      const file = join(dir, 'jp.json');
-      await writeFile(
-        file,
-        JSON.stringify({
-          name: 'jp',
-          cards: [
-            {
-              front: [{ text: 'こんにちは' }, { image: './konnichiwa.png' }],
-              back: 'hello',
-            },
-          ],
-        }),
-        'utf8',
-      );
-      const deck = await loadDeck(file);
-      const first = deck.cards[0];
-      expect(Array.isArray(first?.front)).toBe(true);
-      const fields = first?.front as Array<Record<string, string>>;
-      expect(fields[0]?.text).toBe('こんにちは');
-      expect(fields[1]?.image).toBe('./konnichiwa.png');
-    });
-  });
-
-  it('rejects a deck without a name', async () => {
-    await withTempDir(async (dir) => {
-      const file = join(dir, 'bad.yml');
-      await writeFile(file, 'cards: []\n', 'utf8');
-      await expect(loadDeck(file)).rejects.toBeInstanceOf(DeckLoadError);
-    });
-  });
-
-  it('rejects a card missing back', async () => {
-    await withTempDir(async (dir) => {
-      const file = join(dir, 'bad.yml');
-      await writeFile(file, 'name: x\ncards:\n  - front: hi\n', 'utf8');
-      await expect(loadDeck(file)).rejects.toThrow(/missing front or back/);
-    });
-  });
-
-  it('rejects a field with no text/image/audio', async () => {
-    await withTempDir(async (dir) => {
-      const file = join(dir, 'bad.json');
-      await writeFile(file, JSON.stringify({ name: 'x', cards: [{ front: [{}], back: 'b' }] }), 'utf8');
-      await expect(loadDeck(file)).rejects.toThrow(/has no text, image, or audio/);
-    });
-  });
-
-  it('persists and re-loads SRS state', async () => {
-    await withTempDir(async (dir) => {
-      const file = join(dir, 'd.yml');
-      await writeFile(file, 'name: d\ncards:\n  - front: a\n    back: A\n  - front: b\n    back: B\n', 'utf8');
-      const deck = await loadDeck(file);
-      const initial = await loadReviewCards(deck, file);
-      const reviewed = initial.map((rc, i) => ({
-        ...rc,
-        state: grade(rc.state, 2 as const, 1_000 + i * 1000),
-      }));
-      await saveReviewCards(file, reviewed);
-
-      const reloaded = await loadReviewCards(deck, file);
-      expect(reloaded[0]?.state.streak).toBe(1);
-      expect(reloaded[0]?.state.reviews).toBe(1);
-      expect(reloaded[1]?.state.streak).toBe(1);
-    });
-  });
-
-  it('corrupt progress file is ignored, fresh state returned', async () => {
-    await withTempDir(async (dir) => {
-      const file = join(dir, 'd.yml');
-      await writeFile(file, 'name: d\ncards:\n  - front: a\n    back: A\n', 'utf8');
-      const deck = await loadDeck(file);
-      await writeFile(`${file}.progress.json`, '{ this is not json');
-      const cards = await loadReviewCards(deck, file);
-      expect(cards[0]?.state.streak).toBe(0);
-    });
-  });
-
-  it('createDeck writes a scaffold file', async () => {
-    await withTempDir(async (dir) => {
-      const file = join(dir, 'new.yml');
-      const path = await createDeck(file, 'New Deck');
-      expect(path).toBe(file);
-      const deck = await loadDeck(file);
-      expect(deck.name).toBe('New Deck');
-      expect(deck.cards.length).toBeGreaterThan(0);
-    });
-  });
-
-  it('listDecks finds YAML and JSON files', async () => {
-    await withTempDir(async (dir) => {
-      await writeFile(join(dir, 'a.yml'), 'name: a\ncards: []\n', 'utf8');
-      await writeFile(join(dir, 'b.yaml'), 'name: b\ncards: []\n', 'utf8');
-      await writeFile(join(dir, 'c.json'), '{"name":"c","cards":[]}', 'utf8');
-      await writeFile(join(dir, 'README.md'), 'ignored', 'utf8');
-      const files = await listDecks(dir);
-      expect(files).toHaveLength(3);
-      expect(files.some((f) => f.endsWith('a.yml'))).toBe(true);
-      expect(files.some((f) => f.endsWith('b.yaml'))).toBe(true);
-      expect(files.some((f) => f.endsWith('c.json'))).toBe(true);
-    });
-  });
-});
-
-describe('defaultDecksDir', () => {
-  it('returns a path under the home directory', () => {
-    const dir = defaultDecksDir();
-    expect(dir).toMatch(/\/basa\/decks$/);
-  });
-});