blume 0.2.0 → 0.3.0

package/src/registry/registry.ts

@@ -62,6 +62,165 @@ const layoutComponent = (config: {
   };
 };
 
+/**
+ * A built-in MDX content component offered as editable source. Like
+ * {@link layoutComponent}, but registered under the `mdx` map (the tag you write
+ * in `.mdx`) rather than a `layout` slot.
+ */
+const contentComponent = (config: {
+  name: string;
+  description: string;
+  /** Source basename under `src/components/content`. */
+  file: string;
+  /** MDX tag / component name, also the import name in the post-install hint. */
+  tag: string;
+}): RegistryItem => {
+  const target = `components/blume/${config.file}`;
+  return {
+    description: config.description,
+    files: [
+      {
+        rewrite: true,
+        source: `components/content/${config.file}`,
+        target,
+      },
+    ],
+    name: config.name,
+    postInstall: [
+      "Register it in components.ts:",
+      '  import { defineComponents } from "blume";',
+      `  import ${config.tag} from "./${target}";`,
+      "",
+      `  export default defineComponents({ mdx: { ${config.tag} } });`,
+      "",
+      "It imports the rest from `blume/*`, so it matches the built-in until you edit it.",
+    ],
+  };
+};
+
+/** Every user-facing content component, by `blume add` name → source basename. */
+const CONTENT_COMPONENTS: {
+  name: string;
+  description: string;
+  file: string;
+  tag: string;
+}[] = [
+  {
+    description: "Aside for notes, tips, and warnings.",
+    file: "Callout.astro",
+    name: "callout",
+    tag: "Callout",
+  },
+  {
+    description: "A linkable card with icon, title, and body.",
+    file: "Card.astro",
+    name: "card",
+    tag: "Card",
+  },
+  {
+    description: "A responsive grid of cards.",
+    file: "CardGroup.astro",
+    name: "card-group",
+    tag: "CardGroup",
+  },
+  {
+    description: "Tabbed code blocks for multiple languages.",
+    file: "CodeGroup.astro",
+    name: "code-group",
+    tag: "CodeGroup",
+  },
+  {
+    description: "A small status/label badge.",
+    file: "Badge.astro",
+    name: "badge",
+    tag: "Badge",
+  },
+  {
+    description: "A numbered list of steps.",
+    file: "Steps.astro",
+    name: "steps",
+    tag: "Steps",
+  },
+  {
+    description: "A single step within Steps.",
+    file: "Step.astro",
+    name: "step",
+    tag: "Step",
+  },
+  {
+    description: "A tabbed content panel.",
+    file: "Tabs.astro",
+    name: "tabs",
+    tag: "Tabs",
+  },
+  {
+    description: "A single tab within Tabs.",
+    file: "Tab.astro",
+    name: "tab",
+    tag: "Tab",
+  },
+  {
+    description: "A collapsible accordion group.",
+    file: "Accordion.astro",
+    name: "accordion",
+    tag: "Accordion",
+  },
+  {
+    description: "A single item within an Accordion.",
+    file: "AccordionItem.astro",
+    name: "accordion-item",
+    tag: "AccordionItem",
+  },
+  {
+    description: "A multi-column layout.",
+    file: "Columns.astro",
+    name: "columns",
+    tag: "Columns",
+  },
+  {
+    description: "A single column within Columns.",
+    file: "Column.astro",
+    name: "column",
+    tag: "Column",
+  },
+  {
+    description: "A bordered frame around an image or embed.",
+    file: "Frame.astro",
+    name: "frame",
+    tag: "Frame",
+  },
+  {
+    description: "An inline expand/collapse disclosure.",
+    file: "Expandable.astro",
+    name: "expandable",
+    tag: "Expandable",
+  },
+  {
+    description: "A titled content panel.",
+    file: "Panel.astro",
+    name: "panel",
+    tag: "Panel",
+  },
+  {
+    description: "A hover tooltip.",
+    file: "Tooltip.astro",
+    name: "tooltip",
+    tag: "Tooltip",
+  },
+  {
+    description: "A compact linkable tile.",
+    file: "Tile.astro",
+    name: "tile",
+    tag: "Tile",
+  },
+  {
+    description: "A styled prompt / terminal block.",
+    file: "Prompt.astro",
+    name: "prompt",
+    tag: "Prompt",
+  },
+];
+
 /** The built-in, Blume-owned source registry. */
 export const registry: RegistryItem[] = [
   layoutComponent({
@@ -94,6 +253,13 @@ export const registry: RegistryItem[] = [
     name: "pagination",
     slot: "Pagination",
   }),
+  layoutComponent({
+    description: 'The "Was this page helpful?" feedback rating.',
+    file: "PageFeedback.astro",
+    name: "feedback",
+    slot: "Feedback",
+  }),
+  ...CONTENT_COMPONENTS.map(contentComponent),
 ];
 
 export const findItem = (name: string): RegistryItem | undefined =>

package/src/runtime/index.ts

@@ -5,6 +5,14 @@
  * (config, navigation, page collections) without reaching into generated
  * runtime internals. The surface grows with the customization milestone.
  */
+import type { BlumeData, BlumeRoute } from "../core/data.ts";
+
+export type {
+  BlumeData,
+  BlumeDataConfig,
+  BlumeFeed,
+  BlumeRoute,
+} from "../core/data.ts";
 export type {
   Heading,
   NavNode,
@@ -12,3 +20,56 @@ export type {
   NavTab,
   PageRecord,
 } from "../core/types.ts";
+
+/** Query for {@link getBlumeCollection}. */
+export interface BlumeCollectionQuery {
+  /** Astro collection to read from. Defaults to `"docs"`. */
+  collection?: string;
+  /** Include drafts, hidden pages, and translation fallbacks. Default `false`. */
+  includeHidden?: boolean;
+  /** Restrict to a locale code (matches `route.locale`). */
+  locale?: string;
+  /** Restrict to routes whose path starts with this prefix, e.g. `"/blog"`. */
+  prefix?: string;
+}
+
+/**
+ * Select content routes from the `blume:data` snapshot — for building custom
+ * index pages, listings, or feeds without touching generated internals. Pass the
+ * imported `data` and an optional query; results are sorted by path.
+ *
+ * ```astro
+ * ---
+ * import data from "blume:data";
+ * import { getBlumeCollection } from "blume/runtime";
+ * const posts = getBlumeCollection(data, { prefix: "/blog" });
+ * ---
+ * <ul>{posts.map((p) => <li><a href={p.path}>{p.title}</a></li>)}</ul>
+ * ```
+ */
+export const getBlumeCollection = (
+  data: BlumeData,
+  query: BlumeCollectionQuery = {}
+): BlumeRoute[] => {
+  const collection = query.collection ?? "docs";
+  return data.routes
+    .filter((route) => {
+      if (route.collection !== collection) {
+        return false;
+      }
+      if (query.locale && route.locale !== query.locale) {
+        return false;
+      }
+      if (query.prefix && !route.path.startsWith(query.prefix)) {
+        return false;
+      }
+      if (
+        !query.includeHidden &&
+        (route.draft || route.hidden || route.fallback)
+      ) {
+        return false;
+      }
+      return true;
+    })
+    .toSorted((a, b) => a.path.localeCompare(b.path));
+};

package/src/vite-env.d.ts

@@ -0,0 +1,14 @@
+// Ambient types for the Vite `import.meta.env` fields Blume's client islands read
+// (`.astro` files aren't typechecked, so only real `.ts`/`.tsx` sources need this).
+interface ImportMetaEnv {
+  /** Deployment base path, always with a trailing slash (e.g. `/` or `/docs/`). */
+  readonly BASE_URL: string;
+  readonly DEV: boolean;
+  readonly MODE: string;
+  readonly PROD: boolean;
+  readonly SSR: boolean;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}