@pyric/ui 0.1.0-alpha.11 → 0.1.0-alpha.13

package/src/primitives/JsonView.tsx

@@ -0,0 +1,151 @@
+import { useState } from 'react';
+
+export interface JsonViewProps {
+  /** Any JSON-serializable value. */
+  value: unknown;
+  /**
+   * Depth at and below which object/array nodes start collapsed.
+   * `0` collapses the root, `1` collapses everything under the root,
+   * `Infinity` (default) leaves everything expanded.
+   */
+  defaultCollapsedDepth?: number;
+  /** Forwarded to the root container. */
+  className?: string;
+}
+
+type JsonKind =
+  | 'object'
+  | 'array'
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'null';
+
+function kindOf(value: unknown): JsonKind {
+  if (value === null || value === undefined) return 'null';
+  if (Array.isArray(value)) return 'array';
+  const t = typeof value;
+  if (t === 'object') return 'object';
+  if (t === 'number') return 'number';
+  if (t === 'boolean') return 'boolean';
+  return 'string';
+}
+
+/**
+ * Headless collapsible JSON tree. One structural step above a
+ * `<pre>` dump: object/array nodes are independently expandable, but
+ * there's no editing and no syntax-color theme — just `data-pyric-*`
+ * hooks for the consumer to style.
+ *
+ * Styling hooks:
+ * - `[data-pyric-ui="json-view"]` — root
+ * - `[data-pyric-json-node]` — every node, with `data-pyric-json-type`
+ * - `[data-pyric-json-toggle]` — the expand/collapse button (containers only)
+ * - `[data-pyric-json-node][data-pyric-collapsed]` — a collapsed container
+ * - `[data-pyric-json-key]` — the key/index label
+ * - `[data-pyric-json-value]` — a primitive value
+ * - `[data-pyric-json-summary]` — the `{…}` / `[…]` placeholder when collapsed
+ */
+export function JsonView({
+  value,
+  defaultCollapsedDepth = Infinity,
+  className,
+}: JsonViewProps) {
+  return (
+    <div data-pyric-ui="json-view" className={className}>
+      <JsonNode
+        value={value}
+        depth={0}
+        defaultCollapsedDepth={defaultCollapsedDepth}
+      />
+    </div>
+  );
+}
+
+interface JsonNodeProps {
+  value: unknown;
+  /** Object key or array index label — absent on the root. */
+  nodeKey?: string;
+  depth: number;
+  defaultCollapsedDepth: number;
+}
+
+function JsonNode({
+  value,
+  nodeKey,
+  depth,
+  defaultCollapsedDepth,
+}: JsonNodeProps) {
+  const kind = kindOf(value);
+  const isContainer = kind === 'object' || kind === 'array';
+  const [collapsed, setCollapsed] = useState(
+    isContainer && depth >= defaultCollapsedDepth,
+  );
+
+  if (!isContainer) {
+    return (
+      <div data-pyric-json-node="" data-pyric-json-type={kind}>
+        {nodeKey !== undefined ? (
+          <span data-pyric-json-key="">{nodeKey}</span>
+        ) : null}
+        <span data-pyric-json-value="">{formatPrimitive(value, kind)}</span>
+      </div>
+    );
+  }
+
+  const entries: Array<[string, unknown]> = Array.isArray(value)
+    ? value.map((v, i) => [String(i), v])
+    : Object.entries(value as Record<string, unknown>);
+  const open = kind === 'array' ? '[' : '{';
+  const close = kind === 'array' ? ']' : '}';
+
+  return (
+    <div
+      data-pyric-json-node=""
+      data-pyric-json-type={kind}
+      data-pyric-collapsed={collapsed ? '' : undefined}
+    >
+      <button
+        type="button"
+        data-pyric-json-toggle=""
+        aria-expanded={!collapsed}
+        onClick={() => setCollapsed((c) => !c)}
+      >
+        {nodeKey !== undefined ? (
+          <span data-pyric-json-key="">{nodeKey}</span>
+        ) : null}
+        {collapsed ? (
+          <span data-pyric-json-summary="">
+            {open}
+            {entries.length}
+            {close}
+          </span>
+        ) : (
+          <span data-pyric-json-bracket="">{open}</span>
+        )}
+      </button>
+      {collapsed ? null : (
+        <>
+          <div data-pyric-json-children="">
+            {entries.map(([k, v]) => (
+              <JsonNode
+                key={k}
+                value={v}
+                nodeKey={k}
+                depth={depth + 1}
+                defaultCollapsedDepth={defaultCollapsedDepth}
+              />
+            ))}
+          </div>
+          <span data-pyric-json-bracket="">{close}</span>
+        </>
+      )}
+    </div>
+  );
+}
+
+function formatPrimitive(value: unknown, kind: JsonKind): string {
+  if (kind === 'null') return 'null';
+  if (kind === 'string') return JSON.stringify(value);
+  return String(value);
+}

