blixify-ui-web-mcp 0.1.1

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

@@ -0,0 +1,74 @@
+# Tag
+
+<!-- STORY -->
+
+<hr>
+
+Tag to be displayed for data filter.
+
+##### Import
+
+```js
+import { Tag } from "blixify-ui-web/lib";
+```
+
+##### Usage
+
+```jsx
+return (
+  return (
+    <div className="flex">
+      <Tag
+        tagText="React"
+        action={
+          <XMarkIcon
+            className="cursor-pointer mx-auto h-4 w-4 text-white ml-2 mt-1"
+            onClick={() => {}}
+          />
+        }
+      />
+      <Tag tagText="Clickable Tag" onClick={() => {}} />
+      <Tag tagText="Disabled Tag" disabled />
+      <Tag tagText="Small" size="small" />
+      <Tag tagText="React" variant="outline" />
+      <Tag tagText="React" rounded="lg" variant="outline" />
+      <Tag tagText="React" rounded="md" variant="outline" />
+      <Tag tagText="React" rounded="none" variant="outline" />
+      <Tag tagText="React" color="red" />
+      <Tag tagText="React" color="blue" />
+      <Tag tagText="React" color="green" />
+      <Tag tagText="React" color="yellow" />
+      <Tag tagText="React" color="indigo" />
+      <Tag tagText="React" color="dark" />
+      <Tag tagText="React" color="red" variant="flat" />
+      <Tag tagText="React" color="blue" variant="flat" />
+      <Tag tagText="React" color="green" variant="flat" />
+      <Tag tagText="React" color="yellow" variant="flatOutline" />
+      <Tag tagText="React" color="indigo" variant="flatOutline" />
+      <Tag tagText="React" color="dark" variant="flatOutline" />
+    </div>
+  );
+);
+```
+
+##### Required props
+
+| Name      | Type     | Description          |
+| --------- | -------- | -------------------- |
+| `tagText` | `string` | `Content of the tag` |
+
+##### Optional props
+
+| Name             | Type                                          | Description                   |
+| ---------------- | --------------------------------------------- | ----------------------------- |
+| `id`             | `string`                                      | `id`                          |
+| `action`         | `React Element`                               | `Icon or Action`              |
+| `size`           | `small`                                       |                               |
+| `className`      | `string`                                      | Additional classname          |
+| `disabled`       | `boolean`                                     |                               |
+| `rounded`        | `none / md /lg`                               | Border with                   |
+| `variant`        | `flat / outline /flatOutline`                 |                               |
+| `color`          | `red / blue / green / yellow / indigo / dark` | Background color & text color |
+| `customFontSize` | `string`                                      | Tailwind font class name      |
+| `customPadding`  | `string`                                      | Tailwind padding class name   |
+| `onClick`        | `(value: string) => void`                     | Value is tagText              |

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

