@setzkasten-cms/ui 0.4.2

package/LICENSE

@@ -0,0 +1,37 @@
+Setzkasten Community License
+
+Copyright (c) 2026 Lilapixel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to use,
+copy, modify, merge, publish, and distribute the Software, subject to the
+following conditions:
+
+1. The above copyright notice and this permission notice shall be included in
+   all copies or substantial portions of the Software.
+
+2. The Software may not be used for commercial purposes without a separate
+   commercial license from the copyright holder. "Commercial purposes" means
+   any use of the Software that is primarily intended for or directed toward
+   commercial advantage or monetary compensation. This includes, but is not
+   limited to:
+   - Using the Software to manage content for a commercial website or product
+   - Offering the Software as part of a paid service
+   - Using the Software within a for-profit organization
+
+3. Non-commercial use is permitted without restriction. This includes:
+   - Personal projects
+   - Open source projects
+   - Educational and academic use
+   - Non-profit organizations
+
+4. A commercial license ("Enterprise License") may be obtained by contacting
+   Lilapixel at hello@lilapixel.de.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,271 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode, MutableRefObject } from 'react';
+import { SetzKastenConfig, ContentRepository, AuthProvider, AssetStore, ContentEventBus, FieldRecord, FieldPath, AnyFieldDef, CollectionDefinition, Result, CommitResult, EntryListItem, EntryData, Asset, TreeNode, AssetMetadata } from '@setzkasten-cms/core';
+import * as zustand from 'zustand';
+
+interface SetzKastenContext {
+    config: SetzKastenConfig;
+    repository: ContentRepository;
+    auth: AuthProvider;
+    assets: AssetStore;
+    eventBus: ContentEventBus;
+}
+interface SetzKastenProviderProps {
+    config: SetzKastenConfig;
+    repository: ContentRepository;
+    auth: AuthProvider;
+    assets: AssetStore;
+    children: ReactNode;
+}
+/**
+ * Root provider – the composition root injects all concrete adapters here.
+ * UI components access ports only via this context (Dependency Inversion).
+ */
+declare function SetzKastenProvider({ config, repository, auth, assets, children, }: SetzKastenProviderProps): react_jsx_runtime.JSX.Element;
+declare function useSetzKasten(): SetzKastenContext;
+declare function useRepository(): ContentRepository;
+declare function useAuth(): AuthProvider;
+declare function useAssets(): AssetStore;
+declare function useEventBus(): ContentEventBus;
+declare function useConfig(): SetzKastenConfig;
+
+interface FormState {
+    /** The schema this form is rendering */
+    schema: FieldRecord | null;
+    /** Current form values (Immer-managed) */
+    values: Record<string, unknown>;
+    /** Values at load time (for dirty checking) */
+    initialValues: Record<string, unknown>;
+    /** Validation errors keyed by dot-path */
+    errors: Record<string, string[]>;
+    /** Field paths the user has interacted with */
+    touched: Set<string>;
+    /** Form lifecycle status */
+    status: 'idle' | 'loading' | 'saving' | 'error';
+    /** Error message when status is 'error' */
+    errorMessage?: string;
+}
+interface FormActions {
+    /** Initialize form with schema and values. If draftValues is provided, values starts as draft but initialValues stays as saved. */
+    init(schema: FieldRecord, values: Record<string, unknown>, draftValues?: Record<string, unknown>): void;
+    /** Set a field value by path */
+    setFieldValue(path: FieldPath, value: unknown): void;
+    /** Get a field value by path */
+    getFieldValue(path: FieldPath): unknown;
+    /** Mark a field as touched */
+    touchField(path: FieldPath): void;
+    /** Check if a specific field is dirty */
+    isFieldDirty(path: FieldPath): boolean;
+    /** Check if any field is dirty */
+    isDirty(): boolean;
+    /** Set validation errors for a field */
+    setFieldErrors(path: FieldPath, errors: string[]): void;
+    /** Clear all validation errors */
+    clearErrors(): void;
+    /** Set form status */
+    setStatus(status: FormState['status'], errorMessage?: string): void;
+    /** Reset form to initial values */
+    reset(): void;
+    /** Undo last change */
+    undo(): void;
+    /** Redo last undone change */
+    redo(): void;
+    /** Whether undo is available */
+    canUndo(): boolean;
+    /** Whether redo is available */
+    canRedo(): boolean;
+    /** Reset to initial values and clear history (Verwerfen) */
+    resetToInitial(): void;
+}
+type FormStore = FormState & FormActions;
+/**
+ * Creates a Zustand vanilla store for form state.
+ * One store per open entry – not a singleton.
+ *
+ * Includes undo/redo via CommandHistory (snapshot-based, debounced).
+ */
+declare function createFormStore(): zustand.StoreApi<FormStore>;
+
+interface RecentEntry {
+    readonly collection: string;
+    readonly slug: string;
+    readonly label: string;
+    readonly timestamp: number;
+}
+interface AppState {
+    currentCollection: string | null;
+    currentSlug: string | null;
+    sidebarOpen: boolean;
+    theme: 'light' | 'dark' | 'system';
+    recentEntries: RecentEntry[];
+}
+interface AppActions {
+    navigate(collection: string, slug: string): void;
+    toggleSidebar(): void;
+    setTheme(theme: AppState['theme']): void;
+    addRecentEntry(entry: Omit<RecentEntry, 'timestamp'>): void;
+}
+type AppStore = AppState & AppActions;
+declare function createAppStore(): zustand.StoreApi<AppStore>;
+
+interface FieldRendererProps {
+    field: AnyFieldDef;
+    path: FieldPath;
+    store: ReturnType<typeof createFormStore>;
+}
+/**
+ * Generic field renderer – looks up the correct component by field type.
+ * Adding a new field type = adding an entry to rendererMap.
+ */
+declare const FieldRenderer: react.NamedExoticComponent<FieldRendererProps>;
+
+interface EntryFormProps {
+    schema: FieldRecord;
+    initialValues: Record<string, unknown>;
+    /** If provided, form starts with these values but initialValues stays as the saved baseline (for dirty detection). */
+    draftValues?: Record<string, unknown>;
+    onSave?: (values: Record<string, unknown>) => void;
+    /**
+     * Optional ref that receives the internal FormStore instance.
+     * Useful for external subscribers (e.g. live preview sync).
+     */
+    storeRef?: MutableRefObject<ReturnType<typeof createFormStore> | null>;
+}
+/**
+ * Generates a complete form from a schema definition.
+ * Each instance creates its own FormStore (one store per entry).
+ */
+declare const EntryForm: react.NamedExoticComponent<EntryFormProps>;
+
+interface EntryListProps {
+    collection: string;
+    label: string;
+    onSelect: (slug: string) => void;
+    onCreate: () => void;
+    selectedSlug?: string;
+}
+/**
+ * List of entries in a collection with create/delete actions.
+ */
+declare function EntryList({ collection, label, onSelect, onCreate, selectedSlug, }: EntryListProps): react_jsx_runtime.JSX.Element;
+
+interface CollectionViewProps {
+    collectionKey: string;
+    collection: CollectionDefinition;
+}
+/**
+ * Full CRUD view for a collection: list on the left, form on the right.
+ */
+declare function CollectionView({ collectionKey, collection }: CollectionViewProps): react_jsx_runtime.JSX.Element;
+
+declare function AdminApp(): react_jsx_runtime.JSX.Element;
+
+type ToastType = 'success' | 'error' | 'info';
+interface ToastContextValue {
+    toast: (message: string, type?: ToastType) => void;
+}
+declare function useToast(): ToastContextValue;
+declare function ToastProvider({ children }: {
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+/**
+ * Hook for individual field state – subscribes only to its own path.
+ * This prevents unnecessary re-renders when other fields change.
+ *
+ * IMPORTANT: All selectors must return referentially stable values
+ * to avoid React 19 useSyncExternalStore infinite loops.
+ */
+declare function useField(store: ReturnType<typeof createFormStore>, path: FieldPath): {
+    value: unknown;
+    errors: string[];
+    isTouched: boolean;
+    isDirty: boolean;
+    setValue: (newValue: unknown) => void;
+    touch: () => void;
+    path: FieldPath;
+};
+
+/**
+ * Hook for saving form content to the repository.
+ */
+declare function useSave(store: ReturnType<typeof createFormStore>, collection: string, slug: string): {
+    save: () => Promise<Result<CommitResult>>;
+    saving: boolean;
+};
+
+interface ProxyConfig {
+    /** Base URL of the Setzkasten API proxy, e.g. '/api/setzkasten/github' */
+    proxyBaseUrl: string;
+    /** GitHub owner */
+    owner: string;
+    /** GitHub repo name */
+    repo: string;
+    /** Branch to operate on */
+    branch: string;
+    /** Base path within the repo for content files, e.g. 'src/content' */
+    contentPath?: string;
+}
+/**
+ * Client-side ContentRepository that calls the server-side GitHub proxy.
+ * The GitHub token never leaves the server – all API calls go through
+ * /api/setzkasten/github/[...path].
+ */
+declare class ProxyContentRepository implements ContentRepository {
+    private baseUrl;
+    private owner;
+    private repo;
+    private branch;
+    private contentPath;
+    constructor(config: ProxyConfig);
+    private apiUrl;
+    private contentFilePath;
+    listEntries(collection: string): Promise<Result<EntryListItem[]>>;
+    getEntry(collection: string, slug: string): Promise<Result<EntryData>>;
+    saveEntry(collection: string, slug: string, data: EntryData, assets?: Asset[]): Promise<Result<CommitResult>>;
+    deleteEntry(collection: string, slug: string): Promise<Result<CommitResult>>;
+    getTree(ref?: string): Promise<Result<TreeNode[]>>;
+    private uploadAsset;
+    private uint8ToBase64;
+}
+
+interface ProxyAssetConfig {
+    /** Base URL of the Setzkasten GitHub proxy */
+    proxyBaseUrl: string;
+    /** GitHub owner */
+    owner: string;
+    /** GitHub repo */
+    repo: string;
+    /** Branch */
+    branch: string;
+    /** Base path for assets in the repo, e.g. 'public/images' */
+    assetsPath?: string;
+    /** Public URL prefix for assets, e.g. '/images' */
+    publicUrlPrefix?: string;
+}
+/**
+ * Asset store that uploads files to GitHub via the server-side proxy.
+ * Preserves original filenames (Setzkasten principle).
+ */
+declare class ProxyAssetStore implements AssetStore {
+    private baseUrl;
+    private owner;
+    private repo;
+    private branch;
+    private assetsPath;
+    private publicUrlPrefix;
+    constructor(config: ProxyAssetConfig);
+    private apiUrl;
+    upload(directory: string, filename: string, content: Uint8Array, mimeType: string): Promise<Result<AssetMetadata>>;
+    delete(path: string): Promise<Result<void>>;
+    list(directory: string): Promise<Result<AssetMetadata[]>>;
+    private listRecursive;
+    private isImageFile;
+    getUrl(path: string): string;
+    getPreviewUrl(path: string): string;
+    private uint8ToBase64;
+    private guessMimeType;
+}
+
+export { AdminApp, type AppActions, type AppState, type AppStore, CollectionView, EntryForm, EntryList, FieldRenderer, type FieldRendererProps, type FormActions, type FormState, type FormStore, type ProxyAssetConfig, ProxyAssetStore, type ProxyConfig, ProxyContentRepository, type RecentEntry, type SetzKastenContext, SetzKastenProvider, ToastProvider, createAppStore, createFormStore, useAssets, useAuth, useConfig, useEventBus, useField, useRepository, useSave, useSetzKasten, useToast };