secondbrain-py 0.2.1__py3-none-any.whl

brain/quartz_overrides/quartz/components/CommandPalette.tsx

@@ -0,0 +1,172 @@
+// Brain command palette component (Lane C, Cmd/Ctrl-P).
+//
+// This file is a TEMPLATE. It is installed at
+// `<vault>/.quartz/quartz/components/CommandPalette.tsx` by `brain
+// vault render --overlay`. It does NOT compile or run from the brain
+// repo itself; the imports below resolve against the dependencies
+// Quartz pulls into the cloned workspace via `npm install`, not
+// against any package brain ships.
+//
+// Tested against Quartz v4.5.x (April 2026). The component shape
+// mirrors stock Quartz components — see `Graph.tsx` (also a
+// brain-overlayed component) for the canonical pattern. If a future
+// Quartz version restructures `QuartzComponent` / `QuartzComponentProps`,
+// pull the latest reference component from
+// https://github.com/jackyzha0/quartz/blob/v4/quartz/components/
+// and re-apply the brain tweaks below.
+//
+// Strategy — full new component (not an upstream override): nothing
+// in stock Quartz exposes a quick-open palette. We render the palette
+// markup once per page (registered in `quartz.layout.ts` `afterBody`
+// slot — global, ships with every page in the build), then a
+// co-located inline script (`scripts/commandPalette.inline.ts`)
+// owns the open/close lifecycle, source chips, fuzzy search, keyboard
+// handling, and SPA-nav cleanup.
+//
+// brain (Lane C audit fix 2026-05-02): refactored to native
+// `<dialog>` element. Native dialog gives us, for free:
+//   * Focus trap inside the modal while open (no manual `Tab` ring
+//     management needed).
+//   * Native `Escape` close behavior + `cancel` event we can intercept
+//     to keep the brain close-animation.
+//   * Automatic focus restoration to the previously-focused element
+//     on `dialog.close()`.
+//   * Native `::backdrop` pseudo-element — replaces the manual
+//     `.brain-cmdk-backdrop` div with a CSS-driven scrim that the
+//     browser positions above the rest of the page (top of the
+//     stacking context, no z-index gymnastics).
+// All four are non-trivial to implement correctly by hand; using the
+// platform primitive removes drift surface.
+//
+// Markup contract — must stay in sync with the selector list in
+// `_command_palette.scss` (Lane C/P5.3 SCSS partial) and the DOM walk inside
+// `commandPalette.inline.ts`. See those two files' top comments.
+//
+// brain (Lane C audit fix 2026-05-02): combobox semantics on the
+// search input. Plain `<input aria-controls=...>` is an a11y no-op;
+// the WAI-ARIA combobox pattern is `role="combobox"` +
+// `aria-expanded` (toggled by the script) + `aria-haspopup="listbox"`
+// + `aria-autocomplete="list"`. Pairs with `aria-activedescendant`
+// (set per-keystroke by the script) so screen readers announce each
+// arrow-key result.
+//
+// Responsibility (CLAUDE.md rule 8): this file owns the Preact
+// component wrapper. Open/close + search logic lives in
+// `scripts/commandPalette.inline.ts`; the visual rules live in
+// `../styles/brain/_command_palette.scss`. Don't let them spill into each
+// other.
+
+import { QuartzComponent, QuartzComponentConstructor, QuartzComponentProps } from "./types"
+// @ts-ignore — esbuild-loader resolves .ts to a bundled string; TS doesn't know.
+import script from "./scripts/commandPalette.inline"
+import { SOURCE_ICONS, SOURCE_CHIP_ORDER } from "../util/sourceIcons"
+
+const CHIP_VALUES: ReadonlyArray<keyof typeof SOURCE_ICONS> = SOURCE_CHIP_ORDER
+
+const CommandPalette: QuartzComponent = (_props: QuartzComponentProps) => {
+  // brain: native `<dialog>` element. The script calls `showModal()`
+  // to open and `close()` to dismiss; both manage focus + scroll-lock
+  // + the `::backdrop` pseudo-element automatically. The `id` is the
+  // selector hook used by `commandPalette.inline.ts` and `_command_palette.scss`
+  // — don't rename without updating both.
+  //
+  // brain: `aria-label` on the dialog gives screen readers a name
+  // when the dialog opens (replacing the now-unnecessary `role` /
+  // `aria-modal` attributes — native dialog provides both).
+  return (
+    <dialog id="brain-cmdk-root" class="brain-cmdk-root" aria-label="Command palette">
+      <div class="brain-cmdk-modal">
+        <div class="brain-cmdk-chips" role="group" aria-label="Filter quick open by source">
+          <button
+            type="button"
+            class="brain-cmdk-chip brain-cmdk-chip-all"
+            data-brain-source="__all__"
+            data-active="true"
+            aria-pressed="true"
+          >
+            All
+          </button>
+          {CHIP_VALUES.map((value) => (
+            <button
+              type="button"
+              class="brain-cmdk-chip"
+              data-brain-source={value}
+              data-active="true"
+              aria-pressed="true"
+            >
+              <span class="brain-cmdk-chip-icon" aria-hidden="true">
+                {SOURCE_ICONS[value]}
+              </span>
+              <span class="brain-cmdk-chip-label">{value}</span>
+            </button>
+          ))}
+        </div>
+        <input
+          class="brain-cmdk-input"
+          type="text"
+          autocomplete="off"
+          autocorrect="off"
+          spellcheck={false}
+          placeholder="Search the wiki…"
+          // brain (Lane C audit fix): WAI-ARIA combobox pattern.
+          //   * role="combobox" tells AT this is a search input that
+          //     drives an associated popup.
+          //   * aria-expanded mirrors visibility (set by the script
+          //     when the dialog opens / closes).
+          //   * aria-haspopup="listbox" + aria-autocomplete="list"
+          //     describes the popup shape.
+          //   * aria-controls links to the listbox by id.
+          //   * aria-activedescendant (set per-keystroke by the
+          //     script) points to the currently-selected option's id
+          //     so AT can announce it on each arrow press without
+          //     moving DOM focus off the input.
+          role="combobox"
+          aria-expanded="false"
+          aria-haspopup="listbox"
+          aria-controls="brain-cmdk-results"
+          aria-autocomplete="list"
+          aria-label="Search the wiki"
+        />
+        {/* brain: results list rendered by the inline script. The
+            initial `<ul>` is empty; the script injects `<li
+            class="brain-cmdk-result" id="brain-cmdk-result-N">` rows
+            from the contentIndex match. Each `<li>` carries the
+            stable id the input's `aria-activedescendant` points at. */}
+        <ul
+          class="brain-cmdk-results"
+          id="brain-cmdk-results"
+          role="listbox"
+          aria-label="Search results"
+        ></ul>
+        <div class="brain-cmdk-empty" hidden>
+          No results.
+        </div>
+        <div class="brain-cmdk-footer" aria-hidden="true">
+          <kbd>↑</kbd>
+          <kbd>↓</kbd>
+          <span>navigate</span>
+          <span>·</span>
+          <kbd>↵</kbd>
+          <span>open</span>
+          <span>·</span>
+          <kbd>esc</kbd>
+          <span>close</span>
+        </div>
+      </div>
+    </dialog>
+  )
+}
+
+// brain: wire the inline script. esbuild-loader resolves the
+// `.inline.ts` import to its compiled bundled string at build time;
+// Quartz inlines the string into the page at `</body>` time when
+// `afterDOMLoaded` is set.
+CommandPalette.afterDOMLoaded = script
+
+// brain: no component-css here — visuals live in the global
+// `_command_palette.scss`, which is `@use`-imported via `custom.scss`. That
+// ensures the styles ship with EVERY page (not just pages that mount
+// the component), so first-paint of any page already has the modal's
+// resting state (closed `<dialog>`) rendered without flashing.
+
+export default (() => CommandPalette) satisfies QuartzComponentConstructor

