@poirazis/supercomponents-shared 1.1.8 → 1.2.0

package/src/lib/SuperTableCells/CellTags.svelte

@@ -13,7 +13,7 @@
 
   export let cellOptions;
   export let value;
-  export let fieldSchema;
+
   export let autofocus;
 
   let anchor;
@@ -35,6 +35,33 @@
 
   let searchInput;
 
+  // Helper function to add tags while preventing duplicates (case-insensitive comparison)
+  const addUniqueTags = (tagsToAdd) => {
+    if (!tagsToAdd || !tagsToAdd.length) return;
+
+    const existingLower = new Set(
+      (localValue || []).map((t) =>
+        String(t || "")
+          .toLowerCase()
+          .trim()
+      )
+    );
+
+    const newTags = [];
+    tagsToAdd.forEach((tag) => {
+      const trimmedTag = String(tag || "").trim();
+      if (trimmedTag && !existingLower.has(trimmedTag.toLowerCase())) {
+        newTags.push(trimmedTag);
+        existingLower.add(trimmedTag.toLowerCase());
+      }
+    });
+
+    if (newTags.length) {
+      localValue = [...(localValue || []), ...newTags];
+      cellState.change();
+    }
+  };
+
   const colors = derivedMemo(options, ($options) => {
     let obj = {};
     $options.forEach(
@@ -179,16 +206,25 @@
     },
     Editing: {
       _enter() {
-        originalValue = JSON.stringify(value);
+        originalValue = JSON.stringify(
+          Array.isArray(value) ? value : value ? [value] : []
+        );
         this.clearFilters();
+        editorState.open();
         dispatch("enteredit");
       },
       _exit() {
         editorState.close();
         dispatch("exitedit");
       },
+      focus() {
+        anchor?.focus();
+      },
       focusout(e) {
-        if ($editorState == "Open" || anchor?.contains(e.relatedTarget)) {
+        if (
+          anchor?.contains(e.relatedTarget) ||
+          editor?.contains(e.relatedTarget)
+        ) {
           return;
         } else {
           this.submit();
@@ -215,6 +251,8 @@
         this.submit();
       },
       cancel() {
+        editorState.close();
+        localValue = JSON.parse(originalValue);
         anchor?.blur();
         return "View";
       },
@@ -238,8 +276,8 @@
             localValue.splice(pos, 1);
             localValue = [...localValue];
           } else {
-            // Add if not selected
-            localValue = [...localValue, option];
+            // Add only if not already in localValue
+            addUniqueTags([option]);
           }
           cellState.change();
           // Check if we need to fetch more options
@@ -254,8 +292,8 @@
             localValue.splice(pos, 1);
             localValue = [...localValue];
           } else {
-            // Add if not selected
-            localValue = [...localValue, option];
+            // Add only if not already in localValue
+            addUniqueTags([option]);
           }
           cellState.change();
           // Check if we need to fetch more options
@@ -277,8 +315,7 @@
             .split(",")
             .map((tag) => tag.trim())
             .filter((tag) => tag);
-          localValue = [...localValue, ...tags];
-          cellState.change();
+          addUniqueTags(tags);
         }
         searchTerm = "";
         newTag = null;
@@ -329,14 +366,11 @@
         if (e.key == "Enter") {
           // Add new tag if exists
           if (newTag?.trim()) {
-            localValue = [
-              ...localValue,
-              ...newTag
-                .split(",")
-                .map((tag) => tag.trim())
-                .filter((tag) => tag),
-            ];
-            cellState.change();
+            const tags = newTag
+              .split(",")
+              .map((tag) => tag.trim())
+              .filter((tag) => tag);
+            addUniqueTags(tags);
             newTag = null;
             searchTerm = "";
             // Refocus input
@@ -353,16 +387,29 @@
           // If no focused option, allow space to be input into the search box
         }
         if (e.key == "Tab") {
-          if (focusedOptionIdx > -1 && filteredOptions[focusedOptionIdx])
-            this.toggleOption(focusedOptionIdx);
+          anchor?.focus();
+          editorState.close();
+          e.preventDefault();
+          return;
+        }
 
-          // Keep popup open - no submit/close
+        if (e.key == "Escape") {
+          newTag = null;
+
+          editorState.close();
+          anchor?.focus();
+
+          e.preventDefault();
+          e.stopPropagation();
+          return;
         }
 
         if (e.key == "ArrowDown") this.highlightNext(e.stopPropagation());
         if (e.key == "ArrowUp")
           this.highlightPrevious(e.preventDefault(), e.stopPropagation());
-        if (e.key == "Escape") this.close();
+        if (e.key == "Escape") {
+          cellState.cancel();
+        }
       },
 
       handleKeyboard(e) {
@@ -389,8 +436,6 @@
         if (e.key == "ArrowDown") this.highlightNext();
         if (e.key == "ArrowUp") this.highlightPrevious(e.preventDefault());
 
-        if (e.key == "Escape") this.close();
-
         if (controlType != "inputSelect") search = true;
       },
       highlightNext() {
@@ -526,19 +571,16 @@
   class:multirow={true}
   style:color
   style:background
-  style:font-weight={cellOptions.fontWeight}
   class:inline={role == "inlineInput"}
   class:tableCell={role == "tableCell"}
   class:formInput={role == "formInput"}
   on:focusin={cellState.focus}
-  on:focusout={(e) => {
-    setTimeout(() => cellState.focusout(e), 50);
-  }}
+  on:focusout={cellState.focusout}
   on:keydown={editorState.handleKeyboard}
 >
   <div class="value" class:placeholder={isEmpty} tabindex="-1">
     {#if isEmpty && !inEdit}
-      <span>{cellOptions.placeholder || "No Tags"}</span>
+      <span>{cellOptions.placeholder || "Add some Tags"}</span>
     {/if}
 
     <div
@@ -553,7 +595,6 @@
             class="tag"
             style:--option-color={$colors[tag] ||
               colorsArray[idx % colorsArray.length]}
-            tabindex="-1"
           >
             <span class="tag-wrap">
               <span> {tag} </span>
@@ -565,7 +606,7 @@
                 style:z-index={2}
                 on:mousedown|preventDefault|stopPropagation={() =>
                   editorState.toggleOption(tag)}
-              />
+              ></i>
             {/if}
           </div>
         {/each}
@@ -573,8 +614,8 @@
 
       {#if inEdit}
         <i
-          class="ph ph-plus-circle actionIcon"
-          on:mousedown|preventDefault|stopPropagation={editorState.toggle}
+          class="ph ph-plus actionIcon"
+          on:mouseup|preventDefault|stopPropagation={editorState.toggle}
         ></i>
       {/if}
     </div>
@@ -589,83 +630,78 @@
     useAnchorWidth
     maxHeight={250}
     open={$editorState == "Open"}
-    on:close={(e) => {
-      editorState.close();
-      cellState.focusout({});
-    }}
   >
-    <div class="searchControl" on:keydown={editorState.handleInputKeyboard}>
-      <i
-        class={suggestions ? "ph ph-magnifying-glass" : "ph ph-pencil-simple"}
-        class:actionIcon={true}
-      ></i>
-      <input
-        type="text"
-        placeholder={suggestions ? "Search or Add" : "Enter tag..."}
-        class="searchInput"
-        bind:value={searchTerm}
-        bind:this={searchInput}
-        on:input={(e) => editorState.filterOptions(e.target.value)}
-        on:focusout={(e) => {
-          editorState.close();
-          anchor?.focus();
-        }}
-        use:focus
-      />
-    </div>
+    <div bind:this={editor} class="editor" tabindex="-1">
+      <div class="searchControl" on:keydown={editorState.handleInputKeyboard}>
+        <i
+          class={suggestions ? "ph ph-magnifying-glass" : "ph ph-pencil-simple"}
+          class:actionIcon={true}
+        ></i>
+        <input
+          type="text"
+          placeholder={suggestions ? "Search or Add" : "Enter tag..."}
+          class="searchInput"
+          bind:value={searchTerm}
+          bind:this={searchInput}
+          on:input={(e) => editorState.filterOptions(e.target.value)}
+          on:focusout={cellState.focusout}
+        />
+      </div>
 
-    {#if suggestions}
-      <div
-        bind:this={picker}
-        class="options"
-        on:wheel={(e) => e.stopPropagation()}
-        on:mouseleave={() => (focusedOptionIdx = -1)}
-        on:scroll={suggestions ? handleScroll : null}
-      >
-        {#if suggestions}
-          {#if $fetch?.loading && !$fetch?.rows?.length}
-            <div class="option loading">
-              <i class="ri-loader-2-line rotating" />
-              Loading...
-            </div>
-          {:else if filteredOptions?.length}
-            {#each filteredOptions as option, idx (idx)}
-              {#if !localValue?.includes(option)}
-                <div
-                  class="option"
-                  class:text={optionsViewMode == "text"}
-                  class:focused={focusedOptionIdx === idx}
-                  style:--option-color={$colors[option]}
-                  on:mousedown|preventDefault={(e) =>
-                    editorState.toggleOption(idx)}
-                  on:mouseenter={() => (focusedOptionIdx = idx)}
-                >
-                  <span>
-                    {#if cellOptions.optionsViewMode !== "text"}
-                      <i class="ri-checkbox-blank-fill" />
-                    {/if}
-                    {option}
-                  </span>
+      {#if suggestions}
+        <div
+          bind:this={picker}
+          class="options"
+          on:wheel={(e) => e.stopPropagation()}
+          on:mouseleave={() => (focusedOptionIdx = -1)}
+          on:scroll={suggestions ? handleScroll : null}
+          on:mousedown|preventDefault|stopPropagation
+        >
+          {#if suggestions}
+            {#if $fetch?.loading && !$fetch?.rows?.length}
+              <div class="option loading">
+                <i class="ri-loader-2-line rotating"></i>
+                Loading...
+              </div>
+            {:else if filteredOptions?.length}
+              {#each filteredOptions as option, idx (idx)}
+                {#if !localValue?.includes(option)}
+                  <div
+                    class="option"
+                    class:text={optionsViewMode == "text"}
+                    class:focused={focusedOptionIdx === idx}
+                    style:--option-color={$colors[option]}
+                    on:mousedown|preventDefault={(e) =>
+                      editorState.toggleOption(idx)}
+                    on:mouseenter={() => (focusedOptionIdx = idx)}
+                  >
+                    <span>
+                      {#if cellOptions.optionsViewMode !== "text"}
+                        <i class="ri-checkbox-blank-fill"></i>
+                      {/if}
+                      {option}
+                    </span>
+                  </div>
+                {/if}
+              {/each}
+              {#if $fetch?.loading}
+                <div class="option loading">
+                  <i class="ri-loader-2-line rotating"></i>
+                  Loading more...
                 </div>
               {/if}
-            {/each}
-            {#if $fetch?.loading}
-              <div class="option loading">
-                <i class="ri-loader-2-line rotating" />
-                Loading more...
+            {:else}
+              <div class="option not-found">
+                <span>
+                  <i class="ri-close-line"></i>
+                  No matches found, Tag will be added as new
+                </span>
               </div>
             {/if}
-          {:else}
-            <div class="option not-found">
-              <span>
-                <i class="ri-close-line" />
-                No matches found, Tag will be added as new
-              </span>
-            </div>
           {/if}
-        {/if}
-      </div>
-    {/if}
+        </div>
+      {/if}
+    </div>
   </SuperPopover>
 {/if}
 
@@ -697,9 +733,15 @@
     text-transform: uppercase;
     outline: none;
     max-width: 7rem;
+    transition: all 0.2s ease-in-out;
 
     &:hover {
       filter: brightness(0.9);
+
+      & > i {
+        display: block;
+        cursor: pointer;
+      }
     }
 
     & > span {
@@ -707,6 +749,12 @@
       text-overflow: ellipsis;
       white-space: nowrap;
     }
+
+    & > i {
+      display: none;
+      cursor: pointer;
+      transition: all 0.2s ease-in-out;
+    }
   }
 
   .searchControl {
@@ -745,11 +793,6 @@
       cursor: pointer;
     }
 
-    &.selected {
-      color: var(--spectrum-global-color-gray-800);
-      font-weight: 600;
-    }
-
     &.focused {
       background-color: var(--spectrum-global-color-gray-75);
       color: var(--spectrum-global-color-gray-800);
@@ -805,7 +848,7 @@
     display: flex;
     justify-content: center;
     align-items: center;
-    font-size: 1rem;
+    font-size: 0.85rem;
     color: var(--spectrum-global-color-gray-600);
   }
   .actionIcon:hover {

package/src/lib/SuperTableCells/JSDOC_GUIDE.md

@@ -26,7 +26,167 @@ This guide demonstrates how to use JSDoc annotations for **type definitions only
 
 ## Type Definitions
 
-All types are defined in `types.js` using JSDoc `@typedef` syntax.
+All types are defined in `types.js` using a **unified CellOptions type**:
+
+- `CellOptions` - Single type with common base properties + optional type-specific extensions
+- `CellApi` - Standard API interface exported by all cells
+- `CellRole`, `CellState`, `CellAlign` - Enum types
+- `FieldSchema` - Budibase field schema type
+
+### CellOptions Structure
+
+The unified `CellOptions` type contains:
+
+- **Common properties** (role, readonly, disabled, placeholder, etc.) - used by all cells
+- **Type-specific properties** organized by category (Number, Boolean, Options, Datetime, etc.)
+
+All properties are optional except where noted. Components only use the properties relevant to them.
+
+## Cell FSM State Machine
+
+All cell components use a finite state machine (FSM) managed by `svelte-fsm` to handle user interactions and data loading states. The FSM provides a clean, declarative way to manage component state transitions.
+
+### Core States
+
+The cell FSM supports three core reachable states:
+
+| State       | Usage                                   | Transitions                             |
+| ----------- | --------------------------------------- | --------------------------------------- |
+| **View**    | Default display state, read-only        | → Editing (on focus)                    |
+| **Editing** | User is actively editing the cell value | → View (on focusout, submit, or cancel) |
+| **Loading** | Data is being fetched or processed      | → View (when data loads)                |
+
+### State Diagram
+
+```
+┌──────────────────────────────────┐
+│                                  │
+│    View (Display Mode)           │
+│    - Shows formatted value       │
+│    - Read-only or ready to edit  │
+│                                  │
+└──────────────────────────────────┘
+              ↑
+              │ focusout()
+              │ submit()
+              │ cancel()
+              │
+              ↓
+┌──────────────────────────────────┐
+│                                  │
+│    Editing (Edit Mode)           │
+│    - Input field active          │
+│    - User can modify value       │
+│    - Dispatch change events      │
+│                                  │
+└──────────────────────────────────┘
+              ↑
+              │ focus()
+              │ (when not readonly)
+              │
+┌──────────────────────────────────┐
+│                                  │
+│    Loading (Async Mode)          │
+│    - Fetching data from server   │
+│    - Data-dependent cells only   │
+│    - Auto-transitions to View    │
+│                                  │
+└──────────────────────────────────┘
+```
+
+### Global Transitions (Available in All States)
+
+All states support these global methods via the `"*"` state:
+
+```javascript
+export const cellState = fsm("View", {
+  "*": {
+    goTo(state) {
+      // Manual state transition (for external control)
+      return state;
+    },
+    reset(value) {
+      // Reset to initial value and View state
+      localValue = undefined;
+    },
+  },
+  // ... state-specific transitions
+});
+```
+
+### Lifecycle Hooks
+
+State transitions can trigger lifecycle methods:
+
+- **`_enter()`** - Called when entering a state
+- **`_exit()`** - Called when exiting a state
+
+Example from CellString:
+
+```javascript
+Editing: {
+  _enter() {
+    originalValue = JSON.stringify(localValue);  // Save for rollback
+    dispatch("enteredit");                       // Notify parent
+  },
+  _exit() {
+    dispatch("exitedit");                        // Cleanup
+  },
+  focusout() {
+    this.submit();  // Submit on blur
+  },
+  submit() {
+    dispatch("change", localValue);
+    return "View";  // Transition back to View
+  },
+},
+```
+
+### Usage Pattern
+
+```javascript
+// Declare FSM with initial state
+export const cellState = fsm(cellOptions.initialState ?? "View", {
+  View: {
+    /* ... */
+  },
+  Editing: {
+    /* ... */
+  },
+  Loading: {
+    /* ... */
+  }, // Optional, for data-dependent cells
+});
+
+// Subscribe to state changes in component
+$: inEdit = $cellState === "Editing";
+$: isDirty = inEdit && originalValue !== JSON.stringify(localValue);
+
+// Trigger transitions from event handlers
+const handleFocus = () => cellState.focus();
+const handleBlur = () => cellState.focusout();
+```
+
+### Data-Dependent Cells
+
+Cells that fetch data (CellOptions, CellTags, CellOptionsAdvanced) use the Loading state:
+
+```javascript
+Loading: {
+  _enter() {
+    // Fetch data from server
+    loadOptions();
+  },
+  syncFetch(fetch) {
+    // Handle synchronous fetch results
+    return "View";  // Auto-transition when done
+  },
+  focus() {
+    // Allow editing while loading
+    return "Editing";
+  },
+},
+```
 
 ## JavaScript Example: CellString.svelte (Reference Implementation)
 
@@ -36,7 +196,7 @@ All types are defined in `types.js` using JSDoc `@typedef` syntax.
   import fsm from "svelte-fsm";
 
   /**
-   * @typedef {import('./types.js').CellStringOptions} CellStringOptions
+   * @typedef {import('./types.js').CellOptions} CellOptions
    * @typedef {import('./types.js').CellApi} CellApi
    */
 
@@ -49,7 +209,7 @@ All types are defined in `types.js` using JSDoc `@typedef` syntax.
   /** @type {string | undefined} */
   export let formattedValue = undefined;
 
-  /** @type {CellStringOptions} */
+  /** @type {CellOptions} */
   export let cellOptions = {
     role: "formInput",
     initialState: "Editing",