@astryxdesign/core 0.1.6 → 0.1.7-canary.04cd8f7

package/src/TopNav/TopNavHeading.tsx

@@ -39,6 +39,7 @@ import type {BaseProps} from '../BaseProps';
 import {useMenuHover} from '../hooks/useMenuHover';
 import {NavHeadingCloseContext} from '../NavMenu/NavMenuContext';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 // =============================================================================
 // Styles
@@ -318,6 +319,7 @@ export function TopNavHeading({
   ref,
   ...props
 }: TopNavHeadingProps) {
+  const t = useTranslator();
   const LinkComponent = useLinkComponent(as);
   // Support both headingHref and legacy href
   const headingHref = headingHrefProp ?? href;
@@ -329,7 +331,7 @@ export function TopNavHeading({
   const rootRef = useRef<HTMLElement>(null);
 
   const popover = usePopover({
-    dialogLabel: 'Navigation menu',
+    dialogLabel: t('@astryx.topNav.heading.dialogLabel'),
     hasCloseButton: false,
   });
 
@@ -494,7 +496,7 @@ export function TopNavHeading({
           {renderTextContent(
             <button
               type="button"
-              aria-label="Open menu"
+              aria-label={t('@astryx.topNav.heading.openMenu')}
               onClick={e => {
                 e.stopPropagation();
                 triggerProps.onClick();
@@ -557,7 +559,7 @@ export function TopNavHeading({
             showChevron ? (
               <button
                 type="button"
-                aria-label="Open menu"
+                aria-label={t('@astryx.topNav.heading.openMenu')}
                 onClick={e => {
                   e.stopPropagation();
                   triggerProps.onClick();

package/src/TreeList/TreeList.tsx

@@ -208,8 +208,12 @@ export function TreeList({
   // to this treeitem's own row — never a descendant treeitem's action inside an
   // expanded group.
   const activateItem = useCallback((current: HTMLElement): boolean => {
+    // The chevron toggle is marked with `data-tree-toggle` (set by
+    // TreeListItem) so this filter stays stable across locales — matching by
+    // aria-label would break under any locale where "Toggle children" is
+    // translated.
     const candidates = current.querySelectorAll<HTMLElement>(
-      'a[href], button:not([aria-label="Toggle children"])',
+      'a[href], button:not([data-tree-toggle])',
     );
     for (const candidate of candidates) {
       if (candidate.closest('[role="treeitem"]') === current) {

package/src/TreeList/TreeListItem.tsx

@@ -31,6 +31,7 @@ import {TreeListBranches} from './TreeListBranches';
 import type {TreeListDensity} from './TreeListTypes';
 import {treeItemScope} from './treeListItem.markers.stylex';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 // =============================================================================
 // Styles
@@ -299,6 +300,7 @@ export function TreeListItem({
   setSize,
   isTabbable,
 }: TreeListItemInternalProps) {
+  const t = useTranslator();
   const labelId = useId();
   const descriptionId = useId();
   const LinkComponent = useLinkComponent();
@@ -374,7 +376,10 @@ export function TreeListItem({
       <button
         type="button"
         aria-expanded={isExpanded}
-        aria-label="Toggle children"
+        aria-label={t('@astryx.treeList.toggleChildren')}
+        // Stable identity for TreeList's activateItem selector — do not
+        // remove without also updating TreeList.tsx.
+        data-tree-toggle=""
         disabled={isDisabled}
         // Roving tabindex lives on the treeitem row; the chevron toggle is not
         // a separate tab stop. Row-level Enter/Space forwards to this button.

package/src/Typeahead/BaseTypeahead.tsx

@@ -44,6 +44,7 @@ import {getKey, mergeProps, mergeRefs} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {SearchableItem, SearchSource} from './types';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 // =============================================================================
 // Types
@@ -302,10 +303,10 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   value,
   onChange,
   renderItem,
-  placeholder = 'Search...',
+  placeholder: placeholderFromProps,
   hasEntriesOnFocus = false,
   maxMenuItems = 10,
-  emptySearchResultsText = 'No results found',
+  emptySearchResultsText: emptySearchResultsTextFromProps,
   isDisabled = false,
   isFocusableDisabled = false,
   hasAutoFocus = false,
@@ -321,6 +322,12 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   size = 'md',
   ref,
 }: BaseTypeaheadProps<T>) {
+  const t = useTranslator();
+  const placeholder =
+    placeholderFromProps ?? t('@astryx.typeahead.searchPlaceholder');
+  const emptySearchResultsText =
+    emptySearchResultsTextFromProps ??
+    t('@astryx.typeahead.emptySearchResults');
   const generatedId = useId();
   const inputId = externalInputId ?? generatedId;
   const listboxId = useId();
@@ -759,7 +766,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
       {isLoading && (
         <span
           role="status"
-          aria-label="Loading"
+          aria-label={t('@astryx.typeahead.loading')}
           {...stylex.props(styles.loadingSpinner)}>
           <Icon icon="clock" size="sm" color="secondary" />
         </span>
@@ -769,7 +776,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
         <div
           id={listboxId}
           role="listbox"
-          aria-label="Search results"
+          aria-label={t('@astryx.typeahead.searchResults')}
           {...mergeProps(
             themeProps('typeahead-dropdown'),
             stylex.props(styles.dropdown),

package/src/Typeahead/Typeahead.doc.mjs

@@ -85,7 +85,7 @@ export const docs = {
     },
     {
       name: 'status',
-      type: 'InputStatus',
+      type: "{type: 'warning' | 'error' | 'success', message?: string}",
       description:
         'Validation status object with type and message for error/warning/success states.',
     },

package/src/Typeahead/Typeahead.tsx

@@ -49,6 +49,7 @@ import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import type {SearchableItem, SearchSource} from './types';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 export type {
   InputStatus as TypeaheadStatus,
@@ -249,6 +250,7 @@ export function Typeahead<T extends SearchableItem>({
   style,
   'data-testid': testId,
 }: TypeaheadProps<T>) {
+  const t = useTranslator();
   const size = useSize(sizeProp, 'md');
   const inputId = useId();
   const inputLabelId = useId();
@@ -460,7 +462,7 @@ export function Typeahead<T extends SearchableItem>({
         />
         {hasClear && value && !isDisabled && (
           <InputClearButton
-            label="Clear selection"
+            label={t('@astryx.typeahead.clearSelection')}
             onClick={e => {
               e.stopPropagation();
               handleClear();

package/src/VisuallyHidden/VisuallyHidden.tsx

@@ -13,6 +13,7 @@
  * - /packages/core/src/VisuallyHidden/VisuallyHidden.doc.mjs
  * - /packages/core/src/VisuallyHidden/VisuallyHidden.test.tsx
  * - /apps/storybook/stories/VisuallyHidden.stories.tsx
+ * - /packages/cli/templates/blocks/components/VisuallyHidden/ (showcase blocks)
  */
 
 import {createElement, type ElementType, type ReactNode, type Ref} from 'react';

package/src/authoring/doc.ts

@@ -0,0 +1,166 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file doc.ts
+ * @input A component/function/generic doc object (without the `type` tag).
+ * @output Type-preserving `createComponentDoc`/`createFunctionDoc`/`createDoc`
+ *   helpers plus the doc-authoring TypeScript surface.
+ * @position Integration-author authoring surface. See `./index.ts` for why
+ *   these authoring factories live in `@astryxdesign/core`.
+ *
+ * A doc describes a documentable unit of the design system so the CLI and docs
+ * surfaces can list, search, and render it. There are three kinds, each a tiny
+ * runtime identity helper that stamps a `type` discriminant:
+ *
+ *   - `createComponentDoc` -> `type: 'component'` — a component (or a family).
+ *   - `createFunctionDoc`  -> `type: 'function'`  — any function, including
+ *      hooks: an "inputs + outputs" surface (`params` + `returns`).
+ *   - `createDoc`          -> `type: 'generic'`   — reference/topic docs.
+ *
+ * These factories do NOT validate. Validation happens at the CLI load boundary,
+ * where doc discovery runs the loaded value through a schema that accepts BOTH
+ * the stamped formats and the legacy loose `export const docs = {...}` shape.
+ */
+
+/**
+ * Fields shared by every doc kind (component + function + generic).
+ *
+ * `group` vs `parent` are distinct:
+ *   - `group` is a FLAT sidebar bucket label; many docs can share it and it is
+ *     NOT an inheritance key.
+ *   - `parent` is a DIRECTED inheritance/composition pointer — a doc naming the
+ *     doc it belongs to (e.g. a sub-component naming its parent component). The
+ *     legacy `subComponentOf` field is a synonym.
+ *
+ * `relatedDocs` is a single flat curated cross-reference list; it replaces the
+ * legacy split `relatedComponents` + `relatedHooks`.
+ */
+export interface AstryxBaseDocInput {
+  /** Name of the documented unit, without any prefix, PascalCase. Required. */
+  name: string;
+  /** Human-readable display name for gallery/sidebar. */
+  displayName?: string;
+  /** Short description. */
+  description?: string;
+  /** Usage documentation (description, best practices, anatomy, slotElements). */
+  usage?: unknown;
+  /** Flat sidebar grouping label (not an inheritance key). */
+  group?: string;
+  /** Overview-page functional category. */
+  category?: string;
+  /** CLI fuzzy-search keywords. */
+  keywords?: string[];
+  /** Directed inheritance/composition pointer to the doc this belongs to. */
+  parent?: string;
+  /** Flat curated cross-reference list of related doc names. */
+  relatedDocs?: string[];
+  /** Hide the whole doc from human-facing UI (stays importable/discoverable). */
+  hidden?: boolean;
+  /** Exclude from the categorized overview page (kept in sidebar/CLI). */
+  isHiddenFromOverview?: boolean;
+  /** Any additional fields the rich doc surface carries. */
+  [key: string]: unknown;
+}
+
+/** A single documented prop (mirrors `PropDoc` from core docs-types). */
+export interface AstryxPropInput {
+  name: string;
+  type: string;
+  description: string;
+  default?: string;
+  required?: boolean;
+  [key: string]: unknown;
+}
+
+/** A single documented param (mirrors `HookParamDoc`). */
+export interface AstryxParamInput {
+  name: string;
+  type: string;
+  description: string;
+  default?: string;
+  required?: boolean;
+  [key: string]: unknown;
+}
+
+/** A single documented return field (mirrors `HookReturnDoc`). */
+export interface AstryxReturnInput {
+  name: string;
+  type: string;
+  description: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Input accepted by {@link createComponentDoc}. A component (or a family). The
+ * `type` discriminant is injected by the factory. `anatomy`/`slotElements` live
+ * inside `usage`; `importPath` is DERIVED (never authored).
+ */
+export interface AstryxComponentDocInput extends AstryxBaseDocInput {
+  /** All public props for the component. */
+  props: AstryxPropInput[];
+  /** Theming/selector-surface metadata. */
+  theming?: unknown;
+  /** Interactive-preview playground configuration. */
+  playground?: unknown;
+  /** Short code examples rendered after the props table. */
+  examples?: unknown[];
+}
+
+/**
+ * Input accepted by {@link createFunctionDoc}. Covers any function, including
+ * hooks: an inputs (`params`) + outputs (`returns`) surface. The `type`
+ * discriminant is injected by the factory; `importPath` is DERIVED.
+ */
+export interface AstryxFunctionDocInput extends AstryxBaseDocInput {
+  /** Function/hook parameters or options-object fields. */
+  params: AstryxParamInput[];
+  /** Return value documentation. One entry per field (or a single primitive). */
+  returns: AstryxReturnInput[];
+}
+
+/**
+ * Input accepted by {@link createDoc}. A generic reference/topic doc — just the
+ * shared base. The `type` discriminant is injected by the factory.
+ */
+export type AstryxGenericDocInput = AstryxBaseDocInput;
+
+/**
+ * Back-compat alias. Previously `createDoc` accepted a broad component-doc
+ * record; the union of the three input kinds preserves that permissiveness for
+ * any code referring to the old name.
+ */
+export type AstryxComponentDoc =
+  | AstryxComponentDocInput
+  | AstryxFunctionDocInput
+  | AstryxGenericDocInput;
+
+/**
+ * Author a component doc. Stamp-only: returns the def with `type: 'component'`
+ * injected. Validation happens at the CLI load boundary.
+ */
+export function createComponentDoc<T extends AstryxComponentDocInput>(
+  def: T,
+): T & {type: 'component'} {
+  return {...def, type: 'component'};
+}
+
+/**
+ * Author a function doc (covers any function, including hooks). Stamp-only:
+ * returns the def with `type: 'function'` injected. Validation happens at the
+ * CLI load boundary.
+ */
+export function createFunctionDoc<T extends AstryxFunctionDocInput>(
+  def: T,
+): T & {type: 'function'} {
+  return {...def, type: 'function'};
+}
+
+/**
+ * Author a generic reference/topic doc. Stamp-only: returns the def with
+ * `type: 'generic'` injected. Validation happens at the CLI load boundary.
+ */
+export function createDoc<T extends AstryxGenericDocInput>(
+  def: T,
+): T & {type: 'generic'} {
+  return {...def, type: 'generic'};
+}

package/src/authoring/index.test.ts

@@ -0,0 +1,52 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {
+  createIntegration,
+  createPageTemplate,
+  createBlockTemplate,
+  createComponentDoc,
+  createFunctionDoc,
+  createDoc,
+} from './index';
+
+describe('authoring factories', () => {
+  it('createIntegration returns its argument unchanged', () => {
+    const input = {components: './c', templates: './t'};
+    expect(createIntegration(input)).toBe(input);
+  });
+
+  it('createPageTemplate / createBlockTemplate stamp the template type', () => {
+    expect(createPageTemplate({name: 'P', description: 'd'}).type).toBe('page');
+    expect(createBlockTemplate({name: 'B', description: 'd'}).type).toBe(
+      'block',
+    );
+  });
+
+  it('createPageTemplate preserves authored fields', () => {
+    const t = createPageTemplate({name: 'P', description: 'd', category: 'x'});
+    expect(t).toMatchObject({
+      name: 'P',
+      description: 'd',
+      category: 'x',
+      type: 'page',
+    });
+  });
+
+  it('doc factories stamp the doc kind', () => {
+    expect(createComponentDoc({name: 'Button', props: []}).type).toBe(
+      'component',
+    );
+    expect(
+      createFunctionDoc({name: 'useX', params: [], returns: []}).type,
+    ).toBe('function');
+    expect(createDoc({name: 'Topic'}).type).toBe('generic');
+  });
+
+  it('doc factories do not mutate the input object', () => {
+    const input = {name: 'Button', props: []};
+    const out = createComponentDoc(input);
+    expect(out).not.toBe(input);
+    expect(input).not.toHaveProperty('type');
+  });
+});

package/src/authoring/index.ts

@@ -0,0 +1,50 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file index.ts
+ * @input None (barrel).
+ * @output The Astryx integration-authoring surface: the stamp-only factories an
+ *   integration package uses to describe what it contributes (integrations,
+ *   templates, docs), plus their TypeScript input/output types.
+ * @position Producer-facing authoring surface, exported as
+ *   `@astryxdesign/core/authoring`.
+ *
+ * ## Why these live in core
+ *
+ * These factories are tiny, zero-runtime-dependency identity functions whose
+ * value is their TypeScript surface. Hosting them in `@astryxdesign/core` (the
+ * base of the dependency graph) means core's own docs can adopt them without a
+ * core -> cli -> core cycle, and integration authors get the types without a
+ * hard dependency on the CLI. The CLI re-exports every factory from its
+ * existing subpaths (`@astryxdesign/cli/integration|template|doc`) for
+ * back-compat; the CLI keeps the Zod validation schemas at its load boundary.
+ *
+ * `createConfig` is intentionally NOT here — it is a consumer surface (every app
+ * with an `astryx.config`), exported separately as `@astryxdesign/core/config`.
+ */
+
+export {createIntegration} from './integration';
+export type {AstryxIntegration} from './integration';
+
+export {createPageTemplate, createBlockTemplate} from './template';
+export type {
+  AstryxTemplatePreview,
+  AstryxTemplateInput,
+  AstryxPageTemplateInput,
+  AstryxBlockTemplateInput,
+  AstryxPageTemplate,
+  AstryxBlockTemplate,
+  AstryxTemplate,
+} from './template';
+
+export {createComponentDoc, createFunctionDoc, createDoc} from './doc';
+export type {
+  AstryxBaseDocInput,
+  AstryxPropInput,
+  AstryxParamInput,
+  AstryxReturnInput,
+  AstryxComponentDocInput,
+  AstryxFunctionDocInput,
+  AstryxGenericDocInput,
+  AstryxComponentDoc,
+} from './doc';

package/src/authoring/integration.ts

@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file integration.ts
+ * @input An integration package's manifest object.
+ * @output A type-preserving `createIntegration` helper plus the
+ *   `AstryxIntegration` manifest surface.
+ * @position Integration-author authoring surface. See `./index.ts` for why
+ *   these authoring factories live in `@astryxdesign/core`.
+ *
+ * `createIntegration` is an intentionally tiny runtime identity function: it
+ * returns its argument unchanged. Validation is NOT performed here — it happens
+ * at the CLI load boundary.
+ */
+
+/**
+ * Integration manifest exported from a conventional root manifest file
+ * (astryx.integration.{ts,mjs,js}) sibling to the integration package's
+ * package.json. Identity (name/version) comes from the package's
+ * package.json, not from the manifest.
+ */
+export interface AstryxIntegration {
+  /** Relative path to the components/docs root (resolved to absolute). */
+  components?: string;
+  /** Relative path to the templates root (resolved to absolute). */
+  templates?: string;
+  /** Relative path to the codemods root (resolved to absolute). */
+  codemods?: string;
+  /** Where to file issues/feedback for this integration. */
+  issuesUrl?: string;
+}
+
+/**
+ * Type-preserving helper for an Astryx integration manifest. Returns its
+ * argument unchanged; the value is the exported TypeScript surface. Validation
+ * happens at the CLI load boundary.
+ */
+export function createIntegration<T extends AstryxIntegration>(
+  integration: T,
+): T {
+  return integration;
+}

package/src/authoring/template.ts

@@ -0,0 +1,74 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file template.ts
+ * @input A page/block template doc object (without the `type` tag).
+ * @output Type-preserving `createPageTemplate`/`createBlockTemplate` helpers
+ *   plus the authored-template TypeScript surface.
+ * @position Integration-author authoring surface. See `./index.ts` for why
+ *   these authoring factories live in `@astryxdesign/core`.
+ *
+ * A template doc lives in a `<id>.doc.{ts,mjs,js}` file with a required
+ * same-stem sibling source file (`<id>.tsx`). The doc's `type` (page or block)
+ * — injected by the create* helpers — decides how the template is scaffolded.
+ *
+ * These are tiny runtime identity helpers that inject the `type` discriminant.
+ * They do NOT validate — validation happens at the CLI load boundary, where
+ * integration template discovery runs the module's default export through the
+ * template envelope schema.
+ */
+
+/** Optional preview metadata for a template (used by docs surfaces). */
+export interface AstryxTemplatePreview {
+  /** Path or URL to a preview image. */
+  image?: string;
+  /** CSS aspect-ratio hint for the preview, e.g. "16 / 9". */
+  aspectRatio?: string;
+}
+
+/** Fields common to page and block template docs (without the `type` tag). */
+export interface AstryxTemplateInput {
+  /** Human-readable template name. Required. */
+  name: string;
+  /** One-line description of what the template provides. Required. */
+  description: string;
+  /** Optional grouping/category label. */
+  category?: string;
+  /** Component display names the template composes. */
+  componentsUsed?: string[];
+  /** Optional preview metadata. */
+  preview?: AstryxTemplatePreview;
+}
+
+/** Input accepted by {@link createPageTemplate} (no `type` field). */
+export type AstryxPageTemplateInput = AstryxTemplateInput;
+/** Input accepted by {@link createBlockTemplate} (no `type` field). */
+export type AstryxBlockTemplateInput = AstryxTemplateInput;
+
+/** A validated page template doc. */
+export type AstryxPageTemplate = AstryxTemplateInput & {type: 'page'};
+/** A validated block template doc. */
+export type AstryxBlockTemplate = AstryxTemplateInput & {type: 'block'};
+
+/** A validated template doc (page or block). */
+export type AstryxTemplate = AstryxPageTemplate | AstryxBlockTemplate;
+
+/**
+ * Author an Astryx page template doc. Stamp-only: returns the def with
+ * `type: 'page'` injected. Validation happens at the CLI load boundary.
+ */
+export function createPageTemplate<T extends AstryxPageTemplateInput>(
+  def: T,
+): T & {type: 'page'} {
+  return {...def, type: 'page'};
+}
+
+/**
+ * Author an Astryx block template doc. Stamp-only: returns the def with
+ * `type: 'block'` injected. Validation happens at the CLI load boundary.
+ */
+export function createBlockTemplate<T extends AstryxBlockTemplateInput>(
+  def: T,
+): T & {type: 'block'} {
+  return {...def, type: 'block'};
+}

package/src/config.test.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {createConfig} from './config';
+
+describe('createConfig', () => {
+  it('returns its argument unchanged (identity)', () => {
+    const input = {integrations: ['@acme/astryx'], issuesUrl: 'https://x'};
+    expect(createConfig(input)).toBe(input);
+  });
+
+  it('does not stamp a discriminant', () => {
+    const cfg = createConfig({integrations: []}) as Record<string, unknown>;
+    expect(cfg.type).toBeUndefined();
+  });
+});

package/src/config.ts

@@ -0,0 +1,92 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file config.ts
+ * @input An app's Astryx config object.
+ * @output A type-preserving `createConfig` helper plus the `AstryxConfig`
+ *   surface authors write in `astryx.config.{ts,mjs,js}`.
+ * @position Consumer-facing authoring surface. Lives in `@astryxdesign/core`
+ *   (not the CLI) so an app's config file gets editor/type feedback without
+ *   taking a dependency on the CLI. The CLI re-exports this from
+ *   `@astryxdesign/cli/config` for back-compat.
+ *
+ * `createConfig` is an intentionally tiny runtime identity function: it returns
+ * its argument unchanged. Its value is the exported TypeScript surface.
+ * Validation is NOT performed here — it happens at the CLI load boundary.
+ */
+
+/**
+ * A command to run as part of a post-codemod hook. Returned by a hook's
+ * `buildCommand` and executed after codemods write files.
+ */
+export interface PostCodemodCommand {
+  command: string;
+  args?: string[];
+  options?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    timeout?: number;
+  };
+}
+
+/**
+ * A post-codemod hook. `buildCommand` receives the package directory and the
+ * list of files changed by codemods, and returns the command to run (or a
+ * nullish value to skip).
+ */
+export type PostCodemodHook = {
+  name?: string;
+  buildCommand: (ctx: {
+    packageDir: string;
+    files: string[];
+  }) =>
+    | PostCodemodCommand
+    | null
+    | undefined
+    | Promise<PostCodemodCommand | null | undefined>;
+};
+
+/** A component XLE layout expressions can reference by name via `{hint}`. */
+export interface XleComponent {
+  /** Import specifier the component is imported from, e.g. '@/components/KpiCard'. */
+  from: string;
+  /** Optional human description shown in tooling. */
+  description?: string;
+  /** Import as the module's default export instead of a named export. Defaults to false. */
+  default?: boolean;
+}
+
+/** User config exported from astryx.config.{ts,mjs,js}. */
+export interface AstryxConfig {
+  /** Integration package names to load. */
+  integrations?: string[];
+  /** Where to file issues/feedback for this project. */
+  issuesUrl?: string;
+  /** Lifecycle hooks. */
+  hooks?: {
+    postCodemod?: PostCodemodHook[];
+  };
+  /**
+   * EXPERIMENTAL — shape may change and is not part of the stable config
+   * contract. Provisional home for features still being proven out.
+   */
+  experimental?: {
+    /** Experimental XLE (layout expression) configuration. */
+    xle?: {
+      /**
+       * Register app-local components so XLE layout expressions can
+       * reference them by name via {hint}. Keyed by component name.
+       */
+      components?: Record<string, XleComponent>;
+    };
+  };
+}
+
+/**
+ * Type-preserving helper for the Astryx config file. Returns its argument
+ * unchanged; the value is the exported TypeScript surface so config files get
+ * editor/type feedback. Validation happens at the CLI load boundary.
+ */
+export function createConfig<T extends AstryxConfig>(config: T): T {
+  return config;
+}