@bendyline/docblocks-react 1.1.1 → 2.0.0

package/src/Git/commit-selection.ts

@@ -0,0 +1,63 @@
+/**
+ * Commit-dialog selection state — pure helpers, unit-testable.
+ *
+ * All changed files are included by default. While a merge is being
+ * concluded, conflicted files are force-included: committing a subset that
+ * omits them would not resolve the merge.
+ */
+
+import type { GitFileChange, GitStatus } from '@bendyline/docblocks/host';
+
+export interface CommitSelection {
+  /** Slash-prefixed path → include in the commit. */
+  included: Map<string, boolean>;
+  /** Paths the user cannot exclude (conflicted files during a merge). */
+  locked: Set<string>;
+}
+
+function normalise(path: string): string {
+  return path.startsWith('/') ? path : `/${path}`;
+}
+
+export function initSelection(
+  changes: readonly GitFileChange[],
+  merging: boolean,
+): CommitSelection {
+  const included = new Map<string, boolean>();
+  const locked = new Set<string>();
+  for (const change of changes) {
+    const path = normalise(change.path);
+    included.set(path, true);
+    if (merging && change.conflicted) locked.add(path);
+  }
+  return { included, locked };
+}
+
+export function toggleSelection(selection: CommitSelection, path: string): CommitSelection {
+  const key = normalise(path);
+  if (selection.locked.has(key)) return selection;
+  const included = new Map(selection.included);
+  included.set(key, !included.get(key));
+  return { included, locked: selection.locked };
+}
+
+export function setAllSelected(selection: CommitSelection, value: boolean): CommitSelection {
+  const included = new Map<string, boolean>();
+  for (const key of selection.included.keys()) {
+    included.set(key, selection.locked.has(key) ? true : value);
+  }
+  return { included, locked: selection.locked };
+}
+
+export function selectedPaths(selection: CommitSelection): string[] {
+  return [...selection.included.entries()].filter(([, on]) => on).map(([path]) => path);
+}
+
+export function canCommit(message: string, selection: CommitSelection): boolean {
+  return message.trim().length > 0 && selectedPaths(selection).length > 0;
+}
+
+/** True when committing concludes an in-progress merge. */
+export function isMergeCommit(status: GitStatus | null): boolean {
+  return status?.operation === 'merge';
+}

package/src/Git/git-clone-utils.ts

@@ -0,0 +1,23 @@
+/**
+ * Clone-dialog helpers — pure URL utilities, unit-testable.
+ */
+
+/** Folder name a clone of this URL will produce (mirrors the host's rule). */
+export function deriveCloneFolderName(url: string): string {
+  const trimmed = url.trim().replace(/\/+$/, '');
+  const lastSegment = trimmed.split(/[/:\\]/).pop() ?? '';
+  const withoutGit = lastSegment.replace(/\.git$/i, '');
+  const sanitized = withoutGit.replace(/[^A-Za-z0-9._-]/g, '-');
+  return sanitized.length > 0 ? sanitized : 'repository';
+}
+
+/** Loose shape check for enabling the Clone button — the host re-validates. */
+export function isLikelyGitUrl(url: string): boolean {
+  const trimmed = url.trim();
+  if (trimmed.length === 0 || /\s/.test(trimmed)) return false;
+  if (trimmed.startsWith('-') || trimmed.toLowerCase().startsWith('file:')) return false;
+  if (/^(https?|ssh|git):\/\/\S+\/\S+/i.test(trimmed)) return true;
+  // scp-like: user@host:owner/repo
+  if (/^[\w.-]+@[\w.-]+:\S+/.test(trimmed)) return true;
+  return false;
+}

package/src/Git/git-status.ts

