@db-vincent/components 0.0.0-stage → 0.1.1

package/src/astro/TextField.astro

@@ -0,0 +1,305 @@
+---
+import Icon from "./Icon.astro";
+import "../styles/sr-only.css";
+import "../styles/input.css";
+
+/**
+ * Text field. Label above, hint and count below, error replaces the hint.
+ * Hint and error are wired through aria-describedby; invalid sets
+ * aria-invalid. `validate` adds native constraint validation on blur, with
+ * live recovery while typing. Password fields get a reveal toggle, and
+ * counters update as the value changes.
+ */
+interface Props {
+  label?: string;
+  id?: string;
+  name?: string;
+  type?: string;
+  value?: string;
+  placeholder?: string;
+  hint?: string;
+  error?: string;
+  valid?: boolean;
+  validate?: boolean;
+  disabled?: boolean;
+  required?: boolean;
+  optional?: boolean;
+  multiline?: boolean;
+  rows?: number;
+  /** Multiline only. Which way the user can drag the handle. */
+  resize?: "none" | "vertical" | "both";
+  maxlength?: number;
+  minlength?: number;
+  pattern?: string;
+  count?: boolean;
+  size?: "sm" | "md" | "lg";
+  autocomplete?: string;
+  inputmode?:
+    "text" | "numeric" | "decimal" | "email" | "tel" | "search" | "url";
+  class?: string;
+}
+
+const {
+  label,
+  id,
+  name,
+  type = "text",
+  value,
+  placeholder,
+  hint,
+  error,
+  valid = false,
+  validate = false,
+  disabled = false,
+  required = false,
+  optional = false,
+  multiline = false,
+  rows = 3,
+  resize = "vertical",
+  maxlength,
+  minlength,
+  pattern,
+  count = false,
+  size = "md",
+  autocomplete,
+  inputmode,
+  class: className,
+} = Astro.props;
+
+const fieldId = id ?? `field-${Math.random().toString(36).slice(2, 9)}`;
+const hintId = `${fieldId}-hint`;
+const errorId = `${fieldId}-error`;
+const describedby =
+  [hint && (!error || validate) && hintId, (error || validate) && errorId]
+    .filter(Boolean)
+    .join(" ") || undefined;
+const current = value ?? "";
+const isPassword = !multiline && type === "password";
+const inputClass = [
+  "ds-input",
+  size !== "md" && `ds-input--${size}`,
+  multiline && resize !== "vertical" && `ds-input--resize-${resize}`,
+  error && "is-invalid",
+  valid && !error && "is-valid",
+  valid && !error && "ds-input--with-state",
+]
+  .filter(Boolean)
+  .join(" ");
+---
+
+<div
+  class:list={["ds-field", isPassword && "ds-field--reveal", className]}
+  data-ds-field
+  data-message={error}
+>
+  {label && (
+    <label class="ds-field__label" for={fieldId}>
+      {label}
+      {optional && <span class="ds-field__optional"> (optional)</span>}
+      {required && (
+        <span class="ds-field__required" aria-hidden="true">
+          {" "}
+          *
+        </span>
+      )}
+    </label>
+  )}
+
+  <div class="ds-field__control">
+    {multiline ? (
+      <textarea
+        class={inputClass}
+        id={fieldId}
+        name={name}
+        rows={rows}
+        placeholder={placeholder}
+        disabled={disabled}
+        required={required}
+        maxlength={maxlength}
+        minlength={minlength}
+        aria-invalid={error ? "true" : undefined}
+        aria-describedby={describedby}
+        autocomplete={autocomplete}
+      >{current}</textarea>
+    ) : (
+      <input
+        class={inputClass}
+        id={fieldId}
+        name={name}
+        type={type}
+        value={value}
+        placeholder={placeholder}
+        disabled={disabled}
+        required={required}
+        maxlength={maxlength}
+        minlength={minlength}
+        pattern={pattern}
+        inputmode={inputmode}
+        autocomplete={autocomplete}
+        aria-invalid={error ? "true" : undefined}
+        aria-describedby={describedby}
+      />
+    )}
+    {valid && !error && (
+      <>
+        <span class="ds-field__state" aria-hidden="true">
+          <Icon name="check" size={14} />
+        </span>
+        <span class="ds-sr-only">Valid.</span>
+      </>
+    )}
+    {isPassword && (
+      <button
+        class="ds-field__reveal"
+        type="button"
+        data-ds-reveal
+        aria-label="Show password"
+        aria-pressed="false"
+        aria-controls={fieldId}
+        disabled={disabled}
+      >
+        <span data-ds-reveal-show aria-hidden="true">
+          <Icon name="eye" size={16} />
+        </span>
+        <span data-ds-reveal-hide aria-hidden="true" hidden>
+          <Icon name="eye-off" size={16} />
+        </span>
+      </button>
+    )}
+  </div>
+
+  {((error && !validate) || (hint && (!error || validate))) && (
+    <div
+      class:list={[error && !validate ? "ds-field__error" : "ds-field__hint"]}
+      id={error && !validate ? errorId : hintId}
+    >
+      {error && !validate && <Icon name="alert-circle" size={14} />}
+      {error && !validate ? error : hint}
+    </div>
+  )}
+
+  {count && maxlength && (
+    <>
+      <span class="ds-field__count" data-ds-count>
+        {current.length} / {maxlength}
+      </span>
+      <span class="ds-sr-only" aria-live="polite" data-ds-count-live></span>
+    </>
+  )}
+
+  {validate && (
+    <div class="ds-field__error" id={errorId} data-ds-error hidden={!error}>
+      <Icon name="alert-circle" size={14} />
+      <span data-ds-error-text>{error || "Check this field."}</span>
+    </div>
+  )}
+</div>
+
+<script>
+  const bind = () => {
+    const fields = document.querySelectorAll<HTMLElement>("[data-ds-field]");
+
+    fields.forEach((field) => {
+      if (field.dataset.dsBound) return;
+      field.dataset.dsBound = "true";
+      const input = field.querySelector<HTMLInputElement | HTMLTextAreaElement>(
+        ".ds-input",
+      );
+      const count = field.querySelector<HTMLElement>("[data-ds-count]");
+      const countLive = field.querySelector<HTMLElement>(
+        "[data-ds-count-live]",
+      );
+      const error = field.querySelector<HTMLElement>("[data-ds-error]");
+      const errorText = field.querySelector<HTMLElement>(
+        "[data-ds-error-text]",
+      );
+      const hint = field.querySelector<HTMLElement>(".ds-field__hint");
+      if (!input) return;
+
+      if (count && input.maxLength > 0) {
+        // The visible counter updates silently; screen readers only hear it
+        // near the limit, not on every keystroke.
+        const updateCount = () => {
+          count.textContent = `${input.value.length} / ${input.maxLength}`;
+          const left = input.maxLength - input.value.length;
+          if (countLive) {
+            countLive.textContent =
+              left <= 5
+                ? `${left} ${left === 1 ? "character" : "characters"} left`
+                : "";
+          }
+        };
+        input.addEventListener("input", updateCount);
+        updateCount();
+      }
+
+      if (!error || !errorText) return;
+
+      const message = () => {
+        if (input.validity.valueMissing) {
+          return input.dataset.requiredMessage || "This field is required.";
+        }
+        if (input.validity.tooShort) {
+          return `Use at least ${input.minLength} characters.`;
+        }
+        if (input.validity.patternMismatch) {
+          return field.dataset.message || "Use the requested format.";
+        }
+        if (input.validity.typeMismatch) {
+          return "Enter a valid value.";
+        }
+        if (input.validity.tooLong) {
+          return `Use at most ${input.maxLength} characters.`;
+        }
+        return "";
+      };
+
+      const apply = (invalid: boolean, text: string) => {
+        input.classList.toggle("is-invalid", invalid);
+        if (invalid) {
+          input.setAttribute("aria-invalid", "true");
+        } else {
+          input.removeAttribute("aria-invalid");
+        }
+        error.hidden = !invalid;
+        errorText.textContent = text;
+        if (hint) hint.hidden = invalid;
+      };
+
+      const validate = () => {
+        const text = message();
+        apply(!!text, text);
+      };
+
+      input.addEventListener("blur", validate);
+      input.addEventListener("input", () => {
+        if (input.getAttribute("aria-invalid") === "true") validate();
+      });
+    });
+
+    document
+      .querySelectorAll<HTMLElement>("[data-ds-reveal]")
+      .forEach((button) => {
+        if (button.dataset.dsBound) return;
+        button.dataset.dsBound = "true";
+        const field = button.closest("[data-ds-field]");
+        const input = field?.querySelector<HTMLInputElement>(".ds-input");
+        if (!input) return;
+        const show = button.querySelector<HTMLElement>("[data-ds-reveal-show]");
+        const hide = button.querySelector<HTMLElement>("[data-ds-reveal-hide]");
+
+        button.addEventListener("click", () => {
+          const revealed = input.type === "text";
+          input.type = revealed ? "password" : "text";
+          // Stable name, state in aria-pressed: "Show password, pressed".
+          button.setAttribute("aria-pressed", revealed ? "false" : "true");
+          if (show) show.hidden = !revealed;
+          if (hide) hide.hidden = revealed;
+          input.focus({ preventScroll: true });
+        });
+      });
+  };
+
+  bind();
+  document.addEventListener("astro:page-load", bind);
+</script>

