@db-vincent/components 0.0.0-stage → 0.1.1

package/src/astro/PageHeader.astro

@@ -0,0 +1,34 @@
+---
+import "../styles/page-header.css";
+
+/**
+ * Page header. One h1, an optional lede, metadata and actions. There is no
+ * eyebrow: the breadcrumb in the navbar already says where the page sits.
+ * `display` is for the single landing page per site, not for every route.
+ */
+interface Props {
+  title?: string;
+  lede?: string;
+  display?: boolean;
+  class?: string;
+}
+
+const { title, lede, display = false, class: className } = Astro.props;
+---
+
+<header
+  class:list={[
+    "ds-page-header",
+    display && "ds-page-header--display",
+    className,
+  ]}
+>
+  <h1 class="ds-page-header__title">{title ?? <slot name="title" />}</h1>
+  <p class="ds-page-header__lede">{lede ?? <slot name="lede" />}</p>
+  <div class="ds-page-header__meta">
+    <slot name="meta" />
+  </div>
+  <div class="ds-page-header__actions">
+    <slot name="actions" />
+  </div>
+</header>

package/src/astro/Pagination.astro

@@ -0,0 +1,212 @@
+---
+import Icon from "./Icon.astro";
+import "../styles/pagination.css";
+
+interface Props {
+  current: number;
+  total: number;
+  href?: string;
+  label?: string;
+  interactive?: boolean;
+  class?: string;
+}
+
+const {
+  current,
+  total,
+  href = "?page={page}",
+  label = "Pagination",
+  interactive = false,
+  class: className,
+} = Astro.props;
+
+const urlFor = (page: number) => href.replace("{page}", String(page));
+
+type PageToken = number | "ellipsis-start" | "ellipsis-end";
+const tokens: PageToken[] = [];
+if (total <= 7) {
+  for (let page = 1; page <= total; page++) tokens.push(page);
+} else {
+  tokens.push(1);
+  if (current > 4) tokens.push("ellipsis-start");
+  const start = Math.max(2, current - 1);
+  const end = Math.min(total - 1, current + 1);
+  for (let page = start; page <= end; page++) tokens.push(page);
+  if (current < total - 3) tokens.push("ellipsis-end");
+  tokens.push(total);
+}
+
+const Tag = interactive ? "button" : "a";
+const pageProps = (page: number) =>
+  interactive
+    ? { type: "button" as const, "data-page": page }
+    : { href: urlFor(page), "data-page": page };
+---
+
+<nav
+  class:list={[
+    "ds-pagination",
+    interactive && "ds-pagination--interactive",
+    className,
+  ]}
+  aria-label={label}
+  data-pagination-interactive={interactive ? "true" : undefined}
+  data-total={total}
+  data-current={current}
+>
+  <ul class="ds-pagination__list">
+    <li>
+      <Tag
+        class="ds-pagination__link ds-pagination__link--direction"
+        {...pageProps(current - 1)}
+        aria-disabled={current <= 1 ? "true" : undefined}
+        disabled={interactive && current <= 1 ? true : undefined}
+        data-direction="prev"
+        rel={interactive ? undefined : "prev"}
+      >
+        <Icon name="chevron-left" size={14} />
+        <span class="ds-pagination__label">Previous</span>
+      </Tag>
+    </li>
+    {tokens.map((token) =>
+      typeof token === "number" ? (
+        <li data-token>
+          <Tag
+            class="ds-pagination__link"
+            {...pageProps(token)}
+            aria-current={token === current ? "page" : undefined}
+            aria-label={`Page ${token}`}
+          >
+            {token}
+          </Tag>
+        </li>
+      ) : (
+        <li data-token>
+          <span class="ds-pagination__ellipsis" aria-hidden="true">
+            …
+          </span>
+        </li>
+      ),
+    )}
+    <li>
+      <Tag
+        class="ds-pagination__link ds-pagination__link--direction"
+        {...pageProps(current + 1)}
+        aria-disabled={current >= total ? "true" : undefined}
+        disabled={interactive && current >= total ? true : undefined}
+        data-direction="next"
+        rel={interactive ? undefined : "next"}
+      >
+        <span class="ds-pagination__label">Next</span>
+        <Icon name="chevron-right" size={14} />
+      </Tag>
+    </li>
+  </ul>
+</nav>
+
+<script>
+  type PageToken = number | "ellipsis-start" | "ellipsis-end";
+
+  // Same windowing as the server render in the frontmatter.
+  const buildTokens = (current: number, total: number): PageToken[] => {
+    const tokens: PageToken[] = [];
+    if (total <= 7) {
+      for (let page = 1; page <= total; page++) tokens.push(page);
+      return tokens;
+    }
+    tokens.push(1);
+    if (current > 4) tokens.push("ellipsis-start");
+    const start = Math.max(2, current - 1);
+    const end = Math.min(total - 1, current + 1);
+    for (let page = start; page <= end; page++) tokens.push(page);
+    if (current < total - 3) tokens.push("ellipsis-end");
+    tokens.push(total);
+    return tokens;
+  };
+
+  const renderToken = (token: PageToken, current: number): HTMLLIElement => {
+    const item = document.createElement("li");
+    item.dataset.token = "";
+    if (typeof token !== "number") {
+      const ellipsis = document.createElement("span");
+      ellipsis.className = "ds-pagination__ellipsis";
+      ellipsis.setAttribute("aria-hidden", "true");
+      ellipsis.textContent = "\u2026";
+      item.append(ellipsis);
+      return item;
+    }
+    const button = document.createElement("button");
+    button.type = "button";
+    button.className = "ds-pagination__link";
+    button.dataset.page = String(token);
+    button.setAttribute("aria-label", `Page ${token}`);
+    if (token === current) button.setAttribute("aria-current", "page");
+    button.textContent = String(token);
+    item.append(button);
+    return item;
+  };
+
+  const render = (nav: HTMLElement, page: number) => {
+    const total = Number(nav.dataset.total);
+    nav.dataset.current = String(page);
+    const previous = nav.querySelector<HTMLButtonElement>(
+      '[data-direction="prev"]',
+    );
+    const next = nav.querySelector<HTMLButtonElement>(
+      '[data-direction="next"]',
+    );
+    const nextItem = next?.closest("li");
+    if (!previous || !next || !nextItem) return;
+
+    const hadFocus = nav.contains(document.activeElement);
+    nav.querySelectorAll("li[data-token]").forEach((item) => item.remove());
+    buildTokens(page, total).forEach((token) =>
+      nextItem.before(renderToken(token, page)),
+    );
+
+    previous.dataset.page = String(Math.max(1, page - 1));
+    previous.disabled = page <= 1;
+    previous.setAttribute("aria-disabled", page <= 1 ? "true" : "false");
+    next.dataset.page = String(Math.min(total, page + 1));
+    next.disabled = page >= total;
+    next.setAttribute("aria-disabled", page >= total ? "true" : "false");
+
+    // Page buttons are re-created and a direction button can become
+    // disabled; hand focus to the current page when the control is gone.
+    const focused = document.activeElement;
+    const stillUsable =
+      focused instanceof HTMLButtonElement &&
+      nav.contains(focused) &&
+      !focused.disabled;
+    if (hadFocus && !stillUsable) {
+      nav.querySelector<HTMLElement>('[aria-current="page"]')?.focus();
+    }
+  };
+
+  const bind = () => {
+    document
+      .querySelectorAll<HTMLElement>("[data-pagination-interactive]")
+      .forEach((nav) => {
+        if (nav.dataset.bound) return;
+        nav.dataset.bound = "true";
+        nav.addEventListener("click", (event) => {
+          const control = (event.target as HTMLElement).closest<HTMLElement>(
+            "[data-page]",
+          );
+          if (!control || control.hasAttribute("disabled")) return;
+          event.preventDefault();
+          const page = Number(control.dataset.page);
+          render(nav, page);
+          nav.dispatchEvent(
+            new CustomEvent("page-change", {
+              bubbles: true,
+              detail: { page },
+            }),
+          );
+        });
+      });
+  };
+
+  bind();
+  document.addEventListener("astro:page-load", bind);
+</script>

