@heyramzi/tasks 0.3.0 → 0.4.0

package/README.md

@@ -73,12 +73,26 @@ isn't a drop target (an Overdue lane, say).
 | `sortKey`       | `string`                                                | Active sort. Defaults to `"manual"`.                        |
 | `columnHeader`  | `Snippet<[KanbanColumn, { count, active }]>`            | Optional header. Defaults to label plus count.              |
 | `emptyLabel`    | `string`                                                | Shown in an empty column.                                   |
-| `dropAtTop`     | `(columnId: string) => boolean`                         | Drops on a capped column go to the top.                     |
+| `dropAtTop`     | `(columnId: string) => boolean`                         | Drops on a capped column go to the top. Defaults to "is `limit` hiding its tail".  |
 | `isDroppable`   | `(columnId: string) => boolean`                         | Overrides the per-column `droppable` flag.                  |
-
-`onMove` gives `{ columnId, boardOrder? }`. `boardOrder` is only set for manual
-sorting. It's a fractional key that places the card in its new slot, so a move
-writes one row instead of renumbering a column.
+| `manualTiebreak` | `(a: T, b: T) => number`                               | Settles two cards with the same manual key, or none.        |
+| `getLabel`      | `(item: T) => string`                                   | The screen-reader name of a card. Defaults to a keyboard hint. |
+| `onSelect`      | `(id: string) => void`                                  | Enter or Space on a focused card.                           |
+| `columnFooter`  | `Snippet<[Column, KanbanColumnContext]>`                | Under a column's cards: a "Show all" or an add button.      |
+| `wrapColumn`    | `Snippet<[Column, Snippet<[props]>]>`                   | Wraps a whole column, for a context menu. Render the inner snippet once with the props you are handed. |
+| `limit`         | `(columnId: string) => number \| undefined`             | Cards a column shows before the rest fold. `expanded` and `onExpandedChange` lift it per column. |
+| `hidden`        | `string[]`                                              | Columns folded into a rail on the right. Fold and unfold animate, and a card dropped on a rail entry brings the column back. `onHiddenChange`, `hiddenLabel`, `showAllLabel` and `hiddenItem` go with it. |
+
+`columns` can be your own type, as long as it extends `KanbanColumn`: the
+header, footer and wrap snippets get it back as you passed it, so a column can
+carry a status or a stage for your own markup. The header and footer context is
+`{ count, active, shown, capped, hide, expand }`.
+
+`onMove` gives `{ columnId, boardOrder?, beforeId?, afterId? }`. On a manual
+drop `beforeId` and `afterId` name the cards above and below the new slot (null
+at an end), for a backend that orders by neighbour. `boardOrder` is set when you
+pass a `boardOrder` accessor. It's a fractional key that places the card in its
+new slot, so a move writes one row instead of renumbering a column.
 
 ## List
 
