@orochibraru/ui 1.0.0 → 1.0.1

package/dist/server/hooks.d.ts

@@ -0,0 +1,9 @@
+import type { Handle, HandleServerError } from "@sveltejs/kit/hooks";
+import type { Logger } from "./logger.js";
+/** A `handle` writing one log line per request, skipping assets, data requests and the paths in `quietPaths`. */
+export declare function requestLog(logger: Logger, quietPaths?: string[]): Handle;
+/**
+ * A `handleError` for unexpected errors: logs them, records them on the request's span, and returns an `errorId`
+ * (the trace id when tracing is on) that the error page shows, so a user's report leads to the trace.
+ */
+export declare function unexpectedErrors(logger: Logger, message?: string): HandleServerError;

package/dist/server/hooks.js

@@ -0,0 +1,41 @@
+import { SpanStatusCode, trace } from "@opentelemetry/api";
+const defaultQuietPaths = [
+    "/_app/",
+    "/.well-known/",
+    "/api/health",
+    "/favicon",
+    "/sw.js",
+    "/workbox-",
+];
+/** A `handle` writing one log line per request, skipping assets, data requests and the paths in `quietPaths`. */
+export function requestLog(logger, quietPaths = defaultQuietPaths) {
+    return async ({ event, resolve }) => {
+        const startedAt = performance.now();
+        const response = await resolve(event);
+        const path = event.url.pathname;
+        if (!path.endsWith("/__data.json") &&
+            !quietPaths.some((quiet) => path.startsWith(quiet))) {
+            logger.request({
+                method: event.request.method,
+                path,
+                status: response.status,
+                durationMs: Math.round(performance.now() - startedAt),
+            });
+        }
+        return response;
+    };
+}
+/**
+ * A `handleError` for unexpected errors: logs them, records them on the request's span, and returns an `errorId`
+ * (the trace id when tracing is on) that the error page shows, so a user's report leads to the trace.
+ */
+export function unexpectedErrors(logger, message = "Something went wrong.") {
+    return ({ error, event }) => {
+        const span = trace.getActiveSpan();
+        span?.recordException(error instanceof Error ? error : String(error));
+        span?.setStatus({ code: SpanStatusCode.ERROR });
+        const errorId = span?.spanContext().traceId ?? crypto.randomUUID();
+        logger.error("Unhandled error", { errorId, method: event.request.method, path: event.url.pathname }, error);
+        return { errorId, message };
+    };
+}

package/dist/server/logger.d.ts

@@ -0,0 +1,39 @@
+export type LogLevel = "trace" | "debug" | "info" | "warn" | "error";
+export type LogFormat = "console" | "json";
+export interface LogSettings {
+    level: LogLevel;
+    format: LogFormat;
+}
+export interface RequestLine {
+    method: string;
+    path: string;
+    status: number;
+    durationMs: number;
+}
+/** Sets the level and format every logger writes with; until then they come from `LOG_LEVEL` and `LOG_FORMAT`. */
+export declare function configureLogging(next: Partial<LogSettings>): void;
+/**
+ * Writes scoped log lines, as coloured text or JSON lines, at or above the configured level. JSON lines carry the
+ * active OpenTelemetry trace and span ids, so a log line can be found from its trace and back.
+ */
+export declare class Logger {
+    #private;
+    /** Creates a logger whose lines are tagged with `scope`. */
+    constructor(scope: string);
+    /** Writes a trace line. */
+    trace(message: string, ...params: unknown[]): void;
+    /** Writes a debug line. */
+    debug(message: string, ...params: unknown[]): void;
+    /** Writes an info line. */
+    info(message: string, ...params: unknown[]): void;
+    /** Writes a warning line to stderr. */
+    warn(message: string, ...params: unknown[]): void;
+    /** Writes an error line to stderr; an `Error` param is serialised with its stack. */
+    error(message: string, ...params: unknown[]): void;
+    /** Writes one line for a finished HTTP request, at error level for a 4xx or 5xx other than 404. */
+    request(line: RequestLine): void;
+    /** Writes `lines` framed in hashtags so they stand out in console output; JSON format logs them as one line. */
+    banner(level: LogLevel, lines: string[]): void;
+    /** Writes `text` as is at info level in console output, for a boot logo; JSON format skips it. */
+    art(text: string): void;
+}

package/dist/server/logger.js