@@ -0,0 +1,113 @@
+/**
+ * Pure helpers mapping GitStatus onto UI concerns — file-tree badges,
+ * ahead/behind chips, dirty summaries. No React, no host access.
+ */
+
+import type { GitFileChange, GitStatus } from '@bendyline/docblocks/host';
+
+export type GitBadgeKind =
+  | 'modified'
+  | 'added'
+  | 'untracked'
+  | 'renamed'
+  | 'deleted'
+  | 'conflicted'
+  | 'dir';
+
+export const BADGE_GLYPHS: Record<GitBadgeKind, string> = {
+  modified: 'M',
+  added: 'A',
+  untracked: 'U',
+  renamed: 'R',
+  deleted: 'D',
+  conflicted: '!',
+  dir: '•',
+};
+
+export const BADGE_LABELS: Record<GitBadgeKind, string> = {
+  modified: 'modified',
+  added: 'added',
+  untracked: 'untracked',
+  renamed: 'renamed',
+  deleted: 'deleted',
+  conflicted: 'has conflicts',
+  dir: 'contains changes',
+};
+
+function normalise(path: string): string {
+  return path.startsWith('/') ? path : `/${path}`;
+}
+
+/** True when any path segment is a dot-entry (.git, .github, .gitignore…). */
+function isDotPath(path: string): boolean {
+  return normalise(path)
+    .split('/')
+    .some((segment) => segment.startsWith('.'));
+}
+
+export function badgeKindFor(change: GitFileChange): GitBadgeKind {
+  if (change.conflicted) return 'conflicted';
+  if (change.worktree === 'untracked') return 'untracked';
+  if (change.index === 'deleted' || change.worktree === 'deleted') return 'deleted';
+  if (change.index === 'renamed' || change.worktree === 'renamed') return 'renamed';
+  if (change.index === 'added' || change.worktree === 'added') return 'added';
+  return 'modified';
+}
+
+/**
+ * Slash-prefixed path → badge kind, including directory rollups: any
+ * ancestor directory of a changed file gets a 'dir' dot (or 'conflicted'
+ * when a conflicted descendant wins). Deleted files aren't in the tree, so
+ * they contribute only their ancestor rollup. Dot-paths are excluded so a
+ * `.gitignore` edit doesn't inexplicably dot the root.
+ */
+export function buildBadgeMap(changes: readonly GitFileChange[]): Map<string, GitBadgeKind> {
+  const badges = new Map<string, GitBadgeKind>();
+  const dirKinds = new Map<string, GitBadgeKind>();
+
+  for (const change of changes) {
+    if (isDotPath(change.path)) continue;
+    const filePath = normalise(change.path);
+    const kind = badgeKindFor(change);
+    if (kind !== 'deleted') {
+      badges.set(filePath, kind);
+    }
+    const segments = filePath.split('/').slice(1, -1);
+    let dir = '';
+    for (const segment of segments) {
+      dir += `/${segment}`;
+      const rollup = kind === 'conflicted' ? 'conflicted' : 'dir';
+      if (dirKinds.get(dir) !== 'conflicted') dirKinds.set(dir, rollup);
+    }
+  }
+  for (const [dir, kind] of dirKinds) {
+    if (!badges.has(dir)) badges.set(dir, kind);
+  }
+  return badges;
+}
+
+/** "2↑ 1↓" — empty string when neither applies. */
+export function formatAheadBehind(status: Pick<GitStatus, 'ahead' | 'behind'>): string {
+  const parts: string[] = [];
+  if (status.ahead > 0) parts.push(`${status.ahead}↑`);
+  if (status.behind > 0) parts.push(`${status.behind}↓`);
+  return parts.join(' ');
+}
+
+export function isFileDirty(status: GitStatus | null, path: string | null): boolean {
+  if (!status || !path) return false;
+  const target = normalise(path);
+  return status.changes.some((c) => normalise(c.path) === target);
+}
+
+export function conflictedPaths(status: GitStatus | null): string[] {
+  if (!status) return [];
+  return status.changes.filter((c) => c.conflicted).map((c) => normalise(c.path));
+}
+
+/** "3 changes" / "1 change" / "" when clean. */
+export function summarizeDirty(status: GitStatus | null): string {
+  const count = status?.changes.length ?? 0;
+  if (count === 0) return '';
+  return count === 1 ? '1 change' : `${count} changes`;
+}

