@communitiesuk/svelte-component-library 0.1.17 → 0.2.0-alpha.2

package/dist/components/ui/PostcodeOrAreaSearch.svelte

@@ -0,0 +1,200 @@
+<script lang="ts">
+  import SearchAutocomplete from "./SearchAutocomplete.svelte";
+  import { capitalise } from "./../../utils/text-string-conversion/textStringConversion";
+  import {
+    geoNames,
+    geoCodesLookup,
+    essGeocodes,
+  } from "./../../utils/area-search/geoConfig";
+  import defaultPlacesData from "./../../data/places.json";
+
+  // --- Define Types ---
+  type SuggestionObject = { label: string; value: any; [key: string]: any };
+  type Suggestion = string | SuggestionObject;
+
+  type Place = SuggestionObject & {
+    areacd: string;
+    areanm: string;
+    parentcd?: string;
+    group?: string;
+  };
+
+  type Props = {
+    // Data source configuration
+    customPlacesData?: any[]; // Custom places data (JSON format: [{areacd, areanm, parentcd}])
+    essOnly?: boolean; // Whether to filter to essential geocodes only
+
+    // Custom lookup functions/data (for flexibility)
+    customTypeLookup?: Record<
+      string,
+      { label: string; plural: string; childGroup?: boolean }
+    >;
+    customEssGeocodes?: string[];
+    customGetTypeLabel?: (type: string) => string;
+
+    // Postcode API configuration
+    postcodeApiUrl?: string;
+    postcodeApiKey?: string; // Key in response containing suggestions
+    postcodeApiProperty?: string; // Property to extract from API objects
+    postcodeApiPathBased?: boolean; // Whether the API uses path-based URLs
+
+    // Source selection logic
+    customSourceSelector?: (
+      query: string,
+      options: Suggestion[],
+    ) => "api" | "options";
+
+    // Pass-through props to SearchAutocomplete
+    selectedValue?: any;
+    label_text?: string;
+    button_text?: string;
+    name?: string;
+    placeholder?: string;
+    hint?: string;
+    size?: "large" | "";
+    on_govuk_blue?: boolean;
+    homepage?: boolean;
+    minLength?: number;
+    required?: boolean;
+    [key: string]: any; // Allow other props
+  };
+
+  let {
+    customPlacesData = undefined,
+    essOnly = false,
+    customTypeLookup = undefined,
+    customEssGeocodes = undefined,
+    customGetTypeLabel = undefined,
+    postcodeApiUrl = "https://api.postcodes.io/postcodes",
+    postcodeApiKey = "result",
+    postcodeApiProperty = "postcode",
+    postcodeApiPathBased = false,
+    customSourceSelector = undefined,
+    selectedValue = $bindable(),
+    label_text = "Search for a postcode or area",
+    button_text = "Search",
+    name = "location",
+    placeholder = "e.g. SW1A 1AA or Westminster",
+    hint = "Enter a UK postcode or area name",
+    size = "",
+    on_govuk_blue = false,
+    homepage = false,
+    minLength = 2,
+    required = false,
+    ...restProps
+  }: Props = $props();
+
+  // --- Use custom lookups or defaults ---
+  const typeLookup =
+    customTypeLookup && Object.keys(customTypeLookup).length > 0
+      ? customTypeLookup
+      : geoNames;
+  const essGeocodesArray =
+    customEssGeocodes && customEssGeocodes.length > 0
+      ? customEssGeocodes
+      : essGeocodes;
+
+  // --- Helper Functions ---
+  const getTypeLabel = (type: string) => {
+    // If custom function is provided and returns a non-null value, use it
+    if (customGetTypeLabel) {
+      const customLabel = customGetTypeLabel(type);
+      if (customLabel !== null && customLabel !== undefined) {
+        return customLabel;
+      }
+    }
+    // Otherwise use lookup table (custom or default)
+    return typeLookup[type]
+      ? typeLookup[type].label
+      : geoCodesLookup[type]?.label || type;
+  };
+
+  // Default source selector: use API for postcode-like inputs, options for area names
+  const defaultSourceSelector = (query: string, options: Suggestion[]) => {
+    // If input has 3+ chars and contains a digit, likely a postcode
+    return query.length >= 3 && /\d/.test(query) ? "api" : "options";
+  };
+
+  const sourceSelector = (query: string, options: Suggestion[]) => {
+    // If custom function is provided and returns a non-null value, use it
+    if (customSourceSelector) {
+      const customResult = customSourceSelector(query, options);
+      if (customResult !== null && customResult !== undefined) {
+        return customResult;
+      }
+    }
+    // Otherwise use default selector
+    return defaultSourceSelector(query, options);
+  };
+
+  // --- Process Places Data ---
+  const places = $derived.by(() => {
+    // Use custom data if provided and not empty, otherwise use default
+    let placesData =
+      customPlacesData && customPlacesData.length > 0
+        ? customPlacesData
+        : defaultPlacesData;
+
+    // Filter to essential geocodes if requested
+    if (essOnly) {
+      placesData = placesData.filter((p: any) =>
+        essGeocodesArray.includes(p.areacd.slice(0, 3)),
+      );
+    }
+
+    // Sort by area name
+    const sortedData = [...placesData].sort((a: any, b: any) =>
+      a.areanm.localeCompare(b.areanm),
+    );
+
+    // Create lookup for parent relationships
+    const lookup: Record<string, any> = {};
+    for (const p of sortedData) lookup[p.areacd] = p;
+
+    // Add group information and format for autocomplete
+    const processedPlaces: Place[] = sortedData.map((p: any) => {
+      const type = p.areacd.slice(0, 3);
+      const group =
+        type === "K02"
+          ? ""
+          : p.parentcd && lookup[p.parentcd]
+            ? `${capitalise(getTypeLabel(type))} in ${lookup[p.parentcd].areanm}`
+            : capitalise(getTypeLabel(type));
+
+      return {
+        areacd: p.areacd,
+        areanm: p.areanm,
+        parentcd: p.parentcd,
+        group,
+        label: p.areanm,
+        value: p.areacd,
+      };
+    });
+
+    return processedPlaces;
+  });
+
+  // --- Autocomplete Configuration ---
+  const autocompleteProps = $derived({
+    options: places,
+    source_url: postcodeApiUrl,
+    source_key: postcodeApiKey,
+    source_property: postcodeApiProperty,
+    pathBasedApi: postcodeApiPathBased,
+    groupKey: "group",
+    sourceSelector,
+    label_text,
+    button_text,
+    name,
+    placeholder,
+    hint,
+    size,
+    on_govuk_blue,
+    homepage,
+    minLength,
+    required,
+    ...restProps,
+  });
+</script>
+
+<SearchAutocomplete {...autocompleteProps} bind:selectedValue />

