lightnet 3.12.2 → 4.0.1

package/src/content/content-schema.ts

@@ -5,6 +5,22 @@ import { defineCollection, reference } from "astro:content"
 
 import { imageSchema } from "./astro-image"
 
+/**
+ * Translations by BCP-47 tag
+ * Must contain at least one localized value.
+ *
+ * @example
+ * {
+ *    de: "Hallo",
+ *    en: "Hello"
+ * }
+ */
+export const inlineTranslationSchema = z
+  .record(z.string(), z.string())
+  .refine((value) => Object.keys(value).length > 0, {
+    message: "Inline translations must contain at least one entry",
+  })
+
 /**
  * Category Schema
  */
@@ -12,12 +28,9 @@ export const categorySchema = z.object({
   /**
    * Name of the category.
    *
-   * This can either be a translation key or a string that will be displayed as is.
-   * LightNet will try to use it as translation key first if no translation is found it will use the string as is.
-   *
-   * @example "category.biography"
+   * Label translated for the default locale. Other configured site locales are optional.
    */
-  label: z.string(),
+  label: inlineTranslationSchema,
 
   /* Relative path to the thumbnail image of this category.
    *
@@ -37,10 +50,16 @@ export const mediaCollectionSchema = z.object({
   /**
    * Name of the collection.
    *
-   * This can either be a translation key or a string that will be displayed as is.
-   * LightNet will try to use it as translation key first if no translation is found it will use the string as is.
+   * Label translated for the default locale. Other configured site locales are optional.
+   */
+  label: inlineTranslationSchema,
+  /**
+   * Ordered list of media items included in this collection.
+   * The array order defines how items are shown when querying by collection.
+   *
+   * @example ["my-book--en", "my-video--en"]
    */
-  label: z.string(),
+  mediaItems: z.array(reference("media")),
 })
 
 /**
@@ -48,15 +67,16 @@ export const mediaCollectionSchema = z.object({
  */
 export const mediaItemSchema = z.object({
   /**
-   * Identifier of this media item. If other media items
-   * share the same commonId they will show up as translations.
+   * Optional identifier used to link translated variants of a media item.
+   * If other media items share the same commonId they will show up as translations.
+   * If omitted, the media item is treated as standalone and has no translations.
    * The common id will show up in the media item's url combined with it's language.
    *
    * We suggest you use the english name of the media item, all lower case, words separated with hyphens.
    *
    * @example "a-book-about-love"
    */
-  commonId: z.string(),
+  commonId: z.string().optional(),
   /**
    * Title of this media item.
    * This is expected to be in the language that is defined by the 'language' property.
@@ -89,7 +109,7 @@ export const mediaItemSchema = z.object({
    *
    * @example 2024-09-10
    */
-  dateCreated: z.string().date(),
+  dateCreated: z.iso.date(),
   /**
    * List of categories of this media item.
    *
@@ -97,31 +117,11 @@ export const mediaItemSchema = z.object({
    */
   categories: z.array(reference("categories")).nullish(),
   /**
-   * List of media collections this media item is included.
-   * Collections can be used to group media items into series, playlists...
-   *
-   * @example [{collection:"my-series"}]
-   */
-  collections: z
-    .array(
-      z.object({
-        /**
-         * Id of the collection.
-         */
-        collection: reference("media-collections"),
-        /**
-         * Position of the item inside the collection.
-         */
-        index: z.number().optional(),
-      }),
-    )
-    .nullish(),
-  /**
-   * BCP-47 name of the language this media item is in.
+   * BCP-47 language code of this media item.
    *
    * @example "en"
    */
-  language: z.string(),
+  language: z.string().nonempty(),
   /**
    * Relative path to the image of this media item. Eg. a book cover or video thumbnail.
    *
@@ -139,6 +139,15 @@ export const mediaItemSchema = z.object({
   content: z
     .array(
       z.object({
+        /**
+         * Storage kind for this content item.
+         *
+         * - `"upload"`: a file managed by this LightNet site (typically a relative path like `/files/...`)
+         * - `"link"`: an external URL (typically `https://...`)
+         *
+         * @example "upload"
+         */
+        type: z.enum(["upload", "link"]),
         /**
          * Urls might be:
          * - links to youtube videos
@@ -153,10 +162,11 @@ export const mediaItemSchema = z.object({
          */
         url: z.string(),
         /**
-         * The name of the content. If this is not set. The file name
-         * from URL will be used. This can either be a fixed string or a translation key.
+         * The name of the content translated for the default locale.
+         * Other configured site locales are optional.
+         * If this is not set, the file name from URL will be used.
          */
-        label: z.string().optional(),
+        label: inlineTranslationSchema.optional(),
       }),
     )
     .min(1),