brain/quartz_overrides/quartz/components/Explorer.tsx

@@ -0,0 +1,198 @@
+// Brain wiki overlay — quartz/components/Explorer.tsx
+//
+// This file shadows the upstream ``~/brain-vault/.quartz/quartz/components/Explorer.tsx``.
+// All upstream functionality is preserved verbatim.  The only change is the
+// replacement of the module-level ``numExplorers`` counter with a slug-derived
+// deterministic ID.
+//
+// Amendment #8 (T4 — Plan B v3):
+//   The upstream Explorer uses a module-level counter (``let numExplorers = 0``)
+//   to generate unique aria-id attributes: ``explorer-0``, ``explorer-1``, etc.
+//   In a full build, the counter increments with render order; in a partial build
+//   (fresh Node process), the counter resets to 0. The same slug may therefore
+//   produce a different id in the two paths, breaking byte-exact HTML parity and
+//   confusing the browser's aria-controls association on page reload.
+//
+//   Fix: replace the counter with a slug-derived deterministic id
+//   (``explorer-<slug-with-slashes-as-hyphens>``). The id is unique per page
+//   (each page renders exactly one Explorer), deterministic across builds, and
+//   independent of render order.
+//
+//   This overlay applies in BOTH full-build and partial-build paths so both
+//   produce the same HTML for the same slug regardless of order or process lifetime.
+
+import { QuartzComponent, QuartzComponentConstructor, QuartzComponentProps } from "./types"
+import style from "./styles/explorer.scss"
+
+// @ts-ignore
+import script from "./scripts/explorer.inline"
+import { classNames } from "../util/lang"
+import { i18n } from "../i18n"
+import { FileTrieNode } from "../util/fileTrie"
+import OverflowListFactory from "./OverflowList"
+import { concatenateResources } from "../util/resources"
+
+type OrderEntries = "sort" | "filter" | "map"
+
+export interface Options {
+  title?: string
+  folderDefaultState: "collapsed" | "open"
+  folderClickBehavior: "collapse" | "link"
+  useSavedState: boolean
+  sortFn: (a: FileTrieNode, b: FileTrieNode) => number
+  filterFn: (node: FileTrieNode) => boolean
+  mapFn: (node: FileTrieNode) => void
+  order: OrderEntries[]
+}
+
+const defaultOptions: Options = {
+  folderDefaultState: "collapsed",
+  folderClickBehavior: "link",
+  useSavedState: true,
+  mapFn: (node) => {
+    return node
+  },
+  sortFn: (a, b) => {
+    // Sort order: folders first, then files. Sort folders and files alphabeticall
+    if ((!a.isFolder && !b.isFolder) || (a.isFolder && b.isFolder)) {
+      // numeric: true: Whether numeric collation should be used, such that "1" < "2" < "10"
+      // sensitivity: "base": Only strings that differ in base letters compare as unequal. Examples: a ≠ b, a = á, a = A
+      return a.displayName.localeCompare(b.displayName, undefined, {
+        numeric: true,
+        sensitivity: "base",
+      })
+    }
+
+    if (!a.isFolder && b.isFolder) {
+      return 1
+    } else {
+      return -1
+    }
+  },
+  filterFn: (node) => node.slugSegment !== "tags",
+  order: ["filter", "map", "sort"],
+}
+
+export type FolderState = {
+  path: string
+  collapsed: boolean
+}
+
+// brain overlay (Amendment #8): the upstream numExplorers counter is REMOVED.
+// Each Explorer uses a slug-derived deterministic id instead.
+// See file-level comment for full rationale.
+
+export default ((userOpts?: Partial<Options>) => {
+  const opts: Options = { ...defaultOptions, ...userOpts }
+  const { OverflowList, overflowListAfterDOMLoaded } = OverflowListFactory()
+
+  // brain overlay (Amendment #8): accept fileData from props and derive a
+  // deterministic, slug-based aria-id for the Explorer component.
+  // ``/`` → ``-`` so ``COMPANY_REDACTED/AI-adoption`` becomes ``explorer-COMPANY_REDACTED-AI-adoption``.
+  const Explorer: QuartzComponent = ({ cfg, fileData, displayClass }: QuartzComponentProps) => {
+    // Slug-derived deterministic ID: stable across full-build render order and
+    // partial-build fresh processes.  Replaces the upstream numExplorers counter.
+    const rawSlug = fileData?.slug ?? "root"
+    const slugId = rawSlug.replace(/\//g, "-")
+    const id = `explorer-${slugId}`
+
+    return (
+      <div
+        class={classNames(displayClass, "explorer")}
+        data-behavior={opts.folderClickBehavior}
+        data-collapsed={opts.folderDefaultState}
+        data-savestate={opts.useSavedState}
+        data-data-fns={JSON.stringify({
+          order: opts.order,
+          sortFn: opts.sortFn.toString(),
+          filterFn: opts.filterFn.toString(),
+          mapFn: opts.mapFn.toString(),
+        })}
+      >
+        <button
+          type="button"
+          class="explorer-toggle mobile-explorer hide-until-loaded"
+          data-mobile={true}
+          aria-controls={id}
+        >
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="24"
+            height="24"
+            viewBox="0 0 24 24"
+            stroke-width="2"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+            class="lucide-menu"
+          >
+            <line x1="4" x2="20" y1="12" y2="12" />
+            <line x1="4" x2="20" y1="6" y2="6" />
+            <line x1="4" x2="20" y1="18" y2="18" />
+          </svg>
+        </button>
+        <button
+          type="button"
+          class="title-button explorer-toggle desktop-explorer"
+          data-mobile={false}
+          aria-expanded={true}
+        >
+          <h2>{opts.title ?? i18n(cfg.locale).components.explorer.title}</h2>
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="14"
+            height="14"
+            viewBox="5 8 14 8"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+            class="fold"
+          >
+            <polyline points="6 9 12 15 18 9"></polyline>
+          </svg>
+        </button>
+        <div id={id} class="explorer-content" aria-expanded={false} role="group">
+          <OverflowList class="explorer-ul" />
+        </div>
+        <template id="template-file">
+          <li>
+            <a href="#"></a>
+          </li>
+        </template>
+        <template id="template-folder">
+          <li>
+            <div class="folder-container">
+              <svg
+                xmlns="http://www.w3.org/2000/svg"
+                width="12"
+                height="12"
+                viewBox="5 8 14 8"
+                fill="none"
+                stroke="currentColor"
+                stroke-width="2"
+                stroke-linecap="round"
+                stroke-linejoin="round"
+                class="folder-icon"
+              >
+                <polyline points="6 9 12 15 18 9"></polyline>
+              </svg>
+              <div>
+                <button class="folder-button">
+                  <span class="folder-title"></span>
+                </button>
+              </div>
+            </div>
+            <div class="folder-outer">
+              <ul class="content"></ul>
+            </div>
+          </li>
+        </template>
+      </div>
+    )
+  }
+
+  Explorer.css = style
+  Explorer.afterDOMLoaded = concatenateResources(script, overflowListAfterDOMLoaded)
+  return Explorer
+}) satisfies QuartzComponentConstructor

brain/quartz_overrides/quartz/components/Footer.tsx

@@ -0,0 +1,27 @@
+import { QuartzComponent, QuartzComponentConstructor } from "./types"
+
+interface Options {
+  links: Record<string, string>
+}
+
+export default ((opts?: Options) => {
+  const githubUrl = opts?.links?.GitHub
+
+  const Footer: QuartzComponent = () => (
+    <footer>
+      <p>
+        Second Brain
+        {githubUrl ? (
+          <>
+            {" "}
+            (<a href={githubUrl}>GitHub</a>)
+          </>
+        ) : null}{" "}
+        · © 2026 · notes for my future self · powered by{" "}
+        <a href="https://quartz.jzhao.xyz/">Quartz</a>
+      </p>
+    </footer>
+  )
+
+  return Footer
+}) satisfies QuartzComponentConstructor