Change it, export it¶

Exercise modify-embed-export-annex.pdf · PDF

You cooked the report, the customer tasted it, and now the plate is back at the pass with a note: nice, but could I also have...? Has a teacher or a client ever accepted your first version without asking for a change?

Reports are among the most-changed screens of any app, because the people who read them keep having new questions. A good cook does not start again when a dish comes back. They know which pan to touch. Today you learn to do the same, then you let the customer take the report away, and finally you prepare the exam of this unit.

Which pan do you touch?¶

A change request is a written request to change something that already works. Its acceptance test says how you will know it is done: for a report, the numbers the screen must show.

Every request lands in one layer:

This is why you kept pure functions in report.js, the markup in the page, and the form in the template: each ticket finds one small place to land.

Three change requests¶

Start from your /report route from the charts lesson. For each ticket, first write down where the change goes, with no code. Then code it. Done when the screen shows the numbers.

export function totals(rows) {
  const words = rows.reduce((sum, n) => sum + n.words, 0);
  return {
    count: rows.length,
    words,
    minutes: rows.reduce((sum, n) => sum + n.minutes, 0),
    pinned: rows.filter((n) => n.pinned).length,
    average: rows.length ? Math.round(words / rows.length) : 0
  };
}

<td>{note.pinned ? 'Yes' : ''}</td>      <!-- detail -->
<td>{group.pinned} pinned</td>           <!-- group footer -->
<td>{total.pinned} pinned</td>           <!-- report footer -->

export function filterNotes(notes, { folder = 'All', from = '', until = '', pinnedOnly = false } = {}) {
  return notes.filter(
    (n) =>
      (folder === 'All' || n.folder === folder) &&
      (from === '' || n.created >= from) &&
      (until === '' || n.created <= until) &&
      (!pinnedOnly || n.pinned)
  );
}

<label>
  Created until
  <input type="date" bind:value={until} />
</label>

let wordsOption = $derived({
  title: { text: 'Average words per note' },
  color: ['#1f5fd1'],
  tooltip: {},
  dataset: {
    source: groups
      .map((g) => ({ folder: g.folder, average: g.average }))
      .sort((a, b) => b.average - a.average)
  },
  xAxis: { type: 'category' },
  yAxis: { type: 'value', name: 'words per note' },
  series: [{ type: 'bar', encode: { x: 'folder', y: 'average' }, label: { show: true, position: 'top' } }]
});

Embedded, not attached¶

An embedded report lives inside the application: the user reaches it from the app's navigation, it reads the app's own data, and it looks like the rest of the app.

The opposite is the attached report: export everything to a spreadsheet, and build the report somewhere else.

"Embedded" does not mean "in the same repository". It means the user never leaves the app. Check four things in your own project, and fix whatever is missing:

1. A link to the report in the navigation, not a URL to know by heart: <a href="/report">Report</a> in +layout.svelte (see Routing and navigation).
2. A title in the browser tab: <svelte:head><title>Notes report · NoteBox</title></svelte:head>.
3. The app's data: the report reads the same source as the rest of the app, not a private copy.
4. The app's look: it uses your components and styles, not the browser's default grey.

Take-away 1: print¶

It takes one line of JavaScript:

<button type="button" onclick={() => window.print()}>Print</button>

Press it, and the preview shows the app bar, the filters and the buttons. None of them work on paper. The real work is in the CSS. Add to the page's <style>, with the filters wrapped in class="filters" and the buttons in class="export":

@media print {
  .filters, .export { display: none; }
}

Do the same in +layout.svelte for the app bar.

Which bands does the browser add by itself when printing? A page header and a page footer (date, URL, page number), if the user leaves them on. The browser decides, not you. That is the limit of printing a web page, and the reason for the third take-away.

Take-away 2: CSV¶

Now the rows on the screen become a file the user can open in a spreadsheet. Everything happens in the browser: build the text, wrap it in a Blob (a chunk of data the browser treats like a file), and click a temporary link.

function exportCsv() {
  const lines = [
    'id,title,folder,created,words,minutes',
    ...rows.map((n) =>
      [n.id, `"${n.title.replaceAll('"', '""')}"`, n.folder, n.created, n.words, n.minutes].join(',')
    )
  ];
  const url = URL.createObjectURL(new Blob([lines.join('\n')], { type: 'text/csv' }));
  const a = document.createElement('a');
  a.href = url;
  a.download = 'notes-report.csv';
  a.click();
  URL.revokeObjectURL(url);
}

Three details matter:

• It uses rows, not data.notes: the export must contain what the user is looking at, with the same filter.
• It puts quotes around the title, because a title may contain a comma, and RFC 4180 says that quotes inside a quoted value are doubled.
• minutes is not in the original CSV. The file that leaves is richer than the file that came in.

Take-away 3: PDF, the app runs Typst¶

Here is the plan:

flowchart LR
    B["<b>Export PDF</b><br>the user clicks"] --> P["<b>The page</b><br>sends its rows"]
    P --> S["<b>Server endpoint</b><br>runs typst compile"]
    S --> D["<b>The PDF</b><br>comes back and downloads"]

Why does it need a server? A web page cannot start programs on your computer. Code that runs on the server can.

Modify the report file¶

