storyloco 2.3.1 → 2.6.0

package/README.md

@@ -16,6 +16,7 @@ A collection of slick Storyblok field plugins built with Svelte 5, TypeScript, a
 - **📝 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
+- **📅 Dates** - List of dates, each with an optional time, end date and end time, plus a timezone picker; configure via the `min`, `max` and `auto_sort` options
 
 ### Vite Plugins
 
@@ -59,6 +60,35 @@ import type { SEO } from 'storyloco/seo'
 import type { Video, Heading, Link, Input, Asset, SEO } from 'storyloco'
 ```
 
+### Write Currency Values
+
+Map spreadsheet cells or plain numbers to the currency field's stored shape, e.g. for a Management API import:
+
+```ts
+import { to_currency } from 'storyloco/currency/utils'
+
+to_currency('£1,234.50') // currency defaults to GBP
+// { plugin: 'uiloco-currency', currency: 'GBP', amount: 1234.5, formatted: '£1,234.50' }
+to_currency('', 'GBP') // null
+to_currency('POA', 'GBP') // throws, as do negatives and too many decimal places
+```
+
+`format_currency(amount, code)` gives the same `formatted` string the plugin writes.
+
+### Display Dates
+
+Timed entries carry UTC instants, so the site formats them natively in the field's zone. All-day entries are dates, not moments: use `start_date`/`end_date` as they are.
+
+```ts
+import type { DateEntry, Dates } from 'storyloco/dates'
+
+const show = ({ timezone }: Dates, entry: DateEntry) =>
+	entry.utc_start
+		? new Intl.DateTimeFormat('en-GB', { timeZone: timezone, dateStyle: 'medium', timeStyle: 'short' })
+				.formatRange(new Date(entry.utc_start), new Date(entry.utc_end ?? entry.utc_start))
+		: [entry.start_date, entry.end_date].filter(Boolean).join(' – ')
+```
+
 ### Use Storyblok Client
 
 #### 1. Create your Storyblok client
@@ -84,6 +114,19 @@ at your call site rather than move into the client.
 `client.handle_error` is on the instance, so `.catch(client.handle_error)` works without
 wrapping anything.
 
+Errors carry only a `message` by default. If your `App.Error` needs more, pass `error` to shape
+the body of every 404 and 500 storyloco raises — it's typed against your own `App.Error`:
+
+```typescript
+export const client = new StoryblokClient({
+	token: PUBLIC_STORYBLOK_ACCESS_TOKEN,
+	error: (status) => ({
+		message: status === 404 ? 'Story not found' : 'Storyblok request failed',
+		code: status === 404 ? 'NOT_FOUND' : 'STORYBLOK'
+	})
+})
+```
+
 #### 2. Use in your Svelte components
 
 **`+page.svelte`:**
@@ -222,7 +265,7 @@ 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.
+Errors go through `client.handle_error`, so a missing story is a 404 and anything else a 500, shaped by the client's `error` option.
 
 ### Use Shared Components
 
@@ -289,6 +332,7 @@ export interface StoryblokCustomPlugins {
 	}
 	'loco-time': string
 	'loco-currency': import('storyloco/currency').Currency
+	'loco-dates': import('storyloco/dates').Dates
 	'loco-asset': import('storyloco/asset').Asset
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "storyloco",
-	"version": "2.3.1",
+	"version": "2.6.0",
 	"description": "A collection of slick Storyblok field plugins built with Svelte 5, TypeScript, and Tailwind CSS",
 	"keywords": [
 		"storyblok",
@@ -29,12 +29,15 @@
 		"packages/theme/types.ts",
 		"packages/shared/dist",
 		"packages/vite/dist",
+		"packages/vite/src/lib/currency.ts",
+		"!packages/vite/dist/**/*.test.*",
 		"packages/ticketsource/types.ts",
 		"packages/input/types.ts",
 		"packages/time/types.ts",
 		"packages/seo/types.ts",
 		"packages/hubspot_form/types.ts",
-		"packages/currency/types.ts"
+		"packages/currency/types.ts",
+		"packages/dates/types.ts"
 	],
 	"exports": {
 		".": {
@@ -98,6 +101,14 @@
 		"./currency": {
 			"types": "./packages/currency/types.ts",
 			"svelte": "./packages/currency/src/app.svelte.ts"
+		},
+		"./currency/utils": {
+			"types": "./packages/vite/dist/currency.d.ts",
+			"import": "./packages/vite/dist/currency.js"
+		},
+		"./dates": {
+			"types": "./packages/dates/types.ts",
+			"svelte": "./packages/dates/src/app.svelte.ts"
 		}
 	},
 	"devDependencies": {
@@ -108,7 +119,7 @@
 		"kitto": "1.6.0",
 		"oxfmt": "0.59.0",
 		"typescript": "6.0.3",
-		"vite": "8.1.5"
+		"vite": "7.2.2"
 	},
 	"peerDependencies": {
 		"@storyblok/svelte": "7.2.2",

package/packages/currency/types.ts

@@ -1,11 +1 @@
-/**
- * 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
-}
+export type { Currency, CurrencyField } from '../vite/src/lib/currency.js'

package/packages/dates/types.ts

@@ -0,0 +1,20 @@
+export interface DateEntry {
+	/** `YYYY-MM-DD`, wall-clock in the field's `timezone` */
+	start_date: string
+	/** `HH:mm`; `null` makes this an all-day entry */
+	start_time: string | null
+	/** `YYYY-MM-DD`; `null` means the same day as `start_date` */
+	end_date: string | null
+	/** `HH:mm`; only set when `start_time` is */
+	end_time: string | null
+	/** the start as an ISO instant, e.g. `2026-09-15T10:00:00.000Z`; `null` for all-day entries, which are dates, not moments */
+	utc_start: string | null
+	/** the end as an ISO instant; `null` without an `end_time` */
+	utc_end: string | null
+}
+
+export interface Dates {
+	/** IANA zone the editor picked, e.g. `Europe/London` */
+	timezone: string
+	dates: DateEntry[]
+}

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

@@ -0,0 +1,27 @@
+/**
+ * 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;
+}
+/** The field's value as Storyblok stores it, `plugin` key included — what a Management API write needs. */
+export type CurrencyField<Code extends string = Uppercase<string>> = Currency<Code> & {
+    plugin: "uiloco-currency";
+};
+/** `amount` as the plugin displays it, e.g. `£1,234.50`. The plugin formats with this, so the two can't drift. */
+export declare function format_currency(amount: number, currency?: string): string;
+/**
+ * A spreadsheet cell or plain number as the `uiloco-currency` field's value:
+ * `to_currency('£1,234.50', 'GBP')` → `{ plugin, currency: 'GBP', amount: 1234.5, formatted: '£1,234.50' }`.
+ *
+ * Takes what a CSV export of money looks like — a leading symbol or code, thousands
+ * commas — and throws on anything else rather than guessing: negatives, `POA`, a
+ * decimal comma, or more places than the currency has (`1.005` in GBP). An import
+ * should stop on a bad row, not write a wrong price. Blank returns `null`.
+ */
+export declare function to_currency<Code extends Uppercase<string> = "GBP">(value: string | number | null | undefined, currency?: Code): CurrencyField<Code> | null;

package/packages/vite/dist/currency.js

@@ -0,0 +1,45 @@
+/** `amount` as the plugin displays it, e.g. `£1,234.50`. The plugin formats with this, so the two can't drift. */
+export function format_currency(amount, currency = "GBP") {
+    return new Intl.NumberFormat("en", {
+        style: "currency",
+        currency,
+        currencyDisplay: "narrowSymbol",
+    }).format(amount);
+}
+function minor_digits(currency) {
+    return (new Intl.NumberFormat("en", { style: "currency", currency }).resolvedOptions()
+        .maximumFractionDigits ?? 2);
+}
+/**
+ * A spreadsheet cell or plain number as the `uiloco-currency` field's value:
+ * `to_currency('£1,234.50', 'GBP')` → `{ plugin, currency: 'GBP', amount: 1234.5, formatted: '£1,234.50' }`.
+ *
+ * Takes what a CSV export of money looks like — a leading symbol or code, thousands
+ * commas — and throws on anything else rather than guessing: negatives, `POA`, a
+ * decimal comma, or more places than the currency has (`1.005` in GBP). An import
+ * should stop on a bad row, not write a wrong price. Blank returns `null`.
+ */
+export function to_currency(value, currency = "GBP") {
+    if (value === null || value === undefined)
+        return null;
+    const input = String(value).trim();
+    if (input === "")
+        return null;
+    const raw = input
+        .replace(/^[^\d\s.,-]{1,3}\s?/, "")
+        .replace(/\s?[A-Z]{3}$/, "")
+        .replace(/,(?=\d{3}(?:\D|$))/g, "");
+    const match = /^(\d+)(?:\.(\d+))?$/.exec(raw);
+    if (!match)
+        throw new RangeError(`Not a ${currency} amount: ${JSON.stringify(value)}`);
+    if ((match[2]?.length ?? 0) > minor_digits(currency)) {
+        throw new RangeError(`${JSON.stringify(value)} has more decimal places than ${currency} allows`);
+    }
+    const amount = Number(raw);
+    return {
+        plugin: "uiloco-currency",
+        currency,
+        amount,
+        formatted: format_currency(amount, currency),
+    };
+}

package/packages/vite/dist/server.js

@@ -1,6 +1,6 @@
 import { getRequestEvent } from "$app/server";
 import { error } from "@sveltejs/kit";
-import { handle_error, } from "./storyblok.svelte.js";
+import {} from "./storyblok.svelte.js";
 function is_not_found(err) {
     return typeof err === "object" && err !== null && "status" in err && err.status === 404;
 }
@@ -52,7 +52,7 @@ export function setup(client) {
             .catch((err) => {
             if (is_not_found(err))
                 return null;
-            return handle_error(err);
+            return client.handle_error(err);
         });
         return (response?.data.story ?? null);
     }
@@ -60,7 +60,7 @@ export function setup(client) {
     async function story(slug, params = {}) {
         const found = await find(slug, params);
         if (!found)
-            error(404, "Story not found");
+            error(404, client.error(404));
         return found;
     }
     async function stories(params = {}) {
@@ -71,7 +71,7 @@ export function setup(client) {
             resolve_assets: 1,
             ...params,
         })
-            .catch(handle_error);
+            .catch(client.handle_error);
         return { stories: response.data.stories, total: response.total ?? 0 };
     }
     async function all(params = {}) {
@@ -83,7 +83,7 @@ export function setup(client) {
             per_page: 100,
             ...params,
         })
-            .catch(handle_error);
+            .catch(client.handle_error);
     }
     return Object.assign(context, {
         story,
@@ -97,7 +97,7 @@ export function setup(client) {
         async links(params = {}) {
             const response = await client
                 .get("cdn/links", { version: version(), per_page: 1000, ...params })
-                .catch(handle_error);
+                .catch(client.handle_error);
             return Object.values(response.data.links ?? {});
         },
     });

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

@@ -43,7 +43,15 @@ export interface ClientOptions {
      * news posts reuse the blog template. Applied by `template`.
      */
     aliases?: Record<string, string>;
+    /**
+     * The body of the errors storyloco raises, for projects whose `App.Error` needs more
+     * than a message — e.g. `(status) => ({ message: "Not found", code: "NOT_FOUND" })`.
+     * `cause` is the Storyblok error, when there was one.
+     */
+    error?: ErrorBody;
 }
+/** Shapes the body of a 404 (missing story) or 500 (anything else Storyblok threw) */
+export type ErrorBody = (status: 404 | 500, cause?: unknown) => App.Error;
 /** Type alias for the storyblok api instance */
 type API = ReturnType<typeof useStoryblokApi>;
 /**
@@ -83,8 +91,10 @@ export declare class StoryblokClient {
     put: API["put"];
     /** Make a DELETE request to the Storyblok API */
     delete: API["delete"];
-    /** The standalone `handle_error`, on the instance so `.catch(client.handle_error)` works */
-    handle_error: typeof handle_error;
+    /** Shapes the body of every error storyloco raises; see `ClientOptions.error` */
+    error: ErrorBody;
+    /** `handle_error` with this client's `error` shape, bound so `.catch(client.handle_error)` works */
+    handle_error: (err: unknown) => never;
     /**
      * Configured here rather than by subclassing, so setup is one expression.
      *
@@ -97,7 +107,7 @@ export declare class StoryblokClient {
      * })
      * ```
      */
