@sevenfold/setto-client 0.5.0 → 0.6.0

package/README.md

@@ -8,19 +8,13 @@ Editors authenticate via Supabase, edit text inline on the live page, pick secti
 
 ## Install
 
-Sevenfold sites pin a git tag, not an npm version, so changes ship without an npm round-trip:
+Sevenfold sites pin an npm version via alias:
 
 ```json
-"@setto/client": "github:nitech/setto-client#v0.5.0"
+"@setto/client": "npm:@sevenfold/setto-client@0.5.0"
 ```
 
-Bun clones the repo on `bun install`, runs the package's `prepare` script to build `dist/`, and links it as `@setto/client`. Vercel does the same automatically when it installs build deps.
-
-The package is also still published to npm (`@sevenfold/setto-client`) for external consumers:
-
-```bash
-bun add @setto/client@npm:@sevenfold/setto-client
-```
+`bun install` pulls the prebuilt package from npm — no GitHub token required on Vercel.
 
 Peer deps: `react`, `react-dom`, `react-i18next`, `i18next`.
 
@@ -29,13 +23,14 @@ For local monorepo development the consumer's `vite.config.ts` aliases `@setto/c
 ### Releasing a new version
 
 1. Bump `version` in `package.json` following semver (patch / minor / major).
-2. Commit and tag: `git tag v0.5.1 && git push origin main --follow-tags`.
-3. In each consumer (`carryon.no`, `setto-site`):
-   - Update the tag in `package.json` (e.g. `#v0.5.0` → `#v0.5.1`).
+2. Commit and push to `main`. GitHub Actions publishes `@sevenfold/setto-client` to npm automatically (requires `NPM_TOKEN` secret in this repo).
+3. Confirm the version is on npm: `npm view @sevenfold/setto-client@X.Y.Z version`.
+4. In each consumer (`carryon.no`, `setto-site`):
+   - Update the pin in `package.json` (e.g. `@0.5.0` → `@0.5.1`).
    - Run `bun install` to refresh the lockfile.
-   - Push — Vercel pulls the new tag on the next deploy.
+   - Commit and push — Vercel installs the new npm version on the next deploy.
 
-GitHub Actions still publishes to npm automatically when `package.json` lands on `main` (requires `NPM_TOKEN` secret), but Sevenfold consumers no longer wait for it.
+> **Why npm, not a git tag?** `nitech/setto-client` is private. Vercel cannot fetch `github:nitech/setto-client#v…` without a `GITHUB_TOKEN` with repo access. Public npm avoids that and ships a prebuilt `dist/`.
 
 ---
 

package/dist/SettoAnimation.d.ts

@@ -0,0 +1,22 @@
+import { type ReactNode } from 'react';
+import type { AnimationPreset } from './block-tree/schema';
+export interface SettoAnimationProps {
+    preset: AnimationPreset;
+    /** Delay before play, in milliseconds. */
+    delay?: number;
+    /** Duration in milliseconds. Defaults per preset. */
+    duration?: number;
+    className?: string;
+    children: ReactNode;
+}
+/**
+ * Lightweight, CSS-driven reveal wrapper. Triggers once when scrolled into
+ * view (or immediately, for non-scroll presets). Honors
+ * `prefers-reduced-motion`, falls back to plain children with no animation.
+ *
+ * Hosts that use GSAP (carryon.no, setto-site) should keep their own
+ * `data-reveal` system; this primitive exists so generated layout trees
+ * have a portable animation primitive without dragging GSAP into the
+ * setto-client bundle.
+ */
+export declare function SettoAnimation({ preset, delay, duration, className, children, }: SettoAnimationProps): import("react/jsx-runtime").JSX.Element;

package/dist/SettoForm.d.ts

@@ -0,0 +1,18 @@
+import type { FormField } from './block-tree/schema';
+export interface SettoFormProps {
+    /** Scopes i18n keys: `form.{formId}.submit`, `.success`, `.error`. */
+    formId: string;
+    fields: FormField[];
+    /** Static POST endpoint. Either this or `endpointKey` must be provided. */
+    endpoint?: string;
+    /** i18n key whose value is the runtime endpoint URL. */
+    endpointKey?: string;
+    className?: string;
+}
+/**
+ * Generic POST form whose copy lives in i18n. Field structure is fixed by
+ * the host (or by the block tree) — editors can change labels and copy but
+ * not the field set, matching the Setto product principle that the editor
+ * adjusts content, not structure.
+ */
+export declare function SettoForm({ formId, fields, endpoint, endpointKey, className, }: SettoFormProps): import("react/jsx-runtime").JSX.Element;

