blixify-ui-web-mcp 0.1.2 → 0.1.3

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

@@ -4,88 +4,143 @@
 
 <hr>
 
-Left Nav for Dashboard Template
+A full-page dashboard layout with a collapsible left sidebar, top header bar, and main content area. The sidebar renders navigation items via the `Bars` component and supports drag-to-reorder, grouped items, a footer slot, dark mode, and a mobile overlay menu.
 
 ##### Import
 
 ```js
+import { LeftNav } from "blixify-ui-web/components/navigation/leftNav";
+```
+
+##### Usage
+
+Basic setup:
+
+```jsx
 const [mobile, setMobile] = useState(false);
+const [selectedId, setSelectedId] = useState("dashboard");
+
 const navigation = [
+  { id: "dashboard", name: "Dashboard", href: "/dashboard", icon: HomeIcon },
   {
-    id: "inspection",
-    name: "Inspection",
-    href: "/dashboard",
-    icon: HomeIcon,
+    id: "reports",
+    name: "Reports",
+    href: "/dashboard/reports",
+    icon: FolderIcon,
   },
+];
+
+<LeftNav
+  selectedId={selectedId}
+  navigation={navigation}
+  leftNavMobileMenu={mobile}
+  handleBarsOnClick={(id) => setSelectedId(id)}
+  handleToggleLeftNavMobileMenu={() => setMobile(!mobile)}
+  renderDashboardLogo={() => (
+    <img className="h-10 w-auto" src={Logo} alt="Logo" />
+  )}
+  renderDashboardContent={() => <div className="p-6">Content</div>}
+  renderDashboardHeaderContent={() => <span>Page Title</span>}
+/>;
+```
+
+Collapsible sidebar:
+
+```jsx
+const [collapse, setCollapse] = useState(false);
+
+<LeftNav
+  selectedId={selectedId}
+  navigation={navigation}
+  leftNavMobileMenu={mobile}
+  transition={{ headerVisible: true, collapse }}
+  handleToggleCollapse={() => setCollapse(!collapse)}
+  handleToggleLeftNavMobileMenu={() => setMobile(!mobile)}
+  renderDashboardLogo={() => <img className="h-10 w-auto" src={Logo} />}
+  renderDashboardContent={() => <div className="p-6">Content</div>}
+  renderDashboardHeaderContent={() => <span>Page Title</span>}
+/>;
+```
+
+Draggable with grouped items:
+
+```jsx
+const navigation = [
+  { id: "dashboard", name: "Dashboard", href: "/dashboard", icon: HomeIcon },
   {
-    id: "defects",
-    name: "Defects",
-    href: "/dashboard/defects",
-    icon: FolderIcon,
+    id: "engineering",
+    name: "Engineering",
+    href: "/teams/eng",
+    icon: UsersIcon,
+    groupId: "People",
+  },
+  {
+    id: "hr",
+    name: "HR",
+    href: "/teams/hr",
+    icon: UsersIcon,
+    groupId: "People",
   },
 ];
 
-return (
-  <LeftNav
-    selectedId="inspection"
-    draggable={true}
-    navigation={navigation}
-    leftNavMobileMenu={mobile}
-    handleChangeNavigation={(value) => {
-      setNavigation(value);
-    }}
-    handleToggleLeftNavMobileMenu={() => {
-      setMobile(!mobile);
-    }}
-    renderDashboardLogo={() => (
-      <div className="flex items-center flex-shrink-0 px-6 cursor-pointer">
-        <img className="h-10 w-auto" src={Logo} alt="Favicon" />
-      </div>
-    )}
-    renderDashboardContent={() => {}}
-    renderDashboardHeaderContent={() => {}}
-  />
-);
+<LeftNav
+  selectedId={selectedId}
+  navigation={navigation}
+  leftNavMobileMenu={false}
+  draggable={true}
+  handleChangeNavigation={(value) => setNavigation(value)}
+  handleDropEnd={() => {}}
+  handleToggleLeftNavMobileMenu={() => {}}
+  renderDashboardLogo={() => <img className="h-10 w-auto" src={Logo} />}
+  renderDashboardContent={() => <div className="p-6">Content</div>}
+  renderDashboardHeaderContent={() => <span>Page Title</span>}
+/>;
 ```
 
 ##### Required props
 
