storyloco 1.15.2 → 2.0.0

package/README.md

@@ -24,7 +24,7 @@ A collection of slick Storyblok field plugins built with Svelte 5, TypeScript, a
 ### Storyblok Client
 
 - **🎯 StoryblokClient** - Reactive wrapper for Storyblok with Svelte 5 integration
-- **🔧 Utilities** - Re-exported `editable`, `Block`, and `richtext` functions
+- **🔧 Utilities** - `attrs` for wiring a block to the visual editor, plus re-exported `editable`, `Block`, and `richtext` functions
 
 ### Shared Components
 
@@ -68,18 +68,20 @@ import type { Video, Heading, Link, Input, Asset, SEO } from 'storyloco'
 import { StoryblokClient } from 'storyloco'
 import { PUBLIC_STORYBLOK_ACCESS_TOKEN } from '$env/static/public'
 
-// Create client (defaults to $lib/blocks/*.svelte) - init() called automatically
-export const client = new StoryblokClient(PUBLIC_STORYBLOK_ACCESS_TOKEN)
+export const client = new StoryblokClient({
+	token: PUBLIC_STORYBLOK_ACCESS_TOKEN,
+	relations: ['shared.items'],
+	components: import.meta.glob(['$blocks/**/*.svelte', '$templates/*.svelte'])
+})
+```
 
-// With custom component globs
-export const client = new StoryblokClient(
-	PUBLIC_STORYBLOK_ACCESS_TOKEN,
-	import.meta.glob(['$blocks/*.svelte', '$templates/*.svelte'])
-)
+Everything is configured here rather than by subclassing, and `init()` runs on its own — the
+API methods await it, so you never call it on the server. `components` takes the result of
+`import.meta.glob`: Vite has to see the literal pattern to rewrite it, so the glob has to stay
+at your call site rather than move into the client.
 
-// Single glob pattern
-export const client = new StoryblokClient(PUBLIC_STORYBLOK_ACCESS_TOKEN, import.meta.glob('$blocks/*.svelte'))
-```
+`client.handle_error` is on the instance, so `.catch(client.handle_error)` works without
+wrapping anything.
 
 #### 2. Use in your Svelte components
 
