Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -300,6 +300,11 @@ Content sits on the Cool Shell in a grid of panels: Feed White, 8px, hairline-bo
- **Status:** the console is the one place with status colors, `success` (lane-1's green) and `warning` (lane-5's ochre) beside Rm Red. They only ever mark state (healthy, watch, failing; event levels; better or worse than the period before) and always come with an icon, a sign or a word. They are not lanes and never mark a person.
- **Charts:** drawn in SVG at their real size, one y-axis, hairline gridlines, mono 11px ticks. History is a 2px ink line; a forecast continues it as a dashed Muted Ink line over a 15% Muted Ink wash for its range, after a dashed Rail Gray "today" rule. Columns are at most 24px wide with a 2px surface gap between stacked segments. Hovering shows the inverted tooltip; every chart carries a screen-reader table.

### API Docs
The API docs use the Operations Console's shell (`ConsoleLayout`), for everyone, guests included: the wordmark with a bordered mono `api` chip, a sidebar grouping the guides under `guide`, the theme switch and "Back to /dev/null" (without an avatar for a guest). The header names the section and says in one line what it holds; on the right a mono `v1`.

- **Guides:** read like the site's other long pages, never a card per section: one Feed White sheet on the Cool Shell, 1160px wide, 8px and hairline-bordered, whose sections follow one another with a hairline between them, each under a Section heading that links to itself. Prose at 15px, named values in a hairline list with mono keys like the settings, and code in the same code blocks as commits, highlighted on the server, its language above it.

### Error Pages
403, 404, 429, 500 (outside debug), and 503 render one standalone `error` page, with no app shell, for guests and signed-in users alike. A broken rail: the wordmark sits on a node in the viewer's lane (Rail Gray for guests) whose segment fades out before reaching a hollow, dangling node. Beside it, a mono git-style line (`fatal: path '/x' does not exist in 'HEAD'`), a Headline sentence saying what happened, one muted sentence saying what to do, and a single primary button ("Back to your log", "Go to the home page", or "Try again" during maintenance). A 419 is not a page: it redirects back with an error toast.

Expand Down
4 changes: 3 additions & 1 deletion KNOWLEDGE_BASE.md
Original file line number Diff line number Diff line change
Expand Up @@ -579,7 +579,9 @@ The read-only JSON API at `/api/v1` requires no authentication or token, except

Subscribe in a feed reader to `/@{handle}/feed.atom` for a profile's latest **50 approved top-level commits**, including image enclosures. Feeds are public and can be cached for five minutes.

Sources: [API routes](routes/api.php), [API controllers](app/Http/Controllers/Api), [feed generation](app/Actions/CreateUserFeed.php), [rate limits](app/Providers/AppServiceProvider.php).
The **API docs** at `/docs/api`, linked as **API** from the aside and the user menu, are readable by everyone. Their Introduction says what the API is for, its base URL and format, with a first request anyone can send.

Sources: [API routes](routes/api.php), [API controllers](app/Http/Controllers/Api), [feed generation](app/Actions/CreateUserFeed.php), [rate limits](app/Providers/AppServiceProvider.php), [docs page](app/Http/Controllers/ApiDocsController.php), [guides](resources/js/pages/api-docs/guides).

### Signed API and devices

Expand Down
37 changes: 37 additions & 0 deletions app/Enums/ApiDocsSection.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
<?php

declare(strict_types=1);

namespace App\Enums;

/**
* A page of the API docs: a guide to how the API works, in reading order.
*/
enum ApiDocsSection: string
{
case Introduction = 'introduction';

public function title(): string
{
return $this->name;
}

public function description(): string
{
return match ($this) {
self::Introduction => 'What the API is for, and where it lives',
};
}

/**
* @return array{slug: string, title: string, description: string}
*/
public function toArray(): array
{
return [
'slug' => $this->value,
'title' => $this->title(),
'description' => $this->description(),
];
}
}
30 changes: 30 additions & 0 deletions app/Http/Controllers/ApiDocsController.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use App\Enums\ApiDocsSection;
use App\Services\ApiGuideSnippets;
use App\Services\PageMetadata;
use Inertia\Inertia;
use Inertia\Response;

