@heyramzi/ui 1.54.2 → 2.0.0

package/src/tasks/record/types.ts

@@ -0,0 +1,280 @@
+// The view types of a client or project record. Plain data in, nothing loaded:
+// the host maps its own rows onto these and passes them down.
+import type { PhosphorIcon } from "../../lib/icon-types.js";
+import type { Tone } from "../../lib/tone.js";
+
+/** Where a stage sits in the pipeline. Structure, not an agency's own names. */
+export type StageCategory = "open" | "proposal" | "ongoing" | "completed" | "lost";
+
+/** One stage an agency declares. The record draws its label and tone. */
+export type StageDef = {
+	key: string;
+	label: string;
+	tone: Tone;
+	category: StageCategory;
+};
+
+/**
+ * One thing that happened. Append-only. It belongs to a project, or to a client
+ * when no project exists yet. `occurredAt` is an ISO timestamp.
+ */
+export type RecordEvent = {
+	id: string;
+	/** A registry key: `call`, `note`, `stage`, or a module's own `slug:name`. */
+	kind: string;
+	occurredAt: string;
+	title: string;
+	body?: string | null;
+	/** Money, in the currency's major unit. */
+	amount?: number | null;
+	currency?: string | null;
+	/** Who or what wrote it. The host resolves the name. */
+	actor?: string | null;
+	/** A note that changed after posting. */
+	edited?: boolean;
+	/** The kind's own declared fields, already formatted by the host for display. */
+	details?: { label: string; value: string }[];
+	/** The project it belongs to. Set in client mode, so each entry can say which. */
+	projectId?: string | null;
+	projectName?: string | null;
+	projectHref?: string | null;
+	/** Where the event's source lives: the call, the invoice, the deck. */
+	href?: string | null;
+};
+
+/** The numbers and lines one project rolls up to. The host computes them. */
+export type RecordSummary = {
+	id: string;
+	name: string;
+	href?: string;
+	stageKey: string;
+	/** Short qualifier drawn after the stage, such as a loss reason. */
+	stageDetail?: string | null;
+	/** Money, in the currency's major unit. */
+	value?: number | null;
+	currency?: string | null;
+	/** Money received, from payment events. */
+	paid?: number | null;
+	startDate?: string | null;
+	endDate?: string | null;
+	whereWeAre?: {
+		text: string;
+		/** ISO timestamp of the status event. */
+		at?: string | null;
+		actor?: string | null;
+		health?: { label: string; tone: Tone } | null;
+	} | null;
+	next?: RecordNext | null;
+	lastCallAt?: string | null;
+	lastTouchAt?: string | null;
+	progress?: { done: number; total: number } | null;
+	/** A cancelled or archived project: dropped from "active" and "next". */
+	closed?: boolean;
+};
+
+/** The next milestone, or the next dated task when there are no milestones. */
+export type RecordNext = {
+	label: string;
+	/** ISO date. */
+	date?: string | null;
+	/** ISO date, for a range. */
+	endDate?: string | null;
+	owner?: string | null;
+	href?: string | null;
+	projectId?: string | null;
+	projectName?: string | null;
+};
+
+export type FieldType =
+	| "text"
+	| "longtext"
+	| "choice"
+	| "multi"
+	| "money"
+	| "date"
+	| "url"
+	| "email"
+	| "timezone";
+
+export type FieldOption = {
+	key: string;
+	label: string;
+	tone?: Tone;
+	/** Still reads on old records, cannot be picked. */
+	archived?: boolean;
+};
+
+/** What a field holds. A choice is its option key, a multi is its keys. */
+export type FieldValue = string | number | string[] | null;
+
+/** One attribute a module declares. The record draws it and calls `onSave`. */
+export type FieldDef = {
+	key: string;
+	label: string;
+	type: FieldType;
+	options?: FieldOption[];
+	section?: string;
+	required?: boolean;
+	/** Shown only while another field has this value. Without `equals`, any value. */
+	showWhen?: { key: string; equals?: string | string[] };
+	/** For money. Defaults to the record's currency. */
+	currency?: string;
+	placeholder?: string;
+};
+
+export type FieldSectionDef = { key: string; label: string };
+
+/** One step of the rail. A step is a milestone task. */
+export type StepDef = {
+	id: string;
+	label: string;
+	done: boolean;
+	/** Which group header it sits under, such as Sales or Delivery. */
+	group?: string;
+	/** ISO dates. Both set draws a range, one draws a day. */
+	start?: string | null;
+	end?: string | null;
+	/** Hidden from the rail, still in the edit menu. */
+	hidden?: boolean;
+	/** The label was renamed: the menu offers a reset. */
+	renamed?: boolean;
+};
+
+export type StepGroupDef = { key: string; label: string };
+
+export type StepMarker = "complete" | "current" | "late" | "pending";
+
+/** One row of an `InfoList`. The value is already formatted for display. */
+export type InfoRow = {
+	/** Names the row for a host to find it. Falls back to the label. */
+	id?: string;
+	label: string;
+	icon?: PhosphorIcon;
+	value?: string | null;
+	/** A coloured chip in place of plain text. */
+	tone?: Tone;
+	/** Chips for a multi value. Wins over `value`. */
+	chips?: { label: string; tone?: Tone }[];
+	/** What the editor starts from, when it differs from what is drawn. */
+	editValue?: string | string[] | null;
+	href?: string;
+	muted?: boolean;
+	/** `select` becomes a searchable list past seven options. */
+	input?: "text" | "longtext" | "select" | "multi" | "date" | "number" | "url" | "email";
+	options?: { value: string; label: string; tone?: Tone }[];
+	placeholder?: string;
+	required?: boolean;
+	/** Without it the row is read-only. A multi row passes the picked keys. */
+	onSave?: (value: string | string[]) => void | Promise<void>;
+	divider?: boolean;
+};
+
+/** A kind of event: how its filter chip and its default row read. */
+export type RecordKindDef = {
+	key: string;
+	label: string;
+	icon?: PhosphorIcon;
+	tone?: Tone;
+};
+
+/** A filter chip: a label over the kinds it shows. */
+export type RecordFilterDef = { key: string; label: string; kinds: string[] };
+
+export type RecordLabels = {
+	whereWeAre: string;
+	more: string;
+	less: string;
+	next: string;
+	late: string;
+	steps: string;
+	stepsCount: (done: number, total: number) => string;
+	editSteps: string;
+	rename: string;
+	resetName: string;
+	hide: string;
+	show: string;
+	moveUp: string;
+	moveDown: string;
+	shownCount: (shown: number, total: number) => string;
+	openSteps: string;
+	activity: string;
+	all: string;
+	noEvents: string;
+	older: (count: number) => string;
+	today: string;
+	yesterday: string;
+	by: (name: string) => string;
+	projects: string;
+	projectCount: (count: number) => string;
+	noProjects: string;
+	details: string;
+	edit: (field: string) => string;
+	add: (field: string) => string;
+	save: string;
+	cancel: string;
+	search: string;
+	noMatch: string;
+	pipeline: string;
+	won: string;
+	paid: string;
+	lastCall: string;
+	lastTouch: string;
+	noCall: string;
+	open: string;
+	edited: string;
+	noSteps: string;
+	saveFailed: string;
+	required: string;
+};
+
+export const DEFAULT_RECORD_LABELS: RecordLabels = {
+	whereWeAre: "Where we are",
+	more: "More",
+	less: "Less",
+	next: "Next",
+	late: "Late",
+	steps: "Steps",
+	stepsCount: (done, total) => `${done}/${total}`,
+	editSteps: "Choose visible steps",
+	rename: "Rename",
+	resetName: "Reset name",
+	hide: "Hide",
+	show: "Show",
+	moveUp: "Move up",
+	moveDown: "Move down",
+	shownCount: (shown, total) => `${shown} of ${total} shown`,
+	openSteps: "Open steps",
+	activity: "Activity",
+	all: "All",
+	noEvents: "Nothing logged yet",
+	older: (count) => `Show ${count} older`,
+	today: "Today",
+	yesterday: "Yesterday",
+	by: (name) => `by ${name}`,
+	projects: "Projects",
+	projectCount: (count) => (count === 1 ? "1 project" : `${count} projects`),
+	noProjects: "No projects",
+	details: "Details",
+	edit: (field) => `Edit ${field}`,
+	add: (field) => `Add ${field.toLowerCase()}`,
+	save: "Save",
+	cancel: "Cancel",
+	search: "Search",
+	noMatch: "No match",
+	pipeline: "Pipeline",
+	won: "Won",
+	paid: "Paid",
+	lastCall: "Last call",
+	lastTouch: "Last touch",
+	noCall: "None yet",
+	open: "Open",
+	edited: "edited",
+	noSteps: "No steps yet",
+	saveFailed: "Couldn't save",
+	required: "Required",
+};
+
+/** Merge a partial label set over the defaults. */
+export function resolveLabels(labels?: Partial<RecordLabels>): RecordLabels {
+	return labels ? { ...DEFAULT_RECORD_LABELS, ...labels } : DEFAULT_RECORD_LABELS;
+}

