opacacms 0.1.0

package/src/admin/custom-field.ts

@@ -0,0 +1,179 @@
+export interface CustomFieldProps<TValue = any, TConfig = Record<string, any>> {
+  /** The current value of the field from the CMS database */
+  value: TValue;
+  /** The full schema configuration of the field */
+  fieldConfig: TConfig;
+  /** Whether the field is currently disabled by access control */
+  disabled: boolean;
+  /** Whether the field is currently read-only by access control */
+  readOnly: boolean;
+  /** A validation error message from the CMS, if any */
+  error?: string;
+  /** The current full state of the parent form or row */
+  parentData?: Record<string, unknown>;
+  /** Callback to notify the CMS that the data has changed */
+  onChange: (value: TValue) => void;
+}
+
+export interface CustomFieldAdapter {
+  /**
+   * Called exactly once when the field is inserted into the CMS Admin UI.
+   * Use this to render your React root, Vue app, or Vanilla DOM nodes.
+   *
+   * @param container The DOM element acting as the wrapper for your component.
+   * @param props The initial properties (value, config, onChange) from the CMS.
+   */
+  mount: (container: HTMLElement, props: CustomFieldProps) => void;
+
+  /**
+   * Called whenever the CMS pushes new data to the field (e.g. form resets,
+   * external value changes).
+   *
+   * @param container The same DOM element wrapper.
+   * @param props The updated properties.
+   */
+  update?: (container: HTMLElement, props: CustomFieldProps) => void;
+
+  /**
+   * Called exactly once when the field is removed from the DOM (e.g., navigating away).
+   * Use this to unmount your React root or Vue app to prevent memory leaks.
+   *
+   * @param container The same DOM element wrapper.
+   */
+  unmount?: (container: HTMLElement) => void;
+}
+
+/**
+ * A built-in utility to register framework-agnostic Custom Web Components for the OpacaCMS Admin UI.
+ *
+ * It acts as an adapter, translating the Web Component lifecycle (`connectedCallback`, `disconnectedCallback`,
+ * property setters) into a simple `mount` / `update` / `unmount` paradigm that can easily wrap React, Vue, Angular,
+ * or plain Javascript applications.
+ *
+ * @example
+ * ```tsx
+ * import { defineCustomField } from 'opacacms/admin';
+ * import { createRoot } from 'react-dom/client';
+ *
+ * defineCustomField('my-react-picker', {
+ *   mount: (container, props) => {
+ *     (container as any)._root = createRoot(container);
+ *     (container as any)._root.render(<MyPicker {...props} />);
+ *   },
+ *   update: (container, props) => {
+ *     (container as any)._root.render(<MyPicker {...props} />);
+ *   },
+ *   unmount: (container) => {
+ *     (container as any)._root.unmount();
+ *   }
+ * });
+ * ```
+ *
+ * @param tagName The tag name to register in the browser (e.g., `opaca-color-picker`). Must contain a hyphen.
+ * @param adapter The adapter containing `mount`, optional `update`, and optional `unmount` lifecycle methods.
+ */
+export function defineCustomField(tagName: string, adapter: CustomFieldAdapter) {
+  if (typeof window === "undefined") return;
+
+  if (customElements.get(tagName)) {
+    console.warn(`[OpacaCMS] Custom field tag "${tagName}" is already defined.`);
+    return;
+  }
+
+  class OpacaCustomFieldElement extends HTMLElement {
+    private _value: any;
+    private _fieldConfig: any;
+    private _error?: string;
+    private _parentData?: Record<string, unknown>;
+    private _isMounted = false;
+
+    // Helper to abstract the complex CustomEvent away from the user's DX
+    private handleChange = (newValue: any) => {
+      this.dispatchEvent(
+        new CustomEvent("opacachange", {
+          detail: { value: newValue },
+          bubbles: true,
+          composed: true,
+        }),
+      );
+    };
+
+    private getProps(): CustomFieldProps {
+      return {
+        value: this._value,
+        fieldConfig: this._fieldConfig,
+        disabled: this.getAttribute("data-disabled") === "true",
+        readOnly: this.getAttribute("data-readonly") === "true",
+        error: this._error,
+        parentData: this._parentData,
+        onChange: this.handleChange,
+      };
+    }
+
+    set error(err: string | undefined) {
+      if (this._error !== err) {
+        this._error = err;
+        if (this._isMounted && adapter.update) {
+          adapter.update(this, this.getProps());
+        }
+      }
+    }
+
+    get error() {
+      return this._error;
+    }
+
+    set parentData(data: Record<string, unknown> | undefined) {
+      this._parentData = data;
+      if (this._isMounted && adapter.update) {
+        adapter.update(this, this.getProps());
+      }
+    }
+
+    get parentData() {
+      return this._parentData;
+    }
+
+    set value(val: any) {
+      const oldValue = this._value;
+      this._value = val;
+      // Only call update if the value actually changed and the component is mounted
+      if (this._isMounted && adapter.update && oldValue !== val) {
+        adapter.update(this, this.getProps());
+      }
+    }
+
+    get value() {
+      return this._value;
+    }
+
+    set fieldConfig(config: any) {
+      this._fieldConfig = config;
+      if (this._isMounted && adapter.update) {
+        adapter.update(this, this.getProps());
+      }
+    }
+
+    get fieldConfig() {
+      return this._fieldConfig;
+    }
+
+    connectedCallback() {
+      if (!this._isMounted) {
+        adapter.mount(this, this.getProps());
+        this._isMounted = true;
+      }
+    }
+
+    disconnectedCallback() {
+      if (this._isMounted) {
+        if (adapter.unmount) {
+          adapter.unmount(this);
+        }
+        this._isMounted = false;
+      }
+    }
+  }
+
+  customElements.define(tagName, OpacaCustomFieldElement);
+}

