studiocms 0.1.0-beta.24 → 0.1.0-beta.26

package/src/{utils/validImages.ts → virtuals/auth/validImages/index.ts}

@@ -1,16 +1,16 @@
 /// <reference types="astro/client" />
 import type { ImageMetadata } from 'astro';
-import studiocmsBlobsDark from './loginBackgrounds/studiocms-blobs-dark.png';
-import studiocmsBlobsLight from './loginBackgrounds/studiocms-blobs-light.png';
-import studiocmsBlocksDark from './loginBackgrounds/studiocms-blocks-dark.png';
-import studiocmsBlocksLight from './loginBackgrounds/studiocms-blocks-light.png';
-import studiocmsCurvesDark from './loginBackgrounds/studiocms-curves-dark.png';
-import studiocmsCurvesLight from './loginBackgrounds/studiocms-curves-light.png';
+import studiocmsBlobsDark from './studiocms-blobs-dark.webp';
+import studiocmsBlobsLight from './studiocms-blobs-light.webp';
+import studiocmsBlocksDark from './studiocms-blocks-dark.webp';
+import studiocmsBlocksLight from './studiocms-blocks-light.webp';
+import studiocmsCurvesDark from './studiocms-curves-dark.webp';
+import studiocmsCurvesLight from './studiocms-curves-light.webp';
 
 interface ValidImage {
 	readonly name: string;
 	readonly label: string;
-	readonly format: 'png' | 'web';
+	readonly format: 'local' | 'web';
 	readonly light: ImageMetadata | null;
 	readonly dark: ImageMetadata | null;
 }
