sharper.ly/apps/web/app/routes/knowledge-hub.tsx

/* ============================================================================
   KNOWLEDGE HUB - listing
   ----------------------------------------------------------------------------
   /{locale}/knowledge-hub

   §7 of docs/SHARPER_Website_Draft_Section_EN_AR.docx: training modules,
   toolkits, Civil Society Law Session guides, case studies and FAQs, laid out
   to the 2026 redesign draft ("Knowledge-Hub"):

     hero        the search box the ToR asks for, in the headline band
     collections the five kinds of material as numbered tiles, each carrying
                 the number of items published under it
     FAQs        a sticky heading column beside the accordion
     repository  the closing note on long-term storage

   Browsing is by type, by tag and by free-text search, all three held in the
   query string so a browse is a shareable, crawlable URL:
   ?type=case-study&topic=access-to-justice&q=municipality

   The ?type= values are the `knowledge-item.itemType` enumeration in the CMS,
   verbatim, so the URL and the Strapi filter cannot drift apart.

   Tags are the shared `topics` taxonomy - the same vocabulary the resources
   listing and the news archive filter on - so a tag means the same thing
   everywhere on the site instead of drifting per section.

   WHAT COMES FROM WHERE
     * the five type names and their one-line descriptions are approved draft
       copy and live in ./_shared/page-copy;
     * the COUNT on each tile is Strapi's own count. The draft's "12 modules ·
       EN / AR", "6 guides", "9 case studies" were sample text and are not
       shipped;
     * the FAQ band reads api::faq.faq. The draft writes out five questions and
       answers - on the rule of law, SUQ, eligibility, P2R and reuse - and not
       one of them appears in an approved document, so none of them is
       published here. Until an editor writes them the band shows its localised
       "being prepared" line;
     * the repository note is the ToR's own wording (§2 and §3.3), not the
       draft's stronger claim that every item already is versioned and kept
       beyond the project's end.
   ========================================================================= */

import { Link, useLocation } from "react-router";

import { Button } from "~/components/ui/Button";
import { Card, CardActionHint, CardLink, CardShell } from "~/components/ui/Card";
import {
  formatDate,
  formatNumber,
  interpolate,
  sectionPath,
  useTranslation,
  type Locale,
} from "~/i18n";
import { buildBreadcrumbJsonLd, buildMeta } from "~/lib/seo";

import type { Route } from "./+types/knowledge-hub";
import { Accordion } from "./_page-kit/accordion";
import type { CmsFaq } from "./_page-kit/cms-types";
import { loadMany } from "./_page-kit/cms.server";
import { Container } from "./_page-kit/sections";
import {
  CMS,
  KNOWLEDGE_TYPES,
  fetchCollection,
  fetchCount,
  fetchFilterOptions,
  toImage,
  type CmsImage,
  type KnowledgeEntry,
} from "./_shared/cms";
import {
  PAGE_SIZE,
  buildPagination,
  compactFilters,
  parseOptionalEnum,
  parsePage,
  parseQuery,
  parseSlug,
  readRootSeo,
  requireLocale,
  withParam,
} from "./_shared/listing";
import {
  CalloutBand,
  EmptyState,
  FilterPills,
  ListingHero,
  PageShell,
  Pagination,
  PillSelect,
  ResultSummary,
  SearchForm,
} from "./_shared/listing-ui";
import {
  KNOWLEDGE_COPY,
  KNOWLEDGE_TYPE_BLURBS,
  KNOWLEDGE_TYPE_LABELS,
  getListingChrome,
} from "./_shared/page-copy";

import "./_page-kit/motion.css";

const DATE_FIELD = "publicationDate";

/** More than a dozen questions is a page of its own, not one band. */
const FAQ_PAGE_SIZE = 12;

/** The label for one `itemType`, or the raw value if a new one is added. */
function typeLabel(value: string, locale: Locale): string {
  return KNOWLEDGE_TYPE_LABELS[locale][value] ?? value;
}

interface KnowledgeListItem {
  readonly id: string;
  readonly slug: string;
  readonly title: string;
  readonly summary?: string;
  readonly typeLabel?: string;
  readonly dateLabel?: string;
  readonly image?: CmsImage;
}

