@jjlmoya/utils-books 1.7.0 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jjlmoya/utils-books",
-    "version": "1.7.0",
+    "version": "1.8.0",
     "type": "module",
     "main": "./src/index.ts",
     "types": "./src/index.ts",

package/src/entries.ts

@@ -1,7 +1,10 @@
 export { bookPaginationAndSpineCalculator } from './tool/book-pagination-and-spine-calculator/entry';
 export type { BookPaginationUI, BookPaginationLocaleContent } from './tool/book-pagination-and-spine-calculator/entry';
+export { bookReadingTimeDeadlinePlanner } from './tool/book-reading-time-deadline-planner/entry';
+export type { BookReadingUI, BookReadingLocaleContent } from './tool/book-reading-time-deadline-planner/entry';
 
 import { bookPaginationAndSpineCalculator } from './tool/book-pagination-and-spine-calculator/entry';
 import { bookInteriorMarginAndGutterPlanner } from './tool/book-interior-margin-and-gutter-planner/entry';
+import { bookReadingTimeDeadlinePlanner } from './tool/book-reading-time-deadline-planner/entry';
 
-export const ALL_ENTRIES = [bookPaginationAndSpineCalculator, bookInteriorMarginAndGutterPlanner];
+export const ALL_ENTRIES = [bookPaginationAndSpineCalculator, bookInteriorMarginAndGutterPlanner, bookReadingTimeDeadlinePlanner];

package/src/tests/locale_completeness.test.ts

@@ -18,6 +18,6 @@ describe('Locale Completeness Validation', () => {
   });
 
   it('all tools registered', () => {
-    expect(ALL_TOOLS.length).toBe(2);
+    expect(ALL_TOOLS.length).toBe(3);
   });
 });

package/src/tests/tool_validation.test.ts