@@ -22,21 +22,21 @@ const validImages: ValidImage[] = [
 	{
 		name: 'studiocms-blobs',
 		label: 'Blobs',
-		format: 'png',
+		format: 'local',
 		light: studiocmsBlobsLight,
 		dark: studiocmsBlobsDark,
 	},
 	{
 		name: 'studiocms-blocks',
 		label: 'Blocks',
-		format: 'png',
+		format: 'local',
 		light: studiocmsBlocksLight,
 		dark: studiocmsBlocksDark,
 	},
 	{
 		name: 'studiocms-curves',
 		label: 'Curves',
-		format: 'png',
+		format: 'local',
 		light: studiocmsCurvesLight,
 		dark: studiocmsCurvesDark,
 	},

package/src/{lib → virtuals}/auth/verify-email.ts

@@ -4,9 +4,8 @@ import { Mailer } from 'studiocms:mailer';
 import getTemplate from 'studiocms:mailer/templates';
 import { SDKCoreJs as sdk } from 'studiocms:sdk';
 import type { CombinedUserData } from 'studiocms:sdk/types';
-import { Data, Effect } from 'effect';
 import { CMSNotificationSettingsId } from '../../consts.js';
-import { genLogger, pipeLogger } from '../effects/logger.js';
+import { Data, Effect, genLogger, pipeLogger } from '../../effect.js';
 import type { UserSessionData } from './types.js';
 
 export class VerifyEmailError extends Data.TaggedError('VerifyEmailError')<{ message: string }> {}
@@ -35,16 +34,16 @@ export class VerifyEmailError extends Data.TaggedError('VerifyEmailError')<{ mes
  * - `generateUrl`: Generates a URL with the given base, path, and query parameters.
  */
 export class VerifyEmail extends Effect.Service<VerifyEmail>()(
-	'studiocms/lib/auth/verify-email/VerifyEmail',
+	'studiocms/virtuals/auth/verify-email/VerifyEmail',
 	{
-		effect: genLogger('studiocms/lib/auth/verify-email/VerifyEmail.effect')(function* () {
+		effect: genLogger('studiocms/virtuals/auth/verify-email/VerifyEmail.effect')(function* () {
 			const MailService = yield* Mailer;
 
 			/**
 			 * @private
 			 */
 			const getMailerStatus = () =>
-				pipeLogger('studiocms/lib/auth/verify-email/VerifyEmail.getMailerStatus')(
+				pipeLogger('studiocms/virtuals/auth/verify-email/VerifyEmail.getMailerStatus')(
 					MailService.isEnabled
 				);
 
@@ -55,7 +54,7 @@ export class VerifyEmail extends Effect.Service<VerifyEmail>()(
 			 * @returns The notification settings.
 			 */
 			const getSettings = () =>
-				genLogger('studiocms/lib/auth/verify-email/VerifyEmail.getSettings')(function* () {
+				genLogger('studiocms/virtuals/auth/verify-email/VerifyEmail.getSettings')(function* () {
 					const settings = yield* sdk.GET.databaseTable.notificationSettings();
 
 					if (!settings) {
@@ -80,7 +79,7 @@ export class VerifyEmail extends Effect.Service<VerifyEmail>()(
 			 *
 			 */
 			const isEmailVerificationEnabled = () =>
-				genLogger('studiocms/lib/auth/verify-email/VerifyEmail.isEmailVerificationEnabled')(
+				genLogger('studiocms/virtuals/auth/verify-email/VerifyEmail.isEmailVerificationEnabled')(
 					function* () {
 						const mailer = yield* getMailerStatus();
 						const settings = yield* getSettings();
@@ -96,7 +95,7 @@ export class VerifyEmail extends Effect.Service<VerifyEmail>()(
 			 * @returns A promise that resolves to the email verification request.
 			 */
 			const getEmailVerificationRequest = (id: string) =>
-				pipeLogger('studiocms/lib/auth/verify-email/VerifyEmail.getEmailVerificationRequest')(
+				pipeLogger('studiocms/virtuals/auth/verify-email/VerifyEmail.getEmailVerificationRequest')(
 					sdk.AUTH.verifyEmail.get(id)
 				);
 
@@ -107,9 +106,9 @@ export class VerifyEmail extends Effect.Service<VerifyEmail>()(
 			 * @returns A promise that resolves when the email verification request is successfully deleted.
 			 */
 			const deleteEmailVerificationRequest = (id: string) =>
-				pipeLogger('studiocms/lib/auth/verify-email/VerifyEmail.deleteEmailVerificationRequest')(
-					sdk.AUTH.verifyEmail.delete(id)
-				);
+				pipeLogger(
+					'studiocms/virtuals/auth/verify-email/VerifyEmail.deleteEmailVerificationRequest'
+				)(sdk.AUTH.verifyEmail.delete(id));
 
 			/**
 			 * Creates an email verification request for a given user.
@@ -121,18 +120,18 @@ export class VerifyEmail extends Effect.Service<VerifyEmail>()(
 			 * @returns A promise that resolves to the result of the email verification request creation.
 			 */
 			const createEmailVerificationRequest = (userId: string) =>
-				genLogger('studiocms/lib/auth/verify-email/VerifyEmail.createEmailVerificationRequest')(
-					function* () {
-						yield* deleteEmailVerificationRequest(userId);
-						return yield* sdk.AUTH.verifyEmail.create(userId);
-					}
-				);
+				genLogger(
+					'studiocms/virtuals/auth/verify-email/VerifyEmail.createEmailVerificationRequest'
+				)(function* () {
+					yield* deleteEmailVerificationRequest(userId);
+					return yield* sdk.AUTH.verifyEmail.create(userId);
+				});
 
 			/**
 			 * @private
 			 */
 			const generateUrl = (base: string, path: string, params?: Record<string, string>) =>
-				pipeLogger('studiocms/lib/auth/verify-email/VerifyEmail.generateUrl')(
+				pipeLogger('studiocms/virtuals/auth/verify-email/VerifyEmail.generateUrl')(
 					Effect.try({
 						try: () => {
 							const url = new URL(path, base);
@@ -156,7 +155,7 @@ export class VerifyEmail extends Effect.Service<VerifyEmail>()(
 			 * @throws Will throw an error if the user is not found, if the verification token creation fails, or if the user does not have an email.
 			 */
 			const sendVerificationEmail = (userId: string, isOAuth = false) =>
-				genLogger('studiocms/lib/auth/verify-email/VerifyEmail.sendVerificationEmail')(
+				genLogger('studiocms/virtuals/auth/verify-email/VerifyEmail.sendVerificationEmail')(
 					function* () {
 						const mailer = yield* getMailerStatus();
 						const settings = yield* getSettings();
@@ -223,8 +222,8 @@ export class VerifyEmail extends Effect.Service<VerifyEmail>()(
 			 *    - 'editor': Returns the user's email verification status if editor verification is required, otherwise returns true.
 			 *    - Default: Returns the user's email verification status.
 			 */
-			const isEmailVerified = (user: CombinedUserData | UserSessionData | undefined) =>
-				genLogger('studiocms/lib/auth/verify-email/VerifyEmail.isEmailVerified')(function* () {
+			const isEmailVerified = (user: CombinedUserData | UserSessionData | undefined | null) =>
+				genLogger('studiocms/virtuals/auth/verify-email/VerifyEmail.isEmailVerified')(function* () {
 					if (!user) return false;
 
 					const mailer = yield* getMailerStatus();

package/src/virtuals/components/Generator.astro

@@ -0,0 +1,5 @@
+---
+---
+<meta name="generator" content={Astro.generator} />
+<meta name="generator" content={Astro.locals.StudioCMS.SCMSGenerator} />
+<meta name="generator" content={Astro.locals.StudioCMS.SCMSUiGenerator} />

package/{dist → src/virtuals}/components/Renderer.astro

@@ -1,7 +1,7 @@
 ---
 import { pluginRenderers } from 'studiocms:plugins/renderers';
 import * as renderers from 'virtual:studiocms/plugins/renderers';
-import type { PluginPageTypeRendererProps } from '../types.js';
+import type { PluginPageTypeRendererProps } from '../../types.js';
 
 interface Props extends PluginPageTypeRendererProps {}
 

package/{dist/lib → src/virtuals}/i18n/LanguageSelector.astro

@@ -1,5 +1,5 @@
 ---
-import { languageSelectorOptions } from './index.js';
+import { languageSelectorOptions } from './config.js';
 
 // TODO: Update the language selector's styles to match StudioCMS's new design
 ---

package/src/virtuals/i18n/client.ts

@@ -0,0 +1,232 @@
+/**
+ * This module handles internationalization (i18n) for the StudioCMS application on the client side.
+ *
+ * It provides utilities for loading and managing translation files, as well as functions for
+ * retrieving translated strings based on the current language context.
+ */
+
+import {
+	browser,
+	createI18n,
+	formatter,
+	localeFrom,
+	type Messages,
+	type Translations,
+} from '@nanostores/i18n';
+import { persistentAtom } from '@nanostores/persistent';
+import {
+	baseServerTranslations,
+	clientUiTranslations,
+	defaultLang,
+	type UiTranslationKey,
+	uiTranslationsAvailable,
+} from './config.js';
+
+export { defaultLang, type UiTranslationKey, uiTranslationsAvailable };
+
+/**
+ * The base translation object containing all translations for the default language.
+ */
+export const baseTranslation = baseServerTranslations.translations;
+
+/**
+ * A mapping of UI translation keys to their localized strings.
+ */
+const localeMap = clientUiTranslations;
+
+/**
+ * A persistent atom representing the user's locale settings.
+ */
+export const $localeSettings = persistentAtom<UiTranslationKey | undefined>(
+	'studiocms-i18n-locale',
+	defaultLang
+);
+
+/**
+ * A locale store derived from the user's locale settings and browser detection.
+ */
+export const $locale = localeFrom(
+	$localeSettings, // User’s locale from localStorage
+	browser({
+		// or browser’s locale auto-detect
+		available: uiTranslationsAvailable,
+		fallback: defaultLang,
+	})
+);
+
+/**
+ * A formatter function for the current locale.
+ */
+export const format = formatter($locale);
+
+/**
+ * An i18n (internationalization) utility instance for client-side usage.
+ *
+ * @remarks
+ * This instance is created using the `createI18n` function, initialized with the current locale and a base locale.
+ * It provides a `get` method to asynchronously retrieve translations for a given UI translation key from the `localeMap`.
+ *
+ * @example
+ * ```typescript
+ * const translation = await $i18n.get('welcome_message');
+ * ```
+ *
+ * @see createI18n
+ *
+ * @param $locale - The current locale store or value.
+ * @param defaultLang - The default language to use as a base locale.
+ * @param localeMap - An object mapping translation keys to their localized strings.
+ */
+export const $i18n = createI18n($locale, {
+	baseLocale: defaultLang,
+	get: async (code: UiTranslationKey) => {
+		return localeMap[code] ?? localeMap[defaultLang];
+	},
+});
+
+/**
+ * Updates the document's title, meta description, and language attribute based on the provided component and language.
+ *
+ * @param comp - An object containing the `title` and `description` properties to update the document's title and meta description.
+ * @param lang - The language code to set as the value of the document's `lang` attribute.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: this is a valid use case for explicit any
+export const documentUpdater = (comp: any, lang: string) => {
+	document.title = comp.title;
+	document.querySelector('meta[name="description"]')?.setAttribute('content', comp.description);
+
+	document.documentElement.lang = lang;
+};
+
+type BaseTranslation = typeof baseTranslation;
+type BaseTranslationKeys = keyof BaseTranslation;
+
+/**
+ * Create a custom element that will update its text content
+ * when the translation changes.
+ */
+export const makeTranslation = <Body extends Translations>(
+	currentPage: BaseTranslationKeys,
+	i18n: Messages<Body>
+) => {
+	const currentTranslations = currentPage;
+	type CurrentTranslations = typeof currentTranslations;
+
+	return class Translation extends HTMLElement {
+		connectedCallback() {
+			const key = this.getAttribute('key') as keyof BaseTranslation[CurrentTranslations];
+			if (key) {
+				i18n.subscribe((comp) => {
+					this.innerText = comp[key] as string;
+				});
+			}
+		}
+	};
+};
+
+/**
+ * Regular expression to match required field indicators in labels.
+ */
+const requiredLabelRegex = /.*?<span class="req-star.*?>\*<\/span>/;
+
+/**
+ * Updates the label text for a given form element with a translated string.
+ *
+ * Searches for a `<label>` element associated with the specified element ID (`el`)
+ * and updates its child element with the class `.label` to display the provided translation.
+ * If the label's inner HTML matches the `requiredLabelRegex`, it appends a required star indicator.
+ *
+ * @param el - The ID of the form element whose label should be updated.
+ * @param translation - The translated string to set as the label's text.
+ */
+export const updateElmLabel = (el: string, translation: string) => {
+	const label = document
+		.querySelector<HTMLLabelElement>(`label[for="${el}"]`)
+		?.querySelector('.label') as HTMLSpanElement;
+
+	if (requiredLabelRegex.test(label.innerHTML)) {
+		label.innerHTML = `${translation} <span class="req-star">*</span>`;
+		return;
+	}
+	label.textContent = translation;
+};
+
+/**
+ * Updates the placeholder text of an input element with the specified ID.
+ *
+ * @param el - The ID of the input element whose placeholder should be updated.
+ * @param translation - The new placeholder text to set for the input element.
+ *
+ * @remarks
+ * This function queries the DOM for an input element with the given ID and sets its
+ * `placeholder` property to the provided translation string.
+ *
+ * @throws {TypeError} If no element with the specified ID is found, or if the element is not an input.
+ */
+export const updateElmPlaceholder = (el: string, translation: string) => {
+	const input = document.querySelector<HTMLInputElement>(`#${el}`) as HTMLInputElement;
+	input.placeholder = translation;
+};
+
+/**
+ * Updates the label of a select element with a translated string.
+ *
+ * Finds the corresponding `<label>` element for the given select element by its `for` attribute,
+ * and updates its content with the provided translation. If the label contains a required field indicator
+ * (as determined by `requiredLabelRegex`), it preserves the required star (`*`) in the label.
+ *
+ * @param el - The base ID of the select element (without the `-select-btn` suffix).
+ * @param translation - The translated string to set as the label's text.
+ */
+export const updateSelectElmLabel = (el: string, translation: string) => {
+	const label = document.querySelector<HTMLLabelElement>(
+		`label[for="${el}-select-btn"]`
+	) as HTMLLabelElement;
+
+	if (requiredLabelRegex.test(label.innerHTML)) {
+		label.innerHTML = `${translation} <span class="req-star">*</span>`;
+		return;
+	}
+	label.textContent = translation;
+};
+
+/**
+ * Updates the label text for a toggle element with a given translation.
+ *
+ * This function locates the `<label>` element associated with the provided element ID (`el`),
+ * then finds the corresponding `<span>` inside the label with the ID `label-${el}`.
+ * If the span's inner HTML matches the `requiredLabelRegex`, it updates the span's inner HTML
+ * to include the translated text and a required star indicator. Otherwise, it simply updates
+ * the span's text content with the translation.
+ *
+ * @param el - The ID of the element whose label should be updated.
+ * @param translation - The translated text to set as the label.
+ */
+export const updateToggleElmLabel = (el: string, translation: string) => {
+	const label = document.querySelector<HTMLLabelElement>(`label[for="${el}"]`) as HTMLLabelElement;
+
+	const span = label.querySelector(`#label-${el}`) as HTMLSpanElement;
+
+	if (requiredLabelRegex.test(span.innerHTML)) {
+		span.innerHTML = `${translation} <span class="req-star">*</span>`;
+		return;
+	}
+	span.textContent = translation;
+};
+
+/**
+ * Updates the text content of the page header's title element with the provided translation.
+ *
+ * @param translation - The translated string to set as the page title.
+ *
+ * @remarks
+ * This function selects the element with the class `.page-header` and then finds its child
+ * with the class `.page-title`, updating its text content to the given translation.
+ * It assumes that both elements exist in the DOM.
+ */
+export const pageHeaderUpdater = (translation: string) => {
+	const pageHeader = document.querySelector('.page-header') as HTMLElement;
+	const header = pageHeader.querySelector('.page-title') as HTMLElement;
+
+	header.textContent = translation;
+};

package/src/virtuals/i18n/config.ts

@@ -0,0 +1,170 @@
+/**
+ * This module handles the internationalization (i18n) config for the StudioCMS application for both the Client and Server sides.
+ */
+
+import { availableTranslations } from 'studiocms:i18n/virtual';
+
+/**
+ * Dynamically imports the base English translations for server-side internationalization.
+ *
+ * @remarks
+ * This constant loads the default English translation JSON file asynchronously at runtime.
+ * It is intended to be used as the base set of translations for the server.
+ *
+ * - These translations are also converted to a client-friendly format.
+ */
+export const baseServerTranslations = (
+	await import('./translations/en.json', {
+		assert: { type: 'json' },
+	})
+).default;
+
+/**
+ * Represents a translation record for StudioCMS.
+ *
+ * @property displayName - The human-readable name for the translation.
+ * @property translations - The translation data in the form of a ComponentsJSON object.
+ */
+export type StudioCMSTranslationRecord = typeof baseServerTranslations;
+
+/**
+ * Represents a translation entry in JSON format.
+ * Can be either a string (a translated value) or a nested object of translations.
+ * This allows for both flat and hierarchical translation structures.
+ */
+export type TranslationJSON = string | TranslationsJSON;
+
+/**
+ * The UI translations available in the StudioCMS app.
+ */
+export type UiTranslationKey = string;
+
+/**
+ * Represents a collection of translation entries, where each key is a locale or identifier,
+ * and the value is a `TranslationJSON` object containing the translations for that key.
+ *
+ * @remarks
+ * This interface is typically used to store or retrieve multiple sets of translations,
+ * organized by language or context.
+ *
+ * @example
+ * ```typescript
+ * const translations: TranslationsJSON = {
+ *   en: { greeting: "Hello" },
+ *   fr: { greeting: "Bonjour" }
+ * };
+ * ```
+ */
+export interface TranslationsJSON {
+	[key: string]: TranslationJSON;
+}
+
+/**
+ * Represents a mapping of component names to their respective translation objects.
+ *
+ * @remarks
+ * Each key in the object is a component name (as a string), and the value is a `TranslationsJSON`
+ * object containing the translations for that component.
+ *
+ * @example
+ * ```typescript
+ * const components: ComponentsJSON = {
+ *   header: { en: "Header", fr: "En-tête" },
+ *   footer: { en: "Footer", fr: "Pied de page" }
+ * };
+ * ```
+ */
+export type ComponentsJSON = StudioCMSTranslationRecord['translations'];
+
+/**
+ * Represents the server-side UI translations.
+ *
+ * This type maps each `UiTranslationKey` to its corresponding `StudioCMSTranslationRecord`,
+ * allowing for structured access to translation records for different UI elements.
+ *
+ * @see UiTranslationKey
+ * @see StudioCMSTranslationRecord
+ */
+export type ServerUiTranslations = Record<UiTranslationKey, StudioCMSTranslationRecord>;
+
+/**
+ * Represents a mapping of UI translation keys to their corresponding component translation JSON objects.
+ *
+ * @typeParam UiTranslationKey - The set of valid keys for UI translations.
+ * @typeParam ComponentsJSON - The shape of the translation data for each component.
+ */
+export type ClientUiTranslations = Record<UiTranslationKey, ComponentsJSON>;
+
+/**
+ * Represents an option for selecting a language in the UI.
+ *
+ * @property key - The translation key associated with the language option.
+ * @property value - The display value for the language option.
+ */
+export interface LanguageSelectorOption {
+	readonly key: UiTranslationKey;
+	readonly value: string;
+}
+
+/**
+ * An object containing server-side UI translations for supported locales.
+ *
+ * - The `en` property provides the base server translations for English.
+ * - Additional locale translations are spread from `nonBaseTranslations`.
+ *
+ * @remarks
+ * This constant is typed as `ServerUiTranslations` and marked as `const` for immutability.
+ */
+export const serverUiTranslations: ServerUiTranslations = {
+	en: baseServerTranslations,
+	...availableTranslations,
+};
+
+/**
+ * The UI translations available in the StudioCMS app.
+ */
+export const uiTranslationsAvailable = Object.keys(serverUiTranslations) as UiTranslationKey[];
+
+/**
+ * Transforms the `serverUiTranslations` object into a `ClientUiTranslations` object
+ * by extracting only the `translations` property for each UI translation key.
+ *
+ * @remarks
+ * This reduces the server-side translation structure to a client-friendly format,
+ * mapping each `UiTranslationKey` to its corresponding translations object.
+ *
+ * @type {ClientUiTranslations}
+ */
+export const clientUiTranslations: ClientUiTranslations = Object.entries(
+	serverUiTranslations
+).reduce((acc, [key, value]) => {
+	acc[key as UiTranslationKey] = value.translations;
+	return acc;
+}, {} as ClientUiTranslations);
+
+/**
+ * The default language for the StudioCMS app.
+ */
+export const defaultLang: UiTranslationKey = 'en';
+
+/**
+ * Whether to show the default language in the url path.
+ */
+export const showDefaultLang: boolean = false;
+
+/**
+ * Generates an array of language selector options from the available server UI translations.
+ * Each option contains a `key` representing the language code and a `value` representing the display name of the language.
+ *
+ * @remarks
+ * This is typically used to populate language selection dropdowns in the UI.
+ *
+ * @returns An array of objects, each with `key` and `value` properties for language selection.
+ */
+export const languageSelectorOptions: LanguageSelectorOption[] = Object.keys(serverUiTranslations)
+	.map((key) => {
+		const displayName = serverUiTranslations[key]?.displayName;
+		const value = typeof displayName === 'string' && displayName.trim() ? displayName : String(key);
+		return { key: key as UiTranslationKey, value };
+	})
+	.sort((a, b) => a.value.localeCompare(b.value, undefined, { sensitivity: 'base' }));