@dogsbay/ui 0.2.0-beta.0

package/src/popover/popover.ts

@@ -0,0 +1,144 @@
+import { DismissController } from "@dogsbay/primitives/dismiss";
+import { createPortal } from "@dogsbay/primitives/portal";
+import { setupFloating } from "@dogsbay/primitives/floating";
+import type { Placement } from "@floating-ui/dom";
+
+interface PopoverInstance {
+  root: HTMLElement;
+  trigger: HTMLElement;
+  content: HTMLElement;
+  dismiss: DismissController;
+  cleanupPortal: (() => void) | null;
+  cleanupFloating: (() => void) | null;
+  open: boolean;
+}
+
+const instances = new WeakMap<HTMLElement, PopoverInstance>();
+
+let idCounter = 0;
+function uniqueId(prefix: string) {
+  return `${prefix}-${++idCounter}`;
+}
+
+function resolveAsChild(wrapper: HTMLElement): HTMLElement {
+  const child = wrapper.firstElementChild as HTMLElement | null;
+  if (child) {
+    const part = wrapper.getAttribute("data-part");
+    if (part) child.setAttribute("data-part", part);
+    return child;
+  }
+  return wrapper;
+}
+
+function initPopover(root: HTMLElement) {
+  if (instances.has(root)) return;
+
+  const triggerWrapper = root.querySelector(
+    "[data-part='trigger']",
+  ) as HTMLElement | null;
+  const content = root.querySelector(
+    "[data-part='content']",
+  ) as HTMLElement | null;
+  if (!triggerWrapper || !content) return;
+
+  let trigger = triggerWrapper;
+  if (triggerWrapper.hasAttribute("data-as-child")) {
+    trigger = resolveAsChild(triggerWrapper);
+  }
+
+  const contentId = content.id || uniqueId("base-popover");
+  content.id = contentId;
+  trigger.setAttribute("aria-controls", contentId);
+  trigger.setAttribute("aria-expanded", "false");
+
+  const instance: PopoverInstance = {
+    root,
+    trigger,
+    content,
+    dismiss: new DismissController(content, {
+      onDismiss: () => closePopover(root),
+    }),
+    cleanupPortal: null,
+    cleanupFloating: null,
+    open: false,
+  };
+
+  instances.set(root, instance);
+
+  trigger.addEventListener("click", () => {
+    if (instance.open) {
+      closePopover(root);
+    } else {
+      openPopover(root);
+    }
+  });
+}
+
+function openPopover(root: HTMLElement) {
+  const instance = instances.get(root);
+  if (!instance || instance.open) return;
+  instance.open = true;
+
+  instance.cleanupPortal = createPortal(instance.content, instance.content.id);
+
+  instance.content.hidden = false;
+  instance.content.setAttribute("data-state", "open");
+  instance.trigger.setAttribute("aria-expanded", "true");
+
+  const side = instance.content.dataset.side || "bottom";
+  const align = instance.content.dataset.align || "center";
+  const placement =
+    `${side}${align !== "center" ? `-${align}` : ""}` as Placement;
+
+  instance.cleanupFloating = setupFloating(instance.trigger, instance.content, {
+    placement,
+    offset: 8,
+  });
+
+  instance.dismiss.activate();
+
+  // Focus first focusable element inside popover
+  requestAnimationFrame(() => {
+    const focusable = instance.content.querySelector(
+      "button, input, [tabindex]:not([tabindex='-1']), a[href]",
+    ) as HTMLElement | null;
+    focusable?.focus();
+  });
+}
+
+function closePopover(root: HTMLElement) {
+  const instance = instances.get(root);
+  if (!instance || !instance.open) return;
+  instance.open = false;
+
+  instance.dismiss.deactivate();
+  instance.content.setAttribute("data-state", "closed");
+  instance.trigger.setAttribute("aria-expanded", "false");
+
+  instance.content.hidden = true;
+  if (instance.cleanupFloating) {
+    instance.cleanupFloating();
+    instance.cleanupFloating = null;
+  }
+  if (instance.cleanupPortal) {
+    instance.cleanupPortal();
+    instance.cleanupPortal = null;
+  }
+
+  instance.trigger.focus();
+}
+
+function init() {
+  document.querySelectorAll("[data-component='popover']").forEach((el) => {
+    initPopover(el as HTMLElement);
+  });
+}
+
+if (document.readyState === "loading") {
+  document.addEventListener("DOMContentLoaded", init);
+} else {
+  init();
+}
+document.addEventListener("astro:page-load", init);
+
+export { initPopover, openPopover, closePopover };

