@moldea.ai/website-ui 1.0.0

package/src/components/breadcrumbs/breadcrumbs.component.astro

@@ -0,0 +1,52 @@
+---
+import { ChevronRight } from '@lucide/astro';
+
+import { withBase } from '../../site/index.ts';
+
+export interface IBreadcrumb {
+  href?: string;
+  label: string;
+}
+
+export interface Props {
+  basePath?: string;
+  items: IBreadcrumb[];
+}
+
+const { basePath = import.meta.env.BASE_URL, items } = Astro.props;
+---
+
+<nav
+  aria-label="Breadcrumb"
+  class="min-w-0 text-sm text-muted-foreground"
+>
+  <ol class="flex min-w-0 flex-wrap items-center gap-x-1.5 gap-y-2">
+    {
+      items.map((item, index) => (
+        <li class="flex min-w-0 items-center gap-1.5">
+          {index > 0 && (
+            <ChevronRight
+              class="size-3.5 shrink-0"
+              aria-hidden="true"
+            />
+          )}
+          {item.href ? (
+            <a
+              class="rounded-sm underline-offset-4 hover:text-foreground hover:underline"
+              href={withBase(item.href, basePath)}
+            >
+              {item.label}
+            </a>
+          ) : (
+            <span
+              class="min-w-0 font-medium text-foreground"
+              aria-current="page"
+            >
+              {item.label}
+            </span>
+          )}
+        </li>
+      ))
+    }
+  </ol>
+</nav>

package/src/components/inline-brand-text/inline-brand-text.component.astro

@@ -0,0 +1,20 @@
+---
+export interface Props {
+  text: string;
+}
+
+const { text } = Astro.props;
+const segments = text.split(/(\bmoldea\b)/gu);
+---
+
+{
+  segments.map((segment) =>
+    segment === 'moldea' ? (
+      <code class="rounded-md bg-code px-1.5 py-1 font-mono text-[0.86em] font-semibold text-code-foreground">
+        {segment}
+      </code>
+    ) : (
+      segment
+    ),
+  )
+}

package/src/components/local-search/local-search.component.astro

