@breathe-ds/ui 0.5.4 → 0.6.0

package/components/ProfileSpotlight.tsx

@@ -0,0 +1,94 @@
+import type { ComponentType, ReactNode } from "react";
+import { LivingPortrait, type ProfessionalLiving } from "./ProfessionalCard";
+
+type Props = {
+  name: string;
+  /** Small line above the name ("Idealizadora", "Course coordinator"). */
+  eyebrow?: ReactNode;
+  /** What the person does, under the name, one tone below. */
+  role?: ReactNode;
+  /** Council registration (CREFITO): the family rule for health professionals. */
+  registration?: ReactNode;
+  /** The bio: a string (one paragraph) or your own paragraphs. */
+  bio?: ReactNode;
+  /** The still portrait (4:5). With `living`, it is the fallback if the clip fails. */
+  photo: { src: string; alt?: string };
+  /** Living portrait: the clip plays muted while the mouse is on the block. */
+  living?: ProfessionalLiving;
+  /** Your own image element (e.g. next/image) in place of the photo; must fill the box. */
+  media?: ReactNode;
+  /** Links or buttons at the foot ("Watch the presentation", "Curriculum ↗"). */
+  actions?: ReactNode;
+  /** Social profiles at the foot (Instagram, LinkedIn, Lattes…): round icon
+   *  links, each with its name for screen readers, opening in a new tab. */
+  social?: { label: string; href: string; Icon: ComponentType<{ size?: number; strokeWidth?: number; "aria-hidden"?: boolean | "true" }> }[];
+  /** sr-only after each social link. */
+  newTabLabel?: string;
+  /** `card`: on a white card. `plain` (default): straight on the page color. */
+  variant?: "plain" | "card";
+  /** h2 for a page section (default), h3 inside a section that already has one. */
+  headingLevel?: "h2" | "h3";
+  id?: string;
+  className?: string;
+};
+
+/**
+ * Profile spotlight of the Cuidado Global family: one person in focus — the
+ * founder, a course coordinator, a guest. Portrait on the left (photo or the
+ * living portrait of the team pages), then eyebrow, name, role, registration,
+ * bio and actions. Stacks on phones (portrait on top). The whole block is the
+ * hover target of the living portrait.
+ */
+export function ProfileSpotlight({ name, eyebrow, role, registration, bio, photo, living, media, actions, social, newTabLabel = "(opens in a new tab)", variant = "plain", headingLevel = "h2", id, className = "" }: Props) {
+  const H = headingLevel;
+  const card = variant === "card";
+  return (
+    <article
+      id={id}
+      data-cg-professional-card
+      className={`grid items-center gap-8 md:grid-cols-[minmax(220px,360px)_1fr] md:gap-[clamp(32px,6vw,88px)] ${card ? "rounded-[28px] bg-card p-5 md:p-8" : ""} ${id ? "scroll-mt-24" : ""} ${className}`}
+    >
+      <div className="overflow-hidden rounded-2xl bg-tint">
+        {living ? (
+          <LivingPortrait src={living.src} poster={living.poster} photo={photo} media={media} alt={photo.alt ?? name} decorative className="aspect-[4/5]" />
+        ) : (
+          media ?? (
+            // eslint-disable-next-line @next/next/no-img-element
+            <img src={photo.src} alt="" loading="lazy" decoding="async" className="aspect-[4/5] w-full object-cover" />
+          )
+        )}
+      </div>
+      <div className="min-w-0">
+        {eyebrow && <p className="m-0 mb-3 font-heading text-sm font-semibold text-ink-soft">{eyebrow}</p>}
+        <H className="m-0 font-heading text-[clamp(1.9rem,3.6vw,2.75rem)] leading-[1.1] font-medium tracking-[-0.015em] text-ink">{name}</H>
+        {role && <p className="mt-4 mb-0 max-w-[52ch] text-lg leading-snug text-ink-body">{role}</p>}
+        {registration && <p className="mt-2 mb-0 text-sm text-ink-soft">{registration}</p>}
+        {bio && (
+          <div className="mt-6 flex max-w-[60ch] flex-col gap-4 leading-relaxed text-ink-body [&>p]:m-0">
+            {typeof bio === "string" ? <p>{bio}</p> : bio}
+          </div>
+        )}
+        {actions && <div className="mt-7 flex flex-wrap items-center gap-3">{actions}</div>}
+        {social?.length ? (
+          <ul className={`m-0 flex list-none flex-wrap gap-2 p-0 ${actions ? "mt-5" : "mt-7"}`}>
+            {social.map(({ label, href, Icon }) => (
+              <li key={href}>
+                <a
+                  href={href}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="flex h-11 w-11 items-center justify-center rounded-full bg-tint text-ink transition-colors duration-200 hover:bg-ink hover:text-surface focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ink motion-reduce:transition-none"
+                >
+                  <Icon size={19} strokeWidth={1.75} aria-hidden="true" />
+                  <span className="sr-only">
+                    {label} {newTabLabel}
+                  </span>
+                </a>
+              </li>
+            ))}
+          </ul>
+        ) : null}
+      </div>
+    </article>
+  );
+}

