@aurostack/stacks 0.1.0

package/templates/react-monorepo/files/packages/ui/src/components/ui/progress.tsx

@@ -0,0 +1,33 @@
+import * as React from 'react';
+import { cn } from '../../lib/utils';
+
+type ProgressProps = React.ComponentProps<'div'> & {
+	/** 0-100. Values outside the range are clamped. */
+	value: number;
+	/** Accessible name, e.g. "Upload progress". */
+	label?: string;
+};
+
+/** A determinate progress bar — pair with a percentage or byte count in text. */
+function Progress({ value, label, className, ...props }: ProgressProps) {
+	const percent = Math.min(100, Math.max(0, Math.round(value)));
+	return (
+		<div
+			role="progressbar"
+			aria-valuenow={percent}
+			aria-valuemin={0}
+			aria-valuemax={100}
+			aria-label={label}
+			className={cn('h-2 w-full overflow-hidden rounded-full bg-secondary', className)}
+			{...props}
+		>
+			<div
+				className="h-full rounded-full bg-primary transition-[width] duration-200 ease-out"
+				style={{ width: `${percent}%` }}
+			/>
+		</div>
+	);
+}
+
+export { Progress };
+export type { ProgressProps };

package/templates/react-monorepo/files/packages/ui/src/components/ui/search-input.tsx

@@ -0,0 +1,69 @@
+import * as React from 'react';
+import { Search } from 'lucide-react';
+import { cn } from '../../lib/utils';
+
+/**
+ * `text-base` below `sm` is load-bearing, not a style preference.
+ *
+ * iOS auto-zooms a focused text input whose computed font-size is under 16px,
+ * and it never restores the zoom on blur — so one tap leaves the user zoomed in
+ * for the rest of the session, in the installed PWA too. `text-sm` is 14px.
+ * 14px from `sm` up keeps the intended desktop density, where nothing auto-zooms.
+ *
+ * Never drop the `text-base` half, and never "fix" a zoom by adding
+ * `maximum-scale`/`user-scalable=no` to the viewport — that disables pinch-zoom
+ * and fails WCAG 2.1 SC 1.4.4.
+ */
+const NO_IOS_ZOOM = 'text-base sm:text-sm';
+
+/**
+ * Bare input for a search field. Renders only the input, so callers keep their
+ * own wrapper and icon placement (the market search needs a container ref for its
+ * results dropdown, and the shapes differ — pill vs card).
+ *
+ * Pass shape, padding and tone through `className`.
+ */
+function SearchInput({ className, ...props }: React.ComponentProps<'input'>) {
+	return (
+		<input
+			data-slot="search-input"
+			className={cn(
+				'w-full text-foreground outline-none placeholder:text-mute',
+				'focus-visible:ring-2 focus-visible:ring-ring',
+				NO_IOS_ZOOM,
+				className
+			)}
+			{...props}
+		/>
+	);
+}
+
+/**
+ * The filter row at the top of a combobox dropdown panel: leading icon, a
+ * transparent auto-focused input, and a hairline under both.
+ *
+ * Defaults `aria-label` to the placeholder — a placeholder is not a label.
+ */
+function ComboboxFilter({ className, placeholder, 'aria-label': ariaLabel, ...props }: React.ComponentProps<'input'>) {
+	return (
+		<div className="flex items-center gap-2 border-b border-border px-3 py-2">
+			<Search aria-hidden="true" className="size-4 shrink-0 text-mute" />
+			<input
+				// The panel only exists because the user just opened it to type, so
+				// focus belongs here.
+				autoFocus
+				aria-label={ariaLabel ?? placeholder}
+				placeholder={placeholder}
+				data-slot="combobox-filter"
+				className={cn(
+					'w-full bg-transparent text-foreground outline-none placeholder:text-mute',
+					NO_IOS_ZOOM,
+					className
+				)}
+				{...props}
+			/>
+		</div>
+	);
+}
+
+export { SearchInput, ComboboxFilter };

package/templates/react-monorepo/files/packages/ui/src/components/ui/select.tsx

