@scalar/api-reference 0.2.0 → 0.3.0

package/src/components/Sidebar.vue

@@ -0,0 +1,289 @@
+<script setup lang="ts">
+import { generateRequest, useApiClientRequestStore } from '@scalar/api-client'
+import { useApiClientStore, useOperation } from '@scalar/api-client'
+import { useKeyboardEvent } from '@scalar/use-keyboard-event'
+import { useMediaQuery } from '@vueuse/core'
+
+import { useTemplateStore } from '../stores/template'
+import type { Operation, Spec } from '../types'
+import FindAnythingButton from './FindAnythingButton.vue'
+import SidebarElement from './SidebarElement.vue'
+import SidebarGroup from './SidebarGroup.vue'
+
+const props = defineProps<{ spec: Spec }>()
+
+const { state, setActiveSidebar, toggleApiClient } = useApiClientStore()
+
+const { setActiveRequest } = useApiClientRequestStore()
+
+function showItemInClient(operation: Operation) {
+  const { parameterMap } = useOperation({ operation })
+  const item = generateRequest(
+    operation,
+    parameterMap.value,
+    props.spec.servers[0],
+  )
+  setActiveRequest(item)
+  toggleApiClient(item, true)
+}
+
+const scrollToEndpoint = (item: Operation) => {
+  setActiveSidebar(item.operationId)
+  if (state.showApiClient) {
+    showItemInClient(item)
+  }
+  document.getElementById(`endpoint/${item.operationId}`)?.scrollIntoView()
+}
+
+const isMobile = useMediaQuery('(max-width: 1000px)')
+
+const {
+  state: templateState,
+  setItem: setTemplateItem,
+  toggleCollapsedSidebarItem,
+  setCollapsedSidebarItem,
+} = useTemplateStore()
+
+useKeyboardEvent({
+  keyList: ['k'],
+  withCtrlCmd: true,
+  handler: () => setTemplateItem('showSearch', !templateState.showSearch),
+})
+</script>
+<template>
+  <div class="sidebar">
+    <FindAnythingButton
+      v-if="!isMobile"
+      @click="setTemplateItem('showSearch', true)" />
+    <div class="pages custom-scroll custom-scroll-self-contain-overflow">
+      <SidebarGroup :level="0">
+        <template v-for="tag in spec.tags">
+          <SidebarElement
+            v-if="tag.operations?.length > 0"
+            :key="tag.name"
+            :hasChildren="true"
+            :isActive="false"
+            :item="{
+              uid: '',
+              title: tag.name.toUpperCase(),
+              type: 'Folder',
+            }"
+            :open="templateState.collapsedSidebarItems[tag.name]"
+            @select="() => toggleCollapsedSidebarItem(tag.name)"
+            @toggleOpen="toggleCollapsedSidebarItem(tag.name)">
+            <SidebarGroup :level="0">
+              <SidebarElement
+                v-for="operation in tag.operations"
+                :key="operation.operationId"
+                :isActive="state.activeSidebar === operation.operationId"
+                :item="{
+                  uid: '',
+                  title: operation.name || operation.path,
+                  type: 'Page',
+                }"
+                @select="
+                  () => {
+                    setCollapsedSidebarItem(tag.name, true)
+                    scrollToEndpoint(operation)
+                  }
+                " />
+            </SidebarGroup>
+          </SidebarElement>
+        </template>
+      </SidebarGroup>
+    </div>
+  </div>
+</template>
+
+<style>
+.sidebar {
+  --theme-sidebar-indent-base: 6px;
+  /* prettier-ignore */
+  background: var(--sidebar-background-1, var(--theme-background-1));
+}
+
+/* ----------------------------------------------------- */
+/* Main sidebar styles */
+
+.sidebar {
+  flex: 1;
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  /* prettier-ignore */
+  background: var(--sidebar-background-1, var(--theme-background-1));
+  --sidebar-level: 0;
+}
+
+.pages {
+  padding-top: 9px;
+  padding-bottom: 9px;
+}
+
+.sidebar-group {
+  list-style: none;
+  width: 100%;
+}
+
+.sidebar-heading {
+  display: flex;
+  gap: 6px;
+
+  /* prettier-ignore */
+  color: var(--sidebar-color-2, var(--theme-color-2));
+  font-size: var(--theme-mini);
+  font-weight: var(--theme-semibold);
+  word-break: break-word;
+  line-height: 1.385;
+  display: flex;
+  align-items: center;
+  max-width: 100%;
+  position: relative;
+  cursor: pointer;
+  /* prettier-ignore */
+  border-radius: 0 var(--theme-radius-lg) var(--theme-radius-lg) 0;
+  flex: 1;
+  padding-right: 12px;
+  user-select: none;
+}
+
+/* Folder/page collapse icon */
+.toggle-nested-icon {
+  border: none;
+  position: absolute !important;
+  left: 2px;
+  top: 50%;
+  transform: translateY(-50%);
+  color: currentColor;
+}
+
+.toggle-nested-icon:hover,
+.toggle-nested-icon:focus-visible {
+  color: currentColor;
+  filter: drop-shadow(0 0.125px 0 currentColor)
+    drop-shadow(0 -0.125px 0 currentColor);
+}
+
+/* We indent each level of nesting further */
+.sidebar-indent-nested .sidebar-heading {
+  /* prettier-ignore */
+  padding-left: calc((var(--sidebar-level) * var(--theme-sidebar-indent-base)) + 24px) !important;
+}
+
+/* Collapse/expand icons must also be offset */
+.sidebar-indent-nested .sidebar-heading .toggle-nested-icon {
+  /* prettier-ignore */
+  left: calc((var(--sidebar-level) * var(--theme-sidebar-indent-base)) + 2px) !important;
+}
+
+.sidebar-heading-link {
+  padding-right: 12px;
+  padding: 6px 0;
+  display: flex;
+  align-items: center;
+}
+
+/* Sidebar link icon */
+.link-icon {
+  position: relative;
+  left: 4px;
+}
+
+.sidebar-icon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  margin-right: 6px;
+
+  width: 13px;
+  height: 13px;
+}
+
+.sidebar-icon > svg {
+  width: 13px;
+  height: 13px;
+}
+
+.sidebar-heading:hover {
+  /* prettier-ignore */
+  color: var(--sidebar-color-1, var(--theme-color-1));
+  /* prettier-ignore */
+  background: var(--sidebar-item-hover-background, var(--theme-background-2));
+}
+
+.active_page.sidebar-heading:hover,
+.active_page.sidebar-heading,
+.marc_active .sidebar-heading {
+  /* prettier-ignore */
+  background: var(--sidebar-item-active-background, var(--theme-background-accent)) !important;
+  /* prettier-ignore */
+  color: var(--theme-color-accent, var(--theme-background-accent)) !important;
+}
+.sidebar-group-item {
+  position: relative;
+}
+
+/* Change font colors and weights for nested items */
+.sidebar-indent-nested .sidebar-heading {
+  /* prettier-ignore */
+  color: var(--sidebar-color-1, var(--theme-color-1));
+}
+.sidebar-indent-nested .sidebar-indent-nested .sidebar-heading {
+  /* prettier-ignore */
+  color: var(--sidebar-color-2, var(--theme-color-2));
+}
+.sidebar-indent-nested > div:has(.active_page) .sidebar-heading {
+  font-weight: var(--theme-bold);
+}
+
+.sidebar-mobile-header {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  height: 100%;
+  width: 100%;
+  padding: 0 6px;
+}
+
+.sidebar-mobile-breadcrumbs {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  font-size: var(--theme-small);
+  font-weight: var(--theme-semibold);
+}
+
+.sidebar-mobile-actions {
+  display: flex;
+  flex-direction: row;
+  gap: 4px;
+  height: 24px;
+  align-items: center;
+  padding: 0 4px;
+}
+
+.sidebar-mobile-actions .sidebar-mobile-darkmode-toggle {
+  height: 16px;
+  width: 16px;
+}
+
+@media (max-width: 1000px) {
+  .sidebar {
+    min-height: 0;
+  }
+
+  .pages {
+    padding-top: 12px;
+  }
+}
+
+@media (max-width: 500px) {
+  .header-item-link.header-item-active,
+  .sidebar-section,
+  .sidebar-heading {
+    font-size: var(--theme-micro);
+  }
+}
+</style>