package/src/preview-card/PreviewCard.astro

@@ -0,0 +1,24 @@
+---
+import { tv } from "tailwind-variants";
+
+const previewCard = tv({
+  base: "relative inline-block",
+});
+
+interface Props {
+  delay?: number;
+  class?: string;
+  [key: string]: unknown;
+}
+
+const { delay = 500, class: className, ...rest } = Astro.props;
+---
+
+<span
+  class={previewCard({ class: className })}
+  data-component="preview-card"
+  data-delay={delay}
+  {...rest}
+>
+  <slot />
+</span>

package/src/preview-card/PreviewCardContent.astro

@@ -0,0 +1,24 @@
+---
+import { tv } from "tailwind-variants";
+
+const previewCardContent = tv({
+  base: "absolute z-50 w-80 rounded-md border bg-popover p-4 text-popover-foreground shadow-md",
+});
+
+interface Props {
+  class?: string;
+  [key: string]: unknown;
+}
+
+const { class: className, ...rest } = Astro.props;
+---
+
+<div
+  class={previewCardContent({ class: className })}
+  data-part="content"
+  role="tooltip"
+  hidden
+  {...rest}
+>
+  <slot />
+</div>

package/src/preview-card/PreviewCardTrigger.astro

@@ -0,0 +1,23 @@
+---
+import { tv } from "tailwind-variants";
+
+const previewCardTrigger = tv({
+  base: "cursor-pointer underline decoration-dotted underline-offset-4",
+});
+
+interface Props {
+  class?: string;
+  [key: string]: unknown;
+}
+
+const { class: className, ...rest } = Astro.props;
+---
+
+<span
+  class={previewCardTrigger({ class: className })}
+  data-part="trigger"
+  tabindex="0"
+  {...rest}
+>
+  <slot />
+</span>

package/src/preview-card/index.ts

@@ -0,0 +1,3 @@
+export { default as PreviewCard } from "./PreviewCard.astro";
+export { default as PreviewCardTrigger } from "./PreviewCardTrigger.astro";
+export { default as PreviewCardContent } from "./PreviewCardContent.astro";

package/src/preview-card/preview-card.ts

@@ -0,0 +1,91 @@
+import { setupFloating } from "@dogsbay/primitives/floating";
+
+function init(root: HTMLElement) {
+  if (root.hasAttribute("data-initialized")) return;
+  root.setAttribute("data-initialized", "");
+
+  const trigger = root.querySelector<HTMLElement>("[data-part='trigger']");
+  const content = root.querySelector<HTMLElement>("[data-part='content']");
+  if (!trigger || !content) return;
+
+  const delay = Number(root.getAttribute("data-delay") || "500");
+
+  let showTimeout: ReturnType<typeof setTimeout>;
+  let hideTimeout: ReturnType<typeof setTimeout>;
+  let cleanupFloating: (() => void) | null = null;
+  let isOpen = false;
+
+  function show() {
+    if (isOpen) return;
+    isOpen = true;
+
+    content.hidden = false;
+    content.setAttribute("data-state", "open");
+
+    cleanupFloating = setupFloating(trigger, content, {
+      placement: "bottom-start",
+      offset: 8,
+    });
+  }
+
+  function hide() {
+    if (!isOpen) return;
+    isOpen = false;
+
+    content.setAttribute("data-state", "closed");
+    content.hidden = true;
+
+    if (cleanupFloating) {
+      cleanupFloating();
+      cleanupFloating = null;
+    }
+  }
+
+  trigger.addEventListener("pointerenter", () => {
+    clearTimeout(hideTimeout);
+    showTimeout = setTimeout(show, delay);
+  });
+
+  trigger.addEventListener("pointerleave", () => {
+    clearTimeout(showTimeout);
+    hideTimeout = setTimeout(hide, 200);
+  });
+
+  content.addEventListener("pointerenter", () => {
+    clearTimeout(hideTimeout);
+  });
+
+  content.addEventListener("pointerleave", () => {
+    hideTimeout = setTimeout(hide, 200);
+  });
+
+  // Focus support
+  trigger.addEventListener("focus", () => {
+    clearTimeout(hideTimeout);
+    showTimeout = setTimeout(show, delay);
+  });
+
+  trigger.addEventListener("blur", () => {
+    clearTimeout(showTimeout);
+    hideTimeout = setTimeout(hide, 200);
+  });
+
+  // Escape closes
+  root.addEventListener("keydown", (e) => {
+    if (e.key === "Escape" && isOpen) {
+      e.preventDefault();
+      hide();
+    }
+  });
+}
+
+function initAll() {
+  document.querySelectorAll<HTMLElement>("[data-component='preview-card']").forEach(init);
+}
+
+if (document.readyState === "loading") {
+  document.addEventListener("DOMContentLoaded", initAll);
+} else {
+  initAll();
+}
+document.addEventListener("astro:page-load", initAll);

