blixify-ui-web-mcp 0.1.1

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

@@ -0,0 +1,108 @@
+# Select
+
+<!-- STORY -->
+
+<hr>
+
+A versatile select component supporting single and multi select, multiple display types (dropdown, chips, radio view, modal), async search, dark mode, and custom action buttons.
+
+##### Import
+
+```js
+import { Select, Option } from "blixify-ui-web/input/select";
+```
+
+##### Usage
+
+Single select:
+
+```jsx
+const [value, setValue] = useState("");
+
+<Select
+  value={value}
+  label="Gender"
+  options={[
+    { key: "M", label: "Male" },
+    { key: "F", label: "Female" },
+  ]}
+  onChange={(v: string) => setValue(v)}
+/>;
+```
+
+Multi select with tags:
+
+```jsx
+const [value, setValue] = useState<string[]>([]);
+
+<Select
+  label="Gender"
+  options={options}
+  value={value}
+  showTag={true}
+  onChange={(v: string[]) => setValue(v)}
+/>
+```
+
+Async / database search:
+
+```jsx
+<Select
+  value={value}
+  label="Search"
+  options={dbOptions}
+  onChange={(v) => setValue(v)}
+  onSearch={(search) => fetchOptions(search)}
+/>
+```
+
+##### Required props
+
+| Name      | Type                 | Description                                                |
+| --------- | -------------------- | ---------------------------------------------------------- |
+| `value`   | `string \| string[]` | Current value. Pass `string[]` to enable multi select mode |
+| `label`   | `string`             | Field label                                                |
+| `options` | `Option[]`           | List of selectable options                                 |
+
+##### Optional props
+
+| Name                  | Type                                                                   | Default     | Description                                                                                                                                                                                                 |
+| --------------------- | ---------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type`                | `"default" \| "button" \| "icon" \| "chips" \| "radioview" \| "modal"` | `"default"` | Display type. `"button"` shows option images, `"icon"` shows option icons, `"chips"` renders inline chip toggles, `"radioview"` renders a radio/checkbox list, `"modal"` opens a dual-panel selection modal |
+| `id`                  | `string`                                                               | —           | Field identifier                                                                                                                                                                                            |
+| `placeholder`         | `string`                                                               | —           | Input placeholder text                                                                                                                                                                                      |
+| `optional`            | `boolean`                                                              | —           | Skip required validation                                                                                                                                                                                    |
+| `disabled`            | `boolean`                                                              | —           | Make the field read-only                                                                                                                                                                                    |
+| `newValue`            | `boolean`                                                              | —           | Allow the user to type and add a value not in the options list                                                                                                                                              |
+| `autoFocus`           | `boolean`                                                              | —           | Focus the input on mount                                                                                                                                                                                    |
+| `disableKeyboard`     | `boolean`                                                              | `false`     | Disable keyboard navigation in the dropdown                                                                                                                                                                 |
+| `showTag`             | `boolean`                                                              | —           | Show selected values as removable tags below the input (multi select only)                                                                                                                                  |
+| `closeOnClickOutside` | `boolean`                                                              | —           | Keep the dropdown open until the user clicks outside. Multi select only                                                                                                                                     |
+| `mobileView`          | `boolean`                                                              | —           | Open a bottom-sheet modal on screens narrower than 768px instead of the inline dropdown                                                                                                                     |
+| `portalDropdown`      | `boolean`                                                              | —           | Render the dropdown via a React portal (fixed position). Useful inside overflow-hidden containers                                                                                                           |
+| `staticDropdown`      | `boolean`                                                              | —           | Render the dropdown in static position (takes up space below the input) instead of absolute                                                                                                                 |
+| `darkMode`            | `boolean`                                                              | —           | Enable dark mode styling                                                                                                                                                                                    |
+| `subLabel`            | `string`                                                               | —           | Secondary label shown below the main label                                                                                                                                                                  |
+| `exclude`             | `string[]`                                                             | —           | Option keys to always exclude from the dropdown list                                                                                                                                                        |
+| `additional`          | `ReactElement`                                                         | —           | Extra element always shown at the bottom of the dropdown                                                                                                                                                    |
+| `customElement`       | `ReactElement`                                                         | —           | Extra element rendered next to the label                                                                                                                                                                    |
+| `labelExtra`          | `ReactElement`                                                         | —           | Extra element rendered inline with the label                                                                                                                                                                |
+| `infoElement`         | `ReactElement`                                                         | —           | Info element rendered in the label area                                                                                                                                                                     |
+| `containerClassName`  | `string`                                                               | —           | Tailwind classes for the outer container                                                                                                                                                                    |
+| `selectClassName`     | `string`                                                               | —           | Tailwind classes for the select trigger element                                                                                                                                                             |
+| `dropdownClassName`   | `string`                                                               | —           | Tailwind classes for the dropdown list                                                                                                                                                                      |
+| `imageClassName`      | `string`                                                               | —           | Tailwind classes for option images (used with `type="button"`)                                                                                                                                              |
+| `onChange`            | `(value: string \| string[]) => void`                                  | —           | Called with the updated value when selection changes                                                                                                                                                        |
+| `onSearch`            | `(value: string) => void`                                              | —           | Called as the user types. Use to fetch options dynamically                                                                                                                                                  |
+| `cellInput`           | `CellInput`                                                            | —           | Cell input config for use inside a Table component                                                                                                                                                          |
+
+##### Option
+
+| Name             | Type           | Required | Description                                                   |
+| ---------------- | -------------- | -------- | ------------------------------------------------------------- |
+| `key`            | `string`       | yes      | Unique option identifier — this is the value stored on select |
+| `label`          | `string`       | yes      | Display text                                                  |
+| `secondaryLabel` | `string`       | no       | Secondary text shown below the label                          |
+| `color`          | `string`       | no       | Tailwind color key or hex string for the label text           |
+| `image`          | `string`       | no       | Image URL shown when `type="button"`                          |
+| `icon`           | `ReactElement` | no       | Icon element shown when `type="icon"`                         |

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

@@ -0,0 +1,286 @@
+import { FolderPlusIcon, HomeIcon } from "@heroicons/react/24/outline";
+import { storiesOf } from "@storybook/react";
+import React, { useState } from "react";
+import { Option, Select } from ".";
+import { StorySection } from "../../storyUtils";
+import README from "./README.md";
+
+const stories = storiesOf("Input", module);
+
+stories.addParameters({
+  readme: {
+    content: README,
+  },
+});
+
+const genderOptions: Option[] = [
+  {
+    key: "M",
+    label: "Male",
+    secondaryLabel: "Secondary Label",
+    image:
+      "https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?ixlib=rb-1.2.1&auto=format&fit=facearea&facepad=2&w=256&h=256&q=80",
+    icon: <HomeIcon className="h-6 w-6 mr-3 group-hover:text-white" />,
+  },
+  {
+    key: "F",
+    label: "Female",
+    secondaryLabel: "Secondary Label",
+    image:
+      "https://images.unsplash.com/photo-1550525811-e5869dd03032?ixlib=rb-1.2.1&auto=format&fit=facearea&facepad=2&w=256&h=256&q=80",
+    icon: <FolderPlusIcon className="h-6 w-6 mr-3 group-hover:text-white" />,
+  },
+  {
+    key: "F2",
+    label: "Fluid",
+    secondaryLabel: "Secondary Label",
+    image:
+      "https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?ixlib=rb-1.2.1&auto=format&fit=facearea&facepad=2&w=256&h=256&q=80",
+    icon: <HomeIcon className="h-6 w-6 mr-3 group-hover:text-white" />,
+  },
+  {
+    key: "notToSay",
+    label: "Prefer Not To Say",
+    secondaryLabel: "Secondary Label",
+    image:
+      "https://images.unsplash.com/photo-1550525811-e5869dd03032?ixlib=rb-1.2.1&auto=format&fit=facearea&facepad=2&w=256&h=256&q=80",
+    icon: <FolderPlusIcon className="h-6 w-6 mr-3 group-hover:text-white" />,
+  },
+  {
+    key: "others",
+    label: "Others",
+    secondaryLabel: "Secondary Label",
+    image:
+      "https://images.unsplash.com/photo-1550525811-e5869dd03032?ixlib=rb-1.2.1&auto=format&fit=facearea&facepad=2&w=256&h=256&q=80",
+    icon: <FolderPlusIcon className="h-6 w-6 mr-3 group-hover:text-white" />,
+  },
+];
+
+stories.add("Select", () => {
+  const [value, setValue] = useState("");
+  const [multiValue, setMultiValue] = useState<string[]>(["M"]);
+  const [dbValue, setDBValue] = useState("");
+  const [dbOptions, setDBOptions] = useState<Option[]>([
+    { key: "M", label: "Male", secondaryLabel: "Secondary Label" },
+  ]);
+
+  const handleOptionSearch = (search: string) => {
+    if (search.includes("M")) {
+      setDBOptions([
+        { key: "M", label: "Male", secondaryLabel: "Secondary Label" },
+      ]);
+    } else if (search.includes("F")) {
+      setDBOptions([
+        { key: "F", label: "Female", secondaryLabel: "Secondary Label" },
+      ]);
+    }
+  };
+
+  return (
+    <>
+      <StorySection
+        title="Single & Multi Select"
+        description="Pass a string value for single select, or string[] for multi select. showTag=true renders selected values as removable tags below the input."
+      >
+        <div className="grid grid-cols-1 gap-4 md:grid-cols-2 w-full">
+          <Select
+            value={value}
+            label="Single Select"
+            options={genderOptions}
+            onChange={(v: string) => setValue(v)}
+          />
+          <Select
+            label="Multi Select"
+            options={genderOptions}
+            value={multiValue}
+            showTag={true}
+            onChange={(v: string[]) => setMultiValue(v)}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="New Value"
+        description="newValue=true lets the user type and add a value that isn't in the options list."
+      >
+        <div className="w-full md:w-1/2">
+          <Select
+            value={value}
+            label="Single Select with New Value"
+            options={genderOptions}
+            onChange={(v: string) => setValue(v)}
+            newValue
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Icon & Image Types"
+        description='type="icon" shows the option icon in the trigger. type="button" shows the option image. imageClassName controls the image size and shape.'
+      >
+        <div className="grid grid-cols-1 gap-4 md:grid-cols-2 w-full">
+          <Select
+            value={value}
+            label="With Icon"
+            type="icon"
+            options={genderOptions}
+            onChange={(v: string) => setValue(v)}
+          />
+          <Select
+            value={value}
+            label="With Image"
+            type="button"
+            imageClassName="h-6 w-6 mr-3 rounded-full"
+            options={genderOptions}
+            onChange={(v: string) => setValue(v)}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Chips"
+        description='type="chips" renders options as inline chip toggles instead of a dropdown. Works for both single and multi select.'
+      >
+        <div className="w-full space-y-4">
+          <Select
+            value={value}
+            label="Single Select (Chips)"
+            options={genderOptions}
+            type="chips"
+            onChange={(v: string) => setValue(v)}
+          />
+          <Select
+            label="Multi Select (Chips)"
+            options={genderOptions}
+            value={multiValue}
+            type="chips"
+            onChange={(v: string[]) => setMultiValue(v)}
+          />
+          <Select
+            label="Disabled (Chips)"
+            options={genderOptions}
+            value={multiValue}
+            type="chips"
+            disabled
+            onChange={(v: string[]) => setMultiValue(v)}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Radio View"
+        description='type="radioview" renders options as a radio/checkbox list. Works for both single and multi select.'
+      >
+        <div className="w-full space-y-4">
+          <Select
+            value={value}
+            label="Single Select (Radio View)"
+            options={genderOptions}
+            type="radioview"
+            onChange={(v: string) => setValue(v)}
+          />
+          <Select
+            label="Multi Select (Radio View)"
+            options={genderOptions}
+            value={multiValue}
+            type="radioview"
+            onChange={(v: string[]) => setMultiValue(v)}
+          />
+          <Select
+            label="Disabled (Radio View)"
+            options={genderOptions}
+            value={multiValue}
+            type="radioview"
+            disabled
+            onChange={(v: string[]) => setMultiValue(v)}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Modal Type"
+        description='type="modal" opens a dual-panel modal for moving options between available and selected lists. Useful for large option sets.'
+      >
+        <div className="w-full md:w-1/2">
+          <Select
+            label="Modal Select"
+            options={genderOptions}
+            value={multiValue}
+            type="modal"
+            onChange={(v: string[]) => setMultiValue(v)}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Mobile View"
+        description="mobileView=true opens a bottom-sheet modal on screens narrower than 768px instead of the inline dropdown."
+      >
+        <div className="w-full md:w-1/2">
+          <Select
+            value={value}
+            label="Mobile View"
+            options={genderOptions}
+            mobileView
+            onChange={(v: string) => setValue(v)}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Database / Async Search"
+        description="Pass onSearch to fetch options dynamically as the user types. Update the options prop with the search results."
+      >
+        <div className="w-full md:w-1/2">
+          <Select
+            value={dbValue}
+            label="Database Select"
+            options={dbOptions}
+            onChange={(v: string) => setDBValue(v)}
+            onSearch={handleOptionSearch}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Dark Mode"
+        description="Pass darkMode=true to switch to a dark-themed select."
+        dark
+      >
+        <div className="w-full md:w-1/2">
+          <Select
+            value={value}
+            label="Single Select"
+            type="icon"
+            options={genderOptions}
+            onChange={(v: string) => setValue(v)}
+            darkMode={true}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Disabled"
+        description="disabled=true makes the select read-only."
+      >
+        <div className="grid grid-cols-1 gap-4 md:grid-cols-2 w-full">
+          <Select
+            value={value}
+            label="Disabled Single"
+            options={genderOptions}
+            disabled={true}
+            onChange={(v: string) => setValue(v)}
+          />
+          <Select
+            label="Disabled Multi"
+            options={genderOptions}
+            value={multiValue}
+            disabled={true}
+            showTag={true}
+            onChange={(v: string[]) => setMultiValue(v)}
+          />
+        </div>
+      </StorySection>
+    </>
+  );
+});

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

@@ -0,0 +1,106 @@
+# Signature
+
+<!-- STORY -->
+
+<hr>
+
+E-signature component with a resizable canvas, optional pre-loaded image, clear/reset controls, and form validation support.
+
+### Import
+
+```js
+import { Signature } from "blixify-ui-web/input/signature";
+```
+
+### Usage
+
+```jsx
+const signatureRef = useRef(null);
+const [signing, setSigning] = useState(false);
+const [preview, setPreview] = useState("");
+
+// Give the parent a fixed height — the canvas fills it
+<div className="h-72">
+  <Signature
+    id="signature"
+    ref={signatureRef}
+    label="Signature"
+    signing={signing}
+    penColor="black"
+    signatureClear={true}
+    onChange={setSigning}
+    onSubmit={(_, dataURL) => setPreview(dataURL ?? "")}
+  />
+</div>
+<Button text="Submit" onClick={() => signatureRef.current?.handleSubmit()} />
+```
+
+### Validation via ref
+
+`handleSubmit()` returns a `Promise<boolean>`. It passes when:
+
+- `optional` is `true`, or
+- `dataURL` is set (existing signature from server), or
+- the user has drawn on the canvas (`signing` is `true`)
+
+### Pre-loading an existing signature
+
+```jsx
+<div className="h-72">
+  <Signature
+    id="signature"
+    ref={signatureRef}
+    dataURL="https://example.com/signature.png"
+    signing={signing}
+    label="Signature"
+    signatureClear={true}
+    onChange={setSigning}
+    onSubmit={(_, dataURL) => setPreview(dataURL ?? "")}
+  />
+</div>
+```
+
+The image at `dataURL` must have `Access-Control-Allow-Origin: *`. A Reset button appears automatically when `dataURL` is set.
+
+### Inside a Modal
+
+Force remount with a `key` prop when the modal opens so the canvas measures its container correctly:
+
+```jsx
+const [modalKey, setModalKey] = useState(0);
+
+<Button text="Open" onClick={() => { setIsOpen(true); setModalKey(k => k + 1); }} />
+<Modal open={isOpen} ...>
+  <div className="h-72">
+    <Signature key={modalKey} id="sig" ... />
+  </div>
+</Modal>
+```
+
+### Required props
+
+| Name      | Type      | Description                                 |
+| --------- | --------- | ------------------------------------------- |
+| `id`      | `string`  | HTML id for the component                   |
+| `label`   | `string`  | Label displayed above the canvas            |
+| `signing` | `boolean` | Tracks whether the canvas has been drawn on |
+
+### Optional props
+
+| Name                       | Type                                      | Default   | Description                                                                                                      |
+| -------------------------- | ----------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------- |
+| `dataURL`                  | `string`                                  | —         | URL of an existing signature image to pre-load. Must allow CORS (`Access-Control-Allow-Origin: *`)               |
+| `subLabel`                 | `string`                                  | —         | Secondary label shown below the main label                                                                       |
+| `labelExtra`               | `ReactElement`                            | —         | Extra element rendered inline with the label                                                                     |
+| `infoElement`              | `ReactElement`                            | —         | Content shown in an InfoWindow tooltip next to the label                                                         |
+| `customElement`            | `ReactElement`                            | —         | Custom element rendered in the label row (right side)                                                            |
+| `optional`                 | `boolean`                                 | `false`   | Skips validation when `true`                                                                                     |
+| `darkMode`                 | `boolean`                                 | `false`   | Switches label colours for dark backgrounds                                                                      |
+| `penColor`                 | `string`                                  | `"black"` | Ink colour for the signature canvas                                                                              |
+| `signatureClear`           | `boolean`                                 | `false`   | Shows a Clear button to wipe the canvas                                                                          |
+| `description`              | `string`                                  | —         | Text shown above the pad. Wrap in `*asterisks*` for bold. Blank lines create paragraph spacing.                  |
+| `className`                | `tailwind class`                          | —         | Class applied to the outer container                                                                             |
+| `containerClassName`       | `tailwind class`                          | —         | Class applied to the component wrapper                                                                           |
+| `canvasContainerClassName` | `tailwind class`                          | —         | Class applied to the canvas border/shadow container                                                              |
+| `onChange`                 | `(signing: boolean) => void`              | —         | Called when the user starts drawing (`true`) or the canvas is cleared (`false`)                                  |
+| `onSubmit`                 | `(result: any, dataURL?: string) => void` | —         | Called on successful `handleSubmit`. `dataURL` is a base64 PNG string of the drawn signature, or `""` if cleared |