ui-lab-registry 0.3.44 → 0.3.45

package/src/components/Modal/examples/04-create-api-key.tsx

@@ -0,0 +1,54 @@
+"use client";
+
+import { useState } from "react";
+import { Modal, Button, Input, Label } from "ui-lab-components";
+
+export const metadata = {
+  title: "Create API Key",
+  description: "Form modal with a single required input. The primary action stays disabled until the field has a value.",
+};
+
+export default function Example() {
+  const [isOpen, setIsOpen] = useState(false);
+  const [name, setName] = useState("");
+
+  return (
+    <>
+      <Button onClick={() => setIsOpen(true)}>New API key</Button>
+
+      <Modal
+        isOpen={isOpen}
+        onOpenChange={setIsOpen}
+        title="New API key"
+        footer={
+          <>
+            <Button variant="ghost" onClick={() => setIsOpen(false)}>
+              Cancel
+            </Button>
+            <Button
+              onClick={() => setIsOpen(false)}
+              isDisabled={!name.trim()}
+            >
+              Create
+            </Button>
+          </>
+        }
+      >
+        <div className="flex flex-col gap-4 px-6 py-4">
+          <div className="flex flex-col gap-1.5">
+            <Label htmlFor="key-name">Name</Label>
+            <Input
+              id="key-name"
+              placeholder="e.g. CI deploy key"
+              value={name}
+              onChange={(e) => setName(e.target.value)}
+            />
+          </div>
+          <p className="text-xs text-foreground-400">
+            The key will only be shown once after creation.
+          </p>
+        </div>
+      </Modal>
+    </>
+  );
+}

package/src/components/Modal/examples/05-notification-settings.tsx

@@ -0,0 +1,58 @@
+"use client";
+
+import { useState } from "react";
+import { Modal, Button, Switch } from "ui-lab-components";
+
+export const metadata = {
+  title: "Notification Settings",
+  description: "Settings panel using the compound Modal.Header / Modal.Body / Modal.Footer API with toggle rows.",
+};
+
+export default function Example() {
+  const [isOpen, setIsOpen] = useState(false);
+  const [prefs, setPrefs] = useState({ email: true, push: false, marketing: false });
+
+  const toggle = (key: keyof typeof prefs) =>
+    setPrefs((p) => ({ ...p, [key]: !p[key] }));
+
+  return (
+    <>
+      <Button variant="ghost" onClick={() => setIsOpen(true)}>
+        Notification settings
+      </Button>
+
+      <Modal isOpen={isOpen} onOpenChange={setIsOpen}>
+        <Modal.Header>
+          <span className="text-sm font-semibold text-foreground-100">Notification preferences</span>
+        </Modal.Header>
+
+        <Modal.Body>
+          <div className="flex flex-col divide-y divide-border px-6">
+            {(
+              [
+                { key: "email", label: "Email notifications", description: "Receive updates and alerts by email" },
+                { key: "push", label: "Push notifications", description: "Browser and mobile push alerts" },
+                { key: "marketing", label: "Product updates", description: "New features and announcements" },
+              ] as const
+            ).map(({ key, label, description }) => (
+              <div key={key} className="flex items-center justify-between py-4">
+                <div className="flex flex-col gap-0.5">
+                  <span className="text-sm text-foreground-100">{label}</span>
+                  <span className="text-xs text-foreground-400">{description}</span>
+                </div>
+                <Switch isSelected={prefs[key]} onChange={() => toggle(key)} />
+              </div>
+            ))}
+          </div>
+        </Modal.Body>
+
+        <Modal.Footer>
+          <Button variant="ghost" onClick={() => setIsOpen(false)}>
+            Cancel
+          </Button>
+          <Button onClick={() => setIsOpen(false)}>Save</Button>
+        </Modal.Footer>
+      </Modal>
+    </>
+  );
+}

package/src/components/Modal/examples/index.ts

@@ -2,3 +2,9 @@ export { default as Example1 } from './01-basic-modal.js';
 export { metadata as metadata1 } from './01-basic-modal.js';
 export { default as Example2 } from './02-form-modal.js';
 export { metadata as metadata2 } from './02-form-modal.js';
+export { default as Example3 } from './03-delete-confirmation.js';
+export { metadata as metadata3 } from './03-delete-confirmation.js';
+export { default as Example4 } from './04-create-api-key.js';
+export { metadata as metadata4 } from './04-create-api-key.js';
+export { default as Example5 } from './05-notification-settings.js';
+export { metadata as metadata5 } from './05-notification-settings.js';

