blixify-ui-web-mcp 0.1.1

package/lib/components/display/flexTable/flexTable.stories.tsx

@@ -0,0 +1,313 @@
+import { storiesOf } from "@storybook/react";
+import React, { useRef, useState } from "react";
+import { FlexTable, FlexTableItem } from ".";
+import { StorySection } from "../../storyUtils";
+import { Button } from "../../action/button";
+import { DataStructure, FlexMathQuery } from "../../data/dataTemplate/model";
+import { Form } from "../../input/form";
+import README from "./README.md";
+
+const stories = storiesOf("Display", module);
+
+stories.addParameters({
+  readme: {
+    content: README,
+  },
+});
+
+const researchCategories = [
+  {
+    title: "Test 1",
+    description: "Principal investigator and research staff salaries",
+  },
+  { title: "Test 2", description: "Travel and transportation expenses" },
+  { title: "Test 3", description: "Facility and space rental costs" },
+  // { title: "Test 4", description: "Laboratory supplies and materials" },
+  // { title: "Test 5", description: "Equipment maintenance and calibration" },
+  // { title: "Test 6", description: "Consulting and professional services" },
+  // {
+  //   title: "Test 7",
+  //   description: "Major equipment purchases and capital items",
+  // },
+];
+
+const sampleData: FlexTableItem[] = [
+  {
+    id: "1",
+    title: "Principal Investigator Salary",
+    category: "Test 1",
+    year1: 50000,
+    year2: 52000,
+    year3: 54000,
+  },
+  {
+    id: "2",
+    title: "Research Assistant Salary",
+    category: "Test 1",
+    year1: 30000,
+    year2: 31000,
+    year3: 32000,
+  },
+  {
+    id: "3",
+    title: "Conference Travel",
+    category: "Test 2",
+    year1: 5000,
+    year2: 5500,
+    year3: 6000,
+  },
+  {
+    id: "4",
+    title: "Field Work Travel",
+    category: "Test 2",
+    year1: 8000,
+    year2: 8500,
+    year3: 9000,
+  },
+  {
+    id: "5",
+    title: "Laboratory Rent",
+    category: "Test 3",
+    year1: 12000,
+    year2: 12000,
+    year3: 12000,
+  },
+  {
+    id: "6",
+    title: "Chemicals and Reagents",
+    category: "Test 4",
+    year1: 15000,
+    year2: 16000,
+    year3: 17000,
+  },
+  {
+    id: "7",
+    title: "Equipment Calibration",
+    category: "Test 5",
+    year1: 3000,
+    year2: 3200,
+    year3: 3400,
+  },
+  {
+    id: "8",
+    title: "Statistical Analysis Consultant",
+    category: "Test 6",
+    year1: 5000,
+    year2: 5000,
+    year3: 5000,
+  },
+  {
+    id: "9",
+    title: "Microscope",
+    category: "Test 7",
+    year1: 25000,
+    year2: 0,
+    year3: 0,
+  },
+  {
+    id: "10",
+    title: "Computer Workstation",
+    category: "Test 7",
+    year1: 8000,
+    year2: 0,
+    year3: 4000,
+  },
+];
+
+const baseColumns: DataStructure[] = [
+  { id: "year1", name: "Year 1", type: "number" },
+  { id: "year2", name: "Year 2", type: "number" },
+  { id: "year3", name: "Year 3", type: "number" },
+];
+
+const columnsWithMath: DataStructure[] = [
+  ...baseColumns,
+  {
+    id: "year4",
+    name: "Year 4",
+    type: "list",
+    listSelection: ["Option 1", "Option 2", "Option 3"],
+  },
+  {
+    id: "conditionalYear",
+    name: "Conditional Year",
+    type: "math",
+    mathExpression: "year4 == 'Option 1' ? year2 * 2 + 1 : year3 * 3",
+  },
+];
+
+const flexMathQueries: FlexMathQuery[] = [
+  { type: "categoryPercentage", targetCategory: "Test 2", maxPercentage: 50 },
+  {
+    type: "columnPercentage",
+    targetColumn: "year1",
+    maxPercentage: 70,
+    subtotalColumns: ["year2", "year3"],
+  },
+];
+
+stories.add("FlexTable", () => {
+  const [data, setData] = useState<FlexTableItem[]>(sampleData);
+  const [viewOnlyData] = useState<FlexTableItem[]>(sampleData);
+
+  const formRef = useRef<any>(null);
+  const tableRef = useRef<any>(null);
+
+  return (
+    <>
+      <StorySection
+        title="Default (Editable)"
+        description="Basic editable table with category subtotals. Each category row shows a subtotal. onChangeData fires whenever a cell value changes."
+      >
+        <div className="w-full">
+          <FlexTable
+            label="Research Budget"
+            data={data}
+            columns={baseColumns}
+            categoryList={researchCategories}
+            onChangeData={setData}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="With Grand Total"
+        description="showGrandTotal=true adds a grand total row summing all numeric columns across all categories."
+      >
+        <div className="w-full">
+          <FlexTable
+            label="Research Budget with Grand Total"
+            data={data}
+            columns={baseColumns}
+            categoryList={researchCategories}
+            showGrandTotal={true}
+            onChangeData={setData}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Without Total Row"
+        description="showTotal=false hides the per-category subtotal rows."
+      >
+        <div className="w-full">
+          <FlexTable
+            label="Research Budget (No Subtotals)"
+            data={data}
+            columns={baseColumns}
+            categoryList={researchCategories}
+            showTotal={false}
+            onChangeData={setData}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Math & List Columns"
+        description="Columns with type='math' compute values from a mathExpression using other column values. type='list' renders a dropdown. The math column here evaluates conditionally based on the list selection."
+      >
+        <div className="w-full">
+          <FlexTable
+            label="Budget with Computed Columns"
+            data={data}
+            columns={columnsWithMath}
+            categoryList={researchCategories}
+            onChangeData={setData}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="FlexMathQueries Validation"
+        description="flexMathQueries adds validation rules. categoryPercentage checks that a category's total does not exceed a percentage of the grand total. columnPercentage checks that one column does not exceed a percentage of the sum of other columns."
+      >
+        <div className="w-full space-y-3">
+          <Button
+            text="Submit & Validate"
+            size="small"
+            type="normal"
+            onClick={() => formRef.current?.handleSubmit()}
+          />
+          <Form ref={formRef} refList={[tableRef]}>
+            <FlexTable
+              label="Budget with Validation Rules"
+              ref={tableRef}
+              data={data}
+              columns={columnsWithMath}
+              categoryList={researchCategories}
+              flexMathQueries={flexMathQueries}
+              onChangeData={setData}
+              onAddColumn={(col) => console.log("column added", col)}
+              onRemoveColumn={(key) => console.log("column removed", key)}
+            />
+          </Form>
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Max Rows per Category"
+        description="maxRows limits how many rows can be added per category. The add-row button is hidden once the limit is reached."
+      >
+        <div className="w-full">
+          <FlexTable
+            label="Budget (Max 2 rows per category)"
+            data={data}
+            columns={baseColumns}
+            categoryList={researchCategories}
+            maxRows={2}
+            onChangeData={setData}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Hide Category Column"
+        description="hideCategory=true removes the category grouping and renders a flat list of rows."
+      >
+        <div className="w-full">
+          <FlexTable
+            label="Flat Budget Table"
+            data={data}
+            columns={baseColumns}
+            hideCategory={true}
+            onChangeData={setData}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="View Only (disabled)"
+        description="disabled=true removes all editing controls — no add/remove row, no cell editing, no add column."
+      >
+        <div className="w-full">
+          <FlexTable
+            label="Budget (Read Only)"
+            data={viewOnlyData}
+            columns={baseColumns}
+            categoryList={researchCategories}
+            showGrandTotal={true}
+            disabled={true}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Dark Mode"
+        description="Pass darkMode=true and optionally darkModeBg to customise the background."
+        dark
+      >
+        <div className="w-full">
+          <FlexTable
+            label="Budget (Dark Mode)"
+            data={data}
+            columns={baseColumns}
+            categoryList={researchCategories}
+            darkMode={true}
+            darkModeBg="bg-gray-900"
+            onChangeData={setData}
+          />
+        </div>
+      </StorySection>
+    </>
+  );
+});

