@atelic-action/ui 0.17.2 → 1.0.0

package/src/app/lib/units.ts

@@ -0,0 +1,228 @@
+/**
+ * Unit display for logged measurements.
+ *
+ * The API stores every measurement in one canonical unit (kg, ml, L, g, °C).
+ * The UI converts at the presentation layer so a measure can be read and typed
+ * in either system without the wire format ever changing.
+ *
+ * Two levels:
+ *  - a **scale** is what a single field is stored in (`massKg`, `volumeMl`, …)
+ *  - a **measure** is the preference group a scale belongs to (`bodyMass`,
+ *    `volume`, …). Switching a measure switches every scale under it, so
+ *    weight before and weight after can never disagree.
+ *
+ * Round-trip warning: a value converted out and back does not always land on
+ * itself (84.458 kg reads 186.2 lb, which converts back to 84.46 kg). Callers
+ * must send the untouched canonical value for fields the user did not edit
+ * rather than re-deriving it from the display string.
+ */
+
+export type UnitSystem = "metric" | "imperial";
+
+/** Preference groups. One choice each, persisted in `unitsStore`. */
+export type MeasureId = "bodyMass" | "volume" | "foodMass" | "temperature";
+
+/** A system per measure, as the api stores it on the person and the store keeps it. */
+export type UnitPreferences = Record<MeasureId, UnitSystem>;
+
+/** What a given field is stored in on the API. */
+export type ScaleId = "massKg" | "volumeMl" | "volumeL" | "massG" | "tempC" | "percent" | "count";
+
+export interface UnitDef {
+	/** Shown beside the value and in the dropdown ("kg", "fl oz", "°F"). */
+	label: string;
+	/** Decimal places used when rendering a canonical value in this unit. */
+	decimals: number;
+	/** Canonical value in this unit. */
+	from: (canonical: number) => number;
+	/** This unit back to canonical. */
+	to: (value: number) => number;
+}
+
+interface Scale {
+	/** The preference group, or null when the field has no unit choice. */
+	measure: MeasureId | null;
+	metric: UnitDef;
+	imperial: UnitDef;
+}
+
+const POUNDS_PER_KG = 2.2046226218;
+const FL_OZ_PER_ML = 0.0338140227;
+const OUNCES_PER_GRAM = 0.0352739619;
+
+const identity = (value: number): number => value;
+
+const SCALES: Record<ScaleId, Scale> = {
+	massKg: {
+		measure: "bodyMass",
+		metric: { label: "kg", decimals: 1, from: identity, to: identity },
+		imperial: {
+			label: "lb",
+			decimals: 1,
+			from: (kg) => kg * POUNDS_PER_KG,
+			to: (lb) => lb / POUNDS_PER_KG,
+		},
+	},
+	volumeMl: {
+		measure: "volume",
+		metric: { label: "ml", decimals: 0, from: identity, to: identity },
+		imperial: {
+			label: "fl oz",
+			decimals: 0,
+			from: (ml) => ml * FL_OZ_PER_ML,
+			to: (flOz) => flOz / FL_OZ_PER_ML,
+		},
+	},
+	volumeL: {
+		measure: "volume",
+		metric: { label: "L", decimals: 1, from: identity, to: identity },
+		imperial: {
+			label: "fl oz",
+			decimals: 0,
+			from: (liters) => liters * 1000 * FL_OZ_PER_ML,
+			to: (flOz) => flOz / FL_OZ_PER_ML / 1000,
+		},
+	},
+	massG: {
+		measure: "foodMass",
+		metric: { label: "g", decimals: 0, from: identity, to: identity },
+		imperial: {
+			label: "oz",
+			decimals: 1,
+			from: (grams) => grams * OUNCES_PER_GRAM,
+			to: (oz) => oz / OUNCES_PER_GRAM,
+		},
+	},
+	tempC: {
+		measure: "temperature",
+		metric: { label: "°C", decimals: 1, from: identity, to: identity },
+		imperial: {
+			label: "°F",
+			decimals: 0,
+			from: (celsius) => celsius * 1.8 + 32,
+			to: (fahrenheit) => (fahrenheit - 32) / 1.8,
+		},
+	},
+	percent: {
+		measure: null,
+		metric: { label: "%", decimals: 0, from: identity, to: identity },
+		imperial: { label: "%", decimals: 0, from: identity, to: identity },
+	},
+	count: {
+		measure: null,
+		metric: { label: "", decimals: 0, from: identity, to: identity },
+		imperial: { label: "", decimals: 0, from: identity, to: identity },
+	},
+};
+
+/** The preference group a scale answers to, or null when it has no choice. */
+export function measureOf(scale: ScaleId): MeasureId | null {
+	return SCALES[scale].measure;
+}
+
+/** The unit a scale renders in under the given system. */
+export function unitFor(scale: ScaleId, system: UnitSystem): UnitDef {
+	return SCALES[scale][system];
+}
+
+/** True when the field offers a real choice worth a dropdown. */
+export function hasUnitChoice(scale: ScaleId): boolean {
+	return SCALES[scale].measure !== null;
+}
+
+/** Dropdown options for a scale, metric first. Empty when there is no choice. */
+export function unitOptions(scale: ScaleId): { value: UnitSystem; label: string }[] {
+	if (!hasUnitChoice(scale)) return [];
+	return [
+		{ value: "metric", label: SCALES[scale].metric.label },
+		{ value: "imperial", label: SCALES[scale].imperial.label },
+	];
+}
+
+/** Round to a unit's display precision without trailing-zero padding. */
+function round(value: number, decimals: number): number {
+	const factor = 10 ** decimals;
+	return Math.round(value * factor) / factor;
+}
+
+/**
+ * A canonical value rendered for display, as the string an input holds.
+ * Returns "" for null/undefined/NaN so an empty field stays empty.
+ */
+export function toDisplay(
+	canonical: number | null | undefined,
+	scale: ScaleId,
+	system: UnitSystem,
+): string {
+	if (canonical === null || canonical === undefined || Number.isNaN(canonical)) return "";
+	const unit = unitFor(scale, system);
+	return String(round(unit.from(canonical), unit.decimals));
+}
+
+/**
+ * A typed display string converted back to the canonical unit, or null when
+ * the string does not parse. Canonical values keep two more decimals than the
+ * display so a conversion never throws away what the user typed.
+ */
+export function toCanonical(display: string, scale: ScaleId, system: UnitSystem): number | null {
+	const parsed = parseFloat(display);
+	if (Number.isNaN(parsed)) return null;
+	const unit = unitFor(scale, system);
+	return round(unit.to(parsed), unit.decimals + 2);
+}
+
+/**
+ * Restate a display string from one system in another, preserving what the
+ * user typed as closely as the target precision allows. Used when a unit
+ * dropdown changes while a field holds an unsaved edit.
+ */
+export function convertDisplay(
+	display: string,
+	scale: ScaleId,
+	from: UnitSystem,
+	to: UnitSystem,
+): string {
+	if (from === to) return display;
+	const canonical = toCanonical(display, scale, from);
+	if (canonical === null) return display;
+	return toDisplay(canonical, scale, to);
+}
+
+/** Kilograms to pounds, rounded to two decimals. */
+export function kgToPounds(kg: number): number {
+	return round(kg * POUNDS_PER_KG, 2);
+}
+
+/** Pounds to kilograms, rounded to two decimals. */
+export function poundsToKg(pounds: number): number {
+	return round(pounds / POUNDS_PER_KG, 2);
+}
+
+const CM_PER_INCH = 2.54;
+
+/** Feet and inches to centimeters, rounded to one decimal. */
+export function feetInchesToCm(feet: number, inches: number): number {
+	return round((feet * 12 + inches) * CM_PER_INCH, 1);
+}
+
+/** Centimeters to whole feet and inches; 11.6 inches rolls into the next foot. */
+export function cmToFeetInches(cm: number): { feet: number; inches: number } {
+	const totalInches = cm / CM_PER_INCH;
+	const feet = Math.floor(totalInches / 12);
+	const inches = Math.round(totalInches % 12);
+	if (inches === 12) return { feet: feet + 1, inches: 0 };
+	return { feet, inches };
+}
+
+/** A canonical value plus its unit, e.g. "186.2 lb". Empty string when null. */
+export function formatMeasure(
+	canonical: number | null | undefined,
+	scale: ScaleId,
+	system: UnitSystem,
+): string {
+	const value = toDisplay(canonical, scale, system);
+	if (value === "") return "";
+	const { label } = unitFor(scale, system);
+	const shown = Number(value).toLocaleString();
+	return label === "" ? shown : `${shown} ${label}`;
+}

