@openish/elements

The openish-* custom elements. Import once, use the tags anywhere.

import '@openish/elements'

<link rel="stylesheet" href="@openish/theme/index.css" />
<openish-api-reference url="/openapi.yaml"></openish-api-reference>

Most pages need only <openish-api-reference>; everything below it is composed automatically. The rest are documented because they are usable on their own — <openish-schema> will render a schema anywhere you can give it a document through context, and <openish-code-block> is a general-purpose highlighted code block.

Styling

Every element reads --openish-* custom properties and nothing else. The full list, and what each one binds to in the Jack Henry Design System, is packages/theme/css/tokens.css — override any of them on a host element or at :root and the components follow. The token layer is the primary styling contract, and it is the one that travels: a custom property crosses a shadow boundary, and a selector does not.

Where a token is not enough, the layout, sidebar, tree, operation panes and sections, code blocks and dialogs expose CSS parts, chained through exportparts so a rule on the host page reaches four shadow roots down — ::part(operation-examples), ::part(code-toolbar), and the rest. The operation page also forwards slots (request-start, request-end, response-start, response-end) so a host can put its own markup inside a page it did not render.

Colour is checked, not assumed: packages/elements/test/contrast.test.ts measures every text pair, the HTTP method chips, and the syntax palette against WCAG AA in both schemes, and packages/elements/test/a11y.test.ts runs axe over the rendered pages.

Machine-readable

custom-elements.json ships with the package and is regenerated by npm run build. It is what IDEs, <custom-element> catalogues, and jh-ui's own tooling read.

Elements

<openish-api-reference>

The root of an API reference.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | url | url | string \| undefined | undefined | URL to fetch the document from. Ignored when spec is set. | | spec | — | string \| Record<string, unknown> \| undefined | undefined | An inline document: a YAML/JSON string, or an already-parsed object. Property only. | | sources | — | SourceConfig[] \| undefined | undefined | Several documents, with a picker to move between them. Takes precedence over url and spec. | | config | — | OpenishConfig \| undefined | undefined | Presentation options. Property only, because it is an object. | | basePath | base-path | string | '' | URL prefix this reference is mounted under, e.g. /docs. Only routing="history" reads it. | | routing | routing | RoutingMode | 'hash' | How the reference reads and writes the URL. | | selected | selected | string | '' | The active node id when routing="none". Ignored otherwise. | | colorScheme | color-scheme | ColorSchemePreference | 'auto' | Which scheme the reference renders in. | | credentials | — | Record<string, string> \| undefined | undefined | Credentials a host already has - after its own login, say. | | credentialStore | — | CredentialStore \| undefined | undefined | Where credentials should be kept between page loads, if anywhere. |

| Event | | |---|---| | openish-color-scheme-change | A descendant asked to switch schemes. Re-dispatched so the host can persist the choice and apply it to its own chrome; the reference itself needs nothing done for it, because color-scheme is reflected and @openish/theme matches the attribute. | | openish-client-change | The reader picked a different code-sample client. | | openish-navigate | The active node changed. Useful with routing="none". |

<openish-auth-form>

What the reader has to supply before an operation will answer.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | ui | — | OpenishUiState \| undefined | — | Presentation state. Provided by <openish-api-reference> through context. | | request | — | OpenishRequestState \| undefined | — | The server and credentials the reader has chosen. Provided through context. | | schemes | — | readonly SecurityEntry[] | [] | The schemes this operation accepts, from securitySchemesFor. |

| Event | | |---|---| | openish-auth-change | The reader signed in, signed out, or pasted a credential. |

<openish-callbacks>

The requests this operation will make back, behind a disclosure.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | callbacks | — | unknown | undefined | An operation's callbacks map, unresolved. |

<openish-code-block>

A block of code: highlighted, labelled, and copyable.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | code | code | string | '' | The source to show. Copied verbatim; only the rendering is highlighted. | | language | language | string | 'plaintext' | A highlight.js language name. Unknown ones render unhighlighted rather than failing. | | label | label | string | '' | What to call this block, e.g. curl. Falls back to the language, and to the title slot. | | status | status | string | '' | Shown in place of the code, for a block whose source has not arrived or could not be built. |

<openish-code-sample>

A ready-to-run request for one operation, in the reader's language.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | store | — | DocumentStore \| undefined | — | The parsed document. Provided by <openish-api-reference> through context. | | ui | — | OpenishUiState \| undefined | — | Presentation state. Provided by <openish-api-reference> through context. | | node | — | NavOperationNode | — | The operation to build a request for. | | request | — | ReturnType<typeof operationToHar> \| undefined | undefined | A request to render instead of deriving one. | | mediaType | media-type | string | '' | Which media type to send the body as, when this derives the request itself. | | variants | — | VariantChoices \| undefined | undefined | The variant branches picked in the request body's tree, so the snippet posts what it shows. | | accept | accept | string | '' | The media type to ask for back. |

