blixify-ui-web-mcp 0.1.2 → 0.1.18

package/lib/components/navigation/breadcrumb/README.md

@@ -4,7 +4,7 @@
 
 <hr>
 
-Breadcrumb for selected item navigation
+A breadcrumb trail for hierarchical navigation. Renders a home icon followed by a chevron-separated list of pages. Non-current pages are links; the current page is plain text.
 
 ##### Import
 
@@ -14,35 +14,55 @@ import { Breadcrumb } from "blixify-ui-web/components/navigation/breadcrumb";
 
 ##### Usage
 
+Link-based navigation:
+
 ```jsx
 const pages = [
-  { name: "Projects", href: "#", current: false },
-  { name: "Project Nero", href: "#", current: true },
+  { name: "Projects", href: "/projects", current: false },
+  { name: "Project Nero", href: "/projects/nero", current: true },
 ];
 
-stories.add("Breadcrumb", () => {
-  return <Breadcrumb pages={pages} />;
-});
+<Breadcrumb pages={pages} />;
+```
+
+Programmatic navigation with onClick:
+
+```jsx
+<Breadcrumb
+  pages={pages}
+  onClick={(name) => {
+    // name is the page.name of the clicked item
+    router.push(name);
+  }}
+/>
+```
+
+Dark mode:
+
+```jsx
+<Breadcrumb pages={pages} darkMode={true} />
 ```
 
 ##### Required props
 
-| Name    | Type              | Description     |
-| ------- | ----------------- | --------------- |
-| `pages` | `Page Class List` | Page Class List |
+| Name    | Type     | Description                        |
+| ------- | -------- | ---------------------------------- |
+| `pages` | `Page[]` | Ordered list of pages in the trail |
 
 ##### Optional props
 
-| Name        | Type             | Default    | Description |
-| ----------- | ---------------- | ---------- | ----------- |
-| `className` | `tailwind class` | ""         |             |
-| `onClick`   | `function`       | `() => {}` |             |
+| Name        | Type                                                       | Default | Description                                                                                                |
+| ----------- | ---------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------- |
+| `onClick`   | `(name: string) => void`                                   | —       | When provided, non-current pages render as clickable divs instead of links. Called with the page's `name`. |
+| `darkMode`  | `boolean`                                                  | `false` | Switches the home icon and current-page text to white for use on dark backgrounds.                         |
+| `className` | `string`                                                   | —       | Tailwind classes applied to the outer `<nav>` element.                                                     |
+| `linkType`  | `"react" \| "gatsby" \| "next" \| "external" \| "default"` | —       | Router adapter for link rendering. Pass alongside `custom` when using React Router, Gatsby, or Next.js.    |
+| `custom`    | `any`                                                      | —       | The custom link component to use when `linkType` is `"react"`, `"gatsby"`, or `"next"`.                    |
 
-##### Page Class props
+##### Page
 
-| Name        | Type               | Default                                        | Description             |
-| ----------- | ------------------ | ---------------------------------------------- | ----------------------- |
-| `name`      | `string`           | ""                                             |                         |
-| `href`      | `string`           | ""                                             |                         |
-| `current`   | `boolean`          | false                                          | Whether page is current |
-| `linkProps` | `Link Props Class` | Refer to Link Component for more documentation |                         |
+| Name      | Type      | Description                                                               |
+| --------- | --------- | ------------------------------------------------------------------------- |
+| `name`    | `string`  | Display label for the breadcrumb item                                     |
+| `href`    | `string`  | URL for the link. Used when `onClick` is not provided.                    |
+| `current` | `boolean` | Marks this item as the current page — rendered as plain text, not a link. |

package/lib/components/navigation/breadcrumb/breadcrumb.stories.tsx

@@ -1,27 +1,47 @@
-import { storiesOf } from "@storybook/react";
-import React from "react";
+import React, { useState } from "react";
 import { Breadcrumb } from ".";
-import README from "./README.md";
-const stories = storiesOf("Navigation", module);
+import { StorySection } from "../../storyUtils";
+
+const meta = { title: "Navigation/Breadcrumb" };
+export default meta;
 
-stories.addParameters({
-  readme: {
-    content: README,
-  },
-});
 
 const pages = [
   { name: "Projects", href: "#", current: false },
   { name: "Project Nero", href: "#", current: true },
 ];
 
