@monkey-mini-app/panel 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,401 @@
+import { TokenSet } from './themes.js';
+export { CustomPaletteMap, ModeId, PALETTES, PaletteId, applyThemeTo, clampMode, clampPalette, cssVars, parseThemeCss, runnerThemeCss, themeLabelFromCss, tokensOf } from './themes.js';
+import * as react from 'react';
+
+declare const LOCALE_IDS: readonly ["zh-CN", "en"];
+type LocaleId = (typeof LOCALE_IDS)[number];
+type AppItem = {
+    id: string;
+    name: string;
+    description?: string;
+    acronym?: string;
+    commits?: number;
+    version?: string;
+    theme?: {
+        theme: string;
+        palette: string;
+    } | null;
+};
+type TabKind = "all" | "app";
+type TabItem = {
+    id: string;
+    title: string;
+    kind: TabKind;
+    app?: AppItem;
+};
+type BrowseKind = "history" | "storage";
+type ThemeScope = "global" | "app";
+type DockId = "fill" | "side";
+type CardStyle = "stamp" | "etch" | "hero" | "list";
+type CommitFile = {
+    path: string;
+    add?: number;
+    del?: number;
+    preview?: string;
+};
+type Commit = {
+    id: string;
+    message: string;
+    time: string;
+    files?: CommitFile[];
+};
+type StorageTable = {
+    name: string;
+    size?: number;
+    updatedAt?: string;
+};
+type PanelCapabilities = {
+    history: boolean;
+    storage: boolean;
+    config: boolean;
+    appTheme: boolean;
+    customPalettes: boolean;
+    deleteApp: boolean;
+};
+type PanelActions = {
+    openAppTab: (app: AppItem) => void;
+    closeTab: (id: string) => void;
+    switchTab: (id: string) => void;
+    setDock: (next: DockId) => void;
+    setQuery: (q: string) => void;
+    toggleThemePop: () => void;
+    setAppearance: (next: {
+        theme?: string;
+        palette?: string;
+    }, scope: string) => void;
+    setThemeScope: (scope: ThemeScope) => void;
+    clearAppTheme: () => void;
+    getActiveApp: () => AppItem | null;
+    toggleSettings: (open: boolean) => void;
+    getCfg: () => Record<string, string>;
+    saveHostConfig: (form: Record<string, string>) => void;
+    toggleBrowse: (kind: string) => void;
+    loadCommitDetail: (id: string) => void;
+    loadTable: (name: string) => void;
+    browseBack: () => void;
+    browseFile: (path: string) => void;
+    reloadActive: () => void;
+    askDelete: () => void;
+    hideModal: () => void;
+    confirmDelete: () => void | Promise<void>;
+    closeDashboard: () => void;
+    fetchApps: () => void;
+    setCardStyle: (v: CardStyle) => void;
+};
+type PanelState = {
+    tabs: TabItem[];
+    active: string;
+    apps: AppItem[];
+    error: string | null;
+    loading: boolean;
+    query: string;
+    dock: DockId;
+    theme: string;
+    palette: string;
+    themeScope: ThemeScope;
+    customPalettes: Record<string, {
+        label?: string;
+        swatch?: string;
+        tokens?: unknown;
+    }>;
+    cardStyle: CardStyle;
+    visible: boolean;
+    pendingDelete: string | null;
+    themePopOpen: boolean;
+    settingsOpen: boolean;
+    cfgMsg: string;
+    cfgVersion: number;
+    cfg: Record<string, string>;
+    emptyText: string | undefined;
+    capabilities: PanelCapabilities;
+    locale: LocaleId;
+    browseOpen: boolean;
+    browseKind: BrowseKind;
+    browseAppId: string | null;
+    browseAppName: string;
+    browseLoading: boolean;
+    browseError: string | null;
+    browseList: unknown[];
+    browseDetail: unknown;
+    browseTable: string | null;
+    browseTableValue: unknown;
+    browseOpenFile: string | null;
+};
+
+type I18nParams = Record<string, string | number>;
+type PanelI18n = {
+    readonly locale: LocaleId;
+    t(key: string, params?: I18nParams): string;
+};
+/** i18next helper bound to `locale`. Missing keys throw outside production. */
+declare function createPanelI18n(locale: LocaleId): PanelI18n;
+declare function resolvePanelLocale(value: string | undefined): LocaleId;
+
+/**
+ * PanelHost — the only seam between the panel UI and a host (dsh client, demo, …).
+ * Optional fields hide the matching chrome (history / storage / settings / delete).
+ */
+
+type Palette = {
+    id: string;
+    label: string;
+    swatch: string;
+    tokens?: {
+        light: TokenSet;
+        dark: TokenSet;
+    };
+};
+interface PanelHost {
+    /** Locale for panel chrome. Falls back to createMiniAppPanel options, then zh-CN. */
+    locale?: LocaleId;
+    fetchApps(): Promise<AppItem[]>;
+    frame: {
+        url(appId: string): string;
+        mount(appId: string): void;
+        unmount(appId: string): void;
+        reload(appId: string): void;
+        /** Push current theme/palette/dock into open app iframes. */
+        syncEnv?(): void;
+    };
+    openPanel(): void;
+    closePanel(): void;
+    palettes?(): Promise<Palette[]>;
+    persistTheme?(theme: string, palette: string): void;
+    appTheme?: {
+        save(appId: string, t: {
+            theme: string;
+            palette: string;
+        }): Promise<void>;
+        clear(appId: string): Promise<void>;
+    };
+    config?: {
+        load(): Promise<Record<string, string>>;
+        save(cfg: Record<string, string>): Promise<void>;
+    };
+    history?: {
+        list(appId: string): Promise<Commit[]>;
+        detail(appId: string, id: string): Promise<Commit>;
+    };
+    storage?: {
+        listTables(appId: string): Promise<StorageTable[]>;
+        readTable(appId: string, name: string): Promise<unknown>;
+    };
+    onOpenRequest?(cb: (appId?: string) => void): () => void;
+    emptyText?: string;
+    deleteApp?(appId: string): Promise<void>;
+}
+declare function capabilitiesOf(host: PanelHost): PanelCapabilities;
+
+declare function activeAppFrom(state: PanelState): AppItem | null;
+declare function createPanelActions(host: PanelHost, getRootEl: () => HTMLElement | null, i18n: PanelI18n): PanelActions;
+declare function defaultHideThemePop(): boolean;
+declare function clampPaletteId(v: unknown): string;
+
+declare function AppList(): react.JSX.Element;
+declare function ListRegion(): react.JSX.Element;
+
+declare function Browse(): react.JSX.Element | null;
+
+declare function Loading(): react.JSX.Element;
+
+declare function MiniAppPanel(): react.JSX.Element;
+
+declare function Modal(): react.JSX.Element | null;
+
+declare function Settings(): react.JSX.Element | null;
+
+declare function Tabs(): react.JSX.Element;
+
+declare function ThemePop(): react.JSX.Element;
+
+declare function Toolbar(): react.JSX.Element;
+
+declare function PanelProvider({ actions, i18n, children, }: {
+    actions: PanelActions;
+    i18n: PanelI18n;
+    children: react.ReactNode;
+}): react.JSX.Element;
+declare function usePanelActions(): PanelActions;
+declare function usePanelI18n(): PanelI18n;
+
+declare class PanelError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+
+/**
+ * FrameController — browser iframe hosting for mini-apps.
+ *
+ * Reusable chrome: mounts an app iframe into a given container, posts the
+ * current theme/palette/dock env into it (the appRunnerHtml listens for
+ * `mma-set-env`), and shows a loading overlay. Host-agnostic: the container and
+ * an `envOf(appId)` accessor are injected, so dsh and apps/react-host both use it.
+ */
+type FrameEnv = {
+    theme: string;
+    palette: string;
+    dock: string;
+};
+type FrameRecord = {
+    wrap: HTMLElement;
+    iframe: HTMLIFrameElement;
+};
+type FrameController = {
+    url(appId: string): string;
+    mount(appId: string, title?: string): void;
+    unmount(appId: string): void;
+    unmountAll(): void;
+    reload(appId: string): void;
+    postEnv(appId: string): void;
+    postEnvAll(): void;
+    /** Set/rebind the container the app iframes mount into (e.g. the panel's #mma-frames). */
+    setContainer(el: HTMLElement): void;
+    readonly map: Map<string, FrameRecord>;
+};
+type FrameControllerOptions = {
+    /** The element app iframes mount into; may be bound later via setContainer. */
+    container?: HTMLElement | null;
+    /** Build the iframe src for an app. Usually appFrameUrl(origin, appId, env). */
+    urlOf(appId: string): string;
+    /** Current env for an app (theme/palette/dock), posted via mma-set-env. */
+    envOf(appId: string): FrameEnv;
+};
+declare function createFrameController(opts: FrameControllerOptions): FrameController;
+
+type CreateMiniAppPanelOptions = {
+    locale?: LocaleId;
+};
+interface PanelInstance {
+    actions: PanelActions;
+    mount(el: HTMLElement): void;
+    unmount(): void;
+    open(): void;
+    close(): void;
+}
+declare function createMiniAppPanel(host: PanelHost, options?: CreateMiniAppPanelOptions): PanelInstance;
+
+/**
+ * createHostShell — reusable outer host chrome for mini-apps.
+ *
+ * Assembles the panel↔host seam in one call: a `PanelHost` (REST to a
+ * `packages/host` server), a frame controller for the app iframes, and a mount
+ * that renders `MiniAppPanel` into a container with theme apply/persist. Host
+ * layout details (dock tab sizing, sidebar sync) are supplied by the caller via
+ * injected callbacks; this shell owns the theme + panel + frames.
+ *
+ * Both the dsh plugin and a standalone apps/react-host SPA use this.
+ */
+
+type HostShellOptions = {
+    /** Origin to a `packages/host` Hono server (e.g. http://127.0.0.1:17880). */
+    hostUrl: string;
+    /** Persistence backend. Defaults to window.localStorage. */
+    storage?: Pick<Storage, "getItem" | "setItem" | "removeItem"> | null;
+    cardStyle?: CardStyle;
+    locale?: string;
+    emptyText?: string;
+    /** Optional: resolve the host URL (defaults to the passed hostUrl). */
+    resolveHostUrl?: (current: string, storage: HostShellOptions["storage"]) => string;
+    /** Fired when the host reports a new port. */
+    onHostChange?: (nextHostUrl: string) => void;
+    /** Dock layout hooks — real layout is host-specific; shell just tracks dock state. */
+    layout?: {
+        setDock?(dock: DockId): void;
+        getDock?(): DockId;
+    };
+    onOpen?: () => void;
+    onClose?: () => void;
+};
+interface HostShellInstance {
+    panel: PanelInstance;
+    host: PanelHost;
+    frames: FrameController;
+    mount(el: HTMLElement): void;
+    unmount(): void;
+    openPanel(): void;
+    closePanel(): void;
+    toggle(): void;
+    /** Persist theme to storage + re-apply to the panel host DOM + push to frames. */
+    persistTheme(theme: string, palette: string): void;
+    setCardStyle(v: CardStyle): void;
+    setDock(v: DockId): void;
+}
+declare function createHostShell(opts: HostShellOptions): HostShellInstance;
+
+/** Pure panel helpers. */
+
+declare function hue(id: string): number;
+declare function appBlurb(a: AppItem): string;
+declare function monoOf(a: AppItem): string;
+
+/**
+ * RestPanelHost — a host-agnostic `PanelHost` backed by a mini-app host over HTTP.
+ *
+ * This is the reusable core of the panel↔host seam: it knows how to talk to a
+ * `packages/host` Hono server (/api/*) and persist theme prefs, but knows nothing
+ * about dsh. Both the dsh plugin and a standalone `apps/react-host` SPA implement
+ * the same `PanelHost` by wrapping this. All data/HTTP logic lives here; the panel
+ * never contains /api strings.
+ */
+
+type RestOptions = {
+    /** Origin to reach a `packages/host` Hono server (e.g. http://127.0.0.1:17880). */
+    hostUrl: string;
+    /** Optional: resolve the host URL dynamically (host-port migration). Defaults to hostUrl. */
+    getHostUrl?: () => string;
+    /** Persistence backend for theme prefs. Defaults to window.localStorage. */
+    storage?: Pick<Storage, "getItem" | "setItem"> | null;
+    /** The current host's card style (for host-config form defaults). */
+    cardStyle?: CardStyle;
+    /** Optional: resolve the current card style dynamically (defaults to cardStyle). */
+    getCardStyle?: () => CardStyle;
+    locale?: LocaleId;
+    emptyText?: string;
+    /** Optional overrides for opening/closing the panel (SPA wiring). */
+    onOpen?: () => void;
+    onClose?: () => void;
+    /** Fired when the host reports a new port (e.g. after saving a different hostPort). */
+    onHostChange?: (nextHostUrl: string) => void;
+    /** Fired after a successful host-config save (theme/cardStyle/origin side effects). */
+    onConfigSaved?: (form: Record<string, string>) => void;
+    /** Iframe control — provide a function that mounts/unmounts the app iframe. */
+    frameController?: PanelHost["frame"];
+    deleteApp?: (appId: string) => Promise<void>;
+};
+declare function readJson(url: string, init?: RequestInit): Promise<unknown>;
+/** Thrown when a `packages/host` server cannot be reached at the network level (port blocked / host not started). */
+declare class HostUnreachableError extends Error {
+    readonly url: string;
+    constructor(url: string, cause?: unknown);
+}
+declare function isHostUnreachable(e: unknown): e is HostUnreachableError;
+declare function appFrameUrl(origin: string, appId: string, query: {
+    theme: string;
+    palette: string;
+    dock: string;
+}): string;
+declare function parseAppsResponse(raw: unknown): AppItem[];
+declare function hostConfigToForm(raw: unknown, cardStyle: string): Record<string, string>;
+declare function formToHostConfigBody(form: Record<string, string>): Record<string, unknown>;
+declare function parseCommitList(raw: unknown): Commit[];
+declare function parseCommitDetail(raw: unknown, id: string): Commit;
+declare function parseStorageTables(raw: unknown): StorageTable[];
+declare function parsePalettes(raw: unknown): Palette[];
+/** Build a `PanelHost` that talks to a `packages/host` Hono server over HTTP. */
+declare function createRestPanelHost(opts: RestOptions): PanelHost;
+
+declare function getPanelState(): PanelState;
+declare function setPanelState(patch: Partial<PanelState>): PanelState;
+declare function subscribePanel(listener: () => void): () => void;
+declare function resetPanelState(seed?: Partial<PanelState>): PanelState;
+declare function usePanelState(): PanelState;
+
+/** Injected panel CSS (dsh-style data-plugin-css). Host calls injectPanelCss() on mount. */
+declare const PANEL_CSS_TAG = "panel";
+declare function injectPanelCss(): void;
+
+declare const packageName = "@monkey-mini-app/panel";
+
+export { type AppItem, AppList, Browse, type BrowseKind, type CardStyle, type Commit, type CommitFile, type CreateMiniAppPanelOptions, type DockId, type FrameController, type FrameControllerOptions, type FrameEnv, type FrameRecord, type HostShellInstance, type HostShellOptions, HostUnreachableError, type I18nParams, LOCALE_IDS, ListRegion, Loading, type LocaleId, MiniAppPanel, Modal, PANEL_CSS_TAG, type Palette, type PanelActions, type PanelCapabilities, PanelError, type PanelHost, type PanelI18n, type PanelInstance, PanelProvider, type PanelState, type RestOptions, Settings, type StorageTable, type TabItem, type TabKind, Tabs, ThemePop, type ThemeScope, TokenSet, Toolbar, activeAppFrom, appBlurb, appFrameUrl, capabilitiesOf, clampPaletteId, createFrameController, createHostShell, createMiniAppPanel, createPanelActions, createPanelI18n, createRestPanelHost, defaultHideThemePop, formToHostConfigBody, getPanelState, hostConfigToForm, hue, injectPanelCss, isHostUnreachable, monoOf, packageName, parseAppsResponse, parseCommitDetail, parseCommitList, parsePalettes, parseStorageTables, readJson, resetPanelState, resolvePanelLocale, setPanelState, subscribePanel, usePanelActions, usePanelI18n, usePanelState };