| Event | | |---|---| | openish-client-change | The reader picked a different client. |

<openish-copy-button>

Putting something on the clipboard, and saying so.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | source | — | (() => string) \| undefined | — | What to copy, worked out when the button is pressed. | | action | action | string | 'Copy' | The visible word. Copy unless the thing being copied needs a different one. | | label | label | string | '' | What is being copied, added to the accessible name after the visible text. |

<openish-copy-markdown>

The section, on the clipboard, as a Markdown document.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | store | — | DocumentStore \| undefined | — | The parsed document. Provided by <openish-api-reference> through context. | | node | — | NavNode \| undefined | — | The section to copy. Undefined is the overview. |

<openish-disclosure>

A show/hide section.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | summary | summary | string | '' | The button's label. | | hint | hint | string | '' | A short qualifier after the label: how many rows are inside, or what a status code means. | | tone | tone | string | '' | Colours the label: success, info, danger. | | open | open | boolean | false | Whether the region is showing. Reflected, so CSS can follow it. |

| Event | | |---|---| | openish-toggle | The reader opened or closed it. detail is the new state. |

<openish-download>

Handing the reader the document the page was rendered from.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | store | — | DocumentStore \| undefined | — | The parsed document. Provided by <openish-api-reference> through context. | | ui | — | OpenishUiState \| undefined | — | Presentation state. Provided by <openish-api-reference> through context. |

<openish-markdown>

Renders a markdown string from the document - descriptions, summaries, tag prose.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | markdown | markdown | string | '' | The markdown to render. Sanitised before it reaches the DOM. | | headingOffset | headingOffset | number | 1 | Levels to push headings down by, so document prose nests under the page's own heading. | | headingIds | — | readonly string[] | [] | Ids to give the rendered headings, in document order - normally the NavTextNode ids that @openish/core minted from the same markdown, so a sidebar link has something to land on. |

<openish-model>

One schema from components.schemas.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | store | — | DocumentStore \| undefined | — | The parsed document. Provided by <openish-api-reference> through context. | | node | — | NavModelNode | — | The model to render. | | level | level | number | 1 | The heading level this section's own title takes. See <openish-operation>'s. |

<openish-operation>

One operation: what it is, what it takes, and what it answers with.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | store | — | DocumentStore \| undefined | — | The parsed document. Provided by <openish-api-reference> through context. | | ui | — | OpenishUiState \| undefined | — | Presentation state. Provided by <openish-api-reference> through context. | | node | — | NavOperationNode \| NavWebhookNode | — | The operation or webhook to render. | | level | level | number | 1 | The heading level this section's own title takes. |

<openish-overview>

The landing page: what the API is, where it lives, and how to authenticate.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | store | — | DocumentStore \| undefined | — | The parsed document. Provided by <openish-api-reference> through context. | | ui | — | OpenishUiState \| undefined | — | Presentation state. Provided by <openish-api-reference> through context. | | hash | hash | string | '' | A heading inside the prose to scroll to, passed down rather than read from location here. | | level | level | number | 1 | The heading level this section's own title takes. See <openish-operation>'s. |

<openish-parameters>

An operation's parameters, as one list of rows.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | parameters | — | readonly ParameterEntry[] | [] | Already merged: the path item's parameters plus the operation's. See collectParameters. |

<openish-request-body>

An operation's request body: what to send, and in which media type.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | requestBody | — | unknown | undefined | A Request Body Object, or a $ref to one. | | noExample | no-example | boolean | false | Document the schema without an example. | | examplesOnly | examples-only | boolean | false | Render only the example body, media type by media type. | | mediaType | media-type | string | '' | Which media type the operation is talking about. | | noMediaTabs | no-media-tabs | boolean | false | The caller is asking the media-type question somewhere else, so do not ask it here. | | continuesList | continues-list | boolean | false | This body's rows continue a list that began in another element. | | variants | — | VariantChoices \| undefined | undefined | The oneOf/anyOf branches picked in this body's tree, for the example to honour. |

| Event | | |---|---| | openish-media-type-change | |

<openish-request-form>

The inputs an operation takes, as one table of names and values.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | parameters | — | readonly ParameterEntry[] | [] | Already merged: the path item's parameters plus the operation's. | | values | — | Readonly<Record<string, string>> | {} | Current values, keyed "{in}:{name}". | | mediaTypes | — | readonly string[] | [] | The media types the request body declares, in document order. | | mediaType | mediaType | string | '' | | | body | body | string | '' | |

