rename annotation -> item

LICENSE

@@ -39,7 +39,7 @@
 
       "Derivative Works" shall mean any work, whether in Source or Object
       form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
+      editorial revisions, items, elaborations, or other modifications
       represent, as a whole, an original work of authorship. For the purposes
       of this License, Derivative Works shall not include works that remain
       separable from, or merely link (or bind by name) to the interfaces of,

README.md

@@ -41,9 +41,13 @@ _Status: alpha_
 
 OpenCtx
 
-Annotations - should generalize and just make it ContextItems. Adds context about code files, chat messages, etc. Attachment can be a file range,
+Items - should generalize and just make it ContextItems. Adds context about code files, chat messages, etc. Attachment can be a file range,
 .
 
 Not just context, but also actions.
 
 OpenCtx
+
+## TODOs for rename
+
+- migrate GCS bucket

client/browser/src/background/background.main.ts

@@ -42,7 +42,7 @@ function main(): void {
 
     subscriptions.add(
         addMessageListenersForBackgroundApi({
-            annotationsChanges: (...args) => client.annotationsChanges(...args),
+            itemsChanges: (...args) => client.itemsChanges(...args),
         })
     )
 

client/browser/src/browser-extension/web-extension-api/runtime.ts

@@ -5,5 +5,5 @@ import type { BackgroundApi } from './types'
  * Functions invoked from content scripts that will be executed in the background service worker.
  */
 export const background: BackgroundApi = {
-    annotationsChanges: proxyBackgroundMethodReturningObservable('annotationsChanges'),
+    itemsChanges: proxyBackgroundMethodReturningObservable('itemsChanges'),
 }

client/browser/src/browser-extension/web-extension-api/types.ts

@@ -21,7 +21,7 @@ export interface ManagedStorageItems {}
 /**
  * Functions in the background page that can be invoked from content scripts.
  */
-export interface BackgroundApi extends Pick<Client<Range>, 'annotationsChanges'> {}
+export interface BackgroundApi extends Pick<Client<Range>, 'itemsChanges'> {}
 
 /**
  * Shape of the handler object in the background worker.

client/browser/src/contentScript/contentScript.main.ts

@@ -1,7 +1,7 @@
 import '../shared/polyfills'
 // ^^ import polyfills first
-import { type Annotation } from '@openctx/client'
-import { type AnnotationsParams } from '@openctx/provider'
+import { type Item } from '@openctx/client'
+import { type ItemsParams } from '@openctx/provider'
 import deepEqual from 'deep-equal'
 import { combineLatest, distinctUntilChanged, mergeMap, throttleTime, type Observable } from 'rxjs'
 import { background } from '../browser-extension/web-extension-api/runtime'
@@ -15,23 +15,23 @@ import { locationChanges } from './locationChanges'
  * A function called to inject OpenCtx features on a page. They should just return an empty
  * Observable if they are not intended for the current page.
  */
-type Injector = (location: URL, annotationsChanges_: typeof annotationsChanges) => Observable<void>
+type Injector = (location: URL, itemsChanges_: typeof itemsChanges) => Observable<void>
 
 const INJECTORS: Injector[] = [injectOnGitHubCodeView, injectOnGitHubPullRequestFilesView]
 
 const subscription = locationChanges
-    .pipe(mergeMap(location => combineLatest(INJECTORS.map(injector => injector(location, annotationsChanges)))))
+    .pipe(mergeMap(location => combineLatest(INJECTORS.map(injector => injector(location, itemsChanges)))))
     .subscribe()
 window.addEventListener('unload', () => subscription.unsubscribe())
 
-function annotationsChanges(params: AnnotationsParams): Observable<Annotation[]> {
-    return background.annotationsChanges(params).pipe(
+function itemsChanges(params: ItemsParams): Observable<Item[]> {
+    return background.itemsChanges(params).pipe(
         distinctUntilChanged((a, b) => deepEqual(a, b)),
         throttleTime(200, undefined, { leading: true, trailing: true }),
-        debugTap(annotations => {
-            console.groupCollapsed('annotationsChanges')
-            console.count('annotationsChanges count')
-            console.log(annotations)
+        debugTap(items => {
+            console.groupCollapsed('itemsChanges')
+            console.count('itemsChanges count')
+            console.log(items)
             console.groupEnd()
         })
     )

client/browser/src/contentScript/github/codeView.ts

@@ -1,10 +1,10 @@
-import { type Annotation, type AnnotationsParams } from '@openctx/client'
+import { type Item, type ItemsParams } from '@openctx/client'
 import { createChipList } from '@openctx/ui-standalone'
 import { combineLatest, debounceTime, EMPTY, map, mergeMap, Observable, startWith, tap } from 'rxjs'
 import { toLineRangeStrings } from '../../shared/util/toLineRangeStrings'
 import { DEBUG, debugTap } from '../debug'
 import { withDOMElement } from '../detectElements'
-import { annotationsByLine, LINE_CHIPS_CLASSNAME, styledChipListParams } from '../octxUtil'
+import { itemsByLine, LINE_CHIPS_CLASSNAME, styledChipListParams } from '../octxUtil'
 
 /**
  * Inject OpenCtx features into the GitHub code view.
@@ -16,7 +16,7 @@ import { annotationsByLine, LINE_CHIPS_CLASSNAME, styledChipListParams } from '.
  */
 export function injectOnGitHubCodeView(
     location: URL,
-    annotationsChanges: (params: AnnotationsParams) => Observable<Annotation[]>
+    itemsChanges: (params: ItemsParams) => Observable<Item[]>
 ): Observable<void> {
     // All GitHub code view URLs contain `/blob/` in the path. (But not all URLs with `/blob/` are code
     // views, so we still need to check for the presence of DOM elements below. For example, there
@@ -48,7 +48,7 @@ export function injectOnGitHubCodeView(
             const fileUri = `github://github.com/${githubInitialPath}`
 
             return combineLatest([
-                annotationsChanges({ content, file: fileUri }),
+                itemsChanges({ content, file: fileUri }),
                 significantCodeViewChanges.pipe(
                     debounceTime(200),
                     startWith(undefined),
@@ -60,12 +60,12 @@ export function injectOnGitHubCodeView(
                     })
                 ),
             ]).pipe(
-                tap(([annotations]) => {
+                tap(([items]) => {
                     if (DEBUG) {
                         console.count('redraw')
                         console.time('redraw')
                     }
-                    redraw(annotations)
+                    redraw(items)
                     if (DEBUG) {
                         console.timeEnd('redraw')
                     }
@@ -76,18 +76,18 @@ export function injectOnGitHubCodeView(
     )
 }
 
-function redraw(annotations: Annotation[]): void {
+function redraw(items: Item[]): void {
     // TODO(sqs): optimize this by only redrawing changed chips
 
     const oldChips = document.querySelectorAll(`.${LINE_CHIPS_CLASSNAME}`)
     for (const oldChip of Array.from(oldChips)) {
         oldChip.remove()
     }
 
-    const byLine = annotationsByLine(annotations)
+    const byLine = itemsByLine(items)
 
     // TODO(sqs): switch instead to looping over byLine so we only do work on lines that have
-    // annotations on them.
+    // items on them.
     const codeRowEls = document.querySelectorAll<HTMLDivElement>('.react-code-line-contents')
     for (const el of Array.from(codeRowEls)) {
         const fileLineEl = el.querySelector<HTMLDivElement>('& > div > .react-file-line')
@@ -100,18 +100,18 @@ function redraw(annotations: Annotation[]): void {
         }
         const line = parseInt(lineNumberStr, 10) - 1
 
-        const lineAnns = byLine.find(a => a.line === line)?.annotations
-        if (lineAnns !== undefined) {
-            addChipsToCodeRow(line, lineAnns)
+        const lineItems = byLine.find(i => i.line === line)?.items
+        if (lineItems !== undefined) {
+            addChipsToCodeRow(line, lineItems)
         }
     }
 
-    function addChipsToCodeRow(line: number, annotations: Annotation[]): void {
+    function addChipsToCodeRow(line: number, items: Item[]): void {
         const lineEl = document.querySelector(`.react-file-line[data-line-number="${line + 1}"]`)
         if (lineEl) {
             const chipList = createChipList(
                 styledChipListParams({
-                    annotations,
+                    items,
                 })
             )
             lineEl.append(chipList)

client/browser/src/contentScript/github/pullRequestFilesView.ts

@@ -1,9 +1,9 @@
-import { type Annotation, type AnnotationsParams } from '@openctx/client'
+import { type Item, type ItemsParams } from '@openctx/client'
 import { createChipList } from '@openctx/ui-standalone'
 import { combineLatest, EMPTY, filter, fromEvent, map, mergeMap, startWith, tap, type Observable } from 'rxjs'
 import { DEBUG, debugTap } from '../debug'
 import { withDOMElements } from '../detectElements'
-import { annotationsByLine, LINE_CHIPS_CLASSNAME, styledChipListParams } from '../octxUtil'
+import { itemsByLine, LINE_CHIPS_CLASSNAME, styledChipListParams } from '../octxUtil'
 
 /**
  * Inject OpenCtx features into the GitHub pull request files view.
@@ -16,7 +16,7 @@ import { annotationsByLine, LINE_CHIPS_CLASSNAME, styledChipListParams } from '.
  */
 export function injectOnGitHubPullRequestFilesView(
     location: URL,
-    annotationsChanges: (params: AnnotationsParams) => Observable<Annotation[]>
+    itemsChanges: (params: ItemsParams) => Observable<Item[]>
 ): Observable<void> {
     // All GitHub PR file view URLs contain `/pull/` and `/files` in the path.
     if (!location.pathname.includes('/pull/') && !location.pathname.endsWith('/files')) {
@@ -38,10 +38,10 @@ export function injectOnGitHubPullRequestFilesView(
                 diffData.files
                     .flatMap(file => [file.oldFile, file.newFile])
                     .map(file =>
-                        annotationsChanges({ content: file.content, file: `github://${file.path}` }).pipe(
-                            tap(annotations => {
+                        itemsChanges({ content: file.content, file: `github://${file.path}` }).pipe(
+                            tap(items => {
                                 try {
-                                    redraw(file, annotations)
+                                    redraw(file, items)
                                 } catch (error) {
                                     console.error(error)
                                 }
@@ -66,12 +66,12 @@ function getChipListElementsAtEndOfLine(lineEl: HTMLElement): HTMLElement[] {
     )
 }
 
-function redraw(file: DiffViewFileVersionData, annotations: Annotation[]): void {
+function redraw(file: DiffViewFileVersionData, items: Item[]): void {
     // TODO(sqs): use line numbers as though they were in the original file, not just the displayed
     // excerpt from the diff.
 
     const lineEls = file.tableEl.querySelectorAll<HTMLElement>(file.codeSelector)
-    for (const { line, annotations: lineAnnotations } of annotationsByLine(annotations)) {
+    for (const { line, items: lineItems } of itemsByLine(items)) {
         const lineEl = lineEls[line]
         if (!lineEl) {
             console.error(`could not find lineEl for line ${line} (lineEls.length == ${lineEls.length})`)
@@ -84,7 +84,7 @@ function redraw(file: DiffViewFileVersionData, annotations: Annotation[]): void
 
         const chipList = createChipList(
             styledChipListParams({
-                annotations: lineAnnotations,
+                items: lineItems,
             })
         )
         lineEl.append(chipList)
@@ -178,7 +178,7 @@ function codeSelector(tableEl: HTMLTableElement, version: 'old' | 'new'): string
             : 'td[data-split-side="right"] .blob-code-inner, td[data-split-side="right"].blob-code-inner'
     }
 
-    // Omit .blob-expanded from the new version of the code to avoid double annotations.
+    // Omit .blob-expanded from the new version of the code to avoid double items.
     return version === 'old'
         ? ':where(.blob-code-context, .blob-code-deletion, .blob-expanded) .blob-code-inner'
         : ':where(.blob-code-context, .blob-code-addition) .blob-code-inner'

client/browser/src/contentScript/octxUtil.ts

@@ -1,16 +1,16 @@
-import { type Annotation } from '@openctx/client'
+import { type Item } from '@openctx/client'
 import { type createChipList } from '@openctx/ui-standalone'
 
-export function annotationsByLine(annotations: Annotation[]): { line: number; annotations: Annotation[] }[] {
-    const byLine: { line: number; annotations: Annotation[] }[] = []
-    for (const ann of annotations) {
+export function itemsByLine(items: Item[]): { line: number; items: Item[] }[] {
+    const byLine: { line: number; items: Item[] }[] = []
+    for (const item of items) {
         let cur = byLine.at(-1)
-        const startLine = ann.range?.start.line ?? 0
+        const startLine = item.range?.start.line ?? 0
         if (!cur || cur.line !== startLine) {
-            cur = { line: startLine, annotations: [] }
+            cur = { line: startLine, items: [] }
             byLine.push(cur)
         }
-        cur.annotations.push(ann)
+        cur.items.push(item)
     }
     return byLine
 }

client/codemirror/README.md

@@ -1,6 +1,6 @@
 # OpenCtx extension for CodeMirror
 
-The [`@openctx/codemirror-extension`](https://www.npmjs.com/package/@openctx/codemirror-extension) npm package implements a [CodeMirror](https://codemirror.net/) extension that shows [OpenCtx](https://openctx.org) annotations in the editor.
+The [`@openctx/codemirror-extension`](https://www.npmjs.com/package/@openctx/codemirror-extension) npm package implements a [CodeMirror](https://codemirror.net/) extension that shows [OpenCtx](https://openctx.org) items in the editor.
 
 Check out the [OpenCtx playground](https://openctx.org/playground) for a live example of this extension.
 
@@ -12,7 +12,7 @@ Install it:
 npm install @openctx/codemirror-extension @openctx/client
 ```
 
-Set up an OpenCtx client and fetch annotations:
+Set up an OpenCtx client and fetch items:
 
 ```typescript
 import { createClient } from '@openctx/client'
@@ -30,8 +30,8 @@ const client = createClient({
   logger: console.error,
 })
 
-// Fetch annotations for the file.
-const annotations = await client.annotations({ file: 'file:///foo.js', content: 'my file\nhello\nworld' })
+// Fetch items for the file.
+const items = await client.items({ file: 'file:///foo.js', content: 'my file\nhello\nworld' })
 ```
 
 Then register the extension with CodeMirror.
@@ -47,7 +47,7 @@ function MyComponent() {
   // A helpful React hook if using React.
   const octxExtension = useOpenCtxExtension({
     visibility: true,
-    annotations,
+    items,
   })
 
   // Pass `octxExtension` to CodeMirror as an extension.
@@ -64,14 +64,14 @@ import { openCtxData, showOpenCtxDecorations } from '@openctx/codemirror-extensi
 import { ChipList, IndentationWrapper } from '@openctx/ui-react'
 
 const octxExtension: Extension = [
-  openCtxData(annotations),
+  openCtxData(items),
   showOpenCtxDecorations({
     visibility: true,
-    createDecoration(container, { indent, annotations }) {
+    createDecoration(container, { indent, items }) {
       const root = createRoot(container)
       root.render(
         <IndentationWrapper indent={indent}>
-          <ChipList annotations={annotations} chipClassName="octx-chip" popoverClassName="octx-chip-popover" />
+          <ChipList items={items} chipClassName="octx-chip" popoverClassName="octx-chip-popover" />
         </IndentationWrapper>
       )
       return {

client/codemirror/demo/README.md

@@ -1,6 +1,6 @@
 # Demo: OpenCtx extension for CodeMirror
 
-This is a simple demo that uses the [`@openctx/codemirror-extension`](https://www.npmjs.com/package/@openctx/codemirror-extension) npm package to show OpenCtx annotations in a CodeMirror editor.
+This is a simple demo that uses the [`@openctx/codemirror-extension`](https://www.npmjs.com/package/@openctx/codemirror-extension) npm package to show OpenCtx items in a CodeMirror editor.
 
 ## Usage
 

client/codemirror/demo/demo.ts

@@ -26,25 +26,25 @@ const client = createClient({
 
 const CONTENT = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12].map(n => `console.log("Hello, world #${n}");`).join('\n')
 
-const annotations = await client.annotations({ file: 'file:///foo.js', content: CONTENT })
+const items = await client.items({ file: 'file:///foo.js', content: CONTENT })
 
 const octxExtension: Extension = [
-    openCtxData(annotations),
+    openCtxData(items),
     showOpenCtxDecorations({
         visibility: true,
-        createDecoration(container, { annotations }) {
+        createDecoration(container, { items }) {
             const div = document.createElement('div')
             div.style.display = 'flex'
             div.style.gap = '1rem'
 
-            for (const ann of annotations) {
-                const el = document.createElement(ann.url ? 'a' : 'span')
-                el.innerText = ann.title
-                if (ann.ui?.detail) {
-                    el.title = ann.ui?.detail
+            for (const item of items) {
+                const el = document.createElement(item.url ? 'a' : 'span')
+                el.innerText = item.title
+                if (item.ui?.detail) {
+                    el.title = item.ui?.detail
                 }
-                if (ann.url && el instanceof HTMLAnchorElement) {
-                    el.href = ann.url
+                if (item.url && el instanceof HTMLAnchorElement) {
+                    el.href = item.url
                     el.style.textDecoration = 'none'
                     el.style.fontFamily = 'system-ui, sans-serif'
                     el.style.backgroundColor = '#ffffff22'