@kerfjs/ui 5.0.0-beta.9 → 5.0.0-beta.90

package/ai/application-ui-profile.d.ts

@@ -0,0 +1,106 @@
+export type ApplicationUiProfileScope = 'package' | 'workspace' | 'directory';
+export type QualifiedCatalogKey = `${string}:${string}`;
+
+export interface ApplicationUiCatalogLocation {
+  path: string;
+  schemaVersion: number;
+}
+
+export interface ApplicationUiProfile {
+  $schema?: string;
+  schemaVersion: 1;
+  scope: ApplicationUiProfileScope;
+  catalogs?: Array<{
+    package: string;
+    /** Required for @kerfjs/ui; composition-only consumer packages omit it. */
+    selection?: ApplicationUiCatalogLocation;
+    composition: ApplicationUiCatalogLocation;
+  }>;
+  preferences?: Record<
+    string,
+    {
+      preferred: QualifiedCatalogKey;
+      avoid?: QualifiedCatalogKey[];
+      rationale?: string;
+    }
+  >;
+  theme?: {
+    colorScheme?: 'light' | 'dark' | 'invert' | 'system';
+    allowedColorSchemes?: Array<'light' | 'dark' | 'invert' | 'system'>;
+    density?: 'standard' | 'compact';
+    allowedDensities?: Array<'standard' | 'compact'>;
+  };
+  tokens?: Record<`--kui-${string}`, string>;
+  layout?: {
+    shell?: QualifiedCatalogKey;
+    pane?: QualifiedCatalogKey;
+    responsiveStrategy?: 'device-class' | 'container' | 'application';
+    compactNavigation?: 'nav-stack' | 'tab-scaffold' | 'application';
+    scrollOwnership?: 'one-per-pane' | 'application';
+    spacingScale?: 'kerf-five-step' | 'application';
+  };
+  wiring?: {
+    /** Static application entry modules, relative to the workspace root. */
+    entries?: string[];
+  };
+  exceptions?: Array<{
+    id: string;
+    rules: string[];
+    target: string;
+    rationale: string;
+  }>;
+}
+
+export interface ApplicationUiProfileLayer {
+  source: string;
+  profile: ApplicationUiProfile;
+}
+
+export interface ApplicationUiProfileDiagnostic {
+  code: string;
+  source: string;
+  path: string;
+  message: string;
+}
+
+export interface ResolvedApplicationUiProfile {
+  profile: ApplicationUiProfile;
+  provenance: Record<string, string>;
+}
+
+export const APPLICATION_UI_PROFILE_FILENAME: '.kerf-ui-profile.json';
+export function discoverApplicationUiProfileFiles(options: {
+  workspaceRoot: string;
+  startDirectory: string;
+  packageProfile?: string;
+}): Promise<string[]>;
+export function readApplicationUiProfile(
+  source: string,
+): Promise<ApplicationUiProfileLayer>;
+export function mergeApplicationUiProfiles(
+  layers: ApplicationUiProfileLayer[],
+): ResolvedApplicationUiProfile;
+export function validateApplicationUiProfileLayers(
+  layers: ApplicationUiProfileLayer[],
+): ApplicationUiProfileDiagnostic[];
+export function validateApplicationUiProfile(
+  profile: ApplicationUiProfile,
+  options?: {
+    source?: string;
+    knownComponents?: Iterable<string>;
+    knownTokens?: Iterable<string>;
+    knownRules?: Iterable<string>;
+  },
+): ApplicationUiProfileDiagnostic[];
+export function loadApplicationUiProfile(options: {
+  workspaceRoot: string;
+  startDirectory: string;
+  packageProfile?: string;
+  knownRules?: Iterable<string>;
+}): Promise<{
+  files: string[];
+  layers: ApplicationUiProfileLayer[];
+  profile?: ApplicationUiProfile;
+  provenance?: Record<string, string>;
+  diagnostics: ApplicationUiProfileDiagnostic[];
+}>;

package/ai/application-ui-profile.defaults.json

