import * as React from 'react';

/**
 * The heading every section of a page starts with.
 *
 * There used to be two treatments and no rule about which to use: the playground,
 * the matrices and the two tables drew `text-sm font-semibold`, while the pages
 * drew `t-h4`, so a component page was four sections with nothing marking where
 * one ended and the next began. The trailing hairline is what fixes that — it
 * reads as a divider without costing a heading level or a line of its own.
 *
 * The level stays `h2` at every call site. The classes carry the size, so the
 * document outline is free to be the correct one — a rule this site already
 * learned the hard way, from its own axe panel reporting the `h1` → `h3` jump on
 * every component page.
 *
 * `actions` sits after the rule rather than beside the title, so a row with a
 * button (copy-all on a grid, Share on the playground) and a row without one
 * still start their text at the same place.
 */
export function SectionHeading({
  title,
  description,
  actions,
  id,
}: {
  title: string;
  description?: string;
  /** Buttons pinned to the trailing edge — the rule stretches to meet them. */
  actions?: React.ReactNode;
  /** For `aria-labelledby` on a wrapping section, when one wants it. */
  id?: string;
}) {
  return (
    <div className="space-y-1">
      <div className="cbar-section-row">
        <h2 id={id} className="cbar-section">
          {/* The rule is the `h2`'s own `::after`, so it cannot be read as text
              or land in the accessible name — a `<hr>` here would be both. */}
          {/* `min-w-0` because a flex item defaults to `min-width:auto` and
              would refuse to shrink, pushing the rule off the row instead of
              ellipsing a long title. */}
          <span className="min-w-0 truncate">{title}</span>
        </h2>
        {actions}
      </div>
      {description ? (
        <p className="max-w-prose text-sm text-muted-foreground">{description}</p>
      ) : null}
    </div>
  );
}