package/src/app/lib/unwrap.ts

@@ -0,0 +1,48 @@
+/**
+ * Utilities for unwrapping API response envelopes.
+ * The Rails API wraps collections in { data: { collection: T[] }, meta }
+ * and entities in { data: { entity: T }, meta }.
+ */
+
+/**
+ * API response envelope for collection (index) endpoints.
+ */
+export interface ApiCollectionEnvelope<T> {
+	data: { collection: T[] };
+	meta: {
+		currentPage: number;
+		totalPages: number;
+		totalCount: number;
+		perPage: number;
+	};
+}
+
+/**
+ * API response envelope for entity (show/create/update) endpoints.
+ */
+export interface ApiEntityEnvelope<T> {
+	data: { entity: T };
+	meta: Record<string, unknown>;
+}
+
+/**
+ * Extract a collection from the API envelope.
+ * Generic over both item type T and meta type M so envelopes
+ * with extended meta fields (e.g., inSeason) work without manual unwrapping.
+ */
+export function unwrapCollection<T, M>(envelope: {
+	data: { collection: T[] };
+	meta: M;
+}): { data: T[]; meta: M } {
+	return {
+		data: envelope.data.collection,
+		meta: envelope.meta,
+	};
+}
+
+/**
+ * Extract a single entity from the API envelope.
+ */
+export function unwrapEntity<T>(envelope: ApiEntityEnvelope<T>): T {
+	return envelope.data.entity;
+}

