lightnet 2.15.2

package/src/components/MediaItemList.astro

@@ -0,0 +1,84 @@
+---
+import { Image } from "astro:assets"
+
+import type { MediaItemEntry } from "../content/content-schema-internal"
+import { getMediaTypes } from "../content/get-media-types"
+import { detailsPagePath } from "../utils/paths"
+import Icon from "./Icon"
+
+interface Props {
+  items: (MediaItemEntry & { disabled?: boolean })[]
+}
+
+const { items } = Astro.props
+
+const { t, direction } = Astro.locals.i18n
+
+const mediaTypes = Object.fromEntries(
+  (await getMediaTypes()).map((type) => [
+    type.id,
+    {
+      id: type.id,
+      name: t(type.data.label, { allowFixedStrings: true }),
+      icon: type.data.icon,
+    },
+  ]),
+)
+---
+
+<ol class="divide-y divide-gray-200">
+  {
+    items.map((item) => (
+      <li lang={item.data.language}>
+        <a
+          href={
+            item.disabled
+              ? "javascript:void(0)"
+              : detailsPagePath(Astro.currentLocale, {
+                  id: item.id,
+                })
+          }
+          class="group flex overflow-hidden py-4 transition-colors ease-in-out md:rounded-sm md:py-8 md:hover:bg-gray-100"
+          class:list={
+            item.disabled ? "pointer-events-none cursor-default opacity-50" : ""
+          }
+          tabindex={item.disabled ? -1 : 0}
+        >
+          <div class="flex h-32 w-32 shrink-0 flex-col items-start justify-center">
+            <Image
+              class="max-h-32 w-auto max-w-32 rounded-sm object-contain shadow-md"
+              src={item.data.image}
+              alt=""
+            />
+          </div>
+
+          <div
+            class="ms-5 flex grow flex-col justify-center sm:ms-8"
+            lang={item.data.language}
+          >
+            <p class="mb-1 line-clamp-3 font-bold text-gray-700 md:mb-3">
+              <Icon
+                className={`${mediaTypes[item.data.type.id].icon} me-2 align-bottom text-2xl text-gray-700`}
+                ariaLabel={mediaTypes[item.data.type.id].name}
+              />
+              <span>{item.data.title}</span>
+            </p>
+            <div class="mb-3 flex flex-col flex-wrap items-start gap-2 md:flex-row md:items-center md:gap-3">
+              {!!item.data.authors?.length && (
+                <p class="mb-1 md:mb-0 md:text-base">
+                  {item.data.authors.join(", ")}
+                </p>
+              )}
+            </div>
+          </div>
+
+          <Icon
+            className="mdi--chevron-right hidden sm:block md:group-hover:text-primary my-auto ms-2 me-4 shrink-0 text-2xl text-gray-300"
+            flipIcon={direction === "rtl"}
+            ariaLabel=""
+          />
+        </a>
+      </li>
+    ))
+  }
+</ol>

package/src/components/Section.astro

@@ -0,0 +1,49 @@
+---
+interface Props {
+  /**
+   * Id to set to the section element.
+   * For example this can be used to reference it inside anchors.
+   */
+  id?: string
+  /**
+   * Maximum width of the section container.
+   *
+   * - "full" takes the full available width of the LightNet page. This is not equal to the screen width.
+   *    For example the full width typically is used on the homepage.
+   * - "prose" width ensures text is well readable. This is the width used on the details page.
+   *
+   * @default "full"
+   */
+  maxWidth?: "full" | "prose"
+  /**
+   * Title on top of the section.
+   */
+  title?: string
+  /**
+   * Css classes to set to the section element.
+   */
+  className?: string
+}
+
+const { id, maxWidth = "full", title, className } = Astro.props
+
+const maxWidths = {
+  full: "max-w-screen-xl",
+  prose: "max-w-screen-md",
+}
+---
+
+<section
+  class="mx-auto mt-24 px-4 md:mt-28 md:px-8"
+  class:list={[maxWidths[maxWidth], className]}
+  id={id}
+>
+  {
+    title && (
+      <h2 class="mb-10 text-2xl font-bold text-gray-700 sm:mb-12 sm:text-3xl">
+        {title}
+      </h2>
+    )
+  }
+  <slot />
+</section>

package/src/content/astro-image.ts

@@ -0,0 +1,14 @@
+import { type ImageFunction, z } from "astro:content"
+
+/**
+ * We use this function to make sure decap's relative paths will resolve correctly
+ * with astro content.
+ *
+ * @param image astro content image function
+ * @returns image property
+ */
+export const astroImage = (image: ImageFunction) =>
+  z
+    .string()
+    .transform((path) => (path.startsWith("./") ? path : `./${path}`))
+    .pipe(image())