final readonly class ApiDocsController
{
/**
* A page of the API docs, readable by everyone, with every section for the sidebar.
*/
public function show(ApiDocsSection $section, PageMetadata $metadata, ApiGuideSnippets $snippets): Response
{
return Inertia::render('api-docs/show', [
'sections' => array_map(fn (ApiDocsSection $section): array => $section->toArray(), ApiDocsSection::cases()),
'current' => $section->value,
'snippets' => $snippets->for($section),
])->withViewData(['preview' => $metadata->page(
$section->title().' - API docs - /dev/null',
$section->description().'. The JSON API the /dev/null apps use, open to anything you build.',
route('api-docs.show', $section),
)]);
}
}
39 changes: 39 additions & 0 deletions app/Services/ApiGuideSnippets.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
<?php

declare(strict_types=1);

namespace App\Services;

use App\Enums\ApiDocsSection;
use Tempest\Highlight\Highlighter;

/**
* The code the API docs' guides show, highlighted on the server, so a guide shows it in the same code block as
* everywhere else on the site.
*/
final readonly class ApiGuideSnippets
{
public const string BaseUrl = 'https://dev-null.sh/api/v1';

public function __construct(private Highlighter $highlighter)
{
//
}

/**
* @return array<string, array{language: string, html: string}>
*/
public function for(ApiDocsSection $section): array
{
$snippets = match ($section) {
ApiDocsSection::Introduction => [
'firstRequest' => ['bash', 'curl '.self::BaseUrl."/users/nunomaduro \\\n -H 'Accept: application/json'"],
],
};

return array_map(fn (array $snippet): array => [
'language' => $snippet[0],
'html' => $this->highlighter->parse($snippet[1], $snippet[0]),
], $snippets);
}
}
119 changes: 119 additions & 0 deletions resources/js/components/api-docs/guide.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
import type { ReactNode } from 'react';
import { CodeBlock } from '@/components/code-block';
import { cn } from '@/lib/utils';
import type { ApiDocsSnippet } from '@/types';

/**
* How wide the docs' content is, so moving between their pages never changes the page's width.
*/
export const DOCS_WIDTH = 'max-w-[1160px]';

/**
* A guide of the API docs, read like the site's other long pages: one Feed White sheet on the console's shell, its
* sections one after the other with a hairline between them, never a card each.
*/
export function Guide({ children }: { children: ReactNode }) {
return (
<article
className={cn(
'mx-auto divide-y rounded-lg border bg-card text-[15px] leading-relaxed',
DOCS_WIDTH,
)}
>
{children}
</article>
);
}

function anchor(title: string): string {
return title
.toLowerCase()
.replace(/[^a-z0-9]+/g, '-')
.replace(/^-|-$/g, '');
}

/**
* A section of a guide, its title a link to itself, so a reader can point someone at it.
*/
export function GuideSection({
title,
children,
}: {
title: string;
children: ReactNode;
}) {
const id = anchor(title);

return (
<section
id={id}
aria-labelledby={`${id}-title`}
className="scroll-mt-32 space-y-3 px-5 py-7 text-pretty sm:px-8 lg:scroll-mt-20 [&_a]:underline [&_a]:decoration-rail [&_a]:underline-offset-4 [&_a:hover]:decoration-current"
>
<div className="flex flex-wrap items-baseline gap-x-3">
<h2
id={`${id}-title`}
className="text-lg font-semibold tracking-tight"
>
<a
href={`#${id}`}
className="no-underline! hover:underline!"
>
{title}
</a>
</h2>
</div>
{children}
</section>
);
}

/**
* A guide's code, in the code block the rest of the site uses, highlighted by the server.
*/
export function Snippet({ snippet }: { snippet: ApiDocsSnippet | undefined }) {
if (snippet === undefined) {
return null;
}

return (
<CodeBlock
html={snippet.html}
language={snippet.language}
filename={null}
/>
);
}

export function Code({ children }: { children: ReactNode }) {
return (
<code className="rounded-sm bg-muted px-1 py-0.5 font-mono text-[13px]">
{children}
</code>
);
}

