@viniaraujo68/plinth 0.3.0 → 0.5.0

package/dist/i18n/i18n.svelte.js

@@ -0,0 +1,94 @@
+import { interpolate, matchLocale, pickPhrase, } from "./translate.js";
+/**
+ * The locale an app is shown in, and the `t()` that reads from it.
+ *
+ * Build one per app, at module level, and import it wherever text is rendered: `locale` is
+ * `$state`, so every `t()` read in a template or a `$derived` re-renders when it changes.
+ *
+ * On the server the instance is shared by every request the process handles and there is no
+ * per-request place to keep a reader's language, so it renders the fallback locale and refuses to
+ * switch — a switch there would leak one visitor's language into the next one's page. The browser
+ * corrects the text during hydration, from the remembered pick or the browser's languages.
+ */
+export class I18n {
+    /** The current locale. Switch it with {@link I18n.setLocale}, which also remembers the pick. */
+    locale = $state();
+    /** Every locale on offer, in the order the dictionaries were declared. */
+    locales;
+    #dictionaries;
+    #tags;
+    #fallback;
+    #storageKey;
+    constructor({ dictionaries, tags, fallback, unmatched, storageKey = null }) {
+        this.#dictionaries = dictionaries;
+        this.#tags = tags;
+        this.#fallback = fallback;
+        this.#storageKey = storageKey;
+        this.locales = Object.keys(dictionaries);
+        this.locale = this.#initial(unmatched ?? fallback);
+        this.#applyLang();
+    }
+    /** The BCP 47 tag of the current locale, for `Intl` formatters and `toLocaleDateString`. */
+    get tag() {
+        return this.#tags[this.locale] ?? this.#tags[this.#fallback];
+    }
+    /**
+     * The text for `key` in the current locale, with `{name}` placeholders filled from `params` and
+     * a plural form picked by `params.count`. A key the current dictionary lacks is read from the
+     * fallback one; a key neither has renders as itself — loud on screen, harmless otherwise.
+     *
+     * An arrow property rather than a method, so `const { t } = i18n` keeps working.
+     */
+    t = (key, params) => {
+        const phrase = this.#dictionaries[this.locale]?.[key] ?? this.#dictionaries[this.#fallback]?.[key];
+        return phrase === undefined ? key : interpolate(pickPhrase(phrase, params), params);
+    };
+    /** Whether any dictionary has `key` — for text that is optional rather than missing. */
+    has = (key) => key in (this.#dictionaries[this.locale] ?? {}) ||
+        key in (this.#dictionaries[this.#fallback] ?? {});
+    /** Switches to `locale` and remembers it. Ignored on the server and for a locale not on offer. */
+    setLocale = (locale) => {
+        if (typeof window === "undefined" || !this.locales.includes(locale))
+            return;
+        this.locale = locale;
+        this.#remember(locale);
+        this.#applyLang();
+    };
+    #initial(unmatched) {
+        if (typeof window === "undefined")
+            return this.#fallback;
+        const saved = this.#remembered();
+        if (saved)
+            return saved;
+        const languages = navigator.languages?.length ? navigator.languages : [navigator.language];
+        return matchLocale(languages.filter(Boolean), this.#tags) ?? unmatched;
+    }
+    #remembered() {
+        if (!this.#storageKey)
+            return null;
+        try {
+            const saved = localStorage.getItem(this.#storageKey);
+            return saved && this.locales.includes(saved) ? saved : null;
+        }
+        catch {
+            // Storage blocked: fall through to the browser's languages.
+            return null;
+        }
+    }
+    #remember(locale) {
+        if (!this.#storageKey)
+            return;
+        try {
+            localStorage.setItem(this.#storageKey, locale);
+        }
+        catch {
+            // Storage blocked, as in some private modes: the pick still holds for this visit.
+        }
+    }
+    #applyLang() {
+        if (typeof document !== "undefined")
+            document.documentElement.lang = this.tag;
+    }
+}
+/** An {@link I18n} for `options` — the one place an app declares its locales. */
+export const createI18n = (options) => new I18n(options);

package/dist/i18n/index.d.ts

@@ -0,0 +1,3 @@
+export { createI18n, I18n, type I18nOptions } from "./i18n.svelte.js";
+export { default as LocaleToggle } from "./LocaleToggle.svelte";
+export { interpolate, matchLocale, pickPhrase, type Dictionary, type Phrase, type TranslationParams, } from "./translate.js";

package/dist/i18n/index.js

@@ -0,0 +1,7 @@
+// The app's own strings in more than one language: the current locale as state, a `t()` that reads
+// it, and the toggle that switches it. The library still ships no translations of its own — its
+// components take every word through props — so this is for the app's text, and those props are
+// where its `t()` calls go. `@viniaraujo68/plinth/i18n`.
+export { createI18n, I18n } from "./i18n.svelte.js";
+export { default as LocaleToggle } from "./LocaleToggle.svelte";
+export { interpolate, matchLocale, pickPhrase, } from "./translate.js";

package/dist/i18n/translate.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A dictionary value: plain text, or a pair picked by the `count` parameter.
+ *
+ * Two forms only, `one` for a count of exactly 1 and `other` for everything else. That is
+ * deliberately not CLDR: `Intl.PluralRules` files 0 under "one" in Portuguese, which would print
+ * "0 dia" where a Brazilian reader expects "0 dias". A language that needs more forms than two is
+ * the point at which a real i18n library earns its weight.
+ */
+export type Phrase = string | {
+    one: string;
+    other: string;
+};
+/** One locale's strings, flat and dot-namespaced: `"nav.login": "Entrar"`. */
+export type Dictionary = Readonly<Record<string, Phrase>>;
+/** What a `{name}` placeholder is filled with. `count` also picks a plural form. */
+export type TranslationParams = Readonly<Record<string, string | number | null | undefined>>;
+/** The form of `phrase` for `params`: the text itself, or the `one`/`other` the count picks. */
+export declare const pickPhrase: (phrase: Phrase, params?: TranslationParams) => string;
+/**
+ * `text` with each `{name}` replaced by `params.name`. A placeholder with no value — absent,
+ * `null` or `undefined` — is left as written, so a missing parameter shows up on screen instead of
+ * printing "undefined" into a sentence.
+ */
+export declare const interpolate: (text: string, params?: TranslationParams) => string;
+/**
+ * Which of `locales` a reader's browser asks for. `languages` is `navigator.languages`, most
+ * preferred first: each is matched against the locale tags exactly, then by language alone, so a
+ * browser in `pt-PT` still lands on a `pt-BR` locale. `null` when none of them matches.
+ */
+export declare const matchLocale: <L extends string>(languages: readonly string[], tags: Readonly<Record<L, string>>) => L | null;

package/dist/i18n/translate.js

@@ -0,0 +1,38 @@
+/** The form of `phrase` for `params`: the text itself, or the `one`/`other` the count picks. */
+export const pickPhrase = (phrase, params) => {
+    if (typeof phrase === "string")
+        return phrase;
+    return params?.count === 1 ? phrase.one : phrase.other;
+};
+/**
+ * `text` with each `{name}` replaced by `params.name`. A placeholder with no value — absent,
+ * `null` or `undefined` — is left as written, so a missing parameter shows up on screen instead of
+ * printing "undefined" into a sentence.
+ */
+export const interpolate = (text, params) => {
+    if (!params)
+        return text;
+    return text.replace(/\{(\w+)\}/g, (placeholder, name) => {
+        const value = params[name];
+        return value === null || value === undefined ? placeholder : String(value);
+    });
+};
+/**
+ * Which of `locales` a reader's browser asks for. `languages` is `navigator.languages`, most
+ * preferred first: each is matched against the locale tags exactly, then by language alone, so a
+ * browser in `pt-PT` still lands on a `pt-BR` locale. `null` when none of them matches.
+ */
+export const matchLocale = (languages, tags) => {
+    const entries = Object.entries(tags);
+    const primary = (tag) => tag.toLowerCase().split("-")[0];
+    for (const language of languages) {
+        const wanted = language.toLowerCase();
+        const exact = entries.find(([, tag]) => tag.toLowerCase() === wanted);
+        if (exact)
+            return exact[0];
+        const loose = entries.find(([, tag]) => primary(tag) === primary(wanted));
+        if (loose)
+            return loose[0];
+    }
+    return null;
+};

package/dist/index.d.ts

@@ -5,6 +5,6 @@
  * no portable way to import its own manifest, and a consumer that only wants to log a version
  * should not have to bundle one. `version.spec.ts` fails when this drifts from the manifest.
  */
-export declare const LIBRARY_VERSION = "0.3.0";
+export declare const LIBRARY_VERSION = "0.5.0";
 export { AsyncAction, type AsyncActionStatus, type AsyncFn } from "./async-action.svelte.js";
 export { reportError, setErrorReporter, type ErrorReporter } from "./error.js";

package/dist/index.js

@@ -5,7 +5,7 @@
  * no portable way to import its own manifest, and a consumer that only wants to log a version
  * should not have to bundle one. `version.spec.ts` fails when this drifts from the manifest.
  */
-export const LIBRARY_VERSION = "0.3.0";
+export const LIBRARY_VERSION = "0.5.0";
 // The root entry carries only what is not tied to one area: the error channel an app installs
 // once, and the async state machine the components are built on. Everything visual is reached
 // through a subpath — `/theme`, `/attachments`, `/components`, `/toast` — so importing a button

package/dist/redirect.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The `?next=` round trip of a sign-in page: where a guard sends a visitor who is not signed in,
+ * and where the sign-in page may send them back to afterwards.
+ *
+ * The value arrives in a URL anyone can write, so it is attacker-controlled. Handed straight to
+ * `goto` or `location`, `?next=//evil.example` would send someone who just typed their password to
+ * another site — an open redirect, the first step of most credential phishing.
+ */
+/**
+ * `value` when it is a path on this site, normalised; `null` for anything else.
+ *
+ * A leading `/` is not enough on its own: `//evil.example` and `/\evil.example` are
+ * protocol-relative to a browser, and the URL parser drops tabs and line breaks before it reads a
+ * URL at all, so `/<tab>/evil.example` turns into one of them on the way in. Rather than chase every
+ * spelling, the candidate is resolved the way the browser would resolve it and kept only if it
+ * stays on the same origin.
+ */
+export declare const safeNext: (value: string | null | undefined) => string | null;
+export interface LoginUrlOptions {
+    /** The sign-in page. Defaults to `/login`. */
+    path?: string;
+    /** The search parameter the return path travels in. Defaults to `next`. */
+    param?: string;
+}
+/**
+ * Where a guard sends a visitor who has to sign in first: the sign-in page, carrying the current
+ * path so it can send them back.
+ *
+ * Only the path travels. The query string is dropped on purpose: it is where share tokens and
+ * one-off codes live, and a sign-in URL gets logged, bookmarked and pasted far more than the page
+ * it came from. Nothing is carried from the site root or from the sign-in page itself, where
+ * "come back here" means nothing.
+ */
+export declare const loginUrl: (current: URL | string, { path, param }?: LoginUrlOptions) => string;
+/**
+ * `base` carrying `next` along — the link between the sign-in and the sign-up pages, so the
+ * return path survives a visitor who picked the wrong one first. `next` is checked again here, so
+ * an unchecked value cannot slip through a link built from it.
+ */
+export declare const withNext: (base: string, next: string | null | undefined, param?: string) => string;

package/dist/redirect.js

@@ -0,0 +1,59 @@
+/**
+ * The `?next=` round trip of a sign-in page: where a guard sends a visitor who is not signed in,
+ * and where the sign-in page may send them back to afterwards.
+ *
+ * The value arrives in a URL anyone can write, so it is attacker-controlled. Handed straight to
+ * `goto` or `location`, `?next=//evil.example` would send someone who just typed their password to
+ * another site — an open redirect, the first step of most credential phishing.
+ */
+/** A base no real link can point at, used only to let the URL parser resolve a candidate path. */
+const PROBE_ORIGIN = "https://plinth.invalid";
+/**
+ * `value` when it is a path on this site, normalised; `null` for anything else.
+ *
+ * A leading `/` is not enough on its own: `//evil.example` and `/\evil.example` are
+ * protocol-relative to a browser, and the URL parser drops tabs and line breaks before it reads a
+ * URL at all, so `/<tab>/evil.example` turns into one of them on the way in. Rather than chase every
+ * spelling, the candidate is resolved the way the browser would resolve it and kept only if it
+ * stays on the same origin.
+ */
+export const safeNext = (value) => {
+    if (typeof value !== "string" || !value.startsWith("/"))
+        return null;
+    let url;
+    try {
+        url = new URL(value, PROBE_ORIGIN);
+    }
+    catch {
+        return null;
+    }
+    if (url.origin !== PROBE_ORIGIN)
+        return null;
+    return `${url.pathname}${url.search}${url.hash}`;
+};
+/**
+ * Where a guard sends a visitor who has to sign in first: the sign-in page, carrying the current
+ * path so it can send them back.
+ *
+ * Only the path travels. The query string is dropped on purpose: it is where share tokens and
+ * one-off codes live, and a sign-in URL gets logged, bookmarked and pasted far more than the page
+ * it came from. Nothing is carried from the site root or from the sign-in page itself, where
+ * "come back here" means nothing.
+ */
+export const loginUrl = (current, { path = "/login", param = "next" } = {}) => {
+    const pathname = typeof current === "string" ? new URL(current, PROBE_ORIGIN).pathname : current.pathname;
+    if (pathname === "/" || pathname === path)
+        return path;
+    return `${path}?${param}=${encodeURIComponent(pathname)}`;
+};
+/**
+ * `base` carrying `next` along — the link between the sign-in and the sign-up pages, so the
+ * return path survives a visitor who picked the wrong one first. `next` is checked again here, so
+ * an unchecked value cannot slip through a link built from it.
+ */
+export const withNext = (base, next, param = "next") => {
+    const safe = safeNext(next);
+    if (!safe)
+        return base;
+    return `${base}${base.includes("?") ? "&" : "?"}${param}=${encodeURIComponent(safe)}`;
+};

package/dist/routing.svelte.d.ts

@@ -161,6 +161,7 @@ export declare class RoutingContext<Id extends string = string> {
  */
 export declare const resolvePathname: (pathname: string) => string;
 export declare const getRoutingContext: () => RoutingContext<string>, setRoutingContext: (context: RoutingContext<string>) => RoutingContext<string>;
+export { loginUrl, safeNext, withNext, type LoginUrlOptions } from "./redirect.js";
 /**
  * A copy of `url` with some search parameters set and others removed — `null` or `undefined`
  * removes. It never edits the URL it was given, which is usually the page store's own and is read

package/dist/routing.svelte.js

@@ -189,6 +189,9 @@ export class RoutingContext {
  */
 export const resolvePathname = (pathname) => resolve(pathname);
 export const [getRoutingContext, setRoutingContext] = createContext();
+// The `?next=` round trip of a sign-in page. Pure functions over strings, kept in their own module
+// so they can be read and tested without a routing context.
+export { loginUrl, safeNext, withNext } from "./redirect.js";
 /**
  * A copy of `url` with some search parameters set and others removed — `null` or `undefined`
  * removes. It never edits the URL it was given, which is usually the page store's own and is read