@db-vincent/components 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@db-vincent/components",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "UNLICENSED",
   "type": "module",
   "description": "Minerva design-system components for Astro. Token-driven, dependency-free and accessibility-checked. (Placeholder scope `@ds`; see AGENTS.md.)",
@@ -22,9 +22,9 @@
     "./styles/*.css": "./src/styles/*.css"
   },
   "peerDependencies": {
-    "astro": ">=4"
+    "astro": ">=4 <8"
   },
   "dependencies": {
-    "@db-vincent/tokens": "^0.1.0"
+    "@db-vincent/tokens": "0.1.1"
   }
 }

package/src/astro/Avatar.astro

@@ -0,0 +1,88 @@
+---
+import Icon from "./Icon.astro";
+import { getInitials } from "../scripts/avatar";
+import "../styles/avatar.css";
+
+/**
+ * Avatar: an image with initials (or an icon) underneath, so a missing or
+ * failed image still shows who it is. The root is role="img" named by `name`
+ * plus the status, so the status never relies on colour. Image errors are
+ * handled by scripts/avatar.ts.
+ */
+interface Props {
+  /** Full name. Becomes the accessible name and the source of the initials. */
+  name: string;
+  src?: string;
+  size?: "sm" | "md" | "lg";
+  shape?: "circle" | "square";
+  /** What shows without an image. Defaults to the initials of `name`. */
+  fallback?: "initials" | "icon";
+  status?: "online" | "away" | "busy" | "offline";
+  class?: string;
+}
+
+const {
+  name,
+  src,
+  size = "md",
+  shape = "circle",
+  fallback = "initials",
+  status,
+  class: className,
+} = Astro.props;
+
+const initials = getInitials(name);
+const showIcon = fallback === "icon" || initials === "";
+const label = status ? `${name}, ${status}` : name;
+const iconSize = size === "lg" ? 20 : size === "sm" ? 14 : 16;
+---
+
+<span
+  class:list={[
+    "ds-avatar",
+    size !== "md" && `ds-avatar--${size}`,
+    shape === "square" && "ds-avatar--square",
+    className,
+  ]}
+  role="img"
+  aria-label={label}
+  data-ds-avatar
+>
+  <span class="ds-avatar__face">
+    <span class="ds-avatar__fallback" aria-hidden="true">
+      {showIcon ? <Icon name="user" size={iconSize} /> : initials}
+    </span>
+    {src && (
+      <img
+        class="ds-avatar__img"
+        src={src}
+        alt=""
+        loading="lazy"
+        decoding="async"
+      />
+    )}
+  </span>
+  {status && (
+    <span
+      class={`ds-avatar__status ds-avatar__status--${status}`}
+      aria-hidden="true"
+    />
+  )}
+</span>
+
+<script>
+  import { mountAvatar } from "../scripts/avatar";
+
+  const bind = () => {
+    document
+      .querySelectorAll<HTMLElement>("[data-ds-avatar]")
+      .forEach((root) => {
+        if (root.dataset.dsBound) return;
+        root.dataset.dsBound = "true";
+        mountAvatar(root);
+      });
+  };
+
+  bind();
+  document.addEventListener("astro:page-load", bind);
+</script>

package/src/astro/AvatarGroup.astro

@@ -0,0 +1,63 @@
+---
+import Avatar from "./Avatar.astro";
+import "../styles/avatar.css";
+
+/**
+ * Overlapping avatars with a "+N" count for the rest. The group is named by
+ * `label` ("Project members"); the count is named "N more".
+ */
+interface Person {
+  name: string;
+  src?: string;
+}
+
+interface Props {
+  items: Person[];
+  /** Accessible name for the whole group. */
+  label: string;
+  /** Avatars shown before the "+N" count. */
+  max?: number;
+  size?: "sm" | "md" | "lg";
+  shape?: "circle" | "square";
+  class?: string;
+}
+
+const {
+  items,
+  label,
+  max = 4,
+  size = "md",
+  shape = "circle",
+  class: className,
+} = Astro.props;
+
+const visible = items.slice(0, max);
+const hidden = items.length - visible.length;
+---
+
+<div
+  class:list={["ds-avatar-group", className]}
+  role="group"
+  aria-label={label}
+>
+  {visible.map((person) => (
+    <Avatar name={person.name} src={person.src} size={size} shape={shape} />
+  ))}
+  {hidden > 0 && (
+    <span
+      class:list={[
+        "ds-avatar",
+        size !== "md" && `ds-avatar--${size}`,
+        shape === "square" && "ds-avatar--square",
+      ]}
+      role="img"
+      aria-label={`${hidden} more`}
+    >
+      <span class="ds-avatar__face">
+        <span class="ds-avatar__fallback ds-avatar__count" aria-hidden="true">
+          +{hidden}
+        </span>
+      </span>
+    </span>
+  )}
+</div>

