@lifesg/react-design-system 4.0.0-alpha.5 → 4.0.0-alpha.7

package/tools/storybook-argtypes/config/arg-types-config.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Configuration constants for Storybook argTypes generation.
+ * Centralizes all configuration to improve testability and maintainability.
+ */
+/**
+ * Glob patterns for source files containing type definitions.
+ * Used to discover which component types.ts files to generate argTypes from.
+ */
+export declare const SOURCE_FILE_GLOBS: readonly ["src/*/types.ts", "src/filter/addons/types.ts", "src/form/form-*/types.ts", "src/popover/popover-inline/types.ts"];
+/**
+ * Root directories to watch for file changes (when in watch mode).
+ */
+export declare const WATCH_ROOTS: string[];
+/**
+ * Glob pattern for story files to scan for component references.
+ */
+export declare const STORY_FILE_GLOB = "stories/**/*.stories.@(ts|tsx)";
+/**
+ * Output file path for the generated registry mapping stories to argTypes imports.
+ */
+export declare const STORYBOOK_ARGTYPES_FILE: string;
+/**
+ * TypeScript type formatting flags for consistent text representation.
+ * NoTruncation: Show full type text without truncation
+ * UseSingleQuotesForStringLiteralType: Prefer 'string' over "string"
+ */
+export declare const TYPE_FORMAT_FLAGS: number;
+/**
+ * Header comment for all generated files.
+ */
+export declare const GENERATED_FILE_HEADER: "// This file is generated. Do not edit manually.\n// Run: npm run storybook:argtypes\n";

package/tools/storybook-argtypes/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Storybook ArgTypes Generation Tool - Public API
+ *
+ * Main entry point for the storybook-argtypes utility.
+ * Exports all public interfaces, classes, and utilities.
+ */
+export { ArgTypesGenerator } from "./arg-types-generator";
+export { GENERATED_FILE_HEADER, SOURCE_FILE_GLOBS, STORY_FILE_GLOB, STORYBOOK_ARGTYPES_FILE, TYPE_FORMAT_FLAGS, WATCH_ROOTS, } from "./config/arg-types-config";
+export type * as StorybookArgtypesTypes from "./types";
+export { FileSystemAdapter, type IFileSystemAdapter, } from "./adapters/file-system-adapter";
+export * from "./services";

package/tools/storybook-argtypes/services/arg-types-row-builder.d.ts

@@ -0,0 +1,43 @@
+/**
+ * ArgTypesRowBuilder - Build individual Storybook argType rows.
+ *
+ * Constructs complete argType entries with type information, descriptions,
+ * and control metadata from TypeScript properties and type declarations.
+ */
+import type { GeneratedArgType } from "../types";
+/**
+ * Builds Storybook argType rows.
+ * Creates complete argType entries with metadata.
+ *
+ * Usage:
+ * ```typescript
+ * const builder = new ArgTypesRowBuilder();
+ * const row = builder.buildArgTypeRow({
+ *   key: 'Button.color',
+ *   name: 'color',
+ *   category: 'Styling',
+ *   typeSummary: 'string | number'
+ * });
+ * ```
+ */
+export declare class ArgTypesRowBuilder {
+    /**
+     * Build a complete argType row.
+     * Combines property information with metadata to create a Storybook argType entry.
+     *
+     * @param opts Options object containing name, property, description, etc.
+     * @returns Generated argType row
+     */
+    buildArgTypeRow(opts: {
+        key: string;
+        name: string;
+        category: string;
+        tabGroup?: string;
+        typeSummary?: string;
+        typeSummaryParts?: string[];
+        defaultValue?: string;
+        deprecated?: string | boolean;
+        description?: string;
+        required?: boolean;
+    }): GeneratedArgType;
+}

package/tools/storybook-argtypes/services/file-path-resolver.d.ts

