Add Sort by Functionality to Tag Column

Goal:

1. Frequency of tag usage, toggle from most to least and least to most
2. Alphabetic order, toggle from A to Z and Z to A

Context

Our Existing Implementation

Our Current Render Pipeline:

1. site/src/pages/toolkit.astro
2. site/src/layouts/ToolkitLayout.astro
3. site/src/components/tool-components/TagColumn.astro 4. site/src/components/tool-components/TagChip.astro
4. site/src/components/tool-components/CardGrid.astro 6. site/src/components/tool-components/ToolCard.astro 7. site/src/components/tool-components/BareToolCard.astro

Data Flow and Sorting Logic (Technical Specification)

Data Flow Overview

• toolkit.astro : Loads all tools and their tags from content collections or API.
• ToolkitLayout.astro : Receives all tool data as props, extracts tags, and passes them to TagColumn .
  • Does not use hard "Type Safety" per our constraints, as the Content Team does not always maintain perfect metadata.
• TagColumn.astro : Receives an array of tags (with frequency counts) as a prop, displays them, and implements sorting logic and UI.
• TagChip.astro : Receives a single tag (and possibly its frequency/count) as a prop, renders it as a clickable or display element.

Mermaid Diagram

Implementation Approach

Example Code Snippets

1. toolkit.astro (top-level page)

---
import ToolkitLayout from '../layouts/ToolkitLayout.astro';
import { getAllTools } from '~/lib/data';

const tools = await getAllTools();
const tags = extractTagsWithCounts(tools); // [{ tag: 'AI', count: 12 }, ...]
---
<ToolkitLayout tools={tools} tags={tags} />

2. ToolkitLayout.astro (layout)

---
const { tools, tags } = Astro.props;
import TagColumn from '../components/tool-components/TagColumn.astro';
---
<div class="toolkit-layout">
  <TagColumn tags={tags} />
  <!-- ...other layout components... -->
</div>

3. TagColumn.astro (component)

---
const { tags } = Astro.props;
import TagChip from './TagChip.astro';

// Initial values for client-side sorting
let sortType = 'frequency-desc';

// Function to sort tags based on sort type
function getSortedTags(tags, sortType) {
  if (sortType === 'frequency-desc') return [...tags].sort((a, b) => b.count - a.count);
  if (sortType === 'frequency-asc') return [...tags].sort((a, b) => a.count - b.count);
  if (sortType === 'alpha-asc') return [...tags].sort((a, b) => a.tag.localeCompare(b.tag));
  if (sortType === 'alpha-desc') return [...tags].sort((a, b) => b.tag.localeCompare(a.tag));
  return tags; // Default fallback
}

// Get initial sorted tags for initial render
const initialSortedTags = getSortedTags(tags, sortType);
---

<div class="tag-column">
  <!-- Sort controls -->
  <div class="sort-controls">
    <button id="sort-alpha" class="sort-button" data-sort-type="alpha-asc" aria-label="Sort alphabetically">
      <span class="icon">A-Z</span>
    </button>
    <button id="sort-freq" class="sort-button active" data-sort-type="frequency-desc" aria-label="Sort by frequency">
      <span class="icon">#</span>
    </button>
  </div>
  
  <!-- Tag list (initial render) -->
  <div id="tag-list" class="tag-list" data-tags={JSON.stringify(tags)}>
    {initialSortedTags.map(tag => (
      <TagChip 
        tag={tag.tag} 
        count={tag.count} 
        id={`tag-${tag.tag}`}
      />
    ))}
  </div>
</div>

