pkgviz 0.7.7 → 0.8.0

package/src/components/Loader.tsx

@@ -1,9 +1,15 @@
-import React from 'react';
 import { LucideLoader } from 'lucide-react';
+import React from 'react';
 
+/*** Renders the loading indicator. */
 export default function Loader() {
   return (
-    <div data-testid="loader" className="h-full flex items-center justify-center">
+    <div
+      data-testid="loader"
+      role="status"
+      aria-label="Loading"
+      className="flex min-h-0 min-w-0 flex-1 items-center justify-center"
+    >
       <LucideLoader />
     </div>
   );

package/src/components/ProjectLoadError.tsx

@@ -0,0 +1,15 @@
+interface ProjectLoadErrorProps {
+  readonly message: string;
+}
+
+/*** Renders a persistent project-loading error without taking down the surrounding PKGViz UI. */
+export default function ProjectLoadError({ message }: ProjectLoadErrorProps) {
+  return (
+    <div role="alert" className="flex flex-1 items-center justify-center p-6">
+      <div className="max-w-xl rounded-md border border-red-300 bg-red-50 p-4 dark:border-red-900 dark:bg-red-950">
+        <p className="text-sm font-medium text-red-800 dark:text-red-200">Unable to load project</p>
+        <p className="mt-1 break-all text-xs text-red-700 dark:text-red-300">{message}</p>
+      </div>
+    </div>
+  );
+}

package/src/components/SettingsPanel.tsx

@@ -0,0 +1,184 @@
+'use client';
+import { ChevronDownIcon } from 'lucide-react';
+import { Select, Slider } from 'radix-ui';
+import React from 'react';
+
+import { SidebarRow } from '@/components/sidebar/SidebarRow';
+import { SidebarSection } from '@/components/sidebar/SidebarSection';
+import Switch from '@/components/Switch';
+import { useSettings } from '@/contexts/SettingsContext';
+import { t } from '@/i18n/i18n';
+
+/*** Renders the persistent first-rank graph controls below secondary sidebar tools. */
+export function SettingsPanel() {
+  return (
+    <>
+      <FilterSettings />
+      <SubPackageDepthSettings />
+      <LayoutSettings />
+      <LayoutSpacingSettings />
+    </>
+  );
+}
+
+/*** Renders package-visibility settings. */
+function FilterSettings() {
+  const {
+    showCompoundNodes,
+    showVendorPackages,
+    toggleShowCompoundNodes,
+    toggleShowVendorPackages,
+  } = useSettings();
+
+  return (
+    <SidebarSection title={t('settings.filter')}>
+      <SidebarRow>
+        <Switch
+          id="switch-show-vendor-packages"
+          label={t('settings.showVendorPackages')}
+          onToggle={toggleShowVendorPackages}
+          value={showVendorPackages}
+        />
+      </SidebarRow>
+      <SidebarRow>
+        <Switch
+          id="switch-show-compound-nodes"
+          label={t('settings.showCompoundNodes')}
+          onToggle={toggleShowCompoundNodes}
+          value={showCompoundNodes}
+        />
+      </SidebarRow>
+    </SidebarSection>
+  );
+}
+
+/*** Renders the visible subpackage-depth control. */
+function SubPackageDepthSettings() {
+  const { maxSubPackageDepth, setSubPackageDepth, subPackageDepth } = useSettings();
+
+  return (
+    <SidebarSection title={t('settings.subPackageDepth') + ': ' + subPackageDepth}>
+      <SidebarRow>
+        <SettingsSlider
+          ariaLabel={t('settings.subPackageDepth')}
+          max={maxSubPackageDepth}
+          min={1}
+          step={1}
+          value={subPackageDepth}
+          onValueChange={setSubPackageDepth}
+        />
+      </SidebarRow>
+    </SidebarSection>
+  );
+}
+
+/*** Renders the active Cytoscape layout selector. */
+function LayoutSettings() {
+  const { cytoscapeLayout, setCytoscapeLayout } = useSettings();
+
+  /*** Lets the Select close immediately before starting a potentially expensive graph layout. */
+  const selectLayout = (layout: string) => {
+    if (
+      layout !== 'breadthfirst' &&
+      layout !== 'circle' &&
+      layout !== 'concentric' &&
+      layout !== 'elk' &&
+      layout !== 'grid'
+    ) {
+      return;
+    }
+
+    React.startTransition(() => setCytoscapeLayout(layout));
+  };
+
+  return (
+    <SidebarSection title={t('settings.layout')}>
+      <SidebarRow>
+        <Select.Root value={cytoscapeLayout} onValueChange={selectLayout}>
+          <Select.Trigger
+            aria-label={t('cytoscapeLayout')}
+            className="inline-flex h-9 w-full items-center justify-between rounded-md border px-3"
+          >
+            <Select.Value className="text-foreground" />
+            <Select.Icon>
+              <ChevronDownIcon size={16} />
+            </Select.Icon>
+          </Select.Trigger>
+          <Select.Portal>
+            <Select.Content
+              position="popper"
+              side="bottom"
+              align="start"
+              sideOffset={6}
+              className="z-50 min-w-(--radix-select-trigger-width) rounded-md border bg-white shadow-md dark:bg-neutral-900"
+            >
+              <Select.Viewport className="p-1">
+                <Select.Group>
+                  {['breadthfirst', 'circle', 'concentric', 'elk', 'grid'].map(layout => (
+                    <Select.Item
+                      key={layout}
+                      value={layout}
+                      textValue={t(layout)}
+                      className="rounded px-2 py-1.5 hover:bg-neutral-100 dark:hover:bg-neutral-800"
+                    >
+                      <Select.ItemText>{t(layout)}</Select.ItemText>
+                    </Select.Item>
+                  ))}
+                </Select.Group>
+              </Select.Viewport>
+            </Select.Content>
+          </Select.Portal>
+        </Select.Root>
+      </SidebarRow>
+    </SidebarSection>
+  );
+}
+
+/*** Renders the active layout-spacing control. */
+function LayoutSpacingSettings() {
+  const { cytoscapeLayoutSpacing, setCytoscapeLayoutSpacing } = useSettings();
+
+  return (
+    <SidebarSection title={t('settings.layoutSpacing') + ': ' + cytoscapeLayoutSpacing.toFixed(2)}>
+      <SidebarRow>
+        <SettingsSlider
+          ariaLabel={t('settings.layoutSpacing')}
+          max={1}
+          min={0.1}
+          step={0.01}
+          value={cytoscapeLayoutSpacing}
+          onValueChange={setCytoscapeLayoutSpacing}
+        />
+      </SidebarRow>
+    </SidebarSection>
+  );
+}
+
+/*** Renders the shared slider shape used by numeric sidebar settings. */
+function SettingsSlider({ ariaLabel, max, min, onValueChange, step, value }: SettingsSliderProps) {
+  return (
+    <Slider.Root
+      min={min}
+      max={max}
+      step={step}
+      value={[value]}
+      onValueChange={([nextValue]) => onValueChange(nextValue)}
+      aria-label={ariaLabel}
+      className="relative flex h-5 w-full touch-none select-none items-center"
+    >
+      <Slider.Track className="relative h-1.5 grow rounded-full bg-neutral-200 dark:bg-neutral-800">
+        <Slider.Range className="absolute h-1.5 rounded-full bg-blue-600 dark:bg-blue-400" />
+      </Slider.Track>
+      <Slider.Thumb className="block h-4 w-4 rounded-full border border-neutral-300 bg-white shadow focus:outline-none focus:ring-2 focus:ring-blue-500 dark:border-neutral-600 dark:bg-neutral-100" />
+    </Slider.Root>
+  );
+}
+
+interface SettingsSliderProps {
+  readonly ariaLabel: string;
+  readonly max: number;
+  readonly min: number;
+  readonly onValueChange: (value: number) => void;
+  readonly step: number;
+  readonly value: number;
+}

package/src/components/Switch.tsx

@@ -1,25 +1,17 @@
 'use client';
 import React from 'react';
-import { Switch } from 'radix-ui';
 
+import { ToggleSwitch } from '@/components/ToggleSwitch';
+
+/*** Renders a labeled settings switch. */
 export default function RadixSwitch({ id, label, value, onToggle }: ISwitch) {
   return (
-    <form>
-      <div className="flex items-center justify-between h-[20px]">
-        <label className="pr-[15px] leading-none text-foreground whitespace-nowrap" htmlFor={id}>
-          {label}
-        </label>
-        <Switch.Root
-          className="relative h-[18px] w-[42px] cursor-default rounded-full bg-neutral-200 dark:bg-neutral-800 outline-none data-[state=checked]:bg-neutral-200 dark:data-[state=checked]:bg-gray-700"
-          defaultChecked={value}
-          id={id}
-          checked={value}
-          onCheckedChange={onToggle}
-        >
-          <Switch.Thumb className="block size-[16px] translate-x-0.5 rounded-full bg-neutral-500 dark:bg-neutral-500 transition-transform duration-100 will-change-transform data-[state=checked]:bg-blue-500 dark:data-[state=checked]:bg-white data-[state=checked]:translate-x-[24px]" />
-        </Switch.Root>
-      </div>
-    </form>
+    <div className="flex h-[20px] items-center justify-between">
+      <label className="pr-[15px] leading-none whitespace-nowrap text-foreground" htmlFor={id}>
+        {label}
+      </label>
+      <ToggleSwitch ariaLabel={label} id={id} onToggle={onToggle} value={value} />
+    </div>
   );
 }
 

package/src/components/ThemeToggle.tsx

@@ -1,7 +1,8 @@
 'use client';
-import { useEffect, useState } from 'react';
 import { useTheme } from 'next-themes';
+import { useEffect, useState } from 'react';
 
+/*** Renders the light and dark theme toggle. */
 export default function ThemeToggle() {
   const { theme, setTheme, resolvedTheme } = useTheme();
   const [mounted, setMounted] = useState(false);

package/src/components/ToggleSwitch.tsx

@@ -0,0 +1,36 @@
+'use client';
+import { Switch } from 'radix-ui';
+import React from 'react';
+
+/*** Renders a switch control without imposing row or label layout. */
+export function ToggleSwitch({ ariaLabel, checkedColor, id, onToggle, value }: ToggleSwitchProps) {
+  return (
+    <Switch.Root
+      aria-label={ariaLabel}
+      className="relative h-[18px] w-[42px] shrink-0 cursor-pointer rounded-full bg-neutral-200 outline-none data-[state=checked]:bg-neutral-200 dark:bg-neutral-800 dark:data-[state=checked]:bg-gray-700"
+      id={id}
+      checked={value}
+      onCheckedChange={onToggle}
+    >
+      {value && checkedColor ? (
+        <span
+          aria-hidden="true"
+          className="pointer-events-none absolute inset-0 rounded-full opacity-25"
+          style={{ backgroundColor: checkedColor }}
+        />
+      ) : null}
+      <Switch.Thumb
+        className="relative block size-[16px] translate-x-0.5 rounded-full bg-neutral-500 transition-transform duration-100 will-change-transform data-[state=checked]:translate-x-[24px] data-[state=checked]:bg-blue-500 dark:bg-neutral-500 dark:data-[state=checked]:bg-white"
+        style={value && checkedColor ? { backgroundColor: checkedColor } : undefined}
+      />
+    </Switch.Root>
+  );
+}
+
+interface ToggleSwitchProps {
+  readonly ariaLabel: string;
+  readonly checkedColor?: string;
+  readonly id: string;
+  readonly value: boolean;
+  readonly onToggle: () => void;
+}

package/src/components/sidebar/Sidebar.tsx

@@ -0,0 +1,14 @@
+import React from 'react';
+
+/*** Renders the fixed-width application sidebar shell. */
+export function Sidebar({ children }: SidebarProps) {
+  return (
+    <aside className="flex min-h-0 w-[18rem] min-w-[18rem] max-w-[18rem] shrink-0 self-stretch flex-col overflow-hidden border-r border-r-neutral-200 bg-neutral-100 md:pt-14 dark:border-r-neutral-800 dark:bg-neutral-950">
+      {children}
+    </aside>
+  );
+}
+
+interface SidebarProps {
+  readonly children: React.ReactNode;
+}

package/src/components/sidebar/SidebarBadge.tsx

@@ -0,0 +1,25 @@
+import React from 'react';
+
+/*** Renders a compact circular count badge for sidebar findings and secondary tabs. */
+export function SidebarBadge({ count, tone = 'neutral' }: SidebarBadgeProps) {
+  const toneClass =
+    tone === 'danger'
+      ? 'border-red-300 bg-red-50 text-red-700 dark:border-red-900 dark:bg-red-950 dark:text-red-300'
+      : 'border-neutral-300 text-neutral-700 dark:border-neutral-700 dark:text-neutral-200';
+
+  return (
+    <span
+      className={
+        'inline-flex h-5 min-w-5 shrink-0 items-center justify-center rounded-full border px-1 text-[10px] font-semibold leading-none ' +
+        toneClass
+      }
+    >
+      {count}
+    </span>
+  );
+}
+
+interface SidebarBadgeProps {
+  readonly count: number;
+  readonly tone?: 'danger' | 'neutral';
+}

package/src/components/sidebar/SidebarRow.tsx

@@ -0,0 +1,14 @@
+import React from 'react';
+
+/*** Renders one consistently styled row inside an application-sidebar section. */
+export function SidebarRow({ children }: SidebarRowProps) {
+  return (
+    <div className="ml-3 border-b border-b-neutral-200 bg-white px-3 py-2 dark:border-b-neutral-800 dark:bg-neutral-900">
+      {children}
+    </div>
+  );
+}
+
+interface SidebarRowProps {
+  readonly children: React.ReactNode;
+}

package/src/components/sidebar/SidebarSection.tsx

@@ -0,0 +1,16 @@
+import React from 'react';
+
+/*** Renders a non-collapsible application-sidebar category. */
+export function SidebarSection({ children, title }: SidebarSectionProps) {
+  return (
+    <section>
+      <h3 className="mx-6 mt-6 mb-2 text-sm font-bold">{title}</h3>
+      {children}
+    </section>
+  );
+}
+
+interface SidebarSectionProps {
+  readonly children: React.ReactNode;
+  readonly title: React.ReactNode;
+}

package/src/components/sidebar/SidebarTabs.tsx

@@ -0,0 +1,58 @@
+'use client';
+import { Tabs } from 'radix-ui';
+import React from 'react';
+
+import { SidebarBadge } from '@/components/sidebar/SidebarBadge';
+
+/*** Renders reusable secondary sidebar views above the persistent graph settings. */
+export function SidebarTabs({ ariaLabel, onValueChange, tabs, value }: SidebarTabsProps) {
+  return (
+    <Tabs.Root
+      value={value ?? ''}
+      onValueChange={onValueChange}
+      className="flex min-h-0 flex-1 flex-col overflow-hidden"
+    >
+      <Tabs.List
+        aria-label={ariaLabel}
+        className="ml-3 flex shrink-0 border-b border-neutral-200 dark:border-neutral-800"
+      >
+        {tabs.map(tab => (
+          <Tabs.Trigger
+            key={tab.id}
+            value={tab.id}
+            disabled={tab.disabled}
+            className="flex flex-1 items-center justify-center gap-1.5 border-b-2 border-transparent px-3 py-2 text-xs text-neutral-500 disabled:cursor-default disabled:opacity-40 data-[state=active]:border-blue-600 data-[state=active]:text-neutral-900 dark:text-neutral-400 dark:data-[state=active]:border-blue-400 dark:data-[state=active]:text-neutral-100"
+          >
+            <span>{tab.label}</span>
+            {tab.badge ? <SidebarBadge count={tab.badge} tone={tab.badgeTone} /> : null}
+          </Tabs.Trigger>
+        ))}
+      </Tabs.List>
+      {tabs.map(tab => (
+        <Tabs.Content
+          key={tab.id}
+          value={tab.id}
+          className="min-h-0 flex-1 overflow-y-auto border-b border-neutral-200 pb-3 outline-none dark:border-neutral-800"
+        >
+          {tab.content}
+        </Tabs.Content>
+      ))}
+    </Tabs.Root>
+  );
+}
+
+interface SidebarTab {
+  readonly badge?: number;
+  readonly badgeTone?: 'danger' | 'neutral';
+  readonly content: React.ReactNode;
+  readonly disabled?: boolean;
+  readonly id: string;
+  readonly label: React.ReactNode;
+}
+
+interface SidebarTabsProps {
+  readonly ariaLabel: string;
+  readonly onValueChange: (value: string) => void;
+  readonly tabs: readonly SidebarTab[];
+  readonly value: string | null;
+}

package/src/contexts/SettingsContext.tsx

@@ -1,46 +1,40 @@
+import { useLocalStorage } from 'ankh-hooks/store';
 import type { LayoutOptions } from 'cytoscape';
+import React, { createContext, type PropsWithChildren, use } from 'react';
 
-import React, { createContext, use, type PropsWithChildren } from 'react';
-import {
-  getCytoscapeLayout,
-  getCytoscapeLayoutSpacing,
-  getShowCompoundNodes,
-  getShowVendorPackages,
-  getSubPackageDepth,
-} from '@/shared/utils/parseEnv';
-import { useLocalStorage } from '@/store/useLocalStorage';
+import { readSettingsEnvironment } from '@/features/settings/utils/readSettingsEnvironment';
 
 // Settings context
 const SettingsContext = createContext<ISettingsContext | null>(null);
 
-// Settings provider
+/*** Provides persisted graph settings to the application. */
 export const SettingsProvider = ({ children }: PropsWithChildren) => {
-  const [maxSubPackageDepth, setMaxSubPackageDepth] = useLocalStorage<number>(
-    'maxSubPackageDepth',
-    1
-  );
+  const environment = readSettingsEnvironment();
+  const [maxSubPackageDepth, setMaxSubPackageDepth] = useMaxSubPackageDepthSetting();
   const [showCompoundNodes, setShowCompoundNodes] = useLocalStorage<boolean>(
     'showCompoundNodes',
-    getShowCompoundNodes()
+    environment.showCompoundNodes
   );
   const [showVendorPackages, setShowVendorPackages] = useLocalStorage<boolean>(
     'showVendorPackages',
-    getShowVendorPackages()
+    environment.showVendorPackages
   );
   const [subPackageDepth, setSubPackageDepth] = useLocalStorage<number>(
     'subPackageDepth',
-    getSubPackageDepth() || 1
+    environment.subPackageDepth
   );
   const [cytoscapeLayout, setCytoscapeLayout] = useLocalStorage<LayoutOptions['name']>(
     'cytoscapeLayout',
-    getCytoscapeLayout()
+    environment.cytoscapeLayout
   );
   const [cytoscapeLayoutSpacing, setCytoscapeLayoutSpacing] = useLocalStorage<number>(
     'cytoscapeLayoutSpacing',
-    getCytoscapeLayoutSpacing()
+    environment.cytoscapeLayoutSpacing
   );
 
+  /*** Toggles vendor package visibility. */
   const toggleShowVendorPackages = () => setShowVendorPackages(prev => !prev);
+  /*** Toggles compound node visibility. */
   const toggleShowCompoundNodes = () => setShowCompoundNodes(prev => !prev);
 
   return (
@@ -65,7 +59,12 @@ export const SettingsProvider = ({ children }: PropsWithChildren) => {
   );
 };
 
-// Hook to read/update settings
+/*** Owns the persisted maximum package-depth state. */
+function useMaxSubPackageDepthSetting() {
+  return useLocalStorage<number>('maxSubPackageDepth', 1);
+}
+
+/*** Returns the current graph settings context. */
 export function useSettings() {
   const context = use(SettingsContext);
   if (!context) throw new Error('useSettings() must be used within a SettingsProvider');

package/src/features/audit/adapters/inbound/react/AuditRuleList.tsx

@@ -0,0 +1,76 @@
+'use client';
+import React from 'react';
+
+import { SidebarRow } from '@/components/sidebar/SidebarRow';
+import { SidebarSection } from '@/components/sidebar/SidebarSection';
+import { CyclicDependenciesRuleDetails } from '@/features/audit/adapters/inbound/react/CyclicDependenciesRuleDetails';
+import type { Audit, AuditRuleResult } from '@/types/audit';
+import type { CycleInspection, CycleSelection } from '@/types/auditVisualization';
+
+/*** Renders only violated audit rules in the active Rules sidebar tab. */
+export function AuditRuleList({
+  evaluation,
+  cycleSelection,
+  inspectedCycleId,
+  onCycleInspectionChange,
+}: AuditRuleListProps) {
+  return (
+    <>
+      {evaluation.rules
+        .filter(rule => rule.status === 'failed')
+        .map(rule => (
+          <RuleDetails
+            key={rule.id}
+            evaluation={evaluation}
+            rule={rule}
+            cycleSelection={cycleSelection}
+            inspectedCycleId={inspectedCycleId}
+            onCycleInspectionChange={onCycleInspectionChange}
+          />
+        ))}
+    </>
+  );
+}
+
+/*** Dispatches one violated rule to its dedicated sidebar renderer. */
+function RuleDetails({
+  evaluation,
+  cycleSelection,
+  inspectedCycleId,
+  onCycleInspectionChange,
+  rule,
+}: RuleDetailsProps) {
+  if (rule.id === 'cyclic-dependencies') {
+    return (
+      <CyclicDependenciesRuleDetails
+        cycles={evaluation.cyclicPackages}
+        cycleSelection={cycleSelection}
+        inspectedCycleId={inspectedCycleId}
+        onCycleInspectionChange={onCycleInspectionChange}
+      />
+    );
+  }
+
+  return (
+    <SidebarSection title={rule.id}>
+      {rule.details.map((detail, index) => (
+        <SidebarRow key={detail + ':' + index}>
+          <code className="block truncate text-[11px]" title={detail}>
+            {detail}
+          </code>
+        </SidebarRow>
+      ))}
+    </SidebarSection>
+  );
+}
+
+interface AuditRuleListProps {
+  readonly inspectedCycleId?: string | null;
+  readonly evaluation: Audit['evaluation'];
+  readonly cycleSelection: CycleSelection;
+  readonly onCycleInspectionChange: (inspection: CycleInspection | null) => void;
+}
+
+interface RuleDetailsProps extends AuditRuleListProps {
+  readonly rule: AuditRuleResult;
+}

package/src/features/audit/adapters/inbound/react/AuditRulePanel.tsx

@@ -0,0 +1,30 @@
+'use client';
+import React from 'react';
+
+import { AuditRuleList } from '@/features/audit/adapters/inbound/react/AuditRuleList';
+import type { Audit } from '@/types/audit';
+import type { CycleInspection, CycleSelection } from '@/types/auditVisualization';
+
+/*** Renders violated audit rules while the Rules sidebar tab is active. */
+export function AuditRulePanel({
+  evaluation,
+  cycleSelection,
+  inspectedCycleId,
+  onCycleInspectionChange,
+}: AuditRulePanelProps) {
+  return (
+    <AuditRuleList
+      evaluation={evaluation}
+      cycleSelection={cycleSelection}
+      inspectedCycleId={inspectedCycleId}
+      onCycleInspectionChange={onCycleInspectionChange}
+    />
+  );
+}
+
+interface AuditRulePanelProps {
+  readonly inspectedCycleId?: string | null;
+  readonly evaluation: Audit['evaluation'];
+  readonly cycleSelection: CycleSelection;
+  readonly onCycleInspectionChange: (inspection: CycleInspection | null) => void;
+}