package/lib/components/display/grid/README.md

@@ -0,0 +1,121 @@
+# Grid
+
+<!-- STORY -->
+
+<hr>
+
+A card grid with pagination, horizontal scroll, infinity scroll, drag-and-drop, custom card slots, and dark mode support.
+
+##### Import
+
+```js
+import { Grid, GridClass } from "blixify-ui-web/display/grid";
+```
+
+##### Usage
+
+Cursor pagination with horizontal scroll:
+
+```jsx
+const [pageIndex, setPageIndex] = useState(0);
+
+<Grid
+  data={data}
+  limit={5}
+  loading={false}
+  paginationType="cursor"
+  cursor={cursor}
+  pageIndex={pageIndex}
+  size={data.length}
+  itemClassName="shadow-md rounded"
+  horizontalScroll={true}
+  infinityScroll
+  handleUpdatePageIndex={(value) => {
+    if (typeof value === "number") setPageIndex(value);
+    else setPageIndex((p) => (value === "next" ? p + 1 : p - 1));
+  }}
+/>;
+```
+
+Page pagination with custom column layout:
+
+```jsx
+<Grid
+  data={data}
+  limit={5}
+  loading={false}
+  paginationType="page"
+  size={data.length}
+  pageIndex={pageIndex}
+  gridColClassName="sm:grid-cols-2 sm:gap-x-6 lg:grid-cols-3"
+  handleUpdatePageIndex={handlePagination}
+/>
+```
+
+Custom ribbon on card image:
+
+```jsx
+<Grid
+  data={data}
+  loading={false}
+  renderImgRibbon={(id) => {
+    if (id === "1")
+      return (
+        <div className="absolute top-5 -left-9 w-[50%] bg-yellow-500 text-white text-xs font-bold p-2 text-center transform -rotate-45">
+          WINNER
+        </div>
+      );
+    return null;
+  }}
+/>
+```
+
+##### Required props
+
+| Name      | Type          | Description                           |
+| --------- | ------------- | ------------------------------------- |
+| `data`    | `GridClass[]` | Array of card data items              |
+| `loading` | `boolean`     | Shows a loading indicator when `true` |
+
+##### Optional props
+
+| Name                    | Type                                       | Default                                                 | Description                                                                                                              |
+| ----------------------- | ------------------------------------------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `paginationType`        | `"cursor" \| "page"`                       | —                                                       | Enables pagination. `"cursor"` for token-based, `"page"` for numbered pages                                              |
+| `limit`                 | `number`                                   | `5`                                                     | Cards per page. Required when `paginationType` is set                                                                    |
+| `pageIndex`             | `number`                                   | —                                                       | Current page index (0-based). Required when `paginationType` is set                                                      |
+| `cursor`                | `any`                                      | —                                                       | Pass a truthy value while more pages exist; falsy on the last page. Required when `paginationType="cursor"`              |
+| `size`                  | `number`                                   | —                                                       | Total record count. Required when `paginationType="page"` to calculate page count                                        |
+| `hidePagination`        | `boolean`                                  | `false`                                                 | Hide the pagination bar                                                                                                  |
+| `horizontalScroll`      | `boolean`                                  | `false`                                                 | Render cards in a horizontally scrollable row instead of a grid                                                          |
+| `infinityScroll`        | `boolean`                                  | `false`                                                 | Auto-load the next page when the user scrolls to the end. Requires `horizontalScroll=true` and `paginationType="cursor"` |
+| `gridColClassName`      | `string`                                   | `"sm:grid-cols-2 sm:gap-x-6 lg:grid-cols-3 lg:gap-x-8"` | Tailwind grid column classes                                                                                             |
+| `className`             | `string`                                   | —                                                       | Tailwind classes for the outer container                                                                                 |
+| `itemClassName`         | `string`                                   | —                                                       | Tailwind classes applied to each card, e.g. `"shadow-md rounded"`                                                        |
+| `selectedItemClassName` | `string`                                   | —                                                       | Tailwind classes applied to cards whose id is in `selectedItemsId`                                                       |
+| `selectedItemsId`       | `string[]`                                 | —                                                       | IDs of cards to highlight with `selectedItemClassName`                                                                   |
+| `customGridItems`       | `{ [id: string]: ReactElement }`           | —                                                       | Replace a specific card with custom JSX. The key must match the item's `id` in `data`                                    |
+| `imgContain`            | `boolean`                                  | `false`                                                 | Use `object-contain` instead of `object-cover` for card images                                                           |
+| `darkMode`              | `boolean`                                  | `false`                                                 | Enable dark mode card styling                                                                                            |
+| `darkModeBg`            | `string`                                   | —                                                       | Tailwind bg class for dark mode cards, e.g. `"bg-gray-800"`                                                              |
+| `newTabUrl`             | `string`                                   | —                                                       | Prepends a link to each card. The card `id` is appended to this URL                                                      |
+| `addNewTabUrl`          | `string`                                   | —                                                       | URL appended to the add-card action link                                                                                 |
+| `draggable`             | `boolean`                                  | `false`                                                 | Enable drag-and-drop reordering of cards                                                                                 |
+| `droppable`             | `boolean`                                  | `false`                                                 | Allow cards to be dropped onto other cards                                                                               |
+| `renderImgRibbon`       | `(id: string) => ReactElement \| null`     | —                                                       | Return a ReactElement to overlay on the card image (e.g. a ribbon badge), or `null` for no ribbon                        |
+| `onClickData`           | `(id: string) => void`                     | —                                                       | Called with the card id when a card is clicked                                                                           |
+| `onDropData`            | `(dragId: string, dropId: string) => void` | —                                                       | Called when a card is dropped onto another card                                                                          |
+| `handleUpdatePageIndex` | `(value: string \| number) => void`        | —                                                       | Called with `"next"`, `"prev"`, or a page number when the user navigates                                                 |
+
+##### GridClass
+
+| Name           | Type                     | Required | Description                                         |
+| -------------- | ------------------------ | -------- | --------------------------------------------------- |
+| `id`           | `string`                 | yes      | Unique card identifier                              |
+| `title`        | `string`                 | yes      | Card heading                                        |
+| `description`  | `string \| ReactElement` | yes      | Card body text or custom JSX                        |
+| `tags`         | `string[]`               | no       | Tag badges shown on the card                        |
+| `imageUrl`     | `string`                 | no       | URL for the card image                              |
+| `imageElement` | `ReactElement`           | no       | Custom image element — overrides `imageUrl`         |
+| `ribbonText`   | `string`                 | no       | Built-in ribbon badge text shown on the card image  |
+| `extra`        | `any`                    | no       | Additional data passed through for custom rendering |

