@shabboo/kit 0.0.0-stage → 0.1.0

package/src/ui/Button.astro

@@ -0,0 +1,190 @@
+---
+/**
+ * A button, or a link that looks like one (`href` set).
+ * variant: primary (filled accent) · ghost (outlined) · quiet (text only).
+ * A <button> defaults to type="button"; pass type="submit" inside a form (or a Dialog's actions).
+ * aria-disabled="true" keeps it focusable but inert: a small script cancels its clicks, Enter and Space included.
+ *   The script ships only with such a button; a page without one gets no JS from Button.
+ */
+import type { HTMLAttributes } from "astro/types";
+
+type Common = {
+  variant?: "primary" | "ghost" | "quiet";
+  size?: "sm" | "md" | "lg";
+};
+type Props = Common & ((HTMLAttributes<"a"> & { href: string }) | (HTMLAttributes<"button"> & { href?: undefined }));
+
+const { variant = "ghost", size = "md", class: className, ...rest } = Astro.props;
+const inert = String(rest["aria-disabled"]) === "true";
+---
+
+{
+  rest.href !== undefined ? (
+    <a class:list={["btn", className]} data-variant={variant} data-size={size} {...(rest as HTMLAttributes<"a">)}>
+      <slot />
+    </a>
+  ) : (
+    <button
+      class:list={["btn", className]}
+      data-variant={variant}
+      data-size={size}
+      type="button"
+      {...(rest as HTMLAttributes<"button">)}
+    >
+      <slot />
+    </button>
+  )
+}
+
+{
+  /*
+   * aria-disabled only styles a control; this makes it inert too, so a keyboard user can't follow the link or
+   * submit the form (implicit submission clicks the default button, so it is caught here as well).
+   * Shipped only with a button that needs it, and bound once per page, so pages without one stay JS-free.
+   */
+  inert && (
+    <script is:inline>
+      {`if (!window.__shabBtnGuard) {
+  window.__shabBtnGuard = true;
+  document.addEventListener("click", (e) => {
+    if (!e.target?.closest?.('.btn[aria-disabled="true"]')) return;
+    e.preventDefault();
+    e.stopImmediatePropagation();
+  }, true);
+}`}
+    </script>
+  )
+}
+
+<style>
+  .btn {
+    --btn-pad: var(--control-pad-md);
+    position: relative;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: var(--space-2);
+    min-block-size: var(--control-h-md);
+    padding-inline: var(--btn-pad);
+    border: 1px solid transparent;
+    border-radius: var(--radius);
+    background: none;
+    color: var(--text);
+    font-family: var(--font-mono);
+    font-size: var(--step--1);
+    letter-spacing: var(--tracking-mono);
+    line-height: 1;
+    text-decoration: none;
+    white-space: nowrap;
+    cursor: pointer;
+  }
+  .btn[data-size="sm"] {
+    --btn-pad: var(--control-pad-sm);
+    min-block-size: var(--control-h-sm);
+    font-size: var(--step--2);
+  }
+  .btn[data-size="lg"] {
+    --btn-pad: var(--control-pad-lg);
+    min-block-size: var(--control-h-lg);
+    font-size: var(--step-0);
+  }
+  .btn[data-variant="primary"] {
+    background: var(--fill-accent);
+    border-color: var(--fill-accent-strong);
+    color: var(--text-on-fill);
+  }
+  .btn[data-variant="primary"]:hover {
+    background: var(--fill-accent-strong);
+  }
+  .btn[data-variant="ghost"] {
+    border-color: var(--stroke-control);
+  }
+  .btn[data-variant="ghost"]:hover {
+    border-color: var(--stroke-strong);
+    background: var(--state-hover);
+    color: var(--text-accent);
+  }
+  .btn:is([data-variant="ghost"], [data-variant="quiet"]):active {
+    background: var(--state-active);
+  }
+  .btn[data-variant="quiet"] {
+    color: var(--text-muted);
+  }
+  .btn[data-variant="quiet"]:hover {
+    background: var(--state-hover);
+    color: var(--text-accent);
+  }
+  /*
+   * drawn small, tapped big: sm and md reach --target-min through an invisible hit area (% insets: the border
+   * can't skew it). Not quiet: it sits in running text (WCAG's inline exception), where a taller hit area would
+   * take the clicks of the lines above and below.
+   */
+  .btn:not([data-variant="quiet"])::before {
+    content: "";
+    position: absolute;
+    inset: min(0px, (100% - var(--target-min)) / 2);
+  }
+  /* pixel press: a hard 3px ledge under filled and outlined buttons; hover lifts a frame, press flattens it */
+  .btn:is([data-variant="primary"], [data-variant="ghost"]) {
+    box-shadow: 0 3px 0 0 var(--stroke-control);
+  }
+  .btn[data-variant="primary"] {
+    box-shadow: 0 3px 0 0 var(--surface-sunken), 0 3px 0 1px var(--fill-accent-strong);
+  }
+  @media (prefers-reduced-motion: no-preference) {
+    .btn {
+      transition:
+        background-color var(--dur-step) var(--ease-step),
+        border-color var(--dur-step) var(--ease-step),
+        color var(--dur-step) var(--ease-step),
+        translate var(--dur-step) steps(2, end),
+        box-shadow var(--dur-step) steps(2, end);
+    }
+    .btn:is([data-variant="primary"], [data-variant="ghost"]):hover {
+      translate: 0 -1px;
+    }
+    .btn:is([data-variant="primary"], [data-variant="ghost"]):active {
+      translate: 0 3px;
+      box-shadow: none;
+      transition-duration: 0s;
+    }
+    /* directional icons step forward on hover */
+    .btn:hover :global(.icon.mirror) {
+      translate: 3px 0;
+      transition: translate var(--dur-step) steps(2, end);
+    }
+    .btn:hover:dir(rtl) :global(.icon.mirror) {
+      translate: -3px 0;
+    }
+    /* quiet buttons get a terminal cursor, just past the label; out of flow, so the button never grows */
+    .btn[data-variant="quiet"]:hover::after {
+      content: "_";
+      position: absolute;
+      inset-inline-start: calc(100% - var(--btn-pad) + var(--space-2) - 0.25em);
+      animation: btn-cursor var(--blink) steps(1, end) infinite;
+    }
+  }
+  @keyframes btn-cursor {
+    50% {
+      opacity: 0;
+    }
+  }
+  /* disabled is gray, never a faded accent: no fill color, no ledge, no hover */
+  .btn:is(:disabled, [aria-disabled="true"]) {
+    border-color: var(--stroke-subtle);
+    background: var(--fill-disabled);
+    box-shadow: none;
+    color: var(--text-disabled);
+    cursor: not-allowed;
+    pointer-events: none;
+  }
+  .btn[data-variant="quiet"]:is(:disabled, [aria-disabled="true"]) {
+    border-color: transparent;
+    background: none;
+  }
+  /* letter-spacing breaks Arabic-script joining */
+  .btn:is(:lang(fa), :lang(ar)) {
+    font-family: var(--font-arabic);
+    letter-spacing: 0;
+  }
+</style>

