@san-siva/blogkit-md-cli 0.1.51 → 0.1.52

package/src/components/RenderContent.tsx

@@ -0,0 +1,79 @@
+import { BlogHeader, Callout } from '@san-siva/blogkit';
+import { MarkdownSections, readMarkdownFile } from '@san-siva/blogkit-md';
+import Link from 'next/link';
+import type { ReactNode } from 'react';
+
+import { SettingsToolbar } from './SettingsToolbar';
+
+type MarkdownResult = Awaited<ReturnType<typeof readMarkdownFile>>;
+
+type LinkItem = { href: string; label: string };
+
+/**
+ * Rendered above the content. The CLI passes its live-reload client; a
+ * statically exported site leaves it out, having no SSE endpoint to listen to.
+ */
+type Shared = { liveReload?: ReactNode };
+
+type Props = Shared &
+	(
+		| { kind: 'file'; result: MarkdownResult; fallbackTitle?: string }
+		| { kind: 'directory'; title: string; links: LinkItem[] }
+	);
+
+export const RenderContent = (props: Props) => {
+	const { liveReload } = props;
+
+	if (props.kind === 'directory') {
+		const { title, links } = props;
+		return (
+			<SettingsToolbar>
+				{liveReload}
+				<BlogHeader
+					title={[title]}
+					desc={[`${links.length} markdown file${links.length === 1 ? '' : 's'}`]}
+				/>
+				{links.length === 0 ? (
+					<Callout type="warning">
+						No markdown files found in this directory.
+					</Callout>
+				) : (
+					<ul>
+						{links.map(({ href, label }) => (
+							<li key={href}>
+								<Link href={href}>{label}</Link>
+							</li>
+						))}
+					</ul>
+				)}
+			</SettingsToolbar>
+		);
+	}
+
+	const { result, fallbackTitle } = props;
+
+	if (!result.success) {
+		return (
+			<SettingsToolbar>
+				{liveReload}
+				<Callout type="warning">{result.error}</Callout>
+			</SettingsToolbar>
+		);
+	}
+
+	const { rendered, title, description } = result;
+	const resolvedTitle = title ?? fallbackTitle;
+
+	return (
+		<SettingsToolbar>
+			{liveReload}
+			{resolvedTitle && (
+				<BlogHeader
+					title={[resolvedTitle]}
+					desc={description ? [description] : []}
+				/>
+			)}
+			<MarkdownSections rendered={rendered} />
+		</SettingsToolbar>
+	);
+};

package/src/components/SettingsToolbar.module.scss

@@ -0,0 +1,40 @@
+@use '@san-siva/stylekit/styles/index.module.scss' as styles;
+
+.wrapper {
+	position: fixed;
+	bottom: 0;
+	right: 0;
+	z-index: 10;
+	width: 200px;
+	height: 200px;
+	display: flex;
+	align-items: flex-end;
+	justify-content: flex-end;
+
+	&:hover .toolbar {
+		opacity: 1;
+	}
+}
+
+.toolbar {
+	-webkit-backdrop-filter: blur(19.6px);
+	backdrop-filter: blur(19.6px);
+	background-color: hsla(0, 0%, 97%, 0.82);
+	border: 1px solid rgba(0, 0, 0, 0.1);
+	border-radius: styles.$border-radius--1;
+	padding: styles.space(1) styles.space(2);
+	margin: styles.space(3);
+	opacity: 0;
+	transition: opacity 0.3s ease-in-out;
+	// min-contents is not a CSS value, so this rule was dropped and the
+	// toolbar shrank to the wrapper, wrapping its labels. Size to the widest
+	// label instead, and don't let the flex parent squeeze it back down.
+	width: max-content;
+	flex: none;
+	white-space: nowrap;
+	display: flex;
+	flex-direction: column;
+	align-items: center;
+	justify-content: center;
+	gap: styles.space(1);
+}

package/src/components/SettingsToolbar.tsx

@@ -0,0 +1,45 @@
+'use client';
+
+import { Blog, CheckList, type CheckListItem } from '@san-siva/blogkit';
+import type { ReactNode } from 'react';
+
+import { useLayoutPreferences } from './useLayoutPreferences';
+
+import styles from './SettingsToolbar.module.scss';
+
+type Properties = {
+	children: ReactNode;
+};
+
+export const SettingsToolbar = ({ children }: Properties) => {
+	const {
+		preferences: { increasedWidthMode, isTocEnabled },
+		toggle,
+	} = useLayoutPreferences();
+
+	const widthModeToggle: CheckListItem[] = [
+		{
+			id: 'increased-width-mode',
+			children: <p>Wide layout</p>,
+			isChecked: increasedWidthMode,
+			onClick: () => toggle('increasedWidthMode'),
+		},
+		{
+			id: 'enable-toc',
+			children: <p>Table of contents</p>,
+			isChecked: isTocEnabled,
+			onClick: () => toggle('isTocEnabled'),
+		},
+	];
+
+	return (
+		<Blog increasedWidthMode={increasedWidthMode} isTocEnabled={isTocEnabled}>
+			<div className={styles.wrapper}>
+				<div className={styles.toolbar}>
+					<CheckList items={widthModeToggle} />
+				</div>
+			</div>
+			{children}
+		</Blog>
+	);
+};

