@djangocfg/widget-data 0.1.1

package/src/JsonTree/README.md

@@ -0,0 +1,142 @@
+# JsonTree
+
+Interactive JSON viewer with collapsible nodes, search, copy-path, and a
+hover-revealed toolbar (ChatGPT-style).
+
+```tsx
+import { JsonTree } from '@djangocfg/ui-tools/json-tree';
+
+<JsonTree data={anyJson} />
+```
+
+That covers 95% of cases. The remaining props live in `types.ts`.
+
+## Provenance
+
+Ported from [jalco/ui's `JsonViewer`](https://ui.justinlevine.me/docs/components/json-viewer)
+(MIT, Justin Levine — full source vendored at
+`packages/@sources/jalcoui-main/`). Modifications:
+
+- Removed the Shiki theme module (65 editor palettes) — we keep one
+  Tailwind-token palette that follows the host light/dark theme via
+  `useResolvedTheme`. No `colorTheme` prop.
+- New `toolbar` prop (`'auto' | 'always' | 'never'`). `'auto'` fades the
+  toolbar in on hover or keyboard focus inside the container (the
+  ChatGPT pattern). `'always'` is for debug panels; `'never'` strips it
+  entirely.
+- New `actions` prop selects which buttons to mount. Default omits the
+  download button — file-viewer hosts shouldn't offer "Download" for
+  JSON that already lives on disk.
+- `bordered={false}` strips the card frame for embedded use; the second
+  source of borders (`JsonContent` wrapper) is gone too.
+- Toolbar buttons use ui-core `<Tooltip>` / `<Button>` / `<Input>` so
+  they pick up shared focus/hover styling.
+
+The original `react-json-tree`-based wrapper is gone; consumers that
+called the legacy `<JsonTree mode="full" config={…}>` shape go through
+`LegacyJsonTree` (default export) which adapts old props to the new
+shape — see `legacyAdapter.tsx`.
+
+## API
+
+```ts
+interface JsonTreeProps {
+  data: unknown;
+  title?: string;
+  rootName?: string;                       // default 'root'
+  toolbar?: 'auto' | 'always' | 'never';   // default 'auto'
+  actions?: ('search' | 'expand' | 'copy' | 'download')[];
+                                           // default ['search','expand','copy']
+  defaultExpandedDepth?: number | true;    // default 2; true = expand all
+  bordered?: boolean;                      // default true
+  className?: string;
+  downloadFilename?: string;               // default 'data.json'
+}
+```
+
+### When to override which
+
+| Goal | Set |
+| --- | --- |
+| Embed inside a pane that already draws border + bg | `bordered={false}` |
+| Debug-panel feel (toolbar always visible) | `toolbar="always"` |
+| Strip the toolbar entirely | `toolbar="never"` |
+| Add a Download button (in-memory data) | `actions={['search','expand','copy','download']}` |
+| Read-only display, no Search | `actions={['expand','copy']}` |
+| Long config — open everything | `defaultExpandedDepth={true}` |
+
+## Theme
+
+The data-typed palette is hand-tuned per light/dark rather than wired to
+semantic UI tokens — same convention as Chrome DevTools, Insomnia, and
+Bruno. JSON inspectors carry their own contrast model; flattening keys
+and values into theme pastels makes them illegible.
+
+The component is **transparent by default** — no internal background,
+so it inherits whatever surface the host provides. Pass `bordered`
+explicitly when you want the card frame.
+
+## Search
+
+Hidden behind the magnifying-glass icon in the toolbar; toggling it
+expands the whole tree so matches inside collapsed nodes become
+visible. Matches highlight in both keys and string values; numeric and
+boolean values match as text.
+
+## Copy-path
+
+Hover any row — a `⊕` icon appears on the right. Clicking it copies
+the full JS access path (`root.dependencies["@tiptap/core"]`, including
+bracket syntax for keys that aren't valid identifiers) to the clipboard.
+
+## Legacy props (back-compat)
+
+The default export — `LegacyJsonTree` — accepts the pre-refactor shape
+so existing call sites compile unchanged:
+
+```tsx
+// Old code still works
+import JsonTree from '@djangocfg/ui-tools/json-tree';
+<JsonTree
+  data={obj}
+  mode="full"
+  config={{
+    maxAutoExpandDepth: 3,
+    showActionButtons: true,
+    autoHideToolbar: true,
+  }}
+/>
+```
+
+`legacyAdapter.ts` maps:
+
+- `mode` → `bordered` + `defaultExpandedDepth` defaults
+- `config.maxAutoExpandDepth` → `defaultExpandedDepth`
+- `config.showExpandControls / showCopy / showDownload / showActionButtons`
+  → `actions` array
+- `config.autoHideToolbar` → `toolbar: 'auto'` (vs `'always'`)
+- `jsonTreeProps` → silently dropped (react-json-tree-specific)
+
+Migrate to the new API at your own pace — new code should target
+`{ JsonTree }` from the named export.
+
+## Lazy entries
+
+`@djangocfg/ui-tools/json-tree` ships two lazy wrappers:
+
+- `LazyJsonTree` — legacy shape, default export. Old code keeps working.
+- `LazyJsonTreeNew` — new shape, for greenfield code.
+
+Both wrap the renderer in `React.lazy` (~80KB chunk including the
+toolbar UI and Tailwind utility surface).
+
+## Related
+
+- `@djangocfg/ui-tools/json-editor` — when you need to **edit** JSON
+  (drag-reorder, JSON Schema validation, undo/redo). Lazy-loads
+  `json-edit-react` (~19KB gz) on demand. Use for debug Store panels
+  and config admin UIs; for read-only display always reach for
+  `json-tree` first.
+- `@djangocfg/ui-tools/pretty-code` — read-only syntax-highlighted code
+  blocks (any language). Use when you have a JSON **string** to display
+  unmodified.

package/src/JsonTree/index.tsx

@@ -0,0 +1,11 @@
+'use client';
+
+/** Public surface for `@djangocfg/widget-data/json-tree`. */
+
+export { JsonTree, JsonTree as default } from './JsonViewer';
+export type { JsonTreeProps, JsonValue, JsonAction, JsonSize } from './types';
+
+// In the retired ui-tools the `./json-tree` subpath resolved to `lazy.tsx` and this barrel
+// was unreachable — the inverse of the other seven tools, whose subpath
+// resolved here and left their `Lazy*` dead. One barrel now carries both.
+export { LazyJsonTree } from './lazy';

package/src/JsonTree/lazy.tsx

@@ -0,0 +1,22 @@
+'use client';
+
+/**
+ * `@djangocfg/widget-data/json-tree` subpath entrypoint.
+ *
+ * Single lazy-loaded export (`LazyJsonTree`) wrapping the renderer
+ * (~80KB chunk including the toolbar UI). Suspense fallback ships from
+ * the shared `LoadingFallback`.
+ */
+
+import { createLazyComponent, LoadingFallback } from '@djangocfg/widget-kit/lazy';
+import type { JsonTreeProps } from './types';
+
+export type { JsonTreeProps, JsonValue, JsonAction, JsonSize } from './types';
+
+export const LazyJsonTree = createLazyComponent<JsonTreeProps>(
+  () => import('./JsonViewer').then((m) => ({ default: m.JsonTree })),
+  {
+    displayName: 'LazyJsonTree',
+    fallback: <LoadingFallback minHeight={64} text="Loading JSON viewer…" />,
+  },
+);

package/src/JsonTree/types.ts

@@ -0,0 +1,91 @@
+/**
+ * Public types for the new JsonTree.
+ *
+ * The shape is intentionally narrow — five props cover ~95% of cases.
+ * Old shape (`mode`, `config`, `jsonTreeProps`, `showActionButtons`, …)
+ * is bridged in `legacyAdapter.ts` so existing consumers compile
+ * unchanged. New code should target this surface.
+ */
+
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+/** Which toolbar buttons to expose. Default `['search','expand','copy']`. */
+export type JsonAction = 'search' | 'expand' | 'copy' | 'download';
+
+/**
+ * Font size for the tree body. Toolbar metrics stay constant.
+ *   - `'sm'` (default) — `text-xs`, dense for chat/debug
+ *   - `'md'`           — `text-sm`, reads like Monaco at normal zoom
+ *   - `'lg'`           — `text-base`, presentation / large screen
+ */
+export type JsonSize = 'sm' | 'md' | 'lg';
+
+export interface JsonTreeProps {
+  /** Any JSON-serializable value. */
+  data: unknown;
+
+  /** Optional heading label rendered in the toolbar. */
+  title?: string;
+
+  /** Label for the root node in the tree. Default `'root'`. */
+  rootName?: string;
+
+  /**
+   * How the toolbar behaves:
+   *   - `'auto'` — fades in on hover / keyboard focus (ChatGPT-style)
+   *   - `'always'` — visible from the start (good for debug panels)
+   *   - `'never'` — no toolbar at all
+   * Default `'auto'`.
+   */
+  toolbar?: 'auto' | 'always' | 'never';
+
+  /**
+   * Which action buttons to render in the toolbar. Default
+   * `['search','expand','copy']`. Add `'download'` for in-memory data
+   * that should be exportable; omit for on-disk file viewers.
+   */
+  actions?: readonly JsonAction[];
+
+  /**
+   * Auto-expand depth on mount. `true` = expand everything.
+   * Default `2` — root + first level open, deeper stays collapsed.
+   */
+  defaultExpandedDepth?: number | true;
+
+  /**
+   * Font size for the tree body. Default `'sm'`. Use `'md'` for
+   * full-pane previews (text-viewer.tsx) so it reads at the same
+   * weight as Monaco; `'lg'` for talks / demos.
+   */
+  size?: JsonSize;
+
+  /**
+   * Draw the card frame (border + rounded corners). Default `true`.
+   * Pass `false` to render flush inside a host pane that already owns
+   * the chrome (cmdop preview, OpenAPI response panel).
+   */
+  bordered?: boolean;
+
+  /**
+   * Render the toolbar with reduced padding, smaller icons, and a hidden
+   * "X keys" badge. Use for embedded contexts where the JSON body is
+   * tiny (e.g. error responses with 2 keys) and the default toolbar
+   * dwarfs the content. Default `false`.
+   */
+  compactHeader?: boolean;
+
+  /** Extra class on the root container. */
+  className?: string;
+
+  /**
+   * Filename used for the optional Download action. Default `'data.json'`.
+   * Ignored when `actions` doesn't include `'download'`.
+   */
+  downloadFilename?: string;
+}

package/src/Kanban/context/KanbanContext.tsx

@@ -0,0 +1,165 @@
+'use client';
+
+import * as React from 'react';
+import {
+  createContext,
+  useCallback,
+  useMemo,
+  useState,
+} from 'react';
+
+import type {
+  KanbanCard,
+  KanbanCardId,
+  KanbanColumn,
+  KanbanColumnId,
+  KanbanDragState,
+  KanbanProps,
+} from '../types';
+
+// =====================================================================
+// Context value
+// =====================================================================
+
+export interface KanbanContextValue {
+  columns: KanbanColumn[];
+  dragState: KanbanDragState;
+  setDragState: React.Dispatch<React.SetStateAction<KanbanDragState>>;
+  moveCard: (cardId: KanbanCardId, fromColumnId: KanbanColumnId, toColumnId: KanbanColumnId, toIndex: number) => void;
+  reorderCard: (columnId: KanbanColumnId, cardId: KanbanCardId, toIndex: number) => void;
+  renderCard?: (card: KanbanCard, columnId: KanbanColumnId) => React.ReactNode;
+  renderColumnHeader?: (column: KanbanColumn) => React.ReactNode;
+  loading: boolean;
+  emptyColumnMessage: React.ReactNode;
+}
+
+const KanbanContext = createContext<KanbanContextValue | null>(null);
+
+export function useKanbanContext(): KanbanContextValue {
+  const ctx = React.useContext(KanbanContext);
+  if (!ctx) {
+    throw new Error('useKanbanContext must be used inside <KanbanProvider>');
+  }
+  return ctx;
+}
+
+// =====================================================================
+// Provider
+// =====================================================================
+
+export interface KanbanProviderProps
+  extends Pick<
+    KanbanProps,
+    | 'columns'
+    | 'onMoveCard'
+    | 'onReorderCard'
+    | 'renderCard'
+    | 'renderColumnHeader'
+    | 'loading'
+    | 'emptyColumnMessage'
+  > {
+  children: React.ReactNode;
+}
+
+export function KanbanProvider(props: KanbanProviderProps) {
+  const {
+    columns: initialColumns,
+    onMoveCard,
+    onReorderCard,
+    renderCard,
+    renderColumnHeader,
+    loading = false,
+    emptyColumnMessage = 'No cards',
+    children,
+  } = props;
+
+  const [columns, setColumns] = useState<KanbanColumn[]>(initialColumns);
+  const [dragState, setDragState] = useState<KanbanDragState>({
+    activeCardId: null,
+    activeColumnId: null,
+    overColumnId: null,
+    overCardId: null,
+  });
+
+  // Sync with external columns prop
+  React.useEffect(() => {
+    setColumns(initialColumns);
+  }, [initialColumns]);
+
+  const moveCard = useCallback(
+    (cardId: KanbanCardId, fromColumnId: KanbanColumnId, toColumnId: KanbanColumnId, toIndex: number) => {
+      setColumns((prev) => {
+        const next = prev.map((col) => ({ ...col, cards: [...col.cards] }));
+        const fromCol = next.find((c) => c.id === fromColumnId);
+        const toCol = next.find((c) => c.id === toColumnId);
+        if (!fromCol || !toCol) return prev;
+
+        const cardIndex = fromCol.cards.findIndex((c) => c.id === cardId);
+        if (cardIndex === -1) return prev;
+
+        const [card] = fromCol.cards.splice(cardIndex, 1);
+        if (!card) return prev;
+        const insertIndex = Math.min(toIndex, toCol.cards.length);
+        toCol.cards.splice(insertIndex, 0, card);
+
+        return next;
+      });
+      onMoveCard?.(cardId, fromColumnId, toColumnId, toIndex);
+    },
+    [onMoveCard],
+  );
+
+  const reorderCard = useCallback(
+    (columnId: KanbanColumnId, cardId: KanbanCardId, toIndex: number) => {
+      setColumns((prev) => {
+        const next = prev.map((col) =>
+          col.id === columnId ? { ...col, cards: [...col.cards] } : col,
+        );
+        const col = next.find((c) => c.id === columnId);
+        if (!col) return prev;
+
+        const fromIndex = col.cards.findIndex((c) => c.id === cardId);
+        if (fromIndex === -1 || fromIndex === toIndex) return prev;
+
+        const [card] = col.cards.splice(fromIndex, 1);
+        if (!card) return prev;
+        const insertIndex = Math.min(toIndex, col.cards.length);
+        col.cards.splice(insertIndex, 0, card);
+
+        return next;
+      });
+      onReorderCard?.(columnId, cardId, toIndex);
+    },
+    [onReorderCard],
+  );
+
+  const value = useMemo<KanbanContextValue>(
+    () => ({
+      columns,
+      dragState,
+      setDragState,
+      moveCard,
+      reorderCard,
+      renderCard,
+      renderColumnHeader,
+      loading,
+      emptyColumnMessage,
+    }),
+    [
+      columns,
+      dragState,
+      moveCard,
+      reorderCard,
+      renderCard,
+      renderColumnHeader,
+      loading,
+      emptyColumnMessage,
+    ],
+  );
+
+  return (
+    <KanbanContext.Provider value={value}>
+      {children}
+    </KanbanContext.Provider>
+  );
+}

package/src/Kanban/context/index.ts

@@ -0,0 +1,4 @@
+'use client';
+
+export { KanbanProvider, useKanbanContext } from './KanbanContext';
+export type { KanbanContextValue, KanbanProviderProps } from './KanbanContext';

package/src/Kanban/index.ts

@@ -0,0 +1,31 @@
+'use client';
+
+export {
+  KanbanProvider,
+  useKanbanContext,
+} from './context/KanbanContext';
+export type {
+  KanbanContextValue,
+  KanbanProviderProps,
+} from './context/KanbanContext';
+
+export {
+  Kanban,
+  KanbanColumn,
+  KanbanCard,
+  KanbanDragOverlay,
+} from './parts';
+
+export type {
+  KanbanProps,
+  KanbanCard as KanbanCardType,
+  KanbanColumn as KanbanColumnType,
+  KanbanDragState,
+  KanbanCardId,
+  KanbanColumnId,
+} from './types';
+
+// The dynamic-import wrapper. Exported here because the subpath resolves to
+// this barrel: in the retired ui-tools `lazy.tsx` was reachable from no declared export,
+// so `LazyKanban` was dead code for every tool but `JsonTree`.
+export { LazyKanban } from './lazy';

package/src/Kanban/lazy.tsx

@@ -0,0 +1,23 @@
+'use client';
+
+import { createLazyComponent, LoadingFallback } from '@djangocfg/widget-kit/lazy';
+import type { KanbanProps } from './types';
+
+export const LazyKanban = createLazyComponent<KanbanProps>(
+  () => import('./parts/Kanban').then((m) => ({ default: m.Kanban })),
+  {
+    displayName: 'LazyKanban',
+    fallback: <LoadingFallback minHeight={400} text="Loading kanban board…" />,
+  },
+);
+
+// Re-export light surface synchronously
+export * from './types';
+export {
+  KanbanProvider,
+  useKanbanContext,
+} from './context/KanbanContext';
+export type {
+  KanbanContextValue,
+  KanbanProviderProps,
+} from './context/KanbanContext';

package/src/Kanban/parts/Kanban.tsx

@@ -0,0 +1,77 @@
+'use client';
+
+import * as React from 'react';
+import { cn } from '@djangocfg/ui-core/lib';
+import { ScrollArea } from '@djangocfg/ui-core/components';
+
+import type { KanbanProps } from '../types';
+import { KanbanProvider } from '../context/KanbanContext';
+import { KanbanColumn } from './KanbanColumn';
+
+export function Kanban(props: KanbanProps) {
+  const {
+    columns,
+    onMoveCard,
+    onReorderCard,
+    renderCard,
+    renderColumnHeader,
+    loading,
+    emptyColumnMessage,
+    className,
+    style,
+  } = props;
+
+  return (
+    <KanbanProvider
+      columns={columns}
+      onMoveCard={onMoveCard}
+      onReorderCard={onReorderCard}
+      renderCard={renderCard}
+      renderColumnHeader={renderColumnHeader}
+      loading={loading}
+      emptyColumnMessage={emptyColumnMessage}
+    >
+      <KanbanShell className={className} style={style} />
+    </KanbanProvider>
+  );
+}
+Kanban.displayName = 'Kanban';
+
+function KanbanShell({ className, style }: { className?: string; style?: React.CSSProperties }) {
+  const { columns, loading } = useKanbanContext();
+
+  if (loading) {
+    return (
+      <div
+        data-slot="kanban"
+        className={cn(
+          'flex h-full items-center justify-center rounded-sm border border-border bg-background',
+          className
+        )}
+        style={style}
+      >
+        <span className="text-muted-foreground">Loading…</span>
+      </div>
+    );
+  }
+
+  return (
+    <ScrollArea className="w-full" orientation="horizontal">
+      <div
+        data-slot="kanban"
+        className={cn(
+          'flex h-full min-h-[400px] gap-4 rounded-sm border border-border bg-background p-4',
+          className
+        )}
+        style={style}
+      >
+        {columns.map((column) => (
+          <KanbanColumn key={column.id} column={column} />
+        ))}
+      </div>
+    </ScrollArea>
+  );
+}
+
+// Ambient import for JSX usage
+import { useKanbanContext } from '../context/KanbanContext';

package/src/Kanban/parts/KanbanCard.tsx

@@ -0,0 +1,76 @@
+'use client';
+
+import * as React from 'react';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import type { KanbanCard as KanbanCardType, KanbanColumnId } from '../types';
+import { useKanbanContext } from '../context/KanbanContext';
+
+interface KanbanCardProps {
+  card: KanbanCardType;
+  columnId: KanbanColumnId;
+  index: number;
+}
+
+export function KanbanCard({ card, columnId, index }: KanbanCardProps) {
+  const { renderCard, dragState, setDragState, moveCard, reorderCard } = useKanbanContext();
+  const isActive = dragState.activeCardId === card.id;
+  const isOver = dragState.overCardId === card.id && dragState.activeCardId !== card.id;
+
+  const handlePointerDown = React.useCallback(
+    (e: React.PointerEvent) => {
+      e.preventDefault();
+      setDragState({
+        activeCardId: card.id,
+        activeColumnId: columnId,
+        overColumnId: null,
+        overCardId: null,
+      });
+    },
+    [card.id, columnId, setDragState],
+  );
+
+  const handlePointerEnter = React.useCallback(() => {
+    if (!dragState.activeCardId || dragState.activeCardId === card.id) return;
+
+    setDragState((prev) => ({ ...prev, overCardId: card.id, overColumnId: columnId }));
+
+    if (dragState.activeColumnId === columnId) {
+      reorderCard(columnId, dragState.activeCardId, index);
+    } else if (dragState.activeColumnId) {
+      moveCard(dragState.activeCardId, dragState.activeColumnId, columnId, index);
+      setDragState((prev) => ({ ...prev, activeColumnId: columnId }));
+    }
+  }, [card.id, columnId, index, dragState, setDragState, reorderCard, moveCard]);
+
+  return (
+    <div
+      data-slot="kanban-card"
+      data-id={card.id}
+      data-column-id={columnId}
+      data-active={isActive ? '' : undefined}
+      data-over={isOver ? '' : undefined}
+      onPointerDown={handlePointerDown}
+      onPointerEnter={handlePointerEnter}
+      className={cn(
+        'cursor-grab select-none rounded-sm border border-border bg-background p-3 shadow-sm',
+        'transition-all',
+        'hover:border-primary/50',
+        isActive && 'z-50 scale-[1.02] opacity-80 shadow-lg',
+        isOver && 'border-dashed border-primary'
+      )}
+    >
+      {renderCard ? (
+        renderCard(card, columnId)
+      ) : (
+        <>
+          <h4 className="text-sm font-medium text-foreground">{card.title}</h4>
+          {card.description && (
+            <p className="mt-1 text-xs text-muted-foreground">{card.description}</p>
+          )}
+        </>
+      )}
+    </div>
+  );
+}
+KanbanCard.displayName = 'KanbanCard';