@@ -108,7 +110,7 @@ export const client = new StoryblokClient(PUBLIC_STORYBLOK_ACCESS_TOKEN, import.
 
 ```svelte
 <script lang="ts">
-	import { editable } from 'storyloco'
+	import { attrs } from 'storyloco'
 
    // This is auto-generated by the Storyblok Schema plugin
    import type { Blok, Hero } from '$lib/components.schema.js'
@@ -120,12 +122,78 @@ export const client = new StoryblokClient(PUBLIC_STORYBLOK_ACCESS_TOKEN, import.
 	let { blok } = $props()
 </script>
 
-<section use:editable={blok}>
+<section {...attrs(blok)}>
 	<h1>{blok.headline}</h1>
 	<p>{blok.subheadline}</p>
 </section>
 ```
 
+`attrs` makes the block editable in the visual editor and gives it a stable `id` — the
+block's `anchor` field when it has one, so sections can be linked to, otherwise its `_uid`.
+
+Prefer it to `use:editable`. Being an attachment rather than an action it spreads, so the
+element keeps its own attributes, and you can wrap it to add project-specific ones in one
+place rather than repeating them in every block:
+
+```typescript
+// Mapping section fields onto CSS custom properties is left to you — the field names and
+// the design tokens are yours. Wrap `attrs` rather than reaching past it:
+//
+// export function section<T extends SectionFields>(blok: Blok<T>) {
+//    let style = ''
+//    if (blok.theme) style += `--theme: var(--c-${blok.theme});`
+//    if (blok.pad_top) style += `--pt: var(--s-${blok.pad_top});`
+//    return { ...attrs(blok), style }
+// }
+```
+
+`editable` is still exported for anything `attrs` doesn't cover.
+
+### Read Content on the Server
+
+`storyloco/server` binds a client to the current request, so reads carry the version from
+the `version` hook and the resolve options you'd otherwise repeat everywhere. Server-only,
+since it reads the active request.
+
+**`$lib/storyblok.server.ts`:**
+
+```typescript
+import { setup } from 'storyloco/server'
+import { client } from './storyblok.js'
+
+export const storyblok = setup(client)
+```
+
+Then anywhere on the server:
+
+```typescript
+import { storyblok } from '$lib/storyblok.server.js'
+
+// A single story, with the client's `relations` resolved
+await storyblok.story('layout')
+
+// A list. `total` is the unpaged count, for "showing n of m"
+const { stories, total } = await storyblok.stories({ content_type: 'blog', per_page: 2 })
+
+// The link tree, flattened — Storyblok returns it keyed by uuid
+const links = await storyblok.links({ starts_with: 'blog/' })
+```
+
+Your params are spread last, so any default can be overridden:
+
+```typescript
+await storyblok.story('layout', { resolve_assets: 0 })
+```
+
+It's callable too, for anything the methods don't cover:
+
+```typescript
+const { client, version } = storyblok()
+await client.get('cdn/datasource_entries', { version })
+```
+
+Errors go through `handle_error`, so a missing story is a 404 and anything else a 500.
+
 ### Use Shared Components
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "storyloco",
-	"version": "1.15.2",
+	"version": "2.0.0",
 	"description": "A collection of slick Storyblok field plugins built with Svelte 5, TypeScript, and Tailwind CSS",
 	"keywords": [
 		"storyblok",
@@ -25,13 +25,15 @@
 		"packages/plans/types.ts",
 		"packages/link/types.ts",
 		"packages/asset/types.ts",
+		"packages/asset/r2.ts",
 		"packages/theme/types.ts",
 		"packages/shared/dist",
 		"packages/vite/dist",
 		"packages/ticketsource/types.ts",
 		"packages/input/types.ts",
 		"packages/time/types.ts",
-		"packages/seo/types.ts"
+		"packages/seo/types.ts",
+		"packages/hubspot_form/types.ts"
 	],
 	"exports": {
 		".": {
@@ -77,27 +79,38 @@
 			"types": "./packages/vite/dist/hooks.d.ts",
 			"import": "./packages/vite/dist/hooks.js"
 		},
+		"./server": {
+			"types": "./packages/vite/dist/server.d.ts",
+			"import": "./packages/vite/dist/server.js"
+		},
 		"./time": {
 			"types": "./packages/time/types.ts",
 			"svelte": "./packages/time/src/app.svelte.ts"
 		},
 		"./seo": {
 			"types": "./packages/seo/types.ts"
+		},
+		"./hubspot_form": {
+			"types": "./packages/hubspot_form/types.ts",
+			"svelte": "./packages/hubspot_form/src/app.svelte.ts"
 		}
 	},
 	"devDependencies": {
-		"@types/node": "24.10.0",
-		"@typescript-eslint/eslint-plugin": "8.46.3",
-		"@typescript-eslint/parser": "8.46.3",
-		"eslint": "9.39.1",
-		"kitto": "1.0.0-rc.17",
-		"typescript": "5.9.3",
-		"vite": "7.2.0"
+		"@types/node": "26.1.1",
+		"@typescript-eslint/eslint-plugin": "8.65.0",
+		"@typescript-eslint/parser": "8.65.0",
+		"eslint": "10.7.0",
+		"kitto": "1.6.0",
+		"oxfmt": "0.59.0",
+		"typescript": "6.0.3",
+		"vite": "8.1.5"
 	},
 	"peerDependencies": {
-		"@storyblok/svelte": "5.2.14",
-		"@storyblok/field-plugin": "^1.6.0",
-		"svelte": "^5.0.0"
+		"@storyblok/svelte": "7.2.2",
+		"@storyblok/field-plugin": "^1.7.1",
+		"svelte": "^5.0.0",
+		"@sveltejs/kit": "^2.0.0",
+		"storyblok-js-client": "^7.0.0"
 	},
 	"scripts": {
 		"add-plugin": "npx @storyblok/field-plugin-cli@latest add --dir \"./packages\" --structure monorepo",
@@ -110,8 +123,7 @@
 		"packages/*"
 	],
 	"dependencies": {
-		"ora": "9.0.0",
-		"oxfmt": "0.55.0",
-		"path-to-regexp": "8.3.0"
+		"ora": "9.4.1",
+		"path-to-regexp": "8.4.2"
 	}
 }

package/packages/asset/r2.ts

