@wrikka/solid-framework 0.0.0-stage → 0.15.0

package/src/devtools/shared/types/result.ts

@@ -0,0 +1,53 @@
+/**
+ * Result type for error handling
+ * Represents either a success (Ok) or failure (Err)
+ */
+export type Result<T, E = Error> =
+	| { readonly ok: true; readonly value: T }
+	| { readonly ok: false; readonly error: E };
+
+/**
+ * Create a successful Result
+ */
+export const ok = <T, E = Error>(value: T): Result<T, E> => ({
+	ok: true,
+	value,
+});
+
+/**
+ * Create a failed Result
+ */
+export const err = <T, E = Error>(error: E): Result<T, E> => ({
+	ok: false,
+	error,
+});
+
+/**
+ * Map over the success value
+ */
+export const mapResult = <T, U, E>(
+	result: Result<T, E>,
+	fn: (value: T) => U,
+): Result<U, E> => (result.ok ? ok(fn(result.value)) : result);
+
+/**
+ * Chain operations, short-circuiting on error
+ */
+export const chain = <T, U, E>(
+	result: Result<T, E>,
+	fn: (value: T) => Result<U, E>,
+): Result<U, E> => (result.ok ? fn(result.value) : result);
+
+/**
+ * Get value or throw error
+ */
+export const unwrap = <T, E>(result: Result<T, E>): T => {
+	if (result.ok) return result.value;
+	throw result.error;
+};
+
+/**
+ * Get value or default
+ */
+export const unwrapOr = <T, E>(result: Result<T, E>, defaultValue: T): T =>
+	result.ok ? result.value : defaultValue;

package/src/devtools/shared/utils/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Pure utility functions
+ */
+
+/**
+ * Identity function
+ */
+export const identity = <T>(x: T): T => x;
+
+/**
+ * Constant function
+ */
+export const constant =
+	<T>(value: T) =>
+	() =>
+		value;
+
+/**
+ * Compose functions
+ */
+export const compose =
+	<T, U, V>(f: (x: U) => V, g: (x: T) => U) =>
+	(x: T): V =>
+		f(g(x));
+
+/**
+ * Pipe functions (left-to-right composition)
+ */
+export const pipe =
+	<T, U, V>(g: (x: T) => U, f: (x: U) => V) =>
+	(x: T): V =>
+		f(g(x));

package/src/devtools/style.css

@@ -0,0 +1,2 @@
+/* @unocss all - UnoCSS directive */
+

package/src/head/index.ts

@@ -0,0 +1,5 @@
+// Public API - @wrikka/solid-framework/head
+
+export * from "./modules/head";
+export * from "./presentation";
+export * from "./types";

package/src/head/modules/head/application/index.ts

@@ -0,0 +1 @@
+export * from "./usecases";

package/src/head/modules/head/application/usecases/head-manager.ts

@@ -0,0 +1,68 @@
+/**
+ * Head Manager
+ * Collects head tags during SSR and applies them to document.head on client
+ */
+
+import { renderTags } from "#head/modules/head/domain";
+import type { HeadSink } from "#head/modules/head/ports";
+import type { HeadTag } from "#head/types";
+
+export interface HeadManager extends HeadSink {
+	tags: HeadTag[];
+	clear(): void;
+}
+
+/**
+ * SSR sink — collects tags, renders them as an HTML string for injection
+ */
+export const createHeadManager = (): HeadManager => {
+	const tags: HeadTag[] = [];
+
+	return {
+		tags,
+		add(tag: HeadTag) {
+			tags.push(tag);
+			return () => {
+				const index = tags.indexOf(tag);
+				if (index >= 0) tags.splice(index, 1);
+			};
+		},
+		renderToString: () => renderTags(tags),
+		clear() {
+			tags.length = 0;
+		},
+	};
+};
+
+const toDomNode = (tag: HeadTag): HTMLElement => {
+	const el = document.createElement(tag.type);
+	for (const [key, value] of Object.entries(tag.props)) {
+		if (value === undefined || value === false) continue;
+		if (value === true) {
+			el.setAttribute(key, "");
+		} else {
+			el.setAttribute(key, String(value));
+		}
+	}
+	if (tag.text !== undefined) el.textContent = tag.text;
+	el.setAttribute("data-solid-head", tag.key);
+	return el;
+};
+
+/**
+ * Client sink — applies tags to document.head, deduped by data attribute
+ */
+export const createDomHeadSink = (): HeadSink => ({
+	add(tag: HeadTag) {
+		if (typeof document === "undefined") return () => {};
+
+		const selector = `[data-solid-head="${CSS.escape(tag.key)}"]`;
+		const existing = document.head.querySelector(selector);
+		existing?.remove();
+
+		const el = toDomNode(tag);
+		document.head.appendChild(el);
+		return () => el.remove();
+	},
+	renderToString: () => "",
+});

