Reference & disclosureExplore · Adapt · Compose
Type Definition
Keep the purpose of a contract visible while its implementation stays one click away. Type Definition brings a readable heading, exact identifier, contextual metadata and an accessible disclosure into one compact reference card. Use it for component props, configuration shapes and event payloads without coupling your interface to a syntax highlighter or documentation router. Separate a contract’s purpose from its implementation details. Keep the summary readable and reveal complete source only when the reader needs it. Explore the live examples, inspect their source and choose the composition that fits your interface before connecting it to your application's data.
The examples use @/components/kamod-ui/type-definition in a Preact project. Follow the live result and its source together: compare supported options in the API reference, refine presentation with the component styles guide, and use shared theme tokens for consistent colors and surfaces. Preserve keyboard behavior and meaningful labels as you replace the sample content.
In this guide 7 sections
Installation
Import TypeDefinition from @kamod-ch/ui or @kamod-ch/ui/type-definition. It composes Kamod’s existing Collapsible behavior and uses semantic theme tokens. No parser, clipboard library or router is required. Keep the shared stylesheet configured using the Theming & Tailwind guide before rendering the examples.
pnpm add @kamod-ch/uiThe @/components/kamod-ui/… imports in these examples refer to local source files. Configure that alias when copying source, or use the corresponding exports from @kamod-ch/ui when installing the package. Connect the global theme CSS and Tailwind source detection before your first render.
Usage
Give title a human-readable purpose and typeName the exact identifier readers will find in source. Put a short explanation in description, optional field context in metadata, and the complete definition in children. The card starts collapsed; use defaultOpen for an initially visible definition or pair open with onOpenChange when a prop table, search result or permalink needs to reveal it. Expansion does not update the URL or move focus automatically.
Choose the right boundary. Use Collapsible for a general disclosure, Accordion for a coordinated question-and-answer list, and this component when the summary belongs to a named contract. See the Application Shell brand reference for a complete integration with source links and required-field documentation.
import { TypeDefinition } from "@/components/kamod-ui/type-definition";Choose a complete composition from the examples below; required child components and props vary by pattern.
Component examples & variants
Explore Type Definition in different contexts, from the starting pattern to the compositions below. Begin with Summary and source, then compare the examples that match your content, state and layout. These are working patterns to adapt, not a list of interchangeable variant values: check the API reference before using a prop or combining behaviors. Look at the surrounding labels, supporting text and spacing as well as the component itself.
Read the result and its implementation together. Use each showcase’s Code view to inspect imports and composition, or its Prompt view to prepare a setup or adaptation brief. Try the narrow preview and local theme controls before connecting real data, and use Reset to return an example to its initial state. Keep layout changes in class utilities where appropriate; follow the component styles guide for hierarchy and the theming guide for shared surfaces and colors. The accessibility notes explain what to preserve when making those changes.
Summary and source
Start with a concise description that stays visible when the definition is closed. The muted disclosure bar makes the next action recognizable in both states. Its stronger hover treatment and visible keyboard focus work independently of the surrounding page theme.
import { TypeDefinition } from "@kamod-ch/ui";
export const Example = () => (
<TypeDefinition title="Navigation item" typeName="NavigationItem"
description="A label and destination for one navigation entry.">
<pre><code>{`type NavigationItem = { label: string; href: string; disabled?: boolean };`}</code></pre>
</TypeDefinition>
);Metadata and field documentation
Keep essential context outside the disclosure. Required fields and a small status badge help readers understand a contract before opening it, while source, field explanations and related links can share the expanded content. The header action remains separate from the disclosure so nested buttons are unnecessary.
Keep metadata factual. A required-field list describes your contract; the card does not inspect TypeScript or validate inputs. Supply headerAction for a badge or source link beside the heading, and put longer explanations in the definition content. Follow the source declarations to see the exact slot types.
Reveal from another control
Use controlled state when multiple controls need to address the same definition. A single state owner keeps external actions, the disclosure label and aria-expanded synchronized. Treat defaultOpen as an initial value only; do not switch between controlled and uncontrolled modes after mounting.
Link, reveal, then navigate. Keep a stable headingId when linking from a props table. Your application can set open before scrolling to that anchor. If you close a card from an external control while focus is inside it, return focus to its trigger. Read the accessibility guidance before adding custom navigation or asynchronous content.
Compact contract list
Use compact density for short, related declarations. Each card keeps an independent open state and generated IDs, so expanding one never closes its neighbor. Choose headingLevel to fit the surrounding document hierarchy and retain descriptive type names even when the source is brief.
Use density consistently. Compact cards work well for several small contracts in a vertical list. The disclosure keeps a minimum height of 2.75rem in both densities. Prefer the default spacing for longer summaries and richly documented definitions; use semantic theme colors for any local adjustments.
Props and data
Configure Type Definition using the contracts below. Read the documented options alongside the source definitions to understand which values your application supplies and which details the component owns. Start with a prop or helper, then follow its type link to inspect the declaration without leaving the page.
Props, slots and variants for this component.
TypeScript source at build time. Props inherited through HTMLAttributes, Omit or variant helpers remain references in those declarations; their fields are not flattened here. Match the reference to your installed version, and check a package’s exports before writing an import type. A type exported by a source file is not necessarily re-exported by @kamod-ch/ui.TypeScriptComponent props
? means a field can be omitted; it does not promise a fallback value. Existing documented defaults remain alongside the descriptions. For callbacks, check the argument and return types before connecting your own state or services.Type Definition
Type Definition component props and accepted values.
| Prop / type | Description |
|---|---|
title | Readable heading describing the contract. May include an application-owned permalink. Usage requirementRequired |
typeName | Exact source identifier; shown in monospace and appended to the disclosure's accessible name. Usage requirementRequired |
description | Summary below the type name. Remains visible in both disclosure states. Documented default |
metadata / headerAction | Optional summary slots: metadata follows the description; headerAction sits beside the heading and wraps when necessary. Documented default |
children | Expanded definition content. Plain code, highlighted source, field docs and copy actions are supplied by the caller. Children unmount on collapse, so keep persistent editor state outside the card. Documented default |
open / onOpenChange | Controlled disclosure. The callback reports user toggles; your parent must update open. Programmatic changes to open do not invoke the callback. Documented default |
defaultOpen | Initial uncontrolled state. Ignored when open is supplied. Documented default |
headingId / headingLevel | Heading anchor and semantic level. Explicit heading IDs must be unique; the trigger and panel derive their IDs from it. Documented default |
density | Reduces summary, trigger and content padding without shrinking the minimum disclosure target height. Documented default |
expandLabel / collapseLabel | Visible disclosure labels. Translate both together; the exact type name is appended to their accessible name. Documented default |
class / triggerClass / contentClass | Utility overrides for the root card, disclosure button and inner content respectively. Preserve focus visibility, contrast and minimum target size. Documented default |
Data type reference
Expand a card to inspect and copy the exact declaration. The code header identifies its repository file; follow imported or inherited types in the implementation source when you need the complete dependency chain. Required-field summaries cover fields declared directly in that type. Source-only helpers and inferred schema outputs describe the local implementation, not additional props you can pass to every component.
TypeDefinitionPropstitle, typeNameAccessibility
Build the complete interaction, including the parts outside Type Definition. The notes below distinguish the current implementation from the labels, content and behavior your application supplies. Start with the live preview, check the props and data reference, and test the finished composition with real content rather than assuming that an unchanged visual example covers every use case.
Built-in behavior and defaults
Type Definition pairs a persistent summary with a real disclosure button. aria-expanded follows the actual state and aria-controls names the content panel. Decorative code and chevron icons are hidden from assistive technology. The card starts collapsed unless defaultOpen or controlled open says otherwise. Source children are mounted only while expanded, so hidden copy buttons are not extra tab stops.
Labels and relationships
Use a readable title and an exact typeName: the first explains the purpose; the second distinguishes similarly named actions in a screen-reader button list. The visible action label is included in the accessible name, followed by the type identifier. Translate expandLabel and collapseLabel together. Generated IDs keep separate cards independent; explicitly supplied headingId values must be unique across the document. Match headingLevel to the surrounding sections rather than choosing a heading for its font size.
Match the surrounding heading hierarchy. This section already has an h2, so the card uses h3. Generated IDs are sufficient when there are no external permalink targets.
import { TypeDefinition } from "@kamod-ch/ui";
export const Reference = () => <section aria-labelledby="payloads">
<h2 id="payloads">Event payloads</h2>
<TypeDefinition title="Selection change" typeName="SelectionChange" headingLevel={3}
description="The selected item's stable identifier.">
<pre><code>{`type SelectionChange = { id: string };`}</code></pre>
</TypeDefinition>
</section>;Keyboard and focus
Tab reaches the disclosure and any ordinary links in its summary. Enter or Space toggles it using native button behavior, without submitting an enclosing form. Opening leaves focus on the trigger; the next Tab can enter controls supplied in the expanded content. This is a disclosure, not a composite list with arrow-key navigation. A parent can update controlled open from another action, but must also handle URL changes, scrolling or focus movement when its workflow needs them.
States and integration details
The muted bar is visible whether the card is open or closed; stronger hover color is supplementary, while the label and chevron communicate state. Preserve the visible focus outline when overriding classes. At narrow widths, long identifiers wrap and metadata can move below the heading; code blocks supplied by the caller should scroll within their own width. Children unmount on collapse, so persistent editor state belongs above the card. If an external action closes a card while focus is inside it, move focus to its trigger before hiding that content.
Verify the complete interaction
Check behavior as well as markup. Work through these scenarios in the application where the component will be used. Automated checks can help find structural problems; also review the reading experience with a screen reader, keyboard focus and the actual feedback from your application.
- Activate both disclosure states using Enter and Space inside a form; verify the form does not submit and the accessible name includes the exact type identifier.
- Render multiple cards, including repeated titles, and inspect unique trigger/panel IDs. Tab through an expanded card, close it and confirm hidden controls are no longer reachable.
- Try long identifiers, translated action labels and linked metadata at 320px and enlarged text in both themes. Verify hover and focus remain distinct and the expanded source stays inside the card.
Recheck the result after changing theme tokens, translations or class overrides. Include text enlargement, narrow layouts and reduced-motion settings where animation is present. Inspect the component source when a behavior differs from your expectation; a role or state attribute does not implement keyboard interaction by itself.
For background, read the WAI-ARIA authoring guidance and keyboard interface guidance. These explain the patterns; verify browser and assistive-technology behavior for the implementation and audience you actually support.
Build it into your interface
Use the Type Definition examples as a starting point, then review the behavior in the context of your own screen. Layout, state and content should work together.
Connect the behavior
Use title for the purpose and typeName for the exact identifier. Keep required-field metadata tied to the real declaration. Supply code rendering as children, and let one parent own open state when links or search results must reveal a definition.
Copy the composition, then connect its intent. Replace sample records and callbacks with your own data flow. For options such as value, defaultValue, open or onChange, use only those documented in this component's API; different components expose different contracts.
Give each piece of state one owner. Keep a temporary selection inside the interface when nothing else needs it; lift shared values into a parent when other controls depend on them. Read the prop reference before combining controlled values with defaults. A default normally initializes a control; it is not a substitute for updating its current value.
Connect requests in an event handler or your application’s data layer, never as a side effect of rendering. Keep pending, completed and failed outcomes distinct, preserve useful input after an error, and offer a clear recovery action. If the integration subscribes to an external source, remove that subscription when its owner unmounts; cancel or ignore obsolete requests so an earlier response cannot replace newer results.
Start with the live preview, then exercise the same interaction with your actual data. The type definitions describe accepted values; they do not implement persistence, navigation or server-side validation for you. Keep those responsibilities in the application that composes the UI.
Refine the presentation
Let a parent own the surrounding spacing. Keep related elements together with gap and use semantic surface/foreground pairs so the composition follows the active theme. The wrapper below changes the surrounding layout without assuming extra props on Type Definition.
import type { ComponentChildren } from "preact";
export function ExampleSurface({ children }: { children: ComponentChildren }) {
return (
<div class="grid min-w-0 gap-4 rounded-lg border border-border bg-card p-4 text-card-foreground sm:p-6">
{children}
</div>
);
}Put the chosen example inside ExampleSurface, then refine supported variants and sizes using the API above. For application-wide changes, adjust theme tokens instead of repeating fixed colors. See Component styles for hierarchy, density and focus treatments.
Review the complete interaction
- Open and close with Enter and Space; confirm hidden source and copy actions leave the tab order.
- Try long type names and rich metadata at narrow widths in both themes without clipping the heading or focus ring.
- Verify external reveal actions update the same open state, and use unique headingId values for permalink targets.
The preview's narrow control changes its container width. Also resize the browser when checking viewport-based Tailwind utilities such as sm: and md:, and test overlays in the full page where their portals render.
Compose a complete interface
Type Definition is one part of the interaction. Choose companion components for the information or actions that still need a place on the screen. The references below are suggestions to compose deliberately, not extra dependencies you must add to every example.
Keep one source of truth for the operation and let each component communicate a different part of it. For example, waiting, no results and failure need different explanations. Avoid showing contradictory states together, and keep recovery actions close to the message that explains them.
Start with the smallest composition that explains the task. Browse the component library for individual controls or the block collections for complete layouts. Reuse shared theme tokens so these pieces feel consistent in light and dark mode.
Sources & design references
Follow Type Definition from its implementation to the ideas behind your own composition. Start with the local API, explore a visual direction, then bring the result back to your app’s shared styles.
Bring it back to your app
A reference becomes useful when it fits your real content. Work through these decisions in order:
- Keep the behavior grounded. Start with the interactive examples, then connect your data and callbacks using the integration guidance. Preserve labels, keyboard access and disabled states as you change the presentation.
- Make the styling repeatable. Use the styles guide for local
classadjustments and theming documentation for shared color decisions. Keep semantic surface and foreground pairs together in both light and dark mode. - Check the complete screen. See how components combine in the block collections, then try long labels, loading states and narrow layouts in your own composition. The Theme Toggle guide helps you expose a scheme switch in the finished interface.