blume 0.0.0 → 0.1.0

package/src/components/content/Tree.astro

@@ -0,0 +1,300 @@
+---
+---
+
+<blume-tree
+  class="not-prose my-6 block rounded-blume border border-border bg-background p-3 text-sm"
+  data-blume-tree
+  role="tree"
+>
+  <slot />
+</blume-tree>
+
+<script>
+  const ITEM_SELECTOR = "[data-blume-tree-item]";
+  const FOLDER_SELECTOR = "[data-blume-tree-folder]";
+  const OPENABLE_SELECTOR =
+    '[data-blume-tree-folder][data-blume-tree-openable="true"]';
+  const CHILDREN_SELECTOR = "[data-blume-tree-children]";
+  const TYPEAHEAD_RESET_MS = 700;
+
+  const directItem = (folder: Element) =>
+    folder.querySelector<HTMLElement>(`:scope > ${ITEM_SELECTOR}`);
+
+  const folderForItem = (item: HTMLElement) => {
+    const folder = item.closest<HTMLElement>(FOLDER_SELECTOR);
+    return directItem(folder ?? document.documentElement) === item
+      ? folder
+      : null;
+  };
+
+  const isOpenableDetails = (
+    folder: HTMLElement | null
+  ): folder is HTMLDetailsElement =>
+    folder instanceof HTMLDetailsElement &&
+    folder.matches(OPENABLE_SELECTOR);
+
+  class BlumeTree extends HTMLElement {
+    #activeItem: HTMLElement | null = null;
+    #typeahead = "";
+    #typeaheadTimer = 0;
+
+    connectedCallback() {
+      if (this.dataset.blumeTreeReady === "true") {
+        return;
+      }
+      this.dataset.blumeTreeReady = "true";
+
+      this.addEventListener("click", this.#onClick);
+      this.addEventListener("focusin", this.#onFocusIn);
+      this.addEventListener("keydown", this.#onKeydown);
+      this.#folders().forEach((folder) => {
+        if (folder instanceof HTMLDetailsElement) {
+          folder.addEventListener("toggle", this.#syncFolderState);
+        }
+      });
+      this.#syncTree();
+      this.#setActive(this.#visibleItems()[0] ?? null, false);
+    }
+
+    disconnectedCallback() {
+      this.removeEventListener("click", this.#onClick);
+      this.removeEventListener("focusin", this.#onFocusIn);
+      this.removeEventListener("keydown", this.#onKeydown);
+      this.#folders().forEach((folder) => {
+        if (folder instanceof HTMLDetailsElement) {
+          folder.removeEventListener("toggle", this.#syncFolderState);
+        }
+      });
+      window.clearTimeout(this.#typeaheadTimer);
+    }
+
+    #items() {
+      return Array.from(
+        this.querySelectorAll<HTMLElement>(ITEM_SELECTOR)
+      );
+    }
+
+    #folders() {
+      return Array.from(
+        this.querySelectorAll<HTMLElement>(FOLDER_SELECTOR)
+      );
+    }
+
+    #visibleItems() {
+      return this.#items().filter((item) => this.#isVisible(item));
+    }
+
+    #isVisible(item: HTMLElement) {
+      for (const folder of this.#folders()) {
+        if (
+          folder instanceof HTMLDetailsElement &&
+          folder.contains(item) &&
+          !folder.open &&
+          directItem(folder) !== item
+        ) {
+          return false;
+        }
+      }
+      return true;
+    }
+
+    #syncTree() {
+      this.#folders().forEach((folder) => {
+        const item = directItem(folder);
+        if (!item) {
+          return;
+        }
+        const openable = folder.dataset.blumeTreeOpenable === "true";
+        if (openable || folder.querySelector(CHILDREN_SELECTOR)) {
+          const expanded =
+            folder instanceof HTMLDetailsElement ? folder.open : true;
+          item.setAttribute("aria-expanded", expanded ? "true" : "false");
+        }
+      });
+
+      this.#items().forEach((item) => {
+        item.setAttribute("aria-level", String(this.#level(item)));
+        item.tabIndex = item === this.#activeItem ? 0 : -1;
+      });
+    }
+
+    #level(item: HTMLElement) {
+      let level = 1;
+      let group = item.parentElement?.closest<HTMLElement>(CHILDREN_SELECTOR);
+      while (group && this.contains(group)) {
+        level += 1;
+        const parentFolder =
+          group.parentElement?.closest<HTMLElement>(FOLDER_SELECTOR);
+        group =
+          parentFolder?.parentElement?.closest<HTMLElement>(
+            CHILDREN_SELECTOR
+          ) ?? null;
+      }
+      return level;
+    }
+
+    #setActive(item: HTMLElement | null, focus: boolean) {
+      if (!item) {
+        return;
+      }
+      this.#activeItem = item;
+      this.#syncTree();
+      item.tabIndex = 0;
+      if (focus) {
+        item.focus();
+      }
+    }
+
+    #move(delta: number) {
+      const items = this.#visibleItems();
+      const active = this.#activeItem ?? (document.activeElement as HTMLElement);
+      const index = items.indexOf(active);
+      const nextIndex = Math.min(Math.max(index + delta, 0), items.length - 1);
+      this.#setActive(items[nextIndex] ?? items[0] ?? null, true);
+    }
+
+    #moveToEdge(edge: "first" | "last") {
+      const items = this.#visibleItems();
+      this.#setActive(
+        edge === "first" ? items[0] : items[items.length - 1],
+        true
+      );
+    }
+
+    #firstChild(folder: HTMLElement) {
+      return folder.querySelector<HTMLElement>(
+        `:scope > ${CHILDREN_SELECTOR} > ${ITEM_SELECTOR}, :scope > ${CHILDREN_SELECTOR} > ${FOLDER_SELECTOR} > ${ITEM_SELECTOR}`
+      );
+    }
+
+    #parentItem(item: HTMLElement) {
+      const group = item.parentElement?.closest(CHILDREN_SELECTOR);
+      const parentFolder = group?.parentElement?.closest(FOLDER_SELECTOR);
+      return parentFolder ? directItem(parentFolder) : null;
+    }
+
+    #expandSiblings(item: HTMLElement) {
+      const group = item.parentElement?.closest(CHILDREN_SELECTOR);
+      const scope = group ?? this;
+      scope
+        .querySelectorAll<HTMLDetailsElement>(
+          `:scope > ${OPENABLE_SELECTOR}`
+        )
+        .forEach((folder) => {
+          folder.open = true;
+        });
+      this.#syncTree();
+    }
+
+    #toggle(folder: HTMLDetailsElement) {
+      folder.open = !folder.open;
+      this.#syncTree();
+    }
+
+    #search(character: string) {
+      window.clearTimeout(this.#typeaheadTimer);
+      this.#typeahead += character.toLowerCase();
+      this.#typeaheadTimer = window.setTimeout(() => {
+        this.#typeahead = "";
+      }, TYPEAHEAD_RESET_MS);
+
+      const items = this.#visibleItems();
+      const active = this.#activeItem ?? (document.activeElement as HTMLElement);
+      const activeIndex = items.indexOf(active);
+      const ordered = items
+        .slice(Math.max(activeIndex + 1, 0))
+        .concat(items.slice(0, Math.max(activeIndex + 1, 0)));
+      const match = ordered.find((item) =>
+        (item.dataset.blumeTreeName ?? "")
+          .toLowerCase()
+          .startsWith(this.#typeahead)
+      );
+      this.#setActive(match ?? null, true);
+    }
+
+    #onClick = (event: MouseEvent) => {
+      const item = (event.target as Element | null)?.closest<HTMLElement>(
+        ITEM_SELECTOR
+      );
+      if (item && this.contains(item)) {
+        this.#setActive(item, false);
+      }
+    };
+
+    #onFocusIn = (event: FocusEvent) => {
+      const item = (event.target as Element | null)?.closest<HTMLElement>(
+        ITEM_SELECTOR
+      );
+      if (item && this.contains(item)) {
+        this.#setActive(item, false);
+      }
+    };
+
+    #onKeydown = (event: KeyboardEvent) => {
+      const item = (event.target as Element | null)?.closest<HTMLElement>(
+        ITEM_SELECTOR
+      );
+      if (!item || !this.contains(item)) {
+        return;
+      }
+
+      const folder = folderForItem(item);
+      if (event.key === "ArrowDown") {
+        event.preventDefault();
+        this.#move(1);
+      } else if (event.key === "ArrowUp") {
+        event.preventDefault();
+        this.#move(-1);
+      } else if (event.key === "Home") {
+        event.preventDefault();
+        this.#moveToEdge("first");
+      } else if (event.key === "End") {
+        event.preventDefault();
+        this.#moveToEdge("last");
+      } else if (event.key === "ArrowRight" && folder) {
+        event.preventDefault();
+        if (isOpenableDetails(folder) && !folder.open) {
+          folder.open = true;
+          this.#syncTree();
+        } else {
+          this.#setActive(this.#firstChild(folder), true);
+        }
+      } else if (event.key === "ArrowLeft") {
+        const parent = this.#parentItem(item);
+        if (isOpenableDetails(folder) && folder.open) {
+          event.preventDefault();
+          folder.open = false;
+          this.#syncTree();
+        } else if (parent) {
+          event.preventDefault();
+          this.#setActive(parent, true);
+        }
+      } else if (
+        (event.key === "Enter" || event.key === " ") &&
+        isOpenableDetails(folder)
+      ) {
+        event.preventDefault();
+        this.#toggle(folder);
+      } else if (event.key === "*") {
+        event.preventDefault();
+        this.#expandSiblings(item);
+      } else if (
+        event.key.length === 1 &&
+        !event.altKey &&
+        !event.ctrlKey &&
+        !event.metaKey
+      ) {
+        event.preventDefault();
+        this.#search(event.key);
+      }
+    };
+
+    #syncFolderState = () => {
+      this.#syncTree();
+    };
+  }
+
+  if (!customElements.get("blume-tree")) {
+    customElements.define("blume-tree", BlumeTree);
+  }
+</script>