package/src/head/modules/head/application/usecases/index.ts

@@ -0,0 +1 @@
+export * from "./head-manager";

package/src/head/modules/head/domain/index.ts

@@ -0,0 +1,3 @@
+export * from "./models";
+export * from "./operations";
+export * from "./validators";

package/src/head/modules/head/domain/models/head-tag.ts

@@ -0,0 +1,73 @@
+/**
+ * Head Tag Model
+ * Domain model and key derivation for deduped head tags
+ */
+
+import type {
+	HeadTag,
+	HeadTagType,
+	LinkTagProps,
+	MetaTagProps,
+} from "#head/types";
+
+const textHash = (text: string): string => {
+	let hash = 0;
+	for (let i = 0; i < text.length; i++) {
+		hash = (hash * 31 + text.charCodeAt(i)) | 0;
+	}
+	return Math.abs(hash).toString(36);
+};
+
+export const createTagKey = (
+	type: HeadTagType,
+	props: Record<string, string | boolean | undefined>,
+	text?: string,
+): string => {
+	switch (type) {
+		case "title":
+			return "title";
+		case "meta":
+			return `meta:${props.name ?? props.property ?? props.charset ?? props["http-equiv"] ?? textHash(text ?? "")}`;
+		case "link":
+			return `link:${props.rel ?? ""}:${props.href ?? ""}`;
+		default:
+			return `${type}:${props.src ?? props.href ?? textHash(text ?? JSON.stringify(props))}`;
+	}
+};
+
+export const createHeadTag = (
+	type: HeadTagType,
+	props: Record<string, string | boolean | undefined> = {},
+	text?: string,
+): HeadTag => ({
+	type,
+	props,
+	text,
+	key: createTagKey(type, props, text),
+});
+
+export const metaTag = (props: MetaTagProps): HeadTag =>
+	createHeadTag("meta", props as Record<string, string | undefined>);
+
+export const linkTag = (props: LinkTagProps): HeadTag =>
+	createHeadTag("link", props as Record<string, string | undefined>);
+
+export const titleTag = (title: string): HeadTag =>
+	createHeadTag("title", {}, title);
+
+/**
+ * Preload hints — entry chunks → `modulepreload`, styles → `stylesheet`,
+ * fonts/images via `as`. Read hrefs from the build's
+ * `preload-manifest.json` or pass explicitly:
+ *
+ *   useHead(...preloadTags(["/assets/entry.js", "/assets/app.css"]))
+ */
+export const preloadTags = (urls: string[]): HeadTag[] =>
+	urls.map((url) =>
+		url.endsWith(".css")
+			? linkTag({ rel: "stylesheet", href: url })
+			: createHeadTag("link", {
+					rel: "modulepreload",
+					href: url,
+				}),
+	);

package/src/head/modules/head/domain/models/index.ts

@@ -0,0 +1 @@
+export * from "./head-tag";

package/src/head/modules/head/domain/operations/dedupe.ts

@@ -0,0 +1,18 @@
+/**
+ * Head Tag Dedupe
+ * Last-write-wins dedupe by tag key, preserving insertion order
+ */
+
+import type { HeadTag } from "#head/types";
+
+export const dedupeTags = (tags: HeadTag[]): HeadTag[] => {
+	const order: string[] = [];
+	const byKey = new Map<string, HeadTag>();
+
+	for (const tag of tags) {
+		if (!byKey.has(tag.key)) order.push(tag.key);
+		byKey.set(tag.key, tag);
+	}
+
+	return order.map((key) => byKey.get(key) as HeadTag);
+};