package/src/astro/ThemeToggle.astro

@@ -0,0 +1,66 @@
+---
+import Icon from "./Icon.astro";
+import Button from "./Button.astro";
+import "../styles/theme-toggle.css";
+
+/** Light/dark switch. Persists the choice and follows the OS until then. */
+interface Props {
+  class?: string;
+}
+
+const { class: className } = Astro.props;
+---
+
+<Button
+  variant="ghost"
+  iconOnly
+  ariaLabel="Switch color theme"
+  class:list={["ds-theme-toggle", className]}
+  data-theme-toggle
+>
+  <span class="ds-theme-toggle__sun" aria-hidden="true">
+    <Icon name="sun" size={16} />
+  </span>
+  <span class="ds-theme-toggle__moon" aria-hidden="true">
+    <Icon name="moon" size={16} />
+  </span>
+</Button>
+
+<script>
+  const root = document.documentElement;
+  const query = window.matchMedia("(prefers-color-scheme: dark)");
+  const current = () =>
+    root.dataset.theme ?? (query.matches ? "dark" : "light");
+
+  const sync = () => {
+    const theme = current();
+    document
+      .querySelectorAll<HTMLElement>("[data-theme-toggle]")
+      .forEach((button) => {
+        button.setAttribute(
+          "aria-label",
+          `Switch to ${theme === "dark" ? "light" : "dark"} theme`,
+        );
+      });
+  };
+
+  const apply = (theme: "light" | "dark") => {
+    root.dataset.theme = theme;
+    try {
+      localStorage.setItem("minerva-theme", theme);
+    } catch {}
+    sync();
+  };
+
+  document
+    .querySelectorAll<HTMLElement>("[data-theme-toggle]")
+    .forEach((button) => {
+      if (button.dataset.bound) return;
+      button.dataset.bound = "true";
+      button.addEventListener("click", () =>
+        apply(current() === "dark" ? "light" : "dark"),
+      );
+    });
+  query.addEventListener("change", sync);
+  sync();
+</script>

