@almadar/ui 5.74.0 → 5.76.0

package/dist/docs/index.d.cts

@@ -1,574 +0,0 @@
-import React from 'react';
-import { EventKey, EventPayload } from '@almadar/core';
-import { LucideIcon } from 'lucide-react';
-import * as react_jsx_runtime from 'react/jsx-runtime';
-
-/**
- * Box Component
- *
- * A versatile layout primitive that provides spacing, background, border, and shadow controls.
- * Think of it as a styled div with consistent design tokens.
- */
-
-type BoxPadding = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
-type BoxMargin = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "auto";
-type BoxBg = "transparent" | "primary" | "secondary" | "muted" | "accent" | "surface" | "overlay";
-type BoxRounded = "none" | "sm" | "md" | "lg" | "xl" | "2xl" | "full";
-type BoxShadow = "none" | "sm" | "md" | "lg" | "xl";
-interface BoxProps extends React.HTMLAttributes<HTMLDivElement> {
-    /** Additional CSS classes applied to the root element. */
-    className?: string;
-    /** Padding on all sides */
-    padding?: BoxPadding;
-    /** Horizontal padding (overrides padding for x-axis) */
-    paddingX?: BoxPadding;
-    /** Vertical padding (overrides padding for y-axis) */
-    paddingY?: BoxPadding;
-    /** Margin on all sides */
-    margin?: BoxMargin;
-    /** Horizontal margin */
-    marginX?: BoxMargin;
-    /** Vertical margin */
-    marginY?: BoxMargin;
-    /** Background color */
-    bg?: BoxBg;
-    /** Show border */
-    border?: boolean;
-    /** Border radius */
-    rounded?: BoxRounded;
-    /** Box shadow */
-    shadow?: BoxShadow;
-    /** Display type */
-    display?: "block" | "inline" | "inline-block" | "flex" | "inline-flex" | "grid";
-    /** Fill available width */
-    fullWidth?: boolean;
-    /** Fill available height */
-    fullHeight?: boolean;
-    /** Overflow behavior */
-    overflow?: "auto" | "hidden" | "visible" | "scroll";
-    /** Position */
-    position?: "relative" | "absolute" | "fixed" | "sticky";
-    /** HTML element to render as */
-    as?: React.ElementType;
-    /** Declarative event name — emits UI:{action} via eventBus on click */
-    action?: EventKey;
-    /** Payload to include with the action event */
-    actionPayload?: EventPayload;
-    /** Declarative hover event — emits UI:{hoverEvent} with { hovered: true/false } on mouseEnter/mouseLeave */
-    hoverEvent?: EventKey;
-    /** When true (default), a touch/pen tap also fires `hoverEvent` (toggling hovered) so hover-only reveals work on touch. */
-    tapReveal?: boolean;
-    /** Maximum width (CSS value, e.g., "550px", "80rem") */
-    maxWidth?: string;
-    /** Children elements */
-    children?: React.ReactNode;
-}
-/**
- * Box - Versatile container component with design tokens
- */
-declare const Box: React.ForwardRefExoticComponent<BoxProps & React.RefAttributes<HTMLDivElement>>;
-
-/**
- * Stack Component
- *
- * A layout primitive for arranging children in a vertical or horizontal stack with consistent spacing.
- * Includes convenience exports VStack and HStack for common use cases.
- */
-
-type StackDirection = "horizontal" | "vertical";
-type StackGap = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
-type StackAlign = "start" | "center" | "end" | "stretch" | "baseline";
-type StackJustify = "start" | "center" | "end" | "between" | "around" | "evenly";
-interface StackProps {
-    /** Stack direction */
-    direction?: StackDirection;
-    /** Gap between children */
-    gap?: StackGap;
-    /** Align items on the cross axis */
-    align?: StackAlign;
-    /** Justify items on the main axis */
-    justify?: StackJustify;
-    /** Allow items to wrap */
-    wrap?: boolean;
-    /** Reverse the order of children */
-    reverse?: boolean;
-    /** Fill available space (flex: 1) */
-    flex?: boolean;
-    /** Custom class name */
-    className?: string;
-    /** Inline styles */
-    style?: React.CSSProperties;
-    /** Children elements */
-    children?: React.ReactNode;
-    /** HTML element to render as */
-    as?: React.ElementType;
-    /** Click handler */
-    onClick?: (e: React.MouseEvent) => void;
-    /** Keyboard handler */
-    onKeyDown?: (e: React.KeyboardEvent) => void;
-    /** Role for accessibility */
-    role?: string;
-    /** Tab index for focus management */
-    tabIndex?: number;
-    /** Declarative event name — emits UI:{action} via eventBus on click */
-    action?: EventKey;
-    /** Payload to include with the action event */
-    actionPayload?: EventPayload;
-    /** When true, horizontal stacks flip to vertical below the md breakpoint (768px) */
-    responsive?: boolean;
-}
-/**
- * VStack - Vertical stack shorthand
- */
-interface VStackProps extends Omit<StackProps, "direction"> {
-}
-declare const VStack: React.FC<VStackProps>;
-/**
- * HStack - Horizontal stack shorthand
- */
-interface HStackProps extends Omit<StackProps, "direction"> {
-}
-declare const HStack: React.FC<HStackProps>;
-
-/**
- * Typography Atom Component
- *
- * Text elements following the KFlow design system with theme-aware styling.
- */
-
-type TypographyVariant = "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "heading" | "subheading" | "body1" | "body2" | "body" | "caption" | "overline" | "small" | "large" | "label";
-type TypographySize = "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";
-interface TypographyProps {
-    /** Typography variant */
-    variant?: TypographyVariant;
-    /** Heading level (1-6) - alternative to variant for headings */
-    level?: 1 | 2 | 3 | 4 | 5 | 6;
-    /** Text color */
-    color?: "primary" | "secondary" | "muted" | "error" | "success" | "warning" | "inherit";
-    /** Text alignment */
-    align?: "left" | "center" | "right";
-    /** Font weight override */
-    weight?: "light" | "normal" | "medium" | "semibold" | "bold";
-    /** Font size override */
-    size?: TypographySize;
-    /** Truncate with ellipsis (single line) */
-    truncate?: boolean;
-    /** Overflow handling mode */
-    overflow?: "visible" | "hidden" | "wrap" | "clamp-2" | "clamp-3";
-    /** Custom HTML element */
-    as?: keyof React.JSX.IntrinsicElements;
-    /** HTML id attribute */
-    id?: string;
-    /** Additional class names */
-    className?: string;
-    /** Inline style */
-    style?: React.CSSProperties;
-    /** Text content (alternative to children) */
-    content?: React.ReactNode;
-    /** Children elements */
-    children?: React.ReactNode;
-}
-declare const Typography: React.FC<TypographyProps>;
-
-/**
- * Cross-cutting atom-level prop shapes shared across the design system.
- */
-
-/**
- * Canonical semantic color palette.  Values are the Tailwind / CSS-var token
- * names that every component in the design system understands.  Prefer this
- * over a bare `string` for any `color` or `variant` prop.
- */
-type ColorToken = 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'muted';
-/**
- * Concrete error-state shape read by display components (`error.message`,
- * occasionally `error.stack`). Structurally assignable from the global `Error`,
- * so existing call sites passing an `Error` keep working — this just gives the
- * pattern extractor a readable field schema instead of the opaque `Error` global.
- */
-type UiError = {
-    message: string;
-    name?: string;
-    code?: string;
-    stack?: string;
-};
-
-/**
- * Icon Atom Component
- *
- * Renders an icon from the active icon family (Layer 1 Iconography axis —
- * see lib/iconFamily.ts). Canonical names are lucide kebab-case; the resolver
- * dispatches to phosphor / tabler / fa-solid when `--icon-family` selects them,
- * re-rendering automatically on theme switch.
- *
- * Supports two APIs:
- * - `icon` prop: Pass a LucideIcon component directly (bypasses family resolver
- *   — used for direct lucide component refs, stays in lucide regardless of theme)
- * - `name` prop: Pass a canonical kebab-case name (family-aware, swaps on theme)
- */
-
-type IconSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
-type IconAnimation = 'spin' | 'pulse' | 'none';
-
-/**
- * Canonical icon-input type: a Lucide component reference OR a canonical
- * kebab-case icon name string. The single source of truth for every
- * icon-bearing prop across `@almadar/ui` — pattern-sync's parser maps this
- * union to the `icon` config type, so the factory inspector renders an
- * IconPicker and a string name resolves via `resolveIcon`. Never declare an
- * icon prop as `React.ReactNode` (it collapses to a non-editable `node`).
- */
-type IconInput = LucideIcon | string;
-interface IconProps {
-    /**
-     * Lucide icon component (preferred for type-safe usage), OR a canonical
-     * kebab-case icon name string — a string is treated exactly like `name` so
-     * trait/factory authors can pass an icon by name through the `icon` prop.
-     */
-    icon?: IconInput;
-    /** Icon name as string (resolved from iconMap) */
-    name?: string;
-    /** Size of the icon */
-    size?: IconSize;
-    /** Semantic palette token or an arbitrary Tailwind color class. */
-    color?: ColorToken | string;
-    /** Animation type */
-    animation?: IconAnimation;
-    /** Additional CSS classes */
-    className?: string;
-    /** Icon stroke width - uses theme default if not specified */
-    strokeWidth?: number;
-    /** Inline style */
-    style?: React.CSSProperties;
-}
-declare const Icon: React.FC<IconProps>;
-
-type ButtonVariant = "primary" | "secondary" | "ghost" | "danger" | "success" | "warning" | "default";
-type ButtonSize = "sm" | "md" | "lg";
-interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
-    /** Additional CSS classes applied to the root element. */
-    className?: string;
-    variant?: ButtonVariant;
-    size?: ButtonSize;
-    isLoading?: boolean;
-    /** Left icon: a Lucide component or a canonical icon name string (e.g. "plus", "trash"). */
-    leftIcon?: IconInput;
-    /** Right icon: a Lucide component or a canonical icon name string. */
-    rightIcon?: IconInput;
-    /** Alias for leftIcon */
-    icon?: IconInput;
-    /** Alias for rightIcon */
-    iconRight?: IconInput;
-    /** Declarative event name — emits UI:{action} via eventBus on click */
-    action?: EventKey;
-    /** Payload to include with the action event */
-    actionPayload?: EventPayload;
-    /** Button label text (alternative to children for schema-driven rendering) */
-    label?: string;
-    /** Disable the button (greys out, blocks click events) */
-    disabled?: boolean;
-    /** Test identifier for automated tests */
-    'data-testid'?: string;
-}
-declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
-
-type CardShadow = "none" | "sm" | "md" | "lg";
-/**
- * Layer 2 visual treatment for the card pattern — orthogonal to the semantic
- * `variant` (which conveys role / state).
- */
-type CardLook = "elevated" | "flat-bordered" | "borderless-divider" | "ticket" | "invoice" | "chip" | "tile-image-first";
-interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
-    /** Additional CSS classes applied to the root element. */
-    className?: string;
-    variant?: "default" | "bordered" | "elevated" | "interactive";
-    padding?: "none" | "sm" | "md" | "lg";
-    /** Card title - renders in header if provided */
-    title?: string;
-    /** Card subtitle - renders below title */
-    subtitle?: string;
-    /** Shadow size override */
-    shadow?: CardShadow;
-    /** Layer 2 visual treatment — orthogonal to the semantic variant. */
-    look?: CardLook;
-    /** Card content */
-    children?: React.ReactNode;
-    /** Declarative event key emitted on click for trait dispatch */
-    action?: EventKey;
-    /** Shows a skeleton/spinner overlay while true. */
-    loading?: boolean;
-}
-declare const Card: React.ForwardRefExoticComponent<CardProps & React.RefAttributes<HTMLDivElement>>;
-
-/**
- * Divider Atom Component
- *
- * A divider component for separating content sections.
- */
-
-type DividerOrientation = "horizontal" | "vertical";
-type DividerVariant = "solid" | "dashed" | "dotted";
-interface DividerProps {
-    /**
-     * Orientation of the divider
-     * @default 'horizontal'
-     */
-    orientation?: DividerOrientation;
-    /**
-     * Text label to display in the divider
-     */
-    label?: string;
-    /**
-     * Line style variant
-     * @default 'solid'
-     */
-    variant?: DividerVariant;
-    /**
-     * Additional CSS classes
-     */
-    className?: string;
-}
-declare const Divider: React.FC<DividerProps>;
-
-interface SelectOption {
-    value: string;
-    label: string;
-}
-interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "onChange"> {
-    /** Additional CSS classes applied to the root element. */
-    className?: string;
-    /** Placeholder text */
-    placeholder?: string;
-    /** Current value */
-    value?: string | number;
-    /** Whether input is disabled */
-    disabled?: boolean;
-    /** Declarative event name for trait dispatch */
-    action?: EventKey;
-    /** Input type - supports 'select' and 'textarea' in addition to standard types */
-    inputType?: "text" | "email" | "password" | "number" | "tel" | "url" | "search" | "date" | "datetime-local" | "time" | "checkbox" | "select" | "textarea";
-    label?: string;
-    helperText?: string;
-    error?: string;
-    leftIcon?: IconInput;
-    rightIcon?: IconInput;
-    /** Lucide icon component or canonical kebab-case icon name string for left side */
-    icon?: IconInput;
-    /** Show clear button when input has value */
-    clearable?: boolean;
-    /** Callback or declarative event key when clear button is clicked */
-    onClear?: (() => void) | EventKey;
-    /** Options for select type */
-    options?: SelectOption[];
-    /** Rows for textarea type */
-    rows?: number;
-    /** onChange handler or declarative event key for trait dispatch */
-    onChange?: React.ChangeEventHandler<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement> | EventKey;
-}
-declare const Input: React.ForwardRefExoticComponent<InputProps & React.RefAttributes<HTMLSelectElement | HTMLInputElement | HTMLTextAreaElement>>;
-
-/**
- * DocSidebar — collapsible documentation navigation sidebar.
- * Renders a nested item tree with expand/collapse per category and active-item
- * highlighting. Not a generic nav; it owns doc-site-specific UX (uppercase
- * category headers, indented children, active highlight).
- */
-
-interface DocSidebarItem {
-    /** Display label */
-    label: string;
-    /** Navigation href */
-    href?: string;
-    /** Nested child items (makes this a collapsible category) */
-    items?: DocSidebarItem[];
-    /** Whether this item is currently active */
-    active?: boolean;
-}
-interface DocSidebarProps {
-    /** Sidebar navigation items */
-    items: DocSidebarItem[];
-    /** Additional CSS classes */
-    className?: string;
-}
-declare const DocSidebar: React.FC<DocSidebarProps>;
-
-/**
- * DocTOC Molecule Component
- *
- * A table of contents component with active section highlighting.
- * Composes from Box, VStack, and Typography atoms.
- */
-
-interface DocTOCItem {
-    /** Heading element id to link to */
-    id: string;
-    /** Display label */
-    label: string;
-    /** Heading level: 2 for h2, 3 for h3, etc. */
-    level: number;
-}
-interface DocTOCProps {
-    /** Table of contents items */
-    items: DocTOCItem[];
-    /** Currently active section id */
-    activeId?: string;
-    /** Additional CSS classes */
-    className?: string;
-}
-declare const DocTOC: React.FC<DocTOCProps>;
-
-/**
- * DocBreadcrumb Molecule Component
- *
- * A breadcrumb navigation component for documentation pages.
- * Composes from HStack, Typography, and Icon atoms.
- */
-
-interface DocBreadcrumbItem {
-    /** Display label */
-    label: string;
-    /** Navigation href (omit for the current/last item) */
-    href?: string;
-}
-interface DocBreadcrumbProps {
-    /** Breadcrumb path items, last item is treated as current page */
-    items: DocBreadcrumbItem[];
-    /** Additional CSS classes */
-    className?: string;
-}
-declare const DocBreadcrumb: React.FC<DocBreadcrumbProps>;
-
-/**
- * CodeBlock Molecule Component
- *
- * A syntax-highlighted code block with copy-to-clipboard functionality.
- * Preserves scroll position during re-renders.
- *
- * Event Contract:
- * - Emits: UI:COPY_CODE { language, success }
- */
-
-/**
- * The set of languages with a registered PrismLight grammar (above) plus the
- * `.orb`/`.lolo` grammars from `@almadar/syntax`. Authoritative: an unregistered
- * value renders as plain text, so this union mirrors the `registerLanguage`
- * calls exactly.
- */
-declare const CODE_LANGUAGES: readonly ["text", "json", "javascript", "js", "typescript", "ts", "jsx", "tsx", "css", "markdown", "md", "bash", "shell", "sh", "yaml", "yml", "rust", "python", "py", "sql", "diff", "toml", "go", "graphql", "html", "xml", "orb", "lolo"];
-type CodeLanguage = (typeof CODE_LANGUAGES)[number];
-type CodeViewerMode = 'code' | 'diff';
-interface DiffLine {
-    type: 'add' | 'remove' | 'context';
-    content: string;
-    lineNumber?: number;
-}
-interface CodeViewerAction {
-    label: string;
-    event?: string;
-    navigatesTo?: string;
-    variant?: 'primary' | 'secondary' | 'ghost';
-}
-interface CodeViewerFile {
-    label: string;
-    code: string;
-    language?: CodeLanguage;
-}
-interface CodeBlockProps {
-    /** The code content to display */
-    code?: string;
-    /** Programming language for syntax highlighting */
-    language?: CodeLanguage;
-    /** Show the copy button */
-    showCopyButton?: boolean;
-    /** Show the language badge */
-    showLanguageBadge?: boolean;
-    /** Maximum height before scrolling */
-    maxHeight?: string | number;
-    /** Enable brace-based code folding of multi-line `{}`/`[]` blocks (default: true). */
-    foldable?: boolean;
-    /** Additional CSS classes */
-    className?: string;
-    /**
-     * When true, render an editable surface that composes a transparent `Textarea`
-     * over a Prism-highlighted overlay. The overlay re-tokenizes on each keystroke
-     * (driven from a local mirror of the textarea value), so users see syntax-highlighted
-     * code while still being able to type. Folding is skipped in editable mode.
-     *
-     * History: GAP-51 first-cut shipped plain (no-highlighting) editable text;
-     * GAP-77 (2026-04-12) added the Prism overlay layer.
-     *
-     * Default: false (existing read-only behavior unchanged).
-     */
-    editable?: boolean;
-    /**
-     * GAP-51: called with the new code on every keystroke when `editable === true`.
-     * Consumers should debounce + parse downstream — `CodeBlock` does not.
-     */
-    onChange?: (code: string) => void;
-    /**
-     * GAP-80: line-level error/warning highlights for editable mode.
-     * Map of 1-based line number → severity. The overlay paints a colored
-     * background on each line: error = red, warning = yellow. Pass undefined
-     * (default) to disable. The consumer is responsible for computing the
-     * path → line map from the schema + validation results.
-     */
-    errorLines?: Map<number, 'error' | 'warning'>;
-    /** Title shown in the toolbar */
-    title?: string;
-    /** Diff or plain-code display mode */
-    mode?: CodeViewerMode;
-    /** Pre-computed diff lines */
-    diff?: readonly DiffLine[];
-    /** Old source text — generates diff when combined with newValue */
-    oldValue?: string;
-    /** New source text — generates diff when combined with oldValue */
-    newValue?: string;
-    /** Show line numbers in code / diff mode */
-    showLineNumbers?: boolean;
-    /** Enable word-wrap in code / diff mode */
-    wordWrap?: boolean;
-    /** Multiple files shown as tabs */
-    files?: readonly CodeViewerFile[];
-    /** Action badges in the toolbar */
-    actions?: readonly CodeViewerAction[];
-    /** Loading state */
-    isLoading?: boolean;
-    /** Error state */
-    error?: UiError | null;
-    /** Show copy button (viewer alias for showCopyButton) */
-    showCopy?: boolean;
-}
-declare const CodeBlock: React.NamedExoticComponent<CodeBlockProps>;
-
-interface DocPaginationLink {
-    label: string;
-    href: string;
-    category?: string;
-}
-interface DocPaginationProps {
-    /** Previous page link */
-    prev?: DocPaginationLink;
-    /** Next page link */
-    next?: DocPaginationLink;
-    /** Additional class names */
-    className?: string;
-}
-declare function DocPagination({ prev, next, className }: DocPaginationProps): react_jsx_runtime.JSX.Element | null;
-
-interface DocSearchResult {
-    title: string;
-    href: string;
-    excerpt?: string;
-    category?: string;
-}
-interface DocSearchProps {
-    /** Placeholder text for the input */
-    placeholder?: string;
-    /** Callback invoked with the search query, returns results */
-    onSearch?: (query: string) => DocSearchResult[] | Promise<DocSearchResult[]>;
-    /** Additional class names */
-    className?: string;
-}
-declare function DocSearch({ placeholder, onSearch, className, }: DocSearchProps): react_jsx_runtime.JSX.Element;
-
-export { Box, Button, Card, Divider, DocBreadcrumb, type DocBreadcrumbItem, type DocBreadcrumbProps, CodeBlock as DocCodeBlock, type CodeBlockProps as DocCodeBlockProps, DocPagination, type DocPaginationProps, DocSearch, type DocSearchProps, type DocSearchResult, DocSidebar, type DocSidebarItem, type DocSidebarProps, DocTOC, type DocTOCItem, type DocTOCProps, HStack, Icon, Input, Typography, VStack };