@@ -0,0 +1,217 @@
+/**
+ * Vendored subset of the `moxyloco/r2` types.
+ *
+ * These are hand-copied from the moxy R2 OpenAPI client so storyloco consumers
+ * don't need `moxyloco` (and its `openapi-client-axios` dependency) installed
+ * just to read the asset field-plugin types. Only the schemas and operations the
+ * plugin actually uses are modelled here.
+ */
+
+/* Asset resource in JSON:API format */
+export interface R2Asset {
+	/* Resource type */
+	type: 'asset'
+
+	/* Unique asset identifier (uuid) */
+	id: string
+
+	attributes: R2AssetAttributes
+
+	links?: {
+		/* URL to this asset */
+		self?: string
+
+		/* Public URL for accessing the asset */
+		public?: string
+	}
+}
+
+/* Asset attributes */
+export interface R2AssetAttributes {
+	/* Original filename */
+	filename: string
+
+	/* Display name for the asset (can be different from filename) */
+	name?: string
+
+	/* File size in bytes */
+	size_bytes: number
+
+	/* MIME type of the file */
+	content_type?: string
+
+	/* Detected file format (e.g. "jpeg", "png") */
+	format?: string
+
+	/* Image width in pixels (for images) */
+	width?: number
+
+	/* Image height in pixels (for images) */
+	height?: number
+
+	/* When the asset was uploaded (date-time) */
+	created_at: string
+
+	/* Title for the asset */
+	title?: string
+
+	/* Alt text for accessibility */
+	alt?: string
+
+	/* Source attribution */
+	source?: string
+
+	/* Copyright information */
+	copyright?: string
+
+	/* Focus point for image cropping */
+	focus?: string
+
+	/* Whether the asset is soft-deleted */
+	deleted?: boolean
+
+	/* When the asset was deleted, if applicable (date-time) */
+	deleted_at?: string | null
+}
+
+/* Folder resource in JSON:API format */
+export interface R2Folder {
+	/* Resource type */
+	type: 'folder'
+
+	/* Unique folder identifier (uuid) */
+	id: string
+
+	attributes: R2FolderAttributes
+}
+
+/* Folder attributes */
+export interface R2FolderAttributes {
+	/* Folder name */
+	name: string
+
+	/* UUID of parent folder (null for root folders) */
+	parent_id?: string | null
+
+	/* Number of assets in this folder */
+	asset_count: number
+}
+
+/* Structured folder tree format with unlimited nesting */
+export interface R2FolderTree {
+	/* Folder name */
+	name: string
+
+	/* Folder UUID */
+	id: string
+
+	/* UUID of parent folder (null for root folders) */
+	parent_id?: string | null
+
+	/* Number of assets in this folder */
+	asset_count: number
+
+	/* Child folders (recursive) */
+	children: Array<R2FolderTree>
+}
+
+/* Request/response shapes for the R2 operations the plugin calls */
+export namespace Paths {
+	export namespace ListAssets {
+		export namespace Responses {
+			export interface $200 {
+				data?: Array<R2Asset>
+				included?: Array<R2Folder>
+				meta?: {
+					page?: number
+					limit?: number
+					total?: number
+					total_pages?: number
+				}
+				links?: {
+					self?: string
+					next?: string
+					prev?: string
+				}
+			}
+		}
+	}
+
+	export namespace UpdateAssetsBulk {
+		export interface RequestBody {
+			/* Array of asset UUIDs to update */
+			assets: Array<string>
+			metadata: {
+				name?: string
+				alt?: string
+				title?: string
+				source?: string
+				copyright?: string
+				focus?: string
+				/* UUID of the folder to move the assets to (null for no folder) */
+				folder_id?: string | null
+			}
+		}
+
+		export namespace Responses {
+			export type $204 = Record<string, never>
+		}
+	}
+
+	export namespace UpdateAssetMetadata {
+		export interface RequestBody {
+			name?: string
+			alt?: string
+			title?: string
+			source?: string
+			copyright?: string
+			focus?: string
+			/* UUID of the folder to move the asset to (null for no folder) */
+			folder_id?: string | null
+		}
+
+		export namespace Responses {
+			export interface $200 {
+				data?: R2Asset
+			}
+		}
+	}
+
+	export namespace CreateFolder {
+		export interface RequestBody {
+			/* Folder name */
+			name: string
+
+			/* UUID of parent folder (null for root folders) */
+			parent_id?: string | null
+		}
+
+		export namespace Responses {
+			export interface $201 {
+				data?: R2Folder
+				meta?: {
+					/* Indicates the folder was created */
+					created?: boolean
+				}
+			}
+		}
+	}
+
+	export namespace ListFolders {
+		export namespace Responses {
+			export interface $200 {
+				data?: {
+					/* JSON:API format folder list */
+					list?: Array<R2Folder>
+
+					/* Structured tree format for easier frontend consumption */
+					structured?: Array<R2FolderTree>
+				}
+				meta?: {
+					/* Total number of folders */
+					total?: number
+				}
+			}
+		}
+	}
+}