package/src/progress/Progress.astro

@@ -0,0 +1,61 @@
+---
+import { tv } from "tailwind-variants";
+
+const progress = tv({
+  base: "relative h-2 w-full overflow-hidden rounded-full bg-secondary",
+});
+
+const progressIndicator = tv({
+  base: "h-full rounded-full bg-primary transition-all",
+});
+
+interface Props {
+  value?: number;
+  max?: number;
+  indeterminate?: boolean;
+  class?: string;
+  [key: string]: unknown;
+}
+const {
+  value = 0,
+  max = 100,
+  indeterminate = false,
+  class: className,
+  ...rest
+} = Astro.props;
+const percent = indeterminate
+  ? 0
+  : Math.min(100, Math.max(0, (value / max) * 100));
+const valueText = indeterminate ? undefined : `${Math.round(percent)}%`;
+---
+
+<div
+  class={progress({ class: className })}
+  role="progressbar"
+  aria-valuenow={indeterminate ? undefined : value}
+  aria-valuemin={0}
+  aria-valuemax={max}
+  aria-valuetext={valueText}
+  data-value={indeterminate ? undefined : value}
+  data-max={max}
+  data-indeterminate={indeterminate || undefined}
+  {...rest}
+>
+  <div
+    class={progressIndicator()}
+    data-part="indicator"
+    style={indeterminate ? "width: 50%; animation: progress-indeterminate 1.5s ease-in-out infinite" : `width: ${percent}%`}
+  >
+  </div>
+</div>
+
+<style is:global>
+  @keyframes progress-indeterminate {
+    0% {
+      transform: translateX(-100%);
+    }
+    100% {
+      transform: translateX(300%);
+    }
+  }
+</style>

package/src/progress/index.ts

@@ -0,0 +1 @@
+export { default as Progress } from "./Progress.astro";

package/src/property-item/PropertyItem.astro