-| Name                            | Type              | Description                    |
-| ------------------------------- | ----------------- | ------------------------------ |
-| `selectedId`                    | `string`          | Selected ID of navigation      |
-| `navigation`                    | `Navigation List` | Navigation list to render bars |
-| `leftNavMobileMenu`             | `boolean`         | Mobile menu activation         |
-| `bgColor`                       | `string`          | Content background color       |
-| `handleToggleLeftNavMobileMenu` | `function`        | Toggle mobile menu activation  |
-| `renderDashboardLogo`           | `function`        | Render Logo                    |
-| `renderDashboardContent`        | `function`        | Render Content                 |
-| `renderDashboardHeaderContent`  | `function`        | Render Header Content          |
+| Name                            | Type              | Description                                        |
+| ------------------------------- | ----------------- | -------------------------------------------------- |
+| `selectedId`                    | `string`          | The `id` of the currently active navigation item   |
+| `navigation`                    | `Navigation[]`    | Ordered list of nav items — see Navigation below   |
+| `leftNavMobileMenu`             | `boolean`         | Controls whether the mobile overlay menu is open   |
+| `handleToggleLeftNavMobileMenu` | `() => void`      | Called when the mobile hamburger button is clicked |
+| `renderDashboardLogo`           | `() => ReactNode` | Renders the logo at the top of the sidebar         |
+| `renderDashboardContent`        | `() => ReactNode` | Renders the main page content area                 |
+| `renderDashboardHeaderContent`  | `() => ReactNode` | Renders content inside the top header bar          |
 
 ##### Optional props
 