@@ -5,7 +5,7 @@ import { booksCategory } from '../data';
 describe('Tool Validation Suite', () => {
   describe('Library Registration', () => {
     it('should have tools in ALL_TOOLS', () => {
-      expect(ALL_TOOLS.length).toBe(2);
+      expect(ALL_TOOLS.length).toBe(3);
     });
 
     it('booksCategory should be defined', () => {

package/src/tool/book-reading-time-deadline-planner/bibliography.astro

@@ -0,0 +1,16 @@
+---
+import { Bibliography as SharedBibliography } from '@jjlmoya/utils-shared';
+import { bookReadingTimeDeadlinePlanner } from './index';
+import { bibliography } from './bibliography';
+import type { KnownLocale } from '../../types';
+
+interface Props {
+  locale?: KnownLocale;
+}
+
+const { locale = 'en' } = Astro.props as Props;
+const loader = bookReadingTimeDeadlinePlanner.i18n[locale] || bookReadingTimeDeadlinePlanner.i18n.en;
+const content = await loader?.();
+---
+
+<SharedBibliography links={content?.bibliography || bibliography} />

package/src/tool/book-reading-time-deadline-planner/bibliography.ts

@@ -0,0 +1,31 @@
+import type { BibliographyEntry } from '../../types';
+
+interface TracedBibliographyEntry extends BibliographyEntry {
+  region: string;
+  originalLanguage: string;
+  supports: string;
+}
+
+export const bibliography: TracedBibliographyEntry[] = [
+  {
+    name: 'Allegheny College. College Level Reading',
+    url: 'https://sites.allegheny.edu/academic-success/academic-resources/reading/',
+    region: 'United States',
+    originalLanguage: 'English',
+    supports: 'Measure an individual reading rate in words per minute and pair pacing with comprehension.',
+  },
+  {
+    name: 'Ministerio de Educación y Formación Profesional. Marco teórico de lectura PISA 2018',
+    url: 'https://www.educacionfpydeportes.gob.es/dam/jcr%3A2f1081a1-c1e4-4799-8a49-9bc589724ca4/marco%20teorico%20lectura%202018_esp_ESP.pdf',
+    region: 'Spain and OECD',
+    originalLanguage: 'Spanish',
+    supports: 'Reading fluency combines accuracy, automaticity and meaning, so a speed target is not a comprehension guarantee.',
+  },
+  {
+    name: 'Rayner, Schotter, Masson, Potter and Treiman. So much to read, so little time',
+    url: 'https://profiles.wustl.edu/en/publications/so-much-to-read-so-little-time-how-do-we-read-and-can-speed-readi/',
+    region: 'International research',
+    originalLanguage: 'English',
+    supports: 'Reading speed and comprehension can trade off, so the planner treats speed as a personal estimate rather than a promise.',
+  },
+];

package/src/tool/book-reading-time-deadline-planner/book-reading-time-deadline-planner.css

@@ -0,0 +1,449 @@
+.n-tool {
+  --n-ink: #28231e;
+  --n-muted: #766d63;
+  --n-paper: #fffdf8;
+  --n-paper-alt: #f4ede1;
+  --n-paper-deep: #e7dac7;
+  --n-line: #d7c7b4;
+  --n-accent: #9c4d35;
+  --n-accent-soft: #f0d8cb;
+  --n-ok: #427257;
+  --n-warn: #a6652f;
+  --n-bad: #a34038;
+  --n-shadow: rgba(57, 39, 25, 0.13);
+
+  display: grid;
+  grid-template-columns: minmax(290px, 0.83fr) minmax(420px, 1.17fr);
+  overflow: visible;
+  color: var(--n-ink);
+  background: var(--n-paper);
+  border: 1px solid var(--n-line);
+  box-shadow: 0 18px 40px var(--n-shadow);
+}
+
+.n-setup,
+.n-plan {
+  padding: 30px;
+}
+.n-setup {
+  display: flex;
+  flex-direction: column;
+  gap: 24px;
+  background: var(--n-paper-alt);
+  border-right: 1px solid var(--n-line);
+}
+.n-setup-head,
+.n-panel-label,
+.n-presets,
+.n-presets > div {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+}
+.n-eyebrow,
+.n-panel-label,
+.n-presets > span {
+  color: var(--n-muted);
+  font-size: 0.7rem;
+  font-weight: 700;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+}
+.n-bookmark {
+  color: var(--n-accent);
+  font-size: 1.35rem;
+}
+.n-field-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 16px;
+}
+.n-field-wide {
+  grid-column: 1 / -1;
+}
+.n-field {
+  display: flex;
+  min-width: 0;
+  flex-direction: column;
+  gap: 8px;
+  color: var(--n-muted);
+  font-size: 0.76rem;
+  font-weight: 700;
+}
+.n-field input,
+.n-field select,
+.n-select-trigger {
+  width: 100%;
+  min-height: 45px;
+  padding: 9px 12px;
+  border: 1px solid var(--n-line);
+  border-radius: 2px;
+  background: var(--n-paper);
+  color: var(--n-ink);
+  font: inherit;
+  font-size: 0.95rem;
+}
+.n-field input:focus-visible,
+.n-select-trigger:focus-visible,
+.n-select-menu button:focus-visible,
+.n-presets button:focus-visible {
+  outline: 3px solid var(--n-accent-soft);
+  outline-offset: 2px;
+}
+.n-field small {
+  color: var(--n-accent);
+  font-size: 0.68rem;
+}
+.n-select {
+  position: relative;
+  z-index: 3;
+}
+.n-select-trigger {
+  position: relative;
+  padding-right: 32px;
+  cursor: pointer;
+  text-align: left;
+}
+.n-select-trigger::after {
+  position: absolute;
+  top: 50%;
+  right: 12px;
+  width: 7px;
+  height: 7px;
+  border-right: 1.5px solid currentcolor;
+  border-bottom: 1.5px solid currentcolor;
+  content: "";
+  transform: translateY(-70%) rotate(45deg);
+}
+.n-select[data-open="true"] .n-select-trigger::after {
+  transform: translateY(-20%) rotate(225deg);
+}
+.n-select-menu {
+  position: absolute;
+  z-index: 5;
+  top: calc(100% + 6px);
+  right: 0;
+  left: 0;
+  padding: 5px;
+  border: 1px solid var(--n-line);
+  background: var(--n-paper);
+  box-shadow: 0 12px 25px var(--n-shadow);
+}
+.n-select-menu[hidden] {
+  display: none;
+}
+.n-select-menu button {
+  display: block;
+  width: 100%;
+  padding: 10px;
+  border: 0;
+  background: transparent;
+  color: var(--n-ink);
+  cursor: pointer;
+  font: inherit;
+  text-align: left;
+}
+.n-select-menu button:hover {
+  background: var(--n-accent-soft);
+}
+.n-presets {
+  align-items: flex-start;
+  flex-direction: column;
+  margin-top: auto;
+  padding-top: 18px;
+  border-top: 1px solid var(--n-line);
+}
+.n-presets > div {
+  flex-wrap: wrap;
+  justify-content: flex-start;
+}
+.n-presets button {
+  padding: 8px 10px;
+  border: 1px solid var(--n-line);
+  border-radius: 999px;
+  background: var(--n-paper);
+  color: var(--n-ink);
+  cursor: pointer;
+  font: inherit;
+  font-size: 0.72rem;
+  font-weight: 700;
+}
+.n-presets button:hover {
+  border-color: var(--n-accent);
+  color: var(--n-accent);
+}
+.n-speed-test {
+  display: grid;
+  gap: 12px;
+  padding: 16px;
+  border: 1px solid var(--n-line);
+  background: var(--n-paper);
+}
+.n-speed-test .n-panel-label {
+  align-items: flex-start;
+  flex-direction: column;
+}
+.n-speed-test textarea {
+  width: 100%;
+  min-height: 76px;
+  padding: 10px 12px;
+  border: 1px solid var(--n-line);
+  border-radius: 2px;
+  background: var(--n-paper-alt);
+  color: var(--n-ink);
+  font: inherit;
+  line-height: 1.45;
+  resize: vertical;
+}
+.n-speed-test textarea:focus-visible,
+.n-speed-test-actions button:focus-visible,
+.n-speed-test-result button:focus-visible {
+  outline: 3px solid var(--n-accent-soft);
+  outline-offset: 2px;
+}
+.n-speed-test-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+.n-speed-test-actions button,
+.n-speed-test-result button {
+  padding: 8px 10px;
+  border: 1px solid var(--n-line);
+  border-radius: 999px;
+  background: var(--n-paper-alt);
+  color: var(--n-ink);
+  cursor: pointer;
+  font: inherit;
+  font-size: 0.72rem;
+  font-weight: 700;
+}
+.n-speed-test-actions button[data-speed-test-action],
+.n-speed-test-result button {
+  border-color: var(--n-ink);
+  background: var(--n-ink);
+  color: var(--n-paper);
+}
+.n-speed-test-actions button[data-speed-test-action].is-running {
+  border-color: var(--n-accent);
+  background: var(--n-paper-alt);
+  color: var(--n-accent);
+}
+.n-speed-test-status {
+  margin: 0;
+  color: var(--n-muted);
+  font-size: 0.72rem;
+  line-height: 1.4;
+}
+.n-speed-test-result {
+  display: grid;
+  grid-template-columns: auto 1fr auto 1fr;
+  align-items: center;
+  gap: 7px 10px;
+  color: var(--n-muted);
+  font-size: 0.68rem;
+  text-transform: uppercase;
+}
+.n-speed-test-result strong {
+  color: var(--n-accent);
+  font-size: 0.85rem;
+  text-transform: none;
+}
+.n-speed-test-result button {
+  grid-column: 1 / -1;
+  justify-self: start;
+}
+.n-export-calendar {
+  justify-self: start;
+  padding: 8px 11px;
+  border: 1px solid var(--n-ink);
+  border-radius: 999px;
+  background: var(--n-ink);
+  color: var(--n-paper);
+  cursor: pointer;
+  font: inherit;
+  font-size: 0.72rem;
+  font-weight: 700;
+}
+.n-export-calendar:focus-visible {
+  outline: 3px solid var(--n-accent-soft);
+  outline-offset: 2px;
+}
+.n-plan {
+  display: grid;
+  grid-template-rows: auto auto 1fr auto;
+  gap: 22px;
+}
+.n-status {
+  display: flex;
+  align-items: flex-start;
+  gap: 11px;
+  min-height: 64px;
+}
+.n-status-dot {
+  flex: 0 0 auto;
+  width: 12px;
+  height: 12px;
+  margin-top: 5px;
+  border-radius: 50%;
+  background: var(--n-ok);
+  box-shadow: 0 0 0 5px rgba(66, 114, 87, 0.12);
+}
+.n-status[data-status="tight"] .n-status-dot {
+  background: var(--n-warn);
+  box-shadow: 0 0 0 5px rgba(166, 101, 47, 0.12);
+}
+.n-status[data-status="late"] .n-status-dot,
+.n-status[data-status="invalid"] .n-status-dot {
+  background: var(--n-bad);
+  box-shadow: 0 0 0 5px rgba(163, 64, 56, 0.12);
+}
+.n-status strong {
+  display: block;
+  font-size: 1.08rem;
+}
+.n-status p {
+  max-width: 390px;
+  margin: 5px 0 0;
+  color: var(--n-muted);
+  font-size: 0.79rem;
+  line-height: 1.45;
+}
+.n-output-grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 10px;
+}
+.n-output-card {
+  display: flex;
+  min-height: 74px;
+  flex-direction: column;
+  justify-content: space-between;
+  padding: 13px;
+  border: 1px solid var(--n-line);
+  background: var(--n-paper-alt);
+}
+.n-output-card span {
+  color: var(--n-muted);
+  font-size: 0.67rem;
+  font-weight: 700;
+  text-transform: uppercase;
+}
+.n-output-card strong {
+  color: var(--n-accent);
+  font-size: 1.08rem;
+}
+.n-output-wide {
+  grid-column: 1 / -1;
+  min-height: 58px;
+  flex-direction: row;
+  align-items: center;
+}
+.n-output-wide strong {
+  font-size: 1.18rem;
+}
+.n-timeline-panel {
+  display: grid;
+  align-content: center;
+  padding: 16px;
+  border: 1px solid var(--n-line);
+  background: var(--n-paper-alt);
+}
+.n-panel-label {
+  font-size: 0.65rem;
+}
+.n-panel-label span:last-child {
+  color: var(--n-accent);
+}
+.n-timeline-svg {
+  display: block;
+  width: 100%;
+  margin-top: 12px;
+  overflow: visible;
+}
+.n-timeline-track {
+  fill: none;
+  stroke: var(--n-paper-deep);
+  stroke-width: 6;
+}
+.n-timeline-fill {
+  fill: none;
+  stroke: var(--n-accent);
+  stroke-width: 6;
+  stroke-linecap: round;
+}
+.n-timeline-fill-late {
+  stroke: var(--n-bad);
+}
+.n-milestone circle {
+  fill: var(--n-paper);
+  stroke: var(--n-accent);
+  stroke-width: 3;
+}
+.n-milestone:first-of-type circle {
+  fill: var(--n-accent);
+}
+.n-milestone text {
+  fill: var(--n-muted);
+  font-size: 8px;
+  font-weight: 700;
+}
+.n-milestone text:first-of-type {
+  fill: var(--n-ink);
+}
+.n-timeline-panel p,
+.n-source {
+  margin: 9px 0 0;
+  color: var(--n-muted);
+  font-size: 0.72rem;
+  line-height: 1.45;
+}
+.n-source {
+  margin: 0;
+  padding-top: 10px;
+  border-top: 1px solid var(--n-line);
+}
+html.theme-dark .n-tool {
+  --n-ink: #f6efe5;
+  --n-muted: #b9afa2;
+  --n-paper: #25231f;
+  --n-paper-alt: #171613;
+  --n-paper-deep: #51483e;
+  --n-line: #51483e;
+  --n-accent: #e49a72;
+  --n-accent-soft: #493129;
+  --n-ok: #82ba93;
+  --n-warn: #e0a36f;
+  --n-bad: #ee8b7f;
+  --n-shadow: rgba(0, 0, 0, 0.28);
+}
+
+@media (max-width: 780px) {
+  .n-tool {
+    grid-template-columns: 1fr;
+    max-width: calc(100vw - 40px);
+  }
+  .n-setup {
+    border-right: 0;
+    border-bottom: 1px solid var(--n-line);
+  }
+}
+
+@media (max-width: 480px) {
+  .n-setup,
+  .n-plan {
+    padding: 20px;
+  }
+  .n-field-grid,
+  .n-output-grid {
+    grid-template-columns: 1fr;
+  }
+  .n-field-wide,
+  .n-output-wide {
+    grid-column: auto;
+  }
+  .n-speed-test-result {
+    grid-template-columns: auto 1fr;
+  }
+}

package/src/tool/book-reading-time-deadline-planner/calendar.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+import { createMilestoneIcs } from './calendar';
+import { DEFAULT_INPUTS, calculateReadingPlan } from './logic';
+
+describe('reading milestone calendar export', () => {
+  it('creates five all-day milestone events with exclusive end dates', () => {
+    const calculation = calculateReadingPlan(DEFAULT_INPUTS);
+    const ics = createMilestoneIcs(calculation, 'Reading plan', {
+      start: 'Start', quarter: '25%', half: 'Half', threeQuarter: '75%', finish: 'Finish',
+    });
+
+    expect(ics).toContain('BEGIN:VCALENDAR');
+    expect(ics.match(/BEGIN:VEVENT/g)).toHaveLength(5);
+    expect(ics).toContain('DTSTART;VALUE=DATE:20260101');
+    expect(ics).toContain('DTEND;VALUE=DATE:20260102');
+    expect(ics).toContain('SUMMARY:Reading plan - Start');
+  });
+});

package/src/tool/book-reading-time-deadline-planner/calendar.ts

@@ -0,0 +1,56 @@
+import type { BookReadingCalculation } from './logic';
+
+export interface MilestoneCalendarLabels {
+  start: string;
+  quarter: string;
+  half: string;
+  threeQuarter: string;
+  finish: string;
+}
+
+export function createMilestoneIcs(calculation: BookReadingCalculation, title: string, labels: MilestoneCalendarLabels): string {
+  const milestoneLabels = [labels.start, labels.quarter, labels.half, labels.threeQuarter, labels.finish];
+  const events = calculation.milestoneDates.map((date, index) => createEvent({ calculation, date, label: milestoneLabels[index] || labels.start, index, title }));
+  return ['BEGIN:VCALENDAR', 'VERSION:2.0', 'PRODID:-//jjlmoya-utils//Book Reading Planner//EN', 'CALSCALE:GREGORIAN', ...events, 'END:VCALENDAR', ''].join('\r\n');
+}
+
+interface CalendarEventContext {
+  calculation: BookReadingCalculation;
+  date: string;
+  label: string;
+  index: number;
+  title: string;
+}
+
+function createEvent(context: CalendarEventContext): string {
+  const nextDate = addOneDay(context.date);
+    const summary = escapeCalendarText(`${context.title} - ${context.label}`);
+  return [
+    'BEGIN:VEVENT',
+    `UID:reading-milestone-${context.calculation.startDate}-${context.index}@jjlmoya-utils`,
+    `DTSTAMP:${toCalendarDate(new Date())}T000000Z`,
+    `DTSTART;VALUE=DATE:${toCalendarDateString(context.date)}`,
+    `DTEND;VALUE=DATE:${toCalendarDateString(nextDate)}`,
+    `SUMMARY:${summary}`,
+    `DESCRIPTION:${escapeCalendarText(`Reading milestone: ${context.label}`)}`,
+    'END:VEVENT',
+  ].join('\r\n');
+}
+
+function toCalendarDate(date: Date): string {
+  return date.toISOString().slice(0, 10).replaceAll('-', '');
+}
+
+function toCalendarDateString(date: string): string {
+  return date.replaceAll('-', '');
+}
+
+function addOneDay(date: string): string {
+  const next = new Date(`${date}T00:00:00Z`);
+  next.setUTCDate(next.getUTCDate() + 1);
+  return next.toISOString().slice(0, 10);
+}
+
+function escapeCalendarText(value: string): string {
+  return value.replaceAll('\\', '\\\\').replaceAll(';', '\\;').replaceAll(',', '\\,').replaceAll('\r\n', '\\n').replaceAll('\n', '\\n');
+}