package/src/components/Modal/examples.json

@@ -7,6 +7,21 @@
   "02-form-modal": {
     "title": "Form Modal",
     "description": "A modal dialog containing a form for editing user profile settings. Demonstrates using form inputs, labels, and action buttons within a modal.",
-    "code": "'use client';\n\nimport React from 'react';\nimport { Modal, Button, Input, Label, TextArea, Flex } from 'ui-lab-components';\n\nexport default function Example() {\n  const [isOpen, setIsOpen] = React.useState(false);\n  const [formData, setFormData] = React.useState({\n    name: 'John Doe',\n    email: 'john.doe@example.com',\n    bio: 'Software developer passionate about building great user experiences.',\n  });\n\n  const handleSubmit = (e: React.FormEvent) => {\n    e.preventDefault();\n    // Handle form submission\n    setIsOpen(false);\n  };\n\n  return (\n    <>\n      <Button onClick={() => setIsOpen(true)}>Edit Profile</Button>\n      <Modal isOpen={isOpen} onOpenChange={setIsOpen} size=\"auto\">\n        <Modal.Header>Edit Profile</Modal.Header>\n        <Modal.Body>\n          <form id=\"profile-form\" onSubmit={handleSubmit}>\n            <Flex direction=\"column\" gap=\"md\">\n              <div>\n                <Label htmlFor=\"name\" required>\n                  Full Name\n                </Label>\n                <Input\n                  id=\"name\"\n                  value={formData.name}\n                  onChange={(e) =>\n                    setFormData({ ...formData, name: e.target.value })\n                  }\n                  placeholder=\"Enter your name\"\n                />\n              </div>\n              <div>\n                <Label htmlFor=\"email\" required>\n                  Email Address\n                </Label>\n                <Input\n                  id=\"email\"\n                  type=\"email\"\n                  value={formData.email}\n                  onChange={(e) =>\n                    setFormData({ ...formData, email: e.target.value })\n                  }\n                  placeholder=\"Enter your email\"\n                />\n              </div>\n              <div>\n                <Label htmlFor=\"bio\">Bio</Label>\n                <TextArea\n                  id=\"bio\"\n                  value={formData.bio}\n                  onChange={(e) =>\n                    setFormData({ ...formData, bio: e.target.value })\n                  }\n                  placeholder=\"Tell us about yourself\"\n                  rows={3}\n                />\n              </div>\n            </Flex>\n          </form>\n        </Modal.Body>\n        <Modal.Footer>\n          <Flex gap=\"sm\" justify=\"flex-end\">\n            <Button variant=\"ghost\" onClick={() => setIsOpen(false)}>\n              Cancel\n            </Button>\n            <Button type=\"submit\" form=\"profile-form\">\n              Save Changes\n            </Button>\n          </Flex>\n        </Modal.Footer>\n      </Modal>\n    </>\n  );\n}"
+    "code": "'use client';\n\nimport React from 'react';\nimport { Modal, Button, Input, Label, TextArea, Flex } from 'ui-lab-components';\n\nexport default function Example() {\n  const [isOpen, setIsOpen] = React.useState(false);\n  const [formData, setFormData] = React.useState({\n    name: 'John Doe',\n    email: 'john.doe@example.com',\n    bio: 'Software developer passionate about building great user experiences.',\n  });\n\n  const handleSubmit = (e: React.FormEvent) => {\n    e.preventDefault();\n    // Handle form submission\n    setIsOpen(false);\n  };\n\n  return (\n    <>\n      <Button onClick={() => setIsOpen(true)}>Edit Profile</Button>\n      <Modal isOpen={isOpen} onOpenChange={setIsOpen} size=\"auto\">\n        <Modal.Header>Edit Profile</Modal.Header>\n        <Modal.Body>\n          <form id=\"profile-form\" onSubmit={handleSubmit}>\n            <Flex direction=\"column\" gap=\"md\">\n              <div>\n                <Label htmlFor=\"name\" required>\n                  Full Name\n                </Label>\n                <Input\n                  id=\"name\"\n                  value={formData.name}\n                  onChange={(e) =>\n                    setFormData({ ...formData, name: e.target.value })\n                  }\n                  placeholder=\"Enter your name\"\n                />\n              </div>\n              <div>\n                <Label htmlFor=\"email\" required>\n                  Email Address\n                </Label>\n                <Input\n                  id=\"email\"\n                  type=\"email\"\n                  value={formData.email}\n                  onChange={(e) =>\n                    setFormData({ ...formData, email: e.target.value })\n                  }\n                  placeholder=\"Enter your email\"\n                />\n              </div>\n              <div>\n                <Label htmlFor=\"bio\">Bio</Label>\n                <TextArea\n                  id=\"bio\"\n                  value={formData.bio}\n                  onChange={(e) =>\n                    setFormData({ ...formData, bio: e.target.value })\n                  }\n                  placeholder=\"Tell us about yourself\"\n                  rows={3}\n                />\n              </div>\n            </Flex>\n          </form>\n        </Modal.Body>\n        <Modal.Footer>\n          <Flex gap=\"sm\" justify=\"end\">\n            <Button variant=\"ghost\" onClick={() => setIsOpen(false)}>\n              Cancel\n            </Button>\n            <Button type=\"submit\" form=\"profile-form\">\n              Save Changes\n            </Button>\n          </Flex>\n        </Modal.Footer>\n      </Modal>\n    </>\n  );\n}"
+  },
+  "03-delete-confirmation": {
+    "title": "Delete Confirmation",
+    "description": "Destructive action dialog that blocks the user until they explicitly confirm or cancel.",
+    "code": "\"use client\";\n\nimport { useState } from \"react\";\nimport { Modal, Button } from \"ui-lab-components\";\n\nexport default function Example() {\n  const [isOpen, setIsOpen] = useState(false);\n\n  return (\n    <>\n      <Button variant=\"destructive\" onClick={() => setIsOpen(true)}>\n        Delete workspace\n      </Button>\n\n      <Modal\n        isOpen={isOpen}\n        onOpenChange={setIsOpen}\n        title=\"Delete workspace\"\n        footer={\n          <>\n            <Button variant=\"ghost\" onClick={() => setIsOpen(false)}>\n              Cancel\n            </Button>\n            <Button variant=\"destructive\" onClick={() => setIsOpen(false)}>\n              Delete\n            </Button>\n          </>\n        }\n      >\n        <p className=\"text-sm text-foreground-300\">\n          This will permanently delete <strong className=\"text-foreground-100\">acme-corp</strong> and all\n          its data. This action cannot be undone.\n        </p>\n      </Modal>\n    </>\n  );\n}"
+  },
+  "04-create-api-key": {
+    "title": "Create API Key",
+    "description": "Form modal with a single required input. The primary action stays disabled until the field has a value.",
+    "code": "\"use client\";\n\nimport { useState } from \"react\";\nimport { Modal, Button, Input, Label } from \"ui-lab-components\";\n\nexport default function Example() {\n  const [isOpen, setIsOpen] = useState(false);\n  const [name, setName] = useState(\"\");\n\n  return (\n    <>\n      <Button onClick={() => setIsOpen(true)}>New API key</Button>\n\n      <Modal\n        isOpen={isOpen}\n        onOpenChange={setIsOpen}\n        title=\"New API key\"\n        footer={\n          <>\n            <Button variant=\"ghost\" onClick={() => setIsOpen(false)}>\n              Cancel\n            </Button>\n            <Button\n              onClick={() => setIsOpen(false)}\n              isDisabled={!name.trim()}\n            >\n              Create\n            </Button>\n          </>\n        }\n      >\n        <div className=\"flex flex-col gap-4 px-6 py-4\">\n          <div className=\"flex flex-col gap-1.5\">\n            <Label htmlFor=\"key-name\">Name</Label>\n            <Input\n              id=\"key-name\"\n              placeholder=\"e.g. CI deploy key\"\n              value={name}\n              onChange={(e) => setName(e.target.value)}\n            />\n          </div>\n          <p className=\"text-xs text-foreground-400\">\n            The key will only be shown once after creation.\n          </p>\n        </div>\n      </Modal>\n    </>\n  );\n}"
+  },
+  "05-notification-settings": {
+    "title": "Notification Settings",
+    "description": "Settings panel using the compound Modal.Header / Modal.Body / Modal.Footer API with toggle rows.",
+    "code": "\"use client\";\n\nimport { useState } from \"react\";\nimport { Modal, Button, Switch } from \"ui-lab-components\";\n\nexport default function Example() {\n  const [isOpen, setIsOpen] = useState(false);\n  const [prefs, setPrefs] = useState({ email: true, push: false, marketing: false });\n\n  const toggle = (key: keyof typeof prefs) =>\n    setPrefs((p) => ({ ...p, [key]: !p[key] }));\n\n  return (\n    <>\n      <Button variant=\"ghost\" onClick={() => setIsOpen(true)}>\n        Notification settings\n      </Button>\n\n      <Modal isOpen={isOpen} onOpenChange={setIsOpen}>\n        <Modal.Header>\n          <span className=\"text-sm font-semibold text-foreground-100\">Notification preferences</span>\n        </Modal.Header>\n\n        <Modal.Body>\n          <div className=\"flex flex-col divide-y divide-border px-6\">\n            {(\n              [\n                { key: \"email\", label: \"Email notifications\", description: \"Receive updates and alerts by email\" },\n                { key: \"push\", label: \"Push notifications\", description: \"Browser and mobile push alerts\" },\n                { key: \"marketing\", label: \"Product updates\", description: \"New features and announcements\" },\n              ] as const\n            ).map(({ key, label, description }) => (\n              <div key={key} className=\"flex items-center justify-between py-4\">\n                <div className=\"flex flex-col gap-0.5\">\n                  <span className=\"text-sm text-foreground-100\">{label}</span>\n                  <span className=\"text-xs text-foreground-400\">{description}</span>\n                </div>\n                <Switch isSelected={prefs[key]} onChange={() => toggle(key)} />\n              </div>\n            ))}\n          </div>\n        </Modal.Body>\n\n        <Modal.Footer>\n          <Button variant=\"ghost\" onClick={() => setIsOpen(false)}>\n            Cancel\n          </Button>\n          <Button onClick={() => setIsOpen(false)}>Save</Button>\n        </Modal.Footer>\n      </Modal>\n    </>\n  );\n}"
   }
 }