package/src/astro/Chip.astro

@@ -29,9 +29,28 @@ const {
 } = Astro.props;
 
 // The remove button names the item it removes ("Remove 4K"), not just "Remove".
-const text = (await Astro.slots.render("default"))
-  .replace(/<[^>]+>/g, "")
-  .trim();
+// The slot HTML is already entity-escaped and Astro escapes the attribute
+// again, so decode before it reaches aria-label.
+const ENTITIES: Record<string, string> = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: " ",
+};
+const decode = (html: string) =>
+  html.replace(
+    /&(?:#(\d+)|#x([0-9a-f]+)|([a-z]+));/gi,
+    (match, dec, hex, name) => {
+      if (name) return ENTITIES[name.toLowerCase()] ?? match;
+      const code = Number.parseInt(dec ?? hex, dec ? 10 : 16);
+      return code <= 0x10ffff ? String.fromCodePoint(code) : match;
+    },
+  );
+const text = decode(
+  (await Astro.slots.render("default")).replace(/<[^>]+>/g, ""),
+).trim();
 const removeName = removeLabel ?? (text ? `Remove ${text}` : "Remove");
 
 const classes = [

package/src/astro/Drawer.astro

@@ -0,0 +1,30 @@
+---
+import Modal from "./Modal.astro";
+
+/**
+ * Side drawer: a Modal anchored to the `start` or `end` edge (or `bottom`).
+ * Same native <dialog> behaviour, styles and script as Modal; this wrapper only
+ * changes the defaults.
+ */
+interface Props {
+  id: string;
+  title: string;
+  description?: string;
+  triggerLabel?: string;
+  triggerVariant?: "primary" | "secondary" | "ghost" | "danger";
+  size?: "sm" | "md" | "lg";
+  placement?: "start" | "end" | "bottom";
+  class?: string;
+}
+
+const {
+  triggerLabel = "Open drawer",
+  placement = "end",
+  ...rest
+} = Astro.props;
+---
+
+<Modal {...rest} triggerLabel={triggerLabel} placement={placement}>
+  <slot />
+  <slot name="footer" slot="footer" />
+</Modal>

package/src/astro/Grid.astro

@@ -25,7 +25,13 @@ const {
   class: className,
 } = Astro.props;
 
-const style = `--grid-columns:${columns};--grid-columns-phone:${phoneColumns};--grid-min:${minItem};--grid-masonry-columns:${columns}`;
+const safeLength = (v: string | undefined, fallback?: string) =>
+  v && /^\d+(\.\d+)?(rem|em|px|%|ch|vw|vh)$/.test(v) ? v : fallback;
+const safeInt = (n: number, fallback: number) =>
+  Number.isFinite(n) ? Math.max(1, Math.floor(n)) : fallback;
+const cols = safeInt(columns, 12);
+const phoneCols = safeInt(phoneColumns, 1);
+const style = `--grid-columns:${cols};--grid-columns-phone:${phoneCols};--grid-min:${safeLength(minItem, "16rem")};--grid-masonry-columns:${cols}`;
 const classes = [
   "ds-grid",
   gap !== "md" && `ds-grid--gap-${gap}`,

package/src/astro/GridItem.astro

@@ -15,7 +15,9 @@ const {
   class: className,
 } = Astro.props;
 
-const style = `--grid-item-span:${span};--grid-item-span-phone:${phoneSpan}`;
+const safeInt = (n: number, fallback: number) =>
+  Number.isFinite(n) ? Math.max(1, Math.floor(n)) : fallback;
+const style = `--grid-item-span:${safeInt(span, 1)};--grid-item-span-phone:${safeInt(phoneSpan, 1)}`;
 ---
 
 <Tag class:list={["ds-grid__item", className]} style={style}>

package/src/astro/Menu.astro

@@ -0,0 +1,151 @@
+---
+import Button from "./Button.astro";
+import MenuItem from "./MenuItem.astro";
+import "../styles/popover.css";
+import "../styles/menu.css";
+
+/**
+ * Menu: a trigger button and a list of commands in a native popover. Opens
+ * with Enter, Space or the arrow keys; arrows, Home, End and typing move
+ * between items; Escape closes and returns focus to the trigger; Tab closes.
+ * Picking an item fires `ds-menu-select` on the root with `detail.value`
+ * (and `detail.checked` for checkbox and radio items), then closes.
+ *
+ *   <Menu triggerLabel="Actions" items={[
+ *     { value: "restart", label: "Restart" },
+ *     { type: "separator" },
+ *     { value: "delete", label: "Delete", danger: true },
+ *   ]} />
+ */
+interface Item {
+  value: string;
+  label: string;
+  icon?: string;
+  /** Renders a link instead of a button. */
+  href?: string;
+  disabled?: boolean;
+  danger?: boolean;
+}
+
+interface CheckItem {
+  type: "checkbox";
+  value: string;
+  label: string;
+  checked?: boolean;
+  disabled?: boolean;
+}
+
+interface RadioItem {
+  type: "radio";
+  value: string;
+  label: string;
+  checked?: boolean;
+  disabled?: boolean;
+}
+
+interface Separator {
+  type: "separator";
+}
+
+interface Group {
+  type: "group";
+  label: string;
+  items: (Item | CheckItem | RadioItem)[];
+}
+
+type Entry = Item | CheckItem | RadioItem | Separator | Group;
+
+interface Props {
+  items: Entry[];
+  /** Trigger text, or its accessible name when `triggerIcon` is set. */
+  triggerLabel?: string;
+  /** Icon-only trigger, for example "more-horizontal". */
+  triggerIcon?: string;
+  triggerVariant?: "primary" | "secondary" | "ghost" | "danger";
+  placement?: "top" | "bottom" | "start" | "end";
+  id?: string;
+  class?: string;
+}
+
+const {
+  items,
+  triggerLabel = "Actions",
+  triggerIcon,
+  triggerVariant = "secondary",
+  placement = "bottom",
+  id,
+  class: className,
+} = Astro.props;
+
+const rootId = id ?? `menu-${Math.random().toString(36).slice(2, 9)}`;
+const surfaceId = `${rootId}-surface`;
+const triggerId = `${rootId}-trigger`;
+
+const isGroup = (entry: Entry): entry is Group =>
+  "type" in entry && entry.type === "group";
+const isSeparator = (entry: Entry): entry is Separator =>
+  "type" in entry && entry.type === "separator";
+---
+
+<span class="ds-anchor" id={rootId} data-ds-menu>
+  <Button
+    id={triggerId}
+    variant={triggerVariant}
+    type="button"
+    popovertarget={surfaceId}
+    aria-haspopup="menu"
+    aria-expanded="false"
+    aria-controls={surfaceId}
+    iconOnly={Boolean(triggerIcon)}
+    ariaLabel={triggerIcon ? triggerLabel : undefined}
+    icon={triggerIcon ?? "chevron-down"}
+    iconPosition="end"
+  >
+    {!triggerIcon && triggerLabel}
+  </Button>
+  <div
+    class:list={[
+      "ds-popover",
+      "ds-menu",
+      `ds-popover--${placement}`,
+      className,
+    ]}
+    id={surfaceId}
+    popover="auto"
+    role="menu"
+    tabindex="-1"
+    aria-labelledby={triggerId}
+  >
+    {items.map((entry, index) =>
+      isSeparator(entry) ? (
+        <div class="ds-menu__separator" role="separator" />
+      ) : isGroup(entry) ? (
+        <div role="group" aria-labelledby={`${rootId}-group-${index}`}>
+          <div class="ds-menu__label" id={`${rootId}-group-${index}`}>
+            {entry.label}
+          </div>
+          {entry.items.map((item) => (
+            <MenuItem {...item} />
+          ))}
+        </div>
+      ) : (
+        <MenuItem {...entry} />
+      ),
+    )}
+  </div>
+</span>
+
+<script>
+  import { mountMenu } from "../scripts/menu";
+
+  const bind = () => {
+    document.querySelectorAll<HTMLElement>("[data-ds-menu]").forEach((root) => {
+      if (root.dataset.dsBound) return;
+      root.dataset.dsBound = "true";
+      mountMenu(root);
+    });
+  };
+
+  bind();
+  document.addEventListener("astro:page-load", bind);
+</script>

package/src/astro/MenuItem.astro

@@ -0,0 +1,57 @@
+---
+import Icon from "./Icon.astro";
+
+/** One row of a Menu. Internal: use Menu with an `items` array. */
+interface Props {
+  type?: "item" | "checkbox" | "radio";
+  value: string;
+  label: string;
+  icon?: string;
+  href?: string;
+  checked?: boolean;
+  disabled?: boolean;
+  danger?: boolean;
+}
+
+const {
+  type = "item",
+  value,
+  label,
+  icon,
+  href,
+  checked = false,
+  disabled = false,
+  danger = false,
+} = Astro.props;
+
+const role =
+  type === "checkbox"
+    ? "menuitemcheckbox"
+    : type === "radio"
+      ? "menuitemradio"
+      : "menuitem";
+const Tag = href && type === "item" ? "a" : "button";
+---
+
+<Tag
+  class:list={["ds-menu__item", danger && "ds-menu__item--danger"]}
+  role={role}
+  tabindex="-1"
+  type={Tag === "button" ? "button" : undefined}
+  href={Tag === "a" && !disabled ? href : undefined}
+  aria-checked={type === "item" ? undefined : String(checked)}
+  aria-disabled={disabled ? "true" : undefined}
+  data-value={value}
+>
+  {type !== "item" && (
+    <span class="ds-menu__indicator" aria-hidden="true">
+      <Icon name="check" size={16} />
+    </span>
+  )}
+  {icon && (
+    <span class="ds-menu__icon" aria-hidden="true">
+      <Icon name={icon} size={16} />
+    </span>
+  )}
+  {label}
+</Tag>

package/src/astro/Modal.astro

@@ -7,6 +7,10 @@ import "../styles/modal.css";
  * Modal dialog on native <dialog>. Native showModal() supplies the focus trap,
  * Escape handling and inert background. The trigger is wired with ARIA; focus
  * returns to the trigger on close automatically.
+ *
+ * `placement` anchors the dialog: "center" (default), or a drawer on the
+ * "bottom", "start" or "end" edge. Use the Drawer component for a drawer with
+ * its own defaults.
  */
 interface Props {
   id: string;
@@ -15,7 +19,7 @@ interface Props {
   triggerLabel?: string;
   triggerVariant?: "primary" | "secondary" | "ghost" | "danger";
   size?: "sm" | "md" | "lg";
-  variant?: "dialog" | "sheet";
+  placement?: "center" | "start" | "end" | "bottom";
   class?: string;
 }
 
@@ -26,10 +30,13 @@ const {
   triggerLabel = "Open dialog",
   triggerVariant = "secondary",
   size = "md",
-  variant = "dialog",
+  placement: placementProp,
   class: className,
 } = Astro.props;
 
+const placement = placementProp ?? "center";
+const edge = placement !== "center";
+
 const titleId = `${id}-title`;
 const descriptionId = description ? `${id}-description` : undefined;
 ---
@@ -47,7 +54,7 @@ const descriptionId = description ? `${id}-description` : undefined;
   class:list={[
     "ds-modal",
     size !== "md" && `ds-modal--${size}`,
-    variant === "sheet" && "ds-modal--sheet",
+    edge && ["ds-modal--drawer", `ds-modal--${placement}`],
     className,
   ]}
   id={id}

package/src/astro/Pagination.astro

@@ -52,6 +52,7 @@ const pageProps = (page: number) =>
   aria-label={label}
   data-pagination-interactive={interactive ? "true" : undefined}
   data-total={total}
+  data-current={current}
 >
   <ul class="ds-pagination__list">
     <li>
@@ -69,7 +70,7 @@ const pageProps = (page: number) =>
     </li>
     {tokens.map((token) =>
       typeof token === "number" ? (
-        <li>
+        <li data-token>
           <Tag
             class="ds-pagination__link"
             {...pageProps(token)}
@@ -80,7 +81,7 @@ const pageProps = (page: number) =>
           </Tag>
         </li>
       ) : (
-        <li>
+        <li data-token>
           <span class="ds-pagination__ellipsis" aria-hidden="true">
             …
           </span>
@@ -104,6 +105,84 @@ const pageProps = (page: number) =>
 </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]")
@@ -117,36 +196,7 @@ const pageProps = (page: number) =>
           if (!control || control.hasAttribute("disabled")) return;
           event.preventDefault();
           const page = Number(control.dataset.page);
-          const total = Number(nav.dataset.total);
-          nav.querySelectorAll<HTMLElement>("[data-page]").forEach((item) => {
-            if (Number(item.dataset.page) === page) {
-              item.setAttribute("aria-current", "page");
-            } else {
-              item.removeAttribute("aria-current");
-            }
-          });
-          const previous = nav.querySelector<HTMLButtonElement>(
-            '[data-direction="prev"]',
-          );
-          const next = nav.querySelector<HTMLButtonElement>(
-            '[data-direction="next"]',
-          );
-          if (previous) {
-            previous.dataset.page = String(Math.max(1, page - 1));
-            previous.disabled = page <= 1;
-            previous.setAttribute(
-              "aria-disabled",
-              page <= 1 ? "true" : "false",
-            );
-          }
-          if (next) {
-            next.dataset.page = String(Math.min(total, page + 1));
-            next.disabled = page >= total;
-            next.setAttribute(
-              "aria-disabled",
-              page >= total ? "true" : "false",
-            );
-          }
+          render(nav, page);
           nav.dispatchEvent(
             new CustomEvent("page-change", {
               bubbles: true,