@kerfjs/ui 4.5.0-beta.1 → 5.0.0-beta.100

package/ai/component-composition.d.ts

@@ -0,0 +1,132 @@
+export type CatalogQualifiedKey = `${string}:${string}`;
+/** A `data-*` attribute a wiring helper writes at runtime. The application
+ *  must not render, remove, or treat it as its own state. */
+export interface CatalogStateAttribute {
+  name: `data-${string}`;
+  /** The element that carries it: a public class, or the element passed to the helper. */
+  on: string;
+  /** The helper, one of `wiring.helpers`, that writes it. */
+  helper: string;
+  /** What its presence or value means. */
+  meaning: string;
+}
+export type CatalogCardinality = {
+  min: number;
+  max: number | 'unbounded';
+};
+export type CatalogDiagnostic = {
+  id: `KUI-C${number}`;
+  severity: 'error' | 'warning';
+  when: string;
+  message: string;
+};
+export type CatalogCssValueProp = {
+  path: string;
+  grammar:
+    | 'length'
+    | 'size'
+    | 'flex'
+    | 'color'
+    | 'declarations'
+    | 'media-query'
+    | 'pixels';
+  helpers: string[];
+  nonStandaloneHelpers?: string[];
+  shorthands: string[];
+  canonicalShorthands: string[];
+  exceptionalShorthands: string[];
+  rawPolicy: 'forbid' | 'allow' | 'unsafe-only';
+  unsafeHelper?: string;
+  examples: string[];
+};
+export interface CatalogCompositionEntry {
+  key: CatalogQualifiedKey;
+  package: string;
+  id: string;
+  name: string;
+  kind: 'component' | 'composition' | 'recipe';
+  purpose?: string;
+  publicExports?: Array<{ name: string; subpath: string }>;
+  sourceLinks?: string[];
+  source: string;
+  /** For a wrapper component: the cataloged roots it renders (any one of
+   *  them, or nothing). Composition checks treat its elements as each root. */
+  rendersAs?: CatalogQualifiedKey[];
+  /** Additional JSX exports in this selection entry with their own placement. */
+  jsxExports?: Record<
+    string,
+    {
+      parents: {
+        mode: 'any' | 'root' | 'listed';
+        entries: CatalogQualifiedKey[];
+      };
+    }
+  >;
+  parents: { mode: 'any' | 'root' | 'listed'; entries: CatalogQualifiedKey[] };
+  contexts: string[];
+  zones: Array<{
+    id: string;
+    /** Static JSX binding when this zone is supplied by a public prop. */
+    jsx?: { prop: string };
+    accepts: string[];
+    cardinality: CatalogCardinality;
+    exclusiveWith: string[];
+  }>;
+  children: {
+    mode: 'any' | 'none' | 'listed';
+    concepts: string[];
+    requiredConcepts: string[];
+  };
+  state: Array<{
+    id: string;
+    owner: 'application' | 'controlled' | 'component';
+    required: boolean;
+  }>;
+  wiring: {
+    required: boolean;
+    helpers: string[];
+    /** Defining source files for application-owned helpers, relative to the catalog package root. */
+    sources?: Array<{ export: string; source: string }>;
+    /** `data-action` values the application handles with a root-delegated
+     *  listener (`delegate` / `delegateActions`) instead of a named helper. */
+    actions?: string[];
+    obligations: string[];
+    /** Wiring-owned `data-*` attributes a helper writes at runtime. Optional
+     *  for extension catalogs; first-party entries always list it. */
+    stateAttributes?: CatalogStateAttribute[];
+  };
+  responsive: {
+    owner: 'application' | 'component' | 'shared' | 'not-applicable';
+    behaviors: string[];
+  };
+  layout: {
+    roles: string[];
+    geometry: Record<
+      'margin' | 'border' | 'padding',
+      'self' | 'parent' | 'child' | 'none' | 'conditional' | 'composed'
+    > & { notes?: string[] };
+  };
+  accessibility: { obligations: string[] };
+  boundaries: {
+    rootClass: string | null;
+    publicClasses: string[];
+    /** Public classes an application may place on its own elements; absent means none. */
+    placeableClasses?: string[];
+    /** The intrinsic element the component renders at its root; a placeable class on a plain element of this tag recreates the component. */
+    rootElement?: string;
+    descendantElements?: string[];
+    descendantRootAttribute?: string;
+    publicTokens: string[];
+    publicParts?: string[];
+  };
+  cssValueProps?: CatalogCssValueProp[];
+  diagnostics: CatalogDiagnostic[];
+  provenance: { selection: string; composition: string };
+}
+export interface ComponentComposition {
+  $schema?: string;
+  schemaVersion: 1;
+  package: string;
+  compatibility: { componentCatalog: string; identity: 'package:id' };
+  entries: CatalogCompositionEntry[];
+}