package/src/admin/index.ts

@@ -0,0 +1,15 @@
+export {
+  type CustomFieldAdapter,
+  type CustomFieldProps,
+  defineCustomField,
+} from "./custom-field";
+export { defineReactField } from "./react";
+export * from "./router";
+export * from "./stores/config";
+export * from "./stores/query";
+export * from "./stores/ui";
+export { AdminClient } from "./ui/admin-client";
+export { AdminLayout } from "./ui/admin-layout";
+export { Breadcrumbs } from "./ui/components/ui/breadcrumbs";
+export { Link } from "./ui/components/link";
+export { Toast, ToastContainer } from "./ui/components/toast";

package/src/admin/react.tsx

@@ -0,0 +1,72 @@
+import React from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { type CustomFieldProps, defineCustomField } from './custom-field';
+
+/**
+ * A helper utility to quickly register a React component as an OpacaCMS Custom Field.
+ *
+ * This function abstracts away the boilerplate of converting a React component into a Custom Element,
+ * managing the `createRoot` mounting process, and properly passing down props (`value`, `error`, `onChange`, etc.).
+ *
+ * @example
+ * ```tsx
+ * import { defineReactField } from 'opacacms/admin/react';
+ *
+ * const MyPicker = ({ value, onChange, error }) => (
+ *   <div>
+ *     <input value={value || ''} onChange={e => onChange(e.target.value)} />
+ *     {error && <span style={{ color: 'red' }}>{error}</span>}
+ *   </div>
+ * );
+ *
+ * defineReactField('my-react-picker', MyPicker);
+ * ```
+ *
+ * @param tagName The custom element tag name (must contain a hyphen, e.g., 'opaca-custom-picker').
+ * @param Component The React functional or class component to render.
+ */
+interface OpacaContainer extends HTMLElement {
+  _opacaReactRoot?: Root;
+}
+
+export function defineReactField<TValue = any, TConfig = Record<string, any>>(
+  tagName: string,
+  Component: React.ComponentType<CustomFieldProps<TValue, TConfig>>,
+) {
+  defineCustomField(tagName, {
+    mount: (container, props) => {
+      const el = container as OpacaContainer;
+      const root = createRoot(el);
+      el._opacaReactRoot = root;
+      root.render(
+        React.createElement(
+          Component,
+          props as CustomFieldProps<TValue, TConfig>,
+        ),
+      );
+    },
+    update: (container, props) => {
+      const el = container as OpacaContainer;
+      const root = el._opacaReactRoot;
+      if (root) {
+        root.render(
+          React.createElement(
+            Component,
+            props as CustomFieldProps<TValue, TConfig>,
+          ),
+        );
+      }
+    },
+    unmount: (container) => {
+      const el = container as OpacaContainer;
+      const root = el._opacaReactRoot;
+      if (root) {
+        // Schedule unmount to avoid synchronous React 18+ unmount warnings during DOM teardown
+        setTimeout(() => {
+          root.unmount();
+          delete el._opacaReactRoot;
+        }, 0);
+      }
+    },
+  });
+}

