blixify-ui-web-mcp 0.1.2 → 0.1.3

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

@@ -4,7 +4,7 @@
 
 <hr>
 
-Multiple bars selection for navigation
+A flexible navigation bar component that supports vertical and horizontal layouts, grouped collapsible items, drag-to-reorder, custom colors, and dark mode.
 
 ##### Import
 
@@ -14,27 +14,100 @@ import { Bars } from "blixify-ui-web/components/navigation/bars";
 
 ##### Usage
 
+Basic vertical nav:
+
+```jsx
+<Bars
+  bars={navigation}
+  selectedId="reports"
+  primaryColor={true}
+  onClick={(id) => setSelectedId(id)}
+/>
+```
+
+Horizontal nav bar:
+
+```jsx
+<Bars
+  bars={navigation}
+  selectedId={selectedId}
+  primaryColor={true}
+  horizontal={true}
+  onClick={(id) => setSelectedId(id)}
+/>
+```
+
+Grouped items (collapsible via Disclosure):
+
+```jsx
+const navigation = [
+  { id: "dashboard", name: "Dashboard", href: "#", icon: HomeIcon },
+  {
+    id: "projects",
+    name: "Projects",
+    href: "#",
+    icon: FolderIcon,
+    groupId: "Activity",
+  },
+  {
+    id: "calendar",
+    name: "Calendar",
+    href: "#",
+    icon: CalendarIcon,
+    groupId: "Activity",
+  },
+];
+
+<Bars
+  bars={navigation}
+  selectedId={selectedId}
+  onClick={(id) => setSelectedId(id)}
+/>;
+```
+
+Draggable with reorder callbacks:
+
 ```jsx
-<Bars bars={navigation} selectedId={"reports"} />
+<Bars
+  bars={navigation}
+  selectedId={selectedId}
+  draggable={true}
+  onClick={(id) => setSelectedId(id)}
+  handleChangeBars={(value) => setNavigation(value)}
+  handleDropEnd={() => {}}
+/>
 ```
 
 ##### Required props
 
-| Name         | Type         | Description     |
-| ------------ | ------------ | --------------- |
-| `bars`       | `Bars Class` | Bar Class List  |
-| `selectedId` | `string`     | Selected Tab ID |
+| Name         | Type     | Description                                      |
+| ------------ | -------- | ------------------------------------------------ |
+| `bars`       | `Bar[]`  | Ordered list of navigation items — see Bar below |
+| `selectedId` | `string` | The `id` of the currently active item            |
 
 ##### Optional props
 