package/src/head/modules/head/domain/operations/index.ts

@@ -0,0 +1,2 @@
+export * from "./dedupe";
+export * from "./render-tags";

package/src/head/modules/head/domain/operations/render-tags.ts

@@ -0,0 +1,43 @@
+/**
+ * Render Tags
+ * Turn head tags into HTML strings for SSR injection
+ */
+
+import type { HeadTag } from "#head/types";
+import { dedupeTags } from "./dedupe";
+
+const escapeHtml = (value: string): string =>
+	value
+		.replace(/&/g, "&")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;");
+
+const renderProps = (
+	props: Record<string, string | boolean | undefined>,
+): string =>
+	Object.entries(props)
+		.filter(([, value]) => value !== undefined && value !== false)
+		.map(([key, value]) =>
+			value === true ? key : `${key}="${escapeHtml(String(value))}"`,
+		)
+		.join(" ");
+
+export const renderTag = (tag: HeadTag): string => {
+	const props = renderProps(tag.props);
+	const open = props ? `<${tag.type} ${props}` : `<${tag.type}`;
+
+	switch (tag.type) {
+		case "title":
+			return `<title>${escapeHtml(tag.text ?? "")}</title>`;
+		case "script":
+			return `${open}>${tag.text ?? ""}</script>`;
+		case "style":
+			return `${open}>${tag.text ?? ""}</style>`;
+		default:
+			return `${open}>`;
+	}
+};
+
+export const renderTags = (tags: HeadTag[]): string =>
+	dedupeTags(tags).map(renderTag).join("");

package/src/head/modules/head/domain/validators/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Head Validators
+ */
+
+import type { HeadTag } from "#head/types";
+
+export const isHeadTag = (value: unknown): value is HeadTag =>
+	typeof value === "object" &&
+	value !== null &&
+	"type" in value &&
+	"key" in value &&
+	"props" in value;

package/src/head/modules/head/index.ts

@@ -0,0 +1,3 @@
+export * from "./application";
+export * from "./domain";
+export * from "./ports";

package/src/head/modules/head/ports/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Head Ports
+ * Where collected head tags are applied — SSR string buffer or live DOM
+ */
+
+import type { HeadTag } from "#head/types";
+
+export interface HeadSink {
+	add(tag: HeadTag): () => void;
+	renderToString(): string;
+}

package/src/head/presentation/HeadProvider.tsx

@@ -0,0 +1,42 @@
+/**
+ * Head Provider
+ * Supplies the head sink to tag components — SSR buffer or live DOM
+ */
+
+import { type JSX, useContext } from "solid-js";
+import { isServer } from "solid-js/web";
+import {
+	createDomHeadSink,
+	createHeadManager,
+	type HeadManager,
+} from "#head/modules/head/application/usecases";
+import type { HeadSink } from "#head/modules/head/ports";
+import { HeadContext } from "./head-context";
+
+export { HeadContext };
+
+export interface HeadProviderProps {
+	sink?: HeadSink;
+	children?: JSX.Element;
+}
+
+export const HeadProvider = (props: HeadProviderProps): JSX.Element => {
+	const sink =
+		props.sink ?? (isServer ? createHeadManager() : createDomHeadSink());
+	return (
+		<HeadContext.Provider value={sink}>{props.children}</HeadContext.Provider>
+	);
+};
+
+export const useHeadSink = (): HeadSink => {
+	const sink = useContext(HeadContext);
+	if (sink) return sink;
+	return isServer ? createHeadManager() : createDomHeadSink();
+};
+
+/**
+ * Extract the SSR head manager when running inside a provided sink.
+ * Returns undefined on the client or when the sink is a DOM sink.
+ */
+export const asHeadManager = (sink: HeadSink): HeadManager | undefined =>
+	"tags" in sink ? (sink as HeadManager) : undefined;

package/src/head/presentation/Tags.tsx