package/dist/SettoVideo.d.ts

@@ -0,0 +1,16 @@
+export interface SettoVideoProps {
+    /** i18n key holding the video URL (YouTube, Vimeo, or direct MP4). */
+    srcKey: string;
+    /** Optional i18n key holding a poster image URL (HTML5 video only). */
+    posterKey?: string;
+    title?: string;
+    className?: string;
+}
+/**
+ * Renders a video from a URL stored in i18n. YouTube and Vimeo URLs become
+ * iframe embeds; everything else renders as an HTML5 `<video>` element.
+ *
+ * Editors can change the URL via the i18n draft store (a dedicated picker
+ * UI may follow; until then it's swap-via-publish like other content).
+ */
+export declare function SettoVideo({ srcKey, posterKey, title, className }: SettoVideoProps): import("react/jsx-runtime").JSX.Element;

package/dist/block-tree/SettoBlockTree.d.ts

@@ -0,0 +1,24 @@
+import { type ComponentType } from 'react';
+import { type SettoIconRenderProps } from '../SettoIcon';
+import type { BlockTree } from './schema';
+export interface SettoBlockTreeProps {
+    /** Validated block tree, typically parsed from `home.layout.json`. */
+    tree: BlockTree;
+    /**
+     * Icon registry consumed by `SettoIcon` nodes — the same map a host would
+     * pass directly to `<SettoIcon icons={…}>`.
+     */
+    icons: Record<string, ComponentType<SettoIconRenderProps>>;
+    /**
+     * When true (default), validates the tree and throws on schema errors.
+     * Disable in production after a one-time boot check.
+     */
+    validate?: boolean;
+}
+/**
+ * Renders a block tree by dispatching each node to the matching Setto
+ * primitive. Inside a `repeater`, leaf nodes use keys relative to the item;
+ * the renderer composes them with the active scope so the agent can author
+ * trees without knowing per-item suffixes.
+ */
+export declare function SettoBlockTree({ tree, icons, validate }: SettoBlockTreeProps): import("react/jsx-runtime").JSX.Element;

package/dist/block-tree/extract-keys.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Walks a block tree and reports the i18n keys, theme ids, and required
+ * sample-locale entries it expects. The agent uses this output to validate
+ * that the generated `no.json` covers everything the tree references.
+ */
+import type { BlockTree } from './schema';
+export interface ContentKeyRequirements {
+    /** Plain i18n keys that must exist with a string value. */
+    keys: Set<string>;
+    /**
+     * Section / block theme ids referenced by the tree. The deterministic
+     * sections.json overlay and section-schemas.ts must include each id.
+     */
+    themeIds: Set<string>;
+    /**
+     * Repeater requirements — at least one item entry must exist in the
+     * locale under `itemsKey`, with every field from `defaultItem`.
+     */
+    repeaters: Array<{
+        itemsKey: string;
+        fields: string[];
+        /**
+         * Item-relative keys produced by walking the item template. The
+         * validator checks every existing locale item has these keys.
+         */
+        itemKeys: string[];
+    }>;
+}
+/** Returns content requirements for an already-validated tree. */
+export declare function extractContentKeys(tree: BlockTree): ContentKeyRequirements;

package/dist/block-tree/registry.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Per-type metadata for block-tree nodes.
+ *
+ * The renderer dispatches on node `type`; the validator and key extractor
+ * consult this registry for allowed children, required content keys, and
+ * whether a type carries a theme id.
+ */
+import type { BlockNode, BlockNodeType } from './schema';
+export interface BlockTypeMeta {
+    /**
+     * Allowed child types. `null` means the node is a leaf; `'any'` means any
+     * other type may appear as a child.
+     */
+    allowedChildren: BlockNodeType[] | 'any' | null;
+    /** True when the node has a theme id (used in `sections.json`). */
+    themed: boolean;
+    /** True when this node participates as a `SectionToolbar` target. */
+    selectable: boolean;
+}
+export declare const BLOCK_REGISTRY: Record<BlockNodeType, BlockTypeMeta>;
+/** All known block types, kept in sync with `BLOCK_REGISTRY`. */
+export declare const BLOCK_TYPES: readonly BlockNodeType[];
+/** Returns the children of a node, or an empty array for leaves. */
+export declare function nodeChildren(node: BlockNode): BlockNode[];