package/lib/components/display/grid/grid.stories.tsx

@@ -0,0 +1,234 @@
+import { storiesOf } from "@storybook/react";
+import React, { useState } from "react";
+import { Grid, GridClass } from ".";
+import { StorySection } from "../../storyUtils";
+import README from "./README.md";
+
+const stories = storiesOf("Display", module);
+
+stories.addParameters({
+  readme: {
+    content: README,
+  },
+});
+
+const data: GridClass[] = [
+  {
+    id: "1",
+    title: "Nike Court Vision",
+    description: "Nike Men's Court Vision Low Next Nature Shoes - Black",
+    tags: ["Sports"],
+    imageUrl: "https://cf.shopee.com.my/file/fef57a9b0d40a0626def6fdc993c442a",
+  },
+  {
+    id: "2",
+    title: "Nike Air Max 2X",
+    description: "Nike Men's Air Max 2X Shoes - White",
+    tags: ["Sports", "Promotions"],
+    imageUrl: "https://cf.shopee.com.my/file/6df4da8ff019bfa08c1bcba4bbe3c983",
+  },
+  {
+    id: "3",
+    title: "Nike Air Max 2X",
+    description: "Nike Men's Air Max 2X Shoes - White",
+    tags: ["Sports", "Promotions"],
+    imageUrl: "https://cf.shopee.com.my/file/6df4da8ff019bfa08c1bcba4bbe3c983",
+  },
+  {
+    id: "4",
+    title: "Nike Air Max 2X",
+    description: "Nike Men's Air Max 2X Shoes - White",
+    tags: ["Sports", "Promotions"],
+    ribbonText: "SALE",
+    imageUrl: "https://cf.shopee.com.my/file/6df4da8ff019bfa08c1bcba4bbe3c983",
+  },
+  {
+    id: "5",
+    title: "Nike Air Max 2X",
+    description: "Nike Men's Air Max 2X Shoes - White",
+    tags: ["Sports"],
+    imageUrl: "https://cf.shopee.com.my/file/6df4da8ff019bfa08c1bcba4bbe3c983",
+  },
+  {
+    id: "6",
+    title: "Nike Air Max 2X",
+    description: "Nike Men's Air Max 2X Shoes - White",
+    tags: ["Sports", "Promotions"],
+    imageUrl: "https://cf.shopee.com.my/file/6df4da8ff019bfa08c1bcba4bbe3c983",
+  },
+  {
+    id: "7",
+    title: "Nike Air Max 2X",
+    description: "Nike Men's Air Max 2X Shoes - White",
+    tags: ["Sports"],
+    imageUrl: "https://cf.shopee.com.my/file/6df4da8ff019bfa08c1bcba4bbe3c983",
+  },
+  {
+    id: "8",
+    title: "Nike Air Max 2X",
+    description: "Nike Men's Air Max 2X Shoes - White",
+    tags: ["Sports", "Promotions"],
+    imageUrl: "https://cf.shopee.com.my/file/6df4da8ff019bfa08c1bcba4bbe3c983",
+  },
+];
+
+const renderImgRibbon = (id: string) => {
+  if (id === "1" || id === "2") {
+    return (
+      <div className="absolute top-5 -left-9 w-[50%] bg-yellow-500 text-white text-xs font-bold p-2 text-center transform -rotate-45">
+        <span>WINNER</span>
+      </div>
+    );
+  }
+  return null;
+};
+
+stories.add("Grid", () => {
+  const [pageIndex, setPageIndex] = useState(0);
+  const limit = 5;
+  const cursor = true;
+
+  const handlePagination = (value: string | number) => {
+    if (typeof value === "number") {
+      setPageIndex(value);
+    } else {
+      setPageIndex((prev) => (value === "next" ? prev + 1 : prev - 1));
+    }
+  };
+
+  return (
+    <>
+      <StorySection
+        title="Cursor Pagination"
+        description="Use paginationType='cursor' for token-based pagination (e.g. Firestore). Pass a truthy cursor while more data exists. infinityScroll combined with horizontalScroll auto-loads the next page when the user scrolls to the end."
+      >
+        <div className="w-full">
+          <Grid
+            data={data}
+            limit={limit}
+            loading={false}
+            paginationType="cursor"
+            cursor={cursor}
+            pageIndex={pageIndex}
+            size={data.length}
+            itemClassName="shadow-md rounded"
+            horizontalScroll={true}
+            infinityScroll
+            handleUpdatePageIndex={handlePagination}
+            renderImgRibbon={renderImgRibbon}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Custom Grid Item"
+        description="Pass customGridItems with a map of id → ReactElement to replace a specific card with fully custom content. The key must match the item's id in data."
+      >
+        <div className="w-full">
+          <Grid
+            data={data}
+            limit={limit}
+            loading={false}
+            paginationType="cursor"
+            cursor={cursor}
+            pageIndex={pageIndex}
+            size={data.length}
+            itemClassName="shadow-md rounded"
+            horizontalScroll={true}
+            handleUpdatePageIndex={handlePagination}
+            customGridItems={{
+              "2": (
+                <div className="w-48 h-full flex flex-col justify-center items-center bg-primary-700 text-white p-4 font-thin">
+                  <h1 className="text-3xl">Custom item</h1>
+                  <p className="mt-6 text-sm">
+                    This card replaces the default grid item for id="2".
+                  </p>
+                </div>
+              ),
+            }}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Page Pagination"
+        description="Use paginationType='page' for numbered page navigation. Pass size (total record count) so the component can calculate the page count. gridColClassName overrides the default 3-column layout."
+      >
+        <div className="w-full">
+          <Grid
+            data={data}
+            limit={limit}
+            loading={false}
+            paginationType="page"
+            size={data.length}
+            pageIndex={pageIndex}
+            gridColClassName="sm:grid-cols-2 sm:gap-x-6 lg:grid-cols-3"
+            handleUpdatePageIndex={handlePagination}
+            renderImgRibbon={renderImgRibbon}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Dark Mode"
+        description="Pass darkMode=true and darkModeBg to customise the card background colour."
+        dark
+      >
+        <div className="w-full">
+          <Grid
+            data={data}
+            limit={limit}
+            loading={false}
+            paginationType="page"
+            size={data.length}
+            pageIndex={pageIndex}
+            gridColClassName="sm:grid-cols-2 sm:gap-x-6 lg:grid-cols-3"
+            darkMode={true}
+            darkModeBg="bg-gray-800"
+            handleUpdatePageIndex={handlePagination}
+            renderImgRibbon={renderImgRibbon}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Ribbon Text"
+        description="Set ribbonText on a GridClass item to show a built-in ribbon badge on the card image. Use renderImgRibbon for a fully custom ribbon element."
+      >
+        <div className="w-full">
+          <Grid
+            data={data.slice(0, 4)}
+            limit={limit}
+            loading={false}
+            renderImgRibbon={renderImgRibbon}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Selected Items"
+        description="Pass selectedItemsId and selectedItemClassName to highlight specific cards. Useful for multi-select UIs."
+      >
+        <div className="w-full">
+          <Grid
+            data={data.slice(0, 4)}
+            limit={limit}
+            loading={false}
+            selectedItemsId={["1", "3"]}
+            selectedItemClassName="ring-2 ring-primary-500"
+            onClickData={(id) => console.log("clicked", id)}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Loading State"
+        description="Pass loading=true to show a loading indicator while data is being fetched."
+      >
+        <div className="w-full">
+          <Grid data={[]} loading={true} />
+        </div>
+      </StorySection>
+    </>
+  );
+});