package/src/content/content-schema-internal.ts

@@ -0,0 +1,52 @@
+/**
+ * We use this internal content schema to make content schema easier to
+ * comprehend for external users.
+ */
+import { z } from "astro/zod"
+
+import {
+  mediaItemSchema as externalMediaItemSchema,
+  mediaTypeSchema,
+} from "./content-schema"
+
+export type MediaItem = z.infer<typeof mediaItemSchema>
+export type MediaItemEntry = {
+  id: string
+  data: MediaItem
+}
+
+/**
+ * Media Item
+ */
+const mediaItemSchema = externalMediaItemSchema.extend({
+  image: z.object({
+    src: z.string(),
+    width: z.number(),
+    height: z.number(),
+    format: z.enum([
+      "png",
+      "jpg",
+      "jpeg",
+      "tiff",
+      "webp",
+      "gif",
+      "svg",
+      "avif",
+    ]),
+  }),
+})
+
+export const mediaItemEntrySchema = z.object({
+  id: z.string(),
+  data: mediaItemSchema,
+})
+
+/**
+ * Media Type
+ */
+export const mediaTypeEntrySchema = z.object({
+  id: z.string(),
+  data: mediaTypeSchema,
+})
+
+export type MediaType = z.infer<typeof mediaTypeSchema>

package/src/content/content-schema.ts

@@ -0,0 +1,263 @@
+import { glob } from "astro/loaders"
+import { z } from "astro/zod"
+import type { SchemaContext } from "astro:content"
+import { defineCollection, reference } from "astro:content"
+
+import { astroImage } from "./astro-image"
+
+/**
+ * Category Schema
+ */
+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: z.string(),
+})
+
+/**
+ * Media Collection Schema
+ */
+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: z.string(),
+})
+
+/**
+ * Media Item Schema
+ */
+export const mediaItemSchema = z.object({
+  /**
+   * Identifier of this media item. If other media items
+   * share the same commonId they will show up as 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(),
+  /**
+   * Title of this media item.
+   * This is expected to be in the language that is defined by the 'language' property.
+   *
+   * @example "A book about love"
+   */
+  title: z.string(),
+  /**
+   * References one media-type by its filename without .json suffix.
+   *
+   * @example "book"
+   */
+  type: reference("media-types"),
+  /**
+   *Describes this media item. You can use markdown syntax to add formatting.
+   * This is expected to be in the language that is defined by the 'language' property.
+   *
+   * @example "This is a book about **love**..."
+   */
+  description: z.string().optional(),
+  /**
+   * List of authors of this media item.
+   *
+   * @example ["George Miller", "Timothy Meier"]
+   */
+  authors: z.array(z.string()).optional(),
+  /**
+   * Date this media item has been created on this lightnet instance.
+   * Format is YYYY-MM-DD
+   *
+   * @example 2024-09-10
+   */
+  dateCreated: z.string().date(),
+  /**
+   * List of categories of this media item.
+   *
+   * @example ["family"]
+   */
+  categories: z.array(reference("categories")).optional(),
+  /**
+   * 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(),
+      }),
+    )
+    .optional(),
+  /**
+   * BCP-47 name of the language this media item is in.
+   *
+   * @example "en"
+   */
+  language: z.string(),
+  /**
+   * Relative path to the image of this media item. Eg. a book cover or video thumbnail.
+   *
+   * The image is expected to be inside the `images` folder next to the media item definition json.
+   * This image will be used for previews and on the media item detail page.
+   * It can have on of this file types: png, jpg, tiff, webp, gif, svg, avif.
+   * We suggest to give it a size of at least 1000px for it's longer side.
+   *
+   * @example "./images/a-book-about-love--en.jpg"
+   */
+  image: z.string(),
+  /**
+   * List of objects defining the content of this media item.
+   */
+  content: z
+    .array(
+      z.object({
+        /**
+         * Urls might be:
+         * - links to youtube videos
+         * - links to vimeo videos
+         * - links to .mp4 video files
+         * - links to external websites
+         * - links to pdfs (might be hosted inside the public/files/ folder)
+         * - links to epubs (might be hosted inside the public/files/ folder)
+         *
+         * @example "/files/a-book-about-love.pdf"
+         */
+        url: z.string(),
+        /**
+         * The name of the content. If this is not set. The file name
+         * from URL will be used.
+         */
+        name: z.string().optional(),
+      }),
+    )
+    .min(1),
+})
+
+/**
+ * MediaItemSchema above defines the shape of a media item.
+ * We need this function to accept the astro content's image function that
+ * is available inside defineCollection.
+ *
+ * @param schemaContext that is passed by astro's defineCollection schema.
+ * @returns schema with image mixed in.
+ */
+export const mediaSchema = ({ image }: SchemaContext) =>
+  mediaItemSchema.extend({
+    image: astroImage(image),
+  })
+
+/**
+ * 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(),
+  /**
+   * 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(),
+        /**
+         * What style to use for the cover image.
+         *
+         * @example "book"
+         */
+        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"),
+      }),
+    ])
+    .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(),
+})
+
+export const LIGHTNET_COLLECTIONS = {
+  categories: defineCollection({
+    loader: glob({ pattern: "*.json", base: "./src/content/categories" }),
+    schema: categorySchema,
+  }),
+  "media-collections": defineCollection({
+    loader: glob({
+      pattern: "*.json",
+      base: "./src/content/media-collections",
+    }),
+    schema: mediaCollectionSchema,
+  }),
+  media: defineCollection({
+    loader: glob({
+      pattern: "*.json",
+      base: "./src/content/media",
+    }),
+    schema: mediaSchema,
+  }),
+  "media-types": defineCollection({
+    loader: glob({
+      pattern: "*.json",
+      base: "./src/content/media-types",
+    }),
+    schema: mediaTypeSchema,
+  }),
+}

