@chidchanun/bcp 0.1.0

package/packages/client/src/index.tsx

@@ -0,0 +1,57 @@
+import "./persistent-layout-runtime.js";
+
+export {
+    Link,
+    navigate,
+    useRouter,
+    type LinkProps,
+    type NavigationOptions,
+    type Router,
+} from "./router-v2.js";
+
+export {
+    useNavigation,
+    type NavigationState,
+} from "./navigation-state.js";
+
+export {
+    createIsland,
+    type BcpIslandMetadata,
+    type IslandComponent,
+    type IslandHydrationStrategy,
+    type IslandOptions,
+    type IslandPrefetchStrategy,
+} from "./islands.js";
+
+export {
+    isNotFoundError,
+    notFound,
+    type BcpNotFoundError,
+} from "./not-found.js";
+
+export {
+    BcpRouteErrorBoundary,
+    type BcpErrorComponentProps,
+    type BcpRouteErrorBoundaryProps,
+} from "./error-boundary.js";
+
+export {
+    applyResolvedMetadata,
+    createMetadataHeadEntries,
+    type GenerateMetadata,
+    type GenerateMetadataContext,
+    type Metadata,
+    type MetadataAlternates,
+    type MetadataHeadEntry,
+    type MetadataIcons,
+    type MetadataOpenGraph,
+    type MetadataRobots,
+    type MetadataRouteParam,
+    type ResolvedMetadata,
+    type ResolvedMetadataIcons,
+    type ResolvedMetadataOpenGraph,
+} from "./metadata.js";
+
+export type {
+    HydrationMode,
+} from "./hydration.js";

package/packages/client/src/islands.tsx

@@ -0,0 +1,315 @@
+import {
+    createElement,
+    type ComponentType,
+    type ReactElement,
+} from "react";
+
+export type IslandHydrationStrategy =
+    | "load"
+    | "idle"
+    | "visible"
+    | "media";
+
+export type IslandPrefetchStrategy =
+    | "none"
+    | "idle"
+    | "visible"
+    | "interaction";
+
+export interface IslandOptions {
+    hydrate?: IslandHydrationStrategy;
+    media?: string;
+    prefetch?: IslandPrefetchStrategy;
+    preload?: boolean;
+}
+
+export interface BcpIslandMetadata<
+    Props extends object
+> {
+    id: string;
+    component: ComponentType<Props>;
+    hydrate: IslandHydrationStrategy;
+    media: string | null;
+    prefetch: IslandPrefetchStrategy;
+    preload: boolean;
+}
+
+export type IslandComponent<
+    Props extends object
+> = ComponentType<Props> & {
+    __BCP_ISLAND__:
+        BcpIslandMetadata<Props>;
+};
+
+export function createIsland<
+    Props extends object
+>(
+    id: string,
+    Component: ComponentType<Props>,
+    options: IslandOptions = {}
+): IslandComponent<Props> {
+    assertIslandId(
+        id
+    );
+
+    const loading =
+        resolveIslandOptions(
+            id,
+            options
+        );
+
+    function Island(
+        props: Props
+    ): ReactElement {
+        const serializedProps =
+            serializeIslandProps(
+                props,
+                id
+            );
+
+        return createElement(
+            "div",
+            {
+                "data-bcp-island":
+                    id,
+                "data-bcp-island-props":
+                    serializedProps,
+                "data-bcp-island-hydrate":
+                    loading.hydrate,
+                "data-bcp-island-prefetch":
+                    loading.prefetch,
+                "data-bcp-island-preload":
+                    loading.preload
+                        ? "true"
+                        : "false",
+                ...(
+                    loading.media
+                        ? {
+                            "data-bcp-island-media":
+                                loading.media,
+                        }
+                        : {}
+                ),
+            },
+            createElement(
+                Component,
+                props
+            )
+        );
+    }
+
+    const island =
+        Island as
+        IslandComponent<Props>;
+
+    island.__BCP_ISLAND__ = {
+        id,
+        component:
+            Component,
+        hydrate:
+            loading.hydrate,
+        media:
+            loading.media,
+        prefetch:
+            loading.prefetch,
+        preload:
+            loading.preload,
+    };
+
+    return island;
+}
+
+function resolveIslandOptions(
+    islandId: string,
+    options: IslandOptions
+): {
+    hydrate: IslandHydrationStrategy;
+    media: string | null;
+    prefetch: IslandPrefetchStrategy;
+    preload: boolean;
+} {
+    const hydrate =
+        options.hydrate ??
+        "load";
+
+    if (
+        hydrate !== "load" &&
+        hydrate !== "idle" &&
+        hydrate !== "visible" &&
+        hydrate !== "media"
+    ) {
+        throw new Error(
+            `BCP Framework: island "${islandId}" has an invalid hydration strategy.`
+        );
+    }
+
+    const prefetch =
+        options.prefetch ??
+        "none";
+
+    if (
+        prefetch !== "none" &&
+        prefetch !== "idle" &&
+        prefetch !== "visible" &&
+        prefetch !== "interaction"
+    ) {
+        throw new Error(
+            `BCP Framework: island "${islandId}" has an invalid prefetch strategy.`
+        );
+    }
+
+    const media =
+        options.media?.trim() ??
+        "";
+
+    if (
+        hydrate === "media"
+    ) {
+        if (!media) {
+            throw new Error(
+                `BCP Framework: island "${islandId}" uses hydrate: "media" and requires a non-empty media query.`
+            );
+        }
+    } else if (media) {
+        throw new Error(
+            `BCP Framework: island "${islandId}" defines a media query but hydrate is "${hydrate}". Use hydrate: "media".`
+        );
+    }
+
+    return {
+        hydrate,
+        media:
+            hydrate === "media"
+                ? media
+                : null,
+        prefetch,
+        preload:
+            options.preload ??
+            hydrate === "load",
+    };
+}
+
+function assertIslandId(
+    id: string
+): void {
+    if (
+        !/^[A-Za-z][A-Za-z0-9._-]*$/.test(
+            id
+        )
+    ) {
+        throw new Error(
+            `BCP Framework: island id "${id}" is invalid. Use letters, numbers, dots, underscores, or hyphens, and start with a letter.`
+        );
+    }
+}
+
+function serializeIslandProps(
+    props: object,
+    islandId: string
+): string {
+    assertSerializable(
+        props,
+        `island "${islandId}" props`,
+        new Set<object>()
+    );
+
+    const serialized =
+        JSON.stringify(
+            props
+        );
+
+    if (
+        typeof serialized !==
+        "string"
+    ) {
+        throw new Error(
+            `BCP Framework: island "${islandId}" props could not be serialized.`
+        );
+    }
+
+    return serialized;
+}
+
+function assertSerializable(
+    value: unknown,
+    path: string,
+    seen: Set<object>
+): void {
+    if (
+        value === null ||
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean"
+    ) {
+        return;
+    }
+
+    if (
+        typeof value === "undefined" ||
+        typeof value === "function" ||
+        typeof value === "symbol" ||
+        typeof value === "bigint"
+    ) {
+        throw new Error(
+            `BCP Framework: ${path} must be JSON-serializable.`
+        );
+    }
+
+    if (
+        typeof value !== "object"
+    ) {
+        return;
+    }
+
+    if (
+        seen.has(
+            value
+        )
+    ) {
+        throw new Error(
+            `BCP Framework: ${path} contains a circular reference.`
+        );
+    }
+
+    seen.add(
+        value
+    );
+
+    if (
+        Array.isArray(
+            value
+        )
+    ) {
+        value.forEach(
+            (
+                item,
+                index
+            ) =>
+                assertSerializable(
+                    item,
+                    `${path}[${index}]`,
+                    seen
+                )
+        );
+    } else {
+        for (
+            const [
+                key,
+                item,
+            ]
+            of Object.entries(
+                value
+            )
+        ) {
+            assertSerializable(
+                item,
+                `${path}.${key}`,
+                seen
+            );
+        }
+    }
+
+    seen.delete(
+        value
+    );
+}

