@pharos-ds/core 0.1.9

package/src/VisuallyHidden/VisuallyHidden.doc.mjs

@@ -0,0 +1,80 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'VisuallyHidden',
+  displayName: 'VisuallyHidden',
+  category: 'Utility',
+  keywords: ["visually hidden","sr-only","screen reader","accessibility","a11y","aria-live","hidden label","assistive technology"],
+  props: [
+    {
+      name: 'children',
+      type: 'ReactNode',
+      description: 'Content exposed to assistive technology while hidden from sight.',
+    },
+    {
+      name: 'as',
+      type: 'ElementType',
+      description: 'HTML tag to render as. Use a block element for live regions.',
+      default: "'span'",
+    },
+  ],
+  usage: {
+    description: 'Renders content in the accessibility tree while hiding it visually. Use for accessible names on icon-only controls, aria-live announcement regions, and supplementary screen-reader context. Deliberately has no styling props; the whole point is to stay invisible.',
+    bestPractices: [
+      { guidance: true, description: 'Use to give icon-only buttons and controls an accessible name that screen readers announce.' },
+      { guidance: true, description: 'Render as a block element (as="div") with aria-live to announce dynamic updates like drag-and-drop or result counts.' },
+      { guidance: false, description: 'Use it to hide content from everyone; it stays in the accessibility tree; use conditional rendering or `hidden` to remove content entirely.' },
+      { guidance: false, description: 'Put interactive controls inside it; the content is not visible and cannot receive pointer input.' },
+    ],
+  },
+};
+
+/** @type {import('../docs-types').ComponentDoc} */
+export const docsZh = {
+  name: 'VisuallyHidden',
+  displayName: 'VisuallyHidden',
+  props: [
+    {
+      name: 'children',
+      type: 'ReactNode',
+      description: '对辅助技术公开但对视觉隐藏的内容。',
+    },
+    {
+      name: 'as',
+      type: 'ElementType',
+      description: '要渲染的 HTML 标签。实时区域请使用块级元素。',
+      default: "'span'",
+    },
+  ],
+  usage: {
+    description: 'Renders content in the accessibility tree while hiding it visually. Use for accessible names on icon-only controls, aria-live announcement regions, and supplementary screen-reader context.',
+    bestPractices: [
+      { guidance: true, description: 'Use to give icon-only buttons and controls an accessible name that screen readers announce.' },
+      { guidance: true, description: 'Render as a block element (as="div") with aria-live to announce dynamic updates like drag-and-drop or result counts.' },
+      { guidance: false, description: 'Use it to hide content from everyone; it stays in the accessibility tree; use conditional rendering or `hidden` to remove content entirely.' },
+      { guidance: false, description: 'Put interactive controls inside it; the content is not visible and cannot receive pointer input.' },
+    ],
+  },
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+  description: 'renders content in the a11y tree while hiding it visually (sr-only)',
+  usage: {
+    description: 'Renders content in the accessibility tree while hiding it visually. Use for accessible names on icon-only controls, aria-live announcement regions, and supplementary screen-reader context.',
+    bestPractices: [
+      { guidance: true, description: 'Use to give icon-only buttons and controls an accessible name that screen readers announce.' },
+      { guidance: true, description: 'Render as a block element (as="div") with aria-live to announce dynamic updates like drag-and-drop or result counts.' },
+      { guidance: false, description: 'Use it to hide content from everyone; it stays in the accessibility tree; use conditional rendering or `hidden` to remove content entirely.' },
+      { guidance: false, description: 'Put interactive controls inside it; the content is not visible and cannot receive pointer input.' },
+    ],
+  },
+  propDescriptions: {
+    children: 'content exposed to AT while visually hidden',
+    as: 'HTML tag to render as; block element for live regions',
+  },
+};

package/src/VisuallyHidden/VisuallyHidden.test.tsx