package/src/components/content/TreeFile.astro

@@ -0,0 +1,15 @@
+---
+import Icon from "../Icon.astro";
+
+const { name } = Astro.props;
+---
+
+<div
+  class="flex items-center gap-2 rounded px-2 py-1 text-muted-foreground outline-none transition-colors hover:bg-muted/60 focus-visible:ring-2 focus-visible:ring-accent/40"
+  data-blume-tree-item
+  data-blume-tree-name={name}
+  role="treeitem"
+>
+  <Icon class="shrink-0" name="file" size={15} />
+  <span class="font-mono text-xs">{name}</span>
+</div>

package/src/components/content/TreeFolder.astro

@@ -0,0 +1,62 @@
+---
+import Icon from "../Icon.astro";
+
+const { defaultOpen = false, name, openable = true } = Astro.props;
+---
+
+{
+  openable ? (
+    <details
+      class="group"
+      data-blume-tree-folder
+      data-blume-tree-openable="true"
+      open={defaultOpen}
+      role="none"
+    >
+      <summary
+        class="flex cursor-pointer list-none items-center gap-2 rounded px-2 py-1 font-medium outline-none transition-colors hover:bg-muted/60 focus-visible:ring-2 focus-visible:ring-accent/40 [&::-webkit-details-marker]:hidden"
+        data-blume-tree-item
+        data-blume-tree-name={name}
+        role="treeitem"
+      >
+        <Icon
+          class="shrink-0 transition-transform group-open:rotate-90"
+          name="chevron-right"
+          size={15}
+        />
+        <Icon class="shrink-0 text-muted-foreground" name="folder" size={15} />
+        <span class="font-mono text-xs">{name}</span>
+      </summary>
+      <div
+        class="ms-4 border-border border-s ps-2"
+        data-blume-tree-children
+        role="group"
+      >
+        <slot />
+      </div>
+    </details>
+  ) : (
+    <div
+      data-blume-tree-folder
+      data-blume-tree-openable="false"
+      role="none"
+    >
+      <div
+        class="flex items-center gap-2 rounded px-2 py-1 font-medium outline-none transition-colors hover:bg-muted/60 focus-visible:ring-2 focus-visible:ring-accent/40"
+        data-blume-tree-item
+        data-blume-tree-name={name}
+        role="treeitem"
+      >
+        <Icon class="shrink-0 text-muted-foreground" name="folder" size={15} />
+        <span class="font-mono text-xs">{name}</span>
+      </div>
+      <div
+        class="ms-4 border-border border-s ps-2"
+        data-blume-tree-children
+        role="group"
+      >
+        <slot />
+      </div>
+    </div>
+  )
+}