package/dist/components/ui/PostcodeOrAreaSearch.svelte.d.ts

@@ -0,0 +1,37 @@
+type SuggestionObject = {
+    label: string;
+    value: any;
+    [key: string]: any;
+};
+type Suggestion = string | SuggestionObject;
+type Props = {
+    customPlacesData?: any[];
+    essOnly?: boolean;
+    customTypeLookup?: Record<string, {
+        label: string;
+        plural: string;
+        childGroup?: boolean;
+    }>;
+    customEssGeocodes?: string[];
+    customGetTypeLabel?: (type: string) => string;
+    postcodeApiUrl?: string;
+    postcodeApiKey?: string;
+    postcodeApiProperty?: string;
+    postcodeApiPathBased?: boolean;
+    customSourceSelector?: (query: string, options: Suggestion[]) => "api" | "options";
+    selectedValue?: any;
+    label_text?: string;
+    button_text?: string;
+    name?: string;
+    placeholder?: string;
+    hint?: string;
+    size?: "large" | "";
+    on_govuk_blue?: boolean;
+    homepage?: boolean;
+    minLength?: number;
+    required?: boolean;
+    [key: string]: any;
+};
+declare const PostcodeOrAreaSearch: import("svelte").Component<Props, {}, "selectedValue">;
+type PostcodeOrAreaSearch = ReturnType<typeof PostcodeOrAreaSearch>;
+export default PostcodeOrAreaSearch;

package/dist/components/ui/Search.svelte

@@ -2,8 +2,8 @@
   import { clsx } from "clsx";
   import { browser } from "$app/environment";
   import { onMount } from "svelte";
-  import IconSearch from "../../icons/IconSearch.svelte";
-  import closeIconUrl from "../../assets/govuk_publishing_components/images/icon-close.svg?url";
+  import IconSearch from "./../../icons/IconSearch.svelte";
+  import closeIconUrl from "./../../assets/govuk_publishing_components/images/icon-close.svg?url";
 
   // SSR-safe HTML sanitizer: no-op on server
   let sanitize = $state<(html: string) => string>((html) => html);

package/dist/components/ui/SearchAutocomplete.svelte

@@ -4,15 +4,14 @@
   import Search from "./Search.svelte"; // Base component
   import "accessible-autocomplete/dist/accessible-autocomplete.min.css";
   import { browser } from "$app/environment";