<!-- Client-side interactivity with vanilla JS -->
<script>
  // Get DOM elements
  const sortAlphaBtn = document.getElementById('sort-alpha');
  const sortFreqBtn = document.getElementById('sort-freq');
  const tagList = document.getElementById('tag-list');
  
  // Get tag data from the data attribute
  const tags = JSON.parse(tagList.dataset.tags);
  
  // Current sort state
  let currentSortType = 'frequency-desc';
  
  // Sort function (same as in the component front matter)
  function getSortedTags(tags, sortType) {
    if (sortType === 'frequency-desc') return [...tags].sort((a, b) => b.count - a.count);
    if (sortType === 'frequency-asc') return [...tags].sort((a, b) => a.count - b.count);
    if (sortType === 'alpha-asc') return [...tags].sort((a, b) => a.tag.localeCompare(b.tag));
    if (sortType === 'alpha-desc') return [...tags].sort((a, b) => b.tag.localeCompare(a.tag));
    return tags;
  }
  
  // Render function to update the tag list
  function renderTags() {
    const sortedTags = getSortedTags(tags, currentSortType);
    
    // Clear current list
    tagList.innerHTML = '';
    
    // Add sorted tags
    sortedTags.forEach(tag => {
      // Create a new tag chip element
      const chip = document.createElement('div');
      chip.id = `tag-${tag.tag}`;
      chip.className = 'tag-chip';
      
      // Convert train-case to Normal Case for display
      const normalCase = tag.tag
        .split('-')
        .map(word => word.charAt(0).toUpperCase() + word.slice(1))
        .join(' ');
      
      chip.innerHTML = `
        ${normalCase}
        <span class="tag-count">${tag.count}</span>
      `;
      
      // Add click event listener
      chip.addEventListener('click', () => {
        window.location.href = `/toolkit/${encodeURIComponent(tag.tag)}`;
      });
      
      tagList.appendChild(chip);
    });
  }
  
  // Event handlers for sort buttons
  sortAlphaBtn.addEventListener('click', () => {
    // Toggle between alpha-asc and alpha-desc
    currentSortType = currentSortType === 'alpha-asc' ? 'alpha-desc' : 'alpha-asc';
    
    // Update active button state
    sortAlphaBtn.classList.add('active');
    sortFreqBtn.classList.remove('active');
    
    // Update button data attribute
    sortAlphaBtn.dataset.sortType = currentSortType;
    
    // Re-render tags
    renderTags();
  });
  
  sortFreqBtn.addEventListener('click', () => {
    // Toggle between frequency-desc and frequency-asc
    currentSortType = currentSortType === 'frequency-desc' ? 'frequency-asc' : 'frequency-desc';
    
    // Update active button state
    sortFreqBtn.classList.add('active');
    sortAlphaBtn.classList.remove('active');
    
    // Update button data attribute
    sortFreqBtn.dataset.sortType = currentSortType;
    
    // Re-render tags
    renderTags();
  });
</script>

4. TagChip.astro (component)

---
// Define props interface
interface Props {
  tag: string;
  count?: number;
  includeCount?: boolean;
  id?: string;
}

// Destructure props
const { tag, count, includeCount = false, id } = Astro.props;

// Convert train-case to Normal Case for display
function trainCaseToNormalCase(tag) {
  return tag
    .split('-')
    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
    .join(' ');
}

const normalCase = trainCaseToNormalCase(tag);
---

<button
  class="tag-chip"
  id={id}
  data-tag={tag}
  aria-label={`Click to see content tagged with ${normalCase}`}
  title={`Click to see content tagged with ${normalCase}`}
>
  {normalCase}
  {includeCount && count !== undefined && <span class="tag-count">{count}</span>}
</button>

<script>
  // Get all tag chips
  const tagChips = document.querySelectorAll('.tag-chip');
  
  // Add click event listeners
  tagChips.forEach(chip => {
    chip.addEventListener('click', () => {
      const tag = chip.dataset.tag;
      // Navigate to filtered view or trigger filter action
      window.location.href = `/toolkit/${encodeURIComponent(tag)}`;
    });
  });
</script>

UI/UX Requirements

Sort Controls

• Placement : At the top of the tag column, above the list of tags.
• Appearance : Simple, icon-based buttons that clearly indicate their purpose.
• Functionality :
  • Clicking the "A-Z" button toggles between alphabetical ascending (A-Z) and descending (Z-A).
  • Clicking the "#" button toggles between frequency descending (most used first) and ascending (least used first).
  • The currently active sort criterion should be visually indicated.

<div class="tag-sort-toggle">
  <button class="sort-alpha" id="sort-alpha">
    <Icon name="tabler:list-letters" />
    <!-- Optionally indicate direction/state -->
  </button>
  <button class="sort-frequency" id="sort-freq">
    <Icon name="tabler:sort-descending-numbers" />
    <!-- Optionally indicate direction/state -->
  </button>
</div>

Tag Chip Accessibility

• Each TagChip should have appropriate ARIA attributes and title for accessibility.
• The text displayed should be in Normal Case for readability, even if the tag is stored in train-case.

Usage Example in TagChip (Astro)

const normalCase = trainCaseToNormalCase(tag);

<button
  class="tag-chip"
  aria-label={`Click to see content tagged with ${normalCase}`}
  title={`Click to see content tagged with ${normalCase}`}
>
  {normalCase}
  {count && <span class="tag-count">{count}</span>}
</button>

• This ensures screen readers and tooltips provide a human-friendly, descriptive label for each tag.

Mobile Responsiveness

