@moldea.ai/website-ui 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 moldea.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+# `@moldea.ai/website-ui`
+
+Shared Astro foundations for moldea public websites.
+
+The package owns the reusable design tokens, global website primitives, interaction states, base-path and theme utilities, and small accessible Astro components used by the package and skill websites. Each website continues to own its page composition, navigation copy, content generation, SEO identity, public assets, site URL, and theme storage key.
+
+## Install after release
+
+```bash
+pnpm add @moldea.ai/website-ui@1.0.0
+```
+
+The package currently supports Astro `7.2.2` and Tailwind CSS `4.3.3` exactly. Import the shared stylesheet once from the website's global stylesheet:
+
+```css
+@import '@moldea.ai/website-ui/styles.css';
+```
+
+Tailwind scans the shipped Astro components through the package stylesheet's explicit source declaration.
+
+## Utilities
+
+```typescript
+import { searchDocuments } from '@moldea.ai/website-ui/search';
+import { withBase } from '@moldea.ai/website-ui/site';
+import { isDarkTheme } from '@moldea.ai/website-ui/theme';
+```
+
+`parseSearchDocuments` accepts only complete search records with safe root-relative result URLs. Base-path failures and invalid generated search indexes throw `WebsiteUiConfigurationException` with stable error codes.
+
+## Components
+
+Every component has a dedicated public subpath:
+
+- `@moldea.ai/website-ui/action-button`
+- `@moldea.ai/website-ui/action-link`
+- `@moldea.ai/website-ui/brand-logo`
+- `@moldea.ai/website-ui/breadcrumbs`
+- `@moldea.ai/website-ui/inline-brand-text`
+- `@moldea.ai/website-ui/local-search`
+- `@moldea.ai/website-ui/theme-bootstrap`
+- `@moldea.ai/website-ui/theme-control`
+
+`ThemeBootstrap` belongs in the document head before rendered content. Pass the same app-owned storage key to `ThemeControl`. `BrandLogo` receives app-owned asset paths and labels rather than embedding one site's identity. `LocalSearch` receives app-owned copy, routes, and the generated index URL.
+
+## Development
+
+From the monorepo root:
+
+```bash
+pnpm --filter @moldea.ai/website-ui typecheck
+pnpm --filter @moldea.ai/website-ui build
+pnpm --filter @moldea.ai/website-ui test:unit
+pnpm --filter @moldea.ai/website-ui test:integration
+pnpm --filter @moldea.ai/website-ui test
+```
+
+The integration suite verifies the packed public surface and a real Astro consumer fixture. Publishing the package is a separate release operation and is not part of ordinary website development.

package/dist/chunks/exceptions-BYCwx4kO.js

@@ -0,0 +1,20 @@
+import { Exception } from "error-message-utils";
+//#region src/exceptions.ts
+var CONFIGURATION_ERROR_MESSAGES = {
+	INVALID_BASE_PATH: "The website base path contains unsupported URL characters.",
+	INVALID_SEARCH_INDEX: "The documentation search index is invalid."
+};
+/** Represents invalid configuration or generated input at a website UI boundary. */
+var WebsiteUiConfigurationException = class extends Exception {
+	code;
+	/** Creates the stable configuration exception for one failed boundary. */
+	constructor(code) {
+		super(CONFIGURATION_ERROR_MESSAGES[code], code);
+		this.code = code;
+		this.name = "WebsiteUiConfigurationException";
+	}
+};
+//#endregion
+export { WebsiteUiConfigurationException as t };
+
+//# sourceMappingURL=exceptions-BYCwx4kO.js.map