-    constructor({ token, components, relations, aliases }: ClientOptions);
+    constructor({ token, components, relations, aliases, error, }: ClientOptions);
     /**
      * Load the components and set up the SDK.
      *
@@ -215,9 +225,10 @@ export declare function href(link?: Link): string | undefined;
  * Turn a Storyblok error into a SvelteKit one, for `.catch(handle_error)`.
  *
  * A missing story is a 404; anything else is a 500, since the CMS being unreachable isn't
- * something to show a visitor a Storyblok status code for.
+ * something to show a visitor a Storyblok status code for. `body` shapes the error; prefer
+ * `client.handle_error`, which passes the client's own.
  */
-export declare function handle_error(err: unknown): never;
+export declare function handle_error(err: unknown, body?: ErrorBody): never;
 /** Declaring these keeps `SbBlokData`'s index signature from widening every access. */
 interface BlokFields {
     anchor?: string;

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

@@ -2,6 +2,9 @@ import { storyblokInit, apiPlugin, renderRichText as richtext, useStoryblokBridg
 import { SvelteMap } from "svelte/reactivity";
 import { createAttachmentKey as attach } from "svelte/attachments";
 import { error } from "@sveltejs/kit";
+const default_error = (status) => ({
+    message: status === 404 ? "Story not found" : "Internal server error",
+});
 /**
  * Main Storyblok client class that handles component registration, API calls, and story bridging
  * Provides a unified interface for working with Storyblok in Svelte applications
@@ -56,8 +59,10 @@ export class StoryblokClient {
     put = async (...args) => (await this.#api()).put(...args);
     /** Make a DELETE request to the Storyblok API */
     delete = async (...args) => (await this.#api()).delete(...args);
-    /** The standalone `handle_error`, on the instance so `.catch(client.handle_error)` works */
-    handle_error = handle_error;
+    /** Shapes the body of every error storyloco raises; see `ClientOptions.error` */
+    error = default_error;
+    /** `handle_error` with this client's `error` shape, bound so `.catch(client.handle_error)` works */
+    handle_error = (err) => handle_error(err, this.error);
     /**
      * Configured here rather than by subclassing, so setup is one expression.
      *
@@ -70,11 +75,12 @@ export class StoryblokClient {
      * })
      * ```
      */
-    constructor({ token, components = {}, relations = [], aliases = {} }) {
+    constructor({ token, components = {}, relations = [], aliases = {}, error = default_error, }) {
         this.#access_token = token;
         this.#component_imports = components;
         this.relations = relations;
         this.aliases = aliases;
+        this.error = error;
         // Eager, but handled so a failure surfaces to whoever awaits `init` rather than
         // as an unhandled rejection
         this.init().catch(() => { });
@@ -166,14 +172,15 @@ export function href(link) {
  * Turn a Storyblok error into a SvelteKit one, for `.catch(handle_error)`.
  *
  * A missing story is a 404; anything else is a 500, since the CMS being unreachable isn't
- * something to show a visitor a Storyblok status code for.
+ * something to show a visitor a Storyblok status code for. `body` shapes the error; prefer
+ * `client.handle_error`, which passes the client's own.
  */
-export function handle_error(err) {
+export function handle_error(err, body = default_error) {
     console.error(err);
     const status = typeof err === "object" && err !== null && "status" in err ? err.status : undefined;
     if (status === 404)
-        error(404, "Story not found");
-    error(500, "Internal server error");
+        error(404, body(404, err));
+    error(500, body(500, err));
 }
 /**
  * Spread onto a block's root element to wire it up for the visual editor.

package/packages/vite/src/lib/currency.ts

@@ -0,0 +1,68 @@
+/**
+ * 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
+}
+
+/** The field's value as Storyblok stores it, `plugin` key included — what a Management API write needs. */
+export type CurrencyField<Code extends string = Uppercase<string>> = Currency<Code> & {
+	plugin: "uiloco-currency"
+}
+
+/** `amount` as the plugin displays it, e.g. `£1,234.50`. The plugin formats with this, so the two can't drift. */
+export function format_currency(amount: number, currency: string = "GBP"): string {
+	return new Intl.NumberFormat("en", {
+		style: "currency",
+		currency,
+		currencyDisplay: "narrowSymbol",
+	}).format(amount)
+}
+
+function minor_digits(currency: string): number {
+	return (
+		new Intl.NumberFormat("en", { style: "currency", currency }).resolvedOptions()
+			.maximumFractionDigits ?? 2
+	)
+}
+
+/**
+ * A spreadsheet cell or plain number as the `uiloco-currency` field's value:
+ * `to_currency('£1,234.50', 'GBP')` → `{ plugin, currency: 'GBP', amount: 1234.5, formatted: '£1,234.50' }`.
+ *
+ * Takes what a CSV export of money looks like — a leading symbol or code, thousands
+ * commas — and throws on anything else rather than guessing: negatives, `POA`, a
+ * decimal comma, or more places than the currency has (`1.005` in GBP). An import
+ * should stop on a bad row, not write a wrong price. Blank returns `null`.
+ */
+export function to_currency<Code extends Uppercase<string> = "GBP">(
+	value: string | number | null | undefined,
+	currency: Code = "GBP" as Code
+): CurrencyField<Code> | null {
+	if (value === null || value === undefined) return null
+	const input = String(value).trim()
+	if (input === "") return null
+
+	const raw = input
+		.replace(/^[^\d\s.,-]{1,3}\s?/, "")
+		.replace(/\s?[A-Z]{3}$/, "")
+		.replace(/,(?=\d{3}(?:\D|$))/g, "")
+	const match = /^(\d+)(?:\.(\d+))?$/.exec(raw)
+	if (!match) throw new RangeError(`Not a ${currency} amount: ${JSON.stringify(value)}`)
+	if ((match[2]?.length ?? 0) > minor_digits(currency)) {
+		throw new RangeError(`${JSON.stringify(value)} has more decimal places than ${currency} allows`)
+	}
+
+	const amount = Number(raw)
+	return {
+		plugin: "uiloco-currency",
+		currency,
+		amount,
+		formatted: format_currency(amount, currency),
+	}
+}