package/src/app/lib/utils.ts

@@ -0,0 +1,10 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+/**
+ * Merge Tailwind classes with clsx.
+ * Used by shadcn/ui components.
+ */
+export function cn(...inputs: ClassValue[]) {
+	return twMerge(clsx(inputs));
+}

package/src/app/stores/authStore.ts

@@ -0,0 +1,80 @@
+import { create } from "zustand";
+import { persist } from "zustand/middleware";
+import type { RegisteredUser } from "../types";
+import { appStorage } from "./storage";
+
+export interface AuthState {
+	token: string | null;
+	refreshToken: string | null;
+	expiresAt: number | null;
+	user: RegisteredUser | null;
+	isAuthenticated: boolean;
+	login: (token: string, refreshToken: string, expiresIn: number, user: RegisteredUser) => void;
+	setTokens: (token: string, refreshToken: string, expiresIn: number) => void;
+	logout: () => void;
+	updateUser: (user: RegisteredUser) => void;
+	isTokenExpiringSoon: (bufferMs?: number) => boolean;
+}
+
+/**
+ * Default buffer time before token expiry to trigger proactive refresh (5 minutes).
+ */
+export const DEFAULT_EXPIRY_BUFFER_MS = 5 * 60 * 1000;
+
+/**
+ * Authentication store with localStorage persistence.
+ * Manages JWT token, refresh token, and authenticated user state.
+ *
+ * Persisted as `<storagePrefix>-auth`. The prefix is the app's, so the store
+ * hydrates when the app configures the shell (`AppProvider` or
+ * `configureApp`), not when this module loads.
+ */
+export const useAuthStore = create<AuthState>()(
+	persist(
+		(set, get) => ({
+			token: null,
+			refreshToken: null,
+			expiresAt: null,
+			user: null,
+			isAuthenticated: false,
+
+			login: (token, refreshToken, expiresIn, user) =>
+				set({
+					token,
+					refreshToken,
+					expiresAt: Date.now() + expiresIn * 1000,
+					user,
+					isAuthenticated: true,
+				}),
+
+			setTokens: (token, refreshToken, expiresIn) =>
+				set({
+					token,
+					refreshToken,
+					expiresAt: Date.now() + expiresIn * 1000,
+				}),
+
+			logout: () =>
+				set({
+					token: null,
+					refreshToken: null,
+					expiresAt: null,
+					user: null,
+					isAuthenticated: false,
+				}),
+
+			updateUser: (user) => set({ user }),
+
+			isTokenExpiringSoon: (bufferMs = DEFAULT_EXPIRY_BUFFER_MS) => {
+				const { expiresAt } = get();
+				if (!expiresAt) return true;
+				return Date.now() + bufferMs >= expiresAt;
+			},
+		}),
+		{
+			name: "auth",
+			storage: appStorage,
+			skipHydration: true,
+		},
+	),
+);