package/dist/chunks/exceptions-BYCwx4kO.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions-BYCwx4kO.js","names":[],"sources":["../../src/exceptions.ts"],"sourcesContent":["import { Exception } from 'error-message-utils';\n\n// stable configuration failure contracts exposed by the package\nexport type IWebsiteUiConfigurationErrorCode = 'INVALID_BASE_PATH' | 'INVALID_SEARCH_INDEX';\n\nconst CONFIGURATION_ERROR_MESSAGES = {\n  INVALID_BASE_PATH: 'The website base path contains unsupported URL characters.',\n  INVALID_SEARCH_INDEX: 'The documentation search index is invalid.',\n} as const satisfies Readonly<Record<IWebsiteUiConfigurationErrorCode, string>>;\n\n/** Represents invalid configuration or generated input at a website UI boundary. */\nexport class WebsiteUiConfigurationException extends Exception {\n  public override readonly code: IWebsiteUiConfigurationErrorCode;\n\n  /** Creates the stable configuration exception for one failed boundary. */\n  public constructor(code: IWebsiteUiConfigurationErrorCode) {\n    super(CONFIGURATION_ERROR_MESSAGES[code], code);\n    this.code = code;\n    this.name = 'WebsiteUiConfigurationException';\n  }\n}\n"],"mappings":";;AAKA,IAAM,+BAA+B;CACnC,mBAAmB;CACnB,sBAAsB;AACxB;;AAGA,IAAa,kCAAb,cAAqD,UAAU;CAC7D;;CAGA,YAAmB,MAAwC;EACzD,MAAM,6BAA6B,OAAO,IAAI;EAC9C,KAAK,OAAO;EACZ,KAAK,OAAO;CACd;AACF"}

package/dist/exceptions.d.ts

@@ -0,0 +1,9 @@
+import { Exception } from 'error-message-utils';
+export type IWebsiteUiConfigurationErrorCode = 'INVALID_BASE_PATH' | 'INVALID_SEARCH_INDEX';
+/** Represents invalid configuration or generated input at a website UI boundary. */
+export declare class WebsiteUiConfigurationException extends Exception {
+    readonly code: IWebsiteUiConfigurationErrorCode;
+    /** Creates the stable configuration exception for one failed boundary. */
+    constructor(code: IWebsiteUiConfigurationErrorCode);
+}
+//# sourceMappingURL=exceptions.d.ts.map

package/dist/exceptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions.d.ts","sourceRoot":"","sources":["../src/exceptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAGhD,MAAM,MAAM,gCAAgC,GAAG,mBAAmB,GAAG,sBAAsB,CAAC;AAO5F,oFAAoF;AACpF,qBAAa,+BAAgC,SAAQ,SAAS;IAC5D,SAAyB,IAAI,EAAE,gCAAgC,CAAC;IAEhE,0EAA0E;gBACvD,IAAI,EAAE,gCAAgC;CAK1D"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { WebsiteUiConfigurationException } from './exceptions.js';
+export type { IWebsiteUiConfigurationErrorCode } from './exceptions.js';
+export { parseSearchDocuments, searchDocuments } from './search/index.js';
+export type { ISearchDocument } from './search/index.js';
+export { DEFAULT_BASE_PATH, createCanonicalUrl, isPublicRouteActive, normalizeBasePath, withBase, } from './site/index.js';
+export { isDarkTheme, parseThemePreference } from './theme/index.js';
+export type { IThemePreference } from './theme/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,+BAA+B,EAAE,MAAM,iBAAiB,CAAC;AAClE,YAAY,EAAE,gCAAgC,EAAE,MAAM,iBAAiB,CAAC;AAGxE,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC1E,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGzD,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,QAAQ,GACT,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACrE,YAAY,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+import { t as WebsiteUiConfigurationException } from "./chunks/exceptions-BYCwx4kO.js";
+import { parseSearchDocuments, searchDocuments } from "./search.js";
+import { DEFAULT_BASE_PATH, createCanonicalUrl, isPublicRouteActive, normalizeBasePath, withBase } from "./site.js";
+import { isDarkTheme, parseThemePreference } from "./theme.js";
+export { DEFAULT_BASE_PATH, WebsiteUiConfigurationException, createCanonicalUrl, isDarkTheme, isPublicRouteActive, normalizeBasePath, parseSearchDocuments, parseThemePreference, searchDocuments, withBase };

package/dist/search/index.d.ts