package/src/components/SidebarElement.vue

@@ -0,0 +1,133 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+
+import FlowIconButton from '../components/FlowIconButton.vue'
+import { FlowIcon, Icon } from './Icon'
+
+const props = defineProps<{
+  item: {
+    uid: string
+    title: string
+    type: 'Page' | 'Folder' | 'Link'
+    link?: string
+    icon?: {
+      src: string
+    }
+  }
+  isActive?: boolean
+  hasChildren?: boolean
+  open?: boolean
+}>()
+
+const emit = defineEmits<{
+  (e: 'select'): void
+  (e: 'toggleOpen'): void
+}>()
+
+enum ElementType {
+  Page = 'Page',
+  Folder = 'Folder',
+  Link = 'Link',
+}
+
+const linkProps = computed(() => {
+  const item = props.item
+  if (item.type === ElementType.Link) {
+    return {
+      href: item.link,
+      rel: 'noopener noreferrer',
+      target: '_blank',
+    }
+  }
+
+  return {}
+})
+
+function handleClick() {
+  if (props.item.type === ElementType.Link) return
+
+  if (props.item.type === ElementType.Folder) {
+    emit('toggleOpen')
+    return
+  }
+
+  emit('select')
+}
+
+function handleToggleOpen() {
+  // Allow bubbled event to trigger folder open
+  if (props.item.type === ElementType.Folder) return
+
+  emit('toggleOpen')
+}
+</script>
+<template>
+  <li class="sidebar-group-item">
+    <div
+      class="sidebar-heading"
+      :class="{ active_page: isActive }"
+      @click="handleClick">
+      <!-- If children are detected then show the nesting icon -->
+      <FlowIconButton
+        v-if="hasChildren || item.type === ElementType.Folder"
+        class="toggle-nested-icon"
+        :icon="open ? 'ChevronDown' : 'ChevronRight'"
+        label="Toggle group"
+        variant="text"
+        width="20px"
+        @click="handleToggleOpen" />
+      <a
+        class="flex-1 sidebar-heading-link"
+        v-bind="linkProps">
+        <Icon
+          v-if="item?.icon?.src"
+          class="sidebar-icon"
+          :src="item.icon.src" />
+        <p>{{ item.title }}</p>
+      </a>
+      <FlowIcon
+        v-if="item?.type === ElementType.Link"
+        class="link-icon"
+        icon="ExternalLink"
+        width="16px" />
+    </div>
+    <slot v-if="open" />
+    <div
+      v-if="$slots['action-menu']"
+      class="action-menu">
+      <slot name="action-menu"></slot>
+    </div>
+  </li>
+</template>
+<style scoped>
+.action-menu {
+  position: absolute;
+  top: 5px;
+  right: 5px;
+  display: flex;
+  gap: 6px;
+}
+/**
+* Some awkwardness to make the dropdown buttons hidden when not hovered
+* but still show when the panel is open and focused
+*/
+.action-menu :deep(.button-wrapper button) {
+  /* Hide the icons by default */
+  opacity: 0;
+  width: 20px;
+  height: 20px;
+  padding: 4px;
+}
+.action-menu:hover :deep(.button-wrapper button),
+.action-menu :deep(.button-wrapper button:hover),
+.sidebar-heading:hover ~ .action-menu :deep(.button-wrapper button),
+.action-menu :deep(.button-wrapper button[aria-expanded='true']) {
+  opacity: 1;
+}
+.sidebar-heading:has(~ .action-menu:hover) {
+  /* prettier-ignore */
+  color: var(--sidebar-color-1, var(--theme-color-1));
+  /* prettier-ignore */
+  background: var(--sidebar-item-hover-background, var(--theme-background-2));
+}
+</style>