package/src/components/Modal/index.tsx

@@ -3,11 +3,19 @@ import { Modal, Button } from 'ui-lab-components';
 import { ControlDef, ComponentDetail } from '@/types';
 import { FaWindowRestore, FaX } from 'react-icons/fa6';
 import Example1, { metadata as metadata1 } from './examples/01-basic-modal.js';
+import Example2, { metadata as metadata2 } from './examples/02-form-modal.js';
+import Example3, { metadata as metadata3 } from './examples/03-delete-confirmation.js';
+import Example4, { metadata as metadata4 } from './examples/04-create-api-key.js';
+import Example5, { metadata as metadata5 } from './examples/05-notification-settings.js';
 import examplesJson from './examples.json' with { type: 'json' };
 import { loadComponentExamples } from '../../utils/load-component-examples.js';
 
 const examplesData = [
   { id: '01-basic-modal', Component: Example1, metadata: metadata1 },
+  { id: '02-form-modal', Component: Example2, metadata: metadata2 },
+  { id: '03-delete-confirmation', Component: Example3, metadata: metadata3 },
+  { id: '04-create-api-key', Component: Example4, metadata: metadata4 },
+  { id: '05-notification-settings', Component: Example5, metadata: metadata5 },
 ];
 
 const modalControls: ControlDef[] = [

package/src/components/Modal/metadata.json

@@ -25,5 +25,45 @@
       "Keyboard dismissal",
       "ARIA dialog role"
     ]
