starlight-package-managers 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-present, HiDeoo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PackageManagers.astro

@@ -0,0 +1,150 @@
+---
+import { Tabs, TabItem } from '@astrojs/starlight/components'
+import { Code } from 'astro/components'
+
+import { type CommandType, getCommand, type CommandOptions, getSupportedPkgManagers, type PackageManager } from './pkg'
+
+export type PackageManagersProps = Props
+
+interface Props extends CommandOptions {
+  pkg?: string | undefined
+  pkgManagers?: PackageManager[]
+  type?: CommandType
+}
+
+const { pkg, pkgManagers, type = 'add', ...options } = Astro.props
+const singlePkgManager = pkgManagers?.length === 1 ? pkgManagers[0] : undefined
+---
+
+{
+  singlePkgManager ? (
+    <Code code={getCommand(singlePkgManager, type, pkg, options)} lang="sh" theme="css-variables" />
+  ) : (
+    <starlight-package-managers>
+      <Tabs>
+        {getSupportedPkgManagers(type, pkgManagers).map((pkgManager) => (
+          <TabItem label={pkgManager}>
+            <Code code={getCommand(pkgManager, type, pkg, options)} lang="sh" theme="css-variables" />
+          </TabItem>
+        ))}
+      </Tabs>
+    </starlight-package-managers>
+  )
+}
+
+<style>
+  starlight-package-managers {
+    display: block;
+  }
+</style>
+
+<script>
+  customElements.define(
+    'starlight-package-managers',
+    class StarlightPackageManagers extends HTMLElement {
+      #observer: MutationObserver
+      #observerConfig: MutationObserverInit = { attributes: true, attributeFilter: ['aria-selected'] }
+
+      #tabs: NodeListOf<HTMLAnchorElement>
+
+      constructor() {
+        super()
+
+        this.#observer = new MutationObserver(this.#handleTabChange)
+        this.#tabs = this.querySelectorAll<HTMLAnchorElement>('starlight-tabs [role="tablist"] [role="tab"]')
+
+        this.observeTabs()
+      }
+
+      observeTabs = () => {
+        for (const tab of this.#tabs) {
+          this.#observer.observe(tab, this.#observerConfig)
+        }
+      }
+
+      disconnectTabs = () => {
+        this.#observer.disconnect()
+      }
+
+      #handleTabChange = (mutations: MutationRecord[]) => {
+        const pkgTabs = [...document.querySelectorAll<this>('starlight-package-managers')]
+
+        for (const pkgTab of pkgTabs) {
+          pkgTab.disconnectTabs()
+        }
+
+        let newFocusedTab: HTMLAnchorElement | null = null
+
+        for (const mutation of mutations) {
+          if (mutation.attributeName !== 'aria-selected' || !(mutation.target instanceof HTMLAnchorElement)) {
+            continue
+          }
+
+          if (mutation.target.getAttribute('aria-selected') !== 'true') {
+            continue
+          }
+
+          newFocusedTab = mutation.target
+
+          const newPkgManager = newFocusedTab.textContent?.trim() ?? ''
+          const otherTabs = pkgTabs.filter((tabs) => tabs !== this)
+
+          for (const otherTab of otherTabs) {
+            const starlightTabs = otherTab.querySelector('starlight-tabs')
+
+            if (!this.#isStarlightTabs(starlightTabs)) {
+              continue
+            }
+
+            // We cannot use the `switchTab()` method provided by Starlight as it focuses the new tab which will cause
+            // the page to scroll for every set of tabs.
+            this.#switchTabs(starlightTabs, newPkgManager)
+          }
+        }
+
+        requestAnimationFrame(() => {
+          for (const pkgTab of pkgTabs) {
+            pkgTab.observeTabs()
+          }
+
+          newFocusedTab?.focus()
+        })
+      }
+
+      // https://github.com/withastro/starlight/blob/290af4f0b5f65619fa4c65609940c3a911a7e698/packages/starlight/user-components/Tabs.astro#L116-L135
+      #switchTabs(starlightTabs: StarlightTabs, newPkgManager: string) {
+        const tabs = starlightTabs.tabs
+        const newTabIndex = tabs.findIndex((tab) => tab.textContent?.trim() === newPkgManager)
+        const newTab = tabs[newTabIndex]
+        const newPanel = starlightTabs.panels[newTabIndex]
+
+        if (!newTab || !newPanel) {
+          return
+        }
+
+        for (const tab of starlightTabs.tabs) {
+          tab.removeAttribute('aria-selected')
+          tab.setAttribute('tabindex', '-1')
+        }
+
+        for (const panel of starlightTabs.panels) {
+          panel.hidden = true
+        }
+
+        newPanel.hidden = false
+        // Restore active tab to the default tab order.
+        newTab.removeAttribute('tabindex')
+        newTab.setAttribute('aria-selected', 'true')
+      }
+
+      #isStarlightTabs(element: Element | null): element is StarlightTabs {
+        return element instanceof Element && 'tabs' in element && 'panels' in element
+      }
+    },
+  )
+
+  type StarlightTabs = Element & {
+    panels: HTMLElement[]
+    tabs: HTMLAnchorElement[]
+  }
+</script>

