@astryxdesign/core 0.1.5 → 0.1.6-canary.02f2602

package/src/Toast/Toast.tsx

@@ -22,6 +22,7 @@ import {useTheme} from '../theme';
 import {MediaTheme} from '../theme/MediaTheme';
 import type {ToastType, ToastDismissReason} from './types';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 const styles = stylex.create({
   root: {
@@ -115,6 +116,7 @@ export function Toast({
   isExiting = false,
   onDismiss,
 }: ToastProps) {
+  const t = useTranslator();
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const isPausedRef = useRef(false);
   const remainingRef = useRef(autoHideDuration);
@@ -226,7 +228,7 @@ export function Toast({
               variant="ghost"
               size="sm"
               icon={<Icon icon="close" size="sm" color="inherit" />}
-              label="Dismiss notification"
+              label={t('@astryx.toast.dismiss')}
               onClick={handleDismiss}
               isIconOnly
             />

package/src/Toast/ToastViewport.tsx

@@ -17,6 +17,7 @@ import {INTERACTIVE_SELECTORS} from '../hooks/useClickableContainer';
 import {Toast} from './Toast';
 import {ToastContext, type ToastContextValue} from './ToastContext';
 import type {ToastEntry, ToastPosition, ToastDismissReason} from './types';
+import {useTranslator} from '../i18n';
 
 const styles = stylex.create({
   viewport: {
@@ -107,6 +108,7 @@ export function ToastViewport({
   isTopLayer = true,
   children,
 }: ToastViewportProps) {
+  const t = useTranslator();
   const [toasts, setToasts] = useState<ToastEntry[]>([]);
   const [exitingIds, setExitingIds] = useState<Set<string>>(new Set());
   const toastsRef = useRef(toasts);
@@ -363,7 +365,7 @@ export function ToastViewport({
       <div
         ref={viewportRef}
         role="region"
-        aria-label="Notifications"
+        aria-label={t('@astryx.toast.viewport')}
         tabIndex={-1}
         // popover="manual" promotes to the top layer (above dialogs).
         // Omitted inside dialogs where the viewport is already in a top layer.

package/src/Token/Token.tsx

@@ -34,6 +34,7 @@ import {useLinkComponent} from '../Link/useLinkComponent';
 import {useInteractiveRole} from '../hooks/useInteractiveRole';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 // =============================================================================
 // Types
@@ -324,6 +325,7 @@ export function Token({
   'data-testid': testId,
   ref,
 }: TokenProps) {
+  const t = useTranslator();
   const LinkComponent = useLinkComponent();
   const role = useInteractiveRole({href, onClick, isDisabled});
 
@@ -342,7 +344,7 @@ export function Token({
       {onRemove != null && (
         <button
           type="button"
-          aria-label={`Remove ${label}`}
+          aria-label={t('@astryx.token.remove', {label})}
           onClick={e => {
             e.stopPropagation();
             onRemove(e);
@@ -432,7 +434,7 @@ export function Token({
         {onRemove != null && (
           <button
             type="button"
-            aria-label={`Remove ${label}`}
+            aria-label={t('@astryx.token.remove', {label})}
             onClick={e => {
               e.stopPropagation();
               onRemove(e);

package/src/Tokenizer/Tokenizer.doc.mjs

@@ -84,7 +84,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.',
     },
@@ -296,7 +296,7 @@ export const docsZh = {
     },
     {
       name: 'status',
-      type: 'InputStatus',
+      type: "{type: 'warning' | 'error' | 'success', message?: string}",
       description:
         '\u9a8c\u8bc1\u72b6\u6001\u5bf9\u8c61\uff0c\u5305\u542b\u7c7b\u578b\u548c\u6d88\u606f\uff0c\u7528\u4e8e\u9519\u8bef/\u8b66\u544a/\u6210\u529f\u72b6\u6001\u3002',
     },

package/src/Tokenizer/Tokenizer.tsx

@@ -52,6 +52,7 @@ import {
 import type {SearchableItem, SearchSource} from '../Typeahead/types';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 // Re-export status types for convenience
 export type {
@@ -81,9 +82,7 @@ export type TokenizerSize = 'sm' | 'md' | 'lg';
  * - `'unfocusedLayer'`: Shows a single line with "+ N more" when unfocused, expands as an overlay on focus.
  */
 export type TokenizerOverflowBehavior =
-  | 'none'
-  | 'unfocusedInline'
-  | 'unfocusedLayer';
+  'none' | 'unfocusedInline' | 'unfocusedLayer';
 
 /**
  * Imperative handle for Tokenizer handleRef.
@@ -403,6 +402,7 @@ export function Tokenizer<T extends SearchableItem>({
   ref,
   handleRef,
 }: TokenizerProps<T>) {
+  const t = useTranslator();
   const size = useSize(sizeProp, 'md');
   const inputId = useId();
   const descriptionId = useId();
@@ -786,7 +786,7 @@ export function Tokenizer<T extends SearchableItem>({
           {endContent}
           {hasClear && value.length > 0 && !isDisabled && (
             <InputClearButton
-              label="Clear all"
+              label={t('@astryx.tokenizer.clearAll')}
               onClick={e => {
                 e.stopPropagation();
                 handleClearAll();

package/src/Toolbar/Toolbar.doc.mjs

@@ -116,7 +116,7 @@ export const docs = {
         },
         {
           name: 'gap',
-          type: 'SpacingStep',
+          type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
           description: 'Gap between items within each slot.',
           default: '1',
         },

package/src/TopNav/TopNav.doc.mjs

@@ -109,6 +109,7 @@ export const docs = {
       name: 'label',
       type: 'string',
       description: 'Accessible label for the navigation landmark, applied as aria-label on the <nav> element.',
+      default: "'Top navigation'",
     },
     {
       name: 'xstyle',

package/src/TopNav/TopNav.test.tsx

@@ -13,6 +13,7 @@ import {describe, it, expect, vi} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {TopNav} from './TopNav';
+import {TopNavRenderContext} from './TopNavRenderContext';
 import {TopNavHeading} from './TopNavHeading';
 import {NavIcon} from '../NavIcon';
 import {TopNavItem} from './TopNavItem';
@@ -45,6 +46,35 @@ describe('TopNav', () => {
     );
   });
 
+  it('defaults the landmark label to "Top navigation" when label is omitted', () => {
+    render(<TopNav />);
+    expect(
+      screen.getByRole('navigation', {name: 'Top navigation'}),
+    ).toBeInTheDocument();
+  });
+
+  it('defaults the landmark label in mobile-bar mode', () => {
+    render(
+      <TopNavRenderContext value="mobile-bar">
+        <TopNav heading={<span>Logo</span>} />
+      </TopNavRenderContext>,
+    );
+    expect(
+      screen.getByRole('navigation', {name: 'Top navigation'}),
+    ).toBeInTheDocument();
+  });
+
+  it('custom label overrides the default in mobile-bar mode', () => {
+    render(
+      <TopNavRenderContext value="mobile-bar">
+        <TopNav label="Utility navigation" />
+      </TopNavRenderContext>,
+    );
+    expect(
+      screen.getByRole('navigation', {name: 'Utility navigation'}),
+    ).toBeInTheDocument();
+  });
+
   it('renders heading slot content', () => {
     render(<TopNav heading={<span data-testid="title-content">Logo</span>} />);
     expect(screen.getByTestId('title-content')).toBeInTheDocument();

package/src/TopNav/TopNav.tsx

@@ -21,6 +21,7 @@ import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars} from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
+import {useTranslator} from '../i18n';
 import {TopNavSlotContext} from './TopNavContext';
 import {useTopNavRenderMode} from './TopNavRenderContext';
 import {useTopNavMobileContent} from './TopNavMobileContentContext';
@@ -147,6 +148,7 @@ export interface TopNavProps extends BaseProps<HTMLElement> {
   /**
    * Accessible label for the navigation landmark.
    * Helps screen readers identify the navigation area.
+   * @default 'Top navigation'
    */
   label?: string;
 }
@@ -176,13 +178,15 @@ export function TopNav({
   children,
   centerContent,
   endContent,
-  label,
+  label: labelFromProps,
   xstyle,
   className,
   style,
   ref,
   ...props
 }: TopNavProps) {
+  const t = useTranslator();
+  const label = labelFromProps ?? t('@astryx.topNav.landmarkLabel');
   const renderMode = useTopNavRenderMode();
   const mobileContent = useTopNavMobileContent();
   const {hasAutoToggle} = useAppShellMobile();
@@ -294,9 +298,7 @@ export function TopNav({
       ) : (
         endContent && (
           <div {...stylex.props(styles.endContent)}>
-            <TopNavSlotContext value="end">
-              {endContent}
-            </TopNavSlotContext>
+            <TopNavSlotContext value="end">{endContent}</TopNavSlotContext>
           </div>
         )
       )}

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';
@@ -79,12 +80,9 @@ const styles = stylex.create({
  *
  * @example
  * ```
- * // Accessible name for an icon-only button
  * <IconButton icon="trash" label="">
  *   <VisuallyHidden>Delete incident</VisuallyHidden>
  * </IconButton>
- *
- * // Live region for announcements
  * <VisuallyHidden as="div" aria-live="polite">
  *   {`Moved ${task} to ${column}`}
  * </VisuallyHidden>

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');
+  });
+});