• On mobile devices, the tag column should be collapsible to save space.
• Default (Mobile): TagColumn is collapsed, visible as a slim tab or icon on the left.
• User taps tab/icon: TagColumn expands, showing all tags and sorting controls.
• User selects a tag: TagColumn immediately collapses, revealing filtered results in the main content area.
• User can re-expand TagColumn at any time to change selection.
• The collapse/expand state should be managed in client-side JavaScript using a <script> block with event listeners.

Reusability & Abstraction Guidelines

• TagColumn must accept a prop named collectionExtractedTagArray , which is an array of tag objects from any collection or data source.
  • Example:
    js

    [
      { tag: "AI", count: 12 },
      { tag: "Productivity", count: 5 }
    ]

  • The source of the tag array (content collection, API, static data, etc.) is not the concern of TagColumn.
  • The component should not assume anything about the parent context except that it receives this array.
• TagChip should be presentational by default, but may optionally accept additional props for:
  • Its current sort state (e.g., through data attributes)
  • Its index/order in the current sort (e.g., through data attributes)
  • Any other metadata useful for accessibility or UI (e.g., aria-label , title , etc.)
  • These props should be optional and documented, so TagChip can be used in both simple and advanced scenarios.
• State Management :
  • Use Astro's client-side scripting with standard <script> blocks for interactive functionality.
  • TagColumn should manage its own sort state with client-side JavaScript.
  • Store the current sort state in a variable and use it to update the UI when the user interacts with the sort controls.
  • Use DOM manipulation to update the tag list when the sort order changes.
• Example Prop Interface :
  ts

  // For TagColumn
  type TagColumnProps = {
    collectionExtractedTagArray: Array<{ tag: string; count?: number; [key: string]: any }>;
    // ...other config options
  }
  
  // For TagChip
  type TagChipProps = {
    tag: string;
    count?: number;
    id?: string;
    // ...other UI/accessibility props
  }

• Flexibility :
  • TagColumn and TagChip should not be tightly coupled to any specific data source or sort logic.
  • Document the expected shape of the tag array and optional props for maximum developer clarity.

Selected Tags Feature Implementation

1. Approach Overview

1. Track Selected Tags : Add a mechanism to track which tags are currently selected
2. Modify Sort Logic : Update the sorting logic to prioritize selected tags
3. Visual Indicators : Enhance the UI to clearly show selected tags
4. Multiple Selection : Enable multiple tag selection with appropriate URL handling
5. Card Sorting : Sort tool cards based on how many selected tags they match

2. Implementation Details

1. Update the TagColumn Component :
   • Add functionality to track selected tags in client-side state
   • Modify the sort function to prioritize selected tags
   • Update the rendering logic to visually distinguish selected tags
   • Implement "OR" logic for filtering (show cards matching ANY selected tag)
   • Sort cards by match count (cards matching more tags appear first)
2. Enhance the TagChip Component :
   • Add a "selected" state that can be toggled
   • Update the styling to show a clear visual difference for selected tags
3. URL and Navigation Handling :
   • Modify the URL structure to support multiple tag parameters
   • Update the click handlers to toggle tags rather than navigate directly
   • Preserve state in the URL for bookmarking and sharing

3. Code Implementation Examples

// In TagColumn.astro client script
let selectedTags = [];

// Check URL for already selected tags
const urlParams = new URLSearchParams(window.location.search);
if (urlParams.has('tags')) {
  selectedTags = urlParams.get('tags').split(',');
}

// Function to toggle tag selection
function toggleTagSelection(tag) {
  if (selectedTags.includes(tag)) {
    selectedTags = selectedTags.filter(t => t !== tag);
  } else {
    selectedTags.push(tag);
  }
  
  // Update URL
  const newUrl = new URL(window.location);
  if (selectedTags.length > 0) {
    newUrl.searchParams.set('tags', selectedTags.join(','));
  } else {
    newUrl.searchParams.delete('tags');
  }
  history.pushState({}, '', newUrl);
  
  // Re-render tags with new selection state
  renderTags();
  
  // Trigger content filtering
  filterContent(selectedTags);
}

// Modified sort function to prioritize selected tags
function getSortedTags(tags, sortType, selectedTags) {
  // First sort by selection status
  const sortedTags = [...tags].sort((a, b) => {
    const aSelected = selectedTags.includes(a.tag);
    const bSelected = selectedTags.includes(b.tag);
    
    if (aSelected && !bSelected) return -1;
    if (!aSelected && bSelected) return 1;
    
    // If both have same selection status, sort by the chosen criteria
    if (sortType === 'frequency-desc') return b.count - a.count;
    if (sortType === 'frequency-asc') return a.count - b.count;
    if (sortType === 'alpha-asc') return a.tag.localeCompare(b.tag);
    if (sortType === 'alpha-desc') return b.tag.localeCompare(a.tag);
    return 0;
  });
  
  return sortedTags;
}

