@getvitops/astro 1.0.0 → 2.1.0

package/src/components/Icon.astro

@@ -0,0 +1,94 @@
+---
+/**
+ * One icon, resolved through the site's semantic map.
+ *
+ * `name` is a semantic name ('menu', 'chevron-down') that resolves per the
+ * configured set, OR a fully-qualified `prefix:name` which passes straight
+ * through — that is the escape hatch for a glyph the map doesn't cover.
+ *
+ * **Why this doesn't use astro-icon.** It can't. astro-icon's `./components`
+ * entry is a TypeScript file that Vite has to transform, so it is only reachable
+ * through a statically-analysable import — and a *static* import is precisely
+ * what made the optional peer mandatory for anyone rendering Popover, Details or
+ * Drawer, which is the bug this component exists to fix. A dynamic
+ * `import(/* @vite-ignore *\/ …)` compiles nothing and hands Node raw TS, which
+ * fails silently and renders an empty box. So the glyph is read straight out of
+ * the `@iconify-json/*` collection instead — the same loader the sprite emitter
+ * uses, so both delivery paths draw the identical icon and neither needs a peer.
+ *
+ * Two other things worth knowing:
+ *
+ * - **An unresolvable name warns, it doesn't throw.** A missing glyph must never
+ *   500 an SSR page; the box renders empty and the build log says which name.
+ *   `vitops icons` is the place that fails hard.
+ * - **`.icon` already does the layout.** It's an inline-flex box sized in `em`
+ *   (`--icon-size`) that stretches its `<svg>` child and sets `fill:
+ *   currentColor`. So a start/end adornment on `.cta`/`.btn` — both already
+ *   `inline-flex` with a `gap` — is a matter of child order, not a new class.
+ *   Don't confuse this with `.icon-mask`, the CSS-only adornment path (see
+ *   `.link--icon::before` in anchor-link.css).
+ */
+import { loadIconSvg, spriteId } from '@getvitops/generator';
+import { resolveIcon } from '@getvitops/utils';
+import icons from 'virtual:getvitops/icons';
+
+interface Props {
+  /** Semantic name ('menu') or fully-qualified ('ph:list'). */
+  name: string;
+  /** Resolve against the brand set rather than the UI set. */
+  brand?: boolean;
+  /** Any CSS length; sets `--icon-size`. Defaults to the framework's 1.25em. */
+  size?: string;
+  /**
+   * Accessible name. Omit for decorative icons — the default — which are then
+   * `aria-hidden`. An icon that carries meaning on its own needs this.
+   */
+  label?: string;
+  class?: string;
+}
+
+const { name, brand = false, size, label, class: className } = Astro.props;
+
+const set = brand ? icons.brand : icons.ui;
+const aliased = icons.overrides[name] ?? name;
+
+let qualified: string | null = null;
+try {
+  qualified = resolveIcon(aliased, set, { weight: icons.weight ?? undefined });
+} catch {
+  // A bare name that isn't in the map is legitimate — a sprite id, or a local
+  // SVG — so fall through with what we were given rather than giving up.
+  qualified = aliased.includes(':') ? aliased : null;
+}
+
+let svg: { viewBox: string; body: string } | null = null;
+if (icons.engine === 'inline' && qualified) {
+  // resolveFrom is the project root, not process.cwd() — see IconsData.root.
+  svg = await loadIconSvg(qualified, { resolveFrom: icons.root });
+  if (!svg)
+    console.warn(
+      `[getvitops] <Icon name="${name}"> — "${qualified}" not found. Is ` +
+        `@iconify-json/${qualified.slice(0, qualified.indexOf(':'))} installed?`,
+    );
+} else if (icons.engine === 'none') {
+  console.warn(
+    `[getvitops] <Icon name="${name}"> rendered but icons are not configured. ` +
+      'Add `icons: true` to getvitops() in astro.config.',
+  );
+}
+
+const a11y = label ? { role: 'img', 'aria-label': label } : { 'aria-hidden': 'true' };
+const style = size ? `--icon-size:${size}` : undefined;
+---
+
+<span class:list={['icon', className]} style={style} {...a11y}>
+  {
+    svg ? (
+      <svg viewBox={svg.viewBox} set:html={svg.body} />
+    ) : icons.engine === 'sprite' && icons.sprite && qualified ? (
+      <svg>
+        <use href={`${icons.sprite}#${spriteId(qualified)}`} />
+      </svg>
+    ) : null
+  }
+</span>

