@heyramzi/tasks 0.0.0-stage → 0.4.0

package/src/kanban-drag.ts

@@ -0,0 +1,38 @@
+const FRAME_PAD = 16;
+
+/**
+ * Native drag shows a flat, faded snapshot. This hands the browser a tilted
+ * copy with a lifted shadow instead. Call it from `ondragstart`.
+ */
+export function liftDragImage(e: DragEvent, tilt = -3): void {
+  const source = e.currentTarget as HTMLElement | null;
+  if (!source || !e.dataTransfer) return;
+  const rect = source.getBoundingClientRect();
+
+  // The padded frame leaves room for the tilt and shadow, or the snapshot crops them.
+  const frame = document.createElement("div");
+  Object.assign(frame.style, {
+    position: "fixed",
+    top: "-10000px",
+    left: "-10000px",
+    padding: `${FRAME_PAD}px`,
+    pointerEvents: "none",
+  });
+
+  const ghost = source.cloneNode(true) as HTMLElement;
+  Object.assign(ghost.style, {
+    width: `${rect.width}px`,
+    opacity: "1",
+    rotate: `${tilt}deg`,
+    filter:
+      "drop-shadow(0 2px 4px rgb(35 35 35 / 0.08)) drop-shadow(0 10px 18px rgb(35 35 35 / 0.14))",
+  });
+  frame.appendChild(ghost);
+  document.body.appendChild(frame);
+  e.dataTransfer.setDragImage(
+    frame,
+    e.clientX - rect.left + FRAME_PAD,
+    e.clientY - rect.top + FRAME_PAD,
+  );
+  setTimeout(() => frame.remove());
+}

package/src/kanban-types.ts

@@ -0,0 +1,65 @@
+import type { Snippet } from "svelte";
+
+/** A column the board renders. `id` is the value `getColumn` returns for a card. */
+export type KanbanColumn = {
+  id: string;
+  label: string;
+  /** Any CSS color. Shown as a tint on the column while a card is held over it. */
+  hue?: string;
+  /** Screen-reader label for the column region. Defaults to `label`. */
+  ariaLabel?: string;
+  /**
+   * Set false to make the column a display-only lane: cards there cannot be
+   * dragged over or dropped onto (e.g. an Overdue lane). Defaults to true.
+   */
+  droppable?: boolean;
+};
+
+/** What the board asks the caller to persist after a drop. */
+export type KanbanMove = {
+  columnId: string;
+  /**
+   * Only set when the active sort is manual: a fractional key that places the
+   * card in its new slot. Ignore it when you persist order some other way.
+   */
+  boardOrder?: string;
+  /**
+   * The cards that sit above and below the drop slot once the dragged card is
+   * set aside. Set on manual drops only, null at an end. For a backend that
+   * orders by neighbour instead of by key.
+   */
+  beforeId?: string | null;
+  afterId?: string | null;
+};
+
+/** A named sort the board can apply instead of manual (`boardOrder`) ordering. */
+export type KanbanSortKey<T> = {
+  id: string;
+  label: string;
+  compare: (a: T, b: T) => number;
+};
+
+/** Second argument handed to the card snippet. */
+export type KanbanCardContext = {
+  columnId: string;
+  index: number;
+};
+
+/** Second argument handed to the column header and footer snippets. */
+export type KanbanColumnContext = {
+  /** Every card in the column, including the ones a `limit` keeps out of view. */
+  count: number;
+  /** A card is held over the column. */
+  active: boolean;
+  /** How many cards render. Fewer than `count` while the column is capped. */
+  shown: number;
+  /** The column's `limit` is hiding its tail. */
+  capped: boolean;
+  /** Fold the column into the hidden rail. Needs `hidden` or `onHiddenChange` on the board. */
+  hide: () => void;
+  /** Lift the `limit` so every card shows. */
+  expand: () => void;
+};
+
+/** The default header renderer when no `columnHeader` snippet is given. */
+export type KanbanCardSnippet<T> = Snippet<[T, KanbanCardContext]>;

package/src/lib/cn.ts