| Event | | |---|---| | openish-parameter-input | A field changed. Bubbles within the operation panel, not beyond. | | openish-body-input | The body or its media type changed. |

<openish-response-list>

An operation's responses.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | store | — | DocumentStore \| undefined | — | The parsed document. Provided by <openish-api-reference> through context. | | ui | — | OpenishUiState \| undefined | — | Presentation state. Provided by <openish-api-reference> through context. | | responses | — | unknown | undefined | A Responses Object: status codes to Response Objects. | | noExample | no-example | boolean | false | Document the response schemas without their examples. | | examplesOnly | examples-only | boolean | false | Render only the example bodies, status by status. | | status | status | string | '' | Which status the examples column is showing. Read in examples-only mode and nowhere else. | | mediaType | media-type | string | '' | The media type to show, when something above holds that choice too. | | noMediaTabs | no-media-tabs | boolean | false | The caller is asking the media-type question somewhere else, so do not ask it here. | | variants | — | VariantChoices \| undefined | undefined | Which shape the variant choices below belong to, and what they are. |

| Event | | |---|---| | openish-media-type-change | | | openish-status-change | |

<openish-response-view>

What the API actually answered.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | result | — | SendResult \| undefined | undefined | The outcome of the last send, or undefined before there has been one. |

<openish-schema>

A schema, rendered as a property tree that expands a level at a time.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | store | — | DocumentStore \| undefined | — | The parsed document. Provided by <openish-api-reference> through context. | | ui | — | OpenishUiState \| undefined | — | Presentation state. Provided by <openish-api-reference> through context. | | inherited | — | OpenishSchemaState \| undefined | — | The state an ancestor <openish-schema> left, or undefined at the top of a tree. | | provided | — | OpenishSchemaState | { depth: 0, seenRefs: new Set(), expandAll: false, anchors: new Map() } | What every schema rendered below this one sees: one level deeper, with this one's $ref added to the path. Public because it is the element's half of the recursion contract, and readable in a test without reaching through a shadow root. | | schema | — | unknown | undefined | The schema to render. May be a $ref; it resolves on access through the proxy. | | pointer | pointer | string | '' | The JSON pointer this schema was reached by, when it is not itself a $ref. | | hideHeader | hide-header | boolean | false | Skip the type line, for a caller that has already printed it - a property row does. | | inlineProperties | inline-properties | boolean | false | Show the property list without a disclosure, whatever the depth. | | where | where | string | '' | Where the values in this list travel, worn as a chip on every row at this level. | | variants | — | VariantChoices \| undefined | undefined | The oneOf/anyOf branches the reader has picked, so a rebuilt tab set can restore one. | | continuesList | continues-list | boolean | false | This tree's rows continue a list begun in another element - the parameters beside a body. | | scope | scope | string | '' | Which shape on the page this tree describes - request, or response:404. | | path | path | unknown | VARIANT_PATH_ROOT | Where this tree sits inside the shape named by scope, in variant-path.ts's spelling. |

| Event | | |---|---| | openish-variant-change | |

<openish-schema-preview>

A schema and an example of it, side by side.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | schema | — | unknown | undefined | The schema to render beside its example. | | label | label | string | '' | A caption above the schema, e.g. the media type this one describes. | | mediaType | media-type | string | 'application/json' | The media type the example is an example of. Decides both the syntax and the colours. | | example | — | unknown | undefined | One example the author supplied, for a caller that has only one to give. | | examples | — | readonly MediaTypeExample[] | [] | Every example the author wrote, in document order. More than one becomes a picker. | | scope | scope | string | '' | Which shape on the page this is, and the variant branches the reader picked in its tree. | | variants | — | VariantChoices \| undefined | undefined | | | noExample | no-example | boolean | false | Hide the example block, for callers that show one of their own. | | noSchema | no-schema | boolean | false | Hide the property tree, keeping only the example. | | hideHeader | hide-header | boolean | false | Skip the tree's own type line. Passed straight through to <openish-schema>. | | where | where | string | '' | The chip every row of this tree wears. Passed straight through; see the note on <openish-schema>. | | continuesList | continues-list | boolean | false | These rows continue a list begun in another element. Passed straight through. |

<openish-search>

