@aiaiai-pt/design-system 0.17.1 → 0.19.0

package/components/FilterBar.svelte

@@ -1,49 +1,90 @@
 <!--
   @component FilterBar
 
-  Horizontal bar of filter chips with active-filter state and clear-all action.
-  Accepts a declarative config of filters or renders children directly.
-  Consumes --filter-chip-* and --filter-bar-* tokens from components.css.
+  Filter controls over a feed. Two modes:
 
-  @example Declarative (common case)
+  • **Facet mode** (set `facets` and/or `searchable`) — a row of labelled
+    dropdowns + an optional search box, the shape a browse/list/map surface
+    uses for its declared facets. Options are supplied by the consumer (it
+    owns the data source); FilterBar is presentational. A misconfigured /
+    undeclared facet is surfaced LOUDLY via `error` — never a silent dead
+    control. Consumes --filter-bar-* tokens.
+
+  • **Chip mode** (default — `filters` and/or `children`) — horizontal bar of
+    filter chips with active-filter state and clear-all. Consumes
+    --filter-chip-* and --filter-bar-* tokens.
+
+  @example Facet mode (browse/list/map)
+  <FilterBar
+    facets={[
+      { key: 'status', label: 'Status', value: '', options: [
+        { value: '', label: 'All' },
+        { value: 'open', label: 'Open' },
+      ]},
+    ]}
+    searchable
+    searchPlaceholder="Search"
+    onfacetchange={(key, value) => refetch(key, value)}
+    onsearch={(term) => refetch('search', term)}
+  />
+
+  @example Chip mode (declarative)
   <FilterBar
     filters={[
       { key: 'status', label: 'Status', type: 'toggle', options: [
         { value: 'active', label: 'Active' },
         { value: 'draft', label: 'Draft' },
-        { value: 'error', label: 'Error' },
       ]},
     ]}
     bind:value={activeFilters}
     onchange={handleFilterChange}
   />