package/src/app/stores/storage.ts

@@ -0,0 +1,40 @@
+import { createJSONStorage, type StateStorage } from "zustand/middleware";
+import { peekAppConfig } from "../config";
+
+/**
+ * localStorage under the app's prefix, read when it is used rather than when
+ * the store is created, since the stores live in the package and the prefix is
+ * the app's. Before the app is configured nothing is read or written, and a
+ * browser that refuses storage (a private window, the server) is a no op.
+ */
+const prefixed: StateStorage = {
+	getItem: (name) => {
+		const config = peekAppConfig();
+		if (!config) return null;
+		try {
+			return localStorage.getItem(`${config.storagePrefix}-${name}`);
+		} catch {
+			return null;
+		}
+	},
+	setItem: (name, value) => {
+		const config = peekAppConfig();
+		if (!config) return;
+		try {
+			localStorage.setItem(`${config.storagePrefix}-${name}`, value);
+		} catch {
+			// Storage refused; the state lives in memory for this visit.
+		}
+	},
+	removeItem: (name) => {
+		const config = peekAppConfig();
+		if (!config) return;
+		try {
+			localStorage.removeItem(`${config.storagePrefix}-${name}`);
+		} catch {
+			// Nothing stored to remove.
+		}
+	},
+};
+
+export const appStorage = createJSONStorage(() => prefixed);

package/src/app/stores/unitsStore.ts

@@ -0,0 +1,54 @@
+import { create } from "zustand";
+import { persist } from "zustand/middleware";
+import type { MeasureId, UnitPreferences, UnitSystem } from "../lib/units";
+import { appStorage } from "./storage";
+
+export interface UnitsState {
+	systems: UnitPreferences;
+	setSystem: (measure: MeasureId, system: UnitSystem) => void;
+	/** Take the person's saved choices, as read from the api, over the defaults. */
+	hydrate: (systems: Partial<UnitPreferences> | null | undefined) => void;
+}
+
+/**
+ * Defaults. Body weight and temperature read imperial to match the rest of the
+ * app (miles, feet, the profile's pounds); fuel and hydration stay metric
+ * because bottles, bladders, and gel packets are labelled in ml, L, and g.
+ * Every one of them is one dropdown away from the other system.
+ */
+export const DEFAULT_SYSTEMS: UnitPreferences = {
+	bodyMass: "imperial",
+	volume: "metric",
+	foodMass: "metric",
+	temperature: "imperial",
+};
+
+/**
+ * Which system each measure displays in, persisted to localStorage so the
+ * choice survives a reload, and kept in step with the person's account by
+ * UserContext: their saved choices hydrate the store on sign in, and a change
+ * here is written back. Preference only: the API is always sent canonical
+ * units. Persisted as `<storagePrefix>-units`, hydrated when the app
+ * configures the shell.
+ */
+export const useUnitsStore = create<UnitsState>()(
+	persist(
+		(set) => ({
+			systems: DEFAULT_SYSTEMS,
+			setSystem: (measure, system) =>
+				set((state) => ({ systems: { ...state.systems, [measure]: system } })),
+			hydrate: (systems) => set({ systems: { ...DEFAULT_SYSTEMS, ...(systems ?? {}) } }),
+		}),
+		{
+			name: "units",
+			storage: appStorage,
+			skipHydration: true,
+			// Merge stored values over the defaults so a measure added later
+			// starts on its default instead of arriving undefined.
+			merge: (persisted, current) => {
+				const stored = (persisted as Partial<UnitsState> | undefined)?.systems;
+				return { ...current, systems: { ...DEFAULT_SYSTEMS, ...stored } };
+			},
+		},
+	),
+);

package/src/app/types/index.ts

