@uoa-css-lab/duckscatter 1.3.0

package/eslint.config.js

@@ -0,0 +1,72 @@
+const eslint = require('@eslint/js');
+const tseslint = require('typescript-eslint');
+const prettierPlugin = require('eslint-plugin-prettier');
+const prettierConfig = require('eslint-config-prettier');
+
+module.exports = tseslint.config(
+  // Base ESLint recommended config
+  eslint.configs.recommended,
+
+  // TypeScript ESLint recommended configs
+  ...tseslint.configs.recommended,
+
+  // Prettier integration
+  {
+    plugins: {
+      prettier: prettierPlugin,
+    },
+    rules: {
+      ...prettierConfig.rules,
+      'prettier/prettier': 'error',
+    },
+  },
+
+  // Custom configuration
+  {
+    files: ['**/*.ts', '**/*.tsx'],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      parser: tseslint.parser,
+      parserOptions: {
+        project: './tsconfig.json',
+      },
+    },
+    rules: {
+      '@typescript-eslint/explicit-function-return-type': 'off',
+      '@typescript-eslint/no-explicit-any': 'warn',
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        {
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+        },
+      ],
+      '@typescript-eslint/consistent-type-imports': 'error',
+      'no-console': 'warn',
+    },
+  },
+
+  // Files to ignore
+  {
+    ignores: [
+      'node_modules/**',
+      'dist/**',
+      'build/**',
+      '*.js',
+      '*.d.ts',
+      '*.config.js',
+      '*.config.ts',
+      'package-lock.json',
+      'pnpm-lock.yaml',
+      'yarn.lock',
+      '.vscode/**',
+      '.idea/**',
+      '*.tmp',
+      '*.log',
+      'temp/**',
+      'tmp/**',
+      'examples/next/**',
+    ],
+  }
+);

package/examples/next/README.md

