@caqophony/ui 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Caqophony
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,69 @@
-# Temporary Holding Version
+# @caqophony/ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Generic React UI components built on Gossamer semantic design tokens
+(Tailwind). Maintained centrally by Caqophony and MIT licensed.
+
+**This library is optional.** Apps generated by Caqophony may use it so that
+common UI (buttons, cards, dialogs, tables, page layout) is not regenerated
+from scratch for every app, which saves tokens. It is a courtesy, not an SDK:
+nothing in a generated app requires it. If reuse is turned off for a project,
+the app is built without this dependency and its components are written from
+scratch. It contains only generic UI: no platform, product, auth or
+data-access code.
+
+## Install
+
+```bash
+pnpm add @caqophony/ui        # or npm i / yarn add
+```
+
+Peer dependencies: `react` and `react-dom` (`^18 || ^19`). `@caqophony/ui/charts`
+requires the optional peers `chart.js` and `react-chartjs-2`: install them
+yourself if you import that subpath. No `next` dependency.
+
+The package is ESM-only. Subpath types (`@caqophony/ui/charts`) resolve through
+the `exports` map, so TypeScript needs `moduleResolution` of `bundler` (or
+`node16`/`nodenext`).
+
+`DiceBearAvatar` renders an image from `api.dicebear.com` at runtime, so it
+makes a network request from the user's browser; do not use it where that is
+unacceptable.
+
+## Styles (Tailwind v4)
+
+Components use Gossamer token classes (`bg-primary`, `text-muted-foreground`,
+`border-intent-error-border`, ...). Tailwind v4 does not scan `node_modules`
+and has no mapping for these names, so import the stylesheet this package
+ships, after Tailwind, in your global CSS:
+
+```css
+@import 'tailwindcss';
+@import '@caqophony/ui/styles.css';
+```
+
+`styles.css` defines the token variables (light, and dark under
+`@media (prefers-color-scheme: dark)`, the same OS setting Tailwind v4's `dark:`
+variant follows), maps them to
+Tailwind v4 colour/radius/z-index/opacity/duration utilities and registers the
+package's built files as a Tailwind `@source`. Override any `--token` after the
+import to re-theme.
+
+Tailwind v3 consumers: add `./node_modules/@caqophony/ui/dist/**/*.js` to
+`content` and map the same variables in `theme.extend.colors`.
+
+`animate-in` / `animate-out` (used by tooltips) come from `tailwindcss-animate`
+(v3) or `tw-animate-css` (v4); without it those animations are simply absent.
+
+## Use
+
+```tsx
+import { Button, Card, PageContent } from '@caqophony/ui';
+import { BarChart } from '@caqophony/ui/charts';
+import { MarkdownRenderer } from '@caqophony/ui/markdown';
+```
+
+Every entry point carries a `'use client'` directive.
+
+## Licence
+
+MIT, see `LICENSE`.

package/dist/charts.d.mts