@@ -0,0 +1,183 @@
+---
+/**
+ * Single property row for API documentation.
+ * Used by both PropertyList (parameters) and SchemaViewer (schemas).
+ *
+ * Layout:
+ *   name  type <format>                          REQUIRED
+ *   Description text here
+ *   Enum: value1 | value2
+ *   Example: "doggie"
+ *
+ * Expandable: if properties/items are provided, renders with
+ * details/summary for nested object/array expansion.
+ */
+import { tv } from "tailwind-variants";
+
+interface SchemaProperty {
+  name: string;
+  type: string;
+  description?: string;
+  required?: boolean;
+  nullable?: boolean;
+  format?: string;
+  enum?: string[];
+  default?: unknown;
+  example?: unknown;
+  deprecated?: boolean;
+  properties?: SchemaProperty[];
+  items?: SchemaProperty[];
+}
+
+interface Props extends SchemaProperty {
+  level?: number;
+  showLocation?: boolean;
+  location?: string;
+  class?: string;
+}
+
+const {
+  name,
+  type,
+  description,
+  required = false,
+  nullable = false,
+  format,
+  enum: enumValues,
+  default: defaultValue,
+  example,
+  deprecated = false,
+  properties,
+  items,
+  level = 0,
+  showLocation = false,
+  location,
+  class: className,
+} = Astro.props;
+
+const typeBadge = tv({
+  base: "rounded px-1.5 py-0.5 text-[10px] font-medium",
+  variants: {
+    type: {
+      string: "bg-api-type-string/20 text-api-type-string",
+      number: "bg-api-type-number/20 text-api-type-number",
+      integer: "bg-api-type-number/20 text-api-type-number",
+      boolean: "bg-api-type-boolean/20 text-api-type-boolean",
+      object: "bg-api-type-object/20 text-api-type-object",
+      array: "bg-api-type-array/20 text-api-type-array",
+      null: "bg-muted/20 text-muted-foreground",
+    },
+  },
+  defaultVariants: { type: "string" },
+});
+
+const locationBadge = tv({
+  base: "rounded px-1.5 py-0.5 text-[10px] font-medium uppercase",
+  variants: {
+    location: {
+      path: "bg-api-put/20 text-api-put",
+      query: "bg-api-post/20 text-api-post",
+      header: "bg-api-head/20 text-api-head",
+      cookie: "bg-muted/20 text-muted-foreground",
+    },
+  },
+});
+
+function getTypeVariant(t: string) {
+  const known = ["string", "number", "integer", "boolean", "object", "array", "null"];
+  return known.includes(t) ? t as any : "string";
+}
+
+const hasChildren = (properties && properties.length > 0) || (items && items.length > 0);
+const childProps = properties || items || [];
+const indent = level * 16;
+---
+
+<div
+  class:list={["border-b border-border last:border-b-0", deprecated && "opacity-60", className]}
+>
+  {hasChildren ? (
+    <details>
+      <summary
+        class="flex cursor-pointer items-start justify-between gap-4 px-4 py-3 list-none [&::-webkit-details-marker]:hidden hover:bg-muted/50 rounded"
+        style={indent > 0 ? `padding-left: ${16 + indent}px;` : undefined}
+      >
+        <div class="flex items-center gap-2 min-w-0">
+          <svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-3 shrink-0 text-muted-foreground transition-transform duration-200" data-property-chevron aria-hidden="true"><polyline points="9 18 15 12 9 6" /></svg>
+          <code class="text-sm font-semibold">{name}</code>
+          <span class={typeBadge({ type: getTypeVariant(type) })}>
+            {type}{format ? ` <${format}>` : ""}
+          </span>
+          {showLocation && location && (
+            <span class={locationBadge({ location: location as any })}>{location}</span>
+          )}
+          {nullable && <span class="text-muted-foreground text-[10px]">nullable</span>}
+        </div>
+        <div class="flex shrink-0 items-center gap-2">
+          {required && (
+            <span class="text-[10px] font-semibold uppercase text-api-required">required</span>
+          )}
+        </div>
+      </summary>
+      {description && (
+        <p class="px-4 pb-1 text-sm text-muted-foreground" style={`padding-left: ${32 + indent}px;`} set:html={description} />
+      )}
+      <div class="border-l border-border" style={`margin-left: ${24 + indent}px;`}>
+        {childProps.map((child: SchemaProperty) => (
+          <Astro.self {...child} level={level + 1} />
+        ))}
+      </div>
+    </details>
+  ) : (
+    <div
+      class="flex items-start justify-between gap-4 px-4 py-3"
+      style={indent > 0 ? `padding-left: ${16 + indent}px;` : undefined}
+    >
+      <div class="min-w-0 flex-1">
+        <div class="flex items-center gap-2">
+          {level > 0 && <span class="size-3 shrink-0" />}
+          <code class="text-sm font-semibold">{name}</code>
+          <span class={typeBadge({ type: getTypeVariant(type) })}>
+            {type}{format ? ` <${format}>` : ""}
+          </span>
+          {showLocation && location && (
+            <span class={locationBadge({ location: location as any })}>{location}</span>
+          )}
+          {nullable && <span class="text-muted-foreground text-[10px]">nullable</span>}
+        </div>
+        {description && (
+          <p class:list={["mt-1 text-sm text-muted-foreground", level > 0 && "pl-5"]} set:html={description} />
+        )}
+        {enumValues && (
+          <div class:list={["mt-1.5 flex flex-wrap items-center gap-1 text-[10px]", level > 0 && "pl-5"]}>
+            <span class="text-muted-foreground">Enum:</span>
+            {enumValues.map((v) => (
+              <code class="rounded bg-muted px-1.5 py-0.5">{v}</code>
+            ))}
+          </div>
+        )}
+        {example !== undefined && (
+          <div class:list={["mt-1 text-xs text-muted-foreground", level > 0 && "pl-5"]}>
+            Example: <code class="rounded bg-muted px-1 py-0.5">{JSON.stringify(example)}</code>
+          </div>
+        )}
+        {defaultValue !== undefined && (
+          <div class:list={["mt-1 text-xs text-muted-foreground", level > 0 && "pl-5"]}>
+            Default: <code class="rounded bg-muted px-1 py-0.5">{JSON.stringify(defaultValue)}</code>
+          </div>
+        )}
+      </div>
+      <div class="flex shrink-0 items-center gap-2 pt-0.5">
+        {required && (
+          <span class="text-[10px] font-semibold uppercase text-api-required">required</span>
+        )}
+      </div>
+    </div>
+  )}
+</div>
+
+<style is:global>
+  details[open] > summary [data-property-chevron] {
+    transform: rotate(90deg);
+  }
+</style>