+  },
+  "usage": {
+    "summary": "Use Modal for short, focused dialog tasks that need a dedicated overlay surface and clear dismissal path.",
+    "whenToUse": [
+      "Interruptive tasks that need focused attention",
+      "Short forms, confirmations, or contextual workflows that should not navigate away",
+      "Situations where the dialog itself should provide the only surfaced container"
+    ],
+    "whenNotToUse": [
+      "Long, browse-heavy, or primary page flows",
+      "Cases where inline expansion or a dedicated page would be clearer",
+      "Layouts that require another nested surface just to hold the content"
+    ],
+    "rules": [
+      {
+        "type": "do",
+        "title": "Let Modal be the surface",
+        "description": "Use the modal shell, title, content area, and footer as the dialog structure instead of wrapping the body in another surface component."
+      },
+      {
+        "type": "avoid",
+        "title": "Avoid nested surfaced containers",
+        "description": "Do not place Card or other panel-like surfaces inside the modal body unless there is a strong semantic need for a distinct sub-region.",
+        "relatedComponents": [
+          "card",
+          "panel",
+          "confirm"
+        ]
+      },
+      {
+        "type": "prefer",
+        "title": "Prefer direct content plus layout primitives",
+        "description": "Arrange modal content with Flex, Grid, Group, and Modal footer slots so the hierarchy stays shallow and the dialog reads as a single unit.",
+        "relatedComponents": [
+          "flex",
+          "grid",
+          "group"
+        ]
+      }
+    ]
   }
