@jant/core 0.6.15 → 0.7.0

package/src/types/operations.ts

@@ -3,14 +3,17 @@
  */
 
 import type {
+  ArchiveLayout,
   Format,
   Status,
   Visibility,
   CollectionSortOrder,
+  SmartCollectionSortOrder,
   SystemNavKey,
   NavItemPlacement,
   TextAttachmentContentFormat,
 } from "./constants.js";
+import type { PostFilterSelection } from "../lib/filter-dimensions.js";
 
 export type PostAttachmentInput =
   | {
@@ -93,6 +96,18 @@ export interface CreatePost {
   collectionEntries?: ThreadCollectionEntry[];
   replyToId?: string;
   quietReply?: boolean;
+  /**
+   * BCP 47 content language. Ignored for replies, which always inherit the
+   * Thread root's language so a language filter stays a plain column predicate.
+   * Omitted on single-language sites, where the column stays NULL.
+   */
+  language?: string | null;
+  /**
+   * Thread root ID this Post is a translation of. The service joins both into
+   * one translation group when the Post is created, minting the group on the
+   * source Post if it does not have one yet. Roots only.
+   */
+  translationOfId?: string;
   publishedAt?: number;
   attachments?: PostAttachmentInput[];
 }
@@ -119,6 +134,13 @@ export interface UpdatePost {
   collectionIds?: string[];
   collectionEntries?: ThreadCollectionEntry[];
   publishedAt?: number;
+  /**
+   * Content language. Applied to the whole Thread, like
+   * `PostService.setThreadLanguage` — a Thread is written in one language, and
+   * that is what keeps every language filter a plain column predicate. Ignored
+   * on replies, which follow their root.
+   */
+  language?: string | null;
   attachments?: PostAttachmentInput[];
 }
 
@@ -137,10 +159,20 @@ export type CreateNavItem =
       position?: string;
     }
   | {
+      // The URL is derived from the collection's slug and is not accepted
+      // here; an omitted label means the item follows the collection's title.
       type: "collection";
       collectionId: string;
-      label: string;
-      url: string;
+      label?: string;
+      placement?: NavItemPlacement;
+      position?: string;
+    }
+  | {
+      // Same shape as `collection`: the URL comes from the smart collection's
+      // slug, and an omitted label follows its title.
+      type: "smart_collection";
+      smartCollectionId: string;
+      label?: string;
       placement?: NavItemPlacement;
       position?: string;
     }
@@ -173,11 +205,41 @@ export interface UpdateCollection {
   sortOrder?: CollectionSortOrder;
 }
 
+/**
+ * A smart collection's editable fields.
+ *
+ * `title` is required and stays required: the dialog asks for one, so no
+ * surface ever has to invent a name for an untitled smart collection in a page
+ * heading, a browser tab, a feed, or the directory.
+ */
+export interface CreateSmartCollection {
+  slug: string;
+  title: string;
+  description?: string | null;
+  /** The conditions. Omitted or empty means every post. */
+  selection?: PostFilterSelection;
+  sort?: SmartCollectionSortOrder;
+  layout?: ArchiveLayout | null;
+}
+
+export interface UpdateSmartCollection {
+  slug?: string;
+  title?: string;
+  description?: string | null;
+  selection?: PostFilterSelection;
+  sort?: SmartCollectionSortOrder;
+  layout?: ArchiveLayout | null;
+}
+
 export type CreateCollectionDirectoryEntry =
   | {
       type: "collection";
       collectionId: string;
     }
