fimo-react 0.21.0-experimental.1

package/dist/runtime/react/primitives/renderers/RichTextRenderer.js

@@ -0,0 +1,135 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Fragment } from 'react';
+function DefaultParagraph({ children }) {
+    return _jsx("p", { children: children });
+}
+function DefaultHeading({ node, children }) {
+    const level = node.attrs?.level ?? 1;
+    const Tag = `h${level}`;
+    return _jsx(Tag, { children: children });
+}
+function DefaultBulletList({ children }) {
+    return _jsx("ul", { children: children });
+}
+function DefaultOrderedList({ children }) {
+    return _jsx("ol", { children: children });
+}
+function DefaultListItem({ children }) {
+    return _jsx("li", { children: children });
+}
+function DefaultBlockquote({ children }) {
+    return _jsx("blockquote", { children: children });
+}
+function DefaultCodeBlock({ children }) {
+    return (_jsx("pre", { children: _jsx("code", { children: children }) }));
+}
+function DefaultHorizontalRule() {
+    return _jsx("hr", {});
+}
+function DefaultHardBreak() {
+    return _jsx("br", {});
+}
+function DefaultImage({ node }) {
+    const src = node.attrs?.src;
+    const alt = node.attrs?.alt ?? '';
+    return _jsx("img", { src: src, alt: alt });
+}
+function DefaultIframe({ node }) {
+    const src = node.attrs?.src;
+    return (_jsx("div", { style: {
+            position: 'relative',
+            width: '100%',
+            paddingBottom: '56.25%',
+            borderRadius: '0.375rem',
+            overflow: 'hidden',
+        }, children: _jsx("iframe", { src: src, style: { position: 'absolute', top: 0, left: 0, width: '100%', height: '100%', border: 0 }, allowFullScreen: true }) }));
+}
+function DefaultTable({ children }) {
+    return (_jsx("table", { className: "border-border w-full border-collapse border", children: _jsx("tbody", { children: children }) }));
+}
+function DefaultTableRow({ children }) {
+    return _jsx("tr", { className: "border-border border-b last:border-b-0", children: children });
+}
+function DefaultTableCell({ children }) {
+    return _jsx("td", { className: "border-border border px-3 py-2 align-top", children: children });
+}
+function DefaultTableHeader({ children }) {
+    return _jsx("th", { className: "border-border bg-muted border px-3 py-2 text-left align-top font-semibold", children: children });
+}
+function DefaultBold({ children }) {
+    return _jsx("strong", { children: children });
+}
+function DefaultItalic({ children }) {
+    return _jsx("em", { children: children });
+}
+function DefaultUnderline({ children }) {
+    return _jsx("u", { children: children });
+}
+function DefaultStrike({ children }) {
+    return _jsx("s", { children: children });
+}
+function DefaultCode({ children }) {
+    return _jsx("code", { children: children });
+}
+function DefaultLink({ mark, children }) {
+    const href = mark.attrs?.href;
+    const target = mark.attrs?.target;
+    const rel = mark.attrs?.rel;
+    return (_jsx("a", { href: href, target: target, rel: rel, children: children }));
+}
+const DEFAULT_NODES = {
+    paragraph: DefaultParagraph,
+    heading: DefaultHeading,
+    bulletList: DefaultBulletList,
+    orderedList: DefaultOrderedList,
+    listItem: DefaultListItem,
+    blockquote: DefaultBlockquote,
+    codeBlock: DefaultCodeBlock,
+    horizontalRule: DefaultHorizontalRule,
+    hardBreak: DefaultHardBreak,
+    image: DefaultImage,
+    table: DefaultTable,
+    tableRow: DefaultTableRow,
+    tableCell: DefaultTableCell,
+    tableHeader: DefaultTableHeader,
+    iframe: DefaultIframe,
+};
+const DEFAULT_MARKS = {
+    bold: DefaultBold,
+    strong: DefaultBold,
+    italic: DefaultItalic,
+    em: DefaultItalic,
+    underline: DefaultUnderline,
+    strike: DefaultStrike,
+    code: DefaultCode,
+    link: DefaultLink,
+};
+function renderNode(node, components, key) {
+    if (node.type === 'text') {
+        let result = node.text ?? '';
+        if (node.marks) {
+            for (const mark of node.marks) {
+                const MarkComponent = components?.[mark.type] ?? DEFAULT_MARKS[mark.type];
+                if (MarkComponent) {
+                    result = _jsx(MarkComponent, { mark: mark, children: result });
+                }
+            }
+        }
+        return _jsx(Fragment, { children: result }, key);
+    }
+    const children = node.content?.map((child, index) => renderNode(child, components, index)) ?? null;
+    if (node.type === 'doc') {
+        return _jsx(Fragment, { children: children }, key);
+    }
+    const NodeComponent = components?.[node.type] ?? DEFAULT_NODES[node.type];
+    if (NodeComponent) {
+        return (_jsx(NodeComponent, { node: node, children: children }, key));
+    }
+    return _jsx(Fragment, { children: children }, key);
+}
+export function RichTextRenderer({ document, source, components, elementRef, ...props }) {
+    if (!document) {
+        return null;
+    }
+    return (_jsx("div", { ref: elementRef, ...props, "data-fimo-source": source, "data-fimo-richtext": "", children: renderNode(document, components, 0) }));
+}