package/src/components/index.ts

@@ -0,0 +1,4 @@
+export { RenderContent } from './RenderContent';
+export { SettingsToolbar } from './SettingsToolbar';
+export type { LayoutPreferencesState } from './useLayoutPreferences';
+export { useLayoutPreferences } from './useLayoutPreferences';

package/src/components/useLayoutPreferences.ts

@@ -0,0 +1,48 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+
+import {
+	defaultPreferences,
+	type LayoutPreferences,
+	readPreferences,
+	writePreferences,
+} from '../lib/layout-preferences';
+
+export type LayoutPreferencesState = {
+	preferences: LayoutPreferences;
+	/** Flip one preference and persist the result. */
+	toggle: (key: keyof LayoutPreferences) => void;
+};
+
+/**
+ * Layout preferences that survive a reload of the current tab, independently
+ * of any other tab (see the storage choice in lib/layout-preferences).
+ *
+ * Stored values are read on mount rather than during render: the server has
+ * no storage, so reading during render would make the first client render
+ * disagree with the server HTML and trip hydration.
+ */
+export const useLayoutPreferences = (): LayoutPreferencesState => {
+	const [preferences, setPreferences] =
+		useState<LayoutPreferences>(defaultPreferences);
+	// Only a real toggle is worth storing: without this, the restore below
+	// would write the defaults straight back into a tab nobody has touched.
+	const hasToggled = useRef(false);
+
+	useEffect(() => {
+		setPreferences(readPreferences());
+	}, []);
+
+	useEffect(() => {
+		if (hasToggled.current) writePreferences(preferences);
+	}, [preferences]);
+
+	return {
+		preferences,
+		toggle: key => {
+			hasToggled.current = true;
+			setPreferences(current => ({ ...current, [key]: !current[key] }));
+		},
+	};
+};

package/src/lib/index.ts

@@ -0,0 +1,10 @@
+export type { LayoutPreferences } from './layout-preferences';
+export {
+	defaultPreferences,
+	parsePreferences,
+	readPreferences,
+	STORAGE_KEY,
+	writePreferences,
+} from './layout-preferences';
+export type { LinkItem } from './markdown-links';
+export { collectMarkdownLinks } from './markdown-links';

package/src/lib/layout-preferences.ts

@@ -0,0 +1,76 @@
+export type LayoutPreferences = {
+	/** Widen the article column beyond the default reading width. */
+	increasedWidthMode: boolean;
+	/** Show the table of contents alongside the article. */
+	isTocEnabled: boolean;
+};
+
+export const STORAGE_KEY = 'blogkit-md:layout-preferences';
+
+export const defaultPreferences: LayoutPreferences = {
+	increasedWidthMode: false,
+	isTocEnabled: true,
+};
+
+/**
+ * sessionStorage, not localStorage: it is scoped to the individual tab, so a
+ * refresh keeps that tab's choice while every tab keeps its own layout and a
+ * newly opened one starts from the defaults.
+ */
+const storage = (): Storage | undefined => globalThis.sessionStorage;
+
+const booleanOr = (value: unknown, fallback: boolean): boolean =>
+	typeof value === 'boolean' ? value : fallback;
+
+/**
+ * Coerce a stored payload into preferences, falling back per field so a
+ * partial or half-corrupt value still contributes what it can.
+ */
+export const parsePreferences = (stored: string | null): LayoutPreferences => {
+	if (!stored) return defaultPreferences;
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(stored);
+	} catch {
+		return defaultPreferences;
+	}
+
+	if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+		return defaultPreferences;
+	}
+
+	const { increasedWidthMode, isTocEnabled } = parsed as Record<
+		keyof LayoutPreferences,
+		unknown
+	>;
+
+	return {
+		increasedWidthMode: booleanOr(
+			increasedWidthMode,
+			defaultPreferences.increasedWidthMode
+		),
+		isTocEnabled: booleanOr(isTocEnabled, defaultPreferences.isTocEnabled),
+	};
+};
+
+/**
+ * Read this tab's stored preferences. Storage can be missing (server render)
+ * or throw (private mode, blocked site data); both fall back to the defaults.
+ */
+export const readPreferences = (): LayoutPreferences => {
+	try {
+		return parsePreferences(storage()?.getItem(STORAGE_KEY) ?? null);
+	} catch {
+		return defaultPreferences;
+	}
+};
+
+/** Persist this tab's preferences, ignoring unavailable or full storage. */
+export const writePreferences = (preferences: LayoutPreferences): void => {
+	try {
+		storage()?.setItem(STORAGE_KEY, JSON.stringify(preferences));
+	} catch {
+		// Storage unavailable — preferences stay until this tab is closed.
+	}
+};

package/src/lib/live-reload.ts

