@aglyn/aglyn 1.0.0-beta.215 → 1.0.0-beta.217

package/src/lib/app-utils/theme-library.d.ts

@@ -0,0 +1,206 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { HostTheme } from '@aglyn/shared-data-types';
+import { type ThemeHostDocument } from './marketplace-theme';
+/**
+ * A site's theme library (AGL-3404): the themes a site can switch between,
+ * and the rule that switching, editing and saving never destroy one.
+ *
+ * ## Three layers, one of them picked
+ *
+ * The site renders `theme ⊕ themeOverride` (`resolveSiteTheme`), exactly as
+ * it did before there was a library. What the library adds is WHERE `theme`
+ * came from, named by `themeSelection`:
+ *
+ * - `default` — the platform default. `theme` is empty.
+ * - `preset` — a built-in theme a plugin contributes. `theme` is a copy.
+ * - `custom` — one of the site's own saved themes, kept in the library.
+ * - `installed` — a marketplace theme, kept in the library with the
+ *   provenance an update needs.
+ *
+ * Every edit is an override patch over the picked theme and never a write to
+ * it, so "Restore" is deleting the patch and the theme it restores to is
+ * still exactly the one that was picked. "Save as custom theme" copies the
+ * resolved result into a new library entry; the theme it started from stays
+ * as it was.
+ *
+ * ## Switching keeps each theme's own edits
+ *
+ * Leaving a theme stashes its override on its library entry, and coming back
+ * restores it — so trying another theme is not a way to lose work. A preset
+ * or the default has no content to keep, so its entry holds only the stash.
+ *
+ * ## The site's own settings travel with the site
+ *
+ * `darkScheme` is a decision about the site's content, not about a design
+ * (`THEME_ARTIFACT_FIELDS` says the same for publishing), so it survives every
+ * switch, save and restore: whichever theme is picked, a site that switched
+ * dark off stays light.
+ *
+ * Pure: the console route and the marketplace install route both plan here
+ * and write the plan in their own transaction, so neither can file a switch
+ * differently from the other.
+ */
+/** The host subcollection the library lives in. */
+export declare const THEME_LIBRARY_COLLECTION = "themes";
+/**
+ * The most custom themes one site keeps. A client can read the library, so an
+ * unbounded one is an unbounded read on every visit to the theme page.
+ */
+export declare const THEME_LIBRARY_MAX_CUSTOM = 25;
+/** The longest name a saved theme takes. */
+export declare const THEME_NAME_MAX = 60;
+export type ThemeLibraryKind = 'default' | 'preset' | 'custom' | 'installed';
+/** What `themeSelection` on a host names. */
+export interface HostThemeSelection {
+    kind: ThemeLibraryKind;
+    /** The library entry id (or the preset's entry id). */
+    id: string;
+    /** Shown in the picker; a copy, so a renamed entry renames the selection too. */
+    name: string;
+}
+/** A document in `hosts/{hostId}/themes`. */
+export interface ThemeLibraryEntry {
+    kind: ThemeLibraryKind;
+    name: string;
+    /** The theme itself, for `custom` and `installed`. Never edited in place by the editor. */
+    theme?: HostTheme | null;
+    /** The override stashed while this theme is not the picked one. */
+    override?: unknown;
+    /** Marketplace provenance, for `installed` — what `themeInstalledFrom` is restored from. */
+    installedFrom?: Record<string, unknown> | null;
+    createdAt?: unknown;
+    updatedAt?: unknown;
+}
+/** The entry id the platform default's stash lives under. */
+export declare const DEFAULT_THEME_ENTRY_ID = "default";
+/**
+ * The entry id a pre-library site's own theme is filed under when it first
+ * leaves it. Before the library a site had exactly one theme of its own, so
+ * a fixed id cannot collide with another.
+ */
+export declare const SITE_THEME_ENTRY_ID = "site-theme";
+/** The default's name when nothing else names it. */
+export declare const DEFAULT_THEME_NAME = "Material UI";
+/** A preset's entry id, which holds only its stash. */
+export declare function presetEntryId(presetId: string): string;
+/** A marketplace theme's entry id: one per listing, so reinstalling updates it. */
+export declare function installedEntryId(listingId: string): string;
+/** A host document as the library reads it. */
+export interface ThemeLibraryHost extends ThemeHostDocument {
+    themeSelection?: unknown;
+    themeInstalledFrom?: ({
+        sha256?: string | null;
+        listingId?: string;
+        name?: string;
+    } & Record<string, unknown>) | null;
+}
+/**
+ * The theme a site has picked.
+ *
+ * A site from before the library has no `themeSelection`, and reads as what
+ * it was: a marketplace theme, its own theme, or the default. That is what
+ * lets the library ship without touching a single existing host document.
+ */
+export declare function readThemeSelection(host: ThemeLibraryHost | null | undefined): HostThemeSelection;
+/** A name as stored: trimmed, bounded, and never empty. */
+export declare function normalizeThemeName(name: unknown): string | null;
+/** Marks a field for deletion; the route writing the plan maps it to its store's delete. */
+export declare const THEME_FIELD_DELETE = "__aglynThemeFieldDelete";
+export type ThemeLibraryEntryWrite = {
+    id: string;
+    op: 'create';
+    data: ThemeLibraryEntry;
+} | {
+    id: string;
+    op: 'update';
+    data: Record<string, unknown>;
+} | {
+    id: string;
+    op: 'delete';
+};
+export type ThemeLibraryPlan = {
+    ok: true;
+    /**
+     * Host fields to replace WHOLESALE (`update`, never a deep merge: a
+     * merged override is the union of two patches, and a merged theme keeps
+     * the tokens of the one it replaced).
+     */
+    host: Record<string, unknown>;
+    entries: ThemeLibraryEntryWrite[];
+    /** The theme picked once the plan is written. */
+    selection: HostThemeSelection;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+};
+export type ThemeLibraryTarget = {
+    kind: 'default';
+}
+/** A plugin's theme, sent by the console that listed it. */
+ | {
+    kind: 'preset';
+    id: string;
+    name: string;
+    theme: HostTheme;
+} | {
+    kind: 'custom' | 'installed';
+    id: string;
+};
+export type ThemeLibraryAction = {
+    action: 'select';
+    target: ThemeLibraryTarget;
+} | {
+    action: 'save-as';
+    name: string;
+} | {
+    action: 'update';
+} | {
+    action: 'restore';
+} | {
+    action: 'rename';
+    id: string;
+    name: string;
+} | {
+    action: 'delete';
+    id: string;
+} | {
+    action: 'install';
+    listingId: string;
+    name: string;
+    theme: HostTheme;
+    installedFrom: Record<string, unknown>;
+};
+/**
+ * Plans one library action against the host document and its library as
+ * read in the same transaction.
+ *
+ * `newId` mints a library entry id for a new custom theme.
+ */
+export declare function planThemeLibraryAction(input: {
+    host: ThemeLibraryHost | null | undefined;
+    entries: Readonly<Record<string, ThemeLibraryEntry>>;
+    action: ThemeLibraryAction;
+    newId: () => string;
+}): ThemeLibraryPlan;
+/**
+ * Whether the picked theme carries edits of this site's own — what "Restore"
+ * and "Update" act on. The site's dark-scheme setting is not an edit to the
+ * theme, so an override holding only that does not count.
+ */
+export declare function hasThemeEdits(host: ThemeLibraryHost | null | undefined): boolean;