nebula-cms 0.1.0

package/src/client/js/state/schema.svelte.ts

@@ -0,0 +1,140 @@
+/*
+ * Reactive schema state for the admin SPA.
+ * Fetches, caches, and exposes JSON Schemas for content collections.
+ */
+
+import schemas from 'virtual:nebula/collections';
+import { getExtensionsForSchema } from '../utils/file-types';
+
+// JSON Schema object type.
+type JsonSchema = Record<string, unknown>;
+
+// Cache of fetched schemas keyed by collection name
+const cache = new Map<string, JsonSchema>();
+
+// Currently active schema for the selected collection
+let activeSchema = $state<JsonSchema | null>(null);
+
+export const schema = {
+  // The loaded JSON Schema for the active collection, or null.
+  get active(): JsonSchema | null {
+    return activeSchema;
+  },
+};
+
+/**
+ * Fetches all collection schemas in parallel and caches them.
+ * Call once on app startup so schema-derived state is available before the first collection renders.
+ * @return {Promise<void>}
+ */
+export async function prefetchAllSchemas(): Promise<void> {
+  const entries = Object.entries(schemas);
+  const results = await Promise.all(
+    entries.map(async ([name, url]) => {
+      const response = await fetch(url);
+      const data = (await response.json()) as JsonSchema;
+      return [name, data] as const;
+    }),
+  );
+  for (const [name, data] of results) {
+    cache.set(name, data);
+  }
+}
+
+/**
+ * Fetches and caches the JSON Schema for a collection, then sets the reactive schema state.
+ * @param {string} collection - The collection name to fetch the schema for
+ * @return {Promise<void>}
+ */
+export async function fetchSchema(collection: string): Promise<void> {
+  const cached = cache.get(collection);
+  if (cached) {
+    activeSchema = cached;
+    return;
+  }
+
+  const url = schemas[collection];
+  if (!url) return;
+
+  const response = await fetch(url);
+  const data = (await response.json()) as JsonSchema;
+  cache.set(collection, data);
+  activeSchema = data;
+}
+
+/**
+ * Returns true if the collection's schema has a date-time property, indicating it supports date-based sorting.
+ * Requires prefetchAllSchemas to have been called; returns false if the schema isn't cached yet.
+ * @param {string} collection - The collection name to check
+ * @return {boolean} True if any property in the schema uses the date-time format
+ */
+export function collectionHasDates(collection: string): boolean {
+  const s = cache.get(collection);
+  if (!s) return false;
+  const props = s['properties'] as Record<string, JsonSchema> | undefined;
+  if (!props) return false;
+  return Object.values(props).some((p) => p['format'] === 'date-time');
+}
+
+/**
+ * Reads a top-level string field from a collection's cached schema.
+ * Returns null if the schema isn't cached or the field is absent/non-string.
+ * @param {string} collection - The collection name
+ * @param {string} field - The schema field to read (e.g. 'title', 'description')
+ * @return {string | null} The field value, or null
+ */
+function getStringField(collection: string, field: string): string | null {
+  const s = cache.get(collection);
+  if (!s) return null;
+  const value = s[field];
+  return typeof value === 'string' ? value : null;
+}
+
+/**
+ * Returns the display title for a collection from its cached schema.
+ * Returns null if the schema hasn't been fetched or has no title.
+ * @param {string} collection - The collection name
+ * @return {string | null} The schema title, or null
+ */
+export function getCollectionTitle(collection: string): string | null {
+  return getStringField(collection, 'title');
+}
+
+/**
+ * Returns the description for a collection from its cached schema.
+ * Returns null if the schema hasn't been fetched or has no description.
+ * @param {string} collection - The collection name
+ * @return {string | null} The schema description, or null
+ */
+export function getCollectionDescription(collection: string): string | null {
+  return getStringField(collection, 'description');
+}
+
+/*
+ * Known race condition: if a caller invokes getSchemaExtensions before
+ * prefetchAllSchemas() has completed, the schema won't be cached yet and the
+ * fallback is returned. The caller (dispatchWorker in state.svelte.ts)
+ * mitigates this by awaiting initPromise, which includes prefetchAllSchemas().
+ * If the ordering changes, callers should await prefetchAllSchemas() first.
+ */
+
+/**
+ * Returns the resolved file extensions for a collection from its cached schema.
+ * Falls back to ['.md', '.mdx'] if the schema hasn't been fetched or declares no files.
+ * @param {string} collection - The collection name
+ * @return {string[]} Array of file extensions
+ */
+export function getSchemaExtensions(collection: string): string[] {
+  const s = cache.get(collection);
+  if (!s) return ['.md', '.mdx'];
+  const extensions = getExtensionsForSchema(s);
+  return extensions.length > 0 ? extensions : ['.md', '.mdx'];
+}
+
+/**
+ * Clears the active schema.
+ * @return {void}
+ */
+export function clearSchema(): void {
+  activeSchema = null;
+}

