@orochibraru/ui 0.0.0 → 1.0.0-canary.1

package/README.md

@@ -59,26 +59,58 @@ a search box never gets a login suggestion.
 
 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
+| 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.
 
@@ -94,6 +126,9 @@ them, which apps put in their root layout.
 - `@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.
 
@@ -133,9 +168,23 @@ 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.
+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
@@ -145,3 +194,30 @@ 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/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/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/music-player/format-time.d.ts

@@ -0,0 +1,2 @@
+/** `m:ss`, or `h:mm:ss` past an hour; an unknown or endless duration reads `0:00`. */
+export declare function formatTime(seconds: number): string;

package/dist/components/blocks/music-player/format-time.js

@@ -0,0 +1,13 @@
+/** `m:ss`, or `h:mm:ss` past an hour; an unknown or endless duration reads `0:00`. */
+export function formatTime(seconds) {
+    if (!Number.isFinite(seconds) || seconds < 0) {
+        return "0:00";
+    }
+    const whole = Math.floor(seconds);
+    const hours = Math.floor(whole / 3600);
+    const minutes = Math.floor((whole % 3600) / 60);
+    const rest = String(whole % 60).padStart(2, "0");
+    return hours > 0
+        ? `${hours}:${String(minutes).padStart(2, "0")}:${rest}`
+        : `${minutes}:${rest}`;
+}

package/dist/components/blocks/music-player/labelled-slider.svelte

@@ -0,0 +1,36 @@
+<script lang="ts">
+	import { Slider } from "../../ui/slider/index.js";
+
+	interface Props {
+		value: number;
+		max: number;
+		step: number;
+		label: string;
+		valueText: string;
+		onchange?: (value: number) => void;
+		oncommit?: (value: number) => void;
+		orientation?: "horizontal" | "vertical";
+		disabled?: boolean;
+		class?: string;
+	}
+
+	const { value, label, valueText, onchange, oncommit, ...rest }: Props =
+		$props();
+
+	let ref: HTMLElement | null = $state(null);
+
+	$effect(() => {
+		const thumb = ref?.querySelector("[role=slider]");
+		thumb?.setAttribute("aria-label", label);
+		thumb?.setAttribute("aria-valuetext", valueText);
+	});
+</script>
+
+<Slider
+	bind:ref
+	type="single"
+	{value}
+	onValueChange={onchange}
+	onValueCommit={oncommit}
+	{...rest}
+/>

package/dist/components/blocks/music-player/labelled-slider.svelte.d.ts

@@ -0,0 +1,15 @@
+interface Props {
+    value: number;
+    max: number;
+    step: number;
+    label: string;
+    valueText: string;
+    onchange?: (value: number) => void;
+    oncommit?: (value: number) => void;
+    orientation?: "horizontal" | "vertical";
+    disabled?: boolean;
+    class?: string;
+}
+declare const LabelledSlider: import("svelte").Component<Props, {}, "">;
+type LabelledSlider = ReturnType<typeof LabelledSlider>;
+export default LabelledSlider;

package/dist/components/blocks/music-player/volume-control.svelte

@@ -0,0 +1,48 @@
+<script lang="ts">
+	import Volume1Icon from "@lucide/svelte/icons/volume-1";
+	import Volume2Icon from "@lucide/svelte/icons/volume-2";
+	import VolumeXIcon from "@lucide/svelte/icons/volume-x";
+
+	import { Button } from "../../ui/button/index.js";
+	import * as Popover from "../../ui/popover/index.js";
+
+	import LabelledSlider from "./labelled-slider.svelte";
+
+	interface Props {
+		volume: number;
+		label: string;
+	}
+
+	let { volume = $bindable(1), label }: Props = $props();
+
+	const Icon = $derived(
+		volume === 0 ? VolumeXIcon : volume < 0.5 ? Volume1Icon : Volume2Icon,
+	);
+</script>
+
+<Popover.Root>
+	<Popover.Trigger>
+		{#snippet child({ props })}
+			<Button
+				{...props}
+				variant="ghost"
+				size="icon"
+				aria-label={label}
+				class="size-11 rounded-full md:size-9"
+			>
+				<Icon class="size-5" />
+			</Button>
+		{/snippet}
+	</Popover.Trigger>
+	<Popover.Content class="glass w-auto items-center rounded-2xl p-4">
+		<LabelledSlider
+			orientation="vertical"
+			value={volume}
+			max={1}
+			step={0.01}
+			{label}
+			valueText={`${Math.round(volume * 100)}%`}
+			onchange={(value) => (volume = value)}
+		/>
+	</Popover.Content>
+</Popover.Root>

package/dist/components/blocks/music-player/volume-control.svelte.d.ts

@@ -0,0 +1,7 @@
+interface Props {
+    volume: number;
+    label: string;
+}
+declare const VolumeControl: import("svelte").Component<Props, {}, "volume">;
+type VolumeControl = ReturnType<typeof VolumeControl>;
+export default VolumeControl;