@@ -0,0 +1,117 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+export { Chart as ChartJS } from 'chart.js';
+
+/**
+ * Chart Types - Shared type definitions for chart components
+ *
+ * Authored by Caqophony
+ */
+interface ChartDataPoint {
+    label: string;
+    value: number;
+}
+interface TimeSeriesDataPoint {
+    date: string | Date;
+    value: number;
+    secondaryValue?: number;
+}
+interface BaseChartProps {
+    /** Height of the chart container */
+    height?: number | string;
+    /** Whether to show the legend */
+    showLegend?: boolean;
+    /** Empty state message when no data */
+    emptyMessage?: string;
+    /** Additional CSS classes */
+    className?: string;
+}
+interface LineChartProps extends BaseChartProps {
+    data: TimeSeriesDataPoint[];
+    /** Label for the primary dataset */
+    label?: string;
+    /** Label for the secondary dataset (if secondaryValue provided) */
+    secondaryLabel?: string;
+    /** Primary line color */
+    color?: string;
+    /** Secondary line color */
+    secondaryColor?: string;
+    /** Fill area under line */
+    fill?: boolean;
+    /** Date format for labels */
+    dateFormat?: Intl.DateTimeFormatOptions;
+}
+interface BarChartProps extends BaseChartProps {
+    data: ChartDataPoint[];
+    /** Label for the dataset */
+    label?: string;
+    /** Bar color */
+    color?: string;
+    /** Horizontal bar chart */
+    horizontal?: boolean;
+}
+interface DoughnutChartProps extends BaseChartProps {
+    data: ChartDataPoint[];
+    /** Colors for each segment */
+    colors?: string[];
+    /** Show percentage labels */
+    showPercentage?: boolean;
+}
+type NumberFormatMode = 'compact' | 'full' | 'currency';
+
+declare function LineChart({ data, label, secondaryLabel, color, secondaryColor, fill, showLegend, height, emptyMessage, dateFormat, className, }: LineChartProps): react_jsx_runtime.JSX.Element;
+
+declare function BarChart({ data, label, color, horizontal, showLegend, height, emptyMessage, className, }: BarChartProps): react_jsx_runtime.JSX.Element;
+
+declare function DoughnutChart({ data, colors, showPercentage, showLegend, height, emptyMessage, className, }: DoughnutChartProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * ChartSkeleton - Loading state for chart components
+ *
+ * @example
+ * ```tsx
+ * import { ChartSkeleton } from '@caqophony/ui/charts';
+ *
+ * {isLoading ? <ChartSkeleton /> : <LineChart data={data} />}
+ * ```
+ *
+ * Authored by Caqophony
+ */
+interface ChartSkeletonProps {
+    height?: number | string;
+    className?: string;
+}
+declare function ChartSkeleton({ height, className }: ChartSkeletonProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Chart Utilities - Shared formatting and helper functions
+ *
+ * Authored by Caqophony
+ */
+
+/**
+ * Format a number for display in charts (compact: 1K, 1M, etc.)
+ */
+declare function formatNumber(value: number, mode?: NumberFormatMode): string;
+/**
+ * Format a date for chart labels
+ */
+declare function formatDateLabel(date: string | Date, options?: Intl.DateTimeFormatOptions): string;
+/**
+ * Generate colors for chart segments
+ */
+declare function generateColors(count: number): string[];
+/**
+ * Default chart colors
+ */
+declare const CHART_COLORS: {
+    readonly primary: "rgb(59, 130, 246)";
+    readonly primaryFill: "rgba(59, 130, 246, 0.1)";
+    readonly secondary: "rgb(147, 51, 234)";
+    readonly secondaryFill: "rgba(147, 51, 234, 0.1)";
+    readonly success: "rgb(34, 197, 94)";
+    readonly warning: "rgb(234, 179, 8)";
+    readonly danger: "rgb(239, 68, 68)";
+    readonly gray: "rgb(107, 114, 128)";
+};
+
+export { BarChart, type BarChartProps, type BaseChartProps, CHART_COLORS, type ChartDataPoint, ChartSkeleton, DoughnutChart, type DoughnutChartProps, LineChart, type LineChartProps, type NumberFormatMode, type TimeSeriesDataPoint, formatDateLabel, formatNumber, generateColors };

package/dist/charts.js

@@ -0,0 +1,367 @@
+'use client';
+
+// src/charts/line-chart.tsx
+import { useMemo } from "react";
+import { Line } from "react-chartjs-2";
+
+// src/charts/utils.ts
+function formatNumber(value, mode = "compact") {
+  if (mode === "currency") {
+    return new Intl.NumberFormat("en-US", {
+      style: "currency",
+      currency: "USD",
+      minimumFractionDigits: 0,
+      maximumFractionDigits: 0
+    }).format(value);
+  }
+  if (mode === "full") {
+    return value.toLocaleString();
+  }
+  if (value >= 1e6) {
+    return `${(value / 1e6).toFixed(1)}M`;
+  }
+  if (value >= 1e3) {
+    return `${Math.round(value / 1e3)}K`;
+  }
+  return value.toString();
+}
+function formatDateLabel(date, options = { month: "short", day: "numeric" }) {
+  const d = typeof date === "string" ? new Date(date) : date;
+  return d.toLocaleDateString("en-US", options);
+}
+function generateColors(count) {
+  return Array.from({ length: count }, (_, i) => {
+    const hue = i * 360 / count;
+    return `hsla(${hue}, 70%, 60%, 0.8)`;
+  });
+}
+var CHART_COLORS = {
+  primary: "rgb(59, 130, 246)",
+  // blue-500
+  primaryFill: "rgba(59, 130, 246, 0.1)",
+  secondary: "rgb(147, 51, 234)",
+  // purple-600
+  secondaryFill: "rgba(147, 51, 234, 0.1)",
+  success: "rgb(34, 197, 94)",
+  // green-500
+  warning: "rgb(234, 179, 8)",
+  // yellow-500
+  danger: "rgb(239, 68, 68)",
+  // red-500
+  gray: "rgb(107, 114, 128)"
+  // gray-500
+};
+var BASE_CHART_OPTIONS = {
+  responsive: true,
+  maintainAspectRatio: false,
+  interaction: {
+    intersect: false,
+    mode: "index"
+  }
+};
+
+// src/charts/chart-registry.ts
+import {
+  Chart as ChartJS,
+  CategoryScale,
+  LinearScale,
+  PointElement,
+  LineElement,
+  BarElement,
+  ArcElement,
+  Title,
+  Tooltip,
+  Legend,
+  Filler
+} from "chart.js";
+ChartJS.register(
+  CategoryScale,
+  LinearScale,
+  PointElement,
+  LineElement,
+  BarElement,
+  ArcElement,
+  Title,
+  Tooltip,
+  Legend,
+  Filler
+);
+
+// src/charts/line-chart.tsx
+import { jsx } from "react/jsx-runtime";
+function LineChart({
+  data,
+  label = "Value",
+  secondaryLabel,
+  color = CHART_COLORS.primary,
+  secondaryColor = CHART_COLORS.secondary,
+  fill = false,
+  showLegend = false,
+  height = 256,
+  emptyMessage = "No data available",
+  dateFormat,
+  className
+}) {
+  const chartData = useMemo(() => {
+    const labels = data.map((d) => formatDateLabel(d.date, dateFormat));
+    const datasets = [
+      {
+        label,
+        data: data.map((d) => d.value),
+        borderColor: color,
+        backgroundColor: fill ? color.replace("rgb", "rgba").replace(")", ", 0.1)") : "transparent",
+        fill,
+        tension: 0.3,
+        pointRadius: 3,
+        pointHoverRadius: 5
+      }
+    ];
+    if (data.some((d) => d.secondaryValue !== void 0) && secondaryLabel) {
+      datasets.push({
+        label: secondaryLabel,
+        data: data.map((d) => d.secondaryValue ?? 0),
+        borderColor: secondaryColor,
+        backgroundColor: "transparent",
+        fill: false,
+        tension: 0.3,
+        pointRadius: 2,
+        pointHoverRadius: 5
+      });
+    }
+    return { labels, datasets };
+  }, [data, label, secondaryLabel, color, secondaryColor, fill, dateFormat]);
+  const options = useMemo(
+    () => ({
+      ...BASE_CHART_OPTIONS,
+      plugins: {
+        legend: {
+          display: showLegend,
+          position: "top"
+        },
+        tooltip: {
+          callbacks: {
+            label: (context) => {
+              const val = context.parsed.y ?? 0;
+              return `${context.dataset.label}: ${formatNumber(val)}`;
+            }
+          }
+        }
+      },
+      scales: {
+        x: {
+          grid: {
+            display: false
+          }
+        },
+        y: {
+          beginAtZero: true,
+          ticks: {
+            callback: (tickValue) => {
+              if (tickValue === null) return "";
+              const value = typeof tickValue === "number" ? tickValue : parseFloat(String(tickValue));
+              return formatNumber(value);
+            }
+          }
+        }
+      }
+    }),
+    [showLegend]
+  );
+  if (data.length === 0) {
+    return /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: `flex items-center justify-center text-gray-500 ${className ?? ""}`,
+        style: { height },
+        children: emptyMessage
+      }
+    );
+  }
+  return /* @__PURE__ */ jsx("div", { className, style: { height }, children: /* @__PURE__ */ jsx(Line, { data: chartData, options }) });
+}
+
+// src/charts/bar-chart.tsx
+import { useMemo as useMemo2 } from "react";
+import { Bar } from "react-chartjs-2";
+import { jsx as jsx2 } from "react/jsx-runtime";
+function BarChart({
+  data,
+  label = "Value",
+  color = CHART_COLORS.primary,
+  horizontal = false,
+  showLegend = false,
+  height = 256,
+  emptyMessage = "No data available",
+  className
+}) {
+  const chartData = useMemo2(() => {
+    const labels = data.map((d) => d.label);
+    const colors = data.length > 1 ? generateColors(data.length) : [color];
+    return {
+      labels,
+      datasets: [
+        {
+          label,
+          data: data.map((d) => d.value),
+          backgroundColor: colors,
+          borderColor: colors.map((c) => c.replace("0.8", "1")),
+          borderWidth: 1
+        }
+      ]
+    };
+  }, [data, label, color]);
+  const options = useMemo2(
+    () => ({
+      ...BASE_CHART_OPTIONS,
+      indexAxis: horizontal ? "y" : "x",
+      plugins: {
+        legend: {
+          display: showLegend
+        },
+        tooltip: {
+          callbacks: {
+            label: (context) => {
+              const val = horizontal ? context.parsed.x ?? 0 : context.parsed.y ?? 0;
+              return `${context.dataset.label}: ${formatNumber(val)}`;
+            }
+          }
+        }
+      },
+      scales: {
+        x: {
+          beginAtZero: true,
+          ticks: horizontal ? {
+            callback: (tickValue) => {
+              if (tickValue === null) return "";
+              const value = typeof tickValue === "number" ? tickValue : parseFloat(String(tickValue));
+              return formatNumber(value);
+            }
+          } : void 0
+        },
+        y: {
+          beginAtZero: true,
+          ticks: !horizontal ? {
+            callback: (tickValue) => {
+              if (tickValue === null) return "";
+              const value = typeof tickValue === "number" ? tickValue : parseFloat(String(tickValue));
+              return formatNumber(value);
+            }
+          } : void 0
+        }
+      }
+    }),
+    [horizontal, showLegend]
+  );
+  if (data.length === 0) {
+    return /* @__PURE__ */ jsx2(
+      "div",
+      {
+        className: `flex items-center justify-center text-gray-500 ${className ?? ""}`,
+        style: { height },
+        children: emptyMessage
+      }
+    );
+  }
+  return /* @__PURE__ */ jsx2("div", { className, style: { height }, children: /* @__PURE__ */ jsx2(Bar, { data: chartData, options }) });
+}
+
+// src/charts/doughnut-chart.tsx
+import { useMemo as useMemo3 } from "react";
+import { Doughnut } from "react-chartjs-2";
+import { jsx as jsx3 } from "react/jsx-runtime";
+function DoughnutChart({
+  data,
+  colors,
+  showPercentage = false,
+  showLegend = true,
+  height = 256,
+  emptyMessage = "No data available",
+  className
+}) {
+  const total = useMemo3(
+    () => data.reduce((sum, d) => sum + d.value, 0),
+    [data]
+  );
+  const chartData = useMemo3(() => {
+    const labels = data.map((d) => d.label);
+    const chartColors = colors ?? generateColors(data.length);
+    return {
+      labels,
+      datasets: [
+        {
+          data: data.map((d) => d.value),
+          backgroundColor: chartColors,
+          borderColor: chartColors.map((c) => c.replace("0.8", "1")),
+          borderWidth: 1
+        }
+      ]
+    };
+  }, [data, colors]);
+  const options = useMemo3(
+    () => ({
+      ...BASE_CHART_OPTIONS,
+      plugins: {
+        legend: {
+          display: showLegend,
+          position: "right"
+        },
+        tooltip: {
+          callbacks: {
+            label: (context) => {
+              const val = context.parsed;
+              const percentage = total > 0 ? Math.round(val / total * 100) : 0;
+              if (showPercentage) {
+                return `${context.label}: ${formatNumber(val)} (${percentage}%)`;
+              }
+              return `${context.label}: ${formatNumber(val)}`;
+            }
+          }
+        }
+      }
+    }),
+    [showLegend, showPercentage, total]
+  );
+  if (data.length === 0) {
+    return /* @__PURE__ */ jsx3(
+      "div",
+      {
+        className: `flex items-center justify-center text-gray-500 ${className ?? ""}`,
+        style: { height },
+        children: emptyMessage
+      }
+    );
+  }
+  return /* @__PURE__ */ jsx3("div", { className, style: { height }, children: /* @__PURE__ */ jsx3(Doughnut, { data: chartData, options }) });
+}
+
+// src/charts/chart-skeleton.tsx
+import { jsx as jsx4, jsxs } from "react/jsx-runtime";
+function ChartSkeleton({ height = 256, className }) {
+  return /* @__PURE__ */ jsx4(
+    "div",
+    {
+      className: `animate-pulse rounded-lg bg-gray-100 ${className ?? ""}`,
+      style: { height },
+      children: /* @__PURE__ */ jsxs("div", { className: "flex h-full items-end justify-around gap-2 p-4", children: [
+        /* @__PURE__ */ jsx4("div", { className: "h-1/3 w-8 rounded-t bg-gray-200" }),
+        /* @__PURE__ */ jsx4("div", { className: "h-1/2 w-8 rounded-t bg-gray-200" }),
+        /* @__PURE__ */ jsx4("div", { className: "h-2/3 w-8 rounded-t bg-gray-200" }),
+        /* @__PURE__ */ jsx4("div", { className: "h-1/2 w-8 rounded-t bg-gray-200" }),
+        /* @__PURE__ */ jsx4("div", { className: "h-3/4 w-8 rounded-t bg-gray-200" }),
+        /* @__PURE__ */ jsx4("div", { className: "h-1/3 w-8 rounded-t bg-gray-200" }),
+        /* @__PURE__ */ jsx4("div", { className: "h-1/2 w-8 rounded-t bg-gray-200" })
+      ] })
+    }
+  );
+}
+export {
+  BarChart,
+  CHART_COLORS,
+  ChartJS,
+  ChartSkeleton,
+  DoughnutChart,
+  LineChart,
+  formatDateLabel,
+  formatNumber,
+  generateColors
+};