package/src/ui/Callout.astro

@@ -0,0 +1,112 @@
+---
+/**
+ * A boxed aside in running text. tone: note (accent) · warning · aside (muted)
+ *   · error · success · info: status callouts. Every tone but aside leads its title with an icon.
+ * slot "title" or the `title` prop: an optional label line.
+ * It renders a <div role="note"> by default; pass as="aside" only when it is truly tangential to the page,
+ * since <aside> is a landmark and shows up in screen readers' landmark lists.
+ */
+import type { HTMLAttributes } from "astro/types";
+import Icon from "./Icon.astro";
+import type { IconName } from "./icons";
+
+type Tone = "note" | "warning" | "aside" | "error" | "success" | "info";
+
+interface Props extends HTMLAttributes<"div"> {
+  tone?: Tone;
+  title?: string;
+  as?: "div" | "aside";
+}
+
+const ICON: Partial<Record<Tone, IconName>> = {
+  note: "flower",
+  info: "info",
+  warning: "warning",
+  error: "close",
+  success: "check",
+};
+
+const { tone = "note", title, as: Root = "div", class: className, ...rest } = Astro.props;
+const icon = ICON[tone];
+const hasTitle = Boolean(title) || Astro.slots.has("title");
+---
+
+<Root
+  class:list={["callout", className, { untitled: !hasTitle && icon }]}
+  data-tone={tone}
+  role={Root === "div" ? "note" : undefined}
+  {...rest}
+>
+  {/* without a title the icon still leads, so a status is never told by color alone */}
+  {!hasTitle && icon && <Icon name={icon} size="sm" class="callout-mark" />}
+  {
+    hasTitle && (
+      <p class="callout-title label">
+        {icon && <Icon name={icon} size="sm" />}
+        <slot name="title">{title}</slot>
+      </p>
+    )
+  }
+  <div class="callout-body"><slot /></div>
+</Root>
+
+<style>
+  .callout {
+    --callout-color: var(--text-accent);
+    display: grid;
+    gap: var(--space-2);
+    padding: var(--space-4) var(--space-5);
+    border: 1px solid var(--stroke);
+    border-inline-start: 2px solid var(--fill-accent-strong);
+    border-radius: var(--radius);
+    background: var(--surface-raised);
+  }
+  .callout[data-tone="warning"] {
+    --callout-color: var(--status-warning);
+    border-inline-start-color: var(--status-warning);
+    background: var(--status-warning-fill);
+  }
+  .callout[data-tone="error"] {
+    --callout-color: var(--status-error);
+    border-inline-start-color: var(--status-error);
+    background: var(--status-error-fill);
+  }
+  .callout[data-tone="success"] {
+    --callout-color: var(--status-success);
+    border-inline-start-color: var(--status-success);
+    background: var(--status-success-fill);
+  }
+  .callout[data-tone="info"] {
+    --callout-color: var(--status-info);
+    border-inline-start-color: var(--status-info);
+    background: var(--status-info-fill);
+  }
+  .callout[data-tone="aside"] {
+    --callout-color: var(--text-muted);
+    border-inline-start-color: var(--stroke);
+    background: none;
+    font-style: italic;
+  }
+  .callout.untitled {
+    grid-template-columns: auto minmax(0, 1fr);
+    align-items: baseline;
+    column-gap: var(--space-3);
+  }
+  .callout :global(.callout-mark) {
+    color: var(--callout-color);
+  }
+  .callout-title {
+    display: flex;
+    align-items: center;
+    gap: var(--space-2);
+    color: var(--callout-color);
+  }
+  .callout-body > :global(* + *) {
+    margin-block-start: var(--space-3);
+  }
+  /* Persian and Arabic script is never slanted */
+  .callout:is(:lang(fa), :lang(ar)),
+  .callout:is(:lang(fa), :lang(ar)) :where(*) {
+    font-style: normal;
+  }
+</style>

