@heyramzi/ui 2.8.0 → 2.9.0

package/src/work/docs/docs-demo.svelte

@@ -0,0 +1,227 @@
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import { Bell, FileText, LinkSimple, Star } from "phosphor-svelte";
+	import DocEditorPage from "./doc-editor-page.svelte";
+	import DocMenu from "./doc-menu.svelte";
+	import EditedChip from "./edited-chip.svelte";
+	import type { CopyKind } from "./menu.js";
+
+	// =========================
+	// TYPES
+	// =========================
+	type Node = Record<string, unknown>;
+
+	// =========================
+	// CONTENT
+	// =========================
+	const text = (value: string, marks?: Node[]): Node => ({
+		type: "text",
+		text: value,
+		marks,
+	});
+	const p = (...parts: (string | Node)[]): Node => ({
+		type: "paragraph",
+		content: parts.map((part) => (typeof part === "string" ? text(part) : part)),
+	});
+	const h = (level: number, value: string): Node => ({
+		type: "heading",
+		attrs: { level },
+		content: [text(value)],
+	});
+	const task = (value: string, checked = false): Node => ({
+		type: "taskItem",
+		attrs: { checked },
+		content: [p(value)],
+	});
+	const cell = (type: "tableHeader" | "tableCell", value: string): Node => ({
+		type,
+		content: [p(value)],
+	});
+	const row = (type: "tableHeader" | "tableCell", ...values: string[]): Node => ({
+		type: "tableRow",
+		content: values.map((value) => cell(type, value)),
+	});
+
+	const content: Node = {
+		type: "doc",
+		content: [
+			h(2, "Why this exists"),
+			p(
+				"The weekly report used to be copied by hand from ClickUp into a sheet. It took an hour and the numbers drifted. This doc says how the sync works, what it leaves out and what's still open.",
+			),
+			h(2, "How it works"),
+			p(
+				"Every night a job reads the tasks changed that day and writes one row per task. It never deletes a row. A task that moves lists keeps its row and gets a new ",
+				text("list", [{ type: "code" }]),
+				" value.",
+			),
+			h(3, "What a row holds"),
+			{
+				type: "table",
+				content: [
+					row("tableHeader", "Column", "Source", "Notes"),
+					row("tableCell", "Task", "name", "Linked back to ClickUp"),
+					row("tableCell", "Owner", "assignees[0]", "First assignee only"),
+					row("tableCell", "Hours", "time tracked", "Summed per day"),
+				],
+			},
+			h(3, "The job"),
+			{
+				type: "codeBlock",
+				attrs: { language: "typescript" },
+				content: [
+					text(
+						'export async function syncDay(day: string) {\n  const tasks = await clickup.changedOn(day);\n  const rows = tasks.map(toRow);\n  await sheet.upsert(rows, { key: "id" });\n}',
+					),
+				],
+			},
+			h(2, "Before it ships"),
+			{
+				type: "taskList",
+				content: [
+					task("Backfill the last four weeks", true),
+					task("Decide what a deleted task does to its row"),
+					task("Give finance read access to the sheet"),
+				],
+			},
+			{
+				type: "blockquote",
+				content: [
+					p(
+						"A report nobody trusts is worse than no report. Row counts get checked against ClickUp every Monday.",
+					),
+				],
+			},
+			h(2, "Open questions"),
+			p(
+				"Subtasks are flattened into their parent today. If finance wants hours per subtask, the key changes from the task id to the pair of ids, and the backfill runs again.",
+			),
+		],
+	};
+
+	// =========================
+	// STATE
+	// =========================
+	let title = $state("ClickUp to Sheets");
+	let favorited = $state(false);
+	let showAuthors = $state(false);
+	let editedAt = $state<Date>(new Date("2026-10-21T09:12:00"));
+	let note = $state("");
+
+	// =========================
+	// DERIVED
+	// =========================
+	let latest = $state<Node>(content);
+
+	const owner = { name: "Ramzi Tabka" };
+
+	// =========================
+	// FUNCTIONS
+	// =========================
+	function touched(json: Record<string, unknown>) {
+		latest = json;
+		editedAt = new Date();
+	}
+
+	function said(what: string) {
+		note = what;
+	}
+
+	function copied(kind: CopyKind) {
+		said(`Copied ${kind === "link" ? "title as link" : kind}`);
+	}
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<div class="flex flex-col gap-2">
+	<div
+		class="h-[min(48rem,calc(100svh-9rem))] overflow-hidden rounded-xl border border-border bg-background"
+	>
+		<DocEditorPage
+			bind:title
+			{content}
+			onchange={touched}
+			oncopylink={() => said("Copied link to section")}
+		>
+			{#snippet breadcrumb()}
+				<span class="flex min-w-0 items-center gap-1.5 text-muted-foreground @max-xl/doc:hidden">
+					<FileText size={14} aria-hidden="true" />
+					<span class="truncate">Reporting</span>
+				</span>
+				<span class="px-0.5 text-muted-foreground/60 @max-xl/doc:hidden" aria-hidden="true">›</span>
+				<span class="flex min-w-0 items-center gap-1.5 font-medium">
+					<FileText size={14} class="shrink-0 text-muted-foreground" aria-hidden="true" />
+					<span class="truncate">{title.trim() || "New document"}</span>
+				</span>
+			{/snippet}
+
+			{#snippet menu()}
+				<button
+					type="button"
+					aria-label={favorited ? "Remove from favorites" : "Favorite"}
+					aria-pressed={favorited}
+					onclick={() => (favorited = !favorited)}
+					class="t-press inline-flex size-7 items-center justify-center rounded-md text-muted-foreground transition-colors duration-[var(--duration-fast)] ease-[var(--ease-smooth-out)] outline-none hover:bg-foreground/6 hover:text-foreground focus-visible:ring-3 focus-visible:ring-ring/50 any-pointer-coarse:size-10"
+				>
+					<Star
+						size={15}
+						weight={favorited ? "fill" : "regular"}
+						class={favorited ? "text-brand" : ""}
+					/>
+				</button>
+				<DocMenu
+					{title}
+					url="https://ui.heyramzi.com/work/docs"
+					content={latest}
+					{favorited}
+					onmove={() => said("Move to")}
+					onduplicate={() => said("Duplicated")}
+					onrename={() => said("Rename")}
+					ontemplate={() => said("Template created")}
+					onfavorite={() => (favorited = !favorited)}
+					oncopy={copied}
+					onremind={() => said("Remind me")}
+					onhistory={() => said("History")}
+					ondelete={() => said("Deleted")}
+				/>
+			{/snippet}
+
+			{#snippet meta()}
+				<EditedChip
+					{editedAt}
+					{owner}
+					lastEditor={owner}
+					showAuthorNames={showAuthors}
+					onshowauthors={(next) => (showAuthors = next)}
+					onhistory={() => said("History")}
+				/>
+			{/snippet}
+
+			{#snippet actions()}
+				{@const button =
+					"t-press inline-flex size-7 items-center justify-center rounded-md text-muted-foreground transition-colors duration-[var(--duration-fast)] ease-[var(--ease-smooth-out)] outline-none hover:bg-foreground/6 hover:text-foreground focus-visible:ring-3 focus-visible:ring-ring/50 any-pointer-coarse:size-10"}
+				<button
+					type="button"
+					aria-label="Copy link"
+					class="{button} @max-xl/doc:hidden"
+					onclick={() => said("Copied URL")}
+				>
+					<LinkSimple size={15} />
+				</button>
+				<button
+					type="button"
+					aria-label="Subscribe"
+					class={button}
+					onclick={() => said("Subscribed")}
+				>
+					<Bell size={15} />
+				</button>
+			{/snippet}
+		</DocEditorPage>
+	</div>
+	<p class="h-4 text-xs text-muted-foreground" aria-live="polite">{note}</p>
+</div>

package/src/work/docs/edited-chip.svelte

@@ -0,0 +1,125 @@
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import { ClockCounterClockwise, SlidersHorizontal } from "phosphor-svelte";
+	import { Avatar, AvatarFallback, AvatarImage } from "../../shadcn/avatar/index.js";
+	import { Popover, PopoverContent, PopoverTrigger } from "../../shadcn/popover/index.js";
+	import { Switch } from "../../shadcn/switch/index.js";
+	import { initials } from "../../lib/initials.js";
+	import { editStamp, editedLabel, type DateInput } from "./edited.js";
+	import { docLabels, type DocLabels } from "./labels.js";
+
+	// =========================
+	// TYPES
+	// =========================
+	type Person = { name: string; image?: string | null };
+
+	interface Props {
+		/** When the doc last changed. Unreadable or missing leaves just "Edited". */
+		editedAt?: DateInput;
+		owner?: Person | null;
+		/** The last editor. Their time falls back to `editedAt`. */
+		lastEditor?: (Person & { at?: DateInput }) | null;
+		/** The switch row shows only when this is passed. */
+		showAuthorNames?: boolean;
+		onshowauthors?: (show: boolean) => void;
+		/** The history button shows only when this is passed. */
+		onhistory?: () => void;
+		labels?: Partial<DocLabels>;
+		timeZone?: string;
+		now?: Date;
+	}
+
+	// =========================
+	// PROPS
+	// =========================
+	let {
+		editedAt,
+		owner = null,
+		lastEditor = null,
+		showAuthorNames = false,
+		onshowauthors,
+		onhistory,
+		labels: labelOverrides,
+		timeZone,
+		now,
+	}: Props = $props();
+
+	// =========================
+	// DERIVED
+	// =========================
+	let t = $derived(docLabels(labelOverrides));
+	let chip = $derived(editedLabel(editedAt, t.edited, { timeZone, now }));
+	let editorStamp = $derived(editStamp(lastEditor?.at ?? editedAt, { timeZone, now }));
+	// Nothing to open: the chip is a plain label rather than a button that opens an empty card.
+	let hasDetails = $derived(!!onshowauthors || !!owner || !!lastEditor || !!onhistory);
+</script>
+
+{#snippet person(who: Person)}
+	<Avatar class="size-5">
+		{#if who.image}<AvatarImage src={who.image} alt="" />{/if}
+		<AvatarFallback class="text-[9px]">{initials(who.name)}</AvatarFallback>
+	</Avatar>
+	<span class="truncate text-foreground">{who.name}</span>
+{/snippet}
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+{#if hasDetails}
+	<Popover>
+		<PopoverTrigger
+			class="t-press inline-flex h-7 items-center gap-1.5 rounded-md bg-foreground/5 px-2 @max-xl/doc:px-1.5 text-[13px] font-medium text-foreground/90 tabular-nums transition-colors duration-[var(--duration-fast)] ease-[var(--ease-smooth-out)] outline-none hover:bg-foreground/8 focus-visible:ring-3 focus-visible:ring-ring/50 aria-expanded:bg-foreground/8 any-pointer-coarse:h-10"
+		>
+			<SlidersHorizontal size={14} class="text-muted-foreground" aria-hidden="true" />
+			<!-- On a narrow page the glyph stands alone, so the title keeps the bar. -->
+			<span class="@max-xl/doc:sr-only">{chip}</span>
+		</PopoverTrigger>
+		<PopoverContent align="end" sideOffset={6} class="w-[21.5rem] gap-0 p-0 text-[13px]">
+			<div class="divide-y divide-border/70">
+				{#if onshowauthors}
+					<div class="flex items-center justify-between px-4 py-3">
+						<span class="text-muted-foreground">{t.showAuthorNames}</span>
+						<Switch
+							checked={showAuthorNames}
+							onCheckedChange={(next) => onshowauthors?.(next)}
+							aria-label={t.showAuthorNames}
+						/>
+					</div>
+				{/if}
+				{#if owner}
+					<div class="flex items-center gap-3 px-4 py-3">
+						<span class="w-20 shrink-0 text-muted-foreground">{t.ownedBy}</span>
+						<span class="flex min-w-0 items-center gap-2">{@render person(owner)}</span>
+					</div>
+				{/if}
+				{#if lastEditor}
+					<div class="flex items-center gap-3 px-4 py-3">
+						<span class="w-20 shrink-0 text-muted-foreground">{t.lastEditBy}</span>
+						<span class="flex min-w-0 flex-1 items-center gap-2">{@render person(lastEditor)}</span>
+						{#if editorStamp}
+							<span class="shrink-0 text-xs text-muted-foreground tabular-nums">{editorStamp}</span>
+						{/if}
+					</div>
+				{/if}
+				{#if onhistory}
+					<div class="p-2">
+						<button
+							type="button"
+							onclick={onhistory}
+							class="t-press flex h-8 w-full items-center justify-center gap-2 rounded-lg bg-foreground/5 font-medium transition-colors duration-[var(--duration-fast)] ease-[var(--ease-smooth-out)] outline-none hover:bg-foreground/8 focus-visible:ring-3 focus-visible:ring-ring/50"
+						>
+							<ClockCounterClockwise size={14} aria-hidden="true" />
+							{t.showHistory}
+						</button>
+					</div>
+				{/if}
+			</div>
+		</PopoverContent>
+	</Popover>
+{:else}
+	<span class="inline-flex h-7 items-center text-[13px] text-muted-foreground tabular-nums">
+		{chip}
+	</span>
+{/if}

package/src/work/docs/edited.ts

@@ -0,0 +1,54 @@
+/** The "Edited Oct 23" chip: how a stamp reads, and what to show when it can't be read. */
+
+export type DateInput = Date | string | number | null | undefined;
+
+export type StampOptions = {
+  /** The clock, so a test doesn't depend on today. */
+  now?: Date;
+  locale?: string;
+  timeZone?: string;
+};
+
+export function parseStamp(value: DateInput): Date | null {
+  if (value === null || value === undefined || value === "") return null;
+  const date = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+function yearOf(date: Date, { locale = "en-US", timeZone }: StampOptions) {
+  return new Intl.DateTimeFormat(locale, { year: "numeric", timeZone }).format(date);
+}
+
+/** "Oct 23", or "Oct 23, 2025" when it isn't this year. Empty when the date can't be read. */
+export function shortDate(value: DateInput, options: StampOptions = {}): string {
+  const date = parseStamp(value);
+  if (!date) return "";
+  const { locale = "en-US", timeZone, now = new Date() } = options;
+  const sameYear = yearOf(date, options) === yearOf(now, options);
+  return new Intl.DateTimeFormat(locale, {
+    month: "short",
+    day: "numeric",
+    year: sameYear ? undefined : "numeric",
+    timeZone,
+  }).format(date);
+}
+
+/** "Oct 23, 14:44" for the last-edit row. Empty when the date can't be read. */
+export function editStamp(value: DateInput, options: StampOptions = {}): string {
+  const date = parseStamp(value);
+  if (!date) return "";
+  const { locale = "en-US", timeZone } = options;
+  const time = new Intl.DateTimeFormat(locale, {
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false,
+    timeZone,
+  }).format(date);
+  return `${shortDate(date, options)}, ${time}`;
+}
+
+/** The chip's text. `label` is the word ("Edited"); a bad date leaves only the word. */
+export function editedLabel(value: DateInput, label = "Edited", options: StampOptions = {}) {
+  const day = shortDate(value, options);
+  return day ? `${label} ${day}` : label;
+}

package/src/work/docs/index.ts

@@ -0,0 +1,38 @@
+/**
+ * The document surface: a page to write one, the "Edited" chip, the `…` menu and the outline
+ * logic behind the edge ticks. The app supplies the data and every handler.
+ */
+export { default as DocEditorPage } from "./doc-editor-page.svelte";
+export { default as DocMenu } from "./doc-menu.svelte";
+export { default as EditedChip } from "./edited-chip.svelte";
+export { DEFAULT_DOC_LABELS, docLabels, type DocLabels } from "./labels.js";
+export {
+  anchorIds,
+  headingsOf,
+  outlineOf,
+  outlineOfDoc,
+  slugify,
+  type FoundHeading,
+  type OutlineHeading,
+  type OutlineLevel,
+} from "./outline.js";
+export {
+  editStamp,
+  editedLabel,
+  parseStamp,
+  shortDate,
+  type DateInput,
+  type StampOptions,
+} from "./edited.js";
+export {
+  copyOptions,
+  filterMenu,
+  menuItems,
+  shortcutLabel,
+  shortcutTarget,
+  type CopyKind,
+  type CopyOption,
+  type MenuId,
+  type MenuItem,
+  type Shortcut,
+} from "./menu.js";

package/src/work/docs/labels.ts

@@ -0,0 +1,70 @@
+/** Every word the docs surface prints. The app passes a partial to localise it. */
+export type DocLabels = {
+  titlePlaceholder: string;
+  untitled: string;
+  edited: string;
+  showAuthorNames: string;
+  ownedBy: string;
+  lastEditBy: string;
+  showHistory: string;
+  menu: string;
+  filter: string;
+  noResults: string;
+  moveTo: string;
+  duplicate: string;
+  rename: string;
+  template: string;
+  favorite: string;
+  unfavorite: string;
+  copy: string;
+  copyUrl: string;
+  copyTitle: string;
+  copyTitleAsLink: string;
+  copyMarkdown: string;
+  remind: string;
+  history: string;
+  delete: string;
+  deleteTitle: (title: string) => string;
+  deleteDetail: string;
+  cancel: string;
+  back: string;
+  outline: string;
+  copyLink: string;
+};
+
+export const DEFAULT_DOC_LABELS: DocLabels = {
+  titlePlaceholder: "New document",
+  untitled: "Untitled",
+  edited: "Edited",
+  showAuthorNames: "Show author names",
+  ownedBy: "Owned by",
+  lastEditBy: "Last edit by",
+  showHistory: "Show document history",
+  menu: "Document actions",
+  filter: "Filter…",
+  noResults: "Nothing matches",
+  moveTo: "Move to",
+  duplicate: "Duplicate",
+  rename: "Rename",
+  template: "New template from document",
+  favorite: "Favorite",
+  unfavorite: "Remove from favorites",
+  copy: "Copy",
+  copyUrl: "Copy URL",
+  copyTitle: "Copy title",
+  copyTitleAsLink: "Copy title as link",
+  copyMarkdown: "Copy content as Markdown",
+  remind: "Remind me",
+  history: "Show document history",
+  delete: "Delete",
+  deleteTitle: (title) => `Delete "${title}"`,
+  deleteDetail: "This can't be undone.",
+  cancel: "Cancel",
+  back: "Back",
+  outline: "Outline",
+  copyLink: "Copy link",
+};
+
+export function docLabels(partial?: Partial<DocLabels>): DocLabels {
+  return { ...DEFAULT_DOC_LABELS, ...partial };
+}

package/src/work/docs/menu.ts

@@ -0,0 +1,127 @@
+/**
+ * The `…` menu as data: which items exist, which show, how a filter reads them and
+ * which keys fire them. The component only draws what this returns.
+ */
+import { tiptapToMarkdown } from "../../editor/markdown.js";
+import type { DocLabels } from "./labels.js";
+
+export type MenuId =
+  | "move"
+  | "duplicate"
+  | "rename"
+  | "template"
+  | "favorite"
+  | "copy"
+  | "remind"
+  | "history"
+  | "delete";
+
+export type Shortcut = { key: string; shift?: boolean; alt?: boolean };
+
+export type MenuItem = {
+  id: MenuId;
+  label: string;
+  shortcut?: Shortcut;
+  /** Opens a second list instead of firing. */
+  submenu?: boolean;
+  danger?: boolean;
+  /** Items in one group sit together; a hairline separates groups. */
+  group: number;
+};
+
+export const SHORTCUTS: Partial<Record<MenuId, Shortcut>> = {
+  move: { key: "P", shift: true },
+  rename: { key: "R", shift: true },
+  favorite: { key: "F", alt: true },
+  remind: { key: "H", shift: true },
+};
+
+/** "⇧P", "⌥F". */
+export function shortcutLabel(shortcut: Shortcut): string {
+  return `${shortcut.shift ? "⇧" : ""}${shortcut.alt ? "⌥" : ""}${shortcut.key.toUpperCase()}`;
+}
+
+/** Which callbacks the host passed. An item with no callback never shows. */
+export type MenuAvailable = Partial<Record<MenuId, boolean>>;
+
+export function menuItems(
+  available: MenuAvailable,
+  labels: DocLabels,
+  options: { favorited?: boolean } = {},
+): MenuItem[] {
+  const all: MenuItem[] = [
+    { id: "move", label: labels.moveTo, group: 0 },
+    { id: "duplicate", label: labels.duplicate, group: 0 },
+    { id: "rename", label: labels.rename, group: 0 },
+    { id: "template", label: labels.template, group: 0 },
+    { id: "favorite", label: options.favorited ? labels.unfavorite : labels.favorite, group: 1 },
+    { id: "copy", label: labels.copy, submenu: true, group: 1 },
+    { id: "remind", label: labels.remind, group: 1 },
+    { id: "history", label: labels.history, group: 2 },
+    { id: "delete", label: labels.delete, danger: true, group: 2 },
+  ];
+  return all
+    .filter((item) => available[item.id])
+    .map((item) => Object.assign(item, { shortcut: SHORTCUTS[item.id] }));
+}
+
+/** Case-insensitive, every typed word must appear. An empty query keeps everything. */
+export function filterMenu<T extends { label: string }>(items: T[], query: string): T[] {
+  const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+  if (words.length === 0) return items;
+  return items.filter((item) => {
+    const label = item.label.toLowerCase();
+    return words.every((word) => label.includes(word));
+  });
+}
+
+/** The item a key press fires, or null. `code` is the physical key, since Option+F types "ƒ". */
+export function shortcutTarget(
+  event: { code: string; shiftKey: boolean; altKey: boolean; metaKey: boolean; ctrlKey: boolean },
+  items: MenuItem[],
+): MenuId | null {
+  if (event.metaKey || event.ctrlKey) return null;
+  const hit = items.find(
+    (item) =>
+      item.shortcut &&
+      event.code === `Key${item.shortcut.key.toUpperCase()}` &&
+      !!item.shortcut.shift === event.shiftKey &&
+      !!item.shortcut.alt === event.altKey,
+  );
+  return hit?.id ?? null;
+}
+
+export type CopyKind = "url" | "title" | "link" | "markdown";
+
+export type CopyOption = { kind: CopyKind; label: string; text: string };
+
+/** The Copy submenu. A kind with nothing to copy is left out: no URL, no content. */
+export function copyOptions(
+  source: { title: string; url?: string; content?: unknown },
+  labels: DocLabels,
+): CopyOption[] {
+  const title = source.title.trim() || labels.untitled;
+  const options: CopyOption[] = [];
+  if (source.url) options.push({ kind: "url", label: labels.copyUrl, text: source.url });
+  options.push({ kind: "title", label: labels.copyTitle, text: title });
+  if (source.url) {
+    options.push({
+      kind: "link",
+      label: labels.copyTitleAsLink,
+      text: `[${title.replace(/([[\]\\])/g, "\\$1")}](${source.url})`,
+    });
+  }
+  if (source.content) {
+    options.push({
+      kind: "markdown",
+      label: labels.copyMarkdown,
+      text: tiptapToMarkdown(source.content),
+    });
+  }
+  return options;
+}
+
+/** What the delete confirm calls the doc. */
+export function deleteName(title: string, labels: DocLabels): string {
+  return title.trim() || labels.untitled;
+}