package/src/components/content/TypeTable.astro

@@ -0,0 +1,106 @@
+---
+// A table of object properties laid out like Fumadocs' <TypeTable>: a Prop /
+// Type grid where every row is an expandable <details>. Collapsed, a row shows
+// the accent-colored prop name (with a `?` suffix when optional) and its type;
+// expanded, the row lifts into a card showing the description and a Type/Default
+// detail grid. Uses native <details>/<summary> so the core stays React-free.
+interface TypeEntry {
+  default?: string;
+  description?: string;
+  required?: boolean;
+  type: string;
+  typeDescription?: string;
+  typeDescriptionLink?: string;
+}
+
+interface Props {
+  type?: Record<string, TypeEntry>;
+}
+
+const { type = {} } = Astro.props;
+const entries = Object.entries(type);
+
+// Shared column track so the header, every summary, and the detail grid align.
+const columns = "grid grid-cols-[1fr_2fr_auto] items-center gap-4";
+---
+
+{
+  entries.length > 0 && (
+    <div class="not-prose my-6 rounded-blume border border-border bg-muted/30 p-1.5">
+      <div class={`${columns} px-3 py-2 font-medium text-muted-foreground text-xs`}>
+        <span>Prop</span>
+        <span>Type</span>
+        <span aria-hidden="true" class="size-3.5" />
+      </div>
+
+      <div class="mt-1 flex flex-col gap-1">
+        {entries.map(([name, info]) => (
+        <details class="group/tt border-border border-t [[open]+&]:border-t-transparent open:rounded-blume open:border-transparent open:bg-background open:shadow-sm open:ring-1 open:ring-border">
+          <summary class={`${columns} cursor-pointer list-none px-3 py-2.5 [&::-webkit-details-marker]:hidden`}>
+            <code class="min-w-0 break-words font-mono text-accent text-xs">
+              {name}
+              {info.required ? "" : "?"}
+            </code>
+            {info.typeDescriptionLink ? (
+              <a
+                class="min-w-0 break-words font-mono text-foreground text-xs underline-offset-2 hover:underline"
+                href={info.typeDescriptionLink}
+              >
+                {info.type}
+              </a>
+            ) : (
+              <code class="min-w-0 break-words font-mono text-foreground text-xs">
+                {info.type}
+              </code>
+            )}
+            <svg
+              aria-hidden="true"
+              class="size-3.5 shrink-0 text-muted-foreground transition-transform group-open/tt:rotate-180"
+              fill="none"
+              height="16"
+              stroke="currentColor"
+              stroke-linecap="round"
+              stroke-linejoin="round"
+              stroke-width="2"
+              viewBox="0 0 24 24"
+              width="16"
+            >
+              <path d="m6 9 6 6 6-6" />
+            </svg>
+          </summary>
+
+          <div class="border-border border-t px-3 py-3 text-xs">
+            {info.description && (
+              <p class="mt-0! mb-2! text-foreground">{info.description}</p>
+            )}
+            {info.typeDescription && (
+              <p class="mt-0! mb-2! text-muted-foreground">
+                {info.typeDescription}
+              </p>
+            )}
+            <div class="space-y-1.5">
+              <div class={columns}>
+                <span class="text-muted-foreground">Type</span>
+                <code class="min-w-0 break-words font-mono text-foreground">
+                  {info.type}
+                </code>
+                <span aria-hidden="true" class="size-3.5" />
+              </div>
+              {info.default && (
+                <div class={columns}>
+                  <span class="text-muted-foreground">Default</span>
+                  <code class="min-w-0 break-words font-mono text-foreground">
+                    {info.default}
+                  </code>
+                  <span aria-hidden="true" class="size-3.5" />
+                </div>
+              )}
+            </div>
+          </div>
+        </details>
+        ))}
+      </div>
+    </div>
+  )
+}
+<slot />