-  import suggestionIconUrl from "../../assets/govuk_publishing_components/images/icon-autocomplete-search-suggestion.svg?url";
-  import closeIconUrl from "../../assets/govuk_publishing_components/images/icon-close.svg?url"; // Import for the cancel button
-  
+  import suggestionIconUrl from "./../../assets/govuk_publishing_components/images/icon-autocomplete-search-suggestion.svg?url";
+  import closeIconUrl from "./../../assets/govuk_publishing_components/images/icon-close.svg?url"; // Import for the cancel button
 
   // SSR-safe HTML sanitizer: no-op on server
   let sanitize: (html: string) => string = (html) => html;
 
   // --- Define Props ---
-  type SuggestionObject = { label: string; value: any };
+  type SuggestionObject = { label: string; value: any; [key: string]: any }; // Allow additional properties for grouping
   type Suggestion = string | SuggestionObject;
   type Props = {
     // User can supply either an options array or an API source
@@ -20,6 +19,12 @@
     source_url?: string; // Optional: URL for autocomplete suggestions
     source_key?: string; // Optional: Key in the JSON response containing suggestions array
     source_property?: string; // Property to extract from API objects
+    pathBasedApi?: boolean; // Whether to use path-based URLs (RESTful) instead of query parameters
+    groupKey?: string; // Optional: Key to group suggestions by (e.g., "region", "category")
+    sourceSelector?: (
+      query: string,
+      options: Suggestion[],
+    ) => "api" | "options"; // Function to determine which source to use
     outerClasses?: string; // Optional classes for the outer wrapper
     outerDataAttributes?: Record<string, string>; // Optional data attributes for the outer wrapper
     // Add other expected props passed down (e.g., size, on_govuk_blue, id, name etc.)
@@ -52,9 +57,12 @@
     source_url = undefined,
     source_key = undefined,
     source_property = undefined,
-    size = "", // Default size from Search
+    pathBasedApi = false,
+    groupKey = undefined,
+    sourceSelector = undefined,
+    size = "",
     on_govuk_blue = false,
-    homepage = false, // Added homepage prop handling
+    homepage = false,
     outerClasses = "",
     outerDataAttributes = {},
     id, // Pass down id
@@ -81,6 +89,12 @@
   let containerElement: HTMLDivElement; // bind:this target for the outer div
   let autocompleteInstance: { inputElement?: HTMLInputElement } | null = null; // To store instance if needed
 
+  // Track which source is currently being used for dynamic data attributes
+  let currentSource = $state<"api" | "options" | "auto">("auto");
+  let currentSourceUrl = $state<string | undefined>(undefined);
+  let currentSourceKey = $state<string | undefined>(undefined);
+  let currentSourceProperty = $state<string | undefined>(undefined);
+
   // --- Derived Values ---
   const wrapperClasses = $derived(
     clsx(
@@ -148,6 +162,12 @@
         query: string,
         populateResults: (results: string[]) => void,
       ) => {
+        // Update current source tracking
+        currentSource = "api";
+        currentSourceUrl = source_url;
+        currentSourceKey = source_key;
+        currentSourceProperty = source_property;
+
         if (!source_url || !source_key) {
           console.error(
             "SearchAutocomplete: source_url and source_key are required for API mode.",
@@ -155,8 +175,21 @@
           populateResults([]);
           return;
         }
-        const url = new URL(source_url);
-        url.searchParams.set("q", query);
+
+        // Construct URL based on pathBasedApi setting
+        let url: URL;
+        if (pathBasedApi) {
+          // For RESTful APIs like Zippopotam.us: append query to path
+          const baseUrl = source_url.endsWith("/")
+            ? source_url.slice(0, -1)
+            : source_url;
+          url = new URL(`${baseUrl}/${encodeURIComponent(query)}`);
+        } else {
+          // For query parameter APIs: add ?q=query
+          url = new URL(source_url);
+          url.searchParams.set("q", query);
+        }
+
         fetch(url, { headers: { Accept: "application/json" } })
           .then((response) => {
             if (!response.ok)
@@ -209,6 +242,12 @@
         query: string,
         populateResults: (results: Suggestion[]) => void,
       ) => {
+        // Update current source tracking
+        currentSource = "options";
+        currentSourceUrl = undefined;
+        currentSourceKey = undefined;
+        currentSourceProperty = undefined;
+
         if (!options) {
           populateResults([]);
           return;
@@ -227,6 +266,43 @@
         ? getResultsFromOptions
         : getResultsFromApi;
 
+      // Initialise current source tracking based on initial configuration
+      if (sourceSelector) {
+        currentSource = "auto"; // Will be determined dynamically
+        currentSourceUrl = source_url;
+        currentSourceKey = source_key;
+        currentSourceProperty = source_property;
+      } else if (useOptions) {
+        currentSource = "options";
+        currentSourceUrl = undefined;
+        currentSourceKey = undefined;
+        currentSourceProperty = undefined;
+      } else {
+        currentSource = "api";
+        currentSourceUrl = source_url;
+        currentSourceKey = source_key;
+        currentSourceProperty = source_property;
+      }
+
+      // If sourceSelector is provided, create a dynamic source function
+      const dynamicSourceFunction = sourceSelector
+        ? (query: string, populateResults: (results: Suggestion[]) => void) => {
+            const selectedSource = sourceSelector(query, options || []);
+            // Handle invalid returns by falling back to default logic
+            if (selectedSource === "api") {
+              getResultsFromApi(query, populateResults);
+            } else if (selectedSource === "options") {
+              getResultsFromOptions(query, populateResults);
+            } else {
+              // Fall back to default logic if invalid return value
+              sourceFunction(query, populateResults);
+            }
+          }
+        : null;
+
+      // Use dynamic source if available, otherwise fall back to original logic
+      const finalSourceFunction = dynamicSourceFunction || sourceFunction;
+
       // Define suggestion template function (sanitize and highlight)
       const suggestionTemplate = (result: Suggestion): string => {
         const displayLabel = typeof result === "string" ? result : result.label;
@@ -256,11 +332,17 @@
           html = `${before}<mark class="gem-c-search-with-autocomplete__suggestion-highlight">${match}</mark>${after}`;
         }
 
-        // Match the GOV.UK structure
+        // Get group text if groupKey is provided and result is an object
+        const groupText =
+          groupKey && typeof result === "object" && result[groupKey]
+            ? ` <span class="gem-c-search-with-autocomplete__suggestion-group">${sanitize(String(result[groupKey]))}</span>`
+            : "";
+
+        // Match the GOV.UK structure with integrated group text
         return `
           <div class="gem-c-search-with-autocomplete__option-wrapper">
             <span class="gem-c-search-with-autocomplete__suggestion-icon"></span>
-            <span class="gem-c-search-with-autocomplete__suggestion-text">${html}</span>
+            <span class="gem-c-search-with-autocomplete__suggestion-text">${html}${groupText}</span>
           </div>
         `;
       };
@@ -313,7 +395,7 @@
         id: searchInput.id, // Use the ID from the *rendered* Search input
         name: searchInput.name, // Use the name from the *rendered* Search input
         inputClasses: searchInput.classList, // Pass original classes directly
-        source: sourceFunction,
+        source: finalSourceFunction,
         minLength: minLength,
         confirmOnBlur: confirmOnBlur,
         showNoOptionsFound: showNoOptionsFound,
@@ -428,9 +510,11 @@
   bind:this={containerElement}
   class={wrapperClasses}
   data-module="gem-search-with-autocomplete"
-  data-source-url={source_url}
-  data-source-key={source_key}
-  data-source-property={source_property}
+  data-source-url={currentSourceUrl}
+  data-source-key={currentSourceKey}
+  data-source-property={currentSourceProperty}
+  data-group-key={groupKey}
+  data-current-source={currentSource}
   {...outerDataAttributes}
   style={`--suggestion-icon: url("${suggestionIconUrl}"); --cancel-icon: url("${closeIconUrl}")`}
 >
@@ -567,6 +651,12 @@
       background: none;
     }
 
+    .gem-c-search-with-autocomplete__suggestion-group {
+      opacity: 0.8;
+      font-size: smaller;
+      font-weight: normal;
+    }
+
     .gem-c-search-with-autocomplete.gem-c-search-with-autocomplete--large
       .gem-c-search-with-autocomplete__menu {
       margin-right: -50px;

package/dist/components/ui/SearchAutocomplete.svelte.d.ts

@@ -2,6 +2,7 @@ import "accessible-autocomplete/dist/accessible-autocomplete.min.css";
 type SuggestionObject = {
     label: string;
     value: any;
+    [key: string]: any;
 };
 type Suggestion = string | SuggestionObject;
 type Props = {
@@ -9,6 +10,9 @@ type Props = {
     source_url?: string;
     source_key?: string;
     source_property?: string;
+    pathBasedApi?: boolean;
+    groupKey?: string;
+    sourceSelector?: (query: string, options: Suggestion[]) => "api" | "options";
     outerClasses?: string;
     outerDataAttributes?: Record<string, string>;
     size?: "large" | "";