@db-vincent/components 0.1.0 → 0.1.1

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/Select.astro

@@ -186,218 +186,235 @@ const display =
 </div>
 
 <script>
-  document.querySelectorAll<HTMLElement>("[data-ds-select]").forEach((root) => {
-    const trigger = root.querySelector<HTMLButtonElement>(
-      "[data-ds-select-trigger]",
-    );
-    const popup = root.querySelector<HTMLElement>("[data-ds-popup]");
-    const list = root.querySelector<HTMLElement>('[role="listbox"]');
-    const values = root.querySelector<HTMLElement>("[data-ds-values]");
-    const valueLabel = root.querySelector<HTMLElement>("[data-ds-value]");
-    const done = root.querySelector<HTMLButtonElement>("[data-ds-done]");
-    if (!trigger || !popup || !list || !valueLabel) return;
-
-    const multiple = root.dataset.multiple === "true";
-    const name = root.dataset.name || "";
-    const placeholder = root.dataset.placeholder || "Select an option";
-    const options = Array.from(
-      list.querySelectorAll<HTMLElement>('[role="option"]'),
-    );
-    let active = -1;
-
-    const selected = () =>
-      options.filter(
-        (option) => option.getAttribute("aria-selected") === "true",
-      );
+  const bind = () => {
+    document
+      .querySelectorAll<HTMLElement>("[data-ds-select]")
+      .forEach((root) => {
+        if (root.dataset.dsBound) return;
+        root.dataset.dsBound = "true";
+        const trigger = root.querySelector<HTMLButtonElement>(
+          "[data-ds-select-trigger]",
+        );
+        const popup = root.querySelector<HTMLElement>("[data-ds-popup]");
+        const list = root.querySelector<HTMLElement>('[role="listbox"]');
+        const values = root.querySelector<HTMLElement>("[data-ds-values]");
+        const valueLabel = root.querySelector<HTMLElement>("[data-ds-value]");
+        const done = root.querySelector<HTMLButtonElement>("[data-ds-done]");
+        if (!trigger || !popup || !list || !valueLabel) return;
 
-    const updateLabel = () => {
-      const chosen = selected();
-      valueLabel.textContent =
-        chosen.length === 0
-          ? placeholder
-          : chosen.length === 1
-            ? chosen[0].dataset.label || ""
-            : `${chosen.length} selected`;
-      trigger.classList.toggle("is-placeholder", chosen.length === 0);
-      trigger.title = chosen.map((option) => option.dataset.label).join(", ");
-    };
+        const multiple = root.dataset.multiple === "true";
+        const name = root.dataset.name || "";
+        const placeholder = root.dataset.placeholder || "Select an option";
+        const options = Array.from(
+          list.querySelectorAll<HTMLElement>('[role="option"]'),
+        );
+        let active = -1;
 
-    const syncValues = () => {
-      if (!values) return;
-      values.replaceChildren();
-      selected().forEach((option) => {
-        const input = document.createElement("input");
-        input.type = "hidden";
-        input.name = name;
-        input.value = option.dataset.value || "";
-        values.append(input);
-      });
-    };
+        const selected = () =>
+          options.filter(
+            (option) => option.getAttribute("aria-selected") === "true",
+          );
 
-    const enabled = (index: number) =>
-      options[index]?.getAttribute("aria-disabled") !== "true";
+        const updateLabel = () => {
+          const chosen = selected();
+          valueLabel.textContent =
+            chosen.length === 0
+              ? placeholder
+              : chosen.length === 1
+                ? chosen[0].dataset.label || ""
+                : `${chosen.length} selected`;
+          trigger.classList.toggle("is-placeholder", chosen.length === 0);
+          trigger.title = chosen
+            .map((option) => option.dataset.label)
+            .join(", ");
+        };
 
-    // Move from `from` in `direction`, skipping disabled options; stays put
-    // at either end.
-    const step = (from: number, direction: 1 | -1) => {
-      for (
-        let index = from + direction;
-        index >= 0 && index < options.length;
-        index += direction
-      ) {
-        if (enabled(index)) return index;
-      }
-      return active;
-    };
+        const syncValues = () => {
+          if (!values) return;
+          values.replaceChildren();
+          selected().forEach((option) => {
+            const input = document.createElement("input");
+            input.type = "hidden";
+            input.name = name;
+            input.value = option.dataset.value || "";
+            values.append(input);
+          });
+        };
 
-    const setActive = (index: number, focus = false) => {
-      if (!options.length) return;
-      active = Math.max(0, Math.min(options.length - 1, index));
-      options.forEach((option, position) =>
-        option.classList.toggle("is-active", position === active),
-      );
-      if (focus) options[active]?.focus();
-    };
+        const enabled = (index: number) =>
+          options[index]?.getAttribute("aria-disabled") !== "true";
 
-    const close = (focusTrigger = false) => {
-      popup.hidden = true;
-      trigger.setAttribute("aria-expanded", "false");
-      root.classList.remove("is-open");
-      if (focusTrigger) trigger.focus();
-    };
+        // Move from `from` in `direction`, skipping disabled options; stays put
+        // at either end.
+        const step = (from: number, direction: 1 | -1) => {
+          for (
+            let index = from + direction;
+            index >= 0 && index < options.length;
+            index += direction
+          ) {
+            if (enabled(index)) return index;
+          }
+          return active;
+        };
 
-    const open = () => {
-      if (trigger.disabled) return;
-      popup.hidden = false;
-      trigger.setAttribute("aria-expanded", "true");
-      root.classList.add("is-open");
-      const current = options.findIndex(
-        (option) => option.getAttribute("aria-selected") === "true",
-      );
-      setActive(current >= 0 ? current : step(-1, 1), true);
-    };
+        const setActive = (index: number, focus = false) => {
+          if (!options.length) return;
+          active = Math.max(0, Math.min(options.length - 1, index));
+          options.forEach((option, position) =>
+            option.classList.toggle("is-active", position === active),
+          );
+          if (focus) options[active]?.focus();
+        };
 
-    const choose = (option: HTMLElement) => {
-      if (option.getAttribute("aria-disabled") === "true") return;
-      if (multiple) {
-        option.setAttribute(
-          "aria-selected",
-          option.getAttribute("aria-selected") === "true" ? "false" : "true",
-        );
-      } else {
-        options.forEach((entry) =>
-          entry.setAttribute(
-            "aria-selected",
-            entry === option ? "true" : "false",
-          ),
-        );
-      }
-      syncValues();
-      updateLabel();
-      root.dispatchEvent(
-        new CustomEvent("change", {
-          bubbles: true,
-          detail: { values: selected().map((entry) => entry.dataset.value) },
-        }),
-      );
-      if (multiple) {
-        option.focus();
-      } else {
-        close(true);
-      }
-    };
+        const close = (focusTrigger = false) => {
+          popup.hidden = true;
+          trigger.setAttribute("aria-expanded", "false");
+          root.classList.remove("is-open");
+          if (focusTrigger) trigger.focus();
+        };
 
-    trigger.addEventListener("click", () => {
-      if (popup.hidden) open();
-      else close();
-    });
+        const open = () => {
+          if (trigger.disabled) return;
+          popup.hidden = false;
+          trigger.setAttribute("aria-expanded", "true");
+          root.classList.add("is-open");
+          const current = options.findIndex(
+            (option) => option.getAttribute("aria-selected") === "true",
+          );
+          setActive(current >= 0 ? current : step(-1, 1), true);
+        };
 
-    trigger.addEventListener("keydown", (event) => {
-      if (["ArrowDown", "ArrowUp", "Enter", " "].includes(event.key)) {
-        event.preventDefault();
-        if (popup.hidden) open();
-      }
-    });
+        const choose = (option: HTMLElement) => {
+          if (option.getAttribute("aria-disabled") === "true") return;
+          if (multiple) {
+            option.setAttribute(
+              "aria-selected",
+              option.getAttribute("aria-selected") === "true"
+                ? "false"
+                : "true",
+            );
+          } else {
+            options.forEach((entry) =>
+              entry.setAttribute(
+                "aria-selected",
+                entry === option ? "true" : "false",
+              ),
+            );
+          }
+          syncValues();
+          updateLabel();
+          root.dispatchEvent(
+            new CustomEvent("change", {
+              bubbles: true,
+              detail: {
+                values: selected().map((entry) => entry.dataset.value),
+              },
+            }),
+          );
+          if (multiple) {
+            option.focus();
+          } else {
+            close(true);
+          }
+        };
 
-    list.addEventListener("click", (event) => {
-      const option = (event.target as HTMLElement).closest<HTMLElement>(
-        '[role="option"]',
-      );
-      if (option) choose(option);
-    });
+        trigger.addEventListener("click", () => {
+          if (popup.hidden) open();
+          else close();
+        });
 
-    list.addEventListener("keydown", (event) => {
-      switch (event.key) {
-        case "ArrowDown":
-          event.preventDefault();
-          setActive(step(active, 1), true);
-          break;
-        case "ArrowUp":
-          event.preventDefault();
-          setActive(step(active, -1), true);
-          break;
-        case "Home":
-          event.preventDefault();
-          setActive(step(-1, 1), true);
-          break;
-        case "End":
-          event.preventDefault();
-          setActive(step(options.length, -1), true);
-          break;
-        case "Enter":
-        case " ":
-          event.preventDefault();
-          if (active >= 0) choose(options[active]);
-          break;
-        case "Escape":
-          event.preventDefault();
-          close(true);
-          break;
-        case "Tab":
-          // In multiple mode Tab reaches the Done button before leaving.
-          if (multiple && done && !event.shiftKey) {
+        trigger.addEventListener("keydown", (event) => {
+          if (["ArrowDown", "ArrowUp", "Enter", " "].includes(event.key)) {
             event.preventDefault();
-            done.focus();
-            break;
+            if (popup.hidden) open();
           }
-          close();
-          trigger.focus();
-          break;
-        default:
-          if (event.key.length === 1) {
-            const letter = event.key.toLowerCase();
-            // Wrap-search from the option after the active one; no match
-            // keeps the current option.
-            for (let offset = 1; offset <= options.length; offset += 1) {
-              const index = (active + offset) % options.length;
-              const label = (options[index].dataset.label || "").toLowerCase();
-              if (enabled(index) && label.startsWith(letter)) {
-                setActive(index, true);
+        });
+
+        list.addEventListener("click", (event) => {
+          const option = (event.target as HTMLElement).closest<HTMLElement>(
+            '[role="option"]',
+          );
+          if (option) choose(option);
+        });
+
+        list.addEventListener("keydown", (event) => {
+          switch (event.key) {
+            case "ArrowDown":
+              event.preventDefault();
+              setActive(step(active, 1), true);
+              break;
+            case "ArrowUp":
+              event.preventDefault();
+              setActive(step(active, -1), true);
+              break;
+            case "Home":
+              event.preventDefault();
+              setActive(step(-1, 1), true);
+              break;
+            case "End":
+              event.preventDefault();
+              setActive(step(options.length, -1), true);
+              break;
+            case "Enter":
+            case " ":
+              event.preventDefault();
+              if (active >= 0) choose(options[active]);
+              break;
+            case "Escape":
+              event.preventDefault();
+              close(true);
+              break;
+            case "Tab":
+              // In multiple mode Tab reaches the Done button before leaving.
+              if (multiple && done && !event.shiftKey) {
+                event.preventDefault();
+                done.focus();
                 break;
               }
-            }
+              close();
+              trigger.focus();
+              break;
+            default:
+              if (event.key.length === 1) {
+                const letter = event.key.toLowerCase();
+                // Wrap-search from the option after the active one; no match
+                // keeps the current option.
+                for (let offset = 1; offset <= options.length; offset += 1) {
+                  const index = (active + offset) % options.length;
+                  const label = (
+                    options[index].dataset.label || ""
+                  ).toLowerCase();
+                  if (enabled(index) && label.startsWith(letter)) {
+                    setActive(index, true);
+                    break;
+                  }
+                }
+              }
           }
-      }
-    });
+        });
 
-    done?.addEventListener("click", () => close(true));
-    done?.addEventListener("keydown", (event) => {
-      if (event.key === "Escape") {
-        event.preventDefault();
-        close(true);
-      } else if (event.key === "Tab" && event.shiftKey) {
-        event.preventDefault();
-        setActive(active, true);
-      } else if (event.key === "Tab") {
-        close();
-      }
-    });
+        done?.addEventListener("click", () => close(true));
+        done?.addEventListener("keydown", (event) => {
+          if (event.key === "Escape") {
+            event.preventDefault();
+            close(true);
+          } else if (event.key === "Tab" && event.shiftKey) {
+            event.preventDefault();
+            setActive(active, true);
+          } else if (event.key === "Tab") {
+            close();
+          }
+        });
 
-    document.addEventListener("pointerdown", (event) => {
-      if (!popup.hidden && !root.contains(event.target as Node)) close();
-    });
+        document.addEventListener("pointerdown", (event) => {
+          if (!popup.hidden && !root.contains(event.target as Node)) close();
+        });
+
+        syncValues();
+        updateLabel();
+      });
+  };
 
-    syncValues();
-    updateLabel();
-  });
+  bind();
+  document.addEventListener("astro:page-load", bind);
 </script>

package/src/astro/Skeleton.astro

@@ -18,13 +18,15 @@ const {
   width,
   class: className,
 } = Astro.props;
+const safeWidth =
+  width && /^\d+(\.\d+)?(rem|em|px|%|ch|vw)$/.test(width) ? width : undefined;
 ---
 
 {variant === "paragraph" ? (
   <div
     class:list={["ds-skeleton-stack", className]}
     aria-hidden="true"
-    style={width ? `width:${width}` : undefined}
+    style={safeWidth ? `width:${safeWidth}` : undefined}
   >
     {Array.from({ length: lines }).map(() => (
       <span class="ds-skeleton ds-skeleton--text"></span>
@@ -34,6 +36,6 @@ const {
   <span
     class:list={["ds-skeleton", `ds-skeleton--${variant}`, className]}
     aria-hidden="true"
-    style={width ? `width:${width}` : undefined}
+    style={safeWidth ? `width:${safeWidth}` : undefined}
   ></span>
 )}

package/src/astro/Spinner.astro

@@ -1,4 +1,5 @@
 ---
+import "../styles/sr-only.css";
 import "../styles/spinner.css";
 
 /** Loading spinner. Announces through a visually hidden status, not motion. */

package/src/astro/Stepper.astro

@@ -0,0 +1,82 @@
+---
+import Icon from "./Icon.astro";
+import "../styles/stepper.css";
+import "../styles/sr-only.css";
+
+/**
+ * Progress through an ordered process. Presentational: an <ol> where the
+ * current step carries aria-current="step". State is shown by marker shape
+ * (number, check, cross) and read out as visually hidden text, never by
+ * colour alone.
+ */
+interface Step {
+  label: string;
+  description?: string;
+  state?: "complete" | "current" | "upcoming" | "error";
+}
+
+interface Props {
+  steps: Step[];
+  orientation?: "horizontal" | "vertical";
+  /** Accessible name for the list, e.g. "Setup progress". */
+  label?: string;
+  class?: string;
+}
+
+const {
+  steps,
+  orientation = "horizontal",
+  label,
+  class: className,
+} = Astro.props;
+
+const STATE_TEXT = {
+  complete: "Completed",
+  error: "Error",
+  upcoming: "Not started",
+  current: "",
+};
+---
+
+<ol
+  class:list={[
+    "ds-stepper",
+    orientation === "vertical" && "ds-stepper--vertical",
+    className,
+  ]}
+  aria-label={label}
+>
+  {steps.map((step, index) => {
+    const state = step.state ?? "upcoming";
+    return (
+      <li
+        class="ds-stepper__item"
+        data-state={state}
+        aria-current={state === "current" ? "step" : undefined}
+      >
+        <span class="ds-stepper__marker" aria-hidden="true">
+          {state === "complete" ? (
+            <Icon name="check" size={16} />
+          ) : state === "error" ? (
+            <Icon name="x" size={16} />
+          ) : (
+            index + 1
+          )}
+        </span>
+        <span class="ds-stepper__body">
+          <span class="ds-stepper__label">
+            {step.label}
+            {STATE_TEXT[state] && (
+              <span class="ds-sr-only">
+                , {STATE_TEXT[state].toLowerCase()}
+              </span>
+            )}
+          </span>
+          {step.description && (
+            <span class="ds-stepper__description">{step.description}</span>
+          )}
+        </span>
+      </li>
+    );
+  })}
+</ol>