Search over the navigation tree.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | store | — | DocumentStore \| undefined | — | The parsed document. Provided by <openish-api-reference> through context. | | sources | — | OpenishSourcesState \| undefined | — | Every document on offer, and which of them are loaded. Provided through context. | | ui | — | OpenishUiState \| undefined | — | | | open | open | boolean | false | Whether the dialog is showing. Set it; the element does the rest. | | hotkeys | — | unknown | new HotkeyController(this, () => [{ key: this.ui?.config.searchHotKey \|\| '/' }, { key: 'k', modifier: true }], () => { this.#show(deepActiveElement()) }) | The shortcuts that open this dialog. Public because it is part of the element's behaviour. |

<openish-section-index>

What is inside a section, as links, in tabs.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | store | — | DocumentStore \| undefined | — | The parsed document. Provided by <openish-api-reference> through context. | | node | — | SectionParent | — | The tag or container whose contents this indexes. |

<openish-section-list>

A list of links to sections, built to the design system's list item.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | ui | — | OpenishUiState \| undefined | — | Presentation state. Provided by <openish-api-reference> through context. | | items | — | readonly NavNode[] | [] | The nodes to list, in the order they should read. | | label | label | string | '' | An accessible name for the list, when it is not already labelled by a tab. |

<openish-server-select>

Which server a request goes to, and what its {variables} are.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | store | — | DocumentStore \| undefined | — | The parsed document. Provided by <openish-api-reference> through context. | | request | — | OpenishRequestState \| undefined | — | The server and credentials the reader has chosen. Provided through context. |

| Event | | |---|---| | openish-server-change | The reader picked a server or filled in one of its variables. |

<openish-sidebar>

The navigation tree, rendered as a virtualised list.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | store | — | DocumentStore \| undefined | — | The parsed document. Provided by <openish-api-reference> through context. | | ui | — | OpenishUiState \| undefined | — | Presentation state. Provided by <openish-api-reference> through context. | | sources | — | OpenishSourcesState \| undefined | — | Every document on offer, so the picker appears only when there is a choice to make. |

<openish-sidebar-item>

One row of the navigation tree.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | ui | — | OpenishUiState \| undefined | — | Presentation state. Provided by <openish-api-reference> through context. | | node | — | NavNode | — | The node this row names. | | level | level | number | 1 | How deep the row sits, 1-based. Rendered as indentation and as aria-level. | | hasChildren | has-children | boolean | false | Whether this node has anything under it, which decides between a toggle and a spacer. | | expanded | expanded | boolean | false | Whether it is currently open. Decided by <openish-sidebar>, never here. |

<openish-source-select>

The document picker, for a reference configured with several sources.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | sources | — | OpenishSourcesState \| undefined | — | Every document on offer, and which of them are loaded. Provided through context. |

| Event | | |---|---| | openish-source-change | The reader picked a different document. Carries its slug. |

<openish-table>

A data table.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | columns | — | readonly string[] | [] | Column headings, in order. The first column is the row header. | | rows | — | readonly OpenishTableRow[] | [] | Rows, keyed. A cell may be a string or a template. | | caption | caption | string | '' | The table's accessible name, e.g. "Query parameters". | | captionVisible | caption-visible | boolean | false | Show the caption. Off by default: the caller usually renders a heading above the table. |

<openish-tabs>

A tab set.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | tabs | — | readonly OpenishTab[] | [] | The tabs, in order. Each carries a callback for its panel, rendered only when selected. | | label | label | string | '' | Accessible name for the tab list, e.g. "Response status codes". | | selected | selected | string | '' | The tab to start on. The reader's own choice takes over from there. |

| Event | | |---|---| | openish-tab-change | The reader picked a tab. detail is its id. |

<openish-tag-section>

The landing for a tag, a group, or any other node that has children: its prose on one side, and an index of what is inside it on the other.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | store | — | DocumentStore \| undefined | — | The parsed document. Provided by <openish-api-reference> through context. | | node | — | SectionParent | — | The tag or group whose children this indexes. | | level | level | number | 1 | The heading level this section's own title takes. See <openish-operation>'s. |

<openish-try-it>

Sending the request the page describes.

| Property | Attribute | Type | Default | | |---|---|---|---|---| | store | — | DocumentStore \| undefined | — | The parsed document. Provided by <openish-api-reference> through context. | | ui | — | OpenishUiState \| undefined | — | Presentation state. Provided by <openish-api-reference> through context. | | request | — | OpenishRequestState \| undefined | — | The server and credentials the reader has chosen. Provided through context. | | node | — | NavOperationNode | — | The operation this panel sends. | | open | open | boolean | false | Whether the client is showing. Set it; the element does the rest. | | mediaType | media-type | string | '' | Which media type the operation is talking about, when something above owns that choice. | | variants | — | VariantChoices \| undefined | undefined | The variant branches picked in the request body's tree. | | accept | accept | string | '' | The media type to ask for back, from the response the examples column is showing. |

| Event | | |---|---| | openish-media-type-change | |