packages/ui (4 levels up, then into packages/ui)
+ return path.join(__dirname, "..", "..", "..", "..", "packages", "ui");
+}
+
+/**
+ * Get the path to the apps/www directory.
+ */
+function getWwwPath(): string {
+ // From apps/www/src/lib/ -> apps/www (2 levels up)
+ return path.join(__dirname, "..", "..");
+}
+
+/**
+ * Registry item type for type safety.
+ */
+interface RegistryItem {
+ name: string;
+ files?: Array<{ path: string; type?: string }>;
+}
+
+/**
+ * Look up a component in a registry file.
+ *
+ * @param registryPath - Absolute path to the registry.json file
+ * @param componentName - The component name to find
+ * @returns The registry item if found, null otherwise
+ */
+function findInRegistry(
+ registryPath: string,
+ componentName: string,
+): RegistryItem | null {
+ try {
+ const registryContent = fs.readFileSync(registryPath, "utf-8");
+ const registry = JSON.parse(registryContent);
+ return (
+ registry.items.find((i: RegistryItem) => i.name === componentName) || null
+ );
+ } catch {
+ return null;
+ }
+}
+
+/**
+ * Extract source code from a file path at build time.
+ * Uses React cache for deduplication during SSG.
+ *
+ * @param filePath - Relative path from a base directory
+ * @param basePath - The base directory to resolve from
+ * @returns The file contents as a string
+ */
+export const extractCodeFromFilePath = cache(
+ (filePath: string, basePath?: string): string => {
+ const absolutePath = path.join(basePath || getPackageUiPath(), filePath);
+
+ try {
+ return fs.readFileSync(absolutePath, "utf-8");
+ } catch (error) {
+ console.error(`Failed to read file: ${absolutePath}`, error);
+ return `// Error: Could not load source code for ${filePath}`;
+ }
+ },
+);
+
+/**
+ * Extract source code for a registry component by name.
+ * Looks up the path in registry.json files and reads the file.
+ *
+ * Checks packages/ui/registry.json first (distributable components),
+ * then falls back to apps/www/src/registry.json (legacy/demo components).
+ *
+ * @param componentName - The component name from registry.json
+ * @returns The source code string
+ */
+export const getComponentSource = cache((componentName: string): string => {
+ const packageUiPath = getPackageUiPath();
+ const wwwPath = getWwwPath();
+
+ // First, check packages/ui/registry.json (distributable components)
+ const packageRegistryPath = path.join(packageUiPath, "registry.json");
+ const packageItem = findInRegistry(packageRegistryPath, componentName);
+
+ if (packageItem?.files?.[0]?.path) {
+ return extractCodeFromFilePath(packageItem.files[0].path, packageUiPath);
+ }
+
+ // Fall back to apps/www/src/registry.json (legacy/demo components)
+ const wwwRegistryPath = path.join(wwwPath, "src", "registry.json");
+ const wwwItem = findInRegistry(wwwRegistryPath, componentName);
+
+ if (wwwItem?.files?.[0]?.path) {
+ return extractCodeFromFilePath(wwwItem.files[0].path, wwwPath);
+ }
+
+ return `// Component "${componentName}" not found in registry`;
+});
+
+/**
+ * Get the file path for a registry component.
+ *
+ * @param componentName - The component name from registry.json
+ * @returns The relative file path, or null if not found
+ */
+export const getComponentFilePath = cache(
+ (componentName: string): string | null => {
+ const packageUiPath = getPackageUiPath();
+ const wwwPath = getWwwPath();
+
+ // First, check packages/ui/registry.json
+ const packageRegistryPath = path.join(packageUiPath, "registry.json");
+ const packageItem = findInRegistry(packageRegistryPath, componentName);
+
+ if (packageItem?.files?.[0]?.path) {
+ return packageItem.files[0].path;
+ }
+
+ // Fall back to apps/www/src/registry.json
+ const wwwRegistryPath = path.join(wwwPath, "src", "registry.json");
+ const wwwItem = findInRegistry(wwwRegistryPath, componentName);
+
+ return wwwItem?.files?.[0]?.path || null;
+ },
+);
diff --git a/apps/www/src/lib/extract-props.ts b/apps/www/src/lib/extract-props.ts
new file mode 100644
index 0000000..e6408c0
--- /dev/null
+++ b/apps/www/src/lib/extract-props.ts
@@ -0,0 +1,307 @@
+import fs from "node:fs";
+import path from "node:path";
+import { cache } from "react";
+
+/**
+ * Props information extracted from TypeScript interfaces.
+ */
+export interface PropInfo {
+ /** Property name */
+ prop: string;
+ /** TypeScript type as string */
+ type: string;
+ /** Default value (if any) */
+ default?: string;
+ /** Whether the prop is required */
+ required: boolean;
+ /** Description from JSDoc comment */
+ description?: string;
+}
+
+/**
+ * Component documentation extracted from TypeScript files.
+ */
+export interface ComponentDoc {
+ /** Component display name */
+ displayName: string;
+ /** Component description from JSDoc */
+ description?: string;
+ /** Extracted props */
+ props: PropInfo[];
+}
+
+// Registry types
+interface RegistryFile {
+ path: string;
+ type: string;
+ target: string;
+}
+
+interface RegistryItem {
+ name: string;
+ type: string;
+ title: string;
+ description?: string;
+ files?: RegistryFile[];
+}
+
+interface Registry {
+ items: RegistryItem[];
+}
+
+/**
+ * Get the path to the packages/ui directory from apps/www.
+ */
+function getPackageUiPath(): string {
+ // In monorepo: apps/www -> packages/ui
+ return path.join(process.cwd(), "..", "..", "packages", "ui");
+}
+
+/**
+ * Parse JSDoc comments from a line of code.
+ * Extracts the description text from /** comment * / blocks.
+ */
+function parseJSDocComment(comment: string): string {
+ return comment
+ .replace(/\/\*\*\s*/g, "")
+ .replace(/\s*\*\//g, "")
+ .replace(/^\s*\*\s?/gm, "")
+ .trim();
+}
+
+/**
+ * Extract default value from component implementation.
+ * Looks for destructuring patterns like: { value, max = 100 }
+ */
+function extractDefaultFromDestructuring(
+ content: string,
+ propName: string,
+): string | undefined {
+ // Match destructuring patterns: { propName = defaultValue }
+ const patterns = [
+ // { prop = value } pattern
+ new RegExp(`${propName}\\s*=\\s*([^,}]+)`, "m"),
+ // prop: defaultValue in object
+ new RegExp(`${propName}:\\s*([^,}]+)`, "m"),
+ ];
+
+ for (const pattern of patterns) {
+ const match = content.match(pattern);
+ if (match?.[1]) {
+ const value = match[1].trim();
+ // Clean up the value - remove type annotations and trailing content
+ const cleanValue = value.split(",")[0].trim();
+ // Skip if it's a type annotation or complex expression
+ if (
+ !cleanValue.includes(":") &&
+ !cleanValue.includes("=>") &&
+ cleanValue.length < 50
+ ) {
+ return cleanValue;
+ }
+ }
+ }
+
+ return undefined;
+}
+
+/**
+ * Extract props from a TypeScript interface definition.
+ * This is a lightweight parser that handles common patterns.
+ */
+function extractPropsFromInterface(
+ content: string,
+ interfaceName: string,
+): PropInfo[] {
+ const props: PropInfo[] = [];
+
+ // Find the interface definition
+ const interfaceRegex = new RegExp(
+ `interface\\s+${interfaceName}[^{]*\\{([^}]+(?:\\{[^}]*\\}[^}]*)*)\\}`,
+ "s",
+ );
+ const match = content.match(interfaceRegex);
+
+ if (!match) {
+ return props;
+ }
+
+ const interfaceBody = match[1];
+
+ // Split into individual property declarations
+ // Handle multi-line JSDoc comments
+ const propRegex = /(\/\*\*[\s\S]*?\*\/\s*)?([\w]+)(\?)?:\s*([^;]+);/g;
+
+ for (const propMatch of interfaceBody.matchAll(propRegex)) {
+ const [, jsDocComment, propName, optional, typeStr] = propMatch;
+
+ // Skip className - it's inherited from React.ComponentProps and not useful in API docs
+ if (propName === "className") {
+ continue;
+ }
+
+ const description = jsDocComment
+ ? parseJSDocComment(jsDocComment)
+ : undefined;
+
+ // Clean up type string
+ let cleanType = typeStr.trim();
+ // Remove React.ComponentProps extensions for cleaner display
+ cleanType = cleanType
+ .replace(/React\.\w+<[^>]+>/g, "")
+ .replace(/Omit<[^>]+>/g, "")
+ .trim();
+
+ // Try to extract default from JSDoc or implementation
+ let defaultValue: string | undefined;
+ const defaultMatch = description?.match(/\(default:\s*([^)]+)\)/i);
+ if (defaultMatch) {
+ defaultValue = defaultMatch[1].trim();
+ } else {
+ defaultValue = extractDefaultFromDestructuring(content, propName);
+ }
+
+ props.push({
+ prop: propName,
+ type: cleanType || "unknown",
+ required: !optional,
+ default: defaultValue,
+ description: description?.replace(/\(default:\s*[^)]+\)/i, "").trim(),
+ });
+ }
+
+ return props;
+}
+
+/**
+ * Extract component documentation from a TypeScript file.
+ *
+ * @param filePath - Relative path from packages/ui/
+ * @returns Array of component documentation
+ */
+export const extractComponentDoc = cache((filePath: string): ComponentDoc[] => {
+ const absolutePath = path.join(getPackageUiPath(), filePath);
+ const docs: ComponentDoc[] = [];
+
+ try {
+ const content = fs.readFileSync(absolutePath, "utf-8");
+
+ // Find all interface definitions that end with "Props"
+ const interfaceNames = content.match(/interface\s+(\w+Props)/g) || [];
+
+ for (const match of interfaceNames) {
+ const interfaceName = match.replace("interface ", "");
+ const componentName = interfaceName.replace("Props", "");
+
+ // Extract component JSDoc (if any) - look above the component definition
+ const componentJSDocRegex = new RegExp(
+ `(\\/\\*\\*[\\s\\S]*?\\*\\/)\\s*(?:export\\s+)?(?:const|function)\\s+${componentName}`,
+ );
+ const componentJSDocMatch = content.match(componentJSDocRegex);
+ const componentDescription = componentJSDocMatch?.[1]
+ ? parseJSDocComment(componentJSDocMatch[1])
+ : undefined;
+
+ const props = extractPropsFromInterface(content, interfaceName);
+
+ if (props.length > 0) {
+ docs.push({
+ displayName: componentName,
+ description: componentDescription,
+ props,
+ });
+ }
+ }
+
+ return docs;
+ } catch (error) {
+ console.error(`Failed to extract props from: ${absolutePath}`, error);
+ return [];
+ }
+});
+
+/**
+ * Extract props for a registry component by name.
+ * Looks up the file path in registry.json and extracts props.
+ *
+ * @param componentName - The component name from registry.json
+ * @returns Array of component documentation, or empty array if not found
+ */
+export const getComponentProps = cache(
+ (componentName: string): ComponentDoc[] => {
+ const registryPath = path.join(getPackageUiPath(), "registry.json");
+
+ try {
+ const registryContent = fs.readFileSync(registryPath, "utf-8");
+ const registry: Registry = JSON.parse(registryContent);
+ const item = registry.items.find((i) => i.name === componentName);
+
+ if (!item?.files?.[0]?.path) {
+ console.warn(`Component "${componentName}" not found in registry`);
+ return [];
+ }
+
+ return extractComponentDoc(item.files[0].path);
+ } catch (error) {
+ console.error(`Failed to load registry for "${componentName}"`, error);
+ return [];
+ }
+ },
+);
+
+/**
+ * Get all available component names from the registry.
+ *
+ * @returns Array of component names
+ */
+export const getComponentNames = cache((): string[] => {
+ const registryPath = path.join(getPackageUiPath(), "registry.json");
+
+ try {
+ const registryContent = fs.readFileSync(registryPath, "utf-8");
+ const registry: Registry = JSON.parse(registryContent);
+ return registry.items
+ .filter((item) => item.type === "registry:component")
+ .map((item) => item.name);
+ } catch (error) {
+ console.error("Failed to load registry", error);
+ return [];
+ }
+});
+
+/**
+ * Convert PropInfo array to ApiTable-compatible format.
+ * Formats types and defaults for display.
+ *
+ * @param props - Array of PropInfo from extraction
+ * @returns Formatted data for ApiTable component
+ */
+export function formatPropsForApiTable(props: PropInfo[]): Array<{
+ prop: string;
+ type: string;
+ default: string;
+ description?: string;
+}> {
+ return props.map((p) => ({
+ prop: p.prop,
+ type: formatType(p.type),
+ default: p.required ? "Required" : p.default || "—",
+ description: p.description,
+ }));
+}
+
+/**
+ * Format a TypeScript type for display.
+ * Handles union types, generics, etc.
+ */
+function formatType(type: string): string {
+ // Format union types with quotes for string literals
+ if (type.includes("|")) {
+ return type
+ .split("|")
+ .map((t) => t.trim())
+ .join(" | ");
+ }
+
+ return type;
+}
diff --git a/apps/www/src/lib/shiki.ts b/apps/www/src/lib/shiki.ts
new file mode 100644
index 0000000..53834a8
--- /dev/null
+++ b/apps/www/src/lib/shiki.ts
@@ -0,0 +1,78 @@
+import { cache } from "react";
+import { type Highlighter, createHighlighter } from "shiki";
+
+/** Supported languages for syntax highlighting */
+export type SupportedLanguage =
+ | "typescript"
+ | "tsx"
+ | "javascript"
+ | "jsx"
+ | "bash"
+ | "json"
+ | "css";
+
+let highlighterPromise: Promise
| null = null;
+
+/**
+ * Get or create the Shiki highlighter singleton.
+ * Loads github-light and github-dark themes.
+ */
+export const getHighlighter = cache(async (): Promise => {
+ if (!highlighterPromise) {
+ highlighterPromise = createHighlighter({
+ themes: ["github-light", "github-dark"],
+ langs: [
+ "typescript",
+ "tsx",
+ "javascript",
+ "jsx",
+ "bash",
+ "json",
+ "css",
+ ] satisfies SupportedLanguage[],
+ });
+ }
+ return highlighterPromise;
+});
+
+/**
+ * Highlight code with Shiki.
+ * Returns HTML string with syntax highlighting.
+ *
+ * @param code - The source code to highlight
+ * @param lang - The language for syntax highlighting
+ */
+export const highlightCode = cache(
+ async (code: string, lang: SupportedLanguage = "tsx"): Promise => {
+ const highlighter = await getHighlighter();
+
+ return highlighter.codeToHtml(code, {
+ lang,
+ themes: {
+ light: "github-light",
+ dark: "github-dark",
+ },
+ });
+ },
+);
+
+/**
+ * Highlight code and return the HTML tokens for more control over rendering.
+ * Useful when you need to wrap lines or add line numbers.
+ *
+ * @param code - The source code to highlight
+ * @param lang - The language for syntax highlighting
+ */
+export const highlightCodeToTokens = cache(
+ async (code: string, lang: SupportedLanguage = "tsx") => {
+ const highlighter = await getHighlighter();
+
+ return highlighter.codeToTokens(code, {
+ lang,
+ themes: {
+ light: "github-light",
+ dark: "github-dark",
+ },
+ });
+ },
+);
diff --git a/apps/www/src/mdx-components.tsx b/apps/www/src/mdx-components.tsx
new file mode 100644
index 0000000..3296273
--- /dev/null
+++ b/apps/www/src/mdx-components.tsx
@@ -0,0 +1,92 @@
+import type * as React from "react";
+
+// Import documentation components (created in Phase 2)
+// import { ComponentCodePreview } from "@/components/docs/component-code-preview"
+// import { ApiTable } from "@/components/docs/api-table"
+
+type MDXComponents = Record<
+ string,
+ React.ComponentType<{ children?: React.ReactNode; [key: string]: unknown }>
+>;
+
+export function useMDXComponents(components: MDXComponents): MDXComponents {
+ return {
+ // Override default elements with custom styling
+ h1: ({ children }: { children?: React.ReactNode }) => (
+
+ {children}
+
+ ),
+ h2: ({ children }: { children?: React.ReactNode }) => (
+
+ {children}
+
+ ),
+ h3: ({ children }: { children?: React.ReactNode }) => (
+
+ {children}
+
+ ),
+ h4: ({ children }: { children?: React.ReactNode }) => (
+
+ {children}
+
+ ),
+ p: ({ children }: { children?: React.ReactNode }) => (
+ {children}
+ ),
+ a: ({ children, href }: { children?: React.ReactNode; href?: string }) => (
+
+ {children}
+
+ ),
+ ul: ({ children }: { children?: React.ReactNode }) => (
+
+ ),
+ ol: ({ children }: { children?: React.ReactNode }) => (
+ {children}
+ ),
+ li: ({ children }: { children?: React.ReactNode }) => {children},
+ blockquote: ({ children }: { children?: React.ReactNode }) => (
+
+ {children}
+
+ ),
+ hr: () =>
,
+ table: ({ children }: { children?: React.ReactNode }) => (
+
+ ),
+ tr: ({ children }: { children?: React.ReactNode }) => (
+ {children}
+ ),
+ th: ({ children }: { children?: React.ReactNode }) => (
+
+ {children}
+ |
+ ),
+ td: ({ children }: { children?: React.ReactNode }) => (
+
+ {children}
+ |
+ ),
+ pre: ({ children }: { children?: React.ReactNode }) => (
+
+ {children}
+
+ ),
+ code: ({ children }: { children?: React.ReactNode }) => (
+
+ {children}
+
+ ),
+ // Add custom components (uncomment when created in Phase 2)
+ // ComponentCodePreview,
+ // ApiTable,
+ ...components,
+ };
+}
diff --git a/apps/www/src/registry.json b/apps/www/src/registry.json
index d593b0b..a8168f5 100644
--- a/apps/www/src/registry.json
+++ b/apps/www/src/registry.json
@@ -800,6 +800,40 @@
"target": "app/layout.tsx"
}
]
+ },
+ {
+ "name": "usage-meter",
+ "type": "registry:ui",
+ "title": "Usage Meter",
+ "description": "A linear progress meter for displaying usage/quota information with full Radix accessibility support.",
+ "registryDependencies": [
+ "https://usage-ui.vercel.app/r/usage-meter.json",
+ "https://registry-starter.vercel.app/r/theme.json"
+ ],
+ "files": [
+ {
+ "path": "src/layouts/minimal-layout.tsx",
+ "type": "registry:file",
+ "target": "app/layout.tsx"
+ }
+ ]
+ },
+ {
+ "name": "usage-meter-base",
+ "type": "registry:ui",
+ "title": "Usage Meter (Base)",
+ "description": "A lightweight linear progress meter for displaying usage/quota information without Radix dependency.",
+ "registryDependencies": [
+ "https://usage-ui.vercel.app/r/usage-meter-base.json",
+ "https://registry-starter.vercel.app/r/theme.json"
+ ],
+ "files": [
+ {
+ "path": "src/layouts/minimal-layout.tsx",
+ "type": "registry:file",
+ "target": "app/layout.tsx"
+ }
+ ]
}
]
}
diff --git a/packages/ui/registry.json b/packages/ui/registry.json
index 28ce598..ca02623 100644
--- a/packages/ui/registry.json
+++ b/packages/ui/registry.json
@@ -2,5 +2,36 @@
"$schema": "https://ui.shadcn.com/schema/registry.json",
"name": "usage-ui",
"homepage": "https://usage-ui.vercel.app",
- "items": []
+ "items": [
+ {
+ "name": "usage-meter",
+ "type": "registry:component",
+ "title": "Usage Meter",
+ "description": "A linear progress meter for displaying usage/quota information with full Radix accessibility support.",
+ "dependencies": ["radix-ui"],
+ "registryDependencies": [],
+ "files": [
+ {
+ "path": "src/components/registry/usage-meter/usage-meter.tsx",
+ "type": "registry:component",
+ "target": "components/ui/usage-meter.tsx"
+ }
+ ]
+ },
+ {
+ "name": "usage-meter-base",
+ "type": "registry:component",
+ "title": "Usage Meter (Base)",
+ "description": "A lightweight linear progress meter for displaying usage/quota information without Radix dependency.",
+ "dependencies": [],
+ "registryDependencies": [],
+ "files": [
+ {
+ "path": "src/components/registry/usage-meter/usage-meter-base.tsx",
+ "type": "registry:component",
+ "target": "components/ui/usage-meter-base.tsx"
+ }
+ ]
+ }
+ ]
}
diff --git a/packages/ui/src/components/registry/index.ts b/packages/ui/src/components/registry/index.ts
index af6c27f..fbebfa3 100644
--- a/packages/ui/src/components/registry/index.ts
+++ b/packages/ui/src/components/registry/index.ts
@@ -1,5 +1,2 @@
-// Registry components will be exported here as they are created
-// Example: export * from "./usage-meter";
-
-// Placeholder export to ensure this is a valid module
-export {};
+// Registry components
+export * from "./usage-meter";
diff --git a/packages/ui/src/components/registry/usage-meter/index.ts b/packages/ui/src/components/registry/usage-meter/index.ts
new file mode 100644
index 0000000..87816e1
--- /dev/null
+++ b/packages/ui/src/components/registry/usage-meter/index.ts
@@ -0,0 +1,9 @@
+export { UsageMeter, meterVariants, meterSizes } from "./usage-meter";
+export type { UsageMeterProps } from "./usage-meter";
+
+export {
+ UsageMeterBase,
+ meterBaseVariants,
+ meterBaseSizes,
+} from "./usage-meter-base";
+export type { UsageMeterBaseProps } from "./usage-meter-base";
diff --git a/packages/ui/src/components/registry/usage-meter/usage-meter-base.tsx b/packages/ui/src/components/registry/usage-meter/usage-meter-base.tsx
new file mode 100644
index 0000000..bf54947
--- /dev/null
+++ b/packages/ui/src/components/registry/usage-meter/usage-meter-base.tsx
@@ -0,0 +1,115 @@
+"use client";
+
+import * as React from "react";
+
+import { cn } from "@/lib/utils";
+
+const meterVariants = {
+ default: "bg-primary",
+ success: "bg-chart-2",
+ warning: "bg-chart-4",
+ danger: "bg-destructive",
+} as const;
+
+const meterSizes = {
+ sm: "h-2",
+ default: "h-3",
+ lg: "h-4",
+} as const;
+
+interface UsageMeterBaseProps extends React.HTMLAttributes {
+ /** Current value (required) */
+ value: number;
+ /** Maximum value (default: 100) */
+ max?: number;
+ /** Visual variant */
+ variant?: keyof typeof meterVariants;
+ /** Size variant */
+ size?: keyof typeof meterSizes;
+ /** Optional label text */
+ label?: string;
+ /** Show percentage (default: true) */
+ showPercentage?: boolean;
+}
+
+const UsageMeterBase = React.forwardRef(
+ (
+ {
+ className,
+ value,
+ max = 100,
+ variant = "default",
+ size = "default",
+ label,
+ showPercentage = true,
+ ...props
+ },
+ ref,
+ ) => {
+ // Guard against max being 0 or negative to avoid NaN/Infinity
+ const percentage = max > 0 ? Math.round((value / max) * 100) : 0;
+ const clampedPercentage = Math.min(100, Math.max(0, percentage));
+
+ return (
+
+ {(label || showPercentage) && (
+
+ {label && (
+
+ {label}
+
+ )}
+ {showPercentage && (
+
+ {clampedPercentage}%
+
+ )}
+
+ )}
+
+
+ {(label || showPercentage) && (
+
+ {label && (
+
+ {label}
+
+ )}
+ {showPercentage && (
+
+ {clampedPercentage}%
+
+ )}
+
+ )}
+
+
+
+