@velastack/cms 0.1.0

package/dist/components/cms/cms-store.svelte.d.ts

@@ -0,0 +1,294 @@
+import { type Tree } from './path.js';
+import type { CmsEntry, CmsPagePointer, CmsScopeEntry } from './scope.js';
+export type CmsScopeRef = {
+    scopeId: string;
+    routeId: string;
+    params: Record<string, string>;
+};
+type DraftBucket = {
+    scope: CmsScopeRef;
+    locale: string;
+    tree: Tree;
+};
+/**
+ * Outcome of a page-delete release item: omit for hard-delete (404 after
+ * publish), set to `gone` for permanent removal (410), or `redirect` to a
+ * target URL for a permanent redirect (308). The CMS server keeps the
+ * outcome on the published tombstone after the release is published.
+ */
+export type PageDeleteOutcome = {
+    kind: 'gone';
+} | {
+    kind: 'redirect';
+    to: string;
+};
+export type ReleaseItem = {
+    kind: 'page';
+    routeId: string;
+    params: Record<string, string>;
+    locale: string;
+    tree: Tree;
+    addedAt: string;
+} | {
+    kind: 'layout';
+    routeId: string;
+    locale: string;
+    tree: Tree;
+    addedAt: string;
+} | {
+    kind: 'site';
+    tree: Tree;
+    addedAt: string;
+} | {
+    kind: 'page-delete';
+    routeId: string;
+    params: Record<string, string>;
+    locale: string;
+    outcome?: PageDeleteOutcome;
+    addedAt: string;
+};
+export type OpenRelease = {
+    userId: string;
+    name?: string;
+    createdAt: string;
+    preview_key: string;
+    items: ReleaseItem[];
+};
+/**
+ * Wire shape of a media library item, mirroring the server's `MediaItem`.
+ * `url` is the public path served by the static handler (e.g. `/uploads/abc.png`).
+ */
+export type MediaItem = {
+    id: string;
+    filename: string;
+    originalName: string;
+    mime: string;
+    size: number;
+    url: string;
+    uploadedAt: string;
+    uploadedBy: string;
+};
+/**
+ * Origin where uploaded media files are served. The backend writes files to
+ * `static/uploads/` and returns relative paths like `/uploads/<slug>.png`; the
+ * frontend lives on a different origin in dev, so we prefix each URL here at
+ * the wire boundary so display components and persisted field values both get
+ * a fully-qualified URL.
+ */
+export declare const MEDIA_URL_PREFIX = "https://velastack.dev";
+declare class CmsStore {
+    isEditing: boolean;
+    drafts: Record<string, DraftBucket>;
+    openRelease: OpenRelease | null;
+    overlay: Record<string, Tree>;
+    /** Per-routeId entries overlay populated by `loadAndApplyEntriesOverlay`. */
+    entriesOverlay: Record<string, CmsEntry[]>;
+    /**
+     * Project-global site bucket. Not localized, not route-bound. `siteOverlay`
+     * holds the merged published+open-release tree fetched client-side from
+     * `${endpoint}/site`; `siteDraft` holds in-flight Site Settings panel
+     * edits awaiting save. `cmsStore.site` returns the merged read of base
+     * (load payload) ∪ overlay ∪ draft.
+     */
+    siteOverlay: Tree | undefined;
+    siteDraft: Tree;
+    /**
+     * Active editor preview locale, pushed in by the admin bar from the URL
+     * (`?locale=`). Falls back to `page.data.cms.locale` when unset (read-only
+     * consumer, or no override). Field components read/write through the
+     * default locale below, so editing in `?locale=es` keys drafts to `es`
+     * even if the consumer's `getLocale(url)` doesn't honor the param.
+     */
+    private _activeLocale;
+    private overlayFetchToken;
+    private entriesFetchToken;
+    toggleEdit(): void;
+    setActiveLocale(locale: string | null): void;
+    private effectiveLocale;
+    /** Base doc (server-rendered) for a scope. Already locale-resolved by `resolveCmsPayload`. */
+    private baseDoc;
+    /** Merged read tree: base ∪ overlay (∪ draft when editing) for the given locale. */
+    private mergedTree;
+    /** Read the merged value at `path`. Returns `undefined` if missing. */
+    getValue(scope: CmsScopeRef, path: string, locale?: string): unknown;
+    /** Whether the editor's draft tree contains a value at `path`. */
+    hasDraft(scope: CmsScopeRef, path: string, locale?: string): boolean;
+    /** Whether the client overlay (published+release) contains a value at `path`. */
+    hasOverlay(scope: CmsScopeRef, path: string, locale?: string): boolean;
+    /** Write a value at `path` into the draft tree. Creates the bucket if needed. */
+    setValue(scope: CmsScopeRef, path: string, value: unknown, locale?: string): void;
+    clearOverlay(): void;
+    /**
+     * Reactive merged site tree: base (load payload) ∪ overlay (client-fetched
+     * `/site` response with preview overlay) ∪ draft (Site Settings panel
+     * edits awaiting save). Reads update live, so a value typed in the panel
+     * appears on the page immediately.
+     *
+     * Drafts are always folded in here (no `isEditing` gate) — the panel
+     * commits to the draft via `setSiteValue` only on Save, so any value
+     * present is already an intentional staged change.
+     */
+    get site(): Record<string, unknown>;
+    getSiteValue(path: string): unknown;
+    setSiteValue(path: string, value: unknown): void;
+    hasSiteDraft(path?: string): boolean;
+    clearSiteDraft(): void;
+    /**
+     * Fetch the merged published+release site tree from `${endpoint}/site`
+     * and apply as a client-side overlay. With `previewKey` the response
+     * includes the user's open-release site item; without it (or with
+     * `versionKey`), the response is published-only / past-snapshot.
+     */
+    loadAndApplySiteOverlay(endpoint: string, previewKey: string | null, opts?: {
+        versionKey?: string | null;
+    }): Promise<void>;
+    /**
+     * Fetch merged published+release content for each scope on the current
+     * route via `${endpoint}/docs` and apply as a client-side overlay.
+     *
+     * `previewKey` selects the user's open release on the server; pass `null`
+     * to fetch published-only content (used post-publish to mask the now-stale
+     * `page.data.cms.docs` on static-export sites).
+     *
+     * `opts.versionKey` (mutually exclusive with `previewKey`) requests the
+     * snapshot at a published release's publish time — `?version=…`.
+     *
+     * `opts.locale` is the BCP-47 locale to request — required, scopes the
+     * overlay cache key so different locales don't collide.
+     *
+     * `opts.defaultLocale` (the consumer's `cms.locales[0]`) enables the
+     * fallback fetch: when `locale !== defaultLocale`, we fetch the default
+     * locale's content in parallel and `mergeLocaleDocs` it under the
+     * requested locale. Adapters return only what's stored for the requested
+     * locale (per the mock-adapter contract); the library composes the
+     * `requested → default → undefined` chain. Mirrors `resolveCmsPayload`.
+     *
+     * `opts.reset` replaces the overlay map wholesale (mount with release,
+     * post-publish, post-discard). Otherwise we merge — keeps unchanged-layout
+     * overlays applied during navigation while new-page scopes load.
+     */
+    loadAndApplyOverlay(endpoint: string, scopes: CmsScopeEntry[], previewKey: string | null, opts: {
+        reset?: boolean;
+        versionKey?: string | null;
+        locale: string;
+        defaultLocale?: string;
+    }): Promise<void>;
+    /**
+     * Refresh the per-routeId entries overlay used by `<CmsEntries>`. One fetch
+     * to `${endpoint}/pages?preview=…&locale=…` covers all `routeIds`; we
+     * filter the response per route. With `previewKey` set, draft and
+     * pending-delete entries are kept; with `previewKey === null`, they're
+     * filtered out — used post-publish to mask stale
+     * `page.data.cms.entries` on static-export sites.
+     *
+     * `opts.defaultLocale` enables the fallback fetch: when the requested
+     * locale isn't the default, we fetch the default locale's entries in
+     * parallel and union by params (requested-locale entries win on metadata
+     * for shared params; default-locale-only entries surface as fallbacks).
+     */
+    loadAndApplyEntriesOverlay(endpoint: string, routeIds: string[], previewKey: string | null, opts: {
+        reset?: boolean;
+        versionKey?: string | null;
+        locale: string;
+        defaultLocale?: string;
+    }): Promise<void>;
+    get isDirty(): boolean;
+    /**
+     * Counts distinct page identities and layout routes touched by the open
+     * release, NOT raw item count: a page edited in `en` and `es` registers
+     * as one. Powers the editor's "X pages draft" mental model — they think
+     * "one page is in progress", not "two storage rows exist". For per-locale
+     * breakdowns (locales panel "EN: 6, ES: 4"), use `workingCopyCountsByLocale`.
+     */
+    get workingCopyCounts(): {
+        pages: number;
+        layouts: number;
+        site: number;
+        total: number;
+    };
+    /**
+     * Per-locale breakdown of the open release's working-copy items. Powers
+     * the Locales panel ("default has 6 edits, es missing 2"). Locales with
+     * zero items don't appear in the map; the panel iterates `cms.locales` to
+     * surface them as "0 edits".
+     */
+    get workingCopyCountsByLocale(): Record<string, {
+        pages: number;
+        layouts: number;
+        total: number;
+    }>;
+    clearDrafts(): void;
+    setOpenRelease(release: OpenRelease | null): void;
+    fetchOpenRelease(endpoint: string): Promise<void>;
+    /**
+     * Atomically rename a page's slug: stage a draft `page` item at the new
+     * params copying content from the published entry, plus a `page-delete`
+     * with a redirect outcome on the old params pointing at the new URL. Both
+     * items go into the open release as a transactional pair, so undo removes
+     * them together. The backend composes this on `POST /pages/rename`.
+     */
+    renameSlug(endpoint: string, args: {
+        routeId: string;
+        fromParams: Record<string, string>;
+        toParams: Record<string, string>;
+        locale: string;
+        toUrl: string;
+    }): Promise<{
+        ok: boolean;
+        release?: OpenRelease;
+    }>;
+    /**
+     * Upload a media file to `${endpoint}/media` and return the full `MediaItem`.
+     * The library panel and inline picker both call this so newly-uploaded items
+     * can be prepended to local state without a re-list.
+     */
+    uploadMedia(endpoint: string, file: File): Promise<MediaItem>;
+    /** Back-compat wrapper around `uploadMedia` that returns just the URL. */
+    uploadImage(endpoint: string, file: File): Promise<string>;
+    listMedia(endpoint: string, params?: {
+        offset?: number;
+        limit?: number;
+    }): Promise<{
+        items: MediaItem[];
+        total: number;
+    }>;
+    deleteMedia(endpoint: string, id: string): Promise<void>;
+    /**
+     * Flush dirty drafts to the server's open release as one item per
+     * (scope, locale), each carrying a partial tree. The server deep-merges
+     * each tree into its matching item in the working copy without publishing.
+     */
+    save(endpoint: string): Promise<{
+        ok: boolean;
+        release?: OpenRelease;
+    }>;
+}
+export declare const cmsStore: CmsStore;
+/**
+ * Public read view of the merged CMS payload: server-loaded `page.data.cms`
+ * with `cmsStore.overlay` applied on top, so authed editors see working-copy
+ * content without a server reload.
+ *
+ * Shape mirrors `CmsPayload` directly via getters (`cms.docs`, `cms.metadata`,
+ * `cms.page`, …). `metadata` is now a thin alias — it reads the page scope's
+ * `metadata` branch from the merged docs.
+ */
+declare class Cms {
+    #private;
+    get locale(): string;
+    get locales(): string[];
+    get docs(): Record<string, Record<string, unknown>>;
+    get scopes(): Record<string, CmsScopeEntry>;
+    get metadata(): Record<string, unknown>;
+    get entries(): Record<string, CmsEntry[]>;
+    get endpoint(): string;
+    get page(): CmsPagePointer | null;
+    /**
+     * Project-wide site settings tree, merged through `cmsStore.site` so panel
+     * edits show up live in preview. Use this in display components instead of
+     * reading `data.cms.site.tree` directly — that's only the SSR seed.
+     */
+    get site(): Record<string, unknown>;
+}
+export declare const cms: Cms;
+export {};