package/components/PublicationCard.tsx

@@ -0,0 +1,215 @@
+"use client";
+
+import { useId, useState, type ElementType, type ReactNode } from "react";
+import { ArrowRight, ChevronDown, FileText } from "lucide-react";
+import { FADE_IN } from "./Rows";
+
+export type PublicationCardLabels = {
+  /** The toggle ("Resumo"). */
+  abstract: string;
+  /** sr-only word before the title after the toggle and the PDF link ("de" → "Resumo de {title}").
+   *  A plain string so a server component can pass it. */
+  of: string;
+  pdf: string;
+  newTab: string;
+  /** Footer link of the compact card ("Ler o artigo"). */
+  read: string;
+};
+
+const EN: PublicationCardLabels = {
+  abstract: "Abstract",
+  of: "of",
+  pdf: "PDF",
+  newTab: "(opens in a new tab)",
+  read: "Read the article",
+};
+
+type Props = {
+  /** Plain title (sr-only labels). */
+  title: string;
+  /** Language of the title and abstract when it differs from the page ("en"). */
+  lang?: string;
+  /** The study type, shown as a small tag ("Ensaio clínico randomizado"). */
+  kind?: ReactNode;
+  /** Topics, in a lighter line beside the tag. */
+  topics?: ReactNode[];
+  /** Authors, already shortened ("Ana Souza e mais 3 autores"). */
+  byline?: ReactNode;
+  /** The publication's page on the site. */
+  href?: string;
+  /** The full PDF, opened in a new tab. */
+  pdf?: string;
+  /** Abstract paragraphs (structured abstracts keep Background / Methods… apart). */
+  abstract?: string[];
+  /** Language of the abstract if it differs from the title's. */
+  abstractLang?: string;
+  headingLevel?: "h2" | "h3";
+  /** `full` (default): the library row, abstract opening in place.
+   *  `compact`: the "related articles" tile — same height as its neighbours,
+   *  tag and topics on two fixed lines, and a footer pinned to the bottom with
+   *  "read the article" on the left and the PDF on the right. */
+  variant?: "full" | "compact";
+  /** Link component of the app (e.g. next-intl Link). Default: <a>. */
+  linkComponent?: ElementType;
+  labels?: Partial<PublicationCardLabels>;
+  className?: string;
+};
+
+/** "Background: text" -> the label in bold, so a structured abstract can be scanned. */
+export function abstractLabel(p: string): { label?: string; text: string } {
+  const m = p.match(/^([A-Z][A-Za-z ]{2,22}|[A-ZÀ-Ú ]{3,22}):\s*(.+)$/);
+  return m ? { label: m[1].replace(/\s+/g, " ").trim(), text: m[2] } : { text: p };
+}
+
+/** The paragraphs of an abstract, labels in bold. */
+export function AbstractText({ paragraphs, lang, className = "" }: { paragraphs: string[]; lang?: string; className?: string }) {
+  return (
+    <div lang={lang} className={`flex max-w-[68ch] flex-col gap-3 leading-relaxed text-ink-body ${className}`}>
+      {paragraphs.map((p, i) => {
+        const { label, text } = abstractLabel(p);
+        return (
+          <p key={i} className="m-0">
+            {label && <strong className="font-semibold text-ink">{label}. </strong>}
+            {text}
+          </p>
+        );
+      })}
+    </div>
+  );
+}
+
+const ACTION =
+  "inline-flex min-h-11 items-center gap-1.5 rounded-[2px] text-sm font-semibold text-ink focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ink";
+
+/**
+ * PublicationCard — one study in a library of scientific articles (ttcab's
+ * Artigos). Built on proximity and common region: the white card holds the
+ * whole item, the tag and topics sit tight over the title, the authors right
+ * under it, and the two actions (open the abstract here, open the PDF) share
+ * one row under the authors — never pushed to the far edge of the page.
+ *
+ * The abstract opens in place (a button with `aria-expanded` controlling the
+ * region below, so the PDF link can sit beside the toggle); it fades in with
+ * `@starting-style`, no JavaScript animation.
+ */
+export function PublicationCard({
+  title,
+  lang,
+  kind,
+  topics,
+  byline,
+  href,
+  pdf,
+  abstract,
+  abstractLang,
+  headingLevel: H = "h2",
+  variant = "full",
+  linkComponent,
+  labels,
+  className = "",
+}: Props) {
+  const t = { ...EN, ...labels };
+  const L: ElementType = linkComponent ?? "a";
+  const [open, setOpen] = useState(false);
+  const regionId = useId();
+  const hasAbstract = Boolean(abstract && abstract.length);
+
+  if (variant === "compact") {
+    return (
+      <article className={`flex h-full flex-col rounded-[22px] bg-card ${className}`}>
+        <div className="flex flex-1 flex-col px-6 pt-6 pb-5">
+          {kind && (
+            <p className="m-0">
+              <span className="inline-block rounded-full bg-tint px-2.5 py-1 text-xs font-semibold text-ink">{kind}</span>
+            </p>
+          )}
+          {topics && topics.length > 0 && <p className="m-0 mt-2 text-sm text-ink-soft">{topics.join(" · ")}</p>}
+          <H lang={lang} className="mt-3 font-heading text-[1.15rem] leading-snug font-medium text-balance text-ink">
+            {href ? (
+              <L href={href} className="rounded-[2px] underline decoration-transparent decoration-[1.5px] underline-offset-4 transition-[text-decoration-color] duration-150 hover:decoration-ink focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ink motion-reduce:transition-none">
+                {title}
+              </L>
+            ) : (
+              title
+            )}
+          </H>
+          {byline && <p className="m-0 mt-2 text-sm text-ink-soft">{byline}</p>}
+        </div>
+        {(href || pdf) && (
+          <footer className="flex min-h-14 items-center justify-between gap-4 rounded-b-[22px] border-t border-line bg-surface-alt/60 px-6">
+            {href ? (
+              <L href={href} tabIndex={-1} aria-hidden="true" className="group/read inline-flex min-h-11 items-center gap-1.5 text-sm font-semibold text-ink">
+                {t.read}
+                <ArrowRight aria-hidden="true" size={16} className="transition-transform duration-200 group-hover/read:translate-x-0.5 motion-reduce:transform-none" />
+              </L>
+            ) : (
+              <span />
+            )}
+            {pdf && (
+              <a href={pdf} target="_blank" rel="noopener noreferrer" className={`${ACTION} underline decoration-ink/35 decoration-[1.5px] underline-offset-4 transition-[text-decoration-color] duration-150 hover:decoration-ink motion-reduce:transition-none`}>
+                <FileText aria-hidden="true" size={16} className="text-ink-soft" />
+                {t.pdf}
+                <span className="sr-only">{` ${t.of} ${title} ${t.newTab}`}</span>
+              </a>
+            )}
+          </footer>
+        )}
+      </article>
+    );
+  }
+
+  return (
+    <article className={`rounded-[22px] bg-card p-[clamp(20px,3vw,28px)] ${className}`}>
+      {(kind || (topics && topics.length > 0)) && (
+        <p className="flex flex-wrap items-center gap-x-3 gap-y-1.5 text-sm text-ink-soft">
+          {kind && <span className="rounded-full bg-tint px-2.5 py-1 text-xs font-semibold text-ink">{kind}</span>}
+          {topics && topics.length > 0 && <span>{topics.join(" · ")}</span>}
+        </p>
+      )}
+      <H lang={lang} className="mt-3 max-w-[64ch] font-heading text-[1.2rem] leading-snug font-medium text-balance text-ink md:text-[1.3rem]">
+        {href ? (
+          <L
+            href={href}
+            className="rounded-[2px] underline decoration-transparent decoration-[1.5px] underline-offset-4 transition-[text-decoration-color] duration-150 hover:decoration-ink focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ink motion-reduce:transition-none"
+          >
+            {title}
+          </L>
+        ) : (
+          title
+        )}
+      </H>
+      {byline && <p className="mt-1.5 text-sm text-ink-soft">{byline}</p>}
+
+      {(hasAbstract || pdf) && (
+        <div className="mt-3 flex flex-wrap items-center gap-x-6 border-t border-line pt-1">
+          {hasAbstract && (
+            <button type="button" aria-expanded={open} aria-controls={regionId} onClick={() => setOpen((v) => !v)} className={`group/abs ${ACTION}`}>
+              {t.abstract}
+              <ChevronDown
+                aria-hidden="true"
+                size={16}
+                className={`text-ink-soft transition-transform duration-200 motion-reduce:transition-none ${open ? "rotate-180" : "group-hover/abs:translate-y-0.5"}`}
+              />
+              <span className="sr-only">{` ${t.of} ${title}`}</span>
+            </button>
+          )}
+          {pdf && (
+            <a href={pdf} target="_blank" rel="noopener noreferrer" className={`${ACTION} underline decoration-ink/35 decoration-[1.5px] underline-offset-4 transition-[text-decoration-color] duration-150 hover:decoration-ink motion-reduce:transition-none`}>
+              <FileText aria-hidden="true" size={16} className="text-ink-soft" />
+              {t.pdf}
+              <span className="sr-only">
+                {` ${t.of} ${title} ${t.newTab}`}
+              </span>
+            </a>
+          )}
+        </div>
+      )}
+
+      {hasAbstract && (
+        <div id={regionId} hidden={!open} className={`${FADE_IN} mt-2`}>
+          <AbstractText paragraphs={abstract!} lang={abstractLang ?? lang} />
+        </div>
+      )}
+    </article>
+  );
+}

