@replicated/portal-components 0.0.1 → 0.0.3

package/components/metadata/registry.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.0.1",
-  "generatedAt": "2025-02-09T00:00:00.000Z",
+  "version": "0.0.3",
+  "generatedAt": "2025-12-12T22:19:20Z",
   "components": [
     {
       "name": "Button",
@@ -154,7 +154,7 @@
         "form",
         "card"
       ],
-      "description": "Bordered authentication form with centered branding, email capture, and CTA button built for initial portal logins.",
+      "description": "Bordered authentication flow with centered branding, email capture, and CTA button built for initial portal logins. After a successful submission the component transitions to a verification UI showing the 12-digit code field. Pair with the `initiateLogin` server action exported from `@replicated/portal-components/actions`.",
       "props": [
         {
           "name": "logo",
@@ -215,6 +215,19 @@
           "type": "(email: string) => Promise<void> | void",
           "required": false,
           "description": "Callback invoked when the form submits. Receives the current email string."
+        },
+        {
+          "name": "onVerifyCode",
+          "type": "(code: string, redirectPath: string) => Promise<void | { success: true } | { success: false; message?: string }>",
+          "required": false,
+          "description": "Called when the user submits the 12-digit code in the verification step."
+        },
+        {
+          "name": "redirectPath",
+          "type": "string",
+          "required": false,
+          "defaultValue": "\"/\"",
+          "description": "Relative path to navigate to once verification succeeds."
         }
       ],
       "composition": {
@@ -237,6 +250,18 @@
           "description": "Override the logo with a vendor-specific mark.",
           "scenario": "White-labeled portal for an ISV.",
           "code": "<Login logo={<VendorLogo />} title=\"Acme Deployment Portal\" description=\"Access licenses, releases, and support\" />"
+        },
+        {
+          "id": "verification-step",
+          "description": "The component handles the verification step automatically after onContinue resolves.",
+          "scenario": "Customer enters their code from email to finish authentication.",
+          "code": "<Login onContinue={continueWithEmail} />"
+        },
+        {
+          "id": "server-action",
+          "description": "Invoke the provided server action to trigger passwordless email flows.",
+          "scenario": "Next.js App Router login route wired to Replicated APIs.",
+          "code": "'use server';\nimport { initiateLogin } from \"@replicated/portal-components/actions\";\n\nexport async function continueWithEmail(email: string) {\n  await initiateLogin.run({ email }, {\n    vendorId: \"demo-vendor\",\n    licenseId: \"demo-license\",\n    userId: \"anonymous\"\n  });\n}\n\n<Login onContinue={continueWithEmail} />"
         }
       ],
       "behavior": {
@@ -268,6 +293,87 @@
       "relatedComponents": [
         "Button"
       ]
+    },
+    {
+      "name": "TopNav",
+      "displayName": "Top Navigation",
+      "versionIntroduced": "0.0.2",
+      "stability": "experimental",
+      "category": "layout",
+      "tags": [
+        "navigation",
+        "hero",
+        "tabs"
+      ],
+      "description": "Gradient hero banner containing the primary dashboard navigation tabs. Mirrors the default portal shell shown after login.",
+      "props": [
+        {
+          "name": "links",
+          "type": "Array<{ label: string; icon: ReactNode }>",
+          "required": false,
+          "description": "Override the default portal links. Leave undefined to render the standard set (Dashboard, Download, etc.)."
+        },
+        {
+          "name": "hiddenLabels",
+          "type": "string[]",
+          "required": false,
+          "description": "List of link labels to hide from the default set."
+        },
+        {
+          "name": "additionalLinks",
+          "type": "Array<{ label: string; icon: ReactNode }>",
+          "required": false,
+          "description": "Links appended after the base set. Useful for vendor-specific pages."
+        },
+        {
+          "name": "order",
+          "type": "string[]",
+          "required": false,
+          "description": "Optional ordering hint. Labels listed here are shown first in the specified order; remaining links follow in their original sequence."
+        },
+        {
+          "name": "userMenuLabel",
+          "type": "string",
+          "required": false,
+          "defaultValue": "\"Team: Example\"",
+          "description": "Text to render in the top-right account dropdown trigger."
+        }
+      ],
+      "composition": {
+        "requiredParents": [],
+        "requiredChildren": [],
+        "forbiddenChildren": [],
+        "slots": []
+      },
+      "examples": [
+        {
+          "id": "default-links",
+          "description": "Use the standard portal sections as tabs.",
+          "scenario": "Dashboard shell after successful login.",
+          "code": "<TopNav links={[{ label: \"Dashboard\", icon: <DashboardIcon /> }, { label: \"Download\", icon: <DownloadIcon /> }]} />"
+        }
+      ],
+      "behavior": {
+        "mode": "server",
+        "requiresJavaScript": false,
+        "dataAccess": "none",
+        "managesState": "presentational"
+      },
+      "accessibility": {
+        "aria": [],
+        "keyboard": [],
+        "screenReader": [],
+        "focusManagement": []
+      },
+      "performance": {
+        "bundleImpact": "low",
+        "notes": "Purely presentational markup; icons provided by callers.",
+        "lazyLoadable": true,
+        "virtualization": false
+      },
+      "relatedComponents": [
+        "Login"
+      ]
     }
   ]
 }