@@ -0,0 +1,188 @@
+---
+import { Search } from '@lucide/astro';
+
+import ActionButton from '../action-button/action-button.component.astro';
+
+export interface Props {
+  action: string;
+  buttonLabel?: string;
+  failureMessage: string;
+  initialPrompt: string;
+  inputId?: string;
+  label?: string;
+  loadingMessage?: string;
+  noResultsMessage?: string;
+  placeholder: string;
+  searchIndexUrl: string;
+}
+
+const {
+  action,
+  buttonLabel = 'Search',
+  failureMessage,
+  initialPrompt,
+  inputId = 'documentation-search',
+  label = 'Search documentation',
+  loadingMessage = 'Searching the local documentation index…',
+  noResultsMessage = 'No matching documentation was found.',
+  placeholder,
+  searchIndexUrl,
+} = Astro.props;
+---
+
+<div
+  data-local-search
+  data-failure-message={failureMessage}
+  data-initial-prompt={initialPrompt}
+  data-loading-message={loadingMessage}
+  data-no-results-message={noResultsMessage}
+>
+  <form
+    class="mt-10"
+    data-search-form
+    data-search-index-url={searchIndexUrl}
+    {action}
+    method="get"
+    role="search"
+  >
+    <label
+      class="sr-only"
+      for={inputId}
+      >{label}</label
+    >
+    <div class="flex flex-col gap-3 sm:flex-row sm:items-center">
+      <div class="relative min-w-0 flex-1">
+        <Search
+          class="pointer-events-none absolute start-3 top-1/2 size-5 -translate-y-1/2 text-secondary-foreground"
+          aria-hidden="true"
+        />
+        <input
+          id={inputId}
+          class="min-h-12 w-full min-w-0 rounded-lg border border-border bg-background py-2 ps-10 pe-3 text-lg shadow-inset transition-colors outline-none placeholder:text-secondary-foreground focus-visible:border-transparent! focus-visible:shadow-none focus-visible:ring-2 focus-visible:ring-foreground focus-visible:ring-offset-2 focus-visible:ring-offset-background dark:bg-border/30"
+          type="search"
+          name="query"
+          {placeholder}
+          autocomplete="off"
+          data-search-input
+        />
+      </div>
+      <ActionButton
+        class="px-5 py-3 font-bold"
+        size="lg"
+        type="submit"
+      >
+        {buttonLabel}
+      </ActionButton>
+    </div>
+  </form>
+
+  <p
+    class="mt-4 text-sm text-muted-foreground"
+    aria-live="polite"
+    data-search-status
+  >
+    {initialPrompt}
+  </p>
+  <ol
+    class="mt-8 grid gap-4"
+    data-search-results
+  >
+  </ol>
+</div>
+
+<script>
+  import {
+    parseSearchDocuments,
+    searchDocuments,
+    type ISearchDocument,
+  } from '../../search/index.ts';
+
+  const createSearchResult = (searchDocument: ISearchDocument): HTMLLIElement => {
+    const item = document.createElement('li');
+    const link = document.createElement('a');
+    const title = document.createElement('h2');
+    const excerpt = document.createElement('p');
+
+    item.className = 'surface-card interactive-card p-5';
+    link.className = 'block rounded-md';
+    link.href = searchDocument.url;
+    title.className = 'text-xl font-semibold tracking-tight';
+    title.textContent = searchDocument.title;
+    excerpt.className = 'mt-2 leading-6 text-muted-foreground';
+    excerpt.textContent = searchDocument.description;
+    link.append(title, excerpt);
+    item.append(link);
+
+    return item;
+  };
+
+  const initializeSearch = (root: HTMLElement): void => {
+    const form = root.querySelector<HTMLFormElement>('[data-search-form]');
+    const input = root.querySelector<HTMLInputElement>('[data-search-input]');
+    const status = root.querySelector<HTMLElement>('[data-search-status]');
+    const results = root.querySelector<HTMLOListElement>('[data-search-results]');
+
+    if (!form || !input || !status || !results || root.dataset.searchInitialized === 'true') {
+      return;
+    }
+
+    const searchIndexUrl = form.dataset.searchIndexUrl;
+
+    if (!searchIndexUrl) return;
+
+    root.dataset.searchInitialized = 'true';
+    const documentsPromise = fetch(searchIndexUrl).then(async (response) => {
+      if (!response.ok) {
+        throw new Error('The documentation search index could not be loaded.');
+      }
+
+      return parseSearchDocuments(await response.json());
+    });
+
+    const runSearch = async (query: string): Promise<void> => {
+      results.replaceChildren();
+
+      if (!query.trim()) {
+        status.textContent = root.dataset.initialPrompt ?? '';
+        return;
+      }
+
+      status.textContent = root.dataset.loadingMessage ?? '';
+
+      try {
+        const matches = searchDocuments(query, await documentsPromise);
+
+        for (const match of matches) {
+          results.append(createSearchResult(match));
+        }
+
+        status.textContent = matches.length
+          ? `${matches.length} result${matches.length === 1 ? '' : 's'} for “${query}”.`
+          : (root.dataset.noResultsMessage ?? '');
+      } catch {
+        status.textContent = root.dataset.failureMessage ?? '';
+      }
+    };
+
+    form.addEventListener('submit', (event) => {
+      event.preventDefault();
+      void runSearch(input.value);
+    });
+
+    const query = new URLSearchParams(window.location.search).get('query');
+
+    if (query) {
+      input.value = query;
+      void runSearch(query);
+    }
+  };
+
+  const initializeLocalSearch = (): void => {
+    for (const root of document.querySelectorAll<HTMLElement>('[data-local-search]')) {
+      initializeSearch(root);
+    }
+  };
+
+  document.addEventListener('astro:page-load', initializeLocalSearch);
+  initializeLocalSearch();
+</script>

package/src/components/theme-bootstrap/theme-bootstrap.component.astro

@@ -0,0 +1,32 @@
+---
+export interface Props {
+  storageKey: string;
+}
+
+const { storageKey } = Astro.props;
+---
+
+<script is:inline define:vars={{ storageKey }}>
+  (() => {
+    let stored = null;
+
+    try {
+      stored = localStorage.getItem(storageKey);
+    } catch {
+      stored = null;
+    }
+
+    const preference =
+      stored === 'light' || stored === 'dark' || stored === 'system' ? stored : 'system';
+    const isDark =
+      preference === 'dark' ||
+      (preference === 'system' && matchMedia('(prefers-color-scheme: dark)').matches);
+    const root = document.documentElement;
+
+    root.classList.remove('light', 'dark');
+    root.classList.add(isDark ? 'dark' : 'light');
+    root.dataset.theme = preference;
+    root.dataset.themeStorageKey = storageKey;
+    root.style.colorScheme = isDark ? 'dark' : 'light';
+  })();
+</script>

