@at-flux/astroflare 1.0.2 → 1.0.4

package/src/components/FilterPills.astro

@@ -0,0 +1,164 @@
+---
+import { getTagPalette } from "../tag-colors";
+
+interface Props {
+  /** Tag/filter values rendered as clickable pills. */
+  items: Array<
+    | string
+    | {
+        value: string;
+        label?: string;
+        href?: string;
+        active?: boolean;
+        colorKey?: string;
+      }
+  >;
+  /** Include an "all" filter option first. */
+  includeAll?: boolean;
+  /** Label shown for the catch-all filter. */
+  allLabel?: string;
+  /** Optional URL for the catch-all filter pill (renders as link when set). */
+  allHref?: string;
+  /** Initial active filter value. */
+  active?: string;
+  /** Optional casing transform for labels. */
+  itemCase?: "none" | "upper";
+  /** Explicit color map by lowercase tag key. */
+  colorOverrides?: Record<string, string>;
+  /** Classes applied to the pill row wrapper. */
+  class?: string;
+}
+
+const {
+  items,
+  includeAll = true,
+  allLabel = "All",
+  allHref,
+  active = "all",
+  itemCase = "upper",
+  colorOverrides,
+  class: className = "",
+} = Astro.props;
+
+const formatLabel = (value: string): string =>
+  itemCase === "upper" ? value.toUpperCase() : value;
+
+const normalizedItems = items.map((item) =>
+  typeof item === "string"
+    ? { value: item, label: item }
+    : {
+        value: item.value,
+        label: item.label ?? item.value,
+        href: item.href,
+        active: item.active,
+        colorKey: item.colorKey,
+      },
+);
+---
+
+<div class:list={["af-filter-pills flex flex-wrap items-center gap-2", className]}>
+  {includeAll && (
+    allHref ? (
+      <a
+        href={allHref}
+        class:list={["af-filter-pill", "af-filter-pill-all", active === "all" && "is-active"]}
+      >
+        {formatLabel(allLabel)}
+      </a>
+    ) : (
+      <button
+        type="button"
+        data-filter="all"
+        class:list={["af-filter-pill", "af-filter-pill-all", active === "all" && "is-active"]}
+      >
+        {formatLabel(allLabel)}
+      </button>
+    )
+  )}
+  {normalizedItems.map((item) => {
+    const palette = getTagPalette(item.colorKey ?? item.value, { overrides: colorOverrides });
+    const isActive = item.active ?? active === item.value;
+    const label = formatLabel(item.label);
+    return (
+      item.href ? (
+        <a
+          href={item.href}
+          class:list={["af-filter-pill", isActive && "is-active"]}
+          style={{
+            "--af-pill-bg": palette.bg,
+            "--af-pill-border": palette.border,
+            "--af-pill-text": palette.text,
+          }}
+        >
+          {label}
+        </a>
+      ) : (
+        <button
+          type="button"
+          data-filter={item.value}
+          class:list={["af-filter-pill", isActive && "is-active"]}
+          style={{
+            "--af-pill-bg": palette.bg,
+            "--af-pill-border": palette.border,
+            "--af-pill-text": palette.text,
+          }}
+        >
+          {label}
+        </button>
+      )
+    );
+  })}
+</div>
+
+<style>
+  .af-filter-pill {
+    border-radius: 9999px;
+    border: 1px solid var(--af-pill-border, var(--color-light-border));
+    background: var(--af-pill-bg, color-mix(in oklab, var(--color-light-surface) 80%, transparent));
+    color: var(--af-pill-text, color-mix(in oklab, var(--color-light-text-subtle) 78%, transparent));
+    padding: 0.35rem 0.9rem;
+    font-size: 0.72rem;
+    font-weight: 500;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    cursor: pointer;
+    transition: transform 130ms ease, filter 130ms ease;
+    text-decoration: none;
+    display: inline-flex;
+    align-items: center;
+  }
+
+  .af-filter-pill:hover {
+    filter: brightness(1.04);
+  }
+
+  .af-filter-pill.is-active {
+    border-color: color-mix(in oklab, var(--af-pill-text, var(--color-secondary)) 80%, transparent);
+    box-shadow: inset 0 0 0 1px color-mix(in oklab, var(--af-pill-text, var(--color-secondary)) 36%, transparent);
+  }
+  .af-filter-pill.af-filter-pill-all {
+    --af-pill-bg: transparent;
+    --af-pill-border: color-mix(in oklab, var(--color-light-text-subtle) 45%, transparent);
+    --af-pill-text: color-mix(in oklab, var(--color-light-text-body) 92%, transparent);
+  }
+  .af-filter-pill.af-filter-pill-all.is-active {
+    --af-pill-bg: color-mix(in oklab, var(--color-light-text-body) 7%, transparent);
+    --af-pill-border: color-mix(in oklab, var(--color-light-text-body) 72%, transparent);
+    --af-pill-text: var(--color-light-text-body);
+  }
+  :global([data-theme="dark"]) .af-filter-pill {
+    color: var(--af-pill-text, color-mix(in oklab, var(--color-dark-text-subtle) 85%, transparent));
+    border-color: var(--af-pill-border, var(--color-dark-border));
+    background: var(--af-pill-bg, color-mix(in oklab, var(--color-dark-surface) 70%, transparent));
+  }
+  :global([data-theme="dark"]) .af-filter-pill.af-filter-pill-all {
+    --af-pill-bg: transparent;
+    --af-pill-border: color-mix(in oklab, var(--color-dark-text-subtle) 48%, transparent);
+    --af-pill-text: color-mix(in oklab, var(--color-dark-text-body) 90%, transparent);
+  }
+  :global([data-theme="dark"]) .af-filter-pill.af-filter-pill-all.is-active {
+    --af-pill-bg: color-mix(in oklab, var(--color-dark-text-body) 10%, transparent);
+    --af-pill-border: color-mix(in oklab, var(--color-dark-text-body) 70%, transparent);
+    --af-pill-text: var(--color-dark-text-body);
+  }
+</style>