package/src/property-list/PropertyList.astro

@@ -0,0 +1,68 @@
+---
+/**
+ * Stripe-style property list for API parameters.
+ * Groups parameters by location (path, query, header, cookie)
+ * and renders each with PropertyItem.
+ *
+ * Replaces ParameterTable with a more readable layout at all widths.
+ */
+import PropertyItem from "../property-item/PropertyItem.astro";
+
+interface Parameter {
+  name: string;
+  in: "path" | "query" | "header" | "cookie";
+  type: string;
+  required?: boolean;
+  description?: string;
+  default?: string;
+  enum?: string[];
+  deprecated?: boolean;
+}
+
+interface Props {
+  parameters: Parameter[];
+  class?: string;
+}
+
+const { parameters, class: className } = Astro.props;
+
+// Group by location
+const locationOrder = ["path", "query", "header", "cookie"] as const;
+const locationLabels: Record<string, string> = {
+  path: "Path Parameters",
+  query: "Query Parameters",
+  header: "Header Parameters",
+  cookie: "Cookie Parameters",
+};
+
+const groups = locationOrder
+  .map((loc) => ({
+    location: loc,
+    label: locationLabels[loc],
+    params: parameters.filter((p) => p.in === loc),
+  }))
+  .filter((g) => g.params.length > 0);
+---
+
+<div class={className}>
+  {groups.map((group) => (
+    <div class="mb-4 last:mb-0">
+      <h4 class="mb-1 text-[11px] font-semibold uppercase tracking-wider text-muted-foreground">
+        {group.label}
+      </h4>
+      <div class="rounded-lg border bg-card">
+        {group.params.map((param) => (
+          <PropertyItem
+            name={param.name}
+            type={param.type}
+            required={param.required}
+            description={param.description}
+            default={param.default}
+            enum={param.enum}
+            deprecated={param.deprecated}
+          />
+        ))}
+      </div>
+    </div>
+  ))}
+</div>

package/src/radio-group/RadioGroup.astro

@@ -0,0 +1,41 @@
+---
+import { tv } from "tailwind-variants";
+
+const radioGroup = tv({
+  base: "grid gap-2",
+});
+
+interface Props {
+  name?: string;
+  defaultValue?: string;
+  disabled?: boolean;
+  required?: boolean;
+  orientation?: "horizontal" | "vertical";
+  class?: string;
+  [key: string]: unknown;
+}
+
+const {
+  name,
+  defaultValue,
+  disabled = false,
+  required = false,
+  orientation = "vertical",
+  class: className,
+  ...rest
+} = Astro.props;
+---
+
+<div
+  class={radioGroup({ class: className })}
+  data-component="radio-group"
+  data-name={name}
+  data-default-value={defaultValue}
+  data-disabled={disabled || undefined}
+  data-orientation={orientation}
+  role="radiogroup"
+  aria-required={required ? "true" : undefined}
+  {...rest}
+>
+  <slot />
+</div>