@@ -0,0 +1,76 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file VisuallyHidden.test.tsx
+ * @input Uses vitest, @testing-library/react, VisuallyHidden component
+ * @output Unit tests for VisuallyHidden rendering + a11y behavior
+ * @position Testing; validates VisuallyHidden.tsx implementation
+ *
+ * SYNC: When VisuallyHidden.tsx changes, update tests to match new behavior
+ */
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {createRef} from 'react';
+import {VisuallyHidden} from './VisuallyHidden';
+
+describe('VisuallyHidden', () => {
+  it('renders its children in the accessibility tree', () => {
+    render(<VisuallyHidden>Delete incident</VisuallyHidden>);
+    // Present in the a11y tree (getByText finds it — it is not display:none).
+    expect(screen.getByText('Delete incident')).toBeInTheDocument();
+  });
+
+  it('renders a <span> by default', () => {
+    render(<VisuallyHidden>Label</VisuallyHidden>);
+    expect(screen.getByText('Label').tagName).toBe('SPAN');
+  });
+
+  it('renders a custom element via the `as` prop', () => {
+    render(
+      <VisuallyHidden as="div" aria-live="polite">
+        Moved task to Done
+      </VisuallyHidden>,
+    );
+    const el = screen.getByText('Moved task to Done');
+    expect(el.tagName).toBe('DIV');
+    expect(el).toHaveAttribute('aria-live', 'polite');
+  });
+
+  it('applies the clip styles that hide it visually', () => {
+    render(<VisuallyHidden>Hidden</VisuallyHidden>);
+    const el = screen.getByText('Hidden');
+    // jsdom does not apply the stylesheet, but the StyleX class is attached.
+    expect(el.getAttribute('class')).toBeTruthy();
+    // It must NOT be display:none / hidden — it stays in the a11y tree.
+    expect(el).not.toHaveAttribute('hidden');
+  });
+
+  it('forwards a ref to the rendered element', () => {
+    const ref = createRef<HTMLElement>();
+    render(<VisuallyHidden ref={ref}>Ref target</VisuallyHidden>);
+    expect(ref.current).toBeInstanceOf(HTMLElement);
+    expect(ref.current?.textContent).toBe('Ref target');
+  });
+
+  it('passes through arbitrary BaseProps (id, role, data-*)', () => {
+    render(
+      <VisuallyHidden id="announcer" role="status" data-testid="vh">
+        Status
+      </VisuallyHidden>,
+    );
+    const el = screen.getByTestId('vh');
+    expect(el).toHaveAttribute('id', 'announcer');
+    expect(el).toHaveAttribute('role', 'status');
+  });
+
+  it('gives an icon-only control an accessible name', () => {
+    render(
+      <button type="button">
+        <span aria-hidden="true">🗑️</span>
+        <VisuallyHidden>Delete</VisuallyHidden>
+      </button>,
+    );
+    expect(screen.getByRole('button', {name: 'Delete'})).toBeInTheDocument();
+  });
+});

package/src/VisuallyHidden/VisuallyHidden.tsx

