@orochibraru/ui 0.0.0-stage → 0.0.0

package/README.md

@@ -1,3 +1,147 @@
-# Temporary Holding Version
+# @orochibraru/ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Svelte 5 components and the theme shared by OpenCount, LocalAssistant, Homerun,
+Sergio's, Nuvio Web and Penombre: the shadcn-svelte primitives (vega style) as
+these apps customised them, a handful of app-level blocks, and the oklch theme
+they all draw from. One package instead of six drifting copies.
+
+Built for SvelteKit 3, Svelte 5 runes and Tailwind CSS v4.
+
+## Install
+
+```bash
+bun add -d @orochibraru/ui
+```
+
+It goes in `devDependencies`: the app bundles it, so nothing from it is needed
+at runtime next to the compiled server.
+
+## Set up the stylesheet
+
+Import the theme right after Tailwind in the app's root stylesheet:
+
+```css
+@import "tailwindcss";
+@import "@orochibraru/ui/theme.css";
+```
+
+The theme brings the design tokens, the `data-*` state variants the primitives
+style with, `tw-animate-css`, and an `@source` that makes Tailwind scan the
+package, so no other configuration is needed.
+
+## Use
+
+Every primitive is a subpath, with the same exports shadcn-svelte generates:
+
+```svelte
+<script lang="ts">
+  import EmptyState from "@orochibraru/ui/blocks/empty-state";
+  import { Button } from "@orochibraru/ui/button";
+  import * as Dialog from "@orochibraru/ui/dialog";
+  import { cn } from "@orochibraru/ui/utils";
+</script>
+```
+
+Moving an app over is a rewrite of its imports:
+`#lib/components/ui/button/index.js` becomes `@orochibraru/ui/button`.
+
+Primitives: accordion, alert, alert-dialog, avatar, badge, breadcrumb, button,
+button-group, calendar, card, checkbox, command, context-menu, dialog, drawer,
+dropdown-menu, empty, field, input, input-group, input-otp, label, menubar,
+pagination, popover, progress, radio-group, range-calendar, resizable,
+scroll-area, select, separator, sheet, sidebar, skeleton, slider, sonner,
+spinner, switch, table, tabs, textarea, toggle, toggle-group, tooltip.
+
+`input` turns password managers off on fields that don't set `autocomplete`, so
+a search box never gets a login suggestion.
+
+## Blocks
+
+Under `@orochibraru/ui/blocks/<name>`:
+
+| Block              | What it does                                                                |
+| ------------------ | --------------------------------------------------------------------------- |
+| `auth-shell`       | Centered sign-in layout: heading, optional `brand` and `footer` snippets.   |
+| `copy-field`       | Monospace value with a copy button and a promise toast.                     |
+| `document-title`   | `<title>` from the page title, suffixed with `appName`.                     |
+| `empty-state`      | Icon, title, subtitle and an action slot for an empty list.                 |
+| `error-page`       | Status, message and error id from `page`, with a link to `homeHref`.        |
+| `fab`              | Floating action button above the phone tab bar, with a haptic tap.          |
+| `icon-button`      | Round icon button with a tooltip that doubles as its accessible name.       |
+| `install-prompt`   | One-time PWA install sheet: native prompt, iOS steps or browser menu steps. |
+| `responsive-sheet` | A dialog on desktop, a bottom drawer under 768px.                           |
+| `setting-switch`   | Labelled switch row for settings forms, posting `name=true` when on.        |
+| `stat-card`        | Glass card with an icon, a value and a hint, optionally a link.             |
+| `top-loading-bar`  | Progress bar during SvelteKit navigations, safe-area aware.                 |
+
+Blocks with built-in copy (`copy-field`, `error-page`, `install-prompt`) take a
+`messages` prop. Its keys override the English defaults one by one, which is how
+a French or translated app uses them. Blocks never set the page title: the app
+calls `setPageTitle` itself.
+
+`icon-button`, and `copy-field` through it, need a `Tooltip.Provider` above
+them, which apps put in their root layout.
+
+## Modules
+
+- `@orochibraru/ui/utils`: `cn` and the shadcn-svelte prop helper types.
+- `@orochibraru/ui/toast`: `enhanceToast` and `saveToast` narrate a form action
+  through one promise toast, `toastError` turns anything thrown into a message.
+  Form updates keep `reset: false` by default so `bind:value` fields survive a
+  submit.
+- `@orochibraru/ui/page-title`: `providePageTitle` once in the root layout,
+  `setPageTitle` in pages, `usePageTitle` in app bars.
+- `@orochibraru/ui/appearance`: `applyAppearance` and `appearanceBootScript`
+  apply a saved accent, theme, dark variant, font and corner style to `<html>`,
+  the boot script before first paint.
+- `@orochibraru/ui/haptics`: `haptic("tap" | "success" | "error")`, a no-op
+  where vibration isn't supported.
+
+## Theming
+
+Colours derive from two variables, so an app usually overrides only these after
+importing the theme:
+
+```css
+:root {
+  --hue: 8;
+  --primary-chroma: 0.15;
+}
+```
+
+On `<html>`:
+
+- `class="dark"` switches to the dark palette, `data-dark-variant="amoled"`
+  makes it pure black.
+- `data-accent` picks a preset: `bordeaux`, `green`, `blue`, `violet`, `rose`,
+  `orange`, `amber`, `cyan` or `neutral`.
+- `data-font` (`system`, `serif`, `mono`) and `data-corners="square"` change the
+  type and the radius.
+
+`class="aurora"` on `<body>` adds the drifting gradient background. It is opt-in
+so apps with a flat look don't get it.
+
+The theme also defines the `glass`, `glow`, `no-scrollbar` and `tabular`
+utilities, the `standalone` variant for installed PWAs, `safe-*` spacing for
+notches, the toast styling and the page transitions on phones. Fonts are left to
+each app: set `--app-font` and `--display-font`.
+
+## Develop
+
+```bash
+bun install
+bun run dev
+```
+
+The dev server shows every primitive and block on one page, with an accent and
+dark mode switch. `bun run check`, `bun run test` and `bun run build` are the
+gates; `build` packages `dist/` and runs publint.
+
+New upstream components come from the shadcn-svelte CLI (`components.json` is
+set up), followed by `node_modules/.bin/tailwint --fix` on the new files. The
+CLI overwrites any customised primitive a new one depends on (drawer, input and
+sonner carry the apps' changes): copy those aside before `add --overwrite` and
+put them back after.
+
+Dependencies use caret ranges, unlike the apps' exact pins, so a consuming app
+dedupes `bits-ui` and friends with its own copy instead of bundling two.

package/dist/appearance.d.ts

@@ -0,0 +1,11 @@
+export interface AppearanceAttributes {
+    accent: string;
+    theme: string;
+    darkVariant: string;
+    font: string;
+    corners: string;
+}
+/** Applies an appearance to `<html>`: data attributes for accent, dark variant, font and corners, the `dark` class for the theme. */
+export declare function applyAppearance(root: HTMLElement, appearance: AppearanceAttributes, prefersDark: boolean): void;
+/** An inline script applying `appearance` before first paint, so a reload never flashes the default theme. */
+export declare function appearanceBootScript(appearance: AppearanceAttributes): string;

package/dist/appearance.js

@@ -0,0 +1,16 @@
+/** Applies an appearance to `<html>`: data attributes for accent, dark variant, font and corners, the `dark` class for the theme. */
+export function applyAppearance(root, appearance, prefersDark) {
+    root.dataset.accent = appearance.accent;
+    root.dataset.darkVariant = appearance.darkVariant;
+    root.dataset.font = appearance.font;
+    root.dataset.corners = appearance.corners;
+    const dark = appearance.theme === "dark" ||
+        (appearance.theme === "system" && prefersDark);
+    root.classList.toggle("dark", dark);
+    root.style.colorScheme = dark ? "dark" : "light";
+}
+/** An inline script applying `appearance` before first paint, so a reload never flashes the default theme. */
+export function appearanceBootScript(appearance) {
+    const values = JSON.stringify(appearance).replaceAll("<", "\\u003c");
+    return `<script>(function(){var a=${values};var r=document.documentElement;r.dataset.accent=a.accent;r.dataset.darkVariant=a.darkVariant;r.dataset.font=a.font;r.dataset.corners=a.corners;try{localStorage.setItem("mode-watcher-mode",a.theme)}catch(e){}var d=a.theme==="dark"||(a.theme==="system"&&matchMedia("(prefers-color-scheme: dark)").matches);r.classList.toggle("dark",d);r.style.colorScheme=d?"dark":"light"})()</script>`;
+}

package/dist/components/blocks/auth-shell.svelte

@@ -0,0 +1,35 @@
+<script lang="ts">
+	import type { Snippet } from "svelte";
+
+	interface Props {
+		heading: string;
+		subheading?: string;
+		brand?: Snippet;
+		children: Snippet;
+		footer?: Snippet;
+	}
+
+	const { heading, subheading, brand, children, footer }: Props = $props();
+</script>
+
+<div class="pt-safe-top flex min-h-[85dvh] flex-col justify-center px-6 py-12">
+	<div class="mx-auto w-full max-w-sm">
+		{#if brand}
+			<div class="mb-8">
+				{@render brand()}
+			</div>
+		{/if}
+		<h1 class="text-3xl font-bold tracking-tight">{heading}</h1>
+		{#if subheading}
+			<p class="text-muted-foreground mt-2">{subheading}</p>
+		{/if}
+		<div class="mt-8">
+			{@render children()}
+		</div>
+		{#if footer}
+			<p class="text-muted-foreground mt-8 text-center text-sm">
+				{@render footer()}
+			</p>
+		{/if}
+	</div>
+</div>

package/dist/components/blocks/auth-shell.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { Snippet } from "svelte";
+interface Props {
+    heading: string;
+    subheading?: string;
+    brand?: Snippet;
+    children: Snippet;
+    footer?: Snippet;
+}
+declare const AuthShell: import("svelte").Component<Props, {}, "">;
+type AuthShell = ReturnType<typeof AuthShell>;
+export default AuthShell;

package/dist/components/blocks/copy-field.svelte

@@ -0,0 +1,44 @@
+<script lang="ts">
+	import CheckIcon from "@lucide/svelte/icons/check";
+	import CopyIcon from "@lucide/svelte/icons/copy";
+	import { toast } from "svelte-sonner";
+
+	import IconButton from "./icon-button.svelte";
+
+	const defaultMessages = {
+		loading: "Copying",
+		success: "Copied.",
+		error: "Couldn't copy. Select the text instead.",
+	};
+
+	interface Props {
+		value: string;
+		label: string;
+		messages?: Partial<typeof defaultMessages>;
+	}
+
+	const { value, label, messages = {} }: Props = $props();
+
+	let copied = $state(false);
+
+	async function copyCallback() {
+		await navigator.clipboard.writeText(value);
+		copied = true;
+		setTimeout(() => (copied = false), 2000);
+	}
+
+	function handleCopy() {
+		toast.promise(copyCallback(), { ...defaultMessages, ...messages });
+	}
+</script>
+
+<div class="bg-muted flex min-w-0 items-center gap-2 rounded-xl py-1 pr-1 pl-3">
+	<span class="min-w-0 flex-1 truncate font-mono text-xs select-all"
+		>{value}</span
+	>
+	<IconButton
+		{label}
+		icon={copied ? CheckIcon : CopyIcon}
+		onclick={handleCopy}
+	/>
+</div>

package/dist/components/blocks/copy-field.svelte.d.ts

@@ -0,0 +1,11 @@
+declare const CopyField: import("svelte").Component<{
+    value: string;
+    label: string;
+    messages?: Partial<{
+        loading: string;
+        success: string;
+        error: string;
+    }>;
+}, {}, "">;
+type CopyField = ReturnType<typeof CopyField>;
+export default CopyField;

package/dist/components/blocks/document-title.svelte

@@ -0,0 +1,18 @@
+<script lang="ts">
+	import { usePageTitle } from "../../page-title.svelte.js";
+
+	const { appName }: { appName: string } = $props();
+
+	const title = usePageTitle();
+	const text = $derived(
+		!title.current
+			? appName
+			: title.current.includes(appName)
+				? title.current
+				: `${title.current} · ${appName}`,
+	);
+</script>
+
+<svelte:head>
+	<title>{text}</title>
+</svelte:head>

package/dist/components/blocks/document-title.svelte.d.ts

@@ -0,0 +1,6 @@
+type $$ComponentProps = {
+    appName: string;
+};
+declare const DocumentTitle: import("svelte").Component<$$ComponentProps, {}, "">;
+type DocumentTitle = ReturnType<typeof DocumentTitle>;
+export default DocumentTitle;

package/dist/components/blocks/empty-state.svelte

@@ -0,0 +1,45 @@
+<script lang="ts">
+	import type { Component, Snippet } from "svelte";
+
+	import { cn } from "../../utils.js";
+
+	interface Props {
+		icon: Component<{ class?: string }>;
+		title: string;
+		subtitle?: string;
+		children?: Snippet;
+		class?: string;
+	}
+
+	const {
+		icon: Icon,
+		title,
+		subtitle,
+		children,
+		class: className,
+	}: Props = $props();
+</script>
+
+<div
+	class={cn(
+		"flex flex-col items-center justify-center px-6 py-16 text-center",
+		className,
+	)}
+>
+	<div
+		class="bg-accent text-accent-foreground mb-5 flex size-16 items-center justify-center rounded-2xl"
+	>
+		<Icon class="size-7" />
+	</div>
+	<p class="text-lg font-semibold tracking-tight">{title}</p>
+	{#if subtitle}
+		<p class="text-muted-foreground mt-1.5 max-w-xs text-sm text-pretty">
+			{subtitle}
+		</p>
+	{/if}
+	{#if children}
+		<div class="mt-6">
+			{@render children()}
+		</div>
+	{/if}
+</div>

package/dist/components/blocks/empty-state.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { Component, Snippet } from "svelte";
+interface Props {
+    icon: Component<{
+        class?: string;
+    }>;
+    title: string;
+    subtitle?: string;
+    children?: Snippet;
+    class?: string;
+}
+declare const EmptyState: Component<Props, {}, "">;
+type EmptyState = ReturnType<typeof EmptyState>;
+export default EmptyState;

package/dist/components/blocks/error-page.svelte

@@ -0,0 +1,47 @@
+<script lang="ts">
+	import { page } from "$app/state";
+
+	import { Button } from "../ui/button/index.js";
+
+	const defaultMessages = {
+		notFoundTitle: "Nothing here",
+		notFoundDescription: "This page doesn't exist or was moved.",
+		errorTitle: "Something went wrong",
+		errorId: "Error ID",
+		home: "Back home",
+	};
+
+	interface Props {
+		homeHref: string;
+		messages?: Partial<typeof defaultMessages>;
+	}
+
+	const { homeHref, messages = {} }: Props = $props();
+
+	const text = $derived({ ...defaultMessages, ...messages });
+	const notFound = $derived(page.status === 404);
+</script>
+
+<div
+	class="pt-safe-top pb-safe-bottom flex min-h-dvh flex-col items-center justify-center gap-6 px-6 text-center"
+>
+	<p class="text-primary text-7xl font-bold tracking-tight tabular">
+		{page.status}
+	</p>
+	<div>
+		<h1 class="text-xl font-semibold">
+			{notFound ? text.notFoundTitle : text.errorTitle}
+		</h1>
+		<p class="text-muted-foreground mt-2 text-sm">
+			{notFound ? text.notFoundDescription : page.error?.message}
+		</p>
+		{#if page.error?.errorId}
+			<p class="text-muted-foreground mt-3 font-mono text-xs">
+				{text.errorId}: {page.error.errorId}
+			</p>
+		{/if}
+	</div>
+	<Button href={homeHref} size="lg" class="h-11 rounded-full px-6"
+		>{text.home}</Button
+	>
+</div>

package/dist/components/blocks/error-page.svelte.d.ts

@@ -0,0 +1,12 @@
+declare const ErrorPage: import("svelte").Component<{
+    homeHref: string;
+    messages?: Partial<{
+        notFoundTitle: string;
+        notFoundDescription: string;
+        errorTitle: string;
+        errorId: string;
+        home: string;
+    }>;
+}, {}, "">;
+type ErrorPage = ReturnType<typeof ErrorPage>;
+export default ErrorPage;

package/dist/components/blocks/fab.svelte

@@ -0,0 +1,26 @@
+<script lang="ts">
+	import type { Component } from "svelte";
+
+	import { haptic } from "../../haptics.js";
+
+	interface Props {
+		label: string;
+		icon: Component<{ class?: string }>;
+		onclick: () => void;
+	}
+
+	const { label, icon: Icon, onclick }: Props = $props();
+</script>
+
+<button
+	type="button"
+	aria-label={label}
+	onclick={() => {
+		haptic("tap");
+		onclick();
+	}}
+	class="from-primary glow fixed right-5 bottom-[calc(max(0.75rem,env(safe-area-inset-bottom))+5.25rem)] z-40 flex size-15 items-center justify-center rounded-2xl bg-linear-to-br to-[oklch(0.62_calc(var(--primary-chroma)*1.1)_calc(var(--hue)+40))] text-white transition-transform duration-200 active:scale-90 md:hidden"
+	style="view-transition-name: fab"
+>
+	<Icon class="size-7" />
+</button>

package/dist/components/blocks/fab.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { Component } from "svelte";
+interface Props {
+    label: string;
+    icon: Component<{
+        class?: string;
+    }>;
+    onclick: () => void;
+}
+declare const Fab: Component<Props, {}, "">;
+type Fab = ReturnType<typeof Fab>;
+export default Fab;

package/dist/components/blocks/icon-button.svelte

@@ -0,0 +1,38 @@
+<script lang="ts">
+	import type { Component } from "svelte";
+
+	import { Button, type ButtonProps } from "../ui/button/index.js";
+	import * as Tooltip from "../ui/tooltip/index.js";
+	import { cn } from "../../utils.js";
+
+	type Props = Omit<ButtonProps, "children"> & {
+		label: string;
+		icon: Component<{ class?: string }>;
+	};
+
+	const {
+		label,
+		icon: Icon,
+		class: className,
+		variant = "ghost",
+		...rest
+	}: Props = $props();
+</script>
+
+<Tooltip.Root>
+	<Tooltip.Trigger>
+		{#snippet child({ props })}
+			<Button
+				{...props}
+				{...rest}
+				{variant}
+				size="icon"
+				aria-label={label}
+				class={cn("size-11 rounded-full md:size-9", className)}
+			>
+				<Icon class="size-5" />
+			</Button>
+		{/snippet}
+	</Tooltip.Trigger>
+	<Tooltip.Content>{label}</Tooltip.Content>
+</Tooltip.Root>

package/dist/components/blocks/icon-button.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { Component } from "svelte";
+import { type ButtonProps } from "../ui/button/index.js";
+type Props = Omit<ButtonProps, "children"> & {
+    label: string;
+    icon: Component<{
+        class?: string;
+    }>;
+};
+declare const IconButton: Component<Props, {}, "">;
+type IconButton = ReturnType<typeof IconButton>;
+export default IconButton;

package/dist/components/blocks/install-prompt.svelte

@@ -0,0 +1,156 @@
+<script lang="ts">
+	import DownloadIcon from "@lucide/svelte/icons/download";
+	import EllipsisVerticalIcon from "@lucide/svelte/icons/ellipsis-vertical";
+	import ShareIcon from "@lucide/svelte/icons/share";
+	import SquarePlusIcon from "@lucide/svelte/icons/square-plus";
+	import { onMount, type Snippet } from "svelte";
+
+	import ResponsiveSheet from "./responsive-sheet.svelte";
+	import { Button } from "../ui/button/index.js";
+
+	interface InstallPromptEvent extends Event {
+		prompt: () => Promise<void>;
+		userChoice: Promise<{ outcome: "accepted" | "dismissed" }>;
+	}
+
+	const defaultMessages = {
+		description:
+			"Open it from your home screen like any app: full screen, quicker to reach, and with notifications.",
+		appleShare: "Tap Share in your browser's toolbar or address bar.",
+		appleAdd: "Pick Add to Home Screen, then Add.",
+		menuOpen: "Open your browser's menu.",
+		menuInstall: "Pick Install app or Add to Home screen.",
+		gotIt: "Got it",
+		install: "Install",
+		notNow: "Not now",
+	};
+
+	interface Props {
+		appName: string;
+		storageKey: string;
+		brand?: Snippet;
+		title?: string;
+		messages?: Partial<typeof defaultMessages>;
+	}
+
+	const {
+		appName,
+		storageKey,
+		brand,
+		title = `Install ${appName}`,
+		messages = {},
+	}: Props = $props();
+
+	const text = $derived({ ...defaultMessages, ...messages });
+
+	let open = $state(false);
+	let mode = $state<"native" | "apple" | "menu">("native");
+	let deferred: InstallPromptEvent | undefined;
+
+	function alreadyPrompted(): boolean {
+		try {
+			return localStorage.getItem(storageKey) !== null;
+		} catch {
+			return true;
+		}
+	}
+
+	function show(next: "native" | "apple" | "menu") {
+		if (alreadyPrompted()) {
+			return;
+		}
+		mode = next;
+		open = true;
+		try {
+			localStorage.setItem(storageKey, new Date().toISOString());
+		} catch {
+			open = false;
+		}
+	}
+
+	onMount(() => {
+		const standalone =
+			matchMedia("(display-mode: standalone)").matches ||
+			("standalone" in navigator && navigator.standalone === true);
+		const touch = matchMedia("(pointer: coarse)").matches;
+		if (standalone || !touch || alreadyPrompted()) {
+			return;
+		}
+		const apple =
+			/iPhone|iPad/.test(navigator.userAgent) ||
+			(/Macintosh/.test(navigator.userAgent) && navigator.maxTouchPoints > 1);
+		if (apple) {
+			const timer = setTimeout(() => show("apple"), 1500);
+			return () => clearTimeout(timer);
+		}
+		const capture = (event: Event) => {
+			event.preventDefault();
+			deferred = event as InstallPromptEvent;
+			if (open) {
+				mode = "native";
+			} else {
+				show("native");
+			}
+		};
+		addEventListener("beforeinstallprompt", capture);
+		const fallback = setTimeout(() => {
+			if (!deferred) {
+				show("menu");
+			}
+		}, 4000);
+		return () => {
+			removeEventListener("beforeinstallprompt", capture);
+			clearTimeout(fallback);
+		};
+	});
+
+	async function install() {
+		open = false;
+		await deferred?.prompt();
+		deferred = undefined;
+	}
+</script>
+
+{#snippet step(Icon: typeof ShareIcon, label: string)}
+	<li class="flex items-center gap-3">
+		<span
+			class="bg-accent text-accent-foreground flex size-9 shrink-0 items-center justify-center rounded-xl"
+			><Icon class="size-4" /></span
+		>
+		{label}
+	</li>
+{/snippet}
+
+<ResponsiveSheet bind:open {title} description={text.description}>
+	<div class="flex flex-col gap-5 pb-4">
+		{#if brand}
+			<div class="flex justify-center py-2">
+				{@render brand()}
+			</div>
+		{/if}
+		{#if mode === "native"}
+			<Button class="glow h-12 rounded-xl text-base" onclick={install}>
+				<DownloadIcon />
+				{text.install}
+			</Button>
+			<Button
+				variant="ghost"
+				class="h-11 rounded-xl"
+				onclick={() => (open = false)}>{text.notNow}</Button
+			>
+		{:else}
+			<ol class="flex flex-col gap-3 text-sm">
+				{#if mode === "apple"}
+					{@render step(ShareIcon, text.appleShare)}
+					{@render step(SquarePlusIcon, text.appleAdd)}
+				{:else}
+					{@render step(EllipsisVerticalIcon, text.menuOpen)}
+					{@render step(SquarePlusIcon, text.menuInstall)}
+				{/if}
+			</ol>
+			<Button class="h-12 rounded-xl text-base" onclick={() => (open = false)}
+				>{text.gotIt}</Button
+			>
+		{/if}
+	</div>
+</ResponsiveSheet>