@@ -0,0 +1,118 @@
+/**
+ * FilePathResolver - Resolve file paths and import paths for components and types.
+ *
+ * Handles mapping story files to their corresponding type files
+ * and resolving import paths for components.
+ */
+import type { IFileSystemAdapter } from "../adapters/file-system-adapter";
+/**
+ * Resolves file paths for type definitions and story imports.
+ * Maps story files to component types and resolves import paths.
+ *
+ * Usage:
+ * ```typescript
+ * const resolver = new FilePathResolver();
+ * const typesFile = resolver.getTypesFileFromStoryDirectory('stories/button/button.stories.ts');
+ * ```
+ */
+export declare class FilePathResolver {
+    private readonly fileSystemAdapter;
+    /**
+     * Create a new FilePathResolver.
+     *
+     * @param fileSystemAdapter Adapter for filesystem operations (optional, uses default)
+     */
+    constructor(fileSystemAdapter?: IFileSystemAdapter);
+    /**
+     * Extract the story title from story file text.
+     *
+     * @param fileText Content of the story file
+     * @returns Story title or undefined if not found
+     */
+    getStoryTitle(fileText: string): string | undefined;
+    /**
+     * Extract the component reference from story file text.
+     * Matches `component: Form.CustomField` style declarations.
+     *
+     * @param fileText Content of the story file
+     * @returns Object with rootIdentifier and memberPath, or undefined if not found
+     */
+    getComponentReference(fileText: string): {
+        rootIdentifier: string;
+        memberPath: string[];
+    } | undefined;
+    /**
+     * Get the import path for a referenced identifier in story file text.
+     *
+     * @param fileText Story file content
+     * @param identifier Component identifier to find
+     * @returns Import path or undefined if not found
+     */
+    getImportPathForIdentifier(fileText: string, identifier: string): string | undefined;
+    toKebabCase(name: string): string;
+    private buildResolutionCandidates;
+    /**
+     * Resolve an import path to an absolute file path.
+     * Handles `src/`-prefixed paths and relative paths.
+     *
+     * @param storyFilePath Path to the story file (for relative resolution)
+     * @param importPath Import path to resolve
+     * @returns Absolute file path or undefined if not found
+     */
+    resolveImportPath(storyFilePath: string, importPath: string): string | undefined;
+    /**
+     * Get component directory from a component source path.
+     *
+     * @param componentSourcePath Path to component source file
+     * @returns Component directory path
+     */
+    getComponentDirectory(componentSourcePath: string): string;
+    /**
+     * Get the types.ts file for a component directory.
+     *
+     * @param componentDirectory Component directory path
+     * @returns Path to types.ts or undefined if not found
+     */
+    getTypesFileForComponentDirectory(componentDirectory: string): string | undefined;
+    /**
+     * Get the types file for a nested form component (e.g., Form.CustomField).
+     * Maps `form` directory + member path to `form-{leaf-member}/types.ts`.
+     *
+     * @param componentDirectory Component directory (must be the `form` directory)
+     * @param memberPath Member access path (e.g., ["CustomField"])
+     * @returns Path to the types file or undefined
+     */
+    getNestedFormTypesFile(componentDirectory: string, memberPath: string[]): string | undefined;
+    /**
+     * Get the types file inferred from a story file's location.
+     * Resolves `stories/{dir}/{story-name}.stories.ts` to `src/{dir}/types.ts`
+     * with subdirectory-aware fallback logic.
+     *
+     * @param storyFilePath Path to the story file
+     * @returns Path to the inferred types file or undefined
+     */
+    getTypesFileFromStoryDirectory(storyFilePath: string): string | undefined;
+    /**
+     * Get the output file path for a types source file.
+     * e.g. `src/button/types.ts` → `.storybook/generated/button.argtypes.generated.ts`
+     *
+     * @param sourceFilePath Absolute path to the types source file
+     * @returns Absolute path to the generated output file
+     */
+    getOutputFile(sourceFilePath: string): string;
+    /**
+     * Get the export name for the component's argTypes object.
+     * e.g. "form-custom-field" → "formCustomFieldExtraArgTypes"
+     *
+     * @param sourceFilePath Absolute path to the types source file
+     * @returns Export identifier name
+     */
+    getExportName(sourceFilePath: string): string;
+    /**
+     * Get the relative import path for a generated argTypes file.
+     *
+     * @param outputFile Absolute path to the generated output file
+     * @returns Relative import path (suitable for use in import statements)
+     */
+    getArgTypesImportPath(outputFile: string): string;
+}