@@ -0,0 +1,144 @@
+import { inspect, styleText } from "node:util";
+import { trace } from "@opentelemetry/api";
+const levelOrder = ["trace", "debug", "info", "warn", "error"];
+const levelColors = {
+    trace: "gray",
+    debug: "cyan",
+    info: "blue",
+    warn: "yellow",
+    error: "red",
+};
+function isLevel(value) {
+    return levelOrder.includes(value);
+}
+let settings = {
+    level: isLevel(process.env.LOG_LEVEL) ? process.env.LOG_LEVEL : "info",
+    format: process.env.LOG_FORMAT === "json" ? "json" : "console",
+};
+/** Sets the level and format every logger writes with; until then they come from `LOG_LEVEL` and `LOG_FORMAT`. */
+export function configureLogging(next) {
+    settings = { ...settings, ...next };
+}
+/**
+ * Writes scoped log lines, as coloured text or JSON lines, at or above the configured level. JSON lines carry the
+ * active OpenTelemetry trace and span ids, so a log line can be found from its trace and back.
+ */
+export class Logger {
+    #scope;
+    /** Creates a logger whose lines are tagged with `scope`. */
+    constructor(scope) {
+        this.#scope = scope;
+    }
+    /** Writes a trace line. */
+    trace(message, ...params) {
+        this.#write("trace", message, params);
+    }
+    /** Writes a debug line. */
+    debug(message, ...params) {
+        this.#write("debug", message, params);
+    }
+    /** Writes an info line. */
+    info(message, ...params) {
+        this.#write("info", message, params);
+    }
+    /** Writes a warning line to stderr. */
+    warn(message, ...params) {
+        this.#write("warn", message, params);
+    }
+    /** Writes an error line to stderr; an `Error` param is serialised with its stack. */
+    error(message, ...params) {
+        this.#write("error", message, params);
+    }
+    /** Writes one line for a finished HTTP request, at error level for a 4xx or 5xx other than 404. */
+    request(line) {
+        const level = line.status >= 400 && line.status !== 404 ? "error" : "info";
+        if (settings.format === "json") {
+            this.#write(level, "request", [{ ...line }]);
+            return;
+        }
+        const summary = [
+            styleText("bold", line.method),
+            line.path,
+            styleText(this.#statusColor(line.status), String(line.status)),
+            styleText("gray", `${line.durationMs}ms`),
+        ].join(" ");
+        this.#write(level, summary, []);
+    }
+    /** Writes `lines` framed in hashtags so they stand out in console output; JSON format logs them as one line. */
+    banner(level, lines) {
+        if (settings.format === "json") {
+            this.#write(level, lines.join(" "), []);
+            return;
+        }
+        const width = Math.max(...lines.map((line) => line.length)) + 6;
+        const edge = "#".repeat(width);
+        const blank = `#${" ".repeat(width - 2)}#`;
+        this.#write(level, [
+            "",
+            edge,
+            blank,
+            ...lines.map((line) => `#  ${line.padEnd(width - 6)}  #`),
+            blank,
+            edge,
+        ].join("\n"), []);
+    }
+    /** Writes `text` as is at info level in console output, for a boot logo; JSON format skips it. */
+    art(text) {
+        if (settings.format === "console") {
+            this.#write("info", text, []);
+        }
+    }
+    /** The colour of an HTTP status in console output. */
+    #statusColor(status) {
+        if (status >= 500) {
+            return "red";
+        }
+        return status >= 400 ? "yellow" : "green";
+    }
+    /** Writes one line at `level` when the configured level lets it through. */
+    #write(level, message, params) {
+        if (levelOrder.indexOf(level) < levelOrder.indexOf(settings.level)) {
+            return;
+        }
+        const output = level === "warn" || level === "error" ? console.error : console.log;
+        if (settings.format === "json") {
+            output(JSON.stringify(this.#jsonLine(level, message, params)));
+            return;
+        }
+        output(styleText("gray", new Date().toISOString().slice(11, 23)), styleText(levelColors[level], level.toUpperCase().padEnd(5)), styleText("magenta", `[${this.#scope}]`), message, ...params.map((param) => typeof param === "string"
+            ? param
+            : inspect(param, { colors: true, depth: 5 })));
+    }
+    /** The JSON fields of a line: the active trace, an `Error` param serialised, plain objects merged in, anything else under `params`. */
+    #jsonLine(level, message, params) {
+        const fields = {};
+        const rest = [];
+        for (const param of params) {
+            if (param instanceof Error) {
+                fields.error = {
+                    name: param.name,
+                    message: param.message,
+                    stack: param.stack,
+                };
+            }
+            else if (typeof param === "object" &&
+                param !== null &&
+                Object.getPrototypeOf(param) === Object.prototype) {
+                Object.assign(fields, param);
+            }
+            else {
+                rest.push(param);
+            }
+        }
+        const span = trace.getActiveSpan()?.spanContext();
+        return {
+            time: new Date().toISOString(),
+            level,
+            scope: this.#scope,
+            message,
+            ...(span && { trace_id: span.traceId, span_id: span.spanId }),
+            ...fields,
+            ...(rest.length > 0 && { params: rest }),
+        };
+    }
+}

package/dist/server/telemetry.d.ts