package/components/PullQuote.tsx

@@ -0,0 +1,87 @@
+import type { ElementType, ReactNode } from "react";
+import { Byline, type Person } from "./Byline";
+
+/**
+ * The hand-drawn underline in the action color, under the key words of a line
+ * ("de forma integrada"). Decorative: the words stay plain text for screen
+ * readers. Keep it to a few words — it does not wrap.
+ */
+export function Highlight({ children }: { children: ReactNode }) {
+  return (
+    <span className="relative whitespace-nowrap">
+      {children}
+      <svg
+        aria-hidden="true"
+        viewBox="0 0 200 14"
+        preserveAspectRatio="none"
+        className="pointer-events-none absolute inset-x-0 -bottom-[0.16em] h-[0.3em] w-full"
+      >
+        <path
+          d="M3 9 C 40 3, 80 12, 118 7 C 150 3, 178 8, 197 6"
+          fill="none"
+          strokeWidth="3"
+          strokeLinecap="round"
+          className="stroke-action-line"
+        />
+      </svg>
+    </span>
+  );
+}
+
+type Props = {
+  /** The line itself. Use <Highlight> on the few words that carry it. */
+  children: ReactNode;
+  /** Who said it (portrait + name + role under the line). Omit for a brand
+   *  statement — then the quote marks stay, without an author. */
+  cite?: { people: Person[]; role?: ReactNode };
+  /** Small line above ("O que nos guia"). */
+  eyebrow?: ReactNode;
+  /** `center` (default) for a statement between sections; `start` beside other content. */
+  align?: "center" | "start";
+  /** `lg` (default) between sections; `md` inside a column or a card. */
+  size?: "md" | "lg";
+  /** Big opening quote mark in the action color. Default: true. */
+  mark?: boolean;
+  as?: ElementType;
+  className?: string;
+};
+
+const SIZE = {
+  lg: "text-[clamp(1.75rem,4.2vw,3.25rem)] leading-[1.14]",
+  md: "text-[clamp(1.4rem,2.6vw,2rem)] leading-[1.2]",
+};
+
+/**
+ * Pull quote of the Cuidado Global family: one line that matters, set large,
+ * with the opening mark in the action color and, optionally, the person who
+ * said it (the family's Byline). Between sections it breathes on its own; the
+ * line is balanced (text-balance) so it never ends on a lonely word.
+ */
+export function PullQuote({ children, cite, eyebrow, align = "center", size = "lg", mark = true, as: Root = "figure", className = "" }: Props) {
+  const center = align === "center";
+  return (
+    <Root className={`${center ? "mx-auto text-center" : ""} max-w-4xl ${className}`}>
+      {mark && (
+        // drawn mark: the font's own “ is tiny in Quicksand, it would not hold the line
+        <svg
+          aria-hidden="true"
+          viewBox="0 0 48 36"
+          className={`mb-6 block h-9 w-12 fill-action-line md:mb-8 md:h-12 md:w-16 ${center ? "mx-auto" : ""}`}
+        >
+          <path d="M0 36V22C0 10.5 6 2.6 18.2 0l2.3 5.2C14.6 7.4 11.4 11 11 16h8.6v20H0Zm27.4 0V22c0-11.5 6-19.4 18.2-22l2.3 5.2C42 7.4 38.8 11 38.4 16H47v20H27.4Z" />
+        </svg>
+      )}
+      {eyebrow && (
+        <p className="mb-4 font-heading text-[0.82rem] font-bold tracking-[0.14em] text-ink-soft uppercase">{eyebrow}</p>
+      )}
+      <blockquote className="m-0">
+        <p className={`m-0 font-heading font-medium tracking-[-0.015em] text-balance text-ink ${SIZE[size]}`}>{children}</p>
+      </blockquote>
+      {cite && (
+        <figcaption className={`mt-8 flex ${center ? "justify-center" : ""}`}>
+          <Byline cite people={cite.people} subtitle={cite.role} className="text-left" />
+        </figcaption>
+      )}
+    </Root>
+  );
+}