@@ -0,0 +1,11 @@
+export type ClassValue = string | false | null | undefined;
+
+/** Join class values, dropping empties. Deliberately dependency-free. */
+export function cn(...values: ClassValue[]): string {
+  let out = "";
+  for (const value of values) {
+    if (!value) continue;
+    out = out ? out + " " + value : value;
+  }
+  return out;
+}

package/src/presets/sales.ts

@@ -0,0 +1,16 @@
+import { defineStatuses } from "../define-statuses.js";
+
+/**
+ * An example status map for a sales pipeline. Names are neutral on purpose:
+ * swap the keys and labels for your own domain.
+ */
+export const salesStatuses = defineStatuses({
+	new: { label: "New", tone: "accent", variant: "open" },
+	contacted: { label: "Contacted", tone: "info", variant: "open" },
+	proposal: { label: "Proposal", tone: "accent", variant: "progress", progress: 0.25 },
+	negotiation: { label: "Negotiation", tone: "warning", variant: "progress", progress: 0.75 },
+	won: { label: "Won", tone: "success", variant: "completed" },
+	lost: { label: "Lost", tone: "destructive", variant: "lost" },
+});
+
+export type SalesStatus = (typeof salesStatuses.ids)[number];

package/src/reorder.ts

@@ -0,0 +1,20 @@
+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();
+  const [moved] = next.splice(activeIndex, 1);
+  next.splice(overIndex, 0, moved);
+  return next;
+}

package/src/status-badge.svelte

