@aiaiai-pt/design-system 0.18.0 → 0.20.0

package/components/ActionPanel.svelte

@@ -0,0 +1,111 @@
+<!--
+  @component ActionPanel
+
+  A config-driven vertical stack of detail-page call-to-action buttons —
+  vote / support / comment / acknowledge / reserve … Vertical-agnostic: every
+  CTA is data ({ label, href, icon?, variant?, disabled?, reason? }).
+
+  Presentational only — the consumer decides each CTA's enabled/disabled state
+  and the reason it's closed (grant or row-state). An ENABLED CTA renders as a
+  link (it navigates to the action form); a CLOSED CTA renders as a disabled
+  control with its reason as VISIBLE, programmatically-associated helper text
+  (`aria-describedby`) — never a dead button. Decorative icons are aria-hidden.
+
+  Consumes semantic tokens (`--space-*`, `--color-*`) so dark / high-contrast
+  schemes (#244) ride through without per-component token entries.
+
+  @example
+  <ActionPanel actions={[
+    { key: 'vote', label: 'Vote for this proposal', href: '/submit/vote', icon: ThumbsUpIcon },
+    { key: 'support', label: 'Support', disabled: true, reason: 'Voting has closed.' },
+  ]} />
+-->
+<script module>
+  let _actionPanelUid = 0;
+  /**
+   * @typedef {{
+   *   key?: string,
+   *   label: string,
+   *   href?: string,
+   *   icon?: import('svelte').Component,
+   *   variant?: 'primary' | 'secondary' | 'ghost' | 'destructive',
+   *   disabled?: boolean,
+   *   reason?: string,
+   * }} ActionPanelItem
+   */
+</script>
+
+<script>
+  import Button from './Button.svelte';
+
+  let {
+    /** @type {ActionPanelItem[]} The CTAs to render, in order. */
+    actions = [],
+    /** @type {string} */
+    class: className = '',
+    ...rest
+  } = $props();
+
+  const uid = `action-panel-${_actionPanelUid++}`;
+</script>
+
+{#if actions.length > 0}
+  <div class="action-panel {className}" {...rest}>
+    {#each actions as action, i (action.key ?? i)}
+      {@const Icon = action.icon}
+      {@const isClosed = action.disabled === true || !action.href}
+      {@const reasonId =
+        action.disabled === true && action.reason ? `${uid}-reason-${i}` : undefined}
+      <div class="action-panel-item">
+        <Button
+          variant={action.variant ?? 'primary'}
+          href={isClosed ? undefined : action.href}
+          disabled={isClosed}
+          class="action-panel-btn"
+          aria-describedby={reasonId}
+        >
+          {#if Icon}<span class="action-panel-icon" aria-hidden="true"><Icon /></span>{/if}
+          {action.label}
+        </Button>
+        {#if action.disabled === true && action.reason}
+          <p class="action-panel-reason" id={reasonId}>{action.reason}</p>
+        {/if}
+      </div>
+    {/each}
+  </div>
+{/if}
+
+<style>
+  .action-panel {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-sm);
+  }
+
+  .action-panel-item {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-2xs);
+  }
+
+  /* Ficha CTAs read as a stacked column — each button spans the panel. */
+  .action-panel :global(.action-panel-btn) {
+    width: 100%;
+  }
+
+  .action-panel-icon {
+    display: inline-flex;
+    align-items: center;
+  }
+
+  .action-panel-icon :global(svg) {
+    width: var(--icon-size-sm);
+    height: var(--icon-size-sm);
+  }
+
+  .action-panel-reason {
+    margin: 0;
+    font-size: var(--type-body-sm-size);
+    color: var(--color-text-secondary);
+  }
+</style>

package/components/ActionPanel.svelte.d.ts

@@ -0,0 +1,44 @@
+export default ActionPanel;
+export type ActionPanelItem = {
+    key?: string;
+    label: string;
+    href?: string;
+    icon?: import("svelte").Component;
+    variant?: "primary" | "secondary" | "ghost" | "destructive";
+    disabled?: boolean;
+    reason?: string;
+};
+type ActionPanel = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * ActionPanel
+ *
+ * A config-driven vertical stack of detail-page call-to-action buttons —
+ * vote / support / comment / acknowledge / reserve … Vertical-agnostic: every
+ * CTA is data ({ label, href, icon?, variant?, disabled?, reason? }).
+ *
+ * Presentational only — the consumer decides each CTA's enabled/disabled state
+ * and the reason it's closed (grant or row-state). An ENABLED CTA renders as a
+ * link (it navigates to the action form); a CLOSED CTA renders as a disabled
+ * control with its reason as VISIBLE, programmatically-associated helper text
+ * (`aria-describedby`) — never a dead button. Decorative icons are aria-hidden.
+ *
+ * Consumes semantic tokens (`--space-*`, `--color-*`) so dark / high-contrast
+ * schemes (#244) ride through without per-component token entries.
+ *
+ * @example
+ * <ActionPanel actions={[
+ *   { key: 'vote', label: 'Vote for this proposal', href: '/submit/vote', icon: ThumbsUpIcon },
+ *   { key: 'support', label: 'Support', disabled: true, reason: 'Voting has closed.' },
+ * ]} />
+ */
+declare const ActionPanel: import("svelte").Component<{
+    actions?: any[];
+    class?: string;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    actions?: any[];
+    class?: string;
+} & Record<string, any>;

package/components/FeedView.svelte

@@ -0,0 +1,190 @@
+<!--
+  @component FeedView
+
+  A segmented view-switch for one feed (e.g. list ⇄ map). Presentational only:
+  it renders the available views as a WAI-ARIA tablist and emits the chosen
+  view via `onchange` — it does NOT render the views' content (the consumer
+  swaps that in response to the change, typically by re-resolving the feed).
+
+  Keyboard (automatic activation, per the tablist pattern for cheap-to-reveal
+  views): Arrow keys move focus AND select; Home/End jump to the ends; focus
+  roves (active tab is the only tab stop).
+
+  Consumes --feedview-* tokens from components.css.
+
+  @example
+  <FeedView
+    views={[
+      { value: 'list', label: 'List' },
+      { value: 'map', label: 'Map' },
+    ]}
+    bind:value={activeView}
+    onchange={(v) => goto(`?view=${v}`)}
+  />
+
+  @example With icons (icon is a Svelte component, e.g. phosphor-svelte)
+  <FeedView views={[
+    { value: 'list', label: 'List', icon: ListIcon },
+    { value: 'map', label: 'Map', icon: MapIcon },
+  ]} bind:value={activeView} onchange={onChange} />
+-->
+<script module>
+  let _feedviewUid = 0;
+  /**
+   * @typedef {{ value: string, label: string, icon?: import('svelte').Component }} FeedViewOption
+   */
+</script>
+
+<script>
+  let {
+    /** @type {FeedViewOption[]} The available views (first = default). */
+    views = [],
+    /** @type {string} The active view's value (bindable). */
+    value = $bindable(''),
+    /** @type {((value: string) => void) | undefined} Fires when the view changes. */
+    onchange = undefined,
+    /** @type {string} Accessible name for the tablist. */
+    label = 'View',
+    /** @type {string} */
+    class: className = '',
+    ...rest
+  } = $props();
+
+  const uid = `feedview-${_feedviewUid++}`;
+  /** @type {HTMLButtonElement[]} */
+  let tabs = $state([]);
+
+  const activeIndex = $derived(Math.max(0, views.findIndex((v) => v.value === value)));
+
+  /** @param {string} v */
+  function select(v) {
+    if (v === value) return;
+    value = v;
+    onchange?.(v);
+  }
+
+  /**
+   * @param {number} index
+   * @param {boolean} focus
+   */
+  function activate(index, focus) {
+    const view = views[index];
+    if (!view) return;
+    if (focus) tabs[index]?.focus();
+    select(view.value);
+  }
+
+  /** @param {KeyboardEvent} event */
+  function onKeydown(event) {
+    const last = views.length - 1;
+    let next = -1;
+    switch (event.key) {
+      case 'ArrowRight':
+      case 'ArrowDown':
+        next = activeIndex >= last ? 0 : activeIndex + 1;
+        break;
+      case 'ArrowLeft':
+      case 'ArrowUp':
+        next = activeIndex <= 0 ? last : activeIndex - 1;
+        break;
+      case 'Home':
+        next = 0;
+        break;
+      case 'End':
+        next = last;
+        break;
+      default:
+        return;
+    }
+    event.preventDefault();
+    activate(next, true);
+  }
+</script>
+
+<div
+  class="feedview {className}"
+  role="tablist"
+  aria-label={label}
+  onkeydown={onKeydown}
+  {...rest}
+>
+  {#each views as view, i (view.value)}
+    {@const Icon = view.icon}
+    {@const isActive = view.value === value}
+    <button
+      type="button"
+      role="tab"
+      id={`${uid}-${view.value}`}
+      aria-selected={isActive}
+      tabindex={isActive ? 0 : -1}
+      class="feedview-tab"
+      class:feedview-tab-active={isActive}
+      bind:this={tabs[i]}
+      onclick={() => activate(i, false)}
+    >
+      {#if Icon}<span class="feedview-icon" aria-hidden="true"><Icon /></span>{/if}
+      <span class="feedview-label">{view.label}</span>
+    </button>
+  {/each}
+</div>
+
+<style>
+  .feedview {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--space-2xs);
+    background: var(--feedview-bg);
+    border-radius: var(--feedview-radius);
+    padding: var(--feedview-padding);
+  }
+
+  .feedview-tab {
+    all: unset;
+    box-sizing: border-box;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: var(--space-xs);
+    height: var(--feedview-tab-height);
+    padding: 0 var(--feedview-tab-padding-x);
+    border-radius: var(--feedview-tab-radius);
+    font-family: var(--feedview-tab-font);
+    font-size: var(--feedview-tab-size);
+    letter-spacing: var(--feedview-tab-tracking);
+    color: var(--feedview-tab-color);
+    cursor: pointer;
+    white-space: nowrap;
+    transition: all var(--feedview-tab-transition);
+  }
+
+  .feedview-tab:hover {
+    color: var(--color-text);
+  }
+
+  .feedview-tab:focus-visible {
+    outline: var(--focus-ring-width) solid var(--focus-ring-color);
+    outline-offset: var(--focus-ring-offset);
+  }
+
+  .feedview-tab-active {
+    color: var(--feedview-tab-color-active);
+    background: var(--feedview-tab-bg-active);
+    box-shadow: var(--feedview-tab-shadow-active);
+  }
+
+  .feedview-icon {
+    display: inline-flex;
+    align-items: center;
+  }
+
+  .feedview-icon :global(svg) {
+    width: var(--icon-size-sm);
+    height: var(--icon-size-sm);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .feedview-tab {
+      transition: none;
+    }
+  }
+</style>

package/components/FeedView.svelte.d.ts

@@ -0,0 +1,54 @@
+export default FeedView;
+export type FeedViewOption = {
+    value: string;
+    label: string;
+    icon?: import("svelte").Component;
+};
+type FeedView = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * FeedView
+ *
+ * A segmented view-switch for one feed (e.g. list ⇄ map). Presentational only:
+ * it renders the available views as a WAI-ARIA tablist and emits the chosen
+ * view via `onchange` — it does NOT render the views' content (the consumer
+ * swaps that in response to the change, typically by re-resolving the feed).
+ *
+ * Keyboard (automatic activation, per the tablist pattern for cheap-to-reveal
+ * views): Arrow keys move focus AND select; Home/End jump to the ends; focus
+ * roves (active tab is the only tab stop).
+ *
+ * Consumes --feedview-* tokens from components.css.
+ *
+ * @example
+ * <FeedView
+ *   views={[
+ *     { value: 'list', label: 'List' },
+ *     { value: 'map', label: 'Map' },
+ *   ]}
+ *   bind:value={activeView}
+ *   onchange={(v) => goto(`?view=${v}`)}
+ * />
+ *
+ * @example With icons (icon is a Svelte component, e.g. phosphor-svelte)
+ * <FeedView views={[
+ *   { value: 'list', label: 'List', icon: ListIcon },
+ *   { value: 'map', label: 'Map', icon: MapIcon },
+ * ]} bind:value={activeView} onchange={onChange} />
+ */
+declare const FeedView: import("svelte").Component<{
+    views?: any[];
+    value?: string;
+    onchange?: any;
+    label?: string;
+    class?: string;
+} & Record<string, any>, {}, "value">;
+type $$ComponentProps = {
+    views?: any[];
+    value?: string;
+    onchange?: any;
+    label?: string;
+    class?: string;
+} & Record<string, any>;

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/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/RecordList.svelte

@@ -0,0 +1,131 @@
+<!--
+  @component RecordList
+
+  A typed list of child records rendered from FIELD CONFIG — the generalisation
+  of a comment list into any detail-page child collection (reviews, pareceres,
+  occurrence updates, maintenance logs). Vertical-agnostic: `items` is the child
+  rows, `fields` declares which keys to show and how.
+
+  Layout convention (so one component serves every collection): the FIRST field
+  is the record's primary line; the rest render as a muted meta line, separated
+  by middots. A field may `format` as a date (locale-formatted) or `badge`
+  (rendered as a Badge). Soft-empty: no items → nothing; an absent field value
+  is skipped (no dangling separators).
+
+  Consumes semantic tokens so dark / high-contrast schemes (#244) ride through.
+
+  @example
+  <RecordList
+    items={updates}
+    fields={[
+      { key: 'note', label: 'Update' },
+      { key: 'author' },
+      { key: 'created_at', format: 'date' },
+      { key: 'status', format: 'badge' },
+    ]}
+    locale="pt"
+  />
+-->
+<script module>
+  /**
+   * @typedef {{ key: string, label?: string, format?: 'text' | 'date' | 'badge' }} RecordField
+   */
+</script>
+
+<script>
+  import List from './List.svelte';
+  import ListItem from './ListItem.svelte';
+  import Badge from './Badge.svelte';
+
+  let {
+    /** @type {Record<string, unknown>[]} The child records to render. */
+    items = [],
+    /** @type {RecordField[]} The columns; fields[0] is the primary line. */
+    fields = [],
+    /** @type {string} BCP-47 locale for date formatting. */
+    locale = 'en',
+    /** @type {string} */
+    class: className = '',
+    ...rest
+  } = $props();
+
+  /**
+   * @param {unknown} value
+   * @param {RecordField} field
+   * @returns {string}
+   */
+  function display(value, field) {
+    if (value === null || value === undefined || value === '') return '';
+    if (field.format === 'date') {
+      const d = new Date(String(value));
+      return Number.isNaN(d.getTime()) ? String(value) : d.toLocaleDateString(locale);
+    }
+    return String(value);
+  }
+
+  /**
+   * The non-empty meta fields (everything after the primary) for one record —
+   * precomputed so the template never emits a leading/dangling separator.
+   * @param {Record<string, unknown>} item
+   * @returns {{ field: RecordField, value: unknown }[]}
+   */
+  function metaParts(item) {
+    return fields
+      .slice(1)
+      .map((field) => ({ field, value: item[field.key] }))
+      .filter((p) => p.value !== null && p.value !== undefined && p.value !== '');
+  }
+</script>
+
+{#if items.length > 0 && fields.length > 0}
+  <List class={className} {...rest}>
+    {#each items as item, i (item.id ?? i)}
+      {@const primary = fields[0]}
+      {@const primaryValue = item[primary.key]}
+      {@const meta = metaParts(item)}
+      <ListItem>
+        {#snippet leading()}
+          {#if primaryValue !== null && primaryValue !== undefined && primaryValue !== ''}
+            <span class="record-primary">
+              {#if primary.format === 'badge'}
+                <Badge>{String(primaryValue)}</Badge>
+              {:else}
+                {display(primaryValue, primary)}
+              {/if}
+            </span>
+          {/if}
+          {#if meta.length > 0}
+            <span class="record-meta">
+              {#each meta as part, mi (part.field.key)}
+                {#if mi > 0}<span class="record-sep" aria-hidden="true">·</span>{/if}
+                {#if part.field.format === 'badge'}
+                  <Badge>{String(part.value)}</Badge>
+                {:else}<span>{display(part.value, part.field)}</span>{/if}
+              {/each}
+            </span>
+          {/if}
+        {/snippet}
+      </ListItem>
+    {/each}
+  </List>
+{/if}
+
+<style>
+  .record-primary {
+    display: block;
+  }
+
+  .record-meta {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--space-2xs);
+    margin-top: var(--space-2xs);
+    font-size: var(--type-body-sm-size);
+    color: var(--color-text-secondary);
+  }
+
+  .record-sep {
+    color: var(--color-text-secondary);
+  }
+</style>

package/components/RecordList.svelte.d.ts

@@ -0,0 +1,50 @@
+export default RecordList;
+export type RecordField = {
+    key: string;
+    label?: string;
+    format?: "text" | "date" | "badge";
+};
+type RecordList = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * RecordList
+ *
+ * A typed list of child records rendered from FIELD CONFIG — the generalisation
+ * of a comment list into any detail-page child collection (reviews, pareceres,
+ * occurrence updates, maintenance logs). Vertical-agnostic: `items` is the child
+ * rows, `fields` declares which keys to show and how.
+ *
+ * Layout convention (so one component serves every collection): the FIRST field
+ * is the record's primary line; the rest render as a muted meta line, separated
+ * by middots. A field may `format` as a date (locale-formatted) or `badge`
+ * (rendered as a Badge). Soft-empty: no items → nothing; an absent field value
+ * is skipped (no dangling separators).
+ *
+ * Consumes semantic tokens so dark / high-contrast schemes (#244) ride through.
+ *
+ * @example
+ * <RecordList
+ *   items={updates}
+ *   fields={[
+ *     { key: 'note', label: 'Update' },
+ *     { key: 'author' },
+ *     { key: 'created_at', format: 'date' },
+ *     { key: 'status', format: 'badge' },
+ *   ]}
+ *   locale="pt"
+ * />
+ */
+declare const RecordList: import("svelte").Component<{
+    items?: any[];
+    fields?: any[];
+    locale?: string;
+    class?: string;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    items?: any[];
+    fields?: any[];
+    locale?: string;
+    class?: string;
+} & Record<string, any>;

package/components/index.d.ts

@@ -21,6 +21,9 @@ export { default as AppFrame } from "./AppFrame.svelte";
 export { default as SiteHeader } from "./SiteHeader.svelte";
 export { default as SiteFooter } from "./SiteFooter.svelte";
 export { default as SkipLink } from "./SkipLink.svelte";
+export { default as TextSizeAdjuster } from "./TextSizeAdjuster.svelte";
+export { default as ContrastToggle } from "./ContrastToggle.svelte";
+export { default as LinkHighlightToggle } from "./LinkHighlightToggle.svelte";
 export { default as ServiceNavigation } from "./ServiceNavigation.svelte";
 export { default as Link } from "./Link.svelte";
 export { default as Hero } from "./Hero.svelte";
@@ -47,6 +50,9 @@ export { default as Tabs } from "./Tabs.svelte";
 export { default as TabList } from "./TabList.svelte";
 export { default as Tab } from "./Tab.svelte";
 export { default as TabPanel } from "./TabPanel.svelte";
+export { default as FeedView } from "./FeedView.svelte";
+export { default as ActionPanel } from "./ActionPanel.svelte";
+export { default as RecordList } from "./RecordList.svelte";
 export { default as Alert } from "./Alert.svelte";
 export { default as Toast } from "./Toast.svelte";
 export { default as ToastManager } from "./ToastManager.svelte";

package/components/index.js

@@ -75,6 +75,11 @@ export { default as Tabs } from "./Tabs.svelte";
 export { default as TabList } from "./TabList.svelte";
 export { default as Tab } from "./Tab.svelte";
 export { default as TabPanel } from "./TabPanel.svelte";
+export { default as FeedView } from "./FeedView.svelte";
+
+// Entity ficha (#105 Phase 2)
+export { default as ActionPanel } from "./ActionPanel.svelte";
+export { default as RecordList } from "./RecordList.svelte";
 
 // Feedback
 export { default as Alert } from "./Alert.svelte";

package/components/map-utils.d.ts

@@ -73,6 +73,77 @@ export function cssPx(el: Element, prop: string, fallback: number): number;
  * @returns {string[]}
  */
 export function getHeatmapGradient(el: Element): string[];
+/**
+ * @typedef {object} OverlayLayerStyle
+ * Flat style subset applied to a whole overlay layer. Colors are CSS color
+ * strings (they come from layer DATA — geolayers GeoStyler styles — not
+ * from design tokens; absent values fall back to the DS-tokened defaults).
+ * @property {string} [pointColor]
+ * @property {number} [pointRadius]
+ * @property {string} [strokeColor]
+ * @property {number} [strokeWidth]
+ * @property {string} [fillColor]
+ *
+ * @typedef {object} OverlayLayerDef
+ * One ordered overlay rendered between the tile layer and the component's
+ * own interactive vector layer. v1 is GeoJSON-only — the platform's citizen
+ * data plane serves GeoJSON (`/{app}/public/layers/{id}/features`); WMS/tile
+ * overlays arrive with the per-tenant raster principal (spec open question).
+ * @property {string} [id]
+ * @property {'geojson'} [type]
+ * @property {object} [data] — inline GeoJSON (Feature/FeatureCollection)
+ * @property {string} [url] — fetched when `data` is absent
+ * @property {OverlayLayerStyle | object} [style] — flat style or GeoStyler
+ *   JSON (best-effort subset via `geoStylerToFlat`)
+ * @property {boolean} [visible]
+ */
+/**
+ * Best-effort GeoStyler → flat style. Reads the first symbolizer of the
+ * first rule — enough for the platform's single-rule layer styles. Unknown
+ * shapes return {} so the DS-tokened defaults apply.
+ *
+ * @param {any} style
+ * @returns {OverlayLayerStyle}
+ */
+export function geoStylerToFlat(style: any): OverlayLayerStyle;
+/**
+ * Builds OL vector layers for `layers` overlay defs, ordered as given.
+ * URL-sourced layers load asynchronously into their source; a fetch failure
+ * leaves that overlay empty and logs a warning (the map still renders).
+ *
+ * @param {OverlayLayerDef[]} defs
+ * @param {import('./map-utils.js').MapStyles} styles — DS default styles
+ * @returns {Promise<import('ol/layer/Vector.js').default[]>}
+ */
+export function createOverlayLayers(defs: OverlayLayerDef[], styles: import("./map-utils.js").MapStyles): Promise<import("ol/layer/Vector.js").default[]>;
+/**
+ * Normalises a boundary prop into polygon rings (lon/lat WGS84).
+ * Accepts: raw ring `number[][]`, GeoJSON Polygon / MultiPolygon,
+ * Feature, or FeatureCollection (first polygonal feature per entry).
+ *
+ * @param {any} boundary
+ * @returns {number[][][]} — array of outer rings (one per polygon)
+ */
+export function boundaryToRings(boundary: any): number[][][];
+/**
+ * Ray-casting point-in-polygon over WGS84 rings (outer rings only — holes
+ * are out of scope for the boundary gate; the BFF hard-gate is authoritative).
+ *
+ * @param {[number, number]} lonLat
+ * @param {number[][][]} rings — from `boundaryToRings`
+ * @returns {boolean} true when the point is inside ANY ring
+ */
+export function pointInRings(lonLat: [number, number], rings: number[][][]): boolean;
+/**
+ * Builds the boundary overlay layer (dashed outline, faint fill — distinct
+ * from the selection polygon so "the edge of the allowed area" reads as
+ * context, not content). Token-driven: --map-boundary-*.
+ *
+ * @param {number[][][]} rings
+ * @param {Element} el — token read context
+ * @returns {Promise<import('ol/layer/Vector.js').default | null>}
+ */
+export function createBoundaryLayer(rings: number[][][], el: Element): Promise<import("ol/layer/Vector.js").default | null>;
 export type OsmSource = {
     type: "osm";
 };
@@ -98,3 +169,39 @@ export type MapStyles = {
      */
     refresh: () => void;
 };
+/**
+ * Flat style subset applied to a whole overlay layer. Colors are CSS color
+ * strings (they come from layer DATA — geolayers GeoStyler styles — not
+ * from design tokens; absent values fall back to the DS-tokened defaults).
+ */
+export type OverlayLayerStyle = {
+    pointColor?: string;
+    pointRadius?: number;
+    strokeColor?: string;
+    strokeWidth?: number;
+    fillColor?: string;
+};
+/**
+ * One ordered overlay rendered between the tile layer and the component's
+ * own interactive vector layer. v1 is GeoJSON-only — the platform's citizen
+ * data plane serves GeoJSON (`/{app}/public/layers/{id}/features`); WMS/tile
+ * overlays arrive with the per-tenant raster principal (spec open question).
+ */
+export type OverlayLayerDef = {
+    id?: string;
+    type?: "geojson";
+    /**
+     * — inline GeoJSON (Feature/FeatureCollection)
+     */
+    data?: object;
+    /**
+     * — fetched when `data` is absent
+     */
+    url?: string;
+    /**
+     * — flat style or GeoStyler
+     * JSON (best-effort subset via `geoStylerToFlat`)
+     */
+    style?: OverlayLayerStyle | object;
+    visible?: boolean;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/design-system",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Design system tokens and Svelte components for aiaiai products",
   "license": "MIT",
   "type": "module",

package/tokens/components.css

@@ -403,6 +403,25 @@
   --tabs-trigger-transition: var(--duration-instant) var(--easing-default);
   --tabs-content-padding-top: var(--space-md);
 
+  /* ═══════════════════════════════════════════════
+     FEEDVIEW (segmented view-switch — list ⇄ map)
+     ═══════════════════════════════════════════════ */
+
+  --feedview-bg: var(--color-surface-secondary);
+  --feedview-radius: var(--radius-md);
+  --feedview-padding: var(--space-2xs);
+  --feedview-tab-font: var(--type-label-font);
+  --feedview-tab-size: var(--type-label-size);
+  --feedview-tab-tracking: var(--type-label-tracking);
+  --feedview-tab-height: 32px;
+  --feedview-tab-padding-x: var(--space-md);
+  --feedview-tab-radius: var(--radius-sm);
+  --feedview-tab-color: var(--color-text-secondary);
+  --feedview-tab-color-active: var(--color-text);
+  --feedview-tab-bg-active: var(--color-surface);
+  --feedview-tab-shadow-active: var(--elevation-raised);
+  --feedview-tab-transition: var(--duration-instant) var(--easing-default);
+
   /* ═══════════════════════════════════════════════
      MODAL (centered overlay)
      ═══════════════════════════════════════════════ */