package/src/ui/Card.astro

@@ -0,0 +1,79 @@
+---
+/**
+ * A card whose whole surface is a link. The heading link is rendered here (not slotted) so the
+ * stretched ::after can reach it; it carries `p-name u-url` and stays the accessible name.
+ * slot "meta": the label line above the heading · default slot: body below it.
+ */
+import type { HTMLAttributes } from "astro/types";
+
+interface Props extends HTMLAttributes<"article"> {
+  href: string;
+  title: string;
+  headingLevel?: 2 | 3 | 4;
+  size?: "sm" | "md";
+}
+
+const { href, title, headingLevel = 3, size = "md", class: className, ...rest } = Astro.props;
+const H = `h${headingLevel}` as "h2" | "h3" | "h4";
+---
+
+<article class:list={["card", className]} data-size={size} {...rest}>
+  <slot name="meta" />
+  <H class="card-title"><a class="p-name u-url" href={href}>{title}</a></H>
+  <slot />
+</article>
+
+<style>
+  .card {
+    position: relative;
+    display: grid;
+    gap: var(--space-2);
+    align-content: start;
+    padding: var(--space-5);
+    border: 1px solid var(--stroke);
+    border-radius: var(--radius);
+    background: var(--surface-raised);
+    transition: border-color var(--dur-step) var(--ease-step);
+  }
+  .card[data-size="sm"] {
+    padding: var(--space-4);
+  }
+  .card:hover,
+  .card:focus-within {
+    border-color: var(--stroke-strong);
+  }
+  /* hover lifts the card two frames up-and-over, leaving a hard pixel shadow behind */
+  @media (prefers-reduced-motion: no-preference) {
+    .card {
+      transition:
+        border-color var(--dur-step) var(--ease-step),
+        translate var(--dur-step) steps(2, end),
+        box-shadow var(--dur-step) steps(2, end);
+    }
+    .card:hover,
+    .card:focus-within {
+      translate: -3px -3px;
+      box-shadow: 3px 3px 0 0 var(--stroke-strong);
+    }
+    .card:hover:dir(rtl),
+    .card:focus-within:dir(rtl) {
+      translate: 3px -3px;
+      box-shadow: -3px 3px 0 0 var(--stroke-strong);
+    }
+  }
+  .card-title {
+    font-size: var(--step-2);
+  }
+  .card[data-size="sm"] .card-title {
+    font-size: var(--step-1);
+  }
+  .card-title a {
+    text-decoration: none;
+  }
+  /* the whole card is clickable; the heading link stays the accessible name */
+  .card-title a::after {
+    content: "";
+    position: absolute;
+    inset: 0;
+  }
+</style>

package/src/ui/Dialog.astro

