@at-flux/astroflare 1.0.4 → 1.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@at-flux/astroflare",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "type": "module",
   "description": "Reusable headless components, styles, and utilities for Astro + Tailwind v4 + Cloudflare projects",
   "author": "atflux <dev@atflux.uk>",
@@ -54,6 +54,7 @@
   },
   "files": [
     "dist",
+    "src/*.ts",
     "src/components",
     "src/runtime",
     "src/styles",

package/src/collection-query.ts

@@ -0,0 +1,130 @@
+export interface CollectionQueryOptions {
+  defaultPage?: number;
+  defaultSize?: number;
+  maxSize?: number;
+}
+
+export interface CollectionQueryState {
+  page: number;
+  size: number;
+  offset: number;
+  filters: Record<string, string>;
+}
+
+export interface PaginationSlice<T> {
+  items: T[];
+  totalItems: number;
+  totalPages: number;
+  start: number;
+  end: number;
+}
+
+const toInt = (value: string | null, fallback: number): number => {
+  const parsed = Number.parseInt(value ?? "", 10);
+  return Number.isFinite(parsed) ? parsed : fallback;
+};
+
+export const parseCollectionQuery = (
+  searchParams: URLSearchParams,
+  options: CollectionQueryOptions = {},
+): CollectionQueryState => {
+  const { defaultPage = 1, defaultSize = 12, maxSize = 100 } = options;
+
+  const page = Math.max(1, toInt(searchParams.get("page"), defaultPage));
+  const size = Math.min(
+    maxSize,
+    Math.max(1, toInt(searchParams.get("size"), defaultSize)),
+  );
+  const fallbackOffset = (page - 1) * size;
+  const offset = Math.max(0, toInt(searchParams.get("offset"), fallbackOffset));
+  const rawFilters = searchParams.get("filters");
+  let filters: Record<string, string> = {};
+  if (rawFilters) {
+    try {
+      const parsed = JSON.parse(rawFilters) as Record<string, unknown>;
+      filters = Object.fromEntries(
+        Object.entries(parsed)
+          .filter(([, value]) => typeof value === "string")
+          .map(([key, value]) => [key, String(value)]),
+      );
+    } catch {
+      filters = {};
+    }
+  }
+
+  return { page, size, offset, filters };
+};
+
+export const paginateCollection = <T>(
+  list: T[],
+  query: CollectionQueryState,
+): PaginationSlice<T> => {
+  const totalItems = list.length;
+  const totalPages = Math.max(1, Math.ceil(totalItems / query.size));
+  const normalizedPage = Math.min(
+    totalPages,
+    Math.max(1, Math.floor(query.offset / query.size) + 1),
+  );
+  const start = (normalizedPage - 1) * query.size;
+  const end = start + query.size;
+
+  return {
+    items: list.slice(start, end),
+    totalItems,
+    totalPages,
+    start,
+    end: Math.min(end, totalItems),
+  };
+};
+
+export const buildCollectionHref = (
+  pathname: string,
+  query: CollectionQueryState,
+  overrides: Partial<CollectionQueryState> = {},
+): string => {
+  const next: CollectionQueryState = {
+    ...query,
+    ...overrides,
+  };
+  const normalizedOffset = (next.page - 1) * next.size;
+  const params = new URLSearchParams({
+    page: String(next.page),
+    size: String(next.size),
+    offset: String(next.offset ?? normalizedOffset),
+  });
+  if (Object.keys(next.filters ?? {}).length > 0) {
+    params.set("filters", JSON.stringify(next.filters));
+  }
+  return `${pathname}?${params.toString()}`;
+};
+
+export const matchesCollectionFilters = (
+  values: Record<string, string[]>,
+  filters: Record<string, string>,
+): boolean =>
+  Object.entries(filters).every(([key, value]) => {
+    const candidates = values[key] ?? [];
+    return candidates.includes(value);
+  });
+
+export const buildPageSequence = (
+  totalPages: number,
+  currentPage: number,
+  maxButtons = 7,
+): Array<number | "…"> => {
+  if (totalPages <= maxButtons) {
+    return Array.from({ length: totalPages }, (_, index) => index + 1);
+  }
+
+  const innerSlots = Math.max(1, maxButtons - 2);
+  const left = Math.max(2, currentPage - Math.floor(innerSlots / 2));
+  const right = Math.min(totalPages - 1, left + innerSlots - 1);
+  const adjustedLeft = Math.max(2, right - innerSlots + 1);
+
+  const sequence: Array<number | "…"> = [1];
+  if (adjustedLeft > 2) sequence.push("…");
+  for (let page = adjustedLeft; page <= right; page += 1) sequence.push(page);
+  if (right < totalPages - 1) sequence.push("…");
+  sequence.push(totalPages);
+  return sequence;
+};

package/src/core.ts

@@ -0,0 +1,8 @@
+// Opinionated core surface: forms utilities
+export * from "./forms/index";
+export * from "./tag-colors";
+export * from "./date-format";
+export * from "./collection-query";
+
+// Namespaced access for clearer call sites
+export * as forms from "./forms/index";

package/src/date-format.ts

@@ -0,0 +1,23 @@
+export interface DateFormatOptions {
+  /** BCP 47 locale tag used by `Intl.DateTimeFormat`. */
+  locale?: string;
+  /** Intl formatting options merged with defaults. */
+  options?: Intl.DateTimeFormatOptions;
+}
+
+const DEFAULT_OPTIONS: Intl.DateTimeFormatOptions = {
+  year: "numeric",
+  month: "long",
+  day: "numeric",
+};
+
+/**
+ * Format dates consistently for cards and article metadata.
+ */
+export const formatDisplayDate = (
+  date: Date | string | number,
+  config: DateFormatOptions = {},
+): string => {
+  const { locale = "en-GB", options = DEFAULT_OPTIONS } = config;
+  return new Intl.DateTimeFormat(locale, options).format(new Date(date));
+};

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./core";

package/src/tag-colors.ts

@@ -0,0 +1,89 @@
+export interface TagPalette {
+  /** Soft background fill for the tag surface. */
+  bg: string;
+  /** Border color paired with `bg` for tag outlines. */
+  border: string;
+  /** Foreground text color with readable contrast on `bg`. */
+  text: string;
+}
+
+export interface TagColorOptions {
+  /** Optional explicit tag-key to hex color map (expects lowercase keys). */
+  overrides?: Record<string, string>;
+}
+
+const DEFAULT_OVERRIDES: Record<string, string> = {
+  shoots: "#dc3545",
+  tech: "#8a95a5",
+  ai: "#6b7b8d",
+  sites: "#7dd3c0",
+  flow: "#b367e0",
+};
+
+const hashStringToHue = (input: string): number => {
+  let hash = 0;
+  for (let i = 0; i < input.length; i += 1) {
+    hash = (hash * 31 + input.charCodeAt(i)) >>> 0;
+  }
+  return hash % 360;
+};
+
+const hexToRgb = (hex: string): [number, number, number] | null => {
+  const value = hex.replace("#", "").trim();
+  if (!/^[0-9a-fA-F]{6}$/.test(value)) return null;
+  return [
+    Number.parseInt(value.slice(0, 2), 16),
+    Number.parseInt(value.slice(2, 4), 16),
+    Number.parseInt(value.slice(4, 6), 16),
+  ];
+};
+
+const rgbToHsl = (r: number, g: number, b: number): [number, number, number] => {
+  const red = r / 255;
+  const green = g / 255;
+  const blue = b / 255;
+  const max = Math.max(red, green, blue);
+  const min = Math.min(red, green, blue);
+  const delta = max - min;
+  const lightness = (max + min) / 2;
+  const saturation =
+    delta === 0 ? 0 : delta / (1 - Math.abs(2 * lightness - 1));
+
+  let hue = 0;
+  if (delta !== 0) {
+    if (max === red) hue = ((green - blue) / delta) % 6;
+    else if (max === green) hue = (blue - red) / delta + 2;
+    else hue = (red - green) / delta + 4;
+  }
+
+  return [
+    Math.round((hue * 60 + 360) % 360),
+    Math.round(saturation * 100),
+    Math.round(lightness * 100),
+  ];
+};
+
+const resolveHue = (tag: string, options: TagColorOptions): number => {
+  const key = tag.trim().toLowerCase();
+  const color = options.overrides?.[key] ?? DEFAULT_OVERRIDES[key];
+  if (!color) return hashStringToHue(key);
+  const rgb = hexToRgb(color);
+  if (!rgb) return hashStringToHue(key);
+  return rgbToHsl(...rgb)[0];
+};
+
+/**
+ * Build a deterministic HSL-based palette for a tag label.
+ * Uses known defaults and optional overrides before falling back to hashed hue.
+ */
+export const getTagPalette = (
+  tag: string,
+  options: TagColorOptions = {},
+): TagPalette => {
+  const hue = resolveHue(tag, options);
+  return {
+    bg: `hsla(${hue} 48% 58% / 0.12)`,
+    border: `hsla(${hue} 52% 58% / 0.34)`,
+    text: `hsl(${hue} 50% 66%)`,
+  };
+};