nebula-cms 0.1.0

package/src/client/js/utils/sort.ts

@@ -0,0 +1,84 @@
+/*
+ * Sorting utilities and types for admin sidebar content lists.
+ * Handles sort mode persistence, date coercion, and comparator generation.
+ */
+
+// Sidebar item displayed as a link in the admin navigation. Used by AdminSidebar for both collections and content lists.
+export type SidebarItem = {
+  label: string;
+  href: string;
+  subtitle?: string;
+  date?: Date;
+  // Draft-specific fields
+  draftId?: string;
+  isDraft?: boolean;
+  isOutdated?: boolean;
+};
+
+// Sort mode identifiers.
+export type SortMode = 'alpha' | 'date-asc' | 'date-desc';
+
+// Sort mode configuration: icon name and display label
+export const SORT_MODES: Record<SortMode, { icon: string; label: string }> = {
+  alpha: { icon: 'sort_by_alpha', label: 'Alphabetical' },
+  'date-asc': { icon: 'hourglass_arrow_down', label: 'Oldest first' },
+  'date-desc': { icon: 'hourglass_arrow_up', label: 'Newest first' },
+};
+
+// Fixed display order for sort options in the popover
+export const SORT_ORDER: SortMode[] = ['alpha', 'date-asc', 'date-desc'];
+
+/**
+ * Reads the persisted sort mode from localStorage, defaulting to 'alpha' if absent or invalid.
+ * @param {string} key - Collection name used to construct the storage key
+ * @return {SortMode} The persisted sort mode, or 'alpha' if not set
+ */
+export function readSortMode(key: string): SortMode {
+  const stored = localStorage.getItem(`cms-sort-${key}`);
+  if (stored === 'alpha' || stored === 'date-asc' || stored === 'date-desc') {
+    return stored;
+  }
+  return 'alpha';
+}
+
+/**
+ * Persists the sort mode to localStorage.
+ * @param {string} key - Collection name used to construct the storage key
+ * @param {SortMode} mode - The sort mode to persist
+ * @return {void}
+ */
+export function writeSortMode(key: string, mode: SortMode): void {
+  localStorage.setItem(`cms-sort-${key}`, mode);
+}
+
+/**
+ * Coerces a frontmatter published value (Date object or ISO string) into a Date for sorting. Returns undefined if the value is not a recognized date type.
+ * @param {unknown} val - The published value from frontmatter
+ * @return {Date | undefined} The resolved Date, or undefined
+ */
+export function toSortDate(val: unknown): Date | undefined {
+  if (val instanceof Date) return val;
+  return typeof val === 'string' ? new Date(val) : undefined;
+}
+
+/**
+ * Returns a comparator function for sorting SidebarItems by the given mode.
+ * @param {SortMode} mode - The sort mode to use
+ * @return {(a: SidebarItem, b: SidebarItem) => number} A comparator function suitable for Array.sort
+ */
+export function createComparator(
+  mode: SortMode,
+): (a: SidebarItem, b: SidebarItem) => number {
+  return (a, b) => {
+    if (mode === 'date-asc' || mode === 'date-desc') {
+      // Items without a date sort to the top (e.g. new drafts without a published date)
+      if (!a.date && !b.date) return 0;
+      if (!a.date) return -1;
+      if (!b.date) return 1;
+      return mode === 'date-asc'
+        ? a.date.getTime() - b.date.getTime()
+        : b.date.getTime() - a.date.getTime();
+    }
+    return a.label.toLowerCase().localeCompare(b.label.toLowerCase());
+  };
+}

package/src/client/js/utils/stable-stringify.ts

@@ -0,0 +1,27 @@
+/*
+ * Deterministic JSON serialization with sorted keys.
+ * Prevents false-positive outdated detection when comparing snapshots.
+ */
+
+/**
+ * Recursively sorts object keys and serializes to JSON.
+ * Produces deterministic output regardless of key insertion order.
+ * @param {unknown} value - The value to serialize
+ * @return {string} A JSON string with sorted keys at every nesting level
+ */
+export function stableStringify(value: unknown): string {
+  return JSON.stringify(value, (_key, val) => {
+    if (val !== null && typeof val === 'object' && !Array.isArray(val)) {
+      return Object.keys(val as Record<string, unknown>)
+        .sort()
+        .reduce(
+          (sorted, k) => {
+            sorted[k] = (val as Record<string, unknown>)[k];
+            return sorted;
+          },
+          {} as Record<string, unknown>,
+        );
+    }
+    return val;
+  });
+}

package/src/client/js/utils/url-utils.ts