package/components/RegistrationBox.tsx

@@ -66,7 +66,7 @@ export function RegistrationBox({ title, intro, options, value, onChange, action
                   </span>
                   <span className="flex min-w-0 flex-1 flex-wrap items-center gap-2 font-semibold text-ink">
                     {o.label}
-                    {o.remaining && <span className="rounded-pill bg-ink/[0.08] px-2 py-0.5 text-xs font-semibold text-ink-soft">{o.remaining}</span>}
+                    {o.remaining && <span className="rounded-pill bg-tint px-2 py-0.5 text-xs font-semibold text-ink-soft">{o.remaining}</span>}
                   </span>
                   <span className="shrink-0 font-semibold text-ink">{o.price}</span>
                 </label>

package/components/SearchField.tsx

@@ -0,0 +1,85 @@
+"use client";
+
+import { useRef, type InputHTMLAttributes, type ReactNode } from "react";
+import { Search, X } from "lucide-react";
+
+/** The family's field: a white pill on the page colour, warm hairline, the
+ *  card's soft shadow. 56px tall, so it reads as the page's main control. */
+export const FIELD =
+  "w-full min-h-14 rounded-pill border border-line bg-card text-base text-ink shadow-[0_2px_12px_color-mix(in_srgb,var(--color-shadow)_6%,transparent)] transition-[border-color,box-shadow] duration-150 outline-none hover:border-ink/35 focus-visible:border-ink focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ink disabled:cursor-not-allowed disabled:opacity-60 motion-reduce:transition-none";
+
+/** Label of a field: Figtree semibold in `ink`, sentence case (no uppercase
+ *  tracking: the label is read, not scanned). */
+export const FIELD_LABEL = "mb-2 block text-sm font-semibold text-ink";
+
+type Props = Omit<InputHTMLAttributes<HTMLInputElement>, "value" | "onChange" | "type" | "children"> & {
+  id: string;
+  label: ReactNode;
+  value: string;
+  onValueChange: (value: string) => void;
+  /** aria-label of the clear button ("Limpar busca"). */
+  clearLabel?: string;
+  /** Short help under the field, linked by aria-describedby. */
+  hint?: ReactNode;
+  /** Keep the label for screen readers only (when a heading right above already names the field). */
+  hideLabel?: boolean;
+  className?: string;
+};
+
+/**
+ * SearchField — the search box of a list page (the professionals directory,
+ * a blog). A native `type="search"` input (Esc clears it, the phone keyboard
+ * shows "Search"), with the lucide magnifier on the left and a clear button
+ * on the right once there is text; clearing puts the focus back in the field.
+ * The browser's own cancel glyph is hidden so there is only one ✕.
+ *
+ * Placeholder in `ink-soft` (#54707a on white: 5.3:1 on ttcab, passes AA):
+ * it carries an example, so it has to be legible.
+ */
+export function SearchField({ id, label, value, onValueChange, clearLabel = "Clear search", hint, hideLabel = false, className = "", ...rest }: Props) {
+  const input = useRef<HTMLInputElement>(null);
+  const hintId = hint ? `${id}-hint` : undefined;
+  return (
+    <div className={className}>
+      <label htmlFor={id} className={hideLabel ? "sr-only" : FIELD_LABEL}>
+        {label}
+      </label>
+      <div className="relative">
+        <Search aria-hidden="true" size={20} className="pointer-events-none absolute top-1/2 left-5 -translate-y-1/2 text-ink-soft" />
+        <input
+          ref={input}
+          id={id}
+          type="search"
+          value={value}
+          onChange={(e) => onValueChange(e.target.value)}
+          autoComplete="off"
+          autoCorrect="off"
+          autoCapitalize="none"
+          spellCheck={false}
+          enterKeyHint="search"
+          aria-describedby={hintId}
+          className={`${FIELD} pr-14 pl-13 placeholder:text-ink-soft [&::-webkit-search-cancel-button]:appearance-none [&::-webkit-search-decoration]:appearance-none`}
+          {...rest}
+        />
+        {value && (
+          <button
+            type="button"
+            aria-label={clearLabel}
+            onClick={() => {
+              onValueChange("");
+              input.current?.focus();
+            }}
+            className="absolute top-1/2 right-2 flex h-10 w-10 -translate-y-1/2 items-center justify-center rounded-full text-ink-soft transition-colors duration-150 hover:bg-tint hover:text-ink focus-visible:outline-2 focus-visible:outline-offset-0 focus-visible:outline-ink motion-reduce:transition-none"
+          >
+            <X aria-hidden="true" size={18} />
+          </button>
+        )}
+      </div>
+      {hint && (
+        <p id={hintId} className="mt-2 px-5 text-sm text-ink-soft">
+          {hint}
+        </p>
+      )}
+    </div>
+  );
+}

package/components/SelectField.tsx

@@ -0,0 +1,75 @@
+import type { ReactNode, SelectHTMLAttributes } from "react";
+import { ChevronDown } from "lucide-react";
+import { FIELD, FIELD_LABEL } from "./SearchField";
+
+export type SelectOption = {
+  value: string;
+  label: string;
+  /** Count shown after the label ("São Paulo (51)"). Native options only take text. */
+  count?: number;
+};
+
+export type SelectGroup = { label: string; options: SelectOption[] };
+
+type Props = Omit<SelectHTMLAttributes<HTMLSelectElement>, "value" | "onChange" | "children"> & {
+  id: string;
+  label: ReactNode;
+  value: string;
+  onValueChange: (value: string) => void;
+  /** The first option, value "": "Todos os estados". */
+  placeholder: string;
+  /** Flat options, or groups (`<optgroup>`): pass one or the other. */
+  options?: SelectOption[];
+  groups?: SelectGroup[];
+  /** Keep the label for screen readers only, when a group label above already says
+   *  what the fields are (and the placeholder names the field: "Todos os estados"). */
+  hideLabel?: boolean;
+  /** `md` (default): the 56px field. `sm`: a 40px pill for a filter bar (Apple-like).
+   *  (Not `size`: that is the native <select> attribute.) */
+  density?: "md" | "sm";
+  className?: string;
+};
+
+const text = (o: SelectOption) => (o.count === undefined ? o.label : `${o.label} (${o.count})`);
+
+/**
+ * SelectField — a native `<select>` dressed as the family's field (same pill,
+ * hairline and shadow as SearchField), with a lucide chevron. Native on
+ * purpose: on phones it opens the system picker, which is faster and more
+ * accessible than any custom listbox for a list of states or cities.
+ */
+export function SelectField({ id, label, value, onValueChange, placeholder, options, groups, hideLabel = false, density = "md", className = "", ...rest }: Props) {
+  return (
+    <div className={className}>
+      <label htmlFor={id} className={hideLabel ? "sr-only" : FIELD_LABEL}>
+        {label}
+      </label>
+      <div className="relative">
+        <select
+          id={id}
+          value={value}
+          onChange={(e) => onValueChange(e.target.value)}
+          className={`${FIELD} cursor-pointer appearance-none truncate ${density === "sm" ? "!min-h-10 py-2 pr-9 pl-4 text-sm font-medium" : "pr-12 pl-5"}`}
+          {...rest}
+        >
+          <option value="">{placeholder}</option>
+          {options?.map((o) => (
+            <option key={o.value} value={o.value}>
+              {text(o)}
+            </option>
+          ))}
+          {groups?.map((g) => (
+            <optgroup key={g.label} label={g.label}>
+              {g.options.map((o) => (
+                <option key={o.value} value={o.value}>
+                  {text(o)}
+                </option>
+              ))}
+            </optgroup>
+          ))}
+        </select>
+        <ChevronDown aria-hidden="true" size={density === "sm" ? 16 : 18} className={`pointer-events-none absolute top-1/2 -translate-y-1/2 text-ink-soft ${density === "sm" ? "right-3.5" : "right-5"}`} />
+      </div>
+    </div>
+  );
+}

package/components/SidePanel.tsx

@@ -34,7 +34,10 @@ export function SidePanel({ open, onClose, title, actions, children, labels, cla
   const box = useRef<HTMLDialogElement>(null);
   const headingId = useId();
 
-  // open/close follow the prop; the way out waits for the slide to finish
+  // open/close follow the prop; the way out waits for the slide to finish.
+  // Closed, the dialog is display:none (hidden open:flex): a plain `flex` would
+  // keep it rendered off-screen, its shadow bleeding into the right edge and its
+  // content reachable.
   useEffect(() => {
     const d = box.current;
     if (!d) return;
@@ -76,14 +79,14 @@ export function SidePanel({ open, onClose, title, actions, children, labels, cla
     <dialog
       ref={box}
       aria-labelledby={headingId}
-      className={`fixed inset-y-0 right-0 left-auto m-0 flex h-dvh max-h-none w-[min(100vw,32rem)] max-w-none translate-x-full flex-col overflow-hidden bg-card p-0 text-ink shadow-2xl [transition:translate_280ms_var(--ease-cg)] data-open:translate-x-0 motion-reduce:transition-none backdrop:bg-ink/50 backdrop:backdrop-blur-sm backdrop:opacity-0 backdrop:[transition:opacity_240ms_ease-out] [&[data-open]::backdrop]:opacity-100 ${className}`}
+      className={`fixed inset-y-0 right-0 left-auto m-0 hidden open:flex h-dvh max-h-none w-[min(100vw,32rem)] max-w-none translate-x-full flex-col overflow-hidden bg-card p-0 text-ink shadow-2xl [transition:translate_280ms_var(--ease-cg)] data-open:translate-x-0 motion-reduce:transition-none backdrop:bg-ink/50 backdrop:backdrop-blur-sm backdrop:opacity-0 backdrop:[transition:opacity_240ms_ease-out] [&[data-open]::backdrop]:opacity-100 ${className}`}
     >
       <h2 id={headingId} className="sr-only">{title}</h2>
       <div className="flex shrink-0 items-center justify-between gap-3 border-b border-ink/10 px-4 py-3">
         <button
           type="button"
           onClick={onClose}
-          className="flex h-11 w-11 items-center justify-center rounded-full text-ink transition-colors duration-150 hover:bg-ink/[0.06] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ink motion-reduce:transition-none"
+          className="flex h-11 w-11 items-center justify-center rounded-full text-ink transition-colors duration-150 hover:bg-tint focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ink motion-reduce:transition-none"
         >
           <X aria-hidden="true" size={20} strokeWidth={2} />
           <span className="sr-only">{t.close}</span>

package/components/StickyGroupHeading.tsx

@@ -0,0 +1,38 @@
+import type { ReactNode } from "react";
+
+type Props = {
+  children: ReactNode;
+  /** Lighter info after the title, e.g. the count ("51 profissionais"). */
+  meta?: ReactNode;
+  id?: string;
+  /** h2 by default; h3 inside a section that already has an h2. */
+  as?: "h2" | "h3";
+  /** Where it sticks: below the site's sticky header. Pass a literal Tailwind
+   *  class written in your source (`top-20` = an 80px header), so it gets generated. */
+  stickyTop?: string;
+  className?: string;
+};
+
+/**
+ * StickyGroupHeading — the title of a group in a long list that stays at the
+ * top while its items scroll by, and is pushed away by the next group's title
+ * (the section headers of Apple's lists, Contacts A–Z). Used on ttcab's
+ * professionals directory, one group per state.
+ *
+ * It sticks inside its own group: put it as the first child of the group's
+ * wrapper (a <section>), so the next wrapper pushes it out. The band bleeds
+ * 16/24px past the content so the hairline and the blurred page colour cover
+ * the cards passing under it; `surface` at 90% keeps the title at full
+ * contrast (ink on surface, 9.41:1 on ttcab) even without backdrop-filter.
+ */
+export function StickyGroupHeading({ children, meta, id, as: Tag = "h2", stickyTop = "top-20", className = "" }: Props) {
+  return (
+    <Tag
+      id={id}
+      className={`sticky ${stickyTop} z-10 -mx-4 flex items-baseline gap-3 border-b border-line bg-surface/90 px-4 py-3 font-heading text-xl font-medium text-ink backdrop-blur-md md:-mx-6 md:px-6 ${className}`}
+    >
+      {children}
+      {meta && <span className="text-sm font-normal text-ink-soft tabular-nums">{meta}</span>}
+    </Tag>
+  );
+}