package/src/components/SidebarGroup.vue

@@ -0,0 +1,12 @@
+<script setup lang="ts">
+defineProps<{
+  level: number
+}>()
+</script>
+<template>
+  <ul
+    class="sidebar-group sidebar-indent-nested"
+    :style="{ '--sidebar-level': level }">
+    <slot />
+  </ul>
+</template>

package/src/components/SimpleTable/SimpleCell.vue

@@ -0,0 +1,46 @@
+<script lang="ts" setup>
+import HelpfulLink from '../HelpfulLink.vue'
+
+withDefaults(
+  defineProps<{ wrap?: boolean; strong?: boolean; href?: string | null }>(),
+  {
+    wrap: true,
+    strong: false,
+    href: null,
+  },
+)
+</script>
+<template>
+  <td
+    class="simple-cell"
+    :class="{ wrap: wrap, strong: strong }">
+    <template v-if="href">
+      <HelpfulLink :href="href">
+        <slot />
+      </HelpfulLink>
+    </template>
+    <template v-else>
+      <slot />
+    </template>
+  </td>
+</template>
+<style scoped>
+.simple-cell {
+  position: relative;
+  padding: 0.25em 0.5em;
+  color: var(--theme-color-1);
+  white-space: nowrap;
+}
+
+.simple-cell:last-of-type {
+  border-right: none;
+}
+
+.simple-cell.wrap {
+  white-space: normal;
+}
+
+.simple-cell.strong {
+  font-weight: var(--theme-semibold);
+}
+</style>