package/src/client/js/state/state.svelte.ts

@@ -0,0 +1,334 @@
+/*
+ * Global application state for the admin SPA.
+ * Manages backend connection, schema loading, collections, and navigation state.
+ */
+
+import schemas from 'virtual:nebula/collections';
+import {
+  loadBackend,
+  saveBackend,
+  clearBackend,
+  type BackendConfig,
+} from '../storage/storage';
+import { StorageClient } from '../storage/client';
+import { nav, navigate, adminPath } from './router.svelte';
+import {
+  drafts,
+  mergeDrafts,
+  refreshDrafts,
+  resetDraftMerge,
+} from '../drafts/merge.svelte';
+import { getSchemaExtensions } from './schema.svelte';
+
+export { drafts, refreshDrafts };
+
+// Content item with full frontmatter data returned by the worker.
+export type ContentItem = {
+  filename: string;
+  data: Record<string, unknown>;
+};
+
+// Permission state for the stored FSA directory handle.
+type PermissionState = 'granted' | 'prompt' | 'denied';
+// Backend type discriminator.
+type BackendType = 'fsa' | 'github' | null;
+// Sorted collection names derived from virtual:nebula/collections.
+export const collections = Object.keys(schemas).sort();
+/*
+ * Uses .js extension because svelte-package does not rewrite URL string literals;
+ * the dist output must reference the compiled .js file, not the source .ts file.
+ */
+const sharedWorker = new SharedWorker(
+  new URL('../storage/workers/storage.js', import.meta.url),
+  { type: 'module', name: 'cms-storage' },
+);
+// Main-thread StorageClient for editor and draft-merge I/O.
+export const storageClient = new StorageClient(sharedWorker.port);
+let backendType = $state<BackendType>(null);
+let backendReady = $state(false);
+let permissionState = $state<PermissionState>('denied');
+let contentList = $state<ContentItem[]>([]);
+let error = $state<string | null>(null);
+let loading = $state(false);
+
+export const backend = {
+  // Active backend type, or null if not connected.
+  get type(): BackendType {
+    return backendType;
+  },
+  // True if a backend is initialized and ready.
+  get ready(): boolean {
+    return backendReady;
+  },
+  // FSA permission state for the re-auth flow in BackendPicker.
+  get permission(): PermissionState {
+    return permissionState;
+  },
+};
+
+export const content = {
+  // Parsed content items for the selected collection.
+  get list(): ContentItem[] {
+    return contentList;
+  },
+  // True if the frontmatter worker is actively parsing.
+  get loading(): boolean {
+    return loading;
+  },
+  // Error message for display in the sidebar.
+  get error(): string | null {
+    return error;
+  },
+};
+let worker: Worker | null = null;
+let loadedCollection = '';
+let initPromise: Promise<void> | null = null;
+const contentCache = new Map<string, ContentItem[]>();
+
+/**
+ * Initializes the frontmatter worker and bridges a port to the SharedWorker.
+ * @return {Worker}
+ */
+function ensureWorker(): Worker {
+  if (worker) return worker;
+  // Uses .js extension because svelte-package does not rewrite URL string literals
+  worker = new Worker(
+    new URL('../storage/workers/frontmatter.js', import.meta.url),
+    { type: 'module' },
+  );
+  worker.addEventListener('message', (event) => {
+    const data = event.data;
+    if (data.type === 'result') {
+      const forCollection = data.collection as string;
+      // Always cache under the correct collection
+      contentCache.set(forCollection, data.items);
+      // Only update the visible list if this result is for the current collection
+      if (forCollection === loadedCollection) {
+        contentList = data.items;
+        loading = false;
+        error = null;
+        if (backendReady) mergeDrafts(forCollection);
+      }
+    } else if (data.type === 'error') {
+      error = data.message;
+      loading = false;
+      contentList = [];
+    }
+  });
+
+  // Bridge a port so the frontmatter worker can talk to the storage SharedWorker
+  const channel = new MessageChannel();
+  worker.postMessage({ type: 'port' }, [channel.port1]);
+  sharedWorker.port.postMessage({ type: 'connect-port' }, [channel.port2]);
+
+  return worker;
+}
+
+/**
+ * Sends a parse request to the frontmatter worker. Refresh mode keeps current sidebar visible.
+ * @param {string} collection - The collection name to parse
+ * @param {boolean} refresh - If true, keep current contentList and skip loading state
+ * @return {Promise<void>}
+ */
+async function dispatchWorker(
+  collection: string,
+  refresh = false,
+): Promise<void> {
+  if (!backendReady) return;
+  if (!refresh) {
+    loading = true;
+    contentList = [];
+  }
+  error = null;
+  // Wait for the SharedWorker adapter to be ready before dispatching
+  if (initPromise) await initPromise;
+  const w = ensureWorker();
+  const extensions = getSchemaExtensions(collection);
+  w.postMessage({ type: 'parse', collection, extensions });
+}
+
+/**
+ * Restores a stored backend config from IndexedDB and initializes the SharedWorker.
+ * @return {Promise<void>}
+ */
+export async function restoreBackend(): Promise<void> {
+  try {
+    const config = await loadBackend();
+    if (!config) {
+      backendType = null;
+      backendReady = false;
+      return;
+    }
+
+    if (config.type === 'fsa') {
+      // Check FSA permission state
+      const perm = await config.handle.queryPermission({ mode: 'readwrite' });
+      permissionState = perm;
+      backendType = 'fsa';
+
+      if (perm === 'granted') {
+        await storageClient.init({ type: 'init', backend: config });
+        backendReady = true;
+        navigateToFirstCollectionIfHome();
+      }
+      // If perm is 'prompt', BackendPicker shows re-auth button
+    } else {
+      // GitHub — show UI optimistically, validate in background
+      backendType = 'github';
+      backendReady = true;
+      navigateToFirstCollectionIfHome();
+      initPromise = storageClient
+        .init({ type: 'init', backend: config })
+        .catch(async () => {
+          await clearBackend();
+          backendType = null;
+          backendReady = false;
+          contentList = [];
+          contentCache.clear();
+          loadedCollection = '';
+          navigate(adminPath());
+        })
+        .finally(() => {
+          initPromise = null;
+        });
+    }
+  } catch {
+    backendType = null;
+    backendReady = false;
+  }
+}
+
+/**
+ * Re-requests FSA permission. Must be called from a user gesture.
+ * @return {Promise<void>}
+ */
+export async function requestPermission(): Promise<void> {
+  const config = await loadBackend();
+  if (!config || config.type !== 'fsa') return;
+  try {
+    const perm = await config.handle.requestPermission({ mode: 'readwrite' });
+    permissionState = perm;
+    if (perm === 'granted') {
+      await storageClient.init({ type: 'init', backend: config });
+      backendReady = true;
+      navigateToFirstCollectionIfHome();
+    }
+  } catch {
+    permissionState = 'denied';
+  }
+}
+
+/**
+ * Opens the directory picker and initializes the FSA backend. Must be called from a user gesture.
+ * @return {Promise<void>}
+ */
+export async function pickDirectory(): Promise<void> {
+  try {
+    const handle = await window.showDirectoryPicker({ mode: 'readwrite' });
+    const config: BackendConfig = { type: 'fsa', handle };
+    await storageClient.init({ type: 'init', backend: config });
+    await saveBackend(config);
+    backendType = 'fsa';
+    permissionState = 'granted';
+    backendReady = true;
+    navigateToFirstCollectionIfHome();
+  } catch (err) {
+    if (err instanceof DOMException && err.name === 'AbortError') return;
+    error = err instanceof Error ? err.message : String(err);
+  }
+}
+
+/**
+ * Connects to a GitHub repository via PAT and persists the config.
+ * @param {string} token - GitHub Personal Access Token
+ * @param {string} repo - Repository in "owner/repo" format
+ * @return {Promise<void>}
+ */
+export async function connectGitHub(
+  token: string,
+  repo: string,
+): Promise<void> {
+  const config: BackendConfig = { type: 'github', token, repo };
+  await storageClient.init({ type: 'init', backend: config });
+  await saveBackend(config);
+  backendType = 'github';
+  backendReady = true;
+  navigateToFirstCollectionIfHome();
+}
+
+/**
+ * Disconnects the backend, clears credentials, and resets all state.
+ * @return {Promise<void>}
+ */
+export async function disconnect(): Promise<void> {
+  worker?.terminate();
+  worker = null;
+  resetDraftMerge();
+  await storageClient.teardown();
+  await clearBackend();
+  backendType = null;
+  backendReady = false;
+  permissionState = 'denied';
+  contentList = [];
+  contentCache.clear();
+  loadedCollection = '';
+  error = null;
+  loading = false;
+  navigate(adminPath());
+}
+
+/**
+ * Navigates to the first collection if currently on the home view.
+ * @return {void}
+ */
+function navigateToFirstCollectionIfHome(): void {
+  if (nav.route.view === 'home' && collections.length > 0) {
+    navigate(adminPath(collections[0]));
+  }
+}
+
+/**
+ * Loads a collection. Serves from cache instantly if available, then background refreshes.
+ * @param {string} collection - The collection name to load
+ * @return {void}
+ */
+export function loadCollection(collection: string): void {
+  if (collection === loadedCollection) return;
+  loadedCollection = collection;
+  const cached = contentCache.get(collection);
+  if (cached) {
+    // Serve cached items instantly, then refresh in background
+    contentList = cached;
+    refreshDrafts(collection);
+    dispatchWorker(collection, true);
+  } else {
+    dispatchWorker(collection);
+  }
+}
+
+/**
+ * Forces a background reload, keeping the sidebar visible.
+ * @param {string} collection - The collection to reload
+ * @return {void}
+ */
+export function reloadCollection(collection: string): void {
+  loadedCollection = collection;
+  dispatchWorker(collection, true);
+}
+
+/**
+ * Optimistically updates a single item's frontmatter in the content list and cache.
+ * @param {string} filename - The filename to update
+ * @param {Record<string, unknown>} data - The new frontmatter data
+ * @return {void}
+ */
+export function updateContentItem(
+  filename: string,
+  data: Record<string, unknown>,
+): void {
+  const updated = contentList.map((item) =>
+    item.filename === filename ? { ...item, data } : item,
+  );
+  contentList = updated;
+  if (loadedCollection) contentCache.set(loadedCollection, updated);
+}