@@ -0,0 +1,168 @@
+---
+/**
+ * A modal on a real <dialog>. Open it from any button with invoker commands:
+ *   <Button command="show-modal" commandfor="my-dialog">Open</Button>
+ * Closing needs no JS (a form method="dialog" button, Esc, or a click outside where `closedby` works).
+ * A tiny script backs up invoker commands in browsers that don't have them yet.
+ */
+import type { HTMLAttributes } from "astro/types";
+import Icon from "./Icon.astro";
+
+interface Props extends HTMLAttributes<"dialog"> {
+  id: string;
+  title: string;
+  size?: "sm" | "md" | "lg";
+  /** label of the close button, localized by the caller */
+  closeLabel?: string;
+  /**
+   * what may dismiss it: "any" (Esc or a click outside), "closerequest" (Esc only: use it when a stray
+   * click would lose typed input), "none" (only its own buttons)
+   */
+  closedby?: "any" | "closerequest" | "none";
+}
+
+const { id, title, size = "md", closeLabel = "Close", closedby = "any", class: className, ...rest } = Astro.props;
+const titleId = `${id}-title`;
+---
+
+<dialog
+  id={id}
+  class:list={["dialog", className]}
+  data-size={size}
+  aria-labelledby={titleId}
+  {...{ closedby }}
+  {...rest}
+>
+  <form method="dialog" class="dialog-head">
+    <h2 id={titleId}>{title}</h2>
+    <button class="x" aria-label={closeLabel}><Icon name="close" /></button>
+  </form>
+  <div class="dialog-body"><slot /></div>
+  {
+    Astro.slots.has("actions") && (
+      <form method="dialog" class="dialog-actions">
+        <slot name="actions" />
+      </form>
+    )
+  }
+</dialog>
+
+<script>
+  // invoker commands (command / commandfor) are native in new browsers; this covers the rest
+  if (!("command" in HTMLButtonElement.prototype)) {
+    document.addEventListener("click", (event) => {
+      const button = (event.target as Element | null)?.closest?.("button[commandfor]");
+      if (!button) return;
+      const target = document.getElementById(button.getAttribute("commandfor") ?? "");
+      if (!(target instanceof HTMLDialogElement)) return;
+      const command = button.getAttribute("command");
+      if (command === "show-modal") target.showModal();
+      else if (command === "close") target.close();
+    });
+  }
+</script>
+
+<style>
+  .dialog {
+    /* the global reset zeroes margins; a modal dialog centers with auto */
+    margin: auto;
+    inline-size: min(100% - 2 * var(--gutter), 32rem);
+    max-block-size: min(100% - 2 * var(--gutter), 40rem);
+    padding: 0;
+    border: 1px solid var(--stroke);
+    border-radius: var(--radius);
+    background: var(--surface-raised);
+    color: var(--text);
+    box-shadow: 0 0 0 1px var(--fill-glow), 0 30px 80px -20px var(--surface);
+  }
+  .dialog[data-size="sm"] {
+    inline-size: min(100% - 2 * var(--gutter), 22rem);
+  }
+  .dialog[data-size="lg"] {
+    inline-size: min(100% - 2 * var(--gutter), 48rem);
+  }
+  .dialog::backdrop {
+    background: var(--overlay);
+  }
+  /* opens like a CRT: a scan from the middle out in hard frames, a sideways glitch, a flicker behind */
+  @media (prefers-reduced-motion: no-preference) {
+    .dialog[open] {
+      animation: dialog-scan calc(var(--dur-step) * 2) steps(6, end);
+    }
+    .dialog[open]::backdrop {
+      animation: dialog-flicker calc(var(--dur-step) * 2) steps(1, end);
+    }
+  }
+  @keyframes dialog-scan {
+    0% {
+      clip-path: inset(50% 0 50% 0);
+      translate: -4px 0;
+    }
+    50% {
+      translate: 3px 0;
+    }
+    100% {
+      clip-path: inset(0 0 0 0);
+      translate: 0 0;
+    }
+  }
+  @keyframes dialog-flicker {
+    0% {
+      opacity: 0;
+    }
+    30% {
+      opacity: 0.5;
+    }
+    55% {
+      opacity: 0.2;
+    }
+  }
+  .dialog-head {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--space-4);
+    padding: var(--space-4) var(--space-5);
+    border-block-end: 1px dashed var(--stroke);
+  }
+  h2 {
+    font-size: var(--step-1);
+  }
+  .x {
+    position: relative;
+    display: grid;
+    place-items: center;
+    inline-size: var(--control-h-sm);
+    block-size: var(--control-h-sm);
+    border: 1px solid transparent;
+    border-radius: var(--radius);
+    background: none;
+    color: var(--text-muted);
+    cursor: pointer;
+  }
+  /* drawn small, tapped big: the hit area reaches --target-min, inside the head's padding (% insets: the border can't skew it) */
+  .x::before {
+    content: "";
+    position: absolute;
+    inset: min(0px, (100% - var(--target-min)) / 2);
+  }
+  .x:hover {
+    border-color: var(--stroke);
+    background: var(--state-hover);
+    color: var(--text);
+  }
+  .x:active {
+    background: var(--state-active);
+  }
+  .dialog-body {
+    padding: var(--space-5);
+    color: var(--text-muted);
+  }
+  .dialog-actions {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: flex-end;
+    gap: var(--space-3);
+    padding: 0 var(--space-5) var(--space-5);
+  }
+</style>