/* ---------------------------------------------------------------------------
   LOADER
   ------------------------------------------------------------------------ */

export async function loader({ params, request }: Route.LoaderArgs) {
  const locale = requireLocale(params.lang);
  const search = new URL(request.url).searchParams;

  const page = parsePage(search);
  const type = parseOptionalEnum(search, "type", KNOWLEDGE_TYPES);
  const topic = parseSlug(search, "topic");
  const query = parseQuery(search);

  const filters = compactFilters({
    itemType: type ? { $eq: type } : undefined,
    topics: topic ? { slug: { $eq: topic } } : undefined,
    // Free text hits the title and the summary; the body is deliberately left
    // out so a passing mention does not outrank a real match.
    $or: query
      ? [{ title: { $containsi: query } }, { summary: { $containsi: query } }]
      : undefined,
  });

  const [listing, topicOptions, typeCounts, faqs] = await Promise.all([
    fetchCollection<KnowledgeEntry>(CMS.knowledgeItems, {
      locale,
      filters,
      sort: [`${DATE_FIELD}:desc`, "title:asc"],
      populate: {
        thumbnail: {
          fields: ["url", "alternativeText", "width", "height", "formats"],
        },
        topics: { fields: ["name", "slug"] },
      },
      pagination: { page, pageSize: PAGE_SIZE, withCount: true },
    }),
    fetchFilterOptions(CMS.topics, locale),
    /* One count per type card. Strapi's own figure, so a card can never
       promise material that has not been published. */
    Promise.all(
      KNOWLEDGE_TYPES.map((value) =>
        fetchCount(CMS.knowledgeItems, locale, { itemType: { $eq: value } }),
      ),
    ),
    loadMany<CmsFaq>("faqs", {
      locale,
      sort: ["order:asc", "createdAt:asc"],
      pagination: { pageSize: FAQ_PAGE_SIZE },
    }),
  ]);

  const entries: KnowledgeListItem[] = listing.entries.map((entry) =>
    toListItem(entry, locale),
  );

  return {
    entries,
    pagination: buildPagination(page, PAGE_SIZE, listing.pagination.total),
    available: listing.available,
    filters: {
      type: type ?? "",
      topic: topic ?? "",
      q: query ?? "",
    },
    facets: {
      types: KNOWLEDGE_TYPES.map((value) => ({
        value,
        label: typeLabel(value, locale),
      })),
      topics: topicOptions,
    },
    /** The five type cards, with the draft's descriptions and a real count. */
    browse: KNOWLEDGE_TYPES.map((value, index) => ({
      value,
      label: typeLabel(value, locale),
      blurb: KNOWLEDGE_TYPE_BLURBS[locale][value] ?? "",
      count: typeCounts[index] ?? 0,
    })),
    faqs: faqs
      .filter((faq) => Boolean(faq?.question && faq?.answer))
      .map((faq) => ({
        id: faq.documentId,
        question: faq.question,
        answer: faq.answer,
      })),
  };
}

function toListItem(entry: KnowledgeEntry, locale: Locale): KnowledgeListItem {
  const image = toImage(entry.thumbnail, "small");
  const date = entry.publicationDate ?? entry.publishedAt ?? undefined;

  return {
    id: entry.documentId,
    slug: entry.slug,
    title: entry.title,
    ...(entry.summary ? { summary: entry.summary } : {}),
    ...(entry.itemType ? { typeLabel: typeLabel(entry.itemType, locale) } : {}),
    ...(date ? { dateLabel: formatDate(date, locale) } : {}),
    ...(image ? { image } : {}),
  };
}

/* ---------------------------------------------------------------------------
   META
   Canonical + hreflang are emitted by the shell for every route, so they are
   not repeated here - see root.tsx `Layout`.
   ------------------------------------------------------------------------ */