@@ -0,0 +1,23 @@
+import { type Span } from "@opentelemetry/api";
+export interface TelemetryOptions {
+    serviceName: string;
+    serviceVersion?: string;
+    /** The OTLP base URL, like `http://collector:4318`; tracing stays off without one. */
+    endpoint?: string;
+    resourceAttributes?: Record<string, string>;
+}
+/**
+ * OpenTelemetry tracing over OTLP for a SvelteKit server: start it from `instrumentation.server.ts` and turn on
+ * `tracing: { server: true }` in the kit options, and SvelteKit's own spans for handle, load and actions are exported
+ * with the app's.
+ */
+export declare class Telemetry {
+    #private;
+    constructor(options: TelemetryOptions);
+    /** Registers the global tracer provider; logs and does nothing without an endpoint. Returns whether tracing is on. */
+    start(): boolean;
+    /** Runs `work` inside a span named `name`, marking the span failed and rethrowing when `work` throws. */
+    withSpan<Result>(name: string, attributes: Record<string, string | number | boolean>, work: (span: Span) => Promise<Result>): Promise<Result>;
+    /** Exports the pending spans and stops tracing; never throws, for a shutdown hook. */
+    flush(): Promise<void>;
+}

package/dist/server/telemetry.js

@@ -0,0 +1,82 @@
+import { context, diag, DiagLogLevel, SpanStatusCode, trace, } from "@opentelemetry/api";
+import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
+import { defaultResource, resourceFromAttributes, } from "@opentelemetry/resources";
+import { BatchSpanProcessor, TracerProvider } from "@opentelemetry/sdk-trace";
+import { Logger } from "./logger.js";
+const logger = new Logger("Telemetry");
+/**
+ * OpenTelemetry tracing over OTLP for a SvelteKit server: start it from `instrumentation.server.ts` and turn on
+ * `tracing: { server: true }` in the kit options, and SvelteKit's own spans for handle, load and actions are exported
+ * with the app's.
+ */
+export class Telemetry {
+    #options;
+    #provider;
+    constructor(options) {
+        this.#options = options;
+    }
+    /** Registers the global tracer provider; logs and does nothing without an endpoint. Returns whether tracing is on. */
+    start() {
+        const { endpoint, serviceName, serviceVersion, resourceAttributes } = this.#options;
+        if (!endpoint) {
+            logger.info("Tracing off: no OTLP endpoint", { serviceName });
+            return false;
+        }
+        const forward = (message, ...args) => logger.warn(message, ...args);
+        diag.setLogger({
+            error: forward,
+            warn: forward,
+            info: forward,
+            debug: forward,
+            verbose: forward,
+        }, DiagLogLevel.WARN);
+        context.setGlobalContextManager(new AsyncLocalStorageContextManager().enable());
+        this.#provider = new TracerProvider({
+            resource: defaultResource().merge(resourceFromAttributes({
+                ...resourceAttributes,
+                "service.name": serviceName,
+                ...(serviceVersion && { "service.version": serviceVersion }),
+            })),
+            spanProcessors: [
+                new BatchSpanProcessor({
+                    exporter: new OTLPTraceExporter({
+                        url: `${endpoint.replace(/\/+$/, "")}/v1/traces`,
+                    }),
+                }),
+            ],
+        });
+        trace.setGlobalTracerProvider(this.#provider);
+        logger.info("Tracing on", { endpoint, serviceName });
+        return true;
+    }
+    /** Runs `work` inside a span named `name`, marking the span failed and rethrowing when `work` throws. */
+    withSpan(name, attributes, work) {
+        return trace
+            .getTracer(this.#options.serviceName)
+            .startActiveSpan(name, { attributes }, async (span) => {
+            try {
+                return await work(span);
+            }
+            catch (error) {
+                span.recordException(error instanceof Error ? error : String(error));
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                throw error;
+            }
+            finally {
+                span.end();
+            }
+        });
+    }
+    /** Exports the pending spans and stops tracing; never throws, for a shutdown hook. */
+    async flush() {
+        await this.#provider?.shutdown().catch(() => { });
+        trace.disable();
+        context.disable();
+        diag.disable();
+        this.#provider = undefined;
+    }
+}

package/dist/theme.css

@@ -13,8 +13,18 @@
 @custom-variant data-vertical (&:where([data-orientation="vertical"]));
 
 :root {
-	--hue: 255;
-	--primary-chroma: 0.19;
+	--safe-top: max(env(safe-area-inset-top), var(--emulated-safe-top, 0px));
+	--safe-bottom: max(
+		env(safe-area-inset-bottom),
+		var(--emulated-safe-bottom, 0px)
+	);
+	--safe-left: max(env(safe-area-inset-left), var(--emulated-safe-left, 0px));
+	--safe-right: max(
+		env(safe-area-inset-right),
+		var(--emulated-safe-right, 0px)
+	);
+	--hue: 8;
+	--primary-chroma: 0.15;
 	--app-font: ui-sans-serif, system-ui, sans-serif;
 	--display-font: var(--app-font);
 	--radius: 1rem;
@@ -108,12 +118,14 @@
 	);
 }
 