@@ -0,0 +1,79 @@
+import { XMarkIcon } from "@heroicons/react/24/outline";
+import { storiesOf } from "@storybook/react";
+import React from "react";
+import { Tag } from ".";
+import README from "./README.md";
+
+const stories = storiesOf("Display", module);
+
+stories.addParameters({
+  readme: {
+    content: README,
+  },
+});
+
+stories.add("Tag", () => {
+  return (
+    <div>
+      <div className="flex flex-wrap gap-4">
+        <Tag
+          tagText="React"
+          action={
+            <XMarkIcon
+              className="cursor-pointer mx-auto h-4 w-4 text-white ml-2"
+              onClick={() => {}}
+            />
+          }
+        />
+        <Tag tagText="Clickable" onClick={() => {}} />
+        <Tag tagText="Disabled" disabled />
+      </div>
+      <div className="mt-4 p-4 flex flex-col space-y-2 border rounded-md">
+        <h1 className="font-semibold">Small</h1>
+        <Tag tagText="Small" size="small" />
+      </div>
+      <div className="mt-4 p-4 flex flex-col space-y-2 border rounded-md">
+        <h1 className="font-semibold">Rounded</h1>
+        <div className="flex flex-wrap gap-4">
+          <Tag tagText="React" variant="outline" />
+          <Tag tagText="React" rounded="lg" variant="outline" />
+          <Tag tagText="React" rounded="md" variant="outline" />
+          <Tag tagText="React" rounded="none" variant="outline" />
+        </div>
+      </div>
+      <div className="mt-4 p-4 flex flex-col space-y-2 border rounded-md">
+        <h1 className="mb-4 font-semibold">Color Variant</h1>
+        <h1 className="text-sm font-medium">Color</h1>
+        <div className="flex flex-wrap gap-4">
+          <Tag tagText="React" color="red" />
+          <Tag tagText="React" color="blue" />
+          <Tag tagText="React" color="green" />
+          <Tag tagText="React" color="yellow" />
+          <Tag tagText="React" color="indigo" />
+          <Tag tagText="React" color="dark" />
+          <Tag tagText="Default" color="default" />
+        </div>
+        <h1 className="text-sm font-medium">Outline</h1>
+        <div className="flex flex-wrap gap-4">
+          <Tag tagText="React" color="red" variant="outline" />
+          <Tag tagText="React" color="blue" variant="outline" />
+          <Tag tagText="React" color="green" variant="outline" />
+          <Tag tagText="React" color="yellow" variant="outline" />
+          <Tag tagText="React" color="indigo" variant="outline" />
+          <Tag tagText="React" color="dark" variant="outline" />
+          <Tag tagText="Default" color="default" variant="outline" />
+        </div>
+        <h1 className="text-sm font-medium">Flat & Flat Outline</h1>
+        <div className="flex flex-wrap gap-4">
+          <Tag tagText="React" color="red" variant="flat" />
+          <Tag tagText="React" color="blue" variant="flat" />
+          <Tag tagText="React" color="green" variant="flat" />
+          <Tag tagText="React" color="yellow" variant="flatOutline" />
+          <Tag tagText="React" color="indigo" variant="flatOutline" />
+          <Tag tagText="React" color="dark" variant="flatOutline" />
+          <Tag tagText="Default" color="default" variant="flatOutline" />
+        </div>
+      </div>
+    </div>
+  );
+});

package/lib/components/input/address/README.md

