@ewanc26/pds-landing 1.0.0 → 2.0.2

package/README.md

@@ -1,24 +1,132 @@
-# pds-landing
+# @ewanc26/pds-landing
 
-Static landing page for [pds.ewancroft.uk](https://pds.ewancroft.uk) — a personal ATProto PDS.
+Composable Svelte 5 components for an ATProto PDS landing page — terminal aesthetic, live status fetching, zero config to drop in.
 
-Displays live PDS status by querying `/xrpc/_health` and
-`/xrpc/com.atproto.server.describeServer` on load.
+## Install
 
-## Build
+```bash
+pnpm add @ewanc26/pds-landing @ewanc26/ui
+```
+
+## Quick start — full page
+
+```svelte
+<script>
+  import { PDSPage } from '@ewanc26/pds-landing';
+</script>
+
+<!-- Drop-in: renders the complete terminal landing page -->
+<PDSPage
+  cardTitle="ewan's pds"
+  promptUser="server"
+  promptHost="pds.ewancroft.uk"
+  tagline="Bluesky-compatible ATProto PDS · personal instance"
+  blueskyHandle="ewancroft.uk"
+/>
+```
+
+Import the PDS design tokens and base styles once in your layout:
+
+```css
+/* app.css / layout.css */
+@import '@ewanc26/ui/styles/pds-tokens.css';
+```
+
+---
+
+## Mix-and-match — primitives
+
+All primitives are exported individually so you can compose custom layouts.
+
+```svelte
+<script>
+  import {
+    TerminalCard,
+    PromptLine,
+    Tagline,
+    SectionLabel,
+    Divider,
+    StatusGrid,
+    LinkList,
+    ContactSection,
+    PDSFooter,
+  } from '@ewanc26/pds-landing';
+</script>
+
+<TerminalCard title="my pds">
+  <PromptLine user="server" host="pds.example.com" />
+  <Tagline text="My custom tagline" />
+
+  <SectionLabel label="status" />
+  <StatusGrid />          <!-- fetches live from same origin -->
+
+  <Divider />
 
-```sh
-nix build
+  <SectionLabel label="links" />
+  <LinkList links={[
+    { href: 'https://bsky.app', label: 'Bluesky' },
+    { href: 'https://atproto.com', label: 'ATProto docs' },
+  ]} />
+
+  <Divider />
+
+  <SectionLabel label="contact" />
+  <ContactSection blueskyHandle="you.bsky.social" />
+</TerminalCard>
+
+<PDSFooter />
 ```
 
-Output is a directory of static files suitable for serving directly with Caddy
-or any other file server.
+### Use raw KV data
+
+```svelte
+<script>
+  import { KVGrid } from '@ewanc26/pds-landing';
+  import type { KVItem } from '@ewanc26/pds-landing';
 
-## Usage in nix-config
+  const items: KVItem[] = [
+    { key: 'status', value: '✓ online', status: 'ok' },
+    { key: 'region', value: 'eu-west-1' },
+    { key: 'invite', value: 'required', status: 'warn' },
+  ];
+</script>
 
-Referenced via git subtree at `modules/server/pds-landing`. To pull upstream
-changes into nix-config:
+<KVGrid {items} />
+```
+
+### Fetch status yourself
 
-```sh
-git subtree pull --prefix modules/server/pds-landing pkgs pds-landing-split --squash
+```ts
+import { fetchPDSStatus } from '@ewanc26/pds-landing';
+
+const { health, description, accountCount } = await fetchPDSStatus('https://pds.example.com');
+```
+
+---
+
+## Components
+
+| Component | Description |
+|---|---|
+| `PDSPage` | Full assembled landing page (convenience) |
+| `TerminalCard` | Terminal window shell with traffic-light dots titlebar |
+| `PromptLine` | `user@host:path $` bash prompt header |
+| `Tagline` | Dimmed subtitle beneath the prompt |
+| `SectionLabel` | Uppercase section heading |
+| `Divider` | Thin green-tinted `<hr>` |
+| `KVGrid` | Key-value grid with ok/warn/err/loading states |
+| `StatusGrid` | Live-fetching PDS status grid (wraps `KVGrid`) |
+| `LinkList` | `→ link` list |
+| `ContactSection` | Bluesky mention + optional email |
+| `PDSFooter` | Footer with nixpkgs / atproto links |
+
+## Design tokens
+
+All components consume CSS custom properties from `@ewanc26/ui/styles/pds-tokens.css`:
+
+```
+--pds-font-mono
+--pds-color-crust / mantle / base / surface-0 / surface-1 / overlay-0
+--pds-color-text / subtext-0
+--pds-color-green / red / yellow / shadow
 ```

package/dist/components/ContactSection.svelte

@@ -0,0 +1,59 @@
+<script lang="ts">
+	interface Props {
+		/**
+		 * Bluesky handle (without @) to link to.
+		 * Example: `'ewancroft.uk'`
+		 */
+		blueskyHandle?: string;
+		/**
+		 * Base URL of the Bluesky web client used to build the profile link.
+		 * Defaults to `'https://bsky.app'`.
+		 */
+		blueskyClientUrl?: string;
+		/** Contact email address. Rendered only when provided. */
+		email?: string;
+	}
+
+	let {
+		blueskyHandle,
+		blueskyClientUrl = 'https://bsky.app',
+		email
+	}: Props = $props();
+
+	let profileUrl = $derived(
+		blueskyHandle ? `${blueskyClientUrl}/profile/${blueskyHandle}` : null
+	);
+</script>
+
+{#if blueskyHandle && profileUrl}
+	<p class="pds-contact-note">
+		Send a mention on Bluesky to
+		<a href={profileUrl} target="_blank" rel="noopener">@{blueskyHandle}</a>
+	</p>
+{/if}
+
+{#if email}
+	<p class="pds-contact-note pds-contact-email-row">
+		Email: <a href="mailto:{email}">{email}</a>
+	</p>
+{/if}
+
+<style>
+	.pds-contact-note {
+		font-size: 0.88em;
+		color: var(--pds-color-subtext-0);
+	}
+
+	.pds-contact-email-row {
+		margin-top: 0.4rem;
+	}
+
+	.pds-contact-note a {
+		text-decoration: none;
+		color: var(--pds-color-green);
+	}
+
+	.pds-contact-note a:hover {
+		text-decoration: underline;
+	}
+</style>

package/dist/components/ContactSection.svelte.d.ts

@@ -0,0 +1,17 @@
+interface Props {
+    /**
+     * Bluesky handle (without @) to link to.
+     * Example: `'ewancroft.uk'`
+     */
+    blueskyHandle?: string;
+    /**
+     * Base URL of the Bluesky web client used to build the profile link.
+     * Defaults to `'https://bsky.app'`.
+     */
+    blueskyClientUrl?: string;
+    /** Contact email address. Rendered only when provided. */
+    email?: string;
+}
+declare const ContactSection: import("svelte").Component<Props, {}, "">;
+type ContactSection = ReturnType<typeof ContactSection>;
+export default ContactSection;

package/dist/components/Divider.svelte

@@ -0,0 +1,9 @@
+<hr class="pds-divider" />
+
+<style>
+	.pds-divider {
+		border: none;
+		border-top: 1px solid color-mix(in srgb, var(--pds-color-green) 12%, transparent);
+		margin: 1.2rem 0;
+	}
+</style>

package/dist/components/Divider.svelte.d.ts

@@ -0,0 +1,26 @@
+export default Divider;
+type Divider = SvelteComponent<{
+    [x: string]: never;
+}, {
+    [evt: string]: CustomEvent<any>;
+}, {}> & {
+    $$bindings?: string | undefined;
+};
+declare const Divider: $$__sveltets_2_IsomorphicComponent<{
+    [x: string]: never;
+}, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import("svelte").ComponentConstructorOptions<Props>): import("svelte").SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}

package/dist/components/KVGrid.svelte

@@ -0,0 +1,87 @@
+<script lang="ts">
+	/** A single row in the key-value status grid. */
+	export interface KVItem {
+		key: string;
+		value: string;
+		/** Visual state applied to the value cell. */
+		status?: 'ok' | 'warn' | 'err' | 'loading';
+	}
+
+	interface Props {
+		items: KVItem[];
+	}
+
+	let { items }: Props = $props();
+</script>
+
+<div class="pds-kv-grid" role="list">
+	{#each items as item (item.key)}
+		<span class="pds-kv-key" role="term">{item.key}</span>
+		<span class="pds-kv-val {item.status ?? ''}" role="definition">{item.value}</span>
+	{/each}
+</div>
+
+<style>
+	.pds-kv-grid {
+		display: grid;
+		grid-template-columns: max-content 1fr;
+		gap: 0.25rem 1.2rem;
+		font-size: 0.88em;
+		margin-bottom: 1.4rem;
+	}
+
+	.pds-kv-key {
+		color: var(--pds-color-green);
+		opacity: 0.6;
+		white-space: nowrap;
+	}
+
+	.pds-kv-val {
+		color: var(--pds-color-text);
+		word-break: break-all;
+		min-width: 0;
+	}
+
+	.pds-kv-val.ok {
+		color: var(--pds-color-green);
+	}
+	.pds-kv-val.warn {
+		color: var(--pds-color-yellow);
+	}
+	.pds-kv-val.err {
+		color: var(--pds-color-red);
+	}
+	.pds-kv-val.loading {
+		color: var(--pds-color-surface-1);
+		animation: pds-kv-pulse 1.2s ease-in-out infinite;
+	}
+
+	@keyframes pds-kv-pulse {
+		0%,
+		100% {
+			opacity: 0.4;
+		}
+		50% {
+			opacity: 1;
+		}
+	}
+
+	@media (max-width: 440px) {
+		.pds-kv-grid {
+			grid-template-columns: 1fr;
+			gap: 0;
+		}
+
+		.pds-kv-key {
+			text-transform: uppercase;
+			opacity: 1;
+			font-size: 0.7em;
+			letter-spacing: 0.1em;
+			margin-top: 0.7rem;
+		}
+
+		.pds-kv-key:first-child {
+			margin-top: 0;
+		}
+	}
+</style>

package/dist/components/KVGrid.svelte.d.ts

@@ -0,0 +1,13 @@
+/** A single row in the key-value status grid. */
+export interface KVItem {
+    key: string;
+    value: string;
+    /** Visual state applied to the value cell. */
+    status?: 'ok' | 'warn' | 'err' | 'loading';
+}
+interface Props {
+    items: KVItem[];
+}
+declare const KVGrid: import("svelte").Component<Props, {}, "">;
+type KVGrid = ReturnType<typeof KVGrid>;
+export default KVGrid;

package/dist/components/LinkList.svelte

@@ -0,0 +1,60 @@
+<script lang="ts">
+	/** A single entry in a link list. */
+	export interface LinkItem {
+		href: string;
+		label: string;
+		/**
+		 * Whether to open in a new tab.
+		 * Defaults to `true` — set to `false` for internal navigation.
+		 */
+		external?: boolean;
+	}
+
+	interface Props {
+		links: LinkItem[];
+	}
+
+	let { links }: Props = $props();
+</script>
+
+<ul class="pds-link-list">
+	{#each links as link (link.href)}
+		<li>
+			<a
+				href={link.href}
+				target={link.external !== false ? '_blank' : undefined}
+				rel={link.external !== false ? 'noopener' : undefined}
+			>
+				{link.label}
+			</a>
+		</li>
+	{/each}
+</ul>
+
+<style>
+	.pds-link-list {
+		list-style: none;
+		display: flex;
+		flex-direction: column;
+		gap: 0.35rem;
+		font-size: 0.88em;
+		padding: 0;
+		margin: 0;
+	}
+
+	.pds-link-list li::before {
+		content: '→ ';
+		color: var(--pds-color-green);
+	}
+
+	.pds-link-list a {
+		text-decoration: none;
+		color: var(--pds-color-green);
+		opacity: 0.85;
+		transition: opacity 0.15s;
+	}
+
+	.pds-link-list a:hover {
+		opacity: 1;
+	}
+</style>

package/dist/components/LinkList.svelte.d.ts

@@ -0,0 +1,16 @@
+/** A single entry in a link list. */
+export interface LinkItem {
+    href: string;
+    label: string;
+    /**
+     * Whether to open in a new tab.
+     * Defaults to `true` — set to `false` for internal navigation.
+     */
+    external?: boolean;
+}
+interface Props {
+    links: LinkItem[];
+}
+declare const LinkList: import("svelte").Component<Props, {}, "">;
+type LinkList = ReturnType<typeof LinkList>;
+export default LinkList;

package/dist/components/PDSFooter.svelte

@@ -0,0 +1,43 @@
+<script lang="ts">
+	interface Props {
+		/** Show the `nixpkgs#bluesky-pds` credit. Defaults to `true`. */
+		showNixpkg?: boolean;
+		/** Show the `atproto.com` link. Defaults to `true`. */
+		showAtproto?: boolean;
+	}
+
+	let { showNixpkg = true, showAtproto = true }: Props = $props();
+</script>
+
+<footer class="pds-footer">
+	{#if showNixpkg}
+		powered by
+		<a href="https://search.nixos.org/packages?show=bluesky-pds" target="_blank" rel="noopener"
+			>nixpkgs#bluesky-pds</a
+		>
+	{/if}
+	{#if showNixpkg && showAtproto}
+		&nbsp;·&nbsp;
+	{/if}
+	{#if showAtproto}
+		<a href="https://atproto.com" target="_blank" rel="noopener">atproto.com</a>
+	{/if}
+</footer>
+
+<style>
+	.pds-footer {
+		text-align: center;
+		color: color-mix(in srgb, var(--pds-color-green) 35%, transparent);
+		font-size: 0.75em;
+	}
+
+	.pds-footer a {
+		text-decoration: underline;
+		color: color-mix(in srgb, var(--pds-color-green) 35%, transparent);
+		transition: color 0.15s;
+	}
+
+	.pds-footer a:hover {
+		color: var(--pds-color-green);
+	}
+</style>

package/dist/components/PDSFooter.svelte.d.ts

@@ -0,0 +1,9 @@
+interface Props {
+    /** Show the `nixpkgs#bluesky-pds` credit. Defaults to `true`. */
+    showNixpkg?: boolean;
+    /** Show the `atproto.com` link. Defaults to `true`. */
+    showAtproto?: boolean;
+}
+declare const PDSFooter: import("svelte").Component<Props, {}, "">;
+type PDSFooter = ReturnType<typeof PDSFooter>;
+export default PDSFooter;

package/dist/components/PDSPage.svelte

@@ -0,0 +1,172 @@
+<script lang="ts">
+	/**
+	 * PDSPage — a fully assembled ATProto PDS landing page.
+	 *
+	 * All sections (status, endpoints, links, contact) are included by default.
+	 * Each section can be individually disabled via boolean props, and the
+	 * individual primitives (TerminalCard, StatusGrid, LinkList, …) can be
+	 * composed manually for bespoke layouts.
+	 */
+	import { onMount } from 'svelte';
+	import TerminalCard from './TerminalCard.svelte';
+	import PromptLine from './PromptLine.svelte';
+	import Tagline from './Tagline.svelte';
+	import SectionLabel from './SectionLabel.svelte';
+	import Divider from './Divider.svelte';
+	import StatusGrid from './StatusGrid.svelte';
+	import LinkList from './LinkList.svelte';
+	import ContactSection from './ContactSection.svelte';
+	import PDSFooter from './PDSFooter.svelte';
+	import type { LinkItem } from './LinkList.svelte';
+	import { fetchPDSStatus } from '../utils/fetchPDSStatus.js';
+
+	interface Props {
+		// ── Card chrome ──────────────────────────────────────────────────────
+		/** Text shown in the terminal titlebar. */
+		cardTitle?: string;
+
+		// ── Prompt ───────────────────────────────────────────────────────────
+		promptUser?: string;
+		promptHost?: string;
+		promptPath?: string;
+		tagline?: string;
+
+		// ── API ──────────────────────────────────────────────────────────────
+		/**
+		 * Origin prepended to `/xrpc/…` calls.
+		 * Leave empty (`''`) to use the current page's origin (default).
+		 */
+		baseUrl?: string;
+
+		// ── Sections ─────────────────────────────────────────────────────────
+		showStatus?: boolean;
+		showEndpoints?: boolean;
+		showLinks?: boolean;
+		showContact?: boolean;
+		showFooter?: boolean;
+
+		// ── Links section ────────────────────────────────────────────────────
+		/**
+		 * Static links always shown in the Links section.
+		 * Dynamic links (privacy policy / ToS) from `describeServer` are
+		 * appended automatically.
+		 */
+		staticLinks?: LinkItem[];
+
+		// ── Contact section ──────────────────────────────────────────────────
+		blueskyHandle?: string;
+		blueskyClientUrl?: string;
+
+		// ── Footer ───────────────────────────────────────────────────────────
+		showNixpkg?: boolean;
+		showAtproto?: boolean;
+	}
+
+	let {
+		cardTitle = "ewan's pds",
+		promptUser = 'server',
+		promptHost = 'pds.ewancroft.uk',
+		promptPath = '~',
+		tagline = 'Bluesky-compatible ATProto PDS · personal instance',
+		baseUrl = '',
+		showStatus = true,
+		showEndpoints = true,
+		showLinks = true,
+		showContact = true,
+		showFooter = true,
+		staticLinks = [{ href: 'https://witchsky.app', label: 'Witchsky Web Client' }],
+		blueskyHandle = 'ewancroft.uk',
+		blueskyClientUrl = 'https://witchsky.app',
+		showNixpkg = true,
+		showAtproto = true
+	}: Props = $props();
+
+	const ENDPOINT_LINKS: LinkItem[] = [
+		{ href: 'https://github.com/bluesky-social/atproto', label: 'atproto source code' },
+		{ href: 'https://github.com/bluesky-social/pds', label: 'self-hosting guide' },
+		{ href: 'https://atproto.com', label: 'protocol docs' }
+	];
+
+	// Dynamic state populated from describeServer
+	let extraLinks: LinkItem[] = $state([]);
+	let dynamicLinks: LinkItem[] = $derived([...staticLinks, ...extraLinks]);
+	let contactEmail: string | null = $state(null);
+
+	onMount(async () => {
+		try {
+			const { description } = await fetchPDSStatus(baseUrl);
+			const extras: LinkItem[] = [];
+			if (description.links?.privacyPolicy) {
+				extras.push({ href: description.links.privacyPolicy, label: 'Privacy Policy' });
+			}
+			if (description.links?.termsOfService) {
+				extras.push({ href: description.links.termsOfService, label: 'Terms of Service' });
+			}
+			if (extras.length) extraLinks = extras;
+			if (description.contact?.email) contactEmail = description.contact.email;
+		} catch {
+			// silently fall back to static defaults
+		}
+	});
+</script>
+
+<div class="pds-page">
+	<TerminalCard title={cardTitle}>
+		<PromptLine user={promptUser} host={promptHost} path={promptPath} />
+		<Tagline text={tagline} />
+
+		{#if showStatus}
+			<SectionLabel label="status" />
+			<StatusGrid {baseUrl} />
+		{/if}
+
+		{#if showEndpoints}
+			<Divider />
+			<SectionLabel label="endpoints" />
+			<p class="pds-endpoints-note">
+				Most API routes are under <span class="pds-highlight">/xrpc/</span>
+			</p>
+			<LinkList links={ENDPOINT_LINKS} />
+		{/if}
+
+		{#if showLinks}
+			<Divider />
+			<SectionLabel label="links" />
+			<LinkList links={dynamicLinks} />
+		{/if}
+
+		{#if showContact}
+			<Divider />
+			<SectionLabel label="contact" />
+			<ContactSection
+				{blueskyHandle}
+				{blueskyClientUrl}
+				email={contactEmail ?? undefined}
+			/>
+		{/if}
+	</TerminalCard>
+
+	{#if showFooter}
+		<PDSFooter {showNixpkg} {showAtproto} />
+	{/if}
+</div>
+
+<style>
+	.pds-page {
+		display: flex;
+		flex-direction: column;
+		align-items: center;
+		gap: 2rem;
+		width: 100%;
+	}
+
+	.pds-endpoints-note {
+		font-size: 0.88em;
+		color: var(--pds-color-subtext-0);
+		margin-bottom: 0.7rem;
+	}
+
+	.pds-highlight {
+		color: var(--pds-color-green);
+	}
+</style>