@@ -0,0 +1,38 @@
+/*
+ * URL validation utilities for the editor's smart paste handler.
+ */
+
+/**
+ * Checks whether a string is a valid URL (absolute with scheme, or absolute path).
+ * Used by the smart paste handler to determine whether clipboard content should
+ * be auto-wrapped as a markdown link rather than inserted as plain text.
+ * Trims whitespace before validating. Rejects plain words and relative paths
+ * without a leading slash to avoid false positives on normal text.
+ * @param {string} text - The string to validate
+ * @return {boolean} True if the text is a valid URL or absolute path
+ */
+export function isURL(text: string): boolean {
+  const trimmed = text.trim();
+  if (!trimmed) return false;
+
+  // Absolute URL with scheme (https://, mailto:, etc.)
+  try {
+    new URL(trimmed);
+    return true;
+  } catch {
+    // Not an absolute URL — fall through
+  }
+
+  // Absolute path starting with /
+  if (trimmed.startsWith('/')) {
+    try {
+      // Dummy base required by URL constructor to resolve absolute paths
+      new URL(trimmed, 'https://a.com');
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  return false;
+}

package/src/types.ts

@@ -0,0 +1,25 @@
+/*
+ * Configuration options for the nebula-cms Astro integration.
+ */
+export interface NebulaCMSConfig {
+  /**
+   * URL prefix for the admin SPA.
+   * Accepts a relative or absolute path. Normalized automatically: leading `/`
+   * prepended if missing, consecutive slashes collapsed, trailing `/` stripped.
+   * After normalization, must contain only segments of letters, digits, hyphens,
+   * and underscores — or be `/` for root mount.
+   * @default '/admin'
+   */
+  basePath?: string;
+
+  /**
+   * URL prefix under which collection schema files are served.
+   * Accepts a relative or absolute path. Normalized automatically: leading `/`
+   * prepended if missing, consecutive slashes collapsed, trailing `/` stripped.
+   * After normalization, must contain only segments of letters, digits, hyphens,
+   * and underscores. Cannot be `/` (root) — collections require at least one
+   * path segment.
+   * @default '/collections'
+   */
+  collectionsPath?: string;
+}

package/src/virtual.d.ts

@@ -0,0 +1,22 @@
+/*
+ * Ambient type declarations for virtual modules injected by the nebula-cms
+ * Vite plugin. Consumers reference these via `/// <reference types="nebula-cms/virtual" />`
+ * in their env.d.ts.
+ */
+declare module 'virtual:nebula/config' {
+  /*
+   * CMS configuration: basePath is the URL prefix for the admin SPA,
+   * collectionsPath is the URL prefix for schema files.
+   */
+  const config: {
+    basePath: string;
+    collectionsPath: string;
+  };
+  export default config;
+}
+
+declare module 'virtual:nebula/collections' {
+  // Map of collection names to their schema.json public URLs
+  const collections: Record<string, string>;
+  export default collections;
+}

package/svelte.config.js

@@ -0,0 +1,4 @@
+/** @type {import('@sveltejs/package').Config} */
+const config = {};
+
+export default config;

package/tests/astro/build.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { execFileSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { existsSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+
+// Resolve playground path relative to this test file
+const playgroundDir = resolve(import.meta.dirname, '../../playground');
+const rootDir = resolve(playgroundDir, '..');
+
+describe('playground build integration', () => {
+  beforeAll(() => {
+    // Build root package so playground can resolve the nebula-cms integration.
+    // The prebuild script generates icons.css automatically before svelte-package runs.
+    execFileSync('pnpm', ['build'], { cwd: rootDir, stdio: 'pipe' });
+    // Generate collection schemas, then build the Astro site
+    execFileSync('pnpm', ['sync'], { cwd: playgroundDir, stdio: 'pipe' });
+    execFileSync('pnpm', ['build'], { cwd: playgroundDir, stdio: 'pipe' });
+  }, 60_000);
+
+  afterAll(() => {
+    const dist = resolve(playgroundDir, 'dist');
+    if (existsSync(dist)) rmSync(dist, { recursive: true });
+  });
+
+  it('copies schema files into dist/collections/ via astro:build:done', () => {
+    const distCollections = resolve(playgroundDir, 'dist/collections');
+    expect(existsSync(distCollections)).toBe(true);
+
+    const files = readdirSync(distCollections).filter((f) =>
+      f.endsWith('.schema.json'),
+    );
+    const names = files.map((f) => f.replace('.schema.json', ''));
+    expect(names).toContain('posts');
+    expect(names).toContain('authors');
+  });
+
+  it('generates .schema.json for all four collections', () => {
+    const collectionsDir = resolve(playgroundDir, '.astro/collections');
+    const files = readdirSync(collectionsDir).filter((f) =>
+      f.endsWith('.schema.json'),
+    );
+    const names = files.map((f) => f.replace('.schema.json', ''));
+
+    expect(names).toContain('posts');
+    expect(names).toContain('authors');
+    expect(names).toContain('products');
+    expect(names).toContain('courses');
+  });
+
+  it('bundles collection schema paths into the client JS', () => {
+    // Admin uses client:only="svelte", so collection data lives in the JS
+    // bundle via the virtual:collections module, not in the static HTML.
+    const assetDir = resolve(playgroundDir, 'dist/_astro');
+    const jsFiles = readdirSync(assetDir).filter((f) => f.endsWith('.js'));
+    const allJs = jsFiles
+      .map((f) => readFileSync(resolve(assetDir, f), 'utf-8'))
+      .join('\n');
+
+    for (const name of ['posts', 'authors', 'products', 'courses']) {
+      expect(allJs).toContain(`/collections/${name}.schema.json`);
+    }
+  });
+});