-}
+}

package/src/components/Panel/examples/01-sidebar-toggle.tsx

@@ -0,0 +1,20 @@
+import { Panel } from "ui-lab-components";
+
+export const metadata = {
+  title: "Sidebar with Toggle",
+  description: "Left sidebar that collapses and expands via a toggle button in the content area.",
+};
+
+export default function Example() {
+  return (
+    <Panel style={{ height: "400px" }} className="w-full border border-background-700 rounded-lg bg-background-900">
+      <Panel.Sidebar side="left" defaultOpen width="200px" collapsedWidth="0">
+      </Panel.Sidebar>
+      <Panel.Content>
+        <Panel.Toggle>
+          <button>☰</button>
+        </Panel.Toggle>
+      </Panel.Content>
+    </Panel>
+  );
+}

package/src/components/Panel/examples/index.ts

@@ -0,0 +1,2 @@
+export { default as Example1 } from './01-sidebar-toggle.js';
+export { metadata as metadata1 } from './01-sidebar-toggle.js';

package/src/components/Panel/examples.json

@@ -1 +1,7 @@
-{}
+{
+  "01-sidebar-toggle": {
+    "title": "Sidebar with Toggle",
+    "description": "Left sidebar that collapses and expands via a toggle button in the content area.",
+    "code": "import { Panel } from \"ui-lab-components\";\n\nexport default function Example() {\n  return (\n    <Panel style={{ height: \"400px\" }} className=\"w-full border border-background-700 rounded-lg bg-background-900\">\n      <Panel.Sidebar side=\"left\" defaultOpen width=\"200px\" collapsedWidth=\"0\">\n      </Panel.Sidebar>\n      <Panel.Content>\n        <Panel.Toggle>\n          <button>☰</button>\n        </Panel.Toggle>\n      </Panel.Content>\n    </Panel>\n  );\n}"
+  }
+}

package/src/components/Panel/index.tsx

@@ -1,6 +1,13 @@
 import React from 'react'
 import { Panel } from 'ui-lab-components'
 import { ControlDef, ComponentDetail } from '@/types'
+import Example1, { metadata as metadata1 } from './examples/01-sidebar-toggle.js';
+import examplesJson from './examples.json' with { type: 'json' };
+import { loadComponentExamples } from '../../utils/load-component-examples.js';
+
+const examplesData = [
+  { id: '01-sidebar-toggle', Component: Example1, metadata: metadata1 },
+];
 
 const panelControls: ControlDef[] = [
   {
@@ -140,7 +147,9 @@ export const panelDetail: ComponentDetail = {
         </div>
       ),
     },
+    ...loadComponentExamples(examplesData, examplesJson),
   ],
 }
 
 export { panelControls }
+export * from './examples/index.js';

package/src/components/Path/examples/01-basic-path.tsx