package/components/metadata/registry.md

@@ -1,7 +1,7 @@
 # Component Registry
 
-- Version: 0.0.1
-- Generated: 2025-02-09T00:00:00.000Z
+- Version: 0.0.3
+- Generated: 2025-12-12T22:19:20Z
 
 ## Button
 
@@ -45,7 +45,7 @@ Theme-aware CTA for triggering portal actions with optional icons and loading fe
 
 ## Login
 
-Bordered authentication form with centered branding, email capture, and CTA button built for initial portal logins.
+Bordered authentication flow with centered branding, email capture, and CTA button built for initial portal logins. After a successful submission the component transitions to a verification UI showing the 12-digit code field. Pair with the `initiateLogin` server action exported from `@replicated/portal-components/actions`.
 
 **Category:** pattern
 **Stability:** experimental
@@ -61,6 +61,8 @@ Bordered authentication form with centered branding, email capture, and CTA butt
 | initialEmail | `string` | No | Prefills the input when the user already provided their email. |
 | isSubmitting | `boolean` | No | When true the form disables interactions and shows the button spinner. |
 | onContinue | `(email: string) => Promise<void> \| void` | No | Callback invoked when the form submits. Receives the current email string. |
+| onVerifyCode | `(code: string, redirectPath: string) => Promise<void \| { success: true } \| { success: false; message?: string }>` | No | Called when the user submits the 12-digit code in the verification step. |
+| redirectPath | `string` | No | Relative path to navigate to once verification succeeds. |
 
 **Examples**
 
@@ -75,3 +77,51 @@ Bordered authentication form with centered branding, email capture, and CTA butt
 ```tsx
 <Login logo={<VendorLogo />} title="Acme Deployment Portal" description="Access licenses, releases, and support" />
 ```
+
+**The component handles the verification step automatically after onContinue resolves.**
+
+```tsx
+<Login onContinue={continueWithEmail} />
+```
+
+**Invoke the provided server action to trigger passwordless email flows.**
+
+```tsx
+'use server';
+import { initiateLogin } from "@replicated/portal-components/actions";
+
+export async function continueWithEmail(email: string) {
+  await initiateLogin.run({ email }, {
+    vendorId: "demo-vendor",
+    licenseId: "demo-license",
+    userId: "anonymous"
+  });
+}
+
+<Login onContinue={continueWithEmail} />
+```
+
+---
+
+## Top Navigation
+
+Gradient hero banner containing the primary dashboard navigation tabs. Mirrors the default portal shell shown after login.
+
+**Category:** layout
+**Stability:** experimental
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| links | `Array<{ label: string; icon: ReactNode }>` | No | Override the default portal links. Leave undefined to render the standard set (Dashboard, Download, etc.). |
+| hiddenLabels | `string[]` | No | List of link labels to hide from the default set. |
+| additionalLinks | `Array<{ label: string; icon: ReactNode }>` | No | Links appended after the base set. Useful for vendor-specific pages. |
+| order | `string[]` | No | Optional ordering hint. Labels listed here are shown first in the specified order; remaining links follow in their original sequence. |
+| userMenuLabel | `string` | No | Text to render in the top-right account dropdown trigger. |
+
+**Examples**
+
+**Use the standard portal sections as tabs.**
+
+```tsx
+<TopNav links={[{ label: "Dashboard", icon: <DashboardIcon /> }, { label: "Download", icon: <DownloadIcon /> }]} />
+```