package/src/admin/router.ts

@@ -0,0 +1,9 @@
+import { createRouter } from "@nanostores/router";
+
+export const $router = createRouter({
+  dashboard: "/admin",
+  collections: "/admin/collections/:slug",
+  document: "/admin/collections/:slug/:id",
+  globals: "/admin/globals/:slug",
+  settings: "/admin/settings",
+});

package/src/admin/stores/admin-queries.ts

@@ -0,0 +1,121 @@
+import { atom, computed } from "nanostores";
+import type { PaginatedResult } from "../../types";
+import { api } from "../api-client";
+import { createFetcherStore, createMutatorStore } from "./query";
+
+// --- Collection List ---
+export interface CollectionQueryParams {
+  slug: string;
+  page?: number;
+  limit?: number;
+  sort?: string;
+  search?: string;
+  searchField?: string;
+  filter?: Record<string, unknown>;
+  populate?: string;
+}
+
+export const $collectionQuery = atom<CollectionQueryParams | null>(null);
+
+const $collectionUrl = computed($collectionQuery, (params) => {
+  if (!params) return null;
+
+  const searchParams = new URLSearchParams();
+  if (params.page) searchParams.set("page", params.page.toString());
+  if (params.limit) searchParams.set("limit", params.limit.toString());
+  if (params.sort) searchParams.set("sort", params.sort);
+
+  if (params.filter) {
+    for (const [key, value] of Object.entries(params.filter)) {
+      if (typeof value === "object" && value !== null) {
+        // Handle nested filter operators like { status: { equals: 'draft' } }
+        for (const [op, val] of Object.entries(value)) {
+          searchParams.set(`${key}[${op}]`, String(val));
+        }
+      } else {
+        searchParams.set(`${key}[equals]`, String(value));
+      }
+    }
+  }
+
+  if (params.search && params.searchField) {
+    searchParams.set(`${params.searchField}[like]`, `%${params.search}%`);
+  } else if (params.search) {
+    searchParams.set("search", params.search);
+  }
+
+  if (params.populate) {
+    searchParams.set("populate", params.populate);
+  }
+
+  const query = searchParams.toString();
+  return `api/${params.slug}${query ? `?${query}` : ""}`;
+});
+
+export const $collectionData = createFetcherStore<PaginatedResult<Record<string, unknown>>>([
+  $collectionUrl,
+]);
+
+// --- Document Edit ---
+export interface DocumentQueryParams {
+  slug: string;
+  id: string;
+}
+
+export const $documentQuery = atom<DocumentQueryParams | null>(null);
+
+const $documentUrl = computed($documentQuery, (params) => {
+  if (!params) return null;
+  return `api/${params.slug}/${params.id}`;
+});
+
+export const $documentData = createFetcherStore<Record<string, unknown>>([$documentUrl]);
+
+export interface SaveDocumentParams {
+  slug: string;
+  id: string;
+  body: Record<string, unknown>;
+}
+
+export const $saveDocument = createMutatorStore<SaveDocumentParams, Record<string, unknown>>(
+  async ({ data, revalidate }) => {
+    const { slug, id, body } = data;
+    const method = id === "create" ? "post" : "patch";
+    const url = `api/${slug}${id === "create" ? "" : `/${id}`}`;
+
+    const res = await api[method](url, { json: body }).json<Record<string, unknown>>();
+
+    // Revalidate the list and the document
+    revalidate(`api/${slug}`);
+    revalidate(`api/${slug}/${id}`);
+
+    return res;
+  },
+);
+
+// --- Global Edit ---
+export const $globalQuery = atom<string | null>(null);
+
+const $globalUrl = computed($globalQuery, (slug) => {
+  if (!slug) return null;
+  return `api/globals/${slug}`;
+});
+
+export const $globalData = createFetcherStore<Record<string, unknown>>([$globalUrl]);
+
+export interface SaveGlobalParams {
+  slug: string;
+  body: Record<string, unknown>;
+}
+
+export const $saveGlobal = createMutatorStore<SaveGlobalParams, Record<string, unknown>>(
+  async ({ data, revalidate }) => {
+    const { slug, body } = data;
+    const res = await api
+      .patch(`api/globals/${slug}`, { json: body })
+      .json<Record<string, unknown>>();
+
+    revalidate(`api/globals/${slug}`);
+    return res;
+  },
+);

package/src/admin/stores/auth.ts