package/packages/asset/types.ts

@@ -1,4 +1,4 @@
-import type { R2Asset, R2AssetAttributes } from 'moxyloco/r2'
+import type { R2Asset, R2AssetAttributes } from './r2.js'
 
 interface StoryblokAsset {
 	/* The numeric ID */

package/packages/hubspot_form/types.ts

@@ -0,0 +1,4 @@
+export interface HubspotForm {
+	id: string
+	name: string
+}

package/packages/mux/types.ts

@@ -1,7 +1,70 @@
-import type Mux from '@mux/mux-node'
+/**
+ * Vendored subset of the Mux `Asset` type (previously from `@mux/mux-node`).
+ * Kept self-contained so consumers don't need the Mux SDK installed just to read
+ * these types. Only the fields the plugin actually touches are modelled — the real
+ * SDK `Asset` remains structurally assignable to this.
+ */
+export interface MuxPlaybackID {
+	/* Unique identifier for the PlaybackID */
+	id: string
+
+	/* How the playback ID is secured */
+	policy: 'public' | 'signed' | 'drm'
+
+	/* DRM configuration used by this playback ID (only when `policy` is `drm`) */
+	drm_configuration_id?: string
+}
+
+export interface MuxAssetErrors {
+	/* Error messages with more details */
+	messages?: Array<string>
+
+	/* The type of error that occurred for this asset */
+	type?: string
+}
+
+export interface MuxAssetMeta {
+	/* Identifier for the creator of the asset */
+	creator_id?: string
+
+	/* Identifier linking the asset to your own data */
+	external_id?: string
+
+	/* The asset title */
+	title?: string
+}
+
+export interface MuxAsset {
+	/* Unique identifier for the Asset */
+	id: string
+
+	/* Time the Asset was created (Unix timestamp, seconds since epoch) */
+	created_at: string
+
+	/* The status of the asset */
+	status: 'preparing' | 'ready' | 'errored'
+
+	/* Object describing any errors that happened when processing this asset */
+	errors?: MuxAssetErrors
+
+	/* The aspect ratio of the asset in the form `width:height` (e.g. `16:9`) */
+	aspect_ratio?: string
+
+	/* The duration of the asset in seconds */
+	duration?: number
+
+	/* Playback ID objects used to build HLS playback URLs */
+	playback_ids?: Array<MuxPlaybackID>
+
+	/* Customer provided metadata about this asset */
+	meta?: MuxAssetMeta
+
+	/* Arbitrary passthrough value included in the asset details and webhooks */
+	passthrough?: string
+}
 
 export interface Video {
-	mux_video?: Mux.Video.Assets.Asset
+	mux_video?: MuxAsset
 	playback_id?: string
 	m3u8_url?: string
 	title?: string

package/packages/shared/dist/components/ui/textarea/textarea.svelte

@@ -18,5 +18,4 @@
 		className
 	)}
 	bind:value
-	{...restProps}
-></textarea>
+	{...restProps}></textarea>

package/packages/shared/dist/global.css