@@ -0,0 +1,22 @@
+export interface ISearchDocument {
+    description: string;
+    searchText: string;
+    title: string;
+    url: string;
+}
+/**
+ * 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 declare const parseSearchDocuments: (source: unknown) => ISearchDocument[];
+/**
+ * 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 declare const searchDocuments: (query: string, documents: ISearchDocument[]) => ISearchDocument[];
+//# sourceMappingURL=index.d.ts.map

package/dist/search/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/search/index.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AA+CD;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAAI,QAAQ,OAAO,KAAG,eAAe,EAMrE,CAAC;AAuBF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,EAAE,WAAW,eAAe,EAAE,KAAG,eAAe,EAoB5F,CAAC"}

package/dist/search.js

@@ -0,0 +1,66 @@
+import { t as WebsiteUiConfigurationException } from "./chunks/exceptions-BYCwx4kO.js";
+//#region src/search/index.ts
+var SEARCH_RESULT_LIMIT = 16;
+var SEARCH_URL_ORIGIN = "https://website-ui.invalid";
+var normalizeSearchValue = (source) => source.normalize("NFKD").replaceAll(/\p{M}/gu, "").toLocaleLowerCase("en").replaceAll(/\s+/g, " ").trim();
+var isSafeSearchUrl = (source) => {
+	const hasUnsupportedCharacter = [...source].some((character) => {
+		const codePoint = character.codePointAt(0);
+		return character === "\\" || codePoint === void 0 || 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;
+	}
+};
+var isSearchDocument = (source) => {
+	if (!source || typeof source !== "object") return false;
+	const candidate = source;
+	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.
+*/
+var parseSearchDocuments = (source) => {
+	if (!Array.isArray(source) || !source.every(isSearchDocument)) throw new WebsiteUiConfigurationException("INVALID_SEARCH_INDEX");
+	return source;
+};
+var getSearchScore = (query, tokens, document) => {
+	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.
+*/
+var searchDocuments = (query, documents) => {
+	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);
+};
+//#endregion
+export { parseSearchDocuments, searchDocuments };
+
+//# sourceMappingURL=search.js.map

