gik-components 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nsreehari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,373 @@
+# @gik-ai/components
+
+Public, self-describing declarative components for GIK React hosts.
+
+The package has five public layers:
+
+- `@gik-ai/components/primitives`: domain-neutral UI mechanics such as chart, collection board, form,
+  editable table, growing container, infinite canvas, source viewer, and timer button.
+- `@gik-ai/components/semantic`: domain-neutral information roles and relationships such as event
+  series, processes, measures, narratives, evidence, decisions, and relationship sets.
+- `@gik-ai/components/security`: security-domain contracts such as adversarial attack paths.
+- `@gik-ai/components/software`: software-domain contracts such as source findings and comparisons.
+- `@gik-ai/components/fluent`: reusable Fluent 2 controls that retain `fluent:*` capability names:
+  badges, buttons, inputs, personas, spinners, tabs, tags, lists, tables, and data grids. Presentation choices are closed
+  variants backed by native Fluent props; icon buttons are `fluent:button` variants.
+
+`@gik-ai/components` re-exports every layer and aggregate `component*` registries for convenience.
+New consumers should import narrow subpaths and register each selected `*ComponentViews` registry
+under its matching provider alias. Domain catalogs are opt-in rather than ambient.
+
+The package uses Fluent 2 React v9 through `@fluentui/react-components`. It assumes the host wraps
+rendering in a Fluent `FluentProvider`; it does not create a theme or introduce a semantic provider.
+Components use Fluent theme tokens and contain no independent palette.
+
+Every component accepts native root `className` and `style` props. Internal styles use `makeStyles`;
+root classes use Fluent `mergeClasses` with the consumer class last so callsite Griffel rules can
+override component defaults. Use exported slot props for nested customization when a component
+declares slots. The package does not expose a synthetic or Fluent v8-style `styles` bag.
+
+Each component exports one definition containing its renderer, closed props schema, recognized
+semantic tokens, closed variants where applicable, emitted events, slots, agent-facing authoring
+guidance, validator, and trial materializer.
+
+Component-private interaction mechanics remain inside the component. Blueprint state represents
+application behavior and cross-Cell coordination, not every local visual toggle. Components such
+as `primitive:pane-with-trigger` therefore own their open/closed state by default and may emit
+optional observation events. Use controlled props only when application behavior genuinely needs
+to coordinate that state across components.
+
+```ts
+import {
+  semanticComponentDefinitions,
+  semanticComponentViews,
+} from "@gik-ai/components/semantic";
+
+import {
+  primitiveComponentViews,
+} from "@gik-ai/components/primitives";
+
+import {
+  fluentComponentViews,
+} from "@gik-ai/components/fluent";
+
+import { securityComponentViews } from "@gik-ai/components/security";
+import { softwareComponentViews } from "@gik-ai/components/software";
+
+const eventSeries = semanticComponentDefinitions["event-series"];
+const guidance = eventSeries.describe();
+const defaultVariant = guidance.defaultVariant;
+const variants = guidance.variants;
+const schema = eventSeries.getSchema();
+const report = eventSeries.validate(eventSeries.materializeTrial().props);
+```
+
+## React adapters
+
+The root package exports `GikComponent` as the typed convenience API for rendering one package
+component without constructing a `ResolvedNode`:
+
+```tsx
+import { GikComponent } from "@gik-ai/components";
+
+<GikComponent
+  kind="primitive:chart"
+  spec={{
+    kind: "bar",
+    title: "Requests",
+    fields: { label: "hour", value: "count" },
+  }}
+  data={[{ hour: "09:00", count: 12 }]}
+  variant="compact"
+  onEvent={({ name, payload }) => dispatch(name, payload)}
+/>
+```
+
+The public props are:
+
+- `kind`: required closed capability ID, such as `primitive:chart` or `semantic:event-series`.
+- `spec`: component-specific declarative specification, assigned to the component's `spec` prop.
+- `data`: generic component data, assigned to the selected definition's declared `dataProp`.
+- `variant`: an optional declared presentation variant.
+- `componentProps`: additional component-specific props. Explicit `spec`, `data`, and `variant`
+  values take precedence.
+- `children`: content for components that declare a `children` slot.
+- `id`: optional projection-node identity. A React-generated identity is used when omitted.
+- `onEvent`: receives declared component events as `{ kind, name, payload, actorId }`.
+
+`GikComponent` validates the assembled props against the selected definition before rendering.
+It has no JSON-string or declarative-effect props; non-runtime React hosts may translate `onEvent`
+into their own dispatcher.
+
+Use `GikComponentDeclarative` when the input is one canonical JSON `DocNode`. The adapter creates
+the minimal package vocabulary and program wrapper internally, then runs the node through the GIK
+kernel. `GikComponentRuntimeProvider` supplies initial state and native effect handlers separately
+from the JSON declaration:
+
+```tsx
+import {
+  GikComponentDeclarative,
+  GikComponentRuntimeProvider,
+} from "@gik-ai/components";
+
+<GikComponentRuntimeProvider
+  state={{ report: { points } }}
+  effectHandlers={{ handleSelection }}
+>
+  <GikComponentDeclarative
+    nodeJson={{
+      id: "request-chart",
+      capability: "primitive:chart",
+      props: { spec: chartSpec },
+      edges: {
+        read: { points: "report.points" },
+        on: {
+          select: [{ do: "invoke", args: { tool: "handleSelection" } }],
+        },
+      },
+    }}
+  />
+</GikComponentRuntimeProvider>
+```
+
+`nodeJson` accepts a JSON value and validates that it is a canonical projected node. It supports
+the standard node edges, including `read`, `readExpr`, `gate`, `write`, `on`, `react`, and
+`children`. The provider also accepts shared `contexts` and an optional projection-provider
+resolver. Referenced `invoke` tools are declared as vocabulary externals and must have matching
+provider handlers.
+
+Projection providers remain explicit. A host registers each layer under a provider name, and a
+bundle imports only the capabilities it uses. Nothing is ambient.
+
+Application-owned component layers must provide both their projection views and capability
+descriptors. Pass the view resolver through `resolveProvider` and the matching descriptor resolver
+through `resolveCapabilityDescriptors`:
+
+```tsx
+<GikComponentRuntimeProvider
+  resolveProvider={(from) => from === "finance" ? financeComponentViews : undefined}
+  resolveCapabilityDescriptors={(from) =>
+    from === "finance" ? financeComponentCapabilities : undefined}
+>
+  <GikComponentDeclarative
+    nodeJson={{
+      id: "report",
+      capability: "finance:report",
+      props: { result },
+    }}
+  />
+</GikComponentRuntimeProvider>
+```
+
+The descriptor resolver is consulted only after the built-in Fluent, primitive, semantic,
+security, and software catalogs. Unknown capabilities still fail bundle construction. Supplying a
+custom view without its descriptor is intentionally insufficient because the generated vocabulary
+must contain the component's actual props, data, slot, and event contract.
+
+## Agent authoring kit
+
+Generate instructions and tools for only the components an agent may author. Every catalog has a
+parallel, layer-specific API:
+
+```ts
+import { getSemanticComponentAgentKit } from "@gik-ai/components/semantic";
+import { getPrimitiveComponentAgentKit } from "@gik-ai/components/primitives";
+import { getFluentComponentAgentKit } from "@gik-ai/components/fluent";
+import { getSecurityComponentAgentKit } from "@gik-ai/components/security";
+import { getSoftwareComponentAgentKit } from "@gik-ai/components/software";
+
+const kit = getSemanticComponentAgentKit([
+  "semantic:event-series",
+  "semantic:work-set",
+]);
+
+const primitiveKit = getPrimitiveComponentAgentKit([
+  "primitive:form",
+  "primitive:editable-table",
+]);
+
+const fluentKit = getFluentComponentAgentKit([
+  "fluent:button",
+  "fluent:dropdown",
+]);
+
+const securityKit = getSecurityComponentAgentKit(["security:attack-path"]);
+const softwareKit = getSoftwareComponentAgentKit(["software:source-comparison"]);
+
+// Add kit.instructions to the agent's authoring context.
+// Contribute kit.tools to createStatelessAgentFaceDispatcher(extraTools).
+```
+
+The generated instructions derive from each selected definition's `describe()` metadata. Tool
+schemas and handlers are restricted to the same selected capabilities. Short registry IDs such as
+`event-series` and full IDs such as `semantic:event-series` are accepted and deduplicated. Omitting the list
+selects the complete registry; an explicit empty list is rejected.
+
+The renderer-free `agentFacingComponentCatalog` is designed for the common transport-free
+`describe` tool. Agents first use `catalog-capabilities` to shortlist, then request every selected
+contract together with `multiple-capabilities`. There is no singular detail operation; hosts should
+merge custom catalogs before constructing the tool.
+
+The package also exports the underlying pure APIs:
+
+- `listSemanticComponents()`
+- `describeSemanticComponent(capability)`
+- `validateSemanticComponentProps(capability, props)`
+- `preflightSemanticComponent(capability, props)`
+- `materializeSemanticComponentTrial(capability, variant?)`
+- `getSemanticComponentAgentInstructions(components?)`
+- `createSemanticComponentAuthoringTools(components?)`
+- `getSemanticComponentAgentKit(components?)`
+- `listSecurityComponents()` / `getSecurityComponentAgentKit(components?)`
+- `listSoftwareComponents()` / `getSoftwareComponentAgentKit(components?)`
+- `listPrimitiveComponents()`
+- `describePrimitiveComponent(capability)`
+- `validatePrimitiveComponentProps(capability, props)`
+- `preflightPrimitiveComponent(capability, props)`
+- `materializePrimitiveComponentTrial(capability, variant?)`
+- `getPrimitiveComponentAgentInstructions(components?)`
+- `createPrimitiveComponentAuthoringTools(components?)`
+- `getPrimitiveComponentAgentKit(components?)`
+- `listFluentComponents()`
+- `describeFluentComponent(capability)`
+- `validateFluentComponentProps(capability, props)`
+- `preflightFluentComponent(capability, props)`
+- `materializeFluentComponentTrial(capability, variant?)`
+- `getFluentComponentAgentInstructions(components?)`
+- `createFluentComponentAuthoringTools(components?)`
+- `getFluentComponentAgentKit(components?)`
+
+Each layer exports a `*ComponentAuthoringTools` convenience catalog for its complete registry.
+These are ACX authoring tools, not live AX runtime tools. The package does not create
+`copilot-instructions.md`, `SKILL.md`, or other host-specific agent customization files.
+
+The root entry point also exports `componentViews`, `componentDefinitions`, and
+`componentCapabilities` — each an aggregate merging the fluent, primitive, semantic, security, and
+software registries of the same name. Use them when a host wants one combined registry across every
+layer instead of registering each layer separately.
+
+## Variants
+
+`variant` is an optional top-level rendering prop with a closed component-specific string enum. An
+authoring agent should inspect `describe().variants`, select a value whose `useWhen` guidance matches
+the target surface, and use `defaultVariant` when no alternate presentation is required. Variants do
+not change domain meaning, semantic status mapping, event contracts, or host theme ownership.
+
+- Event series: `chronology`, `axis`, `text`
+- Process: `flow`, `stages`, `text`
+- Entity set: `clusters`, `matrix`, `list`, `text`
+- Decision: `summary`, `rationale-chain`, `text`
+- Graph diagram: `diagram`, `canvas`
+- Chart: `standard`, `compact`
+- Collection board: `standard`, `compact`
+- Fluent list: `standard`, `selectable`, `vertical-cards`
+- Date time: `date`, `time`, `timestamp`
+- Gantt: `standard`, `compact`
+- Semantic graph: `network`, `relations`
+- Infinite canvas: `standard`, `compact`, `minimal`
+- Source viewer: `standard`, `compact`
+- Attack graph: `canvas`, `diagram`, `relations`, `gantt`, `text`
+
+Timeline's `axis` variant places point events as labeled markers on one horizontal scale. Its
+`spec.scale` uses the same datetime and numeric linear coordinate options as Gantt, including
+fractional values, shared `tickStep` markers, and presentation-only `displayPrefix` labels.
+
+Chart's visualization kind is independent of
+presentation variant. Set `spec.kind` to `bar`, `line`,
+or `pie`; use `variant` only for `standard` or `compact` density.
+
+Gantt accepts either actual timestamps or logical coordinates. Omit `spec.scale` (or set
+`kind: "datetime"`) for timestamp intervals. Set `spec.scale.kind` to `linear` for numeric ranges.
+Optional `minimum` and `maximum` values define a fixed domain such as `0..100`; without bounds, the
+domain is derived from data. `displayPrefix` is presentation-only, so numeric `1` may display as `T1`.
+Set a positive `tickStep` to render shared column markers above the tracks: milliseconds for datetime
+scales and coordinate units for linear scales. Datetime row labels and axis markers use human-readable
+browser-local values. `primitive:datetime` owns the reusable `date`,
+`time`, and `timestamp` scalar presentations and exports matching formatter utilities. Dates omit
+the year when it is the current local year and include it for previous or future years. Time and
+timestamp omit seconds and timezone labels by default; `showSeconds` and `showTimeZone` opt into them.
+Time uses 24-hour format by default; set `hourFormat: "12"` for locale-appropriate AM/PM output.
+The formatter exports accept the same options programmatically.
+
+Growing container owns bounded overflow for its `children` slot. Set `followEnd` to `always`,
+`when-at-end`, or `off`. It has no data prop or presentation variant.
+
+Infinite canvas accepts JSON-native node descriptors and ports. Put target ports on `left` or `top`,
+source ports on `right` or `bottom`, and give each intended connection one shared token; the component
+derives edges automatically and emits `node`, `edge`, and `layout`. It does not accept an edge array or
+React render callbacks through its declarative contract.
+
+Attack graph accepts semantic `entities` and `relationships` plus declarative field mappings. Its
+variants choose a representation rather than a density: `canvas` maps relationships to matching
+ports and delegates interaction and geometry persistence to `primitive:infinite-canvas`; `diagram`
+renders a static node-link overview; `relations` renders accessible source-predicate-target cards
+without drawn edges; `gantt` maps relationships with start/end fields into `primitive:gantt`; `text`
+renders plain ordered relationship statements with no visual geometry and includes human-readable
+start/end timestamp metadata when mapped timestamp fields are available.
+Attack graph passes its optional `spec.ganttScale` through to the primitive, so relationships may use
+actual timestamps or numeric linear coordinates, optionally formatted as `T1..T5` for presentation.
+Datetime and linear scales are configurations of the same `gantt` representation, not Attack Graph variants.
+
+Timer button emits `press` with reason `manual` or `timeout`. It supports a simple auto countdown,
+optional repeating timeout behavior, or a user-selectable manual/auto pace. Timer state is
+projection-local; durable scheduling remains a runtime or service responsibility.
+
+Form renders a schema-driven committed object editor and emits `save` with `{ values }`. Editable
+table renders a committed row editor and emits `save` with `{ rows }`. Both keep draft state local;
+explicit event handlers own persistence and external effects.
+
+Collection board arranges records in declared columns. Its optional interaction configuration enables
+single selection, ordering within a column, and movement between columns without assigning workflow
+meaning to those columns. It emits `select`, `activate`, `reorder`, and `move`; event handlers validate
+business transitions and persist the resulting placement. `standard` and `compact` are density variants.
+
+Source viewer renders exact mapped source rows and precomputed diffs. Set `spec.kind` to `source`,
+`unified-diff`, or `split-diff`; these are representations of one source-row model, while `standard`
+and `compact` remain density variants. Diff rows must already contain aligned before/after content and
+a recognized change value. The primitive presents changes but does not calculate or interpret them.
+
+## Events and effects
+
+These projection components are declarative leaves. A definition's `events` list describes the
+semantic events that its view may emit; the generated capability descriptor exposes the same list as
+`emits`. A bundle may map those events to closed-grammar actions or external effect handlers in its
+behavior graph. Components do not execute bundle effects directly.
+
+Most semantic and domain components are render-only leaves. Work sets and interactive graph
+presentations emit declared intents; consuming bundles decide whether and how those intents change
+state or invoke effects.
+
+Primitive components:
+
+- `chart`
+- `datetime`
+- `editable-table`
+- `form`
+- `gantt`
+- `graph-diagram`
+- `growing-container`
+- `infinite-canvas`
+- `timer-button`
+
+Canonical semantic components:
+
+- `argument` (`map`, `outline`, `text`)
+- `event-series` (`chronology`, `axis`, `text`)
+- `process` (`flow`, `stages`, `text`)
+- `work-set` (`board`, `queue`, `list`, `text`)
+- `entity-set` (`clusters`, `matrix`, `list`, `text`)
+- `evidence-case` (`case`, `sources`, `chain`, `text`)
+- `decision` (`summary`, `rationale-chain`, `text`)
+- `narrative` (`article`, `outline`, `briefing`, `text`)
+- `measure-set` (`tiles`, `table`, `ranking`, `text`)
+- `milestones` (`rail`, `timeline`, `list`, `axis`, `text`)
+- `relationship-set` (`network`, `matrix`, `relations`, `text`)
+
+Security components:
+
+- `attack-path` (`canvas`, `diagram`, `relations`, `gantt`, `text`)
+
+Software components:
+
+- `source-findings` (`findings`, `text`)
+- `source-comparison` (`unified-diff`, `split-diff`, `text`)