package/src/components/SimpleTable/SimpleHeader.vue

@@ -0,0 +1,17 @@
+<script lang="ts" setup>
+import SimpleCell from './SimpleCell.vue'
+</script>
+<template>
+  <SimpleCell
+    as="th"
+    class="simple-header">
+    <slot />
+  </SimpleCell>
+</template>
+<style scoped>
+.simple-header {
+  color: var(--theme-color-disabled);
+  font-weight: var(--theme-bold);
+  text-transform: uppercase;
+}
+</style>

package/src/components/SimpleTable/SimpleRow.vue

@@ -0,0 +1,5 @@
+<template>
+  <tr class="simple-row">
+    <slot />
+  </tr>
+</template>

package/src/components/SimpleTable/SimpleTable.vue

@@ -0,0 +1,13 @@
+<template>
+  <table class="simple-table">
+    <slot />
+  </table>
+</template>
+
+<style scoped>
+.simple-table {
+  display: table;
+  width: 100%;
+  font-size: var(--theme-micro);
+}
+</style>

package/src/components/SimpleTable/index.ts

@@ -0,0 +1,4 @@
+export { default as SimpleCell } from './SimpleCell.vue'
+export { default as SimpleHeader } from './SimpleHeader.vue'
+export { default as SimpleRow } from './SimpleRow.vue'
+export { default as SimpleTable } from './SimpleTable.vue'

package/src/declarations/typographic-base.d.ts

@@ -0,0 +1 @@
+declare module 'typographic-base'

package/src/helpers/generateAxiosCodeFromRequest.ts

@@ -0,0 +1,42 @@
+type HarRequestHeader = {
+  name: string
+  value: string
+}
+
+type HarRequest = {
+  url: string
+  method: string
+  headers?: HarRequestHeader[]
+}
+
+export const generateAxiosCodeFromRequest = (request: HarRequest) => {
+  const lines: string[] = []
+
+  lines.push(`import axios from 'axios'`)
+  lines.push(``)
+  lines.push(`axios({`)
+
+  const url = request.url
+  lines.push(`  url: '${url}',`)
+
+  const method = request.method.toLowerCase()
+  lines.push(`  method: '${method}',`)
+
+  if (request.headers) {
+    const headers = request.headers
+      .map((header) => {
+        return `    '${header.name}': '${header.value}',`
+      })
+      .join('\n')
+
+    lines.push(`  headers: [`)
+    lines.push(`${headers}`)
+    lines.push(`  ],`)
+  }
+
+  lines.push(`}).then(response => {`)
+  lines.push(`  console.log(response)`)
+  lines.push(`})`)
+
+  return lines.join('\n')
+}