package/src/components/IconButton.astro

@@ -5,10 +5,15 @@
  * Consumers must supply their own icon via slot.
  */
 interface Props {
+  /** Accessible label announced by screen readers. */
   label: string;
+  /** Optional URL; when set, renders an `<a>` instead of `<button>`. */
   href?: string;
+  /** Extra classes merged with base button styles. */
   class?: string;
+  /** Optional element id for targeting and tests. */
   id?: string;
+  /** Additional passthrough attributes for anchor/button element. */
   [key: string]: unknown;
 }
 

package/src/components/InstagramProfileLink.astro

@@ -2,8 +2,11 @@
 interface Props {
   /** Instagram username without @ */
   handle: string;
+  /** Optional explicit profile URL (defaults to `https://www.instagram.com/{handle}`). */
   href?: string;
+  /** Classes merged onto the anchor element. */
   class?: string;
+  /** Optional accessible label override for the link. */
   'aria-label'?: string;
 }
 

package/src/components/ListSummary.astro

@@ -0,0 +1,63 @@
+---
+import Tooltip from "./Tooltip.astro";
+
+interface Props {
+  /** Ordered list values to render. */
+  items: string[];
+  /** Maximum number of visible items before overflow summary is shown. */
+  visibleCount?: number;
+  /** String used to join visible/overflow values. */
+  separator?: string;
+  /** Classes applied to the outer summary wrapper. */
+  class?: string;
+  /** Fallback label when `items` is empty. */
+  emptyLabel?: string;
+  /** Classes applied to the overflow `+N` chip. */
+  overflowClass?: string;
+  /** Tooltip placement for overflow details. */
+  tooltipPosition?: "top" | "bottom";
+  /** Optional value casing transform before render. */
+  itemCase?: "none" | "upper";
+}
+
+const {
+  items,
+  visibleCount = 3,
+  separator = ", ",
+  class: className = "",
+  emptyLabel = "",
+  overflowClass = "",
+  tooltipPosition = "top",
+  itemCase = "none",
+} = Astro.props;
+
+const formatItem = (item: string): string =>
+  itemCase === "upper" ? item.toUpperCase() : item;
+
+const visibleItems = items.slice(0, visibleCount).map(formatItem);
+const overflowItems = items.slice(visibleCount).map(formatItem);
+const overflowLabel = `+ ${overflowItems.length}`;
+const tooltipText = overflowItems.join(separator);
+---
+
+<span class:list={["inline-flex flex-wrap items-center gap-1", className]}>
+  {items.length === 0 ? (
+    emptyLabel && <span>{emptyLabel}</span>
+  ) : (
+    <>
+      <span>{visibleItems.join(separator)}</span>
+      {overflowItems.length > 0 && (
+        <Tooltip text={tooltipText} position={tooltipPosition}>
+          <span
+            class:list={[
+              "inline-flex cursor-help items-center rounded-full border px-2 py-0.5 text-xs",
+              overflowClass,
+            ]}
+          >
+            {overflowLabel}
+          </span>
+        </Tooltip>
+      )}
+    </>
+  )}
+</span>