@@ -183,111 +193,81 @@ export const createCategorySchema = ({ image }: SchemaContext) =>
 /**
  * Media Type Schema
  */
-export const mediaTypeSchema = z
-  .object({
-    /**
-     * Name of this media type that will be shown on the pages.
-     *
-     * This can either be a fixed string or a translation key.
-     *
-     * @example "media-type.book"
-     */
-    label: z.string(),
-    /**
-     * Defines how the cover image for a media item of this type is rendered.
-     *
-     * Options:
-     * - `"default"` — Renders the media item image with no modifications.
-     * - `"book"` — Adds a book fold effect and sharper edges, styled like a book cover.
-     * - `"video"` — Constrains the image to a 16:9 aspect ratio with a black background.
-     *
-     * @default "default"
-     */
-    coverImageStyle: z.enum(["default", "book", "video"]).default("default"),
-    /**
-     * What media item details page to use for media items with this type.
-     *
-     */
-    detailsPage: z
-      .discriminatedUnion("layout", [
-        z.object({
-          /**
-           * Details page for all media types.
-           */
-          layout: z.literal("default"),
-          /**
-           * Label for the open action button. Use this if you want to change the text
-           * of the "Open" button to be more matching to your media item.
-           * For example you could change the text to be "Read" for a book media type.
-           *
-           * The label is a translation key.
-           *
-           * @example "ln.details.open"
-           */
-          openActionLabel: z.string().optional(),
-          /**
-           * (Deprecated) Specifies the style of the cover image.
-           *
-           * Use `coverImageStyle` instead. This option will be removed in a future major release.
-           *
-           * Supported values:
-           * - `"default"` — unmodified media item image
-           * - `"book"` — styled as a book cover (book fold, sharper edges)
-           *
-           * @example "book"
-           * @deprecated Use `coverImageStyle` instead
-           */
-          coverStyle: z.enum(["default", "book"]).default("default"),
-        }),
-        z.object({
-          /**
-           * Custom details page.
-           */
-          layout: z.literal("custom"),
-          /**
-           * This references a custom component name to be used for the
-           * details page. The custom component has be located at src/details-pages/
-           *
-           * @example "MyArticleDetails.astro"
-           */
-          customComponent: z.string(),
-        }),
-        z.object({
-          /**
-           * Detail page for videos.
-           */
-          layout: z.literal("video"),
-        }),
-        z.object({
-          /**
-           * Detail page for audio files.
-           *
-           * This only supports mp3 files.
-           */
-          layout: z.literal("audio"),
-        }),
-      ])
-      .optional(),
-    /**
-     * Pick the media type's icon from https://pictogrammers.com/library/mdi/
-     * Prefix it's name with "mdi--"
-     *
-     * @example "mdi--ab-testing"
-     */
-    icon: z.string(),
-  })
-  .transform((mediaType) => {
-    // migrate old cover images style to new property
-    const hasDeprecatedBookCover =
-      mediaType.detailsPage?.layout === "default" &&
-      mediaType.detailsPage.coverStyle === "book"
-    return {
-      ...mediaType,
-      coverImageStyle: hasDeprecatedBookCover
-        ? "book"
-        : mediaType.coverImageStyle,
-    }
-  })
+export const mediaTypeSchema = z.object({
+  /**
+   * Name of this media type that will be shown on the pages.
+   *
+   * Label translated for the default locale. Other configured site locales are optional.
+   */
+  label: inlineTranslationSchema,
+  /**
+   * Defines how the cover image for a media item of this type is rendered.
+   *
+   * Options:
+   * - `"default"` — Renders the media item image with no modifications.
+   * - `"book"` — Adds a book fold effect and sharper edges, styled like a book cover.
+   * - `"video"` — Constrains the image to a 16:9 aspect ratio with a black background.
+   *
+   * @default "default"
+   */
+  coverImageStyle: z.enum(["default", "book", "video"]).default("default"),
+  /**
+   * What media item details page to use for media items with this type.
+   *
+   */
+  detailsPage: z
+    .discriminatedUnion("layout", [
+      z.object({
+        /**
+         * Details page for all media types.
+         */
+        layout: z.literal("default"),
+        /**
+         * Label for the open action button. Use this if you want to change the text
+         * of the "Open" button to be more matching to your media item.
+         * For example you could change the text to be "Read" for a book media type.
+         *
+         * Label translated for the default locale. Other configured site locales are optional.
+         */
+        openActionLabel: inlineTranslationSchema.optional(),
+      }),
+      z.object({
+        /**
+         * Custom details page.
+         */
+        layout: z.literal("custom"),
+        /**
+         * This references a custom component name to be used for the
+         * details page. The custom component has be located at src/details-pages/
+         *
+         * @example "MyArticleDetails.astro"
+         */
+        customComponent: z.string(),
+      }),
+      z.object({
+        /**
+         * Detail page for videos.
+         */
+        layout: z.literal("video"),
+      }),
+      z.object({
+        /**
+         * Detail page for audio files.
+         *
+         * This only supports mp3 files.
+         */
+        layout: z.literal("audio"),
+      }),
+    ])
+    .optional(),
+  /**
+   * Pick the media type's icon from https://lucide.dev/icons/
+   * Prefix it's name with "lucide--"
+   *
+   * @example "lucide--book-open"
+   */
+  icon: z.string(),
+})
 
 export const LIGHTNET_COLLECTIONS = {
   categories: defineCollection({
@@ -333,3 +313,10 @@ export const categoryEntrySchema = z.object({
   id: z.string(),
   data: categorySchema,
 })
+
+export const mediaCollectionEntrySchema = z.object({
+  id: z.string(),
+  data: mediaCollectionSchema,
+})
+
+export type MediaCollectionEntry = z.infer<typeof mediaCollectionEntrySchema>

package/src/content/get-categories.ts

@@ -1,43 +1,58 @@
 import { AstroError } from "astro/errors"
 import { getCollection } from "astro:content"
 
-import { type TranslateFn } from "../i18n/translate"
+import type { TranslateMapFn } from "../i18n/translate-map"
+import { lazy } from "../utils/lazy"
 import { verifySchemaAsync } from "../utils/verify-schema"
 import { categoryEntrySchema } from "./content-schema"
 import { getMediaItems } from "./get-media-items"
 
-const categoriesById = Object.fromEntries(
-  (await loadCategories()).map(({ id, data }) => [id, data]),
+const categoriesById = lazy(async () =>
+  Object.fromEntries(
+    (await loadCategories()).map(({ id, data }) => [id, data]),
+  ),
 )
 
-const contentCategories = Object.fromEntries(
-  (await getMediaItems())
-    .flatMap((item) => item.data.categories ?? [])
-    .map((c) => {
-      const category = categoriesById[c.id]
-      if (!category) {
-        throw new AstroError(
-          "Missing Category",
-          `A media item references a non-existent category: "${c.id}".\n` +
-            `To fix this, create a category file at:\n` +
-            `src/content/categories/${c.id}.json`,
-        )
-      }
-      return [c.id, category]
-    }),
-)
+const contentCategories = lazy(async () => {
+  const categories = await categoriesById.get()
+  return Object.fromEntries(
+    (await getMediaItems())
+      .flatMap((item) => item.data.categories ?? [])
+      .map((c) => {
+        const category = categories[c.id]
+        if (!category) {
+          throw new AstroError(
+            "Missing Category",
+            `A media item references a non-existent category: "${c.id}".\n` +
+              `To fix this, create a category file at:\n` +
+              `src/content/categories/${c.id}.json`,
+          )
+        }
+        return [c.id, category]
+      }),
+  )
+})
 
 /**
  * Get categories that are referenced from media items.
  * Adds the translated name of the category and sorts by this name.
  *
  * @param currentLocale current locale
- * @param t translate function
  * @returns categories sorted by labelText
  */
-export async function getUsedCategories(currentLocale: string, t: TranslateFn) {
-  return [...Object.entries(contentCategories)]
-    .map(([id, data]) => ({ id, ...data, labelText: t(data.label) }))
+export async function getUsedCategories(
+  currentLocale: string,
+  tMap: TranslateMapFn,
+) {
+  const categories = await contentCategories.get()
+  return [...Object.entries(categories)]
+    .map(([id, data]) => ({
+      id,
+      ...data,
+      labelText: tMap(data.label, {
+        path: ["categories", id, "label"],
+      }),
+    }))
     .sort((a, b) => a.labelText.localeCompare(b.labelText, currentLocale))
 }
 
@@ -47,17 +62,26 @@ export async function getUsedCategories(currentLocale: string, t: TranslateFn) {
  * by media items use `getUsedCategories`.
  *
  * @param currentLocale current locale
- * @param t translate function
  * @returns categories sorted by labelText
  */
-export async function getCategories(currentLocale: string, t: TranslateFn) {
-  return [...Object.entries(categoriesById)]
-    .map(([id, data]) => ({ id, ...data, labelText: t(data.label) }))
+export async function getCategories(
+  currentLocale: string,
+  tMap: TranslateMapFn,
+) {
+  const categories = await categoriesById.get()
+  return [...Object.entries(categories)]
+    .map(([id, data]) => ({
+      id,
+      ...data,
+      labelText: tMap(data.label, {
+        path: ["categories", id, "label"],
+      }),
+    }))
     .sort((a, b) => a.labelText.localeCompare(b.labelText, currentLocale))
 }
 
 export async function getCategory(id: string) {
-  const category = categoriesById[id]
+  const category = (await categoriesById.get())[id]
   if (!category) {
     throw new AstroError(
       `Missing category "${id}"`,

package/src/content/get-languages.ts

@@ -1,14 +1,35 @@
 import { resolveLanguage } from "../i18n/resolve-language"
+import type { TranslateMapFn } from "../i18n/translate-map"
+import { lazy } from "../utils/lazy"
 import { getMediaItems } from "./get-media-items"
 
+type ResolvedLanguage = Awaited<ReturnType<typeof resolveLanguage>>
+
 /**
  * Array of distinct content languages.
  */
-export const contentLanguages = Object.values(
-  Object.fromEntries(
-    (await getMediaItems()).map(({ data: { language } }) => [
-      language,
-      resolveLanguage(language),
-    ]),
-  ),
-)
+const contentLanguages = lazy(async () => {
+  const languagesByCode = Object.fromEntries(
+    await Promise.all(
+      (await getMediaItems()).map(async ({ data: { language } }) => [
+        language,
+        resolveLanguage(language),
+      ]),
+    ),
+  )
+  return Object.values(languagesByCode) as ResolvedLanguage[]
+})
+
+export const getUsedLanguages = async (
+  currentLocale: string,
+  tMap: TranslateMapFn,
+) => {
+  return (await contentLanguages.get())
+    .map((language) => ({
+      ...language,
+      labelText: tMap(language.label, {
+        path: ["languages", language.code, "label"],
+      }),
+    }))
+    .sort((a, b) => a.labelText.localeCompare(b.labelText, currentLocale))
+}

package/src/content/get-media-collections.ts

@@ -0,0 +1,43 @@
+import { getCollection } from "astro:content"
+
+import { lazy } from "../utils/lazy"
+import { verifySchemaAsync } from "../utils/verify-schema"
+import { mediaCollectionEntrySchema } from "./content-schema"
+
+const collectionsByMediaItemIds = lazy(async () =>
+  (await loadMediaCollections())
+    .flatMap((collection) =>
+      collection.data.mediaItems.map(({ id }) => [id, collection.id]),
+    )
+    .reduce(
+      (collected, [mediaId, collectionId]) => {
+        const collectionIds = collected[mediaId] ?? []
+
+        if (!collectionIds.includes(collectionId)) {
+          collected[mediaId] = [...collectionIds, collectionId]
+        }
+
+        return collected
+      },
+      {} as Record<string, string[]>,
+    ),
+)
+
+export const getCollectionsForMediaItem = async (mediaId: string) => {
+  return (await collectionsByMediaItemIds.get())[mediaId] ?? []
+}
+
+async function loadMediaCollections() {
+  const mediaCollections: unknown[] = await getCollection("media-collections")
+  return await Promise.all(mediaCollections.map(parseMediaCollection))
+}
+
+async function parseMediaCollection(item: unknown) {
+  return await verifySchemaAsync(
+    mediaCollectionEntrySchema,
+    item,
+    (id) => `Invalid media-collection: ${id}`,
+    (id) =>
+      `Fix these issues inside "src/content/media-collections/${id}.json":`,
+  )
+}

package/src/content/get-media-types.ts

@@ -1,18 +1,52 @@
-import { getCollection, getEntry } from "astro:content"
+import { AstroError } from "astro/errors"
+import { getCollection } from "astro:content"
 
+import type { TranslateMapFn } from "../i18n/translate-map"
+import { lazy } from "../utils/lazy"
 import { verifySchema } from "../utils/verify-schema"
 import { mediaTypeEntrySchema } from "./content-schema"
+import { getMediaItems } from "./get-media-items"
+
+const typesById = lazy(async () =>
+  Object.fromEntries((await loadTypes()).map((type) => [type.id, type])),
+)
+
+const contentTypes = lazy(
+  async () => new Set((await getMediaItems()).map((item) => item.data.type.id)),
+)
 
 export const getMediaType = async (id: string) => {
-  return verifySchema(
-    mediaTypeEntrySchema,
-    await getEntry("media-types", id),
-    (id) => `Invalid media type: "${id}"`,
-    (id) => `Fix these issues inside "src/content/media-types/${id}.json":`,
-  )
+  const type = (await typesById.get())[id]
+  if (!type) {
+    throw new AstroError(
+      `No media type found for id ${id}`,
+      `Fix this by adding a media type definition at "src/content/media-types/${id}.json"`,
+    )
+  }
+  return type
+}
+
+export const getUsedMediaTypes = async (
+  currentLocale: string,
+  tMap: TranslateMapFn,
+) => {
+  const byId = await typesById.get()
+  return Array.from(await contentTypes.get(), (typeId) => byId[typeId])
+    .map(({ id, data }) => ({
+      id,
+      ...data,
+      labelText: tMap(data.label, {
+        path: ["media-types", id, "label"],
+      }),
+    }))
+    .sort((a, b) => a.labelText.localeCompare(b.labelText, currentLocale))
 }
 
 export const getMediaTypes = async () => {
+  return Object.values(await typesById.get())
+}
+
+async function loadTypes() {
   const mediaTypes: unknown[] = await getCollection("media-types")
   return mediaTypes.map((type: unknown) =>
     verifySchema(