---
// In TagChip.astro
interface Props {
  tag: string;
  count?: number;
  selected?: boolean;
  onToggle?: () => void;
}

const { tag, count, selected = false } = Astro.props;
---

<div 
  class={`tool-tag ${selected ? 'selected' : ''}`}
  data-tag={tag}
>
  <p>{tag}</p>
  {count !== undefined && <span class="count">{count}</span>}
</div>

<script>
  // Client-side event handling
  document.querySelectorAll('.tool-tag').forEach(tag => {
    tag.addEventListener('click', () => {
      // Dispatch a custom event that TagColumn will listen for
      const tagValue = tag.dataset.tag;
      const event = new CustomEvent('tagToggled', { 
        detail: { tag: tagValue },
        bubbles: true
      });
      tag.dispatchEvent(event);
    });
  });
</script>

// In TagColumn.astro client script
document.addEventListener('tagToggled', (event) => {
  const { tag } = event.detail;
  toggleTagSelection(tag);
});

// Function to filter content based on selected tags
function filterContent(selectedTags) {
  // Get all tool cards
  const toolCards = document.querySelectorAll('.tool-card');
  
  // If no tags selected, show all cards
  if (selectedTags.length === 0) {
    toolCards.forEach(card => {
      card.style.display = '';
    });
    return;
  }
  
  // Create an array to track cards and their match counts
  const cardMatches = [];
  
  // Filter cards based on selected tags
  toolCards.forEach(card => {
    // Get the card's tags
    const cardTagsStr = card.dataset.tags;
    if (!cardTagsStr) return;
    
    const cardTags = JSON.parse(cardTagsStr);
    
    // Count how many selected tags match this card's tags
    const matchCount = selectedTags.filter(tag => cardTags.includes(tag)).length;
    
    // If the card has at least one matching tag, add it to our array with its match count
    if (matchCount > 0) {
      cardMatches.push({
        card: card,
        matchCount
      });
    } else {
      // Hide cards with no matches
      card.style.display = 'none';
    }
  });
  
  // Sort cards by match count (descending)
  cardMatches.sort((a, b) => b.matchCount - a.matchCount);
  
  // Get the parent container of the cards
  const cardContainer = toolCards[0]?.parentElement;
  if (!cardContainer) return;
  
  // Remove all cards from the DOM
  toolCards.forEach(card => card.remove());
  
  // Add cards back in the new sorted order
  cardMatches.forEach(({card, matchCount}) => {
    // Show the card
    card.style.display = '';
    
    // Add a data attribute showing the match count (useful for debugging)
    card.setAttribute('data-match-count', matchCount.toString());
    
    // Add the card back to the container
    cardContainer.appendChild(card);
  });
}

Dynamic Rendering based on selected "TagChip" as a filter.

// Filter entries by tag if filterTag is provided
const filteredEntries = filterTag
  ? toolEntries.filter(entry => entry.data.tags?.includes(filterTag))
  : toolEntries;

// Get all unique tags
const allTags = Array.from(
  new Set(
    toolEntries.flatMap(entry => entry.data.tags || [])
  )
).sort();

// Map entries to tools format with filePath
const toolsWithFilePath = filteredEntries.map(entry => ({
  ...entry.data,
  id: entry.id,
  filePath: `../content/tooling/${entry.id}`,
}));

<Layout title={title} description={description}>
  <main>
    <div class="toolkit-container">
      <div class="sidebar">
        <TagColumn allRenderedTags={allTags} tools={toolEntries.map(entry => entry.data)} />
      </div>
      <div class="tools-container">
        <CardGrid
          tools={toolsWithFilePath}
          gap={gap}
          minCardWidth={minCardWidth}
        />
      </div>
    </div>
  </main>
</Layout>

Summary

1. Enhanced Tag Selection :
   • Selected tags appear at the top of the tag list for easy visibility
   • Multiple tags can be selected simultaneously
   • Visual highlighting clearly indicates which tags are selected
2. Improved Content Filtering :
   • Uses "OR" logic to show cards matching ANY selected tag
   • Cards are sorted by relevance (number of matching tags)
   • Cards with more matching tags appear at the top
3. State Preservation :
   • The URL reflects the current selection state
   • Users can bookmark or share specific tag combinations
   • Selection state is preserved during page navigation
4. Responsive User Experience :
   • All filtering and sorting happens client-side without page reloads
   • Tag selection provides immediate visual feedback
   • Mobile-friendly design with collapsible tag column