makersclaw 0.1.0 → 0.3.0

package/registry/blocks/comment-box/comment-box.jsx

@@ -0,0 +1,198 @@
+"use client";
+
+// CommentBox — a minimal rich comment field (DocEditor in minimal mode)
+// with @mentions and Cmd/Ctrl+Enter to post, and, when `comments` is
+// given, the thread above it. CommentComposer is the field alone: record-
+// notes uses it to add a note and to edit one in place.
+//
+// A post goes out through an async callback that answers { ok }. While it
+// runs the box is locked and Post spins; a refusal (or a throw) keeps the
+// draft and says why under the box. Only a post that came back ok clears.
+import { useEffect, useId, useRef, useState } from "react";
+import { Avatar, Button, KbdGroup, cx } from "../../ui";
+import { DocEditor, isDocEmpty, useDocEditor } from "../doc-editor";
+import { CommentBody } from "./comment-body";
+import { CommentTime } from "./comment-time";
+
+const nameOf = (author) => (typeof author === "string" ? author : author?.name) || "Someone";
+const srcOf = (author) => (typeof author === "object" && author ? author.src : undefined);
+
+/** ⌘ on a Mac, Ctrl elsewhere — known only in the browser. */
+function useModKey() {
+  const [mac, setMac] = useState(null);
+  useEffect(() => {
+    const p = navigator.userAgentData?.platform || navigator.platform || "";
+    setMac(/mac|iphone|ipad/i.test(p));
+  }, []);
+  return mac === null ? null : mac ? "⌘" : "Ctrl";
+}
+
+export function CommentComposer({
+  onSubmit,
+  author,
+  mentions,
+  defaultValue,
+  placeholder = "Write a comment…",
+  submitLabel = "Post",
+  submitIcon = "send",
+  busyLabel,
+  failedText = "Couldn't post. Your comment is still here; try again.",
+  onCancel,
+  cancelLabel = "Cancel",
+  label = "Comment",
+  autoFocus = false,
+  disabled = false,
+  clearOnSubmit = true,
+  className,
+}) {
+  const box = useDocEditor();
+  const [draft, setDraft] = useState(defaultValue ?? null);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState(null);
+  const running = useRef(false);
+  const mod = useModKey();
+  const errorId = useId();
+  const empty = !draft || isDocEmpty(draft);
+
+  async function submit(doc) {
+    if (running.current || disabled || !doc || isDocEmpty(doc)) return;
+    running.current = true;
+    setBusy(true);
+    setError(null);
+    let res;
+    try {
+      res = await onSubmit?.(doc);
+    } catch (e) {
+      res = { ok: false, error: e?.message };
+    }
+    running.current = false;
+    setBusy(false);
+    if (res && res.ok === false) {
+      setError(res.error || failedText);
+      box.current?.focus();
+      return;
+    }
+    if (clearOnSubmit) {
+      box.current?.clear();
+      setDraft(null);
+    }
+    box.current?.focus();
+  }
+
+  return (
+    <div className={cx("flex items-start gap-3", className)}>
+      {author ? (
+        <div className="mt-1 hidden shrink-0 sm:block">
+          <Avatar name={nameOf(author)} src={srcOf(author)} size="sm" />
+        </div>
+      ) : null}
+      <div className="min-w-0 flex-1">
+        <div
+          className={cx(
+            "rounded-md border bg-background px-3 py-2 focus-within:ring-2 focus-within:ring-ring",
+            error ? "border-destructive" : "border-input",
+            (busy || disabled) && "opacity-60",
+          )}
+          aria-describedby={error ? errorId : undefined}
+        >
+          <DocEditor
+            minimal
+            editorRef={box}
+            defaultValue={defaultValue}
+            onChange={(d) => {
+              setDraft(d);
+              if (error) setError(null);
+            }}
+            onSubmit={submit}
+            mentions={mentions}
+            placeholder={placeholder}
+            label={label}
+            autoFocus={autoFocus}
+            editable={!busy && !disabled}
+          />
+        </div>
+        {error ? (
+          <p id={errorId} role="alert" className="mt-1.5 text-xs text-destructive">
+            {error}
+          </p>
+        ) : null}
+        <div className="mt-2 flex flex-wrap items-center justify-end gap-2">
+          {mod ? (
+            <span className="me-auto hidden items-center gap-1.5 text-xs text-muted-foreground sm:inline-flex">
+              <KbdGroup keys={[mod, "Enter"]} />
+              <span>to {submitLabel.toLowerCase()}</span>
+            </span>
+          ) : null}
+          {onCancel ? (
+            <Button variant="quiet" onClick={onCancel} disabled={busy}>
+              {cancelLabel}
+            </Button>
+          ) : null}
+          <Button variant="primary" icon={submitIcon || undefined} loading={busy} disabled={empty || disabled} onClick={() => submit(box.current?.getDoc() ?? draft)}>
+            {busy && busyLabel ? busyLabel : submitLabel}
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+/** One comment in the thread: avatar, name, time, the body. */
+function CommentItem({ comment }) {
+  const name = nameOf(comment.author);
+  return (
+    <li className="flex gap-3">
+      <Avatar name={name} src={srcOf(comment.author)} size="sm" className="shrink-0" />
+      <div className="min-w-0 flex-1">
+        <p className="flex flex-wrap items-baseline gap-x-2 text-sm">
+          <span className="font-medium">{name}</span>
+          <CommentTime date={comment.createdAt} />
+          {comment.edited ? <span className="text-xs text-muted-foreground">(edited)</span> : null}
+        </p>
+        <CommentBody doc={comment.body} className="mt-0.5 text-foreground" />
+      </div>
+    </li>
+  );
+}
+
+export function CommentBox({
+  onPost,
+  comments,
+  author,
+  mentions,
+  placeholder = "Write a comment…",
+  postLabel = "Post",
+  label = "Comment",
+  emptyText = "No comments yet.",
+  threadLabel = "Comments",
+  autoFocus = false,
+  disabled = false,
+  className,
+}) {
+  const list = Array.isArray(comments) ? comments : null;
+  return (
+    <div className={cx("grid gap-4", className)}>
+      {list ? (
+        list.length ? (
+          <ul aria-label={threadLabel} className="grid gap-4">
+            {list.map((c, i) => (
+              <CommentItem key={c.id ?? i} comment={c} />
+            ))}
+          </ul>
+        ) : (
+          <p className="text-sm text-muted-foreground">{emptyText}</p>
+        )
+      ) : null}
+      <CommentComposer
+        onSubmit={onPost}
+        author={author}
+        mentions={mentions}
+        placeholder={placeholder}
+        submitLabel={postLabel}
+        label={label}
+        autoFocus={autoFocus}
+        disabled={disabled}
+      />
+    </div>
+  );
+}

package/registry/blocks/comment-box/comment-time.jsx

@@ -0,0 +1,77 @@
+"use client";
+
+// CommentTime — when a comment was written, as a <time>.
+//
+// Relative words ("5 min ago") need the clock, and the server's clock and
+// time zone are not the reader's. So the server and the first paint show
+// the absolute date; after mount it turns relative, and one shared minute
+// tick (not a timer per comment) keeps every label current. The full date
+// is always in the title.
+import { useEffect, useState } from "react";
+import { cx } from "../../ui";
+
+const listeners = new Set();
+let timer = null;
+function subscribe(fn) {
+  listeners.add(fn);
+  if (!timer) timer = setInterval(() => listeners.forEach((l) => l(Date.now())), 60_000);
+  return () => {
+    listeners.delete(fn);
+    if (!listeners.size && timer) {
+      clearInterval(timer);
+      timer = null;
+    }
+  };
+}
+
+/** Date.now(), refreshed each minute — null until mounted. */
+export function useNow() {
+  const [now, setNow] = useState(null);
+  useEffect(() => {
+    setNow(Date.now());
+    return subscribe(setNow);
+  }, []);
+  return now;
+}
+
+export const toDate = (v) => {
+  if (v === undefined || v === null || v === "") return null;
+  const d = v instanceof Date ? v : new Date(v);
+  return Number.isNaN(d.getTime()) ? null : d;
+};
+
+const fmt = (opts) => new Intl.DateTimeFormat(undefined, opts);
+const TIME = { hour: "numeric", minute: "2-digit" };
+const startOfDay = (ms) => {
+  const d = new Date(ms);
+  d.setHours(0, 0, 0, 0);
+  return d.getTime();
+};
+
+/** "12 Sep 2026, 14:05" — the title, and the label before mount. */
+export function fullDate(d) {
+  return fmt({ day: "numeric", month: "short", year: "numeric", ...TIME }).format(d);
+}
+
+/** "just now" · "5 min ago" · "3 h ago" (today) · "Yesterday, 14:05" · "12 Sep, 14:05" · "12 Sep 2025". */
+export function relativeDate(d, now) {
+  const diff = now - d.getTime();
+  if (diff < 45_000 && diff > -60_000) return "just now";
+  const today = startOfDay(now);
+  if (diff > 0 && diff < 60 * 60_000) return `${Math.round(diff / 60_000)} min ago`;
+  if (d.getTime() >= today && diff > 0) return `${Math.floor(diff / 3_600_000)} h ago`;
+  if (d.getTime() >= today - 86_400_000 && d.getTime() < today) return `Yesterday, ${fmt(TIME).format(d)}`;
+  if (new Date(d).getFullYear() === new Date(now).getFullYear()) return fmt({ day: "numeric", month: "short", ...TIME }).format(d);
+  return fmt({ day: "numeric", month: "short", year: "numeric" }).format(d);
+}
+
+export function CommentTime({ date, className }) {
+  const now = useNow();
+  const d = toDate(date);
+  if (!d) return null;
+  return (
+    <time dateTime={d.toISOString()} title={fullDate(d)} suppressHydrationWarning className={cx("text-xs text-muted-foreground", className)}>
+      {now === null ? fullDate(d) : relativeDate(d, now)}
+    </time>
+  );
+}

package/registry/blocks/comment-box/demo.jsx

@@ -0,0 +1,141 @@
+"use client";
+
+// CommentBox three ways — the gallery's and the smoke test's surface. Not
+// installed into apps. Posts are pretend: a switch makes them fail.
+//   Thread       comments on a design review, the box under them.
+//   Field alone  no thread: a reply field that reports what it posted.
+//   Empty        a thread with nothing in it yet, and a locked box.
+import { useState } from "react";
+import { Card, Switch, TabPanel, Tabs } from "../components/ui";
+import { CommentBox } from "../components/blocks/comment-box";
+import { docToText } from "../components/blocks/doc-editor";
+
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+const ago = (min) => new Date(Date.now() - min * 60_000).toISOString();
+
+const TEAM = [
+  { id: "u-priya", label: "Priya Raman", description: "Design" },
+  { id: "u-tomas", label: "Tomás Ortega", description: "Engineering" },
+  { id: "u-june", label: "June Okafor", description: "Growth" },
+  { id: "u-lena", label: "Lena Fischer", description: "Sales" },
+];
+const findPeople = async (query) => {
+  const q = query.toLowerCase();
+  return TEAM.filter((p) => p.label.toLowerCase().includes(q));
+};
+const ME = { id: "u-june", name: "June Okafor" };
+
+const t = (text, styles = {}) => ({ type: "text", text, styles });
+const at = (id) => ({ type: "mention", props: { id, label: TEAM.find((p) => p.id === id).label } });
+
+const REVIEW_THREAD = [
+  {
+    id: "c1",
+    author: { id: "u-priya", name: "Priya Raman" },
+    createdAt: ago(60 * 26),
+    body: [
+      { type: "paragraph", content: [t("New pricing page is up for review. Two open questions:")] },
+      { type: "numberedListItem", content: [t("Do we show the "), t("annual", { bold: true }), t(" price first?")] },
+      { type: "numberedListItem", content: [t("Is the comparison table too long on a phone?")] },
+    ],
+  },
+  {
+    id: "c2",
+    author: { id: "u-tomas", name: "Tomás Ortega" },
+    createdAt: ago(95),
+    edited: true,
+    body: [
+      { type: "paragraph", content: [at("u-priya"), t(" annual first, monthly as the toggle. The table collapses to cards under 640px already.")] },
+    ],
+  },
+  {
+    id: "c3",
+    author: { id: "u-lena", name: "Lena Fischer" },
+    createdAt: ago(12),
+    body: [{ type: "paragraph", content: [t("From sales: people ask about "), t("seats", { italic: true }), t(" before price. Can the seat line go above the fold?")] }],
+  },
+];
+
+function ThreadDemo() {
+  const [comments, setComments] = useState(REVIEW_THREAD);
+  const [failing, setFailing] = useState(false);
+  const post = async (doc) => {
+    await wait(700);
+    if (failing) return { ok: false, error: "The server is not answering. Your comment is still here; try again." };
+    setComments((c) => [...c, { id: `c${c.length + 1}`, author: ME, body: doc, createdAt: new Date().toISOString() }]);
+    return { ok: true };
+  };
+  return (
+    <Card
+      title="Pricing page review"
+      description="Type @ to mention someone. ⌘/Ctrl+Enter posts."
+      actions={<Switch id="cb-fail" label="Posts fail" checked={failing} onChange={(e) => setFailing(e.target.checked)} />}
+      className="max-w-2xl"
+    >
+      <CommentBox comments={comments} onPost={post} author={ME} mentions={findPeople} />
+    </Card>
+  );
+}
+
+function FieldDemo() {
+  const [last, setLast] = useState(null);
+  const post = async (doc) => {
+    await wait(400);
+    setLast(docToText(doc));
+    return { ok: true };
+  };
+  return (
+    <Card title="Reply" description="The field alone: no thread above it." className="max-w-2xl">
+      <CommentBox onPost={post} mentions={findPeople} postLabel="Reply" placeholder="Reply to Lena…" label="Reply" />
+      {last !== null ? (
+        <p className="mt-3 whitespace-pre-wrap break-words rounded-md bg-muted p-3 text-sm text-muted-foreground">Posted as text: {last}</p>
+      ) : null}
+    </Card>
+  );
+}
+
+function EmptyDemo() {
+  const [comments, setComments] = useState([]);
+  const [locked, setLocked] = useState(false);
+  const post = async (doc) => {
+    await wait(400);
+    setComments((c) => [...c, { id: `e${c.length + 1}`, author: ME, body: doc, createdAt: new Date().toISOString() }]);
+    return { ok: true };
+  };
+  return (
+    <Card
+      title="Q4 onboarding email"
+      actions={<Switch id="cb-lock" label="Locked" checked={locked} onChange={(e) => setLocked(e.target.checked)} />}
+      className="max-w-2xl"
+    >
+      <CommentBox comments={comments} onPost={post} author={ME} mentions={findPeople} disabled={locked} emptyText="No comments yet. Start the conversation." />
+    </Card>
+  );
+}
+
+export default function CommentBoxDemo() {
+  const [tab, setTab] = useState("thread");
+  return (
+    <div className="grid gap-4">
+      <Tabs
+        aria-label="CommentBox variants"
+        value={tab}
+        onChange={setTab}
+        tabs={[
+          { key: "thread", label: "Thread" },
+          { key: "field", label: "Field alone" },
+          { key: "empty", label: "Empty" },
+        ]}
+      />
+      <TabPanel tab="thread" value={tab}>
+        <ThreadDemo />
+      </TabPanel>
+      <TabPanel tab="field" value={tab}>
+        <FieldDemo />
+      </TabPanel>
+      <TabPanel tab="empty" value={tab}>
+        <EmptyDemo />
+      </TabPanel>
+    </div>
+  );
+}

package/registry/blocks/comment-box/index.js

@@ -0,0 +1,8 @@
+// The CommentBox block — `makersclaw add comment-box`. Fixed: compose it
+// through its props (README.md beside this file). CommentComposer is the
+// field alone, CommentBody draws a posted doc, CommentTime a timestamp;
+// record-notes is built from them. The editor is doc-editor's, in its
+// minimal mode.
+export { CommentBox, CommentComposer } from "./comment-box";
+export { CommentBody } from "./comment-body";
+export { CommentTime } from "./comment-time";

package/registry/blocks/contact-section/README.md

@@ -0,0 +1,152 @@
+# Contact Section
+
+A public "contact us" section. It holds a form, the ways to reach you, or
+both. The form asks for a name, an email and a message, and optionally a
+phone, a company, a subject, a topic (chips or radios) and a consent box.
+The ways to reach you are details (email, phone, address, hours) and
+offices.
+
+Three layouts:
+- **form** — the form alone, with the details on one line above it, or
+  a picture beside or behind it;
+- **split** — the form beside an info panel (plain, or filled with the
+  primary colour);
+- **cards** — the details as icon cards, alone, above the form or beside
+  it.
+
+The form checks itself as it is sent. A missing or malformed field gets
+its message under it, and the focus moves to the first one. It then
+calls `onSubmit(values)`, which is async and returns `{ ok }`. While it
+runs, the button spins and a second press does nothing. `{ ok: false,
+error }` (or a throw) shows the error above the button and keeps
+everything typed. `{ ok: true }` replaces the form with a "Message
+sent" notice and a "Send another" button. It is a full-width section: it
+pads itself and centres its content.
+
+```jsx
+import { ContactSection } from "../components/blocks/contact-section";   // a Makersclaw app ("./blocks/contact-section" from components/)
+import { ContactSection } from "@/components/makersclaw/blocks/contact-section";   // a shadcn project
+```
+
+It is a client component: render it from a `"use client"` component.
+
+## The data
+
+`details` is the ways to reach you:
+
+```js
+{
+  icon: "mail",                     // a name from the kit's Icon
+  label: "Email",                   // what it is ("Call sales" on a card)
+  value: "hello@fieldline.io",      // what is shown
+  href?: "mailto:hello@fieldline.io",   // a link: mailto:, tel:, a map, a page
+  description?: "A person replies within a working day.",   // a card's and a panel row's second line
+}
+```
+
+`offices` (split only): `[{ name: "Lisbon", lines: ["Rua da Prata 88", …], icon? }]`.
+
+`onSubmit` receives the values, trimmed:
+
+```js
+{
+  firstName, lastName,   // or `name` with nameFields="one"
+  email, message,
+  phone?, company?, subject?,   // the ones named in `fields`
+  topic?,                       // the chosen option's value, "" for none
+  consent?,                     // true: it was required and ticked
+}
+```
+
+## Props
+
+- `onSubmit(values)` — async, returns `{ ok: true }` or `{ ok: false,
+  error? }`. Without it there is no form (a cards-only or panel-only
+  section).
+- `layout` — `split` (default) · `form` · `cards`.
+- `kicker`, `title`, `description` — the header. `title` defaults to
+  "Get in touch".
+- `align` — the header, and the cards' content: `center` (default for
+  form and cards) · `start` (default for split).
+- `details` — the ways to reach you, as above. A panel's rows in
+  `split`, one line above the form in `form`, the cards in `cards`.
+- `offices` — `split`: the offices, under the details in the panel.
+- `panel` — `split`: `plain` (default, a quiet bordered box) · `filled`
+  (the primary colour).
+- `panelTitle`, `panelBody` — `split`: the panel's heading and a line
+  under it.
+- `cardsPosition` — `cards` with a form: `above` (default) · `beside`
+  (the cards stacked in a column beside the form from `lg` up).
+- `cardColumns` — `cards`: `1` · `2` · `3` · `4`. Default the number of
+  cards, at most 3.
+- `image`, `imageAlt` — `form`: a picture. `imageAlt` defaults to ""
+  (decoration).
+- `imagePosition` — `side` (default: beside the form from `md` up,
+  hidden on a phone) · `background` (behind the form card, under a veil
+  of the background colour).
+- `nameFields` — `split` (default: first name, required, and last name)
+  · `one` (a single "Name").
+- `fields` — the optional fields to add: any of `"phone"`, `"company"`,
+  `"subject"`. Phone and company are marked optional; subject is not
+  required either.
+- `topics` — `{ label?, options, style?, required? }`: `options` are
+  strings or `{ value, label }`; `style` `chips` (default: pressable
+  chips above the name) · `radio` (a radio row after the email).
+- `consent` — the label of a consent checkbox (a string or a node with
+  your policy link). When given, it must be ticked to send.
+- `messageLabel` — default "Message". `messageRows` — default `5`.
+- `submitLabel` — default "Send message".
+- `sent` — `{ title?, body? }` for the sent notice.
+- `defaultValues` — values to start with (a signed-in visitor's name and
+  email).
+- `labels` — override field labels: `{ firstName, lastName, name, email,
+  phone, company, subject }`.
+- `label` — what a screen reader calls the section. Default the title.
+- `className` — the section's spacing and width. Never colour.
+
+## Example
+
+```jsx
+// components/Contact.jsx
+"use client";
+import { ContactSection } from "./blocks/contact-section";
+import { sendContactMessage } from "../lib/actions";   // your server action
+
+export default function Contact() {
+  return (
+    <ContactSection
+      title="Talk to a person"
+      description="We reply within one working day."
+      details={[
+        { icon: "mail", label: "Email", value: "hello@fieldline.io", href: "mailto:hello@fieldline.io" },
+        { icon: "phone", label: "Phone", value: "+44 20 7946 0321", href: "tel:+442079460321" },
+        { icon: "clock", label: "Hours", value: "Mon–Fri, 9:00–18:00 GMT" },
+      ]}
+      topics={{ options: ["Sales", "Support", "Partnerships"], required: true }}
+      consent="I agree to the privacy policy."
+      onSubmit={async (values) => {
+        const res = await sendContactMessage(values);
+        return res.ok ? { ok: true } : { ok: false, error: res.error };
+      }}
+    />
+  );
+}
+```
+
+## What it will not do
+
+- Send anything: `onSubmit` is yours (save a row, email the team).
+- Stop spam: add a captcha or a honeypot in your own `onSubmit` path.
+- Upload files, or take a card number.
+- Draw a map: link the address (`href`) to one.
+
+A section it cannot be is your own component in `components/`, built
+from the kit — not an edit to this block. Its files are fixed: `npm run
+check` refuses a change, and `makersclaw add contact-section` restores
+them.
+
+## Credits
+
+Layouts ported from Creative Tim UI's contact-section blocks
+(https://github.com/creativetimofficial/ui, MIT), rewritten on the
+Makersclaw kit.

package/registry/blocks/contact-section/block.json

@@ -0,0 +1,11 @@
+{
+  "name": "contact-section",
+  "title": "Contact Section",
+  "description": "A public \"contact us\" section: a form (name, email, message; optional phone, company, subject, a topic as chips or radios, a consent box) and/or the ways to reach you (email, phone, address, hours, offices). The form alone, beside an info panel (plain or filled), or with info cards above or beside it; an optional picture beside or behind the form. Validates in place, submits through an async onSubmit that returns { ok }, and shows the failure or a sent state.",
+  "useWhen": "The contact page or contact section of a public site: sales enquiries, support requests, a studio's \"start a project\" form. Not for a signed-in user's support inbox or ticket thread, or a general-purpose record form (use a form of your own from the kit).",
+  "tags": ["contact", "contact us", "form", "enquiry", "support", "get in touch", "email", "phone", "address", "offices", "marketing", "landing page", "lead"],
+  "exports": ["ContactSection"],
+  "files": ["index.js", "contact-section.jsx"],
+  "requires": [],
+  "frame": "bleed"
+}