@@ -0,0 +1,80 @@
+import * as React from 'react';
+import * as SelectPrimitive from '@radix-ui/react-select';
+import { Check, ChevronDown } from 'lucide-react';
+import { cn } from '../../lib/utils';
+
+const Select = SelectPrimitive.Root;
+const SelectGroup = SelectPrimitive.Group;
+const SelectValue = SelectPrimitive.Value;
+
+function SelectTrigger({ className, children, ...props }: React.ComponentProps<typeof SelectPrimitive.Trigger>) {
+	return (
+		<SelectPrimitive.Trigger
+			data-slot="select-trigger"
+			className={cn(
+				'flex h-11 w-full items-center justify-between gap-2 rounded-xl border border-input bg-card px-3.5 py-2 text-sm text-foreground outline-none transition-colors',
+				'data-[placeholder]:text-mute focus-visible:border-foreground focus-visible:ring-2 focus-visible:ring-ring',
+				'disabled:cursor-not-allowed disabled:opacity-50 [&>span]:truncate',
+				className
+			)}
+			{...props}
+		>
+			{children}
+			<SelectPrimitive.Icon asChild>
+				<ChevronDown className="size-4 shrink-0 text-mute" />
+			</SelectPrimitive.Icon>
+		</SelectPrimitive.Trigger>
+	);
+}
+
+function SelectContent({
+	className,
+	children,
+	position = 'popper',
+	...props
+}: React.ComponentProps<typeof SelectPrimitive.Content>) {
+	return (
+		<SelectPrimitive.Portal>
+			<SelectPrimitive.Content
+				data-slot="select-content"
+				position={position}
+				className={cn(
+					'relative z-[70] max-h-[--radix-select-content-available-height] min-w-[8rem] overflow-hidden rounded-2xl border border-border bg-card p-1 text-foreground shadow-[0_12px_32px_rgba(14,15,12,0.18)]',
+					position === 'popper' && 'data-[side=bottom]:translate-y-1 data-[side=top]:-translate-y-1',
+					className
+				)}
+				{...props}
+			>
+				<SelectPrimitive.Viewport
+					className={cn('p-1', position === 'popper' && 'w-full min-w-[var(--radix-select-trigger-width)]')}
+				>
+					{children}
+				</SelectPrimitive.Viewport>
+			</SelectPrimitive.Content>
+		</SelectPrimitive.Portal>
+	);
+}
+
+function SelectItem({ className, children, ...props }: React.ComponentProps<typeof SelectPrimitive.Item>) {
+	return (
+		<SelectPrimitive.Item
+			data-slot="select-item"
+			className={cn(
+				'relative flex w-full cursor-pointer select-none items-center rounded-lg py-2 pl-3 pr-8 text-sm outline-none',
+				'focus:bg-secondary data-[state=checked]:font-semibold',
+				'data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
+				className
+			)}
+			{...props}
+		>
+			<SelectPrimitive.ItemText>{children}</SelectPrimitive.ItemText>
+			<span className="absolute right-2.5 flex size-4 items-center justify-center">
+				<SelectPrimitive.ItemIndicator>
+					<Check className="size-4 text-ink-deep" />
+				</SelectPrimitive.ItemIndicator>
+			</span>
+		</SelectPrimitive.Item>
+	);
+}
+
+export { Select, SelectGroup, SelectValue, SelectTrigger, SelectContent, SelectItem };

package/templates/react-monorepo/files/packages/ui/src/components/ui/skeleton.tsx

@@ -0,0 +1,12 @@
+import * as React from 'react';
+import { cn } from '../../lib/utils';
+
+/**
+ * Placeholder block for loading states. Fill is `foreground/10` so it reads on both
+ * white cards and the muted page background, and adapts to dark mode automatically.
+ */
+function Skeleton({ className, ...props }: React.ComponentProps<'div'>) {
+	return <div aria-hidden="true" className={cn('animate-pulse rounded-md bg-foreground/10', className)} {...props} />;
+}
+
+export { Skeleton };