package/dist/block-tree/schema.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Declarative page model rendered by `SettoBlockTree`.
+ *
+ * A site's layout is a tree of typed nodes. Each node maps to one of the
+ * existing editable primitives (T, SettoSection, SettoBlock, SettoRepeater,
+ * SettoImage, SettoIcon) or to a new composite primitive (SettoForm,
+ * SettoVideo, SettoAnimation). The tree is stored as JSON
+ * (`src/content/pages/home.layout.json`) and is what `setto-agent` generates
+ * during onboarding instead of writing TSX.
+ */
+export type BlockTreeVersion = '1';
+export interface BlockTree {
+    version: BlockTreeVersion;
+    /** Top-level nodes rendered into `<main>` (or a host-provided wrapper). */
+    root: BlockNode[];
+}
+export type BlockNode = SectionNode | BlockBoxNode | ContainerNode | TextNode | ImageNode | IconNode | RepeaterNode | FormNode | VideoNode | AnimationNode;
+export type BlockNodeType = BlockNode['type'];
+interface BaseNode {
+    /** Stable id within the tree — used as React key and for diff/edit ops. */
+    id: string;
+    /** Optional Tailwind / CSS class string applied to the rendered element. */
+    className?: string;
+}
+export interface SectionNode extends BaseNode {
+    type: 'section';
+    /** Matches a key in `sections.json` / `sectionSchemas` for background theme. */
+    sectionId: string;
+    children: BlockNode[];
+}
+export interface BlockBoxNode extends BaseNode {
+    type: 'block';
+    blockId: string;
+    children: BlockNode[];
+}
+export type ContainerTag = 'div' | 'section' | 'header' | 'footer' | 'main' | 'aside' | 'nav' | 'article' | 'ul' | 'ol' | 'li' | 'p' | 'span';
+export interface ContainerNode extends BaseNode {
+    type: 'container';
+    tag?: ContainerTag;
+    children: BlockNode[];
+}
+export type TextAs = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span' | 'div' | 'label' | 'em' | 'strong';
+export interface TextNode extends BaseNode {
+    type: 'text';
+    /** i18n key, or a key relative to the surrounding repeater item. */
+    k: string;
+    /** Element tag to wrap the `<T>` in. Defaults to inline span. */
+    as?: TextAs;
+}
+export interface ImageNode extends BaseNode {
+    type: 'image';
+    /** i18n key holding the image src (resolved at runtime). */
+    srcKey: string;
+    alt?: string;
+}
+export interface IconNode extends BaseNode {
+    type: 'icon';
+    /** i18n key holding the icon name from the host icon registry. */
+    k: string;
+    size?: number;
+}
+export interface RepeaterNode extends BaseNode {
+    type: 'repeater';
+    /** i18n list prefix, e.g. 'faq.items'. */
+    itemsKey: string;
+    /** Norwegian label shown in the editor's add/remove controls. */
+    itemLabel?: string;
+    /** Field defaults seeded into i18n when an editor adds a new item. */
+    defaultItem: Record<string, string>;
+    /**
+     * Subtree rendered once per item. Text/image/icon nodes here may use
+     * keys relative to the item (e.g. `k: 'q'` resolves to
+     * `faq.items.{itemKey}.q` at render time).
+     */
+    itemTemplate: BlockNode[];
+}
+export type FormFieldType = 'text' | 'email' | 'tel' | 'textarea';
+export interface FormField {
+    /** Submitted form field name. */
+    name: string;
+    type: FormFieldType;
+    required?: boolean;
+    /** i18n key for the field label. */
+    labelKey: string;
+    /** i18n key for the placeholder text. */
+    placeholderKey?: string;
+}
+export interface FormNode extends BaseNode {
+    type: 'form';
+    /**
+     * Scopes all i18n keys for this form: `form.{formId}.submit`,
+     * `form.{formId}.success`, `form.{formId}.error`.
+     */
+    formId: string;
+    /** Static POST endpoint. Use `endpointKey` to read from i18n instead. */
+    endpoint?: string;
+    /** i18n key whose value is the form POST endpoint. */
+    endpointKey?: string;
+    fields: FormField[];
+}
+export interface VideoNode extends BaseNode {
+    type: 'video';
+    /** i18n key holding the embed URL (YouTube, Vimeo, MP4, …). */
+    srcKey: string;
+    /** Optional i18n key for a poster image (HTML5 video only). */
+    posterKey?: string;
+    /** Iframe accessibility title. Not editable. */
+    title?: string;
+}
+export type AnimationPreset = 'fadeIn' | 'slideUp' | 'stagger' | 'scrollReveal';
+export interface AnimationNode extends BaseNode {
+    type: 'animation';
+    preset: AnimationPreset;
+    /** Delay before play, in milliseconds. */
+    delay?: number;
+    /** Duration in milliseconds. Defaults to preset value. */
+    duration?: number;
+    children: BlockNode[];
+}
+export {};