@@ -0,0 +1,96 @@
+{
+  "$schema": "./application-ui-profile.schema.json",
+  "schemaVersion": 1,
+  "scope": "package",
+  "catalogs": [
+    {
+      "package": "@kerfjs/ui",
+      "selection": {
+        "path": "./component-catalog.json",
+        "schemaVersion": 1
+      },
+      "composition": {
+        "path": "./component-composition.json",
+        "schemaVersion": 1
+      }
+    }
+  ],
+  "preferences": {
+    "application-shell": {
+      "preferred": "@kerfjs/ui:recipe-app-shell"
+    },
+    "application-tabs": {
+      "preferred": "@kerfjs/ui:tab-bar",
+      "avoid": [
+        "@kerfjs/ui:wa-tab-group",
+        "@kerfjs/ui:wa-tab",
+        "@kerfjs/ui:wa-tab-panel"
+      ],
+      "rationale": "Render TabBar (or SegmentedControl for a view switch) instead of composing Web Awesome tabs directly."
+    },
+    "command-menu": {
+      "preferred": "@kerfjs/ui:popup-menu",
+      "avoid": ["@kerfjs/ui:wa-dropdown", "@kerfjs/ui:wa-dropdown-item"],
+      "rationale": "Render PopupMenu, which wraps wa-dropdown with the shared popup contract; use Select when choosing a value."
+    },
+    "embedded-media": {
+      "preferred": "@kerfjs/ui:content-item",
+      "avoid": [
+        "@kerfjs/ui:wa-animated-image",
+        "@kerfjs/ui:wa-comparison",
+        "@kerfjs/ui:wa-zoomable-frame"
+      ],
+      "rationale": "Keep media behavior application-owned: place a native img, video, or iframe in a ContentItem. Record a narrow KUI-L301 profile exception only when a concrete product requirement needs this Web Awesome element."
+    },
+    "exclusive-choice": {
+      "preferred": "@kerfjs/ui:segmented-control",
+      "avoid": ["@kerfjs/ui:wa-button-group"],
+      "rationale": "Render SegmentedControl for one-of-N choices instead of a Web Awesome button group."
+    },
+    "hierarchy-navigation": {
+      "preferred": "@kerfjs/ui:list",
+      "avoid": ["@kerfjs/ui:wa-tree", "@kerfjs/ui:wa-tree-item"],
+      "rationale": "Present hierarchy as List rows (or NavStack drill-in levels). Record a narrow KUI-L301 profile exception only when the product requires tree behavior."
+    },
+    "icon": {
+      "preferred": "@kerfjs/ui:lucide-icon",
+      "avoid": ["@kerfjs/ui:wa-icon"],
+      "rationale": "Render LucideIcon; Web Awesome icons are not part of the Kerf icon contract."
+    },
+    "navigation-row": {
+      "preferred": "@kerfjs/ui:list-item"
+    },
+    "panel-heading": {
+      "preferred": "@kerfjs/ui:toolbar"
+    },
+    "resizable-pane": {
+      "preferred": "@kerfjs/ui:resize",
+      "avoid": ["@kerfjs/ui:wa-split-panel"],
+      "rationale": "Render ResizableRegion for application panes instead of a Web Awesome split panel."
+    },
+    "structured-search": {
+      "preferred": "@kerfjs/ui:token-search-field"
+    },
+    "value-selection": {
+      "preferred": "@kerfjs/ui:select",
+      "avoid": ["@kerfjs/ui:wa-select", "@kerfjs/ui:wa-option"],
+      "rationale": "Render Select, which wraps wa-select and wa-option with Kerf's popup and spacing contract."
+    }
+  },
+  "theme": {
+    "colorScheme": "light",
+    "allowedColorSchemes": ["light", "dark", "invert"],
+    "density": "standard",
+    "allowedDensities": ["standard"]
+  },
+  "tokens": {},
+  "layout": {
+    "shell": "@kerfjs/ui:recipe-app-shell",
+    "pane": "@kerfjs/ui:pane",
+    "responsiveStrategy": "device-class",
+    "compactNavigation": "nav-stack",
+    "scrollOwnership": "one-per-pane",
+    "spacingScale": "kerf-five-step"
+  },
+  "exceptions": []
+}