+  | {
+      type: "smart_collection";
+      smartCollectionId: string;
+    }
   | {
       type: "divider";
       label?: string | null;

package/src/types/props.ts

@@ -2,15 +2,28 @@
  * Page-Level Props & Feed Data Types
  */
 
-import type { CollectionSortOrder, Format, MediaKind } from "./constants.js";
-import type { Collection, CollectionDirectoryItem } from "./entities.js";
+import type {
+  ArchiveLayout,
+  ArchiveVisibility,
+  CollectionSortOrder,
+  SmartCollectionSortOrder,
+} from "./constants.js";
+import type { PostFilterSelection } from "../lib/filter-dimensions.js";
+import type {
+  Collection,
+  CollectionDirectoryItem,
+  SmartCollection,
+} from "./entities.js";
 import type {
   PostView,
   FeedPostView,
+  LanguageAlternate,
+  LanguageSwitcherOption,
   TimelineItemView,
   SearchResultView,
   ArchiveGroup,
 } from "./views.js";
+import type { DiscoverMode } from "../lib/discover.js";
 
 // =============================================================================
 // Page-Level Props
@@ -26,12 +39,27 @@ export interface HomePageProps {
   signinUrl: string;
 }
 
+/** A link to another language's version of a post. */
+export interface PostTranslationLinkView {
+  href: string;
+  /** The language's own name for itself, e.g. "日本語". */
+  label: string;
+  /** Canonical BCP 47 tag. */
+  lang: string;
+}
+
 /** Props for the single post page component */
 export interface PostPageProps {
   post: PostView;
   threadPosts?: PostView[];
   /** Hide owner-only actions while preserving the public post rendering. */
   isPreview?: boolean;
+  /**
+   * Other-language versions of this post. Rendered as one quiet sentence
+   * after the post — a reader who cannot read this one needs a way out that
+   * does not involve guessing at the language switcher.
+   */
+  translations?: PostTranslationLinkView[];
 }
 
 /** Props for the featured page component */
@@ -42,29 +70,33 @@ export interface FeaturedPageProps {
   baseUrl: string;
 }
 
-/** Visibility filter values for the archive page (includes "featured" as a virtual value). */
-export type ArchiveVisibility =
-  | "public"
-  | "latest_hidden"
-  | "private"
-  | "featured";
+export type { ArchiveLayout, ArchiveVisibility };
 
-/** View mode for the archive page. */
-export type ArchiveView = "grid" | "list";
+/**
+ * Time axis for the archive page.
+ *
+ * `published` (default) orders and buckets by when a thread was first
+ * published — the stable historical record. `updated` switches the whole axis
+ * to thread activity, so a thread moves to the month it last gained a post.
+ * Edits are not activity.
+ */
+export type ArchiveSort = "published" | "updated";
 
-/** Filters currently active on the archive page */
+/**
+ * What the archive page is currently showing.
+ *
+ * The selection itself is the shared dimension vocabulary — the chip bar builds
+ * its links by handing an edited copy back to the same serializer the route
+ * parses with, so a chip can never spell a filter the route cannot read.
+ * `layout` and `sort` sit beside it because they shape the rendering, not the
+ * result set.
+ */
 export interface ArchiveFilters {
-  year?: number;
-  collectionSlug?: string;
-  collectionTitle?: string;
-  format?: Format;
-  mediaKinds?: MediaKind[];
-  hasMedia?: boolean;
-  hasTitle?: boolean;
-  /** true = threads (roots with replies), false = single posts (no replies) */
-  hasReplies?: boolean;
-  visibility?: ArchiveVisibility;
-  view?: ArchiveView;
+  selection: PostFilterSelection;
+  /** Omitted when the site's configured default layout is active */
+  layout?: ArchiveLayout;
+  /** Omitted when the default `published` axis is active */
+  sort?: ArchiveSort;
 }
 
 /** Props for the archive page component */
@@ -73,14 +105,30 @@ export interface ArchivePageProps {
   groups: ArchiveGroup[];
   /** Flat timeline items used by list view (skips month grouping) */
   items?: TimelineItemView[];
+  /**
+   * Layout to use when the URL names none. Comes from the site's
+   * `ARCHIVE_DEFAULT_LAYOUT` setting.
+   */
+  defaultLayout?: ArchiveLayout;
   totalCount: number;
+  /**
+   * Matches the same view with every filter cleared. Lets the count say how
+   * much the active filter removed; omitted when nothing is filtered.
+   */
+  baselineCount?: number;
   currentPage: number;
   totalPages: number;
   filters: ArchiveFilters;
   availableYears: number[];
-  availableCollections: { slug: string; title: string }[];
+  availableCollections: { id: string; slug: string; title: string }[];
   isAuthenticated: boolean;
-  sitePathPrefix?: string;
+  /**
+   * Public path this page's own URLs are built from — the deployment prefix
+   * plus, in a language view, that language's prefix (`/blog/en`). Every link
+   * the archive generates is a link back to itself with different filters, so
+   * this is the only prefix it needs.
+   */
+  basePath?: string;
   timeZone?: string;
   /** Href for the RSS feed matching current filters */
   feedHref?: string;
@@ -93,7 +141,8 @@ export interface SearchPageProps {
   error?: string;
   hasMore: boolean;
   page: number;
-  sitePathPrefix?: string;
+  /** Public path this page's own URLs are built from. See `ArchivePageProps`. */
+  basePath?: string;
   isAuthenticated?: boolean;
 }
 
@@ -111,25 +160,80 @@ export interface CollectionPageProps {
   showRatingSort: boolean;
   isAuthenticated: boolean;
   isInNavigation?: boolean;
+  /** Deployment path prefix. Used for links to admin surfaces. */
   sitePathPrefix?: string;
+  /**
+   * Public path prefix for reader-facing links, which in a language view also
+   * carries that language's prefix. Defaults to `sitePathPrefix`.
+   */
+  basePath?: string;
+  /**
+   * Set when the collection is empty in this language but not in the others.
+   * The empty state then says which language is missing and offers the ones
+   * that have something — an empty page with no way out is a dead end.
+   */
+  emptyInLanguage?: {
+    /** The current language's own name for itself. */
+    languageLabel: string;
+    /** This collection in each of the site's other languages. */
+    alternatives: LanguageSwitcherOption[];
+  };
   /** Href for this collection selection's Atom feed when feeds are enabled. */
   feedHref?: string;
 }
 
-/** Props for the collection editor page component */
-export interface CollectionEditorPageProps {
-  mode: "create" | "edit";
-  collection?: Collection;
-  cancelHref: string;
+/** Props for the smart collection page component */
+export interface SmartCollectionPageProps {
+  smartCollection: SmartCollection;
+  items: TimelineItemView[];
+  totalThreadCount: number;
+  currentPage: number;
+  totalPages: number;
+  pagePath: string;
+  baseUrl: string;
+  currentSort: SmartCollectionSortOrder;
+  defaultSort: SmartCollectionSortOrder;
+  showRatingSort: boolean;
+  /** One sentence naming what the conditions gather. Shown to every reader. */
+  conditionSummary: string;
+  /** Archive URL showing the same posts, for a reader who wants to narrow. */
+  conditionHref: string;
+  isAuthenticated: boolean;
+  isInNavigation?: boolean;
+  /** Deployment path prefix. Used for links to admin surfaces. */
   sitePathPrefix?: string;
+  /**
+   * Public path prefix for reader-facing links, which in a language view also
+   * carries that language's prefix. Defaults to `sitePathPrefix`.
+   */
+  basePath?: string;
+  /** Href for this smart collection's Atom feed when feeds are enabled. */
+  feedHref?: string;
 }
 
 /** Props for the collections list page component */
 export interface CollectionsPageProps {
   items: CollectionDirectoryItem[];
   isAuthenticated: boolean;
+  /**
+   * TypeIDs of the collections and smart collections already in the site
+   * navigation. Both kinds share one list: the directory offers them the
+   * same action, and their ID prefixes keep them apart.
+   */
   navigationCollectionIds?: string[];
+  /**
+   * Whether each collection offers its feed. `/subscribe` lists only the
+   * site-wide feeds, so the directory is where a reader is handed a
+   * collection's — beside the collection itself.
+   */
+  feedsEnabled?: boolean;
+  /** Deployment path prefix. Used for links to admin surfaces. */
   sitePathPrefix?: string;
+  /**
+   * Public path prefix for reader-facing links, which in a language view also
+   * carries that language's prefix. Defaults to `sitePathPrefix`.
+   */
+  basePath?: string;
   siteOrigin?: string;
 }
 
@@ -147,6 +251,38 @@ export interface FeedData {
   title?: string;
   selfUrl: string;
   posts: FeedPostView[];
+  /**
+   * The site's avatar, for `atom:icon`. Readers show it beside the feed, and
+   * a directory listing the site has no other machine-readable place to find
+   * it. Omitted when the site has no avatar; Atom has no empty-icon form.
+   */
+  siteIconUrl?: string;
+  /**
+   * Effective Jant Discover mode, declared in the feed header. Omitted means
+   * the feed says nothing about Discover — which a crawler reads as "this
+   * site predates the protocol", not as `none`.
+   */
+  discover?: DiscoverMode;
+  /** Absolute URL of the feed a Discover crawler should poll, if any. */
+  discoverFeedUrl?: string | null;
+  /**
+   * Absolute URL of the site's featured feed, named beside `discoverFeedUrl`
+   * under `latest` so a directory can show featured posts on one list and
+   * everything on another. Null under `featured`, where `discoverFeedUrl`
+   * already is that feed, and under `none`.
+   */
+  discoverFeaturedFeedUrl?: string | null;
+  /**
+   * Absolute URL of the endpoint a directory asks whether posts it holds are
+   * still in these feeds, scoped to this feed's language view. Null under
+   * `none`.
+   */
+  discoverStatusUrl?: string | null;
+  /**
+   * The same feed in the site's other languages. Empty on a single-language
+   * site.
+   */
+  languageAlternates?: LanguageAlternate[];
 }
 
 // =============================================================================
@@ -188,6 +324,8 @@ export interface ThreadPreviewProps {
   leadingReplies: PostView[];
   trailingReplies: PostView[];
   latestReply: PostView;
+  /** Where the gap link points: the first post the fold hides. */
+  gapHref?: string;
   totalReplyCount: number;
 }
 

package/src/types/views.ts

@@ -68,6 +68,11 @@ export interface PostView {
   /** 24-hour featured time, e.g. "23:05" */
   featuredAtTime?: string;
   rating?: number;
+  /**
+   * BCP 47 content language, on Thread roots of a multilingual site. Absent on
+   * replies (they follow the root) and on sites that publish one language.
+   */
+  language?: string;
 
   // Link preview
   /** Preview kind: "video", "image", etc. */
@@ -102,6 +107,12 @@ export interface PostView {
   threadRootId?: string;
   /** Whether this post is the last (most recent) in its thread. Controls reply button visibility. */
   isLastInThread: boolean;
+  /**
+   * TypeID of an unpublished draft that already ends this thread, set only for
+   * the signed-in author on surfaces that do not render drafts. Replying here
+   * would fork the chain, so the reply affordance resumes that draft instead.
+   */
+  draftTailId?: string;
   /** Number of published replies in this thread when relevant to the current view. */
   replyCount?: number;
 
@@ -157,9 +168,13 @@ export interface NavItemView {
   type: NavItemType;
   systemKey?: SystemNavKey;
   collectionId?: string;
+  smartCollectionId?: string;
   postId?: string;
+  /** Author's override, or `""` when the item follows its target's title */
   label: string;
   url: string;
+  /** Target's current title — the display label when `label` is empty */
+  targetTitle?: string;
   /** "header" = visible in nav bar, "more" = under More dropdown */
   placement: NavItemPlacement;
   /** Pre-computed based on currentPath */
@@ -228,6 +243,8 @@ export interface TimelineItemView {
     leadingReplies: PostView[];
     trailingReplies: PostView[];
     latestReply: PostView;
+    /** Where the gap link points: the first post the fold hides. */
+    gapHref?: string;
     totalReplyCount: number;
   };
   curatedThread?: {
@@ -261,14 +278,45 @@ export interface ArchiveGroup {
 /**
  * Site Layout Props
  */
+/** One `<link rel="alternate" hreflang>` target. */
+export interface LanguageAlternate {
+  /** BCP 47 tag, or `x-default` for the entry point. */
+  hreflang: string;
+  /** Absolute URL. */
+  href: string;
+}
+
+/** One entry in the site's language switcher. */
+export interface LanguageSwitcherOption {
+  /** Canonical BCP 47 tag. */
+  lang: string;
+  /** The language's own name for itself, e.g. "日本語". */
+  label: string;
+  /** Where switching to this language takes the reader. */
+  href: string;
+  /** Whether this is the language currently on screen. */
+  isCurrent: boolean;
+  /**
+   * Whether this is the site's primary language — the one served from the
+   * root. The switcher's trigger stays silent on it and names every other
+   * language, so a reader always knows when they are off the default.
+   */
+  isPrimary: boolean;
+}
+
 export interface SiteLayoutProps {
   siteName: string;
   links: NavItemView[];
   currentPath: string;
   sitePathPrefix?: string;
+  /**
+   * Public base for language-scoped chrome links (logo, search, home
+   * detection). `sitePathPrefix` plus the language-view prefix, when any.
+   */
+  basePath?: string;
   isAuthenticated?: boolean;
   collections?: Collection[];
-  siteAvatarUrl?: string;
+  siteAvatarThumbUrl?: string;
   showHeaderAvatar?: boolean;
   siteDescriptionHtml?: string;
   siteFooterHtml?: string;
@@ -281,4 +329,16 @@ export interface SiteLayoutProps {
   slashCommandDiscovered?: boolean;
   /** When set, the mobile compose FAB pre-selects this collection. */
   composeCollectionId?: string;
+  /**
+   * Languages this site publishes in, for the header's language switcher.
+   * Empty on a single-language site, which renders no switcher at all.
+   */
+  languageSwitcher?: LanguageSwitcherOption[];
+  /** Languages offered in the composer. Empty on a single-language site. */
+  composeLanguages?: Array<{ tag: string; label: string }>;
+  /**
+   * Content language of the page the composer opens from. The composer's
+   * automatic language resolves to this unless detection disagrees.
+   */
+  composeContextLanguage?: string | null;
 }

package/src/ui/__tests__/font-themes.test.ts

@@ -1,3 +1,5 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import { describe, it, expect } from "vitest";
 import {
   BUILTIN_FONT_THEMES,
@@ -93,7 +95,7 @@ describe("BUILTIN_FONT_THEMES", () => {
   });
 
   it("routes zh-Hans content to simplified serif and sans fallbacks", () => {
-    const variables = getCjkFontCssVariables("zh-Hans", "off");
+    const variables = getCjkFontCssVariables("zh-Hans");
     const serif = variables["--font-cjk-serif-fallback"];
     const sans = variables["--font-cjk-sans-fallback"];
 
@@ -105,7 +107,7 @@ describe("BUILTIN_FONT_THEMES", () => {
   });
 
   it("routes zh-Hant content to traditional serif and sans fallbacks", () => {
-    const variables = getCjkFontCssVariables("zh-Hant", "off");
+    const variables = getCjkFontCssVariables("zh-Hant");
     const serif = variables["--font-cjk-serif-fallback"];
     const sans = variables["--font-cjk-sans-fallback"];
 
@@ -117,31 +119,69 @@ describe("BUILTIN_FONT_THEMES", () => {
   });
 
   it("routes Japanese content to the Japanese font profile", () => {
-    const variables = getCjkFontCssVariables("ja", "off");
+    const variables = getCjkFontCssVariables("ja");
 
     expect(variables["--font-cjk-serif-fallback"]).toContain('"Noto Serif JP"');
     expect(variables["--font-cjk-sans-fallback"]).toContain('"Noto Sans JP"');
   });
 
   it("routes Korean content to the Korean font profile", () => {
-    const variables = getCjkFontCssVariables("ko", "off");
+    const variables = getCjkFontCssVariables("ko");
 
     expect(variables["--font-cjk-serif-fallback"]).toContain('"Noto Serif KR"');
     expect(variables["--font-cjk-sans-fallback"]).toContain('"Noto Sans KR"');
   });
 
-  it("uses the explicit CJK fallback for an unadapted content language", () => {
-    expect(resolveCjkFontProfile("en", "zh-Hans")).toBe("zh-Hans");
+  it("derives the profile from the language alone", () => {
+    expect(resolveCjkFontProfile("zh-Hant")).toBe("zh-Hant");
+    expect(resolveCjkFontProfile("zh-CN")).toBe("zh-Hans");
+    expect(resolveCjkFontProfile("ja-JP")).toBe("ja");
   });
 
-  it("lets an adapted content language override the manual fallback", () => {
-    expect(resolveCjkFontProfile("zh-Hant", "zh-Hans")).toBe("zh-Hant");
+  it("has no profile for a language without CJK typography", () => {
+    expect(resolveCjkFontProfile("en")).toBeUndefined();
+    expect(resolveCjkFontProfile()).toBeUndefined();
   });
 
-  it("keeps the default profile neutral", () => {
-    expect(getCjkFontCssVariables("en", "off")).toEqual({});
-    expect(DEFAULT_FONT_CJK_SERIF_FALLBACK).toBe('"Jant Language Fallback"');
-    expect(DEFAULT_FONT_CJK_SANS_FALLBACK).toBe('"Jant Language Fallback"');
+  it("leaves a language without a profile on the token defaults", () => {
+    expect(getCjkFontCssVariables("en")).toEqual({});
+  });
+
+  it("keeps the default stacks real, script-neutral and generic-free", () => {
+    for (const stack of [
+      DEFAULT_FONT_CJK_SERIF_FALLBACK,
+      DEFAULT_FONT_CJK_SANS_FALLBACK,
+    ]) {
+      // A placeholder family name is skipped by the browser, which drops CJK
+      // text to the OS last-resort font — the whole point of these constants.
+      expect(stack).not.toContain("Jant Language Fallback");
+      // The generics belong to the theme stack, after this slot.
+      expect(stack).not.toMatch(/\b(?:ui-)?(?:serif|sans-serif)\b/);
+      // Every script the profiles cover is reachable from the default too.
+      for (const family of ["SC", "TC", "JP", "KR"]) {
+        expect(stack).toContain(family);
+      }
+    }
+    expect(DEFAULT_FONT_CJK_SERIF_FALLBACK).toMatch(/^"Songti SC",/);
+    expect(DEFAULT_FONT_CJK_SANS_FALLBACK).toMatch(/^"PingFang SC",/);
+  });
+
+  it("ships the same defaults in tokens.css", () => {
+    const tokens = readFileSync(
+      fileURLToPath(new URL("../../styles/tokens.css", import.meta.url)),
+      "utf8",
+    );
+    const declared = (name: string) => {
+      const match = tokens.match(new RegExp(`--${name}:([^;]*);`));
+      expect(match, `--${name} is missing from tokens.css`).not.toBeNull();
+      return match![1].trim().replace(/\s+/g, " ");
+    };
+    expect(declared("font-cjk-serif-fallback")).toBe(
+      DEFAULT_FONT_CJK_SERIF_FALLBACK,
+    );
+    expect(declared("font-cjk-sans-fallback")).toBe(
+      DEFAULT_FONT_CJK_SANS_FALLBACK,
+    );
   });
 
   it("puts language slots into every serif and sans theme stack", () => {