@@ -0,0 +1,90 @@
+/**
+ * Head Tag Components
+ * <Title>, <Meta>, <Link>, <Script>, <Style> — render nothing, register tags
+ */
+
+import { createRenderEffect, type JSX, onCleanup } from "solid-js";
+import {
+	createHeadTag,
+	linkTag,
+	metaTag,
+	titleTag,
+} from "#head/modules/head/domain";
+import type { HeadTag, LinkTagProps, MetaTagProps } from "#head/types";
+import { useHeadSink } from "./HeadProvider";
+
+export const useHeadTag = (tag: () => HeadTag): void => {
+	const sink = useHeadSink();
+	// createRenderEffect (not createEffect) — runs during the SSR render
+	// pass so tags are collected into the head sink before flushing
+	createRenderEffect(() => {
+		const dispose = sink.add(tag());
+		onCleanup(dispose);
+	});
+};
+
+export const Title = (props: { children: string }): JSX.Element => {
+	useHeadTag(() => titleTag(String(props.children)));
+	return null;
+};
+
+export const Meta = (props: MetaTagProps): JSX.Element => {
+	useHeadTag(() =>
+		metaTag({
+			name: props.name,
+			property: props.property,
+			content: props.content,
+			charset: props.charset,
+			"http-equiv": props["http-equiv"],
+		}),
+	);
+	return null;
+};
+
+export const Link = (props: LinkTagProps): JSX.Element => {
+	useHeadTag(() =>
+		linkTag({
+			rel: props.rel,
+			href: props.href,
+			type: props.type,
+			sizes: props.sizes,
+			as: props.as,
+			crossorigin: props.crossorigin,
+		}),
+	);
+	return null;
+};
+
+export interface ScriptTagProps {
+	src?: string;
+	type?: string;
+	async?: boolean;
+	defer?: boolean;
+	children?: string;
+}
+
+export const ScriptTag = (props: ScriptTagProps): JSX.Element => {
+	useHeadTag(() =>
+		createHeadTag(
+			"script",
+			{
+				src: props.src,
+				type: props.type,
+				async: props.async,
+				defer: props.defer,
+			},
+			typeof props.children === "string" ? props.children : undefined,
+		),
+	);
+	return null;
+};
+
+export const StyleTag = (props: {
+	type?: string;
+	children?: string;
+}): JSX.Element => {
+	useHeadTag(() =>
+		createHeadTag("style", { type: props.type }, props.children),
+	);
+	return null;
+};

package/src/head/presentation/head-context.ts

@@ -0,0 +1,11 @@
+/**
+ * Head Context
+ * Shared context object — kept in plain .ts so non-JSX callers
+ * (e.g. the routed server entry) can provide a sink without a
+ * JSX transform
+ */
+
+import { createContext } from "solid-js";
+import type { HeadSink } from "#head/modules/head/ports";
+
+export const HeadContext = createContext<HeadSink>();

package/src/head/presentation/index.ts

@@ -0,0 +1,3 @@
+export * from "./HeadProvider";
+export * from "./Tags";
+export * from "./useHead";

package/src/head/presentation/useHead.ts