package/tools/storybook-argtypes/services/index.d.ts

@@ -0,0 +1,6 @@
+export { ArgTypesRowBuilder } from "./arg-types-row-builder";
+export { FilePathResolver } from "./file-path-resolver";
+export { JsDocMetadataExtractor } from "./jsdoc-metadata-extractor";
+export { StoryRegistryGenerator } from "./story-registry-generator";
+export { TypeDependencyResolver } from "./type-dependency-resolver";
+export { TypeFormattingService } from "./type-formatting-service";

package/tools/storybook-argtypes/services/jsdoc-metadata-extractor.d.ts

@@ -0,0 +1,33 @@
+/**
+ * JsDocMetadataExtractor - Extract JSDoc and comment metadata from TypeScript nodes.
+ *
+ * Parses JSDoc tags and comments to extract documentation metadata
+ * like descriptions, examples, deprecation notices, and custom fields.
+ */
+import { type IndexSignatureDeclaration, type PropertySignature, type SourceFile } from "ts-morph";
+import type { JsDocMeta, StorybookTaggedDeclarationNode } from "../types";
+/** Nodes that can carry JSDoc in storybook generation. */
+type JsDocNode = IndexSignatureDeclaration | PropertySignature | StorybookTaggedDeclarationNode;
+/**
+ * Extracts JSDoc metadata from TypeScript declarations.
+ * Parses "@deprecated", "@default", "@remarks", "@example", and "@storybookSection" tags.
+ *
+ * Usage:
+ * ```typescript
+ * const extractor = new JsDocMetadataExtractor();
+ * const meta = extractor.getJsDocMeta(declaration);
+ * ```
+ */
+export declare class JsDocMetadataExtractor {
+    private readonly parser;
+    /**
+     * Check if a source file should be skipped from argTypes generation.
+     * Only top-of-file line comments are considered.
+     */
+    isSkippedSourceFile(sourceFile: SourceFile): boolean;
+    hasSkipTag(node: StorybookTaggedDeclarationNode): boolean;
+    getJsDocMeta(node: JsDocNode): JsDocMeta;
+    mergeJsDocMeta(metas: JsDocMeta[]): JsDocMeta;
+    toStorybookDescription(meta: JsDocMeta): string | undefined;
+}
+export {};

package/tools/storybook-argtypes/services/story-registry-generator.d.ts

@@ -0,0 +1,27 @@
+/**
+ * StoryRegistryGenerator - Generate story-title to argTypes registry content.
+ */
+import { type SourceFile } from "ts-morph";
+import type { IFileSystemAdapter } from "../adapters/file-system-adapter";
+import { FilePathResolver } from "./file-path-resolver";
+/**
+ * Generates registry file content from story source files.
+ */
+export declare class StoryRegistryGenerator {
+    private readonly filePathResolver;
+    /**
+     * Create a new StoryRegistryGenerator.
+     *
+     * @param filePathResolver File path resolver service (optional, uses default)
+     * @param fileSystemAdapter Filesystem adapter (optional, uses default)
+     */
+    constructor(filePathResolver?: FilePathResolver, fileSystemAdapter?: IFileSystemAdapter);
+    /**
+     * Generate complete registry file content.
+     * Returns the full content for the storybook-argtypes.generated.ts file.
+     *
+     * @returns Complete file content
+     */
+    generateRegistryFileContent(storyFiles: SourceFile[], shouldIncludeTypesFile: (typesFilePath: string) => boolean): string;
+    private renderRegistryFileContent;
+}

package/tools/storybook-argtypes/services/type-dependency-resolver.d.ts