package/src/Git/useGit.ts

@@ -0,0 +1,279 @@
+/**
+ * useGit — the single hook DocBlocksShell calls to power all git UI.
+ *
+ * Tier 1 (`available`): running under the Electron host with a working git —
+ * gates only the clone entry. Tier 2 (`repo`): the active workspace is an
+ * electron-native folder that is a git repository — gates everything else.
+ * On the site / VS Code webview / store builds every surface null-renders.
+ *
+ * Actions never throw: typed GitErrors are routed to the auth-guidance or
+ * conflicts dialogs when actionable, otherwise to the aria-live result line.
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import type {
+  DocBlocksHostGitAPI,
+  GitCapabilities,
+  GitError,
+  GitRepoDetection,
+  GitRemoteInfo,
+} from '@bendyline/docblocks/host';
+import { maybeGetDocBlocksHost } from '@bendyline/docblocks/host';
+import type { FileSystemProvider } from '@bendyline/docblocks/filesystem';
+import { buildBadgeMap, conflictedPaths } from './git-status.js';
+import { useGitStatus } from './useGitStatus.js';
+import type { GitBusyKind, GitDialogState, GitInlineResult, GitValue } from './GitContext.js';
+
+/** Capabilities can't change within a session — probe once per page load. */
+let capabilitiesPromise: Promise<GitCapabilities> | null = null;
+function capabilitiesOnce(gitApi: DocBlocksHostGitAPI): Promise<GitCapabilities> {
+  capabilitiesPromise ??= gitApi.capabilities();
+  return capabilitiesPromise;
+}
+
+function describeError(error: GitError): string {
+  return error.message || 'Git operation failed';
+}
+
+export function useGit(
+  provider: FileSystemProvider | null,
+  requestedWorkspaceId: string | null,
+  theme: 'light' | 'dark',
+): GitValue {
+  const host = maybeGetDocBlocksHost();
+  const gitApi = host?.git ?? null;
+  const workspaceId = gitApi ? requestedWorkspaceId : null;
+
+  const [capabilities, setCapabilities] = useState<GitCapabilities | null>(null);
+  useEffect(() => {
+    if (!gitApi) return;
+    let cancelled = false;
+    void capabilitiesOnce(gitApi).then((caps) => {
+      if (!cancelled) setCapabilities(caps);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [gitApi]);
+
+  const available = gitApi !== null && capabilities?.gitAvailable === true;
+
+  const [repo, setRepo] = useState<GitRepoDetection | null>(null);
+  const [remoteWeb, setRemoteWeb] = useState<GitValue['remoteWeb']>(null);
+  useEffect(() => {
+    setRepo(null);
+    setRemoteWeb(null);
+    if (!gitApi || !workspaceId || !available) return;
+    let cancelled = false;
+    void gitApi.detectRepo(workspaceId).then((result) => {
+      if (cancelled || !result.ok || !result.value.isRepo || !result.value.repositoryId) {
+        return;
+      }
+      setRepo(result.value);
+      void gitApi.listRemotes(result.value.repositoryId).then((remotes) => {
+        if (cancelled || !remotes.ok) return;
+        const first: GitRemoteInfo | undefined = remotes.value[0];
+        setRemoteWeb(first?.web ?? null);
+      });
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [gitApi, workspaceId, available]);
+
+  const repositoryId = repo?.repositoryId ?? null;
+  const isRepo = repositoryId !== null;
+  const { status, refresh, scheduleRefresh } = useGitStatus(gitApi, repositoryId, isRepo);
+  const badges = useMemo(() => buildBadgeMap(status?.changes ?? []), [status]);
+
+  const [busy, setBusy] = useState<GitBusyKind>(null);
+  const [lastResult, setLastResult] = useState<GitInlineResult | null>(null);
+  const [dialog, setDialog] = useState<GitDialogState>({ kind: 'none' });
+
+  const openDialog = useCallback((next: GitDialogState) => setDialog(next), []);
+  const closeDialog = useCallback(() => setDialog({ kind: 'none' }), []);
+
+  // Route a failed operation somewhere useful.
+  const routeError = useCallback(
+    (operation: 'push' | 'pull' | 'fetch' | 'commit' | 'branch' | 'pr', error: GitError) => {
+      if (error.code === 'auth-failed') {
+        setDialog({
+          kind: 'auth-guidance',
+          operation: operation === 'commit' || operation === 'branch' ? 'push' : operation,
+          detail: error.message,
+        });
+        return;
+      }
+      setLastResult({ tone: 'error', message: describeError(error) });
+    },
+    [],
+  );
+
+  const statusRef = useRef(status);
+  statusRef.current = status;
+
+  const runAction = useCallback(
+    async <T>(
+      kind: Exclude<GitBusyKind, null>,
+      operation: 'push' | 'pull' | 'fetch' | 'commit' | 'branch' | 'pr',
+      action: (
+        api: DocBlocksHostGitAPI,
+        repository: string,
+      ) => Promise<{ ok: true; value: T } | { ok: false; error: GitError }>,
+      successMessage?: string,
+    ): Promise<boolean> => {
+      if (!gitApi || !repositoryId) return false;
+      setBusy(kind);
+      setLastResult(null);
+      try {
+        const result = await action(gitApi, repositoryId);
+        if (result.ok) {
+          if (successMessage) setLastResult({ tone: 'info', message: successMessage });
+          refresh();
+          return true;
+        }
+        if (operation === 'pull' && result.error.code === 'merge-conflict') {
+          // Surface the conflicted files; the fresh status carries them.
+          const fresh = await gitApi.status(repositoryId);
+          const paths = fresh.ok ? conflictedPaths(fresh.value) : [];
+          refresh();
+          setDialog({ kind: 'conflicts', paths });
+          setLastResult({ tone: 'error', message: 'Pull hit merge conflicts' });
+          return false;
+        }
+        routeError(operation, result.error);
+        refresh();
+        return false;
+      } finally {
+        setBusy(null);
+      }
+    },
+    [gitApi, repositoryId, refresh, routeError],
+  );
+
+  const commit = useCallback(
+    (message: string, paths: string[]) =>
+      runAction(
+        'commit',
+        'commit',
+        (api, repository) => api.commit(repository, message, paths),
+        'Committed',
+      ),
+    [runAction],
+  );
+
+  const push = useCallback(async () => {
+    const setUpstream = statusRef.current?.upstream === null;
+    await runAction(
+      'push',
+      'push',
+      (api, repository) => api.push(repository, setUpstream ? { setUpstream: true } : undefined),
+      setUpstream ? 'Branch published' : 'Pushed',
+    );
+  }, [runAction]);
+
+  const pull = useCallback(async () => {
+    await runAction('pull', 'pull', (api, repository) => api.pull(repository), 'Pulled');
+  }, [runAction]);
+
+  const fetchRemote = useCallback(async () => {
+    await runAction('fetch', 'fetch', (api, repository) => api.fetch(repository), 'Fetched');
+  }, [runAction]);
+
+  const createBranch = useCallback(
+    (name: string) =>
+      runAction(
+        'branch',
+        'branch',
+        (api, repository) => api.createBranch(repository, name, { checkout: true }),
+        `Switched to new branch ${name}`,
+      ),
+    [runAction],
+  );
+
+  const switchBranch = useCallback(
+    (name: string) =>
+      runAction(
+        'branch',
+        'branch',
+        (api, repository) => api.checkoutBranch(repository, name),
+        `Switched to ${name}`,
+      ),
+    [runAction],
+  );
+
+  const openOnRemote = useCallback(
+    (filePath?: string) => {
+      if (!remoteWeb || !host) return;
+      let url = remoteWeb.webUrl;
+      // Only GitHub's blob-path shape is a safe bet; other hosts get the repo.
+      if (filePath && remoteWeb.host === 'github.com' && statusRef.current?.branch) {
+        const rel = filePath.replace(/^\/+/, '');
+        url = `${remoteWeb.webUrl}/blob/${encodeURIComponent(statusRef.current.branch)}/${rel
+          .split('/')
+          .map(encodeURIComponent)
+          .join('/')}`;
+      }
+      void host.shell.openExternal(url);
+    },
+    [remoteWeb, host],
+  );
+
+  const createPullRequest = useCallback(async () => {
+    if (!gitApi || !repositoryId) return;
+    setBusy('pr');
+    setLastResult(null);
+    try {
+      const result = await gitApi.createPullRequest(repositoryId);
+      if (result.ok) {
+        setLastResult({ tone: 'info', message: 'Opening pull request in browser' });
+        return;
+      }
+      if (result.error.code === 'no-upstream') {
+        setLastResult({
+          tone: 'error',
+          message: 'Push the branch first, then create the pull request',
+        });
+        return;
+      }
+      if (result.error.code === 'gh-not-available') {
+        setLastResult({
+          tone: 'error',
+          message: 'Install the GitHub CLI (gh) to create pull requests',
+        });
+        return;
+      }
+      routeError('pr', result.error);
+    } finally {
+      setBusy(null);
+    }
+  }, [gitApi, repositoryId, routeError]);
+
+  return {
+    available,
+    capabilities,
+    repo,
+    repositoryId,
+    remoteWeb,
+    gitApi,
+    provider,
+    theme,
+    status,
+    badges,
+    busy,
+    lastResult,
+    refresh,
+    scheduleRefresh,
+    commit,
+    push,
+    pull,
+    fetchRemote,
+    createBranch,
+    switchBranch,
+    openOnRemote,
+    createPullRequest,
+    dialog,
+    openDialog,
+    closeDialog,
+  };
+}

package/src/Git/useGitStatus.ts

@@ -0,0 +1,78 @@
+/**
+ * useGitStatus — subscribes to the host's owner-scoped repository stream.
+ *
+ * Dedupes identical payloads so a permanently-dirty working tree (normal
+ * under the manual-commit model) doesn't repaint the tree on every push
+ * from the main process.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { DocBlocksHostGitAPI, GitStatus } from '@bendyline/docblocks/host';
+
+const SCHEDULE_REFRESH_MS = 1500;
+
+function statusKey(status: GitStatus): string {
+  return JSON.stringify(status);
+}
+
+export interface UseGitStatusResult {
+  status: GitStatus | null;
+  /** Fetch a fresh status immediately (after a renderer-initiated git op). */
+  refresh: () => void;
+  /** Trailing-debounced refresh (after autosave writes). */
+  scheduleRefresh: () => void;
+}
+
+export function useGitStatus(
+  gitApi: DocBlocksHostGitAPI | null,
+  repositoryId: string | null,
+  enabled: boolean,
+): UseGitStatusResult {
+  const [status, setStatus] = useState<GitStatus | null>(null);
+  const lastKeyRef = useRef<string | null>(null);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const apply = useCallback((next: GitStatus) => {
+    const key = statusKey(next);
+    if (key === lastKeyRef.current) return;
+    lastKeyRef.current = key;
+    setStatus(next);
+  }, []);
+
+  useEffect(() => {
+    lastKeyRef.current = null;
+    setStatus(null);
+    if (!gitApi || !repositoryId || !enabled) return;
+    let cancelled = false;
+    const unsubscribe = gitApi.onStatusChanged(repositoryId, (next) => {
+      if (!cancelled) apply(next);
+    });
+    return () => {
+      cancelled = true;
+      unsubscribe();
+    };
+  }, [gitApi, repositoryId, enabled, apply]);
+
+  const refresh = useCallback(() => {
+    if (!gitApi || !repositoryId || !enabled) return;
+    void gitApi.status(repositoryId).then((result) => {
+      if (result.ok) apply(result.value);
+    });
+  }, [gitApi, repositoryId, enabled, apply]);
+
+  const scheduleRefresh = useCallback(() => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+    timerRef.current = setTimeout(() => {
+      timerRef.current = null;
+      refresh();
+    }, SCHEDULE_REFRESH_MS);
+  }, [refresh]);
+
+  useEffect(() => {
+    return () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+    };
+  }, []);
+
+  return { status, refresh, scheduleRefresh };
+}

package/src/Settings/Settings.tsx

@@ -0,0 +1,118 @@
+/** Shared controls used by the app and host-specific DocBlocks settings dialogs. */
+
+import type { ReactNode } from 'react';
+import { Dialog } from '../components/Dialog.js';
+import { ACCENT_COLORS, type AccentColor, type ThemePreference } from '../preferences/theme.js';
+
+export type { AccentColor, ThemePreference } from '../preferences/theme.js';
+
+const ACCENT_LABELS: Record<AccentColor, string> = {
+  brown: 'Brown',
+  green: 'Green',
+  blue: 'Blue',
+  purple: 'Purple',
+  maroon: 'Maroon',
+  orange: 'Orange',
+  gray: 'Gray',
+};
+
+export interface SettingsDialogProps {
+  title?: string;
+  onClose: () => void;
+  children: ReactNode;
+}
+
+export function SettingsDialog({ title = 'Settings', onClose, children }: SettingsDialogProps) {
+  return (
+    <Dialog title={title} onClose={onClose}>
+      {children}
+    </Dialog>
+  );
+}
+
+export interface ThemeSettingsProps {
+  value: ThemePreference;
+  onChange: (theme: ThemePreference) => void;
+  name?: string;
+}
+
+export function ThemeSettings({ value, onChange, name = 'theme' }: ThemeSettingsProps) {
+  return (
+    <fieldset className="db-settings-fieldset">
+      <legend className="db-settings-legend">Theme</legend>
+      <label className="db-settings-radio">
+        <input
+          type="radio"
+          name={name}
+          value="auto"
+          checked={value === 'auto'}
+          onChange={() => onChange('auto')}
+        />
+        System default
+      </label>
+      <label className="db-settings-radio">
+        <input
+          type="radio"
+          name={name}
+          value="light"
+          checked={value === 'light'}
+          onChange={() => onChange('light')}
+        />
+        Light
+      </label>
+      <label className="db-settings-radio">
+        <input
+          type="radio"
+          name={name}
+          value="dark"
+          checked={value === 'dark'}
+          onChange={() => onChange('dark')}
+        />
+        Dark
+      </label>
+    </fieldset>
+  );
+}
+
+export interface AccentColorSettingsProps {
+  value: AccentColor;
+  onChange: (color: AccentColor) => void;
+  name?: string;
+}
+
+export function AccentColorSettings({
+  value,
+  onChange,
+  name = 'accent-color',
+}: AccentColorSettingsProps) {
+  return (
+    <fieldset className="db-settings-fieldset">
+      <legend className="db-settings-legend">Accent color</legend>
+      <p className="db-settings-hint">Used in both light and dark appearances.</p>
+      <div className="db-settings-accent-grid">
+        {ACCENT_COLORS.map((color) => (
+          <label
+            className={`db-settings-accent${
+              value === color ? ' db-settings-accent--selected' : ''
+            }`}
+            key={color}
+          >
+            <input
+              className="db-settings-accent-input"
+              type="radio"
+              name={name}
+              value={color}
+              checked={value === color}
+              onChange={() => onChange(color)}
+            />
+            <span
+              className={`db-settings-accent-swatch db-settings-accent-swatch--${color}`}
+              aria-hidden="true"
+            />
+            <span>{ACCENT_LABELS[color]}</span>
+          </label>
+        ))}
+      </div>
+    </fieldset>
+  );
+}

package/src/Settings/public-api.ts

@@ -0,0 +1,8 @@
+export { AccentColorSettings, SettingsDialog, ThemeSettings } from './Settings.js';
+export type {
+  AccentColor,
+  AccentColorSettingsProps,
+  SettingsDialogProps,
+  ThemePreference,
+  ThemeSettingsProps,
+} from './Settings.js';