Your Typst file reads the CSV and filters by itself, with one parameter. The screen has three filters. Two filter codes drift apart, and one day they disagree and nobody knows which is right. So this is a fourth change request, on the Typst code: the PDF must contain exactly the rows of the screen.

In reports/notes-report.typ, the data and the parameter change:

// 1 · Data: one dictionary per CSV row. Every value arrives as text.
//     If the app sends its rows (--input rows=[...]), use exactly those.
#let from-app = "rows" in sys.inputs
#let notes = if from-app { json(bytes(sys.inputs.rows)) } else {
  csv("../static/data/notes.csv", row-type: dictionary)
}

// 2 · Parameter: typst compile --input folder=School ...
#let folder = if from-app { json(bytes(sys.inputs.filter)).folder } else {
  sys.inputs.at("folder", default: "All")
}

Then change one cell. Rows from the app carry words as a number, so the detail row writes str(n.words) instead of n.words. Both int(n.words) and str(n.words) work on text and on numbers, so the file still compiles from the command line as before.

The endpoint¶

New file src/routes/report/pdf/+server.js:

import { error } from '@sveltejs/kit';
import { execFile } from 'node:child_process';
import { promisify } from 'node:util';

const run = promisify(execFile);

// POST /report/pdf  { rows: [...], filter: {...} }  →  application/pdf
export async function POST({ request }) {
  const { rows, filter } = await request.json();
  try {
    const { stdout } = await run(
      'typst',
      [
        'compile',
        '--input', `rows=${JSON.stringify(rows)}`,
        '--input', `filter=${JSON.stringify(filter)}`,
        'reports/notes-report.typ',
        '-' // write the PDF to stdout
      ],
      { encoding: 'buffer', maxBuffer: 20 * 1024 * 1024 }
    );
    return new Response(stdout, {
      headers: {
        'content-type': 'application/pdf',
        'content-disposition': 'attachment; filename="notes-report.pdf"'
      }
    });
  } catch (e) {
    console.error(e.stderr?.toString() ?? e);
    error(500, 'Typst could not compile the report');
  }
}

execFile passes each argument separately, and no shell reads them, so a note titled "; rm -rf ~ is only a title. Never build a command line by gluing text together: it is the same rule as with SQL.

The button¶

let exporting = $state(false);
let exportError = $state('');

async function exportPdf() {
  exporting = true;
  exportError = '';
  try {
    const response = await fetch('/report/pdf', {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ rows, filter: { folder, from, pinnedOnly } })
    });
    if (!response.ok) throw new Error(await response.text());
    const url = URL.createObjectURL(await response.blob());
    const a = document.createElement('a');
    a.href = url;
    a.download = 'notes-report.pdf';
    a.click();
    URL.revokeObjectURL(url);
  } catch {
    exportError = 'The PDF could not be created. Check that Typst is installed and try again.';
  } finally {
    exporting = false;
  }
}

<button type="button" onclick={exportPdf} disabled={exporting}>
  {exporting ? 'Creating PDF…' : 'Export PDF'}
</button>
{#if exportError}<p class="error" role="alert">{exportError}</p>{/if}

The disabled button with "Creating PDF…" is visibility of system status, Nielsen's first heuristic, in your own code.

import * as echarts from 'echarts';

  const { rows, filter, option } = await request.json();

  // Same ECharts option as on screen, rendered on the server as an SVG string
  const chart = echarts.init(null, null, { renderer: 'svg', ssr: true, width: 640, height: 300 });
  chart.setOption({ ...option, animation: false });
  const svg = chart.renderToSVGString();
  chart.dispose();

  // ...and one more argument for Typst:
        '--input', `chart=${svg}`,

// Chart: the SVG the app rendered with ECharts, if it sent one
#if "chart" in sys.inputs {
  image(bytes(sys.inputs.chart), format: "svg", width: 100%, alt: "Bar chart: words per folder")
}

Three exports compared¶

Prepare the exam¶

The Unit 6 exam is on Monday 1 February 2027, 11:15–13:05.

Part B has seven tasks:

A drill on paper: percentages¶

Percentages have the same trap as averages. Take these invented rows, and on paper, for 5 minutes, work out: for each row, the pending tasks and the progress in %; and for each folder and for the total, the tasks, done, pending and progress.

Your checklist for the weekend¶

• Your project builds (npm run build), and typst --version answers on the PC you will use.
• You can find in your own project, in under a minute: toNote, filterNotes, totals, groupByFolder, Chart.svelte and the Typst group loop.
• You can log in to Figma and to Classroom.
• Exam technique: before you code, add up one group by hand. If your screen says something else, you know where to look.

Key takeaways¶

• A change request lands in one layer. Most touch one function or one object, so find the layer first.
• A change is done when its acceptance numbers appear, not when it compiles.
• An embedded report keeps the user inside the app: its navigation, its data, its look.
• Three take-aways: print (@media print), CSV (a Blob), and PDF (a server runs Typst).
• The screen decides the rows, and every export receives those rows.
• Total progress is total done ÷ total tasks, never an average of percentages.

Quick check¶

Your report is finished: structured, filtered, charted, on paper and inside the app. In the next unit you document the app you have built: Help systems and docs as code.