@@ -0,0 +1,56 @@
+// Enough failed reconnects (~3s apart in Chrome) to ride out a server
+// replacement — kill + 400ms port release + next start boot — with margin.
+export const MAX_RETRIES = 30;
+
+export type LiveReloadHooks = {
+	/** Soft refresh — re-fetch server components for the current route. */
+	refresh: () => void;
+	/** Full page reload — a different server may own the port now. */
+	reload: () => void;
+	/** Stop listening for events. */
+	close: () => void;
+};
+
+/**
+ * The reconnect state machine behind LiveReload. The SSE server greets every
+ * connection with 'connected' and broadcasts 'reload' on file changes:
+ *
+ * - 'reload' (or any other payload) → soft refresh.
+ * - 'connected' after the stream previously dropped → another server took
+ *   over this port (e.g. a folder server superseding a file server), so the
+ *   page shape may have completely changed → full reload.
+ * - The first successful connect never reloads, even if attempts before it
+ *   failed — otherwise a server still booting would cause a reload loop.
+ * - The retry budget is per-outage: it resets on every successful connect
+ *   and closes the stream once an outage exhausts it.
+ */
+export function createLiveReloadHandlers({
+	refresh,
+	reload,
+	close,
+}: LiveReloadHooks) {
+	let retries = 0;
+	let everConnected = false;
+	let dropped = false;
+
+	return {
+		onMessage(data: string): void {
+			if (data === 'connected') {
+				const replaced = everConnected && dropped;
+				everConnected = true;
+				dropped = false;
+				retries = 0;
+				if (replaced) {
+					close();
+					reload();
+				}
+				return;
+			}
+			refresh();
+		},
+		onError(): void {
+			dropped = true;
+			if (++retries >= MAX_RETRIES) close();
+		},
+	};
+}

package/src/lib/markdown-links.ts

@@ -0,0 +1,51 @@
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+
+export type LinkItem = { href: string; label: string };
+
+/**
+ * Recursively collect a link for every .md file under `root`. Hrefs are built
+ * relative to `base` (the served MARKDOWN_DIR) so they stay valid no matter
+ * which subdirectory is being listed; labels are relative to `root` so a
+ * subdirectory listing isn't prefixed with its own name on every line.
+ */
+export async function collectMarkdownLinks(
+	root: string,
+	base: string
+): Promise<LinkItem[]> {
+	const links: LinkItem[] = [];
+
+	const walk = async (current: string) => {
+		let entries;
+		try {
+			entries = await readdir(current, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			const fullPath = path.join(current, entry.name);
+			if (entry.isDirectory()) {
+				await walk(fullPath);
+			} else if (entry.name.endsWith('.md')) {
+				const href =
+					'/' +
+					path
+						.relative(base, fullPath)
+						.replace(/\.md$/, '')
+						.split(path.sep)
+						.map(encodeURIComponent)
+						.join('/');
+				const label = path
+					.relative(root, fullPath)
+					.replace(/\.md$/, '')
+					.split(path.sep)
+					.join(' / ');
+				links.push({ href, label });
+			}
+		}
+	};
+
+	await walk(root);
+	links.sort((a, b) => a.label.localeCompare(b.label));
+	return links;
+}

package/src/lib/resolve-path.ts

@@ -0,0 +1,47 @@
+import { stat } from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * Resolve a URL slug to a path inside `dir`, rejecting traversal attempts:
+ * `..` segments, separators smuggled inside a segment (also via URL encoding),
+ * and anything that resolves outside `dir`.
+ */
+export const resolveSafePath = (
+	slug: string[],
+	dir: string | undefined
+): string | null => {
+	if (!dir) return null;
+
+	const safeSlug = slug
+		.map(part => decodeURIComponent(part))
+		.filter(p => p && p !== '..' && !p.includes('/') && !p.includes('\\'));
+	if (safeSlug.length !== slug.length) return null;
+
+	const target = path.resolve(dir, safeSlug.join(path.sep));
+	// Defense-in-depth: check '..' as a whole segment so children whose own
+	// name starts with dots (e.g. '..drafts') aren't mistaken for traversal.
+	const relative = path.relative(dir, target);
+	if (
+		relative === '..' ||
+		relative.startsWith('..' + path.sep) ||
+		path.isAbsolute(relative)
+	) {
+		return null;
+	}
+	return target;
+};
+
+/** When the slug names an existing directory inside `dir`, return its path; else null. */
+export const resolveDirectory = async (
+	slug: string[],
+	dir: string | undefined
+): Promise<string | null> => {
+	const target = resolveSafePath(slug, dir);
+	if (!target) return null;
+	try {
+		const stats = await stat(target);
+		return stats.isDirectory() ? target : null;
+	} catch {
+		return null;
+	}
+};

package/src/package.json

@@ -0,0 +1,4 @@
+{
+	"//": "Tests run as ESM so tsx resolves packages that only define an 'import' export condition (e.g. @san-siva/blogkit-md). Scoped here to keep the CJS bin build untouched.",
+	"type": "module"
+}