@@ -0,0 +1,111 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file VisuallyHidden.tsx
+ * @input Uses React createElement/ElementType, stylex
+ * @output Exports VisuallyHidden component and VisuallyHiddenProps
+ * @position Accessibility primitive; renders content in the a11y tree while
+ *   hiding it visually (icon-only labels, aria-live regions, SR-only context)
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /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';
+import type {BaseProps} from '../BaseProps';
+import * as stylex from '@stylexjs/stylex';
+
+/**
+ * VisuallyHidden is deliberately styling-free: it exists to *not* be seen, so it
+ * intentionally omits `xstyle`/`className`/`style`. The clip block is fixed and
+ * non-overridable — styling a visually-hidden node is always a mistake. The
+ * accessibility pass-throughs from `BaseProps` (`aria-*`, `role`, `id`,
+ * `data-*`, event handlers) remain, since the live-region use case needs them.
+ */
+export interface VisuallyHiddenProps extends Omit<
+  BaseProps<HTMLElement>,
+  'className' | 'style'
+> {
+  /** Ref forwarded to the rendered element. */
+  ref?: React.Ref<HTMLElement>;
+
+  /** Content to expose to assistive technology while hidden from sight. */
+  children: ReactNode;
+
+  /**
+   * HTML tag to render as. Defaults to `'span'` (inline) for the common
+   * icon-label case; pass a block element such as `'div'` when wrapping block
+   * content or hosting an `aria-live` region. This is a structural choice, not
+   * a visual one.
+   *
+   * @default 'span'
+   */
+  as?: ElementType;
+}
+
+const styles = stylex.create({
+  // Canonical "visually hidden" clip block. Uses `clip: rect(...)` (not
+  // clip-path) for the widest assistive-tech/browser support. `inset` pins the
+  // 1px box to the top-left so a positioned ancestor cannot reveal it, and
+  // pointer/selection are disabled so the hidden node can't catch clicks or be
+  // text-selected.
+  visuallyHidden: {
+    position: 'absolute',
+    width: 1,
+    height: 1,
+    margin: -1,
+    padding: 0,
+    overflow: 'hidden',
+    clip: 'rect(0, 0, 0, 0)',
+    whiteSpace: 'nowrap',
+    borderStyle: 'none',
+    insetBlockStart: 0,
+    insetInlineStart: 0,
+    pointerEvents: 'none',
+    userSelect: 'none',
+  },
+});
+
+/**
+ * Renders its children in the accessibility tree while hiding them visually.
+ *
+ * Use for content that assistive technology must perceive but sighted users
+ * should not see: accessible names for icon-only controls, `aria-live`
+ * announcement regions, and supplementary screen-reader context.
+ *
+ * @example
+ * ```
+ * <IconButton icon="trash" label="">
+ *   <VisuallyHidden>Delete incident</VisuallyHidden>
+ * </IconButton>
+ * <VisuallyHidden as="div" aria-live="polite">
+ *   {`Moved ${task} to ${column}`}
+ * </VisuallyHidden>
+ * ```
+ */
+export function VisuallyHidden({
+  children,
+  as: element = 'span',
+  ref,
+  ...props
+}: VisuallyHiddenProps) {
+  return createElement(
+    element,
+    {
+      ref: ref as Ref<Element>,
+      // Spread consumer props (aria-*, role, id, data-*, handlers) first, then
+      // the fixed clip styles, so the visually-hidden class can never be
+      // displaced. There is no consumer className/style to merge — by design.
+      ...props,
+      ...stylex.props(styles.visuallyHidden),
+    },
+    children,
+  );
+}
+
+VisuallyHidden.displayName = 'VisuallyHidden';

package/src/VisuallyHidden/index.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file index.ts
+ * @input Imports from VisuallyHidden.tsx
+ * @output Exports VisuallyHidden component and props type
+ * @position Package entry point for VisuallyHidden
+ *
+ * SYNC: When modified, update /packages/core/src/VisuallyHidden/VisuallyHidden.doc.mjs
+ */
+
+export {VisuallyHidden} from './VisuallyHidden';
+export type {VisuallyHiddenProps} from './VisuallyHidden';

package/src/__tests__/TestIcon.tsx

@@ -0,0 +1,26 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TestIcon.tsx
+ * @input Standard SVG props
+ * @output A minimal SVG React component for tests
+ * @position Test fixture; a stand-in external SVG icon for Icon component-mode tests
+ *
+ * A trivial SVG component used by tests that need to pass a custom SVG icon to
+ * `Icon` (component mode) or component `*Icon` props. It forwards all standard
+ * SVG props and its ref so tests exercising prop/ref forwarding behave the same
+ * as a real third-party icon component.
+ */
+
+import React, {type SVGProps} from 'react';
+
+export function TestIcon({
+  ref,
+  ...props
+}: SVGProps<SVGSVGElement> & {ref?: React.Ref<SVGSVGElement>}) {
+  return (
+    <svg ref={ref} viewBox="0 0 24 24" {...props}>
+      <path d="M4 4h16v16H4z" />
+    </svg>
+  );
+}

package/src/__tests__/fastRoleQueries.ts