package/dist/agent-facing-DjAMQ4Ju.d.ts

@@ -0,0 +1,110 @@
+import { ResolvedNode, Json } from '@gik-ai/kernel';
+import { ProjectionView } from '@gik-ai/react';
+
+interface ComponentAuthoringGuide {
+    useWhen: readonly string[];
+    avoidWhen: readonly string[];
+    rules: readonly string[];
+}
+interface ComponentAgentFacingMetadata {
+    catalog?: {
+        for?: readonly string[];
+        notFor?: readonly string[];
+        interaction?: string;
+    };
+    detail?: {
+        dataProps?: Readonly<Record<string, unknown>>;
+        props?: Readonly<Record<string, unknown>>;
+        constraints?: readonly string[];
+        notes?: readonly string[];
+        example?: Readonly<Record<string, unknown>>;
+    };
+}
+interface ComponentVariantDescription {
+    value: string;
+    summary: string;
+    useWhen: readonly string[];
+}
+interface ComponentEventContract {
+    summary: string;
+    payloadSchema: Record<string, unknown>;
+}
+declare function eventContract(summary: string, properties?: Record<string, unknown>, required?: readonly string[]): ComponentEventContract;
+interface ComponentDescription {
+    capability: string;
+    summary: string;
+    dataProp?: string;
+    slots?: readonly string[];
+    events: readonly string[];
+    eventContracts?: Readonly<Record<string, ComponentEventContract>>;
+    semanticTokens: readonly string[];
+    defaultVariant?: string;
+    variants: readonly ComponentVariantDescription[];
+    authoring: ComponentAuthoringGuide;
+    agentFacing?: ComponentAgentFacingMetadata;
+}
+interface ComponentValidationIssue {
+    detail: string;
+    code?: string;
+}
+interface ComponentValidationReport {
+    ok: boolean;
+    errors: ComponentValidationIssue[];
+    warnings: ComponentValidationIssue[];
+}
+interface DeclarativeComponentDefinition {
+    capability: string;
+    version: string;
+    summary: string;
+    dataProp?: string;
+    slots?: readonly string[];
+    events: readonly string[];
+    eventContracts: Readonly<Record<string, ComponentEventContract>>;
+    semanticTokens: readonly string[];
+    defaultVariant?: string;
+    variants: readonly ComponentVariantDescription[];
+    authoring: ComponentAuthoringGuide;
+    component: ProjectionView;
+    describe(): ComponentDescription;
+    getSchema(): Record<string, unknown>;
+    validate(props: unknown): ComponentValidationReport;
+    materializeTrial(): ResolvedNode;
+}
+interface ComponentDefinitionOptions {
+    description: ComponentDescription;
+    version: string;
+    component: ProjectionView;
+    getSchema(): Record<string, unknown>;
+    validate(props: unknown): ComponentValidationReport;
+    materializeTrial(): ResolvedNode;
+}
+declare function defineComponent({ description, version, component, getSchema, validate, materializeTrial, }: ComponentDefinitionOptions): DeclarativeComponentDefinition;
+declare function componentNode(id: string, capability: string, props: Record<string, Json>): ResolvedNode;
+declare function trialNode(capability: string, props: Record<string, Json>): ResolvedNode;
+
+interface AgentFacingCapabilitySelection {
+    for: readonly string[];
+    notFor?: readonly string[];
+    interaction?: string;
+}
+interface AgentFacingCapabilityDetail {
+    dataProps?: Readonly<Record<string, unknown>>;
+    props?: Readonly<Record<string, unknown>>;
+    variants?: Readonly<Record<string, {
+        summary: string;
+        useWhen: readonly string[];
+        default?: true;
+    }>>;
+    slots?: readonly string[];
+    emits?: Readonly<Record<string, ComponentEventContract>>;
+    constraints?: readonly string[];
+    notes?: readonly string[];
+    example?: Readonly<Record<string, unknown>>;
+}
+interface AgentFacingCapabilityCatalog {
+    catalog: Readonly<Record<string, AgentFacingCapabilitySelection>>;
+    details: Readonly<Record<string, AgentFacingCapabilityDetail>>;
+}
+declare function mergeAgentFacingCapabilityCatalogs(...catalogs: readonly AgentFacingCapabilityCatalog[]): AgentFacingCapabilityCatalog;
+
+export { type AgentFacingCapabilityCatalog as A, type ComponentDescription as C, type DeclarativeComponentDefinition as D, type AgentFacingCapabilityDetail as a, type AgentFacingCapabilitySelection as b, type ComponentEventContract as c, type ComponentValidationReport as d, type ComponentAgentFacingMetadata as e, type ComponentAuthoringGuide as f, type ComponentDefinitionOptions as g, type ComponentValidationIssue as h, type ComponentVariantDescription as i, componentNode as j, defineComponent as k, eventContract as l, mergeAgentFacingCapabilityCatalogs as m, trialNode as t };

package/dist/agent-facing.d.ts

@@ -0,0 +1,8 @@
+import { A as AgentFacingCapabilityCatalog } from './agent-facing-DjAMQ4Ju.js';
+export { a as AgentFacingCapabilityDetail, b as AgentFacingCapabilitySelection, m as mergeAgentFacingCapabilityCatalogs } from './agent-facing-DjAMQ4Ju.js';
+import '@gik-ai/kernel';
+import '@gik-ai/react';
+
+declare const agentFacingComponentCatalog: AgentFacingCapabilityCatalog;
+
+export { AgentFacingCapabilityCatalog, agentFacingComponentCatalog };