-stories.add("Breadcrumb", () => {
+export const BreadcrumbStory = () => {
+  const [selected, setSelected] = useState("");
+
   return (
     <>
-      <Breadcrumb pages={pages} />
-      <div className="bg-gray-900 py-2">
+      <StorySection
+        title="Default"
+        description="Each non-current page renders as a link using its href. The current page is rendered as plain text."
+      >
+        <Breadcrumb pages={pages} />
+      </StorySection>
+
+      <StorySection
+        title="With onClick"
+        description="Pass onClick to handle navigation programmatically. The page name is passed as the argument. Useful for SPAs where you manage routing yourself."
+      >
+        <div className="flex flex-col items-center gap-2">
+          <Breadcrumb pages={pages} onClick={(name) => setSelected(name)} />
+          {selected && (
+            <p className="text-sm text-gray-500">Clicked: {selected}</p>
+          )}
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Dark Mode"
+        description="Pass darkMode=true for use on dark backgrounds."
+        dark
+      >
         <Breadcrumb pages={pages} darkMode={true} />
-      </div>
+      </StorySection>
     </>
   );
-});
+}

package/lib/components/navigation/header/README.md

@@ -4,7 +4,7 @@
 
 <hr>
 
-Header for Application UI for Normal User
+A responsive application header with a logo, navigation links, an optional user avatar dropdown, and mobile hamburger menu. Navigation items can have a Popover dropdown (`multiNav`) for grouped sub-links. Supports dark mode, transparent background, and an extra slot for custom elements.
 
 ##### Import
 
@@ -15,135 +15,94 @@ import { Header } from "blixify-ui-web/components/navigation/header";
 ##### Usage
 
 ```jsx
-const multiNavigation = [
-  {
-    name: "Section 1",
-    href: "/dashboard/section1",
-    description:
-      "This is a dropdown section that allows you navigate to section 1",
-    icon: PhoneIcon,
-  },
-  {
-    name: "Section 2",
-    href: "/dashboard/section2",
-    description:
-      "This is a dropdown section that allows you navigate to section 2",
-    icon: ComputerDesktopIcon,
-  },
-  {
-    name: "Section 3",
-    href: "/dashboard/section3",
-    description:
-      "This is a dropdown section that allows you navigate to section 3",
-    icon: BookOpenIcon,
-  },
-  {
-    name: "Section 4",
-    href: "/dashboard/section4",
-    description:
-      "This is a dropdown section that allows you navigate to section 4",
-    icon: MapIcon,
-  },
-];
+import { Disclosure, Menu, Popover, Transition } from "@headlessui/react";
+import { PhoneIcon } from "@heroicons/react/20/solid";
 
 const navigation = [
   { name: "Dashboard", href: "/dashboard" },
   {
     name: "Activities",
-    href: "/dashboard/logistic",
-    multiNav: multiNavigation,
+    href: "/dashboard/activities",
+    multiNav: [
+      {
+        name: "Section 1",
+        href: "/dashboard/section1",
+        description: "Go to section 1",
+        icon: PhoneIcon,
+      },
+    ],
   },
-  { name: "Records", href: "/dashboard/transaction" },
-  { name: "Donees", href: "/dashboard/orgs" },
   { name: "FAQ", href: "https://google.com", openInNewTab: true },
 ];
 
-const [modal, setModal] = useState(false);
-
-const handleSwapAccount = () => {
-  setModal(!modal);
-  window.alert("Swap account clicked");
-};
-
 const userNavigation = [
   { name: "My Profile", href: "/dashboard/profile" },
   {
     name: "Swap Account",
-    customAction: handleSwapAccount,
+    customAction: () => alert("swap"),
     notification: true,
   },
   { name: "Sign out", action: "logout", href: "#" },
 ];
 
-return (
-  <div className="bg-gray-100">
-    <Header
-      defaultNav="/"
-      page="Activities"
-      transparent={true}
-      logo={Logo}
-      navigation={navigation}
-      userNavigation={userNavigation}
-      user={{
-        name: "Louis Ong",
-        email: "louis@blixify.co",
-        image: Favicon,
-      }}
-      lib={{
-        Disclosure,
-        Menu,
-        Transition,
-        Popover,
-      }}
-    />
-  </div>
-);
+<Header
+  defaultNav="/"
+  page="Dashboard"
+  logo={Logo}
+  navigation={navigation}
+  userNavigation={userNavigation}
+  user={{ name: "Jane Doe", email: "jane@example.com", image: Avatar }}
+  lib={{ Disclosure, Menu, Transition, Popover }}
+/>;
 ```
 
 ##### Required props
 
