Shared components and patterns

​

Confirmation alert

const { confirm } = useConfirmationAlert();

confirm({
	title: t("exercises.confirmDelete", { name: exercise.name }),
	message: t("exercises.confirmDeleteMessage"),
	confirmLabel: t("exercises.delete"),
	destructive: true,
	onConfirm: () =>
		run(async () => {
			try {
				await toastAction(() => deleteExercise(slug, exercise.id), {
					error: t("exercises.toast.deleteFailed"),
				});
				setItems((list) => list.filter((x) => x.id !== exercise.id));
			} catch {}
		}),
});

• While onConfirm runs, the confirm button shows a spinner, cancel is disabled and the dialog cannot be dismissed.
• When onConfirm resolves, the dialog closes.
• When it throws, the dialog stays open so the user can retry or cancel. The provider swallows the error, so show your own toast inside onConfirm (for example with toastAction).

​

Unsaved changes guard

const { confirmExit, leave, holdExit, releaseExit } = useUnsavedChanges({
	isDirty,
	onSave: async () => {
		const ok = await save();
		return ok; // false keeps the user on the page
	},
	variant: "plan", // or "generic" (default)
});

​

Why a provider

​

Three interception layers

• Prevented events and non primary buttons.
• Clicks with Cmd, Ctrl, Shift or Alt held (new tab or window).
• Anchors with download, or a target other than empty or _self.
• Hash only links.
• Other origins.
• Links to the current pathname and search.

​

The dialog

​

The back button sentinel

1. When the page becomes dirty, it pushes a duplicate history entry tagged __unsavedChangesGuard: true. The tag is spread over Next’s existing history.state, never replacing it.
2. Pressing back pops the sentinel, which leaves the user on the same URL. The handler pushes the sentinel again and opens the dialog with intent back.
3. Confirming a back exit sets a bypass flag and calls history.go(-2): one step for the sentinel, one for the real back.
4. When the page becomes clean, the cleanup removes the sentinel with history.back() under the bypass flag.

​

The returned helpers

if (destination) {
	holdExit();
}
const saved = await persist();
if (!saved) {
	if (destination) {
		releaseExit();
	}
	return;
}
if (destination) {
	leave(destination);
}

​

Pagination

const { pageItems, pagination, isPaginated } = usePagination(filtered);

• DEFAULT_PAGE_SIZE is 25.
• When the list shrinks (a filter, a delete) and the current page no longer exists, it clamps to the last page.
• isPaginated is false when everything fits on one page. Hide the control then.

{isPaginated ? <Pagination {...pagination} /> : null}

​

Sidebar

​

Menu items

​

Behaviour

• Expanded width is md:w-68, collapsed is a 76px rail with icons only. NavTooltip shows labels on the rail.
• On the rail, an item with sub items opens a pill flyout (NavSubmenuLinks).
• Active state uses isNavSubItemActive(pathname, href), a prefix match on the path without query or hash. templateNavState splits training and nutrition by the scope param.
• Below md the nav becomes a top bar with a menu button that opens a Sheet on the start side.
• The nav element carries data-brand-nav, which brandingCss uses to scope the studio’s icon colour.
• The logo comes from the studio branding (logoUrl), scaled by the --brand-logo-scale custom property. The rail shows a compact mark of the studio’s initials.

​

Adding a menu item

1. Add the entry to coachItems in NavBar.tsx.
2. Add app.menu.<key> to en/saas.json and he/saas.json.
3. If the page needs the full width, add its path to onCanvas in AppWrapper. If it is a full height board, add it to containsBoard.

​

Other building blocks

​

Hooks