package/src/components/theme-control/theme-control.component.astro

@@ -0,0 +1,126 @@
+---
+import { Moon, Sun } from '@lucide/astro';
+
+export interface Props {
+  class?: string;
+  storageKey: string;
+}
+
+const { class: className, storageKey } = Astro.props;
+---
+
+<button
+  class:list={['action-control action-ghost action-size-icon max-md:size-11', className]}
+  type="button"
+  data-theme-control
+  data-theme-storage-key={storageKey}
+  aria-label="Use dark theme"
+  title="Use dark theme"
+>
+  <Moon
+    class="theme-use-dark-icon size-4"
+    aria-hidden="true"
+  />
+  <Sun
+    class="theme-use-light-icon hidden size-4"
+    aria-hidden="true"
+  />
+</button>
+
+<script>
+  import { isDarkTheme, parseThemePreference, type IThemePreference } from '../../theme/index.ts';
+
+  const readPreference = (storageKey: string): IThemePreference => {
+    try {
+      return parseThemePreference(localStorage.getItem(storageKey));
+    } catch {
+      return 'system';
+    }
+  };
+
+  const persistPreference = (storageKey: string, preference: IThemePreference): void => {
+    try {
+      localStorage.setItem(storageKey, preference);
+    } catch {
+      // theme selection still applies to the active page when storage is unavailable
+    }
+  };
+
+  const applyTheme = (preference: IThemePreference, storageKey: string): void => {
+    const isDark = isDarkTheme(
+      preference,
+      window.matchMedia('(prefers-color-scheme: dark)').matches,
+    );
+    const root = document.documentElement;
+
+    root.classList.remove('light', 'dark');
+    root.classList.add(isDark ? 'dark' : 'light');
+    root.dataset.theme = preference;
+    root.dataset.themeStorageKey = storageKey;
+    root.style.colorScheme = isDark ? 'dark' : 'light';
+
+    const label = isDark ? 'Use light theme' : 'Use dark theme';
+
+    for (const control of document.querySelectorAll<HTMLButtonElement>(
+      `[data-theme-control][data-theme-storage-key="${CSS.escape(storageKey)}"]`,
+    )) {
+      control.dataset.nextTheme = isDark ? 'light' : 'dark';
+      control.setAttribute('aria-label', label);
+      control.title = label;
+    }
+  };
+
+  const synchronizeThemeControls = (): void => {
+    const controls = document.querySelectorAll<HTMLButtonElement>('[data-theme-control]');
+    const storageKeys = new Set(
+      [...controls]
+        .map((control) => control.dataset.themeStorageKey)
+        .filter((storageKey): storageKey is string => Boolean(storageKey)),
+    );
+
+    for (const storageKey of storageKeys) {
+      applyTheme(readPreference(storageKey), storageKey);
+    }
+  };
+
+  if (document.documentElement.dataset.themeControlInitialized !== 'true') {
+    document.documentElement.dataset.themeControlInitialized = 'true';
+
+    document.addEventListener('click', (event) => {
+      const target = event.target;
+
+      if (!(target instanceof Element)) return;
+
+      const control = target.closest<HTMLButtonElement>('[data-theme-control]');
+      const storageKey = control?.dataset.themeStorageKey;
+
+      if (!control || !storageKey) return;
+
+      const preference = control.dataset.nextTheme === 'light' ? 'light' : 'dark';
+
+      persistPreference(storageKey, preference);
+      applyTheme(preference, storageKey);
+    });
+
+    document.addEventListener('astro:page-load', synchronizeThemeControls);
+    window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', () => {
+      const storageKey = document.documentElement.dataset.themeStorageKey;
+
+      if (storageKey && document.documentElement.dataset.theme === 'system') {
+        applyTheme('system', storageKey);
+      }
+    });
+  }
+
+  synchronizeThemeControls();
+</script>
+
+<style>
+  :global(html.dark) .theme-use-dark-icon {
+    display: none;
+  }
+
+  :global(html.dark) .theme-use-light-icon {
+    display: block;
+  }
+</style>