package/dist/runtime/react/primitives/renderers/StaticImage.d.ts

@@ -0,0 +1,35 @@
+import type { StaticImageProps } from '../contracts.js';
+export type { StaticImageProps } from '../contracts.js';
+/**
+ * Optimized image component for non-schema images.
+ *
+ * Use `StaticImage` for images that don't come from the database —
+ * decorative images, hardcoded URLs, generated assets, or any image
+ * where you have a direct URL string rather than a `FimoMedia` value
+ * from schema hooks.
+ *
+ * Provides the same Cloudflare Image Resizing optimization as `<Image>`
+ * (responsive srcset, quality, format=auto) but without requiring a
+ * `FimoMedia` instance or database source tracking.
+ *
+ * For schema-backed media, use `<Image value={post.cover} />` instead.
+ *
+ * @example
+ * // Basic usage
+ * <StaticImage src="/images/hero.jpg" alt="Hero background" width={1200} height={630} />
+ *
+ * // With Cloudflare optimization
+ * <StaticImage src="https://...fimo.site/uploads/photo.jpg" alt="Team" width={800} fit="cover" />
+ *
+ * // Responsive mode
+ * <StaticImage
+ *   src="https://...fimo.site/uploads/banner.jpg"
+ *   alt="Banner"
+ *   sizes="(max-width: 768px) 100vw, 50vw"
+ * />
+ *
+ * // Skip optimization
+ * <StaticImage src="/images/logo.svg" alt="Logo" unoptimized />
+ */
+export declare function StaticImage(props: StaticImageProps): import("react/jsx-runtime").JSX.Element | null;
+//# sourceMappingURL=StaticImage.d.ts.map

package/dist/runtime/react/primitives/renderers/StaticImage.js

@@ -0,0 +1,58 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { resolveImagePresentation } from 'fimo/primitives';
+/**
+ * Optimized image component for non-schema images.
+ *
+ * Use `StaticImage` for images that don't come from the database —
+ * decorative images, hardcoded URLs, generated assets, or any image
+ * where you have a direct URL string rather than a `FimoMedia` value
+ * from schema hooks.
+ *
+ * Provides the same Cloudflare Image Resizing optimization as `<Image>`
+ * (responsive srcset, quality, format=auto) but without requiring a
+ * `FimoMedia` instance or database source tracking.
+ *
+ * For schema-backed media, use `<Image value={post.cover} />` instead.
+ *
+ * @example
+ * // Basic usage
+ * <StaticImage src="/images/hero.jpg" alt="Hero background" width={1200} height={630} />
+ *
+ * // With Cloudflare optimization
+ * <StaticImage src="https://...fimo.site/uploads/photo.jpg" alt="Team" width={800} fit="cover" />
+ *
+ * // Responsive mode
+ * <StaticImage
+ *   src="https://...fimo.site/uploads/banner.jpg"
+ *   alt="Banner"
+ *   sizes="(max-width: 768px) 100vw, 50vw"
+ * />
+ *
+ * // Skip optimization
+ * <StaticImage src="/images/logo.svg" alt="Logo" unoptimized />
+ */
+export function StaticImage(props) {
+    const { src, alt, quality, unoptimized = false, fit, width, height, srcSet: srcSetOverride, sizes, style, hostSuffixes, ...imgProps } = props;
+    if (!src) {
+        return null;
+    }
+    const image = resolveImagePresentation({
+        src,
+        alt,
+        quality,
+        fit,
+        unoptimized,
+        width,
+        height,
+        sizes,
+        srcSet: srcSetOverride,
+        hostSuffixes,
+    });
+    const finalStyle = style?.objectFit
+        ? style
+        : {
+            ...style,
+            objectFit: image.objectFit,
+        };
+    return (_jsx("img", { src: image.src, alt: image.alt, width: image.width, height: image.height, style: finalStyle, sizes: image.sizes, srcSet: image.srcSet, ...imgProps }));
+}