-| Name                           | Type               | Default                                          | Description                                                     |
-| ------------------------------ | ------------------ | ------------------------------------------------ | --------------------------------------------------------------- |
-| `draggable`                    | `boolean`          | `false`                                          | `Make component items draggable`                                |
-| `handleChangeNavigation`       | `function`         | `(value) => {setNavigation(value)}`              | `Required when draggable is true`                               |
-| `handleDropEnd`                | `function`         | `(value) => {}`                                  | `Required when draggable is true`                               |
-| `renderDashboardFooterContent` | `function`         | `null`                                           | `Render Left Nav Footer`                                        |
-| `linkProps`                    | `Link Props Class` | `Refer to Link Component for more documentation` |                                                                 |
-| `transition`                   | `Transition Class` | `null`                                           |                                                                 |
-| `handleToggleCollapse`         | `function`         | `() => {}`                                       | `Required when transition exist`                                |
-| `handleBarsOnClick`            | `function`         | `(id:string) => {}`                              | `Used for single page rendering setState instead of navigation` |
-
-##### Navigation Class
-
-| Name   | Type            | Default | Description        |
-| ------ | --------------- | ------- | ------------------ |
-| `id`   | `string`        | ""      | ID of Menu         |
-| `name` | `string`        | ""      | Name of Menu       |
-| `href` | `string`        | ""      | Page Href          |
-| `icon` | `React Element` | ``      | Hero Icons Element |
-
-##### Transition Class
-
-| Name            | Type      | Default | Description                               |
-| --------------- | --------- | ------- | ----------------------------------------- |
-| `headerVisible` | `boolean` | "true"  | Render Header if it is true               |
-| `collapse`      | `boolean` | "false" | Left nav will be collapse when it is true |
+| Name                           | Type                                                       | Default | Description                                                                                                 |
+| ------------------------------ | ---------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
+| `draggable`                    | `boolean`                                                  | `false` | Enables drag-to-reorder on nav items. Requires `handleChangeNavigation`.                                    |
+| `handleChangeNavigation`       | `(value: Navigation[]) => void`                            | —       | Called with the updated nav array after each drag move. Required when `draggable` is `true`.                |
+| `handleDropEnd`                | `() => void`                                               | —       | Called when a drag interaction ends. Required when `draggable` is `true`.                                   |
+| `handleBarsOnClick`            | `(id: string) => void`                                     | —       | Called with the nav item `id` when clicked. Use instead of href navigation for single-page apps.            |
+| `handleToggleCollapse`         | `() => void`                                               | —       | Called when the collapse arrow is clicked. Required when `transition` is set.                               |
+| `transition`                   | `{ headerVisible?: boolean; collapse?: boolean }`          | —       | Controls sidebar collapse and header visibility — see Transition below.                                     |
+| `darkMode`                     | `boolean`                                                  | `false` | Switches the sidebar and header to a dark theme                                                             |
+| `bgColor`                      | `string`                                                   | —       | Tailwind bg class for the outer page background. Defaults to `bg-gray-100` (light) or `bg-gray-900` (dark). |
+| `navbarBgColor`                | `string`                                                   | —       | Tailwind bg class for the sidebar and header bar. Defaults to `bg-white` (light) or `bg-gray-800` (dark).   |
+| `renderDashboardFooterContent` | `() => ReactNode`                                          | —       | Renders a slot at the bottom of the sidebar, above a border separator                                       |
+| `dashboardFooterClassName`     | `string`                                                   | —       | Tailwind classes applied to the footer slot container                                                       |
+| `dashboardContentClassName`    | `string`                                                   | —       | Tailwind classes applied to the main content `<main>` element                                               |
+| `linkType`                     | `"react" \| "gatsby" \| "next" \| "external" \| "default"` | —       | Router adapter passed through to nav links                                                                  |
+| `custom`                       | `any`                                                      | —       | Custom link component used when `linkType` is `"react"`, `"gatsby"`, or `"next"`                            |
+
+##### Navigation
+
+| Name      | Type     | Description                                                                                                |
+| --------- | -------- | ---------------------------------------------------------------------------------------------------------- |
+| `id`      | `string` | Unique identifier — matched against `selectedId` to highlight the active item                              |
+| `name`    | `string` | Display label                                                                                              |
+| `href`    | `string` | URL used when `handleBarsOnClick` is not provided                                                          |
+| `icon`    | `any`    | Heroicon or SVG component rendered beside the label                                                        |
+| `groupId` | `string` | Optional — items sharing the same `groupId` are nested under a collapsible group labelled with that string |
+
+##### Transition
+
+| Name            | Type      | Description                                                                                          |
+| --------------- | --------- | ---------------------------------------------------------------------------------------------------- |
+| `collapse`      | `boolean` | When `true`, the sidebar collapses to icon-only width. Requires `handleToggleCollapse`.              |
+| `headerVisible` | `boolean` | When `false`, the top header bar is hidden on desktop (still shown on mobile for the hamburger menu) |

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

@@ -1,7 +1,8 @@
-import { FolderIcon, HomeIcon } from "@heroicons/react/24/outline";
+import { FolderIcon, HomeIcon, UsersIcon } from "@heroicons/react/24/outline";
 import { storiesOf } from "@storybook/react";
-import React, { useEffect, useState } from "react";
+import React, { useState } from "react";
 import { LeftNav } from ".";
+import { StorySection } from "../../storyUtils";
 import Logo from "../../../assets/logo.png";
 import README from "./README.md";
 
@@ -13,94 +14,186 @@ stories.addParameters({
   },
 });
 