package/src/exceptions.ts

@@ -0,0 +1,21 @@
+import { Exception } from 'error-message-utils';
+
+// stable configuration failure contracts exposed by the package
+export type IWebsiteUiConfigurationErrorCode = 'INVALID_BASE_PATH' | 'INVALID_SEARCH_INDEX';
+
+const CONFIGURATION_ERROR_MESSAGES = {
+  INVALID_BASE_PATH: 'The website base path contains unsupported URL characters.',
+  INVALID_SEARCH_INDEX: 'The documentation search index is invalid.',
+} as const satisfies Readonly<Record<IWebsiteUiConfigurationErrorCode, string>>;
+
+/** Represents invalid configuration or generated input at a website UI boundary. */
+export class WebsiteUiConfigurationException extends Exception {
+  public override readonly code: IWebsiteUiConfigurationErrorCode;
+
+  /** Creates the stable configuration exception for one failed boundary. */
+  public constructor(code: IWebsiteUiConfigurationErrorCode) {
+    super(CONFIGURATION_ERROR_MESSAGES[code], code);
+    this.code = code;
+    this.name = 'WebsiteUiConfigurationException';
+  }
+}

package/src/search/index.ts

@@ -0,0 +1,118 @@
+import { WebsiteUiConfigurationException } from '../exceptions.js';
+
+// one base-aware public document delivered by a static search index
+export interface ISearchDocument {
+  description: string;
+  searchText: string;
+  title: string;
+  url: string;
+}
+
+const SEARCH_RESULT_LIMIT = 16;
+const SEARCH_URL_ORIGIN = 'https://website-ui.invalid';
+
+const normalizeSearchValue = (source: string): string =>
+  source
+    .normalize('NFKD')
+    .replaceAll(/\p{M}/gu, '')
+    .toLocaleLowerCase('en')
+    .replaceAll(/\s+/g, ' ')
+    .trim();
+
+const isSafeSearchUrl = (source: string): boolean => {
+  const hasUnsupportedCharacter = [...source].some((character) => {
+    const codePoint = character.codePointAt(0);
+
+    return character === '\\' || codePoint === undefined || codePoint <= 31 || codePoint === 127;
+  });
+
+  if (!source.startsWith('/') || source.startsWith('//') || hasUnsupportedCharacter) {
+    return false;
+  }
+
+  try {
+    return new URL(source, SEARCH_URL_ORIGIN).origin === SEARCH_URL_ORIGIN;
+  } catch {
+    return false;
+  }
+};
+
+const isSearchDocument = (source: unknown): source is ISearchDocument => {
+  if (!source || typeof source !== 'object') {
+    return false;
+  }
+
+  const candidate = source as Record<string, unknown>;
+
+  return (
+    typeof candidate['description'] === 'string' &&
+    typeof candidate['searchText'] === 'string' &&
+    typeof candidate['title'] === 'string' &&
+    typeof candidate['url'] === 'string' &&
+    isSafeSearchUrl(candidate['url'])
+  );
+};
+
+/**
+ * Validates the generated browser search-index boundary.
+ * @param source Unknown parsed search-index value.
+ * @returns Validated public search documents.
+ * @throws
+ * - INVALID_SEARCH_INDEX: The documentation search index is invalid.
+ */
+export const parseSearchDocuments = (source: unknown): ISearchDocument[] => {
+  if (!Array.isArray(source) || !source.every(isSearchDocument)) {
+    throw new WebsiteUiConfigurationException('INVALID_SEARCH_INDEX');
+  }
+
+  return source;
+};
+
+const getSearchScore = (query: string, tokens: string[], document: ISearchDocument): number => {
+  const title = normalizeSearchValue(document.title);
+  const description = normalizeSearchValue(document.description);
+  const searchText = normalizeSearchValue(document.searchText);
+  const completeText = `${title} ${description} ${searchText}`;
+
+  if (!tokens.every((token) => completeText.includes(token))) {
+    return -1;
+  }
+
+  let score = title === query ? 64 : title.startsWith(query) ? 32 : 0;
+
+  for (const token of tokens) {
+    if (title.includes(token)) score += 16;
+    if (description.includes(token)) score += 4;
+    if (searchText.includes(token)) score += 1;
+  }
+
+  return score;
+};
+
+/**
+ * Searches public documentation locally with deterministic relevance and ordering.
+ * @param query Developer-entered search query.
+ * @param documents Generated public search documents.
+ * @returns The highest-scoring matching documents.
+ */
+export const searchDocuments = (query: string, documents: ISearchDocument[]): ISearchDocument[] => {
+  const normalizedQuery = normalizeSearchValue(query);
+
+  if (!normalizedQuery) {
+    return [];
+  }
+
+  const tokens = [...new Set(normalizedQuery.split(' '))];
+
+  return documents
+    .map((document) => ({ document, score: getSearchScore(normalizedQuery, tokens, document) }))
+    .filter(({ score }) => score >= 0)
+    .sort(
+      (left, right) =>
+        right.score - left.score ||
+        left.document.title.localeCompare(right.document.title) ||
+        left.document.url.localeCompare(right.document.url),
+    )
+    .slice(0, SEARCH_RESULT_LIMIT)
+    .map(({ document }) => document);
+};

