storyloco 2.3.0 → 2.5.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
@@ -186,8 +216,8 @@ 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.
+needed, and unknown names are rejected. Until a schema has been generated, any name is
+accepted and the content is the SDK's permissive type. An explicit type argument always wins.
 
 Your params are spread last, so any default can be overridden:
 
@@ -289,6 +319,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.0",
+	"version": "2.5.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.d.ts

@@ -1,6 +1,6 @@
 import type { ISbStoriesParams, ISbStoryParams } from "@storyblok/svelte";
 import type { ISbLink, ISbLinksParams } from "storyblok-js-client";
-import { type ContentFor, type Story, type StoryblokClient, type Version } from "./storyblok.svelte.js";
+import { type ContentFor, type ContentTypeParam, 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;
 /**
@@ -39,7 +39,7 @@ export declare function setup(client: StoryblokClient): (() => {
         [index: string]: any;
     }>(slug: string, params?: ISbStoryParams) => Promise<Story<T> | null>;
     stories: {
-        <K extends string>(params: ISbStoriesParams & {
+        <K extends ContentTypeParam>(params: ISbStoriesParams & {
             content_type: K;
         }): Promise<{
             stories: Story<ContentFor<K>>[];
@@ -47,18 +47,22 @@ export declare function setup(client: StoryblokClient): (() => {
         }>;
         <T = import("storyblok-js-client").ISbComponentType<string> & {
             [index: string]: any;
-        }>(params?: ISbStoriesParams): Promise<{
+        }>(params?: Omit<ISbStoriesParams, "content_type"> & {
+            content_type?: ContentTypeParam;
+        }): Promise<{
             stories: Story<T>[];
             total: number;
         }>;
     };
     all: {
-        <K extends string>(params: ISbStoriesParams & {
+        <K extends ContentTypeParam>(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>>>;
+        }>(params?: Omit<ISbStoriesParams, "content_type"> & {
+            content_type?: ContentTypeParam;
+        }): Promise<Array<Story<T>>>;
     };
     /**
      * The link tree as a flat array — Storyblok returns it keyed by uuid, which is

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

@@ -152,11 +152,18 @@ export interface Registry {
 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;
+/** Registered content type names; `never` until a schema has been generated. */
+export type Known = keyof Registry & string;
+/**
+ * What a `content_type` param accepts: any string until a schema registers names, then a
+ * registered name (autocompleted) or a comma-separated list starting with one.
+ */
+export type ContentTypeParam = [Known] extends [never] ? string : Known | `${Known},${string}`;
 /**
  * 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;
+export type ContentFor<K extends string> = [Names<K>] extends [Known] ? 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

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),
+	}
+}