package/src/content/external-api.ts

@@ -0,0 +1,7 @@
+import { type CollectionEntry, getCollection } from "astro:content"
+
+import { type MediaItemQuery, queryMediaItems } from "./query-media-items"
+
+export const getMediaItems = (
+  query?: MediaItemQuery<CollectionEntry<"media">>,
+) => queryMediaItems(getCollection("media"), query ?? {})

package/src/content/get-categories.ts

@@ -0,0 +1,15 @@
+import { type TranslateFn } from "../i18n/translate"
+import { getMediaItems } from "./get-media-items"
+import { resolveCategoryLabel } from "./resolve-category-label"
+
+const contentCategories = new Set<string>(
+  (await getMediaItems())
+    .flatMap((item) => item.data.categories ?? [])
+    .map((c) => c.id),
+)
+
+export async function getCategories(currentLocale: string, t: TranslateFn) {
+  return [...contentCategories.values()]
+    .map((id) => ({ id, name: resolveCategoryLabel(t, id) }))
+    .sort((a, b) => a.name.localeCompare(b.name, currentLocale))
+}

package/src/content/get-languages.ts

@@ -0,0 +1,14 @@
+import { resolveLanguage } from "../i18n/resolve-language"
+import { getMediaItems } from "./get-media-items"
+
+/**
+ * Array of distinct content languages.
+ */
+export const contentLanguages = Object.values(
+  Object.fromEntries(
+    (await getMediaItems()).map(({ data: { language } }) => [
+      language,
+      resolveLanguage(language),
+    ]),
+  ),
+)

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

@@ -0,0 +1,27 @@
+import { getCollection, getEntry } from "astro:content"
+
+import { verifySchemaAsync } from "../utils/verify-schema"
+import { mediaItemEntrySchema } from "./content-schema-internal"
+
+/**
+ * Internal API to get media items. Since this package is a Astro integration
+ * we cannot rely on Astro's getCollection typings. They are configured outside this package.
+ */
+
+export const getMediaItem = async (id: string) => {
+  const item = await getEntry("media", id)
+  return prepareItem(item)
+}
+
+export const getMediaItems = async () => {
+  const items: unknown[] = await getCollection("media")
+  return Promise.all(items.map(prepareItem))
+}
+
+const prepareItem = async (item: unknown) => {
+  return await verifySchemaAsync(
+    mediaItemEntrySchema,
+    item,
+    (id) => `Invalid media item: ${id}`,
+  )
+}

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

@@ -0,0 +1,23 @@
+import { getCollection, getEntry } from "astro:content"
+
+import { verifySchema } from "../utils/verify-schema"
+import { mediaTypeEntrySchema } from "./content-schema-internal"
+
+export const getMediaType = async (id: string) => {
+  return verifySchema(
+    mediaTypeEntrySchema,
+    await getEntry("media-types", id),
+    `Received invalid media type ${id}.`,
+  )
+}
+
+export const getMediaTypes = async () => {
+  const mediaTypes: unknown[] = await getCollection("media-types")
+  return mediaTypes.map((type: unknown) =>
+    verifySchema(
+      mediaTypeEntrySchema,
+      type,
+      (id) => `Received invalid media type '${id}'.`,
+    ),
+  )
+}