export function meta({ matches, loaderData }: Route.MetaArgs) {
  const root = readRootSeo(matches);
  const copy = KNOWLEDGE_COPY[root.locale];

  return buildMeta({
    locale: root.locale,
    pathname: root.pathname,
    siteUrl: root.siteUrl,
    title: copy.heading,
    description: copy.metaDescription,
    // If the CMS could not be reached the page is an empty shell, not an empty
    // section - keep it out of the index rather than teaching a crawler that
    // SHARP-ER has published nothing.
    noIndex: loaderData?.available === false,
    jsonLd: buildBreadcrumbJsonLd(root.siteUrl, [
      { name: "SHARP-ER", pathname: sectionPath("home", root.locale) },
      { name: copy.heading, pathname: sectionPath("knowledgeHub", root.locale) },
    ]),
  });
}

/* ---------------------------------------------------------------------------
   PAGE
   ------------------------------------------------------------------------ */

export default function KnowledgeHub({ loaderData }: Route.ComponentProps) {
  const { entries, pagination, filters, facets, browse, faqs } = loaderData;
  const { t, locale } = useTranslation();
  const { pathname, search } = useLocation();
  const params = new URLSearchParams(search);

  const copy = KNOWLEDGE_COPY[locale];
  const chrome = getListingChrome(locale).knowledge;
  const isFiltered = Boolean(filters.type || filters.topic || filters.q);

  const typePills = [
    {
      id: "all",
      label: t("filters.all"),
      href: `${pathname}${withParam(params, "type", undefined)}`,
      isCurrent: filters.type === "",
    },
    ...facets.types.map((option) => ({
      id: option.value,
      label: option.label,
      href: `${pathname}${withParam(params, "type", option.value)}`,
      isCurrent: filters.type === option.value,
    })),
  ];

  const keep = [...params.entries()]
    .filter(([key]) => key !== "q" && key !== "page")
    .map(([key, value]) => [key, value] as const);

  return (
    <>
      <ListingHero
        eyebrow={chrome.eyebrow}
        heading={copy.heading}
        intro={copy.intro}
        ambient={[{ top: -250, from: "start", offset: "10%", width: 740, height: 570, durationSeconds: 21 }]}
      >
        <SearchForm
          action={pathname}
          label={t("search.label")}
          placeholder={chrome.searchPlaceholder}
          defaultValue={filters.q}
          submitLabel={t("search.submit")}
          keep={keep}
          className="max-w-[var(--layout-prose-max)]"
        />
      </ListingHero>

      <PageShell>
        {/* The map of the hub. Hidden once a filter is on, where it would just
            repeat the control the reader has already used. */}
        {!isFiltered ? (
          <nav aria-label={chrome.browseLabel} className="flex flex-col gap-lg">
            <h2 className="sr-only">{chrome.browseLabel}</h2>
            <ul className="grid gap-lg sm:grid-cols-2 lg:grid-cols-3">
              {browse.map((item, index) => (
                <CollectionTile
                  key={item.value}
                  index={index}
                  label={item.label}
                  blurb={item.blurb}
                  count={item.count}
                  countTemplate={chrome.itemCount}
                  actionLabel={t("actions.browseHub")}
                  href={`${pathname}${withParam(new URLSearchParams(), "type", item.value)}`}
                  locale={locale}
                />
              ))}
            </ul>
          </nav>
        ) : null}

        <section className="flex flex-col gap-lg" aria-label={t("filters.heading")}>
          <div className="flex flex-wrap items-center justify-between gap-lg border-b border-border-subtle pb-lg">
            <FilterPills label={t("filters.category")} pills={typePills} />

            {facets.topics.length > 0 ? (
              <PillSelect
                name="topic"
                label={t("filters.topic")}
                value={filters.topic}
                options={facets.topics}
                allLabel={t("filters.all")}
                applyLabel={t("filters.apply")}
                action={pathname}
                keep={[
                  ...(filters.type ? [["type", filters.type] as const] : []),
                  ...(filters.q ? [["q", filters.q] as const] : []),
                ]}
              />
            ) : null}
          </div>

          {filters.q ? (
            <p className="body-md text-text-secondary">
              {t("search.resultsFor", { query: filters.q })}
            </p>
          ) : null}

          <ResultSummary pagination={pagination} t={t} />

          {entries.length === 0 ? (
            <EmptyState
              title={isFiltered ? t("filters.noResults") : copy.emptyTitle}
              body={isFiltered ? t("filters.noResultsHint") : copy.emptyBody}
            >
              {isFiltered ? (
                <Button as={Link} to={pathname} variant="secondary" size="sm">
                  {t("filters.clear")}
                </Button>
              ) : null}
            </EmptyState>
          ) : (
            <ul className="grid gap-lg sm:grid-cols-2 lg:grid-cols-3">
              {entries.map((entry) => (
                <Card.Content
                  key={entry.id}
                  as="li"
                  className="sh-reveal sh-reveal--in"
                  href={`${sectionPath("knowledgeHub", locale)}/${entry.slug}`}
                  title={entry.title}
                  actionLabel={t("actions.readMore")}
                  {...(entry.typeLabel ? { eyebrow: entry.typeLabel } : {})}
                  {...(entry.summary ? { excerpt: entry.summary } : {})}
                  {...(entry.dateLabel ? { badge: entry.dateLabel } : {})}
                  {...(entry.image ? { image: entry.image } : {})}
                />
              ))}
            </ul>
          )}

          <Pagination model={pagination} pathname={pathname} params={params} t={t} />
        </section>
      </PageShell>

      {/* The FAQ band. The draft lifts it off the #0B0B0A ground with
          #1D1D1B, so the surface is painted rather than inherited. */}
      <section
        aria-labelledby="hub-faqs"
        className="sh-band py-3xl md:py-4xl"
      >
        <Container>
          <div className="grid gap-2xl lg:grid-cols-[minmax(0,22rem)_minmax(0,1fr)] lg:items-start">
            <div className="sh-reveal flex flex-col gap-sm lg:sticky lg:top-[var(--layout-sticky-top)]">
              <p className="label-md uppercase text-text-accent">
                {chrome.faqEyebrow}
              </p>
              <h2 id="hub-faqs" className="heading-h2 text-text-primary">
                {chrome.faqHeading}
              </h2>
              <p className="body-md text-text-secondary">{chrome.faqIntro}</p>
            </div>

            {faqs.length > 0 ? (
              <Accordion items={faqs} />
            ) : (
              <EmptyState title={chrome.faqHeading} body={chrome.faqEmpty} />
            )}
          </div>
        </Container>
      </section>

      <PageShell>
        <CalloutBand
          eyebrow={chrome.repositoryEyebrow}
          headline={chrome.repositoryHeadline}
          action={{
            to: sectionPath("resources", locale),
            label: chrome.repositoryAction,
          }}
        />
      </PageShell>
    </>
  );
}