@@ -0,0 +1,57 @@
+<script lang="ts">
+	import type { Snippet } from "svelte";
+	import { cn } from "./lib/cn.js";
+	import { TONE_CLASS } from "./tone.js";
+	import type { Tone, Statuses } from "./status-types.js";
+	import spinnerIcon from "./icons/spinner.svg?raw";
+
+	type Props = {
+		/** 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 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,
+		busy = false,
+		capitalize = true,
+		children,
+		class: className,
+	}: Props = $props();
+
+	let resolvedTone = $derived(tone ?? (statuses && status ? statuses.tone(status) : "neutral"));
+	let resolvedLabel = $derived(label ?? (statuses && status ? statuses.label(status) : (status ?? "")));
+</script>
+
+<span
+	class={cn(
+		"inline-flex h-5 shrink-0 items-center justify-center gap-1 rounded-full border px-2 text-xs font-medium whitespace-nowrap",
+		capitalize && "capitalize",
+		TONE_CLASS[resolvedTone],
+		className,
+	)}
+>
+	{#if busy}
+		<span class="size-3 animate-spin [&>svg]:size-full" aria-hidden="true">{@html spinnerIcon}</span>
+	{/if}
+	{#if children}
+		{@render children()}
+	{:else}
+		{resolvedLabel}
+	{/if}
+</span>

package/src/status-dot.svelte

@@ -0,0 +1,228 @@
+<script lang="ts">
+	import { cn } from "./lib/cn.js";
+	import { TONE_COLOR } from "./tone.js";
+	import type { StatusDotVariant, Statuses } from "./status-types.js";
+
+	interface Props {
+		/** A registry from `defineStatuses`. Resolves color, variant and progress. */
+		statuses?: Statuses;
+		status?: string;
+		/** Explicit color, overrides the registry and tone. */
+		color?: string;
+		variant?: StatusDotVariant;
+		progress?: number;
+		size?: number;
+		animate?: boolean;
+		class?: string;
+	}
+
+	let {
+		statuses,
+		status,
+		color,
+		variant,
+		progress,
+		size = 14,
+		animate = true,
+		class: className,
+	}: Props = $props();
+
+	const INNER_R = 2;
+	const INNER_CIRC = 2 * Math.PI * INNER_R;
+
+	function clamp01(n: number): number {
+		return Math.max(0, Math.min(1, n));
+	}
+
+	let resolvedColor = $derived(
+		color ??
+			(statuses && status ? statuses.color(status) : undefined) ??
+			(statuses && status ? TONE_COLOR[statuses.tone(status)] : undefined) ??
+			TONE_COLOR.neutral,
+	);
+	let resolvedVariant = $derived(
+		variant ?? (statuses && status ? statuses.variant(status) : "open"),
+	);
+	let resolvedProgress = $derived(
+		progress ?? (statuses && status ? statuses.progress(status) : undefined),
+	);
+	let fraction = $derived(
+		resolvedVariant === "progress" && typeof resolvedProgress === "number"
+			? clamp01(resolvedProgress)
+			: undefined,
+	);
+	let dasharray = $derived(
+		fraction != null
+			? `${INNER_CIRC * fraction} ${INNER_CIRC * (1 - fraction)}`
+			: undefined,
+	);
+	let dashoffset = $derived(fraction != null ? INNER_CIRC * 0.25 : undefined);
+</script>
+
+{#if resolvedVariant === "completed"}
+	<svg
+		width={size}
+		height={size}
+		viewBox="0 0 14 14"
+		fill="none"
+		aria-hidden="true"
+		class={cn("sd", className)}
+	>
+		<circle cx="7" cy="7" r="6" fill={resolvedColor} class={animate ? "sd-pop" : ""}></circle>
+		<polyline
+			points="4.5,7 6.5,9 9.5,5"
+			fill="none"
+			class={cn("sd-mark", animate && "sd-check")}
+			stroke-width="1.5"
+			stroke-linecap="round"
+			stroke-linejoin="round"
+		></polyline>
+	</svg>
+{:else if resolvedVariant === "lost"}
+	<svg
+		width={size}
+		height={size}
+		viewBox="0 0 14 14"
+		fill="none"
+		aria-hidden="true"
+		class={cn("sd", className)}
+	>
+		<circle cx="7" cy="7" r="6" fill={resolvedColor} class={animate ? "sd-pop" : ""}></circle>
+		<g class="sd-mark" stroke-width="1.5" stroke-linecap="round">
+			<line x1="5" y1="5" x2="9" y2="9" class={animate ? "sd-cross" : ""}></line>
+			<line x1="9" y1="5" x2="5" y2="9" class={animate ? "sd-cross sd-cross-second" : ""}></line>
+		</g>
+	</svg>
+{:else if resolvedVariant === "filled"}
+	<svg
+		width={size}
+		height={size}
+		viewBox="0 0 14 14"
+		fill="none"
+		aria-hidden="true"
+		class={cn("sd", className)}
+	>
+		<circle cx="7" cy="7" r="6" fill={resolvedColor} class={animate ? "sd-pop" : ""}></circle>
+	</svg>
+{:else}
+	<svg
+		width={size}
+		height={size}
+		viewBox="0 0 14 14"
+		fill="none"
+		aria-hidden="true"
+		class={cn("sd", className)}
+	>
+		<circle
+			cx="7"
+			cy="7"
+			r="5.5"
+			stroke={resolvedColor}
+			stroke-width="1.5"
+			class={resolvedVariant === "dashed" ? "sd-dashed" : ""}
+		></circle>
+		{#if dasharray}
+			<circle
+				cx="7"
+				cy="7"
+				r={INNER_R}
+				fill="none"
+				stroke={resolvedColor}
+				stroke-width="4"
+				stroke-dasharray={dasharray}
+				stroke-dashoffset={dashoffset}
+				transform="rotate(-90 7 7)"
+				class={animate ? "sd-fill" : ""}
+			></circle>
+		{/if}
+	</svg>
+{/if}
+
+<style>
+	.sd {
+		flex-shrink: 0;
+	}
+
+	/* The tick and cross read as cut out of the disc. A host sets the mark to its own ground. */
+	.sd-mark {
+		stroke: var(--status-dot-mark, white);
+	}
+
+	/* 12 dashes that close evenly: 2 * PI * 5.5 = 34.56, cut into 12 periods of 2.88. */
+	.sd-dashed {
+		stroke-dasharray: 1.3 1.58;
+	}
+
+	.sd-fill {
+		transform-origin: 7px 7px;
+		animation: sd-fill-in var(--duration-slow, 320ms) var(--ease-smooth-out, ease-out) forwards;
+	}
+
+	@keyframes sd-fill-in {
+		from {
+			transform: rotate(-90deg) scale(0.4);
+			opacity: 0;
+		}
+		to {
+			transform: rotate(-90deg) scale(1);
+			opacity: 1;
+		}
+	}
+
+	.sd-pop {
+		transform-origin: 7px 7px;
+		animation: sd-pop-in var(--duration-medium, 240ms) var(--ease-smooth-out, ease-out) forwards;
+	}
+
+	@keyframes sd-pop-in {
+		from {
+			transform: scale(0.4);
+			opacity: 0;
+		}
+		60% {
+			transform: scale(1.08);
+			opacity: 1;
+		}
+		to {
+			transform: scale(1);
+			opacity: 1;
+		}
+	}
+
+	.sd-check {
+		stroke-dasharray: 12;
+		stroke-dashoffset: 12;
+		animation: sd-trace var(--duration-medium, 240ms) var(--ease-smooth-out, ease-out)
+			var(--duration-quick, 120ms) forwards;
+	}
+
+	.sd-cross {
+		stroke-dasharray: 6;
+		stroke-dashoffset: 6;
+		animation: sd-trace calc(var(--duration-fast, 160ms) / 2) var(--ease-smooth-out, ease-out)
+			var(--duration-quick, 120ms) forwards;
+	}
+
+	.sd-cross-second {
+		animation-delay: calc(var(--duration-quick, 120ms) + var(--duration-fast, 160ms) / 2);
+	}
+
+	@keyframes sd-trace {
+		to {
+			stroke-dashoffset: 0;
+		}
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.sd-fill,
+		.sd-pop,
+		.sd-check,
+		.sd-cross {
+			animation: none;
+		}
+		.sd-check,
+		.sd-cross {
+			stroke-dashoffset: 0;
+		}
+	}
+</style>

package/src/status-icon.svelte

@@ -0,0 +1,30 @@
+<script lang="ts">
+	import type { Component } from "svelte";
+	import StatusDot from "./status-dot.svelte";
+	import { cn } from "./lib/cn.js";
+	import { TONE_ICON } from "./tone.js";
+	import type { Statuses } from "./status-types.js";
+
+	type Props = {
+		statuses: Statuses;
+		status: string;
+		size?: number;
+		animate?: boolean;
+		class?: string;
+	};
+
+	let { statuses, status, size = 14, animate = true, class: className }: Props = $props();
+
+	// An icon in the map wins; otherwise the status falls back to its dot.
+	let icon = $derived(
+		statuses.icon(status) as Component<{ size?: number; class?: string }> | undefined,
+	);
+	let tone = $derived(statuses.tone(status));
+</script>
+
+{#if icon}
+	{@const Icon = icon}
+	<Icon {size} class={cn("shrink-0", TONE_ICON[tone], className)} />
+{:else}
+	<StatusDot {statuses} {status} {size} {animate} class={className} />
+{/if}

package/src/status-types.ts

@@ -0,0 +1,42 @@
+import type { Component } from "svelte";
+
+/** The one severity scale the kit ships. */
+export type Tone = "neutral" | "accent" | "info" | "success" | "warning" | "destructive";
+
+/**
+ * The shape the dot can take. `progress` needs a `progress` value between 0 and 1.
+ * `dashed` is an open ring cut into dashes, for an aggregate such as "All".
+ */
+export type StatusDotVariant = "open" | "dashed" | "progress" | "filled" | "completed" | "lost";
+
+export type StatusDef = {
+	label: string;
+	tone?: Tone;
+	/** Any Svelte component, for example a Phosphor icon. Renders inside StatusIcon. */
+	icon?: Component;
+	variant?: StatusDotVariant;
+	/** 0 to 1. Only used by the `progress` variant. */
+	progress?: number;
+	/** Optional CSS color. Overrides the tone color for the dot and icon. */
+	color?: string;
+	description?: string;
+};
+
+export type StatusMap = Record<string, StatusDef>;
+
+export type StatusId<M extends StatusMap> = keyof M & string;
+
+/** What the components accept. `defineStatuses` returns this plus a typed `ids`. */
+export type Statuses = {
+	/** The raw map. Kept loose so a registry with specific keys is assignable here. */
+	map: StatusMap;
+	ids: string[];
+	has(id: string): boolean;
+	get(id: string): StatusDef | undefined;
+	label(id: string): string;
+	tone(id: string): Tone;
+	icon(id: string): Component | undefined;
+	variant(id: string): StatusDotVariant;
+	progress(id: string): number | undefined;
+	color(id: string): string | undefined;
+};