@@ -0,0 +1,46 @@
+/**
+ * TypeDependencyResolver - Resolve and cache type dependencies across source files.
+ *
+ * Owns type-level dependency concerns: local type discovery, imported type source
+ * resolution, and safe property-symbol extraction from declarations.
+ */
+import { type InterfaceDeclaration, type PropertySignature, type SourceFile, type Symbol as TsMorphSymbol, type TypeAliasDeclaration } from "ts-morph";
+/**
+ * Resolves and caches type dependency operations used by argTypes generation.
+ */
+export declare class TypeDependencyResolver {
+    /** Cache of locally declared interface/type-alias names keyed by source file path. */
+    private readonly localTypeNamesCache;
+    /** Cache of wrapped imported type usage grouped by source file path and type name. */
+    private readonly wrappedTypeNamesCache;
+    /**
+     * Returns local interface/type-alias names for a file and memoizes the result.
+     */
+    getLocalTypeNames(sourceFile: SourceFile): Set<string>;
+    /**
+     * Returns the first property-signature declaration for a symbol, if present.
+     */
+    getPropertyDeclaration(symbol: TsMorphSymbol): PropertySignature | undefined;
+    /**
+     * Treats symbols from node_modules and custom-types as external declarations.
+     */
+    isExternalDeclaration(symbol: TsMorphSymbol): boolean;
+    /**
+     * Resolves declaration properties and filters out external symbols.
+     */
+    getResolvedProperties(declaration: InterfaceDeclaration | TypeAliasDeclaration): TsMorphSymbol[];
+    /**
+     * Resolves the source file backing an imported type name.
+     *
+     * Resolution order:
+     * 1. Follow alias symbol declarations for interface/type-alias declarations.
+     * 2. Fall back to module specifier source file when declaration lookup is not available.
+     */
+    resolveImportedTypeSourceFile(sourceFile: SourceFile, importedTypeName: string): SourceFile | undefined;
+    /**
+     * Gets cached wrapped type names or computes and stores them lazily.
+     */
+    getOrCreateWrappedTypeNames(sourceFile: SourceFile, factory: () => Map<string, Set<string | undefined>>): Map<string, Set<string | undefined>>;
+    /** Clear all in-memory caches. */
+    clear(): void;
+}

package/tools/storybook-argtypes/services/type-formatting-service.d.ts

@@ -0,0 +1,27 @@
+/**
+ * TypeFormattingService - Transform and format TypeScript type text for Storybook.
+ *
+ * Handles type text cleaning, union simplification, and formatting
+ * to make types more readable in Storybook's argTypes table.
+ */
+import { type IndexSignatureDeclaration, type Node, type PropertySignature, type Type } from "ts-morph";
+/**
+ * Formats TypeScript type text for Storybook argTypes.
+ * Provides type cleaning, union handling, and description generation.
+ *
+ * Usage:
+ * ```typescript
+ * const formatter = new TypeFormattingService();
+ * const cleaned = formatter.cleanType('string | undefined');
+ * ```
+ */
+export declare class TypeFormattingService {
+    cleanType(type: string): string;
+    formatUnionSummary(typeText: string): string;
+    isSimpleLiteralUnion(type: Type): boolean;
+    getExpandedLiteralUnionText(type: Type, contextNode: Node): string | undefined;
+    getSummaryTypeText(type: Type, contextNode: Node, fallbackText?: string): string;
+    getUnionMemberTexts(type: Type, contextNode: Node): string[] | undefined;
+    getPropertyTypeText(property: PropertySignature): string;
+    getIndexSignatureTypeText(indexSignature: IndexSignatureDeclaration): string;
+}