package/dist/runtime/react/primitives/renderers/VideoRenderer.d.ts

@@ -0,0 +1,8 @@
+import { type RefObject } from 'react';
+import type { VideoProps } from '../contracts.js';
+interface VideoRendererProps extends VideoProps {
+    elementRef?: RefObject<HTMLElement | null>;
+}
+export declare function VideoRenderer({ value: media, children, overrideSrc, autoPlay, loop, muted, playsInline, style, elementRef, ...videoProps }: VideoRendererProps): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=VideoRenderer.d.ts.map

package/dist/runtime/react/primitives/renderers/VideoRenderer.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { FIMO_SOURCE } from 'fimo/primitives';
+export function VideoRenderer({ value: media, children, overrideSrc, autoPlay = true, loop = true, muted = true, playsInline = true, style, elementRef, ...videoProps }) {
+    const mediaSource = media[FIMO_SOURCE];
+    if (children) {
+        return (_jsx("span", { ref: elementRef, "data-fimo-source": mediaSource, children: children(media) }));
+    }
+    const finalSrc = overrideSrc ?? media.url;
+    return (_jsx("video", { ref: elementRef, src: finalSrc, width: media.width, height: media.height, autoPlay: autoPlay, loop: loop, muted: muted, playsInline: playsInline, style: style, ...videoProps, "data-fimo-source": mediaSource }));
+}

package/dist/runtime/react/useFimoLiveValue.d.ts

@@ -0,0 +1,20 @@
+import { type RefObject } from 'react';
+/**
+ * useFimoLiveValue — mirror a Fimo value into React state so live edits
+ * coming from the Fimo preview editor flow through reconciliation instead
+ * of mutating the DOM directly.
+ *
+ * In dev mode (editor): the hook subscribes to `fimo:live-edit` CustomEvents
+ * on the returned ref, tags the element with `data-fimo-live-edit` so the
+ * preview knows to dispatch events instead of falling back to raw DOM writes,
+ * and updates internal state when a mutation arrives.
+ *
+ * The hook is framework-adapter-neutral: Vite and Next.js clients render the
+ * same React primitives, and environments that never dispatch
+ * `fimo:live-edit` simply keep mirroring the external value.
+ */
+export declare function useFimoLiveValue<T, E extends HTMLElement = HTMLElement>(external: T): {
+    value: T;
+    ref: RefObject<E | null>;
+};
+//# sourceMappingURL=useFimoLiveValue.d.ts.map

package/dist/runtime/react/useFimoLiveValue.js

@@ -0,0 +1,43 @@
+import { useEffect, useRef, useState } from 'react';
+/**
+ * useFimoLiveValue — mirror a Fimo value into React state so live edits
+ * coming from the Fimo preview editor flow through reconciliation instead
+ * of mutating the DOM directly.
+ *
+ * In dev mode (editor): the hook subscribes to `fimo:live-edit` CustomEvents
+ * on the returned ref, tags the element with `data-fimo-live-edit` so the
+ * preview knows to dispatch events instead of falling back to raw DOM writes,
+ * and updates internal state when a mutation arrives.
+ *
+ * The hook is framework-adapter-neutral: Vite and Next.js clients render the
+ * same React primitives, and environments that never dispatch
+ * `fimo:live-edit` simply keep mirroring the external value.
+ */
+export function useFimoLiveValue(external) {
+    const ref = useRef(null);
+    const [value, setValue] = useState(external);
+    const externalRef = useRef(external);
+    if (externalRef.current !== external) {
+        externalRef.current = external;
+        setValue(external);
+    }
+    useEffect(() => {
+        const el = ref.current;
+        if (!el) {
+            return;
+        }
+        el.setAttribute('data-fimo-live-edit', '1');
+        const handler = (event) => {
+            const detail = event.detail;
+            if (detail !== undefined) {
+                setValue(detail);
+            }
+        };
+        el.addEventListener('fimo:live-edit', handler);
+        return () => {
+            el.removeEventListener('fimo:live-edit', handler);
+            el.removeAttribute('data-fimo-live-edit');
+        };
+    }, []);
+    return { value, ref };
+}

package/dist/runtime/vite/Label.d.ts

