@hyvor/design 2.0.18 → 2.1.0

package/dist/marketing/Docs/OpenApi/OpenApi.svelte

@@ -0,0 +1,144 @@
+<script lang="ts">
+	import Loader from '../../../components/Loader/Loader.svelte';
+	import Callout from '../../../components/Callout/Callout.svelte';
+	import Operation from './Operation.svelte';
+	import { groupOperations, loadOpenApi, methodColor } from './openapi.js';
+
+	interface Props {
+		// path (or URL) to an OpenAPI 3.x JSON document. $refs are dereferenced client-side.
+		path: string;
+		// base URL used to build the example curl requests.
+		// falls back to the spec's servers[0].url, then to an empty string.
+		baseUrl?: string;
+	}
+
+	let { path, baseUrl }: Props = $props();
+
+	async function load() {
+		const { doc, schemaNames } = await loadOpenApi(path);
+		const groups = groupOperations(doc);
+		const resolvedBaseUrl = baseUrl ?? doc.servers?.[0]?.url ?? '';
+		return { groups, schemaNames, baseUrl: resolvedBaseUrl };
+	}
+
+	const dataPromise = $derived(load());
+</script>
+
+<div class="openapi">
+	{#await dataPromise}
+		<Loader block padding="large" />
+	{:then { groups, schemaNames, baseUrl: resolvedBaseUrl }}
+		<nav class="top-nav">
+			{#each groups as group (group.key)}
+				<a href="#{group.key}">{group.title}</a>
+			{/each}
+		</nav>
+
+		<div class="operations">
+			{#each groups as group (group.key)}
+				<section>
+					<h2 id={group.key}>{group.title}</h2>
+
+					<nav class="section-nav">
+						{#each group.operations as operation (operation.id)}
+							<a href="#{operation.id}" class="op-link">
+								<span class="op-method {methodColor(operation.method)}"
+									>{operation.method.toUpperCase()}</span
+								>
+								<span class="op-path">{operation.path}</span>
+							</a>
+						{/each}
+					</nav>
+
+					{#each group.operations as operation (operation.id)}
+						<Operation {operation} baseUrl={resolvedBaseUrl} {schemaNames} />
+					{/each}
+				</section>
+			{/each}
+		</div>
+	{:catch error}
+		<Callout type="danger" title="Failed to load API reference">
+			{error instanceof Error ? error.message : String(error)}
+		</Callout>
+	{/await}
+</div>
+
+<style>
+	.top-nav {
+		position: sticky;
+		top: var(--header-height);
+		z-index: 5;
+		display: flex;
+		flex-wrap: wrap;
+		gap: 4px 18px;
+		padding: 14px 0;
+		margin-bottom: 10px;
+		background-color: var(--box-background);
+		border-bottom: 1px solid var(--border);
+	}
+	.top-nav a {
+		font-size: 13px;
+		font-weight: 600;
+		color: var(--text-light);
+		white-space: nowrap;
+	}
+	.top-nav a:hover {
+		color: var(--text);
+		text-decoration: underline;
+	}
+
+	.section-nav {
+		display: flex;
+		flex-wrap: wrap;
+		gap: 6px 16px;
+		margin: 10px 0 20px;
+		padding-bottom: 16px;
+		border-bottom: 1px solid var(--border);
+	}
+	.op-link {
+		display: flex;
+		align-items: baseline;
+		gap: 6px;
+		font-size: 12px;
+		text-decoration: none;
+		color: var(--text);
+	}
+	.op-link:hover .op-path {
+		text-decoration: underline;
+	}
+	.op-method {
+		font-family: monospace;
+		font-size: 10px;
+		font-weight: 700;
+		flex-shrink: 0;
+	}
+	.op-method.blue {
+		color: var(--blue-dark);
+	}
+	.op-method.green {
+		color: var(--green-dark);
+	}
+	.op-method.orange {
+		color: var(--orange-dark);
+	}
+	.op-method.red {
+		color: var(--red-dark);
+	}
+	.op-method.default {
+		color: var(--gray-dark);
+	}
+	.op-path {
+		font-family: monospace;
+		font-size: 12px;
+		word-break: break-all;
+		color: var(--text-light);
+	}
+
+	.operations h2 {
+		margin: 40px 0 0;
+		font-size: 22px;
+	}
+	.operations section:first-child h2 {
+		margin-top: 0;
+	}
+</style>

package/dist/marketing/Docs/OpenApi/OpenApi.svelte.d.ts

@@ -0,0 +1,7 @@
+interface Props {
+    path: string;
+    baseUrl?: string;
+}
+declare const OpenApi: import("svelte").Component<Props, {}, "">;
+type OpenApi = ReturnType<typeof OpenApi>;
+export default OpenApi;

package/dist/marketing/Docs/OpenApi/Operation.svelte

@@ -0,0 +1,147 @@
+<script lang="ts">
+	import CodeBlock from '../../../components/CodeBlock/CodeBlock.svelte';
+	import Tag from '../../../components/Tag/Tag.svelte';
+	import ParamsTable from './ParamsTable.svelte';
+	import SchemaFields from './SchemaFields.svelte';
+	import {
+		buildCurl,
+		describeType,
+		methodColor,
+		unwrapArraySchema,
+		type Operation,
+		type SchemaNameMap
+	} from './openapi.js';
+
+	interface Props {
+		operation: Operation;
+		baseUrl: string;
+		schemaNames?: SchemaNameMap;
+	}
+
+	let { operation, baseUrl, schemaNames }: Props = $props();
+
+	const curl = $derived(buildCurl(operation, baseUrl));
+
+	const body = $derived(
+		operation.requestBodySchema ? unwrapArraySchema(operation.requestBodySchema) : undefined
+	);
+	const response = $derived(
+		operation.response?.schema ? unwrapArraySchema(operation.response.schema) : undefined
+	);
+</script>
+
+<div class="operation" id={operation.id}>
+	<div class="spec">
+		<div class="op-heading">
+			<Tag size="small" color={methodColor(operation.method)}>{operation.method.toUpperCase()}</Tag>
+			<code class="op-path">{operation.path}</code>
+		</div>
+
+		{#if operation.summary}
+			<p class="summary">{operation.summary}</p>
+		{/if}
+		{#if operation.description}
+			<p>{operation.description}</p>
+		{/if}
+
+		<ParamsTable title="Path Parameters" params={operation.pathParams} />
+		<ParamsTable title="Query Parameters" params={operation.queryParams} />
+		<ParamsTable title="Headers" params={operation.headerParams} />
+
+		{#if body}
+			<h4>
+				Body
+				<span class="type-label">{describeType(operation.requestBodySchema, schemaNames)}</span>
+				{#if operation.requestBodyRequired}<span class="required-label">required</span>{/if}
+			</h4>
+			<SchemaFields schema={body.itemSchema} {schemaNames} />
+		{/if}
+
+		{#if response}
+			<h4>
+				Response
+				<span class="type-label">{describeType(operation.response?.schema, schemaNames)}</span>
+			</h4>
+			<SchemaFields schema={response.itemSchema} {schemaNames} />
+		{/if}
+	</div>
+
+	<div class="example">
+		<div class="example-sticky">
+			<div class="example-label">Example request</div>
+			<CodeBlock code={curl} language="sh" />
+		</div>
+	</div>
+</div>
+
+<style>
+	.operation {
+		display: grid;
+		grid-template-columns: 1fr 420px;
+		gap: 40px;
+		padding: 30px 0;
+		border-top: 1px solid var(--border);
+	}
+	.op-heading {
+		display: flex;
+		align-items: center;
+		gap: 10px;
+		margin-bottom: 12px;
+	}
+	.op-path {
+		font-size: 15px;
+		font-weight: 600;
+	}
+	.summary {
+		font-weight: 600;
+		margin: 0 0 8px;
+	}
+	.spec p {
+		line-height: var(--line-height-content);
+		margin: 0 0 8px;
+	}
+	h4 {
+		margin: 20px 0 8px;
+		font-size: 13px;
+		text-transform: uppercase;
+		letter-spacing: 0.04em;
+		color: var(--text-light);
+	}
+	.required-label {
+		text-transform: none;
+		letter-spacing: normal;
+		color: var(--red-dark);
+		font-weight: 400;
+		margin-left: 6px;
+	}
+	.type-label {
+		text-transform: none;
+		letter-spacing: normal;
+		font-family: monospace;
+		font-weight: 400;
+		color: var(--text-light);
+		margin-left: 6px;
+	}
+	.example-sticky {
+		position: sticky;
+		top: 75px;
+	}
+	.example-label {
+		font-size: 12px;
+		font-weight: 600;
+		text-transform: uppercase;
+		letter-spacing: 0.04em;
+		color: var(--text-light);
+		margin-bottom: 8px;
+	}
+
+	@media (max-width: 992px) {
+		.operation {
+			grid-template-columns: 1fr;
+			gap: 15px;
+		}
+		.example-sticky {
+			position: static;
+		}
+	}
+</style>

package/dist/marketing/Docs/OpenApi/Operation.svelte.d.ts

@@ -0,0 +1,9 @@
+import { type Operation, type SchemaNameMap } from './openapi.js';
+interface Props {
+    operation: Operation;
+    baseUrl: string;
+    schemaNames?: SchemaNameMap;
+}
+declare const Operation: import("svelte").Component<Props, {}, "">;
+type Operation = ReturnType<typeof Operation>;
+export default Operation;

package/dist/marketing/Docs/OpenApi/ParamsTable.svelte

@@ -0,0 +1,57 @@
+<script lang="ts">
+	import Table from '../../../components/Table/Table.svelte';
+	import TableRow from '../../../components/Table/TableRow.svelte';
+	import TableCell from '../../../components/Table/TableCell.svelte';
+	import { describeType, type ParameterObject } from './openapi.js';
+
+	interface Props {
+		title: string;
+		params: ParameterObject[];
+	}
+
+	let { title, params }: Props = $props();
+</script>
+
+{#if params.length}
+	<h4>{title}</h4>
+	<Table columns="1fr 1fr 2fr" style="bordered">
+		<TableRow head>
+			<TableCell>Name</TableCell>
+			<TableCell>Type</TableCell>
+			<TableCell>Description</TableCell>
+		</TableRow>
+		{#each params as param (param.name)}
+			<TableRow>
+				<TableCell>
+					<code>{param.name}</code>
+					{#if param.required}<span class="required" title="required">*</span>{/if}
+				</TableCell>
+				<TableCell><span class="type">{describeType(param.schema)}</span></TableCell>
+				<TableCell>{param.description ?? ''}</TableCell>
+			</TableRow>
+		{/each}
+	</Table>
+{/if}
+
+<style>
+	h4 {
+		margin: 20px 0 8px;
+		font-size: 13px;
+		text-transform: uppercase;
+		letter-spacing: 0.04em;
+		color: var(--text-light);
+	}
+	code {
+		font-size: 13px;
+		font-weight: 600;
+	}
+	.required {
+		color: var(--red-dark);
+		margin-left: 2px;
+	}
+	.type {
+		font-family: monospace;
+		font-size: 12px;
+		color: var(--text-light);
+	}
+</style>

package/dist/marketing/Docs/OpenApi/ParamsTable.svelte.d.ts

@@ -0,0 +1,8 @@
+import { type ParameterObject } from './openapi.js';
+interface Props {
+    title: string;
+    params: ParameterObject[];
+}
+declare const ParamsTable: import("svelte").Component<Props, {}, "">;
+type ParamsTable = ReturnType<typeof ParamsTable>;
+export default ParamsTable;

package/dist/marketing/Docs/OpenApi/SchemaFields.svelte

@@ -0,0 +1,141 @@
+<script lang="ts">
+	import Table from '../../../components/Table/Table.svelte';
+	import TableRow from '../../../components/Table/TableRow.svelte';
+	import TableCell from '../../../components/Table/TableCell.svelte';
+	import { describeType, type JsonSchema, type SchemaNameMap } from './openapi.js';
+	import SchemaFields from './SchemaFields.svelte';
+
+	interface Props {
+		schema?: JsonSchema;
+		schemaNames?: SchemaNameMap;
+	}
+
+	let { schema, schemaNames }: Props = $props();
+
+	interface Field {
+		name: string;
+		schema: JsonSchema;
+		required: boolean;
+	}
+
+	const fields = $derived.by((): Field[] => {
+		if (!schema?.properties) return [];
+		const required = new Set(schema.required ?? []);
+		return Object.entries(schema.properties).map(([name, s]) => ({
+			name,
+			schema: s,
+			required: required.has(name)
+		}));
+	});
+
+	// a property "folds" when it's an object (or array of objects) with its own fields,
+	// so nested/named schemas don't get inlined in full every time they're referenced
+	function nestedSchema(s: JsonSchema): JsonSchema | undefined {
+		if (s.type === 'object' && s.properties) return s;
+		if (s.type === 'array' && s.items?.type === 'object' && s.items.properties) return s.items;
+		return undefined;
+	}
+
+	function nestedName(s: JsonSchema): string | undefined {
+		return schemaNames?.get(s);
+	}
+</script>
+
+{#if fields.length}
+	<Table columns="1fr 1fr 2fr" style="bordered">
+		<TableRow head>
+			<TableCell>Field</TableCell>
+			<TableCell>Type</TableCell>
+			<TableCell>Details</TableCell>
+		</TableRow>
+		{#each fields as field (field.name)}
+			{@const nested = nestedSchema(field.schema)}
+			<TableRow>
+				<TableCell>
+					<code>{field.name}</code>
+					{#if field.required}<span class="required" title="required">*</span>{/if}
+				</TableCell>
+				<TableCell><span class="type">{describeType(field.schema, schemaNames)}</span></TableCell>
+				<TableCell>
+					{#if field.schema.enum}
+						<div class="enum">
+							{#each field.schema.enum as value (String(value))}
+								<code class="enum-value">{JSON.stringify(value)}</code>
+							{/each}
+						</div>
+					{/if}
+					{#if field.schema.description}
+						<div class="meta">{field.schema.description}</div>
+					{/if}
+					{#if field.schema.default !== undefined}
+						<div class="meta">Default: <code>{JSON.stringify(field.schema.default)}</code></div>
+					{/if}
+					{#if field.schema.pattern}
+						<div class="meta">Pattern: <code>{field.schema.pattern}</code></div>
+					{/if}
+					{#if field.schema.maxLength !== undefined}
+						<div class="meta">Max length: {field.schema.maxLength}</div>
+					{/if}
+					{#if field.schema.minLength !== undefined}
+						<div class="meta">Min length: {field.schema.minLength}</div>
+					{/if}
+					{#if nested}
+						<details class="nested">
+							<summary>Show {nestedName(nested) ?? ''} fields</summary>
+							<SchemaFields schema={nested} {schemaNames} />
+						</details>
+					{/if}
+				</TableCell>
+			</TableRow>
+		{/each}
+	</Table>
+{/if}
+
+<style>
+	code {
+		font-size: 13px;
+		font-weight: 600;
+	}
+	.required {
+		color: var(--red-dark);
+		margin-left: 2px;
+	}
+	.type {
+		font-family: monospace;
+		font-size: 12px;
+		color: var(--text-light);
+	}
+	.enum {
+		display: flex;
+		flex-wrap: wrap;
+		gap: 4px;
+		margin-bottom: 4px;
+	}
+	.enum-value {
+		font-size: 11px;
+		font-weight: 400;
+		background: var(--accent-lightest);
+		padding: 1px 6px;
+		border-radius: 8px;
+	}
+	.meta {
+		font-size: 12px;
+		color: var(--text-light);
+	}
+	.meta code {
+		font-size: 11px;
+		font-weight: 400;
+	}
+	.nested {
+		margin-top: 6px;
+		font-size: 13px;
+	}
+	.nested summary {
+		cursor: pointer;
+		color: var(--link);
+		font-size: 12px;
+	}
+	.nested :global(.table) {
+		margin-top: 8px;
+	}
+</style>

package/dist/marketing/Docs/OpenApi/SchemaFields.svelte.d.ts

@@ -0,0 +1,9 @@
+import { type JsonSchema, type SchemaNameMap } from './openapi.js';
+import SchemaFields from './SchemaFields.svelte';
+interface Props {
+    schema?: JsonSchema;
+    schemaNames?: SchemaNameMap;
+}
+declare const SchemaFields: import("svelte").Component<Props, {}, "">;
+type SchemaFields = ReturnType<typeof SchemaFields>;
+export default SchemaFields;

package/dist/marketing/Docs/OpenApi/openapi.d.ts

@@ -0,0 +1,106 @@
+export type HttpMethod = 'get' | 'put' | 'post' | 'delete' | 'options' | 'head' | 'patch' | 'trace';
+export interface JsonSchema {
+    type?: string;
+    format?: string;
+    title?: string;
+    description?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema;
+    enum?: (string | number | boolean)[];
+    oneOf?: JsonSchema[];
+    anyOf?: JsonSchema[];
+    allOf?: JsonSchema[];
+    additionalProperties?: boolean | JsonSchema;
+    nullable?: boolean;
+    default?: unknown;
+    example?: unknown;
+    maxLength?: number;
+    minLength?: number;
+    minimum?: number;
+    maximum?: number;
+    pattern?: string;
+    [key: string]: unknown;
+}
+export interface ParameterObject {
+    name: string;
+    in: 'path' | 'query' | 'header' | 'cookie';
+    required?: boolean;
+    description?: string;
+    schema?: JsonSchema;
+}
+export interface OperationObject {
+    operationId?: string;
+    summary?: string;
+    description?: string;
+    parameters?: ParameterObject[];
+    requestBody?: {
+        required?: boolean;
+        description?: string;
+        content?: Record<string, {
+            schema?: JsonSchema;
+        }>;
+    };
+    responses?: Record<string, {
+        description?: string;
+        content?: Record<string, {
+            schema?: JsonSchema;
+        }>;
+    }>;
+}
+export interface OpenApiDocument {
+    openapi?: string;
+    info?: {
+        title?: string;
+        description?: string;
+        version?: string;
+    };
+    servers?: {
+        url: string;
+        description?: string;
+    }[];
+    paths: Record<string, Record<string, OperationObject>>;
+    components?: {
+        schemas?: Record<string, JsonSchema>;
+    };
+}
+export interface Operation {
+    id: string;
+    method: HttpMethod;
+    path: string;
+    operationId?: string;
+    summary?: string;
+    description?: string;
+    pathParams: ParameterObject[];
+    queryParams: ParameterObject[];
+    headerParams: ParameterObject[];
+    requestBodySchema?: JsonSchema;
+    requestBodyRequired: boolean;
+    response?: {
+        description?: string;
+        schema?: JsonSchema;
+    };
+}
+export interface OperationGroup {
+    key: string;
+    title: string;
+    operations: Operation[];
+}
+export type SchemaNameMap = Map<JsonSchema, string>;
+export interface LoadedOpenApi {
+    doc: OpenApiDocument;
+    schemaNames: SchemaNameMap;
+}
+export declare function loadOpenApi(path: string): Promise<LoadedOpenApi>;
+export declare function titleCase(segment: string): string;
+export declare function groupOperations(doc: OpenApiDocument): OperationGroup[];
+export declare function methodColor(method: HttpMethod): 'blue' | 'green' | 'orange' | 'red' | 'default';
+export declare function describeType(schema?: JsonSchema, schemaNames?: SchemaNameMap): string;
+export declare function unwrapArraySchema(schema: JsonSchema): {
+    isArray: boolean;
+    itemSchema: JsonSchema;
+};
+export declare function exampleValue(schema: JsonSchema | undefined, propName?: string): unknown;
+export declare function paramExample(param: ParameterObject): string;
+export declare function buildUrl(baseUrl: string, operation: Operation): string;
+export declare function buildCurl(operation: Operation, baseUrl: string): string;