starlight-theme-apple 0.6.0 → 0.9.0

package/index.ts

@@ -1,137 +1,98 @@
+/// <reference path="./virtual.d.ts" />
 import type { StarlightPlugin } from "@astrojs/starlight/types";
+import type { AstroIntegration } from "astro";
 import { fileURLToPath } from "node:url";
 
-const doccLight = {
-  name: "apple-docc-light",
-  type: "light" as const,
-  colors: {
-    "editor.background": "#f5f5f7",
-    "editor.foreground": "#000000",
-  },
-  settings: [
-    { settings: { foreground: "#000000", background: "#f5f5f7" } },
-    {
-      scope: ["comment", "punctuation.definition.comment"],
-      settings: { foreground: "#707f8c" },
-    },
-    {
-      scope: ["keyword", "storage", "storage.type"],
-      settings: { foreground: "#ad3da4" },
-    },
-    {
-      scope: ["string", "string.quoted", "constant.other.symbol"],
-      settings: { foreground: "#d12f1b" },
-    },
-    {
-      scope: ["constant.numeric", "constant.character"],
-      settings: { foreground: "#272ad8" },
-    },
-    {
-      scope: ["entity.name.type", "entity.name.class", "support.type"],
-      settings: { foreground: "#703daa" },
-    },
-    {
-      scope: ["entity.name.function", "support.function", "variable.function"],
-      settings: { foreground: "#4b21b0" },
-    },
-    {
-      scope: ["entity.other.attribute-name", "variable.other.constant"],
-      settings: { foreground: "#947100" },
-    },
-    {
-      scope: ["meta.preprocessor", "keyword.control.directive"],
-      settings: { foreground: "#78492a" },
-    },
-  ],
+import {
+  type StarlightThemeAppleConfig,
+  type StarlightThemeAppleUserConfig,
+  configSchema,
+} from "./libs/config";
+import { expressiveCodeConfig } from "./libs/expressive-code";
+import { translations } from "./translations";
+
+export type {
+  StarlightThemeAppleConfig,
+  StarlightThemeAppleLink,
+  StarlightThemeAppleUserConfig,
+} from "./libs/config";
+
+const component = (name: string) =>
+  fileURLToPath(new URL(`./components/${name}.astro`, import.meta.url));
+
+/** Components the theme provides. Consumer and earlier-plugin overrides always win. */
+const themeComponents = {
+  Header: component("Header"),
+  PageFrame: component("PageFrame"),
+  Sidebar: component("Sidebar"),
+  SocialIcons: component("SocialIcons"),
+  PageTitle: component("PageTitle"),
+  Footer: component("Footer"),
+  Pagination: component("Pagination"),
 };
 
-const doccDark = {
-  name: "apple-docc-dark",
-  type: "dark" as const,
-  colors: {
-    "editor.background": "#1c1c1e",
-    "editor.foreground": "#ffffff",
-  },
-  settings: [
-    { settings: { foreground: "#ffffff", background: "#1c1c1e" } },
-    {
-      scope: ["comment", "punctuation.definition.comment"],
-      settings: { foreground: "#7f8c98" },
-    },
-    {
-      scope: ["keyword", "storage", "storage.type"],
-      settings: { foreground: "#ff7ab2" },
-    },
-    {
-      scope: ["string", "string.quoted", "constant.other.symbol"],
-      settings: { foreground: "#ff8170" },
-    },
-    {
-      scope: ["constant.numeric", "constant.character"],
-      settings: { foreground: "#d9c97c" },
-    },
-    {
-      scope: ["entity.name.type", "entity.name.class", "support.type"],
-      settings: { foreground: "#dabaff" },
-    },
-    {
-      scope: ["entity.name.function", "support.function", "variable.function"],
-      settings: { foreground: "#b281eb" },
-    },
-    {
-      scope: ["entity.other.attribute-name", "variable.other.constant"],
-      settings: { foreground: "#cc9768" },
-    },
-    {
-      scope: ["meta.preprocessor", "keyword.control.directive"],
-      settings: { foreground: "#ffa14f" },
+function configIntegration(
+  config: StarlightThemeAppleConfig
+): AstroIntegration {
+  const moduleId = "virtual:starlight-theme-apple/config";
+  const resolvedId = `\0${moduleId}`;
+  return {
+    name: "starlight-theme-apple-config",
+    hooks: {
+      "astro:config:setup"({ updateConfig }) {
+        updateConfig({
+          vite: {
+            plugins: [
+              {
+                name: "vite-plugin-starlight-theme-apple-config",
+                resolveId: (id) => (id === moduleId ? resolvedId : undefined),
+                load: (id) =>
+                  id === resolvedId
+                    ? `export default ${JSON.stringify(config)};`
+                    : undefined,
+              },
+            ],
+          },
+        });
+      },
     },
-  ],
-};
+  };
+}
+
+export default function starlightThemeApple(
+  userConfig?: StarlightThemeAppleUserConfig
+): StarlightPlugin {
+  const parsed = configSchema.safeParse(userConfig);
+  if (!parsed.success) {
+    throw new Error(
+      `Invalid starlight-theme-apple configuration:\n${parsed.error.issues
+        .map(
+          (issue) => `- ${issue.path.join(".") || "(root)"}: ${issue.message}`
+        )
+        .join("\n")}`
+    );
+  }
+  const config = parsed.data;
 
-export default function starlightThemeApple(): StarlightPlugin {
   return {
     name: "starlight-theme-apple",
     hooks: {
-      "config:setup"({ config, updateConfig }) {
-        const userExpressiveCodeConfig =
-          !config.expressiveCode || config.expressiveCode === true
-            ? {}
-            : config.expressiveCode;
-
+      "i18n:setup"({ injectTranslations }) {
+        injectTranslations(translations);
+      },
+      "config:setup"({
+        config: starlightConfig,
+        updateConfig,
+        addIntegration,
+      }) {
+        addIntegration(configIntegration(config));
         updateConfig({
-          components: {
-            ...config.components,
-            PageTitle: fileURLToPath(
-              new URL("./components/PageTitle.astro", import.meta.url)
-            ),
-            Pagination: fileURLToPath(
-              new URL("./components/Pagination.astro", import.meta.url)
-            ),
-          },
+          components: { ...themeComponents, ...starlightConfig.components },
           customCss: [
-            ...(config.customCss ?? []),
             "starlight-theme-apple/styles.css",
+            ...(starlightConfig.customCss ?? []),
           ],
-          expressiveCode:
-            config.expressiveCode === false
-              ? false
-              : {
-                  themes: [doccDark, doccLight],
-                  ...userExpressiveCodeConfig,
-                  styleOverrides: {
-                    borderColor: "var(--apple-hairline)",
-                    borderRadius: "var(--apple-radius-sm)",
-                    ...userExpressiveCodeConfig.styleOverrides,
-                    frames: {
-                      editorActiveTabIndicatorTopColor: "unset",
-                      editorActiveTabIndicatorBottomColor: "var(--apple-link)",
-                      editorTabBarBorderBottomColor: "var(--apple-hairline)",
-                      frameBoxShadowCssValue: "unset",
-                      ...userExpressiveCodeConfig.styleOverrides?.frames,
-                    },
-                  },
-                },
+          expressiveCode: expressiveCodeConfig(starlightConfig.expressiveCode),
         });
       },
     },

package/libs/breadcrumbs.ts

@@ -0,0 +1,80 @@
+interface SidebarLink {
+  type: "link";
+  label: string;
+  href: string;
+  isCurrent: boolean;
+}
+interface SidebarGroup {
+  type: "group";
+  label: string;
+  entries: SidebarEntry[];
+}
+type SidebarEntry = SidebarLink | SidebarGroup;
+
+export interface Crumb {
+  label: string;
+  href?: string | undefined;
+}
+
+const isInternal = (href: string) =>
+  href.startsWith("/") && !href.startsWith("//");
+
+function links(entries: SidebarEntry[]): SidebarLink[] {
+  return entries.flatMap((entry) =>
+    entry.type === "link" ? [entry] : links(entry.entries)
+  );
+}
+
+/**
+ * A group’s landing page is a direct child link whose path contains every other page in the
+ * group, such as an “Overview” at `/guides/` above `/guides/install/`.
+ */
+function landingPage(group: SidebarGroup): SidebarLink | undefined {
+  const pages = links(group.entries).filter((link) => isInternal(link.href));
+  if (pages.length < 2) return undefined;
+  return group.entries.find(
+    (entry): entry is SidebarLink =>
+      entry.type === "link" &&
+      isInternal(entry.href) &&
+      pages.every((page) => page.href.startsWith(entry.href))
+  );
+}
+
+function ancestors(
+  entries: SidebarEntry[],
+  trail: SidebarGroup[] = []
+): SidebarGroup[] | undefined {
+  for (const entry of entries) {
+    if (entry.type === "link") {
+      if (entry.isCurrent) return trail;
+    } else {
+      const found = ancestors(entry.entries, [...trail, entry]);
+      if (found) return found;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Breadcrumbs from the site root through the sidebar groups containing the current page.
+ * Groups link to their landing page when they have one. A group whose landing page is the
+ * current page, or the site root itself, is omitted because it would repeat the title or root.
+ */
+export function breadcrumbs(
+  sidebar: unknown,
+  siteTitle: string,
+  siteHref: string
+): Crumb[] {
+  const entries = sidebar as SidebarEntry[];
+  const trail = ancestors(entries);
+  const current = links(entries).find((link) => link.isCurrent);
+  if (!trail || current?.href === siteHref) return [];
+
+  const crumbs: Crumb[] = [{ label: siteTitle, href: siteHref }];
+  for (const group of trail) {
+    const landing = landingPage(group);
+    if (landing?.isCurrent || landing?.href === siteHref) continue;
+    crumbs.push({ label: group.label, href: landing?.href });
+  }
+  return crumbs;
+}

package/libs/config.ts

@@ -0,0 +1,54 @@
+import type { StarlightIcon } from "@astrojs/starlight/types";
+import { z } from "astro/zod";
+
+const attrsSchema = z
+  .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
+  .optional();
+
+const linkSchema = z.object({
+  /** Visible text for the link. */
+  label: z.string().min(1),
+  /**
+   * Destination. Paths starting with `/` are resolved against Astro's `base`, the same way
+   * Starlight resolves sidebar links. Full URLs are used as they are.
+   */
+  link: z.string().min(1),
+  /** Optional Starlight icon name shown before the label. */
+  icon: z
+    .custom<StarlightIcon>((value) => typeof value === "string")
+    .optional(),
+  /** Extra HTML attributes for the rendered `<a>`, e.g. analytics `data-*` attributes. */
+  attrs: attrsSchema,
+});
+
+export const configSchema = z
+  .object({
+    /** Primary navigation shown in the header and, on small screens, in the navigation menu. */
+    nav: z.array(linkSchema).default([]),
+    /** One emphasized header action, such as “Download”. */
+    action: linkSchema.optional(),
+    /** Extra HTML attributes for Starlight `social` links, keyed by their `icon` name. */
+    socialAttrs: z.record(z.string(), attrsSchema.unwrap()).default({}),
+    footer: z
+      .object({
+        /** Optional columns of site navigation. */
+        groups: z
+          .array(
+            z.object({
+              label: z.string().min(1),
+              links: z.array(linkSchema),
+            })
+          )
+          .default([]),
+        /** Supporting links shown in the site footer. */
+        links: z.array(linkSchema).default([]),
+        /** A short line of text such as a copyright notice. */
+        copyright: z.string().optional(),
+      })
+      .default({ groups: [], links: [] }),
+  })
+  .default({ nav: [], socialAttrs: {}, footer: { groups: [], links: [] } });
+
+export type StarlightThemeAppleUserConfig = z.input<typeof configSchema>;
+export type StarlightThemeAppleConfig = z.output<typeof configSchema>;
+export type StarlightThemeAppleLink = z.output<typeof linkSchema>;

package/libs/expressive-code.ts

@@ -0,0 +1,246 @@
+import type { StarlightUserConfig } from "@astrojs/starlight/types";
+
+type ExpressiveCodeConfig = Exclude<
+  NonNullable<StarlightUserConfig["expressiveCode"]>,
+  boolean
+>;
+
+interface Palette {
+  background: string;
+  foreground: string;
+  comment: string;
+  keyword: string;
+  string: string;
+  number: string;
+  type: string;
+  function: string;
+  property: string;
+  attribute: string;
+  preprocessor: string;
+}
+
+/** Syntax colors modeled on Xcode's default light and dark themes. */
+function xcodeTheme(name: string, type: "light" | "dark", p: Palette) {
+  return {
+    name,
+    type,
+    colors: {
+      "editor.background": p.background,
+      "editor.foreground": p.foreground,
+    },
+    settings: [
+      { settings: { foreground: p.foreground, background: p.background } },
+      {
+        scope: ["comment", "punctuation.definition.comment"],
+        settings: { foreground: p.comment },
+      },
+      {
+        scope: [
+          "keyword",
+          "storage",
+          "storage.type",
+          "storage.modifier",
+          "constant.language",
+        ],
+        settings: { foreground: p.keyword, fontStyle: "bold" },
+      },
+      {
+        scope: ["keyword.operator", "punctuation", "meta.brace"],
+        settings: { foreground: p.foreground, fontStyle: "" },
+      },
+      {
+        scope: [
+          "string",
+          "string.quoted",
+          "constant.other.symbol",
+          "markup.inline.raw",
+        ],
+        settings: { foreground: p.string },
+      },
+      {
+        scope: [
+          "constant.numeric",
+          "constant.character",
+          "constant.other.boolean",
+        ],
+        settings: { foreground: p.number },
+      },
+      {
+        scope: [
+          "entity.name.type",
+          "entity.name.class",
+          "support.type",
+          "support.class",
+          "entity.name.tag",
+        ],
+        settings: { foreground: p.type },
+      },
+      {
+        scope: [
+          "entity.name.function",
+          "support.function",
+          "variable.function",
+          "meta.function-call",
+        ],
+        settings: { foreground: p.function },
+      },
+      {
+        scope: [
+          "support.type.property-name",
+          "meta.object-literal.key",
+          "variable.other.property",
+          "variable.other.key",
+          "entity.name.section",
+          "variable.other.constant",
+        ],
+        settings: { foreground: p.property },
+      },
+      {
+        scope: [
+          "entity.other.attribute-name",
+          "meta.attribute",
+          "variable.parameter",
+        ],
+        settings: { foreground: p.attribute },
+      },
+      {
+        scope: [
+          "meta.preprocessor",
+          "keyword.control.directive",
+          "entity.name.function.preprocessor",
+        ],
+        settings: { foreground: p.preprocessor },
+      },
+      {
+        scope: ["markup.heading", "markup.bold"],
+        settings: { fontStyle: "bold" },
+      },
+      { scope: ["markup.italic"], settings: { fontStyle: "italic" } },
+      { scope: ["markup.deleted"], settings: { foreground: p.string } },
+      { scope: ["markup.inserted"], settings: { foreground: p.property } },
+    ],
+  };
+}
+
+export const xcodeLight = xcodeTheme("apple-xcode-light", "light", {
+  background: "#f5f5f7",
+  foreground: "#1d1d1f",
+  comment: "#5d6c79",
+  keyword: "#9b2393",
+  string: "#c41a16",
+  number: "#1c00cf",
+  type: "#703daa",
+  function: "#3900a0",
+  property: "#326d74",
+  attribute: "#815f03",
+  preprocessor: "#643820",
+});
+
+export const xcodeDark = xcodeTheme("apple-xcode-dark", "dark", {
+  background: "#1d1d1f",
+  foreground: "#f5f5f7",
+  comment: "#7f8c98",
+  keyword: "#ff7ab2",
+  string: "#ff8170",
+  number: "#d9c97c",
+  type: "#dabaff",
+  function: "#b281eb",
+  property: "#78c2b3",
+  attribute: "#cc9768",
+  preprocessor: "#ffa14f",
+});
+
+/**
+ * Apple code listings are flat, borderless panels. Colors come from theme tokens so code
+ * follows the page palette and any token a consumer overrides.
+ */
+const styleOverrides = {
+  borderWidth: "0px",
+  borderRadius: "var(--apple-radius-panel)",
+  borderColor: "var(--apple-hairline)",
+  codeBackground: "var(--apple-code-background)",
+  codeFontFamily: "var(--apple-font-mono)",
+  codeFontSize: "0.875rem",
+  codeLineHeight: "1.65",
+  codePaddingBlock: "0.875rem",
+  codePaddingInline: "1.125rem",
+  uiFontFamily: "var(--apple-font-sans)",
+  uiFontSize: "0.8125rem",
+  focusBorder: "var(--apple-link)",
+  scrollbarThumbColor: "var(--apple-hairline)",
+  textMarkers: {
+    lineMarkerAccentWidth: "0.1875rem",
+    markBackground: "color-mix(in srgb, var(--apple-link) 12%, transparent)",
+    markBorderColor: "color-mix(in srgb, var(--apple-link) 55%, transparent)",
+    insBackground: "color-mix(in srgb, var(--apple-success) 13%, transparent)",
+    insBorderColor: "color-mix(in srgb, var(--apple-success) 60%, transparent)",
+    insDiffIndicatorColor: "var(--apple-success)",
+    delBackground: "color-mix(in srgb, var(--apple-danger) 11%, transparent)",
+    delBorderColor: "color-mix(in srgb, var(--apple-danger) 55%, transparent)",
+    delDiffIndicatorColor: "var(--apple-danger)",
+  },
+  frames: {
+    shadowColor: "transparent",
+    frameBoxShadowCssValue: "none",
+    editorBackground: "var(--apple-code-background)",
+    editorTabBarBackground: "var(--apple-code-background)",
+    editorTabBarBorderColor: "transparent",
+    editorTabBarBorderBottomColor: "var(--apple-hairline)",
+    editorActiveTabBackground: "var(--apple-code-background)",
+    editorActiveTabForeground: "var(--apple-secondary-foreground)",
+    editorActiveTabBorderColor: "transparent",
+    editorActiveTabIndicatorHeight: "0px",
+    editorActiveTabIndicatorTopColor: "transparent",
+    editorActiveTabIndicatorBottomColor: "transparent",
+    editorTabBorderRadius: "0px",
+    editorTabsMarginInlineStart: "0.375rem",
+    terminalBackground: "var(--apple-code-background)",
+    terminalTitlebarBackground: "var(--apple-code-background)",
+    terminalTitlebarForeground: "var(--apple-secondary-foreground)",
+    terminalTitlebarBorderBottomColor: "var(--apple-hairline)",
+    terminalTitlebarDotsForeground: "var(--apple-tertiary-foreground)",
+    terminalTitlebarDotsOpacity: "0.35",
+    inlineButtonBackground: "var(--apple-background)",
+    inlineButtonForeground: "var(--apple-secondary-foreground)",
+    inlineButtonBorder: "var(--apple-hairline)",
+    inlineButtonBorderOpacity: "1",
+    inlineButtonBackgroundIdleOpacity: "0.85",
+    inlineButtonBackgroundHoverOrFocusOpacity: "1",
+    inlineButtonBackgroundActiveOpacity: "1",
+    tooltipSuccessBackground: "var(--apple-success)",
+    tooltipSuccessForeground: "#fff",
+  },
+};
+
+/** Merge the theme's Expressive Code defaults beneath the consumer's own configuration. */
+export function expressiveCodeConfig(
+  user: StarlightUserConfig["expressiveCode"]
+): StarlightUserConfig["expressiveCode"] {
+  if (user === false) return false;
+  const config: ExpressiveCodeConfig = user === true || !user ? {} : user;
+  const userStyles = (config.styleOverrides ?? {}) as Record<
+    string,
+    unknown
+  > & {
+    frames?: Record<string, unknown>;
+    textMarkers?: Record<string, unknown>;
+  };
+  return {
+    themes: [xcodeDark, xcodeLight],
+    // Shell snippets render as plain code listings rather than empty terminal windows.
+    // Use `frame="terminal"` on a block, or set `defaultProps`, to restore the window chrome.
+    defaultProps: {
+      overridesByLang: {
+        "ansi,bash,sh,shell,shellscript,shellsession,zsh,fish,powershell,ps,ps1":
+          { frame: "code" },
+      },
+    },
+    ...config,
+    styleOverrides: {
+      ...styleOverrides,
+      ...userStyles,
+      frames: { ...styleOverrides.frames, ...userStyles.frames },
+      textMarkers: { ...styleOverrides.textMarkers, ...userStyles.textMarkers },
+    },
+  } as ExpressiveCodeConfig;
+}

package/libs/links.ts

@@ -0,0 +1,38 @@
+import type { StarlightThemeAppleLink } from "./config";
+
+const base = import.meta.env.BASE_URL.replace(/\/$/, "");
+const hasProtocol = (link: string) => /^[a-z][a-z\d+.-]*:/i.test(link);
+
+/** Resolve a configured link against the site `base`, as Starlight does for sidebar links. */
+export function resolveHref(link: string): string {
+  if (hasProtocol(link) || link.startsWith("//") || link.startsWith("#"))
+    return link;
+  const path = link.startsWith("/") ? link : `/${link}`;
+  return `${base}${path}`;
+}
+
+const normalize = (path: string) => path.replace(/\/?(index\.html)?$/, "/");
+
+/**
+ * A header link is current when the page is the link target or lives below it.
+ * The site root only matches itself so it does not mark every page as current.
+ */
+export function isCurrentSection(href: string, pathname: string): boolean {
+  if (hasProtocol(href) || href.startsWith("//") || href.startsWith("#"))
+    return false;
+  const target = normalize(href.split(/[?#]/)[0] ?? href);
+  const current = normalize(pathname);
+  if (target === normalize(`${base}/`)) return current === target;
+  return current.startsWith(target);
+}
+
+export function linkProps(item: StarlightThemeAppleLink, pathname: string) {
+  const href = resolveHref(item.link);
+  const external = hasProtocol(href) || href.startsWith("//");
+  return {
+    href,
+    current: isCurrentSection(href, pathname),
+    external,
+    attrs: item.attrs ?? {},
+  };
+}

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "starlight-theme-apple",
-  "version": "0.6.0",
+  "version": "0.9.0",
   "description": "An Apple Developer Documentation-inspired theme for Astro Starlight.",
   "keywords": [
     "starlight",
+    "starlight-plugin",
+    "starlight-theme",
     "theme",
+    "apple",
     "apple-developer-documentation",
-    "docs",
-    "black",
-    "dark"
+    "docs"
   ],
   "homepage": "https://acsandmann.github.io/starlight-theme-apple/",
   "bugs": {
@@ -24,15 +25,20 @@
   "type": "module",
   "exports": {
     ".": "./index.ts",
+    "./components": "./components.ts",
     "./styles.css": "./styles.css",
     "./styles/*": "./styles/*"
   },
+  "scripts": {
+    "test": "bun test"
+  },
   "devDependencies": {
     "@astrojs/starlight": "^0.41.7",
     "astro": "^7.0.2"
   },
   "peerDependencies": {
-    "@astrojs/starlight": ">=0.38"
+    "@astrojs/starlight": ">=0.41.0",
+    "astro": ">=7.0.0"
   },
   "engines": {
     "node": ">=22.23.2"