@heyramzi/ui 2.24.0 → 3.1.0

package/src/work/kanban-board.svelte.test.ts

@@ -0,0 +1,89 @@
+import { createRawSnippet, flushSync, mount, tick, unmount } from "svelte";
+import { describe, expect, it } from "vite-plus/test";
+import KanbanBoard from "./kanban-board.svelte";
+import type { KanbanMove } from "./kanban-types.js";
+
+type Task = { id: string; columnId: string; title: string; boardOrder: string };
+
+const columns = [
+  { id: "todo", label: "To do" },
+  { id: "doing", label: "In progress" },
+  { id: "done", label: "Done" },
+];
+
+const renderCard = createRawSnippet((task: () => Task) => ({
+  render: () => `<p>${task().title}</p>`,
+}));
+
+function render() {
+  const props = $state({
+    columns,
+    items: [
+      { id: "k1", columnId: "todo", title: "Draft notes", boardOrder: "a0" },
+      { id: "k2", columnId: "doing", title: "Ship flow", boardOrder: "a0" },
+    ] as Task[],
+    getId: (t: Task) => t.id,
+    getColumn: (t: Task) => t.columnId,
+    boardOrder: (t: Task) => t.boardOrder,
+    renderCard,
+    onMove: (id: string, move: KanbanMove) => {
+      props.items = props.items.map((t) =>
+        t.id === id ? { ...t, columnId: move.columnId, boardOrder: move.boardOrder ?? "" } : t,
+      );
+    },
+  });
+  const target = document.createElement("div");
+  document.body.appendChild(target);
+  const app = mount(KanbanBoard<Task>, { target, props });
+  flushSync();
+  return {
+    target,
+    card: (id: string) => target.querySelector<HTMLElement>(`[data-kanban-card="${id}"]`),
+    done: () => {
+      void unmount(app);
+      target.remove();
+    },
+  };
+}
+
+// Waits out the board's await of onMove and its tick, then Svelte's flush.
+async function settle() {
+  for (let i = 0; i < 4; i++) await tick();
+  flushSync();
+}
+
+describe("KanbanBoard keyboard move", () => {
+  it("keeps focus on the moved card in its new column and announces the move", async () => {
+    const { target, card, done } = render();
+    const before = card("k1");
+    before?.focus();
+    before?.dispatchEvent(
+      new KeyboardEvent("keydown", { key: "ArrowRight", altKey: true, bubbles: true }),
+    );
+    await settle();
+
+    const moved = card("k1");
+    expect(moved?.closest('[aria-label="In progress"]')).not.toBeNull();
+    expect(document.activeElement).toBe(moved);
+    expect(target.querySelector('[role="status"]')?.textContent).toBe("Moved to In progress");
+    done();
+  });
+
+  it("names a card by its own text and describes it with the move hint", () => {
+    const { card, done } = render();
+    const el = card("k1");
+    expect(el?.hasAttribute("aria-label")).toBe(false);
+    expect(el?.getAttribute("aria-labelledby")).toBe(el?.id);
+    const hint = document.getElementById(el?.getAttribute("aria-describedby") ?? "");
+    expect(hint?.textContent).toBe("Press Alt plus Left or Right arrow to move between columns.");
+    done();
+  });
+
+  it("puts every card inside a list", () => {
+    const { target, done } = render();
+    for (const item of target.querySelectorAll('[role="listitem"]')) {
+      expect(item.parentElement?.getAttribute("role")).toBe("list");
+    }
+    done();
+  });
+});

package/src/work/kanban-column-head.svelte.d.ts