package/src/astro/Toast.astro

@@ -0,0 +1,181 @@
+---
+import Icon from "./Icon.astro";
+import Button from "./Button.astro";
+import "../styles/toast.css";
+
+/**
+ * Toast. A transient message on a raised neutral popover surface, shaped after
+ * shadcn/ui: neutral card, type icon, inline action and close. `danger` (alias
+ * `error`) and `warning` are assertive, the rest are polite.
+ *
+ * With `triggerLabel` the component renders a real button and a template; the
+ * button mounts the toast into one shared bottom-end region. For imperative
+ * use, import `toast` from `@db-vincent/components/scripts/toast` and call
+ * `toast.add`, `toast.close` or `toast.promise`.
+ */
+interface Props {
+  tone?: "info" | "success" | "warning" | "danger" | "error" | "loading";
+  type?: "info" | "success" | "warning" | "danger" | "error" | "loading";
+  title: string;
+  message?: string;
+  description?: string;
+  dismissible?: boolean;
+  icon?: boolean;
+  triggerLabel?: string;
+  triggerVariant?: "primary" | "secondary" | "ghost" | "danger";
+  /** Auto-dismiss delay for the mounted toast, in milliseconds. 0 keeps it. */
+  duration?: number;
+  id?: string;
+  class?: string;
+}
+
+const {
+  tone: toneProp,
+  type: typeProp,
+  title,
+  message,
+  description,
+  dismissible = true,
+  icon = true,
+  triggerLabel,
+  triggerVariant = "secondary",
+  duration = 5000,
+  id,
+  class: className,
+} = Astro.props;
+
+const requested = typeProp ?? toneProp ?? "info";
+const tone = requested === "error" ? "danger" : requested;
+const role = tone === "danger" || tone === "warning" ? "alert" : "status";
+const live = role === "alert" ? "assertive" : "polite";
+const iconName = {
+  info: "info",
+  success: "check-circle",
+  warning: "alert-triangle",
+  danger: "alert-circle",
+  loading: "loader",
+}[tone];
+const body = description ?? message;
+const toastId = id ?? `toast-${Math.random().toString(36).slice(2, 9)}`;
+const hasActions = Astro.slots.has("actions");
+const classes = ["ds-toast", `ds-toast--${tone}`, className]
+  .filter(Boolean)
+  .join(" ");
+---
+
+{triggerLabel ? (
+  <>
+    <Button variant={triggerVariant} type="button" data-toast-trigger={toastId}>
+      {triggerLabel}
+    </Button>
+    <template id={`${toastId}-template`}>
+      <div
+        class={classes}
+        id={toastId}
+        role={role}
+        aria-live={live}
+        aria-atomic="true"
+        data-toast
+        data-toast-type={tone}
+        data-toast-duration={duration}
+      >
+        {icon && (
+          <span class="ds-toast__icon" aria-hidden="true">
+            <Icon name={iconName} size={16} />
+          </span>
+        )}
+        <div class="ds-toast__content">
+          <p class="ds-toast__title">{title}</p>
+          {body && <p class="ds-toast__body">{body}</p>}
+          <slot />
+        </div>
+        {hasActions && (
+          <div class="ds-toast__actions">
+            <slot name="actions" />
+          </div>
+        )}
+        {dismissible && (
+          <button
+            class="ds-toast__close"
+            type="button"
+            aria-label="Close toast"
+            data-toast-close
+          >
+            <Icon name="x" size={16} />
+          </button>
+        )}
+      </div>
+    </template>
+  </>
+) : (
+  <div
+    class={classes}
+    id={toastId}
+    role={role}
+    aria-live={live}
+    aria-atomic="true"
+    data-toast
+    data-toast-type={tone}
+  >
+    {icon && (
+      <span class="ds-toast__icon" aria-hidden="true">
+        <Icon name={iconName} size={16} />
+      </span>
+    )}
+    <div class="ds-toast__content">
+      <p class="ds-toast__title">{title}</p>
+      {body && <p class="ds-toast__body">{body}</p>}
+      <slot />
+    </div>
+    {hasActions && (
+      <div class="ds-toast__actions">
+        <slot name="actions" />
+      </div>
+    )}
+    {dismissible && (
+      <button
+        class="ds-toast__close"
+        type="button"
+        aria-label="Close toast"
+        data-toast-close
+      >
+        <Icon name="x" size={16} />
+      </button>
+    )}
+  </div>
+)}
+
+<script>
+  import { dismiss, mount } from "../scripts/toast";
+
+  document.addEventListener("click", (event) => {
+    const target = event.target;
+    if (!(target instanceof Element)) return;
+
+    const trigger = target.closest<HTMLElement>("[data-toast-trigger]");
+    if (trigger) {
+      const id = trigger.dataset.toastTrigger;
+      const template = id
+        ? (document.getElementById(
+            `${id}-template`,
+          ) as HTMLTemplateElement | null)
+        : null;
+      const toast = template?.content.firstElementChild?.cloneNode(true);
+      if (toast instanceof HTMLElement) {
+        // Inside the shared region the region itself is the live region.
+        if (toast.getAttribute("role") === "status") {
+          toast.removeAttribute("role");
+          toast.removeAttribute("aria-live");
+        }
+        mount(toast, trigger);
+      }
+      return;
+    }
+
+    // Inline previews rendered directly on a page are not mounted in the
+    // shared region, so they keep a local close handler.
+    const close = target.closest("[data-toast-close]");
+    const toast = close?.closest<HTMLElement>("[data-toast]");
+    if (toast && !toast.closest("[data-toast-region]")) dismiss(toast);
+  });
+</script>