@@ -1,4 +1,4 @@
-import { Path, PathItem } from 'ui-lab-components';
+import { Path } from 'ui-lab-components';
 
 export const metadata = {
   title: 'Basic Path',
@@ -8,10 +8,10 @@ export const metadata = {
 export default function Example() {
   return (
     <Path>
-      <PathItem href="/">Home</PathItem>
-      <PathItem href="/products">Products</PathItem>
-      <PathItem href="/products/electronics">Electronics</PathItem>
-      <PathItem>Laptop</PathItem>
+      <Path.Item href="/">Home</Path.Item>
+      <Path.Item href="/products">Products</Path.Item>
+      <Path.Item href="/products/electronics">Electronics</Path.Item>
+      <Path.Item>Laptop</Path.Item>
     </Path>
   );
 }

package/src/components/Path/examples/02-custom-separator.tsx

@@ -0,0 +1,17 @@
+import { Path } from "ui-lab-components";
+import { FaChevronRight } from "react-icons/fa6";
+
+export const metadata = {
+  title: "Custom Separator",
+  description: "Pass any node via the separator prop to replace the default slash.",
+};
+
+export default function Example() {
+  return (
+    <Path separator={<FaChevronRight className="w-3 h-3 text-foreground-400" />}>
+      <Path.Item href="/projects">Projects</Path.Item>
+      <Path.Item href="/projects/ui-lab">ui-lab</Path.Item>
+      <Path.Item>components</Path.Item>
+    </Path>
+  );
+}

package/src/components/Path/examples/03-collapsed-breadcrumb.tsx

@@ -0,0 +1,37 @@
+import { Path, Menu, Button } from "ui-lab-components";
+import { FaEllipsis } from "react-icons/fa6";
+
+export const metadata = {
+  title: "Collapsed Breadcrumb",
+  description: "Deep paths collapse intermediate crumbs into an ellipsis menu — Path.Item wraps the Menu trigger directly.",
+};
+
+const collapsed = [
+  { label: "Projects", href: "/projects" },
+  { label: "ui-lab", href: "/projects/ui-lab" },
+  { label: "packages", href: "/projects/ui-lab/packages" },
+];
+
+export default function Example() {
+  return (
+    <Path>
+      <Path.Item href="/">Home</Path.Item>
+      <Path.Item>
+        <Menu type="pop-over">
+          <Menu.Trigger>
+            <Button icon={<FaEllipsis />} styles="p-2" size="icon" variant="ghost" aria-label="Show collapsed path" />
+          </Menu.Trigger>
+          <Menu.Content align="start">
+            {collapsed.map((crumb) => (
+              <Menu.Item key={crumb.href} onSelect={() => {}}>
+                {crumb.label}
+              </Menu.Item>
+            ))}
+          </Menu.Content>
+        </Menu>
+      </Path.Item>
+      <Path.Item href="/projects/ui-lab/packages/@ui">@ui</Path.Item>
+      <Path.Item>Path.tsx</Path.Item>
+    </Path>
+  );
+}

package/src/components/Path/examples/index.ts

@@ -1,2 +1,6 @@
 export { default as Example1 } from './01-basic-path.js';
 export { metadata as metadata1 } from './01-basic-path.js';
+export { default as Example2 } from './02-custom-separator.js';
+export { metadata as metadata2 } from './02-custom-separator.js';
+export { default as Example3 } from './03-collapsed-breadcrumb.js';
+export { metadata as metadata3 } from './03-collapsed-breadcrumb.js';

package/src/components/Path/examples.json

@@ -2,6 +2,16 @@
   "01-basic-path": {
     "title": "Basic Path",
     "description": "A simple path navigation showing the current page location. Use this to help users understand their position in the site hierarchy.",
-    "code": "import { Path, PathItem } from 'ui-lab-components';\n\nexport default function Example() {\n  return (\n    <Path>\n      <PathItem href=\"/\">Home</PathItem>\n      <PathItem href=\"/products\">Products</PathItem>\n      <PathItem href=\"/products/electronics\">Electronics</PathItem>\n      <PathItem>Laptop</PathItem>\n    </Path>\n  );\n}"
+    "code": "import { Path } from 'ui-lab-components';\n\nexport default function Example() {\n  return (\n    <Path>\n      <Path.Item href=\"/\">Home</Path.Item>\n      <Path.Item href=\"/products\">Products</Path.Item>\n      <Path.Item href=\"/products/electronics\">Electronics</Path.Item>\n      <Path.Item>Laptop</Path.Item>\n    </Path>\n  );\n}"
+  },
+  "02-custom-separator": {
+    "title": "Custom Separator",
+    "description": "Pass any node via the separator prop to replace the default slash.",
+    "code": "import { Path } from \"ui-lab-components\";\nimport { FaChevronRight } from \"react-icons/fa6\";\n\nexport default function Example() {\n  return (\n    <Path separator={<FaChevronRight className=\"w-3 h-3 text-foreground-400\" />}>\n      <Path.Item href=\"/projects\">Projects</Path.Item>\n      <Path.Item href=\"/projects/ui-lab\">ui-lab</Path.Item>\n      <Path.Item>components</Path.Item>\n    </Path>\n  );\n}"
+  },
+  "03-collapsed-breadcrumb": {
+    "title": "Collapsed Breadcrumb",
+    "description": "Deep paths collapse intermediate crumbs into an ellipsis menu — Path.Item wraps the Menu trigger directly.",
+    "code": "import { Path, Menu, Button } from \"ui-lab-components\";\nimport { FaEllipsis } from \"react-icons/fa6\";\n\nconst collapsed = [\n  { label: \"Projects\", href: \"/projects\" },\n  { label: \"ui-lab\", href: \"/projects/ui-lab\" },\n  { label: \"packages\", href: \"/projects/ui-lab/packages\" },\n];\n\nexport default function Example() {\n  return (\n    <Path>\n      <Path.Item href=\"/\">Home</Path.Item>\n      <Path.Item>\n        <Menu type=\"pop-over\">\n          <Menu.Trigger>\n            <Button icon={<FaEllipsis />} styles=\"p-2\" size=\"icon\" variant=\"ghost\" aria-label=\"Show collapsed path\" />\n          </Menu.Trigger>\n          <Menu.Content align=\"start\">\n            {collapsed.map((crumb) => (\n              <Menu.Item key={crumb.href} onSelect={() => {}}>\n                {crumb.label}\n              </Menu.Item>\n            ))}\n          </Menu.Content>\n        </Menu>\n      </Path.Item>\n      <Path.Item href=\"/projects/ui-lab/packages/@ui\">@ui</Path.Item>\n      <Path.Item>Path.tsx</Path.Item>\n    </Path>\n  );\n}"
   }
 }

package/src/components/Path/index.tsx

@@ -1,22 +1,26 @@
 import React from 'react';
-import { Path, PathItem } from 'ui-lab-components';
+import { Path } from 'ui-lab-components';
 import { ComponentDetail } from '@/types';
 import Example1, { metadata as metadata1 } from './examples/01-basic-path.js';
+import Example2, { metadata as metadata2 } from './examples/02-custom-separator.js';
+import Example3, { metadata as metadata3 } from './examples/03-collapsed-breadcrumb.js';
 import examplesJson from './examples.json' with { type: 'json' };
 import { loadComponentExamples } from '../../utils/load-component-examples.js';
 
 const examplesData = [
   { id: '01-basic-path', Component: Example1, metadata: metadata1 },
+  { id: '02-custom-separator', Component: Example2, metadata: metadata2 },
+  { id: '03-collapsed-breadcrumb', Component: Example3, metadata: metadata3 },
 ];
 
-const pathBasicCode = `import { Path, PathItem } from "ui-lab-components";
+const pathBasicCode = `import { Path } from "ui-lab-components";
 
 export function Example() {
   return (
     <Path>
-      <PathItem href="/">Home</PathItem>
-      <PathItem href="/products">Products</PathItem>
-      <PathItem>Electronics</PathItem>
+      <Path.Item href="/">Home</Path.Item>
+      <Path.Item href="/products">Products</Path.Item>
+      <Path.Item>Electronics</Path.Item>
     </Path>
   );
 }`;
@@ -43,9 +47,9 @@ export const pathDetail: ComponentDetail = {
       code: pathBasicCode,
       preview: (
         <Path>
-          <PathItem href="/">Home</PathItem>
-          <PathItem href="/products">Products</PathItem>
-          <PathItem>Electronics</PathItem>
+          <Path.Item href="/">Home</Path.Item>
+          <Path.Item href="/products">Products</Path.Item>
+          <Path.Item>Electronics</Path.Item>
         </Path>
       ),
     },
@@ -59,9 +63,9 @@ export const pathDetail: ComponentDetail = {
       code: pathBasicCode,
       preview: (
         <Path>
-          <PathItem href="/">Home</PathItem>
-          <PathItem href="/products">Products</PathItem>
-          <PathItem>Electronics</PathItem>
+          <Path.Item href="/">Home</Path.Item>
+          <Path.Item href="/products">Products</Path.Item>
+          <Path.Item>Electronics</Path.Item>
         </Path>
       ),
     },

package/src/components/Popover/examples/01-basic-popover.tsx

@@ -1,15 +1,34 @@
-import React from 'react';
+"use client";
+
 import { Popover, Button } from 'ui-lab-components';
 
 export const metadata = {
-  title: 'Basic Popover',
-  description: 'A simple popover with a trigger button. Use this to display contextual content or actions.'
+  title: 'Basic',
+  description: 'Default popover with a short note and two clear actions.'
 };
 
 export default function Example() {
   return (
-    <Popover content={<p className="text-sm">This is popover content. It appears when you click the button.</p>}>
-      <Button>Click me</Button>
+    <Popover
+      content={
+        <div className="w-64 space-y-3">
+          <div className="space-y-1">
+            <div className="text-sm font-medium">Quick note</div>
+            <p>A popover works best when it adds one small piece of context, one simple choice, or one short action.</p>
+          </div>
+
+          <div className="flex items-center gap-2">
+            <Button variant="ghost" size="sm">
+              Dismiss
+            </Button>
+            <Button size="sm">
+              Continue
+            </Button>
+          </div>
+        </div>
+      }
+    >
+      <Button>Show info</Button>
     </Popover>
   );
 }

package/src/components/Popover/examples/02-toggleable-options.tsx

@@ -0,0 +1,58 @@
+"use client";
+
+import { useState } from 'react';
+import { Popover, Button, List } from 'ui-lab-components';
+
+export const metadata = {
+  title: 'Toggleable Options',
+  description: 'Popover containing a list of toggleable options using List.Item and List.Switch.'
+};
+
+const toggleableItems = [
+  { id: "notifications", label: "Notifications", desc: "Push and email alerts" },
+  { id: "autoSave", label: "Auto-save", desc: "Save changes automatically" },
+  { id: "darkMode", label: "Dark mode", desc: "Use dark color scheme" },
+];
+
+export default function Example() {
+  const [enabled, setEnabled] = useState<Set<string>>(
+    () => new Set(["notifications", "darkMode"])
+  );
+
+  const toggle = (id: string) =>
+    setEnabled((prev) => {
+      const next = new Set(prev);
+      next.has(id) ? next.delete(id) : next.add(id);
+      return next;
+    });
+
+  return (
+    <Popover
+      position="bottom"
+      content={
+        <List items={toggleableItems} spacing="sm" style={{ width: 280 }}>
+          {toggleableItems.map((item) => (
+            <List.Item
+              key={item.id}
+              value={item.id}
+              interactive
+              onClick={() => toggle(item.id)}
+            >
+              <div className="min-w-0 flex-1">
+                <List.Title>{item.label}</List.Title>
+                <List.Desc>{item.desc}</List.Desc>
+              </div>
+              <List.Switch
+                isSelected={enabled.has(item.id)}
+                onChange={() => toggle(item.id)}
+                aria-label={item.label}
+              />
+            </List.Item>
+          ))}
+        </List>
+      }
+    >
+      <Button>Options</Button>
+    </Popover>
+  );
+}

package/src/components/Popover/examples/03-table-row-actions.tsx

@@ -0,0 +1,64 @@
+"use client";
+
+import { Popover, Button, List } from 'ui-lab-components';
+import { FaEllipsis } from 'react-icons/fa6';
+
+export const metadata = {
+  title: 'Table Row Actions',
+  description: 'Per-row action menu in a data table, anchored to the overflow button.'
+};
+
+const rows = [
+  { id: "usr_1", name: "Alice", role: "Admin", status: "Active" },
+  { id: "usr_2", name: "Bob", role: "Member", status: "Invited" },
+  { id: "usr_3", name: "Carol", role: "Viewer", status: "Active" },
+];
+
+export default function Example() {
+  return (
+    <table className="w-full text-sm border-collapse">
+      <thead>
+        <tr className="border-b border-background-700">
+          <th className="text-left py-2 px-3 font-medium text-foreground-200">Name</th>
+          <th className="text-left py-2 px-3 font-medium text-foreground-200">Role</th>
+          <th className="text-left py-2 px-3 font-medium text-foreground-200">Status</th>
+          <th className="py-2 px-3" />
+        </tr>
+      </thead>
+      <tbody>
+        {rows.map((row) => (
+          <tr key={row.id} className="border-b border-background-700 last:border-0">
+            <td className="py-2 px-3">{row.name}</td>
+            <td className="py-2 px-3 text-foreground-200">{row.role}</td>
+            <td className="py-2 px-3 text-foreground-200">{row.status}</td>
+            <td className="py-2 px-3 text-right">
+              <Popover
+                position="left"
+                content={
+                  <List gap="sm" styles={{ root: "w-full" }}>
+                    <Button
+                      variant="ghost"
+                      size="sm"
+                      styles={{ root: "justify-start" }}
+                    >
+                      Edit {row.name}
+                    </Button>
+                    <Button
+                      variant="danger"
+                      size="sm"
+                      styles={{ root: "justify-start" }}
+                    >
+                      Remove {row.name}
+                    </Button>
+                  </List>
+                }
+              >
+                <Button icon={<FaEllipsis />} styles="p-2" size="icon" variant="ghost" aria-label={`Row actions for ${row.name}`} />
+              </Popover>
+            </td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}