@@ -0,0 +1,13 @@
+import type { ElementType } from 'react';
+import type { LabelProps } from '../react/primitives/contracts.js';
+export type { LabelProps } from '../react/primitives/contracts.js';
+/**
+ * Render one editable label from the Vite/React Router label context.
+ *
+ * For attributes, metadata, and composed strings, use `useLabels().t()`.
+ *
+ * @example
+ * <Label value="hero.title" as="h1" />
+ */
+export declare function Label<T extends ElementType = 'span'>({ value, ...props }: LabelProps<T>): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=Label.d.ts.map

package/dist/runtime/vite/Label.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Text } from '../react/primitives/editable/Text.js';
+import { useLabels } from './translations.js';
+/**
+ * Render one editable label from the Vite/React Router label context.
+ *
+ * For attributes, metadata, and composed strings, use `useLabels().t()`.
+ *
+ * @example
+ * <Label value="hero.title" as="h1" />
+ */
+export function Label({ value, ...props }) {
+    const { t } = useLabels();
+    const textProps = { ...props, value: t(value) };
+    return _jsx(Text, { ...textProps });
+}

package/dist/runtime/vite/__fixtures__/virtual-translations.d.ts

@@ -0,0 +1,5 @@
+export declare const dictionaries: Record<string, Record<string, string>>;
+export declare const defaultLocale = "en";
+export declare const signature = "fixture";
+export declare const updatedAt: string | null;
+//# sourceMappingURL=virtual-translations.d.ts.map

package/dist/runtime/vite/__fixtures__/virtual-translations.js

@@ -0,0 +1,6 @@
+export const dictionaries = {
+    en: { 'hero.title': 'Welcome' },
+};
+export const defaultLocale = 'en';
+export const signature = 'fixture';
+export const updatedAt = null;

package/dist/runtime/vite/primitives/Images.d.ts

