arcway 0.1.0

package/client/env.js

@@ -0,0 +1,55 @@
+import { useSyncExternalStore } from 'react';
+
+const ENV_PREFIX = 'SOLO_PUBLIC_';
+const WINDOW_KEY = '__SOLO_ENV__';
+
+function collectPublicEnv() {
+  const result = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (key.startsWith(ENV_PREFIX) && value !== undefined) {
+      result[key.slice(ENV_PREFIX.length)] = value;
+    }
+  }
+  return result;
+}
+
+function buildEnvScriptTag(envVars) {
+  const keys = Object.keys(envVars);
+  if (keys.length === 0) return '';
+  const json = JSON.stringify(envVars).replace(/</g, '\\u003c');
+  return `<script id="__app_env">window.${WINDOW_KEY}=${json}</script>`;
+}
+
+function isServer() {
+  return typeof window === 'undefined';
+}
+
+function getEnvStore() {
+  if (isServer()) {
+    return collectPublicEnv();
+  }
+  return globalThis[WINDOW_KEY] ?? {};
+}
+
+function env(key) {
+  return getEnvStore()[key];
+}
+
+function subscribe(_onStoreChange) {
+  return () => {};
+}
+
+function getSnapshot() {
+  return getEnvStore();
+}
+
+function getServerSnapshot() {
+  return collectPublicEnv();
+}
+
+function useEnv(key) {
+  const store = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+  return store[key];
+}
+
+export { buildEnvScriptTag, collectPublicEnv, env, useEnv };

package/client/fetcher.js

@@ -0,0 +1,50 @@
+class ApiError extends Error {
+  status;
+  code;
+  details;
+
+  constructor(status, code, message, details) {
+    super(message);
+    this.name = 'ApiError';
+    this.status = status;
+    this.code = code;
+    this.details = details;
+  }
+}
+
+async function soloFetch(url, init) {
+  const res = await fetch(url, init);
+
+  if (res.status === 204) {
+    if (!res.ok) {
+      throw new ApiError(res.status, 'UNKNOWN', res.statusText);
+    }
+    return void 0;
+  }
+
+  let json;
+  try {
+    json = await res.json();
+  } catch {
+    if (!res.ok) {
+      throw new ApiError(res.status, 'NETWORK_ERROR', res.statusText);
+    }
+    return void 0;
+  }
+
+  if (!res.ok) {
+    if (json?.error && typeof json.error === 'object') {
+      throw new ApiError(
+        res.status,
+        json.error.code || 'UNKNOWN',
+        json.error.message || res.statusText,
+        json.error.details,
+      );
+    }
+    throw new ApiError(res.status, 'UNKNOWN', json?.message || res.statusText);
+  }
+
+  return json.data;
+}
+
+export { ApiError, soloFetch };

package/client/graphql.js

@@ -0,0 +1,35 @@
+class GraphQLError extends Error {
+  errors;
+
+  constructor(errors) {
+    super(errors[0]?.message ?? 'GraphQL Error');
+    this.name = 'GraphQLError';
+    this.errors = errors;
+  }
+}
+
+async function graphqlFetch(url, query, variables, headers) {
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      ...headers,
+    },
+    body: JSON.stringify(variables !== undefined ? { query, variables } : { query }),
+  });
+
+  let json;
+  try {
+    json = await res.json();
+  } catch {
+    throw new Error(`GraphQL request failed: ${res.status} ${res.statusText}`);
+  }
+
+  if (json.errors?.length) {
+    throw new GraphQLError(json.errors);
+  }
+
+  return json.data;
+}
+
+export { GraphQLError, graphqlFetch };

package/client/head.js