@@ -0,0 +1,72 @@
+/**
+ * The wire protocol every app on this shell shares with its api (pagination
+ * and the token pair), and the signed in user as the shell reads it. Domain
+ * types are the app's.
+ */
+
+import type { UnitPreferences } from "../lib/units";
+
+/**
+ * The signed in person, as much of them as the shell reads: the name, the
+ * avatar, the username (the segment their public pages live under), and the
+ * unit preferences it keeps in step with the units store. An app's own user
+ * type extends this and registers itself (see `Register`).
+ */
+export interface AppUser {
+	id: string;
+	email: string;
+	firstName: string;
+	lastName: string;
+	username: string | null;
+	avatar: string | null;
+	units?: UnitPreferences;
+}
+
+/**
+ * Where an app names its own user type, once, so every hook and store the
+ * shell exports hands it back typed in full:
+ *
+ * ```ts
+ * declare module "@atelic-action/ui/app" {
+ *   interface Register {
+ *     user: User;
+ *   }
+ * }
+ * ```
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: the app augments it, as TanStack's Register is augmented
+export interface Register {}
+
+/** The app's registered user type, or `AppUser` when none is registered. */
+export type RegisteredUser = Register extends { user: infer U extends AppUser } ? U : AppUser;
+
+export interface PaginatedResponse<T> {
+	data: T[];
+	meta: {
+		currentPage: number;
+		totalPages: number;
+		totalCount: number;
+		perPage: number;
+	};
+}
+
+export interface PaginationLinks {
+	self: string;
+	first: string;
+	prev: string | null;
+	next: string | null;
+	last: string;
+}
+
+export interface TokenResponse {
+	token: string;
+	refreshToken: string;
+	expiresIn: number;
+	user: RegisteredUser;
+}
+
+export interface RefreshResponse {
+	token: string;
+	refreshToken: string;
+	expiresIn: number;
+}

package/src/app/types/query.ts

@@ -0,0 +1,11 @@
+export interface ToastMeta {
+	success?: string | ((data: unknown) => string);
+	successDescription?: string | ((data: unknown) => string);
+	error?: string;
+}
+
+declare module "@tanstack/react-query" {
+	interface Register {
+		mutationMeta: { toast?: ToastMeta };
+	}
+}

package/src/app/ui/accordion.tsx

@@ -0,0 +1,54 @@
+"use client";
+
+import * as AccordionPrimitive from "@radix-ui/react-accordion";
+import { ChevronDown } from "lucide-react";
+import * as React from "react";
+
+import { cn } from "../lib/utils";
+
+const Accordion = AccordionPrimitive.Root;
+
+const AccordionItem = React.forwardRef<
+	React.ElementRef<typeof AccordionPrimitive.Item>,
+	React.ComponentPropsWithoutRef<typeof AccordionPrimitive.Item>
+>(({ className, ...props }, ref) => (
+	<AccordionPrimitive.Item ref={ref} className={cn("border-b", className)} {...props} />
+));
+AccordionItem.displayName = "AccordionItem";
+
+const AccordionTrigger = React.forwardRef<
+	React.ElementRef<typeof AccordionPrimitive.Trigger>,
+	React.ComponentPropsWithoutRef<typeof AccordionPrimitive.Trigger>
+>(({ className, children, ...props }, ref) => (
+	<AccordionPrimitive.Header className="flex">
+		<AccordionPrimitive.Trigger
+			ref={ref}
+			className={cn(
+				"flex flex-1 items-center justify-between py-4 font-medium transition-all hover:underline [&[data-state=open]>svg]:rotate-180",
+				className,
+			)}
+			{...props}
+		>
+			{children}
+			<ChevronDown className="h-4 w-4 shrink-0 transition-transform duration-200" />
+		</AccordionPrimitive.Trigger>
+	</AccordionPrimitive.Header>
+));
+AccordionTrigger.displayName = AccordionPrimitive.Trigger.displayName;
+
+const AccordionContent = React.forwardRef<
+	React.ElementRef<typeof AccordionPrimitive.Content>,
+	React.ComponentPropsWithoutRef<typeof AccordionPrimitive.Content>
+>(({ className, children, ...props }, ref) => (
+	<AccordionPrimitive.Content
+		ref={ref}
+		className="overflow-hidden text-sm transition-all data-[state=closed]:animate-accordion-up data-[state=open]:animate-accordion-down"
+		{...props}
+	>
+		<div className={cn("pb-4 pt-0", className)}>{children}</div>
+	</AccordionPrimitive.Content>
+));
+
+AccordionContent.displayName = AccordionPrimitive.Content.displayName;
+
+export { Accordion, AccordionContent, AccordionItem, AccordionTrigger };