package/src/primitives/SegmentedControl.tsx

@@ -0,0 +1,72 @@
+import type { ReactNode } from 'react';
+
+export interface SegmentedOption<T extends string> {
+  /** The value committed via `onChange` when this segment is picked. */
+  value: T;
+  /** Visible label. */
+  label: ReactNode;
+  /**
+   * Freeform tone surfaced as `data-pyric-segment-tone` — e.g. `ok`
+   * / `error` so the consumer can tint the active label. The library
+   * doesn't enumerate tones.
+   */
+  tone?: string;
+}
+
+export interface SegmentedControlProps<T extends string> {
+  /** The selectable segments, rendered left-to-right. */
+  options: ReadonlyArray<SegmentedOption<T>>;
+  /** The currently-selected value. */
+  value: T;
+  /** Fired with the new value when a segment is clicked. */
+  onChange: (value: T) => void;
+  /** Forwarded to the container. */
+  className?: string;
+  /** Accessible label for the radiogroup. */
+  ariaLabel?: string;
+}
+
+/**
+ * Headless segmented control — a single-select group of pill
+ * buttons that reads as one widget. Wired as an ARIA radiogroup.
+ *
+ * Ships no visual styling. Consumers style via:
+ * - `[data-pyric-ui="segmented-control"]` — the container
+ * - `[data-pyric-segment]` — each option button
+ * - `[data-pyric-segment][data-pyric-active]` — the selected one
+ * - `[data-pyric-segment-tone="…"]` — tone-tinted options
+ */
+export function SegmentedControl<T extends string>({
+  options,
+  value,
+  onChange,
+  className,
+  ariaLabel,
+}: SegmentedControlProps<T>) {
+  return (
+    <div
+      data-pyric-ui="segmented-control"
+      className={className}
+      role="radiogroup"
+      aria-label={ariaLabel}
+    >
+      {options.map((opt) => {
+        const active = opt.value === value;
+        return (
+          <button
+            key={opt.value}
+            type="button"
+            role="radio"
+            aria-checked={active}
+            onClick={() => onChange(opt.value)}
+            data-pyric-segment=""
+            data-pyric-active={active ? '' : undefined}
+            data-pyric-segment-tone={opt.tone}
+          >
+            {opt.label}
+          </button>
+        );
+      })}
+    </div>
+  );
+}

package/src/primitives/Toast.tsx