-| Name             | Type             | Description                                   |
-| ---------------- | ---------------- | --------------------------------------------- |
-| `defaultNav`     | `string`         | Default path once logo is selected            |
-| `page`           | `string`         | Current selected path according to navigation |
-| `logo`           | `string`         | Logo                                          |
-| `navigation`     | `Navigation`     | Class                                         |
-| `userNavigation` | `UserNavigation` | Class                                         |
-| `lib`            | `class`          | Class                                         |
+| Name         | Type                                        | Description                                                               |
+| ------------ | ------------------------------------------- | ------------------------------------------------------------------------- |
+| `defaultNav` | `string`                                    | URL the logo links to                                                     |
+| `page`       | `string`                                    | Name of the currently active navigation item — used to highlight the link |
+| `logo`       | `string`                                    | Image src for the logo                                                    |
+| `navigation` | `Navigation[]`                              | Ordered list of nav links — see Navigation below                          |
+| `lib`        | `{ Disclosure, Menu, Transition, Popover }` | Headless UI components passed in to avoid bundling conflicts              |
 
 ##### Optional props
 
-| Name          | Type               | Default                                        | Description                                             |
-| ------------- | ------------------ | ---------------------------------------------- | ------------------------------------------------------- |
-| `user`        | `class`            | `null `                                        |                                                         |
-| `transparent` | `boolean`          | `false`                                        | Make background transparent                             |
-| `linkProps`   | `Link Props Class` | Refer to Link Component for more documentation |                                                         |
-| `extra`       | `React Element`    | `null`                                         | React Element placed on the left of userNavigation menu |
-
-##### Navigation props
-
-| Name           | Type                   | Description                              |
-| -------------- | ---------------------- | ---------------------------------------- |
-| `name`         | `string`               | Name of path                             |
-| `href`         | `string`               | Url                                      |
-| `multiNav`     | `Multi Nav List Class` | Optional for multiple navigation list    |
-| `openInNewTab` | `boolean`              | Optional. If true, opens link in new tab |
-
-##### UserNavigation props
-
-| Name           | Type       | Description    |
-| -------------- | ---------- | -------------- |
-| `name`         | `string`   | Name of path   |
-| `href`         | `string`   | Url            |
-| `notification` | `boolean`  | True or false  |
-| `action`       | `function` | Trigger logout |
-| `customAction` | `function` | Optional       |
-
-##### Multi Navigation props
-
-| Name          | Type            | Description  |
-| ------------- | --------------- | ------------ |
-| `name`        | `string`        | Name of path |
-| `href`        | `string`        | Url          |
-| `icon`        | `React Element` |              |
-| `description` | `string`        |              |
+| Name             | Type                                                       | Default | Description                                                                                      |
+| ---------------- | ---------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------ |
+| `userNavigation` | `UserNavigation[]`                                         | —       | Items shown in the user avatar dropdown — see UserNavigation below                               |
+| `user`           | `{ name: string; email: string; image: string }`           | —       | When provided, renders an avatar button that opens the user dropdown                             |
+| `transparent`    | `boolean`                                                  | `false` | Removes the background colour and shadow. Useful over hero images or coloured banners.           |
+| `darkMode`       | `boolean`                                                  | `false` | Switches text and backgrounds to a dark theme                                                    |
+| `extra`          | `ReactElement`                                             | —       | Element rendered to the left of the user avatar. Use for search inputs, notification bells, etc. |
+| `signOut`        | `() => void`                                               | —       | Custom sign-out handler. Called when a `UserNavigation` item with `action: "logout"` is clicked. |
+| `linkType`       | `"react" \| "gatsby" \| "next" \| "external" \| "default"` | —       | Router adapter for all link rendering                                                            |
+| `custom`         | `any`                                                      | —       | Custom link component used when `linkType` is `"react"`, `"gatsby"`, or `"next"`                 |
+
+##### Navigation
+
+| Name           | Type                | Description                                                                     |
+| -------------- | ------------------- | ------------------------------------------------------------------------------- |
+| `name`         | `string`            | Display label and the value matched against `page` to highlight the active item |
+| `href`         | `string`            | URL for the link                                                                |
+| `multiNav`     | `MultiNavigation[]` | Optional — when provided, renders a Popover dropdown instead of a direct link   |
+| `openInNewTab` | `boolean`           | When `true`, opens the link in a new tab                                        |
+
+##### MultiNavigation
+
+| Name          | Type     | Description                                         |
+| ------------- | -------- | --------------------------------------------------- |
+| `name`        | `string` | Sub-item display label                              |
+| `href`        | `string` | URL for the sub-item link                           |
+| `icon`        | `any`    | Heroicon or SVG component shown beside the sub-item |
+| `description` | `string` | Short description shown below the sub-item name     |
+
+##### UserNavigation
+
+| Name           | Type               | Description                                                                                 |
+| -------------- | ------------------ | ------------------------------------------------------------------------------------------- |
+| `name`         | `string`           | Display label                                                                               |
+| `href`         | `string`           | URL — used when neither `action` nor `customAction` is set                                  |
+| `action`       | `string`           | Set to `"logout"` to trigger the `signOut` handler instead of navigating                    |
+| `customAction` | `(e: any) => void` | Custom click handler. When set, renders the item as a `<span>` instead of a link.           |
+| `notification` | `boolean`          | When `true`, shows an animated ping badge on the avatar button to indicate a pending action |