package/README.md

@@ -0,0 +1,81 @@
+<div align="center">
+  <h1>starlight-package-managers 🗃</h1>
+  <p>Quickly display npm related commands for multiple package managers in your Starlight documentation site.</p>
+  <p>
+    <a href="https://github.com/HiDeoo/vercel-env-push/assets/494699/a5ac0d80-984c-418f-8ecd-41a034b2e25a" title="Demo of starlight-package-managers">
+      <img alt="Demo of starlight-package-managers" src="https://github.com/HiDeoo/vercel-env-push/assets/494699/a5ac0d80-984c-418f-8ecd-41a034b2e25a" width="520" />
+    </a>
+  </p>
+</div>
+
+<div align="center">
+  <a href="https://github.com/HiDeoo/starlight-package-managers/actions/workflows/integration.yml">
+    <img alt="Integration Status" src="https://github.com/HiDeoo/starlight-package-managers/actions/workflows/integration.yml/badge.svg" />
+  </a>
+  <a href="https://github.com/HiDeoo/starlight-package-managers/blob/main/LICENSE">
+    <img alt="License" src="https://badgen.net/github/license/HiDeoo/starlight-package-managers" />
+  </a>
+  <br />
+</div>
+
+## Getting Started
+
+Want to get started immediately? Check out the [getting started guide](https://starlight-package-managers.vercel.app/guides/getting-started/).
+
+## Description
+
+Replace the following MDX code:
+
+````mdx
+<Tabs>
+<TabItem label="npm">
+
+```sh
+npm create astro@latest -- --template starlight
+```
+
+</TabItem>
+<TabItem label="pnpm">
+
+```sh
+pnpm create astro --template starlight
+```
+
+</TabItem>
+<TabItem label="Yarn">
+
+```sh
+yarn create astro --template starlight
+```
+
+</TabItem>
+</Tabs>
+````
+
+By this one:
+
+```mdx
+<PackageManagers type="create" pkg="astro@latest" args="--template starlight" />
+```
+
+## Features
+
+- Support for various package managers: [npm](https://www.npmjs.com), [yarn](https://yarnpkg.com), [pnpm](https://pnpm.io), [bun](https://bun.sh) & [ni](https://github.com/antfu/ni).
+- Support for various types of command: [`add`](https://starlight-package-managers.vercel.app/guides/usage/#add), [`create`](https://starlight-package-managers.vercel.app/guides/usage/#create), [`exec`](https://starlight-package-managers.vercel.app/guides/usage/#exec) & [`run`](https://starlight-package-managers.vercel.app/guides/usage/#run).
+- Synced tabs between each instance on the same page.
+- Customizable output with [extra arguments](https://starlight-package-managers.vercel.app/guides/usage/#extra-arguments), [comments](https://starlight-package-managers.vercel.app/guides/usage/#comment) & [prefixes](https://starlight-package-managers.vercel.app/guides/usage/#prefix).
+
+## Documentation
+
+Check out the [Starlight Package Managers documentation](https://starlight-package-managers.vercel.app).
+
+## Related Projects
+
+- [npm-package-manager-extension](https://github.com/HiDeoo/npm-package-manager-extension)
+- [npm-install-block](https://github.com/HiDeoo/npm-install-block)
+
+## License
+
+Licensed under the MIT License, Copyright © HiDeoo.
+
+See [LICENSE](https://github.com/HiDeoo/starlight-package-managers/blob/main/LICENSE) for more information.

package/index.ts

@@ -0,0 +1 @@
+export { default as PackageManagers, type PackageManagersProps } from './PackageManagers.astro'

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "starlight-package-managers",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "Quickly display npm related commands for multiple package managers in your Starlight documentation site.",
+  "author": "HiDeoo <github@hideoo.dev> (https://hideoo.dev)",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@astrojs/starlight": "0.6.0",
+    "@playwright/test": "1.36.2",
+    "astro": "2.9.6",
+    "vitest": "0.33.0"
+  },
+  "peerDependencies": {
+    "@astrojs/starlight": ">=0.5.0",
+    "astro": ">=2.5.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "packageManager": "pnpm@8.6.10",
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "keywords": [
+    "astro-component",
+    "withastro",
+    "starlight",
+    "package",
+    "manager",
+    "npm"
+  ],
+  "homepage": "https://github.com/HiDeoo/starlight-package-managers",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/HiDeoo/starlight-package-managers.git"
+  },
+  "bugs": "https://github.com/HiDeoo/starlight-package-managers/issues",
+  "scripts": {
+    "test": "pnpm test:unit && pnpm test:e2e",
+    "test:unit": "vitest",
+    "test:e2e": "playwright test",
+    "lint": "prettier -c --cache . && eslint . --cache --max-warnings=0"
+  }
+}

package/pkg.ts

@@ -0,0 +1,98 @@
+const pkgManagers = ['npm', 'yarn', 'pnpm', 'bun', 'ni'] as const
+
+const defaultPkgManagers: PackageManager[] = ['npm', 'yarn', 'pnpm']
+
+const commands: Commands = {
+  npm: {
+    add: 'npm i',
+    create: 'npm create',
+    devOption: '-D',
+    exec: 'npx',
+    run: 'npm run',
+  },
+  yarn: {
+    add: 'yarn add',
+    create: 'yarn create',
+    devOption: '-D',
+    exec: 'yarn',
+    run: 'yarn run',
+  },
+  pnpm: {
+    add: 'pnpm add',
+    create: 'pnpm create',
+    devOption: '-D',
+    exec: 'pnpm',
+    run: 'pnpm run',
+  },
+  bun: {
+    add: 'bun add',
+    devOption: '-d',
+    exec: 'bunx',
+    run: 'bun run',
+  },
+  ni: {
+    add: 'ni',
+    devOption: '-D',
+    exec: 'nlx',
+    run: 'nr',
+  },
+}
+
+export function getSupportedPkgManagers(type: CommandType, userPkgManagers: PackageManager[] | undefined) {
+  return (userPkgManagers ?? defaultPkgManagers).filter((pkgManager) => commands[pkgManager][type] !== undefined)
+}
+
+export function getCommand(
+  pkgManager: PackageManager,
+  type: CommandType,
+  pkg: string | undefined,
+  options: CommandOptions,
+) {
+  let command = commands[pkgManager][type]
+
+  if (!command) {
+    throw new Error(`Command type '${type}' is not supported for package manager '${pkgManager}'.`)
+  }
+
+  if (options.prefix) {
+    command = `${options.prefix} ${command}`
+  }
+
+  if (options.comment) {
+    command = `# ${options.comment.replaceAll('{PKG}', pkgManager)}\n${command}`
+  }
+
+  if (type === 'add' && options.dev) {
+    command += ` ${commands[pkgManager].devOption}`
+  }
+
+  if (pkg) {
+    command += ` ${pkg}`
+  }
+
+  if (options.args && options.args.length > 0) {
+    if (pkgManager === 'npm' && type !== 'exec' && type !== 'run') {
+      command += ' --'
+    }
+
+    command += ` ${options.args}`
+  }
+
+  return command
+}
+
+export type CommandType = 'add' | 'create' | 'exec' | 'run'
+
+export interface CommandOptions {
+  args?: string
+  comment?: string
+  dev?: boolean
+  prefix?: string
+}
+
+type Commands = Record<
+  PackageManager,
+  Record<Exclude<CommandType, 'create'> | 'devOption', string> & { create?: string }
+>
+
+export type PackageManager = (typeof pkgManagers)[number]