@@ -107,8 +121,31 @@ group. Rows slide into their new place when the order changes.
 ```
 
 Beyond the board's props it takes `head` (a sticky header row), `groupHeader`
-(`Snippet<[group, { count, active, open }]>`), `collapsible` (default true) and
-`collapsed` (group ids that start folded).
+(`Snippet<[group, { count, active, open, depth, hasChildren }]>`), `actions` (controls at the end of
+a group header, shown on hover), `groupFooter` (an add-task row under the rows),
+`collapsible` (default true), `collapsed` (group ids that start folded) and
+`onCollapsedChange`. Pass `flat` to drop the card border, radius and fill so the list sits on the page (the gantt takes it too); group dividers stay. Pass `draggable={false}` for a list that only groups: rows
+lose the drag handlers and the keyboard move, so links and buttons inside them
+keep every key.
+
+Pass `getParent` to nest one group under another, such as a project under its
+client. It takes a group and returns the id of its parent, or nothing for a
+top-level group. A child draws inside its parent's section, indented, with its
+own sticky header under the parent's, and folds when the parent folds. A parent
+takes no drops and its `count` adds up its children. A child whose parent id
+matches no group is drawn at the top level.
+
+```svelte
+<TaskList
+  groups={[
+    { id: "acme", label: "Acme" },
+    { id: "acme-site", label: "Website", parent: "acme" },
+    { id: "acme-audit", label: "Audit", parent: "acme" },
+  ]}
+  getParent={(group) => group.parent}
+  ...
+/>
+```
 
 ## Gantt
 
@@ -135,14 +172,18 @@ its end. Leave out `onChange` and the chart is read only.
 | Prop           | Type                                      | Notes                                                       |
 | -------------- | ----------------------------------------- | ----------------------------------------------------------- |
 | `items`, `getId`, `getTitle` |                             | Required.                                                   |
-| `getStart`, `getEnd` | `(item: T) => string`               | ISO dates, inclusive. A one-day task has the same start and end. |
+| `getStart`, `getEnd` | `(item: T) => string \| null \| undefined` | ISO dates, inclusive. A one-day task has the same start and end. One date alone is a one-day task, none is undated. A parent with no dates draws the span of its children as an outline bar. |
 | `onChange`     | `(id, { start, end }) => void \| Promise<void>` | Called after a drag, a resize or a key nudge.        |
 | `onSelect`     | `(id) => void`                            | A click or Enter that didn't move the bar.                  |
 | `getHue`       | `(item: T) => string \| undefined`         | Bar color. Falls back to the group hue, then `--color-primary`. |
 | `getProgress`  | `(item: T) => number \| undefined`         | 0 to 1, filled from the left.                               |
 | `getDependsOn` | `(item: T) => string[] \| undefined`       | Draws an arrow from each listed task's end to this one's start. |
 | `groups`, `getGroup` |                                     | Optional. Groups rows under a header with a span line.      |
-| `renderLabel`  | `Snippet<[T]>`                            | The left column. Defaults to the title.                     |
+| `getParent`    | `(item: T) => string \| null \| undefined` | Nests a task under another by id: indented, foldable, depth first. |
+| `collapsed`    | `string[]`                                | Parent ids that start folded.                               |
+| `isMilestone`  | `(item: T) => boolean`                    | Draws a flag at the end date instead of a bar. Not draggable. |
+| `noDatesLabel` | `string`                                  | Shown for a task with no dates. Default "No dates".         |
+| `renderLabel`  | `Snippet<[T, { depth, hasChildren, open }]>` | The left column. Defaults to the title.                  |
 | `from`, `to`   | `string`                                  | The shown range. Defaults to the tasks' span, padded, from a Monday. |
 | `today`        | `string`                                  | Where the today line sits. Defaults to the viewer's today.  |
 | `dayWidth`     | `number`                                  | Default 32. Under 18 the header shows week starts only.     |
@@ -158,6 +199,54 @@ with a pill that slides to the active option. Pass `views`
 (`{ id, label, icon? }[]`) and `bind:value`. `BoardIcon`, `ListIcon` and
 `GanttIcon` are exported for it.
 
+## Time tracking
+
+Optional. `TimeTracker` logs time against one task: a start and stop timer, quick
+entry that reads `1h30`, `90m`, `1.5h` or `1:30`, a date and a note, entries
+grouped by day with day totals, a per-person split and an optional estimate shown
+as a ring that turns warning at 90% and destructive past 100%. It holds no data
+and fetches nothing. You pass entries in and persist what it hands back.
+
+```svelte
+<TimeTracker
+  entries={entries}
+  getId={(e) => e.id}
+  getMinutes={(e) => e.minutes}
+  getDay={(e) => e.day}
+  getPerson={(e) => e.person}
+  estimate={480}
+  {running}
+  onStart={() => (running = { startedAt: Date.now() })}
+  onStop={(info) => save(info.minutes, info.day)}
+  onLog={(input) => save(input.minutes, input.day, input.note)}
+  onDelete={(entry) => remove(entry.id)}
+/>
+```
+
+| Prop | Type | Notes |
+| --- | --- | --- |
+| `entries` | `T[]` | Every entry on the task. |
+| `getId`, `getMinutes`, `getDay`, `getPerson` | accessors | `getDay` returns `YYYY-MM-DD`. |
+| `getPersonId`, `getNote` | accessors | Optional. The id keeps two people with one name apart. |
+| `running` | `{ startedAt } \| null` | The host stores it, so it survives a reload. |
+| `estimate` | `number` | Minutes budgeted. Draws the ring. |
+| `onStart` | `() => void` | The host sets `running`. |
+| `onStop` | `(info) => void` | `info` is `{ minutes, startedAt, stoppedAt, day }`. Clear `running` after saving. |
+| `onLog` | `(input) => void \| boolean` | `input` is `{ minutes, day, note? }`. Return `false` to keep the fields. |
+| `onDelete`, `canDelete` | callback | The delete button shows when `onDelete` is set and `canDelete` allows it. |
+| `renderMeta` | `Snippet<[T]>` | Extra text after a row's note. |
+| `flat` | `boolean` | Drops the card (border, radius, background, shadow, padding) for a host that already has a panel. The running state then shows through the dot, readout and button. |
+| `locale`, `labels`, `class` | | `labels` overrides any string in `DEFAULT_TIME_LABELS`. |
+
+Alt+S starts and stops the timer. A screen reader hears the start, one update a
+minute and the stop. Import it alone from `@heyramzi/tasks/time`.
+
+For boards and lists: `TimeChip` (`minutes`, `estimate?`, `running?`) shows the
+logged total, with a pulsing dot while a timer runs and a small ring against an
+estimate. `TimeRing` and `TimeDot` are the pieces under it.
+`parseMinutes`, `formatMinutes`, `formatClock`, `budgetTone` and `localDay` are
+exported helpers.
+
 ## Also exported
 
 - `KanbanColumn`: the column shell, if you want to build your own board.
@@ -167,12 +256,16 @@ with a pill that slides to the active option. Pass `views`
 - `reorderByIds`: move an item to another item's index in a flat list.
 - `addDays`, `dayNumber`, `isoFromDay`, `todayIso`: the date helpers the gantt uses.
 - `StatusBadge`, `StatusDot`, `StatusIcon`: chips, dots and icons from one config.
+  A badge also takes its text as children, for a caller that already has the word.
 - `defineStatuses`: builds a status registry from a plain map.
 - `TONE_CLASS`, `TONE_COLOR`, `TONE_ICON`, `TONE_TEXT`, `insetWellClass`: the severity scale.
 - `salesStatuses`: an example pipeline map.
 
 ## Styling
 
+The accent tone reads `--tone-accent` and falls back to `--color-primary`. Set
+`--tone-accent` when your primary is a neutral and your accent is a brand color.
+
 Classes are Tailwind, on shadcn-style tokens (`bg-card`, `border-border`,
 `text-muted-foreground`, `--color-primary`). Point Tailwind at the package with
 `@source` so it generates them. Motion reads the `--duration-*` and `--ease-*`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyramzi/tasks",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Svelte 5 task views: a drag-and-drop board, a grouped list and a gantt timeline from one config, plus status badges, dots and icons.",
   "keywords": [
     "svelte",
@@ -54,6 +54,26 @@
       "types": "./src/status-badge.svelte",
       "default": "./src/status-badge.svelte"
     },
+    "./status-dot": {
+      "svelte": "./src/status-dot.svelte",
+      "types": "./src/status-dot.svelte",
+      "default": "./src/status-dot.svelte"
+    },
+    "./statuses": {
+      "svelte": "./src/define-statuses.ts",
+      "types": "./src/define-statuses.ts",
+      "default": "./src/define-statuses.ts"
+    },
+    "./time": {
+      "svelte": "./src/time/time-tracker.svelte",
+      "types": "./src/time/time-tracker.svelte",
+      "default": "./src/time/time-tracker.svelte"
+    },
+    "./inbox": {
+      "svelte": "./src/inbox/index.ts",
+      "types": "./src/inbox/index.ts",
+      "default": "./src/inbox/index.ts"
+    },
     "./presets/sales": {
       "svelte": "./src/presets/sales.ts",
       "types": "./src/presets/sales.ts",
@@ -66,9 +86,12 @@
     "./demo.svelte": "./src/demo.svelte"
   },
   "peerDependencies": {
+    "@heyramzi/ui": "*",
     "svelte": "^5.0.0"
   },
   "devDependencies": {
+    "@heyramzi/ui": "7.0.0",
+    "@types/node": "^26.6.4",
     "svelte-check": "^4.7.6",
     "typescript": "~7.0.2"
   },

package/src/demo.svelte

@@ -13,6 +13,9 @@
 	import { salesStatuses } from "./presets/sales.js";
 	import type { KanbanMove } from "./kanban-types.js";
 	import type { GanttChange } from "./task-types.js";
+	import TimeTracker from "./time/time-tracker.svelte";
+	import TimeChip from "./time/time-chip.svelte";
+	import type { TimeLogInput, TimeStopInfo } from "./time/time-types.js";
 
 	type Priority = "low" | "medium" | "high";
 
@@ -107,6 +110,52 @@
 		tasks = tasks.map((task) => (task.id === id ? { ...task, ...change } : task));
 	}
 
+	// ---- time tracking, an option the host turns on
+	type Entry = { id: string; taskId: string; person: string; day: string; minutes: number; note?: string };
+
+	const estimates: Record<string, number> = { t3: 360, t4: 480, t5: 180, t6: 240 };
+
+	let tracking = $state(true);
+	let timeTaskId = $state("t4");
+	let nextEntry = 100;
+	let entries = $state<Entry[]>([
+		{ id: "e1", taskId: "t4", person: "Dana", day: on(-3), minutes: 150, note: "Signup and email step" },
+		{ id: "e2", taskId: "t4", person: "Ada", day: on(-2), minutes: 95, note: "Copy for the welcome screen" },
+		{ id: "e3", taskId: "t4", person: "Dana", day: on(-2), minutes: 125, note: "Progress bar and empty states" },
+		{ id: "e4", taskId: "t4", person: "Dana", day: on(-1), minutes: 80 },
+		{ id: "e5", taskId: "t3", person: "Ada", day: on(-5), minutes: 210, note: "First draft" },
+		{ id: "e6", taskId: "t3", person: "Bo", day: on(-3), minutes: 95, note: "Pricing table" },
+		{ id: "e7", taskId: "t3", person: "Ada", day: on(-1), minutes: 85, note: "Review changes" },
+		{ id: "e8", taskId: "t5", person: "Bo", day: on(0), minutes: 40 },
+		{ id: "e9", taskId: "t1", person: "Bo", day: on(-12), minutes: 60 },
+	]);
+	// The host keeps the running timer. A reload would read it back from storage.
+	let timer = $state<{ taskId: string; startedAt: number } | null>({
+		taskId: "t4",
+		startedAt: Date.now() - (12 * 60 + 41) * 1000,
+	});
+
+	let minutesByTask = $derived.by(() => {
+		const totals: Record<string, number> = {};
+		for (const entry of entries) totals[entry.taskId] = (totals[entry.taskId] ?? 0) + entry.minutes;
+		return totals;
+	});
+	let timeEntries = $derived(entries.filter((entry) => entry.taskId === timeTaskId));
+	let timeRunning = $derived(timer?.taskId === timeTaskId ? { startedAt: timer.startedAt } : null);
+
+	function addEntry(taskId: string, day: string, minutes: number, note?: string) {
+		entries = [{ id: `e${nextEntry++}`, taskId, person: "Dana", day, minutes, note }, ...entries];
+	}
+
+	function onLog(input: TimeLogInput) {
+		addEntry(timeTaskId, input.day, input.minutes, input.note);
+	}
+
+	function onStop(info: TimeStopInfo) {
+		if (timer) addEntry(timer.taskId, info.day, info.minutes);
+		timer = null;
+	}
+
 	const listGrid = "grid grid-cols-[minmax(0,1fr)_7rem_5.5rem_4.5rem] items-center gap-3 max-sm:grid-cols-[minmax(0,1fr)_4.5rem]";
 </script>
 
@@ -124,7 +173,11 @@
 	<div class="flex h-[600px] flex-col gap-3">
 		<div class="flex flex-wrap items-center gap-2">
 			<TaskViewSwitch {views} bind:value={view} label="Task view" />
-			<div class="ml-auto flex items-center gap-2">
+			<div class="ml-auto flex items-center gap-3">
+				<label class="flex cursor-pointer items-center gap-1.5 text-xs font-medium text-muted-foreground">
+					<input type="checkbox" bind:checked={tracking} class="size-3.5 accent-[var(--tone-accent,var(--color-primary))]" />
+					Time tracking
+				</label>
 				{#if view === "gantt"}
 					<TaskViewSwitch
 						views={[
@@ -170,6 +223,9 @@
 								<div class="mt-2.5 flex items-center gap-2 text-xs">
 									{@render avatar(task.assignee)}
 									<span class={d.late ? "font-medium text-destructive" : "text-muted-foreground"}>{d.label}</span>
+									{#if tracking}
+										<TimeChip minutes={minutesByTask[task.id] ?? 0} estimate={estimates[task.id]} running={timer?.taskId === task.id} />
+									{/if}
 									<span class="ml-auto rounded-full px-1.5 py-0.5 font-medium capitalize {priorityClass[task.priority]}">
 										{task.priority}
 									</span>
@@ -206,6 +262,9 @@
 									<span class="truncate" class:text-muted-foreground={task.status === "done"} class:line-through={task.status === "done"}>
 										{task.title}
 									</span>
+									{#if tracking}
+										<TimeChip minutes={minutesByTask[task.id] ?? 0} estimate={estimates[task.id]} running={timer?.taskId === task.id} />
+									{/if}
 								</span>
 								<span class="flex min-w-0 items-center gap-2 text-muted-foreground max-sm:hidden">
 									{@render avatar(task.assignee)}
@@ -259,6 +318,42 @@
 		</p>
 	</div>
 
+	{#if tracking}
+		<section class="flex flex-col gap-3 border-t border-border pt-4">
+			<div class="flex items-center justify-between gap-3">
+				<h3 class="text-xs font-semibold uppercase tracking-wide text-muted-foreground">Task time</h3>
+				<select
+					bind:value={timeTaskId}
+					aria-label="Task"
+					class="h-8 max-w-[60%] rounded-md border border-border bg-background px-2 text-xs text-foreground"
+				>
+					{#each tasks as task (task.id)}
+						<option value={task.id}>{task.title}</option>
+					{/each}
+				</select>
+			</div>
+			<TimeTracker
+				class="mx-auto w-full max-w-xl"
+				entries={timeEntries}
+				getId={(entry) => entry.id}
+				getMinutes={(entry) => entry.minutes}
+				getDay={(entry) => entry.day}
+				getPerson={(entry) => entry.person}
+				getNote={(entry) => entry.note}
+				estimate={estimates[timeTaskId]}
+				running={timeRunning}
+				onStart={() => {
+					timer = { taskId: timeTaskId, startedAt: Date.now() };
+				}}
+				{onStop}
+				{onLog}
+				onDelete={(entry) => {
+					entries = entries.filter((row) => row.id !== entry.id);
+				}}
+			/>
+		</section>
+	{/if}
+
 	<section class="flex flex-col gap-2 border-t border-border pt-4">
 		<h3 class="text-xs font-semibold uppercase tracking-wide text-muted-foreground">Status badges</h3>
 		<div class="flex flex-wrap items-center gap-2">

package/src/icons/board-icon.svelte

@@ -3,7 +3,9 @@
 </script>
 
 <svg width={size} height={size} viewBox="0 0 16 16" fill="none" aria-hidden="true" class={className}>
-	<rect x="2" y="2.5" width="3.5" height="11" rx="1.25" stroke="currentColor" stroke-width="1.5"></rect>
-	<rect x="7" y="2.5" width="3.5" height="7" rx="1.25" stroke="currentColor" stroke-width="1.5"></rect>
-	<rect x="12" y="2.5" width="2" height="9" rx="1" stroke="currentColor" stroke-width="1.5"></rect>
+	<g stroke="currentColor" stroke-width="1.5" stroke-linecap="round">
+		<line x1="4" y1="3" x2="4" y2="11"></line>
+		<line x1="8" y1="3" x2="8" y2="7.5"></line>
+		<line x1="12" y1="3" x2="12" y2="13"></line>
+	</g>
 </svg>

package/src/icons/chevron-down.svg

@@ -0,0 +1 @@
+<svg viewBox="0 0 10 10" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M2 3.5 5 6.5 8 3.5"/></svg>

package/src/icons/clock.svg

@@ -0,0 +1 @@
+<svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="8" cy="8" r="6"/><path d="M8 4.75V8l2.25 1.5"/></svg>

package/src/icons/close.svg

@@ -0,0 +1 @@
+<svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" aria-hidden="true"><path d="m4 4 8 8M12 4l-8 8"/></svg>

package/src/icons/milestone-flag.svg

@@ -0,0 +1 @@
+<svg viewBox="0 0 16 16" aria-hidden="true"><path d="M4 2v12" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" fill="none"/><path d="M4.75 2.75h8l-2 3 2 3h-8z" fill="currentColor"/></svg>

package/src/icons/play.svg

@@ -0,0 +1 @@
+<svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M8 5.6v12.8a1 1 0 0 0 1.5.86l10.6-6.4a1 1 0 0 0 0-1.72L9.5 4.74A1 1 0 0 0 8 5.6Z"/></svg>

package/src/inbox/icons/call.svg

@@ -0,0 +1 @@
+<svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M3.5 2.5h2l1 3-1.5 1a7 7 0 0 0 4 4l1-1.5 3 1v2a1.5 1.5 0 0 1-1.5 1.5A10.5 10.5 0 0 1 2 4a1.5 1.5 0 0 1 1.5-1.5Z"/></svg>

package/src/inbox/icons/email.svg

@@ -0,0 +1 @@
+<svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><rect x="2" y="3.5" width="12" height="9" rx="1.5"/><path d="m2.5 4.5 5.5 4 5.5-4"/></svg>

package/src/inbox/icons/form.svg

@@ -0,0 +1 @@
+<svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="2" width="10" height="12" rx="1.5"/><path d="M5.5 5.5h5M5.5 8h5M5.5 10.5h3"/></svg>

package/src/inbox/icons/slack.svg

@@ -0,0 +1 @@
+<svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M6.5 2.5 5.5 13.5M10.5 2.5l-1 11M3 6h10.5M2.5 10H13"/></svg>