-stories.add("LeftNav", () => {
-  useEffect(() => {
-    window.addEventListener("resize", checkViewportWidth);
+const baseNavigation = [
+  { id: "dashboard", name: "Dashboard", href: "/dashboard", icon: HomeIcon },
+  {
+    id: "defects",
+    name: "Defects",
+    href: "/dashboard/defects",
+    icon: FolderIcon,
+  },
+  {
+    id: "reports",
+    name: "Reports",
+    href: "/dashboard/reports",
+    icon: FolderIcon,
+  },
+];
+
+const groupedNavigation = [
+  { id: "dashboard", name: "Dashboard", href: "/dashboard", icon: HomeIcon },
+  {
+    id: "teams",
+    name: "Teams",
+    href: "/teams",
+    icon: UsersIcon,
+    groupId: "People",
+  },
+  {
+    id: "engineering",
+    name: "Engineering",
+    href: "/teams/engineering",
+    icon: UsersIcon,
+    groupId: "People",
+  },
+  {
+    id: "hr",
+    name: "Human Resources",
+    href: "/teams/hr",
+    icon: UsersIcon,
+    groupId: "People",
+  },
+  {
+    id: "defects",
+    name: "Defects",
+    href: "/dashboard/defects",
+    icon: FolderIcon,
+  },
+];
 
-    return () => {
-      window.removeEventListener("resize", checkViewportWidth);
-    };
-  });
+const renderLogo = (collapse?: boolean) => (
+  <div className="flex items-center flex-shrink-0 px-6 cursor-pointer">
+    <img
+      className={`h-10 ${
+        collapse ? "w-1/4 object-contain lg:hidden" : "w-auto"
+      }`}
+      src={Logo}
+      alt="Logo"
+    />
+  </div>
+);
 
-  const [mobile, setMobile] = useState(false);
-  const [navigation, setNavigation] = useState([
-    {
-      id: "inspection",
-      name: "Inspection",
-      href: "/dashboard",
-      icon: HomeIcon,
-    },
-    {
-      id: "teams",
-      name: "Teams",
-      href: "/team",
-      icon: HomeIcon,
-      groupId: "team",
-    },
-    {
-      id: "engineering",
-      name: "Engineering",
-      href: "/teams/engineering",
-      icon: HomeIcon,
-      groupId: "team",
-    },
-    {
-      id: "human_resources",
-      name: "Human Resources",
-      href: "/teams/hr",
-      icon: HomeIcon,
-      groupId: "team",
-    },
-    {
-      id: "defects",
-      name: "Defects",
-      href: "/dashboard/defects",
-      icon: FolderIcon,
-    },
-  ]);
+const renderContent = () => (
+  <div className="p-6 text-gray-500 text-sm">Dashboard content goes here.</div>
+);
 
-  const [collapse, setCollapse] = useState(false);
+const renderHeader = () => (
+  <div className="px-4 text-sm font-medium text-gray-700">Page Title</div>
+);
 
-  const checkViewportWidth = () => {
-    const laptop = 1024;
-    if (window.innerWidth <= laptop) {
-      setCollapse(false);
-    }
-  };
+stories.add("LeftNav", () => {
+  const [mobile, setMobile] = useState(false);
+  const [selectedId, setSelectedId] = useState("dashboard");
+  const [navigation] = useState(baseNavigation);
+  const [collapse, setCollapse] = useState(false);
+  const [groupedNav, setGroupedNav] = useState(groupedNavigation);
+  const [darkMobile, setDarkMobile] = useState(false);
 
   return (
-    <LeftNav
-      selectedId="inspection"
-      navigation={navigation}
-      leftNavMobileMenu={mobile}
-      draggable={true}
-      transition={{
-        headerVisible: undefined,
-        collapse,
-      }}
-      handleToggleCollapse={() => {
-        setCollapse(!collapse);
-      }}
-      handleChangeNavigation={(value) => {
-        setNavigation(value);
-      }}
-      handleToggleLeftNavMobileMenu={() => {
-        setMobile(!mobile);
-      }}
-      renderDashboardLogo={() => (
-        <div className="flex items-center flex-shrink-0 px-6 cursor-pointer flex-col">
-          <img
-            className={`h-10 ${
-              collapse ? "w-1/4 object-contain lg:hidden" : "w-auto"
-            } `}
-            w-auto
-            src={Logo}
-            alt="Favicon"
+    <>
+      <StorySection
+        title="Default"
+        description="Basic left nav with logo, nav items, and dashboard content. handleBarsOnClick handles selection for single-page apps. Resize to mobile width to see the hamburger menu."
+      >
+        <div className="w-full h-96 relative overflow-hidden border rounded-lg">
+          <LeftNav
+            selectedId={selectedId}
+            navigation={navigation}
+            leftNavMobileMenu={mobile}
+            handleBarsOnClick={(id) => setSelectedId(id)}
+            handleToggleLeftNavMobileMenu={() => setMobile(!mobile)}
+            renderDashboardLogo={() => renderLogo()}
+            renderDashboardContent={renderContent}
+            renderDashboardHeaderContent={renderHeader}
           />
         </div>
-      )}
-      renderDashboardContent={() => {}}
-      renderDashboardHeaderContent={() => {}}
-    />
+      </StorySection>
+
+      <StorySection
+        title="Draggable + Grouped Items"
+        description="draggable=true lets users reorder nav items via drag-and-drop. Items sharing a groupId are nested under a collapsible group. handleChangeNavigation persists the new order."
+      >
+        <div className="w-full h-96 relative overflow-hidden border rounded-lg">
+          <LeftNav
+            selectedId={selectedId}
+            navigation={groupedNav}
+            leftNavMobileMenu={false}
+            draggable={true}
+            handleBarsOnClick={(id) => setSelectedId(id)}
+            handleChangeNavigation={(value) => setGroupedNav(value)}
+            handleDropEnd={() => {}}
+            handleToggleLeftNavMobileMenu={() => {}}
+            renderDashboardLogo={() => renderLogo()}
+            renderDashboardContent={renderContent}
+            renderDashboardHeaderContent={renderHeader}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Collapsible Sidebar"
+        description="Pass transition.collapse to toggle the sidebar between full and icon-only width. handleToggleCollapse fires when the collapse arrow is clicked. transition.headerVisible=false hides the top header bar on desktop."
+      >
+        <div className="w-full h-96 relative overflow-hidden border rounded-lg">
+          <LeftNav
+            selectedId={selectedId}
+            navigation={navigation}
+            leftNavMobileMenu={false}
+            transition={{ headerVisible: true, collapse }}
+            handleBarsOnClick={(id) => setSelectedId(id)}
+            handleToggleCollapse={() => setCollapse(!collapse)}
+            handleToggleLeftNavMobileMenu={() => {}}
+            renderDashboardLogo={() => renderLogo(collapse)}
+            renderDashboardContent={renderContent}
+            renderDashboardHeaderContent={renderHeader}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Footer Content"
+        description="renderDashboardFooterContent renders a slot at the bottom of the sidebar, above the border. Useful for user profile info or a sign-out button."
+      >
+        <div className="w-full h-96 relative overflow-hidden border rounded-lg">
+          <LeftNav
+            selectedId={selectedId}
+            navigation={navigation}
+            leftNavMobileMenu={false}
+            handleBarsOnClick={(id) => setSelectedId(id)}
+            handleToggleLeftNavMobileMenu={() => {}}
+            renderDashboardLogo={() => renderLogo()}
+            renderDashboardContent={renderContent}
+            renderDashboardHeaderContent={renderHeader}
+            renderDashboardFooterContent={() => (
+              <div className="text-sm text-gray-500">v1.0.0</div>
+            )}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Dark Mode"
+        description="darkMode=true switches the sidebar and header to a dark theme. bgColor and navbarBgColor override the default background colours."
+        dark
+      >
+        <div className="w-full h-96 relative overflow-hidden border border-gray-700 rounded-lg">
+          <LeftNav
+            selectedId={selectedId}
+            navigation={navigation}
+            leftNavMobileMenu={darkMobile}
+            darkMode={true}
+            handleBarsOnClick={(id) => setSelectedId(id)}
+            handleToggleLeftNavMobileMenu={() => setDarkMobile(!darkMobile)}
+            renderDashboardLogo={() => renderLogo()}
+            renderDashboardContent={() => (
+              <div className="p-6 text-gray-400 text-sm">
+                Dashboard content.
+              </div>
+            )}
+            renderDashboardHeaderContent={renderHeader}
+          />
+        </div>
+      </StorySection>
+    </>
   );
 });

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

@@ -1,7 +1,9 @@
 import { storiesOf } from "@storybook/react";
 import React, { useState } from "react";
 import { Tabs } from ".";
+import { StorySection } from "../../storyUtils";
 import README from "./README.md";
+
 const stories = storiesOf("Navigation", module);
 
 stories.addParameters({
@@ -21,40 +23,62 @@ stories.add("Tabs", () => {
 
   return (
     <>
-      <h1 className="mb-2 text-lg font-bold">Default</h1>
-      <Tabs
-        tabs={tabs}
-        selectedId={selectedId}
-        onClick={(id) => {
-          setSelectedId(id);
-        }}
-        handleChangeTabs={(value) => setTabs(value)}
-        handleDropEnd={() => {}}
-        draggable={true}
-      />
-      <h1 className="mt-8 text-lg font-bold">Overflow Wrap</h1>
-      <p className="mb-2 text-sm text-gray-500">
-        Wrap tab options to new row when there's an overflow.
-      </p>
-      <Tabs
-        tabs={tabs}
-        selectedId={selectedId}
-        onClick={(id) => {
-          setSelectedId(id);
-        }}
-        overflowWrap
-      />
-      <h1 className="mt-8 mb-2 text-lg font-bold">Dark Mode</h1>
-      <div className="p-4 bg-black rounded-lg">
+      <StorySection
+        title="Default"
+        description="Basic tab bar. Pass onClick to handle selection and selectedId to highlight the active tab."
+      >
+        <Tabs
+          tabs={tabs}
+          selectedId={selectedId}
+          onClick={(id) => setSelectedId(id)}
+        />
+      </StorySection>
+
+      <StorySection
+        title="Draggable"
+        description="Set draggable=true and provide handleChangeTabs to persist the new order. handleDropEnd fires when the drag interaction ends."
+      >
+        <Tabs
+          tabs={tabs}
+          selectedId={selectedId}
+          onClick={(id) => setSelectedId(id)}
+          handleChangeTabs={(value) => setTabs(value)}
+          handleDropEnd={() => {}}
+          draggable={true}
+        />
+      </StorySection>
+
+      <StorySection
+        title="Overflow Wrap"
+        description="overflowWrap causes tabs to wrap onto a new row when they exceed the container width, instead of scrolling horizontally."
+      >
+        <Tabs
+          tabs={tabs}
+          selectedId={selectedId}
+          onClick={(id) => setSelectedId(id)}
+          overflowWrap
+        />
+      </StorySection>
+
+      <StorySection
+        title="Link-based Navigation"
+        description="Omit onClick to render each tab as a Link using its href value. Useful for multi-page navigation."
+      >
+        <Tabs tabs={tabs} selectedId={selectedId} />
+      </StorySection>
+
+      <StorySection
+        title="Dark Mode"
+        description="Pass darkMode=true for use on dark backgrounds."
+        dark
+      >
         <Tabs
           tabs={tabs}
           selectedId={selectedId}
-          onClick={(id) => {
-            setSelectedId(id);
-          }}
+          onClick={(id) => setSelectedId(id)}
           darkMode={true}
         />
-      </div>
+      </StorySection>
     </>
   );
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blixify-ui-web-mcp",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "license": "MIT",
   "main": "lib/mcp/server.js",
   "bin": {