package/src/client/js/state/theme.svelte.ts

@@ -0,0 +1,173 @@
+/*
+ * Reactive theme state with localStorage persistence and system preference detection.
+ * Manages a three-way preference (light / dark / auto) and resolves the effective
+ * theme by combining user preference with the OS-level color scheme.
+ */
+
+// Tri-state preference: 'light', 'dark', or 'auto' (follow system)
+type ThemePreference = 'light' | 'dark' | 'auto';
+
+// Resolved theme applied to the DOM — always 'light' or 'dark'
+type ResolvedTheme = 'light' | 'dark';
+
+// Material Symbols icon name for each preference
+type ThemeIcon = 'light_mode' | 'dark_mode' | 'brightness_auto';
+
+// Human-readable label for each preference
+type ThemeLabel = 'Light' | 'Dark' | 'Auto';
+
+// localStorage key for persisting the user's preference
+const STORAGE_KEY = 'nebula-theme';
+
+/*
+//////////////////////////////
+// Preference → UI mapping
+//////////////////////////////
+*/
+
+/*
+ * Single source of truth for all preference-derived UI values.
+ * Adding a new preference requires a new entry here — TypeScript
+ * enforces exhaustiveness via the Record<ThemePreference, ...> type.
+ */
+const THEME_MAP: Record<
+  ThemePreference,
+  { icon: ThemeIcon; label: ThemeLabel }
+> = {
+  light: { icon: 'light_mode', label: 'Light' },
+  dark: { icon: 'dark_mode', label: 'Dark' },
+  auto: { icon: 'brightness_auto', label: 'Auto' },
+};
+
+/*
+//////////////////////////////
+// Module initialization
+//////////////////////////////
+*/
+
+/*
+ * Read preference from localStorage at module init to avoid a flash of wrong theme.
+ * Safe because this module is only loaded client-side (client:only="svelte").
+ */
+let stored: string | null = null;
+try {
+  if (typeof localStorage !== 'undefined') {
+    stored = localStorage.getItem(STORAGE_KEY);
+  }
+} catch {
+  // Storage access blocked (SecurityError, private browsing, etc.)
+}
+
+/*
+ * Read system preference at module init so the first render has the correct
+ * resolved theme — deferring this to onMount would cause a flash for auto+dark users.
+ */
+const mq =
+  typeof window !== 'undefined'
+    ? window.matchMedia('(prefers-color-scheme: dark)')
+    : null;
+
+// The user's explicit preference
+let preference = $state<ThemePreference>(
+  stored === 'light' || stored === 'dark' || stored === 'auto'
+    ? stored
+    : 'auto',
+);
+
+// Whether the OS prefers dark mode — updated via matchMedia listener
+let systemPrefersDark = $state(mq?.matches ?? false);
+
+/*
+//////////////////////////////
+// Derived state
+//////////////////////////////
+*/
+
+/*
+ * $derived can only be a variable declaration initializer, not an object
+ * property — Svelte compiler restriction. These private derivations feed
+ * the exported theme object via getters.
+ */
+const resolved: ResolvedTheme = $derived(
+  preference === 'auto' ? (systemPrefersDark ? 'dark' : 'light') : preference,
+);
+const ui = $derived(THEME_MAP[preference]);
+
+/*
+ * Reactive theme state. Consumers read properties directly: theme.resolved,
+ * theme.icon, theme.label. The getters forward Svelte's reactive tracking.
+ */
+export const theme = {
+  get resolved(): ResolvedTheme {
+    return resolved;
+  },
+  get icon(): ThemeIcon {
+    return ui.icon;
+  },
+  get label(): ThemeLabel {
+    return ui.label;
+  },
+};
+
+/*
+//////////////////////////////
+// System preference tracking
+//////////////////////////////
+*/
+
+// Guard against duplicate listener registration (e.g. HMR remount)
+let initialized = false;
+
+/**
+ * Starts listening to OS color scheme changes via matchMedia.
+ * Preference and initial system state are already read at module init,
+ * so this only needs to register the change listener. Call once on mount.
+ * Safe to call multiple times — registers the listener only once.
+ * @return {() => void} Cleanup function that removes the listener
+ */
+export function initTheme(): () => void {
+  if (initialized) return () => {};
+  initialized = true;
+
+  /**
+   * Updates the systemPrefersDark flag when the OS color scheme changes.
+   * @param {MediaQueryListEvent} e - The change event from matchMedia
+   * @return {void}
+   */
+  const handler = (e: MediaQueryListEvent): void => {
+    systemPrefersDark = e.matches;
+  };
+
+  mq?.addEventListener('change', handler);
+
+  return () => {
+    mq?.removeEventListener('change', handler);
+    initialized = false;
+  };
+}
+
+/*
+//////////////////////////////
+// Actions
+//////////////////////////////
+*/
+
+/**
+ * Cycles the preference through auto -> light -> dark -> auto.
+ * Persists the new value to localStorage.
+ * @return {void}
+ */
+export function cycleTheme(): void {
+  const next: ThemePreference =
+    preference === 'auto' ? 'light' : preference === 'light' ? 'dark' : 'auto';
+  preference = next;
+  try {
+    localStorage.setItem(STORAGE_KEY, next);
+  } catch {
+    /*
+     * Persistence failed (quota exceeded, storage disabled, etc.).
+     * The in-memory preference is already updated, so the current
+     * session works correctly — it just won't survive a page reload.
+     */
+  }
+}