@aircloudhq/web 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Air-Cloud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@aircloudhq/web",
+  "version": "1.0.0",
+  "description": "The Air-Cloud site application package (ADR-222): the Rails Action View helpers, the i18n runtime of the locale bundle (ADR-223), resource pages over the resource projection, and React bindings.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22.22.0"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./helpers/number": "./src/helpers/number.js",
+    "./helpers/date": "./src/helpers/date.js",
+    "./helpers/text": "./src/helpers/text.js",
+    "./helpers/translation": "./src/helpers/translation.js",
+    "./helpers/url": "./src/helpers/url.js",
+    "./helpers/navigation": "./src/helpers/navigation.js",
+    "./helpers/sanitize": "./src/helpers/sanitize.js",
+    "./helpers/tag": "./src/helpers/tag.js",
+    "./helpers/form": "./src/helpers/form.js",
+    "./model": "./src/model.js",
+    "./resource": "./src/resource.js",
+    "./api": "./src/api.js",
+    "./i18n": "./src/i18n/index.js",
+    "./function": "./src/function.js",
+    "./react": "./src/react/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src/"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "react-router": "8.4.0"
+  },
+  "peerDependencies": {
+    "react": ">=19.2.7",
+    "react-dom": ">=19.2.7"
+  },
+  "devDependencies": {
+    "jsdom": "30.1.1",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "vitest": "5.0.2"
+  },
+  "scripts": {
+    "test": "vitest run"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/api.js

@@ -0,0 +1,48 @@
+// The same-origin API client over the platform error envelope
+// {"error":{"code","message","correlation_id","details"}} — the seam #246's typed SDK replaces. Every
+// call sends `Accept-Language: <current locale>` (spec S4 § Locale negotiation: the function runtime
+// negotiates from it), and the release pin cookie rides with it (same origin).
+import { currentI18n } from './i18n/current.js';
+
+export class ApiError extends Error {
+  constructor(status, code, message, details = {}, correlationId = '') {
+    super(message || code);
+    this.name = 'ApiError';
+    this.status = status;
+    this.code = code;
+    this.details = details ?? {};
+    this.correlationId = correlationId ?? '';
+  }
+}
+
+/**
+ * api("GET", "/api/pets") — resolves to the parsed JSON body (null for 204); rejects with an ApiError
+ * carrying the envelope's code, message, details and correlation id.
+ * @param {{locale?: string, fetch?: typeof fetch, headers?: Record<string,string>}} [options]
+ */
+export async function api(method, path, body, options = {}) {
+  const locale = options.locale ?? currentI18n()?.locale;
+  const headers = { accept: 'application/json', ...(options.headers ?? {}) };
+  if (locale) headers['accept-language'] = locale;
+  const init = { method, headers };
+  if (body !== undefined) {
+    init.body = JSON.stringify(body);
+    headers['content-type'] = 'application/json';
+  }
+  const res = await (options.fetch ?? fetch)(path, init);
+  if (res.status === 204) return null;
+  const text = await res.text();
+  let value = null;
+  if (text !== '') {
+    try {
+      value = JSON.parse(text);
+    } catch {
+      if (res.ok) throw new ApiError(res.status, 'invalid_response', 'the response is not JSON');
+    }
+  }
+  if (!res.ok) {
+    const err = (value && value.error) || {};
+    throw new ApiError(res.status, err.code || `http_${res.status}`, err.message, err.details, err.correlation_id);
+  }
+  return value;
+}

package/src/function.js

@@ -0,0 +1,73 @@
+// @aircloudhq/web/function — the i18n binding of a JavaScript function (ADR-223 D3, D7; spec S4
+// § Locale negotiation, functions; § Run time). A function does not carry the locale bundle: the
+// functions host serves the bundle of the release the invocation resolved to through the
+// `aircloud:functions/i18n` capability, and this module turns it into the same `t` / `l` / number /
+// `pluralize` runtime the site uses (./i18n), so a function answers exactly as its site renders.
+//
+//   import { i18nFor } from '@aircloudhq/web/function';
+//   const i18n = await i18nFor(request, { function: 'greet' });
+//   i18n.t('.title'); // functions.greet.title in the negotiated locale
+//
+// Negotiation, in S4's order: (1) the end-user and organisation preference — reserved for #632;
+// (2) the request's Accept-Language, RFC 4647 lookup; (3) for a trigger without a request (an
+// `x-air-trigger: event` delivery), the `locale` key of the event payload; (4) default_locale. The
+// URL's `locale` parameter is a site concern and is never read here.
+//
+// A bundle the host cannot resolve is not defaulted: `locales()` / `bundle()` throw the capability's
+// ComponentError (payload.code `functions.locale_bundle_unresolvable`) and it reaches the function.
+// A key no locale resolves renders humanized and is reported through the capability, which alarms
+// once per key per release.
+import { bundle, keyMissing, locales } from 'aircloud:functions/i18n@1.0.0';
+import { acceptLanguage, createI18n, lookupLocale } from './i18n/index.js';
+
+function canonical(available, tag) {
+  if (typeof tag !== 'string') return undefined;
+  const t = tag.toLowerCase();
+  return available.find((a) => a.toLowerCase() === t);
+}
+
+/**
+ * The locale of a function invocation.
+ * @param {{default_locale: string, available_locales: string[]}} header the bundle header
+ * @param {{acceptLanguage?: string|null, trigger?: string|null, payload?: any}} input
+ */
+export function negotiateFunctionLocale(header, { acceptLanguage: al, trigger, payload } = {}) {
+  const available = header.available_locales;
+  const fromHeader = al ? lookupLocale(acceptLanguage(al), available) : undefined;
+  if (fromHeader) return fromHeader;
+  if (trigger === 'event') {
+    const fromEvent = canonical(available, payload?.data?.locale);
+    if (fromEvent) return fromEvent;
+  }
+  return header.default_locale;
+}
+
+/**
+ * The i18n runtime of one invocation: the negotiated locale and the release's bundle for it.
+ * @param {Request} request the invocation's request (for a trigger, its delivery)
+ * @param {{function?: string}} [options] the function's name, the scope of its lazy keys
+ */
+export async function i18nFor(request, { function: name } = {}) {
+  const header = JSON.parse(locales());
+  const trigger = request.headers.get('x-air-trigger');
+  let payload;
+  if (trigger === 'event') {
+    try {
+      payload = await request.clone().json();
+    } catch {
+      payload = undefined; // a delivery that is not JSON carries no locale
+    }
+  }
+  const locale = negotiateFunctionLocale(header, { acceptLanguage: request.headers.get('accept-language'), trigger, payload });
+  const reported = new Set();
+  return createI18n({
+    bundle: JSON.parse(bundle(locale)),
+    locale,
+    lazy: name ? { function: name } : undefined,
+    reporter: (key) => {
+      if (reported.has(key)) return;
+      reported.add(key);
+      keyMissing(locale, key);
+    },
+  });
+}

package/src/helpers/date.js

@@ -0,0 +1,66 @@
+// ActionView::Helpers::DateHelper — the distance-in-words helpers, over the locale's
+// `datetime.distance_in_words.*` keys (pluralized by count). Instants only: the arithmetic uses
+// epoch milliseconds and UTC calendar fields, never the host's time zone.
+import { requireI18n } from '../i18n/current.js';
+
+const MINUTES_IN_YEAR = 525600;
+const MINUTES_IN_QUARTER_YEAR = 131400;
+const MINUTES_IN_THREE_QUARTERS_YEAR = 394200;
+
+const ms = (t) => (t instanceof Date ? t.getTime() : typeof t === 'number' ? t : Date.parse(t));
+const isLeap = (y) => y % 4 === 0 && (y % 100 !== 0 || y % 400 === 0);
+
+/** distance_of_time_in_words(from_time, from_time + 50.minutes) # => "about 1 hour" */
+export function distanceOfTimeInWords(fromTime, toTime = 0, options = {}) {
+  const i18n = requireI18n(options, 'distanceOfTimeInWords');
+  const scope = options.scope ?? 'datetime.distance_in_words';
+  let from = ms(fromTime);
+  let to = ms(toTime);
+  if (!Number.isFinite(from) || !Number.isFinite(to)) throw new RangeError('distanceOfTimeInWords: not a time');
+  if (from > to) [from, to] = [to, from];
+  const tr = (key, count) => i18n.t(key, { scope, count });
+  const seconds = Math.round((to - from) / 1000);
+  const minutes = Math.round((to - from) / 60000);
+  if (minutes <= 1) {
+    if (!options.includeSeconds && !options.include_seconds) {
+      return minutes === 0 ? tr('less_than_x_minutes', 1) : tr('x_minutes', minutes);
+    }
+    if (seconds <= 4) return tr('less_than_x_seconds', 5);
+    if (seconds <= 9) return tr('less_than_x_seconds', 10);
+    if (seconds <= 19) return tr('less_than_x_seconds', 20);
+    if (seconds <= 39) return tr('half_a_minute');
+    if (seconds <= 59) return tr('less_than_x_minutes', 1);
+    return tr('x_minutes', 1);
+  }
+  if (minutes < 45) return tr('x_minutes', minutes);
+  if (minutes < 90) return tr('about_x_hours', 1);
+  if (minutes < 1440) return tr('about_x_hours', Math.round(minutes / 60));
+  if (minutes < 2520) return tr('x_days', 1);
+  if (minutes < 43200) return tr('x_days', Math.round(minutes / 1440));
+  if (minutes < 86400) return tr('about_x_months', Math.round(minutes / 43200));
+  if (minutes < 525600) return tr('x_months', Math.round(minutes / 43200));
+  const f = new Date(from);
+  const t = new Date(to);
+  let fromYear = f.getUTCFullYear();
+  if (f.getUTCMonth() + 1 >= 3) fromYear += 1;
+  let toYear = t.getUTCFullYear();
+  if (t.getUTCMonth() + 1 < 3) toYear -= 1;
+  let leapYears = 0;
+  for (let y = fromYear; y <= toYear; y += 1) if (isLeap(y)) leapYears += 1;
+  const withOffset = minutes - leapYears * 1440;
+  const remainder = withOffset % MINUTES_IN_YEAR;
+  const years = Math.floor(withOffset / MINUTES_IN_YEAR);
+  if (remainder < MINUTES_IN_QUARTER_YEAR) return tr('about_x_years', years);
+  if (remainder < MINUTES_IN_THREE_QUARTERS_YEAR) return tr('over_x_years', years);
+  return tr('almost_x_years', years + 1);
+}
+
+/** time_ago_in_words(3.minutes.from_now) # => "3 minutes" */
+export function timeAgoInWords(fromTime, options = {}) {
+  return distanceOfTimeInWords(fromTime, options.now ?? Date.now(), options);
+}
+
+/** distance_of_time_in_words_to_now — Rails' alias of time_ago_in_words. */
+export function distanceOfTimeInWordsToNow(fromTime, options = {}) {
+  return timeAgoInWords(fromTime, options);
+}

package/src/helpers/form.js

@@ -0,0 +1,203 @@
+// The framework-neutral form model (FormHelper + ActiveModel::Validations + ActiveModel::Dirty): field
+// state from the resource projection, client-side validation mirroring the Flex field policies (the
+// server stays authoritative), dirty tracking, and the submit state. React binds it through
+// useSyncExternalStore (`FormWith`).
+//
+// Validation messages resolve as ActiveModel::Error#generate_message does:
+//   activemodel.errors.models.<entity>.attributes.<field>.<kind>, activemodel.errors.models.<entity>.<kind>,
+//   activemodel.errors.messages.<kind>, errors.attributes.<field>.<kind>, errors.messages.<kind>
+// and a full message is `errors.format` ("%{attribute} %{message}") over the human attribute name.
+import { i18nFor } from '../i18n/current.js';
+import { humanAttributeName, modelName } from '../model.js';
+
+/** The value a form input shows for a stored value of a Flex type. */
+export function toInput(type, value) {
+  if (value === undefined || value === null) return type === 'boolean' ? false : '';
+  switch (type) {
+    case 'boolean':
+      return Boolean(value);
+    case 'datetime':
+      return new Date(value).toISOString().slice(0, 16);
+    case 'json':
+    case 'vector':
+      return JSON.stringify(value);
+    default:
+      return String(value);
+  }
+}
+
+/** The JSON value of a form input for a Flex type; undefined means "not set". Throws on a malformed json. */
+export function toValue(type, raw) {
+  if (type === 'boolean') return Boolean(raw);
+  if (raw === '' || raw === undefined || raw === null) return undefined;
+  switch (type) {
+    case 'integer':
+      return Number(raw);
+    case 'datetime':
+      return new Date(`${raw}Z`).toISOString(); // the input edits UTC
+    case 'json':
+    case 'vector':
+      return JSON.parse(raw);
+    default:
+      return raw;
+  }
+}
+
+/** The ActiveModel validation kind a raw input violates for its field, or null. */
+export function validationKind(field, raw) {
+  const empty = raw === '' || raw === undefined || raw === null || (field.type === 'boolean' ? false : false);
+  if (empty) return field.required && field.type !== 'boolean' ? 'blank' : null;
+  switch (field.type) {
+    case 'integer':
+      return /^-?\d+$/.test(String(raw).trim()) ? null : 'not_an_integer';
+    case 'decimal':
+      return /^-?\d+(\.\d+)?$/.test(String(raw).trim()) ? null : 'not_a_number';
+    case 'date':
+      return /^\d{4}-\d{2}-\d{2}$/.test(String(raw)) ? null : 'invalid';
+    case 'datetime':
+      return Number.isFinite(Date.parse(`${raw}Z`)) ? null : 'invalid';
+    case 'json':
+    case 'vector':
+      try {
+        JSON.parse(raw);
+        return null;
+      } catch {
+        return 'invalid';
+      }
+    default:
+      return null;
+  }
+}
+
+/** ActiveModel::Error#generate_message for (resource, field, kind). */
+export function errorMessage(resource, field, kind, options = {}) {
+  const i18n = i18nFor(options);
+  if (!i18n) return kind;
+  const e = resource.entity;
+  const keys = [
+    `activemodel.errors.models.${e}.attributes.${field}.${kind}`,
+    `activemodel.errors.models.${e}.${kind}`,
+    `activemodel.errors.messages.${kind}`,
+    `errors.attributes.${field}.${kind}`,
+    `errors.messages.${kind}`,
+  ];
+  const [first, ...rest] = keys;
+  return i18n.t(first, {
+    default: rest.map((key) => ({ key })),
+    model: modelName(resource, { i18n }).human(),
+    attribute: humanAttributeName(resource, field, { i18n }),
+  });
+}
+
+/** ActiveModel::Errors#full_message. */
+export function fullMessage(resource, field, message, options = {}) {
+  const i18n = i18nFor(options);
+  const attribute = humanAttributeName(resource, field, { i18n });
+  if (!i18n) return `${attribute} ${message}`;
+  return i18n.t('errors.format', { default: [{ key: 'activemodel.errors.format' }], attribute, message });
+}
+
+/**
+ * createForm(resource, {record, i18n}) — the form model of one resource: a new record, or the edit of
+ * `record` ({id, data}).
+ */
+export function createForm(resource, options = {}) {
+  const i18n = () => i18nFor(options);
+  const initial = Object.fromEntries(resource.fields.map((f) => [f.name, toInput(f.type, options.record?.data?.[f.name])]));
+  let state = {
+    values: { ...initial },
+    initial: { ...initial },
+    errors: {},
+    base: [],
+    status: 'idle',
+    error: null,
+    touched: {},
+  };
+  const listeners = new Set();
+  const emit = () => listeners.forEach((l) => l());
+  const setState = (patch) => {
+    state = { ...state, ...patch };
+    emit();
+  };
+
+  const model = {
+    resource,
+    id: options.record?.id,
+    fields: resource.fields,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    getState: () => state,
+    set(name, value) {
+      setState({ values: { ...state.values, [name]: value }, touched: { ...state.touched, [name]: true } });
+    },
+    /** Reload the edited record (and make its values the clean baseline). */
+    load(record) {
+      const values = Object.fromEntries(resource.fields.map((f) => [f.name, toInput(f.type, record?.data?.[f.name])]));
+      model.id = record?.id;
+      setState({ values, initial: { ...values }, errors: {}, base: [], touched: {} });
+    },
+    /** The fields whose value differs from the baseline (ActiveModel::Dirty#changed). */
+    changed: () => resource.fields.map((f) => f.name).filter((n) => state.values[n] !== state.initial[n]),
+    dirty: () => model.changed().length > 0,
+    /** {field: [before, after]} (ActiveModel::Dirty#changes). */
+    changes: () => Object.fromEntries(model.changed().map((n) => [n, [state.initial[n], state.values[n]]])),
+    /** Validate every field; returns true when valid. */
+    validate() {
+      const errors = {};
+      for (const f of resource.fields) {
+        const kind = validationKind(f, state.values[f.name]);
+        if (kind) errors[f.name] = [errorMessage(resource, f.name, kind, { i18n: i18n() })];
+      }
+      setState({ errors });
+      return Object.keys(errors).length === 0;
+    },
+    /** The JSON body of the submit: set fields; on an update a cleared field is null. */
+    payload() {
+      const data = {};
+      for (const f of resource.fields) {
+        const v = toValue(f.type, state.values[f.name]);
+        if (v !== undefined) data[f.name] = v;
+        else if (model.id !== undefined) data[f.name] = null;
+      }
+      return data;
+    },
+    /** Map a platform error onto the form: base error, and per-field marks for flex.validation. */
+    applyError(error) {
+      const errors = {};
+      const fields = error?.details?.fields;
+      if (fields && typeof fields === 'object') {
+        for (const name of Object.keys(fields)) {
+          if (resource.fields.some((f) => f.name === name)) errors[name] = [errorMessage(resource, name, 'invalid', { i18n: i18n() })];
+        }
+      }
+      setState({ errors, base: error ? [error] : [], status: 'failed', error });
+    },
+    /** Validate, then run `send(payload, form)`; the submit state follows the promise. */
+    async submit(send) {
+      if (!model.validate()) {
+        setState({ status: 'failed', error: null });
+        return undefined;
+      }
+      setState({ status: 'submitting', error: null, base: [] });
+      try {
+        const result = await send(model.payload(), model);
+        setState({ status: 'succeeded', initial: { ...state.values } });
+        return result;
+      } catch (e) {
+        model.applyError(e);
+        return undefined;
+      }
+    },
+  };
+  return model;
+}
+
+/** Rails form_with's submit label: helpers.submit.create / update with %{model}. */
+export function submitLabel(resource, persisted, options = {}) {
+  const i18n = i18nFor(options);
+  const model = modelName(resource, { i18n }).human();
+  if (!i18n) return model;
+  return i18n.t(persisted ? 'helpers.submit.update' : 'helpers.submit.create', { model });
+}

package/src/helpers/navigation.js

@@ -0,0 +1,70 @@
+// ActionView::Helpers::NavigationHelper at the census commit (link_to, button_to, current_page?,
+// link_to_unless_current, link_to_unless, link_to_if). The tag helpers return markup; every URL goes
+// through urlFor, so the current page's `locale` parameter is carried forward (ADR-223 D7). There is
+// no authenticity token: a product site is a static SPA and its writes go to functions.
+import { escapeHtml } from '../i18n/index.js';
+import { htmlAttributes, urlFor } from './url.js';
+
+const METHOD_VERBS = ['patch', 'put', 'delete'];
+
+/** link_to "Profile", "/profiles/1" # => <a href="/profiles/1">Profile</a> */
+export function linkTo(name, url, htmlOptions = {}) {
+  const { currentUrl, ...html } = htmlOptions;
+  const href = urlFor(url, { currentUrl });
+  return `<a${htmlAttributes({ ...html, href })}>${escapeHtml(name ?? href)}</a>`;
+}
+
+/**
+ * button_to "New", "/articles/new", method: :get
+ * # => <form class="button_to" method="get" action="/articles/new"><button type="submit">New</button></form>
+ */
+export function buttonTo(name, url, htmlOptions = {}) {
+  const { method: m, params, form, formClass, form_class, currentUrl, ...html } = htmlOptions;
+  const method = String(m ?? 'post').toLowerCase();
+  const action = urlFor(url, { currentUrl });
+  const formMethod = method === 'get' ? 'get' : 'post';
+  const formAttrs = { class: form?.class ?? formClass ?? form_class ?? 'button_to', ...(form ?? {}), method: formMethod, action };
+  const methodTag = METHOD_VERBS.includes(method)
+    ? `<input type="hidden" name="_method" value="${method}" autocomplete="off" />`
+    : '';
+  const button = `<button${htmlAttributes({ ...html, type: 'submit' })}>${escapeHtml(name ?? action)}</button>`;
+  const hidden = Object.entries(params ?? {})
+    .map(([k, v]) => `<input type="hidden" name="${escapeHtml(k)}" value="${escapeHtml(v)}" autocomplete="off" />`)
+    .join('');
+  return `<form${htmlAttributes(formAttrs)}>${methodTag}${button}${hidden}</form>`;
+}
+
+const trimSlash = (s) => (s.length > 1 ? s.replace(/\/+$/, '') : s);
+
+/**
+ * current_page?("/shop/checkout") — the URL names the current page: its path (and, when the URL has
+ * a query or `checkParameters` is set, its query) equals the current request's.
+ */
+export function currentPage(url, options = {}) {
+  const here = options.currentUrl
+    ? new URL(String(options.currentUrl), 'http://x')
+    : typeof location !== 'undefined'
+      ? new URL(location.href)
+      : undefined;
+  if (!here) throw new Error('currentPage: no current URL');
+  const target = new URL(urlFor(url, { currentUrl: here.href, carryLocale: false }), here.href);
+  const withQuery = String(typeof url === 'string' ? url : url?.path ?? '').includes('?') || options.checkParameters;
+  const a = decodeURIComponent(trimSlash(target.pathname) + (withQuery ? target.search : ''));
+  const b = decodeURIComponent(trimSlash(here.pathname) + (withQuery ? here.search : ''));
+  return a === b;
+}
+
+/** link_to_unless_current("Home", "/") — the name alone on the current page, else the link. */
+export function linkToUnlessCurrent(name, url, htmlOptions = {}) {
+  return linkToUnless(currentPage(url, { currentUrl: htmlOptions.currentUrl }), name, url, htmlOptions);
+}
+
+/** link_to_unless(condition, "Reply", "/reply") — the name alone when the condition holds. */
+export function linkToUnless(condition, name, url, htmlOptions = {}) {
+  return condition ? escapeHtml(name) : linkTo(name, url, htmlOptions);
+}
+
+/** link_to_if(condition, "Login", "/login") — the link when the condition holds, else the name. */
+export function linkToIf(condition, name, url, htmlOptions = {}) {
+  return linkToUnless(!condition, name, url, htmlOptions);
+}

package/src/helpers/number.js

@@ -0,0 +1,131 @@
+// ActionView::Helpers::NumberHelper (ActiveSupport::NumberHelper) at the census commit, over the
+// locale bundle's `number.*` keys: the same option names (camelCase accepted as well), the same
+// defaults, BigDecimal half-up rounding. Without a bound i18n instance the Rails defaults apply.
+import { i18nFor } from '../i18n/current.js';
+import { NUMBER_DEFAULTS, formatDelimited, formatRounded } from '../i18n/index.js';
+import { abs, parseDecimal } from '../i18n/decimal.js';
+
+const SNAKE = {
+  stripInsignificantZeros: 'strip_insignificant_zeros',
+  negativeFormat: 'negative_format',
+  areaCode: 'area_code',
+  countryCode: 'country_code',
+  delimiterPattern: 'delimiter_pattern',
+};
+
+function snake(options = {}) {
+  const out = {};
+  for (const [k, v] of Object.entries(options)) if (k !== 'i18n') out[SNAKE[k] ?? k] = v;
+  return out;
+}
+
+function optionsFor(namespace, options) {
+  const o = snake(options);
+  const i = i18nFor(options);
+  if (i) return i.numberOptions(namespace, o);
+  return { ...NUMBER_DEFAULTS.format, ...(namespace ? NUMBER_DEFAULTS[namespace] ?? {} : {}), ...o };
+}
+
+function lookup(options, key) {
+  return i18nFor(options)?.lookup(key);
+}
+
+/** number_to_currency(1234567890.50) # => "$1,234,567,890.50" */
+export function numberToCurrency(number, options = {}) {
+  const o = optionsFor('currency', options);
+  const d = parseDecimal(number);
+  const rounded = formatRounded(abs(d), o);
+  const format = d.neg && /[1-9]/.test(rounded) ? o.negative_format : o.format;
+  return format.replace('%n', rounded).replace('%u', o.unit);
+}
+
+/** number_with_delimiter(12345678) # => "12,345,678" */
+export function numberWithDelimiter(number, options = {}) {
+  return formatDelimited(number, optionsFor(null, options));
+}
+
+/** number_with_precision(111.2345) # => "111.235" */
+export function numberWithPrecision(number, options = {}) {
+  return formatRounded(number, optionsFor('precision', options));
+}
+
+/** number_to_percentage(100) # => "100.000%" */
+export function numberToPercentage(number, options = {}) {
+  const o = optionsFor('percentage', options);
+  return o.format.replace('%n', formatRounded(number, o));
+}
+
+const DECIMAL_UNITS = { 0: 'unit', 1: 'ten', 2: 'hundred', 3: 'thousand', 6: 'million', 9: 'billion', 12: 'trillion', 15: 'quadrillion', '-1': 'deci', '-2': 'centi', '-3': 'mili', '-6': 'micro', '-9': 'nano', '-12': 'pico', '-15': 'femto' };
+
+function exponentOf(d) {
+  if (d.int !== '0') return d.int.length - 1;
+  const lead = d.frac.match(/^0*/)[0].length;
+  return lead === d.frac.length ? 0 : -(lead + 1);
+}
+
+/** number_to_human(1234567) # => "1.23 Million" */
+export function numberToHuman(number, options = {}) {
+  const o = optionsFor('human', options);
+  const units = { ...NUMBER_DEFAULTS.human.units, ...(lookup(options, 'number.human.decimal_units.units') ?? {}), ...(typeof o.units === 'object' ? o.units : {}) };
+  const format = o.format && o.format.includes('%u') ? o.format : lookup(options, 'number.human.decimal_units.format') ?? '%n %u';
+  const d = parseDecimal(number);
+  // Round first (Rails rounds, then takes the exponent of the rounded number).
+  const rounded = parseDecimal(formatRounded(d, { ...o, delimiter: '', separator: '.', strip_insignificant_zeros: false }));
+  const exponent = exponentOf(rounded);
+  const available = Object.entries(DECIMAL_UNITS)
+    .filter(([, name]) => units[name] !== undefined)
+    .map(([e]) => Number(e))
+    .sort((a, b) => b - a);
+  const unitExp = available.find((e) => e <= exponent) ?? available[available.length - 1] ?? 0;
+  const scaled = shift(d, -unitExp);
+  const value = formatRounded(scaled, o);
+  const unit = units[DECIMAL_UNITS[unitExp]];
+  const unitText = typeof unit === 'object' ? (Number(value.replace(o.separator, '.')) === 1 ? unit.one : unit.other) : unit;
+  return format.replace('%n', value).replace('%u', unitText ?? '').trim();
+}
+
+function shift(d, places) {
+  const digits = d.int + d.frac;
+  const point = d.int.length + places;
+  const padded = point < 0 ? '0'.repeat(-point) + digits : point > digits.length ? digits + '0'.repeat(point - digits.length) : digits;
+  const p = Math.max(point, 0);
+  return parseDecimal(`${d.neg ? '-' : ''}${padded.slice(0, p) || '0'}.${padded.slice(p)}`);
+}
+
+const STORAGE = ['byte', 'kb', 'mb', 'gb', 'tb', 'pb', 'eb', 'zb'];
+
+/** number_to_human_size(1234567) # => "1.18 MB" */
+export function numberToHumanSize(number, options = {}) {
+  const o = optionsFor('human', options);
+  const units = { ...NUMBER_DEFAULTS.storage_units.units, ...(lookup(options, 'number.human.storage_units.units') ?? {}) };
+  const format = lookup(options, 'number.human.storage_units.format') ?? NUMBER_DEFAULTS.storage_units.format;
+  const n = Number(parseDecimal(number).int + '.' + (parseDecimal(number).frac || '0'));
+  let exponent = 0;
+  while (exponent < STORAGE.length - 1 && n >= 1024 ** (exponent + 1)) exponent += 1;
+  if (exponent === 0) {
+    const unit = units.byte;
+    const count = Math.trunc(n);
+    const unitText = typeof unit === 'object' ? (count === 1 ? unit.one : unit.other) : unit;
+    return format.replace('%n', String(count)).replace('%u', unitText);
+  }
+  const value = formatRounded(String(n / 1024 ** exponent), o);
+  return format.replace('%n', value).replace('%u', units[STORAGE[exponent]]);
+}
+
+/** number_to_phone(5551234) # => "555-1234" */
+export function numberToPhone(number, options = {}) {
+  const o = snake(options);
+  const delimiter = o.delimiter ?? '-';
+  let s = String(number).trim();
+  if (o.area_code) {
+    s = s.replace(o.pattern ?? /(\d{1,3})(\d{3})(\d{4}$)/, `($1) $2${delimiter}$3`);
+  } else {
+    s = s.replace(o.pattern ?? /(\d{0,3})(\d{3})(\d{4})$/, `$1${delimiter}$2${delimiter}$3`);
+    if (delimiter && s.startsWith(delimiter)) s = s.slice(delimiter.length);
+  }
+  let out = '';
+  if (o.country_code !== undefined && o.country_code !== null && o.country_code !== '') out += `+${o.country_code}${delimiter}`;
+  out += s;
+  if (o.extension !== undefined && o.extension !== null && o.extension !== '') out += ` x ${o.extension}`;
+  return out;
+}