@@ -0,0 +1,61 @@
+import { atom, computed } from "nanostores";
+import { authClient } from "../auth-client";
+import { notify } from "./ui";
+
+export const $session = atom<any>(null);
+export const $isAuthPending = atom(true);
+
+export const $user = computed($session, (session) => session?.user ?? null);
+export const $isAuthenticated = computed($session, (session) => !!session);
+
+// Synchronize session
+export async function syncSession() {
+  $isAuthPending.set(true);
+  try {
+    const res = await authClient.getSession();
+    $session.set(res.data);
+  } catch (err) {
+    console.error("[OpacaCMS] Failed to sync session:", err);
+  } finally {
+    $isAuthPending.set(false);
+  }
+}
+
+export async function login(data: Record<string, string>) {
+  $isAuthPending.set(true);
+  try {
+    const res = await authClient.signIn.email({
+      email: data.email as string,
+      password: data.password as string,
+    });
+
+    if (res.error) {
+      throw new Error(res.error.message || "Invalid credentials");
+    }
+
+    // Force re-fetch the session from the server immediately after successful sign-in
+    // so the Nano Store reacts and the AdminClient flips from LoginView to DashboardView.
+    await syncSession();
+
+    notify("Logged in successfully", "success");
+    return res;
+  } catch (error) {
+    notify(error instanceof Error ? error.message : "Login failed", "error");
+    throw error;
+  } finally {
+    $isAuthPending.set(false);
+  }
+}
+
+export async function logout() {
+  $isAuthPending.set(true);
+  try {
+    await authClient.signOut();
+    $session.set(null);
+    notify("Logged out successfully");
+  } catch {
+    notify("Logout failed", "error");
+  } finally {
+    $isAuthPending.set(false);
+  }
+}

package/src/admin/stores/column-visibility.ts

@@ -0,0 +1,67 @@
+import { persistentAtom } from "@nanostores/persistent";
+
+/**
+ * Stores column visibility preferences per collection.
+ * Key: collection slug
+ * Value: JSON string of string[] containing visible field names
+ */
+export const $columnVisibility = persistentAtom<Record<string, string[]>>(
+  "opaca-column-visibility",
+  {},
+  {
+    encode: JSON.stringify,
+    decode: JSON.parse,
+  },
+);
+
+/**
+ * Toggle visibility of a column in a collection
+ */
+export function toggleColumnVisibility(slug: string, fieldName: string) {
+  const current = $columnVisibility.get();
+  const visibleColumns = current[slug] || [];
+
+  const nextVisibleColumns = visibleColumns.includes(fieldName)
+    ? visibleColumns.filter((col) => col !== fieldName)
+    : [...visibleColumns, fieldName];
+
+  $columnVisibility.set({
+    ...current,
+    [slug]: nextVisibleColumns,
+  });
+}
+
+/**
+ * Set visible columns for a collection
+ */
+export function setVisibleColumns(slug: string, columns: string[]) {
+  const current = $columnVisibility.get();
+  $columnVisibility.set({
+    ...current,
+    [slug]: columns,
+  });
+}
+
+/**
+ * Initialize column visibility for a collection if not already set.
+ * Uses defaultColumns from config or all available named fields.
+ */
+export function initColumnVisibility(
+  slug: string,
+  fields: { name?: string }[],
+  defaultColumns?: string[],
+) {
+  const current = $columnVisibility.get();
+  if (current[slug]) return; // Already initialized
+
+  // If defaultColumns is provided, use it. Otherwise use all named fields.
+  const initialColumns =
+    defaultColumns && defaultColumns.length > 0
+      ? defaultColumns
+      : fields.filter((f) => f.name).map((f) => f.name!);
+
+  $columnVisibility.set({
+    ...current,
+    [slug]: initialColumns,
+  });
+}

package/src/admin/stores/config.ts

@@ -0,0 +1,15 @@
+import { atom } from "nanostores";
+import type { SerializableConfig } from "../../types";
+
+export const $config = atom<SerializableConfig | null>(null);
+export const $needsInit = atom<boolean>(false);
+export const $isFetchingConfig = atom<boolean>(false);
+export const $hasMetadataError = atom<boolean>(false);
+
+export function setConfig(config: SerializableConfig | null) {
+  $config.set(config);
+}
+
+export function setNeedsInit(needs: boolean) {
+  $needsInit.set(needs);
+}

package/src/admin/stores/media.ts

