first commit

docs/api-stack/api/api-openapi-ui-scalar/src/options/options.md

@@ -0,0 +1,79 @@
+# `ScalarUiOptions` — Zod-validated configuration
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+The options module owns the single Zod schema consumed by every Scalar
+UI handler factory. It is exposed both directly (`scalarUiOptionsSchema`)
+and via the convenience `parseScalarUiOptions(input)` helper that wraps
+the underlying `ZodError` in an `OpenapiUiScalarError` tagged with
+`OPENAPI_UI_SCALAR.INVALID_OPTIONS`. This double-surface lets host
+config ingestion decide whether to surface raw Zod issues or rely on the
+package's stable error-code contract.
+
+## Features
+
+- Required `openapiUrl` field (with default `/openapi.json`).
+- Endpoint defaults match design doc §7 (`/docs/ui/scalar`).
+- Eleven built-in `theme` literals matching the upstream Scalar palette.
+- `layout` literals `"modern" | "classic"`.
+- `assetMode` literals `"cdn" | "bundled"` toggling the runtime asset
+  resolution path.
+- `cdnUrl` defaults to the upstream JSDelivr URL of
+  `@scalar/api-reference`.
+- `editorOptions` is an open passthrough bag for upstream Scalar config
+  options the schema does not enumerate.
+- `.strict()` rejects unknown keys so typos surface at host-config load.
+
+## Usage: Basic
+
+```ts
+import { parseScalarUiOptions } from "@suaveplan/api-openapi-ui-scalar/options";
+
+const opts = parseScalarUiOptions({ openapiUrl: "/openapi.json" });
+console.log(opts.uiEndpoint); // "/docs/ui/scalar"
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    parseScalarUiOptions,
+    scalarUiOptionsSchema,
+} from "@suaveplan/api-openapi-ui-scalar/options";
+
+// Schema can be composed with host-config layers — every default is
+// safe in the empty-object case so the schema can be merged with other
+// host config without surprises.
+const hostSchema = scalarUiOptionsSchema.extend({
+    enabled: scalarUiOptionsSchema.shape.darkMode,
+});
+
+const parsed = parseScalarUiOptions({
+    openapiUrl: "/v1/openapi.json",
+    theme: "deepSpace",
+    layout: "classic",
+    assetMode: "bundled",
+});
+```
+
+## API Reference
+
+- `scalarUiOptionsSchema` — Zod object schema, `.strict()`.
+- `parseScalarUiOptions(input?)` — returns the resolved `ScalarUiOptions`
+  or throws `OpenapiUiScalarError(INVALID_OPTIONS)`.
+- `SCALAR_THEMES` / `SCALAR_LAYOUTS` / `SCALAR_ASSET_MODES` — literal
+  unions backing the schema enums.
+- `ScalarUiOptions` / `ScalarUiOptionsInput` — output / input types.
+
+## Implementation Notes
+
+The schema uses Zod `.default()` on every optional field so the empty
+`{}` case round-trips to a complete options object. The `.strict()` mode
+is essential — host operators frequently mistype keys (e.g. `themes` vs
+`theme`) and the strict guard surfaces those at boot rather than at
+first request. `INVALID_OPTIONS` wraps `safeParse` failures so the error
+chain preserves the underlying issue list for log/telemetry consumers.