@@ -0,0 +1,132 @@
+# Address Input
+
+<!-- STORY -->
+
+<hr>
+
+An address autocomplete input backed by the Google Places API. Supports current location detection, lat/lng editing via modal, drag-marker map selection, and custom action buttons.
+
+### Setup
+
+Load the Google Maps JS script before the component mounts. Include the `places`, `drawing`, and `geometry` libraries:
+
+```html
+<script
+  async
+  src="https://maps.googleapis.com/maps/api/js?key=[YOUR_API_KEY]&libraries=places,drawing,geometry"
+></script>
+```
+
+Or inject it programmatically:
+
+```js
+const script = document.createElement("script");
+script.src = `https://maps.googleapis.com/maps/api/js?key=${apiKey}&libraries=places,drawing,geometry`;
+document.head.appendChild(script);
+```
+
+##### Import
+
+```js
+import { Address, AddressClass } from "blixify-ui-web/input/address";
+```
+
+##### Usage
+
+Basic:
+
+```jsx
+const [value, setValue] =
+  useState < AddressClass > { name: "", lat: 0, lng: 0 };
+
+<Address
+  id="address"
+  value={value}
+  label="Address"
+  onChange={setValue}
+  delayInit={true}
+/>;
+```
+
+With map features:
+
+```jsx
+<Address
+  id="address"
+  value={value}
+  label="Address"
+  onChange={setValue}
+  getCurrentLocation={true}
+  latLngEditModal={true}
+  enableDragMarker={true}
+  delayInit={true}
+/>
+```
+
+With custom buttons:
+
+```jsx
+<Address
+  id="address"
+  value={value}
+  label="Address"
+  onChange={setValue}
+  delayInit={true}
+  customBtn={[
+    {
+      text: "Copy",
+      onClick: (val, text) => console.log(text, val),
+    },
+  ]}
+/>
+```
+
+##### Required props
+
+| Name    | Type           | Description             |
+| ------- | -------------- | ----------------------- |
+| `id`    | `string`       | Unique field identifier |
+| `value` | `AddressClass` | Current address value   |
+| `label` | `string`       | Field label             |
+
+##### Optional props
+
+| Name                 | Type                        | Default | Description                                                                                               |
+| -------------------- | --------------------------- | ------- | --------------------------------------------------------------------------------------------------------- |
+| `onChange`           | `(e: AddressClass) => void` | —       | Called with the updated address when the user selects a place                                             |
+| `placeholder`        | `string`                    | —       | Input placeholder text                                                                                    |
+| `optional`           | `boolean`                   | —       | Marks the field as optional (skips required validation)                                                   |
+| `disabled`           | `boolean`                   | —       | Makes the field read-only                                                                                 |
+| `autoFocus`          | `boolean`                   | —       | Focus the input on mount                                                                                  |
+| `hideMetadata`       | `boolean`                   | —       | Hide the lat/lng display shown below the address field                                                    |
+| `getCurrentLocation` | `boolean`                   | —       | Show a button that fills the field from the browser's geolocation API                                     |
+| `latLngEditModal`    | `boolean`                   | —       | Show a button that opens a modal to manually edit the lat and lng values                                  |
+| `enableDragMarker`   | `boolean`                   | —       | Show a button that opens a map modal where the user can drag a pin to set location                        |
+| `mobileView`         | `boolean`                   | —       | Switch to a mobile-optimised autocomplete layout                                                          |
+| `delayInit`          | `boolean`                   | —       | Delay initialising the Google Places autocomplete service. Use when the Maps script may not be loaded yet |
+| `customBtn`          | `AddressCustomBtn[]`        | —       | Extra action buttons rendered above the input                                                             |
+| `labelExtra`         | `ReactElement`              | —       | Extra element rendered next to the label                                                                  |
+| `infoElement`        | `ReactElement`              | —       | Info element rendered in the label area                                                                   |
+| `className`          | `string`                    | —       | Tailwind classes for the input element                                                                    |
+| `containerClassName` | `string`                    | —       | Tailwind classes for the outer container, e.g. `"col-span-2"`                                             |
+| `darkMode`           | `boolean`                   | —       | Enable dark mode styling                                                                                  |
+| `cellInput`          | `CellInput`                 | —       | Cell input config for use inside a Table component                                                        |
+
+##### AddressClass
+
+| Name       | Type     | Required | Description                   |
+| ---------- | -------- | -------- | ----------------------------- |
+| `name`     | `string` | yes      | Human-readable address string |
+| `lat`      | `number` | yes      | Latitude                      |
+| `lng`      | `number` | yes      | Longitude                     |
+| `poi`      | `string` | no       | Point of interest name        |
+| `district` | `string` | no       | District                      |
+| `state`    | `string` | no       | State / province              |
+| `country`  | `string` | no       | Country                       |
+
+##### AddressCustomBtn
+
+| Name      | Type                                             | Description                                               |
+| --------- | ------------------------------------------------ | --------------------------------------------------------- |
+| `text`    | `string`                                         | Button label                                              |
+| `onClick` | `(value: AddressClass, btnText: string) => void` | Called with the current address value and the button text |

package/lib/components/input/address/address.stories.tsx

@@ -0,0 +1,147 @@
+import { storiesOf } from "@storybook/react";
+import React, { useEffect, useState } from "react";
+import { Address, AddressClass } from ".";
+import { StorySection } from "../../storyUtils";
+import README from "./README.md";
+
+const stories = storiesOf("Input", module);
+
+stories.addParameters({
+  readme: {
+    content: README,
+  },
+});
+
+const emptyAddress: AddressClass = { name: "", lat: 0, lng: 0 };
+
+// Google Maps must be loaded before Address mounts
+const injectGoogleMaps = () => {
+  if (document.getElementById("googleMaps")) return;
+  const script = document.createElement("script");
+  script.id = "googleMaps";
+  script.type = "text/javascript";
+  script.src = `https://maps.googleapis.com/maps/api/js?key=&libraries=places,drawing,geometry`;
+  script.async = true;
+  script.defer = true;
+  document.head.appendChild(script);
+};
+
+stories.add("Address", () => {
+  const [value, setValue] = useState<AddressClass>(emptyAddress);
+
+  useEffect(() => {
+    injectGoogleMaps();
+  }, []);
+
+  return (
+    <>
+      <StorySection
+        title="Default"
+        description="Basic address autocomplete backed by the Google Places API. Requires the Google Maps JS script to be loaded before the component mounts."
+      >
+        <div className="w-full">
+          <Address
+            id="address-default"
+            value={value}
+            label="Address"
+            onChange={setValue}
+            delayInit={true}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="With Map Features"
+        description="getCurrentLocation adds a button to fill the field from the browser's geolocation. latLngEditModal adds a button to manually edit lat/lng. enableDragMarker opens a map modal where the user can drag a pin to set the location."
+      >
+        <div className="w-full">
+          <Address
+            id="address-map"
+            value={value}
+            label="Address"
+            onChange={setValue}
+            getCurrentLocation={true}
+            latLngEditModal={true}
+            enableDragMarker={true}
+            delayInit={true}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Custom Buttons"
+        description="Pass customBtn to render extra action buttons above the input. Each button receives the current AddressClass value and its own label text in the onClick callback."
+      >
+        <div className="w-full">
+          <Address
+            id="address-custom-btn"
+            value={value}
+            label="Address"
+            onChange={setValue}
+            delayInit={true}
+            customBtn={[
+              {
+                text: "Copy",
+                onClick: (val, text) =>
+                  window.alert(`${text}: ${JSON.stringify(val)}`),
+              },
+              {
+                text: "Verify",
+                onClick: (val, text) =>
+                  window.alert(`${text}: ${JSON.stringify(val)}`),
+              },
+            ]}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Mobile View"
+        description="mobileView=true switches the autocomplete to a mobile-optimised layout."
+      >
+        <div className="w-full">
+          <Address
+            id="address-mobile"
+            value={value}
+            label="Address"
+            onChange={setValue}
+            delayInit={true}
+            mobileView={true}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Disabled"
+        description="disabled=true makes the field read-only."
+      >
+        <div className="w-full">
+          <Address
+            id="address-disabled"
+            value={{ name: "Kuala Lumpur, Malaysia", lat: 3.14, lng: 101.69 }}
+            label="Address"
+            onChange={setValue}
+            disabled={true}
+            delayInit={true}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Hide Metadata"
+        description="hideMetadata=true hides the lat/lng display below the address field."
+      >
+        <div className="w-full">
+          <Address
+            id="address-no-meta"
+            value={value}
+            label="Address"
+            onChange={setValue}
+            hideMetadata={true}
+            delayInit={true}
+          />
+        </div>
+      </StorySection>
+    </>
+  );
+});

