Interactive playgrounds

A playground turns a component you own into something readers can explore. You register it once, describe the inputs worth changing, and place it with one line of Markdown. Doqs supplies the controls, preview, event list, reset, widths, expanded view and code panel.

It is not MDX and it compiles nothing in the browser: the component is yours, built with your application, and Markdown never contains Angular templates.

Demo or playground?

	::demo[id]	::playground[id]
Renders	Your component, alone	Your component inside a playground
Controls, events, code	You build them	Doqs provides them
Registered under	demos	playgrounds

Both coexist, and existing demos are unchanged.

Register

const doqConfig = defineDoqConfig({
  ...doqPaths,
  playgrounds: {
    'button-basic': {
      component: ButtonPlayground,
      title: 'Button',
      controls: [
        { input: 'variant', kind: 'select', label: 'Variant', initial: 'solid', options: [{ label: 'Solid', value: 'solid' }, { label: 'Outline', value: 'outline' }] },
        { input: 'disabled', kind: 'boolean', label: 'Disabled' },
      ],
      outputs: [{ event: 'pressed', label: 'Pressed' }],
      code: [{ label: 'Template', language: 'html', code: (values) => formatDoqUsage('app-button', values) }],
    },
  },
});

Keep this in the file that imports your components, not in doq.paths.ts, which must stay free of Angular components. An invalid registry throws one readable error when the configuration is defined.

Place

## Playground

::playground[button-basic]

The directive follows the ::demo[id] rules: alone in its paragraph, id of letters, digits, _ and -, literal inside code blocks, lists, quotes and tables. An unregistered id renders an accessible notice.

Controls

kind	Input it drives	Notes
boolean	boolean	Starts false unless initial says otherwise.
string	string	Without initial the input stays unbound until the reader types.
number	number	Optional min, max, step. Invalid or out-of-range text is rejected with a message and the last valid value stays bound.
select	A finite set	Options carry their own value, so numbers and booleans work. Doqs never invents options.

input is the public binding name: the alias if the input declares one. Signal inputs, required inputs, aliased inputs, input transforms and classic @Input all work, because Doqs binds them with Angular's own createComponent bindings. Set required: true on a control whose input is required: it then needs an initial and can never be emptied.

Outputs

List the outputs worth watching by their public name. Each emission appears in a bounded list of the latest 20 events; payloads are summarised safely (no circular structures, DOM objects or values under keys like password or token). For a model(), list <name>Change. Events stay in the page: they are never logged, indexed or sent anywhere.

Directives

Doqs creates components, not directives. To document an attribute directive, write a small standalone component that applies it and register that, as the live example below does for Angular Movement.

Code examples

Each entry is either static text or a function of the current valid values. formatDoqUsage(selector, values, { attributes, text }) renders template usage with the right escaping; the text on screen is exactly what the copy button copies. A static example does not follow the controls, so label it accordingly.

Preview, expand and reset

• Widths. Responsive, Mobile (320px) and Tablet (768px) resize the preview container, not the browser. Pass previewSizes to customise them or false to hide them. Changing width never recreates the component.
• Expand. The preview moves into a native modal dialog: same instance, same state, Escape closes it and focus returns to the button. Overlays a component appends to <body> render beneath the dialog.
• Reset. Restores every control, clears the events and recreates the component, so internal state starts over. Changing a control never recreates it.

Server rendering

The preview is created during rendering, so a component that renders on the server is in the prerendered HTML, with the controls at their initial values, and hydrates in place. A component that touches window or document must guard them as in any SSR application.

Styling

The playground uses native controls and the existing --host-docs-* tokens. Two optional tokens adjust it: --host-docs-playground-surface and --host-docs-playground-preview.

Live example

Angular Movement's moveEnter directive, wrapped in a component that Volt UI's button replays. Change the controls; every change replays the animation.

Limits

• Controls cover booleans, strings, numbers and finite choices, not object graphs.
• Controls are written by hand. Doqs does not infer them from the API reference.
• Code examples are text you provide; Doqs does not import source files.