package/src/components/MediaProtect.astro

@@ -0,0 +1,41 @@
+---
+/**
+ * Wrap media/content in no-save utility classes and register delegated protection handlers.
+ *
+ * - `drag`: block dragstart inside this protected region (defaults to true)
+ * - `contextMenu`: block right-click context menu inside this protected region (defaults to true)
+ */
+interface Props {
+  /** Classes applied to the inner `.no-save` wrapper. */
+  class?: string;
+  /** Classes applied to the outer `.no-save-container` wrapper. */
+  containerClass?: string;
+  /** Enable dragstart prevention in this protected region. Defaults to true. */
+  drag?: boolean;
+  /** Enable contextmenu prevention in this protected region. Defaults to true. */
+  contextMenu?: boolean;
+}
+
+const {
+  class: className = "",
+  containerClass = "",
+  drag = true,
+  contextMenu = true,
+} = Astro.props;
+---
+
+<div
+  class:list={["no-save-container", containerClass]}
+  data-media-protect-root
+  data-media-protect-drag={drag ? "true" : "false"}
+  data-media-protect-context-menu={contextMenu ? "true" : "false"}
+>
+  <div class:list={["no-save", className]}>
+    <slot />
+  </div>
+</div>
+<script>
+  import { initMediaProtectRoots } from "../runtime/media-protect";
+
+  initMediaProtectRoots();
+</script>

package/src/components/Modal.astro