package/templates/react-monorepo/files/packages/ui/src/components/ui/sonner.tsx

@@ -0,0 +1,23 @@
+import type { ComponentProps } from 'react';
+import { Toaster as SonnerToaster } from 'sonner';
+
+type ToasterProps = ComponentProps<typeof SonnerToaster>;
+
+function Toaster(props: ToasterProps) {
+	return (
+		<SonnerToaster
+			position="top-center"
+			toastOptions={{
+				classNames: {
+					toast: 'rounded-2xl border border-border bg-card text-card-foreground',
+					description: 'text-mute',
+					actionButton: 'bg-primary text-primary-foreground',
+					cancelButton: 'bg-secondary text-secondary-foreground'
+				}
+			}}
+			{...props}
+		/>
+	);
+}
+
+export { Toaster };

package/templates/react-monorepo/files/packages/ui/src/components/ui/spinner.tsx

@@ -0,0 +1,8 @@
+import { LoaderCircle } from 'lucide-react';
+import { cn } from '../../lib/utils';
+
+function Spinner({ className }: { className?: string }) {
+	return <LoaderCircle className={cn('size-4 animate-spin', className)} aria-hidden="true" />;
+}
+
+export { Spinner };

package/templates/react-monorepo/files/packages/ui/src/components/ui/textarea.tsx

@@ -0,0 +1,22 @@
+import * as React from 'react';
+import { cn } from '../../lib/utils';
+
+/** Multiline text input, styled to match Input. */
+function Textarea({ className, ...props }: React.ComponentProps<'textarea'>) {
+	return (
+		<textarea
+			data-slot="textarea"
+			className={cn(
+				'flex min-h-20 w-full min-w-0 rounded-xl border border-input bg-card px-3.5 py-2.5 text-base text-foreground transition-colors',
+				'placeholder:text-mute selection:bg-primary selection:text-primary-foreground',
+				'outline-none focus-visible:border-foreground focus-visible:ring-2 focus-visible:ring-ring',
+				'aria-invalid:border-negative aria-invalid:focus-visible:ring-negative/30',
+				'disabled:cursor-not-allowed disabled:opacity-50',
+				className
+			)}
+			{...props}
+		/>
+	);
+}
+
+export { Textarea };

package/templates/react-monorepo/files/packages/ui/src/index.ts

@@ -0,0 +1,45 @@
+// @acme/ui — shared shadcn/ui components (Wise design system), theme, and primitives.
+export * from './lib/utils';
+export * from './lib/zod-setup';
+
+// Primitives
+export * from './components/ui/button';
+export * from './components/ui/input';
+export * from './components/ui/search-input';
+export * from './components/ui/label';
+export * from './components/ui/card';
+export * from './components/ui/alert';
+export * from './components/ui/checkbox';
+export * from './components/ui/select';
+export * from './components/ui/modal';
+export * from './components/ui/textarea';
+export * from './components/ui/popover';
+// Calendar is intentionally NOT re-exported here — it pulls in react-day-picker, and
+// DatePicker lazy-loads it so it stays out of the main bundle.
+export * from './components/ui/date-picker';
+export * from './components/ui/progress';
+export * from './components/ui/skeleton';
+export * from './components/ui/spinner';
+export * from './components/ui/sonner';
+
+// Form primitives (Formik + Zod)
+export * from './components/form/form';
+
+// Theme (light/dark/system) — shared by every app
+export { ThemeProvider } from './theme/theme-provider';
+export { ThemeToggle } from './theme/theme-toggle';
+export { useTheme } from './theme/use-theme';
+export { themeInitScript } from './theme/init-script';
+export { THEME_STORAGE_KEY, THEME_COLORS } from './theme/theme-context';
+export type { ThemeMode, ResolvedTheme } from './theme/theme-context';
+
+// Document metadata (per-route titles, description, robots, canonical)
+export { PageMeta } from './meta/page-meta';
+export type { PageMetaProps } from './meta/page-meta';
+export { MetaProvider } from './meta/meta-provider';
+export { useMetaConfig } from './meta/use-meta-config';
+export type { MetaConfig } from './meta/meta-context';
+
+// Brand
+export * from './components/brand/logo';
+export * from './components/brand/social-icons';