@@ -0,0 +1,140 @@
+import { useEffect, Children } from 'react';
+
+const SSR_HEAD_KEY = '__ssr_head_data__';
+
+function setSSRHeadData(data) {
+  globalThis[SSR_HEAD_KEY] = data;
+}
+
+function getSSRHeadData() {
+  return globalThis[SSR_HEAD_KEY] ?? null;
+}
+
+function clearSSRHeadData() {
+  delete globalThis[SSR_HEAD_KEY];
+}
+
+function setAttributes(el, attrs) {
+  for (const [key, val] of Object.entries(attrs)) {
+    el.setAttribute(key, val);
+  }
+}
+
+function appendElement(tag, attrs) {
+  const el = document.createElement(tag);
+  setAttributes(el, attrs);
+  document.head.appendChild(el);
+  return el;
+}
+
+function Head({ title, description, children }) {
+  const { metas, links } = extractHeadChildren(children);
+  if (description) {
+    metas.push({ name: 'description', content: description });
+  }
+
+  const headData = getSSRHeadData();
+  if (headData) {
+    if (title) headData.title = title;
+    headData.meta.push(...metas);
+    headData.links.push(...links);
+  }
+
+  useEffect(() => {
+    if (title) {
+      document.title = title;
+    }
+
+    const addedElements = [];
+
+    for (const meta of metas) {
+      const selector = meta.name
+        ? `meta[name="${meta.name}"]`
+        : meta.property
+          ? `meta[property="${meta.property}"]`
+          : null;
+
+      if (selector) {
+        const existing = document.head.querySelector(selector);
+        if (existing) {
+          setAttributes(existing, meta);
+          continue;
+        }
+      }
+
+      addedElements.push(appendElement('meta', meta));
+    }
+
+    for (const link of links) {
+      const selector =
+        link.rel && link.href ? `link[rel="${link.rel}"][href="${link.href}"]` : null;
+      if (selector) {
+        const existing = document.head.querySelector(selector);
+        if (existing) continue;
+      }
+
+      addedElements.push(appendElement('link', link));
+    }
+
+    return () => {
+      for (const el of addedElements) {
+        el.parentNode?.removeChild(el);
+      }
+    };
+  }, [title, description, ...metas.flatMap(Object.values), ...links.flatMap(Object.values)]);
+
+  return null;
+}
+
+function extractHeadChildren(children) {
+  const metas = [];
+  const links = [];
+
+  Children.forEach(children, (child) => {
+    if (!child || typeof child !== 'object') return;
+    if (!child.props) return;
+
+    const { children: _, key: __, ...props } = child.props;
+    if (child.type === 'meta') {
+      metas.push(props);
+    } else if (child.type === 'link') {
+      links.push(props);
+    }
+  });
+
+  return { metas, links };
+}
+
+function escapeHtml(value) {
+  return value
+    .replace(/&/g, '&')
+    .replace(/"/g, '"')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+function renderHeadToString(headData) {
+  const parts = [];
+
+  if (headData.title) {
+    parts.push(`<title>${escapeHtml(headData.title)}</title>`);
+  }
+
+  for (const meta of headData.meta) {
+    const attrs = Object.entries(meta)
+      .map(([k, v]) => `${k}="${escapeHtml(v)}"`)
+      .join(' ');
+    parts.push(`<meta ${attrs} />`);
+  }
+
+  for (const link of headData.links) {
+    const attrs = Object.entries(link)
+      .map(([k, v]) => `${k}="${escapeHtml(v)}"`)
+      .join(' ');
+    parts.push(`<link ${attrs} />`);
+  }
+
+  return parts.join('\n');
+}
+
+export { Head, clearSSRHeadData, extractHeadChildren, renderHeadToString, setSSRHeadData };

package/client/hooks/use-api.js

@@ -0,0 +1,80 @@
+import { useEffect, useCallback, useRef } from 'react';
+import useSWR, { useSWRConfig } from 'swr';
+import { useApiContext, useWsManager } from '../provider.js';
+import { soloFetch, ApiError } from '../fetcher.js';
+import { stringifyQuery } from '../query.js';
+
+function buildUrl(base, query) {
+  if (!query) return base;
+  const qs = stringifyQuery(query);
+  return qs ? `${base}?${qs}` : base;
+}
+
+export default function useApi(path, query, options) {
+  const { pathPrefix, headers } = useApiContext();
+  const wsManager = useWsManager();
+  const { mutate: globalMutate } = useSWRConfig();
+
+  const disabled = path === null || options?.disable === true;
+  const wsEnabled = options?.ws !== false;
+  const fullPath = disabled ? null : `${pathPrefix}${path}`;
+  const url = disabled ? null : buildUrl(fullPath, query);
+
+  const { disable: _, ws: _ws, ...swrConfig } = options ?? {};
+  const result = useSWR(url, (key) => soloFetch(key, { headers }), swrConfig);
+
+  const mutateRef = useRef(result.mutate);
+  mutateRef.current = result.mutate;
+
+  useEffect(() => {
+    if (!wsManager || !fullPath || !wsEnabled) return;
+
+    const unsubscribe = wsManager.subscribe(fullPath, (msg) => {
+      if (msg.data !== undefined) {
+        mutateRef.current(msg.data, { revalidate: false });
+      }
+    });
+    return unsubscribe;
+  }, [wsManager, fullPath, wsEnabled]);
+
+  const makeMethod = useCallback(
+    (method) => async (body) => {
+      if (!fullPath) throw new Error('Cannot call mutation on a disabled useApi hook');
+
+      if (wsManager?.isConnected() && wsEnabled) {
+        const response = await wsManager.request(fullPath, method, body);
+        if (response.error) {
+          throw new ApiError(
+            response.status ?? 400,
+            response.error.code,
+            response.error.message,
+            response.error.details,
+          );
+        }
+        await globalMutate(url);
+        return response.data;
+      }
+
+      const res = await soloFetch(url, {
+        method,
+        headers: {
+          ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+          ...headers,
+        },
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+      });
+      await globalMutate(url);
+      return res;
+    },
+    [fullPath, wsManager, wsEnabled, url, headers, globalMutate],
+  );
+
+  return {
+    ...result,
+    loading: result.isLoading,
+    post: makeMethod('POST'),
+    put: makeMethod('PUT'),
+    patch: makeMethod('PATCH'),
+    del: makeMethod('DELETE'),
+  };
+}

package/client/hooks/use-debounce.js

@@ -0,0 +1,12 @@
+import { useState, useEffect } from 'react';
+
+export default function useDebounce(value, delayMs) {
+  const [debouncedValue, setDebouncedValue] = useState(value);
+
+  useEffect(() => {
+    const timer = setTimeout(() => setDebouncedValue(value), delayMs);
+    return () => clearTimeout(timer);
+  }, [value, delayMs]);
+
+  return debouncedValue;
+}

package/client/hooks/use-form.js

@@ -0,0 +1,86 @@
+import { useState, useCallback, useRef } from 'react';
+import { ArkErrors } from 'arktype';
+
+export default function useForm(options) {
+  const [values, setValues] = useState(options.initialValues);
+  const [errors, setErrors] = useState({});
+  const [touched, setTouched] = useState({});
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  const initialRef = useRef(options.initialValues);
+  const schemaRef = useRef(options.schema);
+  schemaRef.current = options.schema;
+  const onSubmitRef = useRef(options.onSubmit);
+  onSubmitRef.current = options.onSubmit;
+  const valuesRef = useRef(values);
+  valuesRef.current = values;
+
+  const isDirty = Object.keys(initialRef.current).some(
+    (key) => values[key] !== initialRef.current[key],
+  );
+
+  function setField(name, value) {
+    setValues((prev) => ({ ...prev, [name]: value }));
+    setTouched((prev) => ({ ...prev, [name]: true }));
+    setErrors((prev) => {
+      if (!prev[name]) return prev;
+      const next = { ...prev };
+      delete next[name];
+      return next;
+    });
+  }
+
+  const setError = useCallback((name, message) => {
+    setErrors((prev) => ({ ...prev, [name]: message }));
+  }, []);
+
+  const handleSubmit = useCallback(async (e) => {
+    e?.preventDefault?.();
+    const currentValues = valuesRef.current;
+    const schema = schemaRef.current;
+
+    if (schema) {
+      const result = schema(currentValues);
+      if (result instanceof ArkErrors) {
+        const fieldErrors = {};
+        for (const err of result) {
+          const key = String(err.path[0]);
+          if (key && !fieldErrors[key]) {
+            fieldErrors[key] = err.message;
+          }
+        }
+        setErrors(fieldErrors);
+        return;
+      }
+    }
+
+    setErrors({});
+    setIsSubmitting(true);
+    try {
+      await onSubmitRef.current(currentValues);
+    } finally {
+      setIsSubmitting(false);
+    }
+  }, []);
+
+  const reset = useCallback((newValues) => {
+    const resetTo = newValues ?? initialRef.current;
+    if (newValues) initialRef.current = newValues;
+    setValues(resetTo);
+    setErrors({});
+    setTouched({});
+    setIsSubmitting(false);
+  }, []);
+
+  return {
+    values,
+    errors,
+    touched,
+    isDirty,
+    isSubmitting,
+    setField,
+    setError,
+    handleSubmit,
+    reset,
+  };
+}

package/client/hooks/use-graphql.js

@@ -0,0 +1,30 @@
+import useSWR from 'swr';
+import useSWRMutation from 'swr/mutation';
+import { useApiContext } from '../provider.js';
+import { graphqlFetch } from '../graphql.js';
+
+function useGraphQL(query, variables, options) {
+  const { pathPrefix, headers } = useApiContext();
+
+  const key = query
+    ? variables
+      ? `gql:${query}:${JSON.stringify(variables)}`
+      : `gql:${query}`
+    : null;
+
+  return useSWR(
+    key,
+    () => graphqlFetch(`${pathPrefix}/graphql`, query, variables, headers),
+    options,
+  );
+}
+
+function useGraphQLMutation(query) {
+  const { pathPrefix, headers } = useApiContext();
+
+  return useSWRMutation(`gql-mutation:${query}`, (_key, { arg }) =>
+    graphqlFetch(`${pathPrefix}/graphql`, query, arg, headers),
+  );
+}
+
+export { useGraphQL, useGraphQLMutation };

package/client/hooks/use-interval.js

@@ -0,0 +1,12 @@
+import { useEffect, useRef } from 'react';
+
+export default function useInterval(callback, delayMs) {
+  const callbackRef = useRef(callback);
+  callbackRef.current = callback;
+
+  useEffect(() => {
+    if (delayMs === null) return;
+    const id = setInterval(() => callbackRef.current(), delayMs);
+    return () => clearInterval(id);
+  }, [delayMs]);
+}

package/client/hooks/use-mutation.js

@@ -0,0 +1,27 @@
+import useSWRMutation from 'swr/mutation';
+import { useApiContext } from '../provider.js';
+import { soloFetch } from '../fetcher.js';
+
+export default function useMutation(path, options) {
+  const { pathPrefix, headers } = useApiContext();
+  const method = options?.method ?? 'POST';
+  const url = `${pathPrefix}${path}`;
+
+  const result = useSWRMutation(url, (key, { arg }) =>
+    soloFetch(key, {
+      method,
+      headers: {
+        // Only set Content-Type when sending a body — Safari/WebKit rejects
+        // DELETE (and other bodyless) requests that include Content-Type.
+        ...(arg !== undefined ? { 'Content-Type': 'application/json' } : {}),
+        ...headers,
+      },
+      body: arg !== undefined ? JSON.stringify(arg) : undefined,
+    }),
+  );
+
+  return {
+    ...result,
+    loading: result.isMutating,
+  };
+}

package/client/hooks/use-query.js

@@ -0,0 +1,45 @@
+import { useCallback, useSyncExternalStore } from 'react';
+import { parseQuery } from '../query.js';
+
+function subscribe(callback) {
+  window.addEventListener('popstate', callback);
+  window.addEventListener('querychange', callback);
+  return () => {
+    window.removeEventListener('popstate', callback);
+    window.removeEventListener('querychange', callback);
+  };
+}
+
+function getSnapshot() {
+  return window.location.search;
+}
+
+function getServerSnapshot() {
+  return '';
+}
+
+export default function useQuery() {
+  const search = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+  const query = parseQuery(search);
+
+  const setQuery = useCallback((updates, options) => {
+    const next = options?.replace
+      ? new URLSearchParams()
+      : new URLSearchParams(window.location.search);
+
+    for (const [key, value] of Object.entries(updates)) {
+      if (value == null) {
+        next.delete(key);
+      } else {
+        next.set(key, value);
+      }
+    }
+
+    const qs = next.toString();
+    const newUrl = qs ? `${window.location.pathname}?${qs}` : window.location.pathname;
+    window.history.replaceState(null, '', newUrl);
+    window.dispatchEvent(new Event('querychange'));
+  }, []);
+
+  return { query, setQuery };
+}

package/client/hooks/web/use-click-outside.js

@@ -0,0 +1,22 @@
+import { useEffect, useRef } from 'react';
+
+export default function useClickOutside(ref, handler) {
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+
+  useEffect(() => {
+    function listener(event) {
+      if (!ref.current || ref.current.contains(event.target)) {
+        return;
+      }
+      handlerRef.current();
+    }
+
+    document.addEventListener('mousedown', listener);
+    document.addEventListener('touchstart', listener);
+    return () => {
+      document.removeEventListener('mousedown', listener);
+      document.removeEventListener('touchstart', listener);
+    };
+  }, [ref]);
+}

package/client/hooks/web/use-local-storage.js

@@ -0,0 +1,42 @@
+import { useState, useCallback, useEffect } from 'react';
+
+export default function useLocalStorage(key, initialValue) {
+  const [storedValue, setStoredValue] = useState(initialValue);
+
+  useEffect(() => {
+    try {
+      const item = window.localStorage.getItem(key);
+      if (item !== null) {
+        setStoredValue(JSON.parse(item));
+      }
+    } catch {}
+
+    const handleStorage = (e) => {
+      if (e.key === key) {
+        try {
+          setStoredValue(e.newValue !== null ? JSON.parse(e.newValue) : initialValue);
+        } catch {
+          setStoredValue(initialValue);
+        }
+      }
+    };
+
+    window.addEventListener('storage', handleStorage);
+    return () => window.removeEventListener('storage', handleStorage);
+  }, [key, initialValue]);
+
+  const setValue = useCallback(
+    (value) => {
+      setStoredValue((prev) => {
+        const nextValue = value instanceof Function ? value(prev) : value;
+        try {
+          window.localStorage.setItem(key, JSON.stringify(nextValue));
+        } catch {}
+        return nextValue;
+      });
+    },
+    [key],
+  );
+
+  return [storedValue, setValue];
+}