package/dist/block-tree/validate.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Runtime validator for block trees.
+ *
+ * Used by both `setto-client` (when loading a `home.layout.json` at boot)
+ * and `setto-agent` (after generation, before sandbox build). No external
+ * dependencies so we can ship to host sites without bundle bloat.
+ */
+import type { BlockTree, FormField } from './schema';
+export interface ValidationIssue {
+    /** Dotted path to the offending node, e.g. `root[2].children[0]`. */
+    path: string;
+    message: string;
+}
+export type ValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    issues: ValidationIssue[];
+};
+/**
+ * Validates a parsed block tree. Returns the first batch of issues found —
+ * the goal is enough detail for a fixer model to act on, not exhaustive
+ * reporting.
+ */
+export declare function validateBlockTree(input: unknown): ValidationResult;
+/** Narrowing helper: validates and returns a typed tree, or throws. */
+export declare function parseBlockTree(input: unknown): BlockTree;
+export type { FormField };

package/dist/index.d.ts

@@ -9,9 +9,22 @@ export { SettoImage } from './SettoImage';
 export type { SettoImageProps } from './SettoImage';
 export { SettoRepeater } from './SettoRepeater';
 export type { SettoRepeaterProps } from './SettoRepeater';
+export { SettoForm } from './SettoForm';
+export type { SettoFormProps } from './SettoForm';
+export { SettoVideo } from './SettoVideo';
+export type { SettoVideoProps } from './SettoVideo';
+export { SettoAnimation } from './SettoAnimation';
+export type { SettoAnimationProps } from './SettoAnimation';
 export { useSectionTheme } from './use-section-theme';
 export { SettoAdminApp } from './admin/App';
 export { SETTO_BASE } from './lib/urls';
 export { AuthGate } from './edit-mode/auth-gate';
 export type { SettoConfig, BrandColor, DeploymentRow, SiteRow, ContentFile, PublishFile, PublishResult, } from './types';
 export type { SectionSchema, SectionColorField } from './section-schema';
+export { SettoBlockTree } from './block-tree/SettoBlockTree';
+export type { SettoBlockTreeProps } from './block-tree/SettoBlockTree';
+export type { BlockTree, BlockTreeVersion, BlockNode, BlockNodeType, SectionNode, BlockBoxNode, ContainerNode, ContainerTag, TextNode, TextAs, ImageNode, IconNode, RepeaterNode, FormNode, FormField, FormFieldType, VideoNode, AnimationNode, AnimationPreset, } from './block-tree/schema';
+export { validateBlockTree, parseBlockTree, type ValidationIssue, type ValidationResult, } from './block-tree/validate';
+export { extractContentKeys, type ContentKeyRequirements, } from './block-tree/extract-keys';
+export { BLOCK_REGISTRY, BLOCK_TYPES, nodeChildren } from './block-tree/registry';
+export type { BlockTypeMeta } from './block-tree/registry';