@@ -0,0 +1,66 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file fastRoleQueries.ts
+ * @input Uses @testing-library/react screen, dom-accessibility-api
+ * @output getButton/queryButton — role+name lookups that stay O(match) in jsdom
+ * @position Shared test helper; imported by component tests that render large
+ *   always-mounted button collections (Calendar month grids)
+ *
+ * RTL's getByRole('button', {name}) computes the accessible name of EVERY
+ * role candidate before filtering, and each computation consults jsdom's slow
+ * getComputedStyle (~5ms per node). The date components keep a month grid of
+ * ~35–85 role=button nodes mounted — visible in Calendar's case, inside the
+ * closed popover for the *Input components — so a single trigger lookup cost
+ * ~450ms and dominated those suites' runtime (DateRangeInput: 34s for 34
+ * tests before this helper existed).
+ *
+ * These helpers keep RTL's exact name algorithm (dom-accessibility-api is the
+ * library RTL uses internally) but:
+ *   - collect candidates with {hidden: true}, skipping the per-node
+ *     getComputedStyle visibility checks, and
+ *   - inject a constant "visible" style stub into the name computation —
+ *     names only consult display/visibility, and under {hidden: true}
+ *     semantics visibility must not exclude candidates anyway.
+ *
+ * Trade-off vs getByRole: first match wins — no tree-wide uniqueness check.
+ *
+ * SYNC: When modified, update this header.
+ */
+
+import {screen} from '@testing-library/react';
+import {computeAccessibleName} from 'dom-accessibility-api';
+
+// The name algorithm only reads getPropertyValue (for display/visibility/
+// content), so a Pick is all we need to type honestly — no object-literal
+// cast. The widening to CSSStyleDeclaration happens at the call site, where
+// getComputedStyle's signature demands the full type.
+const visibleStyleStub: Pick<CSSStyleDeclaration, 'getPropertyValue'> = {
+  getPropertyValue: prop =>
+    prop === 'display' ? 'block' : prop === 'visibility' ? 'visible' : '',
+};
+
+function matchesName(el: Element, name: string | RegExp): boolean {
+  const accessibleName = computeAccessibleName(el, {
+    getComputedStyle: () => visibleStyleStub as CSSStyleDeclaration,
+  });
+  return typeof name === 'string'
+    ? accessibleName === name
+    : name.test(accessibleName);
+}
+
+export function queryButton(name: string | RegExp): HTMLElement | null {
+  return (
+    screen
+      .queryAllByRole('button', {hidden: true})
+      .find(el => matchesName(el, name)) ?? null
+  );
+}
+
+export function getButton(name: string | RegExp): HTMLElement {
+  const el = queryButton(name);
+  if (!el) {
+    throw new Error(`Unable to find a role=button named ${String(name)}`);
+  }
+  return el;
+}

package/src/__tests__/inputWidthContract.test.tsx