@@ -0,0 +1,36 @@
+This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+
+## Getting Started
+
+First, run the development server:
+
+```bash
+npm run dev
+# or
+yarn dev
+# or
+pnpm dev
+# or
+bun dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+
+You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+
+This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+
+## Learn More
+
+To learn more about Next.js, take a look at the following resources:
+
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
+- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+
+You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+
+## Deploy on Vercel
+
+The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+
+Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.

package/examples/next/app/components/ColorExpressionInput.tsx

@@ -0,0 +1,41 @@
+'use client';
+
+import { useState, useEffect } from 'react';
+import { useScatterPlot } from '../context/ScatterPlotContext';
+
+export function ColorExpressionInput() {
+  const [color, setColor] = useState('#3b82f6');
+  const [error, setError] = useState<string | null>(null);
+  const { updateColor } = useScatterPlot();
+
+  useEffect(() => {
+    const timer = setTimeout(async () => {
+      try {
+        setError(null);
+        const r = parseInt(color.slice(1, 3), 16);
+        const g = parseInt(color.slice(3, 5), 16);
+        const b = parseInt(color.slice(5, 7), 16);
+        const a = 255;
+        const calc = `(CAST(${a} AS BIGINT) * 16777216 + ${r} * 65536 + ${g} * 256 + ${b})`;
+        const colorSql = `(${calc} - CASE WHEN ${calc} > 2147483647 THEN 4294967296 ELSE 0 END)::INTEGER`;
+        await updateColor(colorSql);
+      } catch (e) {
+        setError(e instanceof Error ? e.message : 'Invalid color');
+      }
+    }, 100);
+    return () => clearTimeout(timer);
+  }, [color, updateColor]);
+
+  return (
+    <div className="flex flex-col gap-2">
+      <label className="text-sm font-medium text-zinc-700">Point Color</label>
+      <input
+        type="color"
+        value={color}
+        onChange={(e) => setColor(e.target.value)}
+        className="w-full h-10 cursor-pointer rounded border border-zinc-300"
+      />
+      {error && <p className="text-red-500 text-xs">{error}</p>}
+    </div>
+  );
+}

package/examples/next/app/components/ControlPanel.tsx

@@ -0,0 +1,30 @@
+'use client';
+
+import { PointAlphaSlider } from './PointAlphaSlider';
+import { PointSizeScaleSlider } from './PointSizeScaleSlider';
+import { ColorExpressionInput } from './ColorExpressionInput';
+import { SearchBox } from './SearchBox';
+import { LabelFilterInput } from './LabelFilterInput';
+import { PointLimitSlider } from './PointLimitSlider';
+import { StatsDisplay } from './StatsDisplay';
+import { HoverControlPanel } from './HoverControlPanel';
+import { TimeFilterSlider } from './TimeFilterSlider';
+
+export function ControlPanel() {
+  return (
+    <div className="w-80 bg-zinc-100 border-r border-zinc-300 p-4 flex flex-col gap-4 overflow-y-auto">
+      <div className="flex items-center justify-between">
+        <h2 className="text-lg font-semibold text-zinc-800">Controls</h2>
+        <StatsDisplay />
+      </div>
+      <PointLimitSlider />
+      <PointAlphaSlider />
+      <PointSizeScaleSlider />
+      <TimeFilterSlider />
+      <ColorExpressionInput />
+      <SearchBox />
+      <LabelFilterInput />
+      <HoverControlPanel />
+    </div>
+  );
+}

package/examples/next/app/components/HoverControlPanel.tsx

@@ -0,0 +1,69 @@
+'use client';
+
+import { useState } from 'react';
+import { useScatterPlot } from '../context/ScatterPlotContext';
+import { PointList } from './PointList';
+import { LabelList } from './LabelList';
+
+type Tab = 'points' | 'labels';
+
+export function HoverControlPanel() {
+  const { state, clearAllHover } = useScatterPlot();
+  const [activeTab, setActiveTab] = useState<Tab>('points');
+
+  return (
+    <div className="flex flex-col gap-3">
+      <label className="text-sm font-medium text-zinc-700">Hover Control</label>
+
+      {/* Tabs */}
+      <div className="flex border-b border-zinc-200">
+        <button
+          onClick={() => setActiveTab('points')}
+          className={`px-3 py-1.5 text-sm font-medium border-b-2 -mb-px transition-colors ${
+            activeTab === 'points'
+              ? 'border-blue-500 text-blue-600'
+              : 'border-transparent text-zinc-500 hover:text-zinc-700'
+          }`}
+        >
+          Points
+        </button>
+        <button
+          onClick={() => setActiveTab('labels')}
+          className={`px-3 py-1.5 text-sm font-medium border-b-2 -mb-px transition-colors ${
+            activeTab === 'labels'
+              ? 'border-blue-500 text-blue-600'
+              : 'border-transparent text-zinc-500 hover:text-zinc-700'
+          }`}
+        >
+          Labels
+        </button>
+      </div>
+
+      {/* Tab content */}
+      <div className="min-h-[200px]">
+        {activeTab === 'points' && <PointList />}
+        {activeTab === 'labels' && <LabelList />}
+      </div>
+
+      {/* Clear button */}
+      <button
+        onClick={() => clearAllHover()}
+        className="px-3 py-1.5 bg-zinc-200 text-zinc-700 text-sm rounded hover:bg-zinc-300"
+      >
+        Clear All Hover
+      </button>
+
+      {/* Current hover state */}
+      <div className="text-xs text-zinc-500 border-t border-zinc-200 pt-2">
+        <div>
+          <span className="font-medium">Point:</span>{' '}
+          {state.hoveredPoint ? 'Hovered' : 'None'}
+        </div>
+        <div>
+          <span className="font-medium">Label:</span>{' '}
+          {state.hoveredLabel ? state.hoveredLabel.text : 'None'}
+        </div>
+      </div>
+    </div>
+  );
+}

package/examples/next/app/components/HoverInfoDisplay.tsx

@@ -0,0 +1,40 @@
+'use client';
+
+import { useMemo } from 'react';
+import { useScatterPlot } from '../context/ScatterPlotContext';
+
+interface HoverInfoDisplayProps {
+  mousePosition: { x: number; y: number };
+}
+
+export function HoverInfoDisplay({ mousePosition }: HoverInfoDisplayProps) {
+  const { state } = useScatterPlot();
+
+  const formattedData = useMemo(() => {
+    if (!state.hoveredPoint) return null;
+
+    const { row, columns } = state.hoveredPoint;
+    const obj: Record<string, unknown> = {};
+    columns.forEach((col, i) => {
+      const val = row[i];
+      obj[col] = typeof val === 'bigint' ? Number(val) : val;
+    });
+    return JSON.stringify(obj, null, 2);
+  }, [state.hoveredPoint]);
+
+  if (!formattedData) return null;
+
+  return (
+    <div
+      className="fixed z-50 pointer-events-none"
+      style={{
+        left: mousePosition.x + 15,
+        top: mousePosition.y - 10,
+      }}
+    >
+      <pre className="p-2 bg-white border border-zinc-300 rounded shadow-lg text-zinc-700 text-xs max-w-xs">
+        {formattedData}
+      </pre>
+    </div>
+  );
+}

package/examples/next/app/components/LabelFilterInput.tsx

@@ -0,0 +1,46 @@
+'use client';
+
+import { useState, useRef, useEffect } from 'react';
+import { useScatterPlot } from '../context/ScatterPlotContext';
+
+export function LabelFilterInput() {
+  const [value, setValue] = useState('');
+  const { updateLabelFilter } = useScatterPlot();
+  const debounceRef = useRef<NodeJS.Timeout | null>(null);
+
+  useEffect(() => {
+    if (debounceRef.current) {
+      clearTimeout(debounceRef.current);
+    }
+    debounceRef.current = setTimeout(() => {
+      updateLabelFilter(value);
+    }, 300);
+
+    return () => {
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current);
+      }
+    };
+  }, [value, updateLabelFilter]);
+
+  return (
+    <div className="flex flex-col gap-2">
+      <label className="text-sm font-medium text-zinc-700">Filter Labels</label>
+      <input
+        type="text"
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        placeholder="Filter by label name..."
+        className="px-3 py-2 bg-white border border-zinc-300 rounded text-zinc-800 text-sm"
+      />
+      {value && (
+        <button
+          onClick={() => setValue('')}
+          className="text-xs text-zinc-500 hover:text-zinc-800 self-start"
+        >
+          Clear filter
+        </button>
+      )}
+    </div>
+  );
+}

package/examples/next/app/components/LabelList.tsx

@@ -0,0 +1,106 @@
+'use client';
+
+import { useState, useMemo } from 'react';
+import type { Label } from '@uoa-css-lab/duckscatter';
+import { useScatterPlot } from '../context/ScatterPlotContext';
+
+const PAGE_SIZE = 20;
+
+export function LabelList() {
+  const { state, getLabels, setLabelHover } = useScatterPlot();
+  const [page, setPage] = useState(0);
+
+  // Load and sort labels by count (descending)
+  const labels = useMemo(() => {
+    if (!state.isInitialized) return [];
+    const allLabels = getLabels();
+    return [...allLabels].sort((a, b) => (b.count ?? 0) - (a.count ?? 0));
+  }, [state.isInitialized, getLabels]);
+
+  // Paginate labels
+  const pagedLabels = useMemo(() => {
+    const start = page * PAGE_SIZE;
+    return labels.slice(start, start + PAGE_SIZE);
+  }, [labels, page]);
+
+  const totalPages = Math.ceil(labels.length / PAGE_SIZE);
+
+  const handlePrev = () => {
+    if (page > 0) setPage(page - 1);
+  };
+
+  const handleNext = () => {
+    if (page < totalPages - 1) setPage(page + 1);
+  };
+
+  const handleLabelClick = (label: Label) => {
+    setLabelHover({ text: label.text });
+  };
+
+  // Check if a label is currently hovered
+  const isHovered = (label: Label) => {
+    return state.hoveredLabel?.text === label.text;
+  };
+
+  if (!state.isInitialized) {
+    return <div className="text-xs text-zinc-400">Not initialized</div>;
+  }
+
+  if (labels.length === 0) {
+    return <div className="text-xs text-zinc-400">No labels</div>;
+  }
+
+  return (
+    <div className="flex flex-col gap-2">
+      {/* List */}
+      <div className="max-h-48 overflow-y-auto border border-zinc-200 rounded bg-white">
+        {pagedLabels.map((label, idx) => (
+          <div
+            key={`${label.text}-${idx}`}
+            onClick={() => handleLabelClick(label)}
+            className={`px-2 py-1 text-xs cursor-pointer border-b border-zinc-100 last:border-b-0 hover:bg-blue-50 ${
+              isHovered(label) ? 'bg-blue-100 font-medium' : ''
+            }`}
+          >
+            <div className="flex justify-between items-center">
+              <span className="text-zinc-700 truncate flex-1">{label.text}</span>
+              {label.count !== undefined && (
+                <span className="text-zinc-400 ml-2">({label.count})</span>
+              )}
+            </div>
+            {label.cluster !== undefined && (
+              <span className="text-zinc-400 text-[10px]">cluster: {label.cluster}</span>
+            )}
+          </div>
+        ))}
+      </div>
+
+      {/* Pagination */}
+      {totalPages > 1 && (
+        <div className="flex items-center justify-between text-xs">
+          <button
+            onClick={handlePrev}
+            disabled={page === 0}
+            className="px-2 py-1 bg-zinc-100 rounded hover:bg-zinc-200 disabled:opacity-50 disabled:cursor-not-allowed"
+          >
+            Prev
+          </button>
+          <span className="text-zinc-500">
+            {page + 1} / {totalPages}
+          </span>
+          <button
+            onClick={handleNext}
+            disabled={page >= totalPages - 1}
+            className="px-2 py-1 bg-zinc-100 rounded hover:bg-zinc-200 disabled:opacity-50 disabled:cursor-not-allowed"
+          >
+            Next
+          </button>
+        </div>
+      )}
+
+      <div className="text-[10px] text-zinc-400">
+        Total: {labels.length} labels
+      </div>
+    </div>
+  );
+}

package/examples/next/app/components/PointAlphaSlider.tsx

@@ -0,0 +1,21 @@
+'use client';
+
+import { useScatterPlot } from '../context/ScatterPlotContext';
+import { Slider } from './Slider';
+
+export function PointAlphaSlider() {
+  const { updatePointAlpha } = useScatterPlot();
+
+  return (
+    <Slider
+      label="Point Alpha"
+      min={0}
+      max={1}
+      step={0.01}
+      defaultValue={1.0}
+      onChange={updatePointAlpha}
+      minLabel="0"
+      maxLabel="1"
+    />
+  );
+}

package/examples/next/app/components/PointLimitSlider.tsx

@@ -0,0 +1,23 @@
+'use client';
+
+import { useScatterPlot } from '../context/ScatterPlotContext';
+import { Slider } from './Slider';
+
+export function PointLimitSlider() {
+  const { updatePointLimit } = useScatterPlot();
+
+  return (
+    <Slider
+      label="Visible Points"
+      min={10000}
+      max={5000000}
+      step={1000}
+      defaultValue={100000}
+      onChange={updatePointLimit}
+      parseValue={(v) => parseInt(v, 10)}
+      formatValue={(v) => v.toLocaleString()}
+      minLabel="1K"
+      maxLabel="5M"
+    />
+  );
+}

package/examples/next/app/components/PointList.tsx

@@ -0,0 +1,105 @@
+'use client';
+
+import { useState, useEffect, useCallback } from 'react';
+import { useScatterPlot, type PointListItem } from '../context/ScatterPlotContext';
+
+const PAGE_SIZE = 20;
+
+export function PointList() {
+  const { state, fetchPoints, setPointHover } = useScatterPlot();
+  const [points, setPoints] = useState<PointListItem[]>([]);
+  const [page, setPage] = useState(0);
+  const [isLoading, setIsLoading] = useState(false);
+
+  const totalPages = state.pointCount ? Math.ceil(state.pointCount / PAGE_SIZE) : 0;
+
+  const loadPage = useCallback(
+    async (pageNum: number) => {
+      setIsLoading(true);
+      const data = await fetchPoints(pageNum, PAGE_SIZE);
+      setPoints(data);
+      setIsLoading(false);
+    },
+    [fetchPoints]
+  );
+
+  useEffect(() => {
+    if (state.isInitialized) {
+      // eslint-disable-next-line react-hooks/set-state-in-effect -- async data fetching pattern
+      loadPage(page);
+    }
+  }, [state.isInitialized, page, loadPage]);
+
+  const handlePrev = () => {
+    if (page > 0) setPage(page - 1);
+  };
+
+  const handleNext = () => {
+    if (page < totalPages - 1) setPage(page + 1);
+  };
+
+  const handlePointClick = async (id: string | number) => {
+    await setPointHover(id);
+  };
+
+  // Check if a point is currently hovered
+  const isHovered = (id: string | number) => {
+    if (!state.hoveredPoint) return false;
+    const idIdx = state.hoveredPoint.columns.indexOf('__index_level_0__');
+    if (idIdx === -1) return false;
+    return state.hoveredPoint.row[idIdx] === id;
+  };
+
+  if (!state.isInitialized) {
+    return <div className="text-xs text-zinc-400">Not initialized</div>;
+  }
+
+  return (
+    <div className="flex flex-col gap-2">
+      {/* List */}
+      <div className="max-h-48 overflow-y-auto border border-zinc-200 rounded bg-white">
+        {isLoading ? (
+          <div className="p-2 text-xs text-zinc-400">Loading...</div>
+        ) : points.length === 0 ? (
+          <div className="p-2 text-xs text-zinc-400">No points</div>
+        ) : (
+          points.map((point) => (
+            <div
+              key={String(point.id)}
+              onClick={() => handlePointClick(point.id)}
+              className={`px-2 py-1 text-xs cursor-pointer border-b border-zinc-100 last:border-b-0 hover:bg-blue-50 ${
+                isHovered(point.id) ? 'bg-blue-100 font-medium' : ''
+              }`}
+            >
+              <span className="text-zinc-500">#{point.id}</span>{' '}
+              <span className="text-zinc-700">
+                ({point.x.toFixed(2)}, {point.y.toFixed(2)})
+              </span>
+            </div>
+          ))
+        )}
+      </div>
+
+      {/* Pagination */}
+      <div className="flex items-center justify-between text-xs">
+        <button
+          onClick={handlePrev}
+          disabled={page === 0}
+          className="px-2 py-1 bg-zinc-100 rounded hover:bg-zinc-200 disabled:opacity-50 disabled:cursor-not-allowed"
+        >
+          Prev
+        </button>
+        <span className="text-zinc-500">
+          {page + 1} / {totalPages || 1}
+        </span>
+        <button
+          onClick={handleNext}
+          disabled={page >= totalPages - 1}
+          className="px-2 py-1 bg-zinc-100 rounded hover:bg-zinc-200 disabled:opacity-50 disabled:cursor-not-allowed"
+        >
+          Next
+        </button>
+      </div>
+    </div>
+  );
+}

package/examples/next/app/components/PointSizeScaleSlider.tsx

@@ -0,0 +1,22 @@
+'use client';
+
+import { useScatterPlot } from '../context/ScatterPlotContext';
+import { Slider } from './Slider';
+
+export function PointSizeScaleSlider() {
+  const { updatePointSizeScale } = useScatterPlot();
+
+  return (
+    <Slider
+      label="Size Scale"
+      min={0.1}
+      max={3}
+      step={0.05}
+      defaultValue={1.0}
+      onChange={updatePointSizeScale}
+      formatValue={(v) => `${v.toFixed(2)}x`}
+      minLabel="0.1x"
+      maxLabel="3x"
+    />
+  );
+}