package/src/helpers/generateLaravelCodeFromRequest.ts

@@ -0,0 +1,20 @@
+type HarRequest = {
+  url: string
+  method: string
+}
+
+export const generateLaravelCodeFromRequest = (request: HarRequest) => {
+  const lines: string[] = []
+
+  lines.push(`<?php`)
+  lines.push(``)
+  lines.push(`use Illuminate\\Support\\Facades\\Http;`)
+  lines.push(``)
+
+  const method = request.method.toLowerCase()
+  const url = request.url
+
+  lines.push(`$response = Http::${method}('${url}');`)
+
+  return lines.join('\n')
+}

package/src/helpers/index.ts

@@ -0,0 +1,4 @@
+export { generateAxiosCodeFromRequest } from './generateAxiosCodeFromRequest'
+export { generateLaravelCodeFromRequest } from './generateLaravelCodeFromRequest'
+export { objectMerge } from './objectMerge'
+export { transformToJson } from './transformToJson'

package/src/helpers/objectMerge.ts

@@ -0,0 +1,19 @@
+// TODO: This is a copy of packages/core-interface/src/database/utility.ts
+/**
+ * Overwrite a target object a new replacement object handling removed keys
+ **/
+export function objectMerge<A extends object, B extends object>(
+  target: A,
+  replacement: B,
+) {
+  // Clear any keys that have been removed in the replacement
+  Object.keys(target).forEach((key) => {
+    if (!Object.hasOwn(replacement, key)) {
+      delete target[key as keyof A]
+    }
+  })
+
+  Object.assign(target, replacement)
+
+  return target as unknown as B
+}

package/src/helpers/specHelpers.ts

@@ -0,0 +1,62 @@
+import type { ContentSchema, Operation } from '../types'
+
+type PropertyObject = {
+  required?: string[]
+  properties: {
+    [key: string]: {
+      type: string
+      description?: string
+    }
+  }
+}
+
+function formatProperty(key: string, obj: PropertyObject): string {
+  let output = key
+  const isRequired = obj.required && obj.required.includes(key)
+  output += isRequired ? ' REQUIRED ' : ' optional '
+
+  // Check existence before accessing
+  if (obj.properties[key]) {
+    output += obj.properties[key].type
+    if (obj.properties[key].description) {
+      output += ' ' + obj.properties[key].description
+    }
+  }
+
+  return output
+}
+
+function recursiveLogger(obj: ContentSchema): string[] {
+  const results: string[] = ['Body']
+
+  const properties = obj?.schema?.properties
+  if (properties) {
+    Object.keys(properties).forEach((key) => {
+      results.push(formatProperty(key, obj.schema))
+
+      const property = properties[key]
+      const isNestedObject = property.type === 'object' && !!property.properties
+      if (isNestedObject && property.properties) {
+        Object.keys(property.properties).forEach((subKey) => {
+          results.push(`${subKey} ${property.properties?.[subKey]?.type}`)
+        })
+      }
+    })
+  }
+
+  return results
+}
+
+function extractRequestBody(operation: Operation): string[] | boolean {
+  try {
+    // Using optional chaining here as well
+    const body =
+      operation?.information?.requestBody?.content['application/json']
+    if (!body) throw new Error('Body not found')
+    return recursiveLogger(body)
+  } catch (error) {
+    return false
+  }
+}
+
+export { formatProperty, recursiveLogger, extractRequestBody }

package/src/helpers/transformToJson.test.ts

@@ -0,0 +1,7 @@
+import { describe, expect, it } from 'vitest'
+
+describe('example', () => {
+  it('executes tests', () => {
+    expect(true).toBe(true)
+  })
+})