package/packages/client/src/metadata.ts

@@ -0,0 +1,281 @@
+export interface MetadataRobots {
+    index?: boolean;
+    follow?: boolean;
+    noarchive?: boolean;
+    nosnippet?: boolean;
+    noimageindex?: boolean;
+}
+
+export interface MetadataOpenGraph {
+    title?: string;
+    description?: string;
+    url?: string;
+    type?: string;
+    siteName?: string;
+    images?: string | string[];
+}
+
+export interface MetadataIcons {
+    icon?: string;
+    shortcut?: string;
+    apple?: string;
+}
+
+export interface MetadataAlternates {
+    canonical?: string;
+}
+
+export interface Metadata {
+    title?: string;
+    description?: string;
+    robots?: string | MetadataRobots;
+    alternates?: MetadataAlternates;
+    openGraph?: MetadataOpenGraph;
+    icons?: string | MetadataIcons;
+}
+
+export interface ResolvedMetadataOpenGraph {
+    title: string | null;
+    description: string | null;
+    url: string | null;
+    type: string | null;
+    siteName: string | null;
+    images: string[];
+}
+
+export interface ResolvedMetadataIcons {
+    icon: string | null;
+    shortcut: string | null;
+    apple: string | null;
+}
+
+export interface ResolvedMetadata {
+    title: string;
+    description: string | null;
+    robots: string | null;
+    canonical: string | null;
+    openGraph: ResolvedMetadataOpenGraph | null;
+    icons: ResolvedMetadataIcons;
+}
+
+export type MetadataRouteParam =
+    | string
+    | string[]
+    | undefined;
+
+export interface GenerateMetadataContext {
+    params: Record<
+        string,
+        MetadataRouteParam
+    >;
+    parent: ResolvedMetadata;
+}
+
+export type GenerateMetadata = (
+    context: GenerateMetadataContext
+) => Metadata | Promise<Metadata>;
+
+export interface MetadataHeadEntry {
+    tag: "meta" | "link";
+    key: string;
+    attributes: Record<string, string>;
+}
+
+export function createMetadataHeadEntries(
+    metadata: ResolvedMetadata
+): MetadataHeadEntry[] {
+    const entries: MetadataHeadEntry[] = [];
+
+    if (metadata.description) {
+        entries.push({
+            tag: "meta",
+            key: "description",
+            attributes: {
+                name: "description",
+                content: metadata.description,
+            },
+        });
+    }
+
+    if (metadata.robots) {
+        entries.push({
+            tag: "meta",
+            key: "robots",
+            attributes: {
+                name: "robots",
+                content: metadata.robots,
+            },
+        });
+    }
+
+    if (metadata.canonical) {
+        entries.push({
+            tag: "link",
+            key: "canonical",
+            attributes: {
+                rel: "canonical",
+                href: metadata.canonical,
+            },
+        });
+    }
+
+    if (metadata.openGraph) {
+        const openGraph = metadata.openGraph;
+
+        pushProperty(
+            entries,
+            "og:title",
+            openGraph.title
+        );
+        pushProperty(
+            entries,
+            "og:description",
+            openGraph.description
+        );
+        pushProperty(
+            entries,
+            "og:url",
+            openGraph.url
+        );
+        pushProperty(
+            entries,
+            "og:type",
+            openGraph.type
+        );
+        pushProperty(
+            entries,
+            "og:site_name",
+            openGraph.siteName
+        );
+
+        openGraph.images.forEach(
+            (image, index) => {
+                entries.push({
+                    tag: "meta",
+                    key: `og:image:${index}`,
+                    attributes: {
+                        property: "og:image",
+                        content: image,
+                    },
+                });
+            }
+        );
+    }
+
+    pushLink(
+        entries,
+        "icon",
+        "icon",
+        metadata.icons.icon
+    );
+    pushLink(
+        entries,
+        "shortcut-icon",
+        "shortcut icon",
+        metadata.icons.shortcut
+    );
+    pushLink(
+        entries,
+        "apple-touch-icon",
+        "apple-touch-icon",
+        metadata.icons.apple
+    );
+
+    return entries;
+}
+
+export function applyResolvedMetadata(
+    metadata: ResolvedMetadata
+): void {
+    if (
+        typeof document ===
+        "undefined"
+    ) {
+        return;
+    }
+
+    document.title =
+        metadata.title;
+
+    document
+        .head
+        .querySelectorAll(
+            "[data-bcp-metadata]"
+        )
+        .forEach(
+            (element) =>
+                element.remove()
+        );
+
+    for (
+        const entry
+        of createMetadataHeadEntries(
+            metadata
+        )
+    ) {
+        const element =
+            document.createElement(
+                entry.tag
+            );
+
+        element.setAttribute(
+            "data-bcp-metadata",
+            entry.key
+        );
+
+        for (
+            const [name, value]
+            of Object.entries(
+                entry.attributes
+            )
+        ) {
+            element.setAttribute(
+                name,
+                value
+            );
+        }
+
+        document.head.appendChild(
+            element
+        );
+    }
+}
+
+function pushProperty(
+    entries: MetadataHeadEntry[],
+    property: string,
+    value: string | null
+): void {
+    if (!value) {
+        return;
+    }
+
+    entries.push({
+        tag: "meta",
+        key: property,
+        attributes: {
+            property,
+            content: value,
+        },
+    });
+}
+
+function pushLink(
+    entries: MetadataHeadEntry[],
+    key: string,
+    rel: string,
+    href: string | null
+): void {
+    if (!href) {
+        return;
+    }
+
+    entries.push({
+        tag: "link",
+        key,
+        attributes: {
+            rel,
+            href,
+        },
+    });
+}

package/packages/client/src/navigation-loading.ts

@@ -0,0 +1,52 @@
+const LOADING_ELEMENT_ID =
+    "__bcp_navigation_loading__";
+
+export function showNavigationLoading(
+    html: string | null | undefined
+): void {
+    hideNavigationLoading();
+
+    if (
+        typeof document === "undefined" ||
+        !html
+    ) {
+        return;
+    }
+
+    const container =
+        document.createElement(
+            "div"
+        );
+
+    container.id =
+        LOADING_ELEMENT_ID;
+
+    container.dataset.bcpNavigationLoading =
+        "true";
+
+    container.setAttribute(
+        "aria-live",
+        "polite"
+    );
+
+    container.innerHTML =
+        html;
+
+    document.body.appendChild(
+        container
+    );
+}
+
+export function hideNavigationLoading(): void {
+    if (
+        typeof document === "undefined"
+    ) {
+        return;
+    }
+
+    document
+        .getElementById(
+            LOADING_ELEMENT_ID
+        )
+        ?.remove();
+}