package/src/astro/Popover.astro

@@ -0,0 +1,51 @@
+---
+import Button from "./Button.astro";
+import "../styles/popover.css";
+
+/**
+ * Popover on the native `popover` attribute. The trigger's `popovertarget`
+ * supplies toggling, light dismiss, Escape and focus return, so no script is
+ * needed. Placement uses CSS anchor positioning and flips near the viewport
+ * edge. For a list of commands use Menu; for a hint use Tooltip.
+ */
+interface Props {
+  /** Accessible name for the surface. */
+  label: string;
+  triggerLabel?: string;
+  triggerVariant?: "primary" | "secondary" | "ghost" | "danger";
+  placement?: "top" | "bottom" | "start" | "end";
+  id?: string;
+  class?: string;
+}
+
+const {
+  label,
+  triggerLabel = "Open",
+  triggerVariant = "secondary",
+  placement = "bottom",
+  id,
+  class: className,
+} = Astro.props;
+
+const surfaceId = id ?? `popover-${Math.random().toString(36).slice(2, 9)}`;
+---
+
+<span class="ds-anchor">
+  <Button
+    variant={triggerVariant}
+    type="button"
+    popovertarget={surfaceId}
+    aria-haspopup="dialog"
+  >
+    {triggerLabel}
+  </Button>
+  <div
+    class:list={["ds-popover", `ds-popover--${placement}`, className]}
+    id={surfaceId}
+    popover="auto"
+    role="dialog"
+    aria-label={label}
+  >
+    <slot />
+  </div>
+</span>

package/src/astro/Progress.astro