@@ -4,12 +4,15 @@
  * `class` applies to the modal panel (card). Dialog element keeps backdrop/transparent shell.
  */
 interface Props {
+  /** Dialog id used by triggers (`ModalTrigger`, direct DOM calls). */
   id: string;
   /** Panel (card) classes — surface, border, radius, etc. */
   class?: string;
+  /** Classes applied to the `<dialog>` shell/backdrop container. */
   backdropClass?: string;
   /** Extra panel classes merged after `class`. */
   panelClass?: string;
+  /** Classes applied to the built-in close button. */
   closeButtonClass?: string;
   /** Scrollable inner wrapper around the default slot. */
   contentClass?: string;

package/src/components/ModalTrigger.astro

@@ -3,7 +3,9 @@
  * Headless modal trigger. Clicking opens a <dialog> by ID.
  */
 interface Props {
+  /** Target dialog id to open via `showModal()`. */
   modalId: string;
+  /** Classes applied to the host trigger element. */
   class?: string;
 }
 

package/src/components/Pager.astro

@@ -0,0 +1,92 @@
+---
+interface Props {
+  /** Optional initial page count for static rendering. */
+  pageCount?: number;
+  /** Active page index (1-based) for static rendering. */
+  activePage?: number;
+  /** Classes applied to the pagination wrapper. */
+  class?: string;
+  /** Optional explicit pager items for link-based server rendering. */
+  items?: Array<
+    | { page: number; label?: string; href?: string; active?: boolean }
+    | { ellipsis: true; label?: string }
+  >;
+}
+
+const { pageCount = 0, activePage = 1, class: className = "", items = [] } = Astro.props;
+const fallbackPages = Array.from({ length: Math.max(0, pageCount) }, (_, index) => index + 1);
+---
+
+<div class:list={["af-pager flex items-center justify-center gap-2", className]} data-pagination>
+  {items.length > 0
+    ? items.map((item) =>
+        "ellipsis" in item ? (
+          <span class="af-pager-ellipsis" aria-hidden="true">{item.label ?? "…"}</span>
+        ) : item.href ? (
+          <a
+            href={item.href}
+            data-page={String(item.page)}
+            class:list={["af-pager-pill", item.active && "is-active"]}
+          >
+            {item.label ?? item.page}
+          </a>
+        ) : (
+          <button
+            type="button"
+            data-page={String(item.page)}
+            class:list={["af-pager-pill", item.active && "is-active"]}
+          >
+            {item.label ?? item.page}
+          </button>
+        ),
+      )
+    : fallbackPages.map((page) => (
+        <button
+          type="button"
+          data-page={String(page)}
+          class:list={["af-pager-pill", page === activePage && "is-active"]}
+        >
+          {page}
+        </button>
+      ))}
+</div>
+
+<style is:global>
+  .af-pager .af-pager-pill {
+    border-radius: 9999px;
+    border: 1px solid var(--color-light-border);
+    padding: 0.35rem 0.9rem;
+    font-size: 0.72rem;
+    font-weight: 500;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    color: color-mix(in oklab, var(--color-light-text-subtle) 78%, transparent);
+    background: color-mix(in oklab, var(--color-light-surface) 80%, transparent);
+    cursor: pointer;
+    text-decoration: none;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+  }
+  [data-theme="dark"] .af-pager .af-pager-pill {
+    border-color: var(--color-dark-border);
+    color: color-mix(in oklab, var(--color-dark-text-subtle) 78%, transparent);
+    background: color-mix(in oklab, var(--color-dark-surface) 70%, transparent);
+  }
+  .af-pager .af-pager-pill.is-active {
+    border-color: var(--color-secondary);
+    color: var(--color-secondary);
+    background: color-mix(in oklab, var(--color-secondary) 12%, transparent);
+  }
+  .af-pager .af-pager-ellipsis {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    min-width: 1.7rem;
+    font-size: 0.8rem;
+    color: color-mix(in oklab, var(--color-light-text-subtle) 75%, transparent);
+  }
+  [data-theme="dark"] .af-pager .af-pager-ellipsis {
+    color: color-mix(in oklab, var(--color-dark-text-subtle) 75%, transparent);
+  }
+</style>

package/src/components/Section.astro

@@ -1,7 +1,10 @@
 ---
 interface Props {
+  /** Optional section id attribute. */
   id?: string;
+  /** Additional classes merged onto the section container. */
   class?: string;
+  /** Use narrower inner max width (`max-w-4xl`) instead of default wide layout. */
   narrow?: boolean;
   /** Inner max-width wrapper only — no section padding (e.g. modal body). */
   contentOnly?: boolean;

package/src/components/TagSummary.astro

@@ -0,0 +1,71 @@
+---
+import Tooltip from "./Tooltip.astro";
+import { getTagPalette } from "../tag-colors";
+
+interface Props {
+  /** Ordered tag list to render as pills. */
+  items: string[];
+  /** Maximum number of visible tags before overflow summary is shown. */
+  visibleCount?: number;
+  /** Classes applied to the outer tag list wrapper. */
+  class?: string;
+  /** Classes applied to each visible tag pill. */
+  itemClass?: string;
+  /** Classes applied to the overflow `+N` chip. */
+  overflowClass?: string;
+  /** Optional value casing transform before render. */
+  itemCase?: "none" | "upper";
+  /** Explicit color map by lowercase tag key, overriding default hues. */
+  colorOverrides?: Record<string, string>;
+}
+
+const {
+  items,
+  visibleCount = 3,
+  class: className = "",
+  itemClass = "",
+  overflowClass = "",
+  itemCase = "upper",
+  colorOverrides,
+} = Astro.props;
+
+const formatItem = (item: string): string =>
+  itemCase === "upper" ? item.toUpperCase() : item;
+
+const visibleItems = items.slice(0, visibleCount);
+const overflowItems = items.slice(visibleCount);
+const overflowTooltip = overflowItems.map(formatItem).join(", ");
+---
+
+<div class:list={["flex flex-wrap gap-1.5", className]}>
+  {visibleItems.map((item) => {
+    const palette = getTagPalette(item, { overrides: colorOverrides });
+    return (
+      <span
+        style={{
+          backgroundColor: palette.bg,
+          borderColor: palette.border,
+          color: palette.text,
+        }}
+        class:list={[
+          "inline-block rounded-full border px-2.5 py-0.5 text-[0.68rem] font-medium uppercase tracking-[0.06em]",
+          itemClass,
+        ]}
+      >
+        {formatItem(item)}
+      </span>
+    );
+  })}
+  {overflowItems.length > 0 && (
+    <Tooltip text={overflowTooltip}>
+      <span
+        class:list={[
+          "inline-flex cursor-help items-center rounded-full border border-black/20 px-2.5 py-0.5 text-xs font-medium text-black/70 dark:border-white/20 dark:text-white/70",
+          overflowClass,
+        ]}
+      >
+        + {overflowItems.length}
+      </span>
+    </Tooltip>
+  )}
+</div>

package/src/components/ThemeToggle.astro

@@ -6,6 +6,7 @@
  * Sun/moon icons animate in/out with opacity and rotation transitions.
  */
 interface Props {
+  /** Classes applied to the custom-element host wrapper. */
   class?: string;
 }
 

package/src/components/Tooltip.astro

@@ -0,0 +1,70 @@
+---
+interface Props {
+  /** Plain text shown in the tooltip panel. */
+  text: string;
+  /** Tooltip placement relative to trigger content. */
+  position?: "top" | "bottom";
+  /** Classes applied to the trigger wrapper element. */
+  class?: string;
+  /** Classes applied to the tooltip panel element. */
+  panelClass?: string;
+}
+
+const { text, position = "top", class: className = "", panelClass = "" } = Astro.props;
+---
+
+<span class:list={["af-tooltip-root", className]} data-af-tooltip-root>
+  <slot />
+  <span
+    role="tooltip"
+    class="af-tooltip-panel"
+    class:list={[
+      panelClass,
+    ]}
+    data-position={position}
+  >
+    {text}
+  </span>
+</span>
+
+<style is:global>
+  [data-af-tooltip-root] {
+    position: relative;
+    display: inline-flex;
+    width: max-content;
+    justify-self: start;
+  }
+
+  [data-af-tooltip-root] .af-tooltip-panel {
+    pointer-events: none;
+    position: absolute;
+    left: 50%;
+    z-index: 30;
+    max-width: 20rem;
+    transform: translateX(-50%);
+    border-radius: 0.4rem;
+    border: 1px solid rgba(0, 0, 0, 0.2);
+    background: rgba(10, 10, 12, 0.92);
+    color: #fff;
+    font-size: 0.74rem;
+    line-height: 1.35;
+    padding: 0.35rem 0.55rem;
+    opacity: 0;
+    box-shadow: 0 8px 24px rgba(0, 0, 0, 0.22);
+    transition: opacity 150ms ease;
+    white-space: normal;
+  }
+
+  [data-af-tooltip-root] .af-tooltip-panel[data-position="top"] {
+    bottom: calc(100% + 0.45rem);
+  }
+
+  [data-af-tooltip-root] .af-tooltip-panel[data-position="bottom"] {
+    top: calc(100% + 0.45rem);
+  }
+
+  [data-af-tooltip-root]:hover .af-tooltip-panel,
+  [data-af-tooltip-root]:focus-within .af-tooltip-panel {
+    opacity: 1;
+  }
+</style>

package/src/components/collection-query-props.ts

@@ -0,0 +1,45 @@
+import type { CollectionQueryState } from "../collection-query";
+
+export interface CollectionQueryFilterOption {
+  key: string;
+  value: string;
+  label?: string;
+}
+
+interface CollectionQueryBaseProps {
+  /** Available filters for filter pill rendering. */
+  filters?: CollectionQueryFilterOption[];
+  /** Max visible pager buttons before ellipsis. */
+  maxPageButtons?: number;
+  /** Optional wrapper class for filter pills row. */
+  filtersClass?: string;
+  /** Optional wrapper class for pager row. */
+  pagerClass?: string;
+  /** Visible cards per page in client mode. */
+  perPage?: number;
+  /** Classes applied to the host wrapper element in client mode. */
+  class?: string;
+}
+
+export interface CollectionQueryServerProps extends CollectionQueryBaseProps {
+  /**
+   * Enables URL-driven server query mode.
+   * Mount with `server:defer` at the callsite when true.
+   */
+  useServer: true;
+  /** Route pathname used to build querystring links in server mode. */
+  pathname: string;
+  /** Parsed query state for the current request in server mode. */
+  query: CollectionQueryState;
+  /** Total pages for current filtered collection in server mode. */
+  totalPages: number;
+  /** Currently selected page (1-based) in server mode. */
+  currentPage: number;
+}
+
+export interface CollectionQueryClientProps extends CollectionQueryBaseProps {
+  /** Client mode (default): filters and pagination are handled in-browser. */
+  useServer?: false;
+}
+
+export type CollectionQueryProps = CollectionQueryServerProps | CollectionQueryClientProps;