package/templates/react-monorepo/files/packages/ui/src/lib/utils.ts

@@ -0,0 +1,7 @@
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+/** Merge Tailwind class names, de-duplicating conflicts. */
+export function cn(...inputs: ClassValue[]): string {
+	return twMerge(clsx(inputs));
+}

package/templates/react-monorepo/files/packages/ui/src/lib/zod-setup.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+
+/**
+ * Install once per app at bootstrap. Friendly defaults for missing/empty
+ * required fields; explicit per-field messages (.email(), .min(1, '...'),
+ * .positive('...'), etc.) always take precedence over these.
+ */
+export function installZodErrorMap() {
+	z.config({
+		customError: (issue) => {
+			if (issue.code === 'invalid_type' && (issue.input === undefined || issue.input === null)) {
+				return 'This field is required';
+			}
+			if (
+				issue.code === 'invalid_type' &&
+				issue.expected === 'number' &&
+				typeof issue.input === 'number' &&
+				Number.isNaN(issue.input)
+			) {
+				return 'This field is required';
+			}
+			if (issue.code === 'too_small' && issue.origin === 'string' && issue.minimum === 1) {
+				return 'This field is required';
+			}
+			return undefined;
+		}
+	});
+}

package/templates/react-monorepo/files/packages/ui/src/meta/brand.ts

@@ -0,0 +1,18 @@
+/**
+ * Product name, in one place.
+ *
+ * Consumed twice over, which is the whole reason it lives here:
+ *  - at runtime by `MetaProvider`, as the per-route title suffix;
+ *  - at build time by each app's `vite.config.ts`, which passes it to
+ *    `defineAppConfig({ appTitle })` to substitute `%APP_TITLE%` into
+ *    `index.html` — HTML cannot import, and the static `<title>` is what a
+ *    visitor sees before React mounts.
+ *
+ * Keep this file free of React imports: `vite.config.ts` imports it directly
+ * via the `@acme/ui/brand` subpath, exactly as it does `./theme-colors`.
+ */
+export const BRAND = {
+	name: 'Acme Corp',
+	/** The console needs its own suffix so an admin can tell two tabs apart. */
+	adminName: 'Acme Corp Admin'
+} as const;

package/templates/react-monorepo/files/packages/ui/src/meta/meta-context.ts

@@ -0,0 +1,30 @@
+import { createContext } from 'react';
+import { BRAND } from './brand';
+
+/**
+ * Per-app title suffix, declared once by `MetaProvider` so routes supply only
+ * their own segment. Admin uses a different brand string, which is exactly why
+ * this is context and not a constant.
+ */
+export type MetaConfig = {
+	/** Appended after a separator, e.g. `Acme Corp`. */
+	suffix: string;
+	/** Separator between the page segment and the suffix. */
+	separator: string;
+};
+
+export const DEFAULT_META: MetaConfig = {
+	suffix: BRAND.name,
+	separator: ' · '
+};
+
+export const MetaContext = createContext<MetaConfig>(DEFAULT_META);
+
+/** `About` + `Acme Corp` -> `About · Acme Corp`. */
+export function formatTitle(segment: string, config: MetaConfig): string {
+	const trimmed = segment.trim();
+	if (!trimmed) return config.suffix;
+	// Don't double up when a segment already carries the brand.
+	if (trimmed === config.suffix) return trimmed;
+	return `${trimmed}${config.separator}${config.suffix}`;
+}

package/templates/react-monorepo/files/packages/ui/src/meta/meta-provider.tsx