@@ -0,0 +1,95 @@
+import { persistentAtom } from "@nanostores/persistent";
+import { atom, computed } from "nanostores";
+import { api } from "../api-client";
+import { createFetcherStore } from "./query";
+
+export interface AssetDoc {
+  id: string;
+  key: string;
+  filename: string;
+  originalFilename: string;
+  original_filename?: string;
+  mimeType: string;
+  mime_type?: string;
+  filesize: number;
+  bucket: string;
+  folder: string | null;
+  altText: string | null;
+  alt_text?: string | null;
+  caption: string | null;
+  createdAt: string;
+  updatedAt: string;
+  created_at?: string;
+  updated_at?: string;
+  url?: string;
+  thumbnailUrl?: string;
+}
+
+export interface AssetRegistryData {
+  docs: AssetDoc[];
+  folders: { name: string; buckets: string[] }[];
+  totalDocs: number;
+  limit: number;
+  page: number;
+  totalPages: number;
+}
+
+// Persistent Preferences
+export const $mediaViewMode = persistentAtom<"grid" | "list">("opaca-media-view-mode", "grid");
+export const $mediaSelectedBucket = persistentAtom<string>("opaca-media-selected-bucket", "all");
+export const $bucketColors = persistentAtom<Record<string, string>>(
+  "opaca-bucket-colors",
+  {},
+  {
+    encode: JSON.stringify,
+    decode: JSON.parse,
+  },
+);
+
+// Ephemeral UI State
+export const $mediaCurrentFolder = atom<string>("");
+export const $mediaSearch = atom<string>("");
+export const $mediaPage = atom<number>(1);
+
+// Reactive fetcher based on state
+export const $assets = createFetcherStore<AssetRegistryData>(
+  ["api/__system/assets", $mediaSelectedBucket, $mediaCurrentFolder, $mediaSearch, $mediaPage],
+  {
+    fetcher: (base, bucket, folder, search, page) => {
+      const params = new URLSearchParams({
+        bucket: String(bucket),
+        folder: String(folder),
+        search: String(search),
+        page: String(page),
+        limit: "20",
+      });
+      return api.get(`${base}?${params.toString()}`).json();
+    },
+  },
+);
+
+// Actions
+export const setMediaBucket = (bucket: string) => {
+  $mediaSelectedBucket.set(bucket);
+  $mediaCurrentFolder.set(""); // Reset folder when bucket changes to avoid cross-bucket path issues
+  $mediaPage.set(1); // Reset page on filter change
+};
+
+export const setMediaFolder = (folder: string) => {
+  $mediaCurrentFolder.set(folder);
+  $mediaPage.set(1);
+};
+
+export const setMediaSearch = (search: string) => {
+  $mediaSearch.set(search);
+  $mediaPage.set(1);
+};
+
+export const setMediaPage = (page: number) => {
+  $mediaPage.set(page);
+};
+
+export const setBucketColor = (bucket: string, color: string) => {
+  const current = $bucketColors.get();
+  $bucketColors.set({ ...current, [bucket]: color });
+};

package/src/admin/stores/query.ts

@@ -0,0 +1,13 @@
+import { nanoquery } from "@nanostores/query";
+import { api } from "../api-client";
+
+export const [
+  createFetcherStore,
+  createMutatorStore,
+  { invalidateKeys, revalidateKeys, mutateCache },
+] = nanoquery({
+  fetcher: (...keys) => {
+    const url = keys.join("");
+    return api.get(url).json();
+  },
+});

package/src/admin/stores/ui.ts

@@ -0,0 +1,29 @@
+import { persistentAtom } from "@nanostores/persistent";
+import { atom } from "nanostores";
+
+export interface ToastItem {
+  id: string;
+  message: string;
+  type: "success" | "error" | "info";
+}
+
+export type ToastType = ToastItem["type"];
+
+export const $toasts = atom<ToastItem[]>([]);
+export const $isSidebarCollapsed = persistentAtom<boolean>("opaca-sidebar-collapsed", false, {
+  encode: JSON.stringify,
+  decode: JSON.parse,
+});
+
+export function toggleSidebar() {
+  $isSidebarCollapsed.set(!$isSidebarCollapsed.get());
+}
+
+export function notify(message: string, type: ToastItem["type"] = "success") {
+  const id = Math.random().toString(36).substring(2, 9);
+  $toasts.set([...$toasts.get(), { id, message, type }]);
+}
+
+export function clearToast(id: string) {
+  $toasts.set($toasts.get().filter((t) => t.id !== id));
+}