@@ -0,0 +1,161 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactNode,
+} from 'react';
+import { createPortal } from 'react-dom';
+
+export type ToastKind = 'info' | 'success' | 'warning' | 'error';
+
+export interface ToastInput {
+  title: string;
+  body?: ReactNode;
+  kind?: ToastKind;
+  /** Auto-dismiss after this many ms. `0` makes the toast sticky;
+   *  default is 5000. */
+  duration?: number;
+}
+
+export interface ToastRecord extends ToastInput {
+  id: string;
+}
+
+interface ToastContextValue {
+  toast: (input: ToastInput) => string;
+  dismiss: (id: string) => void;
+  toasts: ReadonlyArray<ToastRecord>;
+}
+
+const Ctx = createContext<ToastContextValue | null>(null);
+
+/**
+ * Imperative toast hook. Returns `{ toast, dismiss, toasts }`.
+ *
+ *   const { toast } = useToast();
+ *   toast({ title: 'Saved.', kind: 'success' });
+ *
+ * Requires a `<ToastProvider>` ancestor.
+ */
+export function useToast(): ToastContextValue {
+  const ctx = useContext(Ctx);
+  if (!ctx) {
+    throw new Error('useToast: missing <ToastProvider> ancestor');
+  }
+  return ctx;
+}
+
+export interface ToastProviderProps {
+  children: ReactNode;
+  /** Default auto-dismiss in ms. Per-toast `duration` overrides.
+   *  Default 5000; pass `0` to make sticky-by-default. */
+  defaultDuration?: number;
+  /** Forwarded to the rendered container. */
+  className?: string;
+  /** Region label for assistive tech. Defaults to "Notifications". */
+  regionLabel?: string;
+}
+
+/**
+ * Toast queue host. Mounts a single live region into `document.body`
+ * via portal and exposes the imperative API via context. Scoped —
+ * a subtree can host its own provider for isolated queues if needed.
+ *
+ * Headless: every node carries structural `data-*` attributes, no
+ * shipped CSS. Auto-dismiss timers are kept per-toast.
+ */
+export function ToastProvider({
+  children,
+  defaultDuration = 5000,
+  className,
+  regionLabel = 'Notifications',
+}: ToastProviderProps) {
+  const [toasts, setToasts] = useState<ToastRecord[]>([]);
+
+  const dismiss = useCallback((id: string) => {
+    setToasts((prev) => prev.filter((t) => t.id !== id));
+  }, []);
+
+  const toast = useCallback<ToastContextValue['toast']>(
+    (input) => {
+      const id = crypto.randomUUID();
+      const duration = input.duration ?? defaultDuration;
+      setToasts((prev) => [...prev, { id, ...input }]);
+      if (duration > 0) {
+        // Schedule auto-dismiss. The timer fires `dismiss(id)`
+        // which is idempotent (filter on a missing id is a no-op).
+        window.setTimeout(() => {
+          setToasts((prev) => prev.filter((t) => t.id !== id));
+        }, duration);
+      }
+      return id;
+    },
+    [defaultDuration],
+  );
+
+  const value = useMemo<ToastContextValue>(
+    () => ({ toast, dismiss, toasts }),
+    [toast, dismiss, toasts],
+  );
+
+  return (
+    <Ctx.Provider value={value}>
+      {children}
+      <ToastRegion
+        toasts={toasts}
+        dismiss={dismiss}
+        className={className}
+        regionLabel={regionLabel}
+      />
+    </Ctx.Provider>
+  );
+}
+
+interface ToastRegionProps {
+  toasts: ReadonlyArray<ToastRecord>;
+  dismiss: (id: string) => void;
+  className?: string;
+  regionLabel: string;
+}
+
+function ToastRegion({ toasts, dismiss, className, regionLabel }: ToastRegionProps) {
+  // SSR guard. Astro `client:only` consumers won't see this branch
+  // hit, but it keeps the import safe in mixed environments.
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => setMounted(true), []);
+  if (!mounted) return null;
+  if (typeof document === 'undefined') return null;
+
+  return createPortal(
+    <ol
+      aria-label={regionLabel}
+      aria-live="polite"
+      data-pyric-ui="toast-region"
+      className={className}
+    >
+      {toasts.map((t) => (
+        <li
+          key={t.id}
+          data-pyric-toast
+          data-pyric-toast-kind={t.kind ?? 'info'}
+          role={t.kind === 'error' ? 'alert' : 'status'}
+        >
+          <div data-pyric-toast-title>{t.title}</div>
+          {t.body ? <div data-pyric-toast-body>{t.body}</div> : null}
+          <button
+            type="button"
+            data-pyric-toast-dismiss
+            aria-label="Dismiss"
+            onClick={() => dismiss(t.id)}
+          >
+            ×
+          </button>
+        </li>
+      ))}
+    </ol>,
+    document.body,
+  );
+}