package/dist/chunk-4YA6BZDJ.js

@@ -0,0 +1,72 @@
+'use client';
+
+// src/markdown-renderer.tsx
+import { memo } from "react";
+import ReactMarkdown from "react-markdown";
+import remarkGfm from "remark-gfm";
+
+// src/utils.ts
+import { clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+function cn(...inputs) {
+  return twMerge(clsx(inputs));
+}
+
+// src/markdown-renderer.tsx
+import { Fragment, jsx } from "react/jsx-runtime";
+var components = {
+  // Links open in new tab
+  a: ({ children, href, ...props }) => /* @__PURE__ */ jsx("a", { href, target: "_blank", rel: "noopener noreferrer", ...props, children }),
+  // Pre blocks pass through children (code block handles its own styling)
+  pre: ({ children }) => /* @__PURE__ */ jsx(Fragment, { children })
+};
+var remarkPlugins = [remarkGfm];
+function getProseClasses(size, className) {
+  return cn(
+    // Base prose sizing
+    size === "sm" ? "prose prose-sm" : "prose",
+    // Let parent container control width
+    "max-w-none",
+    // Headings
+    "prose-headings:text-foreground dark:prose-headings:text-foreground prose-headings:font-semibold",
+    // Body text
+    "prose-p:text-foreground dark:prose-p:text-foreground",
+    // Strong/bold
+    "prose-strong:text-foreground dark:prose-strong:text-foreground",
+    // Emphasis/italic
+    "prose-em:text-foreground dark:prose-em:text-foreground",
+    // Links
+    "prose-a:text-primary-text dark:prose-a:text-primary-text prose-a:no-underline hover:prose-a:underline",
+    // Lists
+    "prose-li:text-foreground dark:prose-li:text-foreground",
+    // Inline code
+    "prose-code:text-foreground dark:prose-code:text-foreground prose-code:bg-muted dark:prose-code:bg-muted prose-code:rounded prose-code:px-1.5 prose-code:py-0.5 prose-code:text-[0.85em] prose-code:font-normal prose-code:before:content-none prose-code:after:content-none",
+    // Code blocks
+    "prose-pre:bg-muted dark:prose-pre:bg-muted prose-pre:text-foreground dark:prose-pre:text-foreground prose-pre:rounded-md",
+    // Blockquotes
+    "prose-blockquote:text-muted-foreground dark:prose-blockquote:text-muted-foreground prose-blockquote:border-border dark:prose-blockquote:border-border",
+    // Horizontal rules
+    "prose-hr:border-border dark:prose-hr:border-border",
+    // Tables
+    "prose-th:text-foreground dark:prose-th:text-foreground prose-th:border-border dark:prose-th:border-border",
+    "prose-td:text-foreground dark:prose-td:text-foreground prose-td:border-border dark:prose-td:border-border",
+    className
+  );
+}
+function NonMemoizedMarkdownRenderer({
+  children,
+  className,
+  size = "sm"
+}) {
+  return /* @__PURE__ */ jsx("div", { className: getProseClasses(size, className), children: /* @__PURE__ */ jsx(ReactMarkdown, { remarkPlugins, components, children }) });
+}
+var MarkdownRenderer = memo(
+  NonMemoizedMarkdownRenderer,
+  (prev, next) => prev.children === next.children && prev.className === next.className && prev.size === next.size
+);
+MarkdownRenderer.displayName = "MarkdownRenderer";
+
+export {
+  cn,
+  MarkdownRenderer
+};