-| Name               | Type               | Default                                        | Description                                  |
-| ------------------ | ------------------ | ---------------------------------------------- | -------------------------------------------- |
-| `primaryColor`     | `boolean`          | `false`                                        |                                              |
-| `draggable`        | `boolean`          | `false`                                        | Make component items draggable               |
-| `collapse`         | `boolean`          | `false`                                        | Required when leftNav transition is not null |
-| `customColor`      | `string`           | `""`                                           | Rainbow color for bar                        |
-| `linkProps`        | `Link Props Class` | Refer to Link Component for more documentation |                                              |
-| `onClick`          | `function`         | `() => {}`                                     |                                              |
-| `handleChangeBars` | `function`         | `(value) => {setBars(value)}`                  | Required when draggable is true              |
-| `handleDropEnd`    | `function`         | `() => {}`                                     | Required when draggable is true              |
-| `horizontal`       | `boolean`          | `false`                                        | When `true`, display horizontal bar          |
+| Name               | Type                                                                         | Default | Description                                                                                         |
+| ------------------ | ---------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
+| `onClick`          | `(id: string) => void`                                                       | —       | When provided, items render as clickable divs instead of links. Called with the item's `id`.        |
+| `primaryColor`     | `boolean`                                                                    | `false` | Highlights the selected item and hover state with the primary brand color.                          |
+| `customColor`      | `"red" \| "orange" \| "yellow" \| "green" \| "blue" \| "indigo" \| "violet"` | —       | Overrides the highlight color for selected and hovered items. Takes precedence over `primaryColor`. |
+| `horizontal`       | `boolean`                                                                    | `false` | Lays items out in a row instead of a column. Useful for top navigation bars.                        |
+| `darkMode`         | `boolean`                                                                    | `false` | Switches item text to white for use on dark backgrounds.                                            |
+| `draggable`        | `boolean`                                                                    | `false` | Makes items reorderable via drag-and-drop. Requires `handleChangeBars` and `handleDropEnd`.         |
+| `handleChangeBars` | `(value: Bar[]) => void`                                                     | —       | Called with the updated bars array after each drag move. Required when `draggable` is `true`.       |
+| `handleDropEnd`    | `() => void`                                                                 | —       | Called when a drag interaction ends. Required when `draggable` is `true`.                           |
+| `collapse`         | `boolean`                                                                    | `false` | Hides item labels and shows only icons. Used when the parent `LeftNav` is in collapsed state.       |
+| `linkType`         | `"react" \| "gatsby" \| "next" \| "external" \| "default"`                   | —       | Router adapter for link rendering when `onClick` is not provided.                                   |
+| `custom`           | `any`                                                                        | —       | The custom link component to use when `linkType` is `"react"`, `"gatsby"`, or `"next"`.             |
+
+##### Bar
+
+| Name             | Type           | Description                                                                                                 |
+| ---------------- | -------------- | ----------------------------------------------------------------------------------------------------------- |
+| `id`             | `string`       | Unique identifier for the item                                                                              |
+| `name`           | `string`       | Display label                                                                                               |
+| `href`           | `string`       | URL used when `onClick` is not provided                                                                     |
+| `icon`           | `any`          | Heroicon or any SVG component rendered to the left of the label                                             |
+| `groupId`        | `string`       | Optional — items sharing the same `groupId` are nested under a collapsible Disclosure group with that label |
+| `additionalIcon` | `ReactElement` | Optional — extra icon/element rendered to the right of the item label                                       |

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

@@ -9,6 +9,7 @@ import {
 import { storiesOf } from "@storybook/react";
 import React, { useState } from "react";
 import { Bars } from ".";
+import { StorySection } from "../../storyUtils";
 import README from "./README.md";
 
 const stories = storiesOf("Navigation", module);
@@ -19,67 +20,140 @@ stories.addParameters({
   },
 });
 