package/src/primitives/VirtualList.tsx

@@ -0,0 +1,104 @@
+import { useRef, type ReactNode } from 'react';
+import { useVirtualizer } from '@tanstack/react-virtual';
+
+export interface VirtualListProps<T> {
+  items: ReadonlyArray<T>;
+  /** Estimated row height in px. `useVirtualizer` measures actual
+   *  rendered heights via ResizeObserver — this is just the guess
+   *  used before measurement. Pass a function for variable sizing. */
+  estimateSize: number | ((index: number) => number);
+  /** Render one row. The library handles positioning + key-by-index. */
+  renderItem: (item: T, index: number) => ReactNode;
+  /**
+   * Number of off-screen rows to render on each side. TanStack
+   * default is 5; bump for smoother fast scrolling.
+   */
+  overscan?: number;
+  /** Forwarded to the scroll container. */
+  className?: string;
+  /** Height the scroll container fills. Default `100%` — the
+   *  consumer's parent typically constrains height. */
+  height?: number | string;
+  /** Optional `key` resolver. Defaults to the index. Use when rows
+   *  reorder so React can preserve component state across moves. */
+  getItemKey?: (item: T, index: number) => string | number;
+}
+
+/**
+ * Thin wrapper around `@tanstack/react-virtual`. Renders a
+ * scrollable container with absolutely-positioned rows, drawing
+ * only the rows currently in view (plus `overscan` neighbors).
+ *
+ * Headless — no shipped CSS beyond what's structurally required
+ * to position rows (the inner spacer's `height` + each row's
+ * `position: absolute; top: …px`). Consumers style via the
+ * `className` prop and standard CSS targeting `[data-pyric-ui=
+ * "virtual-list"]` on the scroll container and
+ * `[data-pyric-virtual-row]` on each row.
+ */
+export function VirtualList<T>({
+  items,
+  estimateSize,
+  renderItem,
+  overscan = 5,
+  className,
+  height = '100%',
+  getItemKey,
+}: VirtualListProps<T>) {
+  const parentRef = useRef<HTMLDivElement | null>(null);
+  const estimator =
+    typeof estimateSize === 'function' ? estimateSize : () => estimateSize;
+
+  const virtualizer = useVirtualizer({
+    count: items.length,
+    getScrollElement: () => parentRef.current,
+    estimateSize: estimator,
+    overscan,
+  });
+
+  return (
+    <div
+      ref={parentRef}
+      className={className}
+      data-pyric-ui="virtual-list"
+      style={{
+        height,
+        overflowY: 'auto',
+        // `contain` keeps the browser from spending paint cost on
+        // off-screen rows even before the virtualizer culls them.
+        contain: 'strict',
+      }}
+    >
+      <div
+        data-pyric-virtual-inner
+        style={{
+          height: `${virtualizer.getTotalSize()}px`,
+          width: '100%',
+          position: 'relative',
+        }}
+      >
+        {virtualizer.getVirtualItems().map((vi) => {
+          const item = items[vi.index];
+          const key = getItemKey ? getItemKey(item, vi.index) : vi.key;
+          return (
+            <div
+              key={key}
+              data-pyric-virtual-row
+              data-index={vi.index}
+              ref={virtualizer.measureElement}
+              style={{
+                position: 'absolute',
+                top: 0,
+                left: 0,
+                width: '100%',
+                transform: `translateY(${vi.start}px)`,
+              }}
+            >
+              {renderItem(item, vi.index)}
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}

package/src/primitives/hooks/useContainerSize.ts

@@ -0,0 +1,53 @@
+import { useEffect, useRef, useState, type RefObject } from 'react';
+
+export type ContainerSize = 'narrow' | 'medium' | 'wide';
+
+export interface UseContainerSizeOptions {
+  /** Width (px) below which the bucket is `'narrow'`. Default 480. */
+  narrowBreakpoint?: number;
+  /** Width (px) below which the bucket is `'medium'` (and above
+   *  which it is `'wide'`). Default 768. */
+  mediumBreakpoint?: number;
+}
+
+/**
+ * Container-query helper. Returns the current size bucket
+ * (`'narrow' | 'medium' | 'wide'`) of the element pointed at by
+ * the returned ref. Re-fires on resize via `ResizeObserver`.
+ *
+ *   const { ref, size } = useContainerSize();
+ *   return <div ref={ref} data-size={size}>…</div>;
+ *
+ * Headless: the consumer styles via `[data-size='narrow']`
+ * selectors. The library's feature components use this hook to
+ * stamp their roots with `data-size`, which is the policy the
+ * survey's modern-CSS subsection landed on (no viewport media
+ * queries, no library-side breakpoints — push the threshold
+ * decision to the consumer via data attributes).
+ */
+export function useContainerSize<T extends HTMLElement = HTMLDivElement>(
+  options: UseContainerSizeOptions = {},
+): { ref: RefObject<T | null>; size: ContainerSize } {
+  const ref = useRef<T | null>(null);
+  const narrow = options.narrowBreakpoint ?? 480;
+  const medium = options.mediumBreakpoint ?? 768;
+  const [size, setSize] = useState<ContainerSize>('wide');
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    if (typeof ResizeObserver === 'undefined') return;
+    const obs = new ResizeObserver((entries) => {
+      const entry = entries[0];
+      if (!entry) return;
+      const w = entry.contentRect.width;
+      if (w < narrow) setSize('narrow');
+      else if (w < medium) setSize('medium');
+      else setSize('wide');
+    });
+    obs.observe(el);
+    return () => obs.disconnect();
+  }, [narrow, medium]);
+
+  return { ref, size };
+}

package/src/primitives/hooks/useUpdateHighlights.ts

@@ -0,0 +1,109 @@
+import { useEffect, useRef, useState } from 'react';
+
+export type UpdateHighlightKind = 'added' | 'modified';
+
+export interface UpdateHighlight {
+  kind: UpdateHighlightKind;
+  cycle: 0 | 1;
+}
+
+export interface UseUpdateHighlightsOptions<T> {
+  scope: string;
+  entries: ReadonlyMap<string, T>;
+  equals?: (previous: T, next: T) => boolean;
+  durationMs?: number;
+  ready?: boolean;
+}
+
+const EMPTY_HIGHLIGHTS: ReadonlyMap<string, UpdateHighlight> = new Map();
+
+/**
+ * Tracks transient additions and modifications between keyed snapshots.
+ * The first ready snapshot in each scope is a silent baseline.
+ */
+export function useUpdateHighlights<T>({
+  scope,
+  entries,
+  equals = Object.is,
+  durationMs = 1_200,
+  ready = true,
+}: UseUpdateHighlightsOptions<T>): ReadonlyMap<string, UpdateHighlight> {
+  const baselineRef = useRef<{ scope: string; entries: ReadonlyMap<string, T> } | null>(null);
+  const cyclesRef = useRef(new Map<string, 0 | 1>());
+  const timersRef = useRef(new Map<string, ReturnType<typeof setTimeout>>());
+  const [highlights, setHighlights] = useState<ReadonlyMap<string, UpdateHighlight>>(
+    EMPTY_HIGHLIGHTS,
+  );
+
+  useEffect(() => {
+    const baseline = baselineRef.current;
+    if (!ready) {
+      if (baseline && baseline.scope !== scope) {
+        baselineRef.current = null;
+        for (const timer of timersRef.current.values()) clearTimeout(timer);
+        timersRef.current.clear();
+        cyclesRef.current.clear();
+        setHighlights(EMPTY_HIGHLIGHTS);
+      }
+      return;
+    }
+    if (!baseline || baseline.scope !== scope) {
+      baselineRef.current = { scope, entries };
+      for (const timer of timersRef.current.values()) clearTimeout(timer);
+      timersRef.current.clear();
+      cyclesRef.current.clear();
+      setHighlights(EMPTY_HIGHLIGHTS);
+      return;
+    }
+
+    const changed = new Map<string, UpdateHighlight>();
+    for (const [key, value] of entries) {
+      const hadValue = baseline.entries.has(key);
+      const previous = baseline.entries.get(key);
+      if (hadValue && equals(previous as T, value)) continue;
+      const cycle: 0 | 1 = cyclesRef.current.get(key) === 0 ? 1 : 0;
+      cyclesRef.current.set(key, cycle);
+      changed.set(key, { kind: hadValue ? 'modified' : 'added', cycle });
+    }
+    baselineRef.current = { scope, entries };
+
+    setHighlights((current) => {
+      const next = new Map(current);
+      let didChange = changed.size > 0;
+      for (const key of current.keys()) {
+        if (!entries.has(key)) {
+          next.delete(key);
+          didChange = true;
+        }
+      }
+      for (const [key, marker] of changed) next.set(key, marker);
+      if (!didChange) return current;
+      return next.size === 0 ? EMPTY_HIGHLIGHTS : next;
+    });
+
+    for (const [key, marker] of changed) {
+      const priorTimer = timersRef.current.get(key);
+      if (priorTimer) clearTimeout(priorTimer);
+      const timer = setTimeout(() => {
+        timersRef.current.delete(key);
+        setHighlights((current) => {
+          if (current.get(key)?.cycle !== marker.cycle) return current;
+          const next = new Map(current);
+          next.delete(key);
+          return next.size === 0 ? EMPTY_HIGHLIGHTS : next;
+        });
+      }, durationMs);
+      timersRef.current.set(key, timer);
+    }
+  }, [durationMs, entries, equals, ready, scope]);
+
+  useEffect(
+    () => () => {
+      for (const timer of timersRef.current.values()) clearTimeout(timer);
+      timersRef.current.clear();
+    },
+    [],
+  );
+
+  return highlights;
+}

package/src/primitives/index.ts

@@ -0,0 +1,39 @@
+export { CopyButton, type CopyButtonProps } from './CopyButton.js';
+export { Badge, type BadgeProps } from './Badge.js';
+export {
+  JsonView,
+  type JsonViewProps,
+} from './JsonView.js';
+export {
+  SegmentedControl,
+  type SegmentedControlProps,
+  type SegmentedOption,
+} from './SegmentedControl.js';
+export { ConfirmDialog, type ConfirmDialogProps } from './ConfirmDialog.js';
+export {
+  ConfirmProvider,
+  useConfirm,
+  type ConfirmOptions,
+  type ConfirmFn,
+  type ConfirmProviderProps,
+} from './useConfirm.js';
+export {
+  ToastProvider,
+  useToast,
+  type ToastInput,
+  type ToastRecord,
+  type ToastKind,
+  type ToastProviderProps,
+} from './Toast.js';
+export { VirtualList, type VirtualListProps } from './VirtualList.js';
+export {
+  useContainerSize,
+  type ContainerSize,
+  type UseContainerSizeOptions,
+} from './hooks/useContainerSize.js';
+export {
+  useUpdateHighlights,
+  type UpdateHighlight,
+  type UpdateHighlightKind,
+  type UseUpdateHighlightsOptions,
+} from './hooks/useUpdateHighlights.js';