@underverse-ui/underverse 1.0.28 → 1.0.30

package/AGENTS.md

@@ -0,0 +1,87 @@
+# Underverse Agent Guide
+
+This file is for coding agents and automation tools that need to use `@underverse-ui/underverse` quickly and correctly.
+
+## Package Summary
+
+- Package: `@underverse-ui/underverse`
+- Runtime: React 18+ (supports Next.js and standalone React)
+- Main entry: `@underverse-ui/underverse`
+- Type definitions: `dist/index.d.ts`
+- Machine-readable API snapshot: `api-reference.json`
+- Quick LLM context: `llms.txt`
+- Task recipes: `agent-recipes.json`
+
+## Install
+
+```bash
+npm i @underverse-ui/underverse
+```
+
+Common peers:
+
+```bash
+npm i react react-dom
+```
+
+Next.js projects may also need:
+
+```bash
+npm i next next-intl
+```
+
+## Quick Usage
+
+```tsx
+import { Button } from "@underverse-ui/underverse";
+
+export function Example() {
+  return <Button>Click</Button>;
+}
+```
+
+## Overlay Scrollbars (recommended)
+
+Use the exported provider to enable overlay scrollbars (no layout width loss):
+
+```tsx
+import "overlayscrollbars/overlayscrollbars.css";
+import { OverlayScrollbarProvider } from "@underverse-ui/underverse";
+
+export function App() {
+  return (
+    <>
+      <OverlayScrollbarProvider />
+      {/* app */}
+    </>
+  );
+}
+```
+
+## i18n Notes
+
+- Components work without `next-intl` using fallback translations.
+- For app-level i18n integration:
+  - Use `TranslationProvider` / `UnderverseProvider`.
+  - Use `underverseMessages` or `getUnderverseMessages(locale)` for message bundles.
+
+## Form Notes
+
+- Form components are exported from main entry and depend on `react-hook-form` ecosystem peers.
+- If an app does not use form features, those peers can often be omitted.
+
+## API Discovery
+
+Preferred order for automated tooling:
+
+1. `api-reference.json` (fast machine parse).
+2. `dist/index.d.ts` (accurate TS API surface).
+3. `agent-recipes.json` / `llms.txt` (ready-to-apply usage).
+4. `README.md` (integration guidance and additional context).
+
+## Agent Rules
+
+- Do not deep-import internal source paths from this package.
+- Always import from `@underverse-ui/underverse`.
+- Prefer exported `Props` types when generating wrappers or stories.
+- Keep usage compatible with React 18+ and Next.js app router defaults.

package/README.md

@@ -30,6 +30,21 @@ A comprehensive UI component library for React/Next.js applications, extracted f
 - Peer dependencies: `react`, `react-dom`
 - Optional: `next`, `next-intl` (for Next.js projects)
 
+## Agent-Readable Metadata
+
+For coding agents and automation tools:
+
+- `AGENTS.md`: concise usage and integration rules.
+- `api-reference.json`: generated export index from `src/index.ts`.
+- `llms.txt`: compact LLM-friendly quickstart.
+- `agent-recipes.json`: structured setup/use recipes.
+
+Regenerate API metadata:
+
+```bash
+npm run generate:api
+```
+
 ## Installation
 
 ```bash

package/agent-recipes.json

@@ -0,0 +1,42 @@
+{
+  "package": "@underverse-ui/underverse",
+  "schemaVersion": 1,
+  "recipes": [
+    {
+      "id": "install-basic",
+      "title": "Install for React",
+      "steps": [
+        "npm i @underverse-ui/underverse",
+        "npm i react react-dom"
+      ]
+    },
+    {
+      "id": "install-next",
+      "title": "Install for Next.js",
+      "steps": [
+        "npm i @underverse-ui/underverse",
+        "npm i react react-dom next next-intl"
+      ]
+    },
+    {
+      "id": "first-component",
+      "title": "Use first component",
+      "code": "import { Button } from \"@underverse-ui/underverse\";\n\nexport function Example(){\n  return <Button>Click</Button>;\n}\n"
+    },
+    {
+      "id": "overlay-scrollbar-provider",
+      "title": "Enable overlay scrollbars",
+      "code": "import \"overlayscrollbars/overlayscrollbars.css\";\nimport { OverlayScrollbarProvider } from \"@underverse-ui/underverse\";\n\nexport function App(){\n  return <><OverlayScrollbarProvider />{/* app */}</>;\n}\n"
+    },
+    {
+      "id": "api-discovery-order",
+      "title": "How agents should discover API",
+      "steps": [
+        "Read api-reference.json first",
+        "Read dist/index.d.ts second",
+        "Read AGENTS.md and README.md for integration notes"
+      ]
+    }
+  ]
+}
+