package/src/components/Popover.astro

@@ -1,5 +1,5 @@
 ---
-import { Icon } from 'astro-icon/components';
+import Icon from './Icon.astro';
 
 interface Props {
   id: string;
@@ -14,8 +14,14 @@ interface Props {
   class?: string;
   anchorName?: string;
   positionArea?: string;
-  /** Resolve semantic icon names to fully-qualified astro-icon names.
-   *  Defaults to pass-through (expects already-qualified names like 'fa7-solid:bars'). */
+  /**
+   * Map a semantic name onto a fully-qualified one before rendering.
+   *
+   * @deprecated The `icons` option on `getvitops()` now does this centrally, so
+   * the site's set is configured once instead of threaded through every call
+   * site. Left in place because removing it would break consumers passing one;
+   * when omitted, `<Icon />` resolves through the site config.
+   */
   iconResolver?: (name: string) => string;
 }
 

package/src/seo.ts

@@ -32,6 +32,11 @@ export interface GetvitopsSeoOptions {
   /**
    * Page-title pattern; `%s` is the page's own title. e.g. `'%s · Acme'`.
    *
+   * Applies to `<title>` only. `og:title`/`twitter:title` get the untemplated
+   * title: a social card already shows `og:site_name` and the domain, so the
+   * suffix would sit directly above the brand it repeats. Override per page with
+   * `ogTitle`.
+   *
    * Skipped when a page's title already equals `siteName` — a homepage titled
    * "Acme" emits `Acme`, not `Acme · Acme` — and never applied to `defaultTitle`.
    */
@@ -70,6 +75,12 @@ export interface GetvitopsSeoOptions {
 export interface SeoProps {
   /** Page title, before `titleTemplate` is applied. */
   title?: string;
+  /**
+   * `og:title`/`twitter:title`, when the social headline should differ from
+   * `title`. Defaults to `title` **without** `titleTemplate` — see the note on
+   * `titleTemplate` for why the suffix is dropped there.
+   */
+  ogTitle?: string;
   description?: string;
   /** Overrides the computed canonical. Relative values resolve against `site`. */
   canonical?: string;
@@ -132,6 +143,8 @@ export interface SeoNameTag {
 /** Everything `<Seo />` renders, already decided. `null` means "emit nothing". */
 export interface ResolvedSeo {
   title: string | null;
+  /** `og:title`/`twitter:title` — the page title without `titleTemplate`. */
+  socialTitle: string | null;
   description: string | null;
   canonical: string | null;
   robots: string | null;
@@ -214,11 +227,27 @@ export function resolveSeo(
   // it over `defaultTitle`, and a homepage whose own title happens to equal the
   // site name — which is the common case, not an edge case.
   const templated = props.title && defaults.titleTemplate && props.title !== siteName;
+  const fallbackTitle = defaults.defaultTitle ?? siteName;
   const title = props.title
     ? templated
       ? String(defaults.titleTemplate).replaceAll('%s', props.title)
       : props.title
-    : (defaults.defaultTitle ?? siteName);
+    : fallbackTitle;
+
+  /*
+   * `og:title`/`twitter:title` take the page's title *without* the template.
+   *
+   * The two are read in different places. `<title>` is navigational — a browser
+   * tab or a search result, competing with a dozen others, so it needs the brand
+   * suffix to disambiguate. A social card is self-contained and already shows
+   * `og:site_name` and the domain, so repeating the brand there is furniture:
+   * "Installation · Acme" sitting directly above "Acme".
+   *
+   * They still derive from one value, which is the part that matters — the
+   * component this replaces computed them in separate places and they drifted.
+   * Pass `ogTitle` when a page wants a genuinely different social headline.
+   */
+  const socialTitle = props.ogTitle ?? props.title ?? fallbackTitle;
 
   const description = props.description ?? defaults.defaultDescription ?? null;
 
@@ -248,7 +277,7 @@ export function resolveSeo(
   };
 
   og('og:type', type);
-  og('og:title', title);
+  og('og:title', socialTitle);
   og('og:description', description);
   og('og:url', canonical);
   og('og:site_name', siteName);
@@ -280,7 +309,7 @@ export function resolveSeo(
   tw('twitter:card', image ? 'summary_large_image' : (defaults.twitter?.card ?? 'summary'));
   tw('twitter:site', defaults.twitter?.site);
   tw('twitter:creator', props.twitterCreator ?? defaults.twitter?.creator);
-  tw('twitter:title', title);
+  tw('twitter:title', socialTitle);
   tw('twitter:description', description);
   tw('twitter:image', image);
   tw('twitter:image:alt', image ? imageAlt : null);
@@ -296,6 +325,7 @@ export function resolveSeo(
 
   return {
     title,
+    socialTitle,
     description,
     canonical,
     robots: resolveRobots(props, defaults),

package/virtual.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Astro generates the real types for `astro:env/*` into a consumer's
+ * `.astro/` on `astro sync`, which never runs for this package — so the
+ * import typechecks nowhere but a consumer project. Declared here at the
+ * shape `plan-features.ts` actually uses; the runtime value comes from
+ * Astro's env schema, and this file cannot import it.
+ */
+declare module 'astro:env/server' {
+  export const SITE_PLAN: string | undefined;
+}
+
 /** Types for the virtual module the getvitops() integration provides to <Head />. */
 declare module 'virtual:getvitops/head' {
   interface FaviconLink {
@@ -6,6 +17,11 @@ declare module 'virtual:getvitops/head' {
     type?: string;
     sizes?: string;
   }
+  /** Mirrors `HeadFont` in src/fonts.ts. `preload` is Astro's `PreloadFilter`. */
+  interface HeadFont {
+    cssVariable: string;
+    preload: boolean | { weight?: string | number; style?: string }[];
+  }
   // Keep these keys in step with `HeadData` in src/integration.ts — the two are
   // hand-duplicated (an ambient `declare module` in a shipped .d.ts cannot import
   // from src), and `head.test.ts` asserts the key sets match.
@@ -17,12 +33,45 @@ declare module 'virtual:getvitops/head' {
     wcBase: string;
     editor: boolean;
     sitemap: string | null;
+    /** Families registered by `getvitops({ fonts })`, for `<Font />`. */
+    fonts: HeadFont[];
     site: string | null;
     // Structurally `GetvitopsSeoOptions` (src/seo.ts). Left loose here because
     // this file can't import from src, and <Seo /> re-types it on the way into
     // `resolveSeo`, which is where the real contract is enforced.
     seo: Record<string, unknown>;
+    // Likewise `GetvitopsAnalyticsOptions` (src/analytics.ts) — re-typed by
+    // <Analytics /> on the way into `resolveAnalytics`.
+    analytics: Record<string, unknown>;
+    consent: boolean;
+    consentCategories: string[];
+    consentPolicyUrl: string | null;
+    consentRuntime: boolean;
   }
   const data: HeadData;
   export default data;
 }
+
+/** Types for the virtual module the getvitops() integration provides to <Icon />. */
+declare module 'virtual:getvitops/icons' {
+  // Keep these keys in step with `IconsData` in src/integration.ts, for the same
+  // reason as HeadData above; `icons.test.ts` asserts the key sets match.
+  //
+  // Note what is NOT here: a resolver function. The module is JSON.stringify'd,
+  // so only data crosses. <Icon /> imports the pure `resolveIcon` from
+  // @getvitops/utils and feeds it these values.
+  interface IconsData {
+    engine: 'inline' | 'sprite' | 'none';
+    /** Absolute project root — where `@iconify-json/*` is resolved from. */
+    root: string;
+    ui: string;
+    brand: string;
+    weight: string | null;
+    /** Consumer aliases applied before the semantic map (legacy names, content values). */
+    overrides: Record<string, string>;
+    /** Public href of the sprite, or null when none is emitted. */
+    sprite: string | null;
+  }
+  const data: IconsData;
+  export default data;
+}