package/dist/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","names":[],"sources":["../src/search/index.ts"],"sourcesContent":["import { WebsiteUiConfigurationException } from '../exceptions.js';\n\n// one base-aware public document delivered by a static search index\nexport interface ISearchDocument {\n  description: string;\n  searchText: string;\n  title: string;\n  url: string;\n}\n\nconst SEARCH_RESULT_LIMIT = 16;\nconst SEARCH_URL_ORIGIN = 'https://website-ui.invalid';\n\nconst normalizeSearchValue = (source: string): string =>\n  source\n    .normalize('NFKD')\n    .replaceAll(/\\p{M}/gu, '')\n    .toLocaleLowerCase('en')\n    .replaceAll(/\\s+/g, ' ')\n    .trim();\n\nconst isSafeSearchUrl = (source: string): boolean => {\n  const hasUnsupportedCharacter = [...source].some((character) => {\n    const codePoint = character.codePointAt(0);\n\n    return character === '\\\\' || codePoint === undefined || codePoint <= 31 || codePoint === 127;\n  });\n\n  if (!source.startsWith('/') || source.startsWith('//') || hasUnsupportedCharacter) {\n    return false;\n  }\n\n  try {\n    return new URL(source, SEARCH_URL_ORIGIN).origin === SEARCH_URL_ORIGIN;\n  } catch {\n    return false;\n  }\n};\n\nconst isSearchDocument = (source: unknown): source is ISearchDocument => {\n  if (!source || typeof source !== 'object') {\n    return false;\n  }\n\n  const candidate = source as Record<string, unknown>;\n\n  return (\n    typeof candidate['description'] === 'string' &&\n    typeof candidate['searchText'] === 'string' &&\n    typeof candidate['title'] === 'string' &&\n    typeof candidate['url'] === 'string' &&\n    isSafeSearchUrl(candidate['url'])\n  );\n};\n\n/**\n * Validates the generated browser search-index boundary.\n * @param source Unknown parsed search-index value.\n * @returns Validated public search documents.\n * @throws\n * - INVALID_SEARCH_INDEX: The documentation search index is invalid.\n */\nexport const parseSearchDocuments = (source: unknown): ISearchDocument[] => {\n  if (!Array.isArray(source) || !source.every(isSearchDocument)) {\n    throw new WebsiteUiConfigurationException('INVALID_SEARCH_INDEX');\n  }\n\n  return source;\n};\n\nconst getSearchScore = (query: string, tokens: string[], document: ISearchDocument): number => {\n  const title = normalizeSearchValue(document.title);\n  const description = normalizeSearchValue(document.description);\n  const searchText = normalizeSearchValue(document.searchText);\n  const completeText = `${title} ${description} ${searchText}`;\n\n  if (!tokens.every((token) => completeText.includes(token))) {\n    return -1;\n  }\n\n  let score = title === query ? 64 : title.startsWith(query) ? 32 : 0;\n\n  for (const token of tokens) {\n    if (title.includes(token)) score += 16;\n    if (description.includes(token)) score += 4;\n    if (searchText.includes(token)) score += 1;\n  }\n\n  return score;\n};\n\n/**\n * Searches public documentation locally with deterministic relevance and ordering.\n * @param query Developer-entered search query.\n * @param documents Generated public search documents.\n * @returns The highest-scoring matching documents.\n */\nexport const searchDocuments = (query: string, documents: ISearchDocument[]): ISearchDocument[] => {\n  const normalizedQuery = normalizeSearchValue(query);\n\n  if (!normalizedQuery) {\n    return [];\n  }\n\n  const tokens = [...new Set(normalizedQuery.split(' '))];\n\n  return documents\n    .map((document) => ({ document, score: getSearchScore(normalizedQuery, tokens, document) }))\n    .filter(({ score }) => score >= 0)\n    .sort(\n      (left, right) =>\n        right.score - left.score ||\n        left.document.title.localeCompare(right.document.title) ||\n        left.document.url.localeCompare(right.document.url),\n    )\n    .slice(0, SEARCH_RESULT_LIMIT)\n    .map(({ document }) => document);\n};\n"],"mappings":";;AAUA,IAAM,sBAAsB;AAC5B,IAAM,oBAAoB;AAE1B,IAAM,wBAAwB,WAC5B,OACG,UAAU,MAAM,CAAC,CACjB,WAAW,WAAW,EAAE,CAAC,CACzB,kBAAkB,IAAI,CAAC,CACvB,WAAW,QAAQ,GAAG,CAAC,CACvB,KAAK;AAEV,IAAM,mBAAmB,WAA4B;CACnD,MAAM,0BAA0B,CAAC,GAAG,MAAM,CAAC,CAAC,MAAM,cAAc;EAC9D,MAAM,YAAY,UAAU,YAAY,CAAC;EAEzC,OAAO,cAAc,QAAQ,cAAc,KAAA,KAAa,aAAa,MAAM,cAAc;CAC3F,CAAC;CAED,IAAI,CAAC,OAAO,WAAW,GAAG,KAAK,OAAO,WAAW,IAAI,KAAK,yBACxD,OAAO;CAGT,IAAI;EACF,OAAO,IAAI,IAAI,QAAQ,iBAAiB,CAAC,CAAC,WAAW;CACvD,QAAQ;EACN,OAAO;CACT;AACF;AAEA,IAAM,oBAAoB,WAA+C;CACvE,IAAI,CAAC,UAAU,OAAO,WAAW,UAC/B,OAAO;CAGT,MAAM,YAAY;CAElB,OACE,OAAO,UAAU,mBAAmB,YACpC,OAAO,UAAU,kBAAkB,YACnC,OAAO,UAAU,aAAa,YAC9B,OAAO,UAAU,WAAW,YAC5B,gBAAgB,UAAU,MAAM;AAEpC;;;;;;;;AASA,IAAa,wBAAwB,WAAuC;CAC1E,IAAI,CAAC,MAAM,QAAQ,MAAM,KAAK,CAAC,OAAO,MAAM,gBAAgB,GAC1D,MAAM,IAAI,gCAAgC,sBAAsB;CAGlE,OAAO;AACT;AAEA,IAAM,kBAAkB,OAAe,QAAkB,aAAsC;CAC7F,MAAM,QAAQ,qBAAqB,SAAS,KAAK;CACjD,MAAM,cAAc,qBAAqB,SAAS,WAAW;CAC7D,MAAM,aAAa,qBAAqB,SAAS,UAAU;CAC3D,MAAM,eAAe,GAAG,MAAM,GAAG,YAAY,GAAG;CAEhD,IAAI,CAAC,OAAO,OAAO,UAAU,aAAa,SAAS,KAAK,CAAC,GACvD,OAAO;CAGT,IAAI,QAAQ,UAAU,QAAQ,KAAK,MAAM,WAAW,KAAK,IAAI,KAAK;CAElE,KAAK,MAAM,SAAS,QAAQ;EAC1B,IAAI,MAAM,SAAS,KAAK,GAAG,SAAS;EACpC,IAAI,YAAY,SAAS,KAAK,GAAG,SAAS;EAC1C,IAAI,WAAW,SAAS,KAAK,GAAG,SAAS;CAC3C;CAEA,OAAO;AACT;;;;;;;AAQA,IAAa,mBAAmB,OAAe,cAAoD;CACjG,MAAM,kBAAkB,qBAAqB,KAAK;CAElD,IAAI,CAAC,iBACH,OAAO,CAAC;CAGV,MAAM,SAAS,CAAC,GAAG,IAAI,IAAI,gBAAgB,MAAM,GAAG,CAAC,CAAC;CAEtD,OAAO,UACJ,KAAK,cAAc;EAAE;EAAU,OAAO,eAAe,iBAAiB,QAAQ,QAAQ;CAAE,EAAE,CAAC,CAC3F,QAAQ,EAAE,YAAY,SAAS,CAAC,CAAC,CACjC,MACE,MAAM,UACL,MAAM,QAAQ,KAAK,SACnB,KAAK,SAAS,MAAM,cAAc,MAAM,SAAS,KAAK,KACtD,KAAK,SAAS,IAAI,cAAc,MAAM,SAAS,GAAG,CACtD,CAAC,CACA,MAAM,GAAG,mBAAmB,CAAC,CAC7B,KAAK,EAAE,eAAe,QAAQ;AACnC"}