+const baseNavigation = [
+  { id: "dashboard", name: "Dashboard", href: "#", icon: HomeIcon },
+  { id: "team", name: "Team", href: "#", icon: UsersIcon },
+  { id: "documents", name: "Documents", href: "#", icon: InboxIcon },
+  { id: "reports", name: "Reports", href: "#", icon: ChartBarIcon },
+];
+
+const groupedNavigation = [
+  { id: "dashboard", name: "Dashboard", href: "#", icon: HomeIcon },
+  { id: "team", name: "Team", href: "#", icon: UsersIcon },
+  {
+    id: "projects",
+    name: "Projects",
+    href: "#",
+    icon: FolderIcon,
+    groupId: "Activity",
+  },
+  {
+    id: "calendar",
+    name: "Calendar",
+    href: "#",
+    icon: CalendarIcon,
+    groupId: "Activity",
+  },
+  { id: "documents", name: "Documents", href: "#", icon: InboxIcon },
+  { id: "reports", name: "Reports", href: "#", icon: ChartBarIcon },
+];
+
 stories.add("Bars", () => {
   const [selectedId, setSelectedId] = useState("reports");
-  const [navigation, setNavigation] = useState([
-    {
-      id: "dashboard",
-      name: "Dashboard",
-      href: "#",
-      icon: HomeIcon,
-    },
-    { id: "team", name: "Team", href: "#", icon: UsersIcon, current: false },
-    {
-      id: "projects",
-      name: "Projects",
-      href: "#",
-      icon: FolderIcon,
-      groupId: "Activity",
-    },
-    {
-      id: "calendar",
-      name: "Calendar",
-      href: "#",
-      icon: CalendarIcon,
-      groupId: "Activity",
-    },
-    {
-      id: "documents",
-      name: "Documents",
-      href: "#",
-      icon: InboxIcon,
-    },
-    {
-      id: "reports",
-      name: "Reports",
-      href: "#",
-      icon: ChartBarIcon,
-    },
-  ]);
+  const [draggableBars, setDraggableBars] = useState(baseNavigation);
 
   return (
     <>
-      <Bars
-        bars={navigation}
-        selectedId={"reports"}
-        primaryColor={true}
-        horizontal={false}
-      />
-      <div className="bg-gray-900">
+      <StorySection
+        title="Default (Vertical)"
+        description="Basic vertical nav bar. Each item renders as a link using its href. primaryColor highlights the selected item with the primary brand color."
+      >
+        <div className="w-64">
+          <Bars
+            bars={baseNavigation}
+            selectedId="reports"
+            primaryColor={true}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="With onClick"
+        description="Pass onClick to handle selection programmatically instead of using href links. selectedId controls which item is highlighted."
+      >
+        <div className="w-64">
+          <Bars
+            bars={baseNavigation}
+            selectedId={selectedId}
+            primaryColor={true}
+            onClick={(id) => setSelectedId(id)}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Grouped Items"
+        description="Items sharing the same groupId are nested under a collapsible Disclosure group labelled with that groupId string."
+      >
+        <div className="w-64">
+          <Bars
+            bars={groupedNavigation}
+            selectedId={selectedId}
+            primaryColor={true}
+            onClick={(id) => setSelectedId(id)}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Draggable"
+        description="Set draggable=true and provide handleChangeBars to persist the new order. handleDropEnd fires when the drag interaction ends."
+      >
+        <div className="w-64">
+          <Bars
+            bars={draggableBars}
+            selectedId={selectedId}
+            primaryColor={true}
+            draggable={true}
+            onClick={(id) => setSelectedId(id)}
+            handleChangeBars={setDraggableBars}
+            handleDropEnd={() => {}}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Horizontal"
+        description="horizontal=true lays items out in a row. Useful for top navigation bars."
+      >
         <Bars
-          draggable={true}
-          bars={navigation}
+          bars={baseNavigation}
           selectedId={selectedId}
           primaryColor={true}
-          darkMode={true}
-          onClick={(id) => {
-            setSelectedId(id);
-          }}
-          handleChangeBars={setNavigation}
-          handleDropEnd={() => {}}
           horizontal={true}
+          onClick={(id) => setSelectedId(id)}
         />
-      </div>
+      </StorySection>
+
+      <StorySection
+        title="Custom Color"
+        description="customColor overrides the selected/hover highlight with a named color: red, orange, yellow, green, blue, indigo, or violet."
+      >
+        <div className="w-64">
+          <Bars
+            bars={baseNavigation}
+            selectedId={selectedId}
+            customColor="indigo"
+            onClick={(id) => setSelectedId(id)}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Dark Mode"
+        description="Pass darkMode=true for use on dark backgrounds."
+        dark
+      >
+        <div className="w-64">
+          <Bars
+            bars={baseNavigation}
+            selectedId={selectedId}
+            primaryColor={true}
+            darkMode={true}
+            onClick={(id) => setSelectedId(id)}
+          />
+        </div>
+      </StorySection>
     </>
   );
 });

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,7 +1,9 @@
 import { storiesOf } from "@storybook/react";
-import React from "react";
+import React, { useState } from "react";
 import { Breadcrumb } from ".";
+import { StorySection } from "../../storyUtils";
 import README from "./README.md";
+
 const stories = storiesOf("Navigation", module);
 
 stories.addParameters({
@@ -16,12 +18,36 @@ const pages = [
 ];
 
 stories.add("Breadcrumb", () => {
+  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>
     </>
   );
 });