@picloom/theme-sdk 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lllei
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# @picloom/theme-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+TypeScript contracts for trusted Picloom home and login themes.
+Create a project with `bun create @picloom/theme@0.1.1 ./my-theme`, or install
+the types with `bun add --dev @picloom/theme-sdk@0.1.1`.
+
+```ts
+import type { ThemeContext } from "@picloom/theme-sdk";
+
+export function mount(container: HTMLElement, context: ThemeContext) {
+  const unsubscribe = context.subscribe((state) => {
+    container.textContent = state.site.name;
+  });
+  return { dispose() { unsubscribe(); container.replaceChildren(); } };
+}
+```
+
+Bundle your own framework and dispose listeners and framework instances when unmounted.
+The host injects runtime capabilities; do not import application-internal modules.
+Theme configuration and package assets are public. Theme code is trusted and login
+themes can read entered credentials; install reviewed packages only.
+
+Use `@picloom/create-theme` for a standalone Vue project using the independently maintained
+template in `tools/create-theme/template/`. Horizon in the separate `picloom-extensions/themes/horizon` project is the advanced example.
+
+SDK snapshots and helpers are framework-independent. In Vue themes, assign each `subscribe()` snapshot to a local ref and derive computed values from that ref. Calls such as `t()`, `localized()` and `links.format()` do not establish reactive dependencies in the theme's bundled Vue runtime: do not cache their results in a computed value without explicitly depending on the relevant snapshot fields (`locale` or `copy.format`). The examples call these helpers during rendering, which is triggered by their snapshot subscription. Configuration is fixed for a mount; draft changes are picked up when a new preview is loaded.
+
+Core errors and notifications in snapshots are translated at display time and update with the current language. Recognized error codes use core dictionaries; unknown errors preserve their original text. Themes continue to receive strings and do not need access to core translation keys. Language changes do not restart notification dismissal timers.
+
+## Documentation
+
+- [Quick start](https://llleixx.github.io/picloom/development/theme-tooling.html)
+- [Theme protocol and localized configuration](https://llleixx.github.io/picloom/development/themes.html)
+- [Schema reference](https://llleixx.github.io/picloom/development/schema.html)
+- [Messages and form hints](https://llleixx.github.io/picloom/development/package-localization.html)
+- [Tool maintenance](https://llleixx.github.io/picloom/development/theme-tooling-maintenance.html)
+
+## Development tools / 开发工具
+
+This package exports types only. `@picloom/theme-tools` provides the `picloom-theme`
+CLI for simulated preview, Vite builds and ZIP packaging. `@picloom/create-theme`
+generates a project using both packages. Framework plugins remain in the theme's
+Vite configuration; no development tools are bundled into the theme.
+
+SDK 仅维护主题与宿主之间的公共类型协议。模拟预览、构建和 ZIP 打包由
+`@picloom/theme-tools` 统一维护，脚手架负责生成项目。消费项目使用 `@picloom/theme-sdk@0.1.1`，无需引用本地源码或压缩包。

package/index.ts

@@ -0,0 +1,207 @@
+/** Browser-only public contract. No application/runtime imports. */
+export type Json =
+  | null
+  | boolean
+  | number
+  | string
+  | Json[]
+  | { [key: string]: Json };
+export type Config = Record<string, Json>;
+export type Page = "home" | "login";
+export type Locale = string;
+export type SchemaFormat =
+  | "date"
+  | "time"
+  | "date-time"
+  | "duration"
+  | "email"
+  | "hostname"
+  | "ipv4"
+  | "ipv6"
+  | "uri"
+  | "uri-reference"
+  | "uuid"
+  | "regex";
+/** Static properties/items define structure; branches only constrain existing fields. */
+export interface Field {
+  $schema?: string;
+  type:
+    | "object"
+    | "array"
+    | "string"
+    | "number"
+    | "integer"
+    | "boolean"
+    | "null";
+  properties?: Record<string, Field>;
+  items?: Field;
+  required?: string[];
+  additionalProperties?: false;
+  enum?: Json[];
+  const?: Json;
+  /** Initial draft data only; localized strings use a language dictionary here. */
+  default?: Json;
+  minimum?: number;
+  maximum?: number;
+  exclusiveMinimum?: number;
+  exclusiveMaximum?: number;
+  multipleOf?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  format?: SchemaFormat;
+  minItems?: number;
+  maxItems?: number;
+  uniqueItems?: boolean;
+  allOf?: Constraint[];
+  anyOf?: Constraint[];
+  oneOf?: Constraint[];
+  not?: Constraint;
+  if?: Constraint;
+  then?: Constraint;
+  else?: Constraint;
+  /** String fields only: store a language dictionary and validate each language's string. */
+  "x-localized"?: boolean;
+  "x-ui"?: {
+    labelKey?: string;
+    descriptionKey?: string;
+    enumKeys?: string[];
+    groupKey?: string;
+    order?: number;
+    advanced?: boolean;
+    widget?: "textarea" | "password";
+    visibleWhen?: { path: string; equals: Json };
+  };
+}
+export type Constraint = Omit<
+  Partial<Field>,
+  "properties" | "items" | "default" | "x-ui" | "x-localized"
+> & {
+  properties?: Record<string, Constraint>;
+  items?: Constraint;
+  default?: never;
+  "x-ui"?: never;
+  "x-localized"?: never;
+};
+export interface Manifest {
+  id: string;
+  author?: string;
+  /** Package text fallback only; does not select the visitor or site language. */
+  defaultLocale: Locale;
+  nameKey: string;
+  version: string;
+  apiVersion: 1;
+  supportedLocales: Locale[];
+  pages: Partial<Record<Page, { entry: string; styles?: string[] }>>;
+  styles?: string[];
+  preview?: string;
+  /** Optional object schema; omission permits only an empty configuration. */
+  configSchema?: Field & { type: "object" };
+  messages: Record<Locale, Record<string, string>>;
+}
+export interface ThemeView {
+  manifest: Manifest;
+  config: Config;
+  baseUrl: string;
+  draftLanguage?: { defaultLocale: string; languageRevision: number };
+  languageRevision?: number;
+  siteDefaultLocale?: string;
+  enabledLocales?: string[];
+}
+export interface InstalledTheme extends ThemeView {
+  active: boolean;
+  compatible: boolean;
+}
+export interface Profile {
+  id: string;
+  name: string;
+  enabled: boolean;
+  available: boolean;
+  maxUploadBytes: number;
+  allowedMimeTypes: string[];
+  reason: string | null;
+}
+export interface Upload {
+  id: string;
+  name: string;
+  size: number;
+  profileName: string;
+  sourceUrl?: string;
+  status:
+    | "queued"
+    | "uploading"
+    | "processing"
+    | "success"
+    | "failed"
+    | "cancelled";
+  progress: number;
+  resumable?: boolean;
+  error?: string;
+  result?: { id: string; url: string };
+}
+export interface Snapshot {
+  page: Page;
+  site: {
+    name: string;
+    homeTitle: string;
+    description: string;
+    logoUrl: string;
+    faviconUrl: string;
+  };
+  user: { name: string } | null;
+  locale: Locale;
+  locales: readonly Locale[];
+  languages: readonly { tag: string; name: string; direction: string }[];
+  /** Effective site default (or the preview draft choice), not the package default. */
+  defaultLocale: string;
+  mode: "light" | "dark" | "auto";
+  dark: boolean;
+  profiles: readonly Profile[];
+  selectedProfileId: string;
+  uploads: readonly Upload[];
+  loading: boolean;
+  error: string;
+  login: {
+    busy: boolean;
+    error: string;
+    expired: boolean;
+    unavailable: boolean;
+  };
+  copy: { format: string; auto: boolean; formats: readonly string[] };
+  notice: string;
+}
+export interface ThemeContext {
+  apiVersion: 1;
+  config: Config;
+  getSnapshot(): Snapshot;
+  subscribe(listener: (snapshot: Snapshot) => void): () => void;
+  asset(path: string): string;
+  t(key: string, params?: Record<string, string | number>): string;
+  /** Read current-language administrator text; missing or empty text never falls back. */
+  localized(value: Json | undefined): string;
+  setLocale(locale: Locale): void;
+  setMode(mode: Snapshot["mode"]): void;
+  navigate(page: Page | "app"): void;
+  selectProfile(id: string): void;
+  refresh(): Promise<void>;
+  uploads: {
+    add(files: File[]): void;
+    addUrls(urls: string[]): void;
+    cancel(id: string): Promise<void>;
+    resume(id: string): void;
+    dismiss(id: string): Promise<void>;
+  };
+  links: {
+    format(url: string): string;
+    copy(url: string): Promise<void>;
+    copyAll(): Promise<void>;
+    setPreferences(format: string, auto: boolean): void;
+  };
+  login(username: string, password: string): Promise<void>;
+}
+export interface ThemeModule {
+  mount(
+    container: HTMLElement,
+    context: ThemeContext,
+  ): { dispose(): void } | Promise<{ dispose(): void }>;
+}

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "@picloom/theme-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "type": "module",
+  "types": "./index.ts",
+  "exports": {
+    ".": {
+      "types": "./index.ts"
+    }
+  },
+  "files": [
+    "index.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "description": "Browser-only public contracts for Picloom themes",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/llleixx/picloom-tooling.git",
+    "directory": "theme-sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}