package/src/content/query-media-items.ts

@@ -0,0 +1,89 @@
+import type { MediaItemEntry } from "./content-schema-internal"
+
+export type MediaItemQuery<TMediaItem extends MediaItemEntry> = {
+  /**
+   * A filter for multiple fields will be logically combined using AND (&&).
+   */
+  where?: {
+    type?: TMediaItem["data"]["type"]["id"]
+    language?: string
+    category?: NonNullable<TMediaItem["data"]["categories"]>[number]["id"]
+    collection?: NonNullable<
+      TMediaItem["data"]["collections"]
+    >[number]["collection"]["id"]
+  }
+  orderBy?: "dateCreated" | "title"
+  limit?: number
+}
+
+export const queryMediaItems = async <TMediaItem extends MediaItemEntry>(
+  allItems: Promise<TMediaItem[]>,
+  query: MediaItemQuery<TMediaItem>,
+) => {
+  const { where = {}, orderBy, limit } = query
+  const filters: { (item: TMediaItem): boolean }[] = []
+
+  if (where.type) {
+    filters.push((item) => item.data.type.id === where.type)
+  }
+  if (where.language) {
+    filters.push((item) => item.data.language === where.language)
+  }
+  if (where.category) {
+    filters.push(
+      (item) => !!item.data.categories?.find(({ id }) => id === where.category),
+    )
+  }
+  if (where.collection) {
+    filters.push(
+      (item) =>
+        !!item.data.collections?.find(
+          ({ collection }) => collection.id === where.collection,
+        ),
+    )
+  }
+  const combinedFilter = (item: TMediaItem) =>
+    filters.every((filter) => filter(item))
+
+  const items = (await allItems).filter(combinedFilter)
+
+  if (orderBy === "dateCreated") {
+    items.sort((item1, item2) =>
+      item2.data.dateCreated.localeCompare(item1.data.dateCreated),
+    )
+  }
+  if (orderBy === "title") {
+    items.sort((item1, item2) =>
+      item1.data.title.localeCompare(item2.data.title),
+    )
+  }
+  const { collection } = where
+  if (!orderBy && collection) {
+    items.sort((a, b) => compareCollectionItems(a, b, collection))
+  }
+
+  return items.slice(0, limit)
+}
+
+function compareCollectionItems(
+  item1: MediaItemEntry,
+  item2: MediaItemEntry,
+  collectionId: string,
+) {
+  const getIndex = (item: MediaItemEntry) =>
+    item.data.collections?.find(
+      ({ collection }) => collection.id === collectionId,
+    )?.index
+  const index1 = getIndex(item1)
+  const index2 = getIndex(item2)
+  if (index1 === index2) {
+    return item1.id.localeCompare(item2.id)
+  }
+  if (index1 === undefined && index2 !== undefined) {
+    return 1
+  }
+  if (index1 !== undefined && index2 === undefined) {
+    return -1
+  }
+  return index1! - index2!
+}

package/src/content/resolve-category-label.ts

@@ -0,0 +1,20 @@
+import { AstroError } from "astro/errors"
+import { getCollection } from "astro:content"
+
+import type { TranslateFn } from "../i18n/translate"
+
+const categories = await getCollection("categories")
+
+export const resolveCategoryLabel = (
+  translate: TranslateFn,
+  categoryId: string,
+) => {
+  const category = categories.find((c) => c.id === categoryId)
+  if (!category) {
+    throw new AstroError(
+      `Unknown category: ${categoryId}`,
+      "Make sure you add the category to the categories content collection.",
+    )
+  }
+  return translate(category.data.label, { allowFixedStrings: true })
+}

package/src/i18n/get-locale-paths.ts

@@ -0,0 +1,8 @@
+import type { GetStaticPaths } from "astro"
+import config from "virtual:lightnet/config"
+
+import { resolveLocales } from "./resolve-locales"
+
+export const getLocalePaths = (() => {
+  return resolveLocales(config).map((locale) => ({ params: { locale } }))
+}) satisfies GetStaticPaths

package/src/i18n/languages.ts

@@ -0,0 +1,10 @@
+import config from "virtual:lightnet/config"
+
+export const BUNDLED_LANGUAGES = [
+  { code: "de", name: "Deutsch", direction: "ltr" },
+  { code: "en", name: "English", direction: "ltr" },
+]
+
+export const ALL_LANGUAGES = config.languages ?? BUNDLED_LANGUAGES
+
+export type Language = (typeof ALL_LANGUAGES)[number]