/* ---------------------------------------------------------------------------
   ONE COLLECTION TILE
   ----------------------------------------------------------------------------
   The draft numbers the tiles and closes each with a count and an arrow. The
   number is ordinal decoration, so it is hidden from assistive technology -
   the tile's accessible name is its title.
   ------------------------------------------------------------------------ */

function CollectionTile({
  index,
  label,
  blurb,
  count,
  countTemplate,
  actionLabel,
  href,
  locale,
}: {
  index: number;
  label: string;
  blurb: string;
  count: number;
  countTemplate: string;
  actionLabel: string;
  href: string;
  locale: Locale;
}) {
  const ordinal = formatNumber(index + 1, locale, {
    minimumIntegerDigits: 2,
    useGrouping: false,
  });

  return (
    <CardShell
      as="li"
      linked
      className="sh-reveal sh-reveal--in flex-col gap-md p-lg"
    >
      <p aria-hidden="true" className="heading-h2 text-text-accent">
        {ordinal}
      </p>

      <h3 className="sh-card-title body-lg-bold text-text-primary">
        <CardLink href={href} className="sh-card-link">
          {label}
        </CardLink>
      </h3>

      {blurb ? <p className="body-sm text-text-secondary">{blurb}</p> : null}

      <div className="mt-auto flex items-center justify-between gap-sm border-t border-border-subtle pt-sm">
        {/* Nothing published yet means no count - a row of zeroes would read
            as a fault rather than as an honest figure. */}
        {count > 0 ? (
          <p className="label-md uppercase text-text-tertiary">
            {interpolate(countTemplate, { count: formatNumber(count, locale) })}
          </p>
        ) : (
          <span />
        )}
        <CardActionHint label={actionLabel} />
      </div>
    </CardShell>
  );
}