@@ -0,0 +1,62 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+import {docs as CheckboxInputDocs} from '../CheckboxInput/CheckboxInput.doc.mjs';
+import {docs as CheckboxListDocs} from '../CheckboxList/CheckboxList.doc.mjs';
+import {docs as DateInputDocs} from '../DateInput/DateInput.doc.mjs';
+import {docs as DateRangeInputDocs} from '../DateRangeInput/DateRangeInput.doc.mjs';
+import {docs as DateTimeInputDocs} from '../DateTimeInput/DateTimeInput.doc.mjs';
+import {docs as FileInputDocs} from '../FileInput/FileInput.doc.mjs';
+import {docs as MultiSelectorDocs} from '../MultiSelector/MultiSelector.doc.mjs';
+import {docs as NumberInputDocs} from '../NumberInput/NumberInput.doc.mjs';
+import {docs as RadioListDocs} from '../RadioList/RadioList.doc.mjs';
+import {docs as SelectorDocs} from '../Selector/Selector.doc.mjs';
+import {docs as SliderDocs} from '../Slider/Slider.doc.mjs';
+import {docs as SwitchDocs} from '../Switch/Switch.doc.mjs';
+import {docs as TextAreaDocs} from '../TextArea/TextArea.doc.mjs';
+import {docs as TextInputDocs} from '../TextInput/TextInput.doc.mjs';
+import {docs as TimeInputDocs} from '../TimeInput/TimeInput.doc.mjs';
+import {docs as TokenizerDocs} from '../Tokenizer/Tokenizer.doc.mjs';
+import {docs as TypeaheadDocs} from '../Typeahead/Typeahead.doc.mjs';
+
+const inputDocsSuite = [
+  {name: 'CheckboxInput', docs: CheckboxInputDocs},
+  {name: 'CheckboxList', docs: CheckboxListDocs},
+  {name: 'DateInput', docs: DateInputDocs},
+  {name: 'DateRangeInput', docs: DateRangeInputDocs},
+  {name: 'DateTimeInput', docs: DateTimeInputDocs},
+  {name: 'FileInput', docs: FileInputDocs},
+  {name: 'MultiSelector', docs: MultiSelectorDocs},
+  {name: 'NumberInput', docs: NumberInputDocs},
+  {name: 'RadioList', docs: RadioListDocs},
+  {name: 'Selector', docs: SelectorDocs},
+  {name: 'Slider', docs: SliderDocs},
+  {name: 'Switch', docs: SwitchDocs},
+  {name: 'TextArea', docs: TextAreaDocs},
+  {name: 'TextInput', docs: TextInputDocs},
+  {name: 'TimeInput', docs: TimeInputDocs},
+  {name: 'Tokenizer', docs: TokenizerDocs},
+  {name: 'Typeahead', docs: TypeaheadDocs},
+];
+
+describe('Input Family width Prop Contract (#4163)', () => {
+  inputDocsSuite.forEach(({name, docs}) => {
+    it(`documents the width prop for ${name}`, () => {
+      const propsList = (docs.props || docs.components?.[0]?.props) as {
+        name: string;
+        type: string;
+      }[];
+      expect(
+        propsList,
+        `${name}.doc.mjs must expose a props array`,
+      ).toBeDefined();
+      const widthProp = propsList.find(p => p.name === 'width');
+      expect(
+        widthProp,
+        `${name}.doc.mjs must document the width prop`,
+      ).toBeDefined();
+      expect(widthProp?.type).toBe('SizeValue');
+    });
+  });
+});

package/src/authoring/doc.ts

@@ -0,0 +1,164 @@
+// 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 `@pharos-ds/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 PharosBaseDocInput {
+  /** 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 PharosPropInput {
+  name: string;
+  type: string;
+  description: string;
+  default?: string;
+  required?: boolean;
+  [key: string]: unknown;
+}
+
+/** A single documented param (mirrors `HookParamDoc`). */
+export interface PharosParamInput {
+  name: string;
+  type: string;
+  description: string;
+  default?: string;
+  required?: boolean;
+  [key: string]: unknown;
+}
+
+/** A single documented return field (mirrors `HookReturnDoc`). */
+export interface PharosReturnInput {
+  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 PharosComponentDocInput extends PharosBaseDocInput {
+  /** All public props for the component. */
+  props: PharosPropInput[];
+  /** 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 PharosFunctionDocInput extends PharosBaseDocInput {
+  /** Function/hook parameters or options-object fields. */
+  params: PharosParamInput[];
+  /** Return value documentation. One entry per field (or a single primitive). */
+  returns: PharosReturnInput[];
+}
+
+/**
+ * Input accepted by {@link createDoc}. A generic reference/topic doc — just the
+ * shared base. The `type` discriminant is injected by the factory.
+ */
+export type PharosGenericDocInput = PharosBaseDocInput;
+
+/**
+ * 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 PharosComponentDoc =
+  PharosComponentDocInput | PharosFunctionDocInput | PharosGenericDocInput;
+
+/**
+ * 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 PharosComponentDocInput>(
+  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 PharosFunctionDocInput>(
+  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 PharosGenericDocInput>(
+  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');
+  });
+});