makersclaw 0.1.0 → 0.3.0

package/templates/next/files/components/ui/carousel.jsx

@@ -0,0 +1,281 @@
+"use client";
+
+import { Children, useCallback, useEffect, useId, useLayoutEffect, useRef, useState } from "react";
+import { cx } from "./cx";
+import { IconButton } from "./button";
+
+// Carousel — a row of slides the user moves through: testimonials, plan
+// cards, screenshots of a template. The browser's own scrolling is the
+// engine (CSS scroll-snap), so a swipe, a trackpad and a scrollbar-less
+// flick all work with nothing to install; the buttons, dots and arrow
+// keys only ask it to scroll. Each child is one slide.
+//
+//   <Carousel label="Customer quotes" itemsPerView={{ sm: 2, lg: 3 }}>
+//     {quotes.map((q) => <QuoteCard key={q.id} {...q} />)}
+//   </Carousel>
+//
+//   label         what a screen reader calls the region (required)
+//   itemsPerView  slides side by side: a number, or { sm, md, lg }. Always
+//                 1 on a phone; a number n is min(n, 2) from sm, n from md
+//   indicator     dots (the default) · counter ("2 / 5") · none
+//   loop          previous on the first goes to the last, and back (off)
+//   autoplay      ms between slides (true = 5000). Off by default; paused
+//                 on hover and focus, while hidden, and never runs for a
+//                 reader who prefers reduced motion. Adds a pause button.
+//   defaultIndex  the slide it opens on
+//   onChange      (index) → the first visible slide, after it settles
+//
+// A carousel hides all but one thing, so it is for things of a kind
+// where seeing one at a time is fine. Content the user must compare
+// (plans, options) reads better as a grid.
+
+const GAP = "calc(var(--spacing) * 4)";
+// The per-breakpoint count arrives as CSS variables; these classes pick
+// the one for the window's width. Written out whole: Tailwind reads
+// class strings literally.
+const PER = "[--per:1] sm:[--per:var(--per-sm)] md:[--per:var(--per-md)] lg:[--per:var(--per-lg)]";
+
+function perView(n) {
+  if (typeof n === "number") return { sm: Math.min(n, 2), md: n, lg: n };
+  const sm = n?.sm ?? 1;
+  const md = n?.md ?? sm;
+  return { sm, md, lg: n?.lg ?? md };
+}
+
+export function Carousel({
+  label,
+  itemsPerView = 1,
+  indicator = "dots",
+  loop = false,
+  autoplay,
+  defaultIndex = 0,
+  onChange,
+  className,
+  children,
+}) {
+  const id = useId();
+  const track = useRef(null);
+  const slides = Children.toArray(children).filter(Boolean);
+  const count = slides.length;
+  const per = perView(itemsPerView);
+  const [index, setIndex] = useState(defaultIndex);
+  const [shown, setShown] = useState(1);
+  const [held, setHeld] = useState(false);
+  const [stopped, setStopped] = useState(false);
+  const [calm, setCalm] = useState(false);
+  const [announce, setAnnounce] = useState(false);
+  const reported = useRef(defaultIndex);
+  const last = Math.max(0, count - shown);
+  const interval = autoplay === true ? 5000 : typeof autoplay === "number" ? autoplay : 0;
+  const playing = interval > 0 && !stopped && !held && !calm;
+
+  const go = useCallback(
+    (i, smooth = true) => {
+      const t = track.current;
+      const el = t?.children[i];
+      if (!t || !el) return;
+      const reduce = typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
+      t.scrollTo({ left: el.offsetLeft, behavior: smooth && !reduce ? "smooth" : "auto" });
+    },
+    [],
+  );
+
+  // Where the scroll rests → the index. Read from the scroll position,
+  // so a swipe, a trackpad and the buttons all land in the same place.
+  const read = useCallback(() => {
+    const t = track.current;
+    if (!t || !t.children.length) return;
+    const n = Number.parseFloat(getComputedStyle(t).getPropertyValue("--per")) || 1;
+    setShown(n);
+    const end = t.scrollWidth - t.clientWidth;
+    const lastPos = Math.max(0, t.children.length - Math.round(n));
+    let i = 0;
+    if (end > 0 && t.scrollLeft >= end - 2) i = lastPos;
+    else {
+      let best = Infinity;
+      [...t.children].forEach((c, k) => {
+        const d = Math.abs(c.offsetLeft - t.scrollLeft);
+        if (d < best) {
+          best = d;
+          i = k;
+        }
+      });
+    }
+    setIndex(Math.min(i, lastPos));
+  }, []);
+
+  useLayoutEffect(() => {
+    if (defaultIndex) go(defaultIndex, false);
+    read();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  useEffect(() => {
+    const t = track.current;
+    if (!t) return;
+    let frame = 0;
+    const onScroll = () => {
+      cancelAnimationFrame(frame);
+      frame = requestAnimationFrame(read);
+    };
+    t.addEventListener("scroll", onScroll, { passive: true });
+    const ro = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(read);
+    ro?.observe(t);
+    return () => {
+      cancelAnimationFrame(frame);
+      t.removeEventListener("scroll", onScroll);
+      ro?.disconnect();
+    };
+  }, [read]);
+
+  // onChange once the index settles, not on every frame of a swipe.
+  useEffect(() => {
+    if (index === reported.current) return;
+    const h = setTimeout(() => {
+      reported.current = index;
+      onChange?.(index);
+    }, 120);
+    return () => clearTimeout(h);
+  }, [index, onChange]);
+
+  useEffect(() => {
+    if (!interval || typeof matchMedia !== "function") return;
+    const mq = matchMedia("(prefers-reduced-motion: reduce)");
+    const on = () => setCalm(mq.matches || document.visibilityState === "hidden");
+    on();
+    mq.addEventListener("change", on);
+    document.addEventListener("visibilitychange", on);
+    return () => {
+      mq.removeEventListener("change", on);
+      document.removeEventListener("visibilitychange", on);
+    };
+  }, [interval]);
+
+  useEffect(() => {
+    if (!playing || last === 0) return;
+    const h = setTimeout(() => go(index >= last ? 0 : index + 1), interval);
+    return () => clearTimeout(h);
+  }, [playing, index, last, interval, go]);
+
+  const prev = () => {
+    setAnnounce(true);
+    go(index > 0 ? index - 1 : loop ? last : 0);
+  };
+  const next = () => {
+    setAnnounce(true);
+    go(index < last ? index + 1 : loop ? 0 : last);
+  };
+
+  function onKeyDown(e) {
+    if (e.target.closest("input, textarea, select, [contenteditable]")) return;
+    if (e.key === "ArrowLeft") prev();
+    else if (e.key === "ArrowRight") next();
+    else if (e.key === "Home") go(0);
+    else if (e.key === "End") go(last);
+    else return;
+    e.preventDefault();
+  }
+
+  if (count === 0) return null;
+  const positions = last + 1;
+
+  return (
+    <section
+      aria-roledescription="carousel"
+      aria-label={label}
+      onKeyDown={onKeyDown}
+      onPointerEnter={() => setHeld(true)}
+      onPointerLeave={() => setHeld(false)}
+      onFocus={() => setHeld(true)}
+      onBlur={(e) => {
+        if (!e.currentTarget.contains(e.relatedTarget)) setHeld(false);
+      }}
+      className={cx("grid min-w-0 gap-3", className)}
+    >
+      <div
+        ref={track}
+        id={`${id}-track`}
+        tabIndex={0}
+        aria-live={announce && !playing ? "polite" : "off"}
+        className={cx(
+          "relative flex snap-x snap-mandatory overflow-x-auto overscroll-x-contain rounded-lg outline-none",
+          "[scrollbar-width:none] [&::-webkit-scrollbar]:hidden",
+          "focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+          PER,
+        )}
+        style={{ gap: GAP, "--per-sm": per.sm, "--per-md": per.md, "--per-lg": per.lg }}
+      >
+        {slides.map((slide, i) => (
+          <div
+            key={slide.key ?? i}
+            role="group"
+            aria-roledescription="slide"
+            aria-label={`${i + 1} of ${count}`}
+            className="min-w-0 shrink-0 snap-start"
+            style={{ flexBasis: `calc((100% - (var(--per) - 1) * ${GAP}) / var(--per))` }}
+          >
+            {slide}
+          </div>
+        ))}
+      </div>
+      {positions > 1 ? (
+        <div className="flex items-center justify-between gap-2">
+          <IconButton
+            icon="chevron-left"
+            label="Previous slide"
+            variant="secondary"
+            aria-controls={`${id}-track`}
+            disabled={!loop && index === 0}
+            onClick={prev}
+          />
+          <div className="flex min-w-0 flex-1 items-center justify-center gap-1">
+            {indicator === "counter" || (indicator === "dots" && positions > 12) ? (
+              <p data-nums className="text-sm text-muted-foreground">
+                {index + 1} / {positions}
+              </p>
+            ) : indicator === "dots" ? (
+              Array.from({ length: positions }, (_, i) => (
+                <button
+                  key={i}
+                  type="button"
+                  aria-label={`Go to slide ${i + 1}`}
+                  aria-current={i === index ? "true" : undefined}
+                  aria-controls={`${id}-track`}
+                  onClick={() => {
+                    setAnnounce(true);
+                    go(i);
+                  }}
+                  className="group grid size-6 place-items-center rounded-full outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                >
+                  <span
+                    className={cx(
+                      "block h-2 rounded-full transition-[width,background-color] duration-200 motion-reduce:transition-none",
+                      i === index ? "w-5 bg-foreground" : "w-2 bg-muted-foreground/40 group-hover:bg-muted-foreground",
+                    )}
+                  />
+                </button>
+              ))
+            ) : null}
+            {interval > 0 && !calm ? (
+              <IconButton
+                icon={stopped ? "play" : "pause"}
+                label={stopped ? "Play slides" : "Pause slides"}
+                size="sm"
+                className="ml-1"
+                onClick={() => setStopped((s) => !s)}
+              />
+            ) : null}
+          </div>
+          <IconButton
+            icon="chevron-right"
+            label="Next slide"
+            variant="secondary"
+            aria-controls={`${id}-track`}
+            disabled={!loop && index >= last}
+            onClick={next}
+          />
+        </div>
+      ) : null}
+    </section>
+  );
+}

package/templates/next/files/components/ui/collapsible.jsx

@@ -0,0 +1,208 @@
+"use client";
+
+import { useRef, useState } from "react";
+import { cx } from "./cx";
+import { Icon } from "./icon";
+
+// Collapsible — a row that shows or hides what is under it: advanced
+// fields, a long note, last week's runs. A native <details>/<summary>
+// underneath, so the browser supplies the keyboard, the expanded state a
+// screen reader announces, and find-in-page opening a closed one. The
+// click is taken over so `open` can be controlled; a toggle the browser
+// makes on its own (find-in-page) is reported through `onOpenChange`.
+// Height animates where the browser can (::details-content) and never
+// when the viewer asks for reduced motion. Never a raw <details> in a
+// surface: `npm run check` refuses it.
+//
+//   title          the trigger's text (the whole row is the target)
+//   meta           a count or a date on the right, muted
+//   open           controlled; with `onOpenChange(next)`. Leave it out and
+//                  `defaultOpen` sets where it starts
+//   variant        plain (a row in the flow) · outline (a bordered panel)
+//                  · flush (edge to edge inside a Card or any bordered
+//                  box: 16px side padding, a rule under each row, none
+//                  under the last — a stack of them is a divided list).
+//                  `accordion-outline` is flush's older name; it still works
+//   chevron        down (default: points down, turns up when open) ·
+//                  right (the disclosure triangle: points right, turns
+//                  down when open — a tree, a list of rows that drill in)
+//   disabled       the row stays readable but does not toggle
+//
+// Accordion below is a list of them: `type` single (one open at a time)
+// or multiple; `collapsible` lets the open one close when single.
+
+const MOTION =
+  "[interpolate-size:allow-keywords] [&::details-content]:h-0 [&::details-content]:overflow-clip " +
+  "[&[open]::details-content]:h-auto [&::details-content]:transition-[height,content-visibility] " +
+  "[&::details-content]:transition-discrete [&::details-content]:duration-200 [&::details-content]:ease-out " +
+  "motion-reduce:[&::details-content]:transition-none";
+
+const LOOKS = {
+  plain: { box: "", row: "-mx-2 px-2 rounded-md", body: "pb-3 pt-1" },
+  outline: { box: "rounded-lg border border-border bg-card text-card-foreground", row: "px-4 rounded-lg", body: "px-4 pb-4" },
+  // An Accordion's items: the list draws the edges.
+  "accordion-plain": { box: "border-b border-border", row: "-mx-2 px-2 rounded-md", body: "pb-4 pt-1" },
+  "accordion-outline": { box: "border-b border-border last:border-b-0", row: "px-4", body: "px-4 pb-4" },
+};
+LOOKS.flush = LOOKS["accordion-outline"];
+
+// Where the chevron points: closed, then open.
+const CHEVRON = {
+  down: { name: "chevron-down", open: "rotate-180" },
+  right: { name: "chevron-right", open: "rotate-90" },
+};
+
+export function Collapsible({
+  title,
+  meta,
+  open,
+  defaultOpen = false,
+  onOpenChange,
+  variant = "plain",
+  chevron = "down",
+  disabled,
+  className,
+  children,
+  ...rest
+}) {
+  const [inner, setInner] = useState(defaultOpen);
+  const controlled = open !== undefined;
+  const isOpen = controlled ? open : inner;
+  const look = LOOKS[variant] ?? LOOKS.plain;
+  const turn = CHEVRON[chevron] ?? CHEVRON.down;
+
+  function set(next) {
+    if (!controlled) setInner(next);
+    onOpenChange?.(next);
+  }
+
+  return (
+    <details
+      open={isOpen}
+      onToggle={(e) => {
+        if (e.currentTarget.open !== isOpen) set(e.currentTarget.open);
+      }}
+      className={cx(MOTION, look.box, className)}
+      {...rest}
+    >
+      <summary
+        aria-disabled={disabled ? true : undefined}
+        onClick={(e) => {
+          e.preventDefault();
+          if (!disabled) set(!isOpen);
+        }}
+        className={cx(
+          "flex min-h-11 list-none items-center gap-3 py-2 text-sm font-medium text-foreground outline-none [&::-webkit-details-marker]:hidden",
+          "focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring",
+          disabled ? "cursor-not-allowed opacity-50" : "cursor-pointer hover:bg-accent",
+          look.row,
+        )}
+      >
+        <span className="min-w-0 flex-1 text-left">{title}</span>
+        {meta !== undefined && meta !== null ? (
+          <span data-nums className="shrink-0 text-xs font-normal text-muted-foreground">
+            {meta}
+          </span>
+        ) : null}
+        <Icon
+          name={turn.name}
+          className={cx(
+            "shrink-0 text-muted-foreground transition-transform duration-200 motion-reduce:transition-none",
+            isOpen && turn.open,
+          )}
+        />
+      </summary>
+      <div className={cx("text-sm", look.body)}>{children}</div>
+    </details>
+  );
+}
+
+/**
+ * A list of Collapsibles. Arrow keys move between the rows, Home/End jump.
+ *
+ *   items        [{ key, title, meta?, content, disabled? }]
+ *   type         single (opening one closes the rest) · multiple
+ *   collapsible  single only: the open row can close (default true)
+ *   value        controlled: a key (or null) when single, an array of keys
+ *                when multiple; with `onChange(next)`. `defaultValue` for
+ *                where it starts when uncontrolled
+ *   variant      plain (rows divided by rules) · outline (one bordered box)
+ *   chevron      down · right, as Collapsible
+ */
+export function Accordion({
+  items,
+  type = "single",
+  collapsible = true,
+  value,
+  defaultValue,
+  onChange,
+  variant = "plain",
+  chevron,
+  className,
+  "aria-label": ariaLabel,
+}) {
+  const root = useRef(null);
+  const multiple = type === "multiple";
+  const [inner, setInner] = useState(defaultValue ?? (multiple ? [] : null));
+  const controlled = value !== undefined;
+  const current = controlled ? value : inner;
+  const live = (items ?? []).filter(Boolean);
+  if (live.length === 0) return null;
+
+  const isOpen = (key) => (multiple ? (current ?? []).includes(key) : current === key);
+
+  function toggle(key, next) {
+    let out;
+    if (multiple) {
+      const list = current ?? [];
+      out = next ? [...list.filter((k) => k !== key), key] : list.filter((k) => k !== key);
+    } else {
+      if (!next && !collapsible) return;
+      out = next ? key : null;
+    }
+    if (!controlled) setInner(out);
+    onChange?.(out);
+  }
+
+  function onKeyDown(e) {
+    const heads = [...(root.current?.querySelectorAll(":scope > details > summary:not([aria-disabled='true'])") ?? [])];
+    const i = heads.indexOf(e.target);
+    if (i < 0) return;
+    let next = null;
+    if (e.key === "ArrowDown") next = (i + 1) % heads.length;
+    else if (e.key === "ArrowUp") next = (i - 1 + heads.length) % heads.length;
+    else if (e.key === "Home") next = 0;
+    else if (e.key === "End") next = heads.length - 1;
+    if (next === null) return;
+    e.preventDefault();
+    heads[next]?.focus();
+  }
+
+  return (
+    <div
+      ref={root}
+      role="group"
+      aria-label={ariaLabel}
+      onKeyDown={onKeyDown}
+      className={cx(
+        variant === "outline" ? "overflow-hidden rounded-lg border border-border bg-card text-card-foreground" : "",
+        className,
+      )}
+    >
+      {live.map((item) => (
+        <Collapsible
+          key={item.key}
+          title={item.title}
+          meta={item.meta}
+          disabled={item.disabled}
+          open={isOpen(item.key)}
+          onOpenChange={(next) => toggle(item.key, next)}
+          variant={variant === "outline" ? "flush" : "accordion-plain"}
+          chevron={chevron}
+        >
+          {item.content}
+        </Collapsible>
+      ))}
+    </div>
+  );
+}