package/tools/storybook-argtypes/types.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Type definitions for Storybook argTypes generation system.
+ * Centralizes all interfaces and types for better discoverability and reusability.
+ */
+import type { IndexSignatureDeclaration, InterfaceDeclaration, PropertySignature, Symbol as TsMorphSymbol, TypeAliasDeclaration, VariableStatement } from "ts-morph";
+/**
+ * Parsed JSDoc metadata extracted from a TypeScript declaration.
+ * Supports these tags: "@deprecated", "@default", "@remarks", "@example", "@storybookSection"
+ */
+export interface JsDocMeta {
+    defaultValue?: string;
+    deprecated?: string | boolean;
+    description?: string;
+    examples?: string[];
+    remarks?: string;
+    tabGroups?: string[];
+}
+/**
+ * Metadata about a story file that determines which argTypes it uses.
+ */
+export interface StoryMetadata {
+    componentReference?: ComponentReference;
+    filePath: string;
+    title: string;
+    typesFilePath?: string;
+}
+/**
+ * Parsed component reference from story's component property.
+ * Examples:
+ * - component: Form.CustomField → { rootIdentifier: "Form", memberPath: ["CustomField"] }
+ * - component: Button → { rootIdentifier: "Button", memberPath: [] }
+ */
+export interface ComponentReference {
+    memberPath: string[];
+    rootIdentifier: string;
+}
+/**
+ * Single argType row for display in Storybook's props table.
+ * Maps to Storybook's internal ArgType structure.
+ */
+export interface GeneratedArgType {
+    key: string;
+    value: {
+        control: false;
+        deprecated?: string | boolean;
+        description?: string;
+        name: string;
+        type?: {
+            required?: boolean;
+        };
+        table: {
+            category: string;
+            defaultValue?: {
+                summary: string;
+            };
+            tabGroup?: string;
+            type: {
+                summary?: string;
+                summaryParts?: string[];
+            };
+        };
+    };
+}
+/**
+ * TypeScript declaration nodes that can have JSDoc comments.
+ * Union of declaration kinds that support documentation in Storybook.
+ */
+export type StorybookTaggedDeclarationNode = InterfaceDeclaration | TypeAliasDeclaration | VariableStatement;
+/**
+ * TypeScript symbol that can be resolved to a type.
+ * Alias for ts-morph's Symbol type for clearer intent.
+ */
+export type ResolvedSymbol = TsMorphSymbol;
+/**
+ * Supported JSDoc declaration node types for metadata extraction.
+ */
+export type JsDocSupportedNode = IndexSignatureDeclaration | InterfaceDeclaration | PropertySignature | VariableStatement | TypeAliasDeclaration;
+/**
+ * Options for configuring the ArgTypes generation.
+ */
+export interface ArgTypesGenerationConfig {
+    sourceFileGlobs: readonly string[];
+    storybookArgTypesFile: string;
+    storyFileGlob: string;
+    watchRoots: readonly string[];
+}
+/**
+ * Result of resolving a types file for a story.
+ * Includes both the file path and metadata about whether it was nested.
+ */
+export interface ResolvedTypesFile {
+    exportName: string;
+    filePath: string;
+    isNested: boolean;
+}
+/**
+ * File statistics result from FileSystemAdapter.
+ */
+export interface FileStat {
+    isDirectory(): boolean;
+    isFile(): boolean;
+}

package/typography/index.d.ts