package/src/tasks/record/where-we-are.svelte

@@ -0,0 +1,121 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import { NavigationArrow } from "phosphor-svelte";
+import { cn } from "../../lib/utils.js";
+import { Button } from "../../shadcn/button/index.js";
+import StatusBadge from "../status-badge.svelte";
+import type { Tone } from "../../lib/tone.js";
+import { gutterClass } from "./gutter.js";
+import { formatAge } from "./format.js";
+import { resolveLabels, type RecordLabels } from "./types.js";
+
+// =========================
+// PROPS
+// =========================
+interface Props {
+	/** The status note. Nothing draws without it. */
+	note?: string | null;
+	/** ISO timestamp of the note. */
+	at?: string | null;
+	actor?: string | null;
+	health?: { label: string; tone: Tone } | null;
+	/** Client mode: the project this note belongs to. */
+	project?: { name: string; href?: string | null } | null;
+	labels?: Partial<RecordLabels>;
+	locale?: string;
+	now?: Date | number;
+	class?: string;
+}
+let { note, at, actor, health, project, labels, locale, now, class: className }: Props = $props();
+
+// =========================
+// STATE
+// =========================
+let expanded = $state(false);
+let clamped = $state(false);
+let text = $state<HTMLElement | null>(null);
+
+// =========================
+// DERIVED
+// =========================
+let t = $derived(resolveLabels(labels));
+let age = $derived(at ? formatAge(at, now, locale) : null);
+let hasMeta = $derived(Boolean(health || actor || age));
+
+// =========================
+// EFFECTS
+// =========================
+// WHY measure instead of guessing from length: the clamp is two lines, so the
+// same note fits at 1280px and overflows at 390px. "More" shows only when text is cut.
+$effect(() => {
+	if (!text) return;
+	const el = text;
+	const measure = () => {
+		if (!expanded) clamped = el.scrollHeight > el.clientHeight + 1;
+	};
+	measure();
+	const observer = new ResizeObserver(measure);
+	observer.observe(el);
+	return () => observer.disconnect();
+});
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+{#if note}
+	<section
+		aria-label={t.whereWeAre}
+		class={cn("flex items-start gap-2.5 border-b border-border bg-muted/40 py-2.5", gutterClass, className)}
+	>
+		<NavigationArrow
+			class="mt-0.5 size-3.5 shrink-0 text-[color:var(--tone-accent,var(--color-primary))]"
+			weight="fill"
+			aria-hidden="true"
+		/>
+		<div class="min-w-0 flex-1">
+			<!-- No `title` attribute: a native tooltip would repeat the whole note
+			     over the steps list. "More" opens it in place. -->
+			<p
+				bind:this={text}
+				class={cn("text-sm leading-snug text-muted-foreground", !expanded && "line-clamp-2")}
+			>
+				<span class="font-medium text-foreground">{t.whereWeAre}</span>
+				{#if project}
+					{#if project.href}
+						<a
+							href={project.href}
+							class="font-medium text-foreground underline-offset-2 hover:underline"
+							>{project.name}</a
+						>
+					{:else}
+						<span class="font-medium text-foreground">{project.name}</span>
+					{/if}
+				{/if}
+				<span class="whitespace-pre-line">{note}</span>
+			</p>
+			{#if hasMeta}
+				<p class="mt-1 flex flex-wrap items-center gap-x-2 gap-y-1 text-xs text-muted-foreground">
+					{#if health}
+						<StatusBadge tone={health.tone} dot capitalize={false}>{health.label}</StatusBadge>
+					{/if}
+					{#if actor}<span>{t.by(actor)}</span>{/if}
+					{#if age}<span class="tabular-nums">{age}</span>{/if}
+				</p>
+			{/if}
+		</div>
+		{#if clamped || expanded}
+			<Button
+				variant="ghost"
+				size="sm"
+				class="-mr-2 shrink-0 text-muted-foreground"
+				aria-expanded={expanded}
+				onclick={() => (expanded = !expanded)}
+			>
+				{expanded ? t.less : t.more}
+			</Button>
+		{/if}
+	</section>
+{/if}

package/src/tasks/reorder.ts

@@ -0,0 +1,19 @@
+type Identifiable = { id: string };
+
+/** Move `activeId` to `overId`'s index. Returns a copy; unknown ids pass through. */
+export function reorderByIds<Item extends Identifiable>(
+  items: Item[],
+  activeId: Item["id"],
+  overId: Item["id"],
+): Item[] {
+  const activeIndex = items.findIndex((item) => item.id === activeId);
+  const overIndex = items.findIndex((item) => item.id === overId);
+
+  if (activeIndex === -1 || overIndex === -1 || activeIndex === overIndex) {
+    return items.slice();
+  }
+
+  const next = items.slice();
+  next.splice(overIndex, 0, ...next.splice(activeIndex, 1));
+  return next;
+}

package/src/tasks/side-panel-types.ts

@@ -0,0 +1,16 @@
+// In a .ts file, not the panel's module script, so a plain `tsc` consumer of the
+// barrel can read them. tsc sees a .svelte file as a default export only.
+
+/** How wide the panel opens from `sm` (a short form) to `2xl` (a reader). Under
+    the `sm` breakpoint every panel is full width. */
+export type SidePanelWidth = "sm" | "md" | "lg" | "xl" | "2xl";
+
+/** One number the record is judged on. They sit in the header, in the order given. */
+export type PanelStat = {
+  label: string;
+  value: string;
+  /** A quiet note beside the value: the rate behind a count, or what the figure is. */
+  sub?: string;
+  /** One severity vocabulary: a count that should be zero is `bad`. */
+  tone?: "default" | "muted" | "good" | "bad";
+};

package/src/tasks/side-panel.svelte

@@ -0,0 +1,193 @@
+<script lang="ts" module>
+import type { PanelStat, SidePanelWidth } from "./side-panel-types.js";
+export type { PanelStat, SidePanelWidth };
+</script>
+
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import type { Snippet } from "svelte";
+import * as Sheet from "../shadcn/sheet/index.js";
+import { OpenIn, type OpenInTool } from "../components/open-in/index.js";
+import { CopyButton } from "../components/copy/index.js";
+import type { Tone } from "../lib/tone.js";
+import { cn } from "../lib/utils.js";
+import StatusBadge from "./status-badge.svelte";
+
+// =========================
+// PROPS
+// =========================
+interface Props {
+	open: boolean;
+	/** Names the dialog for screen readers and heads the panel. */
+	title: string;
+	/** Merged onto the title. A short path is set `font-mono`, a subject is not. */
+	titleClass?: string;
+	/** The facts the record is filed under, read out under the title. */
+	description?: string;
+	/** Status chips, left of the action row. */
+	badges?: { label: string; tone: Tone }[];
+	/** Doors out to another tool. `text` replaces the tool's name on the button. */
+	openIn?: { tool: OpenInTool; href: string; label: string; text?: string }[];
+	/** A prompt for an AI about this record, copied on click. */
+	handoff?: { value: () => string | Promise<string>; label: string; copiedLabel: string };
+	/** The record's numbers, as a strip under the badges. Same place in every panel. */
+	stats?: PanelStat[];
+	/** Anything else the record can do, drawn last in the action row. */
+	actions?: Snippet;
+	/** Pinned actions. The body scrolls above it; the caller aligns the row. */
+	footer?: Snippet;
+	children: Snippet;
+	width?: SidePanelWidth;
+	/** The body brings its own header: the title is read out but not drawn, and
+	    the body is neither padded nor scrolled by the panel. */
+	bare?: boolean;
+	/** Fires once when the panel closes, from the close button, Escape or the overlay. */
+	onClose?: () => void;
+};
+let {
+	open = $bindable(),
+	title,
+	titleClass,
+	description,
+	badges = [],
+	openIn = [],
+	handoff,
+	stats = [],
+	actions,
+	footer,
+	children,
+	width = "sm",
+	bare = false,
+	onClose,
+}: Props = $props();
+
+// =========================
+// STATE
+// =========================
+let panel = $state<HTMLElement | null>(null);
+
+// =========================
+// DERIVED
+// =========================
+let hasRow = $derived(badges.length > 0 || openIn.length > 0 || Boolean(handoff || actions));
+const STAT_TONE = {
+	default: "",
+	muted: "text-muted-foreground",
+	good: "text-success",
+	bad: "text-destructive",
+} as const;
+const WIDTH: Record<SidePanelWidth, string> = {
+	sm: "sm:max-w-sm",
+	md: "sm:max-w-md",
+	lg: "sm:max-w-xl",
+	xl: "sm:max-w-2xl",
+	"2xl": "sm:max-w-3xl",
+};
+
+// =========================
+// HANDLERS
+// =========================
+// WHY focus goes to the panel unless a text field comes first: the dialog otherwise
+// opens on its first control, which draws a ring on a record nobody has touched.
+// A form that opens on its field keeps the default, since that is where you type.
+const FIRST_CONTROL =
+	'a[href], button:not([disabled]), input:not([type="hidden"]):not([disabled]), textarea:not([disabled]), select:not([disabled])';
+function onOpenAutoFocus(event: Event) {
+	if (!panel || panel.querySelector(FIRST_CONTROL)?.matches("input, textarea, select")) return;
+	event.preventDefault();
+	panel.focus();
+}
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<Sheet.Root
+	bind:open
+	onOpenChange={(next) => {
+		if (!next) onClose?.();
+	}}
+>
+	<Sheet.Content
+		side="right"
+		bind:ref={panel}
+		tabindex={-1}
+		class={cn("flex w-full flex-col gap-0 p-0", WIDTH[width], bare && "overflow-hidden")}
+		{onOpenAutoFocus}
+	>
+		{#if bare}
+			<Sheet.Header class="sr-only">
+				<Sheet.Title>{title}</Sheet.Title>
+			</Sheet.Header>
+			{@render children()}
+		{:else}
+			<Sheet.Header class="gap-1 border-b border-border">
+				<!-- WHY the right padding: the close button sits over this corner and
+				     a long title runs straight under it. -->
+				<Sheet.Title class={cn("pr-9 text-base leading-snug", titleClass)}>{title}</Sheet.Title>
+				{#if description}
+					<Sheet.Description>{description}</Sheet.Description>
+				{/if}
+				{#if hasRow}
+					<div class="flex items-center justify-between gap-3 pt-1.5">
+						<div class="flex min-w-0 flex-wrap items-center gap-2">
+							{#each badges as badge (`${badge.tone}:${badge.label}`)}
+								<StatusBadge tone={badge.tone}>{badge.label}</StatusBadge>
+							{/each}
+						</div>
+						<div class="flex shrink-0 items-center gap-1">
+							{#each openIn as door (door.href)}
+								<OpenIn
+									tool={door.tool}
+									href={door.href}
+									title={door.label}
+									label={door.text}
+									variant="button"
+									size="sm"
+								/>
+							{/each}
+							{#if handoff}
+								<CopyButton
+									agent
+									value={handoff.value}
+									label={handoff.label}
+									copiedLabel={handoff.copiedLabel}
+								/>
+							{/if}
+							{@render actions?.()}
+						</div>
+					</div>
+				{/if}
+				{#if stats.length > 0}
+					<dl class="flex flex-wrap gap-x-6 gap-y-3 pt-3">
+						{#each stats as stat (stat.label)}
+							<div class="min-w-0">
+								<dt class="text-xs text-muted-foreground">{stat.label}</dt>
+								<dd class={cn("text-sm font-medium tabular-nums", STAT_TONE[stat.tone ?? "default"])}>
+									{stat.value}
+									{#if stat.sub}
+										<span class="text-xs font-normal text-muted-foreground">{stat.sub}</span>
+									{/if}
+								</dd>
+							</div>
+						{/each}
+					</dl>
+				{/if}
+			</Sheet.Header>
+
+			<!-- WHY the body pads and spaces its sections itself: a panel that lets the
+			     caller choose drifts, one with a grey band and one with a white page. -->
+			<div class="flex min-h-0 flex-1 flex-col gap-4 overflow-y-auto p-4">
+				{@render children()}
+			</div>
+
+			{#if footer}
+				<Sheet.Footer class="mt-0 flex-row items-center justify-end border-t border-border">
+					{@render footer()}
+				</Sheet.Footer>
+			{/if}
+		{/if}
+	</Sheet.Content>
+</Sheet.Root>

package/src/tasks/status-badge.svelte

@@ -0,0 +1,63 @@
+<script lang="ts">
+	import type { Snippet } from "svelte";
+	import type { HTMLAttributes } from "svelte/elements";
+	import { cn } from "../lib/utils.js";
+	import { Badge } from "../shadcn/badge/index.js";
+	import { Spinner } from "../shadcn/spinner/index.js";
+	import { TONE_COLOR, type Tone } from "../lib/tone.js";
+	import type { Statuses } from "./status-types.js";
+
+	interface Props extends Omit<HTMLAttributes<HTMLSpanElement>, "class" | "children"> {
+		/** A registry from `defineStatuses`. Supplies the label and tone. */
+		statuses?: Statuses;
+		/** The status id to look up in `statuses`. Leave it out when you pass `children`. */
+		status?: string;
+		/** Override the registry label. */
+		label?: string;
+		/** Override the registry tone. */
+		tone?: Tone;
+		/** Shows a dot in the tone's colour before the label. */
+		dot?: boolean;
+		/** Shows a spinner: a background job is still working on the record. */
+		busy?: boolean;
+		/** Capitalizes the first letter of each word. Turn off for a name or a number. */
+		capitalize?: boolean;
+		/** The chip's text, for a caller that already has the word. Wins over `label` and the registry. */
+		children?: Snippet;
+		class?: string;
+	}
+
+	let {
+		statuses,
+		status,
+		label,
+		tone,
+		dot = false,
+		busy = false,
+		capitalize = true,
+		children,
+		class: className,
+		...restProps
+	}: Props = $props();
+
+	let resolvedTone = $derived(tone ?? (statuses && status ? statuses.tone(status) : "neutral"));
+	let resolvedLabel = $derived(label ?? (statuses && status ? statuses.label(status) : (status ?? "")));
+</script>
+
+<Badge tone={resolvedTone} class={cn(capitalize && "capitalize", className)} {...restProps}>
+	{#if dot}
+		<span
+			class="size-1.5 shrink-0 rounded-full"
+			style:background-color={TONE_COLOR[resolvedTone]}
+			aria-hidden="true"
+		></span>
+	{/if}
+	{#if busy}
+		<Spinner class="size-3" aria-hidden="true" />
+	{/if}
+	{#if children}
+		{@render children()}
+	{:else}
+		{resolvedLabel}
+	{/if}
+</Badge>