@wocart/theme 0.0.0-stage → 1.1.0

package/dist/types.d.ts

@@ -0,0 +1,479 @@
+/**
+ * The `@wocart/theme` contract — every type in one place.
+ *
+ * Two sides, one seam:
+ * - code-owned: `ThemeDefinition` / `ComponentDefinition` (never serialized);
+ * - data-owned: `ComponentInstance` / `PageData` (always JSON).
+ */
+import type { StoreClient } from "@wocart/storefront/server";
+import type { StoreConfig } from "@wocart/storefront";
+/** Every value page data may hold. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** A JSON object, as stored in `ComponentInstance.props`. */
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+/**
+ * A BCP 47 language tag in canonical case: `ar`, `fr`, `en`, `ar-DZ`, `zgh`.
+ * A plain string type on purpose: the set of languages is platform data, never
+ * a closed enum baked into the contract.
+ */
+export type LocaleCode = string;
+/**
+ * Text that is the same in every language (a plain string), or one value per
+ * language. Used for translatable field values, translatable text defaults, and
+ * editor-facing labels.
+ */
+export type LocalizedText = string | Readonly<Record<LocaleCode, string>>;
+/**
+ * What resolution needs besides the instance: the theme's content pack for
+ * the language being rendered, and the language preference — the requested
+ * language first, then the store's fallback chain.
+ */
+export interface ResolutionScope {
+    content?: Record<string, string>;
+    locales?: readonly LocaleCode[];
+}
+/** The field kinds. `color` and `menu` were added after V1, additively. */
+export type FieldKind = "text" | "textarea" | "number" | "boolean" | "select" | "url" | "color" | "menu";
+interface FieldDefinitionBase {
+    /** The exact prop name the component expects. */
+    key: string;
+    /** Editor-facing name, the same in every language or translated. */
+    label: LocalizedText;
+    /** Editor-facing help text. */
+    description?: LocalizedText;
+    required?: boolean;
+}
+/**
+ * `text` / `textarea`: a string that defaults from the content pack
+ * (`contentKey`) or from a literal (`default`) — mutually exclusive.
+ */
+export interface TextFieldDefinition extends FieldDefinitionBase {
+    kind: "text" | "textarea";
+    /**
+     * The key in the **theme's own** content pack that supplies this field's
+     * creation-time value. The SDK never models the pack: it reads
+     * `ThemeRenderContext.content` — an opaque flat string map — and falls
+     * through to `default` → omit when the key is absent. Pass the pack's key set
+     * to `validateThemeDefinition` to have typos reported.
+     */
+    contentKey?: string;
+    /**
+     * Literal creation-time default (mutually exclusive with `contentKey`), the
+     * same in every language or translated. Prefer `contentKey` for theme copy:
+     * the pack is already per language.
+     */
+    default?: LocalizedText;
+}
+/** `number`: a finite number, optionally bounded. */
+export interface NumberFieldDefinition extends FieldDefinitionBase {
+    kind: "number";
+    default?: number;
+    min?: number;
+    max?: number;
+}
+/** `boolean`. */
+export interface BooleanFieldDefinition extends FieldDefinitionBase {
+    kind: "boolean";
+    default?: boolean;
+}
+/** `select`: one of a closed option list. */
+export interface SelectFieldDefinition extends FieldDefinitionBase {
+    kind: "select";
+    options: readonly string[];
+    default?: string;
+}
+/**
+ * `url`: a link target an editor may set, safe to render as an `href`. Only a
+ * site path (`/products`), a fragment (`#best-sellers`), a query (`?page=2`),
+ * `http(s)://`, `mailto:` or `tel:` is accepted. Anything else, including
+ * `javascript:`, `data:`, protocol-relative `//host` and backslash tricks, is
+ * rejected at assembly and reported as `invalid-prop` on read.
+ */
+export interface UrlFieldDefinition extends FieldDefinitionBase {
+    kind: "url";
+    default?: string;
+}
+/** `color`: a hex color, `#rgb` or `#rrggbb`. Not translatable. */
+export interface ColorFieldDefinition extends FieldDefinitionBase {
+    kind: "color";
+    default?: string;
+}
+/**
+ * `menu`: which of the store's menus to show here — Shopify's `link_list`.
+ * The value is a menu handle (`main-menu`); the theme reads the menu with
+ * the storefront client's `menus.get(handle)`. A theme never assumes a menu
+ * exists: an unknown handle reads as no menu.
+ */
+export interface MenuFieldDefinition extends FieldDefinitionBase {
+    kind: "menu";
+    default?: string;
+}
+export type FieldDefinition = TextFieldDefinition | NumberFieldDefinition | BooleanFieldDefinition | SelectFieldDefinition | UrlFieldDefinition | ColorFieldDefinition | MenuFieldDefinition;
+/**
+ * One composition point a component declares (`"default"` = children).
+ *
+ * **Renderer ceiling (V1):** the reference renderer (`@wocart/theme/astro`)
+ * fills **at most one named slot** per instance. The Astro compiler lifts the
+ * first slot-attribute expression of a dynamic child expression into the
+ * slots-object key, evaluated at component scope, so per-item slot names inside
+ * a `.map()` are not expressible. Any further named slot **with content** is
+ * reported as `multiple-slots-unsupported` — never silently dropped.
+ *
+ * Declaring several named slots is legal; it is a capability declaration, not a
+ * promise that all of them can be filled at once. A component that needs more
+ * than one filled can transfer Astro's own slots inside itself
+ * (`<slot name="x" slot="x" />`) — a component-level decision, deliberately not
+ * part of this contract.
+ */
+export interface SlotDefinition {
+    /** `"default"` or a lowercase kebab-case name. */
+    name: string;
+    /** False = at most one child instance. Defaults to true. */
+    multiple?: boolean;
+    /**
+     * The component types this slot accepts (catalog keys). Absent = any type.
+     * Assembly rejects a type that is not in the catalog; the reader drops a
+     * child of any other type with a `disallowed-child` issue. Narrowing a list
+     * after documents are saved hides their children, so treat it like removing
+     * a slot.
+     */
+    allow?: readonly string[];
+}
+/**
+ * What a component permits.
+ *
+ * V1 carries one flag, and it is **advisory**: `insertable` is metadata for an
+ * editor/CLI's insertion palette. Neither `parsePageData` nor `resolveInstance`
+ * enforces it — a saved document containing a non-insertable component still
+ * renders, and the renderer reports only what the document tells it. The render
+ * path never second-guesses a document that was already saved. Enforcement, when
+ * it exists, belongs at *insertion* time in the writer, not at render.
+ */
+export interface ComponentCapabilities {
+    insertable?: boolean;
+}
+/** The request facts available while rendering (formalises `Astro.locals.store` + URL). */
+export interface ThemeRenderContext {
+    store: StoreConfig;
+    /**
+     * The theme's resolved content pack: an opaque, flat string map with store
+     * overrides already merged. The SDK reads it (through a field's `contentKey`)
+     * and never shapes it — the taxonomy belongs to the theme, and the theme owns
+     * how its components consume the pack.
+     */
+    content: Record<string, string>;
+    /**
+     * The language being rendered (BCP 47). Translatable field values resolve
+     * to it first; `content` is the pack for it.
+     */
+    locale: LocaleCode;
+    /**
+     * The store's fallback chain after `locale`, in order (e.g. the store's
+     * primary language, then the platform default). A translatable value with
+     * no entry for `locale` tries these before the pack and the default.
+     */
+    fallbackLocales?: readonly LocaleCode[];
+    isRTL: boolean;
+    /** Request pathname. */
+    url: string;
+    /**
+     * The route's dynamic segments (`Astro.params`), e.g. `{ slug: "chair" }` on
+     * `/products/[slug]`. A section on a templated surface reads its route
+     * resource through these, with a `reads` key that includes them, instead of
+     * parsing `url`.
+     */
+    params?: Readonly<Record<string, string | undefined>>;
+}
+/** Per-render read sharing; the renderer provides the implementation. */
+export interface ReadCache {
+    get<T>(key: string, load: () => T | Promise<T>): Promise<T>;
+}
+/** What a `load` hook receives. Server-only; reads go through the storefront SDK. */
+export interface LoadContext {
+    storefront: StoreClient;
+    context: ThemeRenderContext;
+    /**
+     * The resolved field values for this instance.
+     *
+     * The renderer merges `load`'s return value **over** these
+     * (`{ ...props, ...loaded }`), so a load-returned key wins over a field of
+     * the same name. A definition whose component reads a prop from `load` should
+     * keep that name out of `fields`.
+     */
+    props: Record<string, unknown>;
+    reads: ReadCache;
+}
+/** Server-side data fetch for one component definition. */
+export type LoadFn = (context: LoadContext) => Promise<Record<string, unknown>>;
+/**
+ * Code-owned description of one reusable component. `component` is the real
+ * component reference — opaque here so the core stays framework-neutral; the
+ * `./astro` renderer narrows it.
+ */
+export interface ComponentDefinition {
+    /** Stable type identity: lowercase kebab-case, unique in the catalog. */
+    type: string;
+    component: unknown;
+    label: LocalizedText;
+    /** The editor palette heading this component is listed under. */
+    group?: LocalizedText;
+    fields?: readonly FieldDefinition[];
+    slots?: readonly SlotDefinition[];
+    load?: LoadFn;
+    capabilities?: ComponentCapabilities;
+}
+/** The value type one field resolves to. A select narrows to its option literals. */
+export type FieldValue<F extends FieldDefinition> = F extends {
+    kind: "number";
+} ? number : F extends {
+    kind: "boolean";
+} ? boolean : F extends {
+    kind: "select";
+    options: readonly (infer Option)[];
+} ? Option : string;
+type FieldsOf<D> = D extends {
+    fields: readonly (infer F extends FieldDefinition)[];
+} ? F : never;
+type FieldProps<D> = {
+    [F in FieldsOf<D> as F extends {
+        default: unknown;
+    } ? F["key"] : never]: FieldValue<F>;
+} & {
+    [F in FieldsOf<D> as F extends {
+        default: unknown;
+    } ? never : F["key"]]?: FieldValue<F>;
+};
+type LoadedProps<D> = D extends {
+    load: (context: LoadContext) => Promise<infer L>;
+} ? L : {};
+/**
+ * The props `InstanceView` passes to a definition's component, derived from
+ * the definition so the component and its fields cannot drift apart:
+ *
+ * ```ts
+ * type Props = InferProps<typeof heroDefinition>;
+ * ```
+ *
+ * A field with a `default` is always present; any other field may be absent
+ * (no value, no content, or reported as invalid). Whatever `load` returns is
+ * merged over the fields, as the renderer does at runtime. Use `defineComponent`
+ * so field keys, kinds and select options keep their literal types.
+ */
+export type InferProps<D extends ComponentDefinition> = Omit<FieldProps<D>, keyof LoadedProps<D>> & LoadedProps<D>;
+/** The catalog a theme ships — the unit the renderer and validator consume. */
+export interface ThemeDefinition {
+    key: string;
+    version: string;
+    /**
+     * The surfaces this theme can render, declared as data. Optional and
+     * additive: a theme that declares none is treated as declaring none, and no
+     * existing page-document behavior changes — `parsePageData` /
+     * `validatePageData` never consult this list. Surface *enforcement* (rejecting
+     * a document whose surface the theme does not serve) is a later, separately
+     * tested concern; the manifest carries the declaration now so an editor can
+     * offer only valid surfaces.
+     */
+    surfaces?: readonly SurfaceSpec[];
+    /**
+     * The languages this theme's content packs cover (BCP 47), e.g.
+     * `["ar", "fr", "en"]`. Declared, the validator requires every translated
+     * label to cover all of them, and the manifest tells an editor which
+     * languages the theme can serve. Absent means "not declared".
+     */
+    locales?: readonly LocaleCode[];
+    /**
+     * The theme's global settings: what a merchant may change about the whole
+     * theme (its font, its colors, which menu the header shows), declared with
+     * the same fields sections use, in named groups. Optional and additive. A
+     * store's values are read with `resolveThemeSettings`; a writer checks them
+     * with `checkThemeSettings`. Setting keys are unique across all groups.
+     */
+    settings?: readonly SettingsGroup[];
+    components: Record<string, ComponentDefinition>;
+}
+/** One group of theme settings, as an editor lists them ("Typography", "Header"). */
+export interface SettingsGroup {
+    /** Lowercase kebab-case, unique in the theme. */
+    key: string;
+    label: LocalizedText;
+    fields: readonly FieldDefinition[];
+}
+/**
+ * One surface a theme declares it can render.
+ *
+ * `key` uses the same surface-key pattern as the page-document envelope
+ * (`SURFACE_KEY_PATTERN` in `schemas.ts`); `label` is the editor-facing name.
+ */
+export interface SurfaceSpec {
+    key: string;
+    label: LocalizedText;
+}
+/**
+ * One component as data: a `ComponentDefinition` minus its runtime-only
+ * implementation. `component` (the live component reference) and `load` (the
+ * server-only data hook) are intentionally absent — neither is
+ * JSON-serializable and neither belongs in a tooling contract.
+ *
+ * `fields` / `slots` are always present (normalized from absent to `[]` by the
+ * generator) so consumers never branch on "missing vs empty".
+ */
+export interface ComponentSpec {
+    /** Stable type identity: lowercase kebab-case, equal to the catalog key. */
+    type: string;
+    /** Editor-facing name. */
+    label: LocalizedText;
+    /** The editor palette heading this component is listed under. */
+    group?: LocalizedText;
+    fields: readonly FieldDefinition[];
+    slots: readonly SlotDefinition[];
+    capabilities?: ComponentCapabilities;
+}
+/**
+ * The serializable theme contract.
+ *
+ * - `contractVersion` identifies this manifest's schema and interpretation
+ *   contract (currently `1`). It versions the *format*, not the theme.
+ * - `key` / `version` identify the *theme* (same values as `ThemeDefinition`).
+ * - `surfaces` declares what the theme can render (possibly empty).
+ * - `components` is the data-only catalogue, keyed by component type.
+ *
+ * Three versioned contracts coexist and must not be confused:
+ * `contractVersion` (this manifest), `ThemeDefinition.version` (the theme's
+ * semver), and `PageData.version` (the page-document envelope, currently `1`).
+ */
+export interface ThemeManifest {
+    contractVersion: 1;
+    key: string;
+    version: string;
+    surfaces: readonly SurfaceSpec[];
+    /** The languages the theme's packs cover (possibly none declared). */
+    locales: readonly LocaleCode[];
+    /** The theme's global settings (possibly none). */
+    settings: readonly SettingsGroup[];
+    components: Record<string, ComponentSpec>;
+}
+export type ThemeManifestIssueCode = "invalid-manifest" | "unsupported-contract" | "invalid-identity" | "invalid-version" | "invalid-surface" | "invalid-settings" | "invalid-component" | "type-mismatch" | "non-serializable";
+/** One reported manifest problem; `path` points into the manifest (e.g. `components.hero.fields[0].kind`). */
+export interface ThemeManifestIssue {
+    path: string;
+    code: ThemeManifestIssueCode;
+    message: string;
+}
+/**
+ * Result of the manifest boundary. `manifest` is non-null only when the input
+ * is structurally sound: structural failures (wrong shape, unsupported
+ * contract, malformed components, non-serializable values) yield `null` plus
+ * issues. The one advisory check — a non-semver `version` — returns the
+ * manifest *with* an `invalid-version` issue, so a version-format concern is
+ * never confused with a fatal structural failure.
+ */
+export interface ThemeManifestResult {
+    manifest: ThemeManifest | null;
+    issues: ThemeManifestIssue[];
+}
+/** One occurrence of a component on one page (JSON only). */
+export interface ComponentInstance {
+    id: string;
+    type: string;
+    props?: JsonObject;
+    children?: ComponentInstance[];
+    slots?: Record<string, ComponentInstance[]>;
+}
+/**
+ * One composed surface's persisted document.
+ *
+ * At runtime the envelope is **forward-compatible**: `parsePageData` and
+ * `PageDataSchema` carry unknown *top-level* keys through verbatim, so a later
+ * writer can record metadata (catalog provenance is the intended first use)
+ * without a `PageData.version` bump. Those keys are never read by the renderer,
+ * which only walks `sections`, and they are deliberately **not declared here**:
+ * an index signature would turn a `page.sectons` typo into `unknown` instead of
+ * a compile error. The field is added when a real reader exists.
+ *
+ * Unknown keys *inside* an instance are still stripped — the envelope is
+ * extensible, the instance is not.
+ */
+export interface PageData {
+    version: 1;
+    surface: string;
+    sections: ComponentInstance[];
+}
+export type PageDataIssueCode = "envelope-invalid" | "instance-dropped" | "duplicate-id" | "unknown-type" | "unknown-prop" | "invalid-prop" | "missing-required-prop" | "undeclared-children" | "unknown-slot" | "slot-not-multiple" | "disallowed-child";
+/** One reported degradation; `path` points into the document (e.g. `sections[0].props.limit`). */
+export interface PageDataIssue {
+    path: string;
+    code: PageDataIssueCode;
+    message: string;
+}
+/** Result of a read boundary: `page` is null only when the envelope itself failed. */
+export interface PageDataResult {
+    page: PageData | null;
+    issues: PageDataIssue[];
+}
+/** What the renderer passes to the real component, after gating. */
+export interface ResolvedInstance {
+    props: Record<string, unknown>;
+    children: ComponentInstance[];
+    slots: Record<string, ComponentInstance[]>;
+    issues: PageDataIssue[];
+}
+export type ThemeDefinitionIssueCode = "invalid-theme" | "invalid-settings" | "invalid-definition" | "invalid-type" | "type-mismatch" | "invalid-field" | "duplicate-field-key" | "unknown-content-key" | "invalid-slot" | "duplicate-slot" | "invalid-capability" | "invalid-load";
+export interface ThemeDefinitionIssue {
+    path: string;
+    code: ThemeDefinitionIssueCode;
+    message: string;
+}
+/**
+ * Optional inputs to `validateThemeDefinition`. Every field is additive: with
+ * no options, the validator behaves exactly as it always has.
+ *
+ * `contentKeys` is the one cross-boundary check the Theme SDK can make and a
+ * theme cannot — it defines `contentKey` *and* reads the resolved content
+ * record, so a typo is invisible everywhere else. The SDK deliberately does not
+ * model content packs; it only compares a field's `contentKey` against the key
+ * set the theme supplies. Passing an **empty** array is meaningful: it enables
+ * the check and reports every declared key.
+ */
+export interface ThemeValidationOptions {
+    contentKeys?: readonly string[];
+}
+export type ThemeSettingsIssueCode = "invalid-settings" | "unknown-setting" | "invalid-setting" | "missing-required-setting";
+/** One reported problem with a store's theme settings; `path` is `settings.<key>`. */
+export interface ThemeSettingsIssue {
+    path: string;
+    code: ThemeSettingsIssueCode;
+    message: string;
+}
+/** The effective settings: every value checked, the rest from the theme's defaults. */
+export interface ThemeSettingsResult {
+    values: Record<string, unknown>;
+    issues: ThemeSettingsIssue[];
+}
+type SettingsFieldsOf<T> = T extends {
+    settings: readonly (infer G)[];
+} ? G extends {
+    fields: readonly (infer F extends FieldDefinition)[];
+} ? F : never : never;
+/**
+ * The effective settings of a theme, typed from its declaration: a setting
+ * with a `default` is always present, any other may be absent.
+ *
+ * ```ts
+ * const { values } = resolveThemeSettings(theme, stored);
+ * const settings = values as InferSettings<typeof theme>;
+ * ```
+ */
+export type InferSettings<T extends ThemeDefinition> = {
+    [F in SettingsFieldsOf<T> as F extends {
+        default: unknown;
+    } ? F["key"] : never]: FieldValue<F>;
+} & {
+    [F in SettingsFieldsOf<T> as F extends {
+        default: unknown;
+    } ? never : F["key"]]?: FieldValue<F>;
+};
+export {};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,82 @@
 {
   "name": "@wocart/theme",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "The Wocart theme contract: code-owned component definitions, JSON page documents, validation and resolution, and a reference Astro renderer.",
+  "keywords": [
+    "wocart",
+    "theme",
+    "storefront",
+    "ecommerce",
+    "page-builder",
+    "astro",
+    "astro-component",
+    "withastro",
+    "typescript"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bighadj22/codflow.git",
+    "directory": "wocart-sdk/theme"
+  },
+  "homepage": "https://github.com/bighadj22/codflow/tree/main/wocart-sdk/theme#readme",
+  "bugs": "https://github.com/bighadj22/codflow/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./astro": {
+      "types": "./dist/astro/index.d.ts",
+      "default": "./dist/astro/index.js"
+    },
+    "./astro/InstanceView.astro": "./dist/astro/InstanceView.astro",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "build": "node --eval \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc && node scripts/copy-astro.mjs",
+    "typecheck": "tsc --noEmit && tsc --project tsconfig.test.json && astro check",
+    "test": "npm run build && vitest run",
+    "test:watch": "vitest",
+    "verify:package": "npm run build && node scripts/check-package.mjs && node scripts/verify-package.mjs",
+    "prepack": "npm run build",
+    "prepublishOnly": "node scripts/check-package.mjs"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@wocart/storefront": "^1.0.0",
+    "astro": "^7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "astro": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@wocart/storefront": "^1.0.0",
+    "@types/node": "^26.2.0",
+    "astro": "^7.3.2",
+    "fast-check": "^4.6.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  }
+}