package/src/astro/Tooltip.astro

@@ -0,0 +1,54 @@
+---
+import "../styles/popover.css";
+import "../styles/tooltip.css";
+
+/**
+ * Tooltip. A short, non-essential label for a control. Wrap one focusable
+ * trigger; the script adds aria-describedby to it. Never put information a
+ * user needs, or anything interactive, in a tooltip: touch and many assistive
+ * technologies cannot reach it. Use Popover for that.
+ *
+ *   <Tooltip text="Copy address"><Button iconOnly icon="copy" ariaLabel="Copy" /></Tooltip>
+ */
+interface Props {
+  text: string;
+  placement?: "top" | "bottom" | "start" | "end";
+  /** Hover delay in milliseconds. Keyboard focus opens at once. */
+  delay?: number;
+  id?: string;
+  class?: string;
+}
+
+const { text, placement = "top", delay, id, class: className } = Astro.props;
+
+const tipId = id ?? `tooltip-${Math.random().toString(36).slice(2, 9)}`;
+---
+
+<span class="ds-anchor" data-ds-tooltip data-delay={delay}>
+  <slot />
+  <span
+    class:list={["ds-tooltip", `ds-tooltip--${placement}`, className]}
+    id={tipId}
+    role="tooltip"
+    popover="manual"
+  >
+    {text}
+  </span>
+</span>
+
+<script>
+  import { mountTooltip } from "../scripts/tooltip";
+
+  const bind = () => {
+    document
+      .querySelectorAll<HTMLElement>("[data-ds-tooltip]")
+      .forEach((root) => {
+        if (root.dataset.dsBound) return;
+        root.dataset.dsBound = "true";
+        mountTooltip(root);
+      });
+  };
+
+  bind();
+  document.addEventListener("astro:page-load", bind);
+</script>

package/src/astro/TopBar.astro

@@ -0,0 +1,29 @@
+---
+import "../styles/topbar.css";
+
+/**
+ * Slim, non-sticky utility strip for the top of a page.
+ *
+ * The start slot holds the page context (usually `<Breadcrumbs>`), the
+ * actions slot holds small utilities (theme toggle, command shortcut).
+ * It scrolls away with the page; persistent navigation belongs to
+ * `<Navbar>` or the sidebar.
+ */
+
+interface Props {
+  class?: string;
+}
+
+const { class: className } = Astro.props;
+---
+
+<div class:list={["ds-topbar", className]}>
+  <div class="ds-topbar__inner">
+    <div class="ds-topbar__start">
+      <slot name="start" />
+    </div>
+    <div class="ds-topbar__actions">
+      <slot name="actions" />
+    </div>
+  </div>
+</div>