@@ -1,4 +1,20 @@
+/**
+ * A collection of pre-styled text components covering headings, body copy, and
+ * hyperlinks.
+ *
+ * Use `Typography` sub-components to render consistently sized and weighted
+ * text.
+ *
+ * Sub-components:
+ * - Heading variants (`HeadingXXL` through `HeadingXS`) render semantic heading elements by default.
+ * - Body variants (`BodyBL`, `BodyMD`, `BodySM`, `BodyXS`) render `p` elements.
+ * - Link variants (`LinkBL`, `LinkMD`, `LinkSM`, `LinkXS`) render `a` elements .
+ *
+ * @remarks All text variants accept an `as` prop to
+ * override the rendered element for semantic flexibility.
+ */
 export declare const Typography: {
+    /** Renders the largest heading (`h1`). */
     HeadingXXL: (props: Omit<any, "ref"> & {
         weight?: import("./types").TypographyWeight | undefined;
         inline?: boolean | undefined;
@@ -6,6 +22,7 @@ export declare const Typography: {
         maxLines?: number | undefined;
         as?: import("react").ElementType<any> | undefined;
     } & import("react").RefAttributes<HTMLHeadingElement>) => React.ReactElement | null;
+    /** Renders an extra-large heading (`h2`). */
     HeadingXL: (props: Omit<any, "ref"> & {
         weight?: import("./types").TypographyWeight | undefined;
         inline?: boolean | undefined;
@@ -13,6 +30,7 @@ export declare const Typography: {
         maxLines?: number | undefined;
         as?: import("react").ElementType<any> | undefined;
     } & import("react").RefAttributes<HTMLHeadingElement>) => React.ReactElement | null;
+    /** Renders a large heading (`h3`). */
     HeadingLG: (props: Omit<any, "ref"> & {
         weight?: import("./types").TypographyWeight | undefined;
         inline?: boolean | undefined;
@@ -20,6 +38,7 @@ export declare const Typography: {
         maxLines?: number | undefined;
         as?: import("react").ElementType<any> | undefined;
     } & import("react").RefAttributes<HTMLHeadingElement>) => React.ReactElement | null;
+    /** Renders a medium heading (`h4`). */
     HeadingMD: (props: Omit<any, "ref"> & {
         weight?: import("./types").TypographyWeight | undefined;
         inline?: boolean | undefined;
@@ -27,6 +46,7 @@ export declare const Typography: {
         maxLines?: number | undefined;
         as?: import("react").ElementType<any> | undefined;
     } & import("react").RefAttributes<HTMLHeadingElement>) => React.ReactElement | null;
+    /** Renders a small heading (`h5`). */
     HeadingSM: (props: Omit<any, "ref"> & {
         weight?: import("./types").TypographyWeight | undefined;
         inline?: boolean | undefined;
@@ -34,6 +54,7 @@ export declare const Typography: {
         maxLines?: number | undefined;
         as?: import("react").ElementType<any> | undefined;
     } & import("react").RefAttributes<HTMLHeadingElement>) => React.ReactElement | null;
+    /** Renders the smallest heading (`h6`). */
     HeadingXS: (props: Omit<any, "ref"> & {
         weight?: import("./types").TypographyWeight | undefined;
         inline?: boolean | undefined;
@@ -41,6 +62,7 @@ export declare const Typography: {
         maxLines?: number | undefined;
         as?: import("react").ElementType<any> | undefined;
     } & import("react").RefAttributes<HTMLHeadingElement>) => React.ReactElement | null;
+    /** Renders baseline body text (`p`). */
     BodyBL: (props: Omit<any, "ref"> & {
         weight?: import("./types").TypographyWeight | undefined;
         inline?: boolean | undefined;
@@ -48,6 +70,7 @@ export declare const Typography: {
         maxLines?: number | undefined;
         as?: import("react").ElementType<any> | undefined;
     } & import("react").RefAttributes<HTMLParagraphElement>) => React.ReactElement | null;
+    /** Renders medium body text (`p`). */
     BodyMD: (props: Omit<any, "ref"> & {
         weight?: import("./types").TypographyWeight | undefined;
         inline?: boolean | undefined;
@@ -55,6 +78,7 @@ export declare const Typography: {
         maxLines?: number | undefined;
         as?: import("react").ElementType<any> | undefined;
     } & import("react").RefAttributes<HTMLParagraphElement>) => React.ReactElement | null;
+    /** Renders small body text (`p`). */
     BodySM: (props: Omit<any, "ref"> & {
         weight?: import("./types").TypographyWeight | undefined;
         inline?: boolean | undefined;
@@ -62,6 +86,7 @@ export declare const Typography: {
         maxLines?: number | undefined;
         as?: import("react").ElementType<any> | undefined;
     } & import("react").RefAttributes<HTMLParagraphElement>) => React.ReactElement | null;
+    /** Renders extra-small body text (`p`). */
     BodyXS: (props: Omit<any, "ref"> & {
         weight?: import("./types").TypographyWeight | undefined;
         inline?: boolean | undefined;
@@ -69,9 +94,13 @@ export declare const Typography: {
         maxLines?: number | undefined;
         as?: import("react").ElementType<any> | undefined;
     } & import("react").RefAttributes<HTMLParagraphElement>) => React.ReactElement | null;
+    /** Renders a baseline-size hyperlink (`a`). */
     LinkBL: (props: import("./types").TypographyLinkProps & import("react").RefAttributes<HTMLAnchorElement>) => React.ReactElement | null;
+    /** Renders a medium-size hyperlink (`a`). */
     LinkMD: (props: import("./types").TypographyLinkProps & import("react").RefAttributes<HTMLAnchorElement>) => React.ReactElement | null;
+    /** Renders a small-size hyperlink (`a`). */
     LinkSM: (props: import("./types").TypographyLinkProps & import("react").RefAttributes<HTMLAnchorElement>) => React.ReactElement | null;
+    /** Renders an extra-small hyperlink (`a`). */
     LinkXS: (props: import("./types").TypographyLinkProps & import("react").RefAttributes<HTMLAnchorElement>) => React.ReactElement | null;
 };
 export * from "./types";

package/typography/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../src/typography/index.ts"],"sourcesContent":["import {\n    BodyBL,\n    BodyMD,\n    BodySM,\n    BodyXS,\n    HeadingLG,\n    HeadingMD,\n    HeadingSM,\n    HeadingXL,\n    HeadingXS,\n    HeadingXXL,\n    LinkBL,\n    LinkMD,\n    LinkSM,\n    LinkXS,\n} from \"./typography\";\n\nexport const Typography = {\n    HeadingXXL,\n    HeadingXL,\n    HeadingLG,\n    HeadingMD,\n    HeadingSM,\n    HeadingXS,\n    BodyBL,\n    BodyMD,\n    BodySM,\n    BodyXS,\n    LinkBL,\n    LinkMD,\n    LinkSM,\n    LinkXS,\n};\n\nexport * from \"./types\";\n"],"names":["Typography","HeadingXXL","HeadingXL","HeadingLG","HeadingMD","HeadingSM","HeadingXS","BodyBL","BodyMD","BodySM","BodyXS","LinkBL","LinkMD","LinkSM","LinkXS"],"mappings":"wNAiBO,MAAMA,EAAa,CACtBC,aACAC,YACAC,YACAC,YACAC,YACAC,YACAC,SACAC,SACAC,SACAC,SACAC,SACAC,SACAC,SACAC"}
+{"version":3,"file":"index.js","sources":["../../src/typography/index.ts"],"sourcesContent":["import {\n    BodyBL,\n    BodyMD,\n    BodySM,\n    BodyXS,\n    HeadingLG,\n    HeadingMD,\n    HeadingSM,\n    HeadingXL,\n    HeadingXS,\n    HeadingXXL,\n    LinkBL,\n    LinkMD,\n    LinkSM,\n    LinkXS,\n} from \"./typography\";\n\n// @catalog\n/**\n * A collection of pre-styled text components covering headings, body copy, and\n * hyperlinks.\n *\n * Use `Typography` sub-components to render consistently sized and weighted\n * text.\n *\n * Sub-components:\n * - Heading variants (`HeadingXXL` through `HeadingXS`) render semantic heading elements by default.\n * - Body variants (`BodyBL`, `BodyMD`, `BodySM`, `BodyXS`) render `p` elements.\n * - Link variants (`LinkBL`, `LinkMD`, `LinkSM`, `LinkXS`) render `a` elements .\n *\n * @remarks All text variants accept an `as` prop to\n * override the rendered element for semantic flexibility.\n */\nexport const Typography = {\n    /** Renders the largest heading (`h1`). */\n    HeadingXXL,\n    /** Renders an extra-large heading (`h2`). */\n    HeadingXL,\n    /** Renders a large heading (`h3`). */\n    HeadingLG,\n    /** Renders a medium heading (`h4`). */\n    HeadingMD,\n    /** Renders a small heading (`h5`). */\n    HeadingSM,\n    /** Renders the smallest heading (`h6`). */\n    HeadingXS,\n    /** Renders baseline body text (`p`). */\n    BodyBL,\n    /** Renders medium body text (`p`). */\n    BodyMD,\n    /** Renders small body text (`p`). */\n    BodySM,\n    /** Renders extra-small body text (`p`). */\n    BodyXS,\n    /** Renders a baseline-size hyperlink (`a`). */\n    LinkBL,\n    /** Renders a medium-size hyperlink (`a`). */\n    LinkMD,\n    /** Renders a small-size hyperlink (`a`). */\n    LinkSM,\n    /** Renders an extra-small hyperlink (`a`). */\n    LinkXS,\n};\n\nexport * from \"./types\";\n"],"names":["Typography","HeadingXXL","HeadingXL","HeadingLG","HeadingMD","HeadingSM","HeadingXS","BodyBL","BodyMD","BodySM","BodyXS","LinkBL","LinkMD","LinkSM","LinkXS"],"mappings":"wNAiCO,MAAMA,EAAa,CAEtBC,aAEAC,YAEAC,YAEAC,YAEAC,YAEAC,YAEAC,SAEAC,SAEAC,SAEAC,SAEAC,SAEAC,SAEAC,SAEAC"}

package/typography/types.d.ts

@@ -1,24 +1,67 @@
 import type { FontSize } from "../theme";
+/** Font weight variant applied to a typography element. */
 export type TypographyWeight = "regular" | "semibold" | "bold" | "light";
+/**
+ * Text size token for a typography element.
+ */
 export type TypographySize = Exclude<FontSize, "form-label" | "form-description">;
+/**
+ * Props shared by all non-link typography variants.
+ *
+ * The generic `T` narrows the element type for the `as` prop and ensures
+ * forwarded HTML attributes match the rendered element.
+ */
 export type TypographyProps<T extends React.ElementType = React.ElementType> = React.ComponentPropsWithoutRef<T> & {
-    /** The font weight */
+    /**
+     * Font weight of the rendered text.
+     *
+     * @default "regular"
+     */
     weight?: TypographyWeight | undefined;
-    /** Specifies if text is displayed inline */
+    /**
+     * Renders the element as an inline `span`. When `true`, the `as` prop
+     * is ignored and `maxLines` clamping is disabled.
+     */
     inline?: boolean | undefined;
-    /** Specifies if text has a bottom margin */
+    /**
+     * Adds a bottom margin to separate the element from following content.
+     */
     paragraph?: boolean | undefined;
-    /** Specify the number of lines visible, the additional lines will be truncated */
+    /**
+     * Clamps visible text to the given number of lines, truncating the
+     * remainder.
+     *
+     * @remarks Has no effect when `inline` is `true`.
+     */
     maxLines?: number | undefined;
-    /** Overrides rendered element, e.g. `h2` for semantic hierarchy */
+    /**
+     * Overrides the rendered HTML element, e.g. `"h2"`.
+     *
+     * @remarks Has no effect when `inline` is `true`.
+     */
     as?: T | undefined;
 };
+/** Text-decoration style applied to a link typography element. */
 export type TypographyUnderlineStyle = "none" | "underline";
+/**
+ * Props for all link typography variants.
+ */
 export interface TypographyLinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
-    /** The font weight */
+    /**
+     * Font weight of the link text.
+     *
+     * @default "regular"
+     */
     weight?: TypographyWeight | undefined;
-    /** Displays indicator to signal that link leads to an external site */
+    /**
+     * Appends an external-link icon after the link text to signal that the
+     * destination is outside the current site.
+     */
     external?: boolean | undefined;
-    /** Toggle text decoration for hyperlinks, underline by default */
+    /**
+     * Text-decoration style for the link.
+     *
+     * @default "underline"
+     */
     underlineStyle?: TypographyUnderlineStyle | undefined;
 }

package/uneditable-section/index.d.ts

@@ -1,5 +1,20 @@
 export * from "./types";
+/**
+ * A read-only summary section for displaying labeled field values.
+ *
+ * Use `UneditableSection` to present a group of non-editable field–value pairs
+ * in a responsive grid layout
+ *
+ * Sub-components:
+ * - `UneditableSection.Item` — a standalone labeled read-only field with optional masking.
+ * - `UneditableSection.ItemSection` — a standalone grid list for composing items.
+ */
 export declare const UneditableSection: ((props: import("./types").UneditableSectionProps & import("react").RefAttributes<HTMLDivElement>) => React.ReactElement | null) & {
+    /**
+     * A standalone grid list for rendering `UneditableSection.Item` elements
+     * outside the full section wrapper.
+     */
     ItemSection: (props: import("./types").UneditableSectionItemSectionProps & import("react").RefAttributes<HTMLUListElement>) => React.ReactElement | null;
+    /** A standalone labeled read-only field with optional masking support. */
     Item: ({ label, value, displayWidth, maskState, maskLoadingState, maskChar, maskRange, unmaskRange, maskRegex, disableMaskUnmask, alert, maskTransformer, onMask, onUnmask, onTryAgain, fullWidth, }: import("./section-item").UneditableSectionItemComponentProps) => import("react/jsx-runtime").JSX.Element;
 };