@@ -0,0 +1,77 @@
+/**
+ * useHead / useSeoMeta
+ * Programmatic head management — the Nuxt-style API
+ */
+
+import { createRenderEffect, onCleanup } from "solid-js";
+import { linkTag, metaTag, titleTag } from "#head/modules/head/domain";
+import type { HeadTag, SeoMetaInput } from "#head/types";
+import { useHeadSink } from "./HeadProvider";
+
+export const useHead = (...tags: HeadTag[]): void => {
+	const sink = useHeadSink();
+	// createRenderEffect — runs during the SSR render pass so tags reach
+	// the head sink before the document head is flushed
+	createRenderEffect(() => {
+		const disposers = tags.map((tag) => sink.add(tag));
+		onCleanup(() => {
+			for (const dispose of disposers) dispose();
+		});
+	});
+};
+
+/**
+ * useHeadEffect — reactive head sink: re-runs `fn` whenever its
+ * dependencies change, replacing the tags it previously added
+ * (used by `page({ head })` for loader-data-driven meta)
+ */
+export const useHeadEffect = (fn: () => HeadTag[]): void => {
+	const sink = useHeadSink();
+	createRenderEffect(() => {
+		const disposers = fn().map((tag) => sink.add(tag));
+		onCleanup(() => {
+			for (const dispose of disposers) dispose();
+		});
+	});
+};
+
+/** SeoMetaInput → HeadTag[] — pure, shared by useSeoMeta and page head */
+export const seoTags = (input: SeoMetaInput): HeadTag[] => {
+	const tags: HeadTag[] = [];
+
+	if (input.title) tags.push(titleTag(input.title));
+	if (input.description)
+		tags.push(metaTag({ name: "description", content: input.description }));
+	if (input.keywords)
+		tags.push(metaTag({ name: "keywords", content: input.keywords }));
+	if (input.robots)
+		tags.push(metaTag({ name: "robots", content: input.robots }));
+	if (input.canonical)
+		tags.push(linkTag({ rel: "canonical", href: input.canonical }));
+
+	if (input.ogTitle)
+		tags.push(metaTag({ property: "og:title", content: input.ogTitle }));
+	if (input.ogDescription)
+		tags.push(
+			metaTag({ property: "og:description", content: input.ogDescription }),
+		);
+	if (input.ogImage)
+		tags.push(metaTag({ property: "og:image", content: input.ogImage }));
+	if (input.ogUrl)
+		tags.push(metaTag({ property: "og:url", content: input.ogUrl }));
+	if (input.ogType)
+		tags.push(metaTag({ property: "og:type", content: input.ogType }));
+
+	if (input.twitterCard)
+		tags.push(metaTag({ name: "twitter:card", content: input.twitterCard }));
+	if (input.twitterSite)
+		tags.push(metaTag({ name: "twitter:site", content: input.twitterSite }));
+	if (input.twitterImage)
+		tags.push(metaTag({ name: "twitter:image", content: input.twitterImage }));
+
+	return tags;
+};
+
+export const useSeoMeta = (input: SeoMetaInput): void => {
+	useHead(...seoTags(input));
+};

package/src/head/shared/index.ts

@@ -0,0 +1 @@
+export * from "./types";

package/src/head/shared/types/index.ts

@@ -0,0 +1,5 @@
+export interface Result<T, E = Error> {
+	success: boolean;
+	data?: T;
+	error?: E;
+}

package/src/head/types/index.ts

@@ -0,0 +1,47 @@
+/**
+ * Head Domain Types
+ * Document head management — meta, links, SEO
+ */
+
+export type HeadTagType = "title" | "meta" | "link" | "script" | "style";
+
+export interface HeadTag {
+	type: HeadTagType;
+	props: Record<string, string | boolean | undefined>;
+	text?: string;
+	/** dedupe key — later tags with the same key replace earlier ones */
+	key: string;
+}
+
+export interface MetaTagProps {
+	name?: string;
+	property?: string;
+	content?: string;
+	charset?: string;
+	"http-equiv"?: string;
+}
+
+export interface LinkTagProps {
+	rel?: string;
+	href?: string;
+	type?: string;
+	sizes?: string;
+	as?: string;
+	crossorigin?: string;
+}
+
+export interface SeoMetaInput {
+	title?: string;
+	description?: string;
+	canonical?: string;
+	keywords?: string;
+	robots?: string;
+	ogTitle?: string;
+	ogDescription?: string;
+	ogImage?: string;
+	ogUrl?: string;
+	ogType?: string;
+	twitterCard?: string;
+	twitterSite?: string;
+	twitterImage?: string;
+}

package/src/hooks/adapters/config/constants.ts

@@ -0,0 +1,12 @@
+// Configuration constants for composables module
+
+export const DEFAULT_DEBOUNCE_DELAY = 300;
+export const DEFAULT_THROTTLE_DELAY = 300;
+export const DEFAULT_INTERVAL = 1000;
+export const DEFAULT_TIMEOUT = 1000;
+
+export const STORAGE_PREFIX = "composables_";
+export const STORAGE_DEFAULT_OPTIONS = {
+	serializer: JSON.stringify,
+	deserializer: JSON.parse,
+};