package/lib/components/input/canvas/README.md

@@ -0,0 +1,131 @@
+# Canvas
+
+<!-- STORY -->
+
+<hr>
+
+An interactive canvas for placing text and freehand drawings over an optional background image. Supports draw mode, erase mode, image upload, and form validation.
+
+##### Import
+
+```js
+import { Canvas } from "blixify-ui-web/input/canvas";
+```
+
+##### Usage
+
+Basic text canvas:
+
+```jsx
+<Canvas
+  id="canvas"
+  label="Annotation"
+  canvasHeight={300}
+  onChange={(texts) => setTexts(texts)}
+/>
+```
+
+Draw mode with background image:
+
+```jsx
+<Canvas
+  id="canvas"
+  label="Annotation"
+  canvasHeight={300}
+  backgroundImageUrl="https://example.com/image.jpg"
+  enableDraw
+  drawings={drawings}
+  onChange={(texts) => setTexts(texts)}
+  onDrawingsChange={(d) => setDrawings(d)}
+/>
+```
+
+With form validation:
+
+```jsx
+const formRef = useRef(null);
+const canvasRef = useRef(null);
+
+<Form ref={formRef} refList={[canvasRef]}>
+  <Canvas
+    ref={canvasRef}
+    id="canvas"
+    label="Annotation (Required)"
+    canvasHeight={300}
+    enableDraw
+    onSubmit={(texts, drawings) => console.log(texts, drawings)}
+  />
+</Form>
+<Button text="Submit" onClick={() => formRef.current?.handleSubmit()} />
+```
+
+##### Required props
+
+| Name    | Type     | Description                  |
+| ------- | -------- | ---------------------------- |
+| `label` | `string` | Label shown above the canvas |
+
+##### Optional props
+
+| Name                       | Type                                                                                    | Default | Description                                                                                                        |
+| -------------------------- | --------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
+| `id`                       | `string`                                                                                | —       | Field identifier. Required when used as a form input ref                                                           |
+| `backgroundImageUrl`       | `string`                                                                                | —       | URL of an image to load as the canvas background. Fetched via axios                                                |
+| `texts`                    | `TextEntry[]`                                                                           | `[]`    | Pre-populated text entries                                                                                         |
+| `drawings`                 | `DrawingPath[]`                                                                         | `[]`    | Pre-populated drawing paths                                                                                        |
+| `enableDraw`               | `boolean`                                                                               | `false` | Show Draw, Erase, and Clear All toolbar buttons                                                                    |
+| `enableImageUpload`        | `boolean`                                                                               | `false` | Show an Images button that lets the user upload a local image and set it as the canvas background                  |
+| `optional`                 | `boolean`                                                                               | `false` | Skip required validation when used inside a Form                                                                   |
+| `disabled`                 | `boolean`                                                                               | `false` | Disable all interactions, show not-allowed cursor, and reduce opacity                                              |
+| `readOnly`                 | `boolean`                                                                               | `false` | Disable all interactions but keep the default cursor and full opacity                                              |
+| `cursor`                   | `string`                                                                                | —       | Override the canvas cursor style                                                                                   |
+| `canvasWidth`              | `number`                                                                                | `500`   | Canvas element width in pixels                                                                                     |
+| `canvasHeight`             | `number`                                                                                | `300`   | Canvas element height in pixels                                                                                    |
+| `darkMode`                 | `boolean`                                                                               | `false` | Enable dark mode label styling                                                                                     |
+| `subLabel`                 | `string`                                                                                | —       | Secondary label shown below the main label                                                                         |
+| `labelExtra`               | `ReactElement`                                                                          | —       | Extra element rendered inline with the label                                                                       |
+| `infoElement`              | `ReactElement`                                                                          | —       | Info element rendered in the label area                                                                            |
+| `customElement`            | `ReactElement`                                                                          | —       | Extra element rendered in the toolbar area                                                                         |
+| `className`                | `string`                                                                                | —       | Tailwind classes for the outer container                                                                           |
+| `containerClassName`       | `string`                                                                                | —       | Tailwind classes for the container wrapping label and canvas                                                       |
+| `canvasContainerClassName` | `string`                                                                                | —       | Tailwind classes for the canvas wrapper div                                                                        |
+| `onChange`                 | `(texts: TextEntry[]) => void`                                                          | —       | Called when text entries change                                                                                    |
+| `onDrawingsChange`         | `(drawings: DrawingPath[]) => void`                                                     | —       | Called when drawing paths change                                                                                   |
+| `onBackgroundImageChange`  | `(image: File \| null) => void`                                                         | —       | Called when the background image changes via upload. Receives `null` when using an image from `backgroundImageUrl` |
+| `onSubmit`                 | `(texts: TextEntry[], drawings: DrawingPath[], backgroundImage?: File \| null) => void` | —       | Called when the form is submitted successfully                                                                     |
+
+##### TextEntry
+
+| Name    | Type     | Description                                   |
+| ------- | -------- | --------------------------------------------- |
+| `id`    | `string` | Unique identifier                             |
+| `text`  | `string` | Text content                                  |
+| `color` | `string` | CSS color string, e.g. `"black"`, `"#ff0000"` |
+| `size`  | `number` | Font size in pixels                           |
+| `x`     | `number` | X position on the canvas                      |
+| `y`     | `number` | Y position on the canvas                      |
+
+##### DrawingPath
+
+| Name        | Type                         | Description                             |
+| ----------- | ---------------------------- | --------------------------------------- |
+| `id`        | `string`                     | Unique identifier                       |
+| `points`    | `{ x: number; y: number }[]` | Ordered list of points forming the path |
+| `color`     | `string`                     | Stroke color                            |
+| `lineWidth` | `number`                     | Stroke width in pixels                  |
+
+##### Using with Form
+
+`Canvas` implements the form input ref interface. When `optional=false` (default), `handleSubmit` validates that:
+
+- At least one text entry exists (when `enableDraw` is false)
+- At least one drawing exists (when `enableDraw` is true)
+
+```jsx
+const formRef = useRef(null);
+const canvasRef = useRef(null);
+
+<Form ref={formRef} refList={[canvasRef]}>
+  <Canvas ref={canvasRef} id="canvas" label="Annotation" enableDraw />
+</Form>;
+```