storyloco 2.1.0 → 2.3.0

package/README.md

@@ -15,6 +15,7 @@ A collection of slick Storyblok field plugins built with Svelte 5, TypeScript, a
 - **🏗️ Plans** - Floor plan manager with drag-and-drop sorting for types, floors, dimensions, and rooms
 - **📝 Input** - Comprehensive form input field with support for all HTML input types, checkboxes, radio buttons, selects, and textareas
 - **⏰ Time** - Simple time input field with step control
+- **💷 Currency** - Amount input with a currency selector; configure allowed codes via the `currencies` and `default_currency` options
 
 ### Vite Plugins
 
@@ -175,16 +176,45 @@ 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 })
 
+// Everything that matches, paged through the API's 100-per-page cap
+const products = await storyblok.all({ content_type: 'product' })
+
 // The link tree, flattened — Storyblok returns it keyed by uuid
 const links = await storyblok.links({ starts_with: 'blog/' })
 ```
 
+Reads with a `content_type` are typed from your generated schema: the plugin registers
+the space's content types with storyloco, so `stories({ content_type: 'product' })` yields
+product stories and `content_type: 'product,category'` a union of both — no type argument
+needed. Until a schema has been generated, or for a name it doesn't know, the content falls
+back to the SDK's permissive type. An explicit type argument always wins.
+
 Your params are spread last, so any default can be overridden:
 
 ```typescript
 await storyblok.story('layout', { resolve_assets: 0 })
 ```
 
+`story` treats a missing story as a 404. Where a slug is allowed not to exist, `find` returns
+`null` instead — the miss is then neither raised nor logged:
+
+```typescript
+const product = await storyblok.find<Product>(`products/${slug}`)
+if (!product) error(404, 'Product not found')
+```
+
+The content type can be a union. Each member becomes its own story type, so `is_component`
+can narrow the result — checking `story.content.component` yourself narrows only `content`,
+not the story:
+
+```typescript
+import { is_component } from 'storyloco'
+
+const story = await storyblok.find<Product | Category>(`products/${slug}`)
+if (is_component(story, 'product')) story.content.sku // ISbStoryData<Product>
+if (is_component(story, 'category')) story.content.description // ISbStoryData<Category>
+```
+
 It's callable too, for anything the methods don't cover:
 
 ```typescript
@@ -258,6 +288,7 @@ export interface StoryblokCustomPlugins {
 		twitter_description: string
 	}
 	'loco-time': string