package/lib/components/navigation/header/header.stories.tsx

@@ -1,3 +1,4 @@
+import React from "react";
 import { Disclosure, Menu, Popover, Transition } from "@headlessui/react";
 import {
   BookOpenIcon,
@@ -5,48 +6,41 @@ import {
   MapIcon,
   PhoneIcon,
 } from "@heroicons/react/20/solid";
-import { storiesOf } from "@storybook/react";
-import React, { useState } from "react";
+import { useState } from "react";
 import { Header } from ".";
 import Favicon from "../../../assets/favicon.png";
 import Logo from "../../../assets/logo.png";
-import README from "./README.md";
+import { StorySection } from "../../storyUtils";
 
-const stories = storiesOf("Navigation", module);
+const meta = { title: "Navigation/Header" };
+export default meta;
 
-stories.addParameters({
-  readme: {
-    content: README,
-  },
-});
+
+const lib = { Disclosure, Menu, Transition, Popover };
 
 const multiNavigation = [
   {
     name: "Section 1",
     href: "/dashboard/section1",
-    description:
-      "This is a dropdown section that allows you navigate to section 1",
+    description: "Navigate to section 1",
     icon: PhoneIcon,
   },
   {
     name: "Section 2",
     href: "/dashboard/section2",
-    description:
-      "This is a dropdown section that allows you navigate to section 2",
+    description: "Navigate to section 2",
     icon: ComputerDesktopIcon,
   },
   {
     name: "Section 3",
     href: "/dashboard/section3",
-    description:
-      "This is a dropdown section that allows you navigate to section 3",
+    description: "Navigate to section 3",
     icon: BookOpenIcon,
   },
   {
     name: "Section 4",
     href: "/dashboard/section4",
-    description:
-      "This is a dropdown section that allows you navigate to section 4",
+    description: "Navigate to section 4",
     icon: MapIcon,
   },
 ];
@@ -55,53 +49,175 @@ const navigation = [
   { name: "Dashboard", href: "/dashboard" },
   {
     name: "Activities",
-    href: "/dashboard/logistic",
+    href: "/dashboard/activities",
     multiNav: multiNavigation,
   },
-  { name: "Records", href: "/dashboard/transaction" },
-  { name: "Donees", href: "/dashboard/orgs" },
+  { name: "Records", href: "/dashboard/records" },
   { name: "FAQ", href: "https://google.com", openInNewTab: true },
 ];
 
-stories.add("Header", () => {
-  const [modal, setModal] = useState(false);
+const user = {
+  name: "Louis Ong",
+  email: "louis@blixify.co",
+  image: Favicon,
+};
 
-  const handleSwapAccount = () => {
-    setModal(!modal);
-    window.alert("Swap account clicked");
-  };
+export const HeaderStory = () => {
+  const [page] = useState("Dashboard");
 
   const userNavigation = [
     { name: "My Profile", href: "/dashboard/profile" },
     {
       name: "Swap Account",
-      customAction: handleSwapAccount,
+      customAction: () => window.alert("Swap account clicked"),
       notification: true,
     },
     { name: "Sign out", action: "logout", href: "#" },
   ];
 
   return (
-    <div className="bg-gray-100">
-      <Header
-        defaultNav="/"
-        page="Activities"
-        transparent={true}
-        logo={Logo}
-        navigation={navigation}
-        userNavigation={userNavigation}
-        user={{
-          name: "Louis Ong",
-          email: "louis@blixify.co",
-          image: Favicon,
-        }}
-        lib={{
-          Disclosure,
-          Menu,
-          Transition,
-          Popover,
-        }}
-      />
-    </div>
+    <>
+      <StorySection
+        title="Default"
+        description="Standard header with logo, nav links, and a user avatar dropdown. page highlights the active nav item. Resize the window to see the mobile hamburger menu."
+      >
+        <div className="w-full bg-gray-100">
+          <Header
+            defaultNav="/"
+            page={page}
+            logo={Logo}
+            navigation={navigation}
+            userNavigation={userNavigation}
+            user={user}
+            lib={lib}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Transparent Background"
+        description="transparent=true removes the background and shadow. Useful when the header sits over a hero image or coloured banner."
+      >
+        <div className="w-full bg-primary-50 rounded-lg">
+          <Header
+            defaultNav="/"
+            page={page}
+            logo={Logo}
+            navigation={navigation}
+            userNavigation={userNavigation}
+            user={user}
+            transparent={true}
+            lib={lib}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Dropdown Navigation (multiNav)"
+        description="Add multiNav to a Navigation item to render a Popover dropdown with icon, name, and description for each sub-item. Click 'Activities' to see it."
+      >
+        <div className="w-full bg-gray-100">
+          <Header
+            defaultNav="/"
+            page="Activities"
+            logo={Logo}
+            navigation={navigation}
+            userNavigation={userNavigation}
+            user={user}
+            lib={lib}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Notification Badge"
+        description="Set notification=true on a UserNavigation item to show an animated ping badge on the avatar button, indicating a pending action."
+      >
+        <div className="w-full bg-gray-100">
+          <Header
+            defaultNav="/"
+            page={page}
+            logo={Logo}
+            navigation={navigation}
+            userNavigation={userNavigation}
+            user={user}
+            lib={lib}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Extra Element"
+        description="extra renders a ReactElement to the left of the user avatar. Useful for search inputs, notification bells, or action buttons."
+      >
+        <div className="w-full bg-gray-100">
+          <Header
+            defaultNav="/"
+            page={page}
+            logo={Logo}
+            navigation={navigation}
+            userNavigation={userNavigation}
+            user={user}
+            extra={
+              <button className="mr-3 text-sm text-primary-600 font-medium border border-primary-300 rounded-md px-3 py-1">
+                Upgrade
+              </button>
+            }
+            lib={lib}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="No User (Public Header)"
+        description="Omit user and userNavigation to render a header without the avatar dropdown. Suitable for public-facing pages."
+      >
+        <div className="w-full bg-gray-100">
+          <Header
+            defaultNav="/"
+            page={page}
+            logo={Logo}
+            navigation={navigation}
+            lib={lib}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Dark Mode"
+        description="darkMode=true switches text and backgrounds to a dark theme."
+        dark
+      >
+        <div className="w-full bg-gray-900 rounded-lg">
+          <Header
+            defaultNav="/"
+            page={page}
+            logo={Logo}
+            navigation={navigation}
+            userNavigation={userNavigation}
+            user={user}
+            darkMode={true}
+            lib={lib}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Empty Navigation (no hamburger, no divider)"
+        description="When navigation=[] the hamburger is hidden on mobile. The user avatar and dropdown show directly on all screen sizes, same as the desktop web view."
+      >
+        <div className="w-full bg-gray-100">
+          <Header
+            defaultNav="/"
+            page={page}
+            logo={Logo}
+            navigation={[]}
+            userNavigation={userNavigation}
+            user={user}
+            lib={lib}
+          />
+        </div>
+      </StorySection>
+    </>
   );
-});
+}