/**
* Named values in a hairline list, keys in mono, as the settings list what they show.
*/
export function FieldList({
fields,
}: {
fields: { name: string; children: ReactNode }[];
}) {
return (
<dl className="divide-y rounded-lg border">
{fields.map((field) => (
<div
key={field.name}
className="grid gap-x-3 gap-y-0.5 px-3 py-2.5 sm:grid-cols-[9rem_minmax(0,1fr)]"
>
<dt className="font-mono text-[13px] text-muted-foreground">
{field.name}
</dt>
<dd className="min-w-0 text-sm">{field.children}</dd>
</div>
))}
</dl>
);
}
8 changes: 8 additions & 0 deletions resources/js/components/app-aside.tsx
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import { Link, usePage } from '@inertiajs/react';
import { Search } from 'lucide-react';
import AboutController from '@/actions/App/Http/Controllers/AboutController';
import ApiDocsController from '@/actions/App/Http/Controllers/ApiDocsController';
import AppController from '@/actions/App/Http/Controllers/AppController';
import ChangelogController from '@/actions/App/Http/Controllers/ChangelogController';
import PartnerController from '@/actions/App/Http/Controllers/PartnerController';
Expand Down Expand Up @@ -114,6 +115,13 @@ export function AppAside({
>
Apps
</Link>
<Link
href={ApiDocsController.show('introduction')}
prefetch
className="transition-colors hover:text-foreground"
>
API
</Link>
<Link
href={ChangelogController.index()}
prefetch
Expand Down
13 changes: 13 additions & 0 deletions resources/js/components/user-menu-content.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ import {
Activity,
AppWindow,
BookOpen,
Braces,
Star,
FileText,
HeartHandshake,
Expand All @@ -12,6 +13,7 @@ import {
UserRound,
} from 'lucide-react';
import AboutController from '@/actions/App/Http/Controllers/AboutController';
import ApiDocsController from '@/actions/App/Http/Controllers/ApiDocsController';
import AppController from '@/actions/App/Http/Controllers/AppController';
import OperationsController from '@/actions/App/Http/Controllers/OperationsController';
import PartnerController from '@/actions/App/Http/Controllers/PartnerController';
Expand Down Expand Up @@ -139,6 +141,17 @@ export function UserMenuContent({ user }: Props) {
Apps
</Link>
</DropdownMenuItem>
<DropdownMenuItem asChild>
<Link
className="block w-full cursor-pointer"
href={ApiDocsController.show('introduction')}
prefetch
onClick={cleanup}
>
<Braces className="mr-2" />
API
</Link>
</DropdownMenuItem>
<DropdownMenuItem asChild>
<Link
className="block w-full cursor-pointer"
Expand Down
58 changes: 58 additions & 0 deletions resources/js/layouts/api-docs/layout.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
import { usePage } from '@inertiajs/react';
import { BookOpen } from 'lucide-react';
import type { PropsWithChildren } from 'react';
import ApiDocsController from '@/actions/App/Http/Controllers/ApiDocsController';
import LogController from '@/actions/App/Http/Controllers/LogController';
import ConsoleLayout from '@/layouts/console/layout';
import type { ConsoleNavGroup } from '@/layouts/console/layout';
import { home } from '@/routes';
import type { ApiDocsProps, ApiDocsSection } from '@/types';

function navItems(sections: ApiDocsSection[]) {
return sections.map((section) => ({
key: section.slug,
title: section.title,
description: section.description,
href: ApiDocsController.show(section.slug),
icon: BookOpen,
}));
}

/**
* The API docs as a console beside the log, its guides in the sidebar.
*/
export default function ApiDocsLayout({ children }: PropsWithChildren) {
const { props } = usePage<ApiDocsProps>();

const groups: ConsoleNavGroup[] = [
{
label: 'Guide',
items: navItems(props.sections),
},
];

return (
<ConsoleLayout
chip="api"
label="/dev/null API docs, go to the introduction"
navLabel="API docs"
brandHref={ApiDocsController.show('introduction')}
prefetch
groups={groups}
current={props.current}
backHref={
props.auth.log === null
? home().url
: LogController.show(props.auth.log).url
}
user={props.auth.user}
headerActions={
<span className="px-2 font-mono text-[13px] text-muted-foreground">
v1
</span>
}
>
{children}
</ConsoleLayout>
);
}
Loading