grassroot
Install

DocsAPI referenceHeadlesstypes

types headless API

The core connector and vanilla mount are always visible. Use the framework choice to inspect native composition, props, outputs, context and hooks for the selected adapter.

@grassroot/ui-headless-core/types

Core connector and vanilla API

6 exports
View source packages/ui-headless/core/src/types.ts

CommandRunner

type

Resolves UI command intents through a mounted part scope. Unresolvable commands (unmounted part, SSR) are silent no-ops — machines never learn about the DOM. Announcements are delegated to the provided announcer.

DeclarationView source
CommandRunnerts
type CommandRunner = (command: UiCommand, scope: PartScope, options?: {
  announce?: (key: string, params: {
    readonly [key: string]: string | number | null;
  }, politeness: "polite" | "assertive") => void;
}) => void;

HiddenInputDescriptor

interface

Hidden form input descriptor (framework adapters render it).

DeclarationView source
HiddenInputDescriptorts
interface HiddenInputDescriptor {
  readonly name: string | undefined;
  readonly value: string;
  readonly disabled: boolean;
  readonly required: boolean;
  /** Functional visually-hidden styling only — no aesthetic values. */
  readonly style: {
    readonly [property: string]: string;
  };
}
Name
Kind
Type
Requirement
Description
disabled
property
boolean
required
—
name
property
string | undefined
required
—
required
property
boolean
required
—
style
property
{ readonly [property: string]: string; }
required
Functional visually-hidden styling only — no aesthetic values.
value
property
string
required
—
Name
disabled
Kind
property
Type
boolean
Requirement
required
Description
—
Name
name
Kind
property
Type
string | undefined
Requirement
required
Description
—
Name
required
Kind
property
Type
boolean
Requirement
required
Description
—
Name
style
Kind
property
Type
{ readonly [property: string]: string; }
Requirement
required
Description
Functional visually-hidden styling only — no aesthetic values.
Name
value
Kind
property
Type
string
Requirement
required
Description
—

MergeProps

type

The locked mergeProps rule (platform plan, verbatim): consumer handlers run first; `preventDefault()` suppresses the internal handler; refs are composed; class/style values are merged; machine-owned IDs and ARIA references cannot be silently overwritten. Signature: internal (machine-owned) props first, consumer overrides second. Returns one merged bag. `id`, `aria-*` relationship attributes (`aria-labelledby`, `aria-describedby`, `aria-controls`, `aria-activedescendant`) from the internal bag win over consumer values; a consumer attempt to override them is reported via the optional `onProtectedOverride` hook (development aid) and ignored.

DeclarationView source
MergePropsts
type MergeProps = (internal: PartProps, consumer: PartProps, options?: {
  onProtectedOverride?: (key: string) => void;
}) => PartProps;

PartProps

interface

Framework-neutral prop bag. Event handlers are `on`-prefixed functions; `ref` is a composition-ready callback; everything else is a plain attribute/property value.

DeclarationView source
PartPropsts
interface PartProps {
  readonly [key: string]: unknown;
}

PartScope

interface

Core platform contracts for `@grassroot/ui-headless-core` — frozen by the orchestrator before implementation (phase 3). Implementations must satisfy these shapes exactly; changing this file is a contract change and stops dependent work. The platform plan's explicit part scope. No global getElementById lookups.

DeclarationView source
PartScopets
interface PartScope {
  /** Stable, SSR-safe id for a part (optionally keyed, e.g. items). */
  id(part: string, key?: string): string;
  /** Ref callback that registers/unregisters the part's element. */
  register(part: string, key?: string): (node: Element | null) => void;
  /** Scoped lookup — never a document-wide query. */
  get(part: string, key?: string): Element | null;
  /**
   * Subscribe to registration changes. The returned cleanup is idempotent;
   * registration callbacks invoke listeners only after the scoped registry
   * has actually changed.
   */
  subscribe(listener: () => void): () => void;
  /** The root the scope is mounted under (document, shadow root or element). */
  root(): Document | ShadowRoot | HTMLElement | null;
}
Name
Kind
Type
Requirement
Description
get
method
(part: string, key?: string) => Element | null
required
Scoped lookup — never a document-wide query.
id
method
(part: string, key?: string) => string
required
Stable, SSR-safe id for a part (optionally keyed, e.g. items).
register
method
(part: string, key?: string) => (node: Element | null) => void
required
Ref callback that registers/unregisters the part's element.
root
method
() => Document | ShadowRoot | HTMLElement | null
required
The root the scope is mounted under (document, shadow root or element).
subscribe
method
(listener: () => void) => () => void
required
Subscribe to registration changes. The returned cleanup is idempotent; registration callbacks invoke listeners only after the scoped registry has actually changed.
Name
get
Kind
method
Type
(part: string, key?: string) => Element | null
Requirement
required
Description
Scoped lookup — never a document-wide query.
Name
id
Kind
method
Type
(part: string, key?: string) => string
Requirement
required
Description
Stable, SSR-safe id for a part (optionally keyed, e.g. items).
Name
register
Kind
method
Type
(part: string, key?: string) => (node: Element | null) => void
Requirement
required
Description
Ref callback that registers/unregisters the part's element.
Name
root
Kind
method
Type
() => Document | ShadowRoot | HTMLElement | null
Requirement
required
Description
The root the scope is mounted under (document, shadow root or element).
Name
subscribe
Kind
method
Type
(listener: () => void) => () => void
Requirement
required
Description
Subscribe to registration changes. The returned cleanup is idempotent; registration callbacks invoke listeners only after the scoped registry has actually changed.

UiCommand

type

UI command intents resolved by the headless command runner (Select set).

DeclarationView source
UiCommandts
type UiCommand = {
  readonly type: "FOCUS_PART";
  readonly part: string;
} | {
  readonly type: "FOCUS_ITEM";
  readonly key: string;
} | {
  readonly type: "SCROLL_ITEM_INTO_VIEW";
  readonly key: string;
} | {
  readonly type: "ANNOUNCE";
  readonly key: string;
  readonly params: {
    readonly [key: string]: string | number | null;
  };
  readonly politeness: "polite" | "assertive";
};

Framework adapters

Each panel keeps its adapter's public vocabulary. React compound exports, Vue composables, standalone Angular declarations, Svelte components, and Solid hooks stay native to their framework.

This entry is core-only. No framework adapter package ships for types yet — mount it through the vanilla API above.