@@ -0,0 +1,4 @@
+import type { ImageProps, StaticImageProps } from '../../react/primitives/contracts.js';
+export declare function Image(props: ImageProps): import("react/jsx-runtime").JSX.Element;
+export declare function StaticImage(props: StaticImageProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=Images.d.ts.map

package/dist/runtime/vite/primitives/Images.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { parseImageHostSuffixes } from 'fimo/primitives';
+import { Image as BaseImage } from '../../react/primitives/editable/Image.js';
+import { StaticImage as BaseStaticImage } from '../../react/primitives/renderers/StaticImage.js';
+const viteEnvironment = import.meta.env;
+const IMAGE_HOST_SUFFIXES = parseImageHostSuffixes(viteEnvironment?.VITE_FIMO_IMAGE_HOSTS);
+export function Image(props) {
+    return _jsx(BaseImage, { ...props, hostSuffixes: IMAGE_HOST_SUFFIXES });
+}
+export function StaticImage(props) {
+    return _jsx(BaseStaticImage, { ...props, hostSuffixes: IMAGE_HOST_SUFFIXES });
+}

package/dist/runtime/vite/translations.d.ts

@@ -0,0 +1,28 @@
+import { FimoString } from 'fimo/primitives';
+/**
+ * Hook to provide a label function (`t`).
+ *
+ * Returns FimoString with source tracking for inline editing.
+ * Use with <Text> component for rendering, or String() for escape hatch.
+ *
+ * @example
+ * const { t } = useLabels();
+ *
+ * // With Text component (recommended)
+ * <Text value={t('welcome')} />
+ *
+ * // Escape hatch for attributes
+ * <input placeholder={String(t('email.placeholder'))} />
+ */
+export declare function useLabels(): {
+    t: (fullKey: string) => FimoString;
+    locale: string;
+};
+/**
+ * Legacy alias for older projects. Prefer useLabels() in new code.
+ */
+export declare function useTranslations(): {
+    t: (fullKey: string) => FimoString;
+    locale: string;
+};
+//# sourceMappingURL=translations.d.ts.map

package/dist/runtime/vite/translations.js

@@ -0,0 +1,103 @@
+import { FimoString } from 'fimo/primitives';
+import { useSyncExternalStore } from 'react';
+import { defaultLocale as bundledDefaultLocale, dictionaries as bundledDictionaries, signature as translationSignature, updatedAt as bundledUpdatedAt, } from 'virtual:translations';
+import { useLocale } from '../i18n-context.js';
+const labelListeners = new Set();
+let labelState = {
+    dictionaries: bundledDictionaries ?? {},
+    defaultLocale: bundledDefaultLocale || 'en',
+    signature: translationSignature,
+    updatedAt: bundledUpdatedAt ?? null,
+};
+function subscribeLabels(listener) {
+    labelListeners.add(listener);
+    return () => {
+        labelListeners.delete(listener);
+    };
+}
+function getLabelSnapshot() {
+    return labelState;
+}
+function setLabelState(next) {
+    if (next.signature === labelState.signature) {
+        return;
+    }
+    labelState = next;
+    for (const listener of labelListeners) {
+        listener();
+    }
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function normalizeDictionaries(value) {
+    if (!isRecord(value)) {
+        return null;
+    }
+    const dictionaries = {};
+    for (const [locale, labels] of Object.entries(value)) {
+        if (!isRecord(labels)) {
+            continue;
+        }
+        dictionaries[locale] = Object.fromEntries(Object.entries(labels).filter((entry) => typeof entry[1] === 'string'));
+    }
+    return dictionaries;
+}
+function applyLabelUpdate(payload) {
+    if (!isRecord(payload)) {
+        return;
+    }
+    const dictionaries = normalizeDictionaries(payload.dictionaries);
+    if (!dictionaries) {
+        return;
+    }
+    const defaultLocale = typeof payload.defaultLocale === 'string' ? payload.defaultLocale : labelState.defaultLocale;
+    const signature = typeof payload.signature === 'string' ? payload.signature : JSON.stringify({ dictionaries, defaultLocale });
+    const updatedAt = typeof payload.updatedAt === 'string' ? payload.updatedAt : null;
+    setLabelState({ dictionaries, defaultLocale, signature, updatedAt });
+}
+// @ts-ignore - import.meta.hot is provided by Vite during development.
+if (import.meta.hot) {
+    const onLabelsUpdated = (payload) => {
+        applyLabelUpdate(payload);
+    };
+    // @ts-ignore - import.meta.hot is provided by Vite during development.
+    import.meta.hot.on('fimo:labels-updated', onLabelsUpdated);
+    // @ts-ignore - import.meta.hot is provided by Vite during development.
+    import.meta.hot.dispose(() => {
+        // @ts-ignore - import.meta.hot is provided by Vite during development.
+        import.meta.hot.off('fimo:labels-updated', onLabelsUpdated);
+    });
+}
+/**
+ * Hook to provide a label function (`t`).
+ *
+ * Returns FimoString with source tracking for inline editing.
+ * Use with <Text> component for rendering, or String() for escape hatch.
+ *
+ * @example
+ * const { t } = useLabels();
+ *
+ * // With Text component (recommended)
+ * <Text value={t('welcome')} />
+ *
+ * // Escape hatch for attributes
+ * <input placeholder={String(t('email.placeholder'))} />
+ */
+export function useLabels() {
+    const localeContext = useLocale();
+    const labels = useSyncExternalStore(subscribeLabels, getLabelSnapshot, getLabelSnapshot);
+    const t = (fullKey) => {
+        const locale = localeContext.locale || labels.defaultLocale || 'en';
+        const dictionary = labels.dictionaries[locale] ?? labels.dictionaries[labels.defaultLocale] ?? {};
+        const text = dictionary[fullKey] ?? '';
+        return new FimoString(text, `__labels.${locale}.${fullKey}.value`);
+    };
+    return { t, locale: localeContext.locale };
+}
+/**
+ * Legacy alias for older projects. Prefer useLabels() in new code.
+ */
+export function useTranslations() {
+    return useLabels();
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "fimo-react",
+  "version": "0.21.0-experimental.1",
+  "description": "Fimo React runtime: content clients, labels, and source-tracked primitives.",
+  "files": [
+    "dist/",
+    "!dist/**/*.d.ts.map",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js"
+    },
+    "./primitives": {
+      "types": "./dist/runtime/primitives.d.ts",
+      "import": "./dist/runtime/primitives.js"
+    },
+    "./primitives/server": {
+      "types": "./dist/runtime/primitives-server.d.ts",
+      "import": "./dist/runtime/primitives-server.js"
+    },
+    "./content": {
+      "types": "./dist/runtime/content/index.d.ts",
+      "import": "./dist/runtime/content/index.js"
+    },
+    "./internal": {
+      "types": "./dist/runtime/internal.d.ts",
+      "import": "./dist/runtime/internal.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.json",
+    "check:types": "tsc -b tsconfig.json --noEmit",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@fimo/tsconfig": "0.21.0-experimental.1",
+    "@tanstack/react-query": "^5.80.6",
+    "@types/node": "^22.15.29",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "fimo": "0.21.0-experimental.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "typescript": "7.0.2",
+    "vite": "^8.0.13",
+    "vitest": "^4.1.6"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.80.6",
+    "fimo": ">=0.14.0",
+    "react": "^18.2.0 || ^19.0.0",
+    "react-dom": "^18.2.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/react-query": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20.12.0"
+  }
+}