package/src/site/index.ts

@@ -0,0 +1,74 @@
+import { WebsiteUiConfigurationException } from '../exceptions.js';
+
+// default public base path used outside framework-owned configuration
+export const DEFAULT_BASE_PATH = '/';
+
+/**
+ * Returns one normalized root-relative base path with a trailing slash.
+ * @param basePath Candidate public base path.
+ * @returns The normalized public base path.
+ * @throws
+ * - INVALID_BASE_PATH: The website base path contains unsupported URL characters.
+ */
+export const normalizeBasePath = (basePath: string): string => {
+  const path = `/${basePath}`.replaceAll(/\/{2,}/g, '/');
+  const normalizedPath = path === '/' ? '/' : `${path.replace(/\/$/, '')}/`;
+
+  if (!/^\/(?:[a-zA-Z0-9._~-]+\/)*$/u.test(normalizedPath)) {
+    throw new WebsiteUiConfigurationException('INVALID_BASE_PATH');
+  }
+
+  return normalizedPath;
+};
+
+/**
+ * Prefixes one root-relative public route with the configured deployment base.
+ * @param route Root-relative public route.
+ * @param basePath Configured public base path.
+ * @returns The base-aware route.
+ * @throws
+ * - INVALID_BASE_PATH: The website base path contains unsupported URL characters.
+ */
+export const withBase = (route: string, basePath = DEFAULT_BASE_PATH): string => {
+  const base = normalizeBasePath(basePath);
+  const routeWithoutRoot = route.replace(/^\//, '');
+
+  return `${base}${routeWithoutRoot}`.replaceAll(/\/{2,}/g, '/');
+};
+
+/**
+ * Checks whether a public pathname identifies a route or one of its descendants.
+ * @param pathname Current public pathname.
+ * @param route Root-relative public route.
+ * @param basePath Configured public base path.
+ * @returns Whether the route is active for the current pathname.
+ * @throws
+ * - INVALID_BASE_PATH: The website base path contains unsupported URL characters.
+ */
+export const isPublicRouteActive = (
+  pathname: string,
+  route: string,
+  basePath = DEFAULT_BASE_PATH,
+): boolean => {
+  const publicRoute = withBase(route, basePath);
+
+  return publicRoute === normalizeBasePath(basePath)
+    ? pathname === publicRoute
+    : pathname.startsWith(publicRoute);
+};
+
+/**
+ * Builds a canonical absolute URL from an origin, base path, and public route.
+ * @param route Root-relative public route.
+ * @param siteUrl Public website origin.
+ * @param basePath Public deployment base path.
+ * @returns The canonical absolute URL.
+ * @throws
+ * - INVALID_BASE_PATH: The website base path contains unsupported URL characters.
+ */
+export const createCanonicalUrl = (route: string, siteUrl: string, basePath: string): string =>
+  new URL(withBase(route, basePath), siteUrl).href;
+
+// exceptions
+export { WebsiteUiConfigurationException } from '../exceptions.js';
+export type { IWebsiteUiConfigurationErrorCode } from '../exceptions.js';