@@ -0,0 +1,40 @@
+import type { Snippet } from "svelte";
+import type { KanbanColumn as KanbanColumnDef, KanbanColumnContext } from "./kanban-types.js";
+declare function $$render<C extends KanbanColumnDef>(): {
+    props: {
+        column: C;
+        context: KanbanColumnContext;
+        /** The board's `columnHeader`. Left out, the head is GroupHead. */
+        columnHeader?: Snippet<[C, KanbanColumnContext]>;
+        onAdd?: (columnId: string) => void;
+        addLabel: string;
+        /** The column holds more cards than its cap, so the caret shows. */
+        foldable: boolean;
+        /** The caret has the column open in every lane. */
+        columnOpen: boolean;
+        onToggle: () => void;
+        expandColumnLabel: string;
+        collapseColumnLabel: string;
+    };
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<C extends KanbanColumnDef> {
+    props(): ReturnType<typeof $$render<C>>['props'];
+    events(): ReturnType<typeof $$render<C>>['events'];
+    slots(): ReturnType<typeof $$render<C>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <C extends KanbanColumnDef>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<C>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<C>['props']>, ReturnType<__sveltets_Render<C>['events']>, ReturnType<__sveltets_Render<C>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<C>['bindings']>;
+    } & ReturnType<__sveltets_Render<C>['exports']>;
+    <C extends KanbanColumnDef>(internal: unknown, props: ReturnType<__sveltets_Render<C>['props']> & {}): ReturnType<__sveltets_Render<C>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const $$Component: $$IsomorphicComponent;
+type $$Component<C extends KanbanColumnDef> = InstanceType<typeof $$Component<C>>;
+export default $$Component;

package/src/work/kanban-column.svelte

@@ -65,40 +65,57 @@
 </div>
 
 <style>
-	/* Columns split the board's width equally, never under 240px (the board scrolls instead)
-	   nor over 420px (a 2-line card title stays near 55 characters a line). At 280px four
-	   columns needed 1168px, so a docs page at 1440 cut the Done column off; 240px fits four
-	   in the 1008px a 1440 page leaves, and a card's meta row still fits on one line. */
-	.kanban-column {
-		flex: 1 1 0;
-		min-width: var(--kanban-column-min, 240px);
-		max-width: var(--kanban-column-max, 420px);
-		transition: opacity var(--duration-quick) var(--ease-smooth-out);
-	}
+	@layer theme, base, components, utilities;
 
-	/* A board under 40rem wide (a phone, a side panel) shows one column and a peek of the next, as 82vw did on a phone. */
-	@container kanban-board (width < 40rem) {
+	@layer components {
+		/* Equal columns, 240px to 420px (the board scrolls below that): four fit the 1008px a
+		   1440 page leaves, and a 2-line title stays near 55 characters a line. */
 		.kanban-column {
-			flex: 0 0 88cqw;
-			min-width: 0;
-			max-width: 88cqw;
-			scroll-snap-align: start;
+			flex: 1 1 0;
+			min-width: var(--kanban-column-min, 240px);
+			max-width: var(--kanban-column-max, 420px);
+			transition: opacity var(--duration-quick) var(--ease-smooth-out);
 		}
-	}
 
-	.kanban-column-collapsing,
-	.kanban-column-expanding {
-		will-change: opacity;
-		overflow: hidden;
-	}
+		/* A board under 40rem wide (a phone, a side panel) shows one column and a peek of the next, as 82vw did on a phone. */
+		@container kanban-board (width < 40rem) {
+			.kanban-column {
+				flex: 0 0 88cqw;
+				min-width: 0;
+				max-width: 88cqw;
+				scroll-snap-align: start;
+			}
+		}
 
-	.kanban-column-collapsing {
-		pointer-events: none;
-		animation: column-fold var(--duration-slow) var(--ease-smooth-out) forwards;
-	}
+		.kanban-column-collapsing,
+		.kanban-column-expanding {
+			will-change: opacity;
+			overflow: hidden;
+		}
+
+		.kanban-column-collapsing {
+			pointer-events: none;
+			animation: column-fold var(--duration-slow) var(--ease-smooth-out) forwards;
+		}
+
+		.kanban-column-expanding {
+			animation: column-unfold var(--duration-slow) var(--ease-smooth-out) both;
+		}
 
-	.kanban-column-expanding {
-		animation: column-unfold var(--duration-slow) var(--ease-smooth-out) both;
+		@media (prefers-reduced-motion: reduce) {
+			.kanban-column-expanding {
+				animation: none;
+			}
+
+			.kanban-column-collapsing {
+				animation: none;
+				opacity: 0;
+				flex: 0 0 0;
+				min-width: 0;
+				max-width: 0;
+				margin-inline-end: -1rem;
+			}
+		}
 	}
 
 	/* One end only: the other is the column's resting width, whatever the container gave it.
@@ -124,19 +141,4 @@
 			margin-inline-end: -1rem;
 		}
 	}
-
-	@media (prefers-reduced-motion: reduce) {
-		.kanban-column-expanding {
-			animation: none;
-		}
-
-		.kanban-column-collapsing {
-			animation: none;
-			opacity: 0;
-			flex: 0 0 0;
-			min-width: 0;
-			max-width: 0;
-			margin-inline-end: -1rem;
-		}
-	}
 </style>

package/src/work/kanban-column.svelte.d.ts

@@ -0,0 +1,20 @@
+import type { Snippet } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
+interface Props extends HTMLAttributes<HTMLDivElement> {
+    /** Any CSS color. Only shows while a card is held over the column. */
+    hue?: string;
+    active?: boolean;
+    collapsing?: boolean;
+    expanding?: boolean;
+    ariaLabel?: string;
+    header: Snippet;
+    children: Snippet;
+    ondragover?: (e: DragEvent) => void;
+    ondragleave?: (e: DragEvent) => void;
+    ondrop?: (e: DragEvent) => void;
+    class?: string;
+    bodyClass?: string;
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/work/kanban-fold-chevron.svelte

@@ -13,22 +13,26 @@
 
 <span
 	class={cn("kanban-fold-chevron [&>svg]:size-full", open && "kanban-fold-chevron-open", className)}
-	aria-hidden="true"><CaretDown weight="bold" /></span
+	aria-hidden="true"><CaretDown aria-hidden="true" weight="bold" /></span
 >
 
 <style>
-	.kanban-fold-chevron {
-		display: inline-flex;
-		transition: transform var(--duration-fast) var(--ease-smooth-out);
-	}
-
-	.kanban-fold-chevron-open {
-		transform: scaleY(-1);
-	}
+	@layer theme, base, components, utilities;
 
-	@media (prefers-reduced-motion: reduce) {
+	@layer components {
 		.kanban-fold-chevron {
-			transition: none;
+			display: inline-flex;
+			transition: transform var(--duration-fast) var(--ease-smooth-out);
+		}
+
+		.kanban-fold-chevron-open {
+			transform: scaleY(-1);
+		}
+
+		@media (prefers-reduced-motion: reduce) {
+			.kanban-fold-chevron {
+				transition: none;
+			}
 		}
 	}
 </style>

package/src/work/kanban-fold-chevron.svelte.d.ts

@@ -0,0 +1,8 @@
+interface Props {
+    /** Flips the caret to point up. */
+    open: boolean;
+    class?: string;
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/work/kanban-hidden-rail.svelte

@@ -34,7 +34,7 @@
 				"size-2.5 transition-transform duration-fast ease-smooth-out motion-reduce:transition-none [&>svg]:size-full",
 				!rail.railOpen && "-rotate-90",
 			)}
-			aria-hidden="true"><CaretDown weight="bold" /></span
+			aria-hidden="true"><CaretDown aria-hidden="true" weight="bold" /></span
 		>
 		{hiddenLabel}
 	</Button>
@@ -96,6 +96,7 @@
 </div>
 
 <style>
+	/* Unlayered: the row's transition-[background-color,outline-color] utility would otherwise drop the fade out. */
 	.kanban-rail-item-leaving {
 		pointer-events: none;
 		opacity: 0;

package/src/work/kanban-hidden-rail.svelte.d.ts

@@ -0,0 +1,39 @@
+import type { Snippet } from "svelte";
+import type { KanbanRailState } from "./kanban-rail-state.svelte.js";
+import type { KanbanColumn as KanbanColumnDef } from "./kanban-types.js";
+declare function $$render<C extends KanbanColumnDef>(): {
+    props: {
+        /** The columns folded into the rail, in board order. */
+        columns: C[];
+        rail: KanbanRailState;
+        /** How many cards a column holds. */
+        countOf: (columnId: string) => number;
+        hiddenLabel: string;
+        showAllLabel: string;
+        hiddenItem?: Snippet<[C, {
+            count: number;
+            active: boolean;
+        }]>;
+    };
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<C extends KanbanColumnDef> {
+    props(): ReturnType<typeof $$render<C>>['props'];
+    events(): ReturnType<typeof $$render<C>>['events'];
+    slots(): ReturnType<typeof $$render<C>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <C extends KanbanColumnDef>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<C>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<C>['props']>, ReturnType<__sveltets_Render<C>['events']>, ReturnType<__sveltets_Render<C>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<C>['bindings']>;
+    } & ReturnType<__sveltets_Render<C>['exports']>;
+    <C extends KanbanColumnDef>(internal: unknown, props: ReturnType<__sveltets_Render<C>['props']> & {}): ReturnType<__sveltets_Render<C>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const $$Component: $$IsomorphicComponent;
+type $$Component<C extends KanbanColumnDef> = InstanceType<typeof $$Component<C>>;
+export default $$Component;

package/src/work/kanban-keyboard.ts

@@ -11,6 +11,9 @@ export type KanbanKeyboardConfig<T, C extends KanbanColumnDef> = {
   moveAndPin: (id: string, move: KanbanMove) => void | Promise<void>;
 };
 
+/** A keyboard move: the column the card went to, and the caller's `onMove` result. */
+export type KanbanKeyboardMove<C> = { column: C; done: void | Promise<void> };
+
 /** The card's keydown handler: Enter or Space selects, Alt + arrow moves. */
 export function createCardKeyDown<T, C extends KanbanColumnDef>(
   config: KanbanKeyboardConfig<T, C>,
@@ -19,9 +22,9 @@ export function createCardKeyDown<T, C extends KanbanColumnDef>(
 
   /**
    * Alt + ArrowLeft/Right moves the focused card to the next droppable column, so
-   * keyboard and screen-reader users get drag's onMove contract.
+   * keyboard and screen-reader users get drag's onMove contract. Returns the move, if one ran.
    */
-  return function onCardKeyDown(e: KeyboardEvent, id: string): void {
+  return function onCardKeyDown(e: KeyboardEvent, id: string): KanbanKeyboardMove<C> | undefined {
     const { onSelect, items, getId, getColumn, columns, sortKey, dropAtTop, boardOrder } = input();
     if (onSelect && e.target === e.currentTarget && (e.key === "Enter" || e.key === " ")) {
       e.preventDefault();
@@ -45,7 +48,7 @@ export function createCardKeyDown<T, C extends KanbanColumnDef>(
         const index = atTop ? 0 : column.length;
         const before = column[index - 1];
         const after = column[index];
-        void moveAndPin(id, {
+        const done = moveAndPin(id, {
           columnId: target.id,
           ...(boardOrder
             ? { boardOrder: boardOrderAt(column, index, (entry) => boardOrder(entry)) }
@@ -53,10 +56,9 @@ export function createCardKeyDown<T, C extends KanbanColumnDef>(
           beforeId: before === undefined ? null : getId(before),
           afterId: after === undefined ? null : getId(after),
         });
-      } else {
-        void moveAndPin(id, { columnId: target.id });
+        return { column: target, done };
       }
-      return;
+      return { column: target, done: moveAndPin(id, { columnId: target.id }) };
     }
   };
 }

package/src/work/task-gantt.svelte

@@ -2,6 +2,8 @@
 	import { workLooks } from "../components/work-parts/looks.js";
 	import type { Snippet } from "svelte";
 	import { cn } from "../lib/utils.js";
+	import LiveRegion from "../lib/live-region.svelte";
+	import { focusAfterRender } from "../lib/focus.js";
 	import { dayNumber, isoFromDay, todayIso } from "./dates.js";
 	import GanttGrid from "./gantt/gantt-grid.svelte";
 	import GanttGroupRow from "./gantt/gantt-group-row.svelte";
@@ -54,9 +56,11 @@
 		groups?: KanbanColumnDef[];
 		getGroup?: (item: T) => string;
 		/** Called after a bar is dragged, resized or nudged. Leave it out for a read-only chart. */
-		onChange?: (id: string, change: GanttChange) => void | Promise<void>;
+		onDatesChange?: (id: string, change: GanttChange) => void | Promise<void>;
 		/** Called on a click or Enter that did not move the bar. */
 		onSelect?: (id: string) => void;
+		/** What a screen reader hears after an arrow key moves a bar, given its new dates. */
+		movedLabel?: (dates: string) => string;
 		/** The left column for a row. Defaults to the title. */
 		renderLabel?: Snippet<[T, GanttLabelContext]>;
 		/** First and last day shown. Default: the tasks' span, padded, starting on a Monday. */
@@ -90,8 +94,9 @@
 		getDependsOn,
 		groups,
 		getGroup,
-		onChange,
+		onDatesChange,
 		onSelect,
+		movedLabel = (dates) => `Now ${dates}`,
 		renderLabel,
 		from,
 		to,
@@ -115,6 +120,7 @@
 	let corner = $state<HTMLDivElement>();
 	let drag = $state<Drag | null>(null);
 	let hoveredId = $state<string | null>(null);
+	let live: LiveRegion | undefined = $state();
 	let scrolledToToday = false;
 	// svelte-ignore state_referenced_locally
 	let folded = $state(new Set(collapsed));
@@ -171,6 +177,12 @@
 		return rangeLabel(span, dayFormat);
 	}
 
+	// A chart sorted by date can reorder the moved bar, and a moved node loses focus.
+	async function onKeyMove(id: string, span: Span): Promise<void> {
+		void live?.announce(movedLabel(describe(span)));
+		await focusAfterRender(scroller, `[data-bar="${CSS.escape(id)}"]`);
+	}
+
 	// Open on today, a third of the way in, so past work and what's next both show.
 	$effect(() => {
 		if (!scroller || scrolledToToday) return;
@@ -236,10 +248,11 @@
 							tipBelow={row.order === 0 && !groups}
 							{drag}
 							setDrag={(next) => (drag = next)}
-							onhover={hover}
+							onHover={hover}
 							onToggle={toggle}
-							{onChange}
+							{onDatesChange}
 							{onSelect}
+							onKeyMove={(id, span) => void onKeyMove(id, span)}
 							{renderLabel}
 							{describe}
 						/>
@@ -248,4 +261,5 @@
 			</div>
 		</div>
 	</div>
+	<LiveRegion bind:this={live} />
 </div>

package/src/work/task-gantt.svelte.d.ts

@@ -0,0 +1,85 @@
+import type { Snippet } from "svelte";
+import type { KanbanColumn as KanbanColumnDef } from "./kanban-types.js";
+import type { GanttChange, GanttLabelContext } from "./task-types.js";
+interface Props<T> {
+    items: T[];
+    getId: (item: T) => string;
+    getTitle: (item: T) => string;
+    /**
+     * ISO date, inclusive. Null or empty means undated: with an end date alone the task
+     * starts the same day, and with neither it has no bar of its own.
+     */
+    getStart: (item: T) => string | null | undefined;
+    /** ISO date, inclusive. See `getStart`. */
+    getEnd: (item: T) => string | null | undefined;
+    /**
+     * The parent task's id; a parent with no dates of its own draws the span of the
+     * children nested under it.
+     */
+    getParent?: (item: T) => string | null | undefined;
+    /** Draws a flag at the end date instead of a bar. Milestones are not draggable. */
+    isMilestone?: (item: T) => boolean;
+    /** Parent ids that start folded. */
+    collapsed?: string[];
+    /** Shown in place of a bar for an undated task. */
+    noDatesLabel?: string;
+    /** Any CSS color for the bar. Falls back to the group hue, then the primary color. */
+    getHue?: (item: T) => string | undefined;
+    /** 0 to 1. Fills the bar from the left. */
+    getProgress?: (item: T) => number | undefined;
+    /** Ids this task waits on. Draws an arrow from each one's end to this one's start. */
+    getDependsOn?: (item: T) => string[] | undefined;
+    /** Group rows under a header, in the order given. Same shape as board columns. */
+    groups?: KanbanColumnDef[];
+    getGroup?: (item: T) => string;
+    /** Called after a bar is dragged, resized or nudged. Leave it out for a read-only chart. */
+    onDatesChange?: (id: string, change: GanttChange) => void | Promise<void>;
+    /** Called on a click or Enter that did not move the bar. */
+    onSelect?: (id: string) => void;
+    /** What a screen reader hears after an arrow key moves a bar, given its new dates. */
+    movedLabel?: (dates: string) => string;
+    /** The left column for a row. Defaults to the title. */
+    renderLabel?: Snippet<[T, GanttLabelContext]>;
+    /** First and last day shown. Default: the tasks' span, padded, starting on a Monday. */
+    from?: string;
+    to?: string;
+    /** The day the today line marks. Defaults to the viewer's today. */
+    today?: string;
+    dayWidth?: number;
+    rowHeight?: number;
+    /** Width of the task column in px. It never takes more than 40% of a narrow screen. */
+    labelWidth?: number;
+    labelHeading?: string;
+    locale?: string;
+    /** Drops the card chrome (border, radius, fill) so the chart sits flat on the page. */
+    flat?: boolean;
+    class?: string;
+}
+declare function $$render<T>(): {
+    props: Props<T>;
+    exports: {
+        scrollToToday: () => void;
+    };
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "";
+    exports(): {
+        scrollToToday: () => void;
+    };
+}
+interface $$IsomorphicComponent {
+    new <T>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const $$Component: $$IsomorphicComponent;
+type $$Component<T> = InstanceType<typeof $$Component<T>>;
+export default $$Component;