@orochibraru/ui 0.0.0-stage → 1.0.0-canary.1

package/README.md

@@ -1,3 +1,223 @@
-# 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                                                                  |
+| --------------------- | ----------------------------------------------------------------------------- |
+| `accent-toggle`       | The accent presets: swatch strip on desktop, labelled rows on phones.         |
+| `auth-shell`          | Centered sign-in layout: heading, optional `brand` and `footer` snippets.     |
+| `bottom-nav`          | Phone tab bar of top-level destinations, the current one lit.                 |
+| `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.   |
+| `music-player`        | Audio bar with a queue: play, skip, seek, volume; positioning is the app's.   |
+| `nav-cards`           | Phone-only list of a section's tabs as cards: icon, label, description.       |
+| `new-password-fields` | New password and its confirmation: reveal, strength meter, rules.             |
+| `option-group`        | Radio cards for a settings choice, with an icon or a `swatch` snippet each.   |
+| `otp-field`           | One-time code: digits only, SMS autofill, posted as one `code` field.         |
+| `password-input`      | Password field with a button to reveal it.                                    |
+| `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.               |
+| `tab-nav`             | Pill tab bar of links, the current page's tab highlighted.                    |
+| `tab-section`         | Layout for a tabbed section: tabs on desktop, nav cards on phones.            |
+| `theme-picker`        | System, light and dark as radio cards, for an appearance page.                |
+| `theme-toggle`        | System, light and dark: icon strip on desktop, three rows on phones.          |
+| `top-loading-bar`     | Progress bar during SvelteKit navigations, safe-area aware.                   |
+| `video-player`        | Video with scrubbing, chapters, subtitles, speed, fullscreen, gestures, keys. |
+
+Blocks with built-in copy (`accent-toggle`, `copy-field`, `error-page`,
+`install-prompt`, `new-password-fields`, `password-input`, `theme-picker`,
+`theme-toggle`) 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, except `tab-section`, which owns its section's title: the app
+calls `setPageTitle` itself.
+
+### Tabbed sections
+
+A tabbed page is one real route per tab, each tab with a description, under a
+`tab-section` layout. On phones the index route renders `nav-cards` and each tab
+is a page titled by its label, its back button returning to the cards. On
+desktop the index replaces itself with the first tab and `tab-nav` shows them
+all. The tabs live in one list (`SectionTab[]`, exported by `nav-cards`) that
+the layout and the index page share.
+
+### Theme
+
+`theme-picker` and `theme-toggle` call `mode-watcher`'s `setMode`, so the app
+mounts `<ModeWatcher />` in its root layout. Both take the saved theme as
+`value`, so the server-rendered page checks the right one, and call `onchange`
+with the new theme for the app to persist. `theme-picker` also posts as a
+`theme` radio field (`name` changes it) inside a form.
+
+`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/password`: `passwordRules` and `passwordScore`, the rules a
+  new password must pass and a 0 to 4 strength, the same on the form and the
+  server. `new-password-fields` renders them; `ruleLabels` translates them.
+- `@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 is the docs site: a page per block, primitive and module, with
+the component live and the code that renders it. That code is the example file
+itself, its `#lib` imports rewritten to the package subpaths, so the two can't
+drift apart. A file named `<slug>.<name>` next to an example is a companion,
+shown after it: the layout, action or page an app needs for what the preview
+can't hold. An example without a script is a note for the preview only.
+
+Every component page can be copied as Markdown, viewed as Markdown, exported as
+a PDF (through the browser's print dialog, in the light theme), or opened in
+Claude or ChatGPT. The list pages filter by category.
+
+The `Dockerfile` deploys the docs site: `bun run build:docs` compiles it to one
+Bun binary that serves on port 3000 and reads `x-forwarded-proto` and
+`x-forwarded-host`, so llms.txt links point at the public URL behind a proxy.
+
+`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.
+
+## MCP server
+
+The package ships an MCP server with the docs and every example's code bundled
+in, so an editor's assistant can list, search and read the components without
+the docs site. It runs over stdio from the package's `bin`:
+
+```bash
+claude mcp add orochibraru-ui -- npx -y @orochibraru/ui
+```
+
+Cursor, VS Code and other clients take the same command:
+
+```json
+{
+  "mcpServers": {
+    "orochibraru-ui": { "command": "npx", "args": ["-y", "@orochibraru/ui"] }
+  }
+}
+```
+
+Its tools are `get_setup` (this README), `list_components` (by group or
+category), `search_components` and `get_component` (the description, import path
+and usage code). `bun run build` bundles it with its content, so it needs no
+dependency at runtime. The docs site serves the same server over streamable HTTP
+at `/mcp`, plus `/llms.txt`, `/llms-full.txt` and a Markdown page per component
+at `/<group>/<slug>.md`.

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/accent-toggle.svelte

@@ -0,0 +1,85 @@
+<script lang="ts">
+	import { MediaQuery } from "svelte/reactivity";
+
+	import * as ToggleGroup from "../ui/toggle-group/index.js";
+
+	type Accent =
+		| "blue"
+		| "bordeaux"
+		| "green"
+		| "violet"
+		| "rose"
+		| "orange"
+		| "amber"
+		| "cyan"
+		| "neutral";
+
+	const defaultMessages = {
+		label: "Accent",
+		blue: "Blue",
+		bordeaux: "Bordeaux",
+		green: "Green",
+		violet: "Violet",
+		rose: "Rose",
+		orange: "Orange",
+		amber: "Amber",
+		cyan: "Cyan",
+		neutral: "Neutral",
+	};
+
+	interface Props {
+		value?: Accent;
+		onchange?: (accent: Accent) => void;
+		messages?: Partial<typeof defaultMessages>;
+	}
+
+	let { value = $bindable("blue"), onchange, messages = {} }: Props = $props();
+
+	const accents: Accent[] = [
+		"blue",
+		"bordeaux",
+		"green",
+		"violet",
+		"rose",
+		"orange",
+		"amber",
+		"cyan",
+		"neutral",
+	];
+
+	const desktop = new MediaQuery("(min-width: 768px)");
+	const text = $derived({ ...defaultMessages, ...messages });
+
+	function pick(next: string) {
+		if (!next) {
+			return;
+		}
+		value = next as Accent;
+		document.documentElement.dataset.accent = value;
+		onchange?.(value);
+	}
+</script>
+
+<ToggleGroup.Root
+	type="single"
+	variant="outline"
+	orientation={desktop.current ? "horizontal" : "vertical"}
+	aria-label={text.label}
+	class="max-md:w-full"
+	bind:value={() => value, pick}
+>
+	{#each accents as accent (accent)}
+		<ToggleGroup.Item
+			value={accent}
+			aria-label={text[accent]}
+			title={text[accent]}
+			data-accent={accent}
+			class="max-md:h-12 max-md:w-full max-md:justify-start max-md:gap-3 max-md:px-4 md:size-9"
+		>
+			<span
+				class="size-3 rounded-full bg-[oklch(0.6_var(--primary-chroma)_var(--hue))]"
+			></span>
+			<span class="md:hidden">{text[accent]}</span>
+		</ToggleGroup.Item>
+	{/each}
+</ToggleGroup.Root>

package/dist/components/blocks/accent-toggle.svelte.d.ts

@@ -0,0 +1,18 @@
+declare const AccentToggle: import("svelte").Component<{
+    value?: "blue" | "bordeaux" | "green" | "violet" | "rose" | "orange" | "amber" | "cyan" | "neutral";
+    onchange?: (accent: "blue" | "bordeaux" | "green" | "violet" | "rose" | "orange" | "amber" | "cyan" | "neutral") => void;
+    messages?: Partial<{
+        label: string;
+        blue: string;
+        bordeaux: string;
+        green: string;
+        violet: string;
+        rose: string;
+        orange: string;
+        amber: string;
+        cyan: string;
+        neutral: string;
+    }>;
+}, {}, "value">;
+type AccentToggle = ReturnType<typeof AccentToggle>;
+export default AccentToggle;

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/bottom-nav.svelte

@@ -0,0 +1,67 @@
+<script lang="ts" module>
+	import type { Component } from "svelte";
+
+	export interface NavItem {
+		href: string;
+		label: string;
+		icon: Component<{ class?: string }>;
+	}
+
+	/** Whether `pathname` sits under the destination at `href`; the root only matches itself. */
+	export function isUnder(pathname: string, href: string): boolean {
+		return href === "/"
+			? pathname === "/"
+			: pathname === href || pathname.startsWith(`${href}/`);
+	}
+</script>
+
+<script lang="ts">
+	import { page } from "$app/state";
+
+	interface Props {
+		items: NavItem[];
+		isActive?: (pathname: string, href: string) => boolean;
+		label?: string;
+	}
+
+	const { items, isActive = isUnder, label = "Main" }: Props = $props();
+
+	let compact = $state(false);
+	let lastY = 0;
+
+	function onscroll() {
+		const y = window.scrollY;
+		if (Math.abs(y - lastY) < 8) {
+			return;
+		}
+		compact = y > lastY && y > 64;
+		lastY = y;
+	}
+</script>
+
+<svelte:window {onscroll} />
+
+<nav
+	class="group/nav fixed inset-x-0 bottom-0 z-40 px-4 pb-[max(0.75rem,env(safe-area-inset-bottom))] md:hidden print:hidden"
+	style="view-transition-name: tab-bar"
+	aria-label={label}
+	data-compact={compact || undefined}
+>
+	<ul
+		class="bg-popover border-border mx-auto flex max-w-sm items-center gap-1 rounded-full border p-1.5 shadow-lg"
+	>
+		{#each items as item (item.href)}
+			{@const active = isActive(page.url.pathname, item.href)}
+			<li class="flex-1">
+				<a
+					href={item.href}
+					aria-current={active ? "page" : undefined}
+					class="text-muted-foreground aria-[current=page]:bg-primary aria-[current=page]:text-primary-foreground aria-[current=page]:glow flex h-12 flex-col items-center justify-center gap-0.5 rounded-full px-0.5 text-[0.6875rem] font-medium tracking-tight transition-all group-data-compact/nav:h-10 active:scale-95"
+				>
+					<item.icon class="size-5" />
+					<span class="group-data-compact/nav:sr-only">{item.label}</span>
+				</a>
+			</li>
+		{/each}
+	</ul>
+</nav>

package/dist/components/blocks/bottom-nav.svelte.d.ts

@@ -0,0 +1,18 @@
+import type { Component } from "svelte";
+export interface NavItem {
+    href: string;
+    label: string;
+    icon: Component<{
+        class?: string;
+    }>;
+}
+/** Whether `pathname` sits under the destination at `href`; the root only matches itself. */
+export declare function isUnder(pathname: string, href: string): boolean;
+interface Props {
+    items: NavItem[];
+    isActive?: (pathname: string, href: string) => boolean;
+    label?: string;
+}
+declare const BottomNav: Component<Props, {}, "">;
+type BottomNav = ReturnType<typeof BottomNav>;
+export default BottomNav;

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;