-
-  @example Composable (custom rendering)
-  <FilterBar bind:value={activeFilters} onchange={handleFilterChange}>
-    {#snippet children(toggle, isActive)}
-      <FilterBar.Chip active={isActive('status', 'active')} onclick={() => toggle('status', 'active')}>
-        Active
-      </FilterBar.Chip>
-    {/snippet}
-  </FilterBar>
 -->
 <script module>
   /**
    * @typedef {{ value: string, label: string, icon?: import('svelte').Component }} FilterOption
    * @typedef {{ key: string, label: string, type: 'toggle' | 'select' | 'multi-select', options?: FilterOption[], defaultValue?: any }} FilterDef
+   * @typedef {{ value: string, label: string, disabled?: boolean }} FacetOption
+   * @typedef {{ key: string, label: string, value?: string, options: FacetOption[] }} FacetControl
    */
 </script>
 
 <script>
+  import Select from './Select.svelte';
+  import SearchInput from './SearchInput.svelte';
+  import Alert from './Alert.svelte';
+
   let {
-    /** @type {FilterDef[]} Declarative filter definitions */
+    // ─── Facet mode ───
+    /** @type {FacetControl[]} Labelled dropdown controls (facet mode). */
+    facets = [],
+    /** @type {boolean} Render a search box (facet mode). */
+    searchable = false,
+    /** @type {string} */
+    searchPlaceholder = 'Search',
+    /** @type {string} */
+    searchValue = '',
+    /** @type {boolean} Spinner on the search box / aria-busy on the bar. */
+    busy = false,
+    /** @type {string | undefined} Loud-fail message for misconfigured facets. */
+    error = undefined,
+    /** @type {((key: string, value: string) => void) | undefined} */
+    onfacetchange = undefined,
+    /** @type {((value: string) => void) | undefined} */
+    onsearch = undefined,
+    /** @type {(() => void) | undefined} Fires when the search box is cleared. */
+    onsearchclear = undefined,
+
+    // ─── Chip mode ───
+    /** @type {FilterDef[]} Declarative chip definitions */
     filters = [],
-    /** @type {Record<string, any>} Active filter values (bindable) */
+    /** @type {Record<string, any>} Active chip values (bindable) */
     value = $bindable({}),
-    /** @type {((value: Record<string, any>) => void) | undefined} Fires when any filter changes */
+    /** @type {((value: Record<string, any>) => void) | undefined} Fires when any chip changes */
     onchange = undefined,
     /** @type {(() => void) | undefined} Fires when "Clear all" is clicked */
     onclear = undefined,
+
     /** @type {string} */
     class: className = '',
     /** @type {import('svelte').Snippet | undefined} */
@@ -51,6 +92,10 @@
     ...rest
   } = $props();
 
+  // Facet mode wins whenever facet controls or search are configured; chip
+  // mode is the default (back-compat with the original FilterBar contract).
+  const isFacetMode = $derived(facets.length > 0 || searchable);
+
   const activeCount = $derived(
     Object.values(value).filter(v => {
       if (Array.isArray(v)) return v.length > 0;
@@ -61,7 +106,7 @@
   const showClearAll = $derived(activeCount >= 2);
 
   /**
-   * Toggle a filter value
+   * Toggle a filter value (chip mode)
    * @param {string} key
    * @param {string} optionValue
    */
@@ -90,7 +135,7 @@
   }
 
   /**
-   * Check if a filter option is active
+   * Check if a filter option is active (chip mode)
    * @param {string} key
    * @param {string} optionValue
    * @returns {boolean}
@@ -106,48 +151,82 @@
     onchange?.({});
     onclear?.();
   }
-
 </script>
 
-<div
-  class="filter-bar {className}"
-  role="group"
-  aria-label="Filters"
-  {...rest}
->
-  {#if children}
-    {@render children(toggle, isActive)}
-  {:else}
-    <div class="filter-bar-chips">
-      {#each filters as filter}
-        {#if filter.options}
-          {#each filter.options as option}
-            {@const active = isActive(filter.key, option.value)}
-            <button
-              class="filter-chip"
-              class:filter-chip-active={active}
-              onclick={() => toggle(filter.key, option.value)}
-              aria-pressed={active}
-              type="button"
-            >
-              {option.label}
-            </button>
-          {/each}
-        {/if}
-      {/each}
-    </div>
-
-    {#if showClearAll}
-      <button
-        class="filter-bar-clear"
-        onclick={clearAll}
-        type="button"
-      >
-        Clear all
-      </button>
-    {/if}
+{#if isFacetMode}
+  <!-- Loud-fail (never a silent dead control): a configured facet the surface
+       does not declare can't filter — surface it as an operator fix. -->
+  {#if error}
+    <Alert variant="error" data-testid="filter-bar-error" class="filter-bar-alert">
+      {error}
+    </Alert>
   {/if}
-</div>
+  <div
+    class="filter-bar filter-bar-facets {className}"
+    role="group"
+    aria-label="Filters"
+    aria-busy={busy}
+    {...rest}
+  >
+    {#if searchable}
+      <SearchInput
+        placeholder={searchPlaceholder}
+        value={searchValue}
+        loading={busy}
+        onsearch={(v) => onsearch?.((v ?? '').trim())}
+        onclear={() => onsearchclear?.()}
+      />
+    {/if}
+    {#each facets as facet (facet.key)}
+      <Select
+        label={facet.label}
+        options={facet.options}
+        value={facet.value ?? ''}
+        onchange={(v) => onfacetchange?.(facet.key, v)}
+      />
+    {/each}
+  </div>
+{:else}
+  <div
+    class="filter-bar {className}"
+    role="group"
+    aria-label="Filters"
+    {...rest}
+  >
+    {#if children}
+      {@render children(toggle, isActive)}
+    {:else}
+      <div class="filter-bar-chips">
+        {#each filters as filter}
+          {#if filter.options}
+            {#each filter.options as option}
+              {@const active = isActive(filter.key, option.value)}
+              <button
+                class="filter-chip"
+                class:filter-chip-active={active}
+                onclick={() => toggle(filter.key, option.value)}
+                aria-pressed={active}
+                type="button"
+              >
+                {option.label}
+              </button>
+            {/each}
+          {/if}
+        {/each}
+      </div>
+
+      {#if showClearAll}
+        <button
+          class="filter-bar-clear"
+          onclick={clearAll}
+          type="button"
+        >
+          Clear all
+        </button>
+      {/if}
+    {/if}
+  </div>
+{/if}
 
 <style>
   .filter-bar {
@@ -157,6 +236,16 @@
     flex-wrap: wrap;
   }
 
+  /* Facet mode: labelled dropdowns + search align to their baselines. */
+  .filter-bar-facets {
+    align-items: flex-end;
+    gap: var(--space-sm);
+  }
+
+  .filter-bar-alert {
+    margin-bottom: var(--space-sm);
+  }
+
   .filter-bar-chips {
     display: flex;
     align-items: center;

package/components/FilterBar.svelte.d.ts

@@ -11,6 +11,17 @@ export type FilterDef = {
     options?: FilterOption[];
     defaultValue?: any;
 };
+export type FacetOption = {
+    value: string;
+    label: string;
+    disabled?: boolean;
+};
+export type FacetControl = {
+    key: string;
+    label: string;
+    value?: string;
+    options: FacetOption[];
+};
 type FilterBar = {
     $on?(type: string, callback: (e: any) => void): () => void;
     $set?(props: Partial<$$ComponentProps>): void;
@@ -18,33 +29,55 @@ type FilterBar = {
 /**
  * FilterBar
  *
- * Horizontal bar of filter chips with active-filter state and clear-all action.
- * Accepts a declarative config of filters or renders children directly.
- * Consumes --filter-chip-* and --filter-bar-* tokens from components.css.
+ * Filter controls over a feed. Two modes:
+ *
+ * • **Facet mode** (set `facets` and/or `searchable`) — a row of labelled
+ *   dropdowns + an optional search box, the shape a browse/list/map surface
+ *   uses for its declared facets. Options are supplied by the consumer (it
+ *   owns the data source); FilterBar is presentational. A misconfigured /
+ *   undeclared facet is surfaced LOUDLY via `error` — never a silent dead
+ *   control. Consumes --filter-bar-* tokens.
  *
- * @example Declarative (common case)
+ * • **Chip mode** (default — `filters` and/or `children`) — horizontal bar of
+ *   filter chips with active-filter state and clear-all. Consumes
+ *   --filter-chip-* and --filter-bar-* tokens.
+ *
+ * @example Facet mode (browse/list/map)
+ * <FilterBar
+ *   facets={[
+ *     { key: 'status', label: 'Status', value: '', options: [
+ *       { value: '', label: 'All' },
+ *       { value: 'open', label: 'Open' },
+ *     ]},
+ *   ]}
+ *   searchable
+ *   searchPlaceholder="Search"
+ *   onfacetchange={(key, value) => refetch(key, value)}
+ *   onsearch={(term) => refetch('search', term)}
+ * />
+ *
+ * @example Chip mode (declarative)
  * <FilterBar
  *   filters={[
  *     { key: 'status', label: 'Status', type: 'toggle', options: [
  *       { value: 'active', label: 'Active' },
  *       { value: 'draft', label: 'Draft' },
- *       { value: 'error', label: 'Error' },
  *     ]},
  *   ]}
  *   bind:value={activeFilters}
  *   onchange={handleFilterChange}
  * />
- *
- * @example Composable (custom rendering)
- * <FilterBar bind:value={activeFilters} onchange={handleFilterChange}>
- *   {#snippet children(toggle, isActive)}
- *     <FilterBar.Chip active={isActive('status', 'active')} onclick={() => toggle('status', 'active')}>
- *       Active
- *     </FilterBar.Chip>
- *   {/snippet}
- * </FilterBar>
  */
 declare const FilterBar: import("svelte").Component<{
+    facets?: any[];
+    searchable?: boolean;
+    searchPlaceholder?: string;
+    searchValue?: string;
+    busy?: boolean;
+    error?: any;
+    onfacetchange?: any;
+    onsearch?: any;
+    onsearchclear?: any;
     filters?: any[];
     value?: Record<string, any>;
     onchange?: any;
@@ -53,6 +86,15 @@ declare const FilterBar: import("svelte").Component<{
     children?: any;
 } & Record<string, any>, {}, "value">;
 type $$ComponentProps = {
+    facets?: any[];
+    searchable?: boolean;
+    searchPlaceholder?: string;
+    searchValue?: string;
+    busy?: boolean;
+    error?: any;
+    onfacetchange?: any;
+    onsearch?: any;
+    onsearchclear?: any;
     filters?: any[];
     value?: Record<string, any>;
     onchange?: any;

package/components/LinkHighlightToggle.svelte

@@ -0,0 +1,37 @@
+<!--
+  @component LinkHighlightToggle
+
+  Citizen "underline links" preference (#244 C7 accessibility pack). A single
+  on/off switch: "on" forces a visible underline on every in-content link, so
+  links are distinguishable by more than colour (WCAG 1.4.1 Use of Colour /
+  Selo item 6 — hyperlinks should not rely on colour alone).
+
+  Presentational, mirrors the scheme/motion controls: it reports the new value
+  via `onchange`; the consumer persists it (cookie) and applies the
+  `:root[data-link-highlight="on"]` layer (tokens/semantic.css) server-side, so
+  SSR paints it with no flash. The label is a prop for i18n (default English).
+
+  @example
+  <LinkHighlightToggle on={prefs.linkHighlight} onchange={(v) => setLinkHighlight(v)} />
+-->
+<script>
+  import Toggle from "./Toggle.svelte";
+
+  let {
+    /** @type {boolean} Whether link-underlining is currently on. */
+    on = false,
+    /** @type {((on: boolean) => void) | undefined} */
+    onchange = undefined,
+    /** @type {string} Accessible label (i18n). */
+    label = "Underline links",
+    ...rest
+  } = $props();
+</script>
+
+<Toggle
+  checked={on}
+  {label}
+  {onchange}
+  data-testid="link-highlight-toggle"
+  {...rest}
+/>

package/components/LinkHighlightToggle.svelte.d.ts

@@ -0,0 +1,31 @@
+export default LinkHighlightToggle;
+type LinkHighlightToggle = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * LinkHighlightToggle
+ *
+ * Citizen "underline links" preference (#244 C7 accessibility pack). A single
+ * on/off switch: "on" forces a visible underline on every in-content link, so
+ * links are distinguishable by more than colour (WCAG 1.4.1 Use of Colour /
+ * Selo item 6 — hyperlinks should not rely on colour alone).
+ *
+ * Presentational, mirrors the scheme/motion controls: it reports the new value
+ * via `onchange`; the consumer persists it (cookie) and applies the
+ * `:root[data-link-highlight="on"]` layer (tokens/semantic.css) server-side, so
+ * SSR paints it with no flash. The label is a prop for i18n (default English).
+ *
+ * @example
+ * <LinkHighlightToggle on={prefs.linkHighlight} onchange={(v) => setLinkHighlight(v)} />
+ */
+declare const LinkHighlightToggle: import("svelte").Component<{
+    on?: boolean;
+    onchange?: any;
+    label?: string;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    on?: boolean;
+    onchange?: any;
+    label?: string;
+} & Record<string, any>;

package/components/MapCluster.svelte

@@ -39,6 +39,14 @@
     layers = [],
     /** @type {((marker: { id: string, lon: number, lat: number, label?: string }) => void) | undefined} */
     onclick = undefined,
+    /** @type {import('svelte').Snippet<[any, () => void]> | undefined} —
+     *  click-popup content. When provided, clicking a single marker (or a
+     *  stacked pile) opens an anchored OL Overlay rendering this snippet with
+     *  `(markerData, close)` — the "ficha resumo" intermediate step before the
+     *  consumer's detail link — INSTEAD of firing `onclick`. Omit for the
+     *  legacy click-to-navigate behaviour. Compose with the DS `MapPopup` for
+     *  the card chrome (the original `let:popup` contract, now a snippet). */
+    popup = undefined,
     /** @type {string} */
     height = '100%',
     /** @type {string} */
@@ -48,6 +56,18 @@
 
   /** @type {HTMLElement | undefined} */
   let container = $state();
+  /** @type {HTMLElement | undefined} — the popup overlay's element (Svelte
+   *  renders the snippet into it; OL positions it). */
+  let popupEl = $state();
+  /** @type {any} — the marker data of the open popup, or null. */
+  let selected = $state(null);
+  /** @type {any} — popup OL Overlay ref, set at mount. */
+  let _popupOverlay;
+
+  function closePopup() {
+    selected = null;
+    _popupOverlay?.setPosition(undefined);
+  }
 
   // Hoisted references for reactive effects
   /** @type {import('ol/Map.js').default | undefined} */
@@ -211,6 +231,22 @@
         stopEvent: false,
       });
 
+      // Click-popup overlay (the "ficha resumo"): anchored above the marker.
+      // `stopEvent: true` (OL default) keeps it in the interactive overlay
+      // pane so the link/close button inside the popup snippet are clickable.
+      // Its element is the Svelte-rendered `popupEl`; Svelte owns the content,
+      // OL owns the position. Only created when a `popup` snippet is supplied.
+      const overlays = [tooltipOverlay];
+      if (popup && popupEl) {
+        _popupOverlay = new Overlay({
+          element: popupEl,
+          positioning: 'bottom-center',
+          offset: [0, -18],
+          stopEvent: true,
+        });
+        overlays.push(_popupOverlay);
+      }
+
       const viewCenter = center
         ? fromLonLat(center)
         : markers.length > 0
@@ -225,7 +261,7 @@
         // The `layers` overlays are NOT built here — the reactive owner
         // effect above inserts them between the tiles and the cluster layer.
         layers: [tileLayer, clusterLayer],
-        overlays: [tooltipOverlay],
+        overlays,
         view: new View({
           center: viewCenter,
           zoom,
@@ -267,16 +303,32 @@
         }
       });
 
+      // `popup` opens the anchored ficha-resumo overlay; otherwise `onclick`
+      // navigates (legacy). A single marker (or a stacked pile that can't split
+      // by zoom) "selects"; a spread cluster zooms in.
+      const selectMarker = (data, coords) => {
+        if (!data) return;
+        if (popup) {
+          selected = data;
+          if (coords) _popupOverlay?.setPosition(coords);
+        } else {
+          onclick?.(data);
+        }
+      };
+
       // Click handler
-      if (onclick) {
+      if (onclick || popup) {
         map.on('click', (evt) => {
           const feature = map?.forEachFeatureAtPixel(evt.pixel, f => f);
-          if (!feature) return;
+          // Clicking empty map dismisses an open popup (no-op without one).
+          if (!feature) { closePopup(); return; }
 
           const clustered = feature.get('features');
           if (clustered?.length === 1) {
-            const data = clustered[0].get('markerData');
-            if (data) onclick(data);
+            selectMarker(
+              clustered[0].get('markerData'),
+              (/** @type {any} */ (feature.getGeometry()))?.getCoordinates(),
+            );
           } else if (clustered?.length > 1) {
             // A cluster of (near-)IDENTICAL coordinates can never split by
             // zooming (stacked reports at one point are common in civic
@@ -286,8 +338,10 @@
             const lats = coords.map((c) => c[1]);
             const spread = Math.max(...lons) - Math.min(...lons) + (Math.max(...lats) - Math.min(...lats));
             if (spread < 1) { // metres in web-mercator units — a stacked pile
-              const data = clustered[0].get('markerData');
-              if (data) onclick(data);
+              selectMarker(
+                clustered[0].get('markerData'),
+                (/** @type {any} */ (feature.getGeometry()))?.getCoordinates(),
+              );
               return;
             }
             const view = map?.getView();
@@ -307,9 +361,16 @@
       });
     } catch (err) { renderMapError(container, 'MapCluster', /** @type {Error} */ (err)); } })();
 
+    // Escape closes an open popup (keyboard dismissal).
+    const onKeydown = (/** @type {KeyboardEvent} */ e) => {
+      if (e.key === 'Escape') closePopup();
+    };
+    if (typeof window !== 'undefined') window.addEventListener('keydown', onKeydown);
+
     return () => {
       disposed = true;
       disposeTheme?.();
+      if (typeof window !== 'undefined') window.removeEventListener('keydown', onKeydown);
       map?.setTarget(undefined);
     };
   });
@@ -324,6 +385,15 @@
   {...rest}
 ></div>
 
+<!-- Popup overlay element. Always in the DOM (OL moves it into the overlay
+     pane + positions it); Svelte owns its content. The snippet receives the
+     selected marker + a `close` callback (the original `let:popup` contract). -->
+{#if popup}
+  <div bind:this={popupEl} class="map-cluster-popup">
+    {#if selected}{@render popup(selected, closePopup)}{/if}
+  </div>
+{/if}
+
 <style>
   .map-cluster {
     width: 100%;
@@ -336,4 +406,11 @@
   .map-cluster :global(.ol-viewport) {
     border-radius: inherit;
   }
+
+  /* Overlay element wrapper — OL owns its position (inline transform); this
+     just lifts it above the map controls. The card chrome is the consumer's
+     MapPopup. */
+  .map-cluster-popup {
+    z-index: 2;
+  }
 </style>

package/components/MapCluster.svelte.d.ts

@@ -25,6 +25,7 @@ declare const MapCluster: import("svelte").Component<{
     tileSource?: Record<string, any>;
     layers?: any[];
     onclick?: any;
+    popup?: any;
     height?: string;
     class?: string;
 } & Record<string, any>, {}, "">;
@@ -36,6 +37,7 @@ type $$ComponentProps = {
     tileSource?: Record<string, any>;
     layers?: any[];
     onclick?: any;
+    popup?: any;
     height?: string;
     class?: string;
 } & Record<string, any>;