@@ -0,0 +1,24 @@
+import { useMemo, type ReactNode } from 'react';
+import { DEFAULT_META, MetaContext, type MetaConfig } from './meta-context';
+
+/**
+ * Declares the app's title template once, so routes supply only their own
+ * segment. Wrap the app root, above the router.
+ *
+ * ```tsx
+ * <MetaProvider suffix="Acme Corp Admin">
+ * ```
+ */
+export function MetaProvider({
+	children,
+	suffix = DEFAULT_META.suffix,
+	separator = DEFAULT_META.separator
+}: {
+	children: ReactNode;
+	suffix?: string;
+	separator?: string;
+}) {
+	const value = useMemo<MetaConfig>(() => ({ suffix, separator }), [suffix, separator]);
+
+	return <MetaContext.Provider value={value}>{children}</MetaContext.Provider>;
+}

package/templates/react-monorepo/files/packages/ui/src/meta/page-meta.tsx

@@ -0,0 +1,69 @@
+import { formatTitle } from './meta-context';
+import { useMetaConfig } from './use-meta-config';
+
+export type PageMetaProps = {
+	/**
+	 * Page segment, not the whole title — the app's suffix is appended by
+	 * `MetaProvider`. Pass `exact` to opt out.
+	 */
+	title?: string;
+	/** Use `title` verbatim, without the app suffix. */
+	exact?: boolean;
+	/** Overrides the base description from `index.html` while mounted. */
+	description?: string;
+	/** e.g. `noindex, nofollow` for the private apps. */
+	robots?: string;
+	/** Absolute URL. */
+	canonical?: string;
+};
+
+/**
+ * Per-route document metadata. Render it anywhere inside a route — React 19
+ * hoists `<title>`, `<meta>` and `<link>` into `<head>` natively, so there is no
+ * head-management dependency and no effect involved.
+ *
+ * **Being effect-free is the point**: it is what makes the tags appear in
+ * server-rendered output, which an effect-based `document.title` hook can never
+ * do. Do not "optimise" this into a `useEffect`.
+ *
+ * Omit a field to inherit it: a route with no `description` keeps the base one
+ * from `index.html`, and React removes the tag again on unmount.
+ *
+ * ## Nesting
+ *
+ * Client-side, the innermost render wins for free — React claims the first
+ * existing `<title>` (so the static one from `index.html` is overwritten), and
+ * for any subsequent one it does `head.insertBefore(new, existing)`. Later
+ * renders therefore land *earlier* in `<head>`, and `document.title` is defined
+ * as the first `<title>` in tree order.
+ *
+ * ## Server-side rendering — read before wiring a prerender
+ *
+ * Order inverts on the server. `react-dom/server` emits tags in render order,
+ * so a document renders as:
+ *
+ * ```html
+ * <head><title>base from index.html</title><title>Route · Brand</title></head>
+ * ```
+ *
+ * and the **base** title wins, because it comes first. React does not
+ * deduplicate `<title>` or `<meta>` (only stylesheets get resource dedupe), so
+ * a prerender step MUST post-process the emitted HTML: keep the **last**
+ * `<title>` and the **last** `<meta name="description">`, dropping earlier
+ * duplicates. Without that, every prerendered page ships the base title and
+ * hydration silently corrects it — invisible in a browser, wrong for crawlers.
+ * Tracked on MAI-88.
+ */
+export function PageMeta({ title, exact, description, robots, canonical }: PageMetaProps) {
+	const config = useMetaConfig();
+	const resolved = title === undefined ? undefined : exact ? title : formatTitle(title, config);
+
+	return (
+		<>
+			{resolved === undefined ? null : <title>{resolved}</title>}
+			{description === undefined ? null : <meta name="description" content={description} />}
+			{robots === undefined ? null : <meta name="robots" content={robots} />}
+			{canonical === undefined ? null : <link rel="canonical" href={canonical} />}
+		</>
+	);
+}

package/templates/react-monorepo/files/packages/ui/src/meta/use-meta-config.ts

@@ -0,0 +1,11 @@
+import { useContext } from 'react';
+import { MetaContext } from './meta-context';
+
+/**
+ * The app's title template. Falls back to the un-suffixed default rather than
+ * throwing, so a component rendering `PageMeta` outside a `MetaProvider` still
+ * produces a usable title instead of blanking the tab.
+ */
+export function useMetaConfig() {
+	return useContext(MetaContext);
+}