+	'loco-currency': import('storyloco/currency').Currency
 	'loco-asset': import('storyloco/asset').Asset
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "storyloco",
-	"version": "2.1.0",
+	"version": "2.3.0",
 	"description": "A collection of slick Storyblok field plugins built with Svelte 5, TypeScript, and Tailwind CSS",
 	"keywords": [
 		"storyblok",
@@ -33,7 +33,8 @@
 		"packages/input/types.ts",
 		"packages/time/types.ts",
 		"packages/seo/types.ts",
-		"packages/hubspot_form/types.ts"
+		"packages/hubspot_form/types.ts",
+		"packages/currency/types.ts"
 	],
 	"exports": {
 		".": {
@@ -93,6 +94,10 @@
 		"./hubspot_form": {
 			"types": "./packages/hubspot_form/types.ts",
 			"svelte": "./packages/hubspot_form/src/app.svelte.ts"
+		},
+		"./currency": {
+			"types": "./packages/currency/types.ts",
+			"svelte": "./packages/currency/src/app.svelte.ts"
 		}
 	},
 	"devDependencies": {

package/packages/currency/types.ts

@@ -0,0 +1,11 @@
+/**
+ * Narrow `Code` to the codes configured in the field's `currencies` option,
+ * e.g. `Currency<'GBP' | 'USD'>`.
+ */
+export interface Currency<Code extends string = Uppercase<string>> {
+	/** ISO 4217 code, e.g. `GBP` */
+	currency: Code
+	amount: number | null
+	/** `amount` formatted for display, e.g. `£130,000.00`; `null` when there's no amount */
+	formatted: string | null
+}

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

@@ -218,6 +218,11 @@ import type { ISbStoryData } from '@storyblok/js';`, "");
 			               }
 
 			               export type ContentType = ContentTypes[keyof ContentTypes]
+
+			               /** Lets storyloco type reads by \`content_type\` without a type argument. */
+			               declare module "storyloco" {
+			                 interface Registry extends ContentTypes {}
+			               }
 			             `;
             let content = component_types.replace(`// This file was generated by the storyblok CLI.
 // DO NOT MODIFY THIS FILE BY HAND.`, header);

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

@@ -1,6 +1,6 @@
-import type { ISbStoriesParams, ISbStoryData, ISbStoryParams } from "@storyblok/svelte";
+import type { ISbStoriesParams, ISbStoryParams } from "@storyblok/svelte";
 import type { ISbLink, ISbLinksParams } from "storyblok-js-client";
-import { type StoryblokClient, type Version } from "./storyblok.svelte.js";
+import { type ContentFor, type Story, 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;
 /**
@@ -19,7 +19,10 @@ export declare function version(): Version;
  *
  * // anywhere on the server
  * await storyblok.story("layout")
- * await storyblok.stories<Blog>({ content_type: "blog", per_page: 2 })
+ * await storyblok.find<Product>(`products/${slug}`) // null when missing
+ * await storyblok.find<Product | Category>(slug) // a union of stories; narrow with is_component
+ * await storyblok.stories({ content_type: "blog", per_page: 2 }) // typed from the generated schema
+ * await storyblok.all<Product>({ content_type: "product" }) // every page
  *
  * const { client, version } = storyblok()
  * await client.get("cdn/links", { version })
@@ -29,23 +32,37 @@ 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> & {
+    story: <T = import("storyblok-js-client").ISbComponentType<string> & {
+        [index: string]: any;
+    }>(slug: string, params?: ISbStoryParams) => Promise<Story<T>>;
+    find: <T = import("storyblok-js-client").ISbComponentType<string> & {
         [index: string]: any;
-    }>(slug: string, params?: ISbStoryParams): Promise<ISbStoryData<T>>;
+    }>(slug: string, params?: ISbStoryParams) => Promise<Story<T> | null>;
+    stories: {
+        <K extends string>(params: ISbStoriesParams & {
+            content_type: K;
+        }): Promise<{
+            stories: Story<ContentFor<K>>[];
+            total: number;
+        }>;
+        <T = import("storyblok-js-client").ISbComponentType<string> & {
+            [index: string]: any;
+        }>(params?: ISbStoriesParams): Promise<{
+            stories: Story<T>[];
+            total: number;
+        }>;
+    };
+    all: {
+        <K extends string>(params: ISbStoriesParams & {
+            content_type: K;
+        }): Promise<Array<Story<ContentFor<K>>>>;
+        <T = import("storyblok-js-client").ISbComponentType<string> & {
+            [index: string]: any;
+        }>(params?: ISbStoriesParams): Promise<Array<Story<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;
-    }>;
 };

package/packages/vite/dist/server.js

@@ -1,5 +1,9 @@
 import { getRequestEvent } from "$app/server";
-import { handle_error } from "./storyblok.svelte.js";
+import { error } from "@sveltejs/kit";
+import { handle_error, } from "./storyblok.svelte.js";
+function is_not_found(err) {
+    return typeof err === "object" && err !== null && "status" in err && err.status === 404;
+}
 /** The content version for the current request, as set by the `version` hook. */
 export function version() {
     return getRequestEvent().locals.version;
@@ -20,7 +24,10 @@ export function version() {
  *
  * // anywhere on the server
  * await storyblok.story("layout")
- * await storyblok.stories<Blog>({ content_type: "blog", per_page: 2 })
+ * await storyblok.find<Product>(`products/${slug}`) // null when missing
+ * await storyblok.find<Product | Category>(slug) // a union of stories; narrow with is_component
+ * await storyblok.stories({ content_type: "blog", per_page: 2 }) // typed from the generated schema
+ * await storyblok.all<Product>({ content_type: "product" }) // every page
  *
  * const { client, version } = storyblok()
  * await client.get("cdn/links", { version })
@@ -28,25 +35,61 @@ export function version() {
  */
 export function setup(client) {
     const context = () => ({ client, version: version() });
+    /**
+     * A single story by full slug, or `null` when there isn't one. Resolves the client's
+     * `relations`, unlike `stories`. For slugs that are allowed not to exist — a miss is
+     * routine, so it's neither raised nor logged. `T` is the story's content type.
+     */
+    async function find(slug, params = {}) {
+        const response = await client
+            .get(`cdn/stories/${slug}`, {
+            version: version(),
+            resolve_links: "url",
+            resolve_relations: client.relations,
+            resolve_assets: 1,
+            ...params,
+        })
+            .catch((err) => {
+            if (is_not_found(err))
+                return null;
+            return handle_error(err);
+        });
+        return (response?.data.story ?? null);
+    }
+    /** A single story by full slug; a missing one is a 404. `find` for stories that may not exist. */
+    async function story(slug, params = {}) {
+        const found = await find(slug, params);
+        if (!found)
+            error(404, "Story not found");
+        return found;
+    }
+    async function stories(params = {}) {
+        const response = await client
+            .get("cdn/stories", {
+            version: version(),
+            resolve_links: "url",
+            resolve_assets: 1,
+            ...params,
+        })
+            .catch(handle_error);
+        return { stories: response.data.stories, total: response.total ?? 0 };
+    }
+    async function all(params = {}) {
+        return client
+            .getAll("cdn/stories", {
+            version: version(),
+            resolve_links: "url",
+            resolve_assets: 1,
+            per_page: 100,
+            ...params,
+        })
+            .catch(handle_error);
+    }
     return Object.assign(context, {
-        /**
-         * 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.
-         */
-        async story(slug, params = {}) {
-            const response = await client
-                .get(`cdn/stories/${slug}`, {
-                version: version(),
-                resolve_links: "url",
-                resolve_relations: client.relations,
-                resolve_assets: 1,
-                ...params,
-            })
-                .catch(handle_error);
-            return response.data.story;
-        },
+        story,
+        find,
+        stories,
+        all,
         /**
          * 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.
@@ -57,20 +100,5 @@ export function setup(client) {
                 .catch(handle_error);
             return Object.values(response.data.links ?? {});
         },
-        /** A list of stories. `total` is the unpaged count, for "showing n of m". */
-        async stories(params = {}) {
-            const response = await client
-                .get("cdn/stories", {
-                version: version(),
-                resolve_links: "url",
-                resolve_assets: 1,
-                ...params,
-            })
-                .catch(handle_error);
-            return {
-                stories: response.data.stories,
-                total: response.total ?? 0,
-            };
-        },
     });
 }

package/packages/vite/dist/storyblok.svelte.d.ts

@@ -140,6 +140,46 @@ export interface Richtext<Blocks = unknown> {
     content?: Array<Richtext<Blocks>>;
     marks?: Array<Richtext<Blocks>>;
 }
+/**
+ * Content types by component name, for narrowing reads by `content_type`. Empty here;
+ * the schema plugin's generated file merges the space's `ContentTypes` into it, so
+ * `storyblok.stories({ content_type: "product" })` is typed as products without a type
+ * argument. Until a schema is generated every name falls back to the SDK's content type.
+ */
+export interface Registry {
+}
+/** The SDK's permissive content type: any component, any fields. */
+export type Content = ISbStoryData["content"];
+/** Each name in a comma-separated `content_type`. */
+type Names<S extends string> = S extends `${infer A},${infer B}` ? A | Names<B> : S;
+/**
+ * The content behind a `content_type` param. Registered names map to their generated
+ * types (a list to their union); anything else is the permissive `Content`.
+ */
+export type ContentFor<K extends string> = [Names<K>] extends [keyof Registry] ? Registry[Names<K>] : Content;
+/**
+ * A story per member of `T`, so a union of content types is a union of stories —
+ * `Story<Product | Category>` is `ISbStoryData<Product> | ISbStoryData<Category>`, which
+ * `is_component` can narrow. `ISbStoryData<Product | Category>` can't be.
+ */
+export type Story<T> = T extends unknown ? ISbStoryData<T> : never;
+/**
+ * Narrow a story (or a union of them) by its content's `component`. TypeScript won't
+ * narrow the story through the nested discriminant on its own.
+ *
+ * @example
+ * ```ts
+ * const story = await storyblok.find<Product | Category>(`products/${slug}`)
+ * if (is_component(story, "product")) story.content.sku // ISbStoryData<Product>
+ * ```
+ */
+export declare function is_component<S extends ISbStoryData<{
+    component?: string;
+}>, K extends string>(story: S | null | undefined, component: K): story is Extract<S, {
+    content: {
+        component?: K;
+    };
+}>;
 /** Adds the `story.url` that `resolve_links: "url"` injects but the CLI doesn't declare. */
 export type Resolved<T extends {
     story?: unknown;

package/packages/vite/dist/storyblok.svelte.js

@@ -137,6 +137,19 @@ export class StoryblokClient {
         };
     }
 }
+/**
+ * Narrow a story (or a union of them) by its content's `component`. TypeScript won't
+ * narrow the story through the nested discriminant on its own.
+ *
+ * @example
+ * ```ts
+ * const story = await storyblok.find<Product | Category>(`products/${slug}`)
+ * if (is_component(story, "product")) story.content.sku // ISbStoryData<Product>
+ * ```
+ */
+export function is_component(story, component) {
+    return story?.content.component === component;
+}
 /**
  * Resolve a multilink to an href. Story links become root-relative, everything else passes
  * through. Prefers `story.url` over `cached_url`, which goes stale when a target moves —