package/src/components/content/Update.astro

@@ -0,0 +1,66 @@
+---
+interface RssMetadata {
+  description?: string;
+  title?: string;
+}
+
+interface Props {
+  description?: string;
+  id?: string;
+  label?: string;
+  rss?: RssMetadata;
+  tags?: string[] | string;
+  title?: string;
+}
+
+const { description, id: providedId, label, rss, tags, title } = Astro.props;
+const slugify = (text: string): string =>
+  text
+    .toLowerCase()
+    .trim()
+    .replaceAll(/[^\w\s-]/gu, "")
+    .replaceAll(/[\s_]+/gu, "-")
+    .replaceAll(/-+/gu, "-")
+    .replaceAll(/^-|-$/gu, "");
+const updateLabel = label ?? title ?? "Update";
+const id = providedId ?? (slugify(updateLabel) || "update");
+const tagList = Array.isArray(tags) ? tags : tags ? [tags] : [];
+---
+
+<article
+  class="not-prose group/update my-8 grid gap-4 border-border border-s ps-4 md:grid-cols-[10rem_minmax(0,1fr)] md:border-s-0 md:ps-0"
+  data-blume-update
+  data-blume-update-rss-description={rss?.description}
+  data-blume-update-rss-title={rss?.title}
+  id={id}
+>
+  <header class="md:border-border md:border-e md:pe-4">
+    <a
+      class="font-semibold text-foreground text-sm no-underline hover:text-accent"
+      href={`#${id}`}
+    >
+      {updateLabel}
+    </a>
+    {
+      description && (
+        <p class="mt-1! mb-0! text-muted-foreground text-xs leading-5">
+          {description}
+        </p>
+      )
+    }
+    {
+      tagList.length > 0 && (
+        <div class="mt-3 flex flex-wrap gap-1.5">
+          {tagList.map((tag) => (
+            <span class="rounded-full bg-muted px-2 py-0.5 font-medium text-muted-foreground text-[0.65rem]">
+              {tag}
+            </span>
+          ))}
+        </div>
+      )
+    }
+  </header>
+  <div class="min-w-0 text-muted-foreground text-sm leading-6 [&_a]:font-medium [&_a]:text-foreground [&_a]:underline [&_code]:rounded [&_code]:bg-muted [&_code]:px-1 [&_h2]:mt-0! [&_h2]:border-t-0! [&_h2]:pt-0! [&_h2]:text-base [&_h2]:font-semibold [&_h2]:text-foreground [&_h3]:font-semibold [&_h3]:text-foreground [&_img]:rounded-blume [&_li]:my-1 [&_p:first-child]:mt-0! [&_p:last-child]:mb-0!">
+    <slot />
+  </div>
+</article>

package/src/components/content/Visibility.astro

@@ -0,0 +1,12 @@
+---
+const { for: audience = "humans" } = Astro.props;
+const visibleOnWeb = audience !== "agents";
+---
+
+{
+  visibleOnWeb && (
+    <div data-blume-visibility={audience}>
+      <slot />
+    </div>
+  )
+}

package/src/components/content/Warning.astro

@@ -0,0 +1,9 @@
+---
+import Callout from "./Callout.astro";
+
+const { title } = Astro.props;
+---
+
+<Callout title={title} type="warning">
+  <slot />
+</Callout>