@@ -0,0 +1,71 @@
+---
+import "../styles/progress.css";
+
+/**
+ * Progress bar. Determinate when `value` is set, indeterminate otherwise.
+ * Uses role="progressbar" rather than <progress> so the bar can animate with
+ * a transform and fall back to a static bar under reduced motion.
+ */
+interface Props {
+  label: string;
+  /** Current value, 0 to `max`. Omit for an indeterminate wait. */
+  value?: number;
+  max?: number;
+  /** Overrides the visible and announced value, e.g. "3 of 5 files". */
+  valueText?: string;
+  tone?: "accent" | "success" | "warning" | "danger";
+  size?: "sm" | "md";
+  id?: string;
+  class?: string;
+}
+
+const {
+  label,
+  value,
+  max = 100,
+  valueText,
+  tone = "accent",
+  size = "md",
+  id,
+  class: className,
+} = Astro.props;
+
+const labelId = `${id ?? `progress-${Math.random().toString(36).slice(2, 9)}`}-label`;
+const determinate = value !== undefined;
+const clamped = determinate ? Math.min(Math.max(value, 0), max) : 0;
+const fraction = max > 0 ? clamped / max : 0;
+const text =
+  valueText ?? (determinate ? `${Math.round(fraction * 100)}%` : undefined);
+---
+
+<div
+  class:list={[
+    "ds-progress",
+    tone !== "accent" && `ds-progress--${tone}`,
+    size !== "md" && `ds-progress--${size}`,
+    !determinate && "ds-progress--indeterminate",
+    className,
+  ]}
+  id={id}
+>
+  <div class="ds-progress__head">
+    <span class="ds-progress__label" id={labelId}>
+      {label}
+    </span>
+    {text && <span class="ds-progress__value">{text}</span>}
+  </div>
+  <div
+    class="ds-progress__track"
+    role="progressbar"
+    aria-labelledby={labelId}
+    aria-valuemin="0"
+    aria-valuemax={max}
+    aria-valuenow={determinate ? clamped : undefined}
+    aria-valuetext={text}
+  >
+    <div
+      class="ds-progress__bar"
+      style={determinate ? `--ds-progress-value: ${fraction}` : undefined}
+    ></div>
+  </div>
+</div>

package/src/astro/Radio.astro

@@ -0,0 +1,58 @@
+---
+import "../styles/choice.css";
+
+/** Radio. Wrap a set in RadioGroup for a native fieldset and legend. */
+interface Props {
+  label: string;
+  description?: string;
+  id?: string;
+  name: string;
+  value: string;
+  checked?: boolean;
+  disabled?: boolean;
+  required?: boolean;
+  class?: string;
+}
+
+const {
+  label,
+  description,
+  id,
+  name,
+  value,
+  checked = false,
+  disabled = false,
+  required = false,
+  class: className,
+} = Astro.props;
+
+const inputId = id ?? `radio-${Math.random().toString(36).slice(2, 9)}`;
+const descriptionId = description ? `${inputId}-description` : undefined;
+// The name comes from the label text only; the description is announced
+// once, as a description, instead of twice (name + description).
+const labelId = `${inputId}-label`;
+---
+
+<label class:list={["ds-choice", "ds-choice--radio", className]}>
+  <input
+    class="ds-choice__input"
+    id={inputId}
+    type="radio"
+    name={name}
+    value={value}
+    checked={checked}
+    disabled={disabled}
+    required={required}
+    aria-labelledby={description ? labelId : undefined}
+    aria-describedby={descriptionId}
+  />
+  <span class="ds-choice__box" aria-hidden="true"></span>
+  <span class="ds-choice__label">
+    <span id={labelId}>{label}</span>
+    {description && (
+      <span class="ds-choice__description" id={descriptionId}>
+        {description}
+      </span>
+    )}
+  </span>
+</label>

package/src/astro/RadioGroup.astro

@@ -0,0 +1,25 @@
+---
+import "../styles/choice.css";
+
+/** Native fieldset/legend grouping for radios or checkboxes. */
+interface Props {
+  legend: string;
+  hint?: string;
+  class?: string;
+}
+
+const { legend, hint, class: className } = Astro.props;
+const hintId = hint
+  ? `group-${Math.random().toString(36).slice(2, 9)}-hint`
+  : undefined;
+---
+
+<fieldset class:list={["ds-choice-group", className]} aria-describedby={hintId}>
+  <legend class="ds-choice-group__legend">{legend}</legend>
+  {hint && (
+    <p class="ds-choice-group__hint" id={hintId}>
+      {hint}
+    </p>
+  )}
+  <slot />
+</fieldset>

package/src/astro/Section.astro

@@ -0,0 +1,25 @@
+---
+import "../styles/section.css";
+
+/** Numbered documentation section: heading, mono index and optional intro. */
+interface Props {
+  title: string;
+  id: string;
+  index?: string;
+  intro?: string;
+  class?: string;
+}
+
+const { title, id, index, intro, class: className } = Astro.props;
+---
+
+<section class:list={["ds-section", className]} aria-labelledby={id}>
+  <div class="ds-section__head">
+    <h2 class="ds-section__title" id={id}>
+      {title}
+    </h2>
+    {index && <span class="ds-section__index">{index}</span>}
+  </div>
+  {intro && <p class="ds-section__intro">{intro}</p>}
+  <slot />
+</section>