chore: nits (#56)

The following changes were made to the repository to either improve or
simplify the project logics in-terms of naming, functionality etc...

- Removed `devJargonsAppAuth` from `octokit/app` and Moved OAuth App's
octokit export to `oauth` object, it just makes logical sense to use
`app.oauth.octokit` as jargons.dev OAuth App octokit and use
`app.octokit` as jargons.dev GitHub App
- Removed addressed todo from `submitWord` function and renamed label to
`via jargons-editor` from `via word-editor` in `submit-word` script
- Documented, fixed typo/naming and add some todo to `recent-searches`
island and `search` store
- add todo `@todo implement logic to allow holding maximum of 5 words by
removing older words when new a one gets added`
- Renamed localstorage object name to `jargons.dev:recent_searches` from
`devJargonsRecentSearches`
- Documented the `word-editor` island and added disallowed cursor on its
`Preview` component dummy navbar
- Removed `label:":computer: via word-editor"` from the
`doContributionStats` action to effectively removing narrowed Pull
request search to compute word contribution which was biased towards
contribution done via the jargons editor
- Documented `useLockBody` and `useIsMacOS` hooks
- Modified the word contribution PR templates, making appropriate use of
semantics for formatting headings
- Added `@todo deprecate the `options` params` to selected
`word-editor.js` function to remind of possibly removing the `options`
param which was initially added to set environment where the function is
being executed from - this was initially added
- Removed redundant `$userData.set()` operation performed on the add new
word page server-side (doesn't even work in the first place), and
implemented `javascript: history.back()` as return navigation `location`
to allow quick navigation back - a trick to avoid re-fetching the
contribution stats for the jargons editor all over again
- Renamed `otherWordData` to `wordMetaData` in word edit page and
implemented a custom return navigation label and location to return to
the word currently being edited canceling the operation onclick of
course
- Integrated Navbar to the jargons editor
- Added `@todo Nice to have: endpoint queries the GitHub to fetch words
directly from jargons.dev repo using the requester's accessToken` to
jargons.dev `browse` api - meant to suggest an implementation where the
api is requesting for all words or r=single word directly from
jargons.dev github repo using the user's token; this is similar to how
the `dictionary` endpoint `POST` handler operates.

📖

Author: babblebey

.env.example

@@ -8,5 +8,5 @@ GITHUB_OAUTH_APP_CLIENT_SECRET=""
 
 CRYPTO_SECRET_KEY="secret"
 
-PUBLIC_PROJECT_REPO="babblebey/jargons.dev"
+PUBLIC_PROJECT_REPO="user/jargons.dev-test"
 PUBLIC_PROJECT_REPO_BRANCH_REF="refs/heads/main"

astro.config.mjs

@@ -1,8 +1,7 @@
 import { defineConfig } from "astro/config";
-import tailwind from "@astrojs/tailwind";
 import mdx from "@astrojs/mdx";
 import react from "@astrojs/react";
-
+import tailwind from "@astrojs/tailwind";
 import vercel from "@astrojs/vercel/serverless";
 
 // https://astro.build/config

src/components/islands/recent-searches.jsx

@@ -3,14 +3,16 @@ import { useStore } from "@nanostores/react";
 import { $recentSearches } from "../../lib/stores/search.js";
 
 /**
+ * Recent Searches Component - An Island that displays a user's last 5 searches
+ * 
  * @todo implement a default list instead of `null` when no `$recentSearch` is found 
  * @todo implement loading component to avoid flickering UI
  */
-export default function RecenctSearches() {
+export default function RecentSearches() {
   const recentSearches = useStore($recentSearches);
 
   useEffect(() => {
-    $recentSearches.set({...JSON.parse(localStorage.getItem("devJargonsRecentSearches"))})
+    $recentSearches.set({...JSON.parse(localStorage.getItem("jargons.dev:recent_searches"))})
   }, []);
 
   return Object.values(recentSearches).length ? (

src/components/islands/word-editor.jsx

@@ -6,6 +6,9 @@ import { capitalizeText } from "../../lib/utils/index.js";
 import useWordEditor from "../../lib/hooks/use-word-editor.js";
 import { $isWordSubmitLoading } from "../../lib/stores/dictionary.js";
 
+/**
+ * Main Word Editor Component - Island
+ */
 export default function WordEditor({ title = "", content = "", metadata = {}, action }) {
   return (
     <div className="w-full flex border rounded-lg">
@@ -21,6 +24,9 @@ export default function WordEditor({ title = "", content = "", metadata = {}, ac
   );
 }
 
+/**
+ * Detached Editor Submit Button Component - Island
+ */
 export function SubmitButton({ children = "Submit" }) {
   const isSubmitLoading = useStore($isWordSubmitLoading);
 
@@ -39,6 +45,9 @@ export function SubmitButton({ children = "Submit" }) {
   );
 }
 
+/**
+ * Editor Markdown Input Component
+ */
 function Editor({ eTitle, eContent, eMetadata, className, action, ...props }) {
   const router = useRouter();
   const { title, setTitle, content, setContent } = useWordEditor();
@@ -112,6 +121,9 @@ function Editor({ eTitle, eContent, eMetadata, className, action, ...props }) {
   );
 }
 
+/**
+ * Editor Markdown Preview Component
+ */
 function Preview({ className, ...props }) {
   const { title, content } = useWordEditor();
 
@@ -120,7 +132,7 @@ function Preview({ className, ...props }) {
       className={`${className} select-none`}
       {...props}  
     >
-      <div className="h-1 grow overflow-auto space-y-6 rounded-lg border p-5 shadow-lg scrollbar">
+      <div className="h-1 grow overflow-auto rounded-lg border p-5 shadow-lg scrollbar">
         <DummyPreviewNavbar />
 
         <div className="max-w-4xl space-y-8 mx-auto">
@@ -143,10 +155,13 @@ function Preview({ className, ...props }) {
   );
 }
 
+/**
+ * Editor Preview Section Dummy Navbar
+ */
 const DummyPreviewNavbar = () => (
-  <div className="@container">
+  <div className="@container mb-6">
     <nav className="flex items-center justify-between pb-4">
-      <span className="flex items-center underline">
+      <span className="flex items-center underline cursor-not-allowed">
         <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" strokeWidth="1.5" stroke="currentColor" className="w-4 h-4">
           <path strokeLinecap="round" strokeLinejoin="round" d="M15.75 19.5 8.25 12l7.5-7.5" />
         </svg> 
@@ -155,7 +170,7 @@ const DummyPreviewNavbar = () => (
         </span>       
       </span>
 
-      <div>
+      <div className="cursor-not-allowed">
         <div className="relative w-56 text-sm hidden @md:flex items-center justify-between border pl-2.5 p-1 space-x-2 border-gray-400 rounded-lg">
           <div className="flex items-center text-gray-400 space-x-2">
             <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" strokeWidth="1.5" stroke="currentColor" className="w-5 h-5">

src/lib/actions/do-contribution-stats.js

@@ -16,8 +16,8 @@ export default async function doContributionStats(astroGlobal) {
   /**
    * @todo Implement narrowed search to project's main branch 
    */
-  const baseQuery = `repo:${repoFullname} is:pull-request type:pr author:@me label:":computer: via word-editor"`;
-  const baseStatsUrlQuery = `is:pr author:@me label:":computer: via word-editor"`;
+  const baseQuery = `repo:${repoFullname} is:pull-request type:pr author:@me`;
+  const baseStatsUrlQuery = `is:pr author:@me`;
 
   /**
    * @todo [thoughts]: would be nice to have all these requests in one, and use a filter to separate by labels

src/lib/hooks/use-is-mac-os.js

@@ -2,6 +2,10 @@ import { useEffect, useState } from "react";
 
 const MAC_OS_USER_AGENT_PART = /Mac|Macintosh|MacIntel|Mac OS X/;
 
+/**
+ * Custom hook used to check if current user's machine is macOS
+ * @returns {boolean}
+ */
 export default function useIsMacOS() {
   const [isMacOS, setIsMacOS] = useState(false);
 

src/lib/hooks/use-lock-body.js

@@ -1,5 +1,8 @@
 import { useLayoutEffect } from "react";
 
+/**
+ * Cutom hook to help remove navigation-ability from web page
+ */
 export default function useLockBody() {
   useLayoutEffect(() => {
     const originalStyle = window.getComputedStyle(document.body).overflow;

src/lib/octokit/app.js

@@ -9,26 +9,14 @@ const app = new App({
 const { data: { id } } = await app.octokit.request(`GET /repos/${import.meta.env.PUBLIC_PROJECT_REPO}/installation`);
 
 /**
- * DevJargons Helper App's Octokit instance
-*/
-const devJargonsOctokit = await app.getInstallationOctokit(id);
-
-/**
- * DevJargons Helper App's Auth Token 
+ * jargons.dev Helper GitHub App's Octokit instance
  */
-const devJargonsAppAuth = await (
-  async () => {
-    const { data: { token } } = await devJargonsOctokit.request(`POST /app/installations/${id}/access_tokens`);
-    return token;
-  }
-)();
+const appOctokit = await app.getInstallationOctokit(id);
 
 /**
- * OAuth App's Octokit instance
- * 
- * @todo consider removing this later, its looking redundant
+ * OAuth App's Octokit instance - useful for verifying user accessToken validity
  */
-const octokit = new Octokit({
+const oauthAppOctokit = new Octokit({
   authStrategy: createOAuthAppAuth,
   auth: {
     clientId: import.meta.env.GITHUB_OAUTH_APP_CLIENT_ID,
@@ -84,10 +72,9 @@ function getUserOctokit({ token, ...options }) {
 };
 
 export default { 
-  octokit,
-  devJargonsAppAuth,
-  devJargonsOctokit,
+  octokit: appOctokit,
   oauth: {
+    octokit: oauthAppOctokit,
     getWebFlowAuthorizationUrl, 
     exchangeWebFlowCode,
   },

src/lib/stores/search.js

@@ -14,6 +14,8 @@ export const $recentSearches = map({});
 /**
  * Add search term to recent search history
  * @param {SearchedItem} item 
+ * 
+ * @todo implement logic to allow holding maximum of 5 words by removing older words when new a one gets added
  */
 export function $addToRecentSearchesFn({ word, url }) {
   const lowercaseKey = word.toLowerCase();
@@ -31,5 +33,5 @@ export function $addToRecentSearchesFn({ word, url }) {
     return;
   }
 
-  localStorage.setItem("devJargonsRecentSearches", JSON.stringify($recentSearches.get()));
+  localStorage.setItem("jargons.dev:recent_searches", JSON.stringify($recentSearches.get()));
 }

src/lib/submit-word.js

@@ -12,7 +12,6 @@ import editWordPRTemp from "./templates/edit-word-pr.md.js";
  * @param {{ title: string, content: string }} word 
  * 
  * @todo implement (submit as) `draft` feature - [idea]
- * @todo implement `maintainer_can_modify` toggle - [idea]
  */
 export async function submitWord(devJargonsOctokit, userOctokit, action, projectRepoDetails, forkedRepoDetails, word) {
   const { repoFullname, repoMainBranchRef } = projectRepoDetails;
@@ -46,7 +45,7 @@ export async function submitWord(devJargonsOctokit, userOctokit, action, project
     issue_number: response.data.number,
     labels: [
       `:book: ${action} word`,
-      ":computer: via word-editor"
+      ":computer: via jargons-editor"
     ]
   });