+:root:not([data-accent]),
 [data-accent="bordeaux"] {
 	--hue: 8;
 	--primary-chroma: 0.15;
 	--primary: oklch(0.44 0.15 8);
 }
 
+.dark:not([data-accent]),
 .dark[data-accent="bordeaux"] {
 	--primary: oklch(0.62 0.17 12);
 }
@@ -228,10 +240,10 @@
 	--color-sidebar-border: var(--sidebar-border);
 	--color-sidebar-ring: var(--sidebar-ring);
 	--color-chrome: var(--chrome);
-	--spacing-safe-top: env(safe-area-inset-top);
-	--spacing-safe-bottom: env(safe-area-inset-bottom);
-	--spacing-safe-left: env(safe-area-inset-left);
-	--spacing-safe-right: env(safe-area-inset-right);
+	--spacing-safe-top: var(--safe-top);
+	--spacing-safe-bottom: var(--safe-bottom);
+	--spacing-safe-left: var(--safe-left);
+	--spacing-safe-right: var(--safe-right);
 }
 
 @layer base {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@orochibraru/ui",
-	"version": "1.0.0",
+	"version": "1.0.1",
 	"description": "Svelte 5 components and theme shared by OpenCount, LocalAssistant, Homerun, Sergio's, Nuvio Web and Penombre.",
 	"license": "MIT",
 	"repository": {
@@ -38,6 +38,18 @@
 			"types": "./dist/password.d.ts",
 			"default": "./dist/password.js"
 		},
+		"./server/logger": {
+			"types": "./dist/server/logger.d.ts",
+			"default": "./dist/server/logger.js"
+		},
+		"./server/telemetry": {
+			"types": "./dist/server/telemetry.d.ts",
+			"default": "./dist/server/telemetry.js"
+		},
+		"./server/hooks": {
+			"types": "./dist/server/hooks.d.ts",
+			"default": "./dist/server/hooks.js"
+		},
 		"./haptics": {
 			"types": "./dist/haptics.d.ts",
 			"default": "./dist/haptics.js"
@@ -46,6 +58,10 @@
 			"types": "./dist/page-title.svelte.d.ts",
 			"svelte": "./dist/page-title.svelte.js"
 		},
+		"./components/*": {
+			"types": "./dist/components/kit/*.svelte.d.ts",
+			"svelte": "./dist/components/kit/*.svelte"
+		},
 		"./blocks/*": {
 			"types": "./dist/components/blocks/*.svelte.d.ts",
 			"svelte": "./dist/components/blocks/*.svelte"
@@ -72,13 +88,32 @@
 		"prepare": "svelte-kit sync || true && prek install --allow-missing-config || true"
 	},
 	"peerDependencies": {
+		"@opentelemetry/context-async-hooks": "^3.0.0",
+		"@opentelemetry/exporter-trace-otlp-proto": "^0.300.0",
+		"@opentelemetry/resources": "^3.0.0",
+		"@opentelemetry/sdk-trace": "^3.0.0",
 		"@sveltejs/kit": "^3.0.0",
 		"svelte": "^5.57.0",
 		"tailwindcss": "^4.3.0"
 	},
+	"peerDependenciesMeta": {
+		"@opentelemetry/context-async-hooks": {
+			"optional": true
+		},
+		"@opentelemetry/exporter-trace-otlp-proto": {
+			"optional": true
+		},
+		"@opentelemetry/resources": {
+			"optional": true
+		},
+		"@opentelemetry/sdk-trace": {
+			"optional": true
+		}
+	},
 	"dependencies": {
 		"@internationalized/date": "^3.12.4",
 		"@lucide/svelte": "^1.64.0",
+		"@opentelemetry/api": "^1.10.0",
 		"bits-ui": "^2.20.2",
 		"cn": "^0.5.0",
 		"mode-watcher": "^1.1.0",
@@ -92,6 +127,10 @@
 		"@happy-dom/global-registrator": "21.0.4",
 		"@j178/prek": "0.5.7",
 		"@modelcontextprotocol/sdk": "1.32.2",
+		"@opentelemetry/context-async-hooks": "3.0.0",
+		"@opentelemetry/exporter-trace-otlp-proto": "0.300.0",
+		"@opentelemetry/resources": "3.0.0",
+		"@opentelemetry/sdk-trace": "3.0.0",
 		"@sveltejs/adapter-bun": "1.0.0",
 		"@sveltejs/kit": "3.1.0",
 		"@sveltejs/package": "3.0.1",