Registry Metadata

Astromer 的元件 API 不應只存在於 .astro 檔案裡。給 Astrologistic 這種 consumer 使用時，還需要一份可序列化的 registry metadata。

Import

import {
  astromerRegistry,
  astromerRegistryByName,
  astrologisticConsumerScenarios,
  astrologisticConsumerContract,
  registrySchemaVersion,
} from "@astromer/core/registry";

Current Scope

目前第一版 registry 先覆蓋已經標成 stable 的基礎 surface：

• actions: Button
• content: Card
• overlays: Dialog
• feedback: ToastProvider
• layout: Container、Stack、Grid、Section
• forms: Field、Input、Textarea、Checkbox、Switch、Slider
• navigation: Breadcrumbs、Pagination、Tabs、NavMenu
• patterns: Hero、FeatureGrid、CTASection、ArticleHeader、ProseSection、RelatedCTA、ServiceGrid、ContactSection

Entry Shape

interface AstromerRegistryEntry {
  name: string;
  kind: "primitive" | "component" | "pattern";
  category: string;
  stability: "stable" | "progressive" | "research";
  importPath: string;
  propsSchema: Record<string, AstromerPropSchema>;
  slots: Array<{ name: string; description: string; required?: boolean }>;
  tokens: string[];
  supports: {
    theme: boolean;
    responsive: boolean;
    motion: boolean;
  };
  editor: {
    label: string;
    description: string;
    icon?: string;
    defaultProps?: Record<string, unknown>;
  };
}

Design Intent

• docs、tests、component API、registry metadata 對同一份現況說真話
• registry 直接帶 stability，避免 consumer 誤把研究中能力當成正式 contract
• consumer 應讀 defaultProps、propsSchema、slots，不要反向解析 component source
• Field.controlId 是必填的 insertion-time value；consumer 必須為每個 Field 產生唯一 ID，並同步套用到 slotted control，不能把固定 ID 放進 defaultProps

Consumer Scenarios

repo 內已經補了一組 astrologisticConsumerScenarios，直接描述 landing、article、contact 三條 flow，並由測試檢查：

• block 只能引用 registry 中存在的 entry
• entry 必須是 stable
• props 與 slots 要符合 registry schema

這代表下一步不是再發明新的 pattern schema，而是讓 Astrologistic 直接用這份 contract 對接真實 editor flow。

Consumer contract payload

也可以直接 import 穩定契約 payload（含 schema version、stable entries 與 scenarios）：

import { astrologisticConsumerContract } from "@astromer/core/registry/consumer-contract";

const { schemaVersion, entries, scenarios } = astrologisticConsumerContract;

astrologisticConsumerContract 會保留：

• schemaVersion: 用來做 migration guard。
• entries: 僅 stable 的 registry entries。
• scenarios: landing/article/contact 三條 flow 及其 block props/slots。