package/dist/site/index.d.ts

@@ -0,0 +1,41 @@
+export declare 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 declare const normalizeBasePath: (basePath: string) => string;
+/**
+ * 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 declare const withBase: (route: string, basePath?: string) => string;
+/**
+ * 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 declare const isPublicRouteActive: (pathname: string, route: string, basePath?: string) => boolean;
+/**
+ * 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 declare const createCanonicalUrl: (route: string, siteUrl: string, basePath: string) => string;
+export { WebsiteUiConfigurationException } from '../exceptions.js';
+export type { IWebsiteUiConfigurationErrorCode } from '../exceptions.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/site/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/site/index.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,MAAM,KAAG,MASpD,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,MAAM,EAAE,iBAA4B,KAAG,MAKtE,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAC9B,UAAU,MAAM,EAChB,OAAO,MAAM,EACb,iBAA4B,KAC3B,OAMF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,EAAE,SAAS,MAAM,EAAE,UAAU,MAAM,KAAG,MACpC,CAAC;AAGnD,OAAO,EAAE,+BAA+B,EAAE,MAAM,kBAAkB,CAAC;AACnE,YAAY,EAAE,gCAAgC,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/site.js

@@ -0,0 +1,54 @@
+import { t as WebsiteUiConfigurationException } from "./chunks/exceptions-BYCwx4kO.js";
+//#region src/site/index.ts
+var 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.
+*/
+var normalizeBasePath = (basePath) => {
+	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.
+*/
+var withBase = (route, basePath = "/") => {
+	return `${normalizeBasePath(basePath)}${route.replace(/^\//, "")}`.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.
+*/
+var isPublicRouteActive = (pathname, route, basePath = "/") => {
+	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.
+*/
+var createCanonicalUrl = (route, siteUrl, basePath) => new URL(withBase(route, basePath), siteUrl).href;
+//#endregion
+export { DEFAULT_BASE_PATH, WebsiteUiConfigurationException, createCanonicalUrl, isPublicRouteActive, normalizeBasePath, withBase };
+
+//# sourceMappingURL=site.js.map

package/dist/site.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"site.js","names":[],"sources":["../src/site/index.ts"],"sourcesContent":["import { WebsiteUiConfigurationException } from '../exceptions.js';\n\n// default public base path used outside framework-owned configuration\nexport const DEFAULT_BASE_PATH = '/';\n\n/**\n * Returns one normalized root-relative base path with a trailing slash.\n * @param basePath Candidate public base path.\n * @returns The normalized public base path.\n * @throws\n * - INVALID_BASE_PATH: The website base path contains unsupported URL characters.\n */\nexport const normalizeBasePath = (basePath: string): string => {\n  const path = `/${basePath}`.replaceAll(/\\/{2,}/g, '/');\n  const normalizedPath = path === '/' ? '/' : `${path.replace(/\\/$/, '')}/`;\n\n  if (!/^\\/(?:[a-zA-Z0-9._~-]+\\/)*$/u.test(normalizedPath)) {\n    throw new WebsiteUiConfigurationException('INVALID_BASE_PATH');\n  }\n\n  return normalizedPath;\n};\n\n/**\n * Prefixes one root-relative public route with the configured deployment base.\n * @param route Root-relative public route.\n * @param basePath Configured public base path.\n * @returns The base-aware route.\n * @throws\n * - INVALID_BASE_PATH: The website base path contains unsupported URL characters.\n */\nexport const withBase = (route: string, basePath = DEFAULT_BASE_PATH): string => {\n  const base = normalizeBasePath(basePath);\n  const routeWithoutRoot = route.replace(/^\\//, '');\n\n  return `${base}${routeWithoutRoot}`.replaceAll(/\\/{2,}/g, '/');\n};\n\n/**\n * Checks whether a public pathname identifies a route or one of its descendants.\n * @param pathname Current public pathname.\n * @param route Root-relative public route.\n * @param basePath Configured public base path.\n * @returns Whether the route is active for the current pathname.\n * @throws\n * - INVALID_BASE_PATH: The website base path contains unsupported URL characters.\n */\nexport const isPublicRouteActive = (\n  pathname: string,\n  route: string,\n  basePath = DEFAULT_BASE_PATH,\n): boolean => {\n  const publicRoute = withBase(route, basePath);\n\n  return publicRoute === normalizeBasePath(basePath)\n    ? pathname === publicRoute\n    : pathname.startsWith(publicRoute);\n};\n\n/**\n * Builds a canonical absolute URL from an origin, base path, and public route.\n * @param route Root-relative public route.\n * @param siteUrl Public website origin.\n * @param basePath Public deployment base path.\n * @returns The canonical absolute URL.\n * @throws\n * - INVALID_BASE_PATH: The website base path contains unsupported URL characters.\n */\nexport const createCanonicalUrl = (route: string, siteUrl: string, basePath: string): string =>\n  new URL(withBase(route, basePath), siteUrl).href;\n\n// exceptions\nexport { WebsiteUiConfigurationException } from '../exceptions.js';\nexport type { IWebsiteUiConfigurationErrorCode } from '../exceptions.js';\n"],"mappings":";;AAGA,IAAa,oBAAoB;;;;;;;;AASjC,IAAa,qBAAqB,aAA6B;CAC7D,MAAM,OAAO,IAAI,WAAW,WAAW,WAAW,GAAG;CACrD,MAAM,iBAAiB,SAAS,MAAM,MAAM,GAAG,KAAK,QAAQ,OAAO,EAAE,EAAE;CAEvE,IAAI,CAAC,+BAA+B,KAAK,cAAc,GACrD,MAAM,IAAI,gCAAgC,mBAAmB;CAG/D,OAAO;AACT;;;;;;;;;AAUA,IAAa,YAAY,OAAe,WAAA,QAAyC;CAI/E,OAAO,GAHM,kBAAkB,QAGrB,IAFe,MAAM,QAAQ,OAAO,EAE7B,IAAmB,WAAW,WAAW,GAAG;AAC/D;;;;;;;;;;AAWA,IAAa,uBACX,UACA,OACA,WAAA,QACY;CACZ,MAAM,cAAc,SAAS,OAAO,QAAQ;CAE5C,OAAO,gBAAgB,kBAAkB,QAAQ,IAC7C,aAAa,cACb,SAAS,WAAW,WAAW;AACrC;;;;;;;;;;AAWA,IAAa,sBAAsB,OAAe,SAAiB,aACjE,IAAI,IAAI,SAAS,OAAO,QAAQ,GAAG,OAAO,CAAC,CAAC"}

package/dist/theme/index.d.ts

@@ -0,0 +1,15 @@
+export type IThemePreference = 'dark' | 'light' | 'system';
+/**
+ * Normalizes an unknown persisted preference to a supported theme choice.
+ * @param value Persisted storage value.
+ * @returns A supported explicit or system preference.
+ */
+export declare const parseThemePreference: (value: unknown) => IThemePreference;
+/**
+ * Resolves whether the effective theme should be dark.
+ * @param preference Explicit or system theme preference.
+ * @param doesSystemPreferDark Current operating-system preference.
+ * @returns Whether the effective website theme is dark.
+ */
+export declare const isDarkTheme: (preference: IThemePreference, doesSystemPreferDark: boolean) => boolean;
+//# sourceMappingURL=index.d.ts.map

package/dist/theme/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/theme/index.ts"],"names":[],"mappings":"AACA,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE3D;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAI,OAAO,OAAO,KAAG,gBAC0B,CAAC;AAEjF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,YAAY,gBAAgB,EAAE,sBAAsB,OAAO,KAAG,OACd,CAAC"}

package/dist/theme.js

@@ -0,0 +1,18 @@
+//#region src/theme/index.ts
+/**
+* Normalizes an unknown persisted preference to a supported theme choice.
+* @param value Persisted storage value.
+* @returns A supported explicit or system preference.
+*/
+var parseThemePreference = (value) => value === "dark" || value === "light" || value === "system" ? value : "system";
+/**
+* Resolves whether the effective theme should be dark.
+* @param preference Explicit or system theme preference.
+* @param doesSystemPreferDark Current operating-system preference.
+* @returns Whether the effective website theme is dark.
+*/
+var isDarkTheme = (preference, doesSystemPreferDark) => preference === "dark" || preference === "system" && doesSystemPreferDark;
+//#endregion
+export { isDarkTheme, parseThemePreference };
+
+//# sourceMappingURL=theme.js.map

package/dist/theme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.js","names":[],"sources":["../src/theme/index.ts"],"sourcesContent":["// persisted website theme choices\nexport type IThemePreference = 'dark' | 'light' | 'system';\n\n/**\n * Normalizes an unknown persisted preference to a supported theme choice.\n * @param value Persisted storage value.\n * @returns A supported explicit or system preference.\n */\nexport const parseThemePreference = (value: unknown): IThemePreference =>\n  value === 'dark' || value === 'light' || value === 'system' ? value : 'system';\n\n/**\n * Resolves whether the effective theme should be dark.\n * @param preference Explicit or system theme preference.\n * @param doesSystemPreferDark Current operating-system preference.\n * @returns Whether the effective website theme is dark.\n */\nexport const isDarkTheme = (preference: IThemePreference, doesSystemPreferDark: boolean): boolean =>\n  preference === 'dark' || (preference === 'system' && doesSystemPreferDark);\n"],"mappings":";;;;;;AAQA,IAAa,wBAAwB,UACnC,UAAU,UAAU,UAAU,WAAW,UAAU,WAAW,QAAQ;;;;;;;AAQxE,IAAa,eAAe,YAA8B,yBACxD,eAAe,UAAW,eAAe,YAAY"}

package/package.json

@@ -0,0 +1,118 @@
+{
+  "name": "@moldea.ai/website-ui",
+  "version": "1.0.0",
+  "description": "Shared Astro foundations for moldea public websites.",
+  "homepage": "https://github.com/moldea-ai/packages/tree/main/projects/website-ui#readme",
+  "bugs": {
+    "url": "https://github.com/moldea-ai/packages/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moldea-ai/packages.git",
+    "directory": "projects/website-ui"
+  },
+  "license": "MIT",
+  "author": "Jesus Graterol",
+  "type": "module",
+  "sideEffects": [
+    "./src/**/*.astro",
+    "./src/**/*.css"
+  ],
+  "files": [
+    "cover.png",
+    "dist",
+    "src/**/*.astro",
+    "src/**/*.css",
+    "src/exceptions.ts",
+    "src/search/index.ts",
+    "src/site/index.ts",
+    "src/theme/index.ts",
+    "LICENSE",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./site": {
+      "types": "./dist/site/index.d.ts",
+      "import": "./dist/site.js"
+    },
+    "./search": {
+      "types": "./dist/search/index.d.ts",
+      "import": "./dist/search.js"
+    },
+    "./theme": {
+      "types": "./dist/theme/index.d.ts",
+      "import": "./dist/theme.js"
+    },
+    "./action-button": {
+      "import": "./src/components/action-button/action-button.component.astro"
+    },
+    "./action-link": {
+      "import": "./src/components/action-link/action-link.component.astro"
+    },
+    "./brand-logo": {
+      "import": "./src/components/brand-logo/brand-logo.component.astro"
+    },
+    "./breadcrumbs": {
+      "import": "./src/components/breadcrumbs/breadcrumbs.component.astro"
+    },
+    "./inline-brand-text": {
+      "import": "./src/components/inline-brand-text/inline-brand-text.component.astro"
+    },
+    "./local-search": {
+      "import": "./src/components/local-search/local-search.component.astro"
+    },
+    "./theme-bootstrap": {
+      "import": "./src/components/theme-bootstrap/theme-bootstrap.component.astro"
+    },
+    "./theme-control": {
+      "import": "./src/components/theme-control/theme-control.component.astro"
+    },
+    "./styles.css": {
+      "style": "./src/styles.css",
+      "default": "./src/styles.css"
+    },
+    "./tokens.css": {
+      "style": "./src/tokens.css",
+      "default": "./src/tokens.css"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "@fontsource-variable/ubuntu-sans": "5.2.10",
+    "@lucide/astro": "1.31.0",
+    "error-message-utils": "1.2.11"
+  },
+  "peerDependencies": {
+    "astro": "7.2.2",
+    "tailwindcss": "4.3.3"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.1",
+    "astro": "7.2.2",
+    "tailwindcss": "4.3.3",
+    "typescript": "6.0.3",
+    "vite": "8.2.1",
+    "vitest": "4.1.10",
+    "web-utils-kit": "1.3.1"
+  },
+  "engines": {
+    "node": "^24.15.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vite build --emptyOutDir && tsc -p tsconfig.build.json",
+    "dev": "vite build --watch",
+    "lint": "eslint src vite.config.ts vitest",
+    "test": "pnpm run test:unit && pnpm run test:integration",
+    "test:integration": "pnpm run build && vitest run --config vitest/test-integration.config.ts",
+    "test:unit": "vitest run --config vitest/test-unit.config.ts",
+    "typecheck": "tsc -p tsconfig.src.json --noEmit && tsc -p tsconfig.json --noEmit"
+  }
+}

package/src/components/action-button/action-button.component.astro

@@ -0,0 +1,25 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+export interface Props extends Omit<HTMLAttributes<'button'>, 'class'> {
+  class?: string;
+  size?: 'icon' | 'lg' | 'md' | 'sm';
+  variant?: 'ghost' | 'link' | 'outline' | 'primary' | 'secondary';
+}
+
+const {
+  class: className,
+  size = 'md',
+  type = 'button',
+  variant = 'primary',
+  ...attributes
+} = Astro.props;
+---
+
+<button
+  class:list={['action-control', `action-${variant}`, `action-size-${size}`, className]}
+  {type}
+  {...attributes}
+>
+  <slot />
+</button>

package/src/components/action-link/action-link.component.astro

@@ -0,0 +1,18 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+export interface Props extends Omit<HTMLAttributes<'a'>, 'class'> {
+  class?: string;
+  size?: 'icon' | 'lg' | 'md' | 'sm';
+  variant?: 'ghost' | 'link' | 'outline' | 'primary' | 'secondary';
+}
+
+const { class: className, size = 'md', variant = 'primary', ...attributes } = Astro.props;
+---
+
+<a
+  class:list={['action-control', `action-${variant}`, `action-size-${size}`, className]}
+  {...attributes}
+>
+  <slot />
+</a>

package/src/components/brand-logo/brand-logo.component.astro

@@ -0,0 +1,55 @@
+---
+import { withBase } from '../../site/index.ts';
+
+export interface Props {
+  basePath?: string;
+  compact?: boolean;
+  darkCompactLogoPath: string;
+  darkLogoPath: string;
+  homeLabel: string;
+  lightCompactLogoPath: string;
+  lightLogoPath: string;
+  suffix?: string;
+}
+
+const {
+  basePath = import.meta.env.BASE_URL,
+  compact = false,
+  darkCompactLogoPath,
+  darkLogoPath,
+  homeLabel,
+  lightCompactLogoPath,
+  lightLogoPath,
+  suffix,
+} = Astro.props;
+const darkAssetPath = compact ? darkCompactLogoPath : darkLogoPath;
+const lightAssetPath = compact ? lightCompactLogoPath : lightLogoPath;
+---
+
+<a
+  class="inline-flex min-w-0 items-center gap-3 rounded-md"
+  href={withBase('/', basePath)}
+  aria-label={homeLabel}
+>
+  <img
+    class="hidden h-8 w-auto dark:block"
+    src={withBase(darkAssetPath, basePath)}
+    width={compact ? 185 : 942}
+    height="210"
+    alt=""
+  />
+  <img
+    class="h-8 w-auto dark:hidden"
+    src={withBase(lightAssetPath, basePath)}
+    width={compact ? 185 : 942}
+    height="210"
+    alt=""
+  />
+  {
+    suffix && (
+      <span class="inline border-s border-border ps-3 text-xs font-semibold text-muted-foreground">
+        {suffix}
+      </span>
+    )
+  }
+</a>