@@ -54,7 +54,7 @@
 
 [data-theme='dark'] {
 	--teal-muted: oklch(74.591% 0.11569 187.182);
-	--background: oklch(32.303% 0.00881 285.843);
+	--background: #333338;
 	--foreground: oklch(0.984 0.003 247.858);
 	--card: oklch(26.239% 0.00928 285.704);
 	--card-foreground: oklch(0.984 0.003 247.858);

package/packages/vite/dist/hooks.d.ts

@@ -1 +1,9 @@
+import type { Handle } from "@sveltejs/kit";
 export { handle_redirects as redirects } from "./redirects/handle.js";
+/**
+ * Put the Storyblok content version on `event.locals.version` — draft while developing and
+ * inside the visual editor (`?_storyblok`), published everywhere else.
+ *
+ * Declare it on `App.Locals` as `version: import("storyloco").Version`.
+ */
+export declare const version: Handle;

package/packages/vite/dist/hooks.js

@@ -1 +1,12 @@
+import { dev } from "$app/environment";
 export { handle_redirects as redirects } from "./redirects/handle.js";
+/**
+ * Put the Storyblok content version on `event.locals.version` — draft while developing and
+ * inside the visual editor (`?_storyblok`), published everywhere else.
+ *
+ * Declare it on `App.Locals` as `version: import("storyloco").Version`.
+ */
+export const version = async ({ event, resolve }) => {
+    event.locals.version = dev || event.url.searchParams.has("_storyblok") ? "draft" : "published";
+    return await resolve(event);
+};

package/packages/vite/dist/schema/plugin.js

@@ -4,9 +4,33 @@ import path from "node:path";
 import { $ } from "../shared/shell.js";
 import exec from "../shared/x.js";
 import { Logger } from "../shared/logger.js";
-import { format } from "oxfmt";
 const name = "vite-storyblok-schema";
 const logger = new Logger(name);
+/**
+ * Formats generated code as a nicety, not a necessity. Prefers oxfmt if it's
+ * installed, falls back to prettier if that happens to be around, and otherwise
+ * leaves the code untouched. Never throws — formatting is entirely optional and
+ * these tools are intentionally not hard dependencies.
+ */
+async function format_code(filename, content) {
+    try {
+        const oxfmt = await import("oxfmt");
+        const { code } = await oxfmt.format(filename, content);
+        return code;
+    }
+    catch {
+        /* oxfmt not available — try the next option */
+    }
+    try {
+        const specifier = "prettier";
+        const prettier = await import(specifier);
+        return await prettier.format(content, { filepath: filename });
+    }
+    catch {
+        /* prettier not available either — leave the code as-is */
+    }
+    return content;
+}
 /**
  * @remarks
  * Vite plugin that automatically regenerates Storyblok component types at regular intervals
@@ -176,7 +200,7 @@ import type { ISbStoryData } from '@storyblok/js';`, "");
                     content = content.replace(/any\[]/g, "unknown[]");
                     // Make _uid and component optional (helps us reuse Storyblok types for non-storyblok components)
                     content = content.replace(/^([a-zA-Z0-9_]+):/gm, "$1?:");
-                    const { code: formatted } = await format(path.basename(schema_ts_file), content);
+                    const formatted = await format_code(path.basename(schema_ts_file), content);
                     // Write the final file
                     logger.start("Finalising schema file...");
                     await writeFile(schema_ts_file, formatted);

package/packages/vite/dist/server.d.ts

@@ -0,0 +1,51 @@
+import type { ISbStoriesParams, ISbStoryData, ISbStoryParams } from "@storyblok/svelte";
+import type { ISbLink, ISbLinksParams } from "storyblok-js-client";
+import { type StoryblokClient, type Version } from "./storyblok.svelte.js";
+/** The content version for the current request, as set by the `version` hook. */
+export declare function version(): Version;
+/**
+ * Bind a client to the current request.
+ *
+ * Returns a callable: call it for the client and version to reach anything the methods
+ * don't cover, or use `.story` / `.stories` for the common reads. Those carry the
+ * request's version and the resolve options a Storyblok read almost always wants; the
+ * caller's params are spread last, so every default can be overridden. `resolve_links`
+ * is on because `href` depends on it.
+ *
+ * @example
+ * ```ts
+ * // $lib/storyblok.server.ts
+ * export const storyblok = setup(client)
+ *
+ * // anywhere on the server
+ * await storyblok.story("layout")
+ * await storyblok.stories<Blog>({ content_type: "blog", per_page: 2 })
+ *
+ * const { client, version } = storyblok()
+ * await client.get("cdn/links", { version })
+ * ```
+ */
+export declare function setup(client: StoryblokClient): (() => {
+    client: StoryblokClient;
+    version: Version;
+}) & {
+    /**
+     * A single story by full slug. Resolves the client's `relations`, unlike `stories`.
+     *
+     * `T` is the story's content type; it defaults to the SDK's permissive one, so an
+     * unparameterised call behaves as before.
+     */
+    story<T = import("storyblok-js-client").ISbComponentType<string> & {
+        [index: string]: any;
+    }>(slug: string, params?: ISbStoryParams): Promise<ISbStoryData<T>>;
+    /**
+     * The link tree as a flat array — Storyblok returns it keyed by uuid, which is
+     * almost never what you want. Filtering and ordering are left to the caller.
+     */
+    links(params?: ISbLinksParams): Promise<ISbLink[]>;
+    /** A list of stories. `total` is the unpaged count, for "showing n of m". */
+    stories<T>(params?: ISbStoriesParams): Promise<{
+        stories: Array<ISbStoryData<T>>;
+        total: number;
+    }>;
+};