package/dist/docs/index.d.ts

@@ -1,29 +0,0 @@
-/**
- * @almadar/ui/docs
- *
- * SSR-safe subset of @almadar/ui for documentation sites.
- * Contains doc-specific molecules composed from @almadar/ui atoms.
- * Designed to eventually replace Docusaurus's built-in doc components.
- *
- * Atoms are re-exported from @almadar/ui/marketing for convenience.
- */
-export { Box } from '../components/core/atoms/Box';
-export { VStack, HStack } from '../components/core/atoms/Stack';
-export { Typography } from '../components/core/atoms/Typography';
-export { Button } from '../components/core/atoms/Button';
-export { Icon } from '../components/core/atoms/Icon';
-export { Card } from '../components/core/atoms/Card';
-export { Divider } from '../components/core/atoms/Divider';
-export { Input } from '../components/core/atoms/Input';
-export { DocSidebar } from '../components/core/molecules/DocSidebar';
-export type { DocSidebarProps, DocSidebarItem } from '../components/core/molecules/DocSidebar';
-export { DocTOC } from '../components/core/molecules/DocTOC';
-export type { DocTOCProps, DocTOCItem } from '../components/core/molecules/DocTOC';
-export { DocBreadcrumb } from '../components/core/molecules/DocBreadcrumb';
-export type { DocBreadcrumbProps, DocBreadcrumbItem } from '../components/core/molecules/DocBreadcrumb';
-export { CodeBlock as DocCodeBlock } from '../components/core/molecules/markdown/CodeBlock';
-export type { CodeBlockProps as DocCodeBlockProps } from '../components/core/molecules/markdown/CodeBlock';
-export { DocPagination } from '../components/core/molecules/DocPagination';
-export type { DocPaginationProps } from '../components/core/molecules/DocPagination';
-export { DocSearch } from '../components/core/molecules/DocSearch';
-export type { DocSearchProps, DocSearchResult } from '../components/core/molecules/DocSearch';