@sevenfold/setto-client 0.1.0

package/README.md

@@ -0,0 +1,369 @@
+# @setto/client
+
+React client library for Setto — git-based inline CMS for Vite + i18next apps.
+
+Published on npm as **`@sevenfold/setto-client`** (Sevenfold org). Import as `@setto/client` in app code.
+
+Editors authenticate via Supabase, edit text inline on the live page, pick section colours from the site brand palette, and publish changes back to GitHub. setto-server commits whitelisted files and tracks the Vercel deployment.
+
+## Install
+
+```bash
+bun add @setto/client@npm:@sevenfold/setto-client
+```
+
+Or add directly to `package.json`:
+
+```json
+"@setto/client": "npm:@sevenfold/setto-client@^0.1.0"
+```
+
+Peer deps: `react`, `react-dom`, `react-i18next`, `i18next`.
+
+For local monorepo development alongside `carryon.no`, a `file:` link also works — see [Local development](#local-development-sevenfold-monorepo).
+
+### Publishing a new version
+
+1. Bump `version` in `package.json`
+2. Commit and push a tag: `git tag v0.1.1 && git push origin v0.1.1`
+3. GitHub Actions publishes to npm automatically
+
+Requires an `NPM_TOKEN` secret in the GitHub repo (Granular Access Token from npmjs.com with write access to `@sevenfold`).
+
+Or trigger manually via **Actions → Publish to npm → Run workflow**.
+
+---
+
+## Quick start
+
+### 1. Wrap the app
+
+```tsx
+// main.tsx
+import { SettoProvider } from '@setto/client';
+import sectionsTheme from './theme/sections.json';
+import { brandColors } from './theme/brand-colors';
+import { sectionSchemas } from './theme/section-schemas';
+
+createRoot(document.getElementById('root')!).render(
+  <SettoProvider
+    config={{
+      siteId: 'my-site',                        // slug in setto-server `sites` table
+      apiUrl: import.meta.env.VITE_SETTO_API_URL,
+      supabase: {
+        url: import.meta.env.VITE_SUPABASE_URL,
+        anonKey: import.meta.env.VITE_SUPABASE_ANON_KEY,
+      },
+      theme: sectionsTheme,                     // bundled defaults for section colours
+      themePath: 'src/theme/sections.json',     // GitHub path — must be in content_paths
+      brandColors,                              // palette for the colour toolbar
+      sectionSchemas,                           // which fields each section exposes
+    }}
+  >
+    <BrowserRouter>
+      <App />
+    </BrowserRouter>
+  </SettoProvider>,
+);
+```
+
+### 2. Mount the admin route
+
+```tsx
+// App.tsx
+import { SettoAdminApp } from '@setto/client';
+
+<Routes>
+  <Route path="/" element={<Home />} />
+  <Route path="/admin/*" element={<SettoAdminApp />} />
+</Routes>
+```
+
+### 3. Replace copy with `<T>`
+
+```tsx
+import { T } from '@setto/client';
+
+<h1><T k="hero.headline" /></h1>
+<p><T k="hero.subheadline" /></p>
+
+{/* Dynamic keys work too */}
+<T k={`faq.items.${item.key}.q`} />
+```
+
+Keep using `t()` for non-visible strings (placeholders, `aria-label`, `alt`) — those are not inline-editable in v0.
+
+### 4. Wire section colours (optional)
+
+```tsx
+import { SettoSection, useSectionTheme } from '@setto/client';
+
+function ValuesSection() {
+  const colors = useSectionTheme('values');
+
+  return (
+    <SettoSection sectionId="values" id="verdier" className="py-20">
+      <span style={{ color: colors.label }}><T k="values.label" /></span>
+      <h2 style={{ color: colors.heading }}><T k="values.headline" /></h2>
+    </SettoSection>
+  );
+}
+```
+
+---
+
+## Environment variables (host app)
+
+| Variable | Purpose |
+|----------|---------|
+| `VITE_SUPABASE_URL` | Supabase project URL |
+| `VITE_SUPABASE_ANON_KEY` | Supabase anon key (public) |
+| `VITE_SETTO_API_URL` | setto-server base URL, e.g. `http://localhost:3001` |
+
+---
+
+## Edit mode
+
+Edit mode activates when **both** are true:
+
+1. Authenticated Supabase session.
+2. URL contains `?setto=edit`.
+
+The `/admin` dashboard does **not** activate edit mode. Use **Begynn å redigere**, which navigates to `/?setto=edit`.
+
+### What editors see
+
+| Action | How |
+|--------|-----|
+| Edit text | Click any `<T>` element — it becomes `contentEditable` |
+| Edit section colours | Click a section or block background (not text) |
+| Follow a link | Ctrl/Cmd + click on nav links |
+| Publish | Top toolbar → **Publiser** |
+| Exit | Top toolbar → **Avslutt** (removes `?setto=edit`) |
+
+A fixed toolbar sits at the top of the viewport. When you click a section or block, a compact colour toolbar appears above it, centred and sized to its contents. Click again or press Escape to dismiss.
+
+---
+
+## Text editing (`<T>`)
+
+`<T k="dotted.key" />` renders the i18next string for the active language.
+
+In edit mode the text is inline-editable. Changes are stored in an in-memory draft layer (`I18nStore`) and applied to the live i18next bundle immediately so the page re-renders.
+
+On publish, the full locale bundles are serialised to JSON and committed to GitHub:
+
+```
+src/i18n/locales/no.json
+src/i18n/locales/en.json
+```
+
+When edit mode starts, setto-server loads the current files from GitHub as the baseline (`GET /sites/:id/content`).
+
+---
+
+## Section colours
+
+Section colours live in a separate JSON file (not in i18n):
+
+```
+src/theme/sections.json
+```
+
+Example:
+
+```json
+{
+  "values": {
+    "background": "#640AFF",
+    "label": "#C9C0DA",
+    "heading": "#FFFFFF",
+    "icon": "#FFFFFF",
+    "cardTitle": "#FFFFFF",
+    "cardDesc": "#C9C0DA"
+  }
+}
+```
+
+### Brand palette (`brandColors`)
+
+Editors do **not** get a free-form colour picker. Each colour field shows the **current swatch**; clicking it opens a menu of predefined brand colours:
+
+```ts
+// theme/brand-colors.ts
+import type { BrandColor } from '@setto/client';
+
+export const brandColors: BrandColor[] = [
+  { label: 'Beige', value: '#E6DCCF' },
+  { label: 'Oliven', value: '#362F00' },
+  { label: 'Lilla', value: '#640AFF' },
+  // …
+];
+```
+
+**Rules for integrators:**
+
+- List every colour token editors should be able to pick.
+- Values must match the palette used in Tailwind/CSS on the site (same hex values).
+- Use solid hex colours in `sections.json` — rgba values won't match swatches.
+- When you add a new brand token to Tailwind, add it to `brandColors` too.
+
+### Section schemas (`sectionSchemas`)
+
+Define which colour fields each section exposes in the toolbar:
+
+```ts
+// theme/section-schemas.ts
+import type { SectionSchema } from '@setto/client';
+
+export const sectionSchemas: Record<string, SectionSchema> = {
+  values: {
+    label: 'Verdier',
+    fields: [
+      { key: 'background', label: 'Bakgrunn' },
+      { key: 'label', label: 'Etikett' },
+      { key: 'heading', label: 'Overskrift' },
+      // keys must match properties used in useSectionTheme('values')
+    ],
+  },
+};
+```
+
+The `sectionId` prop on `<SettoSection>` must match a key in both `sectionSchemas` and `sections.json`.
+
+### Applying colours in components
+
+Read tokens with `useSectionTheme(sectionId)` and apply via inline `style` (or CSS variables you control):
+
+```tsx
+const colors = useSectionTheme('hero');
+
+<SettoSection sectionId="hero" style={{ /* background applied automatically */ }}>
+  <h1 style={{ color: colors.heading }}><T k="hero.headline" /></h1>
+</SettoSection>
+```
+
+`<SettoSection>` always applies `colors.background` as `backgroundColor`. Other tokens are your responsibility.
+
+### Nested blocks (`<SettoBlock>`)
+
+For cards or panels inside a section, wrap each in `<SettoBlock>` with its own theme key:
+
+```tsx
+import { SettoSection, SettoBlock, useSectionTheme } from '@setto/client';
+
+function InnovationSection() {
+  const card = useSectionTheme('innovationCard');
+
+  return (
+    <SettoSection sectionId="innovation" className="py-20">
+      <SettoBlock blockId="innovationCard" className="p-8">
+        <span style={{ color: card.label }}><T k="innovation.label" /></span>
+        <h3 style={{ color: card.heading }}><T k="innovation.headline" /></h3>
+      </SettoBlock>
+    </SettoSection>
+  );
+}
+```
+
+Click a block's background to edit **that block's** colours. Click the section padding to edit the **section** background. Add matching keys to `sections.json` and `sectionSchemas` for each block.
+
+---
+
+## Server setup (setto-server)
+
+Each site row in Supabase needs:
+
+| Column | Example |
+|--------|---------|
+| `id` | `carryon-no` |
+| `repo_owner` / `repo_name` / `branch` | GitHub target |
+| `content_paths` | Whitelist of publishable file paths |
+
+Example `content_paths`:
+
+```
+src/i18n/locales/no.json
+src/i18n/locales/en.json
+src/theme/sections.json
+```
+
+Only paths in this list can be committed. Add new content files here before publishing them.
+
+Register allowed origins for CORS (`allowed_origins`).
+
+---
+
+## Publish flow
+
+1. Editor clicks **Publiser** in the top toolbar.
+2. Client serialises changed locale bundles + `sections.json` (if theme drafts exist).
+3. `POST /sites/:siteId/publish` with `{ files: [{ path, content }] }`.
+4. setto-server validates paths against `content_paths`, commits to GitHub.
+5. A `deployments` row is inserted; the toolbar shows build status via Supabase Realtime + Vercel webhook.
+
+Drafts are cleared after a successful publish.
+
+---
+
+## Admin app (`SettoAdminApp`)
+
+Route: `/admin/*`
+
+Provides Supabase email/password login and a dashboard with a link to start editing (`/?setto=edit`). Does not render the inline editor itself.
+
+---
+
+## Local development (Sevenfold monorepo)
+
+When consumed by `carryon.no`, Vite aliases `@setto/client` to `src/index.ts` so changes hot-reload without a separate watch build.
+
+Typical stack:
+
+```bash
+# Terminal 1 — Supabase
+cd setto-server && supabase start
+
+# Terminal 2 — API
+cd setto-server && bun run dev   # :3001
+
+# Terminal 3 — Site
+cd carryon.no && bun run dev     # :3000
+```
+
+---
+
+## Build (library)
+
+```bash
+bun install
+bun run build
+```
+
+Produces `dist/setto-client.js` and `.d.ts` via Vite library mode. Only needed before publishing to npm.
+
+---
+
+## API surface
+
+| Export | Purpose |
+|--------|---------|
+| `SettoProvider` / `useSetto` | Context, auth, stores, edit mode flag |
+| `T` | Inline-editable translation |
+| `SettoSection` | Section wrapper + edit selection |
+| `SettoBlock` | Nested card/panel with its own colour toolbar |
+| `useSectionTheme` | Read section colour tokens |
+| `SettoAdminApp` | `/admin` login + dashboard |
+| `AuthGate` | Standalone login wrapper |
+| `BrandColor`, `SectionSchema`, `SettoConfig` | Types for host config |
+
+---
+
+## Limitations (v0)
+
+- `<T>` supports text content only — not HTML attributes (`placeholder`, `alt`, `aria-label`).
+- No list/repeater UI (cannot add a new FAQ row from the editor).
+- Drafts are in-memory — refresh discards unpublished changes.
+- Section colour toolbar only offers `brandColors` — no custom hex/rgba input.
+- CTA card colours and nested component colours are not section-themeable yet.
+- Single editor per site (no concurrent-edit conflict handling).

package/dist/SettoBlock.d.ts

@@ -0,0 +1,10 @@
+import { type ComponentPropsWithoutRef } from 'react';
+export interface SettoBlockProps extends ComponentPropsWithoutRef<'div'> {
+    /** Theme key in sections.json, e.g. 'innovationCard'. */
+    blockId: string;
+}
+/**
+ * Themeable block (card, panel) inside a section. Click the block chrome to
+ * edit its colours; click text to edit copy.
+ */
+export declare const SettoBlock: import("react").ForwardRefExoticComponent<SettoBlockProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/SettoSection.d.ts

@@ -0,0 +1,11 @@
+import { type ComponentPropsWithoutRef } from 'react';
+export interface SettoSectionProps extends ComponentPropsWithoutRef<'section'> {
+    /** Theme key, e.g. 'values'. */
+    sectionId: string;
+}
+/**
+ * Wraps a page section with theme-driven background colour and edit-mode
+ * selection. Click the section chrome (not editable text or nested blocks)
+ * to open the colour toolbar.
+ */
+export declare const SettoSection: import("react").ForwardRefExoticComponent<SettoSectionProps & import("react").RefAttributes<HTMLElement>>;

package/dist/T.d.ts

@@ -0,0 +1,9 @@
+export interface TProps {
+    /** The dotted translation key, e.g. 'hero.headline'. */
+    k: string;
+}
+/**
+ * Renders a translation key. In edit mode the text is contentEditable inline;
+ * changes flow into the draft store for the active language.
+ */
+export declare function T({ k }: TProps): import("react/jsx-runtime").JSX.Element;

package/dist/admin/App.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Drop-in admin SPA. Mount under a route like `<Route path="/admin/*" .../>`.
+ *
+ * Behaviour after login:
+ *  - Lists sites the user is a member of (read via Supabase RLS).
+ *  - Single-site sites: redirect to `/?setto=edit` automatically.
+ *  - Multi-site: show a picker.
+ *
+ * While the user is on `/admin`, this component shows the site dashboard.
+ * Editing happens on the public site at `/?setto=edit` via "Begynn å redigere".
+ */
+export declare function SettoAdminApp(): import("react/jsx-runtime").JSX.Element;

package/dist/edit-mode/auth-gate.d.ts

@@ -0,0 +1,10 @@
+import { type ReactNode } from 'react';
+export interface AuthGateProps {
+    /** Rendered after a session is established. */
+    children: ReactNode;
+}
+/**
+ * Wraps `children` with a Supabase email/password login screen. Returns the
+ * children only when a session exists.
+ */
+export declare function AuthGate({ children }: AuthGateProps): import("react/jsx-runtime").JSX.Element;

package/dist/edit-mode/build-status.d.ts

@@ -0,0 +1,13 @@
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { DeploymentRow } from '../types';
+interface BuildStatusProps {
+    supabase: SupabaseClient;
+    deploymentId: string;
+    onDone?: (status: DeploymentRow['status']) => void;
+}
+/**
+ * Subscribes to a single row in `deployments` via Supabase Realtime.
+ * Renders the three-step progress and an error state on failure.
+ */
+export declare function BuildStatus({ supabase, deploymentId, onDone }: BuildStatusProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/edit-mode/constants.d.ts

@@ -0,0 +1,2 @@
+/** Height of the fixed edit toolbar (px). */
+export declare const TOOLBAR_HEIGHT = 44;

package/dist/edit-mode/document-layout.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Reserves space at the top of the viewport for the Setto edit toolbar.
+ * The host site keeps full width — only vertical offset is applied.
+ */
+export declare function useSettoDocumentLayout(active: boolean): void;

package/dist/edit-mode/link-hint.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tooltip when hovering editable text inside a link or button (except language
+ * toggles). Flips to stay within the viewport.
+ */
+export declare function EditLinkHint(): import("react/jsx-runtime").JSX.Element | null;

package/dist/edit-mode/mount.d.ts

@@ -0,0 +1,14 @@
+import { type ReactNode } from 'react';
+import type { ThemeStore } from '../lib/theme-store';
+interface EditModeShellProps {
+    children: ReactNode;
+    themeStore: ThemeStore | null;
+}
+/**
+ * Edit mode: full-width page with a fixed toolbar at the top. Text is edited
+ * inline via contentEditable on `<T>` — no sidebar.
+ */
+export declare function EditModeShell({ children, themeStore }: EditModeShellProps): import("react/jsx-runtime").JSX.Element;
+/** @deprecated Use EditModeShell */
+export declare const EditModeMount: typeof EditModeShell;
+export {};

package/dist/edit-mode/publish-utils.d.ts

@@ -0,0 +1,4 @@
+export declare function guessLangFromPath(path: string, languages: string[]): string | null;
+export declare function pathForLang(_siteId: string, lng: string, _languages: string[]): string;
+export declare function pathForTheme(_siteId: string, themePath?: string): string;
+export declare function isThemePath(path: string, themePath?: string): boolean;

package/dist/edit-mode/section-toolbar.d.ts

@@ -0,0 +1 @@
+export declare function SectionToolbar(): import("react/jsx-runtime").JSX.Element | null;

package/dist/edit-mode/toolbar.d.ts

@@ -0,0 +1 @@
+export declare function EditToolbar(): import("react/jsx-runtime").JSX.Element;

package/dist/edit-mode/use-edit-baseline.d.ts

@@ -0,0 +1,2 @@
+/** Loads locale and theme files from GitHub once per session to seed the draft baseline. */
+export declare function useEditBaseline(): void;

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { SettoProvider, useSetto } from './provider';
+export { T } from './T';
+export { SettoSection } from './SettoSection';
+export { SettoBlock } from './SettoBlock';
+export { useSectionTheme } from './use-section-theme';
+export { SettoAdminApp } from './admin/App';
+export { AuthGate } from './edit-mode/auth-gate';
+export type { SettoConfig, BrandColor, DeploymentRow, SiteRow, ContentFile, PublishResult, } from './types';
+export type { SectionSchema, SectionColorField } from './section-schema';

package/dist/lib/api.d.ts

@@ -0,0 +1,15 @@
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { ContentFile, PublishResult } from '../types';
+export declare function createApi(args: {
+    apiUrl: string;
+    supabase: SupabaseClient;
+}): {
+    getContent(siteId: string): Promise<{
+        files: ContentFile[];
+    }>;
+    publish(siteId: string, files: Array<{
+        path: string;
+        content: string;
+    }>, message?: string): Promise<PublishResult>;
+};
+export type SettoApi = ReturnType<typeof createApi>;

package/dist/lib/color-utils.d.ts

@@ -0,0 +1,4 @@
+/** Returns true when two CSS colour strings represent the same sRGB value. */
+export declare function colorsMatch(a: string, b: string): boolean;
+/** Pick a visible border colour for a swatch on white UI chrome. */
+export declare function swatchBorder(color: string): string;

package/dist/lib/i18n-store.d.ts

@@ -0,0 +1,75 @@
+import type { i18n as I18nType } from 'i18next';
+/**
+ * Tracks an in-memory layer of edits on top of a loaded i18next instance.
+ *
+ * On disk, a site has one JSON file per language under `content_paths`. At
+ * runtime, i18next holds those JSONs as resource bundles in
+ * `i18n.store.data[lng].translation`.
+ *
+ * The draft store mutates the resource bundles directly so the page re-renders
+ * with the editor's text immediately. When the user publishes, we serialise
+ * the merged resource bundles back to JSON and POST them to setto-server.
+ */
+export interface DraftEntry {
+    /** Dotted key path, e.g. 'hero.headline'. */
+    key: string;
+    /** Language code, e.g. 'no'. */
+    lng: string;
+    /** Value before any edits in this session — used for diff and revert. */
+    original: string;
+    /** Current draft value. */
+    current: string;
+}
+export interface I18nStoreSnapshot {
+    /** All edits made in this session, keyed by `${lng}::${key}`. */
+    drafts: Map<string, DraftEntry>;
+    /** Bumps every time the store changes; React components subscribe to this. */
+    version: number;
+}
+/** Stable empty snapshot for useSyncExternalStore when the store is not ready. */
+export declare const EMPTY_I18N_STORE_SNAPSHOT: I18nStoreSnapshot;
+type Listener = (snap: I18nStoreSnapshot) => void;
+export declare class I18nStore {
+    private drafts;
+    private version;
+    private listeners;
+    /** Stable namespace used by react-i18next defaults. */
+    private ns;
+    private i18n;
+    /** Cached reference — useSyncExternalStore requires referential stability. */
+    private cachedSnapshot;
+    constructor(i18n: I18nType, options?: {
+        namespace?: string;
+    });
+    snapshot(): I18nStoreSnapshot;
+    subscribe(listener: Listener): () => void;
+    /**
+     * Returns the current rendered value for a key in a given language,
+     * reading through any draft layer.
+     */
+    get(key: string, lng: string): string;
+    /** Returns the original (pre-edit) value for a key. */
+    original(key: string, lng: string): string;
+    /**
+     * Records an edit. Mutates the live i18next bundle so consumers re-render.
+     * If the value is set back to the original, the draft entry is cleared.
+     */
+    set(key: string, lng: string, value: string): void;
+    /** Resets a single draft back to its original value. */
+    revert(key: string, lng: string): void;
+    /** Resets every draft. */
+    revertAll(): void;
+    /** Marks the current state as the new baseline (after a successful publish). */
+    commit(): void;
+    /** Number of pending draft entries across all languages. */
+    size(): number;
+    /**
+     * Serialises the full resource bundle per language as it currently looks in
+     * i18next (with drafts applied). Used as the payload for /publish.
+     *
+     * The caller maps language → file path via `sites.content_paths`.
+     */
+    serialiseBundles(): Record<string, unknown>;
+    private bump;
+}
+export {};

package/dist/lib/supabase.d.ts

@@ -0,0 +1,9 @@
+import { type SupabaseClient } from '@supabase/supabase-js';
+/**
+ * Returns a Supabase client for a given (url, anonKey) pair.
+ * Memoised so we never create more than one client per provider mount.
+ */
+export declare function getSupabase(config: {
+    url: string;
+    anonKey: string;
+}): SupabaseClient;

package/dist/lib/theme-store.d.ts

@@ -0,0 +1,35 @@
+/** Section colour theme — keyed by section id, then colour token. */
+export type SectionsTheme = Record<string, Record<string, string>>;
+export interface ThemeDraftEntry {
+    sectionId: string;
+    field: string;
+    original: string;
+    current: string;
+}
+export interface ThemeStoreSnapshot {
+    drafts: Map<string, ThemeDraftEntry>;
+    version: number;
+}
+export declare const EMPTY_THEME_STORE_SNAPSHOT: ThemeStoreSnapshot;
+type Listener = (snap: ThemeStoreSnapshot) => void;
+export declare class ThemeStore {
+    private data;
+    private baseline;
+    private drafts;
+    private version;
+    private listeners;
+    private cachedSnapshot;
+    constructor(initial: SectionsTheme);
+    snapshot(): ThemeStoreSnapshot;
+    subscribe(listener: Listener): () => void;
+    getSection(sectionId: string): Record<string, string>;
+    get(sectionId: string, field: string): string;
+    set(sectionId: string, field: string, value: string): void;
+    /** Replace baseline from GitHub without creating drafts. */
+    loadBaseline(next: SectionsTheme): void;
+    commit(): void;
+    size(): number;
+    serialise(): SectionsTheme;
+    private bump;
+}
+export {};