Skip to content

armgit / mimik

Public Imported from GitHub
0

🎬 A browser extension and desktop app that turns your clicks into step-by-step guides with annotated screenshots πŸ“–

refactor(export): render step context from an app and window when there is no url

Luis Ortiz702172a78a59
diff --git a/packages/core/src/export/__tests__/html-export.test.ts b/packages/core/src/export/__tests__/html-export.test.ts
index 200aeff..28d1309 100644
--- a/packages/core/src/export/__tests__/html-export.test.ts
+++ b/packages/core/src/export/__tests__/html-export.test.ts
@@ -96,3 +96,32 @@ describe('exportGuideAsHTML screenshot embedding', () => {
expect(rendered).toHaveBeenCalledTimes(2);
});
});
+
+describe('exportGuideAsHTML mixed browser and desktop steps', () => {
+ beforeEach(() => {
+ rendered.mockReset();
+ rendered.mockImplementation(async () => new Blob(['rendered'], { type: 'image/webp' }));
+ });
+
+ it('links a browser step and renders a desktop step as plain text', async () => {
+ const browserStep = makeStep(0);
+ const desktopStep: Step = {
+ ...makeStep(1),
+ url: '',
+ app: { name: 'Excel', id: 'com.microsoft.Excel' },
+ window: { title: 'Budget.xlsx' },
+ };
+ const shots = new Map([
+ [browserStep.id, makeScreenshot(browserStep.id)],
+ [desktopStep.id, makeScreenshot(desktopStep.id)],
+ ]);
+
+ const html = await render([browserStep, desktopStep], shots);
+
+ expect(html).toContain('<a href="https://example.com/page"');
+ expect(html).toContain('example.com/page');
+ expect(html).toContain('Excel β€” Budget.xlsx');
+ expect(html).not.toContain('<a href="">');
+ expect(html.match(/Excel β€” Budget\.xlsx<\/a>/)).toBeNull();
+ });
+});
diff --git a/packages/core/src/export/__tests__/utils.test.ts b/packages/core/src/export/__tests__/utils.test.ts
index c80865d..ee99535 100644
--- a/packages/core/src/export/__tests__/utils.test.ts
+++ b/packages/core/src/export/__tests__/utils.test.ts
@@ -8,6 +8,7 @@ import {
extractDomain,
fitImage,
formatDate,
+ stepContext,
} from '@/core/export/utils';
import type { Step } from '@/core/guides/types';
@@ -191,3 +192,42 @@ describe('containFit', () => {
expect(containFit(0, 0, 143, 80)).toEqual({ width: 143, height: 80, x: 0, y: 0 });
});
});
+
+describe('stepContext', () => {
+ function step(overrides: Partial<Step>): Step {
+ return {
+ id: 's1',
+ guideId: 'g1',
+ index: 0,
+ description: 'Do the thing',
+ action: 'click',
+ url: '',
+ timestamp: 0,
+ ...overrides,
+ };
+ }
+
+ it('labels a browser step by host and path, and links it', () => {
+ const ctx = stepContext(step({ url: 'https://www.example.com/settings/profile' }));
+ expect(ctx).toEqual({ label: 'example.com/settings/profile', href: 'https://www.example.com/settings/profile' });
+ });
+
+ it('labels a desktop step by app and window, with nothing to link to', () => {
+ const ctx = stepContext(step({ app: { name: 'Excel' }, window: { title: 'Budget.xlsx' } }));
+ expect(ctx).toEqual({ label: 'Excel β€” Budget.xlsx' });
+ expect(ctx?.href).toBeUndefined();
+ });
+
+ it('falls back to the app name when the window has no title', () => {
+ expect(stepContext(step({ app: { name: 'Excel' }, window: { title: null } }))?.label).toBe('Excel');
+ });
+
+ it('returns nothing when a step has neither', () => {
+ expect(stepContext(step({}))).toBeNull();
+ });
+
+ it('truncates at the limit the caller asks for', () => {
+ const long = stepContext(step({ app: { name: 'A'.repeat(200) } }), 64);
+ expect(long?.label).toHaveLength(64);
+ });
+});
diff --git a/packages/core/src/export/docx-export.ts b/packages/core/src/export/docx-export.ts
index 806633e..1706a49 100644
--- a/packages/core/src/export/docx-export.ts
+++ b/packages/core/src/export/docx-export.ts
@@ -22,7 +22,7 @@ import {
import { i18n } from '@/core/env';
import { type Branding, dataUrlToBytes, fitLogo, loadBranding } from '@/core/export/branding';
import { type ExportOptions, IMAGE_SCALE_FACTORS, loadExportOptions } from '@/core/export/options';
-import { blobToArrayBuffer, extractDomain, formatDate } from '@/core/export/utils';
+import { blobToArrayBuffer, extractDomain, formatDate, stepContext } from '@/core/export/utils';
import { actionSteps, calloutAccent, isBlock, stepNumbers, tint } from '@/core/guides/blocks';
import type { Guide, Screenshot, Step } from '@/core/guides/types';
import { logger } from '@/core/logger';
@@ -77,16 +77,6 @@ export function fitDocxImageSize(
};
}
-function stepUrlLabel(url: string): string {
- try {
- const parsed = new URL(url);
- const label = `${parsed.hostname.replace(/^www\./, '')}${parsed.pathname === '/' ? '' : parsed.pathname}`;
- return label.length > 64 ? `${label.slice(0, 63)}…` : label;
- } catch {
- return url;
- }
-}
-
function plainCell(children: Paragraph[], widthMm: number, rightGapMm = 0, bottom = false): TableCell {
return new TableCell({
borders: NO_BORDERS,
@@ -307,27 +297,30 @@ async function buildStepTable(
): Promise<Table> {
const accent = bare(brand.accent);
const stepNumber = String(number).padStart(2, '0');
+ const stepCtx = opts.stepUrls ? stepContext(step, 64) : null;
const textChildren: Paragraph[] = [
new Paragraph({
spacing: { after: 140 },
children: [
new TextRun({ text: step.description, bold: true, color: INK, size: 22, font: DOCX_FONT_FAMILY }),
- ...(step.url && opts.stepUrls
+ ...(stepCtx
? [
new TextRun({ text: ' Β· ', color: MUTED, size: 18, font: DOCX_FONT_FAMILY }),
- new ExternalHyperlink({
- link: step.url,
- children: [
- new TextRun({
- text: stepUrlLabel(step.url),
- color: accent,
- underline: { type: UnderlineType.SINGLE, color: accent },
- size: 18,
- font: DOCX_FONT_FAMILY,
- }),
- ],
- }),
+ stepCtx.href
+ ? new ExternalHyperlink({
+ link: stepCtx.href,
+ children: [
+ new TextRun({
+ text: stepCtx.label,
+ color: accent,
+ underline: { type: UnderlineType.SINGLE, color: accent },
+ size: 18,
+ font: DOCX_FONT_FAMILY,
+ }),
+ ],
+ })
+ : new TextRun({ text: stepCtx.label, color: accent, size: 18, font: DOCX_FONT_FAMILY }),
]
: []),
],
diff --git a/packages/core/src/export/html-export.ts b/packages/core/src/export/html-export.ts
index e9ac372..31eb857 100644
--- a/packages/core/src/export/html-export.ts
+++ b/packages/core/src/export/html-export.ts
@@ -12,6 +12,7 @@ import {
MAX_DESC_LINES,
MAX_LEAD_LINES,
MAX_TITLE_LINES,
+ stepContext,
} from '@/core/export/utils';
import { actionSteps, calloutAccent, isBlock, stepNumbers, tint, variantLabel } from '@/core/guides/blocks';
import type { Guide, Screenshot, Step } from '@/core/guides/types';
@@ -57,16 +58,6 @@ function blockSection(step: Step): string {
</section>`;
}
-function stepUrlLabel(url: string): string {
- try {
- const parsed = new URL(url);
- const label = `${parsed.hostname.replace(/^www\./, '')}${parsed.pathname === '/' ? '' : parsed.pathname}`;
- return label.length > 72 ? `${label.slice(0, 71)}…` : label;
- } catch {
- return url;
- }
-}
-
export async function exportGuideAsHTML(
guide: Guide,
steps: Step[],
@@ -100,10 +91,12 @@ export async function exportGuideAsHTML(
}
const stepNumber = String(number).padStart(2, '0');
- const urlHtml =
- step.url && opts.stepUrls
- ? `<a href="${escapeHtml(step.url)}" target="_blank" rel="noopener" style="font-size:14px;font-weight:400;color:${accent};">${escapeHtml(stepUrlLabel(step.url))}</a>`
- : '';
+ const ctx = opts.stepUrls ? stepContext(step) : null;
+ const urlHtml = !ctx
+ ? ''
+ : ctx.href
+ ? `<a href="${escapeHtml(ctx.href)}" target="_blank" rel="noopener" style="font-size:14px;font-weight:400;color:${accent};">${escapeHtml(ctx.label)}</a>`
+ : `<span style="font-size:14px;font-weight:400;color:${accent};">${escapeHtml(ctx.label)}</span>`;
stepSections.push(`
<section data-step="${number}" style="display:flex;gap:8mm;margin-bottom:13mm;">
diff --git a/packages/core/src/export/pdf-export.ts b/packages/core/src/export/pdf-export.ts
index a10d743..04a7691 100644
--- a/packages/core/src/export/pdf-export.ts
+++ b/packages/core/src/export/pdf-export.ts
@@ -18,6 +18,7 @@ import {
MAX_LEAD_LINES,
MAX_TITLE_LINES,
pxToMm,
+ stepContext,
} from '@/core/export/utils';
import { actionSteps, calloutAccent, isBlock, stepNumbers, tint } from '@/core/guides/blocks';
import type { Guide, Screenshot, Step } from '@/core/guides/types';
@@ -290,8 +291,9 @@ export async function exportGuideAsPDF(
let ux = TEXT_X + widthOf(doc, descLines[descLines.length - 1], 11, true);
let uy = sy + 6 + (descLines.length - 1) * 5;
- if (step.url && opts.stepUrls) {
- const label = stepUrlLabel(step.url);
+ const stepCtx = opts.stepUrls ? stepContext(step, 64) : null;
+ if (stepCtx) {
+ const label = stepCtx.label;
doc.setFontSize(9);
doc.setFont('helvetica', 'normal');
const sep = ' Β· ';
@@ -306,10 +308,14 @@ export async function exportGuideAsPDF(
ux += sepW;
}
doc.setTextColor(...accent);
- doc.textWithLink(label, ux, uy, { url: step.url });
- doc.setDrawColor(...accent);
- doc.setLineWidth(0.2);
- doc.line(ux, uy + 0.9, ux + urlW, uy + 0.9);
+ if (stepCtx.href) {
+ doc.textWithLink(label, ux, uy, { url: stepCtx.href });
+ doc.setDrawColor(...accent);
+ doc.setLineWidth(0.2);
+ doc.line(ux, uy + 0.9, ux + urlW, uy + 0.9);
+ } else {
+ doc.text(label, ux, uy);
+ }
}
let iy = uy + 4;
@@ -383,13 +389,3 @@ function drawBlock(doc: jsPDF, step: Step, y: number, nextPage: () => number): n
writeLines(doc, lines, textX, sy + CALLOUT_PAD_Y + CALLOUT_BASELINE, CALLOUT_SIZE, false, INK, CALLOUT_LINE_H);
return sy + boxH + BLOCK_GAP;
}
-
-function stepUrlLabel(url: string): string {
- try {
- const parsed = new URL(url);
- const label = `${parsed.hostname.replace(/^www\./, '')}${parsed.pathname === '/' ? '' : parsed.pathname}`;
- return label.length > 64 ? `${label.slice(0, 63)}…` : label;
- } catch {
- return url;
- }
-}
diff --git a/packages/core/src/export/utils.ts b/packages/core/src/export/utils.ts
index 45c9dcf..b09c6dd 100644
--- a/packages/core/src/export/utils.ts
+++ b/packages/core/src/export/utils.ts
@@ -26,6 +26,32 @@ export async function blobToArrayBuffer(blob: Blob): Promise<ArrayBuffer> {
return await blob.arrayBuffer();
}
+export interface StepContext {
+ label: string;
+ href?: string;
+}
+
+function truncateLabel(label: string, max: number): string {
+ return label.length > max ? `${label.slice(0, max - 1)}…` : label;
+}
+
+export function stepContext(step: Step, max = 72): StepContext | null {
+ if (step.url) {
+ try {
+ const parsed = new URL(step.url);
+ const path = parsed.pathname === '/' ? '' : parsed.pathname;
+ return { label: truncateLabel(`${parsed.hostname.replace(/^www\./, '')}${path}`, max), href: step.url };
+ } catch {
+ return { label: step.url, href: step.url };
+ }
+ }
+ if (step.app) {
+ const title = step.window?.title;
+ return { label: truncateLabel(title ? `${step.app.name} β€” ${title}` : step.app.name, max) };
+ }
+ return null;
+}
+
export function extractDomain(steps: Step[]): string | null {
const stepWithUrl = steps.find((s) => s.url);
if (!stepWithUrl) return null;
diff --git a/packages/core/src/guides/types.ts b/packages/core/src/guides/types.ts
index c89468a..9402840 100644
--- a/packages/core/src/guides/types.ts
+++ b/packages/core/src/guides/types.ts
@@ -31,6 +31,8 @@ export interface Step {
description: string;
action: string;
url: string;
+ app?: { name: string; id?: string };
+ window?: { title: string | null };
timestamp: number;
screenshotId?: string;
elementMeta?: ElementMeta;